@memorysmithapp/markdown-renderer 0.3.2 → 0.5.0

package/README.md

@@ -19,17 +19,17 @@ import 'katex/dist/katex.min.css';
   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} />}
+  fileOf={(name) => describe(name)}               // { mimeType, bytes, url, description }: drawn by its type, as MemorySmith does
   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))}
+  onToggleTask={(ordinal) => save(toggleTaskAt(latest(), ordinal))} // a promise locks the item under "Updating…" until it settles
   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`. The faces of the default theme are Inter and Space Grotesk, which the page loads.
+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. A file `fileOf` describes is drawn by its media type, never its name: an image, an audio or a video player, and anything else a card with its type, size, description, *Open* where a browser shows it and *Download*; give `renderAttachment` instead to draw files yourself. The stylesheet styles nothing outside `.markdown`. The faces of the default theme are Inter and Space Grotesk, which the page loads.
 
 ## Themes
 
@@ -64,7 +64,7 @@ const acme = defineTheme({
 
 - **Properties** name every value the stylesheet reads — colours, faces, sizes, spacing, headings, quotations, tables, callout hues and icons — and are written on the root as `--markdown-*`, so your CSS may set them too.
 - **Your CSS** is scoped by `.markdown-theme-<name>`, and reaches the note and nothing else.
-- **Slots** — `callout`, `calloutIcon`, `table`, `codeBlock`, `inlineCode`, `heading`, `blockquote`, `embed`, `footnotes`, `taskBox`, `wikilink`, `diagram`, `properties` — are called with the notation already read. A slot decides how a block looks, never what it means: the links it draws go where the host resolved them, a task box reports through the `toggle` it is given, and no raw HTML ever reaches it.
+- **Slots** — `callout`, `calloutIcon`, `table`, `codeBlock`, `inlineCode`, `heading`, `blockquote`, `embed`, `footnotes`, `taskBox`, `wikilink`, `diagram`, `properties`, `modeSwitch` — are called with the notation already read. A slot decides how a block looks, never what it means: the links it draws go where the host resolved them, a task box reports through the `toggle` it is given, and no raw HTML ever reaches it.
 
 The frontmatter is the note's too. The default theme draws it as MemorySmith does: `name` as the title, and the other entries in a block that folds, each key with the icon of its value's shape, lists as chips and dates in `strings.locale`, with a `[[wikilink]]`, a Markdown link or a web address in a value drawn as a link. A theme decides otherwise through the `properties` slot, which may draw nothing, as a host that shows properties elsewhere does:
 
@@ -74,6 +74,52 @@ const mine = defineTheme({ name: 'mine', components: { properties: () => null }
 
 Import `structure.css` instead of `styles.css` for a theme that draws everything itself. A theme names faces; your page loads them.
 
+## Edit
+
+A note the host makes `editable` carries a button at its top right that switches between reading and editing it on the same page. The author edits what they see: marks, headings, lists, tasks, links and the names of notes after `[[`, callouts, tables cell by cell, code, formulas and diagrams with their drawing live, the properties as a form, footnotes and comments. The note is the bytes you gave, and every change comes back whole through `onChange`, unchanged wherever the author did not touch it — the order and quoting of the frontmatter, a list's marker, a table's spacing, a comment, a line break. The package never saves. The toolbar grows out of the switch, which becomes its last control; its first tool undoes every change since editing began, and a right-click on the text opens a menu of the same tools where you are (Shift keeps the browser's); beside the switch, in both modes, Show Markdown opens the note's Markdown, as you have it or would receive it, in a dialog, and Copy Markdown copies it. Those two are reading, so a note that is not `editable` carries them too, without the switch; pass `actions={false}` to hide them, for a print, a preview or an embed.
+
+```tsx
+<NoteBody
+  markdown={note}
+  editable                                        // the switch, at the top right
+  onChange={(next) => save(next)}                 // after every change; return the save's promise
+  suggest={(typed) => namesOfNotesLike(typed)}    // what [[ offers
+  attach={(file, { name, description }, progress) => keepInNotebook(file, name, description, progress)} // the name it is kept under
+  files={() => filesOfTheNotebook()}              // what the attach dialog lists: { name, mimeType, bytes, url, description }
+  modeButton="icon"                               // or "label", the icon and its word
+/>
+```
+
+When `onChange` returns the promise of its save, the editor shows before the switch an icon for whether the last change is *Saving…*, *Saved* or *Not saved*, the last one's icon trying again when clicked, and going back to reading waits for the save, staying in edit when it failed. Return nothing and no status is shown. When there is something to tell the author, resolve the promise with a `SaveOutcome` (the save went through, and they have a choice to make) or reject it with a `SaveRefusal` (it did not, and why): each is a `title`, a `message` and the `actions` to choose from, in your words. The icon then opens a dialog with them; an action's promise is followed like a save, and the author can close the dialog and come back to it:
+
+```tsx
+onChange={async (next) => {
+  const saved = await save(next);
+  if (saved.conflict) throw { title: 'Somebody else wrote this note', message: 'Your edit was not saved.', actions: [
+    { label: 'Discard my edit and reload', run: () => reload() },
+    { label: 'Save anyway', run: () => save(next, { force: true }) },
+  ] } satisfies SaveRefusal;
+  if (saved.renamed) return { title: 'Note renamed', message: `${saved.links} links reached the old name.`, actions: [
+    { label: 'Keep the links broken', run: () => undefined },
+    { label: 'Keep the old name as an alias', run: () => addAlias() },
+  ] } satisfies SaveOutcome;
+}}
+```
+
+While `attach` keeps a file, call `progress({ message, fraction })` with each step in your words — *Sending part 12 of 40*, and `0.3` — and the paperclip shows it, a bar filling when you give the fraction. Reject with `{ message }` (an `AttachRefusal`, not an `Error`) to tell the author why the file was refused; the paperclip says it until they open it again. An `Error` keeps the paperclip's own *The file was not attached*.
+
+Pass the saved note back as `markdown` whenever you like: a text the editor already moved past is not applied over what the author typed since.
+
+`mode` and `onModeChange` let you control the mode yourself, and the words come from `strings` (`edit`, `view` and `editor`). The editor is CodeMirror, loaded the first time a note is edited, so a page that only draws never loads it. To edit without the switch, import it from its own entry point:
+
+```tsx
+import { NoteEditor } from '@memorysmithapp/markdown-renderer/edit';
+
+<NoteEditor markdown={note} onChange={setNote} {...host} />;
+```
+
+A note that mixes line breaks (CRLF and LF) opens read-only, because the editor could not give it back byte for byte.
+
 ## Diagnose
 
 Every note is valid, and nothing here refuses one. What `diagnose` tells a host is where the page will not show what was most likely typed, and what the note lacks that the specification reserves a place for: the notices of [`SPEC.md` §7.13](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/packages/markdown-spec/SPEC.md#713-notices). It imports no React and needs no DOM, so it runs in an editor, on a server, or in a tool that writes a note.

package/dist/Markdown.d.ts

@@ -1,5 +1,6 @@
 import { type AnchorHTMLAttributes, type ReactNode } from 'react';
 import { type FootnoteRef } from './footnotes.js';
+import type { TaskSave } from './task-saves.js';
 /**
  * One run of a note, parsed and drawn: the pipeline of MemorySmith's reading page.
  *
@@ -16,7 +17,10 @@ export interface MarkdownProps {
      * the two disagree on how many there are.
      */
     readonly source?: string;
-    readonly onToggleTask?: (ordinal: number) => void;
+    /** A box of this run was ticked: its ordinal in the run, and the state it is being set to. */
+    readonly onToggleTask?: (ordinal: number, checked: boolean) => void;
+    /** Where the save of a box of this run stands, by its ordinal in the run (`task-saves.ts`). */
+    readonly taskSave?: (ordinal: number) => TaskSave | null;
     readonly writable?: boolean;
     /**
      * How this run takes part in the footnotes of a note drawn in several runs
@@ -37,5 +41,5 @@ type WithNode<T> = T & {
     node?: unknown;
 };
 export declare function MarkdownAnchor({ href, children, node: _node, ...rest }: WithNode<AnchorHTMLAttributes<HTMLAnchorElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
-export declare function Markdown({ children, source, onToggleTask, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
+export declare function Markdown({ children, source, onToggleTask, taskSave, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
 export {};

package/dist/Markdown.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
-import { isValidElement, } from 'react';
+import { isValidElement, useEffect, useMemo, useReducer, useState, } from 'react';
 import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
 import ReactMarkdown from 'react-markdown';
 import rehypeKatex from 'rehype-katex';
 import { followable } from './address.js';
 import { CopyButton } from './CopyButton.js';
-import { highlightLanguage, highlightTree } from './highlight.js';
+import { fileAddress, fileKind, formatBytes, opensInBrowser, rendersAs } from './file-types.js';
+import { highlightLanguage, highlightTree, languageToLoad, loadGrammar } from './highlight.js';
 import { useHost } from './host.js';
 import { readDimensions, readImageAlt } from './image-dimensions.js';
 import { choiceTargetOf, LinkChoice } from './LinkChoice.js';
@@ -56,19 +57,107 @@ function InPageAnchor({ href, children, ...rest }) {
     return (_jsx("a", { href: href, onClick: follow, ...rest, children: children }));
 }
 /**
- * A file the notebook keeps, where a note embedded it. The host draws it by its
- * type — an image, audio, video, or a card — and a name the notebook keeps
- * nothing under is reported the way a pending link is: a notebook is read most
- * while it is being written (§5.8).
+ * A file the notebook keeps, where a note embedded it, drawn by its type — an
+ * image, audio, video, or a card — by the host's `renderAttachment`, else from
+ * what its `fileOf` says (#77). A name the notebook keeps nothing under is
+ * reported the way a pending link is: a notebook is read most while it is
+ * being written (§5.8).
  */
 function Attachment({ name, width, height }) {
     const host = useHost();
-    if (!host.keeps(name)) {
-        return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, children: name }));
-    }
-    if (!host.renderAttachment)
+    if (!host.keeps(name))
+        return _jsx(AttachmentMissing, { name: name });
+    if (host.renderAttachment)
+        return _jsx(_Fragment, { children: host.renderAttachment({ name, width, height }) });
+    if (!host.fileOf)
         return _jsx("span", { className: "attachment-loading", children: name });
-    return _jsx(_Fragment, { children: host.renderAttachment({ name, width, height }) });
+    return _jsx(KeptAttachment, { name: name, width: width, height: height });
+}
+function AttachmentMissing({ name }) {
+    const host = useHost();
+    return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, children: name }));
+}
+function isThenable(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+/**
+ * What the host's `fileOf` says of a name: the file, `null` for none, or `undefined` while a
+ * promise is on its way. An answer given at once is drawn at once, a server's render included.
+ */
+function useKeptFile(name) {
+    const { fileOf } = useHost();
+    const answer = useMemo(() => fileOf?.(name) ?? null, [fileOf, name]);
+    const [settled, setSettled] = useState(null);
+    useEffect(() => {
+        if (!isThenable(answer))
+            return;
+        let live = true;
+        answer.then((file) => live && setSettled({ answer, file }), () => live && setSettled({ answer, file: null }));
+        return () => {
+            live = false;
+        };
+    }, [answer]);
+    if (!isThenable(answer))
+        return answer;
+    return settled?.answer === answer ? settled.file : undefined;
+}
+/**
+ * Opens a file kept as `data:` in a new tab as the `blob:` of its bytes: a browser navigates no tab
+ * to a `data:` address, so the link alone would do nothing (#79). Any other address is the link's.
+ */
+function openInTab(event, url) {
+    if (!/^data:/i.test(url.trim()) || typeof URL.createObjectURL !== 'function')
+        return;
+    event.preventDefault();
+    const tab = window.open('', '_blank');
+    void fetch(url)
+        .then((response) => response.blob())
+        .then((blob) => {
+        const address = URL.createObjectURL(blob);
+        if (tab)
+            tab.location.href = address;
+        else
+            window.open(address, '_blank', 'noreferrer');
+        // The tab has the bytes once it loaded them; the address is let go after a while.
+        setTimeout(() => URL.revokeObjectURL(address), 60_000);
+    })
+        .catch(() => tab?.close());
+}
+/**
+ * A kept file drawn as MemorySmith's `Attachment` draws it (*observed* at `4b67c7e`): an image with
+ * the dimensions the embed declared, an audio or a video player, and everything else — the PDF
+ * included — a card with what it is, its size, and the ways out of the page: Open only for what a
+ * browser shows, Download always. A theme may draw it through the `attachment` slot.
+ */
+function KeptAttachment({ name, width, height }) {
+    const host = useHost();
+    const slot = useSlot('attachment');
+    const described = useKeptFile(name);
+    if (described === undefined)
+        return _jsx("span", { className: "attachment-loading", children: name });
+    const url = described ? fileAddress(described.url) : '';
+    if (!described || url === '')
+        return _jsx(AttachmentMissing, { name: name });
+    const file = { ...described, url, downloadUrl: fileAddress(described.downloadUrl ?? described.url) || url };
+    const shape = rendersAs(file.mimeType);
+    const kind = fileKind(file.mimeType, host.strings.fileKinds);
+    const size = formatBytes(file.bytes, host.strings.locale);
+    const opens = opensInBrowser(file.mimeType);
+    if (slot)
+        return _jsx(_Fragment, { children: drawSlot(slot, { name, file, shape, kind, size, opens, width, height }) });
+    // The attributes reserve the box before the bytes arrive; a height is a style too, since the
+    // surface gives an image `height: auto`, which two numbers overrule (§3.14).
+    const sized = {
+        ...(width === null ? {} : { width }),
+        ...(height === null ? {} : { height, style: { height: `${height}px` } }),
+    };
+    if (shape === 'image')
+        return _jsx("img", { className: "attachment-image", src: file.url, alt: file.description || name, ...sized });
+    if (shape === 'audio')
+        return _jsx("audio", { className: "attachment-player", controls: true, src: file.url });
+    if (shape === 'video')
+        return _jsx("video", { className: "attachment-player", controls: true, src: file.url, ...sized });
+    return (_jsxs("span", { className: "attachment-card", children: [_jsxs("span", { className: "attachment-card-body", children: [_jsx("span", { className: "attachment-card-name", children: name }), _jsxs("span", { className: "attachment-card-note", title: file.mimeType, children: [kind, " \u00B7 ", size] }), file.description && _jsx("span", { className: "attachment-card-note", children: file.description })] }), _jsxs("span", { className: "attachment-card-actions", children: [opens && (_jsx("a", { href: file.url, target: "_blank", rel: "noreferrer", onClick: (event) => openInTab(event, file.url), children: host.strings.attachmentOpen })), _jsx("a", { href: file.downloadUrl, download: name, children: host.strings.attachmentDownload })] })] }));
 }
 export function MarkdownAnchor({ href, children, node: _node, ...rest }) {
     const host = useHost();
@@ -141,6 +230,19 @@ function MarkdownCode({ className, children, node: _node, ...rest }) {
     const { scheme } = useHost();
     const inBlock = useInBlock();
     const inlineSlot = useSlot('inlineCode');
+    // A grammar not among the fifteen is fetched the first time a fence names it, and the block
+    // drawn again highlighted once it is there (#84); until then it is plain code.
+    const toLoad = inBlock ? languageToLoad(className) : null;
+    const [, arrived] = useReducer((count) => count + 1, 0);
+    useEffect(() => {
+        if (!toLoad)
+            return;
+        let live = true;
+        void loadGrammar(toLoad).then((loaded) => live && loaded && arrived());
+        return () => {
+            live = false;
+        };
+    }, [toLoad]);
     if (className?.includes('language-mermaid')) {
         return _jsx(MermaidDiagram, { code: String(children ?? '').trim(), scheme: scheme });
     }
@@ -219,8 +321,9 @@ function taskState(node) {
  * lets a click become a one-character change in the original text — made by
  * the host, never by the package.
  */
-function TaskItem({ node, children, className, source, toggleTask, writable, ...rest }) {
+function TaskItem({ node, children, className, source, toggleTask, taskSave, writable, ...rest }) {
     const boxSlot = useSlot('taskBox');
+    const { strings } = useHost();
     const element = node;
     const checked = taskState(element);
     if (checked === null) {
@@ -228,15 +331,21 @@ function TaskItem({ node, children, className, source, toggleTask, writable, ...
     }
     const offset = element?.position?.start?.offset;
     const ordinal = offset === undefined ? -1 : ordinalAt(source, offset);
-    const enabled = writable && toggleTask !== undefined && ordinal >= 0;
+    // While the host saves a tick the box shows the state being written and answers no click; once a
+    // save failed it is back to what its source holds, which is `checked`.
+    const save = ordinal >= 0 ? (taskSave?.(ordinal) ?? null) : null;
+    const pending = save?.kind === 'pending';
+    const failed = save?.kind === 'failed';
+    const shown = save?.kind === 'pending' ? save.checked : checked;
+    const enabled = writable && toggleTask !== undefined && ordinal >= 0 && !pending;
     const toggle = () => {
         if (enabled)
-            toggleTask(ordinal);
+            toggleTask(ordinal, !checked);
     };
     return (
     // Our class comes LAST, because the one react-markdown passes in is on
     // `className` and spreading it after would silently take the item back.
-    _jsxs("li", { ...rest, className: `${className ?? ''} task-item`.trim(), children: [boxSlot ? (drawSlot(boxSlot, { checked, enabled, toggle })) : (_jsx("input", { type: "checkbox", checked: checked, disabled: !enabled, onChange: toggle })), dropBox(children)] }));
+    _jsxs("li", { ...rest, className: `${className ?? ''} task-item`.trim(), "data-save": pending ? 'pending' : failed ? 'failed' : undefined, "aria-busy": pending || undefined, children: [boxSlot ? (drawSlot(boxSlot, { checked: shown, enabled, toggle, pending, failed })) : (_jsx("input", { type: "checkbox", checked: shown, disabled: !enabled, onChange: toggle })), dropBox(children), pending && (_jsx("span", { className: "task-lock", "aria-hidden": "true", children: _jsx("span", { className: "task-lock-label", children: strings.updating }) })), failed && (_jsx("span", { className: "task-notice", "aria-hidden": "true", children: strings.notSaved }))] }));
 }
 /**
  * The children of the item without the checkbox GFM put in front of them.
@@ -249,7 +358,7 @@ function dropBox(children) {
         return children;
     return children.filter((child) => !(isValidElement(child) && child.type === 'input'));
 }
-export function Markdown({ children, source, onToggleTask, writable = false, footnotes }) {
+export function Markdown({ children, source, onToggleTask, taskSave, writable = false, footnotes }) {
     const text = toUnixNewlines(children);
     const { strings } = useHost();
     const calloutTitle = (kind) => Object.hasOwn(strings.callouts, kind) ? strings.callouts[kind] : undefined;
@@ -293,6 +402,6 @@ export function Markdown({ children, source, onToggleTask, writable = false, foo
                 blockquote: MarkdownBlockquote,
                 section: MarkdownSection,
                 ...headings,
-                li: (props) => (_jsx(TaskItem, { ...props, source: source ?? text, toggleTask: onToggleTask, writable: writable })),
+                li: (props) => (_jsx(TaskItem, { ...props, source: source ?? text, toggleTask: onToggleTask, taskSave: taskSave, writable: writable })),
             }, children: text }) }));
 }

package/dist/NoteActions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What stands beside the switch between reading and editing, in both modes (#76): a button that
+ * shows the note's Markdown in a dialog (#63), and one that copies it. Apart from the editor, so a
+ * note that is only read offers them without loading it.
+ */
+/** Show Markdown and Copy Markdown; `text` answers the bytes when a button is used. */
+export declare function NoteActions({ text }: {
+    text: () => string;
+}): import("react").JSX.Element;

package/dist/NoteActions.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * What stands beside the switch between reading and editing, in both modes (#76): a button that
+ * shows the note's Markdown in a dialog (#63), and one that copies it. Apart from the editor, so a
+ * note that is only read offers them without loading it.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { useHost } from './host.js';
+import { ICON_CHECK, ICON_CLOSE, ICON_COPY, ICON_MARKDOWN } from './mode-icons.js';
+/** Puts the text on the clipboard; answers whether it got there. */
+function copyText(text) {
+    const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
+    if (!clipboard)
+        return Promise.resolve(false);
+    return clipboard.writeText(text).then(() => true, () => false);
+}
+/**
+ * The note's Markdown, read-only, exactly as the host has it or would receive it: a modal dialog,
+ * closed by Escape, its button or a click outside it, the focus then back on the button that
+ * opened it.
+ */
+function SourceDialog({ text, onClose, onClosed }) {
+    const host = useHost();
+    const words = host.strings.editor;
+    const dialog = useRef(null);
+    const [copied, setCopied] = useState(null);
+    const closed = useRef(onClosed);
+    closed.current = onClosed;
+    useEffect(() => {
+        const element = dialog.current;
+        if (!element)
+            return;
+        if (typeof element.showModal === 'function')
+            element.showModal();
+        else
+            element.setAttribute('open', '');
+        element.querySelector('.edit-source-close')?.focus();
+        return () => {
+            if (element.open && typeof element.close === 'function')
+                element.close();
+            // Only once the dialog is closed may the page behind it take the focus.
+            closed.current();
+        };
+    }, []);
+    return (_jsx("dialog", { ref: dialog, className: "edit-source", "aria-modal": "true", "aria-labelledby": "edit-source-title", onCancel: (event) => {
+            event.preventDefault();
+            onClose();
+        }, 
+        // The dialog has no padding of its own, so a click on it and not on its content is outside.
+        onClick: (event) => event.target === dialog.current && onClose(), children: _jsxs("div", { className: "edit-source-frame", children: [_jsxs("header", { className: "edit-source-header", children: [_jsx("h2", { id: "edit-source-title", className: "edit-source-title", children: words.sourceTitle }), _jsx("span", { className: "edit-source-copied", role: "status", children: copied === 'copied' ? words.copied : copied === 'failed' ? words.copyFailed : '' }), _jsx("button", { type: "button", className: "edit-control edit-control-labelled", onClick: () => void copyText(text).then((done) => setCopied(done ? 'copied' : 'failed')), children: words.copy }), _jsx("button", { type: "button", className: "edit-control edit-source-close", "aria-label": host.strings.close, title: host.strings.close, onClick: onClose, children: ICON_CLOSE })] }), _jsx("pre", { className: "edit-source-text", tabIndex: 0, children: text })] }) }));
+}
+/** How long Copy Markdown shows its check, in milliseconds. */
+const COPIED_MS = 1600;
+/** Show Markdown and Copy Markdown; `text` answers the bytes when a button is used. */
+export function NoteActions({ text }) {
+    const words = useHost().strings.editor;
+    const show = useRef(null);
+    const [source, setSource] = useState(null);
+    const [copied, setCopied] = useState(null);
+    useEffect(() => {
+        if (!copied)
+            return;
+        const timer = setTimeout(() => setCopied(null), COPIED_MS);
+        return () => clearTimeout(timer);
+    }, [copied]);
+    const copyLabel = copied === 'copied' ? words.copied : copied === 'failed' ? words.copyFailed : words.copyMarkdown;
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: show, type: "button", className: "note-action", title: words.showMarkdown, "aria-label": words.showMarkdown, "aria-haspopup": "dialog", onClick: () => setSource(text()), children: ICON_MARKDOWN }), _jsx("button", { type: "button", className: "note-action", "data-copied": copied ?? undefined, title: copyLabel, "aria-label": words.copyMarkdown, onClick: () => void copyText(text()).then((done) => setCopied(done ? 'copied' : 'failed')), children: copied === 'copied' ? ICON_CHECK : ICON_COPY }), _jsx("span", { className: "visually-hidden", role: "status", children: copied === 'copied' ? words.copied : copied === 'failed' ? words.copyFailed : '' }), source !== null && _jsx(SourceDialog, { text: source, onClose: () => setSource(null), onClosed: () => show.current?.focus() })] }));
+}

package/dist/NoteBody.d.ts

@@ -2,14 +2,44 @@ import { type NoteHost } from './host.js';
 export interface NoteBodyProps extends NoteHost {
     /**
      * The note as the host keeps it, frontmatter included. It is drawn from these bytes and never
-     * rewritten; the frontmatter is not drawn, because a host shows it as properties.
+     * rewritten; the frontmatter is drawn as the theme decides.
      */
     readonly markdown: string;
+    /**
+     * Whether the note offers the switch to edit it, at its top right (#51). Defaults to `false`:
+     * no switch, the note only read, with Show and Copy Markdown as `actions` says.
+     */
+    readonly editable?: boolean;
+    /** The mode, for a host that controls it; left out, the note keeps its own, starting from `defaultMode`. */
+    readonly mode?: NoteMode;
+    /** The mode a note that keeps its own starts in. Defaults to `view`. */
+    readonly defaultMode?: NoteMode;
+    /** The switch was used: the mode the reader asked for. */
+    readonly onModeChange?: (mode: NoteMode) => void;
+    /**
+     * The note after each change made in edit mode, byte for byte the original wherever it was not
+     * edited. The package never saves it; a host that answers with the promise of its save has the
+     * editor say whether it was saved, and going back to reading wait for it (#64). The promise may
+     * resolve with a `SaveOutcome`, a save that succeeded with something the author must decide, or
+     * reject with a `SaveRefusal`, the reason it was refused: either opens, from the save's status,
+     * a dialog with the host's words and its actions (#86).
+     */
+    readonly onChange?: (markdown: string) => unknown;
+    /** Whether the switch shows its icon alone or its icon and its word. Defaults to `label`. */
+    readonly modeButton?: 'icon' | 'label';
+    /**
+     * Whether the note offers Show Markdown and Copy Markdown at its top right, editable or not:
+     * reading a note's Markdown and copying it are reading (#87). Defaults to `true`; `false` hides
+     * them, for a print, a preview or an embed.
+     */
+    readonly actions?: boolean;
 }
+/** Whether a note is read or edited. */
+export type NoteMode = 'view' | 'edit';
 /**
  * The body of a note, drawn as MemorySmith's reading page draws it.
  *
  * It renders inside `.markdown`, so the stylesheet of the package applies, and asks the host for
  * every piece of notebook data through the props of `NoteHost`.
  */
-export declare function NoteBody({ markdown, writable, onToggleTask, ...host }: NoteBodyProps): import("react").JSX.Element;
+export declare function NoteBody({ editable, mode, defaultMode, onModeChange, onChange, modeButton, actions, ...rest }: NoteBodyProps): import("react").JSX.Element;

package/dist/NoteBody.js

@@ -1,29 +1,96 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from 'react';
-import { HOST_KEYS, HostProvider, resolveHost } from './host.js';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useMemo, useRef, useState } from 'react';
+import { ICON_EDIT, ICON_VIEW } from './mode-icons.js';
+import { NoteActions } from './NoteActions.js';
+import { drawSlot } from './slots.js';
+import { HOST_KEYS, HostProvider, resolveHost, useHost } from './host.js';
 import { planFootnotes } from './footnotes.js';
 import { Markdown } from './Markdown.js';
 import { readingPlugins } from './reading.js';
 import { bodyStart, hideComments, remoteImageHosts, resolveWikilinks } from './markdown.js';
 import { readProperties } from './properties.js';
 import { Properties } from './PropertiesBlock.js';
+import { useTaskSaves } from './task-saves.js';
 import { taskBoxes } from './tasklist.js';
 import { rootStyle } from './theme.js';
 import { Transclusion } from './Transclusion.js';
 import { splitEmbeds } from './transclusion.js';
 import { wikilinkAddress } from './wikilink-address.js';
+/** The editor, loaded the first time a note is edited, so a host that only draws never loads it. */
+const NoteEditor = lazy(() => import('./edit/NoteEditor.js').then((module) => ({ default: module.NoteEditor })));
+/** The switch between reading and editing, drawn by the theme's slot or as the default theme draws it. */
+function ModeSwitch({ mode, display, toggle }) {
+    const host = useHost();
+    const slot = host.theme.components?.modeSwitch;
+    const label = mode === 'view' ? host.strings.edit : host.strings.view;
+    const icon = mode === 'view' ? ICON_EDIT : ICON_VIEW;
+    if (slot)
+        return _jsx(_Fragment, { children: drawSlot(slot, { mode, label, icon, display, toggle }) });
+    return (_jsxs("button", { type: "button", className: `mode-switch mode-switch-${display}`, "data-mode": mode, title: label, "aria-label": display === 'icon' ? label : undefined, onClick: toggle, children: [icon, display === 'label' && _jsx("span", { className: "mode-switch-label", children: label })] }));
+}
 /**
  * The body of a note, drawn as MemorySmith's reading page draws it.
  *
  * It renders inside `.markdown`, so the stylesheet of the package applies, and asks the host for
  * every piece of notebook data through the props of `NoteHost`.
  */
-export function NoteBody({ markdown, writable = false, onToggleTask, ...host }) {
+export function NoteBody({ editable = false, mode, defaultMode = 'view', onModeChange, onChange, modeButton = 'label', actions = true, ...rest }) {
+    const [own, setOwn] = useState(defaultMode);
+    // The author asked to go back to reading, and the editor is finishing: a save, the toolbar folding.
+    const [leaving, setLeaving] = useState(false);
+    // The last text handed to the host in edit mode, which Show and Copy Markdown give there (#76).
+    const handed = useRef(null);
+    const current = editable ? (mode ?? own) : 'view';
+    if (!editable && !actions)
+        return _jsx(NoteView, { ...rest });
+    const go = (next) => {
+        if (mode === undefined)
+            setOwn(next);
+        onModeChange?.(next);
+    };
+    const toggle = () => {
+        if (current === 'view') {
+            handed.current = null;
+            go('edit');
+        }
+        else
+            setLeaving(true);
+    };
+    const hand = (text) => {
+        handed.current = text;
+        return onChange?.(text);
+    };
+    const onLeave = (left) => {
+        setLeaving(false);
+        if (left)
+            go('view');
+    };
+    const { writable: _writable, onToggleTask: _toggle, ...host } = rest;
+    return (_jsx(HostOnly, { host: rest, children: (resolved) => {
+            // Show and Copy Markdown for whoever reads the note, in both modes (#76, #87), and the
+            // switch only where the note is editable.
+            const corner = (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: "note-corner", children: [actions && _jsx(NoteActions, { text: () => (current === 'edit' ? (handed.current ?? rest.markdown) : rest.markdown) }), editable && _jsx(ModeSwitch, { mode: current, display: modeButton, toggle: toggle })] }) }));
+            if (current === 'view')
+                return _jsx(NoteView, { ...rest, corner: corner, switched: editable });
+            return (
+            // While the editor loads, the note stays on the page as it was.
+            _jsx(Suspense, { fallback: _jsx(NoteView, { ...rest, corner: corner, switched: true }), children: _jsx(NoteEditor, { ...host, onChange: hand, corner: corner, autoFocus: true, leaving: leaving, onLeave: onLeave }) }));
+        } }));
+}
+/** The host resolved once, for what is drawn around the note. */
+function HostOnly({ host, children }) {
+    const resolved = useMemo(() => resolveHost(host), HOST_KEYS.map((key) => host[key]));
+    return _jsx(_Fragment, { children: children(resolved) });
+}
+/** The note drawn for reading: the page MemorySmith's reading page draws. */
+function NoteView({ markdown, writable = false, onToggleTask, corner, switched = false, ...host }) {
     const resolved = useMemo(() => resolveHost(host), 
     // Every member of the contract, so a host that passes the same functions keeps the same host.
     HOST_KEYS.map((key) => host[key]));
     // The frontmatter is drawn apart from the body, as the theme decides, so the
     // runs start after it. Everything below counts task items from there.
+    // Each tick the host answers with a promise locks its item until the save settles.
+    const saves = useTaskSaves(onToggleTask);
     const split = bodyStart(markdown);
     const properties = useMemo(() => readProperties(markdown), [markdown]);
     // What a comment holds is never read (§7.6): it leaves before the embeds and the links are found.
@@ -80,7 +147,7 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
     // 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 markdown-theme-${resolved.theme.name}`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [_jsx(Properties, { properties: properties }), segments.map((segment, index) => {
+    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name}${corner ? ' has-note-corner' : ''}${switched ? ' has-mode-switch' : ''}`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [corner, _jsx(Properties, { properties: properties }), segments.map((segment, index) => {
                     if (!('rendered' in segment)) {
                         return _jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index);
                     }
@@ -93,6 +160,6 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
                         // `mappable` above is what makes it safe to write back through.
                         // 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) })] }) }));
+                        source: planned?.text ?? segment.rendered, onToggleTask: onToggleTask && ((ordinal, checked) => saves.toggle(base + ordinal, checked)), taskSave: (ordinal) => saves.stateOf(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) }), writable && onToggleTask && (_jsx("p", { className: "visually-hidden", role: "status", "aria-live": "polite", children: saves.announcement && resolved.strings[saves.announcement] }))] }) }));
 }

package/dist/edit/AttachDialog.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The attach dialog (#78): the three ways a file or an image comes into a note. From the computer —
+ * one or more files, each kept by the host's `attach` under the name and with the description the
+ * author gives; from the notebook — a file it already keeps, listed by the host's `files`, found by
+ * name or description; from the web — an image at a public address, written as `![name](address)`.
+ */
+export interface ChosenFile {
+    readonly file: File;
+    readonly name: string;
+    readonly description: string;
+}
+/** The Markdown of an image at a web address, its name the alternative text (§3.14). */
+export declare function webImage(name: string, address: string): string;
+export declare function AttachDialog({ refusal, onClose, onClosed, onAttach, onEmbed, onLink, }: {
+    /** Why the host refused the last file, said at the top of the dialog the author opened after it (#88). */
+    refusal?: string | null;
+    onClose: () => void;
+    /** Once the dialog is closed: whether something was put in the note, which then has the focus. */
+    onClosed: (inserted: boolean) => void;
+    onAttach: (files: readonly ChosenFile[]) => void;
+    onEmbed: (name: string) => void;
+    onLink: (name: string, address: string) => void;
+}): import("react").JSX.Element;