@profullstack/readm3 0.2.0 → 0.4.0

package/dist/viewer.js

@@ -1,22 +1,36 @@
 /**
- * The reader: a file browser on the left, the rendered document on the right.
+ * The reader: a file browser on the left, the document on the right.
+ *
+ * The right pane has two modes. Reading renders the buffer through
+ * `markdown.ts`; editing shows the same buffer raw, with a caret. Both read the
+ * same text, so leaving edit mode is all it takes to see the change rendered —
+ * there is no separate preview to keep in step.
  */
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { createApp, stringWidth } from "@profullstack/hqtui";
+import { backspace, breakRun, createEditor, del, indent, insert, killToLineEnd, killToLineStart, markSaved, moveDocEnd, moveDocStart, moveDown, moveEnd, moveHome, moveLeft, moveRight, moveUp, moveVertical, moveWordLeft, moveWordRight, newline, redo, text as bufferText, undo, } from "./editor.js";
+import { DEFAULT_FLAVOR } from "./flavors.js";
 import { renderMarkdown } from "./markdown.js";
 import { colorOf } from "./roles.js";
 import { filterTree, flatten, indexOfPath, label as pathLabel, reveal, scan, } from "./tree.js";
 /** Files above this size are refused rather than rendered. */
 const MAX_BYTES = 4 * 1024 * 1024;
+/** A tab is two columns, in the buffer and on screen alike. */
+const TAB = "  ";
 const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+const expand = (line) => line.replace(/\t/g, TAB);
+/** Where a caret at `col` lands once tabs are expanded. */
+const displayCol = (line, col) => expand(line.slice(0, col)).length;
 export async function run(options) {
     const root = resolve(options.root);
+    const flavor = options.flavor ?? DEFAULT_FLAVOR;
+    const readOnly = options.readOnly ?? false;
     const app = await createApp({
         theme: options.theme,
         mouse: options.mouse !== false,
-        // `q` is handled below so it can be typed into the filter.
-        quitKeys: ["ctrl+c"],
+        // `q` is handled below so it can be typed into the filter, and into the text.
+        quitKeys: [],
     });
     let entries = scan(root, { all: options.all ?? false });
     let filter = "";
@@ -28,9 +42,16 @@ export async function run(options) {
     let help = false;
     let message = "";
     let openPath = null;
-    let source = null;
+    /** The open file's text, and the caret into it. Null until a file opens. */
+    let buffer = null;
+    let mode = "read";
+    let spoilers = false;
     let doc = null;
     let scroll = 0;
+    /** Bumped on every edit, so the rendered document is rebuilt exactly then. */
+    let stamp = 0;
+    /** A yes/no the next keypress answers. */
+    let pending = null;
     let sidebar = options.sidebar ?? 0;
     // Last measured pane interiors; the panel header needs them a frame early.
     let viewport = { w: 80, h: 20 };
@@ -38,9 +59,14 @@ export async function run(options) {
     // Owned here rather than left to the widget, so a click can be turned back
     // into an index and the view stays put when the selection moves inside it.
     let treeOffset = 0;
+    // The edit pane scrolls on both axes: long lines are not wrapped, because a
+    // caret in a wrapped line is a lie about where the text is.
+    let editTop = 0;
+    let editLeft = 0;
     // The panel header quotes numbers only the draw can measure, so a change in
     // geometry or document length schedules exactly one more frame.
     let measured = { total: -1, h: -1 };
+    const dirty = () => buffer?.dirty ?? false;
     const rebuild = (keepPath) => {
         view = filter ? filterTree(entries, filter, root) : entries;
         flat = flatten(view);
@@ -54,16 +80,50 @@ export async function run(options) {
                 message = `${basename(path)} is ${(info.size / 1024 / 1024).toFixed(1)} MB — too large to render`;
                 return;
             }
-            source = readFileSync(path, "utf8");
+            buffer = createEditor(readFileSync(path, "utf8"));
             openPath = path;
             doc = null;
             scroll = 0;
+            editTop = 0;
+            editLeft = 0;
+            mode = "read";
             message = "";
         }
         catch (error) {
             message = `Cannot read ${basename(path)}: ${error instanceof Error ? error.message : String(error)}`;
         }
     };
+    /** Do something that would discard unsaved work, asking first if it would. */
+    const guard = (what, run) => {
+        if (!dirty()) {
+            run();
+            return;
+        }
+        pending = { message: `${basename(openPath ?? "")} has unsaved changes. ${what} anyway?`, run };
+    };
+    const save = () => {
+        if (!openPath || !buffer)
+            return;
+        try {
+            writeFileSync(openPath, bufferText(buffer), "utf8");
+            markSaved(buffer);
+            message = "";
+        }
+        catch (error) {
+            message = `Cannot save: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    };
+    const enterEdit = () => {
+        if (!buffer)
+            return;
+        if (readOnly) {
+            message = "Read-only: started with --read-only.";
+            return;
+        }
+        mode = "edit";
+        pane = "view";
+        breakRun(buffer);
+    };
     const maxScroll = () => Math.max(0, (doc?.lines.length ?? 0) - viewport.h);
     const moveSelection = (delta) => {
         if (flat.length === 0)
@@ -79,8 +139,11 @@ export async function run(options) {
             rebuild(current.entry.path);
         }
         else {
-            openFile(current.entry.path);
-            pane = "view";
+            const path = current.entry.path;
+            guard("Open another file", () => {
+                openFile(path);
+                pane = "view";
+            });
         }
     };
     // Open whatever was asked for, or fall back to the first file in the tree.
@@ -91,13 +154,139 @@ export async function run(options) {
             rebuild(openPath);
         }
     }
+    /** Keys while the caret is in the text. Returns false when unhandled. */
+    const editKey = (event) => {
+        const ed = buffer;
+        const { key, name, char, ctrl, alt } = event;
+        const page = Math.max(1, viewport.h - 2);
+        switch (key) {
+            case "escape":
+            case "ctrl+c":
+                // Never a dead key: from the text it steps out, and the next one quits.
+                mode = "read";
+                breakRun(ed);
+                return;
+            case "ctrl+s":
+                save();
+                return;
+            case "ctrl+g":
+            case "f1":
+                // "?" is a character in here, so help moves to a key that is not.
+                help = true;
+                return;
+            case "ctrl+z":
+                undo(ed);
+                stamp++;
+                return;
+            case "ctrl+y":
+            case "ctrl+shift+z":
+                redo(ed);
+                stamp++;
+                return;
+            case "ctrl+k":
+                killToLineEnd(ed);
+                stamp++;
+                return;
+            case "ctrl+u":
+                killToLineStart(ed);
+                stamp++;
+                return;
+            case "ctrl+a":
+                moveHome(ed);
+                return;
+            case "ctrl+e":
+                moveEnd(ed);
+                return;
+            case "ctrl+home":
+                moveDocStart(ed);
+                return;
+            case "ctrl+end":
+                moveDocEnd(ed);
+                return;
+            case "ctrl+left":
+            case "alt+left":
+                moveWordLeft(ed);
+                return;
+            case "ctrl+right":
+            case "alt+right":
+                moveWordRight(ed);
+                return;
+            default:
+                break;
+        }
+        switch (name) {
+            case "left":
+                moveLeft(ed);
+                return;
+            case "right":
+                moveRight(ed);
+                return;
+            case "up":
+                moveUp(ed);
+                return;
+            case "down":
+                moveDown(ed);
+                return;
+            case "home":
+                moveHome(ed);
+                return;
+            case "end":
+                moveEnd(ed);
+                return;
+            case "pageup":
+                moveVertical(ed, -page);
+                return;
+            case "pagedown":
+                moveVertical(ed, page);
+                return;
+            case "enter":
+                newline(ed);
+                stamp++;
+                return;
+            case "backspace":
+                backspace(ed);
+                stamp++;
+                return;
+            case "delete":
+                del(ed);
+                stamp++;
+                return;
+            case "tab":
+                indent(ed);
+                stamp++;
+                return;
+            case "space":
+                insert(ed, " ");
+                stamp++;
+                return;
+            default:
+                break;
+        }
+        if (char && !ctrl && !alt) {
+            insert(ed, char);
+            stamp++;
+        }
+    };
     app.on("key", (event) => {
         const { key, name, char } = event;
+        if (pending) {
+            const answer = pending;
+            pending = null;
+            if (key === "y" || key === "Y")
+                answer.run();
+            app.invalidate();
+            return;
+        }
         if (help) {
             help = false;
             app.invalidate();
             return;
         }
+        if (mode === "edit" && buffer) {
+            editKey(event);
+            app.invalidate();
+            return;
+        }
         if (filtering) {
             if (key === "escape") {
                 filtering = false;
@@ -128,8 +317,24 @@ export async function run(options) {
             return;
         }
         switch (key) {
+            case "ctrl+c":
             case "q":
-                app.stop();
+                guard("Quit", () => app.stop());
+                app.invalidate();
+                return;
+            case "ctrl+s":
+                save();
+                app.invalidate();
+                return;
+            case "e":
+            case "i":
+                enterEdit();
+                app.invalidate();
+                return;
+            case "s":
+                spoilers = !spoilers;
+                doc = null;
+                app.invalidate();
                 return;
             case "?":
                 help = true;
@@ -141,12 +346,14 @@ export async function run(options) {
                 return;
             case "r": {
                 const keep = openPath;
-                entries = scan(root, { all: options.all ?? false });
-                if (keep)
-                    reveal(entries, keep);
-                rebuild(keep);
-                if (keep)
-                    openFile(keep);
+                guard("Reload from disk", () => {
+                    entries = scan(root, { all: options.all ?? false });
+                    if (keep)
+                        reveal(entries, keep);
+                    rebuild(keep);
+                    if (keep)
+                        openFile(keep);
+                });
                 app.invalidate();
                 return;
             }
@@ -297,14 +504,15 @@ export async function run(options) {
                     }
                     p.list({
                         items: flat.map(({ entry, depth }) => {
-                            const indent = "  ".repeat(depth);
+                            const indentation = "  ".repeat(depth);
                             const glyph = entry.dir ? (entry.expanded ? "▾ " : "▸ ") : "  ";
+                            const mark = entry.path === openPath && dirty() ? "● " : "";
                             const color = entry.dir
                                 ? theme.primary
                                 : entry.path === openPath
                                     ? theme.accent
                                     : theme.foreground;
-                            return { label: `${indent}${glyph}${entry.name}`, color };
+                            return { label: `${indentation}${glyph}${mark}${entry.name}`, color };
                         }),
                         selected,
                         offset: treeOffset,
@@ -328,11 +536,17 @@ export async function run(options) {
                     });
                 });
                 // -------------------------------------------------------- reader
+                const editing = mode === "edit" && buffer !== null;
                 panes.panel({
-                    title: openRel ? ` ${openRel} ` : " readm3 ",
-                    subtitle: openPath ? `${percent}%` : undefined,
-                    footer: openPath && total > 0 ? `${Math.min(scroll + viewport.h, total)}/${total}` : undefined,
-                    borderColor: pane === "view" ? theme.borderFocused : theme.border,
+                    title: openRel ? ` ${dirty() ? "● " : ""}${openRel} ` : " readm3 ",
+                    titleColor: editing ? theme.warning : theme.title,
+                    subtitle: openPath ? (editing ? "EDIT" : `${percent}%`) : undefined,
+                    footer: openPath && editing && buffer
+                        ? `${buffer.row + 1}:${buffer.col + 1}`
+                        : openPath && total > 0
+                            ? `${Math.min(scroll + viewport.h, total)}/${total}`
+                            : undefined,
+                    borderColor: editing ? theme.warning : pane === "view" ? theme.borderFocused : theme.border,
                     padding: [0, 1],
                 }, (p) => {
                     const w = p.width;
@@ -341,7 +555,10 @@ export async function run(options) {
                     p.ctx.hit({
                         rect: p.surface.hitRect(),
                         onScroll: (delta) => {
-                            scroll = clamp(scroll + delta * 3, 0, maxScroll());
+                            if (editing && buffer)
+                                moveVertical(buffer, delta * 3);
+                            else
+                                scroll = clamp(scroll + delta * 3, 0, maxScroll());
                             app.invalidate();
                         },
                         onClick: () => {
@@ -353,15 +570,25 @@ export async function run(options) {
                         p.text(message, { fg: theme.danger, wrap: true });
                         return;
                     }
-                    if (!openPath || source === null) {
+                    if (!openPath || !buffer) {
                         p.spacer("fill");
                         p.text("readm3", { fg: theme.title, bold: true, align: "center" });
                         p.text("Pick a file on the left. ? for keys.", { fg: theme.muted, align: "center" });
                         p.spacer("fill");
                         return;
                     }
-                    if (!doc || doc.path !== openPath || doc.width !== w) {
-                        doc = { path: openPath, width: w, lines: renderMarkdown(source, w) };
+                    if (editing) {
+                        drawEditor(p, buffer, theme, w, h);
+                        return;
+                    }
+                    if (!doc || doc.path !== openPath || doc.width !== w || doc.stamp !== stamp || doc.spoilers !== spoilers) {
+                        doc = {
+                            path: openPath,
+                            width: w,
+                            stamp,
+                            spoilers,
+                            lines: renderMarkdown(bufferText(buffer), w, { flavor, spoilers }),
+                        };
                     }
                     scroll = clamp(scroll, 0, Math.max(0, doc.lines.length - h));
                     if (measured.total !== doc.lines.length || measured.h !== h) {
@@ -399,57 +626,145 @@ export async function run(options) {
                 });
             });
             screen.statusBar({
-                items: filtering
+                items: mode === "edit"
                     ? [
-                        { key: "type", label: "filter" },
-                        { key: "↵", label: "open" },
-                        { key: "esc", label: "clear" },
+                        { key: "esc", label: "preview" },
+                        { key: "^s", label: "save" },
+                        { key: "^z", label: "undo" },
+                        { key: "^k", label: "kill" },
+                        { key: "^g", label: "keys" },
                     ]
-                    : pane === "tree"
+                    : filtering
                         ? [
-                            { key: "↑↓", label: "move" },
+                            { key: "type", label: "filter" },
                             { key: "↵", label: "open" },
-                            { key: "←→", label: "fold" },
-                            { key: "/", label: "find" },
-                            { key: "tab", label: "reader" },
-                            { key: "?", label: "keys" },
-                            { key: "q", label: "quit" },
+                            { key: "esc", label: "clear" },
                         ]
-                        : [
-                            { key: "↑↓", label: "scroll" },
-                            { key: "spc", label: "page" },
-                            { key: "g/G", label: "ends" },
-                            { key: "tab", label: "files" },
-                            { key: "?", label: "keys" },
-                            { key: "q", label: "quit" },
-                        ],
+                        : pane === "tree"
+                            ? [
+                                { key: "↑↓", label: "move" },
+                                { key: "↵", label: "open" },
+                                { key: "←→", label: "fold" },
+                                { key: "/", label: "find" },
+                                { key: "tab", label: "reader" },
+                                { key: "?", label: "keys" },
+                                { key: "q", label: "quit" },
+                            ]
+                            : [
+                                { key: "↑↓", label: "scroll" },
+                                { key: "spc", label: "page" },
+                                { key: "e", label: "edit" },
+                                { key: "g/G", label: "ends" },
+                                { key: "tab", label: "files" },
+                                { key: "?", label: "keys" },
+                                { key: "q", label: "quit" },
+                            ],
                 right: [
                     { label: openPath ? (dirname(openRel) === "." ? basename(root) : dirname(openRel)) : basename(root) },
+                    { label: flavor, color: theme.muted },
                     { label: theme.name, color: theme.muted },
                 ],
             });
-            if (help) {
-                screen.modal({ title: " readm3 — keys ", width: 52, height: 18 }, (m) => {
-                    m.keyValues([
-                        { label: "↑ ↓  j k", value: "move / scroll" },
-                        { label: "→ ← l h", value: "expand / collapse" },
-                        { label: "enter", value: "open file" },
-                        { label: "tab", value: "switch pane" },
-                        { label: "space / b", value: "page down / up" },
-                        { label: "g / G", value: "top / bottom" },
-                        { label: "/", value: "filter files" },
-                        { label: "esc", value: "clear filter" },
-                        { label: "r", value: "rescan and reload" },
-                        { label: "[ ]", value: "sidebar width" },
-                        { label: "?", value: "this help" },
-                        { label: "q / ctrl+c", value: "quit" },
-                    ], { labelColor: theme.accent, labelWidth: 14 });
+            if (pending) {
+                screen.modal({ title: " unsaved changes ", width: 56, height: 9 }, (m) => {
+                    m.spacer(1);
+                    m.text(pending?.message ?? "", { fg: theme.foreground, align: "center", wrap: true });
+                    m.spacer(1);
+                    m.text("y to continue, any other key to stay", { fg: theme.muted, align: "center" });
+                    m.spacer("fill");
+                });
+            }
+            else if (help) {
+                screen.modal({ title: " readm3 — keys ", width: 56, height: 24 }, (m) => {
+                    m.keyValues(mode === "edit"
+                        ? [
+                            { label: "esc", value: "back to the preview" },
+                            { label: "ctrl+g", value: "this help" },
+                            { label: "ctrl+s", value: "save" },
+                            { label: "ctrl+z / ctrl+y", value: "undo / redo" },
+                            { label: "ctrl+k / ctrl+u", value: "kill to end / start" },
+                            { label: "ctrl+a / ctrl+e", value: "line start / end" },
+                            { label: "ctrl+← →", value: "by word" },
+                            { label: "ctrl+home/end", value: "top / bottom" },
+                            { label: "enter", value: "split, continuing a list" },
+                            { label: "tab", value: "indent two spaces" },
+                        ]
+                        : [
+                            { label: "↑ ↓  j k", value: "move / scroll" },
+                            { label: "→ ← l h", value: "expand / collapse" },
+                            { label: "enter", value: "open file" },
+                            { label: "e / i", value: "edit this file" },
+                            { label: "ctrl+s", value: "save" },
+                            { label: "tab", value: "switch pane" },
+                            { label: "space / b", value: "page down / up" },
+                            { label: "g / G", value: "top / bottom" },
+                            { label: "/", value: "filter files" },
+                            { label: "s", value: "reveal spoilers" },
+                            { label: "esc", value: "clear filter" },
+                            { label: "r", value: "rescan and reload" },
+                            { label: "[ ]", value: "sidebar width" },
+                            { label: "?", value: "this help" },
+                            { label: "q / ctrl+c", value: "quit" },
+                        ], { labelColor: theme.accent, labelWidth: 16 });
                     m.spacer(1);
                     m.text("Any key closes.", { fg: theme.muted, align: "center" });
                 });
             }
         });
     });
+    /**
+     * The raw buffer with a caret.
+     *
+     * Long lines scroll sideways rather than wrap: a caret inside a wrapped line
+     * cannot say honestly which column of the file it is in.
+     */
+    function drawEditor(p, ed, theme, w, h) {
+        const gutter = Math.max(3, String(ed.lines.length).length + 1);
+        const textWidth = Math.max(8, w - gutter - 1);
+        // Keep the caret on screen on both axes.
+        if (ed.row < editTop)
+            editTop = ed.row;
+        else if (ed.row >= editTop + h)
+            editTop = ed.row - h + 1;
+        editTop = clamp(editTop, 0, Math.max(0, ed.lines.length - 1));
+        const caretCol = displayCol(ed.lines[ed.row] ?? "", ed.col);
+        if (caretCol < editLeft)
+            editLeft = caretCol;
+        else if (caretCol >= editLeft + textWidth)
+            editLeft = caretCol - textWidth + 1;
+        editLeft = Math.max(0, editLeft);
+        for (let i = 0; i < h; i++) {
+            const row = editTop + i;
+            if (row >= ed.lines.length) {
+                p.text("", { height: 1 });
+                continue;
+            }
+            const line = expand(ed.lines[row]);
+            const shown = line.slice(editLeft, editLeft + textWidth);
+            const onCaretRow = row === ed.row;
+            const caretAt = caretCol - editLeft;
+            p.row({ height: 1 }, (r) => {
+                r.text(`${String(row + 1).padStart(gutter - 1)} `, {
+                    width: gutter,
+                    fg: onCaretRow ? theme.accent : theme.border,
+                });
+                if (!onCaretRow) {
+                    r.text(shown, { width: textWidth, fg: theme.foreground });
+                    return;
+                }
+                // Split the line so the caret cell can be painted on its own.
+                const before = shown.slice(0, caretAt);
+                const under = shown.slice(caretAt, caretAt + 1) || " ";
+                const after = shown.slice(caretAt + 1);
+                if (before)
+                    r.text(before, { width: stringWidth(before), fg: theme.foreground });
+                r.text(under, { width: Math.max(1, stringWidth(under)), fg: theme.background, bg: theme.cursor });
+                if (after)
+                    r.text(after, { width: stringWidth(after), fg: theme.foreground });
+                r.spacer("fill");
+            });
+        }
+    }
     await app.start();
 }
 //# sourceMappingURL=viewer.js.map