@memorysmithapp/markdown-renderer 0.1.1 → 0.2.0

package/README.md

@@ -29,9 +29,52 @@ import 'katex/dist/katex.min.css';
 />;
 ```
 
-Every prop is optional, and every default is the safe one: with no `resolve` every link is pending, with no `keeps` no embed reaches a file. The stylesheet styles nothing outside `.markdown`; theme it with the `--markdown-*` custom properties. The faces are Inter and Space Grotesk, which the page loads.
+Every prop is optional, and every default is the safe one: with no `resolve` every link is pending, with no `keeps` no embed reaches a file. The stylesheet styles nothing outside `.markdown`. The faces of the default theme are Inter and Space Grotesk, which the page loads.
 
-The host contract, the stylesheet's properties and the decisions behind them are in the repository's [`ARCHITECTURE.md`](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/ARCHITECTURE.md).
+## Themes
+
+With no theme, a note looks as it does in MemorySmith, in `theme="light"` or `theme="dark"`. To give it your own look, write a theme in your project and pass it:
+
+```tsx
+import { defineTheme, NoteBody } from '@memorysmithapp/markdown-renderer';
+import '@memorysmithapp/markdown-renderer/styles.css';
+import './acme-theme.css';                          // your CSS, under .markdown-theme-acme
+
+const acme = defineTheme({
+  name: 'acme',                                    // the root of a note carries .markdown-theme-acme
+  schemes: ['light', 'dark'],
+  properties: {                                    // level 1: values, no CSS needed
+    light: { bg: '#ffffff', text: '#222222', accent: '#e11d48', fontSans: "'IBM Plex Sans', sans-serif" },
+    dark: { bg: '#111111', text: '#eeeeee', accent: '#fb7185' },
+  },
+  icons: { warning: <AlertTriangle />, tip: <Lightbulb /> }, // any icon library
+  components: {                                    // level 3: draw a block your way
+    table: ({ children }) => <table className="acme-table">{children}</table>,
+    callout: ({ kind, title, icon, children }) => (
+      <aside className={`acme-callout acme-${kind}`}>
+        <header>{icon}{title}</header>
+        {children}
+      </aside>
+    ),
+  },
+});
+
+<NoteBody markdown={note} theme={acme} scheme="dark" />;
+```
+
+- **Properties** name every value the stylesheet reads — colours, faces, sizes, spacing, headings, quotations, tables, callout hues and icons — and are written on the root as `--markdown-*`, so your CSS may set them too.
+- **Your CSS** is scoped by `.markdown-theme-<name>`, and reaches the note and nothing else.
+- **Slots** — `callout`, `calloutIcon`, `table`, `codeBlock`, `inlineCode`, `heading`, `blockquote`, `embed`, `footnotes`, `taskBox`, `wikilink`, `diagram`, `properties` — are called with the notation already read. A slot decides how a block looks, never what it means: the links it draws go where the host resolved them, a task box reports through the `toggle` it is given, and no raw HTML ever reaches it.
+
+The frontmatter is the note's too. The default theme draws it as MemorySmith does: `name` as the title, and the other entries in a block that folds, each key with the icon of its value's shape, lists as chips and dates in `strings.locale`, with a `[[wikilink]]`, a Markdown link or a web address in a value drawn as a link. A theme decides otherwise through the `properties` slot, which may draw nothing, as a host that shows properties elsewhere does:
+
+```tsx
+const mine = defineTheme({ name: 'mine', components: { properties: () => null } });
+```
+
+Import `structure.css` instead of `styles.css` for a theme that draws everything itself. A theme names faces; your page loads them.
+
+The host contract, the stylesheet's properties, the slots and the decisions behind them are in the repository's [`ARCHITECTURE.md`](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/ARCHITECTURE.md).
 
 ## Licence
 

package/dist/Markdown.d.ts

@@ -1,3 +1,4 @@
+import { type AnchorHTMLAttributes, type ReactNode } from 'react';
 import type { PluggableList } from 'unified';
 import { type FootnoteRef } from './footnotes.js';
 /**
@@ -27,9 +28,20 @@ export interface MarkdownProps {
         readonly refs: readonly FootnoteRef[];
     } | 'section';
 }
+/**
+ * What react-markdown hands a component beside the attributes: the hast
+ * element it came from. It is not an attribute, and spread onto the element
+ * it reached the page as `node="[object Object]"` on every link, image and
+ * code span.
+ */
+type WithNode<T> = T & {
+    node?: unknown;
+};
+export declare function MarkdownAnchor({ href, children, node: _node, ...rest }: WithNode<AnchorHTMLAttributes<HTMLAnchorElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 /**
  * The remark plugins of the reading surface, in their order. `planFootnotes` reads a note
  * through the same list, so it counts the references this surface draws and no other.
  */
 export declare function readingPlugins(titleOf: (kind: string) => string | undefined): PluggableList;
 export declare function Markdown({ children, source, onToggleTask, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
+export {};

package/dist/Markdown.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
-import { isValidElement, useRef, } from 'react';
+import { isValidElement, } from 'react';
 import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
 import ReactMarkdown from 'react-markdown';
 import rehypeKatex from 'rehype-katex';
@@ -17,6 +17,7 @@ import { MermaidDiagram } from './MermaidDiagram.js';
 import { remarkCallouts } from './remark-callouts.js';
 import { remarkBlockIds, remarkComments, remarkHighlight, remarkMathDollarRule } from './remark-ring.js';
 import { CLOBBER_PREFIX, rehypeFootnoteRun, rehypeFootnoteSection } from './footnotes.js';
+import { drawSlot, headings, InBlock, MarkdownBlockquote, MarkdownDiv, MarkdownSection, MarkdownTable, useInBlock, useSlot } from './slots.js';
 import { ordinalAt } from './tasklist.js';
 /**
  * An image, with the dimensions the specification puts in its alt text
@@ -72,8 +73,9 @@ function Attachment({ name, width, height }) {
         return _jsx("span", { className: "attachment-loading", children: name });
     return _jsx(_Fragment, { children: host.renderAttachment({ name, width, height }) });
 }
-function MarkdownAnchor({ href, children, node: _node, ...rest }) {
+export function MarkdownAnchor({ href, children, node: _node, ...rest }) {
     const host = useHost();
+    const wikilinkSlot = useSlot('wikilink');
     if (href?.startsWith('attachment:')) {
         /**
          * The address carries the dimension the pipe declared, after the encoded
@@ -93,7 +95,8 @@ function MarkdownAnchor({ href, children, node: _node, ...rest }) {
         return _jsx(Attachment, { name: name, width: measured?.width ?? null, height: measured?.height ?? null });
     }
     if (href?.startsWith('pending:')) {
-        return (_jsx("span", { className: "wikilink-pending", title: host.strings.pendingLink, children: children }));
+        const pending = (label) => (_jsx("span", { className: "wikilink-pending", title: host.strings.pendingLink, children: label }));
+        return wikilinkSlot ? drawSlot(wikilinkSlot, { pending: true, children, link: pending }) : pending(children);
     }
     // Refused by `followable`: the text stays on the page and stops being
     // something to click. An author sees they got nothing, which is the same
@@ -103,11 +106,17 @@ function MarkdownAnchor({ href, children, node: _node, ...rest }) {
     }
     // A target no single note answers by name opens its choice in place.
     const choice = choiceTargetOf(href);
-    if (choice !== null)
-        return _jsx(LinkChoice, { target: choice, children: children });
+    if (choice !== null) {
+        const link = (label) => _jsx(LinkChoice, { target: choice, children: label });
+        if (!wikilinkSlot)
+            return link(children);
+        return drawSlot(wikilinkSlot, { pending: host.reaches(choice) === 0, children, link });
+    }
     // An address of the host's own: its router draws it.
-    if (href.startsWith('/'))
-        return _jsx(_Fragment, { children: host.renderLink({ href, className: 'wikilink', children }) });
+    if (href.startsWith('/')) {
+        const link = (label) => _jsx(_Fragment, { children: host.renderLink({ href, className: 'wikilink', children: label }) });
+        return wikilinkSlot ? drawSlot(wikilinkSlot, { pending: false, children, link }) : link(children);
+    }
     if (href.startsWith('#')) {
         return (_jsx(InPageAnchor, { href: href, ...rest, children: children }));
     }
@@ -132,10 +141,14 @@ function MarkdownAnchor({ href, children, node: _node, ...rest }) {
  * highlighter would otherwise breach it.
  */
 function MarkdownCode({ className, children, node: _node, ...rest }) {
-    const { theme } = useHost();
+    const { scheme } = useHost();
+    const inBlock = useInBlock();
+    const inlineSlot = useSlot('inlineCode');
     if (className?.includes('language-mermaid')) {
-        return _jsx(MermaidDiagram, { code: String(children).trim(), theme: theme });
+        return _jsx(MermaidDiagram, { code: String(children).trim(), scheme: scheme });
     }
+    if (!inBlock && inlineSlot)
+        return drawSlot(inlineSlot, { children });
     const language = highlightLanguage(className);
     if (language !== null) {
         // The source is read and never rewritten: what is on the page is the
@@ -161,13 +174,31 @@ function MarkdownCode({ className, children, node: _node, ...rest }) {
  */
 function MarkdownPre({ children, node, ...rest }) {
     const { strings } = useHost();
-    const ref = useRef(null);
+    const slot = useSlot('codeBlock');
     const code = node?.children?.find((child) => child.tagName === 'code');
     const classes = code?.properties?.['className'];
     if (Array.isArray(classes) && classes.includes('language-mermaid')) {
         return _jsx("pre", { ...rest, children: children });
     }
-    return (_jsxs("div", { className: "code-block", children: [_jsx("pre", { ref: ref, ...rest, children: children }), _jsx(CopyButton, { className: "code-copy", label: strings.copy, done: strings.copied, text: () => (ref.current?.querySelector('code')?.textContent ?? '').replace(/\n$/, '') })] }));
+    // The bytes as typed: the text of the fence, less the newline before its closing line.
+    const typed = textOf(code).replace(/\n$/, '');
+    const copy = _jsx(CopyButton, { className: "code-copy", label: strings.copy, done: strings.copied, text: () => typed });
+    if (slot) {
+        const language = Array.isArray(classes)
+            ? (classes.map(String).find((name) => name.startsWith('language-'))?.slice('language-'.length) ?? null)
+            : null;
+        return _jsx(InBlock.Provider, { value: true, children: drawSlot(slot, { language, code: typed, children, copy }) });
+    }
+    return (_jsxs("div", { className: "code-block", children: [_jsx(InBlock.Provider, { value: true, children: _jsx("pre", { ...rest, children: children }) }), copy] }));
+}
+/** The text of a hast element, which for a fence is the code as typed. */
+function textOf(node) {
+    if (!node)
+        return '';
+    const text = node.value;
+    if (typeof text === 'string')
+        return text;
+    return (node.children ?? []).map(textOf).join('');
 }
 /**
  * Whether this list item is a task box, and how it is ticked.
@@ -191,6 +222,7 @@ function taskState(node) {
  * the host, never by the package.
  */
 function TaskItem({ node, children, className, source, toggleTask, writable, ...rest }) {
+    const boxSlot = useSlot('taskBox');
     const element = node;
     const checked = taskState(element);
     if (checked === null) {
@@ -199,10 +231,14 @@ function TaskItem({ node, children, className, source, toggleTask, writable, ...
     const offset = element?.position?.start?.offset;
     const ordinal = offset === undefined ? -1 : ordinalAt(source, offset);
     const enabled = writable && toggleTask !== undefined && ordinal >= 0;
+    const toggle = () => {
+        if (enabled)
+            toggleTask(ordinal);
+    };
     return (
     // Our class comes LAST, because the one react-markdown passes in is on
     // `className` and spreading it after would silently take the item back.
-    _jsxs("li", { ...rest, className: `${className ?? ''} task-item`.trim(), children: [_jsx("input", { type: "checkbox", checked: checked, disabled: !enabled, onChange: () => enabled && toggleTask(ordinal) }), dropBox(children)] }));
+    _jsxs("li", { ...rest, className: `${className ?? ''} task-item`.trim(), children: [boxSlot ? (drawSlot(boxSlot, { checked, enabled, toggle })) : (_jsx("input", { type: "checkbox", checked: checked, disabled: !enabled, onChange: toggle })), dropBox(children)] }));
 }
 /**
  * The children of the item without the checkbox GFM put in front of them.
@@ -246,7 +282,10 @@ export function Markdown({ children, source, onToggleTask, writable = false, foo
     const text = toUnixNewlines(children);
     const { strings } = useHost();
     const calloutTitle = (kind) => Object.hasOwn(strings.callouts, kind) ? strings.callouts[kind] : undefined;
-    return (_jsx("div", { className: "markdown", children: _jsx(ReactMarkdown, { remarkPlugins: readingPlugins(calloutTitle), 
+    return (
+    // The pass that draws a cut note's footnotes continues the note rather than opening a run,
+    // so its section keeps the space a section takes at the end of a note.
+    _jsx("div", { className: footnotes === 'section' ? 'markdown footnotes-run' : 'markdown', children: _jsx(ReactMarkdown, { remarkPlugins: readingPlugins(calloutTitle), 
             // Raw HTML is NOT enabled, and its absence is the point: no
             // `rehype-raw` is loaded, so a note carrying `<script>` is text. It is
             // a security boundary rather than a rendering preference, because a
@@ -278,6 +317,11 @@ export function Markdown({ children, source, onToggleTask, writable = false, foo
                 code: MarkdownCode,
                 pre: MarkdownPre,
                 img: MarkdownImage,
+                div: MarkdownDiv,
+                table: MarkdownTable,
+                blockquote: MarkdownBlockquote,
+                section: MarkdownSection,
+                ...headings,
                 li: (props) => (_jsx(TaskItem, { ...props, source: source ?? text, toggleTask: onToggleTask, writable: writable })),
             }, children: text }) }));
 }

package/dist/MermaidDiagram.d.ts

@@ -1,7 +1,7 @@
 interface MermaidDiagramProps {
     readonly code: string;
-    /** The theme the host draws in, which picks Mermaid's own. */
-    readonly theme: 'light' | 'dark';
+    /** The scheme the note is drawn in, which picks Mermaid's own theme. */
+    readonly scheme: 'light' | 'dark';
 }
 /**
  * A mermaid code block drawn as an SVG diagram (§7.2). The library is heavy, so
@@ -12,5 +12,5 @@ interface MermaidDiagramProps {
  * output, not note-derived HTML: Mermaid renders with its default `strict`
  * security level, which encodes the text of the diagram.
  */
-export declare function MermaidDiagram({ code, theme }: MermaidDiagramProps): import("react").JSX.Element;
+export declare function MermaidDiagram({ code, scheme }: MermaidDiagramProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | null | undefined;
 export {};

package/dist/MermaidDiagram.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useId, useState } from 'react';
+import { drawSlot, useSlot } from './slots.js';
 /**
  * A mermaid code block drawn as an SVG diagram (§7.2). The library is heavy, so
  * it is imported lazily, out of the bundle that draws the rest of the note; on
@@ -9,7 +10,7 @@ import { useEffect, useId, useState } from 'react';
  * output, not note-derived HTML: Mermaid renders with its default `strict`
  * security level, which encodes the text of the diagram.
  */
-export function MermaidDiagram({ code, theme }) {
+export function MermaidDiagram({ code, scheme }) {
     const id = useId().replace(/[^a-zA-Z0-9]/g, '');
     const [svg, setSvg] = useState(null);
     const [failed, setFailed] = useState(false);
@@ -26,7 +27,7 @@ export function MermaidDiagram({ code, theme }) {
                 await document.fonts?.ready;
                 mermaid.initialize({
                     startOnLoad: false,
-                    theme: theme === 'dark' ? 'dark' : 'neutral',
+                    theme: scheme === 'dark' ? 'dark' : 'neutral',
                     fontFamily: 'Inter, sans-serif',
                     // SVG text labels measure reliably; HTML labels clip inside nodes
                     // when the webfont metrics differ from the fallback.
@@ -60,11 +61,9 @@ export function MermaidDiagram({ code, theme }) {
         return () => {
             alive = false;
         };
-    }, [code, id, theme]);
-    if (failed) {
-        return (_jsx("pre", { children: _jsx("code", { children: code }) }));
-    }
-    if (!svg)
-        return _jsx("div", { className: "mermaid-diagram mermaid-loading" });
-    return _jsx("div", { className: "mermaid-diagram", dangerouslySetInnerHTML: { __html: svg } });
+    }, [code, id, scheme]);
+    const slot = useSlot('diagram');
+    const state = failed ? 'failed' : svg ? 'ready' : 'loading';
+    const drawn = state === 'failed' ? (_jsx("pre", { children: _jsx("code", { children: code }) })) : state === 'ready' ? (_jsx("div", { className: "mermaid-diagram", dangerouslySetInnerHTML: { __html: svg ?? '' } })) : (_jsx("div", { className: "mermaid-diagram mermaid-loading" }));
+    return slot ? drawSlot(slot, { source: code, state, children: drawn }) : drawn;
 }

package/dist/NoteBody.js

@@ -4,7 +4,10 @@ import { HOST_KEYS, HostProvider, resolveHost } from './host.js';
 import { planFootnotes } from './footnotes.js';
 import { Markdown, readingPlugins } from './Markdown.js';
 import { bodyStart, remoteImageHosts, resolveWikilinks } from './markdown.js';
+import { readProperties } from './properties.js';
+import { Properties } from './PropertiesBlock.js';
 import { taskBoxes } from './tasklist.js';
+import { rootStyle } from './theme.js';
 import { Transclusion } from './Transclusion.js';
 import { splitEmbeds } from './transclusion.js';
 import { wikilinkAddress } from './wikilink-address.js';
@@ -18,9 +21,10 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
     const resolved = useMemo(() => resolveHost(host), 
     // Every member of the contract, so a host that passes the same functions keeps the same host.
     HOST_KEYS.map((key) => host[key]));
-    // Frontmatter is shown as properties, not as prose, so the reading surface
-    // starts after it. Everything below counts task items from there.
+    // The frontmatter is drawn apart from the body, as the theme decides, so the
+    // runs start after it. Everything below counts task items from there.
     const split = bodyStart(markdown);
+    const properties = useMemo(() => readProperties(markdown), [markdown]);
     const body = markdown.slice(split);
     // The body is cut into runs of text and the embeds between them; each run
     // is parsed on its own, as on MemorySmith's reading page.
@@ -74,7 +78,7 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
     // The runs and whether an embed cut them are the whole input.
     [runs.join('\u0000'), runs.length < segments.length]);
     let run = 0;
-    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: "markdown", "data-theme": resolved.theme, children: [segments.map((segment, index) => {
+    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name}`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [_jsx(Properties, { properties: properties }), segments.map((segment, index) => {
                     if (!('rendered' in segment)) {
                         return _jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index);
                     }

package/dist/PropertiesBlock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The frontmatter of a note, drawn above its body — or not — as the theme decides.
+ *
+ * The renderer reads it (`readProperties`) and hands it to the theme's
+ * `properties` slot. With none, the default theme draws what MemorySmith's note
+ * page draws above the body (*observed* at `4b67c7e`): the name as the note's
+ * title, always — *Unnamed note* when it has none — and the properties in a
+ * block that folds, under a rule and never in a card. The reserved keys come
+ * first, in the order of the specification, then the notebook's own in the
+ * order written; each key wears the icon of the shape of its value; a list is
+ * chips, a boolean the reader's *Yes* or *No*, a date in the reader's locale,
+ * and what was typed stays in the title of each.
+ */
+import type { ReactNode } from 'react';
+import { type NoteProperties } from './properties.js';
+export declare function Properties({ properties }: {
+    properties: NoteProperties;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;

package/dist/PropertiesBlock.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useHost } from './host.js';
+import { MarkdownAnchor } from './Markdown.js';
+import { DRAWN_RESERVED_KEYS, isTrue, VALUE_LINK, } from './properties.js';
+import { drawSlot, useSlot } from './slots.js';
+import { wikilinkAddress } from './wikilink-address.js';
+/**
+ * A value as the note means it: a wikilink a link to where the host resolved it — the note, the
+ * choice, or the pending marker — a Markdown link or a bare address to the web a link to it, each
+ * through the anchor the body's links take, so the address filter holds and a theme's `wikilink`
+ * slot draws them too; everything else as text, never as markup.
+ */
+function useValue() {
+    const host = useHost();
+    return (text) => {
+        const parts = [];
+        let cursor = 0;
+        for (const match of text.matchAll(VALUE_LINK)) {
+            const at = match.index ?? 0;
+            if (at > cursor)
+                parts.push(text.slice(cursor, at));
+            const [whole, wikiTarget, wikiLabel, mdLabel, mdUrl, rawUrl] = match;
+            if (wikiTarget) {
+                const target = wikiTarget.trim();
+                const name = target.split('#')[0]?.trim() ?? '';
+                const address = name ? wikilinkAddress(host, name.normalize('NFC')) : null;
+                parts.push(_jsx(MarkdownAnchor, { href: address ?? `pending:${encodeURIComponent(name)}`, children: wikiLabel?.trim() || target }, at));
+            }
+            else {
+                parts.push(_jsx(MarkdownAnchor, { href: mdUrl ?? rawUrl, children: mdLabel ?? rawUrl }, at));
+            }
+            cursor = at + whole.length;
+        }
+        if (cursor < text.length)
+            parts.push(text.slice(cursor));
+        return parts.length === 1 ? parts[0] : _jsx(_Fragment, { children: parts });
+    };
+}
+/** The type that picks a key's icon, by the shape of its value and never by its key. */
+function iconType(entry) {
+    if (entry.shape === 'list')
+        return 'list';
+    if (entry.shape === 'boolean')
+        return 'checkbox';
+    if (entry.shape === 'date')
+        return 'date';
+    return 'text';
+}
+/**
+ * A date in the reader's locale, as the rest of an interface writes one. A note's date carries no
+ * zone, so it is read and written in UTC: read in the zone of the browser, `2026-09-21` is the
+ * evening of the 20th west of Greenwich. A form the reading does not take stays as typed.
+ */
+function readableDate(value, locale) {
+    const typed = value.trim();
+    if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})?$/.test(typed))
+        return null;
+    const [day, time] = typed.split(/[T ]/);
+    const [year, month, date] = (day ?? '').split('-').map(Number);
+    const [hours, minutes] = (time ?? '').split(':').map(Number);
+    const when = new Date(Date.UTC(year ?? 0, (month ?? 1) - 1, date ?? 1, hours ?? 0, minutes ?? 0));
+    if (when.getUTCDate() !== date || when.getUTCMonth() !== (month ?? 1) - 1)
+        return null;
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'medium', ...(time ? { timeStyle: 'short' } : {}), timeZone: 'UTC' }).format(when);
+    }
+    catch {
+        return null;
+    }
+}
+function PropertyValue({ entry, value }) {
+    const { strings } = useHost();
+    if (entry.shape === 'list') {
+        return (_jsx("span", { className: "prop-tags", children: entry.values.map((item, index) => (_jsx("span", { className: "prop-tag", children: value(item) }, index))) }));
+    }
+    const typed = (entry.values[0] ?? '').trim();
+    if (entry.shape === 'boolean')
+        return _jsx("span", { title: typed, children: isTrue(typed) ? strings.yes : strings.no });
+    if (entry.shape === 'date') {
+        const readable = readableDate(typed, strings.locale);
+        if (readable !== null) {
+            return (_jsx("time", { dateTime: typed, title: typed, children: readable }));
+        }
+    }
+    return _jsx(_Fragment, { children: value(typed) });
+}
+/** The reserved keys first, in the order of the specification, then the rest in the order written. */
+function ordered(entries) {
+    const rank = (key) => {
+        const at = DRAWN_RESERVED_KEYS.indexOf(key);
+        return at === -1 ? DRAWN_RESERVED_KEYS.length : at;
+    };
+    return entries
+        .filter((entry) => entry.shape !== 'empty')
+        .map((entry, index) => ({ entry, index }))
+        .sort((left, right) => rank(left.entry.key) - rank(right.entry.key) || left.index - right.index)
+        .map(({ entry }) => entry);
+}
+export function Properties({ properties }) {
+    const { strings } = useHost();
+    const slot = useSlot('properties');
+    const value = useValue();
+    if (slot)
+        return drawSlot(slot, { name: properties.name, entries: properties.entries, value });
+    const shown = ordered(properties.entries);
+    return (_jsxs(_Fragment, { children: [_jsx("h1", { className: properties.name === null ? 'note-title note-unnamed' : 'note-title', children: properties.name ?? strings.unnamedNote }), shown.length > 0 && (_jsxs("details", { className: "properties-box", open: true, children: [_jsx("summary", { children: strings.properties }), _jsx("div", { className: "metadata-container", children: shown.map((entry, index) => (_jsxs("div", { className: "metadata-property", "data-property-type": iconType(entry), children: [_jsx("span", { className: "metadata-property-key", children: entry.key }), _jsx("span", { className: "metadata-property-value", children: _jsx(PropertyValue, { entry: entry, value: value }) })] }, index))) })] }))] }));
+}

package/dist/Transclusion.d.ts

@@ -8,4 +8,4 @@
 export declare function Transclusion({ target, anchor }: {
     target: string;
     anchor: string | null;
-}): import("react").JSX.Element;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | null | undefined;

package/dist/Transclusion.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { useHost } from './host.js';
 import { Markdown } from './Markdown.js';
+import { drawSlot, useSlot } from './slots.js';
 import { bodyStart, resolveWikilinks } from './markdown.js';
 import { blockOf, demoteEmbeds, isBlockAnchor, sectionOf } from './transclusion.js';
 import { wikilinkAddress } from './wikilink-address.js';
@@ -25,6 +26,7 @@ export function Transclusion({ target, anchor }) {
     // passage the page can inline on their behalf.
     const one = host.loadNote !== null && host.reaches(name) === 1;
     const [loaded, setLoaded] = useState({ state: 'loading' });
+    const slot = useSlot('embed');
     useEffect(() => {
         if (!one || !host.loadNote)
             return;
@@ -39,10 +41,13 @@ export function Transclusion({ target, anchor }) {
     // is still being written, so a target that does not exist yet is an
     // expected state and never an error that stops the page.
     if (!one || loaded.state === 'missing') {
-        return (_jsx("p", { className: "embed-pending", children: _jsx("span", { className: "wikilink-pending", title: strings.pendingLink, children: target }) }));
+        const marker = (_jsx("p", { className: "embed-pending", children: _jsx("span", { className: "wikilink-pending", title: strings.pendingLink, children: target }) }));
+        return slot ? drawSlot(slot, { state: 'pending', target, anchor, caption: null, children: marker }) : marker;
+    }
+    if (loaded.state === 'loading') {
+        const skeleton = _jsx(TransclusionSkeleton, { loading: strings.loading });
+        return slot ? drawSlot(slot, { state: 'loading', target, anchor, caption: null, children: skeleton }) : skeleton;
     }
-    if (loaded.state === 'loading')
-        return _jsx(TransclusionSkeleton, { loading: strings.loading });
     const { note } = loaded;
     const whole = note.markdown.slice(bodyStart(note.markdown));
     // The caption names the note the content came from, and a note may have no
@@ -53,14 +58,25 @@ export function Transclusion({ target, anchor }) {
     // section named `^x` and a block called `x` would answer for each other.
     const cut = !anchor ? whole : isBlockAnchor(anchor) ? blockOf(whole, anchor.slice(1)) : sectionOf(whole, anchor);
     const caption = anchor ? `${sourceLabel} › ${anchor}` : sourceLabel;
-    return (_jsxs("figure", { className: "embed", children: [_jsx("div", { className: "embed-body", children: cut === null ? (_jsx("p", { className: "embed-missing", children: strings.embedSectionMissing(anchor ?? '') })) : (
-                /**
-                 * Resolved, like every other run of the note. Without this every
-                 * `[[link]]` inside transcluded content reached the page with its
-                 * brackets — and the sharpest case is the one the one-level rule
-                 * creates itself: `demoteEmbeds` turns an embed found in embedded
-                 * content into a wikilink, and that embed is drawn as A LINK to its
-                 * target. Raw text is not a link.
-                 */
-                _jsx(Markdown, { children: resolveWikilinks(demoteEmbeds(cut, host.keeps), (each) => wikilinkAddress(host, each), host.keeps) })) }), _jsx("figcaption", { className: "embed-source", children: note.address === null ? caption : host.renderLink({ href: note.address, children: caption }) })] }));
+    const named = note.address === null ? caption : host.renderLink({ href: note.address, children: caption });
+    const content = cut === null ? (_jsx("p", { className: "embed-missing", children: strings.embedSectionMissing(anchor ?? '') })) : (
+    /**
+     * Resolved, like every other run of the note. Without this every
+     * `[[link]]` inside transcluded content reached the page with its
+     * brackets — and the sharpest case is the one the one-level rule
+     * creates itself: `demoteEmbeds` turns an embed found in embedded
+     * content into a wikilink, and that embed is drawn as A LINK to its
+     * target. Raw text is not a link.
+     */
+    _jsx(Markdown, { children: resolveWikilinks(demoteEmbeds(cut, host.keeps), (each) => wikilinkAddress(host, each), host.keeps) }));
+    if (slot) {
+        return drawSlot(slot, {
+            state: cut === null ? 'section-missing' : 'ready',
+            target,
+            anchor,
+            caption: named,
+            children: content,
+        });
+    }
+    return (_jsxs("figure", { className: "embed", children: [_jsx("div", { className: "embed-body", children: content }), _jsx("figcaption", { className: "embed-source", children: named })] }));
 }

package/dist/host.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import { type NoteStrings } from './strings.js';
+import { type Scheme, type Theme } from './theme.js';
 /**
  * The host contract: everything the renderer needs from the notebook a note lives in, given by
  * whoever draws it.
@@ -62,8 +63,17 @@ export interface NoteHost {
     readonly renderLink?: (link: LinkRequest) => ReactNode;
     /** The words the page shows, in the reader's language; each one left out is MemorySmith's English. */
     readonly strings?: Partial<NoteStrings>;
-    /** The theme the host draws in, which picks the theme of a Mermaid diagram. Defaults to `light`. */
-    readonly theme?: 'light' | 'dark';
+    /**
+     * How the note looks: a theme (`defineTheme`), or `light` or `dark`, which are the default
+     * theme — MemorySmith's look — in that scheme. Defaults to the default theme.
+     */
+    readonly theme?: Scheme | Theme;
+    /**
+     * The scheme a theme is drawn in, which also picks the theme of a Mermaid diagram. Defaults to
+     * the scheme `theme` names when it is `light` or `dark`, and to `light` otherwise; a theme of one
+     * scheme is drawn in it whatever is asked.
+     */
+    readonly scheme?: Scheme;
     /**
      * Whether a note that fetched images from other sites says so, naming them, under the body
      * (§7.10). Defaults to `true`: the specification forbids only silence. A host that discloses it
@@ -127,7 +137,10 @@ export interface ResolvedHost {
     readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;
     readonly renderLink: (link: LinkRequest) => ReactNode;
     readonly strings: NoteStrings;
-    readonly theme: 'light' | 'dark';
+    /** The theme the note is drawn in. */
+    readonly theme: Theme;
+    /** The scheme it is drawn in. */
+    readonly scheme: Scheme;
 }
 export declare function resolveHost(host: NoteHost): ResolvedHost;
 export declare const HostProvider: import("react").Provider<ResolvedHost>;

package/dist/host.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
 import { withDefaults } from './strings.js';
+import { DEFAULT_THEME, schemeOf } from './theme.js';
 /**
  * Every member of the contract, by name. The `satisfies` is what makes it complete: a member added
  * to `NoteHost` and not listed here does not compile.
@@ -19,11 +20,18 @@ export const HOST_KEYS = Object.keys({
     renderLink: 1,
     strings: 1,
     theme: 1,
+    scheme: 1,
     remoteNotice: 1,
 });
 const nothing = () => null;
 const never = () => false;
 const plainLink = ({ href, className, children }) => (_jsx("a", { className: className, href: href, children: children }));
+function themeOf(host) {
+    const given = host.theme ?? DEFAULT_THEME;
+    const theme = typeof given === 'string' ? DEFAULT_THEME : given;
+    const asked = host.scheme ?? (typeof given === 'string' ? given : 'light');
+    return { theme, scheme: schemeOf(theme, asked) };
+}
 export function resolveHost(host) {
     const resolve = host.resolve ?? nothing;
     return {
@@ -38,7 +46,7 @@ export function resolveHost(host) {
         renderAttachment: host.renderAttachment ?? null,
         renderLink: host.renderLink ?? plainLink,
         strings: withDefaults(host.strings),
-        theme: host.theme ?? 'light',
+        ...themeOf(host),
     };
 }
 const HostContext = createContext(resolveHost({}));

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { NoteBody, type NoteBodyProps } from './NoteBody.js';
 export type { AttachmentRequest, EmbeddedNote, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
 export { ENGLISH, type NoteStrings } from './strings.js';
+export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, type BlockquoteSlotProps, type CalloutSlotProps, type CodeBlockSlotProps, type DiagramSlotProps, type EmbedSlotProps, type FootnotesSlotProps, type HeadingSlotProps, type InlineCodeSlotProps, type PropertiesSlotProps, type Scheme, type TableSlotProps, type TaskBoxSlotProps, type Theme, type ThemeComponents, type ThemeProperties, type WikilinkSlotProps, } from './theme.js';
 export { followable } from './address.js';
 export { readDimensions, readImageAlt, type ImageAlt } from './image-dimensions.js';
 export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, type SplitDocument, } from './markdown.js';
 export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { readProperties, type NoteProperties, type PropertyEntry, type PropertyShape } from './properties.js';
 export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';