@cosmicdrift/kumiko-bundled-features 0.91.0 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -90,11 +90,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.91.0",
-    "@cosmicdrift/kumiko-framework": "0.91.0",
-    "@cosmicdrift/kumiko-headless": "0.91.0",
-    "@cosmicdrift/kumiko-renderer": "0.91.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.91.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.92.0",
+    "@cosmicdrift/kumiko-framework": "0.92.0",
+    "@cosmicdrift/kumiko-headless": "0.92.0",
+    "@cosmicdrift/kumiko-renderer": "0.92.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.92.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/folders/web/__tests__/folder-manager.test.tsx

@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { FoldersHandlers, FoldersQueries } from "../../constants";
+import { type FolderFiling, FolderManager } from "../folder-manager";
+import { defaultTranslations } from "../i18n";
+
+type FolderRow = { id: string; name: string; parentId: string | null; version: number };
+
+let folderRows: readonly FolderRow[] = [];
+
+beforeEach(() => {
+  folderRows = [];
+  dispatchSpy.mockClear();
+});
+
+const dispatchSpy = mock(async () => ({ isSuccess: true, data: undefined }));
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === FoldersQueries.folderList ? { rows: folderRows } : { rows: [] },
+  loading: false,
+  error: null,
+  refetch: mock(async () => {}),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useDispatcher: mock(() => ({ write: dispatchSpy, query: mock(), batch: mock() })),
+  useQuery: useQuerySpy,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+const filingWith = (onReassigned: () => void): FolderFiling => ({
+  entityType: "credit",
+  leavesByFolder: new Map([["f1", [{ id: "c-1", label: "Credit 1" }]]]),
+  unfiled: [{ id: "c-2", label: "Credit 2" }],
+  unfiledLabel: "Unfiled",
+  onReassigned,
+});
+
+const dropLeaf = (targetTestId: string, entityId: string): void => {
+  fireEvent.drop(screen.getByTestId(targetTestId), {
+    dataTransfer: { getData: () => entityId },
+  });
+};
+
+describe("FolderManager filing mode", () => {
+  test("renders filed leaves under their folder and the unfiled bucket", () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    render(
+      <Wrapper>
+        <FolderManager filing={filingWith(() => {})} />
+      </Wrapper>,
+    );
+    expect(screen.getByTestId("folder-leaf-c-1")).toBeTruthy();
+    expect(screen.getByTestId("folder-node-unfiled")).toBeTruthy();
+    expect(screen.getByTestId("folder-leaf-c-2")).toBeTruthy();
+  });
+
+  test("dropping a leaf on another folder dispatches set-folder + refetches the host", async () => {
+    folderRows = [
+      { id: "f1", name: "A", parentId: null, version: 1 },
+      { id: "f2", name: "B", parentId: null, version: 1 },
+    ];
+    const onReassigned = mock(() => {});
+    render(
+      <Wrapper>
+        <FolderManager filing={filingWith(onReassigned)} />
+      </Wrapper>,
+    );
+    dropLeaf("folder-node-f2", "c-1");
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.setFolder, {
+        folderId: "f2",
+        entityType: "credit",
+        entityId: "c-1",
+      }),
+    );
+    await waitFor(() => expect(onReassigned).toHaveBeenCalled());
+  });
+
+  test("dropping a leaf on the unfiled bucket dispatches clear-folder", async () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    render(
+      <Wrapper>
+        <FolderManager filing={filingWith(() => {})} />
+      </Wrapper>,
+    );
+    dropLeaf("folder-node-unfiled", "c-1");
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.clearFolder, {
+        entityType: "credit",
+        entityId: "c-1",
+      }),
+    );
+  });
+
+  test("dropping a leaf on the folder it already lives in is a no-op (no write)", async () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    render(
+      <Wrapper>
+        <FolderManager filing={filingWith(() => {})} />
+      </Wrapper>,
+    );
+    dropLeaf("folder-node-f1", "c-1");
+    // give any (erroneous) async write a tick to land
+    await new Promise((r) => setTimeout(r, 0));
+    expect(dispatchSpy).not.toHaveBeenCalled();
+  });
+
+  test("without filing the manager renders no leaves or bucket (backward compatible)", () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    render(
+      <Wrapper>
+        <FolderManager />
+      </Wrapper>,
+    );
+    expect(screen.getByTestId("folder-node-f1")).toBeTruthy();
+    expect(screen.queryByTestId("folder-node-unfiled")).toBeNull();
+    expect(screen.queryByTestId("folder-leaf-c-1")).toBeNull();
+  });
+
+  test("delete is confirm-gated; confirming dispatches delete-folder", async () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    render(
+      <Wrapper>
+        <FolderManager />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByTestId("folder-delete-f1"));
+    expect(dispatchSpy).not.toHaveBeenCalled(); // no write before confirm
+    fireEvent.click(await screen.findByTestId("folder-manager-delete-dialog-confirm"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.deleteFolder, { id: "f1" }),
+    );
+  });
+
+  test("the in-tree new-folder row opens a draft; submitting (Enter) creates a root folder", async () => {
+    folderRows = [];
+    render(
+      <Wrapper>
+        <FolderManager />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByTestId("folder-manager-new-root"));
+    fireEvent.change(document.getElementById("folder-manager-draft") as HTMLInputElement, {
+      target: { value: "Inbox" },
+    });
+    fireEvent.submit(screen.getByTestId("folder-manager-draft"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.createFolder, { name: "Inbox" }),
+    );
+  });
+});

package/src/folders/web/folder-manager.tsx

@@ -5,21 +5,27 @@
 // rolled-up Restschuld/Rate) next to each node — the manager knows nothing about
 // what's filed in a folder, only the folder tree itself.
 //
+// Optional `filing` mode: when a host hands in its entities (grouped by folder +
+// an unfiled bucket) the manager interleaves them as draggable leaf rows and
+// becomes a full filing tree — drag a leaf onto a folder to file it (set-folder),
+// onto the unfiled bucket to unfile it (clear-folder). The host owns the entity
+// data + stats; the manager owns the folder writes AND the reassignment writes,
+// then refetches its own catalog and calls the host's onReassigned to refresh the
+// host's assignment-derived data. ponytail: native HTML5 DnD, desktop-only;
+// pointer-based (dnd-kit) only if touch filing is ever needed — keyboard filing
+// stays available via <FolderSection>.
+//
 // Finder/Explorer-style: the tree is flattened to its visible rows in DFS order
 // and rendered as full-width rows with (a) alternating zebra striping, (b) one
 // vertical guide line per ancestor depth, and (c) a disclosure chevron + folder
-// icon. Icons are lucide-react (the same set the nav's NAV_ICONS uses), so they
-// match the rest of the app. Actions are compact always-visible icon buttons (NOT
-// hover-only — static screenshots can't hover). Flattening (vs nested divs) is
-// what lets the zebra + guide lines run edge-to-edge and stay aligned regardless
-// of depth.
+// icon. The chevron+name toggle a node; expansion state persists in localStorage
+// so a reload doesn't re-expand everything. Create/rename happen inline (Enter
+// saves); delete asks for confirmation; root folders are added via the in-tree
+// "+ new folder" row (no floating toolbar button). Icons are lucide-react.
 //
 // NOTE on Tailwind: a host's Tailwind v4 build must `@source`-scan this package's
 // src (node_modules is ignored by default) or these classes never compile. money-
 // horse already does; that scan is a real shipping requirement for any host.
-//
-// Folder writes are immediate; the manager owns its catalog query and refetches
-// after each action.
 
 import {
   useDispatcher,
@@ -27,21 +33,51 @@ import {
   useQuery,
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
-import {
-  ChevronDown,
-  ChevronRight,
-  Folder,
-  type LucideIcon,
-  Pencil,
-  Plus,
-  Trash2,
-} from "lucide-react";
-import { type ReactNode, useState } from "react";
+import { ChevronRight, File, Folder, type LucideIcon, Pencil, Plus, Trash2 } from "lucide-react";
+import { type DragEvent, type ReactNode, useEffect, useState } from "react";
 import { FoldersHandlers, FoldersQueries } from "../constants";
 import { buildFolderTree, type FolderNode, type FolderRow } from "./tree";
 
 type FolderListResponse = { readonly rows: readonly FolderRow[] };
 
+// One filed entity, rendered as a draggable leaf under its folder. The host maps
+// its rows into these (label + an optional trailing slot for a KPI/amount).
+export type FolderLeaf = {
+  readonly id: string;
+  readonly label: string;
+  readonly trailing?: ReactNode;
+  readonly onOpen?: () => void;
+};
+
+// Opt-in filing binding. Host computes the grouping (it already holds the
+// assignments for its stats); the manager renders + drives the set/clear-folder
+// writes and tells the host to refetch via onReassigned.
+export type FolderFiling = {
+  readonly entityType: string;
+  readonly leavesByFolder: ReadonlyMap<string, readonly FolderLeaf[]>;
+  readonly unfiled: readonly FolderLeaf[];
+  readonly unfiledLabel: string;
+  readonly unfiledMeta?: ReactNode;
+  readonly leafIcon?: LucideIcon;
+  readonly onReassigned: () => Promise<void> | void;
+};
+
+const UNFILED = "__unfiled__";
+const DRAG_MIME = "text/plain";
+// ponytail: one global key — folder expansion is low-stakes UI state shared
+// across every folder tree in the app; a per-host key only if trees ever diverge.
+const COLLAPSED_KEY = "kumiko:folders:collapsed";
+
+const loadCollapsed = (): ReadonlySet<string> => {
+  if (typeof window === "undefined") return new Set();
+  try {
+    const raw = window.localStorage.getItem(COLLAPSED_KEY);
+    return new Set(raw ? (JSON.parse(raw) as string[]) : []);
+  } catch {
+    return new Set();
+  }
+};
+
 type Pending =
   | { readonly mode: "create"; readonly parentId: string | null }
   | { readonly mode: "rename"; readonly id: string; readonly version: number }
@@ -49,20 +85,35 @@ type Pending =
 
 export function FolderManager({
   renderMeta,
+  filing,
 }: {
   // Optional per-folder slot (right side of each row). The host owns the data;
   // the manager just gives it a place to render.
   readonly renderMeta?: (folder: FolderRow) => ReactNode;
+  // Optional filing mode: interleave the host's draggable entities + DnD.
+  readonly filing?: FolderFiling;
 }): ReactNode {
-  const { Banner, Button, Input, Text } = usePrimitives();
+  const { Banner, Button, Dialog, Input, Text } = usePrimitives();
   const t = useTranslation();
   const dispatcher = useDispatcher();
   const catalog = useQuery<FolderListResponse>(FoldersQueries.folderList, {});
   const [pending, setPending] = useState<Pending>(null);
   const [draftName, setDraftName] = useState("");
-  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set());
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(loadCollapsed);
   const [busy, setBusy] = useState(false);
   const [errorKey, setErrorKey] = useState<string | null>(null);
+  const [dragOverKey, setDragOverKey] = useState<string | null>(null);
+  const [pendingDelete, setPendingDelete] = useState<FolderNode | null>(null);
+
+  // Persist expand/collapse so a reload (F5) doesn't re-expand everything.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    try {
+      window.localStorage.setItem(COLLAPSED_KEY, JSON.stringify([...collapsed]));
+    } catch {
+      // storage unavailable (private mode / quota) — expansion just won't persist
+    }
+  }, [collapsed]);
 
   if (catalog.loading && catalog.data === null) {
     return (
@@ -82,6 +133,14 @@ export function FolderManager({
   const rows = catalog.data?.rows ?? [];
   const tree = buildFolderTree(rows);
 
+  // entityId → current folder (null = unfiled) for the drop no-op guard.
+  const currentFolderByEntity = new Map<string, string | null>();
+  if (filing !== undefined) {
+    for (const [folderId, leaves] of filing.leavesByFolder)
+      for (const leaf of leaves) currentFolderByEntity.set(leaf.id, folderId);
+    for (const leaf of filing.unfiled) currentFolderByEntity.set(leaf.id, null);
+  }
+
   const toggleCollapse = (id: string): void =>
     setCollapsed((prev) => {
       const next = new Set(prev);
@@ -144,16 +203,68 @@ export function FolderManager({
     );
   };
 
-  const deleteFolder = (node: FolderNode): void => {
+  // Delete goes through a confirm dialog — a folder can hold filed entries that
+  // fall back to "unfiled" when it's gone. Child folders still block outright.
+  const requestDelete = (node: FolderNode): void => {
     if (node.children.length > 0) {
       setErrorKey("folders.manager.deleteBlocked");
       return;
     }
-    void apply(() => writeOk(FoldersHandlers.deleteFolder, { id: node.id }));
+    setErrorKey(null);
+    setPendingDelete(node);
+  };
+
+  const confirmDelete = async (): Promise<void> => {
+    const node = pendingDelete;
+    setPendingDelete(null);
+    if (node === null) return;
+    await apply(() => writeOk(FoldersHandlers.deleteFolder, { id: node.id }));
+  };
+
+  // Drop a leaf into a folder (set-folder) or the unfiled bucket (clear-folder).
+  // No-op if it already lives there (both handlers are idempotent, but a re-set
+  // would burn a redundant event).
+  const reassign = async (entityId: string, folderId: string | null): Promise<void> => {
+    if (filing === undefined) return;
+    if ((currentFolderByEntity.get(entityId) ?? null) === folderId) return;
+    setErrorKey(null);
+    const ok =
+      folderId === null
+        ? await writeOk(FoldersHandlers.clearFolder, { entityType: filing.entityType, entityId })
+        : await writeOk(FoldersHandlers.setFolder, {
+            folderId,
+            entityType: filing.entityType,
+            entityId,
+          });
+    if (ok) {
+      await catalog.refetch();
+      await filing.onReassigned();
+    }
   };
 
-  // One vertical guide line per ancestor depth, centered in a chevron-width column;
-  // self-stretch makes consecutive rows' lines join into continuous rails.
+  // Drop-target handlers, attached only in filing mode (so plain folder
+  // management keeps non-interactive rows).
+  const dropProps = (key: string, folderId: string | null) =>
+    filing === undefined
+      ? {}
+      : {
+          onDragOver: (e: DragEvent<HTMLDivElement>) => {
+            e.preventDefault();
+            e.dataTransfer.dropEffect = "move";
+            setDragOverKey(key);
+          },
+          onDragLeave: () => setDragOverKey((cur) => (cur === key ? null : cur)),
+          onDrop: (e: DragEvent<HTMLDivElement>) => {
+            e.preventDefault();
+            setDragOverKey(null);
+            const id = e.dataTransfer.getData(DRAG_MIME);
+            if (id !== "") void reassign(id, folderId);
+          },
+        };
+
+  // One vertical guide line per ancestor depth, centered in a chevron-width
+  // column; self-stretch fills the padding-free min-h-9 row edge-to-edge, so
+  // consecutive rows' lines join into continuous, gapless rails.
   const rails = (depth: number): ReactNode =>
     Array.from({ length: depth }, (_, i) => (
       // biome-ignore lint/suspicious/noArrayIndexKey: positional rail, no identity
@@ -162,10 +273,10 @@ export function FolderManager({
       </span>
     ));
 
-  const rowClass = (stripe: boolean): string =>
-    `flex items-center gap-1.5 px-2 py-1.5 transition-colors hover:bg-muted/60 ${
+  const rowClass = (stripe: boolean, dropActive: boolean): string =>
+    `flex min-h-9 items-center gap-1.5 px-2 transition-colors hover:bg-muted/60 ${
       stripe ? "bg-muted/40" : ""
-    }`;
+    } ${dropActive ? "ring-1 ring-inset ring-primary/40" : ""}`;
 
   const actionButton = (
     label: string,
@@ -182,7 +293,7 @@ export function FolderManager({
       aria-label={label}
       title={label}
       data-testid={testId}
-      className={`rounded p-1 text-muted-foreground transition-colors hover:bg-background disabled:opacity-40 ${
+      className={`cursor-pointer rounded p-1 text-muted-foreground transition-colors hover:bg-background disabled:opacity-40 ${
         danger ? "hover:text-destructive" : "hover:text-foreground"
       }`}
     >
@@ -190,8 +301,52 @@ export function FolderManager({
     </button>
   );
 
+  // Chevron + folder icon + name = one click target that toggles (cursor-pointer).
+  // A non-expandable folder renders the same layout without the toggle affordance.
+  const toggleArea = (
+    id: string,
+    label: string,
+    expanded: boolean,
+    expandable: boolean,
+  ): ReactNode =>
+    expandable ? (
+      // kumiko-lint-ignore primitives-discipline: dense Finder-row toggle (chevron + name); the Button primitive would break the single-row layout
+      <button
+        type="button"
+        aria-expanded={expanded}
+        onClick={() => toggleCollapse(id)}
+        data-testid={`folder-toggle-${id}`}
+        className="flex min-w-0 flex-1 cursor-pointer items-center gap-1.5 text-left"
+      >
+        <ChevronRight
+          size={16}
+          aria-hidden="true"
+          className={`shrink-0 text-muted-foreground transition-transform ${
+            expanded ? "rotate-90" : ""
+          }`}
+        />
+        <Folder size={16} aria-hidden="true" className="shrink-0 text-muted-foreground" />
+        <span className="flex-1 truncate font-medium">{label}</span>
+      </button>
+    ) : (
+      <div className="flex min-w-0 flex-1 items-center gap-1.5">
+        <span className="w-4 shrink-0" />
+        <Folder size={16} aria-hidden="true" className="shrink-0 text-muted-foreground" />
+        <span className="flex-1 truncate font-medium">{label}</span>
+      </div>
+    );
+
   const draftRow = (depth: number, key: string, stripe: boolean): ReactNode => (
-    <div key={key} className={rowClass(stripe)} data-testid="folder-manager-draft">
+    // kumiko-lint-ignore primitives-discipline: native form only to capture Enter-to-submit on the inline draft field
+    <form
+      key={key}
+      className={rowClass(stripe, false)}
+      data-testid="folder-manager-draft"
+      onSubmit={(e) => {
+        e.preventDefault();
+        saveDraft();
+      }}
+    >
       {rails(depth)}
       <Folder size={16} aria-hidden="true" className="shrink-0 text-muted-foreground/50" />
       <div className="flex-1">
@@ -215,35 +370,47 @@ export function FolderManager({
       <Button variant="secondary" disabled={busy} onClick={() => setPending(null)}>
         {t("folders.manager.cancel")}
       </Button>
-    </div>
+    </form>
   );
 
+  const leafRow = (leaf: FolderLeaf, depth: number, stripe: boolean): ReactNode => {
+    const LeafIcon = filing?.leafIcon ?? File;
+    return (
+      // kumiko-lint-ignore primitives-discipline: draggable Finder-style leaf row; the Button primitive can't be a dense, full-row drag source
+      <button
+        key={`leaf-${leaf.id}`}
+        type="button"
+        draggable
+        onDragStart={(e) => {
+          e.dataTransfer.setData(DRAG_MIME, leaf.id);
+          e.dataTransfer.effectAllowed = "move";
+        }}
+        onClick={leaf.onOpen}
+        className={`${rowClass(stripe, false)} w-full cursor-pointer text-left`}
+        data-testid={`folder-leaf-${leaf.id}`}
+      >
+        {rails(depth)}
+        <span className="w-5 shrink-0" />
+        <LeafIcon size={16} aria-hidden="true" className="shrink-0 text-muted-foreground/70" />
+        <span className="flex-1 truncate">{leaf.label}</span>
+        {leaf.trailing}
+      </button>
+    );
+  };
+
   const folderRow = (node: FolderNode, depth: number, stripe: boolean): ReactNode => {
-    const hasChildren = node.children.length > 0;
-    const expanded = hasChildren && !collapsed.has(node.id);
+    const leaves = filing?.leavesByFolder.get(node.id) ?? [];
+    const expandable = node.children.length > 0 || leaves.length > 0;
+    const expanded = expandable && !collapsed.has(node.id);
     return (
-      <div key={node.id} data-testid={`folder-node-${node.id}`} className={rowClass(stripe)}>
+      <div
+        key={node.id}
+        data-testid={`folder-node-${node.id}`}
+        className={rowClass(stripe, dragOverKey === node.id)}
+        {...dropProps(node.id, node.id)}
+      >
         {rails(depth)}
-        {hasChildren ? (
-          // kumiko-lint-ignore primitives-discipline: compact disclosure chevron, not a form button
-          <button
-            type="button"
-            className="flex h-5 w-5 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-background hover:text-foreground"
-            aria-expanded={expanded}
-            onClick={() => toggleCollapse(node.id)}
-            data-testid={`folder-toggle-${node.id}`}
-          >
-            {expanded ? (
-              <ChevronDown size={16} aria-hidden="true" />
-            ) : (
-              <ChevronRight size={16} aria-hidden="true" />
-            )}
-          </button>
-        ) : (
-          <span className="w-5 shrink-0" />
-        )}
-        <Folder size={16} aria-hidden="true" className="shrink-0 text-muted-foreground" />
-        <span className="flex-1 truncate font-medium">{node.name}</span>
+        {toggleArea(node.id, node.name, expanded, expandable)}
         {renderMeta?.(node)}
         <div className="flex items-center gap-0.5">
           {actionButton(t("folders.manager.addChild"), `folder-add-child-${node.id}`, Plus, () =>
@@ -256,7 +423,7 @@ export function FolderManager({
             t("folders.manager.delete"),
             `folder-delete-${node.id}`,
             Trash2,
-            () => deleteFolder(node),
+            () => requestDelete(node),
             true,
           )}
         </div>
@@ -264,9 +431,43 @@ export function FolderManager({
     );
   };
 
+  const bucketRow = (stripe: boolean): ReactNode => {
+    if (filing === undefined) return null;
+    const expanded = !collapsed.has(UNFILED);
+    return (
+      <div
+        key={UNFILED}
+        data-testid="folder-node-unfiled"
+        className={rowClass(stripe, dragOverKey === UNFILED)}
+        {...dropProps(UNFILED, null)}
+      >
+        {toggleArea(UNFILED, filing.unfiledLabel, expanded, true)}
+        {filing.unfiledMeta}
+      </div>
+    );
+  };
+
+  // Subtle in-tree row to add a root folder (replaces the old floating toolbar
+  // button, which caused an ugly header jump in hosts with their own actions).
+  const newRootRow = (): ReactNode => (
+    // kumiko-lint-ignore primitives-discipline: dense Finder-row action (add root folder); the Button primitive would break the row layout
+    <button
+      type="button"
+      disabled={busy}
+      onClick={() => openCreate(null)}
+      data-testid="folder-manager-new-root"
+      className="flex min-h-9 w-full cursor-pointer items-center gap-1.5 px-2 text-left text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground disabled:opacity-40"
+    >
+      <span className="w-5 shrink-0" />
+      <Plus size={16} aria-hidden="true" className="shrink-0" />
+      <span className="font-medium">{t("folders.manager.newRoot")}</span>
+    </button>
+  );
+
   // Flatten the visible tree (DFS) into ordered rows so the zebra index + guide
   // rails stay correct across depth. A pending rename swaps a node's row in place;
-  // a pending create appends a draft row at the end of its parent's children.
+  // a pending create appends a draft row at the end of its parent's children. In
+  // filing mode a folder's leaf rows render before its subfolders.
   const out: ReactNode[] = [];
   let idx = 0;
   const stripeNext = (): boolean => {
@@ -282,42 +483,54 @@ export function FolderManager({
           ? draftRow(depth, `rename-${node.id}`, stripeNext())
           : folderRow(node, depth, stripeNext()),
       );
-      if (node.children.length > 0 && !collapsed.has(node.id)) walk(node.children, depth + 1);
+      const leaves = filing?.leavesByFolder.get(node.id) ?? [];
+      const expandable = node.children.length > 0 || leaves.length > 0;
+      if (expandable && !collapsed.has(node.id)) {
+        for (const leaf of leaves) out.push(leafRow(leaf, depth + 1, stripeNext()));
+        if (node.children.length > 0) walk(node.children, depth + 1);
+      }
       if (pending?.mode === "create" && pending.parentId === node.id)
         out.push(draftRow(depth + 1, `create-under-${node.id}`, stripeNext()));
     }
   };
   walk(tree, 0);
 
+  const hasUnfiled = filing !== undefined && filing.unfiled.length > 0;
+  if (hasUnfiled) {
+    out.push(bucketRow(stripeNext()));
+    if (!collapsed.has(UNFILED))
+      for (const leaf of filing.unfiled) out.push(leafRow(leaf, 1, stripeNext()));
+  }
+
   const creatingRoot = pending?.mode === "create" && pending.parentId === null;
   if (creatingRoot) out.unshift(draftRow(0, "create-root", false));
 
   return (
     <div data-testid="folder-manager" className="flex flex-col gap-2">
-      <div className="flex justify-end">
-        <Button
-          variant="primary"
-          disabled={busy || creatingRoot}
-          onClick={() => openCreate(null)}
-          testId="folder-manager-new-root"
-        >
-          {t("folders.manager.newRoot")}
-        </Button>
+      <div className="overflow-hidden rounded-md border">
+        {out}
+        {!creatingRoot && newRootRow()}
       </div>
 
-      {tree.length === 0 && !creatingRoot ? (
-        <Banner variant="info" testId="folder-manager-empty">
-          <Text>{t("folders.manager.empty")}</Text>
-        </Banner>
-      ) : (
-        <div className="overflow-hidden rounded-md border">{out}</div>
-      )}
-
       {errorKey !== null && (
         <Banner variant="error" testId="folder-manager-action-error">
           <Text>{t(errorKey)}</Text>
         </Banner>
       )}
+
+      <Dialog
+        open={pendingDelete !== null}
+        onOpenChange={(o) => {
+          if (!o) setPendingDelete(null);
+        }}
+        title={t("folders.manager.deleteConfirmTitle")}
+        description={t("folders.manager.deleteConfirmBody")}
+        confirmLabel={t("folders.manager.delete")}
+        cancelLabel={t("folders.manager.cancel")}
+        variant="danger"
+        onConfirm={confirmDelete}
+        testId="folder-manager-delete-dialog"
+      />
     </div>
   );
 }

package/src/folders/web/i18n.ts

@@ -28,6 +28,9 @@ export const defaultTranslations: TranslationsByLocale = {
     "folders.manager.cancel": "Abbrechen",
     "folders.manager.working": "Speichert…",
     "folders.manager.deleteBlocked": "Erst Unterordner entfernen.",
+    "folders.manager.deleteConfirmTitle": "Ordner löschen?",
+    "folders.manager.deleteConfirmBody":
+      "Der Ordner wird entfernt. Abgelegte Einträge wandern zurück zu „Ohne Ordner“.",
   },
   en: {
     "folders.section.createMode": "Save the entity first to pick a folder.",
@@ -51,5 +54,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "folders.manager.cancel": "Cancel",
     "folders.manager.working": "Saving…",
     "folders.manager.deleteBlocked": "Remove subfolders first.",
+    "folders.manager.deleteConfirmTitle": "Delete folder?",
+    "folders.manager.deleteConfirmBody":
+      "The folder will be removed. Filed entries move back to Unfiled.",
   },
 };

package/src/folders/web/index.ts

@@ -1,6 +1,6 @@
 // @runtime client
 export { FOLDER_SECTION_EXTENSION_NAME, FoldersHandlers, FoldersQueries } from "../constants";
 export { foldersClient } from "./client-plugin";
-export { FolderManager } from "./folder-manager";
+export { type FolderFiling, type FolderLeaf, FolderManager } from "./folder-manager";
 export { FolderSection } from "./folder-section";
 export { buildFolderTree, type FolderNode, type FolderRow, folderPath } from "./tree";