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

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

@@ -0,0 +1,108 @@
+// 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

@@ -0,0 +1,59 @@
+// 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

@@ -0,0 +1,16 @@
+// 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

@@ -0,0 +1,108 @@
+// 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

@@ -0,0 +1,165 @@
+// 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',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/start-a-template.doc.mjs

@@ -0,0 +1,143 @@
+// 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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'start-a-template',
+  placement: {parent: 'namespace:templates', slot: 'build', order: 10},
+  title: 'Start a template',
+  category: 'guide',
+  keywords: [
+    'what is a template',
+    'add a template',
+    'page template',
+    'block template',
+  ],
+  description:
+    'Help others build apps faster and share a consistent visual language by turning your UI idea into a full page or page section.',
+  sections: [
+    {
+      id: 'what-a-template-is',
+      title: 'What a template is',
+      content: [
+        {
+          type: 'prose',
+          text: 'Unlike a component, a template becomes app code: an app copies it into its own code and adapts it to its product.',
+        },
+        {
+          type: 'prose',
+          text: "A component stays a package dependency and updates with the package. A copied template does not, so updating the package never rewrites the app's copy.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# How an app finds a template and copies it
+npx astryx template --list
+npx astryx template acme-dashboard src/app/dashboard`,
+        },
+      ],
+    },
+    {
+      id: 'why-share-one',
+      title: 'Why share one',
+      content: [
+        {
+          type: 'prose',
+          text: 'Templates help other people build apps faster while keeping a consistent visual language across products. Share one when people need more than one component to get started: a template brings the right components, layout, content structure, and interaction wiring already assembled.',
+        },
+        {
+          type: 'prose',
+          text: 'Do not turn a product-specific page into a rigid component only to share its structure. Share it as a template and let each app adapt its copy.',
+        },
+      ],
+    },
+    {
+      id: 'choose-page-or-block',
+      title: 'Choose a page or block',
+      content: [
+        {
+          type: 'table',
+          headers: ['Kind', 'Use it for'],
+          rows: [
+            [
+              'Page',
+              'A complete screen, such as a dashboard, settings page, or checkout flow.',
+            ],
+            [
+              'Block',
+              'A smaller section that fits inside a page, such as a hero, form, or data panel. A block can also be the example or showcase for a component.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'pick-a-template-id',
+      title: 'Pick a template id',
+      content: [
+        {
+          type: 'prose',
+          text: 'Choose a stable lowercase kebab-case id, such as `acme-dashboard`. The id becomes the source and doc file name, the package export, and the value apps pass to `astryx template`. To change a label, edit the doc ({@link generic:template-doc-overview}); never rename the id.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Start with your product or package name, then name the reusable pattern, so the id stays distinct from Core and other integrations.',
+            'Do not end the id with `-page`, `-app`, `-view`, or `-screen`.',
+            'Do not reuse a Core id by accident: the bare id becomes ambiguous in every app that installs your package. To take over a Core template on purpose, declare `replaces` ({@link generic:replace-a-core-template}).',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# See the Core ids\nnpx astryx --json template --list --package @astryxdesign/core',
+        },
+      ],
+    },
+    {
+      id: 'run-the-add-command',
+      title: 'Run the add command',
+      content: [
+        {
+          type: 'prose',
+          text: 'Pages are the default. Pass `--type block` to add a block.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `npx astryx integration add template acme-dashboard
+npx astryx integration add template acme-stat-card --type block`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `template contribution added
+
+[ok] acme-dashboard
+
+Declare template root ./templates in astryx.integration.mjs.
+
+- templates/acme-dashboard.doc.mjs
+- templates/acme-dashboard.tsx
+- package.json
+- astryx.integration.mjs`,
+        },
+        {
+          type: 'prose',
+          text: 'The command writes `templates/<id>.tsx` for the UI and `templates/<id>.doc.mjs` for its metadata, and declares the templates directory in `astryx.integration.mjs`. When `package.json` has an `exports` map, it also adds the `./templates/<id>` export ({@link generic:export-template-assets}).',
+        },
+        {
+          type: 'prose',
+          text: 'It never overwrites an existing source or doc file. Add `--dry-run` to see every planned write first.',
+        },
+      ],
+    },
+  ],
+};