shelving 1.212.0 → 1.214.0

package/extract/Extractor.js

@@ -20,8 +20,6 @@ export function mergeTreeElements(primary, secondary) {
         key: primary.key,
         props: {
             ...primary.props,
-            title: primary.props.title,
-            source: primary.props.source,
             description: primary.props.description ?? secondary.props.description,
             content: _mergeContent(primary.props.content, secondary.props.content),
             children: mergeElements(primary.props.children, secondary.props.children),

package/index.d.ts

@@ -6,7 +6,6 @@
 export * from "./api/index.js";
 export * from "./db/index.js";
 export * from "./error/index.js";
-export * from "./markup/index.js";
 export * from "./schema/index.js";
 export * from "./sequence/index.js";
 export * from "./store/index.js";

package/index.js

@@ -9,7 +9,7 @@ export * from "./error/index.js";
 // export * from "./firestore/client/index.js"; // Not exported.
 // export * from "./firestore/lite/index.js"; // Not exported.
 // export * from "./firestore/server/index.js"; // Not exported.
-export * from "./markup/index.js";
+// export * from "./markup/index.js"; // Not exported — `shelving/markup` now compiles JSX and imports React's JSX runtime.
 // export * from "./react/index.js"; // Not exported.
 export * from "./schema/index.js";
 // export * from "./ui/index.js"; // Not exported — shelving/ui requires a bundler (CSS Modules, JSX) and is consumed as source.

package/markup/render.d.ts

@@ -1,4 +1,4 @@
-import type { Elements } from "../util/element.js";
+import type { ReactNode } from "react";
 import type { MarkupOptions } from "./util/options.js";
 /**
  * Parse a text string as Markdownish syntax and render it as elements.
@@ -8,6 +8,6 @@ import type { MarkupOptions } from "./util/options.js";
  * @param options An options object for the render.
  * @param context The context to render in (defaults to `"block"`).
  *
- * @returns Elements, i.e. either a complete `Element`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns A React node — an element, a string, `null`, or an array of zero or more of those.
  */
-export declare function renderMarkup(input: string, options: MarkupOptions, context?: string): Elements;
+export declare function renderMarkup(input: string, options: MarkupOptions, context?: string): ReactNode;

package/markup/render.js

@@ -6,7 +6,7 @@
  * @param options An options object for the render.
  * @param context The context to render in (defaults to `"block"`).
  *
- * @returns Elements, i.e. either a complete `Element`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns A React node — an element, a string, `null`, or an array of zero or more of those.
  */
 export function renderMarkup(input, options, context = "block") {
     const arr = Array.from(_parseString(input, options, context));

package/markup/rule/blockquote.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { BLOCK_CONTENT_REGEXP, createBlockRegExp } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const PREFIX = ">";
@@ -11,9 +11,4 @@ export const BLOCKQUOTE_REGEXP = createBlockRegExp(`${PREFIX}${BLOCK_CONTENT_REG
  * - No spaces can appear before the `>` quote character.
  * - Quote block is only broken by `\n\n` two newline characters.
  */
-export const BLOCKQUOTE_RULE = createMarkupRule(BLOCKQUOTE_REGEXP, ([quote], options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "blockquote",
-    props: { children: renderMarkup(quote.replace(INDENT, ""), options, "block") },
-}), ["block", "list"]);
+export const BLOCKQUOTE_RULE = createMarkupRule(BLOCKQUOTE_REGEXP, ([quote], options, key) => _jsx("blockquote", { children: renderMarkup(quote.replace(INDENT, ""), options, "block") }, key), ["block", "list"]);

package/markup/rule/code.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { getRegExp } from "../../util/regexp.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { BLOCK_CONTENT_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const CODE_REGEXP = getRegExp(`(?<fence>\`+)(?<code>${BLOCK_CONTENT_REGEXP})\\k<fence>`);
@@ -10,9 +10,4 @@ const CODE_REGEXP = getRegExp(`(?<fence>\`+)(?<code>${BLOCK_CONTENT_REGEXP})\\k<
  * - Closing characters must exactly match opening characters.
  * - Same as Markdown syntax.
  */
-export const CODE_RULE = createMarkupRule(CODE_REGEXP, ({ groups: { code } }, _options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "code",
-    props: { children: code },
-}), ["inline", "list"], 10);
+export const CODE_RULE = createMarkupRule(CODE_REGEXP, ({ groups: { code } }, _options, key) => _jsx("code", { children: code }, key), ["inline", "list"], 10);

package/markup/rule/fenced.js

@@ -1,4 +1,4 @@
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { BLOCK_CONTENT_REGEXP, BLOCK_START_REGEXP, createBlockRegExp, LINE_CONTENT_REGEXP, LINE_SPACE_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const FENCE = "`{3,}|~{3,}";
@@ -16,19 +16,4 @@ const FENCED_REGEXP = createBlockRegExp(`(?<code>${BLOCK_CONTENT_REGEXP})`,
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
  */
-export const FENCED_RULE = createMarkupRule(FENCED_REGEXP, ({ groups: { title, code } }, _options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "pre",
-    props: {
-        children: {
-            $$typeof: REACT_ELEMENT_TYPE,
-            type: "code",
-            key: null,
-            props: {
-                title: title?.trim() || undefined,
-                children: code.trim(),
-            },
-        },
-    },
-}), ["block", "list"], 10);
+export const FENCED_RULE = createMarkupRule(FENCED_REGEXP, ({ groups: { title, code } }, _options, key) => (_jsx("pre", { children: _jsx("code", { title: title?.trim() || undefined, children: code.trim() }) }, key)), ["block", "list"], 10);

package/markup/rule/heading.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { createLineRegExp, LINE_CONTENT_REGEXP, LINE_SPACE_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const HEADING_REGEXP = createLineRegExp(`(?<prefix>#{1,6})(?:${LINE_SPACE_REGEXP}+(?<heading>${LINE_CONTENT_REGEXP}))?`);
@@ -9,9 +9,8 @@ const HEADING_REGEXP = createLineRegExp(`(?<prefix>#{1,6})(?:${LINE_SPACE_REGEXP
  * - `#` must be the first character on the line.
  * - Markdown's underline syntax is not supported (for simplification).
  */
-export const HEADING_RULE = createMarkupRule(HEADING_REGEXP, ({ groups: { prefix, heading = "" } }, options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: `h${prefix.length}`,
-    props: { children: renderMarkup(heading.trim(), options, "inline") },
-}), ["block"]);
+export const HEADING_RULE = createMarkupRule(HEADING_REGEXP, ({ groups: { prefix, heading = "" } }, options, key) => {
+    // The hash count picks the heading level; cast the dynamic tag to the known `h1`–`h6` set.
+    const Heading = `h${prefix.length}`;
+    return _jsx(Heading, { children: renderMarkup(heading.trim(), options, "inline") }, key);
+}, ["block"]);

package/markup/rule/inline.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { createWordRegExp } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 /** Map characters, e.g. `*`, to their coresponding HTML tag, e.g. `strong` */
@@ -18,9 +18,7 @@ const INLINE_REGEXP = createWordRegExp(`(?<wrap>(?<char>[${Object.keys(INLINE_CH
  * - Closing characters must exactly match opening characters.
  * - Different to Markdown: strong is always surrounded by `*asterisks*` and emphasis is always surrounded by `_underscores_` (strong isn't 'double emphasis').
  */
-export const INLINE_RULE = createMarkupRule(INLINE_REGEXP, ({ groups: { char, text } }, options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: INLINE_CHARS[char],
-    props: { children: renderMarkup(text, options, "inline") },
-}), ["inline", "list", "link"]);
+export const INLINE_RULE = createMarkupRule(INLINE_REGEXP, ({ groups: { char, text } }, options, key) => {
+    const Inline = INLINE_CHARS[char];
+    return _jsx(Inline, { children: renderMarkup(text, options, "inline") }, key);
+}, ["inline", "list", "link"]);

package/markup/rule/linebreak.js

@@ -1,4 +1,4 @@
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { createMarkupRule } from "../util/rule.js";
 /**
  * Hard linebreak (`<br />` tag).
@@ -10,9 +10,8 @@ import { createMarkupRule } from "../util/rule.js";
  *   - This is more intuitive (a linebreak becomes a linebreak is isn't silently ignored).
  *   - This works better with textareas that wrap text (since manually breaking up long lines is no longer necessary).
  */
-export const LINEBREAK_RULE = createMarkupRule(/[^\n\S]*\n[^\n\S]*/, (_match, _options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "br",
-    props: {},
-}), ["inline", "list", "link"]);
+export const LINEBREAK_RULE = createMarkupRule(/[^\n\S]*\n[^\n\S]*/, (_match, _options, key) => _jsx("br", {}, key), [
+    "inline",
+    "list",
+    "link",
+]);

package/markup/rule/link.js

@@ -1,9 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { formatURI } from "../../util/format.js";
 import { getLink } from "../../util/link.js";
 import { getRegExp } from "../../util/regexp.js";
 import { HTTP_SCHEMES } from "../../util/uri.js";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { createMarkupRule } from "../util/rule.js";
 /** Render `<a href="">` if the link is a valid one, or `<a>` (with no `href`) if it isn't. */
 function renderLinkMarkupRule({ groups: { title, href: unsafeHref } }, options, key) {
@@ -11,12 +11,7 @@ function renderLinkMarkupRule({ groups: { title, href: unsafeHref } }, options,
     const link = getLink(unsafeHref, url, root);
     const href = link && schemes.includes(link.protocol) ? link?.href : undefined;
     const children = title ? renderMarkup(title, options, "link") : link ? formatURI(link) : "";
-    return {
-        key,
-        $$typeof: REACT_ELEMENT_TYPE,
-        type: "a",
-        props: { href, rel, children },
-    };
+    return (_jsx("a", { href: href, rel: rel, children: children }, key));
 }
 export const LINK_REGEXP = getRegExp(/\[(?<title>[^\]\n]*?)\]\((?<href>[^)\n]*?)\)/);
 /**
@@ -27,8 +22,7 @@ export const LINK_REGEXP = getRegExp(/\[(?<title>[^\]\n]*?)\]\((?<href>[^)\n]*?)
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only `http://` or `https://` links will work (if invalid the unparsed text will be returned).
  */
-export const LINK_RULE = createMarkupRule(LINK_REGEXP, //
-renderLinkMarkupRule, ["inline", "list"]);
+export const LINK_RULE = createMarkupRule(LINK_REGEXP, renderLinkMarkupRule, ["inline", "list"]);
 export const AUTOLINK_REGEXP = getRegExp(/(?<href>[a-z]{2,}:\S+)(?: +(?:\((?<title>[^)\n]*?)\)))?/);
 /**
  * Autolinked URL starts with `scheme://` (any scheme in `options.schemes`) and matches an unlimited number of non-space characters.
@@ -37,5 +31,4 @@ export const AUTOLINK_REGEXP = getRegExp(/(?<href>[a-z]{2,}:\S+)(?: +(?:\((?<tit
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `options.schemes` will match (defaults to `http:` and `https:`).
  */
-export const AUTOLINK_RULE = createMarkupRule(AUTOLINK_REGEXP, //
-renderLinkMarkupRule, ["inline", "list"]);
+export const AUTOLINK_RULE = createMarkupRule(AUTOLINK_REGEXP, renderLinkMarkupRule, ["inline", "list"]);

package/markup/rule/ordered.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { BLOCK_CONTENT_REGEXP, BLOCK_SPACE_REGEXP, createBlockRegExp, LINE_SPACE_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const INDENT = /^\t/gm; // Nesting is recognised with tabs only.
@@ -13,27 +13,11 @@ export const ORDERED_REGEXP = createBlockRegExp(`(?<list>${NUMBER}(?:${LINE_SPAC
  * - Second-level list can be created by indenting with `\t` one tab.
  * - Sparse lists are not supported.
  */
-export const ORDERED_RULE = createMarkupRule(ORDERED_REGEXP, ({ groups: { list } }, options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "ol",
-    props: {
-        children: Array.from(_getOrderedItems(list, options)),
-    },
-}), ["block", "list"]);
+export const ORDERED_RULE = createMarkupRule(ORDERED_REGEXP, ({ groups: { list } }, options, key) => _jsx("ol", { children: Array.from(_getOrderedItems(list, options)) }, key), ["block", "list"]);
 /** Parse a markdown list into a set of items elements. */
 function* _getOrderedItems(list, options) {
     let key = 0;
     for (const [_unused, number = "", item = ""] of list.matchAll(ITEM)) {
-        yield {
-            $$typeof: REACT_ELEMENT_TYPE,
-            type: "li",
-            props: {
-                value: Number.parseInt(number, 10),
-                children: renderMarkup(item.replace(INDENT, ""), options, "list"),
-            },
-            key: key.toString(),
-        };
-        key++;
+        yield (_jsx("li", { value: Number.parseInt(number, 10), children: renderMarkup(item.replace(INDENT, ""), options, "list") }, key++));
     }
 }

package/markup/rule/paragraph.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { BLOCK_SPACE_REGEXP, BLOCK_START_REGEXP, createBlockRegExp } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 export const PARAGRAPH_REGEXP = createBlockRegExp("(?<paragraph>(?:(?=\\S)[\\s\\S]*?\\S))", 
@@ -11,9 +11,4 @@ export const PARAGRAPH_REGEXP = createBlockRegExp("(?<paragraph>(?:(?=\\S)[\\s\\
  * - Any run of non-whitespace.
  * - Leading and trailing whitespace is trimmed.
  */
-export const PARAGRAPH_RULE = createMarkupRule(PARAGRAPH_REGEXP, ({ groups: { paragraph } }, options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "p",
-    props: { children: renderMarkup(paragraph, options, "inline") },
-}), ["block"], -10);
+export const PARAGRAPH_RULE = createMarkupRule(PARAGRAPH_REGEXP, ({ groups: { paragraph } }, options, key) => _jsx("p", { children: renderMarkup(paragraph, options, "inline") }, key), ["block"], -10);

package/markup/rule/separator.js

@@ -1,4 +1,4 @@
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { createLineRegExp } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const SEPARATOR_REGEXP = createLineRegExp("([-*•+_=])(?: *\\1){2,}");
@@ -9,9 +9,4 @@ const SEPARATOR_REGEXP = createLineRegExp("([-*•+_=])(?: *\\1){2,}");
  * - Character must be the same every time (can't mix)
  * - Might have infinite number of spaces between the characters.
  */
-export const SEPARATOR_RULE = createMarkupRule(SEPARATOR_REGEXP, (_match, _options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "hr",
-    props: {},
-}), ["block"]);
+export const SEPARATOR_RULE = createMarkupRule(SEPARATOR_REGEXP, (_match, _options, key) => _jsx("hr", {}, key), ["block"]);

package/markup/rule/table.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { createBlockRegExp, LINE_SPACE_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 // Constants.
@@ -41,35 +41,26 @@ function _renderTable(table, options, key) {
         }
     }
     sections.push(section);
-    // First section is `<thead>`; the last is `<tfoot>` when there are 3+ sections; sections in between are each a `<tbody>`.
+    // Build the table with explicit loops — markup elements are static and positional, so the loop index is the natural key.
     const last = sections.length - 1;
-    const children = sections.map((rows, s) => {
-        const type = s === 0 ? "thead" : s === last && last >= 2 ? "tfoot" : "tbody";
-        return {
-            $$typeof: REACT_ELEMENT_TYPE,
-            type,
-            key: `${type}-${s}`,
-            props: { children: Array.from(_renderRows(rows, s === 0 ? "th" : "td", aligns, options)) },
-        };
-    });
-    return { key, $$typeof: REACT_ELEMENT_TYPE, type: "table", props: { children } };
-}
-/** Render the rows of one section into `<tr>` elements of `<th>` or `<td>` cells. */
-function* _renderRows(rows, cell, aligns, options) {
-    let r = 0;
-    for (const row of rows) {
-        const values = _splitRow(row);
-        const cells = aligns.map((align, c) => {
-            const children = renderMarkup(values[c] ?? "", options, "inline");
-            return {
-                $$typeof: REACT_ELEMENT_TYPE,
-                type: cell,
-                key: c.toString(),
-                props: align ? { align, children } : { children },
-            };
-        });
-        yield { $$typeof: REACT_ELEMENT_TYPE, type: "tr", key: (r++).toString(), props: { children: cells } };
+    const body = [];
+    for (let s = 0; s < sections.length; s++) {
+        // First section is `<thead>`; the last is `<tfoot>` with 3+ sections; sections in between are each a `<tbody>`.
+        const Section = s === 0 ? "thead" : s === last && last >= 2 ? "tfoot" : "tbody";
+        const Cell = s === 0 ? "th" : "td";
+        const rowLines = sections[s] ?? [];
+        const rows = [];
+        for (let r = 0; r < rowLines.length; r++) {
+            const values = _splitRow(rowLines[r] ?? "");
+            const cells = [];
+            for (let c = 0; c < aligns.length; c++) {
+                cells.push(_jsx(Cell, { align: aligns[c], children: renderMarkup(values[c] ?? "", options, "inline") }, c));
+            }
+            rows.push(_jsx("tr", { children: cells }, r));
+        }
+        body.push(_jsx(Section, { children: rows }, s));
     }
+    return _jsx("table", { children: body }, key);
 }
 /** Split a table row into trimmed cell strings, honouring `\|` escaped pipes. */
 function _splitRow(row) {

package/markup/rule/unordered.d.ts

@@ -1,4 +1,4 @@
-import type { Element } from "../../util/element.js";
+import type { ReactElement } from "react";
 import type { MarkupOptions } from "../util/options.js";
 export declare const UNORDERED_REGEXP: import("../../index.js").NamedRegExp<{
     list?: string;
@@ -13,4 +13,4 @@ export declare const UNORDERED_REGEXP: import("../../index.js").NamedRegExp<{
  */
 export declare const UNORDERED_RULE: import("../util/rule.js").MarkupRule;
 /** Parse a markdown list into a set of items elements. */
-export declare function _getItems(list: string, options: MarkupOptions): Iterable<Element>;
+export declare function _getItems(list: string, options: MarkupOptions): Iterable<ReactElement>;

package/markup/rule/unordered.js

@@ -1,5 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
 import { renderMarkup } from "../render.js";
-import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { BLOCK_CONTENT_REGEXP, BLOCK_SPACE_REGEXP, createBlockRegExp, LINE_SPACE_REGEXP } from "../util/regexp.js";
 import { createMarkupRule } from "../util/rule.js";
 const INDENT = /^\t/gm; // Nesting is recognised with tabs only.
@@ -14,26 +14,11 @@ export const UNORDERED_REGEXP = createBlockRegExp(`(?<list>${BULLET}(?:${LINE_SP
  * - List block is ended by `\n\n` two newline characters.
  * - Sparse lists are not supported.
  */
-export const UNORDERED_RULE = createMarkupRule(UNORDERED_REGEXP, ({ groups: { list = "" } }, options, key) => ({
-    key,
-    $$typeof: REACT_ELEMENT_TYPE,
-    type: "ul",
-    props: {
-        children: Array.from(_getItems(list, options)),
-    },
-}), ["block", "list"]);
+export const UNORDERED_RULE = createMarkupRule(UNORDERED_REGEXP, ({ groups: { list = "" } }, options, key) => _jsx("ul", { children: Array.from(_getItems(list, options)) }, key), ["block", "list"]);
 /** Parse a markdown list into a set of items elements. */
 export function* _getItems(list, options) {
     let key = 0;
     for (const [_unused, item = ""] of list.matchAll(ITEM)) {
-        yield {
-            $$typeof: REACT_ELEMENT_TYPE,
-            type: "li",
-            props: {
-                children: renderMarkup(item.replace(INDENT, ""), options, "list"),
-            },
-            key: key.toString(),
-        };
-        key++;
+        yield _jsx("li", { children: renderMarkup(item.replace(INDENT, ""), options, "list") }, key++);
     }
 }

package/markup/util/rule.d.ts

@@ -1,4 +1,4 @@
-import type { Element } from "../../util/element.js";
+import type { ReactElement } from "react";
 import type { NamedRegExp, NamedRegExpExecArray } from "../../util/regexp.js";
 import type { MarkupOptions } from "./options.js";
 export type MarkupContexts = [string, ...string[]];
@@ -6,7 +6,7 @@ export interface MarkupRule {
     /** Regular expression used for matching the rule. */
     regexp: RegExp;
     /** Use the matched data to render an element. */
-    render(match: RegExpExecArray, options: MarkupOptions, key: string): Element;
+    render(match: RegExpExecArray, options: MarkupOptions, key: string): ReactElement;
     /** One or more contexts this rule should render in. */
     contexts: MarkupContexts;
     /** Priority for this rule (higher priority rules override lower priority rules). */
@@ -14,4 +14,4 @@ export interface MarkupRule {
 }
 export type MarkupRules = readonly MarkupRule[];
 /** Helper to make it easier to create typed `MarkupRule` instances using `NamedRegExp` regular expressions. */
-export declare function createMarkupRule<T extends NamedRegExp | RegExp>(regexp: T, render: T extends NamedRegExp<infer X> ? (match: NamedRegExpExecArray<X>, options: MarkupOptions, key: string) => Element : (match: RegExpExecArray, options: MarkupOptions, key: string) => Element, contexts: MarkupContexts, priority?: number): MarkupRule;
+export declare function createMarkupRule<T extends NamedRegExp | RegExp>(regexp: T, render: T extends NamedRegExp<infer X> ? (match: NamedRegExpExecArray<X>, options: MarkupOptions, key: string) => ReactElement : (match: RegExpExecArray, options: MarkupOptions, key: string) => ReactElement, contexts: MarkupContexts, priority?: number): MarkupRule;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.212.0",
+	"version": "1.214.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -35,6 +35,7 @@
 		"./cloudflare": "./cloudflare/index.js",
 		"./db": "./db/index.js",
 		"./error": "./error/index.js",
+		"./extract": "./extract/index.js",
 		"./firestore/client": "./firestore/client/index.js",
 		"./firestore/lite": "./firestore/lite/index.js",
 		"./firestore/server": "./firestore/server/index.js",

package/ui/README.md

@@ -0,0 +1,83 @@
+# ui
+
+A React component library for building Shelving apps — forms, content, layout, routing, dialogs, and the documentation-site components, all in one place.
+
+The `ui` module exists so an app never hand-rolls the same form field, card, or router twice. Every component picks up its look from shared CSS and exposes its variations as plain boolean props. You build a screen by composing these pieces, and reach for a custom-styled element only when nothing here fits.
+
+`ui` is consumed as source — it ships `.tsx` and `.module.css` files and needs a bundler that understands CSS Modules and JSX. It is not part of the root `shelving` package; import it from `shelving/ui`.
+
+## How components work
+
+A few conventions run through every component (see also the React Components section of `AGENTS.md`):
+
+- **Variants, not CSS.** Visual options are boolean props — `<Button small primary>`, `<Section narrow>`. Each maps to a class in the component's CSS Module. You never pass `style` or raw `className`.
+- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `Card`, `Section`, `Button`, and `Tag` rather than shipping their own styling.
+- **Sentence case.** Titles, headings, and button labels capitalise only the first word.
+- **Theming via CSS variables.** Colour and spacing come from CSS custom properties with fallback chains, so a theme is a small set of variable overrides.
+
+## Module map
+
+### Content
+
+| Folder | What's inside |
+|---|---|
+| [block](/ui/block) | Block-level content — `Card`, `Section`, `Heading`, `Table`, `List`, `Prose`, `Figure`, `Flex` |
+| [inline](/ui/inline) | Inline content — `Code`, `Strong`, `Emphasis`, `Link`, `Mark`, `Small` |
+| [misc](/ui/misc) | Cross-cutting pieces — `Markup`, `Tag`, `Status`, `Loading`, `Color`, `Catcher`, `Mapper` |
+
+### Structure
+
+| Folder | What's inside |
+|---|---|
+| [app](/ui/app) | The `<App>` root component |
+| [page](/ui/page) | Document-level components — `<HTML>`, `<Head>`, `<Page>` |
+| [layout](/ui/layout) | Page layouts — `SidebarLayout`, `CenteredLayout` |
+| [router](/ui/router) | Client-side routing — `<Navigation>`, `<Router>` |
+
+### Interaction
+
+| Folder | What's inside |
+|---|---|
+| [form](/ui/form) | Forms and inputs — `<Form>`, `<Field>`, typed inputs, `<Button>`, `FormStore` |
+| [dialog](/ui/dialog) | `<Dialog>` and `<Modal>` overlays |
+| [menu](/ui/menu) | `<Menu>` and `<MenuItem>` |
+| [notice](/ui/notice) | Inline and global notices |
+| [transition](/ui/transition) | CSS enter / leave transitions |
+
+### Documentation site
+
+| Folder | What's inside |
+|---|---|
+| [tree](/ui/tree) | `<TreeApp>` and the components that turn a tree into a site |
+| [docs](/ui/docs) | Page and card renderers for directories, files, and code symbols |
+| [util](/ui/util) | UI helper functions — context, meta, CSS class composition |
+
+## Quick start
+
+A minimal single-screen app:
+
+```tsx
+import { App, CenteredLayout, Section, Heading, Paragraph } from "shelving/ui";
+
+function HelloApp() {
+  return (
+    <App app="My app">
+      <CenteredLayout>
+        <Section narrow>
+          <Heading>Hello</Heading>
+          <Paragraph>Welcome to the app.</Paragraph>
+        </Section>
+      </CenteredLayout>
+    </App>
+  );
+}
+```
+
+For a routed, multi-page app, wrap the tree in [`<Navigation>` and `<Router>`](/ui/router). For a documentation site, hand an extracted tree to [`<TreeApp>`](/ui/tree) — see the [extract](/extract) guide.
+
+## See also
+
+- [extract](/extract) — builds the tree that the documentation components render
+- [markup](/markup) — Markdown rendering used by `<Markup>` and `<Prose>`
+- [store](/store) — reactive state behind `FormStore`, `NavigationStore`, and notices
+- [react](/react) — store and provider hooks used alongside these components

package/ui/app/README.md

@@ -0,0 +1,32 @@
+# App
+
+Root component for a client-side Shelving app. `<App>` applies the theme CSS class to `document.body` and provides a `Meta` context so every descendant can read or update page metadata.
+
+Use `<App>` when mounting into an existing HTML page on the client. For server-side rendering where you need the full `<html>` document shell, use [`<HTML>`](/ui/page) instead.
+
+## Usage
+
+```tsx
+import { App, Navigation, Router } from "shelving/ui";
+
+export function MyApp() {
+  return (
+    <App app="My App" root="https://example.com/" url="/">
+      <Navigation>
+        <Router routes={{
+          "/": HomePage,
+          "/about": AboutPage,
+        }} />
+      </Navigation>
+    </App>
+  );
+}
+```
+
+`<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
+
+## See also
+
+- [`ui/page`](/ui/page) — `<HTML>` and `<Page>` for the document shell and per-page metadata
+- [`ui/layout`](/ui/layout) — `SidebarLayout` and `CenteredLayout`
+- [`ui/router`](/ui/router) — `<Navigation>` and `<Router>` for client-side routing