@cosmicdrift/kumiko-renderer 0.202.0 → 0.204.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.202.0",
+  "version": "0.204.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.202.0",
-    "@cosmicdrift/kumiko-headless": "0.202.0",
+    "@cosmicdrift/kumiko-framework": "0.204.0",
+    "@cosmicdrift/kumiko-headless": "0.204.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/app/__tests__/build-list-query-payload.test.ts

@@ -0,0 +1,107 @@
+// fw#2165: buildListQueryPayload was extracted out of EntityListBody's
+// queryPayload useMemo so ProjectionListBody could reuse it without
+// duplicating the branch logic. This pins the extracted function against
+// exactly what EntityListBody built before the extraction — the regression
+// floor both list types now sit on.
+import { describe, expect, test } from "bun:test";
+import { buildListQueryPayload } from "../kumiko-screen";
+
+const base = {
+  limit: 50,
+  search: "",
+  sort: null,
+  usePager: false,
+  page: 1,
+  useInfinite: false,
+  cursor: undefined,
+} as const;
+
+describe("buildListQueryPayload", () => {
+  test("bare state: only limit, no search/sort/pager/infinite keys", () => {
+    expect(buildListQueryPayload(base)).toEqual({ limit: 50 });
+  });
+
+  test("empty search term is omitted, not sent as an empty string", () => {
+    expect(buildListQueryPayload({ ...base, search: "" })).toEqual({ limit: 50 });
+  });
+
+  test("non-empty search lands in the payload", () => {
+    expect(buildListQueryPayload({ ...base, search: "acme" })).toEqual({
+      limit: 50,
+      search: "acme",
+    });
+  });
+
+  test("no sort: neither sort nor sortDirection appear", () => {
+    expect(buildListQueryPayload({ ...base, sort: null })).toEqual({ limit: 50 });
+  });
+
+  test("sort carries both field and direction", () => {
+    expect(buildListQueryPayload({ ...base, sort: { field: "createdAt", dir: "desc" } })).toEqual({
+      limit: 50,
+      sort: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  test("pager mode, page 1: totalCount is sent, offset is omitted (not offset: 0)", () => {
+    expect(buildListQueryPayload({ ...base, usePager: true, page: 1 })).toEqual({
+      limit: 50,
+      totalCount: true,
+    });
+  });
+
+  test("pager mode, page 3: offset is (page - 1) * limit", () => {
+    expect(buildListQueryPayload({ ...base, usePager: true, page: 3 })).toEqual({
+      limit: 50,
+      offset: 100,
+      totalCount: true,
+    });
+  });
+
+  test("infinite mode without a cursor yet: no cursor key", () => {
+    expect(buildListQueryPayload({ ...base, useInfinite: true, cursor: undefined })).toEqual({
+      limit: 50,
+    });
+  });
+
+  test("infinite mode with a cursor: cursor lands in the payload", () => {
+    expect(buildListQueryPayload({ ...base, useInfinite: true, cursor: "row-42" })).toEqual({
+      limit: 50,
+      cursor: "row-42",
+    });
+  });
+
+  test("pager wins over infinite when both flags are true (usePager gates first)", () => {
+    expect(
+      buildListQueryPayload({ ...base, usePager: true, useInfinite: true, cursor: "row-42" }),
+    ).toEqual({ limit: 50, totalCount: true });
+  });
+
+  test("pagination=false (neither pager nor infinite): no pagination keys at all", () => {
+    expect(
+      buildListQueryPayload({ ...base, usePager: false, useInfinite: false, cursor: "row-42" }),
+    ).toEqual({ limit: 50 });
+  });
+
+  test("full combination: search + sort + pager", () => {
+    expect(
+      buildListQueryPayload({
+        limit: 25,
+        search: "acme",
+        sort: { field: "name", dir: "asc" },
+        usePager: true,
+        page: 2,
+        useInfinite: false,
+        cursor: undefined,
+      }),
+    ).toEqual({
+      limit: 25,
+      search: "acme",
+      sort: "name",
+      sortDirection: "asc",
+      offset: 25,
+      totalCount: true,
+    });
+  });
+});

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

@@ -0,0 +1,449 @@
+// fw#2166: projectionDetail screens can declare header `actions`, and get a
+// default "edit" action for free when `detailFor` names an entity that has a
+// visible entityEdit screen somewhere in the app (not just this feature —
+// the motivating case is a projectionDetail whose query belongs to one
+// feature while the entity's entityEdit screen lives in another). This
+// renders the real path (KumikoScreen → ProjectionDetailBody → RenderEdit)
+// under a stub dispatcher + AppFeaturesProvider, and proves the default-edit
+// resolution rules from the boot-validator's detailFor doc (cross-feature
+// lookup, access-gating, id: "edit" declared-action suppression).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  AccessRule,
+  EntityEditScreenDefinition,
+  ProjectionDetailScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, fireEvent, render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { UserRolesProvider } from "../../context/user-roles-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type BannerProps,
+  type ButtonProps,
+  type CorePrimitives,
+  type FormProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { AppFeaturesProvider } from "../app-features-context";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi, ScreenTarget } from "../nav";
+import { NavProvider } from "../nav";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) => (
+  <button type="button" data-testid={testId} onClick={() => void onClick?.()}>
+    {children}
+  </button>
+);
+
+// Form's `actions` slot carries the header buttons under test — passChildren
+// alone would drop it. Wrapped in distinct testid'd containers so a test can
+// assert a banner rendered as a Form CHILD (formError/actionError region)
+// rather than inside the actions row — the review finding this proves.
+const FormWithActions: ComponentType<FormProps> = ({ children, actions }) => (
+  <>
+    <div data-testid="form-body">{children}</div>
+    <div data-testid="form-actions">{actions}</div>
+  </>
+);
+
+// passChildren would drop testId — this test asserts on Banner structure/
+// placement, so it needs a real (if minimal) wrapper element.
+const TestBanner: ComponentType<BannerProps> = ({ children, testId }) => (
+  <div data-testid={testId}>{children}</div>
+);
+
+const testPrimitives: CorePrimitives = {
+  Button: TestButton,
+  Banner: TestBanner,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: FormWithActions,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function stubDispatcher(
+  record: Readonly<Record<string, unknown>>,
+  writeErrorMessage?: string,
+): Dispatcher {
+  const writeResult =
+    writeErrorMessage !== undefined
+      ? {
+          isSuccess: false,
+          error: {
+            code: "write-failed",
+            httpStatus: 500,
+            i18nKey: "kumiko.errors.does-not-exist-in-any-bundle",
+            message: writeErrorMessage,
+          },
+        }
+      : { isSuccess: true, data: {} };
+  return {
+    write: (async () => writeResult) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: record })) 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: () => [],
+  };
+}
+
+function detailScreen(
+  overrides?: Partial<ProjectionDetailScreenDefinition & { readonly detailFor?: string }>,
+): FeatureSchema["screens"][number] {
+  return {
+    id: "rent-detail",
+    type: "projectionDetail",
+    query: "app:query:rent:detail",
+    layout: { sections: [{ title: "s", fields: ["description"] }] },
+    detailFor: "rent",
+    ...overrides,
+  } as FeatureSchema["screens"][number];
+}
+
+// Registry-qualified id ("<feature>:screen:<short>"), matching real schema
+// output — a bare short id here would hide the QN-vs-short-form bug this
+// test suite exists to catch (fw#2166 review finding 1/4).
+function editScreen(
+  entity: string,
+  access?: AccessRule,
+  featureName = "app",
+): EntityEditScreenDefinition {
+  return {
+    id: `${featureName}:screen:rent-edit`,
+    type: "entityEdit",
+    entity,
+    layout: { sections: [{ columns: 1, fields: ["name"] }] },
+    ...(access !== undefined && { access }),
+  };
+}
+
+function renderDetail(opts: {
+  readonly primarySchema: FeatureSchema;
+  readonly features: readonly FeatureSchema[];
+  readonly userRoles?: readonly string[];
+  readonly record?: Readonly<Record<string, unknown>>;
+  readonly onNavigate?: (target: ScreenTarget) => void;
+  readonly writeErrorMessage?: string;
+}): ReturnType<typeof render> {
+  const navApi: NavApi = {
+    route: { screenId: "app:screen:rent-detail" },
+    // Header actions only ever navigate with a ScreenTarget (screenId +
+    // entityId) — same narrowing idiom as nav.tsx's resolveTarget.
+    navigate: (target) => {
+      if ("screenId" in target) opts.onNavigate?.(target);
+    },
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: () => {},
+  };
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider
+        dispatcher={stubDispatcher(
+          opts.record ?? { id: "rent-1", description: "Rent for April" },
+          opts.writeErrorMessage,
+        )}
+      >
+        <AppFeaturesProvider features={opts.features}>
+          <UserRolesProvider roles={opts.userRoles}>
+            <NavProvider value={navApi}>
+              <PrimitivesProvider value={testPrimitives}>
+                <KumikoScreen
+                  schema={opts.primarySchema}
+                  qn="app:screen:rent-detail"
+                  entityId="rent-1"
+                />
+              </PrimitivesProvider>
+            </NavProvider>
+          </UserRolesProvider>
+        </AppFeaturesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionDetail default edit action (fw#2166)", () => {
+  test("detailFor + matching entityEdit in the SAME feature → edit button navigates with the record id", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), editScreen("rent")],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    // trigger() is async (busy-state bookkeeping around onPress), so the
+    // click's state updates land after this tick — act() flushes them.
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
+  });
+
+  test("edit screen access denied → no edit button", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), editScreen("rent", { roles: ["admin"] })],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-edit")).toBeNull();
+  });
+
+  test("no entityEdit screen for the detailFor entity → no edit button", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen()],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-edit")).toBeNull();
+  });
+
+  test('a declared actions entry with id: "edit" wins — exactly one edit button, the declared one', async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            { kind: "navigate", id: "edit", label: "custom-edit-label", screen: "rent-edit" },
+          ],
+        }),
+        editScreen("rent"),
+      ],
+    };
+    const { getAllByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    const editButtons = getAllByTestId("render-edit-action-edit");
+    expect(editButtons).toHaveLength(1);
+    // "custom-edit-label" has no translation registered, so translate()
+    // returns the raw key — proving this is the declared action, not the
+    // default (which renders the translated "kumiko.actions.edit").
+    expect(editButtons[0]?.textContent).toBe("custom-edit-label");
+  });
+
+  test("two entityEdit screens for the same entity, only the second accessible → button still renders, targeting the second (review finding 2)", async () => {
+    const lockedEdit: EntityEditScreenDefinition = {
+      id: "app:screen:rent-edit-locked",
+      type: "entityEdit",
+      entity: "rent",
+      layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      access: { roles: ["admin"] },
+    };
+    const openEdit: EntityEditScreenDefinition = {
+      id: "app:screen:rent-edit-open",
+      type: "entityEdit",
+      entity: "rent",
+      layout: { sections: [{ columns: 1, fields: ["name"] }] },
+    };
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), lockedEdit, openEdit],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit-open", entityId: "rent-1" });
+  });
+
+  test("declared navigate action without entityId, targeting an entityEdit of the SAME entity → auto-fills the record id (review finding 3)", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "navigate",
+              id: "open-record",
+              label: "actions.openRecord",
+              screen: "rent-edit",
+            },
+          ],
+        }),
+        editScreen("rent"),
+      ],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-open-record"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
+  });
+
+  test("declared action with a non-matching visible condition → no button rendered", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "navigate",
+              id: "archive",
+              label: "actions.archive",
+              screen: "rent-edit",
+              visible: { field: "status", eq: "closed" },
+            },
+          ],
+        }),
+      ],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      record: { id: "rent-1", description: "Rent for April", status: "open" },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-archive")).toBeNull();
+  });
+
+  test("entityEdit screen lives in ANOTHER feature → edit button is still there (cross-feature resolution)", async () => {
+    const appSchema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen()],
+    };
+    const billingSchema: FeatureSchema = {
+      featureName: "billing",
+      entities: {},
+      screens: [editScreen("rent", undefined, "billing")],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: appSchema,
+      features: [appSchema, billingSchema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    // trigger() is async (busy-state bookkeeping around onPress), so the
+    // click's state updates land after this tick — act() flushes them.
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
+  });
+
+  test("a failed writeHandler action shows its error in the shared error region, NOT inside the action button row", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "writeHandler",
+              id: "archive",
+              label: "actions.archive",
+              handler: "app:write:archive",
+            },
+          ],
+        }),
+      ],
+    };
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      writeErrorMessage: "archive failed: rent is still active",
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-archive"));
+    });
+
+    const errorBanner = await waitFor(() => getByTestId("render-edit-action-error"));
+    expect(errorBanner.textContent).toBe("archive failed: rent is still active");
+    // The banner must be a Form child (formError-adjacent region), not a
+    // descendant of the actions row — a full-width Banner inside the
+    // `justify-end` button row breaks its layout (fw#2166 review finding 5).
+    expect(errorBanner.closest('[data-testid="form-body"]')).not.toBeNull();
+    expect(errorBanner.closest('[data-testid="form-actions"]')).toBeNull();
+    expect(
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+    ).not.toBeNull();
+  });
+});