@memorysmithapp/markdown-renderer 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,8 +1,10 @@
 // The entry point of @memorysmithapp/markdown-renderer.
 export { NoteBody } from './NoteBody.js';
 export { ENGLISH } from './strings.js';
+export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, } from './theme.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 { readProperties } from './properties.js';
 export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/markdown.d.ts

@@ -20,15 +20,16 @@ export interface SplitDocument {
  */
 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
+ * Where the body of a note starts: after its frontmatter, which the theme draws apart from the
+ * body (`readProperties`). 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.
+ * properties, its lists joined by commas. The renderer draws the frontmatter from
+ * `readProperties`, which keeps each item and each shape apart; this stays for a host that reads
+ * the values MemorySmith does.
  */
 export declare function splitFrontmatter(input: string): SplitDocument;
 /** The half-open ranges of `body` that are fenced blocks. */

package/dist/markdown.js

@@ -12,8 +12,8 @@ export function toUnixNewlines(raw) {
     return raw.replace(/\r\n?/g, '\n');
 }
 /**
- * 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
+ * Where the body of a note starts: after its frontmatter, which the theme draws apart from the
+ * body (`readProperties`). 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 function bodyStart(text) {
@@ -32,8 +32,9 @@ function unquote(value) {
 }
 /**
  * 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.
+ * properties, its lists joined by commas. The renderer draws the frontmatter from
+ * `readProperties`, which keeps each item and each shape apart; this stays for a host that reads
+ * the values MemorySmith does.
  */
 export function splitFrontmatter(input) {
     const raw = toUnixNewlines(input);

package/dist/properties.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The frontmatter of a note, read for drawing (§6).
+ *
+ * The frontmatter is content: what the author wrote about the note. The
+ * renderer reads it the way the specification reads it and hands it to the
+ * theme, which decides how — and whether — it is drawn. The default theme
+ * draws `name` as the note's title and every other entry as a property, by
+ * the shape of its value.
+ *
+ * It reads the subset of YAML §6.2 names — scalars, inline lists and dash
+ * lists, with one layer of matching quotes stripped — and nothing else; a line
+ * it does not read is left out, never guessed at. A value written as a
+ * wikilink, `"[[Note]]"`, is kept as written: the theme draws it as a link,
+ * resolved by the host as a link of the body is. That is a decision of the
+ * reading surface; it adds no edge, and what an Indexer reads is unchanged.
+ */
+/** The shape of a value, which decides how it is drawn (§6.3). */
+export type PropertyShape = 'list' | 'date' | 'boolean' | 'text' | 'prose' | 'empty';
+/** One entry of the frontmatter, other than `name`. */
+export interface PropertyEntry {
+    /** The key as the author wrote it, in their language. */
+    readonly key: string;
+    readonly shape: PropertyShape;
+    /**
+     * The value as written, one layer of quotes stripped: one item, or each item of a list. A
+     * theme reads a boolean or a date from it, and shows what was typed where it shows the bytes.
+     */
+    readonly values: readonly string[];
+}
+/** The frontmatter, read. */
+export interface NoteProperties {
+    /** The name of the note: `name:` when it is a single text value (§6.5), else `null`. */
+    readonly name: string | null;
+    /** Every other entry, in the order written. */
+    readonly entries: readonly PropertyEntry[];
+}
+/**
+ * The frontmatter of a note, or no name and no entries when it has none. The block begins on the
+ * first line with `---` and ends at the next line that is `---` (§6.1).
+ */
+export declare function readProperties(markdown: string): NoteProperties;
+/**
+ * What a value may carry that is a link: a wikilink, a Markdown link to the web, or a bare web
+ * address — as MemorySmith's properties read it, and nothing else of Markdown.
+ */
+export declare const VALUE_LINK: RegExp;
+/** Whether a boolean value reads true: `true` or `yes`, in any case. */
+export declare function isTrue(value: string): boolean;
+/** The reserved keys a theme draws as properties (§6.4): `name` is the title, not a property. */
+export declare const DRAWN_RESERVED_KEYS: readonly string[];

package/dist/properties.js

@@ -0,0 +1,144 @@
+/**
+ * The frontmatter of a note, read for drawing (§6).
+ *
+ * The frontmatter is content: what the author wrote about the note. The
+ * renderer reads it the way the specification reads it and hands it to the
+ * theme, which decides how — and whether — it is drawn. The default theme
+ * draws `name` as the note's title and every other entry as a property, by
+ * the shape of its value.
+ *
+ * It reads the subset of YAML §6.2 names — scalars, inline lists and dash
+ * lists, with one layer of matching quotes stripped — and nothing else; a line
+ * it does not read is left out, never guessed at. A value written as a
+ * wikilink, `"[[Note]]"`, is kept as written: the theme draws it as a link,
+ * resolved by the host as a link of the body is. That is a decision of the
+ * reading surface; it adds no edge, and what an Indexer reads is unchanged.
+ */
+/** Above this a single value is prose rather than a category (§6.3). */
+const CATEGORY_CEILING = 40;
+const KEY = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/;
+const DASH = /^\s+-\s+(.*)$/;
+const DATE = /^(\d{4})-(\d{2})-(\d{2})/;
+const BOOLEAN = /^(true|false|yes|no)$/i;
+/** A value that is one wikilink and nothing else, which YAML would otherwise read as a nested list. */
+const WIKILINK_VALUE = /^\[\[[^\]]+\]\]$/;
+function unquote(value) {
+    const trimmed = value.trim();
+    const quoted = /^(["'])([\s\S]*)\1$/.exec(trimmed);
+    return (quoted ? (quoted[2] ?? '') : trimmed).trim();
+}
+/** The items of an inline list, split on the commas outside quotes and outside a wikilink. */
+function inlineItems(inside) {
+    const items = [];
+    let current = '';
+    let quote = null;
+    let depth = 0;
+    for (let i = 0; i < inside.length; i++) {
+        const character = inside[i];
+        if (quote) {
+            if (character === quote)
+                quote = null;
+        }
+        else if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (inside.startsWith('[[', i)) {
+            depth += 1;
+            current += '[[';
+            i += 1;
+            continue;
+        }
+        else if (inside.startsWith(']]', i) && depth > 0) {
+            depth -= 1;
+            current += ']]';
+            i += 1;
+            continue;
+        }
+        else if (character === ',' && depth === 0) {
+            items.push(current);
+            current = '';
+            continue;
+        }
+        current += character;
+    }
+    items.push(current);
+    return items.map(unquote).filter((item) => item.length > 0);
+}
+function isDate(value) {
+    const match = DATE.exec(value);
+    if (!match)
+        return false;
+    const [, year, month, day] = match.map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+function scalarEntry(key, raw) {
+    const value = unquote(raw);
+    if (value.length === 0)
+        return { key, shape: 'empty', values: [] };
+    if (isDate(value))
+        return { key, shape: 'date', values: [value] };
+    if (BOOLEAN.test(value))
+        return { key, shape: 'boolean', values: [value] };
+    return { key, shape: value.length > CATEGORY_CEILING ? 'prose' : 'text', values: [value] };
+}
+/**
+ * The frontmatter of a note, or no name and no entries when it has none. The block begins on the
+ * first line with `---` and ends at the next line that is `---` (§6.1).
+ */
+export function readProperties(markdown) {
+    const text = markdown.replace(/\r\n?/g, '\n');
+    const none = { name: null, entries: [] };
+    if (!text.startsWith('---\n'))
+        return none;
+    const end = text.indexOf('\n---', 3);
+    if (end === -1)
+        return none;
+    const lines = text.slice(4, end).split('\n');
+    const entries = [];
+    for (const line of lines) {
+        const pair = KEY.exec(line);
+        if (pair) {
+            const raw = (pair[2] ?? '').trim();
+            const inline = raw.startsWith('[') && raw.endsWith(']') && !WIKILINK_VALUE.test(raw);
+            entries.push({ key: pair[1], raw, items: inline ? inlineItems(raw.slice(1, -1)) : null });
+            continue;
+        }
+        const dash = DASH.exec(line);
+        const last = entries[entries.length - 1];
+        // A dash list belongs to the key above it, which was written with no value.
+        if (dash && last && (last.items !== null || last.raw === '')) {
+            const item = unquote(dash[1] ?? '');
+            if (item.length > 0)
+                last.items = [...(last.items ?? []), item];
+        }
+    }
+    let name = null;
+    const read = [];
+    for (const { key, raw, items } of entries) {
+        if (key === 'name') {
+            // Only a single text value names a note; any other shape leaves it unnamed (§6.5).
+            const value = items === null ? unquote(raw) : '';
+            name = value.length > 0 ? value : null;
+            continue;
+        }
+        // A list written with no item, `[]`, is an empty value, never a list (§6.3).
+        read.push(items === null
+            ? scalarEntry(key, raw)
+            : items.length === 0
+                ? { key, shape: 'empty', values: [] }
+                : { key, shape: 'list', values: items });
+    }
+    return { name, entries: read };
+}
+/**
+ * What a value may carry that is a link: a wikilink, a Markdown link to the web, or a bare web
+ * address — as MemorySmith's properties read it, and nothing else of Markdown.
+ */
+export const VALUE_LINK = /\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]|\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)|(https?:\/\/[^\s,]+)/g;
+/** Whether a boolean value reads true: `true` or `yes`, in any case. */
+export function isTrue(value) {
+    return /^(true|yes)$/i.test(value.trim());
+}
+/** The reserved keys a theme draws as properties (§6.4): `name` is the title, not a property. */
+export const DRAWN_RESERVED_KEYS = ['aliases', 'tags'];

package/dist/remark-callouts.js

@@ -19,7 +19,7 @@
  * can tell the difference.
  */
 /** `[!type]`, an optional fold marker, and whatever titles it. */
-const MARKER = /^\[!([A-Za-z][\w-]*)\][+-]?[ \t]*(.*)$/;
+const MARKER = /^\[!([A-Za-z][\w-]*)\]([+-]?)[ \t]*(.*)$/;
 export function remarkCallouts(options = {}) {
     return (tree) => descend(tree, options);
 }
@@ -42,10 +42,12 @@ function rewrite(quote, options) {
     if (!marker)
         return;
     const kind = (marker[1] ?? '').toLowerCase();
-    const { title, body } = split(marker[2] ?? '', broke === -1 ? null : lead.value.slice(broke + 1), inline);
+    const { title, body } = split(marker[3] ?? '', broke === -1 ? null : lead.value.slice(broke + 1), inline);
     quote.data = {
         hName: 'div',
-        hProperties: { className: ['callout'], 'data-callout': kind },
+        // The fold marker travels too, for a theme that folds; the default theme
+        // draws a callout open whatever it says, as MemorySmith's page does.
+        hProperties: { className: ['callout'], 'data-callout': kind, ...(marker[2] ? { 'data-fold': marker[2] } : {}) },
     };
     quote.children = [
         {

package/dist/slots.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The slots of a theme, where the reading surface hands a drawn notation over.
+ *
+ * Each component here draws exactly what the default theme draws when the
+ * theme leaves its slot empty, so a note with no theme is the same DOM it was
+ * before slots existed, and calls the slot with the notation already
+ * interpreted when the theme fills it. Nothing a slot is given lets it reach
+ * the source: what it draws is decided before it is called.
+ */
+import { type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import type { ThemeComponents } from './theme.js';
+/** The slot a theme fills, or `undefined`. */
+export declare function useSlot<K extends keyof ThemeComponents>(name: K): ThemeComponents[K] | undefined;
+/** Draws a slot as a component, so a slot may use hooks. */
+export declare function drawSlot<P extends object>(slot: (props: P) => ReactNode, props: P): ReactNode;
+type WithNode<T> = T & {
+    node?: unknown;
+};
+/** Whether a code element sits in a fenced block, which is what tells a block from a span. */
+export declare const InBlock: import("react").Context<boolean>;
+/** A `div` of the tree: a callout or its title, which `remarkCallouts` marks, or any other. */
+export declare function MarkdownDiv({ className, children, node: _node, ...rest }: WithNode<HTMLAttributes<HTMLDivElement>>): import("react").JSX.Element;
+export declare function MarkdownTable({ children, node, ...rest }: WithNode<HTMLAttributes<HTMLTableElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export declare const headings: {
+    h1: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+    h2: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+    h3: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+    h4: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+    h5: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+    h6: (props: HTMLAttributes<HTMLHeadingElement>) => import("react").JSX.Element;
+};
+export declare function MarkdownBlockquote({ children, node: _node, ...rest }: WithNode<HTMLAttributes<HTMLQuoteElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+export declare function MarkdownSection({ children, node: _node, ...rest }: WithNode<HTMLAttributes<HTMLElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+/** Whether a code element is being drawn inside a fenced block. */
+export declare function useInBlock(): boolean;
+export {};

package/dist/slots.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The slots of a theme, where the reading surface hands a drawn notation over.
+ *
+ * Each component here draws exactly what the default theme draws when the
+ * theme leaves its slot empty, so a note with no theme is the same DOM it was
+ * before slots existed, and calls the slot with the notation already
+ * interpreted when the theme fills it. Nothing a slot is given lets it reach
+ * the source: what it draws is decided before it is called.
+ */
+import { Children, createContext, createElement, Fragment, isValidElement, useContext, } from 'react';
+import { useHost } from './host.js';
+/** The slot a theme fills, or `undefined`. */
+export function useSlot(name) {
+    return useHost().theme.components?.[name];
+}
+/** Draws a slot as a component, so a slot may use hooks. */
+export function drawSlot(slot, props) {
+    return createElement(slot, props);
+}
+/** Whether a code element sits in a fenced block, which is what tells a block from a span. */
+export const InBlock = createContext(false);
+// ── Callouts ─────────────────────────────────────────────────────────────────
+/** The title `remarkCallouts` built, carried to the callout that holds it. */
+function CalloutTitle({ children }) {
+    return _jsx("div", { className: "callout-title", children: children });
+}
+function Callout({ kind, fold, children }) {
+    const { theme } = useHost();
+    const slot = useSlot('callout');
+    const iconSlot = useSlot('calloutIcon');
+    const icon = theme.icons && Object.hasOwn(theme.icons, kind)
+        ? theme.icons[kind]
+        : iconSlot
+            ? drawSlot(iconSlot, { kind })
+            : null;
+    const parts = Children.toArray(children);
+    // The title arrives as the `div` react-markdown draws through `MarkdownDiv`.
+    const at = parts.findIndex((part) => isValidElement(part) &&
+        part.type === MarkdownDiv &&
+        (part.props.className?.split(/\s+/) ?? []).includes('callout-title'));
+    const title = at === -1 ? null : parts[at].props.children;
+    const titled = icon === null ? (_jsx(CalloutTitle, { children: title })) : (
+    // An icon of the theme's takes the place of the one the stylesheet draws.
+    _jsxs("div", { className: "callout-title has-icon", children: [_jsx("span", { className: "callout-icon", "aria-hidden": "true", children: icon }), title] }));
+    if (slot) {
+        const body = parts.filter((_, index) => index !== at);
+        return drawSlot(slot, { kind, fold, title, icon, children: body });
+    }
+    return (_jsx("div", { className: "callout", "data-callout": kind, ...(fold ? { 'data-fold': fold } : {}), children: parts.map((part, index) => (index === at ? _jsx(Fragment, { children: titled }, "title") : part)) }));
+}
+/** A `div` of the tree: a callout or its title, which `remarkCallouts` marks, or any other. */
+export function MarkdownDiv({ className, children, node: _node, ...rest }) {
+    const classes = className?.split(/\s+/) ?? [];
+    const data = rest;
+    if (classes.includes('callout-title'))
+        return _jsx(CalloutTitle, { children: children });
+    if (classes.includes('callout')) {
+        const fold = data['data-fold'];
+        return (_jsx(Callout, { kind: String(data['data-callout'] ?? ''), fold: fold === '+' || fold === '-' ? fold : null, children: children }));
+    }
+    return (_jsx("div", { className: className, ...rest, children: children }));
+}
+/** The alignment of each column, read from the first row's cells. */
+function alignOf(node) {
+    const rows = [];
+    const walk = (element) => {
+        if (element.tagName === 'tr')
+            rows.push(element);
+        else
+            for (const child of element.children ?? [])
+                walk(child);
+    };
+    if (node)
+        walk(node);
+    const first = rows[0];
+    return (first?.children ?? [])
+        .filter((cell) => cell.tagName === 'th' || cell.tagName === 'td')
+        .map((cell) => {
+        const align = cell.properties?.['align'];
+        return align === 'left' || align === 'center' || align === 'right' ? align : null;
+    });
+}
+export function MarkdownTable({ children, node, ...rest }) {
+    const slot = useSlot('table');
+    if (slot)
+        return drawSlot(slot, { align: alignOf(node), children });
+    return _jsx("table", { ...rest, children: children });
+}
+function Heading({ level, className, children, node: _node, ...rest }) {
+    const slot = useSlot('heading');
+    // The heading of the footnotes is the footnotes slot's, not a heading of the note.
+    if (slot && !className?.split(/\s+/).includes('footnotes-label'))
+        return drawSlot(slot, { level, children });
+    return createElement(`h${level}`, { className, ...rest }, children);
+}
+export const headings = {
+    h1: (props) => _jsx(Heading, { level: 1, ...props }),
+    h2: (props) => _jsx(Heading, { level: 2, ...props }),
+    h3: (props) => _jsx(Heading, { level: 3, ...props }),
+    h4: (props) => _jsx(Heading, { level: 4, ...props }),
+    h5: (props) => _jsx(Heading, { level: 5, ...props }),
+    h6: (props) => _jsx(Heading, { level: 6, ...props }),
+};
+export function MarkdownBlockquote({ children, node: _node, ...rest }) {
+    const slot = useSlot('blockquote');
+    if (slot)
+        return drawSlot(slot, { children });
+    return _jsx("blockquote", { ...rest, children: children });
+}
+export function MarkdownSection({ children, node: _node, ...rest }) {
+    const slot = useSlot('footnotes');
+    const { strings } = useHost();
+    const footnotes = rest['data-footnotes'] !== undefined;
+    if (slot && footnotes) {
+        const notes = Children.toArray(children).filter((child) => !(isValidElement(child) && child.props.id === 'footnote-label'));
+        return drawSlot(slot, { label: strings.footnotes, children: notes });
+    }
+    return _jsx("section", { ...rest, children: children });
+}
+/** Whether a code element is being drawn inside a fenced block. */
+export function useInBlock() {
+    return useContext(InBlock);
+}

package/dist/strings.d.ts

@@ -8,6 +8,13 @@
 export interface NoteStrings {
     /** The title of an untitled callout, by kind (`note`, `warning`, …). */
     readonly callouts: Readonly<Record<string, string>>;
+    /** The heading of the properties a note's frontmatter declares. */
+    readonly properties: string;
+    /** The locale a date of a property is written in, as `Intl` takes it: `en-US`, `pt-BR`. */
+    readonly locale: string;
+    /** How a boolean property reads, true and false. */
+    readonly yes: string;
+    readonly no: string;
     /** The heading of the footnotes gathered at the end of a note. */
     readonly footnotes: string;
     /** The label of the way back from a footnote to its reference, counted from 1. */

package/dist/strings.js

@@ -31,6 +31,10 @@ const CALLOUTS = {
 /** The words MemorySmith shows in English, used for every word a host does not give. */
 export const ENGLISH = {
     callouts: CALLOUTS,
+    properties: 'Properties',
+    locale: 'en-US',
+    yes: 'Yes',
+    no: 'No',
     footnotes: 'Notes',
     footnoteBack: (number) => `Back to reference ${number}`,
     pendingLink: 'Pending link: the target note does not exist yet.',