@cosmicdrift/kumiko-renderer 0.239.0 → 0.241.0

package/src/app/row-actions.ts

@@ -0,0 +1,201 @@
+import type {
+  IconKey,
+  RowAction,
+  RowActionNavigate,
+  RowActionWriteHandler,
+  RowFieldExtractor,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
+import type { DataTableRowAction, DataTableRowActionMode } from "../primitives";
+import { shouldRenderActionsIconOnly } from "../primitives";
+import type { NavApi } from "./nav";
+import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
+
+export function evalRowExtractor(
+  extractor: RowFieldExtractor,
+  row: Record<string, unknown>,
+): Record<string, unknown> {
+  if ("pick" in extractor) {
+    return Object.fromEntries(extractor.pick.map((f) => [f, row[f]]));
+  }
+  return Object.fromEntries(Object.entries(extractor.map).map(([to, from]) => [to, row[from]]));
+}
+
+export function isWriteHandlerRowAction(action: RowAction): action is RowActionWriteHandler {
+  return action.kind === "writeHandler" || action.kind === undefined;
+}
+
+// Part B (fw-ui-defaults): id-derived default icon for actions that never
+// declared one — a screen author still gets a recognizable glyph instead of
+// a bare label. Checked against the actually registered IconKey vocabulary
+// (nav-icon.ts) — no entry for verbs without a matching icon (e.g. "start",
+// "pause").
+const ACTION_ICON_BY_ID: Readonly<Partial<Record<string, IconKey>>> = {
+  delete: "trash",
+  edit: "pencil",
+  create: "plus",
+  new: "plus",
+  add: "plus",
+  view: "eye",
+  open: "eye",
+  cancel: "x",
+  reject: "x",
+  complete: "check",
+  resolve: "check",
+  approve: "check",
+  archive: "archive",
+  publish: "upload",
+  duplicate: "copy",
+  copy: "copy",
+  download: "download",
+  refresh: "refresh",
+  retry: "refresh",
+  settings: "settings",
+  share: "share",
+  send: "send",
+};
+
+// Ids are kebab-case (RowAction.id doc) — a compound id whose full form has
+// no entry falls back to its last segment ("order-ship" -> "ship").
+function kebabLastSegment(id: string): string {
+  const idx = id.lastIndexOf("-");
+  return idx === -1 ? id : id.slice(idx + 1);
+}
+
+// Resolution order: author-declared `icon` wins, then the id-derived
+// default (full id, then its last kebab segment). `declared` is `undefined`
+// for ToolbarAction, which has no author-facing icon field.
+export function resolveActionIcon(id: string, declared?: IconKey): IconKey | undefined {
+  if (declared !== undefined) return declared;
+  return ACTION_ICON_BY_ID[id] ?? ACTION_ICON_BY_ID[kebabLastSegment(id)];
+}
+
+// Row-action column mode for a resolved action set: a group where every
+// member carries an icon renders inline so `shouldRenderActionsIconOnly`
+// can collapse it to icon-only buttons (fw#2580). Anything else keeps the
+// DataTable's adaptive default (kebab past two actions) — inline text
+// buttons for an icon-less group are the very thing the collapse avoids.
+export function rowActionModeFor(
+  actions: readonly DataTableRowAction[] | undefined,
+): DataTableRowActionMode | undefined {
+  if (actions === undefined || !shouldRenderActionsIconOnly(actions)) return undefined;
+  return "inline";
+}
+
+export function stringifyNavParams(params: Record<string, unknown>): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const [k, v] of Object.entries(params)) {
+    out[k] =
+      v === null || v === undefined ? null : Array.isArray(v) ? JSON.stringify(v) : String(v);
+  }
+  return out;
+}
+
+export async function refetchAfterWrite(refetch: () => Promise<unknown>): Promise<void> {
+  await refetch().catch((err: unknown) => {
+    // biome-ignore lint/suspicious/noConsole: refetch must not poison the write-action error path
+    console.error("kumiko-screen: refetch after write action failed", err);
+  });
+}
+
+// Navigate execution for query-driven rows (projectionList, and relatedList
+// — both have no guaranteed "id" field, unlike entityList's rows which back
+// a real entity). No same-entity row["id"] fallback (see EntityListBody's
+// own runNavigate for that variant, which stays separate — entityList's
+// fallback needs `screen.entity`, which neither projectionList nor
+// relatedList has).
+export function runProjectionRowNavigate(
+  nav: NavApi,
+  action: RowActionNavigate,
+  row: ListRowViewModel,
+): void {
+  if (action.entity !== undefined) {
+    const id = action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : "";
+    // skip: no entityId column on this row — nothing to navigate to.
+    if (id === "") return;
+    nav.navigate({ entity: action.entity, id });
+  } else if (action.screen !== undefined) {
+    const entityId =
+      action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
+    nav.navigate({
+      screenId: action.screen,
+      ...(entityId !== undefined && entityId !== "" && { entityId }),
+    });
+  } else {
+    // skip: neither entity nor screen set — the boot-validator rejects this
+    // shape (resolveRowActionNavigateTarget), so this only guards types.
+    return;
+  }
+  const params =
+    action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
+  if (params !== undefined) {
+    nav.setSearchParams(stringifyNavParams(params));
+  }
+}
+
+// Builds the DataTable-ready row-action set for a query-driven row source
+// (projectionList, relatedList) — navigate dispatches through
+// runProjectionRowNavigate, writeHandler dispatches through the shared
+// Dispatcher and refetches `refetch` on success. Single implementation so
+// projectionList's rowActions and a projectionDetail relatedList section's
+// rowActions can't drift apart (fw editable-detail-screens).
+export function buildProjectionRowActions(options: {
+  readonly rowActions: readonly RowAction[] | undefined;
+  readonly translate: Translate;
+  readonly dispatcher: Dispatcher | undefined;
+  readonly nav: NavApi;
+  readonly refetch: () => Promise<unknown>;
+}): readonly DataTableRowAction[] | undefined {
+  const { rowActions, translate, dispatcher, nav, refetch } = options;
+  if (rowActions === undefined) return undefined;
+  const out: DataTableRowAction[] = [];
+  for (const action of rowActions) {
+    if (action.kind === "navigate") {
+      const navigateAction = action;
+      const visible = action.visible;
+      const actionIcon = resolveActionIcon(action.id, action.icon);
+      out.push({
+        id: action.id,
+        label: translate(action.label),
+        ...(action.style !== undefined && { style: action.style }),
+        ...(actionIcon !== undefined && { icon: actionIcon }),
+        onTrigger: (row: ListRowViewModel) => runProjectionRowNavigate(nav, navigateAction, row),
+        ...(visible !== undefined && {
+          isVisible: (row: ListRowViewModel) => evalFieldCondition(visible, row.values),
+        }),
+      });
+      continue;
+    }
+    // writeHandler (default-kind) — a swallowed failure result must become a
+    // thrown error (fw prod-bug 2026-06-07), same as every other write path.
+    if (dispatcher === undefined) continue;
+    const writeAction = action;
+    const writeVisible = writeAction.visible;
+    out.push({
+      id: writeAction.id,
+      label: translate(writeAction.label),
+      ...(writeAction.style !== undefined && { style: writeAction.style }),
+      icon: resolveActionIcon(writeAction.id, writeAction.icon),
+      ...(writeAction.confirm !== undefined && { confirm: translate(writeAction.confirm) }),
+      ...(writeAction.confirmLabel !== undefined && {
+        confirmLabel: translate(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, translate));
+        }
+        await refetchAfterWrite(refetch);
+      },
+      ...(writeVisible !== undefined && {
+        isVisible: (row: ListRowViewModel) => evalFieldCondition(writeVisible, row.values),
+      }),
+    });
+  }
+  return out.length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,163 @@
+import { describe, expect, test } from "bun:test";
+import type { RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, EditRelatedListSectionViewModel } from "@cosmicdrift/kumiko-headless";
+import { render, screen as rtlScreen, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { NavProvider } from "../../app/nav";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type CorePrimitives,
+  type DataTableProps,
+  PrimitivesProvider,
+  type SectionProps,
+} from "../../primitives";
+import { RelatedListSection } from "../related-list-section";
+
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+const noop = () => {};
+
+const testSection: ComponentType<SectionProps> = ({ testId, children }) => (
+  <div data-testid={testId}>{children}</div>
+);
+
+// A minimal DataTable stub: renders one button per row per row-action,
+// wired straight to the action's onTrigger — enough to prove
+// RelatedListSection wires rowActions through to a real dispatch, without
+// needing the production DataTable's sorting/paging/kebab-menu chrome.
+const testDataTable: ComponentType<DataTableProps> = ({ rows, rowActions }) => (
+  <table>
+    <tbody>
+      {rows.map((row) => (
+        <tr key={row.id} data-testid={`row-${row.id}`}>
+          <td>
+            {(rowActions ?? []).map((action) => (
+              <button
+                key={action.id}
+                type="button"
+                data-testid={`action-${action.id}-${row.id}`}
+                onClick={() => void action.onTrigger(row)}
+              >
+                {action.label}
+              </button>
+            ))}
+          </td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+);
+
+function testPrimitives(): CorePrimitives {
+  return {
+    Button: noop,
+    Banner: ({ children, testId }: { children?: ReactNode; testId?: string }) => (
+      <div data-testid={testId}>{children}</div>
+    ),
+    Field: passChildren,
+    Input: noop,
+    DataTable: testDataTable,
+    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(): {
+  dispatcher: Dispatcher;
+  writes: Array<{ type: string; payload: unknown }>;
+  queryCount: () => number;
+} {
+  const writes: Array<{ type: string; payload: unknown }> = [];
+  let queryCalls = 0;
+  const dispatcher: Dispatcher = {
+    write: (async (type, payload) => {
+      writes.push({ type, payload });
+      return { isSuccess: true, data: null };
+    }) as Dispatcher["write"],
+    query: (async () => {
+      queryCalls += 1;
+      return {
+        isSuccess: true,
+        data: { rows: [{ id: "r1", name: "Alice" }], nextCursor: null },
+      };
+    }) 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, queryCount: () => queryCalls };
+}
+
+const rowActions: readonly RowAction[] = [
+  {
+    id: "resend",
+    label: "actions.resend",
+    handler: "orders:write:resend",
+    payload: { pick: ["id"] },
+  },
+];
+
+const historySection: EditRelatedListSectionViewModel = {
+  kind: "relatedList",
+  title: "History",
+  query: "orders:query:notifications:list",
+  columns: [{ field: "name" }],
+  rowActions,
+};
+
+function renderRelatedList(dispatcher: Dispatcher) {
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={dispatcher}>
+        <PrimitivesProvider value={testPrimitives()}>
+          <NavProvider
+            value={{
+              route: undefined,
+              navigate: noop,
+              replace: noop,
+              hrefFor: () => "#",
+              searchParams: {},
+              setSearchParams: noop,
+            }}
+          >
+            <RelatedListSection section={historySection} parentId="order-1" featureName="orders" />
+          </NavProvider>
+        </PrimitivesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RelatedListSection — rowActions", () => {
+  test("clicking a row action dispatches through the configured write-handler with the extracted payload, then refetches", async () => {
+    const { dispatcher, writes, queryCount } = stubDispatcher();
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    rtlScreen.getByTestId("action-resend-r1").click();
+
+    await waitFor(() => expect(writes).toHaveLength(1));
+    expect(writes[0]).toEqual({ type: "orders:write:resend", payload: { id: "r1" } });
+    await waitFor(() => expect(queryCount()).toBe(2));
+  });
+});

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

@@ -123,6 +123,20 @@ describe("hasEditableSection", () => {
     expect(hasEditableSection([])).toBe(false);
   });
 
+  // writeForm owns its own submit button (write-form-section-submit) —
+  // counting it here would additionally render the screen-level Save button
+  // (render-edit-submit) on a projectionDetail, which has no form submit to
+  // wire it to.
+  test("writeForm section → false (has its own submit, not the screen's)", () => {
+    const writeFormSection: EditSectionViewModel = {
+      kind: "writeForm",
+      columns: 1,
+      handler: "orders:write:add-note",
+      fields: [field(false)],
+    };
+    expect(hasEditableSection([writeFormSection])).toBe(false);
+  });
+
   test("hidden section with editable field → false (user cannot see the field)", () => {
     const hiddenSectionWithEditableField: EditSectionViewModel = {
       kind: "fields",

package/src/components/__tests__/render-field-json-format.test.tsx

@@ -0,0 +1,164 @@
+// fw#2312: readOnly fields with `field.renderer: { format: "json" }` (audit
+// payload/metadata, job logs) must hand the RAW value to a registered
+// JsonView primitive — applyFormatSpec's already-indented string is only
+// the fallback for a primitives-provider without JsonView (e.g. an app
+// predating this rollout). "children contains \n" is not a discriminating
+// assertion here (applyFormatSpec already returns a real newline string
+// today) — the test instead checks that JsonView is actually invoked and
+// receives the structured value, not a flattened string.
+//
+// Capture-primitives instead of real ones, same pattern as
+// render-field-unit-format.test.tsx.
+
+import { describe, expect, test } from "bun:test";
+import type { EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import {
+  type CorePrimitives,
+  type JsonViewProps,
+  PrimitivesProvider,
+  type TextProps,
+} from "../../primitives";
+import { RenderField } from "../render-field";
+
+let capturedJsonView: JsonViewProps | undefined;
+const captureJsonView: ComponentType<JsonViewProps> = (props) => {
+  capturedJsonView = props;
+  return null;
+};
+
+let capturedText: TextProps | undefined;
+const captureText: ComponentType<TextProps> = (props) => {
+  capturedText = props;
+  return null;
+};
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const basePrimitives: Omit<CorePrimitives, "Text" | "JsonView"> = {
+  Button: noop,
+  // Passes children through (not noop): the "unsupported jsonb" fallback
+  // path wraps its Text/JsonView content in <Banner>, so a Banner that
+  // swallows children would silently never mount them, making those
+  // captures a no-op regardless of which branch RenderField actually took.
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: noop,
+  Section: noop,
+  Card: noop,
+  Grid: noop,
+  GridCell: noop,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+const primitivesWithJsonView: CorePrimitives = {
+  ...basePrimitives,
+  Text: captureText,
+  JsonView: captureJsonView,
+};
+
+const primitivesWithoutJsonView: CorePrimitives = {
+  ...basePrimitives,
+  Text: captureText,
+};
+
+function payloadField(
+  value: unknown,
+  renderer: EditFieldViewModel["renderer"] = { format: "json" },
+): EditFieldViewModel {
+  return {
+    field: "payload",
+    label: "Payload",
+    type: "jsonb",
+    value,
+    visible: true,
+    readOnly: true,
+    required: false,
+    renderer,
+  };
+}
+
+// No `renderer` key at all (not even `renderer: undefined`, which a default
+// parameter would still override) — this is the "no author-declared
+// FieldRenderer" case that falls through to renderInput's jsonb/embedded/
+// files/images fallback banner instead of FieldRendererOutput.
+function unrenderedJsonbField(value: unknown): EditFieldViewModel {
+  return {
+    field: "payload",
+    label: "Payload",
+    type: "jsonb",
+    value,
+    visible: true,
+    readOnly: true,
+    required: false,
+  };
+}
+
+function renderPayload(primitives: CorePrimitives, field: EditFieldViewModel): void {
+  capturedJsonView = undefined;
+  capturedText = undefined;
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "en-US" })}>
+      <PrimitivesProvider value={primitives}>
+        <RenderField field={field} onChange={() => {}} />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderField — format: json (fw#2312)", () => {
+  test("mit registriertem JsonView bekommt es den rohen, strukturierten Wert — keinen flachen String", () => {
+    const value = { user: { id: 1, roles: ["admin", "billing"] } };
+    renderPayload(primitivesWithJsonView, payloadField(value));
+    expect(capturedJsonView?.value).toBe(value);
+    expect(typeof capturedJsonView?.value).toBe("object");
+    expect(capturedText).toBeUndefined();
+  });
+
+  test("renderer.indent wird an JsonView durchgereicht", () => {
+    renderPayload(primitivesWithJsonView, payloadField({ a: 1 }, { format: "json", indent: 4 }));
+    expect(capturedJsonView?.indent).toBe(4);
+  });
+
+  test("ohne registriertes JsonView fällt es auf Text mit dem von applyFormatSpec formatierten String zurück", () => {
+    const value = { a: 1 };
+    renderPayload(primitivesWithoutJsonView, payloadField(value));
+    expect(capturedJsonView).toBeUndefined();
+    expect(capturedText?.children).toBe(JSON.stringify(value, null, 2));
+  });
+
+  test("ein zirkulärer Wert erreicht JsonView unverändert — die Aufbereitung ist Sache der Primitive-Implementierung, nicht von RenderField", () => {
+    const circular: Record<string, unknown> = { name: "job-1" };
+    circular["self"] = circular;
+    expect(() => renderPayload(primitivesWithJsonView, payloadField(circular))).not.toThrow();
+    expect(capturedJsonView?.value).toBe(circular);
+  });
+});
+
+describe("RenderField — unsupported jsonb/embedded/files/images Fallback-Banner (fw#2312)", () => {
+  test("mit registriertem JsonView zeigt der Banner den Wert strukturiert statt als JSON.stringify-Einzeiler", () => {
+    const value = { assignee: "user-1", tags: ["a", "b"] };
+    renderPayload(primitivesWithJsonView, unrenderedJsonbField(value));
+    expect(capturedJsonView?.value).toBe(value);
+    expect(capturedText).toBeUndefined();
+  });
+
+  test("ohne registriertes JsonView fällt der Banner auf Text variant=code mit dem alten Einzeiler zurück", () => {
+    const value = { assignee: "user-1" };
+    renderPayload(primitivesWithoutJsonView, unrenderedJsonbField(value));
+    expect(capturedJsonView).toBeUndefined();
+    expect(capturedText?.children).toBe(JSON.stringify(value));
+    expect(capturedText?.variant).toBe("code");
+  });
+});