Skip to content

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

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

/**
 * @file Built themes carry component icon slots and resolve them as runtime.
 * @input Real themeBuild and themeBuildFamily calls on source themes whose
 *   `componentIcons` hold static values and slot functions: an imported map, a
 *   child with inline static slots and an imported slot function, a theme
 *   extending a built module, a theme extending a package theme, and a family.
 * @output Native ESM loads that resolve every slot for each state under the
 *   built and the runtime theme, read the static `componentIcons` view, and
 *   render CodeBlock's copy button.
 * @position Theme build parity for component icon slots. 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 {themeBuild, themeBuildFamily} from './build.mjs';

let tmpDir;
beforeEach(() => {
  // Under the CLI package, so core and React resolve both in the theme loader
  // and in the native artifact checks.
  tmpDir = fs.mkdtempSync(
    path.resolve(import.meta.dirname, '../../..', '.tmp-component-icons-'),
  );
});
afterEach(() => {
  fs.rmSync(tmpDir, {recursive: true, force: true});
});

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

const SLOT_FUNCTIONS = `export const copySlot = ({copied}) =>
  copied ? {icon: 'checkDouble', size: 'lg'} : {icon: 'clock'};
export const baseSlots = {
  'code-block-copy': copySlot,
  'parity-panel-dismiss': {icon: 'close', size: 'sm'},
  'parity-nav-leading': ({selected}) => (selected ? null : undefined),
  'parity-unset': undefined,
};
`;

/** A base with an imported slot map, and a child with inline slots. */
function writeLineage() {
  write('base/slots.mjs', SLOT_FUNCTIONS);
  write(
    'base/source.mjs',
    `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from './slots.mjs';
export const baseTheme = defineTheme({
  name: 'slots-base', tokens: {}, componentIcons: baseSlots,
});
export default baseTheme;
`,
  );
  write(
    'child/source.mjs',
    `import {defineTheme} from '@astryxdesign/core/theme';
import {baseTheme} from '../base/source.mjs';
import {copySlot} from '../base/slots.mjs';
export const childTheme = defineTheme({
  name: 'slots-child', extends: baseTheme, tokens: {},
  componentIcons: {
    'parity-panel-dismiss': null,
    'parity-tab-close': {size: 'xsm'},
    'parity-copy-again': copySlot,
    'parity-nav-leading': undefined,
  },
});
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,
 * how every slot resolves for each state, the static view, and the glyph in
 * CodeBlock's copy button.
 *
 * @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} from 'react';
import {renderToStaticMarkup} from 'react-dom/server';
import {CodeBlock} from '@astryxdesign/core/CodeBlock';
import {Theme} from '@astryxdesign/core/theme';
const {resolveComponentIcon} = await import(
  import.meta.resolve('@astryxdesign/core/Icon').replace(/index\\.js$/, 'globalIconRegistry.js')
);
const SLOTS = {
  'code-block-copy': [{copied: false}, {copied: true}],
  'parity-copy-again': [{copied: false}, {copied: true}],
  'parity-panel-dismiss': [undefined],
  'parity-tab-close': [undefined],
  'parity-nav-leading': [{selected: false}, {selected: true}],
};
const copyGlyph = theme => {
  const html = renderToStaticMarkup(
    createElement(Theme, {theme}, createElement(CodeBlock, {code: 'x'})),
  );
  return /astryx-code-block-copy-button[^>]*>(.*?)<\\/button>/s.exec(html)?.[1] ?? null;
};
const describe = theme => ({
  resolved: Object.fromEntries(
    Object.entries(SLOTS).flatMap(([slot, states]) =>
      states.map(state => [
        slot + '|' + JSON.stringify(state ?? null),
        resolveComponentIcon(slot, state, {icon: 'copy', size: 'sm'}, theme),
      ]),
    ),
  ),
  componentIcons: theme.componentIcons ?? null,
  componentIconKeys: Object.keys(theme.componentIcons ?? {}).sort(),
  staticViewHasFunction: Object.values(theme.componentIcons ?? {}).some(
    value => typeof value === 'function',
  ),
  copyGlyph: copyGlyph(theme),
});
const result = {};
${pairs
  .map(
    ({label, built, runtime}) => `{
  const built = ${load(built)};
  const runtime = ${load(runtime)};
  result[${JSON.stringify(label)}] = {built: describe(built), runtime: describe(runtime)};
}`,
  )
  .join('\n')}
process.stdout.write(JSON.stringify(result));`,
    ],
    {cwd: tmpDir, encoding: 'utf8', timeout: 60000},
  );
  return JSON.parse(output);
}

describe('built themes keep component icon slots', () => {
  it('resolve every slot and state as the runtime theme does', async () => {
    writeLineage();
    await buildAndCheck('base/source.mjs');
    await buildAndCheck('child/source.mjs');
    // A grandchild extends the BUILT child module and adds a static slot.
    write(
      'grandchild/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {slotsChildTheme} from '../child/slots-child.js';
export default defineTheme({
  name: 'slots-grandchild', extends: slotsChildTheme, tokens: {},
  componentIcons: {'parity-tab-close': 'menu'},
});
`,
    );
    await buildAndCheck('grandchild/source.mjs');

    const result = inspect([
      {
        label: 'base',
        built: './base/slots-base.js#slotsBaseTheme',
        runtime: './base/source.mjs#default',
      },
      {
        label: 'child',
        built: './child/slots-child.js#slotsChildTheme',
        runtime: './child/source.mjs#default',
      },
      {
        label: 'grandchild',
        built: './grandchild/slots-grandchild.js#slotsGrandchildTheme',
        runtime: './grandchild/source.mjs#default',
      },
    ]);

    for (const {built, runtime} of Object.values(result)) {
      expect(built).toEqual(runtime);
      expect(built.staticViewHasFunction).toBe(false);
    }

    const child = result.child.built;
    expect(child.resolved).toEqual({
      'code-block-copy|{"copied":false}': {icon: 'clock', size: 'sm'},
      'code-block-copy|{"copied":true}': {icon: 'checkDouble', size: 'lg'},
      'parity-copy-again|{"copied":false}': {icon: 'clock', size: 'sm'},
      'parity-copy-again|{"copied":true}': {icon: 'checkDouble', size: 'lg'},
      'parity-panel-dismiss|null': {icon: null, size: 'sm'},
      'parity-tab-close|null': {icon: 'copy', size: 'xsm'},
      // An undefined entry inherits the base's slot function.
      'parity-nav-leading|{"selected":false}': {icon: 'copy', size: 'sm'},
      'parity-nav-leading|{"selected":true}': {icon: null, size: 'sm'},
    });
    // The static view leaves out every slot function.
    expect(child.componentIcons).toEqual({
      'parity-panel-dismiss': null,
      'parity-tab-close': {size: 'xsm'},
    });
    expect(result.grandchild.built.resolved['parity-tab-close|null']).toEqual({
      icon: 'menu',
      size: 'sm',
    });
    expect(child.copyGlyph).toContain('data-size="sm"');
  });

  it('writes static slots as JSON with no import', async () => {
    write(
      'static.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
export default defineTheme({
  name: 'slots-static', tokens: {},
  componentIcons: {'code-block-copy': 'clock', 'parity-panel-dismiss': null},
});
`,
    );
    await buildAndCheck('static.mjs');

    const module = fs.readFileSync(
      path.join(tmpDir, 'slots-static.js'),
      'utf8',
    );
    expect(module).not.toMatch(/^import /m);
    expect(module).not.toContain('__componentIcons');
    const {staticSlots} = inspect([
      {
        label: 'staticSlots',
        built: './slots-static.js#slotsStaticTheme',
        runtime: './static.mjs#default',
      },
    ]);
    expect(staticSlots.built).toEqual(staticSlots.runtime);
    expect(staticSlots.built.componentIcons).toEqual({
      'code-block-copy': 'clock',
      'parity-panel-dismiss': null,
    });
  });

  it('keeps the slot functions of a package theme it extends', async () => {
    const pkg = 'node_modules/@fixture/slot-functions';
    write(
      `${pkg}/package.json`,
      JSON.stringify({
        name: '@fixture/slot-functions',
        type: 'module',
        exports: './index.mjs',
      }),
    );
    write(`${pkg}/slots.mjs`, SLOT_FUNCTIONS);
    write(
      `${pkg}/index.mjs`,
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from './slots.mjs';
export const packageTheme = defineTheme({
  name: 'slots-package', tokens: {}, componentIcons: baseSlots,
});
`,
    );
    write(
      'package-child.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {packageTheme} from '@fixture/slot-functions';
export default defineTheme({
  name: 'slots-package-child', extends: packageTheme, tokens: {},
  componentIcons: {'parity-tab-close': 'menu'},
});
`,
    );
    await buildAndCheck('package-child.mjs');

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

    expect(packageChild.built).toEqual(packageChild.runtime);
    expect(
      packageChild.built.resolved['code-block-copy|{"copied":true}'],
    ).toEqual({icon: 'checkDouble', size: 'lg'});
  });

  it('keeps slot functions in a family build', async () => {
    writeLineage();
    // A member that sets no slots of its own inherits the child's values.
    write(
      'inherit/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {childTheme} from '../child/source.mjs';
export default defineTheme({name: 'slots-inherit', extends: childTheme, tokens: {}});
`,
    );
    // A family member supplies its own slot functions through a named import
    // of its whole componentIcons map, so this child sets only static slots.
    write(
      'child/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseTheme} from '../base/source.mjs';
export const childTheme = defineTheme({
  name: 'slots-child', extends: baseTheme, tokens: {},
  componentIcons: {'parity-panel-dismiss': null, 'parity-tab-close': {size: 'xsm'}},
});
export default childTheme;
`,
    );
    // A member whose imported map leaves a slot undefined keeps the parent's.
    write(
      'imported/slots.mjs',
      `export const importedSlots = {'code-block-copy': undefined, 'parity-tab-close': 'menu'};\n`,
    );
    write(
      'imported/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {childTheme} from '../child/source.mjs';
import {importedSlots} from './slots.mjs';
export default defineTheme({
  name: 'slots-imported', extends: childTheme, tokens: {}, componentIcons: importedSlots,
});
`,
    );
    const receipt = await themeBuildFamily(
      [
        'base/source.mjs',
        'child/source.mjs',
        'inherit/source.mjs',
        'imported/source.mjs',
      ],
      {familyKey: 'slots-family'},
      {cwd: tmpDir},
    );
    expect(receipt?.type).toBe('theme.build');
    const familyModule = `./${receipt.data.outputs.js}`;

    const result = inspect([
      {
        label: 'base',
        built: `${familyModule}#slotsBaseTheme`,
        runtime: './base/source.mjs#default',
      },
      {
        label: 'child',
        built: `${familyModule}#slotsChildTheme`,
        runtime: './child/source.mjs#default',
      },
      {
        label: 'inherit',
        built: `${familyModule}#slotsInheritTheme`,
        runtime: './inherit/source.mjs#default',
      },
      {
        label: 'imported',
        built: `${familyModule}#slotsImportedTheme`,
        runtime: './imported/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.imported.built).toEqual(result.imported.runtime);
    // A runtime theme extending the family root reads what one extending the
    // source root reads: the root's undefined slot is not listed.
    write(
      'family-child.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {slotsBaseTheme} from '${familyModule}';
import source from './base/source.mjs';
export const fromBuilt = defineTheme({name: 'family-from-built', extends: slotsBaseTheme, tokens: {}});
export const fromSource = defineTheme({name: 'family-from-source', extends: source, tokens: {}});
`,
    );
    const {child} = inspect([
      {
        label: 'child',
        built: './family-child.mjs#fromBuilt',
        runtime: './family-child.mjs#fromSource',
      },
    ]);
    expect(child.built).toEqual(child.runtime);
    expect(child.built.componentIconKeys).not.toContain('parity-unset');
    expect(
      result.imported.built.resolved['code-block-copy|{"copied":true}'],
    ).toEqual({icon: 'checkDouble', size: 'lg'});
    expect(
      result.child.built.resolved['code-block-copy|{"copied":true}'],
    ).toEqual({icon: 'checkDouble', size: 'lg'});
  });
});

describe('built slot values follow defineTheme', () => {
  it('keeps an inherited slot under an undefined own slot, and reads static values through constants', async () => {
    writeLineage();
    write(
      'undefined-own/slots.mjs',
      `export const childSlots = {'code-block-copy': undefined, 'parity-tab-close': 'menu'};\n`,
    );
    write(
      'undefined-own/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseTheme} from '../base/source.mjs';
import {childSlots} from './slots.mjs';
export default defineTheme({
  name: 'slots-undefined-own', extends: baseTheme, tokens: {}, componentIcons: childSlots,
});
`,
    );
    write('constants/sizes.mjs', `export const COMPACT = 'xsm';\n`);
    write(
      'constants/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseTheme} from '../base/source.mjs';
import {copySlot} from '../base/slots.mjs';
import {COMPACT} from './sizes.mjs';
const SIZE = 'xsm';
const SIZES = {compact: SIZE, icons: {dismiss: 'close'}};
const DISMISS = {icon: SIZES.icons.dismiss, size: SIZE};
export default defineTheme({
  name: 'slots-constants', extends: baseTheme, tokens: {},
  componentIcons: {
    'parity-panel-dismiss': DISMISS,
    'parity-tab-close': {size: SIZES.compact},
    'parity-nav-leading': {size: COMPACT},
    'parity-copy-again': copySlot,
  },
});
`,
    );
    // Inside one object, a later undefined slot replaces a spread value, so the
    // theme keeps no value for it.
    write(
      'spread-undefined/source.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from '../base/slots.mjs';
export default defineTheme({
  name: 'slots-spread-undefined', tokens: {},
  componentIcons: {...baseSlots, 'code-block-copy': undefined},
});
`,
    );
    for (const file of [
      'undefined-own/source.mjs',
      'constants/source.mjs',
      'spread-undefined/source.mjs',
    ]) {
      await buildAndCheck(file);
    }
    // A runtime theme extends the built root and the source root alike.
    write(
      'spread-undefined/child.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {slotsSpreadUndefinedTheme} from './slots-spread-undefined.js';
import source from './source.mjs';
export const fromBuilt = defineTheme({name: 'from-built', extends: slotsSpreadUndefinedTheme, tokens: {}});
export const fromSource = defineTheme({name: 'from-source', extends: source, tokens: {}});
`,
    );

    const result = inspect([
      {
        label: 'undefinedOwn',
        built: './undefined-own/slots-undefined-own.js#slotsUndefinedOwnTheme',
        runtime: './undefined-own/source.mjs#default',
      },
      {
        label: 'constants',
        built: './constants/slots-constants.js#slotsConstantsTheme',
        runtime: './constants/source.mjs#default',
      },
      {
        label: 'spreadUndefined',
        built:
          './spread-undefined/slots-spread-undefined.js#slotsSpreadUndefinedTheme',
        runtime: './spread-undefined/source.mjs#default',
      },
      {
        label: 'extendsBuiltRoot',
        built: './spread-undefined/child.mjs#fromBuilt',
        runtime: './spread-undefined/child.mjs#fromSource',
      },
    ]);
    for (const {built, runtime} of Object.values(result)) {
      expect(built).toEqual(runtime);
    }
    expect(
      result.undefinedOwn.built.resolved['code-block-copy|{"copied":false}'],
    ).toEqual({icon: 'clock', size: 'sm'});
    expect(result.constants.built.componentIcons).toMatchObject({
      'parity-panel-dismiss': {icon: 'close', size: 'xsm'},
      'parity-tab-close': {size: 'xsm'},
      'parity-nav-leading': {size: 'xsm'},
    });
    expect(
      Object.keys(result.extendsBuiltRoot.built.componentIcons ?? {}),
    ).toEqual(
      Object.keys(result.extendsBuiltRoot.runtime.componentIcons ?? {}),
    );
    expect(
      result.spreadUndefined.built.resolved['code-block-copy|{"copied":true}'],
    ).toEqual({icon: 'copy', size: 'sm'});
  });
});

describe('a built theme written with --out', () => {
  it('keeps the slot import as the source spells it, and loads where a module answers to it', async () => {
    write('src/slots.mjs', SLOT_FUNCTIONS);
    write(
      'src/theme.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from './slots.mjs';
export default defineTheme({name: 'slots-out', tokens: {}, componentIcons: baseSlots});
`,
    );
    const built = await themeBuild(
      'src/theme.mjs',
      {out: 'dist/theme.css'},
      {cwd: tmpDir},
    );
    expect(built?.type).toBe('theme.build');
    const module = fs.readFileSync(
      path.join(tmpDir, 'dist/slots-out.js'),
      'utf8',
    );
    expect(module).toContain(`import { baseSlots } from './slots.mjs';`);

    // The output directory supplies the module the specifier names.
    write('dist/slots.mjs', SLOT_FUNCTIONS);
    const {out} = inspect([
      {
        label: 'out',
        built: './dist/slots-out.js#slotsOutTheme',
        runtime: './src/theme.mjs#default',
      },
    ]);
    expect(out.built).toEqual(out.runtime);
    expect(out.built.resolved['code-block-copy|{"copied":true}']).toEqual({
      icon: 'checkDouble',
      size: 'lg',
    });
  });
});

describe('the static view never captures a slot binding', () => {
  it.each(['slot', 'Object'])(
    'loads a built theme whose slot map is imported as `%s`',
    async binding => {
      write('slots.mjs', SLOT_FUNCTIONS);
      write(
        'bound.mjs',
        `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots as ${binding}} from './slots.mjs';
export default defineTheme({name: 'bound-slots', tokens: {}, componentIcons: ${binding}});
`,
      );
      await buildAndCheck('bound.mjs');

      const {bound} = inspect([
        {
          label: 'bound',
          built: './bound-slots.js#boundSlotsTheme',
          runtime: './bound.mjs#default',
        },
      ]);
      expect(bound.built).toEqual(bound.runtime);
      expect(bound.built.componentIcons).toEqual({
        'parity-panel-dismiss': {icon: 'close', size: 'sm'},
      });
    },
  );
});

describe('a slot function the build cannot carry fails the build', () => {
  it('names a value that is neither static nor imported', async () => {
    write('slots.mjs', SLOT_FUNCTIONS);
    write(
      'computed.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from './slots.mjs';
const big = Math.random() > 2;
export default defineTheme({name: 'computed-slots', tokens: {},
  componentIcons: {...baseSlots, 'parity-tab-close': {size: big ? 'lg' : 'sm'}}});
`,
    );

    await expect(
      themeBuild('computed.mjs', {}, {cwd: tmpDir}),
    ).rejects.toMatchObject({
      code: 'ERR_THEME_INVALID',
      message: expect.stringContaining(
        'The value for "parity-tab-close" is neither a static value nor an imported binding.',
      ),
    });
  });

  it.each([
    [
      'an inline slot function',
      `componentIcons: {'code-block-copy': ({copied}) => ({icon: copied ? 'check' : 'copy'})}`,
    ],
    [
      'a slot function beside a spread map',
      `componentIcons: {...baseSlots, 'code-block-copy': () => null}`,
    ],
  ])('rejects %s before writing', async (_label, field) => {
    write('slots.mjs', SLOT_FUNCTIONS);
    write(
      'inline.mjs',
      `import {defineTheme} from '@astryxdesign/core/theme';
import {baseSlots} from './slots.mjs';
export default defineTheme({name: 'inline-slots', tokens: {}, ${field}});
`,
    );

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