@cosmicdrift/kumiko-renderer 0.1.0

package/src/app/nav.tsx

@@ -0,0 +1,124 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+// Navigation-Contract, plattform-neutral. Types + Context + Hook leben
+// hier; die konkrete Implementation (window.history im Web,
+// react-navigation im Native) kommt via `<NavProvider value={...}>`
+// vom Plattform-Package rein.
+//
+// Pfad-Format hat zwei Modi je nach App-Schema:
+//   * ohne Workspaces: `/<screenId>[/<entityId>]`
+//   * mit Workspaces:  `/<workspaceId>/<screenId>[/<entityId>]`
+// Der Mode wird beim parsePath() per `hasWorkspaces` Flag durchgereicht
+// — Schema-Layer entscheidet, parsePath bleibt dumm/pure. formatPath()
+// braucht keinen Hint: target.workspaceId vorhanden → Prefix; sonst flach.
+
+export type NavRoute = {
+  // Active workspace short id, present iff the app runs in workspace
+  // mode (schema.workspaces non-empty). undefined for non-workspace apps.
+  readonly workspaceId?: string;
+  readonly screenId: string;
+  readonly entityId?: string;
+};
+
+export type NavTarget = {
+  // Optional in workspace-aware navigate calls. Omit for cross-workspace
+  // navigation (current workspace stays); set to switch workspaces in the
+  // same call as picking a screen — e.g. WorkspaceSwitcher does this.
+  readonly workspaceId?: string;
+  readonly screenId: string;
+  readonly entityId?: string;
+};
+
+export type NavApi = {
+  /** Current route — `undefined` when the URL is at the root / there's
+   *  no route selected. Caller's initial fallback kicks in then. */
+  readonly route: NavRoute | undefined;
+  /** Push a new route. Platform-specific Impl writes to
+   *  history/stack and notifies subscribers. */
+  readonly navigate: (target: NavTarget) => void;
+  /** Replace the current route in place. Same effect as navigate from
+   *  the user's perspective, but doesn't add a history entry — used for
+   *  mount-time URL fills (e.g. WorkspaceShell defaulting to `/admin/x`
+   *  when the user typed `/`). Browser Back must take the user out of
+   *  the app, not back to the original empty path. */
+  readonly replace: (target: NavTarget) => void;
+  /** Build the href a click on {target} would produce. Used by
+   *  platform-specific Link-Komponenten (Web: `<a href>`; Native
+   *  typically doesn't need this). */
+  readonly hrefFor: (target: NavTarget) => string;
+  /** Lese-Snapshot der aktuellen Search-Params (Browser: ?key=value-
+   *  Pairs nach dem Pfad). Native-Impls die kein URL-Konzept haben
+   *  liefern ein leeres Object. Wert ist ein Plain-Record (kein Map)
+   *  damit React-Subscribers shallow-compare können. */
+  readonly searchParams: Readonly<Record<string, string>>;
+  /** Mergt Updates in die aktuellen Search-Params. Wert `null` löscht
+   *  den Key. Ändert NICHT den Pfad. Plattform-Impls nutzen
+   *  history.replaceState (kein Push) — Sort/Filter-Toggles sollen
+   *  nicht die Back-Navigation fluten. Native-Impls können no-op'en
+   *  wenn das Konzept nicht existiert. */
+  readonly setSearchParams: (updates: Readonly<Record<string, string | null>>) => void;
+};
+
+// Pfad-Format:
+//   ohne workspaces: `/task-list`, `/task-edit/abc-123`, `/` → undefined
+//   mit workspaces:  `/admin/task-list`, `/admin/task-edit/abc`,
+//                    `/admin` → workspace-only (no screen yet),
+//                    `/` → undefined.
+// Alles nach den ersten 2/3 Segmenten wird ignoriert — kumikos
+// Navigation-Grammatik nested nicht weiter. Nested-Routes wäre eine
+// Spec-Änderung, nicht ein URL-Shape-Unfall.
+export function parsePath(pathname: string, hasWorkspaces?: boolean): NavRoute | undefined {
+  const parts = pathname.split("/").filter((p) => p !== "");
+  if (hasWorkspaces === true) {
+    const [workspaceId, screenId, entityId] = parts;
+    if (workspaceId === undefined || workspaceId === "") return undefined;
+    if (screenId === undefined || screenId === "") {
+      // Workspace-only URL ("/admin") — caller resolves the default screen
+      // for that workspace. We carry workspaceId WITHOUT a screen so the
+      // shell can branch instead of making something up.
+      return { workspaceId, screenId: "" };
+    }
+    return {
+      workspaceId,
+      screenId,
+      ...(entityId !== undefined && { entityId }),
+    };
+  }
+  const [screenId, entityId] = parts;
+  if (screenId === undefined || screenId === "") return undefined;
+  return { screenId, ...(entityId !== undefined && { entityId }) };
+}
+
+export function formatPath(target: NavTarget): string {
+  // Workspace-Mode: prefix the workspace short id. Order matters —
+  // workspace before screen mirrors parsePath's segment order.
+  const segments: string[] = [];
+  if (target.workspaceId !== undefined) segments.push(target.workspaceId);
+  segments.push(target.screenId);
+  if (target.entityId !== undefined) segments.push(target.entityId);
+  return `/${segments.join("/")}`;
+}
+
+// Context + Hook. Default ist `undefined` damit fehlender Provider
+// laut kracht statt ein silent-no-op NavApi mit toten navigate()
+// Aufrufen anzubieten.
+const NavContext = createContext<NavApi | undefined>(undefined);
+
+export type NavProviderProps = {
+  readonly children: ReactNode;
+  readonly value: NavApi;
+};
+
+export function NavProvider({ children, value }: NavProviderProps): ReactNode {
+  return <NavContext.Provider value={value}>{children}</NavContext.Provider>;
+}
+
+export function useNav(): NavApi {
+  const api = useContext(NavContext);
+  if (api === undefined) {
+    throw new Error(
+      "useNav: no <NavProvider> mounted above this component. Plattform-Packages (z.B. @cosmicdrift/kumiko-renderer-web) liefern eine Default-Impl über createKumikoApp.",
+    );
+  }
+  return api;
+}

package/src/app/qn.ts

@@ -0,0 +1,23 @@
+// Qualified-Name-Helper. Kumiko's Registry stempelt beim Boot den
+// Feature-Prefix auf jede Screen/Nav/Workspace-id ein:
+//
+//   r.screen({ id: "task-list", ... })
+//     → registry-stored.id === "tasks:screen:task-list"
+//     → schema.screens (ans Browser) hat id === "tasks:screen:task-list"
+//
+// Der Renderer arbeitet aber mit Short-Form ids — formatPath schreibt
+// sie 1:1 in die URL, parsePath liest sie 1:1 raus. Beim Übergang von
+// Schema (QN-Form) → nav.navigate (Short-Form) muss der Prefix weg,
+// sonst landet die URL doppelt-qualifiziert
+// ("/tasks:screen:task-list" + Re-Lookup → "tasks:screen:tasks:screen:
+// task-list" → 404).
+//
+// `lastSegment` ist die Inverse von qualifyScreenId/Nav/Workspace —
+// nimmt den letzten ":"-getrennten Teil. Robust gegen Strings ohne
+// ":" (returnt sie unverändert, damit App-Author-Code mit Short-Form-
+// ids in eigenen Stellen weiter passt).
+
+export function lastSegment(qn: string): string {
+  const idx = qn.lastIndexOf(":");
+  return idx < 0 ? qn : qn.slice(idx + 1);
+}

package/src/components/render-edit.tsx

@@ -0,0 +1,346 @@
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { normalizeEditField } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  DispatcherError,
+  EditFieldViewModel,
+  FieldConditions,
+  FieldIssue,
+  FormSnapshot,
+  FormValues,
+  SubmitResult,
+  Translate,
+} from "@cosmicdrift/kumiko-headless";
+import { computeEditViewModel } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode, useMemo, useState } from "react";
+import type { z } from "zod";
+import { useForm } from "../hooks/use-form";
+import { useTranslation } from "../i18n";
+import { usePrimitives } from "../primitives";
+import { RenderField } from "./render-field";
+
+// End-to-end renderer für einen entityEdit screen. Rendert aus-
+// schließlich über Primitives — kein raw HTML. Ein Native-Renderer
+// der dieselbe Primitives-Registry füllt kriegt das Form ohne weitere
+// Änderungen.
+
+export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
+  readonly screen: EntityEditScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly featureName: string;
+  readonly initial: TValues;
+  /** Standard single-write Submit-Pfad. Ignoriert wenn `customSubmit`
+   *  gesetzt ist (configEdit-Screens dispatchen mehrere Writes pro
+   *  Submit, da macht writeCommand keinen Sinn). */
+  readonly writeCommand?: string;
+  /** Override für die Submit-Pipeline. Wenn gesetzt, läuft erst
+   *  controller.validate() und dann customSubmit(snapshot) statt
+   *  controller.submit(). On-success rebased der Form-State so dass
+   *  isUnchanged/isDirty wieder false werden — ohne das blieben
+   *  Save-Button und Banner stale. */
+  readonly customSubmit?: (snapshot: FormSnapshot<TValues>) => Promise<SubmitResult<unknown>>;
+  readonly translate?: Translate;
+  readonly ctx?: TCtx;
+  readonly schema?: z.ZodType;
+  readonly onSubmit?: (result: SubmitResult<unknown>) => void;
+  readonly payloadMode?: "values" | "changes";
+  readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+  readonly onDelete?: () => Promise<void> | void;
+  readonly onCancel?: () => void;
+  readonly onReload?: () => void;
+  /** i18n-key für den Submit-Button. Default: "kumiko.actions.save".
+   *  Action-Forms (Tier 2.7d) übergeben hier ihren screen.submitLabel,
+   *  damit "Speichern" durch domain-spezifischere Strings ersetzt
+   *  werden kann ("Genehmigen" / "Versenden" / etc.). */
+  readonly submitLabel?: string;
+};
+
+function deriveFormFields<TValues extends FormValues, TCtx>(
+  screen: EntityEditScreenDefinition,
+): Record<string, FieldConditions<TValues, TCtx>> {
+  const out: Record<string, FieldConditions<TValues, TCtx>> = {};
+  for (const section of screen.layout.sections) {
+    for (const spec of section.fields) {
+      const normalized = normalizeEditField(spec);
+      out[normalized.field] = {
+        ...(normalized.visible !== undefined && {
+          visible: normalized.visible as FieldConditions<TValues, TCtx>["visible"],
+        }),
+        ...(normalized.readOnly !== undefined && {
+          readonly: normalized.readOnly as FieldConditions<TValues, TCtx>["readonly"],
+        }),
+        ...(normalized.required !== undefined && {
+          required: normalized.required as FieldConditions<TValues, TCtx>["required"],
+        }),
+      };
+    }
+  }
+  return out;
+}
+
+export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
+  props: RenderEditProps<TValues, TCtx>,
+): ReactNode {
+  const {
+    screen,
+    entity,
+    featureName,
+    initial,
+    writeCommand,
+    translate: translateProp,
+    ctx,
+    schema,
+    onSubmit,
+    payloadMode = "values",
+    buildPayload,
+    onDelete,
+    onCancel,
+    onReload,
+    submitLabel,
+  } = props;
+  const { customSubmit } = props;
+  // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
+  // konsumieren wir den i18next-Context direkt. Sonst wären Field-
+  // Labels ohne Caller-Wiring raw-Keys (`feature:entity:foo:field:title`).
+  // useTranslation throwt ohne LocaleProvider — das ist ok, weil RenderEdit
+  // ohnehin nur in einem mounted Kumiko-App-Tree läuft.
+  const t = useTranslation();
+  const translate = translateProp ?? t;
+
+  const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [formError, setFormError] = useState<DispatcherError | null>(null);
+  const { Button, Banner, Dialog, Form, Section, Grid, GridCell, Text } = usePrimitives();
+
+  const fields = useMemo(() => deriveFormFields<TValues, TCtx>(screen), [screen]);
+
+  // Submit-Config nur wenn der Caller einen writeCommand mitgibt; bei
+  // customSubmit-Pfad kommt der Form-Controller ohne Submit-Wiring,
+  // weil wir controller.submit() eh nicht rufen.
+  const submitConfig =
+    writeCommand !== undefined
+      ? {
+          type: writeCommand,
+          payloadMode,
+          ...(buildPayload !== undefined && { buildPayload }),
+        }
+      : undefined;
+
+  const { controller, snapshot } = useForm<TValues, TCtx>({
+    initial,
+    fields,
+    ...(schema !== undefined && { schema }),
+    ...(ctx !== undefined && { ctx }),
+    ...(submitConfig !== undefined && { submit: submitConfig }),
+  });
+
+  const vm = useMemo(
+    () =>
+      computeEditViewModel({
+        screen,
+        entity,
+        values: snapshot.values,
+        translate,
+        featureName,
+        ctx,
+      }),
+    [screen, entity, snapshot.values, translate, featureName, ctx],
+  );
+
+  async function handleSubmit(): Promise<void> {
+    setIsSubmitting(true);
+    try {
+      let result: SubmitResult<unknown>;
+      if (customSubmit !== undefined) {
+        // customSubmit-Pfad (z.B. configEdit, das pro Field einen
+        // separaten Write feuert). Erst client-side Validation, dann
+        // an den Caller; on-success rebased der Form-State explizit
+        // weil controller.submit() das normalerweise selbst macht und
+        // ohne customSubmit's Hilfe weiß der Controller nichts vom
+        // erfolgreichen Submit (isUnchanged blieb sonst false).
+        //
+        // WICHTIG: snapshot direkt vom Controller holen statt aus
+        // React-State. Bei rapid fill→click kann React-Batching die
+        // Input-State-Updates noch nicht commited haben, wenn der
+        // submit-Click fire'd. handleSubmit's Closure würde dann mit
+        // stale snapshot.changes={} laufen, customSubmit fired keine
+        // Writes, returnt success, Form rebase → User glaubt "saved"
+        // aber gar nichts ist passiert. controller.getSnapshot() ist
+        // immer aktuell — der Controller ist die Source-of-Truth, die
+        // React-State ist nur ein Mirror für's Rendering.
+        const valid = controller.validate();
+        if (!valid) {
+          // Field-Order matters: validationBlocked-true ist eine eigene
+          // Variante in der SubmitResult-Union (NICHT mit data/error
+          // gemixt), TS narrowt das nur ohne den Discriminator-Fight.
+          const blocked: SubmitResult<unknown> = {
+            validationBlocked: true,
+            isSuccess: false,
+          };
+          result = blocked;
+        } else {
+          result = await customSubmit(controller.getSnapshot());
+          if (result.isSuccess) controller.rebase();
+        }
+      } else {
+        result = await controller.submit();
+      }
+      // Form-level Errors (ohne field-level details) landen im Banner.
+      // Field-Errors fließen über snapshot.errors in die einzelnen Fields.
+      if (result.isSuccess) {
+        setFormError(null);
+      } else if (!result.validationBlocked) {
+        const fieldIssues = result.error.details?.fields ?? [];
+        setFormError(fieldIssues.length === 0 ? result.error : null);
+      }
+      onSubmit?.(result);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  // Sticky-top Action-Bar: Delete (links, destructive) + Cancel +
+  // Save. Delete sitzt links abgesetzt damit die Click-Distanz zu
+  // Save groß ist; rot + Confirm-Dialog sind ausreichend Schutz
+  // gegen Fehlklicks. Save bleibt rechts (primary affordance).
+  const formActions = (
+    <>
+      {onDelete !== undefined && (
+        <Button
+          type="button"
+          variant="danger"
+          testId="render-edit-delete"
+          onClick={() => setConfirmDeleteOpen(true)}
+        >
+          {translate("kumiko.actions.delete")}
+        </Button>
+      )}
+      {onCancel !== undefined && (
+        <Button
+          type="button"
+          variant="secondary"
+          onClick={() => onCancel()}
+          testId="render-edit-cancel"
+        >
+          {translate("kumiko.actions.cancel")}
+        </Button>
+      )}
+      <Button
+        type="submit"
+        disabled={snapshot.isUnchanged || isSubmitting}
+        loading={isSubmitting}
+        variant="primary"
+        testId="render-edit-submit"
+      >
+        {translate(submitLabel ?? "kumiko.actions.save")}
+      </Button>
+    </>
+  );
+
+  // Title-Resolution analog zu RenderList: i18n-Key `screen:<id>.title`,
+  // mit screenId als Fallback wenn das Bundle den Key nicht kennt.
+  const titleKey = `screen:${screen.id}.title`;
+  const resolvedTitle = translate(titleKey);
+  const formTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
+
+  return (
+    <Form
+      onSubmit={() => void handleSubmit()}
+      title={formTitle}
+      actions={formActions}
+      testId="render-edit-form"
+    >
+      {vm.sections.map((section) => (
+        <Section key={section.title} title={section.title} testId={`section-${section.title}`}>
+          <Grid columns={section.columns}>
+            {section.fields.map((field) => (
+              <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}
+              />
+            ))}
+          </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>
+  );
+}
+
+// Winziger Wrapper der die span-Logik kapselt und die Field-Cell in
+// die Grid platziert. Eigene Component damit die map-Callback oben
+// schlank bleibt.
+type GridCellForFieldProps = {
+  readonly field: EditFieldViewModel;
+  readonly columns: number;
+  readonly issues: readonly FieldIssue[] | undefined;
+  readonly onChange: (value: unknown) => void;
+  readonly GridCell: ReturnType<typeof usePrimitives>["GridCell"];
+  /** Tier 2.7e-3: durchgereicht damit Reference-Felder die richtige
+   *  Lookup-Query-QN bauen können (`<feature>:query:<refEntity>:list`). */
+  readonly featureName: string;
+};
+
+function GridCellForField({
+  field,
+  columns,
+  issues,
+  onChange,
+  GridCell,
+  featureName,
+}: GridCellForFieldProps): ReactNode {
+  const effectiveSpan = field.span !== undefined ? Math.min(field.span, columns) : 1;
+  return (
+    <GridCell span={effectiveSpan}>
+      <RenderField
+        field={field}
+        {...(issues !== undefined && { issues })}
+        onChange={onChange}
+        featureName={featureName}
+      />
+    </GridCell>
+  );
+}