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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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);});});