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

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

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

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

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

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