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

package/foundation/discovery/docs-section-key.mjs

@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable section keys, section lookup, and the topic index.
+ *
+ * @input Reference-doc sections, each with an optional authored `id`.
+ * @output The key a section is addressed by (its `id`, else a kebab-case key
+ *   derived from its authored title), lookup by key or title, and the compact
+ *   index a topic-only docs read returns.
+ * @position Shared by docs discovery (which rejects colliding keys before a
+ *   reader sees them), the docs leaves (index, section, detail), and Doctor
+ *   (output budgets). Imports nothing from discovery, so both can use it.
+ */
+
+/** A stable key: lowercase letters and digits, joined by single hyphens. */
+export const SECTION_KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The longest summary an index entry carries, in characters. */
+export const SECTION_SUMMARY_MAX = 240;
+
+/**
+ * A section's authored title. A `--zh`/`--dense` overlay replaces the visible
+ * title, but extensions are written against the authored one and keys derive
+ * from it, so both stay the same in every language.
+ */
+const SOURCE_TITLE = Symbol('astryx.docs.sourceTitle');
+
+/**
+ * Record the authored title of a section whose visible title a translation
+ * overlay replaces.
+ * @template {object} T
+ * @param {T} section
+ * @param {string} title
+ * @returns {T}
+ */
+export function withSourceTitle(section, title) {
+  Object.defineProperty(section, SOURCE_TITLE, {value: title, configurable: true});
+  return section;
+}
+
+/**
+ * @param {any} section
+ * @returns {string}
+ */
+export function sourceTitle(section) {
+  return section?.[SOURCE_TITLE] ?? section?.title;
+}
+
+/**
+ * The key a title derives: accents folded, `&` spelled out, and every other
+ * run of non-alphanumerics collapsed to one hyphen. Empty when the title has
+ * no Latin letters or digits to derive from.
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function sectionTitleKey(title) {
+  if (typeof title !== 'string') return '';
+  return title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * The key a section is addressed by: its authored `id`, else the key its
+ * authored title derives.
+ * @param {any} section
+ * @returns {string}
+ */
+export function sectionKey(section) {
+  return typeof section?.id === 'string'
+    ? section.id
+    : sectionTitleKey(sourceTitle(section));
+}
+
+/**
+ * Problems with the keys of a topic's sections: an authored id that is not a
+ * stable key, a title no key derives from, and two sections sharing a key.
+ * Keys are never suffixed to make them unique, because readers link to them.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyProblems(sections) {
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  sections.forEach((section, s) => {
+    const at = `sections[${s}]`;
+    // A missing title is reported where titles are checked; no key to judge.
+    if (
+      section?.id == null &&
+      (typeof section?.title !== 'string' || section.title === '')
+    ) {
+      return;
+    }
+    if (
+      section?.id != null &&
+      (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id))
+    ) {
+      problems.push(
+        `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+      );
+      return;
+    }
+    const key = sectionKey(section);
+    if (key === '') {
+      problems.push(
+        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. Give the section an id.`,
+      );
+      return;
+    }
+    const first = seen.get(key);
+    if (first != null) {
+      problems.push(
+        `${at}: the key "${key}" is already used by sections[${first}]. Give one of them a distinct id or title.`,
+      );
+      return;
+    }
+    seen.set(key, s);
+  });
+  return problems;
+}
+
+/**
+ * Stamp every section with the key it is addressed by. Runs only after
+ * extensions merge: a derived key must never take part in merge matching.
+ * @template {{sections: any[]}} T
+ * @param {T} doc
+ * @returns {T}
+ */
+export function withSectionKeys(doc) {
+  return {
+    ...doc,
+    sections: doc.sections.map(section =>
+      section.id != null
+        ? section
+        : withSourceTitle(
+            {...section, id: sectionKey(section)},
+            sourceTitle(section),
+          ),
+    ),
+  };
+}
+
+/**
+ * Find the section a reader asked for: by key, then by exact title (or the
+ * key the query derives), then by a title that contains the query. More than
+ * one match is refused rather than guessed.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
+ *   matches when the query is ambiguous, and is empty when nothing matches
+ */
+export function findDocSection(sections, query) {
+  const wanted = query.trim();
+  const byKey = sections.find(section => sectionKey(section) === wanted);
+  if (byKey) return {section: byKey, candidates: []};
+
+  const lower = wanted.toLowerCase();
+  const derived = sectionTitleKey(wanted);
+  const exact = sections.filter(
+    section =>
+      section.title.toLowerCase() === lower ||
+      (derived !== '' && sectionTitleKey(sourceTitle(section)) === derived),
+  );
+  if (exact.length === 1) return {section: exact[0], candidates: []};
+  if (exact.length > 1) return {section: null, candidates: exact};
+
+  const partial = sections.filter(section =>
+    section.title.toLowerCase().includes(lower),
+  );
+  if (partial.length === 1) return {section: partial[0], candidates: []};
+  return {section: null, candidates: partial};
+}
+
+/**
+ * One line that says what a section holds: its first prose or list text,
+ * whitespace collapsed, cut at a word boundary.
+ * @param {any} section
+ * @param {number} [max]
+ * @returns {string}
+ */
+export function sectionSummary(section, max = SECTION_SUMMARY_MAX) {
+  const first = (section?.content ?? []).find(
+    (/** @type {any} */ block) =>
+      (block?.type === 'prose' && typeof block.text === 'string') ||
+      (block?.type === 'list' && Array.isArray(block.items)),
+  );
+  const raw =
+    first == null ? '' : first.type === 'prose' ? first.text : first.items[0];
+  const text = String(raw ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+/**
+ * The index a topic-only read returns: what the topic is, and one entry per
+ * section with the key to read it by.
+ * @param {{name: string, title: string, description: string, sections: any[]}} doc
+ * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ */
+export function buildDocsIndexData(doc) {
+  return {
+    name: doc.name,
+    title: doc.title,
+    description: doc.description,
+    sections: doc.sections.map(section => ({
+      id: sectionKey(section),
+      title: section.title,
+      summary: sectionSummary(section),
+    })),
+  };
+}

package/foundation/discovery/docs-section-key.test.mjs

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  SECTION_KEY_RE,
+  SECTION_SUMMARY_MAX,
+  buildDocsIndexData,
+  findDocSection,
+  sectionKey,
+  sectionKeyProblems,
+  sectionSummary,
+  sectionTitleKey,
+  sourceTitle,
+  withSectionKeys,
+  withSourceTitle,
+} from './docs-section-key.mjs';
+
+/** @param {string} title @param {object} [fields] */
+const section = (title, fields = {}) => ({title, content: [], ...fields});
+
+describe('sectionTitleKey', () => {
+  it.each([
+    ['Quick Start', 'quick-start'],
+    ['Light/Dark Mode', 'light-dark-mode'],
+    ["Do & Don't", 'do-and-don-t'],
+    ['  Café Crème  ', 'cafe-creme'],
+    ['useTheme()', 'usetheme'],
+    ['--- Tokens ---', 'tokens'],
+    ['亮/暗模式', ''],
+    ['', ''],
+  ])('%j derives %j', (title, key) => {
+    expect(sectionTitleKey(title)).toBe(key);
+  });
+
+  it('derives only stable keys', () => {
+    for (const title of ['A  B', 'x__y', 'Élan 2.0', 'a-b-', '-a']) {
+      expect(sectionTitleKey(title)).toMatch(SECTION_KEY_RE);
+    }
+  });
+
+  it('derives nothing from a non-string', () => {
+    expect(sectionTitleKey(undefined)).toBe('');
+    expect(sectionTitleKey(42)).toBe('');
+  });
+});
+
+describe('sectionKey', () => {
+  it('prefers the authored id', () => {
+    expect(sectionKey(section('Quick Start', {id: 'start'}))).toBe('start');
+  });
+
+  it('derives from the authored title, not a translated one', () => {
+    const translated = withSourceTitle(section('快速开始'), 'Quick Start');
+    expect(sectionKey(translated)).toBe('quick-start');
+  });
+});
+
+describe('sectionKeyProblems', () => {
+  it('accepts distinct keys', () => {
+    expect(
+      sectionKeyProblems([section('Install'), section('Usage', {id: 'use'})]),
+    ).toEqual([]);
+  });
+
+  it('rejects two sections that share a key', () => {
+    const problems = sectionKeyProblems([
+      section('Quick Start'),
+      section('Quick-start'),
+    ]);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('"quick-start" is already used by sections[0]');
+  });
+
+  it('rejects an authored id that collides with a derived key', () => {
+    expect(
+      sectionKeyProblems([section('Install'), section('Setup', {id: 'install'})]),
+    ).toHaveLength(1);
+  });
+
+  it('rejects an unsafe id and never suffixes one', () => {
+    for (const id of ['Quick Start', 'a_b', 'a--b', '-a', '', 7]) {
+      expect(sectionKeyProblems([section('Install', {id})])[0]).toContain(
+        'is not a stable key',
+      );
+    }
+  });
+
+  it('rejects a title no key derives from', () => {
+    expect(sectionKeyProblems([section('亮/暗模式')])[0]).toContain(
+      'Give the section an id',
+    );
+    expect(sectionKeyProblems([section('亮/暗模式', {id: 'light-dark'})])).toEqual(
+      [],
+    );
+  });
+
+  it('leaves a missing title to the title check', () => {
+    expect(sectionKeyProblems([{content: []}, section('')])).toEqual([]);
+  });
+});
+
+describe('withSectionKeys', () => {
+  it('stamps derived keys and keeps authored ones', () => {
+    const doc = withSectionKeys({
+      sections: [section('Quick Start'), section('Usage', {id: 'use'})],
+    });
+    expect(doc.sections.map(s => s.id)).toEqual(['quick-start', 'use']);
+  });
+
+  it('keeps the authored title of a translated section', () => {
+    const doc = withSectionKeys({
+      sections: [withSourceTitle(section('快速开始'), 'Quick Start')],
+    });
+    expect(doc.sections[0].id).toBe('quick-start');
+    expect(sourceTitle(doc.sections[0])).toBe('Quick Start');
+  });
+});
+
+describe('findDocSection', () => {
+  const sections = withSectionKeys({
+    sections: [
+      section('Quick Start'),
+      section('Theme Props'),
+      section('Theme Tokens', {id: 'tokens'}),
+      section('Overview', {id: 'overview-a'}),
+      section('Overview', {id: 'overview-b'}),
+    ],
+  }).sections;
+
+  it('finds a section by key first', () => {
+    expect(findDocSection(sections, 'tokens').section.title).toBe(
+      'Theme Tokens',
+    );
+  });
+
+  it('finds a section by exact title, case-insensitively', () => {
+    expect(findDocSection(sections, 'quick start').section.id).toBe(
+      'quick-start',
+    );
+  });
+
+  it('finds a section by the key its query derives', () => {
+    expect(findDocSection(sections, 'Quick-Start!').section.id).toBe(
+      'quick-start',
+    );
+  });
+
+  it('finds a section by a unique part of its title', () => {
+    expect(findDocSection(sections, 'props').section.id).toBe('theme-props');
+  });
+
+  it('refuses an ambiguous exact title and lists the candidates', () => {
+    const {section: match, candidates} = findDocSection(sections, 'Overview');
+    expect(match).toBeNull();
+    expect(candidates.map(s => s.id)).toEqual(['overview-a', 'overview-b']);
+  });
+
+  it('refuses an ambiguous partial title', () => {
+    const {section: match, candidates} = findDocSection(sections, 'theme');
+    expect(match).toBeNull();
+    expect(candidates.map(s => s.id)).toEqual(['theme-props', 'tokens']);
+  });
+
+  it('returns nothing for no match', () => {
+    expect(findDocSection(sections, 'zzz')).toEqual({
+      section: null,
+      candidates: [],
+    });
+  });
+});
+
+describe('sectionSummary', () => {
+  it('uses the first prose or list text, whitespace collapsed', () => {
+    expect(
+      sectionSummary({
+        content: [
+          {type: 'code', lang: 'ts', code: 'x'},
+          {type: 'prose', text: 'Line one.\n\n  Line two.'},
+        ],
+      }),
+    ).toBe('Line one. Line two.');
+    expect(
+      sectionSummary({content: [{type: 'list', items: ['First', 'Second']}]}),
+    ).toBe('First');
+  });
+
+  it('is empty when the section has no text', () => {
+    expect(sectionSummary({content: [{type: 'table', headers: [], rows: []}]})).toBe(
+      '',
+    );
+  });
+
+  it('cuts a long summary at a word boundary', () => {
+    const summary = sectionSummary({
+      content: [{type: 'prose', text: 'word '.repeat(200)}],
+    });
+    expect(summary.length).toBeLessThanOrEqual(SECTION_SUMMARY_MAX);
+    expect(summary.endsWith('word…')).toBe(true);
+  });
+});
+
+describe('buildDocsIndexData', () => {
+  it('lists each section by key, title, and summary', () => {
+    expect(
+      buildDocsIndexData({
+        name: 'theme',
+        title: 'Theme',
+        description: 'Theming.',
+        sections: [
+          section('Quick Start', {content: [{type: 'prose', text: 'Start.'}]}),
+          section('Usage', {id: 'use'}),
+        ],
+      }),
+    ).toEqual({
+      name: 'theme',
+      title: 'Theme',
+      description: 'Theming.',
+      sections: [
+        {id: 'quick-start', title: 'Quick Start', summary: 'Start.'},
+        {id: 'use', title: 'Usage', summary: ''},
+      ],
+    });
+  });
+});

package/foundation/discovery/template-adapter.mjs

@@ -27,10 +27,11 @@ import {createJiti} from 'jiti';
 import {loadModuleWithParser} from '../fs/module-loader.mjs';
 import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
+import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
 import {Project} from '../config/project.mjs';
 
 /** Identity used for core (built-in) templates in package-scoped listings. */
-const CORE_PACKAGE = '@astryxdesign/core';
+const CORE_PACKAGE = CORE_PROVIDER_ID;
 
 /**
  * Identity for a template in package-scoped views. Core (built-in) templates

package/foundation/discovery/theming-targets.test.mjs

@@ -265,14 +265,18 @@ describe('collectThemingTargets', () => {
     expect(doc.subComponentOf).toBe('Dialog');
     expect(doc.theming.targets).toEqual([
       {className: 'astryx-dialog-header'},
+      {className: 'astryx-dialog-header-start-content'},
       {className: 'astryx-dialog-header-title-block'},
+      {className: 'astryx-dialog-header-end-content'},
       {className: 'astryx-dialog-header-close-icon'},
     ]);
   });
 
   it.each([
     'dialog-header',
+    'dialog-header-start-content',
     'dialog-header-title-block',
+    'dialog-header-end-content',
     'dialog-header-close-icon',
   ])('enumerates %s once under its canonical Dialog owner', async key => {
     const matches = (await enumerated).filter(target => target.key === key);

package/foundation/doc-compiler/compile.d.mts

@@ -0,0 +1,162 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * One authored file, as discovery loaded it.
+ * @typedef {object} AuthoredFile
+ * @property {string} file the file's name, for messages only
+ * @property {any} [doc] the parsed doc, when it loaded
+ * @property {unknown} [error] why it did not load or parse
+ * @property {any} [overlay] the language overlay's export, when one applies
+ * @property {unknown} [overlayError] why the overlay did not load
+ */
+/**
+ * @typedef {object} ReferenceTopicInput
+ * @property {string} id the topic's name in the catalog
+ * @property {string} provider the package that owns the topic
+ * @property {string | null} replaces the topic it took the place of
+ * @property {string | null} lang the overlay language, or null for authored text
+ * @property {AuthoredFile} base
+ * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
+ */
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ * @typedef {{status: 'resolved', topic: string, section: string, previewType?: string, content: any[]}
+ *   | {status: 'unknown-topic'}
+ *   | {status: 'unknown-section'}} TokenRefResolution
+ */
+/**
+ * @typedef {object} CompiledReferenceNode
+ * @property {number} schemaVersion
+ * @property {'reference'} kind
+ * @property {'lowered' | 'linked'} stage `linked` once every token reference
+ *   carries its resolution; a lowered node carries none
+ * @property {string} id the topic's name in the catalog
+ * @property {string | null} lang
+ * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
+ * @property {Record<string, string>} sourceTitles section key -> authored title
+ * @property {any} doc the topic: authored fields in authored order, every
+ *   section keyed; a linked node's token references carry `resolved`
+ */
+/**
+ * Lower one topic: overlay each file, merge the extensions in order, and stamp
+ * every section with its key.
+ * @param {ReferenceTopicInput} input
+ * @returns {CompiledReferenceNode}
+ */
+export function lowerReferenceTopic(input: ReferenceTopicInput): CompiledReferenceNode;
+/**
+ * Link every section of a lowered node.
+ * @param {CompiledReferenceNode} node
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ *   the lowered node a reference names, or null when no topic has that name
+ * @returns {Promise<CompiledReferenceNode>}
+ */
+export function linkReferenceTopic(node: CompiledReferenceNode, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<CompiledReferenceNode>;
+/**
+ * Resolve the token references in one section. A section with none comes back
+ * as it went in.
+ * @template {{content: any[]}} S
+ * @param {S} section
+ * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
+ * @returns {Promise<S>}
+ */
+export function linkReferenceSection<S extends {
+    content: any[];
+}>(section: S, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<S>;
+/** Bumped whenever the shape of a compiled node changes. */
+export const COMPILED_DOC_SCHEMA_VERSION: 1;
+/**
+ * One authored file, as discovery loaded it.
+ */
+export type AuthoredFile = {
+    /**
+     * the file's name, for messages only
+     */
+    file: string;
+    /**
+     * the parsed doc, when it loaded
+     */
+    doc?: any;
+    /**
+     * why it did not load or parse
+     */
+    error?: unknown;
+    /**
+     * the language overlay's export, when one applies
+     */
+    overlay?: any;
+    /**
+     * why the overlay did not load
+     */
+    overlayError?: unknown;
+};
+export type ReferenceTopicInput = {
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    /**
+     * the package that owns the topic
+     */
+    provider: string;
+    /**
+     * the topic it took the place of
+     */
+    replaces: string | null;
+    /**
+     * the overlay language, or null for authored text
+     */
+    lang: string | null;
+    base: AuthoredFile;
+    /**
+     * in merge order
+     */
+    extensions: Array<AuthoredFile & {
+        provider: string;
+    }>;
+};
+/**
+ * A token reference after linking: the target section's content, or why it
+ * has none.
+ */
+export type TokenRefResolution = {
+    status: "resolved";
+    topic: string;
+    section: string;
+    previewType?: string;
+    content: any[];
+} | {
+    status: "unknown-topic";
+} | {
+    status: "unknown-section";
+};
+export type CompiledReferenceNode = {
+    schemaVersion: number;
+    kind: "reference";
+    /**
+     * `linked` once every token reference
+     * carries its resolution; a lowered node carries none
+     */
+    stage: "lowered" | "linked";
+    /**
+     * the topic's name in the catalog
+     */
+    id: string;
+    lang: string | null;
+    provenance: {
+        provider: string;
+        replaces: string | null;
+        extensions: string[];
+    };
+    /**
+     * section key -> authored title
+     */
+    sourceTitles: Record<string, string>;
+    /**
+     * the topic: authored fields in authored order, every
+     * section keyed; a linked node's token references carry `resolved`
+     */
+    doc: any;
+};