An open source design system that's fully customizable and agent ready
TypeScript
feat(Stepper): --step-connector-gap, so a theme can stop the on-track connector short of the indicator (#5495)
freddymeta680338c1b95d
diff --git a/.changeset/step-connector-gap.md b/.changeset/step-connector-gap.mdnew file mode 100644index 0000000000..3ed4989d10--- /dev/null+++ b/.changeset/step-connector-gap.md@@ -0,0 +1,42 @@+---+'@astryxdesign/core': patch+---++[feat] Stepper: `--step-connector-gap`, so a theme can stop the on-track connector short of the indicator++The on-track layouts draw the connector as one segment either side of the node. A theme that wants the track to leave a hole around the indicator had to reach the two segments separately, and they are only distinguishable by sibling position — which changes with `indicator="none"`.++One public var does it instead, declared on the Stepper root because component vars are root-owned: a theme writes `stepper: {base: {'--step-connector-gap': '4px'}}` and every connector inherits it. Astryx spends it on whichever side each segment faces the node from, so the pair leaves a symmetric hole and the caller never names the pieces. `0px` by default: the shipped track still reads as one unbroken line.++Measured in Chromium against a built theme override, reading painted pixels down a 12px segment:++| value | clipped away | stepper height |+| ------- | ------------- | -------------- |+| `6px` | 6px | unchanged |+| `-4px` | 0 | unchanged |+| `1rem` | capped to 8px | unchanged |+| `999px` | capped to 8px | unchanged |+| `10%` | 1px (of 12px) | unchanged |+| `50%` | capped to 6px | unchanged |++Four things that had to be true and are:++**A theme override reaches it.** The default is declared once on the root, not on each connector. Declared per-connector, every connector re-declared `0px` on itself, and a value declared on an element beats an inherited one — so a generated `stepper` override compiled cleanly and changed nothing.++**The value is bounded**, and both halves earn it — neither for padding's reasons. `max(0px, …)` because `inset()` _accepts_ a negative length: Chromium computes `inset(0 0 -4px 0)` as written rather than clamping it the way it clamps negative padding, so the floor has to be declared. `min(…, --spacing-2)` — the flexible segment's own `min-height` — so an oversized gap leaves a short track rather than an unbounded one. Neither can grow the Stepper; a clip cannot change layout. (An earlier padding-based revision grew a three-step Stepper 108px → 144px at `1rem`.)++**The horizontal clip mirrors under `dir="rtl"`.** `clip-path: inset()` is physical — top/right/bottom/left, no logical form — while the row itself reverses. Left unflipped, the leading segment sits to the _right_ of the node in RTL and still clipped its right edge, so the hole opened at the join between steps instead of at the indicator. Measured before the fix: `con0 x=622, indicator x=606, clips RIGHT edge`. After: `clips LEFT edge`, with LTR unchanged. The block axis needs no handling — `dir` does not reverse it.++**One declaration covers both layers.** The gap has to reach the track (the segment's own background) and the accent fill (an absolutely placed `::before`). Spending it on each separately meant two declarations on two boxes, so a percentage resolved against a different containing block for each and stopped them ~1.2px apart. A single `clip-path: inset(…)` on the segment clips the element and its pseudo-element together against one reference box, so every accepted value behaves identically on both — which is what [#5824](https://github.com/facebook/astryx/pull/5824) requires of a public input across its full value domain. Clipping also cannot change layout, so the node the segment positions cannot move.++**No indicator, no gap.** `indicator="none"` renders no node, so a gap there is a hole in a track that is meant to be continuous.++Any CSS length or percentage is accepted and behaves the same way on both layers. A percentage resolves against each segment's own box, so a fixed and a flexible segment clip by slightly different amounts from one declared value — cosmetic, bounded by the cap, and recorded as accepted rather than fixed.++**Why a custom property and not a guaranteed CSS property.** A theme target reaches the element, never its `::before`. Measured against a built theme override on `step-connector`: `paddingBlock: 6px` produces no hole at all — the background paints to its border box and the fill is out of reach — its only effect being the Stepper growing 108px → 120px; `paddingBlockEnd: 6px` produces no hole either, and addresses only one of the two edges. Only the component can clip both layers together, mirror per axis and direction, and clamp first.++Adds `Stepper.spec.md`, the canonical owning record for this public property, carrying that admission argument, the value contract, and the anatomy-to-target map. `Stepper.doc.mjs` gains the anatomy entries its existing `stepper`, `step`, and `step-connector` targets never had, so every current target is anchored to a described part.++Supersedes the `segment` variant this PR previously proposed. That exposed `lead` / `rail` / `content` as public theming vocabulary, which does not hold up: the words never appeared in the generated docs, they emit bare `lead` / `content` classes where a consumer's own stylesheet can collide with them, and `lead` means different geometry per orientation. The pieces are how this layout happens to be drawn today, not a contract.++@freddymetadiff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex 522ad60cfb..add1bd5e06 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -114,6 +114,17 @@"next": "button[aria-label=\"Next\"]"}},+ {+ "component": "Stepper",+ "storyId": "core-stepper--default-horizontal",+ "dims": [+ "D2"+ ],+ "selectors": {+ "prev": ".astryx-stepper > li:first-child",+ "next": ".astryx-stepper > li:last-child"+ }+ },{"component": "TabList","storyId": "core-tablist--overflow",diff --git a/packages/core/src/Stepper/Step.doc.mjs b/packages/core/src/Stepper/Step.doc.mjsindex b12cae8b61..d151c958cb 100644--- a/packages/core/src/Stepper/Step.doc.mjs+++ b/packages/core/src/Stepper/Step.doc.mjs@@ -10,7 +10,7 @@ export const docs = {category: 'Navigation',isHiddenFromOverview: true,description:- 'Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper\'s activeStep and this step\'s step index.',+ "Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper's activeStep and this step's step index.",props: [{name: 'step',diff --git a/packages/core/src/Stepper/Step.tsx b/packages/core/src/Stepper/Step.tsxindex 3d006f77e3..049b787aec 100644--- a/packages/core/src/Stepper/Step.tsx+++ b/packages/core/src/Stepper/Step.tsx@@ -197,6 +197,37 @@ function CurrentIcon() {// --- Styles ---const BAR_WIDTH = spacingVars['--spacing-1'];++/**+ * How much of itself a connector gives up where it meets the indicator, read+ * from the public `--step-connector-gap` declared on the Stepper root.+ *+ * Clipped, not padded. The gap has to apply to two layers — the track, which is+ * the segment's own background, and the accent fill, which is an absolutely+ * placed `::before`. Spending it on each separately meant two declarations on+ * two boxes: a percentage then resolved against a different containing block+ * for each and stopped them ~1.2px apart. `clip-path` is ONE declaration on the+ * segment that clips the element and its pseudo-element together, against one+ * reference box — so every accepted value behaves the same way on both layers,+ * which is what a public input owes its full value domain.+ *+ * Clipping also cannot change layout: the segment keeps its box, so the node it+ * positions cannot move and the Stepper cannot grow. A raw `1rem` padding grew+ * a 180px stepper to 240px.+ *+ * Still clamped, because the value arrives with nothing in between to reject+ * it. Both halves earn their place, and not for the reasons padding needed:+ *+ * - `max(0px, …)` — `inset()` ACCEPTS a negative length. Chromium computes+ * `inset(0 0 -4px 0)` as-is rather than dropping it, which is the opposite+ * of padding (there CSS clamps a negative to `0` for you). This normalises+ * it to `0` so a negative gap means "no gap" rather than a clip rect+ * stretched outside the segment's own box.+ * - `min(…, --spacing-2)` — the flexible segment's own `min-height`, so an+ * oversized gap leaves a short track rather than an unbounded one.+ */+const CONNECTOR_GAP = `max(0px, min(var(--step-connector-gap, 0px), ${spacingVars['--spacing-2']}))`;+// Every indicator — check, ring, custom icon, number badge — occupies the same// box, so the `auto` mode swapping a number for a check as a step completes// never nudges the label or the track.@@ -730,6 +761,43 @@ const styles = stylex.create({flexShrink: 0,borderRadius: 0,},+ // The gap a connector leaves where it meets the indicator, spent on the side+ // that faces the node so the pair leaves a symmetric hole around it.+ //+ // Clip the segment rather than changing its box: one `clip-path` clips the+ // segment's own track and its absolutely positioned `::before` fill against+ // the same reference box. The indicator stays put, the Stepper cannot grow,+ // and percentage values cannot resolve differently between the two layers.+ // The inherited value is clamped in CONNECTOR_GAP; its default is declared+ // once on the Stepper root, where a generated theme override can replace it.+ //+ // A public var rather than a per-segment theme vocabulary: "do not touch the+ // indicator" is one intent, and naming the segments would publish which+ // pieces this layout happens to be drawn from today.+ otSegGapLeadV: {+ clipPath: `inset(0 0 ${CONNECTOR_GAP} 0)`,+ },+ otSegGapRailV: {+ clipPath: `inset(${CONNECTOR_GAP} 0 0 0)`,+ },+ // The horizontal pair is PHYSICAL: `clip-path: inset()` takes top/right/+ // bottom/left and has no logical form, while the row itself reverses under+ // `dir="rtl"`. Left unflipped, the leading segment sits to the RIGHT of the+ // node in RTL and still clips its right edge — opening the hole at the join+ // between steps instead of at the indicator. The block axis needs no such+ // handling: `dir` does not reverse it.+ otSegGapLeadH: {+ clipPath: {+ default: `inset(0 ${CONNECTOR_GAP} 0 0)`,+ ':is([dir="rtl"] *)': `inset(0 0 0 ${CONNECTOR_GAP})`,+ },+ },+ otSegGapRailH: {+ clipPath: {+ default: `inset(0 0 0 ${CONNECTOR_GAP})`,+ ':is([dir="rtl"] *)': `inset(0 ${CONNECTOR_GAP} 0 0)`,+ },+ },// Flexible segment (below the node) — grows to fill the step height and// meets the next node's leading segment.otSegFlexV: {@@ -1352,6 +1420,7 @@ export function Step({styles.otSegBaseV,styles.otSegLeadV(densitySpace),styles.connectorTrack,+ hasIndicator && styles.otSegGapLeadV,beforeSegStyle,beforeTiming,styles.otSegHiddenIfFirst,@@ -1367,6 +1436,7 @@ export function Step({styles.otSegBaseV,styles.otSegFlexV,styles.connectorTrack,+ hasIndicator && styles.otSegGapRailV,afterSegStyle,railTiming,styles.otSegHiddenIfLast,@@ -1432,6 +1502,7 @@ export function Step({stylex.props(styles.otSegH,styles.connectorTrack,+ hasIndicator && styles.otSegGapLeadH,beforeSegStyle,beforeTiming,styles.otSegHiddenIfFirst,@@ -1446,6 +1517,7 @@ export function Step({stylex.props(styles.otSegH,styles.connectorTrack,+ hasIndicator && styles.otSegGapRailH,afterSegStyle,railTiming,styles.otSegHiddenIfLast,diff --git a/packages/core/src/Stepper/Stepper.doc.mjs b/packages/core/src/Stepper/Stepper.doc.mjsindex f1de040caf..c6d15a7a32 100644--- a/packages/core/src/Stepper/Stepper.doc.mjs+++ b/packages/core/src/Stepper/Stepper.doc.mjs@@ -53,12 +53,30 @@ export const docs = {},],anatomy: [+ {+ name: 'Stepper',+ required: true,+ description:+ 'The ordered list holding the steps. Owns the orientation and the indicator placement the whole flow is laid out on.',+ },+ {+ name: 'Step',+ required: true,+ description:+ 'One step in the flow, and the element carrying its status. Wraps the indicator, label, description, and the track segments belonging to it.',+ },{name: 'Progress bar',required: true,description:'A 4px segmented bar per step. Filled for completed and active steps. Advancing one step grows the fill along the track it just covered, so the movement reads as progress rather than a bar changing color. Every other change applies at once: going back, jumping forward by more than one step, mounting mid-flow, and any change at all under prefers-reduced-motion. Where a span is drawn by more than one segment (the on-track layouts split it between two steps, three when a content slot sits between them), the segments run in track order at one constant speed, so the fill reads as a single line growing rather than pieces lighting in turn.',},+ {+ name: 'Connector',+ required: false,+ description:+ 'The track drawn between indicators in the on-track layouts. Each connector paints an unfilled line and, over it, the accent fill covering the progress made. How many pieces a connector is drawn from is an implementation detail of the layout, not a themeable part; use --step-connector-gap to hold the track off the indicator.',+ },{name: 'Indicator',required: false,@@ -88,6 +106,14 @@ export const docs = {{className: 'astryx-step-bar'},{className: 'astryx-step-connector'},],+ vars: [+ {+ name: '--step-connector-gap',+ description:+ 'Gap a connector leaves where it meets the indicator, spent on the side facing it. Applies to the on-track layouts, whose connector is drawn as one segment either side of the node; 0 leaves the track running unbroken through it.',+ default: '0px',+ },+ ],},components: [{@@ -260,6 +286,14 @@ export const docsZh = {{className: 'astryx-step-bar'},{className: 'astryx-step-connector'},],+ vars: [+ {+ name: '--step-connector-gap',+ description:+ '连接线与指示器相接处留出的间隙,落在朝向指示器的一侧。适用于 on-track 布局——其连接线由节点两侧各一段绘制;取 0 时轨道将不间断地穿过节点。',+ default: '0px',+ },+ ],},components: [{diff --git a/packages/core/src/Stepper/Stepper.spec.md b/packages/core/src/Stepper/Stepper.spec.mdnew file mode 100644index 0000000000..e0b030ec87--- /dev/null+++ b/packages/core/src/Stepper/Stepper.spec.md@@ -0,0 +1,218 @@+---+schema_version: 3+template_version: 3+kind: component+id: component:Stepper+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-09-02+owners: [cixzhang]+review_triggers: [public-api, theming, layout]+verified_by:+ [packages/core/src/Stepper/Stepper.test.tsx, scripts/check-knowledge.mjs]+modules: []+families: []+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]+contributing: []+system_specs: [spec:AST-002/DEC-1]+---++# Stepper component contract++## Intent++Stepper presents an ordered flow of steps and the progress made through it. This+contract records the anatomy-to-target map for the existing targets and owns the+one public semantic custom property the component exposes,+`--step-connector-gap`.++## Compatibility and migration++- Released default preserved: `yes` — `--step-connector-gap` defaults to `0px`,+ which renders the shipped track unchanged+- Compatibility class: additive; one new public custom property, no change to+ existing targets, DOM, props, or default pixels+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The `stepper`, `step`, `step-bar`, `step-connector`, and `step-indicator`+ targets.+- The two paint layers of a connector — the unfilled track (the element's own+ background) and the accent fill (an absolutely placed `::before`) — and the+ single clip that holds both off the indicator.+- Which pieces an on-track connector is drawn from, and how many.++**Does not own / non-goals**++- Indicator artwork supplied through `indicator` — owned by the caller.+- The step content slot and any `endContent` — owned by the caller.+- Whether a step is complete: derived from `activeStep`, not from a caller-owned+ per-step lifecycle.++## Public concepts++| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ---------------------- | ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------------------- | --------- | --------------------------------------------------------------------------------------------------------- |+| `--step-connector-gap` | Any CSS `<length-percentage>` | How far the track stops short of the indicator, on the side facing it | `indicatorPosition="on-track"`, both orientations and both directions, only on steps that render an indicator | `0px` | `component:Stepper` | stable | Clamped, never rejected: values below `0` resolve to `0`, values above `--spacing-2` cap at `--spacing-2` |++Consumer syntax and description remain in `Stepper.doc.mjs` `theming.vars`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------ |+| FR1 | The default for `--step-connector-gap` is declared once, on the `stepper` root, so a theme's `stepper` override is inherited by every connector. | Reviewed defect (PR #5495) | Settled |+| FR2 | The gap is applied to the ONE edge each segment faces the indicator from, mirrored per axis, so the pair leaves a hole centred on the node. | Current source and browser probe | Settled |+| FR3 | One declaration covers both connector paint layers. A clip on the segment clips its `::before` with it, against one reference box, so the two cannot disagree. | Current source and browser probe | Settled |+| FR4 | The resolved value is clamped to `max(0px, min(value, --spacing-2))` before use. | Reviewed defect (PR #5495) | Settled |+| FR5 | A step rendering no indicator (`indicator="none"`) applies no clip, leaving its track continuous. | Current source and browser probe | Settled |+| FR6 | No accepted value changes the Stepper's outer size, in either orientation. A clip cannot affect layout. | Current source and browser probe | Settled |+| FR7 | The horizontal clip mirrors under `dir="rtl"`, so the hole stays at the indicator rather than moving to the join between steps. | Reviewed defect (PR #5495) | Settled |+| FR8 | The pieces an on-track connector is drawn from are not public: no `data-segment`, and no bare `lead`/`rail`/`content` class is emitted. | `component:Stepper/DEC-1` | Settled |++### Allowed variation++- **AV1 — Segment count.** How many elements draw one connector span may change+ with orientation and with the presence of a content slot, without becoming a+ regression. It is not public.+- **AV2 — Percentage resolution.** A percentage resolves against each segment's+ own box, so the hole may differ slightly between a fixed and a flexible+ segment. Both layers of any one segment still agree exactly (FR3).++### Representative states++| State | Required invariant | Allowed variation |+| -------------------------------- | ------------------ | ----------------- |+| vertical, on-track, indicator | FR2, FR3, FR6 | AV1, AV2 |+| horizontal, on-track, indicator | FR2, FR3, FR6, FR7 | AV1, AV2 |+| `dir="rtl"`, horizontal | FR7 | AV1 |+| `indicator="none"` | FR5 | — |+| value below `0` or above the cap | FR4, FR6 | — |++### Transformation and precedence order++- **ORD1 — Gap resolution.** Read the inherited custom property → clamp to+ `max(0px, min(value, --spacing-2))` → apply as one `clip-path: inset()` on the+ segment. Both halves of the clamp are load-bearing, and neither for padding's+ reasons: `inset()` **accepts** a negative length rather than clamping it the+ way padding does, so the floor has to be written; the cap bounds an oversized+ gap to a short track.++### Performance and resources++- No new performance or resource rule is introduced. The gap is a static CSS+ declaration; it adds no measurement, listener, or observer.++## Accessibility contract++This contract does not change Stepper's existing roles, `aria-current` handling,+or reduced-motion behavior. The connector is `aria-hidden`, so the gap is a+purely visual change.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ---------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |+| Stepper | Lays the flow out on one orientation and indicator placement. | Current source and public docs | Supporting | FR1 |+| Step | Carries one step's status. | Current source and public docs | Supporting | — |+| Progress bar | Presents progress as a segmented bar per step. | Current source and public docs | Prominent | — |+| Connector | Presents the track between indicators, and the progress made along it. | Current source and public docs | Prominent | FR2–FR7 |+| Indicator | Presents the step's position or completion. | Current source and public docs | Prominent | FR5 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Stepper": {"target": "stepper"},+ "Step": {"target": "step"},+ "Progress bar": {"target": "step-bar"},+ "Connector": {"target": "step-connector"},+ "Indicator": {"target": "step-indicator"},+ "Label": {"inherits": "step"},+ "Description": {"inherits": "step"}+}+```++Connector is one anatomy part with one target, even though the on-track layouts+draw it from up to three elements. Those pieces are layout implementation, not+semantic parts, so they get no targets of their own — see `DEC-1`, which is also+why the caller-owned gap is a custom property rather than a per-piece vocabulary.++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, the+ guaranteed-property catalog, and the admission rule for public semantic+ variables.+- `architecture:public-component-api` owns the API admission bar those variables+ must also pass.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------- |+| FR1 | `Stepper.test.tsx` root-ownership assertion | vertical on-track | Moving the declaration back onto the connector makes a `stepper` theme override a no-op. | `audit:Stepper/theming` |+| FR2, FR3 | `Stepper.test.tsx` clip assertions | vertical and horizontal on-track | Clipping the wrong edge, or per-layer copies of the value, fails the suite. | `audit:Stepper/theming` |+| FR4, FR6 | `Stepper.test.tsx` clamp assertion | values below `0` and above the cap | Removing the floor lets a negative inset through; removing the cap unbounds the hole. | `audit:Stepper/theming` |+| FR5 | `Stepper.test.tsx` no-indicator assertion | `indicator="none"` | Applying the clip unconditionally puts holes in a track with no node in them. | `audit:Stepper/theming` |+| FR7 | `Stepper.test.tsx` RTL assertion | `dir="rtl"`, horizontal | Dropping the mirror moves the hole to the join between steps; caught by the assertion. | `audit:Stepper/theming` |+| FR8 | `Stepper.test.tsx` vocabulary guard | vertical on-track | Re-adding `data-segment` or a bare role class fails the guard. | `audit:Stepper/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and the five current targets | A target with no anatomy owner, or a stale/extra part, fails repository validation. | `audit:Stepper/theming` |++## Decision log++### DEC-1 — The connector gap is a public custom property, not a theme target per piece++**Reference:** `component:Stepper/DEC-1`+**Decider:** `cixzhang`, `2026-09-02`++The optional Connector anatomy represents the connected, on-track presentation;+its inner gap from the component-owned Indicator is a stable component+responsibility. A theme may want that track to stop short of the indicator rather+than run through it. Two otherwise identical Steppers need different resolved outcomes+and only the theme knows which, so the need is caller-owned+(`spec:AST-002/DEC-1` FR1). Astryx cannot derive it: nothing in the component's+state, content, or layout says whether this design wants a broken or a+continuous track.++No guaranteed CSS property on the owning target can express it. A connector+paints in two layers — the element's own background (the unfilled track) and a+`::before` at `inset: 0` (the accent fill) — and a theme target reaches the+element only. Measured in Chromium against a built theme override on+`step-connector`, three steps, vertical:++- `paddingBlock: 6px` produces **no hole at all**. The element's background+ paints to its border box, and the fill is a pseudo-element the theme cannot+ reach, so the only observable effect is the Stepper growing 108px → 120px.+- `paddingBlockEnd: 6px` produces no hole either, and would in any case address+ only one of the two edges: the leading segment faces the node with its far+ edge, the trailing segment with its near one.++Only the component can put one clip on the segment that takes its pseudo-element+with it, mirror it per axis and per direction, and clamp the value first.++Rejected: exposing `lead` / `rail` / `content` as a public segment vocabulary+(the earlier form of this change). The words never reached generated docs, they+emitted bare `lead` / `content` classes a consumer stylesheet can collide with,+and `lead` denotes different geometry per orientation, so a theme selecting it+could not know what it would get.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, implementation+steps, or system rules. It links to their owners.diff --git a/packages/core/src/Stepper/Stepper.test.tsx b/packages/core/src/Stepper/Stepper.test.tsxindex 1782cd9b6e..bcc0d101f8 100644--- a/packages/core/src/Stepper/Stepper.test.tsx+++ b/packages/core/src/Stepper/Stepper.test.tsx@@ -6,6 +6,8 @@ import {render, screen, within} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Stepper} from './Stepper';import {Step} from './Step';+import {defineTheme} from '../theme/defineTheme';+import {generateThemeCSS} from '../theme/generateThemeRules';describe('Stepper', () => {it('renders an ordered list of steps (not a nav landmark)', () => {@@ -1021,4 +1023,204 @@ describe('Stepper', () => {expect(isInstant(getByTestId('b'))).toBe(true);});});++ describe('--step-connector-gap', () => {+ // The on-track layouts draw the connector as one segment either side of+ // the indicator. A theme that wants the track to stop short of the node+ // sets one var; Astryx spends it on whichever side each segment faces the+ // node from, so the pair leaves a symmetric hole and the caller never+ // names the pieces.+ const onTrack = (orientation: 'vertical' | 'horizontal') => (+ <Stepper+ activeStep={1}+ orientation={orientation}+ indicatorPosition="on-track">+ <Step step={0} label="One" />+ <Step step={1} label="Two" />+ </Stepper>+ );++ /**+ * Every declaration the injected stylesheet carries for an element's own+ * atomic classes, `::before` rules included — the same route `fillEasings`+ * above takes, because StyleX puts static styles in the sheet rather than+ * inline and jsdom resolves no cascade of its own.+ *+ * Atomic class names are unique hashes, so the owning class is matched+ * anywhere in the selector rather than only at its head: a StyleX variant+ * such as the `dir="rtl"` mirror emits a compound selector the class does+ * not lead. Those rules are tagged `rtl:` so a test can tell the two+ * directions apart.+ */+ const declarationsFor = (el: Element) => {+ const classes = new Set(el.className.split(/\s+/));+ const out: string[] = [];+ for (const sheet of Array.from(document.styleSheets)) {+ for (const rule of Array.from(sheet.cssRules)) {+ if (!('selectorText' in rule)) {+ continue;+ }+ const {selectorText, style} = rule as CSSStyleRule;+ const owner = [...selectorText.matchAll(/\.([\w-]+)/g)].find(match =>+ classes.has(match[1]),+ );+ if (owner == null) {+ continue;+ }+ const prefix =+ (selectorText.includes('[dir="rtl"]') ? 'rtl:' : '') ++ (selectorText.endsWith('::before') ? 'before:' : '');+ for (const prop of Array.from(style)) {+ out.push(`${prefix}${prop}:${style.getPropertyValue(prop)}`);+ }+ }+ }+ return out.join(';');+ };++ it('clips the side each segment faces the node from', () => {+ const {container} = render(onTrack('vertical'));+ const [lead, rail] = [+ ...container.querySelectorAll('.astryx-step-connector'),+ ];+ // Above the node clips its bottom edge, below it clips its top —+ // mirrored, so the hole is centred on the indicator.+ expect(declarationsFor(lead)).toMatch(/clip-path:inset\(0 0 [^;]*\)/);+ expect(declarationsFor(rail)).toMatch(/clip-path:inset\([^0][^;]*0 0\)/);+ });++ it('uses the inline axis when the stepper is horizontal', () => {+ const {container} = render(onTrack('horizontal'));+ const [lead, rail] = [+ ...container.querySelectorAll('.astryx-step-connector'),+ ];+ expect(declarationsFor(lead)).toMatch(+ /clip-path:inset\(0 [^0][^;]*0 0\)/,+ );+ expect(declarationsFor(rail)).toMatch(+ /clip-path:inset\(0 0 0 [^0][^;]*\)/,+ );+ });++ it('clips the track and the fill with one declaration', () => {+ // The gap has to reach two layers: the track is the segment's own+ // background, the accent fill an absolutely placed ::before. Spending it+ // on each separately meant two declarations on two boxes, so a+ // percentage resolved against a different containing block for each and+ // stopped them ~1.2px apart. One clip on the segment covers both.+ const {container} = render(onTrack('vertical'));+ const lead = container.querySelector(+ '.astryx-step-connector',+ ) as HTMLElement;+ const declarations = declarationsFor(lead);+ expect(declarations).toContain('clip-path');+ // No per-layer copy of the gap to disagree with.+ expect(declarations).not.toMatch(+ /before:[a-z-]*padding[^;]*connector-gap/,+ );+ expect(declarations).not.toMatch(/before:inset[^;]*connector-gap/);+ });++ it('clamps a negative gap away and caps an oversized one', () => {+ // A theme value arrives with nothing in between to reject it, and+ // `inset()` is not padding: Chromium ACCEPTS `inset(0 0 -4px 0)` rather+ // than clamping it, so the floor has to be written. The cap is the+ // flexible segment's own `min-height`, bounding an oversized gap to a+ // short track. Neither can grow the Stepper — a clip cannot change+ // layout.+ const {container} = render(onTrack('vertical'));+ const lead = container.querySelector(+ '.astryx-step-connector',+ ) as HTMLElement;+ const declarations = declarationsFor(lead);+ expect(declarations).toContain('max(0px');+ expect(declarations).toContain('min(var(--step-connector-gap');+ });++ it('flips the horizontal clip under dir="rtl"', () => {+ // `clip-path: inset()` is physical (top/right/bottom/left) and has no+ // logical form, but the row reverses under `dir="rtl"`. Unflipped, the+ // leading segment sits to the RIGHT of the node in RTL and still clips+ // its right edge, opening the hole at the join between steps instead of+ // at the indicator.+ const {container} = render(onTrack('horizontal'));+ const [lead, rail] = [+ ...container.querySelectorAll('.astryx-step-connector'),+ ];+ // Each segment carries BOTH the LTR clip and its mirrored RTL variant.+ const leadRules = declarationsFor(lead);+ const railRules = declarationsFor(rail);+ expect(leadRules).toMatch(/rtl:clip-path:inset\(0 0 0 [^0]/);+ expect(railRules).toMatch(/rtl:clip-path:inset\(0 [^0][^;]*0 0\)/);+ });++ it('leaves the track unbroken when there is no indicator to avoid', () => {+ // `indicator="none"` renders no node, so a gap is a hole in a track that+ // is meant to be continuous.+ const {container} = render(+ <Stepper activeStep={0} indicatorPosition="on-track">+ <Step step={0} label="One" indicator="none" />+ <Step step={1} label="Two" indicator="none" />+ </Stepper>,+ );+ const connectors = [+ ...container.querySelectorAll('.astryx-step-connector'),+ ];+ expect(connectors.length).toBeGreaterThan(0);+ for (const node of connectors) {+ expect(declarationsFor(node)).not.toContain('--step-connector-gap');+ }+ });++ it('declares the default on the Stepper root, where a theme reaches it', () => {+ // Component vars are root-owned. Declared on each connector instead —+ // where this started — every connector re-declared 0px on itself, and a+ // declared value beats an inherited one, so a generated `stepper`+ // override compiled cleanly and changed nothing.+ const {container} = render(onTrack('vertical'));+ const root = container.querySelector('.astryx-stepper') as HTMLElement;+ expect(declarationsFor(root)).toContain('--step-connector-gap:0px');++ const lead = container.querySelector(+ '.astryx-step-connector',+ ) as HTMLElement;+ expect(declarationsFor(lead)).not.toContain('--step-connector-gap:0px');+ });++ it('emits a root-owned override through the theme build path', () => {+ const theme = defineTheme({+ name: 'stepper-connector-gap-test',+ components: {+ stepper: {+ base: {'--step-connector-gap': '6px'},+ },+ },+ });+ const {component} = generateThemeCSS(theme);++ expect(component).toMatch(+ /\.astryx-stepper\s*\{[^}]*--step-connector-gap:\s*6px;/,+ );+ expect(component).not.toMatch(+ /\.astryx-step-connector\s*\{[^}]*--step-connector-gap:/,+ );+ });++ it('leaves the connector target itself free of a segment vocabulary', () => {+ // The pieces are an implementation of the on-track layout, not API: no+ // `data-segment`, and no bare `lead`/`rail`/`content` class that could+ // collide with a consumer's own stylesheet.+ const {container} = render(onTrack('vertical'));+ const connectors = [+ ...container.querySelectorAll('.astryx-step-connector'),+ ];+ expect(connectors.length).toBeGreaterThan(0);+ for (const node of connectors) {+ expect(node.getAttribute('data-segment')).toBeNull();+ for (const cls of ['lead', 'rail', 'content']) {+ expect(node.classList.contains(cls)).toBe(false);+ }+ }+ });+ });});diff --git a/packages/core/src/Stepper/Stepper.tsx b/packages/core/src/Stepper/Stepper.tsxindex e8a3d432b8..19709ab626 100644--- a/packages/core/src/Stepper/Stepper.tsx+++ b/packages/core/src/Stepper/Stepper.tsx@@ -85,6 +85,14 @@ const styles = stylex.create({listStyleType: 'none',margin: 0,padding: 0,+ // Public, and declared HERE because component vars are root-owned: a theme+ // writes `stepper: {base: {'--step-connector-gap': '4px'}}`, which lands on+ // this element in `@layer astryx-theme` and beats this declaration. The+ // connectors inherit it. Declaring it on each connector instead — where it+ // started — made every one of them re-declare 0px on itself, and a value+ // declared on an element always beats an inherited one, so the generated+ // override compiled and changed nothing.+ '--step-connector-gap': '0px',},horizontal: {flexDirection: 'row',diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 2ee0527746..d9f6feb115 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -295,6 +295,11 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set(['--tree-list-indent','--_tree-indent','--tree-list-row-gap',+ // Clipped on the ONE side each on-track connector segment faces the+ // indicator from — trailing above the node, leading below it, mirrored+ // again per axis. No standard property maps onto this purpose-based seam:+ // one clip must cover the segment and its pseudo-element fill together.+ '--step-connector-gap',// Composed into a single box-shadow list on the card, so neither maps 1:1// onto boxShadow — setting one through a derived entry would clobber the// other.