@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/hooks/useLongPress.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useLongPress.ts
+ * @input Long-press options: onLongPress callback, disabled, delayMs, moveCancelPx
+ * @output Touch handlers to spread onto an element
+ * @position Core hook for touch long-press invocation; used by ContextMenu
+ *
+ * SYNC: When modified, update the hooks barrel /packages/core/src/hooks/index.ts
+ *
+ * Detects a single-finger long-press: fires `onLongPress` with the touch
+ * start point after `delayMs`. Cancels if the finger moves past
+ * `moveCancelPx` (treated as a scroll/drag), lifts, or the touch is
+ * cancelled. The pending timer is also cleared on unmount.
+ *
+ * Motivation: iOS Safari never synthesizes a `contextmenu` event on
+ * long-press, so long-press is the only touch affordance for opening
+ * cursor-positioned surfaces.
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+
+// Default long-press tuning.
+const DEFAULT_DELAY_MS = 500;
+const DEFAULT_MOVE_CANCEL_PX = 10;
+
+export interface UseLongPressOptions {
+  /** Fired with the touch start point once the press is held for `delayMs`. */
+  onLongPress: (point: {x: number; y: number}) => void;
+  /** When true, touch handlers are inert. */
+  disabled?: boolean;
+  /** Hold duration before the press fires, in ms. Defaults to 500. */
+  delayMs?: number;
+  /** Movement past this distance (px, either axis) cancels the press. Defaults to 10. */
+  moveCancelPx?: number;
+}
+
+export interface UseLongPressHandlers {
+  onTouchStart: (e: React.TouchEvent) => void;
+  onTouchMove: (e: React.TouchEvent) => void;
+  onTouchEnd: () => void;
+  onTouchCancel: () => void;
+}
+
+export function useLongPress(
+  options: UseLongPressOptions,
+): UseLongPressHandlers {
+  const {
+    onLongPress,
+    disabled = false,
+    delayMs = DEFAULT_DELAY_MS,
+    moveCancelPx = DEFAULT_MOVE_CANCEL_PX,
+  } = options;
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const startRef = useRef<{x: number; y: number} | null>(null);
+  // Keep the latest callback without re-creating handlers on every render.
+  const onLongPressRef = useRef(onLongPress);
+  onLongPressRef.current = onLongPress;
+
+  const clear = useCallback(() => {
+    if (timerRef.current != null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    startRef.current = null;
+  }, []);
+
+  const onTouchStart = useCallback(
+    (e: React.TouchEvent) => {
+      if (disabled || e.touches.length !== 1) {
+        return;
+      }
+      const touch = e.touches[0];
+      // Clear any stale timer first, THEN record the start point — clearing
+      // also nulls startRef, so order matters.
+      clear();
+      startRef.current = {x: touch.clientX, y: touch.clientY};
+      timerRef.current = setTimeout(() => {
+        const start = startRef.current;
+        if (start == null) {
+          return;
+        }
+        onLongPressRef.current({x: start.x, y: start.y});
+      }, delayMs);
+    },
+    [disabled, delayMs, clear],
+  );
+
+  const onTouchMove = useCallback(
+    (e: React.TouchEvent) => {
+      const start = startRef.current;
+      if (start == null || e.touches.length !== 1) {
+        return;
+      }
+      const touch = e.touches[0];
+      if (
+        Math.abs(touch.clientX - start.x) > moveCancelPx ||
+        Math.abs(touch.clientY - start.y) > moveCancelPx
+      ) {
+        // Treat as a scroll/drag, not a long-press.
+        clear();
+      }
+    },
+    [moveCancelPx, clear],
+  );
+
+  // Cancel any pending long-press timer on unmount.
+  useEffect(() => clear, [clear]);
+
+  return {
+    onTouchStart,
+    onTouchMove,
+    onTouchEnd: clear,
+    onTouchCancel: clear,
+  };
+}

package/src/hooks/useTreeFocus.doc.mjs

@@ -0,0 +1,140 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useTreeFocus',
+  displayName: 'useTreeFocus',
+  keywords: ['tree', 'treeview', 'focus', 'keyboard', 'navigation', 'arrow', 'expand', 'collapse', 'roving', 'tabindex', 'a11y', 'wai-aria', 'apg'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseTreeFocusOptions',
+      description: 'Configuration object for tree focus behavior.',
+      required: false,
+    },
+    {
+      name: 'options.itemSelector',
+      type: 'string',
+      description: 'Selector for visible treeitems within the tree, in DOM order.',
+      default: "'[role=\"treeitem\"]'",
+      required: false,
+    },
+    {
+      name: 'options.isItemDisabled',
+      type: '(item: HTMLElement) => boolean',
+      description: 'Predicate for whether a treeitem is disabled and must be skipped during navigation. Defaults to reading `data-tree-disabled` / `aria-disabled`.',
+      required: false,
+    },
+    {
+      name: 'options.getLevel',
+      type: '(item: HTMLElement) => number',
+      description: 'Reads the 1-based nesting level of a treeitem. Defaults to the `aria-level` attribute.',
+      required: false,
+    },
+    {
+      name: 'options.onToggleExpand',
+      type: '(id: string) => void',
+      description: 'Called to expand/collapse the treeitem with the given id (ArrowRight on a collapsed parent, ArrowLeft on an expanded parent, Enter/Space on a parent without its own action).',
+      required: false,
+    },
+    {
+      name: 'options.onActivate',
+      type: '(item: HTMLElement, id: string | undefined) => boolean | void',
+      description: 'Called when Enter/Space activates a treeitem. Return true when handled; return false/undefined to let the hook fall back to toggling expansion.',
+      required: false,
+    },
+    {
+      name: 'options.onActiveChange',
+      type: '(id: string | undefined) => void',
+      description: 'Notified when the hook moves focus to a treeitem. Consumers use this to move a single roving tab stop.',
+      required: false,
+    },
+    {
+      name: 'options.hasRovingTabIndex',
+      type: 'boolean',
+      description: 'When true, the hook owns a single roving tab stop across the visible treeitems (stamps tabindex 0/-1, repairs on mount, moves with navigation). Preserves an existing tabindex="0" seed on mount. Attach the returned `handleFocus` to keep the stop in sync after clicks.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.typeahead',
+      type: 'boolean',
+      description: 'Whether typeahead (jump to next item whose text starts with the typed characters) is enabled.',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'treeRef',
+      type: 'React.RefObject<HTMLElement | null>',
+      description: 'Ref to attach to the tree container element (role="tree").',
+    },
+    {
+      name: 'handleKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description: 'Key down handler to attach to the tree container.',
+    },
+    {
+      name: 'handleFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: '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 always safe to attach.',
+    },
+    {
+      name: 'focusFirst',
+      type: '() => void',
+      description: 'Focus the first enabled visible treeitem.',
+    },
+    {
+      name: 'focusLast',
+      type: '() => void',
+      description: 'Focus the last enabled visible treeitem.',
+    },
+  ],
+  usage: {
+    description:
+      'Manages roving-tabindex focus and the WAI-ARIA tree keyboard model. ArrowUp/ArrowDown/Home/End roam linearly over the visible treeitems (skipping disabled ones), while ArrowRight/ArrowLeft carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate, and printable characters trigger typeahead.',
+    bestPractices: [
+      { guidance: true, description: 'Use for hierarchical tree widgets: wire onToggleExpand to your expansion state and onActiveChange to a single roving tab stop.' },
+      { guidance: true, description: 'Attach both treeRef and handleKeyDown to the role="tree" container element.' },
+      { guidance: false, description: 'Use for linear lists (prefer useListFocus) or 2D grids (prefer useGridFocus); those traversals differ from a tree.' },
+    ],
+  },
+  relatedComponents: ['TreeList'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useFocusTrap'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Manages roving-tabindex focus + WAI-ARIA tree keyboard model. ArrowUp/Down/Home/End roam linearly over visible treeitems (skip disabled); ArrowRight/Left carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate; printable chars trigger typeahead.',
+  paramDescriptions: {
+    options: 'config for tree focus behavior.',
+    'options.itemSelector': 'selector for visible treeitems in DOM order.',
+    'options.isItemDisabled': 'predicate: is treeitem disabled (skipped in nav). Defaults to data-tree-disabled / aria-disabled.',
+    'options.getLevel': 'reads 1-based nesting level. Defaults to aria-level attr.',
+    'options.onToggleExpand': 'expand/collapse treeitem by id (ArrowRight collapsed parent, ArrowLeft expanded parent, Enter/Space parent w/o own action).',
+    'options.onActivate': 'called on Enter/Space activation. Return true when handled; else hook falls back to toggling expansion.',
+    'options.onActiveChange': 'notified when focus moves to a treeitem. Use to move a single roving tab stop.',
+    'options.hasRovingTabIndex': 'hook owns a single roving tab stop (stamps tabindex 0/-1, repairs on mount, moves w/ nav). Preserves an existing tabindex="0" seed. Attach handleFocus to sync after clicks.',
+    'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars).',
+  },
+  returnDescriptions: {
+    treeRef: 'ref to attach to tree container (role="tree").',
+    handleKeyDown: 'key down handler for tree container.',
+    handleFocus: 'onFocus handler; keeps roving tab stop in sync when hasRovingTabIndex on (no-op otherwise).',
+    focusFirst: 'focus first enabled visible treeitem.',
+    focusLast: 'focus last enabled visible treeitem.',
+  },
+  usage: {
+    description:
+      'Manages roving-tabindex focus + WAI-ARIA tree keyboard model. ArrowUp/Down/Home/End roam linearly over visible treeitems (skip disabled); ArrowRight/Left carry tree semantics (expand/collapse, move to first-child/parent). Enter/Space activate; printable chars trigger typeahead.',
+    bestPractices: [
+      { guidance: true, description: 'Use for hierarchical tree widgets: wire onToggleExpand to expansion state + onActiveChange to a single roving tab stop.' },
+      { guidance: true, description: 'Attach both treeRef + handleKeyDown to role="tree" container.' },
+      { guidance: false, description: 'Use for linear lists (prefer useListFocus) or 2D grids (prefer useGridFocus).' },
+    ],
+  },
+};

package/src/hooks/useTreeFocus.test.tsx

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTreeFocus.test.tsx
+ * @input Uses vitest, @testing-library/react, useTreeFocus hook
+ * @output Unit tests for useTreeFocus APG tree keyboard navigation
+ * @position Testing; validates useTreeFocus.ts keyboard model
+ *
+ * SYNC: When useTreeFocus.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {useState} from 'react';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useTreeFocus} from './useTreeFocus';
+
+interface Node {
+  id: string;
+  label: string;
+  level: number;
+  disabled?: boolean;
+  /** 'expanded' | 'collapsed' | undefined (leaf) */
+  expanded?: boolean;
+}
+
+const NO_NODES: Node[] = [];
+
+/**
+ * Minimal generic tree harness driven by a flat list of visible nodes. Mirrors
+ * the DOM contract TreeList exposes: role="treeitem", aria-level, aria-expanded,
+ * data-tree-id, data-tree-disabled. Expansion is faked by swapping the visible
+ * node list on toggle so ArrowRight/ArrowLeft can be exercised.
+ */
+function Tree({
+  collapsed = NO_NODES,
+  expanded = NO_NODES,
+  onActivate,
+}: {
+  collapsed?: Node[];
+  expanded?: Node[];
+  onActivate?: (id: string | undefined) => boolean | undefined;
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+  const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;
+  const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+    onToggleExpand: () => setIsOpen(o => !o),
+    onActivate: onActivate
+      ? (_item, id) => onActivate(id)
+      : undefined,
+  });
+  return (
+    <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+      {nodes.map(n => (
+        <li
+          key={n.id}
+          role="treeitem"
+          aria-level={n.level}
+          aria-expanded={n.expanded}
+          data-tree-id={n.id}
+          data-tree-disabled={n.disabled || undefined}
+          tabIndex={-1}
+          data-testid={n.id}>
+          {n.label}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+const FLAT: Node[] = [
+  {id: 'a', label: 'Apple', level: 1},
+  {id: 'b', label: 'Banana', level: 1},
+  {id: 'c', label: 'Cherry', level: 1},
+];
+
+describe('useTreeFocus linear navigation', () => {
+  it('ArrowDown / ArrowUp move between visible treeitems', () => {
+    render(<Tree collapsed={FLAT} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('b')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('c')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowUp'});
+    expect(screen.getByTestId('b')).toHaveFocus();
+  });
+
+  it('ArrowDown / ArrowUp skip disabled treeitems', () => {
+    const nodes: Node[] = [
+      {id: 'a', label: 'Apple', level: 1},
+      {id: 'b', label: 'Banana', level: 1, disabled: true},
+      {id: 'c', label: 'Cherry', level: 1},
+    ];
+    render(<Tree collapsed={nodes} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('c')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowUp'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+
+  it('Home / End move to the first and last visible treeitems', () => {
+    render(<Tree collapsed={FLAT} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('b').focus();
+
+    fireEvent.keyDown(tree, {key: 'End'});
+    expect(screen.getByTestId('c')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'Home'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+
+  it('ArrowDown does not wrap past the last item', () => {
+    render(<Tree collapsed={FLAT} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('c').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('c')).toHaveFocus();
+  });
+});
+
+describe('useTreeFocus tree semantics (Arrow Left/Right)', () => {
+  const COLLAPSED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: false},
+  ];
+  const EXPANDED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: true},
+    {id: 'c1', label: 'Child 1', level: 2},
+    {id: 'c2', label: 'Child 2', level: 2},
+  ];
+
+  it('ArrowRight expands a collapsed parent, then enters the first child', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+    fireEvent.keyDown(tree, {key: 'ArrowRight'});
+    // Expanded now.
+    expect(screen.getByTestId('c1')).toBeInTheDocument();
+    // Focus stayed on parent.
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'});
+    expect(screen.getByTestId('c1')).toHaveFocus();
+  });
+
+  it('ArrowRight on a leaf is a no-op', () => {
+    render(<Tree collapsed={FLAT} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowRight'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+
+  it('ArrowLeft on a child moves to the parent; on an expanded parent collapses', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} />);
+    const tree = screen.getByRole('tree');
+    // Start expanded.
+    screen.getByTestId('p').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // expand
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // into child 1
+    expect(screen.getByTestId('c1')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // child leaf → parent
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // expanded parent → collapse
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+  });
+});
+
+describe('useTreeFocus activation + typeahead', () => {
+  it('Enter/Space call onActivate for the focused item', () => {
+    const onActivate = vi.fn(() => true);
+    render(<Tree collapsed={FLAT} onActivate={onActivate} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+
+    fireEvent.keyDown(tree, {key: 'Enter'});
+    expect(onActivate).toHaveBeenCalledWith('a');
+
+    fireEvent.keyDown(tree, {key: ' '});
+    expect(onActivate).toHaveBeenCalledTimes(2);
+  });
+
+  it('Enter toggles expansion when onActivate does not handle it', () => {
+    const COLLAPSED: Node[] = [
+      {id: 'p', label: 'Parent', level: 1, expanded: false},
+    ];
+    const EXPANDED: Node[] = [
+      {id: 'p', label: 'Parent', level: 1, expanded: true},
+      {id: 'c1', label: 'Child 1', level: 2},
+    ];
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+    fireEvent.keyDown(tree, {key: 'Enter'});
+    expect(screen.getByTestId('c1')).toBeInTheDocument();
+  });
+
+  it('typeahead moves focus to the next item matching typed characters', () => {
+    render(<Tree collapsed={FLAT} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+    fireEvent.keyDown(tree, {key: 'c'});
+    expect(screen.getByTestId('c')).toHaveFocus();
+  });
+});