@cosmicdrift/kumiko-renderer 0.319.0 → 0.321.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.319.0",
+  "version": "0.321.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.319.0",
-    "@cosmicdrift/kumiko-headless": "0.319.0",
-    "@cosmicdrift/kumiko-types": "0.319.0",
+    "@cosmicdrift/kumiko-framework": "0.321.0",
+    "@cosmicdrift/kumiko-headless": "0.321.0",
+    "@cosmicdrift/kumiko-types": "0.321.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.319.0"
+    "@cosmicdrift/kumiko-locale-de": "0.321.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/return-to.test.ts

@@ -1,7 +1,37 @@
 import { describe, expect, test } from "bun:test";
 import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { FeatureSchema } from "../feature-schema";
-import { formatReturnTo, resolveReturnTarget, returnToParams, splitReturnTo } from "../return-to";
+import type { NavApi, NavTarget } from "../nav";
+import {
+  formatReturnTo,
+  navigateWithReturnTo,
+  resolveReturnTarget,
+  returnToParams,
+  splitReturnTo,
+} from "../return-to";
+
+// hrefFor maps entity ObjectTargets to their detail screen, mirroring resolveTarget.
+function fakeNav(searchParams: Readonly<Record<string, string>> = {}): {
+  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 hrefFor = (target: NavTarget): string =>
+    "screenId" in target
+      ? `/${[target.screenId, target.entityId].filter((s) => s !== undefined).join("/")}`
+      : `/vehicle-detail/${target.id}`;
+  const nav: NavApi = {
+    route: undefined,
+    navigate: (target) => navigateCalls.push(target),
+    replace: () => {},
+    hrefFor,
+    searchParams,
+    setSearchParams: (updates) => setSearchParamsCalls.push(updates),
+  };
+  return { nav, navigateCalls, setSearchParamsCalls };
+}
 
 function schemaWith(featureName: string, screens: readonly ScreenDefinition[]): FeatureSchema {
   return { featureName, entities: {}, screens };
@@ -336,3 +366,31 @@ describe("formatReturnTo / splitReturnTo", () => {
     ).toEqual({ returnTo: "token-list?tab=keys" });
   });
 });
+
+describe("navigateWithReturnTo — ObjectTarget", () => {
+  test("target resolves away from the host: returnTo carries the host's search-params snapshot", () => {
+    const { nav, navigateCalls, setSearchParamsCalls } = fakeNav({ tab: "active" });
+    navigateWithReturnTo(nav, { entity: "vehicle", id: "abc" }, { screenId: "vehicle-list" });
+
+    expect(navigateCalls).toEqual([{ entity: "vehicle", id: "abc" }]);
+    expect(setSearchParamsCalls).toEqual([{ returnTo: "vehicle-list?tab=active" }]);
+  });
+
+  test("target resolves to the host itself: no returnTo", () => {
+    const { nav, setSearchParamsCalls } = fakeNav();
+    navigateWithReturnTo(
+      nav,
+      { entity: "vehicle", id: "abc" },
+      { screenId: "vehicle-detail", entityId: "abc" },
+    );
+
+    expect(setSearchParamsCalls).toEqual([]);
+  });
+
+  test("no host: only params, no returnTo", () => {
+    const { nav, setSearchParamsCalls } = fakeNav();
+    navigateWithReturnTo(nav, { entity: "vehicle", id: "abc" }, undefined, { name: "Vehicle A" });
+
+    expect(setSearchParamsCalls).toEqual([{ name: "Vehicle A" }]);
+  });
+});

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

@@ -1,10 +1,17 @@
 import { describe, expect, test } from "bun:test";
-import type { RowActionNavigate } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  RelatedListToolbarAction,
+  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";
+import {
+  buildProjectionToolbarActions,
+  buildRecordActions,
+  runProjectionRowNavigate,
+} from "../row-actions";
 
-function recordingNav(): {
+function recordingNav(hrefFor: (target: NavTarget) => string = () => ""): {
   readonly nav: NavApi;
   readonly navigateCalls: NavTarget[];
   readonly setSearchParamsCalls: ReadonlyArray<Readonly<Record<string, string | null>>>;
@@ -15,13 +22,19 @@ function recordingNav(): {
     route: undefined,
     navigate: (target) => navigateCalls.push(target),
     replace: () => {},
-    hrefFor: () => "",
+    hrefFor,
     searchParams: {},
     setSearchParams: (updates) => setSearchParamsCalls.push(updates),
   };
   return { nav, navigateCalls, setSearchParamsCalls };
 }
 
+// hrefFor maps entity ObjectTargets to their detail screen, mirroring resolveTarget.
+const hrefForVehicleDetail = (target: NavTarget): string =>
+  "screenId" in target
+    ? `/${[target.screenId, target.entityId].filter((s) => s !== undefined).join("/")}`
+    : `/vehicle-detail/${target.id}`;
+
 const host: ReturnHost = { screenId: "vehicle-list" };
 const noOpenDrawer = (): void => {};
 const noOnWriteSuccess = async (): Promise<void> => {};
@@ -74,7 +87,7 @@ describe("buildRecordActions — RowActionNavigate.tab", () => {
       record: { id: "abc" },
       translate: (key) => key,
       nav,
-      host,
+      host: undefined,
       dispatcher: undefined,
       openDrawer: noOpenDrawer,
       onWriteSuccess: noOnWriteSuccess,
@@ -85,6 +98,32 @@ describe("buildRecordActions — RowActionNavigate.tab", () => {
     expect(setSearchParamsCalls[0]).toEqual({ tab: "channels" });
   });
 
+  test("entity-target: carries returnTo when the target resolves away from the host", () => {
+    const { nav, navigateCalls, setSearchParamsCalls } = recordingNav(hrefForVehicleDetail);
+    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(navigateCalls).toEqual([{ entity: "vehicle", id: "abc" }]);
+    expect(setSearchParamsCalls).toEqual([{ tab: "channels", [RETURN_TO_PARAM]: "vehicle-list" }]);
+  });
+
   test("no tab set: search params carry no tab key", () => {
     const { nav, setSearchParamsCalls } = recordingNav();
     const action: RowActionNavigate = {
@@ -111,3 +150,74 @@ describe("buildRecordActions — RowActionNavigate.tab", () => {
     expect(setSearchParamsCalls[0]).not.toHaveProperty("tab");
   });
 });
+
+describe("buildProjectionToolbarActions — navigate.tab", () => {
+  test("tab lands in the setSearchParams call", () => {
+    const { nav, navigateCalls, setSearchParamsCalls } = recordingNav();
+    const action: RelatedListToolbarAction = {
+      kind: "navigate",
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      screen: "vehicle-detail",
+      tab: "channels",
+    };
+    const actions = buildProjectionToolbarActions({
+      toolbarActions: [action],
+      translate: (key) => key,
+      dispatcher: undefined,
+      nav,
+      refetch: async () => {},
+      host: undefined,
+    });
+    actions?.[0]?.onTrigger();
+
+    expect(navigateCalls).toEqual([{ screenId: "vehicle-detail" }]);
+    expect(setSearchParamsCalls).toEqual([{ tab: "channels" }]);
+  });
+
+  test("navigatePrefill and tab both survive into the same setSearchParams call, plus returnTo with a host", () => {
+    const { nav, setSearchParamsCalls } = recordingNav();
+    const action: RelatedListToolbarAction = {
+      kind: "navigate",
+      id: "create-channel",
+      label: "app.actions.createChannel",
+      screen: "channel-create",
+      tab: "channels",
+    };
+    const actions = buildProjectionToolbarActions({
+      toolbarActions: [action],
+      translate: (key) => key,
+      dispatcher: undefined,
+      nav,
+      refetch: async () => {},
+      navigatePrefill: { vehicleId: "abc" },
+      host,
+    });
+    actions?.[0]?.onTrigger();
+
+    expect(setSearchParamsCalls).toHaveLength(1);
+    expect(setSearchParamsCalls[0]).toMatchObject({
+      tab: "channels",
+      vehicleId: "abc",
+      [RETURN_TO_PARAM]: "vehicle-list",
+    });
+  });
+});
+
+describe("runProjectionRowNavigate — entity target carries returnTo", () => {
+  test("entity action with a host and tab: navigate gets the ObjectTarget, returnTo and tab land together", () => {
+    const { nav, navigateCalls, setSearchParamsCalls } = recordingNav(hrefForVehicleDetail);
+    const action: RowActionNavigate = {
+      kind: "navigate",
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      entity: "vehicle",
+      entityId: "id",
+      tab: "channels",
+    };
+    runProjectionRowNavigate(nav, action, { id: "abc", values: { id: "abc" } }, host);
+
+    expect(navigateCalls).toEqual([{ entity: "vehicle", id: "abc" }]);
+    expect(setSearchParamsCalls).toEqual([{ tab: "channels", [RETURN_TO_PARAM]: "vehicle-list" }]);
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -1951,11 +1951,8 @@ function EntityListBody({
           action.entity === screen.entity ? String(row.values["id"] ?? "") : undefined;
         const id = explicit ?? fallback ?? "";
         if (id === "") return;
-        nav.navigate({ entity: action.entity, id });
         const params = navigateActionSearchParams(action, row.values);
-        if (params !== undefined) {
-          nav.setSearchParams(params);
-        }
+        navigateWithReturnTo(nav, { entity: action.entity, id }, host, params);
       } else if (action.screen !== undefined) {
         // Default entityId für entityEdit-Targets: row["id"] wenn kein expliziter
         // entityId-Feldname gesetzt ist. Nur für Targets DERSELBEN Entity — sonst

package/src/app/return-to.tsx

@@ -3,7 +3,7 @@ import { createContext, type ReactNode, useContext, useMemo } from "react";
 import { useUserRoles } from "../context/user-roles-context";
 import { useAppFeatures } from "./app-features-context";
 import type { FeatureSchema } from "./feature-schema";
-import { type NavApi, type ScreenTarget, useNav } from "./nav";
+import { type NavApi, type NavTarget, type ObjectTarget, type ScreenTarget, useNav } from "./nav";
 import { lastSegment } from "./qn";
 import { screenAccessAllows } from "./screen-access";
 
@@ -93,14 +93,34 @@ export function returnToParams(
   return { [RETURN_TO_PARAM]: formatReturnTo(host, hostParams) };
 }
 
+// ObjectTarget only resolves to a path inside the NavApi impl (detailFor
+// lookup across all features), so compare hrefs instead of the raw target.
+function objectTargetIsHost(nav: NavApi, target: ObjectTarget, host: ReturnHost): boolean {
+  const hostTarget: ScreenTarget = {
+    screenId: host.screenId,
+    ...(host.entityId !== undefined && { entityId: host.entityId }),
+  };
+  return nav.hrefFor(target) === nav.hrefFor(hostTarget);
+}
+
+function returnParamsFor(
+  nav: NavApi,
+  target: NavTarget,
+  host: ReturnHost | undefined,
+): Readonly<Record<string, string>> {
+  if ("screenId" in target) return returnToParams(host, target, nav.searchParams);
+  if (host === undefined || objectTargetIsHost(nav, target, host)) return {};
+  return { [RETURN_TO_PARAM]: formatReturnTo(host, nav.searchParams) };
+}
+
 export function navigateWithReturnTo(
   nav: NavApi,
-  target: ScreenTarget,
+  target: NavTarget,
   host: ReturnHost | undefined,
   params?: Readonly<Record<string, string | null>>,
 ): void {
   // Snapshot before navigating — nav.searchParams still describes the host.
-  const returnParams = returnToParams(host, target, nav.searchParams);
+  const returnParams = returnParamsFor(nav, target, host);
   nav.navigate(target);
   const merged: Record<string, string | null> = {
     ...(params ?? {}),

package/src/app/row-actions.ts

@@ -106,11 +106,8 @@ export function runProjectionRowNavigate(
     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 });
     const params = navigateActionSearchParams(action, row.values);
-    if (params !== undefined) {
-      nav.setSearchParams(params);
-    }
+    navigateWithReturnTo(nav, { entity: action.entity, id }, host, params);
   } else if (action.screen !== undefined) {
     const entityId =
       action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
@@ -320,7 +317,10 @@ function buildNavigateToolbarAction(
         action.params !== undefined && record !== undefined
           ? evalRowExtractor(action.params, record)
           : prefill;
-      const params = resolvedParams !== undefined ? stringifyNavParams(resolvedParams) : undefined;
+      const stringifiedParams =
+        resolvedParams !== undefined ? stringifyNavParams(resolvedParams) : undefined;
+      const params =
+        action.tab === undefined ? stringifiedParams : { ...stringifiedParams, tab: action.tab };
       navigateWithReturnTo(nav, target, host, params);
     },
   };
@@ -450,10 +450,6 @@ function buildNavigateRecordAction(
     defaultScreenTargetEntityId,
     sameEntityScreenId,
   } = options;
-  const runParams = (): void => {
-    const params = navigateActionSearchParams(action, record);
-    if (params !== undefined) nav.setSearchParams(params);
-  };
   if (action.entity !== undefined) {
     const targetEntity = action.entity;
     const id = action.entityId !== undefined ? String(record[action.entityId] ?? "") : "";
@@ -466,8 +462,8 @@ function buildNavigateRecordAction(
       onPress: () => {
         // No entityId on record (id === "") → nothing to navigate to.
         if (id !== "") {
-          nav.navigate({ entity: targetEntity, id });
-          runParams();
+          const params = navigateActionSearchParams(action, record);
+          navigateWithReturnTo(nav, { entity: targetEntity, id }, host, params);
         }
       },
     };

package/src/app/screen-access.ts

@@ -1,28 +1,16 @@
 import type {
-  AccessRule,
   EntityEditScreenDefinition,
   FeatureSchema,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import { isOpenToAllGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+import { isUiAccessGranted } from "@cosmicdrift/kumiko-framework/ui-types";
 import { lastSegment } from "./qn";
 
-// Minimal role-gate for the screen-render path (#1203 — nav filtering via
-// filterByAccess in workspace-shell.tsx hid role-gated screens from the
-// menu, but a direct URL/screenQn hit reached KumikoScreen unchecked).
-// Reimplemented instead of imported from framework/engine's hasAccess
-// (pulls server-side deps) — same bundle-purity reasoning as headless/nav's
-// resolve.ts:userCanSee, which this mirrors. Own leaf module (not exported
-// from kumiko-screen.tsx directly) so render-field.tsx can import it too
-// without the kumiko-screen → RenderEdit → RenderField cycle.
-export function screenAccessAllows(
-  access: AccessRule | undefined,
-  userRoles: readonly string[] | undefined,
-): boolean {
-  if (!access) return true;
-  if ("openToAll" in access) return isOpenToAllGranted(access);
-  if (userRoles === undefined) return false;
-  return access.roles.some((role) => userRoles.includes(role));
-}
+// Shared UI-visibility predicate for the screen-render path (#1203 — nav
+// filtering via filterByAccess in workspace-shell.tsx hid role-gated
+// screens from the menu, but a direct URL/screenQn hit reached
+// KumikoScreen unchecked). Public name kept as an alias of the shared
+// predicate that headless/nav and workspace-shell use as well.
+export { isUiAccessGranted as screenAccessAllows };
 
 // A navigate target (metric click) declares no access rule of its own — the
 // destination screen already does, so the jump is offered exactly when the
@@ -49,7 +37,7 @@ export function navigateTargetAllows(
       // First match IS the destination: short ids are globally unique
       // (validateScreenShortIdCollisions) and both the router and
       // resolveTarget take the first hit.
-      if (isTarget) return screenAccessAllows(candidate.access, userRoles);
+      if (isTarget) return isUiAccessGranted(candidate.access, userRoles);
     }
   }
   // Unresolvable target — the boot-validator doesn't check metric navigate
@@ -67,7 +55,7 @@ export function findEditScreenFor(
   for (const feature of appFeatures) {
     const match = feature.screens.find(
       (s): s is EntityEditScreenDefinition =>
-        s.type === "entityEdit" && s.entity === entity && screenAccessAllows(s.access, userRoles),
+        s.type === "entityEdit" && s.entity === entity && isUiAccessGranted(s.access, userRoles),
     );
     if (match !== undefined) return match;
   }

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "navigateWithReturnTo carries returnTo for entity ObjectTargets",
+    "detail": "navigateWithReturnTo now accepts a NavTarget (ScreenTarget or ObjectTarget),\nnot just ScreenTarget. For an entity target it compares the resolved href\nagainst the host's to detect a self-navigate (no returnTo) and otherwise\nsets returnTo to the host snapshot, same as the existing screen-target\npath. runProjectionRowNavigate, buildNavigateRecordAction, EntityListBody's\nrow navigate and related-list-section's legacy rowClick now go through\nthis for entity actions."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "Toolbar navigate actions merge `tab` into the search params",
+    "detail": "buildNavigateToolbarAction (shared by entityList, projectionList and\nrelatedList-section toolbars) sets `tab` in the same params object as any\ndeclared `params`/prefill, so it lands in the single navigateWithReturnTo\ncall next to returnTo."
+  },
   {
     "version": "0.318.0",
     "type": "improvement",

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

@@ -20,7 +20,7 @@ import {
 } from "../app/list-facets";
 import { useNav } from "../app/nav";
 import { ReferenceFacetBridges, type ReferenceFacetOption } from "../app/reference-facet-bridge";
-import { useReturnHost } from "../app/return-to";
+import { navigateWithReturnTo, useReturnHost } from "../app/return-to";
 import {
   buildDefaultEditRowAction,
   buildProjectionRowActions,
@@ -252,7 +252,7 @@ export function RelatedListSection({
       ? (row: ListRowViewModel) => {
           const id = String(row.values[rowClick.idColumn ?? "id"] ?? "");
           if (id === "") return;
-          nav.navigate({ entity: rowClick.entity, id });
+          navigateWithReturnTo(nav, { entity: rowClick.entity, id }, host);
         }
       : rowClickAction !== undefined
         ? (row: ListRowViewModel) => runProjectionRowNavigate(nav, rowClickAction, row, host)

package/src/i18n-defaults.ts

@@ -82,6 +82,12 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
 
     "kumiko.dashboard.filter.all": "All",
 
+    "kumiko.app-boot.loading": "Loading…",
+    "kumiko.app-boot.unauthorized": "You need to sign in to see this.",
+    "kumiko.app-boot.failed": "Couldn't load the app. Check your connection and try again.",
+    "kumiko.app-boot.no-open-screen":
+      "This app has no screen that's accessible without a role restriction.",
+
     "kumiko.widget.loading": "Loading…",
     "kumiko.widget.error.title": "Couldn't load.",