@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/embedded-entity-form.md

@@ -0,0 +1,598 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/embedded-entity-form. Do not edit. -->
+
+# embedded-entity-form
+
+RenderEdit hosted in a Drawer, no screen or route — externally-sourced prefill, controlled mode, and a custom write handler instead of the built-in CRUD create.
+
+## README
+
+# Embedded entity form
+
+Host `RenderEdit` inside a `Drawer` instead of a dedicated screen — no nav
+entry, no route. The form is prefilled from an externally-sourced record
+(a suggestion, not this entity's own detail query), runs in controlled mode
+so the host can read live dirty/valid state and re-validate after patching
+values from outside, and saves through a custom write handler instead of
+the built-in CRUD create.
+
+## What it shows
+
+- **`RenderEdit` without a screen or route** — `screen` is a plain
+  `EntityEditScreenDefinition` literal, never passed to `r.screen`. Nothing
+  about `RenderEdit` touches Nav or the router.
+- **Create-mode prefill from an external source** — `initial` comes from a
+  `suggestion` prop, `entityId={null}`, no detail-fetch for the entity being
+  created.
+- **Controlled mode** — `onChange` reports `{ dirty, valid }` on every
+  keystroke; `onControlsReady` hands back `patch`/`validate` so the Drawer's
+  footer can restore the suggestion's values and re-validate without a
+  remount or a write.
+- **`customSubmit` instead of the built-in CRUD create** — the client sends
+  only the fields the user actually changed (`snapshot.changes`, the same
+  delta the controlled mode reports); `prospect:accept` merges that onto the
+  suggestion it already has server-side.
+- **One write, two entities, atomically** — `prospect:accept` creates the
+  prospect, stamps `source`/`acceptedBy`/`acceptedAt` (fields never on the
+  edit form, so the client can't set them), and flips the suggestion to
+  `accepted` — the same DB transaction, so a suggestion never ends up
+  accepted without a prospect or vice versa.
+
+## Feature composition
+
+```
+suggestion — externally-sourced draft, seeded via the standard CRUD create
+prospect   — created only through prospect:accept, never through r.crud
+```
+
+## Flow
+
+1. A caller has a `suggestion` (elsewhere seeded, e.g. by an AI extraction
+   pipeline) and opens `AcceptSuggestionDrawer` next to it.
+2. The Drawer prefills `RenderEdit` from the suggestion's fields.
+3. The user edits a field or two; `onChange` updates the live status text.
+4. Submit calls `customSubmit`, which dispatches `prospect:accept` with
+   just `{ suggestionId, changes }`.
+5. The handler merges `changes` onto the suggestion, creates the prospect,
+   and marks the suggestion `accepted`. A second accept on the same
+   suggestion is rejected (`unprocessable`).
+
+## When to reach for it
+
+You have a form that belongs next to something else — a list row, an inbox
+item, a reference field — not on its own page, and saving it needs more
+than a single-entity CRUD write (merging server-known data, writing a
+second record, stamping fields the client must not control). Use the plain
+`writeCommand` + built-in submit path instead when the form both lives on
+its own screen and a single CRUD write is enough.
+
+## Source
+
+The feature entry point is `src/feature.ts`; the Drawer component is
+`src/web/accept-suggestion-drawer.tsx`. Integration tests under
+`src/__tests__/` cover the merge, the atomic status flip, the double-accept
+rejection, and per-role access.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Embedded Entity Form Sample — Integration Test
+// Proves: prospect:accept merges client changes onto the suggestion it
+// already knows, stamps provenance the client never sent, flips the
+// suggestion to accepted, and rejects a second accept on the same
+// suggestion.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { prospectEntity, prospectsFeature, suggestionEntity } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const viewer = createTestUser({ id: 2, roles: ["Viewer"] });
+
+async function seedSuggestion(overrides: Partial<Record<string, unknown>> = {}): Promise<string> {
+  const created = await stack.http.writeOk<SaveContext>(
+    "prospects:write:suggestion:create",
+    { name: "Max Mustermann", email: "max@test.de", company: "Acme", ...overrides },
+    admin,
+  );
+  return created.id as string;
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [prospectsFeature] });
+  await unsafeCreateEntityTable(stack.db, suggestionEntity);
+  await unsafeCreateEntityTable(stack.db, prospectEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("prospect:accept", () => {
+  test("creates a prospect merged from the suggestion, no client-sent changes", async () => {
+    const suggestionId = await seedSuggestion();
+
+    const accepted = await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      admin,
+    );
+
+    expect(accepted.data["name"]).toBe("Max Mustermann");
+    expect(accepted.data["email"]).toBe("max@test.de");
+    expect(accepted.data["company"]).toBe("Acme");
+    expect(accepted.data["source"]).toBe(`suggestion:${suggestionId}`);
+    expect(accepted.data["acceptedBy"]).toBe(`user:${admin.id}`);
+    expect(typeof accepted.data["acceptedAt"]).toBe("string");
+  });
+
+  test("client changes override the suggestion's field values", async () => {
+    const suggestionId = await seedSuggestion({ name: "Draft Name" });
+
+    const accepted = await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: { name: "Corrected Name" } },
+      admin,
+    );
+
+    expect(accepted.data["name"]).toBe("Corrected Name");
+  });
+
+  test("client-sent provenance fields in changes are ignored, not adopted", async () => {
+    const suggestionId = await seedSuggestion();
+
+    const accepted = await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      {
+        suggestionId,
+        changes: { name: "X", source: "evil", acceptedBy: "user:999" },
+      },
+      admin,
+    );
+
+    expect(accepted.data["name"]).toBe("X");
+    expect(accepted.data["source"]).toBe(`suggestion:${suggestionId}`);
+    expect(accepted.data["acceptedBy"]).toBe(`user:${admin.id}`);
+  });
+
+  test("flips the suggestion to accepted", async () => {
+    const suggestionId = await seedSuggestion();
+
+    await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "prospects:query:suggestion:detail",
+      { id: suggestionId },
+      admin,
+    );
+    expect(detail["status"]).toBe("accepted");
+  });
+
+  test("a second accept on the same suggestion is rejected", async () => {
+    const suggestionId = await seedSuggestion();
+
+    await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      admin,
+    );
+    expect(error.code).toBe("unprocessable");
+  });
+
+  test("accepting an unknown suggestion is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "prospects:write:prospect:accept",
+      { suggestionId: "00000000-0000-4000-8000-000000000999", changes: {} },
+      admin,
+    );
+    expect(error.code).toBe("not_found");
+  });
+
+  test("only Admin can accept", async () => {
+    const suggestionId = await seedSuggestion();
+
+    const error = await stack.http.writeErr(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("clearing the email via changes is accepted, not rejected as an invalid address", async () => {
+    const suggestionId = await seedSuggestion();
+
+    const accepted = await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: { email: "" } },
+      admin,
+    );
+
+    expect(accepted.data["email"]).toBe("");
+  });
+});
+
+// kumiko-framework#1905: `suggestion.status` must only ever flip
+// pending → accepted through prospect:accept, which stamps provenance the
+// client can't set itself. A generic suggestion:update write would let an
+// admin set `{ status: "accepted" }` directly, bypassing that path — the
+// CRUD registration now omits the `update` verb, so the handler doesn't
+// exist at all.
+describe("suggestion:update", () => {
+  test("does not exist — an admin cannot flip status directly, bypassing prospect:accept", async () => {
+    const suggestionId = await seedSuggestion();
+
+    const error = await stack.http.writeErr(
+      "prospects:write:suggestion:update",
+      { id: suggestionId, version: 1, changes: { status: "accepted" } },
+      admin,
+    );
+
+    expect(error.code).toBe("not_found");
+  });
+});
+
+describe("prospect:detail", () => {
+  test("reads back the created prospect", async () => {
+    const suggestionId = await seedSuggestion();
+    const accepted = await stack.http.writeOk<SaveContext>(
+      "prospects:write:prospect:accept",
+      { suggestionId, changes: {} },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "prospects:query:prospect:detail",
+      { id: accepted.id },
+      viewer,
+    );
+    expect(detail["name"]).toBe("Max Mustermann");
+  });
+});
+```
+
+### src/entities/prospect.ts
+
+```ts
+import {
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Created only through `prospect:accept` — never through a built-in CRUD
+// create, so `source`/`acceptedBy`/`acceptedAt` are never on the edit form
+// and a client can't set them itself.
+export const prospectEntity = createEntity({
+  table: "read_sample_prospects",
+  fields: {
+    name: createTextField({ required: true, personal: "self", find: "fuzzy" }),
+    email: createTextField({ format: "email", personal: "self", find: "none" }),
+    company: createTextField({ personal: false, reason: "is_business_data" }),
+    notes: createTextField({ personal: { of: "id" }, find: "none" }),
+    source: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    acceptedBy: createTextField({ personal: "ref", required: true }),
+    acceptedAt: createTimestampField({ required: true }),
+  },
+});
+```
+
+### src/entities/suggestion.ts
+
+```ts
+import {
+  createEntity,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// The externally-sourced draft (e.g. an AI extraction from an inbox item).
+// Seeded via the standard CRUD create — `prospect:accept` is the only path
+// that ever moves it from "pending" to "accepted".
+export const suggestionEntity = createEntity({
+  table: "read_sample_suggestions",
+  fields: {
+    name: createTextField({ required: true, personal: "self", find: "fuzzy" }),
+    email: createTextField({ format: "email", personal: "self", find: "none" }),
+    company: createTextField({ personal: false, reason: "is_business_data" }),
+    notes: createTextField({ personal: { of: "id" }, find: "none" }),
+    status: createSelectField({
+      options: ["pending", "accepted", "rejected"] as const,
+      default: "pending",
+    }),
+  },
+});
+```
+
+### src/feature.ts
+
+```ts
+// Embedded Entity Form Sample
+// Shows: RenderEdit hosted in a Drawer with no dedicated screen/route,
+// prefilled from an externally-sourced record (a suggestion, not this
+// entity's own detail query), controlled mode (onChange + validate-
+// without-write via onControlsReady), and a custom write handler instead
+// of the built-in CRUD create.
+//
+// Tables:
+//   suggestion — an externally-sourced draft (e.g. an AI extraction),
+//                seeded via the standard CRUD create
+//   prospect   — created only through `prospect:accept`, which merges the
+//                caller's field-level changes onto the suggestion it
+//                already knows server-side, stamps provenance the client
+//                can't set itself, and flips the suggestion to accepted —
+//                one atomic write the built-in CRUD create can't do.
+
+import { createEntityExecutor, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+import { prospectEntity } from "./entities/prospect";
+import { suggestionEntity } from "./entities/suggestion";
+
+export { prospectEntity } from "./entities/prospect";
+export { suggestionEntity } from "./entities/suggestion";
+
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may read suggestions and prospects in this recipe; writes " +
+        "are still gated by adminWrite",
+    },
+  },
+} as const;
+
+const acceptChangesSchema = z.object({
+  name: z.string().min(1).optional(),
+  email: z.union([z.email(), z.literal("")]).optional(),
+  company: z.string().optional(),
+  notes: z.string().optional(),
+});
+
+export const prospectsFeature = defineFeature("prospects", (r) => {
+  // No `update` verb: `suggestion.status` must only ever flip pending →
+  // accepted through `prospect:accept` below, which merges the caller's
+  // changes onto the suggestion server-side and stamps provenance the
+  // client can't set itself. A generic `suggestion:update` write would let
+  // an admin set `{ status: "accepted" }` directly, skipping that path
+  // entirely and leaving an "accepted" suggestion with no matching
+  // prospect (see entities/suggestion.ts).
+  r.crud("suggestion", suggestionEntity, {
+    write: adminWrite,
+    read: openRead,
+    verbs: { update: false },
+  });
+  r.entity("prospect", prospectEntity);
+
+  const { executor: suggestionExecutor } = createEntityExecutor("suggestion", suggestionEntity);
+  const { executor: prospectExecutor } = createEntityExecutor("prospect", prospectEntity);
+
+  // Custom handler: the client only ever sends the fields the user actually
+  // edited (RenderEdit's onChange `changes`, same delta the controlled mode
+  // reports) — the handler owns merging that onto the suggestion it already
+  // has, so an untouched field never has to round-trip through the browser.
+  r.writeHandler(
+    "prospect:accept",
+    z.object({ suggestionId: z.uuid(), changes: acceptChangesSchema }),
+    async (event, ctx) => {
+      const suggestion = await suggestionExecutor.detail(
+        { id: event.payload.suggestionId },
+        event.user,
+        ctx.db,
+      );
+      if (!suggestion) return failNotFound("suggestion", event.payload.suggestionId);
+      if (suggestion["status"] !== "pending") {
+        return failUnprocessable("suggestion_already_processed", { status: suggestion["status"] });
+      }
+
+      const created = await prospectExecutor.create(
+        {
+          name: suggestion["name"],
+          email: suggestion["email"],
+          company: suggestion["company"],
+          notes: suggestion["notes"],
+          ...event.payload.changes,
+          source: `suggestion:${event.payload.suggestionId}`,
+          acceptedBy: `user:${event.user.id}`,
+          acceptedAt: getTemporal().Now.instant().toString(),
+        },
+        event.user,
+        ctx.db,
+      );
+      if (!created.isSuccess) return created;
+
+      // Same ctx.db as the create above — one transaction, so a suggestion
+      // never ends up "accepted" without a prospect or vice versa.
+      const flipped = await suggestionExecutor.update(
+        {
+          id: event.payload.suggestionId,
+          version: suggestion["version"] as number,
+          changes: { status: "accepted" },
+        },
+        event.user,
+        ctx.db,
+      );
+      if (!flipped.isSuccess) return flipped;
+      return created;
+    },
+    adminWrite,
+  );
+
+  r.queryHandler(
+    "prospect:detail",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => prospectExecutor.detail(query.payload, query.user, ctx.db),
+    openRead,
+  );
+});
+```
+
+### src/screens/prospect-accept-screen.ts
+
+```ts
+import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+
+// Not registered via `r.screen` — no nav entry, no route. RenderEdit only
+// reads `entity`/`layout` off this object, so a plain literal is enough to
+// host it inside a Drawer.
+export const prospectAcceptScreen: EntityEditScreenDefinition = {
+  id: "prospect-accept-form",
+  type: "entityEdit",
+  entity: "prospect",
+  layout: {
+    sections: [{ fields: ["name", "email", "company", "notes"] }],
+  },
+};
+```
+
+### src/web/accept-suggestion-drawer.tsx
+
+```tsx
+import type { RenderEditControls } from "@cosmicdrift/kumiko-renderer";
+import { RenderEdit, useDispatcher, usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { Drawer } from "@cosmicdrift/kumiko-renderer-web";
+import { type ReactNode, useMemo, useRef, useState } from "react";
+import { z } from "zod";
+import { prospectEntity } from "../entities/prospect";
+import { prospectAcceptScreen } from "../screens/prospect-accept-screen";
+
+const acceptSchema = z.object({
+  name: z.string().min(1),
+  email: z.union([z.email(), z.literal("")]).optional(),
+  company: z.string().optional(),
+  notes: z.string().optional(),
+});
+
+type FormFields = {
+  readonly name: string;
+  readonly email: string;
+  readonly company: string;
+  readonly notes: string;
+};
+
+export type Suggestion = {
+  readonly id: string;
+  readonly name: string;
+  readonly email?: string;
+  readonly company?: string;
+  readonly notes?: string;
+};
+
+// The create handler's success payload is `{ id, ... }` (see prospect:accept
+// in feature.ts) but RenderEdit's onSubmit only types it as `unknown` —
+// narrow defensively instead of casting through it.
+function extractProspectId(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const id = (data as Record<string, unknown>)["id"];
+  return typeof id === "string" ? id : undefined;
+}
+
+function toFormFields(suggestion: Suggestion): FormFields {
+  return {
+    name: suggestion.name,
+    email: suggestion.email ?? "",
+    company: suggestion.company ?? "",
+    notes: suggestion.notes ?? "",
+  };
+}
+
+export type AcceptSuggestionDrawerProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly suggestion: Suggestion;
+  readonly onAccepted: (prospectId: string | undefined) => void;
+};
+
+// Hosts the prospect create-form inside a Drawer next to the suggestion it
+// came from — no dedicated screen/route, prefilled from the suggestion
+// (an external source, not this entity's own detail query), and saved
+// through `prospect:accept` instead of the built-in CRUD create.
+export function AcceptSuggestionDrawer({
+  open,
+  onOpenChange,
+  suggestion,
+  onAccepted,
+}: AcceptSuggestionDrawerProps): ReactNode {
+  const { Button } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const controls = useRef<RenderEditControls<FormFields> | null>(null);
+  const [live, setLive] = useState({ dirty: false, valid: true });
+  const initial = useMemo(() => toFormFields(suggestion), [suggestion]);
+
+  if (!open) return null;
+  return (
+    <Drawer
+      open={open}
+      onOpenChange={onOpenChange}
+      title="Accept suggestion"
+      description={
+        !live.valid
+          ? "Please fill in required fields"
+          : live.dirty
+            ? "Unsaved changes"
+            : "Unchanged from the suggestion"
+      }
+      footer={
+        <Button
+          variant="secondary"
+          onClick={() => {
+            controls.current?.patch(initial);
+            controls.current?.validate();
+          }}
+        >
+          Restore AI suggestion
+        </Button>
+      }
+    >
+      <RenderEdit
+        key={suggestion.id}
+        screen={prospectAcceptScreen}
+        entity={prospectEntity}
+        featureName="prospects"
+        initial={initial}
+        entityId={null}
+        schema={acceptSchema}
+        onChange={({ dirty, valid }) => setLive({ dirty, valid })}
+        onControlsReady={(next) => {
+          controls.current = next;
+        }}
+        customSubmit={async (snapshot) => {
+          const result = await dispatcher.write("prospects:write:prospect:accept", {
+            suggestionId: suggestion.id,
+            changes: snapshot.changes,
+          });
+          return { validationBlocked: false, ...result };
+        }}
+        onSubmit={(result) => {
+          if (result.validationBlocked || !result.isSuccess) return;
+          onAccepted(extractProspectId(result.data));
+          onOpenChange(false);
+        }}
+        onCancel={() => onOpenChange(false)}
+      />
+    </Drawer>
+  );
+}
+```