@cosmicdrift/kumiko-framework 0.224.1 → 0.225.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.224.1",
+  "version": "0.225.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.224.1",
+    "@cosmicdrift/kumiko-types": "0.225.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.224.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.225.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/boot-validator.test.ts

@@ -4099,7 +4099,7 @@ describe("boot-validator — config key backing × scope", () => {
     expect(() => validateBoot([feature])).not.toThrow();
   });
 
-  test("navigate with params targeting a dashboard screen → Throw", () => {
+  test("navigate with params targeting a dashboard screen without a filter → Throw (params would be a no-op)", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", createEntity({ fields: { name: createTextField() } }));
       r.screen({
@@ -4135,7 +4135,97 @@ describe("boot-validator — config key backing × scope", () => {
       });
     });
     expect(() => validateBoot([feature])).toThrow(
-      /sets params on navigate-target "product-dashboard".*screen type "dashboard".*only actionForm and entityEdit-create/,
+      /sets params on navigate-target "product-dashboard" \(dashboard\).*declares no filter.*no-op/,
+    );
+  });
+
+  test("navigate with params targeting a dashboard screen with a matching filter → no throw (useFilterParams reads it, fw#1708 follow-up)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "actions.view",
+            screen: "product-dashboard",
+            params: { map: { category: "name" } },
+          },
+        ],
+      });
+      r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "product-dashboard",
+        type: "dashboard",
+        filter: {
+          id: "category",
+          label: "Category",
+          kind: "select",
+          options: [{ value: "a", label: "A" }],
+        },
+        panels: [
+          {
+            kind: "stat",
+            id: "count",
+            label: "Products",
+            query: "shop:query:count",
+            valueField: "total",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate with params targeting a dashboard screen whose filter id doesn't match any extracted key → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "actions.view",
+            screen: "product-dashboard",
+            params: { map: { productName: "name" } },
+          },
+        ],
+      });
+      r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "product-dashboard",
+        type: "dashboard",
+        filter: {
+          id: "category",
+          label: "Category",
+          kind: "select",
+          options: [{ value: "a", label: "A" }],
+        },
+        panels: [
+          {
+            kind: "stat",
+            id: "count",
+            label: "Products",
+            query: "shop:query:count",
+            valueField: "total",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /sets params \[productName\] on navigate-target "product-dashboard" \(dashboard\) whose filter id is "category".*none of the extracted keys match/,
     );
   });
 

package/src/engine/__tests__/build-app-schema.test.ts

@@ -12,7 +12,7 @@ import { z } from "zod";
 import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
-import type { EntityDefinition } from "../types/fields";
+import type { EntityDefinition, MultiSelectFieldDef } from "../types/fields";
 import type { ProjectionListScreenDefinition } from "../types/screen";
 
 describe("buildAppSchema", () => {
@@ -314,6 +314,141 @@ describe("buildAppSchema", () => {
     expect(fields["name"]?.["searchable"]).toBeUndefined();
   });
 
+  test("MultiSelect: display/columns/maxRows überleben die Projection (fw#2494)", () => {
+    // Regression: without display in the client schema, render-field.tsx's
+    // `field.display === "checkboxes"` check always falls through → the
+    // renderer always shows the combobox, MultiSelectCheckboxes is unreachable.
+    const entity = {
+      fields: {
+        tags: {
+          type: "multiSelect",
+          options: ["a", "b", "c"],
+          display: "checkboxes",
+          columns: 3,
+          maxRows: 5,
+        },
+        categories: { type: "multiSelect", options: ["x", "y"] },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["tags"]?.["display"]).toBe("checkboxes");
+    expect(fields["tags"]?.["columns"]).toBe(3);
+    expect(fields["tags"]?.["maxRows"]).toBe(5);
+    // Fields without display/columns/maxRows don't carry the keys (no false-litter).
+    expect(fields["categories"]?.["display"]).toBeUndefined();
+    expect(fields["categories"]?.["columns"]).toBeUndefined();
+    expect(fields["categories"]?.["maxRows"]).toBeUndefined();
+  });
+
+  test("MultiSelectFieldDef: alle Keys sind in projectField bewusst eingeordnet", () => {
+    // Bounded completeness check, scoped to MultiSelectFieldDef's own key set
+    // (packages/types/src/fields.ts) — NOT a general FieldDefinition lockstep.
+    // A full-union version would have to classify every property of all 20
+    // FieldDefinition variants as forwarded or server-only, and several are
+    // known-forwarded-but-missing today (e.g. image's `capture`, embedded's
+    // `schema`/`derived`/`totals`/`minItems`/`maxItems`, date's
+    // `min`/`max`/`locale`, longText's `multiline`) — declaring those
+    // "server-only" here would be a false claim, and fixing them is out of
+    // scope for fw#2494 (see report for the full gap list). This check only
+    // covers the type this fix actually touches.
+    //
+    // The `_allKeysClassified` assignment below is the actual guard: if
+    // MultiSelectFieldDef ever gains a key that isn't in one of the three
+    // lists, `Exclude<keyof MultiSelectFieldDef, Classified>` stops being
+    // `never` and the assignment fails to typecheck — `bun run typecheck`
+    // (part of `bun run kumiko check`) catches it even without touching this
+    // test's runtime assertions.
+    const FORWARDED_KEYS = [
+      "type",
+      "required",
+      "filterable",
+      "options",
+      "display",
+      "columns",
+      "maxRows",
+    ] as const;
+
+    const SERVER_ONLY_KEYS = [
+      "sensitive", // controls write-response redaction, never rendered
+      "access", // server-side authz check, not a renderer concern
+      "pii", // PII classification, drives crypto/storage — not client-relevant
+      "userOwned", // same: subject-key annotation, server/crypto-only
+      "tenantOwned", // same: subject-key annotation, server/crypto-only
+      "anonymize", // retention-cleanup callback, never serializable to JSON
+      "allowPlaintext", // PII-audit reason string, not a renderer concern
+      "lookupable", // blind-index equality lookup, server-side query concern
+      "subjectRef", // GDPR-hook-coverage marker, not a renderer concern
+    ] as const;
+
+    // Keys that ARE client-relevant in principle but aren't forwarded today —
+    // pre-existing gaps, each with its own reason, none introduced by fw#2494.
+    const KNOWN_GAP_KEYS = [
+      "default", // array-valued for multiSelect, but projectField's isLiteral()
+      // only accepts string/number/boolean/null — so array defaults are
+      // silently dropped, never a real server-only property. Verified
+      // empirically: a multiSelect field with `default: ["a"]` projects to
+      // no `default` key at all. Separate pre-existing bug, out of scope here.
+    ] as const;
+
+    type Classified =
+      | (typeof FORWARDED_KEYS)[number]
+      | (typeof SERVER_ONLY_KEYS)[number]
+      | (typeof KNOWN_GAP_KEYS)[number];
+    const _allKeysClassified: Exclude<keyof MultiSelectFieldDef, Classified> extends never
+      ? true
+      : never = true;
+
+    const entity = {
+      fields: {
+        tags: {
+          type: "multiSelect",
+          required: true,
+          filterable: true,
+          options: ["a", "b"],
+          display: "checkboxes",
+          columns: 2,
+          maxRows: 4,
+          sensitive: true,
+          access: { read: ["admin"] },
+          pii: true,
+          userOwned: { ownerField: "authorId" },
+          tenantOwned: true,
+          anonymize: () => "[ANONYMIZED]",
+          allowPlaintext: "is_business_data",
+          lookupable: true,
+          subjectRef: true,
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projected = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields["tags"] as Record<string, unknown>;
+
+    for (const key of FORWARDED_KEYS) {
+      expect(projected[key]).toBeDefined();
+    }
+    for (const key of SERVER_ONLY_KEYS) {
+      expect(projected[key]).toBeUndefined();
+    }
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

package/src/engine/__tests__/projection-detail-tabs.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// Akten-Layout: projectionDetail `layout.mode: "tabs"` + `header`/`metrics`.
+describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
+  test("mode: tabs with only one section throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          mode: "tabs",
+          sections: [{ id: "overview", title: "Overview", fields: ["description"] }],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/tabs need at least 2 sections/);
+  });
+
+  test("tabs section without a title throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", fields: ["description"] },
+            { id: "history", title: "History", fields: ["notes"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/sections\[0\] has no title/);
+  });
+
+  test("tabs section without an id throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { title: "Overview", fields: ["description"] },
+            { id: "history", title: "History", fields: ["notes"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/sections\[0\] \("Overview"\) has no id/);
+  });
+
+  test("tabs section id that is not kebab-case throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "Overview", title: "Overview", fields: ["description"] },
+            { id: "history", title: "History", fields: ["notes"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/must be kebab-case/);
+  });
+
+  test("duplicate tab ids throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["description"] },
+            { id: "overview", title: "History", fields: ["notes"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/duplicate tab id "overview"/);
+  });
+
+  test("mode: tabs on entityEdit throws — tabs are projectionDetail-only", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("rent", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", columns: 1, fields: ["name"] },
+            { id: "history", title: "History", columns: 1, fields: ["name"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "rent-edit" \(entityEdit\) sets mode: "tabs" — tabs are only supported on projectionDetail/,
+    );
+  });
+
+  test("metric without a fieldLabels entry throws — no fallback to the raw column name", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        metrics: ["balance"],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/metric "balance" has no entry in fieldLabels/);
+  });
+
+  test("valid tabs + header + metrics declaration boots cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        header: { title: "name", subtitle: "address", status: "state" },
+        metrics: ["balance", "overdueDays"],
+        fieldLabels: { balance: "rent.balance", overdueDays: "rent.overdueDays" },
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["description"] },
+            { id: "history", title: "History", fields: ["notes"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/boot-validator/screens.ts

@@ -6,7 +6,7 @@
 
 import { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 import { rowMetaFieldNames } from "../../db/table-builder";
-import { isValidQn, qualifyEntityName } from "../qualified-name";
+import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition } from "../types";
@@ -83,6 +83,14 @@ function validateNoWidgetRequiredField(
 // entityList and projectionList (framework#1708) — projectionList has no
 // `screen.entity`, so there's no same-entity row["id"] auto-fill case: any
 // entityEdit target without an explicit entityId reaches create there.
+//
+// dashboard targets (framework#1708 follow-up, commit 4e0d6cb26) also read
+// URL search params — but only for the single `filter.id` a dashboard
+// declares (useFilterParams in dashboard-body.tsx seeds its value from
+// `nav.searchParams[filter.id]`). A dashboard with no `filter` has nowhere
+// for the value to land, and a params extractor whose keys don't include
+// the filter's id would silently miss it — both are boot errors instead of
+// a silently-empty dashboard.
 function validateRowActionNavigateParams(
   featureName: string,
   screenId: string,
@@ -93,16 +101,38 @@ function validateRowActionNavigateParams(
 ): void {
   // skip: not a navigate-with-params action — nothing to validate here.
   if (action.kind !== "navigate" || action.params === undefined) return;
-  // entityList/projectionList targets also read URL search params (Tier
+  // skip: unresolvable/custom target already reported (or exempt) elsewhere.
+  if (target === undefined || target.screen.type === "custom") return;
+  // skip: entityList/projectionList targets also read URL search params (Tier
   // 2.7c filter-prefill, see use-list-url-state.ts: `<screenId>.q/.sort/
   // .dir/.page/.f.<field>`), not just actionForm/entityEdit-create.
-  const exemptTargetType =
-    target === undefined ||
-    target.screen.type === "custom" ||
-    target.screen.type === "entityList" ||
-    target.screen.type === "projectionList";
-  // skip: unresolvable/custom/list target already reported (or exempt) elsewhere.
-  if (exemptTargetType) return;
+  if (target.screen.type === "entityList" || target.screen.type === "projectionList") return;
+
+  if (target.screen.type === "dashboard") {
+    const targetDescriptor =
+      action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
+    const filter = target.screen.filter;
+    if (filter === undefined) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" sets ` +
+          `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
+          `filter — params would be a no-op. Remove the params extractor, or add a \`filter\` to the ` +
+          `target dashboard so it has somewhere to read the value from.`,
+      );
+    }
+    const extractedKeys =
+      "pick" in action.params ? action.params.pick : Object.keys(action.params.map);
+    if (!extractedKeys.includes(filter.id)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" sets ` +
+          `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
+          `filter id is "${filter.id}" — none of the extracted keys match, so the filter would stay ` +
+          `unset. Fix the params extractor to produce a "${filter.id}" key, or remove it.`,
+      );
+    }
+    // skip: filter present and the extractor's keys cover it — valid dashboard deep-link.
+    return;
+  }
 
   const isEntityEditUpdate =
     target.screen.type === "entityEdit" &&
@@ -140,6 +170,17 @@ function validateWizardLayout(
   layout: EditLayout,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
+  // Tabs truncate the layout to one section, but scopeFieldNames derives
+  // required-field validation from the `fields` prop, not from layout — a
+  // hidden tab could hide a required field and silently block submit.
+  // projectionDetail has no submit, so tabs are safe there (see its own
+  // branch in validateScreens) but not here.
+  if (layout.mode === "tabs") {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets mode: "tabs" — tabs are only ` +
+        `supported on projectionDetail. Use mode: "wizard" or "single" instead.`,
+    );
+  }
   // "form-draft" is hardcoded because the framework layer must not depend on
   // @cosmicdrift/kumiko-bundled-features — same precedence as the
   // "user-data-rights" check in gdpr-storage.ts.
@@ -572,6 +613,54 @@ export function validateScreens(
             `declare at least one section.`,
         );
       }
+      if (screen.layout.mode === "tabs") {
+        if (screen.layout.sections.length < 2) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but only ` +
+              `${screen.layout.sections.length} section(s) — tabs need at least 2 sections.`,
+          );
+        }
+        const tabIds = new Set<string>();
+        screen.layout.sections.forEach((section, index) => {
+          if (section.title === undefined || section.title.trim().length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but ` +
+                `sections[${index}] has no title — every tab needs a title.`,
+            );
+          }
+          if (section.id === undefined || section.id.trim().length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but ` +
+                `sections[${index}] ("${section.title}") has no id — every tab needs a stable id for ` +
+                `the ?tab= param.`,
+            );
+          }
+          if (!isKebabSegment(section.id)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sections[${index}] ` +
+                `("${section.title}") has id "${section.id}" — must be kebab-case.`,
+            );
+          }
+          if (tabIds.has(section.id)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has duplicate tab id ` +
+                `"${section.id}" (sections[${index}]).`,
+            );
+          }
+          tabIds.add(section.id);
+        });
+      }
+      if (screen.metrics !== undefined) {
+        for (const metric of screen.metrics) {
+          if (screen.fieldLabels?.[metric] === undefined) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${metric}" has ` +
+                `no entry in fieldLabels — every metrics field needs a label, there is no fallback to ` +
+                `the raw column name.`,
+            );
+          }
+        }
+      }
       for (const section of screen.layout.sections) {
         if (isExtensionEditSection(section)) {
           throw new Error(

package/src/engine/build-app-schema.ts

@@ -428,6 +428,12 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (typeof def["entity"] === "string") out["entity"] = def["entity"];
   if (typeof def["labelField"] === "string") out["labelField"] = def["labelField"];
   if (typeof def["multiple"] === "boolean") out["multiple"] = def["multiple"];
+  // MultiSelect: display picks checkboxes vs. combobox in the renderer,
+  // columns/maxRows size the checkbox grid — without these the renderer
+  // always falls back to the combobox (fw#2494).
+  if (typeof def["display"] === "string") out["display"] = def["display"];
+  if (typeof def["columns"] === "number") out["columns"] = def["columns"];
+  if (typeof def["maxRows"] === "number") out["maxRows"] = def["maxRows"];
   return out as FieldDefinition; // @cast-boundary schema-walk
 }