An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): complete and correct component replacement (#7180)
Joey9fbfdc043910
diff --git a/.changeset/integration-component-replacements.md b/.changeset/integration-component-replacements.mdindex 765d72381c..11cca93d81 100644--- a/.changeset/integration-component-replacements.md+++ b/.changeset/integration-component-replacements.md@@ -4,7 +4,7 @@[feat] An integration component can replace a Core component, once its package opts in-A component whose doc sets `replaces: 'SideNav'` takes over `SideNav` for unqualified component detail, batch selectors, every `component --list` detail level, `search`, `swizzle`, and gap-report routing, when its package declares `"@astryxdesign/cli": ">=0.6.7"` in `peerDependencies` (optional in `peerDependenciesMeta`). The replacement keeps answering to its own name, every result names its package, and `--package @astryxdesign/core` still selects the original Core component.+An `@acme/nav` component whose doc sets `replaces: 'SideNav'` takes over `SideNav` for unqualified component detail, batch selectors, every `component --list` detail level, `search`, `swizzle`, and gap-report routing, when `@acme/nav` declares `"@astryxdesign/cli": ">=0.6.7"` in `peerDependencies` (optional in `peerDependenciesMeta`). Every result names its package, `--package @astryxdesign/core` still selects the original Core component, and the replacement keeps answering to its own name. `component SideNav --package @acme/nav` also selects it.-Any `@astryxdesign/cli` range that starts at 0.6.7 or later is the opt-in, including the `>=0.7.0` that `integration add doc --parent` wrote in 0.6.4 and 0.6.5, and `integration add theme` in 0.6.5. A package whose range admits an earlier CLI keeps its component under its own name and Core stays selected, and an app that loads it sees no new output; its author gets warnings naming the range to add, from `astryx doctor integration components` and `integration pack --check`. `component SideNav --package <that package>` also selects the replacement. For a package that declares the range, `astryx doctor integration components` reports a missing Core target, an invalid value, a component named after a different Core component, or two replacements for one target in the package as errors and exits 1. When several packages replace one target, an explicitly configured package beats an autolinked one, the later configured package wins, and Doctor warns.+Any `@astryxdesign/cli` range that starts at 0.6.7 or later is the opt-in, including the `>=0.7.0` that `integration add doc --parent` wrote in 0.6.4 and 0.6.5, and `integration add theme` in 0.6.5. A package whose range admits an earlier CLI keeps its component under its own name and Core stays selected, and an app that loads it sees no new output; its author gets warnings naming the range to add, from `astryx doctor integration components` and `integration verify`. For a package that declares the range, `astryx doctor integration components` reports a missing Core target, an invalid value, a component named after a different Core component, or two replacements for one target in the package as errors and exits 1. When several packages replace one target, an explicitly configured package beats an autolinked one, the later configured package wins, and Doctor warns.@josephfarinadiff --git a/packages/cli/api/component/component-replacement.test.mjs b/packages/cli/api/component/component-replacement.test.mjsindex 1dc0e9f006..d4bf384f42 100644--- a/packages/cli/api/component/component-replacement.test.mjs+++ b/packages/cli/api/component/component-replacement.test.mjs@@ -12,6 +12,7 @@ import * as path from 'node:path';import {component} from './component.mjs';import {componentKeywords, search} from '../search/search.mjs';import {swizzleCopy} from '../swizzle/copy/copy.mjs';+import {swizzle} from '../swizzle/swizzle.mjs';import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';import {GAP_REPORT_CATEGORIES, gapReport} from '../gap-report/gap-report.mjs';import {Project} from '../../foundation/config/project.mjs';@@ -248,6 +249,17 @@ describe('a package that declares the CLI floor', () => {SLOW,);+ it(+ 'leaves the swizzle list naming Core components, the replaced one included',+ async () => {+ const listed = await swizzle(undefined, {cwd: tmpDir, list: true});+ expect(listed.type).toBe('swizzle.list');+ expect(listed.data).toContain('SideNav');+ expect(listed.data).not.toContain('AcmeSideNav');+ },+ SLOW,+ );+it('routes issues and reports no findings for a valid replacement',async () => {diff --git a/packages/cli/api/component/component.doc.mjs b/packages/cli/api/component/component.doc.mjsindex 057d62dcaf..4b8cfe5ae4 100644--- a/packages/cli/api/component/component.doc.mjs+++ b/packages/cli/api/component/component.doc.mjs@@ -21,7 +21,10 @@ export const doc = {'integration packages; an array returns one ordered result row per selector at ' +'every array length; and no name returns the catalog grouped by category. ' +'Boolean flags narrow each resolved component to just its props, source, ' +- 'showcase, or example blocks.',+ 'showcase, or example blocks. An integration component that replaces a Core ' ++ 'component (its doc sets replaces, and its package declares the CLI range that ' ++ 'turns replacement on) answers to the Core name in detail, batch, and list ' ++ "results; use options.package '@astryxdesign/core' for the original.",importPath: '@astryxdesign/cli/api',signature:'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',@@ -62,7 +65,7 @@ export const doc = {name: 'options.package',type: 'string',description:- "Scope lookup to a specific external package (e.g. '@acme/widgets').",+ "Scope lookup to a specific external package (e.g. '@acme/widgets'). Use '@astryxdesign/core' to select an original replaced by an integration component.",},{name: 'options.props',diff --git a/packages/cli/api/gap-report/gap-report.doc.mjs b/packages/cli/api/gap-report/gap-report.doc.mjsindex bfa9a334a6..e5d7d12336 100644--- a/packages/cli/api/gap-report/gap-report.doc.mjs+++ b/packages/cli/api/gap-report/gap-report.doc.mjs@@ -15,6 +15,7 @@ export const doc = {summary:'Report a missing or hard-to-use design-system capability to the package that owns it.',description:+ 'Routes the report to the package that owns the gap: options.package when given, else the integration whose component replaces the named Core component, else the one package that provides the component, else Core. ' +'Sends a gap report to every configured handler: the project config handler first, then each integration handler in config order. ' +'Each handler has 30 s to finish, and its output goes to stderr. Public handlers run only with confirmPublic; internal handlers always run. ' +"With no handler, it files a GitHub issue for the owning package only with confirmPublic (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +@@ -60,7 +61,7 @@ export const doc = {name: 'options.package',type: 'string',description:- 'Package that owns the gap: @astryxdesign/core, or a loaded integration by package name or config entry. Overrides automatic owner routing; required when more than one package provides the component.',+ 'Package that owns the gap: @astryxdesign/core, or a loaded integration by package name or config entry. Overrides automatic owner routing, which picks the integration whose component replaces the named Core component, else the one package that provides it, else Core; required when more than one package provides the component.',},{name: 'options.confirmPublic',diff --git a/packages/cli/api/swizzle/swizzle.doc.mjs b/packages/cli/api/swizzle/swizzle.doc.mjsindex bf594dfa1f..8caafc8785 100644--- a/packages/cli/api/swizzle/swizzle.doc.mjs+++ b/packages/cli/api/swizzle/swizzle.doc.mjs@@ -19,7 +19,10 @@ export const doc = {'It copies from the locally resolved @astryxdesign/core (or the owning integration) ' +'package source, rewriting imports that escape the component directory to the owner ' +"package's subpaths and flagging whether any copied file uses StyleX. With no name " +- '(or list) it returns the swizzlable component names instead.',+ '(or list) it returns the swizzlable component names instead. An integration ' ++ 'component that replaces a Core component is what that Core name copies; ' ++ "options.package '@astryxdesign/core' copies the original. The list names Core " ++ 'components, including one an integration component replaces.',importPath: '@astryxdesign/cli/api',signature:'swizzle(component?: string, options?: SwizzleOptions): Promise<SwizzleListResponse | SwizzleCopyResponse>',@@ -48,7 +51,7 @@ export const doc = {name: 'options.package',type: 'string',description:- 'Owning package to copy from when the name is provided by more than one.',+ "Owning package to copy from when the name is provided by more than one. Use '@astryxdesign/core' to copy an original replaced by an integration component.",},{name: 'options.list',diff --git a/packages/cli/clients/cli/commands/component-replacement.text.test.mjs b/packages/cli/clients/cli/commands/component-replacement.text.test.mjsindex 5338853c81..d1897dc9bf 100644--- a/packages/cli/clients/cli/commands/component-replacement.text.test.mjs+++ b/packages/cli/clients/cli/commands/component-replacement.text.test.mjs@@ -218,6 +218,51 @@ describe('component list text', () => {expect(run.stdout).toContain('AcmeSideNav');},);++ it('prints only the requested category at full detail', async () => {+ const layout = await runCli(+ ['component', '--list', '--category', 'Layout', '--detail', 'full'],+ {cwd: tmpDir},+ );+ expect(layout.status, layout.stderr).toBe(0);+ expect(layout.stdout.match(/^## .+$/gm)).toEqual(['## Layout']);+ expect(layout.stdout).not.toContain('@astryxdesign/core/SideNav');+ expect(layout.stdout).not.toContain('AcmeSideNav');++ const navigation = await runCli(+ ['component', '--list', '--category', 'Navigation', '--detail', 'full'],+ {cwd: tmpDir},+ );+ expect(navigation.status, navigation.stderr).toBe(0);+ expect(navigation.stdout.match(/^## .+$/gm)).toEqual(['## Navigation']);+ expect(navigation.stdout).toMatch(+ /^AcmeSideNav {2}<- from '@acme\/nav\/components\/AcmeSideNav' {2}\[@acme\/nav\]$/m,+ );+ expect(navigation.stdout).not.toMatch(/^SideNav[( ]/m);+ });++ it.each(['brief', 'compact'])(+ 'prints only the requested category at %s detail',+ async detail => {+ const layout = await runCli(+ ['component', '--category', 'Layout', '--detail', detail],+ {cwd: tmpDir},+ );+ expect(layout.status, layout.stderr).toBe(0);+ expect(layout.stdout).not.toContain('@astryxdesign/core/SideNav');+ expect(layout.stdout).not.toContain('AcmeSideNav');++ const navigation = await runCli(+ ['component', '--category', 'Navigation', '--detail', detail],+ {cwd: tmpDir},+ );+ expect(navigation.status, navigation.stderr).toBe(0);+ expect(navigation.stdout).toContain(+ '@acme/nav/components/AcmeSideNav [@acme/nav]',+ );+ expect(navigation.stdout).not.toMatch(/^name: +SideNav$/m);+ },+ );});describe('help documents the replacement', () => {diff --git a/packages/cli/clients/cli/commands/component/index.mjs b/packages/cli/clients/cli/commands/component/index.mjsindex 5b865552cc..e96244b08b 100644--- a/packages/cli/clients/cli/commands/component/index.mjs+++ b/packages/cli/clients/cli/commands/component/index.mjs@@ -292,7 +292,9 @@ export function registerComponent(program) {// --detail full — dense per-component docs (signature, props, theming,// examples). Verbatim doc block from the shared formatter. A Core slot// an integration component replaces prints that component, from the- // list result (spec:AST-035 FR11).+ // list result (spec:AST-035 FR11). Only the result's groups print, so+ // `--category` text shows what its JSON shows and every printed slot+ // is covered by the replacement map built from that result./** @type {Map<string, any>} */const replacements = new Map();for (const items of Object.values(result.data.components)) {@@ -312,6 +314,7 @@ export function registerComponent(program) {lang,themeData,replacements,+ categories: Object.keys(result.data.components),}),),);diff --git a/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjsindex a8c95b3fcc..6a3cfd621e 100644--- a/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs+++ b/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs@@ -17,7 +17,7 @@ export const doc = {'range that turns replacement on, a missing Core target, an invalid value, a ' +'component named after a different Core component, or two replacements for one ' +'Core component is an error. In a package without that range they are warnings, ' +- 'with one more warning naming the range to declare.',+ 'with a warning for each such component, naming the range to declare.',fn: 'integrationComponentConflicts',args: [{diff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjsindex daff80ef0a..daa44a4da5 100644--- a/packages/cli/clients/cli/lib/component-format.mjs+++ b/packages/cli/clients/cli/lib/component-format.mjs@@ -638,20 +638,30 @@ export function formatProps(docs, componentName) {* Format brief summaries for ALL components in one output.* `replacements` maps a replaced Core name to the full list entry of the* integration component that takes its slot; that entry is printed in its- * place, naming its package.+ * place, naming its package. `categories`, when given, limits the output to+ * those group keys (the keys of the list result it renders), so the text shows+ * the same groups as the JSON and `replacements` covers every slot it prints.* @param {string} coreDir- * @param {{zh?: boolean, lang?: string, themeData?: any, replacements?: Map<string, any>}} [options]+ * @param {{zh?: boolean, lang?: string, themeData?: any, replacements?: Map<string, any>, categories?: string[]}} [options]* @returns {Promise<string>}*/export async function formatBriefAll(coreDir,- {zh = false, lang, themeData = null, replacements = new Map()} = {},+ {+ zh = false,+ lang,+ themeData = null,+ replacements = new Map(),+ categories,+ } = {},) {const components = discoverComponents(coreDir);+ const shown = categories ? new Set(categories) : null;/** @type {string[]} */const output = [];for (const [key, comps] of Object.entries(components)) {+ if (shown && !shown.has(key)) continue;const isUngrouped = comps.length === 1 && comps[0] === key;if (!isUngrouped) {output.push(`## ${key}\n`);