Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
15.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file docs-pages.mjs
 *
 * How the CLI's docs become docsite pages. The CLI splits a long topic into a
 * docs-tree namespace of short guides, so an agent can read one guide at a
 * time. A human reader keeps one full page per topic, at the same URL and in
 * the same sidebar spot, whatever the split.
 *
 * @input A docs reader with the CLI docs API's shape
 *   (`docs(topic, section, options)` from `@astryxdesign/cli/api`) and the
 *   flat topics the site already built.
 * @output Doc pages ({topic, title, description, category, sections, and
 *   the sidebar `parent` of a page shown under another}) and redirects from
 *   each guide's own slug to its section on the full page.
 * @position Used by generate-data.mjs; tested on its own with a fake reader.
 */

/**
 * Root namespaces that have no page of their own at their slug: /docs/cli is
 * the @astryxdesign/cli package page. Their pages are listed in
 * GUIDE_NAMESPACE_PAGES; a guide below them that no such page holds keeps a
 * page of its own.
 */
export const GUIDE_PAGE_NAMESPACES = new Set(['cli']);

/**
 * The pages a root namespace in GUIDE_PAGE_NAMESPACES shows besides one page
 * per guide: each is one full page of the namespace at `route` (minus the
 * routes in `except`, which another page holds), at `slug`, so every guide
 * slug below it redirects to its section there. `aliases` are older slugs
 * that redirect to the page. The integration guides that `cli` once held as
 * two such pages now sit under `authoring`, an ordinary root namespace.
 * @type {Map<string, Array<{route: string, slug: string, title: string, except?: string[], aliases?: string[]}>>}
 */
export const GUIDE_NAMESPACE_PAGES = new Map();

/**
 * Nested namespaces that have a page of their own instead of a part of their
 * root namespace's page, by root. The root page leaves each one out, and each
 * one is a full page at its route's slug, with `parent` set to the root page's
 * slug so the sidebar shows it under that page.
 * @type {Map<string, string[]>}
 */
export const NESTED_NAMESPACE_PAGES = new Map();

/**
 * Pages the sidebar shows under another page, child slug to parent slug. The
 * child keeps its URL and moves into its parent's sidebar group. A nested
 * namespace's page (NESTED_NAMESPACE_PAGES) has its root page as parent with
 * no entry here.
 * @type {Map<string, string>}
 */
export const SIDEBAR_PARENTS = new Map([
  ['cli-experimental-icon-sets', 'icons'],
  ['cli-experimental-icon-set-files', 'icons'],
  ['styling', 'styling-overview'],
]);

/**
 * Older slugs of a root namespace's page, which redirect to it: global mode
 * was `cli/global`, and before that the `cli/install-once` guide; the
 * integration guides were the CLI Integrations page before `authoring` took
 * them.
 * @type {Map<string, string[]>}
 */
export const ROOT_PAGE_ALIASES = new Map([
  ['global', ['cli-global', 'cli-install-once']],
  ['authoring', ['cli-integrations', 'cli-integrations-overview']],
]);

/**
 * Older guide slugs of a root namespace, from before its guides moved there:
 * the integration guides were `cli/integrations/…` (/docs/cli-integrations-…)
 * before `authoring` took them, and the Writing docs page and one older alias
 * pointed into them. Each opens where its guide's new slug does.
 * @type {Map<string, {prefix: string, pages: Record<string, string>}>}
 */
export const MOVED_GUIDE_SLUGS = new Map([
  [
    'authoring',
    {
      prefix: 'cli-integrations',
      pages: {
        'cli-writing-docs': 'authoring-building-blocks-docs',
        'cli-integrations-docs-add-a-topic':
          'authoring-building-blocks-docs-add-a-topic',
      },
    },
  ],
]);

/**
 * Redirects for a root namespace's older guide slugs (MOVED_GUIDE_SLUGS),
 * read off the redirects its page made for the guides' new slugs.
 * @param {string} root
 * @param {Record<string, string>} redirects the page's redirects
 * @returns {Record<string, string>}
 */
export function movedGuideRedirects(root, redirects) {
  const moved = MOVED_GUIDE_SLUGS.get(root);
  if (!moved) return {};
  /** @type {Record<string, string>} */
  const out = {};
  for (const [slug, href] of Object.entries(redirects)) {
    if (slug.startsWith(`${root}-`)) {
      out[`${moved.prefix}-${slug.slice(root.length + 1)}`] = href;
    }
  }
  for (const [old, now] of Object.entries(moved.pages)) {
    if (Object.hasOwn(redirects, now)) out[old] = redirects[now];
  }
  return out;
}

/**
 * Flat topics whose full text the site shows on another topic's page. The
 * theme split (before namespaces) left `theme` as a short overview and moved
 * its text to two flat topics, so the theme page shows those two in order in
 * place of the overview's pointers to them.
 */
export const MERGED_TOPICS = new Map([
  ['theme', ['use-a-theme', 'author-a-theme']],
]);

/**
 * Flat topics that are data for other docs, not pages: `token-tables` is what
 * token references read, and the tokens page already shows every table.
 */
export const DATA_ONLY_TOPICS = new Map([['token-tables', 'tokens']]);

/**
 * Anchor ids of a page's sections, the way ReferenceDocView's outline builds
 * them: the slug of each title, numbered on repeats, with heading blocks
 * taking their own ids in between.
 * @param {Array<{title: string, content?: Array<{type?: string, text?: string}>}>} sections
 * @returns {string[]}
 */
export function sectionAnchors(sections) {
  const seen = new Map();
  const unique = (value, fallback) => {
    const base =
      value
        .toLowerCase()
        .trim()
        .replace(/[^a-z0-9]+/g, '-')
        .replace(/^-+|-+$/g, '') || fallback;
    const count = seen.get(base) ?? 0;
    seen.set(base, count + 1);
    return count === 0 ? base : `${base}-${count + 1}`;
  };
  return sections.map(section => {
    const id = unique(section.title, 'section');
    for (const block of section.content ?? []) {
      if (block?.type === 'heading' && block.text) {
        unique(`${section.title} ${block.text}`, `${id}-heading`);
      }
    }
    return id;
  });
}

/** A docs-tree route as a site slug: `layout/scaffold` is `layout-scaffold`. */
export const routeSlug = route => route.replaceAll('/', '-');

/**
 * The docsite renders token tables itself, so a resolved token reference is
 * not copied into the registry.
 * @param {any[]} sections
 */
export function withoutResolvedTokens(sections) {
  return sections.map(section => ({
    ...section,
    content: (section.content ?? []).map(block => {
      if (block?.type !== 'token-ref') return block;
      const {resolved: _resolved, ...authored} = block;
      return authored;
    }),
  }));
}

/**
 * Doc text with its CLI commands shown the way a reader runs them. Docs write
 * commands as bare `astryx ...`; the CLI prefixes them when it prints a doc,
 * and the docsite does the same with its own door name. `show(text, lang)`
 * prefixes the commands in one piece of text: prose and list items (`lang`
 * null), or one code block's body in its language. A table cell that is a
 * whole command is prefixed too, the way `astryx docs` prints it.
 * @param {any[]} sections
 * @param {(text: string, lang?: string | null) => string} show
 * @param {string} stem the invocation `show` prefixes with
 */
export function withCliCommands(sections, show, stem) {
  /** @param {string} cell */
  const cell = cell =>
    /^astryx(\s|$)/.test(cell ?? '')
      ? `${stem}${cell.slice('astryx'.length)}`
      : show(cell ?? '');
  return sections.map(section => ({
    ...section,
    content: (section.content ?? []).map(block => {
      switch (block?.type) {
        case 'prose':
        case 'heading':
          return {...block, text: show(block.text ?? '')};
        case 'code':
          return {...block, code: show(block.code ?? '', block.lang ?? '')};
        case 'list':
          return {...block, items: (block.items ?? []).map(item => show(item))};
        case 'table':
          return {...block, rows: (block.rows ?? []).map(row => row.map(cell))};
        default:
          return block;
      }
    }),
  }));
}

/**
 * The sidebar group of a namespace page: the namespace's own category when it
 * declares one, otherwise `foundations` when every guide under it is a
 * foundations doc, otherwise `guide`.
 * @param {string | null | undefined} own
 * @param {Array<string | null | undefined>} guideCategories
 */
export function namespaceCategory(own, guideCategories) {
  if (own) return own;
  return guideCategories.length > 0 &&
    guideCategories.every(category => category === 'foundations')
    ? 'foundations'
    : 'guide';
}

/**
 * One full page for a namespace: every guide under it, compiled in tree
 * order, as `astryx docs <route> --depth all --detail full` reads it. Each
 * guide and nested namespace keeps its slug as a redirect to where its text
 * starts on the page. Typed docs (commands, API docs) open only in
 * `astryx docs` and add nothing to the page.
 *
 * A namespace with no guide placed under it (a generated topic level, Guides
 * or Foundations, whose children are flat topics with pages of their own) has
 * no page.
 * @param {(topic?: string, section?: string, options?: object) => Promise<any>} readDocs
 * @param {string} route
 * @param {{slug?: string, title?: string, except?: string[], aliases?: string[]}} [options]
 *   the page's slug and title when they are not the route's, routes below it
 *   that another page holds, and older slugs that redirect to it
 * @returns {Promise<{page: object, redirects: Record<string, string>} | null>}
 */
export async function namespacePage(readDocs, route, options = {}) {
  const {slug = route, title, except = [], aliases = []} = options;
  const excluded = child =>
    except.some(skip => child === skip || child.startsWith(`${skip}/`));
  const read = await readDocs(route, undefined, {depth: 'all', detail: 'full'});
  if (read?.type !== 'docs.node' || read.data.kind !== 'namespace') return null;
  const node = read.data;
  const sections = [];
  /** @type {Array<[string, number]>} slug and index of its first section */
  const starts = [];
  const guideCategories = [];
  if (node.content?.length > 0) {
    sections.push({title: 'Overview', content: node.content});
  }
  const walk = async slots => {
    for (const slot of slots ?? []) {
      for (const child of slot.children) {
        if (!child.route.startsWith(`${route}/`)) continue;
        if (excluded(child.route)) continue;
        if (child.kind === 'generic') {
          const detail = await readDocs(child.route);
          guideCategories.push(detail?.data?.category ?? null);
          starts.push([routeSlug(child.route), sections.length]);
          sections.push(...withoutResolvedTokens(child.sections ?? []));
        } else if (child.kind === 'namespace') {
          starts.push([routeSlug(child.route), sections.length]);
          if (child.content?.length > 0) {
            sections.push({title: child.title, content: child.content});
          }
          await walk(child.slots);
        }
      }
    }
  };
  await walk(node.slots);
  if (guideCategories.length === 0) return null;

  const anchors = sectionAnchors(sections);
  const href = `/docs/${slug}`;
  const redirects = {};
  for (const [guideSlug, index] of starts) {
    redirects[guideSlug] =
      index < sections.length ? `${href}#${anchors[index]}` : href;
  }
  for (const alias of [routeSlug(route), ...aliases]) {
    if (alias !== slug) redirects[alias] = href;
  }
  return {
    page: {
      topic: slug,
      title: title || node.title || route,
      description: node.summary || '',
      category: namespaceCategory(node.category, guideCategories),
      sections,
    },
    redirects,
  };
}

/**
 * The pages of a root namespace: its own page without its nested namespaces
 * that have a page of their own, and one page for each of those, marked with
 * the root page as its `parent`. A namespace with no guide below it has no
 * page.
 * @param {(topic?: string, section?: string, options?: object) => Promise<any>} readDocs
 * @param {string} root
 * @param {{aliases?: string[], nested?: string[]}} [options] older slugs of
 *   the root page, and the nested namespaces with a page of their own
 *   (NESTED_NAMESPACE_PAGES by default)
 * @returns {Promise<{root: {page: object, redirects: Record<string, string>} | null, nested: Array<{page: object, redirects: Record<string, string>}>}>}
 */
export async function rootNamespacePages(readDocs, root, options = {}) {
  const {
    aliases = [],
    nested: nestedRoutes = NESTED_NAMESPACE_PAGES.get(root) ?? [],
  } = options;
  const rootPage = await namespacePage(readDocs, root, {
    aliases,
    except: nestedRoutes,
  });
  const nested = [];
  for (const route of nestedRoutes) {
    const page = await namespacePage(readDocs, route, {slug: routeSlug(route)});
    if (!page) continue;
    if (rootPage) page.page.parent = rootPage.page.topic;
    nested.push(page);
  }
  return {root: rootPage, nested};
}

/**
 * Set the sidebar `parent` of each page that SIDEBAR_PARENTS names. Nesting is
 * one level deep, so a parent cannot have a parent of its own.
 * @param {Array<{topic: string, parent?: string}>} pages
 * @param {Map<string, string>} [parents]
 * @throws when an entry names a page that does not exist, or nests deeper
 *   than one level
 */
export function applySidebarParents(pages, parents = SIDEBAR_PARENTS) {
  const bySlug = new Map(pages.map(page => [page.topic, page]));
  for (const [child, parent] of parents) {
    const page = bySlug.get(child);
    if (!page || !bySlug.has(parent) || child === parent) {
      throw new Error(
        `docs: sidebar parent "${child}" -> "${parent}" needs two different pages.`,
      );
    }
    page.parent = parent;
  }
  for (const page of pages) {
    if (page.parent && bySlug.get(page.parent)?.parent) {
      throw new Error(
        `docs: "${page.topic}" is under "${page.parent}", which is itself under another page.`,
      );
    }
  }
  return pages;
}

/**
 * Apply MERGED_TOPICS and DATA_ONLY_TOPICS to the flat topics: a merged
 * topic's sections move onto its host page and its slug redirects there; a
 * data-only topic has no page. A host or part that is missing is skipped, so
 * the rule holds before and after the split that created it.
 * @param {Array<{topic: string, sections: any[]}>} topics
 * @returns {{topics: any[], redirects: Record<string, string>}}
 */
export function mergeFlatTopics(topics) {
  const bySlug = new Map(topics.map(topic => [topic.topic, topic]));
  const redirects = {};
  const dropped = new Set();
  for (const [host, parts] of MERGED_TOPICS) {
    const page = bySlug.get(host);
    const present = parts.filter(part => bySlug.has(part));
    if (!page || present.length === 0) continue;
    const sections = [];
    const starts = [];
    for (const part of present) {
      starts.push([part, sections.length]);
      sections.push(...bySlug.get(part).sections);
      dropped.add(part);
    }
    page.sections = sections;
    const anchors = sectionAnchors(sections);
    for (const [part, index] of starts) {
      redirects[part] = `/docs/${host}#${anchors[index]}`;
    }
  }
  for (const [topic, host] of DATA_ONLY_TOPICS) {
    if (!bySlug.has(topic)) continue;
    dropped.add(topic);
    redirects[topic] = `/docs/${host}`;
  }
  return {topics: topics.filter(topic => !dropped.has(topic.topic)), redirects};
}