@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e4f8e4e

package/src/ProgressBar/ProgressBar.spec.md

@@ -0,0 +1,208 @@
+---
+schema_version: 1
+template_version: 1
+kind: component
+id: component:ProgressBar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by: [packages/core/src/ProgressBar/ProgressBar.test.tsx]
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:theme-authoring-contract,
+    architecture:theme-tokens,
+  ]
+contributing: []
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
+---
+
+# ProgressBar component contract
+
+## Intent
+
+ProgressBar communicates the progress of an operation. A determinate bar must be
+a sufficient standalone visual: people must be able to distinguish completed
+from remaining progress without depending on visible text rendered elsewhere.
+External text may supplement the bar, but it is not a prerequisite for the bar
+to be correct.
+
+This draft is intentionally limited to that visual-completeness requirement and
+the resulting public-API boundary. It does not choose a visual treatment.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; this draft changes no runtime behavior.
+- Compatibility class: documentation-only draft; no public API is added, removed,
+  or changed.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: `component:ProgressBar/DEC-1`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- A sufficient standalone visual distinction between completed and remaining
+  progress for every determinate presentation the component provides.
+- Internal resolution of that visual treatment when the caller supplies ordinary
+  progress state.
+
+**Does not own / non-goals**
+
+- External visible labels, values, or descriptions — owned by the product
+  callsite and supplementary to the bar.
+- The exact standalone contrast treatment — still a human design decision.
+- Theme token definitions — owned by `architecture:theme-tokens`.
+- Public API that makes visual correctness depend on caller-declared external
+  content — governed by `architecture:public-component-api` and `spec:AST-002`.
+
+## Public concepts
+
+| Concept             | Closed values or states                                    | Meaning                                                         | Availability by variant/orientation/state | Default                         | Owner                   | Stability          | Invalid-value behavior         |
+| ------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- | ------------------------------- | ----------------------- | ------------------ | ------------------------------ |
+| Progress mode       | `determinate`, `indeterminate`                             | Whether completed progress is known                             | All variants                              | Determinate                     | `component:ProgressBar` | Stable current API | Existing prop handling applies |
+| Built-in value text | Shown or hidden                                            | Optional visible text supplement generated by ProgressBar       | Determinate only                          | Hidden                          | `component:ProgressBar` | Stable current API | Ignored when indeterminate     |
+| Visual treatment    | One sufficient standalone treatment; exact form unresolved | How the graphic distinguishes completed from remaining progress | Determinate progress                      | Sufficient standalone treatment | `component:ProgressBar` | Draft decision     | No incomplete public mode      |
+
+The current public props remain documented in `ProgressBar.doc.mjs`. This draft
+does not turn nearby external content into a ProgressBar concept.
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                              | Basis                                                              | Draft review state     |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------- |
+| FR1 | Every determinate presentation ProgressBar provides MUST be a sufficient standalone visual for distinguishing completed from remaining progress. | `component:ProgressBar/DEC-1`; existing non-text contrast standard | Settled                |
+| FR2 | External visible text MAY supplement the bar but MUST NOT be required for the bar's visual correctness.                                          | `component:ProgressBar/DEC-1`                                      | Settled                |
+| FR3 | ProgressBar MUST NOT make visual correctness depend on caller-declared external content that it cannot verify or associate.                      | `component:ProgressBar/DEC-1`; `spec:AST-002`                      | Settled                |
+| FR4 | Supplementary text or graphics MUST NOT substitute for a sufficient distinction between completed and remaining progress.                        | `component:ProgressBar/DEC-1`                                      | Settled                |
+| FR5 | Public API MAY be considered only after the component has a correct base behavior and a stable caller-owned distinction still remains.           | `component:ProgressBar/DEC-1`; `spec:AST-002`                      | Settled admission gate |
+
+### Observed current behavior
+
+These observations describe `main`; they are not design approval from this
+draft:
+
+- Determinate progress renders a semantic-color fill over a muted track.
+- `hasValueLabel` optionally renders formatted value text in the component.
+- Callers may compose other visible text outside the component.
+- The current public theming surface exposes root, fill, track, and mark targets;
+  variant state is reflected on the root, fill, and mark targets.
+- Current unit tests cover value semantics, labels, variants, determinate and
+  indeterminate modes, disabled rendering, marks, and public target names. They
+  do not establish a sufficient standalone completed-versus-remaining visual
+  across shipped themes.
+
+### Allowed variation
+
+- **AV1 — Exact visual treatment.** Shape, token choice, and other rendering
+  details may vary if every resulting presentation satisfies FR1.
+- **AV2 — Themes.** Themes may express their visual language through the current
+  theming system while preserving the standalone distinction.
+
+### Representative states
+
+| State                                  | Required invariant                                                          | Allowed variation                                                                             |
+| -------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Determinate, partial progress          | Completed and remaining progress are distinguishable from the graphic alone | Exact visual treatment and semantic variant                                                   |
+| Determinate with built-in value text   | The graphic still satisfies FR1; value text supplements it                  | Value formatting                                                                              |
+| Determinate with external visible text | The graphic still satisfies FR1 without relying on that text                | Callsite composition                                                                          |
+| Indeterminate                          | Communicates ongoing activity without claiming a completed amount           | Existing animation and theme variation; completed-versus-remaining distinction does not apply |
+
+### Transformation and precedence order
+
+- **ORD1 — Progress state before presentation.** Resolve determinate or
+  indeterminate behavior from component state, then render a treatment valid for
+  that mode. External content does not weaken the determinate visual requirement.
+
+### Performance and resources
+
+- **PR1 — No external-content inspection.** ProgressBar MUST NOT add DOM
+  observation, measurement, or relationship discovery to decide whether nearby
+  visible text makes a weaker bar acceptable.
+
+## Accessibility contract
+
+- **AR1 — Standalone non-text distinction.** A determinate bar MUST satisfy the
+  applicable non-text contrast requirement without relying on external visible
+  text.
+- **AR2 — Programmatic semantics remain present.** The current required
+  accessible name and determinate value semantics remain independent of the
+  visible treatment.
+- **AR3 — Supplementary text is not inferred.** ProgressBar MUST NOT claim that
+  external text is present, visible, equivalent, or correctly associated when it
+  cannot encode or verify those facts.
+
+## Design relationships
+
+| Anatomy or state                     | Design requirement                          | Representation authority | Hierarchy role | Component contract |
+| ------------------------------------ | ------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Determinate fill and remaining track | Sufficient standalone distinction           | Unsettled                | Prominent      | FR1, AR1           |
+| Built-in or external visible value   | Supplements rather than enables correctness | Prescribed               | Supporting     | FR2, AR3           |
+
+The component implements design requirements without copying their rationale.
+The standalone visual remains a human design decision; this contract does not
+invent its form.
+
+## Family and system relationships
+
+- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a
+  caller-owned distinction justifies a public prop.
+- `architecture:component-theming-surface` governs which stable visible parts and
+  states become public theme capabilities.
+- `architecture:theme-authoring-contract` governs how themes override those
+  component capabilities without creating a second component contract.
+- `architecture:theme-tokens` governs the semantic token vocabulary used by the
+  eventual treatment.
+
+## Verification map
+
+| Contract      | Verification                                                                    | Representative states                                       | Mutation or failure expectation                                          | Audit section                          |
+| ------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------- |
+| FR1, AR1      | Real-browser visual and contrast evidence across shipped themes and color modes | Partial determinate progress for each semantic variant      | A completed or remaining segment becomes indistinguishable without text  | Future ProgressBar visual audit        |
+| FR2, FR3, AR3 | Public type and consumer-doc review                                             | No value text, built-in value text, external composed text  | A caller signal is credited with correctness the component cannot verify | Future ProgressBar API tests           |
+| AR2           | `ProgressBar.test.tsx`                                                          | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change         | Future ProgressBar accessibility audit |
+| Theming       | Theme-target metadata checks plus browser evidence                              | Shipped themes, light and dark modes                        | A theme override bypasses the standalone distinction                     | Future ProgressBar theming audit       |
+
+## Decision log
+
+### DEC-1 — ProgressBar owns a sufficient standalone visual
+
+**Reference:** `component:ProgressBar/DEC-1`  
+**Decider:** `cixzhang`, `2026-08-30`
+
+ProgressBar must provide a sufficient standalone visual. Visible text inside or
+outside the component may improve understanding, but the bar remains responsible
+for communicating completed versus remaining progress without it.
+
+Public API must not make that correctness depend on external content the
+component cannot carry, associate, or verify. Solve the component behavior first.
+Consider new API only when a stable caller-owned distinction still remains after
+the base behavior is correct.
+
+Rejected: weakening the bar based on a caller claim about nearby content. That
+would move component correctness into an external condition the component cannot
+verify.
+
+## Open questions
+
+- **OQ1 — What exact visual treatment gives every determinate presentation a
+  sufficient standalone completed-versus-remaining distinction across supported
+  variants, themes, and color modes?** (`human-design`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, current audit
+results, implementation steps, exact visual values, or system theming rules. It
+links to their owners.

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -98,6 +98,62 @@ export const docs = {
   usage: {
     description:
       'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Selected'],
+        description:
+          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, and selected colors as they appear on screen.',
+      },
+      {
+        name: 'Essential icon',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only'],
+        description:
+          'When a segment has no visible label, its icon must have at least 3:1 contrast with the segment background. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Selected state indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if relied upon',
+        states: ['Selected'],
+        description:
+          'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label color and weight also show selection.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The control edge or segment borders need at least 3:1 contrast when users need them to see the choices.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around the segment. Check it on the track and selected background.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},

package/src/Selector/Selector.doc.mjs

@@ -194,6 +194,13 @@ export const docs = {
         '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.',
       default: "'end'",
     },
+    {
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
+      description:
+        'How the option list is presented. adaptive uses a bottom sheet on compact touch screens and an anchored popover otherwise.',
+      default: "'popover'",
+    },
     {
       name: 'width',
       type: 'SizeValue',
@@ -253,6 +260,11 @@ export const docs = {
         description:
           'Use variant="ghost" when a selector sits in a toolbar with ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.',
       },
+      {
+        guidance: true,
+        description:
+          'Use presentation="adaptive" when the selector should become a bottom sheet on compact touch screens.',
+      },
       {
         guidance: false,
         description:

package/src/Selector/Selector.test.tsx

@@ -10,6 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {readFileSync} from 'node:fs';
 import {
   act,
   render,
@@ -19,6 +20,7 @@ import {
   within,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
 import {useState} from 'react';
 import type {ReactNode} from 'react';
 import {Selector} from './Selector';
@@ -35,6 +37,7 @@ import {defineTheme} from '../theme/defineTheme';
 import {Theme} from '../theme/Theme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {spacingVars} from '../theme/tokens.stylex';
+import {selectorPresentationStyles} from './selectorPresentation.stylex';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -45,6 +48,28 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
 beforeEach(() => {
   // The live regions are a document-level singleton; start each test clean.
   __resetLiveRegionsForTest();
+  __resetInteractionModalityForTest();
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
   HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
     this.setAttribute('popover-open', '');
     const event = new Event('toggle', {bubbles: false});
@@ -228,6 +253,116 @@ function mockSelectorRects({
 }
 
 describe('Selector', () => {
+  it('uses a bottom sheet and closes after a selection when requested', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        onChange={onChange}
+        presentation="bottom-sheet"
+      />,
+    );
+
+    const trigger = screen.getByRole('combobox');
+    await user.click(trigger);
+
+    expect(
+      await screen.findByRole('dialog', {name: 'Fruit'}),
+    ).toBeInTheDocument();
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('option', {name: /Banana/}));
+    expect(onChange).toHaveBeenCalledWith('Banana');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('restores touch focus without painting a trigger focus ring', async () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={OPTIONS}
+        onChange={() => {}}
+        presentation="bottom-sheet"
+      />,
+    );
+
+    const trigger = screen.getByRole('combobox');
+    fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+    fireEvent.click(trigger, {detail: 1});
+    const option = await screen.findByRole('option', {name: /Banana/});
+    fireEvent.pointerDown(option, {pointerType: 'touch'});
+    fireEvent.click(option, {detail: 1});
+
+    trigger.focus();
+    expect(trigger).toHaveFocus();
+    expect(trigger.parentElement).toHaveClass(
+      stylex.props(selectorPresentationStyles.pointerRestoredFocus).className!,
+    );
+  });
+
+  it('uses content-hugging height without extra bottom content padding', () => {
+    const source = readFileSync(
+      'packages/core/src/Selector/SelectorBottomSheet.tsx',
+      'utf8',
+    );
+
+    expect(source).toContain('height="hug"');
+    expect(source).toContain('paddingBlockStart={4}');
+    expect(source).toContain('paddingBlockEnd={0}');
+  });
+
+  it('moves keyboard focus into a bottom-sheet listbox', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector label="Fruit" options={OPTIONS} presentation="bottom-sheet" />,
+    );
+
+    const trigger = screen.getByRole('combobox');
+    trigger.focus();
+    await user.keyboard('{Enter}');
+
+    await waitFor(() => expect(screen.getByRole('listbox')).toHaveFocus());
+  });
+
+  it('uses a bottom sheet for adaptive presentation on compact touch', async () => {
+    vi.stubGlobal(
+      'matchMedia',
+      vi.fn().mockImplementation((query: string) => ({
+        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    );
+    const user = userEvent.setup();
+    render(
+      <Selector label="Fruit" options={OPTIONS} presentation="adaptive" />,
+    );
+
+    await user.click(screen.getByRole('combobox'));
+    expect(
+      await screen.findByRole('dialog', {name: 'Fruit'}),
+    ).toBeInTheDocument();
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
+  it('keeps adaptive presentation anchored without compact touch', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector label="Fruit" options={OPTIONS} presentation="adaptive" />,
+    );
+
+    await user.click(screen.getByRole('combobox'));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledOnce();
+    expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();
+  });
+
   it('renders with placeholder when no value', () => {
     render(<Selector label="Fruit" options={OPTIONS} placeholder="Pick one" />);
     expect(screen.getByRole('combobox')).toHaveTextContent('Pick one');