An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Colocated tests for the `component` command dispatcher
* (api/component/component.mjs), run against the real @astryxdesign/core
* registry. `component` fans out to list/detail(+props/source/showcase/blocks)
* leaves; this pins the DISPATCH + precedence rules that no other suite covered
* (component had no api-level tests). Locks behavior so a future refactor of the
* router can't silently change which leaf a given arg/flag combination hits.
*/
import {describe, it, expect} from 'vitest';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {component} from './component.mjs';
import {search} from '../search/search.mjs';
import {AstryxError} from '../error.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';
// api/component/ -> up 4 = repo root (has packages/core, which findCoreDir walks to).
const REPO = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../../../..',
);
const cwd = REPO;
const SLOW = 30_000;
describe('component dispatcher — routing', () => {
it(
'routes a bare name to component.detail',
async () => {
const r = await component('Button', {cwd});
expect(r.type).toBe('component.detail');
expect(r.data.name).toBe('Button');
},
SLOW,
);
it(
'routes no-name to the list leaf (component.list, detail=names)',
async () => {
const r = await component(undefined, {cwd});
expect(r.type).toBe('component.list');
expect(r.data.detail).toBe('names');
expect(Object.keys(r.data.components).length).toBeGreaterThan(0);
},
SLOW,
);
it(
'routes --category to the list leaf, filtered to that group',
async () => {
const r = await component(undefined, {cwd, category: 'Layout'});
expect(r.type).toBe('component.list');
expect(Object.keys(r.data.components)).toContain('Layout');
},
SLOW,
);
it(
'treats an empty-string name as a list (not a not-found error)',
async () => {
const r = await component('', {cwd});
expect(r.type).toBe('component.list');
},
SLOW,
);
});
describe('component dispatcher — detail levels on list', () => {
it(
'--detail compact lists with detail=compact',
async () => {
const r = await component(undefined, {
cwd,
list: true,
detail: 'compact',
});
expect(r.type).toBe('component.list');
expect(r.data.detail).toBe('compact');
},
SLOW,
);
it(
'--detail full lists with detail=full',
async () => {
const r = await component(undefined, {cwd, list: true, detail: 'full'});
expect(r.type).toBe('component.list');
expect(r.data.detail).toBe('full');
},
SLOW,
);
});
describe('component list — components whose docs live in a family folder', () => {
it('lists HStack, VStack and Heading at every detail level, each with its own import', async () => {
const {docs: stackDoc} = await import(
path.join(REPO, 'packages', 'core', 'src', 'Stack', 'Stack.doc.mjs')
);
const vstackMember = stackDoc.components.find(c => c.name === 'VStack');
const names = await component(undefined, {cwd, list: true});
const listed = Object.values(names.data.components).flat();
for (const name of ['HStack', 'VStack', 'Heading']) {
expect(listed).toContainEqual({name, package: '@astryxdesign/core'});
}
const compact = await component(undefined, {cwd, list: true, detail: 'compact'});
const brief = Object.values(compact.data.components).flat();
expect(brief.find(e => e.name === 'VStack')).toEqual({
name: 'VStack',
package: '@astryxdesign/core',
description: vstackMember.description,
import: '@astryxdesign/core/VStack',
});
const full = await component(undefined, {cwd, list: true, detail: 'full'});
const entry = Object.values(full.data.components)
.flat()
.find(e => e.name === 'VStack');
// Shaped like every other full entry (a component doc plus its package):
// the member's own name, display name and summary, and no scoping field
// the full-entry type does not describe.
expect(entry).toEqual({
name: 'VStack',
package: '@astryxdesign/core',
displayName: vstackMember.displayName,
group: stackDoc.group,
category: stackDoc.category,
usage: {description: vstackMember.description},
props: vstackMember.props,
theming: stackDoc.theming,
import: '@astryxdesign/core/VStack',
});
}, SLOW);
it('answers a Core-scoped lookup of a member with that member, as the unscoped lookup does', async () => {
for (const name of ['HStack', 'VStack']) {
const unscoped = await component(name, {cwd});
const scoped = await component(name, {
cwd,
package: '@astryxdesign/core',
});
expect(scoped.data.name).toBe(name);
expect(scoped.data.parentDoc).toBe('Stack');
expect(scoped.data.import).toBe(`@astryxdesign/core/${name}`);
expect(scoped.data.props).toEqual(unscoped.data.props);
expect(scoped.data.props.length).toBeGreaterThan(0);
}
}, SLOW);
it('prints each one\'s own import path in the list, the detail, and search', async () => {
// The path `component <Name>` prints is the one docs and examples teach:
// the component's own entry point, never its family's (/Stack, /Text) or
// a re-export (/Layout).
const compact = Object.values(
(await component(undefined, {cwd, list: true, detail: 'compact'})).data.components,
).flat();
const full = Object.values(
(await component(undefined, {cwd, list: true, detail: 'full'})).data.components,
).flat();
const textList = (await runCli(['component', '--list'], cwd)).stdout;
const textCompact = (
await runCli(['component', '--list', '--detail', 'compact'], cwd)
).stdout;
/** The `import:` line of a text record, found by its `name:` line. */
const textImport = (text, name) =>
new RegExp(`^name:\\s+${name}\\n(?:(?!name:).*\\n)*?import:\\s+(\\S+)`, 'm').exec(
text,
)?.[1];
for (const name of ['VStack', 'HStack', 'Heading']) {
const expected = `@astryxdesign/core/${name}`;
expect(compact.find(e => e.name === name)?.import).toBe(expected);
expect((await component(name, {cwd})).data.import).toBe(expected);
const hits = (await search(name, {cwd, type: 'component'})).data.results;
expect(hits.find(r => r.name === name)?.import).toBe(expected);
expect(textImport(textList, name)).toBe(expected);
expect(textImport(textCompact, name)).toBe(expected);
}
// The full level spreads a component's own doc, which states no import
// (Button's entry has none either); a member's entry is scoped to the
// member and states its own.
for (const name of ['VStack', 'HStack']) {
expect(full.find(e => e.name === name)?.import).toBe(`@astryxdesign/core/${name}`);
}
}, SLOW);
});
describe('component dispatcher — projection precedence (locked)', () => {
it(
'--props routes to component.detail.props',
async () => {
const r = await component('Button', {cwd, props: true});
expect(r.type).toBe('component.detail.props');
},
SLOW,
);
it(
'--source routes to component.detail.source',
async () => {
const r = await component('Button', {cwd, source: true});
expect(r.type).toBe('component.detail.source');
},
SLOW,
);
it(
'--source WINS over --props when both are set (precedence lock)',
async () => {
const r = await component('Button', {cwd, props: true, source: true});
expect(r.type).toBe('component.detail.source');
},
SLOW,
);
it(
'--list WINS over a given name (list dispatch precedence lock)',
async () => {
const r = await component('Button', {cwd, list: true});
expect(r.type).toBe('component.list');
},
SLOW,
);
});
describe('component dispatcher — name resolution', () => {
it(
'strips a legacy XDS prefix (XDSButton -> Button)',
async () => {
const r = await component('XDSButton', {cwd});
expect(r.type).toBe('component.detail');
expect(r.data.name).toBe('Button');
},
SLOW,
);
it(
'is case-SENSITIVE: a lowercased name is unknown',
async () => {
let err;
try {
await component('button', {cwd});
} catch (e) {
err = e;
}
expect(err).toBeDefined();
expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
},
SLOW,
);
it(
'opens Tokenizer for tokenizer, not CodeBlock through its tokenizer module (spec:AST-083 FR7)',
async () => {
const r = await component('tokenizer', {cwd});
expect(r.type).toBe('component.detail');
expect(r.data.name).toBe('Tokenizer');
},
SLOW,
);
it.each(['slider', 'switch', 'progressBar', 'tokenizer'])(
'reads no source for %s, a component name in another case that a motion table or helper module shares',
async name => {
let err;
try {
await component(name, {cwd, source: true});
} catch (e) {
err = e;
}
expect(err?.code).toBe('ERR_NO_SOURCE');
},
SLOW,
);
it(
'throws ERR_UNKNOWN_COMPONENT for a genuinely unknown name',
async () => {
let err;
try {
await component('ZzzNope99', {cwd});
} catch (e) {
err = e;
}
expect(err.code).toBe('ERR_UNKNOWN_COMPONENT');
},
SLOW,
);
it(
'throws ERR_UNKNOWN_PACKAGE when --package names a missing package',
async () => {
let err;
try {
await component('Button', {cwd, package: '@nonexistent/pkg-xyz'});
} catch (e) {
err = e;
}
expect(err).toBeDefined();
expect(err.code).toBe('ERR_UNKNOWN_PACKAGE');
},
SLOW,
);
});
describe('component dispatcher — scoped --package routes all projections', () => {
const CORE = '@astryxdesign/core';
it(
'--package (core) routes --showcase like the no-scope path',
async () => {
const ns = await component('Button', {cwd, showcase: true});
const sc = await component('Button', {
cwd,
package: CORE,
showcase: true,
});
expect(sc.type).toBe(ns.type); // was silently component.detail before the fix
},
SLOW,
);
it(
'--package (core) routes --blocks like the no-scope path',
async () => {
const ns = await component('Button', {cwd, blocks: true});
const sc = await component('Button', {cwd, package: CORE, blocks: true});
expect(sc.type).toBe(ns.type);
expect(sc.type).toBe('component.detail.blocks');
},
SLOW,
);
it(
"--props carries a prop doc's stability marker (Drawer's experimental prop)",
async () => {
const r = await component('Drawer', {cwd, props: true});
expect(r.type).toBe('component.detail.props');
const experimental = r.data.find(p => p.name === 'experimental');
expect(experimental?.stability).toBe('experimental');
// Only the experimental prop object is marked; stable props carry no field.
expect(
r.data.filter(p => p.stability !== undefined).map(p => p.name),
).toEqual(['experimental']);
},
SLOW,
);
it(
'--props --json and the text props table both show the stability marker',
async () => {
const json = await runCli(
['component', 'Drawer', '--props', '--json'],
cwd,
);
expect(json.status).toBe(0);
const envelope = JSON.parse(json.stdout);
expect(envelope.type).toBe('component.detail.props');
expect(
envelope.data.find(p => p.name === 'experimental')?.stability,
).toBe('experimental');
const text = await runCli(['component', 'Drawer', '--props'], cwd);
expect(text.status).toBe(0);
const rows = text.stdout
.split('\n')
.filter(line => line.startsWith('| `'));
const experimentalRow = rows.find(line =>
line.startsWith('| `experimental` |'),
);
expect(experimentalRow).toContain('**(experimental)**');
expect(
rows.filter(line => line.includes('**(experimental)**')),
).toHaveLength(1);
},
SLOW,
);
it(
'--package (core) still routes --source and --props',
async () => {
expect(
(await component('Button', {cwd, package: CORE, source: true})).type,
).toBe('component.detail.source');
expect(
(await component('Button', {cwd, package: CORE, props: true})).type,
).toBe('component.detail.props');
},
SLOW,
);
});
describe('component dispatcher — category guard', () => {
it(
'a non-string category throws a coded error (not a raw TypeError)',
async () => {
for (const bad of [123, {}, [1]]) {
const err = await component(undefined, {
cwd,
category: /** @type {any} */ (bad),
}).catch(e => e);
expect(err).toBeInstanceOf(AstryxError);
expect(err.code).toBe('ERR_UNKNOWN_CATEGORY');
}
},
SLOW,
);
});
describe('component dispatcher — detail and lang guards', () => {
// `detail` and `lang` are the same controls as the CLI's --detail and --lang:
// same accepted values, same error codes.
it(
'rejects a detail level the CLI rejects, with the same code',
async () => {
const cliRun = await runCli(
['--json', 'component', '--list', '--detail', 'bogus'],
cwd,
);
expect(cliRun.code).toBe(1);
expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
const bogus = /** @type {any} */ ('bogus');
for (const call of [
() => component(undefined, {cwd, list: true, detail: bogus}),
() => component('Button', {cwd, detail: bogus}),
]) {
const err = await call().catch(e => e);
expect(err).toBeInstanceOf(AstryxError);
expect(err.code).toBe('ERR_INVALID_DETAIL');
}
},
SLOW,
);
it(
'rejects a lang the CLI rejects, with the same code',
async () => {
const cliRun = await runCli(
['--json', 'component', 'Button', '--lang', 'fr'],
cwd,
);
expect(cliRun.code).toBe(1);
expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
for (const call of [
() => component('Button', {cwd, lang: 'fr'}),
() =>
component(undefined, {
cwd,
list: true,
detail: 'compact',
lang: 'fr',
}),
]) {
const err = await call().catch(e => e);
expect(err).toBeInstanceOf(AstryxError);
expect(err.code).toBe('ERR_INVALID_LANG');
}
const zh = await component('Button', {cwd, lang: 'zh'});
expect(zh.type).toBe('component.detail');
},
SLOW,
);
});
describe('component dispatcher — detail levels on single component (text only)', () => {
it(
'--detail compact returns less text than full',
async () => {
const full = await runCli(['component', 'Button'], cwd);
const compact = await runCli(
['component', 'Button', '--detail', 'compact'],
cwd,
);
expect(full.code).toBe(0);
expect(compact.code).toBe(0);
expect(compact.stdout.length).toBeLessThan(full.stdout.length);
// Compact still shows the name and import
expect(compact.stdout).toContain('Button');
expect(compact.stdout).toContain('@astryxdesign/core');
},
SLOW,
);
it(
'--detail brief returns less text than compact',
async () => {
const compact = await runCli(
['component', 'Button', '--detail', 'compact'],
cwd,
);
const brief = await runCli(
['component', 'Button', '--detail', 'brief'],
cwd,
);
expect(brief.code).toBe(0);
expect(brief.stdout.length).toBeLessThan(compact.stdout.length);
expect(brief.stdout).toContain('Button');
},
SLOW,
);
it(
'--json --detail compact returns the same full JSON as --json (contract)',
async () => {
const full = await runCli(['--json', 'component', 'Button'], cwd);
const compact = await runCli(
['--json', 'component', 'Button', '--detail', 'compact'],
cwd,
);
expect(full.code).toBe(0);
expect(compact.code).toBe(0);
const fullData = JSON.parse(full.stdout);
const compactData = JSON.parse(compact.stdout);
// JSON shape is identical — detail is a text-only projection
expect(Object.keys(compactData.data).sort()).toEqual(
Object.keys(fullData.data).sort(),
);
},
SLOW,
);
});
describe('component not-found suggestions', () => {
const suggested = async (/** @type {string} */ name) => {
const error = await component(name, {cwd}).catch(e => e);
expect(error).toBeInstanceOf(AstryxError);
expect(error.code).toBe('ERR_UNKNOWN_COMPONENT');
return error.suggestions.map((/** @type {{name: string}} */ s) => s.name);
};
it(
'leaves out a weaker match after a strong first suggestion',
async () => {
// FieldLabel is another name for it; past the second suggestion, the
// matches on one word of the name ("input", "label") are weaker and add
// only noise.
const names = await suggested('InputLabel');
expect(names[0]).toBe('FieldLabel');
expect(names).toHaveLength(2);
},
SLOW,
);
it(
'keeps a close spelling of the whole name after a stronger first match',
async () => {
expect(await suggested('Blockqoute')).toContain('Blockquote');
expect(await suggested('TextrAea')).toContain('TextArea');
},
SLOW,
);
});