@cosmicdrift/kumiko-renderer 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.44.0",
+  "version": "0.45.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>",

package/src/app/extension-form-submit.tsx

@@ -0,0 +1,118 @@
+// @runtime client
+// Extension-Form-Submit-Registry — erlaubt einer Extension-Section (z.B.
+// Custom-Fields), beim Submit des umgebenden entityEdit-Forms mitzuschreiben,
+// statt einen eigenen Save-Button zu führen ("composed form, ein Save",
+// Bug-Bash 3 #1). Die Section meldet (a) einen Submit-Handler und (b) ihren
+// dirty-State an die Form; die Form aktiviert ihren Save-Button auch wenn nur
+// eine Section dirty ist und ruft nach dem Entity-Write alle Section-Handler
+// mit der entityId.
+//
+// Ohne umgebende Form (Context === null) fällt die Section auf ihren eigenen
+// Save-Button zurück (Standalone-Backward-Compat).
+
+import { createContext, useContext, useEffect, useId, useMemo, useRef } from "react";
+
+export type ExtensionSubmitContext = { readonly entityId: string };
+
+export type ExtensionSubmitResult = {
+  readonly isSuccess: boolean;
+  /** i18n-Key für die Fehlermeldung, die die Form als Banner zeigt. */
+  readonly errorKey?: string;
+};
+
+export type ExtensionFormSubmitHandler = (
+  ctx: ExtensionSubmitContext,
+) => Promise<ExtensionSubmitResult>;
+
+type Registration = {
+  readonly key: string;
+  readonly dirty: boolean;
+  readonly handler: ExtensionFormSubmitHandler;
+};
+
+export type ExtensionFormRegistry = {
+  readonly upsert: (reg: Registration) => void;
+  readonly remove: (key: string) => void;
+};
+
+const ExtensionFormRegistryContext = createContext<ExtensionFormRegistry | null>(null);
+
+export const ExtensionFormRegistryProvider = ExtensionFormRegistryContext.Provider;
+
+// Host-Seite (render-edit): hält die Registrierungen in einem ref, meldet den
+// aggregierten dirty-State via onDirtyChange hoch (damit der Save-Button
+// re-rendert) und liefert runAll() zum Ausführen aller Handler beim Submit.
+export function useExtensionFormHost(onDirtyChange: (anyDirty: boolean) => void): {
+  readonly registry: ExtensionFormRegistry;
+  readonly runAll: (ctx: ExtensionSubmitContext) => Promise<readonly ExtensionSubmitResult[]>;
+} {
+  const regsRef = useRef<Map<string, Registration>>(new Map());
+  const onDirtyRef = useRef(onDirtyChange);
+  onDirtyRef.current = onDirtyChange;
+
+  const registry = useMemo<ExtensionFormRegistry>(() => {
+    const emitDirty = (): void => {
+      let any = false;
+      for (const r of regsRef.current.values()) {
+        if (r.dirty) {
+          any = true;
+          break;
+        }
+      }
+      onDirtyRef.current(any);
+    };
+    return {
+      upsert: (reg) => {
+        regsRef.current.set(reg.key, reg);
+        emitDirty();
+      },
+      remove: (key) => {
+        regsRef.current.delete(key);
+        emitDirty();
+      },
+    };
+  }, []);
+
+  const runAll = useMemo(
+    () =>
+      async (ctx: ExtensionSubmitContext): Promise<readonly ExtensionSubmitResult[]> => {
+        const results: ExtensionSubmitResult[] = [];
+        // Insertion-Order (Map) = Section-Reihenfolge im Form.
+        for (const reg of regsRef.current.values()) {
+          results.push(await reg.handler(ctx));
+        }
+        return results;
+      },
+    [],
+  );
+
+  return { registry, runAll };
+}
+
+// Section-Seite: meldet Handler + dirty an die umgebende Form. Returnt true
+// wenn eine composed-Form vorhanden ist (Section blendet dann ihren eigenen
+// Save-Button aus); false = standalone (eigener Save-Button bleibt).
+export function useExtensionFormSubmit(opts: {
+  readonly dirty: boolean;
+  readonly onSubmit: ExtensionFormSubmitHandler;
+}): boolean {
+  const registry = useContext(ExtensionFormRegistryContext);
+  const key = useId();
+  // Handler über ref, damit das Re-Registrieren NICHT an jeder Handler-
+  // Identity hängt (nur an dirty); der Handler liest immer den frischen
+  // Closure-State (pending) zur Aufruf-Zeit.
+  const handlerRef = useRef(opts.onSubmit);
+  handlerRef.current = opts.onSubmit;
+
+  useEffect(() => {
+    if (registry === null) return;
+    registry.upsert({
+      key,
+      dirty: opts.dirty,
+      handler: (ctx) => handlerRef.current(ctx),
+    });
+    return () => registry.remove(key);
+  }, [registry, key, opts.dirty]);
+
+  return registry !== null;
+}

package/src/components/render-edit.tsx

@@ -23,6 +23,7 @@ import type {
 import { computeEditViewModel } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useMemo, useState } from "react";
 import type { z } from "zod";
+import { ExtensionFormRegistryProvider, useExtensionFormHost } from "../app/extension-form-submit";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections";
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
@@ -196,6 +197,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [formError, setFormError] = useState<DispatcherError | null>(null);
+  // Composed-Save: Extension-Sections melden hier ihren dirty-State (damit der
+  // Save-Button aktiv wird wenn NUR eine Section geändert wurde) + ihren
+  // Submit-Handler (läuft nach dem Entity-Write). extensionErrorKey hält den
+  // i18n-Key einer fehlgeschlagenen Section-Persistierung.
+  const [extensionDirty, setExtensionDirty] = useState(false);
+  const [extensionErrorKey, setExtensionErrorKey] = useState<string | null>(null);
+  const { registry: extensionFormRegistry, runAll: runExtensionSubmits } =
+    useExtensionFormHost(setExtensionDirty);
   const { Button, Banner, Dialog, Form, Section, Grid, GridCell, Text } = usePrimitives();
 
   const fields = useMemo(() => deriveFormFields<TValues, TCtx>(screen), [screen]);
@@ -232,9 +241,32 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     [screen, entity, snapshot.values, translate, featureName],
   );
 
+  // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
+  // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
+  // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
+  async function persistExtensions(): Promise<boolean> {
+    const entityId = entityIdProp ?? null;
+    if (entityId === null) return true;
+    const results = await runExtensionSubmits({ entityId });
+    const failed = results.find((r) => !r.isSuccess);
+    if (failed !== undefined) {
+      setExtensionErrorKey(failed.errorKey ?? "kumiko.form.extension.save-failed");
+      return false;
+    }
+    return true;
+  }
+
   async function handleSubmit(): Promise<void> {
     setIsSubmitting(true);
+    setExtensionErrorKey(null);
     try {
+      // Extension-only: nur eine Section ist dirty, das Haupt-Form unverändert.
+      // Kein Entity-Write (würde einen leeren changes-Payload schreiben) — nur
+      // die Section-Handler laufen lassen.
+      if (snapshot.isUnchanged && extensionDirty) {
+        await persistExtensions();
+        return;
+      }
       let result: SubmitResult<unknown>;
       if (customSubmit !== undefined) {
         // customSubmit-Pfad (z.B. configEdit, das pro Field einen
@@ -274,6 +306,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       // Field-Errors fließen über snapshot.errors in die einzelnen Fields.
       if (result.isSuccess) {
         setFormError(null);
+        await persistExtensions();
       } else if (!result.validationBlocked) {
         const fieldIssues = result.error.details?.fields ?? [];
         setFormError(fieldIssues.length === 0 ? result.error : null);
@@ -312,7 +345,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       )}
       <Button
         type="submit"
-        disabled={snapshot.isUnchanged || isSubmitting}
+        disabled={(snapshot.isUnchanged && !extensionDirty) || isSubmitting}
         loading={isSubmitting}
         variant="primary"
         testId="render-edit-submit"
@@ -329,94 +362,101 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const formTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
 
   return (
-    <Form
-      onSubmit={() => void handleSubmit()}
-      title={formTitle}
-      actions={formActions}
-      testId="render-edit-form"
-    >
-      {vm.sections.map((section: EditSectionViewModel) => {
-        if (section.kind === "extension") {
+    <ExtensionFormRegistryProvider value={extensionFormRegistry}>
+      <Form
+        onSubmit={() => void handleSubmit()}
+        title={formTitle}
+        actions={formActions}
+        testId="render-edit-form"
+      >
+        {vm.sections.map((section: EditSectionViewModel) => {
+          if (section.kind === "extension") {
+            return (
+              <ExtensionSectionMount
+                key={section.title}
+                section={section}
+                entityName={vm.entityName}
+                entityId={entityIdProp !== undefined ? entityIdProp : vm.id}
+                initialValues={extensionInitialValues}
+              />
+            );
+          }
+          // 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 (
-            <ExtensionSectionMount
+            <Section
               key={section.title}
-              section={section}
-              entityName={vm.entityName}
-              entityId={entityIdProp !== undefined ? entityIdProp : vm.id}
-              initialValues={extensionInitialValues}
-            />
+              {...(sectionTitle !== undefined && { title: sectionTitle })}
+              testId={`section-${section.title}`}
+            >
+              <Grid columns={section.columns}>
+                {section.fields.map((field: EditFieldViewModel) => (
+                  <GridCellForField
+                    key={field.field}
+                    field={field}
+                    columns={section.columns}
+                    issues={snapshot.errors[field.field]}
+                    onChange={(v) => {
+                      (controller.setField as (k: string, v: unknown) => void)(field.field, v);
+                    }}
+                    GridCell={GridCell}
+                    featureName={featureName}
+                    {...(labelAppendix !== undefined && {
+                      labelAppendix: labelAppendix(field.field),
+                    })}
+                    {...(fieldAppendix !== undefined && {
+                      fieldAppendix: fieldAppendix(field.field),
+                    })}
+                  />
+                ))}
+              </Grid>
+            </Section>
           );
-        }
-        // 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}
-            {...(sectionTitle !== undefined && { title: sectionTitle })}
-            testId={`section-${section.title}`}
-          >
-            <Grid columns={section.columns}>
-              {section.fields.map((field: EditFieldViewModel) => (
-                <GridCellForField
-                  key={field.field}
-                  field={field}
-                  columns={section.columns}
-                  issues={snapshot.errors[field.field]}
-                  onChange={(v) => {
-                    (controller.setField as (k: string, v: unknown) => void)(field.field, v);
+        })}
+        {formError !== null && (
+          <Banner
+            variant="error"
+            testId="render-edit-form-error"
+            actions={
+              formError.code === "version_conflict" && onReload !== undefined ? (
+                <Button
+                  variant="secondary"
+                  onClick={() => {
+                    onReload();
+                    setFormError(null);
                   }}
-                  GridCell={GridCell}
-                  featureName={featureName}
-                  {...(labelAppendix !== undefined && {
-                    labelAppendix: labelAppendix(field.field),
-                  })}
-                  {...(fieldAppendix !== undefined && {
-                    fieldAppendix: fieldAppendix(field.field),
-                  })}
-                />
-              ))}
-            </Grid>
-          </Section>
-        );
-      })}
-      {formError !== null && (
-        <Banner
-          variant="error"
-          testId="render-edit-form-error"
-          actions={
-            formError.code === "version_conflict" && onReload !== undefined ? (
-              <Button
-                variant="secondary"
-                onClick={() => {
-                  onReload();
-                  setFormError(null);
-                }}
-                testId="render-edit-form-error-reload"
-              >
-                {translate("kumiko.actions.reload")}
-              </Button>
-            ) : undefined
-          }
-        >
-          <Text testId="render-edit-form-error-key">{translate(formError.i18nKey)}</Text>
-        </Banner>
-      )}
-      {onDelete !== undefined && (
-        <Dialog
-          open={confirmDeleteOpen}
-          onOpenChange={setConfirmDeleteOpen}
-          title={translate("kumiko.actions.delete-confirm")}
-          confirmLabel={translate("kumiko.actions.delete")}
-          variant="danger"
-          onConfirm={async () => {
-            await onDelete();
-          }}
-          testId="render-edit-delete-dialog"
-        />
-      )}
-    </Form>
+                  testId="render-edit-form-error-reload"
+                >
+                  {translate("kumiko.actions.reload")}
+                </Button>
+              ) : undefined
+            }
+          >
+            <Text testId="render-edit-form-error-key">{translate(formError.i18nKey)}</Text>
+          </Banner>
+        )}
+        {extensionErrorKey !== null && (
+          <Banner variant="error" testId="render-edit-extension-error">
+            <Text testId="render-edit-extension-error-key">{translate(extensionErrorKey)}</Text>
+          </Banner>
+        )}
+        {onDelete !== undefined && (
+          <Dialog
+            open={confirmDeleteOpen}
+            onOpenChange={setConfirmDeleteOpen}
+            title={translate("kumiko.actions.delete-confirm")}
+            confirmLabel={translate("kumiko.actions.delete")}
+            variant="danger"
+            onConfirm={async () => {
+              await onDelete();
+            }}
+            testId="render-edit-delete-dialog"
+          />
+        )}
+      </Form>
+    </ExtensionFormRegistryProvider>
   );
 }
 

package/src/components/render-list.tsx

@@ -253,14 +253,18 @@ export function RenderList(props: RenderListProps): ReactNode {
     />
   ) : undefined;
 
-  // Toolbar-End-Slot: Toolbar-Actions (List-Header-Buttons aus dem
-  // Schema) + optional "+ Neu" am rechten Edge. Reihenfolge im Rendering
-  // = Reihenfolge im Array (Schema-deklariert), "+ Neu" kommt zuletzt
-  // weil das die häufigste/auffälligste CTA ist.
+  // Toolbar-End-Slot: optionaler Header-Slot (z.B. Cap-Counter, links im
+  // rechten Cluster) + Toolbar-Actions (List-Header-Buttons aus dem Schema)
+  // + optional "+ Neu" am rechten Edge. Der Header-Slot lebt IN der Toolbar-
+  // Zeile (gleicher Card-Rahmen), nicht als loser Text über dem Screen-Titel
+  // (Bug-Bash 3 #12). Reihenfolge = Array-Reihenfolge (Schema-deklariert),
+  // "+ Neu" zuletzt weil das die häufigste/auffälligste CTA ist.
   const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
+  const hasHeaderSlot = screen.slots?.header !== undefined;
   const toolbarEnd =
-    hasToolbarActions || onCreate !== undefined ? (
+    hasHeaderSlot || hasToolbarActions || onCreate !== undefined ? (
       <>
+        {hasHeaderSlot && <ListHeaderSlotMount screen={screen} />}
         {hasToolbarActions &&
           toolbarActions.map((a) => (
             <ToolbarActionView key={a.id} action={a} Button={Button} Dialog={Dialog} />
@@ -300,7 +304,6 @@ export function RenderList(props: RenderListProps): ReactNode {
   // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
   return (
     <>
-      <ListHeaderSlotMount screen={screen} />
       {referenceColumns.map(
         (rc: { field: string; refEntity: string; refFeature: string; labelField: string }) => (
           <ReferenceLookupBridge
@@ -334,8 +337,8 @@ export function RenderList(props: RenderListProps): ReactNode {
   );
 }
 
-// Header-Slot über der Liste: `screen.slots.header` ist eine
-// PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über
+// Header-Slot in der Listen-Toolbar (toolbarEnd): `screen.slots.header` ist
+// eine PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über
 // dieselbe ExtensionSectionsProvider-Registry wie entityEdit-Sections.
 // entityId ist null (Listen-Kontext, keine Row); die Component lädt ihre
 // Daten selbst (z.B. ein Cap-Counter aus einer usage-Query). Eigene

package/src/i18n-defaults.ts

@@ -52,7 +52,6 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.config.source.computed": "Berechnet",
     "kumiko.config.source.default": "Standard",
     "kumiko.config.source.missing": "Fehlt",
-    "kumiko.config.cascade.preset": "Vorgabe",
     "kumiko.config.cascade.noValue": "Kein Wert gesetzt",
     "kumiko.config.cascade.activeMarker": "aktiv",
     "kumiko.config.cascade.resetTo": "Überschreibung zurücksetzen ({scope})",
@@ -62,6 +61,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.form.error.generic": "Etwas ist schiefgegangen.",
     "kumiko.form.error.version-conflict":
       "Datensatz wurde zwischenzeitlich geändert. Lade neu und versuche es erneut.",
+    "kumiko.form.extension.save-failed": "Ein Zusatzfeld konnte nicht gespeichert werden.",
 
     // Validation — Default-Reason-Codes aus dem Framework. App-Code
     // kann eigene Codes via Validation-Hooks reinwerfen; die hier sind
@@ -125,7 +125,6 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.config.source.computed": "Computed",
     "kumiko.config.source.default": "Default",
     "kumiko.config.source.missing": "Missing",
-    "kumiko.config.cascade.preset": "Preset",
     "kumiko.config.cascade.noValue": "No value set",
     "kumiko.config.cascade.activeMarker": "active",
     "kumiko.config.cascade.resetTo": "Reset override ({scope})",
@@ -133,6 +132,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.form.error.generic": "Something went wrong.",
     "kumiko.form.error.version-conflict":
       "Record was modified in the meantime. Reload and try again.",
+    "kumiko.form.extension.save-failed": "A custom field could not be saved.",
 
     "kumiko.validation.required": "Required.",
     "kumiko.validation.invalid": "Invalid value.",

package/src/index.ts

@@ -18,6 +18,13 @@ export type {
 export { ColumnRenderersProvider, useColumnRenderer } from "./app/column-renderers";
 export type { CustomScreensMap, CustomScreensProviderProps } from "./app/custom-screens";
 export { CustomScreensProvider, useCustomScreenComponent } from "./app/custom-screens";
+export type {
+  ExtensionFormRegistry,
+  ExtensionFormSubmitHandler,
+  ExtensionSubmitContext,
+  ExtensionSubmitResult,
+} from "./app/extension-form-submit";
+export { ExtensionFormRegistryProvider, useExtensionFormSubmit } from "./app/extension-form-submit";
 export type {
   ExtensionSectionComponent,
   ExtensionSectionProps,
@@ -87,6 +94,7 @@ export type {
   CorePrimitives,
   DataTableProps,
   DataTableRowAction,
+  DataTableRowActionMode,
   DataTableSort,
   DataTableSortDir,
   DialogProps,

package/src/primitives.tsx

@@ -302,6 +302,9 @@ export type DataTableSort = {
   readonly dir: DataTableSortDir;
 };
 
+// Render-Modus der Row-Action-Spalte (siehe DataTableProps.rowActionMode).
+export type DataTableRowActionMode = "adaptive" | "inline";
+
 // Resolved-Form einer Row-Action (KumikoScreen baut das aus
 // EntityListScreenDefinition.rowActions): Labels schon translated,
 // handler-QN aufgelöst zu einer onTrigger-Function die den dispatcher
@@ -348,6 +351,14 @@ export type DataTableProps = {
    *  Form (Labels + onTrigger schon verdrahtet); DataTable kümmert
    *  sich nur um Render + Confirm-Dialog. */
   readonly rowActions?: readonly DataTableRowAction[];
+  /** Wie die Row-Action-Spalte rendert:
+   *  - `"adaptive"` (Default): ≤2 sichtbare Actions inline (rechtsbündig),
+   *    >2 als Kebab-Dropdown. Passt die Optik automatisch an die Anzahl an.
+   *  - `"inline"`: IMMER Inline-Buttons, linksbündig — auch bei >2 (kein
+   *    Kebab). So stehen die Aktionen über alle Rows an derselben x-Position
+   *    (kein Wandern durch unterschiedlich breite Labels) und alle Listen
+   *    einer App sehen gleich aus. */
+  readonly rowActionMode?: DataTableRowActionMode;
   /** Custom Empty-State-Inhalt (z. B. Icon + Heading + CTA-Button).
    *  Default-Renderer rahmt ihn in einer dashed-border Box. */
   readonly emptyState?: ReactNode;