blume 2.0.2 → 2.1.0

package/src/markdown/api-rail.ts

@@ -0,0 +1,259 @@
+import type { EvaluatedValue } from "../ai/component-markdown.ts";
+import { readStaticExpression } from "../ai/static-expression.ts";
+import { PARAM_LOCATIONS } from "../components/content/api-field.ts";
+import type { FieldValue } from "../components/content/api-field.ts";
+import {
+  AUTH_METHODS,
+  PLAYGROUND_MODES,
+  parseApiEndpoint,
+} from "../components/content/api-page.ts";
+import type {
+  EndpointField,
+  EndpointSpec,
+} from "../components/content/api-page.ts";
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+
+/**
+ * The right-hand column of a hand-written API page, as Mintlify renders one.
+ * Top-level `<RequestExample>` and `<ResponseExample>` move into an
+ * `<ApiRail>` at the end of the document, request examples first, and the
+ * render is flagged so the layout makes room for the column (see
+ * `ApiRail.astro`). Below `xl` the rail follows the page's content, and the
+ * examples are ordinary code groups there. An example nested in another
+ * component stays where it is written.
+ *
+ * A page with `api` frontmatter (`POST /v1/users`) also gets its endpoint: the
+ * method and path at the top of the page (`<ApiEndpoint>`), and at the head of
+ * the rail a Try it panel and request samples (`<ApiPlayground>`) built from
+ * the page's `<ParamField>`s, which the plugin collects here, nested body
+ * fields included (see `components/content/api-page.ts`).
+ */
+
+/** The render-frontmatter key that tells the layout a page has a rail. */
+export const API_RAIL_KEY = "blumeApiRail";
+
+/** The components that move to the rail, in the order they stack there. */
+const RAIL_COMPONENTS = ["RequestExample", "ResponseExample"];
+
+/** The root, as the plugin's `after` hook receives it. */
+interface RailRoot {
+  children: MdastNode[];
+}
+
+/** The slice of Satteri's visitor context the plugin uses. */
+export interface ApiRailContext {
+  appendChild: (node: RailRoot, child: MdastNode) => void;
+  data?: { astro?: { frontmatter?: Record<string, EvaluatedValue> } };
+  insertChildAt: (node: RailRoot, index: number, child: MdastNode) => void;
+  removeNode: (node: MdastNode) => void;
+}
+
+/**
+ * A detached copy of a node Satteri materialized lazily: its own fields,
+ * children included, without the arena handles that tie it to its old place.
+ * Appending the original instead would move an empty shell.
+ */
+const detach = (node: MdastNode): MdastNode =>
+  JSON.parse(
+    JSON.stringify(node, (key: string, value: MdastValue) =>
+      key === "_id" || key === "_resolver" ? undefined : value
+    )
+  );
+
+const isName = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+const railIndex = (node: MdastNode): number =>
+  node.type === "mdxJsxFlowElement" && isName(node.name)
+    ? RAIL_COMPONENTS.indexOf(node.name)
+    : -1;
+
+/** An element's name, when it is a JSX element. */
+const elementName = (node: MdastNode): string | undefined =>
+  node.type === "mdxJsxFlowElement" && isName(node.name)
+    ? node.name
+    : undefined;
+
+const isNode = (value: MdastValue): value is MdastNode =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A node's children, when it has any. */
+const childrenOf = (node: MdastNode): MdastNode[] =>
+  Array.isArray(node.children) ? node.children.filter(isNode) : [];
+
+/** One JSX attribute, as the parser leaves it. */
+interface JsxAttribute {
+  name?: string;
+  type: string;
+  value?: string | { value: string } | null;
+}
+
+const isAttribute = (value: MdastValue): value is JsxAttribute & MdastNode =>
+  isNode(value) && value.type === "mdxJsxAttribute";
+
+/** An element's attributes, name to value. */
+interface AttributeValues {
+  [name: string]: EvaluatedValue;
+}
+
+/**
+ * An element's attributes as values: text, shorthand flags as `true`, and
+ * expressions read as literal data (see `ai/static-expression.ts`); one that
+ * isn't literal is left out.
+ */
+const attributeValues = (
+  node: MdastNode,
+  frontmatter: Record<string, EvaluatedValue> | undefined
+): AttributeValues => {
+  const values: AttributeValues = {};
+  const attributes = Array.isArray(node.attributes) ? node.attributes : [];
+  for (const attribute of attributes.filter(isAttribute)) {
+    const { name, value } = attribute;
+    if (!name) {
+      continue;
+    }
+    if (value === null || value === undefined) {
+      values[name] = true;
+    } else if (isName(value)) {
+      values[name] = value;
+    } else {
+      const read = readStaticExpression(value.value, frontmatter);
+      if (read.ok) {
+        values[name] = read.value;
+      }
+    }
+  }
+  return values;
+};
+
+const isFlag = (value: EvaluatedValue): boolean =>
+  value === true || value === "true";
+
+/** A `<ParamField>`'s values as an endpoint field, or `null` with no location. */
+const endpointField = (values: AttributeValues): EndpointField | null => {
+  const location = PARAM_LOCATIONS.find((key) => isName(values[key]));
+  const name = location ? values[location] : undefined;
+  if (!(location && isName(name))) {
+    return null;
+  }
+  const field: EndpointField = { location, name };
+  if (isName(values.type)) {
+    field.type = values.type;
+  }
+  if (isName(values.placeholder)) {
+    field.placeholder = values.placeholder;
+  }
+  if (isFlag(values.required)) {
+    field.required = true;
+  }
+  if (isFlag(values.deprecated)) {
+    field.deprecated = true;
+  }
+  if (values.default !== undefined) {
+    // SAFETY: an attribute's literal data is JSON-shaped; a frontmatter
+    // date only arrives through `frontmatter.*`, which a default never reads.
+    field.default = values.default as FieldValue;
+  }
+  return field;
+};
+
+/**
+ * The `<ParamField>`s under `nodes`, in document order. A field's own nested
+ * fields (in its `<Expandable>`) become its `fields`, the properties of the
+ * object it describes.
+ */
+const collectFields = (
+  nodes: MdastNode[],
+  frontmatter: Record<string, EvaluatedValue> | undefined
+): EndpointField[] =>
+  nodes.flatMap((node) => {
+    const nested = collectFields(childrenOf(node), frontmatter);
+    if (elementName(node) !== "ParamField") {
+      return nested;
+    }
+    const field = endpointField(attributeValues(node, frontmatter));
+    if (!field) {
+      return nested;
+    }
+    return nested.length > 0 ? [{ ...field, fields: nested }] : [field];
+  });
+
+/** The page's endpoint, when its `api` frontmatter names one. */
+const endpointSpec = (
+  root: RailRoot,
+  frontmatter: Record<string, EvaluatedValue> | undefined,
+  requestExample: boolean
+): EndpointSpec | null => {
+  const api = frontmatter?.api;
+  const endpoint = isName(api) ? parseApiEndpoint(api) : null;
+  if (!endpoint) {
+    return null;
+  }
+  const spec: EndpointSpec = {
+    fields: collectFields(root.children, frontmatter),
+    method: endpoint.method,
+    requestExample,
+    target: endpoint.target,
+  };
+  const authMethod = AUTH_METHODS.find(
+    (method) => method === frontmatter?.authMethod
+  );
+  if (authMethod) {
+    spec.authMethod = authMethod;
+  }
+  const playground = PLAYGROUND_MODES.find(
+    (mode) => mode === frontmatter?.playground
+  );
+  if (playground) {
+    spec.playground = playground;
+  }
+  return spec;
+};
+
+/** Where the endpoint header goes: after a front matter block, if any. */
+const headerIndex = (root: RailRoot): number =>
+  root.children.findIndex(
+    (node) => node.type !== "yaml" && node.type !== "toml"
+  );
+
+export const apiRailPlugin = () => ({
+  after(root: RailRoot, ctx: ApiRailContext) {
+    const frontmatter = ctx.data?.astro?.frontmatter;
+    const examples = root.children.filter((node) => railIndex(node) !== -1);
+    const spec = endpointSpec(
+      root,
+      frontmatter,
+      examples.some((node) => railIndex(node) === 0)
+    );
+    const specAttribute = spec
+      ? [jsxAttribute("spec", JSON.stringify(spec))]
+      : [];
+    const playground =
+      spec && spec.playground !== "none"
+        ? [jsxFlowElement("ApiPlayground", specAttribute, [])]
+        : [];
+    for (const example of examples) {
+      ctx.removeNode(example);
+    }
+    if (spec) {
+      ctx.insertChildAt(
+        root,
+        Math.max(headerIndex(root), 0),
+        jsxFlowElement("ApiEndpoint", specAttribute, [])
+      );
+    }
+    const rail = [
+      ...playground,
+      ...examples.toSorted((a, b) => railIndex(a) - railIndex(b)).map(detach),
+    ];
+    if (rail.length === 0) {
+      return;
+    }
+    ctx.appendChild(root, jsxFlowElement("ApiRail", [], rail));
+    if (frontmatter) {
+      frontmatter[API_RAIL_KEY] = true;
+    }
+  },
+  name: "blume-api-rail",
+});

package/src/markdown/base-links.ts

@@ -1,7 +1,7 @@
 import {
   isInternalPath,
+  withAuthoredBasePath,
   withBasePath,
-  withComposedBasePath,
 } from "../core/base-path.ts";
 import { servesRoute } from "../core/locale-links.ts";
 import type { MdastNode } from "./mdast.ts";
@@ -20,18 +20,6 @@ interface MdastUrlContext {
   setProperty: (node: MdastNode, key: "url", value: string) => void;
 }
 
-/**
- * A path whose final segment carries a file extension (`/spec.pdf`, `/logo.svg`)
- * — a public asset, which Blume serves from `public/` at the site root and
- * does *not* move under `basePath`, unless a page is served there: a dotted
- * route (`/releases/v1.2`) is based like any other page link, the same
- * served-route test the link checker and the locale rewrite apply.
- */
-const DOTTED_PATH = /\.[a-z0-9]+$/iu;
-
-/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
-const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
-
 /** Only a string URL can be rebased; MDAST allows null or absent urls. */
 const isUrl = (url: string | null | undefined): url is string =>
   typeof url === "string";
@@ -45,13 +33,15 @@ export interface BaseLinksPluginOptions {
 }
 
 /**
- * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
- * layered over the site-wide `basePath` — to root-relative internal page links
- * (`[x](/guide)` -> `/base/docs/guide`), so authors write links as if mounted
- * at root. Idempotent per layer (via `withComposedBasePath`, so a hand-written
- * `/docs/x` isn't double-prefixed) and inert for external URLs, fragments,
- * relative paths, images, and asset links. Only constructed when a base is set
- * (see `markdown/index.ts`).
+ * Satteri MDAST plugin that prepends the served-URL base to root-relative
+ * internal links, so authors write links as if mounted at root. A page link
+ * gains `deployment.base` layered over the site-wide `basePath` (`[x](/guide)`
+ * -> `/base/docs/guide`); a public asset — an image, or a link to a file like
+ * `/spec.pdf` (see `withAuthoredBasePath`) — gains `deployment.base` alone,
+ * since Astro serves `public/` under it but never under `basePath`.
+ * Idempotent per layer (a hand-written `/docs/x` isn't double-prefixed) and
+ * inert for external URLs, fragments, and relative paths. Only constructed
+ * when a base is set (see `markdown/index.ts`).
  */
 export const baseLinksPlugin = (
   deployBase: string,
@@ -78,30 +68,38 @@ export const baseLinksPlugin = (
     return cached.routes;
   };
 
-  /** Whether an internal `url` links a page rather than a public asset. */
-  const isPageLink = (url: string): boolean => {
-    const path = pathOf(url);
-    return (
-      !DOTTED_PATH.test(path) ||
-      servesRoute(servedRoutes(), withBasePath(basePath, path))
-    );
-  };
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean =>
+    servesRoute(servedRoutes(), route);
 
-  const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
+  /** Record `based(url)` on the node when its root-relative URL changes. */
+  const rebase = (
+    node: UrlNode,
+    ctx: MdastUrlContext,
+    based: (url: string) => string
+  ): void => {
     const { url } = node;
-    if (isUrl(url) && isInternalPath(url) && isPageLink(url)) {
-      const next = withComposedBasePath(deployBase, basePath, url);
+    if (isUrl(url) && isInternalPath(url)) {
+      const next = based(url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);
       }
     }
   };
-  // `link` covers inline links; `definition` covers reference-style link
-  // definitions (`[x]: /guide`). `image` is intentionally excluded — images are
-  // public assets served at the site root, unaffected by `basePath`.
+  const rebaseLink = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) =>
+      withAuthoredBasePath(deployBase, basePath, url, servesPage)
+    );
+  // An image is always a file, never a page: `public/` (or a generated asset
+  // endpoint), served under the deployment base but not `basePath`.
+  const rebaseImage = (node: UrlNode, ctx: MdastUrlContext): void =>
+    rebase(node, ctx, (url) => withBasePath(deployBase, url));
+  // `link` covers inline links; `definition` covers reference-style
+  // definitions (`[x]: /guide`), which a link or an image may cite.
   return {
-    definition: rebase,
-    link: rebase,
+    definition: rebaseLink,
+    image: rebaseImage,
+    link: rebaseLink,
     name: "blume-base-links",
   };
 };

package/src/markdown/code-title.ts

@@ -7,6 +7,12 @@
  *   language label.
  * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
+ * - the `wrap` keyword becomes `data-wrap`: this block's long lines wrap
+ *   instead of scrolling, as `markdown.code.wrap` does for every block.
+ * - the `expandable` keyword becomes `data-expandable` on a block of
+ *   {@link EXPANDABLE_MIN_LINES} lines or more: the theme shows its first
+ *   {@link EXPANDABLE_VISIBLE_LINES} lines, and the page script adds a toggle
+ *   that shows the rest in full. A shorter block renders as it is.
  */
 
 import {
@@ -16,9 +22,20 @@ import {
   RESERVED_META_KEYWORDS,
 } from "./fence-meta.ts";
 
+/** The lines a collapsed `expandable` block shows. */
+export const EXPANDABLE_VISIBLE_LINES = 10;
+
+/**
+ * The lines a block needs before `expandable` collapses it: a few more than it
+ * shows, so the toggle never hides a line or two behind a click.
+ */
+export const EXPANDABLE_MIN_LINES = 16;
+
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
   options: { meta?: { __raw?: string } };
+  /** The block's code, as highlighted. */
+  source?: string;
 }
 
 /** The `<pre>` hast node a Shiki `pre` hook receives. */
@@ -33,12 +50,6 @@ export interface CodeTitleTransformer {
 }
 
 const TITLE_ATTR = /(?:^|\s)title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
-const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
-
-// Quoted attrs are blanked before keyword/bare-token scans so a quoted value
-// can't leak tokens (`title="enable lineNumbers later"`).
-const withoutQuotedAttrs = (raw: string): string =>
-  raw.replace(QUOTED_ATTR, " ");
 
 // The first bare token is the title (```ts blume.config.ts): a non-empty token
 // that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
@@ -71,8 +82,14 @@ export const parseCodeTitle = (raw: string | undefined): string | undefined => {
   return metaTokens(raw).find(isTitleToken);
 };
 
-const hasLineNumbers = (raw: string | undefined): boolean =>
-  Boolean(raw && LINE_NUMBERS.test(withoutQuotedAttrs(raw)));
+// The shared tokenizer keeps a quoted attr whole, so a keyword inside a
+// quoted value (`title="enable lineNumbers later"`) is never a token of its own.
+const hasKeyword = (raw: string | undefined, keyword: string): boolean =>
+  metaTokens(raw).includes(keyword);
+
+/** How many lines a block's code runs to, a trailing newline aside. */
+export const lineCount = (source = ""): number =>
+  source === "" ? 0 : source.replace(/\r?\n$/u, "").split(/\r?\n/u).length;
 
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export const codeTitleTransformer = (): CodeTitleTransformer => ({
@@ -83,8 +100,17 @@ export const codeTitleTransformer = (): CodeTitleTransformer => ({
     if (title) {
       node.properties.dataTitle = title;
     }
-    if (hasLineNumbers(raw)) {
+    if (hasKeyword(raw, "lineNumbers")) {
       node.properties.dataLineNumbers = true;
     }
+    if (hasKeyword(raw, "wrap")) {
+      node.properties.dataWrap = true;
+    }
+    if (
+      hasKeyword(raw, "expandable") &&
+      lineCount(this.source) >= EXPANDABLE_MIN_LINES
+    ) {
+      node.properties.dataExpandable = true;
+    }
   },
 });