@memorysmithapp/markdown-renderer 0.4.0 → 0.6.0

package/dist/host.d.ts

@@ -71,8 +71,13 @@ export interface NoteHost {
      * has its own name and none), and answers the name it is kept under, which the editor embeds as
      * `![[name]]` (#75, #78). The package never stores a file. Without it, the editor offers no file
      * from the computer.
+     *
+     * While it keeps the file, the host may report each step through `progress`, which the paperclip
+     * shows and announces; a promise rejected with an `AttachRefusal` has the paperclip say why until
+     * the author acts (#88). A host that ignores `progress` and rejects with an error keeps the
+     * paperclip's own words.
      */
-    readonly attach?: (file: File, attributes: AttachAttributes) => string | PromiseLike<string>;
+    readonly attach?: (file: File, attributes: AttachAttributes, progress: (report: AttachProgress) => void) => string | PromiseLike<string>;
     /**
      * The files the notebook keeps, with their names, which the attach dialog lists for the author to
      * embed one (#78). Without it, the dialog offers no file of the notebook.
@@ -87,9 +92,21 @@ export interface NoteHost {
     /**
      * 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`.
+     *
+     * In edit mode the node may be drawn outside the host's React tree, in the root of a block the
+     * editor draws, so it must not depend on the host's context; a node that throws there leaves the
+     * block's Markdown in its place (#90).
      */
     readonly renderAttachment?: (file: AttachmentRequest) => ReactNode;
-    /** Draws a link to an internal address, through the host's router. */
+    /**
+     * Draws a link to an internal address, through the host's router.
+     *
+     * In edit mode the node may be drawn outside the host's React tree, in the root of a block the
+     * editor draws — a callout, a table, an embed, the properties — so it must not depend on the host's
+     * context: a router's `<Link>`, which reads its router from context, throws there. Hand it what it
+     * needs (a `navigate` captured where the router is) or draw an anchor whose click the host follows.
+     * A node that throws leaves the block's Markdown in its place (#90).
+     */
     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?: NoteStringsInput;
@@ -155,6 +172,23 @@ export interface KeptFile {
 export interface KeptFileEntry extends KeptFile {
     readonly name: string;
 }
+/** A step of keeping a file, as the host words it (#88). */
+export interface AttachProgress {
+    /** What is happening, in the reader's language: "Sending part 12 of 40". */
+    readonly message: string;
+    /** How much is done, from 0 to 1, when the host knows it: drawn as a determinate indicator. */
+    readonly fraction?: number;
+}
+/**
+ * Why the host would not keep a file, what `attach` rejects with (#88): a plain object, so that an
+ * `Error`, whose message is meant for a developer, keeps the paperclip's own words.
+ */
+export interface AttachRefusal {
+    /** Why, in the reader's language: "An attached file goes up to 100 MB". */
+    readonly message: string;
+}
+/** Whether a rejection is a refusal the host worded for the author, and not an error. */
+export declare function isAttachRefusal(value: unknown): value is AttachRefusal;
 /** What the author said of a file they attach (#78). */
 export interface AttachAttributes {
     /** The name to keep it under; the host may answer another, when that one is taken. */
@@ -188,7 +222,7 @@ export interface ResolvedHost {
     readonly loadNote: ((name: string) => Promise<EmbeddedNote | null>) | null;
     readonly keeps: (name: string) => boolean;
     readonly suggest: ((query: string) => readonly string[] | PromiseLike<readonly string[]>) | null;
-    readonly attach: ((file: File, attributes: AttachAttributes) => string | PromiseLike<string>) | null;
+    readonly attach: ((file: File, attributes: AttachAttributes, progress: (report: AttachProgress) => void) => string | PromiseLike<string>) | null;
     readonly files: (() => readonly KeptFileEntry[] | PromiseLike<readonly KeptFileEntry[]>) | null;
     readonly fileOf: ((name: string) => KeptFile | null | PromiseLike<KeptFile | null>) | null;
     readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;

package/dist/host.js

@@ -2,6 +2,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
 import { withDefaults } from './strings.js';
 import { DEFAULT_THEME, schemeOf } from './theme.js';
+/** Whether a rejection is a refusal the host worded for the author, and not an error. */
+export function isAttachRefusal(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Error) &&
+        typeof value.message === 'string' &&
+        value.message.length > 0);
+}
 /**
  * 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.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { NoteBody, type NoteBodyProps, type NoteMode } from './NoteBody.js';
-export type { AttachAttributes, AttachmentRequest, EmbeddedNote, KeptFile, KeptFileEntry, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
+export type { SaveAction, SaveNotice, SaveOutcome, SaveRefusal } from './edit/saves.js';
+export { isAttachRefusal } from './host.js';
+export type { AttachAttributes, AttachmentRequest, AttachProgress, AttachRefusal, EmbeddedNote, KeptFile, KeptFileEntry, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
 export { ENGLISH, type EditorWords, type NoteStrings, type NoteStringsInput } from './strings.js';
 export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, type BlockquoteSlotProps, type CalloutSlotProps, type CodeBlockSlotProps, type DiagramSlotProps, type EmbedSlotProps, type FootnotesSlotProps, type HeadingSlotProps, type InlineCodeSlotProps, type ModeSwitchSlotProps, type AttachmentSlotProps, type PropertiesSlotProps, type Scheme, type TableSlotProps, type TaskBoxSlotProps, type Theme, type ThemeComponents, type ThemeProperties, type WikilinkSlotProps, } from './theme.js';
 export { followable } from './address.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 // The entry point of @memorysmithapp/markdown-renderer.
 export { NoteBody } from './NoteBody.js';
+export { isAttachRefusal } from './host.js';
 export { ENGLISH } from './strings.js';
 export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, } from './theme.js';
 export { followable } from './address.js';

package/dist/strings.d.ts

@@ -107,6 +107,10 @@ export interface EditorWords {
     readonly attach: string;
     readonly attaching: string;
     readonly attachFailed: string;
+    /** Said after the host's step while more files wait their turn (#88). */
+    readonly attachQueued: (count: number) => string;
+    /** Said over a drawn block's lines when drawing it failed, so the block is never left empty (#90). */
+    readonly blockFailed: string;
     /** A code block's language, chosen at its top right (#84). */
     readonly language: string;
     readonly plainText: string;

package/dist/strings.js

@@ -112,6 +112,8 @@ export const ENGLISH = {
         attach: 'Attach a file',
         attaching: 'Attaching…',
         attachFailed: 'The file was not attached',
+        attachQueued: (count) => (count === 1 ? '1 more file waiting' : `${count} more files waiting`),
+        blockFailed: 'This block could not be drawn; its Markdown is below',
         language: 'Language',
         plainText: 'Plain text',
         mermaidDiagram: 'Mermaid diagram',

package/dist/theme.d.ts

@@ -315,7 +315,10 @@ export interface Theme {
     };
     /** An icon per callout kind, drawn in the title in place of the stylesheet's. */
     readonly icons?: Readonly<Record<string, ReactNode>>;
-    /** The slots the theme fills. */
+    /**
+     * The slots the theme fills. In edit mode a slot may be drawn outside the host's React tree, in
+     * the root of a block the editor draws, so it must not depend on the host's context (#90).
+     */
     readonly components?: Partial<ThemeComponents>;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A React component that draws a MemorySmith note exactly as MemorySmith's reading page does.",
   "keywords": [
     "markdown",
@@ -79,7 +79,7 @@
     "unified": "11.0.5"
   },
   "devDependencies": {
-    "@memorysmithapp/markdown-spec": "0.4.0",
+    "@memorysmithapp/markdown-spec": "0.6.0",
     "@types/hast": "3.0.5",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",

package/structure.css

@@ -15,6 +15,13 @@
   box-sizing: border-box;
 }
 
+/* What is laid out of the flow hangs from the note, never from the page: a
+   host that scrolls the note in a pane of its own keeps a page of its own
+   height (#93). */
+.markdown {
+  position: relative;
+}
+
 .markdown img {
   max-width: 100%;
 }
@@ -233,6 +240,17 @@
 /* The attach dialog (#78): its ways in as tabs, a panel that alone scrolls,
    and the files of the notebook as a list of buttons. */
 /* One height for every way in, so the dialog does not jump between them. */
+/* The paperclip and, under it, the bar of the host's fraction (#88). */
+.markdown .edit-attach-control {
+  position: relative;
+  display: inline-flex;
+}
+.markdown .edit-attach-progress {
+  position: absolute;
+  inset-inline: 0.2rem;
+  bottom: 0;
+  pointer-events: none;
+}
 .markdown .edit-attach .edit-source-frame {
   height: min(34rem, calc(100vh - 4rem));
 }
@@ -291,6 +309,19 @@
   display: flex;
   justify-content: flex-end;
 }
+/* What the host said of a save (#86): its title, its explanation, and its
+   choices in a row that wraps, as narrow as its words. */
+.markdown .edit-notice {
+  max-width: min(32rem, calc(100vw - 2rem));
+}
+.markdown .edit-notice-message {
+  margin: 0;
+}
+.markdown .edit-notice-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
 @media (max-width: 560px) {
   .markdown .edit-attach-file {
     grid-template-columns: 1fr auto;
@@ -373,6 +404,12 @@
 .markdown .cm-ms-math-block {
   display: flow-root;
 }
+/* A block that could not be drawn shows its lines as they were written (#90). */
+.markdown .cm-ms-block-failed pre {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
 /* A table's cell is where a click edits it: it fills its column and keeps a
    size of its own when it is empty, as every cell of a new table is, or it
    would be nothing wide and nothing could be clicked (#68). */

package/theme-default.css

@@ -1298,6 +1298,9 @@
 .markdown .edit-save[data-save='failed'] {
   color: rgb(var(--ms-callout-stop));
 }
+.markdown .edit-save[data-save='alert'] {
+  color: rgb(var(--ms-callout-warn));
+}
 /* Asked to leave while the last save failed: the corner shakes once. */
 .markdown .edit-corner[data-blocked] {
   animation: markdown-corner-refuse 360ms ease-in-out;
@@ -1322,6 +1325,14 @@
 .markdown .edit-control[data-attach='failed'] {
   color: rgb(var(--ms-callout-stop));
 }
+.markdown .edit-attach-progress {
+  height: 2px;
+  border-radius: 1px;
+  background: linear-gradient(to right, var(--ms-accent) calc(var(--edit-attach-fraction, 0) * 100%), var(--ms-border) 0);
+}
+.markdown .edit-attach-refusal {
+  padding: 0.6rem 1rem 0;
+}
 @media (prefers-reduced-motion: reduce) {
   .markdown .edit-control[data-attach='busy'] > svg {
     animation: none;
@@ -1332,7 +1343,8 @@
     transform: rotate(360deg);
   }
 }
-.markdown .edit-save-retry {
+.markdown .edit-save-retry,
+.markdown .edit-save-notice {
   padding: 0;
   border: 0;
   border-radius: calc(var(--ms-radius) - 2px);
@@ -1340,10 +1352,12 @@
   color: inherit;
   cursor: pointer;
 }
-.markdown .edit-save-retry:hover {
+.markdown .edit-save-retry:hover,
+.markdown .edit-save-notice:hover {
   background: var(--ms-code-bg);
 }
-.markdown .edit-save-retry:focus-visible {
+.markdown .edit-save-retry:focus-visible,
+.markdown .edit-save-notice:focus-visible {
   outline: 2px solid var(--ms-accent);
   outline-offset: 2px;
 }
@@ -1637,6 +1651,19 @@
   font-size: 1rem;
   font-weight: 600;
 }
+/* What the host said of a save: the dialog's own size, whatever the toolbar it opens from. */
+.markdown .edit-notice {
+  font-family: var(--ms-font-sans);
+  font-size: 0.95rem;
+  line-height: 1.55;
+}
+.markdown .edit-notice-message {
+  padding: 1rem 1rem 0;
+}
+.markdown .edit-notice-actions {
+  gap: 0.5rem;
+  padding: 1rem;
+}
 .markdown .edit-source-copied {
   color: var(--ms-text-soft);
   font-size: 0.8rem;
@@ -1886,6 +1913,20 @@
 .markdown .cm-ms-block:hover {
   box-shadow: 0 0 0 1px var(--ms-border);
 }
+.markdown .cm-ms-block-failed {
+  padding: 0.5rem 0.75rem;
+  border: 1px dashed var(--ms-border);
+  border-radius: var(--ms-radius);
+}
+.markdown .cm-ms-block-failed-notice {
+  margin: 0 0 0.35rem;
+  color: var(--ms-text-soft);
+  font-size: 0.85em;
+}
+.markdown .cm-ms-block-failed pre {
+  font-family: var(--ms-font-mono);
+  font-size: 0.9em;
+}
 .markdown .edit-block-controls {
   opacity: 0;
   padding: 0.1rem;