@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/wizard-form.md

@@ -0,0 +1,379 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/wizard-form. Do not edit. -->
+
+# wizard-form
+
+EditLayout.mode: "wizard" — a multi-step entity form with a review step that reads live form values through an extension section, and draft: true resuming the in-progress form via the bundled form-draft feature.
+
+## README
+
+# Wizard form
+
+An `entityEdit` screen with `EditLayout.mode: "wizard"` — one section per
+step instead of one long form. The final step is a review section
+(`kind: "extension"`) that reads the wizard's live values instead of
+re-fetching them, and `draft: true` resumes an abandoned wizard from where
+the user left off.
+
+## What it shows
+
+- **`mode: "wizard"`** — the same three sections a `"single"` layout would
+  render all at once instead render one per step, with a progress
+  indicator and per-step validation. The boot-validator requires at least
+  two sections, each with a non-empty `title`.
+- **A review step as an extension section** — the third step
+  (`kind: "extension"`) mounts `ListingReviewSection`, a client component
+  resolved by the `__component` name at render time. It receives the host
+  form's current values through `ExtensionSectionProps.values` (the same
+  live snapshot the other steps edit) and renders them read-only via
+  `DetailList` — no second fetch, no duplicated state.
+- **`draft: true`** — persists the in-progress wizard as a resumable draft.
+  This flag only does two things in the feature: it requires
+  `mode: "wizard"` and it requires the bundled `form-draft` feature to be
+  mounted alongside this one (both enforced at boot). The actual
+  save/resume/discard wiring happens automatically inside `RenderEdit` —
+  this recipe never calls a form-draft handler from its own code.
+
+## Feature composition
+
+```
+listing     — the entity being created through the wizard
+form-draft  — bundled feature backing draft: true (mounted, never called
+              directly by this feature — RenderEdit wires it client-side)
+config      — form-draft requires this for its retention-days setting;
+              mount createConfigFeature() alongside form-draft
+```
+
+## Flow
+
+1. A user opens the `listing-wizard` screen and fills in the "Basics"
+   step, then "Pricing".
+2. If they navigate away mid-wizard, `RenderEdit` has already saved a
+   draft under a client-minted `${screen.id}:new:${draftId}` key
+   (sessionStorage-backed); reopening the same tab resumes those values
+   instead of starting over. A new tab has no `draftId` yet — it falls
+   back to `form-draft:query:list` and either auto-adopts a single
+   in-progress draft or offers a picker when there's more than one.
+3. On the "Review" step, `ListingReviewSection` reads the values entered
+   so far straight from the host form and displays them read-only — no
+   extra network round-trip.
+4. Submitting creates the `listing` through the standard CRUD create and
+   discards the draft.
+
+## When to reach for it
+
+A form is long enough that one page of fields overwhelms the user, or
+losing everything on an accidental tab close is a real cost — onboarding,
+a multi-part application, anything a user is likely to fill in over more
+than one sitting. Use a `"single"`-mode layout instead when the form is
+short enough to fit on one screen; wizard mode's per-step validation and
+draft persistence are overhead a short form doesn't need.
+
+## Source
+
+The feature entry point is `src/feature.ts`; the review-step component is
+`src/web/listing-review-section.tsx`. `src/web/index.ts` exports
+`listingsClient`, a `ClientFeatureDefinition` that registers
+`ListingReviewSection` under the `__component` name `feature.ts`'s review
+section points at — an app mounting this recipe must include
+`listingsClient` in `createKumikoApp`'s `clientFeatures`, or the review
+step falls back to `RenderEdit`'s unregistered-extension placeholder
+instead of rendering the real component. The integration test under
+`src/__tests__/` covers the entity's CRUD create through the wizard's
+fields and the form-draft save/get/discard round-trip that backs
+`draft: true`. `e2e/wizard.spec.ts` is a Playwright spec against the real
+client bundle (mounted via `listingsClient`, the same registration an app
+would use) — step navigation, per-step validation blocking Next on empty required fields,
+draft-resume after a page reload, and that a successful submit discards
+the draft (reopening the wizard starts fresh on step 1).
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Wizard Form Sample — Integration Test
+// Proves: the listing entity + wizard-mode screen boot together (the
+// boot-validator's wizard rules — >= 2 titled sections, draft: true only
+// with mode: "wizard" and form-draft mounted — all pass for this feature
+// combination), the entity's CRUD create works end-to-end, and the
+// form-draft save/get/discard round-trip that backs `draft: true` behaves
+// exactly as a resumed-then-submitted wizard would use it.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  FormDraftHandlers,
+  FormDraftQueries,
+  formDraftEntity,
+  formDraftFeature,
+} from "@cosmicdrift/kumiko-bundled-features/form-draft";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { listingEntity, listingsFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const otherUser = createTestUser({ id: 2, roles: ["Admin"] });
+
+// Arbitrary draftKey for exercising the handler contract directly — this
+// suite calls FormDraftHandlers/FormDraftQueries with an explicit key, it
+// doesn't go through RenderEdit's client-side derivation (which mints its
+// own `${screenId}:new:${draftId}` for a create-mode wizard, issue #1913).
+const DRAFT_KEY = "listing-wizard";
+
+beforeAll(async () => {
+  // form-draft requires the "config" feature (its retention-days setting).
+  stack = await setupTestStack({
+    features: [listingsFeature, formDraftFeature, createConfigFeature()],
+  });
+  await unsafeCreateEntityTable(stack.db, listingEntity);
+  await unsafeCreateEntityTable(stack.db, formDraftEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("listing:create", () => {
+  test("creates a listing with the wizard's fields", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "listings:write:listing:create",
+      { title: "Vintage desk lamp", category: "furniture", price: 42, condition: "used" },
+      admin,
+    );
+
+    expect(created.data["title"]).toBe("Vintage desk lamp");
+    expect(created.data["category"]).toBe("furniture");
+    expect(created.data["price"]).toBe(42);
+    expect(created.data["condition"]).toBe("used");
+  });
+
+  test("condition defaults to used when omitted", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "listings:write:listing:create",
+      { title: "Old bicycle", category: "vehicles", price: 80 },
+      admin,
+    );
+
+    expect(created.data["condition"]).toBe("used");
+  });
+});
+
+describe("wizard draft resume", () => {
+  test("save persists the in-progress steps, get resumes them", async () => {
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      {
+        draftKey: DRAFT_KEY,
+        values: { title: "Draft title", category: "electronics" },
+        stepIndex: 1,
+      },
+      admin,
+    );
+
+    const resumed = await stack.http.queryOk<{ draft: { values: Record<string, unknown> } | null }>(
+      FormDraftQueries.get,
+      { draftKey: DRAFT_KEY },
+      admin,
+    );
+
+    expect(resumed.draft?.values["title"]).toBe("Draft title");
+    expect(resumed.draft?.values["category"]).toBe("electronics");
+  });
+
+  test("a later save overwrites the earlier one, not duplicates it", async () => {
+    const key = "listing-wizard:overwrite";
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      { draftKey: key, values: { title: "First pass" }, stepIndex: 0 },
+      admin,
+    );
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      { draftKey: key, values: { title: "Second pass", category: "other" }, stepIndex: 1 },
+      admin,
+    );
+
+    const resumed = await stack.http.queryOk<{ draft: { values: Record<string, unknown> } | null }>(
+      FormDraftQueries.get,
+      { draftKey: key },
+      admin,
+    );
+
+    expect(resumed.draft?.values["title"]).toBe("Second pass");
+  });
+
+  test("discard clears the draft — the next get resolves null, same as a completed submit", async () => {
+    const key = "listing-wizard:discard";
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      { draftKey: key, values: { title: "About to submit" }, stepIndex: 2 },
+      admin,
+    );
+
+    await stack.http.writeOk(FormDraftHandlers.discard, { draftKey: key }, admin);
+
+    const afterDiscard = await stack.http.queryOk<{ draft: unknown }>(
+      FormDraftQueries.get,
+      { draftKey: key },
+      admin,
+    );
+    expect(afterDiscard.draft).toBeNull();
+  });
+
+  test("a foreign user's get never resolves another user's draft", async () => {
+    const key = "listing-wizard:isolated";
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      { draftKey: key, values: { title: "Only mine" }, stepIndex: 0 },
+      admin,
+    );
+
+    const foreign = await stack.http.queryOk<{ draft: unknown }>(
+      FormDraftQueries.get,
+      { draftKey: key },
+      otherUser,
+    );
+    expect(foreign.draft).toBeNull();
+  });
+});
+```
+
+### src/entities/listing.ts
+
+```ts
+import {
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const listingEntity = createEntity({
+  table: "read_sample_listings",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+    }),
+    category: createSelectField({
+      options: ["electronics", "furniture", "vehicles", "other"] as const,
+      required: true,
+    }),
+    price: createNumberField({ required: true }),
+    condition: createSelectField({
+      options: ["new", "used"] as const,
+      default: "used",
+    }),
+  },
+});
+```
+
+### src/feature.ts
+
+```ts
+// Wizard Form Sample
+// Shows: EditLayout.mode: "wizard" splitting one entityEdit screen into
+// steps, a review step (kind: "extension") that reads the host form's
+// live values through ExtensionSectionProps.values instead of its own
+// fetch, and draft: true resuming an in-progress wizard via the bundled
+// form-draft feature — the actual save/get/discard wiring is automatic
+// client-side, this feature only turns the two flags on. form-draft itself
+// requires the bundled "config" feature (its retention-days setting), so
+// any app mounting this recipe must mount that too.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { listingEntity } from "./entities/listing";
+
+export { listingEntity } from "./entities/listing";
+
+const editorWrite = { access: { roles: ["Admin", "User"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list and view listings; writes are still gated by editorWrite",
+    },
+  },
+} as const;
+
+export const listingsFeature = defineFeature("listings", (r) => {
+  r.crud("listing", listingEntity, { write: editorWrite, read: openRead });
+
+  r.screen({
+    id: "listing-wizard",
+    type: "entityEdit",
+    entity: "listing",
+    layout: {
+      mode: "wizard",
+      draft: true,
+      sections: [
+        { title: "Basics", fields: ["title", "category"] },
+        { title: "Pricing", fields: ["price", "condition"] },
+        {
+          kind: "extension",
+          title: "Review",
+          component: { react: { __component: "ListingReviewSection" } },
+        },
+      ],
+    },
+    access: editorWrite.access,
+  });
+});
+```
+
+### src/web/index.ts
+
+```ts
+// Client-side registration for the review step's extension section (see
+// ../feature.ts's `component: { react: { __component: "ListingReviewSection" } }`).
+// A `kind: "extension"` section only resolves through
+// clientFeatures.extensionSectionComponents (createKumikoApp → ExtensionSectionsProvider)
+// — never imported directly from feature.ts, which keeps the server file
+// free of the renderer-web graph. Without registering this export, an app
+// mounting this recipe gets RenderEdit's fallback placeholder instead of
+// the real review step.
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { ListingReviewSection } from "./listing-review-section";
+
+export const listingsClient: ClientFeatureDefinition = {
+  name: "listings",
+  extensionSectionComponents: { ListingReviewSection },
+};
+```
+
+### src/web/listing-review-section.tsx
+
+```tsx
+import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import { DetailList } from "@cosmicdrift/kumiko-renderer-web";
+import type { ReactNode } from "react";
+
+// Registered under the `__component` name the feature's review section
+// points at (see feature.ts) — never imported by feature.ts itself, the
+// string name is the only link so the server file stays free of the
+// renderer-web graph.
+export function ListingReviewSection({ values }: ExtensionSectionProps): ReactNode {
+  return (
+    <DetailList
+      testId="listing-review"
+      rows={[
+        { label: "Title", value: String(values?.["title"] ?? "") },
+        { label: "Category", value: String(values?.["category"] ?? "") },
+        { label: "Price", value: String(values?.["price"] ?? "") },
+        { label: "Condition", value: String(values?.["condition"] ?? "") },
+      ]}
+    />
+  );
+}
+```