@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.1

package/dist/transclusion.js

@@ -0,0 +1,161 @@
+/**
+ * Transclusion: `![[note]]` and `![[note#section]]`, expanded for reading.
+ *
+ * The expansion belongs to the reading surface. It is the same class of work
+ * the wikilink resolution already does here: interpreting the notation to
+ * display it. Nothing changes in what the host stores: the body of the
+ * embedded note comes from the host, and the package never fetches.
+ *
+ * ONE LEVEL, AND ONLY ONE. An embed found inside transcluded content is drawn
+ * as a link to its target, which is what keeps a pair of notes that embed each
+ * other from hanging the page.
+ *
+ * **Three places an embed cannot expand, and one answer for all of them.**
+ * Inside embedded content, past the ceiling this file sets, and — since
+ * specification v0.4.0 named it — inside a table cell, because a cell holds inlines
+ * and never blocks (§4.1). Wherever expansion cannot happen the embed becomes
+ * a link and is never dropped, which is what `demoteEmbeds` does.
+ */
+import { codeRegions, headingKey, insideCode, insideTable, outsideCode, tableRegions } from './markdown.js';
+/** Same shape the link extractor matches, plus the leading `!`. */
+const EMBED = /!\[\[([^\]|#]+?)(?:#([^\]|]+?))?(?:\|[^\]]*?)?\]\]/g;
+/**
+ * How many embeds one page expands. Past it the rest stay as links: the cost
+ * of a page has to stay predictable, and a note with forty embeds is a note
+ * that wanted a different structure.
+ */
+export const EMBED_LIMIT = 10;
+/**
+ * Splits a body into what to render inline and what to transclude. Embeds past
+ * the ceiling are demoted to plain wikilinks instead of being dropped, because
+ * losing the reference would be worse than not expanding it.
+ */
+export function splitEmbeds(body, 
+/**
+ * Whether the notebook keeps a FILE under that name. An embed of one
+ * expands nothing here: it stays in the text run, where the wikilink pass
+ * turns it into the attachment the page draws by its type.
+ */
+keeps = () => false, limit = EMBED_LIMIT) {
+    const segments = [];
+    const code = codeRegions(body);
+    const tables = tableRegions(body);
+    let cursor = 0;
+    let expanded = 0;
+    for (const match of body.matchAll(EMBED)) {
+        const at = match.index ?? 0;
+        const target = (match[1] ?? '').trim();
+        if (!target)
+            continue;
+        // A file is not a note, so there is nothing to transclude: it is left in
+        // the text run, where the wikilink pass turns it into the attachment the
+        // page draws by its type.
+        if (keeps(target))
+            continue;
+        // An embed written inside code is an example of the notation, not a use of
+        // it: expanding it would replace the very text somebody was showing.
+        if (insideCode(code, at))
+            continue;
+        // An embed inside a table cell is drawn as a link (§7.3): no block
+        // fits in a cell. Skipping it here leaves it in the surrounding text run,
+        // where `demoteEmbeds` turns it into the wikilink the specification asks for —
+        // and, just as importantly, keeps the run from being cut mid-row, which
+        // used to empty the cell and leave the closing pipe as a paragraph.
+        if (insideTable(tables, at))
+            continue;
+        if (expanded >= limit)
+            break;
+        // Demoted like the tail is, and for the embeds this loop SKIPPED: one in
+        // a table cell lands in a run before an expanded one, and without this it
+        // would reach the page as the literal `![[…]]` — dropped notation, which
+        // is the one thing §7.3 forbids in every place expansion cannot happen.
+        // Code is untouched, because `demoteEmbeds` rewrites outside it.
+        const before = demoteEmbeds(body.slice(cursor, at), keeps);
+        if (before.length > 0)
+            segments.push({ kind: 'text', text: before });
+        segments.push({ kind: 'embed', target, anchor: match[2]?.trim() ?? null });
+        cursor = at + match[0].length;
+        expanded += 1;
+    }
+    const rest = body.slice(cursor);
+    if (rest.length > 0)
+        segments.push({ kind: 'text', text: demoteEmbeds(rest, keeps) });
+    return segments;
+}
+/**
+ * `![[x]]` becomes `[[x]]`: a reference instead of an expansion.
+ *
+ * **An embed of a file keeps its `!`**. Demoting exists for an embed
+ * that cannot be expanded here — one inside a table cell, one inside embedded
+ * content — and an attachment is not one of those: the page draws it. Taking
+ * the bang off it was what made `[[picture]]` and `![[picture]]` arrive at the
+ * wikilink pass as the same three characters, so a **link** to a file drew the
+ * file. A link addresses a note (§5.2), and only the embed reaches a file.
+ */
+export function demoteEmbeds(body, keeps = () => false) {
+    return outsideCode(body, (text) => text.replace(EMBED, (all, target) => (keeps(target.trim()) ? all : all.slice(1))));
+}
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+/**
+ * The block a `^identifier` names, or null when nothing names it (§7.7).
+ *
+ * A block is what the parser would call one: a run of lines up to a blank
+ * line. The identifier sits at the END of it, and the marker is left in the
+ * text on purpose — `remarkBlockIds` takes it off the page, and cutting it
+ * here would mean this function decides what the reader shows.
+ *
+ * An identifier that names nothing answers null, and the caller renders it the
+ * way it renders a pending link. It is never an error: a notebook is read most
+ * while it is being written.
+ */
+export function blockOf(markdown, identifier) {
+    const marker = new RegExp(`[ \\t]\\^${escapeRegExp(identifier)}[ \\t]*$`);
+    const lines = markdown.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        if (!marker.test(lines[index] ?? ''))
+            continue;
+        // Walk back to the top of the block: the first line after a blank one.
+        let start = index;
+        while (start > 0 && (lines[start - 1] ?? '').trim().length > 0)
+            start--;
+        return lines
+            .slice(start, index + 1)
+            .join('\n')
+            .trimEnd();
+    }
+    return null;
+}
+/** An anchor written `^id` addresses a block; anything else, a section. */
+export function isBlockAnchor(anchor) {
+    return anchor.startsWith('^');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The section of a document, cut syntactically: from the heading whose slug
+ * matches the anchor to the next heading of equal or higher level. No notebook
+ * convention takes part in this: the cut is syntactic.
+ */
+export function sectionOf(markdown, anchor) {
+    const wanted = headingKey(anchor);
+    const lines = markdown.split('\n');
+    let start = -1;
+    let level = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const heading = HEADING.exec(lines[index] ?? '');
+        if (!heading)
+            continue;
+        if (start === -1) {
+            if (headingKey(heading[2] ?? '') === wanted) {
+                start = index;
+                level = (heading[1] ?? '').length;
+            }
+            continue;
+        }
+        if ((heading[1] ?? '').length <= level) {
+            return lines.slice(start, index).join('\n').trimEnd();
+        }
+    }
+    return start === -1 ? null : lines.slice(start).join('\n').trimEnd();
+}

package/dist/wikilink-address.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedHost } from './host.js';
+/**
+ * Where a wikilink goes: the note when exactly one answers it, and the choice
+ * otherwise — several notes, or none, which is pending and still asks — when
+ * the host can say which notes a target may lead to. With no such host, a
+ * target no single note answers is pending.
+ */
+export declare function wikilinkAddress(host: ResolvedHost, name: string): string | null;

package/dist/wikilink-address.js

@@ -0,0 +1,13 @@
+import { CHOICE_SCHEME } from './LinkChoice.js';
+/**
+ * Where a wikilink goes: the note when exactly one answers it, and the choice
+ * otherwise — several notes, or none, which is pending and still asks — when
+ * the host can say which notes a target may lead to. With no such host, a
+ * target no single note answers is pending.
+ */
+export function wikilinkAddress(host, name) {
+    const address = host.resolve(name);
+    if (address !== null)
+        return address;
+    return host.choose ? `${CHOICE_SCHEME}${encodeURIComponent(name)}` : null;
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "A React component that draws a MemorySmith note exactly as MemorySmith's reading page does.",
+  "keywords": [
+    "markdown",
+    "react",
+    "remark",
+    "renderer",
+    "wikilink",
+    "callout",
+    "katex",
+    "mermaid",
+    "memorysmith"
+  ],
+  "homepage": "https://github.com/memorysmithapp/memorysmithapp-markdown/tree/main/packages/markdown-renderer#readme",
+  "bugs": {
+    "url": "https://github.com/memorysmithapp/memorysmithapp-markdown/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memorysmithapp/memorysmithapp-markdown.git",
+    "directory": "packages/markdown-renderer"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "styles.css",
+    "LICENSE",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "peerDependencies": {
+    "katex": "^0.18.5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "hast-util-to-jsx-runtime": "2.3.6",
+    "mermaid": "11.17.0",
+    "react-markdown": "9.1.0",
+    "refractor": "5.0.0",
+    "rehype-katex": "7.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-math": "6.0.0",
+    "remark-parse": "11.0.0",
+    "unified": "11.0.5"
+  },
+  "devDependencies": {
+    "@memorysmithapp/markdown-spec": "0.1.1",
+    "@types/hast": "3.0.5",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "katex": "0.18.5",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "cd ../.. && vitest run --project markdown-renderer"
+  }
 }