@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/src/Outline/useScrollSpy.ts

@@ -10,11 +10,26 @@
  *
  * Drives the active outline item from scroll position. On each scroll
  * (rAF-throttled) it reads live heading positions and marks the last heading
- * whose top has passed its activation line (its own scroll-margin-top, i.e.
- * where it lands when navigated to). This is stable — it never compares stale
- * cached positions — so the indicator moves monotonically instead of jumping.
- * Defaults to the first item at the top and the last item at the bottom so
- * short final sections still activate.
+ * whose top has passed its activation line. This is stable — it never compares
+ * stale cached positions — so the indicator moves monotonically instead of
+ * jumping. Defaults to the first item at the top and the last item at the
+ * bottom so short final sections still activate.
+ *
+ * The activation line and the scroll landing are the same number, computed once
+ * in `getRestingTop`: scroll-root top + `offset` (a fixed header overlaying the
+ * root) + the heading's own `scroll-margin-top`. A heading therefore activates
+ * exactly where navigating to it puts it. `offset` and `scroll-margin-top`
+ * compose — the header, then the breathing room below it — they do not
+ * duplicate each other.
+ *
+ * It also owns the single navigation path (`scrollTo`), shared by click and
+ * keyboard activation: it announces the jump, suppresses scroll-spy for the
+ * duration of the programmatic scroll (so the indicator doesn't chase it), and
+ * resolves when the scroll settles — via `scrollend` where supported, or a
+ * timeout fallback where it is not.
+ *
+ * The scroll root is the `scrollContainerRef` element when provided, otherwise
+ * the nearest scrollable ancestor of the outline, otherwise the viewport.
  *
  * SYNC: When modified, update /packages/core/src/Outline/Outline.tsx
  */
@@ -22,6 +37,14 @@
 import {useCallback, useEffect, useRef, useState} from 'react';
 import type {OutlineItem} from './types';
 
+/**
+ * How long to wait for a programmatic smooth scroll to settle when the
+ * `scrollend` event never arrives — either because the browser does not
+ * support it (Safari at time of writing) or because the target was already in
+ * position, so no scroll happened at all and no events were emitted.
+ */
+const SCROLL_SETTLE_TIMEOUT_MS = 1200;
+
 /** Keys that scroll the viewport — used to detect a manual scroll intent. */
 const SCROLL_KEYS = new Set([
   'ArrowUp',
@@ -58,26 +81,82 @@ function getScrollableAncestor(
   return null;
 }
 
+/** The element's own `scroll-margin-top` in px (0 when unset). */
+function getScrollMarginTop(element: HTMLElement): number {
+  return (
+    Number.parseFloat(window.getComputedStyle(element).scrollMarginTop) || 0
+  );
+}
+
+/** The top of the scroll root in viewport coordinates (0 for the viewport). */
+function getRootTop(scrollRoot: HTMLElement | null): number {
+  return scrollRoot != null ? scrollRoot.getBoundingClientRect().top : 0;
+}
+
+/**
+ * Where a heading comes to rest, in viewport coordinates: below the fixed
+ * header (`offset`) and below its own `scroll-margin-top` breathing room.
+ *
+ * This is the single source of truth shared by the activation line and the
+ * scroll landing — the two must agree, or a heading activates somewhere other
+ * than where navigating to it puts it.
+ */
+function getRestingTop(
+  target: HTMLElement,
+  scrollRoot: HTMLElement | null,
+  offset: number,
+): number {
+  return getRootTop(scrollRoot) + offset + getScrollMarginTop(target);
+}
+
+/**
+ * Bring `target` to rest at the top of the scroll root, below any fixed header.
+ *
+ * With no `offset`, this is the CSS-native path: `scrollIntoView` already
+ * honors the heading's `scroll-margin-top`, and it walks *every* scrollable
+ * ancestor, so the browser does it better than we can.
+ *
+ * An `offset` describes a fixed header overlaying the top of the scroll root —
+ * which the browser cannot know about, so `scrollIntoView` would park the
+ * heading underneath it, hidden. Compute the landing explicitly instead, from
+ * the same {@link getRestingTop} the activation line uses.
+ */
+function scrollToTarget(
+  target: HTMLElement,
+  scrollRoot: HTMLElement | null,
+  scrollTarget: HTMLElement | Window,
+  offset: number,
+): void {
+  if (offset === 0) {
+    target.scrollIntoView({behavior: 'smooth', block: 'start'});
+    return;
+  }
+
+  const delta =
+    target.getBoundingClientRect().top -
+    getRestingTop(target, scrollRoot, offset);
+  scrollTarget.scrollBy({top: delta, behavior: 'smooth'});
+}
+
 /**
  * Resolve the active heading id from current scroll position.
  *
- * A heading is "passed" once its top reaches its activation line — the scroll
- * root's top plus the heading's own scroll-margin-top. The active heading is
- * the last passed one (headings are in document order). When none have passed
- * (scrolled above the first), the first item is active; at the bottom, the
- * last item is active.
+ * A heading is "passed" once its top reaches its activation line — exactly
+ * where navigating to it would land it ({@link getRestingTop}): the scroll
+ * root's top, plus `offset` (a fixed header overlaying the scroll root), plus
+ * the heading's own scroll-margin-top. The active heading is the last passed
+ * one (headings are in document order). When none have passed (scrolled above
+ * the first), the first item is active; at the bottom, the last item is active.
  */
 function resolveActiveId(
   items: OutlineItem[],
   scrollRoot: HTMLElement | null,
+  offset: number,
 ): string | undefined {
   if (items.length === 0) {
     return undefined;
   }
 
-  const rootTop =
-    scrollRoot != null ? scrollRoot.getBoundingClientRect().top : 0;
-
   const atBottom =
     scrollRoot != null
       ? scrollRoot.scrollTop + scrollRoot.clientHeight >=
@@ -94,11 +173,10 @@ function resolveActiveId(
     if (element == null) {
       continue;
     }
-    const top = element.getBoundingClientRect().top;
-    const marginTop =
-      Number.parseFloat(window.getComputedStyle(element).scrollMarginTop) || 0;
 
-    if (top <= rootTop + marginTop + 1) {
+    // 1px of tolerance absorbs sub-pixel rounding after a scroll lands.
+    const top = element.getBoundingClientRect().top;
+    if (top <= getRestingTop(element, scrollRoot, offset) + 1) {
       activeId = item.id;
     } else {
       break;
@@ -112,6 +190,20 @@ interface UseScrollSpyOptions {
   items: OutlineItem[];
   onActiveIdChange?: (id: string) => void;
   rootRef: React.RefObject<HTMLElement | null>;
+  /**
+   * Height in px of a fixed header overlaying the top of the scroll root.
+   * Shifts both the activation line and the scroll landing by the same amount,
+   * on top of each heading's own `scroll-margin-top`.
+   */
+  offset?: number;
+  /** Scroll container to track, instead of the nearest scrollable ancestor. */
+  scrollContainerRef?: React.RefObject<HTMLElement | null>;
+  /** Whether {@link UseScrollSpyResult.scrollTo} performs the smooth scroll. */
+  hasScrollOnClick?: boolean;
+  /** Called when a navigation begins, before the scroll starts. */
+  onNavigateStart?: (id: string) => void;
+  /** Called once per navigation, when the scroll settles or is interrupted. */
+  onNavigateEnd?: (id: string) => void;
 }
 
 interface UseScrollSpyResult {
@@ -119,13 +211,19 @@ interface UseScrollSpyResult {
   /** Set the active id (notifies onActiveIdChange). For controlled consumers. */
   setActiveId: (id: string) => void;
   /**
-   * Handle a click on the outline item with id `id`. Delays moving the
-   * indicator: scroll-spy is suppressed during the programmatic smooth scroll
-   * so the indicator doesn't chase it, then the indicator moves once to the
-   * clicked item when the scroll settles. If the user scrolls manually mid-way,
-   * scroll-position tracking resumes immediately instead.
+   * Navigate to the item with id `id` — the single path shared by click and
+   * keyboard activation.
+   *
+   * Fires `onNavigateStart(id)`, scrolls (unless `hasScrollOnClick` is false),
+   * and fires `onNavigateEnd(id)` exactly once when the scroll settles or the
+   * user interrupts it. While uncontrolled, scroll-spy is suppressed for the
+   * duration so the indicator doesn't chase the scroll through intervening
+   * sections; it lands on the target once the scroll settles, or resumes
+   * position tracking if the user scrolls away mid-flight.
+   *
+   * Returns false (and does nothing) when no element with `id` exists.
    */
-  lockActiveId: (id: string) => void;
+  scrollTo: (id: string) => boolean;
 }
 
 export function useScrollSpy({
@@ -133,18 +231,29 @@ export function useScrollSpy({
   items,
   onActiveIdChange,
   rootRef,
+  offset = 0,
+  scrollContainerRef,
+  hasScrollOnClick = true,
+  onNavigateStart,
+  onNavigateEnd,
 }: UseScrollSpyOptions): UseScrollSpyResult {
   const isControlled = activeId !== undefined;
   const [uncontrolledActiveId, setUncontrolledActiveId] = useState<
     string | undefined
   >(items[0]?.id);
   const activeIdRef = useRef<string | undefined>(activeId);
-  // While true, scroll-spy ignores scroll updates because a click is driving a
-  // programmatic scroll. Released when that scroll settles or the user scrolls.
+  // While true, scroll-spy ignores scroll updates because a navigation is
+  // driving a programmatic scroll. Released when it settles or the user scrolls.
   const suppressRef = useRef(false);
-  const releaseSuppressionRef = useRef<(() => void) | null>(null);
-  // Latest scroll-position resolver, so the click handler can resume tracking
-  // when the user scrolls during a programmatic scroll.
+  // The navigation currently in flight, if any.
+  const navigationRef = useRef<{
+    /** End it (without resuming tracking) because a new one is starting. */
+    supersede: () => void;
+    /** Drop its listeners without firing onNavigateEnd (unmount). */
+    teardown: () => void;
+  } | null>(null);
+  // Latest scroll-position resolver, so a navigation can resume tracking when
+  // the user scrolls during the programmatic scroll.
   const syncRef = useRef<(() => void) | null>(null);
   // Keep latest items/callback in refs so the scroll listener effect doesn't
   // re-subscribe on every render (items is a fresh array each render).
@@ -155,12 +264,23 @@ export function useScrollSpy({
   const itemIds = items.map(item => item.id).join('\n');
   activeIdRef.current = isControlled ? activeId : uncontrolledActiveId;
 
+  /**
+   * The element whose scroll position drives the outline: the explicit
+   * container when scoped, else the nearest scrollable ancestor, else null
+   * (meaning the viewport).
+   */
+  const getScrollRoot = useCallback((): HTMLElement | null => {
+    return (
+      scrollContainerRef?.current ?? getScrollableAncestor(rootRef.current)
+    );
+  }, [rootRef, scrollContainerRef]);
+
   useEffect(() => {
     if (isControlled || typeof window === 'undefined') {
       return;
     }
 
-    const scrollRoot = getScrollableAncestor(rootRef.current);
+    const scrollRoot = getScrollRoot();
     const scrollTarget: HTMLElement | Window = scrollRoot ?? window;
 
     let frame = 0;
@@ -169,7 +289,11 @@ export function useScrollSpy({
       if (suppressRef.current) {
         return;
       }
-      const nextActiveId = resolveActiveId(itemsRef.current, scrollRoot);
+      const nextActiveId = resolveActiveId(
+        itemsRef.current,
+        scrollRoot,
+        offset,
+      );
       if (nextActiveId != null && nextActiveId !== activeIdRef.current) {
         activeIdRef.current = nextActiveId;
         setUncontrolledActiveId(nextActiveId);
@@ -195,12 +319,12 @@ export function useScrollSpy({
         cancelAnimationFrame(frame);
       }
     };
-  }, [isControlled, itemIds, rootRef]);
+  }, [isControlled, itemIds, offset, getScrollRoot]);
 
-  // Tear down any pending suppression listeners when the Outline unmounts.
+  // Tear down any in-flight navigation's listeners when the Outline unmounts.
   useEffect(() => {
     return () => {
-      releaseSuppressionRef.current?.();
+      navigationRef.current?.teardown();
     };
   }, []);
 
@@ -211,65 +335,117 @@ export function useScrollSpy({
     onActiveIdChange?.(nextActiveId);
   };
 
-  const lockActiveId = useCallback((clickedId: string) => {
-    if (typeof window === 'undefined') {
-      setUncontrolledActiveId(clickedId);
-      activeIdRef.current = clickedId;
-      onActiveIdChangeRef.current?.(clickedId);
-      return;
+  // Defined in render (not memoized) so it always closes over the current props
+  // — it only ever runs from an event handler, never during render.
+  const scrollTo = (id: string): boolean => {
+    const target =
+      typeof document !== 'undefined' ? document.getElementById(id) : null;
+    if (target == null) {
+      return false;
+    }
+
+    // A second navigation replaces the first: end the old one (balancing its
+    // onNavigateStart) without resuming tracking, since we are about to
+    // suppress it again anyway.
+    navigationRef.current?.supersede();
+
+    onNavigateStart?.(id);
+
+    if (isControlled) {
+      // The consumer owns the active state — notify only.
+      setActiveId(id);
+    } else {
+      // Freeze the indicator during the programmatic scroll instead of moving
+      // it immediately: it lands on the target once the scroll settles, so it
+      // doesn't chase the scroll through intervening sections.
+      suppressRef.current = true;
     }
 
-    // Freeze the indicator during the programmatic smooth scroll instead of
-    // moving it immediately — it lands on the clicked item once the scroll
-    // settles, so it doesn't chase the scroll through intervening sections.
-    suppressRef.current = true;
-    // Replace any in-flight handlers from a previous click.
-    releaseSuppressionRef.current?.();
+    const scrollRoot = getScrollRoot();
+    const scrollTarget: HTMLElement | Window = scrollRoot ?? window;
 
     let settleTimer = 0;
+    let isSettled = false;
+
     const cleanup = () => {
-      window.removeEventListener('scrollend', onSettle);
-      window.removeEventListener('wheel', onManual);
-      window.removeEventListener('touchmove', onManual);
+      scrollTarget.removeEventListener('scrollend', onSettle);
+      scrollTarget.removeEventListener('wheel', onManual);
+      scrollTarget.removeEventListener('touchmove', onManual);
       window.removeEventListener('keydown', onKeyDown);
       if (settleTimer !== 0) {
         clearTimeout(settleTimer);
         settleTimer = 0;
       }
-      releaseSuppressionRef.current = null;
+      navigationRef.current = null;
     };
-    // Programmatic scroll finished: move the indicator to the clicked item.
-    const onSettle = () => {
-      cleanup();
-      suppressRef.current = false;
-      setUncontrolledActiveId(clickedId);
-      activeIdRef.current = clickedId;
-      onActiveIdChangeRef.current?.(clickedId);
-    };
-    // User scrolled mid-flight: hand control back to scroll-position tracking.
-    const onManual = () => {
+
+    /**
+     * End the navigation exactly once. `didArrive` is false when the user took
+     * over with a manual scroll mid-flight. `onNavigateEnd` fires either way,
+     * so every `onNavigateStart` is balanced and a consumer's "navigating"
+     * state can never leak.
+     */
+    const finish = (didArrive: boolean, shouldResume = true) => {
+      if (isSettled) {
+        return;
+      }
+      isSettled = true;
       cleanup();
-      suppressRef.current = false;
-      syncRef.current?.();
+
+      if (!isControlled) {
+        suppressRef.current = false;
+        if (didArrive) {
+          setUncontrolledActiveId(id);
+          activeIdRef.current = id;
+          onActiveIdChangeRef.current?.(id);
+        } else if (shouldResume) {
+          // Hand control back to scroll-position tracking.
+          syncRef.current?.();
+        }
+      }
+
+      onNavigateEnd?.(id);
     };
+
+    const onSettle = () => finish(true);
+    const onManual = () => finish(false);
     const onKeyDown = (event: KeyboardEvent) => {
-      if (SCROLL_KEYS.has(event.key)) {
-        onManual();
+      // A key the outline itself consumed (arrow roving focus, Space
+      // activation) is prevented, so the browser will not scroll — it is not a
+      // manual scroll intent and must not cancel the navigation it just began.
+      if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) {
+        finish(false);
       }
     };
 
-    window.addEventListener('scrollend', onSettle, {once: true});
-    window.addEventListener('wheel', onManual, {passive: true});
-    window.addEventListener('touchmove', onManual, {passive: true});
-    window.addEventListener('keydown', onKeyDown);
-    // Fallback when scrollend is unsupported or no scroll is needed.
-    settleTimer = window.setTimeout(onSettle, 1200);
-    releaseSuppressionRef.current = cleanup;
-  }, []);
+    if (hasScrollOnClick) {
+      // Arm settle detection *before* scrolling so an instant jump (a target
+      // already in position, or prefers-reduced-motion collapsing the smooth
+      // scroll) cannot land before anyone is listening.
+      scrollTarget.addEventListener('scrollend', onSettle, {once: true});
+      scrollTarget.addEventListener('wheel', onManual, {passive: true});
+      scrollTarget.addEventListener('touchmove', onManual, {passive: true});
+      window.addEventListener('keydown', onKeyDown);
+      settleTimer = window.setTimeout(onSettle, SCROLL_SETTLE_TIMEOUT_MS);
+      navigationRef.current = {
+        supersede: () => finish(false, false),
+        teardown: cleanup,
+      };
+      scrollToTarget(target, scrollRoot, scrollTarget, offset);
+    } else {
+      // The consumer owns scrolling — there is no scroll to wait for, so the
+      // navigation is already at rest. Resolving immediately (instead of
+      // waiting on the settle timeout) keeps onNavigateEnd usable for arrival
+      // effects even when hasScrollOnClick is false.
+      finish(true);
+    }
+
+    return true;
+  };
 
   return {
     activeId: isControlled ? activeId : uncontrolledActiveId,
     setActiveId,
-    lockActiveId,
+    scrollTo,
   };
 }

package/src/Selector/SelectorOption.doc.mjs

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

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/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/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>
  *     )},