@cosmicdrift/kumiko-renderer 0.201.0 → 0.202.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.201.0",
+  "version": "0.202.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,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.201.0",
-    "@cosmicdrift/kumiko-headless": "0.201.0",
+    "@cosmicdrift/kumiko-framework": "0.202.0",
+    "@cosmicdrift/kumiko-headless": "0.202.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/app/__tests__/nav.test.ts

@@ -4,7 +4,9 @@
 // (mit/ohne Workspaces). Pure, kein DOM.
 
 import { describe, expect, test } from "bun:test";
-import { formatPath, parsePath } from "../nav";
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FeatureSchema } from "../feature-schema";
+import { formatPath, parsePath, resolveTarget } from "../nav";
 
 describe("parsePath — ohne Workspaces", () => {
   test("/<screenId>", () => {
@@ -81,3 +83,92 @@ describe("Roundtrip parsePath ↔ formatPath", () => {
     expect(parsePath(formatPath(t), true)).toEqual(t);
   });
 });
+
+// resolveTarget: ObjectTarget -> ScreenTarget lookup (fw#2163). Custom-Screen
+// detailFor is the main case in app repos (projectionDetail has no entity to
+// key off), so it gets its own scenario rather than piggy-backing on the
+// entityList one.
+function schemaWith(featureName: string, screens: readonly ScreenDefinition[]): FeatureSchema {
+  return { featureName, entities: {}, screens };
+}
+
+const leaseDetailScreen: ScreenDefinition = {
+  id: "lease-detail",
+  type: "custom",
+  renderer: { react: "stub" },
+  detailFor: "lease",
+};
+
+const leaseListScreen: ScreenDefinition = {
+  id: "lease-list",
+  type: "entityList",
+  entity: "lease",
+  columns: ["name"],
+};
+
+const leaseEditScreen: ScreenDefinition = {
+  id: "lease-edit",
+  type: "entityEdit",
+  entity: "lease",
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+const leaseEditScreenAlt: ScreenDefinition = {
+  id: "lease-edit-quick",
+  type: "entityEdit",
+  entity: "lease",
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+describe("resolveTarget", () => {
+  test("ScreenTarget passes through unchanged", () => {
+    const target = { screenId: "task-edit", entityId: "abc" };
+    expect(resolveTarget([], target)).toBe(target);
+  });
+
+  test("ObjectTarget resolves via the matching custom detailFor screen", () => {
+    const schema = schemaWith("property", [leaseDetailScreen]);
+    expect(resolveTarget([schema], { entity: "lease", id: "l-1" })).toEqual({
+      screenId: "property:screen:lease-detail",
+      entityId: "l-1",
+    });
+  });
+
+  // solon's "property" entity has THREE entityEdit screens — "the" edit
+  // screen for an entity isn't well-defined, so resolveTarget only ever
+  // looks at detailFor. This pins that multiple same-entity entityEdit
+  // screens don't confuse detail resolution (no first-match ambiguity).
+  test("multiple screens on the same entity (list, two entityEdit forms, one detail) — only the detailFor screen resolves", () => {
+    const schema = schemaWith("property", [
+      leaseListScreen,
+      leaseEditScreen,
+      leaseEditScreenAlt,
+      leaseDetailScreen,
+    ]);
+    expect(resolveTarget([schema], { entity: "lease", id: "l-1" })).toEqual({
+      screenId: "property:screen:lease-detail",
+      entityId: "l-1",
+    });
+  });
+
+  test("workspaceId carries through when set", () => {
+    const schema = schemaWith("property", [leaseDetailScreen]);
+    const resolved = resolveTarget([schema], { entity: "lease", id: "l-1", workspaceId: "admin" });
+    expect(resolved).toEqual({
+      workspaceId: "admin",
+      screenId: "property:screen:lease-detail",
+      entityId: "l-1",
+    });
+  });
+
+  test("workspaceId is omitted (not undefined) when not set", () => {
+    const schema = schemaWith("property", [leaseDetailScreen]);
+    const resolved = resolveTarget([schema], { entity: "lease", id: "l-1" });
+    expect("workspaceId" in resolved).toBe(false);
+  });
+
+  test("unknown entity throws with the entity name in the message", () => {
+    const schema = schemaWith("property", [leaseDetailScreen]);
+    expect(() => resolveTarget([schema], { entity: "boat", id: "b-1" })).toThrow(/"boat"/);
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -49,6 +49,7 @@ import {
 } from "./projection-detail-shim";
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim";
 import { lastSegment, toKebab } from "./qn";
+import { qualifyScreenId } from "./qualify-screen-id";
 import { screenAccessAllows } from "./screen-access";
 import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
 
@@ -100,19 +101,10 @@ export type KumikoScreenProps = {
   readonly onCopyLink?: () => Promise<void> | void;
 };
 
-// Build the qualified name the registry would stamp on screen ingest:
-// <feature>:screen:<short-id>. Matches the rule in
-// packages/framework/src/engine/qualified-name.ts so client lookups
-// line up with server-side registry state.
-export function qualifyScreenId(featureName: string, screenId: string): string {
-  return `${featureName}:screen:${screenId}`;
-}
+export { qualifyScreenId };
 
-/** Symmetrisch zu qualifyScreenId für Nav-QNs. NavDefinition-IDs in der
- *  Registry haben die Form `<feature>:nav:<short-id>`; Code der QNs
- *  baut (z.B. WorkspaceShell-Resolver) sollte das hier durchreichen statt
- *  String-Concat damit ein zukünftiger QN-Schema-Wechsel an einer Stelle
- *  greift. */
+/** Mirrors qualifyScreenId for nav QNs (registry form `<feature>:nav:<short-id>`).
+ *  Callers building QNs (e.g. the WorkspaceShell resolver) should use this instead of string-concat, so a QN-schema change only touches one place. */
 export function qualifyNavId(featureName: string, navId: string): string {
   return `${featureName}:nav:${navId}`;
 }

package/src/app/nav.tsx

@@ -1,4 +1,6 @@
 import { createContext, type ReactNode, useContext } from "react";
+import type { FeatureSchema } from "./feature-schema";
+import { qualifyScreenId } from "./qualify-screen-id";
 
 // Navigation-Contract, plattform-neutral. Types + Context + Hook leben
 // hier; die konkrete Implementation (window.history im Web,
@@ -20,7 +22,7 @@ export type NavRoute = {
   readonly entityId?: string;
 };
 
-export type NavTarget = {
+export type ScreenTarget = {
   // 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.
@@ -29,6 +31,23 @@ export type NavTarget = {
   readonly entityId?: string;
 };
 
+// Object-based nav target — callers name WHAT they want to see (an entity's
+// row) instead of WHICH screen shows it. resolveTarget() below turns this
+// into a ScreenTarget by looking up the screen with matching `detailFor`.
+// No edit-form resolution here: an entity can have several entityEdit
+// screens (e.g. solon's "property" has three), so "the" edit screen isn't
+// well-defined — callers that want a form still name its screenId directly.
+export type ObjectTarget = {
+  readonly workspaceId?: string;
+  readonly entity: string;
+  readonly id: string;
+};
+
+// No `kind` tag: `"screenId" in target` narrows cleanly, and a tag would
+// force every existing NavTarget literal (every navigate/hrefFor call in
+// every app) to add one for an additive ticket. See resolveTarget().
+export type NavTarget = ScreenTarget | ObjectTarget;
+
 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. */
@@ -89,7 +108,7 @@ export function parsePath(pathname: string, hasWorkspaces?: boolean): NavRoute |
   return { screenId, ...(entityId !== undefined && { entityId }) };
 }
 
-export function formatPath(target: NavTarget): string {
+export function formatPath(target: ScreenTarget): string {
   // Workspace-Mode: prefix the workspace short id. Order matters —
   // workspace before screen mirrors parsePath's segment order.
   const segments: string[] = [];
@@ -99,6 +118,28 @@ export function formatPath(target: NavTarget): string {
   return `/${segments.join("/")}`;
 }
 
+// Resolves a NavTarget to the ScreenTarget form navigate/replace/hrefFor
+// operate on. Pure — no context, no I/O — so callers can use it outside
+// React too (see resolve-at-NavApi-build alternative in renderer-web).
+export function resolveTarget(features: readonly FeatureSchema[], target: NavTarget): ScreenTarget {
+  if ("screenId" in target) return target;
+
+  for (const feature of features) {
+    for (const screen of feature.screens) {
+      if (screen.detailFor !== target.entity) continue;
+      return {
+        ...(target.workspaceId !== undefined && { workspaceId: target.workspaceId }),
+        screenId: qualifyScreenId(feature.featureName, screen.id),
+        entityId: target.id,
+      };
+    }
+  }
+
+  throw new Error(
+    `resolveTarget: no detail screen for entity "${target.entity}". Add detailFor: "${target.entity}" to the screen that shows it.`,
+  );
+}
+
 // Context + Hook. Default ist `undefined` damit fehlender Provider
 // laut kracht statt ein silent-no-op NavApi mit toten navigate()
 // Aufrufen anzubieten.

package/src/app/qualify-screen-id.ts

@@ -0,0 +1,6 @@
+// Dependency-free: kumiko-screen.tsx already imports useNav from nav.tsx, so
+// this can't live in either without a cycle. Form must match the registry's
+// qualification rule (packages/framework/src/engine/qualified-name.ts).
+export function qualifyScreenId(featureName: string, screenId: string): string {
+  return `${featureName}:screen:${screenId}`;
+}

package/src/index.ts

@@ -64,8 +64,15 @@ export type {
 export { isAppSchema, toAppSchema } from "./app/feature-schema";
 export type { KumikoScreenProps } from "./app/kumiko-screen";
 export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen";
-export type { NavApi, NavProviderProps, NavRoute, NavTarget } from "./app/nav";
-export { formatPath, NavProvider, parsePath, useNav } from "./app/nav";
+export type {
+  NavApi,
+  NavProviderProps,
+  NavRoute,
+  NavTarget,
+  ObjectTarget,
+  ScreenTarget,
+} from "./app/nav";
+export { formatPath, NavProvider, parsePath, resolveTarget, useNav } from "./app/nav";
 export { lastSegment } from "./app/qn";
 export type { VariableChipsProps } from "./app/variable-chips";
 export { VariableChips } from "./app/variable-chips";