Skip to content

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.md
new file mode 100644
index 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.
+
+@AKnassa
diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjs
index 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 docs
return 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.md
diff --git a/packages/cli/src/lib/componentDocOverlay.test.mjs b/packages/cli/src/lib/componentDocOverlay.test.mjs
new file mode 100644
index 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);
+ });
+});