@cosmicdrift/kumiko-renderer 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.37.0",
-    "@cosmicdrift/kumiko-headless": "0.37.0",
+    "@cosmicdrift/kumiko-framework": "0.38.0",
+    "@cosmicdrift/kumiko-headless": "0.38.0",
     "react": "^19.2.6"
   },
   "devDependencies": {

package/src/app/kumiko-screen.tsx

@@ -5,13 +5,13 @@ import type {
   EntityDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
-  FieldCondition,
   RowAction,
   RowActionWriteHandler,
   RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
 } from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   Command,
   FormSnapshot,
@@ -46,13 +46,6 @@ function evalRowExtractor(
   return Object.fromEntries(Object.entries(extractor.map).map(([to, from]) => [to, row[from]]));
 }
 
-function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean {
-  if (typeof cond === "boolean") return cond;
-  const val = values[cond.field];
-  if ("eq" in cond) return val === cond.eq;
-  return val !== cond.ne;
-}
-
 // KumikoScreen picks up a ScreenDefinition from the schema by qn and
 // routes it to the right renderer based on `screen.type`. Command
 // qualification (`<feature>:write:<entity>:create` etc.) happens here
@@ -695,9 +688,16 @@ function EntityListBody({
         // immer da (Provider von createKumikoApp).
         if (action.kind === "navigate") {
           // Default entityId für entityEdit-Targets: row["id"] wenn
-          // kein expliziter entityId-Feldname gesetzt ist.
+          // kein expliziter entityId-Feldname gesetzt ist. Nur für Targets
+          // DERSELBEN Entity — ein Cross-Entity-Edit-Screen bekäme sonst die
+          // falsche row.id injiziert, und "Duplicate → Create"-Patterns
+          // würden in den Update-Mode gezwungen. Cross-Entity-Navigation
+          // setzt action.entityId explizit.
           const targetIsEntityEdit = schema.screens.some(
-            (s) => s.type === "entityEdit" && lastSegment(s.id) === action.screen,
+            (s) =>
+              s.type === "entityEdit" &&
+              s.entity === screen.entity &&
+              lastSegment(s.id) === action.screen,
           );
           const actionVisible = action.visible;
           return {
@@ -731,6 +731,11 @@ function EntityListBody({
                 // NACH navigate: pushState trägt keine Query — Params die
                 // vor dem Push gesetzt werden, kleben an der ALTEN URL und
                 // sind auf dem Ziel-Screen weg (actionForm-Prefill leer).
+                // Bekannte Kante (bewusst offen): zielt die Action auf den
+                // AKTUELLEN pathname, short-circuit't pushPath ohne die Query
+                // zu leeren — die neuen Params mergen dann auf den alten
+                // ?-String. Für Row-Actions praktisch nicht erreichbar
+                // (Pfad differiert über entityId/screen).
                 nav.setSearchParams(stringified);
               }
             },
@@ -777,7 +782,7 @@ function EntityListBody({
         };
       })
       .filter((a: DataTableRowAction | null): a is DataTableRowAction => a !== null);
-  }, [screen.rowActions, effectiveTranslate, dispatcher, nav, schema.screens]);
+  }, [screen.rowActions, screen.entity, effectiveTranslate, dispatcher, nav, schema.screens]);
 
   // ToolbarActions: Schema → Resolved-Form (analog rowActions).
   // navigate-kind → useNav().navigate({ screenId }), writeHandler-kind
@@ -1055,7 +1060,7 @@ function ConfigEditBody({
   }, [valuesQuery.data, screen.fields, screen.configKeys]);
 
   // Sources-Lookup: qualifiedKey → ConfigValueSource für das
-  // ConfigSourceBadge. Wird via fieldAppendix an RenderEdit
+  // ConfigSourceBadge. Wird via labelAppendix an RenderEdit
   // durchgereicht.
   const sources = useMemo<Record<string, ConfigValueSource>>(() => {
     if (valuesQuery.data === null) return {};
@@ -1145,25 +1150,26 @@ function ConfigEditBody({
       customSubmit={customSubmit}
       {...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel })}
       {...(translate !== undefined && { translate })}
-      fieldAppendix={(fieldName: string) => {
+      labelAppendix={(fieldName: string) => {
         const source = sources[fieldName];
+        return source ? (
+          <ConfigSourceBadge source={source} screenScope={screen.scope} />
+        ) : undefined;
+      }}
+      fieldAppendix={(fieldName: string) => {
         const cascade = cascades[fieldName];
+        if (cascade === undefined) return undefined;
         return (
-          <>
-            {source ? <ConfigSourceBadge source={source} /> : null}
-            {cascade !== undefined ? (
-              <ConfigCascadeView
-                cascade={cascade}
-                screenScope={screen.scope}
-                qualifiedKey={screen.configKeys[fieldName]}
-                onReset={async (key, scope) => {
-                  await dispatcher.write("config:write:reset", { key, scope });
-                  await valuesQuery.refetch?.();
-                  await cascadeQuery.refetch?.();
-                }}
-              />
-            ) : null}
-          </>
+          <ConfigCascadeView
+            cascade={cascade}
+            screenScope={screen.scope}
+            qualifiedKey={screen.configKeys[fieldName]}
+            onReset={async (key, scope) => {
+              await dispatcher.write("config:write:reset", { key, scope });
+              await valuesQuery.refetch?.();
+              await cascadeQuery.refetch?.();
+            }}
+          />
         );
       }}
     />

package/src/components/render-edit.tsx

@@ -3,7 +3,11 @@ import type {
   EntityEditScreenDefinition,
   FieldCondition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import { isExtensionEditSection, normalizeEditField } from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  evalFieldCondition,
+  isExtensionEditSection,
+  normalizeEditField,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   DispatcherError,
   EditExtensionSectionViewModel,
@@ -70,7 +74,11 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  damit "Speichern" durch domain-spezifischere Strings ersetzt
    *  werden kann ("Genehmigen" / "Versenden" / etc.). */
   readonly submitLabel?: string;
-  /** Pro-Field-Zusatz-Inhalt nach dem Label (z.B. ConfigSourceBadge).
+  /** Pro-Field-Zusatz-Inhalt inline nach dem Label (z.B. ConfigSourceBadge).
+   *  Wird mit dem Field-Namen aufgerufen, returnt ReactNode oder
+   *  undefined. */
+  readonly labelAppendix?: (fieldName: string) => ReactNode | undefined;
+  /** Pro-Field-Zusatz-Inhalt unter dem Input (z.B. ConfigCascadeView).
    *  Wird mit dem Field-Namen aufgerufen, returnt ReactNode oder
    *  undefined. */
   readonly fieldAppendix?: (fieldName: string) => ReactNode | undefined;
@@ -80,12 +88,8 @@ function toConditionValue<TValues extends FormValues, TCtx>(
   cond: FieldCondition,
 ): NonNullable<FieldConditions<TValues, TCtx>["visible"]> {
   if (typeof cond === "boolean") return cond;
-  if ("eq" in cond) {
-    const { field, eq } = cond;
-    return (values: TValues) => (values as Record<string, unknown>)[field] === eq;
-  }
-  const { field, ne } = cond;
-  return (values: TValues) => (values as Record<string, unknown>)[field] !== ne;
+  // @cast-boundary form-values: TValues ist strukturell ein Record.
+  return (values: TValues) => evalFieldCondition(cond, values as Record<string, unknown>);
 }
 
 function deriveFormFields<TValues extends FormValues, TCtx>(
@@ -175,6 +179,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     onCancel,
     onReload,
     submitLabel,
+    labelAppendix,
     fieldAppendix,
     entityId: entityIdProp,
     extensionInitialValues,
@@ -342,8 +347,16 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             />
           );
         }
+        // Section-Header unterdrücken wenn er den Form-Titel der
+        // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-
+        // ActionForms, deren Section-Label = Screen-Titel ist).
+        const sectionTitle = section.title === formTitle ? undefined : section.title;
         return (
-          <Section key={section.title} title={section.title} testId={`section-${section.title}`}>
+          <Section
+            key={section.title}
+            {...(sectionTitle !== undefined && { title: sectionTitle })}
+            testId={`section-${section.title}`}
+          >
             <Grid columns={section.columns}>
               {section.fields.map((field: EditFieldViewModel) => (
                 <GridCellForField
@@ -356,8 +369,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                   }}
                   GridCell={GridCell}
                   featureName={featureName}
+                  {...(labelAppendix !== undefined && {
+                    labelAppendix: labelAppendix(field.field),
+                  })}
                   {...(fieldAppendix !== undefined && {
-                    labelAppendix: fieldAppendix(field.field),
                     fieldAppendix: fieldAppendix(field.field),
                   })}
                 />

package/src/components/render-field.tsx

@@ -39,8 +39,9 @@ export function RenderField({
   const { Field, Input } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
   // navigator.language (Browser-Sprache) zurück statt der gewählten
-  // App-Sprache. useLocale() wirft ohne LocaleProvider; ok, weil
-  // RenderField nur unter RenderEdit im Kumiko-App-Tree läuft.
+  // App-Sprache. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
+  // public exportiert und verlangt jetzt einen LocaleProvider —
+  // Standalone-Consumer/Tests müssen wrappen (createKumikoApp tut es).
   const appLocale = useLocale().locale();
   if (!field.visible) return null;
 
@@ -261,6 +262,7 @@ function renderInput({
           {...common}
           value={stringValue(field.value)}
           onChange={(v) => onChange(v)}
+          {...(field.wallClock !== undefined && { wallClock: field.wallClock })}
         />
       );
     case "select": {

package/src/i18n-defaults.ts

@@ -71,6 +71,25 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.validation.too-short": "Zu kurz (mindestens {min} Zeichen).",
     "kumiko.validation.too-long": "Zu lang (höchstens {max} Zeichen).",
     "kumiko.validation.out-of-range": "Wert außerhalb des erlaubten Bereichs.",
+
+    // errors.validation.* — der kanonische Key-Namespace den Server
+    // (ValidationError) und Client (zod-bridge) für Field-Issues
+    // erzeugen. Codes = Zod-4-Issue-Codes + Framework-eigene.
+    "errors.validation.invalid_type": "Ungültiger Wert.",
+    "errors.validation.too_small": "Zu klein oder zu kurz (Minimum: {minimum}).",
+    "errors.validation.too_big": "Zu groß oder zu lang (Maximum: {maximum}).",
+    "errors.validation.invalid_format": "Ungültiges Format.",
+    "errors.validation.not_multiple_of": "Muss ein Vielfaches von {divisor} sein.",
+    "errors.validation.unrecognized_keys": "Unbekannte Felder.",
+    "errors.validation.invalid_union": "Ungültiger Wert.",
+    "errors.validation.invalid_key": "Ungültiger Schlüssel.",
+    "errors.validation.invalid_element": "Ungültiger Eintrag.",
+    "errors.validation.invalid_value": "Ungültige Auswahl.",
+    "errors.validation.custom": "Ungültiger Wert.",
+    "errors.validation.unexpected_field": "Unbekanntes Feld.",
+    "errors.validation.out_of_bounds": "Wert außerhalb des erlaubten Bereichs.",
+    "errors.validation.invalid_option": "Ungültige Auswahl.",
+    "errors.validation.failed": "Validierung fehlgeschlagen.",
   },
   en: {
     "kumiko.actions.save": "Save",
@@ -120,5 +139,21 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.validation.too-short": "Too short (at least {min} characters).",
     "kumiko.validation.too-long": "Too long (at most {max} characters).",
     "kumiko.validation.out-of-range": "Value out of allowed range.",
+
+    "errors.validation.invalid_type": "Invalid value.",
+    "errors.validation.too_small": "Too small or too short (minimum: {minimum}).",
+    "errors.validation.too_big": "Too big or too long (maximum: {maximum}).",
+    "errors.validation.invalid_format": "Invalid format.",
+    "errors.validation.not_multiple_of": "Must be a multiple of {divisor}.",
+    "errors.validation.unrecognized_keys": "Unknown fields.",
+    "errors.validation.invalid_union": "Invalid value.",
+    "errors.validation.invalid_key": "Invalid key.",
+    "errors.validation.invalid_element": "Invalid entry.",
+    "errors.validation.invalid_value": "Invalid choice.",
+    "errors.validation.custom": "Invalid value.",
+    "errors.validation.unexpected_field": "Unknown field.",
+    "errors.validation.out_of_bounds": "Value out of allowed range.",
+    "errors.validation.invalid_option": "Invalid choice.",
+    "errors.validation.failed": "Validation failed.",
   },
 };

package/src/i18n.tsx

@@ -25,6 +25,21 @@ export type TranslationBundle = Readonly<Record<string, string>>;
 /** Map von Locale-Code (BCP-47, z.B. `"de"`, `"en-US"`) → Bundle. */
 export type TranslationsByLocale = Readonly<Record<string, TranslationBundle>>;
 
+/** Merged zwei TranslationsByLocale-Maps — der override gewinnt pro Key,
+ *  die Locales werden zusammengeführt. Standard-Baustein für Client-
+ *  Plugins, die App-Overrides über ihre Default-Bundles legen. */
+export function mergeTranslations(
+  base: TranslationsByLocale,
+  override: TranslationsByLocale,
+): TranslationsByLocale {
+  const locales = new Set([...Object.keys(base), ...Object.keys(override)]);
+  const merged: Record<string, Record<string, string>> = {};
+  for (const locale of locales) {
+    merged[locale] = { ...(base[locale] ?? {}), ...(override[locale] ?? {}) };
+  }
+  return merged;
+}
+
 type LocaleContextValue = {
   readonly resolver: LocaleResolver;
   readonly fallbackBundles: readonly TranslationsByLocale[];

package/src/index.ts

@@ -75,6 +75,7 @@ export type {
 export {
   createStaticLocaleResolver,
   LocaleProvider,
+  mergeTranslations,
   useLocale,
   useTranslation,
 } from "./i18n";

package/src/primitives.tsx

@@ -264,10 +264,16 @@ export type InputProps =
       readonly kind: "timestamp";
       readonly id: string;
       readonly name: string;
-      /** ISO-8601 Datetime-String inkl. Zeit ("2026-04-25T13:45").
-       *  Empty-State = `""`. Web nutzt `<input type="datetime-local">`. */
+      /** ISO-8601 Datetime-String. UTC-Instant mit `Z`
+       *  ("2026-04-25T13:45:00Z") oder Wall-Clock ohne Offset
+       *  ("2026-04-25T13:45", nur bei wallClock). Empty-State = `""`.
+       *  Web nutzt `<input type="datetime-local">` und konvertiert. */
       readonly value: string;
       readonly onChange: (v: string | undefined) => void;
+      /** true = locatedTimestamp (Wall-Clock ohne Offset, Server
+       *  validiert z.iso.datetime({local:true})). false/undefined =
+       *  UTC-Instant, onChange MUSS mit `Z`-Suffix emittieren. */
+      readonly wallClock?: boolean;
       readonly disabled?: boolean;
       readonly required?: boolean;
       readonly hasError?: boolean;
@@ -404,7 +410,10 @@ export type FormProps = {
  *  View mit Header-Text. Native-Impls können den Title als Accordion
  *  oder Collapsible rendern. */
 export type SectionProps = {
-  readonly title: string;
+  /** Optional — ohne Titel rendert die Section nur die Gruppierung
+   *  (kein Header). RenderEdit lässt ihn weg, wenn er den Screen-Titel
+   *  der Action-Bar 1:1 wiederholen würde. */
+  readonly title?: string;
   readonly children: ReactNode;
   readonly testId?: string;
 };
@@ -477,9 +486,16 @@ export type DialogProps = {
 };
 
 /** Source-badge for one cascade step (User / Tenant / System / …).
- *  Used inline next to a config value to indicate where it came from. */
+ *  Used inline next to a config value to indicate where it came from.
+ *  Requires a LocaleProvider above it (labels run through useTranslation)
+ *  — createKumikoApp wires one; standalone consumers must wrap. */
 export type ConfigSourceBadgeProps = {
   readonly source: ConfigValueSource;
+  /** Scope of the hosting screen. Non-system screens collapse sources
+   *  ABOVE their scope (system-row/app-override/computed) into the neutral
+   *  default badge — operator internals stay invisible to tenants, same
+   *  rule as ConfigCascadeView's toDisplayLevels. */
+  readonly screenScope?: ConfigScope;
 };
 
 /** Collapsible cascade-view that lives under a config-edit input.