initial stab at extracting types from style macro

LFDanLu · LFDanLu · commit 28eb78849c0b · 2025-10-24T14:36:51.000-07:00
diff --git a/packages/@react-spectrum/s2/style/index.ts b/packages/@react-spectrum/s2/style/index.ts
@@ -15,7 +15,7 @@ import {Inset, fontRelative as internalFontRelative, size as internalSize, space
 import type {MacroContext} from '@parcel/macros';
 import {StyleString} from './types';
 
-export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style} from './spectrum-theme';
+export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style, themeConfig} from './spectrum-theme';
 export type {StyleString} from './types';
 
 // Wrap these functions in arbitrary value syntax when called from the outside.
@@ -81,7 +81,7 @@ const iconSizes = {
 
 export function iconStyle(this: MacroContext | void, options: IconStyle): StyleString<Exclude<keyof IconStyle, 'color' | 'size'>> {
   let {size = 'M', color, ...styles} = options;
-  
+
   if (color) {
     styles['--iconPrimary'] = {
       type: 'fill',
diff --git a/packages/@react-spectrum/s2/style/spectrum-theme.ts b/packages/@react-spectrum/s2/style/spectrum-theme.ts
@@ -535,7 +535,7 @@ const minFontSize = 10;
 const maxFontSize = 32;
 const lineHeightCalc = `round(1em * (${minFontScale} + (1 - ((min(${maxFontSize}, ${fontSizeCalc}) - ${minFontSize})) / ${maxFontSize - minFontSize}) * ${(maxFontScale - minFontScale).toFixed(2)}), 2px)`;
 
-export const style = createTheme({
+export const themeConfig = {
   properties: {
     // colors
     color: new SpectrumColorProperty('color', {
@@ -1044,4 +1044,6 @@ export const style = createTheme({
     xl: `@media (min-width: ${pxToRem(1280)})`,
     '2xl': `@media (min-width: ${pxToRem(1536)})`
   }
-});
+} as const;
+
+export const style = createTheme(themeConfig);
diff --git a/packages/dev/s2-docs/pages/s2/Reference.mdx b/packages/dev/s2-docs/pages/s2/Reference.mdx
@@ -0,0 +1,76 @@
+import {Layout} from '../../src/Layout';
+import {InlineAlert, Heading, Content, Link} from '@react-spectrum/s2';
+import {S2Colors} from '../../src/S2Colors';
+import {S2Typography} from '../../src/S2Typography';
+import {StyleMacroProperties} from '../../src/types';
+import {getPropertyDefinitions} from '../../src/styleProperties';
+export default Layout;
+
+export const section = 'Guides';
+export const tags = ['style', 'macro', 'spectrum', 'custom', 'values', 'reference'];
+export const description = 'Reference table for the `style` macro';
+
+# Style Macro Reference
+
+Reference table for the properties and values supported by React Spectrum `style` macro.
+
+## Colors
+
+All Spectrum 2 color tokens are available across color properties (e.g., `backgroundColor`, `color`, `borderColor`).
+
+<S2Colors />
+
+## Spacing
+
+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:
+
+- `edge-to-text` – default spacing between the edge of a control and its text. Relative to control height.
+- `pill` – default spacing between the edge of a pill-shaped control and its text. Relative to control height.
+- `text-to-control` – default spacing between text and a control (e.g., label and input). Scales with font size.
+- `text-to-visual` – default spacing between text and a visual element (e.g., icon). Scales with font size.
+
+## Sizing
+
+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.
+
+### top
+
+<StyleMacroProperties properties={getPropertyDefinitions(['top'])} />
+
+## Text
+
+// TODO: edit copy
+Spectrum 2 typography is applied via the `font` shorthand, which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
+
+```tsx
+<main>
+  <h1 className={style({font: 'heading-xl'})}>Heading</h1>
+  <p className={style({font: 'body'})}>Body</p>
+  <ul className={style({font: 'body-sm', fontWeight: 'bold'})}>
+    <li>List item</li>
+  </ul>
+</main>
+```
+
+Type scales include: UI, Body, Heading, Title, Detail, and Code. Each scale has a default and additional t-shirt sizes (e.g., `ui-sm`, `heading-2xl`, `code-xl`).
+
+<S2Typography />
+
+
+## Effects
+
+
+## Layout
+
+### display
+
+<StyleMacroProperties properties={getPropertyDefinitions(['display'])} />
+
+
+## Misc
+
+
+## Shorthands
+
+
+## Conditions
diff --git a/packages/dev/s2-docs/src/styleProperties.ts b/packages/dev/s2-docs/src/styleProperties.ts
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+interface StyleMacroPropertyDefinition {
+  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  values: string[],
+  additionalTypes?: string[]
+}
+
+// Properties that use PercentageProperty (accept LengthPercentage in addition to mapped values)
+const percentageProperties = new Set([
+  'top', 'left', 'bottom', 'right',
+  'insetStart', 'insetEnd',
+  'marginTop', 'marginBottom', 'marginStart', 'marginEnd',
+  'paddingTop', 'paddingBottom', 'paddingStart', 'paddingEnd',
+  'textIndent', 'translateX', 'translateY'
+]);
+
+// Properties that use SizingProperty (accept number and LengthPercentage in addition to mapped values)
+const sizingProperties = new Set([
+  'width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+  'flexBasis', 'containIntrinsicWidth', 'containIntrinsicHeight'
+]);
+
+// Manually defined property values from spectrum-theme.ts
+// These are extracted from the theme definition
+const propertyValues: {[key: string]: string[]} = {
+  display: ['block', 'inline-block', 'inline', 'flex', 'inline-flex', 'grid', 'inline-grid', 'contents', 'list-item', 'none'],
+  top: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', '-2', '-4', '-8', '-12', '-16', '-20', '-24', '-28', '-32', '-36', '-40', '-44', '-48', '-56', '-64', '-80', '-96', 'auto', 'full'],
+  position: ['absolute', 'fixed', 'relative', 'sticky', 'static'],
+  width: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  height: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  minWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  minHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen'],
+  maxWidth: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
+  maxHeight: ['auto', 'full', 'min', 'max', 'fit', 'screen', 'none'],
+  flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
+  justifyContent: ['normal', 'start', 'end', 'center', 'space-between', 'space-around', 'space-evenly', 'stretch'],
+  alignItems: ['start', 'end', 'center', 'baseline', 'stretch'],
+  gap: ['0', '2', '4', '8', '12', '16', '20', '24', '28', '32', '36', '40', '44', '48', '56', '64', '80', '96', 'text-to-control', 'text-to-visual', 'edge-to-text', 'pill']
+};
+
+export function getPropertyDefinition(propertyName: string): StyleMacroPropertyDefinition {
+  const values = propertyValues[propertyName] || [];
+
+  if (sizingProperties.has(propertyName)) {
+    return {
+      type: 'sizing',
+      values,
+      additionalTypes: ['number', 'LengthPercentage']
+    };
+  }
+
+  if (percentageProperties.has(propertyName)) {
+    return {
+      type: 'percentage',
+      values,
+      additionalTypes: ['LengthPercentage']
+    };
+  }
+
+  return {
+    type: 'mapped',
+    values
+  };
+}
+
+export function getPropertyDefinitions(propertyNames: string[]): {[key: string]: StyleMacroPropertyDefinition} {
+  const result: {[key: string]: StyleMacroPropertyDefinition} = {};
+  for (const name of propertyNames) {
+    result[name] = getPropertyDefinition(name);
+  }
+  return result;
+}
diff --git a/packages/dev/s2-docs/src/types.tsx b/packages/dev/s2-docs/src/types.tsx
@@ -47,7 +47,7 @@ export type TKeyof = {type: 'keyof', keyof: TType};
 export type TLink = {type: 'link', id: string};
 export type TReference =  {type: 'reference', local: string, imported: string, specifier: string};
 export type TMapped = {type: 'mapped', readonly: boolean | '+' | '-', typeParameter: TTypeParameter, typeAnnotation: TType};
-export type TType = 
+export type TType =
   | TKeyword
   | TIdentifier
   | TString
@@ -694,3 +694,71 @@ function TemplateLiteral({elements}: TTemplate) {
     </>
   );
 }
+
+interface StyleMacroPropertyDefinition {
+  type: 'mapped' | 'percentage' | 'sizing' | 'arbitrary',
+  values: string[],
+  additionalTypes?: string[]
+}
+
+interface StyleMacroPropertiesProps {
+  properties: {[propertyName: string]: StyleMacroPropertyDefinition}
+}
+
+export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
+  let propertyNames = Object.keys(properties);
+
+  return (
+    <Table>
+      <TableHeader>
+        <tr>
+          <TableColumn>Property</TableColumn>
+          <TableColumn>Values</TableColumn>
+        </tr>
+      </TableHeader>
+      <TableBody>
+        {propertyNames.map((propertyName, index) => {
+          let propDef = properties[propertyName];
+          let values = propDef.values;
+
+          return (
+            <TableRow key={index}>
+              <TableCell role="rowheader">
+                <code className={codeStyle}>
+                  <span className={codeStyles.attribute}>{propertyName}</span>
+                </code>
+              </TableCell>
+              <TableCell>
+                <code className={codeStyle}>
+                  {values.map((value, i) => (
+                    <React.Fragment key={i}>
+                      {i > 0 && <Punctuation>{' | '}</Punctuation>}
+                      <span className={codeStyles.string}>'{value}'</span>
+                    </React.Fragment>
+                  ))}
+                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => (
+                    <React.Fragment key={`type-${i}`}>
+                      <Punctuation>{' | '}</Punctuation>
+                      <TypePopover name={typeName}>
+                        {typeName === 'LengthPercentage' && (
+                          <p className={style({font: 'body'})}>
+                            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>
+                          </p>
+                        )}
+                        {typeName === 'number' && (
+                          <p className={style({font: 'body'})}>
+                            A numeric value in pixels. Will be converted to rem and scaled on touch devices.
+                          </p>
+                        )}
+                      </TypePopover>
+                    </React.Fragment>
+                  ))}
+                </code>
+              </TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}
