@astryxdesign/core 0.6.0 → 0.6.1

package/src/TabList/__tests__/Tabs.a11y.known-failures.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tabs.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Exact public-safe Tabs migration failures
+ * @position AST-021 debt records; operational ownership remains outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+const COMMON = {
+  binding: 'Tab',
+  state: 'tab-disabled-unselected',
+  evidenceLayer: 'real-browser',
+  standardsReference:
+    'WCAG 2.2 4.1.2 Name, Role, Value; WAI-ARIA 1.2 aria-disabled',
+  reason:
+    'This migration records the existing behavior without changing the component interaction contract.',
+} as const;
+
+export const TABS_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+  {
+    ...COMMON,
+    expectation: 'tabs.tab.unavailable-pointer-inert',
+    failureEquals:
+      'the tab is reported unavailable, but clicking it selected it',
+    userImpact:
+      'A pointer user can activate a tab that assistive technology reports as unavailable.',
+  },
+  {
+    ...COMMON,
+    expectation: 'tabs.tab.unavailable-enter-inert',
+    failureEquals: 'the tab is reported unavailable, but Enter selected it',
+    userImpact:
+      'A keyboard user can activate a focusable tab with Enter after assistive technology reports it unavailable.',
+  },
+  {
+    ...COMMON,
+    expectation: 'tabs.tab.unavailable-space-inert',
+    failureEquals: 'the tab is reported unavailable, but Space selected it',
+    userImpact:
+      'A keyboard user can activate a focusable tab with Space after assistive technology reports it unavailable.',
+  },
+];

package/src/TabList/__tests__/Tabs.a11y.renders.tsx

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Tabs.a11y.renders.tsx
+ * @input Uses TabList, Tab, React state, and the checked Tabs state inventory
+ * @output Consumer-realistic explicit Tabs render functions shared by jsdom and Storybook
+ * @position Binding fixture layer; navigation, callbacks, styling, and TabMenu stay local.
+ */
+
+import {useState, type ReactElement} from 'react';
+import {Tab, TabList} from '../index';
+import type {TabsStateId} from './Tabs.a11y.states';
+
+function TabsFixture({
+  direction = 'ltr',
+  disabledActivity = false,
+  hiddenSelectedLabel = false,
+}: {
+  direction?: 'ltr' | 'rtl';
+  disabledActivity?: boolean;
+  hiddenSelectedLabel?: boolean;
+}) {
+  const [value, setValue] = useState('overview');
+  const panels = {
+    overview: 'Everything at a glance.',
+    activity: 'What happened recently.',
+    members: 'Who has access.',
+  } as const;
+
+  return (
+    <div dir={direction}>
+      <button type="button">Before tabs</button>
+      <TabList
+        value={value}
+        onChange={setValue}
+        role="tablist"
+        aria-label="Project views">
+        <Tab
+          value="overview"
+          label="Overview"
+          id="tabs-a11y-tab-overview"
+          panelId="tabs-a11y-panel-overview"
+          isLabelHidden={hiddenSelectedLabel}
+          icon={
+            hiddenSelectedLabel ? <span aria-hidden="true">▣</span> : undefined
+          }
+        />
+        <Tab
+          value="activity"
+          label="Activity"
+          id="tabs-a11y-tab-activity"
+          panelId="tabs-a11y-panel-activity"
+          aria-disabled={disabledActivity || undefined}
+        />
+        <Tab
+          value="members"
+          label="Members"
+          id="tabs-a11y-tab-members"
+          panelId="tabs-a11y-panel-members"
+        />
+      </TabList>
+      {Object.entries(panels).map(([key, content]) => (
+        <div
+          key={key}
+          id={`tabs-a11y-panel-${key}`}
+          role="tabpanel"
+          aria-labelledby={`tabs-a11y-tab-${key}`}
+          tabIndex={0}
+          hidden={value !== key}>
+          {content}
+        </div>
+      ))}
+      <button type="button">After tabs</button>
+    </div>
+  );
+}
+
+export type TabsStateRender = () => ReactElement;
+
+export const TABS_STATE_RENDERS: Record<TabsStateId, TabsStateRender> = {
+  'tab-list-selected-ltr': () => <TabsFixture />,
+  'tab-list-selected-rtl': () => <TabsFixture direction="rtl" />,
+  'tab-list-disabled-skip': () => <TabsFixture disabledActivity />,
+  'tab-selected-visible-label': () => <TabsFixture />,
+  'tab-unselected-visible-label': () => <TabsFixture />,
+  'tab-disabled-unselected': () => <TabsFixture disabledActivity />,
+  'tab-selected-hidden-label': () => <TabsFixture hiddenSelectedLabel />,
+  'tabpanel-active': () => <TabsFixture />,
+  'tabpanel-inactive': () => <TabsFixture />,
+};

package/src/TabList/__tests__/Tabs.a11y.states.ts

@@ -0,0 +1,247 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tabs.a11y.states.ts
+ * @input Uses TabsStateFacts from @astryxdesign/a11y-spec
+ * @output The AST-021 binding inventory for explicit TabList Tabs parts and states
+ * @position Data-only inventory shared by jsdom, Storybook, and Chromium bindings.
+ */
+
+import type {TabsStateFacts} from '@astryxdesign/a11y-spec';
+
+export type TabsBinding = 'TabList' | 'Tab' | 'TabsComposition';
+
+export interface TabsRelation {
+  readonly selector: string;
+}
+
+export interface TabsBindingState {
+  readonly id: string;
+  readonly binding: TabsBinding;
+  readonly summary: string;
+  readonly facts: TabsStateFacts;
+  readonly subject:
+    | {readonly role: 'tablist' | 'tab'; readonly name: string}
+    | {readonly selector: string};
+  readonly relations?: Readonly<Record<string, TabsRelation>>;
+  readonly storyId: string;
+}
+
+export type TabsBindingRow = (typeof TABS_BINDING_STATES)[number];
+export type TabsStateId = (typeof TABS_BINDING_STATES)[number]['id'];
+
+const RELATIONS = {
+  first: {selector: '[role="tab"][data-tab-value="overview"]'},
+  second: {selector: '[role="tab"][data-tab-value="activity"]'},
+  third: {selector: '[role="tab"][data-tab-value="members"]'},
+  panel: {selector: '#tabs-a11y-panel-activity[role="tabpanel"]'},
+  tab: {selector: '#tabs-a11y-tab-overview[role="tab"]'},
+  'panel-first': {selector: '#tabs-a11y-panel-overview[role="tabpanel"]'},
+  'panel-second': {selector: '#tabs-a11y-panel-activity[role="tabpanel"]'},
+  'panel-third': {selector: '#tabs-a11y-panel-members[role="tabpanel"]'},
+} as const;
+
+function tablistFacts(overrides: Partial<TabsStateFacts> = {}): TabsStateFacts {
+  return {
+    part: 'tablist',
+    selected: null,
+    active: null,
+    disabled: null,
+    focusable: null,
+    visibleLabel: true,
+    controlsPanel: false,
+    controlledPanel: null,
+    labelledByTab: false,
+    labellingTab: null,
+    tabRelations: ['first', 'second', 'third'],
+    panelRelations: ['panel-first', 'panel-second', 'panel-third'],
+    disabledTabs: [],
+    selectedTab: 'first',
+    direction: 'ltr',
+    manualActivation: true,
+    tabReachable: true,
+    pointerSelection: true,
+    pointerCancellation: false,
+    ...overrides,
+  };
+}
+
+function tabFacts(overrides: Partial<TabsStateFacts> = {}): TabsStateFacts {
+  return tablistFacts({
+    part: 'tab',
+    selected: true,
+    disabled: false,
+    focusable: true,
+    controlsPanel: true,
+    controlledPanel: 'panel',
+    tabRelations: [],
+    panelRelations: [],
+    selectedTab: null,
+    pointerSelection: false,
+    pointerCancellation: true,
+    ...overrides,
+  });
+}
+
+function panelFacts(overrides: Partial<TabsStateFacts> = {}): TabsStateFacts {
+  return tablistFacts({
+    part: 'tabpanel',
+    selected: null,
+    active: true,
+    disabled: null,
+    focusable: null,
+    controlsPanel: false,
+    controlledPanel: null,
+    labelledByTab: true,
+    labellingTab: 'tab',
+    tabRelations: [],
+    panelRelations: [],
+    selectedTab: null,
+    tabReachable: false,
+    pointerSelection: false,
+    pointerCancellation: false,
+    ...overrides,
+  });
+}
+
+const story = (id: string) => `a11y-tabs-pattern--${id}`;
+
+export const TABS_BINDING_STATES = [
+  {
+    id: 'tab-list-selected-ltr',
+    binding: 'TabList',
+    summary: 'an explicit horizontal LTR tablist with manual activation',
+    facts: tablistFacts(),
+    subject: {role: 'tablist', name: 'Project views'},
+    relations: RELATIONS,
+    storyId: story('tab-list-selected-ltr'),
+  },
+  {
+    id: 'tab-list-selected-rtl',
+    binding: 'TabList',
+    summary: 'an explicit horizontal RTL tablist with logical arrow movement',
+    facts: tablistFacts({direction: 'rtl'}),
+    subject: {role: 'tablist', name: 'Project views'},
+    relations: RELATIONS,
+    storyId: story('tab-list-selected-rtl'),
+  },
+  {
+    id: 'tab-list-disabled-skip',
+    binding: 'TabList',
+    summary: 'a tablist whose unavailable middle tab is skipped by arrows',
+    facts: tablistFacts({disabledTabs: ['second']}),
+    subject: {role: 'tablist', name: 'Project views'},
+    relations: RELATIONS,
+    storyId: story('tab-list-disabled-skip'),
+  },
+  {
+    id: 'tab-selected-visible-label',
+    binding: 'Tab',
+    summary: 'the selected available tab with a visible label',
+    facts: tabFacts(),
+    subject: {role: 'tab', name: 'Overview'},
+    relations: {
+      panel: {selector: '#tabs-a11y-panel-overview[role="tabpanel"]'},
+    },
+    storyId: story('tab-selected-visible-label'),
+  },
+  {
+    id: 'tab-unselected-visible-label',
+    binding: 'Tab',
+    summary: 'an available unselected tab with a visible label',
+    facts: tabFacts({selected: false, tabReachable: false}),
+    subject: {role: 'tab', name: 'Activity'},
+    relations: {panel: RELATIONS.panel},
+    storyId: story('tab-unselected-visible-label'),
+  },
+  {
+    id: 'tab-disabled-unselected',
+    binding: 'Tab',
+    summary: 'an unavailable unselected tab outside the roving order',
+    facts: tabFacts({
+      selected: false,
+      disabled: true,
+      tabReachable: false,
+      pointerCancellation: false,
+    }),
+    subject: {role: 'tab', name: 'Activity'},
+    relations: {panel: RELATIONS.panel},
+    storyId: story('tab-disabled-unselected'),
+  },
+  {
+    id: 'tab-selected-hidden-label',
+    binding: 'Tab',
+    summary: 'a selected icon-only tab named programmatically',
+    facts: tabFacts({visibleLabel: false}),
+    subject: {role: 'tab', name: 'Overview'},
+    relations: {
+      panel: {selector: '#tabs-a11y-panel-overview[role="tabpanel"]'},
+    },
+    storyId: story('tab-selected-hidden-label'),
+  },
+  {
+    id: 'tabpanel-active',
+    binding: 'TabsComposition',
+    summary: 'the visible panel labelled by the selected tab',
+    facts: panelFacts(),
+    subject: {selector: '#tabs-a11y-panel-overview[role="tabpanel"]'},
+    relations: {tab: RELATIONS.tab},
+    storyId: story('tabpanel-active'),
+  },
+  {
+    id: 'tabpanel-inactive',
+    binding: 'TabsComposition',
+    summary: 'an inactive hidden panel labelled by its tab',
+    facts: panelFacts({active: false}),
+    subject: {selector: '#tabs-a11y-panel-activity[role="tabpanel"]'},
+    relations: {
+      tab: {selector: '#tabs-a11y-tab-activity[role="tab"]'},
+    },
+    storyId: story('tabpanel-inactive'),
+  },
+] as const satisfies ReadonlyArray<TabsBindingState>;
+
+export const TABS_EXCLUSIONS = [
+  {
+    owner: 'TabList and Tab without role="tablist"',
+    classification: 'out-of-scope',
+    reason:
+      'The default navigation pattern remains a nav landmark with aria-current and belongs to navigation semantics, not the ARIA Tabs contract.',
+  },
+  {
+    owner: 'TabMenu trigger, popup, and options',
+    classification: 'out-of-scope',
+    reason:
+      'TabMenu is a menu-button, menu, and radio-menu composition and is invalid as a child of an explicit tablist.',
+  },
+  {
+    owner: 'The table-filter page template’s narrow-view Tabs composition',
+    classification: 'out-of-scope',
+    reason:
+      'The public template currently points every tab at one shared panel and labels that panel independently. Its page-owned composition mismatch is recorded separately rather than changing a template inside this pattern-migration pull request.',
+  },
+  {
+    owner: 'Home and End shortcuts',
+    classification: 'preserved',
+    reason:
+      'The component keeps its local coverage; these APG-optional shortcuts are not promoted into the shared contract.',
+  },
+  {
+    owner: 'Vertical Tabs and automatic activation',
+    classification: 'needs-human',
+    reason:
+      'Neither mode is currently exposed by TabList, and adopting either changes public behavior and interaction policy.',
+  },
+  {
+    owner: 'A public TabPanel primitive or generated relationship ids',
+    classification: 'needs-human',
+    reason:
+      'The current API leaves panel elements and ids with the caller; introducing a primitive or ownership change is public API design.',
+  },
+  {
+    owner: 'No-selection, multi-selection, or selected-disabled policy',
+    classification: 'needs-human',
+    reason:
+      'The current controlled API can be given invalid values, but no current record defines the supported recovery policy.',
+  },
+] as const;

package/src/TabList/__tests__/Tabs.a11y.test.tsx

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Tabs.a11y.test.tsx
+ * @input Uses the shared Tabs contract and complete explicit-Tabs binding inventory
+ * @output DOM-layer binding evidence; browser-owned outcomes remain explicitly unrun
+ * @position Fast migration lane for TabList, Tab, and caller-authored panel composition.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TABS_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {TABS_KNOWN_FAILURES} from './Tabs.a11y.known-failures';
+import {TABS_STATE_RENDERS} from './Tabs.a11y.renders';
+import {
+  TABS_BINDING_STATES,
+  TABS_EXCLUSIONS,
+  type TabsBindingRow,
+} from './Tabs.a11y.states';
+
+function subjectFor(state: TabsBindingRow): Element {
+  if ('selector' in state.subject) {
+    const element = document.querySelector(state.subject.selector);
+    if (element == null) {
+      throw new Error(`no subject for ${state.id}`);
+    }
+    return element;
+  }
+  return screen.getByRole(state.subject.role, {
+    name: state.subject.name,
+    hidden: true,
+  });
+}
+
+function relatedFor(state: TabsBindingRow): Readonly<Record<string, Element>> {
+  return Object.fromEntries(
+    Object.entries(state.relations ?? {}).map(([name, relation]) => {
+      const element = document.querySelector(relation.selector);
+      if (element == null) {
+        throw new Error(`no related subject "${name}" for ${state.id}`);
+      }
+      return [name, element];
+    }),
+  );
+}
+
+async function expectState(state: TabsBindingRow): Promise<void> {
+  await expectAccessibilitySpec({
+    spec: TABS_PATTERN,
+    binding: state.binding,
+    state: state.id,
+    facts: state.facts,
+    knownFailures: TABS_KNOWN_FAILURES,
+    render: () => {
+      render(TABS_STATE_RENDERS[state.id]());
+    },
+    subject: () => subjectFor(state),
+    related: () => relatedFor(state),
+    cleanup,
+  });
+}
+
+async function checkState(state: TabsBindingRow): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TABS_PATTERN,
+    binding: state.binding,
+    state: state.id,
+    facts: state.facts,
+    knownFailures: TABS_KNOWN_FAILURES,
+    mount: async () => {
+      render(TABS_STATE_RENDERS[state.id]());
+      return createJsdomHarness({
+        subject: subjectFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('the shared Tabs pattern, jsdom lane', () => {
+  it.each(
+    TABS_BINDING_STATES.map(
+      state =>
+        [`${state.binding} [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectState(state);
+  });
+
+  it('runs the DOM layer and reports higher layers as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TABS_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TABS_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('the explicit Tabs binding inventory', () => {
+  it('names a distinct checked-in story for every state', () => {
+    const ids = TABS_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('binds TabList, Tab, and caller-authored panel composition', () => {
+    expect(
+      [...new Set(TABS_BINDING_STATES.map(state => state.binding))].sort(),
+    ).toEqual(['Tab', 'TabList', 'TabsComposition']);
+  });
+
+  it('records excluded and unsettled surfaces explicitly', () => {
+    expect(TABS_EXCLUSIONS.map(row => row.classification)).toEqual([
+      'out-of-scope',
+      'out-of-scope',
+      'out-of-scope',
+      'preserved',
+      'needs-human',
+      'needs-human',
+      'needs-human',
+    ]);
+    expect(TABS_EXCLUSIONS.every(row => row.reason.length > 0)).toBe(true);
+  });
+
+  it('binds only explicit horizontal manual-activation Tabs', () => {
+    const wrong = TABS_BINDING_STATES.filter(state => {
+      if (state.facts.part !== 'tablist') {
+        return false;
+      }
+      return !state.facts.manualActivation;
+    });
+    expect(wrong).toEqual([]);
+  });
+
+  it('renders exactly one subject for every state', () => {
+    for (const state of TABS_BINDING_STATES) {
+      render(TABS_STATE_RENDERS[state.id]());
+      expect(subjectFor(state), state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});

package/src/Table/Table.doc.mjs

@@ -131,8 +131,8 @@ export const docs = {
       {className: 'astryx-table-row'},
       {className: 'astryx-table-cell', visualProps: ['density']},
       {className: 'astryx-table-header-cell', visualProps: ['density']},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {className: 'astryx-base-table', deprecatedFor: 'table'},
     ],
   },

package/src/TextArea/TextArea.doc.mjs

@@ -277,8 +277,8 @@ export const docs = {
       },
       {className: 'astryx-text-area-control'},
       {className: 'astryx-text-area-counter'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {
         className: 'astryx-textarea',
         visualProps: ['size', 'status'],
@@ -533,8 +533,8 @@ export const docsZh = {
       },
       {className: 'astryx-text-area-control'},
       {className: 'astryx-text-area-counter'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {
         className: 'astryx-textarea',
         visualProps: ['size', 'status'],

package/src/TextArea/TextArea.tsx

@@ -571,8 +571,8 @@ export function TextArea({
               disabled: isDisabled ? 'disabled' : null,
               readonly: isReadOnly ? 'readonly' : null,
             },
-            // `textarea` ran the compound name together; themes styling it
-            // keep working until the next major.
+            // `textarea` ran the compound name together; keep it emitted so
+            // existing themes continue to work.
             {legacyNames: ['textarea']},
           ),
           stylex.props(

package/src/TextInput/TextInput.doc.mjs

@@ -74,7 +74,8 @@ export const docs = {
     {
       name: 'onEnter',
       type: '() => void',
-      description: 'Callback fired when the user presses the Enter key.',
+      description:
+        'Callback fired when the user presses the Enter key. IME-safe: Enter used to commit a Japanese/Chinese/Korean conversion does not fire it.',
     },
     {
       name: 'onKeyDown',