@astryxdesign/cli 0.5.0-canary.09d191c → 0.5.0-canary.1d94f85

package/api/theme/build/build.public-component-vars.test.mjs

@@ -0,0 +1,151 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * A component's *documented* theming vars must survive `astryx theme build`.
+ *
+ * `validatePrivateVars` rejects a theme that sets a `--_*` var, on the rule
+ * that private vars are reached through the derived-var pipeline rather than
+ * written directly. That makes "which prefix a themeable var carries" a
+ * build-time contract rather than a naming preference — and nothing checked
+ * the two against each other, so a component could document a var, and ship a
+ * changeset telling theme authors to set it, that the build then complains
+ * about (#5214).
+ *
+ * The theme this builds is generated FROM each component's own
+ * `theming.vars[]`, not from a snippet copied into this file. A hand-copied
+ * snippet only ever proves the builder accepts the string it was handed; a
+ * doc-driven one fails the moment a component documents a var a theme author
+ * cannot actually set. It covers every component with public vars, so the
+ * next one is covered without touching this file.
+ *
+ * Asserted on the receipt's `warnings` rather than on a rejection: a private
+ * var is reported (logged `✗`, collected into the receipt) and the build then
+ * emits its CSS and resolves anyway. Asserting a throw would pass for the
+ * wrong reason — it never throws, which is why a throwaway build read as a
+ * pass on the first version of #5214.
+ *
+ * `themeBuild` compiles via @astryxdesign/core's generator, so it needs a built
+ * core — the `node` project's globalSetup builds it once before workers fork.
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeAll,
+  beforeEach,
+  afterEach,
+  vi,
+} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {themeBuild} from './build.mjs';
+import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
+
+vi.setConfig({testTimeout: 60000});
+
+/** Every documented public var, as `{component, key, vars: [{name, value}]}`. */
+const documented = [];
+
+beforeAll(async () => {
+  // Core and the CLI ship as siblings, the same resolution build.mjs uses.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const coreSrc = path.resolve(here, '../../../../core/src');
+  const docs = [];
+  (function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== '__tests__')
+          scan(full);
+      } else if (entry.name.endsWith('.doc.mjs')) {
+        docs.push(full);
+      }
+    }
+  })(coreSrc);
+
+  for (const docPath of docs) {
+    let doc;
+    try {
+      doc = await loadComponentDoc(docPath);
+    } catch {
+      continue;
+    }
+    const theming = doc?.theming;
+    // The `defineTheme` key is the first target's class minus the namespace —
+    // the same derivation `theme targets` and the builder's own validation use.
+    const key = theming?.targets?.[0]?.className?.replace(/^astryx-/, '');
+    // Every var the docs PRESENT as settable — `private: true` is what hides
+    // one from `astryx component <Name>`, so anything without it is something
+    // a theme author is being told they may write. Deliberately not filtered
+    // by the `--_` prefix: a var carrying the private prefix while missing the
+    // private flag is advertised by the CLI and rejected by the builder, and
+    // that disagreement is the whole thing this test exists to catch.
+    const publicVars = (theming?.vars || []).filter(
+      v => typeof v?.name === 'string' && !v.private && !v.derived,
+    );
+    if (!key || publicVars.length === 0) continue;
+    documented.push({
+      component: path.basename(docPath, '.doc.mjs'),
+      key,
+      // A length or a color would each need a plausible value; `unset` is
+      // valid for any custom property and is not what is under test — that a
+      // theme may NAME the var at all is.
+      vars: publicVars.map(v => v.name),
+    });
+  }
+});
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-public-vars-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+async function buildTheme(name, components) {
+  const themeFile = path.join(tmpDir, `${name}.mjs`);
+  fs.writeFileSync(
+    themeFile,
+    `export default ${JSON.stringify({name, tokens: {}, components}, null, 2)};\n`,
+  );
+  return themeBuild(`${name}.mjs`, {}, {cwd: tmpDir});
+}
+
+const privateVarWarnings = result =>
+  (result?.data.warnings ?? []).filter(w => /private var/i.test(w));
+
+describe('documented component vars build cleanly', () => {
+  it('finds components with public theming vars to check', () => {
+    // A rename that broke the doc scan would otherwise silently empty this
+    // file out, the way a var-count bail once did in derivedVarRegistry.test.
+    expect(documented.length).toBeGreaterThan(0);
+  });
+
+  it('accepts every var the component docs tell a theme author to set', async () => {
+    const components = Object.fromEntries(
+      documented.map(({key, vars}) => [
+        key,
+        {base: Object.fromEntries(vars.map(name => [name, 'unset']))},
+      ]),
+    );
+
+    const result = await buildTheme('documentedvars', components);
+
+    expect(result).not.toBeNull();
+    expect(privateVarWarnings(result)).toEqual([]);
+  });
+
+  it('still reports a private var, so the rule this relies on is real', async () => {
+    // The negative control: if the builder stopped reporting `--_*`, the test
+    // above would pass for the wrong reason.
+    const result = await buildTheme('privatevar', {
+      spinner: {'size:xl': {'--_spinner-diameter': '40px'}},
+    });
+
+    expect(privateVarWarnings(result)).toHaveLength(1);
+  });
+});

package/assets/docs/icons.doc.mjs

@@ -102,13 +102,43 @@ export const brandTheme = defineTheme({
         },
       ],
     },
+    {
+      title: 'Component and Library Icons',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'A glyph that belongs to one component or library gets a namespaced key (`numberInput:stepperDown`, `richtext:bold`) instead of a new semantic name. It resolves through the same registry and a theme overrides it the same way, but the shared IconName list stays reserved for glyphs the whole system uses — so adding one does not make every downstream icon registry grow a key.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Owning and theming a namespaced icon',
+          code: `// The component renders it like any other name, keeping size and color.
+<Icon icon="numberInput:stepperDown" size="xsm" />
+
+// A theme maps it independently of the shared chevron.
+export const brandTheme = defineTheme({
+  name: 'brand',
+  icons: {
+    chevronDown: <ChevronDownIcon />,
+    'numberInput:stepperDown': <CaretDownFilledIcon />,
+  },
+});`,
+        },
+        {
+          type: 'prose',
+          text: 'Ship the fallback in `defaultIcons` under the same key so the glyph still renders with no theme, or pass one to `getExtendedIcon(key, fallback)` when the icon lives outside core.',
+        },
+      ],
+    },
     {
       title: 'Adding New Icons',
   category: 'foundations',
       content: [
         {
           type: 'prose',
-          text: 'To add a new semantic icon name to the design system:',
+          text: 'To add a new semantic icon name to the design system — only for a glyph the whole system shares; a component-owned one takes a namespaced key instead:',
         },
         {
           type: 'list',

package/assets/templates/blocks/components/Step/StepIndicator.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Step — Indicator',
   displayName: 'Step — Indicator',
   description:
-    'Everything the indicator prop accepts: the auto default, an always-number badge, a custom ReactNode, and none — each on its own completed Step so the prop is the only difference between them. Every variant occupies the same 16px box, so a step swapping its number for a check as it completes never shifts the label beside it. The last cell shows that a custom node can be live rather than static: a Spinner on a step that is in progress, shaded `inherit` so it picks up the step\u2019s own tint like any other glyph.',
+    'Everything the indicator prop accepts: the auto default, an always-number badge, a custom ReactNode, and none, each on its own completed Step so the prop is the only difference between them. Every variant occupies the same 16px box, so a step swapping its number for a check as it completes never shifts the label beside it. The last cell shows that a custom node can be live rather than static: a Spinner on a step that is in progress, shaded `inherit` so it picks up the step\'s own tint like any other glyph.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['Stepper', 'Step', 'Icon', 'Spinner', 'Text'],

package/assets/templates/blocks/components/Step/StepShowcase.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Step',
   displayName: 'Step',
   description:
-    'A single Step, with every part it can render: the indicator, the label with its optional marker and trailing endContent, and the description beneath. A Step never sets its own completed/current state — it declares its index and derives the rest from the parent Stepper, so one Step in one Stepper is a complete example.',
+    'A single Step, with every part it can render: the indicator, the label with its optional marker and trailing endContent, and the description beneath. A Step never sets its own completed/current state. It declares its index and derives the rest from the parent Stepper, so one Step in one Stepper is a complete example.',
   isReady: true,
   isShowcase: true,
   aspectRatio: 16 / 9,

package/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Stepper — Checkout Progress',
   displayName: 'Stepper — Checkout Progress',
   description:
-    'The default stepper: a horizontal track where every step owns an equal segment of the progress bar above its label. The default auto indicator resolves itself per step — a check once the step is done, a ring on the current step, a number for the ones still ahead. Click any step to jump.',
+    'The default stepper: a horizontal track where every step owns an equal segment of the progress bar above its label. The default auto indicator resolves itself per step: a check once the step is done, a ring on the current step, a number for the ones still ahead. Click any step to jump.',
   isReady: true,
   isShowcase: true,
   aspectRatio: 16 / 9,