Skip to content

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

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

/**
 * @file codeLinkifiers.ts
 * @input The text content of an inline code span.
 * @output The docs-site href that span points at, or null to leave it as
 *   plain code.
 * @position Consumed by InlineCode.tsx, which renders every inline code span
 *   on the site. Kept separate so the rules are unit-testable without React.
 *
 * Docs prose cites sibling topics as the literal CLI command — "Semantic
 * tokens, not hardcoded values (see `astryx docs tokens`)". That is what an
 * agent should type, so it stays copy-pasteable code; linkifying it gives a
 * human somewhere to click. Component mentions work the same way: authors
 * write `<InternationalizationProvider>` as literal code, and the span
 * resolves to that component's doc page.
 *
 * To teach the site a new kind of cross-reference, write a CodeLinkifier and
 * append it to LINKIFIERS.
 */

import {docRedirects, docTopics} from '../generated/docsRegistry';
import {components} from '../generated/componentRegistry';

/** Returns an href for a code span it recognizes, or null to pass. */
type CodeLinkifier = (code: string) => string | null;

const KNOWN_TOPICS = new Set(docTopics.map(d => d.topic));

/**
 * `astryx docs tokens` -> /docs/tokens, `astryx docs` -> the docs index.
 *
 * Anything after the topic — a section argument, or a flag like `--dense`
 * that only changes CLI output — still belongs to the topic's page. Unknown
 * topics return null so a renamed doc degrades to plain code, not a 404.
 */
const docTopic: CodeLinkifier = code => {
  const match =
    /^(?:npx (?:@astryxdesign\/cli(?:@\S+)?|astryx)|astryx) docs(?:\s+([a-z][\w-]*(?:\/[a-z][\w-]*)*))?(?:\s.*)?$/.exec(
      code,
    );
  if (!match) {
    return null;
  }
  const topic = match[1];
  if (topic == null) {
    return '/docs';
  }
  // A docs-tree guide has a slug named after its route, with "/" as "-": its
  // own page (`authoring/quick-start`), or a redirect to its section on
  // its namespace's page (`layout/scaffold` -> /docs/layout#scaffold).
  const slug = topic.replaceAll('/', '-');
  if (KNOWN_TOPICS.has(slug)) {
    return `/docs/${slug}`;
  }
  return docRedirects[slug] ?? null;
};

/** Every documented component and hook name; each has a /components page. */
const KNOWN_COMPONENTS = new Set(
  Object.values(components)
    .flat()
    .map(c => c.name),
);

/**
 * `Button`, `<InternationalizationProvider>`, `<Button />` -> the component's
 * doc page.
 *
 * A span has to be exactly one documented name — bare, or as a lone JSX tag —
 * so snippets like `<Button open>` and phrases that merely contain a name stay
 * plain code. Case-sensitive on purpose: `button` is the HTML element,
 * `Button` the component. XDS-prefixed aliases resolve to the unprefixed page,
 * matching the prose linkifier (changelogLinkify's linkifyComponents).
 */
const componentName: CodeLinkifier = code => {
  const jsx = /^<([A-Z][A-Za-z\d]*)\s*\/?>$/.exec(code);
  const name = jsx != null ? jsx[1] : code;
  if (KNOWN_COMPONENTS.has(name)) {
    return `/components/${name}`;
  }
  if (name.startsWith('XDS') && KNOWN_COMPONENTS.has(name.slice(3))) {
    return `/components/${name.slice(3)}`;
  }
  return null;
};

const LINKIFIERS: CodeLinkifier[] = [docTopic, componentName];

/** Resolve an inline code span to a docs href, or null to leave it alone. */
export function linkifyCode(code: string): string | null {
  const text = code.trim();
  for (const linkify of LINKIFIERS) {
    const href = linkify(text);
    if (href != null) {
      return href;
    }
  }
  return null;
}