yamlover 0.3.4 → 0.3.6

package/src/client/api.ts

@@ -1,213 +0,0 @@
-// Typed wrappers over the server's JSON API.
-
-export interface TreeNode {
-  path: string;
-  label: string;
-  type: string;
-  format: string | null;
-  valueType?: string | null; // renderer dispatch facets (TYPES.md §9)
-  hasKeyed?: boolean;
-  hasOrdinal?: boolean;
-  concrete: string | null; // how it is stored; `dir` → a plain-folder icon
-  hasChildren: boolean;
-  children: TreeNode[];
-}
-
-export interface NodeJson {
-  path: string;
-  type: string;
-  format?: string | null; // schema `format`; with the facets it keys the renderer (TYPES.md §9)
-  valueType?: string | null; // the scalar self-VALUE's type (null|boolean|integer|number|string|binary), or null
-  hasKeyed?: boolean; // owns ≥1 keyed element
-  hasOrdinal?: boolean; // owns ≥1 ordinal (keyless) element
-  concrete: string | null;
-  documentPath?: string; // the document (nearest yamlover entity) this node is in —
-                         // the anchor a document-relative (`/…`) link resolves against
-  title: string | null;
-  description: string | null;
-  value: unknown;
-  relations?: Record<string, unknown>; // named up-edges (+ `..`) as ref markers
-}
-
-async function getJson<T>(url: string): Promise<T> {
-  const res = await fetch(url);
-  const body = await res.json();
-  if (!res.ok) throw new Error((body && body.error) || `HTTP ${res.status}`);
-  return body as T;
-}
-
-/** Server info: the ROOT path as given on the CLI (breadcrumb head; "" if omitted). */
-export function fetchInfo(): Promise<{ root: string }> {
-  return getJson<{ root: string }>("/api/info");
-}
-
-/** A long-running server task (indexing, hashing, …) — mirrors server/tasks.ts. Updates ride
- *  /api/events as `{type:"task", task}` frames; this shape is also what GET /api/tasks lists. */
-export interface TaskInfo {
-  id: string;
-  label: string;
-  state: "running" | "done" | "error";
-  progress: { done: number; total?: number; message?: string };
-  startedAt: number;
-  finishedAt?: number;
-  error?: string;
-}
-
-/** Server tasks in flight (or just finished) — the snapshot a freshly loaded page needs. */
-export function fetchTasks(): Promise<TaskInfo[]> {
-  return getJson<TaskInfo[]>("/api/tasks");
-}
-
-/** The TOC subtree rooted at `path`, `depth` levels deep (server default 3). */
-export function fetchTree(path = ":", depth?: number): Promise<TreeNode> {
-  const q = new URLSearchParams({ path });
-  if (depth != null) q.set("depth", String(depth));
-  return getJson<TreeNode>(`/api/tree?${q}`);
-}
-
-export function fetchNode(
-  path: string,
-  depth?: number,
-  opts?: { binary?: boolean },
-): Promise<NodeJson> {
-  const q = new URLSearchParams({ path });
-  if (depth != null) q.set("depth", String(depth));
-  if (opts?.binary) q.set("binary", "1"); // request a binary leaf's base64 bytes
-  return getJson<NodeJson>(`/api/json?${q}`);
-}
-
-/** URL of a file-backed node's raw bytes (image / pdf / html / djvu source). */
-export function blobUrl(path: string): string {
-  return `/api/blob?path=${encodeURIComponent(path)}`;
-}
-
-/** The node's instance schema, one level deep (nested containers as link markers). */
-export function fetchSchema(path: string, depth?: number): Promise<unknown> {
-  const q = new URLSearchParams({ path });
-  if (depth != null) q.set("depth", String(depth));
-  return getJson<unknown>(`/api/schema?${q}`);
-}
-
-/** A tag as the annotation API hands it around: its node path, display name (the taxonomy key),
- *  and explicit color — null for a named tag, whose hue the client derives from the name. */
-export interface TagRef {
-  path: string;
-  name: string;
-  color: string | null;
-}
-
-/** An annotation of a material — ONE TAG APPLICATION (ANNOTATIONS.md): the whole node, or a
- *  fragment within it (then `selector` carries that fragment's region and `fragmentSlug` its
- *  key, and `imageUrl` its crop), tagged by `tag` with optional `description` / `params`. */
-export interface Annotation {
-  tag?: TagRef | null;
-  selector?: { type?: string; exact?: string; prefix?: string; suffix?: string; [k: string]: unknown };
-  fragmentSlug?: string; // set when the tag is on a fragment (the region) rather than the whole node
-  imageUrl?: string; // an image-like fragment's crop (a /api/blob URL)
-  description?: string;
-  params?: Record<string, unknown>;
-  created?: string;
-  path?: string; // a transient client marker only ("(preview)"/"(pending)"); annotations have no node path
-}
-
-/** The annotations whose `target` is the material at `path` (the engine's reverse link). */
-export function fetchAnnotations(path: string): Promise<Annotation[]> {
-  return getJson<Annotation[]>(`/api/annotations?path=${encodeURIComponent(path)}`);
-}
-
-/** The materials filed under the tag at `path` — `$yamloverLink` markers, annotations already
- *  resolved to their `target` and deduped (the explorer's member list for a tag page). */
-export function fetchTagged(path: string): Promise<unknown[]> {
-  return getJson<unknown[]>(`/api/tagged?path=${encodeURIComponent(path)}`);
-}
-
-/** Evaluate a colon-grammar QUERY (QUERY.md / engine `query` op) at `at` (default: the root `:`),
- *  returning the matched node paths in canonical colon form. A malformed query rejects (the
- *  server answers 400). Reused by the tag-picker typeahead and, later, by find-usages. */
-export function query(q: string, at = ":"): Promise<string[]> {
-  const params = new URLSearchParams({ q, path: at });
-  return getJson<{ results: string[] }>(`/api/query?${params}`).then((r) => r.results);
-}
-
-async function postJson<T>(url: string, body: unknown): Promise<T> {
-  const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
-  const json = await res.json();
-  if (!res.ok) throw new Error((json && json.error) || `HTTP ${res.status}`);
-  return json as T;
-}
-
-/** Create a FRAGMENT — a marked region in the node at `target` (ANNOTATIONS.md). Returns its slug
- *  and full node path, which is then the `target` for {@link annotate}. `imageBase64` is an
- *  optional PNG crop for image-like selections. */
-export function createFragment(target: string, selector: Record<string, unknown>, imageBase64?: string): Promise<{ slug: string; fragmentPath: string }> {
-  return postJson("/api/fragment", { target, selector, ...(imageBase64 ? { imageBase64 } : {}) });
-}
-
-/** Apply the tag at `tag` to the node at `target` (a whole node OR a fragment path) — appends to
- *  the target's `yamlover-annotations`. `description`/`params` make it a parametrized annotation. */
-export function annotate(a: { target: string; tag: string; description?: string; params?: Record<string, unknown> }): Promise<{ ok: true }> {
-  return postJson("/api/annotate", a);
-}
-
-/** Create a named tag at the project's default tags location (settings.yamlover; `/tags` by
- *  default) — the picker's create-on-miss. Idempotent: an existing tag at that path is returned
- *  as-is; a non-tag node already occupying the path is an error. */
-export function createTag(name: string): Promise<TagRef> {
-  return fetch("/api/tag", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name }) }).then(
-    async (res) => {
-      const body = await res.json();
-      if (!res.ok) throw new Error((body && body.error) || `HTTP ${res.status}`);
-      return body as TagRef;
-    },
-  );
-}
-
-/** The result of pasting/uploading a file or text: the new file's node path (for a text chunk,
- *  the chapter it joined), and (for a chapter) the chapter path plus any chunk pointer appended. */
-export interface PasteResult {
-  path: string; // the new file's node path (a text chunk: the chapter's own path)
-  chapter?: string; // the chapter the chunk was appended to (chapter paste only)
-  pointer?: string; // the `*…` chunk pointer appended (chapter FILE paste only)
-  dir?: string; // the enclosing directory the file landed in (directory/member paste)
-  open?: boolean; // true when the page was a MEMBER of a directory → open the new file
-}
-
-function postPaste(body: Record<string, unknown>): Promise<PasteResult> {
-  return fetch("/api/paste", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  }).then(async (res) => {
-    const json = await res.json();
-    if (!res.ok) throw new Error((json && json.error) || `HTTP ${res.status}`);
-    return json as PasteResult;
-  });
-}
-
-/** Upload a pasted file onto the page at `target` (a directory or a chapter). */
-export function pasteFile(target: string, filename: string, contentBase64: string): Promise<PasteResult> {
-  return postPaste({ path: target, filename, contentBase64 });
-}
-
-/** Paste plain TEXT onto the page at `target`: a chapter gains it as a new chunk; anywhere else
- *  it becomes a new chapter .yamlover file in the nearest enclosing directory. */
-export function pasteText(target: string, text: string): Promise<PasteResult> {
-  return postPaste({ path: target, text });
-}
-
-/** Paste RICH content (an HTML selection: text + images + heading-nested subchapters) onto the
- *  page at `target`. A chapter appends the chunks and subchapters; anywhere else a new chapter
- *  is created — directory-backed when files are present, a standalone .yamlover file otherwise.
- *  `rich` is the RichNode tree from paste-html.ts (images already inline as base64 files). */
-export function pasteRich(target: string, rich: unknown): Promise<PasteResult> {
-  return postPaste({ path: target, rich });
-}
-
-/** Remove the application of `tag` from the node at `target` (a whole node OR a fragment path) —
- *  splices the matching element out of its `yamlover-annotations`. */
-export function deleteAnnotation(target: string, tag: string): Promise<void> {
-  const q = new URLSearchParams({ target, tag });
-  return fetch(`/api/annotate?${q}`, { method: "DELETE" }).then(async (res) => {
-    if (!res.ok) throw new Error(((await res.json().catch(() => null))?.error) || `HTTP ${res.status}`);
-  });
-}

package/src/client/icons.ts

@@ -1,91 +0,0 @@
-// Type/format icon for a TOC node — chosen by the schema `format`, falling back
-// to `type`. One exception to being concrete-agnostic: a node stored as an
-// on-disk directory gets a folder icon, since it really is a filesystem folder —
-// plain (`dir`, no `.yamlover/` marker) or a yamlover entity (`yamlover`).
-
-export interface Glyph {
-  glyph: string;
-  cls: string; // CSS class (color)
-  title: string; // tooltip
-}
-
-// Type → a monochrome glyph, colored by category (matches the value highlighting).
-const TYPE: Record<string, { glyph: string; cls: string }> = {
-  object: { glyph: "{}", cls: "t-struct" },
-  array: { glyph: "[]", cls: "t-struct" },
-  string: { glyph: "“”", cls: "t-str" },
-  integer: { glyph: "#", cls: "t-num" },
-  number: { glyph: "½", cls: "t-num" },
-  boolean: { glyph: "◧", cls: "t-bool" },
-  null: { glyph: "∅", cls: "t-null" },
-  binary: { glyph: "0110", cls: "t-bin binsq" }, // bits in a little square
-};
-
-// Exact-match formats → an icon.
-const FORMAT: Record<string, string> = {
-  "date-time": "🕑",
-  date: "📅",
-  time: "🕑",
-  duration: "⏳",
-  email: "✉️",
-  "idn-email": "✉️",
-  hostname: "🖥️",
-  "idn-hostname": "🖥️",
-  ipv4: "🌐",
-  ipv6: "🌐",
-  uri: "🔗",
-  iri: "🔗",
-  "uri-reference": "🔗",
-  "iri-reference": "🔗",
-  "uri-template": "🔗",
-  url: "🔗",
-  uuid: "🆔",
-  regex: "🔣",
-  "json-pointer": "📍",
-  "relative-json-pointer": "📍",
-  password: "🔑",
-  color: "🎨",
-};
-
-// Media-type / binary-encoding / custom formats → an icon, chosen by prefix.
-function mediaIcon(format: string): string | null {
-  if (format === "x-yamlover-chapter") return "§"; // a chapter — the section sign
-  if (format === "x-yamlover-tag") return "🏷️";
-  if (format.startsWith("x-yamlover-")) return "🧩"; // a custom yamlover renderer
-  if (format === "application/pdf") return "📕";
-  if (format === "application/x-fictionbook+xml") return "📘";
-  if (format === "application/epub+zip") return "📗";
-  if (format === "image/vnd.djvu") return "📓";
-  if (format.startsWith("image/")) return "🖼️";
-  if (format === "text/markdown") return "📝";
-  if (format === "text/asciidoc") return "📃";
-  if (format === "text/csv" || format === "text/tab-separated-values") return "▦"; // a table
-  if (format === "text/x-plantuml") return "📊"; // source that compiles to a diagram
-  if (format === "application/vnd.ms-excel") return "▦"; // legacy .xls workbook
-  if (format === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet") return "▦"; // .xlsx
-  if (format === "application/rtf") return "📄";
-  if (format === "application/msword") return "📄"; // legacy .doc
-  if (format === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") return "📄"; // .docx
-  if (format === "application/vnd.google-earth.kml+xml" || format === "application/vnd.google-earth.kmz") return "🗺️"; // map overlay
-  if (format.startsWith("text/")) return "📄";
-  if (format.startsWith("audio/")) return "🔊";
-  if (format.startsWith("video/")) return "🎬";
-  if (/^(u?int|float)\d/.test(format)) return "💾"; // int32/le, float64, …
-  return null;
-}
-
-/** The type/format icon for a node — `format` wins, then a directory concrete
- *  (`dir`/`yamlover`) shows a folder, else `type`. */
-export function typeIcon(type: string, format: string | null, concrete?: string | null): Glyph {
-  if (format) {
-    const g = FORMAT[format] ?? mediaIcon(format);
-    if (g) return { glyph: g, cls: "t-fmt", title: format };
-  }
-  // a plain directory (no `.yamlover/`) — a real OS folder
-  if (concrete === "dir") return { glyph: "📁", cls: "t-struct", title: "folder" };
-  // a yamlover entity stored as a directory (a folder with a `.yamlover/` marker)
-  if (concrete === "yamlover") return { glyph: "🗂️", cls: "t-struct", title: "yamlover folder" };
-  const t = TYPE[type];
-  if (t) return { glyph: t.glyph, cls: t.cls, title: type };
-  return { glyph: "•", cls: "t-bin", title: type || "unknown" };
-}

package/src/client/links.tsx

@@ -1,108 +0,0 @@
-import { ReactNode } from "react";
-import { segsToStr, strToSegs } from "./paths";
-
-/**
- * The shared **link** concept: one place that decides what a link *target* means
- * and how a link is made clickable. Every renderer that emits links routes through
- * here, so link behaviour is defined once.
- *
- * A target is addressed in the app's JSON instance space — the same space the
- * tree, breadcrumbs, and the URL all navigate — with two anchors, mirroring how an
- * `x-yamlover` `rel` pointer is written:
- *
- *   - **`/some/path`** — relative to the *document* the link appears in (the
- *     nearest yamlover entity; "document" meaning the literal file/entity, overlays
- *     and all). Resolved against the `documentPath` the server reports for the node.
- *   - **`//some/path`** — relative to the *project root* (the location given at
- *     yamlover startup), i.e. the served root → browser path `/some/path`.
- *   - **`scheme://…` / `mailto:…`** — an ordinary external link.
- *
- * `resolveLink` is deliberately the single seam for interpretation: it is where
- * refs and rels are expected to plug in later (gaining the full pointer grammar —
- * `..`, `^name`, virtual children), rather than each renderer re-deciding what a
- * target points at. (Refs/rels keep their own server-side interpretation for now;
- * this powers marklower links.)
- */
-
-/** A link's resolved destination. Exactly one of `path` (an in-app JSON-space path
- *  for SPA navigation) or `href` (an external URL) is set; both null means the
- *  target did not resolve and the link renders as plain text. */
-export interface ResolvedLink {
-  path: string | null;
-  href: string | null;
-}
-
-const UNRESOLVED: ResolvedLink = { path: null, href: null };
-
-/** True for an external target carrying a URI scheme (`http:`, `https:`, `mailto:`,
- *  …). A `//`-rooted project path is *not* a scheme (no leading `scheme:`). */
-const hasScheme = (s: string) => /^[a-z][a-z0-9+.-]*:/i.test(s);
-
-/** Join a document base path with a document-relative path (both JSON-space),
- *  canonicalizing the result. */
-function joinDoc(documentPath: string, rel: string): string {
-  return segsToStr([...strToSegs(documentPath), ...strToSegs(rel)]);
-}
-
-/** Tokenize a LEGACY slash-spelled link target (`/a/b[0]`) into segments. */
-function slashSegs(str: string): (string | number)[] {
-  const out: (string | number)[] = [];
-  for (const tok of str.match(/\[\d+\]|[^/\[\]]+/g) || []) {
-    out.push(/^\[\d+\]$/.test(tok) ? Number(tok.slice(1, -1)) : tok);
-  }
-  return out;
-}
-
-/** Interpret a link `target` against the `documentPath` it appears in (the JSON-space
- *  path of its document; defaults to root). Colon spellings (`:a:b`, `::a:b` —
- *  SEPARATOR.md) are canonical; legacy slash spellings (`/a/b`, `//a/b`) still parse. */
-export function resolveLink(target: string, documentPath = ":"): ResolvedLink {
-  const raw = target.trim();
-  if (!raw) return UNRESOLVED;
-  if (raw.startsWith("::")) return { path: segsToStr(strToSegs(raw.slice(2))), href: null }; // project root
-  if (raw.startsWith(":")) return { path: joinDoc(documentPath, raw), href: null }; // document-relative
-  if (raw.startsWith("//")) return { path: segsToStr(slashSegs(raw)), href: null }; // legacy project root
-  if (hasScheme(raw)) return { path: null, href: raw }; // external (http(s)/mailto/…)
-  if (raw.startsWith("/")) return { path: segsToStr([...strToSegs(documentPath), ...slashSegs(raw)]), href: null }; // legacy doc-relative
-  return UNRESOLVED; // anything else is not (yet) a recognized link target
-}
-
-/** Render a link as the right kind of anchor: an in-app `.descend` link that calls
- *  `onNavigate` for an internal target, an ordinary external `.extlink` for a URL,
- *  or plain children when the target doesn't resolve. The single place a link
- *  becomes clickable — shared by every renderer that emits links. */
-export function NavLink({
-  target,
-  documentPath,
-  onNavigate,
-  children,
-}: {
-  target: string;
-  documentPath?: string;
-  onNavigate: (path: string) => void;
-  children: ReactNode;
-}) {
-  const { path, href } = resolveLink(target, documentPath);
-  if (href) {
-    return (
-      <a className="extlink" href={href} target="_blank" rel="noopener noreferrer">
-        {children}
-      </a>
-    );
-  }
-  if (path) {
-    return (
-      <a
-        className="descend"
-        href={path}
-        onClick={(e) => {
-          e.preventDefault();
-          onNavigate(path);
-        }}
-      >
-        {children}
-      </a>
-    );
-  }
-  return <>{children}</>;
-}

package/src/client/live.ts

@@ -1,42 +0,0 @@
-// live.ts — the client side of the UNIFIED change flow. Every change to the served tree —
-// mediated writes (annotate, tag, paste, mv) and external edits (the FS watcher) — reaches the
-// client as ONE currency: a file-level IndexDiff over /api/events, which App re-broadcasts as a
-// `yamlover:diff` window event. Hooks that hold server-derived state subscribe HERE instead of
-// inventing per-feature push paths; a new surface gets live refresh by adding one useDiffBump.
-
-import { useEffect, useState } from "react";
-
-/** A reindex/write diff as App re-broadcasts it: client JSON paths of the touched FILES
- *  (added + changed + removed + both ends of moves), with the removals also listed alone. */
-export interface DiffDetail {
-  paths: string[];
-  removed: string[];
-}
-
-export const DIFF_EVENT = "yamlover:diff";
-
-/** Re-broadcast a server diff to the window (App's SSE handler is the only caller). */
-export function broadcastDiff(detail: DiffDetail): void {
-  window.dispatchEvent(new CustomEvent(DIFF_EVENT, { detail }));
-}
-
-/** Diffs that can affect graph-derived state (annotations, tags, document bodies) — any touched
- *  `.yamlover` source. A binary-only diff (a photo import, say) passes nothing here. */
-export const touchesYamlover = (d: DiffDetail): boolean => d.paths.some((p) => p.endsWith(".yamlover"));
-
-/** A counter that bumps whenever a diff matches `match` (default: every diff) — put it in a
- *  fetch effect's dependency list and the data refetches on relevant changes. `match` must be
- *  a stable (module-level) predicate; it is deliberately not a re-subscribe dependency. */
-export function useDiffBump(match: (d: DiffDetail) => boolean = () => true): number {
-  const [bump, setBump] = useState(0);
-  useEffect(() => {
-    const on = (e: Event) => {
-      const det = (e as CustomEvent).detail as DiffDetail | undefined;
-      if (det && match(det)) setBump((b) => b + 1);
-    };
-    window.addEventListener(DIFF_EVENT, on);
-    return () => window.removeEventListener(DIFF_EVENT, on);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-  return bump;
-}

package/src/client/main.tsx

@@ -1,10 +0,0 @@
-import React from "react";
-import { createRoot } from "react-dom/client";
-import { App } from "./App";
-import "./styles.css";
-
-createRoot(document.getElementById("root")!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>,
-);