@cosmicdrift/kumiko-renderer 0.270.0 → 0.274.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.270.0",
+  "version": "0.274.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.270.0",
-    "@cosmicdrift/kumiko-headless": "0.270.0",
+    "@cosmicdrift/kumiko-framework": "0.274.0",
+    "@cosmicdrift/kumiko-headless": "0.274.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.270.0"
+    "@cosmicdrift/kumiko-locale-de": "0.274.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/action-form-field-labels.test.tsx

@@ -0,0 +1,92 @@
+// fieldLabels overrides a field's label per screen, via the same
+// label-resolution pipeline as entityEdit (see action-form-shim.ts).
+
+import { describe, expect, test } from "bun:test";
+import type { ActionFormScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { render } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { RenderEdit } from "../../components/render-edit";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import { type CorePrimitives, type FieldProps, PrimitivesProvider } from "../../primitives";
+import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "../action-form-shim";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+function renderActionFormCapturingFieldLabels(screen: ActionFormScreenDefinition): {
+  labels: Record<string, string>;
+} {
+  const labels: Record<string, string> = {};
+  const capturingField = (props: FieldProps): ReactNode => {
+    if (props.testId !== undefined) labels[props.testId] = props.label;
+    return props.children;
+  };
+  const primitives: CorePrimitives = {
+    Button: noop,
+    Banner: noop,
+    Field: capturingField,
+    Input: noop,
+    DataTable: noop,
+    Form: passChildren,
+    Section: passChildren,
+    Card: passChildren,
+    Grid: passChildren,
+    GridCell: passChildren,
+    Text: passChildren,
+    Heading: noop,
+    Dialog: noop,
+    Modal: noop,
+    Lightbox: noop,
+    ConfigSourceBadge: noop,
+    ConfigCascadeView: noop,
+    Link: noop,
+  };
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <PrimitivesProvider value={primitives}>
+        <RenderEdit
+          screen={synthesizeActionFormScreen(screen)}
+          entity={synthesizeActionFormEntity(screen.fields)}
+          featureName="shop"
+          initial={{ dueAt: "" }}
+        />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+  return { labels };
+}
+
+describe("RenderEdit — ActionFormScreenDefinition.fieldLabels", () => {
+  test("a field named in fieldLabels renders the screen's own label", () => {
+    const screen: ActionFormScreenDefinition = {
+      id: "reschedule",
+      type: "actionForm",
+      handler: "shop:write:reschedule",
+      fields: { dueAt: { type: "date" } },
+      fieldLabels: { dueAt: "shop:reschedule.dueAt" },
+      layout: { sections: [{ fields: ["dueAt"] }] },
+    };
+
+    const { labels } = renderActionFormCapturingFieldLabels(screen);
+
+    expect(labels["field-dueAt"]).toBe("shop:reschedule.dueAt");
+  });
+
+  test("without fieldLabels, the field renders the default __action-form__ convention label", () => {
+    const screen: ActionFormScreenDefinition = {
+      id: "reschedule",
+      type: "actionForm",
+      handler: "shop:write:reschedule",
+      fields: { dueAt: { type: "date" } },
+      layout: { sections: [{ fields: ["dueAt"] }] },
+    };
+
+    const { labels } = renderActionFormCapturingFieldLabels(screen);
+
+    expect(labels["field-dueAt"]).toBe("shop:entity:__action-form__:field:dueAt");
+  });
+});

package/src/app/__tests__/action-form-shim.test.ts

@@ -69,6 +69,27 @@ describe("synthesizeActionFormScreen", () => {
     });
     expect("slots" in withoutSlots).toBe(false);
   });
+
+  test("carries fieldLabels through so RenderEdit resolves the screen's own label override", () => {
+    const withFieldLabels = synthesizeActionFormScreen({
+      id: "reschedule",
+      type: "actionForm",
+      handler: "shop:write:reschedule",
+      layout: { sections: [{ title: "Reschedule", fields: ["dueAt"] }] },
+      fields: { dueAt: { type: "date" } },
+      fieldLabels: { dueAt: "shop:reschedule.dueAt" },
+    });
+    expect(withFieldLabels.fieldLabels).toEqual({ dueAt: "shop:reschedule.dueAt" });
+
+    const withoutFieldLabels = synthesizeActionFormScreen({
+      id: "reschedule",
+      type: "actionForm",
+      handler: "shop:write:reschedule",
+      layout: { sections: [{ title: "Reschedule", fields: ["dueAt"] }] },
+      fields: { dueAt: { type: "date" } },
+    });
+    expect("fieldLabels" in withoutFieldLabels).toBe(false);
+  });
 });
 
 describe("synthesizeSecretMintConfirmScreen (fw#2838)", () => {

package/src/app/__tests__/entity-list-row-action-entity-target.test.tsx

@@ -22,6 +22,7 @@ import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
 import { kumikoDefaultTranslations } from "../../i18n-defaults";
 import {
   type ButtonProps,
+  type CardProps,
   type CorePrimitives,
   type DataTableProps,
   type DataTableRowAction,
@@ -62,6 +63,16 @@ const captureDataTable: ComponentType<DataTableProps> = (props) => {
 };
 const noop = (): ReactNode => null;
 const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+// Card's title/subtitle/headerActions arrive as `slots` instead of raw
+// JSX children.
+const cardWithSlots: ComponentType<CardProps> = ({ slots, children }) => (
+  <>
+    {slots?.title}
+    {slots?.subtitle}
+    {slots?.headerActions}
+    {children}
+  </>
+);
 
 const testPrimitives: CorePrimitives = {
   Button: noop,
@@ -71,7 +82,7 @@ const testPrimitives: CorePrimitives = {
   DataTable: captureDataTable,
   Form: passChildren,
   Section: passChildren,
-  Card: passChildren,
+  Card: cardWithSlots,
   Grid: passChildren,
   GridCell: passChildren,
   Text: passChildren,

package/src/app/__tests__/list-filter-facets.test.tsx

@@ -102,13 +102,17 @@ function StatefulNav({ children }: { readonly children: ReactNode }): ReactNode
   return <NavProvider value={value}>{children}</NavProvider>;
 }
 
-function renderScreen(schema: FeatureSchema, qn: string): void {
+function renderScreen(
+  schema: FeatureSchema,
+  qn: string,
+  dispatcher: Dispatcher = stubDispatcher(),
+): void {
   render(
     <LocaleProvider
       resolver={createStaticLocaleResolver({ locale: "de-DE" })}
       fallbackBundles={[kumikoDefaultTranslations]}
     >
-      <DispatcherProvider dispatcher={stubDispatcher()}>
+      <DispatcherProvider dispatcher={dispatcher}>
         <StatefulNav>
           <PrimitivesProvider value={testPrimitives}>
             <KumikoScreen schema={schema} qn={qn} />
@@ -119,6 +123,27 @@ function renderScreen(schema: FeatureSchema, qn: string): void {
   );
 }
 
+function stubDispatcherByType(
+  responses: Readonly<Record<string, { rows: readonly Record<string, unknown>[] }>>,
+): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string, payload: unknown) => {
+      queryCalls.push({ type, payload });
+      const rows = responses[type]?.rows ?? [];
+      return { isSuccess: true, data: { rows, nextCursor: null } };
+    }) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
 describe("entityList facets — unchanged after the shared buildFilterFacets/buildFilterPayload extraction (fw#2224)", () => {
   test("a filterable boolean field renders as a facet, and toggling it sends a coerced boolean in payload.filters", async () => {
     queryCalls = [];
@@ -337,4 +362,67 @@ describe("projectionList filter + facets (fw#2224)", () => {
     expect(facet?.label).toBe(save);
     expect(facet?.options?.[0]?.label).toBe(cancel);
   });
+
+  test("a reference facet loads its options from the referenced entity's list query, and selecting one sends an id filter", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    const dispatcher = stubDispatcherByType({
+      "ledger:query:member:list": { rows: [] },
+      "ledger:query:tenant:list": {
+        rows: [
+          { id: "t1", name: "Acme" },
+          { id: "t2", name: "Globex" },
+        ],
+      },
+    });
+    const screen: ProjectionListScreenDefinition = {
+      id: "member-list",
+      type: "projectionList",
+      query: "ledger:query:member:list",
+      columns: ["tenantId"],
+      facets: [
+        {
+          field: "tenantId",
+          type: "reference",
+          label: "Tenant",
+          entity: "tenant",
+          labelField: "name",
+        },
+      ],
+    };
+    const schema: FeatureSchema = {
+      featureName: "ledger",
+      entities: {},
+      screens: [screen],
+    } as FeatureSchema;
+
+    renderScreen(schema, "ledger:screen:member-list", dispatcher);
+
+    await waitFor(() =>
+      expect(queryCalls.some((c) => c.type === "ledger:query:tenant:list")).toBe(true),
+    );
+    await waitFor(() => expect(getCapturedProps()?.filterFacets?.[0]?.options).toHaveLength(2));
+    const props = getCapturedProps();
+    if (props === undefined) throw new Error("DataTable was not rendered");
+    expect(props.filterFacets).toEqual([
+      {
+        field: "tenantId",
+        label: "Tenant",
+        options: [
+          { value: "t1", label: "Acme" },
+          { value: "t2", label: "Globex" },
+        ],
+      },
+    ]);
+
+    const countBeforeSelect = queryCalls.length;
+    await act(async () => {
+      props.onFilterChange?.("tenantId", ["t1"]);
+    });
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(countBeforeSelect));
+    const lastPayload = queryCalls[queryCalls.length - 1]?.payload;
+    expect(lastPayload).toMatchObject({
+      filters: [{ field: "tenantId", op: "in", value: ["t1"] }],
+    });
+  });
 });

package/src/app/__tests__/projection-detail-actions.test.tsx

@@ -26,6 +26,7 @@ import {
   type ActionOverflowMenuProps,
   type BannerProps,
   type ButtonProps,
+  type CardProps,
   type CorePrimitives,
   type DialogProps,
   type FormProps,
@@ -40,6 +41,17 @@ import { NavProvider } from "../nav";
 const noop = (): ReactNode => null;
 const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
 
+// Card's title/subtitle/headerActions arrive as `slots`; this stub renders
+// them so tests asserting on header-action content still see it.
+const CardWithSlots: ComponentType<CardProps> = ({ slots, children }) => (
+  <>
+    {slots?.title}
+    {slots?.subtitle}
+    {slots?.headerActions}
+    {children}
+  </>
+);
+
 const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) => (
   <button type="button" data-testid={testId} onClick={() => void onClick?.()}>
     {children}
@@ -130,7 +142,7 @@ const testPrimitives: CorePrimitives = {
   DataTable: noop,
   Form: FormWithActions,
   Section: passChildren,
-  Card: passChildren,
+  Card: CardWithSlots,
   Grid: passChildren,
   GridCell: passChildren,
   Text: passChildren,

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

@@ -0,0 +1,255 @@
+import { describe, expect, test } from "bun:test";
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FeatureSchema } from "../feature-schema";
+import { resolveReturnTarget, returnToParams } from "../return-to";
+
+function schemaWith(featureName: string, screens: readonly ScreenDefinition[]): FeatureSchema {
+  return { featureName, entities: {}, screens };
+}
+
+const listScreen: ScreenDefinition = {
+  id: "token-list",
+  type: "entityList",
+  entity: "token",
+  columns: ["name"],
+};
+
+const editScreen: ScreenDefinition = {
+  id: "token-edit",
+  type: "entityEdit",
+  entity: "token",
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+const detailScreen: ScreenDefinition = {
+  id: "token-detail",
+  type: "projectionDetail",
+  query: "tokens:query:token:detail",
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+const singletonDetailScreen: ScreenDefinition = {
+  id: "my-settings",
+  type: "projectionDetail",
+  query: "tokens:query:settings:mine",
+  singleton: true,
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+const adminOnlyScreen: ScreenDefinition = {
+  id: "admin-only",
+  type: "custom",
+  renderer: { react: "stub" },
+  access: { roles: ["Admin"] },
+};
+
+const features: readonly FeatureSchema[] = [
+  schemaWith("tokens", [
+    listScreen,
+    editScreen,
+    detailScreen,
+    singletonDetailScreen,
+    adminOnlyScreen,
+  ]),
+];
+
+describe("resolveReturnTarget", () => {
+  test("valid short id resolves to a ScreenTarget", () => {
+    expect(resolveReturnTarget("token-list", "token-create", features, undefined)).toEqual({
+      screenId: "token-list",
+    });
+  });
+
+  test("with entityId on an entityEdit screen", () => {
+    expect(resolveReturnTarget("token-edit/abc-123", "token-create", features, undefined)).toEqual({
+      screenId: "token-edit",
+      entityId: "abc-123",
+    });
+  });
+
+  test("with entityId on a projectionDetail screen", () => {
+    expect(
+      resolveReturnTarget("token-detail/abc-123", "token-create", features, undefined),
+    ).toEqual({ screenId: "token-detail", entityId: "abc-123" });
+  });
+
+  test("accepts a '%'-containing entityId that decodes to a safe value", () => {
+    expect(resolveReturnTarget("token-edit/abc%41", "token-create", features, undefined)).toEqual({
+      screenId: "token-edit",
+      entityId: "abc%41",
+    });
+  });
+
+  test("undefined raw value", () => {
+    expect(resolveReturnTarget(undefined, "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("empty string", () => {
+    expect(resolveReturnTarget("", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("rejects an unknown screen id", () => {
+    expect(
+      resolveReturnTarget("unknown-screen", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a qualified screen id ('feature:screen:x')", () => {
+    expect(
+      resolveReturnTarget("tokens:screen:token-list", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a protocol-relative value ('//evil.com')", () => {
+    expect(resolveReturnTarget("//evil.com", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("rejects an absolute URL ('https://evil.com')", () => {
+    expect(
+      resolveReturnTarget("https://evil.com", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects more than two segments ('a/b/c')", () => {
+    expect(resolveReturnTarget("a/b/c", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("rejects a trailing slash ('x/')", () => {
+    expect(resolveReturnTarget("token-list/", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("rejects a leading slash ('/x')", () => {
+    expect(resolveReturnTarget("/token-list", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("rejects a role-gated screen when roles are missing", () => {
+    expect(resolveReturnTarget("admin-only", "token-create", features, undefined)).toBeUndefined();
+  });
+
+  test("accepts a role-gated screen when the role matches", () => {
+    expect(resolveReturnTarget("admin-only", "token-create", features, ["Admin"])).toEqual({
+      screenId: "admin-only",
+    });
+  });
+
+  test("rejects the own screen (self)", () => {
+    expect(
+      resolveReturnTarget("token-create", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects an entityId on a list screen", () => {
+    expect(
+      resolveReturnTarget("token-list/abc-123", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId '..'", () => {
+    expect(
+      resolveReturnTarget("token-edit/..", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId '.'", () => {
+    expect(
+      resolveReturnTarget("token-edit/.", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId with '?'", () => {
+    expect(
+      resolveReturnTarget("token-edit/abc?x=1", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId with '#'", () => {
+    expect(
+      resolveReturnTarget("token-edit/abc#frag", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId with '\\\\'", () => {
+    expect(
+      resolveReturnTarget("token-edit/abc\\def", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects entityId with a space", () => {
+    expect(
+      resolveReturnTarget("token-edit/abc def", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a percent-encoded entityId that decodes to '..'", () => {
+    expect(
+      resolveReturnTarget("token-edit/%2e%2e", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a percent-encoded entityId that decodes to '.'", () => {
+    expect(
+      resolveReturnTarget("token-edit/%2E", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a percent-encoded entityId that decodes to a slash", () => {
+    expect(
+      resolveReturnTarget("token-edit/%2Fx", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a malformed percent-encoded entityId", () => {
+    expect(
+      resolveReturnTarget("token-edit/%E0%A4%A", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a percent-encoded entityId that decodes to whitespace", () => {
+    expect(
+      resolveReturnTarget("token-edit/a%20b", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("rejects a non-singleton projectionDetail without an entityId", () => {
+    expect(
+      resolveReturnTarget("token-detail", "token-create", features, undefined),
+    ).toBeUndefined();
+  });
+
+  test("accepts a singleton projectionDetail without an entityId", () => {
+    expect(resolveReturnTarget("my-settings", "token-create", features, undefined)).toEqual({
+      screenId: "my-settings",
+    });
+  });
+});
+
+describe("returnToParams", () => {
+  test("no host -> {}", () => {
+    expect(returnToParams(undefined, { screenId: "token-list" })).toEqual({});
+  });
+
+  test("target equals the host (self) -> {}", () => {
+    expect(returnToParams({ screenId: "token-list" }, { screenId: "token-list" })).toEqual({});
+  });
+
+  test("target equals the host including entityId -> {}", () => {
+    expect(
+      returnToParams(
+        { screenId: "token-edit", entityId: "abc" },
+        { screenId: "token-edit", entityId: "abc" },
+      ),
+    ).toEqual({});
+  });
+
+  test("different target -> returnTo param", () => {
+    expect(returnToParams({ screenId: "token-list" }, { screenId: "token-create" })).toEqual({
+      returnTo: "token-list",
+    });
+  });
+
+  test("host with entityId formats as 'screenId/entityId'", () => {
+    expect(
+      returnToParams({ screenId: "token-edit", entityId: "abc" }, { screenId: "token-create" }),
+    ).toEqual({ returnTo: "token-edit/abc" });
+  });
+});

package/src/app/__tests__/row-default-edit-action.test.tsx

@@ -1,4 +1,4 @@
-// kumiko-screen-akte-bedienkonzept: entityList and projectionList rowActions
+// entityList and projectionList rowActions
 // get a default "Edit" row action for free when the row's entity has a
 // visible entityEdit screen — same cross-feature resolution as
 // projectionDetail's header defaultEditAction (fw#2166), reused here via

package/src/app/action-form-shim.ts

@@ -50,9 +50,11 @@ export function synthesizeActionFormScreen(
     layout: screen.layout,
     ...(screen.description !== undefined && { description: screen.description }),
     ...(screen.access !== undefined && { access: screen.access }),
-    // Only ActionFormScreenDefinition carries slots — SecretMintScreenDefinition
-    // has none, so `in` is the narrowing (no cast).
+    // Only ActionFormScreenDefinition carries slots/fieldLabels; `in` narrows
+    // without a cast since SecretMintScreenDefinition has neither.
     ...("slots" in screen && screen.slots !== undefined && { slots: screen.slots }),
+    ...("fieldLabels" in screen &&
+      screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),
   };
 }