An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): label deprecated components from their doc (#9046)
Xinzi Zhouea33dafd5fba
diff --git a/.changeset/component-deprecated-field.md b/.changeset/component-deprecated-field.mdnew file mode 100644index 0000000000..0419fba1bc--- /dev/null+++ b/.changeset/component-deprecated-field.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+---++[feat] A component doc can mark its component deprecated with `deprecated: {replacement, description}`: the `name` of the component to use instead and the modernization route. `astryx search` results and `astryx build` kit entries for that component carry the field as `deprecated` (a `deprecated:` line in their text output), and the docsite shows a Deprecated badge in the component's page header (beside any stability badge) and a notice at the top of its page that names and links the replacement, and labels it Deprecated on its components index tile and in site search. `BottomSheetSwitcher` sets it, naming `BottomSheet`; the component keeps working unchanged.++@imdreamrunnerdiff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 4d13f0a5d3..41bdd2d265 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -564,6 +564,18 @@ function sanitizeForJson(obj) {);}+/**+ * A component doc's `deprecated` (what replaces it), copied for the registry;+ * null when the component is not deprecated. `replacementDisplayName` is+ * resolved once every package's components are known.+ * @param {{deprecated?: {replacement: string, description: string}}} doc+ */+function deprecationOf(doc) {+ if (!doc.deprecated) return null;+ const {replacement, description} = doc.deprecated;+ return {replacement, replacementDisplayName: replacement, description};+}+function extractStringArrayField(content, field) {const re = new RegExp(`${field}:\\s*\\[([^\\]]*)\\]`);const match = re.exec(content);@@ -729,6 +741,7 @@ async function generateComponentRegistry() {description: doc.description || parentMeta.topDescription || '',keywords: parentMeta.keywords ?? keywords,hidden: parentMeta.hidden ?? hidden,+ deprecated: deprecationOf(doc),registry,parentDoc: doc.subComponentOf,props: isHookEntry@@ -794,6 +807,7 @@ async function generateComponentRegistry() {description: doc.description || topDescription,keywords,hidden,+ deprecated: deprecationOf(doc),registry,parentDoc: name,props: sanitizeForJson(doc.props),@@ -863,6 +877,7 @@ async function generateComponentRegistry() {description: sub.description || topDescription,keywords,hidden,+ deprecated: null,registry: sub.registry ? sanitizeForJson(sub.registry) : null,parentDoc: doc.name,props: isHookEntry@@ -909,6 +924,7 @@ async function generateComponentRegistry() {description: topDescription,keywords,hidden,+ deprecated: null,registry,parentDoc: dirPrimaryDoc,props: [],@@ -945,6 +961,7 @@ async function generateComponentRegistry() {description: topDescription,keywords,hidden,+ deprecated: deprecationOf(doc),registry,parentDoc: null,props: Array.isArray(doc.props) ? sanitizeForJson(doc.props) : [],@@ -1020,6 +1037,24 @@ async function generateComponentRegistry() {}}+ // A deprecated component's notice links its replacement, so the replacement+ // must be a documented component; its display name labels the link.+ const entriesByName = new Map(+ Object.values(allComponents)+ .flat()+ .map(entry => [entry.name, entry]),+ );+ for (const entry of entriesByName.values()) {+ if (!entry.deprecated) continue;+ const replacement = entriesByName.get(entry.deprecated.replacement);+ if (!replacement || replacement.deprecated) {+ throw new Error(+ `${entry.name} is deprecated in favor of "${entry.deprecated.replacement}", which is not a documented, non-deprecated component. Set \`deprecated.replacement\` to the \`name\` of the component to use instead.`,+ );+ }+ entry.deprecated.replacementDisplayName = replacement.displayName;+ }+const content = `// Auto-generated by scripts/generate-data.mjs — do not editimport type {@@ -1212,6 +1247,9 @@ export interface ComponentEntry {* declares \`stability: 'experimental'\` (spec:AST-017 FR21), and null for* a stable one. */stability: 'experimental' | 'lab' | null;+ /** What replaces a deprecated component, from its doc's \`deprecated\`;+ * null when it is not deprecated. */+ deprecated: ComponentDeprecation | null;registry: {slug?: string; aliases?: string[]} | null;parentDoc: string | null;props: PropDoc[];@@ -1227,6 +1265,15 @@ export interface ComponentEntry {playground: PlaygroundConfig | null;}+export interface ComponentDeprecation {+ /** \`name\` of the documented component to use instead. */+ replacement: string;+ /** That component's display name. */+ replacementDisplayName: string;+ /** The modernization route, in a sentence or two. */+ description: string;+}+export type ElementDescriptor = ComponentSlotElement;export type PlaygroundConfig = ComponentPlaygroundConfig;diff --git a/apps/docsite/src/__tests__/cli-search-presentation.test.ts b/apps/docsite/src/__tests__/cli-search-presentation.test.tsindex 429c5d16d8..212820ba18 100644--- a/apps/docsite/src/__tests__/cli-search-presentation.test.ts+++ b/apps/docsite/src/__tests__/cli-search-presentation.test.ts@@ -33,6 +33,17 @@ describe('site search presentation', () => {result({domain: 'component', name: 'Theme'}),{title: 'Theme', context: 'Component', icon: Shapes},],+ [+ result({+ domain: 'component',+ name: 'OldTheme',+ deprecated: {+ replacement: 'Theme',+ description: 'Render a Theme instead.',+ },+ }),+ {title: 'OldTheme', context: 'Component · Deprecated', icon: Shapes},+ ],[result({domain: 'hook', name: 'useTheme'}),{title: 'useTheme', context: 'Hook', icon: Webhook},diff --git a/apps/docsite/src/__tests__/component-deprecation.test.tsx b/apps/docsite/src/__tests__/component-deprecation.test.tsxnew file mode 100644index 0000000000..237eaee6d3--- /dev/null+++ b/apps/docsite/src/__tests__/component-deprecation.test.tsx@@ -0,0 +1,199 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++// @vitest-environment jsdom++/**+ * @file A deprecated component's page labels it by the title and leads with a+ * notice naming the replacement and linking to its page; a current+ * component's page shows neither. Both read the registry entry's+ * `deprecated`, generated from the component doc.+ */++import {cleanup, render, screen, within} from '@testing-library/react';+import {afterEach, beforeAll, describe, expect, it, vi} from 'vitest';+import {components} from '../generated/componentRegistry';+import {+ DEPRECATED_LABEL,+ DeprecatedBadge,+ DeprecationNotice,+} from '../components/Deprecation';+import {ComponentDetailClient} from '../components/component-detail/ComponentDetailClient';+import ComponentsGalleryPage from '../app/(docs)/components/page';++vi.mock('next/navigation', () => ({+ usePathname: () => '/components/Example',+ useRouter: () => ({replace: () => {}, push: () => {}}),+ useSearchParams: () => new URLSearchParams(),+}));+vi.mock('@stylexjs/stylex', () => ({+ create: <T,>(styles: T) => styles,+ props: () => ({}),+ defineVars: <T,>(vars: T) => vars,+ defineConsts: <T,>(consts: T) => consts,+}));+// The page's previews and tabs are not under test; keep the article light.+vi.mock('../components/component-detail/ShowcasePreview', () => ({+ ShowcasePreview: () => null,+}));+vi.mock('../components/component-detail/PlaygroundPropsTable', () => ({+ PlaygroundPropsTable: () => null,+}));+vi.mock('../components/ShowcaseThumbnail', () => ({+ ShowcaseThumbnail: () => null,+}));+// The playground's theme objects need built theme packages, which the data+// job does not build; the presentation under test reads none of them.+vi.mock('../generated/themeRegistry', () => ({themeObjectsFull: {}}));++// jsdom has no matchMedia; the page's responsive hooks only need an answer.+beforeAll(() => {+ window.matchMedia = (query: string) =>+ ({+ matches: false,+ media: query,+ onchange: null,+ addEventListener: () => {},+ removeEventListener: () => {},+ addListener: () => {},+ removeListener: () => {},+ dispatchEvent: () => false,+ }) as MediaQueryList;+});+afterEach(cleanup);++const all = Object.entries(components).flatMap(([pkg, entries]) =>+ entries.map(entry => ({pkg, entry})),+);++describe('deprecation presentation', () => {+ const deprecation = {+ replacement: 'NewThing',+ replacementDisplayName: 'New Thing',+ description: 'Render a NewThing with steps instead.',+ };++ it('the notice states the status, names the replacement, and links to it', () => {+ render(<DeprecationNotice deprecation={deprecation} />);+ expect(+ screen.getByText(`${DEPRECATED_LABEL}: use New Thing instead`),+ ).toBeTruthy();+ expect(screen.getByText(deprecation.description)).toBeTruthy();+ expect(+ screen.getByRole('link', {name: 'View New Thing'}).getAttribute('href'),+ ).toBe('/components/NewThing');+ });++ it('the badge reads Deprecated, in the neutral variant', () => {+ render(<DeprecatedBadge />);+ expect(+ screen+ .getByText(DEPRECATED_LABEL)+ .closest('.astryx-badge')+ ?.getAttribute('data-variant'),+ ).toBe('neutral');+ });++ it("a deprecated component's page shows the badge in its header line and the notice before its content", () => {+ const found = all.find(({entry}) => entry.deprecated);+ expect(found).toBeDefined();+ const {pkg, entry} = found!;+ render(+ <ComponentDetailClient+ comp={entry}+ pkg={pkg}+ pkgVersion="0.0.0"+ showcase={undefined}+ />,+ );+ const title = screen.getByText(entry.displayName, {+ selector: '.astryx-text, span, p, div',+ });+ // The header's second line: package, version, module, then the badge.+ const headerLine = title.nextElementSibling as HTMLElement;+ expect(headerLine.textContent).toContain(` · ${entry.moduleName}`);+ expect(within(headerLine).getByText(DEPRECATED_LABEL)).toBeTruthy();+ const notice = screen.getByText(+ `${DEPRECATED_LABEL}: use ${entry.deprecated!.replacementDisplayName} instead`,+ );+ // The notice sits below the header and above the tabs.+ // The tab renders its label twice (one copy hidden, for width).+ const [overviewTab] = screen.getAllByText('Overview');+ expect(+ headerLine.compareDocumentPosition(notice) &+ Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ expect(+ notice.compareDocumentPosition(overviewTab) &+ Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ expect(+ screen+ .getByRole('link', {+ name: `View ${entry.deprecated!.replacementDisplayName}`,+ })+ .getAttribute('href'),+ ).toBe(`/components/${entry.deprecated!.replacement}`);+ });++ it('a deprecated component with a stability shows both badges in the header line, stability first', () => {+ const {pkg, entry} = all.find(({entry}) => entry.deprecated)!;+ render(+ <ComponentDetailClient+ comp={{...entry, stability: 'experimental'}}+ pkg={pkg}+ pkgVersion="0.0.0"+ showcase={undefined}+ />,+ );+ const title = screen.getByText(entry.displayName, {+ selector: '.astryx-text, span, p, div',+ });+ const headerLine = title.nextElementSibling as HTMLElement;+ const stability = within(headerLine).getByText('Experimental');+ const deprecated = within(headerLine).getByText(DEPRECATED_LABEL);+ expect(+ stability.compareDocumentPosition(deprecated) &+ Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ });++ it('the components index labels the deprecated tile, and only it', () => {+ const {container} = render(<ComponentsGalleryPage />);+ const deprecatedNames = new Set(+ all.filter(({entry}) => entry.deprecated).map(({entry}) => entry.name),+ );+ const tiles = [+ ...container.querySelectorAll<HTMLAnchorElement>(+ 'a[href^="/components/"]',+ ),+ ];+ expect(tiles.length).toBeGreaterThan(0);+ let labeled = 0;+ for (const tile of tiles) {+ const name = tile.getAttribute('href')!.replace('/components/', '');+ const row = tile.parentElement!.parentElement!;+ const hasBadge = within(row).queryByText(DEPRECATED_LABEL) != null;+ expect(hasBadge, name).toBe(deprecatedNames.has(name));+ if (hasBadge) {+ labeled++;+ }+ }+ expect(labeled).toBeGreaterThan(0);+ });++ it("a current component's page shows no deprecation", () => {+ const {pkg, entry} = all.find(+ ({entry}) => !entry.deprecated && entry.props.length > 0,+ )!;+ render(+ <ComponentDetailClient+ comp={entry}+ pkg={pkg}+ pkgVersion="0.0.0"+ showcase={undefined}+ />,+ );+ expect(screen.queryByText(DEPRECATED_LABEL)).toBeNull();+ expect(screen.queryByText(/^Deprecated: use /)).toBeNull();+ });+});diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex b0575be9b2..d393cc0abd 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -17,6 +17,7 @@ import {describe, it, expect} from 'vitest';import {docs as chatDocs} from '../../../../packages/core/src/Chat/Chat.doc.mjs';import {docs as drawerDocs} from '../../../../packages/core/src/Drawer/Drawer.doc.mjs';import {docs as drawerHeaderDocs} from '../../../../packages/core/src/Drawer/DrawerHeader.doc.mjs';+import {docs as bottomSheetSwitcherDocs} from '../../../../packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs';import docsiteConfig from '../../astryx.config.mjs';import {DEMO_CONTENT_MODULE,@@ -722,6 +723,24 @@ describe('componentRegistry', () => {expect(toolCalls!.parentDoc).toBeNull();});+ it('projects a doc deprecation, naming a documented current replacement', () => {+ const all = Object.values(components).flat();+ const byName = new Map(all.map(entry => [entry.name, entry]));+ const switcher = byName.get(bottomSheetSwitcherDocs.name);+ expect(bottomSheetSwitcherDocs.deprecated).toBeDefined();+ expect(switcher?.deprecated).toMatchObject(+ bottomSheetSwitcherDocs.deprecated!,+ );+ for (const entry of all.filter(e => e.deprecated)) {+ const replacement = byName.get(entry.deprecated!.replacement);+ expect(replacement, entry.name).toBeDefined();+ expect(replacement!.deprecated, entry.name).toBeNull();+ expect(entry.deprecated!.replacementDisplayName).toBe(+ replacement!.displayName,+ );+ }+ });+it('simple components have null parentDoc', () => {const core = components['@astryxdesign/core'];const button = core.find(c => c.name === 'Button');diff --git a/apps/docsite/src/app/(docs)/components/page.tsx b/apps/docsite/src/app/(docs)/components/page.tsxindex ef3a971e8d..bcb144b1b6 100644--- a/apps/docsite/src/app/(docs)/components/page.tsx+++ b/apps/docsite/src/app/(docs)/components/page.tsx@@ -25,6 +25,10 @@ import {components as componentRegistry} from '../../../generated/componentRegisimport {packages} from '../../../generated/packageRegistry';import {showcaseRegistry} from '../../../generated/showcaseRegistry';import {ShowcaseThumbnail} from '../../../components/ShowcaseThumbnail';+import {+ DEPRECATED_LABEL,+ DeprecatedBadge,+} from '../../../components/Deprecation';import {normalizeComponentCategory} from '../../../lib/componentCategories';import {layout} from '../../../layout.stylex';@@ -88,6 +92,8 @@ interface CategoryItem {hasShowcase: boolean;packageName: string;isReady: boolean;+ /** Whether the component's doc marks it deprecated. */+ isDeprecated: boolean;}function ComponentGrid({items}: {items: CategoryItem[]}) {@@ -96,7 +102,11 @@ function ComponentGrid({items}: {items: CategoryItem[]}) {{items.map(item => (<VStack key={`${item.packageName}:${item.name}`} gap={1}><ClickableCard- label={item.displayName}+ label={+ item.isDeprecated+ ? `${item.displayName} (${DEPRECATED_LABEL})`+ : item.displayName+ }href={item.href}padding={0}variant="transparent">@@ -106,7 +116,10 @@ function ComponentGrid({items}: {items: CategoryItem[]}) {<div {...stylex.props(styles.cardImage)} />)}</ClickableCard>- <Text type="supporting">{item.displayName}</Text>+ <HStack gap={2} vAlign="center">+ <Text type="supporting">{item.displayName}</Text>+ {item.isDeprecated && <DeprecatedBadge />}+ </HStack></VStack>))}</Grid>@@ -152,6 +165,7 @@ export default function ComponentsGalleryPage() {hasShowcase: SHOWCASE_NAMES.has(comp.name),packageName,isReady: comp.isReady,+ isDeprecated: comp.deprecated != null,});}}diff --git a/apps/docsite/src/components/Deprecation.tsx b/apps/docsite/src/components/Deprecation.tsxnew file mode 100644index 0000000000..351e1f9074--- /dev/null+++ b/apps/docsite/src/components/Deprecation.tsx@@ -0,0 +1,55 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Deprecation.tsx+ * @input A component registry entry's `deprecated`, generated from its doc's+ * `deprecated` field.+ * @output The label every surface uses for a deprecated component, the+ * Deprecated badge shown in its page header (beside any stability badge) and+ * on its index tile, and the notice on its page that names the replacement+ * and links to it.+ * @position Shared by ComponentDetailClient, the components index, and the+ * search palette, so every surface says the same thing.+ */++import {Badge} from '@astryxdesign/core/Badge';+import {Banner} from '@astryxdesign/core/Banner';+import {Button} from '@astryxdesign/core/Button';+import type {ComponentDeprecation} from '../generated/componentRegistry';++/** The label every surface shows for a deprecated component. */+export const DEPRECATED_LABEL = 'Deprecated';++// Neutral: metadata beside the module name, not an alert. The notice on the+// page carries the message.+export function DeprecatedBadge() {+ return <Badge variant="neutral" label={DEPRECATED_LABEL} />;+}++/**+ * The notice at the top of a deprecated component's page: the status and the+ * replacement in its title, the modernization route below, and a link to the+ * replacement's page.+ */+export function DeprecationNotice({+ deprecation,+}: {+ deprecation: ComponentDeprecation;+}) {+ const replacement = deprecation.replacementDisplayName;+ return (+ <Banner+ status="warning"+ title={`${DEPRECATED_LABEL}: use ${replacement} instead`}+ description={deprecation.description}+ endContent={+ <Button+ variant="secondary"+ size="sm"+ label={`View ${replacement}`}+ href={`/components/${deprecation.replacement}`}+ />+ }+ />+ );+}diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsxindex 66e8186f23..309c3db2c4 100644--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx@@ -33,6 +33,7 @@ import {Accessibility} from './Accessibility';import {HookSignature} from './HookSignature';import {ExampleBlock} from './ExampleBlock';import {MarkdownText} from '../MarkdownText';+import {DeprecatedBadge, DeprecationNotice} from '../Deprecation';import {InteractivePreviewStage,useInteractiveState,@@ -428,10 +429,18 @@ export function ComponentDetailClient({/></>)}+ {comp.deprecated && (+ <>+ {' '}+ <DeprecatedBadge />+ </>+ )}{!comp.isReady && pkg ? ` · npm install ${pkg}@canary` : ''}</Text></VStack>+ {comp.deprecated && <DeprecationNotice deprecation={comp.deprecated} />}+{hasTabs ? (<Suspensefallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}>diff --git a/apps/docsite/src/lib/cliSearchPresentation.ts b/apps/docsite/src/lib/cliSearchPresentation.tsindex 859f546c08..6e5ba5eed1 100644--- a/apps/docsite/src/lib/cliSearchPresentation.ts+++ b/apps/docsite/src/lib/cliSearchPresentation.ts@@ -19,6 +19,7 @@ import {type LucideProps,} from 'lucide-react';import type {SiteSearchResult} from './cliSearchTypes';+import {DEPRECATED_LABEL} from '../components/Deprecation';const FALLBACK_DOC_ROOT_TYPES: Readonly<Record<string, string>> = {'Astryx CLI': 'Reference',@@ -99,7 +100,9 @@ function contextForCatalogResult(result: SiteSearchResult): string {}switch (result.domain) {case 'component':- return 'Component';+ return result.deprecated+ ? `Component · ${DEPRECATED_LABEL}`+ : 'Component';case 'hook':return 'Hook';case 'template':diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 33b15d72d4..9d214cae88 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -495,7 +495,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query, plus package, the npm package that owns the component. || `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. The envelope's package names the same package. || `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |-| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why. |+| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). The result for a deprecated component also carries deprecated {replacement, description}: the name of the component to use instead and the modernization route, from its doc. When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why. || `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. || `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. || `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. |diff --git a/packages/cli/api/search/_gather-components.mjs b/packages/cli/api/search/_gather-components.mjsindex c70d7f0521..6424cb3961 100644--- a/packages/cli/api/search/_gather-components.mjs+++ b/packages/cli/api/search/_gather-components.mjs@@ -73,6 +73,8 @@ async function gatherCoreComponents(coreDir) {let description = '';/** @type {string[]} */let guidance = [];+ /** @type {import('@astryxdesign/cli/authoring').ComponentDeprecation | undefined} */+ let deprecated;if (readme && readme.endsWith('.doc.mjs')) {const loaded = await loadModuleDoc(readme);// A member documented in its family's doc (VStack in Stack's doc) is@@ -83,6 +85,7 @@ async function gatherCoreComponents(coreDir) {keywords = Array.isArray(doc.keywords) ? doc.keywords : [];description = doc.usage?.description || doc.description || '';guidance = guidanceFrom(doc);+ deprecated = doc.deprecated;}for (const [n, place] of familyPlaces(loaded)) places.set(n, place);}@@ -92,6 +95,7 @@ async function gatherCoreComponents(coreDir) {keywords,description,guidance,+ ...(deprecated ? {_deprecated: deprecated} : {}),_package: CORE_PACKAGE,_import: resolveImportPath(coreDir, comp),});@@ -178,6 +182,7 @@ async function gatherIntegrationComponents(loadedIntegrations) {keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],description: doc ? doc.usage?.description || doc.description || '' : '',guidance: guidanceFrom(doc),+ ...(doc?.deprecated ? {_deprecated: doc.deprecated} : {}),...places.get(rec.name),_package: rec.package ?? integration.name,// Exactly what `component` reports: a doc may state its own specifierdiff --git a/packages/cli/api/search/_lexical.mjs b/packages/cli/api/search/_lexical.mjsindex f9d188bcba..b60bc04314 100644--- a/packages/cli/api/search/_lexical.mjs+++ b/packages/cli/api/search/_lexical.mjs@@ -99,6 +99,8 @@ import {toResult, searchedComponentsOf} from './_result.mjs';* @property {'file'|'doc'} [_hold] - How an integration component holds its* name, for the owner rule.* @property {string} [_docPath] - An integration component's doc.+ * @property {import('@astryxdesign/cli/authoring').ComponentDeprecation} [_deprecated] -+ * A deprecated component's replacement, from its doc's `deprecated`.*//**diff --git a/packages/cli/api/search/_result.mjs b/packages/cli/api/search/_result.mjsindex 08ad201191..849c6e08bc 100644--- a/packages/cli/api/search/_result.mjs+++ b/packages/cli/api/search/_result.mjs@@ -49,6 +49,7 @@ export function toResult(...base,import: c._import,command: c._command ?? `astryx component ${c.name}`,+ ...(c._deprecated ? {deprecated: c._deprecated} : {}),};break;case 'hook':diff --git a/packages/cli/api/search/search.deprecated.test.mjs b/packages/cli/api/search/search.deprecated.test.mjsnew file mode 100644index 0000000000..7a89a0724d--- /dev/null+++ b/packages/cli/api/search/search.deprecated.test.mjs@@ -0,0 +1,118 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A deprecated component's search result carries its doc's `deprecated`+ * (the replacement and modernization route), for Core and for an+ * integration, so a reader such as the docsite search can label it. Other+ * component results carry no such field.+ */++import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {afterAll, beforeAll, describe, expect, it} from 'vitest';+import {search} from './search.mjs';+import {findCoreDir} from '../../foundation/fs/paths.mjs';+import {findComponentReadme} from '../../foundation/discovery/component-discovery.mjs';+import {loadModuleDoc} from './_module-doc.mjs';++const SLOW = 60_000;++describe('deprecated component results', () => {+ it(+ "each Core component result carries its doc's deprecation, and only a deprecated one",+ async () => {+ const coreDir = findCoreDir();+ const {results} = (await search('bottom sheet', {type: 'component'}))+ .data;+ const docs = await Promise.all(+ results.map(r =>+ loadModuleDoc(+ /** @type {string} */ (findComponentReadme(coreDir, r.name)),+ ),+ ),+ );+ results.forEach((r, i) => {+ if (docs[i]?.deprecated) {+ expect(r.deprecated, r.name).toEqual(docs[i].deprecated);+ } else {+ expect(r, r.name).not.toHaveProperty('deprecated');+ }+ });+ // The query reaches a deprecated Core component and its replacement.+ const deprecated = results.find(r => r.deprecated);+ expect(deprecated).toBeDefined();+ expect(results.map(r => r.name)).toContain(+ deprecated?.deprecated?.replacement,+ );+ },+ SLOW,+ );++ describe('an integration component (cold start)', () => {+ /** @type {string} */+ let dir;+ const deprecation = {+ replacement: 'TileGrid',+ description: 'Render a TileGrid with columns instead.',+ };+ beforeAll(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-deprecated-'));+ const pkg = path.join(dir, 'node_modules', '@acme', 'tiles');+ fs.mkdirSync(path.join(pkg, 'components'), {recursive: true});+ fs.mkdirSync(+ path.join(dir, 'node_modules', '@astryxdesign', 'core', 'src'),+ {recursive: true},+ );+ fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"consumer"}');+ fs.writeFileSync(+ path.join(dir, 'astryx.config.mjs'),+ "export default { integrations: ['@acme/tiles'] };\n",+ );+ fs.writeFileSync(+ path.join(pkg, 'package.json'),+ '{"name":"@acme/tiles","version":"1.0.0"}',+ );+ fs.writeFileSync(+ path.join(pkg, 'astryx.integration.mjs'),+ "export default { components: './components' };\n",+ );+ for (const [name, extra] of [+ ['TileColumns', {deprecated: deprecation}],+ ['TileGrid', {}],+ ]) {+ fs.writeFileSync(+ path.join(pkg, 'components', `${name}.doc.mjs`),+ `export default ${JSON.stringify({+ type: 'component',+ name,+ usage: {description: `${name} arranges tiles.`},+ props: [],+ ...extra,+ })};\n`,+ );+ fs.writeFileSync(+ path.join(pkg, 'components', `${name}.tsx`),+ `export function ${name}() { return null; }\n`,+ );+ }+ });+ afterAll(() => fs.rmSync(dir, {recursive: true, force: true}));++ it(+ 'carries the deprecation on the deprecated component only',+ async () => {+ const {results} = (await search('tiles', {cwd: dir, type: 'component'}))+ .data;+ expect(results.find(r => r.name === 'TileColumns')).toMatchObject({+ package: '@acme/tiles',+ deprecated: deprecation,+ });+ expect(results.find(r => r.name === 'TileGrid')).not.toHaveProperty(+ 'deprecated',+ );+ },+ SLOW,+ );+ });+});diff --git a/packages/cli/api/search/search.doc.mjs b/packages/cli/api/search/search.doc.mjsindex 59268f5a4d..e5b05c6228 100644--- a/packages/cli/api/search/search.doc.mjs+++ b/packages/cli/api/search/search.doc.mjs@@ -58,7 +58,7 @@ export const doc = {{type: 'search',description:- "The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the topic level (Guides or Foundations) for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `{@command theme add <slug>}` (outside a project, where there is no app to add it to, `{@command theme eject <slug>}`), and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI's own themes). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is `{skipped, reason}`: the domains it skipped (`component`, `hook`, `template`) and why; the results are the docs and themes, and text mode prints one line on standard error.",+ "The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A deprecated component's result also carries `deprecated`, `{replacement, description}` from its doc: the name of the component to use instead and the modernization route. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the topic level (Guides or Foundations) for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `{@command theme add <slug>}` (outside a project, where there is no app to add it to, `{@command theme eject <slug>}`), and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI's own themes). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is `{skipped, reason}`: the domains it skipped (`component`, `hook`, `template`) and why; the results are the docs and themes, and text mode prints one line on standard error.",},],throws: [diff --git a/packages/cli/api/search/search.type.mjs b/packages/cli/api/search/search.type.mjsindex ce257dfe68..7202d6c5ba 100644--- a/packages/cli/api/search/search.type.mjs+++ b/packages/cli/api/search/search.type.mjs@@ -33,6 +33,7 @@* @property {string} [parent] - Command that opens the level above a doc result — its topic's section list for a section, the docs-tree namespace it sits in for a tree node — so a reader can see the siblings and open another.* @property {string} [displayName] - Friendly display name — present for template and theme results.* @property {'page' | 'block'} [kind] - Template kind (`page` | `block`) — present for template results.+ * @property {import('@astryxdesign/cli/authoring').ComponentDeprecation} [deprecated] - The replacement and modernization route — present for a deprecated component, from its doc's `deprecated`.*//**diff --git a/packages/cli/authoring/doctypes/_schema.mjs b/packages/cli/authoring/doctypes/_schema.mjsindex e66fc698a8..9bb2d36239 100644--- a/packages/cli/authoring/doctypes/_schema.mjs+++ b/packages/cli/authoring/doctypes/_schema.mjs@@ -306,6 +306,17 @@ const BaseDocFields = {isHiddenFromOverview: z.boolean().optional(),};+/**+ * A deprecated component's replacement (`ComponentBaseDoc.deprecated`). Strict:+ * the docsite and search read both fields, so a misspelled one fails to load.+ */+const ComponentDeprecationSchema = z+ .object({+ replacement: nonEmptyString,+ description: nonEmptyString,+ })+ .strict();+const ComponentBaseSchema = z.object({...BaseDocFields,@@ -314,6 +325,7 @@ const ComponentBaseSchema = zplayground: z.unknown().optional(),examples: z.array(z.unknown()).optional(),replaces: z.string().min(1).optional(),+ deprecated: ComponentDeprecationSchema.optional(),}).passthrough();@@ -776,10 +788,12 @@ const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({props: z.array(PropSchema),+ deprecated: ComponentDeprecationSchema.optional(),}).passthrough();const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({components: z.array(z.unknown()),+ deprecated: ComponentDeprecationSchema.optional(),}).passthrough();const LegacyHookDocSchema = LegacyBaseDocSchema.extend({@@ -791,6 +805,7 @@ const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({subComponentOf: z.string().min(1, 'subComponentOf is required'),description: z.string(),props: z.array(PropSchema),+ deprecated: ComponentDeprecationSchema.optional(),}).passthrough();/** The permissive legacy union (sub-component, hook, multi, single, then reference). */diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjsindex e371c25fc5..2c5fc63226 100644--- a/packages/cli/authoring/doctypes/component/component.doc.mjs+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs@@ -58,6 +58,12 @@ export const doc = {description:'Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package\'s peer range starts at the release that applies it, `"@astryxdesign/cli": ">=0.6.7"` or later; with a lower range nothing changes and `doctor integration components` warns ({@link generic:replace-a-core-component}). Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.',},+ {+ name: 'deprecated',+ type: '{replacement: string; description: string}',+ description:+ "Marks a deprecated component: it keeps working and stays documented, labeled with what replaces it. `replacement` is the `name` of the documented component to use instead; `description` is the modernization route in a sentence or two. The docsite shows a Deprecated badge in the component's page header and index tile, labels its search result, and adds a notice that links the replacement; `astryx search` results and `astryx build` kit entries carry the field. Omit it for a component that is not deprecated.",+ },{name: 'keywords',type: 'string[]',diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.tsindex 5c223a6feb..14893c1b6e 100644--- a/packages/cli/authoring/doctypes/component/type.ts+++ b/packages/cli/authoring/doctypes/component/type.ts@@ -21,6 +21,15 @@ import type {UsageDoc,} from '../base/type.js';+/** What replaces a deprecated component (`ComponentBaseDoc.deprecated`). */+export interface ComponentDeprecation {+ /** `name` of the documented component to use instead, e.g. `'BottomSheet'`. */+ replacement: string;+ /** The modernization route in a sentence or two: what to write instead,+ * and where the migration is described. */+ description: string;+}+/*** Shared fields between single-component and multi-component docs.* Do not use this interface directly — use `ComponentDoc` (the union type).@@ -63,6 +72,13 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {* range, and on older CLIs that do not read `replaces`, the component keeps* its own name. */replaces?: string;+ /** Marks a deprecated component (spec:AST-017 FR26, FR29b): it keeps+ * working and stays documented, labeled with its replacement. The docsite+ * shows a Deprecated badge in its page header and index tile, labels its+ * search result, and adds a notice that links the replacement; `astryx+ * search` results and `astryx build` kit entries carry the field. Omit for+ * a component that is not deprecated. */+ deprecated?: ComponentDeprecation;/** Search keywords for CLI discovery. Terms a developer might type when* looking for this component: synonyms, related UI concepts, and common* names from other design systems (MUI, Chakra, Radix, and others).diff --git a/packages/cli/authoring/doctypes/parse.test.mjs b/packages/cli/authoring/doctypes/parse.test.mjsindex b92a21031c..f2e2bb7e42 100644--- a/packages/cli/authoring/doctypes/parse.test.mjs+++ b/packages/cli/authoring/doctypes/parse.test.mjs@@ -177,6 +177,43 @@ describe('per-kind parsers (stamped format)', () => {parseDoc({name: 'Widget', props: [], audience: 'secret'}),).toThrow();});++ it('accepts a deprecated component that names its replacement, stamped or not', () => {+ const deprecated = {+ replacement: 'Gauge',+ description: 'Render a Gauge instead.',+ };+ const {type, ...loose} = goodComponent;+ expect(parseComponent({...goodComponent, deprecated}).deprecated).toEqual(+ deprecated,+ );+ expect(parseDoc({...loose, deprecated}).deprecated).toEqual(deprecated);+ expect(+ parseDoc({+ name: 'Part',+ subComponentOf: 'Widget',+ description: 'A part.',+ props: [],+ deprecated,+ }).deprecated,+ ).toEqual(deprecated);+ });++ it('rejects a deprecation without a replacement or with a field it does not know', () => {+ const {type, ...loose} = goodComponent;+ for (const deprecated of [+ {description: 'Render a Gauge instead.'},+ {replacement: '', description: 'Render a Gauge instead.'},+ {replacement: 'Gauge'},+ {replacement: 'Gauge', description: 'Render a Gauge.', since: '0.7.5'},+ 'Use Gauge.',+ ]) {+ expect(() => parseComponent({...goodComponent, deprecated})).toThrow(+ /deprecated/u,+ );+ expect(() => parseDoc({...loose, deprecated})).toThrow();+ }+ });});describe('parseDoc (load boundary, both formats)', () => {diff --git a/packages/cli/authoring/index.d.ts b/packages/cli/authoring/index.d.tsindex 9dda79baff..fd44355713 100644--- a/packages/cli/authoring/index.d.ts+++ b/packages/cli/authoring/index.d.ts@@ -118,6 +118,7 @@ export type {SingleComponentDoc,MultiComponentDoc,ComponentEntry,+ ComponentDeprecation,ComponentGroupDoc,ComponentTranslationDoc,ComponentPropDoc,diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjsindex e1d96a01d4..912b2f100b 100644--- a/packages/cli/clients/cli/commands/build.mjs+++ b/packages/cli/clients/cli/commands/build.mjs@@ -21,6 +21,7 @@ import {jsonOut} from '../../../foundation/response/json.mjs';import {resultSet, resultSetOf} from '../../../foundation/debug/index.mjs';import {emit,+ formatDeprecation,section,text,list,@@ -172,18 +173,23 @@ export function registerBuild(program) {'package','domain','displayName',+ 'deprecated','score','reason','import','description','command',],- format: {command: formatCliCommand},+ format: {command: formatCliCommand, deprecated: formatDeprecation},};/** @param {string[]} fields */const brief = fields => ({fields,- format: {command: formatCliCommand, description: firstSentence},+ format: {+ command: formatCliCommand,+ description: firstSentence,+ deprecated: formatDeprecation,+ },});// Blocks and components are extras: the text names the top few, and// says how many more the JSON and --verbose carry.@@ -277,7 +283,7 @@ export function registerBuild(program) {? [records(shown(domain),- verbose ? full : brief(['name', 'package', 'description']),+ verbose ? full : brief(['name', 'package', 'deprecated', 'description']),),]: []),diff --git a/packages/cli/clients/cli/commands/build.text-fields.test.mjs b/packages/cli/clients/cli/commands/build.text-fields.test.mjsindex dbdea3f528..43bdeda190 100644--- a/packages/cli/clients/cli/commands/build.text-fields.test.mjs+++ b/packages/cli/clients/cli/commands/build.text-fields.test.mjs@@ -43,6 +43,21 @@ describe('build kit text fields mirror the JSON keys', () => {for (const field of fields) expect(keys).toContain(field);}, SLOW);+ it("prints a deprecated component's `deprecated` field, as search does", async () => {+ const idea = 'step by step wizard in a bottom sheet';+ const json = await runCli(['build', idea, '--json', '--verbose'], REPO);+ expect(json.status).toBe(0);+ const {domain} = JSON.parse(json.stdout).data;+ const deprecated = domain.find(entry => entry.deprecated);+ expect(deprecated, 'the idea reaches a deprecated component').toBeDefined();+ const line = `deprecated: use ${deprecated.deprecated.replacement}: `;+ for (const args of [['build', idea, '--verbose'], ['build', idea]]) {+ const human = await runCli(args, REPO);+ expect(human.status).toBe(0);+ expect(human.stdout, args.join(' ')).toContain(line);+ }+ }, SLOW);+it('leads with the start, then the alternatives, blocks and components', async () => {const human = await runCli(['build', 'analytics dashboard'], REPO);expect(human.status).toBe(0);diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjsindex e71711d5a5..187ac5ee9e 100644--- a/packages/cli/clients/cli/commands/search.mjs+++ b/packages/cli/clients/cli/commands/search.mjs@@ -27,7 +27,7 @@ import {} from '../../../foundation/env/package-manager.mjs';import {jsonOut} from '../../../foundation/response/json.mjs';import {resultSetOf} from '../../../foundation/debug/index.mjs';-import {emit, section, text, records} from '../formatters/index.mjs';+import {emit, formatDeprecation, section, text, records} from '../formatters/index.mjs';import {cliError} from '../lib/cli-error.mjs';import {defineCommand} from '../lib/define-command.mjs';import {search as searchApi} from '../../../api/search/search.mjs';@@ -145,6 +145,7 @@ export function registerSearch(program) {'title','displayName','kind',+ 'deprecated','score','reason','import',@@ -160,6 +161,7 @@ export function registerSearch(program) {'title','displayName','kind',+ 'deprecated','import','description','command',@@ -177,7 +179,11 @@ export function registerSearch(program) {),records(results, {fields,- format: {command: formatCliCommand, parent: formatCliCommand},+ format: {+ command: formatCliCommand,+ parent: formatCliCommand,+ deprecated: formatDeprecation,+ },}),...note,...discoverHint(run, q, options.type),diff --git a/packages/cli/clients/cli/formatters/index.mjs b/packages/cli/clients/cli/formatters/index.mjsindex dcc8f17334..93cc381f51 100644--- a/packages/cli/clients/cli/formatters/index.mjs+++ b/packages/cli/clients/cli/formatters/index.mjs@@ -371,6 +371,17 @@ function isBlock(b) {return b instanceof Block;}+/**+ * The text value of a deprecated component's `deprecated` field: the component+ * to use instead, then the modernization route. Every command that prints a+ * component result's fields prints it this way.+ * @param {{replacement: string, description: string}} deprecation+ * @returns {string}+ */+export function formatDeprecation(deprecation) {+ return `use ${deprecation.replacement}: ${deprecation.description}`;+}+/*** The one sanctioned way to write human output to stdout. Joins blocks with a* single blank line and hands the result to `humanLog`, which is a no-op indiff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex b13f3c2819..5a37d999f6 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -238,7 +238,7 @@ export const doc = {{value: 'search',description:- 'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why.',+ 'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). The result for a deprecated component also carries deprecated {replacement, description}: the name of the component to use instead and the modernization route, from its doc. When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why.',},// builddiff --git a/packages/cli/foundation/response/response-types.doc.test.mjs b/packages/cli/foundation/response/response-types.doc.test.mjsindex dc51159076..ec022c349a 100644--- a/packages/cli/foundation/response/response-types.doc.test.mjs+++ b/packages/cli/foundation/response/response-types.doc.test.mjs@@ -119,12 +119,24 @@ describe('response-types EnumDoc names every field', () => {it('search, across component, hook, template, and doc results', async () => {const mixed = await data(['search', 'dashboard', '--limit', '50']);const docsOnly = await data(['search', 'tokens', '--type', 'doc']);+ // Reaches a deprecated component, whose result carries `deprecated`.+ const deprecated = await data([+ 'search',+ 'switcher',+ '--type',+ 'component',+ ]);expect(new Set(mixed.data.results.map(r => r.domain))).toContain('template',);+ expect(deprecated.data.results.some(r => r.deprecated)).toBe(true);expectNamed('search',- new Set([...fieldsOf(mixed.data), ...fieldsOf(docsOnly.data)]),+ new Set([+ ...fieldsOf(mixed.data),+ ...fieldsOf(docsOnly.data),+ ...fieldsOf(deprecated.data),+ ]),);});diff --git a/packages/cli/test/__golden__/no-icon-set/search-close.json b/packages/cli/test/__golden__/no-icon-set/search-close.jsonindex 8093efa4d8..dc1a01162b 100644--- a/packages/cli/test/__golden__/no-icon-set/search-close.json+++ b/packages/cli/test/__golden__/no-icon-set/search-close.json@@ -36,6 +36,10 @@"description": "<text>","import": "@astryxdesign/core/BottomSheet","command": "astryx component BottomSheetSwitcher",+ "deprecated": {+ "replacement": "<text>",+ "description": "<text>"+ },"mentions": []},{diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs b/packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjsindex 6c750b0573..56822dfbb2 100644--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs+++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs@@ -29,6 +29,11 @@ export const docs = {group: 'BottomSheet',category: 'Overlay',keywords: ['bottom sheet', 'switcher', 'multi-step', 'flow', 'wizard'],+ deprecated: {+ replacement: 'BottomSheet',+ description:+ 'Write each step as its own BottomSheet with isOpen, controlled by one state value that names the open step; moving on from inside the open step replaces it in place (see BottomSheet, Replacing a sheet). BottomSheetSwitcher keeps working until a future minor release removes it.',+ },playground: {overlay: true,overlayControl: {