Skip to content

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

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

/**
 * @file The canonical `.doc.{mjs,ts,js}` suffix is discovered identically
 * to the released `.template.{ts,mjs,js}` compatibility suffix.
 *
 * New authoring writes `.doc.mjs`, the canonical typed descriptor. Stable
 * 0.6.0 already accepted `.template.*`, so these tests
 * keep that family as a compatibility input and assert equivalent discovery +
 * scaffolding.
 */

import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import {template, findShowcase, findRelatedBlocks} from './template.mjs';

let tmpDir;
let originalCwd;

function makeConsumer() {
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-suffix-'));
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    JSON.stringify({name: 'consumer'}),
  );
  fs.writeFileSync(
    path.join(dir, 'astryx.config.mjs'),
    `export default { integrations: ['@acme/widgets'] };\n`,
  );
  return dir;
}

function installWidgets(consumerDir) {
  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
  fs.mkdirSync(path.join(pkgDir, 'templates'), {recursive: true});
  fs.writeFileSync(
    path.join(pkgDir, 'package.json'),
    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
  );
  fs.writeFileSync(
    path.join(pkgDir, 'astryx.integration.mjs'),
    `export default { templates: './templates' };\n`,
  );
  return pkgDir;
}

/**
 * Write a template-spec file (default-export a stamped `type: 'page' | 'block'`
 * object) plus its same-stem `.tsx` source under the templates root.
 * @param {string} pkgDir
 * @param {string} id
 * @param {{kind: 'page'|'block', suffix: string}} opts
 */
function writeTemplate(pkgDir, id, {kind, suffix}) {
  const docPath = path.join(pkgDir, 'templates', `${id}${suffix}`);
  fs.mkdirSync(path.dirname(docPath), {recursive: true});
  fs.writeFileSync(
    docPath,
    `export default {type: '${kind}', name: '${id} name', description: '${id} desc'};\n`,
  );
  fs.writeFileSync(
    path.join(pkgDir, 'templates', `${id}.tsx`),
    `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
  );
}

beforeEach(() => {
  originalCwd = process.cwd();
  tmpDir = makeConsumer();
  process.chdir(tmpDir);
});

afterEach(() => {
  process.chdir(originalCwd);
  fs.rmSync(tmpDir, {recursive: true, force: true});
});

describe('integration templates: canonical .doc.* plus released .template.* compatibility', () => {
  for (const suffix of ['.doc.mjs', '.doc.ts', '.template.mjs']) {
    it(`discovers + lists a page template authored as ${suffix}`, async () => {
      const pkgDir = installWidgets(tmpDir);
      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});

      const result = await template(undefined, {list: true, cwd: tmpDir});
      const entry = result.data.find(t => t.id === 'pricing');
      expect(entry).toBeTruthy();
      expect(entry.type).toBe('page');
      expect(entry.package).toBe('@acme/widgets');
      expect(entry.name).toBe('pricing name');
      expect(entry.description).toBe('pricing desc');
    });

    it(`scaffolds a page template authored as ${suffix}`, async () => {
      const pkgDir = installWidgets(tmpDir);
      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});

      const result = await template('pricing', {
        targetPath: './dest',
        cwd: tmpDir,
      });
      expect(result.type).toBe('template.copy');
      expect(result.data.fileName).toBe('page.tsx');
      expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
    });

    it(`scaffolds a nested block template authored as ${suffix}`, async () => {
      const pkgDir = installWidgets(tmpDir);
      writeTemplate(pkgDir, 'marketing/hero', {kind: 'block', suffix});

      const result = await template('marketing/hero', {
        targetPath: './dest',
        cwd: tmpDir,
      });
      expect(result.type).toBe('template.copy');
      expect(result.data.fileName).toBe('hero.tsx');
      expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
    });
  }

  it('treats canonical .doc.mjs and released .template.ts identically (same shape)', async () => {
    const pkgDir = installWidgets(tmpDir);
    writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
    writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});

    const result = await template(undefined, {list: true, cwd: tmpDir});
    const gauge = result.data.find(t => t.id === 'gauge');
    const chip = result.data.find(t => t.id === 'chip');

    // Both discovered, both blocks, both from the same package, both ready.
    for (const entry of [gauge, chip]) {
      expect(entry).toBeTruthy();
      expect(entry.type).toBe('block');
      expect(entry.package).toBe('@acme/widgets');
    }
    // Field-by-field parity apart from the (intentionally different) id/name.
    expect(gauge.type).toBe(chip.type);
    expect(gauge.package).toBe(chip.package);
  });
  it('lists both same-stem specs and reads the id as ambiguous', async () => {
    for (const [first, second] of [
      ['.doc.mjs', '.template.ts'],
      ['.doc.ts', '.doc.mjs'],
    ]) {
      const pkgDir = installWidgets(tmpDir);
      fs.rmSync(path.join(pkgDir, 'templates'), {recursive: true, force: true});
      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: first});
      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: second});

      const result = await template(undefined, {list: true, cwd: tmpDir});
      expect(
        result.data.filter(entry => entry.id === 'pricing'),
        `${first} + ${second}`,
      ).toHaveLength(2);
      await expect(
        template('pricing', {cwd: tmpDir}),
        `${first} + ${second}`,
      ).rejects.toMatchObject({code: 'ERR_AMBIGUOUS_TEMPLATE'});
    }
  });
});

describe('external showcase blocks: canonical .doc.* plus released .template.* compatibility', () => {
  /**
   * Create a consumer whose @test/ext package contributes two showcase blocks,
   * one authored with released `Foo.template.ts` and one with canonical `Bar.doc.mjs`.
   */
  function makeShowcaseFixture() {
    // Symlink the real core package (needed by findCoreDir during discovery).
    const realCoreDir = path.resolve(
      import.meta.dirname,
      '..',
      '..',
      '..',
      'core',
    );
    const coreDir = path.join(tmpDir, 'packages', 'core');
    fs.mkdirSync(path.dirname(coreDir), {recursive: true});
    fs.symlinkSync(realCoreDir, coreDir);

    const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
    const blocksDir = path.join(extDir, 'blocks', 'components');

    // Foo showcase — released .template.ts compatibility input.
    const fooDir = path.join(blocksDir, 'Foo');
    fs.mkdirSync(fooDir, {recursive: true});
    fs.writeFileSync(
      path.join(fooDir, 'FooShowcase.template.ts'),
      `export default {\n` +
        `  type: 'block',\n` +
        `  name: 'Foo — Showcase',\n` +
        `  description: 'Foo showcase.',\n` +
        `  isShowcase: true,\n` +
        `  aspectRatio: 16 / 9,\n` +
        `  componentsUsed: ['Foo'],\n` +
        `};\n`,
    );
    fs.writeFileSync(
      path.join(fooDir, 'FooShowcase.tsx'),
      "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
    );

    // Bar showcase — canonical .doc.mjs (historical named export).
    const barDir = path.join(blocksDir, 'Bar');
    fs.mkdirSync(barDir, {recursive: true});
    fs.writeFileSync(
      path.join(barDir, 'BarShowcase.doc.mjs'),
      `export const doc = {\n` +
        `  type: 'block',\n` +
        `  name: 'Bar — Showcase',\n` +
        `  description: 'Bar showcase.',\n` +
        `  isReady: true,\n` +
        `  isShowcase: true,\n` +
        `  aspectRatio: 4 / 3,\n` +
        `  componentsUsed: ['Bar', 'Chip'],\n` +
        `};\n`,
    );
    fs.writeFileSync(
      path.join(barDir, 'BarShowcase.tsx'),
      "'use client';\nexport default function BarShowcase() { return <div>Bar</div>; }",
    );

    fs.writeFileSync(
      path.join(extDir, 'package.json'),
      JSON.stringify({
        name: '@test/ext',
        astryx: {
          docs: './src',
          category: 'Common',
          blocks: './blocks/components',
        },
      }),
    );
    fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
  }

  it('findShowcase resolves a .template.ts external block by directory name', async () => {
    makeShowcaseFixture();
    const result = await findShowcase('Foo', tmpDir);
    expect(result).not.toBeNull();
    expect(result.name).toBe('Foo — Showcase');
    expect(result.filePath).toContain('FooShowcase.tsx');
  });

  it('findShowcase resolves a canonical .doc.mjs external block by componentsUsed', async () => {
    makeShowcaseFixture();
    const result = await findShowcase('Bar', tmpDir);
    expect(result).not.toBeNull();
    expect(result.name).toBe('Bar — Showcase');
  });

  it('findShowcase prefers the showcase that names the component in exampleFor', async () => {
    makeShowcaseFixture();
    // Bar's showcase also uses Chip; Chip's own showcase sits in a folder
    // that does not carry its name and says so only through exampleFor.
    const dir = path.join(
      tmpDir,
      'node_modules',
      '@test',
      'ext',
      'blocks',
      'components',
      'Gallery',
    );
    fs.mkdirSync(dir, {recursive: true});
    fs.writeFileSync(
      path.join(dir, 'ChipCard.doc.mjs'),
      "export default {type: 'block', name: 'Chip — Card', description: 'Chip showcase.', category: 'Test - Showcases', exampleFor: 'Chip', isShowcase: true, componentsUsed: ['Chip']};\n",
    );
    fs.writeFileSync(
      path.join(dir, 'ChipCard.tsx'),
      "'use client';\nexport default function ChipCard() { return <div>Chip</div>; }",
    );
    const result = await findShowcase('Chip', tmpDir);
    expect(result?.name).toBe('Chip — Card');
  });

  it('findRelatedBlocks finds both suffix families', async () => {
    makeShowcaseFixture();
    const foo = await findRelatedBlocks('Foo', tmpDir);
    expect(foo.map(b => b.dirName)).toContain('FooShowcase');
    const chip = await findRelatedBlocks('Chip', tmpDir);
    expect(chip.map(b => b.dirName)).toContain('BarShowcase');
  });
});