@cosmicdrift/kumiko-framework 0.258.1 → 0.259.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.258.1",
+  "version": "0.259.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.258.1",
+    "@cosmicdrift/kumiko-types": "0.259.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.258.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.259.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.259.0",
+    "type": "improvement",
+    "title": "Dashboard screens compose other declarative screens via kind: \"screen\" panels (fw#2844, decision fw#2841).",
+    "detail": "`DashboardScreenPanel` (`@cosmicdrift/kumiko-types`) embeds a registered screen by same-feature short id or `<feature>:screen:<id>`; embeddable are projectionList, actionForm, secretMint, configEdit, secretsEdit — the boot validator rejects unresolvable targets and dashboard/entityEdit/projectionDetail/custom/entityList. `visibleWhen: { query, field, eq }` shows the panel only while the live query's flat result matches (query boot-checked). A user without access to the target gets no tile. `DashboardBodyProps` gains the required `featureName` (only relevant for a custom dashboard body implementation); `useEmbeddedScreen` is exported from `@cosmicdrift/kumiko-renderer`. Replaces \"framework screen plus own content\" custom screens with an app-feature-structure lint-ignore."
+  },
   {
     "version": "0.242.0",
     "type": "improvement",

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

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { requiredKeysFromScreen } from "../../i18n/required-surface-keys";
 import { validateBoot } from "../boot-validator";
 import { defineFeature } from "../define-feature";
-import type { DashboardScreenDefinition } from "../types/screen";
+import type { DashboardScreenDefinition, DashboardScreenPanel } from "../types/screen";
 
 const STAT_PANEL = {
   kind: "stat",
@@ -242,3 +242,140 @@ describe("validateBoot — dashboard screens", () => {
     expect(keys).not.toContain("custom-panel");
   });
 });
+
+const catalogFeature = defineFeature("catalog", (r) => {
+  r.queryHandler("items:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+    access: { openToAll: true },
+  });
+  r.queryHandler("items:status", z.object({}), async () => ({ enabled: true }), {
+    access: { openToAll: true },
+  });
+  r.screen({
+    id: "items",
+    type: "projectionList",
+    query: "catalog:query:items:list",
+    columns: ["name"],
+  });
+  r.screen({
+    id: "items-overview",
+    type: "dashboard",
+    panels: [STAT_PANEL],
+  });
+  r.translations({
+    keys: {
+      "screen:items.title": { de: "Artikel", en: "Items" },
+      "screen:items-overview.title": { de: "Übersicht", en: "Overview" },
+      "demo:dashboard:panel:open-incidents": { de: "Offene Vorfälle", en: "Open incidents" },
+    },
+  });
+});
+
+function screenPanelFeature(panel: DashboardScreenPanel) {
+  return dashboardFeature([STAT_PANEL, panel]);
+}
+
+describe("validateBoot — dashboard screen panels (fw#2841)", () => {
+  test("accepts a cross-feature projectionList target with a registered visibleWhen query", () => {
+    const feature = screenPanelFeature({
+      kind: "screen",
+      id: "items",
+      screen: "catalog:screen:items",
+      label: "demo:dashboard:panel:latest",
+      visibleWhen: { query: "catalog:query:items:status", field: "enabled", eq: true },
+    });
+    expect(() => validateBoot([feature, catalogFeature])).not.toThrow();
+  });
+
+  test("accepts a same-feature short id", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.queryHandler("items:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "items",
+        type: "projectionList",
+        query: "demo:query:items:list",
+        columns: ["name"],
+      });
+      r.screen({
+        id: "overview",
+        type: "dashboard",
+        panels: [{ kind: "screen", id: "items", screen: "items" }],
+      });
+      r.translations({
+        keys: {
+          "screen:items.title": { de: "Artikel", en: "Items" },
+          "screen:overview.title": { de: "Übersicht", en: "Overview" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects a target that resolves to no registered screen", () => {
+    const feature = screenPanelFeature({
+      kind: "screen",
+      id: "items",
+      screen: "catalog:screen:ghost",
+    });
+    expect(() => validateBoot([feature, catalogFeature])).toThrow(
+      /screen-panel "items" screen "catalog:screen:ghost" does not resolve/,
+    );
+  });
+
+  test("rejects a short id that only exists in another feature", () => {
+    const feature = screenPanelFeature({ kind: "screen", id: "items", screen: "items" });
+    expect(() => validateBoot([feature, catalogFeature])).toThrow(/checked "demo:screen:items"/);
+  });
+
+  test("rejects embedding a dashboard (no nesting)", () => {
+    const feature = screenPanelFeature({
+      kind: "screen",
+      id: "nested",
+      screen: "catalog:screen:items-overview",
+    });
+    expect(() => validateBoot([feature, catalogFeature])).toThrow(
+      /of type "dashboard", which can't be embedded/,
+    );
+  });
+
+  test("rejects a visibleWhen query that is not registered", () => {
+    const feature = screenPanelFeature({
+      kind: "screen",
+      id: "items",
+      screen: "catalog:screen:items",
+      visibleWhen: { query: "catalog:query:items:ghost", field: "enabled", eq: true },
+    });
+    expect(() => validateBoot([feature, catalogFeature])).toThrow(
+      /screen-panel "items" visibleWhen query "catalog:query:items:ghost" is not a registered query-handler/,
+    );
+  });
+
+  test("rejects a visibleWhen with an empty field", () => {
+    const feature = screenPanelFeature({
+      kind: "screen",
+      id: "items",
+      screen: "catalog:screen:items",
+      visibleWhen: { query: "catalog:query:items:status", field: "", eq: true },
+    });
+    expect(() => validateBoot([feature, catalogFeature])).toThrow(
+      /visibleWhen needs a non-empty query and field/,
+    );
+  });
+
+  test("requiredKeysFromScreen sammelt ein gesetztes Screen-Panel-Label", () => {
+    const screen: DashboardScreenDefinition = {
+      id: "overview",
+      type: "dashboard",
+      panels: [
+        {
+          kind: "screen",
+          id: "items",
+          screen: "catalog:screen:items",
+          label: "demo:dashboard:panel:latest",
+        },
+      ],
+    };
+    expect(requiredKeysFromScreen("demo", screen)).toContain("demo:dashboard:panel:latest");
+  });
+});

package/src/engine/boot-validator/query-refs.ts

@@ -56,6 +56,17 @@ function checkDashboardQueryRefs(
 ): void {
   for (const panel of screen.panels) {
     if (panel.kind === "custom") continue;
+    if (panel.kind === "screen") {
+      if (panel.visibleWhen !== undefined) {
+        checkQueryRef(
+          queryHandlers,
+          panel.visibleWhen.query,
+          () =>
+            `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}" visibleWhen`,
+        );
+      }
+      continue;
+    }
     if (panel.kind === "stat-group") {
       for (const stat of panel.stats) {
         checkQueryRef(

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

@@ -23,6 +23,7 @@ import type {
   DashboardFilterDefinition,
   DashboardPanelDefinition,
   DashboardScreenDefinition,
+  DashboardScreenPanel,
   DashboardStatGroupPanel,
   EditFieldSpec,
   EditLayout,
@@ -1234,7 +1235,7 @@ export function validateScreens(
     }
 
     if (screen.type === "dashboard") {
-      validateDashboardScreen(feature.name, screenId, screen);
+      validateDashboardScreen(feature.name, screenId, screen, featureMap);
       continue;
     }
 
@@ -1807,6 +1808,7 @@ function validateDashboardScreen(
   featureName: string,
   screenId: string,
   screen: DashboardScreenDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
   if (screen.panels.length === 0) {
     throw new Error(
@@ -1830,6 +1832,8 @@ function validateDashboardScreen(
       validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelId);
     } else if (panel.kind === "custom") {
       validateDashboardCustomPanel(featureName, screenId, panel);
+    } else if (panel.kind === "screen") {
+      validateDashboardScreenPanel(featureName, screenId, panel, featureMap);
     } else {
       validateDashboardQueryPanel(featureName, screenId, panel);
     }
@@ -1840,6 +1844,42 @@ function validateDashboardScreen(
   }
 }
 
+const EMBEDDABLE_SCREEN_TYPES: ReadonlySet<ScreenDefinition["type"]> = new Set([
+  "projectionList",
+  "actionForm",
+  "secretMint",
+  "configEdit",
+  "secretsEdit",
+]);
+
+function validateDashboardScreenPanel(
+  featureName: string,
+  screenId: string,
+  panel: DashboardScreenPanel,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`;
+  const targetQn = resolveScreenTargetQn(featureName, panel.screen);
+  const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
+  const target = featureMap.get(targetFeatureName)?.screens[targetShortId];
+  if (target === undefined) {
+    throw new Error(
+      `${context} screen "${panel.screen}" does not resolve to a registered screen (checked "${targetQn}"). ` +
+        `Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`,
+    );
+  }
+  if (!EMBEDDABLE_SCREEN_TYPES.has(target.type)) {
+    throw new Error(
+      `${context} embeds "${targetQn}" of type "${target.type}", which can't be embedded — allowed: ` +
+        `${[...EMBEDDABLE_SCREEN_TYPES].join(", ")}. Use a custom panel for app components.`,
+    );
+  }
+  const visibleWhen = panel.visibleWhen;
+  if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
+    throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
+  }
+}
+
 function validateDashboardStatGroupPanel(
   featureName: string,
   screenId: string,
@@ -1882,7 +1922,10 @@ function validateDashboardCustomPanel(
 function validateDashboardQueryPanel(
   featureName: string,
   screenId: string,
-  panel: Exclude<DashboardPanelDefinition, DashboardStatGroupPanel | DashboardCustomPanel>,
+  panel: Exclude<
+    DashboardPanelDefinition,
+    DashboardStatGroupPanel | DashboardCustomPanel | DashboardScreenPanel
+  >,
 ): void {
   if (!panel.query || typeof panel.query !== "string") {
     throw new Error(

package/src/engine/index.ts

@@ -333,8 +333,10 @@ export type {
   DashboardFilterDefinition,
   DashboardListPanel,
   DashboardPanelDefinition,
+  DashboardPanelVisibility,
   DashboardProgressListPanel,
   DashboardScreenDefinition,
+  DashboardScreenPanel,
   DashboardStatGroupPanel,
   DashboardStatPanel,
   DateFieldDef,

package/src/engine/types/index.ts

@@ -270,8 +270,10 @@ export type {
   DashboardFilterDefinition,
   DashboardListPanel,
   DashboardPanelDefinition,
+  DashboardPanelVisibility,
   DashboardProgressListPanel,
   DashboardScreenDefinition,
+  DashboardScreenPanel,
   DashboardStatGroupPanel,
   DashboardStatPanel,
   EditExtensionSection,

package/src/ui-types/index.ts

@@ -66,8 +66,10 @@ export type {
   DashboardFilterDefinition,
   DashboardListPanel,
   DashboardPanelDefinition,
+  DashboardPanelVisibility,
   DashboardProgressListPanel,
   DashboardScreenDefinition,
+  DashboardScreenPanel,
   DashboardStatGroupPanel,
   DashboardStatPanel,
   EditExtensionSection,