@astryxdesign/cli 0.4.1 → 0.4.2-canary.10bcaa1

package/api/theme/build/build.test.mjs

@@ -254,6 +254,28 @@ describe('themeBuild() — component override validation', () => {
     expect(result?.data.warnings).toEqual([]);
   });
 
+  it('accepts the heading type rules a type scale generates', async () => {
+    // `typography.scale` makes defineTheme emit `heading: {'type:display-1' …}`
+    // (Heading renders a `type:` class alongside `level:`), so any theme with a
+    // type scale carried override keys the validator called unknown — including
+    // the shipped neutralTheme.
+    const themeFile = path.join(tmpDir, 'typescale.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'typescale',
+        tokens: {'--color-bg': '#0a0a0a'},
+        components: {
+          heading: {'type:display-1': {letterSpacing: '0.01em'}},
+        },
+      };\n`,
+    );
+
+    const result = await themeBuild('typescale.mjs', {}, {cwd: tmpDir});
+
+    expect(result?.data.warnings).toEqual([]);
+  });
+
   it('still warns on a key that is neither a visual prop nor a state', async () => {
     // Widening the known set to states must not turn the guard off.
     const themeFile = path.join(tmpDir, 'bogus.mjs');
@@ -273,3 +295,208 @@ describe('themeBuild() — component override validation', () => {
     ]);
   });
 });
+
+describe('themeBuild() — the shipped theme template', () => {
+  // `assets/theme.template.ts` is what `astryx theme template` puts in a
+  // consumer's project. It is the one theme file we hand out, so it has to
+  // compile as shipped — and cleanly apart from the font warnings it earns on
+  // purpose: a template that greets its first reader with warnings teaches them
+  // to ignore warnings. The claims its comments make are checked separately by
+  // scripts/check-theme-template.test.mjs.
+  it('compiles as shipped, warning only about the fonts it deliberately names', async () => {
+    const src = path.resolve(
+      import.meta.dirname,
+      '../../../assets/theme.template.ts',
+    );
+    fs.copyFileSync(src, path.join(tmpDir, 'theme.template.ts'));
+
+    const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});
+
+    // The template names Inter and Geist Mono to teach "SHIP THE FONTS YOU
+    // NAME", and loads neither — so the unloaded-font warning firing here is
+    // the lesson landing, not a defect. Any OTHER warning still fails.
+    const unexpected = (result?.data.warnings ?? []).filter(
+      w => !/^Font "(Inter|Geist Mono)" is named by this theme but not loaded/.test(w),
+    );
+    expect(unexpected).toEqual([]);
+    expect(result?.data.warnings).toHaveLength(2);
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
+    // The template teaches custom variants; the augmentation it promises the
+    // reader has to actually be generated.
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(
+      true,
+    );
+  });
+});
+
+describe('themeBuild() — extends', () => {
+  // These fixtures `import {defineTheme} from '@astryxdesign/core/theme'` the
+  // way a real theme file does, so they have to sit somewhere that specifier
+  // resolves — an OS temp dir has no node_modules above it.
+  let extDir;
+  beforeEach(() => {
+    extDir = fs.mkdtempSync(
+      path.join(path.resolve(import.meta.dirname, '../../..'), '.tmp-extends-'),
+    );
+  });
+  afterEach(() => {
+    fs.rmSync(extDir, {recursive: true, force: true});
+  });
+
+  /**
+   * Every `prop: value` a generated stylesheet actually applies. Header
+   * comments and scope wrappers are ignored — two themes never share those.
+   */
+  function declarations(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => /^[-a-z][^{}]*:.+;$/.test(l)),
+    );
+  }
+  /** Every component rule a stylesheet opens, e.g. `.astryx-switch {`. */
+  function selectors(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.endsWith('{') && l.startsWith('.')),
+    );
+  }
+
+  /** A base theme with geometry, elevation and a component override. */
+  const BASE_SOURCE = `export const brandTheme = {
+    name: 'ext-base',
+    tokens: {
+      '--radius-element': '6px',
+      '--shadow-low': '0 1px 3px rgb(0 0 0 / 0.1)',
+      '--color-border-emphasized': '#D4D4D4',
+    },
+    components: {
+      switch: {base: {backgroundColor: 'var(--color-border-emphasized)'}},
+    },
+  };\n`;
+
+  /**
+   * The child names its base with a plain relative specifier, exactly as a
+   * generated palette does. `theme build` writes `ext-base.js` next to
+   * `ext-base.mjs`, so `./ext-base` is ambiguous — and the artifact, which
+   * exports `extBaseTheme` rather than `brandTheme`, is the wrong answer.
+   */
+  const CHILD_SOURCE = `import {defineTheme} from '@astryxdesign/core/theme';
+  import {brandTheme} from './ext-base';
+  export const paletteTheme = defineTheme({
+    name: 'ext-child',
+    extends: brandTheme,
+    tokens: {'--color-accent': 'hsl(220 88% 72%)'},
+  });\n`;
+
+  it('emits every declaration its base emits (the child stylesheet is self-contained)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    // Build the base FIRST, as any real project does — that write is what
+    // used to poison the child's build.
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    const baseCss = fs.readFileSync(path.join(extDir, 'ext-base.css'), 'utf8');
+    const childCss = fs.readFileSync(
+      path.join(extDir, 'ext-child.css'),
+      'utf8',
+    );
+
+    const childDecls = declarations(childCss);
+    expect([...declarations(baseCss)].filter(d => !childDecls.has(d))).toEqual(
+      [],
+    );
+
+    const childSelectors = selectors(childCss);
+    expect([...selectors(baseCss)].filter(s => !childSelectors.has(s))).toEqual(
+      [],
+    );
+
+    // …and the child's own override still wins.
+    expect(childCss).toContain('--color-accent: hsl(220 88% 72%);');
+  });
+
+  it('resolves the base from its source, not from the generated sibling artifact', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    const result = await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    expect(result?.data.componentCount).toBe(1);
+    expect(result?.data.tokenCount).toBe(4);
+  });
+
+  it('inherits component overrides when the base IS a built theme module', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+
+    // Extending a package's pre-built theme module (e.g. the `./built`
+    // subpath the shipped themes expose) must not silently drop its
+    // component overrides.
+    fs.writeFileSync(
+      path.join(extDir, 'ext-built-child.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {extBaseTheme} from './ext-base.js';
+      export const builtChildTheme = defineTheme({
+        name: 'ext-built-child',
+        extends: extBaseTheme,
+      });\n`,
+    );
+
+    await themeBuild('ext-built-child.mjs', {}, {cwd: extDir});
+    const css = fs.readFileSync(
+      path.join(extDir, 'ext-built-child.css'),
+      'utf8',
+    );
+
+    expect(css).toContain('.astryx-switch {');
+    expect(css).toContain('--radius-element: 6px;');
+  });
+
+  it('resolves extends on a plain object theme file (no defineTheme call)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(
+      path.join(extDir, 'ext-plain.mjs'),
+      `import {brandTheme} from './ext-base.mjs';
+      export default {
+        name: 'ext-plain',
+        extends: brandTheme,
+        tokens: {'--color-accent': '#ff0000'},
+      };\n`,
+    );
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-plain.mjs', {}, {cwd: extDir});
+
+    const css = fs.readFileSync(path.join(extDir, 'ext-plain.css'), 'utf8');
+    expect(css).toContain('--radius-element: 6px;');
+    expect(css).toContain('.astryx-switch {');
+  });
+
+  it('fails loudly when the base import resolved to nothing', async () => {
+    fs.writeFileSync(
+      path.join(extDir, 'ext-broken.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {notAThing} from './ext-missing.mjs';
+      export const brokenTheme = defineTheme({
+        name: 'ext-broken',
+        extends: notAThing,
+        tokens: {'--color-accent': '#ff0000'},
+      });\n`,
+    );
+    fs.writeFileSync(
+      path.join(extDir, 'ext-missing.mjs'),
+      `export const somethingElse = 1;\n`,
+    );
+
+    await expect(
+      themeBuild('ext-broken.mjs', {}, {cwd: extDir}),
+    ).rejects.toThrow(/extends/);
+  });
+});

package/api/theme/build/font-warning.d.mts

@@ -0,0 +1,26 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Collect the font families a resolved theme names but does not load —
+ * every `--font-family-*` token plus every component-override `fontFamily`,
+ * minus generics, CSS-wide keywords, `var()` references, and known system
+ * families. Source order, first-seen casing, deduped case-insensitively.
+ *
+ * @param {{tokens?: Record<string, string>, components?: object}} resolvedTheme
+ * @returns {string[]}
+ */
+export function collectUnloadedFonts(resolvedTheme: {
+    tokens?: Record<string, string>;
+    components?: object;
+}): string[];
+/**
+ * Render the human fix printed after the install instructions: which fonts
+ * the theme names but does not load, the Google Fonts `<link>` recipe, and
+ * the self-hosted `@font-face` alternative.
+ *
+ * @param {string} themeName
+ * @param {string[]} families
+ * @returns {string}
+ */
+export function formatFontLoadingHelp(themeName: string, families: string[]): string;

package/api/theme/build/font-warning.mjs

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Font-loading warning helpers for `astryx theme build` (#5015).
+ *
+ * Nothing in the pipeline loads font files — defineTheme and the built CSS
+ * only set `font-family` — so a theme that names a webfont renders in the
+ * fallback typeface on every machine whose app never loads it, and no step
+ * says so. These helpers close that gap at build time.
+ *
+ * `collectUnloadedFonts` inspects a RESOLVED theme (raw typography configs
+ * are already collapsed into `--font-family-*` tokens by the time the build
+ * sees the theme, so tokens + component-override `fontFamily` values are the
+ * complete font surface on both load paths) and returns the families that
+ * are neither CSS generics nor known preinstalled system fonts. Unrecognized
+ * names are assumed to be webfonts on purpose: a missed warning hides the
+ * bug, a spurious one costs a glance.
+ *
+ * @input A resolved theme object ({tokens, components}) from build.mjs.
+ * @output Ordered, case-insensitively deduped family names, and the human
+ *   help snippet (<link> pair + @font-face) printed after the install
+ *   instructions.
+ * @position Sits beside build.mjs (api/theme/build/). Pure functions, no IO,
+ *   so the `--json` receipt and the human output share one source of truth.
+ */
+
+// font-family values that never need loading: CSS generic families, the ui-*
+// system keywords, and CSS-wide keywords that can appear in a token value.
+const GENERIC_KEYWORDS = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'math',
+  'emoji',
+  'fangsong',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]);
+
+// Families a clean machine already has: the members of core's own default
+// stacks (tokens.stylex.ts typographyDefaults) plus the classic web-safe
+// macOS/Windows set. Deliberately short — an unknown family warns, and for a
+// preinstalled rarity that is a one-line false alarm, not a broken theme.
+const SYSTEM_FAMILIES = new Set([
+  '-apple-system',
+  'blinkmacsystemfont',
+  'segoe ui',
+  'segoe ui emoji',
+  'segoe ui symbol',
+  'roboto',
+  'helvetica',
+  'helvetica neue',
+  'arial',
+  'arial black',
+  'sf mono',
+  'sf pro',
+  'sf pro text',
+  'sf pro display',
+  'monaco',
+  'consolas',
+  'menlo',
+  'courier',
+  'courier new',
+  'georgia',
+  'times',
+  'times new roman',
+  'verdana',
+  'tahoma',
+  'trebuchet ms',
+  'impact',
+  'palatino',
+  'cambria',
+  'calibri',
+  'lucida grande',
+  'lucida console',
+  'gill sans',
+  'brush script mt',
+  'snell roundhand',
+  'old english text mt',
+  // Linux staples — the shipped themes' fallback stacks name these on
+  // purpose (e.g. neutral's code stack ends in Liberation Mono).
+  'liberation mono',
+  'liberation sans',
+  'liberation serif',
+  'dejavu sans',
+  'dejavu sans mono',
+]);
+
+/**
+ * Split a CSS font-family value into clean family names. Complete `var()`
+ * calls are stripped first — neither the reference nor its fallback
+ * arguments are this theme's own family declarations (the referenced token
+ * is checked in its own right) — then names are unquoted and
+ * whitespace-collapsed, and any remaining function-shaped fragment is
+ * dropped. The unquoted branch of the tokenizer cannot start at whitespace
+ * or a quote, so a quoted name is always taken whole even mid-list (commas
+ * inside quotes stay inside the name).
+ *
+ * @param {string} value
+ * @returns {string[]}
+ */
+function splitFamilies(value) {
+  const families = [];
+  const withoutVars = value.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, '');
+  for (const segment of withoutVars.match(/"[^"]*"|'[^']*'|[^,"'\s][^,]*/g) ??
+    []) {
+    let name = segment.trim();
+    if (!name) continue;
+    // /s: a quoted name may span lines (template-literal theme sources).
+    const quoted = /^(["']).*\1$/s.test(name);
+    if (quoted) name = name.slice(1, -1);
+    name = name.trim().replace(/\s+/g, ' ');
+    if (!name || (!quoted && /[()]/.test(name))) continue;
+    families.push(name);
+  }
+  return families;
+}
+
+/**
+ * Collect the font families a resolved theme names but does not load —
+ * every `--font-family-*` token plus every component-override `fontFamily`,
+ * minus generics, CSS-wide keywords, `var()` references, and known system
+ * families. Source order, first-seen casing, deduped case-insensitively.
+ *
+ * @param {{tokens?: Record<string, string>, components?: object}} resolvedTheme
+ * @returns {string[]}
+ */
+export function collectUnloadedFonts(resolvedTheme) {
+  const seen = new Set();
+  /** @type {string[]} */
+  const unloaded = [];
+
+  /** @param {unknown} value */
+  const consider = value => {
+    if (typeof value !== 'string') return;
+    for (const family of splitFamilies(value)) {
+      const key = family.toLowerCase();
+      if (GENERIC_KEYWORDS.has(key) || SYSTEM_FAMILIES.has(key)) continue;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      unloaded.push(family);
+    }
+  };
+
+  for (const [token, value] of Object.entries(resolvedTheme?.tokens ?? {})) {
+    if (token.startsWith('--font-family-')) consider(value);
+  }
+
+  // Component overrides are plain CSS maps of unknown depth (style keys,
+  // nested at-rule blocks) — walk them and pick up every fontFamily.
+  /** @param {unknown} node */
+  const walk = node => {
+    if (!node || typeof node !== 'object') return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'fontFamily') consider(value);
+      else walk(value);
+    }
+  };
+  walk(resolvedTheme?.components);
+
+  return unloaded;
+}
+
+/**
+ * Render the human fix printed after the install instructions: which fonts
+ * the theme names but does not load, the Google Fonts `<link>` recipe, and
+ * the self-hosted `@font-face` alternative.
+ *
+ * @param {string} themeName
+ * @param {string[]} families
+ * @returns {string}
+ */
+export function formatFontLoadingHelp(themeName, families) {
+  const named = families.map(f => `"${f}"`).join(', ');
+  const cssHref =
+    'https://fonts.googleapis.com/css2?' +
+    families
+      .map(f => `family=${encodeURIComponent(f).replace(/%20/g, '+')}`)
+      .join('&') +
+    '&display=swap';
+  const first = families[0];
+  const slug = first.toLowerCase().replace(/ /g, '-');
+  return `
+⚠ Theme "${themeName}" names fonts it does not load: ${named}
+  The built CSS only sets font-family — load these in your app, or every
+  browser quietly falls back.
+
+  Google Fonts (add :wght@… axes as your theme's weights require):
+
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="${cssHref}" />
+
+  Self-hosted (repeat per family and weight):
+
+    @font-face {
+      font-family: ${JSON.stringify(first)};
+      src: url('/fonts/${slug}.woff2') format('woff2');
+      font-display: swap;
+    }
+
+  Recipe and fallback-stack guidance: astryx docs typography
+`;
+}