@cosmicdrift/kumiko-types 0.332.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/extension-options-map.d.ts

@@ -5,5 +5,5 @@ export interface KumikoExtensionOptionsMap {
 export type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap ? KumikoExtensionOptionsMap[N] & {
     readonly escapeHatch?: EscapeHatchDeclaration;
 } : Record<string, unknown>;
-/** Rest-tuple for useExtension's positional options arg: required for an augmented name, optional otherwise. */
-export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap ? [options: ExtensionOptionsFor<N>] : [options?: Record<string, unknown>];
+/** Rest-tuple for useExtension's positional options arg: required for an augmented name with required keys, optional otherwise. */
+export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap ? Record<never, never> extends KumikoExtensionOptionsMap[N] ? [options?: ExtensionOptionsFor<N>] : [options: ExtensionOptionsFor<N>] : [options?: Record<string, unknown>];

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

@@ -147,6 +147,16 @@ export type RowFieldExtractor = {
 } | {
     readonly map: Readonly<Record<string, string>>;
 };
+/** How a row action renders inline in the row-action column. `"button"` is a
+ *  bordered button (its colour follows the action's `style`), `"link"` a text
+ *  link, `"icon"` an icon-only button (needs a resolved icon, falls back to
+ *  `"link"` without one). Unset: the renderer decides (primary action as link,
+ *  the rest in the kebab menu). */
+export type RowActionDisplay = "button" | "link" | "icon";
+/** Row-action column layout. `"adaptive"` (default): primary action as link,
+ *  the rest in a kebab menu — except actions with an explicit `display`, which
+ *  stay inline. `"inline"`: every action inline, no kebab. */
+export type RowActionMode = "adaptive" | "inline";
 export type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer;
 export type RowActionWriteHandler = {
     /** Default für RowActions ohne explizit gesetzten `kind` —
@@ -182,6 +192,8 @@ export type RowActionWriteHandler = {
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
      *  (renderer-web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
+    /** Inline render form in the row-action column — see `RowActionDisplay`. */
+    readonly display?: RowActionDisplay;
 };
 export type RowActionNavigateBase = {
     readonly kind: "navigate";
@@ -216,6 +228,8 @@ export type RowActionNavigateBase = {
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
      *  (renderer-web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
+    /** Inline render form in the row-action column — see `RowActionDisplay`. */
+    readonly display?: RowActionDisplay;
 };
 /** Exactly one of `screen` / `entity` — mutual exclusivity is type-enforced
  *  (boot validator still rejects both/neither for untyped schemas). */
@@ -252,6 +266,15 @@ export type RowActionDrawer = {
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
      *  (renderer-web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
+    /** Inline render form in the row-action column — see `RowActionDisplay`. */
+    readonly display?: RowActionDisplay;
+    /** Drawer heading (i18n key) instead of the action `label`. `{name}`
+     *  placeholders resolve from the drawer prefill (`params`), formatted for
+     *  display like `ActionFormScreenDefinition.summary`. */
+    readonly title?: string;
+    /** Line under the drawer heading (i18n key or a bare `{name}` template),
+     *  resolved like `title`. */
+    readonly subtitle?: string;
 };
 export type ToolbarAction = {
     readonly kind: "navigate";
@@ -294,6 +317,10 @@ export type ToolbarAction = {
      *  not force a confirm dialog here: the target form is the
      *  confirmation. */
     readonly style?: "primary" | "secondary" | "danger";
+    /** Drawer heading (i18n key) instead of `label`. */
+    readonly title?: string;
+    /** Line under the drawer heading (i18n key). */
+    readonly subtitle?: string;
 };
 export type RelatedListToolbarAction = (Extract<ToolbarAction, {
     readonly kind: "navigate";
@@ -319,6 +346,31 @@ export type RelatedListToolbarAction = (Extract<ToolbarAction, {
  *  layout and are therefore omitted. `kind` stays the discriminator so further
  *  expansion kinds can be added without a breaking change. */
 export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField">;
+/** An extra choice on a facet next to the field's own options: a named
+ *  bundle of values ("Running" = several statuses) or "no filter" (`values:
+ *  []`, e.g. "All"). Chips only. */
+export type EntityListFacetExtraOption = {
+    readonly id: string;
+    /** i18n key. */
+    readonly label: string;
+    /** Option values this choice selects; `[]` selects nothing, i.e. no filter. */
+    readonly values: readonly string[];
+    /** Where the chip sits relative to the field's own options. Default "start". */
+    readonly position?: "start" | "end";
+};
+export type EntityListFacetConfig = {
+    /** `"select"` (default): dropdown with checkboxes. `"chips"`: one toggle
+     *  chip per option, single choice. */
+    readonly display?: "select" | "chips";
+    /** Chips show how many rows each option matches (other facets and the
+     *  search apply). Counts come from the list query itself, one `limit: 1`
+     *  count request per chip. */
+    readonly showCounts?: boolean;
+    /** Chips with zero matching rows are not shown. Needs counts; implies
+     *  `showCounts`'s requests even when the number itself is not shown. */
+    readonly hideEmpty?: boolean;
+    readonly extraOptions?: readonly EntityListFacetExtraOption[];
+};
 export type EntityListScreenDefinition = {
     readonly id: string;
     readonly type: "entityList";
@@ -340,10 +392,13 @@ export type EntityListScreenDefinition = {
     readonly columns: readonly ListColumnSpec[];
     readonly rowRenderer?: PlatformComponent;
     readonly cardRenderer?: PlatformComponent;
-    /** Per-Row-Aktionen — rendert eine Actions-Spalte rechts in der Tabelle.
-     *  Bis zu 2 actions als inline-Buttons; >2 als Kebab-Dropdown.
-     *  Reihenfolge im Array = Reihenfolge in der UI. */
+    /** Per-row actions, rendered as an actions column on the right.
+     *  Adaptive (default, see `rowActionMode`): the primary action as a link,
+     *  the rest in the kebab menu; actions with an explicit `display` stay
+     *  inline. Array order is UI order. */
     readonly rowActions?: readonly RowAction[];
+    /** Layout of the row-action column — see `RowActionMode`. */
+    readonly rowActionMode?: RowActionMode;
     /** Toolbar-Aktionen (List-Header). "Open Incident", "Schedule Maintenance"
      *  etc. — neben "+ Neu" wenn vorhanden. Reihenfolge im Array = UI-
      *  Reihenfolge, primary-style links. */
@@ -361,6 +416,17 @@ export type EntityListScreenDefinition = {
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
     readonly defaultSort?: ListSortSpec;
+    /** Initial facet selection, per filterable field: option values (string
+     *  facets) or a boolean. Applies only while the URL carries no value for
+     *  that field, so a link or the user's own choice wins; picking "no filter"
+     *  (an `extraOptions` entry with `values: []`, or clearing the facet) is
+     *  remembered in the URL and is not overridden again. */
+    readonly defaultFilters?: Readonly<Record<string, readonly string[] | boolean>>;
+    /** Per-facet display options for the entity's `filterable` fields, keyed by
+     *  field name. `false` hides the facet's control (its filter stays usable
+     *  through `defaultFilters` and the URL). Fields without an entry keep the
+     *  default dropdown. */
+    readonly facets?: Readonly<Record<string, EntityListFacetConfig | false>>;
     /** i18n key for the primary create button label (default `kumiko.actions.create`). */
     readonly createLabel?: string;
     /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
@@ -430,6 +496,8 @@ export type ProjectionListScreenDefinition = {
     readonly rowRenderer?: PlatformComponent;
     readonly cardRenderer?: PlatformComponent;
     readonly rowActions?: readonly RowAction[];
+    /** Layout of the row-action column — see `RowActionMode`. */
+    readonly rowActionMode?: RowActionMode;
     readonly toolbarActions?: readonly ToolbarAction[];
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
@@ -667,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 = {
@@ -713,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;
 };
@@ -723,6 +800,11 @@ export type EditFieldSpec = string | {
     readonly readOnly?: FieldCondition;
     readonly required?: FieldCondition;
     readonly renderer?: FieldRenderer;
+    /** `false` keeps the field out of the submitted payload — for values
+     *  that are shown or prefilled for display only (a label, a counter)
+     *  and that the write handler's schema does not accept. Validation and
+     *  rendering are unchanged. */
+    readonly submit?: false;
     /** Prefix icon on the input — closed FieldIconKey vocabulary into
      *  the FIELD_ICONS registry (renderer-web), analogous to
      *  `ScreenNavSugar.icon` / NavIconKey. Only takes effect for
@@ -780,6 +862,10 @@ export type EditFieldsSection = {
      *  Ignored outside tabs mode or when the field's value is not a finite
      *  number. */
     readonly countField?: string;
+    /** Short line (i18n key) under this step's title in the wizard step rail
+     *  and in the "up next" box. Wizard layouts only; unlike `description` it
+     *  is not shown inside the step. */
+    readonly subtitle?: string;
     /** Rendered top-right in the section's Card title row — same
      *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
      *  evaluated against the same record. Every action must resolve an icon
@@ -816,6 +902,26 @@ export type EditExtensionSection = {
      *  (declared or id-derived); the boot-validator rejects one that doesn't. */
     readonly actions?: readonly RowAction[];
 };
+/** Rows are grouped by `field` in order of first appearance. Every group gets
+ *  a collapsible header. */
+export type RelatedListGroupBy = {
+    readonly field: string;
+    /** Groups whose field value equals this start collapsed; the others start open. */
+    readonly collapsedWhen?: string | number | boolean | null;
+    /** i18n key of the group header. Placeholders: `{count}` rows in the group,
+     *  `{value}` the group's field value, `{lastDate}` the group's latest
+     *  `dateField` value as a locale date. */
+    readonly label: string;
+    /** Header i18n key per group value (as string), overriding `label`. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Row field (ISO date or timestamp) behind `{lastDate}`. */
+    readonly dateField?: string;
+};
+/** Row tint rule: rows where the `FieldCondition` (`{ field, eq }`, `{ field,
+ *  in }` …) holds get the tone. `bad` renders red. */
+export type RelatedListRowTone = Exclude<FieldCondition, boolean> & {
+    readonly tone: SelectOptionTone;
+};
 export type EditRelatedListSection = {
     /** Kebab-case tab id, used as the `?tab=` value. Required by the
      *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
@@ -885,6 +991,13 @@ export type EditRelatedListSection = {
      *  writeHandler action re-runs this section's own query, same as a
      *  projectionList row action re-running its list query. */
     readonly rowActions?: readonly RowAction[];
+    /** Layout of the row-action column — see `RowActionMode`. */
+    readonly rowActionMode?: RowActionMode;
+    /** Groups rows by the value of a field under collapsible group headers. */
+    readonly groupBy?: RelatedListGroupBy;
+    /** Tints rows whose field matches — a declarative rule, not a function, so
+     *  the screen definition stays serializable. */
+    readonly rowTone?: RelatedListRowTone;
     /** Toolbar actions above the table — same type and dispatch semantics as
      *  `entityList`/`projectionList`'s `toolbarActions` ("+ Anlegen" etc.),
      *  plus `visible`/`params` evaluated against the parent record (see
@@ -958,9 +1071,23 @@ 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;
+    /** Wizard layouts only. `upNext: true` adds an "up next" box to the step
+     *  rail with the following step's title and `subtitle`; the last step
+     *  shows none. */
+    readonly wizard?: {
+        readonly aside?: {
+            readonly upNext: true;
+        };
+    };
 };
 export type EntityEditScreenDefinition = {
     readonly id: string;
@@ -984,6 +1111,11 @@ export type EntityEditScreenDefinition = {
     readonly entity: string;
     /** Entity field whose value names the loaded record in the header breadcrumb (edit mode only). */
     readonly recordTitleField?: string;
+    /** Screen title (i18n key) with `{field}` placeholders filled from the
+     *  current form values, so the title follows what the user types (create
+     *  wizard: "Add {make} {model}"). Falls back to the plain title while the
+     *  placeholders are still empty. */
+    readonly titleTemplate?: 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
@@ -1085,6 +1217,12 @@ export type ActionFormScreenDefinition = {
     /** i18n-key für den Submit-Button. Default: i18n-Default des
      *  Renderers (typischerweise "actions.submit"). */
     readonly submitLabel?: string;
+    /** Extra buttons in the form footer next to the submit button. A click
+     *  applies `patch` to the form values, then submits the form (same
+     *  validation, same handler) — e.g. a "Mark as posted" button that sets
+     *  `posted: true`. The patched field need not be rendered by the layout.
+     *  Order in the array = order in the footer, before the submit button. */
+    readonly footerActions?: readonly ActionFormFooterAction[];
     /** Context box above the fields (i18n keys). `{name}` placeholders resolve from the
      *  drawer prefill (`params` of the opening row action), formatted for display. */
     readonly summary?: {
@@ -1131,6 +1269,17 @@ export type ActionFormScreenDefinition = {
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;
 };
+export type ActionFormFooterAction = {
+    /** Stable id (kebab-case), used for the test id. */
+    readonly id: string;
+    /** i18n key. */
+    readonly label: string;
+    readonly icon?: IconKey;
+    /** Button style. Default "secondary". */
+    readonly variant?: "primary" | "secondary" | "danger";
+    /** Form values set before the submit. JSON-safe literals only. */
+    readonly patch: Readonly<Record<string, string | number | boolean | null>>;
+};
 /** Redirect target plus the success-payload field carrying the navigation
  *  id. The write-handler reports the id of what it wrote (`data.id`); when
  *  that record is a child and the target screen shows its parent, the
@@ -1290,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.332.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>",