@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/ContextMenu/ContextMenuItem.doc.mjs

@@ -35,6 +35,12 @@ export const docs = {
       description: 'StyleX styles for layout customization.',
     },
   ],
+  playground: {
+    defaults: {
+      label: 'Edit',
+      description: 'Modify this item',
+    },
+  },
 };
 
 export const docsZh = {

package/src/DateTimeInput/DateTimeInput.test.tsx

@@ -214,6 +214,21 @@ describe('DateTimeInput', () => {
     expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-busy');
   });
 
+  it('sets aria-busy on the time input when isLoading is true', () => {
+    render(<DateTimeInput label="Meeting" isLoading onChange={() => {}} />);
+    expect(screen.getByLabelText('Meeting time')).toHaveAttribute(
+      'aria-busy',
+      'true',
+    );
+  });
+
+  it('does not set aria-busy on the time input when not loading', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    expect(screen.getByLabelText('Meeting time')).not.toHaveAttribute(
+      'aria-busy',
+    );
+  });
+
   it('renders status icon for error status', () => {
     render(
       <DateTimeInput
@@ -270,6 +285,61 @@ describe('DateTimeInput', () => {
     expect(found).toBe(true);
   });
 
+  it('links the description to the time input via aria-describedby', () => {
+    render(
+      <DateTimeInput
+        label="Meeting"
+        description="Pick the meeting datetime"
+        onChange={() => {}}
+      />,
+    );
+    // The description covers both halves of the field, so the time input must
+    // carry it too — a screen-reader user tabbing into the time half should
+    // not lose the field's description.
+    const timeInput = screen.getByLabelText('Meeting time');
+    const describedBy = timeInput.getAttribute('aria-describedby')!;
+    const ids = describedBy.split(' ');
+    const found = ids.some(id =>
+      document
+        .getElementById(id)
+        ?.textContent?.includes('Pick the meeting datetime'),
+    );
+    expect(found).toBe(true);
+  });
+
+  it('links the status message to the time input via aria-describedby', () => {
+    render(
+      <DateTimeInput
+        label="Meeting"
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid datetime'}}
+      />,
+    );
+    const timeInput = screen.getByLabelText('Meeting time');
+    const describedBy = timeInput.getAttribute('aria-describedby')!;
+    const ids = describedBy.split(' ');
+    const found = ids.some(id =>
+      document.getElementById(id)?.textContent?.includes('Invalid datetime'),
+    );
+    expect(found).toBe(true);
+  });
+
+  it('links the disabled reason to the time input via aria-describedby', () => {
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+    render(
+      <DateTimeInput
+        label="When"
+        onChange={() => {}}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+    const timeInput = screen.getByLabelText('When time');
+    const tooltip = screen.getByRole('tooltip', {hidden: true});
+    expect(timeInput.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+
   it('handles Escape keydown on date input without error', () => {
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);
     const input = screen.getByRole('combobox');

package/src/DateTimeInput/DateTimeInput.tsx

@@ -987,10 +987,12 @@ export function DateTimeInput({
             aria-disabled={showsDisabledMessage ? 'true' : undefined}
             readOnly={showsDisabledMessage || undefined}
             aria-label={timeLabel ?? `${label} time`}
+            aria-describedby={ariaDescribedBy}
             aria-required={isRequired === true ? 'true' : undefined}
             aria-invalid={
               status?.type === 'error' || !isTimeInputValid ? 'true' : undefined
             }
+            aria-busy={isBusy || undefined}
             {...stylex.props(
               styles.input,
               isEffectivelyDisabled && styles.inputDisabled,

package/src/Dialog/DialogHeader.doc.mjs

@@ -65,6 +65,51 @@ export const docs = {
       default: 'true',
     },
   ],
+  playground: {
+    defaults: {
+      title: 'Delete file?',
+      subtitle: 'This action cannot be undone.',
+      hasDivider: true,
+    },
+  },
+  examples: [
+    {
+      label: 'Basic',
+      code: `
+import {DialogHeader} from '@astryxdesign/core/Dialog';
+
+<DialogHeader title="Delete file?" subtitle="This action cannot be undone." />;
+`,
+    },
+    {
+      label: 'With close button',
+      code: `
+import {useState} from 'react';
+import {DialogHeader} from '@astryxdesign/core/Dialog';
+
+function Header() {
+  const [, setIsOpen] = useState(true);
+
+  // Passing onOpenChange renders a close button that calls it with false.
+  return <DialogHeader title="Settings" onOpenChange={setIsOpen} />;
+}
+`,
+    },
+    {
+      label: 'With start and end content',
+      code: `
+import {DialogHeader} from '@astryxdesign/core/Dialog';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Badge} from '@astryxdesign/core/Badge';
+
+<DialogHeader
+  title="Notifications"
+  startContent={<Icon icon="chevronLeft" size="sm" />}
+  endContent={<Badge label="3" />}
+/>;
+`,
+    },
+  ],
 };
 
 export const docsZh = {

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -11,7 +11,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-dropdown-menu'},
-      {className: 'astryx-dropdown-menu-item'},
+      {className: 'astryx-dropdown-menu-item', visualProps: ['size']},
     ],
     vars: [
       {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},

package/src/Field/FieldLabel.test.tsx

@@ -11,7 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
-import {StarIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {FieldLabel} from './FieldLabel';
 
 describe('FieldLabel', () => {
@@ -49,7 +49,7 @@ describe('FieldLabel', () => {
       <FieldLabel
         label="Starred"
         inputID="starred-input"
-        labelIcon={StarIcon}
+        labelIcon={TestIcon}
       />,
     );
     const svg = document.querySelector('svg');

package/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap

@@ -4,7 +4,6 @@ exports[`FormLayout > matches snapshot for horizontal direction 1`] = `
 <div
   class="astryx-form-layout horizontal FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"
   data-direction="horizontal"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40; @astryxdesign/core:src/FormLayout/FormLayout.tsx:45"
   data-testid="layout"
 >
   <input
@@ -20,7 +19,6 @@ exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `
 <div
   class="astryx-form-layout horizontal-labels FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
   data-direction="horizontal-labels"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40; @astryxdesign/core:src/FormLayout/FormLayout.tsx:50"
   data-testid="layout"
 >
   <label>
@@ -36,7 +34,6 @@ exports[`FormLayout > matches snapshot for vertical direction 1`] = `
 <div
   class="astryx-form-layout vertical FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
   data-direction="vertical"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40"
   data-testid="layout"
 >
   <input

package/src/Grid/Grid.test.tsx

@@ -65,7 +65,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(250px, 1fr))');
   });
 
-  it('renders with columns object max (capped via track-max)', () => {
+  it('renders with columns object max (count capped, tracks still fill)', () => {
     render(
       <Grid columns={{minWidth: 250, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -74,13 +74,37 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // Track max caps at (100% - 2 * gap) / 3 — no maxWidth on container
+    // Cap lives on the track MIN (min(100%, max(minWidth, perColumn))); the
+    // track MAX stays 1fr so present columns fill the row (a lone column on
+    // mobile stretches to 100% instead of leaving dead space).
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(250px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
+  it('keeps track max at 1fr with a max cap so a lone column can fill (#3391)', () => {
+    // Regression: previously the cap was applied to the track MAX
+    // (minmax(minWidth, 100%/max)), so when fewer than `max` columns fit —
+    // e.g. a single column on mobile — the lone column was pinned to ~100%/max
+    // and left dead space on the right. The cap now lives on the track MIN and
+    // the track MAX stays 1fr, so present columns always stretch to fill.
+    render(
+      <Grid columns={{minWidth: 360, max: 2}} gap={4} data-testid="grid">
+        <div>Left</div>
+        <div>Right</div>
+      </Grid>,
+    );
+    const grid = screen.getByTestId('grid');
+    const template = templateColumns(grid);
+    // Track max must be 1fr (fills), not a fraction-of-container cap.
+    expect(template).toMatch(/, 1fr\)\)$/);
+    expect(template).not.toMatch(/, calc\([^)]*\/ 2\)\)\)$/);
+    expect(template).toBe(
+      'repeat(auto-fill, minmax(min(100%, max(360px, calc((100% - 1 * var(--spacing-4)) / 2))), 1fr))',
+    );
+  });
+
   it('renders with columns object max using columnGap', () => {
     render(
       <Grid columns={{minWidth: 200, max: 4}} columnGap={6} data-testid="grid">
@@ -89,9 +113,9 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence for track-max calculation
+    // columnGap takes precedence in the perColumn floor calculation
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',
+      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 3 * var(--spacing-6)) / 4))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -165,7 +189,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('1fr');
   });
 
-  it('uses auto-fill without track-max cap when no max specified', () => {
+  it('uses auto-fill with a plain 1fr track when no max specified', () => {
     render(
       <Grid columns={{minWidth: 200}} data-testid="grid">
         <div>Item</div>
@@ -220,7 +244,7 @@ describe('Grid', () => {
 
   // --- P2: columns object + columnGap interaction (hardening #719) ---
 
-  it('uses columnGap var in track-max when both columnGap and gap are set', () => {
+  it('uses columnGap var in the count-cap floor when both columnGap and gap are set', () => {
     render(
       <Grid
         columns={{minWidth: 200, max: 3}}
@@ -231,14 +255,14 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence over gap in track-max
+    // columnGap takes precedence over gap in the perColumn floor
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 2 * var(--spacing-6)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses gap var in track-max when columnGap is not set', () => {
+  it('uses gap var in the count-cap floor when columnGap is not set', () => {
     render(
       <Grid columns={{minWidth: 150, max: 2}} gap={3} data-testid="grid">
         <div>Item</div>
@@ -246,12 +270,12 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',
+      'repeat(auto-fill, minmax(min(100%, max(150px, calc((100% - 1 * var(--spacing-3)) / 2))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses simple fraction in track-max when no gap is set', () => {
+  it('uses simple fraction in the count-cap floor when no gap is set', () => {
     render(
       <Grid columns={{minWidth: 100, max: 3}} data-testid="grid">
         <div>Item</div>
@@ -259,7 +283,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(100px, calc(100% / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(100px, calc(100% / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -332,7 +356,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
   });
 
-  it('renders with columns={{minWidth, max}} capping via track-max', () => {
+  it('renders with columns={{minWidth, max}} capping the count while filling', () => {
     render(
       <Grid columns={{minWidth: 280, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -340,14 +364,15 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // Track-max limits columns — grid stays full width
+    // Count is capped via the track MIN; track MAX stays 1fr so present
+    // columns fill the row (grid stays full width).
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + track-max', () => {
+  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + count cap', () => {
     render(
       <Grid
         columns={{minWidth: 280, max: 3, repeat: 'fit'}}
@@ -359,7 +384,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fit, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });

package/src/Grid/Grid.tsx

@@ -38,9 +38,10 @@ export type GridAlignment = 'start' | 'center' | 'end' | 'stretch';
  *   - `minWidth` — minimum width (px) for each column track
  *   - `repeat` — `'fill'` (default) preserves empty tracks for consistent widths;
  *     `'fit'` collapses empty tracks so items stretch to fill
- *   - `max` — caps the maximum number of columns by limiting track max size.
- *     The grid stretches to 100% of its parent; `max` only limits how many
- *     columns appear.
+ *   - `max` — caps the maximum number of columns. The grid stretches to 100%
+ *     of its parent and the columns that are present always fill the row, so a
+ *     layout collapsing to a single column on mobile stretches to full width
+ *     (no dead space on the right).
  */
 export type GridColumns =
   | number
@@ -321,9 +322,20 @@ const spacingVarNames: Record<SpacingStep, string> = {
 };
 
 /**
- * Build a grid-template-columns value that caps columns at `max` by
- * limiting each track's max size to `(100% - (max-1) * gap) / max`.
- * The grid stays 100% width; the track-max prevents more than `max` columns.
+ * Build a grid-template-columns value that caps the column *count* at `max`
+ * while still letting the columns that are actually present stretch to fill
+ * the row.
+ *
+ * The cap lives on the track's **min** size, not its max: each track is at
+ * least `perColumn = (100% - (max-1) * gap) / max`, so more than `max` columns
+ * can never fit. The track **max** stays `1fr`, so whenever fewer than `max`
+ * columns fit (most importantly a lone column on mobile) they still grow to
+ * fill the whole row — no dead space on the right.
+ *
+ * The track min is `max(minWidth, perColumn)` so an explicit `minWidth` is
+ * still honored, wrapped in `min(100%, …)` so a single column on a viewport
+ * narrower than `minWidth`/`perColumn` shrinks to the container instead of
+ * overflowing it.
  */
 function buildCappedTemplate(
   minWidth: number,
@@ -339,12 +351,17 @@ function buildCappedTemplate(
         ? spacingVarNames[gap]
         : null;
 
-  // trackMax = (100% - (maxCols - 1) * gap) / maxCols
-  const trackMax = gapVar
+  // perColumn = (100% - (maxCols - 1) * gap) / maxCols — the width a track
+  // would have if exactly `maxCols` columns were present. Used as a floor so
+  // the grid never fits more than `maxCols` columns.
+  const perColumn = gapVar
     ? `calc((100% - ${maxCols - 1} * var(${gapVar})) / ${maxCols})`
     : `calc(100% / ${maxCols})`;
 
-  return `repeat(${repeatMode}, minmax(${minWidth}px, ${trackMax}))`;
+  // Track min caps the count; track max stays 1fr so present columns fill.
+  const trackMin = `min(100%, max(${minWidth}px, ${perColumn}))`;
+
+  return `repeat(${repeatMode}, minmax(${trackMin}, 1fr))`;
 }
 
 /**

package/src/Icon/Icon.test.tsx

@@ -11,48 +11,48 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
-import {HomeIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {Icon} from './Icon';
 
 describe('Icon', () => {
   it('renders the icon component', () => {
-    render(<Icon icon={HomeIcon} data-testid="icon" />);
+    render(<Icon icon={TestIcon} data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
   it('renders as an SVG element', () => {
-    render(<Icon icon={HomeIcon} data-testid="icon" />);
+    render(<Icon icon={TestIcon} data-testid="icon" />);
     const icon = screen.getByTestId('icon');
     expect(icon.tagName.toLowerCase()).toBe('svg');
   });
 
   it('applies aria-hidden by default', () => {
-    render(<Icon icon={HomeIcon} data-testid="icon" />);
+    render(<Icon icon={TestIcon} data-testid="icon" />);
     expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
   });
 
   it('renders with different color variants', () => {
     const {rerender} = render(
-      <Icon icon={HomeIcon} color="primary" data-testid="icon" />,
+      <Icon icon={TestIcon} color="primary" data-testid="icon" />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="secondary" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="secondary" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="accent" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="accent" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="success" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="success" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="error" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="error" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="warning" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="warning" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} color="inherit" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} color="inherit" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
@@ -70,50 +70,41 @@ describe('Icon', () => {
       'purple',
     ] as const;
     const {rerender} = render(
-      <Icon
-        icon={HomeIcon}
-        color={nonSemanticColors[0]}
-        data-testid="icon"
-      />,
+      <Icon icon={TestIcon} color={nonSemanticColors[0]} data-testid="icon" />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
     for (const c of nonSemanticColors.slice(1)) {
-      rerender(<Icon icon={HomeIcon} color={c} data-testid="icon" />);
+      rerender(<Icon icon={TestIcon} color={c} data-testid="icon" />);
       expect(screen.getByTestId('icon')).toBeInTheDocument();
     }
   });
 
   it('renders with different size variants', () => {
     const {rerender} = render(
-      <Icon icon={HomeIcon} size="xsm" data-testid="icon" />,
+      <Icon icon={TestIcon} size="xsm" data-testid="icon" />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} size="sm" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} size="sm" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} size="md" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} size="md" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={HomeIcon} size="lg" data-testid="icon" />);
+    rerender(<Icon icon={TestIcon} size="lg" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
   it('forwards ref correctly', () => {
     const ref = vi.fn();
-    render(<Icon icon={HomeIcon} ref={ref} />);
+    render(<Icon icon={TestIcon} ref={ref} />);
     expect(ref).toHaveBeenCalledWith(expect.any(SVGSVGElement));
   });
 
   it('passes additional SVG props', () => {
     render(
-      <Icon
-        icon={HomeIcon}
-        data-testid="icon"
-        role="img"
-        aria-label="Home"
-      />,
+      <Icon icon={TestIcon} data-testid="icon" role="img" aria-label="Home" />,
     );
     const icon = screen.getByTestId('icon');
     expect(icon).toHaveAttribute('role', 'img');
@@ -121,8 +112,29 @@ describe('Icon', () => {
   });
 
   it('uses default color and size when not specified', () => {
-    render(<Icon icon={HomeIcon} data-testid="icon" />);
+    render(<Icon icon={TestIcon} data-testid="icon" />);
     // The component should render without errors with defaults
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
+
+  it('applies aria-hidden by default in string (registry) mode', () => {
+    render(<Icon icon="check" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('lets a string-mode icon be made meaningful by overriding aria-hidden', () => {
+    render(
+      <Icon
+        icon="check"
+        data-testid="icon"
+        role="img"
+        aria-label="Done"
+        aria-hidden={false}
+      />,
+    );
+    const icon = screen.getByTestId('icon');
+    expect(icon).toHaveAttribute('role', 'img');
+    expect(icon).toHaveAttribute('aria-label', 'Done');
+    expect(icon).toHaveAttribute('aria-hidden', 'false');
+  });
 });

package/src/Icon/Icon.tsx

@@ -281,12 +281,16 @@ function IconFromRegistry({
 
   return (
     <span
+      // Decorative by default, but placed BEFORE the prop spread so consumers
+      // can override it (e.g. `aria-hidden={false}` + `role="img"` +
+      // `aria-label`) to expose a meaningful standalone icon. This matches
+      // component-mode Icon, which already sets aria-hidden before its spread.
+      aria-hidden="true"
       {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
       {...mergeProps(
         themeProps('icon', {size, color}),
         stylex.props(styles.span, colorStyles[color], spanSizeStyles[size]),
-      )}
-      aria-hidden="true">
+      )}>
       {resolvedIcon}
     </span>
   );

package/src/InputGroup/InputGroup.tsx

@@ -201,11 +201,11 @@ export function InputGroup({
           labelTooltip={labelTooltip}>
           <div
             ref={ref}
+            data-testid={testId}
+            {...rest}
             role="group"
             aria-labelledby={labelID}
             aria-describedby={describedByIDs}
-            data-testid={testId}
-            {...rest}
             {...mergeProps(
               themeProps('input-group', {
                 size,

package/src/Item/Item.tsx

@@ -470,9 +470,9 @@ export function Item({
   return (
     <Component
       ref={ref as React.Ref<never>}
+      {...restProps}
       aria-selected={isSelected || undefined}
       aria-disabled={isDisabled || undefined}
-      {...restProps}
       {...mergeProps(
         themeProps('item', {density, align}),
         stylex.props(

package/src/Layout/LayoutContent.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       type: 'ReactNode',
       description: 'Content.',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -44,6 +50,11 @@ export const docsZh = {
       type: 'ReactNode',
       description: '内容。',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -70,6 +81,7 @@ export const docsDense = {
   description: 'Scrollable main content area.',
   propDescriptions: {
     children: 'Content.',
+    padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
     label: 'Accessible label for landmark element.',
     role: 'ARIA landmark role.',