@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/assets/templates/blocks/components/Timer/TimerFormats.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Timer',
-  name: 'Timer — Formats',
-  displayName: 'Timer — Formats',
-  description:
-    'Elapsed compact units and stopwatch clock notation shown from the same start time.',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  componentsUsed: ['Timer', 'Layout', 'Text'],
-};

package/assets/templates/blocks/components/Timer/TimerFormats.tsx

@@ -1,34 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Timer} from '@astryxdesign/core/Timer';
-import {Stack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function TimerFormats() {
-  const [startedAt] = useState(() => Date.now() - 3_753_000);
-
-  return (
-    <Stack direction="vertical" gap={3}>
-      <Stack direction="horizontal" gap={3} vAlign="center">
-        <Text type="supporting" color="secondary">
-          Elapsed
-        </Text>
-        <Timer startTime={startedAt} type="body" color="primary" />
-      </Stack>
-      <Stack direction="horizontal" gap={3} vAlign="center">
-        <Text type="supporting" color="secondary">
-          Clock
-        </Text>
-        <Timer
-          format="clock"
-          startTime={startedAt}
-          type="body"
-          color="primary"
-        />
-      </Stack>
-    </Stack>
-  );
-}

package/assets/templates/blocks/components/Timer/TimerInline.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Timer',
-  name: 'Timer — Inline',
-  displayName: 'Timer — Inline',
-  description:
-    'A Timer composed into status copy while inheriting the surrounding typography.',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  componentsUsed: ['Timer', 'Text'],
-};

package/assets/templates/blocks/components/Timer/TimerInline.tsx

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {Timer} from '@astryxdesign/core/Timer';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function TimerInline() {
-  return (
-    <Text type="body" color="primary">
-      Processing for <Timer type="inherit" color="inherit" />
-    </Text>
-  );
-}

package/assets/templates/blocks/components/Timer/TimerShowcase.doc.mjs

@@ -1,13 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Timer',
-  name: 'Timer',
-  displayName: 'Timer',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  isShowcase: true,
-  componentsUsed: ['Timer', 'Layout', 'Text'],
-};

package/assets/templates/blocks/components/Timer/TimerShowcase.tsx

@@ -1,47 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Timer} from '@astryxdesign/core/Timer';
-import {Stack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function TimerShowcase() {
-  const [startedAt] = useState(() => Date.now() - 3_753_000);
-
-  return (
-    <Stack direction="vertical" gap={4}>
-      <Text type="large" color="primary" weight="semibold">
-        Processing
-      </Text>
-      <Stack direction="horizontal" gap={6} vAlign="center">
-        <Stack direction="vertical" gap={1}>
-          <Text type="supporting" color="secondary">
-            Elapsed
-          </Text>
-          <Timer
-            startTime={startedAt}
-            type="body"
-            size="xl"
-            color="primary"
-            weight="semibold"
-          />
-        </Stack>
-        <Stack direction="vertical" gap={1}>
-          <Text type="supporting" color="secondary">
-            Clock
-          </Text>
-          <Timer
-            format="clock"
-            startTime={startedAt}
-            type="body"
-            size="xl"
-            color="primary"
-            weight="semibold"
-          />
-        </Stack>
-      </Stack>
-    </Stack>
-  );
-}

package/assets/templates/blocks/components/Timer/TimerTypography.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Timer',
-  name: 'Timer — Typography',
-  displayName: 'Timer — Typography',
-  description:
-    'Timer using its Timestamp-matched default typography and an emphasized override.',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  componentsUsed: ['Timer', 'Layout', 'Text'],
-};

package/assets/templates/blocks/components/Timer/TimerTypography.tsx

@@ -1,31 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Timer} from '@astryxdesign/core/Timer';
-import {Stack} from '@astryxdesign/core/Layout';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function TimerTypography() {
-  const [startedAt] = useState(() => Date.now() - 128_000);
-
-  return (
-    <Stack direction="vertical" gap={3}>
-      <Text type="supporting" color="secondary">
-        Default
-      </Text>
-      <Timer startTime={startedAt} />
-      <Text type="supporting" color="secondary">
-        Emphasized
-      </Text>
-      <Timer
-        startTime={startedAt}
-        type="body"
-        size="xl"
-        color="primary"
-        weight="semibold"
-      />
-    </Stack>
-  );
-}

package/authoring/doctypes/base/graph-fields.doc.d.mts

@@ -1,9 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @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: import("@astryxdesign/cli/authoring").SchemaDoc;

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

@@ -1,62 +0,0 @@
-// 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/load-contract.test.mjs

@@ -1,207 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Every authored doc kind has a compile-time lock between its load check
- * and its published type: the `_*DriftLock` typedefs in `_schema.mjs` and
- * `template/parse.mjs`, which the strict typecheck evaluates. A lock names each
- * place the loader is deliberately looser than the type. These tests pin that
- * looser behavior and the published unknown-field policy, so tightening a load
- * check is a reviewed change rather than a silent one.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {fileURLToPath, pathToFileURL} from 'node:url';
-import {describe, expect, it} from 'vitest';
-import {parseDoc} from './parse.mjs';
-import {AuthoredDocKindSchema} from './_schema.mjs';
-import {doc as graphFieldsDoc} from './base/graph-fields.doc.mjs';
-import {problemsInTopic} from '../../foundation/discovery/docs-discovery.mjs';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const KINDS = AuthoredDocKindSchema.options;
-
-/** The lock that pins each kind's load check to its published type. */
-const LOCKS = {
-  component: '_ComponentDocDriftLock',
-  function: '_FunctionDocDriftLock',
-  generic: '_ReferenceDocDriftLock',
-  page: '_PageTemplateDocDriftLock',
-  block: '_BlockTemplateDocDriftLock',
-  schema: '_SchemaDocDriftLock',
-  command: '_CommandDocDriftLock',
-  enum: '_EnumDocDriftLock',
-  namespace: '_NamespaceDocDriftLock',
-};
-
-/** One valid example doc per kind, from the typed examples. */
-const EXAMPLES = Object.fromEntries(
-  await Promise.all(
-    KINDS.map(async kind => {
-      const file = {generic: 'reference', function: 'function'}[kind] ?? kind;
-      const url = pathToFileURL(
-        path.join(HERE, '../../test/authoring-types', `${file}.doc.mjs`),
-      );
-      return [kind, (await import(url.href)).docs];
-    }),
-  ),
-);
-
-describe('load check vs published type', () => {
-  it('locks every doc kind', () => {
-    const source = ['_schema.mjs', 'template/parse.mjs']
-      .map(file => fs.readFileSync(path.join(HERE, file), 'utf8'))
-      .join('\n');
-    expect(Object.keys(LOCKS).sort()).toEqual([...KINDS].sort());
-    const locks = [
-      ...Object.values(LOCKS),
-      '_AuthoredDocKindDriftLock',
-      '_HookDocIsFunctionDocLock',
-    ];
-    for (const lock of locks) {
-      expect(source, `${lock} is missing`).toMatch(
-        new RegExp(`\\}\\s*${lock}\\b`),
-      );
-    }
-  });
-
-  it('dispatches every doc kind and refuses any other', () => {
-    for (const kind of KINDS) {
-      expect(() => parseDoc(EXAMPLES[kind], `${kind}.doc.mjs`)).not.toThrow();
-    }
-    expect(() => parseDoc({type: 'widget', name: 'x'}, 'x.doc.mjs')).toThrow(
-      /unsupported type "widget"/,
-    );
-  });
-});
-
-describe('where loading is deliberately looser than the type', () => {
-  it('a stamped component needs no displayName; usage, theming and examples are unchecked', () => {
-    expect(() =>
-      parseDoc(
-        {
-          type: 'component',
-          name: 'Badge',
-          category: 'badges',
-          props: [],
-          usage: 'free text',
-          theming: 5,
-          examples: [{title: 'Basic'}],
-        },
-        'Badge.doc.mjs',
-      ),
-    ).not.toThrow();
-  });
-
-  it('each entry of a stamped group doc needs a name, and nothing more', () => {
-    const group = (/** @type {unknown[]} */ components) => ({
-      type: 'component',
-      name: 'Tabs',
-      components,
-    });
-    expect(() =>
-      parseDoc(
-        group([{name: 'Tab'}, {name: 'TabPanel', description: 'x'}]),
-        'Tabs.doc.mjs',
-      ),
-    ).not.toThrow();
-    for (const bad of [null, 5, 'Tab', {}, {name: ''}, {displayName: 'Tab'}]) {
-      expect(() => parseDoc(group([bad]), 'Tabs.doc.mjs')).toThrow(
-        /components\.0/,
-      );
-    }
-  });
-
-  it('a stamped function needs no displayName; usage is unchecked', () => {
-    expect(() =>
-      parseDoc(
-        {type: 'function', name: 'useX', params: [], returns: [], usage: 5},
-        'useX.doc.mjs',
-      ),
-    ).not.toThrow();
-  });
-
-  it('a stamped generic doc loads without title, description or sections, but is no topic', () => {
-    const doc = parseDoc({type: 'generic', name: 'notes'}, 'notes.doc.mjs');
-    expect(doc.title).toBe('notes');
-    expect(problemsInTopic(doc)).toEqual([
-      'description: expected a non-empty string',
-      'sections: expected at least one section',
-    ]);
-  });
-
-  it('a template needs no displayName or aspectRatio and may use its own category', () => {
-    expect(() =>
-      parseDoc(
-        {type: 'block', name: 'widget-demo', category: 'components/Widget'},
-        'widget-demo.doc.mjs',
-      ),
-    ).not.toThrow();
-    expect(() =>
-      parseDoc(
-        {type: 'page', name: 'widget-page', category: 'Widgets'},
-        'widget-page.doc.mjs',
-      ),
-    ).not.toThrow();
-  });
-
-  it('schema, command and enum docs load only as their type allows', () => {
-    const {fields, ...schemaDoc} = EXAMPLES.schema;
-    const {summary, ...commandDoc} = EXAMPLES.command;
-    const {members, ...enumDoc} = EXAMPLES.enum;
-    expect(() => parseDoc(schemaDoc, 's.doc.mjs')).toThrow(/fields/);
-    expect(() => parseDoc(commandDoc, 'c.doc.mjs')).toThrow(/summary/);
-    expect(() => parseDoc(enumDoc, 'e.doc.mjs')).toThrow(/members/);
-  });
-});
-
-describe('unknown fields', () => {
-  const keeps = KINDS.filter(kind => {
-    try {
-      parseDoc({...EXAMPLES[kind], notAField: true}, `${kind}.doc.mjs`);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-
-  it('match the published policy', () => {
-    const policy = graphFieldsDoc.notes
-      .map(note => ('text' in note ? note.text : ''))
-      .find(text => text.startsWith('Unknown fields'));
-    expect(policy, 'graph-fields.doc.mjs states the policy').toBeDefined();
-    const [kept, refused] = /** @type {string} */ (policy).split(
-      ' docs accept',
-    );
-    const named = (/** @type {string} */ text) =>
-      [...text.matchAll(/`([a-z]+)`/g)].map(match => match[1]).sort();
-    expect(named(kept)).toEqual([...keeps].sort());
-    expect(named(refused).filter(kind => KINDS.includes(kind))).toEqual(
-      KINDS.filter(kind => !keeps.includes(kind)).sort(),
-    );
-  });
-
-  it('are refused inside sections and content blocks', () => {
-    const [section] = EXAMPLES.generic.sections;
-    expect(() =>
-      parseDoc(
-        {...EXAMPLES.generic, sections: [{...section, notAField: true}]},
-        'r.doc.mjs',
-      ),
-    ).toThrow();
-    expect(() =>
-      parseDoc(
-        {
-          ...EXAMPLES.generic,
-          sections: [
-            {
-              ...section,
-              content: [{type: 'prose', text: 'x', notAField: true}],
-            },
-          ],
-        },
-        'r.doc.mjs',
-      ),
-    ).toThrow();
-  });
-});

package/authoring/doctypes/namespace/namespace.doc.d.mts

@@ -1,9 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @file SchemaDoc for NamespaceDoc, the authored hierarchy and layout owner.
- * @position packages/cli/authoring/doctypes/namespace — doc-type documentation
- */
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/doctypes/namespace/namespace.doc.mjs

@@ -1,132 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file SchemaDoc for NamespaceDoc, the authored hierarchy and layout owner.
- * @position packages/cli/authoring/doctypes/namespace — doc-type documentation
- */
-
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc = {
-  type: 'schema',
-  name: 'namespace-doc',
-  displayName: 'NamespaceDoc',
-  namespace: 'authoring',
-  description:
-    "Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents. Not loaded yet: only the docs graph reads namespace docs, and it is not built, so keep them out of an integration's docs directory for now.",
-  appliesTo: '<namespace>.doc.mjs',
-  fields: [
-    {
-      name: 'type',
-      type: "'namespace'",
-      description: 'Doc-kind discriminant.',
-      required: true,
-    },
-    {
-      name: 'name',
-      type: 'string',
-      description:
-        'Stable provider-local identity. Moving the namespace does not change this value.',
-      required: true,
-    },
-    {
-      name: 'title',
-      type: 'string',
-      description: 'Human-readable page title.',
-      required: true,
-    },
-    {
-      name: 'summary',
-      type: 'string',
-      description: 'One-line summary used in listings and search results.',
-      required: true,
-    },
-    {
-      name: 'placement',
-      type: 'DocPlacement',
-      description:
-        'Optional canonical parent request: {parent, slot?, order?}. Invalid explicit placement will fail compilation instead of falling back.',
-    },
-    {
-      name: 'aliases',
-      type: 'string[]',
-      description:
-        'Prior names or routes the docs graph will keep resolving to this doc.',
-    },
-    {
-      name: 'audience',
-      type: "'public' | 'internal'",
-      description: "Bundle audience. Defaults to 'public'.",
-      default: "'public'",
-    },
-    {
-      name: 'keywords',
-      type: 'string[]',
-      description: 'Search terms not already present in the title or summary.',
-    },
-    {
-      name: 'slots',
-      type: 'Record<string, NamespaceSlot>',
-      description:
-        'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
-      required: true,
-    },
-    {
-      name: 'adopts',
-      type: 'NamespaceAdoptionRule[]',
-      description:
-        'Provider-local rules that adopt otherwise-unplaced docs from a logical discovery group. They never scan a folder.',
-    },
-    {
-      name: 'blocks',
-      type: 'ReferenceContentBlock[]',
-      description:
-        'Ordered layout content. V1 adds only workflow, collection, and reference to the existing prose, heading, code, table, list, and token-ref blocks.',
-    },
-  ],
-  examples: [
-    {
-      label: 'A CLI namespace with one adopted source group',
-      code: `/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'cli',
-  title: 'Astryx CLI',
-  summary: 'Commands, APIs, and integration authoring.',
-  slots: {
-    guides: {title: 'Guides', accepts: {kinds: ['namespace', 'generic']}},
-    reference: {
-      title: 'Reference',
-      accepts: {kinds: ['namespace', 'command']},
-    },
-  },
-  adopts: [{
-    source: {group: 'cli-commands', kinds: ['command']},
-    into: 'reference',
-  }],
-  blocks: [
-    {type: 'collection', source: {slot: 'guides'}, presentation: 'cards'},
-    {type: 'collection', source: {slot: 'reference'}, presentation: 'compact'},
-  ],
-};`,
-    },
-  ],
-  notes: [
-    {
-      type: 'prose',
-      text: "Namespace docs are not loaded yet. Only the docs graph reads them, and it is not built. A namespace doc in an integration's docs directory fails to load as a topic, and with it every topic that package contributes, until the file is removed.",
-    },
-    {
-      type: 'prose',
-      text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
-    },
-    {
-      type: 'list',
-      style: 'dont',
-      items: [
-        'Use a directory as implicit navigation.',
-        'Put JSX, HTML, ANSI, callbacks, or custom renderer code in a doc.',
-        'Use choice, callout, or checklist blocks before the full block-extension contract exists.',
-      ],
-    },
-  ],
-};

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

@@ -1,12 +0,0 @@
-// @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.js').NamespaceDoc} NamespaceDoc */
-/**
- * Validate an unknown value as a NamespaceDoc, or throw a readable error.
- * @param {unknown} input
- * @param {string} [label]
- * @returns {NamespaceDoc}
- */
-export function parseNamespace(input: unknown, label?: string): NamespaceDoc;
-export type NamespaceDoc = import("../types.js").NamespaceDoc;

package/authoring/doctypes/namespace/parse.mjs

@@ -1,25 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Namespace doc parser. Zod is sealed in `../_schema.mjs`; consumers call
- * `parseNamespace` or use `parseDoc`.
- */
-
-import {NamespaceDocKindSchema} from '../_schema.mjs';
-import {formatZodError} from '../../_shared/errors.mjs';
-
-/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
-
-/**
- * Validate an unknown value as a NamespaceDoc, or throw a readable error.
- * @param {unknown} input
- * @param {string} [label]
- * @returns {NamespaceDoc}
- */
-export function parseNamespace(input, label = 'namespace doc') {
-  const result = NamespaceDocKindSchema.safeParse(input);
-  if (!result.success) {
-    throw new Error(formatZodError(label, result.error));
-  }
-  return result.data;
-}