@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/assets/docs/tree/define-the-theme.doc.mjs

@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/define-the-theme`:
+ * map the palette to tokens, keep light-dark() to colors, and avoid Core internals.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'define-the-theme',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 30},
+  title: 'Define the theme',
+  category: 'guide',
+  description:
+    'Point theme tokens at the palette, keep light-dark() to colors, and avoid Core internals.',
+  sections: [
+    {
+      id: 'map-the-palette-to-tokens',
+      title: 'Map the palette to tokens',
+      content: [
+        {
+          type: 'prose',
+          text: 'A theme token is a named slot that Astryx components read for a value — `--color-accent` for the accent color, and so on. Components never read your palette directly; they read tokens. Defining a theme means pointing each token at a palette shade, so the components wear your colors.',
+        },
+        {
+          type: 'prose',
+          text: 'Import the palette in `oceanTheme.ts` and point your tokens at its stops. Each token takes a `[light, dark]` pair — the shade to use in light mode and the one in dark mode.',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          code: `// themes/ocean/oceanTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {palette} from './tokens/ocean.palette';
+
+const {light, dark} = palette.ocean;
+
+export const oceanTheme = defineTheme({
+  name: 'ocean',
+  tokens: {
+    '--color-accent': [light['45'], dark['70']],
+  },
+});`,
+        },
+        {
+          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:theme}.',
+        },
+      ],
+    },
+    {
+      id: 'build-on-another-theme',
+      title: 'Build on another theme',
+      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}).',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          code: `import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from './oceanTheme';
+
+export const oceanContrastTheme = defineTheme({
+  name: 'ocean-contrast',
+  extends: oceanTheme,
+  tokens: {
+    '--color-accent': ['#0051a3', '#4aa3ff'],
+  },
+});`,
+        },
+      ],
+    },
+    {
+      id: 'keep-light-dark-to-colors',
+      title: 'Keep light-dark() to colors',
+      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.',
+        },
+      ],
+    },
+    {
+      id: 'avoid-core-internals',
+      title: 'Do not set Core private variables',
+      content: [
+        {
+          type: 'prose',
+          text: 'Core private variables start with `--_`, such as `--_field-radius`. They are internals and can change in any Core release, so `theme build` reports each one it finds as an `[error]`. Set the standard CSS property instead — `borderRadius`, `padding` — and let the build emit the internal variable where Core needs it.',
+        },
+      ],
+    },
+    {
+      id: 'declare-the-peers',
+      title: 'Declare the peer dependencies',
+      content: [
+        {
+          type: 'prose',
+          text: 'The theme imports `@astryxdesign/core/theme`, so declare Core as a peer dependency, with the range of Core versions you test the theme against — a range, not an exact version, so a Core patch release does not force a republish. `integration add theme` already declared the optional `@astryxdesign/cli` peer that reads themes:',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: `"peerDependencies": {
+  "@astryxdesign/core": "^0.7.0",
+  "@astryxdesign/cli": ">=0.7.0"
+},
+"peerDependenciesMeta": {
+  "@astryxdesign/cli": {"optional": true}
+}`,
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/describe-the-component.doc.mjs

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * choose and maintain the ComponentDoc shape that matches a component's public
+ * source.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'describe-the-component',
+  placement: {parent: 'namespace:components', slot: 'guides', order: 20},
+  title: 'Describe the component',
+  summary:
+    'Write and maintain the default component doc, then adapt it when one family owns several exports or a member needs its own file.',
+  keywords: [
+    'component doc',
+    'component documentation',
+    'component family',
+    'subcomponent',
+  ],
+  slots: {
+    guides: {
+      title: 'Describe the component',
+      accepts: {kinds: ['generic']},
+    },
+  },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'A component\'s `.doc.mjs` is part of the integration\'s public contract, not optional commentary. Astryx uses it for CLI output and search, and people and agents read it to decide whether the component fits and how to use it.',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'Change the source and its `.doc.mjs` together.',
+        'Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.',
+        '`integration verify` checks the doc shape and packed import, but it cannot prove the prose still matches the component.',
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'Every component doc has one stable identity and enough usage guidance for a reader to choose it correctly. Pick the shape below that matches your module.',
+    },
+    {
+      type: 'prose',
+      text: 'After every source or doc change, read the component back. This output is what people and agents receive.',
+    },
+    {
+      type: 'code',
+      lang: 'bash',
+      code: 'npx astryx component AcmeCarousel',
+    },
+  ],
+};

package/assets/docs/tree/docs.doc.mjs

@@ -0,0 +1,21 @@
+// 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).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'docs',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 40},
+  title: 'Docs',
+  summary:
+    'Write docs that ship with your package and that people and agents find by search or one level at a time.',
+  keywords: ['writing docs', 'doc topic', 'docs section', 'placement', 'links'],
+  slots: {
+    guides: {title: 'Guides', accepts: {kinds: ['generic']}},
+  },
+};

package/assets/docs/tree/document-the-template.doc.mjs

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template`:
+ * document page and block templates for discovery and correct reuse.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'document-the-template',
+  placement: {parent: 'namespace:templates', slot: 'build', order: 20},
+  title: 'Document the template',
+  summary:
+    'Write the doc that helps people and agents find, choose, and trust your template: its name, description, readiness, preview, and any Core replacement.',
+  keywords: [
+    'template doc',
+    'template documentation',
+    'page template',
+    'block template',
+  ],
+  slots: {
+    guides: {
+      title: 'Guides',
+      accepts: {kinds: ['generic']},
+    },
+  },
+};

package/assets/docs/tree/document-the-theme.doc.mjs

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/document-the-theme`:
+ * document a theme by extending the core theme topic, not in agent guidance.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'document-the-theme',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 50},
+  title: 'Document the theme',
+  category: 'guide',
+  description:
+    'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.',
+  sections: [
+    {
+      id: 'extend-the-theme-topic',
+      title: 'Extend the core theme topic',
+      content: [
+        {
+          type: 'prose',
+          text: 'Give your theme a doc topic that extends the core `theme` topic, so an app that lists your package sees your theme at the end of `astryx docs theme`. Add it with `extends: \'theme\'` ({@link generic:extend-or-replace}).',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: `// docs/ocean-theme.doc.mjs
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'ocean-theme',
+  extends: 'theme',
+  title: 'Ocean theme',
+  description: 'Use the Ocean theme from @acme/astryx-widgets.',
+  sections: [
+    {
+      id: 'use-the-ocean-theme',
+      title: 'Use the Ocean theme',
+      content: [
+        {
+          type: 'prose',
+          text: "Add \`@acme/astryx-widgets\` to the app's dependencies and apply the Ocean theme with \`<Theme theme={oceanTheme}>\`.",
+        },
+      ],
+    },
+  ],
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'Keep the section short: how to add the package, apply the theme ({@link generic:use-a-theme-in-an-app}), and — if the theme uses a custom font — which fonts the app must load ({@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.',
+        },
+      ],
+    },
+    {
+      id: 'not-agent-guidance',
+      title: 'Not agent guidance',
+      content: [
+        {
+          type: 'prose',
+          text: 'Do not put theme usage in `agentDocs`. Agent lines land in every app\'s agent file and are for guidance needed every session; a theme\'s install-and-use steps belong in a doc topic that people and agents read on demand. See {@link generic:agent-guidance}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/export-template-assets.doc.mjs

@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets`:
+ * expose and include everything a copied template imports, and declare the
+ * packages it needs.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'export-template-assets',
+  placement: {
+    parent: 'namespace:package-and-test',
+    slot: 'guides',
+    order: 10,
+  },
+  title: 'Export the template and assets',
+  category: 'guide',
+  description:
+    'Make sure the published package contains and exposes everything the copied template imports.',
+  sections: [
+    {
+      id: 'keep-the-generated-template-export',
+      title: 'Keep the generated template export',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration verify` resolves each template through a public package path without a file extension, such as `./templates/acme-dashboard`, and fails when that path is missing.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `{
+  "exports": {
+    "./templates/acme-dashboard": "./templates/acme-dashboard.tsx"
+  }
+}`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`integration add` writes this entry when `package.json` has an `exports` map ({@link generic:start-a-template}). Without a map it writes nothing, because creating one would make existing deep imports private. Add the map yourself, then the entry.',
+            'Keep the public path without `.tsx`. Only the target file ends in `.tsx`.',
+            'Do not point the entry at a barrel file that loses the template default export.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'export-package-owned-support-files',
+      title: 'Export package-owned support files',
+      content: [
+        {
+          type: 'prose',
+          text: 'Add a public path for every package-owned component, helper, icon, or stylesheet that the copied source imports. Keep implementation-only files private.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'Relevant package.json entries',
+          code: `{
+  "exports": {
+    "./templates/acme-dashboard": "./templates/acme-dashboard.tsx",
+    "./components/AcmeStatusCard": "./components/AcmeStatusCard.tsx",
+    "./icons/AcmePulseIcon": "./icons/AcmePulseIcon.tsx",
+    "./styles/acme-dashboard.css": "./styles/acme-dashboard.css"
+  }
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'If a block is also loaded directly as a live `.tsx` preview, add a pattern that keeps the extension, such as `"./templates/*.tsx": "./templates/*.tsx"`. Keep the generated entry too; `integration verify` resolves the template through it.',
+        },
+      ],
+    },
+    {
+      id: 'include-every-file',
+      title: 'Include every file',
+      content: [
+        {
+          type: 'prose',
+          text: 'An export can point to a file that npm leaves out. When `package.json#files` exists, list the integration manifest, the templates directory, and every directory the copied file depends on.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `{
+  "files": [
+    "astryx.integration.mjs",
+    "templates",
+    "components",
+    "icons",
+    "styles",
+    "assets/fonts"
+  ],
+  "sideEffects": ["**/*.css"]
+}`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`integration add` appends the manifest and templates directory when a `files` list already exists. Add the other directories yourself.',
+            'If `package.json` sets `sideEffects`, include CSS in it, as above, so bundlers keep side-effect stylesheet imports.',
+            'Run `npm pack --dry-run` and read the real file list instead of reasoning from the workspace.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'declare-what-the-copied-file-imports',
+      title: 'Declare what the copied file imports',
+      content: [
+        {
+          type: 'prose',
+          text: 'A copied file imports from the app, so the app must install every package it imports. Declare the Astryx peers as described in {@link generic:versioning}. For other packages:',
+        },
+        {
+          type: 'table',
+          headers: ['Field', 'Use it for'],
+          rows: [
+            [
+              '`peerDependencies`',
+              'Libraries the copied source imports, such as an icon library. List them in `devDependencies` too, so the package itself builds.',
+            ],
+            [
+              '`dependencies`',
+              'Runtime packages used only by package-owned modules, which should travel with the integration',
+            ],
+            [
+              '`devDependencies`',
+              'Everything needed to build and test the integration itself',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Use only ranges you test. A package that resolves only because a workspace hoisted it is not declared.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/extend-or-replace.doc.mjs

@@ -0,0 +1,103 @@
+// 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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'extend-or-replace',
+  placement: {parent: 'namespace:docs', slot: 'guides', order: 40},
+  title: 'Extend or replace a topic',
+  category: 'guide',
+  description: 'Take over a topic, or merge sections into it.',
+  sections: [
+    {
+      id: 'replace-a-topic',
+      title: 'Replace a topic',
+      content: [
+        {
+          type: 'prose',
+          text: "Set `replaces` to take over an existing topic, such as Core's `getting-started`. Readers who open the old name get your topic.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add doc acme-getting-started --replaces getting-started\n# The old name now opens your topic\nnpx astryx docs getting-started',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/acme-getting-started.doc.mjs',
+          code: "export default {\n  type: 'generic',\n  name: 'acme-getting-started',\n  replaces: 'getting-started',\n  title: 'Acme getting started',\n  description: 'Install Acme widgets and render your first carousel.',\n  sections: [/* ... */],\n};",
+        },
+        {
+          type: 'prose',
+          text: 'The docs list shows your topic in place of the old one. Because your topic has its own `name`, the old name keeps resolving to it, so links and agents that learned the old name still land on your topic.',
+        },
+      ],
+    },
+    {
+      id: 'extend-a-topic',
+      title: 'Extend a topic',
+      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.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add doc acme-theming --extends theme\nnpx astryx docs theme --index',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/acme-theming.doc.mjs',
+          code: "export default {\n  type: 'generic',\n  name: 'acme-theming',\n  extends: 'theme',\n  title: 'Acme theming',\n  description: 'Theme an app that uses Acme widgets.',\n  sections: [\n    {id: 'quick-start', title: 'Quick Start', content: [/* replaces the base section */]},\n    {id: 'use-the-ocean-theme', title: 'Use the ocean theme', content: [/* added at the end */]},\n  ],\n};",
+        },
+        {
+          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`.",
+            "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.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'check-overlaps-with-core-topics',
+      title: 'Check overlaps with Core topics',
+      content: [
+        {
+          type: 'prose',
+          text: "A topic sets `replaces` or `extends`, never both, and a placed guide sets neither. A topic that uses a Core topic's name with neither is an accidental conflict: apps keep reading the Core topic.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration 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.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'An intentional overlap prints as `[info]`. An accidental one fails with exit code 1.',
+            'A topic that sets both fails as `invalid_doc`, and so does a placed guide that sets either one.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/fonts-and-assets.doc.mjs

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * name a theme's fonts, and have the app load them (Astryx never loads a font).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'fonts-and-assets',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 35},
+  title: 'Fonts',
+  category: 'guide',
+  description:
+    'Name your theme\'s fonts in its tokens, then have the app load them — Astryx never loads a font file.',
+  sections: [
+    {
+      id: 'name-the-font',
+      title: 'Name the font',
+      content: [
+        {
+          type: 'prose',
+          text: 'A theme names its typefaces in `typography`: `body`, `heading`, and `code`, each with a `family` and `fallbacks`. These set the `--font-family-*` tokens every component reads. Always give real `fallbacks` so text stays readable before the font loads, or if it never does. `heading` inherits `family` and `fallbacks` from `body` when you omit them.',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          code: `// themes/ocean/oceanTheme.ts
+export const oceanTheme = defineTheme({
+  name: 'ocean',
+  typography: {
+    body: {family: 'Acme Sans', fallbacks: 'system-ui, sans-serif'},
+    code: {family: 'Acme Mono', fallbacks: 'ui-monospace, monospace'},
+  },
+  // ...your tokens
+});`,
+        },
+        {
+          type: 'prose',
+          text: 'The full type scale and font roles are in {@link generic:theme}.',
+        },
+      ],
+    },
+    {
+      id: 'load-the-font-in-the-app',
+      title: 'Load the font in the app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Naming a family does not load it — Astryx never downloads a font file. The app that uses your theme loads the font itself, so your job is to tell your users which families and weights to load, in your theme\'s docs ({@link generic:document-the-theme}). An app loads a font one of two ways:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Link a hosted stylesheet in the app\'s `<head>` — for example a Google Fonts `<link>` covering every weight the UI uses.',
+            'Self-host: serve the font files and add an `@font-face` for each weight and style to the app\'s global CSS.',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          code: `/* In the app's global CSS, when self-hosting */
+@font-face {
+  font-family: 'Acme Sans';
+  src: url('/fonts/acme-sans.woff2') format('woff2');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
+}`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic — include the italic face, with the same `unicode-range`s as the roman.',
+            'Set a `unicode-range` per face so the browser downloads only the subsets it needs.',
+            'Use `font-display: swap` unless a measured need justifies another value.',
+            'Serve WOFF2; add another format only when a target browser needs it.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'verify-in-an-app',
+      title: 'Verify in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Before publishing, install the package in a clean app, apply the theme, load the fonts, and open it in a browser. The source and the applied result are not the same thing until you look.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Text renders in the named families at every weight and style — the italic face resolves, not a synthesized slant.',
+            'Every font request succeeds; nothing silently falls back to a system font.',
+            'Color pairs still meet contrast in both light and dark mode.',
+          ],
+        },
+      ],
+    },
+  ],
+};