Skip to content

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

TypeScript

feat(docsite): surface canary-only components (#5583)

Cindy Zhangea5705c0f956
diff --git a/.changeset/integration-owned-showcases.md b/.changeset/integration-owned-showcases.md
new file mode 100644
index 0000000000..a7305b484a
--- /dev/null
+++ b/.changeset/integration-owned-showcases.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Preserve block showcase metadata from CLI integrations so packages can ship their own docsite previews. Charts now includes its primary bar-chart showcase alongside the package.
+
+@cixzhang
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 303435c2dd..5d50cb9589 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -89,13 +89,24 @@ jobs:
if: needs.check-scope.outputs.spec_only == 'true'
run: node scripts/check-knowledge.mjs
- # docsite `generate` runs `astryx theme build`, which imports the compiled
+ # Docsite `generate` runs `astryx theme build`, which imports the compiled
# @astryxdesign/core/theme entry (dist/theme/index.js). Build core first so that
# entry exists — otherwise generate fails with "Cannot find module".
- name: Build core package
if: needs.check-scope.outputs.spec_only != 'true'
run: pnpm -F @astryxdesign/core build
+ # The generated preview registry imports every configured canary component
+ # package. Build those exports so Vitest exercises the same graph as the
+ # canary deployment.
+ - name: Build canary component packages
+ if: needs.check-scope.outputs.spec_only != 'true'
+ run: |
+ pnpm -F @astryxdesign/lab build
+ pnpm -F @astryxdesign/charts build
+ pnpm -F @astryxdesign/richtext build
+ pnpm -F @astryxdesign/vega build
+
- name: Generate and test docsite data
if: needs.check-scope.outputs.spec_only != 'true'
run: pnpm -F @astryxdesign/docsite generate && pnpm -F @astryxdesign/docsite test
@@ -337,6 +348,14 @@ jobs:
if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true'
run: pnpm -F @astryxdesign/charts typecheck:docs
+ - name: Typecheck rich text docs
+ if: needs.check-scope.outputs.docsite_only != 'true'
+ run: pnpm -F @astryxdesign/richtext typecheck:docs
+
+ - name: Typecheck Vega docs
+ if: needs.check-scope.outputs.docsite_only != 'true'
+ run: pnpm -F @astryxdesign/vega typecheck:docs
+
- name: Typecheck template docs
if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true'
run: pnpm -F @astryxdesign/cli typecheck:template-docs
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index c7034b0c98..4fd5f8cf06 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -135,6 +135,12 @@ jobs:
- name: Typecheck charts docs
run: pnpm -F @astryxdesign/charts typecheck:docs
+ - name: Typecheck rich text docs
+ run: pnpm -F @astryxdesign/richtext typecheck:docs
+
+ - name: Typecheck Vega docs
+ run: pnpm -F @astryxdesign/vega typecheck:docs
+
- name: Typecheck template docs
run: pnpm -F @astryxdesign/cli typecheck:template-docs
diff --git a/apps/docsite/.gitignore b/apps/docsite/.gitignore
index a22b86b707..eb5066b58f 100644
--- a/apps/docsite/.gitignore
+++ b/apps/docsite/.gitignore
@@ -3,6 +3,7 @@ next-env.d.ts
# Auto-generated by scripts/generate-data.mjs
src/generated/
+.content-cache/
# Auto-generated by scripts/generate-playground-types.mjs
public/playground-types.json
diff --git a/apps/docsite/README.md b/apps/docsite/README.md
index ce182b1af3..5430930bca 100644
--- a/apps/docsite/README.md
+++ b/apps/docsite/README.md
@@ -24,17 +24,18 @@ from the monorepo and writes typed TypeScript registries to `src/generated/`.
`scripts/generate-data.mjs` scans the monorepo and produces:
-| Registry | Source | What it contains |
-| ---------------------- | ------------------------------------------ | ------------------------------------------------------------- |
-| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |
-| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups, per package |
-| `blockRegistry.ts` | CLI `templates/blocks/` | Showcase and example blocks with metadata |
-| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |
-| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |
-| `blogRegistry.ts` | `src/content/blog/posts/` | Human-authored blog posts (frontmatter validated) |
-| `themeRegistry.ts` | Installed `@astryxdesign/theme-*` packages | Built theme objects, keyed by package name |
-| `showcaseRegistry.ts` | Blocks with `isShowcase` | Copied showcase source files |
-| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |
+| Registry | Source | What it contains |
+| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |
+| `componentRegistry.ts` | Core + CLI-configured integration `.doc.mjs` files | Props, usage docs, hooks, groups, per package |
+| `componentPreviewRegistry.ts` | Components from those same packages | Runtime exports for the shared Properties preview |
+| `blockRegistry.ts` | CLI + integration template blocks | Showcase and example blocks with metadata |
+| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |
+| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |
+| `blogRegistry.ts` | `src/content/blog/posts/` | Human-authored blog posts (frontmatter validated) |
+| `themeRegistry.ts` | Installed `@astryxdesign/theme-*` packages | Built theme objects, keyed by package name |
+| `showcaseRegistry.ts` | Blocks with `isShowcase` | Copied showcase source files |
+| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |
The `src/generated/` directory is gitignored. Pages import from these registries
and render whatever the pipeline found, with no manual wiring needed.
@@ -67,7 +68,12 @@ The target is derived from Vercel's `VERCEL_ENV`: the production deploy is
dev are `canary`. `scripts/resolve-content-root.mjs` maps the target to the
filesystem root the pipeline reads from — for `latest` it downloads the
published package tarballs from npm (their `src/` ships the `.doc.mjs` the
-pipeline needs); for `canary` it reads the live workspace. Only the documented
+pipeline needs); for `canary` it reads the live workspace and loads the
+component integrations in `astryx.config.mjs`. Packages marked
+`astryx.canaryOnly` are excluded from the `latest` snapshot. Their generated
+components use the existing `isReady: false` state and are grouped under the
+owning package on canary, with one flask on that package category rather than
+one marker per component. Only the documented
**data** is version-pinned — CLI template demos are live-rendered React and
always resolve `@astryxdesign/core` from the bundled workspace version.
@@ -111,11 +117,18 @@ them. Check the theme's `## Fonts` section for the specific Google Fonts URL.
1. Create the package under `packages/<name>/`
2. Add `"@astryxdesign/<name>": "*"` to `apps/docsite/package.json` dependencies
-3. Run `pnpm generate`
+3. For a canary-only component package, set `astryx.canaryOnly: true` in its
+ `package.json`, add `astryx.integration.mjs` with `components: './src'`,
+ include that file in the package's `files`, and list the package in
+ `apps/docsite/astryx.config.mjs`. Keep optional showcase blocks in the
+ package too and expose their directory through the integration's `templates`
+ field; the docsite retrieves them through the CLI template API.
+4. Run `pnpm generate`
The package appears in the sidebar, the libraries section, and gets its own
`/docs/<name>` detail page. If the package contains `.doc.mjs` files,
-its components are extracted into `componentRegistry.ts` as well.
+its components are extracted into `componentRegistry.ts` as well. Canary-only
+packages and components appear only on canary builds and carry a flask icon.
## Adding a Blog Post
diff --git a/apps/docsite/astryx.config.mjs b/apps/docsite/astryx.config.mjs
new file mode 100644
index 0000000000..05330da3f7
--- /dev/null
+++ b/apps/docsite/astryx.config.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx CLI integrations documented by the canary site.
+ * Production uses published stable packages and never loads this catalog.
+ */
+export default {
+ integrations: [
+ '@astryxdesign/lab',
+ '@astryxdesign/charts',
+ '@astryxdesign/richtext',
+ '@astryxdesign/vega',
+ ],
+};
diff --git a/apps/docsite/package.json b/apps/docsite/package.json
index 9f5cbff2b0..25dae2a12e 100644
--- a/apps/docsite/package.json
+++ b/apps/docsite/package.json
@@ -22,12 +22,15 @@
"@astryxdesign/charts": "*",
"@astryxdesign/cli": "*",
"@astryxdesign/core": "*",
+ "@astryxdesign/lab": "*",
+ "@astryxdesign/richtext": "*",
"@astryxdesign/theme-butter": "*",
"@astryxdesign/theme-gothic": "*",
"@astryxdesign/theme-matcha": "*",
"@astryxdesign/theme-neutral": "*",
"@astryxdesign/theme-stone": "*",
"@astryxdesign/theme-y2k": "*",
+ "@astryxdesign/vega": "*",
"fflate": "^0.8.2",
"lucide-react": "^1.18.0",
"lz-string": "^1.5.0",
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 4dcf68e2ab..49c0dc17f9 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -1,7 +1,6 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
-
/**
* @file generate-data.mjs
*
@@ -21,8 +20,11 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {execFileSync} from 'node:child_process';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {resolveContentRoot} from './resolve-content-root.mjs';
+import {template as queryTemplates} from '@astryxdesign/cli/api';
+import docsiteConfig from '../astryx.config.mjs';
import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';
import {
buildTypeDefinitionIndex,
@@ -33,6 +35,15 @@ const __dirname = path.dirname(fileURLToPath(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)
@@ -64,6 +75,45 @@ function writeRegistry(filename, content) {
console.log(` wrote ${path.relative(REPO_ROOT, outPath)}`);
}
+/**
+ * Ask the CLI for the component packages configured by this docsite. The
+ * integration list is canary-only: stable production content comes from the
+ * published package snapshot and never loads workspace integrations.
+ */
+function discoverConfiguredComponentPackages() {
+ if (DOCSITE_TARGET !== 'canary') {
+ return new Set();
+ }
+
+ 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
@@ -103,19 +153,46 @@ function parseStringLiteral(content, openIdx) {
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 '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));
+ out += String.fromCodePoint(
+ parseInt(content.slice(i + 3, end), 16),
+ );
i = end + 1;
continue;
}
@@ -187,17 +264,28 @@ function readDocMeta(docPath) {
isHiddenFromOverview,
};
} catch {
- return {group: null, description: '', name: null, displayName: null, hidden: false, keywords: [], category: null, isHiddenFromOverview: false};
+ return {
+ group: null,
+ description: '',
+ name: null,
+ displayName: null,
+ hidden: false,
+ keywords: [],
+ category: null,
+ isHiddenFromOverview: false,
+ };
}
}
-function findDocFilesRecursive(dir) {
+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()) {
- results.push(...findDocFilesRecursive(full));
+ if (!skipDirs.has(entry.name)) {
+ results.push(...findDocFilesRecursive(full, skipDirs));
+ }
} else if (entry.name.endsWith('.doc.mjs')) {
results.push(full);
}
@@ -247,22 +335,40 @@ 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 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'));
- // Skip private packages
- if (raw.private === true) return null;
+ 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 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;
@@ -271,10 +377,16 @@ function generatePackageRegistry() {
: null;
return {
name: raw.name,
- displayName: raw.displayName || raw.name.replace('@astryxdesign/', '').replace('theme-', 'Theme: ').replace(/^\w/, c => c.toUpperCase()),
+ displayName:
+ raw.displayName ||
+ raw.name
+ .replace('@astryxdesign/', '')
+ .replace('theme-', 'Theme: ')
+ .replace(/^\w/, c => c.toUpperCase()),
version: raw.version,
description: raw.description || '',
packagePath: dir,
+ canaryOnly,
hasReadme,
hasChangelog,
readme,
@@ -292,6 +404,7 @@ export interface PackageMeta {
version: string;
description: string;
packagePath: string;
+ canaryOnly: boolean;
hasReadme: boolean;
hasChangelog: boolean;
readme: string | null;
@@ -304,14 +417,51 @@ export const packages: PackageMeta[] = ${JSON.stringify(packages, null, 2)};
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;
- }));
+ return JSON.parse(
+ JSON.stringify(obj, (key, value) => {
+ if (typeof value === 'function' || typeof value === 'symbol')
+ return undefined;
+ return value;
+ }),
+ );
}
function extractStringArrayField(content, field) {
@@ -330,14 +480,33 @@ async function generateComponentRegistry() {
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'));
- const allDocFiles = findDocFilesRecursive(srcDir);
+ 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) {
- componentPackages.push({name: pkgJson.name, srcDir, dir});
+ 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 SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
const allComponents = {};
let totalCount = 0;
@@ -348,11 +517,11 @@ async function generateComponentRegistry() {
const standaloneNames = new Set();
const pendingSubComponents = [];
- for (const entry of fs.readdirSync(pkg.srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
-
- const dirPath = path.join(pkg.srcDir, entry.name);
- const docFiles = fs.readdirSync(dirPath).filter(f => f.endsWith('.doc.mjs'));
+ 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
@@ -366,7 +535,12 @@ async function generateComponentRegistry() {
try {
const mod = await import(pathToFileURL(dfPath).href);
const d = mod.docs;
- if (d && (d.components || d.props) && !d.params && !d.subComponentOf) {
+ if (
+ d &&
+ (d.components || d.props) &&
+ !d.params &&
+ !d.subComponentOf
+ ) {
dirPrimaryDoc = d.name || null;
dirPrimaryMeta = {
name: d.name || null,
@@ -382,7 +556,9 @@ async function generateComponentRegistry() {
};
break;
}
- } catch { /* ignore */ }
+ } catch {
+ /* ignore */
+ }
}
for (const docFileName of docFiles) {
@@ -394,7 +570,9 @@ async function generateComponentRegistry() {
doc = mod.docs;
if (!doc) continue;
} catch (err) {
- console.warn(` warn: failed to import ${docFileName}: ${err.message}`);
+ console.warn(
+ ` warn: failed to import ${docFileName}: ${err.message}`,
+ );
continue;
}
@@ -406,7 +584,9 @@ async function generateComponentRegistry() {
const topDescription = doc.usage?.description || doc.description || '';
const usage = doc.usage ? sanitizeForJson(doc.usage) : null;
const theming = doc.theming ? sanitizeForJson(doc.theming) : null;
- const playground = doc.playground ? sanitizeForJson(doc.playground) : null;
+ const playground = doc.playground
+ ? sanitizeForJson(doc.playground)
+ : null;
if (doc.subComponentOf) {
// Extracted sub-component: lives in its parent's directory in its own
@@ -431,12 +611,14 @@ async function generateComponentRegistry() {
`${pkg.name}: subcomponent ${subName} (parent ${doc.subComponentOf})`,
),
moduleName: subName,
- directory: entry.name,
- importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ directory,
+ importPath: resolveImportPathForPkg(pkg.dir, directory),
group: parentMeta.group ?? group,
category: parentMeta.category ?? category,
isHiddenFromOverview:
- doc.isHiddenFromOverview ?? parentMeta.isHiddenFromOverview ?? false,
+ doc.isHiddenFromOverview ??
+ parentMeta.isHiddenFromOverview ??
+ false,
description: doc.description || parentMeta.topDescription || '',
keywords: parentMeta.keywords ?? keywords,
hidden: parentMeta.hidden ?? hidden,
@@ -455,7 +637,7 @@ async function generateComponentRegistry() {
? null
: doc.theming
? sanitizeForJson(doc.theming)
- : parentMeta.theming ?? null,
+ : (parentMeta.theming ?? null),
params: isHookEntry
? Array.isArray(doc.params)
? sanitizeForJson(doc.params)
@@ -476,7 +658,7 @@ async function generateComponentRegistry() {
? null
: doc.playground
? sanitizeForJson(doc.playground)
- : parentMeta.playground ?? null,
+ : (parentMeta.playground ?? null),
});
}
} else if (doc.components && doc.components.length > 0) {
@@ -484,7 +666,9 @@ async function generateComponentRegistry() {
// 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/, '');
+ const name =
+ doc.name ||
+ docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
standaloneNames.add(name);
components.push({
name,
@@ -493,8 +677,8 @@ async function generateComponentRegistry() {
`${pkg.name}: component ${name}`,
),
moduleName: name,
- directory: entry.name,
- importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ directory,
+ importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
@@ -559,11 +743,12 @@ async function generateComponentRegistry() {
`${pkg.name}: subcomponent ${sub.name || subName} (parent ${doc.name})`,
),
moduleName: sub.name || subName,
- directory: entry.name,
- importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ directory,
+ importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
- isHiddenFromOverview: sub.isHiddenFromOverview ?? isHiddenFromOverview,
+ isHiddenFromOverview:
+ sub.isHiddenFromOverview ?? isHiddenFromOverview,
description: sub.description || topDescription,
keywords,
hidden,
@@ -603,8 +788,8 @@ async function generateComponentRegistry() {
`${pkg.name}: hook ${name}`,
),
moduleName: name,
- directory: entry.name,
- importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ directory,
+ importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
@@ -615,15 +800,20 @@ async function generateComponentRegistry() {
props: [],
usage,
theming: null,
- params: Array.isArray(doc.params) ? sanitizeForJson(doc.params) : [],
- returns: Array.isArray(doc.returns) ? sanitizeForJson(doc.returns) : [],
+ 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,
});
} else {
// Simple/standalone component
- const name = doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
+ const name =
+ doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
standaloneNames.add(name);
components.push({
name,
@@ -632,8 +822,8 @@ async function generateComponentRegistry() {
`${pkg.name}: component ${name}`,
),
moduleName: name,
- directory: entry.name,
- importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ directory,
+ importPath: resolveImportPathForPkg(pkg.dir, directory),
group,
category,
isHiddenFromOverview,
@@ -672,6 +862,7 @@ async function generateComponentRegistry() {
path.relative(CONTENT_ROOT, pkg.srcDir),
);
for (const comp of components) {
+ comp.isReady = !pkg.canaryOnly;
const referenced = new Map();
const rows = [
...comp.props,
@@ -699,6 +890,19 @@ async function generateComponentRegistry() {
}
}
+ 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);
+ }
+ }
+
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {
@@ -884,6 +1088,8 @@ export interface ComponentEntry {
description: string;
keywords: string[];
hidden: boolean;
+ /** Whether this component is ready for the stable documentation line. */
+ isReady: boolean;
parentDoc: string | null;
props: PropDoc[];
/** Declarations for every type referenced from \`props[]\`, \`params[]\`, or
@@ -909,6 +1115,39 @@ export const componentCount = ${totalCount};
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'.
@@ -917,6 +1156,9 @@ export const componentCount = ${totalCount};
* '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')
@@ -951,22 +1193,32 @@ function generateGroupedComponentRegistry(allComponents) {
entry.group === 'Utilities' ||
(isHook && !entry.parentDoc && entry.directory === 'hooks')
) {
- utilities.push({name: entry.name, displayName, href: `/components/${entry.name}`});
+ 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});
+ 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});
+ groups.get(dir).push({
+ name: entry.name,
+ displayName,
+ href: `/components/${entry.name}`,
+ description: entry.description,
+ });
continue;
}
if (
@@ -976,23 +1228,44 @@ function generateGroupedComponentRegistry(allComponents) {
) {
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});
+ 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}`});
+ utilities.push({
+ name: entry.name,
+ displayName,
+ href: `/components/${entry.name}`,
+ });
continue;
}
- ungrouped.push({name: entry.name, displayName, href: `/components/${entry.name}`, description: entry.description});
+ 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}});
+ 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
@@ -1003,11 +1276,33 @@ function generateGroupedComponentRegistry(allComponents) {
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}))}});
+ 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.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));
@@ -1086,18 +1381,24 @@ async function generateBlockRegistry() {
}
const cuMatch = content.match(/componentsUsed:\s*\[([^\]]*)\]/);
if (cuMatch) {
- componentsUsed = [...cuMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map(m => m[1]);
+ componentsUsed = [...cuMatch[1].matchAll(/['"]([^'"]+)['"]/g)].map(
+ m => m[1],
+ );
}
const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);
if (efMatch) {
exampleFor = efMatch[1];
}
- } catch { /* ignore */ }
+ } catch {
+ /* ignore */
+ }
let source = '';
try {
source = fs.readFileSync(tsxPath, 'utf-8');
- } catch { /* ignore */ }
+ } catch {
+ /* ignore */
+ }
const resolvedName = meta.name || basename;
blocks.push({
@@ -1121,6 +1422,40 @@ async function generateBlockRegistry() {
});
}
+ if (DOCSITE_TARGET === 'canary') {
+ const templateList = await queryTemplates(undefined, {
+ list: true,
+ type: 'block',
+ cwd: DOCSITE_ROOT,
+ });
+ const integrationBlocks = templateList.data.filter(entry =>
+ CONFIGURED_COMPONENT_PACKAGES.has(entry.package),
+ );
+ for (const entry of integrationBlocks) {
+ const shown = await queryTemplates(entry.id, {
+ show: true,
+ type: 'block',
+ package: entry.package,
+ cwd: DOCSITE_ROOT,
+ });
+ blocks.push({
+ dirName: `${entry.package}-${entry.id}`.replace(/[^a-zA-Z0-9_-]/g, '-'),
+ name: entry.name,
+ displayName: entry.displayName || entry.name,
+ description: entry.description,
+ exampleFor: entry.exampleFor || '',
+ alsoExampleFor: entry.alsoExampleFor ?? [],
+ alsoShowcaseFor: entry.alsoShowcaseFor ?? [],
+ isShowcase: entry.isShowcase ?? false,
+ 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;
@@ -1141,6 +1476,8 @@ export interface BlockEntry {
description: string;
/** The component this block is an example of (e.g. 'Button', 'Dialog') */
exampleFor: string;
+ alsoExampleFor?: string[];
+ alsoShowcaseFor?: string[];
isShowcase: boolean;
aspectRatio: number;
componentsUsed: string[];
@@ -1148,6 +1485,8 @@ export interface BlockEntry {
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)};
@@ -1166,12 +1505,17 @@ async function generateTemplateRegistry() {
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(
+ 'templateRegistry.ts',
+ `// Auto-generated — no templates found\nexport const templates = [];\nexport const templateCount = 0;\n`,
+ );
return {templates: [], templateCount: 0};
}
const templates = [];
- const dirs = fs.readdirSync(PAGES_DIR, {withFileTypes: true}).filter(e => e.isDirectory());
+ 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');
@@ -1181,18 +1525,28 @@ async function generateTemplateRegistry() {
let doc;
try {
- const mod = await import(fileURLToPath(new URL(`file://${docPath}`)).replace(/\\/g, '/'));
+ 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};
+ 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 */ }
+ try {
+ source = fs.readFileSync(pagePath, 'utf-8');
+ } catch {
+ /* ignore */
+ }
templates.push({
slug: dir.name,
@@ -1237,7 +1591,10 @@ async function generateDocsRegistry() {
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;\n`);
+ writeRegistry(
+ 'docsRegistry.ts',
+ `// Auto-generated — no docs found\nexport const docTopics = [];\nexport const docsCount = 0;\n`,
+ );
return {docTopics: [], docsCount: 0};
}
@@ -1267,7 +1624,13 @@ async function generateDocsRegistry() {
description = meta.description;
}
- docTopics.push({topic, title: title || topic, description, category: category || null, sections});
+ docTopics.push({
+ topic,
+ title: title || topic,
+ description,
+ category: category || null,
+ sections,
+ });
}
docTopics.sort((a, b) => a.topic.localeCompare(b.topic));
@@ -1317,30 +1680,38 @@ export const docsCount = ${docTopics.length};
return {docTopics, docsCount: docTopics.length};
}
-
async function generateThemeRegistry(packages) {
console.log('Generating theme registry...');
- const themePackages = packages.filter(p => p.name.startsWith('@astryxdesign/theme-'));
+ const themePackages = packages.filter(p =>
+ p.name.startsWith('@astryxdesign/theme-'),
+ );
if (!themePackages.length) {
- writeRegistry('themeRegistry.ts', `// Auto-generated — no theme packages found
+ 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 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');
+ 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
@@ -1366,10 +1737,12 @@ export const themeObjects: Record<string, DefinedTheme> = {};
}
}
- const fullEntries = themePackages.map(p => {
- const slug = p.name.replace('@astryxdesign/theme-', '');
- return ` '${p.name}': {...${slug}Theme, components: componentOverrides['${p.name}']},`;
- }).join('\n');
+ 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
@@ -1386,7 +1759,10 @@ ${entries}
* 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')};
+ ${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
@@ -1449,7 +1825,7 @@ function importsPackageMissingFromDocsite(tsxSource) {
return imports.some(pkg => _docsiteDeps[pkg] == null);
}
-function generateShowcaseRegistry() {
+function generateShowcaseRegistry(blocks) {
console.log('Generating showcase registry...');
const BLOCKS_DIR = path.join(CLI_ROOT, 'assets', 'templates', 'blocks');
@@ -1503,7 +1879,30 @@ function generateShowcaseRegistry() {
fs.copyFileSync(tsxSrc, path.join(SHOWCASE_OUT, destFile));
entries.push({exampleFor: target, basename: aliasBasename, destFile});
}
+ }
+ for (const block of blocks) {
+ if (!block.sourcePackage || !block.isShowcase || !block.exampleFor) {
+ continue;
+ }
+ if (importsPackageMissingFromDocsite(block.source)) {
+ console.log(
+ ` skipping showcase ${block.dirName} — imports a package not installed in the docsite`,
+ );
+ continue;
+ }
+ const basename = `integration-${block.dirName}`;
+ const targets = [block.exampleFor, ...(block.alsoShowcaseFor ?? [])];
+ for (const [index, target] of targets.entries()) {
+ const targetBasename = index === 0 ? basename : `${basename}__${target}`;
+ const destFile = `${targetBasename}.tsx`;
+ fs.writeFileSync(
+ path.join(SHOWCASE_OUT, destFile),
+ block.source,
+ 'utf-8',
+ );
+ entries.push({exampleFor: target, basename: targetBasename, destFile});
+ }
}
// Deduplicate: one showcase per component (first wins)
@@ -1515,9 +1914,9 @@ function generateShowcaseRegistry() {
});
// Generate the registry with dynamic imports
- const importLines = uniqueEntries.map(
- e => ` '${e.exampleFor}': () => import('./showcases/${e.basename}'),`
- ).join('\n');
+ const importLines = uniqueEntries
+ .map(e => ` '${e.exampleFor}': () => import('./showcases/${e.basename}'),`)
+ .join('\n');
const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {ComponentType} from 'react';
@@ -1530,13 +1929,15 @@ ${importLines}
`;
writeRegistry('showcaseRegistry.ts', registryContent);
- console.log(` copied ${entries.length} showcase files (${uniqueEntries.length} unique components)`);
+ console.log(
+ ` copied ${entries.length} showcase files (${uniqueEntries.length} unique components)`,
+ );
return uniqueEntries.length;
}
// ── Main
-function generateExampleRegistry() {
+function generateExampleRegistry(blocks) {
console.log('Generating example registry...');
const BLOCKS_DIR = path.join(CLI_ROOT, 'assets', 'templates', 'blocks');
@@ -1567,7 +1968,11 @@ function generateExampleRegistry() {
const description = extractQuotedField(content, 'description');
let source = '';
- try { source = fs.readFileSync(tsxSrc, 'utf-8'); } catch { /* ignore */ }
+ try {
+ source = fs.readFileSync(tsxSrc, 'utf-8');
+ } catch {
+ /* ignore */
+ }
// Skip live-preview entries for blocks the docsite cannot resolve — they'd
// break `next build`. The block's code is still shown via the block
@@ -1607,7 +2012,48 @@ function generateExampleRegistry() {
source,
});
}
+ }
+ for (const block of blocks) {
+ if (!block.sourcePackage) {
+ continue;
+ }
+ if (importsPackageMissingFromDocsite(block.source)) {
+ console.log(
+ ` skipping example ${block.dirName} — imports a package not installed in the docsite`,
+ );
+ continue;
+ }
+ const basename = `integration-${block.dirName}`;
+ if (!block.isShowcase && block.exampleFor) {
+ fs.writeFileSync(
+ path.join(EXAMPLES_OUT, `${basename}.tsx`),
+ block.source,
+ 'utf-8',
+ );
+ entries.push({
+ exampleFor: block.exampleFor,
+ basename,
+ name: block.name,
+ description: block.description,
+ source: block.source,
+ });
+ }
+ for (const target of block.alsoExampleFor ?? []) {
+ const aliasBasename = `${basename}__${target}`;
+ fs.writeFileSync(
+ path.join(EXAMPLES_OUT, `${aliasBasename}.tsx`),
+ block.source,
+ 'utf-8',
+ );
+ entries.push({
+ exampleFor: target,
+ basename: aliasBasename,
+ name: block.name,
+ description: block.description || `Example using ${target}.`,
+ source: block.source,
+ });
+ }
}
// Group by component
@@ -1618,12 +2064,17 @@ function generateExampleRegistry() {
}
// Generate registry: component name → array of example metadata + loaders
- const componentLines = Object.entries(grouped).map(([comp, examples]) => {
- const exampleLines = examples.map(
- e => ` {name: ${JSON.stringify(e.name)}, description: ${JSON.stringify(e.description)}, source: ${JSON.stringify(e.source)}, load: () => import('./examples/${e.basename}')},`
- ).join('\n');
- return ` '${comp}': [\n${exampleLines}\n ],`;
- }).join('\n');
+ const componentLines = Object.entries(grouped)
+ .map(([comp, examples]) => {
+ const exampleLines = examples
+ .map(
+ e =>
+ ` {name: ${JSON.stringify(e.name)}, description: ${JSON.stringify(e.description)}, source: ${JSON.stringify(e.source)}, load: () => import('./examples/${e.basename}')},`,
+ )
+ .join('\n');
+ return ` '${comp}': [\n${exampleLines}\n ],`;
+ })
+ .join('\n');
const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit
import type {ComponentType} from 'react';
@@ -1641,7 +2092,9 @@ ${componentLines}
`;
writeRegistry('exampleRegistry.ts', registryContent);
- console.log(` copied ${entries.length} example blocks for ${Object.keys(grouped).length} components`);
+ console.log(
+ ` copied ${entries.length} example blocks for ${Object.keys(grouped).length} components`,
+ );
return entries.length;
}
@@ -1650,19 +2103,12 @@ ${componentLines}
async function generateBlogRegistry() {
console.log('Generating blog registry...');
- const POSTS_DIR = path.join(
- DOCSITE_ROOT,
- 'src',
- 'content',
- 'blog',
- 'posts',
- );
+ 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} = await import(
- pathToFileURL(
- path.join(DOCSITE_ROOT, 'src', 'lib', 'blog', 'posts.mjs'),
- ).href
+ pathToFileURL(path.join(DOCSITE_ROOT, 'src', 'lib', 'blog', 'posts.mjs'))
+ .href
);
// Exclude drafts from production output; include them only in dev.
@@ -1720,19 +2166,24 @@ async function main() {
const packages = generatePackageRegistry();
const themeCount = await generateThemeRegistry(packages);
- const {allComponents, totalCount: componentCount} = await generateComponentRegistry();
+ const {allComponents, totalCount: componentCount} =
+ await generateComponentRegistry();
+ generateComponentPreviewRegistry(allComponents);
generateGroupedComponentRegistry(allComponents);
- const {blockCount, showcaseCount} = await generateBlockRegistry();
+ const {blocks, blockCount, showcaseCount} = await generateBlockRegistry();
+ generatePackageStyles(packages, blocks, allComponents);
const {templateCount} = await generateTemplateRegistry();
const {docsCount} = await generateDocsRegistry();
const {blogPostCount} = await generateBlogRegistry();
- const showcaseCopied = generateShowcaseRegistry();
- const examplesCopied = generateExampleRegistry();
+ const showcaseCopied = generateShowcaseRegistry(blocks);
+ const examplesCopied = generateExampleRegistry(blocks);
console.log(`\nSummary:`);
console.log(` ${packages.length} packages`);
console.log(` ${componentCount} components`);
- console.log(` ${blockCount} blocks (${showcaseCopied} showcases, ${examplesCopied} examples)`);
+ console.log(
+ ` ${blockCount} blocks (${showcaseCopied} showcases, ${examplesCopied} examples)`,
+ );
console.log(` ${templateCount} templates`);
console.log(` ${docsCount} doc topics`);
console.log(` ${blogPostCount} blog posts`);
diff --git a/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
index fa3d5ea748..116c232e2d 100644
--- a/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
+++ b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
@@ -18,6 +18,19 @@ vi.mock('@astryxdesign/core', () => ({
}));
describe('component detail element resolution', () => {
+ it('resolves external components and nested descriptors lazily', () => {
+ expect(getComponent('RichTextEditor')).not.toBeNull();
+ const tourStep = resolveValue({
+ __element: 'TourStep',
+ props: {title: 'Review'},
+ });
+ expect(isValidElement(tourStep)).toBe(true);
+ expect((tourStep as ReactElement).type).not.toBe('TourStep');
+ expect(
+ ((tourStep as ReactElement).type as {displayName?: string}).displayName,
+ ).toBe('TourStep');
+ });
+
it('resolves descriptor arrays from playground defaults into React elements', () => {
const resolved = resolveValue([
{__element: 'SideNavItem', props: {label: 'Dashboard'}},
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index 104c6b5789..f2fa2d36f6 100644
--- a/apps/docsite/src/__tests__/component-preview-state.test.ts
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -798,6 +798,16 @@ describe('hasInteractivePlayground', () => {
}),
).toBe(true);
});
+
+ it('uses the standard playground for components from canary packages', () => {
+ expect(
+ hasInteractivePlayground({
+ category: 'Data Input',
+ params: null,
+ playground: null,
+ }),
+ ).toBe(true);
+ });
});
// ── Simulated mobile AppShell context (#4983) ───────────────────────────────
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 5cbb924e4b..7c2f2ecbcc 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -11,6 +11,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {describe, it, expect} from 'vitest';
+import docsiteConfig from '../../astryx.config.mjs';
import {packages} from '../generated/packageRegistry';
import {
components,
@@ -21,6 +22,7 @@ import {blocks, blockCount, showcaseCount} from '../generated/blockRegistry';
import {templates, templateCount} from '../generated/templateRegistry';
import {docTopics, docsCount} from '../generated/docsRegistry';
import {showcaseRegistry} from '../generated/showcaseRegistry';
+import {externalComponentPreviews} from '../generated/componentPreviewRegistry';
import {eagerShowcases} from '../components/eagerShowcases';
import {exampleRegistry} from '../generated/exampleRegistry';
import {normalizeComponentCategory} from '../lib/componentCategories';
@@ -38,6 +40,7 @@ const COMPONENT_REGISTRY_SOURCE = fs.readFileSync(
COMPONENT_REGISTRY_PATH,
'utf-8',
);
+const CONFIGURED_CANARY_PACKAGES = new Set(docsiteConfig.integrations);
function findFiles(dir: string, predicate: (filePath: string) => boolean) {
const files: string[] = [];
@@ -102,20 +105,26 @@ function getComponentDocCompletenessIssues(
// ── Package Registry ───────────────────────────────────────────────────
describe('packageRegistry', () => {
- it('discovers installed packages (private and uninstalled excluded)', () => {
+ it('discovers installed stable packages and canary-only integrations', () => {
const names = packages.map(p => p.name);
expect(names).toContain('@astryxdesign/core');
expect(names).toContain('@astryxdesign/cli');
expect(names).toContain('@astryxdesign/theme-neutral');
expect(names).toContain('@astryxdesign/theme-gothic');
expect(names).toContain('@astryxdesign/theme-stone');
+ expect(names).toContain('@astryxdesign/lab');
+ expect(names).toContain('@astryxdesign/charts');
+ expect(names).toContain('@astryxdesign/richtext');
+ expect(names).toContain('@astryxdesign/vega');
expect(names).not.toContain('@astryxdesign/theme-default');
expect(names).not.toContain('@astryxdesign/theme-brutalist');
expect(names).not.toContain('@astryxdesign/theme-chocolate');
expect(names).not.toContain('@astryxdesign/theme-daily');
- expect(names).not.toContain('@astryxdesign/lab');
expect(names).not.toContain('@astryxdesign/build');
- expect(packages.length).toBeGreaterThanOrEqual(5);
+ expect(packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name)).toEqual(
+ [...CONFIGURED_CANARY_PACKAGES].sort(),
+ );
+ expect(packages.length).toBeGreaterThanOrEqual(9);
});
it('only includes packages listed in docsite dependencies', () => {
@@ -137,11 +146,36 @@ describe('packageRegistry', () => {
expect(pkg.displayName).toBeTruthy();
expect(pkg.version).toMatch(/^\d+\.\d+\.\d+/);
expect(pkg.packagePath).toBeTruthy();
+ expect(typeof pkg.canaryOnly).toBe('boolean');
expect(typeof pkg.hasReadme).toBe('boolean');
expect(typeof pkg.hasChangelog).toBe('boolean');
}
});
+ it('generates CSS imports for every canary component package that exports CSS', () => {
+ const css = fs.readFileSync(
+ path.join(REPO_ROOT, 'apps/docsite/src/generated/package-styles.css'),
+ 'utf-8',
+ );
+ const expectedImports = packages
+ .filter(pkg => pkg.canaryOnly && components[pkg.name]?.length > 0)
+ .flatMap(pkg => {
+ const manifest = JSON.parse(
+ fs.readFileSync(
+ path.join(REPO_ROOT, pkg.packagePath, 'package.json'),
+ 'utf-8',
+ ),
+ );
+ return Object.keys(manifest.exports ?? {})
+ .filter(subpath => subpath.endsWith('.css'))
+ .map(subpath => `@import "${pkg.name}/${subpath.slice(2)}";`);
+ });
+
+ for (const expectedImport of expectedImports) {
+ expect(css).toContain(expectedImport);
+ }
+ });
+
it('no duplicate package names', () => {
const names = packages.map(p => p.name);
expect(new Set(names).size).toBe(names.length);
@@ -164,7 +198,9 @@ describe('packageRegistry', () => {
if (pkg.hasChangelog) {
expect(pkg.changelog).toBeTruthy();
expect(typeof pkg.changelog).toBe('string');
- expect(pkg.changelog!.length).toBeGreaterThan(50);
+ expect(pkg.changelog!.length).toBeGreaterThan(
+ pkg.name === '@astryxdesign/richtext' ? 0 : 50,
+ );
} else {
expect(pkg.changelog).toBeNull();
}
@@ -199,6 +235,75 @@ describe('componentRegistry', () => {
expect(components['@astryxdesign/core'].length).toBeGreaterThan(100);
});
+ it('discovers CLI-configured canary package components', () => {
+ expect(components['@astryxdesign/lab'].length).toBeGreaterThan(30);
+ expect(components['@astryxdesign/charts'].map(comp => comp.name)).toEqual([
+ 'Chart',
+ 'ChartSwatch',
+ ]);
+ expect(components['@astryxdesign/richtext'].map(comp => comp.name)).toEqual(
+ ['RichTextEditor'],
+ );
+ expect(components['@astryxdesign/vega'].map(comp => comp.name)).toEqual([
+ 'VegaChart',
+ ]);
+
+ for (const packageName of [
+ '@astryxdesign/lab',
+ '@astryxdesign/charts',
+ '@astryxdesign/richtext',
+ '@astryxdesign/vega',
+ ]) {
+ expect(
+ components[packageName].every(comp => !comp.isReady),
+ packageName,
+ ).toBe(true);
+ }
+ expect(components['@astryxdesign/core'].every(comp => comp.isReady)).toBe(
+ true,
+ );
+ });
+
+ it('groups every chart-family component under Charts', () => {
+ const chartComponents = [
+ ...(components['@astryxdesign/charts'] ?? []),
+ ...(components['@astryxdesign/lab'] ?? []).filter(comp =>
+ comp.name.startsWith('Chart'),
+ ),
+ ];
+ expect(chartComponents.length).toBeGreaterThan(2);
+ expect(chartComponents.every(comp => comp.group === 'Charts')).toBe(true);
+ expect(
+ chartComponents.every(comp => comp.category === 'Data Visualization'),
+ ).toBe(true);
+ });
+
+ it('keeps every Lab chat component in the Chat family and category', () => {
+ const chatComponents = (components['@astryxdesign/lab'] ?? []).filter(
+ comp => comp.name.startsWith('Chat'),
+ );
+ expect(chatComponents.length).toBeGreaterThan(4);
+ expect(chatComponents.every(comp => comp.group === 'Chat')).toBe(true);
+ expect(chatComponents.every(comp => comp.category === 'Chat')).toBe(true);
+ });
+
+ it('generates lazy previews for every non-core component', () => {
+ const externalNames = Object.entries(components).flatMap(
+ ([packageName, entries]) =>
+ packageName === '@astryxdesign/core'
+ ? []
+ : entries.map(component => component.name),
+ );
+ expect(Object.keys(externalComponentPreviews).sort()).toEqual(
+ externalNames.sort(),
+ );
+ expect(
+ Object.values(externalComponentPreviews).every(
+ component => component != null && typeof component === 'object',
+ ),
+ ).toBe(true);
+ });
+
it('component count matches sum of all packages', () => {
const sum = Object.values(components).reduce(
(acc, list) => acc + list.length,
@@ -217,6 +322,7 @@ describe('componentRegistry', () => {
expect(typeof comp.description).toBe('string');
expect(Array.isArray(comp.keywords)).toBe(true);
expect(typeof comp.hidden).toBe('boolean');
+ expect(typeof comp.isReady).toBe('boolean');
// parentDoc is string | null
expect(
comp.parentDoc === null || typeof comp.parentDoc === 'string',
@@ -621,6 +727,13 @@ describe('componentRegistry', () => {
}
});
+ it('has globally unique component route names', () => {
+ const names = Object.values(components)
+ .flat()
+ .map(component => component.name);
+ expect(new Set(names).size).toBe(names.length);
+ });
+
it('known compound docs are expanded, not emitted as single entries', () => {
const core = components['@astryxdesign/core'];
const names = core.map(c => c.name);
@@ -755,6 +868,18 @@ describe('blockRegistry', () => {
expect(buttonShowcase).toBeDefined();
});
+ it('discovers the Charts-owned showcase through its CLI integration', () => {
+ const chartShowcase = blocks.find(
+ block => block.isShowcase && block.exampleFor === 'Chart',
+ );
+ expect(chartShowcase).toMatchObject({
+ displayName: 'Chart',
+ sourcePackage: '@astryxdesign/charts',
+ aspectRatio: 1.6,
+ });
+ expect(chartShowcase?.source).toContain("from '@astryxdesign/charts'");
+ });
+
it('every block has exampleFor set', () => {
const missing = blocks.filter(b => !b.exampleFor);
expect(missing.map(b => b.dirName)).toEqual([]);
@@ -939,6 +1064,9 @@ describe('showcaseRegistry', () => {
expect(showcaseRegistry['Dialog']).toBeDefined();
expect(showcaseRegistry['Table']).toBeDefined();
expect(showcaseRegistry['Card']).toBeDefined();
+ expect(showcaseRegistry['Chart']).toBeDefined();
+ expect(showcaseRegistry['ChartBar']).toBeDefined();
+ expect(showcaseRegistry['RichTextEditor']).toBeDefined();
});
it('no duplicate keys (one showcase per component)', () => {
diff --git a/apps/docsite/src/__tests__/search-palette.test.ts b/apps/docsite/src/__tests__/search-palette.test.ts
index f93204bb5d..4de9bc0f8a 100644
--- a/apps/docsite/src/__tests__/search-palette.test.ts
+++ b/apps/docsite/src/__tests__/search-palette.test.ts
@@ -12,7 +12,10 @@ import {components} from '../generated/componentRegistry';
import {packages} from '../generated/packageRegistry';
import {docTopics} from '../generated/docsRegistry';
import {templates} from '../generated/templateRegistry';
-import {flattenComponentSidebarEntries} from '../components/componentSidebarData';
+import {
+ flattenComponentSidebarEntries,
+ getComponentSidebarData,
+} from '../components/componentSidebarData';
import {
buildSearchPaletteItems,
getSearchItemKeywords,
@@ -39,7 +42,9 @@ function searchItems(query: string) {
describe('SearchPalette data', () => {
it('uses the sidebar entries as the command palette component set', () => {
const componentIds = buildItems()
- .filter(item => item.auxiliaryData.group === 'Component')
+ .filter(item =>
+ ['Component', 'Canary component'].includes(item.auxiliaryData.group),
+ )
.map(item => item.id);
const sidebarIds = flattenComponentSidebarEntries().map(
entry => entry.href,
@@ -53,6 +58,70 @@ describe('SearchPalette data', () => {
expect(componentIds).toContain('/components/Table');
});
+ it('includes canary-only component packages with canary metadata', () => {
+ const entries = flattenComponentSidebarEntries();
+ const items = buildItems();
+ const canaryPackages = new Set(
+ packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name),
+ );
+ const canaryEntries = entries.filter(entry =>
+ canaryPackages.has(entry.packageName),
+ );
+
+ expect(canaryEntries.length).toBeGreaterThan(0);
+ expect(canaryEntries.every(entry => !entry.isReady)).toBe(true);
+ expect(
+ canaryEntries.every(entry => {
+ const item = items.find(item => item.id === entry.href);
+ return (
+ item?.auxiliaryData.isReady === false &&
+ item.auxiliaryData.group === 'Canary component'
+ );
+ }),
+ ).toBe(true);
+ expect(
+ entries
+ .filter(entry => !canaryPackages.has(entry.packageName))
+ .every(entry => entry.isReady),
+ ).toBe(true);
+ });
+
+ it('keeps ready families unified and groups canary components by package', () => {
+ const {componentItems, canaryCategories} = getComponentSidebarData();
+ const readyGroups = componentItems.filter(item => item.type === 'group');
+
+ expect(readyGroups.filter(group => group.label === 'Chat')).toHaveLength(1);
+ expect(
+ readyGroups
+ .find(group => group.label === 'Chat')
+ ?.entries.every(entry => entry.isReady),
+ ).toBe(true);
+
+ expect(canaryCategories.map(category => category.displayName)).toEqual([
+ 'Charts',
+ 'Lab',
+ 'Rich Text',
+ 'Vega',
+ ]);
+ const chartEntries = canaryCategories.flatMap(category =>
+ category.componentItems.flatMap(item =>
+ item.type === 'entry' || item.label !== 'Charts' ? [] : item.entries,
+ ),
+ );
+ expect(chartEntries.map(entry => entry.name)).toEqual(
+ expect.arrayContaining(['Chart', 'ChartSwatch', 'ChartBar', 'ChartLine']),
+ );
+ expect(chartEntries.every(entry => !entry.isReady)).toBe(true);
+
+ const lab = canaryCategories.find(
+ category => category.displayName === 'Lab',
+ );
+ const threeD = lab?.componentItems.find(
+ item => item.type === 'group' && item.label === '3D',
+ );
+ expect(threeD?.displayName).toBe('3D');
+ });
+
it('finds Dropdown Menu by spaced display name and PascalCase API name', () => {
const items = buildItems();
const dropdown = items.find(item => item.id === '/components/DropdownMenu');
diff --git a/apps/docsite/src/app/(docs)/components/page.tsx b/apps/docsite/src/app/(docs)/components/page.tsx
index 7581aad502..ef3a971e8d 100644
--- a/apps/docsite/src/app/(docs)/components/page.tsx
+++ b/apps/docsite/src/app/(docs)/components/page.tsx
@@ -7,6 +7,7 @@
'use client';
import {Fragment, useMemo} from 'react';
+import {FlaskConical} from 'lucide-react';
import * as stylex from '@stylexjs/stylex';
import {Text} from '@astryxdesign/core/Text';
import {Heading} from '@astryxdesign/core/Text';
@@ -14,12 +15,14 @@ import {VStack, HStack} from '@astryxdesign/core/Layout';
import {Section} from '@astryxdesign/core/Section';
import {Grid} from '@astryxdesign/core/Grid';
import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {Icon} from '@astryxdesign/core/Icon';
import {Divider} from '@astryxdesign/core/Divider';
import {Button} from '@astryxdesign/core/Button';
import {Popover} from '@astryxdesign/core/Popover';
import {Card} from '@astryxdesign/core/Card';
import {CodeExampleBlock} from '../../../components/CodeExampleBlock';
import {components as componentRegistry} from '../../../generated/componentRegistry';
+import {packages} from '../../../generated/packageRegistry';
import {showcaseRegistry} from '../../../generated/showcaseRegistry';
import {ShowcaseThumbnail} from '../../../components/ShowcaseThumbnail';
import {normalizeComponentCategory} from '../../../lib/componentCategories';
@@ -55,6 +58,10 @@ const CATEGORIES = [
*/
const SHOWCASE_NAMES = new Set(Object.keys(showcaseRegistry));
+const packageDisplayNames = new Map(
+ packages.map(pkg => [pkg.name, pkg.displayName]),
+);
+
const styles = stylex.create({
heroTitle: {
textAlign: 'center' as const,
@@ -79,56 +86,86 @@ interface CategoryItem {
category: string;
/** Whether a showcase block exists to render in this component's tile */
hasShowcase: boolean;
+ packageName: string;
+ isReady: boolean;
+}
+
+function ComponentGrid({items}: {items: CategoryItem[]}) {
+ return (
+ <Grid columns={{minWidth: 300, repeat: 'fill'}} gap={3} rowGap={4}>
+ {items.map(item => (
+ <VStack key={`${item.packageName}:${item.name}`} gap={1}>
+ <ClickableCard
+ label={item.displayName}
+ href={item.href}
+ padding={0}
+ variant="transparent">
+ {item.hasShowcase ? (
+ <ShowcaseThumbnail name={item.name} />
+ ) : (
+ <div {...stylex.props(styles.cardImage)} />
+ )}
+ </ClickableCard>
+ <Text type="supporting">{item.displayName}</Text>
+ </VStack>
+ ))}
+ </Grid>
+ );
}
export default function ComponentsGalleryPage() {
/** All categorized components (excluding hidden, hooks, and utilities) */
const categorizedItems = useMemo(() => {
- const coreComponents = componentRegistry['@astryxdesign/core'] ?? [];
const items: CategoryItem[] = [];
- for (const comp of coreComponents) {
- // Skip components explicitly hidden from overview
- if (comp.isHiddenFromOverview) {
- continue;
- }
- // Skip hidden components
- if (comp.hidden) {
- continue;
- }
- // Skip hooks (they appear in the Utilities section)
- if (comp.name.startsWith('use')) {
- continue;
- }
- // Skip components without a category
- if (!comp.category) {
- continue;
- }
- // Skip utilities group
- if (comp.group === 'Utilities') {
- continue;
- }
+ for (const [packageName, packageComponents] of Object.entries(
+ componentRegistry,
+ )) {
+ for (const comp of packageComponents) {
+ // Skip components explicitly hidden from overview
+ if (comp.isHiddenFromOverview) {
+ continue;
+ }
+ // Skip hidden components
+ if (comp.hidden) {
+ continue;
+ }
+ // Skip hooks (they appear in the Utilities section)
+ if (comp.name.startsWith('use')) {
+ continue;
+ }
+ // Skip components without a category
+ if (!comp.category) {
+ continue;
+ }
+ // Skip utilities group
+ if (comp.group === 'Utilities') {
+ continue;
+ }
- items.push({
- name: comp.name,
- displayName: comp.displayName,
- description: comp.description,
- href: `/components/${comp.name}`,
- category: normalizeComponentCategory(comp.category),
- hasShowcase: SHOWCASE_NAMES.has(comp.name),
- });
+ items.push({
+ name: comp.name,
+ displayName: comp.displayName,
+ description: comp.description,
+ href: `/components/${comp.name}`,
+ category: normalizeComponentCategory(comp.category),
+ hasShowcase: SHOWCASE_NAMES.has(comp.name),
+ packageName,
+ isReady: comp.isReady,
+ });
+ }
}
return items;
}, []);
- /** Group items by category */
+ /** Group ready items by functional category. */
const groupedByCategory = useMemo(() => {
const map = new Map<string, CategoryItem[]>();
for (const cat of CATEGORIES) {
map.set(cat, []);
}
- for (const item of categorizedItems) {
+ for (const item of categorizedItems.filter(item => item.isReady)) {
const list = map.get(item.category);
if (list) {
list.push(item);
@@ -137,6 +174,23 @@ export default function ComponentsGalleryPage() {
return map;
}, [categorizedItems]);
+ /** Group canary items by owning package; readiness appears on the category. */
+ const canaryCategories = useMemo(() => {
+ const map = new Map<string, CategoryItem[]>();
+ for (const item of categorizedItems.filter(item => !item.isReady)) {
+ const list = map.get(item.packageName) ?? [];
+ list.push(item);
+ map.set(item.packageName, list);
+ }
+ return [...map.entries()]
+ .map(([packageName, items]) => ({
+ packageName,
+ displayName: packageDisplayNames.get(packageName) ?? packageName,
+ items: items.sort((a, b) => a.displayName.localeCompare(b.displayName)),
+ }))
+ .sort((a, b) => a.displayName.localeCompare(b.displayName));
+ }, [categorizedItems]);
+
return (
<Section
maxWidth={layout.contentMaxWidth}
@@ -212,31 +266,24 @@ export default function ComponentsGalleryPage() {
<Divider />
<VStack gap={4}>
<Heading level={2}>{cat}</Heading>
- <Grid
- columns={{minWidth: 300, repeat: 'fill'}}
- gap={3}
- rowGap={4}>
- {items.map(item => (
- <VStack key={item.name} gap={1}>
- <ClickableCard
- label={item.displayName}
- href={item.href}
- padding={0}
- variant="transparent">
- {item.hasShowcase ? (
- <ShowcaseThumbnail name={item.name} />
- ) : (
- <div {...stylex.props(styles.cardImage)} />
- )}
- </ClickableCard>
- <Text type="supporting">{item.displayName}</Text>
- </VStack>
- ))}
- </Grid>
+ <ComponentGrid items={items} />
</VStack>
</Fragment>
);
})}
+
+ {canaryCategories.map(category => (
+ <Fragment key={category.packageName}>
+ <Divider />
+ <VStack gap={4}>
+ <HStack gap={2} vAlign="center">
+ <Heading level={2}>{category.displayName}</Heading>
+ <Icon icon={FlaskConical} label="Canary" size="sm" />
+ </HStack>
+ <ComponentGrid items={category.items} />
+ </VStack>
+ </Fragment>
+ ))}
</VStack>
</Section>
);
diff --git a/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx b/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
index 8fcb242ae5..7f3132d424 100644
--- a/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
+++ b/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
@@ -13,7 +13,10 @@
import type {Metadata} from 'next';
import {notFound} from 'next/navigation';
import {docTopics} from '../../../../generated/docsRegistry';
-import {packages} from '../../../../generated/packageRegistry';
+import {
+ packages,
+ type PackageMeta,
+} from '../../../../generated/packageRegistry';
import {components} from '../../../../generated/componentRegistry';
import {ReferenceDocView} from '../../../../components/docs/ReferenceDocView';
import {TokensDocView} from '../../../../components/docs/TokensDocView';
@@ -46,18 +49,19 @@ function isThemePackage(name: string): boolean {
return name.includes('theme-');
}
-function getInstallSteps(pkgName: string): InstallStep[] {
- if (pkgName.endsWith('/cli')) {
+function getInstallSteps(pkg: PackageMeta): InstallStep[] {
+ const installTarget = pkg.canaryOnly ? `${pkg.name}@canary` : pkg.name;
+ if (pkg.name.endsWith('/cli')) {
return [
- {label: 'Install the CLI', code: `npm install -D ${pkgName}`},
+ {label: 'Install the CLI', code: `npm install -D ${installTarget}`},
{label: 'Run a command', code: `npx @astryxdesign/cli component --list`},
];
}
return [
- {label: 'Install the package', code: `npm install ${pkgName}`},
+ {label: 'Install the package', code: `npm install ${installTarget}`},
{
label: 'Import a component',
- code: `import {...} from '${pkgName}/ComponentName';`,
+ code: `import {...} from '${pkg.name}/ComponentName';`,
language: 'typescript',
},
];
@@ -148,7 +152,8 @@ export default async function DocPage({
notFound();
}
- const isComponentPkg = pkg.name === '@astryxdesign/core';
+ const isCorePackage = pkg.name === '@astryxdesign/core';
+ const firstComponent = components[pkg.name]?.find(comp => !comp.hidden);
return (
<PackageStubPage
@@ -156,14 +161,17 @@ export default async function DocPage({
description={pkg.description}
version={pkg.version}
readme={pkg.readme}
- installSteps={getInstallSteps(pkg.name)}
+ installSteps={getInstallSteps(pkg)}
cta={
- isComponentPkg
- ? {label: 'View Components', href: '/components/Button'}
+ firstComponent
+ ? {
+ label: 'View Components',
+ href: `/components/${firstComponent.name}`,
+ }
: undefined
}
- stripSections={isComponentPkg ? CORE_STRIP_SECTIONS : undefined}
- stripIntro={isComponentPkg}
+ stripSections={isCorePackage ? CORE_STRIP_SECTIONS : undefined}
+ stripIntro={isCorePackage}
/>
);
}
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.css
index ce55a055e9..1f8192d179 100644
--- a/apps/docsite/src/app/globals.css
+++ b/apps/docsite/src/app/globals.css
@@ -2,6 +2,9 @@
@import "@astryxdesign/core/reset.css";
@import "@astryxdesign/core/astryx.css";
+/* Package CSS is generated from packages visible to this docs target, so
+ canary-only styles never enter the production build. */
+@import "../generated/package-styles.css";
/* Aggregated theme CSS — auto-generated by scripts/generate-data.mjs
from every @astryxdesign/theme-* package in this app's dependencies. New
themes are picked up automatically; no edit here required. */
diff --git a/apps/docsite/src/app/mcp/route.ts b/apps/docsite/src/app/mcp/route.ts
index 0e6972271b..6796ff9206 100644
--- a/apps/docsite/src/app/mcp/route.ts
+++ b/apps/docsite/src/app/mcp/route.ts
@@ -31,6 +31,17 @@ import type {TemplateEntry} from '../../generated/templateRegistry';
const allComponents: ComponentEntry[] = Object.values(components).flat();
const visibleComponents = allComponents.filter(c => !c.hidden);
+function componentImport(comp: ComponentEntry): string {
+ const importPath = comp.importPath ?? `@astryxdesign/core/${comp.name}`;
+ return `import {${comp.moduleName}} from '${importPath}';`;
+}
+
+function componentInstall(comp: ComponentEntry): string {
+ const importPath = comp.importPath ?? '@astryxdesign/core';
+ const packageName = /^@[^/]+\/[^/]+/.exec(importPath)?.[0] ?? importPath;
+ return `npm install ${packageName}${comp.isReady ? '' : '@canary'}`;
+}
+
// ── Keyword Index ──────────────────────────────────────────────────────
// Built from the `keywords` field on each component's .doc.mjs file.
// Inverts keyword[] → component name so natural language queries resolve
@@ -115,7 +126,7 @@ const handler = createMcpHandler(
server.tool(
'search',
`Search Astryx (XDS) design system: finds components, documentation topics, and page templates.\n\n` +
- `Returns brief results (name, description, key info). Use the "get" tool with a ` +
+ `Returns brief results (name, description, key info). Components include isReady and the required install command; components that are not ready install from @canary. Use the "get" tool with a ` +
`specific name for full details including props and code examples.\n\n` +
`Examples: "dropdown menu", "form inputs", "theming", "dashboard template", ` +
`"sidebar navigation", "toast notification", "table with sorting", "success message"`,
@@ -214,7 +225,9 @@ const handler = createMcpHandler(
moduleName: comp.moduleName,
group: comp.group,
description: comp.description,
- import: `import {${comp.moduleName}} from '@astryxdesign/core/${comp.name}';`,
+ isReady: comp.isReady,
+ install: componentInstall(comp),
+ import: componentImport(comp),
keyProps: comp.props
.filter(
p =>
@@ -281,7 +294,7 @@ const handler = createMcpHandler(
server.tool(
'get',
`Get full documentation for a specific Astryx (XDS) component, doc topic, or template by name.\n\n` +
- `Returns complete props, usage guidelines, code examples, and theming info.\n\n` +
+ `Returns complete props, usage guidelines, code examples, theming info, isReady, and the required install command. Components that are not ready install from @canary.\n\n` +
`For doc topics, optionally pass a section name to get just that section ` +
`(recommended for large topics like "theme" to avoid context overload).\n\n` +
`Examples:\n` +
@@ -350,9 +363,11 @@ const handler = createMcpHandler(
const result = {
name: comp.name,
moduleName: comp.moduleName,
- import: `import {${comp.moduleName}} from '@astryxdesign/core/${comp.name}';`,
+ import: componentImport(comp),
group: comp.group,
description: comp.description,
+ isReady: comp.isReady,
+ install: componentInstall(comp),
props: comp.props,
usage: comp.usage,
theming: comp.theming,
@@ -384,8 +399,10 @@ const handler = createMcpHandler(
groupMembers: groupMembers.slice(0, 6).map(m => ({
name: m.name,
moduleName: m.moduleName,
- import: `import {${m.moduleName}} from '@astryxdesign/core/${m.name}';`,
+ import: componentImport(m),
description: m.description.slice(0, 120),
+ isReady: m.isReady,
+ install: componentInstall(m),
...(m.params
? {
returns: (m.returns ?? [])
@@ -518,8 +535,10 @@ const handler = createMcpHandler(
.map(c => ({
name: c.name,
moduleName: c.moduleName,
- import: `import {${c.moduleName}} from '@astryxdesign/core/${c.name}';`,
+ import: componentImport(c),
description: c.description,
+ isReady: c.isReady,
+ install: componentInstall(c),
}))
: [];
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index 01aad7e73a..eb059acac4 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -4,17 +4,22 @@
import {useState, useMemo} from 'react';
import {usePathname} from 'next/navigation';
-import {Search} from 'lucide-react';
+import {Search, FlaskConical} from 'lucide-react';
+import * as stylex from '@stylexjs/stylex';
import {AppShell} from '@astryxdesign/core/AppShell';
import {SideNav, SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
import {TextInput} from '@astryxdesign/core/TextInput';
+import {Icon} from '@astryxdesign/core/Icon';
import {SharedTopNav} from './SharedTopNav';
import {CanaryBanner} from './CanaryBanner';
import {CURRENT_TARGET} from '../lib/docsVersions';
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
-import type {GroupedEntry} from '../generated/groupedComponentRegistry';
-import {getComponentSidebarData} from './componentSidebarData';
+import {
+ getComponentSidebarData,
+ type ComponentSidebarEntry,
+ type ComponentSidebarItem,
+} from './componentSidebarData';
interface DocsShellProps {
children: React.ReactNode;
@@ -22,6 +27,24 @@ interface DocsShellProps {
docTopics: DocTopic[];
}
+const styles = stylex.create({
+ canaryMarker: {
+ alignItems: 'center',
+ display: 'inline-flex',
+ height: 24,
+ justifyContent: 'center',
+ width: 24,
+ },
+});
+
+function CanaryCategoryMarker() {
+ return (
+ <span {...stylex.props(styles.canaryMarker)}>
+ <Icon icon={FlaskConical} label="Canary" size="sm" />
+ </span>
+ );
+}
+
/** Foundations: tokens first, then alphabetical */
const foundationsSort = (a: DocTopic, b: DocTopic) => {
if (a.topic === 'tokens') {
@@ -39,43 +62,43 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
const pathname = usePathname();
const [componentQuery, setComponentQuery] = useState('');
- const {componentItems, utilities} = getComponentSidebarData();
+ const {componentItems, utilities, canaryCategories} =
+ getComponentSidebarData();
const q = componentQuery.trim().toLowerCase();
- // When searching, flatten groups to individual entries so results are
- // all at the same level with no nesting.
- const flatSearchResults = useMemo<GroupedEntry[]>(() => {
+ // When searching, flatten every readiness category to individual entries so
+ // results are all at the same level with no nesting.
+ const flatSearchResults = useMemo<ComponentSidebarEntry[]>(() => {
if (!q) {
return [];
}
- return componentItems.flatMap(item => {
+ const allItems = [
+ ...componentItems,
+ ...canaryCategories.flatMap(category => category.componentItems),
+ ];
+ return allItems.flatMap(item => {
if (item.type === 'entry') {
return item.displayName.toLowerCase().includes(q) ? [item] : [];
}
- return item.entries
- .filter(e => e.displayName.toLowerCase().includes(q))
- .map(e => ({
- type: 'entry' as const,
- name: e.name,
- displayName: e.displayName,
- href: e.href,
- description: '',
- }));
+ return item.entries.filter(e => e.displayName.toLowerCase().includes(q));
});
- }, [componentItems, q]);
+ }, [canaryCategories, componentItems, q]);
- const filteredUtilities = useMemo(
- () =>
- q
- ? utilities.filter(u => u.displayName.toLowerCase().includes(q))
- : utilities,
- [utilities, q],
- );
+ const filteredUtilities = useMemo(() => {
+ const allUtilities = [
+ ...utilities,
+ ...canaryCategories.flatMap(category => category.utilities),
+ ];
+ return q
+ ? allUtilities.filter(u => u.displayName.toLowerCase().includes(q))
+ : utilities;
+ }, [canaryCategories, utilities, q]);
// Classify packages
const isTheme = (p: PackageMeta) => p.name.includes('theme-');
- const libraryPackages = packages.filter(p => !isTheme(p));
+ const libraryPackages = packages.filter(p => !isTheme(p) && !p.canaryOnly);
+ const canaryPackages = packages.filter(p => !isTheme(p) && p.canaryOnly);
// Classify doc topics by category (from data). Getting Started is promoted
// to a top-level nav item, so it is excluded from the Guide section.
@@ -104,6 +127,34 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
/>
);
+ const renderComponentItems = (items: ComponentSidebarItem[]) =>
+ items.map(item =>
+ item.type === 'entry' ? (
+ <SideNavItem
+ key={`${item.packageName}:${item.name}`}
+ label={item.displayName}
+ href={item.href}
+ isSelected={pathname === item.href}
+ />
+ ) : (
+ <SideNavItem
+ key={`${item.packageName}:${item.label}`}
+ label={item.displayName}
+ collapsible={{
+ defaultIsCollapsed: !item.entries.some(e => pathname === e.href),
+ }}>
+ {item.entries.map(entry => (
+ <SideNavItem
+ key={`${entry.packageName}:${entry.name}`}
+ label={entry.displayName}
+ href={entry.href}
+ isSelected={pathname === entry.href}
+ />
+ ))}
+ </SideNavItem>
+ ),
+ );
+
return (
<AppShell
variant="surface"
@@ -160,7 +211,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
</SideNavItem>
</SideNavSection>
- {/* Libraries */}
+ {/* Stable libraries */}
<SideNavSection title="Libraries" isHeaderHidden>
<SideNavItem
label="Libraries"
@@ -178,6 +229,23 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
))}
</SideNavItem>
</SideNavSection>
+
+ {canaryPackages.length > 0 && (
+ <SideNavSection title="Canary libraries" isHeaderHidden>
+ {canaryPackages.map(p => (
+ <SideNavItem
+ key={p.name}
+ label={p.displayName}
+ endContent={<CanaryCategoryMarker />}
+ href={`/docs/${p.name.replace('@astryxdesign/', '')}`}
+ isSelected={
+ pathname ===
+ `/docs/${p.name.replace('@astryxdesign/', '')}`
+ }
+ />
+ ))}
+ </SideNavSection>
+ )}
</>
)}
@@ -195,47 +263,20 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
{q
? flatSearchResults.map(item => (
<SideNavItem
- key={item.name}
+ key={`${item.packageName}:${item.name}`}
label={item.displayName}
href={item.href}
isSelected={pathname === item.href}
/>
))
- : componentItems.map(item =>
- item.type === 'entry' ? (
- <SideNavItem
- key={item.name}
- label={item.displayName}
- href={item.href}
- isSelected={pathname === item.href}
- />
- ) : (
- <SideNavItem
- key={item.label}
- label={item.displayName}
- collapsible={{
- defaultIsCollapsed: !item.entries.some(
- e => pathname === e.href,
- ),
- }}>
- {item.entries.map(entry => (
- <SideNavItem
- key={entry.name}
- label={entry.displayName}
- href={entry.href}
- isSelected={pathname === entry.href}
- />
- ))}
- </SideNavItem>
- ),
- )}
+ : renderComponentItems(componentItems)}
{/* Utilities — secondary list rendered below the main Components
section. Always starts collapsed; users can expand on demand. */}
{filteredUtilities.length > 0 &&
(q ? (
filteredUtilities.map(comp => (
<SideNavItem
- key={comp.name}
+ key={`${comp.packageName}:${comp.name}`}
label={comp.displayName}
href={comp.href}
isSelected={pathname === comp.href}
@@ -247,7 +288,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
collapsible={{defaultIsCollapsed: true}}>
{utilities.map(comp => (
<SideNavItem
- key={comp.name}
+ key={`${comp.packageName}:${comp.name}`}
label={comp.displayName}
href={comp.href}
isSelected={pathname === comp.href}
@@ -256,6 +297,41 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
</SideNavItem>
))}
</SideNavSection>
+
+ {!q && canaryCategories.length > 0 && (
+ <SideNavSection title="Canary components" isHeaderHidden>
+ {canaryCategories.map(category => (
+ <SideNavItem
+ key={category.packageName}
+ label={category.displayName}
+ endContent={<CanaryCategoryMarker />}
+ collapsible={{
+ defaultIsCollapsed: ![
+ ...category.componentItems.flatMap(item =>
+ item.type === 'entry' ? [item] : item.entries,
+ ),
+ ...category.utilities,
+ ].some(entry => pathname === entry.href),
+ }}>
+ {renderComponentItems(category.componentItems)}
+ {category.utilities.length > 0 && (
+ <SideNavItem
+ label="Utilities"
+ collapsible={{defaultIsCollapsed: true}}>
+ {category.utilities.map(comp => (
+ <SideNavItem
+ key={`${comp.packageName}:${comp.name}`}
+ label={comp.displayName}
+ href={comp.href}
+ isSelected={pathname === comp.href}
+ />
+ ))}
+ </SideNavItem>
+ )}
+ </SideNavItem>
+ ))}
+ </SideNavSection>
+ )}
</>
)}
</SideNav>
diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsx
index 08d9e5a47e..c1d296503e 100644
--- a/apps/docsite/src/components/SearchPalette.tsx
+++ b/apps/docsite/src/components/SearchPalette.tsx
@@ -5,6 +5,7 @@
import {useMemo, useCallback} from 'react';
import {useRouter} from 'next/navigation';
import {CommandPalette} from '@astryxdesign/core/CommandPalette';
+import {Text} from '@astryxdesign/core/Text';
import {createStaticSource} from '@astryxdesign/core/Typeahead';
import type {ComponentEntry} from '../generated/componentRegistry';
import type {PackageMeta} from '../generated/packageRegistry';
@@ -77,6 +78,7 @@ export function SearchPalette({
isOpen={isOpen}
onOpenChange={onOpenChange}
searchSource={searchSource}
+ renderItem={item => <Text type="inherit">{item.label}</Text>}
label="Search docs, components, and templates"
value=""
onValueChange={handleValueChange}
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index d35bb74774..4744a64a46 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -352,8 +352,10 @@ export function ComponentDetailClient({
<VStack gap={2}>
<Text type="display-1">{comp.displayName}</Text>
<Text type="supporting" color="secondary">
+ {!comp.isReady ? 'Canary · ' : ''}
{pkg}
{pkgVersion ? ` v${pkgVersion}` : ''} · {comp.moduleName}
+ {!comp.isReady && pkg ? ` · npm install ${pkg}@canary` : ''}
</Text>
</VStack>
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index f0d93e6cea..96f4f10113 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -4,6 +4,7 @@
import {
createElement,
+ Suspense,
useMemo,
useState,
useCallback,
@@ -404,55 +405,62 @@ export function InteractivePreviewStage({
width: '100%',
padding: 'var(--spacing-4)',
}}>
- <PreviewErrorBoundary
- resetKeys={[Component, runtimeState, WrapperComponent]}>
- {playground?.appShellMobile === true ? (
- <AppShellMobilePreviewProvider>
+ <Suspense
+ fallback={
+ <Text type="supporting" color="secondary">
+ Loading preview…
+ </Text>
+ }>
+ <PreviewErrorBoundary
+ resetKeys={[Component, runtimeState, WrapperComponent]}>
+ {playground?.appShellMobile === true ? (
+ <AppShellMobilePreviewProvider>
+ <VStack
+ gap={2}
+ style={{alignItems: 'center', textAlign: 'center'}}>
+ {renderPreview(createElement(Component, runtimeState))}
+ <Text type="supporting" color="secondary">
+ Simulated mobile AppShell — in an app this renders only
+ below the mobile breakpoint.
+ </Text>
+ </VStack>
+ </AppShellMobilePreviewProvider>
+ ) : (
+ renderPreview(createElement(Component, runtimeState))
+ )}
+ {isOverlayPreviewClosed(playground, state) && (
<VStack
gap={2}
- style={{alignItems: 'center', textAlign: 'center'}}>
- {renderPreview(createElement(Component, runtimeState))}
+ style={{
+ alignItems: 'center',
+ paddingBlock: 24,
+ paddingInline: 16,
+ textAlign: 'center',
+ }}>
<Text type="supporting" color="secondary">
- Simulated mobile AppShell — in an app this renders only
- below the mobile breakpoint.
+ Opens as a full-screen overlay — nothing renders while it
+ is closed.
</Text>
+ {onPropChange != null &&
+ overlayControl != null &&
+ (overlayControl.stateProp !== 'isOpen' ||
+ canControlOpenState) && (
+ <Button
+ label="Open preview"
+ variant="secondary"
+ size="sm"
+ onClick={() =>
+ onPropChange(
+ overlayControl.stateProp,
+ overlayControl.openValue,
+ )
+ }
+ />
+ )}
</VStack>
- </AppShellMobilePreviewProvider>
- ) : (
- renderPreview(createElement(Component, runtimeState))
- )}
- {isOverlayPreviewClosed(playground, state) && (
- <VStack
- gap={2}
- style={{
- alignItems: 'center',
- paddingBlock: 24,
- paddingInline: 16,
- textAlign: 'center',
- }}>
- <Text type="supporting" color="secondary">
- Opens as a full-screen overlay — nothing renders while it is
- closed.
- </Text>
- {onPropChange != null &&
- overlayControl != null &&
- (overlayControl.stateProp !== 'isOpen' ||
- canControlOpenState) && (
- <Button
- label="Open preview"
- variant="secondary"
- size="sm"
- onClick={() =>
- onPropChange(
- overlayControl.stateProp,
- overlayControl.openValue,
- )
- }
- />
- )}
- </VStack>
- )}
- </PreviewErrorBoundary>
+ )}
+ </PreviewErrorBoundary>
+ </Suspense>
</Center>
)}
</Card>
diff --git a/apps/docsite/src/components/component-detail/resolveElements.ts b/apps/docsite/src/components/component-detail/resolveElements.ts
index 9aae7963e2..b6ab82b7a1 100644
--- a/apps/docsite/src/components/component-detail/resolveElements.ts
+++ b/apps/docsite/src/components/component-detail/resolveElements.ts
@@ -13,6 +13,7 @@ import {
type ComponentType,
} from 'react';
import * as Core from '@astryxdesign/core';
+import {externalComponentPreviews} from '../../generated/componentPreviewRegistry';
import type {ElementDescriptor} from '../../generated/componentRegistry';
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -30,8 +31,14 @@ export function getComponent(name: string): AnyComponent | null {
return undefined;
}
};
- const value = readExport(name) ?? readExport(`XDS${name}`);
- return typeof value === 'function' ? (value as AnyComponent) : null;
+ const value =
+ readExport(name) ??
+ readExport(`XDS${name}`) ??
+ externalComponentPreviews[name];
+ return typeof value === 'function' ||
+ (value != null && typeof value === 'object')
+ ? (value as AnyComponent)
+ : null;
}
export function isElementDescriptor(v: unknown): v is ElementDescriptor {
diff --git a/apps/docsite/src/components/componentSidebarData.ts b/apps/docsite/src/components/componentSidebarData.ts
index f90196f95f..1b66c8eba9 100644
--- a/apps/docsite/src/components/componentSidebarData.ts
+++ b/apps/docsite/src/components/componentSidebarData.ts
@@ -1,59 +1,209 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {components} from '../generated/componentRegistry';
import {groupedComponents} from '../generated/groupedComponentRegistry';
+import {packages} from '../generated/packageRegistry';
import type {
ComponentItem,
GroupedEntry,
+ GroupedGroup,
} from '../generated/groupedComponentRegistry';
+export interface ComponentSidebarEntry extends GroupedEntry {
+ packageName: string;
+ isReady: boolean;
+}
+
+export interface ComponentSidebarGroup extends Omit<GroupedGroup, 'entries'> {
+ packageName: string;
+ isReady: boolean;
+ entries: ComponentSidebarEntry[];
+}
+
+export type ComponentSidebarItem =
+ ComponentSidebarEntry | ComponentSidebarGroup;
+
+export interface CanaryComponentCategory {
+ packageName: string;
+ displayName: string;
+ componentItems: ComponentSidebarItem[];
+ utilities: ComponentSidebarEntry[];
+}
+
export interface ComponentSidebarData {
- componentItems: ComponentItem[];
- utilities: Array<{name: string; displayName: string; href: string}>;
+ componentItems: ComponentSidebarItem[];
+ utilities: ComponentSidebarEntry[];
+ canaryCategories: CanaryComponentCategory[];
}
-/**
- * Single source of truth for the component sidebar. Other navigation surfaces
- * that should mirror the sidebar (for example the command palette) should use
- * this helper instead of independently filtering componentRegistry entries.
- */
-export function getComponentSidebarData(): ComponentSidebarData {
- const grouped = groupedComponents['@astryxdesign/core'];
- if (!grouped) {
- return {componentItems: [], utilities: []};
+const componentReadiness = new Map(
+ Object.entries(components).flatMap(([packageName, entries]) =>
+ entries.map(entry => [`${packageName}:${entry.name}`, entry.isReady]),
+ ),
+);
+
+const packageDisplayNames = new Map(
+ packages.map(pkg => [pkg.name, pkg.displayName]),
+);
+
+function enrichEntry(
+ entry: GroupedEntry,
+ packageName: string,
+): ComponentSidebarEntry {
+ return {
+ ...entry,
+ packageName,
+ isReady: componentReadiness.get(`${packageName}:${entry.name}`) ?? true,
+ };
+}
+
+function enrichItem(
+ item: ComponentItem,
+ packageName: string,
+): ComponentSidebarItem {
+ if (item.type === 'entry') {
+ return enrichEntry(item, packageName);
}
- return {componentItems: grouped.items, utilities: grouped.utilities};
+ const entries = item.entries.map(entry =>
+ enrichEntry({...entry, type: 'entry', description: ''}, packageName),
+ );
+ return {
+ ...item,
+ packageName,
+ isReady: entries.every(entry => entry.isReady),
+ entries,
+ };
}
-export function flattenComponentSidebarEntries(
- {componentItems, utilities}: ComponentSidebarData = getComponentSidebarData(),
-): GroupedEntry[] {
- const entries: GroupedEntry[] = [];
+function sortItems(items: ComponentSidebarItem[]) {
+ items.sort((a, b) => {
+ const aKey = a.type === 'entry' ? a.name : a.label;
+ const bKey = b.type === 'entry' ? b.name : b.label;
+ return aKey.localeCompare(bKey);
+ });
+}
+
+function addMergedItem(
+ items: ComponentSidebarItem[],
+ groups: Map<string, ComponentSidebarGroup>,
+ item: ComponentSidebarItem,
+) {
+ if (item.type === 'entry') {
+ items.push(item);
+ return;
+ }
+ const existing = groups.get(item.label);
+ if (!existing) {
+ groups.set(item.label, item);
+ return;
+ }
+ existing.entries.push(...item.entries);
+ existing.entries.sort((a, b) => a.name.localeCompare(b.name));
+ if (existing.packageName !== item.packageName) {
+ existing.packageName = 'multiple';
+ }
+}
- for (const item of componentItems) {
+function packageItems(
+ packageName: string,
+ isReady: boolean,
+): {
+ componentItems: ComponentSidebarItem[];
+ utilities: ComponentSidebarEntry[];
+} {
+ const grouped = groupedComponents[packageName];
+ const componentItems: ComponentSidebarItem[] = [];
+ const utilities = grouped.utilities
+ .map(entry =>
+ enrichEntry({...entry, type: 'entry', description: ''}, packageName),
+ )
+ .filter(entry => entry.isReady === isReady);
+
+ for (const rawItem of grouped.items) {
+ const item = enrichItem(rawItem, packageName);
if (item.type === 'entry') {
- entries.push(item);
- } else {
- entries.push(
- ...item.entries.map(entry => ({
- type: 'entry' as const,
- name: entry.name,
- displayName: entry.displayName,
- href: entry.href,
- description: '',
- })),
- );
+ if (item.isReady === isReady) {
+ componentItems.push(item);
+ }
+ continue;
+ }
+ const entries = item.entries.filter(entry => entry.isReady === isReady);
+ if (entries.length > 0) {
+ componentItems.push({...item, entries, isReady});
}
}
- entries.push(
- ...utilities.map(entry => ({
- type: 'entry' as const,
- name: entry.name,
- displayName: entry.displayName,
- href: entry.href,
- description: '',
- })),
+ sortItems(componentItems);
+ utilities.sort((a, b) => a.name.localeCompare(b.name));
+ return {componentItems, utilities};
+}
+
+/**
+ * Single source of truth for the component sidebar. Ready components retain
+ * the unified family view. Components that are not ready are separated by
+ * their owning package, so the canary category carries their release status
+ * once instead of repeating it on every child.
+ */
+export function getComponentSidebarData(): ComponentSidebarData {
+ const componentItems: ComponentSidebarItem[] = [];
+ const componentGroups = new Map<string, ComponentSidebarGroup>();
+ const utilities: ComponentSidebarEntry[] = [];
+ const canaryCategories: CanaryComponentCategory[] = [];
+
+ const groupedPackages = Object.keys(groupedComponents).sort(
+ (a, b) =>
+ Number(b === '@astryxdesign/core') - Number(a === '@astryxdesign/core'),
);
+ for (const packageName of groupedPackages) {
+ const ready = packageItems(packageName, true);
+ for (const item of ready.componentItems) {
+ addMergedItem(componentItems, componentGroups, item);
+ }
+ utilities.push(...ready.utilities);
+
+ const canary = packageItems(packageName, false);
+ if (canary.componentItems.length > 0 || canary.utilities.length > 0) {
+ canaryCategories.push({
+ packageName,
+ displayName: packageDisplayNames.get(packageName) ?? packageName,
+ ...canary,
+ });
+ }
+ }
+
+ componentItems.push(...componentGroups.values());
+ sortItems(componentItems);
+ utilities.sort((a, b) => a.name.localeCompare(b.name));
+ canaryCategories.sort((a, b) => a.displayName.localeCompare(b.displayName));
+
+ return {componentItems, utilities, canaryCategories};
+}
+
+export function flattenComponentSidebarEntries(
+ {
+ componentItems,
+ utilities,
+ canaryCategories,
+ }: ComponentSidebarData = getComponentSidebarData(),
+): ComponentSidebarEntry[] {
+ const entries: ComponentSidebarEntry[] = [];
+
+ const appendItems = (items: ComponentSidebarItem[]) => {
+ for (const item of items) {
+ if (item.type === 'entry') {
+ entries.push(item);
+ } else {
+ entries.push(...item.entries);
+ }
+ }
+ };
+
+ appendItems(componentItems);
+ entries.push(...utilities);
+ for (const category of canaryCategories) {
+ appendItems(category.componentItems);
+ entries.push(...category.utilities);
+ }
return entries;
}
diff --git a/apps/docsite/src/components/searchPaletteData.ts b/apps/docsite/src/components/searchPaletteData.ts
index 7b0049a603..0c58217010 100644
--- a/apps/docsite/src/components/searchPaletteData.ts
+++ b/apps/docsite/src/components/searchPaletteData.ts
@@ -10,6 +10,7 @@ import {flattenComponentSidebarEntries} from './componentSidebarData';
export interface SearchItemAuxiliaryData {
group: string;
keywords: string[];
+ isReady: boolean;
}
export interface SearchItem extends SearchableItem<SearchItemAuxiliaryData> {
@@ -65,10 +66,13 @@ export function buildSearchPaletteItems({
id: entry.href,
label: entry.displayName,
auxiliaryData: {
- group: 'Component',
+ group: entry.isReady ? 'Component' : 'Canary component',
+ isReady: entry.isReady,
keywords: uniqueKeywords([
entry.name,
entry.displayName,
+ entry.packageName,
+ entry.isReady ? null : 'canary',
comp?.moduleName,
...(comp?.keywords ?? []),
]),
@@ -89,7 +93,8 @@ export function buildSearchPaletteItems({
: `/docs/${pkg.name.replace('@astryxdesign/', '')}`,
label: pkg.displayName,
auxiliaryData: {
- group: 'Package',
+ group: pkg.canaryOnly ? 'Canary package' : 'Package',
+ isReady: !pkg.canaryOnly,
keywords: uniqueKeywords([pkg.name, pkg.displayName]),
},
});
@@ -101,6 +106,7 @@ export function buildSearchPaletteItems({
label: doc.title,
auxiliaryData: {
group: doc.category === 'guide' ? 'Guide' : 'Foundations',
+ isReady: true,
keywords: uniqueKeywords([doc.topic, doc.title, doc.category]),
},
});
@@ -112,6 +118,7 @@ export function buildSearchPaletteItems({
label: tmpl.name,
auxiliaryData: {
group: 'Template',
+ isReady: true,
keywords: uniqueKeywords([tmpl.slug, tmpl.name, tmpl.category]),
},
});
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 4e731a0edd..548887ab19 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -46,5 +46,9 @@
{
"component": "unknown/ChartTooltip",
"reason": "ChartTooltip uses explicitly physical left/right/top viewport placement and clamping. It has no logical start/end placement, direction-dependent control order, horizontal scrolling action, or coarse form hit target; tooltip rows inherit bidi layout without component-specific directional logic."
+ },
+ {
+ "component": "unknown/ThreeD",
+ "reason": "The ThreeD documentation family renders Cartesian x/y/z data visualizations in SVG and WebGL. Its axes and pointer-drag rotation are physical data-space interactions that intentionally remain invariant across writing directions; it has no reading-order controls, inline-start/end placement, directional glyphs, or overlays to mirror."
}
]
diff --git a/package.json b/package.json
index 4b2fd82d72..0f38eab881 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
"private": true,
"license": "MIT",
"scripts": {
- "build": "pnpm -F @astryxdesign/build build && pnpm -F @astryxdesign/core build && pnpm -F @astryxdesign/lab build && pnpm -F @astryxdesign/charts build && pnpm -F @astryxdesign/vega build && pnpm -F @astryxdesign/theme-neutral build && pnpm -F @astryxdesign/theme-matcha build && pnpm -F @astryxdesign/theme-stone build && pnpm -F @astryxdesign/theme-gothic build && pnpm -F @astryxdesign/theme-chocolate build && pnpm -F @astryxdesign/theme-y2k build && pnpm -F @astryxdesign/theme-butter build && pnpm -F @astryxdesign/theme-probe build && pnpm bundle:cli-themes && pnpm -F @astryxdesign/cli sync:api-types",
+ "build": "pnpm -F @astryxdesign/build build && pnpm -F @astryxdesign/core build && pnpm -F @astryxdesign/lab build && pnpm -F @astryxdesign/charts build && pnpm -F @astryxdesign/richtext build && pnpm -F @astryxdesign/vega build && pnpm -F @astryxdesign/theme-neutral build && pnpm -F @astryxdesign/theme-matcha build && pnpm -F @astryxdesign/theme-stone build && pnpm -F @astryxdesign/theme-gothic build && pnpm -F @astryxdesign/theme-chocolate build && pnpm -F @astryxdesign/theme-y2k build && pnpm -F @astryxdesign/theme-butter build && pnpm -F @astryxdesign/theme-probe build && pnpm bundle:cli-themes && pnpm -F @astryxdesign/cli sync:api-types",
"bundle:cli-themes": "node scripts/generate-cli-themes.mjs",
"dev": "pnpm -F @astryxdesign/storybook dev",
"test": "vitest run",
diff --git a/packages/charts/astryx.integration.mjs b/packages/charts/astryx.integration.mjs
new file mode 100644
index 0000000000..b46ee20ece
--- /dev/null
+++ b/packages/charts/astryx.integration.mjs
@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx CLI integration for the canary-only Charts package.
+ * Package identity and version come from package.json.
+ */
+export default {
+ components: './src',
+ templates: './blocks',
+ issuesUrl: 'https://github.com/facebook/astryx/issues',
+};
diff --git a/packages/charts/blocks/ChartShowcase.template.mjs b/packages/charts/blocks/ChartShowcase.template.mjs
new file mode 100644
index 0000000000..7652ea38be
--- /dev/null
+++ b/packages/charts/blocks/ChartShowcase.template.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'block',
+ name: 'Chart',
+ displayName: 'Chart',
+ description: 'A responsive monthly revenue bar chart.',
+ exampleFor: 'Chart',
+ aspectRatio: 16 / 10,
+ isShowcase: true,
+ alsoShowcaseFor: ['ChartBar'],
+ componentsUsed: ['Chart', 'ChartAxis', 'ChartGrid'],
+};
diff --git a/packages/charts/blocks/ChartShowcase.tsx b/packages/charts/blocks/ChartShowcase.tsx
new file mode 100644
index 0000000000..e655315e06
--- /dev/null
+++ b/packages/charts/blocks/ChartShowcase.tsx
@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Chart, ChartAxis, ChartGrid, bar} from '@astryxdesign/charts';
+
+const monthlyRevenue = [
+ {month: 'Jan', revenue: 42},
+ {month: 'Feb', revenue: 58},
+ {month: 'Mar', revenue: 51},
+ {month: 'Apr', revenue: 74},
+ {month: 'May', revenue: 68},
+ {month: 'Jun', revenue: 86},
+];
+
+export default function ChartShowcase() {
+ return (
+ <Chart
+ data={monthlyRevenue}
+ xKey="month"
+ series={[bar('revenue', {label: 'Revenue'})]}
+ tooltip
+ grid={<ChartGrid horizontal />}
+ axes={
+ <>
+ <ChartAxis position="bottom" />
+ <ChartAxis position="left" />
+ </>
+ }
+ height={260}
+ />
+ );
+}
diff --git a/packages/charts/package.json b/packages/charts/package.json
index ffd3b6b4d9..49f44ed154 100644
--- a/packages/charts/package.json
+++ b/packages/charts/package.json
@@ -29,6 +29,8 @@
"types": "./dist/index.d.ts",
"sideEffects": false,
"files": [
+ "astryx.integration.mjs",
+ "blocks",
"dist",
"src",
"README.md",
diff --git a/packages/charts/tsconfig.docs.json b/packages/charts/tsconfig.docs.json
index f19aeb0097..13f1e12f3f 100644
--- a/packages/charts/tsconfig.docs.json
+++ b/packages/charts/tsconfig.docs.json
@@ -6,5 +6,5 @@
"checkJs": true,
"noEmit": true
},
- "include": ["src/**/*.doc.mjs"]
+ "include": ["src/**/*.doc.mjs", "blocks/**/*"]
}
diff --git a/packages/cli/api/template/list/list.mjs b/packages/cli/api/template/list/list.mjs
index 689a8eb881..5462e7335f 100644
--- a/packages/cli/api/template/list/list.mjs
+++ b/packages/cli/api/template/list/list.mjs
@@ -21,17 +21,24 @@ export function templateList(templates, options = {}) {
const {type, package: packageFilter} = options;
let filtered = templates;
if (type) filtered = filtered.filter(t => t.type === type);
- if (packageFilter) filtered = filtered.filter(t => pkgOf(t) === packageFilter);
+ if (packageFilter)
+ filtered = filtered.filter(t => pkgOf(t) === packageFilter);
return {
type: 'template.list',
data: filtered.map(t => ({
id: t.dirName,
name: t.name,
+ displayName: t.displayName,
description: t.description,
type: t.type,
package: pkgOf(t),
category: t.category || undefined,
componentsUsed: t.componentsUsed ?? undefined,
+ aspectRatio: t.aspectRatio,
+ exampleFor: t.exampleFor,
+ alsoExampleFor: t.alsoExampleFor,
+ alsoShowcaseFor: t.alsoShowcaseFor,
+ isShowcase: t.isShowcase,
// Discovery always sets isReady (defaulting to true), so `?? true` never
// changes the emitted value — it only satisfies the required-boolean
// field type where the DiscoveredTemplate typedef leaves it optional.
diff --git a/packages/cli/api/template/template-integration.test.mjs b/packages/cli/api/template/template-integration.test.mjs
index 5a4e5cb2dd..8181d00a31 100644
--- a/packages/cli/api/template/template-integration.test.mjs
+++ b/packages/cli/api/template/template-integration.test.mjs
@@ -18,9 +18,7 @@ let tmpDir;
let originalCwd;
function makeConsumer() {
- const dir = fs.mkdtempSync(
- path.join(process.cwd(), '.astryx-template-it-'),
- );
+ const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-template-it-'));
fs.writeFileSync(
path.join(dir, 'package.json'),
JSON.stringify({name: 'consumer'}),
@@ -94,6 +92,43 @@ describe('integration template discovery', () => {
expect(entry.description).toBe('pricing desc');
});
+ it('preserves integration block showcase metadata in list output', async () => {
+ const pkgDir = installWidgets(tmpDir);
+ writeTemplate(pkgDir, 'chart-showcase', {
+ kind: 'block',
+ body: `export default {
+ type: 'block',
+ name: 'Chart',
+ displayName: 'Chart',
+ description: 'A chart.',
+ category: 'components/Chart',
+ exampleFor: 'Chart',
+ aspectRatio: 16 / 10,
+ isShowcase: true,
+ alsoExampleFor: ['ChartBar'],
+ alsoShowcaseFor: ['ChartSwatch'],
+ componentsUsed: ['Chart'],
+};\n`,
+ });
+
+ const result = await template(undefined, {
+ list: true,
+ type: 'block',
+ package: '@acme/widgets',
+ cwd: tmpDir,
+ });
+ expect(result.data[0]).toMatchObject({
+ id: 'chart-showcase',
+ displayName: 'Chart',
+ exampleFor: 'Chart',
+ aspectRatio: 1.6,
+ isShowcase: true,
+ alsoExampleFor: ['ChartBar'],
+ alsoShowcaseFor: ['ChartSwatch'],
+ componentsUsed: ['Chart'],
+ });
+ });
+
it('lists nested-id templates (kebab path under root)', async () => {
const pkgDir = installWidgets(tmpDir);
writeTemplate(pkgDir, 'marketing/hero', {kind: 'block'});
diff --git a/packages/cli/api/template/template.type.mjs b/packages/cli/api/template/template.type.mjs
index 80dae9b2e4..d3bc143d4d 100644
--- a/packages/cli/api/template/template.type.mjs
+++ b/packages/cli/api/template/template.type.mjs
@@ -27,11 +27,17 @@
* @typedef {object} TemplateListEntry
* @property {string} id - Stable template id (relative path under the templates root, minus the .doc.* suffix).
* @property {string} name
+ * @property {string} [displayName]
* @property {string} description
* @property {'page' | 'block'} type
* @property {string} package - Owning package; core (built-in) templates report '@astryxdesign/core'.
* @property {string} [category] - Optional grouping/category label.
* @property {string[]} [componentsUsed] - Component display names the template composes.
+ * @property {number} [aspectRatio] - Block preview width/height ratio.
+ * @property {string} [exampleFor] - Component documented by a block.
+ * @property {string[]} [alsoExampleFor] - Additional component pages that receive this example.
+ * @property {string[]} [alsoShowcaseFor] - Additional component pages that reuse this showcase.
+ * @property {boolean} [isShowcase] - Whether a block is the component's primary showcase.
* @property {boolean} isReady
* @property {boolean} [scaffold]
*/
diff --git a/packages/cli/authoring/doctypes/template/parse.mjs b/packages/cli/authoring/doctypes/template/parse.mjs
index bbd5057395..dab04c2251 100644
--- a/packages/cli/authoring/doctypes/template/parse.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.mjs
@@ -4,11 +4,8 @@
* @file Template doc parser (stamped `type: 'page' | 'block'`). Zod is sealed
* here; template discovery calls `parseTemplate` at the load boundary.
*
- * The schema is the minimal INTEGRATION-template envelope (integration templates
- * carry only name/description/category/componentsUsed/preview plus the
- * page|block discriminant). First-party core templates use the richer
- * {@link TemplateDoc} and are loaded separately; `parseTemplate` returns that
- * public type.
+ * Integration templates use the same authored fields as first-party templates;
+ * discovery normalizes the result into the public {@link TemplateDoc} shape.
*/
import {z} from 'zod';
@@ -25,15 +22,30 @@ const previewSchema = z
const baseTemplateFields = {
name: z.string().min(1, 'name is required'),
+ displayName: z.string().min(1).optional(),
description: z.string().min(1, 'description is required'),
category: z.string().optional(),
componentsUsed: z.array(z.string()).optional(),
preview: previewSchema.optional(),
+ isReady: z.boolean().optional(),
+ scaffold: z.boolean().optional(),
+ isHiddenFromOverview: z.boolean().optional(),
};
const templateEnvelopeSchema = z.discriminatedUnion('type', [
z.object({...baseTemplateFields, type: z.literal('page')}).strict(),
- z.object({...baseTemplateFields, type: z.literal('block')}).strict(),
+ z
+ .object({
+ ...baseTemplateFields,
+ type: z.literal('block'),
+ exampleFor: z.string().optional(),
+ alsoExampleFor: z.array(z.string()).optional(),
+ alsoShowcaseFor: z.array(z.string()).optional(),
+ aspectRatio: z.number().positive().optional(),
+ scale: z.number().positive().optional(),
+ isShowcase: z.boolean().optional(),
+ })
+ .strict(),
]);
/**
diff --git a/packages/cli/authoring/doctypes/template/parse.test.mjs b/packages/cli/authoring/doctypes/template/parse.test.mjs
index 55d33e166b..c644d2a14c 100644
--- a/packages/cli/authoring/doctypes/template/parse.test.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.test.mjs
@@ -41,7 +41,26 @@ describe('parseTemplate (load boundary)', () => {
preview: {image: './preview.png', aspectRatio: '16 / 9'},
});
expect(parsed.name).toBe('Hero');
- expect(parsed.preview).toEqual({image: './preview.png', aspectRatio: '16 / 9'});
+ expect(parsed.preview).toEqual({
+ image: './preview.png',
+ aspectRatio: '16 / 9',
+ });
+ });
+
+ it('accepts the shared readiness fields', () => {
+ const parsed = parseTemplate({
+ type: 'page',
+ name: 'Draft',
+ description: 'A draft page.',
+ isReady: false,
+ scaffold: true,
+ isHiddenFromOverview: true,
+ });
+ expect(parsed).toMatchObject({
+ isReady: false,
+ scaffold: true,
+ isHiddenFromOverview: true,
+ });
});
it('rejects a missing name', () => {
@@ -53,7 +72,9 @@ describe('parseTemplate (load boundary)', () => {
});
it('rejects an empty-string name', () => {
- expect(reason({type: 'page', name: '', description: 'x'})).toContain('name');
+ expect(reason({type: 'page', name: '', description: 'x'})).toContain(
+ 'name',
+ );
});
it('rejects a missing/invalid type', () => {
diff --git a/packages/cli/foundation/discovery/template-adapter.mjs b/packages/cli/foundation/discovery/template-adapter.mjs
index 0fa1da19fb..371954ee09 100644
--- a/packages/cli/foundation/discovery/template-adapter.mjs
+++ b/packages/cli/foundation/discovery/template-adapter.mjs
@@ -50,11 +50,15 @@ export function pkgOf(t) {
* @property {'page'|'block'} type
* @property {string} dirName
* @property {string} name
+ * @property {string} [displayName]
* @property {string} description
* @property {string} [category]
* @property {boolean} [isReady]
* @property {boolean} [scaffold]
* @property {number} [aspectRatio]
+ * @property {string} [exampleFor]
+ * @property {string[]} [alsoExampleFor]
+ * @property {string[]} [alsoShowcaseFor]
* @property {string[]} [componentsUsed]
* @property {boolean} [isShowcase]
* @property {string} filePath
@@ -322,7 +326,9 @@ async function discoverBlocks() {
const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
if (!fs.existsSync(tsxPath)) continue;
const doc = await loadDocModule(docPath);
- const relPath = toPosixPath(path.relative(BLOCKS_DIR, path.dirname(docPath)));
+ const relPath = toPosixPath(
+ path.relative(BLOCKS_DIR, path.dirname(docPath)),
+ );
blocks.push({
type: 'block',
dirName: basename,
@@ -340,7 +346,6 @@ async function discoverBlocks() {
return blocks;
}
-
/**
* Discover blocks from external packages that declare `astryx.blocks` in
* their package.json. Same shape as discoverBlocks() output.
@@ -362,7 +367,9 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
if (!fs.existsSync(tsxPath)) continue;
const doc = await loadDocModule(docPath);
- const relPath = toPosixPath(path.relative(ext.blocksDir, path.dirname(docPath)));
+ const relPath = toPosixPath(
+ path.relative(ext.blocksDir, path.dirname(docPath)),
+ );
blocks.push({
type: 'block',
dirName: basename,
@@ -449,7 +456,9 @@ function findIntegrationDocFiles(root) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
- } else if (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+ } else if (
+ ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))
+ ) {
results.push(full);
}
}
@@ -578,10 +587,18 @@ export async function discoverIntegrationTemplatesForOne(integration) {
type,
dirName: id,
name: doc?.name || id,
+ displayName: doc?.displayName,
description: doc?.description || '',
category: doc?.category || '',
- isReady: true,
- scaffold: false,
+ isReady: doc?.isReady ?? true,
+ scaffold: doc?.scaffold ?? false,
+ aspectRatio: doc?.type === 'block' ? doc.aspectRatio : undefined,
+ exampleFor: doc?.type === 'block' ? doc.exampleFor : undefined,
+ alsoExampleFor:
+ doc?.type === 'block' ? (doc.alsoExampleFor ?? []) : undefined,
+ alsoShowcaseFor:
+ doc?.type === 'block' ? (doc.alsoShowcaseFor ?? []) : undefined,
+ isShowcase: doc?.type === 'block' ? (doc.isShowcase ?? false) : undefined,
// The integration envelope carries `componentsUsed` for both page and
// block templates; the rich TemplateDoc union only declares it on blocks,
// so read it off the envelope shape here.
@@ -604,7 +621,9 @@ export async function discoverIntegrationTemplatesForOne(integration) {
export async function findRelatedBlocks(componentName, cwd) {
const blocks = await discoverAllBlocks(cwd);
return blocks.filter(b =>
- (b.componentsUsed ?? []).some(c => c.toLowerCase() === componentName.toLowerCase()),
+ (b.componentsUsed ?? []).some(
+ c => c.toLowerCase() === componentName.toLowerCase(),
+ ),
);
}
diff --git a/packages/lab/astryx.integration.mjs b/packages/lab/astryx.integration.mjs
new file mode 100644
index 0000000000..a44976917a
--- /dev/null
+++ b/packages/lab/astryx.integration.mjs
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx CLI integration for the canary-only Lab package.
+ * Package identity and version come from package.json.
+ */
+export default {
+ components: './src',
+ issuesUrl: 'https://github.com/facebook/astryx/issues',
+};
diff --git a/packages/lab/package.json b/packages/lab/package.json
index 73b05f87b1..cd766cc1be 100644
--- a/packages/lab/package.json
+++ b/packages/lab/package.json
@@ -29,6 +29,7 @@
"types": "./dist/index.d.ts",
"sideEffects": false,
"files": [
+ "astryx.integration.mjs",
"dist",
"src",
"README.md",
diff --git a/packages/lab/src/Chart/ChartArea.doc.mjs b/packages/lab/src/Chart/ChartArea.doc.mjs
index 46f5cd51eb..6503493388 100644
--- a/packages/lab/src/Chart/ChartArea.doc.mjs
+++ b/packages/lab/src/Chart/ChartArea.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartArea',
displayName: 'Chart Area',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartBar.doc.mjs b/packages/lab/src/Chart/ChartBar.doc.mjs
index a0579b28ba..2942c9707c 100644
--- a/packages/lab/src/Chart/ChartBar.doc.mjs
+++ b/packages/lab/src/Chart/ChartBar.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartBar',
displayName: 'Chart Bar',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartCandlestick.doc.mjs b/packages/lab/src/Chart/ChartCandlestick.doc.mjs
index de29d6d7dd..68d342eed7 100644
--- a/packages/lab/src/Chart/ChartCandlestick.doc.mjs
+++ b/packages/lab/src/Chart/ChartCandlestick.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartCandlestick',
displayName: 'Chart Candlestick',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartDot.doc.mjs b/packages/lab/src/Chart/ChartDot.doc.mjs
index 022006ed69..4ac57b76a0 100644
--- a/packages/lab/src/Chart/ChartDot.doc.mjs
+++ b/packages/lab/src/Chart/ChartDot.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartDot',
displayName: 'Chart Dot',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartDotGL.doc.mjs b/packages/lab/src/Chart/ChartDotGL.doc.mjs
index ae41714cf0..f4ce4ef6bd 100644
--- a/packages/lab/src/Chart/ChartDotGL.doc.mjs
+++ b/packages/lab/src/Chart/ChartDotGL.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartDotGL',
displayName: 'Chart Dot GL',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartDotGLInteractive.doc.mjs b/packages/lab/src/Chart/ChartDotGLInteractive.doc.mjs
index 0449e38f8e..14e5969f4f 100644
--- a/packages/lab/src/Chart/ChartDotGLInteractive.doc.mjs
+++ b/packages/lab/src/Chart/ChartDotGLInteractive.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartDotGLInteractive',
displayName: 'Chart Dot GL Interactive',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartHeatmapGL.doc.mjs b/packages/lab/src/Chart/ChartHeatmapGL.doc.mjs
index 53f07d84f4..a10f1fc332 100644
--- a/packages/lab/src/Chart/ChartHeatmapGL.doc.mjs
+++ b/packages/lab/src/Chart/ChartHeatmapGL.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartHeatmapGL',
displayName: 'Chart Heatmap GL',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartLine.doc.mjs b/packages/lab/src/Chart/ChartLine.doc.mjs
index 36c5cce98e..22e74f740d 100644
--- a/packages/lab/src/Chart/ChartLine.doc.mjs
+++ b/packages/lab/src/Chart/ChartLine.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartLine',
displayName: 'Chart Line',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chart/ChartStreamGL.doc.mjs b/packages/lab/src/Chart/ChartStreamGL.doc.mjs
index 613b9ef3be..3fc487d182 100644
--- a/packages/lab/src/Chart/ChartStreamGL.doc.mjs
+++ b/packages/lab/src/Chart/ChartStreamGL.doc.mjs
@@ -5,7 +5,7 @@
export const docs = {
name: 'ChartStreamGL',
displayName: 'Chart Stream GL',
- group: 'Chart',
+ group: 'Charts',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/Chat/ChatEmojiPicker.doc.mjs b/packages/lab/src/Chat/ChatEmojiPicker.doc.mjs
index dd560c2541..8df1a3ae3d 100644
--- a/packages/lab/src/Chat/ChatEmojiPicker.doc.mjs
+++ b/packages/lab/src/Chat/ChatEmojiPicker.doc.mjs
@@ -5,6 +5,8 @@
export const docs = {
name: 'ChatEmojiPicker',
subComponentOf: 'Chat',
+ group: 'Chat',
+ category: 'Chat',
displayName: 'Chat Emoji Picker',
description: 'Popover emoji grid wrapping a trigger button: a shortname filter input over an 8-column grid with arrow-key roving focus. Picking an emoji calls onSelect and closes the popover, restoring focus to the trigger. Ships with a small default emoji set; override via emojis.',
props: [
diff --git a/packages/lab/src/Chat/ChatReactionBar.doc.mjs b/packages/lab/src/Chat/ChatReactionBar.doc.mjs
index 34c95abbe9..4ed378ebb8 100644
--- a/packages/lab/src/Chat/ChatReactionBar.doc.mjs
+++ b/packages/lab/src/Chat/ChatReactionBar.doc.mjs
@@ -5,6 +5,8 @@
export const docs = {
name: 'ChatReactionBar',
subComponentOf: 'Chat',
+ group: 'Chat',
+ category: 'Chat',
displayName: 'Chat Reaction Bar',
description: 'Row of emoji reaction pills under a chat message. Each pill shows an emoji and count; the current user\'s own reactions get an accent tint and aria-pressed. Provide onAdd to render a trailing add-reaction button that opens a ChatEmojiPicker popover.',
props: [
diff --git a/packages/lab/src/Chat/ChatTypingIndicator.doc.mjs b/packages/lab/src/Chat/ChatTypingIndicator.doc.mjs
index bb7db081d3..433edae8cb 100644
--- a/packages/lab/src/Chat/ChatTypingIndicator.doc.mjs
+++ b/packages/lab/src/Chat/ChatTypingIndicator.doc.mjs
@@ -5,6 +5,8 @@
export const docs = {
name: 'ChatTypingIndicator',
subComponentOf: 'Chat',
+ group: 'Chat',
+ category: 'Chat',
displayName: 'Chat Typing Indicator',
description: 'Animated three-dot typing hint with a grammar-aware label: "Ana is typing...", "Ana and Ben are typing...", or "Ana and 2 others are typing...". Dots bounce with staggered stylex.keyframes delays, disabled under prefers-reduced-motion; the label is announced politely via role="status".',
props: [
diff --git a/packages/lab/src/Chat/ChatUnreadDivider.doc.mjs b/packages/lab/src/Chat/ChatUnreadDivider.doc.mjs
index eee9aa5ec1..f53e541726 100644
--- a/packages/lab/src/Chat/ChatUnreadDivider.doc.mjs
+++ b/packages/lab/src/Chat/ChatUnreadDivider.doc.mjs
@@ -5,6 +5,8 @@
export const docs = {
name: 'ChatUnreadDivider',
subComponentOf: 'Chat',
+ group: 'Chat',
+ category: 'Chat',
displayName: 'Chat Unread Divider',
description: 'Error-colored rule with a trailing label marking where unread messages begin in a chat thread. Rendered as an aria separator with an accessible label. Distinct from ChatSystemMessage\'s divider variant, which is for neutral date breaks.',
props: [
diff --git a/packages/lab/src/ThreeD/3DBar.doc.mjs b/packages/lab/src/ThreeD/ThreeDBar.doc.mjs
similarity index 87%
rename from packages/lab/src/ThreeD/3DBar.doc.mjs
rename to packages/lab/src/ThreeD/ThreeDBar.doc.mjs
index 7cc0884203..86a7c75309 100644
--- a/packages/lab/src/ThreeD/3DBar.doc.mjs
+++ b/packages/lab/src/ThreeD/ThreeDBar.doc.mjs
@@ -3,9 +3,9 @@
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
- name: '3DBar',
+ name: 'ThreeDBar',
displayName: '3D Bar',
- group: 'ThreeD',
+ group: '3D',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/ThreeD/3DChart.doc.mjs b/packages/lab/src/ThreeD/ThreeDChart.doc.mjs
similarity index 87%
rename from packages/lab/src/ThreeD/3DChart.doc.mjs
rename to packages/lab/src/ThreeD/ThreeDChart.doc.mjs
index 953ef790ad..8c41082c8d 100644
--- a/packages/lab/src/ThreeD/3DChart.doc.mjs
+++ b/packages/lab/src/ThreeD/ThreeDChart.doc.mjs
@@ -3,9 +3,9 @@
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
- name: '3DChart',
+ name: 'ThreeDChart',
displayName: '3D Chart',
- group: 'ThreeD',
+ group: '3D',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/ThreeD/3DScatter.doc.mjs b/packages/lab/src/ThreeD/ThreeDScatter.doc.mjs
similarity index 86%
rename from packages/lab/src/ThreeD/3DScatter.doc.mjs
rename to packages/lab/src/ThreeD/ThreeDScatter.doc.mjs
index 5e549f0806..8460b99d0b 100644
--- a/packages/lab/src/ThreeD/3DScatter.doc.mjs
+++ b/packages/lab/src/ThreeD/ThreeDScatter.doc.mjs
@@ -3,9 +3,9 @@
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
- name: '3DScatter',
+ name: 'ThreeDScatter',
displayName: '3D Scatter',
- group: 'ThreeD',
+ group: '3D',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/ThreeD/3DScatterGL.doc.mjs b/packages/lab/src/ThreeD/ThreeDScatterGL.doc.mjs
similarity index 86%
rename from packages/lab/src/ThreeD/3DScatterGL.doc.mjs
rename to packages/lab/src/ThreeD/ThreeDScatterGL.doc.mjs
index a07a11a7d4..4de3097cb3 100644
--- a/packages/lab/src/ThreeD/3DScatterGL.doc.mjs
+++ b/packages/lab/src/ThreeD/ThreeDScatterGL.doc.mjs
@@ -3,9 +3,9 @@
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
- name: '3DScatterGL',
+ name: 'ThreeDScatterGL',
displayName: '3D Scatter GL',
- group: 'ThreeD',
+ group: '3D',
category: 'Data Visualization',
usage: {
diff --git a/packages/lab/src/ThreeD/3DSurface.doc.mjs b/packages/lab/src/ThreeD/ThreeDSurface.doc.mjs
similarity index 86%
rename from packages/lab/src/ThreeD/3DSurface.doc.mjs
rename to packages/lab/src/ThreeD/ThreeDSurface.doc.mjs
index 37e45a8f75..4ee0e1d44f 100644
--- a/packages/lab/src/ThreeD/3DSurface.doc.mjs
+++ b/packages/lab/src/ThreeD/ThreeDSurface.doc.mjs
@@ -3,9 +3,9 @@
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
- name: '3DSurface',
+ name: 'ThreeDSurface',
displayName: '3D Surface',
- group: 'ThreeD',
+ group: '3D',
category: 'Data Visualization',
usage: {
diff --git a/packages/richtext/astryx.integration.mjs b/packages/richtext/astryx.integration.mjs
new file mode 100644
index 0000000000..07076851f8
--- /dev/null
+++ b/packages/richtext/astryx.integration.mjs
@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx CLI integration for the canary-only Rich Text package.
+ * Package identity and version come from package.json.
+ */
+export default {
+ components: './src',
+ templates: './blocks',
+ issuesUrl: 'https://github.com/facebook/astryx/issues',
+};
diff --git a/packages/richtext/blocks/RichTextEditorShowcase.template.mjs b/packages/richtext/blocks/RichTextEditorShowcase.template.mjs
new file mode 100644
index 0000000000..d5102dff2d
--- /dev/null
+++ b/packages/richtext/blocks/RichTextEditorShowcase.template.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'block',
+ name: 'RichTextEditor',
+ displayName: 'Rich Text Editor',
+ description: 'A rich text field with its formatting toolbar.',
+ exampleFor: 'RichTextEditor',
+ aspectRatio: 16 / 10,
+ isShowcase: true,
+ componentsUsed: ['RichTextEditor', 'RichTextEditorToolbar'],
+};
diff --git a/packages/richtext/blocks/RichTextEditorShowcase.tsx b/packages/richtext/blocks/RichTextEditorShowcase.tsx
new file mode 100644
index 0000000000..0958e41421
--- /dev/null
+++ b/packages/richtext/blocks/RichTextEditorShowcase.tsx
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {RichTextEditor, RichTextEditorToolbar} from '@astryxdesign/richtext';
+
+export default function RichTextEditorShowcase() {
+ return (
+ <div style={{width: 480, maxWidth: '100%'}}>
+ <RichTextEditor
+ label="Release notes"
+ description="Capture formatted context for your team."
+ placeholder="Write an update…"
+ toolbar={<RichTextEditorToolbar />}
+ minHeight={112}
+ />
+ </div>
+ );
+}
diff --git a/packages/richtext/package.json b/packages/richtext/package.json
index cb55f7b109..9a9acf7b92 100644
--- a/packages/richtext/package.json
+++ b/packages/richtext/package.json
@@ -1,5 +1,6 @@
{
"name": "@astryxdesign/richtext",
+ "displayName": "Rich Text",
"version": "0.1.9",
"private": true,
"description": "Astryx rich text — a Lexical-based rich text editor and viewer. Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
@@ -31,6 +32,8 @@
"types": "./dist/index.d.ts",
"sideEffects": false,
"files": [
+ "astryx.integration.mjs",
+ "blocks",
"dist",
"src",
"README.md",
diff --git a/packages/richtext/tsconfig.docs.json b/packages/richtext/tsconfig.docs.json
index f19aeb0097..13f1e12f3f 100644
--- a/packages/richtext/tsconfig.docs.json
+++ b/packages/richtext/tsconfig.docs.json
@@ -6,5 +6,5 @@
"checkJs": true,
"noEmit": true
},
- "include": ["src/**/*.doc.mjs"]
+ "include": ["src/**/*.doc.mjs", "blocks/**/*"]
}
diff --git a/packages/vega/astryx.integration.mjs b/packages/vega/astryx.integration.mjs
new file mode 100644
index 0000000000..991807b759
--- /dev/null
+++ b/packages/vega/astryx.integration.mjs
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx CLI integration for the canary-only Vega package.
+ * Package identity and version come from package.json.
+ */
+export default {
+ components: './src',
+ issuesUrl: 'https://github.com/facebook/astryx/issues',
+};
diff --git a/packages/vega/package.json b/packages/vega/package.json
index c5e3505514..9a4fd83836 100644
--- a/packages/vega/package.json
+++ b/packages/vega/package.json
@@ -37,6 +37,7 @@
}
},
"files": [
+ "astryx.integration.mjs",
"dist",
"src",
"README.md"
@@ -46,6 +47,7 @@
"dev": "tsup --watch",
"test": "vitest run --root ../..",
"test:watch": "vitest --root ../..",
+ "typecheck:docs": "tsc --project tsconfig.docs.json",
"typecheck": "tsc --noEmit"
},
"peerDependencies": {
@@ -55,6 +57,7 @@
"vega-lite": ">=6.0.0"
},
"devDependencies": {
+ "@astryxdesign/cli": "workspace:*",
"@types/react": "^19.2.17",
"tsup": "^8.3.0",
"typescript": "^6.0.3",
diff --git a/packages/vega/src/VegaChart.doc.mjs b/packages/vega/src/VegaChart.doc.mjs
new file mode 100644
index 0000000000..b07e234a0b
--- /dev/null
+++ b/packages/vega/src/VegaChart.doc.mjs
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docs = {
+ name: 'VegaChart',
+ displayName: 'Vega Chart',
+ category: 'Data Visualization',
+ keywords: ['vega', 'vega-lite', 'chart', 'data visualization'],
+ props: [
+ {
+ name: 'spec',
+ type: 'AnySpec',
+ description:
+ 'A Vega or Vega-Lite specification with an official $schema URL.',
+ required: true,
+ },
+ {
+ name: 'data',
+ type: 'ViewData',
+ description:
+ 'Initial values for datasets named by the spec. Read when the view is created; later updates should use the live View.',
+ },
+ {
+ name: 'compileOptions',
+ type: 'CompileOptions',
+ description:
+ 'Options passed to Vega-Lite compilation. Ignored for native Vega specs.',
+ },
+ {
+ name: 'parseConfig',
+ type: 'Config',
+ description: 'Vega configuration passed to vega.parse().',
+ },
+ {
+ name: 'parseOptions',
+ type: 'ParseOptions',
+ description: 'Options passed to vega.parse().',
+ },
+ {
+ name: 'viewOptions',
+ type: "Omit<ViewOptions, 'container'>",
+ description:
+ 'Options passed to the Vega View. The component always supplies the container.',
+ },
+ {
+ name: 'onReady',
+ type: '(view: View) => void',
+ description: 'Called with the live Vega View after the first render.',
+ },
+ {
+ name: 'onError',
+ type: '(error: Error) => void',
+ description:
+ 'Called when schema validation, compilation, or rendering fails.',
+ },
+ ],
+ usage: {
+ description:
+ 'Renders Vega and Vega-Lite specifications through the Vega runtime. Experimental component in @astryxdesign/vega (canary).',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Only render specifications you authored or reviewed. For untrusted specs, configure the interpreter and a restricted loader as described in the package README.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Keep spec and option objects stable to avoid recreating the Vega View unnecessarily.',
+ },
+ ],
+ },
+};
diff --git a/packages/vega/src/VegaChart.tsx b/packages/vega/src/VegaChart.tsx
index cbcdcf276b..a5725695fd 100644
--- a/packages/vega/src/VegaChart.tsx
+++ b/packages/vega/src/VegaChart.tsx
@@ -6,7 +6,9 @@
* @output A React component that renders the spec via the Vega runtime
* @position Primary component in @astryxdesign/vega; owns the Vega View lifecycle
*
- * SYNC: When modified, update /packages/vega/README.md
+ * SYNC: When modified, update:
+ * - /packages/vega/src/VegaChart.doc.mjs
+ * - /packages/vega/README.md
*/
import React, {useEffect, useEffectEvent, useRef, useState} from 'react';
diff --git a/packages/vega/tsconfig.docs.json b/packages/vega/tsconfig.docs.json
new file mode 100644
index 0000000000..f19aeb0097
--- /dev/null
+++ b/packages/vega/tsconfig.docs.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "../..",
+ "allowJs": true,
+ "checkJs": true,
+ "noEmit": true
+ },
+ "include": ["src/**/*.doc.mjs"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index deb345b2ae..90c7f7130e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -145,6 +145,12 @@ importers:
'@astryxdesign/core':
specifier: '*'
version: link:../../packages/core
+ '@astryxdesign/lab':
+ specifier: '*'
+ version: link:../../packages/lab
+ '@astryxdesign/richtext':
+ specifier: '*'
+ version: link:../../packages/richtext
'@astryxdesign/theme-butter':
specifier: '*'
version: link:../../packages/themes/butter
@@ -163,6 +169,9 @@ importers:
'@astryxdesign/theme-y2k':
specifier: '*'
version: link:../../packages/themes/y2k
+ '@astryxdesign/vega':
+ specifier: '*'
+ version: link:../../packages/vega
'@heroicons/react':
specifier: ^2.2.0
version: 2.2.0([email protected])
@@ -927,6 +936,9 @@ importers:
specifier: '>=19.2.0'
version: 19.2.7([email protected])
devDependencies:
+ '@astryxdesign/cli':
+ specifier: workspace:*
+ version: link:../cli
'@types/react':
specifier: ^19.2.17
version: 19.2.17