@cosmicdrift/kumiko-renderer-web 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.35.0",
-    "@cosmicdrift/kumiko-headless": "0.35.0",
-    "@cosmicdrift/kumiko-renderer": "0.35.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.38.0",
+    "@cosmicdrift/kumiko-headless": "0.38.0",
+    "@cosmicdrift/kumiko-renderer": "0.38.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/__tests__/config-edit.test.tsx

@@ -166,4 +166,63 @@ describe("KumikoScreen / configEdit", () => {
     // dieser State stale (regression-guard).
     await waitFor(() => expect(submit.disabled).toBe(true));
   });
+
+  // Regression Bug-Bash-2 (2026-06-08): RenderEdit reichte denselben
+  // Appendix-Callback als labelAppendix UND fieldAppendix durch —
+  // Badge + Vorgabe-Disclosure erschienen doppelt (vor und nach dem
+  // Input) auf jedem Settings-Screen mit Default-Werten.
+  test("Source-Badge und Vorgabe-Disclosure erscheinen genau einmal pro Feld", async () => {
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async (qn: string) => {
+        if (qn === "config:query:cascade") {
+          return {
+            isSuccess: true,
+            data: {
+              "demo:config:site-name": {
+                value: "Acme",
+                source: "tenant-row",
+                levels: [
+                  {
+                    source: "tenant-row",
+                    label: "tenant-row",
+                    value: "Acme",
+                    isActive: true,
+                    hasValue: true,
+                  },
+                  {
+                    source: "default",
+                    label: "default",
+                    value: "fallback",
+                    isActive: false,
+                    hasValue: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        return {
+          isSuccess: true,
+          data: {
+            "demo:config:site-name": { value: "Acme", scope: "tenant", source: "tenant-row" },
+          },
+        };
+      }) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="demo:screen:settings" />
+      </DispatcherProvider>,
+    );
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const field = screen.getByTestId("field-siteName");
+    await waitFor(() =>
+      expect(field.querySelectorAll('[data-testid="config-cascade"]')).toHaveLength(1),
+    );
+    expect(field.querySelectorAll('[data-testid="config-source-badge"]')).toHaveLength(1);
+    // Badge inline am Label, Disclosure unter dem Input — nicht umgekehrt.
+    const label = field.querySelector("label");
+    expect(label?.querySelector('[data-testid="config-source-badge"]')).toBeTruthy();
+    expect(label?.querySelector('[data-testid="config-cascade"]')).toBeNull();
+  });
 });

package/src/__tests__/field-validation-i18n.test.tsx

@@ -0,0 +1,69 @@
+// Regression Bug-Bash-2 (2026-06-08): Validierungsfehler zeigten ROHE
+// Keys ("errors.validation.invalid_format") — der Namespace den Server
+// (ValidationError) und Client (zod-bridge) erzeugen war in keinem
+// Default-Bundle definiert, und DefaultField reichte issue.params nicht
+// an t() durch (Platzhalter wie {minimum} blieben uninterpoliert).
+import { describe, expect, test } from "bun:test";
+import type { FieldIssue } from "@cosmicdrift/kumiko-headless";
+import { defaultPrimitives } from "../primitives";
+import { render } from "./test-utils";
+
+function renderFieldWithIssues(issues: readonly FieldIssue[]) {
+  const { Field } = defaultPrimitives;
+  return render(
+    <Field id="f" label="Feld" issues={issues} testId="field-under-test">
+      <input id="f" />
+    </Field>,
+  );
+}
+
+describe("DefaultField / errors.validation.* i18n", () => {
+  test("invalid_format zeigt übersetzten Text statt rohem Key", () => {
+    const view = renderFieldWithIssues([
+      { path: "startsAt", code: "invalid_format", i18nKey: "errors.validation.invalid_format" },
+    ]);
+    expect(view.container.textContent).not.toContain("errors.validation");
+    expect(view.container.textContent).toContain("Invalid format.");
+  });
+
+  test("too_small interpoliert {minimum} aus issue.params", () => {
+    const view = renderFieldWithIssues([
+      {
+        path: "name",
+        code: "too_small",
+        i18nKey: "errors.validation.too_small",
+        params: { minimum: 3 },
+      },
+    ]);
+    expect(view.container.textContent).not.toContain("errors.validation");
+    expect(view.container.textContent).not.toContain("{minimum}");
+    expect(view.container.textContent).toContain("minimum: 3");
+  });
+
+  test("alle Server-/Zod-Codes sind in beiden Default-Bundles übersetzt", async () => {
+    const { kumikoDefaultTranslations } = await import("@cosmicdrift/kumiko-renderer");
+    const codes = [
+      "invalid_type",
+      "too_small",
+      "too_big",
+      "invalid_format",
+      "not_multiple_of",
+      "unrecognized_keys",
+      "invalid_union",
+      "invalid_key",
+      "invalid_element",
+      "invalid_value",
+      "custom",
+      "unexpected_field",
+      "out_of_bounds",
+      "invalid_option",
+      "failed",
+    ];
+    for (const locale of ["de", "en"] as const) {
+      const bundle = kumikoDefaultTranslations[locale];
+      for (const code of codes) {
+        expect(bundle?.[`errors.validation.${code}`]).toBeString();
+      }
+    }
+  });
+});

package/src/__tests__/form-action-bar.test.tsx

@@ -0,0 +1,94 @@
+// F2.4 (Bug-Bash-2): Die Sticky-Action-Bar spannte die volle Breite,
+// während der Form-Body auf max-w-2xl begrenzt ist — die Buttons
+// klebten am Fensterrand, optisch abgekoppelt vom Formular. Außerdem
+// wiederholte der Section-Header bei Single-Section-ActionForms den
+// Screen-Titel 1:1. Strukturelle Assertions (Klassen/DOM) — der
+// visuelle Beweis läuft über die publicstatus-Screens nach dem Bump.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { DispatcherProvider, RenderEdit } from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "../primitives";
+import { createMockDispatcher, render, screen } from "./test-utils";
+
+const { Form, Section, Button } = defaultPrimitives;
+
+describe("DefaultForm Action-Bar", () => {
+  test("Bar-Inhalt aligned mit dem Form-Body (max-w-Container in der Bar)", () => {
+    render(
+      <Form onSubmit={() => {}} title="Titel" actions={<Button>Save</Button>} testId="f">
+        <div>body</div>
+      </Form>,
+    );
+    const bar = screen.getByTestId("f-actions");
+    const inner = bar.firstElementChild;
+    expect(inner).toBeTruthy();
+    // Gleiche Breiten-Constraint wie der Body (max-w-2xl + px-6) — die
+    // Buttons enden damit an derselben Linie wie die Formularfelder.
+    expect(inner?.className).toContain("max-w-2xl");
+    expect(inner?.className).toContain("px-6");
+  });
+});
+
+describe("DefaultSection ohne Titel", () => {
+  test("rendert keinen leeren Header", () => {
+    render(
+      <Section testId="s">
+        <div>content</div>
+      </Section>,
+    );
+    expect(screen.getByTestId("s").querySelector("h3")).toBeNull();
+  });
+});
+
+const orderEntity = {
+  fields: { title: { type: "text", required: true } },
+} as unknown as EntityDefinition; // @cast-boundary test-fixture
+
+function makeScreen(sectionTitle: string): EntityEditScreenDefinition {
+  return {
+    id: "orders:screen:order-edit",
+    type: "entityEdit",
+    entity: "order",
+    layout: { sections: [{ title: sectionTitle, columns: 1, fields: ["title"] }] },
+  };
+}
+
+describe("RenderEdit Section-Titel-Dopplung", () => {
+  test("Section-Titel == Form-Titel → Header unterdrückt", () => {
+    // Ohne translate-Bundle fällt der Form-Titel auf screen.id zurück —
+    // ein gleichlautender Section-Titel reproduziert die Dopplung.
+    render(
+      <DispatcherProvider dispatcher={createMockDispatcher()}>
+        <RenderEdit
+          screen={makeScreen("orders:screen:order-edit")}
+          entity={orderEntity}
+          featureName="orders"
+          initial={{ title: "" }}
+          writeCommand="order:create"
+        />
+      </DispatcherProvider>,
+    );
+    const section = screen.getByTestId("section-orders:screen:order-edit");
+    expect(section.querySelector("h3")).toBeNull();
+  });
+
+  test("abweichender Section-Titel bleibt sichtbar", () => {
+    render(
+      <DispatcherProvider dispatcher={createMockDispatcher()}>
+        <RenderEdit
+          screen={makeScreen("Basics")}
+          entity={orderEntity}
+          featureName="orders"
+          initial={{ title: "" }}
+          writeCommand="order:create"
+        />
+      </DispatcherProvider>,
+    );
+    const section = screen.getByTestId("section-Basics");
+    expect(section.querySelector("h3")?.textContent).toBe("Basics");
+  });
+});

package/src/__tests__/timestamp-input.test.tsx

@@ -0,0 +1,95 @@
+// Regression Bug-Bash-2 (2026-06-08): timestamp-Felder ohne locatedBy
+// werden server-seitig als z.iso.datetime() (UTC mit `Z`) validiert,
+// das native datetime-local-Input emittierte aber offset-lose lokale
+// Zeit ("2026-06-08T21:09") → jeder Save endete in 422 invalid_format.
+// Die Assertions laufen gegen die ECHTEN Zod-Schemas aus
+// schema-builder.ts (z.iso.datetime / z.iso.datetime({local:true})).
+import { describe, expect, test } from "bun:test";
+import { fireEvent } from "@testing-library/react";
+import { z } from "zod";
+import { defaultPrimitives } from "../primitives";
+import { inputValueToTimestamp, timestampToInputValue } from "../primitives/timestamp-input";
+import { render } from "./test-utils";
+
+const utcSchema = z.iso.datetime();
+const wallClockSchema = z.iso.datetime({ local: true });
+const DATETIME_LOCAL = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+
+describe("timestamp Konvertierung (Helpers)", () => {
+  test("UTC: lokale Eingabe wird als Z-Instant emittiert, Instant bleibt erhalten", () => {
+    const emitted = inputValueToTimestamp("2026-06-08T21:09", false);
+    if (emitted === undefined) throw new Error("expected emitted value");
+    expect(utcSchema.safeParse(emitted).success).toBe(true);
+    expect(emitted.endsWith("Z")).toBe(true);
+    expect(new Date(emitted).getTime()).toBe(new Date("2026-06-08T21:09").getTime());
+  });
+
+  test("wallClock: Eingabe geht offset-los durch und passt das local-Schema", () => {
+    const emitted = inputValueToTimestamp("2026-06-08T21:09", true);
+    expect(emitted).toBe("2026-06-08T21:09");
+    expect(wallClockSchema.safeParse(emitted).success).toBe(true);
+  });
+
+  test("leere Eingabe → undefined (Feld geleert)", () => {
+    expect(inputValueToTimestamp("", false)).toBeUndefined();
+    expect(inputValueToTimestamp("", true)).toBeUndefined();
+  });
+
+  test("UTC-Instant aus dem Server wird als lokale Wall-Clock angezeigt", () => {
+    const display = timestampToInputValue("2026-06-08T19:09:00.000Z");
+    expect(display).toMatch(DATETIME_LOCAL);
+    expect(new Date(`${display}`).getTime()).toBe(new Date("2026-06-08T19:09:00.000Z").getTime());
+  });
+
+  test("offset-loser Wert wird nur auf Minuten gekürzt", () => {
+    expect(timestampToInputValue("2026-06-08T21:09:33")).toBe("2026-06-08T21:09");
+    expect(timestampToInputValue("")).toBe("");
+  });
+});
+
+describe("Input kind=timestamp (Primitive)", () => {
+  test("rendert UTC-Wert als valides datetime-local und emittiert Z-Instant", () => {
+    const { Input } = defaultPrimitives;
+    const emitted: (string | undefined)[] = [];
+    const view = render(
+      <Input
+        kind="timestamp"
+        id="ts"
+        name="ts"
+        value="2026-06-08T19:09:00Z"
+        onChange={(v) => emitted.push(v)}
+      />,
+    );
+    const input = view.container.querySelector("input");
+    if (!input) throw new Error("expected input");
+    // datetime-local akzeptiert keine Z-Suffixe — der angezeigte Wert
+    // muss konvertiert sein, sonst zeigt der Browser ein leeres Feld.
+    expect(input.value).toMatch(DATETIME_LOCAL);
+
+    fireEvent.change(input, { target: { value: "2026-06-08T21:09" } });
+    expect(emitted).toHaveLength(1);
+    const value = emitted[0];
+    if (value === undefined) throw new Error("expected emitted value");
+    expect(utcSchema.safeParse(value).success).toBe(true);
+  });
+
+  test("wallClock-Variante emittiert offset-lose Wall-Clock", () => {
+    const { Input } = defaultPrimitives;
+    const emitted: (string | undefined)[] = [];
+    const view = render(
+      <Input
+        kind="timestamp"
+        id="ts"
+        name="ts"
+        value=""
+        wallClock
+        onChange={(v) => emitted.push(v)}
+      />,
+    );
+    const input = view.container.querySelector("input");
+    if (!input) throw new Error("expected input");
+    fireEvent.change(input, { target: { value: "2026-06-08T10:00" } });
+    expect(emitted).toEqual(["2026-06-08T10:00"]);
+    expect(wallClockSchema.safeParse(emitted[0]).success).toBe(true);
+  });
+});

package/src/components/config-cascade.tsx

@@ -137,7 +137,7 @@ export function ConfigCascadeView({
   const hasOverride = activeDisplay?.level.source === screenScopeSource;
 
   return (
-    <div className="mt-1 text-xs">
+    <div className="mt-1 text-xs" data-testid="config-cascade">
       <button
         type="button"
         onClick={() => setExpanded(!expanded)}

package/src/components/config-source-badge.tsx

@@ -18,6 +18,7 @@ export function ConfigSourceBadge({ source }: { readonly source: ConfigValueSour
 
   return (
     <span
+      data-testid="config-source-badge"
       style={{
         display: "inline-flex",
         alignItems: "center",

package/src/layout/__tests__/workspace-switcher.test.tsx

@@ -5,7 +5,11 @@
 // Nutzt useTranslation → über test-utils mit LocaleProvider gerendert.
 
 import { describe, expect, mock, test } from "bun:test";
-import type { WorkspaceSchema } from "@cosmicdrift/kumiko-renderer";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  type WorkspaceSchema,
+} from "@cosmicdrift/kumiko-renderer";
 import { fireEvent, render, screen } from "../../__tests__/test-utils";
 import { WorkspaceSwitcher } from "../workspace-switcher";
 
@@ -48,3 +52,24 @@ describe("WorkspaceSwitcher — Render", () => {
     expect(onSelect).toHaveBeenCalledWith("b");
   });
 });
+
+describe("WorkspaceSwitcher — i18n-Labels (Punkt-Konvention)", () => {
+  test("Label mit Punkt geht durch t() und rendert die Übersetzung", () => {
+    const bundle = { en: { "nav.adminArea": "Admin Area" } };
+    const { getByTestId } = render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en" })}
+        fallbackBundles={[bundle]}
+      >
+        <WorkspaceSwitcher
+          workspaces={[ws("a", "nav.adminArea"), ws("b", "Plain Label")]}
+          activeId="a"
+          onSelect={mock()}
+        />
+      </LocaleProvider>,
+    );
+    expect(getByTestId("workspace-tab-a").textContent).toBe("Admin Area");
+    // ohne Punkt: verbatim, kein t()-Roundtrip
+    expect(getByTestId("workspace-tab-b").textContent).toBe("Plain Label");
+  });
+});

package/src/layout/avatar.tsx

@@ -61,7 +61,7 @@ function pickColor(id: string): string {
 }
 
 function extractInitials(label: string): string {
-  // "Daniel Hennig" → "DH". "alice@example.com" → "A". Single-word
+  // "Daniel Hennig" → "DH". "alice@example.com" → "AL". Single-word
   // fällt auf erste 2 Buchstaben zurück ("Daniel" → "DA"). Alles
   // upper-case.
   const trimmed = label.trim();

package/src/primitives/__tests__/data-table-logic.test.ts

@@ -38,6 +38,24 @@ describe("computeVisiblePages", () => {
   test("page=5/20: Übergang Rand→Mitte (Ellipsis links erscheint)", () => {
     expect(computeVisiblePages(5, 20)).toEqual([1, "ellipsis", 3, 4, 5, 6, 7, "ellipsis", 20]);
   });
+
+  test("page=16/20: letzte Mitte-Position (Ellipsis rechts noch da)", () => {
+    expect(computeVisiblePages(16, 20)).toEqual([
+      1,
+      "ellipsis",
+      14,
+      15,
+      16,
+      17,
+      18,
+      "ellipsis",
+      20,
+    ]);
+  });
+
+  test("page=17/20: Übergang Mitte→Rand (Ellipsis rechts verschwindet, 5er-Tail)", () => {
+    expect(computeVisiblePages(17, 20)).toEqual([1, "ellipsis", 16, 17, 18, 19, 20]);
+  });
 });
 
 describe("isComponentRendererRef", () => {
@@ -61,10 +79,10 @@ describe("isComponentRendererRef", () => {
 });
 
 describe("applyFormatSpec", () => {
-  test("null/undefined/leer → leerer String (alle Formate)", () => {
+  test("null/undefined/leer → leerer String (priority rendert stattdessen emptyLabel)", () => {
     expect(applyFormatSpec({ format: "boolean" }, null)).toBe("");
     expect(applyFormatSpec({ format: "currency", symbol: "€" }, undefined)).toBe("");
-    expect(applyFormatSpec({ format: "priority" }, "")).toBe("");
+    expect(applyFormatSpec({ format: "priority" }, "")).toBe("—");
   });
 
   test("boolean: true → ✓, false → leer (defaults)", () => {
@@ -101,12 +119,20 @@ describe("applyFormatSpec", () => {
   });
 
   test("unbekanntes format → String(value) fallback + dev-warning", () => {
+    // Warnung feuert nur bei NODE_ENV !== "production" — explizit setzen
+    // statt sich aufs Test-Runner-Preset zu verlassen.
+    const prevNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
     const warn = spyOn(console, "warn").mockImplementation(() => {});
-    expect(applyFormatSpec({ format: "custom-app-format" }, 42)).toBe("42");
-    expect(applyFormatSpec({ format: "custom-app-format" }, "hello")).toBe("hello");
-    expect(warn).toHaveBeenCalledTimes(2);
-    expect(warn.mock.calls[0]?.[0]).toContain("custom-app-format");
-    warn.mockRestore();
+    try {
+      expect(applyFormatSpec({ format: "custom-app-format" }, 42)).toBe("42");
+      expect(applyFormatSpec({ format: "custom-app-format" }, "hello")).toBe("hello");
+      expect(warn).toHaveBeenCalledTimes(2);
+      expect(warn.mock.calls[0]?.[0]).toContain("custom-app-format");
+    } finally {
+      warn.mockRestore();
+      process.env.NODE_ENV = prevNodeEnv;
+    }
   });
 });
 

package/src/primitives/index.tsx

@@ -55,6 +55,7 @@ import {
   DropdownMenuTrigger,
 } from "./dropdown-menu";
 import { MoneyInput } from "./money-input";
+import { TimestampInput } from "./timestamp-input";
 import { useToast } from "./toast";
 
 // ---- Button ----
@@ -172,7 +173,7 @@ function DefaultField({
           className="text-xs text-destructive"
         >
           {issues.map((issue) => (
-            <div key={`${issue.path}:${issue.code}`}>{t(issue.i18nKey)}</div>
+            <div key={`${issue.path}:${issue.code}`}>{t(issue.i18nKey, issue.params)}</div>
           ))}
         </div>
       )}
@@ -340,13 +341,15 @@ function DefaultInput(props: InputProps): ReactNode {
       );
     case "timestamp":
       return (
-        <input
-          type="datetime-local"
-          {...common}
+        <TimestampInput
+          id={props.id}
+          name={props.name}
           value={props.value}
-          onChange={(e: ChangeEvent<HTMLInputElement>) =>
-            props.onChange(e.target.value !== "" ? e.target.value : undefined)
-          }
+          onChange={props.onChange}
+          {...(props.wallClock !== undefined && { wallClock: props.wallClock })}
+          {...(props.disabled !== undefined && { disabled: props.disabled })}
+          {...(props.required !== undefined && { required: props.required })}
+          {...(props.hasError !== undefined && { hasError: props.hasError })}
           className={cn(inputClassBase, errorClass)}
         />
       );
@@ -1176,14 +1179,19 @@ function DefaultForm({ onSubmit, children, title, actions, testId }: FormProps):
       {(title !== undefined || actions !== undefined) && (
         <div
           data-testid={testId !== undefined ? `${testId}-actions` : undefined}
-          className="sticky top-0 z-10 h-12 px-6 bg-muted/30 border-b flex items-center gap-3"
+          className="sticky top-0 z-10 h-12 bg-muted/30 border-b"
         >
-          {title !== undefined && (
-            <div className="text-lg font-semibold tracking-tight truncate">{title}</div>
-          )}
-          {actions !== undefined && (
-            <div className="flex items-center gap-2 ml-auto">{actions}</div>
-          )}
+          {/* Bar-Hintergrund spannt die volle Breite, der Inhalt aligned
+              aber mit dem max-w-2xl-Form-Body — sonst kleben die Buttons
+              am Fensterrand, optisch abgekoppelt vom Formular. */}
+          <div className="h-full px-6 max-w-2xl w-full flex items-center gap-3">
+            {title !== undefined && (
+              <div className="text-lg font-semibold tracking-tight truncate">{title}</div>
+            )}
+            {actions !== undefined && (
+              <div className="flex items-center gap-2 ml-auto">{actions}</div>
+            )}
+          </div>
         </div>
       )}
       <div className="px-6 pt-6 pb-12 max-w-2xl w-full flex flex-col gap-8">{children}</div>
@@ -1198,9 +1206,11 @@ function DefaultSection({ title, children, testId }: SectionProps): ReactNode {
   // aus Border + Shadow. Spart Chrome und sieht weniger "boxy" aus.
   return (
     <section data-testid={testId} className="flex flex-col gap-4">
-      <h3 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-        {title}
-      </h3>
+      {title !== undefined && (
+        <h3 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+          {title}
+        </h3>
+      )}
       <div className="flex flex-col gap-4">{children}</div>
     </section>
   );

package/src/primitives/timestamp-input.tsx

@@ -0,0 +1,88 @@
+// TimestampInput — natives <input type="datetime-local"> mit
+// Wert-Konvertierung. Der Server validiert timestamp-Felder als
+// ISO-UTC mit `Z` (z.iso.datetime()) bzw. als Wall-Clock ohne Offset
+// bei locatedTimestamps (z.iso.datetime({ local: true })). Das native
+// datetime-local-Input spricht aber IMMER lokale Wall-Clock ohne
+// Offset — ohne Konvertierung ging jeder UTC-Timestamp als
+// offset-loser String raus und der Server lehnte mit invalid_format
+// ab (Bug-Bash-2, 2026-06-08).
+
+import type { ChangeEvent, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+const LOCAL_MINUTES = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+const HAS_OFFSET = /(?:Z|[+-]\d{2}:\d{2})$/;
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Form-State → datetime-local-Format (`yyyy-MM-ddTHH:mm`).
+ *  UTC-Instants (mit `Z`/Offset) werden in lokale Wall-Clock
+ *  umgerechnet; offset-lose Werte nur auf Minuten gekürzt. */
+export function timestampToInputValue(value: string): string {
+  if (value === "") return "";
+  if (HAS_OFFSET.test(value)) {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return "";
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  }
+  const m = LOCAL_MINUTES.exec(value);
+  return m !== null ? m[0] : "";
+}
+
+/** datetime-local-Wert → Wire-Format. wallClock=true reicht die
+ *  Wall-Clock unverändert durch; sonst wird die lokale Zeit als
+ *  UTC-Instant mit `Z`-Suffix emittiert. */
+export function inputValueToTimestamp(raw: string, wallClock: boolean): string | undefined {
+  if (raw === "") return undefined;
+  if (wallClock) return raw;
+  // Offset-loser Datetime-String wird von Date als LOKALE Zeit geparst
+  // (ES2020+) — genau die Semantik die datetime-local liefert.
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return undefined;
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}Z`;
+}
+
+export type TimestampInputProps = {
+  readonly id: string;
+  readonly name: string;
+  readonly value: string;
+  readonly onChange: (v: string | undefined) => void;
+  readonly wallClock?: boolean;
+  readonly disabled?: boolean;
+  readonly required?: boolean;
+  readonly hasError?: boolean;
+  readonly className?: string;
+};
+
+export function TimestampInput({
+  id,
+  name,
+  value,
+  onChange,
+  wallClock,
+  disabled,
+  required,
+  hasError,
+  className,
+}: TimestampInputProps): ReactNode {
+  return (
+    <input
+      type="datetime-local"
+      id={id}
+      name={name}
+      disabled={disabled}
+      required={required}
+      aria-invalid={hasError === true ? true : undefined}
+      value={timestampToInputValue(value)}
+      onChange={(e: ChangeEvent<HTMLInputElement>) =>
+        onChange(inputValueToTimestamp(e.target.value, wallClock === true))
+      }
+      // Das `flex` der Input-Basisklasse macht die Shadow-DOM-Teile des
+      // datetime-local zu Flex-Items — der Picker-Indicator klebt dann
+      // direkt am Text statt am rechten Rand. ml-auto schiebt ihn zurück.
+      className={cn("[&::-webkit-calendar-picker-indicator]:ml-auto", className)}
+    />
+  );
+}