@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Tooltip/useTooltip.tsx

@@ -37,6 +37,13 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 
+/**
+ * Grace period (ms) before hiding on pointer-leave when no explicit `hideDelay`
+ * is set, so the pointer can travel across the small gap from the trigger onto
+ * the tooltip surface without the tooltip disappearing (WCAG 1.4.13 hoverable).
+ */
+const HOVER_BRIDGE_DELAY = 100;
+
 const styles = stylex.create({
   // Base container styles - inverted colors for high contrast
   container: {
@@ -233,9 +240,7 @@ function isFocusable(element: HTMLElement): boolean {
  * {tooltip.renderTooltip('Helpful tooltip text')}
  * ```
  */
-export function useTooltip(
-  options: TooltipOptions = {},
-): TooltipReturn {
+export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   const {
     placement = 'above',
     alignment = 'center',
@@ -293,21 +298,29 @@ export function useTooltip(
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, layer, delay]);
 
-  // Schedule hide with delay (suppressed when isOpen is true)
+  // Schedule hide with delay (suppressed when isOpen is true).
+  // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
+  // trigger onto the tooltip surface without the tooltip vanishing — required
+  // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
   const scheduleHide = useCallback(() => {
     if (isOpen === true) {
       return;
     }
     clearTimeouts();
-    if (hideDelay > 0) {
-      hideTimeoutRef.current = setTimeout(() => {
-        layer.hide();
-      }, hideDelay);
-    } else {
+    const effectiveHideDelay = hideDelay > 0 ? hideDelay : HOVER_BRIDGE_DELAY;
+    hideTimeoutRef.current = setTimeout(() => {
       layer.hide();
-    }
+    }, effectiveHideDelay);
   }, [isOpen, clearTimeouts, layer, hideDelay]);
 
+  // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
+  const cancelHide = useCallback(() => {
+    if (hideTimeoutRef.current) {
+      clearTimeout(hideTimeoutRef.current);
+      hideTimeoutRef.current = null;
+    }
+  }, []);
+
   // Event handlers
   const handleMouseEnter = useCallback(() => {
     // Suppress tooltips on touch devices — hover is simulated and eats a tap
@@ -422,6 +435,32 @@ export function useTooltip(
     }
   }, [isOpen, clearTimeouts, layer]);
 
+  // Dismiss on Escape (WCAG 1.4.13 — dismissible). Uncontrolled tooltips only;
+  // a controlled tooltip's visibility is owned by the consumer. The listener is
+  // mounted for the lifetime of an uncontrolled tooltip rather than gated on
+  // `layer.isOpen` (React state, which can lag a frame behind the DOM) —
+  // `layer.hide()` self-guards and no-ops when the layer is already closed.
+  // Guarded against IME composition-cancel.
+  useEffect(() => {
+    if (isOpen !== undefined) {
+      return;
+    }
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') {
+        return;
+      }
+      if (e.isComposing || e.keyCode === 229) {
+        return;
+      }
+      clearTimeouts();
+      layer.hide();
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen, layer, clearTimeouts]);
+
   // Render function that wraps layer.render with tooltip styling
   const renderTooltip = useCallback(
     (children: ReactNode, props?: ContextRenderProps): ReactNode => {
@@ -429,8 +468,15 @@ export function useTooltip(
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
+        role: 'tooltip',
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
         className: themeProps('tooltip').className,
+        // Keep the tooltip open while the pointer is over the surface itself
+        // (WCAG 1.4.13 hoverable). These sit on the layer container — the
+        // element the user actually hovers — not the inner content div, since
+        // mouseenter/leave do not bubble.
+        onMouseEnter: cancelHide,
+        onMouseLeave: scheduleHide,
       };
 
       return layer.render(
@@ -438,7 +484,7 @@ export function useTooltip(
         renderProps,
       );
     },
-    [layer, placement, alignment, popoverXstyle],
+    [layer, placement, alignment, popoverXstyle, cancelHide, scheduleHide],
   );
 
   return {

package/src/TreeList/TreeList.test.tsx

@@ -61,6 +61,44 @@ const deepItems: TreeListItemData[] = [
   },
 ];
 
+// APG keyboard fixtures (module-level to satisfy no-unstable-default-props).
+const flatItems: TreeListItemData[] = [
+  {id: 'a', label: 'Apple'},
+  {id: 'b', label: 'Banana'},
+  {id: 'c', label: 'Cherry'},
+];
+
+const withDisabledItems: TreeListItemData[] = [
+  {id: 'a', label: 'Apple'},
+  {id: 'b', label: 'Banana', isDisabled: true},
+  {id: 'c', label: 'Cherry'},
+];
+
+const collapsedParentItems: TreeListItemData[] = [
+  {
+    id: 'parent',
+    label: 'Parent',
+    children: [
+      {id: 'child-1', label: 'Child 1'},
+      {id: 'child-2', label: 'Child 2'},
+    ],
+  },
+  {id: 'sibling', label: 'Sibling'},
+];
+
+const expandedParentItems: TreeListItemData[] = [
+  {
+    id: 'parent',
+    label: 'Parent',
+    isExpanded: true,
+    children: [
+      {id: 'child-1', label: 'Child 1'},
+      {id: 'child-2', label: 'Child 2'},
+    ],
+  },
+  {id: 'sibling', label: 'Sibling'},
+];
+
 describe('TreeList', () => {
   // ===========================================================================
   // Basic rendering
@@ -160,6 +198,26 @@ describe('TreeList', () => {
     expect(item).not.toHaveAttribute('aria-expanded');
   });
 
+  it('renders a keyboard-focusable toggle button for parents without onClick/href', () => {
+    render(<TreeList items={nestedItems} />);
+    const toggle = screen.getByRole('button', {name: 'Toggle children'});
+    expect(toggle).toBeInTheDocument();
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('expands a parent from the keyboard via the toggle button', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={nestedItems} />);
+    // Collapsed: children are not rendered.
+    expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+    const toggle = screen.getByRole('button', {name: 'Toggle children'});
+    toggle.focus();
+    expect(toggle).toHaveFocus();
+    await user.keyboard('{Enter}');
+    expect(screen.getByText('Child 1')).toBeInTheDocument();
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  });
+
   it('renders group role for nested children', () => {
     render(<TreeList items={nestedItemsExpanded} />);
     const groups = document.querySelectorAll('[role="group"]');
@@ -210,18 +268,14 @@ describe('TreeList', () => {
   it('fires onClick when invisible button is clicked', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();
-    const items: TreeListItemData[] = [
-      {id: 'a', label: 'Clickable', onClick},
-    ];
+    const items: TreeListItemData[] = [{id: 'a', label: 'Clickable', onClick}];
     render(<TreeList items={items} />);
     await user.click(screen.getByRole('button'));
     expect(onClick).toHaveBeenCalledTimes(1);
   });
 
   it('renders an invisible anchor when href is provided', () => {
-    const items: TreeListItemData[] = [
-      {id: 'a', label: 'Link', href: '/docs'},
-    ];
+    const items: TreeListItemData[] = [{id: 'a', label: 'Link', href: '/docs'}];
     const {container} = render(<TreeList items={items} />);
     const anchor = container.querySelector('a');
     expect(anchor).toBeInTheDocument();
@@ -317,4 +371,239 @@ describe('TreeList', () => {
     const root = screen.getByTestId('tree');
     expect(root.className).toContain('astryx-tree-list');
   });
+
+  // ===========================================================================
+  // APG structural ARIA (aria-level / aria-posinset / aria-setsize)
+  // ===========================================================================
+
+  it('sets aria-level, aria-posinset, and aria-setsize at the top level', () => {
+    render(<TreeList items={flatItems} />);
+    const apple = screen.getByText('Apple').closest('li');
+    expect(apple).toHaveAttribute('aria-level', '1');
+    expect(apple).toHaveAttribute('aria-posinset', '1');
+    expect(apple).toHaveAttribute('aria-setsize', '3');
+
+    const cherry = screen.getByText('Cherry').closest('li');
+    expect(cherry).toHaveAttribute('aria-posinset', '3');
+    expect(cherry).toHaveAttribute('aria-setsize', '3');
+  });
+
+  it('sets aria-level/posinset/setsize correctly at deeper levels', () => {
+    render(<TreeList items={expandedParentItems} />);
+    const parent = screen.getByText('Parent').closest('li');
+    expect(parent).toHaveAttribute('aria-level', '1');
+    expect(parent).toHaveAttribute('aria-setsize', '2');
+
+    const child1 = screen.getByText('Child 1').closest('li');
+    expect(child1).toHaveAttribute('aria-level', '2');
+    expect(child1).toHaveAttribute('aria-posinset', '1');
+    expect(child1).toHaveAttribute('aria-setsize', '2');
+
+    const child2 = screen.getByText('Child 2').closest('li');
+    expect(child2).toHaveAttribute('aria-level', '2');
+    expect(child2).toHaveAttribute('aria-posinset', '2');
+  });
+
+  it('sets aria-level across three depths', () => {
+    render(<TreeList items={deepItems} />);
+    expect(screen.getByText('Root').closest('li')).toHaveAttribute(
+      'aria-level',
+      '1',
+    );
+    expect(screen.getByText('Mid').closest('li')).toHaveAttribute(
+      'aria-level',
+      '2',
+    );
+    expect(screen.getByText('Leaf').closest('li')).toHaveAttribute(
+      'aria-level',
+      '3',
+    );
+  });
+
+  // ===========================================================================
+  // Roving tabindex
+  // ===========================================================================
+
+  it('makes exactly one treeitem tabbable by default (the first enabled)', () => {
+    render(<TreeList items={flatItems} />);
+    const treeitems = screen.getAllByRole('treeitem');
+    const tabbable = treeitems.filter(
+      el => el.getAttribute('tabindex') === '0',
+    );
+    expect(tabbable).toHaveLength(1);
+    expect(tabbable[0]).toBe(screen.getByText('Apple').closest('li'));
+    expect(screen.getByText('Banana').closest('li')).toHaveAttribute(
+      'tabindex',
+      '-1',
+    );
+  });
+
+  it('defaults the tab stop to the selected item when one is selected', () => {
+    const items: TreeListItemData[] = [
+      {id: 'a', label: 'Apple'},
+      {id: 'b', label: 'Banana', isSelected: true},
+      {id: 'c', label: 'Cherry'},
+    ];
+    render(<TreeList items={items} />);
+    expect(screen.getByText('Banana').closest('li')).toHaveAttribute(
+      'tabindex',
+      '0',
+    );
+    expect(screen.getByText('Apple').closest('li')).toHaveAttribute(
+      'tabindex',
+      '-1',
+    );
+  });
+
+  it('moves the single tab stop when focus moves via keyboard', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={flatItems} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('{ArrowDown}');
+    const treeitems = screen.getAllByRole('treeitem');
+    const tabbable = treeitems.filter(
+      el => el.getAttribute('tabindex') === '0',
+    );
+    expect(tabbable).toHaveLength(1);
+    expect(tabbable[0]).toBe(screen.getByText('Banana').closest('li'));
+  });
+
+  // ===========================================================================
+  // APG keyboard navigation
+  // ===========================================================================
+
+  it('ArrowDown / ArrowUp move focus between visible treeitems', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={flatItems} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('{ArrowDown}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Banana').closest('li'),
+    );
+    await user.keyboard('{ArrowDown}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Cherry').closest('li'),
+    );
+    await user.keyboard('{ArrowUp}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Banana').closest('li'),
+    );
+  });
+
+  it('ArrowDown / ArrowUp skip disabled treeitems', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={withDisabledItems} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('{ArrowDown}');
+    // Banana is disabled → skipped, lands on Cherry.
+    expect(document.activeElement).toBe(
+      screen.getByText('Cherry').closest('li'),
+    );
+    await user.keyboard('{ArrowUp}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Apple').closest('li'),
+    );
+  });
+
+  it('ArrowRight expands a collapsed parent, then enters the first child', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={collapsedParentItems} />);
+    const parent = screen.getByText('Parent').closest('li')!;
+    parent.focus();
+    expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+    await user.keyboard('{ArrowRight}');
+    // First ArrowRight expands.
+    expect(screen.getByText('Child 1')).toBeInTheDocument();
+    expect(document.activeElement).toBe(parent);
+    await user.keyboard('{ArrowRight}');
+    // Second ArrowRight moves into first child.
+    expect(document.activeElement).toBe(
+      screen.getByText('Child 1').closest('li'),
+    );
+  });
+
+  it('ArrowRight on a leaf is a no-op', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={flatItems} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('{ArrowRight}');
+    expect(document.activeElement).toBe(apple);
+  });
+
+  it('ArrowLeft collapses an expanded parent, then moves to parent', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={expandedParentItems} />);
+    const parent = screen.getByText('Parent').closest('li')!;
+    // Focus a child first.
+    const child1 = screen.getByText('Child 1').closest('li')!;
+    child1.focus();
+    await user.keyboard('{ArrowLeft}');
+    // Child is a leaf → ArrowLeft moves to parent.
+    expect(document.activeElement).toBe(parent);
+    await user.keyboard('{ArrowLeft}');
+    // Parent is expanded → ArrowLeft collapses it.
+    expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+  });
+
+  it('Home and End move to the first and last visible treeitems', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={flatItems} />);
+    const banana = screen.getByText('Banana').closest('li')!;
+    banana.focus();
+    await user.keyboard('{End}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Cherry').closest('li'),
+    );
+    await user.keyboard('{Home}');
+    expect(document.activeElement).toBe(
+      screen.getByText('Apple').closest('li'),
+    );
+  });
+
+  it('Enter activates the item onClick', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    const items: TreeListItemData[] = [{id: 'a', label: 'Apple', onClick}];
+    render(<TreeList items={items} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('{Enter}');
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('Space activates the item onClick', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    const items: TreeListItemData[] = [{id: 'a', label: 'Apple', onClick}];
+    render(<TreeList items={items} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard(' ');
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('Enter toggles expansion for a parent without its own action', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={collapsedParentItems} />);
+    const parent = screen.getByText('Parent').closest('li')!;
+    parent.focus();
+    expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+    await user.keyboard('{Enter}');
+    expect(screen.getByText('Child 1')).toBeInTheDocument();
+  });
+
+  it('typeahead moves focus to the next item matching typed characters', async () => {
+    const user = userEvent.setup();
+    render(<TreeList items={flatItems} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('c');
+    expect(document.activeElement).toBe(
+      screen.getByText('Cherry').closest('li'),
+    );
+  });
 });

package/src/TreeList/TreeList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TreeList.tsx
- * @input Uses React, StyleX, theme tokens, TreeListItem, TreeListTypes
+ * @input Uses React, StyleX, theme tokens, TreeListItem, TreeListTypes, useTreeFocus
  * @output Exports TreeList component, TreeListProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -23,6 +23,7 @@ import type {BaseProps} from '../BaseProps';
 import {TreeListItem} from './TreeListItem';
 import type {TreeListItemData, TreeListDensity} from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
+import {useTreeFocus} from '../hooks/useTreeFocus';
 
 // =============================================================================
 // Types
@@ -97,6 +98,35 @@ function collectExpandedKeys(items: TreeListItemData[]): string[] {
   return keys;
 }
 
+/**
+ * Compute the initial roving-tabindex seed: the first selected enabled item in
+ * document order, else the first enabled item, else the first item. The hook
+ * (useTreeFocus with hasRovingTabIndex) takes ownership after mount — it
+ * preserves this seeded `tabindex="0"` on its repair pass and moves the stop
+ * with keyboard navigation.
+ */
+function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
+  let firstEnabled: string | undefined;
+  const walk = (list: TreeListItemData[]): string | undefined => {
+    for (const item of list) {
+      if (item.isSelected && item.isDisabled !== true) {
+        return item.id;
+      }
+      if (firstEnabled == null && item.isDisabled !== true) {
+        firstEnabled = item.id;
+      }
+      if (item.children != null && item.children.length > 0) {
+        const selected = walk(item.children);
+        if (selected != null) {
+          return selected;
+        }
+      }
+    }
+    return undefined;
+  };
+  return walk(items) ?? firstEnabled ?? items[0]?.id;
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -160,6 +190,42 @@ export function TreeList({
     [expandedKeysFromProps],
   );
 
+  // ---------------------------------------------------------------------------
+  // Roving tabindex + APG tree keyboard model (via useTreeFocus)
+  // ---------------------------------------------------------------------------
+
+  // The hook (hasRovingTabIndex) owns the tree's single tab stop: it repairs
+  // the stop on mount and moves it with keyboard navigation. We only seed the
+  // initially-tabbable treeitem in the render (selected item or first enabled);
+  // the hook's repair pass preserves that seeded `tabindex="0"`.
+  const initialTabbableId = useMemo(
+    () => findInitialTabbableId(items),
+    [items],
+  );
+
+  // Enter/Space activation: prefer the treeitem's own inner action (link or
+  // button); return true when handled so the hook does not also toggle. Scoped
+  // to this treeitem's own row — never a descendant treeitem's action inside an
+  // expanded group.
+  const activateItem = useCallback((current: HTMLElement): boolean => {
+    const candidates = current.querySelectorAll<HTMLElement>(
+      'a[href], button:not([aria-label="Toggle children"])',
+    );
+    for (const candidate of candidates) {
+      if (candidate.closest('[role="treeitem"]') === current) {
+        candidate.click();
+        return true;
+      }
+    }
+    return false;
+  }, []);
+
+  const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
+    onToggleExpand: handleToggle,
+    onActivate: activateItem,
+    hasRovingTabIndex: true,
+  });
+
   function renderItems(
     items: TreeListItemData[],
     nestedLevel: number,
@@ -206,6 +272,9 @@ export function TreeList({
           onToggle={handleToggle}
           density={density}
           renderedChildren={renderedChildren}
+          posInSet={index + 1}
+          setSize={items.length}
+          isTabbable={item.id === initialTabbableId}
         />
       );
     });
@@ -227,8 +296,11 @@ export function TreeList({
         </div>
       )}
       <ul
+        ref={treeRef}
         role="tree"
         aria-labelledby={header != null ? headerId : undefined}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
         {...stylex.props(styles.list)}>
         {renderItems(items, 0, [])}
       </ul>