@kupcad/files 0.0.0-stage → 0.1.4

package/src/menu.js

@@ -0,0 +1,41 @@
+// The menu of a row of a project's tree, and of the tree itself, as data a host draws: as a
+// native menu (the desktop app's), or as a page's (ContextMenu.svelte).
+
+/** @import { Entry } from './tree.js' */
+
+/**
+ * An item of a menu: what it says and does, or a separator.
+ * @typedef {{ text: string, action: () => void } | '-'} MenuItem
+ */
+
+/**
+ * What a row's menu does. Uploading and downloading are a browser's: its files are in no folder
+ * of the person's own.
+ * @typedef {object} RowActions
+ * @property {() => void} newScript
+ * @property {() => void} newFolder
+ * @property {() => void} rename
+ * @property {() => void} remove
+ * @property {() => void} [upload] puts the person's files in the row's folder
+ * @property {() => void} [download] saves the row's file to the person's
+ */
+
+/** @param {string} text @param {() => void} action @returns {MenuItem} */
+const item = (text, action) => ({ text, action });
+
+/**
+ * The menu of a row of the tree (`entry`), or of the tree itself (none): what can be made in
+ * its folder, and what can be done to it (a folder isn't downloaded).
+ * @param {Entry | null} entry
+ * @param {RowActions} actions
+ * @param {{ remove?: string }} [labels] what removing says: Move to Trash where the system has one
+ * @returns {MenuItem[]}
+ */
+export function rowMenu(entry, actions, { remove = 'Delete…' } = {}) {
+  const make = [item('New Script', actions.newScript), item('New Folder', actions.newFolder)];
+  if (actions.upload) make.push(item('Upload Files…', actions.upload));
+  if (!entry) return make;
+  const download =
+    actions.download && entry.kind !== 'folder' ? [item('Download', actions.download)] : [];
+  return [...make, '-', ...download, item('Rename…', actions.rename), item(remove, actions.remove)];
+}

package/src/scripts.svelte.js

@@ -0,0 +1,226 @@
+// The scripts a host read, by their paths: each one's text now and as the disk (whatever keeps
+// them) had it when it was last read or saved, for what is unsaved, and its editor's snapshot
+// (its undo history) while another is shown. The disk is read again when the host says a file
+// changed, or the window is back (`check`): a script with no unsaved changes takes the disk's
+// text; one with them keeps its own, the disk's held as a conflict for the person to choose
+// (`resolve`); one gone from the disk is dropped, or kept, unsaved, where it has changes. A save
+// that finds the disk changed since writes nothing unless told to (`overwrite`): nothing
+// someone else wrote is lost unasked.
+
+import { SvelteMap } from 'svelte/reactivity';
+import { within } from './tree.js';
+
+/**
+ * What the scripts are read and written with.
+ * @typedef {object} ScriptFiles
+ * @property {(path: string) => Promise<string>} read
+ * @property {(path: string, text: string) => Promise<void>} write
+ * @property {(path: string) => Promise<boolean>} exists
+ */
+
+/**
+ * A script read: its text now, and the disk's when it was last read or saved (null: gone from
+ * the disk since).
+ * @typedef {{ text: string, saved: string | null }} Held
+ */
+
+export class Scripts {
+  /** @type {SvelteMap<string, Held>} */
+  #held = new SvelteMap();
+  /**
+   * The disk's text of each script it changed under unsaved changes (null: it was removed), until
+   * the person chooses.
+   * @type {SvelteMap<string, string | null>}
+   */
+  conflicts = new SvelteMap();
+  /** Each script's editor as it was left, its undo history with it (Editor's `snapshot()`). */
+  #snapshots = new Map();
+  /** The paths being written: what the disk says of one meanwhile is the save's. */
+  #writing = new Set();
+  /** @type {ScriptFiles} */
+  #files;
+
+  /** The paths of the scripts whose text isn't the disk's. */
+  unsaved = $derived(
+    new Set([...this.#held].filter(([, held]) => held.text !== held.saved).map(([path]) => path)),
+  );
+
+  /** @param {ScriptFiles} files */
+  constructor(files) {
+    this.#files = files;
+  }
+
+  /** @param {string} path */
+  has(path) {
+    return this.#held.has(path);
+  }
+
+  /** The script's text now; none for one not read. @param {string} path */
+  text(path) {
+    return this.#held.get(path)?.text ?? '';
+  }
+
+  /**
+   * The script at `path`, read from the disk unless it was: its text.
+   * @param {string} path
+   */
+  async read(path) {
+    if (!this.#held.has(path)) {
+      const text = await this.#files.read(path);
+      if (!this.#held.has(path)) this.#held.set(path, { text, saved: text });
+    }
+    return this.text(path);
+  }
+
+  /**
+   * The person changed the script at `path` to `text`.
+   * @param {string} path
+   * @param {string} text
+   */
+  edit(path, text) {
+    const held = this.#held.get(path);
+    if (held) this.#held.set(path, { text, saved: held.saved });
+  }
+
+  /**
+   * Writes the script at `path`; if the disk changed since it was read or saved, nothing unless
+   * `overwrite`, the disk's text held as a conflict.
+   * @param {string} path
+   * @param {{ overwrite?: boolean }} [options]
+   * @returns {Promise<'saved' | 'changed'>}
+   */
+  async save(path, { overwrite = false } = {}) {
+    const held = this.#held.get(path);
+    if (!held) return 'saved';
+    const { text } = held;
+    this.#writing.add(path);
+    try {
+      if (!overwrite && held.saved !== null) {
+        const disk = await this.#onDisk(path);
+        if (disk !== null && disk !== held.saved && disk !== text) {
+          this.conflicts.set(path, disk);
+          return 'changed';
+        }
+      }
+      await this.#files.write(path, text);
+    } finally {
+      this.#writing.delete(path);
+    }
+    // What was typed while it was written stays, unsaved
+    this.#held.set(path, { text: this.#held.get(path)?.text ?? text, saved: text });
+    this.conflicts.delete(path);
+    return 'saved';
+  }
+
+  /**
+   * Reads each script again as the disk has it now: a change of the disk's under none of the
+   * person's is taken, under theirs held as a conflict; a script gone from the disk is dropped,
+   * or kept, unsaved. One the disk can't be read for is left as it is.
+   * @returns {Promise<string[]>} the paths dropped
+   */
+  async check() {
+    /** @type {string[]} */
+    const dropped = [];
+    for (const path of this.#held.keys()) {
+      if (this.#writing.has(path)) continue;
+      let disk;
+      try {
+        disk = await this.#onDisk(path);
+      } catch {
+        continue;
+      }
+      const held = this.#held.get(path);
+      if (!held || this.#writing.has(path) || disk === held.saved) continue;
+      if (disk === null && held.text === held.saved) {
+        this.drop(path);
+        dropped.push(path);
+      } else if (disk === null) {
+        this.#held.set(path, { text: held.text, saved: null });
+        this.conflicts.set(path, null);
+      } else if (held.text === held.saved || held.text === disk) {
+        this.#held.set(path, { text: disk, saved: disk });
+        this.conflicts.delete(path);
+      } else {
+        this.conflicts.set(path, disk);
+      }
+    }
+    return dropped;
+  }
+
+  /**
+   * The person's choice for the script at `path`, which the disk changed under their changes:
+   * the disk's text (for one removed, the script dropped), or theirs, which the next save writes
+   * over the disk's (or back, for one removed).
+   * @param {string} path
+   * @param {'disk' | 'mine'} keep
+   */
+  resolve(path, keep) {
+    const disk = this.conflicts.get(path);
+    const held = this.#held.get(path);
+    if (disk === undefined || !held) return;
+    this.conflicts.delete(path);
+    if (keep === 'mine') this.#held.set(path, { text: held.text, saved: disk });
+    else if (disk === null) this.drop(path);
+    else this.#held.set(path, { text: disk, saved: disk });
+  }
+
+  /**
+   * Keeps the snapshot of the script's editor, its undo history with it, while another is shown.
+   * @param {string} path
+   * @param {unknown} snapshot
+   */
+  keep(path, snapshot) {
+    this.#snapshots.set(path, snapshot);
+  }
+
+  /** The snapshot of the script's editor, as it was left; none for one not left. @param {string} path */
+  snapshot(path) {
+    return this.#snapshots.get(path);
+  }
+
+  /**
+   * Moves what is held of the scripts at or under `from` to `to`, as the person renamed it.
+   * @param {string} from
+   * @param {string} to
+   */
+  rename(from, to) {
+    for (const map of [this.#held, this.conflicts, this.#snapshots]) {
+      // A copy: renaming adds to what is iterated
+      for (const [path, value] of Array.from(map)) {
+        if (!within(path, from)) continue;
+        map.delete(path);
+        map.set(to + path.slice(from.length), value);
+      }
+    }
+  }
+
+  /**
+   * Forgets the scripts at or under `path`, unsaved changes and all.
+   * @param {string} path
+   */
+  drop(path) {
+    for (const map of [this.#held, this.conflicts, this.#snapshots]) {
+      for (const held of map.keys()) if (within(held, path)) map.delete(held);
+    }
+  }
+
+  /** Forgets every script: another folder is opened. */
+  clear() {
+    this.#held.clear();
+    this.conflicts.clear();
+    this.#snapshots.clear();
+  }
+
+  /**
+   * The disk's text of `path`; null where it is gone.
+   * @param {string} path
+   */
+  async #onDisk(path) {
+    try {
+      return await this.#files.read(path);
+    } catch (error) {
+      if (await this.#files.exists(path).catch(() => true)) throw error;
+      return null;
+    }
+  }
+}

package/src/tree.js

@@ -0,0 +1,197 @@
+// A project's files as a tree, whatever keeps them (the disk, a browser's private file system):
+// its folders, scripts and the files they read, listed through the host's `readDir`, which of
+// them a tree shows with some folders closed, the names a new entry may take, and the paths of
+// entries in folders. A path is the host's: `/` or `\` between its names.
+
+/** What a script reads as data: a mesh, a drawing, a JSON file, a font. */
+export const DATA_EXTENSIONS = new Set([
+  'json',
+  'stl',
+  'obj',
+  '3mf',
+  'step',
+  'stp',
+  'svg',
+  'dxf',
+  'ttf',
+  'otf',
+]);
+export const SCRIPT_EXTENSION = 'kup';
+/** Folders that hold no file of the user's: hidden ones (.git, .kupcad's packages) and build output. */
+export const SKIPPED_FOLDER = /^\.|^node_modules$|^target$/;
+/** A folder with more files than this is no project: the list stops there. */
+export const MAX_ENTRIES = 5000;
+
+/**
+ * An entry of the folder's tree, in the order it is shown: a folder before what is in it.
+ * @typedef {object} Entry
+ * @property {'folder' | 'script' | 'data'} kind
+ * @property {string} name
+ * @property {string} path
+ * @property {number} depth how many folders down it is
+ */
+
+/**
+ * An entry of a folder, as the host's `readDir` gives it.
+ * @typedef {object} DirEntry
+ * @property {string} name
+ * @property {boolean} isDirectory
+ * @property {boolean} isFile
+ * @property {boolean} [isSymlink]
+ */
+
+/** @typedef {{ readDir: (path: string) => Promise<DirEntry[]> }} DirReader */
+
+/**
+ * The tree of `root`: its folders, scripts and data files, each folder's entries by name (its
+ * folders first), at most MAX_ENTRIES. A folder holding files but none of these is left out;
+ * an empty one (made a moment ago, for what goes in it) is not.
+ * @param {string} root
+ * @param {DirReader} fs
+ * @returns {Promise<Entry[]>}
+ */
+export async function listFolder(root, fs) {
+  /** @type {Entry[]} */
+  const entries = [];
+  /**
+   * @param {string} dir
+   * @param {number} depth
+   * @returns {Promise<boolean>} whether it is shown: it holds anything listed, or nothing at all
+   */
+  const walk = async (dir, depth) => {
+    const children = (await fs.readDir(dir)).toSorted(
+      (a, b) => Number(b.isDirectory) - Number(a.isDirectory) || a.name.localeCompare(b.name),
+    );
+    let any = false;
+    for (const child of children) {
+      if (entries.length >= MAX_ENTRIES) return any;
+      const path = childPath(dir, child.name);
+      if (child.isDirectory) {
+        if (SKIPPED_FOLDER.test(child.name) || child.isSymlink) continue;
+        const at = entries.push({ kind: 'folder', name: child.name, path, depth }) - 1;
+        if (await walk(path, depth + 1)) any = true;
+        else entries.splice(at);
+      } else if (child.isFile) {
+        const kind = kindOf(child.name);
+        if (!kind) continue;
+        entries.push({ kind, name: child.name, path, depth });
+        any = true;
+      }
+    }
+    return any || children.length === 0;
+  };
+  await walk(root, 0);
+  return entries;
+}
+
+/**
+ * The entries a tree shows with the folders in `collapsed` closed: a closed folder's row, and
+ * nothing of what is under it.
+ * @param {Entry[]} entries
+ * @param {ReadonlySet<string>} collapsed the closed folders' paths
+ * @returns {Entry[]}
+ */
+export function shownEntries(entries, collapsed) {
+  /** @type {Entry[]} */
+  const shown = [];
+  // The depth of the closed folder whose entries are being passed over
+  let closed = Infinity;
+  for (const entry of entries) {
+    if (entry.depth > closed) continue;
+    closed = Infinity;
+    shown.push(entry);
+    if (entry.kind === 'folder' && collapsed.has(entry.path)) closed = entry.depth;
+  }
+  return shown;
+}
+
+/**
+ * The folders the entry at `path` is in, the outermost first: in the tree's order, the nearest
+ * entry before it at each depth above its own. None for one the tree doesn't hold.
+ * @param {Entry[]} entries
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function foldersAbove(entries, path) {
+  const at = entries.findIndex((entry) => entry.path === path);
+  if (at < 0) return [];
+  /** @type {string[]} */
+  const above = [];
+  let depth = entries[at].depth;
+  for (let i = at - 1; i >= 0 && depth > 0; i--) {
+    if (entries[i].depth < depth) {
+      above.unshift(entries[i].path);
+      depth = entries[i].depth;
+    }
+  }
+  return above;
+}
+
+/**
+ * What a file is to KupCAD, by its extension: a script, data a script reads, or nothing.
+ * @param {string} name
+ * @returns {'script' | 'data' | null}
+ */
+export function kindOf(name) {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return null;
+  const extension = name.slice(dot + 1).toLowerCase();
+  if (extension === SCRIPT_EXTENSION) return 'script';
+  return DATA_EXTENSIONS.has(extension) ? 'data' : null;
+}
+
+/**
+ * What is wrong with `name` as a new entry's, or null: one the system takes in any folder, not
+ * one the tree leaves out (a hidden one).
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function nameProblem(name) {
+  if (name.trim() === '') return 'A name is needed.';
+  if (name !== name.trim()) return 'A name may not start or end with a space.';
+  if (/[\\/:*?"<>|]/.test(name) || /\p{Cc}/u.test(name)) {
+    return 'A name may not have any of \\ / : * ? " < > |.';
+  }
+  if (name.startsWith('.'))
+    return "A name starting with a dot is hidden: the tree wouldn't show it.";
+  return null;
+}
+
+/**
+ * The name a new script takes for `name`: with its extension, which the tree knows it by.
+ * @param {string} name
+ */
+export function scriptName(name) {
+  return kindOf(name) === 'script' ? name : `${name}.${SCRIPT_EXTENSION}`;
+}
+
+/**
+ * The folder `path` is in.
+ * @param {string} path
+ */
+export function parentOf(path) {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  return at <= 0 ? path.slice(0, at + 1) : path.slice(0, at);
+}
+
+/**
+ * Whether `path` is `under`, or in it, however deep. `under` may end with its separator (the
+ * root, `/`).
+ * @param {string} path
+ * @param {string} under
+ */
+export function within(path, under) {
+  if (path === under) return true;
+  if (under.endsWith('/') || under.endsWith('\\')) return path.startsWith(under);
+  return path.startsWith(`${under}/`) || path.startsWith(`${under}\\`);
+}
+
+/**
+ * `name` in the folder `dir`, with the separator `dir` uses.
+ * @param {string} dir
+ * @param {string} name
+ */
+export function childPath(dir, name) {
+  const separator = dir.includes('\\') && !dir.includes('/') ? '\\' : '/';
+  return dir.endsWith(separator) ? `${dir}${name}` : `${dir}${separator}${name}`;
+}