@cosmicdrift/kumiko-types 0.390.1 → 0.391.0

package/dist/feature-registrar.d.ts

@@ -12,6 +12,7 @@ import type { AccessRule, AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, Declarativ
 import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
 import type { HttpRouteDefinition } from "./http-route.ts";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
+import type { ProbeOptions } from "./probe.ts";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
 import type { RelationDefinition } from "./relations.ts";
 import type { ScreenDefinition } from "./screen.ts";
@@ -293,6 +294,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     secret(definition: {
         readonly name: string;
     } & SecretOptions): SecretKeyHandle;
+    probe(options: ProbeOptions): void;
     secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
     secretNamespace(definition: {
         readonly name: string;

package/dist/feature.d.ts

@@ -7,6 +7,7 @@ import type { AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, EventDef, Eve
 import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn } from "./hooks.ts";
 import type { HttpRouteDefinition } from "./http-route.ts";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
+import type { ProbeDefinition } from "./probe.ts";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
 import type { EntityRelations, RelationDefinition } from "./relations.ts";
 import type { ScreenDefinition } from "./screen.ts";
@@ -179,6 +180,7 @@ export type FeatureDefinition = {
     readonly metrics: Readonly<Record<string, FeatureMetricDef>>;
     readonly secretKeys: Readonly<Record<string, SecretKeyDefinition>>;
     readonly secretNamespaces: Readonly<Record<string, SecretNamespaceDefinition>>;
+    readonly probes?: Readonly<Record<string, ProbeDefinition>>;
     readonly projections: Readonly<Record<string, ProjectionDefinition>>;
     readonly entityProjectionExtensions?: Readonly<Record<string, readonly EntityProjectionExtension[]>>;
     readonly multiStreamProjections: Readonly<Record<string, MultiStreamProjectionDefinition>>;

package/dist/fields.d.ts

@@ -233,11 +233,11 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
     readonly optionTones?: {
         readonly [K in TOptions[number]]?: SelectOptionTone;
     };
-    /** Loads the options from this query (QN). Contract:
-     *  `{ rows: { value, label, description?, group? }[] }`, labels are shown verbatim
-     *  (not translated); description is a muted second line, group a heading. `options` must be empty when set.
-     *  Only valid on configEdit/actionForm screen fields and config keys, not on entity
-     *  fields: the stored value would not be checked against the query result. */
+    /** Loads the options from this query (QN), labels shown verbatim: `{ rows: { value, label,
+     *  description?, group?, default? }[] }`; description is a muted second line, group a heading.
+     *  actionForm only: the first `default: true` row seeds an empty field like a prefill (not a
+     *  change); set `submitPrefilled` to submit it unchanged. `options` must be empty when set.
+     *  Only valid on configEdit/actionForm screen fields and config keys, not entity fields. */
     readonly optionsQuery?: string;
     /** Payload sent with every `optionsQuery` call. `{ field }` entries re-load the
      *  options when that sibling field changes. */

package/dist/probe.d.ts

@@ -0,0 +1,45 @@
+import type { JobContext } from "./handlers.ts";
+import type { TenantId } from "./identifiers.ts";
+export type ProbeScope = "tenant" | "system";
+export type ProbeCost = "free" | "paid";
+export type ProbeText = {
+    readonly key: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+};
+export type ProbeTarget = {
+    readonly id: string;
+    readonly label: ProbeText;
+    readonly ownerUserId?: string;
+};
+export type ProbeVerdict = {
+    readonly status: "ok";
+    readonly message: ProbeText;
+} | {
+    readonly status: "skipped";
+    readonly message: ProbeText;
+};
+export type ProbeContext = Pick<JobContext, "db" | "registry" | "obs" | "tz" | "services"> & {
+    readonly probeRunId: string;
+    readonly tenantId: TenantId;
+    readonly triggeredByUserId: string;
+    readonly triggeredByEmail: string | undefined;
+};
+export type ProbeOptions = {
+    readonly name: string;
+    readonly scope: ProbeScope;
+    readonly cost: ProbeCost;
+    /** i18n key, column "Bereich" */
+    readonly area: string;
+    /** i18n key, column "Check" (used when the probe has no targets) */
+    readonly label: string;
+    /** Default 10_000 */
+    readonly timeoutMs?: number;
+    /** Screen QN linked from a failed result */
+    readonly fixScreen?: string;
+    readonly targets?: (ctx: ProbeContext) => Promise<readonly ProbeTarget[]>;
+    /** Failure = throw */
+    readonly run: (ctx: ProbeContext, target: ProbeTarget | undefined) => Promise<ProbeVerdict>;
+};
+export type ProbeDefinition = ProbeOptions & {
+    readonly qualifiedName: string;
+};

package/dist/probe.js

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

package/dist/screen-entity-list.d.ts

@@ -70,6 +70,11 @@ export type ListColumnSpec = string | {
     readonly display?: ListColumnDisplay;
     /** Row field naming the badge tone; only with `display: "badge"`. */
     readonly badgeToneField?: string;
+    /** Row field holding a screen QN (`<feature>:screen:<id>`): the cell links
+     *  to that screen when the row sets it and the user may open it. For
+     *  query-backed lists (projectionList, relatedList), whose rows can point
+     *  at a different screen each. */
+    readonly linkScreenField?: string;
 };
 export type ListColumnDisplay = "bar" | "badge" | "datetime";
 export type ListBadgeTone = "positive" | "warn" | "negative" | "neutral";

package/dist/screen-projection.d.ts

@@ -1,7 +1,8 @@
 import type { SelectOptionTone } from "./fields.ts";
 import type { AccessRule, AgentScreenHints } from "./handlers.ts";
+import type { NavIconKey } from "./nav-icon.ts";
 import type { PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts";
-import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
+import type { DashboardPanelVisibility, DashboardStatTone } from "./screen-dashboard.ts";
 import type { EditLayout, ListEmptyStateSpec } from "./screen-entity-edit.ts";
 import type { ListColumnSpec, ListPaginationMode, ListSortSpec, RowAction, RowActionMode, RowFieldExtractor, ScreenFilter, ToolbarAction } from "./screen-entity-list.ts";
 import type { ListBulkAction } from "./screen-list-bulk.ts";
@@ -150,6 +151,10 @@ export type MetricSpec = {
     readonly field: string;
     readonly label: string;
     readonly navigate?: MetricNavigate;
+    /** Tile color as on dashboard stat panels; not applied while the value is 0. */
+    readonly tone?: DashboardStatTone;
+    /** Icon chip of the tile; only drawn with `metricsStyle: "tiles"`. */
+    readonly icon?: NavIconKey;
 };
 export type ProjectionDetailScreenDefinition = {
     readonly id: string;
@@ -187,6 +192,10 @@ export type ProjectionDetailScreenDefinition = {
      *  can reach the query — a stray id on the path is ignored, never
      *  forwarded. */
     readonly singleton?: boolean;
+    /** Refetches the record and its relatedList sections when their entity
+     *  changes (live SSE), for a screen that shows work a background job is
+     *  still doing. Needs queries named `<feature>:query:<entity>:<verb>`. */
+    readonly live?: boolean;
     readonly layout: EditLayout;
     /** Optional per-field label i18n key (field name → key), analogous to
      *  entityEdit.fieldLabels. The pseudo entity `__projection-detail__` has
@@ -199,6 +208,8 @@ export type ProjectionDetailScreenDefinition = {
     /** Metric band above the layout — column names in the query row, each with its own i18n `label`.
      *  Rendered only when set. */
     readonly metrics?: readonly MetricSpec[];
+    /** "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band. */
+    readonly metricsStyle?: "band" | "tiles";
     /** Parent list screen (short id) for a "back" navigation. */
     readonly listScreenId?: string;
     readonly slots?: ScreenSlots;

package/dist/screen.d.ts

@@ -1,3 +1,4 @@
+import type { SelectOptionTone } from "./fields.ts";
 import type { NavIconKey } from "./nav-icon.ts";
 import type { ActionFormScreenDefinition, SecretMintScreenDefinition } from "./screen-action-form.ts";
 import type { ConfigEditScreenDefinition, CustomScreenDefinition, SecretsEditScreenDefinition } from "./screen-custom-config.ts";
@@ -59,7 +60,11 @@ export interface FieldFormatRegistry {
     };
     enumOption: {
         readonly keyPrefix: string;
+        readonly tones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
     };
+    /** Value is a `DashboardI18nText` (`{ i18nKey, i18nParams }`) a query built
+     *  server-side, or a plain i18n key, translated in the user's language. */
+    i18nText: Record<never, never>;
     /** JSON-safe structured value rendered as indented text. */
     json: {
         readonly indent?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.390.1",
+  "version": "0.391.0",
   "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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -285,6 +285,10 @@
     "./temporal": {
       "types": "./dist/temporal.d.ts",
       "default": "./dist/temporal.js"
+    },
+    "./probe": {
+      "types": "./dist/probe.d.ts",
+      "default": "./dist/probe.js"
     }
   },
   "devDependencies": {
@@ -572,6 +576,10 @@
       "./temporal": {
         "types": "./dist/temporal.d.ts",
         "default": "./dist/temporal.js"
+      },
+      "./probe": {
+        "types": "./dist/probe.d.ts",
+        "default": "./dist/probe.js"
       }
     }
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "i18nText format, enumOption tones, linkScreenField, live projectionDetail and metric tiles",
+    "detail": "FormatSpec gains { format: \"i18nText\" } for values that are a server-built { i18nKey, i18nParams } or a plain i18n key. enumOption takes tones per option value. ListColumnSpec takes linkScreenField, the row field holding the screen QN the cell links to. ProjectionDetailScreenDefinition takes live and metricsStyle (\"band\" or \"tiles\"); MetricSpec takes tone and icon."
+  },
   {
     "version": "0.389.0",
     "type": "breaking",