Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): preserve anatomy in localized doc overlays (#5753)

Cindy Zhang2312b4cc3507
diff --git a/.changeset/localized-anatomy-inheritance.md b/.changeset/localized-anatomy-inheritance.md
new file mode 100644
index 0000000000..b3a7efbc7e
--- /dev/null
+++ b/.changeset/localized-anatomy-inheritance.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Preserve canonical anatomy in localized component docs
+
+Localized component docs now inherit canonical anatomy when they omit it, while explicit localized anatomy still takes precedence.
+
+@cixzhang
diff --git a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
index 39960513eb..754c679236 100644
--- a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
+++ b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
@@ -34,15 +34,30 @@ export const docs = {
],
anatomy: [
{
- name: 'Base-only anatomy',
+ name: 'Track',
required: true,
- description: 'This must not leak into translated output.',
+ description: 'The rail that shows the current on/off state.',
+ },
+ {
+ name: 'Thumb',
+ required: true,
+ description: 'The control that moves along the track.',
},
],
},
props: [],
};
+export const docsZh = {
+ name: 'AccessibilityOverlayFixture',
+ displayName: 'Accessibility Overlay Fixture',
+ category: 'Test',
+ usage: {
+ description: 'Translated full-doc description.',
+ },
+ props: [],
+};
+
export const docsDense = {
usage: {
description: 'Dense description.',
diff --git a/packages/cli/foundation/discovery/__fixtures__/component-anatomy-override.doc.mjs b/packages/cli/foundation/discovery/__fixtures__/component-anatomy-override.doc.mjs
new file mode 100644
index 0000000000..ade921d15b
--- /dev/null
+++ b/packages/cli/foundation/discovery/__fixtures__/component-anatomy-override.doc.mjs
@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export const docs = {
+ name: 'AnatomyOverrideFixture',
+ displayName: 'Anatomy Override Fixture',
+ category: 'Test',
+ usage: {
+ description: 'A multiline field for longer text.',
+ anatomy: [
+ {
+ name: 'Field',
+ required: true,
+ description: 'The multiline text entry area.',
+ },
+ {
+ name: 'Resize handle',
+ required: false,
+ description: 'Lets the user change the field height.',
+ },
+ ],
+ },
+ props: [],
+};
+
+export const docsZh = {
+ name: 'AnatomyOverrideFixture',
+ displayName: 'Anatomy Override Fixture',
+ category: 'Test',
+ usage: {
+ description: '用于输入较长文本的多行字段。',
+ anatomy: [
+ {
+ name: '文本区域',
+ required: true,
+ description: '用于输入多行文本的区域。',
+ },
+ {
+ name: '调整大小控件',
+ required: false,
+ description: '允许用户调整字段高度。',
+ },
+ ],
+ },
+ props: [],
+};
diff --git a/packages/cli/foundation/discovery/component-loader.mjs b/packages/cli/foundation/discovery/component-loader.mjs
index b3a38c7562..844a7620d7 100644
--- a/packages/cli/foundation/discovery/component-loader.mjs
+++ b/packages/cli/foundation/discovery/component-loader.mjs
@@ -194,7 +194,8 @@ function overlayComponentDoc(docs, translation) {
});
};
- /** Preserve structured accessibility data without changing established translated output.
+ /** Preserve canonical structured guidance added after legacy full-doc translations,
+ * without changing established translated prose behavior.
* @param {any} baseUsage
* @param {any} translatedUsage
*/
@@ -210,6 +211,9 @@ function overlayComponentDoc(docs, translation) {
baseUsage?.accessibilityThemeCoverage !== undefined
? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
: null),
+ ...(translatedUsage.anatomy === undefined && baseUsage?.anatomy !== undefined
+ ? {anatomy: baseUsage.anatomy}
+ : null),
};
};
diff --git a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
index 7f02de1456..611ce55322 100644
--- a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
+++ b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
@@ -90,7 +90,7 @@ describe('translated component docs never drop a prop', () => {
}
});
-describe('the reported symptom', () => {
+describe('full component-doc overlays', () => {
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});
@@ -127,6 +127,33 @@ describe('the reported symptom', () => {
'Decorative track — Not part of the contrast audit.',
);
expect(dense.usage.bestPractices).toBeUndefined();
- expect(dense.usage.anatomy).toBeUndefined();
+ expect(dense.usage.anatomy).toEqual(english.usage.anatomy);
+ });
+
+ it('inherits canonical anatomy when a full docsZh usage omits it', async () => {
+ const docPath = path.join(
+ import.meta.dirname,
+ '__fixtures__',
+ 'component-accessibility-overlay.doc.mjs',
+ );
+ const english = await loadDocs(docPath);
+ const zh = await loadDocs(docPath, {zh: true});
+
+ expect(zh.usage.description).toBe('Translated full-doc description.');
+ expect(zh.usage.anatomy).toEqual(english.usage.anatomy);
+ expect(zh.usage.bestPractices).toBeUndefined();
+ });
+
+ it('keeps explicit localized anatomy from a full docsZh usage', async () => {
+ const docPath = path.join(
+ import.meta.dirname,
+ '__fixtures__',
+ 'component-anatomy-override.doc.mjs',
+ );
+ const mod = await import(pathToFileURL(docPath).href);
+ const zh = await loadDocs(docPath, {zh: true});
+
+ expect(zh.usage.anatomy).toEqual(mod.docsZh.usage.anatomy);
+ expect(zh.usage.anatomy).not.toEqual(mod.docs.usage.anatomy);
});
});