@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for graph metadata shared by every authored doc kind.
+ * @position packages/cli/authoring/doctypes/base — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'authored-doc-graph-fields',
+  displayName: 'Authored doc graph fields',
+  namespace: 'authoring',
+  description:
+    'Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs graph. The docs graph is not built yet, so nothing reads them: a reference topic that sets one fails to load, and other doc kinds accept them and ignore them.',
+  appliesTo: 'Every supported .doc.mjs object',
+  fields: [
+    {
+      name: 'placement',
+      type: 'DocPlacement',
+      description:
+        'Requests one canonical parent in the docs graph. Not read yet: a topic that sets it fails to load.',
+      fields: [
+        {
+          name: 'placement.parent',
+          type: 'string',
+          description: 'Stable reference to the requested parent namespace.',
+          required: true,
+        },
+        {
+          name: 'placement.slot',
+          type: 'string',
+          description: 'Named slot owned by the parent namespace.',
+        },
+        {
+          name: 'placement.order',
+          type: 'number',
+          description: 'Integer sibling order within the slot.',
+        },
+      ],
+    },
+    {
+      name: 'aliases',
+      type: 'string[]',
+      description:
+        'Prior names or routes the docs graph will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+    },
+    {
+      name: 'audience',
+      type: "'public' | 'internal'",
+      description:
+        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
+      default: "'public'",
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'Unknown fields: `component`, `function`, `generic`, `schema`, `command` and `enum` docs accept a field they do not know, and nothing reads it, so a doc written for a newer CLI still loads here. `page`, `block` and `namespace` docs refuse one. Sections and content blocks refuse one in every doc.',
+    },
+  ],
+};

package/authoring/doctypes/base/type.ts

@@ -4,6 +4,46 @@
  * @file Shared leaf primitives used across the doc types.
  */
 
+/** Every authored documentation kind accepted by `parseDoc`. */
+export type AuthoredDocKind =
+  | 'component'
+  | 'function'
+  | 'generic'
+  | 'page'
+  | 'block'
+  | 'schema'
+  | 'command'
+  | 'enum'
+  | 'namespace';
+
+/** Visibility of an authored doc in a compiled audience-specific bundle. */
+export type DocAudience = 'public' | 'internal';
+
+/**
+ * Optional canonical placement request. The compiler resolves `parent` as a
+ * stable doc reference. `slot` selects one parent-owned slot, and `order`
+ * provides deterministic sibling ordering inside that slot.
+ */
+export interface DocPlacement {
+  parent: string;
+  slot?: string;
+  order?: number;
+}
+
+/**
+ * Graph metadata shared by every authored doc kind. Reserved for the docs
+ * graph, which is not built yet: nothing reads these fields, and a reference
+ * topic that sets one fails to load.
+ */
+export interface AuthoredDocGraphFields {
+  /** Requested canonical parent in the docs graph. Not read yet. */
+  placement?: DocPlacement;
+  /** Prior routes or names the docs graph will keep resolving. Not read yet. */
+  aliases?: string[];
+  /** Docs bundle audience; omit for public docs. Not read yet. */
+  audience?: DocAudience;
+}
+
 /**
  * Stable public identity for generated registry resources.
  *

package/authoring/doctypes/command/command.doc.mjs

@@ -135,8 +135,9 @@ export const doc = {
         },
         {
           name: 'options[].default',
-          type: 'string',
-          description: 'Default value as a string.',
+          type: 'string | boolean | string[]',
+          description:
+            'Default value: a string, a boolean, or a list of strings.',
         },
         {
           name: 'options[].cliOnly',

package/authoring/doctypes/command/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').CommandDoc} CommandDoc */
+/** @typedef {import('../types.js').CommandDoc} CommandDoc */
 /**
  * Validate an unknown value as a stamped command doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {CommandDoc}
  */
 export function parseCommand(input: unknown, label?: string): CommandDoc;
-export type CommandDoc = import("../types").CommandDoc;
+export type CommandDoc = import("../types.js").CommandDoc;

package/authoring/doctypes/command/parse.mjs

@@ -8,7 +8,7 @@
 import {CommandDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').CommandDoc} CommandDoc */
+/** @typedef {import('../types.js').CommandDoc} CommandDoc */
 
 /**
  * Validate an unknown value as a stamped command doc, or throw.

package/authoring/doctypes/command/type.ts

@@ -9,7 +9,8 @@
  * `--help`. Colocated at `clients/cli/commands/<name>.doc.mjs`.
  */
 
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /** A positional argument. `param` links it to a FunctionDoc param for its description. */
 export interface CommandArgDoc {
@@ -53,7 +54,7 @@ export interface CommandExampleDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').CommandDoc} \*\/
  *   export const doc = { type: 'command', name: 'search', fn: 'search', ... };
  */
-export interface CommandDoc {
+export interface CommandDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant. */
   type?: 'command';
   /** Command path, e.g. 'search' | 'theme build'. */

package/authoring/doctypes/component/component.doc.mjs

@@ -56,7 +56,7 @@ export const doc = {
       name: 'keywords',
       type: 'string[]',
       description:
-        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, shadcn). Lowercase. Used by `astryx component <term>` fuzzy matching.',
+        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. Used by `astryx component <term>` fuzzy matching.',
     },
     {
       name: 'hiddenComponents',
@@ -124,8 +124,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. (Optional on SubComponentDoc, where the sub-component description is used instead.)',
-      required: true,
+        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. Required on a component doc; optional on a sub-component doc (`subComponentOf`), which uses its description instead.',
       fields: [
         {
           name: 'usage.description',
@@ -242,6 +241,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "When it loads, a stamped component doc is checked as loosely as an unstamped one, so adding `type: 'component'` to an existing doc never breaks it: `displayName` may be missing, `category` may be any string, and `usage`, `theming`, `playground` and `examples` are not checked. Each entry in a group doc's `components` must have a `name`. Write to the type anyway; it is the contract.",
+    },
     {
       type: 'prose',
       text: 'ComponentDoc is a discriminated union of three shapes that all extend ComponentBaseDoc. Pick the variant by which key you set: `props` (single), `components` (multi), or `subComponentOf` (sub).',

package/authoring/doctypes/component/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').ComponentDoc} ComponentDoc */
+/** @typedef {import('../types.js').ComponentDoc} ComponentDoc */
 /**
  * Validate an unknown value as a stamped component doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ComponentDoc}
  */
 export function parseComponent(input: unknown, label?: string): ComponentDoc;
-export type ComponentDoc = import("../types").ComponentDoc;
+export type ComponentDoc = import("../types.js").ComponentDoc;

package/authoring/doctypes/component/parse.mjs

@@ -8,7 +8,7 @@
 import {ComponentDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ComponentDoc} ComponentDoc */
+/** @typedef {import('../types.js').ComponentDoc} ComponentDoc */
 
 /**
  * Validate an unknown value as a stamped component doc, or throw.

package/authoring/doctypes/component/type.ts

@@ -5,6 +5,7 @@
  */
 
 import type {
+  AuthoredDocGraphFields,
   ComponentAccessibilityRequirement,
   ComponentAnatomyElement,
   ComponentBestPractice,
@@ -18,13 +19,13 @@ import type {
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Shared fields between single-component and multi-component docs.
  * Do not use this interface directly — use `ComponentDoc` (the union type).
  */
-export interface ComponentBaseDoc {
+export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'component', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it, and `parseDoc` falls back to
@@ -49,7 +50,7 @@ export interface ComponentBaseDoc {
   import?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
-   *  names from other design systems (MUI, Chakra, Radix, shadcn).
+   *  names from other design systems (MUI, Chakra, Radix, and others).
    *  Lowercase only. Used by `astryx component <term>` for fuzzy matching.
    *  e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */
   keywords?: string[];

package/authoring/doctypes/enum/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').EnumDoc} EnumDoc */
+/** @typedef {import('../types.js').EnumDoc} EnumDoc */
 /**
  * Validate an unknown value as a stamped enum doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {EnumDoc}
  */
 export function parseEnum(input: unknown, label?: string): EnumDoc;
-export type EnumDoc = import("../types").EnumDoc;
+export type EnumDoc = import("../types.js").EnumDoc;

package/authoring/doctypes/enum/parse.mjs

@@ -8,7 +8,7 @@
 import {EnumDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').EnumDoc} EnumDoc */
+/** @typedef {import('../types.js').EnumDoc} EnumDoc */
 
 /**
  * Validate an unknown value as a stamped enum doc, or throw.

package/authoring/doctypes/enum/type.ts

@@ -5,6 +5,8 @@
  * discriminants). Colocated next to the source of truth it documents.
  */
 
+import type {AuthoredDocGraphFields} from '../base/type.js';
+
 /** One member of an enumerated vocabulary. */
 export interface EnumMemberDoc {
   /** The literal value, e.g. 'ERR_UNKNOWN_TOPIC' | 'component.list'. */
@@ -21,7 +23,7 @@ export interface EnumMemberDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').EnumDoc} \*\/
  *   export const doc = { type: 'enum', name: 'error-codes', ... };
  */
-export interface EnumDoc {
+export interface EnumDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant. */
   type?: 'enum';
   /** URL-safe identifier, used as the docs slug within its namespace. */

package/authoring/doctypes/function/function.doc.mjs

@@ -250,6 +250,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",

package/authoring/doctypes/function/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 /**
  * Validate an unknown value as a stamped function doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {FunctionDoc}
  */
 export function parseFunction(input: unknown, label?: string): FunctionDoc;
-export type FunctionDoc = import("../types").FunctionDoc;
+export type FunctionDoc = import("../types.js").FunctionDoc;

package/authoring/doctypes/function/parse.mjs

@@ -14,7 +14,7 @@
 
 import {parseHook} from '../hook/parse.mjs';
 
-/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 
 /**
  * Validate an unknown value as a stamped function doc, or throw.

package/authoring/doctypes/function/type.ts

@@ -10,7 +10,11 @@
  * here — the function does not know it has a CLI.
  */
 
-import type {HookParamDoc, UsageDoc} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  HookParamDoc,
+  UsageDoc,
+} from '../base/type.js';
 
 /**
  * A documented return. Hooks list named return fields (`name` set); CLI/API
@@ -45,7 +49,7 @@ export interface FunctionExampleDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').FunctionDoc} \*\/
  *   export const doc = { type: 'function', kind: 'api', name: 'search', ... };
  */
-export interface FunctionDoc {
+export interface FunctionDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant (shared with hooks). */
   type?: 'function';
   /** Export name, e.g. 'search' | 'useMediaQuery'. */

package/authoring/doctypes/hook/hook.doc.mjs

@@ -200,6 +200,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",

package/authoring/doctypes/hook/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {HookDoc}
  */
 export function parseHook(input: unknown, label?: string): HookDoc;
-export type HookDoc = import("../types").HookDoc;
+export type HookDoc = import("../types.js").HookDoc;

package/authoring/doctypes/hook/parse.mjs

@@ -8,7 +8,7 @@
 import {FunctionDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.

package/authoring/doctypes/hook/type.ts

@@ -5,13 +5,14 @@
  */
 
 import type {
+  AuthoredDocGraphFields,
   ComponentAccessibilityRequirement,
   ComponentBestPractice,
   HookParamDoc,
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Documentation for a standalone hook's .doc.mjs file.
@@ -27,7 +28,7 @@ import type {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').HookDoc} \*\/
  *   export const docs = { ... };
  */
-export interface HookDoc {
+export interface HookDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'function', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it. */

package/authoring/doctypes/legacy.d.mts

@@ -1,15 +1,17 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc}
+ * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
-export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
+export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc | ReferenceDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;

package/authoring/doctypes/legacy.mjs

@@ -10,20 +10,21 @@
 import {LegacyDocSchema} from './_schema.mjs';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc}
+ * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
 export function parseLegacyDoc(input, label = 'doc') {
   const result = LegacyDocSchema.safeParse(input);
   if (!result.success) {
     throw new Error(formatZodError(label, result.error));
   }
-  return /** @type {ComponentDoc | HookDoc} */ (result.data);
+  return /** @type {ComponentDoc | HookDoc | ReferenceDoc} */ (result.data);
 }