@deckbuilderkit/view-explorer 0.0.0-stage → 0.1.1

package/src/explorer/name-index.ts

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { stream } from '@deckbuilderkit/ui';
+import type { Project, SearchHit } from '../client';
+
+export interface NameIndex {
+  /** Every file and folder path of each project, as `/api/fs/names` lists them. */
+  entries: Record<string, SearchHit[]>;
+  loading: boolean;
+  /** Loads the projects whose index is missing or older than `maxAgeMs`. */
+  ensure(ids: string[], maxAgeMs?: number): void;
+}
+
+/** Per-project name lists for Quick Open and tree find, cached until `ensure` finds them stale or `exclude` changes. */
+export function useNameIndex(projects: Project[], exclude: string[]): NameIndex {
+  const [entries, setEntries] = useState<Record<string, SearchHit[]>>({});
+  const [pending, setPending] = useState(0);
+  const loaded = useRef(new Map<string, number>());
+  const running = useRef(new Map<string, AbortController>());
+  const excludeKey = JSON.stringify(exclude);
+  const known = useRef(projects);
+  known.current = projects;
+
+  const load = useCallback((id: string) => {
+    running.current.get(id)?.abort();
+    const ac = new AbortController();
+    running.current.set(id, ac);
+    const found: SearchHit[] = [];
+    setPending((n) => n + 1);
+    stream('/api/fs/names', { root: id, path: '', exclude: JSON.parse(excludeKey).length ? excludeKey : undefined }, (hit) => found.push(hit as SearchHit), ac.signal)
+      .then(() => {
+        loaded.current.set(id, Date.now());
+        setEntries((e) => ({ ...e, [id]: found }));
+      })
+      .catch(() => { /* an aborted or failed listing leaves the old one */ })
+      .finally(() => {
+        if (running.current.get(id) === ac) running.current.delete(id);
+        setPending((n) => n - 1);
+      });
+  }, [excludeKey]);
+
+  useEffect(() => {
+    loaded.current.clear();
+    return () => {
+      for (const ac of running.current.values()) ac.abort();
+    };
+  }, [excludeKey]);
+
+  const ensure = useCallback((ids: string[], maxAgeMs = 10_000) => {
+    const now = Date.now();
+    for (const id of ids) {
+      if (running.current.has(id) || !known.current.some((p) => p.id === id)) continue;
+      const at = loaded.current.get(id);
+      if (at === undefined || now - at > maxAgeMs) load(id);
+    }
+  }, [load]);
+
+  return { entries, loading: pending > 0, ensure };
+}

package/src/explorer/os-drop.ts

@@ -0,0 +1,56 @@
+/** A file read from a dropped folder; `rel` is its path below the dropped entry's parent, starting with the entry's own name. */
+export interface DroppedFile {
+  rel: string[];
+  file: File;
+}
+
+/** What a dropped OS entry holds: every file below it, and the folders that have nothing in them. */
+export interface DroppedTree {
+  files: DroppedFile[];
+  emptyDirs: string[][];
+}
+
+/** The entries of a drop; call before the first await, the browser empties `items` afterwards. */
+export function entriesOf(data: DataTransfer): FileSystemEntry[] {
+  const entries: FileSystemEntry[] = [];
+  for (const item of Array.from(data.items)) {
+    const entry = item.kind === 'file' ? item.webkitGetAsEntry() : null;
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+const readFile = (entry: FileSystemFileEntry) => new Promise<File>((resolve, reject) => entry.file(resolve, reject));
+
+async function readAll(dir: FileSystemDirectoryEntry): Promise<FileSystemEntry[]> {
+  const reader = dir.createReader();
+  const all: FileSystemEntry[] = [];
+  for (;;) {
+    const batch = await new Promise<FileSystemEntry[]>((resolve, reject) => reader.readEntries(resolve, reject));
+    if (!batch.length) return all;
+    all.push(...batch);
+  }
+}
+
+/** Walks `entry` (a file or a folder, recursively). */
+export async function walkEntry(entry: FileSystemEntry, parent: string[] = [], out: DroppedTree = { files: [], emptyDirs: [] }): Promise<DroppedTree> {
+  const rel = [...parent, entry.name];
+  if (entry.isFile) {
+    out.files.push({ rel, file: await readFile(entry as FileSystemFileEntry) });
+  } else {
+    const children = await readAll(entry as FileSystemDirectoryEntry);
+    if (!children.length) out.emptyDirs.push(rel);
+    for (const child of children) await walkEntry(child, rel, out);
+  }
+  return out;
+}
+
+/** `wanted`, or the first free `name copy.ext`, `name copy 2.ext`, ... among `taken` (compared with `fold`). Like the server's copy naming. */
+export function freeName(wanted: string, isDir: boolean, taken: ReadonlySet<string>, fold: (name: string) => string = (n) => n): string {
+  const dot = wanted.lastIndexOf('.');
+  const ext = isDir || dot <= 0 ? '' : wanted.slice(dot);
+  const stem = ext ? wanted.slice(0, dot) : wanted;
+  let name = wanted;
+  for (let n = 1; taken.has(fold(name)); n++) name = `${stem} copy${n > 1 ? ` ${n}` : ''}${ext}`;
+  return name;
+}

package/src/explorer/resolve-image-path.ts

@@ -0,0 +1,19 @@
+/** Project path of an image `src` found in the markdown file `filePath`; null when it leaves the project. */
+export function resolveImagePath(filePath: string, src: string): string | null {
+  let raw = src.split('#')[0]!.split('?')[0]!;
+  try {
+    raw = decodeURIComponent(raw);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  const parts: string[] = raw.startsWith('/') ? [] : filePath.split('/').slice(0, -1);
+  for (const seg of raw.split('/')) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') {
+      if (!parts.length) return null;
+      parts.pop();
+    } else parts.push(seg);
+  }
+  return parts.length ? parts.join('/') : null;
+}

package/src/explorer/tab-actions.ts

@@ -0,0 +1,17 @@
+import { useEffect, useRef } from 'react';
+import { effectiveKeys, type TabAction, useKeybindings } from '@deckbuilderkit/ui';
+
+/** The first key of a command, for tooltips and menus. */
+export function useChordOf(): (id: string) => string | undefined {
+  const kb = useKeybindings();
+  const keys = kb ? effectiveKeys(kb.defs, kb.keymap) : undefined;
+  return (id) => keys?.get(id)?.[0];
+}
+
+/** Calls `onActions` after every render (the tab bar ignores unchanged lists) and clears them on unmount. */
+export function useTabActions(actions: TabAction[], onActions?: (actions: TabAction[]) => void) {
+  const ref = useRef(onActions);
+  ref.current = onActions;
+  useEffect(() => ref.current?.(actions));
+  useEffect(() => () => ref.current?.([]), []);
+}

package/src/explorer/tree-find.ts

@@ -0,0 +1,37 @@
+import { relPath } from '@deckbuilderkit/ui/rel-path';
+import type { SearchHit } from '../client';
+
+export interface FindResult {
+  /** Matched entries by path: indices into the entry's name to highlight. */
+  matches: Map<string, number[]>;
+  /** Folder path -> matched entries below it ('' is the project root). */
+  counts: Map<string, number>;
+  /** Matched entries in tree order. */
+  order: string[];
+}
+
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+
+/** Entries whose name matches `query` (their path when the query has a `/`), with the folder counts above them. */
+export function findInTree(query: string, entries: readonly SearchHit[]): FindResult | undefined {
+  const q = query.trim().replace(/\\/g, '/').toLowerCase();
+  if (!q) return undefined;
+  const byPath = q.includes('/');
+  const matches = new Map<string, number[]>();
+  const counts = new Map<string, number>();
+  for (const e of entries) {
+    const name = relPath.basename(e.path);
+    const at = (byPath ? e.path : name).toLowerCase().indexOf(q);
+    if (at < 0) continue;
+    const start = byPath ? at - (e.path.length - name.length) : at;
+    const positions: number[] = [];
+    for (let i = 0; i < q.length; i++) if (start + i >= 0) positions.push(start + i);
+    matches.set(e.path, positions);
+    for (let dir = relPath.dirname(e.path); ; dir = relPath.dirname(dir)) {
+      counts.set(dir, (counts.get(dir) ?? 0) + 1);
+      if (!dir) break;
+    }
+  }
+  const order = [...matches.keys()].sort((a, b) => collator.compare(a, b));
+  return { matches, counts, order };
+}

package/src/explorer/useLocalImages.ts

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { requestBlob } from '@deckbuilderkit/ui';
+import { resolveImagePath } from './resolve-image-path';
+
+const PLACEHOLDER = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+
+/** `resolveImage` for the markdown preview: loads the project's images through the API as blob URLs. */
+export function useLocalImages(project: string, filePath: string): (src: string) => string | null {
+  // One cache per file, so loads started for a new file survive the old file's cleanup.
+  const cache = useMemo(() => ({ images: new Map<string, string | null>(), live: true }), [project, filePath]);
+  const [version, setVersion] = useState(0);
+
+  useEffect(() => {
+    cache.live = true;
+    return () => {
+      cache.live = false;
+      for (const [path, url] of cache.images) {
+        if (url && url !== PLACEHOLDER) {
+          URL.revokeObjectURL(url);
+          cache.images.delete(path);
+        }
+      }
+    };
+  }, [cache]);
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useCallback((src: string) => {
+    const path = resolveImagePath(filePath, src);
+    if (!path) return null;
+    const { images } = cache;
+    if (images.has(path)) return images.get(path)!;
+    images.set(path, PLACEHOLDER);
+    queueMicrotask(() => {
+      void requestBlob('/api/fs/raw', { root: project, path })
+        .then((blob) => (/\.svg$/i.test(path) && blob.type !== 'image/svg+xml' ? new Blob([blob], { type: 'image/svg+xml' }) : blob))
+        .then((blob) => URL.createObjectURL(blob), () => null)
+        .then((url) => {
+          if (!cache.live || images.get(path) !== PLACEHOLDER) {
+            if (url) URL.revokeObjectURL(url);
+            if (!cache.live) images.delete(path);
+            return;
+          }
+          images.set(path, url);
+          setVersion((v) => v + 1);
+        });
+    });
+    return PLACEHOLDER;
+  }, [cache, version]);
+}

package/src/explorer-paths.ts

@@ -0,0 +1,9 @@
+/** Tree node id, also what `settings.explorer.expanded` stores. */
+export const nodeId = (project: string, path: string) => `${project}:${path}`;
+
+/** Absolute path of `path` inside the project folder, with the separator the folder path uses. */
+export function fullPath(projectPath: string, path: string): string {
+  if (!path) return projectPath;
+  const sep = projectPath.includes('\\') ? '\\' : '/';
+  return `${projectPath.replace(/[\\/]+$/, '')}${sep}${path.split('/').join(sep)}`;
+}

package/src/explorer-state.ts

@@ -0,0 +1,21 @@
+/** The stored Explorer state. */
+export interface ExplorerSettings {
+  /** Fractions of the sidebar and the workspace. */
+  sizes: [number, number];
+  collapsed: boolean;
+  /** Expanded tree node ids per project id. */
+  expanded: Record<string, string[]>;
+  /** Project ids shown in the sidebar, 1 or 2. */
+  trees?: string[];
+  /** Fractions of the two trees when `trees` has 2. */
+  treeSizes?: [number, number];
+  /** Edit / split / preview of markdown files; live when omitted. */
+  markdownMode?: 'live' | 'edit' | 'split' | 'preview';
+  /** Wrap long lines in the file editors; on when omitted. */
+  wrapLines?: boolean;
+  /** Fractions of the SQL editor and its results panel. */
+  sqlSizes?: [number, number];
+  /** Last database connection id used per project id, for SQL files. */
+  connections?: Record<string, string>;
+  tabs?: unknown;
+}

package/src/explorer.css

@@ -0,0 +1,61 @@
+.xp-loading { display: flex; justify-content: center; padding: var(--space-12); }
+.xp-pane { display: flex; flex-direction: column; height: 100%; min-height: 0; }
+.xp-find { display: flex; align-items: center; gap: var(--space-6); padding: var(--space-4) var(--space-8); }
+.xp-find input { flex: 1; min-width: 0; }
+.xp-find-count { font-size: var(--fs-xs-plus); white-space: nowrap; }
+.xp-pane-body { flex: 1; min-height: 0; overflow: auto; }
+.xp-project { display: flex; flex-direction: column; border-top: 1px solid var(--border-soft); }
+/* The tree fills the pane, so a file dropped below the last row still lands in the project. */
+.xp-tree-wrap:not([hidden]) { display: flex; flex-direction: column; min-height: 100%; }
+.xp-project { flex: 1; }
+.xp-project > .tree { flex: 1; }
+.xp-head { display: flex; align-items: center; gap: var(--space-6); padding: var(--space-8) var(--space-8) var(--space-4); }
+.xp-search { flex: 1; min-width: 0; }
+.xp-search input { width: 100%; }
+.xp-results { display: flex; flex-direction: column; padding: var(--space-4); }
+.xp-status { display: flex; align-items: center; gap: var(--space-6); padding: var(--space-4) var(--space-8); font-size: var(--fs-sm); }
+.xp-hit {
+  display: flex; align-items: flex-start; gap: var(--space-8); padding: 5px var(--space-8); border: 0; border-radius: var(--radius-md);
+  background: transparent; color: var(--text-2); text-align: left; cursor: pointer;
+}
+.xp-hit:hover:not(:disabled) { background: var(--hover); color: var(--text); }
+.xp-hit:disabled { cursor: default; opacity: .6; }
+.xp-hit-text { display: flex; flex-direction: column; min-width: 0; flex: 1; }
+.xp-hit-path { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: var(--fs-md); }
+.xp-hit-line { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: var(--fs-xs); color: var(--text-3); }
+
+/* The file view fills its pane edge to edge, like VS Code: breadcrumbs, banners, content, status bar. */
+.xp-file { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+.xp-bar { display: flex; align-items: center; gap: var(--space-8); min-height: var(--control-h-xs); padding: 0 var(--space-8); font-size: var(--fs-sm); }
+.xp-body { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+.xp-body > .code-editor { height: 100%; }
+.xp-body .code-editor, .xp-body .code-view, .xp-body .code-view-plain { border: 0; border-radius: 0; }
+.xp-file > .panel-banner { border-radius: 0; }
+.xp-sql-editor { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+
+.xp-watermark { display: grid; gap: var(--space-8); margin: 28px auto 0; width: max-content; max-width: 100%; color: var(--text-2); font-size: var(--fs-md); }
+.xp-watermark > div { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: var(--space-24); align-items: center; }
+.xp-watermark dt { text-align: right; }
+.xp-watermark dd { margin: 0; }
+
+.xp-details { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+.xp-details-body { display: flex; flex-direction: column; flex: 1; min-height: 0; }
+.xp-details-body > .dtable { flex: 1; min-height: 0; }
+.xp-details-name { display: inline-flex; align-items: center; gap: var(--space-6); min-width: 0; }
+.xp-details-name.dim { opacity: 0.55; }
+.xp-details-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+.ex-pane { display: flex; flex-direction: column; min-width: 0; min-height: 0; height: 100%; overflow: hidden; }
+/* The plan table of the SQL results (@deckbuilderkit/sql-ui classes), scoped to the Explorer panels. */
+.ex-pane .wb-plan { display: flex; flex-direction: column; height: 100%; min-height: 0; }
+.ex-pane .wb-plan-bar { align-items: center; gap: var(--space-8); padding: var(--space-4) var(--space-8); border-bottom: 1px solid var(--border-soft); }
+.ex-pane .wb-plan-bar .mono-label { flex: 1; }
+.ex-pane .wb-plan-empty { padding: var(--space-8); }
+.ex-pane .wb-plan-scroll { flex: 1; min-height: 0; overflow: auto; }
+.ex-pane .wb-plan-table { border-collapse: collapse; width: 100%; font-family: var(--mono, monospace); font-size: var(--fs-sm); }
+.ex-pane .wb-plan-table th, .ex-pane .wb-plan-table td { padding: var(--space-2) var(--space-6); text-align: left; white-space: nowrap; border-bottom: 1px solid var(--border-soft); }
+.ex-pane .wb-plan-table th { position: sticky; top: 0; background: var(--bg); color: var(--text-2); font-weight: 500; }
+.ex-pane .wb-plan-table .num { text-align: right; }
+.ex-pane .wb-plan-hot td { background: color-mix(in srgb, var(--warn) 18%, transparent); }
+.ex-pane .wb-plan-hot td:first-child { box-shadow: inset 3px 0 var(--warn); }
+.ex-pane .wb-plan-pred { color: var(--text-2); }