@cosmicdrift/kumiko-types 0.331.0 → 0.333.0

package/dist/config.d.ts

@@ -7,6 +7,7 @@ import type { EscapeHatchDeclaration, JobContext } from "./handlers.js";
 import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.js";
 import type { TenantId } from "./identifiers.js";
 import type { NavIconKey } from "./nav-icon.js";
+import type { DashboardCustomPanel, DashboardScreenPanel } from "./screen.js";
 import type { TenantDb } from "./tenant-db-types.js";
 export type ConfigKeyAccess = {
     readonly read: readonly string[];
@@ -213,9 +214,11 @@ export type RegistrarExtensionRegistration = {
     readonly options?: Record<string, unknown> | undefined;
     readonly featureName?: string;
 };
+export type ExtensionSelectorPanel = DashboardCustomPanel | Omit<DashboardScreenPanel, "label">;
 export type ExtensionSelectorDef = {
     readonly extensionName: string;
     readonly qualifiedKey: string;
+    readonly panels?: readonly ExtensionSelectorPanel[];
 };
 export type ReferenceDataDef = {
     readonly entityName: string;

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/feature.d.ts

@@ -1,6 +1,6 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys, TranslationsDef } from "./config.js";
+import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys, TranslationsDef } from "./config.js";
 import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
@@ -327,11 +327,15 @@ export type FeatureRegistrar<TFeature extends string = string> = {
      * Settings-Hub render one tenant dashboard for the owner: the selector as a
      * select of the mounted plugin ids, the selected plugin's config and secrets
      * as panels, and plugin features lose their own tenant nav. `config:write:set`
-     * rejects unknown plugin ids (`""` clears).
+     * rejects unknown plugin ids (`""` clears). `options.panels` adds the owner's own
+     * `custom`/`screen` panels to that dashboard, after the selection and before the
+     * plugin panels (a short `screen` id means a screen of the declaring feature).
      */
     extensionSelector(extensionName: string, key: {
         readonly name: string;
-    } | string): void;
+    } | string, options?: {
+        readonly panels?: readonly ExtensionSelectorPanel[];
+    }): void;
     /**
      * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
      * unter dem genannten Namen bereit. Die eigentliche Implementation
@@ -489,6 +493,7 @@ export type Registry = {
     getExtension(name: string): RegistrarExtensionDef | undefined;
     getExtensionUsages(extensionName: string): readonly RegistrarExtensionRegistration[];
     getAllExtensionSelectors(): ReadonlyMap<string, string>;
+    getExtensionSelectorPanels(extensionName: string): readonly ExtensionSelectorPanel[];
     getAllNotifications(): ReadonlyMap<string, NotificationDefinition>;
     getAllReferenceData(): readonly ReferenceDataDef[];
     getProjectionsForSource(entityName: string): readonly ProjectionDefinition[];

package/dist/nav-icon.d.ts

@@ -1,3 +1,3 @@
-export declare const NAV_ICON_KEYS: readonly ["dashboard", "layout-grid", "book-open", "clipboard-list", "package", "gauge", "list", "table", "layers", "building", "calculator", "wallet", "coins", "credit-card", "piggy-bank", "receipt", "chart", "bar-chart", "trending", "sparkles", "wand", "calendar", "file", "folder", "folder-open", "home", "bell", "shield", "shield-check", "send", "settings", "users", "user", "search", "tag", "key", "link", "palette", "share", "server", "mail", "lock", "hash", "download", "upload", "rocket", "plus", "languages", "trash", "x", "check", "arrow-left", "arrow-right", "copy", "pencil", "eye", "eye-off", "filter", "refresh", "more-horizontal", "more-vertical", "external-link", "chevron-down", "chevron-left", "chevron-right", "save", "undo", "archive", "star", "flag", "clock", "map-pin", "phone", "printer", "alert-triangle", "info", "check-circle", "x-circle", "loader", "mic", "circle-stop", "image", "camera", "headphones"];
+export declare const NAV_ICON_KEYS: readonly ["dashboard", "layout-grid", "book-open", "clipboard-list", "package", "gauge", "list", "table", "layers", "building", "calculator", "wallet", "coins", "credit-card", "piggy-bank", "receipt", "chart", "bar-chart", "trending", "sparkles", "wand", "calendar", "file", "folder", "folder-open", "home", "bell", "shield", "shield-check", "send", "settings", "users", "user", "search", "tag", "key", "link", "palette", "share", "server", "mail", "lock", "hash", "download", "upload", "rocket", "plus", "languages", "trash", "x", "check", "arrow-left", "arrow-right", "copy", "pencil", "eye", "eye-off", "filter", "refresh", "more-horizontal", "more-vertical", "external-link", "chevron-down", "chevron-up", "chevron-left", "chevron-right", "save", "undo", "archive", "star", "flag", "clock", "map-pin", "phone", "printer", "alert-triangle", "info", "check-circle", "x-circle", "loader", "mic", "circle-stop", "image", "camera", "headphones"];
 export type NavIconKey = (typeof NAV_ICON_KEYS)[number];
 export type IconKey = NavIconKey;

package/dist/nav-icon.js

@@ -78,6 +78,7 @@ export const NAV_ICON_KEYS = [
     "more-vertical",
     "external-link",
     "chevron-down",
+    "chevron-up",
     "chevron-left",
     "chevron-right",
     "save",

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;
@@ -462,13 +530,20 @@ export type ProjectionListScreenDefinition = {
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;
 };
+export type RecordHeaderSubtitlePart = string | {
+    readonly field: string;
+    readonly navigate?: MetricNavigate;
+};
 export type RecordHeaderSpec = {
     readonly title: string;
-    readonly subtitle?: string;
+    /** Field name, or several parts (field name or `{ field, navigate }`)
+     *  joined by a separator; parts with an empty value are dropped. */
+    readonly subtitle?: string | readonly RecordHeaderSubtitlePart[];
     readonly status?: string;
     /** Record field holding an absolute http(s) URL. When present and the
      *  field's value is such a URL, the subtitle renders as an external link
-     *  (`target="_blank"`) instead of plain text. */
+     *  (`target="_blank"`) instead of plain text. Only valid with the string
+     *  form of `subtitle`. */
     readonly subtitleHref?: string;
     /** Badge tone per `status` field value; unlisted values fall back to the value heuristic. */
     readonly statusTones?: {
@@ -716,6 +791,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
@@ -773,6 +853,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
@@ -809,6 +893,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". */
@@ -878,6 +982,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
@@ -954,6 +1065,14 @@ export type EditLayout = {
     /** 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;
@@ -977,6 +1096,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
@@ -1078,6 +1202,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?: {
@@ -1124,6 +1254,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.331.0",
+  "version": "0.333.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>",