@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/Selector/Selector.tsx

@@ -4,15 +4,17 @@
 
 /**
  * @file Selector.tsx
- * @input Uses React, StyleX, usePopover, useTooltip, Icon, InputGroupContext,
- *   and Selector positioning hooks
- * @output Exports Selector component
+ * @input Uses React, StyleX, adaptive selection surfaces, theme-resolved
+ *   indicators, Field, and InputGroup context
+ * @output Exports Selector with content-derived option-mark layout
  * @position Core implementation; consumed by index.ts
  *
  * SYNC: When modified, update:
+ * - /packages/core/src/Selector/Selector.spec.md
  * - /packages/core/src/Selector/Selector.doc.mjs
  * - /packages/core/src/Selector/Selector.test.tsx
  * - /packages/core/src/Selector/index.ts
+ * - /apps/storybook/stories/Selector.stories.tsx
  * - /apps/storybook/stories/InputGroup.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/Selector/ (showcase blocks)
  */
@@ -102,9 +104,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-3'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     // A FIXED line box, not the ratio: the trigger's padding is derived from
     // one line being `--spacing-5` tall, and a ratio makes the line box track
@@ -362,18 +369,20 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
-  // The mark's column, reserved on every row and at either position, so a row
-  // occupies the same geometry whether or not it is the chosen one — the
-  // default check draws nothing when unchecked, and without the column a list
-  // would indent (or truncate) its chosen row differently from the rest.
-  // `minWidth` rather than `width`: a theme can replace `check` with a larger
-  // indicator (a radio is 20px at `sm`), and the column has to grow with it.
+  // The wrapper keeps a visible mark at either logical position and lets a
+  // replacement indicator grow beyond the default 1rem minimum. When the
+  // resolved indicator draws nothing, `:empty` removes the wrapper from layout
+  // instead of reserving blank space. Selected and unselected labels may
+  // therefore shift or have different available width by design (AST-004).
   itemMarkColumn: {
     display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
     flexShrink: 0,
     minWidth: '1rem',
+    ':empty': {
+      display: 'none',
+    },
   },
   itemCheckmark: {
     flexShrink: 0,
@@ -649,10 +658,10 @@ interface SelectorPropsBase<
   renderValue?: (option: SelectorOptionData) => ReactNode;
 
   /**
-   * Which edge of the option row carries the selected mark. `start` reserves a
-   * mark column ahead of every label so they stay aligned, the way a native
-   * menu does; `end` is the house convention shared with Typeahead and
-   * CommandPalette.
+   * Which logical edge of the option row carries a rendered selection mark. An
+   * empty mark consumes no space, so selected and unselected labels may shift or
+   * have different available width. `end` is the house convention shared with
+   * Typeahead and CommandPalette.
    *
    * @default 'end'
    */

package/src/Selector/__tests__/Listbox.a11y.chromium.spec.ts

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.chromium.spec.ts
+ * @input Uses the Listbox contract, browser harness, state inventory, and checked-in stories
+ * @output DOM/accessibility-tree evidence for each real Listbox binding part
+ * @position Browser binding; keyboard policy, pixels, and real AT remain separate owners.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  LISTBOX_PATTERN,
+  checkAccessibilitySpec,
+  blockingResults,
+  formatFailures,
+  formatReport,
+  summarize,
+  neverExercised,
+  unmatchedKnownFailures,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  serveStorybook,
+  DEFAULT_STORYBOOK_DIR,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {LISTBOX_KNOWN_FAILURES} from './Listbox.a11y.known-failures';
+import {LISTBOX_SCENARIOS, listboxParts} from './Listbox.a11y.states';
+
+let storybook: StaticServer;
+const observedResults: BindingResult[] = [];
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+  expect(
+    unmatchedKnownFailures(LISTBOX_KNOWN_FAILURES, observedResults),
+  ).toEqual([]);
+});
+
+for (const scenario of LISTBOX_SCENARIOS) {
+  test(`${scenario.component} — ${scenario.id}`, async ({page}) => {
+    test.setTimeout(2 * 60 * 1000);
+    const cdp = await page.context().newCDPSession(page);
+    const results: BindingResult[] = [];
+    const mount = async () => {
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=a11y-listbox-pattern--${scenario.id}&viewMode=story&globals=direction:${scenario.direction ?? 'ltr'}`,
+        {waitUntil: 'load'},
+      );
+      await holdMotionStill(page);
+      await expect(
+        page.locator(`[data-listbox-scenario="${scenario.id}"]`),
+      ).toBeAttached();
+      await page.getByRole('listbox').waitFor({state: 'visible'});
+      if (scenario.query != null) {
+        await page.getByRole('combobox').fill(scenario.query);
+      }
+      await expect(page.getByRole('listbox').getByRole('option')).toHaveCount(
+        scenario.expectedOptions.length,
+      );
+    };
+
+    for (const part of listboxParts(scenario)) {
+      results.push(
+        await checkAccessibilitySpec({
+          spec: LISTBOX_PATTERN,
+          binding: `${scenario.component}.${part.role}`,
+          state: part.state,
+          facts: part.facts,
+          knownFailures: LISTBOX_KNOWN_FAILURES,
+          mount: async () => {
+            await mount();
+            const listbox = page.getByRole('listbox');
+            const subject =
+              part.role === 'listbox'
+                ? listbox
+                : part.role === 'group'
+                  ? listbox
+                      .getByRole('group')
+                      .nth(scenario.groups.indexOf(part.name ?? ''))
+                  : listbox.getByRole('option', {
+                      name: part.name,
+                      exact: true,
+                    });
+            return createChromiumHarness({
+              page,
+              cdp,
+              subject,
+              related: {
+                listbox,
+                ...Object.fromEntries(
+                  scenario.expectedOptions.map(option => [
+                    `option:${option.value}`,
+                    listbox.getByRole('option', {
+                      name: option.name,
+                      exact: true,
+                    }),
+                  ]),
+                ),
+                ...Object.fromEntries(
+                  scenario.groups.map((name, index) => [
+                    `group:${name}`,
+                    listbox.getByRole('group').nth(index),
+                  ]),
+                ),
+              },
+            });
+          },
+        }),
+      );
+    }
+
+    observedResults.push(...results);
+    const report = summarize(LISTBOX_PATTERN, results);
+    console.log(formatReport(report));
+    expect(formatFailures(blockingResults(results))).toBe('');
+    expect(report.counts.unrun).toBe(0);
+    if (scenario.component === 'Selector' && scenario.groups.length > 0) {
+      expect(neverExercised(results)).toEqual([]);
+    }
+  });
+}

package/src/Selector/__tests__/Listbox.a11y.dom.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.dom.ts
+ * @input Uses Vitest lifecycle hooks and the DOM Dialog prototype
+ * @output Scoped stubs for Dialog methods missing from jsdom
+ * @position DOM-only binding setup; these stubs prove no native modal behavior.
+ */
+
+import {afterAll, beforeAll} from 'vitest';
+
+export function installListboxDialogStubs(): void {
+  const originals = new Map<string, PropertyDescriptor | undefined>();
+  beforeAll(() => {
+    for (const name of ['show', 'showModal', 'close']) {
+      originals.set(
+        name,
+        Object.getOwnPropertyDescriptor(HTMLDialogElement.prototype, name),
+      );
+      Object.defineProperty(HTMLDialogElement.prototype, name, {
+        configurable: true,
+        writable: true,
+        value: function (this: HTMLDialogElement) {
+          this.open = name !== 'close';
+        },
+      });
+    }
+  });
+  afterAll(() => {
+    for (const [name, descriptor] of originals) {
+      if (descriptor == null) {
+        Reflect.deleteProperty(HTMLDialogElement.prototype, name);
+      } else {
+        Object.defineProperty(HTMLDialogElement.prototype, name, descriptor);
+      }
+    }
+  });
+}

package/src/Selector/__tests__/Listbox.a11y.inventory.test.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.inventory.test.ts
+ * @input Uses the locked Listbox migration matrix and checklist
+ * @output Coverage-boundary and part-inventory regression checks
+ * @position Binding metadata proof, separate from runtime conformance results.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {LISTBOX_PATTERN, unansweredDimensions} from '@astryxdesign/a11y-spec';
+import {LISTBOX_KNOWN_FAILURES} from './Listbox.a11y.known-failures';
+import {
+  LISTBOX_SCENARIOS,
+  LISTBOX_EXCLUSIONS,
+  listboxParts,
+} from './Listbox.a11y.states';
+
+describe('Listbox migration inventory', () => {
+  it('accounts for every checklist dimension without claiming other evidence layers', () => {
+    expect(unansweredDimensions(LISTBOX_PATTERN)).toEqual([]);
+    expect(LISTBOX_EXCLUSIONS).toHaveLength(5);
+  });
+
+  it('binds 21 scenarios and all six real semantic parts', () => {
+    expect(LISTBOX_SCENARIOS).toHaveLength(21);
+    const parts = LISTBOX_SCENARIOS.flatMap(scenario =>
+      listboxParts(scenario).map(part => ({
+        binding: `${scenario.component}.${part.role}`,
+        state: part.state,
+      })),
+    );
+    expect(parts).toHaveLength(89);
+    expect(new Set(parts.map(part => part.state)).size).toBe(89);
+    expect([...new Set(parts.map(part => part.binding))].sort()).toEqual([
+      'MultiSelector.group',
+      'MultiSelector.listbox',
+      'MultiSelector.option',
+      'Selector.group',
+      'Selector.listbox',
+      'Selector.option',
+    ]);
+  });
+
+  it('pins each known failure to one exact inventory part', () => {
+    const parts = LISTBOX_SCENARIOS.flatMap(scenario =>
+      listboxParts(scenario).map(part => ({
+        binding: `${scenario.component}.${part.role}`,
+        state: part.state,
+      })),
+    );
+
+    expect(LISTBOX_KNOWN_FAILURES).toHaveLength(2);
+    for (const record of LISTBOX_KNOWN_FAILURES) {
+      expect(
+        parts.filter(
+          part =>
+            part.binding === record.binding && part.state === record.state,
+        ),
+      ).toHaveLength(1);
+    }
+  });
+});

package/src/Selector/__tests__/Listbox.a11y.known-failures.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Exact public-safe Selector and MultiSelector listbox migration failures
+ * @position AST-021 debt records; operational ownership remains outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const LISTBOX_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+  {
+    expectation: 'listbox.exposure.identity',
+    binding: 'Selector.listbox',
+    state: 'single-sheet:listbox',
+    evidenceLayer: 'accessibility-tree',
+    failureEquals: 'the browser exposes the listbox without an accessible name',
+    standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+    userImpact:
+      'An accessibility consumer encounters an unnamed listbox in the bottom-sheet presentation and cannot identify what set of choices it contains.',
+    reason:
+      'The no-search bottom-sheet presentation renders a visible sheet heading without assigning that heading, or another label, as the listbox accessible name. This migration records the existing behavior without changing the component.',
+  },
+  {
+    expectation: 'listbox.exposure.identity',
+    binding: 'MultiSelector.listbox',
+    state: 'multiple-sheet:listbox',
+    evidenceLayer: 'accessibility-tree',
+    failureEquals: 'the browser exposes the listbox without an accessible name',
+    standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+    userImpact:
+      'An accessibility consumer encounters an unnamed multi-select listbox in the bottom-sheet presentation and cannot identify what set of choices it contains.',
+    reason:
+      'The no-search bottom-sheet presentation renders a visible sheet heading without assigning that heading, or another label, as the listbox accessible name. This migration records the existing behavior without changing the component.',
+  },
+];

package/src/Selector/__tests__/Listbox.a11y.states.ts

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.states.ts
+ * @input Uses public Selector option types and the shared Listbox facts
+ * @output A bounded, explicit inventory of existing listbox/group/option states
+ * @position Test-only migration ledger shared by component tests and browser stories.
+ */
+
+import type {ListboxStateFacts} from '@astryxdesign/a11y-spec';
+import type {SelectorOptionType} from '../types';
+
+export interface ListboxScenario {
+  readonly id: string;
+  readonly component: 'Selector' | 'MultiSelector';
+  readonly options: SelectorOptionType[];
+  readonly values: string[];
+  readonly expectedOptions: ReadonlyArray<{
+    value: string;
+    name: string;
+    disabled: boolean;
+    selected?: boolean;
+    group?: string;
+  }>;
+  readonly groups: ReadonlyArray<string>;
+  readonly hasSearch?: boolean;
+  readonly query?: string;
+  readonly presentation?: 'popover' | 'bottom-sheet';
+  readonly customContent?: boolean;
+  readonly hiddenLabel?: boolean;
+  readonly direction?: 'ltr' | 'rtl';
+  readonly isLoading?: boolean;
+  readonly hasSelectAll?: boolean;
+}
+
+const flatOptions: SelectorOptionType[] = [
+  {value: 'apple', label: 'Apple'},
+  {value: 'banana', label: 'Banana'},
+  {value: 'cherry', label: 'Cherry', disabled: true},
+];
+const flatExpected = [
+  {value: 'apple', name: 'Apple', disabled: false},
+  {value: 'banana', name: 'Banana', disabled: false},
+  {value: 'cherry', name: 'Cherry', disabled: true},
+];
+const groupedOptions: SelectorOptionType[] = [
+  {
+    type: 'section',
+    title: 'Citrus',
+    options: [
+      {value: 'orange', label: 'Orange'},
+      {value: 'lemon', label: 'Lemon'},
+    ],
+  },
+  {type: 'divider'},
+  {
+    type: 'section',
+    title: 'Berries',
+    options: [{value: 'blueberry', label: 'Blueberry', disabled: true}],
+  },
+];
+const groupedExpected = [
+  {value: 'orange', name: 'Orange', disabled: false, group: 'Citrus'},
+  {value: 'lemon', name: 'Lemon', disabled: false, group: 'Citrus'},
+  {value: 'blueberry', name: 'Blueberry', disabled: true, group: 'Berries'},
+];
+
+function scenarios(component: ListboxScenario['component']): ListboxScenario[] {
+  const prefix = component === 'Selector' ? 'single' : 'multiple';
+  const base = {
+    component,
+    options: flatOptions,
+    expectedOptions: flatExpected,
+    groups: [],
+  };
+  return [
+    {...base, id: `${prefix}-unset`, values: []},
+    {
+      ...base,
+      id: `${prefix}-selected`,
+      values: component === 'Selector' ? ['apple'] : ['apple', 'banana'],
+    },
+    {...base, id: `${prefix}-disabled-selected`, values: ['cherry']},
+    {
+      ...base,
+      id: `${prefix}-grouped`,
+      options: groupedOptions,
+      values: ['orange'],
+      expectedOptions: groupedExpected,
+      groups: ['Citrus', 'Berries'],
+    },
+    {
+      ...base,
+      id: `${prefix}-filtered`,
+      options: groupedOptions,
+      values: ['orange'],
+      expectedOptions: [
+        {value: 'lemon', name: 'Lemon', disabled: false, group: 'Citrus'},
+      ],
+      groups: ['Citrus'],
+      hasSearch: true,
+      query: 'lem',
+    },
+    {
+      ...base,
+      id: `${prefix}-custom-rtl`,
+      values: ['banana'],
+      customContent: true,
+      hiddenLabel: true,
+      direction: 'rtl',
+      expectedOptions: [
+        {value: 'apple', name: 'Apple details', disabled: false},
+        {value: 'banana', name: 'Banana details', disabled: false},
+        {value: 'cherry', name: 'Cherry details', disabled: true},
+      ],
+    },
+    {
+      ...base,
+      id: `${prefix}-sheet`,
+      values: ['apple'],
+      presentation: 'bottom-sheet',
+    },
+    {
+      ...base,
+      id: `${prefix}-sheet-search`,
+      values: ['banana'],
+      presentation: 'bottom-sheet',
+      hasSearch: true,
+    },
+    {...base, id: `${prefix}-loading`, values: ['apple'], isLoading: true},
+  ];
+}
+
+export const LISTBOX_SCENARIOS: ReadonlyArray<ListboxScenario> = [
+  ...scenarios('Selector'),
+  ...scenarios('MultiSelector'),
+  ...(['none', 'partial', 'all'] as const).map(state => ({
+    id: `multiple-select-all-${state}`,
+    component: 'MultiSelector' as const,
+    options: flatOptions,
+    values:
+      state === 'none'
+        ? []
+        : state === 'partial'
+          ? ['apple']
+          : ['apple', 'banana'],
+    groups: [],
+    hasSelectAll: true,
+    expectedOptions: [
+      {
+        value: 'select-all',
+        name:
+          state === 'partial' ? 'Select all, partially selected' : 'Select all',
+        disabled: false,
+        selected: state === 'all',
+      },
+      ...flatExpected,
+    ],
+  })),
+];
+
+export interface ListboxBindingPart {
+  readonly role: 'listbox' | 'group' | 'option';
+  readonly name?: string;
+  readonly state: string;
+  readonly facts: ListboxStateFacts;
+}
+
+export function listboxParts(
+  scenario: ListboxScenario,
+): ReadonlyArray<ListboxBindingPart> {
+  const multiple = scenario.component === 'MultiSelector';
+  return [
+    {
+      role: 'listbox',
+      state: `${scenario.id}:listbox`,
+      facts: {
+        part: 'listbox',
+        multiple,
+        optionRelations: scenario.expectedOptions.map(
+          option => `option:${option.value}`,
+        ),
+      },
+    },
+    ...scenario.groups.map(name => ({
+      role: 'group' as const,
+      name,
+      state: `${scenario.id}:group:${name}`,
+      facts: {part: 'group' as const, multiple},
+    })),
+    ...scenario.expectedOptions.map(option => ({
+      role: 'option' as const,
+      name: option.name,
+      state: `${scenario.id}:option:${option.value}`,
+      facts: {
+        part: 'option' as const,
+        multiple,
+        selected: option.selected ?? scenario.values.includes(option.value),
+        disabled: option.disabled,
+        ownerGroup: option.group == null ? undefined : `group:${option.group}`,
+      },
+    })),
+  ];
+}
+
+export const LISTBOX_EXCLUSIONS = [
+  {
+    owner: 'Selector/MultiSelector trigger and search input',
+    reason:
+      'Combobox, field validation, required/read-only/disabled trigger state, and opening/closing are separate contracts. This slice observes active popup parts.',
+  },
+  {
+    owner: 'Selector/MultiSelector existing interaction suites',
+    reason:
+      'Keyboard selection, selection-follows-focus, disabled-option discovery, Home/End, typeahead, and callback policy are not newly adopted here.',
+  },
+  {
+    owner: 'Selector/MultiSelector empty-state and live-region owners',
+    reason:
+      'Zero-result representation and announcement timing require their own authority/evidence. No required option is invented for an empty listbox.',
+  },
+  {
+    owner: 'Typeahead, Tokenizer, PowerSearch, ComplexSelector, CommandPalette',
+    reason:
+      'Later bounded adopters; this first migration is limited to Selector and MultiSelector.',
+  },
+  {
+    owner: 'Component-specific suites',
+    reason:
+      'Public ID forwarding, callback payloads, forms, value formatting, sorting, required/error status, and styling stay local. Selector has no independent uncontrolled selected-value owner; an omitted value is the unset state.',
+  },
+] as const;