@cosmicdrift/kumiko-types 0.329.0 → 0.330.2

package/dist/aggregate-types.d.ts

@@ -0,0 +1,25 @@
+export type AggregateMeasure = {
+    readonly fn: "count";
+} | {
+    readonly fn: "countDistinct" | "sum" | "avg";
+    readonly field: string;
+};
+export type AggregateTimeBucket = "hour" | "day";
+export type AggregateDimension = {
+    readonly field: string;
+} | {
+    readonly field: string;
+    readonly bucket: AggregateTimeBucket;
+    readonly timeZone: string;
+};
+export type AggregateSpec = {
+    readonly measure: AggregateMeasure;
+    readonly groupBy?: readonly AggregateDimension[];
+    readonly orderByValue?: "asc" | "desc";
+    readonly limit?: number;
+};
+export type AggregateKey = string | number | boolean | null;
+export type AggregateRow = {
+    readonly keys: readonly AggregateKey[];
+    readonly value: number | null;
+};

package/dist/aggregate-types.js

@@ -0,0 +1 @@
+export {};

package/dist/screen.d.ts

@@ -113,7 +113,15 @@ export type ListColumnSpec = string | {
      *  `md` breakpoint (tables keep it). For columns that only make sense
      *  next to the others, like a sort key. */
     readonly hideOnNarrow?: boolean;
+    /** Dashboard list panels only. "bar": field holds a 0..1 fraction, drawn
+     *  as bar + percent. "badge": field holds a label, drawn as a pill whose
+     *  tone comes from `badgeToneField`. Other list renderers ignore it. */
+    readonly display?: ListColumnDisplay;
+    /** Row field naming the badge tone; only with `display: "badge"`. */
+    readonly badgeToneField?: string;
 };
+export type ListColumnDisplay = "bar" | "badge";
+export type ListBadgeTone = "positive" | "warn" | "negative" | "neutral";
 export type ListPaginationMode = "pages" | "infinite" | false;
 export type ListSortDir = "asc" | "desc";
 export type ListSortSpec = {
@@ -322,6 +330,8 @@ export type EntityListScreenDefinition = {
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
     readonly entity: string;
+    /** Short screen id (same feature) the create button opens instead of the entity's default edit screen. */
+    readonly createScreen?: string;
     readonly columns: readonly ListColumnSpec[];
     readonly rowRenderer?: PlatformComponent;
     readonly cardRenderer?: PlatformComponent;
@@ -487,6 +497,8 @@ export type ProjectionDetailScreenDefinition = {
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
     readonly query: string;
+    /** Query output field whose value titles the page header (breadcrumb) when no `header` is set. */
+    readonly recordTitleField?: string;
     /** Query-payload key for the row-id. Default "id". */
     readonly idParam?: string;
     /** The server determines the shown row from the caller's session/context
@@ -530,20 +542,39 @@ export type ProjectionDetailScreenDefinition = {
      *  Set "form" to opt back into the disabled-Input look (fw#2245). */
     readonly valueDisplay?: "form" | "text";
 };
-export type DashboardStatPanel = {
+export type DashboardPanelQueryOptions = {
+    /** Static, author-set query parameters merged on top of the screen's
+     *  dynamic filterParams — lets a panel pin a value (e.g. a status facet)
+     *  the screen-wide filter doesn't cover, without needing its own query.
+     *  The panel wins over the screen filter and the time range. */
+    readonly params?: Readonly<Record<string, unknown>>;
+    /** The screen `filter` value is NOT merged into this panel's query (a tenant
+     *  picker must not hit sources without a tenant column). The screen
+     *  `timeRange` still is. */
+    readonly ignoreScreenFilter?: boolean;
+};
+export type DashboardPanelSpan = "half" | "full";
+export type DashboardPanelEmptyState = {
+    readonly span?: DashboardPanelSpan;
+    readonly emptyLabel?: string;
+    /** Second line under `emptyLabel`. */
+    readonly emptyHint?: string;
+};
+export type DashboardStatPanel = DashboardPanelQueryOptions & {
     readonly kind: "stat";
-    /** Stable id — kebab-case, eindeutig im Panel-Set. */
+    /** Stable id: kebab-case, unique within the panel set. */
     readonly id: string;
     /** Anzeige-Text (i18n-Key). */
     readonly label: string;
     readonly query: string;
-    /** Static, author-set query parameters merged on top of the screen's
-     *  dynamic filterParams — lets a panel pin a value (e.g. a status facet)
-     *  the screen-wide filter doesn't cover, without needing its own query. */
-    readonly params?: Readonly<Record<string, unknown>>;
     readonly valueField: string;
     readonly subField?: string;
     readonly toneField?: string;
+    /** Fixed tone when `toneField` is unset or yields none; not applied while the value is 0. */
+    readonly tone?: "default" | "positive" | "warn" | "negative";
+    /** Record field holding `{ atMs, value | null }[]` (MetricResult.points),
+     *  drawn as a sparkline next to the value. */
+    readonly sparklineField?: string;
     /** Optionaler Delta-Chip (z.B. "↓23 %") neben dem Label. Nur wenn BEIDE
      *  Felder gesetzt sind UND der Query-Handler sie liefert, rendert der Chip
      *  — sonst bleibt die Kachel wie ohne Delta. `deltaToneField` fällt auf
@@ -564,15 +595,20 @@ export type DashboardStatPanel = {
      *  Icon) — ohne icon wird der Wert still verworfen. */
     readonly accentColor?: string;
 };
-export type DashboardChartPanel = {
+export type DashboardChartKind = "timeseries" | "stacked-bars" | "segment-bars" | "stacked-area";
+export type DashboardChartTone = "positive" | "negative" | "active" | "neutral";
+export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
     readonly kind: "chart";
     readonly id: string;
     readonly label: string;
-    /** v1: geglättete Zeitreihe. Weitere Chart-Formen additiv. */
-    readonly chart: "timeseries";
+    readonly chart: DashboardChartKind;
     readonly query: string;
+    /** i18n key under the title, e.g. "7 days, by creation day". */
+    readonly subtitle?: string;
+    /** Series/segment key -> tone; unmapped keys fall back to a palette. */
+    readonly seriesTones?: Readonly<Record<string, DashboardChartTone>>;
 };
-export type DashboardListPanel = {
+export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
     readonly kind: "list";
     readonly id: string;
     readonly label: string;
@@ -582,17 +618,16 @@ export type DashboardListPanel = {
 export type DashboardStatGroupPanel = {
     readonly kind: "stat-group";
     readonly id: string;
-    readonly label: string;
+    readonly label?: string;
     readonly stats: readonly DashboardStatPanel[];
 };
-export type DashboardFeedPanel = {
+export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
     readonly kind: "feed";
     readonly id: string;
     readonly label: string;
     readonly query: string;
-    readonly emptyLabel?: string;
 };
-export type DashboardProgressListPanel = {
+export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
     readonly kind: "progress-list";
     readonly id: string;
     readonly label: string;
@@ -631,6 +666,19 @@ export type DashboardFilterDefinition = {
     /** Query-Result-Contract: `{ rows: { value: string; label: string }[] }`. */
     readonly optionsQuery?: string;
 };
+export type DashboardTimeRangeDefinition = {
+    readonly id: string;
+    /** `label` is an i18n key. */
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly default: string;
+};
+export type DashboardScopeDefinition = {
+    readonly badge: string;
+    readonly notice?: string;
+};
 export type DashboardScreenDefinition = {
     readonly id: string;
     readonly type: "dashboard";
@@ -643,6 +691,11 @@ export type DashboardScreenDefinition = {
     readonly dormant?: boolean;
     readonly panels: readonly DashboardPanelDefinition[];
     readonly filter?: DashboardFilterDefinition;
+    /** Segmented control in the toolbar; the value lives in URL search param
+     *  `id` and is merged into EVERY panel query (also ignoreScreenFilter ones). */
+    readonly timeRange?: DashboardTimeRangeDefinition;
+    /** Marks the screen as spanning more than the caller's own scope. */
+    readonly scope?: DashboardScopeDefinition;
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;
 };
@@ -905,6 +958,8 @@ export type EntityEditScreenDefinition = {
      *  value is overwritten. */
     readonly urlPrefillFields?: readonly string[];
     readonly entity: string;
+    /** Entity field whose value names the loaded record in the header breadcrumb (edit mode only). */
+    readonly recordTitleField?: string;
     readonly layout: EditLayout;
     /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
      *  `kumiko.actions.save`. Lässt den Auto-Edit-Screen domain-spezifische
@@ -1179,6 +1234,9 @@ export type CustomScreenDefinition = {
 export type ConfigEditScreenDefinition = {
     readonly id: string;
     readonly type: "configEdit";
+    /** Default true: the form fills the shell content height with a pinned
+     *  footer. `false` restores the card layout with the footer in the flow. */
+    readonly fillHeight?: boolean;
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;

package/dist/tenant-db-types.d.ts

@@ -1,3 +1,4 @@
+import type { AggregateRow, AggregateSpec } from "./aggregate-types.js";
 import type { DbRunner } from "./db-connection.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
 import type { ExecutorOnly, NotExecutorOnly } from "./executor-brand.js";
@@ -44,6 +45,7 @@ export type TenantDb = {
     selectMany<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where?: WhereObject, options?: SelectOptions): Promise<readonly T[]>;
     fetchOne<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where: WhereObject): Promise<T | undefined>;
     count(table: SchemaTable | EntityTableMeta, where?: WhereObject): Promise<number>;
+    aggregate(table: SchemaTable | EntityTableMeta, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
     insertOne<T = Record<string, unknown>>(table: WritableTable, values: Record<string, unknown>): Promise<T | undefined>;
     updateMany<T = Record<string, unknown>>(table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly T[]>;
     deleteMany(table: WritableTable, where: WhereObject): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.329.0",
+  "version": "0.330.2",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -138,6 +138,10 @@
       "types": "./dist/where-clause-types.d.ts",
       "default": "./dist/where-clause-types.js"
     },
+    "./aggregate-types": {
+      "types": "./dist/aggregate-types.d.ts",
+      "default": "./dist/aggregate-types.js"
+    },
     "./tenant-db-types": {
       "types": "./dist/tenant-db-types.d.ts",
       "default": "./dist/tenant-db-types.js"
@@ -393,6 +397,10 @@
         "types": "./dist/where-clause-types.d.ts",
         "default": "./dist/where-clause-types.js"
       },
+      "./aggregate-types": {
+        "types": "./dist/aggregate-types.d.ts",
+        "default": "./dist/aggregate-types.js"
+      },
       "./tenant-db-types": {
         "types": "./dist/tenant-db-types.d.ts",
         "default": "./dist/tenant-db-types.js"