@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/assets/docs/tree/replace-a-core-template.doc.mjs

@@ -1,172 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
- * deliberately replace one Core template through template metadata.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'replace-a-core-template',
-  placement: {
-    parent: 'namespace:document-the-template',
-    slot: 'guides',
-    order: 40,
-  },
-  title: 'Replace a Core template',
-  category: 'guide',
-  description:
-    'Use a template replacement only when an integration intentionally changes the default source returned for one Core template id.',
-  sections: [
-    {
-      id: 'replace-only-on-purpose',
-      title: 'Replace only on purpose',
-      content: [
-        {
-          type: 'prose',
-          text: 'Use with care: replace a Core template only when every app using this integration should receive your source for an existing Core id by default. An alternative, a product-specific variation, or a different kind of template gets its own id instead ({@link generic:start-a-template}).',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Sharing a Core id without `replaces` does not replace Core. It makes the bare id ambiguous, so `astryx template <id>` fails until the app adds `--package`, and `doctor integration templates` reports an accidental collision.',
-            'A replacement can keep the Core id or use its own. `replaces` is what makes it the default.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'declare-the-replacement',
-      title: 'Declare the replacement',
-      content: [
-        {
-          type: 'prose',
-          text: 'Find the exact Core id and kind first.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx --json template --list --package @astryxdesign/core',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'templates/acme-app-shell.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export default {
-  type: 'page',
-  name: 'acme-app-shell',
-  displayName: 'Acme App Shell',
-  description:
-    'An Acme application shell with product navigation, account controls, and a responsive content region.',
-  replaces: 'shell-side-nav',
-  isReady: true,
-  category: 'Shell - Left Sidebar',
-};`,
-        },
-        {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
-        },
-        {
-          type: 'prose',
-          text: 'Declare `replaces` on the template doc, never in `astryx.integration.mjs`.',
-        },
-      ],
-    },
-    {
-      id: 'require-a-compatible-cli',
-      title: 'Require a compatible CLI',
-      content: [
-        {
-          type: 'prose',
-          text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          label: 'package.json',
-          code: `{
-  "peerDependencies": {
-    "@astryxdesign/cli": ">=0.7.0"
-  },
-  "peerDependenciesMeta": {
-    "@astryxdesign/cli": {
-      "optional": true
-    }
-  }
-}`,
-        },
-        {
-          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.',
-        },
-      ],
-    },
-    {
-      id: 'what-apps-receive',
-      title: 'What apps receive',
-      content: [
-        {
-          type: 'code',
-          lang: 'bash',
-          code: `# Receives the active replacement
-npx astryx template shell-side-nav src/app
-
-# Receives the original Core template
-npx astryx template shell-side-nav --package @astryxdesign/core src/app`,
-        },
-        {
-          type: 'prose',
-          text: 'When several integrations replace the same Core template, one wins:',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'An integration explicitly listed in `astryx.config.mjs` wins over one that is only installed and picked automatically.',
-            'When several explicitly configured integrations replace the same target, the one listed later wins and Astryx reports the ambiguity.',
-            "When no integration is configured explicitly, the package listed later in the app's package.json dependencies wins. Configure the intended integration explicitly instead of relying on that order.",
-          ],
-        },
-      ],
-    },
-    {
-      id: 'check-the-replacement',
-      title: 'Check the replacement',
-      content: [
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx doctor integration templates',
-        },
-        {
-          type: 'table',
-          headers: ['Issue', 'Meaning'],
-          rows: [
-            [
-              '`missing_template_replacement_target`',
-              '`replaces` does not name a Core template id.',
-            ],
-            [
-              '`invalid_template_replacement`',
-              'The replacement is unusable or its page/block kind differs from Core.',
-            ],
-            [
-              '`ambiguous_template_replacement`',
-              'One package declares two replacements for a target, or several active packages contend for it.',
-            ],
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'Replacement resolution is safe by default. A missing source, invalid doc, missing target, wrong kind, or conflicting declaration never hands the Core id to a questionable replacement: Astryx reports the issue and keeps the Core template. Fix every issue before publishing.',
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/sections-and-placement.doc.mjs

@@ -1,108 +0,0 @@
-// 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.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'sections-and-placement',
-  placement: {parent: 'namespace:docs', slot: 'guides', order: 20},
-  title: 'Sections and placement',
-  category: 'guide',
-  description: 'Give your package its own docs section and place guides in it.',
-  sections: [
-    {
-      id: 'add-a-docs-section',
-      title: 'Add a docs section',
-      content: [
-        {
-          type: 'prose',
-          text: "Give your package its own section in the docs tree with `integration add doc <name> --parent <section>`. The first run also writes the section's namespace doc.",
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx integration add doc deploying --parent acme\n# Open your section\nnpx astryx docs acme',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'docs/acme.doc.mjs',
-          code: "/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */\nexport default {\n  type: 'namespace',\n  name: 'acme',\n  title: 'Acme',\n  summary: 'Guides for Acme.',\n  slots: {\n    guides: {title: 'Guides', accepts: {kinds: ['generic']}},\n  },\n};",
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Edit its `title` and `summary`: readers see them in the docs list and at the top of your section.',
-            "The guide, `docs/deploying.doc.mjs`, gets `placement: {parent: 'namespace:acme', slot: 'guides'}`. Later runs with `--parent acme` reuse the namespace doc.",
-            '`package.json` gets the optional peer `"@astryxdesign/cli": ">=0.7.0"`, because an older CLI does not read sections; see {@link generic:versioning}.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'place-a-doc',
-      title: 'Place a doc',
-      content: [
-        {
-          type: 'prose',
-          text: 'A guide names its one home with `placement`: a namespace of your package, a slot in it, and an `order`. Its route is the section name, then the guide name.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: "placement: {parent: 'namespace:acme', slot: 'guides', order: 10}, // route: acme/deploying",
-        },
-        {
-          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.',
-            'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
-          ],
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx docs acme/deploying',
-        },
-      ],
-    },
-    {
-      id: 'fix-a-failed-placement',
-      title: 'Fix a failed placement',
-      content: [
-        {
-          type: 'prose',
-          text: 'A failed `placement` hides the doc: it gets no route and does not show in the docs list. `doctor integration docs` fails with `invalid_doc_graph` and names what to fix.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx doctor integration docs',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: 'severity: [fail]\ncode:     invalid_doc_graph\nmessage:  @acme/astryx-widgets/deploying.doc.mjs: placement.parent "namespace:cli" names no namespace; @acme/astryx-widgets declares "acme".',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'A `parent` that your package does not ship, such as `namespace:cli`, "names no namespace".',
-            'A `slot` that the namespace does not declare "is not a slot of namespace"; the message lists the slots it does declare.',
-            'The check exits 1; see {@link generic:check-your-docs}.',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/see-it-in-an-app.doc.mjs

@@ -1,59 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
- * integration component from an app that installs the package.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'see-it-in-an-app',
-  placement: {parent: 'namespace:components', slot: 'guides', order: 40},
-  title: 'See it in an app',
-  category: 'guide',
-  description:
-    'Confirm that an app discovers the component, its package, its public import, and its documentation.',
-  sections: [
-    {
-      id: 'read-the-installed-component',
-      title: 'Read the installed component',
-      content: [
-        {
-          type: 'prose',
-          text: 'An app that installs your package sees the component beside Core components, with its package name and public import. The app needs no config.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: `npx astryx component AcmeCarousel
-npx astryx component --list
-npx astryx search carousel`,
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: `# AcmeCarousel
-
-Cycles through slides one at a time. Use it for a small set of related cards.
-
-**Import:** \`import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';\``,
-        },
-        {
-          type: 'prose',
-          text: '`component --list` shows it as `import: @acme/astryx-widgets/components/AcmeCarousel  [@acme/astryx-widgets]`. The same commands work in your package while you build it.',
-        },
-      ],
-    },
-    {
-      id: 'test-the-packed-package',
-      title: 'Test the packed package',
-      content: [
-        {
-          type: 'prose',
-          text: 'Install the packed package in a test app before publishing. Then run the same detail, list, and search commands there. See {@link generic:test-in-an-app}.',
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,16 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @file astryx docs cli/integrations/ship — test, publish, and upgrade. */
-
-/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'ship',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 30},
-  title: 'Ship',
-  summary: 'Test, publish, and upgrade your package.',
-  keywords: ['ship', 'publish', 'release', 'upgrade'],
-  slots: {
-    guides: {title: 'Ship', accepts: {kinds: ['generic']}},
-  },
-};

package/assets/docs/tree/short-and-findable.doc.mjs

@@ -1,108 +0,0 @@
-// 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.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'short-and-findable',
-  placement: {parent: 'namespace:docs', slot: 'guides', order: 50},
-  title: 'Short and findable',
-  category: 'guide',
-  description: 'Write short sections that people and agents find by search.',
-  sections: [
-    {
-      id: 'keep-each-read-short',
-      title: 'Keep each read short',
-      content: [
-        {
-          type: 'prose',
-          text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `npx astryx doctor` warns on any read over 32 KB.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'When a section needs a second idea, split it into two sections.',
-            'Keep a topic to a few sections. When it grows past five, split it into more guides in your docs section.',
-            'A topic with more than one section reads as its section list. Readers open one section by its key, or the whole topic with `--full`.',
-          ],
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: '# The section list\nnpx astryx docs acme/deploying\n# One section\nnpx astryx docs acme/deploying check-before-you-ship\n# Everything\nnpx astryx docs acme/deploying --full',
-        },
-      ],
-    },
-    {
-      id: 'lead-with-the-summary',
-      title: 'Lead with the summary',
-      content: [
-        {
-          type: 'prose',
-          text: "A section's first prose block, or its first list item, is its summary in section lists and search results. Make it answer the section's question in one or two sentences.",
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'The summary is cut at about 240 characters.',
-            'A code block first does not count: the summary comes from the next prose block.',
-            'Open with the answer, not with background.',
-          ],
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder to your host.',
-        },
-      ],
-    },
-    {
-      id: 'make-docs-findable',
-      title: 'Make docs findable',
-      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.',
-        },
-        {
-          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.',
-            '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.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'test-with-search',
-      title: 'Test with search',
-      content: [
-        {
-          type: 'prose',
-          text: 'Test a doc the way a new reader finds it: search for the question, and check that the first hit answers it. Quote a query of more than one word.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx search "place a doc" --type doc',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'This query returns the section of these guides that shows how to place a doc.',
-            'Run the same search in an app that installs your package; see {@link generic:test-in-an-app}.',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/single-component.doc.mjs

@@ -1,165 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/describe-the-component/single-component`:
- * write and maintain the default ComponentDoc for one public component.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'single-component',
-  placement: {
-    parent: 'namespace:describe-the-component',
-    slot: 'guides',
-    order: 20,
-  },
-  title: 'Single component',
-  category: 'guide',
-  description:
-    'Write the default component doc: explain when to use the component, document every public prop, and add focused examples.',
-  sections: [
-    {
-      id: 'start-from-the-generated-doc',
-      title: 'Start from the generated doc',
-      content: [
-        {
-          type: 'prose',
-          text: '`integration add component` creates the normal doc for one public component. Keep the generated identity and import, then replace its sample text and props with the component\'s real public contract.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'components/AcmeCarousel.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export default {
-  type: 'component',
-  name: 'AcmeCarousel',
-  displayName: 'Acme Carousel',
-  import: '@acme/astryx-widgets/components/AcmeCarousel',
-  usage: {
-    description:
-      'Cycles through slides one at a time. Use it for a small set of related cards.',
-  },
-  props: [
-    {
-      name: 'slides',
-      type: 'ReactNode[]',
-      description: 'The slides to show, in order.',
-      required: true,
-    },
-  ],
-};`,
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Keep `props` on the top-level doc. Private implementation helpers do not need entries.',
-            'Keep the doc beside the source and change both in the same pull request.',
-            'If the module later exposes several related public exports, adapt this doc with {@link generic:component-family}.',
-          ],
-        },
-        {
-          type: 'reference',
-          target: 'schema:component-doc',
-          presentation: 'summary',
-        },
-      ],
-    },
-    {
-      id: 'explain-when-to-use-it',
-      title: 'Explain when to use it',
-      content: [
-        {
-          type: 'prose',
-          text: 'Write `usage.description` so a person or agent can decide whether this is the right component without opening its source. Say what it does, when to use it, and the most important boundary with a nearby alternative.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: `usage: {
-  description:
-    'Cycles through slides one at a time. Use it for a small set of related cards. Use a static list when every item should stay visible.',
-  bestPractices: [
-    {guidance: true, description: 'Keep the slide order stable while someone interacts with the carousel.'},
-    {guidance: false, description: 'Hide information that must remain visible for comparison.'},
-  ],
-},`,
-        },
-      ],
-    },
-    {
-      id: 'document-every-public-prop',
-      title: 'Document every public prop',
-      content: [
-        {
-          type: 'prose',
-          text: 'Copy the public prop names and types from the source. Explain the behavior a caller controls, not only the TypeScript type.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: `props: [
-  {
-    name: 'slides',
-    type: 'ReactNode[]',
-    description: 'The slides to show, in order.',
-    required: true,
-  },
-  {
-    name: 'interval',
-    type: 'number',
-    description: 'Milliseconds between automatic slide changes.',
-    default: '5000',
-  },
-],`,
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Set `required: true` only when every caller must pass the prop.',
-            'Write `default` exactly as the value should appear in documentation.',
-            'Skip styling escape hatches such as `xstyle`, `className`, and `style`.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'add-focused-examples',
-      title: 'Add focused examples',
-      content: [
-        {
-          type: 'prose',
-          text: 'Add short examples for important usage that the prop table does not make obvious. Each example should teach one complete pattern and use only public imports.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: `examples: [
-  {
-    label: 'Automatic rotation',
-    code: '<AcmeCarousel slides={slides} interval={5000} />',
-  },
-],`,
-        },
-      ],
-    },
-    {
-      id: 'read-the-result',
-      title: 'Read the result',
-      content: [
-        {
-          type: 'prose',
-          text: 'Read the component after every source or doc change. Confirm that its purpose, import, props, defaults, and examples match the source, then verify the packed package.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx component AcmeCarousel\nnpx astryx integration verify',
-        },
-      ],
-    },
-  ],
-};