@cosmicdrift/kumiko-types 0.333.0 → 0.334.0

package/dist/config.d.ts

@@ -2,7 +2,7 @@ import type { ZodType } from "zod";
 import type { ConcurrencyMode } from "./concurrency-mode.js";
 import type { ConfigScope } from "./config-scope.js";
 import type { DbConnection } from "./db-connection.js";
-import type { FieldDefinition } from "./fields.js";
+import type { FieldDefinition, OptionsQueryPayload } from "./fields.js";
 import type { EscapeHatchDeclaration, JobContext } from "./handlers.js";
 import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.js";
 import type { TenantId } from "./identifiers.js";
@@ -46,12 +46,14 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
     readonly piiEncrypted?: boolean;
     readonly options?: readonly string[];
     /** Only on `type: "select"`: loads the options from this query (QN), contract
-     *  `{ rows: { value, label }[] }`, labels shown verbatim. Mutually exclusive with
+     *  `{ rows: { value, label, description?, group? }[] }`, labels shown verbatim. Mutually exclusive with
      *  `options` and `allowPerRequest`. The write side does not check the value against
      *  the query result; the consuming feature validates it where it uses it. */
     readonly optionsQuery?: string;
-    /** Static payload sent with every `optionsQuery` call. Requires `optionsQuery`. */
-    readonly optionsQueryPayload?: Readonly<Record<string, string | number | boolean>>;
+    /** Payload sent with every `optionsQuery` call. Requires `optionsQuery`. `{ field }`
+     *  names another config key (short name) of the owner feature, resolved on the
+     *  generated settings screen. */
+    readonly optionsQueryPayload?: OptionsQueryPayload;
     readonly bounds?: ConfigBounds;
     readonly pattern?: {
         readonly regex: string;
@@ -68,6 +70,8 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
 };
 export type ConfigMask = {
     readonly title: string;
+    /** i18n key for help text shown under the field label. */
+    readonly description?: string;
     readonly icon?: NavIconKey;
     readonly order?: number;
 };

package/dist/fields.d.ts

@@ -89,6 +89,18 @@ export type TextFieldDef = {
     readonly filterable?: boolean;
     readonly encrypted?: boolean;
     readonly sensitive?: boolean;
+    /** Write-only secret (API key): the value is never returned to clients. Reads
+     *  (list/detail/write responses) show `true` = set, `null` = empty. Writes:
+     *  `""` or omitted = unchanged, `null` = clear, string = new value.
+     *  Server-side: executor reads (detail/list in server handlers) and
+     *  postSave/postQuery hooks see the plaintext; ctx.query, dispatcher.query,
+     *  agent tools and `_refs` see true/null; ctx.db sees the ciphertext.
+     *  Known limit: masking runs for entity-bound query handlers with array /
+     *  {rows} / flat results; an unbound custom query handler that returns
+     *  executor rows must call maskWriteOnlyFields itself (same scope limit as
+     *  access.read). Requires `sensitive` (via `find: "secret"`); forbidden with
+     *  default/searchable/sortable/filterable/lookupable and on screen/form fields. */
+    readonly writeOnly?: boolean;
     /** A later run reads this field's value as an instruction — prompt, rule,
      *  template. Every create/update whose payload writes it requires agent.risk
      *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
@@ -158,6 +170,16 @@ export type BooleanFieldDef = {
     readonly access?: FieldAccess;
 };
 export type SelectOptionTone = "ok" | "warn" | "bad" | "neutral";
+/** One `optionsQueryPayload` entry: a literal, or `{ field }` = the current value of
+ *  a sibling field of the same form (config keys: another key of the owner feature). */
+export type OptionsQueryPayloadValue = string | number | boolean | {
+    readonly field: string;
+};
+export type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
+export declare function isOptionsQueryFieldRef(value: OptionsQueryPayloadValue): value is {
+    readonly field: string;
+};
+export declare function optionsQueryFieldRefs(payload: OptionsQueryPayload | undefined): string[];
 export type SelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
     readonly type: "select";
     readonly description?: string;
@@ -180,13 +202,15 @@ 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 }[] }`,
-     *  labels are shown verbatim (not translated). `options` must be empty when set.
+    /** 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. */
     readonly optionsQuery?: string;
-    /** Static payload sent with every `optionsQuery` call. */
-    readonly optionsQueryPayload?: Readonly<Record<string, string | number | boolean>>;
+    /** Payload sent with every `optionsQuery` call. `{ field }` entries re-load the
+     *  options when that sibling field changes. */
+    readonly optionsQueryPayload?: OptionsQueryPayload;
 } & ResolvedPiiFlags;
 export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
     readonly type: "multiSelect";

package/dist/fields.js

@@ -1,4 +1,12 @@
 // --- Field Types ---
+export function isOptionsQueryFieldRef(value) {
+    return typeof value === "object" && value !== null;
+}
+export function optionsQueryFieldRefs(payload) {
+    return Object.values(payload ?? {})
+        .filter(isOptionsQueryFieldRef)
+        .map((ref) => ref.field);
+}
 /** Qualified config key a `{ kind: "tenant" }` MoneyCurrencySource resolves
  *  against — the tenant-settings bundle's per-tenant currency. Lives here
  *  (client-safe) rather than framework/engine so renderer code can read it

package/dist/screen.d.ts

@@ -735,6 +735,11 @@ export type DashboardScreenPanel = {
     readonly screen: string;
     readonly label?: string;
     readonly visibleWhen?: DashboardPanelVisibility;
+    /** Render the embedded form without its own card frame and padding, aligned to
+     *  the dashboard's page grid like a standalone settings screen. Default false
+     *  (framed card); set for panels whose body is a settings-list form, where a
+     *  card inside the page would double the inset. */
+    readonly chromeless?: boolean;
 };
 export type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardCustomPanel | DashboardScreenPanel;
 export type DashboardFilterDefinition = {
@@ -781,6 +786,10 @@ export type DashboardScreenDefinition = {
     readonly timeRange?: DashboardTimeRangeDefinition;
     /** Marks the screen as spanning more than the caller's own scope. */
     readonly scope?: DashboardScopeDefinition;
+    /** Show the "Updated at" timestamp in the toolbar. Default true; turn off for
+     *  dashboards that host forms rather than live metrics, where a load time
+     *  next to the form reads as stale data. */
+    readonly showUpdatedAt?: boolean;
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;
 };
@@ -1062,6 +1071,12 @@ export type EditLayout = {
      *  boot-validator rejects it on entityEdit, see the check for the reason);
      *  requires >= 2 sections, each with a title and an `id`. */
     readonly mode?: "single" | "wizard" | "tabs";
+    /** "settings-list" lays each section out as a band with a title column on
+     *  the left and one hairline-separated row per field (label + help left,
+     *  control right) — the familiar settings pattern, for screens that are a
+     *  list of independent preferences rather than one record form. Default
+     *  "form" keeps the grid of cells. */
+    readonly variant?: "form" | "settings-list";
     /** Persists in-progress wizard state as a resumable draft instead of
      *  discarding it on navigation away. */
     readonly draft?: boolean;
@@ -1424,6 +1439,11 @@ export type ConfigEditScreenDefinition = {
      *  ohne es unter der `__config-edit__`-Konvention zu duplizieren.
      *  Fehlt ein Eintrag, gilt die Konvention. */
     readonly fieldLabels?: Readonly<Record<string, string>>;
+    /** Per-field help text i18n key (Field-Name → Key), from `mask.description`. */
+    readonly fieldDescriptions?: Readonly<Record<string, string>>;
+    /** Field names whose config key declares `required: true` — drives the
+     *  "Not set. Required." origin line, not form validation. */
+    readonly requiredFields?: readonly string[];
     /** i18n-key für den Submit-Button. Default: "kumiko.actions.save". */
     readonly submitLabel?: string;
     readonly slots?: ScreenSlots;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.333.0",
+  "version": "0.334.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",