@cosmicdrift/kumiko-samples 0.338.0

package/samples/apps/styleguide/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@cosmicdrift/kumiko-framework/*": [
+        "../../../packages/framework/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-bundled-features/*": [
+        "../../../packages/bundled-features/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server": [
+        "../../../packages/dev-server/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server/*": [
+        "../../../packages/dev-server/src/*"
+      ],
+      "@cosmicdrift/kumiko-renderer-web": [
+        "../../../packages/renderer-web/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-renderer-web/*": [
+        "../../../packages/renderer-web/src/*"
+      ],
+      "@cosmicdrift/kumiko-dispatcher-live": [
+        "../../../packages/dispatcher-live/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-headless": [
+        "../../../packages/headless/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-renderer": [
+        "../../../packages/renderer/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-renderer/*": ["../../../packages/renderer/src/*"]
+    },
+    "noEmit": true,
+    "rootDir": "../../..",
+    "jsx": "react-jsx",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["bun-types"]
+  },
+  "include": ["src", "e2e", "../../e2e"]
+}

package/samples/apps/ui-walkthrough/README.md

@@ -0,0 +1,105 @@
+# UI Walkthrough
+
+Full-stack demo of the Kumiko renderer: `DefaultAppShell` +
+`LanguageSwitcher` + `ThemeToggle` + `emailPasswordClient` +
+`TenantSwitcher` + tasks CRUD. Boots via `runDevApp` from
+`@cosmicdrift/kumiko-dev-server` in auth mode (login screen before
+access) with two dev tenants so the TenantSwitcher is visible.
+
+## Run
+
+```bash
+# Boot Postgres + Redis (once)
+bun kumiko dev
+
+# In a new terminal — boots the sample on http://localhost:4173
+cd samples/apps/ui-walkthrough && bun dev
+```
+
+Port 4173 is hardcoded in the dev script so three samples can run in
+parallel (workspaces=4174, showcase=4175). Use
+`KUMIKO_DEV_DB_NAME=tasks_demo bun dev` for a persistent DB (data
+survives restarts).
+
+## Design-Abnahme #3381
+
+Features `rental` (319 leases, 19 board rows first) and `vehicles`
+(Octavia + 4 campaigns) mirror the design board masks.
+
+```bash
+bun kumiko dev
+cd samples/apps/ui-walkthrough && bun dev   # http://localhost:4173, admin@kumiko.dev / kumiko-admin
+```
+
+| Mask | Route |
+| --- | --- |
+| Liste | `/lease-list` (pager check: `/lease-list-short`, 3 rows) |
+| Detail | click "Max Nachmieter" (`/lease-detail/00000000-0000-4000-8000-000000003103`), tab "Positionen" |
+| Drawer | Positionen tab, button "Miete anpassen" |
+| Formular | `/vehicle-list`, click "Octavia" (`/vehicle-edit`) |
+| Wizard | `/vehicle-list`, row menu "Schritt für Schritt" (`/vehicle-wizard`), 3x "Weiter" for step 4 |
+| Mobile | `/campaign-list` at 390 px width |
+
+Screenshots (light 1440x900, mobile 390x844, dark for liste and detail):
+
+```bash
+SCREENSHOT_DIR=/path/to/shots bun --env-file=../../../.env x playwright test e2e/screenshots.spec.ts --config=playwright.config.ts
+```
+
+## Schema
+
+`src/run-config.ts` holds `APP_FEATURES` + `HAS_AUTH`. `kumiko/schema.ts`
+derives `ENTITY_METAS` from the same compose path as the dev server — the
+pattern used by `kumiko new app` and production apps like publicstatus.
+
+```bash
+# From this directory — static schema/boot alignment check (no DB)
+bun test src/__tests__/schema-alignment.test.ts
+```
+
+## Login
+
+```
+admin@kumiko.dev
+kumiko-admin
+```
+
+The admin is a member of two tenants — the TenantSwitcher in the
+topbar toggles between "Dev Tenant" (role Admin) and "Beta Tenant"
+(role User), proving tenant-isolated memberships.
+
+## What to try
+
+**Form + validation**
+- Type into **Title** — the form controller pins `dirty` + `changes`.
+- Empty title + submit → `required` validation blocks, no network call.
+- Tick **Is urgent** → the `notes` field appears with a required marker.
+- Submit with urgent + empty notes → field error.
+
+**Optimistic locking**
+- Open the form for a task in tab A.
+- Edit the same task in tab B, save.
+- Tab A: save → banner "Version conflict, reload".
+
+**Tenant switch**
+- Click the tenant switcher in the topbar → switches to the Beta tenant.
+- Task list is empty (Beta has none), role flips to User.
+
+**Theme toggle**
+- Click sun/moon top-right — `<html>` class toggles between `light`
+  and `dark`, Tailwind tokens follow.
+
+**Language**
+- LanguageSwitcher → de/en, nav labels switch instantly
+  (`tasks.nav.list` → "Aufgaben" / "Tasks").
+
+## Tests
+
+```bash
+# From repo root
+bun kumiko test e2e samples/apps/ui-walkthrough
+```
+
+Six Playwright specs: smoke + create flow + update flow + 4 generated
+specs (from the registry-driven E2E generator).
+

package/samples/apps/ui-walkthrough/kumiko/schema.ts

@@ -0,0 +1,14 @@
+// @runtime dev
+// App schema for `kumiko-schema` (validate | generate). Same compose path as
+// runtime boot — see src/run-config.ts.
+
+import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import { APP_FEATURES, HAS_AUTH } from "../src/run-config";
+
+export const FEATURES: readonly FeatureDefinition[] = composeFeatures([...APP_FEATURES], {
+  includeBundled: HAS_AUTH,
+});
+
+export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);

package/samples/apps/ui-walkthrough/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-ui-walkthrough",
+  "description": "Browser live-viewer for the ui-core logic layer. No renderer — raw inputs + a <pre> panel that shows form-state + view-model updating in real time as you type.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "PORT=4173 bun --env-file=../../../.env run kumiko-dev src/app/server.ts",
+    "screenshots": "bun x playwright test e2e/screenshots.spec.ts --config=playwright.config.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-headless": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-web": "workspace:*",
+    "@cosmicdrift/kumiko-server-runtime": "workspace:*",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "zod": "^4.4.3",
+    "@cosmicdrift/kumiko-locale-de": "workspace:*"
+  }
+}

package/samples/apps/ui-walkthrough/playwright.config.ts

@@ -0,0 +1,29 @@
+// @runtime test
+// Playwright-Config für den ui-walkthrough-Durchstich. Startet den
+// echten dev-server als webServer-Fixture, genau wie `bun dev` — nur
+// auf dem Port aus samples/e2e/e2e-ports.ts, damit keine Dev-Session kollidiert.
+//
+// Der dev-server macht auf PORT-Env basierend das HTTP-Binding. Die
+// setupTestStack-Default ist ephemeral (fresh kumiko_test_<random> DB),
+// deshalb braucht's keine DB-Reset-Logik hier.
+
+import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import { E2E_PORTS } from "../../e2e/e2e-ports";
+
+const PORT = E2E_PORTS["framework/ui-walkthrough"];
+
+export default {
+  ...defineAppE2eConfig({
+    port: PORT,
+    serverEntry: "src/app/server.ts",
+    locale: "en-US",
+    env: PLAYWRIGHT_DEMO_ENV,
+  }),
+  // globalSetup spawnt vor allen Tests einen bun-Subprozess der die
+  // Registry auswertet und `e2e/.e2e-data.json` schreibt. Der eigent-
+  // liche generated.spec.ts-Runner liest nur die JSON — framework-
+  // runtime bleibt aus dem Playwright-Worker raus (sonst kollidiert
+  // sie mit Playwrights expect). Nicht Teil von AppE2eConfigInput,
+  // daher als Zusatzfeld auf dem template-erzeugten Config-Objekt.
+  globalSetup: "./e2e/global-setup.ts",
+};

package/samples/apps/ui-walkthrough/scripts/emit-e2e-data.ts

@@ -0,0 +1,19 @@
+// Emitter für e2e/.e2e-data.json. Läuft unter bun, lädt die volle
+// framework-runtime, baut die Registry und schreibt generateE2ESpec()-
+// Output als JSON. Playwrights globalSetup ruft dieses Script vor
+// jedem Run als Subprozess — dadurch landet framework-runtime NIE im
+// Playwright-Worker (wo sie mit Playwrights expect kollidiert).
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { generateE2ESpec } from "@cosmicdrift/kumiko-framework/testing/e2e-generator";
+import { taskFeature } from "../src/features/tasks";
+
+const outPath = resolve(import.meta.dir, "..", "e2e", ".e2e-data.json");
+const specs = generateE2ESpec(createRegistry([taskFeature]));
+
+await mkdir(dirname(outPath), { recursive: true });
+await writeFile(outPath, JSON.stringify(specs, null, 2), "utf8");
+
+console.log(`[emit-e2e-data] wrote ${specs.length} spec(s) → ${outPath}`);

package/samples/apps/ui-walkthrough/src/app/assistant-action.tsx

@@ -0,0 +1,49 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { WandSparkles } from "lucide-react";
+import { type ReactNode, useEffect, useState } from "react";
+
+const noop = (): void => {};
+
+export function AssistantAction(): ReactNode {
+  const { Dialog } = usePrimitives();
+  const [open, setOpen] = useState(false);
+
+  // Registered here on purpose: an overflow menu that unmounts this component
+  // must visibly lose the shortcut.
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  return (
+    <>
+      <button
+        type="button"
+        data-testid="assistant-action"
+        onClick={() => setOpen(true)}
+        className="inline-flex h-9 items-center gap-2 rounded-md border border-border bg-card px-3 text-sm font-medium text-foreground hover:bg-accent"
+      >
+        <WandSparkles className="h-4 w-4" aria-hidden="true" />
+        Assistent
+        <kbd className="rounded border border-border px-1 font-sans text-xs text-muted-foreground">
+          ⌘K
+        </kbd>
+      </button>
+      <Dialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Assistent"
+        description="Der Assistent ist im Walkthrough nicht angebunden."
+        confirmLabel="Schließen"
+        onConfirm={noop}
+        testId="assistant-dialog"
+      />
+    </>
+  );
+}

package/samples/apps/ui-walkthrough/src/app/auth-constants.ts

@@ -0,0 +1,20 @@
+// Reine Konstanten — kein Framework-Import. Wird sowohl von seed.ts
+// (server-Seite, idempotent admin-Anlage) als auch vom E2E-Helper
+// `e2e/_helpers/login.ts` gelesen.
+//
+// Warum getrennt: e2e-Specs laufen im Playwright-Worker, der nichts aus
+// `@cosmicdrift/kumiko-framework/testing` (zieht `vitest`) oder
+// `@cosmicdrift/kumiko-bundled-features/.../testing` (zieht das ebenfalls) ertragen
+// kann — Vitest's expect redefined Object.prototype-Symbole und kollidiert
+// mit Playwrights expect. Diese Datei bleibt importchain-leer und ist die
+// einzige sichere shared Quelle für die Login-Strings.
+
+export const ADMIN_EMAIL = "admin@kumiko.dev";
+export const ADMIN_PASSWORD = "kumiko-admin";
+
+// Tenant-IDs gespiegelt zwischen server.ts (TenantId-Cast) und client.tsx
+// (plain string für tenantName-Mapping). Hier zentral als plain strings,
+// da diese Datei framework-frei bleibt — server.ts macht den
+// `as TenantId`-Cast lokal.
+export const DEV_TENANT_ID = "00000000-0000-4000-8000-000000000001";
+export const BETA_TENANT_ID = "00000000-0000-4000-8000-000000000002";

package/samples/apps/ui-walkthrough/src/app/client.tsx

@@ -0,0 +1,21 @@
+// Browser-Entry. Sammelt nur die ClientFeatures (auth + tasks) und
+// übergibt Shell + clientFeatures an createKumikoApp.
+
+import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { localeDeClient } from "@cosmicdrift/kumiko-locale-de/web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { rentalClient } from "../features/rental/web";
+import { tasksClient } from "../features/tasks/web";
+import { vehiclesClient } from "../features/vehicles/web";
+import { AppShell } from "./shell";
+
+createKumikoApp({
+  shell: AppShell,
+  clientFeatures: [
+    localeDeClient(),
+    emailPasswordClient(),
+    tasksClient,
+    rentalClient,
+    vehiclesClient,
+  ],
+});

package/samples/apps/ui-walkthrough/src/app/seed-rental.ts

@@ -0,0 +1,266 @@
+// Board rows carry fixed ascending ids: the list ties on `beginn` (many equal
+// dates) and breaks by id ASC, so the screenshot order is reproducible.
+
+import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { countRowsForTenant } from "../db/queries/row-counts";
+import { leaseExecutor, partyExecutor, positionExecutor } from "../features/rental/lease-support";
+
+type BoardLease = {
+  readonly mieter: string;
+  readonly einheit: string;
+  readonly liegenschaft: string;
+  readonly beginn: string;
+  readonly ende?: string;
+  readonly miete: number;
+};
+
+const BOARD_LEASES: readonly BoardLease[] = [
+  {
+    mieter: "Otto Freihand",
+    einheit: "WE-42",
+    liegenschaft: "Haus Freihandweg",
+    beginn: "2026-10-01",
+    miete: 720,
+  },
+  {
+    mieter: "Tobias Treuhand",
+    einheit: "WE-32",
+    liegenschaft: "Haus Ulmenpark",
+    beginn: "2026-09-01",
+    miete: 690,
+  },
+  {
+    mieter: "Max Nachmieter",
+    einheit: "WE-12",
+    liegenschaft: "Haus Ahornweg",
+    beginn: "2026-09-01",
+    miete: 850,
+  },
+  {
+    mieter: "Petra Pfand",
+    einheit: "WE-31",
+    liegenschaft: "Haus Pappelhof",
+    beginn: "2026-09-01",
+    miete: 640,
+  },
+  {
+    mieter: "Sina Kautionsfall",
+    einheit: "WE-41",
+    liegenschaft: "Haus Kautionsweg",
+    beginn: "2026-09-01",
+    miete: 610,
+  },
+  {
+    mieter: "Erika Musterfrau",
+    einheit: "WE-11",
+    liegenschaft: "Haus Lindenstraße",
+    beginn: "2026-09-01",
+    miete: 780,
+  },
+  {
+    mieter: "Thomas Bergmann",
+    einheit: "WE-05",
+    liegenschaft: "Haus Kastanienallee (Vertrag)",
+    beginn: "2026-09-01",
+    miete: 705,
+  },
+  {
+    mieter: "Sabine Hoffmann",
+    einheit: "WE-21",
+    liegenschaft: "Nordring 14",
+    beginn: "2026-06-01",
+    miete: 815,
+  },
+  {
+    mieter: "Meier Handels GmbH",
+    einheit: "Stellplatz 15, Stellplatz 16, Stellplatz 14, EG, Stellplatz 13, Stellplatz 12",
+    liegenschaft: "Hauptstraße, Köln",
+    beginn: "2026-03-01",
+    miete: 1450,
+  },
+  {
+    mieter: "Meier Handels GmbH",
+    einheit: "Stellplatz 16, Stellplatz 13, Stellplatz 15, Stellplatz 14, EG, Stellplatz 12",
+    liegenschaft: "Hauptstraße, Köln",
+    beginn: "2026-03-01",
+    miete: 1450,
+  },
+  {
+    mieter: "Nora Mietanpassung",
+    einheit: "WE-51",
+    liegenschaft: "Haus Kastanienallee",
+    beginn: "2026-01-01",
+    miete: 665,
+  },
+  {
+    mieter: "Otto Ausgezogen2",
+    einheit: "WE-42",
+    liegenschaft: "Haus Ulmenhof",
+    beginn: "2026-01-01",
+    ende: "2026-08-31",
+    miete: 700,
+  },
+  {
+    mieter: "Karl Positionsende",
+    einheit: "WE-51",
+    liegenschaft: "Haus Kastanienweg",
+    beginn: "2026-01-01",
+    miete: 655,
+  },
+  {
+    mieter: "Uwe Auszieher",
+    einheit: "WE-61",
+    liegenschaft: "Haus Erlenweg",
+    beginn: "2026-01-01",
+    miete: 630,
+  },
+  {
+    mieter: "Otto Zweitposition",
+    einheit: "WE-52",
+    liegenschaft: "Haus Fliederweg",
+    beginn: "2026-01-01",
+    miete: 670,
+  },
+  {
+    mieter: "Rita Ausgelaufen",
+    einheit: "WE-52",
+    liegenschaft: "Haus Fliederweg",
+    beginn: "2026-01-01",
+    miete: 660,
+  },
+  {
+    mieter: "Otto Ausgezogen",
+    einheit: "WE-32",
+    liegenschaft: "Haus Lindenhof",
+    beginn: "2026-01-01",
+    ende: "2026-08-31",
+    miete: 645,
+  },
+  {
+    mieter: "Nora Zusatzpartei",
+    einheit: "WE-41",
+    liegenschaft: "Haus Birkenweg",
+    beginn: "2026-01-01",
+    miete: 620,
+  },
+  {
+    mieter: "Nora Zusatzposten",
+    einheit: "WE-31",
+    liegenschaft: "Haus Ahornweg",
+    beginn: "2026-01-01",
+    miete: 635,
+  },
+  {
+    mieter: "Lena Langlabel",
+    einheit: "Haus Kautionsweg — WE-41 · 01.09.2026",
+    liegenschaft: "Haus Kautionsweg",
+    beginn: "2024-01-01",
+    miete: 610,
+  },
+];
+
+const MAX_NACHMIETER_INDEX = 2;
+const GENERATED_LEASE_COUNT = 300;
+const FIRST_NAMES = [
+  "Anna",
+  "Ben",
+  "Clara",
+  "David",
+  "Elif",
+  "Felix",
+  "Greta",
+  "Hannes",
+  "Ida",
+  "Jonas",
+];
+const LAST_NAMES = [
+  "Albrecht",
+  "Brandt",
+  "Conrad",
+  "Dietrich",
+  "Engel",
+  "Fischer",
+  "Graf",
+  "Hartmann",
+];
+const PROPERTIES = ["Haus Eichenweg", "Haus Buchenring", "Haus Tannenhof", "Haus Weidenpfad"];
+
+function boardLeaseId(index: number): string {
+  return `00000000-0000-4000-8000-${String(3100 + index + 1).padStart(12, "0")}`;
+}
+
+function eur(amount: number) {
+  return { amount, currency: "EUR" } as const;
+}
+
+function generatedLease(index: number): BoardLease & { readonly terminated: boolean } {
+  const month = String((index % 12) + 1).padStart(2, "0");
+  const year = 2025 - Math.floor(index / 150);
+  const terminated = index === 0;
+  return {
+    mieter: `${FIRST_NAMES[index % FIRST_NAMES.length]} ${LAST_NAMES[index % LAST_NAMES.length]}`,
+    einheit: `WE-${String(100 + index)}`,
+    liegenschaft: PROPERTIES[index % PROPERTIES.length] ?? "Haus Eichenweg",
+    beginn: `${year}-${month}-01`,
+    ...(terminated && { ende: "2025-12-31" }),
+    miete: 500 + (index % 20) * 15,
+    terminated,
+  };
+}
+
+export const seedRental: SeedFn = async (stack) => {
+  const { tenantId } = TestUsers.admin;
+  if ((await countRowsForTenant(stack.db, "read_ui_walkthrough_leases", tenantId)) > 0) return;
+  const db = createTenantDb(stack.db, tenantId);
+
+  const createLease = async (lease: BoardLease, terminated: boolean, id?: string) => {
+    const result = await leaseExecutor.create(
+      {
+        ...(id && { id }),
+        mieter: lease.mieter,
+        einheit: lease.einheit,
+        liegenschaft: lease.liegenschaft,
+        beginn: lease.beginn,
+        ...(lease.ende && { ende: lease.ende }),
+        status: terminated ? "terminated" : "active",
+        grundmiete: eur(lease.miete),
+        kuendigungsfrist: "3 Monate",
+        zahltag: 3,
+      },
+      TestUsers.admin,
+      db,
+    );
+    if (!result.isSuccess) throw new Error(`seed lease "${lease.mieter}" failed`);
+  };
+
+  for (const [index, lease] of BOARD_LEASES.entries()) {
+    await createLease(lease, lease.ende !== undefined, boardLeaseId(index));
+  }
+  for (let index = 0; index < GENERATED_LEASE_COUNT; index++) {
+    const lease = generatedLease(index);
+    await createLease(lease, lease.terminated);
+  }
+
+  const maxId = boardLeaseId(MAX_NACHMIETER_INDEX);
+  for (const party of [
+    { name: "Max Nachmieter", rolle: "Hauptmieter" },
+    { name: "Marie Nachmieter", rolle: "Mitmieterin" },
+  ]) {
+    const result = await partyExecutor.create({ lease: maxId, ...party }, TestUsers.admin, db);
+    if (!result.isSuccess) throw new Error(`seed party "${party.name}" failed`);
+  }
+  const position = await positionExecutor.create(
+    {
+      lease: maxId,
+      art: "Grundmiete",
+      einheit: "WE-12",
+      betrag: eur(850),
+      gueltigVon: "2026-09-01",
+    },
+    TestUsers.admin,
+    db,
+  );
+  if (!position.isSuccess) throw new Error("seed position failed");
+};