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

package/src/TabList/TabList.tsx

@@ -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
@@ -17,20 +21,44 @@
  * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
  */
 
-import React, {useCallback, useMemo, type ReactNode} from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type AriaRole,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {borderVars, colorVars, spacingVars} from '../theme/tokens.stylex';
+import {
+  borderVars,
+  colorVars,
+  durationVars,
+  easeVars,
+  focusVars,
+  radiusVars,
+  shadowVars,
+  sizeVars,
+  spacingVars,
+} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {TabListContext} from './TabListContext';
 import type {TabListSize} from './TabListContext';
 import {useSize} from '../SizeContext/SizeContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import {useListFocus} from '../hooks/useListFocus';
 import {useKeyboardHint} from '../hooks/useKeyboardHint';
+import {useScrollOverflow} from '../hooks/useScrollOverflow';
+import {isRtlElement} from '../hooks/isRtlElement';
+import {Icon} from '../Icon';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
+import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
+import {devWarn} from '../utils/devWarning';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Selector matching the focusable stops in the tab strip: every Tab
  * (`[data-tab-value]`) and every TabMenu trigger (`[data-tab-menu]`),
@@ -38,6 +66,24 @@ import {useTranslator} from '../i18n';
  */
 const TAB_STOP_SELECTOR = '[data-tab-value],[data-tab-menu]';
 
+function preventFocus(e: React.MouseEvent) {
+  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.
+ */
+export type TabListOverflow = 'auto' | 'scroll' | 'visible';
+
 export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
   ref?: React.Ref<HTMLElement>;
   /**
@@ -66,12 +112,85 @@ 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.
    */
   children: ReactNode;
 }
 
+/**
+ * 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 = stylex.create({
   nav: {
     display: 'flex',
@@ -79,6 +198,7 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-0-5'],
     maxWidth: '100%',
     minWidth: 0,
+    position: 'relative',
   },
   fill: {
     width: '100%',
@@ -96,6 +216,114 @@ const styles = stylex.create({
     paddingBlockEnd: spacingVars['--spacing-1'],
     '--_tab-indicator-bottom': `calc(-1 * (${spacingVars['--spacing-1']} + ${borderVars['--border-width']}))`,
   },
+  strip: {
+    display: 'flex',
+    alignItems: 'stretch',
+    // Inherited rather than restated so an `xstyle` gap override on the
+    // TabList still reaches the tabs.
+    gap: 'inherit',
+    flexGrow: 1,
+    flexShrink: 1,
+    minWidth: 0,
+    // Content-height, not stretched: the bleed padding below is inside the
+    // strip's own height, and a stretched height would push the tabs out of
+    // the scrollport.
+    alignSelf: 'flex-start',
+  },
+  stripScroll: {
+    overflowX: 'auto',
+    overflowY: 'hidden',
+    overscrollBehaviorX: 'contain',
+    scrollPaddingInline: SCROLL_EDGE_INSET,
+    scrollbarWidth: 'none',
+    scrollBehavior: {
+      default: 'smooth',
+      '@media (prefers-reduced-motion: reduce)': 'auto',
+    },
+    [BLEED_VAR]: {
+      default: '0px',
+      ':has(:focus-visible)': RING_BLEED,
+    },
+    paddingBlockStart: BLEED,
+    marginBlockStart: `calc(-1 * (${BLEED}))`,
+    paddingBlockEnd: BLOCK_END_BLEED,
+    marginBlockEnd: `calc(-1 * (${BLOCK_END_BLEED}))`,
+    paddingInline: BLEED,
+    marginInline: `calc(-1 * (${BLEED}))`,
+    maskImage: 'none',
+    transitionProperty: 'mask-image',
+    transitionDuration: {
+      default: durationVars['--duration-medium'],
+      '@media (prefers-reduced-motion: reduce)': '0ms',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  fadeStart: {
+    maskImage: {
+      default: FADE_FROM_START,
+      ':is([dir="rtl"] *)': FADE_FROM_END,
+    },
+  },
+  fadeEnd: {
+    maskImage: {
+      default: FADE_FROM_END,
+      ':is([dir="rtl"] *)': FADE_FROM_START,
+    },
+  },
+  fadeBoth: {
+    maskImage: `linear-gradient(to right, transparent ${BLEED}, black ${SCROLL_EDGE_INSET}, black calc(100% - ${SCROLL_EDGE_INSET}), transparent calc(100% - ${BLEED}))`,
+  },
+  arrow: {
+    position: 'absolute',
+    insetBlockStart: 0,
+    // A pointer-only affordance: keyboard and assistive-technology users move
+    // through the strip with the arrow keys, which scrolls the focused tab
+    // into view on its own.
+    display: {
+      default: 'none',
+      '@media (hover: hover)': 'flex',
+    },
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    borderRadius: radiusVars['--radius-full'],
+    // Opaque, because it sits over the tabs it scrolls: the strip's edge fade
+    // thins the content underneath but does not clear it.
+    backgroundColor: colorVars['--color-background-popover'],
+    boxShadow: shadowVars['--shadow-low'],
+    color: {
+      default: colorVars['--color-text-secondary'],
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+        colorVars['--color-text-primary'],
+    },
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
+  },
+  arrowStart: {
+    insetInlineStart: 0,
+  },
+  arrowEnd: {
+    insetInlineEnd: 0,
+  },
+});
+
+const arrowSizeStyles = stylex.create({
+  sm: {
+    width: sizeVars['--size-element-sm'],
+    height: sizeVars['--size-element-sm'],
+  },
+  md: {
+    width: sizeVars['--size-element-md'],
+    height: sizeVars['--size-element-md'],
+  },
+  lg: {
+    width: sizeVars['--size-element-lg'],
+    height: sizeVars['--size-element-lg'],
+  },
 });
 
 /**
@@ -121,6 +349,8 @@ export function TabList({
   size: sizeProp,
   layout = 'hug',
   hasDivider = false,
+  role,
+  overflow = 'auto',
   xstyle,
   className,
   style,
@@ -129,6 +359,7 @@ export function TabList({
   onFocus: onFocusProp,
   onBlur: onBlurProp,
   'aria-label': ariaLabelFromProps,
+  'aria-labelledby': ariaLabelledBy,
   'aria-orientation': _ariaOrientation,
   [EDGE_COMP_ATTR]: _edgeCompAttr,
   ...restProps
@@ -136,13 +367,22 @@ 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<HTMLDivElement | null>(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
@@ -153,7 +393,7 @@ export function TabList({
   // the first enabled stop when none is tabbable.
   const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLElement>({
     itemSelector: TAB_STOP_SELECTOR,
-    orientation: 'both',
+    orientation: isTabList ? 'horizontal' : 'both',
     hasRovingTabIndex: true,
   });
 
@@ -164,9 +404,124 @@ export function TabList({
     onBlur: onHintBlur,
   } = useKeyboardHint();
 
+  const {scrollRef, overflowStart, overflowEnd} = useScrollOverflow();
+
+  const attachStrip = useCallback(
+    (el: HTMLDivElement | null) => {
+      stripRef.current = el;
+      scrollRef(hasScroll ? el : null);
+    },
+    [hasScroll, scrollRef],
+  );
+
+  const revealStop = useCallback(
+    (stop: HTMLElement | null) => {
+      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<HTMLElement>('[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<string | null>(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: -1 | 1) => {
+    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],
+    () => ({
+      value,
+      onChange,
+      size,
+      layout,
+      pattern: isTabList ? ('tabs' as const) : ('nav' as const),
+    }),
+    [value, onChange, size, layout, isTabList],
   );
 
   const handleRootKeyDown = useCallback(
@@ -189,8 +544,12 @@ export function TabList({
       }
       onHintFocus(e);
       handleFocus(e);
+      // 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],
+    [onFocusProp, onHintFocus, handleFocus, revealStop],
   );
 
   const handleRootBlur = useCallback(
@@ -204,12 +563,58 @@ export function TabList({
     [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 (
     <TabListContext value={contextValue}>
-      <nav
-        ref={mergeRefs(ref, listRef)}
+      <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}
@@ -225,9 +630,72 @@ export function TabList({
           className,
           style,
         )}>
-        {children}
+        <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}
+        </div>
+        {hasScroll && overflowStart && (
+          <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],
+              ),
+            )}>
+            <Icon
+              icon="chevronLeft"
+              size="sm"
+              color="inherit"
+              xstyle={rtlStyles.mirror}
+            />
+          </button>
+        )}
+        {hasScroll && overflowEnd && (
+          <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],
+              ),
+            )}>
+            <Icon
+              icon="chevronRight"
+              size="sm"
+              color="inherit"
+              xstyle={rtlStyles.mirror}
+            />
+          </button>
+        )}
         {hintElement}
-      </nav>
+      </Wrapper>
     </TabListContext>
   );
 }

package/src/TabList/TabListContext.ts

@@ -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
@@ -27,13 +27,24 @@ 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 const TabListContext = createContext<TabListContextValue | null>(null);

package/src/TabList/TabMenu.tsx

@@ -37,7 +37,8 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useTabListContext} from './TabListContext';
 import type {TabListSize} from './TabListContext';
 import {tabScope} from './tab.markers.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -336,7 +337,7 @@ export function TabMenu({
     [tabListCtx, popover],
   );
 
-  const setButtonRef = mergeRefs<HTMLButtonElement>(
+  const setButtonRef = useMergedRefs<HTMLButtonElement>(
     popover.triggerRef,
     buttonRef,
     ref,