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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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 packageif: 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 dataif: 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 docsif: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true'run: pnpm -F @astryxdesign/cli typecheck:template-docsdiff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.ymlindex c7034b0c98..4fd5f8cf06 100644--- a/.github/workflows/deploy.yml+++ b/.github/workflows/deploy.yml@@ -135,6 +135,12 @@ jobs:- name: Typecheck charts docsrun: 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 docsrun: pnpm -F @astryxdesign/cli typecheck:template-docsdiff --git a/apps/docsite/.gitignore b/apps/docsite/.gitignoreindex 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.mjssrc/generated/+.content-cache/# Auto-generated by scripts/generate-playground-types.mjspublic/playground-types.jsondiff --git a/apps/docsite/README.md b/apps/docsite/README.mdindex 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 registriesand 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 isdev are `canary`. `scripts/resolve-content-root.mjs` maps the target to thefilesystem root the pipeline reads from — for `latest` it downloads thepublished 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 andalways 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 Postdiff --git a/apps/docsite/astryx.config.mjs b/apps/docsite/astryx.config.mjsnew file mode 100644index 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.jsonindex 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.mjsindex 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 docsiteif (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 editimport 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 showcasesif (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 foundimport 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 editimport 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 editimport 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.tsindex 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.tsindex 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.tsindex 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 | nullexpect(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.tsindex 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.tsxindex 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 (<SectionmaxWidth={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.tsxindex 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.cssindex 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.mjsfrom every @astryxdesign/theme-* package in this app's dependencies. Newthemes 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.tsindex 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.tsxindex 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 packagesconst 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 (<AppShellvariant="surface"@@ -160,7 +211,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {</SideNavItem></SideNavSection>- {/* Libraries */}+ {/* Stable libraries */}<SideNavSection title="Libraries" isHeaderHidden><SideNavItemlabel="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 Componentssection. 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.tsxindex 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.tsxindex 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.tsxindex 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) && (<VStackgap={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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.jsonindex 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.jsonindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 = zconst 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.jsonindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjssimilarity index 87%rename from packages/lab/src/ThreeD/3DBar.doc.mjsrename to packages/lab/src/ThreeD/ThreeDBar.doc.mjsindex 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.mjssimilarity index 87%rename from packages/lab/src/ThreeD/3DChart.doc.mjsrename to packages/lab/src/ThreeD/ThreeDChart.doc.mjsindex 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.mjssimilarity index 86%rename from packages/lab/src/ThreeD/3DScatter.doc.mjsrename to packages/lab/src/ThreeD/ThreeDScatter.doc.mjsindex 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.mjssimilarity index 86%rename from packages/lab/src/ThreeD/3DScatterGL.doc.mjsrename to packages/lab/src/ThreeD/ThreeDScatterGL.doc.mjsindex 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.mjssimilarity index 86%rename from packages/lab/src/ThreeD/3DSurface.doc.mjsrename to packages/lab/src/ThreeD/ThreeDSurface.doc.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.jsonindex 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.mjsnew file mode 100644index 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.tsxindex 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.jsonnew file mode 100644index 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.yamlindex 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.0version: 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.17version: 19.2.17