blots-editor 0.0.13 → 0.0.15

package/asset/language/en.json

@@ -15,5 +15,23 @@
   "editor.mode.normal": "NORMAL",
   "command.prompt": "Command",
   "command.unknown": "Unknown command: {cmd}",
-  "toolbar.fileTree": "File Tree"
+  "command.saveError": "Save failed",
+  "toolbar.fileTree": "File Tree",
+  "toolbar.save": "Save",
+  "toolbar.settings": "Settings",
+  "fileTree.scanning": "Scanning...",
+  "fileTree.noDir": "No directory",
+  "fileTree.fail": "Scan failed",
+  "fileTree.unsaved": "Unsaved changes",
+  "editor.setting.title": "Menu",
+  "editor.setting.openSetting": "Settings",
+  "editor.setting.exit": "Exit",
+  "confirm.save": "Save",
+  "confirm.discard": "Discard",
+  "confirm.cancel": "Cancel",
+  "settings.fileTreeRoot": "FileTree Root",
+  "settings.fileTreeRoot.startup": "Startup directory",
+  "settings.fileTreeRoot.custom": "Custom path",
+  "settings.ok": "OK",
+  "settings.cancel": "Cancel"
 }

package/asset/language/zh.json

@@ -15,5 +15,23 @@
   "editor.mode.normal": "普通",
   "command.prompt": "命令",
   "command.unknown": "未知命令：{cmd}",
-  "toolbar.fileTree": "文件树"
+  "command.saveError": "保存失败",
+  "toolbar.fileTree": "文件树",
+  "toolbar.save": "保存",
+  "toolbar.settings": "设置",
+  "fileTree.scanning": "正在扫描...",
+  "fileTree.noDir": "没有目录",
+  "fileTree.fail": "扫描失败",
+  "fileTree.unsaved": "未保存的更改",
+  "editor.setting.title": "菜单",
+  "editor.setting.openSetting": "设置",
+  "editor.setting.exit": "退出",
+  "confirm.save": "保存",
+  "confirm.discard": "丢弃",
+  "confirm.cancel": "取消",
+  "settings.fileTreeRoot": "文件树根目录",
+  "settings.fileTreeRoot.startup": "启动目录",
+  "settings.fileTreeRoot.custom": "自定义路径",
+  "settings.ok": "确定",
+  "settings.cancel": "取消"
 }

package/dist/core/document/document.d.ts

@@ -26,6 +26,19 @@ export declare class Document {
     /** Snapshot of all line texts (for rendering; internally the model is `TextLine[]`). */
     get lines(): string[];
     getLine(i: number): string;
+    /**
+     * The full document text with normalized LF line endings — the inverse
+     * of the constructor's `split(/\r?\n/)`, so text → document → text is
+     * lossless. Used for saving and dirty-hash comparison.
+     */
+    get text(): string;
+    /**
+     * Replace the whole content (used when opening a file). Resets the
+     * cursor and scroll state; the wrap width is view-configured and
+     * untouched. The `Document` instance stays stable, so controllers and
+     * bindings that hold it keep working.
+     */
+    setText(text: string): void;
     get cursor(): CursorState;
     get scrollTop(): number;
     /** Soft-wrap width in terminal cells; `Infinity` disables wrapping. */
@@ -46,6 +59,7 @@ export declare class Document {
         start: number;
         end: number;
         first: boolean;
+        text: string;
     } | null;
     /** Global visual line the cursor sits on. */
     get cursorVisualLine(): number;

package/dist/core/document/document.js

@@ -36,6 +36,27 @@ export class Document {
     getLine(i) {
         return this._lines[i].text;
     }
+    /**
+     * The full document text with normalized LF line endings — the inverse
+     * of the constructor's `split(/\r?\n/)`, so text → document → text is
+     * lossless. Used for saving and dirty-hash comparison.
+     */
+    get text() {
+        return this._lines.map((l) => l.text).join("\n");
+    }
+    /**
+     * Replace the whole content (used when opening a file). Resets the
+     * cursor and scroll state; the wrap width is view-configured and
+     * untouched. The `Document` instance stays stable, so controllers and
+     * bindings that hold it keep working.
+     */
+    setText(text) {
+        this._lines = text.split(/\r?\n/).map((t) => new TextLine(t));
+        this._cursor = { line: 0, logical: 0 };
+        this._scrollTop = 0;
+        this._viewScrollTop = null;
+        this._scrollRemainder = 0;
+    }
     get cursor() {
         const line = this._lines[this._cursor.line];
         return {
@@ -59,14 +80,14 @@ export class Document {
     lineSegments(line) {
         const tl = this._lines[line];
         if (tl.text.length === 0) {
-            return [{ start: 0, end: 0 }];
+            return [{ start: 0, end: 0, text: "" }];
         }
         const segs = [];
         let segVisual = 0;
         let segStart = 0;
         while (segStart < tl.text.length) {
             const seg = tl.segmentFrom(segVisual, this._wrapWidth);
-            segs.push({ start: segStart, end: seg.endLogical });
+            segs.push({ start: segStart, end: seg.endLogical, text: seg.text });
             if (seg.text === "") {
                 break;
             }
@@ -101,6 +122,7 @@ export class Document {
                     start: segs[remaining].start,
                     end: segs[remaining].end,
                     first: remaining === 0,
+                    text: segs[remaining].text,
                 };
             }
             remaining -= segs.length;

package/dist/core/document/text-line.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Tab stop used for display width and tab expansion. Tabs are expanded by
+ * the editor (see {@link expandTabs}) so the rendered text is plain spaces —
+ * this keeps Ink's internal layout, the terminal paint, and the width math
+ * identical, which raw tabs would break (string-width counts a tab as one
+ * cell while terminals jump to the next tab stop). 4 matches the common
+ * editor default.
+ */
+export declare const TAB_STOP = 4;
+/**
+ * Expand tabs to spaces aligned to `startColumn`'s tab stops. This is what
+ * gets rendered (and what segment widths are computed against), so raw tabs
+ * never reach the terminal.
+ */
+export declare function expandTabs(text: string, startColumn?: number): string;
 /**
  * A single line of text with its terminal width cached.
  *
@@ -6,7 +21,7 @@
  * the same prefix at the middle index — the cursor never sits inside a
  * surrogate pair, but aligning the array to code units lets `visualAt` /
  * `logicalAt` use direct indexing and binary search instead of per-character
- * scans on every call.
+ * scans on every call. Tabs are column-relative (width to the next stop).
  */
 export declare class TextLine {
     readonly text: string;

package/dist/core/document/text-line.js

@@ -1,4 +1,35 @@
 import stringWidth from "string-width";
+/**
+ * Tab stop used for display width and tab expansion. Tabs are expanded by
+ * the editor (see {@link expandTabs}) so the rendered text is plain spaces —
+ * this keeps Ink's internal layout, the terminal paint, and the width math
+ * identical, which raw tabs would break (string-width counts a tab as one
+ * cell while terminals jump to the next tab stop). 4 matches the common
+ * editor default.
+ */
+export const TAB_STOP = 4;
+/** Width of one character at the given column; a tab jumps to the next stop. */
+function charWidth(ch, col) {
+    if (ch === "\t") {
+        return TAB_STOP - (col % TAB_STOP);
+    }
+    return stringWidth(ch);
+}
+/**
+ * Expand tabs to spaces aligned to `startColumn`'s tab stops. This is what
+ * gets rendered (and what segment widths are computed against), so raw tabs
+ * never reach the terminal.
+ */
+export function expandTabs(text, startColumn = 0) {
+    let col = startColumn;
+    let out = "";
+    for (const ch of text) {
+        const w = charWidth(ch, col);
+        out += ch === "\t" ? " ".repeat(w) : ch;
+        col += w;
+    }
+    return out;
+}
 /**
  * A single line of text with its terminal width cached.
  *
@@ -7,7 +38,7 @@ import stringWidth from "string-width";
  * the same prefix at the middle index — the cursor never sits inside a
  * surrogate pair, but aligning the array to code units lets `visualAt` /
  * `logicalAt` use direct indexing and binary search instead of per-character
- * scans on every call.
+ * scans on every call. Tabs are column-relative (width to the next stop).
  */
 export class TextLine {
     text;
@@ -19,7 +50,8 @@ export class TextLine {
         let sum = 0;
         for (let i = 0; i < text.length;) {
             const cp = text.codePointAt(i);
-            const w = stringWidth(String.fromCodePoint(cp));
+            const ch = String.fromCodePoint(cp);
+            const w = charWidth(ch, sum);
             const units = cp > 0xffff ? 2 : 1;
             for (let k = 0; k < units; k++) {
                 prefix.push(sum + w);
@@ -83,7 +115,8 @@ export class TextLine {
             end = start + (this.text.codePointAt(start) > 0xffff ? 2 : 1);
         }
         return {
-            text: this.text.slice(start, end),
+            // Tabs expanded so the caller can render the segment verbatim.
+            text: expandTabs(this.text.slice(start, end), startVisualActual),
             endVisual: this.visualAt(end),
             endLogical: end,
         };

package/dist/core/io/file-tree-model.d.ts

@@ -0,0 +1,49 @@
+import type { FileTreeSettings } from "../settings/schema.js";
+/** Clear the scan cache (refresh button, tests). */
+export declare function clearFileTreeCache(): void;
+export type FileTreeState = {
+    ok: true;
+    node: FileNode;
+    path: string;
+} | {
+    fail: true;
+} | {
+    scanning: true;
+};
+/** Scan a directory, serving repeat calls for the same root from the cache. */
+export declare function scanDirectoryCached(root: string): Promise<FileTreeState>;
+/** One entry of the scanned tree. Directories carry their children. */
+export type FileNode = {
+    /** Entry name (not the full path). */
+    name: string;
+    /** Absolute path. */
+    path: string;
+    isDir: boolean;
+    /** Children of a directory; undefined for files. */
+    children?: FileNode[];
+};
+/** Expand a leading `~` to the user's home directory. */
+export declare function expandHome(path: string): string;
+/** Resolve the file-tree root from settings: startup dir or custom path. */
+export declare function resolveFileTreeRoot(settings: FileTreeSettings, startupDir: string): string | null;
+/**
+ * Recursively scan a directory into a tree. Symlinks are never followed
+ * (they can loop), dotfiles and known dependency/VCS dirs are skipped.
+ * Directories sort before files, both alphabetically.
+ *
+ * @returns The root node, or null when the directory cannot be read.
+ */
+export declare function scanDirectory(root: string): Promise<FileNode | null>;
+/** One visible tree row produced by flattening with expansion state. */
+export type TreeRow = {
+    node: FileNode;
+    /** Indentation depth (root = 0). */
+    depth: number;
+};
+/**
+ * Flatten the tree into the rows to render: children of expanded directories
+ * appear under their parent, collapsed subtrees are omitted.
+ */
+export declare function flattenTree(root: FileNode, expanded: ReadonlySet<string>): TreeRow[];
+/** Expand a directory, or collapse it when already expanded. */
+export declare function toggleExpanded(expanded: Set<string>, path: string): void;

package/dist/core/io/file-tree-model.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs/promises';
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Scan cache: large directories take a while to recurse, and the file tree
+ * is re-scanned on every open. Once scanned, a root is served from the cache
+ * forever — refreshing the tree is an explicit action (`clearFileTreeCache`
+ * via the tree's refresh button), not a time-based expiry.
+ */
+const scanCache = new Map();
+/** Clear the scan cache (refresh button, tests). */
+export function clearFileTreeCache() {
+    scanCache.clear();
+}
+/** Scan a directory, serving repeat calls for the same root from the cache. */
+export async function scanDirectoryCached(root) {
+    const hit = scanCache.get(root);
+    if (hit) {
+        return {
+            ok: true,
+            node: hit,
+            path: root
+        };
+    }
+    const tree = await scanDirectory(root);
+    if (tree) {
+        scanCache.set(root, tree);
+        return {
+            ok: true,
+            node: tree,
+            path: root
+        };
+    }
+    return {
+        fail: true
+    };
+}
+/** Directories skipped at every depth (dependency dirs, VCS internals). */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".next", ".cache"]);
+/** Any entry starting with "." is hidden (dotfiles) and skipped. */
+const isHidden = (name) => name.startsWith(".");
+/** Expand a leading `~` to the user's home directory. */
+export function expandHome(path) {
+    return path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+/** Resolve the file-tree root from settings: startup dir or custom path. */
+export function resolveFileTreeRoot(settings, startupDir) {
+    if (settings.root === "custom") {
+        const custom = expandHome(settings.customPath.trim());
+        return custom.length > 0 ? custom : null;
+    }
+    return startupDir;
+}
+/**
+ * Recursively scan a directory into a tree. Symlinks are never followed
+ * (they can loop), dotfiles and known dependency/VCS dirs are skipped.
+ * Directories sort before files, both alphabetically.
+ *
+ * @returns The root node, or null when the directory cannot be read.
+ */
+export async function scanDirectory(root) {
+    const entries = await readDirSafe(root);
+    if (!entries) {
+        return null;
+    }
+    const nodes = [];
+    for (const entry of entries) {
+        const name = entry.name;
+        if (isHidden(name) || entry.isSymbolicLink()) {
+            continue;
+        }
+        const path = join(root, name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(name)) {
+                continue;
+            }
+            nodes.push({ name, path, isDir: true, children: await scanChildren(path) });
+        }
+        else if (entry.isFile()) {
+            nodes.push({ name, path, isDir: false });
+        }
+    }
+    // Code-unit compare, not localeCompare: deterministic across locales
+    // (localeCompare reorders by the host's locale).
+    nodes.sort((a, b) => a.isDir === b.isDir ? (a.name < b.name ? -1 : a.name > b.name ? 1 : 0) : a.isDir ? -1 : 1);
+    return { name: root, path: root, isDir: true, children: nodes };
+}
+async function scanChildren(dir) {
+    const child = await scanDirectory(dir);
+    return child?.children;
+}
+/** Read a directory without throwing; null when unreadable (EACCES etc.). */
+async function readDirSafe(path) {
+    try {
+        return await fs.readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Flatten the tree into the rows to render: children of expanded directories
+ * appear under their parent, collapsed subtrees are omitted.
+ */
+export function flattenTree(root, expanded) {
+    const rows = [];
+    const walk = (node, depth) => {
+        rows.push({ node, depth });
+        if (node.isDir && node.children && expanded.has(node.path)) {
+            for (const child of node.children) {
+                walk(child, depth + 1);
+            }
+        }
+    };
+    // The root itself is never rendered (it is the pane's title area).
+    for (const child of root.children ?? []) {
+        walk(child, 1);
+    }
+    return rows;
+}
+/** Expand a directory, or collapse it when already expanded. */
+export function toggleExpanded(expanded, path) {
+    if (expanded.has(path)) {
+        expanded.delete(path);
+    }
+    else {
+        expanded.add(path);
+    }
+}

package/dist/core/io/session.d.ts

@@ -0,0 +1,58 @@
+import { EditorController, type EditorOptions } from "../editor-controller.js";
+export type ActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Transient status message shown in the information bar. */
+export type SessionMessage = {
+    /** Display text (already localized where applicable). */
+    text: string;
+    kind: "success" | "error";
+};
+type SessionListener = () => void;
+/**
+ * File-session coordinator shared by the editor, file tree, and toolbar.
+ *
+ * Owns the single open document (via an {@link EditorController}), the path
+ * it was loaded from, and the saved-content hash used for the dirty check.
+ * All file I/O happens here; components only call `open` / `save` and react
+ * to `onChange`. The dirty check compares the current document text against
+ * the hash of the last saved content (node `crypto` sha256), so a stray
+ * formatting change never needs manual dirty bookkeeping.
+ *
+ * An instance is created per editor mount (see `Editor`) and passed to the
+ * layer elements — the file tree, toolbar, and command bar all receive it
+ * via props.
+ */
+export declare class EditorSession {
+    private readonly _controller;
+    private _filePath;
+    /** Hash of the content last written to `_filePath`; null while untitled. */
+    private _savedHash;
+    private _message;
+    private readonly _listeners;
+    constructor(initialText?: string, options?: EditorOptions);
+    get controller(): EditorController;
+    /** Absolute path of the open file, or null for the untitled buffer. */
+    get filePath(): string | null;
+    /** File name for display; `[untitled]` when no file is open. */
+    get displayName(): string;
+    /** Last operation message (save result, open error), or null. */
+    get message(): SessionMessage | null;
+    /** True when the buffer differs from the saved content of its file. */
+    isDirty(): boolean;
+    onChange(listener: SessionListener): () => void;
+    /**
+     * Load a file into the buffer, replacing the previous document. The
+     * buffer becomes clean (hash of the just-read content).
+     */
+    open(filePath: string): ActionResult;
+    /** Write the buffer to the open file, clearing the dirty state. */
+    save(): ActionResult;
+    private hash;
+    private fail;
+    private _notify;
+}
+export {};

package/dist/core/io/session.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { EditorController } from "../editor-controller.js";
+/**
+ * File-session coordinator shared by the editor, file tree, and toolbar.
+ *
+ * Owns the single open document (via an {@link EditorController}), the path
+ * it was loaded from, and the saved-content hash used for the dirty check.
+ * All file I/O happens here; components only call `open` / `save` and react
+ * to `onChange`. The dirty check compares the current document text against
+ * the hash of the last saved content (node `crypto` sha256), so a stray
+ * formatting change never needs manual dirty bookkeeping.
+ *
+ * An instance is created per editor mount (see `Editor`) and passed to the
+ * layer elements — the file tree, toolbar, and command bar all receive it
+ * via props.
+ */
+export class EditorSession {
+    _controller;
+    _filePath = null;
+    /** Hash of the content last written to `_filePath`; null while untitled. */
+    _savedHash = null;
+    _message = null;
+    _listeners = new Set();
+    constructor(initialText = "", options = {}) {
+        this._controller = new EditorController(initialText, options);
+    }
+    get controller() {
+        return this._controller;
+    }
+    /** Absolute path of the open file, or null for the untitled buffer. */
+    get filePath() {
+        return this._filePath;
+    }
+    /** File name for display; `[untitled]` when no file is open. */
+    get displayName() {
+        return this._filePath ? basename(this._filePath) : "[untitled]";
+    }
+    /** Last operation message (save result, open error), or null. */
+    get message() {
+        return this._message;
+    }
+    /** True when the buffer differs from the saved content of its file. */
+    isDirty() {
+        if (this._filePath === null || this._savedHash === null) {
+            return false;
+        }
+        return this.hash(this._controller.document.text) !== this._savedHash;
+    }
+    onChange(listener) {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    /**
+     * Load a file into the buffer, replacing the previous document. The
+     * buffer becomes clean (hash of the just-read content).
+     */
+    open(filePath) {
+        let text;
+        try {
+            text = readFileSync(filePath, "utf8");
+        }
+        catch (err) {
+            return this.fail(err);
+        }
+        // NUL bytes mark binary content — refuse it instead of rendering garbage.
+        if (text.includes("\0")) {
+            this._message = { text: "Binary file", kind: "error" };
+            this._notify();
+            return { ok: false, error: "Binary file" };
+        }
+        this._controller.document.setText(text);
+        this._filePath = filePath;
+        // Hash the NORMALIZED document text, not the raw disk bytes: the
+        // document normalizes CRLF to LF, so hashing the raw text would
+        // flag every CRLF file as dirty on open.
+        this._savedHash = this.hash(this._controller.document.text);
+        this._message = null;
+        this._notify();
+        return { ok: true };
+    }
+    /** Write the buffer to the open file, clearing the dirty state. */
+    save() {
+        if (this._filePath === null) {
+            this._message = { text: "No file open", kind: "error" };
+            this._notify();
+            return { ok: false, error: "No file open" };
+        }
+        const text = this._controller.document.text;
+        try {
+            writeFileSync(this._filePath, text, "utf8");
+        }
+        catch (err) {
+            return this.fail(err);
+        }
+        this._savedHash = this.hash(text);
+        this._message = { text: "Saved", kind: "success" };
+        this._notify();
+        return { ok: true };
+    }
+    hash(text) {
+        return createHash("sha256").update(text).digest("hex");
+    }
+    fail(err) {
+        const error = err instanceof Error ? err.message : String(err);
+        this._message = { text: error, kind: "error" };
+        this._notify();
+        return { ok: false, error };
+    }
+    _notify() {
+        this._listeners.forEach((fn) => fn());
+    }
+}

package/dist/core/settings/schema.d.ts

@@ -9,15 +9,28 @@ import { z } from "zod";
  */
 /** Wheel sensitivity in visual lines per notch, 1.0–10.0, 0.5 steps. */
 export declare const sensitivitySchema: z.ZodDefault<z.ZodNumber>;
+/** File-tree root source: the process startup directory or a custom path. */
+export declare const fileTreeRootSchema: z.ZodDefault<z.ZodEnum<{
+    startup: "startup";
+    custom: "custom";
+}>>;
 export declare const settingsSchema: z.ZodObject<{
     language: z.ZodDefault<z.ZodString>;
     wheel: z.ZodDefault<z.ZodObject<{
         cursor: z.ZodDefault<z.ZodNumber>;
         view: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    fileTree: z.ZodDefault<z.ZodObject<{
+        root: z.ZodDefault<z.ZodEnum<{
+            startup: "startup";
+            custom: "custom";
+        }>>;
+        customPath: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type EditorSettings = z.infer<typeof settingsSchema>;
 export type WheelSensitivity = EditorSettings["wheel"];
+export type FileTreeSettings = EditorSettings["fileTree"];
 export declare const DEFAULT_SETTINGS: EditorSettings;
 /** Parse an unknown persisted value, falling back to defaults on any failure. */
 export declare function parseSettings(raw: unknown): EditorSettings;

package/dist/core/settings/schema.js

@@ -15,6 +15,8 @@ export const sensitivitySchema = z
     .step(0.5)
     .default(1);
 const DEFAULT_WHEEL = { cursor: 1, view: 3 };
+/** File-tree root source: the process startup directory or a custom path. */
+export const fileTreeRootSchema = z.enum(["startup", "custom"]).default("startup");
 export const settingsSchema = z.object({
     /** Persisted UI language (validated at the app layer; unknown codes fall back). */
     language: z.string().min(1).default("en"),
@@ -26,10 +28,19 @@ export const settingsSchema = z.object({
         view: sensitivitySchema,
     })
         .default(DEFAULT_WHEEL),
+    fileTree: z
+        .object({
+        /** Which directory the file tree scans: startup dir or `customPath`. */
+        root: fileTreeRootSchema,
+        /** Absolute path scanned when `root` is "custom"; ignored otherwise. */
+        customPath: z.string().default(""),
+    })
+        .default({ root: "startup", customPath: "" }),
 });
 export const DEFAULT_SETTINGS = {
     language: "en",
     wheel: DEFAULT_WHEEL,
+    fileTree: { root: "startup", customPath: "" },
 };
 /** Parse an unknown persisted value, falling back to defaults on any failure. */
 export function parseSettings(raw) {

package/dist/core/settings/useSettings.d.ts

@@ -16,6 +16,8 @@ export type SettingsApi = {
     commit: () => void;
     /** Persist the UI language (called alongside the i18n `setLanguage`). */
     setLanguage: (code: string) => void;
+    /** Persist the file-tree root settings. */
+    setFileTree: (fileTree: EditorSettings["fileTree"]) => void;
 };
 /**
  * React binding for the shared {@link settingsStore}. Re-renders subscribers