@cosmicdrift/kumiko-framework 0.224.2 → 0.225.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.224.2",
+  "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.2",
+    "@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.2",
+    "@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__/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(