An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Every surface knows an integration component, or a family member, by
* the name its doc documents. Fixtures live under a repo-local temp dir: Vite
* refuses to import a module from outside the project root.
*/
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {spawnSync} from 'node:child_process';
import {component} from './component.mjs';
import {search} from '../search/search.mjs';
import {validateIntegration} from '../integration/validate-integration.mjs';
import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';
import {swizzleCopy} from '../swizzle/copy/copy.mjs';
import {gapReport} from '../gap-report/gap-report.mjs';
import {Project} from '../../foundation/config/project.mjs';
import {collectDocInputs} from '../../foundation/doc-compiler/inputs.mjs';
import {COMPONENT_REPLACES_CLI} from '../../foundation/integrations/cli-requirement.mjs';
import {scopeIntegrationMember} from './_adapter.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';
const SLOW = 30_000;
/** @type {string} */
let tmpDir;
/** @type {string} */
let pkgDir;
/**
* @param {string} file path under the package's src/, without extension
* @param {string} name
* @param {string} source
* @param {string} description
* @param {object} [extra] more doc fields
*/
function writeComponent(file, name, source, description, extra = {}) {
const target = path.join(pkgDir, 'src', file);
fs.mkdirSync(path.dirname(target), {recursive: true});
fs.writeFileSync(`${target}.tsx`, source);
fs.writeFileSync(
`${target}.doc.mjs`,
`export default ${JSON.stringify(
{
type: 'component',
name,
displayName: name,
import: `@acme/widgets/${file}`,
usage: {description},
props: [],
...extra,
},
null,
2,
)};\n`,
);
}
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-export-name-test-'));
fs.writeFileSync(
path.join(tmpDir, 'package.json'),
JSON.stringify({name: 'consumer', version: '1.0.0'}),
);
fs.writeFileSync(
path.join(tmpDir, 'astryx.config.mjs'),
"export default {integrations: ['@acme/widgets']};\n",
);
pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
fs.mkdirSync(pkgDir, {recursive: true});
fs.writeFileSync(
path.join(pkgDir, 'package.json'),
JSON.stringify({
name: '@acme/widgets',
version: '1.0.0',
exports: {
'./gallery/Slides': './src/gallery/Slides.tsx',
'./gallery/Overlays': './src/gallery/Overlays.tsx',
'./AcmeBadge': './src/AcmeBadge.tsx',
'./tabs': './src/tabs/AcmeTabs.tsx',
},
}),
);
fs.writeFileSync(
path.join(pkgDir, 'astryx.integration.mjs'),
"export default {components: './src', issuesUrl: 'https://example.com/acme/issues'};\n",
);
writeComponent(
'gallery/Slides',
'AcmeCarousel',
'export function AcmeCarousel() { return null; }\nexport function useSlides() { return []; }\n',
'Cycles through a row of slides.',
);
writeComponent(
'AcmeBadge',
'AcmeBadge',
'export function AcmeBadge() { return null; }\n',
'A small status label.',
);
// A family doc whose members the module it imports exports.
fs.mkdirSync(path.join(pkgDir, 'src', 'tabs'), {recursive: true});
fs.writeFileSync(
path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.tsx'),
'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\n',
);
fs.writeFileSync(
path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs'),
`export default ${JSON.stringify(
{
type: 'component',
name: 'AcmeTabs',
displayName: 'Acme Tabs',
import: '@acme/widgets/tabs',
keywords: ['tabs', 'navigation'],
usage: {description: 'Switches between views.'},
components: [
{
name: 'AcmeTabs',
displayName: 'Acme Tabs',
description: 'The tab list.',
props: [],
},
{
name: 'AcmeTab',
displayName: 'Acme Tab',
description: 'One labelled tab in the list.',
props: [
{name: 'label', type: 'string', description: 'The tab label.'},
],
},
],
},
null,
2,
)};\n`,
);
});
afterEach(() => {
fs.rmSync(tmpDir, {recursive: true, force: true});
});
/** @param {any} list @returns {string[]} the integration's listed names */
function listedNames(list) {
return Object.values(list.data.components)
.flat()
.filter(entry => entry.package === '@acme/widgets')
.map(entry => entry.name)
.sort();
}
describe('a component doc that names another export of its file', () => {
it(
"leaves a name a legacy docs package documents to that package's doc",
async () => {
const legacy = path.join(tmpDir, 'node_modules', '@legacy', 'docs');
fs.mkdirSync(path.join(legacy, 'docs'), {recursive: true});
fs.writeFileSync(
path.join(legacy, 'package.json'),
JSON.stringify({name: '@legacy/docs', astryx: {docs: './docs'}}),
);
for (const name of ['AcmeCarousel', 'Slides']) {
fs.writeFileSync(
path.join(legacy, 'docs', `${name}.doc.mjs`),
`export default {type: 'component', name: '${name}', usage: {description: 'Legacy.'}, props: []};\n`,
);
}
const cwd = tmpDir;
expect((await component('AcmeCarousel', {cwd})).data.package).toBe(
'@legacy/docs',
);
const scoped = {cwd, package: '@acme/widgets'};
expect((await component('AcmeCarousel', scoped)).data.package).toBe(
'@acme/widgets',
);
// Slides.doc.mjs's file name still answers first, as on main.
expect((await component('Slides', {cwd})).data.package).toBe(
'@acme/widgets',
);
const report = {cwd, category: 'other', reason: 'Needs a size.'};
for (const name of ['AcmeCarousel', 'acmecarousel']) {
expect((await gapReport(name, report)).data.package).toBe(
'@astryxdesign/core',
);
}
const hits = (await search('AcmeCarousel', {cwd, type: 'component'})).data
.results;
expect(hits.find(hit => hit.package === '@acme/widgets')?.command).toBe(
'astryx component AcmeCarousel --package @acme/widgets',
);
},
SLOW,
);
it(
'is listed, opened and found by the export name',
async () => {
expect(
listedNames(await component(undefined, {cwd: tmpDir, list: true})),
).toEqual(['AcmeBadge', 'AcmeCarousel', 'AcmeTab', 'AcmeTabs']);
const detail = await component('AcmeCarousel', {cwd: tmpDir});
expect(detail.type).toBe('component.detail');
expect(detail.data).toMatchObject({
name: 'AcmeCarousel',
package: '@acme/widgets',
import: '@acme/widgets/gallery/Slides',
sourceAvailable: true,
});
const hits = (
await search('AcmeCarousel', {cwd: tmpDir, type: 'component'})
).data.results;
expect(hits[0]).toMatchObject({
name: 'AcmeCarousel',
package: '@acme/widgets',
import: '@acme/widgets/gallery/Slides',
});
// The file name opens the same doc, as it did before, routes a gap
// report to the package, and search finds the component by it, a word
// of it included.
expect((await component('Slides', {cwd: tmpDir})).data.name).toBe(
'AcmeCarousel',
);
const report = {cwd: tmpDir, category: 'other', reason: 'Needs a size.'};
expect((await gapReport('Slides', report)).data.package).toBe(
'@acme/widgets',
);
for (const query of ['Slides', 'slide']) {
const byFileName = (
await search(query, {cwd: tmpDir, type: 'component'})
).data.results;
expect(byFileName[0]?.name).toBe('AcmeCarousel');
}
},
SLOW,
);
it.each(['the export its doc names', 'a member its family doc lists'])(
"leaves a Core name to Core unless --package names it, when it is %s, and passes Doctor's package checks",
async kind => {
// Overlays.tsx exports Dialog, a Core name, and nothing named Overlays.
const members = [{name: 'Dialog', description: 'A dialog.', props: []}];
const member = kind === 'a member its family doc lists';
writeComponent(
'gallery/Overlays',
member ? 'AcmeOverlays' : 'Dialog',
'export function AcmeOverlays() { return null; }\nexport function Dialog() { return null; }\n',
'Overlays.',
member ? {components: members} : {},
);
const validation = await validateIntegration(undefined, {cwd: pkgDir});
expect(validation.data.issues).toEqual([]);
const conflicts = await integrationComponentConflicts(undefined, {
cwd: pkgDir,
});
expect(conflicts.data.conflicts.map(conflict => conflict.name)).toEqual([
'Dialog',
]);
// Lookups by the bare name still answer with Core's Dialog, as before.
const cwd = tmpDir;
const core = '@astryxdesign/core';
expect((await component('Dialog', {cwd})).data.package).toBe(core);
expect((await component('Dialog', {cwd, props: true})).package).toBe(
core,
);
expect((await swizzleCopy('Dialog', {cwd})).package).toBe(core);
const report = {cwd, category: 'other', reason: 'Needs a size.'};
expect((await gapReport('Dialog', report)).data.package).toBe(core);
// The list and --package reach the integration's Dialog.
const scoped = {cwd, package: '@acme/widgets'};
expect((await component('Dialog', scoped)).data.import).toBe(
'@acme/widgets/gallery/Overlays',
);
expect(
listedNames(await component(undefined, {cwd, list: true})),
).toContain('Dialog');
// Search shows both; the package's hit names its package and follows
// Core's.
const hits = (await search('Dialog', {cwd, type: 'component'})).data
.results;
const ours = hits.findIndex(hit => hit.package === '@acme/widgets');
expect(hits[0]).toMatchObject({name: 'Dialog', package: core});
expect(hits[ours]).toMatchObject({
name: 'Dialog',
command: 'astryx component Dialog --package @acme/widgets',
});
},
SLOW,
);
it(
'leaves a Core name with no folder of its own unknown to swizzle, as before',
async () => {
// Core documents CheckboxIndicator inside Indicator's doc, with no folder.
// BaseTable, named after its file, keeps routing reports to its package.
writeComponent(
'BaseTable',
'BaseTable',
'export function BaseTable() { return null; }\n',
'A file-named table.',
);
writeComponent(
'gallery/Indicator',
'CheckboxIndicator',
'export function CheckboxIndicator() { return null; }\n',
'A header.',
);
const cwd = tmpDir;
expect((await component('CheckboxIndicator', {cwd})).data.package).toBe(
'@astryxdesign/core',
);
await expect(
swizzleCopy('CheckboxIndicator', {cwd}),
).rejects.toMatchObject({
code: 'ERR_UNKNOWN_COMPONENT',
});
const scoped = {cwd, package: '@acme/widgets'};
expect((await swizzleCopy('CheckboxIndicator', scoped)).package).toBe(
'@acme/widgets',
);
const report = {cwd, category: 'other', reason: 'Needs a size.'};
expect((await gapReport('CheckboxIndicator', report)).data.package).toBe(
'@astryxdesign/core',
);
const hit = (
await search('CheckboxIndicator', {cwd, type: 'component'})
).data.results.find(result => result.package === '@acme/widgets');
expect(hit?.command).toBe(
'astryx component CheckboxIndicator --package @acme/widgets',
);
expect((await gapReport('BaseTable', report)).data.package).toBe(
'@acme/widgets',
);
},
SLOW,
);
it.each([
// props must be an array: the loader rejects this doc.
[
'invalid',
"export default {type: 'component', name: 'AcmeTab', props: 'x'};",
],
[
'hidden',
"export default {\n type: 'component',\n name: 'AcmeTab',\n hidden: true,\n usage: {description: 'x'},\n props: [],\n};",
],
])(
"leaves a name to another package's file-named doc even when that doc is %s",
async (kind, doc) => {
writeComponent(
'gallery/Strip',
'AcmeTab',
'export function AcmeTab() { return null; }\n',
'A strip of tabs.',
);
const beta = path.join(tmpDir, 'node_modules', '@beta', 'kit');
fs.mkdirSync(path.join(beta, 'src'), {recursive: true});
for (const [file, text] of Object.entries({
'package.json': '{"name": "@beta/kit", "version": "1.0.0"}',
'astryx.integration.mjs': "export default {components: './src'};",
'src/AcmeTab.tsx': 'export function AcmeTab() { return null; }',
'src/AcmeTab.doc.mjs': doc,
})) {
fs.writeFileSync(path.join(beta, file), `${text}\n`);
}
fs.writeFileSync(
path.join(tmpDir, 'astryx.config.mjs'),
"export default {integrations: ['@acme/widgets', '@beta/kit']};\n",
);
const cwd = tmpDir;
expect((await component('AcmeTab', {cwd, source: true})).package).toBe(
'@beta/kit',
);
if (kind === 'invalid') {
await expect(component('AcmeTab', {cwd})).rejects.toMatchObject({
code: 'ERR_INVALID_DOC',
});
}
const report = {cwd, category: 'other', reason: 'Needs a size.'};
for (const name of ['AcmeTab', 'acmetab']) {
expect((await gapReport(name, report)).data.package).toBe(
'@astryxdesign/core',
);
}
const hit = (
await search('AcmeTab', {cwd, type: 'component'})
).data.results.find(result => result.package === '@acme/widgets');
expect(hit?.command).toBe(
'astryx component AcmeTab --package @acme/widgets',
);
},
SLOW,
);
it(
'leaves a file name Core also has to Core in search, as in detail',
async () => {
// Badge.doc.mjs documents AcmeStatusBadge; its file name is Core's.
writeComponent(
'status/Badge',
'AcmeStatusBadge',
'export function AcmeStatusBadge() { return null; }\n',
'Shows a status.',
);
const cwd = tmpDir;
const [first] = (await search('Badge', {cwd, type: 'component'})).data
.results;
expect(first).toMatchObject({
name: 'Badge',
package: '@astryxdesign/core',
});
expect((await component('Badge', {cwd})).data.package).toBe(
'@astryxdesign/core',
);
const [own] = (await search('AcmeStatusBadge', {cwd, type: 'component'}))
.data.results;
expect(own).toMatchObject({
name: 'AcmeStatusBadge',
command: 'astryx component AcmeStatusBadge',
});
},
SLOW,
);
it(
'copies a replacement recorded under its export into its file name folder, as before',
async () => {
const manifest = path.join(pkgDir, 'package.json');
fs.writeFileSync(
manifest,
JSON.stringify({
...JSON.parse(fs.readFileSync(manifest, 'utf-8')),
peerDependencies: {
'@astryxdesign/cli': `>=${COMPONENT_REPLACES_CLI}`,
},
}),
);
writeComponent(
'gallery/Slides',
'AcmeCarousel',
'export function AcmeCarousel() { return null; }\n',
'Cycles through a row of slides.',
{replaces: 'Carousel'},
);
const copied = await swizzleCopy('Carousel', {cwd: tmpDir});
expect(copied.data).toMatchObject({
package: '@acme/widgets',
outputDir: path.join('components', 'astryx', 'Slides'),
});
},
SLOW,
);
it(
"opens a member named like its family doc's own name as that member",
async () => {
// Overlays.tsx exports Overlays, so the doc keeps its file name, and
// AcmeChip, the doc's own name, is a member.
const label = {name: 'label', type: 'string', description: 'The label.'};
writeComponent(
'gallery/Overlays',
'AcmeChip',
'export function Overlays() { return null; }\nexport function AcmeChip() { return null; }\nexport function AcmeChipIcon() { return null; }\n',
'Chips.',
{
components: [
{name: 'AcmeChip', description: 'One chip.', props: [label]},
{name: 'AcmeChipIcon', description: 'An icon.', props: []},
],
},
);
// Every member names the family by the name it opens under.
expect(
(await component('AcmeChipIcon', {cwd: tmpDir})).data.parentDoc,
).toBe('Overlays');
const detail = await component('AcmeChip', {cwd: tmpDir});
expect(detail.data).toMatchObject({
name: 'AcmeChip',
description: 'One chip.',
parentDoc: 'Overlays',
});
const props = await component('AcmeChip', {cwd: tmpDir, props: true});
expect(props.data.map(prop => prop.name)).toEqual(['label']);
},
SLOW,
);
it(
'opens, lists and finds a family member as itself, with the import its family states',
async () => {
const list = await component(undefined, {cwd: tmpDir, list: true});
const entry = Object.values(list.data.components)
.flat()
.find(item => item.name === 'AcmeTab');
expect(entry).toEqual({
name: 'AcmeTab',
package: '@acme/widgets',
import: '@acme/widgets/tabs',
});
const detail = await component('AcmeTab', {cwd: tmpDir});
expect(detail.data).toMatchObject({
name: 'AcmeTab',
description: 'One labelled tab in the list.',
parentDoc: 'AcmeTabs',
package: '@acme/widgets',
import: '@acme/widgets/tabs',
sourceAvailable: true,
});
expect(detail.data.props.map(prop => prop.name)).toEqual(['label']);
const props = await component('AcmeTab', {cwd: tmpDir, props: true});
expect(props.data.map(prop => prop.name)).toEqual(['label']);
// The family's own doc is unchanged.
expect((await component('AcmeTabs', {cwd: tmpDir})).data).toMatchObject({
name: 'AcmeTabs',
import: '@acme/widgets/tabs',
});
const hits = (await search('AcmeTab', {cwd: tmpDir, type: 'component'}))
.data.results;
expect(hits[0]).toMatchObject({
name: 'AcmeTab',
description: 'One labelled tab in the list.',
import: '@acme/widgets/tabs',
});
// The member does not carry the family's keywords.
const tabs = (
await search('navigation', {cwd: tmpDir, type: 'component'})
).data.results;
expect(tabs.map(hit => hit.name)).toContain('AcmeTabs');
expect(tabs.map(hit => hit.name)).not.toContain('AcmeTab');
},
SLOW,
);
it(
'leaves a member named like a Core sub-component to Core, and swizzle unknown',
async () => {
const tabs = path.join(pkgDir, 'src', 'tabs');
const doc = path.join(tabs, 'AcmeTabs.doc.mjs');
fs.writeFileSync(
doc,
fs
.readFileSync(doc, 'utf-8')
.replace(
'"components": [',
'"components": [{"name": "DialogHeader", "description": "x"},',
),
);
fs.appendFileSync(
path.join(tabs, 'AcmeTabs.tsx'),
'export function DialogHeader() { return null; }\n',
);
const cwd = tmpDir;
expect(
listedNames(await component(undefined, {cwd, list: true})),
).toContain('DialogHeader');
expect((await component('DialogHeader', {cwd})).data.package).toBe(
'@astryxdesign/core',
);
await expect(swizzleCopy('DialogHeader', {cwd})).rejects.toMatchObject({
code: 'ERR_UNKNOWN_COMPONENT',
});
},
SLOW,
);
it('fails a member its family doc, as this process loaded it, does not list', async () => {
const owner = {
package: '@acme/widgets',
docPath: path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs'),
sourcePath: null,
};
// The doc this process loaded before AcmeTab was added.
const stale = {type: 'component', name: 'AcmeTabs', components: []};
expect(() =>
scopeIntegrationMember(/** @type {any} */ (stale), owner, 'AcmeTab', ''),
).toThrow(expect.objectContaining({code: 'ERR_UNKNOWN_COMPONENT'}));
});
it(
'indexes an installed .doc.ts family and its member, as a .doc.mjs family is',
() => {
const fam = path.join(pkgDir, 'src', 'fam');
fs.mkdirSync(fam, {recursive: true});
const manifest = path.join(pkgDir, 'package.json');
const pkg = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
pkg.exports['./fam'] = './src/fam/AcmeFamTs.tsx';
fs.writeFileSync(manifest, JSON.stringify(pkg));
fs.writeFileSync(
path.join(fam, 'AcmeFamTs.doc.ts'),
"export default {type: 'component', name: 'AcmeFamTs', import: '@acme/widgets/fam', usage: {description: 'A family.'}, components: [{name: 'AcmeFamTs', description: 'x'}, {name: 'AcmeFamItem', description: 'One item.'}]};\n",
);
fs.writeFileSync(
path.join(fam, 'AcmeFamTs.tsx'),
'export function AcmeFamTs() { return null; }\nexport function AcmeFamItem() { return null; }\n',
);
// The real CLI under Node, which does not strip types in node_modules:
// the doc loads through jiti, so the member is found as in a .doc.mjs.
const run = spawnSync(
process.execPath,
[
path.join(process.cwd(), 'packages/cli/clients/cli/bin/astryx.mjs'),
'search',
'AcmeFamTs',
'--json',
],
{cwd: tmpDir, encoding: 'utf-8'},
);
const hits = JSON.parse(run.stdout).data.results.filter(
(/** @type {any} */ hit) => hit.domain === 'component',
);
expect(hits.map((/** @type {any} */ hit) => hit.name)).toEqual([
'AcmeFamTs',
'AcmeFamItem',
]);
},
SLOW,
);
it(
'reads a family doc once when the docs compile',
async () => {
const {inputs, problems} = await collectDocInputs(
await Project.load(tmpDir),
);
expect(problems).toEqual([]);
const tabsDoc = path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs');
expect(
inputs.filter(input => input.file === tabsDoc).map(input => input.name),
).toEqual(['AcmeTabs']);
},
SLOW,
);
});