@anchrd/intel-ui 0.3.0 → 0.5.0

package/src/app/app-tree/app-tree.tsx

@@ -0,0 +1,798 @@
+import { useMutation, useQueries, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
+import {
+  ChevronRight,
+  CornerLeftUp,
+  FileText,
+  Folder,
+  FolderOpen,
+  Paperclip,
+  Plus,
+  Table,
+  Upload,
+  Workflow,
+} from "lucide-react";
+import { useRef, useState } from "react";
+import {
+  type MoveDestination,
+  MoveDialog,
+  moveErrorKey,
+  moveVerdict,
+  parentOf,
+} from "@/app/tree-move/tree-move.tsx";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+} from "@/components/ui/sidebar";
+import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
+import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { Modal } from "@/modal/modal.tsx";
+import { ResourceMenu } from "@/resource-menu/resource-menu.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import { selectedFrom } from "@/router/selection-search.ts";
+
+type NewKind = "folder" | "document" | "table" | "flow";
+type Creating = { parentId: string | null; kind: NewKind };
+
+const icons = {
+  folder: Folder,
+  document: FileText,
+  attachment: Paperclip,
+  table: Table,
+  flow: Workflow,
+} as const;
+
+// Attachments are inlined as base64, so the browser holds the file twice while it uploads.
+const MaxUploadBytes = 15_000_000;
+
+async function fileBase64(file: File): Promise<string> {
+  if (file.size > MaxUploadBytes) throw new Error("Attachment exceeds the 15 MB upload limit");
+  return await new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(reader.error ?? new Error("Attachment could not be read"));
+    reader.onload = () => {
+      const result = reader.result;
+      if (typeof result !== "string" || !result.includes(",")) {
+        reject(new Error("Attachment could not be encoded"));
+        return;
+      }
+      resolve(result.slice(result.indexOf(",") + 1));
+    };
+    reader.readAsDataURL(file);
+  });
+}
+
+// A level is either a folder of the shared tree or the flows one flow calls. The second kind is
+// derived from that flow's graph, not from `parent_id` (ADR-0004 §3), which is why it is its own
+// level rather than another folder.
+type Level = { id: string | null; type: "folder" | "flow" };
+
+// One key per level. `null` is the root; every expanded row adds one of its own, and nothing else is
+// ever asked for.
+function levelKey(level: Level): readonly unknown[] {
+  return level.type === "flow" ? ["flow-calls", level.id] : ["tree", level.id];
+}
+
+// The optimistic row, filed where it is about to land. Its own parent has to travel with it, or the
+// plus on the moved row would still file into the folder it just left.
+function withParent(entry: TreeEntry, parentId: string | null): TreeEntry {
+  return entry.type === "knowledge"
+    ? { ...entry, node: { ...entry.node, parentId } }
+    : { ...entry, flow: { ...entry.flow, parentId } };
+}
+
+export function AppTree() {
+  const { data, i18n } = useIntelRouterContext();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const [expanded, setExpanded] = useState<readonly Level[]>([]);
+  const [creating, setCreating] = useState<Creating | null>(null);
+  const [uploadTo, setUploadTo] = useState<string | null>(null);
+  const uploadInput = useRef<HTMLInputElement>(null);
+  const [dragged, setDragged] = useState<TreeEntry | null>(null);
+  const draggedRef = useRef<TreeEntry | null>(null);
+  // Which target the pointer is over: `undefined` for none, `null` for the root strip, an id for a
+  // folder row. Three answers, because "the root" and "nothing" are not the same drop.
+  const [over, setOver] = useState<string | null | undefined>(undefined);
+  const [moving, setMoving] = useState<{
+    entry: TreeEntry;
+    initial: MoveDestination | null;
+  } | null>(null);
+
+  const location = useRouterState({
+    select: (state) => ({
+      pathname: state.location.pathname,
+      select: selectedFrom(state.location.search),
+    }),
+  });
+
+  // ⚠️ The whole point of #11: one query per level, and a level only exists while its folder is
+  // open. A recursive load would put an N+1 on every page of the app, because the tree is now on
+  // every page.
+  const parents: Level[] = [{ id: null, type: "folder" }, ...expanded];
+  const levels = useQueries({
+    queries: parents.map((parent) => ({
+      queryKey: levelKey(parent),
+      queryFn: async () =>
+        parent.type === "flow" && parent.id !== null
+          ? // The same row a folder's level builds for a flow, from the same function: what hangs
+            // under an expanded flow differs in where the flows come from, never in what a flow row
+            // is (#30).
+            (await data.listFlowCalls(parent.id)).items.map(flowEntry)
+          : await data.listTreeChildren(parent.id),
+    })),
+  });
+  const levelFor = (level: Level) =>
+    levels[parents.findIndex((entry) => entry.id === level.id && entry.type === level.type)];
+  const root = levels[0];
+
+  function toggle(level: Level & { id: string }, open: boolean) {
+    setExpanded((current) => {
+      const rest = current.filter((entry) => entry.id !== level.id || entry.type !== level.type);
+      return open ? [...rest, level] : rest;
+    });
+  }
+
+  // ⚠️ The level a row appears in is not the only thing that goes stale. The header search reads
+  // the whole flow list, and the graph is what the link picker and the flow editor's Knowledge step
+  // offer — a row created here has to reach those too, or another screen keeps showing yesterday.
+  async function reveal(
+    parentId: string | null,
+    collection: "flows" | "knowledge-graph",
+  ): Promise<void> {
+    if (parentId !== null) toggle({ id: parentId, type: "folder" }, true);
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: levelKey({ id: parentId, type: "folder" }) }),
+      queryClient.invalidateQueries({ queryKey: [collection] }),
+      // The graph view of that same level draws exactly this list, so it goes stale for the same
+      // reason the level does (#19).
+      queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+    ]);
+  }
+
+  const create = useMutation({
+    mutationFn: async ({
+      parentId,
+      kind,
+      title,
+      columns,
+    }: Creating & { title: string; columns: string[] }) => {
+      if (kind === "flow") {
+        const flow = await data.createFlow({
+          parentId,
+          title,
+          description: null,
+          idempotencyKey: crypto.randomUUID(),
+        });
+        return { area: "/flows" as const, id: flow.id, parentId, collection: "flows" as const };
+      }
+      const node = await data.createKnowledge({
+        parentId,
+        kind,
+        title,
+        description: null,
+        contextPolicy: "relevant",
+        idempotencyKey: crypto.randomUUID(),
+      });
+      // ⚠️ Two calls, because they are two things: the node is a row in the tree, the header is the
+      // contract every later append is measured against (#40). A table without a header would sit
+      // there refusing every append, so the second call happens here rather than being left to the
+      // person who created it.
+      if (kind === "table") {
+        await data.defineKnowledgeTable({
+          nodeId: node.id,
+          columns,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      }
+      return {
+        area: "/knowledge" as const,
+        id: node.id,
+        parentId,
+        collection: "knowledge-graph" as const,
+      };
+    },
+    onSuccess: async (created) => {
+      setCreating(null);
+      await reveal(created.parentId, created.collection);
+      await navigate({ to: created.area, search: { select: created.id } });
+    },
+  });
+
+  const upload = useMutation({
+    mutationFn: async ({ parentId, file }: { parentId: string | null; file: File }) => {
+      const contentBase64 = await fileBase64(file);
+      const node = await data.createKnowledge({
+        parentId,
+        kind: "attachment",
+        title: file.name,
+        description: null,
+        contextPolicy: "relevant",
+        idempotencyKey: crypto.randomUUID(),
+      });
+      try {
+        await data.saveKnowledgeAttachment({
+          nodeId: node.id,
+          baseVersionId: null,
+          contentBase64,
+          mediaType: file.type || "application/octet-stream",
+          idempotencyKey: crypto.randomUUID(),
+        });
+      } catch (error) {
+        // An attachment node without bytes is a row nobody can open. Take it back rather than
+        // leaving it in the tree, but never let the cleanup hide the real failure.
+        const current = await data.getKnowledge(node.id).catch(() => null);
+        if (current?.version === null && current.node.updatedAt === node.updatedAt) {
+          await data
+            .archiveKnowledge({
+              nodeId: node.id,
+              baseUpdatedAt: current.node.updatedAt,
+              archived: true,
+              idempotencyKey: crypto.randomUUID(),
+            })
+            .catch(() => undefined);
+        }
+        throw error;
+      }
+      return { id: node.id, parentId };
+    },
+    onSuccess: async (created) => {
+      await reveal(created.parentId, "knowledge-graph");
+      await navigate({ to: "/knowledge", search: { select: created.id } });
+    },
+  });
+
+  // ⚠️ Optimistic, never authoritative. The row is lifted out of one level and dropped into the
+  // other before the server answers, and every refusal — 403, `parent_not_folder`, `move_cycle`,
+  // `update_conflict` — puts both levels back exactly as they were and then re-reads them, so a
+  // rejected move cannot leave a row standing twice or nowhere at all.
+  const move = useMutation({
+    mutationFn: async ({
+      entry,
+      destination,
+    }: {
+      entry: TreeEntry;
+      destination: MoveDestination;
+    }) => {
+      // `baseUpdatedAt` travels with the move: it is what turns a concurrent edit into a 409 the
+      // view can act on instead of an overwrite nobody notices.
+      if (entry.type === "flow") {
+        await data.updateFlow({
+          flowId: entry.id,
+          baseUpdatedAt: entry.flow.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      } else {
+        await data.updateKnowledge({
+          nodeId: entry.id,
+          baseUpdatedAt: entry.node.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      }
+    },
+    onMutate: async ({ entry, destination }) => {
+      const fromKey = levelKey({ id: parentOf(entry), type: "folder" });
+      const toKey = levelKey({ id: destination.id, type: "folder" });
+      await Promise.all([
+        queryClient.cancelQueries({ queryKey: fromKey }),
+        queryClient.cancelQueries({ queryKey: toKey }),
+      ]);
+      const snapshot = [
+        [fromKey, queryClient.getQueryData<TreeEntry[]>(fromKey)],
+        [toKey, queryClient.getQueryData<TreeEntry[]>(toKey)],
+      ] as const;
+      queryClient.setQueryData<TreeEntry[]>(fromKey, (current) =>
+        current?.filter((row) => row.id !== entry.id),
+      );
+      // A level nobody has opened stays unloaded: writing one here would show a folder's contents
+      // that were never read.
+      queryClient.setQueryData<TreeEntry[]>(toKey, (current) =>
+        current === undefined
+          ? current
+          : [...current.filter((row) => row.id !== entry.id), withParent(entry, destination.id)],
+      );
+      return { snapshot };
+    },
+    onError: (_error, _variables, context) => {
+      for (const [key, value] of context?.snapshot ?? []) queryClient.setQueryData(key, value);
+    },
+    onSuccess: (_result, { destination }) => {
+      if (destination.id !== null) toggle({ id: destination.id, type: "folder" }, true);
+    },
+    onSettled: async (_result, _error, { entry, destination }) => {
+      await Promise.all([
+        queryClient.invalidateQueries({
+          queryKey: levelKey({ id: parentOf(entry), type: "folder" }),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: levelKey({ id: destination.id, type: "folder" }),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: [entry.type === "flow" ? "flows" : "knowledge-graph"],
+        }),
+        queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+      ]);
+    },
+  });
+
+  function startMove(entry: TreeEntry, destination: MoveDestination | null) {
+    move.reset();
+    setMoving({ entry, initial: destination });
+  }
+
+  // What a drop on this target would do. `undefined` means nothing is being dragged, so the target
+  // is not a target at all.
+  function verdictFor(
+    carried: TreeEntry | null,
+    targetId: string | null,
+    targetAncestors: ReadonlySet<string>,
+  ) {
+    if (!carried) return undefined;
+    return moveVerdict({
+      draggedId: carried.id,
+      draggedParentId: parentOf(carried),
+      targetId,
+      targetAncestors,
+    });
+  }
+
+  function dropHandlers(target: MoveDestination, ancestors: ReadonlySet<string>) {
+    // Two readings of the same question. The render-time one drives what is on screen; the handlers
+    // ask `draggedRef` instead, because a drag's events can all arrive before React has re-rendered
+    // and a closure over the previous render would then move the previous row.
+    const verdict = verdictFor(dragged, target.id, ancestors);
+    return {
+      verdict,
+      props: {
+        onDragOver: (event: React.DragEvent) => {
+          if (verdictFor(draggedRef.current, target.id, ancestors) !== "ok") {
+            event.dataTransfer.dropEffect = "none";
+            return;
+          }
+          // Without `preventDefault` the browser refuses the drop, so this is also what makes the
+          // "not allowed" cursor appear over every target the tree has ruled out.
+          event.preventDefault();
+          event.dataTransfer.dropEffect = "move";
+          setOver(target.id);
+        },
+        onDragLeave: () => setOver((current) => (current === target.id ? undefined : current)),
+        onDrop: (event: React.DragEvent) => {
+          event.preventDefault();
+          const carried = draggedRef.current;
+          setOver(undefined);
+          setDragged(null);
+          draggedRef.current = null;
+          if (carried && verdictFor(carried, target.id, ancestors) === "ok") {
+            startMove(carried, target);
+          }
+        },
+      },
+    };
+  }
+
+  function startUpload(parentId: string | null) {
+    setUploadTo(parentId);
+    uploadInput.current?.click();
+  }
+
+  function renderLevel(parent: Level, ancestors: ReadonlySet<string>, label?: string) {
+    const level = levelFor(parent);
+    if (!level || level.isPending) {
+      return (
+        <SidebarMenu aria-label={label}>
+          {[0, 1, 2].map((row) => (
+            <SidebarMenuItem key={row}>
+              <SidebarMenuSkeleton showIcon />
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      );
+    }
+    if (level.isError) {
+      return (
+        <div role="alert" className="space-y-2 px-2 py-1.5 text-sm">
+          <p className="text-destructive">{i18n.t("tree.failed")}</p>
+          <button
+            type="button"
+            onClick={() => void level.refetch()}
+            className="rounded-md border px-2 py-1 text-xs outline-none hover:bg-sidebar-accent focus-visible:ring-2 focus-visible:ring-sidebar-ring"
+          >
+            {i18n.t("common.retry")}
+          </button>
+        </div>
+      );
+    }
+    // ⚠️ The cycle guard, in the form a per-level load needs: a broken `parentId` that points back
+    // up would otherwise open the same folder inside itself for as long as anyone keeps clicking.
+    // The recursion is gone, so the depth limit that used to save us is gone with it; what stops it
+    // now is that a row already on the path from the root is not rendered again.
+    const entries = level.data?.filter((entry) => !ancestors.has(entry.id)) ?? [];
+    if (entries.length === 0) {
+      // ⚠️ An open folder with nothing in it says nothing (#24): the missing row already is the
+      // answer, and the sentence used to repeat itself once per opened folder. The other two stay,
+      // and deliberately: the empty root is the whole of the navigation, so a blank sidebar on a
+      // fresh installation would leave a new user without any way in; and "this flow calls no other
+      // flow" is a different statement from "empty" — it is an answer, not filler.
+      const message =
+        parent.type === "flow"
+          ? i18n.t("tree.noCalls")
+          : parent.id === null
+            ? i18n.t("tree.empty")
+            : null;
+      // The folder keeps its list, empty. The structure is what carries "there is nothing here" to
+      // a screen reader — "list, 0 items" — which is the same answer the missing rows give a reader
+      // who can see them, and neither of them is a sentence.
+      return message === null ? (
+        <SidebarMenu aria-label={label} />
+      ) : (
+        <p className="px-2 py-1.5 text-sm text-muted-foreground">{message}</p>
+      );
+    }
+    return (
+      <SidebarMenu aria-label={label}>
+        {entries.map((entry) => renderRow(entry, ancestors, parent.type === "flow"))}
+      </SidebarMenu>
+    );
+  }
+
+  // ⚠️ `derived` is the level under a flow: its rows are that flow's calls, read out of its graph
+  // (ADR-0004 §3, `levelKey`). Nothing there has a `parent_id` to rewrite, so those rows are neither
+  // dragged nor dropped on — a move made there would silently be a move of the shared flow itself.
+  function renderRow(entry: TreeEntry, ancestors: ReadonlySet<string>, derived: boolean) {
+    const isFolder = entry.kind === "folder";
+    // ⚠️ A flow expands too, and what appears under it is what it calls — read from its graph, not
+    // from `parent_id`. A flow reused by three callers therefore shows up under all three, which is
+    // the answer to "what do I run, and how" (ADR-0004 §3).
+    const level: Level & { id: string } = { id: entry.id, type: isFolder ? "folder" : "flow" };
+    const expandable = isFolder || entry.type === "flow";
+    const isOpen =
+      expandable && expanded.some((open) => open.id === entry.id && open.type === level.type);
+    const Icon = isOpen && isFolder ? FolderOpen : icons[entry.kind];
+    const area = entry.type === "flow" ? "/flows" : "/knowledge";
+    const isActive = location.select === entry.id && location.pathname === area;
+    // A row's plus files into that row's place: inside a folder, beside anything else.
+    const target = isFolder ? entry.id : parentOf(entry);
+    // Only a folder takes a drop, and only on a level that owns its rows. Everything else keeps the
+    // default cursor while a drag is in progress, which is the answer "not here" without a word.
+    const drop =
+      isFolder && !derived ? dropHandlers({ id: entry.id, title: entry.title }, ancestors) : null;
+    const isDragged = dragged?.id === entry.id;
+    // While a drag is in progress every row says which of the three it is: the row being carried,
+    // a folder that would take it, or something that would not. Silence on the last two is what
+    // turns a drag into a guess that only the drop answers.
+    const highlight =
+      dragged === null || isDragged
+        ? ""
+        : drop?.verdict === "ok"
+          ? over === entry.id
+            ? "bg-sidebar-accent ring-2 ring-sidebar-ring"
+            : "ring-1 ring-sidebar-border"
+          : "opacity-40";
+
+    return (
+      <SidebarMenuItem key={entry.id} className="group/row">
+        {/* ⚠️ The colouring sits on the ROW, not on the button inside it — the difference the
+            ticket is about. It used to hang on `SidebarMenuButton`, whose siblings the plus and this
+            menu are, so the grey stopped short of them: two icons standing outside the very row they
+            operate, with a pale strip left over on the right. Taken from gate, where the same
+            mistake was made and unmade three times (`service-tree.tsx`, GATE-76/-78/-81) — there the
+            row carries the fill and `flex-1` on the label pushes the actions to the end *inside* it.
+            The button keeps its own hover and active fill switched off rather than doubled, so the
+            row shows one surface instead of two overlapping ones. */}
+        <div
+          className={`flex items-center gap-0.5 rounded-md pr-1 transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground ${
+            isActive ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : ""
+          }`}
+        >
+          {expandable ? (
+            <button
+              type="button"
+              aria-expanded={isOpen}
+              aria-label={i18n.t(
+                isFolder
+                  ? isOpen
+                    ? "tree.collapse"
+                    : "tree.expand"
+                  : isOpen
+                    ? "tree.collapseCalls"
+                    : "tree.expandCalls",
+                { title: entry.title },
+              )}
+              onClick={() => toggle(level, !isOpen)}
+              // The icons inside a coloured row need a step of their own, or their hover would be
+              // the row's colour on the row's colour and read as nothing at all.
+              className="shrink-0 rounded-md p-1 text-sidebar-foreground/70 outline-none hover:bg-sidebar-accent-foreground/10 focus-visible:ring-2 focus-visible:ring-sidebar-ring"
+            >
+              <ChevronRight
+                aria-hidden="true"
+                className={`size-3.5 transition-transform ${isOpen ? "rotate-90" : ""}`}
+              />
+            </button>
+          ) : (
+            <span aria-hidden="true" className="size-5 shrink-0" />
+          )}
+          {/* The row's own control is what is grabbed and what is dropped on: a real button, so the
+              gesture rides on something that is already focusable and named rather than on a bare
+              div that assistive technology would have to be told about twice. */}
+          <SidebarMenuButton
+            isActive={isActive}
+            draggable={!derived}
+            onDragStart={(event) => {
+              event.dataTransfer.effectAllowed = "move";
+              event.dataTransfer.setData("text/plain", entry.id);
+              draggedRef.current = entry;
+              setDragged(entry);
+            }}
+            onDragEnd={() => {
+              draggedRef.current = null;
+              setDragged(null);
+              setOver(undefined);
+            }}
+            {...(drop?.props ?? {})}
+            data-drop={
+              dragged === null ? undefined : isDragged ? "dragged" : (drop?.verdict ?? "none")
+            }
+            className={`min-w-0 flex-1 hover:bg-transparent data-[active=true]:bg-transparent ${derived ? "" : "cursor-grab active:cursor-grabbing"} ${isDragged ? "opacity-50" : ""} ${highlight}`}
+            onClick={() => void navigate({ to: area, search: { select: entry.id } })}
+          >
+            <Icon aria-hidden="true" className="size-4 shrink-0" />
+            <span className="truncate">{entry.title}</span>
+            {/* The icon carries the type on screen; this carries it everywhere else, and it is why
+                a flow needs no suffix in its name to be told from a document. */}
+            <span className="sr-only">{i18n.t(`tree.kind.${entry.kind}`)}</span>
+          </SidebarMenuButton>
+          <AddMenu
+            label={i18n.t("tree.add", { title: entry.title })}
+            onSelect={(kind) => {
+              if (kind === "upload") startUpload(target);
+              else setCreating({ parentId: target, kind });
+            }}
+          />
+          {/* ⚠️ Dragging is a pointer gesture and nothing else: no keyboard, no screen reader, no
+              touch worth the name. A capability that exists only for a mouse is missing for
+              everyone else, so moving has a second, equal route — this menu's folder picker. #27
+              opened the menu with that one item; the rest of the row's actions moved in here from
+              the header, which is what #24 is. A row under a flow is what that flow calls, read out
+              of its graph rather than from `parent_id` (ADR-0004 §3): it has no place of its own to
+              be moved from, so it gets no move — and no menu, since renaming the shared flow from
+              under one of its callers would rename it for all of them without saying so. */}
+          {derived ? null : (
+            <ResourceMenu target={entry} variant="row" onMove={() => startMove(entry, null)} />
+          )}
+        </div>
+        {/* The same rows one indent deeper: one row component for every depth, so the plus on the
+            fourth level is the same plus as on the first. The list is named after the row it hangs
+            under — indentation says whose contents these are to anyone who can see it, and this is
+            the same sentence for anyone who cannot. */}
+        {isOpen ? (
+          <div className="ml-3.5 border-l border-sidebar-border pl-1.5">
+            {renderLevel(
+              level,
+              new Set([...ancestors, entry.id]),
+              i18n.t(isFolder ? "tree.contents" : "tree.calls", { title: entry.title }),
+            )}
+          </div>
+        ) : null}
+      </SidebarMenuItem>
+    );
+  }
+
+  const rootDrop = dropHandlers({ id: null, title: i18n.t("tree.move.root") }, new Set());
+
+  return (
+    <SidebarGroup className="min-h-0 flex-1 overflow-y-auto">
+      {/* The root has no row to drop on, so while something is being carried it gets one. It is the
+          only way back out of a folder, and it appears exactly when it can be used. */}
+      {rootDrop.verdict === undefined || dragged === null ? null : (
+        <button
+          type="button"
+          {...rootDrop.props}
+          onClick={() => startMove(dragged, { id: null, title: i18n.t("tree.move.root") })}
+          data-drop={rootDrop.verdict}
+          className={`mb-1 flex w-full items-center gap-1 rounded-md border border-dashed px-2 py-1.5 text-left text-sm outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring ${
+            rootDrop.verdict === "ok"
+              ? over === null
+                ? "bg-sidebar-accent ring-2 ring-sidebar-ring"
+                : "text-sidebar-foreground"
+              : "text-muted-foreground opacity-40"
+          }`}
+        >
+          <CornerLeftUp aria-hidden="true" className="size-4 shrink-0" />
+          {i18n.t("tree.move.dropRoot")}
+        </button>
+      )}
+      {/* The tree is the navigation and carries no heading of its own (ADR-0004); the list is
+          named for assistive technology instead. */}
+      {renderLevel({ id: null, type: "folder" }, new Set(), i18n.t("tree.label"))}
+      {create.isError || upload.isError ? (
+        <p role="alert" className="px-2 py-1.5 text-sm text-destructive">
+          {upload.isError ? i18n.t("tree.uploadFailed") : i18n.t("tree.createFailed")}
+        </p>
+      ) : null}
+      {/* Four refusals, four sentences — and by the time one is read the row is already back where
+          it started, because the rollback happens in `onError` rather than here. */}
+      {move.isError ? (
+        <p role="alert" className="px-2 py-1.5 text-sm text-destructive">
+          {i18n.t(moveErrorKey(move.error))}
+        </p>
+      ) : null}
+      {/* The root has no row of its own, so it gets one — otherwise a tree could only ever grow
+          inside the folders it already has, and the plus would stand loose under the list, attached
+          to nothing (#24). As a whole row it is also the one thing on screen when the tree is empty,
+          which is exactly when somebody needs to be told where to start. */}
+      {root?.isPending ? null : (
+        <div className="mt-1 flex items-center gap-0.5">
+          {/* The gutter the disclosure arrows occupy, so the plus lines up with the row icons
+              above it rather than half a step to their left. */}
+          <span aria-hidden="true" className="size-5 shrink-0" />
+          <AddMenu
+            label={i18n.t("tree.addRoot")}
+            variant="row"
+            onSelect={(kind) => {
+              if (kind === "upload") startUpload(null);
+              else setCreating({ parentId: null, kind });
+            }}
+          />
+        </div>
+      )}
+      <input
+        ref={uploadInput}
+        type="file"
+        className="sr-only"
+        aria-label={i18n.t("tree.upload")}
+        onChange={(event) => {
+          const file = event.target.files?.[0];
+          if (file) upload.mutate({ parentId: uploadTo, file });
+          event.currentTarget.value = "";
+        }}
+      />
+      {creating ? (
+        <Modal title={i18n.t(`tree.new.${creating.kind}`)} close={() => setCreating(null)}>
+          <CreateForm
+            kind={creating.kind}
+            pending={create.isPending}
+            submit={(title, columns) => create.mutate({ ...creating, title, columns })}
+          />
+        </Modal>
+      ) : null}
+      {moving ? (
+        <MoveDialog
+          entry={moving.entry}
+          initial={moving.initial}
+          close={() => setMoving(null)}
+          submit={(destination) => {
+            setMoving(null);
+            move.mutate({ entry: moving.entry, destination });
+          }}
+        />
+      ) : null}
+    </SidebarGroup>
+  );
+}
+
+// ⚠️ Hover alone would hide this from a keyboard and from touch entirely, which is the same as not
+// having it. It stays in the tab order, focus makes it visible, and below `md` it is always shown.
+//
+// `row` is the root's form: a full-width row that says what it does, because the root has no title
+// beside which a bare icon would mean anything.
+function AddMenu({
+  label,
+  variant = "icon",
+  onSelect,
+}: {
+  label: string;
+  variant?: "icon" | "row";
+  onSelect(kind: NewKind | "upload"): void;
+}) {
+  const { i18n } = useIntelRouterContext();
+  const items: Array<{ kind: NewKind | "upload"; labelKey: string; Icon: typeof Plus }> = [
+    { kind: "folder", labelKey: "tree.new.folder", Icon: Folder },
+    { kind: "document", labelKey: "tree.new.document", Icon: FileText },
+    { kind: "table", labelKey: "tree.new.table", Icon: Table },
+    { kind: "upload", labelKey: "tree.new.upload", Icon: Upload },
+    { kind: "flow", labelKey: "tree.new.flow", Icon: Workflow },
+  ];
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        {...(variant === "row" ? {} : { "aria-label": label })}
+        className={
+          variant === "row"
+            ? "flex min-w-0 flex-1 items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm text-sidebar-foreground/70 outline-none transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 focus-visible:ring-sidebar-ring data-[state=open]:bg-sidebar-accent"
+            : "shrink-0 rounded-md p-1 text-sidebar-foreground outline-none transition-opacity hover:bg-sidebar-accent-foreground/10 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-sidebar-ring data-[state=open]:opacity-100 group-focus-within/row:opacity-100 group-hover/row:opacity-100 md:opacity-0"
+        }
+      >
+        <Plus aria-hidden="true" className="size-4 shrink-0" />
+        {variant === "row" ? <span className="truncate">{label}</span> : null}
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="w-44">
+        {items.map((item) => (
+          <DropdownMenuItem key={item.kind} onSelect={() => onSelect(item.kind)}>
+            <item.Icon aria-hidden="true" />
+            {i18n.t(item.labelKey)}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+// The column names of a new table, as one line. A comma-separated list is what a CSV header is,
+// so the field looks like the thing it produces rather than like a form that hides it.
+function columnsOf(value: string): string[] {
+  return value
+    .split(",")
+    .map((column) => column.trim())
+    .filter(Boolean);
+}
+
+function CreateForm({
+  kind,
+  pending,
+  submit,
+}: {
+  kind: NewKind;
+  pending: boolean;
+  submit(title: string, columns: string[]): void;
+}) {
+  const { i18n } = useIntelRouterContext();
+  const [title, setTitle] = useState("");
+  const [columns, setColumns] = useState("");
+  const parsedColumns = columnsOf(columns);
+  const incomplete = title.trim().length === 0 || (kind === "table" && parsedColumns.length === 0);
+  return (
+    <form
+      className="space-y-4"
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (!pending && !incomplete) submit(title.trim(), parsedColumns);
+      }}
+    >
+      <label className="block text-sm font-medium">
+        {i18n.t("common.title")}
+        <input
+          required
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+          className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        />
+      </label>
+      {kind === "table" ? (
+        <label className="block text-sm font-medium">
+          {i18n.t("tree.table.columns")}
+          <input
+            required
+            value={columns}
+            onChange={(event) => setColumns(event.target.value)}
+            aria-describedby="create-table-columns-hint"
+            className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          />
+          <span
+            id="create-table-columns-hint"
+            className="mt-1 block text-xs font-normal text-muted-foreground"
+          >
+            {i18n.t("tree.table.columnsHint")}
+          </span>
+        </label>
+      ) : null}
+      <button
+        type="submit"
+        disabled={pending || incomplete}
+        className="w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+      >
+        {pending ? i18n.t("common.saving") : i18n.t("common.create")}
+      </button>
+    </form>
+  );
+}