An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): translated component docs must not drop props (#3892)
AK02f2602bb429
diff --git a/.changeset/component-doc-overlay-prop-drop.md b/.changeset/component-doc-overlay-prop-drop.mdnew file mode 100644index 0000000000..874d8796f5--- /dev/null+++ b/.changeset/component-doc-overlay-prop-drop.md@@ -0,0 +1,13 @@+---+'@astryxdesign/cli': patch+---++[fix] Translated component docs no longer drop props++A `docsZh` / `docsDense` block that carried its own `props` array replaced the English component doc **wholesale** rather than overlaying it, so any prop the translation had not caught up with simply ceased to exist. `astryx component Button --zh` silently omitted `isInterruptible` and `isIconOnly`; ten components were affected, including `MobileNav`, `Popover` and `Stack` through the multi-component `components[]` shape.++A reader of the translated docs cannot discover a prop that is not there — and `CLAUDE.md` instructs every AI agent to read `astryx component <Name>` before touching a component, so a missing prop is a prop that never gets used.++Translations are now an overlay, matched by prop **name** rather than position: a prop the translation does not cover falls back to its English entry instead of vanishing, and the prop's contract (`type`, `default`, `required`) stays authoritative from the English doc while the translation supplies the prose. Existing Chinese descriptions are unaffected. A test asserts no translated view can drop a prop the English doc documents.++@AKnassadiff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjsindex 38b42eed8b..d691f57837 100644--- a/packages/cli/src/lib/component-loader.mjs+++ b/packages/cli/src/lib/component-loader.mjs@@ -144,15 +144,64 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {const translation = mod[translationKey];- // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly+ // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be+ // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop+ // the translation had not caught up with simply ceased to exist —+ // `component Button --zh` silently omitted `isInterruptible` and+ // `isIconOnly`. A reader of the translated docs cannot discover a prop that+ // is not there. Overlay it instead, so an untranslated prop falls back to+ // its English entry. (Same principle as the reference-doc overlays, #2182.)if (translation.props || translation.components?.some(c => c.props)) {- return translation;+ return overlayComponentDoc(docs, translation);}// Otherwise it's a TranslationDoc — merge it onto docsreturn mergeTranslation(docs, translation);}+/**+ * Overlay a full-ComponentDoc-shaped translation onto the English doc.+ *+ * Base order and completeness win; the translation supplies text for the+ * entries it covers. Props are matched by name, never by position, so a+ * translation that is missing entries (or lists them in another order) can no+ * longer drop or misattribute one.+ *+ * @param {any} docs Base (English) component doc.+ * @param {any} translation Translated doc, possibly covering only some props.+ * @returns {any} Merged doc with every base prop present.+ */+function overlayComponentDoc(docs, translation) {+ /** Merge one prop list: keep base entries and order, translate what's covered. */+ const overlayProps = (baseProps, tProps) => {+ if (!baseProps) return baseProps;+ const byName = new Map((tProps ?? []).map(p => [p.name, p]));+ return baseProps.map(prop => {+ const t = byName.get(prop.name);+ // Take the translated text, but never let it drop the prop's contract+ // (type/default/required stay authoritative from the English doc).+ return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;+ });+ };++ const merged = {...docs, ...translation};++ merged.props = overlayProps(docs.props, translation.props);++ if (docs.components) {+ const tByName = new Map(+ (translation.components ?? []).map(c => [c.name, c]),+ );+ merged.components = docs.components.map(base => {+ const t = tByName.get(base.name);+ if (!t) return base;+ return {...base, ...t, props: overlayProps(base.props, t.props)};+ });+ }++ return merged;+}+/*** Find the doc file for a component, checking both top-level* and nested directories. Prefers {Name}.doc.mjs, then README.mddiff --git a/packages/cli/src/lib/componentDocOverlay.test.mjs b/packages/cli/src/lib/componentDocOverlay.test.mjsnew file mode 100644index 0000000000..d5e13895fd--- /dev/null+++ b/packages/cli/src/lib/componentDocOverlay.test.mjs@@ -0,0 +1,111 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Guards translated/compressed component docs against dropping props.+ * @input packages/core/src/{Name}/{Name}.doc.mjs — its `docs`, `docsZh`, `docsDense`.+ * @output Vitest failures naming every prop that exists in `docs` but vanishes+ * from a translated view.+ * @position Regression gate for component-loader.mjs.+ *+ * A `docsZh` that carries its own `props` array used to REPLACE the base doc+ * wholesale, so any prop the translation had not caught up with simply ceased+ * to exist: `astryx component Button --zh` silently omitted `isInterruptible`+ * and `isIconOnly`. A reader of the translated docs cannot discover a prop that+ * is not there, and CLAUDE.md tells every AI agent to read these docs.+ *+ * Translations are now an overlay: a prop the translation does not cover falls+ * back to its English entry rather than disappearing. Same principle as the+ * reference-doc overlays in #2182 — an overlay covering a subset must not+ * destroy what it does not cover.+ */++import {describe, it, expect} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {pathToFileURL} from 'node:url';+import {loadDocs} from './component-loader.mjs';++const CORE_SRC = path.join(+ import.meta.dirname,+ '..',+ '..',+ '..',+ 'core',+ 'src',+);++/** Component dirs that ship a doc file. */+function componentDocs() {+ const out = [];+ for (const dir of fs.readdirSync(CORE_SRC)) {+ const docPath = path.join(CORE_SRC, dir, `${dir}.doc.mjs`);+ if (!fs.existsSync(docPath)) continue;+ if (!fs.readdirSync(path.join(CORE_SRC, dir)).includes(`${dir}.doc.mjs`)) {+ continue; // case-exact match only+ }+ out.push({name: dir, docPath});+ }+ return out;+}++/** Prop names on a doc, across single- and multi-component shapes. */+function propNames(doc) {+ const names = new Set();+ for (const p of doc?.props ?? []) names.add(p.name);+ for (const c of doc?.components ?? []) {+ for (const p of c.props ?? []) names.add(`${c.name ?? '?'}.${p.name}`);+ }+ return names;+}++describe('translated component docs never drop a prop', () => {+ const comps = componentDocs();++ it('finds component docs to check', () => {+ expect(comps.length).toBeGreaterThan(0);+ });++ for (const {name, docPath} of comps) {+ for (const locale of ['zh', 'dense']) {+ it(`${name} --${locale}: documents every prop the English doc documents`, async () => {+ const mod = await import(pathToFileURL(docPath).href);+ const key = locale === 'zh' ? 'docsZh' : 'docsDense';+ if (!mod[key]) return; // no overlay, nothing to drift++ const english = propNames(mod.docs);+ const translated = propNames(+ await loadDocs(docPath, {[locale]: true}),+ );++ const dropped = [...english].filter(p => !translated.has(p));+ expect(+ dropped,+ `${name}.doc.mjs ${key} drops ${dropped.length} prop(s) from the ` ++ `--${locale} view: ${dropped.join(', ')}. A reader of the ` ++ `translated docs cannot discover a prop that is not there. An ` ++ `untranslated prop must fall back to its English entry, not vanish.`,+ ).toEqual([]);+ });+ }+ }+});++describe('the reported symptom', () => {+ it('astryx component Button --zh still lists isInterruptible and isIconOnly', async () => {+ const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');+ const zh = await loadDocs(docPath, {zh: true});+ const names = propNames(zh);+ expect(names.has('isInterruptible')).toBe(true);+ expect(names.has('isIconOnly')).toBe(true);+ });++ it('keeps the translated descriptions it does have', async () => {+ const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');+ const mod = await import(pathToFileURL(docPath).href);+ const zh = await loadDocs(docPath, {zh: true});++ const translated = mod.docsZh.props.find(p => p.name === 'variant');+ const merged = zh.props.find(p => p.name === 'variant');+ expect(merged.description).toBe(translated.description);+ });+});