@memorysmithapp/markdown-renderer 0.1.0 → 0.1.1

package/dist/Markdown.d.ts

@@ -1,3 +1,5 @@
+import type { PluggableList } from 'unified';
+import { type FootnoteRef } from './footnotes.js';
 /**
  * One run of a note, parsed and drawn: the pipeline of MemorySmith's reading page.
  *
@@ -16,5 +18,18 @@ export interface MarkdownProps {
     readonly source?: string;
     readonly onToggleTask?: (ordinal: number) => void;
     readonly writable?: boolean;
+    /**
+     * How this run takes part in the footnotes of a note drawn in several runs
+     * (`footnotes.ts`): the number and id of each of its references, or
+     * `'section'` for the pass that draws the note's one section.
+     */
+    readonly footnotes?: {
+        readonly refs: readonly FootnoteRef[];
+    } | 'section';
 }
-export declare function Markdown({ children, source, onToggleTask, writable }: MarkdownProps): import("react").JSX.Element;
+/**
+ * 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;

package/dist/Markdown.js

@@ -16,6 +16,7 @@ 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 { CLOBBER_PREFIX, rehypeFootnoteRun, rehypeFootnoteSection } from './footnotes.js';
 import { ordinalAt } from './tasklist.js';
 /**
  * An image, with the dimensions the specification puts in its alt text
@@ -42,8 +43,13 @@ function MarkdownImage({ alt, node: _node, ...rest }) {
 function InPageAnchor({ href, children, ...rest }) {
     const follow = (event) => {
         const id = decodeURIComponent(href.slice(1));
-        const note = event.currentTarget.closest('.markdown');
-        const target = note?.querySelector(`[id="${CSS.escape(id)}"]`);
+        // The note is the root `NoteBody` draws, since a footnote's way back may
+        // cross runs; inside an embed it is the embed's own run. A match inside
+        // an embed answers only a link inside that same embed.
+        const link = event.currentTarget;
+        const embed = link.closest('.embed');
+        const note = embed ? link.closest('.markdown') : (link.closest('.markdown[data-theme]') ?? link.closest('.markdown'));
+        const target = [...(note?.querySelectorAll(`[id="${CSS.escape(id)}"]`) ?? [])].find((candidate) => candidate.closest('.embed') === embed);
         if (!(target instanceof HTMLElement))
             return;
         event.preventDefault();
@@ -209,42 +215,58 @@ function dropBox(children) {
         return children;
     return children.filter((child) => !(isValidElement(child) && child.type === 'input'));
 }
-export function Markdown({ children, source, onToggleTask, writable = false }) {
+/**
+ * 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: [
-                /**
-                 * `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: calloutTitle }],
-                remarkHighlight,
-                remarkComments,
-                remarkBlockIds,
-                remarkMath,
-                // After remark-math, and it gives back what was never a formula.
-                remarkMathDollarRule,
-            ], 
+    return (_jsx("div", { className: "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
             // notebook is written by several people and by agents (§7.9).
             // A formula KaTeX cannot typeset shows its source, never an error (§7.8).
-            rehypePlugins: [[rehypeKatex, { throwOnError: false }]], 
+            rehypePlugins: [
+                [rehypeKatex, { throwOnError: false }],
+                ...(footnotes === undefined
+                    ? []
+                    : footnotes === 'section'
+                        ? [rehypeFootnoteSection]
+                        : [[rehypeFootnoteRun, footnotes]]),
+            ], 
             // Footnotes (§7.12): the words around them are the reader's, and the
             // label heads the notes gathered at the end of the note, where a
             // reader sees it — GFM hides it, and a stylesheet that hides nothing
             // shows it as a visible heading, so it is in the reader's language.
             remarkRehypeOptions: {
+                // remark-rehype's own default, stated: `footnotes.ts` renumbers by it.
+                clobberPrefix: CLOBBER_PREFIX,
                 footnoteLabel: strings.footnotes,
                 footnoteLabelProperties: { className: ['footnotes-label'] },
                 footnoteBackLabel: (referenceIndex) => strings.footnoteBack(referenceIndex + 1),

package/dist/NoteBody.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
 import { HOST_KEYS, HostProvider, resolveHost } from './host.js';
-import { Markdown } from './Markdown.js';
+import { planFootnotes } from './footnotes.js';
+import { Markdown, readingPlugins } from './Markdown.js';
 import { bodyStart, remoteImageHosts, resolveWikilinks } from './markdown.js';
 import { taskBoxes } from './tasklist.js';
 import { Transclusion } from './Transclusion.js';
@@ -64,16 +65,28 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
      * every note would be a thing to scroll past rather than a thing to read.
      */
     const hosts = resolved.remoteNotice ? remoteImageHosts(body) : [];
+    // The footnotes of a note an embed cuts (§7.12): each run is handed the
+    // definitions of the others and the numbers of the note, and the note's one
+    // section is drawn at its end, below the last embed too. Null, and nothing
+    // changes, for a note no embed cuts or with no footnote to carry.
+    const runs = segments.flatMap((segment) => ('rendered' in segment ? [segment.rendered] : []));
+    const footnotes = useMemo(() => planFootnotes(runs, runs.length < segments.length, readingPlugins(() => undefined)), 
+    // 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) => {
                     if (!('rendered' in segment)) {
                         return _jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index);
                     }
                     const base = seen;
                     seen += taskBoxes(segment.rendered).length;
+                    const planned = footnotes?.runs[run++];
                     return (_jsx(Markdown, { 
                         // The text the ordinal is counted over, stated rather than left to
                         // a default: it is the one the parser reports offsets into, and
                         // `mappable` above is what makes it safe to write back through.
-                        source: segment.rendered, onToggleTask: onToggleTask && ((ordinal) => onToggleTask(base + ordinal)), writable: writable && mappable, children: segment.rendered }, index));
-                }), hosts.length > 0 && _jsx("p", { className: "remote-notice", children: resolved.strings.remoteImages(hosts) })] }) }));
+                        // A planned run is the same text with definitions appended after
+                        // it, so every box keeps the offset it had.
+                        source: planned?.text ?? segment.rendered, onToggleTask: onToggleTask && ((ordinal) => onToggleTask(base + ordinal)), writable: writable && mappable, ...(planned ? { footnotes: { refs: planned.refs } } : {}), children: planned?.text ?? segment.rendered }, index));
+                }), footnotes && _jsx(Markdown, { footnotes: "section", children: footnotes.section }), hosts.length > 0 && _jsx("p", { className: "remote-notice", children: resolved.strings.remoteImages(hosts) })] }) }));
 }

package/dist/footnotes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Footnotes across the runs of a note (§7.12).
+ *
+ * `NoteBody` draws the text between two embeds as runs of their own, each
+ * through its own parser, and a footnote is resolved inside one parse: GFM
+ * reads `[^label]` as a reference only when the same document defines
+ * `label`. A reference above an embed and its definition below it therefore
+ * never met, and the reference reached the page as its characters. MemorySmith's
+ * reading page does the same; this renderer does not carry it.
+ *
+ * The runs stay runs — they are what keeps the task ordinals and the layout
+ * of every other note as MemorySmith draws them — and the note is drawn as one
+ * document would draw it:
+ *
+ * - every run is handed the definitions written in the OTHER runs, appended
+ *   after its own text, so its references parse; appending after the text
+ *   moves no offset the task boxes are counted from;
+ * - each run's own footnotes section is dropped, and each reference is
+ *   renumbered in the order of the note, with the id one document would give
+ *   its n-th use of a label;
+ * - one section is drawn at the end of the note, after its last embed too,
+ *   from every reference of the note in order and every definition, so its
+ *   numbers and its ways back are the ones a single document would have.
+ *
+ * Only a definition written at the top level of a run travels. A note with
+ * one inside a quote or a list, with no embed, or with no definition, is
+ * planned as nothing and drawn exactly as before.
+ */
+import { type PluggableList } from 'unified';
+/** The prefix remark-rehype gives every footnote id, set explicitly where `Markdown` draws. */
+export declare const CLOBBER_PREFIX = "user-content-";
+interface HastNode {
+    type: string;
+    tagName?: string;
+    value?: string;
+    properties?: Record<string, unknown>;
+    children?: HastNode[];
+}
+/** One reference as the note numbers it: its footnote's number, and which use of the label it is. */
+export interface FootnoteRef {
+    readonly number: number;
+    readonly occurrence: number;
+}
+export interface FootnotePlan {
+    /** For each run, in order: the text its parser reads, and its references in the order it draws them. */
+    readonly runs: readonly {
+        readonly text: string;
+        readonly refs: readonly FootnoteRef[];
+    }[];
+    /** The text the one footnotes section of the note is drawn from. */
+    readonly section: string;
+}
+/**
+ * How the runs of a note draw their footnotes, or null when nothing has to
+ * change: a note no embed cuts, or one with no footnote to carry. `cut` says
+ * whether an embed cut it — a note of one run followed by an embed is cut
+ * too, because its notes belong below the embed, at the end of the note.
+ *
+ * `plugins` are the remark plugins of `Markdown`, so a reference the reading
+ * surface would not draw — inside a comment, say — is not counted either.
+ */
+export declare function planFootnotes(runs: readonly string[], cut: boolean, plugins: PluggableList): FootnotePlan | null;
+/**
+ * The rehype side of a run: its own section dropped, and each reference given
+ * the number and the id the note gives it.
+ */
+export declare function rehypeFootnoteRun(options: {
+    refs: readonly FootnoteRef[];
+}): (tree: HastNode) => void;
+/** The rehype side of the section pass: the section and nothing else. */
+export declare function rehypeFootnoteSection(): (tree: HastNode) => void;
+export {};

package/dist/footnotes.js

@@ -0,0 +1,137 @@
+/**
+ * Footnotes across the runs of a note (§7.12).
+ *
+ * `NoteBody` draws the text between two embeds as runs of their own, each
+ * through its own parser, and a footnote is resolved inside one parse: GFM
+ * reads `[^label]` as a reference only when the same document defines
+ * `label`. A reference above an embed and its definition below it therefore
+ * never met, and the reference reached the page as its characters. MemorySmith's
+ * reading page does the same; this renderer does not carry it.
+ *
+ * The runs stay runs — they are what keeps the task ordinals and the layout
+ * of every other note as MemorySmith draws them — and the note is drawn as one
+ * document would draw it:
+ *
+ * - every run is handed the definitions written in the OTHER runs, appended
+ *   after its own text, so its references parse; appending after the text
+ *   moves no offset the task boxes are counted from;
+ * - each run's own footnotes section is dropped, and each reference is
+ *   renumbered in the order of the note, with the id one document would give
+ *   its n-th use of a label;
+ * - one section is drawn at the end of the note, after its last embed too,
+ *   from every reference of the note in order and every definition, so its
+ *   numbers and its ways back are the ones a single document would have.
+ *
+ * Only a definition written at the top level of a run travels. A note with
+ * one inside a quote or a list, with no embed, or with no definition, is
+ * planned as nothing and drawn exactly as before.
+ */
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/** The prefix remark-rehype gives every footnote id, set explicitly where `Markdown` draws. */
+export const CLOBBER_PREFIX = 'user-content-';
+/** What one document would key a label by: remark-rehype's own normalisation. */
+const keyOf = (node) => String(node.identifier ?? '').toUpperCase();
+/**
+ * How the runs of a note draw their footnotes, or null when nothing has to
+ * change: a note no embed cuts, or one with no footnote to carry. `cut` says
+ * whether an embed cut it — a note of one run followed by an embed is cut
+ * too, because its notes belong below the embed, at the end of the note.
+ *
+ * `plugins` are the remark plugins of `Markdown`, so a reference the reading
+ * surface would not draw — inside a comment, say — is not counted either.
+ */
+export function planFootnotes(runs, cut, plugins) {
+    if (!cut || !runs.some((run) => run.includes('[^')))
+        return null;
+    const processor = unified().use(remarkParse).use(plugins);
+    const read = (text) => processor.runSync(processor.parse(text), text);
+    // The definitions, the first of each label winning, as in one document.
+    const definitions = new Map();
+    let nested = false;
+    runs.forEach((run, index) => {
+        const tree = processor.parse(run);
+        const below = (node) => (node.children ?? []).some((child) => child.type === 'footnoteDefinition' || below(child));
+        nested ||= (tree.children ?? []).some(below);
+        for (const child of tree.children ?? []) {
+            const start = child.position?.start?.offset;
+            const end = child.position?.end?.offset;
+            if (child.type !== 'footnoteDefinition' || start === undefined || end === undefined)
+                continue;
+            if (!definitions.has(keyOf(child)))
+                definitions.set(keyOf(child), { source: run.slice(start, end), run: index });
+        }
+    });
+    // A definition inside a quote or a list cannot be lifted into the section
+    // without its markers, so a note that has one is drawn as before.
+    if (definitions.size === 0 || nested)
+        return null;
+    const order = [];
+    const uses = new Map();
+    const labels = [];
+    const planned = runs.map((run, index) => {
+        const others = [...definitions.values()].filter((definition) => definition.run !== index);
+        const text = others.length === 0 ? run : `${run}\n\n${others.map((definition) => definition.source).join('\n\n')}\n`;
+        const refs = [];
+        const walk = (node) => {
+            // A reference inside a definition is drawn in the section, after every
+            // reference of the body, which is where the section pass meets it.
+            if (node.type === 'footnoteDefinition')
+                return;
+            if (node.type === 'footnoteReference') {
+                const key = keyOf(node);
+                if (!order.includes(key))
+                    order.push(key);
+                const occurrence = (uses.get(key) ?? 0) + 1;
+                uses.set(key, occurrence);
+                labels.push(node.label ?? node.identifier ?? '');
+                refs.push({ number: order.indexOf(key) + 1, occurrence });
+            }
+            for (const child of node.children ?? [])
+                walk(child);
+        };
+        walk(read(text));
+        return { text, refs };
+    });
+    if (order.length === 0)
+        return null;
+    const section = `${labels.map((label) => `[^${label}]`).join(' ')}\n\n${[...definitions.values()]
+        .map((definition) => definition.source)
+        .join('\n\n')}\n`;
+    return { runs: planned, section };
+}
+function isElement(node, tagName) {
+    return node.type === 'element' && node.tagName === tagName;
+}
+const isSection = (node) => isElement(node, 'section') && node.properties?.dataFootnotes !== undefined;
+/**
+ * The rehype side of a run: its own section dropped, and each reference given
+ * the number and the id the note gives it.
+ */
+export function rehypeFootnoteRun(options) {
+    return (tree) => {
+        tree.children = (tree.children ?? []).filter((child) => !isSection(child));
+        let index = 0;
+        const walk = (node) => {
+            if (isElement(node, 'a') && node.properties?.dataFootnoteRef !== undefined) {
+                const ref = options.refs[index++];
+                const href = String(node.properties.href ?? '');
+                if (ref && href.startsWith(`#${CLOBBER_PREFIX}fn-`)) {
+                    const safe = href.slice(`#${CLOBBER_PREFIX}fn-`.length);
+                    node.properties.id = `${CLOBBER_PREFIX}fnref-${safe}${ref.occurrence > 1 ? `-${ref.occurrence}` : ''}`;
+                    node.children = [{ type: 'text', value: String(ref.number) }];
+                }
+                return;
+            }
+            for (const child of node.children ?? [])
+                walk(child);
+        };
+        walk(tree);
+    };
+}
+/** The rehype side of the section pass: the section and nothing else. */
+export function rehypeFootnoteSection() {
+    return (tree) => {
+        tree.children = (tree.children ?? []).filter(isSection);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A React component that draws a MemorySmith note exactly as MemorySmith's reading page does.",
   "keywords": [
     "markdown",
@@ -54,10 +54,12 @@
     "refractor": "5.0.0",
     "rehype-katex": "7.0.1",
     "remark-gfm": "4.0.1",
-    "remark-math": "6.0.0"
+    "remark-math": "6.0.0",
+    "remark-parse": "11.0.0",
+    "unified": "11.0.5"
   },
   "devDependencies": {
-    "@memorysmithapp/markdown-spec": "0.1.0",
+    "@memorysmithapp/markdown-spec": "0.1.1",
     "@types/hast": "3.0.5",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",