@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

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;

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

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Selector.a11y.chromium.spec.ts
+ * @input Uses the checked-in no-search bottom-sheet Storybook story and Chromium
+ * @output Chromium accessibility-tree regression coverage for the sheet listbox name
+ * @position Browser-only accessibility regression test for Selector
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+test('names the no-search bottom-sheet listbox from the Selector label', async ({
+  page,
+}) => {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-selector--bottom-sheet-presentation&viewMode=story`,
+    {waitUntil: 'load'},
+  );
+
+  await page.getByRole('combobox', {name: 'Team'}).click();
+
+  const listbox = page.getByRole('listbox');
+  await expect(listbox).toBeVisible();
+  // Playwright resolves this matcher from Chromium's accessibility tree, not
+  // the DOM attribute alone. The sheet is a modal layer, so a reference to the
+  // trigger outside it produces no name; this is the regression proof.
+  await expect(listbox).toHaveAccessibleName('Team');
+});

package/src/Selector/__tests__/Selector.listbox.a11y.test.tsx

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Selector.listbox.a11y.test.tsx
+ * @input Uses Selector, its explicit part/state inventory, and the Listbox contract
+ * @output DOM evidence for real single-select listbox, group, and option parts
+ * @position Component-facing binding; keyboard, callbacks, forms, and styles stay local.
+ */
+
+import {cleanup, render, screen, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {describe, expect, it} from 'vitest';
+import {
+  expectAccessibilitySpec,
+  LISTBOX_PATTERN,
+} from '@astryxdesign/a11y-spec';
+import {Selector} from '../Selector';
+import {LISTBOX_SCENARIOS, listboxParts} from './Listbox.a11y.states';
+import {installListboxDialogStubs} from './Listbox.a11y.dom';
+
+installListboxDialogStubs();
+
+const scenarios = LISTBOX_SCENARIOS.filter(
+  scenario => scenario.component === 'Selector',
+);
+
+describe('Selector Listbox semantic binding', () => {
+  it.each(scenarios)('$id', async scenario => {
+    for (const part of listboxParts(scenario)) {
+      await expectAccessibilitySpec({
+        spec: LISTBOX_PATTERN,
+        binding: `Selector.${part.role}`,
+        state: part.state,
+        facts: part.facts,
+        render: async () => {
+          render(
+            <div dir={scenario.direction ?? 'ltr'}>
+              <Selector
+                label="Fruit"
+                options={scenario.options}
+                value={scenario.values[0]}
+                onChange={() => {}}
+                hasSearch={scenario.hasSearch}
+                presentation={scenario.presentation}
+                isLoading={scenario.isLoading}
+                isLabelHidden={scenario.hiddenLabel}
+                renderOption={
+                  scenario.customContent
+                    ? option => <span>{option.label} details</span>
+                    : undefined
+                }
+                isDefaultOpen
+              />
+            </div>,
+          );
+          await screen.findByRole('listbox', {hidden: true});
+          if (scenario.query != null) {
+            await userEvent
+              .setup()
+              .type(
+                screen.getByRole('combobox', {hidden: true}),
+                scenario.query,
+              );
+          }
+        },
+        subject: () =>
+          part.role === 'listbox'
+            ? screen.getByRole('listbox', {hidden: true})
+            : part.role === 'group'
+              ? within(
+                  screen.getByRole('listbox', {hidden: true}),
+                ).getAllByRole('group', {hidden: true})[
+                  scenario.groups.indexOf(part.name ?? '')
+                ]
+              : within(screen.getByRole('listbox', {hidden: true})).getByRole(
+                  'option',
+                  {name: part.name, hidden: true},
+                ),
+        related: () => {
+          const listbox = screen.getByRole('listbox', {hidden: true});
+          expect(
+            within(listbox).getAllByRole('option', {hidden: true}),
+          ).toHaveLength(scenario.expectedOptions.length);
+          return {
+            listbox,
+            ...Object.fromEntries(
+              scenario.expectedOptions.map(option => [
+                `option:${option.value}`,
+                within(listbox).getByRole('option', {
+                  name: option.name,
+                  hidden: true,
+                }),
+              ]),
+            ),
+            ...Object.fromEntries(
+              scenario.groups.map((name, index) => [
+                `group:${name}`,
+                within(listbox).getAllByRole('group', {hidden: true})[index],
+              ]),
+            ),
+          };
+        },
+        cleanup,
+      });
+    }
+  });
+
+  it('keeps the bounded state matrix explicit', () => {
+    expect(scenarios.map(scenario => scenario.id)).toEqual([
+      'single-unset',
+      'single-selected',
+      'single-disabled-selected',
+      'single-grouped',
+      'single-filtered',
+      'single-custom-rtl',
+      'single-sheet',
+      'single-sheet-search',
+      'single-loading',
+    ]);
+  });
+});

package/src/SideNav/SideNav.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
       {className: 'astryx-side-nav-section'},
     ],
   },
-  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
+  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible and resizable modes.',
   props: [
     {
       name: 'header',

package/src/SideNav/SideNav.test.tsx

@@ -989,6 +989,16 @@ describe('SideNav resizable', () => {
     ).toBeInTheDocument();
   });
 
+  it('clips the overlay drag handle within the resizable nav bounds', () => {
+    render(<SideNav resizable>Content</SideNav>);
+    const nav = screen.getByRole('navigation');
+    const container = nav.parentElement;
+    const handle = screen.getByTestId('astryx-sidenav-resize-handle');
+
+    expect(container).toContainElement(handle);
+    expect(getComputedStyle(container!).overflow).toBe('clip');
+  });
+
   it('does not render drag handle without resizable', () => {
     render(<SideNav>Content</SideNav>);
     expect(

package/src/SideNav/SideNav.tsx

@@ -11,7 +11,8 @@
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
  *
- * Supports optional resize via drag handle at the inline-end edge.
+ * Supports optional resize via a drag handle at the inline-end edge. The
+ * resizable wrapper clips handle overflow while keeping its focus ring inside.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/SideNav/SideNav.doc.mjs
@@ -25,7 +26,7 @@ import {useCallback, useImperativeHandle, useRef, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {spacingVars} from '../theme/tokens.stylex';
+import {focusVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {
   SideNavCollapseContext,
@@ -241,6 +242,16 @@ const styles = stylex.create({
     display: 'flex',
     flexShrink: 0,
     height: '100%',
+    overflow: 'clip',
+  },
+  resizableHandle: {
+    // Keep the shared ring inside the clipping boundary. The wrapper cannot
+    // use overflow-clip-margin: that paint allowance also contributes the
+    // overlay's half-pixel spill to AppShell's scrollable overflow.
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': `calc(0px - ${focusVars['--focus-outline-width']})`,
+    },
   },
   // Topbar mode — horizontal layout for mobile top bar
   topbar: {
@@ -658,6 +669,7 @@ export function SideNav({
         position="overlay"
         pillPlacement="end"
         isAlwaysVisible={false}
+        xstyle={styles.resizableHandle}
         resizable={resizableHook.props}
         label={t('@astryx.sideNav.resizeSidebar')}
       />

package/src/Slider/Slider.doc.mjs

@@ -160,7 +160,8 @@ export const docs = {
     {
       name: 'marks',
       type: 'Array<{ value: number; label?: string }>',
-      description: 'Tick marks at specified positions with optional labels.',
+      description:
+        'Tick marks at specified positions with optional labels. Unfilled marks use the track color; marks inside the filled region (at or behind the thumb, or between the thumbs in range mode) use the fill color.',
     },
     {
       name: 'minStepsBetweenThumbs',
@@ -255,6 +256,17 @@ export const docs = {
     ],
   },
   usage: {
+    accessibility: [
+      {
+        name: 'Thumb',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'The thumb must have at least 3:1 contrast with the track and the surface behind it. Pointer down is the whole drag: measure the thumb with the pressed overlay applied.',
+      },
+    ],
     anatomy,
     description:
       'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
@@ -354,7 +366,8 @@ export const docsZh = {
     {
       name: 'marks',
       type: 'Array<{ value: number; label?: string }>',
-      description: '在指定位置的刻度标记，带可选标签。',
+      description:
+        '在指定位置的刻度标记，带可选标签。未填充区域的标记使用轨道颜色；填充区域内的标记使用强调色。',
     },
     {
       name: 'minStepsBetweenThumbs',
@@ -520,7 +533,8 @@ export const docsDense = {
     orientation: 'Slider orientation.',
     formatValue: 'Custom value formatting fn for display + aria-valuetext.',
     valueDisplay: 'How current value is displayed.',
-    marks: 'Tick marks at specified positions w/ optional labels.',
+    marks:
+      'Tick marks at specified positions w/ optional labels. Unfilled marks use the track color; filled marks use the accent color.',
     minStepsBetweenThumbs:
       'Min steps between thumbs in range mode; prevents overlap.',
     isDisabled: 'Whether slider is disabled.',