@graph8/sdk 0.370.0 → 0.374.0

package/blocks/documents/components/library-document-form.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+/**
+ * LibraryDocumentForm: write a text document into the Library, or edit one (rename, move, change its text).
+ *
+ * SDK operations, in order:
+ *   1. getLibraryDocument (GET /library/documents/{document_id})  read   edit only: the FULL record is read before the form shows
+ *   2. createLibraryDocument (POST /library/documents)            write  new text document; stored as typed, no extraction
+ *   3. updateLibraryDocument (PUT /library/documents/{document_id}) write only the fields that changed; an omitted field is left alone
+ * Edit is disabled until the full record has loaded: a list row can carry less than the record, and saving a form seeded
+ * from it would write blanks over real text. A cleared text box is sent as an empty string, which the API stores. After a
+ * save the document's cache entries and the library lists are refreshed, so reopening the form shows what was saved.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ROOT, docName, fileNameFor, folderLabel } from "../lib/documents-types";
+import type { LibraryDoc, LibraryFolder } from "../lib/documents-types";
+
+export interface LibraryDocumentFormProps {
+  /** Edit this document; omit to write a new one. */
+  document?: LibraryDoc;
+  folders: LibraryFolder[];
+  /** Pre-select the folder for a new document. */
+  folderPath?: string;
+  onSaved: (doc: LibraryDoc) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function LibraryDocumentForm({ document, folders, folderPath, onSaved, onCancel }: LibraryDocumentFormProps) {
+  const full = useG8Query(
+    (signal) => g8Get<LibraryDoc>(`/library/documents/${encodeURIComponent(document!.id)}`, {}, { signal }).then((r) => r.data),
+    [document?.id],
+    { enabled: Boolean(document), key: ["documents", "doc", document?.id ?? ""], placeholderData: document },
+  );
+  if (!document) return <Fields folders={folders} folderPath={folderPath} onSaved={onSaved} onCancel={onCancel} />;
+  if (full.error && (!full.data || full.isPlaceholderData)) return <ApiError error={full.error} title="Could not load this document" onRetry={() => void full.refetch()} />;
+  if (!full.data || full.isPlaceholderData || full.data.id !== document.id) return <Skeleton className="h-40 w-full" aria-label="Loading document" />;
+  return <Fields key={full.data.id} document={full.data} folders={folders} onSaved={onSaved} onCancel={onCancel} />;
+}
+
+function Fields({ document, folders, folderPath, onSaved, onCancel }: LibraryDocumentFormProps) {
+  const editing = Boolean(document);
+  const [title, setTitle] = useState(document?.display_name ?? "");
+  const [fileName, setFileName] = useState(document?.file_name ?? "");
+  const [fileTouched, setFileTouched] = useState(false);
+  const [folder, setFolder] = useState(document?.folder_path ?? folderPath ?? ROOT);
+  const [content, setContent] = useState(document?.content ?? "");
+  const folderChoices = [...new Set([ROOT, ...folders.map((f) => f.full_path), folder])];
+  const valid = title.trim() !== "" && (editing || (fileName.trim() !== "" && content.trim() !== ""));
+
+  const save = useG8Mutation(
+    async (): Promise<LibraryDoc> => {
+      if (document) {
+        const diff: Record<string, unknown> = {};
+        if (title.trim() !== (document.display_name ?? "")) diff.display_name = title.trim();
+        if (folder !== document.folder_path) diff.folder_path = folder;
+        if (content !== (document.content ?? "")) diff.content = content;
+        if (Object.keys(diff).length === 0) return document;
+        return (await g8Put<LibraryDoc>(`/library/documents/${encodeURIComponent(document.id)}`, diff)).data;
+      }
+      return (await g8Post<LibraryDoc>("/library/documents", { folder_path: folder, file_name: fileName.trim(), display_name: title.trim(), content })).data;
+    },
+    { onSuccess: onSaved, invalidates: (saved) => [["documents", "list"], ["documents", "tree"], ["documents", "doc", saved?.id ?? document?.id ?? ""]] },
+  );
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div>
+        <Label htmlFor="g8-dd-title" className="mb-1">Title</Label>
+        <Input id="g8-dd-title" value={title} onChange={(e) => { setTitle(e.target.value); if (!editing && !fileTouched) setFileName(fileNameFor(e.target.value)); }} placeholder="Security overview" />
+      </div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-dd-folder" className="mb-1">Folder</Label>
+          <select id="g8-dd-folder" className={SELECT} value={folder} onChange={(e) => setFolder(e.target.value)}>
+            {folderChoices.map((p) => <option key={p} value={p}>{folderLabel(p)}</option>)}
+          </select>
+        </div>
+        {editing ? null : (
+          <div>
+            <Label htmlFor="g8-dd-file" className="mb-1">File name</Label>
+            <Input id="g8-dd-file" value={fileName} onChange={(e) => { setFileName(e.target.value); setFileTouched(true); }} placeholder="security-overview.md" />
+          </div>
+        )}
+      </div>
+      <div>
+        <Label htmlFor="g8-dd-content" className="mb-1">Text</Label>
+        <Textarea id="g8-dd-content" rows={12} value={content} onChange={(e) => setContent(e.target.value)} placeholder={editing ? undefined : "Write or paste the document. It is stored as typed."} />
+        {editing && document?.has_file_data ? <p className="text-muted-foreground mt-1 text-xs">{docName(document)} was uploaded as a file. Changing this text changes what the library reads; the original file is untouched.</p> : null}
+      </div>
+      {save.error ? <ApiError error={save.error} title="Could not save the document" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>{editing ? "Save changes" : "Add document"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

package/blocks/documents/components/library-folder-form.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * LibraryFolderForm: make a Library folder or rename one.
+ *
+ * SDK operations, in order:
+ *   1. createLibraryFolder (POST /library/folders)            write  a new folder under a parent (the Library root or another folder)
+ *   2. renameLibraryFolder (PUT /library/folders/{folder_id}) write  rename only; the documents inside keep their ids
+ * The API's rules are checked here first so the person sees them before the call: a name is letters, numbers, spaces,
+ * hyphens and underscores (at most 50), and folders go three levels deep. Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ROOT, folderLabel, folderNameProblem } from "../lib/documents-types";
+import type { LibraryFolder } from "../lib/documents-types";
+
+export interface LibraryFolderFormProps {
+  /** Rename this folder; omit to create one. */
+  folder?: LibraryFolder;
+  /** Every folder, to offer as the parent when creating. */
+  folders: LibraryFolder[];
+  /** Pre-select the parent when creating. */
+  parentPath?: string;
+  onSaved: (folder: LibraryFolder) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function LibraryFolderForm({ folder, folders, parentPath, onSaved, onCancel }: LibraryFolderFormProps) {
+  const [name, setName] = useState(folder?.name ?? "");
+  const [parent, setParent] = useState(parentPath || ROOT);
+  const parentOptions = [ROOT, ...folders.map((f) => f.full_path)].filter((p) => p.split("/").length < 3);
+  const problem = name.trim() === "" ? null : folderNameProblem(name, folder ? folder.parent_path : parent);
+  const changed = folder ? name.trim() !== folder.name : true;
+  const valid = name.trim() !== "" && problem === null && changed;
+
+  const save = useG8Mutation(
+    async (): Promise<LibraryFolder> => {
+      if (folder) return (await g8Put<LibraryFolder>(`/library/folders/${encodeURIComponent(folder.id)}`, { name: name.trim() })).data;
+      return (await g8Post<LibraryFolder>("/library/folders", { name: name.trim(), parent_path: parent })).data;
+    },
+    { onSuccess: onSaved, invalidates: [["documents"]] },
+  );
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div>
+        <Label htmlFor="g8-df-name" className="mb-1">Folder name</Label>
+        <Input id="g8-df-name" value={name} maxLength={50} onChange={(e) => setName(e.target.value)} placeholder="Case studies" />
+        {problem ? <p role="alert" className="text-error mt-1 text-xs">{problem}</p> : null}
+      </div>
+      {folder ? (
+        <p className="text-muted-foreground text-xs">Inside {folderLabel(folder.parent_path)}. Renaming keeps every document in it.</p>
+      ) : (
+        <div>
+          <Label htmlFor="g8-df-parent" className="mb-1">Inside</Label>
+          <select id="g8-df-parent" className={SELECT} value={parent} onChange={(e) => setParent(e.target.value)}>
+            {parentOptions.map((p) => <option key={p} value={p}>{folderLabel(p)}</option>)}
+          </select>
+        </div>
+      )}
+      {save.error ? <ApiError error={save.error} title={folder ? "Could not rename the folder" : "Could not create the folder"} /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>{folder ? "Rename folder" : "Create folder"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

package/blocks/documents/components/library-panel.tsx

@@ -0,0 +1,235 @@
+"use client";
+
+/**
+ * LibraryPanel: the organization's document Library as a finished page: folders on one side, documents and the selected
+ * document's detail on the other.
+ *
+ * SDK operations, in order:
+ *   1. getLibraryTree (GET /library/tree)                       read         read FIRST: the API creates the preset folders (Security, Case Studies) when the tree is read
+ *   2. listLibraryFolders (GET /library/folders)                read         the flat folder list (the tree leaves out folders more than one level down)
+ *   3. listLibraryDocuments (GET /library/documents)            read         every document, or with removed ones too; the API does not page it
+ *   4. deleteLibraryFolder (DELETE /library/folders/{folder_id}) DESTRUCTIVE  an EMPTY folder only; behind ConfirmSpendDialog
+ *   5. reextractAllLibraryDocuments (POST .../reextract-all)     write        replaces the stored text of PDF and Word files (never the files); behind ConfirmSpendDialog, counted from the documents it will touch
+ * New folders, renames, new text documents, uploads and every per-document action live in the composed parts
+ * (LibraryFolderForm, LibraryDocumentForm, LibraryUpload, LibraryDocumentDetail). The Library here is the organization's
+ * (global) one: the API's campaign and account libraries are read and written with different ids, so they are not offered.
+ * URL: `?id=` the selected document, `?folder=` the folder, `&view=full` the document as a page.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { FileText, Folder, FolderOpen, FolderPlus, Pencil, Plus, ScanText, Trash2, Upload } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { DEFAULT_MAX_BYTES, REEXTRACT_TYPES, ROOT, docName, fmtSize, folderLabel, rowsOf, when } from "../lib/documents-types";
+import type { LibraryDoc, LibraryFolder, Rec } from "../lib/documents-types";
+import { LibraryDocumentDetail } from "./library-document-detail";
+import { LibraryDocumentForm } from "./library-document-form";
+import { LibraryFolderForm } from "./library-folder-form";
+import { LibraryUpload } from "./library-upload";
+
+export interface LibraryPanelProps {
+  renderRowActions?: (doc: LibraryDoc) => ReactNode;
+  renderDetailActions?: (doc: LibraryDoc) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (doc: LibraryDoc) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  /** Largest upload in bytes. Default 5 MiB, the /api/g8 proxy's body limit. */
+  maxBytes?: number;
+}
+
+type Sheet = null | "upload" | "document" | "folder" | "rename";
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const ALL = "";
+
+/** The documents the "read text again" call will touch: PDF and Word files with stored bytes, in the folder and under it (the API matches on the path prefix). */
+export function reextractTargets(docs: LibraryDoc[], folderPath: string): LibraryDoc[] {
+  return docs.filter((d) => !d.deleted_at && d.has_file_data === true && (REEXTRACT_TYPES as readonly string[]).includes((d.file_type ?? "").toLowerCase()) && (folderPath === ALL || d.folder_path.startsWith(folderPath)));
+}
+
+export function LibraryPanel({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, maxBytes = DEFAULT_MAX_BYTES }: LibraryPanelProps) {
+  const brand = useBrand();
+  const [id, setId] = useUrlState("id", "");
+  const [folderParam, setFolderParam] = useUrlState("folder", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [typeFilter, setTypeFilter] = useState("");
+  const [sourceFilter, setSourceFilter] = useState("");
+  const [showRemoved, setShowRemoved] = useState(false);
+  const [sheet, setSheet] = useState<Sheet>(null);
+  const [folderToDelete, setFolderToDelete] = useState<LibraryFolder | null>(null);
+  const [rereading, setRereading] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+
+  const tree = useG8Query((signal) => g8Get<Rec>("/library/tree", {}, { signal }).then((r) => r.data), [], { key: ["documents", "tree"] });
+  const ready = tree.data !== undefined || tree.error !== undefined;
+  const foldersQ = useG8Query((signal) => g8Get<Rec>("/library/folders", {}, { signal }).then((r) => rowsOf<LibraryFolder>(r.data)), [], { enabled: ready, key: ["documents", "folders"] });
+  const docsQ = useG8Query(
+    (signal) => g8Get<Rec>("/library/documents", { include_deleted: showRemoved ? true : undefined }, { signal }).then((r) => rowsOf<LibraryDoc>(r.data)),
+    [showRemoved],
+    { key: ["documents", "list", showRemoved] },
+  );
+
+  const folders = (foldersQ.data ?? []).slice().sort((a, b) => a.full_path.localeCompare(b.full_path));
+  const docs = docsQ.data ?? [];
+  const folder = folders.find((f) => f.full_path === folderParam) ?? null;
+  const folderPath = folder ? folder.full_path : ALL;
+  const q = search.trim().toLowerCase();
+  const shown = docs.filter((d) => (folderPath === ALL || d.folder_path === folderPath) && (!typeFilter || (d.file_type ?? "") === typeFilter) && (!sourceFilter || (d.source ?? "") === sourceFilter) && (!q || `${docName(d)} ${d.file_name ?? ""} ${d.folder_path}`.toLowerCase().includes(q)));
+  const selected = docs.find((d) => d.id === id) ?? null;
+  const countIn = (path: string): number => docs.filter((d) => d.folder_path === path && !d.deleted_at).length;
+  const hasChildren = (f: LibraryFolder): boolean => folders.some((x) => x.parent_path === f.full_path);
+  const targets = reextractTargets(docs, folderPath);
+  const types = [...new Set(docs.map((d) => d.file_type).filter((t): t is string => Boolean(t)))].sort();
+  const sources = [...new Set(docs.map((d) => d.source).filter((s): s is string => Boolean(s)))].sort();
+  const known = docs.map((d) => d.file_size_bytes).filter((n): n is number => typeof n === "number");
+  const closeDetail = (): void => { setId(null); setView(null); };
+
+  const deleteFolder = useG8Mutation((f: LibraryFolder) => g8Delete(`/library/folders/${encodeURIComponent(f.id)}`), {
+    onSuccess: (_r, f) => { setFolderToDelete(null); if (folderParam === f.full_path) setFolderParam(null); },
+    invalidates: [["documents"]],
+  });
+  const rereadAll = useG8Mutation(() => g8Post<Rec>("/library/documents/reextract-all", undefined, { query: { folder_path: folder?.full_path } }), {
+    onSuccess: () => { setRereading(false); setNotice(`Asked the library to read the text of ${plural(targets.length, "document")} again.`); },
+    invalidates: [["documents"]],
+  });
+
+  const rail = (
+    <nav aria-label="Folders" className="grid gap-0.5 text-sm">
+      <button type="button" aria-current={folderPath === ALL} className={`flex items-center justify-between rounded-md px-2 py-1.5 text-left ${folderPath === ALL ? "bg-muted font-medium" : "hover:bg-muted"}`} onClick={() => setFolderParam(null)}>
+        <span className="flex items-center gap-2"><FolderOpen className="size-4" />All documents</span><span className="text-muted-foreground tabular-nums">{docsQ.data ? docs.filter((d) => !d.deleted_at).length : ""}</span>
+      </button>
+      {folders.map((f) => (
+        <button key={f.id} type="button" aria-current={folderPath === f.full_path} style={{ paddingLeft: `${0.5 + (f.full_path.split("/").length - 2) * 0.9}rem` }} className={`flex items-center justify-between rounded-md py-1.5 pr-2 text-left ${folderPath === f.full_path ? "bg-muted font-medium" : "hover:bg-muted"}`} onClick={() => setFolderParam(f.full_path)}>
+          <span className="flex min-w-0 items-center gap-2"><Folder className="size-4 shrink-0" /><span className="truncate">{f.name}</span></span><span className="text-muted-foreground tabular-nums">{docsQ.data ? countIn(f.full_path) : ""}</span>
+        </button>
+      ))}
+      {foldersQ.error ? <ApiError error={foldersQ.error} title="Could not load folders" compact onRetry={() => void foldersQ.refetch()} /> : null}
+    </nav>
+  );
+
+  const rows = docsQ.error ? <ApiError error={docsQ.error} title="Could not load documents" onRetry={() => void docsQ.refetch()} /> : docsQ.loading && !docsQ.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<FileText className="size-8" />} title={docs.length === 0 ? "Nothing in the library yet" : "No documents match"} description={docs.length === 0 ? `Add the material ${brand.name} should draw on: case studies, security policies, battlecards.` : folder && !q && !typeFilter && !sourceFilter ? `${folderLabel(folderPath)} has no documents.` : "Try another search or filter."} action={docs.length === 0 ? <Button onClick={() => setSheet("upload")}>Upload files</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === docs.length ? `All ${plural(docs.length, "document")}` : `${shown.length.toLocaleString()} of ${plural(docs.length, "document")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((d) => (
+          <li key={d.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${d.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(d.id)}>
+              <span className="block truncate font-medium">{docName(d)}</span>
+              <span className="text-muted-foreground block truncate text-xs">{folderLabel(d.folder_path)} · {fmtSize(d.file_size_bytes) || "-"} · {when(d.updated_at ?? d.created_at) || "-"}</span>
+            </button>
+            {d.deleted_at ? <StatusPill tone="warning">Removed</StatusPill> : null}
+            {d.file_type ? <StatusPill tone="info">{d.file_type.toUpperCase()}</StatusPill> : null}
+            {renderRowActions?.(d)}
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const list = (
+    <div className="grid gap-3">
+      <Toolbar
+        search={{ value: search, onChange: setSearch, placeholder: "Search documents" }}
+        filters={(
+          <>
+            <select aria-label="Filter by type" className={SELECT} value={typeFilter} onChange={(e) => setTypeFilter(e.target.value)}><option value="">All types</option>{types.map((t) => <option key={t} value={t}>{t.toUpperCase()}</option>)}</select>
+            <select aria-label="Filter by source" className={SELECT} value={sourceFilter} onChange={(e) => setSourceFilter(e.target.value)}><option value="">All sources</option>{sources.map((s) => <option key={s} value={s}>{s.charAt(0).toUpperCase() + s.slice(1)}</option>)}</select>
+            <label className="flex items-center gap-1.5 text-sm"><input type="checkbox" checked={showRemoved} onChange={(e) => { setShowRemoved(e.target.checked); closeDetail(); }} />Show removed</label>
+          </>
+        )}
+        actions={(
+          <>
+            {toolbarActions}
+            <Button size="sm" variant="outline" onClick={() => setSheet("folder")}><FolderPlus className="size-4" />New folder</Button>
+            <Button size="sm" variant="outline" onClick={() => setSheet("document")}><Plus className="size-4" />New document</Button>
+            <Button size="sm" onClick={() => setSheet("upload")}><Upload className="size-4" />Upload</Button>
+          </>
+        )}
+      />
+      <div className="grid gap-3 lg:grid-cols-[14rem_1fr]">
+        <div className="grid content-start gap-2">
+          {rail}
+          {folder ? (
+            <div className="flex flex-wrap gap-1">
+              <Button size="sm" variant="ghost" onClick={() => setSheet("rename")}><Pencil className="size-4" />Rename folder</Button>
+              <Button size="sm" variant="ghost" disabled={countIn(folder.full_path) > 0 || hasChildren(folder)} title={countIn(folder.full_path) > 0 || hasChildren(folder) ? "Only an empty folder can be deleted: move or delete what is inside first." : undefined} onClick={() => setFolderToDelete(folder)}><Trash2 className="size-4" />Delete folder</Button>
+            </div>
+          ) : null}
+          <Button size="sm" variant="ghost" disabled={targets.length === 0} title={targets.length === 0 ? "No PDF or Word files here to read again." : undefined} onClick={() => setRereading(true)}><ScanText className="size-4" />{folder ? "Read this folder's text again" : "Read all text again"}</Button>
+        </div>
+        <div className="min-w-0">{notice ? <p role="status" className="mb-2 text-sm">{notice}</p> : null}{rows}</div>
+      </div>
+    </div>
+  );
+
+  return (
+    <div className="grid gap-4">
+      <StatStrip items={[
+        { label: "Documents", value: docsQ.data ? docs.filter((d) => !d.deleted_at).length.toLocaleString() : "..." },
+        { label: "Folders", value: foldersQ.data ? folders.length.toLocaleString() : "..." },
+        { label: "Stored", value: known.length > 0 ? fmtSize(known.reduce((a, b) => a + b, 0)) : "-", hint: known.length < docs.length ? "Adds up the documents that report a size." : undefined },
+        { label: "Removed", value: showRemoved ? docs.filter((d) => d.deleted_at).length.toLocaleString() : "-", hint: showRemoved ? undefined : "Turn on Show removed to count them." },
+      ]} />
+      <SplitView
+        list={list}
+        detail={selected ? <LibraryDocumentDetail key={selected.id} doc={selected} folders={folders} onClose={closeDetail} onDeleted={closeDetail} onExpand={() => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined} renderActions={renderDetailActions} extraTabs={extraDetailTabs} /> : null}
+        detailOpen={Boolean(selected)}
+        onCloseDetail={closeDetail}
+        expanded={view === "full"}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        detailWidth="xl"
+      />
+      <FormSheet open={sheet === "upload"} onOpenChange={(o) => setSheet(o ? "upload" : null)} title="Upload files" description="Added to the folder you choose and read for their text.">
+        {sheet === "upload" ? <LibraryUpload folders={folders} folderPath={folderPath || ROOT} maxBytes={maxBytes} onDone={() => setSheet(null)} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "document"} onOpenChange={(o) => setSheet(o ? "document" : null)} title="New document" description="Text you write or paste. It is stored as typed." width="lg">
+        {sheet === "document" ? <LibraryDocumentForm folders={folders} folderPath={folderPath || ROOT} onCancel={() => setSheet(null)} onSaved={(d) => { setSheet(null); setId(d.id); }} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "folder"} onOpenChange={(o) => setSheet(o ? "folder" : null)} title="New folder">
+        {sheet === "folder" ? <LibraryFolderForm folders={folders} parentPath={folderPath || ROOT} onCancel={() => setSheet(null)} onSaved={(f) => { setSheet(null); setFolderParam(f.full_path); }} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "rename" && folder !== null} onOpenChange={(o) => setSheet(o ? "rename" : null)} title="Rename folder">
+        {sheet === "rename" && folder ? <LibraryFolderForm folder={folder} folders={folders} onCancel={() => setSheet(null)} onSaved={(f) => { setSheet(null); setFolderParam(f.full_path ?? folder.full_path); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={folderToDelete !== null}
+        tier="destructive"
+        title={`Delete the folder ${folderToDelete?.name ?? ""}?`}
+        affected={1}
+        description={<><p>An empty folder is removed. A folder with documents in it cannot be deleted.</p>{deleteFolder.error ? <ApiError error={deleteFolder.error} title="Could not delete the folder" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={deleteFolder.loading}
+        onCancel={() => setFolderToDelete(null)}
+        onConfirm={() => { if (folderToDelete) void deleteFolder.mutate(folderToDelete); }}
+      />
+      <ConfirmSpendDialog
+        open={rereading}
+        tier="destructive"
+        title={`Read the text of ${plural(targets.length, "document")} again?`}
+        affected={targets.length}
+        description={<><p>{folder ? `PDF and Word files in ${folderLabel(folder.full_path)} and under it` : "Every PDF and Word file in the library"} get their stored text replaced by a fresh read, including text edited by hand. The files themselves are not changed. A large library takes a while.</p>{rereadAll.error ? <ApiError error={rereadAll.error} title="Could not start the re-read" /> : null}</>}
+        confirmLabel="Read again"
+        confirming={rereadAll.loading}
+        onCancel={() => setRereading(false)}
+        onConfirm={() => void rereadAll.mutate(undefined)}
+      />
+    </div>
+  );
+}

package/blocks/documents/components/library-upload.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * LibraryUpload: add files to a Library folder.
+ *
+ * SDK operations, in order:
+ *   1. uploadLibraryDocument (POST /library/documents/upload)        write  one file (multipart)
+ *   2. uploadLibraryDocuments (POST /library/documents/upload-batch) write  several files at once; PARTIAL SUCCESS is normal
+ * Files are checked here before anything is sent: only the Library's file types, nothing empty, no file over `maxBytes`
+ * (default 5 MiB, the largest BODY the /api/g8 proxy forwards; the app itself takes 50 MB, so raise `maxBodyBytes` in the
+ * proxy route first), and at most 20 at a time. The proxy caps the whole request, not each file, so the files are sent in
+ * consecutive requests whose combined size (plus multipart overhead) stays under `maxBytes`; a lone file goes through the
+ * single route. Results are merged. A request that fails (a 413, a network error) marks only ITS files as failed and the later
+ * ones are still tried. The files that failed stay selected so a retry sends only them, never the ones that already landed. Text-bearing files are read for their text; images and
+ * spreadsheets are stored as bytes. Nothing here is billable, external or destructive.
+ */
+
+import { useRef, useState } from "react";
+import { Button, Label } from "@graph8/sdk/ui";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { BASE_OVERHEAD, DEFAULT_MAX_BYTES, FILE_OVERHEAD, LIBRARY_EXTENSIONS, fileLimit, ROOT, checkFiles, fmtSize, folderLabel } from "../lib/documents-types";
+import type { LibraryFolder, Rec } from "../lib/documents-types";
+
+export const MAX_BATCH = 20;
+
+/** Consecutive groups of files whose combined size and multipart overhead stay within `maxBytes` (a file over the limit on its own still gets a group of its own, to be refused by the proxy with a reason). */
+export function requestGroups(files: readonly File[], maxBytes: number): File[][] {
+  const groups: File[][] = [];
+  let current: File[] = [];
+  let size = BASE_OVERHEAD;
+  for (const f of files) {
+    const cost = f.size + FILE_OVERHEAD;
+    if (current.length > 0 && size + cost > maxBytes) {
+      groups.push(current);
+      current = [];
+      size = BASE_OVERHEAD;
+    }
+    current.push(f);
+    size += cost;
+  }
+  if (current.length > 0) groups.push(current);
+  return groups;
+}
+
+export interface LibraryUploadProps {
+  folders: LibraryFolder[];
+  /** Pre-select the destination folder. */
+  folderPath?: string;
+  /** Largest file accepted, in bytes. Default 5 MiB: the /api/g8 proxy rejects bigger bodies. */
+  maxBytes?: number;
+  onUploaded?: () => void;
+  onDone?: () => void;
+}
+
+interface Outcome { added: number; failed: { filename: string; error: string }[]; warnings: string[] }
+const reasonOf = (err: unknown): string => (err instanceof Error && err.message ? err.message : "The request failed.");
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function LibraryUpload({ folders, folderPath, maxBytes = DEFAULT_MAX_BYTES, onUploaded, onDone }: LibraryUploadProps) {
+  const [folder, setFolder] = useState(folderPath || ROOT);
+  const [picked, setPicked] = useState<File[]>([]);
+  const [notes, setNotes] = useState<string[]>([]);
+  const [outcome, setOutcome] = useState<Outcome | null>(null);
+  const input = useRef<HTMLInputElement>(null);
+  const choices = [...new Set([ROOT, ...folders.map((f) => f.full_path), folder])];
+
+  const choose = (list: FileList | null): void => {
+    const { ok, problems } = checkFiles(Array.from(list ?? []), LIBRARY_EXTENSIONS, fileLimit(maxBytes));
+    const over = ok.length > MAX_BATCH ? [`Add at most ${MAX_BATCH} files at a time; the first ${MAX_BATCH} are kept.`] : [];
+    setPicked(ok.slice(0, MAX_BATCH));
+    setNotes([...problems, ...over]);
+    setOutcome(null);
+  };
+
+  const send = useG8Mutation(
+    async (files: File[]): Promise<Outcome> => {
+      const total: Outcome = { added: 0, failed: [], warnings: [] };
+      for (const group of requestGroups(files, maxBytes)) {
+        try {
+          const part = await sendGroup(group, folder);
+          total.added += part.added;
+          total.failed.push(...part.failed);
+          total.warnings.push(...part.warnings);
+        } catch (err) {
+          // One request failing (a 413, a network error) fails only its own files; the next group is still tried.
+          total.failed.push(...group.map((f) => ({ filename: f.name, error: reasonOf(err) })));
+        }
+      }
+      return total;
+    },
+    {
+      onSuccess: (r, files) => {
+        setOutcome(r);
+        const failedNames = new Set(r.failed.map((f) => f.filename));
+        setPicked(files.filter((f) => failedNames.has(f.name)));
+        if (input.current) input.current.value = "";
+        onUploaded?.();
+      },
+      invalidates: [["documents"]],
+    },
+  );
+
+  const finished = outcome !== null && outcome.failed.length === 0;
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (picked.length > 0) void send.mutate(picked); }}>
+      <div>
+        <Label htmlFor="g8-du-folder" className="mb-1">Add to folder</Label>
+        <select id="g8-du-folder" className={SELECT} value={folder} onChange={(e) => setFolder(e.target.value)}>
+          {choices.map((p) => <option key={p} value={p}>{folderLabel(p)}</option>)}
+        </select>
+      </div>
+      <div>
+        <Label htmlFor="g8-du-files" className="mb-1">Files</Label>
+        <input ref={input} id="g8-du-files" type="file" multiple accept={LIBRARY_EXTENSIONS.map((e) => `.${e}`).join(",")} onChange={(e) => choose(e.target.files)} className="border-input bg-background w-full rounded-md border p-2 text-sm" />
+        <p className="text-muted-foreground mt-1 text-xs">{LIBRARY_EXTENSIONS.join(", ")}. Up to {fmtSize(fileLimit(maxBytes))} each. The server takes {fmtSize(maxBytes)} per request, so several files are sent in several requests. {MAX_BATCH} files at a time.</p>
+      </div>
+      {notes.length > 0 ? <ul role="alert" className="text-error list-disc pl-5 text-xs">{notes.map((n) => <li key={n}>{n}</li>)}</ul> : null}
+      {picked.length > 0 ? (
+        <ul aria-label="Files to add" className="divide-y rounded-md border text-sm">
+          {picked.map((f) => <li key={f.name} className="flex justify-between gap-2 p-2"><span className="truncate">{f.name}</span><span className="text-muted-foreground shrink-0">{fmtSize(f.size)}</span></li>)}
+        </ul>
+      ) : null}
+            {outcome ? (
+        <div role="status" className="grid gap-1 rounded-md border p-3 text-sm">
+          <p className="font-medium">{outcome.failed.length === 0 ? `${plural(outcome.added, "file")} added.` : `${outcome.added} added, ${outcome.failed.length} not added.`}</p>
+          {outcome.failed.map((f) => <p key={f.filename} className="text-error text-xs">{f.filename}: {f.error}</p>)}
+          {outcome.warnings.map((w) => <p key={w} className="text-muted-foreground text-xs">{w}</p>)}
+          {outcome.failed.length > 0 ? <p className="text-muted-foreground text-xs">Only the files that failed are still selected, so adding again will not duplicate the others.</p> : null}
+        </div>
+      ) : null}
+      <div className="flex gap-2">
+        {finished ? <Button type="button" onClick={onDone}>Done</Button> : <Button type="submit" loading={send.loading} disabled={picked.length === 0}>{picked.length > 1 ? `Add ${picked.length} files` : "Add file"}</Button>}
+        {!finished && onDone ? <Button type="button" variant="outline" onClick={onDone}>Close</Button> : null}
+      </div>
+    </form>
+  );
+}
+
+/** One request: a lone file through the single route, several through the batch route (partial success is normal there). */
+async function sendGroup(files: File[], folder: string): Promise<Outcome> {
+  const form = new FormData();
+  form.append("folder_path", folder);
+  if (files.length === 1) {
+    form.append("file", files[0]);
+    await g8Post("/library/documents/upload", form);
+    return { added: 1, failed: [], warnings: [] };
+  }
+  for (const f of files) form.append("files", f);
+  const data = (await g8Post<Rec>("/library/documents/upload-batch", form)).data ?? {};
+  const ok = Array.isArray(data.success) ? (data.success as Rec[]) : [];
+  const bad = Array.isArray(data.failed) ? (data.failed as Rec[]) : [];
+  return {
+    added: ok.length,
+    failed: bad.map((b) => ({ filename: String(b.filename ?? "A file"), error: String(b.error ?? "It could not be added.") })),
+    warnings: ok.filter((o) => o.warning).map((o) => `${String(o.filename ?? "A file")}: ${String(o.warning)}`),
+  };
+}