Skip to content

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

TypeScript
16.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Built themes carry function icon entries and resolve them as runtime.
 * @input Real themeBuild and themeBuildFamily calls on source themes whose icon
 *   registries hold functions of `{size, variant}` and that list icon variants:
 *   a child under a replaced list, a theme extending a built module, a theme
 *   extending a package theme, and a family.
 * @output Native ESM loads that render `<Icon>` for every request a theme's
 *   entries can receive under the built and the runtime theme, read the public
 *   icon views, and a TypeScript program that extends a built theme.
 * @position `architecture:theme-compilation` INV15 and `spec:AST-087` FR3,
 *   FR18, and FR19 for theme build. The node project's global setup supplies
 *   the compiled core package.
 */

import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import ts from 'typescript';
import {themeBuild, themeBuildFamily} from './build.mjs';
import {
  makeLinkedFixture,
  removeLinkedFixture,
} from '../../../test-utils/linked-fixture.mjs';

const SIZES = ['xsm', 'sm', 'md', 'lg'];

let tmpDir;
beforeEach(() => {
  // Core, React and TypeScript resolve both in the theme loader and in the
  // native artifact checks.
  tmpDir = makeLinkedFixture('astryx-icon-functions-', [
    '@astryxdesign',
    'react',
    'react-dom',
    'typescript',
  ]);
});
afterEach(() => {
  removeLinkedFixture(tmpDir);
});

/** @param {string} file @param {string} source */
function write(file, source) {
  fs.mkdirSync(path.dirname(path.join(tmpDir, file)), {recursive: true});
  fs.writeFileSync(path.join(tmpDir, file), source);
}

/** A registry module whose function entries label what they were asked for. */
function writeRegistry(file, exportName, entries) {
  write(
    file,
    `import {createElement} from 'react';
const draw = label => ({size, variant}) =>
  createElement('svg', {'data-icon': label + ':' + size + ':' + (variant ?? 'normal')});
export const ${exportName} = {
${Object.entries(entries)
  .map(([key, label]) =>
    label.startsWith('node:')
      ? `  ${JSON.stringify(key)}: createElement('svg', {'data-icon': ${JSON.stringify(label.slice(5))}}),`
      : `  ${JSON.stringify(key)}: draw(${JSON.stringify(label)}),`,
  )
  .join('\n')}
};
`,
  );
}

/** The base, its child under a replaced list, and their registries. */
function writeLineage() {
  writeRegistry('base/icons.mjs', 'baseIcons', {
    info: 'base-info',
    close: 'base-close',
    check: 'node:base-check',
    'parity:mark': 'base-mark',
  });
  write(
    'base/source.mjs',
    `import {defineTheme} from '@astryxdesign/core/theme';
import {baseIcons} from './icons.mjs';
export const baseTheme = defineTheme({
  name: 'parity-base', tokens: {}, iconVariants: ['outline', 'filled'], icons: baseIcons,
});
export default baseTheme;
`,
  );
  writeRegistry('child/icons.mjs', 'childIcons', {
    close: 'child-close',
    menu: 'child-menu',
  });
  write(
    'child/source.mjs',
    `import {defineTheme} from '@astryxdesign/core/theme';
import {baseTheme} from '../base/source.mjs';
import {childIcons} from './icons.mjs';
export const childTheme = defineTheme({
  name: 'parity-child', extends: baseTheme, tokens: {},
  iconVariants: ['filled', 'bold'], icons: childIcons,
});
export default childTheme;
`,
  );
}

/** @param {string} file */
async function buildAndCheck(file) {
  const built = await themeBuild(file, {}, {cwd: tmpDir});
  expect(built?.type).toBe('theme.build');
  const checked = await themeBuild(file, {check: true}, {cwd: tmpDir});
  expect(checked?.data.upToDate).toBe(true);
  return built;
}

/**
 * Load built and runtime themes with native Node and report, for each pair,
 * what `<Icon>` renders for every request and what the public reads return.
 * The requests are every key a theme draws × the four sizes × no variant and
 * each name any theme here lists, so unlisted names are covered too.
 *
 * @param {Array<{label: string, built: string, runtime: string}>} pairs -
 *   Module specifiers with `#export` suffixes, relative to the fixture root.
 */
function inspect(pairs) {
  const load = specifier => {
    const [file, name] = specifier.split('#');
    return `(await import(${JSON.stringify(file)}))[${JSON.stringify(name)}]`;
  };
  const output = execFileSync(
    process.execPath,
    [
      '--input-type=module',
      '--eval',
      `import {createElement, isValidElement} from 'react';
import {renderToStaticMarkup} from 'react-dom/server';
import {Icon, getIcon, getIconRegistry} from '@astryxdesign/core/Icon';
import {Theme} from '@astryxdesign/core/theme';
const SIZES = ${JSON.stringify(SIZES)};
const VARIANTS = [undefined, 'outline', 'filled', 'bold'];
const label = node => {
  if (node == null) return null;
  if (!isValidElement(node)) return 'not-a-node:' + typeof node;
  return node.props['data-icon'];
};
const rendered = (theme, icon, size, variant) => {
  const html = renderToStaticMarkup(
    createElement(Theme, {theme}, createElement(Icon, {icon, size, variant})),
  );
  return /data-icon="([^"]+)"/.exec(html)?.[1] ?? null;
};
const describe = theme => {
  const keys = Object.keys(theme.icons ?? {}).sort();
  const requests = {};
  for (const key of keys) {
    for (const size of SIZES) {
      for (const variant of VARIANTS) {
        requests[key + '|' + size + '|' + (variant ?? '-')] = rendered(theme, key, size, variant);
      }
    }
  }
  return {
    keys,
    requests,
    icons: Object.fromEntries(keys.map(key => [key, label(theme.icons[key])])),
    getIcon: Object.fromEntries(keys.map(key => [key, label(getIcon(key, theme))])),
    registry: Object.fromEntries(
      Object.entries(getIconRegistry(theme))
        .filter(([key]) => keys.includes(key))
        .map(([key, node]) => [key, label(node)]),
    ),
    iconVariants: theme.iconVariants ?? null,
  };
};
const result = {};
${pairs
  .map(
    ({label, built, runtime}) => `{
  const built = ${load(built)};
  const runtime = ${load(runtime)};
  const mod = await import(${JSON.stringify(built.split('#')[0])});
  const reexports = Object.entries(mod).filter(([name]) => name !== ${JSON.stringify(built.split('#')[1])});
  result[${JSON.stringify(label)}] = {
    built: describe(built),
    runtime: describe(runtime),
    reexportIsNodeView: reexports.length === 0 ? null : reexports.every(([, value]) => value === built.icons),
  };
}`,
  )
  .join('\n')}
process.stdout.write(JSON.stringify(result));`,
    ],
    {cwd: tmpDir, encoding: 'utf8', timeout: 60000},
  );
  return JSON.parse(output);
}

describe('built themes keep function icon entries', () => {
  it('resolve every request as the runtime theme does, including an inherited entry under a replaced list', async () => {
    writeLineage();
    await buildAndCheck('base/source.mjs');
    await buildAndCheck('child/source.mjs');
    // A grandchild extends the BUILT child module.
    write(
      'grandchild/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {parityChildTheme} from '../child/parity-child.js';
export default defineTheme({name: 'parity-grandchild', extends: parityChildTheme, tokens: {}});
`,
    );
    await buildAndCheck('grandchild/source.mjs');

    const result = inspect([
      {
        label: 'base',
        built: './base/parity-base.js#parityBaseTheme',
        runtime: './base/source.mjs#default',
      },
      {
        label: 'child',
        built: './child/parity-child.js#parityChildTheme',
        runtime: './child/source.mjs#default',
      },
      {
        label: 'grandchild',
        built: './grandchild/parity-grandchild.js#parityGrandchildTheme',
        runtime: './grandchild/source.mjs#default',
      },
    ]);

    for (const {built, runtime, reexportIsNodeView} of Object.values(result)) {
      // INV15: built resolution and public views match runtime.
      expect(built).toEqual(runtime);
      expect(reexportIsNodeView).not.toBe(false);
    }

    const child = result.child.built;
    expect(child.keys).toEqual([
      'check',
      'close',
      'info',
      'menu',
      'parity:mark',
    ]);
    for (const size of SIZES) {
      // The child's own entry receives the names the child lists.
      expect(child.requests[`close|${size}|bold`]).toBe(
        `child-close:${size}:bold`,
      );
      expect(child.requests[`close|${size}|filled`]).toBe(
        `child-close:${size}:filled`,
      );
      expect(child.requests[`close|${size}|outline`]).toBe(
        `child-close:${size}:normal`,
      );
      // The inherited entry keeps its defining theme's list: 'outline' is no
      // longer listed by the child, and the base never listed 'bold'.
      expect(child.requests[`info|${size}|filled`]).toBe(
        `base-info:${size}:filled`,
      );
      expect(child.requests[`info|${size}|outline`]).toBe(
        `base-info:${size}:normal`,
      );
      expect(child.requests[`info|${size}|bold`]).toBe(
        `base-info:${size}:normal`,
      );
      expect(child.requests[`info|${size}|-`]).toBe(`base-info:${size}:normal`);
      // A node entry renders the same node for every request.
      expect(child.requests[`check|${size}|filled`]).toBe('base-check');
    }
    expect(result.grandchild.built.requests).toEqual(child.requests);

    // FR18: public reads are React nodes, each function read at md.
    expect(child.icons).toEqual({
      check: 'base-check',
      close: 'child-close:md:normal',
      info: 'base-info:md:normal',
      menu: 'child-menu:md:normal',
      'parity:mark': 'base-mark:md:normal',
    });
    expect(child.getIcon).toEqual(child.icons);
    expect(child.registry).toEqual({
      check: 'base-check',
      close: 'child-close:md:normal',
      info: 'base-info:md:normal',
      menu: 'child-menu:md:normal',
    });
    expect(result.base.reexportIsNodeView).toBe(true);
    expect(result.child.reexportIsNodeView).toBe(true);
  });

  it('keeps the function entries of a package theme it extends', async () => {
    const pkg = 'node_modules/@fixture/function-icons';
    write(
      `${pkg}/package.json`,
      JSON.stringify({
        name: '@fixture/function-icons',
        type: 'module',
        exports: './index.mjs',
      }),
    );
    writeRegistry(`${pkg}/icons.mjs`, 'packageIcons', {info: 'package-info'});
    write(
      `${pkg}/index.mjs`,
      `import {defineTheme} from '@astryxdesign/core/theme';
import {packageIcons} from './icons.mjs';
export const packageTheme = defineTheme({
  name: 'parity-package', tokens: {}, iconVariants: ['filled'], icons: packageIcons,
});
`,
    );
    write(
      'package-child.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {packageTheme} from '@fixture/function-icons';
export default defineTheme({name: 'parity-package-child', extends: packageTheme, tokens: {}});
`,
    );
    await buildAndCheck('package-child.mjs');

    const {packageChild} = inspect([
      {
        label: 'packageChild',
        built: './parity-package-child.js#parityPackageChildTheme',
        runtime: './package-child.mjs#default',
      },
    ]);

    expect(packageChild.built).toEqual(packageChild.runtime);
    for (const size of SIZES) {
      expect(packageChild.built.requests[`info|${size}|filled`]).toBe(
        `package-info:${size}:filled`,
      );
    }
    expect(packageChild.built.icons).toEqual({info: 'package-info:md:normal'});
  });

  it('keeps function entries in a family build', async () => {
    writeLineage();
    // A member that sets no icons of its own inherits the child's entries.
    write(
      'inherit/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {childTheme} from '../child/source.mjs';
export default defineTheme({name: 'parity-inherit', extends: childTheme, tokens: {}});
`,
    );
    const receipt = await themeBuildFamily(
      ['base/source.mjs', 'child/source.mjs', 'inherit/source.mjs'],
      {familyKey: 'parity-family'},
      {cwd: tmpDir},
    );
    expect(receipt?.type).toBe('theme.build');
    const familyModule = `./${receipt.data.outputs.js}`;

    const result = inspect([
      {
        label: 'base',
        built: `${familyModule}#parityBaseTheme`,
        runtime: './base/source.mjs#default',
      },
      {
        label: 'child',
        built: `${familyModule}#parityChildTheme`,
        runtime: './child/source.mjs#default',
      },
      {
        label: 'inherit',
        built: `${familyModule}#parityInheritTheme`,
        runtime: './inherit/source.mjs#default',
      },
    ]);

    expect(result.base.built).toEqual(result.base.runtime);
    expect(result.child.built).toEqual(result.child.runtime);
    expect(result.inherit.built).toEqual(result.inherit.runtime);
    expect(result.inherit.built.requests).toEqual(result.child.built.requests);
    expect(result.child.built.requests['info|sm|filled']).toBe(
      'base-info:sm:filled',
    );
    expect(result.child.built.requests['info|sm|outline']).toBe(
      'base-info:sm:normal',
    );
  });
});

describe('the node view never captures a registry binding', () => {
  it.each(['entries', 'nodes', 'name', 'entry', 'Object'])(
    'loads a built theme whose registry is imported as `%s`',
    async binding => {
      writeRegistry('icons.mjs', 'registry', {info: 'bound-info'});
      write(
        'bound.mjs',
        `import {defineTheme} from '@astryxdesign/core/theme';
import {registry as ${binding}} from './icons.mjs';
export default defineTheme({
  name: 'bound', tokens: {}, iconVariants: ['filled'], icons: ${binding},
});
`,
      );
      await buildAndCheck('bound.mjs');

      const {bound} = inspect([
        {
          label: 'bound',
          built: './bound.js#boundTheme',
          runtime: './bound.mjs#default',
        },
      ]);
      expect(bound.built).toEqual(bound.runtime);
      expect(bound.built.icons).toEqual({info: 'bound-info:md:normal'});
      expect(bound.built.requests['info|lg|filled']).toBe(
        'bound-info:lg:filled',
      );
      expect(bound.reexportIsNodeView).toBe(true);
    },
  );
});

describe('a built theme types its icon variants', () => {
  it('lets a theme extending the built module type `variant` by its list', async () => {
    writeLineage();
    await buildAndCheck('base/source.mjs');

    const variants = fs.readFileSync(
      path.join(tmpDir, 'base/parity-base.variants.d.ts'),
      'utf8',
    );
    expect(variants).toContain("declare module '@astryxdesign/core/Icon'");
    expect(variants).toContain("'outline': true;");
    expect(variants).toContain("'filled': true;");

    write(
      'consumer.ts',
      `import {defineTheme} from '@astryxdesign/core/theme';
import type {IconVariant} from '@astryxdesign/core/Icon';
import {parityBaseTheme} from './base/parity-base.js';

type Equal<A, B> =
  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;

defineTheme({
  name: 'consumer',
  extends: parityBaseTheme,
  icons: {
    info: ({variant}) => {
      const exact: Equal<typeof variant, 'outline' | 'filled' | undefined> = true;
      return exact ? null : null;
    },
    // @ts-expect-error -- 'bold' is not a name the built theme lists.
    close: ({variant}) => (variant === 'bold' ? null : null),
  },
});

// The built theme's augmentation adds its names to IconVariant.
export const listed: IconVariant = 'filled';
// @ts-expect-error -- no theme here lists 'bold'.
export const unlisted: IconVariant = 'bold';
`,
    );
    const program = ts.createProgram([path.join(tmpDir, 'consumer.ts')], {
      strict: true,
      noEmit: true,
      skipLibCheck: true,
      target: ts.ScriptTarget.ES2022,
      module: ts.ModuleKind.ESNext,
      moduleResolution: ts.ModuleResolutionKind.Bundler,
      types: [],
    });
    const diagnostics = ts
      .getPreEmitDiagnostics(program)
      .filter(diagnostic => diagnostic.file?.fileName.endsWith('consumer.ts'))
      .map(diagnostic =>
        ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
      );
    expect(diagnostics).toEqual([]);
  });
});

describe('a function the build cannot carry fails the build', () => {
  it.each([
    [
      'an inline function entry',
      `icons: {info: ({size}) => createElement('svg', {'data-size': size})}`,
    ],
    [
      'a function beside a spread registry',
      `icons: {...baseIcons, info: () => null}`,
    ],
  ])('rejects %s before writing', async (_label, iconsField) => {
    writeRegistry('icons.mjs', 'baseIcons', {close: 'base-close'});
    write(
      'inline.mjs',
      `import {createElement} from 'react';
import {defineTheme} from '@astryxdesign/core/theme';
import {baseIcons} from './icons.mjs';
export default defineTheme({name: 'inline-functions', tokens: {}, ${iconsField}});
`,
    );

    await expect(
      themeBuild('inline.mjs', {}, {cwd: tmpDir}),
    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
    expect(fs.readdirSync(tmpDir).sort()).toEqual(['icons.mjs', 'inline.mjs']);
  });
});