Skip to content

Commit e2b29c9

Browse files
LFDanLuLFDanLu
committed
add more type links
1 parent 36f1a6f commit e2b29c9

File tree

3 files changed

+161
-79
lines changed

3 files changed

+161
-79
lines changed

‎packages/dev/s2-docs/pages/s2/Reference.mdx‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,17 @@ export const description = 'Reference table for the `style` macro';
1212

1313
# Style Macro Reference
1414

15-
Reference table for the properties and values supported by React Spectrum `style` macro.
15+
Reference for the properties and values supported by React Spectrum `style` macro.
1616

1717
## Colors
1818

19-
TODO: do we just want the table or preserve the same formatting as the styling guide?
20-
2119
All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
2220

2321
<S2Colors />
2422

25-
Below are the rest of the `style` macro supported color properties.
26-
2723
<StyleMacroProperties properties={getPropertyDefinitions('color')} />
2824

29-
## Spacing
30-
31-
TODO: decide what to do with Spacing/Sizing since they are pretty much rolled up into Dimensions?
25+
## Dimensions
3226

3327
Spacing props like `margin` and `padding` accept values on a **4px grid**. These are specified in `px` and get converted to `rem`. In addition to numbers, these named options are available:
3428

@@ -37,8 +31,6 @@ Spacing props like `margin` and `padding` accept values on a **4px grid**. These
3731
- `text-to-control` – default spacing between text and a control (e.g., label and input). Scales with font size.
3832
- `text-to-visual` – default spacing between text and a visual element (e.g., icon). Scales with font size.
3933

40-
## Sizing
41-
4234
Size props like `width` and `height` accept arbitrary pixel values. Values are converted to `rem` and multiplied by 1.25x on touch devices to increase hit targets.
4335

4436
<StyleMacroProperties properties={getPropertyDefinitions('dimensions')} />
@@ -47,7 +39,7 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
4739

4840
// TODO: edit copy
4941

50-
Spectrum 2 typography is applied via the `font` shorthand, which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
42+
Spectrum 2 typography can be applied via the `font` [shorthand](#shorthand), which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
5143

5244
```tsx
5345
<main>
@@ -75,7 +67,6 @@ Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has
7567

7668
<StyleMacroProperties properties={getPropertyDefinitions('layout')} />
7769

78-
7970
## Misc
8071

8172
<StyleMacroProperties properties={getPropertyDefinitions('misc')} />

‎packages/dev/s2-docs/src/styleProperties.ts‎

Lines changed: 84 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,32 @@ const sizingProperties = new Set([
3030
'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
3131
]);
3232

33+
// Properties that accept baseSpacing values
34+
const baseSpacingProperties = new Set([
35+
'borderSpacing', 'rowGap', 'columnGap',
36+
'paddingStart', 'paddingEnd', 'paddingTop', 'paddingBottom',
37+
'scrollMarginStart', 'scrollMarginEnd', 'scrollMarginTop', 'scrollMarginBottom',
38+
'scrollPaddingStart', 'scrollPaddingEnd', 'scrollPaddingTop', 'scrollPaddingBottom',
39+
'textIndent', 'gridAutoRows', 'gridAutoColumns', 'gridTemplateColumns', 'gridTemplateRows',
40+
'marginStart', 'marginEnd', 'marginTop', 'marginBottom', 'translateX', 'translateY',
41+
'insetStart', 'insetEnd', 'top', 'left', 'bottom', 'right'
42+
]);
43+
44+
// Properties that accept negative spacing values
45+
const negativeSpacingProperties = new Set([
46+
'marginStart', 'marginEnd', 'marginTop', 'marginBottom',
47+
'translateX', 'translateY',
48+
'insetStart', 'insetEnd', 'top', 'left', 'bottom', 'right'
49+
]);
50+
3351
// Spacing values used across multiple properties
34-
// TODO: double check these values, and maybe add them as additional types so we get a type link instead since they are quite long
3552
const baseSpacingValues = ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96',];
3653
const negativeBaseSpacingValues = ['-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96'];
3754
const relativeSpacingValues = [ 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill'];
38-
const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
39-
const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
40-
const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
41-
const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
55+
// const spacingValues = [...baseSpacingValues, ...relativeSpacingValues];
56+
// const marginValues = [...spacingValues, ...negativeBaseSpacingValues, 'auto'];
57+
// const insetValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'auto', 'full'];
58+
// const translateValues = [...baseSpacingValues, ...negativeBaseSpacingValues, 'full'];
4259
const heightBaseValues = ['auto', 'full', 'min', 'max', 'fit', 'screen'];
4360
const fontSize = [
4461
'ui-xs', 'ui-sm', 'ui', 'ui-lg', 'ui-xl', 'ui-2xl', 'ui-3xl',
@@ -79,10 +96,10 @@ const colorPropertyValues: {[key: string]: string[]} = {
7996
};
8097

8198
const dimensionsPropertyValues: {[key: string]: string[]} = {
82-
borderSpacing: baseSpacingValues,
99+
borderSpacing: [],
83100
flexBasis: ['auto', 'full'],
84-
rowGap: spacingValues,
85-
columnGap: spacingValues,
101+
rowGap: relativeSpacingValues,
102+
columnGap: relativeSpacingValues,
86103
height: heightBaseValues,
87104
width: heightBaseValues,
88105
containIntrinsicWidth: heightBaseValues,
@@ -97,39 +114,44 @@ const dimensionsPropertyValues: {[key: string]: string[]} = {
97114
borderBottomWidth: ['0', '1', '2', '4'],
98115
borderStyle: ['solid', 'dashed', 'dotted', 'double', 'hidden', 'none'],
99116
strokeWidth: ['0', '1', '2'],
100-
marginStart: marginValues,
101-
marginEnd: marginValues,
102-
marginTop: marginValues,
103-
marginBottom: marginValues,
104-
paddingStart: spacingValues,
105-
paddingEnd: spacingValues,
106-
paddingTop: spacingValues,
107-
paddingBottom: spacingValues,
108-
scrollMarginStart: baseSpacingValues,
109-
scrollMarginEnd: baseSpacingValues,
110-
scrollMarginTop: baseSpacingValues,
111-
scrollMarginBottom: baseSpacingValues,
112-
scrollPaddingStart: baseSpacingValues,
113-
scrollPaddingEnd: baseSpacingValues,
114-
scrollPaddingTop: baseSpacingValues,
115-
scrollPaddingBottom: baseSpacingValues,
116-
textIndent: baseSpacingValues,
117-
translateX: translateValues,
118-
translateY: translateValues,
119-
// TODO would be good if these numbers/strings were types links instead
117+
marginStart: ['auto'],
118+
marginEnd: ['auto'],
119+
marginTop: ['auto'],
120+
marginBottom: ['auto'],
121+
paddingStart: relativeSpacingValues,
122+
paddingEnd: relativeSpacingValues,
123+
paddingTop: relativeSpacingValues,
124+
paddingBottom: relativeSpacingValues,
125+
scrollMarginStart: [],
126+
scrollMarginEnd: [],
127+
scrollMarginTop: [],
128+
scrollMarginBottom: [],
129+
scrollPaddingStart: [],
130+
scrollPaddingEnd: [],
131+
scrollPaddingTop: [],
132+
scrollPaddingBottom: [],
133+
textIndent: [],
134+
translateX: ['full'],
135+
translateY: ['full'],
136+
137+
138+
// TODO These ones should have a description for the supported values, make a type link for number however
120139
rotate: ['number', '${number}deg', '${number}rad', '${number}grad', '${number}turn'],
121140
scaleX: ['number', '${number}%'],
122141
scaleY: ['number', '${number}%'],
142+
143+
123144
transform: ['string'],
124145
position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
125-
insetStart: insetValues,
126-
insetEnd: insetValues,
127-
top: insetValues,
128-
left: insetValues,
129-
bottom: insetValues,
130-
right: insetValues,
146+
insetStart: ['auto', 'full'],
147+
insetEnd: ['auto', 'full'],
148+
top: ['auto', 'full'],
149+
left: ['auto', 'full'],
150+
bottom: ['auto', 'full'],
151+
right: ['auto', 'full'],
152+
131153
// TODO: also would like this number/number to be code formatted, not a string? Maybe make it a type link as well
132-
aspectRatio: ['auto', 'square', 'video', 'number/number (e.g. 4/3)']
154+
aspectRatio: ['auto', 'square', 'video', 'number / number']
133155
};
134156

135157
const textPropertyValues: {[key: string]: string[]} = {
@@ -144,7 +166,7 @@ const textPropertyValues: {[key: string]: string[]} = {
144166
verticalAlign: ['baseline', 'top', 'middle', 'bottom', 'text-top', 'text-bottom', 'sub', 'super'],
145167
textDecoration: ['none', 'underline', 'overline', 'line-through'],
146168
textOverflow: ['ellipsis', 'clip'],
147-
// TODO: how to get this as an actual type link like boolean
169+
// TODO: make common type link for number, link to mdn
148170
lineClamp: ['number'],
149171
hyphens: ['none', 'manual', 'auto'],
150172
whiteSpace: ['normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'break-spaces'],
@@ -154,7 +176,7 @@ const textPropertyValues: {[key: string]: string[]} = {
154176
boxDecorationBreak: ['slice', 'clone']
155177
};
156178

157-
// TODO: also missing values that are ArbitraryProperties/ExpandedProperties, etc
179+
158180
const effectsPropertyValues: {[key: string]: string[]} = {
159181
boxShadow: ['emphasized', 'elevated', 'dragged', 'none'],
160182
filter: ['emphasized', 'elevated', 'dragged', 'none'],
@@ -164,7 +186,7 @@ const effectsPropertyValues: {[key: string]: string[]} = {
164186
borderBottomEndRadius: ['none', 'sm', 'default', 'lg', 'xl', 'full', 'pill'],
165187
forcedColorAdjust: ['auto', 'none'],
166188
colorScheme: ['light', 'dark', 'light dark'],
167-
// TODO: ideally would be type links for string and LinearGradient
189+
// TODO: ideally would be type links for string and LinearGradient, will need to decide if we wanna export LinearGradient
168190
backgroundImage: ['string', 'LinearGradient'],
169191
backgroundPosition: ['bottom', 'center', 'left', 'left bottom', 'left top', 'right', 'right bottom', 'right top', 'top'],
170192
backgroundSize: ['auto', 'cover', 'contain'],
@@ -206,7 +228,6 @@ const effectsPropertyValues: {[key: string]: string[]} = {
206228
animationPlayState: ['paused', 'running']
207229
};
208230

209-
// TODO this is missing the values that are ArbitraryProperties, will need to add them
210231
const layoutPropertyValues: {[key: string]: string[]} = {
211232
display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
212233
alignContent: ['normal', 'center', 'start', 'end', 'space-between', 'space-around', 'space-evenly', 'baseline', 'stretch'],
@@ -231,10 +252,10 @@ const layoutPropertyValues: {[key: string]: string[]} = {
231252
gridAutoFlow: ['row', 'column', 'dense', 'row dense', 'column dense'],
232253

233254
// TODO: make these link to MDN and also have baseSpacingValue type link
234-
gridAutoRows:[...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
235-
gridAutoColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
236-
gridTemplateColumns: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
237-
gridTemplateRows: [...baseSpacingValues, 'auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
255+
gridAutoRows:['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
256+
gridAutoColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'string'],
257+
gridTemplateColumns: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string',],
258+
gridTemplateRows: ['auto', 'min-content', 'max-content', '${number}fr', 'minmax(${string}, ${string})', 'none', 'subgrid', 'string'],
238259
gridTemplateAreas: ['string[]'],
239260

240261

@@ -258,8 +279,6 @@ const layoutPropertyValues: {[key: string]: string[]} = {
258279
order: ['number'],
259280
};
260281

261-
// TODO: some of these aren't interactions really? Will need to classify them later
262-
// Add this to the docs, the table is called misc
263282
const miscPropertyValues: {[key: string]: string[]} = {
264283
pointerEvents: ['none', 'auto'],
265284
touchAction: ['auto', 'none', 'pan-x', 'pan-y', 'manipulation', 'pinch-zoom'],
@@ -380,21 +399,37 @@ const properties: {[key: string]: {[key: string]: string[]}} = {
380399
// TODO: see if there are any others that we will need to add additional shared types for
381400
// this is less additional types and more that we want to represent the below as a type link
382401
export function getAdditionalTypes(propertyName: string): string[] {
402+
let types: string[] = [];
403+
383404
if (baseColorProperties.has(propertyName)) {
384-
return ['baseColors'];
405+
types.push('baseColors');
406+
}
407+
408+
if (baseSpacingProperties.has(propertyName)) {
409+
types.push('baseSpacing');
410+
}
411+
412+
if (negativeSpacingProperties.has(propertyName)) {
413+
types.push('negativeSpacing');
385414
}
386415

387416
if (sizingProperties.has(propertyName)) {
388-
return ['number', 'LengthPercentage'];
417+
types.push('number', 'LengthPercentage');
389418
}
390419

391420
if (percentageProperties.has(propertyName)) {
392-
return ['LengthPercentage'];
421+
types.push('LengthPercentage');
393422
}
394423

395-
return [];
424+
return types;
396425
}
397426

427+
// Export spacing values for use in TypePopover
428+
export const spacingTypeValues = {
429+
baseSpacing: baseSpacingValues,
430+
negativeSpacing: negativeBaseSpacingValues
431+
};
432+
398433
interface StyleMacroPropertyDefinition {
399434
values: string[],
400435
additionalTypes?: string[]

‎packages/dev/s2-docs/src/types.tsx‎

Lines changed: 74 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {ColorLink, Link as SpectrumLink} from './Link';
1616
import {getDoc} from 'globals-docs';
1717
import Markdown from 'markdown-to-jsx';
1818
import React, {ReactNode} from 'react';
19+
import {spacingTypeValues} from './styleProperties';
1920
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
2021
import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from './Table';
2122
import {TypePopover} from './TypePopover';
@@ -695,6 +696,64 @@ function TemplateLiteral({elements}: TTemplate) {
695696
);
696697
}
697698

699+
const styleMacroTypeLinks = {
700+
'baseColors': {
701+
// TODO: will need to have this link work somehow
702+
description: 'A base set of colors defined by Spectrum. Contains a various global and semantic colors as well as high contrast color values for accessibility high contrast mode. See [above](#colors) for more info.'
703+
},
704+
'baseSpacing': {
705+
description: 'Base spacing values in pixels, following a 4px grid. Will be converted to rem.',
706+
body: (
707+
<code className={codeStyle}>
708+
{spacingTypeValues['baseSpacing'].map((val, idx) => (
709+
<React.Fragment key={idx}>
710+
{idx > 0 && <Punctuation>{' | '}</Punctuation>}
711+
<span className={codeStyles.string}>'{val}'</span>
712+
</React.Fragment>
713+
))}
714+
</code>
715+
)
716+
},
717+
'negativeSpacing': {
718+
description: 'Negative spacing values in pixels, following a 4px grid. Will be converted to rem.',
719+
body: (
720+
<code className={codeStyle}>
721+
{spacingTypeValues['negativeSpacing'].map((val, idx) => (
722+
<React.Fragment key={idx}>
723+
{idx > 0 && <Punctuation>{' | '}</Punctuation>}
724+
<span className={codeStyles.string}>'{val}'</span>
725+
</React.Fragment>
726+
))}
727+
</code>
728+
)
729+
},
730+
'LengthPercentage': {
731+
description: <>A CSS length value with percentage or viewport units. e.g. <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code></>
732+
},
733+
'number': {
734+
description: <>A numeric value in pixels e.g. <code className={codeStyle}>20</code>. Will be converted to rem and scaled on touch devices.</>
735+
}
736+
}
737+
738+
interface StyleMacroTypePopoverProps {
739+
typeName: string,
740+
description: ReactNode,
741+
body?: ReactNode
742+
}
743+
744+
function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopoverProps) {
745+
return (
746+
<TypePopover name={typeName}>
747+
<>
748+
<p className={style({font: 'body'})}>
749+
{description}
750+
</p>
751+
{body}
752+
</>
753+
</TypePopover>
754+
)
755+
}
756+
698757
interface StyleMacroPropertyDefinition {
699758
values: string[],
700759
additionalTypes?: string[]
@@ -738,24 +797,11 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
738797
))}
739798
{propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (
740799
<React.Fragment key={`type-${i}`}>
741-
<Punctuation>{' | '}</Punctuation>
742-
<TypePopover name={typeName}>
743-
{typeName === 'baseColors' && (
744-
<p className={style({font: 'body'})}>
745-
A base set of colors defined by Spectrum. See the global and semantic colors in the color reference above.
746-
</p>
747-
)}
748-
{typeName === 'LengthPercentage' && (
749-
<p className={style({font: 'body'})}>
750-
A CSS length value with percentage or viewport units. Examples: <code className={codeStyle}>'50%'</code>, <code className={codeStyle}>'100vw'</code>, <code className={codeStyle}>'50vh'</code>
751-
</p>
752-
)}
753-
{typeName === 'number' && (
754-
<p className={style({font: 'body'})}>
755-
A numeric value in pixels. Will be converted to rem and scaled on touch devices.
756-
</p>
757-
)}
758-
</TypePopover>
800+
{(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
801+
{styleMacroTypeLinks[typeName] ?
802+
<StyleMacroTypePopover typeName={typeName} description={styleMacroTypeLinks[typeName].description} body={styleMacroTypeLinks[typeName].body} /> :
803+
undefined
804+
}
759805
</React.Fragment>
760806
))}
761807
</code>
@@ -767,3 +813,13 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
767813
</Table>
768814
);
769815
}
816+
817+
818+
// TODO: for the below, will need to figure out how to get the same kind of mdx styling in the popover
819+
// TODO: for the baseColors, either link up or expose a type that displays the visual colors in the popover
820+
// for some reason trying to render the S2 colors example into the popover crashes the build?
821+
// same for spacing, perhaps do the type that contains the same explaination, and remove the text blob
822+
// TODO: add to the table a description col span 2 to describe what things like aspectRatio and such accept (aka This takes a). this exists in the Prop table so look there
823+
824+
// TODO: For the Shorthands, have a column for Name, value (what values it accepts), and mapping where mapping is what properties it maps to
825+
//

0 commit comments

Comments
 (0)