@astryxdesign/core 0.7.6-canary.dfc83ee → 0.7.6-canary.e30ffbf

package/src/Stepper/Step.spec.md

@@ -1,200 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Step
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/Stepper/Stepper.test.tsx,
-    apps/storybook/stories/Stepper.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:interaction-modality, architecture:component-theming-surface]
-contributing: []
-system_specs: [spec:AST-085]
----
-
-# Step component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`.                                                                                                                            |
-| Behavior                | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick` and is not compact; a disabled step keeps its button, `aria-disabled`, and never activates. |
-| End-user impact         | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, a "Go to step N" name and the step's description on clickable steps; keyboard users Tab between clickable steps, disabled ones included.                         |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                    |
-| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact).                                                                                                                                                                                                                          |
-| Review checks           | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step.                                                                                                                     |
-| Governing rules         | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`.                                                                                                                                                                                                              |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Step is one stage of a Stepper flow. It owns its progress derivation, its
-indicator choice, its status cues and text alternatives, its clickable form, its optional cue, and where its content renders. Consumer usage lives in `Step.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: progress follows the Stepper's active step
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Other indicator modes show status by color alone, or not at all.** With
-  `indicator="number"`, a reached step shows status only through badge color
-  and a not-started step shows none. A custom node shows status only through
-  its wrapper's color, on every step. `indicator="none"` shows no indicator, and
-  under `auto` the current step's ring and label keep progress color whatever
-  its `status`, so in both cases status shows only in the visually hidden word. WCAG 1.4.1 requires information
-  not to be conveyed by color alone.
-- **A clickable step's name hides its other text.** The button's name is the
-  step number, label, and status word, and only the description describes it,
-  so the "Optional" cue and `endContent` never reach assistive technology on a
-  clickable step. WCAG 1.3.1 requires information shown to be
-  available programmatically.
-
-## Ownership boundary
-
-**Owns**
-
-- Progress derivation, indicator selection, status glyphs and text, the
-  clickable button, disabled and optional handling, and density fallback
-  (FR1–FR7).
-- Where `children` render and how they stay mounted (FR8), and the focus outline
-  (FR9).
-
-**Does not own / non-goals**
-
-- The `step`, `step-bar`, `step-connector`, `step-indicator`, `step-label`, and
-  `step-description` targets, connector geometry and gap, Label and Description
-  paint, and the compact horizontal presentation — owned by `component:Stepper`
-  FR1–FR16.
-- The active step, orientation, indicator position, and `onStepClick` — owned by
-  the Stepper and its caller.
-- Custom indicator artwork, `endContent`, and `children` — owned by the caller.
-
-## Public concepts
-
-| Concept   | Closed values or states                   | Meaning                                            | Availability by variant/orientation/state | Default                | Owner            | Stability | Invalid-value behavior                                                             |
-| --------- | ----------------------------------------- | -------------------------------------------------- | ----------------------------------------- | ---------------------- | ---------------- | --------- | ---------------------------------------------------------------------------------- |
-| Progress  | `completed`, `in-progress`, `not-started` | Derived from `step` and the Stepper's active step. | Every step.                               | —                      | `component:Step` | Stable    | Not caller-settable.                                                               |
-| Status    | `accent`, `success`, `warning`, `error`   | Semantic color and glyph for the indicator.        | Every step.                               | Unset (progress color) | `component:Step` | Stable    | TypeScript rejects other values.                                                   |
-| Indicator | `auto`, `number`, `none`, node            | What the indicator shows.                          | Every step.                               | `auto`                 | `component:Step` | Stable    | A non-string node renders as given; another string shows the ring, then the check. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Basis                           |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
-| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode keeps its button, focusable with `aria-disabled="true"` and the same name, keeps its tab stop and its focus when it becomes disabled while focused, and does not activate (`spec:AST-085` FR1, FR4). A clickable Step's description describes its button, so a disabled step's reason reaches assistive technology (`spec:AST-085` FR5). | Current source and tests        |
-| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
-| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests        |
-| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests        |
-| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
-| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source                  |
-| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source, docs, and tests |
-| FR9 | The step button paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source                  |
-
-### Allowed variation
-
-- **AV1 — Indicator artwork.** A custom node may replace the indicator.
-- **AV2 — Layout.** Orientation and indicator position come from the Stepper.
-
-### Representative states
-
-| State                  | Required invariant                                          | Allowed variation |
-| ---------------------- | ----------------------------------------------------------- | ----------------- |
-| Completed, clickable   | Check indicator; "completed" text; named button.            | Status color.     |
-| In progress            | `aria-current="step"`; ring indicator.                      | —                 |
-| Not started with error | Error glyph replaces the number; "error" text.              | —                 |
-| Disabled               | Dimmed; focusable and `aria-disabled`; no activation (FR2). | —                 |
-| Compact horizontal     | No button; content mounted but hidden.                      | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Status word.** `error`, then `warning`, then `completed` (completed
-  progress or `success`).
-- **ORD2 — Density.** Step `density`, then the Stepper's.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Current step.** FR1's `aria-current="step"`.
-- **AR2 — Non-color status.** With `indicator="auto"`, FR4's glyphs and FR5's
-  hidden text carry status beyond color; indicators stay hidden from assistive
-  technology. Implementation gap: in `number`, custom-node, and `none` modes,
-  and on the `auto` current step, status shows by color alone or only in the
-  hidden word (Current-state
-  impact).
-- **AR3 — Clickable name.** FR2's button name includes the step number, label,
-  and status word, and the step's description describes it. Implementation gap:
-  a clickable step's optional cue and `endContent` are not exposed
-  (Current-state impact).
-- **AR4 — Keyboard.** Clickable steps, disabled ones included, are reached with
-  Tab in document order; enabled ones activate with Enter or Space.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                 | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Indicator        | Number, check, status glyph, ring, or custom node. | Current source and public docs | Prominent      | FR3, FR4           |
-| Optional cue     | "Optional" after the label.                        | Current source                 | Supporting     | FR6                |
-
-`Step.doc.mjs` declares no anatomy of its own; Step anatomy and targets are in
-`component:Stepper`'s theming map.
-
-## Family and system relationships
-
-- `component:Stepper` owns the targets, connector, Label and Description paint,
-  and compact layout this component renders within.
-
-## Verification map
-
-| Contract     | Verification                                                        | Representative states                 | Mutation or failure expectation                                                                                                                                         | Audit section              |
-| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1          | `Stepper.test.tsx` list and aria-current tests                      | Each progress                         | Wrong current step fails.                                                                                                                                               | `audit:Step/accessibility` |
-| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails, and so does a disabled step that leaves the tab order, loses focus when it becomes disabled, lacks `aria-disabled`, or activates. | `audit:Step/behavior`      |
-| FR3, FR4     | `Stepper.test.tsx` step-number, indicator, and status glyph tests   | Each indicator mode and status        | Wrong glyph or recolored bar fails.                                                                                                                                     | `audit:Step/behavior`      |
-| FR8          | `Stepper.test.tsx` compact content-mount tests                      | Both indicator positions              | Step content that loses its state while hidden in a compact Stepper fails.                                                                                              | `audit:Step/behavior`      |
-| FR5, AR2     | `Stepper.test.tsx` hidden status text tests                         | Separated and on-track                | Missing status text fails.                                                                                                                                              | `audit:Step/accessibility` |
-
-Read from source, with no focused test yet:
-
-- FR3: the number on a not-started step and the check after completion under
-  `auto`, the empty indicator under `none`, and the string fallback.
-- FR6: the dimmed disabled paint, the optional cue, and `endContent`.
-- FR7.
-- FR8: the one-line label.
-- FR9.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, or Stepper layout
-rules. It links to their owners.

package/src/Stepper/Stepper.public.test.ts

@@ -1,91 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Stepper.public.test.ts
- * @input Imports the Stepper public barrel and internal context module
- * @output Locks the supported horizontal options and context surfaces
- * @position Compatibility test guarding @astryxdesign/core/Stepper
- *
- * The `expectTypeOf` assertions here are enforced by `pnpm -F
- * @astryxdesign/core typecheck`, not by the test run. A failed negative property
- * assertion surfaces as `TS2554: Expected 2 arguments, but got 1`.
- */
-
-import {describe, expectTypeOf, it} from 'vitest';
-
-import type {
-  StepperContextValue,
-  StepperProps,
-  StepperRegistrationOptions,
-  useStepperContext,
-} from './index';
-import type {StepperInternalContextValue} from './StepperContext';
-
-const privateContextFields = [
-  'stepCount',
-  'isCompact',
-  'summarySlot',
-  'minimumStepWidth',
-  'minStepWidthMeasureRef',
-] as const;
-
-describe('Stepper public surface', () => {
-  it('accepts only pixel numbers for the minimum step width', () => {
-    type HorizontalOptions = NonNullable<StepperProps['horizontalOptions']>;
-
-    expectTypeOf<
-      HorizontalOptions['minimumStepWidth']
-    >().toEqualTypeOf<number>();
-  });
-
-  it('keeps private coordination off the public context', () => {
-    for (const field of privateContextFields) {
-      expectTypeOf<StepperContextValue>().not.toHaveProperty(field);
-      expectTypeOf<ReturnType<typeof useStepperContext>>().not.toHaveProperty(
-        field,
-      );
-    }
-  });
-
-  it('preserves the supported public context reads', () => {
-    expectTypeOf<
-      ReturnType<typeof useStepperContext>
-    >().toEqualTypeOf<StepperContextValue>();
-    expectTypeOf<StepperContextValue>().toHaveProperty('activeStep');
-    expectTypeOf<StepperContextValue>().toHaveProperty('previousActiveStep');
-    expectTypeOf<StepperContextValue>().toHaveProperty('orientation');
-    expectTypeOf<StepperContextValue>().toHaveProperty('isNonLinear');
-    expectTypeOf<StepperContextValue>().toHaveProperty('onStepClick');
-    expectTypeOf<StepperContextValue>().toHaveProperty('density');
-    expectTypeOf<StepperContextValue>().toHaveProperty('indicatorPosition');
-    expectTypeOf<StepperContextValue>().toHaveProperty('registerStep');
-  });
-
-  it('keeps the registration options on the public context', () => {
-    type RegisterStep = StepperContextValue['registerStep'];
-
-    expectTypeOf<Parameters<RegisterStep>[1]>().toEqualTypeOf<
-      StepperRegistrationOptions | undefined
-    >();
-    expectTypeOf<StepperRegistrationOptions['getIsDisabled']>().toEqualTypeOf<
-      (() => boolean) | undefined
-    >();
-  });
-
-  it('keeps layout coordination on the internal context only', () => {
-    expectTypeOf<StepperInternalContextValue>().toMatchTypeOf<StepperContextValue>();
-    expectTypeOf<StepperInternalContextValue>().toHaveProperty(
-      'previousActiveStep',
-    );
-    expectTypeOf<StepperInternalContextValue>().toHaveProperty('registerStep');
-    expectTypeOf<StepperInternalContextValue>().toHaveProperty('stepCount');
-    expectTypeOf<StepperInternalContextValue>().toHaveProperty('isCompact');
-    expectTypeOf<StepperInternalContextValue>().toHaveProperty('summarySlot');
-    expectTypeOf<StepperInternalContextValue>().not.toHaveProperty(
-      'minimumStepWidth',
-    );
-    expectTypeOf<StepperInternalContextValue>().not.toHaveProperty(
-      'minStepWidthMeasureRef',
-    );
-  });
-});