shelving 1.202.0 → 1.203.0

package/extract/DirectoryExtractor.d.ts

@@ -0,0 +1,29 @@
+import type { Element } from "../util/element.js";
+import { Extractor } from "./Extractor.js";
+import type { FileExtractor } from "./FileExtractor.js";
+/** Options for a directory extractor. */
+export interface DirectoryExtractorOptions {
+    /** Filenames to treat as the directory's index file (e.g. `["README.md", "INDEX.md"]`). */
+    readonly index: readonly string[];
+    /** Extractor to use for child files. */
+    readonly extractor: FileExtractor;
+}
+/**
+ * Extractor that processes a directory's files into a directory element.
+ * - Finds an index file and absorbs its content as the directory's own content.
+ * - Delegates remaining files to the child file extractor.
+ * - Errors if two child elements resolve to the same slug.
+ * - Preserves file system ordering.
+ */
+export declare class DirectoryExtractor extends Extractor<{
+    name: string;
+    files: File[];
+}> {
+    private readonly _index;
+    private readonly _extractor;
+    constructor({ index, extractor }: DirectoryExtractorOptions);
+    extract({ name, files }: {
+        name: string;
+        files: File[];
+    }): Promise<Element>;
+}

package/extract/DirectoryExtractor.js

@@ -0,0 +1,48 @@
+import { requireSlug } from "../util/string.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Extractor that processes a directory's files into a directory element.
+ * - Finds an index file and absorbs its content as the directory's own content.
+ * - Delegates remaining files to the child file extractor.
+ * - Errors if two child elements resolve to the same slug.
+ * - Preserves file system ordering.
+ */
+export class DirectoryExtractor extends Extractor {
+    _index;
+    _extractor;
+    constructor({ index, extractor }) {
+        super();
+        this._index = index;
+        this._extractor = extractor;
+    }
+    async extract({ name, files }) {
+        let indexElement;
+        const children = [];
+        const keys = new Set();
+        for (const file of files) {
+            if (!indexElement && this._index.includes(file.name)) {
+                indexElement = await this._extractor.extract(file);
+            }
+            else {
+                const element = await this._extractor.extract(file);
+                const { key } = element;
+                if (key) {
+                    if (keys.has(key))
+                        throw new Error(`Duplicate key "${key}" in directory "${name}"`);
+                    keys.add(key);
+                }
+                children.push(element);
+            }
+        }
+        return {
+            type: "tree-directory",
+            key: requireSlug(name),
+            props: {
+                title: indexElement?.props.title ?? name,
+                description: indexElement?.props.description,
+                content: indexElement?.props.content,
+                children,
+            },
+        };
+    }
+}

package/extract/Extractor.d.ts

@@ -0,0 +1,11 @@
+import type { Element } from "../util/element.js";
+/**
+ * Base class for an extractor that converts input into an element.
+ * - Extractors are composable: outer extractors delegate to inner extractors.
+ */
+export declare abstract class Extractor<I> {
+    /** Extract an element from the given input. */
+    abstract extract(input: I): Element | Promise<Element>;
+}
+/** Extractor that converts string content into an element. */
+export type ContentExtractor = Extractor<string>;

package/extract/Extractor.js

@@ -0,0 +1,6 @@
+/**
+ * Base class for an extractor that converts input into an element.
+ * - Extractors are composable: outer extractors delegate to inner extractors.
+ */
+export class Extractor {
+}

package/extract/FileExtractor.d.ts

@@ -0,0 +1,17 @@
+import type { Element } from "../util/element.js";
+import { type ContentExtractor, Extractor } from "./Extractor.js";
+/** Options for a file extractor. */
+export interface FileExtractorOptions {
+    /** Map of file extension (e.g. `".md"`, `".ts"`) to content extractor. */
+    readonly extractors: Readonly<Record<string, ContentExtractor>>;
+}
+/**
+ * Extractor that dispatches to a content extractor based on file extension.
+ * - Reads the file content and passes it to the matched extractor.
+ * - Sets the element `key` to the slugified filename (without extension).
+ */
+export declare class FileExtractor extends Extractor<File> {
+    private readonly _extractors;
+    constructor({ extractors }: FileExtractorOptions);
+    extract(file: File): Promise<Element>;
+}

package/extract/FileExtractor.js

@@ -0,0 +1,25 @@
+import { splitFileExtension } from "../util/file.js";
+import { requireSlug } from "../util/string.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Extractor that dispatches to a content extractor based on file extension.
+ * - Reads the file content and passes it to the matched extractor.
+ * - Sets the element `key` to the slugified filename (without extension).
+ */
+export class FileExtractor extends Extractor {
+    _extractors;
+    constructor({ extractors }) {
+        super();
+        this._extractors = extractors;
+    }
+    async extract(file) {
+        const [base, ext] = splitFileExtension(file.name);
+        const key = requireSlug(base ?? file.name);
+        const extractor = ext ? this._extractors[ext] : undefined;
+        if (!extractor)
+            return { type: "tree-file", key, props: {} };
+        const content = await file.text();
+        const element = await extractor.extract(content);
+        return { ...element, key };
+    }
+}

package/extract/MarkdownExtractor.d.ts

@@ -0,0 +1,13 @@
+import type { MarkupOptions } from "../markup/util/options.js";
+import type { Element } from "../util/element.js";
+import { type ContentExtractor, Extractor } from "./Extractor.js";
+/**
+ * Extractor that converts a Markdown string into a file element.
+ * - Parses the markdown using the markup module.
+ * - Extracts the first `<h1>` heading as the element title.
+ */
+export declare class MarkdownExtractor extends Extractor<string> implements ContentExtractor {
+    private readonly _options;
+    constructor(options?: MarkupOptions);
+    extract(content: string): Element;
+}

package/extract/MarkdownExtractor.js

@@ -0,0 +1,32 @@
+import { renderMarkup } from "../markup/render.js";
+import { MARKUP_RULES } from "../markup/rule/index.js";
+import { getElements, getElementText } from "../util/element.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Extractor that converts a Markdown string into a file element.
+ * - Parses the markdown using the markup module.
+ * - Extracts the first `<h1>` heading as the element title.
+ */
+export class MarkdownExtractor extends Extractor {
+    _options;
+    constructor(options = { rules: MARKUP_RULES }) {
+        super();
+        this._options = options;
+    }
+    extract(content) {
+        const elements = renderMarkup(content, this._options);
+        const title = _getFirstHeadingText(elements);
+        return {
+            type: "tree-file",
+            key: null,
+            props: { title, content: elements },
+        };
+    }
+}
+/** Find the first `h1` element and extract its text content. */
+function _getFirstHeadingText(elements) {
+    for (const el of getElements(elements)) {
+        if (el.type === "h1")
+            return getElementText(el.props.children) || undefined;
+    }
+}

package/extract/TypescriptExtractor.d.ts

@@ -0,0 +1,11 @@
+import type { Element } from "../util/element.js";
+import { type ContentExtractor, Extractor } from "./Extractor.js";
+/**
+ * Extractor that converts a TypeScript source string into a file element.
+ * - Uses the TypeScript compiler API to parse the AST.
+ * - Extracts exported, public, non-`_`-prefixed declarations with their JSDoc and type signatures.
+ * - Top-of-file JSDoc comment becomes the file's description.
+ */
+export declare class TypescriptExtractor extends Extractor<string> implements ContentExtractor {
+    extract(content: string): Element;
+}

package/extract/TypescriptExtractor.js

@@ -0,0 +1,244 @@
+import ts from "typescript";
+import { Extractor } from "./Extractor.js";
+/**
+ * Extractor that converts a TypeScript source string into a file element.
+ * - Uses the TypeScript compiler API to parse the AST.
+ * - Extracts exported, public, non-`_`-prefixed declarations with their JSDoc and type signatures.
+ * - Top-of-file JSDoc comment becomes the file's description.
+ */
+export class TypescriptExtractor extends Extractor {
+    extract(content) {
+        const source = ts.createSourceFile("source.ts", content, ts.ScriptTarget.Latest, true);
+        const children = [];
+        const description = _getFileDocComment(source);
+        for (const statement of source.statements) {
+            const element = _extractStatement(statement, source);
+            if (element)
+                children.push(element);
+        }
+        return {
+            type: "tree-file",
+            key: null,
+            props: { description, children },
+        };
+    }
+}
+/** Get the leading JSDoc comment of the file (before the first statement). */
+function _getFileDocComment(source) {
+    const { statements } = source;
+    if (!statements.length)
+        return;
+    const first = statements[0];
+    if (!first)
+        return;
+    const ranges = ts.getLeadingCommentRanges(source.text, first.pos);
+    if (!ranges?.length)
+        return;
+    const range = ranges[0];
+    if (!range || range.kind !== ts.SyntaxKind.MultiLineCommentTrivia)
+        return;
+    const text = source.text.slice(range.pos, range.end);
+    return _parseJSDocComment(text);
+}
+/** Extract an element from a top-level statement, or return undefined if it should be skipped. */
+function _extractStatement(statement, source) {
+    // Skip non-exported statements.
+    if (!_isExported(statement))
+        return;
+    // Skip statements without a name.
+    const name = _getStatementName(statement);
+    if (!name)
+        return;
+    // Skip private/internal names.
+    if (name.startsWith("_"))
+        return;
+    const jsDoc = _getJSDoc(statement, source);
+    const kind = _getElementType(statement);
+    if (!kind)
+        return;
+    const signature = _getSignature(statement, source);
+    const params = _getParams(statement, source);
+    const returns = _getReturnType(statement, source);
+    const examples = jsDoc?.examples;
+    const children = _getClassMembers(statement, source);
+    const props = {
+        title: name,
+        description: jsDoc?.description,
+        signature,
+    };
+    if (params?.length)
+        props.params = params;
+    if (returns)
+        props.returns = returns;
+    if (examples?.length)
+        props.examples = examples;
+    if (children?.length)
+        props.children = children;
+    return { type: kind, key: null, props };
+}
+/** Check if a statement has an `export` modifier. */
+function _isExported(statement) {
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+    return !!modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+}
+/** Get the declared name of a statement. */
+function _getStatementName(statement) {
+    if (ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement) ||
+        ts.isEnumDeclaration(statement)) {
+        return statement.name?.text;
+    }
+    if (ts.isVariableStatement(statement)) {
+        const declaration = statement.declarationList.declarations[0];
+        if (declaration && ts.isIdentifier(declaration.name))
+            return declaration.name.text;
+    }
+}
+/** Map a statement to its tree element type. */
+function _getElementType(statement) {
+    if (ts.isFunctionDeclaration(statement))
+        return "tree-function";
+    if (ts.isClassDeclaration(statement))
+        return "tree-class";
+    if (ts.isInterfaceDeclaration(statement))
+        return "tree-interface";
+    if (ts.isTypeAliasDeclaration(statement))
+        return "tree-type";
+    if (ts.isVariableStatement(statement))
+        return "tree-constant";
+}
+/** Get the text signature of a statement. */
+function _getSignature(statement, source) {
+    if (ts.isFunctionDeclaration(statement)) {
+        const params = statement.parameters.map(p => p.getText(source)).join(", ");
+        const ret = statement.type ? statement.type.getText(source) : "void";
+        return `(${params}) => ${ret}`;
+    }
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return statement.type.getText(source);
+    }
+    if (ts.isVariableStatement(statement)) {
+        const declaration = statement.declarationList.declarations[0];
+        if (declaration?.type)
+            return declaration.type.getText(source);
+    }
+}
+/** Extract parameters from a function or method declaration. */
+function _getParams(statement, source) {
+    if (!ts.isFunctionDeclaration(statement))
+        return;
+    const jsDocParams = _getJSDoc(statement, source)?.params;
+    const params = statement.parameters.map(p => {
+        const name = p.name.getText(source);
+        const type = p.type?.getText(source);
+        const optional = !!p.questionToken || !!p.initializer;
+        const description = jsDocParams?.find(d => d.name === name)?.description;
+        return { name, type, description, optional };
+    });
+    return params.length ? params : undefined;
+}
+/** Get the return type of a function declaration. */
+function _getReturnType(statement, source) {
+    if (ts.isFunctionDeclaration(statement) && statement.type)
+        return statement.type.getText(source);
+}
+/** Extract class or interface members as child elements. */
+function _getClassMembers(statement, source) {
+    if (!ts.isClassDeclaration(statement) && !ts.isInterfaceDeclaration(statement))
+        return;
+    const members = [];
+    for (const member of statement.members) {
+        // Skip private, protected, and _-prefixed members.
+        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        if (!name || name.startsWith("_"))
+            continue;
+        if (ts.canHaveModifiers(member)) {
+            const modifiers = ts.getModifiers(member);
+            if (modifiers?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+                continue;
+        }
+        const jsDoc = _getJSDoc(member, source);
+        const props = {
+            title: name,
+            description: jsDoc?.description,
+        };
+        if (ts.isMethodDeclaration(member) || ts.isMethodSignature(member)) {
+            const params = member.parameters.map(p => p.getText(source)).join(", ");
+            const ret = member.type ? member.type.getText(source) : "void";
+            props.signature = `(${params}) => ${ret}`;
+            members.push({ type: "tree-method", key: null, props });
+        }
+        else if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
+            if (member.type)
+                props.signature = member.type.getText(source);
+            members.push({ type: "tree-property", key: null, props });
+        }
+    }
+    return members.length ? members : undefined;
+}
+/** Extract JSDoc from a node. */
+function _getJSDoc(node, source) {
+    const ranges = ts.getLeadingCommentRanges(source.text, node.pos);
+    if (!ranges?.length)
+        return;
+    // Find the last JSDoc-style comment (/** ... */).
+    for (let i = ranges.length - 1; i >= 0; i--) {
+        const range = ranges[i];
+        if (!range || range.kind !== ts.SyntaxKind.MultiLineCommentTrivia)
+            continue;
+        const text = source.text.slice(range.pos, range.end);
+        if (!text.startsWith("/**"))
+            continue;
+        const description = _parseJSDocComment(text);
+        const params = _parseJSDocParams(text);
+        const examples = _parseJSDocExamples(text);
+        return {
+            description: description || undefined,
+            params: params.length ? params : undefined,
+            examples: examples.length ? examples : undefined,
+        };
+    }
+}
+/** Parse a JSDoc comment block into its description text. */
+function _parseJSDocComment(text) {
+    const lines = text
+        .replace(/^\/\*\*\s*/, "")
+        .replace(/\s*\*\/$/, "")
+        .split("\n")
+        .map(l => l.replace(/^\s*\*\s?/, ""));
+    // Collect lines until we hit a @tag.
+    const description = [];
+    for (const line of lines) {
+        if (line.startsWith("@"))
+            break;
+        description.push(line);
+    }
+    const result = description.join("\n").trim();
+    return result || undefined;
+}
+/** Parse `@param` tags from a JSDoc comment. */
+function _parseJSDocParams(text) {
+    const results = [];
+    const regexp = /@param\s+(?:\{[^}]*\}\s+)?(\w+)\s+(.*)/g;
+    let match;
+    while ((match = regexp.exec(text))) {
+        const name = match[1];
+        const description = match[2];
+        if (name && description)
+            results.push({ name, description: description.trim() });
+    }
+    return results;
+}
+/** Parse `@example` tags from a JSDoc comment. */
+function _parseJSDocExamples(text) {
+    const results = [];
+    const regexp = /@example\s+(.*)/g;
+    let match;
+    while ((match = regexp.exec(text))) {
+        if (match[1])
+            results.push(match[1].trim());
+    }
+    return results;
+}

package/extract/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./DirectoryExtractor.js";
+export * from "./Extractor.js";
+export * from "./FileExtractor.js";
+export * from "./MarkdownExtractor.js";
+export * from "./TypescriptExtractor.js";

package/extract/index.js

@@ -0,0 +1,5 @@
+export * from "./DirectoryExtractor.js";
+export * from "./Extractor.js";
+export * from "./FileExtractor.js";
+export * from "./MarkdownExtractor.js";
+export * from "./TypescriptExtractor.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.202.0",
+	"version": "1.203.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,17 +9,17 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.14",
+		"@biomejs/biome": "^2.4.15",
 		"@google-cloud/firestore": "^8.5.0",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.13",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
-		"firebase": "^12.12.1",
-		"react": "canary",
+		"@typescript/native-preview": "^7.0.0-dev.20260509.2",
+		"firebase": "^12.13.0",
+		"react": "^19.3.0-canary-d5736f09-20260507",
 		"react-dom": "canary",
-		"typescript": "^5"
+		"typescript": "^5.9.3"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",

package/ui/form/ButtonInput.d.ts

@@ -4,4 +4,4 @@ import { type InputProps } from "./Input.js";
 export interface ButtonInputProps extends InputProps, ClickableProps {
 }
 /** Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided. */
-export declare function ButtonInput({ title, placeholder, disabled, href, onClick, target, download, children }: ButtonInputProps): ReactElement;
+export declare function ButtonInput({ title, placeholder, disabled, href, onClick, target, download, children, }: ButtonInputProps): ReactElement;

package/ui/form/CheckboxInput.d.ts

@@ -4,4 +4,4 @@ export interface CheckboxProps extends ValueInputProps<boolean> {
     children?: ReactNode | undefined;
 }
 /** Checkbox element. */
-export declare function CheckboxInput({ name, title, placeholder, required, disabled, message, value, onValue, children }: CheckboxProps): ReactElement;
+export declare function CheckboxInput({ name, title, placeholder, required, disabled, message, value, onValue, children, }: CheckboxProps): ReactElement;

package/ui/form/DateInput.d.ts

@@ -9,4 +9,4 @@ export interface DateInputProps extends ValueInputProps<string, PossibleDate> {
     step?: number | undefined;
 }
 export declare function DateInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
-required, disabled, message, value, onValue, min, max, input, step }: DateInputProps): ReactElement;
+required, disabled, message, value, onValue, min, max, input, step, }: DateInputProps): ReactElement;

package/ui/form/FileInput.d.ts

@@ -4,4 +4,4 @@ import { type ValueInputProps } from "./Input.js";
 export interface FileInputProps extends ValueInputProps<string | File> {
     types?: FileTypes | undefined;
 }
-export declare function FileInput({ name, title, placeholder, required, disabled, message, onValue, types }: FileInputProps): ReactElement;
+export declare function FileInput({ name, title, placeholder, required, disabled, message, onValue, types, }: FileInputProps): ReactElement;

package/ui/form/Input.d.ts

@@ -38,7 +38,7 @@ export interface ValueInputProps<O, I = never> extends InputProps {
     onValue(value: O | undefined): void;
 }
 /** Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided. */
-export declare function Input({ title, placeholder, disabled, href, onClick, target, download, children }: InputProps & ClickableProps): ReactElement;
+export declare function Input({ title, placeholder, disabled, href, onClick, target, download, children, }: InputProps & ClickableProps): ReactElement;
 /** Input that is loading. */
 export declare const LOADING_INPUT: import("react/jsx-runtime").JSX.Element;
 /** Wraps an input with support for absolutely-positioned `data-slot` icon elements on either side. */

package/ui/form/NumberInput.d.ts

@@ -8,5 +8,5 @@ export interface NumberInputProps extends ValueInputProps<number> {
     formatter?: NumberFormatter | undefined;
 }
 export declare function NumberInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
-required, disabled, message, value, onValue, formatter }: NumberInputProps): ReactElement;
+required, disabled, message, value, onValue, formatter, }: NumberInputProps): ReactElement;
 export {};

package/ui/form/Popover.d.ts

@@ -28,4 +28,4 @@ export interface PopoverProps {
  * @todo DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
  */
 export declare function Popover({ children: [trigger, ...popover], //
-onClose, open }: PopoverProps): ReactElement;
+onClose, open, }: PopoverProps): ReactElement;

package/ui/form/RadioInput.d.ts

@@ -4,4 +4,4 @@ export interface RadioInputProps extends ValueInputProps<boolean> {
     children?: ReactNode | undefined;
 }
 /** A single `<input type="radio">` in a `<label>` wrapper styled as an `<Input>` */
-export declare function RadioInput({ name, title, placeholder, required, disabled, message, value, onValue, children }: RadioInputProps): ReactElement;
+export declare function RadioInput({ name, title, placeholder, required, disabled, message, value, onValue, children, }: RadioInputProps): ReactElement;

package/ui/form/TextInput.d.ts

@@ -12,5 +12,5 @@ export interface TextInputProps extends ValueInputProps<string> {
     formatter?: TextFormatter | undefined;
 }
 export declare function TextInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
-required, disabled, message, value, onValue, input, min, max, rows, formatter }: TextInputProps): ReactElement;
+required, disabled, message, value, onValue, input, min, max, rows, formatter, }: TextInputProps): ReactElement;
 export {};

package/ui/index.d.ts

@@ -9,4 +9,5 @@ export * from "./notice/index.js";
 export * from "./page/index.js";
 export * from "./router/index.js";
 export * from "./transition/index.js";
+export * from "./tree/index.js";
 export * from "./util/index.js";

package/ui/index.js

@@ -9,4 +9,5 @@ export * from "./notice/index.js";
 export * from "./page/index.js";
 export * from "./router/index.js";
 export * from "./transition/index.js";
+export * from "./tree/index.js";
 export * from "./util/index.js";

package/ui/index.ts

@@ -9,4 +9,5 @@ export * from "./notice/index.js";
 export * from "./page/index.js";
 export * from "./router/index.js";
 export * from "./transition/index.js";
+export * from "./tree/index.js";
 export * from "./util/index.js";

package/ui/misc/Mapper.d.ts

@@ -0,0 +1,32 @@
+import { type ComponentType, type JSX, type ReactNode } from "react";
+/**
+ * Element mapping — maps intrinsic element type strings to React components.
+ * - Keys are element type names from `JSX.IntrinsicElements` (e.g. `"tree-file"`, `"tree-directory"`).
+ * - Each component must accept the props declared in `JSX.IntrinsicElements` for that element type.
+ */
+export type Mapping = {
+    [K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K]>;
+};
+/** Props for the `Mapping` component returned by `createElementMapper()`. */
+export interface MappingProps {
+    /** Mapping entries that override the defaults (and any parent `Mapping` entries). */
+    mapping: Mapping;
+    children: ReactNode;
+}
+/** Props for the `Mapper` component returned by `createElementMapper()`. */
+export interface MapperProps {
+    children?: ReactNode;
+}
+/**
+ * Create an element mapper — a `[Mapping, Mapper]` pair of React components.
+ *
+ * - `Mapping` — wraps a subtree to override or extend the element mapping for this mapper.
+ * - `Mapper` — maps children, replacing element types with registered components.
+ *
+ * Each mapper has its own React context, so different mappers (e.g. `TreeMenu`, `TreePage`)
+ * can have independent mappings without interfering with each other.
+ *
+ * @param defaults Default mapping entries (lowest priority — overridden by any `Mapping` wrapper).
+ * @returns A `[Mapping, Mapper]` tuple of React components.
+ */
+export declare function createMapper(defaults?: Mapping): [Mapping: React.FunctionComponent<MappingProps>, Mapper: React.FunctionComponent<MapperProps>];