@astryxdesign/core 0.1.4-canary.fd7ab46 → 0.1.4

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -25,6 +25,7 @@
 
 import {useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Item} from '../Item';
 import {
@@ -34,7 +35,6 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import type {BaseProps} from '../BaseProps';
 import {useDropdownMenuContext} from './DropdownMenuContext';
 import {themeProps} from '../utils/themeProps';
 
@@ -75,10 +75,7 @@ const itemSizeStyles = stylex.create({
   lg: {},
 });
 
-export interface DropdownMenuItemProps extends Pick<
-  BaseProps,
-  'xstyle' | 'className' | 'style'
-> {
+export interface DropdownMenuItemProps {
   /** Icon to display before the label. */
   icon?: ReactNode | IconType;
   /** Primary label text. */
@@ -91,6 +88,21 @@ export interface DropdownMenuItemProps extends Pick<
   isDisabled?: boolean;
   /** Additional content to render after the label/description. */
   endContent?: ReactNode;
+  /**
+   * StyleX styles for layout customization (margins, positioning, sizing).
+   * Must be a `stylex.create()` value — not an inline style object.
+   *
+   * @example
+   * ```
+   * const styles = stylex.create({ wrapper: { marginTop: 8 } });
+   * <DropdownMenuItem xstyle={styles.wrapper} />
+   * ```
+   */
+  xstyle?: StyleXStyles;
+  /** CSS class name(s) appended to the root element. */
+  className?: string;
+  /** Inline styles applied to the root element. */
+  style?: React.CSSProperties;
 }
 
 /**

package/src/Field/Field.test.tsx

@@ -137,7 +137,10 @@ describe('Field', () => {
 
   it('renders description without ID attribute when descriptionID is not provided', () => {
     render(
-      <Field label="Email" inputID="email-input" description="Description text">
+      <Field
+        label="Email"
+        inputID="email-input"
+        description="Description text">
         <input id="email-input" />
       </Field>,
     );

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 {TestIcon} from '../__tests__/TestIcon';
+import {StarIcon} from '@heroicons/react/24/outline';
 import {FieldLabel} from './FieldLabel';
 
 describe('FieldLabel', () => {
@@ -49,7 +49,7 @@ describe('FieldLabel', () => {
       <FieldLabel
         label="Starred"
         inputID="starred-input"
-        labelIcon={TestIcon}
+        labelIcon={StarIcon}
       />,
     );
     const svg = document.querySelector('svg');

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

@@ -4,6 +4,7 @@ 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
@@ -19,6 +20,7 @@ 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>
@@ -34,6 +36,7 @@ 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 (count capped, tracks still fill)', () => {
+  it('renders with columns object max (capped via track-max)', () => {
     render(
       <Grid columns={{minWidth: 250, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -74,37 +74,13 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // 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).
+    // Track max caps at (100% - 2 * gap) / 3 — no maxWidth on container
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(250px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
+      'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     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">
@@ -113,9 +89,9 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence in the perColumn floor calculation
+    // columnGap takes precedence for track-max calculation
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 3 * var(--spacing-6)) / 4))), 1fr))',
+      'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -189,7 +165,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('1fr');
   });
 
-  it('uses auto-fill with a plain 1fr track when no max specified', () => {
+  it('uses auto-fill without track-max cap when no max specified', () => {
     render(
       <Grid columns={{minWidth: 200}} data-testid="grid">
         <div>Item</div>
@@ -244,7 +220,7 @@ describe('Grid', () => {
 
   // --- P2: columns object + columnGap interaction (hardening #719) ---
 
-  it('uses columnGap var in the count-cap floor when both columnGap and gap are set', () => {
+  it('uses columnGap var in track-max when both columnGap and gap are set', () => {
     render(
       <Grid
         columns={{minWidth: 200, max: 3}}
@@ -255,14 +231,14 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence over gap in the perColumn floor
+    // columnGap takes precedence over gap in track-max
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 2 * var(--spacing-6)) / 3))), 1fr))',
+      'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses gap var in the count-cap floor when columnGap is not set', () => {
+  it('uses gap var in track-max when columnGap is not set', () => {
     render(
       <Grid columns={{minWidth: 150, max: 2}} gap={3} data-testid="grid">
         <div>Item</div>
@@ -270,12 +246,12 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(150px, calc((100% - 1 * var(--spacing-3)) / 2))), 1fr))',
+      'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses simple fraction in the count-cap floor when no gap is set', () => {
+  it('uses simple fraction in track-max when no gap is set', () => {
     render(
       <Grid columns={{minWidth: 100, max: 3}} data-testid="grid">
         <div>Item</div>
@@ -283,7 +259,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(100px, calc(100% / 3))), 1fr))',
+      'repeat(auto-fill, minmax(100px, calc(100% / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -356,7 +332,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
   });
 
-  it('renders with columns={{minWidth, max}} capping the count while filling', () => {
+  it('renders with columns={{minWidth, max}} capping via track-max', () => {
     render(
       <Grid columns={{minWidth: 280, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -364,15 +340,14 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // Count is capped via the track MIN; track MAX stays 1fr so present
-    // columns fill the row (grid stays full width).
+    // Track-max limits columns — grid stays full width
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
+      'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + count cap', () => {
+  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + track-max', () => {
     render(
       <Grid
         columns={{minWidth: 280, max: 3, repeat: 'fit'}}
@@ -384,7 +359,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fit, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
+      'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
   });

package/src/Grid/Grid.tsx

@@ -38,10 +38,9 @@ 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. 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).
+ *   - `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.
  */
 export type GridColumns =
   | number
@@ -322,20 +321,9 @@ const spacingVarNames: Record<SpacingStep, string> = {
 };
 
 /**
- * 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.
+ * 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.
  */
 function buildCappedTemplate(
   minWidth: number,
@@ -351,17 +339,12 @@ function buildCappedTemplate(
         ? spacingVarNames[gap]
         : null;
 
-  // 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
+  // trackMax = (100% - (maxCols - 1) * gap) / maxCols
+  const trackMax = gapVar
     ? `calc((100% - ${maxCols - 1} * var(${gapVar})) / ${maxCols})`
     : `calc(100% / ${maxCols})`;
 
-  // 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))`;
+  return `repeat(${repeatMode}, minmax(${minWidth}px, ${trackMax}))`;
 }
 
 /**

package/src/HoverCard/HoverCard.doc.mjs

@@ -46,13 +46,13 @@ export const docs = {
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+          description: 'Position relative to the anchor element.',
           default: "'above'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+          description: 'Alignment along the placement axis.',
           default: "'center'",
         },
         {
@@ -155,13 +155,13 @@ export const docsZh = {
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: '相对于锚点元素的位置。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
+          description: '相对于锚点元素的位置。',
           default: "'above'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: '沿放置轴的对齐方式。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。',
+          description: '沿放置轴的对齐方式。',
           default: "'center'",
         },
         {
@@ -246,8 +246,8 @@ export const docsDense = {
       propDescriptions: {
         children: 'Trigger element; must accept ref.',
         content: 'Hover card content.',
-        placement: 'Position relative to anchor element. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-        alignment: 'Alignment along placement axis. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+        placement: 'Position relative to anchor element.',
+        alignment: 'Alignment along placement axis.',
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger hover card.',

package/src/HoverCard/useHoverCard.doc.mjs

@@ -7,8 +7,8 @@ export const docs = {
   group: 'HoverCard',
   keywords: ['hovercard', 'hover', 'preview', 'card', 'tooltip', 'popup', 'floating', 'anchor'],
   params: [
-    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
+    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: 'Position relative to the trigger.', default: "'above'"},
+    {name: 'alignment', type: "'start' | 'center' | 'end'", description: 'Alignment along the placement axis.', default: "'center'"},
     {name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},
     {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
     {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
@@ -24,7 +24,7 @@ export const docs = {
     {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.'},
     {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
     {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
-    {name: 'renderHoverCard', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment.'},
+    {name: 'renderHoverCard', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for the anchor-positioned hover card content.'},
     {name: 'show', type: '() => void', description: 'Imperatively show the hover card immediately.'},
     {name: 'hide', type: '() => void', description: 'Imperatively hide the hover card immediately.'},
   ],
@@ -46,8 +46,8 @@ export const docs = {
 export const docsDense = {
   description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {
-    placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-    alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+    placement: 'position relative to trigger.',
+    alignment: 'alignment along placement axis.',
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
     focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',

package/src/HoverCard/useHoverCard.tsx

@@ -181,14 +181,10 @@ export interface HoverCardReturn {
   /**
    * Render function for hover card content.
    * Returns anchor-positioned popover element.
-   *
-   * `positioning` is excluded: the hover card always derives its position
-   * from placement/alignment, so accepting the custom opt-out here would be
-   * a silent no-op.
    */
   renderHoverCard: (
     children: ReactNode,
-    props?: Omit<ContextRenderProps, 'positioning'>,
+    props?: ContextRenderProps,
   ) => ReactNode;
 
   /**
@@ -454,10 +450,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
   // Render function that wraps layer.render with hover card behavior
   const renderHoverCard = useCallback(
-    (
-      children: ReactNode,
-      props?: Omit<ContextRenderProps, 'positioning'>,
-    ): ReactNode => {
+    (children: ReactNode, props?: ContextRenderProps): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
       const renderProps = {
         placement: renderPlacement,

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 {TestIcon} from '../__tests__/TestIcon';
+import {HomeIcon} from '@heroicons/react/24/outline';
 import {Icon} from './Icon';
 
 describe('Icon', () => {
   it('renders the icon component', () => {
-    render(<Icon icon={TestIcon} data-testid="icon" />);
+    render(<Icon icon={HomeIcon} data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
   it('renders as an SVG element', () => {
-    render(<Icon icon={TestIcon} data-testid="icon" />);
+    render(<Icon icon={HomeIcon} data-testid="icon" />);
     const icon = screen.getByTestId('icon');
     expect(icon.tagName.toLowerCase()).toBe('svg');
   });
 
   it('applies aria-hidden by default', () => {
-    render(<Icon icon={TestIcon} data-testid="icon" />);
+    render(<Icon icon={HomeIcon} data-testid="icon" />);
     expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
   });
 
   it('renders with different color variants', () => {
     const {rerender} = render(
-      <Icon icon={TestIcon} color="primary" data-testid="icon" />,
+      <Icon icon={HomeIcon} color="primary" data-testid="icon" />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="secondary" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="secondary" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="accent" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="accent" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="success" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="success" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="error" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="error" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="warning" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="warning" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} color="inherit" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} color="inherit" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
@@ -70,41 +70,50 @@ describe('Icon', () => {
       'purple',
     ] as const;
     const {rerender} = render(
-      <Icon icon={TestIcon} color={nonSemanticColors[0]} data-testid="icon" />,
+      <Icon
+        icon={HomeIcon}
+        color={nonSemanticColors[0]}
+        data-testid="icon"
+      />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
     for (const c of nonSemanticColors.slice(1)) {
-      rerender(<Icon icon={TestIcon} color={c} data-testid="icon" />);
+      rerender(<Icon icon={HomeIcon} color={c} data-testid="icon" />);
       expect(screen.getByTestId('icon')).toBeInTheDocument();
     }
   });
 
   it('renders with different size variants', () => {
     const {rerender} = render(
-      <Icon icon={TestIcon} size="xsm" data-testid="icon" />,
+      <Icon icon={HomeIcon} size="xsm" data-testid="icon" />,
     );
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} size="sm" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} size="sm" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} size="md" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} size="md" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
 
-    rerender(<Icon icon={TestIcon} size="lg" data-testid="icon" />);
+    rerender(<Icon icon={HomeIcon} size="lg" data-testid="icon" />);
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
   it('forwards ref correctly', () => {
     const ref = vi.fn();
-    render(<Icon icon={TestIcon} ref={ref} />);
+    render(<Icon icon={HomeIcon} ref={ref} />);
     expect(ref).toHaveBeenCalledWith(expect.any(SVGSVGElement));
   });
 
   it('passes additional SVG props', () => {
     render(
-      <Icon icon={TestIcon} data-testid="icon" role="img" aria-label="Home" />,
+      <Icon
+        icon={HomeIcon}
+        data-testid="icon"
+        role="img"
+        aria-label="Home"
+      />,
     );
     const icon = screen.getByTestId('icon');
     expect(icon).toHaveAttribute('role', 'img');
@@ -112,29 +121,8 @@ describe('Icon', () => {
   });
 
   it('uses default color and size when not specified', () => {
-    render(<Icon icon={TestIcon} data-testid="icon" />);
+    render(<Icon icon={HomeIcon} 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,16 +281,12 @@ 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/Layer/useLayer.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles — including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
     },
   ],
   usage: {
@@ -130,7 +130,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring — yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
+    render: 'renders popover element; pass placement/alignment or x/y. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
   },
   usage: {
     description: