@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/dist/TabList/TabList.d.ts

@@ -1,10 +1,14 @@
 /**
  * @file TabList.tsx
- * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint
- * @output Exports TabList component and TabListProps type
- * @position Nav wrapper; provides TabListContext to Tab and TabMenu children.
- *   Owns roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
- *   strip via the shared useListFocus hook so it is a single Tab stop.
+ * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint,
+ *   useScrollOverflow, Icon
+ * @output Exports TabList component, TabListProps and TabListOverflow types
+ * @position Tab strip wrapper; provides TabListContext to Tab and TabMenu
+ *   children. A `<nav>` landmark by default; speaks the WAI-ARIA tabs pattern
+ *   where the caller asks for it with `role="tablist"`. Owns
+ *   roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
+ *   strip via the shared useListFocus hook so it is a single Tab stop, and
+ *   owns horizontal scrolling when the tabs are wider than the strip.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TabList/TabList.doc.mjs
@@ -12,10 +16,20 @@
  * - /packages/core/src/TabList/TabList.test.tsx
  * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
  */
-import React, { type ReactNode } from 'react';
+import React, { type AriaRole, type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 import type { TabListSize } from './TabListContext';
 import { EDGE_COMP_ATTR } from '../Layout/edgeCompensation.stylex';
+/**
+ * How a strip narrower than its tabs behaves.
+ *
+ * - `'auto'` — the component picks the strategy. Today that is always
+ *   `'scroll'`.
+ * - `'scroll'` — the tabs scroll horizontally. Every tab stays a tab.
+ * - `'visible'` — no overflow handling: tabs keep their intrinsic widths and
+ *   spill out of the strip, as they did before overflow existed.
+ */
+export type TabListOverflow = 'auto' | 'scroll' | 'visible';
 export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
     ref?: React.Ref<HTMLElement>;
     /**
@@ -44,6 +58,31 @@ export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
      * @default false
      */
     hasDivider?: boolean;
+    /**
+     * ARIA role for the strip.
+     *
+     * `"tablist"` asks for the WAI-ARIA tabs pattern: `role="tablist"` /
+     * `role="tab"` and `aria-selected`, with each tab pointing at the panel it
+     * controls via its `panelId`. Only tabs may live in a tablist strip, and a
+     * tab does not navigate — an `href` is ignored there.
+     *
+     * Left unset, the strip is a `<nav>` landmark marking the current tab with
+     * `aria-current`. Any other value is passed through to the element
+     * unchanged.
+     */
+    role?: AriaRole;
+    /**
+     * What happens when the tabs are wider than the strip.
+     *
+     * `'auto'` lets the component choose; today it always scrolls. `'scroll'`
+     * scrolls the tabs horizontally, with edge fades and — for pointers that
+     * can hover — arrow affordances. `'visible'` turns overflow handling off and
+     * lets the tabs spill out of the strip.
+     *
+     * The selected tab is always scrolled back into view.
+     * @default 'auto'
+     */
+    overflow?: TabListOverflow;
     /**
      * Tab and TabMenu children.
      */
@@ -65,7 +104,7 @@ export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
  * </TabList>
  * ```
  */
-export declare function TabList({ ref, value, onChange, size: sizeProp, layout, hasDivider, xstyle, className, style, children, onKeyDown: onKeyDownProp, onFocus: onFocusProp, onBlur: onBlurProp, 'aria-label': ariaLabelFromProps, 'aria-orientation': _ariaOrientation, [EDGE_COMP_ATTR]: _edgeCompAttr, ...restProps }: TabListProps): React.JSX.Element;
+export declare function TabList({ ref, value, onChange, size: sizeProp, layout, hasDivider, role, overflow, xstyle, className, style, children, onKeyDown: onKeyDownProp, onFocus: onFocusProp, onBlur: onBlurProp, 'aria-label': ariaLabelFromProps, 'aria-labelledby': ariaLabelledBy, 'aria-orientation': _ariaOrientation, [EDGE_COMP_ATTR]: _edgeCompAttr, ...restProps }: TabListProps): React.JSX.Element;
 export declare namespace TabList {
     var displayName: string;
 }

package/dist/TabList/TabList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TabList.d.ts","sourceRoot":"","sources":["../../src/TabList/TabList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,EAAuB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAGlE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAKlD,OAAO,EAAC,cAAc,EAAC,MAAM,mCAAmC,CAAC;AAWjE,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAC5E,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AA4BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EAAE,QAAQ,EACd,MAAc,EACd,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,kBAAkB,EAChC,kBAAkB,EAAE,gBAAgB,EACpC,CAAC,cAAc,CAAC,EAAE,aAAa,EAC/B,GAAG,SAAS,EACb,EAAE,YAAY,qBAkGd;yBApHe,OAAO"}
+{"version":3,"file":"TabList.d.ts","sourceRoot":"","sources":["../../src/TabList/TabList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,EAKZ,KAAK,QAAQ,EACb,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAQlD,OAAO,EAAC,cAAc,EAAC,MAAM,mCAAmC,CAAC;AAsBjE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAC5E,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAyLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EAAE,QAAQ,EACd,MAAc,EACd,UAAkB,EAClB,IAAI,EACJ,QAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,kBAAkB,EAChC,iBAAiB,EAAE,cAAc,EACjC,kBAAkB,EAAE,gBAAgB,EACpC,CAAC,cAAc,CAAC,EAAE,aAAa,EAC/B,GAAG,SAAS,EACb,EAAE,YAAY,qBA+Ud;yBApWe,OAAO"}

package/dist/TabList/TabList.js

@@ -4,11 +4,15 @@
 
 /**
  * @file TabList.tsx
- * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint
- * @output Exports TabList component and TabListProps type
- * @position Nav wrapper; provides TabListContext to Tab and TabMenu children.
- *   Owns roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
- *   strip via the shared useListFocus hook so it is a single Tab stop.
+ * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint,
+ *   useScrollOverflow, Icon
+ * @output Exports TabList component, TabListProps and TabListOverflow types
+ * @position Tab strip wrapper; provides TabListContext to Tab and TabMenu
+ *   children. A `<nav>` landmark by default; speaks the WAI-ARIA tabs pattern
+ *   where the caller asks for it with `role="tablist"`. Owns
+ *   roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
+ *   strip via the shared useListFocus hook so it is a single Tab stop, and
+ *   owns horizontal scrolling when the tabs are wider than the strip.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TabList/TabList.doc.mjs
@@ -16,26 +20,96 @@
  * - /packages/core/src/TabList/TabList.test.tsx
  * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
  */
-import React, { useCallback, useMemo } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { borderVars, colorVars, spacingVars } from "../theme/tokens.stylex.js";
+import { borderVars, colorVars, durationVars, easeVars, focusVars, radiusVars, shadowVars, sizeVars, spacingVars } from "../theme/tokens.stylex.js";
 import { TabListContext } from "./TabListContext.js";
 import { useSize } from "../SizeContext/SizeContext.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps, rtlStyles } from "../utils/index.js";
 import { useListFocus } from "../hooks/useListFocus.js";
 import { useKeyboardHint } from "../hooks/useKeyboardHint.js";
+import { useScrollOverflow } from "../hooks/useScrollOverflow.js";
+import { isRtlElement } from "../hooks/isRtlElement.js";
+import { Icon } from "../Icon/index.js";
 import { EDGE_COMP_ATTR } from "../Layout/edgeCompensation.stylex.js";
 import { themeProps } from "../utils/themeProps.js";
+import { observeResize, unobserveResize } from "../utils/sharedResizeObserver.js";
+import { devWarn } from "../utils/devWarning.js";
+import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
 import { useTranslator } from "../i18n/index.js";
-
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 /**
  * Selector matching the focusable stops in the tab strip: every Tab
  * (`[data-tab-value]`) and every TabMenu trigger (`[data-tab-menu]`),
  * in DOM order. Disabled stops are filtered out by the handler.
  */
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const TAB_STOP_SELECTOR = '[data-tab-value],[data-tab-menu]';
+function preventFocus(e) {
+  e.preventDefault();
+}
+
+/** Fraction of the visible strip an arrow press scrolls. */
+const SCROLL_PAGE_RATIO = 0.8;
+
+/**
+ * How a strip narrower than its tabs behaves.
+ *
+ * - `'auto'` — the component picks the strategy. Today that is always
+ *   `'scroll'`.
+ * - `'scroll'` — the tabs scroll horizontally. Every tab stays a tab.
+ * - `'visible'` — no overflow handling: tabs keep their intrinsic widths and
+ *   spill out of the strip, as they did before overflow existed.
+ */
+
+/**
+ * A scroll container clips at its padding box, and two things a tab paints sit
+ * outside its own box: the focus ring (offset + width) and the selected
+ * indicator, which `--_tab-indicator-bottom` pushes further down when a
+ * divider rail is reserved. The strip pads by that much and takes the padding
+ * straight back off with a negative margin, so nothing is clipped and the tabs
+ * stay exactly where they were.
+ *
+ * A bleed is not free, though. The padding is real geometry: the strip's
+ * border box sticks out of the TabList's, and any ancestor that scrolls counts
+ * that as something to scroll to. So the ring's share of the bleed is taken
+ * only while a ring is actually drawn inside the strip -- the same
+ * `:has(:focus-visible)` condition that draws it -- and at rest the strip is
+ * exactly as wide and as tall as the TabList, as it was before the strip could
+ * scroll. The indicator's share is always taken, because the indicator is
+ * always drawn.
+ *
+ * Turning the bleed on moves nothing: padding and negative margin cancel, so
+ * the border box grows outwards and the content stays put.
+ */
+const RING_BLEED = `calc(${focusVars['--focus-outline-width']} + ${focusVars['--focus-outline-offset']})`;
+const BLEED_VAR = '--_tab-strip-bleed';
+const BLEED = `var(${BLEED_VAR})`;
+const INDICATOR_BLEED = 'calc(-1 * var(--_tab-indicator-bottom, -1px))';
+const BLOCK_END_BLEED = `max(${BLEED}, ${INDICATOR_BLEED})`;
+
+/** How far the edge fade runs; wide enough to sit under an arrow. */
+const FADE_WIDTH = spacingVars['--spacing-8'];
+
+/**
+ * Where the fade turns fully opaque, and — the same distance, for the same
+ * reason — how far a revealed stop is kept clear of the edge. Declared as
+ * scroll-padding so the browser's own focus scrolling uses it too, and read
+ * back from the computed style so the arithmetic below has one source of
+ * truth with the CSS.
+ */
+const SCROLL_EDGE_INSET = `calc(${BLEED} + ${FADE_WIDTH})`;
+
+/**
+ * The fade reaches transparent at the strip's *own* edge, not at the bleed
+ * edge — otherwise the scroll container paints tabs past the TabList's box,
+ * past a divider rail, and past the scroll arrow that caps that edge. Masking
+ * the bleed costs nothing: only a faded edge is masked, and a stop at a faded
+ * edge never holds focus, so the bleed is still there when the ring needs it.
+ */
+const FADE_FROM_START = `linear-gradient(to right, transparent ${BLEED}, black ${SCROLL_EDGE_INSET})`;
+const FADE_FROM_END = `linear-gradient(to left, transparent ${BLEED}, black ${SCROLL_EDGE_INSET})`;
 const styles = {
   nav: {
     k1xSpc: "x78zum5",
@@ -43,6 +117,7 @@ const styles = {
     kOIVth: "x1lsbc85",
     ks0D6T: "x193iq5w",
     k7Eaqz: "xeuugli",
+    kVAEAm: "x1n2onr6",
     $$css: true
   },
   fill: {
@@ -56,6 +131,89 @@ const styles = {
     kGO01o: "xy143xn",
     "--_tab-indicator-bottom": "xficto1",
     $$css: true
+  },
+  strip: {
+    k1xSpc: "x78zum5",
+    kGNEyG: "x1qjc9v5",
+    kOIVth: "x14kbac9",
+    kzQI83: "x1iyjqo2",
+    kmuXW: "xs83m0k",
+    k7Eaqz: "xeuugli",
+    kSGwAc: "xqcrz7y",
+    $$css: true
+  },
+  stripScroll: {
+    kXHlph: "xw2csxc",
+    kORKVm: "x10wlt62",
+    kvh3hx: "x7p5m3t",
+    katHQp: "x1xif8ns",
+    k5wCbM: "x1rohswg",
+    khEr5k: "xkcv6ua xg83hb1",
+    "--_tab-strip-bleed": "x78b515 x158n88w",
+    kLKAdn: "xlr2r7p",
+    keoZOQ: "xmqyaqf",
+    kGO01o: "xwhchk8",
+    k1K539: "xlgak1e",
+    kg3NbH: "x1kpkw9v",
+    kUOVxO: "xi5l473",
+    kX1K2I: "xw4ya9i",
+    k1ekBW: "x157bb6t",
+    kIyJzY: "x80gvsz x12w9bfk",
+    kAMwcw: "xlr8y92",
+    $$css: true
+  },
+  fadeStart: {
+    kX1K2I: "x1hua2o0 x1nwey30",
+    $$css: true
+  },
+  fadeEnd: {
+    kX1K2I: "xoj6v2h x1rxa4r8",
+    $$css: true
+  },
+  fadeBoth: {
+    kX1K2I: "xq05pg6",
+    $$css: true
+  },
+  arrow: {
+    kVAEAm: "x10l6tqk",
+    k87sOh: "x13vifvy",
+    k1xSpc: "x1s85apg xqwu39o",
+    kGNEyG: "x6s0dn4",
+    kjj79g: "xl56j7k",
+    kmVPX3: "x1717udv",
+    kMzoRj: "xc342km",
+    ksu8eU: "xng3xce",
+    kaIpWk: "xjspbzw",
+    kWkggS: "x1prclbq",
+    kGVxlE: "x1i5ehqx",
+    kMwMTN: "xv1l7n4 x9o1np9",
+    kkrTdU: "x1ypdohk x16khyan",
+    $$css: true
+  },
+  arrowStart: {
+    kLqNvP: "x1o0tod",
+    $$css: true
+  },
+  arrowEnd: {
+    kt4wiu: "xtijo5x",
+    $$css: true
+  }
+};
+const arrowSizeStyles = {
+  sm: {
+    kzqmXN: "x1fvqzum",
+    kZKoxP: "x6k0iem",
+    $$css: true
+  },
+  md: {
+    kzqmXN: "x805d0l",
+    kZKoxP: "x1ueg155",
+    $$css: true
+  },
+  lg: {
+    kzqmXN: "x1m747yf",
+    kZKoxP: "xssyfek",
+    $$css: true
   }
 };
 
@@ -82,6 +240,8 @@ export function TabList({
   size: sizeProp,
   layout = 'hug',
   hasDivider = false,
+  role,
+  overflow = 'auto',
   xstyle,
   className,
   style,
@@ -90,6 +250,7 @@ export function TabList({
   onFocus: onFocusProp,
   onBlur: onBlurProp,
   'aria-label': ariaLabelFromProps,
+  'aria-labelledby': ariaLabelledBy,
   'aria-orientation': _ariaOrientation,
   [EDGE_COMP_ATTR]: _edgeCompAttr,
   ...restProps
@@ -97,13 +258,21 @@ export function TabList({
   const t = useTranslator();
   const ariaLabel = ariaLabelFromProps ?? t('@astryx.tabList.label');
   const size = useSize(sizeProp, 'md');
+  const hasScroll = overflow !== 'visible';
+  const stripRef = useRef(null);
+  // Only an asserted `role="tablist"` switches the pattern. Left unset the
+  // strip is the `<nav>` it has always been, and every other role passes
+  // through to the element untouched.
+  const isTabList = role === 'tablist';
 
   // Roving-tabindex keyboard navigation across the tab strip via the shared
-  // hook. `orientation: 'both'` accepts both arrow axes per the WAI-ARIA APG
-  // allowance for tab strips (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp
-  // retreat). We do not set `aria-orientation` on the `<nav>`: that attribute
-  // is invalid on the navigation role and triggers an axe `aria-allowed-attr`
-  // violation.
+  // hook. Under the navigation pattern `orientation: 'both'` accepts both
+  // arrow axes per the WAI-ARIA APG allowance for tab strips
+  // (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp retreat). A tablist
+  // reports itself as horizontal, so there the strip takes only the
+  // horizontal arrows and leaves ArrowUp and ArrowDown to scroll the page. We
+  // do not set `aria-orientation` on the `<nav>`: that attribute is invalid on
+  // the navigation role and triggers an axe `aria-allowed-attr` violation.
   //
   // `hasRovingTabIndex` makes the hook own the single tab stop: it stamps
   // tabindex 0/-1, repairs the stop on mount and as stops mount/unmount or
@@ -118,7 +287,7 @@ export function TabList({
     handleFocus
   } = useListFocus({
     itemSelector: TAB_STOP_SELECTOR,
-    orientation: 'both',
+    orientation: isTabList ? 'horizontal' : 'both',
     hasRovingTabIndex: true
   });
   const {
@@ -127,12 +296,105 @@ export function TabList({
     onFocus: onHintFocus,
     onBlur: onHintBlur
   } = useKeyboardHint();
+  const {
+    scrollRef,
+    overflowStart,
+    overflowEnd
+  } = useScrollOverflow();
+  const attachStrip = useCallback(el => {
+    stripRef.current = el;
+    scrollRef(hasScroll ? el : null);
+  }, [hasScroll, scrollRef]);
+  const revealStop = useCallback(stop => {
+    const strip = stripRef.current;
+    if (!hasScroll || !strip || !stop) {
+      return;
+    }
+    const stripBox = strip.getBoundingClientRect();
+    const stopBox = stop.getBoundingClientRect();
+    const inset = parseFloat(getComputedStyle(strip).scrollPaddingLeft) || 0;
+    const pastEnd = stopBox.right - (stripBox.right - inset);
+    const pastStart = stopBox.left - (stripBox.left + inset);
+    // A stop wider than the space kept clear cannot be shown whole, so show
+    // its reading start, the way `scrollIntoView({inline: 'nearest'})` does.
+    const tooWide = stopBox.width > stripBox.width - 2 * inset;
+    const delta = tooWide ? isRtlElement(strip) ? pastEnd : pastStart : pastEnd > 0 ? pastEnd : pastStart < 0 ? pastStart : 0;
+    if (delta !== 0) {
+      // Not an animation: the strip has to arrive already showing the right
+      // tab, so this overrides the CSS smooth behaviour arrow presses use.
+      strip.scrollBy({
+        left: delta,
+        behavior: 'instant'
+      });
+    }
+  }, [hasScroll]);
+  const revealSelectedTab = useCallback(() => {
+    const strip = stripRef.current;
+    if (!strip) {
+      return;
+    }
+    revealStop(Array.from(strip.querySelectorAll('[data-tab-value]')).find(el => el.dataset.tabValue === value) ?? null);
+  }, [revealStop, value]);
+
+  // Both reveals below reach the callback through a ref instead of depending
+  // on it: its identity also changes with `overflow`, and that is not a reason
+  // to scroll anything.
+  const revealSelectedTabRef = useRef(revealSelectedTab);
+  useEffect(() => {
+    revealSelectedTabRef.current = revealSelectedTab;
+  }, [revealSelectedTab]);
+
+  // The tab you are on has to be visible. Selection can move without focus —
+  // on mount, or when the host sets `value` itself — and neither scrolls the
+  // strip the way clicking or arrowing to a tab does. The check is what makes
+  // a selection change the trigger, rather than the effect happening to run.
+  const revealedValueRef = useRef(null);
+  useEffect(() => {
+    if (revealedValueRef.current === value) {
+      return;
+    }
+    revealedValueRef.current = value;
+    revealSelectedTabRef.current();
+  }, [value]);
+
+  // ...and it has to stay visible when the strip is what moved. A strip that
+  // fitted at one width can hide the selected tab at a narrower one, and no
+  // prop changes when that happens. This one re-reveals the same selection by
+  // design, which is why the check above sits in the effect rather than in
+  // `revealSelectedTab`.
+  //
+  // The wrapper is observed rather than the strip because the shared observer
+  // keeps one callback per element and `useScrollOverflow` already holds the
+  // strip's.
+  useEffect(() => {
+    const root = listRef.current;
+    if (!hasScroll || !root) {
+      return;
+    }
+    const onResize = () => revealSelectedTabRef.current();
+    observeResize(root, onResize);
+    return () => unobserveResize(root);
+  }, [hasScroll, listRef]);
+  const scrollByPage = useCallback(direction => {
+    const strip = stripRef.current;
+    if (!strip) {
+      return;
+    }
+    // Under RTL the scroll axis is inverted, so flip the physical delta.
+    const rtlSign = isRtlElement(strip) ? -1 : 1;
+    strip.scrollBy({
+      left: rtlSign * direction * strip.clientWidth * SCROLL_PAGE_RATIO
+    });
+  }, []);
+  const scrollToStart = useCallback(() => scrollByPage(-1), [scrollByPage]);
+  const scrollToEnd = useCallback(() => scrollByPage(1), [scrollByPage]);
   const contextValue = useMemo(() => ({
     value,
     onChange,
     size,
-    layout
-  }), [value, onChange, size, layout]);
+    layout,
+    pattern: isTabList ? 'tabs' : 'nav'
+  }), [value, onChange, size, layout, isTabList]);
   const handleRootKeyDown = useCallback(e => {
     onKeyDownProp?.(e);
     if (e.defaultPrevented) {
@@ -148,7 +410,11 @@ export function TabList({
     }
     onHintFocus(e);
     handleFocus(e);
-  }, [onFocusProp, onHintFocus, handleFocus]);
+    // The browser scrolls a focused element into view only when it is
+    // entirely outside the scrollport, so arrowing onto a half-visible stop
+    // leaves it cut off under the fade. Finish the job it started.
+    revealStop(e.target.closest(TAB_STOP_SELECTOR));
+  }, [onFocusProp, onHintFocus, handleFocus, revealStop]);
   const handleRootBlur = useCallback(e => {
     onBlurProp?.(e);
     if (e.defaultPrevented) {
@@ -156,12 +422,38 @@ export function TabList({
     }
     onHintBlur(e);
   }, [onBlurProp, onHintBlur]);
+
+  // `role="tablist"` owns only tabs, so anything else in the strip is invalid
+  // markup. Dev-only, and only under the asserted role — nothing else in the
+  // component reads the rendered DOM.
+  const hasWarnedContentRef = useRef(false);
+  useEffect(() => {
+    const strip = stripRef.current;
+    if (process.env.NODE_ENV === 'production' || !isTabList || !strip || hasWarnedContentRef.current) {
+      return;
+    }
+    const stranger = Array.from(strip.children).find(child => child.getAttribute('role') !== 'tab');
+    if (stranger) {
+      hasWarnedContentRef.current = true;
+      devWarn('TabList', `role="tablist" owns only tabs, but the strip contains a <${stranger.tagName.toLowerCase()}> that is not one. ` + 'Render menus and other controls outside the strip, or drop the role for the navigation pattern.');
+    }
+    // No dependency list: the check is on rendered DOM, which can change
+    // without any prop this component could watch.
+  });
+  const fadeStyle = !hasScroll ? null : overflowStart && overflowEnd ? styles.fadeBoth : overflowStart ? styles.fadeStart : overflowEnd ? styles.fadeEnd : null;
+
+  // A tablist is not navigation, so the landmark element is only right under
+  // the navigation pattern. The role is fixed by a prop rather than by what
+  // the strip happens to hold, so this is settled once at the callsite.
+  const Wrapper = isTabList ? 'div' : 'nav';
   return /*#__PURE__*/_jsx(TabListContext, {
     value: contextValue,
-    children: /*#__PURE__*/_jsxs("nav", {
-      ref: mergeRefs(ref, listRef),
+    children: /*#__PURE__*/_jsxs(Wrapper, {
+      ref: useMergedRefs(ref, listRef),
       ...restProps,
-      "aria-label": ariaLabel,
+      role: isTabList ? undefined : role,
+      "aria-label": isTabList ? undefined : ariaLabel,
+      "aria-labelledby": isTabList ? undefined : ariaLabelledBy,
       onKeyDown: handleRootKeyDown,
       onFocus: handleRootFocus,
       onBlur: handleRootBlur,
@@ -169,7 +461,45 @@ export function TabList({
       ...mergeProps(themeProps('tab-list', {
         size
       }), stylex.props(styles.nav, layout === 'fill' && styles.fill, hasDivider && styles.divider, xstyle), className, style),
-      children: [children, hintElement]
+      children: [/*#__PURE__*/_jsx("div", {
+        ref: attachStrip,
+        role: isTabList ? 'tablist' : undefined,
+        "aria-label": isTabList ? ariaLabel : undefined
+        // The name belongs to whichever element carries the widget role.
+        ,
+        "aria-labelledby": isTabList ? ariaLabelledBy : undefined,
+        ...mergeProps(themeProps('tab-strip'), stylex.props(styles.strip, hasScroll && styles.stripScroll, fadeStyle)),
+        children: children
+      }), hasScroll && overflowStart && /*#__PURE__*/_jsx("button", {
+        type: "button",
+        "aria-hidden": "true",
+        tabIndex: -1
+        // Nothing hidden from assistive technology should end up holding
+        // focus, and a click would put it here.
+        ,
+        onMouseDown: preventFocus,
+        onClick: scrollToStart,
+        ...mergeProps(themeProps('tab-scroll-button'), focusOutlineProps.focusVisible(styles.arrow, styles.arrowStart, arrowSizeStyles[size])),
+        children: /*#__PURE__*/_jsx(Icon, {
+          icon: "chevronLeft",
+          size: "sm",
+          color: "inherit",
+          xstyle: rtlStyles.mirror
+        })
+      }), hasScroll && overflowEnd && /*#__PURE__*/_jsx("button", {
+        type: "button",
+        "aria-hidden": "true",
+        tabIndex: -1,
+        onMouseDown: preventFocus,
+        onClick: scrollToEnd,
+        ...mergeProps(themeProps('tab-scroll-button'), focusOutlineProps.focusVisible(styles.arrow, styles.arrowEnd, arrowSizeStyles[size])),
+        children: /*#__PURE__*/_jsx(Icon, {
+          icon: "chevronRight",
+          size: "sm",
+          color: "inherit",
+          xstyle: rtlStyles.mirror
+        })
+      }), hintElement]
     })
   });
 }

package/dist/TabList/TabListContext.d.ts

@@ -10,13 +10,23 @@ export type TabListSize = 'sm' | 'md' | 'lg';
  */
 export type TabListLayout = 'hug' | 'fill';
 /**
- * Context for communicating value/onChange/size/layout from TabList to children.
+ * ARIA pattern the strip resolved to.
+ * - `'nav'`: a `<nav>` of links or buttons, current item marked with
+ *   `aria-current`.
+ * - `'tabs'`: the WAI-ARIA tabs pattern — `role="tablist"` / `role="tab"`,
+ *   `aria-selected`, and `aria-controls` for the panel each tab owns.
+ */
+export type TabListPattern = 'nav' | 'tabs';
+/**
+ * Context for communicating value/onChange/size/layout and the resolved ARIA
+ * pattern from TabList to children.
  */
 export interface TabListContextValue {
     value: string;
     onChange: (value: string) => void;
     size: TabListSize;
     layout: TabListLayout;
+    pattern: TabListPattern;
 }
 export declare const TabListContext: import("react").Context<TabListContextValue | null>;
 /**

package/dist/TabList/TabListContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TabListContext.d.ts","sourceRoot":"","sources":["../../src/TabList/TabListContext.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAC;AAG9E;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CASvD"}
+{"version":3,"file":"TabListContext.d.ts","sourceRoot":"","sources":["../../src/TabList/TabListContext.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAC;AAG9E;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CASvD"}

package/dist/TabList/TabListContext.js

@@ -5,7 +5,7 @@
 /**
  * @file TabListContext.ts
  * @input React createContext, use
- * @output Exports TabListContext, useTabListContext
+ * @output Exports TabListContext, useTabListContext, TabListPattern
  * @position Context provider; consumed by Tab.tsx, TabMenu.tsx
  *
  * SYNC: When modified, update /packages/core/src/TabList/TabList.doc.mjs
@@ -24,7 +24,16 @@ import { createContext, use } from 'react';
  */
 
 /**
- * Context for communicating value/onChange/size/layout from TabList to children.
+ * ARIA pattern the strip resolved to.
+ * - `'nav'`: a `<nav>` of links or buttons, current item marked with
+ *   `aria-current`.
+ * - `'tabs'`: the WAI-ARIA tabs pattern — `role="tablist"` / `role="tab"`,
+ *   `aria-selected`, and `aria-controls` for the panel each tab owns.
+ */
+
+/**
+ * Context for communicating value/onChange/size/layout and the resolved ARIA
+ * pattern from TabList to children.
  */
 
 export const TabListContext = /*#__PURE__*/createContext(null);

package/dist/TabList/TabMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TabMenu.d.ts","sourceRoot":"","sources":["../../src/TabList/TabMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAGxE,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAmBtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,CAAC,iBAAiB,CAAC,EAC5B,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AA+KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,GAAG,EACH,KAAK,EACL,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,qBA4Ld;yBAnMe,OAAO"}
+{"version":3,"file":"TabMenu.d.ts","sourceRoot":"","sources":["../../src/TabList/TabMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAGxE,OAAO,EAAiB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAoBtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,CAAC,iBAAiB,CAAC,EAC5B,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AA+KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,GAAG,EACH,KAAK,EACL,OAAO,EACP,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,qBA4Ld;yBAnMe,OAAO"}

package/dist/TabList/TabMenu.js

@@ -28,7 +28,8 @@ import { useListFocus } from "../hooks/useListFocus.js";
 import { useTabListContext } from "./TabListContext.js";
 import "./tab.markers.stylex.js";
 import { tabScope } from "./tab.markers.stylex.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // =============================================================================
@@ -227,7 +228,7 @@ export function TabMenu({
     tabListCtx.onChange(value);
     popover.hide();
   }, [tabListCtx, popover]);
-  const setButtonRef = mergeRefs(popover.triggerRef, buttonRef, ref);
+  const setButtonRef = useMergedRefs(popover.triggerRef, buttonRef, ref);
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsxs("button", {
       ref: setButtonRef,