Skip to content

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

TypeScript

docs(cli): make the integration guides and Authoring Reference match the CLI (#7263)

Joeye4bdd70269e6
diff --git a/.changeset/integration-guides-cleanup.md b/.changeset/integration-guides-cleanup.md
new file mode 100644
index 0000000000..8f173546c9
--- /dev/null
+++ b/.changeset/integration-guides-cleanup.md
@@ -0,0 +1,14 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] The `astryx docs cli/integrations` guides and `astryx docs authoring` now match the current CLI, and the guides point to the matching `astryx docs authoring <section>` for every field instead of repeating its tables.
+
+@josephfarina
+
+- Old-CLI notes name the published releases that behave that way: template `replaces`, links, docs sections, section `id`s and typed theme descriptors work from 0.6.4, and template `keywords` from 0.6.6. `integration verify` still names the CLI range to declare.
+- The quick start makes the package an ES module, so a theme it builds can be imported.
+- Samples and output that had drifted are fixed, among them the subcomponent imports, a theme that extends another, and the upgrade output.
+- The Authoring Reference corrects how an invalid `astryx.config` is handled, the `issuesUrl` format, where codemod files go, and which fields nothing reads yet. Its examples use the `export default {type: ...}` form that `integration add` writes.
+- `astryx docs cli/integrations` links to the Authoring Reference, and the reference links back to the guides.
+- `astryx docs styling-overview` and `tokens-and-setup` give the real symptom of a missing StyleX compiler: importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime`.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 81b0e5be31..7d9ee80cf1 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -581,12 +581,12 @@ There is no factory: write a plain object. For editor autocomplete and
type-checking, annotate it with the `AstryxConfig` type exported from
`@astryxdesign/cli/authoring`.
-| Field | Type | Purpose |
-| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `integrations` | `string[]` | Integration package names to load (see [Integrations](#integrations)). |
-| `issuesUrl` | `string` | Where "report an issue" links point for your project. Defaults to the core issue tracker. |
-| `hooks.postCodemod` | `PostCodemodHook[]` | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat). |
-| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
+| Field | Type | Purpose |
+| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `integrations` | `string[]` | Integration package names to load (see [Integrations](#integrations)). |
+| `issuesUrl` | `string` | Where "report an issue" links point for your project. Defaults to the core issue tracker. |
+| `hooks.postCodemod` | `PostCodemodHook[]` | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat). |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it. |
The config is validated against a strict schema when the CLI loads it, so an
unknown field is a hard error rather than a silent no-op. `astryx doctor`
diff --git a/packages/cli/assets/docs/styling-overview.doc.mjs b/packages/cli/assets/docs/styling-overview.doc.mjs
index 72cde2c32d..5341d5900c 100644
--- a/packages/cli/assets/docs/styling-overview.doc.mjs
+++ b/packages/cli/assets/docs/styling-overview.doc.mjs
@@ -158,7 +158,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.',
+ text: "If importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime` and the page does not render, the app is missing a StyleX compiler. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.",
},
],
},
diff --git a/packages/cli/assets/docs/tree/add-a-component.doc.mjs b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
index 6aa374cb8a..936d4a483b 100644
--- a/packages/cli/assets/docs/tree/add-a-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/add-a-component`: choose a
+ * @file `astryx docs cli/integrations/building-blocks/components/add-a-component`: choose a
* component name and generate its first source and doc files.
*/
diff --git a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
index b4c4c0e0cf..dbbeefe66c 100644
--- a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
@@ -44,7 +44,7 @@ Declare theme root ./themes in astryx.integration.mjs.
},
{
type: 'prose',
- text: "`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source. `oceanTheme.doc.mjs` describes it with `type: 'theme'`, `name`, `displayName`, `description`, and `maintained`; `theme list` shows its `name`, `description`, and `maintained`. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every descriptor field is in {@link generic:authoring}.",
+ text: '`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source, and `oceanTheme.doc.mjs` is the descriptor that `theme list` reads. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every field is in {@link schema:theme-doc}.',
},
{
type: 'prose',
diff --git a/packages/cli/assets/docs/tree/add-a-topic.doc.mjs b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
index b7342f2e9d..23c7c492d4 100644
--- a/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/add-a-topic`: add a doc topic to an
- * integration package, write its sections, and pick the doc kind for each
- * thing the package ships.
+ * @file `astryx docs cli/integrations/building-blocks/docs/add-a-topic`: add a
+ * doc topic to an integration package, write its sections, and pick the doc
+ * kind for each thing the package ships.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -40,7 +40,7 @@ export const docs = {
items: [
'Name the topic in lowercase kebab-case, such as `deploying`. Readers type the name as a command argument, so it holds only letters, digits, `_`, and `-`.',
'Keep the name stable: readers and links find the topic by it.',
- 'Pick a name no Core topic uses. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
+ 'Pick a name that `astryx docs` does not already list: no Core topic, and no section such as `tokens` or `layout`. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
],
},
],
@@ -59,13 +59,16 @@ export const docs = {
label: 'docs/deploying.doc.mjs',
code: "/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n sections: [{\n id: 'build-before-you-ship',\n title: 'Build before you ship',\n content: [\n {type: 'prose', text: 'Build the app, then upload the `dist` folder.'},\n {type: 'code', lang: 'bash', code: 'npm run build'},\n {type: 'list', style: 'unordered', items: ['Keep `dist` out of git.']},\n {type: 'table', headers: ['Variable', 'Value'], rows: [['`NODE_ENV`', '`production`']]},\n ],\n }],\n};",
},
+ {
+ type: 'prose',
+ text: 'The sample sets a section `id`, so `package.json` needs the CLI peer `"@astryxdesign/cli": ">=0.6.4"`. Published 0.6.3 and earlier reject `id` and hide every doc topic your package ships, and `integration verify` fails without that peer; see {@link generic:versioning}.',
+ },
{
type: 'list',
style: 'unordered',
items: [
- 'Content blocks are `prose`, `code`, `list`, and `table`, as shown; `heading`, with a `level` from 3 to 6 and a `text`; and `token-ref`, which inlines a token table from another topic.',
- '`id` is optional: a stable key for the section. Without it, the key comes from the title. A stable CLI before 0.6.4 cannot read `id`; see {@link generic:versioning}.',
- 'Replace the `Overview` placeholder that `integration add` writes. Every field is in {@link generic:authoring}.',
+ 'Replace the `Overview` placeholder that `integration add` writes.',
+ 'Every field is in {@link schema:reference-doc}.',
],
},
],
diff --git a/packages/cli/assets/docs/tree/agent-guidance.doc.mjs b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
index 58186b60e6..32cc603a36 100644
--- a/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
+++ b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/agent-guidance`: add short lines of
+ * @file `astryx docs cli/integrations/building-blocks/configuration/agent-guidance`: add short lines of
* guidance that apps put in front of their AI agents, within the limits.
*/
@@ -121,7 +121,7 @@ export default {
lang: 'bash',
code: `npx astryx init --features agents
# Or: --from takes the Core version the app had before
-npx astryx upgrade --from 0.7.0 --apply`,
+npx astryx upgrade --from <version> --apply`,
},
{
type: 'code',
diff --git a/packages/cli/assets/docs/tree/block-template.doc.mjs b/packages/cli/assets/docs/tree/block-template.doc.mjs
index a8d660f89c..33940eb0eb 100644
--- a/packages/cli/assets/docs/tree/block-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/block-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/document-the-template/block-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/block-template`:
* the block-only fields: component relationships and the preview shape.
*/
@@ -54,18 +54,8 @@ export default {
title: 'Choose the component relationship',
content: [
{
- type: 'reference',
- target: 'schema:template-doc',
- projection: {
- fields: [
- 'exampleFor',
- 'alsoExampleFor',
- 'alsoShowcaseFor',
- 'componentsUsed',
- 'isShowcase',
- ],
- },
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:template-doc}.',
},
{
type: 'prose',
@@ -101,14 +91,12 @@ export default {
title: 'Choose a useful preview',
content: [
{
- type: 'reference',
- target: 'schema:template-doc',
- projection: {fields: ['aspectRatio']},
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:template-doc}.',
},
{
type: 'prose',
- text: 'Start from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
+ text: 'Set `aspectRatio` from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
},
{
type: 'table',
diff --git a/packages/cli/assets/docs/tree/build-the-template.doc.mjs b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
index bbf5057928..9adc96e4b0 100644
--- a/packages/cli/assets/docs/tree/build-the-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template`:
* author portable template source and every asset that source needs.
*/
diff --git a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
index 9ecb21fd30..12214adbd6 100644
--- a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
+++ b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/check-your-docs`: what each check
- * proves about an integration's docs: the docs check, each doc's fields, the
- * read size, and the CLI peer.
+ * @file `astryx docs cli/integrations/building-blocks/docs/check-your-docs`:
+ * what each check proves about an integration's docs: the docs check, each
+ * doc's fields, the read size, and the CLI peer.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -46,7 +46,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'A doc that does not load, an accidental Core overlap, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
+ text: 'A doc that does not load, an accidental Core overlap, a `reference` block that names no doc, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
},
{
type: 'table',
@@ -67,6 +67,11 @@ export const docs = {
'`[fail]` `invalid_doc_graph`',
'1',
],
+ [
+ 'A `reference` block whose target names no doc',
+ '`[fail]` `invalid_doc_reference`',
+ '1',
+ ],
['A link that names no doc', '`[warn]` `invalid_doc_graph`', '0'],
[
'A topic that sets `replaces` or `extends`',
diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjs
index fef38d55c9..0922e84b3d 100644
--- a/packages/cli/assets/docs/tree/checks.doc.mjs
+++ b/packages/cli/assets/docs/tree/checks.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/checks`: what each package check
+ * @file `astryx docs cli/integrations/ship/checks`: what each package check
* proves, what fails and what only warns, and one command to run them all.
*/
@@ -120,7 +120,7 @@ export const docs = {
},
{
type: 'prose',
- text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+ text: '`integration pack --check`, the name this check had before published 0.6.5, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/codemods.doc.mjs b/packages/cli/assets/docs/tree/codemods.doc.mjs
index dffd123d1d..17db365f86 100644
--- a/packages/cli/assets/docs/tree/codemods.doc.mjs
+++ b/packages/cli/assets/docs/tree/codemods.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
* integration package, and know which of them `astryx upgrade` runs in an app.
*/
@@ -82,7 +82,7 @@ export default {
},
{
type: 'prose',
- text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+ text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link schema:codemod}.",
},
],
},
@@ -124,14 +124,14 @@ npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
type: 'code',
lang: 'text',
code: `Integrations: @acme/astryx-widgets
-1 codemod to run (dry run)
+<n> codemods to run (dry run)
Applying integration codemods...
Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
! ~ src/Hero.tsx (would change)`,
},
{
type: 'prose',
- text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+ text: "`<n>` counts Core's codemods for the same versions too: they run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
},
{
type: 'prose',
diff --git a/packages/cli/assets/docs/tree/component-family.doc.mjs b/packages/cli/assets/docs/tree/component-family.doc.mjs
index dee4f1fb97..440fce1832 100644
--- a/packages/cli/assets/docs/tree/component-family.doc.mjs
+++ b/packages/cli/assets/docs/tree/component-family.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
* author one ComponentDoc for several public exports in a component family.
*/
@@ -38,10 +38,8 @@ export const docs = {
],
},
{
- type: 'reference',
- target: 'schema:component-doc',
- projection: {fields: ['components']},
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:component-doc}.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/component-imports.doc.mjs b/packages/cli/assets/docs/tree/component-imports.doc.mjs
index 2afd5dad40..4cdb621ac9 100644
--- a/packages/cli/assets/docs/tree/component-imports.doc.mjs
+++ b/packages/cli/assets/docs/tree/component-imports.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
* integration component's documented import resolve from the packed package.
*/
@@ -51,7 +51,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+ text: '`integration verify` unpacks the packed package into a temporary app, resolves each documented import, and checks that the module exports the documented component name. Its `--json` output names each failure by code.',
},
{
type: 'code',
diff --git a/packages/cli/assets/docs/tree/components.doc.mjs b/packages/cli/assets/docs/tree/components.doc.mjs
index 9e9bab4003..553bc493ca 100644
--- a/packages/cli/assets/docs/tree/components.doc.mjs
+++ b/packages/cli/assets/docs/tree/components.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components`: guides for adding and
+ * @file `astryx docs cli/integrations/building-blocks/components`: guides for adding and
* documenting components in an integration package.
*/
diff --git a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
index 71ef4740d5..fc1c010ac1 100644
--- a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
+++ b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/debug-and-gap-reports`: receive a record
+ * @file `astryx docs cli/integrations/building-blocks/configuration/debug-and-gap-reports`: receive a record
* of each CLI run with `debug`, and handle `astryx gap-report` with
* `gapReport`, both named exports of the integration manifest.
*/
@@ -44,7 +44,7 @@ export default {
},
{
type: 'prose',
- text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+ text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link schema:debug-event}.',
},
{
type: 'prose',
@@ -104,22 +104,11 @@ export const gapReport = {
},
{
type: 'prose',
- text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
- },
- {
- type: 'table',
- headers: ['`status`', 'Meaning'],
- rows: [
- [
- '`filed`',
- 'You created or queued the report. Return `url` or `message`.',
- ],
- [
- '`routed_only`',
- 'You point the caller to where to file it. `url` is required.',
- ],
- ['`skipped`', 'You chose not to act, for example on a duplicate.'],
- ],
+ text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages.',
+ },
+ {
+ type: 'prose',
+ text: 'Every field is in {@link schema:gap-report-handler}.',
},
{
type: 'prose',
diff --git a/packages/cli/assets/docs/tree/define-the-theme.doc.mjs b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
index 0498133954..e28d662747 100644
--- a/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
@@ -45,7 +45,7 @@ export const oceanTheme = defineTheme({
},
{
type: 'prose',
- text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:author-a-theme}.',
+ text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and every theme in the package disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set and component theming, read {@link generic:author-a-theme}.',
},
],
},
@@ -55,13 +55,14 @@ export const oceanTheme = defineTheme({
content: [
{
type: 'prose',
- text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
+ text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. Add the derived theme with `integration add theme ocean-contrast`, and import the base from its built package export, since local imports cannot leave the theme folder. The derived theme keeps a live link to the base and picks up its later changes when you rebuild it — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
},
{
type: 'code',
lang: 'ts',
- code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {oceanTheme} from './oceanTheme';
+ code: `// themes/ocean-contrast/oceanContrastTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
export const oceanContrastTheme = defineTheme({
name: 'ocean-contrast',
@@ -79,7 +80,7 @@ export const oceanContrastTheme = defineTheme({
content: [
{
type: 'prose',
- text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
+ text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: `light-dark()` takes two colors, so wrapping whole gradients makes the value invalid where the token is used, and `theme build` does not warn.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/describe-the-component.doc.mjs b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
index 802eb728fe..c72c7bc504 100644
--- a/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component`:
* choose and maintain the ComponentDoc shape that matches a component's public
* source.
*/
diff --git a/packages/cli/assets/docs/tree/docs.doc.mjs b/packages/cli/assets/docs/tree/docs.doc.mjs
index 9d45ebfd8b..4551f109ae 100644
--- a/packages/cli/assets/docs/tree/docs.doc.mjs
+++ b/packages/cli/assets/docs/tree/docs.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
- * integration package, which join the same docs tree as the CLI's own
- * (spec:AST-046, spec:AST-047).
+ * @file `astryx docs cli/integrations/building-blocks/docs`: the guides to
+ * writing docs for an integration package, which join the same docs tree as
+ * the CLI's own (spec:AST-046, spec:AST-047).
*/
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
diff --git a/packages/cli/assets/docs/tree/document-the-template.doc.mjs b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
index 5f5dcfc741..69913bda74 100644
--- a/packages/cli/assets/docs/tree/document-the-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/document-the-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template`:
* document page and block templates for discovery and correct reuse.
*/
diff --git a/packages/cli/assets/docs/tree/document-the-theme.doc.mjs b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
index 509ba4c1bd..26f5345c8a 100644
--- a/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
@@ -50,7 +50,7 @@ export default {
},
{
type: 'prose',
- text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that lists that package first drops your section.',
+ text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that loads that package after yours drops your section.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/export-template-assets.doc.mjs b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
index cde01fe276..687ee4136e 100644
--- a/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets`:
* expose and include everything a copied template imports, and declare the
* packages it needs.
*/
diff --git a/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
index 5d414a5516..38ab35a7b1 100644
--- a/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
+++ b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/extend-or-replace`: take over an
- * existing topic with `replaces`, merge sections into one with `extends`, and
- * check overlaps with Core topics.
+ * @file `astryx docs cli/integrations/building-blocks/docs/extend-or-replace`:
+ * take over an existing topic with `replaces`, merge sections into one with
+ * `extends`, and check overlaps with Core topics.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -46,7 +46,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.',
+ text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section replaces the base section it matches, and a section that matches none is added at the end.',
},
{
type: 'code',
@@ -63,7 +63,7 @@ export const docs = {
type: 'list',
style: 'unordered',
items: [
- "A section's key is its `id`, or a key made from its title. Read the base topic's keys with `--index`.",
+ "Read the base topic's keys with `--index`, and give a section that replaces one that key as its `id`. A section without an `id` matches only a base section with exactly its title, or one whose `id` is the key its title makes, so `Integration Themes` is added beside a base `Integration themes` that has no `id`.",
"The topic keeps the base's title and description, and readers open it by the base's name.",
'Replace the `Overview` placeholder that `integration add` writes, or it is added to the base topic.',
"Extend a topic to correct or add to it. A copy made with `replaces` stops getting the owner's fixes.",
@@ -87,7 +87,7 @@ export const docs = {
{
type: 'code',
lang: 'text',
- code: 'severity: [info]\ntopic: acme-getting-started\nrelationship: replaces\ncoreTopic: getting-started\nmessage: Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity: [fail]\ntopic: tokens\nrelationship: accidental\ncoreTopic: tokens\nmessage: Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: \'tokens\' to take it over, or declare extends: \'tokens\' to merge sections.',
+ code: 'severity: [info]\ntopic: acme-getting-started\nrelationship: replaces\ncoreTopic: getting-started\nmessage: Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity: [fail]\ntopic: color\nrelationship: accidental\ncoreTopic: color\nmessage: Accidental conflict: "color" is already a Core topic. Rename it, declare replaces: \'color\' to take it over, or declare extends: \'color\' to merge sections.',
},
{
type: 'list',
diff --git a/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
index 5c2449b9ae..81f5a55d33 100644
--- a/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
@@ -61,7 +61,7 @@ export const oceanTheme = defineTheme({
},
{
type: 'prose',
- text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. If the app loads the same family outside the generated module, Doctor warns because it cannot prove the loader, but the warning does not fail the app.',
+ text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. Doctor warns when it cannot prove the loader — a hosted `@import`, or no font stylesheet while the app loads the family itself — but the warning does not fail the app.',
},
{
type: 'code',
@@ -83,7 +83,7 @@ export const oceanTheme = defineTheme({
'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic.',
'Include self-hosted font files and their licenses in the packed package.',
'Keep CSS and font assets side-effectful so a bundler does not remove the loader.',
- 'Run `integration verify`; it fails when an exported font stylesheet or one of its packed files cannot resolve.',
+ 'Run `integration verify`; it fails when an exported font stylesheet cannot resolve, but it does not check the font files the stylesheet names.',
],
},
],
diff --git a/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
index f6cce3bc61..0ac5958567 100644
--- a/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
+++ b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
@@ -21,7 +21,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+ text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent.',
},
{
type: 'prose',
@@ -50,7 +50,9 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
lang: 'text',
code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
-[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json
+
+Review and edit the candidate before adopting it as theme-owned palette data.`,
},
{
type: 'prose',
@@ -58,7 +60,7 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
},
{
type: 'prose',
- text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+ text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. Every option is in {@link command:theme palette generate}, and the config it reads is described in {@link function:generateTonalPalette}.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
index daa42b7c14..c9e223a1f1 100644
--- a/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
+++ b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates/grade-template-with-agent`:
* give an agent the canonical rubric and require a reproducible template grade.
*/
diff --git a/packages/cli/assets/docs/tree/integrations.doc.mjs b/packages/cli/assets/docs/tree/integrations.doc.mjs
index 6ec96b6be0..47e4accaf1 100644
--- a/packages/cli/assets/docs/tree/integrations.doc.mjs
+++ b/packages/cli/assets/docs/tree/integrations.doc.mjs
@@ -36,6 +36,10 @@ export const docs = {
type: 'prose',
text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
},
+ {
+ type: 'prose',
+ text: 'Every field of every file you write for an integration is in {@link generic:authoring}.',
+ },
{
type: 'prose',
text: "Every integration runs `astryx integration check --strict` in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See {@link generic:checks}.",
diff --git a/packages/cli/assets/docs/tree/links.doc.mjs b/packages/cli/assets/docs/tree/links.doc.mjs
index 6d97f6135e..2052123ed1 100644
--- a/packages/cli/assets/docs/tree/links.doc.mjs
+++ b/packages/cli/assets/docs/tree/links.doc.mjs
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/links`: link one doc to another by
- * identity, link the CLI's docs, and fix a link that names no doc.
+ * @file `astryx docs cli/integrations/building-blocks/docs/links`: link one doc
+ * to another by identity, link the CLI's docs, and fix a link that names no
+ * doc.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -36,7 +37,7 @@ export const docs = {
type: 'list',
style: 'unordered',
items: [
- 'The kind is `generic` for a topic or guide, `namespace` for a docs section, `command` or `function` for a CLI command or API function, `component` for a component, and `page` or `block` for a template.',
+ 'The kind is `generic` for a topic or guide, `namespace` for a docs section, `command` or `function` for a CLI command or API function, `schema` or `enum` for a schema or a fixed set of values, `component` for a component, and `page` or `block` for a template.',
'Name a component by its export name and a template by its id. Its link reads as the command that opens it, such as `astryx component AcmeCarousel --package @acme/widgets`.',
'Inside backticks or a code block, link syntax prints as written.',
],
@@ -89,7 +90,7 @@ export const docs = {
style: 'unordered',
items: [
'The warning keeps exit code 0, so read the report before you ship; see {@link generic:check-your-docs}.',
- 'A stable CLI before 0.7.0 does not read links: it prints each one as written. See {@link generic:versioning}.',
+ 'Published 0.6.4 and later read links. An older CLI, such as published 0.6.3, prints each one as written; see {@link generic:versioning}.',
],
},
],
diff --git a/packages/cli/assets/docs/tree/package-and-test.doc.mjs b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
index 7022c1e054..e9966a5fae 100644
--- a/packages/cli/assets/docs/tree/package-and-test.doc.mjs
+++ b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/package-and-test`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test`:
* expose a template from its package and prove the copied result in an app.
*/
diff --git a/packages/cli/assets/docs/tree/page-template.doc.mjs b/packages/cli/assets/docs/tree/page-template.doc.mjs
index aaf14a2676..f455546977 100644
--- a/packages/cli/assets/docs/tree/page-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/page-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/document-the-template/page-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/page-template`:
* the page-only fields that help people find a page.
*/
@@ -49,12 +49,8 @@ export default {
title: 'Help people find the page',
content: [
{
- type: 'reference',
- target: 'schema:template-doc',
- projection: {
- fields: ['category', 'scaffold'],
- },
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:template-doc}.',
},
{
type: 'list',
diff --git a/packages/cli/assets/docs/tree/publishing.doc.mjs b/packages/cli/assets/docs/tree/publishing.doc.mjs
index d86b241bdb..f22f5389ff 100644
--- a/packages/cli/assets/docs/tree/publishing.doc.mjs
+++ b/packages/cli/assets/docs/tree/publishing.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/publishing`: publish an integration to
+ * @file `astryx docs cli/integrations/ship/publishing`: publish an integration to
* npm, use release tags, and check the package before and after.
*/
diff --git a/packages/cli/assets/docs/tree/quick-start.doc.mjs b/packages/cli/assets/docs/tree/quick-start.doc.mjs
index 718e43ab2c..457bdb2054 100644
--- a/packages/cli/assets/docs/tree/quick-start.doc.mjs
+++ b/packages/cli/assets/docs/tree/quick-start.doc.mjs
@@ -34,17 +34,18 @@ export const docs = {
},
{
type: 'prose',
- text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI, Core, and TypeScript for development.',
+ text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, make it an ES module, then install the Astryx CLI, Core, and TypeScript for development.',
},
{
type: 'code',
lang: 'bash',
- code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",
+ code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets type=module\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",
},
{
type: 'list',
style: 'unordered',
items: [
+ 'Set `"type": "module"`: the `.js` files the CLI generates, such as a built theme, are ES modules, and Node fails to load them in a package marked `"type": "commonjs"`, which `npm init -y` writes on npm 11.',
'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
'Component commands read Core, so they need `@astryxdesign/core` installed.',
@@ -200,7 +201,7 @@ export const docs = {
],
[
'`peerDependencies`',
- '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+ '`@astryxdesign/core` when your code imports it; `@astryxdesign/cli`, optional, when you ship a feature that needs a newer CLI ({@link generic:versioning})',
'The app supplies these packages for your integration.',
],
[
@@ -254,21 +255,8 @@ export const docs = {
text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
},
{
- type: 'reference',
- target: 'schema:integration',
- projection: {
- fields: [
- 'providerId',
- 'components',
- 'templates',
- 'codemods',
- 'docs',
- 'themes',
- 'agentDocs',
- 'issuesUrl',
- ],
- },
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:integration}.',
},
{
type: 'heading',
diff --git a/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
index dc72f07b98..6d39f182d9 100644
--- a/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/replace-a-core-component`:
* intentionally make an integration component the default for a Core identity.
*/
@@ -65,10 +65,8 @@ export default {
};`,
},
{
- type: 'reference',
- target: 'schema:component-doc',
- projection: {fields: ['replaces']},
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:component-doc}.',
},
{
type: 'prose',
@@ -87,7 +85,7 @@ export default {
type: 'list',
style: 'unordered',
items: [
- 'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that earlier `integration add theme` and `integration add doc --parent` wrote.',
+ 'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that `integration add doc --parent` wrote in published 0.6.4 and 0.6.5, and `integration add theme` in published 0.6.5.',
'Without such a range, the component keeps its own name, the Core component stays selected (a component named like its target stays ambiguous by that bare name, as before), and `doctor integration components` warns with the range to add. Apps that load such a package see no change.',
'`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',
diff --git a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
index 4eb38724a1..70caf89eb3 100644
--- a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template`:
* deliberately replace one Core template through template metadata.
*/
@@ -67,10 +67,8 @@ export default {
};`,
},
{
- type: 'reference',
- target: 'schema:template-doc',
- projection: {fields: ['replaces']},
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:template-doc}.',
},
{
type: 'prose',
@@ -84,7 +82,7 @@ export default {
content: [
{
type: 'prose',
- text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+ text: 'Declare the CLI floor that `integration verify` names as an optional peer ({@link generic:versioning}).',
},
{
type: 'code',
@@ -103,7 +101,7 @@ export default {
},
{
type: 'prose',
- text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+ text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, published 0.6.3 and earlier drop that template and hide your doc topics.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
index dc9839bb87..6cef07935d 100644
--- a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
+++ b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/sections-and-placement`: give an
- * integration package its own section in the docs tree, place guides in it,
- * and fix a placement that fails.
+ * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * give an integration package its own section in the docs tree, place guides
+ * in it, and fix a placement that fails.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -62,9 +62,7 @@ export const docs = {
type: 'list',
style: 'unordered',
items: [
- "`parent` is `namespace:<name>`, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.",
- "`slot` is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.",
- '`order` is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.',
+ 'Every field is in {@link schema:authored-doc-graph-fields}.',
'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
],
},
diff --git a/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
index 157d5ba2a8..a73fc54a51 100644
--- a/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs cli/integrations/building-blocks/components/see-it-in-an-app`: inspect an
* integration component from an app that installs the package.
*/
@@ -33,7 +33,9 @@ npx astryx search carousel`,
{
type: 'code',
lang: 'text',
- code: `# AcmeCarousel
+ code: `package: @acme/astryx-widgets
+
+# AcmeCarousel
Cycles through slides one at a time. Use it for a small set of related cards.
diff --git a/packages/cli/assets/docs/tree/short-and-findable.doc.mjs b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
index acd4cf7c12..9987d6e30a 100644
--- a/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
+++ b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/docs/short-and-findable`: keep each read
- * short, lead each section with its summary, and write docs that search finds.
+ * @file `astryx docs cli/integrations/building-blocks/docs/short-and-findable`:
+ * keep each read short, lead each section with its summary, and write docs
+ * that search finds.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -58,7 +59,7 @@ export const docs = {
{
type: 'code',
lang: 'text',
- code: 'build-before-you-ship Build before you ship - Build the app, then upload the `dist` folder to your host.',
+ code: 'build-before-you-ship Build before you ship - Build the app, then upload the `dist` folder.',
},
],
},
@@ -68,14 +69,14 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.',
+ text: 'In a topic with more than one section, search ranks a section whose title matches the query, or that names it in backticks, above words in body text. Title each section with the task a reader searches for.',
},
{
type: 'list',
style: 'unordered',
items: [
'Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".',
- 'Write field names, file names, and error codes in backticks, such as `deployTarget`: search treats each one as a keyword.',
+ 'Write field names, file names, and error codes in backticks, such as `deployTarget`: in a topic with more than one section, search treats each one as a keyword.',
'Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.',
],
},
diff --git a/packages/cli/assets/docs/tree/single-component.doc.mjs b/packages/cli/assets/docs/tree/single-component.doc.mjs
index 49c125aaf2..2e8674259c 100644
--- a/packages/cli/assets/docs/tree/single-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/single-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/describe-the-component/single-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/single-component`:
* write and maintain the default ComponentDoc for one public component.
*/
@@ -61,9 +61,8 @@ export default {
],
},
{
- type: 'reference',
- target: 'schema:component-doc',
- presentation: 'summary',
+ type: 'prose',
+ text: 'Every field is in {@link schema:component-doc}.',
},
],
},
@@ -87,6 +86,15 @@ export default {
],
},`,
},
+ {
+ type: 'prose',
+ text: "Set `keywords` to the words people search for: synonyms and the task the component does, such as `keywords: ['slider', 'slideshow', 'rotating cards']`. `astryx search` ranks a match on a component's name or keywords above one in its description, so without keywords a search for the component's task can list Core components first. Check with the words a person would type:",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx search "rotating cards" --type component',
+ },
],
},
{
diff --git a/packages/cli/assets/docs/tree/start-a-template.doc.mjs b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
index 5da9515874..f6d9702f65 100644
--- a/packages/cli/assets/docs/tree/start-a-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/start-a-template`: what a
- * template is, why an integration shares one, whether it is a page or a
- * block, and how to add one.
+ * @file `astryx docs cli/integrations/building-blocks/templates/start-a-template`:
+ * what a template is, why an integration shares one, whether it is a page or
+ * a block, and how to add one.
*/
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
diff --git a/packages/cli/assets/docs/tree/subcomponent.doc.mjs b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
index bbaccb79e1..7b9deb98c4 100644
--- a/packages/cli/assets/docs/tree/subcomponent.doc.mjs
+++ b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/components/describe-the-component/subcomponent`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/subcomponent`:
* give one member of a component family its own ComponentDoc.
*/
@@ -51,6 +51,7 @@ export default {
type: 'component',
name: 'AcmeDialog',
displayName: 'Acme Dialog',
+ import: '@acme/astryx-widgets/components/AcmeDialog',
usage: {description: 'Presents a focused task above the current page.'},
components: [
{
@@ -82,6 +83,7 @@ export default {
type: 'component',
name: 'AcmeDialogHeader',
displayName: 'Acme Dialog Header',
+ import: '@acme/astryx-widgets/components/AcmeDialogHeader',
subComponentOf: 'AcmeDialog',
description: 'Labels an Acme Dialog and holds its close action.',
props: [
@@ -95,10 +97,8 @@ export default {
};`,
},
{
- type: 'reference',
- target: 'schema:component-doc',
- projection: {fields: ['subComponentOf', 'description', 'props']},
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:component-doc}.',
},
{
type: 'list',
@@ -106,7 +106,7 @@ export default {
items: [
'`subComponentOf` must exactly match the parent doc\'s `name`.',
'`description` explains this member\'s role in the family. `usage` is optional; add it when the member needs guidance beyond that sentence.',
- 'The child inherits family fields such as `group`, `category`, `keywords`, `theming`, and `playground` unless it overrides them.',
+ 'The CLI does not copy family fields such as `group`, `category`, or `keywords` from the parent to the child. Set any the child needs in its own doc.',
],
},
],
diff --git a/packages/cli/assets/docs/tree/template-assets.doc.mjs b/packages/cli/assets/docs/tree/template-assets.doc.mjs
index 2c92a45f0c..003de0be06 100644
--- a/packages/cli/assets/docs/tree/template-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-assets.doc.mjs
@@ -1,8 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/template-assets`: make every
- * style, font, icon, and media dependency survive a template copy.
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets`:
+ * make every style, font, icon, and media dependency survive a template copy.
*/
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
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 4aa5671e7a..19fa2775a7 100644
--- a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/document-the-template/template-doc-overview`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/template-doc-overview`:
* the source and doc file pair, the fields every template doc shares, and how
* to check what Astryx lists.
*/
@@ -54,22 +54,11 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
+ text: 'The fields below apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
},
{
- type: 'reference',
- target: 'schema:template-doc',
- projection: {
- fields: [
- 'type',
- 'name',
- 'displayName',
- 'description',
- 'keywords',
- 'isReady',
- ],
- },
- presentation: 'full',
+ type: 'prose',
+ text: 'Every field is in {@link schema:template-doc}.',
},
{
type: 'list',
diff --git a/packages/cli/assets/docs/tree/template-fonts.doc.mjs b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
index 67a721fec0..63de6f0915 100644
--- a/packages/cli/assets/docs/tree/template-fonts.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-fonts`:
* use the app typeface by default, and ship every font file a template needs
* when it must bring its own.
*/
diff --git a/packages/cli/assets/docs/tree/template-icons.doc.mjs b/packages/cli/assets/docs/tree/template-icons.doc.mjs
index 8980331e42..6da3f52e46 100644
--- a/packages/cli/assets/docs/tree/template-icons.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-icons.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-icons`:
* render template icons through Astryx and ship custom product icons from the
* package.
*/
diff --git a/packages/cli/assets/docs/tree/template-images-media.doc.mjs b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
index 5ca9962e04..75b375126a 100644
--- a/packages/cli/assets/docs/tree/template-images-media.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-images-media`:
* keep template images and video working after the copy, or make them clear
* placeholders.
*/
diff --git a/packages/cli/assets/docs/tree/template-styles.doc.mjs b/packages/cli/assets/docs/tree/template-styles.doc.mjs
index 988ff71808..032b33464e 100644
--- a/packages/cli/assets/docs/tree/template-styles.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-styles.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-styles`:
* style a template with Astryx first, keep editable styles in the file, and
* ship shared CSS from the package.
*/
@@ -85,7 +85,7 @@ const styles = stylex.create({
},
{
type: 'prose',
- text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). In a TypeScript app, this import type-checks only when the app declares `*.css` modules.',
+ text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). TypeScript 6 and later check side-effect imports by default, so this import type-checks only when the app or its framework declares `*.css` modules.',
},
],
},
diff --git a/packages/cli/assets/docs/tree/templates.doc.mjs b/packages/cli/assets/docs/tree/templates.doc.mjs
index be9700b915..8f79829109 100644
--- a/packages/cli/assets/docs/tree/templates.doc.mjs
+++ b/packages/cli/assets/docs/tree/templates.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates`: guides for adding,
+ * @file `astryx docs cli/integrations/building-blocks/templates`: guides for adding,
* documenting, packaging, and testing templates in an integration package.
*/
diff --git a/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
index e03df93fd7..07ca363619 100644
--- a/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/test-in-an-app`: install the packed
+ * @file `astryx docs cli/integrations/ship/test-in-an-app`: install the packed
* package in an app and run the commands its users run.
*/
@@ -63,11 +63,11 @@ export const docs = {
],
[
'`template --list --package`',
- 'An `acme-dashboard` entry with `package: @acme/astryx-widgets`',
+ 'An `acme-dashboard` entry whose `package` is `@acme/astryx-widgets`',
],
[
'`theme list --package`',
- '`- ocean (maintained, @acme/astryx-widgets)`',
+ 'An `ocean` entry whose `package` is `@acme/astryx-widgets`',
],
['`docs acme`', 'Your section, with guides such as `deploying`'],
[
diff --git a/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
index 5763a9657b..b32a808b31 100644
--- a/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app`:
* copy the packed template into a clean app, build it, and render it the way
* apps will.
*/
diff --git a/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs
index 79cb2cef0b..3720ce16d0 100644
--- a/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs
+++ b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs
@@ -15,13 +15,7 @@ export const docs = {
category: 'guide',
description:
'Using design tokens in custom styles and configuring a StyleX compiler for swizzled components.',
- keywords: [
- 'StyleX setup',
- 'swizzle',
- 'webpack',
- 'Vite',
- 'Next.js',
- ],
+ keywords: ['StyleX setup', 'swizzle', 'webpack', 'Vite', 'Next.js'],
sections: [
{
@@ -77,30 +71,40 @@ const styles = stylex.create({
content: [
{
type: 'prose',
- text: 'Astryx components ship pre-compiled: `astryx.css` and each package\'s own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
+ text: "Astryx components ship pre-compiled: `astryx.css` and each package's own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one, importing the component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render. If a swizzled component throws that error, the app is missing a StyleX compiler. The same applies if you author your own StyleX with `stylex.create()`.",
},
{
type: 'table',
headers: ['Bundler', 'StyleX plugin'],
rows: [
['Webpack', '@stylexjs/webpack-plugin'],
- ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],
- ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
- ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],
+ [
+ 'Vite / Rollup',
+ '@stylexjs/rollup-plugin (or a community Vite plugin)',
+ ],
+ [
+ 'Babel (any bundler)',
+ '@stylexjs/babel-plugin + @stylexjs/postcss-plugin',
+ ],
+ [
+ 'Next.js (App Router, SWC)',
+ 'An SWC-based transform; see the Next.js note below',
+ ],
],
},
{
type: 'prose',
- text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',
+ text: "Next.js (App Router) is the sharp edge. StyleX's canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.",
},
{
type: 'prose',
- text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',
+ text: "The repo's `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.",
},
{
type: 'code',
lang: 'js',
- label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
+ label:
+ 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
code: `import stylexPlugin from '@stylexswc/nextjs-plugin';
export default stylexPlugin({
@@ -117,7 +121,7 @@ export default stylexPlugin({
type: 'list',
style: 'unordered',
items: [
- 'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
+ "Symptom of a missing compiler: importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render.",
'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',
'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
'Keep loading `astryx.css` with a StyleX compiler in place. The compiler builds your own and swizzled source only; never add `node_modules/@astryxdesign` to its inputs.',
diff --git a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
index 8698cbfdab..550f022150 100644
--- a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
+++ b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/troubleshooting`: the messages the CLI
+ * @file `astryx docs cli/integrations/help/troubleshooting`: the messages the CLI
* prints while you build, verify, and install an integration, and the fix
* for each.
*/
@@ -103,11 +103,11 @@ export const docs = {
],
[
'`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.",
+ "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A CLI older than published 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
],
[
'`section_ids_need_cli`: The package has a doc section that sets `id` but declares no @astryxdesign/cli peer.',
- 'The same fix as `themes_need_cli`, or drop the section `id`s: a stable CLI before 0.6.4 rejects them and hides your doc topics.',
+ 'The same fix as `themes_need_cli`, or drop the section `id`s: a CLI older than published 0.6.4 rejects them and hides your doc topics.',
],
],
},
@@ -151,7 +151,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.6.6 for a template that sets `keywords`, or before 0.6.4 for a template that sets `replaces`, a docs section, or 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.6.6 for a template that sets `keywords`, or before 0.6.4 for a template that sets `replaces`, a docs section, or a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm checks the app's CLI against it when the app installs your package.",
],
],
},
diff --git a/packages/cli/assets/docs/tree/upgrading.doc.mjs b/packages/cli/assets/docs/tree/upgrading.doc.mjs
index eae5e7b239..461d3f9851 100644
--- a/packages/cli/assets/docs/tree/upgrading.doc.mjs
+++ b/packages/cli/assets/docs/tree/upgrading.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/upgrading`: update an integration
+ * @file `astryx docs cli/integrations/ship/upgrading`: update an integration
* package for each Astryx release, and the command apps run to upgrade with
* it.
*/
@@ -57,7 +57,7 @@ export const docs = {
{
type: 'code',
lang: 'text',
- code: 'Integrations: @acme/astryx-widgets\n1 codemod to run\nApplying integration codemods...\n Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok] [ok] src/Hero.tsx',
+ code: 'Integrations: @acme/astryx-widgets\n<n> codemods to run\nApplying integration codemods...\n Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok] [ok] src/Hero.tsx',
},
{
type: 'list',
@@ -65,7 +65,7 @@ export const docs = {
items: [
'`--from` is the `@astryxdesign/core` version the app had before, and the target is the installed Core.',
'`--integration` names your package. Without it, or an `integrations` entry in `astryx.config`, the upgrade skips your codemods, even when the app has your package installed.',
- "The count includes Core's codemods for the same versions, which run first.",
+ "`<n>` includes Core's codemods for the same versions, which run first.",
'Put this command in your release notes.',
],
},
diff --git a/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
index 3fc0e88ecb..e93f44533b 100644
--- a/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
@@ -34,7 +34,9 @@ export const docs = {
code: `import {Theme} from '@astryxdesign/core/theme';
import {themes, defaultThemeSlug} from './astryx-themes';
-<Theme theme={themes[defaultThemeSlug]}>{/* app */}</Theme>`,
+<Theme theme={themes[defaultThemeSlug]}>
+ <App />
+</Theme>`,
},
{
type: 'prose',
diff --git a/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
index ed107bf35b..872474b285 100644
--- a/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
* what `integration verify` checks for templates, and what it leaves to the
* app test.
*/
diff --git a/packages/cli/assets/docs/tree/versioning.doc.mjs b/packages/cli/assets/docs/tree/versioning.doc.mjs
index 56ea9e00c6..3a7bce28d5 100644
--- a/packages/cli/assets/docs/tree/versioning.doc.mjs
+++ b/packages/cli/assets/docs/tree/versioning.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/versioning`: version an integration
+ * @file `astryx docs cli/integrations/ship/versioning`: version an integration
* package, know which changes break apps, declare peer ranges, keep apps on
* older CLIs working, and match codemod folders to versions.
*/
@@ -106,8 +106,8 @@ export const docs = {
],
[
'`@astryxdesign/cli`',
- '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.6.6` when you ship a template that sets `keywords`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
+ 'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a component that sets `replaces`, a doc section with an `id`, or a theme',
+ '`>=0.6.6` when you ship a template that sets `keywords`, `>=0.6.7` when a component sets `replaces`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
],
],
},
@@ -136,10 +136,10 @@ export const docs = {
items: [
'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.',
+ 'Published 0.6.3 and earlier print each `{@link ...}` as written.',
'Published 0.6.3 and earlier reject a template that sets `replaces` or `keywords`, drop that template, and hide every doc topic your package ships. Published 0.6.4 and 0.6.5 still drop a template that sets `keywords`.',
- 'A stable CLI before 0.6.4 cannot read a docs section, 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.',
+ 'Published 0.6.3 and earlier cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. They can then hide every doc topic your package ships.',
+ 'Published 0.6.2 and 0.6.3 still load your components, but published 0.6.0 and 0.6.1 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
'An app on an older CLI lists a component whose doc names another export of its file under the file name, and lists no family members, so `component AcmeCarousel` fails there.',
],
},
diff --git a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
index 33e48f284b..b0400a7eb3 100644
--- a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
+++ b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/write-the-template-file`:
* what gets copied, where the copied file lands, and the imports and
* export a copied template needs.
*/
@@ -145,7 +145,7 @@ export default function AcmeAccountSummary() {
type: 'list',
style: 'unordered',
items: [
- 'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+ 'Add `use client` as the first statement only when hooks, event handlers, browser APIs, or a component passed as a prop, such as `icon={BellIcon}`, need a client boundary.',
'Keep a static template server-compatible when it needs no client behavior.',
],
},
diff --git a/packages/cli/authoring/codemod/codemod.doc.mjs b/packages/cli/authoring/codemod/codemod.doc.mjs
index 195c210de2..4a46ae53a4 100644
--- a/packages/cli/authoring/codemod/codemod.doc.mjs
+++ b/packages/cli/authoring/codemod/codemod.doc.mjs
@@ -17,7 +17,8 @@ export const doc = {
'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
"plain object with a `type` discriminant: 'code' rewrites source files, " +
"'config' rewrites the astryx.config.* file. There is no factory to call.",
- appliesTo: 'the codemods/ dir of an integration',
+ appliesTo:
+ '`<codemods>/<version>/<id>.{ts,mjs,js}` in an integration package: `<codemods>` is the codemods root of astryx.integration.*, and `<version>` is the exact @astryxdesign/core version (such as 0.7.0) whose upgrade runs the codemod. A file directly in the root never runs.',
fields: [
{
name: 'title',
@@ -44,6 +45,7 @@ export const doc = {
description:
'File extensions this codemod applies to. Code codemods only; a ' +
'config codemod always targets astryx.config.*.',
+ default: "['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']",
example: "['.tsx', '.ts']",
},
{
@@ -58,6 +60,7 @@ export const doc = {
name: 'file',
type: 'AstryxCodemodFile',
description: 'The source file presented to the transform.',
+ required: true,
fields: [
{
name: 'file.path',
@@ -77,6 +80,7 @@ export const doc = {
name: 'api',
type: 'AstryxCodemodApi',
description: 'Helpers and context passed as the second argument.',
+ required: true,
fields: [
{
name: 'api.jscodeshift',
@@ -89,14 +93,14 @@ export const doc = {
name: 'api.stats',
type: '(...args: unknown[]) => void',
description:
- 'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+ 'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
required: true,
},
{
name: 'api.report',
type: '(...args: unknown[]) => void',
description:
- 'Report progress (no-op-friendly; provided for jscodeshift parity).',
+ 'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
required: true,
},
],
diff --git a/packages/cli/authoring/config/config.doc.mjs b/packages/cli/authoring/config/config.doc.mjs
index 701a9606de..e0fe98fbcf 100644
--- a/packages/cli/authoring/config/config.doc.mjs
+++ b/packages/cli/authoring/config/config.doc.mjs
@@ -15,8 +15,8 @@ export const doc = {
description:
'The optional astryx.config.* file at your project root. Declares which ' +
'integrations to load, where to route issue links, post-codemod hooks, local ' +
- 'debug-log and gap-report handlers, and experimental layout components. All ' +
- 'optional; {} is valid.',
+ 'debug-log and gap-report handlers, a discover source, and experimental ' +
+ 'layout components. All optional; {} is valid.',
appliesTo: 'astryx.config.{ts,mjs,js}',
fields: [
{
@@ -29,7 +29,9 @@ export const doc = {
{
name: 'issuesUrl',
type: 'string',
- description: 'URL that "report an issue" affordances link to.',
+ description:
+ "Where reports about Core go: `astryx gap-report` routes a Core report here when no handler is loaded, gapReport handlers receive it as `report.target.issuesUrl`, and `astryx swizzle` prints it as the feedback link for a Core component. A report or swizzle for an integration's component uses that integration's own issuesUrl, never this one. An absolute URL; a value that is not a URL makes the config invalid.",
+ default: "'https://github.com/facebook/astryx/issues/new'",
},
{
name: 'hooks',
@@ -40,7 +42,7 @@ export const doc = {
name: 'hooks.postCodemod',
type: 'PostCodemodHook[]',
description:
- 'Commands run after an upgrade applies codemods (e.g. re-run your formatter). Each hook returns a command to execute, or null to skip.',
+ 'Commands to run after `astryx upgrade` changes files (e.g. re-run your formatter). Each hook is an object `{name?, buildCommand}`: buildCommand gets `{packageDir, files}` and returns `{command, args?, options?}` to run, or null to skip. A dry run prints each command instead of running it.',
},
],
},
@@ -77,7 +79,7 @@ export const doc = {
name: 'experimental.xle.components',
type: 'Record<string, XleComponent>',
description:
- 'Custom components the layout expander (XLE) may emit, keyed by tag.',
+ 'Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it.',
},
],
},
@@ -90,6 +92,7 @@ export const doc = {
{
label: 'Send every command run somewhere of your own',
code:
+ "import {appendFileSync} from 'node:fs';\n\n" +
'export default {\n' +
' debug: event => appendFileSync("runs.ndjson", JSON.stringify(event) + "\\n"),\n' +
'};',
@@ -98,7 +101,7 @@ export const doc = {
notes: [
{
type: 'prose',
- text: 'The config is validated at load with a strict schema: unknown keys are errors, so a typo fails fast rather than being silently ignored.',
+ text: 'The config is validated at load with a strict schema: an unknown key, a misspelled one included, or a value of the wrong type makes the whole file invalid. `astryx gap-report`, `astryx discover`, and `astryx upgrade` stop with the error, and `astryx doctor` fails its `config` check (exit 1). Reads such as `component`, `docs`, `search`, `template`, and `theme` carry on silently as if there were no config and no integrations, and no debug handler runs, so run `astryx doctor` after editing the file.',
},
],
};
diff --git a/packages/cli/authoring/config/type.ts b/packages/cli/authoring/config/type.ts
index 0926d65ec8..bf718185b5 100644
--- a/packages/cli/authoring/config/type.ts
+++ b/packages/cli/authoring/config/type.ts
@@ -115,8 +115,10 @@ export interface AstryxConfig {
/** Experimental XLE (layout expression) configuration. */
xle?: {
/**
- * Register app-local components so XLE layout expressions can
- * reference them by name via {hint}. Keyed by component name.
+ * Custom components for the removed layout expander, keyed by
+ * component name. The CLI still validates the field, so an entry
+ * without a string `from` makes `astryx.config` invalid, but nothing
+ * reads it.
*/
components?: Record<string, XleComponent>;
};
diff --git a/packages/cli/authoring/discover/discover.doc.mjs b/packages/cli/authoring/discover/discover.doc.mjs
index 1b338575ff..d251ff1a68 100644
--- a/packages/cli/authoring/discover/discover.doc.mjs
+++ b/packages/cli/authoring/discover/discover.doc.mjs
@@ -16,7 +16,7 @@ export const doc = {
displayName: 'DiscoverSource',
namespace: 'authoring',
description:
- 'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.',
+ 'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer that source gave for the same request, or reports the source as failed when it saved none. Discover only reads: it prints the command that adds a package and never runs it.',
appliesTo:
'`discover` in astryx.config.*, or the `discover` named export of astryx.integration.*',
fields: [
diff --git a/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
index c86df4da41..6de73a717c 100644
--- a/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
+++ b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
@@ -12,14 +12,15 @@ export const doc = {
displayName: 'Authored doc graph fields',
namespace: 'authoring',
description:
- "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
- appliesTo: 'Every supported .doc.mjs object',
+ "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide and namespace doc, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic that sets one fails to load, placed in the docs tree or not, and other doc kinds accept them and ignore them.",
+ appliesTo:
+ "Every authored doc kind's .doc.mjs object. Theme descriptors take none of these fields.",
fields: [
{
name: 'placement',
type: 'DocPlacement',
description:
- "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also `replaces` or `extends` a topic. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
+ "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's, and for every namespace doc: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also set `replaces` or `extends`; a namespace doc with `placement` nests under that parent. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
fields: [
{
name: 'placement.parent',
@@ -37,7 +38,8 @@ export const doc = {
{
name: 'placement.order',
type: 'number',
- description: 'Integer sibling order within the slot.',
+ description:
+ "Integer sibling order within the slot. Docs without an order come after the ordered ones, sorted by title. The same order sets each doc's Previous and Next links.",
},
],
},
diff --git a/packages/cli/authoring/doctypes/command/command.doc.mjs b/packages/cli/authoring/doctypes/command/command.doc.mjs
index 06754f6a26..0dbaae802f 100644
--- a/packages/cli/authoring/doctypes/command/command.doc.mjs
+++ b/packages/cli/authoring/doctypes/command/command.doc.mjs
@@ -48,18 +48,20 @@ export const doc = {
{
name: 'description',
type: 'string',
- description: 'Longer help body / when-to-use.',
+ description:
+ 'Longer body / when-to-use. `astryx docs` prints it after the summary; `--help` shows only the summary.',
},
{
name: 'namespace',
type: 'string',
description:
- "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+ "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`, spaces as hyphens (`theme build` is `cli/commands/theme-build`). Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
},
{
name: 'aliases',
type: 'string[]',
- description: 'Alternate slugs that also resolve to this doc.',
+ description:
+ 'Reserved: other names for this doc. Nothing reads it today, so they do not resolve to it.',
},
{
name: 'fn',
@@ -83,13 +85,13 @@ export const doc = {
name: 'args[].param',
type: 'string',
description:
- 'FunctionDoc param this arg binds to (inherits its description).',
+ "FunctionDoc param this arg binds to; `astryx docs` shows that param's description when the arg has none.",
},
{
name: 'args[].description',
type: 'string',
description:
- 'Override description (else inherited from the referenced param).',
+ "Override description. `--help` shows an argument's description only when it sets this.",
},
{
name: 'args[].required',
@@ -126,7 +128,7 @@ export const doc = {
name: 'options[].description',
type: 'string',
description:
- 'Override/explicit description (required when `cliOnly`).',
+ 'Override/explicit description. Nothing requires it: a flag with neither this nor `param` shows no description.',
},
{
name: 'options[].choices',
@@ -143,7 +145,7 @@ export const doc = {
name: 'options[].cliOnly',
type: 'boolean',
description:
- 'True for CLI-only flags with no function param (e.g. --json).',
+ 'True for CLI-only flags with no function param (e.g. --verbose). Nothing reads it.',
},
],
},
@@ -220,13 +222,13 @@ export const doc = {
type: 'command',
name: 'search',
displayName: 'astryx search',
- summary: 'Find components, hooks, docs, and templates.',
- namespace: 'cli',
+ summary: 'Find components, hooks, docs, templates, and themes.',
+ namespace: 'cli/commands',
fn: 'search',
args: [{name: 'query', param: 'query', required: true}],
options: [
- {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template']},
- {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
+ {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template', 'theme']},
+ {flag: '--verbose', cliOnly: true, description: "Also print each result's score and match reason."},
],
examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
exitCodes: [{code: 1, when: 'The --type value is not a known domain.'}],
@@ -241,7 +243,7 @@ export const doc = {
},
{
type: 'prose',
- text: "Bind an arg/option to a function param via `param` so it inherits that param's description. Use `cliOnly: true` for flags with no function param (e.g. `--json`); those must supply their own `description`.",
+ text: "Bind an arg/option to a function param via `param` so it inherits that param's description: an option's in `--help` and `astryx docs`, an arg's in `astryx docs` only. Mark a flag with no function param (e.g. `--verbose`) `cliOnly: true` and give it its own `description`; nothing checks either. `--json` is a global flag, so a command doc does not declare it.",
},
],
};
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index b8ff1d1832..04b439a805 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -30,7 +30,7 @@ export const doc = {
name: 'name',
type: 'string',
description:
- "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
+ "Stable machine identity without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
required: true,
},
{
@@ -62,19 +62,19 @@ export const doc = {
name: 'keywords',
type: 'string[]',
description:
- 'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. Used by `astryx component <term>` fuzzy matching.',
+ 'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. `astryx search` matches them; `astryx component <term>` also suggests Core components by keyword.',
},
{
name: 'hiddenComponents',
type: 'string[]',
description:
- 'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source.',
+ "Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source. In an integration it hides only full entries in this doc's `components`, which the CLI then neither lists nor opens; hide a sub-component that has its own doc with `hidden` in that doc.",
},
{
name: 'hidden',
type: 'boolean',
description:
- 'Hide this entire component from human-facing UI. It stays public and importable. Use for shared primitives (NavIcon, NavMenu) that only make sense inside their parent.',
+ 'Hide this entire component from human-facing UI. It stays public and importable. Use for a shared primitive that only makes sense inside its parent.',
},
{
name: 'group',
@@ -98,13 +98,13 @@ export const doc = {
name: 'theming',
type: '{ container?: boolean; targets: ComponentThemingTarget[]; vars?: ComponentThemingVar[]; derived?: ComponentThemingDerivedVar[] }',
description:
- 'Theming configuration: the stable selector surface (xds-* classes + data-attribute reflections) that themes target via @scope selectors in defineTheme.',
+ 'Theming configuration: the stable selector surface (astryx-* classes + data-attribute reflections) that themes target via @scope selectors in defineTheme.',
fields: [
{
name: 'theming.container',
type: 'boolean',
description:
- 'When true, container `padding` props are mapped to container tokens by the theme pipeline instead of emitting raw CSS.',
+ "Marks a container component. Nothing reads it today: the theme pipeline maps `padding` to container tokens from a `theming.derived` entry `{property: 'padding', expand: 'container'}`.",
},
{
name: 'theming.targets',
@@ -122,7 +122,7 @@ export const doc = {
name: 'theming.derived',
type: 'ComponentThemingDerivedVar[]',
description:
- 'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first.',
+ "Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first. The pipeline reads only Core components' entries, so an integration's have no effect.",
},
],
},
@@ -193,7 +193,7 @@ export const doc = {
name: 'subComponentOf',
type: 'string',
description:
- "SubComponentDoc variant (required there): the parent component's `name` (e.g. 'Chat'). Marks this file as a sub-component doc that inherits family fields (group, category, keywords, theming, playground) from the parent.",
+ "SubComponentDoc variant (required there): the parent component's `name` (e.g. 'Chat'). Marks this file as a sub-component doc. The CLI does not copy family fields (group, category, keywords, theming, playground) from the parent to an integration's sub-component: its detail, list group and search use only what its own doc sets. Set any the child needs in its own doc.",
},
{
name: 'description',
@@ -206,9 +206,10 @@ export const doc = {
{
label: 'SingleComponentDoc (props on the doc)',
code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
- name: 'Switch',
- displayName: 'Switch',
+export default {
+ type: 'component',
+ name: 'AcmeSwitch',
+ displayName: 'Acme Switch',
category: 'Form Controls',
keywords: ['toggle', 'switch', 'on off'],
usage: {
@@ -229,17 +230,18 @@ export const docs = {
{
label: 'MultiComponentDoc (a components array)',
code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
- name: 'Table',
- displayName: 'Table',
+export default {
+ type: 'component',
+ name: 'AcmeTable',
+ displayName: 'Acme Table',
category: 'Table & List',
usage: {description: 'Displays rows and columns of data. Compose the sub-components to build headers, rows, and cells.'},
components: [
- {name: 'Table', displayName: 'Table', description: 'The table container.', props: []},
- {name: 'TableRow', displayName: 'Table Row', description: 'A row within the table body.', props: [
+ {name: 'AcmeTable', displayName: 'Acme Table', description: 'The table container.', props: []},
+ {name: 'AcmeTableRow', displayName: 'Acme Table Row', description: 'A row within the table body.', props: [
{name: 'isSelected', type: 'boolean', description: 'Highlights the row as selected.'},
]},
- {name: 'useTableSelection', displayName: 'useTableSelection', description: 'Manages row selection state.',
+ {name: 'useAcmeTableSelection', displayName: 'useAcmeTableSelection', description: 'Manages row selection state.',
params: [{name: 'rows', type: 'T[]', description: 'The rows to track.', required: true}],
returns: [{name: 'selectedIds', type: 'Set<string>', description: 'Currently selected row ids.'}]},
],
@@ -249,7 +251,7 @@ export const docs = {
notes: [
{
type: 'prose',
- text: "When it loads, a stamped component doc is checked as loosely as an unstamped one, so adding `type: 'component'` to an existing doc never breaks it: `displayName` may be missing, `category` may be any string, and `usage`, `theming`, `playground` and `examples` are not checked. Each entry in a group doc's `components` must have a `name`. Write to the type anyway; it is the contract.",
+ text: "When it loads, a stamped component doc is checked about as loosely as an unstamped one, so adding `type: 'component'` to a doc that follows the type never breaks it: `displayName` may be missing, `category` may be any string, `usage`, `theming` and `playground` are not checked, and `examples` need only be an array. Unlike an unstamped doc, each entry in a group doc's `components` must have a `name`, and `import` and `replaces`, when set, must be non-empty strings. Write to the type anyway; it is the contract.",
},
{
type: 'prose',
@@ -261,7 +263,7 @@ export const docs = {
items: [
'SingleComponentDoc: one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
'MultiComponentDoc: a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
- 'SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
+ "SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It does not take the parent's family fields, and it may omit `usage`.",
],
},
{
@@ -269,11 +271,12 @@ export const docs = {
lang: 'js',
label: 'SubComponentDoc',
code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
- name: 'ChatComposer',
- displayName: 'Chat Composer',
- subComponentOf: 'Chat',
- description: 'The message input row within a Chat, with an editor and send affordance.',
+export default {
+ type: 'component',
+ name: 'AcmeChatComposer',
+ displayName: 'Acme Chat Composer',
+ subComponentOf: 'AcmeChat',
+ description: 'The message input row within an Acme Chat, with an editor and send affordance.',
props: [
{name: 'onSend', type: '(text: string) => void', description: 'Called when the user submits a message.', required: true},
],
@@ -281,7 +284,7 @@ export const docs = {
},
{
type: 'prose',
- text: "The stamped format is `export default { type: 'component', ... }`; legacy docs use `export const docs = {...}` and omit `type` (the parser shape-sniffs). A hook that is part of a component API is documented as a ComponentEntry in a MultiComponentDoc `components` array (with `params`/`returns`), not as a standalone HookDoc.",
+ text: "The stamped format is `export default { type: 'component', ... }`, which `astryx integration add component` writes; legacy docs use `export const docs = {...}` and omit `type` (the parser shape-sniffs). A hook that is part of a component API is listed in a MultiComponentDoc `components` array: inline as a ComponentEntry (with `params`/`returns`), or by name with its own SubComponentDoc file, as Core's useTableSelection is.",
},
],
};
diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.ts
index 7b131b60ee..13c6a58f4b 100644
--- a/packages/cli/authoring/doctypes/component/type.ts
+++ b/packages/cli/authoring/doctypes/component/type.ts
@@ -338,15 +338,17 @@ export interface SingleComponentDoc extends ComponentBaseDoc {
* `subComponentOf` field, which names the parent component.
*
* A sub-component owns its `description`, `props`, and (optionally) its own
- * `usage`. Family-level fields (`group`, `category`, `keywords`, `theming`,
- * `playground`) are inherited from the directory's primary doc unless
- * overridden here. The generated registry entry is identical to the legacy
- * inline `components[]` expansion — this is purely a file-structure change.
+ * `usage`. The CLI does not copy family-level fields (`group`, `category`,
+ * `keywords`, `theming`, `playground`) from the parent to an integration's
+ * sub-component: its detail, list group and search use only what its own doc
+ * sets. Set any the child needs in its own doc. The generated registry entry
+ * is identical to the legacy inline `components[]` expansion — this is purely
+ * a file-structure change.
*/
export interface SubComponentDoc extends Omit<ComponentBaseDoc, 'usage'> {
/** Name of the parent component this sub-component belongs to, matching the
* parent doc's `name` (e.g. `"Chat"`). Marks this file as a sub-component
- * doc so the pipeline parents and inherits family fields correctly. */
+ * doc. The CLI does not copy the parent's family fields to it. */
subComponentOf: string;
/** One-sentence description of what this sub-component does and its role
* within the parent composition. */
diff --git a/packages/cli/authoring/doctypes/enum/enum.doc.mjs b/packages/cli/authoring/doctypes/enum/enum.doc.mjs
index 2ba3d0eda3..905b76f56f 100644
--- a/packages/cli/authoring/doctypes/enum/enum.doc.mjs
+++ b/packages/cli/authoring/doctypes/enum/enum.doc.mjs
@@ -16,13 +16,15 @@ export const doc = {
description:
'The doc-type for a closed vocabulary: a fixed set of literal values such as ' +
'error codes or response-type discriminants. Colocated as a `.doc.mjs` next to ' +
- 'the source of truth it documents.',
+ 'the source of truth it documents. Only the CLI reads enum docs, from its own ' +
+ "source: one in an integration's docs directory fails to load, and so do that package's other docs.",
appliesTo: '<enum>.doc.mjs',
fields: [
{
name: 'type',
type: "'enum'",
- description: 'Doc-kind discriminant. Marks the file as an enum doc.',
+ description:
+ 'Doc-kind discriminant. Optional in the type, but the CLI reads a doc as an enum doc only when it is set; without it the doc drops out of the docs tree.',
},
{
name: 'name',
@@ -54,7 +56,8 @@ export const doc = {
{
name: 'aliases',
type: 'string[]',
- description: 'Alternate slugs that also resolve to this doc.',
+ description:
+ 'Reserved: alternate slugs for this doc. Nothing reads it today, so `astryx docs <alias>` does not open it.',
},
{
name: 'members',
@@ -91,7 +94,7 @@ export const doc = {
type: 'enum',
name: 'error-codes',
displayName: 'Error Codes',
- namespace: 'cli',
+ namespace: 'cli/api',
description: 'Stable error codes thrown by the CLI/API and surfaced in the JSON envelope.',
members: [
{value: 'ERR_UNKNOWN_TOPIC', description: 'The requested docs topic does not exist.'},
diff --git a/packages/cli/authoring/doctypes/function/function.doc.mjs b/packages/cli/authoring/doctypes/function/function.doc.mjs
index b2875622b5..450419cca1 100644
--- a/packages/cli/authoring/doctypes/function/function.doc.mjs
+++ b/packages/cli/authoring/doctypes/function/function.doc.mjs
@@ -18,7 +18,7 @@ export const doc = {
'functions. A hook (HookDoc) is the hook-flavored view of this same kind; FunctionDoc ' +
'adds the fields an API function needs (a {type, data} return envelope, thrown error ' +
'codes, the wrapping CLI command). The CLI binding itself lives in a separate CommandDoc.',
- appliesTo: 'api/<name>/<name>.doc.mjs',
+ appliesTo: 'api/<dir>/<name>.doc.mjs',
fields: [
{
name: 'type',
@@ -41,7 +41,7 @@ export const doc = {
name: 'kind',
type: "'hook' | 'api'",
description:
- 'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
+ "Which flavor. Nothing reads it today: no reader sections docs by it or infers it from `importPath`. The CLI's API function docs set 'api'.",
},
{
name: 'summary',
@@ -57,12 +57,13 @@ export const doc = {
name: 'namespace',
type: 'string',
description:
- "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`. Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+ "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`, the name in kebab case (`themeUse` is `theme-use`). Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
},
{
name: 'aliases',
type: 'string[]',
- description: 'Alternate slugs that also resolve to this doc.',
+ description:
+ 'Reserved: other names for this doc. Nothing reads it today, so they do not resolve to it.',
},
{
name: 'keywords',
@@ -231,11 +232,11 @@ export const doc = {
displayName: 'search()',
namespace: 'cli/api',
importPath: '@astryxdesign/cli/api',
- summary: 'Find components, hooks, docs, and templates by term.',
+ summary: 'Find components, hooks, docs, templates, and themes by term.',
signature: 'search(query, options?): Promise<SearchResponse>',
params: [
{name: 'query', type: 'string', description: 'The search term.', required: true},
- {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template'", description: 'Restrict results to one domain.'},
+ {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template' | 'theme'", description: 'Restrict results to one domain.'},
],
returns: [
{type: 'search', description: 'Envelope with the query and ranked results[].'},
@@ -253,11 +254,11 @@ export const doc = {
notes: [
{
type: 'prose',
- text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+ text: '`parseDoc` accepts a stamped function doc without `displayName` and does not check its `usage`, and the CLI reads its own function docs without checking them. Write to the type anyway; it is the contract.',
},
{
type: 'prose',
- text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",
+ text: "The `type` discriminant is 'function' for both flavors. `kind: 'hook'` or `kind: 'api'` names the flavor; nothing reads it today.",
},
{
type: 'prose',
diff --git a/packages/cli/authoring/doctypes/hook/hook.doc.mjs b/packages/cli/authoring/doctypes/hook/hook.doc.mjs
index 61e98ada6c..9b186ef01d 100644
--- a/packages/cli/authoring/doctypes/hook/hook.doc.mjs
+++ b/packages/cli/authoring/doctypes/hook/hook.doc.mjs
@@ -16,7 +16,8 @@ export const doc = {
'The doc-type for a standalone React hook (e.g. useMediaQuery, useFocusTrap, ' +
'useOverflow) that gets its own `.doc.mjs`. Hooks that are part of a component API ' +
"(e.g. useImperativeDialog) belong in that component's MultiComponentDoc `components` " +
- "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind.",
+ "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind. " +
+ "`astryx hook` reads Core's hook docs only; an integration lists its hooks in a component doc's `components` array.",
appliesTo: '{useX}.doc.mjs',
fields: [
{
@@ -195,14 +196,14 @@ export const docs = {
description:
'Subscribes to a CSS media query and re-renders when it changes. Use for responsive behavior that CSS alone cannot express, such as swapping components by breakpoint.',
},
- relatedHooks: ['useIsMobile'],
+ relatedHooks: ['useImageMode'],
};`,
},
],
notes: [
{
type: 'prose',
- text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+ text: '`parseDoc` accepts a stamped hook doc without `displayName` and does not check its `usage`, and `astryx hook` prints a hook doc without checking it at all. Write to the type anyway; it is the contract.',
},
{
type: 'prose',
@@ -210,7 +211,7 @@ export const docs = {
},
{
type: 'prose',
- text: "Only standalone hooks get their own file. A hook that is part of a component API is documented as an entry in that component's MultiComponentDoc `components` array (with `params`/`returns`), so it renders under the component.",
+ text: "A hook that is part of a component API is listed in that component's MultiComponentDoc `components` array: inline with `params`/`returns`, or by name with its own SubComponentDoc file, as Core's useTableSelection is.",
},
],
};
diff --git a/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs b/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs
index 799873edba..1cffdb8c63 100644
--- a/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs
+++ b/packages/cli/authoring/doctypes/namespace/namespace.doc.mjs
@@ -55,7 +55,8 @@ export const doc = {
{
name: 'audience',
type: "'public' | 'internal'",
- description: "Bundle audience. Defaults to 'public'.",
+ description:
+ "Reserved: bundle audience. Nothing reads it yet: a namespace that sets 'internal' still shows in `astryx docs`.",
default: "'public'",
},
{
@@ -67,7 +68,7 @@ export const doc = {
name: 'slots',
type: 'Record<string, NamespaceSlot>',
description:
- 'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
+ "Named placement and collection targets. Each slot declares a title and the doc kinds it accepts. `accepts.providers` is not read yet: only docs of the namespace's own package can be placed in a slot.",
required: true,
},
{
@@ -80,7 +81,7 @@ export const doc = {
name: 'blocks',
type: '(ReferenceContentBlock | GraphContentBlock)[]',
description:
- 'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. Not rendered yet: `astryx docs <route>` lists every slot and its children in order.',
+ 'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. `astryx docs <route>` prints the prose, heading, code, table, and list blocks above the slots, and `--json` returns every block with its links resolved. A collection block is not rendered yet, and `astryx doctor` warns on one.',
},
],
examples: [
@@ -100,7 +101,7 @@ export const docs = {
},
},
adopts: [{
- source: {group: 'cli-commands', kinds: ['command']},
+ source: {group: 'cli/commands', kinds: ['command']},
into: 'reference',
}],
};`,
@@ -109,11 +110,11 @@ export const docs = {
notes: [
{
type: 'prose',
- text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
+ text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc without a `placement` is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
},
{
type: 'prose',
- text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
+ text: 'Child docs request one canonical home with placement. A collection block refers to those docs by stable reference and never creates a second identity or parent. It is not rendered yet: `astryx doctor` warns on one.',
},
{
type: 'list',
diff --git a/packages/cli/authoring/doctypes/reference/reference.doc.mjs b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
index 8ca2852f86..be80a48497 100644
--- a/packages/cli/authoring/doctypes/reference/reference.doc.mjs
+++ b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
@@ -18,7 +18,8 @@ export const doc = {
'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
'built from ordered sections of mixed content blocks.',
- appliesTo: 'assets/docs/<topic>.doc.mjs',
+ appliesTo:
+ "<topic>.doc.{ts,mjs,js} in the folder the integration manifest's `docs` names",
fields: [
{
name: 'type',
@@ -69,7 +70,7 @@ export const doc = {
name: 'extends',
type: 'string',
description:
- "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
+ "Name of an existing topic this doc merges onto, section by section. A section replaces the base section with the same `id`, or else the one with exactly its title when either of the two has no `id`. A key derived from a title counts only against an `id`: a section without an `id` also matches a base section whose `id` is the key its title derives, and a section with an `id` also matches a base section without one whose title derives that `id`. Two different `id`s never match, two sections without an `id` whose titles differ only in case or punctuation stay separate, and a section that matches none is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
example: "'theme'",
},
{
@@ -83,7 +84,7 @@ export const doc = {
name: 'sections[].id',
type: 'string',
description:
- 'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+ 'Stable section anchor. New docs should set this instead of relying on a mutable title. Published @astryxdesign/cli 0.6.3 and earlier reject the field and hide every doc topic the package ships, so `astryx integration verify` fails an integration that sets one until it declares an `@astryxdesign/cli` peer of `>=0.6.4`.',
},
{
name: 'sections[].title',
@@ -109,7 +110,7 @@ export const doc = {
name: 'sections[].previewType',
type: 'ReferenceTokenPreviewType',
description:
- "Preview type for token tables in this section. When set, the docsite renders a visual preview column from the token's computed value. Omit for non-token sections.",
+ 'Preview type for token tables in this section. The CLI rejects a value not in the list below and returns the value in `astryx docs --json`, but draws no preview from it. Omit for non-token sections.',
},
],
},
@@ -117,17 +118,17 @@ export const doc = {
name: 'tokenCategory',
type: 'string',
description:
- "Token category for foundational docs that map to a token section (e.g. 'color'). Lets the tokens overview link to this doc for detailed guidance.",
+ "Token category for foundational docs that map to a token section (e.g. 'color'). `astryx docs --json` returns it as authored; no tokens page links to the doc through it.",
},
],
examples: [
{
label: 'A reference doc with one section',
code: `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
+export default {
type: 'generic',
- name: 'spacing',
- title: 'Spacing',
+ name: 'acme-spacing',
+ title: 'Acme Spacing',
description: 'Spacing tokens for gap, margin, and padding.',
category: 'foundations',
tokenCategory: 'spacing',
@@ -194,7 +195,7 @@ type ReferenceDocBlock = {
type GraphContentBlock =
| { type: 'workflow'; title?: string; steps: WorkflowStep[] }
- | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+ | { type: 'collection'; title?: string; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
| ReferenceDocBlock;`,
},
{
@@ -203,7 +204,7 @@ type GraphContentBlock =
},
{
type: 'prose',
- text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+ text: "A section may set `previewType`, a hint for previewing its token table, to one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'; the CLI rejects any other value.",
},
],
};
diff --git a/packages/cli/authoring/doctypes/schema/schema.doc.mjs b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
index 85171865ec..6784f6f57d 100644
--- a/packages/cli/authoring/doctypes/schema/schema.doc.mjs
+++ b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
@@ -55,7 +55,7 @@ export const doc = {
name: 'aliases',
type: 'string[]',
description:
- 'Alternate slugs that also resolve to this doc (back-compat).',
+ 'Reserved: alternate slugs for this doc. Nothing reads it yet: `astryx docs` finds a schema doc by its `name` only.',
},
{
name: 'appliesTo',
@@ -141,7 +141,7 @@ export const doc = {
name: 'notes',
type: 'ReferenceContentBlock[]',
description:
- 'Freeform prose/notes rendered after the field table. Same block union as ReferenceDoc (prose, heading, code, table, list, token-ref).',
+ 'Freeform prose/notes rendered after the field table and examples. The stable ReferenceContentBlock union (prose, heading, code, table, list, token-ref), without the reference block a ReferenceDoc section also takes; a token-ref note is accepted but not rendered.',
},
],
examples: [
@@ -152,17 +152,17 @@ export const doc = {
type: 'schema',
name: 'integration',
displayName: 'Astryx Integration',
- namespace: 'cli',
- description: 'The astryx.integration.* manifest that registers the components a package provides.',
+ namespace: 'authoring',
+ description: 'The astryx.integration.* manifest that points the CLI at what a package contributes.',
appliesTo: 'astryx.integration.{ts,mjs,js}',
fields: [
- {name: 'name', type: 'string', description: 'Package name.', required: true},
+ {name: 'docs', type: 'string', description: 'The folder that holds your doc topics, relative to package.json.'},
{
- name: 'components',
- type: '{ dir: string }',
- description: 'Where component sources live.',
+ name: 'agentDocs',
+ type: '{ append?: readonly string[] }',
+ description: 'Guidance your package adds to the agent instructions the CLI manages.',
fields: [
- {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
+ {name: 'agentDocs.append', type: 'readonly string[]', description: 'Lines added at the end, at most eight.'},
],
},
],
diff --git a/packages/cli/authoring/doctypes/template/template.doc.mjs b/packages/cli/authoring/doctypes/template/template.doc.mjs
index df95f19b6b..acc49b3ae7 100644
--- a/packages/cli/authoring/doctypes/template/template.doc.mjs
+++ b/packages/cli/authoring/doctypes/template/template.doc.mjs
@@ -31,14 +31,14 @@ export const doc = {
name: 'name',
type: 'string',
description:
- 'Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path.',
+ "Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label in the gallery. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path. `astryx template --list` and `astryx search` print `name` as the label of both, and `astryx template <id>` finds a template by its id, never by `name`: an integration template's id is its path under the templates folder without the `.doc.*` suffix.",
required: true,
},
{
name: 'displayName',
type: 'string',
description:
- "Human-readable label for the gallery/CLI. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
+ "Human-readable label for the gallery. The CLI prints `name` instead; `astryx template --list --json` also returns an integration template's `displayName`. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
required: true,
},
{
diff --git a/packages/cli/authoring/doctypes/theme/theme.doc.mjs b/packages/cli/authoring/doctypes/theme/theme.doc.mjs
index 4a4dad3d02..ceab72fbb6 100644
--- a/packages/cli/authoring/doctypes/theme/theme.doc.mjs
+++ b/packages/cli/authoring/doctypes/theme/theme.doc.mjs
@@ -12,7 +12,7 @@ export const doc = {
displayName: 'ThemeDoc',
namespace: 'authoring',
description:
- 'The strongly typed descriptor for one integration or CLI-bundled source theme.',
+ "The strongly typed descriptor for one source theme: bundled with the CLI, shipped by an integration, or kept in the project's src/themes, where `theme eject` writes one.",
appliesTo: '<theme-source-stem>.doc.mjs',
fields: [
{
@@ -65,7 +65,7 @@ export default {
notes: [
{
type: 'prose',
- text: 'ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.',
+ text: "ThemeDoc is static metadata. The descriptor holds one default-exported object of literal string and boolean fields, directly under a `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */` comment, and nothing else: without that comment, or with any other statement, it fails to load. Discovery validates it without executing the descriptor or theme source.",
},
{
type: 'prose',
diff --git a/packages/cli/authoring/gap-report/gap-report.doc.mjs b/packages/cli/authoring/gap-report/gap-report.doc.mjs
index 387f520157..f1f57e8b52 100644
--- a/packages/cli/authoring/gap-report/gap-report.doc.mjs
+++ b/packages/cli/authoring/gap-report/gap-report.doc.mjs
@@ -15,7 +15,7 @@ export const doc = {
displayName: 'GapReportHandler',
namespace: 'authoring',
description:
- 'A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.',
+ "A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Handlers add up rather than replace each other: the project handler first, then each loaded integration's in load order (the `integrations` list, then autolinked ones), whichever package the report is about.",
appliesTo:
'`gapReport` in astryx.config.*, or the `gapReport` named export of astryx.integration.*',
fields: [
@@ -104,7 +104,7 @@ export const doc = {
name: 'report.target.version',
type: 'string',
description:
- 'The installed version. Null when it is not known.',
+ "The integration's version from its package.json. Null for Core, and when the package.json has none.",
required: true,
},
{
diff --git a/packages/cli/authoring/identity/identity.doc.mjs b/packages/cli/authoring/identity/identity.doc.mjs
index 69d95ecb64..2f7b5809c0 100644
--- a/packages/cli/authoring/identity/identity.doc.mjs
+++ b/packages/cli/authoring/identity/identity.doc.mjs
@@ -12,7 +12,7 @@ export const doc = {
displayName: 'Provider and artifact identity',
namespace: 'authoring',
description:
- 'Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI\'s own docs. Artifact, instance, and compiler-input identities are defined for every provider-owned artifact; no command reads them.',
+ "Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI's docs and each integration's. Artifact IDs for kinds outside the docs tree, provider instances, and compiler-input entries are defined for every provider-owned artifact; no command builds them.",
appliesTo:
'Integration manifests, provider conflicts, and docs-tree node ids.',
fields: [
@@ -41,14 +41,14 @@ export const doc = {
name: 'ProviderInstance',
type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
description:
- 'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+ 'One immutable package version and source/content digest. It carries no installed, configured, loaded, selected, or healthy state.',
required: true,
},
{
name: 'AuthoredDocEntry',
type: '{ id; provider; kind; stableName; source; authored }',
description:
- 'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+ 'Normalized compiler input. `stableName`, the key in its doc ID, is given separately from the authored display name; source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
required: true,
},
],
diff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjs
index cee056ea0b..f243492bdd 100644
--- a/packages/cli/authoring/integration/integration.doc.mjs
+++ b/packages/cli/authoring/integration/integration.doc.mjs
@@ -51,7 +51,7 @@ export const doc = {
name: 'docs',
type: 'string',
description:
- 'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
+ 'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} under it shows up in `astryx docs`: a flat topic next to the built-in topics, where it can set `replaces` or `extends` to take over a built-in topic or add to it, and a guide with `placement` at its own route in the docs tree, under a namespace doc of the same package.',
example: "'./docs'",
},
{
@@ -71,7 +71,8 @@ export const doc = {
{
name: 'issuesUrl',
type: 'string',
- description: 'Where to file issues/feedback for this integration.',
+ description:
+ "Where people file issues for this package: an absolute URL, such as its GitHub issues page. A value that is not a URL fails the whole manifest; the scheme is not checked. Nothing warns when it is missing, but without it `astryx gap-report` about this package fails unless the project or a loaded integration has a gapReport handler, and `astryx swizzle` prints no feedback link for this package's components. When no handler is loaded, a github.com issues URL is filed with the GitHub CLI once the reporter passes `--confirm-public`; any other URL is returned for the reporter to open.",
example: "'https://github.com/acme/widgets/issues'",
},
{
@@ -118,7 +119,7 @@ export const doc = {
},
{
type: 'prose',
- text: 'A themes root is forward-compatible but version-gated: a CLI released before this field ignores it with a warning and continues loading every contribution kind it understands. That older CLI cannot list or add the contributed themes.',
+ text: 'A themes root is version-gated: an older CLI lists and adds none of its themes. Depending on its age, that CLI ignores `themes` with an `unknown_manifest_key` warning and loads every other contribution kind, reports the root as invalid because it expects the earlier `manifest.json` theme catalog, or, if it is old enough to treat an unknown field as an error, rejects the whole manifest, so the package contributes nothing there.',
},
{
type: 'prose',
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.mjs b/packages/cli/foundation/discovery/authoring-self-docs.mjs
index a9bb90060d..61afe85076 100644
--- a/packages/cli/foundation/discovery/authoring-self-docs.mjs
+++ b/packages/cli/foundation/discovery/authoring-self-docs.mjs
@@ -193,7 +193,7 @@ export function buildAuthoringReferenceDoc(docs) {
title: 'Authoring Reference',
category: 'guide',
description:
- 'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+ 'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
sections: docs.map(selfDocSection),
});
}