@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/TopNav/TopNavMenu.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When TopNavMenu changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {TopNavMenu} from './TopNavMenu';
 
 const mockItems = [
@@ -32,10 +33,13 @@ describe('TopNavMenu', () => {
     expect(screen.getByRole('button', {name: 'Products'})).toBeInTheDocument();
   });
 
-  it('trigger has aria-haspopup attribute', () => {
+  it('trigger announces a menu popup, not a dialog', () => {
     render(<TopNavMenu label="Products" items={mockItems} />);
     const trigger = screen.getByRole('button', {name: 'Products'});
-    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    // usePopover with role:'none' emits aria-haspopup="true" (the ARIA
+    // synonym for "menu") because the exposed semantics of the popup are its
+    // child role="menu", not a dialog.
+    expect(trigger).toHaveAttribute('aria-haspopup', 'true');
   });
 
   it('renders with custom items', () => {
@@ -57,3 +61,113 @@ describe('TopNavMenu', () => {
     expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();
   });
 });
+
+describe('menu semantics (APG)', () => {
+  it('does not wrap the popup in a role="dialog" / aria-modal shell', () => {
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    // The popup's exposed semantics are the role="menu" container itself —
+    // no dialog wrapper, no aria-modal.
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-modal]')).toBeNull();
+    expect(
+      screen.getByRole('menu', {name: 'Products', hidden: true}),
+    ).toBeInTheDocument();
+  });
+});
+
+describe('keyboard navigation (APG menu pattern)', () => {
+  it('exposes exactly one tab stop among menu items (roving tabindex)', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+    expect(items).toHaveLength(2);
+    const tabbable = items.filter(el => el.getAttribute('tabindex') === '0');
+    expect(tabbable).toHaveLength(1);
+  });
+
+  it('moves focus with ArrowDown/ArrowUp and the tab stop follows', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+    items[0].focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(items[1]).toHaveFocus();
+    expect(items[1]).toHaveAttribute('tabindex', '0');
+    expect(items[0]).toHaveAttribute('tabindex', '-1');
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(items[0]).toHaveFocus();
+    expect(items[0]).toHaveAttribute('tabindex', '0');
+    expect(items[1]).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('wraps focus at both ends', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    const items = screen.getAllByRole('menuitem', {hidden: true});
+
+    items[1].focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(items[0]).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    expect(items[1]).toHaveFocus();
+  });
+
+  it('typeahead moves focus to the item matching the typed character', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'm'});
+    expect(
+      screen.getByRole('menuitem', {name: /Messaging/, hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused onClick-only item with Enter', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<TopNavMenu label="Menu" items={[{title: 'Action', onClick}]} />);
+    await user.click(screen.getByRole('button', {name: 'Menu'}));
+
+    const item = screen.getByRole('menuitem', {hidden: true});
+    item.focus();
+    fireEvent.keyDown(item, {key: 'Enter'});
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('still activates an item on click', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<TopNavMenu label="Menu" items={[{title: 'Action', onClick}]} />);
+    await user.click(screen.getByRole('button', {name: 'Menu'}));
+
+    await user.click(screen.getByRole('menuitem', {hidden: true}));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('closes the menu with Escape', async () => {
+    const user = userEvent.setup();
+    render(<TopNavMenu label="Products" items={mockItems} />);
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Escape'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file TopNavMenu.tsx
- * @input Uses React, StyleX, useHoverCard, TopNavItem tokens
+ * @input Uses React, StyleX, usePopover, useMenuHover, useListFocus,
+ *   useTypeahead, TopNavItem tokens
  * @output Exports TopNavMenu component and related types
  * @position Navigation item with hover-triggered overflow menu for TopNav
  *
@@ -15,10 +16,18 @@
  * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
-import React, {useId, useRef, useState, type ReactNode} from 'react';
+import React, {
+  useCallback,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
+import {useListFocus} from '../hooks/useListFocus';
+import {useTypeahead} from '../hooks/useTypeahead';
 import {getIcon} from '../Icon/globalIconRegistry';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -332,7 +341,10 @@ export function TopNavMenu({
   const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
 
   const popover = usePopover({
-    dialogLabel: label,
+    // The popup's own role="menu" is the exposed semantics; a modal dialog
+    // wrapper would announce an unnamed dialog around the menu and make the
+    // trigger claim aria-haspopup="dialog" for menu content (see TabMenu).
+    role: 'none',
     xstyle: styles.menuOffset,
   });
 
@@ -353,6 +365,65 @@ export function TopNavMenu({
     ref,
   );
 
+  // The desktop popup is a composite menu widget per the APG menu pattern:
+  // a single roving tab stop with ArrowUp/ArrowDown traversal (wrapping),
+  // Home/End, and first-character typeahead. The hook owns item tabindex —
+  // items render tabIndex={-1} and exactly one is promoted to 0. The
+  // composition mirrors NavHeadingMenu.
+  const {listRef, handleKeyDown, handleFocus, focusItem} =
+    useListFocus<HTMLDivElement>({
+      itemSelector: '[role="menuitem"]',
+      hasRovingTabIndex: true,
+      onEscape: popover.hide,
+    });
+
+  // First-character typeahead over the menu items (menus-11).
+  const getMenuItems = useCallback(
+    (): HTMLElement[] =>
+      listRef.current
+        ? Array.from(
+            listRef.current.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+          )
+        : [],
+    [listRef],
+  );
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () =>
+      getMenuItems().findIndex(
+        el =>
+          el === document.activeElement || el.contains(document.activeElement),
+      ),
+  });
+
+  // Extend useListFocus with Enter/Space activation. Items rendered without an
+  // `href` are `<div role="menuitem">` elements, which have no native keyboard
+  // activation — without this, Enter/Space on a focused onClick-only item does
+  // nothing. Anchor items (with `href`) already activate on Enter natively.
+  const menuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        const focused = document.activeElement as HTMLElement | null;
+        if (focused?.getAttribute('role') === 'menuitem') {
+          e.preventDefault();
+          focused.click();
+          return;
+        }
+      }
+      if (typeahead.onKeyDown(e)) {
+        e.preventDefault();
+        return;
+      }
+      handleKeyDown(e);
+    },
+    [handleKeyDown, typeahead],
+  );
+
+  // Menu container carries both the hover hook's ref (for its open/close
+  // focus management) and the list-focus ref (for roving tabindex/typeahead).
+  const setMenuRef = mergeRefs<HTMLDivElement>(menuRef, listRef);
+
   // Mobile bar: hide menus entirely
   if (renderMode === 'mobile-bar') {
     return null;
@@ -437,10 +508,15 @@ export function TopNavMenu({
       </button>
       {popover.render(
         <div
-          ref={menuRef}
+          ref={setMenuRef}
           role="menu"
           aria-label={label}
           {...contentProps}
+          // After the contentProps spread so the full APG composition (roving
+          // tabindex + typeahead + Enter/Space activation) replaces the hover
+          // hook's basic arrow-key handler.
+          onKeyDown={menuKeyDown}
+          onFocus={handleFocus}
           {...stylex.props(styles.menuContainer)}>
           {items.map(item => {
             const Element = item.href ? 'a' : 'div';
@@ -448,7 +524,9 @@ export function TopNavMenu({
               <Element
                 key={getMenuItemKey(item)}
                 role="menuitem"
-                tabIndex={popover.isOpen ? 0 : -1}
+                // Single tab stop: useListFocus owns the roving tabindex and
+                // promotes exactly one item to 0.
+                tabIndex={-1}
                 href={item.href}
                 onClick={item.onClick}
                 {...stylex.props(styles.menuItem)}>

package/src/TreeList/TreeList.doc.mjs

@@ -26,6 +26,12 @@ export const docs = {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
       {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-chevron', states: ['state']},
+      {className: 'astryx-tree-list-item-label', states: ['selected']},
+      {className: 'astryx-tree-list-guide'},
+    ],
+    vars: [
+      {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
     ],
   },
   components: [
@@ -47,6 +53,13 @@ export const docs = {
           description: 'Spacing density for items.',
           default: "'balanced'",
         },
+        {
+          name: 'variant',
+          type: "'lineGuides' | 'noGuides'",
+          description:
+            'Visual treatment of the hierarchy guide lines. lineGuides shows connector lines; noGuides hides them, keeping indentation. Orthogonal to density.',
+          default: "'lineGuides'",
+        },
         {
           name: 'header',
           type: 'ReactNode',
@@ -90,6 +103,12 @@ export const docsZh = {
     targets: [
       {className: 'astryx-tree-list', visualProps: ['density']},
       {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
+      {className: 'astryx-tree-list-chevron', states: ['state']},
+      {className: 'astryx-tree-list-item-label', states: ['selected']},
+      {className: 'astryx-tree-list-guide'},
+    ],
+    vars: [
+      {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。', default: 'var(--spacing-4)'},
     ],
   },
   components: [
@@ -112,6 +131,13 @@ export const docsZh = {
           description: '项目的间距密度。',
           default: "'balanced'",
         },
+        {
+          name: 'variant',
+          type: "'lineGuides' | 'noGuides'",
+          description:
+            '层级引导线的视觉呈现。lineGuides 显示连接线；noGuides 隐藏连接线并保留缩进。与 density 正交。',
+          default: "'lineGuides'",
+        },
         {
           name: 'header',
           type: 'ReactNode',
@@ -156,6 +182,7 @@ export const docsDense = {
   propDescriptions: {
     items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
     density: 'Spacing density for items.',
+    variant: 'Guide-line treatment: lineGuides shows connectors, noGuides hides them (indent kept). Orthogonal to density.',
     header: 'Header content, linked to tree via aria-labelledby.',
     xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
   },
@@ -167,6 +194,7 @@ export const docsDense = {
       propDescriptions: {
         items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
         density: 'Spacing density for items.',
+        variant: 'Guide-line treatment: lineGuides shows connectors, noGuides hides them (indent kept). Orthogonal to density.',
         header: 'Header content, linked to tree via aria-labelledby.',
         xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
       },

package/src/TreeList/TreeList.test.tsx

@@ -14,6 +14,8 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 const simpleItems: TreeListItemData[] = [
   {id: 'a', label: 'Item A'},
@@ -393,6 +395,155 @@ describe('TreeList', () => {
     expect(screen.getByRole('tree')).toBeInTheDocument();
   });
 
+  // ===========================================================================
+  // Variant (guide lines)
+  // ===========================================================================
+
+  describe('variant', () => {
+    it('renders guide lines by default', () => {
+      const {container} = render(<TreeList items={nestedItemsExpanded} />);
+      expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+    });
+
+    it("variant='lineGuides' renders guide lines (explicit == default)", () => {
+      const {container} = render(
+        <TreeList items={nestedItemsExpanded} variant="lineGuides" />,
+      );
+      expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+    });
+
+    it("variant='noGuides' renders NO guide lines", () => {
+      const {container} = render(
+        <TreeList items={nestedItemsExpanded} variant="noGuides" />,
+      );
+      expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+    });
+
+    it("variant='noGuides' preserves the tree structure and items", () => {
+      render(<TreeList items={nestedItemsExpanded} variant="noGuides" />);
+      // Rows, roles, and nesting are all intact — only the connectors are gone.
+      expect(screen.getByRole('tree')).toBeInTheDocument();
+      expect(screen.getAllByRole('treeitem')).toHaveLength(4);
+      expect(screen.getByText('Parent')).toBeInTheDocument();
+      expect(screen.getByText('Child 1')).toBeInTheDocument();
+      expect(screen.getByText('Child 2')).toBeInTheDocument();
+      expect(screen.getByText('Sibling')).toBeInTheDocument();
+    });
+
+    it("variant='noGuides' preserves per-level indentation on the rows", () => {
+      // Indentation lives on the row's margin-inline-start (not the guide
+      // element), so it must survive when the connectors are suppressed. The
+      // per-row distance is published as the `--_tree-indent` custom property
+      // (not an inline longhand — see #4308), so the theme layer can override
+      // the `margin-inline-start` declaration. A deeper row is indented more
+      // than a shallower one.
+      const {container} = render(
+        <TreeList items={deepItems} variant="noGuides" />,
+      );
+      const indentOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="--_tree-indent"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      // Guides are gone…
+      expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+      // …but each level still publishes an indent distance, and the level
+      // multiplier grows with depth (0, 1, 2).
+      expect(indentOf('Root')).toContain('--_tree-indent');
+      expect(indentOf('Mid')).toContain('--_tree-indent');
+      expect(indentOf('Leaf')).toContain('--_tree-indent');
+      const level = (text: string): number => {
+        const m = /calc\((\d+)/.exec(indentOf(text));
+        return m ? Number(m[1]) : NaN;
+      };
+      expect(level('Mid')).toBeGreaterThan(level('Root'));
+      expect(level('Leaf')).toBeGreaterThan(level('Mid'));
+    });
+  });
+
+  // ===========================================================================
+  // Guide theme target
+  // ===========================================================================
+
+  describe('guide theme target', () => {
+    it('renders the astryx-tree-list-guide target on the connector lines', () => {
+      const {container} = render(<TreeList items={nestedItemsExpanded} />);
+      const guide = container.querySelector('.astryx-tree-list-guide');
+      // A dedicated, stable target so a theme can recolor or hide the guides
+      // without hiding the built-in connectors and reimplementing them.
+      expect(guide).not.toBeNull();
+    });
+
+    it('exposes tree-list-guide as a themeable defineTheme target', () => {
+      // jsdom cannot resolve the @layer cascade, so the generated CSS is what
+      // proves a theme override reaches the guide element.
+      const theme = defineTheme({
+        name: 'tree-list-guide-test',
+        components: {
+          'tree-list-guide': {
+            base: {backgroundColor: 'var(--color-accent)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-guide {');
+      expect(css).toContain('background-color: var(--color-accent)');
+    });
+
+    it('lets a theme hide the guides via display: none on the target', () => {
+      // Hiding the guides is done through the theme target, not a prop — the
+      // theme rule lands in @layer astryx-theme, above StyleX's base layer.
+      const theme = defineTheme({
+        name: 'tree-list-guide-hidden-test',
+        components: {
+          'tree-list-guide': {
+            base: {display: 'none'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-guide {');
+      expect(css).toContain('display: none');
+    });
+  });
+
+  // ===========================================================================
+  // Indent lever (--tree-list-indent)
+  // ===========================================================================
+
+  describe('indent lever', () => {
+    it('lets a theme retune the indent step via the tree-list target', () => {
+      // The per-level step is a public, themeable var (default --spacing-4) set
+      // on the tree-list root, so a theme can retune the indent metric (e.g. to
+      // --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
+      // so the generated CSS is what proves the override reaches the lever.
+      const theme = defineTheme({
+        name: 'tree-list-indent-test',
+        components: {
+          'tree-list': {
+            base: {'--tree-list-indent': 'var(--spacing-5)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list {');
+      expect(css).toContain('--tree-list-indent: var(--spacing-5)');
+    });
+
+    it('rows consume the indent step in their published indent distance', () => {
+      // Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
+      // so retuning the step scales every level uniformly.
+      render(<TreeList items={deepItems} variant="noGuides" />);
+      const indentOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="--_tree-indent"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
+      expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
+    });
+  });
+
   // ===========================================================================
   // xds class name
   // ===========================================================================
@@ -403,6 +554,127 @@ describe('TreeList', () => {
     expect(root.className).toContain('astryx-tree-list');
   });
 
+  // ===========================================================================
+  // Chevron theme target
+  // ===========================================================================
+
+  describe('chevron theme target', () => {
+    it('renders the astryx-tree-list-chevron target on the toggle button', () => {
+      render(<TreeList items={nestedItems} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+
+      // Dedicated, stable theme target on the expand/collapse control, so a
+      // theme can restyle the chevron without a fragile [data-tree-toggle] hook.
+      expect(toggle).toHaveClass('astryx-tree-list-chevron');
+      // Open/closed state is reflected so a theme can target each state alone.
+      expect(toggle).toHaveAttribute('data-state', 'collapsed');
+    });
+
+    it('reflects the expanded state on the toggle when open', () => {
+      render(<TreeList items={nestedItemsExpanded} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+
+      expect(toggle).toHaveClass('astryx-tree-list-chevron');
+      expect(toggle).toHaveAttribute('data-state', 'expanded');
+    });
+
+    it('keeps the functional data-tree-toggle hook alongside the new target', () => {
+      // The theme target is additive — the toggle is still a real <button> and
+      // still carries the functional activation attribute TreeList relies on.
+      render(<TreeList items={nestedItems} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+      expect(toggle.tagName).toBe('BUTTON');
+      expect(toggle).toHaveAttribute('data-tree-toggle');
+    });
+
+    it('exposes tree-list-chevron as a themeable defineTheme target', () => {
+      // The generated CSS is what proves the target is reachable by a theme:
+      // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+      // above and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'tree-list-chevron-test',
+        components: {
+          'tree-list-chevron': {
+            base: {color: 'var(--color-accent)'},
+            'state:expanded': {color: 'var(--color-text-primary)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-chevron {');
+      expect(css).toContain('color: var(--color-accent)');
+      expect(css).toContain('.astryx-tree-list-chevron.expanded');
+      expect(css).toContain('color: var(--color-text-primary)');
+    });
+  });
+
+  // ===========================================================================
+  // Item label theme target
+  // ===========================================================================
+
+  describe('item label theme target', () => {
+    it('renders the astryx-tree-list-item-label target on the label span', () => {
+      render(<TreeList items={simpleItems} />);
+      const label = screen.getByText('Item A');
+
+      // Dedicated, stable theme target on the label text, so a theme can style
+      // just the label without a fragile `button:not([data-tree-toggle]) > span`
+      // structural selector.
+      expect(label).toHaveClass('astryx-tree-list-item-label');
+      // A non-selected item's label carries no selected reflection.
+      expect(label).not.toHaveAttribute('data-selected');
+    });
+
+    it('reflects the selected state on the selected item label', () => {
+      render(
+        <TreeList items={[{id: 'a', label: 'Item A', isSelected: true}]} />,
+      );
+      const label = screen.getByText('Item A');
+      expect(label).toHaveClass('astryx-tree-list-item-label');
+      expect(label).toHaveAttribute('data-selected', 'selected');
+    });
+
+    it('keeps the label linked to its row via aria-labelledby', () => {
+      // The theme target is additive — the label still owns the id the
+      // interactive row references for its accessible name.
+      render(
+        <TreeList items={[{id: 'a', label: 'Item A', onClick: () => {}}]} />,
+      );
+      const label = screen.getByText('Item A');
+      const action = screen.getByRole('button');
+      expect(action).toHaveAttribute('aria-labelledby', label.id);
+    });
+
+    it('exposes tree-list-item-label as a themeable defineTheme target', () => {
+      // The generated CSS is what proves the target is reachable by a theme:
+      // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+      // above and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'tree-list-item-label-test',
+        components: {
+          'tree-list-item-label': {
+            base: {color: 'var(--color-text-primary)'},
+            selected: {fontWeight: 'var(--font-weight-bold)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-item-label {');
+      expect(css).toContain('color: var(--color-text-primary)');
+      expect(css).toContain('.astryx-tree-list-item-label.selected');
+      expect(css).toContain('font-weight: var(--font-weight-bold)');
+    });
+  });
+
   // ===========================================================================
   // APG structural ARIA (aria-level / aria-posinset / aria-setsize)
   // ===========================================================================