Skip to content

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

TypeScript

feat(cli): build tells parts from pages by the system's components; templates declare keywords (#6805)

Joey3f1bee4d2331
diff --git a/.changeset/build-template-keywords.md b/.changeset/build-template-keywords.md
new file mode 100644
index 0000000000..e194ea4b5a
--- /dev/null
+++ b/.changeset/build-template-keywords.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Templates declare their `keywords`, and `build` tells a part of a page from a page by the components the project can use (#6805)
+
+- `TemplateDoc` gains an optional `keywords` list: the ideas, domains, and other names a builder might use for what the template serves. `parseTemplate` validates it, discovery carries it from every template source, `astryx search` matches it as it matches a template's description, and `astryx build` ranks page templates on it. Each Core page template's closing list of ideas moved out of its `description` into `keywords`, so descriptions describe the layout.
+- `build` starts a part of a page where it lives (`spec:AST-048` FR3), and the project's own components say what a part is: an idea whose head noun is a word of a component's name or keywords, Core's or an integration's, asks for a part, unless the noun names a family of page templates or the idea lists three or more pieces. A part starts from the base template of the family the idea names, else from the app shell; a change to an existing page or part (an idea whose "existing" names a page family or a component, such as "the existing table", and that does not ask for a new page) starts from the app shell. The start's reason says which case applies and why.
+- A family's base template leads its family unless a variant matches two terms of its own; a base that cannot start on its own never displaces the variant that leads.
+
+Integration templates that set `keywords` need `@astryxdesign/cli` 0.7.0 or later. The template metadata object is strict, so a stable CLI before 0.7.0 rejects the field, drops that template, and hides the package's doc topics; only `template --list` and `search` print a warning. `integration verify` fails a package whose template sets `keywords` until it declares `@astryxdesign/cli >=0.7.0`, as it does for `replaces`.
+@josephfarina
diff --git a/packages/cli/api/build/_adapter.mjs b/packages/cli/api/build/_adapter.mjs
index 1f423cb35b..07acb415e3 100644
--- a/packages/cli/api/build/_adapter.mjs
+++ b/packages/cli/api/build/_adapter.mjs
@@ -2,20 +2,23 @@
/**
* @file The build subject's environment access: the page templates a project
- * can scaffold.
+ * can scaffold, and the components it can use.
*
- * @input Template discovery for `cwd` — the CLI's own templates plus any that
- * the project's configured integrations contribute.
+ * @input Template and component discovery for `cwd` — the CLI's own templates
+ * and Core's components, plus any that the project's configured integrations
+ * contribute.
* @output Ready page templates as `{name, displayName, description, category,
- * command}`, where `command` is the `astryx template` command that selects
- * exactly that template.
- * @position Beside build.mjs (api/build/). The kit leaf reads templates only
- * through here, because a subject's `_adapter.mjs` is its only environment
- * access. Search keeps its own discovery; this adds none of its own, it
- * reuses the template subject's.
+ * keywords, command}`, where `command` is the `astryx template` command that
+ * selects exactly that template; components as `{name, keywords}`.
+ * @position Beside build.mjs (api/build/). The kit leaf reads templates and
+ * components only through here, because a subject's `_adapter.mjs` is its
+ * only environment access. This adds no discovery of its own: templates come
+ * from the template subject's, components from search's.
*/
import {discoverTemplates} from '../template/template.mjs';
+import {componentKeywords} from '../search/search.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
/**
* A page template the kit can recommend starting from.
@@ -23,8 +26,16 @@ import {discoverTemplates} from '../template/template.mjs';
* @property {string} name The template's own id, as search reports it.
* @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
* @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
* @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
*/
/**
@@ -53,8 +64,28 @@ export async function loadPageTemplates(cwd) {
displayName: t.displayName || t.name,
description: t.description || '',
category: t.category || '',
+ keywords: t.keywords ?? [],
// The id `template()` resolves back to this entry: an active replacement
// owns the Core id it names, so that id selects it, not its own.
command: `astryx template ${t.replaces ?? t.dirName} --type page`,
}));
}
+
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export async function loadComponents(cwd) {
+ const coreDir = findCoreDir(cwd);
+ if (!coreDir) return [];
+ try {
+ return await componentKeywords(coreDir, cwd);
+ } catch {
+ return [];
+ }
+}
diff --git a/packages/cli/api/build/build.doc.mjs b/packages/cli/api/build/build.doc.mjs
index e005a08b9c..aaa892f906 100644
--- a/packages/cli/api/build/build.doc.mjs
+++ b/packages/cli/api/build/build.doc.mjs
@@ -19,8 +19,8 @@ export const doc = {
'The "build a page" entry point. Called with no query it returns the ' +
'how-to-build-a-page playbook as data: the workflow steps with their ' +
'commands, the on-system rules, and related lookups. Called with a query it names the page template to ' +
- 'START from (always one: the page template a ranker built for long descriptions puts first, else the app ' +
- 'shell) and the next two templates, ' +
+ 'START from (always one: the page template a ranker built for long descriptions puts first; for a part ' +
+ 'of a page, the page it names; else the app shell) and the next two templates, ' +
'and the unified search grouped around it: the other close page templates, drop-in blocks, and ' +
'idea-specific components/hooks, plus the always-on frame + foundation. A template carries the page ' +
'frame and spacing, so the kit never recommends composing a page from components.',
diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjs
index a9ef6bcab7..91bbb0617a 100644
--- a/packages/cli/api/build/build.test.mjs
+++ b/packages/cli/api/build/build.test.mjs
@@ -8,7 +8,7 @@ import {describe, it, expect, vi} from 'vitest';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {build} from './build.mjs';
-import {search} from '../search/search.mjs';
+import {search, searchedComponents} from '../search/search.mjs';
// api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
const REPO = path.resolve(
@@ -152,6 +152,16 @@ describe('build API', () => {
});
});
+describe('build kit — reuses the components its search gathered', () => {
+ it('keeps them beside the search response, out of its JSON', async () => {
+ const all = await search('date picker', {cwd: REPO});
+ expect(searchedComponents(all)?.map(c => c.name)).toContain('DateRangeInput');
+ expect(JSON.stringify(all)).not.toContain('"keywords"');
+ const pagesOnly = await search('date picker', {cwd: REPO, type: 'template'});
+ expect(searchedComponents(pagesOnly)).toBeNull();
+ }, 60_000);
+});
+
describe('build kit — coverage gates the pages group', () => {
it('does not call a one-word coincidence a direct match', async () => {
// A page's keywords include every component its source renders, so any
@@ -259,7 +269,7 @@ describe('build kit — a thin kit says what to try next', () => {
// A skeleton is a 35-line excerpt: a reader who studies it and composes
// the rest loses the spacing the template exists to carry. A loose match
// is still the best start there is, so `start` scaffolds it.
- const r = await build('executive summary', {cwd: REPO});
+ const r = await build('quarterly business review', {cwd: REPO});
expect(r.type).toBe('build.kit');
if (r.type !== 'build.kit') return;
expect(r.data.directMatch).toBe(false);
@@ -357,9 +367,35 @@ describe('build kit — every page starts from a template', () => {
const placed = await build('an empty state for a settings page', {cwd: REPO});
if (placed.type !== 'build.kit') throw new Error(placed.type);
expect(placed.data.start).toMatchObject({name: 'settings', basis: 'closest'});
+ expect(placed.data.start?.reason).toMatch(/part of a page, so it starts from the page it names/);
const loose = await build('a date range picker', {cwd: REPO});
if (loose.type !== 'build.kit') throw new Error(loose.type);
expect(loose.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+ expect(loose.data.start?.reason).toMatch(/part of a page and names no page, so it starts from the app shell/);
+ });
+
+ it('starts a change to an existing page from the app shell', async () => {
+ // The page is the builder's to keep; no template scaffolds it.
+ const r = await build('add a sort toggle to the existing reports dashboard', {cwd: REPO});
+ if (r.type !== 'build.kit') throw new Error(r.type);
+ expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+ expect(r.data.start?.reason).toMatch(/changes a page you already have, so keep it/);
+ expect(r.data.start?.reason).not.toMatch(/too little of the idea fits/);
+ // A direct match the response reports is still named.
+ if (r.data.directMatch) expect(r.data.start?.reason).toContain(`\`${r.data.pages[0].name}\``);
+ });
+
+ it('does not call a new page that mentions something existing a change', async () => {
+ for (const idea of [
+ 'a new dashboard inspired by the existing one',
+ 'a new dashboard based on the existing dashboard',
+ 'clone the existing dashboard as a new page',
+ ]) {
+ const r = await build(idea, {cwd: REPO});
+ if (r.type !== 'build.kit') throw new Error(r.type);
+ expect(r.data.start?.name).toBe('dashboard');
+ expect(r.data.start?.reason).not.toMatch(/already have/);
+ }
});
it('names a direct match the ranker outweighed in the reason', async () => {
diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjs
index 4da3dee004..59174015ba 100644
--- a/packages/cli/api/build/kit/kit.mjs
+++ b/packages/cli/api/build/kit/kit.mjs
@@ -27,13 +27,13 @@
* the invocation stays the renderer's job.
*/
-import {search} from '../../search/search.mjs';
+import {search, searchedComponents} from '../../search/search.mjs';
import {findCoreDir} from '../../../foundation/fs/paths.mjs';
import {AstryxError} from '../../error.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {getResultCoverage} from '../../search/coverage.mjs';
-import {loadPageTemplates} from '../_adapter.mjs';
-import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickAlternatives, pickStart, rankPages} from './rank.mjs';
/** A page at/above this score is a confident direct match. */
const PAGE_DIRECT = 95;
@@ -118,6 +118,24 @@ const asTemplate = t => ({
command: `${t.command} <path>`,
});
+/**
+ * Why a part of a page, or a change to a page the builder already has, starts
+ * where it does (spec:AST-048/FR3, FR9): the rest of the start's reason, or
+ * null for a whole page.
+ * @param {import('./rank.mjs').IdeaKind} kind
+ * @param {boolean} inPage whether the start is the page the idea names
+ * @returns {string | null}
+ */
+function placement(kind, inPage) {
+ if (kind === 'edit')
+ return 'the idea changes a page you already have, so keep it and add blocks to it; a new page starts from the app shell.';
+ if (kind === 'part')
+ return inPage
+ ? 'the idea is a part of a page, so it starts from the page it names.'
+ : 'the idea is a part of a page and names no page, so it starts from the app shell.';
+ return null;
+}
+
/**
* The template to start from: the ready page the ranker puts first when it
* has the evidence to lead, else the first fallback shell the project can
@@ -129,12 +147,13 @@ const asTemplate = t => ({
* the reason names it, so the reader knows why the kit starts elsewhere.
*
* @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').IdeaKind} kind
* @param {SearchResultEntry[]} pages
* @param {boolean} directMatch
* @param {PageTemplate[]} catalog
* @returns {Omit<BuildStart, 'alternatives'> | null}
*/
-function chooseStart(ranked, pages, directMatch, catalog) {
+function chooseStart(ranked, kind, pages, directMatch, catalog) {
const direct = directMatch ? pages[0].name : null;
const unready =
direct && !catalog.some(t => t.name === direct) ? direct : null;
@@ -142,20 +161,32 @@ function chooseStart(ranked, pages, directMatch, catalog) {
// match the ranker outweighed is named, and so are the loose page matches
// search listed when the kit falls back to the shell.
const loose = pages.map(p => `\`${p.name}\``).join(', ');
- const pick = pickStart(ranked);
+ /**
+ * A part's or an edit's reason, naming a direct match that is not the start.
+ * @param {string} place
+ * @param {string} startName
+ */
+ const placed = (place, startName) =>
+ direct && direct !== startName
+ ? `Search matched \`${direct}\` by name, but ${place}`
+ : place[0].toUpperCase() + place.slice(1);
+ const pick = pickStart(ranked, kind);
const closest = pick && catalog.find(t => t.name === pick.name);
- if (closest) {
+ if (pick && closest) {
const agrees = closest.name === direct;
+ const place = placement(kind, pick.base && pick.familyNamed);
return {
...asTemplate(closest),
basis: agrees ? 'direct' : 'closest',
- reason: agrees
- ? 'Matches the idea.'
- : unready
- ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
- : direct
- ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
- : 'The closest template; none is exactly this page.',
+ reason: unready
+ ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
+ : place
+ ? placed(place, closest.name)
+ : agrees
+ ? 'Matches the idea.'
+ : direct
+ ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
+ : 'The closest template; none is exactly this page.',
};
}
for (const id of FALLBACK_STARTS) {
@@ -164,18 +195,21 @@ function chooseStart(ranked, pages, directMatch, catalog) {
// The shell can also be the ranker's best guess without the evidence to
// lead ("horizontal site navigation"); say so rather than "no match".
const nearest = ranked[0]?.name === shell.name && ranked[0].hits > 0;
+ const place = placement(kind, false);
return {
...asTemplate(shell),
basis: 'fallback',
reason: unready
? `\`${unready}\` matches but is not ready yet, so start from the app shell.`
- : direct
- ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
- : nearest
- ? 'No template is a clear match; the app shell is the closest.'
- : loose
- ? `Search matched ${loose} only loosely, so start from the app shell.`
- : 'No template matched, so start from the app shell.',
+ : place
+ ? placed(place, shell.name)
+ : direct
+ ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
+ : nearest
+ ? 'No template is a clear match; the app shell is the closest.'
+ : loose
+ ? `Search matched ${loose} only loosely, so start from the app shell.`
+ : 'No template matched, so start from the app shell.',
};
}
}
@@ -301,8 +335,18 @@ export async function buildKit(query, options = {}) {
const wantsPages = !type || type === 'template';
const catalog = wantsPages ? await loadPageTemplates(cwd) : [];
const ranked = wantsPages ? rankPages(query, catalog) : [];
+ // A part of a page starts where it lives (spec:AST-048/FR3); the project's
+ // own components say what a part is. The search above already gathered them
+ // unless it was narrowed to templates.
+ const kind = wantsPages
+ ? ideaKind(
+ query,
+ catalog,
+ searchedComponents(result) ?? (await loadComponents(cwd)),
+ )
+ : 'page';
const chosen = wantsPages
- ? chooseStart(ranked, matchedPages, directMatch, catalog)
+ ? chooseStart(ranked, kind, matchedPages, directMatch, catalog)
: null;
// Name the ranker's next two templates beside the start: the reader judges
// meaning better than keywords do, and an acceptable template is in these
diff --git a/packages/cli/api/build/kit/rank.mjs b/packages/cli/api/build/kit/rank.mjs
index 0928b13caa..079699f26a 100644
--- a/packages/cli/api/build/kit/rank.mjs
+++ b/packages/cli/api/build/kit/rank.mjs
@@ -2,13 +2,15 @@
/**
* @file The page ranker behind `build`'s START: which page template an idea
- * should start from.
+ * should start from, and whether the idea asks for a page at all.
*
- * @input A free-text idea and the project's ready page templates (id, display
- * name, description, `Family - Variant` category), all read from each
- * template's own descriptor.
+ * @input A free-text idea, the project's ready page templates (id, display
+ * name, description, keywords, `Family - Variant` category) and its
+ * components (name, keywords), all read from each item's own descriptor.
* @output Every template, ranked, with the query terms it matched and whether
- * the idea names its family; `pickStart` turns that into a template or null.
+ * the idea names its family; `ideaKind`, whether the idea asks for a page, a
+ * part of one, or a change to a page the builder has; `pickStart` turns both
+ * into a template or null.
* @position Beside kit.mjs (api/build/kit/). Search ranks components, docs,
* blocks and pages against short lookups; this ranks only page templates,
* against the long descriptions builders actually write ("ops dashboard with
@@ -36,8 +38,27 @@
* next one counts half, unless the template names the same pair
* ("executive summary").
* - The family base. A template whose id is its family's name (`dashboard`,
- * `settings`) is that family's default; it wins when no variant's own words
- * outweigh it.
+ * `settings`) is that family's default. A variant displaces it only with two
+ * matched terms of its own ("a small comparison note" does not make a
+ * dashboard the comparison dashboard), and a base too weak to start on its
+ * own displaces no variant ("a funnel for a dashboard" is the funnel).
+ *
+ * Parts (spec:AST-048/FR3). "A date range picker" asks for a part of a page,
+ * not a page, and the system's own components say what a part is: an idea
+ * whose head noun is a word of a component's name or keywords, Core's or an
+ * integration's, asks for that part, unless the noun is a family word ("a data
+ * table") or the idea lists a page's worth of pieces. Words search drops as
+ * stopwords ("page", "screen", "app", "view") name no component, so "a calendar
+ * page" asks for a page and "a calendar" for a part. A part starts from the
+ * base template of the family the idea names ("an empty state for a settings
+ * page"), else from the app shell. An idea that changes a page or part the
+ * builder already has starts from the app shell too: that page is the
+ * builder's to keep (FR9), and no template scaffolds it. "Existing" marks one
+ * when its phrase names a page family or a component ("add a column to the
+ * existing table"), unless the idea asks for a new page ("a new dashboard like
+ * the existing dashboard", "clone the existing dashboard as a new page"). A
+ * bare "existing" phrase that names a page ("existing reports dashboard with a
+ * date filter") reads as the builder's own page.
*
* Family words come from the templates' own ids — a word in the ids of two or
* more templates of one family, plus the family's name when a template carries
@@ -50,79 +71,68 @@ import {stem, STOPWORDS, SYNONYMS} from '../../search/search.mjs';
/**
* How much a term counts by where the template names it. The id and category
- * are the author's own label for what the page is; the description's last
- * sentence lists the ideas it serves; its body describes the layout.
+ * are the author's own label for what the page is; its keywords name the ideas
+ * it serves; its description describes the layout.
*/
const FIELD_WEIGHT = {
id: 3,
variant: 3,
family: 2,
display: 2,
- intent: 2,
- body: 1,
+ keywords: 2,
+ description: 1,
};
-/** A synonym hit counts at this share of a direct hit. */
+/**
+ * A synonym hit counts half a direct hit: a synonym says the idea is near the
+ * page, not that it names it.
+ */
const SYNONYM_SHARE = 0.5;
-/** A container word ("in a modal") counts this many times over. */
+/**
+ * A container word ("in a modal") counts double: it names the page's frame,
+ * which is what a template is.
+ */
const CONTAINER = 2;
-/** A word that only modifies another ("product" in "product response"). */
+/**
+ * A word that only modifies another ("product" in "product response") counts
+ * half: it describes its head, not the page.
+ */
const MODIFIER = 0.5;
-/** Added when the idea's head names the template's family. */
+/**
+ * Added when the idea's head names the template's family: more than any one
+ * word scores (an id word only one template carries is worth about ten), so the
+ * head's family outranks a rarer word among the parts.
+ */
const HEAD_FAMILY = 12;
-/** Added when the family is named anywhere else in the idea. */
+/**
+ * Added when the family is named anywhere else in the idea: about a description
+ * word, enough to settle a near tie.
+ */
const BODY_FAMILY = 2;
-/** Added to a family's base template when the idea names that family. */
+/**
+ * Added to a family's base template when the idea names that family: settles a
+ * near tie toward the family's default page.
+ */
const FAMILY_BASE = 2;
/**
* The least a start must score, and the evidence it needs: two matched terms,
* or the idea naming its family. One rare word alone is how a tic-tac-toe game
- * board became a kanban board.
+ * board became a kanban board, and it is also too little for a variant to
+ * displace its family's base template.
*/
const START_SCORE = 10;
const START_TERMS = 2;
+/**
+ * How many listed pieces make an idea a page: a part is one thing with a detail
+ * or two ("a status pill with a tooltip"), while three pieces, two commas
+ * apart, describe a page.
+ */
+const PAGE_PIECES = 3;
/**
* Words search drops that name layout: "side navigation", "side by side".
*/
const LAYOUT_WORDS = new Set(['side']);
-/** Filler that search keeps but that says nothing about a page's layout. */
-const FILLER = new Set([
- 'per',
- 'each',
- 'every',
- 'using',
- 'via',
- 'into',
- 'onto',
- 'about',
- 'above',
- 'below',
- 'across',
- 'within',
- 'without',
- 'between',
- 'plus',
- 'also',
- 'then',
- 'them',
- 'they',
- 'which',
- 'while',
- 'when',
- 'all',
- 'any',
- 'new',
- 'use',
- 'used',
- 'show',
- 'shows',
- 'showing',
- 'display',
- 'displays',
- 'displaying',
-]);
-
/**
* Where an idea's head ends: its first clause, before the parts it lists.
*/
@@ -142,6 +152,24 @@ const OVERLAY_FRAMES = new Set([
'overlay',
]);
+/**
+ * The word that marks a page or part the builder already has, when its phrase
+ * names one (see `changesExistingPage`).
+ */
+const EXISTING = /\bexisting\b/i;
+
+/**
+ * The word that marks an idea asking for a new page ("a new dashboard", "as a
+ * new page"), which is never a change to one the builder has.
+ */
+const NEW = /\bnew\b/;
+
+/**
+ * The family whose templates are app chrome rather than page content: the
+ * explicit `Shell -` category (architecture:template-authoring/INV7).
+ */
+const SHELL_FAMILY = 'Shell';
+
/** A container phrase: "in a modal", "inside the side panel". */
const CONTAINER_PHRASE =
/\b(?:in|inside|within)\s+(?:a|an|the)\s+([a-z-]+)(?:\s+([a-z-]+))?/gi;
@@ -155,12 +183,11 @@ const PHRASE_END =
/** @param {string} t */
const isContentWord = t =>
- t.length >= 2 &&
- (LAYOUT_WORDS.has(t) || (!STOPWORDS.has(t) && !FILLER.has(t)));
+ t.length >= 2 && (LAYOUT_WORDS.has(t) || !STOPWORDS.has(t));
/**
- * Content terms of a text: lowercase alphanumeric words, stopwords and filler
- * removed, stemmed.
+ * Content terms of a text: lowercase alphanumeric words, stopwords removed,
+ * stemmed.
* @param {string} text
* @returns {string[]}
*/
@@ -262,8 +289,44 @@ const SYNONYMS_OF = (() => {
/**
* @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
- * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean}} RankedPage
+ * @typedef {import('../_adapter.mjs').ComponentWords} ComponentWords
+ * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean, family: string, base: boolean, matched: Set<string>}} RankedPage
+ * @typedef {'page' | 'part' | 'edit'} IdeaKind
+ */
+
+/** @param {PageTemplate} page */
+const familyOf = page => (page.category.split(' - ')[0] ?? '').trim();
+
+/**
+ * Family words, from the templates' own ids: a word in the ids of two or more
+ * templates of one family, plus the family's name when a template carries it.
+ * Each word maps to its family.
+ * @param {PageTemplate[]} pages
+ * @returns {Map<string, string>}
*/
+function familyWordsOf(pages) {
+ /** @type {Map<string, Map<string, number>>} */
+ const idWords = new Map();
+ for (const page of pages) {
+ const family = familyOf(page);
+ const counts = idWords.get(family) ?? new Map();
+ for (const w of new Set(page.name.split('-'))) {
+ if (w.length >= 3) counts.set(stem(w), (counts.get(stem(w)) ?? 0) + 1);
+ }
+ idWords.set(family, counts);
+ }
+ /** @type {Map<string, string>} */
+ const familyOfWord = new Map();
+ for (const [family, counts] of idWords) {
+ const heads = [...counts].filter(([, c]) => c >= 2).map(([w]) => w);
+ const name = normalized(family).split(' ').pop() ?? '';
+ if (name.length >= 3 && counts.has(stem(name))) heads.push(stem(name));
+ for (const head of heads) {
+ if (!familyOfWord.has(head)) familyOfWord.set(head, family);
+ }
+ }
+ return familyOfWord;
+}
/**
* Rank page templates against an idea, best first. Ties go to the template
@@ -276,20 +339,15 @@ const SYNONYMS_OF = (() => {
export function rankPages(query, pages) {
const docs = pages.map(page => {
const [family = '', ...variantParts] = page.category.split(' - ');
- const sentences = page.description.trim().split(/(?<=[.!?])\s+/);
- const intent = sentences.length > 1 ? sentences[sentences.length - 1] : '';
- const body =
- sentences.length > 1
- ? sentences.slice(0, -1).join(' ')
- : page.description;
/** @type {Record<keyof typeof FIELD_WEIGHT, string>} */
const fields = {
id: page.name.replace(/-/g, ' '),
variant: variantParts.join(' - '),
family,
display: page.displayName,
- intent,
- body,
+ // Each keyword is its own phrase: a pair never spans two of them.
+ keywords: (page.keywords ?? []).join(', '),
+ description: page.description,
};
/** @type {Map<string, number>} */
const bag = new Map();
@@ -320,26 +378,7 @@ export function rankPages(query, pages) {
return d ? Math.log(1 + (n - d + 0.5) / (d + 0.5)) : 0;
};
- // Family words, from the templates' own ids.
- /** @type {Map<string, Map<string, number>>} */
- const idWords = new Map();
- for (const {page, family} of docs) {
- const counts = idWords.get(family) ?? new Map();
- for (const w of new Set(page.name.split('-'))) {
- if (w.length >= 3) counts.set(stem(w), (counts.get(stem(w)) ?? 0) + 1);
- }
- idWords.set(family, counts);
- }
- /** @type {Map<string, string>} */
- const familyOfWord = new Map();
- for (const [family, counts] of idWords) {
- const heads = [...counts].filter(([, c]) => c >= 2).map(([w]) => w);
- const name = normalized(family).split(' ').pop() ?? '';
- if (name.length >= 3 && counts.has(stem(name))) heads.push(stem(name));
- for (const head of heads) {
- if (!familyOfWord.has(head)) familyOfWord.set(head, family);
- }
- }
+ const familyOfWord = familyWordsOf(pages);
/** @param {string[]} ts */
const familiesIn = ts =>
new Set(ts.filter(t => familyOfWord.has(t)).map(t => familyOfWord.get(t)));
@@ -352,11 +391,13 @@ export function rankPages(query, pages) {
const modifiers = modifiersOf(query);
const containers = containersOf(query);
- return docs
+ const ranked = docs
.map(({page, family, bag, pairs}) => {
let score = 0;
let hits = 0;
let containerMatched = false;
+ /** @type {Set<string>} */
+ const matched = new Set();
for (const t of queryTerms) {
// A modifier is discounted where the template names it outright; a
// synonym hit is already discounted by SYNONYM_SHARE.
@@ -378,16 +419,25 @@ export function rankPages(query, pages) {
if (value > 0) {
score += value;
hits++;
+ matched.add(t);
if (containers.has(t)) containerMatched = true;
}
}
const familyNamed = namedFamilies.has(family);
if (headFamilies.has(family)) score += HEAD_FAMILY;
else if (familyNamed) score += BODY_FAMILY;
- if (familyNamed && normalized(page.name) === normalized(family)) {
- score += FAMILY_BASE;
- }
- return {name: page.name, score, hits, familyNamed, containerMatched};
+ const base = normalized(page.name) === normalized(family);
+ if (familyNamed && base) score += FAMILY_BASE;
+ return {
+ name: page.name,
+ score,
+ hits,
+ familyNamed,
+ containerMatched,
+ family,
+ base,
+ matched,
+ };
})
.sort(
(a, b) =>
@@ -395,6 +445,123 @@ export function rankPages(query, pages) {
a.name.split('-').length - b.name.split('-').length ||
a.name.localeCompare(b.name),
);
+ return baseFirst(ranked);
+}
+
+/**
+ * Put a named family's base template ahead of the variant that outranks it,
+ * unless the variant matched START_TERMS terms the base did not, or the base
+ * scores too little to start on its own.
+ * @param {RankedPage[]} ranked
+ * @returns {RankedPage[]}
+ */
+function baseFirst(ranked) {
+ const top = ranked[0];
+ if (!top || top.base || !top.familyNamed) return ranked;
+ const base = ranked.find(r => r.base && r.family === top.family);
+ if (!base || base.score < START_SCORE) return ranked;
+ const own = [...top.matched].filter(t => !base.matched.has(t)).length;
+ return own >= START_TERMS
+ ? ranked
+ : [base, ...ranked.filter(r => r !== base)];
+}
+
+/**
+ * What an idea asks for (spec:AST-048/FR3): a whole `page`; a `part` of one,
+ * when its head noun names one of the system's components and it lists fewer
+ * than PAGE_PIECES pieces; or an `edit` of a page the builder already has.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @param {ComponentWords[]} components
+ * @returns {IdeaKind}
+ */
+export function ideaKind(query, pages, components) {
+ const text = String(query);
+ const familyWords = familyWordsOf(pages);
+ if (changesExistingPage(text, familyWords, components)) return 'edit';
+ // The head's last word, page words included: "calendar" is the noun of "a
+ // calendar", "page" the noun of "a calendar page". An overlay frame names
+ // where the thing lives, not the thing: "drafts" is the noun of "drafts in
+ // a modal".
+ const head = (text.split(HEAD_END)[0] ?? '').replace(CONTAINER_PHRASE, m =>
+ containersOf(m).size > 0 ? ' ' : m,
+ );
+ const words = (head.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter(
+ w => w.length >= 2,
+ );
+ const noun = stem(words[words.length - 1] ?? '');
+ if (familyWords.has(noun)) return 'page';
+ const pieces = (text.match(/,/g) ?? []).length + 1;
+ if (pieces >= PAGE_PIECES) return 'page';
+ return components.some(c => componentTerms(c).includes(noun))
+ ? 'part'
+ : 'page';
+}
+
+/**
+ * Whether an idea changes a page or part the builder already has: "existing"
+ * in the same phrase as a word that names a family of page templates or one of
+ * the system's components ("the existing incidents table", "the existing
+ * banner"). A new page "inspired by the existing one", or "existing users" on a
+ * new page, names neither, and an idea that asks for a new page is no change
+ * whatever it names.
+ * @param {string} text
+ * @param {Map<string, string>} familyWords
+ * @param {ComponentWords[]} components
+ * @returns {boolean}
+ */
+function changesExistingPage(text, familyWords, components) {
+ const componentWords = new Set(components.flatMap(nameTerms));
+ const phrases = text.toLowerCase().split(PHRASE_END);
+ if (asksNewPage(phrases, familyWords)) return false;
+ return phrases.some(phrase => {
+ const at = phrase.search(EXISTING);
+ return (
+ at >= 0 &&
+ terms(phrase.slice(at)).some(
+ t => familyWords.has(t) || componentWords.has(t),
+ )
+ );
+ });
+}
+
+/**
+ * Whether an idea asks for a new page: "new" before a word that names a family
+ * of page templates ("a new dashboard"), or before only words search drops,
+ * such as "page" ("as a new page"). "A new column" asks for a part.
+ * @param {string[]} phrases
+ * @param {Map<string, string>} familyWords
+ * @returns {boolean}
+ */
+function asksNewPage(phrases, familyWords) {
+ return phrases.some(phrase => {
+ const at = phrase.search(NEW);
+ if (at < 0) return false;
+ const after = terms(phrase.slice(at + 'new'.length));
+ return after.length === 0 || familyWords.has(after[0]);
+ });
+}
+
+/**
+ * The words of a component's name: "DateRangeInput" is date, range, input.
+ * @param {ComponentWords} component
+ * @returns {string[]}
+ */
+function nameTerms(component) {
+ return terms(component.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2'));
+}
+
+/**
+ * The terms a component answers to: the words of its name and of its keywords.
+ * @param {ComponentWords} component
+ * @returns {string[]}
+ */
+function componentTerms(component) {
+ return [
+ ...nameTerms(component),
+ ...component.keywords.flatMap(keyword => terms(keyword)),
+ ];
}
/**
@@ -416,14 +583,27 @@ export function pickAlternatives(ranked, startName, count = 2) {
}
/**
- * The template to start from, or null when the best one has too little
- * evidence to lead and the page should start from the app shell. Evidence is
- * two matched terms, the idea naming the template's family, or its container.
+ * The template to start from, or null for the kit's neutral app shell. A page
+ * needs evidence to lead: two matched terms, the idea naming the template's
+ * family, or its container. A part starts from the base template of the family
+ * the idea places it in, else from the app shell (spec:AST-048/FR3); an edit of
+ * a page the builder already has starts from the app shell (FR9). Either way,
+ * the app shell is the shell template the idea describes when one leads.
*
* @param {RankedPage[]} ranked
+ * @param {IdeaKind} [kind]
* @returns {RankedPage | null}
*/
-export function pickStart(ranked) {
+export function pickStart(ranked, kind = 'page') {
+ if (kind !== 'page') {
+ const host = kind === 'part' && ranked.find(r => r.base && r.familyNamed);
+ if (host) return host;
+ // Otherwise the app shell (FR2): the shell template the idea describes
+ // when one leads ("a frame with sidebar navigation"), else none, for the
+ // kit's neutral fallback.
+ const lead = pickStart(ranked);
+ return lead?.family === SHELL_FAMILY ? lead : null;
+ }
const top = ranked[0];
if (!top || top.score < START_SCORE) return null;
return top.hits >= START_TERMS || top.familyNamed || top.containerMatched
diff --git a/packages/cli/api/build/kit/rank.test.mjs b/packages/cli/api/build/kit/rank.test.mjs
index 6833bd234a..21d2ffad6d 100644
--- a/packages/cli/api/build/kit/rank.test.mjs
+++ b/packages/cli/api/build/kit/rank.test.mjs
@@ -2,14 +2,15 @@
/**
* @file Tests for build's page ranker: long ideas, head nouns, family bases,
- * rare-word weighting, and family words taken from the templates themselves.
+ * rare-word weighting, keywords, family words taken from the templates
+ * themselves, and parts told from pages by the system's own components.
*/
import {describe, it, expect} from 'vitest';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
-import {pickStart, rankPages} from './rank.mjs';
-import {loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
// api/build/kit/ -> up 5 = repo root (has packages/core and the templates).
const REPO = path.resolve(
@@ -17,14 +18,24 @@ const REPO = path.resolve(
'../../../../..',
);
-/** @param {string} name @param {string} category @param {string} description */
-const page = (name, category, description) => ({
+/**
+ * @param {string} name
+ * @param {string} category
+ * @param {string} description
+ * @param {string[]} [keywords]
+ */
+const page = (name, category, description, keywords = []) => ({
name,
displayName: name,
category,
description,
+ keywords,
+ command: `astryx template ${name} --type page`,
});
+/** @param {string} name @param {string[]} [keywords] */
+const component = (name, keywords = []) => ({name, keywords});
+
describe('rankPages on the shipped page templates', () => {
/** @param {string} query */
const start = async query =>
@@ -49,6 +60,19 @@ describe('rankPages on the shipped page templates', () => {
);
});
+ it('keeps the family base when a variant shares one incidental word', async () => {
+ // "comparison" and "cohort" name dashboard variants, but here each is one
+ // small part of a general dashboard.
+ expect(
+ await start(
+ 'support dashboard with ticket volume charts and a small comparison note',
+ ),
+ ).toBe('dashboard');
+ expect(
+ await start('sales dashboard with a cohort filter and weekly charts'),
+ ).toBe('dashboard');
+ });
+
it('lets the head noun decide between families', async () => {
// Both ideas mention a table and summary numbers; the head says which
// page it is.
@@ -64,6 +88,14 @@ describe('rankPages on the shipped page templates', () => {
).toMatch(/^table-/);
});
+ it('keeps a variant that leads when its family base cannot start alone', async () => {
+ // The dashboard base matches only the family word here; the funnel
+ // dashboard matches the idea.
+ expect(await start('a funnel for a dashboard')).toBe(
+ 'dashboard-cohort-funnel',
+ );
+ });
+
it('does not start from one rare word', async () => {
// "board" is the kanban board's own word; a game board is not a kanban.
expect(
@@ -75,11 +107,10 @@ describe('rankPages on the shipped page templates', () => {
describe('rankPages on any catalog', () => {
it('ranks only the templates it is given', () => {
const ranked = rankPages('dashboard', [
- page(
+ page('dashboard', 'Dashboard - Analytics', 'Tiles, charts, tables.', [
'dashboard',
- 'Dashboard - Analytics',
- 'Tiles, charts, tables. Dashboard, metrics.',
- ),
+ 'metrics',
+ ]),
]);
expect(ranked.map(r => r.name)).toEqual(['dashboard']);
});
@@ -88,17 +119,14 @@ describe('rankPages on any catalog', () => {
// An integration's family: its word is in two of its ids, so an idea
// naming it picks the family, and its base template leads it.
const catalog = [
- page(
+ page('dashboard', 'Dashboard - Analytics', 'Tiles, charts, tables.', [
'dashboard',
- 'Dashboard - Analytics',
- 'Tiles, charts, tables. Dashboard, metrics.',
- ),
- page('widget', 'Widget - Basic', 'One compact card. Widget, tile.'),
- page(
- 'widget-grid',
- 'Widget - Grid',
- 'Many compact cards in a grid. Widget wall.',
- ),
+ 'metrics',
+ ]),
+ page('widget', 'Widget - Basic', 'One compact card.', ['widget', 'tile']),
+ page('widget-grid', 'Widget - Grid', 'Many compact cards in a grid.', [
+ 'widget wall',
+ ]),
];
const ranked = rankPages('weather widget with charts', catalog);
expect(ranked[0].name).toBe('widget');
@@ -106,15 +134,41 @@ describe('rankPages on any catalog', () => {
expect(pickStart(ranked)?.name).toBe('widget');
});
+ it("counts a template's keywords above words in its description", () => {
+ // Both mention uptime; only one names it as an idea it serves.
+ const catalog = [
+ page('ops', 'Dashboard - Ops', 'Uptime strips beside alert rows.'),
+ page('health', 'Dashboard - Health', 'Status tiles over time charts.', [
+ 'uptime',
+ ]),
+ ];
+ expect(rankPages('uptime overview', catalog)[0].name).toBe('health');
+ });
+
+ it("lets a variant displace its family's base only with two words of its own", () => {
+ const catalog = [
+ page('widget', 'Widget - Basic', 'One compact card.', ['widget']),
+ page('widget-weather', 'Widget - Weather', 'A forecast card.', [
+ 'weather',
+ 'forecast',
+ 'radar',
+ ]),
+ ];
+ // One word of the variant's own: still the family's base.
+ expect(rankPages('weather widget', catalog)[0].name).toBe('widget');
+ // Two: the variant.
+ expect(rankPages('weather widget with radar', catalog)[0].name).toBe(
+ 'widget-weather',
+ );
+ });
+
it('weighs a word by how rare it is among page templates', () => {
const catalog = [
- page('alpha', 'Dashboard - Alpha', 'Status tiles. Status overview.'),
- page('beta', 'Dashboard - Beta', 'Status rows. Status list.'),
- page(
- 'gamma',
- 'Dashboard - Gamma',
- 'Funnel of stages. Funnel conversion.',
- ),
+ page('alpha', 'Dashboard - Alpha', 'Status tiles.', ['status overview']),
+ page('beta', 'Dashboard - Beta', 'Status rows.', ['status list']),
+ page('gamma', 'Dashboard - Gamma', 'Funnel of stages.', [
+ 'funnel conversion',
+ ]),
];
// "status" is on two templates, "funnel" on one: the rare word wins.
const ranked = rankPages('status funnel', catalog);
@@ -127,22 +181,24 @@ describe('rankPages structure signals', () => {
page(
'dialog-panel',
'Settings - Dialog',
- 'Preferences inside a modal container. Settings, or modal dialog.',
- ),
- page(
- 'tree-table',
- 'Table - Tree',
- 'Nested rows under parents. Tree, nested rows, file browser.',
- ),
- page(
- 'item-detail',
- 'Content - Item Detail',
- 'One item with its media. Product, listing, or item detail.',
+ 'Preferences inside a modal container.',
+ ['settings', 'modal dialog'],
),
+ page('tree-table', 'Table - Tree', 'Nested rows under parents.', [
+ 'tree',
+ 'nested rows',
+ 'file browser',
+ ]),
+ page('item-detail', 'Content - Item Detail', 'One item with its media.', [
+ 'product',
+ 'listing',
+ 'item detail',
+ ]),
page(
'docs-catalog',
'Content - Documentation Catalog',
- 'A grid of category cards. Documentation, docs, or API index.',
+ 'A grid of category cards.',
+ ['documentation', 'docs', 'api index'],
),
];
@@ -179,18 +235,145 @@ describe('rankPages structure signals', () => {
it('does not treat a synonym as a family name', () => {
// "landing" is a synonym of "hero" in search, not a family word here.
const heroes = [
- page(
- 'hero-centered',
- 'Gallery - Hero',
- 'A centered hero. Hero, banner, or landing.',
- ),
- page(
- 'hero-split',
- 'Gallery - Hero Split',
- 'A split hero. Hero or splash.',
- ),
+ page('hero-centered', 'Gallery - Hero', 'A centered hero.', [
+ 'hero',
+ 'banner',
+ 'landing',
+ ]),
+ page('hero-split', 'Gallery - Hero Split', 'A split hero.', [
+ 'hero',
+ 'splash',
+ ]),
];
const ranked = rankPages('internal landing page', heroes);
expect(ranked.every(r => !r.familyNamed)).toBe(true);
});
});
+
+describe('ideaKind: a part of a page, told by the components the system ships', () => {
+ const pages = [
+ page('table', 'Table - Basic', 'Rows of records.'),
+ page('table-filter', 'Table - Filtering', 'Rows narrowed by filters.'),
+ page('settings', 'Settings', 'Grouped preferences.'),
+ ];
+ const components = [
+ component('DateRangeInput', ['date picker']),
+ component('Tooltip'),
+ component('Calendar'),
+ component('Table'),
+ component('Dialog', ['modal']),
+ ];
+ /** @param {string} idea @param {object[]} [using] */
+ const kind = (idea, using = components) => ideaKind(idea, pages, using);
+
+ it('takes a part from a component name or keyword at the head', () => {
+ expect(kind('a date range input')).toBe('part');
+ expect(kind('a date picker with presets')).toBe('part');
+ expect(kind('a tooltip')).toBe('part');
+ });
+
+ it('takes a page word or a family word at the head as a page', () => {
+ expect(kind('a calendar')).toBe('part');
+ expect(kind('a team calendar page')).toBe('page');
+ // Table is a component, but table is also a family of page templates.
+ expect(kind('a data table with filters')).toBe('page');
+ });
+
+ it("reads parts from the project's own components", () => {
+ // An integration's component joins the vocabulary by existing.
+ expect(kind('a revenue gauge')).toBe('page');
+ expect(
+ kind('a revenue gauge', [...components, component('AcmeGauge')]),
+ ).toBe('part');
+ });
+
+ it("takes an idea that lists a page's worth of pieces as a page", () => {
+ expect(kind('a calendar with a tooltip')).toBe('part');
+ expect(kind('a calendar, a tooltip, and a date range input')).toBe('page');
+ });
+
+ it('takes the frame of a container phrase as the frame, not the head', () => {
+ expect(kind('a dialog')).toBe('part');
+ expect(kind('saved drafts in a modal')).toBe('page');
+ });
+
+ it('takes a change to an existing page or part as an edit', () => {
+ expect(kind('add a sort toggle to the existing reports table')).toBe(
+ 'edit',
+ );
+ expect(kind('reuse the existing tooltip on the chart')).toBe('edit');
+ });
+
+ it('does not take "existing" that names no page or part as an edit', () => {
+ expect(kind('a new settings page inspired by the existing one')).toBe(
+ 'page',
+ );
+ expect(kind('show existing users in a settings page')).toBe('page');
+ });
+
+ it('does not take a request for a new page as an edit', () => {
+ expect(
+ kind('a new settings page based on the existing settings page'),
+ ).toBe('page');
+ expect(kind('clone the existing table as a new page')).toBe('page');
+ // "A new column" asks for a part, so the change stays a change.
+ expect(kind('add a new column to the existing reports table')).toBe('edit');
+ });
+});
+
+describe('pickStart on parts and edits (spec:AST-048/FR3)', () => {
+ const shipped = Promise.all([loadPageTemplates(REPO), loadComponents(REPO)]);
+ /** @param {string} query */
+ const start = async query => {
+ const [catalog, components] = await shipped;
+ const kind = ideaKind(query, catalog, components);
+ return pickStart(rankPages(query, catalog), kind)?.name ?? null;
+ };
+
+ it('starts a part from the page it names, else from the app shell', async () => {
+ expect(await start('an empty state for a settings page')).toBe('settings');
+ expect(await start('a date range picker')).toBeNull();
+ expect(await start('compact status pill with a tooltip')).toBeNull();
+ });
+
+ it('starts an edit of an existing page or part from the app shell', async () => {
+ for (const idea of [
+ 'add a sparkline column to the existing incidents table',
+ 'add a sort toggle to the existing reports dashboard',
+ 'swap the existing banner for a toast',
+ ]) {
+ expect(await start(idea)).toBeNull();
+ }
+ });
+
+ it('starts a new page that mentions something existing from its template', async () => {
+ expect(await start('a new dashboard inspired by the existing one')).toBe(
+ 'dashboard',
+ );
+ expect(await start('show existing users in a table page')).toMatch(
+ /^table/,
+ );
+ });
+
+ it('starts a new page that names an existing one from its template', async () => {
+ for (const idea of [
+ 'a new dashboard based on the existing dashboard',
+ 'a new dashboard like the existing dashboard',
+ 'clone the existing dashboard as a new page',
+ ]) {
+ expect(await start(idea)).toBe('dashboard');
+ }
+ });
+
+ it('reads a bare "existing" phrase that names a page as the builder\'s page', async () => {
+ expect(
+ await start('existing reports dashboard with a date filter'),
+ ).toBeNull();
+ });
+
+ it('still starts a whole page from its template', async () => {
+ expect(
+ await start('saved drafts in a modal with resume and delete row actions'),
+ ).toBe('settings-dialog');
+ });
+});
diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjs
index 3ed753abef..7e819cb7bb 100644
--- a/packages/cli/api/integration/pack-check.mjs
+++ b/packages/cli/api/integration/pack-check.mjs
@@ -29,6 +29,7 @@ import {assertWithin} from '../../foundation/fs/path-safety.mjs';
import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
import {
docsTreeCliProblem,
+ keywordsCliProblem,
replacesCliProblem,
sectionIdsCliProblem,
themesCliProblem,
@@ -670,8 +671,9 @@ export async function integrationPackCheck(options = {}) {
}
}
}
- // A template that sets `replaces` needs a CLI that reads the field
- // (spec:AST-035): an older CLI drops that template and hides the package's docs.
+ // A template that sets `replaces` (spec:AST-035) or `keywords` needs a CLI
+ // that reads the field: an older CLI drops that template and hides the
+ // package's docs.
if (loaded.templates) {
const found = await discoverIntegrationTemplatesForOne(loaded).catch(
() => ({templates: [], errors: []}),
@@ -683,6 +685,13 @@ export async function integrationPackCheck(options = {}) {
);
const problem = setsReplaces ? replacesCliProblem(pkg) : null;
if (problem != null) issues.push(error('replaces_needs_cli', problem));
+ const setsKeywords = found.templates.some(
+ template => template.keywords != null && template.keywords.length > 0,
+ );
+ const keywordsProblem = setsKeywords ? keywordsCliProblem(pkg) : null;
+ if (keywordsProblem != null) {
+ issues.push(error('keywords_needs_cli', keywordsProblem));
+ }
}
// A theme needs a CLI that reads typed theme descriptors: an older CLI
// rejects the themes root and withholds the package's themes and docs.
diff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjs
index 8806626ff4..c908ca89da 100644
--- a/packages/cli/api/integration/pack-check.test.mjs
+++ b/packages/cli/api/integration/pack-check.test.mjs
@@ -469,6 +469,37 @@ describe('integrationPackCheck', () => {
expect(await codes()).not.toContain('replaces_needs_cli');
}, 120_000);
+ it('fails a package with a template that sets keywords on a CLI range that rejects the field', async () => {
+ writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
+ fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, 'templates', 'acme-health.doc.mjs'),
+ "export default {type: 'page', name: 'acme-health', description: 'Status tiles.', keywords: ['uptime']};\n",
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'templates', 'acme-health.tsx'),
+ 'export default function AcmeHealth() { return null; }\n',
+ );
+ const file = path.join(tmpDir, 'package.json');
+ const peer = (/** @type {string | undefined} */ range) => {
+ const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+ if (range == null) delete pkg.peerDependencies;
+ else pkg.peerDependencies = {'@astryxdesign/cli': range};
+ fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+ };
+ const codes = async () =>
+ (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+ (/** @type {{code: string}} */ issue) => issue.code,
+ );
+
+ peer(undefined);
+ expect(await codes()).toContain('keywords_needs_cli');
+ peer('^0.6.0');
+ expect(await codes()).toContain('keywords_needs_cli');
+ peer('>=0.7.0');
+ expect(await codes()).not.toContain('keywords_needs_cli');
+ }, 120_000);
+
it('passes when package.json has no files field', async () => {
writePackage({files: undefined});
const result = await integrationPackCheck({cwd: tmpDir});
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index d9883a0901..fd06f92f4c 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -1007,6 +1007,64 @@ async function gatherComponents(coreDir, cwd) {
return [...core, ...integrations];
}
+/**
+ * The components each search response was scored against, by response:
+ * `build` reads them to tell a part of a page from a page without gathering
+ * them again. Module-private, so they never enter search's JSON.
+ * @type {WeakMap<object, {name: string, keywords: string[]}[]>}
+ */
+const searchedComponentsOf = new WeakMap();
+
+/**
+ * The components (name and keywords) a search response was scored against, or
+ * null when that search was narrowed away from components.
+ * @param {object} response
+ * @returns {{name: string, keywords: string[]}[] | null}
+ */
+export function searchedComponents(response) {
+ return searchedComponentsOf.get(response) ?? null;
+}
+
+/**
+ * Every component the project can use, Core's and its integrations', with the
+ * keywords its own doc declares: the discovery and doc reads search's own
+ * candidates use, without the import paths and prose a result carries. `build`
+ * reads it to tell a part of a page from a page when its search was narrowed
+ * away from components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<{name: string, keywords: string[]}[]>}
+ */
+export async function componentKeywords(coreDir, cwd) {
+ /** @param {any} doc */
+ const keywordsOf = doc => (Array.isArray(doc?.keywords) ? doc.keywords : []);
+ const core = Object.values(discoverComponents(coreDir))
+ .flat()
+ .map(async name => {
+ const readme = findComponentReadme(coreDir, name);
+ const doc =
+ readme && readme.endsWith('.doc.mjs')
+ ? await loadModuleDoc(readme)
+ : null;
+ return {name, keywords: keywordsOf(doc)};
+ });
+ const integrations = (await loadIntegrationsSafely(cwd)).map(
+ async integration => {
+ const {components} = await discoverValidIntegrationComponents(integration);
+ return Promise.all(
+ components.map(async rec => ({
+ name: rec.name,
+ keywords: keywordsOf(await loadModuleDoc(rec.docPath)),
+ })),
+ );
+ },
+ );
+ return [
+ ...(await Promise.all(core)),
+ ...(await Promise.all(integrations)).flat(),
+ ];
+}
+
/**
* Build hook candidates: name + keywords + usage/description from the hook's
* .doc.mjs.
@@ -1393,6 +1451,10 @@ async function gatherTemplates(cwd) {
keywords,
weakKeywords,
description: t.description || '',
+ // A template's own keywords name the many ideas it serves, so they score
+ // as its prose does, not as a name: one of them matching one word of a
+ // short idea is not a direct match.
+ prose: t.keywords ?? [],
_displayName: t.name,
_kind: t.type, // 'page' | 'block'
_resultName: t.dirName,
@@ -1563,7 +1625,8 @@ export async function search(query, options = {}) {
// 57 things and one matching exactly 20 would be indistinguishable.
const limited = scored.slice(0, limit);
- return {
+ /** @type {import('./search.type.mjs').SearchResponse} */
+ const response = {
type: 'search',
data: {
query: String(query).trim(),
@@ -1574,4 +1637,11 @@ export async function search(query, options = {}) {
),
},
};
+ if (wants('component')) {
+ searchedComponentsOf.set(
+ response,
+ components.map(c => ({name: c.name, keywords: c.keywords ?? []})),
+ );
+ }
+ return response;
}
diff --git a/packages/cli/api/template/template-integration.test.mjs b/packages/cli/api/template/template-integration.test.mjs
index 7588e39802..434b486e6a 100644
--- a/packages/cli/api/template/template-integration.test.mjs
+++ b/packages/cli/api/template/template-integration.test.mjs
@@ -125,6 +125,20 @@ describe('integration template discovery', () => {
expect(entry.description).toBe('pricing desc');
});
+ it("reads an integration template's keywords in search and build", async () => {
+ const pkgDir = installWidgets(tmpDir);
+ writeTemplate(pkgDir, 'observatory', {
+ kind: 'page',
+ body: "export default {type: 'page', name: 'Observatory', description: 'Live tiles over a sky view.', category: 'Dashboard - Observatory', keywords: ['telescope', 'star map']};\n",
+ });
+
+ const found = await search('telescope', {cwd: tmpDir, type: 'template'});
+ expect(found.data.results.map(r => r.name)).toContain('observatory');
+ const kit = await build('telescope star map page', {cwd: tmpDir});
+ if (kit.type !== 'build.kit') throw new Error(kit.type);
+ expect(kit.data.start?.name).toBe('observatory');
+ });
+
it('preserves integration block showcase metadata in list output', async () => {
const pkgDir = installWidgets(tmpDir);
writeTemplate(pkgDir, 'chart-showcase', {
diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjs
index a22a0a5a4e..493787b2ab 100644
--- a/packages/cli/assets/docs/tree/checks.doc.mjs
+++ b/packages/cli/assets/docs/tree/checks.doc.mjs
@@ -106,7 +106,7 @@ export const docs = {
'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
"It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
- 'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.7.0` for a docs section, a placed guide, or a template `replaces`, and `>=0.6.4` for a doc section with an `id` or a theme.',
+ 'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.7.0` for a docs section, a placed guide, or a template `replaces` or `keywords`, and `>=0.6.4` for a doc section with an `id` or a theme.',
],
},
{
diff --git a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
index 8e32fac354..a51ca83853 100644
--- a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
@@ -60,7 +60,14 @@ export const docs = {
type: 'reference',
target: 'schema:template-doc',
projection: {
- fields: ['type', 'name', 'displayName', 'description', 'isReady'],
+ fields: [
+ 'type',
+ 'name',
+ 'displayName',
+ 'description',
+ 'keywords',
+ 'isReady',
+ ],
},
presentation: 'full',
},
@@ -71,9 +78,14 @@ export const docs = {
'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
+ "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. `astryx search` matches them as it matches the description, and `astryx build` ranks page templates on them, so the description can stay about the layout.",
'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
],
},
+ {
+ type: 'prose',
+ text: 'Note: `keywords` needs `@astryxdesign/cli` 0.7.0 or later. A stable CLI before 0.7.0 rejects the field, drops that template, and hides your doc topics: `template --list` and `search` print one warning, and `docs` and `build` say nothing. Declare the CLI floor as an optional peer ({@link generic:versioning}); `integration verify` fails until you do.',
+ },
],
},
{
diff --git a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
index fc6cd21c34..0e1a75eab2 100644
--- a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
+++ b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
@@ -93,6 +93,10 @@ export const docs = {
'`replaces_needs_cli`: The package has a template that sets `replaces` but declares no @astryxdesign/cli peer.',
'Same fix: an older CLI rejects `replaces`, drops that template, and hides your doc topics.',
],
+ [
+ '`keywords_needs_cli`: The package has a template that sets `keywords` but declares no @astryxdesign/cli peer.',
+ 'Same fix: an older CLI rejects `keywords`, drops that template, and hides your doc topics.',
+ ],
[
'`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',
"Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A stable CLI before 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
@@ -135,7 +139,7 @@ export const docs = {
],
[
'Your docs section, templates, or themes are missing only in some apps',
- 'Those apps run a CLI too old to read them: a stable CLI before 0.7.0 for a docs section or a template that sets `replaces`, or before 0.6.4 for a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
+ 'Those apps run a CLI too old to read them: a stable CLI before 0.7.0 for a docs section or a template that sets `replaces` or `keywords`, or before 0.6.4 for a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
],
],
},
diff --git a/packages/cli/assets/docs/tree/versioning.doc.mjs b/packages/cli/assets/docs/tree/versioning.doc.mjs
index 5b8cd88bfe..2acb6f237c 100644
--- a/packages/cli/assets/docs/tree/versioning.doc.mjs
+++ b/packages/cli/assets/docs/tree/versioning.doc.mjs
@@ -106,8 +106,8 @@ export const docs = {
],
[
'`@astryxdesign/cli`',
- 'You ship a docs section, a placed guide, a template that sets `replaces`, a doc section with an `id`, or a theme',
- '`>=0.7.0` for a docs section, a placed guide, or `replaces`; `>=0.6.4` when you ship only a theme or a section `id`. Optional in `peerDependenciesMeta`',
+ 'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a doc section with an `id`, or a theme',
+ '`>=0.7.0` for a docs section, a placed guide, `replaces`, or `keywords`; `>=0.6.4` when you ship only a theme or a section `id`. Optional in `peerDependenciesMeta`',
],
],
},
@@ -137,14 +137,14 @@ export const docs = {
'An unknown field in `astryx.integration.mjs` is ignored with an `unknown_manifest_key` warning, and the rest of the manifest still loads.',
'A named export that the CLI does not know is ignored with no warning, so `debug` and `gapReport` are safe to add.',
'A stable CLI before 0.7.0 prints each `{@link ...}` as written.',
- 'A stable CLI before 0.7.0 cannot read a docs section or a template that sets `replaces`. It can then hide every doc topic your package ships.',
+ 'A stable CLI before 0.7.0 cannot read a docs section or a template that sets `replaces` or `keywords`. It can then hide every doc topic your package ships.',
'A stable CLI before 0.6.4 cannot read a section `id` or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
],
},
{
type: 'prose',
- text: '`integration verify` requires the CLI peer for a docs section, a placed guide, a template `replaces`, a doc section with an `id`, and a theme. A CLI too old for one of them cannot read it, and when it hides your topics, `docs` gives no warning.',
+ text: '`integration verify` requires the CLI peer for a docs section, a placed guide, a template `replaces` or `keywords`, a doc section with an `id`, and a theme. A CLI too old for one of them cannot read it, and when it hides your topics, `docs` gives no warning.',
},
],
},
diff --git a/packages/cli/assets/templates/pages/ai-chat-landing/template.doc.mjs b/packages/cli/assets/templates/pages/ai-chat-landing/template.doc.mjs
index 98ac47c180..ea45c4ab85 100644
--- a/packages/cli/assets/templates/pages/ai-chat-landing/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/ai-chat-landing/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'AI Chat Landing',
displayName: 'AI Chat Landing',
- description: 'Zero-state entry surface centered on a single composer with suggestion chips instead of history, sized for the moment before any content exists. The empty counterpart to a transcript. Chat, conversation, assistant, prompt, or messages launcher.',
+ description:
+ 'Zero-state entry surface centered on a single composer with suggestion chips instead of history, sized for the moment before any content exists. The empty counterpart to a transcript.',
+ keywords: [
+ 'chat',
+ 'conversation',
+ 'assistant',
+ 'prompt',
+ 'messages launcher',
+ ],
isReady: true,
category: 'AI Chat - Landing',
};
diff --git a/packages/cli/assets/templates/pages/ai-chat/template.doc.mjs b/packages/cli/assets/templates/pages/ai-chat/template.doc.mjs
index 0a6913609a..28fe67d237 100644
--- a/packages/cli/assets/templates/pages/ai-chat/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/ai-chat/template.doc.mjs
@@ -5,7 +5,22 @@ export const doc = {
type: 'page',
name: 'AI Chat Conversation',
displayName: 'AI Chat Conversation',
- description: 'Transcript of alternating turns carrying mixed rich content inline (markdown, code blocks, collapsible tool-call output) beside a resizable artifact panel that holds generated output while the stream keeps scrolling. Chat, conversation, assistant, messages, or copilot thread.',
+ description:
+ 'Transcript of alternating turns carrying mixed rich content inline (markdown, code blocks, collapsible tool-call output) beside a resizable artifact panel that holds generated output while the stream keeps scrolling.',
+ keywords: [
+ 'chat',
+ 'conversation',
+ 'assistant',
+ 'messages',
+ 'copilot thread',
+ 'agent',
+ 'session',
+ 'composer',
+ 'questions',
+ 'answers with citations',
+ 'reasoning trace',
+ 'prompt playground',
+ ],
isReady: true,
category: 'AI Chat - Conversation',
};
diff --git a/packages/cli/assets/templates/pages/blank/template.doc.mjs b/packages/cli/assets/templates/pages/blank/template.doc.mjs
index e6d36f3153..836cecae60 100644
--- a/packages/cli/assets/templates/pages/blank/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/blank/template.doc.mjs
@@ -5,7 +5,9 @@ export const doc = {
type: 'page',
name: 'Blank',
displayName: 'Blank',
- description: 'Bare scaffold: one heading slot, one empty content region, no navigation and no chrome. The starting point when every other layout imposes more structure than wanted. Blank, empty, stub, placeholder, or minimal scaffold.',
+ description:
+ 'Bare scaffold: one heading slot, one empty content region, no navigation and no chrome. The starting point when every other layout imposes more structure than wanted.',
+ keywords: ['blank', 'empty', 'stub', 'placeholder', 'minimal scaffold'],
isReady: true,
scaffold: true,
category: 'Shell - Blank',
diff --git a/packages/cli/assets/templates/pages/canvas-editor/template.doc.mjs b/packages/cli/assets/templates/pages/canvas-editor/template.doc.mjs
index bfb99dcdd7..14457a9d2b 100644
--- a/packages/cli/assets/templates/pages/canvas-editor/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/canvas-editor/template.doc.mjs
@@ -6,7 +6,15 @@ export const doc = {
name: 'Canvas Editor',
displayName: 'Canvas Editor',
description:
- 'Layered artboard workspace: document tabs over a layer rail, a fixed-size frame you zoom on a muted backdrop, and an inspector of position, type, and filter fields that retargets to the selected layer. Objects hold a coordinate rather than reflowing, so moving one never moves another. Design tool, artboard, poster, graphic, image, or slide editor.',
+ 'Layered artboard workspace: document tabs over a layer rail, a fixed-size frame you zoom on a muted backdrop, and an inspector of position, type, and filter fields that retargets to the selected layer. Objects hold a coordinate rather than reflowing, so moving one never moves another.',
+ keywords: [
+ 'design tool',
+ 'artboard',
+ 'poster',
+ 'graphic',
+ 'image',
+ 'slide editor',
+ ],
isReady: true,
category: 'Tools - Canvas Editor',
};
diff --git a/packages/cli/assets/templates/pages/centered-hero/template.doc.mjs b/packages/cli/assets/templates/pages/centered-hero/template.doc.mjs
index fc89316317..e2ad85e124 100644
--- a/packages/cli/assets/templates/pages/centered-hero/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/centered-hero/template.doc.mjs
@@ -5,7 +5,9 @@ export const doc = {
type: 'page',
name: 'Centered Hero',
displayName: 'Centered Hero',
- description: 'Symmetrical centered stack (headline, short blurb, paired call-to-action buttons) resting on one wide full-bleed picture, with nothing on either flank competing. Hero, banner, splash, landing image, or marketing masthead.',
+ description:
+ 'Symmetrical centered stack (headline, short blurb, paired call-to-action buttons) resting on one wide full-bleed picture, with nothing on either flank competing.',
+ keywords: ['hero', 'banner', 'splash', 'landing image', 'marketing masthead'],
isReady: true,
category: 'Gallery - Hero',
};
diff --git a/packages/cli/assets/templates/pages/checkout-wizard/template.doc.mjs b/packages/cli/assets/templates/pages/checkout-wizard/template.doc.mjs
index 8efd98f78c..1f8acef0a4 100644
--- a/packages/cli/assets/templates/pages/checkout-wizard/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/checkout-wizard/template.doc.mjs
@@ -7,6 +7,7 @@ export const doc = {
displayName: 'Checkout Wizard',
description:
'Multi-step checkout, cart, order, and payment wizard with a running summary that recalculates as answers change. It adapts to its host width, renders the summary first on narrow surfaces, validates every forward path, and completes locally without sending payment.',
+ keywords: ['checkout', 'cart', 'order', 'payment'],
isReady: true,
category: 'Form - Checkout',
};
diff --git a/packages/cli/assets/templates/pages/classic-gallery/template.doc.mjs b/packages/cli/assets/templates/pages/classic-gallery/template.doc.mjs
index 782e0f7844..d2dd44f6fd 100644
--- a/packages/cli/assets/templates/pages/classic-gallery/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/classic-gallery/template.doc.mjs
@@ -4,7 +4,9 @@
export const doc = {
name: 'Classic Gallery',
displayName: 'Classic Gallery',
- description: 'Uniform grid of equal-ratio media tiles under a centered intro, with filter tabs that narrow the set in place. Regular rhythm, unlike the variable-height masonry variant. Gallery, photos, images, pictures, or portfolio index.',
+ description:
+ 'Uniform grid of equal-ratio media tiles under a centered intro, with filter tabs that narrow the set in place. Regular rhythm, unlike the variable-height masonry variant.',
+ keywords: ['gallery', 'photos', 'images', 'pictures', 'portfolio index'],
type: 'page',
isReady: true,
category: 'Gallery - Basic',
diff --git a/packages/cli/assets/templates/pages/contact-form/template.doc.mjs b/packages/cli/assets/templates/pages/contact-form/template.doc.mjs
index 460d73eae6..d8ebc369e7 100644
--- a/packages/cli/assets/templates/pages/contact-form/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/contact-form/template.doc.mjs
@@ -5,7 +5,22 @@ export const doc = {
type: 'page',
name: 'Contact Form',
displayName: 'Contact Form',
- description: 'Flat single-column form mixing control types (text, pill toggles, dropdowns, long free-text) landing on one full-width submit. No steps, no branching, no summary rail. Contact, lead capture, enquiry, survey, or intake form.',
+ description:
+ 'Flat single-column form mixing control types (text, pill toggles, dropdowns, long free-text) landing on one full-width submit. No steps, no branching, no summary rail.',
+ keywords: [
+ 'contact',
+ 'lead capture',
+ 'enquiry',
+ 'survey',
+ 'intake form',
+ 'questionnaire',
+ 'feedback',
+ 'request',
+ 'submission',
+ 'entry',
+ 'fields',
+ 'upload',
+ ],
isReady: true,
category: 'Form - Basic',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-alert-rail/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-alert-rail/template.doc.mjs
index f15c4f4032..2039941f02 100644
--- a/packages/cli/assets/templates/pages/dashboard-alert-rail/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-alert-rail/template.doc.mjs
@@ -6,7 +6,29 @@ export const doc = {
name: 'Service Monitoring Dashboard',
displayName: 'Service Monitoring Dashboard',
description:
- 'Always-on analytics with a triage rail: status-colored tiles with sparklines, multi-series time charts over a switchable window, and an independently scrolling alert column that folds into the content when narrow. Monitoring, uptime, health, latency, alerting, incidents, or observability.',
+ 'Always-on analytics with a triage rail: status-colored tiles with sparklines, multi-series time charts over a switchable window, and an independently scrolling alert column that folds into the content when narrow.',
+ keywords: [
+ 'monitoring',
+ 'uptime',
+ 'health',
+ 'latency',
+ 'alerting',
+ 'incidents',
+ 'observability',
+ 'operations',
+ 'live status',
+ 'real-time',
+ 'reliability',
+ 'traffic',
+ 'anomalies',
+ 'severity',
+ 'on-call',
+ 'oncall',
+ 'fleet',
+ 'pipelines',
+ 'freshness',
+ 'command center',
+ ],
isReady: true,
category: 'Dashboard - Monitoring',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-cohort-funnel/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-cohort-funnel/template.doc.mjs
index e8562a620b..29402d9e7f 100644
--- a/packages/cli/assets/templates/pages/dashboard-cohort-funnel/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-cohort-funnel/template.doc.mjs
@@ -6,7 +6,16 @@ export const doc = {
name: 'Funnel & Cohort Dashboard',
displayName: 'Funnel & Cohort Dashboard',
description:
- 'Analytics for sequence and retention questions, pairing two shapes a plain dashboard cannot hold: a staged funnel where each step reads as drop-off against the one before, and a two-axis cohort matrix rendered as a heatmap. Conversion, drop-off, activation, churn, or retention reporting.',
+ 'Analytics for sequence and retention questions, pairing two shapes a plain dashboard cannot hold: a staged funnel where each step reads as drop-off against the one before, and a two-axis cohort matrix rendered as a heatmap.',
+ keywords: [
+ 'conversion',
+ 'drop-off',
+ 'activation',
+ 'churn',
+ 'retention reporting',
+ 'stages',
+ 'segments',
+ ],
isReady: true,
category: 'Dashboard - Funnel & Cohort',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-comparison/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-comparison/template.doc.mjs
index 2678c6785b..a1ee039008 100644
--- a/packages/cli/assets/templates/pages/dashboard-comparison/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-comparison/template.doc.mjs
@@ -6,7 +6,15 @@ export const doc = {
name: 'Data Dashboard',
displayName: 'Data Dashboard',
description:
- 'Comparison-heavy analytics behind a persistent filter bar: tiles that each carry an inline sparkline and several period-over-period deltas, then segmented breakdowns underneath. Every number is shown against another number. Dashboard, metrics, stats, analytics, trends, or reporting.',
+ 'Comparison-heavy analytics behind a persistent filter bar: tiles that each carry an inline sparkline and several period-over-period deltas, then segmented breakdowns underneath. Every number is shown against another number.',
+ keywords: [
+ 'dashboard',
+ 'metrics',
+ 'stats',
+ 'analytics',
+ 'trends',
+ 'reporting',
+ ],
isReady: true,
category: 'Dashboard - Comparison',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-composition/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-composition/template.doc.mjs
index e409d95d6c..9d80168695 100644
--- a/packages/cli/assets/templates/pages/dashboard-composition/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-composition/template.doc.mjs
@@ -6,7 +6,16 @@ export const doc = {
name: 'Portfolio Dashboard',
displayName: 'Portfolio Dashboard',
description:
- 'Analytics for a value-over-time question: balance and change tiles above a stacked area chart of composition through time, closing on a ranked table of the largest contributors. Portfolio, holdings, positions, returns, allocation, investments, or performance reporting.',
+ 'Analytics for a value-over-time question: balance and change tiles above a stacked area chart of composition through time, closing on a ranked table of the largest contributors.',
+ keywords: [
+ 'portfolio',
+ 'holdings',
+ 'positions',
+ 'returns',
+ 'allocation',
+ 'investments',
+ 'performance reporting',
+ ],
isReady: true,
category: 'Dashboard - Portfolio',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-progress/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-progress/template.doc.mjs
index b031bf41ed..4ad3ca45c3 100644
--- a/packages/cli/assets/templates/pages/dashboard-progress/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-progress/template.doc.mjs
@@ -6,7 +6,23 @@ export const doc = {
name: 'Project Status Dashboard',
displayName: 'Project Status Dashboard',
description:
- 'Status analytics mixing progress and time-axis shapes: a completion donut, a horizontal timeline of dated bars against a today marker, a per-owner table with progress and status, an at-risk list, and a burndown. Project, program, milestone, roadmap, launch, or delivery status.',
+ 'Status analytics mixing progress and time-axis shapes: a completion donut, a horizontal timeline of dated bars against a today marker, a per-owner table with progress and status, an at-risk list, and a burndown.',
+ keywords: [
+ 'project',
+ 'program',
+ 'milestone',
+ 'roadmap',
+ 'launch',
+ 'delivery status',
+ 'workstreams and milestones',
+ 'gates',
+ 'blockers',
+ 'gantt',
+ 'rollout',
+ 'release planning',
+ 'readiness',
+ 'tracker',
+ ],
isReady: true,
category: 'Dashboard - Project Status',
};
diff --git a/packages/cli/assets/templates/pages/dashboard-scorecard/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard-scorecard/template.doc.mjs
index 25b645a5dc..01535297b7 100644
--- a/packages/cli/assets/templates/pages/dashboard-scorecard/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard-scorecard/template.doc.mjs
@@ -6,7 +6,8 @@ export const doc = {
name: 'Executive Summary Dashboard',
displayName: 'Executive Summary Dashboard',
description:
- 'Report-shaped analytics with a prose rail beside the charts: a scorecard of headline numbers with period deltas and status coloring, goal-attainment bars, a trend grid, and a written commentary column that folds beneath the content when narrow. Executive summary, business review, readout, or reporting.',
+ 'Report-shaped analytics with a prose rail beside the charts: a scorecard of headline numbers with period deltas and status coloring, goal-attainment bars, a trend grid, and a written commentary column that folds beneath the content when narrow.',
+ keywords: ['executive summary', 'business review', 'readout', 'reporting'],
isReady: true,
category: 'Dashboard - Scorecard',
};
diff --git a/packages/cli/assets/templates/pages/dashboard/template.doc.mjs b/packages/cli/assets/templates/pages/dashboard/template.doc.mjs
index a690b798e5..3b89d74991 100644
--- a/packages/cli/assets/templates/pages/dashboard/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/dashboard/template.doc.mjs
@@ -6,7 +6,21 @@ export const doc = {
name: 'Analytics Dashboard',
displayName: 'Analytics Dashboard',
description:
- 'Three-band analytics: a row of headline tiles, then charts, then supporting tables, all re-reading from one global filter bar. Breadth over depth, a summary surface rather than a drill-down. Dashboard, overview, metrics, stats, analytics, reporting, or insights.',
+ 'Three-band analytics: a row of headline tiles, then charts, then supporting tables, all re-reading from one global filter bar. Breadth over depth, a summary surface rather than a drill-down.',
+ keywords: [
+ 'dashboard',
+ 'overview',
+ 'metrics',
+ 'stats',
+ 'analytics',
+ 'reporting',
+ 'insights',
+ 'kpi tiles',
+ 'widgets',
+ 'donut charts',
+ 'breakdowns',
+ 'forecasts',
+ ],
isReady: true,
category: 'Dashboard - Analytics',
};
diff --git a/packages/cli/assets/templates/pages/detail-page/template.doc.mjs b/packages/cli/assets/templates/pages/detail-page/template.doc.mjs
index 6a48583741..7916c01e4f 100644
--- a/packages/cli/assets/templates/pages/detail-page/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/detail-page/template.doc.mjs
@@ -6,6 +6,14 @@ export const doc = {
name: 'Order Detail',
displayName: 'Order Detail',
description: 'Single-record detail in two columns: a summary header with status and actions, a repeating line-item list, a totals block that sums it, and a chronological activity timeline in the rail. The shape for any record holding children plus a history: a customer order with shipping, an invoice, a transaction, or a job.',
+ keywords: [
+ 'order',
+ 'invoice',
+ 'transaction',
+ 'job',
+ 'record detail',
+ 'summary header',
+ ],
isReady: true,
category: 'Content - Order Detail',
};
diff --git a/packages/cli/assets/templates/pages/documentation-design/template.doc.mjs b/packages/cli/assets/templates/pages/documentation-design/template.doc.mjs
index b22dcafb5d..39d10eb9c4 100644
--- a/packages/cli/assets/templates/pages/documentation-design/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/documentation-design/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Documentation Design',
displayName: 'Documentation Design',
- description: 'Reference article alternating prose with live rendered examples: an interactive preview, a property table, paired do and don\'t comparisons, and copyable code blocks. Documentation, docs, guide, reference, usage, or API entry.',
+ description:
+ 'Reference article alternating prose with live rendered examples: an interactive preview, a property table, paired do and don\'t comparisons, and copyable code blocks.',
+ keywords: [
+ 'documentation',
+ 'docs',
+ 'guide',
+ 'reference',
+ 'usage',
+ 'api entry',
+ ],
isReady: true,
category: 'Content - Documentation Design',
};
diff --git a/packages/cli/assets/templates/pages/documentation-technical/template.doc.mjs b/packages/cli/assets/templates/pages/documentation-technical/template.doc.mjs
index d10d464d25..eecebbe370 100644
--- a/packages/cli/assets/templates/pages/documentation-technical/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/documentation-technical/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Documentation Technical',
displayName: 'Documentation Technical',
- description: 'Reference article ordered as sequential numbered steps with code at each stage, plus callout cards for prerequisites and onward links. A linear walkthrough rather than a browsable reference. Getting started, install, setup, tutorial, quickstart, or onboarding guide.',
+ description:
+ 'Reference article ordered as sequential numbered steps with code at each stage, plus callout cards for prerequisites and onward links. A linear walkthrough rather than a browsable reference.',
+ keywords: [
+ 'getting started',
+ 'install',
+ 'setup',
+ 'tutorial',
+ 'quickstart',
+ 'onboarding guide',
+ ],
isReady: true,
category: 'Content - Documentation Technical',
};
diff --git a/packages/cli/assets/templates/pages/documentation/template.doc.mjs b/packages/cli/assets/templates/pages/documentation/template.doc.mjs
index 87f3984145..7fa5a14772 100644
--- a/packages/cli/assets/templates/pages/documentation/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/documentation/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Documentation Catalog',
displayName: 'Documentation Catalog',
- description: 'Reference landing that is pure wayfinding: a banner above a grid of category cards linking into sections, with no article content on the surface itself. Documentation, docs, guide, handbook, reference, or API index.',
+ description:
+ 'Reference landing that is pure wayfinding: a banner above a grid of category cards linking into sections, with no article content on the surface itself.',
+ keywords: [
+ 'documentation',
+ 'docs',
+ 'guide',
+ 'handbook',
+ 'reference',
+ 'api index',
+ ],
isReady: true,
category: 'Content - Documentation Catalog',
};
diff --git a/packages/cli/assets/templates/pages/editor/template.doc.mjs b/packages/cli/assets/templates/pages/editor/template.doc.mjs
index 177d27bbf9..bbbbe8f3a4 100644
--- a/packages/cli/assets/templates/pages/editor/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/editor/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'Page Editor',
displayName: 'Page Editor',
- description: 'Three-pane authoring workspace: a source palette on one flank, a live canvas in the middle, and an inspector that retargets to whatever is selected. Drag and drop to reorder, edit to see it render immediately. Builder, composer, drag and drop, page builder, or WYSIWYG editor.',
+ description:
+ 'Three-pane authoring workspace: a source palette on one flank, a live canvas in the middle, and an inspector that retargets to whatever is selected. Drag and drop to reorder, edit to see it render immediately.',
+ keywords: [
+ 'builder',
+ 'composer',
+ 'drag and drop',
+ 'page builder',
+ 'wysiwyg editor',
+ ],
isReady: true,
category: 'Tools - Page Editor',
};
diff --git a/packages/cli/assets/templates/pages/file-explorer/template.doc.mjs b/packages/cli/assets/templates/pages/file-explorer/template.doc.mjs
index 9acb255612..7cb7486f29 100644
--- a/packages/cli/assets/templates/pages/file-explorer/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/file-explorer/template.doc.mjs
@@ -5,7 +5,9 @@ export const doc = {
type: 'page',
name: 'File Explorer',
displayName: 'File Explorer',
- description: 'Hierarchical browser that drills through nested levels as adjacent columns rather than replacing the list each time, with breadcrumb history, switchable list and grid density, and a metadata pane for the selected node. Files, folders, directory, tree, or Finder-style navigator.',
+ description:
+ 'Hierarchical browser that drills through nested levels as adjacent columns rather than replacing the list each time, with breadcrumb history, switchable list and grid density, and a metadata pane for the selected node.',
+ keywords: ['files', 'folders', 'directory', 'tree', 'finder-style navigator'],
isReady: true,
category: 'Tools - File Explorer',
};
diff --git a/packages/cli/assets/templates/pages/form-two-column/template.doc.mjs b/packages/cli/assets/templates/pages/form-two-column/template.doc.mjs
index 0e7b294eac..eb1334465b 100644
--- a/packages/cli/assets/templates/pages/form-two-column/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/form-two-column/template.doc.mjs
@@ -5,7 +5,23 @@ export const doc = {
type: 'page',
name: 'Two-column Form',
displayName: 'Two-column Form',
- description: 'Form split into two columns beneath a hero header: inputs on one flank, a persistent context panel opposite that stays put while the fields scroll. Flat, single submit, no steps. Contact, lead capture, intake, request, or enquiry form.',
+ description:
+ 'Form split into two columns beneath a hero header: inputs on one flank, a persistent context panel opposite that stays put while the fields scroll. Flat, single submit, no steps.',
+ keywords: [
+ 'contact',
+ 'lead capture',
+ 'intake',
+ 'request',
+ 'enquiry form',
+ 'configurator',
+ 'generator',
+ 'launcher',
+ 'calculator',
+ 'checklist',
+ 'upload',
+ 'live preview',
+ 'side panel',
+ ],
isReady: true,
category: 'Form - Two-column',
};
diff --git a/packages/cli/assets/templates/pages/form-wizard-dialog/template.doc.mjs b/packages/cli/assets/templates/pages/form-wizard-dialog/template.doc.mjs
index 908b0a0b6b..471ed8301a 100644
--- a/packages/cli/assets/templates/pages/form-wizard-dialog/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/form-wizard-dialog/template.doc.mjs
@@ -7,6 +7,7 @@ export const doc = {
displayName: 'Dialog Wizard',
description:
'Step through a short flow in a dialog, overlay, or popup launched from the page underneath, which stays where it was. Compact step markers and a pinned action row inside a constrained width, rather than the full page a wizard usually gets. Best for two to four short steps — setup, invite, schedule, onboarding — where losing the context underneath would cost more than the flow is worth.',
+ keywords: ['setup', 'invite', 'schedule', 'onboarding'],
isReady: true,
category: 'Form - Wizard Dialog',
};
diff --git a/packages/cli/assets/templates/pages/form-wizard/template.doc.mjs b/packages/cli/assets/templates/pages/form-wizard/template.doc.mjs
index ee89beb623..478ac34037 100644
--- a/packages/cli/assets/templates/pages/form-wizard/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/form-wizard/template.doc.mjs
@@ -6,7 +6,20 @@ export const doc = {
name: 'Form Wizard',
displayName: 'Form Wizard',
description:
- 'Linear multi-step form that moves through one panel at a time, with a horizontal progress track pinned above rather than running down a rail, so every step keeps the full content width for its fields. Only the current step renders, unlike an accordion where each section expands into one long scrolling form. Each advance is validated, and a step left broken stays flagged to jump back to. Wizard, stepper, multi-step, onboarding, setup, signup, or guided flow.',
+ 'Linear multi-step form that moves through one panel at a time, with a horizontal progress track pinned above rather than running down a rail, so every step keeps the full content width for its fields. Only the current step renders, unlike an accordion where each section expands into one long scrolling form. Each advance is validated, and a step left broken stays flagged to jump back to.',
+ keywords: [
+ 'wizard',
+ 'stepper',
+ 'multi-step',
+ 'onboarding',
+ 'setup',
+ 'signup',
+ 'guided flow',
+ 'step-by-step',
+ 'workflow',
+ 'review step',
+ 'request flow',
+ ],
isReady: true,
category: 'Form - Wizard',
};
diff --git a/packages/cli/assets/templates/pages/gallery-hero/template.doc.mjs b/packages/cli/assets/templates/pages/gallery-hero/template.doc.mjs
index 7c452457d7..a49d952293 100644
--- a/packages/cli/assets/templates/pages/gallery-hero/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/gallery-hero/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Gallery Hero',
displayName: 'Gallery Hero',
- description: 'Centered stack (headline, short blurb, call-to-action buttons) resolving into a multi-image photo grid rather than one wide full-bleed picture, so the imagery reads as a set. Hero, banner, splash, landing image, masthead, or gallery intro.',
+ description:
+ 'Centered stack (headline, short blurb, call-to-action buttons) resolving into a multi-image photo grid rather than one wide full-bleed picture, so the imagery reads as a set.',
+ keywords: [
+ 'hero',
+ 'banner',
+ 'splash',
+ 'landing image',
+ 'masthead',
+ 'gallery intro',
+ ],
isReady: true,
category: 'Gallery - Hero',
};
diff --git a/packages/cli/assets/templates/pages/ide/template.doc.mjs b/packages/cli/assets/templates/pages/ide/template.doc.mjs
index bd9d171097..58c29efae9 100644
--- a/packages/cli/assets/templates/pages/ide/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/ide/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'IDE',
displayName: 'IDE',
- description: 'Dense multi-pane workspace of resizable, collapsible regions: a hierarchy tree on one flank, tabbed documents in the middle, a docked drawer along the bottom, an inspector opposite. Drag a divider to resize or collapse any of them. Editor, IDE, workbench, terminal, or development environment.',
+ description:
+ 'Dense multi-pane workspace of resizable, collapsible regions: a hierarchy tree on one flank, tabbed documents in the middle, a docked drawer along the bottom, an inspector opposite. Drag a divider to resize or collapse any of them.',
+ keywords: [
+ 'editor',
+ 'ide',
+ 'workbench',
+ 'terminal',
+ 'development environment',
+ ],
isReady: true,
category: 'Tools - IDE',
};
diff --git a/packages/cli/assets/templates/pages/incident-console/template.doc.mjs b/packages/cli/assets/templates/pages/incident-console/template.doc.mjs
index 868d14fc75..dfa6762710 100644
--- a/packages/cli/assets/templates/pages/incident-console/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/incident-console/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Incident Console',
displayName: 'Incident Console',
- description: 'Dense row queue with an inspector: severity-coded rows grouped by status, a saved-search filter bar, a segmented status control, and a resizable detail pane for the selected row. Rows, not cards, sized for scanning volume. Incident, alert, on-call, outage, ticket, or triage console.',
+ description:
+ 'Dense row queue with an inspector: severity-coded rows grouped by status, a saved-search filter bar, a segmented status control, and a resizable detail pane for the selected row. Rows, not cards, sized for scanning volume.',
+ keywords: [
+ 'incident',
+ 'alert',
+ 'on-call',
+ 'outage',
+ 'ticket',
+ 'triage console',
+ ],
isReady: false,
category: 'Tools - Incident Console',
};
diff --git a/packages/cli/assets/templates/pages/kanban-board/template.doc.mjs b/packages/cli/assets/templates/pages/kanban-board/template.doc.mjs
index b4aacdbac1..2ea42925ca 100644
--- a/packages/cli/assets/templates/pages/kanban-board/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/kanban-board/template.doc.mjs
@@ -5,7 +5,17 @@ export const doc = {
type: 'page',
name: 'Kanban Board',
displayName: 'Kanban Board',
- description: 'Horizontal lanes of draggable cards where the column itself is the status, so drag and drop between lanes is the state change. Fixed columns, variable-height cards. Kanban, board, swimlane, sprint, backlog, tasks, or pipeline.',
+ description:
+ 'Horizontal lanes of draggable cards where the column itself is the status, so drag and drop between lanes is the state change. Fixed columns, variable-height cards.',
+ keywords: [
+ 'kanban',
+ 'board',
+ 'swimlane',
+ 'sprint',
+ 'backlog',
+ 'tasks',
+ 'pipeline',
+ ],
isReady: true,
category: 'Tools - Kanban Board',
};
diff --git a/packages/cli/assets/templates/pages/library/template.doc.mjs b/packages/cli/assets/templates/pages/library/template.doc.mjs
index 71435abfcd..27e11c98ac 100644
--- a/packages/cli/assets/templates/pages/library/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/library/template.doc.mjs
@@ -5,7 +5,21 @@ export const doc = {
type: 'page',
name: 'Card Grid',
displayName: 'Card Grid',
- description: 'Searchable, browsable card grid with filter tabs and a real empty state: uniform tiles organized by topic, narrowing in place, with no detail surface behind them. Catalog, index, directory, library, browse, or gallery of entries.',
+ description:
+ 'Searchable, browsable card grid with filter tabs and a real empty state: uniform tiles organized by topic, narrowing in place, with no detail surface behind them.',
+ keywords: [
+ 'catalog',
+ 'index',
+ 'directory',
+ 'library',
+ 'browse',
+ 'gallery of entries',
+ 'hub',
+ 'landing',
+ 'feed',
+ 'tags',
+ 'previews',
+ ],
isReady: true,
category: 'Content - Card Grid',
};
diff --git a/packages/cli/assets/templates/pages/login-card/template.doc.mjs b/packages/cli/assets/templates/pages/login-card/template.doc.mjs
index e127745f49..4f8fb15e50 100644
--- a/packages/cli/assets/templates/pages/login-card/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/login-card/template.doc.mjs
@@ -5,7 +5,17 @@ export const doc = {
type: 'page',
name: 'Login Card',
displayName: 'Login Card',
- description: 'Credential form inside an elevated centered card, third-party provider buttons separated from the fields by a divider, secondary sign-up and legal links beneath. Login, sign in, signin, authentication, credentials, social, or account access.',
+ description:
+ 'Credential form inside an elevated centered card, third-party provider buttons separated from the fields by a divider, secondary sign-up and legal links beneath.',
+ keywords: [
+ 'login',
+ 'sign in',
+ 'signin',
+ 'authentication',
+ 'credentials',
+ 'social',
+ 'account access',
+ ],
isReady: true,
category: 'Login - Card',
};
diff --git a/packages/cli/assets/templates/pages/login-split/template.doc.mjs b/packages/cli/assets/templates/pages/login-split/template.doc.mjs
index 10b0d47686..795cd25f46 100644
--- a/packages/cli/assets/templates/pages/login-split/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/login-split/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Login Split',
displayName: 'Login Split',
- description: 'Credential form filling one half of a two-pane split, full-bleed media holding the other. Same fields as the card variant, but the layout carries brand imagery. Login, sign in, signin, authentication, credentials, or account access.',
+ description:
+ 'Credential form filling one half of a two-pane split, full-bleed media holding the other. Same fields as the card variant, but the layout carries brand imagery.',
+ keywords: [
+ 'login',
+ 'sign in',
+ 'signin',
+ 'authentication',
+ 'credentials',
+ 'account access',
+ ],
isReady: true,
category: 'Login - Split',
};
diff --git a/packages/cli/assets/templates/pages/login-sso/template.doc.mjs b/packages/cli/assets/templates/pages/login-sso/template.doc.mjs
index be94a1a21b..afa4ad6a93 100644
--- a/packages/cli/assets/templates/pages/login-sso/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/login-sso/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Login SSO',
displayName: 'Login SSO',
- description: 'Progressive credential flow that branches on input: the email domain resolves an identity provider and redirects, with a password path as fallback. Two-stage rather than one form. Single sign-on, SSO, SAML, enterprise login, directory, or corporate authentication.',
+ description:
+ 'Progressive credential flow that branches on input: the email domain resolves an identity provider and redirects, with a password path as fallback. Two-stage rather than one form.',
+ keywords: [
+ 'single sign-on',
+ 'sso',
+ 'saml',
+ 'enterprise login',
+ 'directory',
+ 'corporate authentication',
+ ],
isReady: true,
category: 'Login - SSO',
};
diff --git a/packages/cli/assets/templates/pages/login/template.doc.mjs b/packages/cli/assets/templates/pages/login/template.doc.mjs
index 3c0d0ae624..875dfd060d 100644
--- a/packages/cli/assets/templates/pages/login/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/login/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Basic Login',
displayName: 'Basic Login',
- description: 'Minimal centered credential form on a plain ground: two fields and a submit, nothing competing for attention. The least-chrome entry surface. Login, sign in, signin, authentication, credentials, or account access.',
+ description:
+ 'Minimal centered credential form on a plain ground: two fields and a submit, nothing competing for attention. The least-chrome entry surface.',
+ keywords: [
+ 'login',
+ 'sign in',
+ 'signin',
+ 'authentication',
+ 'credentials',
+ 'account access',
+ ],
isReady: true,
isHiddenFromOverview: true,
category: 'Login - Basic',
diff --git a/packages/cli/assets/templates/pages/messaging-shell/template.doc.mjs b/packages/cli/assets/templates/pages/messaging-shell/template.doc.mjs
index 79b7e1e204..1461b2991b 100644
--- a/packages/cli/assets/templates/pages/messaging-shell/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/messaging-shell/template.doc.mjs
@@ -5,7 +5,17 @@ export const doc = {
type: 'page',
name: 'Messaging Shell',
displayName: 'Messaging Shell',
- description: 'Four-column nested navigation narrowing left to right (team workspace, channel list, message stream, thread panel) where each column scopes the next. Dense rows, zero cards. Team messaging, chat, channels, threads, inbox, direct message, or conversation workspace.',
+ description:
+ 'Four-column nested navigation narrowing left to right (team workspace, channel list, message stream, thread panel) where each column scopes the next. Dense rows, zero cards.',
+ keywords: [
+ 'team messaging',
+ 'chat',
+ 'channels',
+ 'threads',
+ 'inbox',
+ 'direct message',
+ 'conversation workspace',
+ ],
isReady: false,
category: 'Shell - Messaging',
};
diff --git a/packages/cli/assets/templates/pages/mixed-gallery/template.doc.mjs b/packages/cli/assets/templates/pages/mixed-gallery/template.doc.mjs
index 67bf44d5eb..2a52335e12 100644
--- a/packages/cli/assets/templates/pages/mixed-gallery/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/mixed-gallery/template.doc.mjs
@@ -4,7 +4,16 @@
export const doc = {
name: 'Mixed Gallery',
displayName: 'Mixed Gallery',
- description: 'Masonry grid of variable-height tiles that pack against each other instead of cropping to a shared ratio, captioned per tile. Irregular rhythm, unlike the uniform gallery. Photos, images, pictures, portfolio, masonry, or media wall.',
+ description:
+ 'Masonry grid of variable-height tiles that pack against each other instead of cropping to a shared ratio, captioned per tile. Irregular rhythm, unlike the uniform gallery.',
+ keywords: [
+ 'photos',
+ 'images',
+ 'pictures',
+ 'portfolio',
+ 'masonry',
+ 'media wall',
+ ],
type: 'page',
isReady: true,
category: 'Gallery - Mixed',
diff --git a/packages/cli/assets/templates/pages/payment-form/template.doc.mjs b/packages/cli/assets/templates/pages/payment-form/template.doc.mjs
index fd477ef412..17c9eb04d0 100644
--- a/packages/cli/assets/templates/pages/payment-form/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/payment-form/template.doc.mjs
@@ -5,7 +5,9 @@ export const doc = {
type: 'page',
name: 'Checkout Form',
displayName: 'Checkout Form',
- description: 'Long sectioned form running beside a summary that stays visible while the fields scroll and recalculates as they change, ending on a terminal confirm of the total. Sections run contact, address, delivery choice, then card details. Checkout, payment, billing, cart, buyer, or purchase.',
+ description:
+ 'Long sectioned form running beside a summary that stays visible while the fields scroll and recalculates as they change, ending on a terminal confirm of the total. Sections run contact, address, delivery choice, then card details.',
+ keywords: ['checkout', 'payment', 'billing', 'cart', 'buyer', 'purchase'],
isReady: true,
category: 'Form - Checkout',
};
diff --git a/packages/cli/assets/templates/pages/product-detail/template.doc.mjs b/packages/cli/assets/templates/pages/product-detail/template.doc.mjs
index 37f1d4f0ec..8fe28b68d1 100644
--- a/packages/cli/assets/templates/pages/product-detail/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/product-detail/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'Product Detail',
displayName: 'Product Detail',
- description: 'Single-item detail pairing a media gallery with a selection column: variant swatches, a quantity stepper, primary and secondary commit actions, and collapsible specification sections below. Product, listing, item, catalog entry, or storefront detail.',
+ description:
+ 'Single-item detail pairing a media gallery with a selection column: variant swatches, a quantity stepper, primary and secondary commit actions, and collapsible specification sections below.',
+ keywords: [
+ 'product',
+ 'listing',
+ 'item',
+ 'catalog entry',
+ 'storefront detail',
+ ],
isReady: true,
category: 'Content - Product Detail',
};
diff --git a/packages/cli/assets/templates/pages/product-gallery/template.doc.mjs b/packages/cli/assets/templates/pages/product-gallery/template.doc.mjs
index af5e2544e8..70299618b9 100644
--- a/packages/cli/assets/templates/pages/product-gallery/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/product-gallery/template.doc.mjs
@@ -4,7 +4,16 @@
export const doc = {
name: 'Product Gallery',
displayName: 'Product Gallery',
- description: 'Uniform card grid where every tile carries media, title, supporting line, and a price. Browse-to-select only, with no filtering and no detail surface. Products, catalog, storefront, shop, listings, or ecommerce grid.',
+ description:
+ 'Uniform card grid where every tile carries media, title, supporting line, and a price. Browse-to-select only, with no filtering and no detail surface.',
+ keywords: [
+ 'products',
+ 'catalog',
+ 'storefront',
+ 'shop',
+ 'listings',
+ 'ecommerce grid',
+ ],
type: 'page',
isReady: true,
category: 'Gallery - Product',
diff --git a/packages/cli/assets/templates/pages/settings-dialog/template.doc.mjs b/packages/cli/assets/templates/pages/settings-dialog/template.doc.mjs
index 670d1db17d..c4690f01a2 100644
--- a/packages/cli/assets/templates/pages/settings-dialog/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/settings-dialog/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'Settings Dialog',
displayName: 'Settings Dialog',
- description: 'Preferences inside a modal container with searchable section navigation, so configuration happens without leaving whatever is underneath. Grouped toggles, live preview of appearance choices, rebindable shortcuts. Settings, preferences, configuration, options, or modal dialog.',
+ description:
+ 'Preferences inside a modal container with searchable section navigation, so configuration happens without leaving whatever is underneath. Grouped toggles, live preview of appearance choices, rebindable shortcuts.',
+ keywords: [
+ 'settings',
+ 'preferences',
+ 'configuration',
+ 'options',
+ 'modal dialog',
+ ],
isReady: true,
category: 'Settings - Dialog',
};
diff --git a/packages/cli/assets/templates/pages/settings-sidebar/template.doc.mjs b/packages/cli/assets/templates/pages/settings-sidebar/template.doc.mjs
index 47a85aa2fd..a0d0829ddf 100644
--- a/packages/cli/assets/templates/pages/settings-sidebar/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/settings-sidebar/template.doc.mjs
@@ -5,7 +5,15 @@ export const doc = {
type: 'page',
name: 'Settings Panels',
displayName: 'Settings Panels',
- description: 'Preferences split into nav-switched panels: a persistent section list swaps the pane beside it, and rows edit in place rather than opening a separate form. Settings, preferences, configuration, options, or account panels.',
+ description:
+ 'Preferences split into nav-switched panels: a persistent section list swaps the pane beside it, and rows edit in place rather than opening a separate form.',
+ keywords: [
+ 'settings',
+ 'preferences',
+ 'configuration',
+ 'options',
+ 'account panels',
+ ],
isReady: true,
category: 'Settings - Panels',
};
diff --git a/packages/cli/assets/templates/pages/settings/template.doc.mjs b/packages/cli/assets/templates/pages/settings/template.doc.mjs
index a4cd3a92f2..0bfe436c87 100644
--- a/packages/cli/assets/templates/pages/settings/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/settings/template.doc.mjs
@@ -5,7 +5,9 @@ export const doc = {
type: 'page',
name: 'Settings Form',
displayName: 'Settings Form',
- description: 'Preferences as one continuously scrolling form, sections stacked in order with no navigation between them. The simplest settings shape: everything reachable by scrolling. Settings, preferences, configuration, options, or account.',
+ description:
+ 'Preferences as one continuously scrolling form, sections stacked in order with no navigation between them. The simplest settings shape: everything reachable by scrolling.',
+ keywords: ['settings', 'preferences', 'configuration', 'options', 'account'],
isReady: true,
category: 'Settings - Form',
};
diff --git a/packages/cli/assets/templates/pages/shell-nav/template.doc.mjs b/packages/cli/assets/templates/pages/shell-nav/template.doc.mjs
index 56e6c72d15..5531e064d9 100644
--- a/packages/cli/assets/templates/pages/shell-nav/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/shell-nav/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Shell Nav',
displayName: 'Shell Nav',
- description: 'Application frame combining both navigation axes: a top menu bar with command-palette search over a resizable hierarchy rail, wrapping placeholder content. For when one axis is not enough. Shell, chrome, layout frame, navigation, sidebar, or menu bar.',
+ description:
+ 'Application frame combining both navigation axes: a top menu bar with command-palette search over a resizable hierarchy rail, wrapping placeholder content. For when one axis is not enough.',
+ keywords: [
+ 'shell',
+ 'chrome',
+ 'layout frame',
+ 'navigation',
+ 'sidebar',
+ 'menu bar',
+ ],
isReady: true,
category: 'Shell - Top Nav + Left Sidebar',
};
diff --git a/packages/cli/assets/templates/pages/shell-side-nav/template.doc.mjs b/packages/cli/assets/templates/pages/shell-side-nav/template.doc.mjs
index ec6860baaa..3909330c42 100644
--- a/packages/cli/assets/templates/pages/shell-side-nav/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/shell-side-nav/template.doc.mjs
@@ -5,7 +5,20 @@ export const doc = {
type: 'page',
name: 'Side Nav',
displayName: 'Side Nav',
- description: 'Application frame with a single collapsible, resizable left rail carrying grouped history and search, wrapping the main content. Vertical navigation only, no top bar. Shell, chrome, layout frame, sidebar, drawer, left rail, or navigation.',
+ description:
+ 'Application frame with a single collapsible, resizable left rail carrying grouped history and search, wrapping the main content. Vertical navigation only, no top bar.',
+ keywords: [
+ 'shell',
+ 'chrome',
+ 'layout frame',
+ 'sidebar',
+ 'drawer',
+ 'left rail',
+ 'navigation',
+ 'desktop app',
+ 'directory',
+ 'workspace',
+ ],
isReady: true,
category: 'Shell - Left Sidebar',
};
diff --git a/packages/cli/assets/templates/pages/shell-top-nav/template.doc.mjs b/packages/cli/assets/templates/pages/shell-top-nav/template.doc.mjs
index ba01e035a2..198de5af90 100644
--- a/packages/cli/assets/templates/pages/shell-top-nav/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/shell-top-nav/template.doc.mjs
@@ -5,7 +5,17 @@ export const doc = {
type: 'page',
name: 'Top Nav',
displayName: 'Top Nav',
- description: 'Application frame with horizontal navigation only: a centered bar whose items open full-width mega-menu panels, over placeholder content that keeps the entire width. Shell, chrome, layout frame, header, menu, topbar, or navigation.',
+ description:
+ 'Application frame with horizontal navigation only: a centered bar whose items open full-width mega-menu panels, over placeholder content that keeps the entire width.',
+ keywords: [
+ 'shell',
+ 'chrome',
+ 'layout frame',
+ 'header',
+ 'menu',
+ 'topbar',
+ 'navigation',
+ ],
isReady: true,
category: 'Shell - Top Nav',
};
diff --git a/packages/cli/assets/templates/pages/side-gallery/template.doc.mjs b/packages/cli/assets/templates/pages/side-gallery/template.doc.mjs
index 4d827ffef6..44dd78e56f 100644
--- a/packages/cli/assets/templates/pages/side-gallery/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/side-gallery/template.doc.mjs
@@ -4,7 +4,9 @@
export const doc = {
name: 'Side Gallery',
displayName: 'Side Gallery',
- description: 'Asymmetric split section: a copy column of headline, supporting text, and links held against a clustered image collage opposite. Deliberately off-balance, unlike the centered hero. Feature banner, split section, marketing, or gallery intro.',
+ description:
+ 'Asymmetric split section: a copy column of headline, supporting text, and links held against a clustered image collage opposite. Deliberately off-balance, unlike the centered hero.',
+ keywords: ['feature banner', 'split section', 'marketing', 'gallery intro'],
type: 'page',
isReady: true,
category: 'Gallery - Side',
diff --git a/packages/cli/assets/templates/pages/table-filter/template.doc.mjs b/packages/cli/assets/templates/pages/table-filter/template.doc.mjs
index ecb546654c..6ee2022887 100644
--- a/packages/cli/assets/templates/pages/table-filter/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table-filter/template.doc.mjs
@@ -5,7 +5,27 @@ export const doc = {
type: 'page',
name: 'Filterable Table',
displayName: 'Filterable Table',
- description: 'Flat row collection built around progressive filtering: a token bar that escalates into full query syntax, saved views that persist a filter set, column and grouping options, and a resizable detail pane. Table, list, rows, records, grid, search, or filtered dataset.',
+ description:
+ 'Flat row collection built around progressive filtering: a token bar that escalates into full query syntax, saved views that persist a filter set, column and grouping options, and a resizable detail pane.',
+ keywords: [
+ 'table',
+ 'list',
+ 'rows',
+ 'records',
+ 'grid',
+ 'search',
+ 'filtered dataset',
+ 'searchable list',
+ 'filters',
+ 'faceted search',
+ 'advanced search',
+ 'results list',
+ 'explorer',
+ 'bulk actions',
+ 'badges',
+ 'detail drawer',
+ 'csv export',
+ ],
isReady: true,
category: 'Table - Filtering',
};
diff --git a/packages/cli/assets/templates/pages/table-grouped/template.doc.mjs b/packages/cli/assets/templates/pages/table-grouped/template.doc.mjs
index ff90a700e1..4564e9ce8b 100644
--- a/packages/cli/assets/templates/pages/table-grouped/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table-grouped/template.doc.mjs
@@ -5,7 +5,21 @@ export const doc = {
type: 'page',
name: 'Grouped Table',
displayName: 'Grouped Table',
- description: 'Row collection bundled into collapsible sections with per-group counts, so a long list reads as a handful of blocks that expand and collapse. Query filtering and a resizable inspector for the selected row. Table, list, rows, records, grid, or grouped dataset.',
+ description:
+ 'Row collection bundled into collapsible sections with per-group counts, so a long list reads as a handful of blocks that expand and collapse. Query filtering and a resizable inspector for the selected row.',
+ keywords: [
+ 'table',
+ 'list',
+ 'rows',
+ 'records',
+ 'grid',
+ 'grouped dataset',
+ 'to-do list',
+ 'todo',
+ 'priorities',
+ 'completed items',
+ 'checkboxes',
+ ],
isReady: true,
category: 'Table - Grouped',
};
diff --git a/packages/cli/assets/templates/pages/table-inbox/template.doc.mjs b/packages/cli/assets/templates/pages/table-inbox/template.doc.mjs
index a15dc2f211..c5e3eb1030 100644
--- a/packages/cli/assets/templates/pages/table-inbox/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table-inbox/template.doc.mjs
@@ -6,12 +6,24 @@ export const doc = {
name: 'Inbox Table',
displayName: 'Inbox Table',
description:
- 'Two-pane message queue: the table indexes a reading pane rather than ' +
- 'being the destination, with a divider you drag to resize. Rows stack ' +
- 'when the table narrows, not the window; threads read as collapsible ' +
- 'messages; replying opens a composer that leaves the list live. Inbox, ' +
- 'mail, email, conversations, thread, triage, reading pane, split pane, ' +
- 'resize, collapse, compose, or notifications.',
+ 'Two-pane message queue: the table indexes a reading pane rather than being the destination, with a divider you drag to resize. Rows stack when the table narrows, not the window; threads read as collapsible messages; replying opens a composer that leaves the list live.',
+ keywords: [
+ 'inbox',
+ 'mail',
+ 'email',
+ 'conversations',
+ 'thread',
+ 'triage',
+ 'reading pane',
+ 'split pane',
+ 'resize',
+ 'collapse',
+ 'compose',
+ 'notifications',
+ 'review queue',
+ 'approvals',
+ 'decisions',
+ ],
isReady: true,
category: 'Table - Split Pane',
};
diff --git a/packages/cli/assets/templates/pages/table-page/template.doc.mjs b/packages/cli/assets/templates/pages/table-page/template.doc.mjs
index 2a5c46dcf0..5f077a8a6a 100644
--- a/packages/cli/assets/templates/pages/table-page/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table-page/template.doc.mjs
@@ -6,7 +6,26 @@ export const doc = {
name: 'Searchable Table',
displayName: 'Searchable Table',
description:
- 'Flat table of uniform rows under a block of record-level facts, narrowed three ways at once — a full-text search box, a scope toggle, and per-column popovers — with sortable and filterable columns, per-row hover detail, and totals derived from the visible rows that flag themselves as partial while a filter is on. The shape for one homogeneous list, not nested rows or groups with their own columns. Search, filter, sort, table, data table, flat rows, records, dataset, or totals.',
+ 'Flat table of uniform rows under a block of record-level facts, narrowed three ways at once — a full-text search box, a scope toggle, and per-column popovers — with sortable and filterable columns, per-row hover detail, and totals derived from the visible rows that flag themselves as partial while a filter is on. The shape for one homogeneous list, not nested rows or groups with their own columns.',
+ keywords: [
+ 'search',
+ 'filter',
+ 'sort',
+ 'table',
+ 'flat rows',
+ 'records',
+ 'dataset',
+ 'totals',
+ 'roster',
+ 'inventory',
+ 'assets',
+ 'registry',
+ 'lookup',
+ 'report table',
+ 'numeric columns',
+ 'pagination',
+ 'csv export',
+ ],
isReady: true,
category: 'Table - Basic',
};
diff --git a/packages/cli/assets/templates/pages/table-tree/template.doc.mjs b/packages/cli/assets/templates/pages/table-tree/template.doc.mjs
index c95ee214db..62e3cd18c6 100644
--- a/packages/cli/assets/templates/pages/table-tree/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table-tree/template.doc.mjs
@@ -6,7 +6,20 @@ export const doc = {
name: 'Tree Table',
displayName: 'Tree Table',
description:
- 'Hierarchical table where every parent row rolls up from its children — a code repository whose folders show the newest commit beneath them, beside a detail sidebar and a rendered README. Columns resize, siblings sort within their own level, arrow keys walk the rows, and search prunes the tree to matching branches. Tree, hierarchy, nested rows, drilldown, expand, collapse, resizable, expandable, file browser, repository, rolled-up parents.',
+ 'Hierarchical table where every parent row rolls up from its children — a code repository whose folders show the newest commit beneath them, beside a detail sidebar and a rendered README. Columns resize, siblings sort within their own level, arrow keys walk the rows, and search prunes the tree to matching branches.',
+ keywords: [
+ 'tree',
+ 'hierarchy',
+ 'nested rows',
+ 'drilldown',
+ 'expand',
+ 'collapse',
+ 'resizable',
+ 'expandable',
+ 'file browser',
+ 'repository',
+ 'rolled-up parents',
+ ],
isReady: true,
category: 'Table - Tree/Hierarchical List',
};
diff --git a/packages/cli/assets/templates/pages/table/template.doc.mjs b/packages/cli/assets/templates/pages/table/template.doc.mjs
index 33c05b9f79..bab5793ad2 100644
--- a/packages/cli/assets/templates/pages/table/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/table/template.doc.mjs
@@ -5,7 +5,17 @@ export const doc = {
type: 'page',
name: 'Simple Table',
displayName: 'Simple Table',
- description: 'Flat row collection where columns sort, rows select into a bulk-action toolbar, and each row carries an overflow menu. Sortable but ungrouped, with no detail pane, the baseline shape. Table, list, rows, records, grid, spreadsheet, or roster.',
+ description:
+ 'Flat row collection where columns sort, rows select into a bulk-action toolbar, and each row carries an overflow menu. Sortable but ungrouped, with no detail pane, the baseline shape.',
+ keywords: [
+ 'table',
+ 'list',
+ 'rows',
+ 'records',
+ 'grid',
+ 'spreadsheet',
+ 'roster',
+ ],
isReady: false,
category: 'Table - Basic',
isHiddenFromOverview: true,
diff --git a/packages/cli/assets/templates/pages/theme-showcase/template.doc.mjs b/packages/cli/assets/templates/pages/theme-showcase/template.doc.mjs
index 3a799484b6..90a799befb 100644
--- a/packages/cli/assets/templates/pages/theme-showcase/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/theme-showcase/template.doc.mjs
@@ -5,7 +5,16 @@ export const doc = {
type: 'page',
name: 'Theme Showcase',
displayName: 'Theme Showcase',
- description: 'Several unrelated product surfaces rendered together on one canvas so a token change can be judged across contexts at once. A comparison harness rather than a layout to ship. Theme, tokens, palette, typography, styling, or design system preview.',
+ description:
+ 'Several unrelated product surfaces rendered together on one canvas so a token change can be judged across contexts at once. A comparison harness rather than a layout to ship.',
+ keywords: [
+ 'theme',
+ 'tokens',
+ 'palette',
+ 'typography',
+ 'styling',
+ 'design system preview',
+ ],
isReady: true,
// Surfaced via the Themes page "Open in Playground" action, not the
// Templates gallery, so keep it out of the overview + playground menu.
diff --git a/packages/cli/assets/templates/pages/work-item-detail/template.doc.mjs b/packages/cli/assets/templates/pages/work-item-detail/template.doc.mjs
index ad2a969c58..c86cb50975 100644
--- a/packages/cli/assets/templates/pages/work-item-detail/template.doc.mjs
+++ b/packages/cli/assets/templates/pages/work-item-detail/template.doc.mjs
@@ -7,6 +7,16 @@ export const doc = {
displayName: 'Work Item Detail',
description:
'Single work-item detail in two columns: a title with a status selector, a description, a subtask checklist with progress, an attachments block, and a comment and activity feed in the main column, plus a property rail with assignee, dates, labels, and linked items. The shape for any tracked item with children, properties, and a comment history — a task, ticket, issue, story, bug, card, request, or work item.',
+ keywords: [
+ 'task',
+ 'ticket',
+ 'issue',
+ 'story',
+ 'bug',
+ 'card',
+ 'request',
+ 'work item',
+ ],
isReady: true,
category: 'Content - Work Item Detail',
};
diff --git a/packages/cli/authoring/doctypes/template/parse.mjs b/packages/cli/authoring/doctypes/template/parse.mjs
index fe8aa6ca90..dcd8cbe772 100644
--- a/packages/cli/authoring/doctypes/template/parse.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.mjs
@@ -44,6 +44,7 @@ const baseTemplateFields = {
name: z.string().min(1, 'name is required'),
displayName: z.string().min(1).optional(),
description: z.string().min(1, 'description is required').optional(),
+ keywords: z.array(z.string().min(1)).optional(),
category: z.string().optional(),
componentsUsed: z.array(z.string()).optional(),
preview: previewSchema.optional(),
diff --git a/packages/cli/authoring/doctypes/template/parse.test.mjs b/packages/cli/authoring/doctypes/template/parse.test.mjs
index 80ea25acc6..9ed0f31a2e 100644
--- a/packages/cli/authoring/doctypes/template/parse.test.mjs
+++ b/packages/cli/authoring/doctypes/template/parse.test.mjs
@@ -34,6 +34,27 @@ describe('parseTemplate (load boundary)', () => {
}
});
+ it('accepts keywords on page and block templates', () => {
+ for (const type of ['page', 'block']) {
+ const parsed = parseTemplate({
+ type,
+ name: 'Acme health',
+ description: 'Status tiles over time charts.',
+ keywords: ['uptime', 'on-call'],
+ });
+ expect(parsed.keywords).toEqual(['uptime', 'on-call']);
+ }
+ });
+
+ it('rejects keywords that are not a list of words', () => {
+ expect(
+ reason({type: 'page', name: 'Acme health', keywords: 'uptime'}),
+ ).toMatch(/keywords/);
+ expect(reason({type: 'page', name: 'Acme health', keywords: ['']})).toMatch(
+ /keywords/,
+ );
+ });
+
it('rejects an empty replaces', () => {
expect(reason({type: 'page', name: 'Acme shell', replaces: ''})).toMatch(
/replaces must name a Core template id/,
diff --git a/packages/cli/authoring/doctypes/template/template.doc.mjs b/packages/cli/authoring/doctypes/template/template.doc.mjs
index e679e1831f..33016a198b 100644
--- a/packages/cli/authoring/doctypes/template/template.doc.mjs
+++ b/packages/cli/authoring/doctypes/template/template.doc.mjs
@@ -52,6 +52,12 @@ export const doc = {
type: 'string',
description: 'One-sentence description of what the template provides.',
},
+ {
+ name: 'keywords',
+ type: 'string[]',
+ description:
+ "Search keywords for CLI discovery: the ideas, domains, and other names a builder might use for what the template serves (e.g. ['monitoring', 'uptime', 'on-call'] for a service-health dashboard). Lowercase. `astryx search` matches them as it matches the description and `astryx build` ranks page templates on them, so keep them out of `description`. Integration templates need @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
+ },
{
name: 'replaces',
type: 'string',
diff --git a/packages/cli/authoring/doctypes/template/type.ts b/packages/cli/authoring/doctypes/template/type.ts
index 1b2723d3f6..5ab09a4d7e 100644
--- a/packages/cli/authoring/doctypes/template/type.ts
+++ b/packages/cli/authoring/doctypes/template/type.ts
@@ -26,6 +26,16 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
/** One-sentence description of what the template provides. */
description?: string;
+ /** Search keywords for CLI discovery: the ideas, domains, and other names a
+ * builder might use for what this template serves (e.g. `['monitoring',
+ * 'uptime', 'on-call']` for a service-health dashboard). Lowercase.
+ * `astryx search` matches them as it matches the description, and
+ * `astryx build` ranks page templates on them, so the `description` can
+ * stay a description of the layout. Integration templates need
+ * `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field, drop
+ * that template, and hide the package's doc topics. */
+ keywords?: string[];
+
/** Optional stable slug override and prior aliases for registry output. */
registry?: RegistryDocIdentity;
diff --git a/packages/cli/foundation/discovery/template-adapter.mjs b/packages/cli/foundation/discovery/template-adapter.mjs
index 7762752c8a..63cf5b858a 100644
--- a/packages/cli/foundation/discovery/template-adapter.mjs
+++ b/packages/cli/foundation/discovery/template-adapter.mjs
@@ -102,6 +102,7 @@ export function effectiveTemplateDiscovery(templates) {
* @property {string} name
* @property {string} [displayName]
* @property {string} description
+ * @property {string[]} [keywords]
* @property {string} [category]
* @property {boolean} [isReady]
* @property {boolean} [scaffold]
@@ -633,6 +634,7 @@ async function discoverPages() {
name: doc?.name || dir.name,
description: doc?.description || '',
category: doc?.category || '',
+ keywords: doc?.keywords ?? [],
isReady: doc?.isReady ?? true,
scaffold: doc?.scaffold ?? false,
filePath: path.join(dirPath, 'page.tsx'),
@@ -661,6 +663,7 @@ async function discoverBlocks() {
dirName: basename,
name: doc?.name || basename,
description: doc?.description || '',
+ keywords: doc?.keywords ?? [],
isReady: doc?.isReady ?? true,
aspectRatio: doc?.aspectRatio ?? 1,
componentsUsed: doc?.componentsUsed ?? [],
@@ -702,6 +705,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
dirName: basename,
name: doc?.name || basename,
description: doc?.description || '',
+ keywords: doc?.keywords ?? [],
isReady: doc?.isReady ?? true,
aspectRatio: doc?.aspectRatio ?? 1,
componentsUsed: doc?.componentsUsed ?? [],
@@ -1269,6 +1273,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
name: doc?.name || id,
displayName: doc?.displayName,
description: doc?.description || '',
+ keywords: doc?.keywords ?? [],
category: doc?.category || '',
isReady: doc?.isReady ?? true,
scaffold: doc?.scaffold ?? false,
diff --git a/packages/cli/foundation/integrations/cli-requirement.mjs b/packages/cli/foundation/integrations/cli-requirement.mjs
index 90370b927d..bb56d88b3f 100644
--- a/packages/cli/foundation/integrations/cli-requirement.mjs
+++ b/packages/cli/foundation/integrations/cli-requirement.mjs
@@ -19,10 +19,10 @@ export const CLI_PACKAGE = '@astryxdesign/cli';
/**
* The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide ships,
- * with no warning; and it rejects `replaces`, drops that template, and hides
- * the package's doc topics.
+ * and placed guides) and its templates' `replaces` and `keywords`. A release
+ * before it can hide every doc topic a package with a namespace doc or a
+ * placed guide ships, with no warning; and it rejects `replaces` or
+ * `keywords`, drops that template, and hides the package's doc topics.
*/
export const DOCS_TREE_CLI = '0.7.0';
@@ -197,6 +197,23 @@ export function themesCliProblem(pkg) {
);
}
+/**
+ * Why a package with a template that sets `keywords` would lose that template
+ * and its doc topics on an older CLI, or null when its declared CLI range
+ * admits only CLIs that read the field. Published 0.6.3 rejects the field,
+ * drops that template, and hides the package's doc topics.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function keywordsCliProblem(pkg) {
+ return cliRangeProblem(
+ pkg,
+ 'has a template that sets `keywords`',
+ "rejects the field, drops that template, and hides the package's doc topics",
+ DOCS_TREE_CLI,
+ );
+}
+
/**
* The package.json with a CLI peer of `>=floor`: optional, unless the package
* already says otherwise. Call it only when the package's range admits a CLI
diff --git a/packages/cli/foundation/integrations/cli-requirement.test.mjs b/packages/cli/foundation/integrations/cli-requirement.test.mjs
index 38b4307bb6..8900d75709 100644
--- a/packages/cli/foundation/integrations/cli-requirement.test.mjs
+++ b/packages/cli/foundation/integrations/cli-requirement.test.mjs
@@ -10,6 +10,7 @@ import {
THEMES_CLI,
lowestAdmitted,
docsTreeCliProblem,
+ keywordsCliProblem,
replacesCliProblem,
sectionIdsCliProblem,
themesCliProblem,
@@ -117,7 +118,7 @@ describe('themesCliProblem and sectionIdsCliProblem', () => {
}
});
- it('keeps 0.7.0 for the docs tree and for replaces', () => {
+ it('keeps 0.7.0 for the docs tree, replaces, and keywords', () => {
const pkg = {peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}};
expect(docsTreeCliProblem(pkg)).toContain(
'admits a stable CLI before 0.7.0',
@@ -125,6 +126,12 @@ describe('themesCliProblem and sectionIdsCliProblem', () => {
expect(replacesCliProblem(pkg)).toContain(
'admits a stable CLI before 0.7.0',
);
+ expect(keywordsCliProblem(pkg)).toContain(
+ 'admits a stable CLI before 0.7.0',
+ );
+ expect(
+ keywordsCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
+ ).toBeNull();
});
it('names a released CLI for a feature that already shipped', () => {