@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app`:
+ * an app installs the integration and applies or extends the theme, like any theme.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'use-a-theme-in-an-app',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 40},
+  title: 'Use and extend the theme',
+  category: 'guide',
+  description:
+    'An app installs the integration and applies or extends your theme, the same as any theme.',
+  sections: [
+    {
+      id: 'apply-the-theme',
+      title: 'Apply the theme',
+      content: [
+        {
+          type: 'prose',
+          text: 'An app installs the integration as a dependency and applies your theme like any Astryx theme: wrap the app in `<Theme>`. The theme comes from the installed package — there is no copy step. Your theme only names its fonts; the app loads them ({@link generic:fonts-and-assets}).',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          code: `import {Theme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
+
+<Theme theme={oceanTheme}>{/* app */}</Theme>`,
+        },
+        {
+          type: 'prose',
+          text: 'The import specifier is whatever your integration exports for the theme. Applying a theme — `mode`, SSR, and the production build — works the same for every theme; see {@link generic:theme}.',
+        },
+      ],
+    },
+    {
+      id: 'extend-the-theme',
+      title: 'Extend to customize',
+      content: [
+        {
+          type: 'prose',
+          text: 'To change a theme, an app does not copy it — it derives a new one with `extends`: import your theme and override only the tokens it changes. See {@link generic:define-the-theme}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/verify-packed-template.doc.mjs

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template`:
+ * what `integration verify` checks for templates, and what it leaves to the
+ * app test.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'verify-packed-template',
+  placement: {
+    parent: 'namespace:package-and-test',
+    slot: 'guides',
+    order: 20,
+  },
+  title: 'Verify the packed package',
+  category: 'guide',
+  description:
+    'Catch missing files, exports, and CLI requirements before you publish, and know what still needs the app test.',
+  sections: [
+    {
+      id: 'run-the-package-check',
+      title: 'Run the package check',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration verify',
+        },
+        {
+          type: 'prose',
+          text: '`integration verify` runs `npm pack`, including lifecycle scripts, unpacks the `.tgz` file into a temporary app without installing its dependencies, and checks the unpacked integration. It publishes nothing and removes the `.tgz` file and the temporary app.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'It validates the manifest, every template doc, its source file, and the templates directory.',
+            'It checks that the manifest and every template file are in the `.tgz` file.',
+            'It checks that each packed template keeps the same id, type, `name`, and `replaces` as your working copy. It does not compare template source or other doc fields.',
+            'It resolves each template through its public package path in the unpacked package.',
+            'It checks that the resolved template module has a default export.',
+            'It checks the CLI peer that features such as template replacement require.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Each failure prints a `[fail]` line with its message; add `--json` to see each issue code. {@link generic:troubleshooting} lists the common messages and their fixes. Fix every error, and review every warning before publishing.',
+        },
+      ],
+    },
+    {
+      id: 'know-what-it-does-not-prove',
+      title: 'Know what it does not prove',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration verify` checks the packed templates and their public entrypoints. It does not copy a template into an app or run a browser build, so it cannot show the following.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Whether a relative helper or stylesheet survives the copy.',
+            'Whether the copied file type-checks in every supported app toolchain.',
+            'Whether package-owned CSS, fonts, icons, images, or media load in a browser.',
+            'Whether layout, color modes, keyboard and pointer input, and real content work.',
+            'Whether a template id collides with Core, or whether a `replaces` target exists. Run `npx astryx doctor integration templates` for those.',
+            'How the template scores on quality.',
+          ],
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'versioning',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 30},
+  title: 'Versioning',
+  category: 'guide',
+  keywords: ['peer dependency', 'semver', 'cli version'],
+  description:
+    'Version your package, declare its peers, and keep apps on older CLIs working.',
+  sections: [
+    {
+      id: 'pick-a-version',
+      title: 'Pick a version',
+      content: [
+        {
+          type: 'prose',
+          text: 'Version your package with semver: a major version for a breaking change, a minor version for a new feature, and a patch for a fix.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# 1.0.0 -> 2.0.0: a breaking change\nnpm version major\n# 1.0.0 -> 1.1.0: a new feature\nnpm version minor\n# 1.0.0 -> 1.0.1: a fix\nnpm version patch',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Before 1.0.0, npm treats each minor version as breaking: an app that asks for `^0.6.0` never gets `0.7.0`. Bump the minor version for a breaking change, and the patch for anything else.',
+            'Ship a codemod with each breaking change so apps can migrate; see {@link generic:codemods}.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'know-what-breaks-apps',
+      title: 'Know what breaks apps',
+      content: [
+        {
+          type: 'prose',
+          text: 'A breaking change stops code, commands, or links that worked in an app from working after the upgrade. For an integration, these names are part of its API.',
+        },
+        {
+          type: 'table',
+          headers: ['You change or remove', 'What stops working in the app'],
+          rows: [
+            [
+              'A component name, such as `AcmeCarousel`',
+              'Imports, and `npx astryx component AcmeCarousel`',
+            ],
+            [
+              'A template id, such as `acme-dashboard`',
+              '`npx astryx template acme-dashboard`',
+            ],
+            ['A theme slug, such as `ocean`', '`npx astryx theme add ocean`'],
+            [
+              'A topic name or route, such as `acme/deploying`',
+              'Reads of the old name, and links to it from other docs',
+            ],
+            [
+              "A component's `import` path",
+              'Imports written from the old path',
+            ],
+            [
+              'An `exports` entry',
+              'Imports of that path, which fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`',
+            ],
+            ['A prop', 'Code that passes it'],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'List each breaking change in your release notes, with the codemod that migrates it. Any changelog tool works. If `package.json` has a `files` allowlist, add `CHANGELOG.md` to it so npm packs it.',
+        },
+      ],
+    },
+    {
+      id: 'declare-peer-ranges',
+      title: 'Declare peer ranges',
+      content: [
+        {
+          type: 'prose',
+          text: 'Declare the Astryx packages that your code imports as peer dependencies, in `peerDependencies`, so the app installs one copy of each. Keep each range as wide as your tests prove.',
+        },
+        {
+          type: 'table',
+          headers: ['Peer', 'Declare it when', 'Range'],
+          rows: [
+            [
+              '`@astryxdesign/core`',
+              'Your code imports Core, as a theme does with `@astryxdesign/core/theme`',
+              'The Core versions you test, such as `^0.6.0`',
+            ],
+            [
+              '`@astryxdesign/theme-*`',
+              'Your code imports that theme package',
+              'The versions you test',
+            ],
+            [
+              '`@astryxdesign/cli`',
+              'You ship a docs section, a placed guide, a template that sets `replaces`, a doc section with an `id`, or a theme',
+              '`>=0.7.0`, optional in `peerDependenciesMeta`',
+            ],
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{\n  "peerDependencies": {\n    "@astryxdesign/core": "^0.6.0",\n    "@astryxdesign/cli": ">=0.7.0"\n  },\n  "peerDependenciesMeta": {\n    "@astryxdesign/cli": {"optional": true}\n  }\n}',
+        },
+        {
+          type: 'prose',
+          text: '`integration verify` fails a package that needs the CLI peer and lacks it, or whose range admits a stable CLI before 0.7.0. `integration add doc --parent` and `integration add theme` write the peer for you.',
+        },
+      ],
+    },
+    {
+      id: 'support-older-clis',
+      title: 'Support older CLIs',
+      content: [
+        {
+          type: 'prose',
+          text: 'An app may run an older CLI than the one you build with. A CLI reads what it knows and skips the rest, but some newer files make an older CLI hide your docs.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          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.',
+            'A stable CLI before 0.7.0 cannot read a docs section, a section `id`, a template that sets `replaces`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
+            'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: '`integration verify` requires the CLI peer for a docs section, a placed guide, a template `replaces`, a doc section with an `id`, and a theme. A stable CLI before 0.7.0 cannot read any of them, and when it hides your topics, `docs` gives no warning.',
+        },
+      ],
+    },
+    {
+      id: 'codemods-and-versions',
+      title: 'Name codemod folders after Core versions',
+      content: [
+        {
+          type: 'prose',
+          text: 'Name each codemod folder after the Core version whose upgrade should run it, not after your package\'s version. Which folders an app runs, and when, is in "Choose when a codemod runs" in {@link generic:codemods}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/write-good-templates.doc.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates`:
+ * what makes a template good, the rubric that scores it, and grading with an agent.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'write-good-templates',
+  placement: {parent: 'namespace:templates', slot: 'quality', order: 10},
+  title: 'How to write good templates',
+  summary:
+    'Write templates people trust: what good means, the rubric that scores it, and how to grade one with an agent.',
+  keywords: [
+    'template quality',
+    'template rubric',
+    'grade template',
+    'template review',
+  ],
+  blocks: [
+    {
+      type: 'prose',
+      text: 'A good template does more than render. It gives an app a clear product starting point that is easy to understand, safe to change, and complete after Astryx copies it out of the package. A rubric scores that quality so you can grade as you build.',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'Its purpose and primary task are clear before someone reads every detail.',
+        'It composes Astryx components instead of rebuilding their behavior with raw HTML or custom styles.',
+        'Its hierarchy, spacing, interactions, and reading order still work at narrow widths and in every supported color mode.',
+        'Its source, imports, styles, fonts, icons, images, and media still work from the copied location.',
+        'Its metadata makes the template easy to find and accurately explains when to use it.',
+        'Its example content is realistic enough to expose overflow, empty-space, and hierarchy problems.',
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'Grade the first runnable version, again after each source, doc, dependency, or asset change, and in full before every release. Grade the source, doc, copied file, and rendered app together; none of them is enough alone.',
+    },
+    {
+      type: 'list',
+      style: 'ordered',
+      items: [
+        'Read every scoring rule in {@link generic:template-grading-rubric}.',
+        'Fix publication blockers first, then every reasonable deduction.',
+        'Repeat the full grade on the packed package in a clean app ({@link generic:test-template-in-app}).',
+        'To have an agent grade and improve the template, use {@link generic:grade-template-with-agent}.',
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'Keep each scorecard with its package revision and rubric version.',
+    },
+  ],
+  slots: {
+    guides: {
+      title: 'Guides',
+      accepts: {kinds: ['generic']},
+    },
+  },
+};

package/assets/docs/tree/write-the-template-file.doc.mjs

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'write-the-template-file',
+  placement: {
+    parent: 'namespace:build-the-template',
+    slot: 'guides',
+    order: 10,
+  },
+  title: 'Write the template file',
+  category: 'guide',
+  description:
+    'Astryx copies just this one file into an app, so write it to work on its own there: where it lands, what it can import, and what it exports.',
+  sections: [
+    {
+      id: 'know-what-gets-copied',
+      title: 'Know what gets copied',
+      content: [
+        {
+          type: 'prose',
+          text: '`astryx template` copies exactly one source file. It does not copy sibling helpers, stylesheets, fonts, icons, images, or media. Plan for that before you add supporting files.',
+        },
+        {
+          type: 'table',
+          headers: ['Template', 'Directory target', 'Explicit file target'],
+          rows: [
+            ['Page', 'Writes `<target>/page.tsx`', 'Writes the exact file path'],
+            [
+              'Block',
+              'Writes `<target>/<source-basename>.tsx`',
+              'Writes the exact file path',
+            ],
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Page: src/app/account/page.tsx
+npx astryx template acme-account src/app/account
+
+# Block: src/features/account/acme-stat-card.tsx
+npx astryx template acme-stat-card src/features/account
+
+# Exact destination for either kind
+npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
+        },
+        {
+          type: 'prose',
+          text: 'Astryx refuses to replace an existing file unless the caller passes `--overwrite` or `-f`.',
+        },
+      ],
+    },
+    {
+      id: 'keep-edited-code-in-one-file',
+      title: 'Keep edited code in one file',
+      content: [
+        {
+          type: 'prose',
+          text: 'Put every helper that the app is expected to edit in the template source. Small local components, example data, constants, and event handlers can live above or below the default component in the same file.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Inline a helper when it is part of the editable starting point.',
+            'Move a helper into the integration package only when it should stay package-owned and update with the package.',
+            'Do not import `./helper`, `./styles`, or any other sibling file.',
+            'Do not create routes, configuration, or extra files at runtime. Give the app one explicit source file to own.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'use-imports-that-work',
+      title: 'Use imports that work in the app',
+      content: [
+        {
+          type: 'prose',
+          text: 'After the copy, imports resolve from the app, not from the template directory. Every bare import must name a package the app installs, and every package path must be public.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          code: `import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
+
+const metrics = [
+  {label: 'Healthy accounts', value: '1,248'},
+  {label: 'Needs review', value: '37'},
+];
+
+function MetricRow({label, value}: {label: string; value: string}) {
+  return (
+    <HStack justify="between">
+      <Text>{label}</Text>
+      <Text>{value}</Text>
+    </HStack>
+  );
+}
+
+export default function AcmeAccountSummary() {
+  return (
+    <Card>
+      <VStack gap={4}>
+        <AcmeStatusCard />
+        {metrics.map(metric => <MetricRow key={metric.label} {...metric} />)}
+        <Button label="Review accounts" />
+      </VStack>
+    </Card>
+  );
+}`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Import Astryx components from their public Core paths.',
+            'Import integration-owned components, helpers, icons, or styles only through paths the package exports ({@link generic:export-template-assets}).',
+            'Avoid adding another library when Astryx or platform APIs already provide the behavior.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'export-one-component',
+      title: 'Export one component',
+      content: [
+        {
+          type: 'prose',
+          text: 'The source must default-export one React component. Named helpers inside the file are fine.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+            'Keep a static template server-compatible when it needs no client behavior.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/typography.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'foundations',
   description:
     'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',
+  keywords: ['font', 'fonts', 'font size'],
   tokenCategory: 'typography',
 
   sections: [
@@ -44,9 +45,10 @@ export const docs = {
       ],
     },
 
-    // ── Loading Custom Fonts ────────────────────────────────────────────────
+    // ── Custom Fonts ────────────────────────────────────────────────────────
     {
-      title: 'Loading Custom Fonts',
+      id: 'loading-custom-fonts',
+      title: 'Custom fonts',
   category: 'foundations',
       content: [
         {
@@ -165,11 +167,16 @@ export const docs = {
       ],
     },
 
-    // ── Usage ────────────────────────────────────────────────────────────────
+    // ── Headings and text ───────────────────────────────────────────────────
     {
-      title: 'Usage',
+      id: 'usage',
+      title: 'Headings and text',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Use `Heading` for document structure and `Text` for everything else; each maps its props to the type scale tokens.',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -205,6 +212,19 @@ export const docs = {
 // Display without heading semantics (data callouts, decorative)
 <Text type="display-2">$1.2M Revenue</Text>`,
         },
+      ],
+    },
+
+    // ── Custom type scale ───────────────────────────────────────────────────
+    {
+      id: 'custom-type-scale',
+      title: 'Custom type scale',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Change the whole ramp with `base` and `ratio` in `defineTheme`; every font size and line height recomputes from them.',
+        },
         {
           type: 'code',
           lang: 'tsx',