feat(core): let a flow drop the Stepper's collapsed controls and label

[ernestt]

Note

Stacked on #5659. Base is core-stepper-narrow-collapse, so this diff is just the two new props. Review #5659 first; this can retarget to main once that lands.

Why

Feedback on #5659: the collapsed summary row often repeats the page around it on a phone. A wizard that brings its own Back/Continue gets two pairs of controls, and one that heads its own step gets the step named twice. The collapse is right to exist — it just had no way to yield the half a given flow already covers.

What

Two independent booleans on Stepper, both @default true:

prop	off means
hasCollapsedControls	no Previous/Next beneath a collapsed track
hasCollapsedLabel	a collapsed track does not name the current step

Defaults preserve today's behavior exactly. Dropping one leaves the other in the row; dropping both removes the row entirely rather than leaving an empty one to spend the frame's gap.

Step needed no change — it already gates its summary portal on the slot existing, so withholding the slot is the entire implementation of hasCollapsedLabel.

Accessibility

Both props are purely visual. The summary row is aria-hidden and the <ol> keeps every step's name at any width, so neither prop can shorten what a screen reader hears. Asserted directly by a test that reads back the full sequence with both halves off.

The one sharp edge

Turning the controls off in the separated layout leaves a collapsed stepper with nothing to press — that layout gives up its step click targets along with its labels. That is the intent when the flow has its own controls, but it does mean the stepper is purely a progress indicator until it is wide again. on-track keeps its indicators pressable as nodes on the rail, so there it costs nothing. Named in the hasCollapsedControls JSDoc and the prop table rather than left to be discovered.

How the names were chosen

Arbitrated with a vibe test rather than picked; harness and full findings in internal/vibe-tests/stepper-collapse-naming-test. Four naming arms × four prompts with isolated agents, arm docs machine-generated from one template so no arm got a lexical head start, plus a five-sample recall probe that described the behavior with the props deliberately unnamed.

• The generation battery tied 16/16 correct. Naming does not change whether an agent can use the API, so everything below is tie-break.
• Shape: 5/5 recall samples produced two independent booleans and nobody produced an enum. The four states are genuinely independent, and an enum forces you to restate the half you did not want to change.
• hasLabel is out: it collides with the existing label prop, which names the whole sequence. A real collision in the shipping API, not an artifact of the test.
• Summary is out: it only ever won by leaking an internal name off a data attribute, and both Summary choosers started at Collapsed and switched for that reason. The judge also found that B and C results stopped to verify the prop would not kill the desktop labels 4/4, while A and D never did 0/4 — the Collapsed qualifier removes real scope doubt.
• has over show: the probe preferred show* 5/5, but packages/core/src has ~30 has* booleans and zero show*. The 16/16 tie is the evidence that taking the house convention costs nothing for a prop that is always documented.

Docs

Updated in all three Stepper.doc.mjs variants (full, --dense, --zh): both props in the prop tables, a new Collapsed summary anatomy row so astryx-stepper-summary is no longer a theme target for a part the docs never mention, and a corrected best practice — the old "use the vertical orientation for narrow containers" now contradicted the component, and would still send an agent to orientation="vertical" on mobile.

Also picked up pre-existing drift while in the same tables: indicatorPosition was missing from both the dense and Chinese prop tables.

Test plan

Six new tests in Stepper.test.tsx:

• drops the controls but keeps the name on request
• drops the name but keeps the controls on request
• leaves the bare track when neither half is wanted
• keeps the sequence whole for a screen reader with both halves off
• leaves a stepper that has room for its labels alone
• leaves on-track nodes pressable after the controls are dropped

Local verification:

• Stepper.test.tsx + docs-drift — 65 passed
• docPropReferences + docPropLiterals — 22 passed, confirming the documented props match the real signature
• astryx component Stepper rendered in all three variants; eslint and prettier clean

Known gap, pre-existing and left alone: docsZh has no anatomy block at all, so the new anatomy row does not reach Chinese readers. Closing that means translating all five entries and felt like a separate change.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 4, 2026 1:25am UTC