@cosmicdrift/kumiko-renderer 0.309.0 → 0.310.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.309.0",
+  "version": "0.310.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,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.309.0",
-    "@cosmicdrift/kumiko-headless": "0.309.0",
-    "@cosmicdrift/kumiko-types": "0.309.0",
+    "@cosmicdrift/kumiko-framework": "0.310.0",
+    "@cosmicdrift/kumiko-headless": "0.310.0",
+    "@cosmicdrift/kumiko-types": "0.310.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.309.0"
+    "@cosmicdrift/kumiko-locale-de": "0.310.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/row-actions-navigate-tab.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import type { RowActionNavigate } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { NavApi, NavTarget } from "../nav";
+import { RETURN_TO_PARAM, type ReturnHost } from "../return-to";
+import { buildRecordActions } from "../row-actions";
+
+function recordingNav(): {
+  readonly nav: NavApi;
+  readonly navigateCalls: NavTarget[];
+  readonly setSearchParamsCalls: ReadonlyArray<Readonly<Record<string, string | null>>>;
+} {
+  const navigateCalls: NavTarget[] = [];
+  const setSearchParamsCalls: Array<Readonly<Record<string, string | null>>> = [];
+  const nav: NavApi = {
+    route: undefined,
+    navigate: (target) => navigateCalls.push(target),
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: (updates) => setSearchParamsCalls.push(updates),
+  };
+  return { nav, navigateCalls, setSearchParamsCalls };
+}
+
+const host: ReturnHost = { screenId: "vehicle-list" };
+const noOpenDrawer = (): void => {};
+const noOnWriteSuccess = async (): Promise<void> => {};
+
+describe("buildRecordActions — RowActionNavigate.tab", () => {
+  test("screen-target: tab lands in the same setSearchParams call as returnTo", () => {
+    const { nav, navigateCalls, setSearchParamsCalls } = recordingNav();
+    const action: RowActionNavigate = {
+      kind: "navigate",
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      screen: "vehicle-detail",
+      entityId: "id",
+      tab: "channels",
+      params: { pick: ["name"] },
+    };
+    const actions = buildRecordActions({
+      actions: [action],
+      record: { id: "abc", name: "Vehicle A" },
+      translate: (key) => key,
+      nav,
+      host,
+      dispatcher: undefined,
+      openDrawer: noOpenDrawer,
+      onWriteSuccess: noOnWriteSuccess,
+    });
+    actions?.[0]?.onPress();
+
+    expect(navigateCalls).toEqual([{ screenId: "vehicle-detail", entityId: "abc" }]);
+    expect(setSearchParamsCalls).toHaveLength(1);
+    expect(setSearchParamsCalls[0]).toMatchObject({
+      tab: "channels",
+      name: "Vehicle A",
+      [RETURN_TO_PARAM]: "vehicle-list",
+    });
+  });
+
+  test("entity-target: tab is included in the navigate search params", () => {
+    const { nav, setSearchParamsCalls } = recordingNav();
+    const action: RowActionNavigate = {
+      kind: "navigate",
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      entity: "vehicle",
+      entityId: "id",
+      tab: "channels",
+    };
+    const actions = buildRecordActions({
+      actions: [action],
+      record: { id: "abc" },
+      translate: (key) => key,
+      nav,
+      host,
+      dispatcher: undefined,
+      openDrawer: noOpenDrawer,
+      onWriteSuccess: noOnWriteSuccess,
+    });
+    actions?.[0]?.onPress();
+
+    expect(setSearchParamsCalls).toHaveLength(1);
+    expect(setSearchParamsCalls[0]).toEqual({ tab: "channels" });
+  });
+
+  test("no tab set: search params carry no tab key", () => {
+    const { nav, setSearchParamsCalls } = recordingNav();
+    const action: RowActionNavigate = {
+      kind: "navigate",
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      screen: "vehicle-detail",
+      entityId: "id",
+      params: { pick: ["name"] },
+    };
+    const actions = buildRecordActions({
+      actions: [action],
+      record: { id: "abc", name: "Vehicle A" },
+      translate: (key) => key,
+      nav,
+      host,
+      dispatcher: undefined,
+      openDrawer: noOpenDrawer,
+      onWriteSuccess: noOnWriteSuccess,
+    });
+    actions?.[0]?.onPress();
+
+    expect(setSearchParamsCalls).toHaveLength(1);
+    expect(setSearchParamsCalls[0]).not.toHaveProperty("tab");
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -103,9 +103,9 @@ import {
   buildRecordActions,
   evalRowExtractor,
   isWriteHandlerRowAction,
+  navigateActionSearchParams,
   refetchAfterWrite,
   runProjectionRowNavigate,
-  stringifyNavParams,
 } from "./row-actions";
 import { findEditScreenFor, navigateTargetAllows, screenAccessAllows } from "./screen-access";
 import { SecretMintBody } from "./secret-mint-body";
@@ -1952,10 +1952,9 @@ function EntityListBody({
         const id = explicit ?? fallback ?? "";
         if (id === "") return;
         nav.navigate({ entity: action.entity, id });
-        const params =
-          action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
+        const params = navigateActionSearchParams(action, row.values);
         if (params !== undefined) {
-          nav.setSearchParams(stringifyNavParams(params));
+          nav.setSearchParams(params);
         }
       } else if (action.screen !== undefined) {
         // Default entityId für entityEdit-Targets: row["id"] wenn kein expliziter
@@ -1979,10 +1978,7 @@ function EntityListBody({
         // kennt via URL nur Strings). Known-edge: zielt die Action auf den
         // AKTUELLEN pathname, mergen die Params auf den alten ?-String (für
         // Row-Actions praktisch nicht erreichbar, Pfad differiert).
-        const params =
-          action.params !== undefined
-            ? stringifyNavParams(evalRowExtractor(action.params, row.values))
-            : undefined;
+        const params = navigateActionSearchParams(action, row.values);
         navigateWithReturnTo(nav, target, host, params);
       }
     },
@@ -2586,6 +2582,7 @@ function runMetricNavigate(
           entity: navigate.entity,
           ...(navigate.entityId !== undefined && { entityId: navigate.entityId }),
           ...(navigate.params !== undefined && { params: navigate.params }),
+          ...(navigate.tab !== undefined && { tab: navigate.tab }),
         }
       : navigate.screen !== undefined
         ? {
@@ -2593,11 +2590,11 @@ function runMetricNavigate(
             screen: navigate.screen,
             ...(navigate.entityId !== undefined && { entityId: navigate.entityId }),
             ...(navigate.params !== undefined && { params: navigate.params }),
+            ...(navigate.tab !== undefined && { tab: navigate.tab }),
           }
         : undefined;
   if (action === undefined) return;
   runProjectionRowNavigate(nav, action, { id: "", values: record }, host);
-  if (navigate.tab !== undefined) nav.setSearchParams({ tab: navigate.tab });
 }
 
 // Absolute http(s) check for RecordHeaderSpec.subtitleHref — deliberately

package/src/app/row-actions.ts

@@ -71,6 +71,18 @@ export function stringifyNavParams(params: Record<string, unknown>): Record<stri
   return out;
 }
 
+export function navigateActionSearchParams(
+  action: RowActionNavigate,
+  values: Readonly<Record<string, unknown>>,
+): Record<string, string | null> | undefined {
+  const params =
+    action.params !== undefined
+      ? stringifyNavParams(evalRowExtractor(action.params, values))
+      : undefined;
+  if (action.tab === undefined) return params;
+  return { ...params, tab: action.tab };
+}
+
 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
@@ -95,10 +107,9 @@ export function runProjectionRowNavigate(
     // skip: no entityId column on this row — nothing to navigate to.
     if (id === "") return;
     nav.navigate({ entity: action.entity, id });
-    const params =
-      action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
+    const params = navigateActionSearchParams(action, row.values);
     if (params !== undefined) {
-      nav.setSearchParams(stringifyNavParams(params));
+      nav.setSearchParams(params);
     }
   } else if (action.screen !== undefined) {
     const entityId =
@@ -107,10 +118,7 @@ export function runProjectionRowNavigate(
       screenId: action.screen,
       ...(entityId !== undefined && entityId !== "" && { entityId }),
     };
-    const params =
-      action.params !== undefined
-        ? stringifyNavParams(evalRowExtractor(action.params, row.values))
-        : undefined;
+    const params = navigateActionSearchParams(action, row.values);
     navigateWithReturnTo(nav, target, host, params);
   }
   // skip: neither entity nor screen set — the boot-validator rejects this
@@ -443,9 +451,8 @@ function buildNavigateRecordAction(
     sameEntityScreenId,
   } = options;
   const runParams = (): void => {
-    const params =
-      action.params !== undefined ? evalRowExtractor(action.params, record) : undefined;
-    if (params !== undefined) nav.setSearchParams(stringifyNavParams(params));
+    const params = navigateActionSearchParams(action, record);
+    if (params !== undefined) nav.setSearchParams(params);
   };
   if (action.entity !== undefined) {
     const targetEntity = action.entity;
@@ -482,10 +489,7 @@ function buildNavigateRecordAction(
           screenId: targetScreen,
           ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
         };
-        const params =
-          action.params !== undefined
-            ? stringifyNavParams(evalRowExtractor(action.params, record))
-            : undefined;
+        const params = navigateActionSearchParams(action, record);
         navigateWithReturnTo(nav, target, host, params);
       },
     };

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.310.0",
+    "type": "improvement",
+    "title": "Navigate actions merge `tab` into the search params next to returnTo",
+    "detail": "Row, record and section navigate actions set `tab` in the same\nsetSearchParams call as their `params` and `returnTo`, so the back\nnavigation survives. Metric navigate with screen/entity plus tab now also\nlands in that single call instead of a second setSearchParams after it."
+  },
   {
     "version": "0.308.0",
     "type": "improvement",