From 2e224ce83e86dd47bf0c9ffdd7ca60ee161bdd59 Mon Sep 17 00:00:00 2001
From: "Joshua J." <31038284+joshuajaco@users.noreply.github.com>
Date: Fri, 30 Jan 2026 02:00:06 +0100
Subject: [PATCH 1/2] fix(HiddenSelect): initial form value (#9466)

* fix(HiddenSelect): initial form value

* Add test to make sure we pass through Select correctly

* Apply suggestion from @snowystinger

---------

Co-authored-by: Robert Snow <rsnow@adobe.com>
Co-authored-by: Robert Snow <snowystinger@gmail.com>
---
 .../@react-aria/select/src/HiddenSelect.tsx   |  9 +++-
 .../select/test/HiddenSelect.test.tsx         | 17 ++++++++
 .../react-aria-components/test/Select.test.js | 41 ++++++++++++++++++-
 3 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/packages/@react-aria/select/src/HiddenSelect.tsx b/packages/@react-aria/select/src/HiddenSelect.tsx
index 61e9455b571..1029f53eb8e 100644
--- a/packages/@react-aria/select/src/HiddenSelect.tsx
+++ b/packages/@react-aria/select/src/HiddenSelect.tsx
@@ -145,6 +145,8 @@ export function HiddenSelect<T, M extends SelectionMode = 'single'>(props: Hidde
   let inputRef = useRef(null);
   let {containerProps, selectProps} = useHiddenSelect({...props, selectRef: state.collection.size <= 300 ? selectRef : inputRef}, state, triggerRef);
 
+  let values: (Key | null)[] = Array.isArray(state.value) ? state.value : [state.value];
+
   // If used in a <form>, use a hidden input so the value can be submitted to a server.
   // If the collection isn't too big, use a hidden <select> element for this so that browser
   // autofill will work. Otherwise, use an <input type="hidden">.
@@ -167,6 +169,10 @@ export function HiddenSelect<T, M extends SelectionMode = 'single'>(props: Hidde
                 );
               }
             })}
+            {/* The collection may be empty during the initial render. */}
+            {/* Rendering options for the current values ensures the select has a value immediately, */}
+            {/* making FormData reads consistent. */}
+            {state.collection.size === 0 && name && values.map((value, i) => <option key={i} value={value ?? ''} />)}
           </select>
         </label>
       </div>
@@ -176,11 +182,10 @@ export function HiddenSelect<T, M extends SelectionMode = 'single'>(props: Hidde
     let {validationBehavior} = data;
 
     // Always render at least one hidden input to ensure required form submission.
-    let values: (Key | null)[] = Array.isArray(state.value) ? state.value : [state.value];
     if (values.length === 0) {
       values = [null];
     }
-    
+
     let res = values.map((value, i) => {
       let inputProps: InputHTMLAttributes<HTMLInputElement> = {
         type: 'hidden',
diff --git a/packages/@react-aria/select/test/HiddenSelect.test.tsx b/packages/@react-aria/select/test/HiddenSelect.test.tsx
index eac596cace7..995adb081f3 100644
--- a/packages/@react-aria/select/test/HiddenSelect.test.tsx
+++ b/packages/@react-aria/select/test/HiddenSelect.test.tsx
@@ -53,6 +53,23 @@ describe('<HiddenSelect />', () => {
     );
   });
 
+  it('should have form value after initial render', async () => {
+    let formRef = React.createRef<HTMLFormElement>();
+    render(
+      <form ref={formRef}>
+        <HiddenSelectExample
+          value="value"
+          hiddenProps={{
+            name: 'select'
+          }}
+          items={[]} />
+      </form>
+    );
+
+    let formData = new FormData(formRef.current!);
+    expect(formData.get('select')).toEqual('value');
+  });
+
   it('should trigger on onSelectionChange when select onchange is triggered (autofill)', async () => {
     const onSelectionChange = jest.fn();
     render(
diff --git a/packages/react-aria-components/test/Select.test.js b/packages/react-aria-components/test/Select.test.js
index 23993cdf1d2..97d7cba1038 100644
--- a/packages/react-aria-components/test/Select.test.js
+++ b/packages/react-aria-components/test/Select.test.js
@@ -12,7 +12,7 @@
 
 import {act, pointerMap, render, within} from '@react-spectrum/test-utils-internal';
 import {Button, FieldError, Form, Label, ListBox, ListBoxItem, ListBoxLoadMoreItem, Popover, Select, SelectContext, SelectStateContext, SelectValue, Text} from '../';
-import React from 'react';
+import React, {useEffect, useRef, useState} from 'react';
 import {User} from '@react-aria/test-utils';
 import userEvent from '@testing-library/user-event';
 
@@ -726,4 +726,43 @@ describe('Select', () => {
     await selectTester.selectOption({option: 'Dog'});
     expect(trigger).toHaveTextContent('2 selected items');
   });
+
+  it('has a value immediately after rendering', async () => {
+    function Example() {
+      const ref = useRef(null);
+      const [formData, setFormData] = useState(() => new FormData());
+
+      useEffect(() => {
+        if (ref.current) {
+          setFormData(new FormData(ref.current));
+        }
+      }, []);
+
+      const selectValue = formData.get('select');
+
+      if (selectValue instanceof File) {
+        throw new Error('');
+      }
+
+      return (
+        <form ref={ref}>
+          <Select name="select" defaultValue="1" aria-label="Select">
+            <Button>
+              <SelectValue />
+              <span aria-hidden="true">▼</span>
+            </Button>
+            <Popover>
+              <ListBox>
+                <ListBoxItem id="1">value</ListBoxItem>
+              </ListBox>
+            </Popover>
+          </Select>
+          <div data-testid="select-value">select value: {selectValue}</div>
+        </form>
+      );
+    }
+    let {getByTestId} = render(<Example />);
+    let selectValue = getByTestId('select-value');
+    expect(selectValue).toHaveTextContent('select value: 1');
+  });
 });

From b4382b073f6de422cd22d206696ef1e21eed01f3 Mon Sep 17 00:00:00 2001
From: Reid Barber <reid@reidbarber.com>
Date: Thu, 29 Jan 2026 20:52:32 -0600
Subject: [PATCH 2/2] docs(S2): Improve markdown output for Style Macro
 reference page (#9535)

* handle style macro reference page in markdown docs

* remove links from value outputs

* fix lint

* add comments
---
 .../s2-docs/scripts/generateMarkdownDocs.mjs  | 515 ++++++++++++++++++
 1 file changed, 515 insertions(+)

diff --git a/packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs b/packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs
index 8abd1ec524e..73b2e7aee08 100644
--- a/packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs
+++ b/packages/dev/s2-docs/scripts/generateMarkdownDocs.mjs
@@ -66,6 +66,8 @@ const classTableCache = new Map();
 const propTableCache = new Map();
 const descriptionCache = new Map();
 let tsFileIndex = null;
+let styleMacroDataCache = null;
+const styleMacroTableCache = new Map();
 
 function getTsFileIndex() {
   if (tsFileIndex) {
@@ -132,6 +134,470 @@ function cleanTypeText(t) {
   return cleaned;
 }
 
+/**
+ * Recursively evaluates a Babel AST node to extract its runtime value.
+ * This function statically evaluates TS/JS expressions from the AST.
+ * 
+ * Example: Given the AST for `const colors = ['red', ...baseColors]`,
+ * this function would return ['red', 'green', 'blue'] if `baseColors` was 
+ * defined in scope as ['green', 'blue'].
+ * 
+ * @param {object} node - A Babel AST node (StringLiteral, ArrayExpression, etc.)
+ * @param {Map} scope - A Map of variable names to their evaluated values
+ * @returns {*} The evaluated value (string, number, array, object, Set, etc.) or undefined
+ */
+function evaluateStylePropertiesNode(node, scope) {
+  if (!node) {
+    return undefined;
+  }
+
+  switch (node.type) {
+    // Primitive literals - return their direct values
+    case 'StringLiteral':
+      return node.value;
+
+    case 'NumericLiteral':
+      return node.value;
+
+    case 'BooleanLiteral':
+      return node.value;
+
+    case 'NullLiteral':
+      return null;
+
+    // Variable references - look up the value in our scope Map
+    // Example: if scope has {baseColors: ['green', 'blue']}, evaluating `baseColors` returns ['green', 'blue']
+    case 'Identifier':
+      return scope.get(node.name);
+
+    // Unary expressions like -5 or +10
+    case 'UnaryExpression': {
+      const value = evaluateStylePropertiesNode(node.argument, scope);
+      if (typeof value === 'number') {
+        return node.operator === '-' ? -value : value;
+      }
+      return undefined;
+    }
+
+    // Array expressions like ['red', 'blue', ...otherColors]
+    // Handles both regular elements and spread elements
+    case 'ArrayExpression': {
+      const values = [];
+      for (const element of node.elements || []) {
+        if (!element) {
+          continue;
+        }
+        // Handle spread syntax: ...otherArray
+        if (element.type === 'SpreadElement') {
+          const spreadValue = evaluateStylePropertiesNode(element.argument, scope);
+          if (Array.isArray(spreadValue)) {
+            values.push(...spreadValue);
+          }
+          continue;
+        }
+        const value = evaluateStylePropertiesNode(element, scope);
+        if (value !== undefined) {
+          values.push(value);
+        }
+      }
+      return values;
+    }
+
+    // Object expressions like {margin: ['0', '4', '8'], ...otherProps}
+    // Handles both regular properties and spread properties
+    case 'ObjectExpression': {
+      const obj = {};
+      for (const prop of node.properties || []) {
+        if (!prop) {
+          continue;
+        }
+        // Handle spread syntax: ...otherObject
+        if (prop.type === 'SpreadElement') {
+          const spreadValue = evaluateStylePropertiesNode(prop.argument, scope);
+          if (spreadValue && typeof spreadValue === 'object') {
+            Object.assign(obj, spreadValue);
+          }
+          continue;
+        }
+        if (prop.type !== 'ObjectProperty') {
+          continue;
+        }
+        const key = prop.key.type === 'Identifier' ? prop.key.name : prop.key.value;
+        const value = evaluateStylePropertiesNode(prop.value, scope);
+        if (key !== undefined) {
+          obj[key] = value;
+        }
+      }
+      return obj;
+    }
+
+    // Template literals like `color-${name}`
+    // Preserves ${identifier} syntax for identifiers, evaluates other expressions
+    case 'TemplateLiteral': {
+      let output = '';
+      node.quasis.forEach((quasi, idx) => {
+        output += quasi.value.cooked || '';
+        const expr = node.expressions?.[idx];
+        if (expr) {
+          // Keep identifier placeholders as-is: ${varName}
+          if (expr.type === 'Identifier') {
+            output += `\${${expr.name}}`;
+          } else {
+            // Evaluate other expressions inline
+            const exprValue = evaluateStylePropertiesNode(expr, scope);
+            if (exprValue !== undefined) {
+              output += String(exprValue);
+            }
+          }
+        }
+      });
+      return output;
+    }
+
+    // Constructor calls like `new Set(['a', 'b', 'c'])`
+    // Currently only handles Set constructor
+    case 'NewExpression': {
+      const calleeName = node.callee?.type === 'Identifier' ? node.callee.name : '';
+      if (calleeName === 'Set') {
+        const argValue = evaluateStylePropertiesNode(node.arguments?.[0], scope);
+        return new Set(Array.isArray(argValue) ? argValue : []);
+      }
+      return undefined;
+    }
+
+    // TypeScript type assertions - unwrap and evaluate the inner expression
+    // Examples: `value as string`, `<string>value`, `value!`
+    case 'TSAsExpression':
+    case 'TSTypeAssertion':
+    case 'TSNonNullExpression':
+      return evaluateStylePropertiesNode(node.expression, scope);
+
+    // Parenthesized expressions - unwrap and evaluate
+    case 'ParenthesizedExpression':
+      return evaluateStylePropertiesNode(node.expression, scope);
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Loads and parses the style macro configuration from styleProperties.ts.
+ * This function reads the TypeScript source file, parses it into an AST using Babel,
+ * and evaluates all variable declarations to extract style property metadata.
+ * 
+ * The styleProperties.ts file contains definitions like:
+ *   const properties = {
+ *     spacing: { margin: ['0', '4', '8', '12'], padding: [...] },
+ *     layout: { display: ['flex', 'grid', 'block'] }
+ *   }
+ * 
+ * This function evaluates these declarations and returns a structured object with:
+ * - properties: categorized style properties and their allowed values
+ * - shorthandMapping: mappings from shorthand names to full property names
+ * - mdnTypeLinks/mdnPropertyLinks: documentation URLs
+ * - various Sets for property categorization (spacing, sizing, etc.)
+ * 
+ * @returns {object|null} Parsed style macro data or null if file doesn't exist/parse fails
+ */
+function loadStyleMacroData() {
+  if (styleMacroDataCache !== null) {
+    return styleMacroDataCache;
+  }
+
+  const stylePropertiesPath = path.join(REPO_ROOT, 'packages/dev/s2-docs/src/styleProperties.ts');
+  if (!fs.existsSync(stylePropertiesPath)) {
+    styleMacroDataCache = null;
+    return null;
+  }
+
+  try {
+    // Parse the TypeScript file into a Babel AST
+    const content = fs.readFileSync(stylePropertiesPath, 'utf8');
+    const ast = babel.parse(content, {
+      sourceType: 'module',
+      plugins: ['typescript']
+    });
+
+    // Build a scope Map to store evaluated variable values
+    // This allows later declarations to reference earlier ones
+    const scope = new Map();
+
+    // Helper to evaluate and register a variable declaration
+    // Example: const colors = ['red', 'blue'] => scope.set('colors', ['red', 'blue'])
+    const registerDeclaration = (decl) => {
+      if (!decl || decl.type !== 'VariableDeclarator') {
+        return;
+      }
+      const id = decl.id;
+      if (!id || id.type !== 'Identifier' || !decl.init) {
+        return;
+      }
+      const value = evaluateStylePropertiesNode(decl.init, scope);
+      scope.set(id.name, value);
+    };
+
+    // Walk through all top-level declarations and evaluate them
+    // Handles both: const x = ... and export const x = ...
+    for (const node of ast.program.body || []) {
+      if (node.type === 'VariableDeclaration') {
+        node.declarations.forEach(registerDeclaration);
+        continue;
+      }
+      if (node.type === 'ExportNamedDeclaration' && node.declaration?.type === 'VariableDeclaration') {
+        node.declaration.declarations.forEach(registerDeclaration);
+      }
+    }
+
+    // Extract the specific variables we need for style macro documentation
+    styleMacroDataCache = {
+      properties: scope.get('properties') || {},
+      shorthandMapping: scope.get('shorthandMapping') || {},
+      mdnTypeLinks: scope.get('mdnTypeLinks') || {},
+      mdnPropertyLinks: scope.get('mdnPropertyLinks') || {},
+      propertyDescriptions: scope.get('propertyDescriptions') || {},
+      baseSpacingProperties: scope.get('baseSpacingProperties'),
+      negativeSpacingProperties: scope.get('negativeSpacingProperties'),
+      sizingProperties: scope.get('sizingProperties'),
+      percentageProperties: scope.get('percentageProperties'),
+      spacingTypeValues: scope.get('spacingTypeValues') || {}
+    };
+  } catch {
+    styleMacroDataCache = null;
+  }
+
+  return styleMacroDataCache;
+}
+
+/**
+ * Extracts property definitions for a specific category from the loaded style macro data.
+ * 
+ * Example: For category 'spacing', this returns an object like:
+ * {
+ *   margin: {
+ *     values: ['0', '4', '8', '12', '16'],
+ *     additionalTypes: ['baseSpacing', 'number'],
+ *     links: { '0': {href: 'https://...'} },
+ *     description: 'Sets the margin on all sides'
+ *   },
+ *   marginX: {
+ *     values: [...],
+ *     additionalTypes: [...],
+ *     links: {...},
+ *     mapping: ['marginLeft', 'marginRight'],  // for shorthands
+ *     description: 'Sets horizontal margins'
+ *   }
+ * }
+ * 
+ * @param {string} category - The property category (e.g., 'spacing', 'layout', 'colors')
+ * @returns {object|null} Property definitions or null if category doesn't exist
+ */
+function getStyleMacroPropertyDefinitions(category) {
+  const data = loadStyleMacroData();
+  if (!data?.properties?.[category]) {
+    return null;
+  }
+
+  // Determine what additional type values a property accepts based on its classification
+  // Example: spacing properties accept baseSpacing values like 0, 4, 8, 12, 16, etc.
+  const getAdditionalTypes = (propertyName) => {
+    const types = [];
+    if (data.baseSpacingProperties?.has?.(propertyName)) {
+      types.push('baseSpacing');
+    }
+    if (data.negativeSpacingProperties?.has?.(propertyName)) {
+      types.push('negativeSpacing');
+    }
+    if (data.sizingProperties?.has?.(propertyName)) {
+      types.push('number', 'lengthPercentage');
+    }
+    if (data.percentageProperties?.has?.(propertyName)) {
+      types.push('lengthPercentage');
+    }
+    return Array.from(new Set(types));
+  };
+
+  const result = {};
+  
+  // Process regular properties (e.g., margin, padding, display)
+  for (const [name, rawValues] of Object.entries(data.properties[category])) {
+    let values = Array.isArray(rawValues) ? [...rawValues] : [];
+    const links = {};
+
+    // Add MDN documentation links for specific property values
+    if (data.mdnPropertyLinks?.[name]) {
+      for (const [key, href] of Object.entries(data.mdnPropertyLinks[name])) {
+        links[key] = {href};
+      }
+    }
+
+    // If no explicit values but we have links, use link keys as values
+    if (values.length === 0 && Object.keys(links).length > 0) {
+      values = Object.keys(links);
+    }
+
+    // Add MDN type documentation links for generic type values (e.g., 'length', 'color')
+    for (const value of values) {
+      if (links[value]) {
+        continue;  // Already has a link
+      }
+      // Skip 'number' for sizing properties and 'pill' for non-dimension categories
+      if ((value === 'number' && data.sizingProperties?.has?.(name)) || (value === 'pill' && category !== 'dimensions')) {
+        continue;
+      }
+      if (data.mdnTypeLinks?.[value]) {
+        links[value] = {href: data.mdnTypeLinks[value]};
+      }
+    }
+
+    result[name] = {
+      values,
+      additionalTypes: getAdditionalTypes(name),
+      links,
+      description: data.propertyDescriptions?.[name]
+    };
+  }
+
+  // Process shorthand properties (e.g., marginX, marginY)
+  // Shorthands map to multiple full properties: marginX -> [marginLeft, marginRight]
+  for (const [shorthandName, shorthandDef] of Object.entries(data.shorthandMapping || {})) {
+    if (shorthandDef.category !== category) {
+      continue;
+    }
+    let values = Array.isArray(shorthandDef.values) ? [...shorthandDef.values] : [];
+    const links = {};
+    
+    // Add MDN links for shorthand values
+    for (const value of values) {
+      if (value === 'pill' && shorthandName.includes('border')) {
+        continue;
+      }
+      if (data.mdnTypeLinks?.[value]) {
+        links[value] = {href: data.mdnTypeLinks[value]};
+      }
+    }
+
+    result[shorthandName] = {
+      values,
+      additionalTypes: getAdditionalTypes(shorthandDef.mapping?.[0]),
+      links,
+      mapping: shorthandDef.mapping,  // Which full properties this shorthand controls
+      description: data.propertyDescriptions?.[`${shorthandName}Shorthand`]
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Generates a markdown table documenting style macro properties and their allowed values.
+ * 
+ * Example output for category 'spacing':
+ * | Property | Values |
+ * |---------|--------|
+ * | margin | `0`, `4`, `8`, `12`, `baseSpacing (0, 4, 8, 12, 16, 20, 24, 28, 32)`, `number`, `lengthPercentage` |
+ * | marginX | `0`, `4`, `8`, `baseSpacing (...)`, `number` |
+ * | padding | `0`, `4`, `8`, `12`, `baseSpacing (...)` |
+ * 
+ * The table includes:
+ * - Explicit allowed values (e.g., '0', '4', '8')
+ * - Type categories with their full value sets (e.g., 'baseSpacing (0, 4, 8, ...)')
+ * - Generic types (e.g., 'number', 'lengthPercentage')
+ * 
+ * @param {string} category - Property category to generate table for (e.g., 'spacing', 'layout', 'colors')
+ * @param {object} options - Configuration options (e.g., {sort: true})
+ * @param {boolean} options.sort - Whether to sort properties alphabetically (default: true)
+ * @returns {string|null} Markdown table string or null if no properties found
+ */
+function generateStyleMacroTable(category, {sort = true} = {}) {
+  const cacheKey = `${category}:${sort ? 'sorted' : 'original'}`;
+  if (styleMacroTableCache.has(cacheKey)) {
+    return styleMacroTableCache.get(cacheKey);
+  }
+
+  const definitions = getStyleMacroPropertyDefinitions(category);
+  if (!definitions) {
+    styleMacroTableCache.set(cacheKey, null);
+    return null;
+  }
+
+  let propertyNames = Object.keys(definitions);
+  if (sort) {
+    propertyNames.sort((a, b) => a.localeCompare(b));
+  }
+
+  const data = loadStyleMacroData();
+  
+  // Build a row for each property, combining explicit values and type categories
+  const rows = propertyNames.map((propertyName) => {
+    const def = definitions[propertyName] || {};
+    const values = Array.isArray(def.values) ? def.values : [];
+    const additionalTypes = Array.isArray(def.additionalTypes) ? def.additionalTypes : [];
+    const tokens = [];
+    const seen = new Set();
+
+    const addToken = (token) => {
+      if (!token || seen.has(token)) {
+        return;
+      }
+      seen.add(token);
+      tokens.push(token);
+    };
+
+    const formatValue = (value) => `\`${String(value)}\``;
+
+    // Add explicit allowed values (e.g., '0', '4', '8', 'flex', 'grid')
+    values.forEach((value) => {
+      if (value === undefined || value === null) {
+        return;
+      }
+      addToken(formatValue(value));
+    });
+
+    // Add type categories with their full value sets
+    // Example: baseSpacing becomes `baseSpacing (0, 4, 8, 12, 16, 20, 24, 28, 32)`
+    additionalTypes.forEach((typeName) => {
+      if (!typeName) {
+        return;
+      }
+      if (typeName === 'baseSpacing' && Array.isArray(data?.spacingTypeValues?.baseSpacing)) {
+        const list = data.spacingTypeValues.baseSpacing.map(String).join(', ');
+        addToken(`\`${typeName} (${list})\``);
+        return;
+      }
+      if (typeName === 'negativeSpacing' && Array.isArray(data?.spacingTypeValues?.negativeSpacing)) {
+        const list = data.spacingTypeValues.negativeSpacing.map(String).join(', ');
+        addToken(`\`${typeName} (${list})\``);
+        return;
+      }
+      addToken(formatValue(typeName));
+    });
+
+    // Escape pipe characters for markdown table compatibility
+    const valueText = (tokens.length ? tokens.join(', ') : '—').replace(/\|/g, '\\|');
+    return {
+      name: propertyName,
+      values: valueText
+    };
+  });
+
+  if (!rows.length) {
+    styleMacroTableCache.set(cacheKey, null);
+    return null;
+  }
+
+  // Build the markdown table
+  const header = '| Property | Values |';
+  const separator = '|---------|--------|';
+  const body = rows
+    .map((row) => `| \`${row.name}\` | ${row.values || '—'} |`)
+    .join('\n');
+
+  const table = `${header}\n${separator}\n${body}`;
+  styleMacroTableCache.set(cacheKey, table);
+  return table;
+}
+
 /**
  * Get type text from a declaration, preferring the type node (AST) over the resolved type.
  */
@@ -1611,6 +2077,55 @@ function remarkDocsComponentsToMarkdown() {
         return index;
       }
 
+      // Render a table of style macro properties and values.
+      // This handles MDX components from style-macro.mdx like:
+      //   <StyleMacroProperties properties={getPropertyDefinitions('spacing')} />
+      //   <StyleMacroProperties properties={getPropertyDefinitions('layout')} sort={false} />
+      // And converts them to markdown tables documenting the available properties and values.
+      if (name === 'StyleMacroProperties') {
+        const propertiesAttr = node.attributes?.find(a => a.name === 'properties');
+        let category = null;
+
+        // Extract the category name from expressions like getPropertyDefinitions('spacing')
+        if (propertiesAttr && propertiesAttr.value?.type === 'mdxJsxAttributeValueExpression') {
+          const expr = propertiesAttr.value.value.trim();
+          const match = expr.match(/getPropertyDefinitions\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+          if (match) {
+            category = match[1];  // e.g., 'spacing', 'layout', 'colors'
+          }
+        }
+
+        // Check if sorting should be disabled (default is true)
+        let sort = true;
+        const sortAttr = node.attributes?.find(a => a.name === 'sort');
+        if (sortAttr) {
+          if (sortAttr.value?.type === 'mdxJsxAttributeValueExpression') {
+            const sortValue = sortAttr.value.value.trim();
+            if (sortValue === 'false') {
+              sort = false;
+            }
+          } else if (typeof sortAttr.value === 'string') {
+            sort = sortAttr.value !== 'false';
+          }
+        }
+
+        if (!category) {
+          parent.children.splice(index, 1);
+          return index;
+        }
+
+        // Generate and insert the markdown table
+        const table = generateStyleMacroTable(category, {sort});
+        if (table) {
+          const tableTree = unified().use(remarkParse).parse(table);
+          parent.children.splice(index, 1, ...tableTree.children);
+          return index + tableTree.children.length;
+        }
+
+        parent.children.splice(index, 1);
+        return index;
+      }
+
       // Render a table of S2 colors.
       if (name === 'S2Colors') {
         const colorSections = [