@memorysmithapp/markdown-renderer 0.1.2 → 0.3.0

package/README.md

@@ -29,9 +29,70 @@ 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.
+
+## Diagnose
+
+Every note is valid, and nothing here refuses one. What `diagnose` tells a host is where the page will not show what was most likely typed, and what the note lacks that the specification reserves a place for: the notices of [`SPEC.md` §7.13](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/packages/markdown-spec/SPEC.md#713-notices). It imports no React and needs no DOM, so it runs in an editor, on a server, or in a tool that writes a note.
+
+```ts
+import { diagnose } from '@memorysmithapp/markdown-renderer/diagnose';
+
+const notices = await diagnose(note, {
+  resolve: (name) => addressOfTheOneNoteNamed(name), // or reaches; leave both out and no link is pending
+  keeps: (name) => notebookKeepsAFile(name),
+});
+// [{ code: 'heading-skipped-level', severity: 'notice', section: '3.3',
+//    message: 'This heading skips a level below the heading before it.',
+//    line: 12, column: 1, endLine: 12, endColumn: 14 }, …]
+```
+
+A `notice` says the page will differ from the text — a fence never closed, a formula KaTeX cannot typeset, a diagram Mermaid cannot read, raw HTML, a footnote with no definition or no reference, a single-tilde strikethrough, a frontmatter never closed, a `name` that leaves the note unnamed or none at all, `aliases` or `tags` that are not a list, a body that does not start at `#` or skips a level. A `hint` says nothing is drawn wrong: no `aliases`, no `tags`, a link or an embed no note answers yet. Lines and columns count from 1 over the whole note, frontmatter included, and the `message` is English; a host words it in its own language from the `code`, which is stable. Mermaid is loaded only for a note that holds a diagram, and `diagrams: false` skips it.
+
+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,4 +1,4 @@
-import type { PluggableList } from 'unified';
+import { type AnchorHTMLAttributes, type ReactNode } from 'react';
 import { type FootnoteRef } from './footnotes.js';
 /**
  * One run of a note, parsed and drawn: the pipeline of MemorySmith's reading page.
@@ -28,8 +28,14 @@ export interface MarkdownProps {
     } | 'section';
 }
 /**
- * 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.
+ * 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.
  */
-export declare function readingPlugins(titleOf: (kind: string) => string | undefined): PluggableList;
+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;
 export declare function Markdown({ children, source, onToggleTask, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
+export {};

package/dist/Markdown.js

@@ -1,11 +1,9 @@
 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';
-import remarkGfm from 'remark-gfm';
-import remarkMath from 'remark-math';
 import { followable } from './address.js';
 import { CopyButton } from './CopyButton.js';
 import { highlightLanguage, highlightTree } from './highlight.js';
@@ -14,9 +12,9 @@ import { readDimensions, readImageAlt } from './image-dimensions.js';
 import { choiceTargetOf, LinkChoice } from './LinkChoice.js';
 import { toUnixNewlines } from './markdown.js';
 import { MermaidDiagram } from './MermaidDiagram.js';
-import { remarkCallouts } from './remark-callouts.js';
-import { remarkBlockIds, remarkComments, remarkHighlight, remarkMathDollarRule } from './remark-ring.js';
+import { readingPlugins } from './reading.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 +70,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 +92,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 +103,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 +138,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 +171,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 +219,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 +228,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.
@@ -215,38 +248,14 @@ function dropBox(children) {
         return children;
     return children.filter((child) => !(isValidElement(child) && child.type === 'input'));
 }
-/**
- * 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 function readingPlugins(titleOf) {
-    return [
-        /**
-         * `singleTilde: false` is a decision and not a default.
-         *
-         * GFM specifies strikethrough as `~~x~~`; GitHub also accepts a
-         * single tilde, outside its own specification. Here that extension
-         * actively misrenders a notation the specification leaves out:
-         * somebody writing `H~2~O` for a subscript would get `H` struck-out
-         * `2` `O`, which is a worse answer than nothing. With it off the
-         * characters stay on the page, and the author can see they got what
-         * the specification says they get, which is nothing.
-         */
-        [remarkGfm, { singleTilde: false }],
-        [remarkCallouts, { titleOf }],
-        remarkHighlight,
-        remarkComments,
-        remarkBlockIds,
-        remarkMath,
-        // After remark-math, and it gives back what was never a formula.
-        remarkMathDollarRule,
-    ];
-}
 export function Markdown({ children, source, onToggleTask, writable = false, footnotes }) {
     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 +287,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

@@ -2,9 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
 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 { Markdown } from './Markdown.js';
+import { readingPlugins } from './reading.js';
+import { bodyStart, hideComments, 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,10 +22,12 @@ 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 body = markdown.slice(split);
+    const properties = useMemo(() => readProperties(markdown), [markdown]);
+    // What a comment holds is never read (§7.6): it leaves before the embeds and the links are found.
+    const body = hideComments(markdown.slice(split)).text;
     // 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.
     const segments = splitEmbeds(body, resolved.keeps).map((segment) => segment.kind === 'text'
@@ -74,7 +80,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,7 +2,8 @@ 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 { bodyStart, resolveWikilinks } from './markdown.js';
+import { drawSlot, useSlot } from './slots.js';
+import { bodyStart, hideComments, resolveWikilinks } from './markdown.js';
 import { blockOf, demoteEmbeds, isBlockAnchor, sectionOf } from './transclusion.js';
 import { wikilinkAddress } from './wikilink-address.js';
 /** The shape of what is coming, in the position it will occupy, while the host answers. */
@@ -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,12 +41,15 @@ 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));
+    const whole = hideComments(note.markdown.slice(bodyStart(note.markdown))).text;
     // The caption names the note the content came from, and a note may have no
     // name.
     const sourceLabel = note.name ?? strings.unnamedNote;
@@ -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 })] }));
 }