@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/TabList/TabList.doc.mjs

@@ -16,6 +16,8 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-tab-list', visualProps: ['size']},
+      {className: 'astryx-tab-strip'},
+      {className: 'astryx-tab-scroll-button'},
       {className: 'astryx-tab', states: ['selected']},
       {className: 'astryx-tab-indicator', states: ['selected']},
       {className: 'astryx-tab-menu'},
@@ -26,7 +28,7 @@ export const docs = {
       {name: '--_tab-indicator-bottom', description: 'Vertical offset of the selected-tab indicator from the tab bottom edge. A host that draws its own bottom divider (Toolbar) sets this so the indicator sits on the divider instead of above it.', default: '-1px', private: true},
     ],
   },
-  description: 'Nav wrapper that provides TabListContext (value, onChange, size) to Tab and TabMenu children.',
+  description: 'Tab strip that provides TabListContext (value, onChange, size) to Tab and TabMenu children; a nav landmark, or the WAI-ARIA tabs pattern where role="tablist" asks for it.',
   props: [
     {
       name: 'value',
@@ -58,10 +60,21 @@ export const docs = {
       description: 'Whether to show a bottom border divider under the tab list.',
       default: 'false',
     },
+    {
+      name: 'role',
+      type: 'AriaRole',
+      description: "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 an href on a tab 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.",
+    },
+    {
+      name: 'overflow',
+      type: "'auto' | 'scroll' | 'visible'",
+      description: "What happens when the tabs are wider than the strip. 'auto' lets the component choose, which today always scrolls. 'scroll' scrolls the tabs horizontally, with edge fades and arrow affordances for pointers that can hover. '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'",
+    },
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Tab and TabMenu items to render inside the nav.',
+      description: 'Tab and TabMenu items to render inside the strip.',
       slotElements: [
         {
           __element: 'Tab',
@@ -88,8 +101,9 @@ export const docs = {
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     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: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { 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: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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.' },
@@ -109,8 +123,9 @@ export const docsZh = {
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     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: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { 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: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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.' },
@@ -125,14 +140,15 @@ export const docsZh = {
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Tab navigation w/ overflow menu support; semantic nav landmark w/ button or anchor tab items.',
+  description: 'Tab strip w/ overflow scrolling; nav landmark by default, WAI-ARIA tabs pattern under role="tablist".',
   usage: {
     description:
       'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
     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: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },
       { 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: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },
       { 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

@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TabList} from './TabList';
+import type {TabListProps} from './TabList';
 import {Tab} from './Tab';
 import {TabMenu} from './TabMenu';
 import {LinkProvider} from '../Link/LinkProvider';
@@ -960,3 +961,561 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
     expect(hidePopover).toHaveBeenCalled();
   });
 });
+
+describe('TabList overflow (scroll)', () => {
+  const STRIP = '.astryx-tab-strip';
+  const ARROW = '.astryx-tab-scroll-button';
+
+  /** jsdom has no layout, so the scroll box is described by hand. */
+  function fakeScrollBox(
+    strip: HTMLElement,
+    {
+      scrollWidth,
+      clientWidth,
+      scrollLeft = 0,
+    }: {scrollWidth: number; clientWidth: number; scrollLeft?: number},
+  ) {
+    Object.defineProperty(strip, 'scrollWidth', {
+      value: scrollWidth,
+      configurable: true,
+    });
+    Object.defineProperty(strip, 'clientWidth', {
+      value: clientWidth,
+      configurable: true,
+    });
+    Object.defineProperty(strip, 'scrollLeft', {
+      value: scrollLeft,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  /**
+   * Places the strip at 0..width and a tab at the given offsets, so the
+   * keep-selected-visible arithmetic has real numbers to work with.
+   */
+  function fakeGeometry(
+    strip: HTMLElement,
+    tabValue: string,
+    {
+      stripWidth,
+      tabLeft,
+      tabRight,
+    }: {stripWidth: number; tabLeft: number; tabRight: number},
+  ) {
+    strip.getBoundingClientRect = () =>
+      ({left: 0, right: stripWidth, width: stripWidth}) as DOMRect;
+    const tab = strip.querySelector<HTMLElement>(
+      `[data-tab-value="${tabValue}"]`,
+    );
+    if (tab) {
+      tab.getBoundingClientRect = () =>
+        ({
+          left: tabLeft,
+          right: tabRight,
+          width: tabRight - tabLeft,
+        }) as DOMRect;
+    }
+  }
+
+  function renderStrip(props: Partial<TabListProps> = {}) {
+    const utils = render(
+      <TabList value="a" onChange={() => {}} {...props}>
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+    const strip = utils.container.querySelector<HTMLElement>(STRIP);
+    if (!strip) {
+      throw new Error('no tab strip');
+    }
+    return {...utils, strip};
+  }
+
+  it('renders the tabs inside a scroll strip by default', () => {
+    const {strip} = renderStrip();
+    expect(strip.querySelectorAll('[data-tab-value]')).toHaveLength(3);
+  });
+
+  it('offers an end arrow while there are tabs past the end, and pressing it scrolls', () => {
+    const {container, strip} = renderStrip();
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    fireEvent.scroll(strip);
+
+    const arrows = container.querySelectorAll(ARROW);
+    expect(arrows).toHaveLength(1);
+
+    fireEvent.click(arrows[0]);
+    expect(scrollBy).toHaveBeenCalledWith({left: 240});
+  });
+
+  it('offers both arrows once the strip is scrolled away from the start', () => {
+    const {container, strip} = renderStrip();
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300, scrollLeft: 150});
+    strip.scrollBy = vi.fn();
+    fireEvent.scroll(strip);
+
+    expect(container.querySelectorAll(ARROW)).toHaveLength(2);
+  });
+
+  it('keeps the arrows out of the tab order and out of the accessibility tree', () => {
+    const {container, strip} = renderStrip();
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300});
+    strip.scrollBy = vi.fn();
+    fireEvent.scroll(strip);
+
+    const arrow = container.querySelector<HTMLElement>(ARROW);
+    expect(arrow?.getAttribute('aria-hidden')).toBe('true');
+    expect(arrow?.tabIndex).toBe(-1);
+  });
+
+  it('scrolls a selected tab that starts out of view back into view on mount', () => {
+    const scrollBy = vi.fn();
+    // The strip mounts before the effect runs, so the geometry has to be in
+    // place on the prototype rather than on an element we can reach first.
+    const originalScrollBy = Element.prototype.scrollBy;
+    const originalRect = Element.prototype.getBoundingClientRect;
+    Element.prototype.scrollBy = scrollBy;
+    Element.prototype.getBoundingClientRect = function (this: Element) {
+      return (
+        this.classList.contains('astryx-tab-strip')
+          ? {left: 0, right: 300, width: 300}
+          : {left: 420, right: 500, width: 80}
+      ) as DOMRect;
+    };
+
+    render(
+      <TabList value="c" onChange={() => {}}>
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(scrollBy).toHaveBeenCalledWith(
+      expect.objectContaining({behavior: 'instant'}),
+    );
+    expect(scrollBy.mock.calls[0][0].left).toBeGreaterThan(0);
+    Element.prototype.scrollBy = originalScrollBy;
+    Element.prototype.getBoundingClientRect = originalRect;
+  });
+
+  it('keeps the selected tab in view when the host changes value without focus', () => {
+    const {strip, rerender} = renderStrip({value: 'a'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: 420, tabRight: 500});
+
+    rerender(
+      <TabList value="c" onChange={() => {}}>
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+    expect(scrollBy.mock.calls[0][0].left).toBeGreaterThan(0);
+  });
+
+  it('leaves a tab that is already in view alone', () => {
+    const {strip, rerender} = renderStrip({value: 'a'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    fakeGeometry(strip, 'b', {stripWidth: 300, tabLeft: 80, tabRight: 140});
+
+    rerender(
+      <TabList value="b" onChange={() => {}}>
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(scrollBy).not.toHaveBeenCalled();
+  });
+
+  it('reveals on a selection change, not on an unrelated overflow change', () => {
+    const {strip, rerender} = renderStrip({value: 'c', overflow: 'visible'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: 420, tabRight: 500});
+
+    // Turning scrolling on re-measures the strip, and that one reveal is the
+    // resize path's. The selection has not moved, so nothing may add a second.
+    rerender(
+      <TabList value="c" onChange={() => {}} overflow="scroll">
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+
+    fakeGeometry(strip, 'a', {stripWidth: 300, tabLeft: -200, tabRight: -120});
+    rerender(
+      <TabList value="a" onChange={() => {}} overflow="scroll">
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(scrollBy).toHaveBeenCalledTimes(2);
+    expect(scrollBy.mock.calls[1][0].left).toBeLessThan(0);
+  });
+
+  it('finishes the job on focus: a tab only half in view is scrolled clear', () => {
+    const {strip} = renderStrip({value: 'a'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    // The browser scrolls a focused tab into view only when it is entirely
+    // outside the box, so this one — straddling the end edge — stays cut off.
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: 260, tabRight: 340});
+
+    const tab = strip.querySelector<HTMLElement>('[data-tab-value="c"]');
+    fireEvent.focus(tab!, {bubbles: true});
+
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+    expect(scrollBy.mock.calls[0][0].left).toBeCloseTo(40);
+  });
+
+  it('reveals a half-visible overflow menu trigger too, not just tabs', () => {
+    const {container} = render(
+      <TabList value="a" onChange={() => {}}>
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <TabMenu label="More" options={[{value: 'c', label: 'Gamma'}]} />
+      </TabList>,
+    );
+    const strip = container.querySelector<HTMLElement>(STRIP);
+    if (!strip) {
+      throw new Error('no tab strip');
+    }
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    strip.getBoundingClientRect = () =>
+      ({left: 0, right: 300, width: 300}) as DOMRect;
+    const trigger = strip.querySelector<HTMLElement>('[data-tab-menu]');
+    if (!trigger) {
+      throw new Error('no menu trigger');
+    }
+    trigger.getBoundingClientRect = () =>
+      ({left: 260, right: 340, width: 80}) as DOMRect;
+
+    fireEvent.focus(trigger, {bubbles: true});
+
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+    expect(scrollBy.mock.calls[0][0].left).toBeCloseTo(40);
+  });
+
+  it('fades out at the strip’s own edge, not at the bleed edge', () => {
+    // The scroll box is a ring-bleed wider than the TabList on each side while
+    // it holds focus, so a fade that ran to the box edge would paint tabs
+    // outside the component and past the arrow that caps that edge.
+    const bleed = 'var(--_tab-strip-bleed)';
+    const {strip} = renderStrip();
+    strip.scrollBy = vi.fn();
+
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300});
+    fireEvent.scroll(strip);
+    expect(getComputedStyle(strip).maskImage).toContain(`transparent ${bleed}`);
+
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300, scrollLeft: 150});
+    fireEvent.scroll(strip);
+    expect(getComputedStyle(strip).maskImage).toContain(
+      `transparent calc(100% - ${bleed})`,
+    );
+  });
+
+  it('is no wider than the TabList until the strip holds focus', () => {
+    // The bleed is real geometry: while the strip carries it, its border box
+    // sticks out of the TabList's and every ancestor that scrolls counts it.
+    // jsdom has no layout, so the box is read off the declarations: padding
+    // and its cancelling margin are both the bleed, and the bleed is zero
+    // until a ring needs keeping whole. `:has(:focus-visible)` flips it --
+    // covered in a browser, since jsdom does not recompute style on a focus
+    // change.
+    const {strip} = renderStrip();
+    const cs = getComputedStyle(strip);
+
+    expect(cs.getPropertyValue('--_tab-strip-bleed')).toBe('0px');
+    expect(cs.paddingInline).toBe('var(--_tab-strip-bleed)');
+    expect(cs.marginInline).toBe('calc(-1 * (var(--_tab-strip-bleed)))');
+  });
+
+  it('does not hand focus to an arrow, which is hidden from assistive tech', () => {
+    const {container, strip} = renderStrip();
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300});
+    strip.scrollBy = vi.fn();
+    fireEvent.scroll(strip);
+
+    const arrow = container.querySelector<HTMLElement>(ARROW);
+    const prevented = !fireEvent.mouseDown(arrow!);
+    expect(prevented).toBe(true);
+  });
+
+  it('overflow="visible" scrolls nothing and offers no arrows', () => {
+    const {container, strip, rerender} = renderStrip({
+      value: 'a',
+      overflow: 'visible',
+    });
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    fakeScrollBox(strip, {scrollWidth: 600, clientWidth: 300});
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: 420, tabRight: 500});
+    fireEvent.scroll(strip);
+
+    rerender(
+      <TabList value="c" onChange={() => {}} overflow="visible">
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+        <Tab value="c" label="Gamma" />
+      </TabList>,
+    );
+
+    expect(container.querySelectorAll(ARROW)).toHaveLength(0);
+    expect(scrollBy).not.toHaveBeenCalled();
+  });
+
+  it('shows the reading start of a stop too wide to fit', () => {
+    const {strip} = renderStrip({value: 'a'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    // Wider than the strip, so one end stays hidden either way. Aligning the
+    // end would land a long label on its last words.
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: 420, tabRight: 800});
+
+    const tab = strip.querySelector<HTMLElement>('[data-tab-value="c"]');
+    fireEvent.focus(tab!, {bubbles: true});
+
+    expect(scrollBy.mock.calls[0][0].left).toBeCloseTo(420);
+  });
+
+  it('shows the reading start of an over-wide stop in RTL too', () => {
+    const {strip} = renderStrip({value: 'a'});
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    strip.style.direction = 'rtl';
+    fakeGeometry(strip, 'c', {stripWidth: 300, tabLeft: -500, tabRight: -120});
+
+    const tab = strip.querySelector<HTMLElement>('[data-tab-value="c"]');
+    fireEvent.focus(tab!, {bubbles: true});
+
+    // RTL reads from the right edge, so that is the end to bring flush.
+    expect(scrollBy.mock.calls[0][0].left).toBeCloseTo(-420);
+  });
+});
+
+describe('TabList ARIA pattern — role="tablist"', () => {
+  function warnSpy() {
+    return vi.spyOn(console, 'warn').mockImplementation(() => {});
+  }
+
+  it('speaks the tabs pattern: a labelled tablist of tabs with aria-selected', () => {
+    render(
+      <TabList value="b" onChange={() => {}} role="tablist" aria-label="Views">
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+        <Tab value="b" label="Beta" panelId="panel-b" />
+      </TabList>,
+    );
+
+    const tablist = screen.getByRole('tablist', {name: 'Views'});
+    const tabs = screen.getAllByRole('tab');
+    expect(tabs).toHaveLength(2);
+    expect(tabs.every(tab => tablist.contains(tab))).toBe(true);
+    expect(tabs[0]).toHaveAttribute('aria-selected', 'false');
+    expect(tabs[1]).toHaveAttribute('aria-selected', 'true');
+    expect(tabs[1]).toHaveAttribute('aria-controls', 'panel-b');
+    expect(tabs[1]).not.toHaveAttribute('aria-current');
+  });
+
+  it('lets the consumer name the tablist from another element', () => {
+    render(
+      <>
+        <h2 id="views-heading">Project views</h2>
+        <TabList
+          value="a"
+          onChange={() => {}}
+          role="tablist"
+          aria-labelledby="views-heading">
+          <Tab value="a" label="Alpha" panelId="panel-a" />
+        </TabList>
+      </>,
+    );
+
+    expect(screen.getByRole('tablist', {name: 'Project views'})).not.toBeNull();
+  });
+
+  it('renders no navigation landmark around the tabs', () => {
+    const {container} = render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+      </TabList>,
+    );
+
+    expect(container.querySelector('nav')).toBeNull();
+    expect(screen.queryByRole('navigation')).toBeNull();
+  });
+
+  it('omits aria-controls when a tab has no panel, and says so', () => {
+    const warn = warnSpy();
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('tab')).not.toHaveAttribute('aria-controls');
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Tab: a tab in a role="tablist" TabList controls nothing',
+      ),
+    );
+    warn.mockRestore();
+  });
+
+  it('leaves a hand-wired aria-controls alone, and does not ask for a panelId it already has', () => {
+    const warn = warnSpy();
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" aria-controls="panel-written-by-hand" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('tab')).toHaveAttribute(
+      'aria-controls',
+      'panel-written-by-hand',
+    );
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('ignores href: the tab is a button, and the caller is told', () => {
+    const warn = warnSpy();
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" panelId="panel-a" href="/alpha" />
+      </TabList>,
+    );
+
+    const tab = screen.getByRole('tab');
+    expect(tab.tagName).toBe('BUTTON');
+    expect(tab).not.toHaveAttribute('href');
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('Tab: href is ignored in a role="tablist"'),
+    );
+    warn.mockRestore();
+  });
+
+  it('warns about anything in the strip that is not a tab, however it got there', () => {
+    const warn = warnSpy();
+    const showMenu = true;
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+        {showMenu ? (
+          <div>
+            <TabMenu label="More" options={[{value: 'b', label: 'Beta'}]} />
+          </div>
+        ) : null}
+      </TabList>,
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('TabList: role="tablist" owns only tabs'),
+    );
+    warn.mockRestore();
+  });
+
+  it('says nothing when the strip holds only tabs with panels', () => {
+    const warn = warnSpy();
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+        <Tab value="b" label="Beta" panelId="panel-b" />
+      </TabList>,
+    );
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('leaves ArrowDown and ArrowUp to the page', async () => {
+    // A tablist reports itself as horizontal, so the vertical arrows are the
+    // page's to scroll with.
+    const user = userEvent.setup();
+    render(
+      <TabList value="a" onChange={() => {}} role="tablist">
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+        <Tab value="b" label="Beta" panelId="panel-b" />
+      </TabList>,
+    );
+
+    const alpha = screen.getByRole('tab', {name: 'Alpha'});
+    alpha.focus();
+    await user.keyboard('{ArrowDown}');
+    expect(alpha).toHaveFocus();
+  });
+});
+
+describe('TabList ARIA pattern — no role', () => {
+  it('is the navigation landmark it has always been', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(
+      <TabList value="a" onChange={() => {}} aria-label="Views">
+        <Tab value="a" label="Alpha" />
+        <Tab value="b" label="Beta" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('navigation', {name: 'Views'})).toBeInTheDocument();
+    expect(screen.queryByRole('tablist')).toBeNull();
+    expect(screen.getByRole('button', {name: 'Alpha'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('drops a panelId and says so: there is no panel relationship to state', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(
+      <TabList value="a" onChange={() => {}}>
+        <Tab value="a" label="Alpha" panelId="panel-a" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('button', {name: 'Alpha'})).not.toHaveAttribute(
+      'aria-controls',
+    );
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Tab: panelId does nothing outside a role="tablist" TabList',
+      ),
+    );
+    warn.mockRestore();
+  });
+});
+
+describe('TabList ARIA pattern — any other role', () => {
+  it('passes the role through and leaves the tabs on the navigation pattern', () => {
+    const {container} = render(
+      <TabList value="a" onChange={() => {}} role="toolbar">
+        <Tab value="a" label="Alpha" />
+      </TabList>,
+    );
+
+    expect(container.querySelector('nav')).toHaveAttribute('role', 'toolbar');
+    expect(screen.queryByRole('tablist')).toBeNull();
+    expect(screen.getByRole('button', {name: 'Alpha'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+  });
+});