@graph8/sdk 0.373.0 → 0.374.0

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

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * LibraryDocumentDetail: one Library document with its text, its facts and every action on it.
+ *
+ * SDK operations, in order:
+ *   1. getLibraryDocument (GET /library/documents/{document_id})                 read         the full record, with its extracted text
+ *   2. downloadLibraryDocument (GET /library/documents/{document_id}/download)  read         the ORIGINAL bytes (not the JSON envelope), saved as a file
+ *   3. updateLibraryDocument, through LibraryDocumentForm                         write        rename, move or change the text
+ *   4. reextractLibraryDocument (POST .../reextract)                             write        read a PDF or DOCX's text again; replaces the stored text, never the file
+ *   5. refreshLibraryDocument (POST .../refresh)                                 write        re-fetch a SCRAPED page (the API may answer that it cannot yet; its message is shown as is)
+ *   6. restoreLibraryDocument (POST .../restore)                                 write        bring back a removed document
+ *   7. deleteLibraryDocument (DELETE .../{document_id})                          DESTRUCTIVE  removes the row AND its bytes for good; behind ConfirmSpendDialog
+ * Only the owner or an admin can delete (the API says 403 otherwise and the reason is shown). Nothing here is billable or external.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Download, FileText, Pencil, RefreshCw, RotateCcw, ScanText, Trash2 } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+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 { downloadFile } from "../lib/download";
+import { REEXTRACT_TYPES, docName, fmtSize, folderLabel, when } from "../lib/documents-types";
+import type { LibraryDoc, LibraryFolder, Rec } from "../lib/documents-types";
+import { LibraryDocumentForm } from "./library-document-form";
+
+export interface LibraryDocumentDetailProps {
+  doc: LibraryDoc;
+  folders: LibraryFolder[];
+  onClose: () => void;
+  onDeleted?: (doc: LibraryDoc) => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  renderActions?: (doc: LibraryDoc) => ReactNode;
+  extraTabs?: { id: string; label: string; render: (doc: LibraryDoc) => ReactNode }[];
+}
+
+const sourceLabel = (s: string | null | undefined): string => (s ? s.charAt(0).toUpperCase() + s.slice(1) : "");
+
+export function LibraryDocumentDetail({ doc, folders, onClose, onDeleted, onExpand, onCollapse, renderActions, extraTabs }: LibraryDocumentDetailProps) {
+  const [editing, setEditing] = useState(false);
+  const [deleting, setDeleting] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [downloadError, setDownloadError] = useState<unknown>(undefined);
+  const [downloading, setDownloading] = useState(false);
+
+  const full = useG8Query(
+    (signal) => g8Get<LibraryDoc>(`/library/documents/${encodeURIComponent(doc.id)}`, {}, { signal }).then((r) => r.data),
+    [doc.id],
+    { key: ["documents", "doc", doc.id], placeholderData: doc },
+  );
+  const d = full.data && full.data.id === doc.id ? full.data : doc;
+  const removed = Boolean(d.deleted_at);
+  const type = (d.file_type ?? "").toLowerCase();
+  const canReextract = (REEXTRACT_TYPES as readonly string[]).includes(type) && d.has_file_data === true && !removed;
+
+  const reextract = useG8Mutation(() => g8Post<Rec>(`/library/documents/${encodeURIComponent(doc.id)}/reextract`), {
+    onSuccess: (r) => { const n = (r.data as Rec | null)?.content_length; setNotice(typeof n === "number" ? `Text read again: ${n.toLocaleString()} characters.` : "Text read again."); },
+    invalidates: [["documents"]],
+  });
+  const refresh = useG8Mutation(() => g8Post<Rec>(`/library/documents/${encodeURIComponent(doc.id)}/refresh`), {
+    onSuccess: (r) => { const m = (r.data as Rec | null)?.message; setNotice(typeof m === "string" && m ? m : "Refresh requested."); },
+    invalidates: [["documents"]],
+  });
+  const restore = useG8Mutation(() => g8Post<LibraryDoc>(`/library/documents/${encodeURIComponent(doc.id)}/restore`), { onSuccess: () => setNotice("Document restored."), invalidates: [["documents"]] });
+  const remove = useG8Mutation(() => g8Delete(`/library/documents/${encodeURIComponent(doc.id)}`), {
+    onSuccess: () => { setDeleting(false); onDeleted?.(doc); },
+    invalidates: [["documents"]],
+  });
+
+  const save = async (): Promise<void> => {
+    setDownloading(true);
+    setDownloadError(undefined);
+    try {
+      await downloadFile(`/library/documents/${encodeURIComponent(doc.id)}/download`, d.file_name || docName(d));
+    } catch (err) {
+      setDownloadError(err);
+    } finally {
+      setDownloading(false);
+    }
+  };
+
+  const preview = full.error && !full.data ? <ApiError error={full.error} title="Could not load this document" onRetry={() => void full.refetch()} /> : full.isPlaceholderData ? (
+    <Skeleton className="h-32 w-full" aria-label="Loading text" />
+  ) : d.content ? (
+    <pre aria-label="Document text" className="bg-muted max-h-[28rem] overflow-auto whitespace-pre-wrap rounded-md p-3 text-sm">{d.content}</pre>
+  ) : (
+    <EmptyState compact icon={<FileText className="size-8" />} title="No text to show" description={type === "png" || type === "jpg" || type === "jpeg" ? "Images are stored as files. Download it to see it." : d.has_file_data ? "No text was read from this file. Download the original, or read it again." : "This document has no text."} />
+  );
+
+  const actions = (
+    <>
+      {renderActions?.(d)}
+      {removed ? (
+        <Button size="sm" variant="outline" loading={restore.loading} onClick={() => void restore.mutate(undefined)}><RotateCcw className="size-4" />Restore</Button>
+      ) : (
+        <Button size="sm" variant="outline" disabled={full.isPlaceholderData} onClick={() => setEditing(true)}><Pencil className="size-4" />Edit</Button>
+      )}
+      <Button size="sm" variant="outline" loading={downloading} onClick={() => void save()}><Download className="size-4" />Download</Button>
+      {canReextract ? <Button size="sm" variant="outline" loading={reextract.loading} onClick={() => void reextract.mutate(undefined)}><ScanText className="size-4" />Read text again</Button> : null}
+      {d.source === "scrape" && !removed ? <Button size="sm" variant="outline" loading={refresh.loading} onClick={() => void refresh.mutate(undefined)}><RefreshCw className="size-4" />Refresh from source</Button> : null}
+      <Button size="sm" variant="outline" onClick={() => setDeleting(true)}><Trash2 className="size-4" />Delete</Button>
+    </>
+  );
+
+  return (
+    <>
+      <DetailPanel
+        title={docName(d)}
+        subtitle={`${folderLabel(d.folder_path)}${d.file_name && d.file_name !== d.display_name ? ` · ${d.file_name}` : ""}`}
+        badges={<>{type ? <StatusPill tone="info">{type.toUpperCase()}</StatusPill> : null}{removed ? <StatusPill tone="warning">Removed</StatusPill> : null}</>}
+        actions={actions}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+        summary={notice || reextract.error || refresh.error || restore.error || downloadError ? (
+          <div className="grid gap-2 px-4 pt-3">
+            {notice ? <p role="status" className="text-sm">{notice}</p> : null}
+            {reextract.error ? <ApiError error={reextract.error} title="Could not read the text again" compact /> : null}
+            {refresh.error ? <ApiError error={refresh.error} title="Could not refresh the document" compact /> : null}
+            {restore.error ? <ApiError error={restore.error} title="Could not restore the document" compact /> : null}
+            {downloadError ? <ApiError error={downloadError} title="Could not download the file" compact /> : null}
+          </div>
+        ) : undefined}
+        tabs={[
+          { id: "text", label: "Text", content: preview },
+          {
+            id: "details",
+            label: "Details",
+            content: (
+              <KeyValueList columns={2} items={[
+                { label: "Title", value: d.display_name },
+                { label: "File name", value: d.file_name },
+                { label: "Type", value: type ? type.toUpperCase() : "" },
+                { label: "Folder", value: folderLabel(d.folder_path) },
+                { label: "Size", value: fmtSize(d.file_size_bytes) },
+                { label: "Source", value: sourceLabel(d.source) },
+                { label: "Added by", value: d.owner_name },
+                { label: "Added", value: when(d.created_at) },
+                { label: "Updated", value: when(d.updated_at) },
+                { label: "Searchable by the AI", value: d.indexed_at ? `Since ${when(d.indexed_at)}` : "Not yet" },
+                { label: "Version", value: d.current_version != null ? String(d.current_version) : "" },
+                { label: "Document id", value: d.id, mono: true },
+              ]} />
+            ),
+          },
+          ...(extraTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(d) })),
+        ]}
+      />
+      <FormSheet open={editing} onOpenChange={setEditing} title="Edit document" description="Only what you change is saved." width="lg">
+        {editing ? <LibraryDocumentForm document={doc} folders={folders} onCancel={() => setEditing(false)} onSaved={() => { setEditing(false); setNotice("Saved."); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={deleting}
+        tier="destructive"
+        title={`Delete ${docName(d)}?`}
+        affected={1}
+        description={<><p>The document and its stored file are removed for good. It cannot be restored. Only its owner or an admin can delete it.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the document" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setDeleting(false)}
+        onConfirm={() => void remove.mutate(undefined)}
+      />
+    </>
+  );
+}

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>
+  );
+}