@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/hooks/useInputContainer.ts

@@ -35,6 +35,36 @@ const FOCUS_INPUT_TYPES = new Set([
   'week',
 ]);
 
+/**
+ * `aria-haspopup` values that advertise a control opens a popup on activation.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-haspopup
+ */
+const HASPOPUP_VALUES = new Set([
+  'true',
+  'menu',
+  'listbox',
+  'tree',
+  'grid',
+  'dialog',
+]);
+
+/**
+ * Whether an element is a popup trigger — a combobox or any control that
+ * advertises `aria-haspopup`. Such controls activate their popup on *click*
+ * (e.g. DateInput's `<input type="text" role="combobox" aria-haspopup="dialog">`
+ * opens its calendar via `onClick`, with no `onFocus` opener). Forwarding a
+ * container click to `.focus()` would focus the control but leave the popup
+ * closed — so we `.click()` these instead. Plain text inputs (no popup) are
+ * unaffected and keep `.focus()`.
+ */
+function isPopupTrigger(el: HTMLElement): boolean {
+  if (el.getAttribute('role') === 'combobox') {
+    return true;
+  }
+  const haspopup = el.getAttribute('aria-haspopup');
+  return haspopup != null && HASPOPUP_VALUES.has(haspopup);
+}
+
 export interface UseInputContainerOptions {
   /** Ref to the outer container/wrapper element */
   containerRef: RefObject<HTMLElement | null>;
@@ -83,7 +113,12 @@ export function useInputContainer({
     if (input == null) {
       return;
     }
-    if (
+    // Popup triggers (combobox / aria-haspopup) activate their popup on
+    // *click*, not focus — so check this BEFORE the type check, otherwise a
+    // `type="text"` combobox (DateInput) would `.focus()` and never open.
+    if (input instanceof HTMLElement && isPopupTrigger(input)) {
+      input.click();
+    } else if (
       input instanceof HTMLInputElement &&
       FOCUS_INPUT_TYPES.has(input.type)
     ) {

package/src/hooks/useInputStatusIcon.test.tsx

@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import type {ReactElement} from 'react';
+import {render, screen} from '@testing-library/react';
+import {TextInput} from '../TextInput/TextInput';
+import {TextArea} from '../TextArea/TextArea';
+import {NumberInput} from '../NumberInput/NumberInput';
+import {DateInput} from '../DateInput/DateInput';
+import {DateRangeInput} from '../DateRangeInput/DateRangeInput';
+import {TimeInput} from '../TimeInput/TimeInput';
+import {FileInput} from '../FileInput/FileInput';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
+
+// Every id referenced by an aria-describedby must resolve to an element in the
+// document (WCAG 1.3.1) — a described-by pointing at a non-rendered node is a
+// dangling reference. The tooltip variant is the interesting case: it swaps the
+// message box for a tooltip layer, so the referenced ids change per variant.
+function expectNoDanglingDescribedBy(root: HTMLElement) {
+  for (const el of Array.from(root.querySelectorAll('[aria-describedby]'))) {
+    const value = el.getAttribute('aria-describedby') ?? '';
+    for (const id of value.split(/\s+/).filter(Boolean)) {
+      expect(
+        document.getElementById(id),
+        `dangling aria-describedby id "${id}" on <${el.tagName.toLowerCase()}>`,
+      ).not.toBeNull();
+    }
+  }
+}
+
+const VARIANTS: FieldStatusVariant[] = ['attached', 'detached', 'tooltip'];
+
+const INPUTS: [string, (variant: FieldStatusVariant) => ReactElement][] = [
+  [
+    'TextInput',
+    v => (
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'TextArea',
+    v => (
+      <TextArea
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'NumberInput',
+    v => (
+      <NumberInput
+        label="Field"
+        value={undefined}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'DateInput',
+    v => (
+      <DateInput
+        label="Field"
+        value={undefined}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'DateRangeInput',
+    v => (
+      <DateRangeInput
+        label="Field"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'TimeInput',
+    v => (
+      <TimeInput
+        label="Field"
+        value={undefined}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+  [
+    'FileInput',
+    v => (
+      <FileInput
+        label="Field"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant={v}
+      />
+    ),
+  ],
+];
+
+describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', () => {
+  for (const [name, make] of INPUTS) {
+    for (const variant of VARIANTS) {
+      it(`${name} / statusVariant="${variant}"`, () => {
+        const {container} = render(make(variant));
+        expectNoDanglingDescribedBy(container);
+      });
+    }
+  }
+
+  it('tooltip variant links the input to the rendered tooltip element', () => {
+    render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const input = screen.getByRole('textbox');
+    const tooltip = screen.getByRole('tooltip', {hidden: true});
+    expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+
+  it('does not render a tooltip (or reference one) when there is no message', () => {
+    // No message → the tooltip variant renders no tooltip layer and no
+    // described-by should point at a non-existent status element.
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error'}}
+        statusVariant="tooltip"
+      />,
+    );
+    expect(
+      screen.queryByRole('tooltip', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expectNoDanglingDescribedBy(container);
+  });
+});
+
+describe('useInputStatusIcon — input-status-icon theme target', () => {
+  // The stable theme target lands on the on-field status glyph itself, so a
+  // theme can restyle (e.g. resize) just this icon via `defineTheme`. It is
+  // rendered by the attached and tooltip variants; detached suppresses the
+  // on-field icon in favour of the detached message box's leading glyph.
+  const getStatusIcon = (root: HTMLElement): HTMLElement => {
+    const icon = root.querySelector('.astryx-input-status-icon');
+    if (icon == null) {
+      throw new Error('status icon not found');
+    }
+    return icon as HTMLElement;
+  };
+
+  for (const variant of ['attached', 'tooltip'] as const) {
+    it(`renders the target on the on-field icon (statusVariant="${variant}")`, () => {
+      const {container} = render(
+        <TextInput
+          label="Field"
+          value=""
+          onChange={() => {}}
+          status={{type: 'warning', message: 'Message'}}
+          statusVariant={variant}
+        />,
+      );
+      const icon = getStatusIcon(container);
+      expect(icon).toHaveClass('astryx-input-status-icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-size', 'md');
+      expect(icon).toHaveAttribute('data-status', 'warning');
+    });
+  }
+
+  it('reflects the status type per status', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'success', message: 'Message'}}
+        statusVariant="attached"
+      />,
+    );
+    expect(getStatusIcon(container)).toHaveAttribute('data-status', 'success');
+  });
+
+  it('does not render the on-field target for the detached variant', () => {
+    const {container} = render(
+      <TextInput
+        label="Field"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Message'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-input-status-icon')).toBeNull();
+  });
+});

package/src/hooks/useInputStatusIcon.tsx

@@ -0,0 +1,235 @@
+// 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';
+import {themeProps} from '../utils/themeProps';
+
+/**
+ * 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}
+      // Stable theme target on the status glyph itself, so a theme can restyle
+      // just this icon (color, size) — and each status — via `defineTheme`.
+      // Same-element rules in @layer astryx-theme win over the icon's own base
+      // width/height/fontSize, which a field-level target could not reach.
+      // Shared by the attached and tooltip variants across all bordered inputs.
+      {...themeProps('input-status-icon', {size, status: 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.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useKeyboardHint',
   displayName: 'useKeyboardHint',
@@ -72,7 +72,7 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',

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)
@@ -13,7 +13,7 @@
  * - /packages/core/src/hooks/index.ts
  * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
  * - /apps/storybook/stories/useKeyboardHint.stories.tsx
- * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
  */
 
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
@@ -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

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useListFocus',
   displayName: 'useListFocus',
@@ -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:
@@ -116,18 +135,19 @@ export const docs = {
   category: 'focus',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',
   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: