@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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

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

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

@@ -1,115 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/describe-the-component/subcomponent`:
- * give one member of a component family its own ComponentDoc.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'subcomponent',
-  placement: {
-    parent: 'namespace:describe-the-component',
-    slot: 'guides',
-    order: 40,
-  },
-  title: 'Subcomponent',
-  category: 'guide',
-  description:
-    'Move one member of a component family into its own sibling doc without duplicating it in the parent.',
-  sections: [
-    {
-      id: 'choose-a-separate-doc',
-      title: 'Choose a separate doc',
-      content: [
-        {
-          type: 'prose',
-          text: 'Start with a component family doc. Move one public member into a sibling doc when it has its own source and enough behavior, props, or usage guidance to maintain separately. The parent still lists the member, but only by name.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Keep a small member inline when its whole contract stays clear in the family doc.',
-            'Use a sibling doc when the member needs focused search results, examples, usage guidance, or independent maintenance.',
-            'Give each member one documentation owner. Do not keep a full parent entry and a sibling doc for the same name.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'reference-it-from-the-parent',
-      title: 'Reference it from the parent',
-      content: [
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'components/AcmeDialog.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export default {
-  type: 'component',
-  name: 'AcmeDialog',
-  displayName: 'Acme Dialog',
-  usage: {description: 'Presents a focused task above the current page.'},
-  components: [
-    {
-      name: 'AcmeDialog',
-      displayName: 'Acme Dialog',
-      description: 'Owns the modal surface and open state.',
-      props: [],
-    },
-    {name: 'AcmeDialogHeader'},
-  ],
-};`,
-        },
-        {
-          type: 'prose',
-          text: 'The name-only entry keeps `AcmeDialogHeader` in the family. Its description and props come only from the sibling file.',
-        },
-      ],
-    },
-    {
-      id: 'write-the-subcomponent-doc',
-      title: 'Write the subcomponent doc',
-      content: [
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'components/AcmeDialogHeader.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export default {
-  type: 'component',
-  name: 'AcmeDialogHeader',
-  displayName: 'Acme Dialog Header',
-  subComponentOf: 'AcmeDialog',
-  description: 'Labels an Acme Dialog and holds its close action.',
-  props: [
-    {
-      name: 'title',
-      type: 'string',
-      description: 'The dialog title.',
-      required: true,
-    },
-  ],
-};`,
-        },
-        {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['subComponentOf', 'description', 'props']},
-          presentation: 'full',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`subComponentOf` must exactly match the parent doc\'s `name`.',
-            '`description` explains this member\'s role in the family. `usage` is optional; add it when the member needs guidance beyond that sentence.',
-            'The child inherits family fields such as `group`, `category`, `keywords`, `theming`, and `playground` unless it overrides them.',
-          ],
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,64 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/templates/template-assets`: make every
- * style, font, icon, and media dependency survive a template copy.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'template-assets',
-  placement: {
-    parent: 'namespace:build-the-template',
-    slot: 'guides',
-    order: 20,
-  },
-  title: 'Assets',
-  summary:
-    "Make sure the template's styles, fonts, icons, images, and video still show up after an app copies it.",
-  blocks: [
-    {
-      type: 'prose',
-      text: 'The copied file does not bring sibling assets with it ({@link generic:write-the-template-file}). Give every asset exactly one owner:',
-    },
-    {
-      type: 'table',
-      headers: ['Owner', 'Use when', 'How the copied source reaches it'],
-      rows: [
-        [
-          'Copied source',
-          'The value is small, editable, and belongs to the starting point',
-          'Keep it in the `.tsx` file',
-        ],
-        [
-          'Integration package',
-          'The asset should stay centrally maintained with the package',
-          'Import a stable public package path',
-        ],
-        [
-          'App',
-          'The app must provide product-specific content or branding',
-          'Use an explicit placeholder or app public URL and say what to replace',
-        ],
-      ],
-    },
-    {
-      type: 'prose',
-      text: 'Do not make a template look self-contained while it relies on an undocumented package file or app convention.',
-    },
-  ],
-  keywords: [
-    'template assets',
-    'template styles',
-    'template fonts',
-    'template icons',
-    'template images',
-  ],
-  slots: {
-    guides: {
-      title: 'Guides',
-      accepts: {kinds: ['generic']},
-    },
-  },
-};

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

@@ -1,109 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/templates/document-the-template/template-doc-overview`:
- * the source and doc file pair, the fields every template doc shares, and how
- * to check what Astryx lists.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'template-doc-overview',
-  placement: {
-    parent: 'namespace:document-the-template',
-    slot: 'guides',
-    order: 10,
-  },
-  title: 'Template doc overview',
-  category: 'guide',
-  description:
-    'Understand what the template doc controls, keep it accurate as the UI changes, and check how Astryx lists the template.',
-  sections: [
-    {
-      id: 'understand-the-two-files',
-      title: 'Understand the two files',
-      content: [
-        {
-          type: 'prose',
-          text: 'Every template has a source file and a doc file. For `acme-dashboard`, the source is `templates/acme-dashboard.tsx` and the doc is `templates/acme-dashboard.doc.mjs`. Both begin with `acme-dashboard`, which is how Astryx knows they belong together.',
-        },
-        {
-          type: 'table',
-          headers: ['File', 'What it controls'],
-          rows: [
-            [
-              '`templates/acme-dashboard.tsx`',
-              'The UI source that an app copies and then owns.',
-            ],
-            [
-              '`templates/acme-dashboard.doc.mjs`',
-              'How Astryx names, describes, categorizes, previews, and resolves the template before it is copied.',
-            ],
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'The integration manifest points Astryx to the `templates` directory; it does not list each template. Change the source and doc together whenever the purpose, preview, readiness, or replacement behavior changes. No automated check can tell whether the doc still describes the rendered UI.',
-        },
-      ],
-    },
-    {
-      id: 'document-the-shared-fields',
-      title: 'Document the shared fields',
-      content: [
-        {
-          type: 'prose',
-          text: 'These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
-        },
-        {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: ['type', 'name', 'displayName', 'description', 'isReady'],
-          },
-          presentation: 'full',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
-            'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
-            'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
-            'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'check-how-astryx-lists-it',
-      title: 'Check how Astryx lists it',
-      content: [
-        {
-          type: 'prose',
-          text: 'Read the package-scoped template list after every doc change. Confirm the id, visible name, description, type, readiness, and package.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx --json template --list --package @acme/astryx-templates',
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          label: 'Relevant list result',
-          code: `{
-  "id": "acme-dashboard",
-  "name": "acme-dashboard",
-  "displayName": "Acme Dashboard",
-  "description": "An analytics dashboard for reviewing account health and recent trends.",
-  "type": "page",
-  "package": "@acme/astryx-templates",
-  "isReady": false
-}`,
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,102 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts`:
- * use the app typeface by default, and ship every font file a template needs
- * when it must bring its own.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'template-fonts',
-  placement: {
-    parent: 'namespace:template-assets',
-    slot: 'guides',
-    order: 30,
-  },
-  title: 'Fonts',
-  category: 'guide',
-  description:
-    "Keep text in the app's typeface unless the template truly needs its own, and ship every font file it uses when it does.",
-  sections: [
-    {
-      id: 'prefer-host-typography',
-      title: 'Prefer host typography',
-      content: [
-        {
-          type: 'prose',
-          text: 'Use Astryx typography components and theme values unless the template must demonstrate a specific licensed typeface. A copied template should normally inherit the app typography instead of installing a new global font.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Do not add a font only to make sample content look more polished.',
-            'Do not override the app body font from a template.',
-            'Use a custom face only for a real product or content requirement that the integration package owns.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'package-a-required-font',
-      title: 'Package a required font',
-      content: [
-        {
-          type: 'prose',
-          text: 'Keep the font files beside a package-owned stylesheet. The stylesheet can use relative `url()` paths because it stays in the package, and the template imports the stylesheet by its public path ({@link generic:template-styles}).',
-        },
-        {
-          type: 'code',
-          lang: 'css',
-          label: 'styles/acme-dashboard.css',
-          code: `@font-face {
-  font-family: 'Acme Sans';
-  src: url('../assets/fonts/acme-sans-regular.woff2') format('woff2');
-  font-style: normal;
-  font-weight: 400;
-  font-display: swap;
-}
-
-.acme-dashboard-title {
-  font-family: 'Acme Sans', sans-serif;
-}`,
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Ship WOFF2 when it satisfies the supported browsers. Add another format only when those browsers require it.',
-            'Declare every weight and style the template uses. Do not make the browser synthesize bold or italic because a file is missing.',
-            'Use `font-display: swap` unless the product requirement and performance test justify another value.',
-            'Confirm that the font license permits redistribution in the integration package.',
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'Exporting the stylesheet does not publish the font files it points to. Include the font directory in the package as well ({@link generic:export-template-assets}).',
-        },
-      ],
-    },
-    {
-      id: 'check-fonts-in-the-app',
-      title: 'Check fonts in the app',
-      content: [
-        {
-          type: 'prose',
-          text: 'When you test the template in an app ({@link generic:test-template-in-app}), also confirm the following.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Every font request succeeds from the built asset path.',
-            'Computed styles show the requested family, weight, and style.',
-            'Text stays readable with the fallback stack when a font loads slowly or fails.',
-          ],
-        },
-      ],
-    },
-  ],
-};