@astryxdesign/core 0.1.2 → 0.1.3

package/src/hooks/useKeyboardHint.test.tsx

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useKeyboardHint.test.tsx
+ * @input Uses React Testing Library, useKeyboardHint
+ * @output Unit tests for keyboard hint rendering
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
+
+function TestHint({orientation}: {orientation?: KeyboardHintOrientation}) {
+  const {hintElement} = useKeyboardHint({orientation});
+  return <div>{hintElement}</div>;
+}
+
+function getKeyLabels(container: HTMLElement): (string | null)[] {
+  return Array.from(container.querySelectorAll('.astryx-kbd')).map(key =>
+    key.getAttribute('aria-label'),
+  );
+}
+
+function getKeyText(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('kbd')).map(
+    key => key.textContent ?? '',
+  );
+}
+
+describe('useKeyboardHint', () => {
+  it('renders horizontal arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="horizontal" />);
+
+    expect(getKeyLabels(container)).toEqual(['Left arrow', 'Right arrow']);
+    expect(getKeyText(container)).toEqual(['←', '→']);
+  });
+
+  it('renders vertical arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="vertical" />);
+
+    expect(getKeyLabels(container)).toEqual(['Up arrow', 'Down arrow']);
+    expect(getKeyText(container)).toEqual(['↑', '↓']);
+  });
+
+  it('renders all arrow keys for both-axis navigation', () => {
+    const {container} = render(<TestHint orientation="both" />);
+
+    expect(getKeyLabels(container)).toEqual([
+      'Left arrow',
+      'Right arrow',
+      'Up arrow',
+      'Down arrow',
+    ]);
+    expect(getKeyText(container)).toEqual(['←', '→', '↑', '↓']);
+  });
+
+  it('positions the hint farther from the anchor', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.style.marginBlockStart).toBe('var(--spacing-2)');
+  });
+
+  it('keeps the hint surface padding after useLayer reset styles', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.className).toContain('useKeyboardHint__styles.hint');
+  });
+});

package/src/hooks/useKeyboardHint.tsx

@@ -0,0 +1,332 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useKeyboardHint.tsx
+ * @input Uses React, StyleX, Kbd, useLayer
+ * @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)
+ *
+ * SYNC: When modified, update:
+ * - /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
+ */
+
+import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  radiusVars,
+  shadowVars,
+  spacingVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import {Kbd} from '../Kbd';
+import {useLayer} from '../Layer/useLayer';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';
+
+export interface UseKeyboardHintOptions {
+  /**
+   * Orientation of the arrow-key navigation. Controls which arrow icons are
+   * shown in the hint badge.
+   * - `'horizontal'` → ← →
+   * - `'vertical'` → ↑ ↓
+   * - `'both'` → ← → ↑ ↓
+   * @default 'horizontal'
+   */
+  orientation?: KeyboardHintOrientation;
+
+  /**
+   * Milliseconds before the hint auto-dismisses after appearing.
+   * @default 3000
+   */
+  dismissAfterMs?: number;
+
+  /**
+   * Whether the hint is enabled. Set to false to disable for a specific
+   * instance (e.g. when the widget is read-only or the user has dismissed
+   * globally).
+   * @default true
+   */
+  isEnabled?: boolean;
+}
+
+export interface UseKeyboardHintReturn {
+  /**
+   * The popover hint element to render inside your component tree (portals to
+   * top layer via `popover="manual"`). Render unconditionally — it manages its
+   * own visibility.
+   */
+  hintElement: ReactNode;
+
+  /**
+   * Attach to the composite container's `onFocus`. Shows the hint on the first
+   * keyboard-focus (`:focus-visible`) entry from outside.
+   */
+  onFocus: (e: React.FocusEvent) => void;
+
+  /**
+   * Attach to the composite container's `onBlur`. Hides the hint when focus
+   * leaves the composite entirely.
+   */
+  onBlur: (e: React.FocusEvent) => void;
+
+  /**
+   * Attach to the composite container's `onKeyDown`. Dismisses the hint on the
+   * first arrow press (the user discovered the interaction).
+   */
+  onKeyDown: (e: React.KeyboardEvent) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const ARROW_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown']);
+
+const ARROW_HINT_KEYS: Record<
+  KeyboardHintOrientation,
+  ReadonlyArray<string>
+> = {
+  horizontal: ['left', 'right'],
+  vertical: ['up', 'down'],
+  both: ['left', 'right', 'up', 'down'],
+};
+
+const styles = stylex.create({
+  hint: {
+    // Top layer + anchor positioned
+    position: 'fixed',
+    inset: 'auto',
+    margin: 0,
+    border: 'none',
+
+    // Surface
+    backgroundColor: colorVars['--color-background-popover'],
+    borderRadius: radiusVars['--radius-element'],
+    boxShadow: shadowVars['--shadow-low'],
+    paddingBlockStart: spacingVars['--spacing-1'],
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    paddingInlineStart: spacingVars['--spacing-2'],
+    paddingInlineEnd: spacingVars['--spacing-2'],
+
+    // Typography
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+    whiteSpace: 'nowrap',
+
+    // Animation
+    opacity: {
+      default: 0,
+      ':popover-open': 1,
+    },
+    transitionProperty: 'opacity, display, overlay',
+    transitionDuration: '150ms',
+    transitionBehavior: 'allow-discrete',
+
+    // Don't capture pointer events (hint floats above content)
+    pointerEvents: 'none',
+  },
+  keys: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  label: {
+    marginInlineStart: spacingVars['--spacing-1'],
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Shows an ephemeral visual hint ("← → to navigate") anchored to the focused
+ * item when a composite widget first receives keyboard focus. Teaches sighted
+ * keyboard users that arrows navigate within the group.
+ *
+ * The hint renders in the top layer (popover="manual") and is CSS-anchor-
+ * positioned to the currently focused element, so it is never clipped by
+ * overflow containers. It auto-dismisses on first arrow press, timeout, or
+ * blur, and does not re-show for that instance.
+ *
+ * @example
+ * ```
+ * const hint = useKeyboardHint({orientation: 'horizontal'});
+ * <div role="toolbar" onFocus={hint.onFocus} onBlur={hint.onBlur} onKeyDown={hint.onKeyDown}>
+ *   {children}
+ *   {hint.hintElement}
+ * </div>
+ * ```
+ */
+export function useKeyboardHint(
+  options: UseKeyboardHintOptions = {},
+): UseKeyboardHintReturn {
+  const {
+    orientation = 'horizontal',
+    dismissAfterMs = 3000,
+    isEnabled = true,
+  } = options;
+
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const dismissedRef = useRef(false);
+  const isVisibleRef = useRef(false);
+  const layerAnchorRef = useRef<(el: HTMLElement | null) => void>(() => {});
+
+  const clearDismissTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  const handleLayerShow = useCallback(() => {
+    isVisibleRef.current = true;
+  }, []);
+
+  const handleLayerHide = useCallback(() => {
+    isVisibleRef.current = false;
+    clearDismissTimeout();
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout]);
+
+  const layer = useLayer({
+    mode: 'context',
+    onShow: handleLayerShow,
+    onHide: handleLayerHide,
+  });
+  layerAnchorRef.current = layer.ref;
+
+  // Hide + mark dismissed (won't re-show for this instance)
+  const dismiss = useCallback(() => {
+    dismissedRef.current = true;
+    clearDismissTimeout();
+    layer.hide();
+    isVisibleRef.current = false;
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout, layer]);
+
+  // Show the layer anchored to the focused element
+  const show = useCallback(
+    (anchor: HTMLElement) => {
+      if (dismissedRef.current || !isEnabled) {
+        return;
+      }
+
+      layerAnchorRef.current(anchor);
+      layer.show();
+
+      clearDismissTimeout();
+      timeoutRef.current = setTimeout(() => {
+        dismiss();
+      }, dismissAfterMs);
+    },
+    [clearDismissTimeout, dismiss, dismissAfterMs, isEnabled, layer],
+  );
+
+  // Cleanup on unmount
+  useEffect(
+    () => () => {
+      clearDismissTimeout();
+      layerAnchorRef.current(null);
+    },
+    [clearDismissTimeout],
+  );
+
+  // --- Handlers ---
+
+  const onFocus = useCallback(
+    (e: React.FocusEvent) => {
+      if (dismissedRef.current || !isEnabled) {
+        return;
+      }
+      // Only show on keyboard focus (focus-visible)
+      const target = e.target as HTMLElement;
+      if (!target.matches(':focus-visible')) {
+        return;
+      }
+      // Only show when focus enters from outside the container
+      const container = e.currentTarget as HTMLElement;
+      if (
+        e.relatedTarget instanceof Node &&
+        container.contains(e.relatedTarget)
+      ) {
+        return;
+      }
+      show(target);
+    },
+    [show, isEnabled],
+  );
+
+  const onBlur = useCallback(
+    (e: React.FocusEvent) => {
+      if (!isVisibleRef.current) {
+        return;
+      }
+      const container = e.currentTarget as HTMLElement;
+      // Only dismiss when focus leaves the container entirely
+      if (
+        e.relatedTarget instanceof Node &&
+        container.contains(e.relatedTarget)
+      ) {
+        // Focus moved within — re-anchor to the new target
+        if (!dismissedRef.current && e.relatedTarget instanceof HTMLElement) {
+          layerAnchorRef.current(e.relatedTarget);
+        }
+        return;
+      }
+      dismiss();
+    },
+    [dismiss],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (!isVisibleRef.current) {
+        return;
+      }
+      if (ARROW_KEYS.has(e.key)) {
+        dismiss();
+      }
+    },
+    [dismiss],
+  );
+
+  // --- Render the hint element ---
+
+  const arrowContent = (
+    <span {...stylex.props(styles.keys)}>
+      {ARROW_HINT_KEYS[orientation].map(key => (
+        <Kbd key={key} keys={key} />
+      ))}
+    </span>
+  );
+
+  const hintElement = layer.render(
+    <span aria-hidden="true">
+      {arrowContent}
+      <span {...stylex.props(styles.label)}>to navigate</span>
+    </span>,
+    {
+      placement: 'below',
+      alignment: 'start',
+      xstyle: styles.hint,
+      style: {
+        marginBlockStart: spacingVars['--spacing-2'],
+      },
+    },
+  );
+
+  return {hintElement, onFocus, onBlur, onKeyDown};
+}

package/src/hooks/useListFocus.doc.mjs

@@ -34,11 +34,39 @@ export const docs = {
     },
     {
       name: 'options.orientation',
-      type: "'horizontal' | 'vertical'",
-      description: "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",
+      type: "'horizontal' | 'vertical' | 'both'",
+      description: "Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
       default: "'vertical'",
       required: false,
     },
+    {
+      name: 'options.hasHomeEnd',
+      type: 'boolean',
+      description: 'Whether Home/End jump to the first/last enabled item.',
+      default: 'true',
+      required: false,
+    },
+    {
+      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',
+      required: false,
+    },
+    {
+      name: 'options.hasRovingTabIndex',
+      type: 'boolean',
+      description: 'Opt into roving-tabindex ownership: the hook stamps a single tab stop (one item tabindex="0", the rest -1), repairs it as items mount/unmount or toggle disabled, and moves it with arrow navigation. When false, the hook only moves focus and never touches tabindex.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasCaretGuard',
+      type: 'boolean',
+      description: "When true, arrow keys are not stolen from a nested text input/textarea whose caret is not at the boundary in the direction of travel (or that has a selection), and are never stolen from a nested contenteditable (rich-text editor / chat composer). Preserves inline text editing within the list.",
+      default: 'false',
+      required: false,
+    },
   ],
   returns: [
     {
@@ -51,6 +79,11 @@ export const docs = {
       type: '(e: React.KeyboardEvent) => void',
       description: 'Key down handler to attach to the list container.',
     },
+    {
+      name: 'handleFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Focus handler for the container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so it is always safe to attach.',
+    },
     {
       name: 'focusItem',
       type: '(index: number) => void',
@@ -58,21 +91,22 @@ export const docs = {
     },
     {
       name: 'focusFirst',
-      type: '() => void',
-      description: 'Focus the first focusable item in the list.',
+      type: '() => boolean',
+      description: 'Focus the first enabled item. Returns true when an item was focused.',
     },
     {
       name: 'focusLast',
-      type: '() => void',
-      description: 'Focus the last focusable item in the list.',
+      type: '() => boolean',
+      description: 'Focus the last enabled item. Returns true when an item was focused.',
     },
   ],
   usage: {
     description:
-      'Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical or horizontal), Home/End for boundaries, optional wrap-around, and Escape to close. Suitable for dropdown menus, toolbars, and any 1D focusable list.',
+      'Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical, horizontal, or both), Home/End for boundaries, optional wrap-around, RTL, and Escape to close. Opt into hasRovingTabIndex for composite widgets (toolbars, segmented controls, tab strips) that own a single tab stop. Suitable for dropdown menus, toolbars, and any 1D focusable list.',
     bestPractices: [
       { guidance: true, description: "Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus." },
       { guidance: true, description: 'Provide an onEscape callback for menus/dropdowns to return focus to the trigger.' },
+      { guidance: true, description: 'Enable hasRovingTabIndex (and hasCaretGuard when the widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },
       { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids and calendars.' },
     ],
   },
@@ -91,14 +125,19 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     '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.",
+    '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.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.",
   },
   returnDescriptions: {
     listRef: 'ref to attach to list container element.',
     handleKeyDown: 'key down handler for list container.',
+    handleFocus: 'focus handler; keeps roving tab stop in sync when hasRovingTabIndex is on (else no-op).',
     focusItem: 'focus specific item by index (clamped to valid range).',
-    focusFirst: 'focus first focusable item in list.',
-    focusLast: 'focus last focusable item in list.',
+    focusFirst: 'focus first enabled item; returns true when focused.',
+    focusLast: 'focus last enabled item; returns true when focused.',
   },
   usage: {
     description:
@@ -106,6 +145,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus." },
       { guidance: true, description: 'Provide onEscape callback for menus/dropdowns to return focus to trigger.' },
+      { guidance: true, description: 'Enable hasRovingTabIndex (+ hasCaretGuard when widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },
       { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids + calendars.' },
     ],
   },