@astryxdesign/core 0.1.8 → 0.1.9

package/src/TopNav/TopNavHeading.tsx

@@ -332,6 +332,10 @@ export function TopNavHeading({
 
   const popover = usePopover({
     dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
+    // The popup exposes its own role="menu" semantics; a role="dialog"
+    // aria-modal wrapper would announce "dialog, Navigation menu" around a
+    // menu (the anti-pattern removed in a478a3dcf).
+    role: 'none',
     hasCloseButton: false,
   });
 
@@ -511,13 +515,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',
@@ -575,13 +585,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNavMegaMenu} from './TopNavMegaMenu';
@@ -75,6 +75,154 @@ describe('TopNavMegaMenu — default mode', () => {
   });
 });
 
+// =============================================================================
+// Popup semantics (default mode)
+// =============================================================================
+
+describe('TopNavMegaMenu — popup semantics', () => {
+  // Mock the Popover API (not implemented in jsdom).
+  const originalMatches = HTMLElement.prototype.matches;
+
+  beforeAll(() => {
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('popover-open', '');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'open'});
+      this.dispatchEvent(event);
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('popover-open');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'closed'});
+      this.dispatchEvent(event);
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = function (
+      selector: string,
+    ): boolean {
+      if (selector === ':popover-open') {
+        return this.hasAttribute('popover-open');
+      }
+      return originalMatches.call(this, selector);
+    };
+  });
+
+  afterAll(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = originalMatches;
+  });
+
+  it('trigger aria-controls resolves to the popup element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    // aria-controls must be present and point at the real popup element.
+    const controlsId = trigger.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const popup = document.getElementById(controlsId as string);
+    expect(popup).not.toBeNull();
+
+    await user.click(trigger);
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    // The referenced element is the popup that contains the panel content.
+    expect(popup).toContainElement(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    );
+  });
+
+  it('does not wrap the panel in a role="dialog" aria-modal element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Focus stays on the trigger while the panel is open, so a modal dialog
+    // wrapper would tell assistive tech the focused control is inert.
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+  });
+
+  it('does not expose role="menu" — a link grid is not an ARIA menu', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Per the WAI-ARIA APG, mega menu panels of navigation links must not use
+    // the menu role (reserved for action menus with menuitem children).
+    expect(screen.queryByRole('menu', {hidden: true})).not.toBeInTheDocument();
+    expect(screen.queryAllByRole('menuitem', {hidden: true})).toHaveLength(0);
+  });
+
+  it('exposes the panel as a labeled group', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    expect(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps item links with accessible names inside the panel', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const analytics = screen.getByRole('link', {
+      name: /Analytics/,
+      hidden: true,
+    });
+    expect(analytics).toHaveAttribute('href', '/analytics');
+    expect(
+      screen.getByRole('link', {name: /Reports/, hidden: true}),
+    ).toHaveAttribute('href', '/reports');
+  });
+});
+
 // =============================================================================
 // Mobile-bar mode — should be hidden
 // =============================================================================

package/src/TopNav/TopNavMegaMenu.tsx

@@ -354,7 +354,11 @@ function DefaultMegaMenu({
   }, [onOpenChange]);
 
   const popover = usePopover({
-    dialogLabel: label,
+    // role: 'none' — the panel exposes its own role="group" labeled by
+    // `label`. Focus stays on the trigger while the panel is open, so a
+    // role="dialog" aria-modal="true" wrapper would announce an unnamed
+    // modal dialog around a grid of links.
+    role: 'none',
     // hasSurface: false — mega menu provides its own surface (panelContainer)
     // with border-top and custom overflow. Animation is applied via the
     // render() call's xstyle prop (panelAnimation), not the hook options.
@@ -434,8 +438,7 @@ function DefaultMegaMenu({
       <button
         ref={mergeRefs(triggerButtonRef, ref)}
         type="button"
-        aria-haspopup="true"
-        aria-expanded={popover.isOpen}
+        {...popover.triggerProps}
         onClick={handleClick}
         onMouseEnter={handleMouseEnter}
         onMouseLeave={handleMouseLeave}
@@ -454,7 +457,10 @@ function DefaultMegaMenu({
       </button>
       {popover.render(
         <div
-          role="menu"
+          // role="group" — a mega menu is a browsing grid of links, not an
+          // ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is
+          // for action menus; link mega menus are the documented anti-case).
+          role="group"
           aria-label={label}
           onMouseEnter={handleMouseEnter}
           onMouseLeave={handleMouseLeave}

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: 'Alt text for the image.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) — usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
     },
     {
       name: 'linkLabel',
@@ -71,7 +71,7 @@ export const docsZh = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: '图片的替代文本。',
+      description: '图片的替代文本。省略时图片会被显式标记为装饰性（alt=""、role="presentation"、aria-hidden）——由于卡片已有可见标题，这通常是正确的。仅当图片传达标题和描述之外的信息时才提供。',
     },
     {
       name: 'linkLabel',
@@ -99,7 +99,7 @@ export const docsDense = {
     title: 'Card title.',
     description: 'Description below title.',
     image: 'Image URL above body.',
-    imageAlt: 'Image alt text.',
+    imageAlt: 'Image alt text. Omitted → explicitly decorative (hidden from screen readers); usually correct since card has visible title.',
     linkLabel: 'CTA link text.',
     linkHref: 'CTA link URL.',
     children: 'Custom content below standard body.',

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -84,7 +84,15 @@ export interface TopNavMegaMenuFeaturedCardProps extends BaseProps<HTMLDivElemen
   description?: string;
   /** Optional image URL displayed above the body. */
   image?: string;
-  /** Alt text for the image. */
+  /**
+   * Alt text for the image.
+   *
+   * When omitted, the image is explicitly decorative (`alt=""` +
+   * `role="presentation"` + `aria-hidden`, matching Avatar) and hidden from
+   * assistive technology. Since the card already has a visible `title`, a
+   * decorative image is usually correct; pass `imageAlt` only when the image
+   * conveys information beyond the title and description.
+   */
   imageAlt?: string;
   /** CTA link text. */
   linkLabel?: string;
@@ -149,7 +157,16 @@ export function TopNavMegaMenuFeaturedCard({
       )}
       {...rest}>
       {image && (
-        <img src={image} alt={imageAlt ?? ''} {...stylex.props(styles.image)} />
+        // Without `imageAlt`, the image is explicitly decorative rather than
+        // silently empty-alt, matching Avatar's handling of unnamed images.
+        // Usually correct here: the card already has a visible title.
+        <img
+          src={image}
+          alt={imageAlt ?? ''}
+          role={imageAlt ? undefined : 'presentation'}
+          aria-hidden={imageAlt ? undefined : true}
+          {...stylex.props(styles.image)}
+        />
       )}
       <div {...stylex.props(styles.body)}>
         <span {...stylex.props(styles.title)}>{title}</span>

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,9 @@ 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'},
     ],
   },
   components: [
@@ -47,6 +50,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 +100,9 @@ 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'},
     ],
   },
   components: [
@@ -112,6 +125,13 @@ export const docsZh = {
           description: '项目的间距密度。',
           default: "'balanced'",
         },
+        {
+          name: 'variant',
+          type: "'lineGuides' | 'noGuides'",
+          description:
+            '层级引导线的视觉呈现。lineGuides 显示连接线；noGuides 隐藏连接线并保留缩进。与 density 正交。',
+          default: "'lineGuides'",
+        },
         {
           name: 'header',
           type: 'ReactNode',
@@ -156,6 +176,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 +188,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.',
       },