Skip to content

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.md
new file mode 100644
index 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.
+
+@imdreamrunner
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 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 edit
import 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.ts
index 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.tsx
new file mode 100644
index 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.ts
index 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.tsx
index 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/componentRegis
import {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.tsx
new file mode 100644
index 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.tsx
index 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 ? (
<Suspense
fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}>
diff --git a/apps/docsite/src/lib/cliSearchPresentation.ts b/apps/docsite/src/lib/cliSearchPresentation.ts
index 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.md
index 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.mjs
index 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 specifier
diff --git a/packages/cli/api/search/_lexical.mjs b/packages/cli/api/search/_lexical.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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 = z
playground: 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.mjs
index 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.ts
index 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.mjs
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 in
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 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.',
},
// build
diff --git a/packages/cli/foundation/response/response-types.doc.test.mjs b/packages/cli/foundation/response/response-types.doc.test.mjs
index 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.json
index 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.mjs
index 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: {