@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

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.', default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: 'Alignment along the placement axis.', default: "'center'"},
+    {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: '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?: ContextRenderProps) => ReactNode', description: 'Render function for the anchor-positioned hover card content.'},
+    {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: '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.',
-    alignment: 'alignment along placement axis.',
+    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).',
     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,10 +181,14 @@ 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?: ContextRenderProps,
+    props?: Omit<ContextRenderProps, 'positioning'>,
   ) => ReactNode;
 
   /**
@@ -450,7 +454,10 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
   // Render function that wraps layer.render with hover card behavior
   const renderHoverCard = useCallback(
-    (children: ReactNode, props?: ContextRenderProps): ReactNode => {
+    (
+      children: ReactNode,
+      props?: Omit<ContextRenderProps, 'positioning'>,
+    ): 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 {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.doc.mjs

@@ -20,6 +20,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-input-group', visualProps: ['size', 'status']},
+      {className: 'astryx-input-group-text'},
     ],
   },
   description:

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/InteractiveRoleContext/InteractiveRoleContext.test.tsx

@@ -0,0 +1,185 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file InteractiveRoleContext.test.tsx
+ * @input Uses vitest, @testing-library/react, InteractiveRoleContext + useInteractiveRole
+ * @output Characterization tests for the interactive-role override context
+ * @position Testing; validates the role-override contract and its consumption
+ *   by useInteractiveRole
+ *
+ * SYNC: When InteractiveRoleContext.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {renderHook} from '@testing-library/react';
+import {createElement, type ReactNode} from 'react';
+import {
+  InteractiveRoleContext,
+  useInteractiveRoleContext,
+} from './InteractiveRoleContext';
+import {
+  useInteractiveRole,
+  type InteractiveRole,
+} from '../hooks/useInteractiveRole';
+
+/** Wrap children in an InteractiveRoleContext provider set to `role`. */
+function withRole(role: InteractiveRole | null) {
+  return function Wrapper({children}: {children: ReactNode}) {
+    return (
+      <InteractiveRoleContext value={role}>{children}</InteractiveRoleContext>
+    );
+  };
+}
+
+describe('InteractiveRoleContext', () => {
+  describe('context primitive', () => {
+    it('defaults to null when read with no provider', () => {
+      const {result} = renderHook(() => useInteractiveRoleContext());
+      expect(result.current).toBeNull();
+    });
+
+    it('exposes a displayName for devtools', () => {
+      expect(InteractiveRoleContext.displayName).toBe('InteractiveRoleContext');
+    });
+
+    it('returns the provided role override', () => {
+      const {result} = renderHook(() => useInteractiveRoleContext(), {
+        wrapper: withRole('button'),
+      });
+      expect(result.current).toBe('button');
+    });
+
+    it('returns null when a provider explicitly supplies null', () => {
+      const {result} = renderHook(() => useInteractiveRoleContext(), {
+        wrapper: withRole(null),
+      });
+      expect(result.current).toBeNull();
+    });
+
+    it.each(['link', 'button', 'inert'] as const)(
+      'passes through the "%s" override verbatim',
+      role => {
+        const {result} = renderHook(() => useInteractiveRoleContext(), {
+          wrapper: withRole(role),
+        });
+        expect(result.current).toBe(role);
+      },
+    );
+
+    it('resolves to the nearest provider when nested', () => {
+      function Nested({children}: {children: ReactNode}) {
+        return (
+          <InteractiveRoleContext value="link">
+            <InteractiveRoleContext value="button">
+              {children}
+            </InteractiveRoleContext>
+          </InteractiveRoleContext>
+        );
+      }
+      const {result} = renderHook(() => useInteractiveRoleContext(), {
+        wrapper: Nested,
+      });
+      expect(result.current).toBe('button');
+    });
+
+    it('supports the createElement (no-JSX) provider form', () => {
+      const {result} = renderHook(() => useInteractiveRoleContext(), {
+        wrapper: ({children}: {children: ReactNode}) =>
+          createElement(InteractiveRoleContext, {value: 'button'}, children),
+      });
+      expect(result.current).toBe('button');
+    });
+  });
+
+  // useInteractiveRole is the real consumer of this context; these tests pin
+  // down how the context signal participates in the role-resolution priority.
+  describe('consumption via useInteractiveRole', () => {
+    it('href alone resolves to "link"', () => {
+      const {result} = renderHook(() =>
+        useInteractiveRole({href: '/somewhere'}),
+      );
+      expect(result.current).toBe('link');
+    });
+
+    it('onClick alone resolves to "button"', () => {
+      const {result} = renderHook(() =>
+        useInteractiveRole({onClick: () => {}}),
+      );
+      expect(result.current).toBe('button');
+    });
+
+    it('nothing interactive resolves to "inert"', () => {
+      const {result} = renderHook(() => useInteractiveRole({}));
+      expect(result.current).toBe('inert');
+    });
+
+    it('context override is used when neither href nor onClick is set', () => {
+      const {result} = renderHook(() => useInteractiveRole({}), {
+        wrapper: withRole('button'),
+      });
+      expect(result.current).toBe('button');
+    });
+
+    it('href wins over a context override (navigation has top priority)', () => {
+      const {result} = renderHook(() => useInteractiveRole({href: '/x'}), {
+        wrapper: withRole('button'),
+      });
+      expect(result.current).toBe('link');
+    });
+
+    it('onClick wins over a context override', () => {
+      const {result} = renderHook(
+        () => useInteractiveRole({onClick: () => {}}),
+        {wrapper: withRole('link')},
+      );
+      expect(result.current).toBe('button');
+    });
+
+    // NOTE — documents current behavior. The `isDisabled` JSDoc says a disabled
+    // href "falls back to button", but the implementation only *skips* the link
+    // branch when disabled — it does not force a button. With no onClick and no
+    // context override, a disabled href therefore resolves to "inert", not
+    // "button". (The doc-promised "button" fallback only holds when an onClick
+    // or a context override is also present — see the two tests below.)
+    it('a disabled href with nothing else resolves to "inert" (not "button" as the JSDoc implies)', () => {
+      const {result} = renderHook(() =>
+        useInteractiveRole({href: '/x', isDisabled: true}),
+      );
+      expect(result.current).toBe('inert');
+    });
+
+    it('a disabled href with an onClick resolves to "button" via the onClick branch', () => {
+      const {result} = renderHook(() =>
+        useInteractiveRole({href: '/x', isDisabled: true, onClick: () => {}}),
+      );
+      expect(result.current).toBe('button');
+    });
+
+    it('a disabled href with a context override falls through to that override', () => {
+      const {result} = renderHook(
+        () => useInteractiveRole({href: '/x', isDisabled: true}),
+        {wrapper: withRole('button')},
+      );
+      expect(result.current).toBe('button');
+    });
+
+    it('an "inert" context override is honored when nothing else is interactive', () => {
+      const {result} = renderHook(() => useInteractiveRole({}), {
+        wrapper: withRole('inert'),
+      });
+      expect(result.current).toBe('inert');
+    });
+
+    it('a null onClick is treated as absent (falls through to inert)', () => {
+      const {result} = renderHook(() => useInteractiveRole({onClick: null}));
+      expect(result.current).toBe('inert');
+    });
+
+    it('a null onClick still yields to a context override', () => {
+      const {result} = renderHook(() => useInteractiveRole({onClick: null}), {
+        wrapper: withRole('button'),
+      });
+      expect(result.current).toBe('button');
+    });
+  });
+});

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. 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. 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.',
     },
   ],
   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. 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. 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.',
   },
   usage: {
     description: