@memorysmithapp/markdown-renderer 0.7.1 → 0.8.0

package/README.md

@@ -18,7 +18,7 @@ import 'katex/dist/katex.min.css';
 <NoteBody
   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
+  keeps={(name) => notebookKeepsAFile(name)}       // reached by an embed, and by an image with no host: ![](../assets/x.png)
   fileOf={(name) => describe(name)}               // { mimeType, bytes, url, description }: drawn by its type, as MemorySmith does
   renderLink={({ href, className, children }) => <a href={href} className={className} onClick={follow(href)}>{children}</a>} // follow: your router's navigate, captured where it is
   loadNote={(name) => fetchTheBodyOf(name)}        // for an embedded note; the package never fetches

package/dist/Markdown.d.ts

@@ -1,4 +1,4 @@
-import { type AnchorHTMLAttributes, type ReactNode } from 'react';
+import { type AnchorHTMLAttributes, type ImgHTMLAttributes, type ReactNode } from 'react';
 import { type FootnoteRef } from './footnotes.js';
 import type { TaskSave } from './task-saves.js';
 /**
@@ -40,6 +40,17 @@ export interface MarkdownProps {
 type WithNode<T> = T & {
     node?: unknown;
 };
+/**
+ * An image, with the dimensions the specification puts in its alt text
+ * (§3.14). What precedes the pipe is the description and is never dropped;
+ * what follows it is width, or width and height, in CSS pixels, or a width as
+ * a share of the page at most (#108), and never appears as text. A value that is neither stays part of the description,
+ * because deleting an accessibility label is the worse failure.
+ *
+ * A destination that names no host is a file the notebook keeps, by the last segment of its path
+ * (§5.8, #104): it is drawn as the embed of that file is, and never asked of a path under the page.
+ */
+export declare function MarkdownImage({ alt, node: _node, ...rest }: WithNode<ImgHTMLAttributes<HTMLImageElement>>): import("react").JSX.Element;
 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, taskSave, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
 export {};

package/dist/Markdown.js

@@ -7,9 +7,10 @@ import rehypeKatex from 'rehype-katex';
 import { followable } from './address.js';
 import { CopyButton } from './CopyButton.js';
 import { fileAddress, fileKind, formatBytes, opensInBrowser, rendersAs } from './file-types.js';
+import { keptImageName } from './kept-image.js';
 import { highlightLanguage, highlightTree, languageToLoad, loadGrammar } from './highlight.js';
 import { useHost } from './host.js';
-import { readDimensions, readImageAlt } from './image-dimensions.js';
+import { readDimensions, readImageAlt, sizedAttributes } from './image-dimensions.js';
 import { choiceTargetOf, LinkChoice } from './LinkChoice.js';
 import { toUnixNewlines } from './markdown.js';
 import { MermaidDiagram } from './MermaidDiagram.js';
@@ -20,13 +21,21 @@ import { ordinalAt } from './tasklist.js';
 /**
  * An image, with the dimensions the specification puts in its alt text
  * (§3.14). What precedes the pipe is the description and is never dropped;
- * what follows it is width, or width and height, in CSS pixels, and never
- * appears as text. A value that is neither stays part of the description,
+ * what follows it is width, or width and height, in CSS pixels, or a width as
+ * a share of the page at most (#108), and never appears as text. A value that is neither stays part of the description,
  * because deleting an accessibility label is the worse failure.
+ *
+ * A destination that names no host is a file the notebook keeps, by the last segment of its path
+ * (§5.8, #104): it is drawn as the embed of that file is, and never asked of a path under the page.
  */
-function MarkdownImage({ alt, node: _node, ...rest }) {
+export function MarkdownImage({ alt, node: _node, ...rest }) {
     const read = readImageAlt(alt ?? '');
-    return (_jsx("img", { ...rest, alt: read.description, ...(read.width === null ? {} : { width: read.width }), ...(read.height === null ? {} : { height: read.height }) }));
+    const name = typeof rest.src === 'string' ? keptImageName(rest.src) : null;
+    if (name !== null)
+        return _jsx(Attachment, { name: name, size: read, description: read.description, title: rest.title });
+    // The description is the hover hint too, so a person who sees the picture can read it (#109); a title written wins.
+    const title = rest.title || read.description || undefined;
+    return _jsx("img", { ...rest, alt: read.description, title: title, ...sizedAttributes(read) });
 }
 /**
  * A link to a place in the same note: a footnote and its way back (§7.12),
@@ -56,26 +65,19 @@ 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, 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 }) {
+function Attachment({ name, size, ...written }) {
     const host = useHost();
     if (!host.keeps(name))
-        return _jsx(AttachmentMissing, { name: name });
+        return _jsx(AttachmentMissing, { name: name, label: written.description });
     if (host.renderAttachment)
-        return _jsx(_Fragment, { children: host.renderAttachment({ name, width, height }) });
+        return _jsx(_Fragment, { children: host.renderAttachment({ name, ...size, ...written }) });
     if (!host.fileOf)
-        return _jsx("span", { className: "attachment-loading", children: name });
-    return _jsx(KeptAttachment, { name: name, width: width, height: height });
+        return _jsx("span", { className: "attachment-loading", children: written.description || name });
+    return _jsx(KeptAttachment, { name: name, size: size, ...written });
 }
-function AttachmentMissing({ name }) {
+function AttachmentMissing({ name, label }) {
     const host = useHost();
-    return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, children: name }));
+    return (_jsx("span", { className: "attachment-missing", title: host.strings.attachmentMissing, "data-name": label ? name : undefined, children: label || name }));
 }
 function isThenable(value) {
     return typeof value === 'object' && value !== null && typeof value.then === 'function';
@@ -129,30 +131,36 @@ function openInTab(event, url) {
  * 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 }) {
+function KeptAttachment({ name, size: declared, ...written }) {
     const host = useHost();
     const slot = useSlot('attachment');
     const described = useKeptFile(name);
     if (described === undefined)
-        return _jsx("span", { className: "attachment-loading", children: name });
+        return _jsx("span", { className: "attachment-loading", children: written.description || 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 };
+        return _jsx(AttachmentMissing, { name: name, label: written.description });
+    // What the note wrote of the file is what the reader gets of it; the file's own when it wrote nothing.
+    const description = written.description || described.description;
+    const file = {
+        ...described,
+        url,
+        downloadUrl: fileAddress(described.downloadUrl ?? described.url) || url,
+        ...(description ? { description } : {}),
+    };
     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 });
+        return _jsx(_Fragment, { children: drawSlot(slot, { name, file, shape, kind, size, opens, ...declared, title: written.title ?? null }) });
+    const sized = sizedAttributes(declared);
+    if (shape === 'image') {
+        // Described, its description is also the hover hint, a title written winning (#109); a picture
+        // with none takes its name as its `alt` and no hint, which would only say the name again.
+        const title = written.title || file.description;
+        return _jsx("img", { className: "attachment-image", src: file.url, alt: file.description || name, ...(title ? { title } : {}), ...sized });
+    }
     if (shape === 'audio')
         return _jsx("audio", { className: "attachment-player", controls: true, src: file.url });
     if (shape === 'video')
@@ -178,7 +186,7 @@ export function MarkdownAnchor({ href, children, node: _node, ...rest }) {
         const at = address.lastIndexOf('|');
         const measured = at === -1 ? null : readDimensions(address.slice(at + 1));
         const name = measured ? address.slice(0, at) : address;
-        return _jsx(Attachment, { name: name, width: measured?.width ?? null, height: measured?.height ?? null });
+        return _jsx(Attachment, { name: name, size: measured ?? { width: null, height: null, percent: null } });
     }
     if (href?.startsWith('pending:')) {
         const pending = (label) => (_jsx("span", { className: "wikilink-pending", title: host.strings.pendingLink, children: label }));

package/dist/diagnose.js

@@ -11,6 +11,7 @@
  * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
  * reads a diagram as the page would draw it, loaded only when a note carries one.
  */
+import { keptImageName } from './kept-image.js';
 import katex from 'katex';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
@@ -36,7 +37,7 @@ export const NOTICES = {
     'raw-html': { severity: 'notice', section: '7.9', message: 'Raw HTML is drawn as text, tags and all.' },
     'strikethrough-single-tilde': { severity: 'notice', section: '4.3', message: 'One tilde strikes nothing: the tildes stay on the page. Strikethrough is ~~two~~.' },
     'link-pending': { severity: 'hint', section: '7.4', message: 'No note answers this link yet, so it is drawn as pending.' },
-    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, so it is drawn as a pending link.' },
+    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, or no kept file this image, so it is drawn as pending.' },
 };
 /** A footnote reference left as text, which is one with no definition (§7.12). */
 const UNDEFINED_REFERENCE = /\[\^[^\]\s]+\]/g;
@@ -106,6 +107,7 @@ export async function diagnose(markdown, options = {}) {
     const diagrams = [];
     const referenced = new Set();
     const definitions = [];
+    const images = [];
     walk(tree, (node) => {
         const at = span(node);
         if (!at)
@@ -136,6 +138,11 @@ export async function diagnose(markdown, options = {}) {
         else if (node.type === 'footnoteDefinition') {
             definitions.push(node);
         }
+        else if (node.type === 'image') {
+            const name = keptImageName(node.url ?? '');
+            if (name !== null)
+                images.push({ name, at });
+        }
     });
     for (const definition of definitions) {
         const at = span(definition);
@@ -164,6 +171,13 @@ export async function diagnose(markdown, options = {}) {
         }
     });
     pending(hidden, split, options, report);
+    // An image whose destination names no host names a kept file, and only a kept file (§5.8, #104).
+    if (options.resolve || options.reaches) {
+        const keeps = options.keeps ?? (() => false);
+        for (const image of images)
+            if (!keeps(image.name))
+                report('embed-pending', image.at[0], image.at[1], image.name);
+    }
     if (diagrams.length > 0 && options.diagrams !== false) {
         const mermaid = (await import('mermaid')).default;
         for (const diagram of diagrams) {

package/dist/edit/ContextMenu.d.ts

@@ -1,6 +1,6 @@
 /**
  * The editor's own menu on a right-click in edit mode (#81): what the toolbar formats and inserts,
- * where the author is, with the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
+ * where the author is, after the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
  * kept inside the window, and closed by Escape, a click outside it, a scroll, or an entry run.
  */
 import { type ReactNode } from 'react';

package/dist/edit/ContextMenu.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * The editor's own menu on a right-click in edit mode (#81): what the toolbar formats and inserts,
- * where the author is, with the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
+ * where the author is, after the clipboard's three verbs. It is a `role="menu"` reached by keyboard,
  * kept inside the window, and closed by Escape, a click outside it, a scroll, or an entry run.
  */
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';

package/dist/edit/NoteEditor.js

@@ -261,7 +261,7 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     /** Where the editing menu is open, in the window's coordinates (#81). */
     const [menu, setMenu] = useState(null);
     const openMenu = useRef((x, y) => setMenu({ x, y }));
-    /** The menu's groups, from the same commands as the toolbar: Format with a selection, Insert, Edit. */
+    /** The menu's groups, from the same commands as the toolbar: Edit first (#110), Format with a selection, Insert. */
     const menuGroups = (target) => {
         const words = resolved.strings.editor;
         const item = (name, action, shortcut) => ({
@@ -308,7 +308,8 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
                 { name: 'attach', label: words.attach, icon: ICONS.attach, run: () => setAttachOpen(true) },
             ],
         });
-        groups.push({
+        // The clipboard's verbs open the menu, as they open every other one a person knows (#110).
+        groups.unshift({
             label: words.menuEdit,
             items: [
                 {

package/dist/edit/blocks.d.ts

@@ -29,12 +29,28 @@ export declare function CalloutBlock({ view, text, marker }: {
         fold: '+' | '-' | null;
     };
 }): import("react").JSX.Element;
+/** The narrowest an image is sized to, by a field or the handle: something a reader still sees (#105). */
+export declare const MIN_IMAGE_SIZE = 16;
 /**
- * An image drawn in edit mode with the size it is drawn at set in place (#98): a width in pixels,
- * its height following, a handle at its corner that drags it, and a button back to its own size.
- * Each writes the dimensions of its notation — `![description|300](…)` or `![[photo.jpg|300]]` —
- * and no other byte. The controls appear once an image is drawn inside it, so an embed of a file
- * that is not an image, or a host's own drawing without one, offers none.
+ * An image drawn in edit mode with what its notation writes set in place (#98, #106): its width and
+ * its height with a lock between them — locked, the height follows and only the width is written,
+ * `|300`; open, both are, `|300x180` — the width's unit, pixels or a share of the page (`|50%`,
+ * #108), its description for a Markdown image, a button back to its own size, and a handle at its
+ * corner that drags it, keeping the proportion or, with the lock open or Shift held, not. Each
+ * writes the dimensions or the description of its notation, and no other byte.
+ *
+ * A field selects what it holds when it takes the focus, so typing replaces it, and writes on Enter
+ * or when it is left; Escape leaves the note as it is. A value outside the range a reader can see
+ * — from 16 pixels to the column or the image's own width, the wider — is refused where it was
+ * typed, never brought into the range and written (#105).
+ *
+ * The controls stand under the picture, never over it, and nothing that starts on them or in the
+ * moment after reaches the click that shows the image's source (#107): they are all marked as
+ * controls, gaps included, and the frame is marked busy while one of them has the focus, while the
+ * handle is dragged and for a moment after a pointer or a touch on them.
+ *
+ * The controls appear once an image is drawn inside it, so an embed of a file that is not an image,
+ * or a host's own drawing without one, offers none.
  */
 export declare function ImageBlock({ view, source, children }: {
     view: EditorView;