[imdreamrunner]

Stacked on #7712, which is stacked on #7648. This PR's diff is only its delta over #7712. It was split from #7712 to keep that PR under the 2,000 authored-line threshold.

Primary intent

Deprecate BottomSheetSwitcher and the sheetId prop of BottomSheet. #7712 lets standalone sheets run the switcher's replace handoff: closing the top sheet and opening one other sheet in the same update. A multi-step flow can therefore be one standalone BottomSheet per step, driven by one state value that names the open step. The switcher keeps working exactly as released. Only its declarations and documentation change, and a future minor release removes it.

User or maintainer impact

• Existing switcher flows: nothing changes at runtime. Editors show the @deprecated tags on BottomSheetSwitcher, BottomSheetSwitcherProps, and BottomSheet's sheetId, each pointing to the replacement.
• New flows: the docs now teach the replacement first. One step state value; each step is a standalone sheet with isOpen={step === 'id'}, and the same replace handoff runs between steps.
• Non-modal flows (hasScrim={false}) are the one case the switcher still covers alone. Non-modal sheets neither stack nor replace (feat(core): BottomSheet replace handoff on open-order stacking (prototype, stacked on #7648) #7712), so a non-modal step change there is a plain exit and entrance. The deprecation text says so.

Problem and solution fit

Delta	Why
@deprecated JSDoc on BottomSheetSwitcher, BottomSheetSwitcherProps, and BottomSheet's sheetId	spec:AST-017 FR26: public lifecycle state is explicit on the declaration
BottomSheetSwitcher.doc.mjs: descriptions lead with "Deprecated: …"; the replacement example comes first; the switcher example is labelled deprecated; best practices prefer standalone steps	Builders reading the docs or astryx component BottomSheetSwitcher see the replacement before the deprecated API
BottomSheet.doc.mjs: the sheetId prop doc is marked deprecated	It is the switcher's half of the API
[feat] Changeset (patch) with a four-step migration	spec:AST-017 FR28 / FR29d: a deprecation names its replacement and migration and ships with no behaviour change

There is no runtime warning. The repository's whole-component deprecations warn through declarations only (the 0.6 deprecations, removed in #6118, followed the same pattern). Removable tagalongs: none.

Before / after, per flow:

// Before (deprecated, still works)
<BottomSheetSwitcher activeSheet={step} onActiveSheetChange={setStep}>
  <BottomSheet sheetId="details" label="Details">…</BottomSheet>
  <BottomSheet sheetId="confirm" label="Confirm">…</BottomSheet>
</BottomSheetSwitcher>

// After
<BottomSheet isOpen={step === 'details'} onOpenChange={o => !o && setStep(null)} label="Details">…</BottomSheet>
<BottomSheet isOpen={step === 'confirm'} onOpenChange={o => !o && setStep(null)} label="Confirm">…</BottomSheet>

Authority

• spec:AST-017 FR26, FR28, FR29d: lifecycle state, replacement, and migration for a deprecation; removal is a separate [breaking] change in a declared minor.
• The replacement behaviour is feat(core): BottomSheet replace handoff on open-order stacking (prototype, stacked on #7648) #7712's replace handoff. feat(core): BottomSheet replace handoff on open-order stacking (prototype, stacked on #7648) #7712's description drafts the component:BottomSheet claim text that would own it, plus a decision recording this deprecation. That record is cut as a spec PR once the stacking direction is chosen.
• Owner direction: keep BottomSheetSwitcher supported and deprecated for now, and remove it only in a future minor release.

Change and evidence

Five files, +68 / −12: BottomSheetSwitcher.tsx, BottomSheet.tsx (JSDoc only), BottomSheetSwitcher.doc.mjs, BottomSheet.doc.mjs, and the Changeset. No source logic, styles, tests, or stories change.

API audit against #7712's build. The exports map is identical. The public .d.ts files differ only in the added @deprecated tags and doc comments.

Scope

• This PR has one primary intent.
• Independently removable deltas were removed or split.
• Public text and artifacts contain no internal Meta context.

Testing

pnpm exec vitest run packages/core/src/{BottomSheet,Dialog,AlertDialog,Selector,DropdownMenu,ContextMenu,DateInput,DateTimeInput,TimeInput,Tokenizer,Layer,Layout,CommandPalette,MoreMenu,Popover,Lightbox,MobileNav}/ packages/lab/src/MobileTokenizer/
  this branch: Test Files 89 passed, Tests 2537 passed (same as #7712; no test changes)
pnpm -F @astryxdesign/core typecheck                      ✓
ASTRYX_STRICT_LINT=1 pnpm exec eslint packages/core/src/BottomSheet/   0 errors
pnpm check:sync · check:knowledge · check:package-boundaries · check:changesets   ✓
node scripts/sync-exports.js --check                      ✓
git diff --check                                          ✓
node scripts/release/changeset-coverage.mjs pr --base origin/main --head HEAD --released v0.7.1   ✓
pnpm storybook:build                                      ✓

Follow-up, not in this PR: the two CLI block templates that still use the switcher move to standalone steps in a separate change.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 20, 2026 11:04pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🔄 In progress (for maintainers only)	Oct 20, 2026, 10:56 PM UTC

[imdreamrunner]

Folded into #7648, which now carries open-order stacking, the replace handoff, and the BottomSheetSwitcher deprecation as one change.