@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/hooks/useInputStatusIcon.tsx

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInputStatusIcon.tsx
+ * @input Input status, statusVariant, and InputGroup awareness
+ * @output The on-field status icon element (with tooltip) and aria-describedby wiring
+ * @position Shared hook for bordered inputs that render a status affordance inside the control
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * Centralizes the on-field status icon across the bordered inputs (TextInput,
+ * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,
+ * FileInput) so the three statusVariants behave consistently:
+ *
+ * - `attached`  → icon sits inside the control; the message box below carries
+ *   the text.
+ * - `detached`  → the detached message box renders its OWN leading icon, so the
+ *   on-field icon is suppressed here to avoid a duplicate glyph.
+ * - `tooltip`   → no message box renders; the status is surfaced through an
+ *   info-tip on the on-field icon. The icon is a real focusable `<button>` so
+ *   the status is reachable by every user, not just those with hover or a
+ *   screen reader:
+ *     - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a
+ *       visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.
+ *     - Pointer: hover opens it (guarded to fine pointers).
+ *     - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.
+ *     - Assistive tech: the button has an accessible name (its status type,
+ *       WCAG 4.1.2) and is described by the message via `aria-describedby`.
+ *     - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.
+ */
+
+import {useCallback, useEffect, useState} from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon, type IconName, type IconSize} from '../Icon';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
+import type {InputStatus, InputStatusType} from '../Field/types';
+import {useTooltip} from '../Tooltip';
+import {useTranslator} from '../i18n';
+import {colorVars, radiusVars} from '../theme/tokens.stylex';
+
+/**
+ * Maps each status type to its glyph. Shared so every input shows the same icon
+ * for a given status, matching the detached message box's leading icon.
+ */
+const STATUS_ICON: Record<InputStatusType, IconName> = {
+  warning: 'warning',
+  error: 'error',
+  success: 'success',
+};
+
+/**
+ * Accessible-name i18n keys for the focusable status button, keyed by type.
+ */
+const STATUS_BUTTON_LABEL_KEY: Record<InputStatusType, string> = {
+  warning: '@astryx.input.statusButton.warning',
+  error: '@astryx.input.statusButton.error',
+  success: '@astryx.input.statusButton.success',
+};
+
+const styles = stylex.create({
+  // Contain the anchor so the tooltip positions against the icon, and keep the
+  // glyph vertically centered within the input control.
+  iconAnchor: {
+    display: 'inline-flex',
+    alignItems: 'center',
+  },
+  // The tooltip-variant status affordance is a real button so it is keyboard
+  // focusable and tappable. Strip the native chrome and show only a focus ring.
+  statusButton: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 0,
+    margin: 0,
+    border: 'none',
+    background: 'none',
+    color: 'inherit',
+    cursor: 'pointer',
+    borderRadius: radiusVars['--radius-full'],
+    outlineWidth: {default: null, ':focus-visible': '2px'},
+    outlineStyle: {default: null, ':focus-visible': 'solid'},
+    outlineColor: {
+      default: null,
+      ':focus-visible': colorVars['--color-accent'],
+    },
+    outlineOffset: {default: null, ':focus-visible': '2px'},
+  },
+});
+
+export interface UseInputStatusIconOptions {
+  /** The input's status, or undefined when there is none. */
+  status?: InputStatus;
+  /** How the status is presented relative to the input. */
+  statusVariant?: FieldStatusVariant;
+  /** Whether the input is inside an InputGroup (which owns status rendering). */
+  isInGroup?: boolean;
+  /** Size of the on-field icon. @default 'md' */
+  size?: IconSize;
+}
+
+export interface UseInputStatusIconReturn {
+  /**
+   * The on-field status affordance to render inside the input container —
+   * the status icon (plain, for attached) or a focusable info-tip button plus
+   * its tooltip layer (for the `tooltip` variant). `null` when no icon should
+   * render (no status, `detached` variant, or inside a group).
+   */
+  statusIcon: ReactNode;
+  /**
+   * ID to add to the input's `aria-describedby` when — and only when — the
+   * status is surfaced through a rendered tooltip layer (the `tooltip` variant
+   * with a message). It is `undefined` in every other case (no status, no
+   * message, `attached`/`detached`, or inside a group), so call-sites can drop
+   * it straight into their described-by list without a dangling reference: the
+   * id is present exactly when its tooltip element is in the DOM.
+   */
+  describedBy: string | undefined;
+}
+
+/**
+ * Builds the on-field status icon and its accessibility wiring for a bordered
+ * input. See the file header for the per-variant behavior.
+ */
+export function useInputStatusIcon({
+  status,
+  statusVariant = 'attached',
+  isInGroup = false,
+  size = 'md',
+}: UseInputStatusIconOptions): UseInputStatusIconReturn {
+  const t = useTranslator();
+  const isTooltipVariant = statusVariant === 'tooltip';
+  const hasTooltip = isTooltipVariant && !!status?.message;
+
+  // Touch tap-to-toggle. Hover is unavailable on touch, and useTooltip
+  // suppresses simulated hover there, so on touch a tap controls visibility.
+  // `undefined` leaves the tooltip uncontrolled (pointer + keyboard drive it);
+  // a boolean takes control for the current open/close cycle.
+  const [tapOpen, setTapOpen] = useState<boolean | undefined>(undefined);
+
+  const tooltip = useTooltip({
+    placement: 'above',
+    isEnabled: hasTooltip,
+    isOpen: tapOpen,
+  });
+
+  // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed
+  // (Escape/outside interaction), so subsequent pointer/keyboard use behaves
+  // normally.
+  const handleButtonBlur = useCallback(() => {
+    setTapOpen(undefined);
+  }, []);
+
+  const handleButtonClick = useCallback(() => {
+    // Only take control on touch/hover-less devices. On hover-capable devices
+    // pointer hover and keyboard focus already drive the tooltip (uncontrolled),
+    // so a click-toggle would fight them; leave it uncontrolled there.
+    if (
+      typeof window === 'undefined' ||
+      typeof window.matchMedia !== 'function' ||
+      !window.matchMedia('(hover: none)').matches
+    ) {
+      return;
+    }
+    setTapOpen(prev => (prev === true ? false : true));
+  }, []);
+
+  // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled
+  // state (useTooltip owns Escape for the uncontrolled case, but while we hold
+  // control via isOpen it does not, so mirror it here).
+  useEffect(() => {
+    if (tapOpen !== true) {
+      return;
+    }
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setTapOpen(undefined);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [tapOpen]);
+
+  // Inside a group the group owns status rendering; the detached message box
+  // renders its own leading icon, so the on-field icon would duplicate it.
+  const shouldRenderIcon =
+    !!status && !isInGroup && statusVariant !== 'detached';
+
+  if (!shouldRenderIcon) {
+    return {statusIcon: null, describedBy: undefined};
+  }
+
+  const icon = (
+    <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+  );
+
+  // Attached (and tooltip-without-message) variants: plain, non-interactive
+  // icon. The message box (attached) already carries the text.
+  if (!hasTooltip) {
+    return {statusIcon: icon, describedBy: undefined};
+  }
+
+  return {
+    statusIcon: (
+      <>
+        <button
+          type="button"
+          ref={tooltip.ref}
+          aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
+          aria-describedby={tooltip.describedBy}
+          onClick={handleButtonClick}
+          onBlur={handleButtonBlur}
+          {...stylex.props(styles.statusButton)}>
+          {icon}
+        </button>
+        {tooltip.renderTooltip(status.message)}
+      </>
+    ),
+    describedBy: tooltip.describedBy,
+  };
+}

package/src/hooks/useKeyboardHint.test.tsx

@@ -9,6 +9,7 @@
 import {render} from '@testing-library/react';
 import {describe, expect, it} from 'vitest';
 import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
+import {InternationalizationProvider} from '../i18n';
 
 function TestHint({orientation}: {orientation?: KeyboardHintOrientation}) {
   const {hintElement} = useKeyboardHint({orientation});
@@ -67,4 +68,25 @@ describe('useKeyboardHint', () => {
 
     expect(hint.className).toContain('useKeyboardHint__styles.hint');
   });
+
+  it('renders the "to navigate" label from the i18n catalog', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.textContent).toContain('to navigate');
+  });
+
+  it('localizes the "to navigate" label through the i18n catalog', () => {
+    const {container} = render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.keyboardHint.toNavigate': 'pour naviguer'}}}>
+        <TestHint />
+      </InternationalizationProvider>,
+    );
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.textContent).toContain('pour naviguer');
+    expect(hint.textContent).not.toContain('to navigate');
+  });
 });

package/src/hooks/useKeyboardHint.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useKeyboardHint.tsx
- * @input Uses React, StyleX, Kbd, useLayer
+ * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
  * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
  * @position Core hook; shows sighted keyboard users how to navigate composite
  *   widgets that use roving tabindex (single Tab stop, arrows inside)
@@ -27,6 +27,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Kbd} from '../Kbd';
 import {useLayer} from '../Layer/useLayer';
+import {useTranslator} from '../i18n';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -179,6 +180,7 @@ export function useKeyboardHint(
     isEnabled = true,
   } = options;
 
+  const t = useTranslator();
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const dismissedRef = useRef(false);
   const isVisibleRef = useRef(false);
@@ -316,7 +318,9 @@ export function useKeyboardHint(
   const hintElement = layer.render(
     <span aria-hidden="true">
       {arrowContent}
-      <span {...stylex.props(styles.label)}>to navigate</span>
+      <span {...stylex.props(styles.label)}>
+        {t('@astryx.keyboardHint.toNavigate')}
+      </span>
     </span>,
     {
       placement: 'below',

package/src/hooks/useListFocus.doc.mjs

@@ -19,6 +19,13 @@ export const docs = {
       default: "'[role=\"menuitem\"]'",
       required: false,
     },
+    {
+      name: 'options.boundarySelector',
+      type: 'string',
+      description:
+        "Selector identifying a list boundary, for lists that contain nested lists of the same kind (e.g. a menu with submenu flyouts). When set, item collection and key handling are scoped to this level's own container. Typically '[role=\"menu\"]'.",
+      required: false,
+    },
     {
       name: 'options.wrap',
       type: 'boolean',
@@ -49,8 +56,8 @@ export const docs = {
     {
       name: 'options.isRtl',
       type: 'boolean',
-      description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction.',
-      default: 'false',
+      description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction. When omitted, auto-detected from the container computed direction on keydown.',
+      default: "undefined (auto-detect from the container's computed direction)",
       required: false,
     },
     {
@@ -99,6 +106,18 @@ export const docs = {
       type: '() => boolean',
       description: 'Focus the last enabled item. Returns true when an item was focused.',
     },
+    {
+      name: 'ownsEvent',
+      type: '(e: React.KeyboardEvent) => boolean',
+      description:
+        "Whether a key event belongs to this list level rather than a nested list sharing the same boundarySelector. Always true when no boundarySelector is set. Use to guard consumer-added key handling (Enter/Space, typeahead).",
+    },
+    {
+      name: 'getItems',
+      type: '() => HTMLElement[]',
+      description:
+        "This level's focusable items in DOM order (already scoped by boundarySelector). Build typeahead targets from this instead of re-querying.",
+    },
   ],
   usage: {
     description:
@@ -123,11 +142,12 @@ export const docsDense = {
   paramDescriptions: {
     options: 'config for list focus behavior. All fields optional.',
     'options.itemSelector': 'selector for focusable items in list.',
+    'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
     'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
-    'options.isRtl': 'when true, ArrowLeft/ArrowRight swap for horizontal nav (RTL).',
+    'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',
     'options.hasRovingTabIndex': 'opt into roving-tabindex ownership: hook stamps + repairs a single tab stop across items.',
     'options.hasCaretGuard': "when true, don't steal arrow keys from a nested text input/textarea mid-line or from a contenteditable.",
   },
@@ -138,6 +158,8 @@ export const docsDense = {
     focusItem: 'focus specific item by index (clamped to valid range).',
     focusFirst: 'focus first enabled item; returns true when focused.',
     focusLast: 'focus last enabled item; returns true when focused.',
+    ownsEvent: 'whether a key event is this level\'s vs a nested list\'s (boundarySelector); always true without one.',
+    getItems: "this level's focusable items in DOM order, scoped by boundarySelector.",
   },
   usage: {
     description:

package/src/hooks/useListFocus.test.tsx

@@ -3,13 +3,15 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping + navigation
+ * @output Unit tests for useListFocus disabled-item skipping, navigation, and
+ *   RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
 import {describe, it, expect} from 'vitest';
+import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
 
@@ -373,3 +375,153 @@ describe('useListFocus shortcut passthrough', () => {
     expect(screen.getByTestId('A')).toHaveFocus();
   });
 });
+
+/**
+ * A horizontal list (menubar-like) for RTL direction tests. jsdom reflects the
+ * `dir` attribute into computed style only on the element that carries it, so
+ * `dir` is set on the list container itself — the element the hook reads via
+ * listRef.
+ */
+function HorizontalMenu({dir, isRtl}: {dir?: 'ltr' | 'rtl'; isRtl?: boolean}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
+    orientation: 'horizontal',
+    isRtl,
+  });
+  const items = ['One', 'Two', 'Three'];
+  return (
+    <div ref={listRef} role="menu" dir={dir} onKeyDown={handleKeyDown}>
+      {items.map(label => (
+        <div key={label} role="menuitem" tabIndex={-1} data-testid={label}>
+          {label}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+describe('useListFocus RTL auto-detection (WCAG 1.3.2)', () => {
+  it('auto-detects dir="rtl": ArrowLeft moves to the next item', () => {
+    render(<HorizontalMenu dir="rtl" />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves to the previous item', () => {
+    render(<HorizontalMenu dir="rtl" />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Two').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('One')).toHaveFocus();
+  });
+
+  it('stays LTR without a direction: ArrowRight moves to the next item', () => {
+    render(<HorizontalMenu />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('explicit isRtl={false} overrides a dir="rtl" container', () => {
+    render(<HorizontalMenu dir="rtl" isRtl={false} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowRight'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('explicit isRtl={true} flips arrows without a dir attribute', () => {
+    render(<HorizontalMenu isRtl />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});
+
+// A menu whose second item contains a NESTED role="menu" (mirrors an inline
+// submenu flyout). Exercises boundarySelector: item scoping + event ownership.
+function NestedMenu() {
+  const {listRef, handleKeyDown, ownsEvent} = useListFocus<HTMLDivElement>({
+    boundarySelector: '[role="menu"]',
+    wrap: false,
+  });
+  return (
+    <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer1">
+        Outer1
+      </div>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer2">
+        Outer2
+        {/* Nested submenu rendered inline (like a popover flyout). */}
+        <div role="menu" data-testid="inner-menu">
+          <div role="menuitem" tabIndex={-1} data-testid="Inner1">
+            Inner1
+          </div>
+          <div role="menuitem" tabIndex={-1} data-testid="Inner2">
+            Inner2
+          </div>
+        </div>
+      </div>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer3">
+        Outer3
+      </div>
+      {/* Surface ownership for assertions. */}
+      <input
+        data-testid="probe-owns"
+        onKeyDown={e => {
+          e.currentTarget.setAttribute('data-owns', String(ownsEvent(e)));
+        }}
+      />
+    </div>
+  );
+}
+
+// Variant with the ownsEvent probe placed INSIDE the nested menu, so a key
+// event from it reports as not-owned by the outer list.
+function NestedMenuWithInnerProbe() {
+  const {listRef, handleKeyDown, ownsEvent} = useListFocus<HTMLDivElement>({
+    boundarySelector: '[role="menu"]',
+    wrap: false,
+  });
+  const report = (e: ReactKeyboardEvent<HTMLInputElement>) => {
+    e.currentTarget.setAttribute('data-owns', String(ownsEvent(e)));
+  };
+  return (
+    <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+      <div role="menuitem" tabIndex={-1} data-testid="Outer1">
+        Outer1
+      </div>
+      <div role="menu" data-testid="inner-menu">
+        <input data-testid="inner-probe" onKeyDown={report} />
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus boundarySelector (nested lists)', () => {
+  it("ArrowDown skips over a nested list's items to the next own item", () => {
+    render(<NestedMenu />);
+    const menu = screen.getAllByRole('menu')[0];
+    screen.getByTestId('Outer2').focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    // Lands on Outer3, not Inner1 (which is inside the nested menu).
+    expect(screen.getByTestId('Outer3')).toHaveFocus();
+  });
+
+  it('ownsEvent is true for an event originating at this level', () => {
+    render(<NestedMenu />);
+    const ownProbe = screen.getByTestId('probe-owns');
+    fireEvent.keyDown(ownProbe, {key: 'ArrowDown'});
+    expect(ownProbe).toHaveAttribute('data-owns', 'true');
+  });
+
+  it('ownsEvent is false for an event from inside a nested list', () => {
+    render(<NestedMenuWithInnerProbe />);
+    const innerProbe = screen.getByTestId('inner-probe');
+    fireEvent.keyDown(innerProbe, {key: 'ArrowDown'});
+    expect(innerProbe).toHaveAttribute('data-owns', 'false');
+  });
+});