@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 memorysmithapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @memorysmithapp/markdown-renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A React component that draws the body of a MemorySmith note exactly as MemorySmith's reading page does: callouts, wikilinks, embedded notes, task boxes, code with highlighting and diagrams, mathematics, footnotes — the notation of the [MemorySmith Markdown Specification](https://www.npmjs.com/package/@memorysmithapp/markdown-spec).
+
+The package knows no API, no router and no i18n library. Everything it needs from the notebook a note lives in reaches it as props, and it never rewrites the note: ticking a task box reports which box, and the host applies it.
+
+## Use
+
+```sh
+npm install @memorysmithapp/markdown-renderer react react-dom katex
+```
+
+```tsx
+import { NoteBody, toggleTaskAt } from '@memorysmithapp/markdown-renderer';
+import '@memorysmithapp/markdown-renderer/styles.css';
+import 'katex/dist/katex.min.css';
+
+<NoteBody
+  markdown={note}                                  // the note as you keep it, frontmatter included
+  resolve={(name) => addressOfTheOneNoteNamed(name)} // or null: the link is pending
+  keeps={(name) => notebookKeepsAFile(name)}       // only an embed reaches a file
+  renderAttachment={({ name, width, height }) => <img src={urlOf(name)} width={width ?? undefined} />}
+  renderLink={({ href, className, children }) => <RouterLink to={href} className={className}>{children}</RouterLink>}
+  loadNote={(name) => fetchTheBodyOf(name)}        // for an embedded note; the package never fetches
+  writable
+  onToggleTask={(ordinal) => save(toggleTaskAt(note, ordinal))}
+  theme="dark"
+  strings={{ footnotes: 'Notas' }}                 // every word left out is MemorySmith's English
+/>;
+```
+
+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.
+
+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).
+
+## Licence
+
+[MIT](LICENSE).

package/dist/CopyButton.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copying to the clipboard, in the one way that works everywhere a note is
+ * opened.
+ *
+ * The async clipboard API can stay pending forever in embedded or automated
+ * contexts, so the promise is raced against a short timeout and the legacy
+ * path takes over when it does not settle.
+ */
+export declare function copyText(text: string): Promise<void>;
+/**
+ * The verb beside a block of code, which carries it somewhere else. It says
+ * *Copied* with the check for two seconds and goes back.
+ *
+ * The word is dropped at phone width and the icon stays, so the label lives in
+ * `aria-label` and `title` too: whoever hears the page still hears *Copy*.
+ *
+ * The text is asked for at the moment of the click, because a block is copied
+ * from what is on the page and not from a string held since it was drawn.
+ */
+export declare function CopyButton({ text, label, done, className, }: {
+    text: () => string;
+    /** The verb, in the reader's language. */
+    label: string;
+    /** What it says once the text is copied. */
+    done: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/CopyButton.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Copying to the clipboard, in the one way that works everywhere a note is
+ * opened.
+ *
+ * The async clipboard API can stay pending forever in embedded or automated
+ * contexts, so the promise is raced against a short timeout and the legacy
+ * path takes over when it does not settle.
+ */
+export async function copyText(text) {
+    const viaApi = navigator.clipboard
+        ?.writeText(text)
+        .then(() => true)
+        .catch(() => false);
+    const done = await Promise.race([
+        viaApi ?? Promise.resolve(false),
+        new Promise((resolve) => setTimeout(() => resolve(false), 350)),
+    ]);
+    if (done)
+        return;
+    const scratch = document.createElement('textarea');
+    scratch.value = text;
+    scratch.style.position = 'fixed';
+    scratch.style.opacity = '0';
+    document.body.appendChild(scratch);
+    scratch.select();
+    document.execCommand('copy');
+    scratch.remove();
+}
+const ICON = {
+    width: 16,
+    height: 16,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round',
+    'aria-hidden': true,
+};
+function CopyIcon() {
+    return (_jsxs("svg", { ...ICON, children: [_jsx("rect", { x: "9", y: "9", width: "13", height: "13", rx: "2" }), _jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })] }));
+}
+function CheckIcon() {
+    return (_jsx("svg", { ...ICON, children: _jsx("path", { d: "M20 6 9 17l-5-5" }) }));
+}
+/**
+ * The verb beside a block of code, which carries it somewhere else. It says
+ * *Copied* with the check for two seconds and goes back.
+ *
+ * The word is dropped at phone width and the icon stays, so the label lives in
+ * `aria-label` and `title` too: whoever hears the page still hears *Copy*.
+ *
+ * The text is asked for at the moment of the click, because a block is copied
+ * from what is on the page and not from a string held since it was drawn.
+ */
+export function CopyButton({ text, label, done, className = '', }) {
+    const [copied, setCopied] = useState(false);
+    const timer = useRef(undefined);
+    useEffect(() => () => clearTimeout(timer.current), []);
+    async function copy() {
+        await copyText(text());
+        setCopied(true);
+        clearTimeout(timer.current);
+        timer.current = setTimeout(() => setCopied(false), 2000);
+    }
+    return (_jsxs("button", { type: "button", className: `button is-small copy-action ${className}`.trim(), onClick: () => void copy(), "aria-label": label, title: copied ? done : label, children: [copied ? _jsx(CheckIcon, {}) : _jsx(CopyIcon, {}), _jsx("span", { className: "copy-action-label", children: copied ? done : label })] }));
+}

package/dist/LinkChoice.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from 'react';
+/**
+ * The address a wikilink carries when no single note answers it and the host
+ * can say which notes might: `choice:` and the encoded name. It never leaves
+ * the page — the anchor of the surface turns it into a `LinkChoice` — and it
+ * exists so the decision is made once, where the wikilink is resolved.
+ */
+export declare const CHOICE_SCHEME = "choice:";
+/** The name a choice address carries, or `null`. */
+export declare function choiceTargetOf(href: string): string | null;
+export declare function shortened(description: string, limit?: number): string;
+/**
+ * A wikilink that no single note answers by name, and the choice it opens.
+ *
+ * Two cases reach here. A name several notes carry is a choice, told apart by
+ * the folder each note lives in. A name no note carries is drawn as pending and
+ * still asks, because an alias may answer it with one note, which opens, or
+ * with several, which is the choice. The host answers both, through `choose`.
+ *
+ * **The choice is a DIALOG over the page, and it has to be.** A menu
+ * positioned inside whatever held the link was clipped by the scroll box of a
+ * table, which every table of a note has. `showModal()` puts the dialog in the
+ * top layer, which no ancestor can clip, and brings the focus handling with it.
+ */
+export declare function LinkChoice({ target, children }: {
+    target: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/LinkChoice.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { useHost } from './host.js';
+/**
+ * The address a wikilink carries when no single note answers it and the host
+ * can say which notes might: `choice:` and the encoded name. It never leaves
+ * the page — the anchor of the surface turns it into a `LinkChoice` — and it
+ * exists so the decision is made once, where the wikilink is resolved.
+ */
+export const CHOICE_SCHEME = 'choice:';
+/** The name a choice address carries, or `null`. */
+export function choiceTargetOf(href) {
+    if (!href.startsWith(CHOICE_SCHEME))
+        return null;
+    try {
+        return decodeURIComponent(href.slice(CHOICE_SCHEME.length)).normalize('NFC');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How long a click may resolve before the dialog opens on placeholder rows.
+ * Under it the dialog opens once, with its content; over it the click would
+ * otherwise look ignored.
+ */
+const PATIENCE_MS = 150;
+/**
+ * How long a description may be on a row of a choice. It is a folder
+ * description, written to be read whole somewhere else; here it is a hint
+ * under a path, and three rows of prose would bury the paths they were
+ * supposed to tell apart. Cut on a word, never mid-word, and say that it was
+ * cut.
+ */
+const DESCRIPTION_LIMIT = 120;
+export function shortened(description, limit = DESCRIPTION_LIMIT) {
+    const text = description.trim().replace(/\s+/g, ' ');
+    if (text.length <= limit)
+        return text;
+    const cut = text.slice(0, limit);
+    const lastSpace = cut.lastIndexOf(' ');
+    return `${(lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+/**
+ * A wikilink that no single note answers by name, and the choice it opens.
+ *
+ * Two cases reach here. A name several notes carry is a choice, told apart by
+ * the folder each note lives in. A name no note carries is drawn as pending and
+ * still asks, because an alias may answer it with one note, which opens, or
+ * with several, which is the choice. The host answers both, through `choose`.
+ *
+ * **The choice is a DIALOG over the page, and it has to be.** A menu
+ * positioned inside whatever held the link was clipped by the scroll box of a
+ * table, which every table of a note has. `showModal()` puts the dialog in the
+ * top layer, which no ancestor can clip, and brings the focus handling with it.
+ */
+export function LinkChoice({ target, children }) {
+    const host = useHost();
+    const { strings } = host;
+    const [asked, setAsked] = useState(false);
+    const [answer, setAnswer] = useState({ state: 'loading' });
+    const [patient, setPatient] = useState(false);
+    const anchor = useRef(null);
+    const dialog = useRef(null);
+    useEffect(() => {
+        if (!asked || !host.choose)
+            return;
+        let alive = true;
+        setAnswer({ state: 'loading' });
+        host.choose(target).then((choices) => alive && setAnswer({ state: 'ready', choices }), () => alive && setAnswer({ state: 'error' }));
+        return () => {
+            alive = false;
+        };
+    }, [asked, host, target]);
+    const resolving = asked && answer.state === 'loading';
+    // No dialog that flashes: the click marks the link as loading, and the
+    // dialog opens either with its content or, past a moment, on placeholders.
+    useEffect(() => {
+        if (!resolving)
+            return;
+        const timer = setTimeout(() => setPatient(true), PATIENCE_MS);
+        return () => clearTimeout(timer);
+    }, [resolving]);
+    // One note answers, which only an alias can do here: the choice is a step
+    // nobody asked for, so the click goes straight to the note.
+    const notes = answer.state === 'ready' ? answer.choices.notes : [];
+    const only = notes.length === 1 ? notes[0] : undefined;
+    useEffect(() => {
+        if (asked && only) {
+            setAsked(false);
+            setPatient(false);
+            host.navigate(only.address);
+        }
+    }, [asked, only, host]);
+    const open = asked && !only && (patient || !resolving);
+    // The dialog is modal or it is nothing: `open` as an attribute renders it
+    // inline, inside the scroll box this exists to escape.
+    useEffect(() => {
+        const node = dialog.current;
+        if (!node || !open)
+            return;
+        if (!node.open)
+            node.showModal?.();
+    }, [open]);
+    // The first option takes the focus, and not the control that closes.
+    useEffect(() => {
+        if (!open || resolving)
+            return;
+        dialog.current?.querySelector('.link-choice-option')?.focus();
+    }, [open, resolving, answer]);
+    // Pending is what reaches no note, by its name or by a spelling one of them
+    // declares.
+    const pending = host.reaches(target) === 0;
+    const address = host.targetAddress(target);
+    const ask = (event) => {
+        // A modifier or a middle click keeps the ordinary behaviour of a link,
+        // when the host gave the link an address to keep it for.
+        if (address && (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0))
+            return;
+        event.preventDefault();
+        setAsked(true);
+    };
+    const close = () => {
+        dialog.current?.close?.();
+        setAsked(false);
+        setPatient(false);
+        anchor.current?.focus();
+    };
+    return (_jsxs("span", { className: "link-choice", children: [_jsx("a", { ref: anchor, href: address ?? '#', className: pending ? 'wikilink-pending' : 'wikilink', title: pending ? strings.pendingLink : undefined, "aria-haspopup": "dialog", "aria-expanded": open, "aria-busy": resolving && !open, onClick: ask, children: children }), open && (_jsx("dialog", { ref: dialog, className: "link-choice-dialog", "aria-label": strings.linkChoice(target), 
+                // Esc fires `cancel`, and a click on the backdrop lands on the
+                // dialog element itself, never on the card inside it.
+                onCancel: (event) => {
+                    event.preventDefault();
+                    close();
+                }, onClick: (event) => {
+                    if (event.target === dialog.current)
+                        close();
+                }, children: _jsxs("div", { className: "link-choice-card", children: [_jsxs("header", { className: "link-choice-header", children: [_jsx("h2", { children: pending ? strings.linkLeadsNowhere : strings.linkLeadsToSeveral }), _jsxs("button", { type: "button", className: "link-choice-close", onClick: close, children: [_jsx("span", { "aria-hidden": "true", children: "\u2715" }), _jsx("span", { className: "visually-hidden", children: strings.close })] })] }), _jsx(LinkChoiceContent, { target: target, answer: answer, onPick: (picked) => {
+                                close();
+                                host.navigate(picked);
+                            } }), _jsx("footer", { className: "link-choice-footer", children: _jsx("button", { type: "button", className: "link-choice-cancel", onClick: close, children: strings.cancel }) })] }) }))] }));
+}
+/** Three rows of nothing, so a click never looks ignored while it resolves. */
+function Placeholders() {
+    return (_jsx("ul", { className: "link-choice-options", "aria-hidden": "true", children: [0, 1].map((row) => (_jsx("li", { children: _jsx("span", { className: "link-choice-option is-placeholder" }) }, row))) }));
+}
+/**
+ * What a link to more than one note has to say.
+ *
+ * **What leads an option depends on what matched.** Matched by name, every
+ * option carries the same name, so repeating it is noise: the folder trail
+ * leads, and the name is said once, in the explanation. Matched by alias, the
+ * names differ, so each option leads with its name and carries the trail under
+ * it.
+ */
+function LinkChoiceContent({ target, answer, onPick, }) {
+    const { strings } = useHost();
+    if (answer.state === 'loading') {
+        return (_jsxs("div", { className: "link-choice-body", "aria-busy": "true", children: [_jsx("p", { className: "link-choice-explanation", children: strings.loading }), _jsx(Placeholders, {})] }));
+    }
+    if (answer.state === 'error') {
+        return (_jsx("div", { className: "link-choice-body", children: _jsx("p", { className: "link-choice-explanation", children: strings.failed }) }));
+    }
+    const { by, notes } = answer.choices;
+    if (notes.length === 0) {
+        return (_jsx("div", { className: "link-choice-body", children: _jsx("p", { className: "link-choice-explanation", children: strings.targetPending(target) }) }));
+    }
+    const byAlias = by === 'alias';
+    /**
+     * The path, written the way a path is written: an address of a place a note
+     * is IN, the root included, as `/`.
+     */
+    const trailOf = (note) => (note.trail.length === 0 ? '/' : `/${note.trail.join('/')}`);
+    const pick = (address) => (event) => {
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+            return;
+        event.preventDefault();
+        onPick(address);
+    };
+    return (_jsxs("div", { className: "link-choice-body", children: [_jsx("p", { className: "link-choice-explanation", children: byAlias ? strings.targetAliased(target, notes.length) : strings.targetNamed(target, notes.length) }), _jsx("ul", { className: "link-choice-options", children: notes.map((note) => (_jsx("li", { children: _jsxs("a", { className: "link-choice-option", href: note.address, onClick: pick(note.address), children: [_jsx("span", { className: "link-choice-lead", children: byAlias ? note.name || strings.unnamedNote : trailOf(note) }), byAlias && _jsx("span", { className: "link-choice-under", children: trailOf(note) }), note.folderDescription.trim().length > 0 && (_jsx("span", { className: "link-choice-about", children: shortened(note.folderDescription) }))] }) }, note.address))) })] }));
+}

package/dist/Markdown.d.ts

@@ -0,0 +1,35 @@
+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.
+ *
+ * It draws the text it is given and nothing else. What a note becomes before this — its
+ * frontmatter cut, its embeds split out, its wikilinks resolved — is `NoteBody`'s.
+ */
+export interface MarkdownProps {
+    readonly children: string;
+    /**
+     * The text the ordinal of a task box is counted over. It has to be the text
+     * the PARSER saw, because the offsets come from it — not the bytes a write
+     * sends back, which are the original ones. Keeping the two aligned is the
+     * caller's job, and `NoteBody` does it by refusing to enable the boxes when
+     * the two disagree on how many there are.
+     */
+    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';
+}
+/**
+ * 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;