@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.0

package/dist/host.d.ts

@@ -0,0 +1,135 @@
+import { type ReactNode } from 'react';
+import { type NoteStrings } from './strings.js';
+/**
+ * The host contract: everything the renderer needs from the notebook a note lives in, given by
+ * whoever draws it.
+ *
+ * The package knows no API, no router, no i18n library and no query cache. What MemorySmith reads
+ * from those reaches the component as these props: functions that answer about the notebook, and
+ * the words the page shows. The host decides; the package draws.
+ *
+ * **Every default is the safe one.** With no `resolve`, every link is pending; with no `keeps`, no
+ * embed reaches a file; with no `renderLink`, an internal address is a plain anchor; with no
+ * `strings`, the words are MemorySmith's English.
+ */
+export interface NoteHost {
+    /**
+     * The address of the one note a link target names, compared after NFC, or `null` when no single
+     * note answers it. The target is a name, literal: never slugified, never stripped of an extension.
+     */
+    readonly resolve?: (name: string) => string | null;
+    /**
+     * How many notes a target reaches, by name or, when no name matches, by alias (§5.2). One is a
+     * link; more than one is a choice; none is pending. Defaults to one when `resolve` answers and
+     * none otherwise.
+     */
+    readonly reaches?: (name: string) => number;
+    /**
+     * The notes a target no single note answers may lead to, asked when its link is clicked. With it,
+     * such a link opens the choice in place — or goes straight to the note, when one answers by
+     * alias. Without it, the link is pending and asks nothing.
+     */
+    readonly choose?: (name: string) => Promise<LinkChoices>;
+    /** The address of the host's page about a target, which a choice link carries for a new tab. */
+    readonly targetAddress?: (name: string) => string | null;
+    /** Goes to an internal address, through the host's router. Defaults to `location.assign`. */
+    readonly navigate?: (address: string) => void;
+    /**
+     * The note a target names, for an embed to draw in place: its body as the host keeps it, its name
+     * and its address. Asked only for a target exactly one note reaches; `null` draws the embed as
+     * pending. Without it, every embed of a note is pending. The package never fetches.
+     */
+    readonly loadNote?: (name: string) => Promise<EmbeddedNote | null>;
+    /**
+     * Whether the reader may tick the task boxes of this note. Defaults to `false`: every box shows
+     * its state and none answers a click.
+     */
+    readonly writable?: boolean;
+    /**
+     * A task box was ticked. The ordinal counts the boxes of the note as the host gave it, frontmatter
+     * included; the host applies it with `toggleTaskAt`, a one-character change of its bytes. The
+     * package never writes the note.
+     */
+    readonly onToggleTask?: (ordinal: number) => void;
+    /** Whether the notebook keeps a file under that name. Only an embed reaches a file. */
+    readonly keeps?: (name: string) => boolean;
+    /**
+     * Draws a file the notebook keeps where a note embeds it: an image, audio, video, or a card. The
+     * dimensions are the ones the embed declared, in CSS pixels, or `null`.
+     */
+    readonly renderAttachment?: (file: AttachmentRequest) => ReactNode;
+    /** Draws a link to an internal address, through the host's router. */
+    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';
+    /**
+     * 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
+     * elsewhere turns it off and reads the hosts with `remoteImageHosts`.
+     */
+    readonly remoteNotice?: boolean;
+}
+/** What a target that no single note answers may lead to. */
+export interface LinkChoices {
+    /** What matched: the names of notes, their aliases, or nothing. */
+    readonly by: 'name' | 'alias' | null;
+    readonly notes: readonly LinkChoiceNote[];
+}
+/** A note a choice offers. */
+export interface LinkChoiceNote {
+    /** Its name, or `null` for a note that has none. */
+    readonly name: string | null;
+    /** Its address, which the host follows. */
+    readonly address: string;
+    /** The folders from the root down to the one that holds it. */
+    readonly trail: readonly string[];
+    /** What the folder that holds it is for, in the notebook's words. */
+    readonly folderDescription: string;
+}
+/** A note an embed draws in place. */
+export interface EmbeddedNote {
+    /** The note as the host keeps it, frontmatter included. */
+    readonly markdown: string;
+    /** Its name, or `null` for a note that has none. */
+    readonly name: string | null;
+    /** Its address, which the caption under the embed links to, or `null`. */
+    readonly address: string | null;
+}
+/** A file to draw: its name, and the dimensions the embed declared. */
+export interface AttachmentRequest {
+    readonly name: string;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+/** A link to draw through the host's router. */
+export interface LinkRequest {
+    readonly href: string;
+    readonly className?: string;
+    readonly children: ReactNode;
+}
+/**
+ * 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.
+ */
+export declare const HOST_KEYS: (keyof NoteHost)[];
+/** The host contract with every default applied. */
+export interface ResolvedHost {
+    readonly resolve: (name: string) => string | null;
+    readonly reaches: (name: string) => number;
+    readonly choose: ((name: string) => Promise<LinkChoices>) | null;
+    readonly targetAddress: (name: string) => string | null;
+    readonly navigate: (address: string) => void;
+    readonly remoteNotice: boolean;
+    readonly loadNote: ((name: string) => Promise<EmbeddedNote | null>) | null;
+    readonly keeps: (name: string) => boolean;
+    readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;
+    readonly renderLink: (link: LinkRequest) => ReactNode;
+    readonly strings: NoteStrings;
+    readonly theme: 'light' | 'dark';
+}
+export declare function resolveHost(host: NoteHost): ResolvedHost;
+export declare const HostProvider: import("react").Provider<ResolvedHost>;
+/** The host the note is drawn under, read by every part of the surface. */
+export declare function useHost(): ResolvedHost;

package/dist/host.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { withDefaults } from './strings.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.
+ */
+export const HOST_KEYS = Object.keys({
+    resolve: 1,
+    reaches: 1,
+    choose: 1,
+    targetAddress: 1,
+    navigate: 1,
+    loadNote: 1,
+    writable: 1,
+    onToggleTask: 1,
+    keeps: 1,
+    renderAttachment: 1,
+    renderLink: 1,
+    strings: 1,
+    theme: 1,
+    remoteNotice: 1,
+});
+const nothing = () => null;
+const never = () => false;
+const plainLink = ({ href, className, children }) => (_jsx("a", { className: className, href: href, children: children }));
+export function resolveHost(host) {
+    const resolve = host.resolve ?? nothing;
+    return {
+        resolve,
+        reaches: host.reaches ?? ((name) => (resolve(name) === null ? 0 : 1)),
+        choose: host.choose ?? null,
+        targetAddress: host.targetAddress ?? nothing,
+        navigate: host.navigate ?? ((address) => window.location.assign(address)),
+        remoteNotice: host.remoteNotice ?? true,
+        loadNote: host.loadNote ?? null,
+        keeps: host.keeps ?? never,
+        renderAttachment: host.renderAttachment ?? null,
+        renderLink: host.renderLink ?? plainLink,
+        strings: withDefaults(host.strings),
+        theme: host.theme ?? 'light',
+    };
+}
+const HostContext = createContext(resolveHost({}));
+export const HostProvider = HostContext.Provider;
+/** The host the note is drawn under, read by every part of the surface. */
+export function useHost() {
+    return useContext(HostContext);
+}

package/dist/image-dimensions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The pipe inside the alt text of an image, which separates the description
+ * from the dimensions (`SPEC.md` §3.14).
+ *
+ * `![Engelbart|100x145](engelbart.jpg)` is 100 by 145 CSS pixels and
+ * `![Engelbart|100](…)` is 100 wide with the aspect ratio kept. What precedes
+ * the pipe is the **description** and is never dropped — it is what a person
+ * gets when the image does not load, and it is what a screen reader says.
+ *
+ * **A value that is neither form is not a dimension.** `![Engelbart|large](…)`
+ * keeps `Engelbart|large` as the whole description, because deleting what an
+ * author wrote into an accessibility label is the worse of the two failures.
+ * Until the specification declared this form, an imported note displayed the
+ * pipe and the digits on screen and mandated the whole string as the label.
+ */
+export interface ImageAlt {
+    /** What a reader hears, and sees when the image does not load. */
+    readonly description: string;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+/**
+ * What follows a pipe, when it is a dimension and not text.
+ *
+ * The wikilink embed of an attachment carries the same thing the alt text of a
+ * Markdown image does — `![[engelbart.jpg|100x145]]` and
+ * `![Engelbart|100x145](…)` mean one thing — so both read it here.
+ */
+export declare function readDimensions(value: string): {
+    width: number;
+    height: number | null;
+} | null;
+export declare function readImageAlt(alt: string): ImageAlt;

package/dist/image-dimensions.js

@@ -0,0 +1,42 @@
+/**
+ * The pipe inside the alt text of an image, which separates the description
+ * from the dimensions (`SPEC.md` §3.14).
+ *
+ * `![Engelbart|100x145](engelbart.jpg)` is 100 by 145 CSS pixels and
+ * `![Engelbart|100](…)` is 100 wide with the aspect ratio kept. What precedes
+ * the pipe is the **description** and is never dropped — it is what a person
+ * gets when the image does not load, and it is what a screen reader says.
+ *
+ * **A value that is neither form is not a dimension.** `![Engelbart|large](…)`
+ * keeps `Engelbart|large` as the whole description, because deleting what an
+ * author wrote into an accessibility label is the worse of the two failures.
+ * Until the specification declared this form, an imported note displayed the
+ * pipe and the digits on screen and mandated the whole string as the label.
+ */
+/** `100` or `100x145`, and nothing else. */
+const DIMENSIONS = /^(\d{1,5})(?:x(\d{1,5}))?$/;
+/**
+ * What follows a pipe, when it is a dimension and not text.
+ *
+ * The wikilink embed of an attachment carries the same thing the alt text of a
+ * Markdown image does — `![[engelbart.jpg|100x145]]` and
+ * `![Engelbart|100x145](…)` mean one thing — so both read it here.
+ */
+export function readDimensions(value) {
+    const measured = DIMENSIONS.exec(value.trim());
+    if (!measured)
+        return null;
+    return {
+        width: Number(measured[1]),
+        height: measured[2] === undefined ? null : Number(measured[2]),
+    };
+}
+export function readImageAlt(alt) {
+    const at = alt.lastIndexOf('|');
+    if (at === -1)
+        return { description: alt, width: null, height: null };
+    const measured = readDimensions(alt.slice(at + 1));
+    if (!measured)
+        return { description: alt, width: null, height: null };
+    return { description: alt.slice(0, at).trim(), width: measured.width, height: measured.height };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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 { 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 { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// The entry point of @memorysmithapp/markdown-renderer.
+export { NoteBody } from './NoteBody.js';
+export { ENGLISH } from './strings.js';
+export { followable } from './address.js';
+export { readDimensions, readImageAlt } from './image-dimensions.js';
+export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, } from './markdown.js';
+export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/markdown.d.ts

@@ -0,0 +1,68 @@
+export interface SplitDocument {
+    frontmatter: Record<string, string>;
+    /**
+     * Which of those keys the notebook wrote as a list, whether in a dash block or
+     * inline. The values are flattened to one comma-separated string so the
+     * table can print them, and that flattening is lossy: `tags: a, b` and a
+     * two-item list read the same afterwards. The set keeps the difference,
+     * because a list is drawn as chips and a sentence is not, and guessing from
+     * the commas would turn a prose value that happens to have one into chips.
+     */
+    lists: Set<string>;
+    body: string;
+}
+/**
+ * A note is bytes the notebook wrote, and a notebook written on Windows, or in a
+ * desktop editor, or pasted from anywhere, carries CRLF. Every reader in this
+ * module starts here, because a carriage return left at the end of a line is
+ * invisible in the source and fatal to a regex: `.` does not match one, so
+ * `(.*)$` fails on exactly the lines that have a value.
+ */
+export declare function toUnixNewlines(raw: string): string;
+/**
+ * Where the body of a note starts: after its frontmatter, which a host shows as properties and
+ * not as prose. The cut is the one MemorySmith's reading page makes, so the ordinals of the task
+ * boxes below it are counted over the whole note, as the host stores it.
+ */
+export declare function bodyStart(text: string): number;
+/**
+ * The frontmatter block, read the way MemorySmith's reading page reads it to show a note's
+ * properties. The package does not draw it — `NoteBody` starts after it — and exports this so a
+ * host that draws the properties reads the same values MemorySmith does.
+ */
+export declare function splitFrontmatter(input: string): SplitDocument;
+/** The half-open ranges of `body` that are fenced blocks. */
+export declare function fenceRegions(body: string): Array<[number, number]>;
+/** The half-open ranges of `body` that are code, fenced or inline, in order. */
+export declare function codeRegions(body: string): Array<[number, number]>;
+/** Whether an offset falls inside one of them. */
+export declare function insideCode(regions: Array<[number, number]>, at: number): boolean;
+export declare function tableRegions(body: string): Array<[number, number]>;
+/** Whether an offset falls inside one of them. */
+export declare function insideTable(regions: Array<[number, number]>, at: number): boolean;
+/** Runs a rewrite over everything except code, which is copied through. */
+export declare function outsideCode(body: string, rewrite: (text: string) => string): string;
+export declare function resolveWikilinks(body: string, resolve: (name: string) => string | null, 
+/**
+ * Whether the notebook keeps a FILE under that name. The extension of a
+ * name decides nothing, so what a target is cannot be read off it: it is
+ * read off what the notebook holds, which is the host's to answer.
+ */
+keeps?: (name: string) => boolean): string;
+/**
+ * The key a **heading** is matched by, which is how an anchor finds the
+ * section it names inside a note.
+ *
+ * **It is not the key of a note, and there is no longer one of those.** A link
+ * resolves against the name, literally and case-exact (§5.2), so the
+ * slug this file used to compute — the second implementation of a rule the
+ * kernel also implemented, and the one that drifted — is gone. What is
+ * left is this: an anchor and a heading are two spellings of the same phrase,
+ * written by the same person minutes apart, and folding case and punctuation
+ * between them is what makes `#Artigo 75` find `## Artigo 75`.
+ *
+ * Nothing outside this comparison reads it, and nothing else in the renderer
+ * computes a key from a name: the address of a note is the host's to give.
+ */
+export declare function headingKey(name: string): string;
+export declare function remoteImageHosts(body: string): string[];