@cosmicdrift/kumiko-framework 0.130.2 → 0.131.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.130.2",
+  "version": "0.131.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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.130.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.131.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import { requiredKeysFromScreen } from "../../i18n/required-surface-keys";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import type { DashboardScreenDefinition } from "../types/screen";
+
+const STAT_PANEL = {
+  kind: "stat",
+  id: "open-incidents",
+  label: "demo:dashboard:panel:open-incidents",
+  query: "demo:query:incident:open-count",
+  valueField: "count",
+} as const;
+
+function dashboardFeature(panels: DashboardScreenDefinition["panels"]) {
+  return defineFeature("demo", (r) => {
+    r.screen({ id: "overview", type: "dashboard", panels });
+    r.translations({
+      keys: {
+        "screen:overview.title": { de: "Übersicht", en: "Overview" },
+        "demo:dashboard:panel:open-incidents": { de: "Offene Vorfälle", en: "Open incidents" },
+        "demo:dashboard:panel:latest": { de: "Neueste", en: "Latest" },
+        "demo:dashboard:col:name": { de: "Name", en: "Name" },
+      },
+    });
+  });
+}
+
+describe("validateBoot — dashboard screens", () => {
+  test("accepts a valid stat + list panel set", () => {
+    const feature = dashboardFeature([
+      STAT_PANEL,
+      {
+        kind: "list",
+        id: "latest",
+        label: "demo:dashboard:panel:latest",
+        query: "demo:query:incident:latest",
+        columns: [{ field: "name", label: "demo:dashboard:col:name" }],
+      },
+    ]);
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects an empty panels list", () => {
+    const feature = dashboardFeature([]);
+    expect(() => validateBoot([feature])).toThrow(/empty panels list/);
+  });
+
+  test("rejects duplicate panel ids", () => {
+    const feature = dashboardFeature([STAT_PANEL, STAT_PANEL]);
+    expect(() => validateBoot([feature])).toThrow(/duplicate panel id/);
+  });
+
+  test("rejects a stat panel with empty valueField", () => {
+    const feature = dashboardFeature([{ ...STAT_PANEL, valueField: "" }]);
+    expect(() => validateBoot([feature])).toThrow(/empty valueField/);
+  });
+
+  test("rejects a list panel without columns", () => {
+    const feature = dashboardFeature([
+      {
+        kind: "list",
+        id: "latest",
+        label: "demo:dashboard:panel:latest",
+        query: "demo:query:incident:latest",
+        columns: [],
+      },
+    ]);
+    expect(() => validateBoot([feature])).toThrow(/empty columns list/);
+  });
+
+  test("requiredKeysFromScreen sammelt Panel- und Column-Labels", () => {
+    const screen: DashboardScreenDefinition = {
+      id: "overview",
+      type: "dashboard",
+      panels: [
+        STAT_PANEL,
+        {
+          kind: "list",
+          id: "latest",
+          label: "demo:dashboard:panel:latest",
+          query: "demo:query:incident:latest",
+          columns: [{ field: "name", label: "demo:dashboard:col:name" }],
+        },
+      ],
+    };
+    const keys = requiredKeysFromScreen("demo", screen);
+    expect(keys).toContain("screen:overview.title");
+    expect(keys).toContain("demo:dashboard:panel:open-incidents");
+    expect(keys).toContain("demo:dashboard:panel:latest");
+    expect(keys).toContain("demo:dashboard:col:name");
+  });
+});

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

@@ -4,6 +4,7 @@ import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
 import type {
+  DashboardScreenDefinition,
   FieldCondition,
   RowAction,
   RowFieldExtractor,
@@ -162,6 +163,11 @@ export function validateScreens(
       continue;
     }
 
+    if (screen.type === "dashboard") {
+      validateDashboardScreen(feature.name, screenId, screen);
+      continue;
+    }
+
     if (screen.type === "configEdit") {
       // configEdit: layout/fields wie actionForm validieren, plus
       // Cross-Check dass jeder qualifizierte Config-Key registriert
@@ -634,6 +640,51 @@ export function validateScreens(
   }
 }
 
+// Panel-getrieben, keine Entity — Struktur-Checks (eindeutige Panel-Ids,
+// non-empty Queries/Columns/valueField); die Query-Contracts (Stat-Record,
+// Points-Envelope, Paged-Rows) werden zur Render-Zeit aufgelöst.
+function validateDashboardScreen(
+  featureName: string,
+  screenId: string,
+  screen: DashboardScreenDefinition,
+): void {
+  if (screen.panels.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) has an empty panels list — ` +
+        `declare at least one panel.`,
+    );
+  }
+  const panelIds = new Set<string>();
+  for (const panel of screen.panels) {
+    if (panelIds.has(panel.id)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${panel.id}".`,
+      );
+    }
+    panelIds.add(panel.id);
+    if (!panel.query || typeof panel.query !== "string") {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query.`,
+      );
+    }
+    if (panel.kind === "stat" && panel.valueField.length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`,
+      );
+    }
+    if (panel.kind === "list") {
+      if (panel.columns.length === 0) {
+        throw new Error(
+          `[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list.`,
+        );
+      }
+      for (const col of panel.columns) {
+        validateColumnRendererForm(featureName, screenId, normalizeListColumn(col));
+      }
+    }
+  }
+}
+
 // Form-check für ListColumn-Renderer in der PlatformComponent-Form
 // (`{ react: { __component: "Name" } }`). Der Server kennt die client-
 // seitige columnRenderers-Map nicht — also nur prüfen ob die Struktur

package/src/engine/types/index.ts

@@ -219,6 +219,11 @@ export type {
   ConfigEditScreenDefinition,
   CustomScreenDefinition,
   CustomScreenRoute,
+  DashboardChartPanel,
+  DashboardListPanel,
+  DashboardPanelDefinition,
+  DashboardScreenDefinition,
+  DashboardStatPanel,
   EditExtensionSection,
   EditFieldSpec,
   EditFieldsSection,

package/src/engine/types/screen.ts

@@ -324,6 +324,64 @@ export type ProjectionListScreenDefinition = {
   readonly access?: AccessRule;
 };
 
+// --- dashboard ---
+
+// Deklaratives Panel-Grid — Kennzahlen, Verläufe und Kurzlisten ohne
+// Custom-JSX. Jedes Panel zieht seine Daten aus einer eigenen Query
+// (fully-qualified QN, cross-feature erlaubt wie projectionList).
+// Formatierung ist Sache des Query-Handlers: Stat-Werte kommen als
+// anzeigefertige Strings/Zahlen aus der Read-Projection (ES-Read-Models
+// shapen ihre Daten selbst; der Renderer formatiert nicht nach).
+
+// Query-Result-Contract: flaches Record; `valueField` zeigt auf den
+// anzeigefertigen Wert, `subField` optional auf eine Sub-Zeile,
+// `toneField` optional auf "default" | "positive" | "warn".
+export type DashboardStatPanel = {
+  readonly kind: "stat";
+  /** Stable id — kebab-case, eindeutig im Panel-Set. */
+  readonly id: string;
+  /** Anzeige-Text (i18n-Key). */
+  readonly label: string;
+  readonly query: string;
+  readonly valueField: string;
+  readonly subField?: string;
+  readonly toneField?: string;
+};
+
+// Query-Result-Contract: `{ points: { atMs, value | null }[],
+// windowStartMs, windowEndMs }` — value=null zeichnet einen Einbruch.
+export type DashboardChartPanel = {
+  readonly kind: "chart";
+  readonly id: string;
+  readonly label: string;
+  /** v1: geglättete Zeitreihe. Weitere Chart-Formen additiv. */
+  readonly chart: "timeseries";
+  readonly query: string;
+};
+
+// Kurzliste im Dashboard — Query-Contract wie projectionList
+// (`{ rows, nextCursor, total? }`), gerendert ohne Pager/Toolbar.
+export type DashboardListPanel = {
+  readonly kind: "list";
+  readonly id: string;
+  readonly label: string;
+  readonly query: string;
+  readonly columns: readonly ListColumnSpec[];
+};
+
+export type DashboardPanelDefinition =
+  | DashboardStatPanel
+  | DashboardChartPanel
+  | DashboardListPanel;
+
+export type DashboardScreenDefinition = {
+  readonly id: string;
+  readonly type: "dashboard";
+  readonly panels: readonly DashboardPanelDefinition[];
+  readonly slots?: ScreenSlots;
+  readonly access?: AccessRule;
+};
+
 // --- entityEdit ---
 
 // camelCase `readOnly` instead of the spec's lowercase `readonly`: TS's
@@ -557,6 +615,7 @@ export type ScreenSlots = {
 export type ScreenDefinition =
   | EntityListScreenDefinition
   | ProjectionListScreenDefinition
+  | DashboardScreenDefinition
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition

package/src/i18n/required-surface-keys.ts

@@ -1,6 +1,7 @@
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
+  DashboardScreenDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FeatureDefinition,
@@ -106,6 +107,19 @@ export function requiredKeysFromScreen(
       for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
       break;
     }
+    case "dashboard": {
+      const dashboard = screen as DashboardScreenDefinition;
+      for (const panel of dashboard.panels) {
+        pushKey(out, panel.label);
+        if (panel.kind === "list") {
+          for (const col of panel.columns) {
+            const normalized = normalizeListColumn(col);
+            if (normalized.label !== undefined) pushKey(out, normalized.label);
+          }
+        }
+      }
+      break;
+    }
     case "entityEdit": {
       const edit = screen as EntityEditScreenDefinition;
       pushKey(out, edit.submitLabel);

package/src/testing/e2e-generator.ts

@@ -115,6 +115,9 @@ export function generateE2ESpec(
     // projectionList: query-getrieben, Author-spezifische Projection —
     // kein generischer CRUD-Spec ableitbar (wie actionForm/configEdit).
     if (screen.type === "projectionList") continue;
+    // dashboard: panel-getrieben (Stat/Chart/List-Queries) — dito, keine
+    // generische CRUD-Annahme möglich.
+    if (screen.type === "dashboard") continue;
     const { scope: feature, name: short } = parseQn(screenQn);
     const urlPath = `/t/${tenant}/${feature}/${short}`;
     const title = `${feature}/${short}`;

package/src/ui-types/index.ts

@@ -46,6 +46,11 @@ export type {
   ConfigEditScreenDefinition,
   CustomScreenDefinition,
   CustomScreenRoute,
+  DashboardChartPanel,
+  DashboardListPanel,
+  DashboardPanelDefinition,
+  DashboardScreenDefinition,
+  DashboardStatPanel,
   EditExtensionSection,
   EditFieldSpec,
   EditFieldsSection,