@cosmicdrift/kumiko-renderer 0.130.1 → 0.131.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.130.1",
+  "version": "0.131.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.130.1",
-    "@cosmicdrift/kumiko-headless": "0.130.1",
+    "@cosmicdrift/kumiko-framework": "0.131.0",
+    "@cosmicdrift/kumiko-headless": "0.131.0",
     "react": "^19.2.6"
   },
   "devDependencies": {

package/src/app/dashboard-body.tsx

@@ -0,0 +1,32 @@
+// Dashboard-Body-Injection: der KumikoScreen-Switch ist plattform-agnostisch,
+// die Dashboard-Panels (StatCard, Charts) sind es nicht — die Implementierung
+// kommt vom Platform-Package (renderer-web registriert seine Web-Variante in
+// createKumikoApp). Gleiches Muster wie CustomScreensProvider.
+
+import type { DashboardScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "@cosmicdrift/kumiko-headless";
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+export type DashboardBodyProps = {
+  readonly screen: DashboardScreenDefinition;
+  readonly translate?: Translate;
+};
+
+const DashboardBodyContext = createContext<ComponentType<DashboardBodyProps> | undefined>(
+  undefined,
+);
+
+export type DashboardBodyProviderProps = {
+  readonly children: ReactNode;
+  readonly value: ComponentType<DashboardBodyProps>;
+};
+
+export function DashboardBodyProvider({ children, value }: DashboardBodyProviderProps): ReactNode {
+  return <DashboardBodyContext.Provider value={value}>{children}</DashboardBodyContext.Provider>;
+}
+
+/** Undefined wenn kein Platform-Package einen Dashboard-Body registriert
+ *  hat — KumikoScreen zeigt dann seinen Placeholder-Banner. */
+export function useDashboardBody(): ComponentType<DashboardBodyProps> | undefined {
+  return useContext(DashboardBodyContext);
+}

package/src/app/kumiko-screen.tsx

@@ -2,6 +2,7 @@ import type { ConfigCascade } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
+  DashboardScreenDefinition,
   EntityDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
@@ -34,6 +35,7 @@ import { type DataTableFacet, type DataTableRowAction, usePrimitives } from "../
 import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./action-form-shim";
 import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config-edit-shim";
 import { useCustomScreenComponent } from "./custom-screens";
+import { useDashboardBody } from "./dashboard-body";
 import type { FeatureSchema } from "./feature-schema";
 import { useNav } from "./nav";
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim";
@@ -146,6 +148,8 @@ export function KumikoScreen({
           {...(onRowClick !== undefined && { onRowClick })}
         />
       );
+    case "dashboard":
+      return <DashboardScreenBody screen={screen} translate={translate} />;
     case "actionForm":
       return <ActionFormBody schema={schema} screen={screen} translate={translate} />;
     case "configEdit":
@@ -155,6 +159,29 @@ export function KumikoScreen({
   }
 }
 
+// Injection-Body für dashboard-Screens: die Panel-Implementierung (StatCard,
+// Charts) ist plattform-spezifisch und kommt aus dem DashboardBody-Context
+// (renderer-web registriert die Web-Variante in createKumikoApp).
+function DashboardScreenBody({
+  screen,
+  translate,
+}: {
+  readonly screen: DashboardScreenDefinition;
+  readonly translate?: Translate;
+}): ReactNode {
+  const { Banner, Text } = usePrimitives();
+  const Body = useDashboardBody();
+  if (Body === undefined) {
+    return (
+      <Banner padded variant="info" testId="kumiko-screen-dashboard-placeholder">
+        Dashboard screen <Text variant="code">{screen.id}</Text> — kein Dashboard-Body registriert
+        (createKumikoApp aus <Text variant="code">kumiko-renderer-web</Text> wired ihn automatisch).
+      </Banner>
+    );
+  }
+  return <Body screen={screen} {...(translate !== undefined && { translate })} />;
+}
+
 // Lookup-Body für custom-screens: schaut die Component aus dem
 // CustomScreens-Context (gefüttert von clientFeatures.components in
 // createKumikoApp). Wenn weder Provider gemounted noch screenId
@@ -1036,6 +1063,7 @@ function ProjectionListBody({
   const { Banner } = usePrimitives();
   const t = useTranslation();
   const nav = useNav();
+  const dispatcher = useOptionalDispatcher();
   const effectiveTranslate = translate ?? t;
   const entity = useMemo(() => synthesizeProjectionEntity(screen.columns), [screen.columns]);
   const listScreen = useMemo(() => synthesizeProjectionScreen(screen), [screen]);
@@ -1066,39 +1094,88 @@ function ProjectionListBody({
     if (screen.rowActions === undefined) return undefined;
     const out: DataTableRowAction[] = [];
     for (const action of screen.rowActions) {
-      // v1: nur navigate (writeHandler-RowActions bräuchten den Dispatcher-Pfad).
-      if (action.kind !== "navigate") continue;
-      const navigateAction = action;
-      const visible = action.visible;
+      if (action.kind === "navigate") {
+        const navigateAction = action;
+        const visible = action.visible;
+        out.push({
+          id: action.id,
+          label: effectiveTranslate(action.label),
+          ...(action.style !== undefined && { style: action.style }),
+          onTrigger: (row: ListRowViewModel) => runNavigate(navigateAction, row),
+          ...(visible !== undefined && {
+            isVisible: (row: ListRowViewModel) => evalFieldCondition(visible, row.values),
+          }),
+        });
+        continue;
+      }
+      // writeHandler (default-kind) — gleicher Dispatch-Pfad wie entityList:
+      // Failure-Result MUSS zum Error werden (sonst schließt der Confirm-
+      // Dialog kommentarlos).
+      if (dispatcher === undefined) continue;
+      const writeAction = action as RowActionWriteHandler;
+      const writeVisible = writeAction.visible;
       out.push({
-        id: action.id,
-        label: effectiveTranslate(action.label),
-        ...(action.style !== undefined && { style: action.style }),
-        onTrigger: (row: ListRowViewModel) => runNavigate(navigateAction, row),
-        ...(visible !== undefined && {
-          isVisible: (row: ListRowViewModel) => evalFieldCondition(visible, row.values),
+        id: writeAction.id,
+        label: effectiveTranslate(writeAction.label),
+        ...(writeAction.style !== undefined && { style: writeAction.style }),
+        ...(writeAction.confirm !== undefined && {
+          confirm: effectiveTranslate(writeAction.confirm),
+        }),
+        ...(writeAction.confirmLabel !== undefined && {
+          confirmLabel: effectiveTranslate(writeAction.confirmLabel),
+        }),
+        onTrigger: async (row: ListRowViewModel) => {
+          const payload =
+            writeAction.payload !== undefined
+              ? evalRowExtractor(writeAction.payload, row.values)
+              : { id: row.values["id"] };
+          const result = await dispatcher.write(writeAction.handler, payload);
+          if (!result.isSuccess) {
+            throw new WriteFailedError(
+              result.error,
+              dispatcherErrorText(result.error, effectiveTranslate),
+            );
+          }
+        },
+        ...(writeVisible !== undefined && {
+          isVisible: (row: ListRowViewModel) => evalFieldCondition(writeVisible, row.values),
         }),
       });
     }
     return out.length > 0 ? out : undefined;
-  }, [screen.rowActions, effectiveTranslate, runNavigate]);
+  }, [screen.rowActions, effectiveTranslate, runNavigate, dispatcher]);
 
   const toolbarActions = useMemo((): readonly ToolbarActionButton[] | undefined => {
     if (screen.toolbarActions === undefined) return undefined;
     const out: ToolbarActionButton[] = [];
     for (const action of screen.toolbarActions) {
-      // v1: nur navigate (writeHandler-Toolbar bräuchte den Dispatcher-Pfad).
-      if (action.kind !== "navigate") continue;
-      const target = action.screen;
+      if (action.kind === "navigate") {
+        const target = action.screen;
+        out.push({
+          id: action.id,
+          label: effectiveTranslate(action.label),
+          ...(action.style !== undefined && { style: action.style }),
+          onTrigger: () => nav.navigate({ screenId: target }),
+        });
+        continue;
+      }
+      // writeHandler — analog entityList; ohne Dispatcher skippen statt crashen.
+      if (dispatcher === undefined) continue;
       out.push({
         id: action.id,
         label: effectiveTranslate(action.label),
         ...(action.style !== undefined && { style: action.style }),
-        onTrigger: () => nav.navigate({ screenId: target }),
+        ...(action.confirm !== undefined && { confirm: effectiveTranslate(action.confirm) }),
+        ...(action.confirmLabel !== undefined && {
+          confirmLabel: effectiveTranslate(action.confirmLabel),
+        }),
+        onTrigger: async () => {
+          await dispatcher.write(action.handler, action.payload ?? {});
+        },
       });
     }
     return out.length > 0 ? out : undefined;
-  }, [screen.toolbarActions, effectiveTranslate, nav]);
+  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher]);
 
   if (rowsQuery.loading && rowsQuery.data === null) {
     return (

package/src/components/__tests__/render-field-app-locale.test.tsx

@@ -40,6 +40,7 @@ const testPrimitives: CorePrimitives = {
   Lightbox: noop,
   ConfigSourceBadge: noop,
   ConfigCascadeView: noop,
+  Link: noop,
 };
 
 function moneyField(): EditFieldViewModel {

package/src/hooks/__tests__/use-disclosure.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { act, renderHook } from "@testing-library/react";
+import { useDisclosure } from "../use-disclosure";
+
+describe("useDisclosure", () => {
+  test("open/close/toggle steuern den Zustand", () => {
+    const { result } = renderHook(() => useDisclosure());
+    expect(result.current.open).toBe(false);
+    act(() => result.current.onOpen());
+    expect(result.current.open).toBe(true);
+    act(() => result.current.onClose());
+    expect(result.current.open).toBe(false);
+    act(() => result.current.onToggle());
+    expect(result.current.open).toBe(true);
+  });
+
+  test("Callbacks sind referenz-stabil über Re-Renders", () => {
+    const { result, rerender } = renderHook(() => useDisclosure(true));
+    const first = result.current;
+    rerender();
+    expect(result.current.onOpen).toBe(first.onOpen);
+    expect(result.current.onClose).toBe(first.onClose);
+    expect(result.current.onToggle).toBe(first.onToggle);
+  });
+});

package/src/hooks/__tests__/use-mutation.test.tsx

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { useMutation } from "../use-mutation";
+
+function makeDispatcher(write: Dispatcher["write"]): Dispatcher {
+  return {
+    write,
+    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function wrapperFor(dispatcher: Dispatcher) {
+  return ({ children }: { readonly children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useMutation", () => {
+  test("Success setzt data, pending toggelt, Result wird durchgereicht", async () => {
+    let resolve: (() => void) | undefined;
+    const gate = new Promise<void>((r) => {
+      resolve = r;
+    });
+    const dispatcher = makeDispatcher((async (_type: string, payload: unknown) => {
+      await gate;
+      return { isSuccess: true, data: { echoed: payload } };
+    }) as unknown as Dispatcher["write"]);
+
+    const { result } = renderHook(() => useMutation<{ echoed: unknown }>("f:write:x:create"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    expect(result.current.pending).toBe(false);
+    let outcome: Awaited<ReturnType<typeof result.current.mutate>> | undefined;
+    act(() => {
+      void result.current.mutate({ name: "a" }).then((r) => {
+        outcome = r;
+      });
+    });
+    await waitFor(() => expect(result.current.pending).toBe(true));
+    act(() => resolve?.());
+    await waitFor(() => expect(result.current.pending).toBe(false));
+    expect(result.current.data).toEqual({ echoed: { name: "a" } });
+    expect(result.current.error).toBeNull();
+    expect(outcome?.isSuccess).toBe(true);
+  });
+
+  test("Failure setzt error, reset räumt auf", async () => {
+    const dispatcher = makeDispatcher((async () => ({
+      isSuccess: false,
+      error: { code: "conflict", message: "boom", i18nKey: "errors.conflict" },
+    })) as unknown as Dispatcher["write"]);
+
+    const { result } = renderHook(() => useMutation("f:write:x:create"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    await act(async () => {
+      await result.current.mutate({});
+    });
+    expect(result.current.error?.code).toBe("conflict");
+    act(() => result.current.reset());
+    expect(result.current.error).toBeNull();
+    expect(result.current.data).toBeNull();
+  });
+});

package/src/hooks/use-disclosure.ts

@@ -0,0 +1,20 @@
+import { useCallback, useState } from "react";
+
+// Open/close state for dialogs, sheets and collapsibles — the standard
+// replacement for the hand-rolled `useState(false)` + toggle-callback
+// trio in app screens. All callbacks are referentially stable.
+
+export type UseDisclosureResult = {
+  readonly open: boolean;
+  readonly onOpen: () => void;
+  readonly onClose: () => void;
+  readonly onToggle: () => void;
+};
+
+export function useDisclosure(initialOpen = false): UseDisclosureResult {
+  const [open, setOpen] = useState(initialOpen);
+  const onOpen = useCallback(() => setOpen(true), []);
+  const onClose = useCallback(() => setOpen(false), []);
+  const onToggle = useCallback(() => setOpen((prev) => !prev), []);
+  return { open, onOpen, onClose, onToggle };
+}

package/src/hooks/use-mutation.ts

@@ -0,0 +1,51 @@
+import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
+import { useCallback, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context";
+
+// React wrapper around dispatcher.write — the write-side sibling of
+// useQuery. One hook instance per handler-type; `mutate` carries the
+// payload so a single instance serves list-row actions with varying
+// payloads.
+//
+// `mutate` resolves with the raw WriteResult so callers can branch
+// (navigate on success, keep the form open on failure) without waiting
+// for a re-render of `error`/`data`.
+
+export type UseMutationResult<TData> = {
+  readonly mutate: (payload: unknown) => Promise<WriteResult<TData>>;
+  readonly pending: boolean;
+  readonly error: DispatcherError | null;
+  readonly data: TData | null;
+  readonly reset: () => void;
+};
+
+export function useMutation<TData = unknown>(type: string): UseMutationResult<TData> {
+  const dispatcher = useDispatcher();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<DispatcherError | null>(null);
+  const [data, setData] = useState<TData | null>(null);
+
+  const mutate = useCallback(
+    async (payload: unknown): Promise<WriteResult<TData>> => {
+      setPending(true);
+      setError(null);
+      const result = await dispatcher.write<TData>(type, payload);
+      if (result.isSuccess) {
+        setData(result.data);
+      } else {
+        setError(result.error);
+      }
+      setPending(false);
+      return result;
+    },
+    [dispatcher, type],
+  );
+
+  const reset = useCallback(() => {
+    setPending(false);
+    setError(null);
+    setData(null);
+  }, []);
+
+  return { mutate, pending, error, data, reset };
+}

package/src/i18n-defaults.ts

@@ -45,9 +45,14 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.combobox.loading": "Lade…",
     "kumiko.combobox.placeholder": "—",
 
+    // Widgets — Query-States (QueryTable, LoadingState, ErrorState).
+    "kumiko.widget.loading": "Lade…",
+    "kumiko.widget.error.title": "Konnte nicht geladen werden.",
+
     // Nav — Sidebar Tree (Toggle-aria-Labels).
     "kumiko.nav.expand": "Aufklappen",
     "kumiko.nav.collapse": "Zuklappen",
+    "kumiko.nav.search": "Navigation durchsuchen…",
 
     // Dialog — Confirm-Buttons + Close-aria-Label.
     "kumiko.dialog.confirm": "Bestätigen",
@@ -149,8 +154,12 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.combobox.loading": "Loading…",
     "kumiko.combobox.placeholder": "—",
 
+    "kumiko.widget.loading": "Loading…",
+    "kumiko.widget.error.title": "Couldn't load.",
+
     "kumiko.nav.expand": "Expand",
     "kumiko.nav.collapse": "Collapse",
+    "kumiko.nav.search": "Search navigation…",
 
     "kumiko.dialog.confirm": "Confirm",
     "kumiko.dialog.cancel": "Cancel",

package/src/index.ts

@@ -18,6 +18,8 @@ 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 { DashboardBodyProps, DashboardBodyProviderProps } from "./app/dashboard-body";
+export { DashboardBodyProvider, useDashboardBody } from "./app/dashboard-body";
 export type {
   ExtensionFormRegistry,
   ExtensionFormSubmitHandler,
@@ -62,6 +64,8 @@ export {
   REFERENCE_LIST_LOOKUP_LIMIT,
   REFERENCE_SEARCH_DEBOUNCE_MS,
 } from "./hooks/reference-limits";
+export type { UseDisclosureResult } from "./hooks/use-disclosure";
+export { useDisclosure } from "./hooks/use-disclosure";
 export type { UseFormOptions, UseFormResult } from "./hooks/use-form";
 export { useForm } from "./hooks/use-form";
 export type {
@@ -71,6 +75,8 @@ export type {
   ListUrlStateApi,
 } from "./hooks/use-list-url-state";
 export { useListUrlState } from "./hooks/use-list-url-state";
+export type { UseMutationResult } from "./hooks/use-mutation";
+export { useMutation } from "./hooks/use-mutation";
 export type { UseQueryOptions, UseQueryResult } from "./hooks/use-query";
 export { useQuery } from "./hooks/use-query";
 export { useStore, useStoreSelector } from "./hooks/use-store";
@@ -111,6 +117,7 @@ export type {
   HeadingProps,
   InputProps,
   LightboxProps,
+  LinkProps,
   PrimitivesProviderProps,
   PrimitivesRegistry,
   RuntimeRenderer,

package/src/primitives.tsx

@@ -66,8 +66,25 @@ export type ButtonProps = {
   readonly loading?: boolean;
   /** Semantische Klasse — default="primary". Custom-Impls entscheiden
    *  was daraus visuell wird; die Renderer verwenden "primary" für
-   *  Save, "danger" für Delete, "secondary" für Confirm-State. */
-  readonly variant?: "primary" | "secondary" | "danger";
+   *  Save, "danger" für Delete, "secondary" für Confirm-State,
+   *  "link" für Inline-Aktionen im Fließtext (kein BG, underline). */
+  readonly variant?: "primary" | "secondary" | "danger" | "link";
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
+/** Navigations-Link. `variant="button"` rendert die Button-Optik auf einem
+ *  semantischen Anchor (z.B. „Zum Login" nach Reset-Success), `muted` den
+ *  dezenten Sekundär-Link. Interne SPA-Navigation läuft über den Browser-
+ *  Default (History-Integration liegt beim Nav-Layer, nicht am Primitive). */
+export type LinkProps = {
+  readonly href: string;
+  readonly variant?: "default" | "button" | "muted";
+  /** `_blank` setzt in der Web-Impl automatisch rel="noreferrer". */
+  readonly target?: "_blank";
+  /** Layout-Zusätze (self-center, text-xs) — Web merged via cn(),
+   *  Native-Impls ignorieren es (Präzedenz: CardProps.className). */
+  readonly className?: string;
   readonly children: ReactNode;
   readonly testId?: string;
 };
@@ -533,9 +550,10 @@ export type GridCellProps = {
 /** Semantischer Text. Variants bilden Standard-Typografie-Rollen ab —
  *  `body` ist Default, `small` für sekundäre Labels, `code` für inline
  *  monospace (entityId, screen-id), `required-mark` für das Sternchen
- *  hinter Labels. Custom-Impls mappen auf ihren TypeScale. */
+ *  hinter Labels, `muted` für gedimmten Fließtext (text-sm muted-
+ *  foreground). Custom-Impls mappen auf ihren TypeScale. */
 export type TextProps = {
-  readonly variant?: "body" | "small" | "code" | "required-mark";
+  readonly variant?: "body" | "small" | "code" | "required-mark" | "muted";
   readonly children: ReactNode;
   readonly testId?: string;
 };
@@ -674,6 +692,7 @@ export type CorePrimitives = {
   readonly Lightbox: ComponentType<LightboxProps>;
   readonly ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
   readonly ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;
+  readonly Link: ComponentType<LinkProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern