An open source design system that's fully customizable and agent ready
TypeScript
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file generate-data.mjs
*
* Build-time data extraction for the Astryx docsite.
* Reads package.json, .doc.mjs, templates, and markdown files across the
* monorepo and generates typed TypeScript registries in src/generated/.
*
* Run: node scripts/generate-data.mjs
*
* Generates:
* - packageRegistry.ts — metadata for every distributable package
* - componentRegistry.ts — component listings per package (from .doc.mjs)
* - blockRegistry.ts — showcases + example blocks from CLI templates
* - templateRegistry.ts — page templates including playground source
* - templateMetadataRegistry.ts — lightweight page-template metadata
* - docsRegistry.ts — long-form documentation topics from CLI docs/
* - blogRegistry.ts — blog posts (plus canary-only test fixtures)
* - blogExampleAssets.ts — each post's live-example assets, loaded on demand
* - searchLinks.json — search destinations and document presentation metadata
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {execFileSync} from 'node:child_process';
import {createRequire} from 'node:module';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {
admittedStableIntegration,
resolveContentRoot,
} from './resolve-content-root.mjs';
import {
GUIDE_NAMESPACE_PAGES,
GUIDE_PAGE_NAMESPACES,
ROOT_PAGE_ALIASES,
applySidebarParents,
movedGuideRedirects,
mergeFlatTopics,
namespacePage,
rootNamespacePages,
routeSlug,
sectionAnchors,
withCliCommands,
withoutResolvedTokens,
} from './docs-pages.mjs';
import {
DOCSITE_CLI_COMMAND,
DOCSITE_PACKAGE_MANAGER,
GLOBAL_PAGE,
GLOBAL_PAGE_CLI_COMMAND,
getCliInvocation,
prefixCliCommands,
runWithDocPackageManager,
runWithCliDoor,
} from './lib/cli-command.mjs';
import {
docs as readDocs,
template as queryTemplates,
} from '@astryxdesign/cli/api';
import {
discoverAll,
pkgOf,
replaceDemoContent,
} from '../../../packages/cli/foundation/discovery/template-adapter.mjs';
import docsiteConfig from '../astryx.config.mjs';
import {
integrationContentEnabled,
integrationPackagesForTarget,
} from '../src/lib/integrationTargets.mjs';
import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';
import {componentStability} from './lib/component-stability.mjs';
import {projectThemingDoc} from './lib/theming-doc.mjs';
import {searchLinkTables} from '../src/lib/searchLinks.mjs';
import {exampleAnchorId} from '../src/lib/exampleAnchor.mjs';
import {collectBlogImages} from './lib/blog-images.mjs';
import {
buildTypeDefinitionIndex,
collectPropTypeRefs,
} from '../src/lib/typeDefinitions.mjs';
import {
generateShadcnRegistryForTarget,
registrySkipNotices,
reportRegistrySkips,
} from './generate-shadcn-registry.mjs';
import {createPublishedImportJudge} from './published-exports.mjs';
import {
blockRegistryIdentity,
resolveShadcnRegistryOrigin,
} from '../src/lib/shadcnRegistry.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const require = createRequire(import.meta.url);
const DOCSITE_ROOT = path.resolve(__dirname, '..');
const REPO_ROOT = path.resolve(DOCSITE_ROOT, '..', '..');
const OUT_DIR = path.join(DOCSITE_ROOT, 'src', 'generated');
const CLI_BIN = path.join(
REPO_ROOT,
'packages',
'cli',
'clients',
'cli',
'bin',
'astryx.mjs',
);
// Which version of the packages supplies the documented DATA (component
// .doc.mjs, package.json versions, READMEs). `canary` (and every PR preview)
// reads the live workspace; `latest` (production) reads the published release.
// CLI_ROOT is deliberately NOT pinned — template demos are live-rendered React
// against the bundled core, so they always come from the workspace.
const {
target: DOCSITE_TARGET,
contentRoot: CONTENT_ROOT,
cliRoot: CLI_ROOT,
} = resolveContentRoot();
console.log(
`Docsite content target: ${DOCSITE_TARGET} (reading package docs from ${
path.relative(REPO_ROOT, CONTENT_ROOT) || '.'
})`,
);
fs.mkdirSync(OUT_DIR, {recursive: true});
// ── Helpers ────────────────────────────────────────────────────────────
const COPYRIGHT_HEADER =
'// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n';
function writeRegistry(filename, content) {
const outPath = path.join(OUT_DIR, filename);
fs.writeFileSync(outPath, COPYRIGHT_HEADER + content, 'utf-8');
console.log(` wrote ${path.relative(REPO_ROOT, outPath)}`);
}
/**
* The integration packages this build documents. Canary documents every
* configured integration and asks the CLI to confirm each one is installed.
* `latest` documents only the configured integrations that are stable
* releases present in the published content snapshot
* (src/lib/integrationTargets.mjs); their component docs are read from the
* snapshot like Core's, so no workspace discovery runs.
*
* The admitted list is written to src/generated/integrationPackages.json so
* generate-scope.mjs and generate-playground-types.mjs document the same
* packages without resolving the content snapshot again.
*/
function discoverConfiguredComponentPackages() {
const admitted = integrationPackagesForTarget(
DOCSITE_TARGET,
docsiteConfig,
admittedStableIntegration(CONTENT_ROOT),
);
fs.writeFileSync(
path.join(OUT_DIR, 'integrationPackages.json'),
JSON.stringify({target: DOCSITE_TARGET, packages: admitted}, null, 2) +
'\n',
);
if (admitted.length === 0) {
return new Set();
}
if (!integrationContentEnabled(DOCSITE_TARGET)) {
return new Set(admitted);
}
const output = execFileSync(
process.execPath,
[CLI_BIN, 'discover', '--json'],
{cwd: DOCSITE_ROOT, encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024},
);
const result = JSON.parse(output);
if (
result.type !== 'discover.list' ||
!Array.isArray(result.data) ||
result.meta?.configured === false
) {
throw new Error('Astryx CLI returned an invalid integration package list.');
}
const configured = Array.isArray(docsiteConfig.integrations)
? docsiteConfig.integrations
: [];
const discovered = new Set(result.data.map(pkg => pkg.name));
const missing = configured.filter(name => !discovered.has(name));
if (missing.length > 0) {
throw new Error(
`Astryx CLI did not discover configured integration packages: ${missing.join(', ')}`,
);
}
return discovered;
}
const CONFIGURED_COMPONENT_PACKAGES = discoverConfiguredComponentPackages();
/**
* Validates that a doc file declared an explicit `displayName`. Display
* names are authored by hand rather than derived at build time so
* authors stay in control of how each component reads in the gallery
* and sidebar UI (see PR #2376 review thread). Use the
* apps/docsite/scripts/backfill-display-name.mjs codemod to backfill
* the field on any doc file that's missing it.
*/
function requireDisplayName(displayName, where) {
if (!displayName) {
throw new Error(
`Missing \`displayName\` on doc entry: ${where}\n` +
'Every .doc.mjs file must declare an explicit `displayName` field.\n' +
'Run `node apps/docsite/scripts/backfill-display-name.mjs` to backfill it.',
);
}
return displayName;
}
/**
* Parses a single/double/backtick-quoted JS string literal starting at
* `openIdx` (the index of the opening quote) and returns the decoded
* string value plus the index just past the closing quote.
*
* Unlike a naive `[^'"`]` character class, this correctly handles:
* - interior quotes of a different type (e.g. `'Swap the default "/"'`)
* - escaped quotes of the same type (e.g. `'won\'t close it'`)
* - standard escape sequences (\n, \t, \uXXXX, \xXX, line continuations)
* and has no length cap, so long descriptions survive intact.
*/
function parseStringLiteral(content, openIdx) {
const quote = content[openIdx];
let i = openIdx + 1;
let out = '';
while (i < content.length) {
const ch = content[i];
if (ch === '\\') {
const next = content[i + 1];
switch (next) {
case 'n':
out += '\n';
i += 2;
continue;
case 'r':
out += '\r';
i += 2;
continue;
case 't':
out += '\t';
i += 2;
continue;
case 'b':
out += '\b';
i += 2;
continue;
case 'f':
out += '\f';
i += 2;
continue;
case 'v':
out += '\v';
i += 2;
continue;
case '0':
out += '\0';
i += 2;
continue;
case '\n':
i += 2;
continue; // line continuation
case '\r':
i += content[i + 2] === '\n' ? 3 : 2;
continue;
case 'u': {
if (content[i + 2] === '{') {
const end = content.indexOf('}', i + 3);
out += String.fromCodePoint(
parseInt(content.slice(i + 3, end), 16),
);
i = end + 1;
continue;
}
out += String.fromCharCode(parseInt(content.slice(i + 2, i + 6), 16));
i += 6;
continue;
}
case 'x':
out += String.fromCharCode(parseInt(content.slice(i + 2, i + 4), 16));
i += 4;
continue;
default:
out += next; // \', \", \`, \\, and any other escaped char
i += 2;
continue;
}
}
if (ch === quote) {
return {value: out, end: i + 1};
}
out += ch;
i++;
}
return {value: out, end: i};
}
/**
* Extracts a top-level quoted field value (e.g. `description`) from
* .doc.mjs source, decoding the string literal so interior quotes and
* escapes survive intact. Returns null when the field is absent.
*/
function extractQuotedField(content, field) {
const re = new RegExp(`(?:^|\\n) {0,4}${field}:\\s*\\n?\\s*['"\`]`);
const m = re.exec(content);
if (!m) return null;
const openIdx = m.index + m[0].length - 1; // index of the opening quote
return parseStringLiteral(content, openIdx).value;
}
/** Extract doc metadata from .doc.mjs source without dynamic import. */
const GROUP_RE = /(?:^|\n) {0,4}group:\s*['"]([^'"]+)['"]/;
const HIDDEN_RE = /(?:^|\n) {0,4}hidden:\s*true/;
const KEYWORDS_RE = /keywords:\s*\[([^\]]*)\]/;
const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
const IS_HIDDEN_FROM_OVERVIEW_RE = /(?:^|\n) {0,4}isHiddenFromOverview:\s*true/;
function readDocMeta(docPath) {
try {
const content = fs.readFileSync(docPath, 'utf-8');
const groupMatch = GROUP_RE.exec(content);
const description = extractQuotedField(content, 'description');
const name = extractQuotedField(content, 'name');
const displayName = extractQuotedField(content, 'displayName');
const hidden = HIDDEN_RE.test(content);
const kwMatch = KEYWORDS_RE.exec(content);
const keywords = kwMatch
? [...kwMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map(m => m[1])
: [];
const categoryMatch = CATEGORY_RE.exec(content);
const isHiddenFromOverview = IS_HIDDEN_FROM_OVERVIEW_RE.test(content);
return {
group: groupMatch?.[1] ?? null,
description: description ?? '',
name: name ?? null,
displayName: displayName ?? null,
hidden,
keywords,
category: categoryMatch?.[1] ?? null,
isHiddenFromOverview,
};
} catch {
return {
group: null,
description: '',
name: null,
displayName: null,
hidden: false,
keywords: [],
category: null,
isHiddenFromOverview: false,
};
}
}
function findDocFilesRecursive(dir, skipDirs = new Set()) {
const results = [];
if (!fs.existsSync(dir)) return results;
for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (!skipDirs.has(entry.name)) {
results.push(...findDocFilesRecursive(full, skipDirs));
}
} else if (entry.name.endsWith('.doc.mjs')) {
results.push(full);
}
}
return results;
}
/**
* Resolve the correct import path for a component given its package directory
* and the subdirectory it lives in. Checks the package.json "exports" field to
* find a matching subpath export (e.g. `@astryxdesign/core/Chat`).
*
* Falls back to the package name when no explicit export is found.
*/
function resolveImportPathForPkg(pkgDir, directory) {
const pkgJsonPath = path.join(CONTENT_ROOT, pkgDir, 'package.json');
if (!fs.existsSync(pkgJsonPath)) return null;
const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
if (pkg.exports && pkg.exports[`./${directory}`]) {
return `${pkg.name}/${directory}`;
}
// No matching export — fall back to package root
return pkg.name;
}
// ── Package discovery ──────────────────────────────────────────────────
/**
* Auto-discover packages from the monorepo workspace globs.
* Reads the `packages:` block of CONTENT_ROOT's pnpm-workspace.yaml — the live
* workspace on canary, the materialized release snapshot on latest (see
* resolve-content-root.mjs, which writes a synthetic pnpm-workspace.yaml into
* the snapshot) — and expands the globs.
* Skips apps/* and internal/* — only surfaces packages/*.
*/
function discoverPackageDirs() {
return expandWorkspaceDirs(CONTENT_ROOT)
.map(abs => path.relative(CONTENT_ROOT, abs))
.filter(rel => rel.startsWith('packages'))
.filter(rel => fs.existsSync(path.join(CONTENT_ROOT, rel, 'package.json')))
.sort();
}
const REGISTRY_EXTERNAL_DEPENDENCIES = [
'@heroicons/react',
'@stylexjs/stylex',
'lucide-react',
'recharts',
];
function registryExternalDependencySpecs() {
return Object.fromEntries(
REGISTRY_EXTERNAL_DEPENDENCIES.map(packageName => {
const version = require(`${packageName}/package.json`).version;
return [packageName, `${packageName}@${version}`];
}),
);
}
// ── 1. Package Registry ────────────────────────────────────────────────
function generatePackageRegistry() {
console.log('Generating package registry...');
const packageDirs = discoverPackageDirs();
const docsitePkg = JSON.parse(
fs.readFileSync(path.join(DOCSITE_ROOT, 'package.json'), 'utf-8'),
);
const docsiteDeps = {
...docsitePkg.dependencies,
...docsitePkg.devDependencies,
};
const packages = packageDirs
.map(dir => {
const pkgPath = path.join(CONTENT_ROOT, dir, 'package.json');
const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
const canaryOnly = raw.astryx?.canaryOnly === true;
// Private packages stay internal unless they are explicitly published on
// the canary line. The latest content snapshot never contains those
// packages, so this exception cannot leak them into production docs.
if (
raw.private === true &&
!(DOCSITE_TARGET === 'canary' && canaryOnly)
) {
return null;
}
// Skip packages not installed in the docsite
if (docsiteDeps[raw.name] == null) return null;
const hasReadme = fs.existsSync(
path.join(CONTENT_ROOT, dir, 'README.md'),
);
const hasChangelog = fs.existsSync(
path.join(CONTENT_ROOT, dir, 'CHANGELOG.md'),
);
const readme = hasReadme
? fs.readFileSync(path.join(CONTENT_ROOT, dir, 'README.md'), 'utf-8')
: null;
const changelog = hasChangelog
? fs.readFileSync(path.join(CONTENT_ROOT, dir, 'CHANGELOG.md'), 'utf-8')
: null;
return {
name: raw.name,
displayName:
raw.displayName ||
raw.name
.replace('@astryxdesign/', '')
.replace('theme-', 'Theme: ')
.replace(/^\w/, c => c.toUpperCase()),
version: raw.version,
description: raw.description || '',
packagePath: dir,
canaryOnly,
packageExports: raw.exports ?? null,
peerDependencies: raw.peerDependencies ?? {},
hasReadme,
hasChangelog,
readme,
changelog,
};
})
.filter(Boolean)
.sort((a, b) => a.name.localeCompare(b.name));
const publicPackages = packages.map(
({packageExports: _packageExports, ...pkg}) => pkg,
);
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface PackageMeta {
name: string;
displayName: string;
version: string;
description: string;
packagePath: string;
canaryOnly: boolean;
peerDependencies: Record<string, string>;
hasReadme: boolean;
hasChangelog: boolean;
readme: string | null;
changelog: string | null;
}
export const packages: PackageMeta[] = ${JSON.stringify(publicPackages, null, 2)};
`;
writeRegistry('packageRegistry.ts', content);
return packages;
}
function generatePackageStyles(packages, blocks, allComponents) {
const sourcePackages = new Set([
...blocks.map(block => block.sourcePackage).filter(Boolean),
...Object.keys(allComponents).filter(
packageName => packageName !== '@astryxdesign/core',
),
]);
const imports = [];
for (const pkg of packages.filter(entry => sourcePackages.has(entry.name))) {
const manifest = JSON.parse(
fs.readFileSync(
path.join(CONTENT_ROOT, pkg.packagePath, 'package.json'),
'utf-8',
),
);
for (const subpath of Object.keys(manifest.exports ?? {})) {
if (subpath.endsWith('.css')) {
imports.push(`@import "${pkg.name}/${subpath.slice(2)}";`);
}
}
}
const outPath = path.join(OUT_DIR, 'package-styles.css');
fs.writeFileSync(
outPath,
'/* Copyright (c) Meta Platforms, Inc. and affiliates. */\n\n' +
imports.join('\n') +
'\n',
'utf-8',
);
console.log(` wrote ${path.relative(REPO_ROOT, outPath)}`);
}
// ── 2. Component Registry ──────────────────────────────────────────────
const COMPONENT_DOC_SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
/** Sanitize a doc object for JSON serialization (strip functions, symbols, etc.) */
function sanitizeForJson(obj) {
return JSON.parse(
JSON.stringify(obj, (key, value) => {
if (typeof value === 'function' || typeof value === 'symbol')
return undefined;
return value;
}),
);
}
/**
* A component doc's `deprecated` (what replaces it), copied for the registry;
* null when the component is not deprecated. `replacementDisplayName` is
* resolved once every package's components are known.
* @param {{deprecated?: {replacement: string, description: string}}} doc
*/
function deprecationOf(doc) {
if (!doc.deprecated) return null;
const {replacement, description} = doc.deprecated;
return {replacement, replacementDisplayName: replacement, description};
}
function extractStringArrayField(content, field) {
const re = new RegExp(`${field}:\\s*\\[([^\\]]*)\\]`);
const match = re.exec(content);
if (!match) return [];
return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map(m => m[1]);
}
async function generateComponentRegistry() {
console.log('Generating component registry...');
const packageDirs = discoverPackageDirs();
const componentPackages = [];
for (const dir of packageDirs) {
const srcDir = path.join(CONTENT_ROOT, dir, 'src');
if (!fs.existsSync(srcDir)) continue;
const pkgJson = JSON.parse(
fs.readFileSync(path.join(CONTENT_ROOT, dir, 'package.json'), 'utf-8'),
);
if (
pkgJson.name !== '@astryxdesign/core' &&
!CONFIGURED_COMPONENT_PACKAGES.has(pkgJson.name)
) {
continue;
}
const allDocFiles = findDocFilesRecursive(srcDir, COMPONENT_DOC_SKIP_DIRS);
if (allDocFiles.length > 0) {
const manifest = JSON.parse(
fs.readFileSync(path.join(CONTENT_ROOT, dir, 'package.json'), 'utf-8'),
);
const docDirs = [
...new Set(allDocFiles.map(file => path.dirname(file))),
].sort();
componentPackages.push({
name: pkgJson.name,
srcDir,
dir,
docDirs,
canaryOnly: manifest.astryx?.canaryOnly === true,
});
}
}
const allComponents = {};
let totalCount = 0;
for (const pkg of componentPackages) {
if (!fs.existsSync(pkg.srcDir)) continue;
const components = [];
const standaloneNames = new Set();
const pendingSubComponents = [];
for (const dirPath of pkg.docDirs) {
const directory = path.relative(pkg.srcDir, dirPath);
const docFiles = fs
.readdirSync(dirPath)
.filter(f => f.endsWith('.doc.mjs'));
if (docFiles.length === 0) continue;
// First pass: find the primary component doc for this directory. Used to
// (a) parent standalone hook docs that share the directory, and
// (b) let sibling sub-component docs (subComponentOf) inherit family
// fields (group, category, keywords, theming, importPath, ...).
let dirPrimaryDoc = null;
let dirPrimaryMeta = null;
for (const df of docFiles) {
const dfPath = path.join(dirPath, df);
try {
const mod = await import(pathToFileURL(dfPath).href);
const d = mod.docs;
if (
d &&
(d.components || d.props) &&
!d.params &&
!d.subComponentOf
) {
dirPrimaryDoc = d.name || null;
dirPrimaryMeta = {
name: d.name || null,
group: d.group || null,
category: d.category || null,
keywords: d.keywords || [],
hidden: d.hidden ?? false,
isHiddenFromOverview: d.isHiddenFromOverview ?? false,
topDescription: d.usage?.description || d.description || '',
usage: d.usage ? sanitizeForJson(d.usage) : null,
theming: d.theming
? projectThemingDoc(sanitizeForJson(d.theming))
: null,
playground: d.playground ? sanitizeForJson(d.playground) : null,
stability: d.stability,
};
break;
}
} catch {
/* ignore */
}
}
for (const docFileName of docFiles) {
const docFile = path.join(dirPath, docFileName);
let doc;
try {
const mod = await import(pathToFileURL(docFile).href);
doc = mod.docs;
if (!doc) continue;
recordDocExampleOrder(doc);
} catch (err) {
console.warn(
` warn: failed to import ${docFileName}: ${err.message}`,
);
continue;
}
const group = doc.group || null;
const category = doc.category || null;
const isHiddenFromOverview = doc.isHiddenFromOverview ?? false;
const keywords = doc.keywords || [];
const hidden = doc.hidden ?? false;
const topDescription = doc.usage?.description || doc.description || '';
const usage = doc.usage ? sanitizeForJson(doc.usage) : null;
const theming = doc.theming
? projectThemingDoc(sanitizeForJson(doc.theming))
: null;
const registry = doc.registry ? sanitizeForJson(doc.registry) : null;
const playground = doc.playground
? sanitizeForJson(doc.playground)
: null;
if (doc.subComponentOf) {
// Extracted sub-component: lives in its parent's directory in its own
// .doc.mjs file. Inherits family fields (group, category, keywords,
// theming, playground, importPath) from the directory's primary doc
// unless the sub-component doc overrides them; owns its name,
// description, props, and usage. When no usage block is authored,
// use the sub-component description as the usage summary instead of
// inheriting parent prose. Produces a registry entry identical to the
// legacy inline `components[]` expansion.
const parentMeta = dirPrimaryMeta || {};
const subName = (doc.name || '').replace(/^XDS/, '');
if (subName) {
const isHookEntry =
subName.startsWith('use') ||
Array.isArray(doc.params) ||
Array.isArray(doc.returns);
pendingSubComponents.push({
name: subName,
displayName: requireDisplayName(
doc.displayName,
`${pkg.name}: subcomponent ${subName} (parent ${doc.subComponentOf})`,
),
moduleName: subName,
directory,
importPath: resolveImportPathForPkg(pkg.dir, directory),
group: parentMeta.group ?? group,
category: parentMeta.category ?? category,
isHiddenFromOverview:
doc.isHiddenFromOverview ??
parentMeta.isHiddenFromOverview ??
false,
description: doc.description || parentMeta.topDescription || '',
keywords: parentMeta.keywords ?? keywords,
hidden: parentMeta.hidden ?? hidden,
deprecated: deprecationOf(doc),
registry,
parentDoc: doc.subComponentOf,
props: isHookEntry
? []
: Array.isArray(doc.props)
? sanitizeForJson(doc.props)
: [],
usage: doc.usage
? sanitizeForJson(doc.usage)
: doc.description
? {description: doc.description}
: null,
theming: isHookEntry
? null
: doc.theming
? projectThemingDoc(sanitizeForJson(doc.theming))
: (parentMeta.theming ?? null),
params: isHookEntry
? Array.isArray(doc.params)
? sanitizeForJson(doc.params)
: Array.isArray(doc.props)
? sanitizeForJson(doc.props)
: []
: null,
returns: isHookEntry
? Array.isArray(doc.returns)
? sanitizeForJson(doc.returns)
: []
: null,
relatedComponents: isHookEntry
? doc.relatedComponents || [doc.subComponentOf]
: null,
relatedHooks: isHookEntry ? doc.relatedHooks || null : null,
playground: isHookEntry
? null
: doc.playground
? sanitizeForJson(doc.playground)
: (parentMeta.playground ?? null),
stability: componentStability(pkg.name, doc, parentMeta),
});
}
} else if (doc.components && doc.components.length > 0) {
// A family parent that also documents its own component surface (it has
// top-level props) is emitted as its own entry. Abstract families with
// no top-level props (e.g. Chat) contribute only their sub-components.
if (Array.isArray(doc.props) && doc.props.length > 0) {
const name =
doc.name ||
docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
standaloneNames.add(name);
components.push({
name,
displayName: requireDisplayName(
doc.displayName,
`${pkg.name}: component ${name}`,
),
moduleName: name,
directory,
importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
description: doc.description || topDescription,
keywords,
hidden,
deprecated: deprecationOf(doc),
registry,
parentDoc: name,
props: sanitizeForJson(doc.props),
usage,
theming,
params: null,
returns: null,
relatedComponents: null,
relatedHooks: null,
playground,
stability: componentStability(pkg.name, doc),
});
}
for (const sub of doc.components) {
const rawSubName = sub.name || '';
const subName = rawSubName.replace(/^XDS/, '');
if (!subName) continue;
const isHookEntry =
rawSubName.startsWith('use') ||
subName.startsWith('use') ||
Array.isArray(sub.params);
// Name-only entries are cross-link references to sub-components that
// have been extracted into their own sibling .doc.mjs files. Their
// content is emitted from those files (subComponentOf branch); skip
// here to avoid double emission.
const isNameOnlyRef =
Object.keys(sub).length === 1 && sub.name != null;
if (isNameOnlyRef) continue;
// Sub-entries whose name differs from the doc name are
// sub-components — hide them from the overview page.
const isSubEntry = subName !== doc.name;
// Each sub-component may have its own usage; fall back to
// the parent doc's usage only when the sub doesn't define one.
// Hook entries should read as hook docs, not as the parent component,
// so use the hook description as the usage summary when no explicit
// usage block is authored.
const subUsage = sub.usage
? sanitizeForJson(sub.usage)
: isHookEntry && sub.description
? {description: sub.description}
: usage;
const params = isHookEntry
? Array.isArray(sub.params)
? sanitizeForJson(sub.params)
: Array.isArray(sub.props)
? sanitizeForJson(sub.props)
: []
: null;
const returns = isHookEntry
? Array.isArray(sub.returns)
? sanitizeForJson(sub.returns)
: []
: null;
pendingSubComponents.push({
name: subName,
displayName: requireDisplayName(
sub.displayName,
`${pkg.name}: subcomponent ${sub.name || subName} (parent ${doc.name})`,
),
moduleName: sub.name || subName,
directory,
importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview:
sub.isHiddenFromOverview ?? isHiddenFromOverview,
description: sub.description || topDescription,
keywords,
hidden,
deprecated: null,
registry: sub.registry ? sanitizeForJson(sub.registry) : null,
parentDoc: doc.name,
props: isHookEntry
? []
: Array.isArray(sub.props)
? sanitizeForJson(sub.props)
: [],
usage: subUsage,
theming: isHookEntry ? null : theming,
params,
returns,
relatedComponents: isHookEntry
? sub.relatedComponents || (doc.name ? [doc.name] : null)
: null,
relatedHooks: isHookEntry ? sub.relatedHooks || null : null,
// Sub-components may declare their own playground (e.g. an
// overlay drawer whose sibling toggle must not inherit it);
// fall back to the parent doc's playground otherwise — same
// override rule as extracted subComponentOf docs.
playground: isHookEntry
? null
: sub.playground
? sanitizeForJson(sub.playground)
: playground,
stability: componentStability(pkg.name, sub, doc),
});
}
} else if (doc.params) {
// HookDoc — parent to the component doc in the same directory
const name = doc.name || docFileName.replace('.doc.mjs', '');
standaloneNames.add(name);
components.push({
name,
displayName: requireDisplayName(
doc.displayName,
`${pkg.name}: hook ${name}`,
),
moduleName: name,
directory,
importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
description: topDescription,
keywords,
hidden,
deprecated: null,
registry,
parentDoc: dirPrimaryDoc,
props: [],
usage,
theming: null,
params: Array.isArray(doc.params)
? sanitizeForJson(doc.params)
: [],
returns: Array.isArray(doc.returns)
? sanitizeForJson(doc.returns)
: [],
relatedComponents: doc.relatedComponents || null,
relatedHooks: doc.relatedHooks || null,
playground: null,
stability: componentStability(pkg.name, doc),
});
} else {
// Simple/standalone component
const name =
doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
standaloneNames.add(name);
components.push({
name,
displayName: requireDisplayName(
doc.displayName,
`${pkg.name}: component ${name}`,
),
moduleName: name,
directory,
importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
description: topDescription,
keywords,
hidden,
deprecated: deprecationOf(doc),
registry,
parentDoc: null,
props: Array.isArray(doc.props) ? sanitizeForJson(doc.props) : [],
usage,
theming,
params: null,
returns: null,
relatedComponents: null,
relatedHooks: null,
playground,
stability: componentStability(pkg.name, doc),
});
}
}
}
for (const sub of pendingSubComponents) {
if (!standaloneNames.has(sub.name)) {
standaloneNames.add(sub.name);
components.push(sub);
}
}
// Surface the shape of non-primitive types (issue #2682): when a
// documented prop, hook parameter, or hook return type references a named
// type exported from this package's source (e.g. `SearchSource<T>`,
// `ToastOptions`), record the reference on the row and attach the
// extracted declaration to the entry so the docs table can render it on
// demand.
const typeIndex = buildTypeDefinitionIndex(
pkg.srcDir,
path.relative(CONTENT_ROOT, pkg.srcDir),
);
for (const comp of components) {
comp.isReady = !pkg.canaryOnly;
const referenced = new Map();
const rows = [
...comp.props,
...(comp.params ?? []),
...(comp.returns ?? []),
];
for (const row of rows) {
const typeRefs = collectPropTypeRefs(row.type, typeIndex);
if (typeRefs.length > 0) {
row.typeRefs = typeRefs;
for (const name of typeRefs) {
referenced.set(name, typeIndex.get(name));
}
}
}
comp.typeDefs = [...referenced.values()].sort((a, b) =>
a.name.localeCompare(b.name),
);
}
components.sort((a, b) => a.name.localeCompare(b.name));
if (components.length > 0) {
allComponents[pkg.name] = components;
totalCount += components.length;
}
}
const componentOwners = new Map();
for (const [packageName, entries] of Object.entries(allComponents)) {
for (const entry of entries) {
const owner = componentOwners.get(entry.name);
if (owner) {
throw new Error(
`Duplicate component name "${entry.name}" in ${owner} and ${packageName}. Component routes must be globally unique.`,
);
}
componentOwners.set(entry.name, packageName);
}
}
// A deprecated component's notice links its replacement, so the replacement
// must be a documented component; its display name labels the link.
const entriesByName = new Map(
Object.values(allComponents)
.flat()
.map(entry => [entry.name, entry]),
);
for (const entry of entriesByName.values()) {
if (!entry.deprecated) continue;
const replacement = entriesByName.get(entry.deprecated.replacement);
if (!replacement || replacement.deprecated) {
throw new Error(
`${entry.name} is deprecated in favor of "${entry.deprecated.replacement}", which is not a documented, non-deprecated component. Set \`deprecated.replacement\` to the \`name\` of the component to use instead.`,
);
}
entry.deprecated.replacementDisplayName = replacement.displayName;
}
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {
ComponentPlaygroundConfig,
ComponentSlotElement,
} from '@astryxdesign/cli/authoring';
export interface PropDoc {
name: string;
type: string;
description: string;
default?: string;
required?: boolean;
slotElements?: ElementDescriptor[];
/** \`'experimental'\` for a prop outside the stable compatibility promise. */
stability?: 'experimental';
/** Names of package-exported types referenced by \`type\`, resolvable
* against the owning entry's \`typeDefs\`. */
typeRefs?: string[];
}
export interface TypeDefinition {
/** Exported type name, e.g. \`SearchSource\`. */
name: string;
/** Extracted TypeScript declaration source, including member JSDoc. */
definition: string;
/** Repo-relative source file, e.g. \`packages/core/src/Typeahead/types.ts\`. */
sourcePath: string;
}
export interface BestPractice {
guidance: boolean;
description: string;
}
export interface AccessibilityRequirement {
name: string;
description: string;
category?: 'Color contrast' | 'Keyboard' | 'Semantics' | 'Content';
criterion?: string;
requirement?: string;
states?: string[];
}
export type AccessibilityThemeStatus = 'Pass' | 'Fail' | 'Not tested';
export type AccessibilityThemeApplicability =
| 'Required'
| 'Conditional'
| 'Supplemental'
| 'Decorative';
export interface AccessibilityThemeMeasurement {
label: string;
value: string;
detail?: string;
applicability?: AccessibilityThemeApplicability;
colorPair?: {
foreground: string;
background: string;
};
breakdown?: Array<{
label: string;
value: string;
detail?: string;
colorPair: {
foreground: string;
background: string;
};
status?: 'Pass' | 'Fail';
}>;
status?: 'Pass' | 'Fail';
}
export interface AccessibilityThemeResult {
name: string;
measurements: AccessibilityThemeMeasurement[];
status: AccessibilityThemeStatus;
}
export interface AccessibilityThemeMode {
mode: 'Light' | 'Dark';
results: AccessibilityThemeResult[];
}
export interface AccessibilityThemeTable {
title?: string;
description?: string;
modes: AccessibilityThemeMode[];
}
export interface AccessibilityThemeCoverage {
theme: string;
tables: AccessibilityThemeTable[];
notMeasured?: string[];
}
export interface AnatomyElement {
name: string;
required: boolean;
description: string;
}
export interface UsageDoc {
description: string;
bestPractices?: BestPractice[];
anatomy?: AnatomyElement[];
features?: string[];
accessibility?: AccessibilityRequirement[];
accessibilityThemeCoverage?: AccessibilityThemeCoverage[];
keyboard?: string;
notes?: string[];
}
export interface ThemingTarget {
className: string;
visualProps?: string[];
states?: string[];
}
export interface ComponentVar {
name: string;
description: string;
default: string;
derived?: boolean;
formula?: string;
private?: boolean;
}
export interface DerivedVar {
property: string;
vars?: string[];
expand?: 'container';
/** Emit only the vars, dropping the source property from the rule. */
replaces?: boolean;
}
export interface ComponentIconSlotState {
name: string;
type: string;
description: string;
}
export interface ComponentIconSlot {
slot: string;
description: string;
fallback: string;
state?: ComponentIconSlotState[];
whenNull: string;
}
export interface ThemingDoc {
container?: boolean;
targets: ThemingTarget[];
vars?: ComponentVar[];
derived?: DerivedVar[];
componentIcons?: ComponentIconSlot[];
}
export interface HookParamDoc {
name: string;
type: string;
description: string;
default?: string;
required?: boolean;
/** Names of package-exported types referenced by \`type\`, resolvable
* against the owning entry's \`typeDefs\`. */
typeRefs?: string[];
}
export interface HookReturnDoc {
name: string;
type: string;
description: string;
/** Names of package-exported types referenced by \`type\`, resolvable
* against the owning entry's \`typeDefs\`. */
typeRefs?: string[];
}
export interface ComponentEntry {
/** Identifier name — matches the React component import name, e.g. \`AppShell\`. */
name: string;
/**
* Human-readable display name with spaces between words, e.g.
* \`Aspect Ratio\` for the \`AspectRatio\` component. Derived from
* \`name\` by inserting spaces between PascalCase / camelCase words
* while preserving capitalization.
*/
displayName: string;
moduleName: string;
directory: string;
/** Resolved import path, e.g. \`@astryxdesign/core/Chat\`. Derived from package.json exports. */
importPath: string | null;
group: string | null;
/** Functional category for the overview gallery (Actions, Inputs, etc.) */
category: string | null;
/** Whether this component is hidden from the overview page. */
isHiddenFromOverview: boolean;
description: string;
keywords: string[];
hidden: boolean;
/** Whether this component is ready for the stable documentation line. */
isReady: boolean;
/** \`'lab'\` for a component of the Lab package (spec:AST-017 FR27),
* \`'experimental'\` for a surface whose doc, or whose family's doc,
* declares \`stability: 'experimental'\` (spec:AST-017 FR21), and null for
* a stable one. */
stability: 'experimental' | 'lab' | null;
/** What replaces a deprecated component, from its doc's \`deprecated\`;
* null when it is not deprecated. */
deprecated: ComponentDeprecation | null;
registry: {slug?: string; aliases?: string[]} | null;
parentDoc: string | null;
props: PropDoc[];
/** Declarations for every type referenced from \`props[]\`, \`params[]\`, or
* \`returns[]\` \`typeRefs\`. */
typeDefs: TypeDefinition[];
usage: UsageDoc | null;
theming: ThemingDoc | null;
params: HookParamDoc[] | null;
returns: HookReturnDoc[] | null;
relatedComponents: string[] | null;
relatedHooks: string[] | null;
playground: PlaygroundConfig | null;
}
export interface ComponentDeprecation {
/** \`name\` of the documented component to use instead. */
replacement: string;
/** That component's display name. */
replacementDisplayName: string;
/** The modernization route, in a sentence or two. */
description: string;
}
export type ElementDescriptor = ComponentSlotElement;
export type PlaygroundConfig = ComponentPlaygroundConfig;
export const components: Record<string, ComponentEntry[]> = ${JSON.stringify(allComponents, null, 2)};
export const componentCount = ${totalCount};
`;
writeRegistry('componentRegistry.ts', content);
return {allComponents, totalCount};
}
function generateComponentPreviewRegistry(allComponents) {
const packageNames = Object.keys(allComponents).filter(
packageName => packageName !== '@astryxdesign/core',
);
const entries = packageNames
.flatMap(packageName =>
allComponents[packageName].map(
component =>
` ${JSON.stringify(component.name)}: namedLazy(${JSON.stringify(component.name)}, () => import(${JSON.stringify(packageName)}).then(module => module.${component.moduleName} as PreviewComponent)),`,
),
)
.join('\n');
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
import {lazy, type ComponentType} from 'react';
type PreviewComponent = ComponentType<any>;
type NamedLazyComponent = PreviewComponent & {displayName?: string};
type PreviewImport = () => Promise<PreviewComponent>;
function namedLazy(name: string, load: PreviewImport): PreviewComponent {
const component = lazy(async () => ({default: await load()})) as NamedLazyComponent;
component.displayName = name;
return component;
}
export const externalComponentPreviews: Record<string, PreviewComponent> = {
${entries}
};
`;
writeRegistry('componentPreviewRegistry.ts', content);
}
/**
* Humanize a raw group label (a PascalCase component/group name) into a
* spaced display label, e.g. 'TopNav' -> 'Top Nav', 'Chat' -> 'Chat'.
* Used as the group label when no member's name exactly matches the group
* (so the label doesn't fall back to an arbitrary member's displayName like
* 'Chat Composer' for the 'Chat' group).
*/
function humanizeGroupLabel(label) {
if (/^\d+[A-Z]+$/.test(label)) {
return label;
}
return label
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
.trim();
}
function generateGroupedComponentRegistry(allComponents) {
console.log('Generating grouped component registry...');
const results = {};
for (const [pkgName, entries] of Object.entries(allComponents)) {
const utilities = [];
const groups = new Map();
const ungrouped = [];
const parentDocsWithComponents = new Set();
for (const e of entries) {
if (e.parentDoc && !e.name.startsWith('use') && !e.hidden) {
parentDocsWithComponents.add(e.parentDoc);
}
}
for (const entry of entries) {
if (entry.hidden) continue;
const isHook = entry.name.startsWith('use');
// entry.displayName is required upstream (see ComponentEntry generation
// — requireDisplayName throws if missing), so no fallback is needed.
const {displayName} = entry;
if (
entry.group === 'Utilities' ||
(isHook && !entry.parentDoc && entry.directory === 'hooks')
) {
utilities.push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
});
continue;
}
if (entry.group) {
if (!groups.has(entry.group)) groups.set(entry.group, []);
groups.get(entry.group).push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
description: entry.description,
});
continue;
}
if (isHook && !entry.parentDoc && entry.directory !== 'hooks') {
const dir = entry.directory;
if (!groups.has(dir)) groups.set(dir, []);
groups.get(dir).push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
description: entry.description,
});
continue;
}
if (
isHook &&
entry.parentDoc &&
parentDocsWithComponents.has(entry.parentDoc)
) {
const parent = entry.parentDoc;
if (!groups.has(parent)) groups.set(parent, []);
groups.get(parent).push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
description: entry.description,
});
continue;
}
if (isHook) {
utilities.push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
});
continue;
}
ungrouped.push({
name: entry.name,
displayName,
href: `/components/${entry.name}`,
description: entry.description,
});
}
const items = [];
for (const [label, members] of groups) {
members.sort((a, b) => a.name.localeCompare(b.name));
if (members.length === 1) {
items.push({
sortKey: members[0].name,
item: {
type: 'entry',
name: members[0].name,
displayName: members[0].displayName,
href: members[0].href,
description: members[0].description,
},
});
} else {
const canonical = members.find(m => m.name === label);
// Prefer the canonical member's already-required displayName as the
// group label. When no member's name matches the group label (e.g. the
// 'Chat' group has no component literally named 'Chat'), humanize the
// raw label instead of falling back to an arbitrary member's
// displayName (which produced labels like 'Chat Composer').
const groupDisplayName = canonical
? canonical.displayName
: humanizeGroupLabel(label);
items.push({
sortKey: label,
item: {
type: 'group',
label,
displayName: groupDisplayName,
description: (canonical || members[0]).description,
entries: members.map(m => ({
name: m.name,
displayName: m.displayName,
href: m.href,
})),
},
});
}
}
for (const entry of ungrouped) {
items.push({
sortKey: entry.name,
item: {
type: 'entry',
name: entry.name,
displayName: entry.displayName,
href: entry.href,
description: entry.description,
},
});
}
items.sort((a, b) => a.sortKey.localeCompare(b.sortKey));
results[pkgName] = {
items: items.map(i => i.item),
utilities: utilities.sort((a, b) => a.name.localeCompare(b.name)),
};
}
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface GroupedEntry {
type: 'entry';
/** Identifier name — matches the React component import name. */
name: string;
/** Human-readable display name with spaces between camelCased words. */
displayName: string;
href: string;
description: string;
}
export interface GroupedGroup {
type: 'group';
/** Raw group label (the component name acting as parent). */
label: string;
/** Human-readable version of \`label\` with spaces between camelCased words. */
displayName: string;
description: string;
entries: Array<{name: string; displayName: string; href: string}>;
}
export type ComponentItem = GroupedEntry | GroupedGroup;
export interface GroupedComponents {
items: ComponentItem[];
utilities: Array<{name: string; displayName: string; href: string}>;
}
export const groupedComponents: Record<string, GroupedComponents> = ${JSON.stringify(results, null, 2)};
`;
writeRegistry('groupedComponentRegistry.ts', content);
return Object.keys(results).length;
}
// ── 3. Block Registry ──────────────────────────────────────────────────
/** The authored file of each integration block, by block `dirName`. */
const integrationBlockFiles = new Map();
async function generateBlockRegistry() {
console.log('Generating block registry...');
const BLOCKS_DIR = path.join(CLI_ROOT, 'assets', 'templates', 'blocks');
const docFiles = findDocFilesRecursive(BLOCKS_DIR);
const blocks = [];
for (const docPath of docFiles) {
const basename = path.basename(docPath, '.doc.mjs');
const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
if (!fs.existsSync(tsxPath)) continue;
const meta = readDocMeta(docPath);
const relCategory = path.relative(BLOCKS_DIR, path.dirname(docPath));
// Read isShowcase, aspectRatio, componentsUsed, exampleFor from the doc file
let isShowcase = false;
let aspectRatio = 1;
let componentsUsed = [];
let exampleFor = null;
let alsoExampleFor = [];
let alsoShowcaseFor = [];
let registry = null;
try {
const content = fs.readFileSync(docPath, 'utf-8');
isShowcase = /isShowcase:\s*true/.test(content);
const arMatch = content.match(/aspectRatio:\s*([\d.]+)\s*\/\s*([\d.]+)/);
const arSingle = content.match(/aspectRatio:\s*([\d.]+)(?!\s*\/)/);
if (arMatch) {
aspectRatio = parseFloat(arMatch[1]) / parseFloat(arMatch[2]);
} else if (arSingle) {
aspectRatio = parseFloat(arSingle[1]);
}
const cuMatch = content.match(/componentsUsed:\s*\[([^\]]*)\]/);
if (cuMatch) {
componentsUsed = [...cuMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map(
m => m[1],
);
}
const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);
if (efMatch) {
exampleFor = efMatch[1];
}
alsoExampleFor = extractStringArrayField(content, 'alsoExampleFor');
alsoShowcaseFor = extractStringArrayField(content, 'alsoShowcaseFor');
const module = await import(pathToFileURL(docPath).href);
registry = module.doc?.registry
? sanitizeForJson(module.doc.registry)
: null;
} catch {
/* ignore */
}
if (isShowcase && !exampleFor) {
throw new Error(
`Block ${path.relative(REPO_ROOT, docPath)} sets isShowcase without exampleFor`,
);
}
let source = '';
try {
source = fs.readFileSync(tsxPath, 'utf-8');
} catch {
/* ignore */
}
// Displayed source: the Code tab, Open in Playground, and the MCP server
// show each demo-content element as the placeholder a copy writes, and keep
// fixture media. The live preview renders the original file (see
// writeBlockPreview). A use that cannot be replaced safely fails the build.
source = replaceDemoContent(source).source;
const resolvedName = meta.name || basename;
blocks.push({
dirName: basename,
name: resolvedName,
// Human-readable display name for gallery + sidebar UI. Required —
// every doc file must declare an explicit `displayName` so authors
// stay in control of how each component reads in the UI (rather
// than relying on a build-time regex derivation).
displayName: requireDisplayName(
meta.displayName,
`block ${path.relative(REPO_ROOT, docPath)}`,
),
description: meta.description,
exampleFor,
alsoExampleFor,
alsoShowcaseFor,
isShowcase,
registry,
aspectRatio,
componentsUsed,
category: relCategory,
source,
});
}
// Showcase blocks are executable content: like Core's CLI templates they are
// live-rendered from the workspace install (see resolve-content-root.mjs),
// filtered to the integration packages this build documents.
if (CONFIGURED_COMPONENT_PACKAGES.size > 0) {
const templateList = await queryTemplates(undefined, {
list: true,
type: 'block',
cwd: DOCSITE_ROOT,
});
const integrationBlocks = templateList.data.filter(entry =>
CONFIGURED_COMPONENT_PACKAGES.has(entry.package),
);
const discovered = await discoverAll(DOCSITE_ROOT);
for (const entry of integrationBlocks) {
const shown = await queryTemplates(entry.id, {
show: true,
type: 'block',
package: entry.package,
cwd: DOCSITE_ROOT,
});
const dirName = `${entry.package}-${entry.id}`.replace(
/[^a-zA-Z0-9_-]/g,
'-',
);
const authored = discovered.find(
t =>
t.type === 'block' &&
t.dirName === entry.id &&
pkgOf(t) === entry.package,
);
if (!authored) throw new Error(`No authored file for ${dirName}`);
integrationBlockFiles.set(dirName, authored.filePath);
blocks.push({
dirName,
name: entry.name,
displayName: entry.displayName || entry.name,
description: entry.description,
exampleFor: entry.exampleFor || null,
alsoExampleFor: entry.alsoExampleFor ?? [],
alsoShowcaseFor: entry.alsoShowcaseFor ?? [],
isShowcase: entry.isShowcase ?? false,
registry: entry.registry ?? null,
aspectRatio: entry.aspectRatio ?? 1,
componentsUsed: entry.componentsUsed ?? [],
category: entry.category || entry.package,
source: shown.data.source,
sourcePackage: entry.package,
});
}
}
blocks.sort((a, b) => a.name.localeCompare(b.name));
const showcaseCount = blocks.filter(b => b.isShowcase).length;
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface BlockEntry {
dirName: string;
/** Identifier name — matches the React component import name (PascalCase). */
name: string;
/**
* Human-readable display name with spaces between words, e.g.
* "Chat Message Metadata" for the "ChatMessageMetadata" component.
* Falls back to a prettified version of \`name\` when no explicit
* displayName is declared on the doc file.
*/
displayName: string;
description: string;
/** Optional component ownership. Null means a standalone block. */
exampleFor: string | null;
alsoExampleFor: string[];
alsoShowcaseFor: string[];
isShowcase: boolean;
registry: {slug?: string; aliases?: string[]} | null;
aspectRatio: number;
componentsUsed: string[];
/** Category path, e.g. 'components/Button' */
category: string;
/** Raw TSX source code for live rendering */
source: string;
/** Owning integration package for library-owned blocks. */
sourcePackage?: string;
}
export const blocks: BlockEntry[] = ${JSON.stringify(blocks, null, 2)};
export const blockCount = ${blocks.length};
export const showcaseCount = ${showcaseCount};
`;
writeRegistry('blockRegistry.ts', content);
return {blocks, blockCount: blocks.length, showcaseCount};
}
// ── 4. Template Registry ───────────────────────────────────────────────
async function generateTemplateRegistry() {
console.log('Generating template registry...');
const PAGES_DIR = path.join(CLI_ROOT, 'assets', 'templates', 'pages');
if (!fs.existsSync(PAGES_DIR)) {
writeRegistry(
'templateRegistry.ts',
`// Auto-generated — no templates found\nexport const templates = [];\nexport const templateCount = 0;\n`,
);
writeRegistry(
'templateMetadataRegistry.ts',
`// Auto-generated — no templates found\nexport const templateMetadata = [];\nexport const templateMetadataCount = 0;\n`,
);
return {templates: [], templateCount: 0};
}
const templates = [];
const dirs = fs
.readdirSync(PAGES_DIR, {withFileTypes: true})
.filter(e => e.isDirectory());
for (const dir of dirs) {
const docPath = path.join(PAGES_DIR, dir.name, 'template.doc.mjs');
if (!fs.existsSync(docPath)) continue;
const pagePath = path.join(PAGES_DIR, dir.name, 'page.tsx');
if (!fs.existsSync(pagePath)) continue;
let doc;
try {
const mod = await import(
fileURLToPath(new URL(`file://${docPath}`)).replace(/\\/g, '/')
);
doc = mod.doc;
} catch {
const meta = readDocMeta(docPath);
doc = {
name: meta.name || dir.name,
description: meta.description,
isReady: true,
};
}
// Skip scaffolds — these are starter templates, not showcases
if (doc.scaffold) continue;
let source = '';
try {
source = fs.readFileSync(pagePath, 'utf-8');
} catch {
/* ignore */
}
// Displayed source, like each block's: the playground and the MCP server
// hand out the demo-content replacement a copy applies, with fixture media.
source = replaceDemoContent(source).source;
templates.push({
slug: dir.name,
name: doc.name || dir.name,
description: doc.description || '',
isReady: doc.isReady ?? true,
category: doc.category || '',
isHiddenFromOverview: doc.isHiddenFromOverview ?? false,
registry: doc.registry ? sanitizeForJson(doc.registry) : null,
source,
});
}
templates.sort((a, b) => a.name.localeCompare(b.name));
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface TemplateEntry {
slug: string;
name: string;
description: string;
isReady: boolean;
/** Functional category, e.g. 'Dashboard - Analytics'. Empty when untagged.
* The overview groups by the part before ' - '. */
category: string;
/** When true, hide from the Templates overview gallery (still CLI-available). */
isHiddenFromOverview: boolean;
registry: {slug?: string; aliases?: string[]} | null;
source: string;
}
export const templates: TemplateEntry[] = ${JSON.stringify(templates, null, 2)};
export const templateCount = ${templates.length};
`;
writeRegistry('templateRegistry.ts', content);
const templateMetadata = templates.map(
({source: _source, ...metadata}) => metadata,
);
const metadataContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface TemplateMetadataEntry {
slug: string;
name: string;
description: string;
isReady: boolean;
/** Functional category, e.g. 'Dashboard - Analytics'. Empty when untagged.
* The overview groups by the part before ' - '. */
category: string;
/** When true, hide from the Templates overview gallery (still CLI-available). */
isHiddenFromOverview: boolean;
registry: {slug?: string; aliases?: string[]} | null;
}
export const templateMetadata: TemplateMetadataEntry[] = ${JSON.stringify(templateMetadata, null, 2)};
export const templateMetadataCount = ${templateMetadata.length};
`;
writeRegistry('templateMetadataRegistry.ts', metadataContent);
return {templates, templateCount: templates.length};
}
// ── 5. Docs Registry ──────────────────────────────────────────────────
/**
* The docsite pages of the CLI's docs tree, read through the CLI's public docs
* API. Every root namespace is one full page at its own slug (docs-pages.mjs),
* so splitting a flat topic into a namespace keeps its URL, sidebar spot and
* text; the guides under it redirect to their sections on that page. A nested
* namespace in NESTED_NAMESPACE_PAGES is a page of its own instead, under its
* root's page in the sidebar. A root namespace in GUIDE_PAGE_NAMESPACES shows
* the pages GUIDE_NAMESPACE_PAGES lists, the same way one level down, and its
* other guides keep a page each.
*/
async function docsTreePages() {
const pages = [];
const redirects = {};
// Every route the tree has. A reference to a route without a page of its
// own (a command or API doc) still opens it in `astryx docs`.
const routes = [];
const list = await readDocs();
const pending = [];
// Routes a page of a GUIDE_PAGE_NAMESPACES root holds, so their guides get
// no page of their own.
const held = new Set();
for (const {topic: root} of list.meta?.namespaces ?? []) {
if (GUIDE_PAGE_NAMESPACES.has(root)) {
pending.push(root);
for (const spec of GUIDE_NAMESPACE_PAGES.get(root) ?? []) {
for (const route of await treeRoutes(spec.route)) held.add(route);
const full = await namespacePage(readDocs, spec.route, spec);
if (!full) continue;
pages.push(full.page);
Object.assign(redirects, full.redirects);
}
continue;
}
routes.push(...(await treeRoutes(root)));
const {root: full, nested} = await rootNamespacePages(readDocs, root, {
aliases: ROOT_PAGE_ALIASES.get(root) ?? [],
});
for (const page of nested) {
pages.push(page.page);
Object.assign(redirects, page.redirects);
}
if (!full) continue;
pages.push(full.page);
Object.assign(
redirects,
full.redirects,
movedGuideRedirects(root, full.redirects),
);
}
while (pending.length > 0) {
const route = pending.shift();
routes.push(route);
const read = await readDocs(route);
if (read.type !== 'docs.node') continue;
for (const slot of read.data.slots) {
for (const child of slot.children) {
if (child.kind !== 'namespace') routes.push(child.route);
if (child.kind === 'namespace') {
pending.push(child.route);
} else if (
child.kind === 'generic' &&
child.route.includes('/') &&
!held.has(child.route)
) {
const doc = (await readDocs(child.route)).data;
pages.push({
topic: routeSlug(child.route),
title: doc.title || child.title,
description: doc.description || '',
category: doc.category || null,
sections: doc.sections || [],
});
}
}
}
}
return {pages, redirects, routes};
}
/**
* Every route at or below a docs-tree node.
* @param {string} route
* @returns {Promise<string[]>}
*/
async function treeRoutes(route) {
const read = await readDocs(route, undefined, {depth: 'all'});
const routes = [route];
const walk = slots => {
for (const slot of slots ?? []) {
for (const child of slot.children) {
routes.push(child.route);
walk(child.slots);
}
}
};
if (read.type === 'docs.node') walk(read.data.slots);
return routes;
}
async function generateDocsRegistry() {
console.log('Generating docs registry...');
const DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
if (!fs.existsSync(DOCS_DIR)) {
writeRegistry(
'docsRegistry.ts',
`// Auto-generated — no docs found\nexport const docTopics = [];\nexport const docsCount = 0;\nexport const docsTreeRoutes = [];\nexport const docRedirects = {};\n`,
);
fs.writeFileSync(path.join(OUT_DIR, 'docRedirects.json'), '{}\n');
return {docTopics: [], docsCount: 0};
}
const docTopics = [];
for (const file of fs.readdirSync(DOCS_DIR)) {
const match = file.match(/^([\w-]+)\.doc\.mjs$/);
if (!match) continue;
// Skip translations
if (file.includes('.doc.zh.') || file.includes('.doc.dense.')) continue;
const topic = match[1];
if (DOCSITE_TARGET !== 'canary' && topic === 'shadcn-compatibility') {
continue;
}
const docPath = path.join(DOCS_DIR, file);
let title = '';
let description = '';
let category = '';
let sections = [];
try {
const mod = await import(`file://${docPath}`);
title = mod.docs?.title || '';
description = mod.docs?.description || '';
category = mod.docs?.category || '';
sections = mod.docs?.sections || [];
} catch {
const meta = readDocMeta(docPath);
description = meta.description;
}
if (sections.length > 0) {
// Read the sections through the CLI's docs API, so each link between
// docs (`{@link <target>}`) reads as the command that opens its doc, as
// it does in `astryx docs`. Only the CLI's own topics are read here, so
// the read runs from the CLI package. The docsite renders token tables
// itself, so a resolved token reference is not copied into the registry.
const read = await readDocs(topic, undefined, {cwd: CLI_ROOT});
sections = withoutResolvedTokens(read.data.sections);
}
docTopics.push({
topic,
title: title || topic,
description,
category: category || null,
sections,
});
}
// Flat topics shown on another topic's page, or kept only as data.
const merged = mergeFlatTopics(docTopics);
docTopics.splice(0, docTopics.length, ...merged.topics);
// Guides the CLI's docs tree places (spec:AST-046) are not topic files: the
// CLI reads them only by route. A root namespace is one full page at its
// slug (a former flat topic keeps its URL), and each guide under it
// redirects to its section there. Guides under GUIDE_PAGE_NAMESPACES keep a
// flat page whose slug is the route with "/" as "-", so
// `cli/component-lookups` is /docs/cli-component-lookups.
const tree = await docsTreePages();
for (const page of tree.pages) {
if (docTopics.some(topic => topic.topic === page.topic)) {
throw new Error(
`docs: "${page.topic}" is both a flat topic and a docs-tree page. Remove the flat topic file when its namespace replaces it.`,
);
}
docTopics.push(page);
}
applySidebarParents(docTopics);
const docsTreeRoutes = [...new Set(tree.routes)].sort();
const docRedirects = Object.fromEntries(
Object.entries({...merged.redirects, ...tree.redirects}).sort(([a], [b]) =>
a.localeCompare(b),
),
);
for (const slug of Object.keys(docRedirects)) {
if (docTopics.some(topic => topic.topic === slug)) {
throw new Error(`docs: "${slug}" is both a page and a redirect.`);
}
}
docTopics.sort((a, b) => a.topic.localeCompare(b.topic));
// Docs write commands as bare `astryx ...`. The site shows them as
// `npx @astryxdesign/cli ...`, which runs before any install, and as plain
// `astryx ...` on the global mode page, whose readers installed it. Each is
// a docsite door name, and goes through the CLI's picker like any other.
const cliStem = runWithCliDoor(DOCSITE_CLI_COMMAND, () =>
getCliInvocation(DOCSITE_ROOT),
);
const globalStem = runWithCliDoor(GLOBAL_PAGE_CLI_COMMAND, () =>
getCliInvocation(DOCSITE_ROOT),
);
for (const topic of docTopics) {
const stem = topic.topic === GLOBAL_PAGE ? globalStem : cliStem;
topic.sections = withCliCommands(
topic.sections,
(text, lang = null) =>
// The CLI rendered the doc tokens as it compiled the doc (for npm,
// under runWithDocPackageManager below), so only bare commands are
// prefixed here.
prefixCliCommands(text, stem, lang),
stem,
);
}
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
export interface ContentBlock {
type: string;
text?: string;
code?: string;
lang?: string;
label?: string;
level?: number;
headers?: string[];
rows?: string[][];
items?: string[];
style?: string;
topic?: string;
section?: string;
}
export interface DocSection {
/** Stable key readers address the section by: astryx docs <topic> <id>. */
id?: string;
title: string;
/** The npm package that wrote the section, as the CLI's docs read names it. */
package?: string;
content: ContentBlock[];
previewType?: string;
category?: string;
}
export interface DocTopic {
/** URL-friendly slug derived from filename (e.g. 'getting-started') */
topic: string;
/** Display title from docs.title (e.g. 'Getting Started') */
title: string;
/** Short description */
description: string;
/** Navigation category: 'guide' | 'foundations' | null */
category: string | null;
/** Slug of the page the sidebar shows this page under, if any */
parent?: string;
/** Full doc sections with content blocks */
sections: DocSection[];
}
export const docTopics: DocTopic[] = ${JSON.stringify(docTopics, null, 2)};
export const docsCount = ${docTopics.length};
/** Every route of the CLI's docs tree. A route with no page or redirect here
* (a command or API doc) opens only in \`astryx docs\`. */
export const docsTreeRoutes: string[] = ${JSON.stringify(docsTreeRoutes, null, 2)};
/** Slugs that are not pages of their own, each to where its text is shown: a
* guide under a namespace page, or a flat topic merged into another page.
* next.config.mjs serves them as redirects. */
export const docRedirects: Record<string, string> = ${JSON.stringify(docRedirects, null, 2)};
`;
writeRegistry('docsRegistry.ts', content);
fs.writeFileSync(
path.join(OUT_DIR, 'docRedirects.json'),
`${JSON.stringify(docRedirects, null, 2)}\n`,
);
return {docTopics, docsCount: docTopics.length};
}
/**
* The tables the search panel opens a CLI search result through
* (src/lib/searchLinks.mjs): this build's doc pages, redirects, section
* anchors, component and template pages, and the page each block shows on.
* The search API (app/api/search/route.ts) reads them.
*/
function generateSearchLinks({
docTopics,
allComponents,
templates,
blocks,
packages,
}) {
const docRedirects = JSON.parse(
fs.readFileSync(path.join(OUT_DIR, 'docRedirects.json'), 'utf-8'),
);
const tables = searchLinkTables({
docTopics,
docRedirects,
components: Object.values(allComponents)
.flat()
.map(c => c.name),
templates: templates.map(t => t.slug),
blocks,
// The package pages /docs/[topic] serves; theme packages show on /themes.
packagePages: packages
.map(p => p.name)
.filter(name => !name.startsWith('@astryxdesign/theme-'))
.map(name => name.replace('@astryxdesign/', '')),
sectionAnchors,
});
fs.writeFileSync(
path.join(OUT_DIR, 'searchLinks.json'),
`${JSON.stringify(tables)}\n`,
);
console.log(
` wrote ${path.relative(REPO_ROOT, path.join(OUT_DIR, 'searchLinks.json'))}`,
);
}
async function generateThemeRegistry(packages) {
console.log('Generating theme registry...');
const themePackages = packages.filter(p =>
p.name.startsWith('@astryxdesign/theme-'),
);
if (!themePackages.length) {
writeRegistry(
'themeRegistry.ts',
`// Auto-generated — no theme packages found
import type {DefinedTheme} from '@astryxdesign/core/theme';
export const themeObjects: Record<string, DefinedTheme> = {};
`,
);
// Empty CSS aggregator so the globals.css @import doesn't 404.
writeThemesCss('');
return 0;
}
const imports = themePackages
.map(p => {
const slug = p.name.replace('@astryxdesign/theme-', '');
const exportName = `${slug}Theme`;
return `import {${exportName}} from '${p.name}/built';`;
})
.join('\n');
const entries = themePackages
.map(p => {
const slug = p.name.replace('@astryxdesign/theme-', '');
return ` '${p.name}': ${slug}Theme,`;
})
.join('\n');
// The `/built` objects are tokens-only — component overrides are compiled into
// each theme's CSS file, not the JS object. Extract those overrides here at
// build time from the package's full (main) export. In Node the `use client`
// directive on defineTheme is ignored, so this import is safe; the values are
// plain string maps, so the generated file stays pure data and is safe to
// import from server components. They're re-attached to the built objects in
// `themeObjectsFull` for the theme editors/playground, which rebuild the theme
// at runtime and so need the overrides (e.g. display fonts) on the object.
const componentOverrides = {};
for (const p of themePackages) {
const slug = p.name.replace('@astryxdesign/theme-', '');
try {
const mod = await import(p.name);
const theme = mod[`${slug}Theme`];
if (theme?.components && Object.keys(theme.components).length > 0) {
componentOverrides[p.name] = theme.components;
}
} catch (err) {
console.warn(
` warn: could not extract components for ${p.name}: ${err.message}`,
);
}
}
const fullEntries = themePackages
.map(p => {
const slug = p.name.replace('@astryxdesign/theme-', '');
return ` '${p.name}': {...${slug}Theme, components: componentOverrides['${p.name}']},`;
})
.join('\n');
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {DefinedTheme} from '@astryxdesign/core/theme';
${imports}
export const themeObjects: Record<string, DefinedTheme> = {
${entries}
};
/**
* Component overrides extracted from each theme's full export (the /built
* objects above are tokens-only — their component styles live in CSS). Plain
* data, safe to import from server components.
*/
const componentOverrides: Record<string, DefinedTheme['components']> =
${JSON.stringify(componentOverrides, null, 2)
.split('\n')
.map((l, i) => (i === 0 ? l : ' ' + l))
.join('\n')};
/**
* Built theme objects with their component overrides re-attached. Used by the
* theme editors/playground, which serialize the theme over postMessage and
* rebuild it at runtime, so component overrides (e.g. display fonts) must live
* on the object rather than in a separate CSS file.
*/
export const themeObjectsFull: Record<string, DefinedTheme> = {
${fullEntries}
};
`;
writeRegistry('themeRegistry.ts', content);
// CSS aggregator — globals.css imports this single file so adding a
// new theme package no longer requires hand-editing globals.css.
const cssImports = themePackages
.map(p => `@import "${p.name}/theme.css";`)
.join('\n');
writeThemesCss(cssImports);
return themePackages.length;
}
// Writes the aggregated themes.css alongside the TS registries. It's
// imported once from globals.css and re-generated every time the theme
// package list changes.
function writeThemesCss(body) {
const outPath = path.join(OUT_DIR, 'themes.css');
const content = `/* Copyright (c) Meta Platforms, Inc. and affiliates. */
/* Auto-generated by scripts/generate-data.mjs — do not edit */
${body}
`;
fs.writeFileSync(outPath, content, 'utf-8');
console.log(` wrote ${path.relative(REPO_ROOT, outPath)}`);
}
// ── 7. Showcase Registry ───────────────────────────────────────────────
// Blocks are copied into the docsite and rendered via a live import, so they
// can only reference packages the docsite actually depends on. A block for a
// component whose package is not a docsite dependency (e.g. anything in
// `@astryxdesign/lab`, which is canary-only and deliberately not installed
// here) is authored and version-controlled in the CLI templates, but must be
// skipped from the docsite's live preview until its package becomes resolvable
// — otherwise `next build` fails on the unresolved import. The block source is
// still shown as code; it just has no rendered preview until, for example, the
// component is promoted to core.
const _docsiteDeps = (() => {
const pkg = JSON.parse(
fs.readFileSync(path.join(DOCSITE_ROOT, 'package.json'), 'utf-8'),
);
return {...pkg.dependencies, ...pkg.devDependencies};
})();
function importsPackageMissingFromDocsite(tsxSource) {
const imports = [
...tsxSource.matchAll(/from\s+['"](@astryxdesign\/[^'"/]+)/g),
].map(m => m[1]);
return imports.some(pkg => _docsiteDeps[pkg] == null);
}
function blockSourcePath(block) {
if (block.sourcePackage) {
return null;
}
return path.join(
CLI_ROOT,
'assets',
'templates',
'blocks',
block.category,
`${block.dirName}.tsx`,
);
}
function templateSourcePath(template) {
return path.join(
CLI_ROOT,
'assets',
'templates',
'pages',
template.slug,
'page.tsx',
);
}
function writeBlockPreview(block, outDir, basename) {
const destFile = `${basename}.tsx`;
const destination = path.join(outDir, destFile);
const sourcePath = blockSourcePath(block);
if (sourcePath) {
if (!fs.existsSync(sourcePath)) {
return null;
}
fs.copyFileSync(sourcePath, destination);
} else {
fs.writeFileSync(destination, block.source, 'utf8');
}
return destFile;
}
function generateShowcaseRegistry(blocks, availableRegistryPaths) {
console.log('Generating showcase registry...');
const SHOWCASE_OUT = path.join(OUT_DIR, 'showcases');
fs.rmSync(SHOWCASE_OUT, {recursive: true, force: true});
fs.mkdirSync(SHOWCASE_OUT, {recursive: true});
const entries = [];
for (const block of blocks) {
if (importsPackageMissingFromDocsite(block.source)) {
console.log(
` skipping showcase ${block.dirName} — imports a package not installed in the docsite`,
);
continue;
}
const identity = blockRegistryIdentity(
block.name,
block.exampleFor,
block.isShowcase,
block.registry,
);
const registryItemPath = availableRegistryPaths?.has(identity.path)
? identity.path
: null;
if (block.isShowcase && block.exampleFor) {
const basename = block.sourcePackage
? `integration-${block.dirName}`
: block.dirName;
const destFile = writeBlockPreview(block, SHOWCASE_OUT, basename);
if (destFile) {
entries.push({
exampleFor: block.exampleFor,
basename,
destFile,
registryItemPath,
});
}
}
for (const target of block.alsoShowcaseFor ?? []) {
const base = block.sourcePackage
? `integration-${block.dirName}`
: block.dirName;
const basename = `${base}__${target}`;
const destFile = writeBlockPreview(block, SHOWCASE_OUT, basename);
if (destFile) {
entries.push({
exampleFor: target,
basename,
destFile,
registryItemPath,
});
}
}
}
const seen = new Set();
const uniqueEntries = entries.filter(entry => {
if (seen.has(entry.exampleFor)) return false;
seen.add(entry.exampleFor);
return true;
});
const importLines = uniqueEntries
.map(
entry =>
` '${entry.exampleFor}': () => import('./showcases/${entry.basename}'),`,
)
.join('\n');
const itemPathLines = uniqueEntries
.filter(entry => entry.registryItemPath)
.map(
entry =>
` '${entry.exampleFor}': ${JSON.stringify(entry.registryItemPath)},`,
)
.join('\n');
const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {ComponentType} from 'react';
type ShowcaseLoader = () => Promise<{default: ComponentType}>;
export const showcaseRegistry: Record<string, ShowcaseLoader> = {
${importLines}
};
export const showcaseRegistryItemPaths: Record<string, string> = {
${itemPathLines}
};
`;
writeRegistry('showcaseRegistry.ts', registryContent);
console.log(
` copied ${entries.length} showcase files (${uniqueEntries.length} unique components)`,
);
return uniqueEntries.length;
}
// ── Main
// Example labels in authored order, per documented component or sub-component.
// A component page lists the example blocks named after those labels in the
// same order as its doc's `examples`, so the snippet list and the runnable
// demos read as one set; any other example blocks follow in name order.
const DOC_EXAMPLE_ORDER = new Map();
function recordDocExampleOrder(doc) {
const entries = [
doc,
...(Array.isArray(doc.components) ? doc.components : []),
];
for (const entry of entries) {
const name = (entry?.name || '').replace(/^XDS/, '');
if (!name || !Array.isArray(entry.examples)) continue;
const labels = entry.examples
.map(example => example?.label)
.filter(label => typeof label === 'string');
if (labels.length > 0) DOC_EXAMPLE_ORDER.set(name, labels);
}
}
/** Sorts one component's examples by its doc's example order (stable). */
function orderExamplesByDoc(component, examples) {
const labels = DOC_EXAMPLE_ORDER.get(component);
if (!labels) return examples;
const rank = name => {
const index = labels.indexOf(name);
return index === -1 ? labels.length : index;
};
return [...examples].sort((a, b) => rank(a.name) - rank(b.name));
}
function generateExampleRegistry(blocks, availableRegistryPaths) {
console.log('Generating example registry...');
const EXAMPLES_OUT = path.join(OUT_DIR, 'examples');
fs.rmSync(EXAMPLES_OUT, {recursive: true, force: true});
fs.mkdirSync(EXAMPLES_OUT, {recursive: true});
const entries = [];
for (const block of blocks) {
if (importsPackageMissingFromDocsite(block.source)) {
console.log(
` skipping example ${block.dirName} — imports a package not installed in the docsite`,
);
continue;
}
const identity = blockRegistryIdentity(
block.name,
block.exampleFor,
block.isShowcase,
block.registry,
);
const registryItemPath = availableRegistryPaths?.has(identity.path)
? identity.path
: null;
const base = block.sourcePackage
? `integration-${block.dirName}`
: block.dirName;
if (!block.isShowcase && block.exampleFor) {
const destFile = writeBlockPreview(block, EXAMPLES_OUT, base);
if (destFile) {
entries.push({
exampleFor: block.exampleFor,
basename: base,
anchorId: exampleAnchorId(block.dirName),
registryItemPath,
name: block.name || block.dirName,
description: block.description || '',
source: block.source,
});
}
}
for (const target of block.alsoExampleFor ?? []) {
const basename = `${base}__${target}`;
const destFile = writeBlockPreview(block, EXAMPLES_OUT, basename);
if (destFile) {
entries.push({
exampleFor: target,
basename,
anchorId: exampleAnchorId(block.dirName),
registryItemPath,
name: block.name || block.dirName,
description: block.description || `Example using ${target}.`,
source: block.source,
});
}
}
}
const grouped = {};
for (const entry of entries) {
if (!grouped[entry.exampleFor]) grouped[entry.exampleFor] = [];
grouped[entry.exampleFor].push(entry);
}
const componentLines = Object.entries(grouped)
.map(([component, examples]) => {
const exampleLines = orderExamplesByDoc(component, examples)
.map(
entry =>
` {name: ${JSON.stringify(entry.name)}, anchorId: ${JSON.stringify(entry.anchorId)}, description: ${JSON.stringify(entry.description)}, registryItemPath: ${JSON.stringify(entry.registryItemPath)}, source: ${JSON.stringify(entry.source)}, load: () => import('./examples/${entry.basename}')},`,
)
.join('\n');
return ` '${component}': [\n${exampleLines}\n ],`;
})
.join('\n');
const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {ComponentType} from 'react';
export interface ExampleEntry {
name: string;
anchorId: string;
description: string;
registryItemPath: string | null;
source: string;
load: () => Promise<{default: ComponentType}>;
}
export const exampleRegistry: Record<string, ExampleEntry[]> = {
${componentLines}
};
`;
writeRegistry('exampleRegistry.ts', registryContent);
console.log(
` copied ${entries.length} example blocks for ${Object.keys(grouped).length} components`,
);
return entries.length;
}
// ── 6. Blog Registry ───────────────────────────────────────────────────
async function generateBlogRegistry() {
console.log('Generating blog registry...');
const POSTS_DIR = path.join(DOCSITE_ROOT, 'src', 'content', 'blog', 'posts');
// Single source of truth for discovery + validation (shared with tests).
const {discoverPosts, collectTypes, collectTags, collectExampleAssets} =
await import(
pathToFileURL(path.join(DOCSITE_ROOT, 'src', 'lib', 'blog', 'posts.mjs'))
.href
);
// Local development and every draft/preview deployment use the canary target.
const includeDrafts = DOCSITE_TARGET === 'canary';
const posts = discoverPosts(POSTS_DIR, {includeDrafts});
// Test fixtures (spec:AST-033 FR22): canary-only posts that the post and
// plain-text routes serve but the index, feed and sitemap never list.
const FIXTURES_DIR = path.join(
DOCSITE_ROOT,
'src',
'content',
'blog',
'fixtures',
);
const fixturePosts = includeDrafts
? discoverPosts(FIXTURES_DIR, {includeDrafts: true})
: [];
for (const fixture of fixturePosts) {
if (posts.some(p => p.slug === fixture.slug)) {
throw new Error(
`Blog fixture "${fixture.slug}" has the same slug as a post`,
);
}
}
const types = collectTypes(posts);
const tags = collectTags(posts);
// Definitive facts about body images, scanned from public/blog/** at build
// time so ThemedImage never probes at runtime: which images have a
// "<name>.dark.<ext>" counterpart, and the natural size of every "@2x"
// image, which renders at half its pixel width. Paths are site-absolute
// URLs ("/blog/...").
const {darkImages, imageSizes} = collectBlogImages(
path.join(DOCSITE_ROOT, 'public'),
);
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {BlogPost, BlogPostType} from '../lib/blog/schema';
export const blogPosts: BlogPost[] = ${JSON.stringify(posts, null, 2)};
export const blogTypes: BlogPostType[] = ${JSON.stringify(types)};
export const blogTags: string[] = ${JSON.stringify(tags)};
export const blogPostCount = ${posts.length};
/**
* Test fixture posts (canary only): the post and plain-text routes serve them,
* but the index, feed and sitemap read only blogPosts.
*/
export const blogFixturePosts: BlogPost[] = ${JSON.stringify(fixturePosts, null, 2)};
/**
* Site-absolute paths of every dark-mode image variant found under
* public/blog (files named "<name>.dark.<ext>"). ThemedImage consults this to
* decide whether a body image has a dark counterpart — a definitive,
* build-time list rather than a runtime existence probe.
*/
export const blogDarkImages: string[] = ${JSON.stringify(darkImages, null, 2)};
/**
* Natural pixel size of every body image whose file name ends in "@2x"
* (before the extension and the optional ".dark" marker). ThemedImage renders
* such an image at half its pixel width, so a Retina screenshot shows the
* component at the size it really is on screen.
*/
export const blogImageSizes: Record<string, {width: number; height: number}> =
${JSON.stringify(imageSizes, null, 2)};
`;
writeRegistry('blogRegistry.ts', content);
// Each post's example assets, loaded on demand inside the preview frame
// that runs that post's live examples (spec:AST-033 FR22).
const assetEntries = [
...posts.map(p => ({slug: p.slug, dir: POSTS_DIR})),
...fixturePosts.map(p => ({slug: p.slug, dir: FIXTURES_DIR})),
]
.map(({slug, dir}) => ({slug, assets: collectExampleAssets(dir, slug)}))
.filter(({assets}) => assets.length > 0);
const assetLines = assetEntries.map(({slug, assets}) => {
const loaders = assets.map(({specifier, file}) => {
const target = path
.relative(OUT_DIR, file)
.replace(/\\/g, '/')
.replace(/\.(tsx?|jsx?)$/, '');
return ` ${JSON.stringify(specifier)}: () => import(${JSON.stringify(target)}),`;
});
return ` ${JSON.stringify(slug)}: {\n${loaders.join('\n')}\n },`;
});
writeRegistry(
'blogExampleAssets.ts',
`// Auto-generated by scripts/generate-data.mjs — do not edit
/**
* Each blog post's example assets, by post slug and then by the relative
* specifier its live examples import (spec:AST-033 FR22).
*/
export const blogExampleAssets: Record<
string,
Record<string, () => Promise<unknown>>
> = {
${assetLines.join('\n')}
};
`,
);
return {blogPostCount: posts.length, blogTypeCount: types.length};
}
function checkShadcnRouteLock(contracts, {allowSubset = false} = {}) {
const lockPath = path.join(
REPO_ROOT,
'internal',
'shadcn-registry',
'routes.lock.json',
);
const lock = {version: 1, items: contracts};
const serialized = `${JSON.stringify(lock, null, 2)}\n`;
if (process.env.UPDATE_SHADCN_ROUTE_LOCK === '1') {
if (allowSubset) {
throw new Error(
'Refusing to replace the complete ShadCN route lock from a production subset.',
);
}
fs.writeFileSync(lockPath, serialized, 'utf8');
console.log(` updated ${path.relative(REPO_ROOT, lockPath)}`);
return;
}
if (!fs.existsSync(lockPath)) {
throw new Error(
`Missing ${path.relative(REPO_ROOT, lockPath)}. Run UPDATE_SHADCN_ROUTE_LOCK=1 node apps/docsite/scripts/generate-data.mjs and review the public route contract.`,
);
}
const current = fs.readFileSync(lockPath, 'utf8');
if (allowSubset) {
const locked = new Map(
JSON.parse(current).items.map(contract => [contract.name, contract]),
);
for (const contract of contracts) {
if (
JSON.stringify(locked.get(contract.name)) !== JSON.stringify(contract)
) {
throw new Error(
`Production ShadCN route ${contract.path} is absent from or differs from the reviewed route lock.`,
);
}
}
return;
}
if (current !== serialized) {
throw new Error(
`Generated ShadCN names or routes changed. Preserve old paths with doc.registry.aliases, or intentionally refresh the reviewed lock with UPDATE_SHADCN_ROUTE_LOCK=1 node apps/docsite/scripts/generate-data.mjs.`,
);
}
}
async function main() {
console.log('Generating docsite data...\n');
const packages = generatePackageRegistry();
const themeCount = await generateThemeRegistry(packages);
const {allComponents, totalCount: componentCount} =
await generateComponentRegistry();
generateComponentPreviewRegistry(allComponents);
generateGroupedComponentRegistry(allComponents);
const {blocks, blockCount} = await generateBlockRegistry();
generatePackageStyles(packages, blocks, allComponents);
const {templates, templateCount} = await generateTemplateRegistry();
const {docTopics, docsCount} = await generateDocsRegistry();
generateSearchLinks({docTopics, allComponents, templates, blocks, packages});
const {blogPostCount} = await generateBlogRegistry();
const shadcnCounts = generateShadcnRegistryForTarget({
target: DOCSITE_TARGET,
outDir: path.join(DOCSITE_ROOT, 'public', 'shadcn'),
packages,
allComponents,
// The registries carry displayed source. A shadcn install is a copy, so it
// starts from the file as authored.
blocks: blocks.map(block => ({
...block,
authoredSourcePath:
blockSourcePath(block) ?? integrationBlockFiles.get(block.dirName),
})),
templates: templates.map(template => ({
...template,
authoredSourcePath: templateSourcePath(template),
})),
cliRoot: CLI_ROOT,
dependencyTag: DOCSITE_TARGET === 'canary' ? 'canary' : null,
externalDependencySpecs: registryExternalDependencySpecs(),
// Production installs the published packages, so an example that imports
// a name they lack waits for the release that adds it.
publishedImports:
DOCSITE_TARGET === 'latest'
? createPublishedImportJudge(CONTENT_ROOT, packages)
: null,
});
reportRegistrySkips(registrySkipNotices(shadcnCounts));
checkShadcnRouteLock(shadcnCounts.contracts, {
allowSubset: DOCSITE_TARGET === 'latest',
});
// `/r` stays unclaimed for a future Astryx-native registry.
fs.rmSync(path.join(DOCSITE_ROOT, 'public', 'r'), {
recursive: true,
force: true,
});
const shadcnUiItemPaths =
DOCSITE_TARGET === 'canary' ? shadcnCounts.itemPaths : undefined;
const showcaseCopied = generateShowcaseRegistry(blocks, shadcnUiItemPaths);
const examplesCopied = generateExampleRegistry(blocks, shadcnUiItemPaths);
const registryOrigin = resolveShadcnRegistryOrigin(process.env);
const registryIsPreview =
DOCSITE_TARGET === 'canary' &&
registryOrigin !== 'https://astryx.atmeta.com/shadcn';
writeRegistry(
'shadcnRegistry.ts',
`// Auto-generated — do not edit
export const shadcnRegistryOrigin = ${JSON.stringify(registryOrigin)};
export const shadcnRegistryIsPreview = ${registryIsPreview};
`,
);
console.log(`\nSummary:`);
console.log(` ${packages.length} packages`);
console.log(` ${componentCount} components`);
console.log(
` ${blockCount} blocks (${showcaseCopied} showcases, ${examplesCopied} examples)`,
);
console.log(` ${templateCount} templates`);
console.log(` ${docsCount} doc topics`);
console.log(` ${blogPostCount} blog posts`);
console.log(` ${themeCount} themes`);
console.log(
` ${shadcnCounts.total} ShadCN registry items ` +
`(${shadcnCounts.components} components, ${shadcnCounts.hooks} hooks, ` +
`${shadcnCounts.showcases} showcases, ${shadcnCounts.examples} examples, ` +
`${shadcnCounts.blocks} standalone blocks, ${shadcnCounts.pages} pages; ` +
`${shadcnCounts.skippedUnpublishedComponents} unpublished components, ` +
`${shadcnCounts.skippedUnpublishedBlocks} blocks, and ` +
`${shadcnCounts.skippedUnpublishedPages} pages skipped)`,
);
console.log('Done.');
}
// Every `{@pm}` step on the site reads as npm, whatever this checkout uses.
runWithDocPackageManager(DOCSITE_PACKAGE_MANAGER, main).catch(err => {
console.error(err);
process.exit(1);
});