@astryxdesign/cli 0.5.2-canary.e4f8e4e → 0.5.2-canary.edc0cfc

package/api/theme/targets/targets.test.mjs

@@ -39,6 +39,21 @@ describe('themeTargets (api/theme/targets)', () => {
     ]);
   }, 60_000);
 
+  it.each(['table-header', 'table-body', 'table-footer'])(
+    '%s appears once under the Table owner',
+    async target => {
+      const {data} = await themeTargets('Table');
+      const matches = data.targets.filter(entry => entry.key === target);
+      expect(data.componentCount).toBe(1);
+      expect(matches).toHaveLength(1);
+      expect(matches[0]).toMatchObject({
+        key: target,
+        component: 'Table',
+      });
+    },
+    60_000,
+  );
+
   // Half the system's keys contain "button" (chat-send-button, toggle-button,
   // …). A component name has to mean the component, or `theme targets Button`
   // answers a different question than `component Button` and the two views

package/assets/templates/blocks/components/Table/TableRowStatusTable.doc.mjs

@@ -4,10 +4,10 @@
 export const doc = {
   type: 'block',
   exampleFor: 'useTableRowStatus',
-  name: 'useTableRowStatus - Status Dots',
-  displayName: 'useTableRowStatus - Status Dots',
+  name: 'useTableRowStatus - Status Icons',
+  displayName: 'useTableRowStatus - Status Icons',
   description:
-    'A job table using useTableRowStatus to render a colored status dot (or icon) per row (failed / running / queued). Rows with no status show no dot.',
+    'A job table using useTableRowStatus. Semantic outcomes use the themed success, warning, and error icons; a palette-only queued state keeps the neutral dot.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['Table'],

package/assets/templates/blocks/components/Table/TableRowStatusTable.tsx

@@ -34,13 +34,13 @@ const columns: TableColumn<Job>[] = [
 function jobStatus(job: Job): TableRowStatus | null {
   switch (job.state) {
     case 'failed':
-      return {color: 'error', icon: 'error', label: 'Failed'};
+      return {color: 'error', label: 'Failed'};
     case 'running':
-      return {color: 'warning', icon: 'warning', label: 'Running'};
+      return {color: 'warning', label: 'Running'};
     case 'queued':
       return {color: 'gray', label: 'Queued'};
-    default:
-      return null; // succeeded: no dot
+    case 'succeeded':
+      return {color: 'success', label: 'Succeeded'};
   }
 }
 

package/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.d.mts

@@ -33,7 +33,13 @@ export namespace docs {
     }
     let props: never[];
 }
-export namespace docsDense {
+export namespace docsZh {
+    let name_1: string;
+    export { name_1 as name };
+    let displayName_1: string;
+    export { displayName_1 as displayName };
+    let category_1: string;
+    export { category_1 as category };
     export namespace usage_1 {
         let description_1: string;
         export { description_1 as description };
@@ -42,3 +48,12 @@ export namespace docsDense {
     let props_1: never[];
     export { props_1 as props };
 }
+export namespace docsDense {
+    export namespace usage_2 {
+        let description_2: string;
+        export { description_2 as description };
+    }
+    export { usage_2 as usage };
+    let props_2: never[];
+    export { props_2 as props };
+}

package/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.',

package/foundation/discovery/__fixtures__/component-anatomy-override.doc.d.mts

@@ -0,0 +1,38 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export namespace docs {
+    let name: string;
+    let displayName: string;
+    let category: string;
+    namespace usage {
+        let description: string;
+        let anatomy: {
+            name: string;
+            required: boolean;
+            description: string;
+        }[];
+    }
+    let props: never[];
+}
+export namespace docsZh {
+    let name_1: string;
+    export { name_1 as name };
+    let displayName_1: string;
+    export { displayName_1 as displayName };
+    let category_1: string;
+    export { category_1 as category };
+    export namespace usage_1 {
+        let description_1: string;
+        export { description_1 as description };
+        let anatomy_1: {
+            name: string;
+            required: boolean;
+            description: string;
+        }[];
+        export { anatomy_1 as anatomy };
+    }
+    export { usage_1 as usage };
+    let props_1: never[];
+    export { props_1 as props };
+}

package/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: [],
+};

package/foundation/discovery/component-loader.mjs

@@ -51,7 +51,7 @@ export async function loadComponentDoc(
   /** @type {any} */
   const translation = mod[translationKey];
   if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
-    return translation;
+    return overlayComponentDoc(docs, translation);
   }
   return mergeTranslation(docs, translation);
 }
@@ -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),
     };
   };
 

package/foundation/discovery/component-loader.test.mjs

@@ -9,7 +9,8 @@
  */
 
 import {describe, it, expect} from 'vitest';
-import {mergeTranslation} from './component-loader.mjs';
+import * as path from 'node:path';
+import {loadComponentDoc, loadDocs, mergeTranslation} from './component-loader.mjs';
 
 /** Minimal HookDoc-shaped fixture with params + returns. */
 function hookDocs() {
@@ -105,3 +106,37 @@ describe('mergeTranslation — component prop descriptions (regression)', () =>
     expect(merged.props.find(p => p.name === 'disabled').description).toBe('Disabled state.');
   });
 });
+
+describe('loadComponentDoc — full localized doc overlays', () => {
+  it('inherits canonical anatomy when docsZh omits it and matches loadDocs', async () => {
+    const docPath = path.join(
+      import.meta.dirname,
+      '__fixtures__',
+      'component-accessibility-overlay.doc.mjs',
+    );
+
+    const direct = await loadComponentDoc(docPath, {zh: true});
+    const cli = await loadDocs(docPath, {zh: true});
+
+    expect(direct).toEqual(cli);
+    expect(direct.usage.description).toBe('Translated full-doc description.');
+    expect(direct.usage.anatomy).toEqual((await loadComponentDoc(docPath)).usage.anatomy);
+    expect(direct.usage.bestPractices).toBeUndefined();
+  });
+
+  it('keeps explicit localized anatomy and matches loadDocs', async () => {
+    const docPath = path.join(
+      import.meta.dirname,
+      '__fixtures__',
+      'component-anatomy-override.doc.mjs',
+    );
+
+    const direct = await loadComponentDoc(docPath, {zh: true});
+    const cli = await loadDocs(docPath, {zh: true});
+    const canonical = await loadComponentDoc(docPath);
+
+    expect(direct).toEqual(cli);
+    expect(direct.usage.anatomy).not.toEqual(canonical.usage.anatomy);
+    expect(direct.usage.anatomy[0].name).toBe('文本区域');
+  });
+});

package/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);
   });
 });

package/foundation/discovery/theming-targets.d.mts

@@ -3,16 +3,21 @@
 
 /**
  * Every theming target declared under a core `src` directory, sorted by key
- * then component. A key can appear more than once: a shared sub-element (the
- * radio indicator, say) is documented by every component that renders it.
+ * then component. When both a parent doc and one of its `subComponentOf`
+ * children declare the same class, the parent is the canonical discovery owner;
+ * the child keeps its direct docs but does not add a second listing row. Shared
+ * targets declared by unrelated components remain separate rows.
  *
  * Unreadable docs are skipped rather than fatal — a single malformed doc must
  * not take out theme validation or the listing.
  *
  * @param {string} coreSrc - absolute path to `<core>/src`
+ * @param {{includeDeprecated?: boolean}} [options] - preserve the CLI's full listing by default; ownership checks can request active targets only
  * @returns {Promise<ThemingTarget[]>}
  */
-export function collectThemingTargets(coreSrc: string): Promise<ThemingTarget[]>;
+export function collectThemingTargets(coreSrc: string, { includeDeprecated }?: {
+    includeDeprecated?: boolean;
+}): Promise<ThemingTarget[]>;
 /**
  * One public custom property a theme may set on a component's target.
  * @typedef {object} ThemingVar

package/foundation/discovery/theming-targets.mjs

@@ -45,19 +45,25 @@ function targetKey(className) {
 
 /**
  * Every theming target declared under a core `src` directory, sorted by key
- * then component. A key can appear more than once: a shared sub-element (the
- * radio indicator, say) is documented by every component that renders it.
+ * then component. When both a parent doc and one of its `subComponentOf`
+ * children declare the same class, the parent is the canonical discovery owner;
+ * the child keeps its direct docs but does not add a second listing row. Shared
+ * targets declared by unrelated components remain separate rows.
  *
  * Unreadable docs are skipped rather than fatal — a single malformed doc must
  * not take out theme validation or the listing.
  *
  * @param {string} coreSrc - absolute path to `<core>/src`
+ * @param {{includeDeprecated?: boolean}} [options] - preserve the CLI's full listing by default; ownership checks can request active targets only
  * @returns {Promise<ThemingTarget[]>}
  */
-export async function collectThemingTargets(coreSrc) {
+export async function collectThemingTargets(
+  coreSrc,
+  {includeDeprecated = true} = {},
+) {
   if (!coreSrc || !fs.existsSync(coreSrc)) return [];
 
-  /** @type {ThemingTarget[]} */
+  /** @type {Array<ThemingTarget & {parent: string|null}>} */
   const targets = [];
 
   /** @param {string} dir */
@@ -85,6 +91,7 @@ export async function collectThemingTargets(coreSrc) {
           : path.basename(path.dirname(full));
 
       for (const target of doc?.theming?.targets || []) {
+        if (!includeDeprecated && target?.deprecatedFor != null) continue;
         const className = target?.className;
         if (typeof className !== 'string') continue;
         const key = targetKey(className);
@@ -93,6 +100,8 @@ export async function collectThemingTargets(coreSrc) {
           key,
           className,
           component,
+          parent:
+            typeof doc?.subComponentOf === 'string' ? doc.subComponentOf : null,
           props: stringList(target.visualProps),
           states: stringList(target.states),
         });
@@ -102,10 +111,53 @@ export async function collectThemingTargets(coreSrc) {
 
   await scan(coreSrc);
 
-  targets.sort(
+  const canonical = canonicalizeParentTargets(targets);
+  canonical.sort(
     (a, b) => a.key.localeCompare(b.key) || a.component.localeCompare(b.component),
   );
-  return targets;
+  return canonical;
+}
+
+/**
+ * Collapse only an explicit parent/child duplicate. A child target is removed
+ * when its `subComponentOf` parent declares that same class exactly once; its
+ * props and states are merged into the parent's row so no capability is lost.
+ *
+ * Unrelated components sharing a class remain separate. An ambiguous parent
+ * declaration also remains untouched rather than guessing which row is
+ * canonical.
+ *
+ * @param {Array<ThemingTarget & {parent: string|null}>} targets
+ * @returns {ThemingTarget[]}
+ */
+function canonicalizeParentTargets(targets) {
+  /** @type {Map<string, Array<ThemingTarget & {parent: string|null}>>} */
+  const rootsByComponentAndClass = new Map();
+  for (const target of targets) {
+    if (target.parent != null) continue;
+    const identity = `${target.component}\0${target.className}`;
+    const roots = rootsByComponentAndClass.get(identity) ?? [];
+    roots.push(target);
+    rootsByComponentAndClass.set(identity, roots);
+  }
+
+  /** @type {Set<ThemingTarget & {parent: string|null}>} */
+  const duplicates = new Set();
+  for (const target of targets) {
+    if (target.parent == null) continue;
+    const roots =
+      rootsByComponentAndClass.get(`${target.parent}\0${target.className}`) ?? [];
+    if (roots.length !== 1) continue;
+
+    const canonical = roots[0];
+    canonical.props = [...new Set([...canonical.props, ...target.props])];
+    canonical.states = [...new Set([...canonical.states, ...target.states])];
+    duplicates.add(target);
+  }
+
+  return targets
+    .filter(target => !duplicates.has(target))
+    .map(({parent: _parent, ...target}) => target);
 }
 
 /**

package/foundation/discovery/theming-targets.test.mjs

@@ -41,6 +41,10 @@ const coreSrc = path.join(coreDir, 'src');
 
 /** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */
 const enumerated = collectThemingTargets(coreSrc);
+/** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */
+const activeEnumerated = collectThemingTargets(coreSrc, {
+  includeDeprecated: false,
+});
 
 describe('collectThemingTargets', () => {
   it('enumerates the whole surface, not a handful', async () => {
@@ -56,6 +60,20 @@ describe('collectThemingTargets', () => {
     }
   });
 
+  it('can limit ownership checks to active targets', async () => {
+    const all = await enumerated;
+    const active = await activeEnumerated;
+    expect(
+      all.some(t => t.component === 'CodeBlock' && t.key === 'codeblock'),
+    ).toBe(true);
+    expect(
+      active.some(t => t.component === 'CodeBlock' && t.key === 'codeblock'),
+    ).toBe(false);
+    expect(
+      active.some(t => t.component === 'CodeBlock' && t.key === 'code-block'),
+    ).toBe(true);
+  });
+
   it('carries the props and states a target reflects', async () => {
     const targets = await enumerated;
     expect(targets.find(t => t.key === 'switch-thumb')).toEqual({
@@ -67,6 +85,34 @@ describe('collectThemingTargets', () => {
     });
   });
 
+  it.each([
+    ['TableHeader', 'table-header'],
+    ['TableBody', 'table-body'],
+    ['TableFooter', 'table-footer'],
+  ])('keeps %s theming metadata available in its direct doc', async (name, key) => {
+    const doc = await loadComponentDoc(
+      path.join(coreSrc, 'Table', `${name}.doc.mjs`),
+    );
+    expect(doc.subComponentOf).toBe('Table');
+    expect(doc.theming.targets).toContainEqual({className: `astryx-${key}`});
+  });
+
+  it.each(['table-header', 'table-body', 'table-footer'])(
+    'enumerates %s once under its canonical Table owner',
+    async key => {
+      const matches = (await enumerated).filter(target => target.key === key);
+      expect(matches).toEqual([
+        {
+          key,
+          className: `astryx-${key}`,
+          component: 'Table',
+          props: [],
+          states: [],
+        },
+      ]);
+    },
+  );
+
   it('is sorted by key, so a diff of two runs is readable', async () => {
     const keys = (await enumerated).map(t => t.key);
     expect(keys).toEqual([...keys].sort((a, b) => a.localeCompare(b)));
@@ -78,9 +124,10 @@ describe('collectThemingTargets', () => {
   it('collapses to the override keys, merging the components that share one', async () => {
     const byKey = targetsByKey(await enumerated);
     expect(byKey['switch']).toEqual(['size', 'checked', 'disabled']);
-    // `radio` is documented by both Indicator and RadioList.
+    // `radio` is documented by two unrelated owners. Parent/child
+    // canonicalization must not collapse a shared target across families.
     const radio = (await enumerated).filter(t => t.key === 'radio');
-    expect(radio.length).toBeGreaterThan(1);
+    expect(radio.map(t => t.component)).toEqual(['Indicator', 'RadioList']);
     for (const t of radio) {
       for (const name of [...t.props, ...t.states]) {
         expect(byKey['radio']).toContain(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.5.2-canary.e4f8e4e",
+  "version": "0.5.2-canary.edc0cfc",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -87,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/core": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/lab": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/charts": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/core": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/lab": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.edc0cfc",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/core": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/lab": "0.5.2-canary.e4f8e4e",
-    "@astryxdesign/theme-neutral": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/charts": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/core": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/lab": "0.5.2-canary.edc0cfc",
+    "@astryxdesign/theme-neutral": "0.5.2-canary.edc0cfc",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {