@hackcove/ui-react 0.10.1 → 0.10.3

package/dist/highlightConsole.js

@@ -0,0 +1,42 @@
+import { splitLines } from "./highlightKit.js";
+const CONSOLE_PROMPT = "$ ";
+/**
+ * The lines of a console session, marked: a line that starts with `$ ` is a command (`prompt`), and
+ * so is every line after a command line that ends with `\\`, which continues it. The rest is output.
+ */
+function consoleLines(code) {
+    let continued = false;
+    return splitLines(code).map(({ body, eol }) => {
+        const prompt = !continued && body.startsWith(CONSOLE_PROMPT);
+        const command = prompt || continued;
+        continued = command && body.endsWith("\\");
+        return { body, eol, command, prompt };
+    });
+}
+/** A shell session: `$ ` is the prompt, the command after it is bash, other lines are output. */
+export function scanConsole(code, emit, bash) {
+    for (const { body, eol, command, prompt } of consoleLines(code)) {
+        if (prompt)
+            emit("prompt", CONSOLE_PROMPT);
+        const text = prompt ? body.slice(CONSOLE_PROMPT.length) : body;
+        if (command)
+            bash(text, emit);
+        else
+            emit("plain", text);
+        emit("plain", eol);
+    }
+}
+/**
+ * What a console block's copy button copies: each command without its `$ `, plus the lines that
+ * continue it as written (the trailing `\\` and the indentation kept, so the paste runs), joined by
+ * newlines. Output is left out. A block with no `$ ` line has no commands, so it is copied as given.
+ */
+export function consoleCommands(code) {
+    const lines = consoleLines(code);
+    if (!lines.some((line) => line.prompt))
+        return code;
+    return lines
+        .filter((line) => line.command)
+        .map((line) => (line.prompt ? line.body.slice(CONSOLE_PROMPT.length) : line.body))
+        .join("\n");
+}

package/dist/highlightHtml.d.ts

@@ -0,0 +1,7 @@
+import type { Emit, Scanner } from "./highlightKit.js";
+/**
+ * HTML: comments, the doctype, tags with their attributes (a start tag may span lines), and text,
+ * which is plain. The content of `<script>` and `<style>` runs to the first closing tag of that
+ * name, wherever it falls, and is scanned with `script` (JS) or `style` (CSS).
+ */
+export declare function scanHtml(code: string, emit: Emit, script: Scanner, style: Scanner): void;

package/dist/highlightHtml.js

@@ -0,0 +1,132 @@
+import { sticky } from "./highlightKit.js";
+const OPEN = /<(\/?)([A-Za-z][\w:-]*)/y;
+const DOCTYPE = /<!doctype\b[^>]*>?/iy;
+const SPACE = /\s+/y;
+const ATTR = /[^\s"'<>/=]+/y;
+const UNQUOTED = /[^\s>"'=<`]+/y;
+/** `>` or `/>` where the tag ends. */
+function tagEnd(code, at) {
+    if (code.startsWith("/>", at))
+        return "/>";
+    return code.charAt(at) === ">" ? ">" : undefined;
+}
+/** The value after an `=`: a quoted string (which may span lines) or a bare run, which stays plain. */
+function takeValue(scan) {
+    const { code, at } = scan;
+    const c = code.charAt(at);
+    if (c === '"' || c === "'") {
+        const close = code.indexOf(c, at + 1);
+        const end = close === -1 ? code.length : close + 1;
+        scan.emit("string", code.slice(at, end));
+        scan.at = end;
+        return true;
+    }
+    const bare = sticky(UNQUOTED, code, at);
+    if (bare === undefined)
+        return false;
+    scan.emit("plain", bare);
+    scan.at += bare.length;
+    return true;
+}
+/** One piece of a tag's insides: space, `=`, a value, an attribute name, or a stray character. */
+function tagStep(scan) {
+    const { code, at } = scan;
+    const space = sticky(SPACE, code, at);
+    if (space !== undefined) {
+        scan.emit("plain", space);
+        scan.at += space.length;
+        return;
+    }
+    if (code.charAt(at) === "=") {
+        scan.emit("plain", "=");
+        scan.afterEquals = true;
+        scan.at += 1;
+        return;
+    }
+    const wasAfterEquals = scan.afterEquals;
+    scan.afterEquals = false;
+    if (wasAfterEquals && takeValue(scan))
+        return;
+    const name = sticky(ATTR, code, at);
+    scan.emit(name === undefined ? "plain" : "attr", name ?? code.charAt(at));
+    scan.at += name?.length ?? 1;
+}
+/** The rest of a tag from just past its name; says where it ended and how. */
+function scanTag(code, from, emit) {
+    const scan = { code, emit, at: from, afterEquals: false };
+    while (scan.at < code.length) {
+        const end = tagEnd(code, scan.at);
+        if (end !== undefined) {
+            emit("plain", end);
+            return { end: scan.at + end.length, closed: true, selfClosed: end === "/>" };
+        }
+        tagStep(scan);
+    }
+    return { end: code.length, closed: false, selfClosed: false };
+}
+/** A comment (which may span lines) or a doctype at `at`: where it ends and its colour. */
+function special(code, at) {
+    if (code.startsWith("<!--", at)) {
+        const close = code.indexOf("-->", at + 4);
+        return { end: close === -1 ? code.length : close + 3, kind: "comment" };
+    }
+    const doctype = sticky(DOCTYPE, code, at);
+    return doctype === undefined ? undefined : { end: at + doctype.length, kind: "keyword" };
+}
+/** The `<script>` or `<style>` start tag whose content is another language, if this is one. */
+function rawOf(name, tag, embedded) {
+    if (!tag.closed || tag.selfClosed)
+        return undefined;
+    if (name === "script")
+        return { name, scan: embedded.script };
+    return name === "style" ? { name, scan: embedded.style } : undefined;
+}
+/** The content of a `<script>` or `<style>`, up to the first closing tag of that name, wherever it falls. */
+function rawContent(code, at, raw, emit) {
+    const closing = new RegExp(`</${raw.name}(?=[\\s/>]|$)`, "gi");
+    closing.lastIndex = at;
+    const end = closing.exec(code)?.index ?? code.length;
+    raw.scan(code.slice(at, end), emit);
+    return end;
+}
+/** A tag at a `<`, or a lone `<` that opens nothing. Returns the index to carry on from. */
+function scanElement(code, at, emit, embedded) {
+    OPEN.lastIndex = at;
+    const open = OPEN.exec(code);
+    if (open === null) {
+        emit("plain", "<");
+        return at + 1;
+    }
+    const [whole, slash = "", tagName = ""] = open;
+    emit("plain", `<${slash}`);
+    emit("tag", tagName);
+    const tag = scanTag(code, at + whole.length, emit);
+    const raw = slash === "" ? rawOf(tagName.toLowerCase(), tag, embedded) : undefined;
+    return raw === undefined ? tag.end : rawContent(code, tag.end, raw, emit);
+}
+/** Markup at a `<`: a comment, a doctype or a tag. Returns the index to carry on from. */
+function scanMarkup(code, at, emit, embedded) {
+    const found = special(code, at);
+    if (found === undefined)
+        return scanElement(code, at, emit, embedded);
+    emit(found.kind, code.slice(at, found.end));
+    return found.end;
+}
+/**
+ * HTML: comments, the doctype, tags with their attributes (a start tag may span lines), and text,
+ * which is plain. The content of `<script>` and `<style>` runs to the first closing tag of that
+ * name, wherever it falls, and is scanned with `script` (JS) or `style` (CSS).
+ */
+export function scanHtml(code, emit, script, style) {
+    let at = 0;
+    while (at < code.length) {
+        if (code.charAt(at) === "<") {
+            at = scanMarkup(code, at, emit, { script, style });
+            continue;
+        }
+        const next = code.indexOf("<", at);
+        const end = next === -1 ? code.length : next;
+        emit("plain", code.slice(at, end));
+        at = end;
+    }
+}

package/dist/highlightKit.d.ts

@@ -0,0 +1,16 @@
+/** The pieces the scanners in `highlight*.ts` share. */
+export type TokenKind = "plain" | "comment" | "keyword" | "string" | "number" | "tag" | "attr" | "function" | "prompt";
+export type Token = {
+    text: string;
+    kind: TokenKind;
+};
+export type Emit = (kind: TokenKind, text: string) => void;
+/** A scanner for a whole run of code, given to a scanner of a language that holds another. */
+export type Scanner = (code: string, emit: Emit) => void;
+/** The text a sticky `pattern` matches at `at`, or `undefined`. */
+export declare function sticky(pattern: RegExp, code: string, at: number): string | undefined;
+/** Each line of `code` without its line break, and the break (`\n`, `\r\n` or nothing at the end). */
+export declare function splitLines(code: string): {
+    body: string;
+    eol: string;
+}[];

package/dist/highlightKit.js

@@ -0,0 +1,23 @@
+/** The pieces the scanners in `highlight*.ts` share. */
+/** The text a sticky `pattern` matches at `at`, or `undefined`. */
+export function sticky(pattern, code, at) {
+    pattern.lastIndex = at;
+    return pattern.exec(code)?.[0];
+}
+/** Each line of `code` without its line break, and the break (`\n`, `\r\n` or nothing at the end). */
+export function splitLines(code) {
+    const out = [];
+    let at = 0;
+    for (;;) {
+        const newline = code.indexOf("\n", at);
+        const end = newline === -1 ? code.length : newline;
+        const bodyEnd = end > at && code.charAt(end - 1) === "\r" ? end - 1 : end;
+        out.push({
+            body: code.slice(at, bodyEnd),
+            eol: code.slice(bodyEnd, newline === -1 ? end : end + 1),
+        });
+        if (newline === -1)
+            return out;
+        at = newline + 1;
+    }
+}

package/dist/highlightYaml.d.ts

@@ -0,0 +1,3 @@
+import type { Emit } from "./highlightKit.js";
+/** Line by line. The lines of a block scalar are one plain run: no comment or key is read in them. */
+export declare function scanYaml(code: string, emit: Emit): void;

package/dist/highlightYaml.js

@@ -0,0 +1,143 @@
+import { splitLines, sticky } from "./highlightKit.js";
+const YAML_MARKER = /-(?: +|$)/y;
+const YAML_KEYWORDS = /^(?:true|false|null|~)$/;
+const YAML_NUMBER = /^-?\d[\d._]*$/;
+const YAML_BLOCK_HEADER = /^[|>](?:[1-9][-+]?|[-+][1-9]?)?$/;
+/**
+ * The index past the quoted scalar at `at` in a YAML line, or `undefined`. A single-quoted scalar
+ * escapes a quote by doubling it (`'it''s'`), a double-quoted one with a backslash.
+ */
+function quotedEnd(line, at) {
+    const quote = line.charAt(at);
+    if (quote !== '"' && quote !== "'")
+        return undefined;
+    let i = at + 1;
+    while (i < line.length) {
+        const c = line.charAt(i);
+        if (quote === '"' && c === "\\")
+            i += 2;
+        else if (c !== quote)
+            i += 1;
+        else if (quote === "'" && line.charAt(i + 1) === "'")
+            i += 2;
+        else
+            return i + 1;
+    }
+    return line.length;
+}
+/** What follows a quoted scalar: spaces, then perhaps a comment. */
+function trailing(rest, emit) {
+    const comment = /^(\s+)(#.*)$/.exec(rest);
+    if (comment === null)
+        emit("plain", rest);
+    else {
+        emit("plain", comment[1] ?? "");
+        emit("comment", comment[2] ?? "");
+    }
+}
+/** A quoted key: the closing quote must be followed by `:` and a space or the line end. */
+function quotedKey(line, at) {
+    const end = quotedEnd(line, at);
+    if (end === undefined || end - at < 2 || line.charAt(end - 1) !== line.charAt(at))
+        return undefined;
+    return /^:(?:\s|$)/.test(line.slice(end)) ? { end, kind: "string" } : undefined;
+}
+/** An unquoted key: the text up to the first `:` that is followed by a space or the line end. */
+function plainKey(line, at) {
+    if ("#[{|>".includes(line.charAt(at)))
+        return undefined;
+    const colon = /:(?:\s|$)/.exec(line.slice(at));
+    if (colon === null || colon.index === 0)
+        return undefined;
+    const text = line.slice(at, at + colon.index);
+    if (/(?:^|\s)#/.test(text))
+        return undefined;
+    return { end: at + text.trimEnd().length, kind: "attr" };
+}
+/** The mapping key at `at`: where its text ends (before the `:`) and its colour. */
+function keyAt(line, at) {
+    const first = line.charAt(at);
+    if (first === "")
+        return undefined;
+    return first === '"' || first === "'" ? quotedKey(line, at) : plainKey(line, at);
+}
+/** The colour of an unquoted scalar read whole. */
+function scalarKind(scalar) {
+    if (YAML_NUMBER.test(scalar))
+        return "number";
+    return YAML_KEYWORDS.test(scalar) ? "keyword" : "plain";
+}
+/** A value: a quoted string, or an unquoted scalar up to a comment. True when it opens a block scalar. */
+function emitValue(line, from, emit) {
+    const value = line.slice(from);
+    if (value === "")
+        return false;
+    if (value.startsWith("#")) {
+        emit("comment", value);
+        return false;
+    }
+    const quoted = quotedEnd(line, from);
+    if (quoted !== undefined) {
+        emit("string", line.slice(from, quoted));
+        trailing(line.slice(quoted), emit);
+        return false;
+    }
+    const comment = /\s#/.exec(value);
+    const scalar = line.slice(from, comment === null ? line.length : from + comment.index).trimEnd();
+    emit(scalarKind(scalar), scalar);
+    const commentAt = comment === null ? line.length : from + comment.index + 1;
+    emit("plain", line.slice(from + scalar.length, commentAt));
+    emit("comment", line.slice(commentAt));
+    return YAML_BLOCK_HEADER.test(scalar);
+}
+/** The `- ` markers from `at`: where the content starts, and the column of the last dash. */
+function emitMarkers(line, at, emit) {
+    let column = at;
+    let next = at;
+    for (;;) {
+        const marker = sticky(YAML_MARKER, line, next);
+        if (marker === undefined)
+            return { at: next, column };
+        column = next;
+        emit("plain", marker);
+        next += marker.length;
+    }
+}
+/**
+ * One YAML line. Returns the column its block scalar's lines must be indented past, when it ends
+ * in `|` or `>`: the key's own column, after any `- ` markers (a key-less item uses its dash's).
+ */
+function scanLine(line, emit) {
+    const indent = line.length - line.trimStart().length;
+    emit("plain", line.slice(0, indent));
+    if (line.charAt(indent) === "#") {
+        emit("comment", line.slice(indent));
+        return undefined;
+    }
+    const markers = emitMarkers(line, indent, emit);
+    let { at, column } = markers;
+    const key = keyAt(line, at);
+    if (key !== undefined) {
+        column = at;
+        emit(key.kind, line.slice(at, key.end));
+        const colon = line.indexOf(":", key.end);
+        emit("plain", line.slice(key.end, colon + 1));
+        at = colon + 1;
+    }
+    const gap = line.length - at - line.slice(at).trimStart().length;
+    emit("plain", line.slice(at, at + gap));
+    return emitValue(line, at + gap, emit) ? column : undefined;
+}
+/** Line by line. The lines of a block scalar are one plain run: no comment or key is read in them. */
+export function scanYaml(code, emit) {
+    let block;
+    for (const { body, eol } of splitLines(code)) {
+        const indent = body.length - body.trimStart().length;
+        if (block !== undefined && (body.trim() === "" || indent > block)) {
+            emit("plain", body + eol);
+            continue;
+        }
+        block = scanLine(body, emit);
+        emit("plain", eol);
+    }
+}

package/dist/index.d.ts

@@ -77,7 +77,7 @@ export { MediaTile, type MediaTileProps } from "./MediaTile.js";
 export { ScrollStrip, type ScrollStripProps } from "./ScrollStrip.js";
 export { TextLink, type TextLinkSize } from "./TextLink.js";
 export { ToolCallCard } from "./ToolCallCard.js";
-export { Caption, Display, Lead, Overline, PageHeading, SectionHeading, SubsectionHeading, type SubsectionHeadingSize, Text, type TextTone, type TypographyColor, type TypographyProps, } from "./typography.js";
+export { Caption, Display, Lead, Overline, PageHeading, Prose, SectionHeading, SubsectionHeading, type SubsectionHeadingSize, Text, type TextTone, type TypographyColor, type TypographyProps, } from "./typography.js";
 export { DateField, type DateFieldProps } from "./DateField.js";
 export { fromISODate, toISODate } from "./isoDate.js";
 export type { CalendarDate } from "@internationalized/date";

package/dist/index.js

@@ -73,6 +73,6 @@ export { MediaTile } from "./MediaTile.js";
 export { ScrollStrip } from "./ScrollStrip.js";
 export { TextLink } from "./TextLink.js";
 export { ToolCallCard } from "./ToolCallCard.js";
-export { Caption, Display, Lead, Overline, PageHeading, SectionHeading, SubsectionHeading, Text, } from "./typography.js";
+export { Caption, Display, Lead, Overline, PageHeading, Prose, SectionHeading, SubsectionHeading, Text, } from "./typography.js";
 export { DateField } from "./DateField.js";
 export { fromISODate, toISODate } from "./isoDate.js";

package/dist/scrollEdges.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export declare function useScrollEdges(element: HTMLElement | null, axis: "x" | "y"): void;

package/dist/scrollEdges.js

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export function useScrollEdges(element, axis) {
+    useEffect(() => {
+        if (!element)
+            return undefined;
+        const el = element;
+        const update = () => {
+            const [position, scrollSize, clientSize] = axis === "x"
+                ? [el.scrollLeft, el.scrollWidth, el.clientWidth]
+                : [el.scrollTop, el.scrollHeight, el.clientHeight];
+            const start = position > 1;
+            const end = scrollSize - clientSize - position > 1;
+            el.toggleAttribute("data-more-start", start);
+            el.toggleAttribute("data-more-end", end);
+            el.toggleAttribute("data-more", start || end);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
+        resize?.observe(el);
+        for (const child of el.children)
+            resize?.observe(child);
+        return () => {
+            el.removeEventListener("scroll", update);
+            resize?.disconnect();
+        };
+    });
+}

package/dist/stickyColumn.d.ts

@@ -15,3 +15,13 @@ export declare const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)]
 export declare const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
 export declare const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
 export declare const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";
+/**
+ * While a sticky column's scroller has more to scroll to on a side, that edge fades out (a mask, so
+ * it follows any theme), the way AppShell's header row does. `useScrollEdges` sets `data-more-start`
+ * / `data-more-end` (and `data-more` for either); a column that fits has none and is untouched.
+ * Each is prefixed with its breakpoint, below which the column neither sticks nor scrolls and gets
+ * no mask. While the scroller itself holds the keyboard's tab stop (`focus-visible`) the mask is
+ * off, since it would hide the focus ring (an outline) at the faded edges.
+ */
+export declare const STICKY_FADE_MD = "md:data-more-start:[--fade-start:1.5rem] md:data-more-end:[--fade-end:1.5rem] md:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] md:data-more:focus-visible:[mask-image:none]";
+export declare const STICKY_FADE_LG = "lg:data-more-start:[--fade-start:1.5rem] lg:data-more-end:[--fade-end:1.5rem] lg:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] lg:data-more:focus-visible:[mask-image:none]";

package/dist/stickyColumn.js

@@ -15,3 +15,13 @@ export const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)] md:self
 export const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
 export const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
 export const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";
+/**
+ * While a sticky column's scroller has more to scroll to on a side, that edge fades out (a mask, so
+ * it follows any theme), the way AppShell's header row does. `useScrollEdges` sets `data-more-start`
+ * / `data-more-end` (and `data-more` for either); a column that fits has none and is untouched.
+ * Each is prefixed with its breakpoint, below which the column neither sticks nor scrolls and gets
+ * no mask. While the scroller itself holds the keyboard's tab stop (`focus-visible`) the mask is
+ * off, since it would hide the focus ring (an outline) at the faded edges.
+ */
+export const STICKY_FADE_MD = "md:data-more-start:[--fade-start:1.5rem] md:data-more-end:[--fade-end:1.5rem] md:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] md:data-more:focus-visible:[mask-image:none]";
+export const STICKY_FADE_LG = "lg:data-more-start:[--fade-start:1.5rem] lg:data-more-end:[--fade-end:1.5rem] lg:data-more:[mask-image:linear-gradient(to_bottom,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)] lg:data-more:focus-visible:[mask-image:none]";

package/dist/typography.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithoutRef, type ElementType, type ReactElement, type ReactNode } from "react";
+import type { Passthrough } from "./props.js";
 import type { Size } from "./size.js";
 export type TypographyColor = "default" | "secondary" | "tertiary" | "muted" | "brand";
 /**
@@ -77,8 +78,31 @@ export declare const PageHeading: {
     <E extends ElementType = "h1">(props: TypographyProps<E>): ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
     displayName: string;
 };
+/** True inside a `Prose`, where the text roles take the long-form scale. Internal. */
+export declare function useProse(): boolean;
 /**
- * Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets
+ * Sets the text roles back to the app scale around what a component renders itself (a `Dialog`, a
+ * `Drawer`, an `EmptyState`), so one opened from a docs page looks as it does anywhere else.
+ * Renders no element. Internal: not exported from the package.
+ */
+export declare function AppScale({ children }: {
+    children?: ReactNode;
+}): ReactElement;
+/**
+ * Long-form content, for a docs page or an article. A block (`div`) that sets text-base/7 on itself,
+ * so a bare `<li>` or text node inside reads at 16px, and puts the text roles inside it on the
+ * prose scale: `Text` text-base/7, `SectionHeading` text-2xl/8, `SubsectionHeading` `lg` text-2xl/8,
+ * `md` text-xl/7 and `sm` text-base/7 (a semibold line at body size), and the box of a `Callout`
+ * text-base/7. Every other role keeps its size. Nothing outside a `Prose` changes, and a `Dialog`,
+ * `Drawer` or `EmptyState` inside one is back on the app scale. An app screen never uses it: wrap the
+ * body of a docs page or an article, inside a `ProseLayout`, a `SidebarLayout` or anywhere else.
+ */
+export declare function Prose({ children, ...rest }: {
+    children?: ReactNode;
+} & Passthrough): ReactElement;
+/**
+ * Top-level section header. `h2`, text-base/6 semibold, primary text (text-2xl/8 semibold tight
+ * inside a `Prose`). `rule` sets
  * a hairline under it (the `Divider` line colour) with the space either side of
  * the line built in. `description` is a muted line under the heading, outside the `<h2>`, so the
  * heading's name stays the title; the rule then sits under the description.
@@ -92,7 +116,9 @@ export declare function SectionHeading<E extends ElementType = "h2">({ rule, des
 export type SubsectionHeadingSize = Size;
 /**
  * Nested header. `h3`, text-base/6 semibold, primary text. `size` steps it down for a dense card
- * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. `truncate` keeps it on
+ * or up for a drawer or form-group title: `sm` (text-sm), `md` (default) or `lg`. Inside a `Prose`
+ * `md` is text-xl/7 (the h3 of a doc), `sm` text-base/7 (the h4: body size, set apart by its weight)
+ * and `lg` text-2xl/8, the size of a `SectionHeading` there. `truncate` keeps it on
  * one line and cuts it with an ellipsis where its container ends, the full text as the `title`.
  */
 export declare function SubsectionHeading<E extends ElementType = "h3">({ size, ...props }: TypographyProps<E> & {
@@ -115,7 +141,8 @@ export declare const Overline: {
 /** A fixed width for a run of text: `amount` is a money figure, right-aligned, at a width that lines a column up. */
 export type TextMinWidth = "amount";
 /**
- * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it
+ * Running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary (text-base/7
+ * inside a `Prose`). A block of it
  * stops at a readable line length (`max-w-[72ch]`), wherever it sits. `strong` emphasises it:
  * font-medium in the primary ink, unless `color` or `tone` says otherwise.
  * `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse.