@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/SideNav/SideNav.test.tsx

@@ -337,7 +337,9 @@ describe('SideNavHeading', () => {
   it('whole heading is popover trigger when menu provided without hrefs', () => {
     render(<SideNavHeading heading="My App" menu={<div>Menu</div>} />);
     const button = screen.getByRole('button');
-    expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+    // The popup is no longer a dialog (role: 'none' on usePopover), so the
+    // trigger advertises a generic popup rather than aria-haspopup="dialog".
+    expect(button).toHaveAttribute('aria-haspopup', 'true');
     expect(button).toHaveAttribute('aria-expanded', 'false');
   });
 
@@ -351,7 +353,7 @@ describe('SideNavHeading', () => {
     const button = screen.getByRole('button');
     // The trigger button uses aria attributes from usePopover and
     // an onClick handler from useMenuHover for click-to-lock toggle.
-    expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+    expect(button).toHaveAttribute('aria-haspopup', 'true');
     expect(button).toHaveAttribute('aria-expanded');
   });
 
@@ -364,13 +366,92 @@ describe('SideNavHeading', () => {
       />,
     );
     const button = screen.getByRole('button', {name: 'Open menu'});
-    expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+    expect(button).toHaveAttribute('aria-haspopup', 'true');
   });
 
   it('passes data-testid', () => {
     render(<SideNavHeading heading="My App" data-testid="nav-header" />);
     expect(screen.getByTestId('nav-header')).toBeInTheDocument();
   });
+
+  // ===========================================================================
+  // Menu popover semantics — the popup must not be announced as a modal
+  // dialog, and role="menu" must be scoped to the actual menu items so the
+  // heading button is not an invalid child of the menu.
+  // ===========================================================================
+
+  // The popover layer keeps `popover` content display:none in jsdom even
+  // when open, hiding it from role queries — so these tests assert the
+  // popup's ARIA semantics at the DOM level instead.
+  describe('menu popover semantics', () => {
+    const menuItems = (
+      <>
+        <div role="menuitem">Alpha</div>
+        <div role="menuitem">Beta</div>
+      </>
+    );
+
+    it('does not wrap the heading menu popup in a modal dialog', async () => {
+      const user = userEvent.setup();
+      render(<SideNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+    });
+
+    it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+      const user = userEvent.setup();
+      render(<SideNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'My App');
+      const children = Array.from(menu!.children);
+      expect(children.length).toBeGreaterThan(0);
+      for (const child of children) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+
+    it('keeps the popup heading button outside the menu and closes on click', async () => {
+      const user = userEvent.setup();
+      render(<SideNavHeading heading="My App" menu={menuItems} />);
+      const trigger = screen.getByRole('button', {name: 'Open menu'});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      // The heading replica button in the popup is a sibling of the menu,
+      // not an invalid menu child.
+      const headingButton = Array.from(
+        document.querySelectorAll('button'),
+      ).find(b => b !== trigger && b.textContent?.includes('My App'));
+      expect(headingButton).toBeDefined();
+      expect(menu!.contains(headingButton!)).toBe(false);
+      // Clicking it still closes the popup.
+      fireEvent.click(headingButton!);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+      const user = userEvent.setup();
+      render(
+        <SideNavHeading
+          heading="Product"
+          headingHref="/product"
+          menu={menuItems}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'Product');
+      for (const child of Array.from(menu!.children)) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+  });
 });
 
 // =============================================================================
@@ -476,6 +557,41 @@ describe('SideNavHeading collapsed', () => {
     );
     expect(screen.getByTestId('nav-header')).toBeInTheDocument();
   });
+
+  it('collapsed menu popup is not a dialog and scopes role="menu" to menu items', async () => {
+    const user = userEvent.setup();
+    render(
+      <CollapsedWrapper>
+        <SideNavHeading
+          heading="My App"
+          icon={<span data-testid="app-icon">🏠</span>}
+          menu={
+            <>
+              <div role="menuitem">Alpha</div>
+              <div role="menuitem">Beta</div>
+            </>
+          }
+        />
+      </CollapsedWrapper>,
+    );
+    await user.click(screen.getByRole('button', {name: 'My App'}));
+    // No modal dialog wrapper around the menu popup.
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+    expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+    // role="menu" is scoped to the menu items and has a direct name.
+    const menu = document.querySelector('[role="menu"]');
+    expect(menu).not.toBeNull();
+    expect(menu).toHaveAttribute('aria-label', 'My App');
+    const children = Array.from(menu!.children);
+    expect(children.length).toBeGreaterThan(0);
+    for (const child of children) {
+      expect(child).toHaveAttribute('role', 'menuitem');
+    }
+    // No button (trigger or heading replica) lives inside the menu.
+    for (const button of Array.from(document.querySelectorAll('button'))) {
+      expect(menu!.contains(button)).toBe(false);
+    }
+  });
 });
 
 // =============================================================================

package/src/SideNav/SideNavCollapseButton.tsx

@@ -120,7 +120,12 @@ export function SideNavCollapseButton({
   return (
     <Button
       ref={ref}
-      label={label ?? (isCollapsed ? t('@astryx.sideNavCollapseButton.expandSidebar') : t('@astryx.sideNavCollapseButton.collapseSidebar'))}
+      label={
+        label ??
+        (isCollapsed
+          ? t('@astryx.sideNavCollapseButton.expandSidebar')
+          : t('@astryx.sideNavCollapseButton.collapseSidebar'))
+      }
       variant="ghost"
       {...props}
       onClick={composeEventHandlers(onClickProp, toggle)}

package/src/SideNav/SideNavHeading.tsx

@@ -351,6 +351,10 @@ export function SideNavHeading({
 
   const popover = usePopover({
     dialogLabel: t('@astryx.sideNav.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,
   });
 
@@ -428,7 +432,6 @@ export function SideNavHeading({
           {popover.render(
             <div
               ref={menuRef}
-              role="menu"
               {...stylex.props(styles.popoverContent)}
               {...contentProps}>
               <button
@@ -461,9 +464,14 @@ export function SideNavHeading({
                   )}
                 </span>
               </button>
-              <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}>
+                <NavHeadingCloseContext value={closeMenuCtx}>
+                  {menu}
+                </NavHeadingCloseContext>
+              </div>
             </div>,
             {placement: 'below', alignment: 'start', xstyle: styles.popover},
           )}
@@ -620,11 +628,15 @@ export function SideNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            {menu}
+            {/* 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}>
+              {menu}
+            </div>
           </div>,
           {
             placement: 'below',
@@ -683,11 +695,15 @@ export function SideNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            {menu}
+            {/* 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}>
+              {menu}
+            </div>
           </div>,
           {
             placement: 'below',

package/src/SideNav/SideNavItem.doc.mjs

@@ -23,12 +23,12 @@ export const docs = {
     {
       name: 'icon',
       type: 'IconType',
-      description: 'Icon displayed in the outline (unselected) variant. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed in the outline (unselected) variant. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'selectedIcon',
       type: 'IconType',
-      description: 'Icon displayed when the item is selected (filled variant). See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed when the item is selected (filled variant). See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isSelected',

package/src/SideNav/SideNavItem.tsx

@@ -628,7 +628,11 @@ export function SideNavItem({
         <button
           type="button"
           onClick={handleToggleClick}
-          aria-label={isItemCollapsed ? t('@astryx.sideNavItem.expand', {label}) : t('@astryx.sideNavItem.collapse', {label})}
+          aria-label={
+            isItemCollapsed
+              ? t('@astryx.sideNavItem.expand', {label})
+              : t('@astryx.sideNavItem.collapse', {label})
+          }
           aria-expanded={!isItemCollapsed}
           aria-controls={`${id}-children`}
           {...stylex.props(styles.expandToggle)}>

package/src/Slider/Slider.test.tsx

@@ -155,6 +155,60 @@ describe('Slider', () => {
     expect(ariaHidden.length).toBeGreaterThanOrEqual(2);
   });
 
+  // --- Required state ---
+
+  it('conveys required state through the accessible description', () => {
+    render(<Slider label="Volume" value={50} isRequired />);
+    const slider = screen.getByRole('slider');
+    expect(slider).toHaveAccessibleDescription(/Required/);
+    // aria-required is not a supported property of role="slider" in
+    // WAI-ARIA 1.2, so it must never appear on the thumb.
+    expect(slider).not.toHaveAttribute('aria-required');
+  });
+
+  it('conveys required state on both thumbs of a range slider', () => {
+    render(
+      <Slider
+        label="Price range"
+        value={[20, 80] as [number, number]}
+        isRequired
+      />,
+    );
+    const sliders = screen.getAllByRole('slider');
+    expect(sliders).toHaveLength(2);
+    for (const thumb of sliders) {
+      expect(thumb).toHaveAccessibleDescription(/Required/);
+      expect(thumb).not.toHaveAttribute('aria-required');
+    }
+  });
+
+  it('combines required with other describedby parts in the description', () => {
+    render(
+      <Slider
+        label="Volume"
+        value={50}
+        description="Adjust the volume level"
+        isRequired
+      />,
+    );
+    const slider = screen.getByRole('slider');
+    expect(slider).toHaveAccessibleDescription(/Adjust the volume level/);
+    expect(slider).toHaveAccessibleDescription(/Required/);
+  });
+
+  it('does not mention required without isRequired', () => {
+    render(
+      <Slider
+        label="Volume"
+        value={50}
+        description="Adjust the volume level"
+      />,
+    );
+    const slider = screen.getByRole('slider');
+    expect(slider).not.toHaveAccessibleDescription(/Required/);
+    expect(slider).not.toHaveAttribute('aria-required');
+  });
+
   // --- Disabled guards ---
 
   it('disables thumbs when isDisabled is true', () => {
@@ -549,7 +603,11 @@ describe('Slider', () => {
     it('submits both range values under the same name', () => {
       const {container} = render(
         <form>
-          <Slider label="Price" htmlName="price" value={[20, 80] as [number, number]} />
+          <Slider
+            label="Price"
+            htmlName="price"
+            value={[20, 80] as [number, number]}
+          />
         </form>,
       );
       const data = new FormData(container.querySelector('form')!);
@@ -562,7 +620,9 @@ describe('Slider', () => {
           <Slider label="Volume" htmlName="volume" value={50} isDisabled />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });

package/src/Slider/Slider.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Slider.tsx
- * @input Uses React, useId, useRef, useCallback, Field, Tooltip, useTooltip
+ * @input Uses React, useId, useRef, useCallback, Field, Tooltip, useTooltip, VisuallyHidden
  * @output Exports Slider component, SliderProps, SliderSingleProps, SliderRangeProps, SliderBaseProps
  * @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
  *
@@ -38,6 +38,7 @@ import {
 import {Field} from '../Field/Field';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {useTooltip} from '../Tooltip';
+import {VisuallyHidden} from '../VisuallyHidden';
 import type {InputStatus} from '../Field/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -393,6 +394,7 @@ export function Slider({ref, ...props}: SliderProps) {
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  const requiredID = useId();
 
   const trackRef = useRef<HTMLDivElement>(null);
   const draggingThumbRef = useRef<number | null>(null);
@@ -412,6 +414,12 @@ export function Slider({ref, ...props}: SliderProps) {
     isEnabled: showsDisabledMessage,
   });
 
+  // Required state. `aria-required` is not a supported property of
+  // role="slider" in WAI-ARIA 1.2, so the thumb instead points its
+  // aria-describedby at a visually hidden "Required" span — mirroring the
+  // Field label's visible indicator (where isOptional takes precedence).
+  const conveysRequired = isRequired && !isOptional;
+
   // Build aria-describedby
   const describedByParts: string[] = [];
   if (description) {
@@ -420,6 +428,9 @@ export function Slider({ref, ...props}: SliderProps) {
   if (status?.message) {
     describedByParts.push(statusMessageID);
   }
+  if (conveysRequired) {
+    describedByParts.push(requiredID);
+  }
   if (showsDisabledMessage) {
     describedByParts.push(disabledMessageTooltip.describedBy);
   }
@@ -921,6 +932,9 @@ export function Slider({ref, ...props}: SliderProps) {
 
         {textDisplay}
       </div>
+      {conveysRequired && (
+        <VisuallyHidden id={requiredID}>Required</VisuallyHidden>
+      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/Switch/Switch.doc.mjs

@@ -107,7 +107,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon displayed before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon displayed before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',

package/src/Switch/Switch.test.tsx

@@ -9,10 +9,15 @@
  * SYNC: When Switch.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Switch} from './Switch';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
@@ -324,6 +329,32 @@ describe('Switch', () => {
     expect(describedBy).toBeTruthy();
   });
 
+  // Regression: the status is conditionally mounted, so it must be announced
+  // through the persistent useAnnounce live region — a live region born
+  // together with its content is not reliably announced.
+  it('announces a status message that appears after mount', async () => {
+    const {rerender} = render(
+      <Switch label="Enable notifications" value={false} onChange={() => {}} />,
+    );
+    expect(
+      document.querySelector('[data-astryx-live-region="assertive"]'),
+    ).toBeNull();
+
+    rerender(
+      <Switch
+        label="Enable notifications"
+        value={false}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Failed to save setting'}}
+      />,
+    );
+    await waitFor(() => {
+      expect(
+        document.querySelector('[data-astryx-live-region="assertive"]'),
+      ).toHaveTextContent('Failed to save setting');
+    });
+  });
+
   it('calls onFocus and onBlur callbacks', async () => {
     const user = userEvent.setup();
     const handleFocus = vi.fn();

package/src/TabList/Tab.tsx

@@ -138,7 +138,11 @@ const styles = stylex.create({
   },
   indicator: {
     position: 'absolute',
-    bottom: '-1px',
+    // Sits on the tab's bottom edge by default (-1px). When the tab strip
+    // reserves space for a divider rail — TabList `hasDivider` or a Toolbar
+    // with a bottom divider — that ancestor sets `--_tab-indicator-bottom`
+    // to drop the indicator onto the rail beneath the reserved gap.
+    bottom: 'var(--_tab-indicator-bottom, -1px)',
     left: spacingVars['--spacing-3'],
     right: spacingVars['--spacing-3'],
     height: '2px',

package/src/TabList/TabList.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -113,7 +113,7 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
@@ -135,7 +135,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
       { guidance: true, description: 'Use TabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
-      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\'t overpower the tab row.' },
+      { guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },
       { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
       { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
       { guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },

package/src/TabList/TabList.test.tsx

@@ -323,6 +323,72 @@ describe('TabList', () => {
   });
 });
 
+describe('TabList divider gap', () => {
+  // The divider adds the reserved gap + indicator offset via a single class
+  // (StyleX applies deterministic classes in the test env). Capture that
+  // class set once so the assertions describe intent, not opaque hashes.
+  function navClasses(hasDivider: boolean): Set<string> {
+    const {unmount} = render(
+      <TabList value="home" onChange={() => {}} hasDivider={hasDivider}>
+        <Tab value="home" label="Home" />
+      </TabList>,
+    );
+    const nav = screen.getByRole('navigation');
+    const classes = new Set(nav.className.split(/\s+/).filter(Boolean));
+    unmount();
+    return classes;
+  }
+
+  it('adds divider-only styling classes when hasDivider is set', () => {
+    const withDivider = navClasses(true);
+    const withoutDivider = navClasses(false);
+
+    // Every class the plain nav has must still be present when divided: the
+    // divider only adds styling (border + reserved gap + indicator offset),
+    // it never removes the base nav styles.
+    for (const cls of withoutDivider) {
+      expect(withDivider.has(cls)).toBe(true);
+    }
+
+    // And it must add at least one class the undivided nav does not have.
+    const added = [...withDivider].filter(c => !withoutDivider.has(c));
+    expect(added.length).toBeGreaterThan(0);
+  });
+
+  it('does not add divider styling to an undivided tab list (default)', () => {
+    // Default (no hasDivider) and explicit hasDivider={false} are identical:
+    // the non-divided path is untouched by the divider gap change.
+    expect(navClasses(false)).toEqual(
+      (() => {
+        const {unmount} = render(
+          <TabList value="home" onChange={() => {}}>
+            <Tab value="home" label="Home" />
+          </TabList>,
+        );
+        const nav = screen.getByRole('navigation');
+        const classes = new Set(nav.className.split(/\s+/).filter(Boolean));
+        unmount();
+        return classes;
+      })(),
+    );
+  });
+
+  it('keeps the selected indicator rendered under a divider', () => {
+    render(
+      <TabList value="home" onChange={() => {}} hasDivider>
+        <Tab value="home" label="Home" />
+        <Tab value="away" label="Away" />
+      </TabList>,
+    );
+    const selected = screen.getByRole('button', {name: 'Home'});
+    // The indicator span carries the selected marker; the divider must not
+    // drop it (it is repositioned onto the rail, not removed).
+    expect(
+      selected.querySelector('[data-selected="selected"]'),
+    ).toBeInTheDocument();
+  });
+});
+
 describe('TabList keyboard navigation (roving tabindex)', () => {
   it('exposes the tab strip as a single Tab stop (only selected tab is tabbable)', () => {
     render(

package/src/TabList/TabList.tsx

@@ -96,6 +96,14 @@ const styles = stylex.create({
     borderBottomWidth: borderVars['--border-width'],
     borderBottomStyle: 'solid',
     borderBottomColor: colorVars['--color-border'],
+    // Reserve a gap between the tabs and the divider rail so the hover pill
+    // (which fills the tab height) no longer touches the underline, and an
+    // adjacent same-size Button aligns to the tabs rather than butting the
+    // rail. The tabs keep their element-size height; this padding grows the
+    // strip. `--_tab-indicator-bottom` drops the selected indicator through
+    // the reserved gap (+ the 1px border) so it still sits on the rail.
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    '--_tab-indicator-bottom': `calc(-1 * (${spacingVars['--spacing-1']} + ${borderVars['--border-width']}))`,
   },
 });
 

package/src/TabList/TabMenu.tsx

@@ -122,7 +122,10 @@ const styles = stylex.create({
   },
   indicator: {
     position: 'absolute',
-    bottom: '-1px',
+    // Mirrors Tab's indicator: sits on the bottom edge by default (-1px), or
+    // drops onto the divider rail when an ancestor (TabList `hasDivider` or a
+    // Toolbar with a bottom divider) sets `--_tab-indicator-bottom`.
+    bottom: 'var(--_tab-indicator-bottom, -1px)',
     left: spacingVars['--spacing-3'],
     right: spacingVars['--spacing-3'],
     height: '2px',

package/src/Table/Table.doc.mjs

@@ -111,6 +111,8 @@ export const docs = {
     {name: 'useTableSelection'},
     {name: 'useTableSelectionState'},
     {name: 'useTableSortable'},
+    {name: 'useTableTreeData'},
+    {name: 'useTableTreeState'},
     {name: 'useTablePagination'},
     {name: 'useTableColumnSettings'},
     {name: 'useTableFiltering'},

package/src/Table/Table.tsx

@@ -275,7 +275,7 @@ function TableInner<T extends Record<string, unknown>>({
  *   columns={[
  *     { key: 'name', header: 'Name', width: proportional(1), renderCell: (u) => (
  *       <HStack gap={2} align="center">
- *         <Avatar name={u.name} size="small" />
+ *         <Avatar name={u.name} size="md" />
  *         <Text weight="semibold">{u.name}</Text>
  *       </HStack>
  *     )},