@astryxdesign/core 0.1.2 → 0.1.3-canary.1e94ba0

package/dist/hooks/useKeyboardHint.js

@@ -0,0 +1,220 @@
+// 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 } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, radiusVars, shadowVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
+import { Kbd } from "../Kbd/index.js";
+import { useLayer } from "../Layer/useLayer.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const ARROW_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown']);
+const ARROW_HINT_KEYS = {
+  horizontal: ['left', 'right'],
+  vertical: ['up', 'down'],
+  both: ['left', 'right', 'up', 'down']
+};
+const styles = {
+  hint: {
+    kVAEAm: "xixxii4",
+    kpwlN0: "x1anvkwx",
+    kogj98: "x1ghz6dp",
+    kWkggS: "x1prclbq",
+    kaIpWk: "xh6dtrn",
+    kGVxlE: "x1i5ehqx",
+    kLKAdn: "xfsso4q",
+    kGO01o: "xy143xn",
+    kZCmMZ: "x12gdq22",
+    kwRFfy: "x1djylfy",
+    kGuDYH: "x141an7d",
+    kLWn49: "x1ltkj2j",
+    kMwMTN: "xv1l7n4",
+    khDVqt: "xuxw1ft",
+    kSiTet: "xg01cxk xofkqq2",
+    k1ekBW: "xsm4mo9",
+    kIyJzY: "xx6bhzk",
+    kzIqYQ: "xd00j3c",
+    kfzvcC: "x47corl",
+    $$css: true
+  }
+};
+
+// ---------------------------------------------------------------------------
+// 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 = {}) {
+  const {
+    orientation = 'horizontal',
+    dismissAfterMs = 3000,
+    isEnabled = true
+  } = options;
+  const timeoutRef = useRef(null);
+  const dismissedRef = useRef(false);
+  const isVisibleRef = useRef(false);
+  const layerAnchorRef = useRef(() => {});
+  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 => {
+    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 => {
+    if (dismissedRef.current || !isEnabled) {
+      return;
+    }
+    // Only show on keyboard focus (focus-visible)
+    const target = e.target;
+    if (!target.matches(':focus-visible')) {
+      return;
+    }
+    // Only show when focus enters from outside the container
+    const container = e.currentTarget;
+    if (e.relatedTarget instanceof Node && container.contains(e.relatedTarget)) {
+      return;
+    }
+    show(target);
+  }, [show, isEnabled]);
+  const onBlur = useCallback(e => {
+    if (!isVisibleRef.current) {
+      return;
+    }
+    const container = e.currentTarget;
+    // 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 => {
+    if (!isVisibleRef.current) {
+      return;
+    }
+    if (ARROW_KEYS.has(e.key)) {
+      dismiss();
+    }
+  }, [dismiss]);
+
+  // --- Render the hint element ---
+
+  const arrowContent = /*#__PURE__*/_jsx("span", {
+    ...{
+      className: "x3nfvp2 x6s0dn4 xzye2dw"
+    },
+    children: ARROW_HINT_KEYS[orientation].map(key => /*#__PURE__*/_jsx(Kbd, {
+      keys: key
+    }, key))
+  });
+  const hintElement = layer.render(/*#__PURE__*/_jsxs("span", {
+    "aria-hidden": "true",
+    children: [arrowContent, /*#__PURE__*/_jsx("span", {
+      ...{
+        className: "x11g1kdw"
+      },
+      children: "to navigate"
+    })]
+  }), {
+    placement: 'below',
+    alignment: 'start',
+    xstyle: styles.hint,
+    style: {
+      marginBlockStart: spacingVars['--spacing-2']
+    }
+  });
+  return {
+    hintElement,
+    onFocus,
+    onBlur,
+    onKeyDown
+  };
+}

package/dist/hooks/useListFocus.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Navigation orientation for a linear list.
+ * - `'horizontal'`: ArrowLeft/ArrowRight move between items.
+ * - `'vertical'`: ArrowUp/ArrowDown move between items.
+ * - `'both'`: all four arrows move between items (in linear DOM order).
+ */
+export type ListFocusOrientation = 'horizontal' | 'vertical' | 'both';
 /**
  * Configuration for list focus behavior
  */
@@ -17,11 +24,47 @@ export interface UseListFocusOptions {
      */
     onEscape?: () => void;
     /**
-     * Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight,
-     * 'vertical' uses ArrowUp/ArrowDown.
+     * Navigation orientation. `'horizontal'` uses ArrowLeft/ArrowRight,
+     * `'vertical'` uses ArrowUp/ArrowDown, `'both'` accepts all four arrows.
      * @default 'vertical'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: ListFocusOrientation;
+    /**
+     * Whether Home/End jump to the first/last enabled item.
+     * @default true
+     */
+    hasHomeEnd?: boolean;
+    /**
+     * Whether the list is in a right-to-left context. When true, ArrowLeft and
+     * ArrowRight are swapped so horizontal navigation follows visual direction.
+     * Only affects horizontal (`'horizontal'`/`'both'`) navigation.
+     * @default false
+     */
+    isRtl?: boolean;
+    /**
+     * Roving-tabindex ownership. When true, the hook manages a single tab stop
+     * across the items: exactly one enabled item carries `tabindex="0"` and the
+     * rest `tabindex="-1"`. The tab stop is stamped on mount and repaired
+     * whenever items mount/unmount or toggle disabled, and moves with arrow
+     * navigation. Attach the returned {@link UseListFocusReturn.handleFocus} to
+     * the container's `onFocus` to keep the stop in sync after clicks or
+     * programmatic focus.
+     *
+     * When false (the default), the hook only *moves* focus (`.focus()`) and
+     * never touches `tabindex` — the caller owns tab-stop management.
+     * @default false
+     */
+    hasRovingTabIndex?: boolean;
+    /**
+     * 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 non-collapsed selection), and are never stolen from a nested
+     * `contenteditable` (rich-text editor / chat composer). This preserves
+     * normal caret movement while the user is editing inline within the list
+     * (e.g. a toolbar search field or composer).
+     * @default false
+     */
+    hasCaretGuard?: boolean;
 }
 /**
  * Return type for useListFocus hook
@@ -35,18 +78,24 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
      * Key down handler to attach to the list container.
      */
     handleKeyDown: (e: React.KeyboardEvent) => void;
+    /**
+     * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
+     * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it is
+     * always safe to attach.
+     */
+    handleFocus: (e: React.FocusEvent) => void;
     /**
      * Focus a specific item by index.
      */
     focusItem: (index: number) => void;
     /**
-     * Focus the first focusable item.
+     * Focus the first enabled item. Returns true when an item was focused.
      */
-    focusFirst: () => void;
+    focusFirst: () => boolean;
     /**
-     * Focus the last focusable item.
+     * Focus the last enabled item. Returns true when an item was focused.
      */
-    focusLast: () => void;
+    focusLast: () => boolean;
 }
 /**
  * Hook for managing keyboard navigation within a linear list.
@@ -58,6 +107,12 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  * - End: Move to last item
  * - Escape: Custom callback (e.g., close menu)
  *
+ * By default the hook only *moves* focus and leaves `tabindex` management to
+ * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
+ * that owns a single tab stop (roving tabindex) across the items — stamping and
+ * repairing it as items mount/unmount or toggle disabled — for toolbars,
+ * segmented controls, tab strips, and similar composite widgets.
+ *
  * @example
  * ```
  * const {listRef, handleKeyDown} = useListFocus({
@@ -68,6 +123,22 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  *   {items.map(item => <div role="menuitem" tabIndex={0}>{item}</div>)}
  * </div>
  * ```
+ *
+ * Roving-tabindex composite (e.g. a toolbar):
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+ *   itemSelector: 'button, input, [tabindex]',
+ *   orientation: 'horizontal',
+ *   hasRovingTabIndex: true,
+ *   hasCaretGuard: true,
+ * });
+ *
+ * <div ref={listRef} role="toolbar" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {children}
+ * </div>
+ * ```
  */
 export declare function useListFocus<T extends HTMLElement = HTMLElement>(options?: UseListFocusOptions): UseListFocusReturn<T>;
 //# sourceMappingURL=useListFocus.d.ts.map

package/dist/hooks/useListFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAkIvB"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwSvB"}