@cosmicdrift/kumiko-bundled-features 0.89.0 → 0.90.2

package/src/folders/feature.ts

@@ -0,0 +1,106 @@
+// folders — generic, host-agnostic hierarchical folders for ANY entity.
+//
+// **Event-sourced, not relational.** No pivot table with foreign keys and JOINs.
+// The feature owns two event-sourced entities:
+//   1. `folder` (read_folders)                   — per-tenant folder tree (parentId).
+//   2. `folder-assignment` (read_folder_assignments) — single-membership rows keyed
+//      by (entityType, entityId) with a deterministic aggregate-id, so an entity
+//      belongs to at most one folder and re-setting moves it.
+//
+// Cross-entity views compose in the read-layer (no JOIN): list folder-assignments
+// filtered on entityId (the folder of an entity) or folderId (entities in a folder).
+//
+// Scope: folder catalog CRUD (create/update[=rename]/delete/list/detail via the
+// generic entity handlers), set-folder (put/move), clear-folder (unfile).
+// Deferred: reparenting with cycle-check (folder:update CAN change parentId, but
+// no UI exposes it in v1 — folders-view guards cycles defensively).
+
+import {
+  type AccessRule,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_FOLDER_ACCESS, FOLDERS_FEATURE_NAME } from "./constants";
+import { folderAssignmentEntity, folderEntity } from "./entity";
+import { createClearFolderHandler } from "./handlers/clear-folder.write";
+import { createSetFolderHandler } from "./handlers/set-folder.write";
+
+// Opt-in tier-gating: when set, the feature declares itself r.toggleable so the
+// dispatcher gate + feature-toggles + tier-engine can switch the WHOLE feature
+// on/off per tenant — no host-side hook. For a tier-gated feature use
+// { default: false } (fail-closed) and list the feature name in the entitling
+// tiers' TierMap; tenants below it get every folder path disabled.
+type FoldersToggleable = { readonly default: boolean };
+
+function registerFolders(
+  r: FeatureRegistrar<typeof FOLDERS_FEATURE_NAME>,
+  access: AccessRule,
+  toggleable: FoldersToggleable | undefined,
+): void {
+  r.describe(
+    "Generic, host-agnostic hierarchical folders for any entity. Owns two event-sourced entities — the per-tenant `folder` tree (`read_folders`, self-referential via parentId) and SINGLE-membership `folder-assignment` rows keyed by (entityType, entityId) (`read_folder_assignments`) — so filing an entity adds NO column to the host and needs no relational pivot or JOIN. The folder catalog uses the generic entity handlers (create, update [= rename, optimistic-locked], delete, list, detail); set-folder puts/moves an entity into a folder (one folder per entity) and clear-folder unfiles it (both idempotent). Read which folder an entity is in, or which entities a folder holds, by listing `folder-assignment` filtered on `entityId` or `folderId`. Every path uses one access rule — adopt the host's model with createFoldersFeature({ access: { openToAll: true } }) or pin roles. Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
+  );
+  r.uiHints({
+    displayLabel: "Folders",
+    category: "data",
+    recommended: false,
+  });
+
+  if (toggleable !== undefined) r.toggleable(toggleable);
+
+  r.entity("folder", folderEntity);
+  r.entity("folder-assignment", folderAssignmentEntity);
+
+  // Folder catalog — plain CRUD, no custom logic. update is rename (and, in a
+  // later stage, reparent: it accepts changes.parentId, optimistic-locked).
+  r.writeHandler(defineEntityCreateHandler("folder", folderEntity, { access }));
+  r.writeHandler(defineEntityUpdateHandler("folder", folderEntity, { access }));
+  r.writeHandler(defineEntityDeleteHandler("folder", folderEntity, { access }));
+  r.queryHandler(defineEntityListHandler("folder", folderEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("folder", folderEntity, { access }));
+
+  // Single-membership assignment — hand-written (deterministic id + move/restore).
+  r.writeHandler(createSetFolderHandler(access));
+  r.writeHandler(createClearFolderHandler(access));
+  r.queryHandler(defineEntityListHandler("folder-assignment", folderAssignmentEntity, { access }));
+}
+
+export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
+  registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined),
+);
+
+export type FoldersFeatureOptions = {
+  /** Access rule for all folder write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: true } when any authenticated
+   *  tenant user may file entities, or { roles: ["Admin"] } for a custom role
+   *  vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+  /** Make the whole feature tier-gatable: declares r.toggleable so the
+   *  tier-engine/feature-toggles can enable/disable every folder path per tenant.
+   *  `default` applies when no toggle/tier override exists — use { default: false }
+   *  for fail-closed tier-gating. Omit to keep folders always-on (default). */
+  readonly toggleable?: FoldersToggleable;
+};
+
+function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_FOLDER_ACCESS;
+}
+
+// Options wrapper. Without options returns the module-level singleton (no
+// rebuild). access/roles/toggleable build a fresh feature-definition.
+export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof foldersFeature {
+  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
+    return foldersFeature;
+  }
+  const access = resolveAccess(opts);
+  return defineFeature(FOLDERS_FEATURE_NAME, (r) => registerFolders(r, access, opts.toggleable));
+}

package/src/folders/handlers/clear-folder.write.ts

@@ -0,0 +1,35 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { folderAssignmentAggregateId } from "../aggregate-id";
+import { DEFAULT_FOLDER_ACCESS } from "../constants";
+import { folderAssignmentExecutor } from "../executor";
+import { type ClearFolderPayload, clearFolderPayloadSchema } from "../schemas";
+
+// clear-folder — removes a host entity from its folder (back to "unfiled").
+// Idempotent: clearing an entity that isn't in any folder is already the
+// requested end state, so we pre-check and return success without a delete.
+export function createClearFolderHandler(
+  access: AccessRule = DEFAULT_FOLDER_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "clear-folder",
+    schema: clearFolderPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as ClearFolderPayload; // @cast-boundary engine-payload
+      const id = folderAssignmentAggregateId(
+        event.user.tenantId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const existing = await folderAssignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (!existing) {
+        return { isSuccess: true as const, data: { id } };
+      }
+
+      return folderAssignmentExecutor.delete({ id }, event.user, ctx.db);
+    },
+  };
+}
+
+export const clearFolderHandler: WriteHandlerDef = createClearFolderHandler();

package/src/folders/handlers/set-folder.write.ts

@@ -0,0 +1,82 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { folderAssignmentAggregateId } from "../aggregate-id";
+import { DEFAULT_FOLDER_ACCESS } from "../constants";
+import { folderAssignmentExecutor, folderExecutor } from "../executor";
+import { type SetFolderPayload, setFolderPayloadSchema } from "../schemas";
+
+// set-folder — puts a host entity into a folder. Single-membership: the
+// assignment id is deterministic over (tenant, entity) WITHOUT folderId, so an
+// entity has exactly one assignment and setting a different folder MOVES it.
+//
+// Lifecycle (set → clear → set):
+//   - already in the requested folder → success (requested end state).
+//   - in a different folder           → update folderId (move).
+//   - cleared (soft-deleted)          → restore() then update folderId to the
+//     requested one. create() would append at version 0 onto the
+//     created+deleted stream and version_conflict.
+//   - never assigned                  → create().
+// The internal move/restore-update uses skipOptimisticLock: this handler is the
+// authority for the assignment's folderId, there is no client read-modify-write
+// race to guard, and clients never send a version for set-folder.
+//
+// Referential integrity: there is no FK (event-sourced, no JOIN), so we verify
+// the target folder exists before writing — a malformed call with an unknown
+// folderId would otherwise point an entity at a phantom folder.
+export function createSetFolderHandler(
+  access: AccessRule = DEFAULT_FOLDER_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "set-folder",
+    schema: setFolderPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as SetFolderPayload; // @cast-boundary engine-payload
+      const id = folderAssignmentAggregateId(
+        event.user.tenantId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const folder = await folderExecutor.detail({ id: payload.folderId }, event.user, ctx.db);
+      if (!folder) return writeFailure(new NotFoundError("folder", payload.folderId));
+
+      const existing = await folderAssignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (existing) {
+        if (existing["folderId"] === payload.folderId) {
+          return { isSuccess: true as const, data: { id } };
+        }
+        return folderAssignmentExecutor.update(
+          { id, changes: { folderId: payload.folderId } },
+          event.user,
+          ctx.db,
+          { skipOptimisticLock: true },
+        );
+      }
+
+      const restored = await folderAssignmentExecutor.restore({ id }, event.user, ctx.db);
+      if (restored.isSuccess) {
+        return folderAssignmentExecutor.update(
+          { id, changes: { folderId: payload.folderId } },
+          event.user,
+          ctx.db,
+          { skipOptimisticLock: true },
+        );
+      }
+      if (restored.error.code !== "not_found") return restored;
+
+      return folderAssignmentExecutor.create(
+        {
+          id,
+          folderId: payload.folderId,
+          entityType: payload.entityType,
+          entityId: payload.entityId,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const setFolderHandler: WriteHandlerDef = createSetFolderHandler();

package/src/folders/index.ts

@@ -0,0 +1,23 @@
+export { folderAssignmentAggregateId } from "./aggregate-id";
+export {
+  DEFAULT_FOLDER_ACCESS,
+  DEFAULT_FOLDER_ROLES,
+  FOLDER_SECTION_EXTENSION_NAME,
+  FOLDERS_FEATURE_NAME,
+  FoldersHandlers,
+  FoldersQueries,
+} from "./constants";
+export { folderAssignmentEntity, folderEntity } from "./entity";
+export {
+  createFoldersFeature,
+  type FoldersFeatureOptions,
+  foldersFeature,
+} from "./feature";
+export { clearFolderHandler, createClearFolderHandler } from "./handlers/clear-folder.write";
+export { createSetFolderHandler, setFolderHandler } from "./handlers/set-folder.write";
+export {
+  type ClearFolderPayload,
+  clearFolderPayloadSchema,
+  type SetFolderPayload,
+  setFolderPayloadSchema,
+} from "./schemas";

package/src/folders/schemas.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+// set-folder + clear-folder share the (entity) reference shape; set-folder adds
+// the target folderId. Folder catalog CRUD (create/update/delete) uses the
+// generic defineEntity*Handler schemas — no hand-written schema needed there.
+const entityRef = {
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+} as const;
+
+export const setFolderPayloadSchema = z.object({
+  folderId: z.string().min(1).max(64),
+  ...entityRef,
+});
+export type SetFolderPayload = z.infer<typeof setFolderPayloadSchema>;
+
+export const clearFolderPayloadSchema = z.object(entityRef);
+export type ClearFolderPayload = z.infer<typeof clearFolderPayloadSchema>;

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

@@ -0,0 +1,181 @@
+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 { FolderSection } from "../folder-section";
+import { defaultTranslations } from "../i18n";
+
+type FolderRow = { id: string; name: string; parentId: string | null; version: number };
+type AssignmentRow = { folderId: string; entityType: string; entityId: string };
+
+let folderRows: readonly FolderRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+
+beforeEach(() => {
+  folderRows = [];
+  assignmentRows = [];
+});
+
+const dispatchSpy = mock(async (type: string) =>
+  type === FoldersHandlers.createFolder
+    ? { isSuccess: true, data: { id: "folder-new" } }
+    : { isSuccess: true, data: undefined },
+);
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === FoldersQueries.folderList ? { rows: folderRows } : { rows: assignmentRows },
+  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>
+  );
+}
+
+// The real combobox is cmdk + Radix (popover = e2e/primitive-test territory).
+// A headless single-select stub renders one button per option and fires
+// onChange(value) — same contract, no popover — so the select/clear → set/clear
+// wiring is pinnable in jsdom.
+const StubInput: typeof defaultPrimitives.Input = (props) => {
+  if (props.kind === "combobox" && props.multiple !== true) {
+    return (
+      <div data-testid="stub-combobox">
+        {props.options.map((o) => (
+          <button
+            key={o.value}
+            type="button"
+            data-testid={`folder-opt-${o.value === "" ? "none" : o.value}`}
+            onClick={() => props.onChange(o.value)}
+          >
+            {o.label}
+          </button>
+        ))}
+      </div>
+    );
+  }
+  return <input data-testid={`stub-${props.id}`} />;
+};
+
+function StubComboboxWrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={{ ...defaultPrimitives, Input: StubInput }}>
+        {children}
+      </PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("FolderSection", () => {
+  test("options carry the full folder path (not just the leaf name)", () => {
+    folderRows = [
+      { id: "f1", name: "Immobilie", parentId: null, version: 1 },
+      { id: "f2", name: "Müller", parentId: "f1", version: 1 },
+    ];
+    assignmentRows = [{ folderId: "f1", entityType: "credit", entityId: "c-1" }];
+
+    render(
+      <StubComboboxWrapper>
+        <FolderSection entityName="credit" entityId="c-1" />
+      </StubComboboxWrapper>,
+    );
+    expect(screen.getByText("Immobilie / Müller")).toBeTruthy();
+  });
+
+  test("selecting a different folder dispatches set-folder", async () => {
+    folderRows = [
+      { id: "f1", name: "A", parentId: null, version: 1 },
+      { id: "f2", name: "B", parentId: null, version: 1 },
+    ];
+    assignmentRows = [{ folderId: "f1", entityType: "credit", entityId: "c-1" }];
+    dispatchSpy.mockClear();
+
+    render(
+      <StubComboboxWrapper>
+        <FolderSection entityName="credit" entityId="c-1" />
+      </StubComboboxWrapper>,
+    );
+    fireEvent.click(screen.getByTestId("folder-opt-f2"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.setFolder, {
+        folderId: "f2",
+        entityType: "credit",
+        entityId: "c-1",
+      }),
+    );
+  });
+
+  test("selecting the no-folder option dispatches clear-folder", async () => {
+    folderRows = [{ id: "f1", name: "A", parentId: null, version: 1 }];
+    assignmentRows = [{ folderId: "f1", entityType: "credit", entityId: "c-1" }];
+    dispatchSpy.mockClear();
+
+    render(
+      <StubComboboxWrapper>
+        <FolderSection entityName="credit" entityId="c-1" />
+      </StubComboboxWrapper>,
+    );
+    fireEvent.click(screen.getByTestId("folder-opt-none"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.clearFolder, {
+        entityType: "credit",
+        entityId: "c-1",
+      }),
+    );
+  });
+
+  test("create-and-file dispatches create-folder, then set-folder with the new id", async () => {
+    folderRows = [];
+    assignmentRows = [];
+    dispatchSpy.mockClear();
+
+    render(
+      <Wrapper>
+        <FolderSection entityName="credit" entityId="c-9" />
+      </Wrapper>,
+    );
+    fireEvent.change(document.getElementById("folder-section-new") as HTMLInputElement, {
+      target: { value: "Neuer" },
+    });
+    fireEvent.click(screen.getByTestId("folder-section-create"));
+
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.createFolder, { name: "Neuer" }),
+    );
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(FoldersHandlers.setFolder, {
+        folderId: "folder-new",
+        entityType: "credit",
+        entityId: "c-9",
+      }),
+    );
+  });
+
+  test("create-mode (no entityId yet) shows the save-first hint instead of the picker", () => {
+    render(
+      <Wrapper>
+        <FolderSection entityName="credit" entityId={null} />
+      </Wrapper>,
+    );
+    expect(screen.getByTestId("folder-section-create-mode")).toBeTruthy();
+    expect(screen.queryByTestId("folder-section")).toBeNull();
+  });
+});

package/src/folders/web/__tests__/tree.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { buildFolderTree, type FolderRow, folderPath } from "../tree";
+
+const f = (id: string, name: string, parentId: string | null = null): FolderRow => ({
+  id,
+  name,
+  parentId,
+  version: 1,
+});
+
+describe("buildFolderTree", () => {
+  test("empty input → no roots", () => {
+    expect(buildFolderTree([])).toEqual([]);
+  });
+
+  test("flat roots are sorted by name with depth 0", () => {
+    const tree = buildFolderTree([f("2", "Beta"), f("1", "Alpha")]);
+    expect(tree.map((n) => n.name)).toEqual(["Alpha", "Beta"]);
+    expect(tree.every((n) => n.depth === 0 && n.children.length === 0)).toBe(true);
+  });
+
+  test("children nest under their parent with incremented depth", () => {
+    const tree = buildFolderTree([
+      f("root", "Root"),
+      f("child", "Child", "root"),
+      f("grandchild", "Grandchild", "child"),
+    ]);
+    expect(tree).toHaveLength(1);
+    const root = tree[0]!;
+    expect(root.children).toHaveLength(1);
+    expect(root.children[0]!.depth).toBe(1);
+    expect(root.children[0]!.children[0]!.name).toBe("Grandchild");
+    expect(root.children[0]!.children[0]!.depth).toBe(2);
+  });
+
+  test("a row whose parentId points at a deleted parent surfaces as a root", () => {
+    const tree = buildFolderTree([f("orphan", "Orphan", "gone")]);
+    expect(tree).toHaveLength(1);
+    expect(tree[0]!.name).toBe("Orphan");
+    expect(tree[0]!.depth).toBe(0);
+  });
+});
+
+describe("folderPath", () => {
+  const rows = [f("a", "Immobilie"), f("b", "Müller", "a"), f("c", "Kredit", "b")];
+
+  test("root folder → just its name", () => {
+    expect(folderPath(rows, "a")).toBe("Immobilie");
+  });
+
+  test("nested folder → full path", () => {
+    expect(folderPath(rows, "c")).toBe("Immobilie / Müller / Kredit");
+  });
+
+  test("unknown id → empty string", () => {
+    expect(folderPath(rows, "nope")).toBe("");
+  });
+});

package/src/folders/web/client-plugin.tsx

@@ -0,0 +1,16 @@
+// @runtime client
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { FOLDER_SECTION_EXTENSION_NAME, FOLDERS_FEATURE_NAME } from "../constants";
+import { FolderSection } from "./folder-section";
+import { defaultTranslations } from "./i18n";
+
+export function foldersClient(): ClientFeatureDefinition {
+  return {
+    name: FOLDERS_FEATURE_NAME,
+    extensionSectionComponents: {
+      [FOLDER_SECTION_EXTENSION_NAME]: FolderSection,
+    },
+    translations: defaultTranslations,
+  };
+}