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

package/src/TopNav/TopNav.test.tsx

@@ -200,6 +200,56 @@ describe('TopNavHeading', () => {
     expect(screen.getByTestId('logo')).toBeInTheDocument();
   });
 
+  describe('logo link accessible name', () => {
+    const logo = <img src="/logo.png" alt="" />;
+
+    // A logo image is decorative; when the logo is wrapped in a link the link
+    // itself needs an accessible name, otherwise axe reports link-name.
+    it('names the logo link in the independent-links config', () => {
+      render(
+        <TopNavHeading
+          logo={logo}
+          superheading="Suite"
+          superheadingHref="/suite"
+          heading="Product"
+          headingHref="/product"
+        />,
+      );
+      // No link should have an empty accessible name.
+      for (const link of screen.getAllByRole('link')) {
+        expect(link).toHaveAccessibleName();
+      }
+      // The logo link is named from the heading.
+      expect(
+        screen.getAllByRole('link', {name: 'Product'}).length,
+      ).toBeGreaterThanOrEqual(1);
+    });
+
+    it('names the logo link in the menu + hrefs config', () => {
+      render(
+        <TopNavHeading
+          logo={logo}
+          superheading="Suite"
+          superheadingHref="/suite"
+          heading="Product"
+          headingHref="/product"
+          menu={<a href="#menu">Menu item</a>}
+        />,
+      );
+      for (const link of screen.getAllByRole('link')) {
+        expect(link).toHaveAccessibleName();
+      }
+    });
+
+    it('names a logo-only link via logoLabel', () => {
+      render(<TopNavHeading logo={logo} headingHref="/home" logoLabel="Home" />);
+      expect(screen.getByRole('link', {name: 'Home'})).toHaveAttribute(
+        'href',
+        '/home',
+      );
+    });
+  });
+
   it('renders as anchor when href is provided', () => {
     render(<TopNavHeading heading="Home" href="/" />);
     const link = screen.getByRole('link');

package/src/TopNav/TopNavHeading.tsx

@@ -214,6 +214,12 @@ export interface TopNavHeadingProps extends BaseProps<HTMLElement> {
    * Can be an image, NavIcon, or any ReactNode.
    */
   logo?: ReactNode;
+  /**
+   * Accessible name for the logo when it links somewhere (`headingHref`) and
+   * has no adjacent text to name it (for example a logo-only heading). Defaults
+   * to `heading` when available. Ignored when the logo is not a link.
+   */
+  logoLabel?: string;
   /**
    * Product/app name.
    */
@@ -295,6 +301,7 @@ export interface TopNavHeadingProps extends BaseProps<HTMLElement> {
 export function TopNavHeading({
   as,
   logo,
+  logoLabel,
   heading,
   headingHref: headingHrefProp,
   href,
@@ -314,6 +321,10 @@ export function TopNavHeading({
   const LinkComponent = useLinkComponent(as);
   // Support both headingHref and legacy href
   const headingHref = headingHrefProp ?? href;
+  // When the logo is wrapped in a link it needs its own accessible name (the
+  // logo image itself is decorative). Prefer an explicit logoLabel, fall back
+  // to the heading text. axe: link-name.
+  const logoLinkLabel = logoLabel ?? heading;
 
   const rootRef = useRef<HTMLElement>(null);
 
@@ -425,6 +436,7 @@ export function TopNavHeading({
       <Element
         ref={ref as React.Ref<HTMLAnchorElement & HTMLDivElement>}
         href={headingHref}
+        aria-label={headingHref ? logoLabel : undefined}
         data-testid={testId}
         {...mergeProps(
           themeProps('top-nav-heading'),
@@ -533,6 +545,7 @@ export function TopNavHeading({
             (headingHref ? (
               <LinkComponent
                 href={headingHref}
+                aria-label={logoLinkLabel}
                 onClick={(e: React.MouseEvent) => e.stopPropagation()}
                 {...stylex.props(styles.logo)}>
                 {logo}
@@ -593,7 +606,10 @@ export function TopNavHeading({
         {...props}>
         {logo &&
           (headingHref ? (
-            <LinkComponent href={headingHref} {...stylex.props(styles.logo)}>
+            <LinkComponent
+              href={headingHref}
+              aria-label={logoLinkLabel}
+              {...stylex.props(styles.logo)}>
               {logo}
             </LinkComponent>
           ) : (

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>