@cosmicdrift/kumiko-renderer 0.239.0 → 0.241.0

package/src/components/__tests__/write-form-section.test.tsx

@@ -0,0 +1,225 @@
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher, EditWriteFormSectionViewModel } from "@cosmicdrift/kumiko-headless";
+import { fireEvent, render, screen as rtlScreen, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type BannerProps,
+  type ButtonProps,
+  type CorePrimitives,
+  PrimitivesProvider,
+  type SectionProps,
+} from "../../primitives";
+import { WriteFormSection } from "../write-form-section";
+
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+const noop = () => {};
+
+const testButton: ComponentType<ButtonProps> = ({ children, onClick, testId, disabled, icon }) => (
+  <button type="button" data-testid={testId} data-icon={icon} onClick={onClick} disabled={disabled}>
+    {children}
+  </button>
+);
+
+const testInput: ComponentType<{
+  name?: string;
+  value?: unknown;
+  onChange?: (v: unknown) => void;
+}> = ({ name = "field", value, onChange }) => (
+  <input
+    aria-label={name}
+    data-testid={`input-${name}`}
+    value={typeof value === "string" ? value : ""}
+    onChange={(e) => onChange?.(e.target.value)}
+  />
+);
+
+const testBanner: ComponentType<BannerProps> = ({ children, testId }) => (
+  <div data-testid={testId}>{children}</div>
+);
+
+// Mirrors DefaultSection's real actions slot closely enough to let tests
+// assert the submit button lands in the footer, not the body (fw#2675).
+const testSection: ComponentType<SectionProps> = ({ testId, children, actions }) => (
+  <div data-testid={testId}>
+    <div data-testid={testId !== undefined ? `${testId}-body` : undefined}>{children}</div>
+    {actions !== undefined && (
+      <div data-testid={testId !== undefined ? `${testId}-actions` : undefined}>{actions}</div>
+    )}
+  </div>
+);
+
+function testPrimitives(): CorePrimitives {
+  return {
+    Button: testButton,
+    Banner: testBanner,
+    Field: passChildren,
+    Input: testInput,
+    DataTable: noop,
+    Form: noop,
+    Section: testSection,
+    Card: passChildren,
+    Grid: passChildren,
+    GridCell: passChildren,
+    Text: noop,
+    Heading: noop,
+    Dialog: noop,
+    Modal: noop,
+    Lightbox: noop,
+    ConfigSourceBadge: noop,
+    ConfigCascadeView: noop,
+    Link: noop,
+  } as unknown as CorePrimitives;
+}
+
+function stubDispatcher(writeImpl?: Dispatcher["write"]): {
+  dispatcher: Dispatcher;
+  writes: Array<{ type: string; payload: unknown }>;
+} {
+  const writes: Array<{ type: string; payload: unknown }> = [];
+  const dispatcher: Dispatcher = {
+    write: (async (type, payload) => {
+      writes.push({ type, payload });
+      if (writeImpl) return writeImpl(type, payload);
+      return { isSuccess: true, data: { id: "n1" } };
+    }) as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: {} })) as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+  return { dispatcher, writes };
+}
+
+const noteSection: EditWriteFormSectionViewModel = {
+  kind: "writeForm",
+  title: "Add note",
+  columns: 1,
+  handler: "orders:write:add-note",
+  fields: [
+    {
+      field: "note",
+      label: "Note",
+      type: "text",
+      value: "",
+      visible: true,
+      readOnly: false,
+      required: true,
+    },
+  ],
+};
+
+function renderWriteForm(
+  section: EditWriteFormSectionViewModel,
+  dispatcher: Dispatcher,
+  onSubmitted: () => void,
+) {
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={dispatcher}>
+        <PrimitivesProvider value={testPrimitives()}>
+          <WriteFormSection section={section} featureName="orders" onSubmitted={onSubmitted} />
+        </PrimitivesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("WriteFormSection", () => {
+  test("submit button renders in the section's actions footer, not the body (fw#2675)", () => {
+    const { dispatcher } = stubDispatcher();
+    renderWriteForm(noteSection, dispatcher, noop);
+
+    const actions = rtlScreen.getByTestId("write-form-Add note-actions");
+    const body = rtlScreen.getByTestId("write-form-Add note-body");
+    const button = rtlScreen.getByTestId("write-form-section-submit");
+
+    expect(actions.contains(button)).toBe(true);
+    expect(body.contains(button)).toBe(false);
+    expect(button.dataset["icon"]).toBe("check");
+  });
+
+  test("submit dispatches through the section's configured write handler with the entered values", async () => {
+    const { dispatcher, writes } = stubDispatcher();
+    let submittedCount = 0;
+    renderWriteForm(noteSection, dispatcher, () => {
+      submittedCount += 1;
+    });
+
+    fireEvent.change(rtlScreen.getByLabelText("note"), { target: { value: "Called back" } });
+    fireEvent.click(rtlScreen.getByTestId("write-form-section-submit"));
+
+    await waitFor(() => expect(submittedCount).toBe(1));
+    expect(writes).toEqual([{ type: "orders:write:add-note", payload: { note: "Called back" } }]);
+  });
+
+  test("a failed write surfaces the error banner and does not call onSubmitted", async () => {
+    const { dispatcher } = stubDispatcher(async () => ({
+      isSuccess: false,
+      error: { code: "conflict", httpStatus: 409, i18nKey: "errors.conflict", message: "conflict" },
+    }));
+    let submittedCount = 0;
+    renderWriteForm(noteSection, dispatcher, () => {
+      submittedCount += 1;
+    });
+
+    fireEvent.change(rtlScreen.getByLabelText("note"), { target: { value: "x" } });
+    fireEvent.click(rtlScreen.getByTestId("write-form-section-submit"));
+
+    await waitFor(() => expect(rtlScreen.getByTestId("write-form-section-error")).toBeTruthy());
+    expect(submittedCount).toBe(0);
+  });
+
+  test("submit is blocked by schema validation when a required field is left empty", async () => {
+    const { dispatcher, writes } = stubDispatcher();
+    renderWriteForm(noteSection, dispatcher, () => {
+      throw new Error("must not submit while required field is empty");
+    });
+
+    fireEvent.click(rtlScreen.getByTestId("write-form-section-submit"));
+
+    await waitFor(() => expect(writes).toHaveLength(0));
+  });
+
+  // Pins the only route a writeForm section has to thread the host record's
+  // id into its payload (see EditWriteFormSection.handler's doc): a
+  // visible:false field never renders an input, but its resolved value still
+  // seeds `initial` and so rides along in the submit payload untouched.
+  test("a visible:false field's prefilled value rides along in the submit payload", async () => {
+    const sectionWithHiddenId: EditWriteFormSectionViewModel = {
+      ...noteSection,
+      fields: [
+        {
+          field: "orderId",
+          label: "Order",
+          type: "text",
+          value: "order-42",
+          visible: false,
+          readOnly: false,
+          required: false,
+        },
+        ...noteSection.fields,
+      ],
+    };
+    const { dispatcher, writes } = stubDispatcher();
+    renderWriteForm(sectionWithHiddenId, dispatcher, noop);
+
+    expect(rtlScreen.queryByTestId("input-orderId")).toBeNull();
+
+    fireEvent.change(rtlScreen.getByLabelText("note"), { target: { value: "hi" } });
+    fireEvent.click(rtlScreen.getByTestId("write-form-section-submit"));
+
+    await waitFor(() => expect(writes).toHaveLength(1));
+    expect(writes[0]?.payload).toEqual({ orderId: "order-42", note: "hi" });
+  });
+});

package/src/components/grid-cell-for-field.tsx

@@ -0,0 +1,60 @@
+import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
+import type { ReactNode } from "react";
+import type { usePrimitives } from "../primitives";
+import { RenderField } from "./render-field";
+
+// Extracted out of render-edit.tsx so write-form-section.tsx can reuse it
+// without a circular import between the two components.
+export 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: passed through so Reference fields can build the correct
+   *  lookup query QN (`<feature>:query:<refEntity>:list`). */
+  readonly featureName: string;
+  readonly labelAppendix?: ReactNode;
+  readonly fieldAppendix?: ReactNode;
+  /** Full issues-by-path map (FormSnapshot.errors) — passed through for
+   *  embedded-list fields, which bucket row-/cell-level issues themselves. */
+  readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
+  /** Passed through to RenderField unchanged — see RenderEditProps.valueDisplay. */
+  readonly valueDisplay: "form" | "text";
+  /** Passed through to RenderField as `row` — see RenderFieldProps.row. */
+  readonly row: Readonly<Record<string, unknown>>;
+};
+
+export function GridCellForField({
+  field,
+  columns,
+  issues,
+  onChange,
+  GridCell,
+  featureName,
+  labelAppendix,
+  fieldAppendix,
+  allIssues,
+  valueDisplay,
+  row,
+}: GridCellForFieldProps): ReactNode {
+  // RenderField renders nothing for a hidden field, but the GridCell around it still claims the row.
+  if (!field.visible) return null;
+
+  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}
+        {...(labelAppendix !== undefined && { labelAppendix })}
+        {...(fieldAppendix !== undefined && { fieldAppendix })}
+        allIssues={allIssues}
+        valueDisplay={valueDisplay}
+        row={row}
+      />
+    </GridCell>
+  );
+}

package/src/components/related-list-section.tsx

@@ -1,6 +1,7 @@
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
+  RowActionNavigate,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
@@ -10,7 +11,13 @@ import type {
 } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useMemo } from "react";
 import { useNav } from "../app/nav";
+import {
+  buildProjectionRowActions,
+  rowActionModeFor,
+  runProjectionRowNavigate,
+} from "../app/row-actions";
 import { dispatcherErrorText } from "../app/write-failed-error";
+import { useOptionalDispatcher } from "../context/dispatcher-context";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
@@ -57,6 +64,7 @@ export function RelatedListSection({
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
+  const dispatcher = useOptionalDispatcher();
 
   const entity = useMemo(() => synthesizeRelatedListEntity(section.columns), [section.columns]);
   const listScreen = useMemo(
@@ -84,6 +92,12 @@ export function RelatedListSection({
   const rowsQuery = useQuery<PagedRows>(section.query, payload);
 
   const rowClick = section.rowClick;
+  // A row-body click target comes from EITHER the legacy `rowClick` field OR
+  // a `rowActions` entry marked rowClick:true — the boot-validator rejects
+  // both being set, so this order is just a fallback, not a precedence rule.
+  const rowClickAction = section.rowActions?.find(
+    (a): a is RowActionNavigate => a.kind === "navigate" && a.rowClick === true,
+  );
   const onRowClick =
     rowClick !== undefined
       ? (row: ListRowViewModel) => {
@@ -91,7 +105,26 @@ export function RelatedListSection({
           if (id === "") return;
           nav.navigate({ entity: rowClick.entity, id });
         }
-      : undefined;
+      : rowClickAction !== undefined
+        ? (row: ListRowViewModel) => runProjectionRowNavigate(nav, rowClickAction, row)
+        : undefined;
+
+  // Same execution path as projectionList's rowActions (kumiko-screen.tsx) —
+  // a relatedList row has the identical "no guaranteed id field" shape a
+  // query-projection row has, so navigate/writeHandler dispatch is shared
+  // rather than a second implementation (fw editable-detail-screens).
+  const rowActions = useMemo(
+    () =>
+      buildProjectionRowActions({
+        rowActions: section.rowActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: rowsQuery.refetch,
+      }),
+    [section.rowActions, effectiveTranslate, dispatcher, nav, rowsQuery.refetch],
+  );
+  const rowActionMode = rowActionModeFor(rowActions);
 
   const content =
     rowsQuery.loading && rowsQuery.data === null ? (
@@ -110,6 +143,8 @@ export function RelatedListSection({
         featureName={featureName}
         translate={effectiveTranslate}
         {...(onRowClick !== undefined && { onRowClick })}
+        {...(rowActions !== undefined && { rowActions })}
+        {...(rowActionMode !== undefined && { rowActionMode })}
       />
     );
 

package/src/components/render-edit-logic.ts

@@ -41,9 +41,10 @@ export function shouldNotifyCaller(
   return !(result.isSuccess && !extensionsPersisted);
 }
 
-// Extension and relatedList sections skip the `fields` filter (neither has a
-// `field`-name set that filtering applies to); a `fields` section left with
-// zero fields after filtering is dropped, not rendered empty.
+// Extension, relatedList and writeForm sections skip the `fields` filter
+// (writeForm's fields belong to its own independent form, not the host's);
+// a `fields` section left with zero fields after filtering is dropped, not
+// rendered empty.
 export function filterEditSections(
   sections: readonly EditSectionViewModel[],
   fieldsFilter: readonly string[] | undefined,
@@ -52,7 +53,11 @@ export function filterEditSections(
   const filterSet = new Set(fieldsFilter);
   const result: EditSectionViewModel[] = [];
   for (const section of sections) {
-    if (section.kind === "extension" || section.kind === "relatedList") {
+    if (
+      section.kind === "extension" ||
+      section.kind === "relatedList" ||
+      section.kind === "writeForm"
+    ) {
       result.push(section);
       continue;
     }

package/src/components/render-edit.tsx

@@ -13,7 +13,6 @@ import type {
   EditFieldViewModel,
   EditSectionViewModel,
   FieldConditions,
-  FieldIssue,
   FormValues,
   SubmitResult,
 } from "@cosmicdrift/kumiko-headless";
@@ -37,6 +36,7 @@ import { formatWhen } from "../format-when";
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
 import { shouldRenderActionsIconOnly, usePrimitives } from "../primitives";
+import { GridCellForField } from "./grid-cell-for-field";
 import { RelatedListSection } from "./related-list-section";
 import {
   filterEditSections,
@@ -44,7 +44,7 @@ import {
   resolveExtensionEntityId,
   shouldNotifyCaller,
 } from "./render-edit-logic";
-import { RenderField } from "./render-field";
+import { WriteFormSection } from "./write-form-section";
 
 // Qualified names of the bundled `form-draft` feature. Hardcoded because the
 // renderer must not depend on @cosmicdrift/kumiko-bundled-features; a screen
@@ -606,17 +606,18 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const filteredSections = useMemo(
     // A fully-hidden "fields" section (every field in it currently
     // condition-hidden) must not occupy a wizard step; it would render
-    // empty and block Back/Next on nothing. Extension and relatedList
-    // sections carry no `visible` (they own their own lifecycle / run
-    // their own query), so they always pass through. A section with no
-    // fields at all (e.g. a review-only step) has `visible: fields.some(...)`
-    // = false vacuously; that's "no fields to hide", not "hidden", so it
-    // stays too (fw#1901).
+    // empty and block Back/Next on nothing. Extension, relatedList and
+    // writeForm sections carry no `visible` (they own their own lifecycle /
+    // run their own query / own submit), so they always pass through. A
+    // section with no fields at all (e.g. a review-only step) has
+    // `visible: fields.some(...)` = false vacuously; that's "no fields to
+    // hide", not "hidden", so it stays too (fw#1901).
     () =>
       filterEditSections(vm.sections, fieldsFilter).filter(
         (section) =>
           section.kind === "extension" ||
           section.kind === "relatedList" ||
+          section.kind === "writeForm" ||
           section.fields.length === 0 ||
           section.visible,
       ),
@@ -1211,6 +1212,21 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               />
             );
           }
+          if (section.kind === "writeForm") {
+            // Own submit button + dispatcher call, entirely independent of
+            // this screen's (nonexistent, on projectionDetail) form submit —
+            // rejected at boot in wizard layouts, so no WizardStepGroup here.
+            return (
+              <WriteFormSection
+                key={section.title ?? `write-form-${sectionIndex}`}
+                section={section}
+                featureName={featureName}
+                translate={translate}
+                hideTitle={hideSectionTitles}
+                onSubmitted={() => onReload?.()}
+              />
+            );
+          }
           if (!section.visible) return null;
           // Section-Header unterdrücken wenn er den Form-Titel der
           // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-
@@ -1307,60 +1323,3 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     </ExtensionFormRegistryProvider>
   );
 }
-
-// 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;
-  readonly labelAppendix?: ReactNode;
-  readonly fieldAppendix?: ReactNode;
-  /** Full issues-by-path map (FormSnapshot.errors) — passed through for
-   *  embedded-list fields, which bucket row-/cell-level issues themselves. */
-  readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
-  /** Passed through to RenderField unchanged — see RenderEditProps.valueDisplay. */
-  readonly valueDisplay: "form" | "text";
-  /** Passed through to RenderField as `row` — see RenderFieldProps.row. */
-  readonly row: Readonly<Record<string, unknown>>;
-};
-
-function GridCellForField({
-  field,
-  columns,
-  issues,
-  onChange,
-  GridCell,
-  featureName,
-  labelAppendix,
-  fieldAppendix,
-  allIssues,
-  valueDisplay,
-  row,
-}: GridCellForFieldProps): ReactNode {
-  // RenderField renders nothing for a hidden field, but the GridCell around it still claims the row.
-  if (!field.visible) return null;
-
-  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}
-        {...(labelAppendix !== undefined && { labelAppendix })}
-        {...(fieldAppendix !== undefined && { fieldAppendix })}
-        allIssues={allIssues}
-        valueDisplay={valueDisplay}
-        row={row}
-      />
-    </GridCell>
-  );
-}

package/src/components/render-field.tsx

@@ -83,7 +83,7 @@ export function RenderField({
   valueDisplay = "form",
   row,
 }: RenderFieldProps): ReactNode {
-  const { Field, Input, Banner, Text } = usePrimitives();
+  const { Field, Input, Banner, Text, JsonView } = 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. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
@@ -137,7 +137,19 @@ export function RenderField({
     ) : readOnlyText && !isComplexFieldType(field.type) ? (
       <Text testId={`field-value-${field.field}`}>{readOnlyDisplayText(field, appLocale)}</Text>
     ) : (
-      renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, t, row })
+      renderInput({
+        field,
+        id,
+        hasError,
+        onChange,
+        Input,
+        appLocale,
+        Banner,
+        Text,
+        JsonView,
+        t,
+        row,
+      })
     );
 
   return (
@@ -351,7 +363,7 @@ function FieldRendererOutput({
   readonly row?: Readonly<Record<string, unknown>>;
   readonly appLocale: string;
 }): ReactNode {
-  const { Text } = usePrimitives();
+  const { Text, JsonView } = usePrimitives();
   const t = useTranslation();
   const componentName =
     !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
@@ -359,6 +371,18 @@ function FieldRendererOutput({
       : undefined;
   const Component = useColumnRenderer(componentName);
   if (isFormatSpec(renderer)) {
+    // format:"json" wants the raw value (JsonView stringifies + highlights
+    // itself) — applyFormatSpec's already-indented string is only the
+    // fallback for primitives-providers without JsonView (fw#2312).
+    if (renderer.format === "json" && JsonView !== undefined) {
+      return (
+        <JsonView
+          value={field.value}
+          indent={renderer.indent}
+          testId={`field-value-${field.field}`}
+        />
+      );
+    }
     // App locale as default when the FormatSpec declares none of its own —
     // otherwise locale-sensitive formats (timestamp/date/number/decimal/
     // bigInt/unit) fell back to Intl's runtime default instead of the app
@@ -495,6 +519,7 @@ function renderInput({
   appLocale,
   Banner,
   Text,
+  JsonView,
   t,
   row,
 }: {
@@ -506,6 +531,7 @@ function renderInput({
   readonly appLocale: string;
   readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
   readonly Text: ReturnType<typeof usePrimitives>["Text"];
+  readonly JsonView: ReturnType<typeof usePrimitives>["JsonView"];
   readonly t: ReturnType<typeof useTranslation>;
   readonly row?: Readonly<Record<string, unknown>>;
 }): ReactNode {
@@ -710,7 +736,12 @@ function renderInput({
       return (
         <Banner id={id} variant="info">
           {t("kumiko.field.unsupported")}
-          {hasValue && <Text variant="code">{JSON.stringify(field.value)}</Text>}
+          {hasValue &&
+            (JsonView !== undefined ? (
+              <JsonView value={field.value} testId={`field-value-${field.field}`} />
+            ) : (
+              <Text variant="code">{JSON.stringify(field.value)}</Text>
+            ))}
         </Banner>
       );
     }