@cosmicdrift/kumiko-framework 0.416.0 → 0.418.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/agents/api/framework-engine.md +32 -9
  2. package/agents/api/framework-ui-types.md +37 -10
  3. package/agents/api/renderer-web.md +25 -2
  4. package/agents/api/types.md +121 -64
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +23 -1
  7. package/agents/examples/crypto-shredding-hr.md +2 -2
  8. package/agents/examples/dashboard-stats.md +51 -0
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/list-table-options.md +346 -12
  11. package/agents/examples/managed-config.md +9 -1
  12. package/agents/examples/record-detail-layout.md +71 -6
  13. package/agents/examples/secrets-demo.md +3 -1
  14. package/agents/examples/signature.md +3 -2
  15. package/agents/examples/writeform-section.md +329 -0
  16. package/agents/features.md +1 -1
  17. package/dist/api/server-boot-checks.d.ts +1 -0
  18. package/dist/api/server-boot-checks.js +25 -0
  19. package/dist/api/server-rate-limit-wiring.js +2 -1
  20. package/dist/db/queries/event-store.d.ts +3 -0
  21. package/dist/db/queries/event-store.js +12 -0
  22. package/dist/engine/boot-validator/action-form-preview-rules.d.ts +22 -0
  23. package/dist/engine/boot-validator/action-form-preview-rules.js +22 -0
  24. package/dist/engine/boot-validator/action-form-preview.d.ts +2 -0
  25. package/dist/engine/boot-validator/action-form-preview.js +54 -0
  26. package/dist/engine/boot-validator/boot-rules.d.ts +87 -1
  27. package/dist/engine/boot-validator/boot-rules.js +2 -0
  28. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  29. package/dist/engine/boot-validator/config-key-rules.d.ts +5 -0
  30. package/dist/engine/boot-validator/config-key-rules.js +5 -0
  31. package/dist/engine/boot-validator/date-only-after-days.d.ts +4 -0
  32. package/dist/engine/boot-validator/date-only-after-days.js +32 -0
  33. package/dist/engine/boot-validator/entity-handler.d.ts +1 -0
  34. package/dist/engine/boot-validator/entity-handler.js +1 -1
  35. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +40 -0
  36. package/dist/engine/boot-validator/list-bulk-actions-rules.js +40 -0
  37. package/dist/engine/boot-validator/list-bulk-actions.d.ts +2 -1
  38. package/dist/engine/boot-validator/list-bulk-actions.js +79 -9
  39. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  40. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  41. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  42. package/dist/engine/boot-validator/list-table-options.js +8 -6
  43. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  44. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  45. package/dist/engine/boot-validator/query-output-columns.js +29 -2
  46. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  47. package/dist/engine/boot-validator/query-refs.js +3 -0
  48. package/dist/engine/boot-validator/screens-actions.d.ts +7 -2
  49. package/dist/engine/boot-validator/screens-actions.js +4 -2
  50. package/dist/engine/boot-validator/screens-forms.js +2 -0
  51. package/dist/engine/boot-validator/screens-kind-entity-list.js +5 -3
  52. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  53. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  54. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  55. package/dist/engine/boot-validator/screens-kind-projection-list.js +2 -2
  56. package/dist/engine/boot-validator/screens-kind-shared.d.ts +1 -1
  57. package/dist/engine/boot-validator/screens-kind-shared.js +3 -1
  58. package/dist/engine/boot-validator/screens-lists-rules.d.ts +10 -0
  59. package/dist/engine/boot-validator/screens-lists-rules.js +10 -0
  60. package/dist/engine/boot-validator/screens-lists.js +13 -1
  61. package/dist/engine/boot-validator/screens.js +1 -2
  62. package/dist/engine/boot-validator/url-prefill-fields.js +8 -1
  63. package/dist/engine/boot-validator/zod-shape.d.ts +1 -0
  64. package/dist/engine/boot-validator/zod-shape.js +7 -0
  65. package/dist/engine/bridge-stub.js +1 -0
  66. package/dist/engine/build-config-feature-schema.js +30 -3
  67. package/dist/engine/screen-helpers.js +7 -3
  68. package/dist/engine/types/screen.d.ts +1 -1
  69. package/dist/engine/types/screen.js +1 -1
  70. package/dist/event-store/archive.d.ts +1 -0
  71. package/dist/event-store/archive.js +5 -1
  72. package/dist/event-store/event-store.d.ts +5 -0
  73. package/dist/event-store/event-store.js +23 -3
  74. package/dist/i18n/required-surface-keys.js +53 -13
  75. package/dist/pipeline/handler-context-events.js +15 -1
  76. package/dist/ui-types/card-column-roles.d.ts +3 -0
  77. package/dist/ui-types/card-column-roles.js +9 -5
  78. package/dist/ui-types/index.d.ts +1 -1
  79. package/package.json +3 -3
  80. package/src/changes.json +36 -0
@@ -300,6 +300,7 @@ type ActionFormScreenDefinition = {
300
300
  successLinks?: ActionFormSuccessLink[]; // Links shown in the success box after a successful submit while the screen stays put.
301
301
  successFacts?: ActionFormSuccessFact[]; // Key figures from the handler's success payload, shown in the success box while the screen stays put (e.g. charged/skipped/failed of a batch run).
302
302
  successItems?: ActionFormSuccessItems; // One hint per entry of a success-payload array, each with its own link (e.g. "this file is already in the inbox" with "Open" per uploaded file).
303
+ preview?: ActionFormPreview; // Preview of what the submit will do, computed by a query from the current form values.
303
304
  resetOnSuccess?: boolean; // Reset the form to its initial values after a successful submit (prefill kept, typed values cleared).
304
305
  load?: ActionFormLoad; // Load the initial values from a query.
305
306
  cancelTarget?: string | false; // Target of the Cancel button.
@@ -415,6 +416,7 @@ type ConfigEditScreenDefinition = {
415
416
  fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
416
417
  requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
417
418
  submitLabel?: string; // i18n key for the submit button.
419
+ compact?: true; // Compact rows: no origin icon, no reset link, no accent bar on changed fields; the form column is capped to a readable width.
418
420
  actions?: ConfigEditAction[]; // Handler buttons drawn as their own row after `afterField` (settings-list layout).
419
421
  slots?: ScreenSlots;
420
422
  access?: AccessRule;
@@ -537,6 +539,10 @@ type EditFieldSpec =
537
539
  fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
538
540
  aiAssist?: FieldAiAssist; // Helper under a `text` or `longText` input: stackable chips and an optional free instruction call a query and write its `resultField` into the field.
539
541
  valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
542
+ concealed?: true; // Read-only display of a value the viewer may not see: the value (or the mask the query returns) shows muted with a lock icon instead of a replacement text.
543
+ badge?: FieldBadge; // Pill next to the label, e.g. "price source open" in `warn`.
544
+ hintField?: string; // Value field whose non-empty text shows as a muted small hint under the field (e.g. "From the buyer: Skoda Octavia").
545
+ hideOnNarrow?: true; // Leaves the field out below `sm`; its value is still submitted.
540
546
  refEntity?: string; // Marks this field as a reference lookup instead of a plain value — for projectionDetail fields, which have no `EntityDefinition` to carry a real `reference` field type.
541
547
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
542
548
  format?: "email" | "phone"; // Text format for projectionDetail fields, which have no `EntityDefinition` to carry it: a read-only value renders as a `mailto:`/`tel:` link.
@@ -544,7 +550,7 @@ type EditFieldSpec =
544
550
  prefill?: EditFieldPrefill; // Fills an empty value when the create form opens; the update form and values from URL params or a handoff are never touched.
545
551
  }
546
552
  ;
547
- type EditRelatedListSection = {
553
+ type EditRelatedListSection = EditSectionPresentation & {
548
554
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
549
555
  visibleWhen?: Exclude<FieldCondition, boolean>; // projectionDetail only: shows the section (and its tab) only while the loaded record matches, same `{ field, eq | ne | in | notIn }` syntax as a field's `visibleWhen`.
550
556
  kind: "relatedList";
@@ -579,7 +585,9 @@ type EditRelatedListSection = {
579
585
  emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
580
586
  photoGrid?: {
581
587
  imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
582
- captionField?: string; // Row field printed under the image.
588
+ captionField?: string; // Row field printed under the image; without it the tile reads "Photo n".
589
+ badgeField?: string; // Row field whose non-empty text shows as a warn badge on the image's top left.
590
+ badgeFirst?: true; // On a phone (below `sm`) tiles whose `badgeField` has text come first, the rest keep their order; from `sm` up the natural order stays.
583
591
  }; // Draws the rows as a tile grid of images instead of a table.
584
592
  };
585
593
  type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
@@ -667,6 +675,7 @@ type EntityListScreenDefinition = {
667
675
  allowCreate?: boolean; // `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action.
668
676
  columns: ListColumnSpec[];
669
677
  rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
678
+ mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
670
679
  rowDecoration?: ListRowDecoration; // Computed row fields from an app query, readable by `rowToneField`, column `hint`, `linkScreenField`/`linkParamsField` and rowAction `visible`/`params`/`payload`; a column may name a decoration field.
671
680
  rowRenderer?: PlatformComponent;
672
681
  rowActions?: RowAction[]; // Per-row actions, rendered as an actions column on the right.
@@ -880,7 +889,7 @@ interface FieldFormatRegistry {
880
889
  absoluteAfterDays?: number;
881
890
  withTime?: boolean;
882
891
  timeZone?: string; // IANA zone id for the clock time and the day boundary.
883
- }; // Epoch ms or ISO timestamp, shown as "5 minutes ago" at render time (a table cell does not tick).
892
+ }; // Epoch ms or ISO timestamp, shown as "5 min.
884
893
  date: {
885
894
  locale?: string;
886
895
  dateStyle?: "full" | "long" | "medium" | "short";
@@ -967,6 +976,7 @@ type HandlerEvents<TMap extends object = KumikoEventTypeMap> = { // Event-store
967
976
  tryAppend: TryAppendEventFn; // Optimistic append: runs in a savepoint and returns a version conflict as a result instead of throwing, so the handler can continue after losing a race on the same aggregate stream.
968
977
  fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
969
978
  load: (aggregateId: string, options?: { asOf?: Temporal.Instant; atVersion?: never; includeArchived?: boolean; } | { atVersion?: number; asOf?: never; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
979
+ loadByTypes: (args: { aggregateIds: string[]; eventTypes: string[]; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
970
980
  archive: (aggregateId: string, args: { aggregateType: string; reason?: string; }) => Promise<void>;
971
981
  restore: (aggregateId: string) => Promise<void>;
972
982
  isArchived: (aggregateId: string) => Promise<boolean>;
@@ -1073,18 +1083,27 @@ type ListColumnSpec =
1073
1083
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
1074
1084
  sortable?: boolean; // Marks this column as sortable via a clickable header — for relatedList columns, which have no `EntityDefinition` field to carry `sortable` on.
1075
1085
  valueType?: "number" | "decimal" | "bigInt" | "money"; // Value type of a projectionList or relatedList column, which has no `EntityDefinition` field to derive it from.
1076
- emptyPlaceholder?: false; // `false` leaves an empty cell blank instead of drawing the "—" placeholder.
1077
- hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
1086
+ emptyPlaceholder?: string | false; // An empty cell stays blank by default; a string (i18n key or literal) is shown muted in its place, e.g. "No vehicle".
1087
+ hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (phone viewport).
1088
+ hideWhenDocked?: true; // Leaves the column out of a table whose container is narrower than `md` (docked assistant panel); the viewport is not looked at, so the phone card still shows it.
1078
1089
  showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
1079
1090
  narrowInline?: true; // In the compact card, consecutive `narrowInline` columns stand side by side on one line (12px gap, no separator) instead of one line each.
1091
+ ellipsis?: true; // One line with a trailing ellipsis in the table; the full text is the cell's `title`.
1092
+ multiline?: true; // Free text: the cell wraps instead of ending in "…", and a line break (`\n`) in the value starts a new line (table and phone card).
1093
+ cardAbove?: true; // Phone card: the column's line stands above the title (muted, e.g. "date, channel") instead of below it.
1094
+ emphasis?: true; // Cell text in medium weight and foreground colour, like the title column of a board.
1095
+ tone?: "muted"; // `"muted"` draws every cell of the column in the muted text colour (e.g. a free-text message beside primary columns).
1096
+ cardBadge?: true; // The phone card shows this column as its badge: right of the title, as an outlined neutral pill (a `display: "badge"` column keeps its own pill).
1097
+ dateOnlyAfterDays?: number; // Timestamp or relativeTime column: a value older than this many days shows the date only, without the time.
1080
1098
  hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
1081
1099
  pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
1082
1100
  width?: number; // Start width in px.
1083
1101
  minWidth?: number; // Smallest width in px the user can resize to.
1084
1102
  display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
1085
1103
  variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
1086
- badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
1104
+ badgeToneField?: string; // Row field naming the badge tone: a `ListBadgeTone` word or a `SelectOptionTone` word (`ok`, `bad`, `critical`, `accent`); only with `display: "badge"`.
1087
1105
  badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
1106
+ badgeIcon?: "sparkles"; // `"sparkles"` marks an AI-prepared value: the dashboard list draws the badge as the soft blue AI pill with a sparkles icon, like an AI row action; only with `display: "badge"`.
1088
1107
  pillField?: string; // Row field holding a second label, drawn as a pill next to the cell's own value (e.g. a vehicle name with a "free" pill).
1089
1108
  pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
1090
1109
  linkScreenField?: 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.
@@ -1410,8 +1429,11 @@ type ProjectionDetailScreenDefinition = {
1410
1429
  metrics?: MetricSpec[]; // Metric band above the layout — column names in the query row, each with its own i18n `label`.
1411
1430
  metricsStyle?: "band" | "tiles"; // "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band.
1412
1431
  metricsPlacement?: {
1413
- narrow?: "after-guidance";
1414
- }; // `narrow: "after-guidance"` moves the metrics below the summary, banner and steps on screens under md, ahead of the tabs.
1432
+ narrow?: "after-guidance" | "before-steps";
1433
+ }; // On screens under md, `narrow: "after-guidance"` moves the metrics below the summary, banner and steps, ahead of the tabs; `"before-steps"` puts them below the summary and banner, ahead of the next step.
1434
+ mobileSummary?: string; // Record field holding one line of text shown instead of the metrics below `sm`.
1435
+ pageNavigation?: false; // `false` leaves out the "On this page" navigation of a stacked (non-tabs) layout.
1436
+ photosBeside?: true; // A tab holding fields sections and a relatedList with `photoGrid` shows the fields left and the photos right from `lg` up.
1415
1437
  breadcrumb?: RecordBreadcrumbSpec; // Path above the header (query column holding items).
1416
1438
  summary?: RecordSummarySpec; // One emphasized sentence below the header.
1417
1439
  banner?: RecordBannerSpec; // Notice below the summary.
@@ -1420,7 +1442,7 @@ type ProjectionDetailScreenDefinition = {
1420
1442
  listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
1421
1443
  slots?: ScreenSlots;
1422
1444
  access?: AccessRule;
1423
- actions?: RowAction[]; // Header action buttons.
1445
+ actions?: EntityEditAction[]; // Header action buttons.
1424
1446
  primaryAction?: string; // Id of the action that stays the visible header button when the actions collapse into a menu (and the one that keeps the phone icon slot when it has an icon and no confirm).
1425
1447
  inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
1426
1448
  footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
@@ -1442,6 +1464,7 @@ type ProjectionListScreenDefinition = {
1442
1464
  query: string;
1443
1465
  columns: ListColumnSpec[];
1444
1466
  rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
1467
+ mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
1445
1468
  rowDecoration?: ListRowDecoration; // Computed row fields from an app query, merged into the query rows; see `ListRowDecoration`.
1446
1469
  rowRenderer?: PlatformComponent;
1447
1470
  rowActions?: RowAction[];
@@ -67,6 +67,17 @@ type ActionFormLoad = {
67
67
  singleton?: boolean; // The query picks the row from the caller's tenant/session context, so the form loads without a record id and the query is called WITHOUT `idParam` (same semantics as `ProjectionDetailScreenDefinition.singleton`).
68
68
  passPrefill?: boolean; // Sends the values a drawer opens the form with (row-action params, e.g. `vehicleId`) in the load payload next to `idParam`, so the query can pre-fill for the chosen item.
69
69
  };
70
+ type ActionFormPreview = { // Preview panel above the submit button: runs a query over the current form values and shows what the submit would do.
71
+ query: string; // Query QN.
72
+ fields?: string[]; // Form fields sent to the query; they also trigger a rerun when they change.
73
+ title?: string; // Panel title (i18n key).
74
+ facts?: ActionFormSuccessFact[]; // Key figures from the query result, shown like the success box facts.
75
+ list?: ActionFormPreviewList; // Table of rows from the query result.
76
+ };
77
+ type ActionFormPreviewList = { // Rows of the preview panel, read from an array in the preview query's result.
78
+ field: string; // Flat field name of an array in the query result; an entry that is no object is skipped.
79
+ columns: { field: string; label: string; type?: ActionFormValueType; }[];
80
+ };
70
81
  type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
71
82
  screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
72
83
  idFrom?: string; // Flat field name in the handler's success payload, e.g. "leaseId".
@@ -76,6 +87,7 @@ type ActionFormRedirect = { // Redirect target plus the success-payload field ca
76
87
  type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
77
88
  field: string; // Flat field name in the handler's success payload.
78
89
  label: string; // Label (i18n key).
90
+ type?: ActionFormValueType; // Format of the value (a money object, a date string, a number); default `text`.
79
91
  };
80
92
  type ActionFormSuccessItems = { // Per-entry hints of the success box, read from an array in the handler's success payload.
81
93
  field: string; // Flat field name of an array in the success payload.
@@ -86,6 +98,7 @@ type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom" | "searchParams">
86
98
  params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
87
99
  label: string; // Link text (i18n key).
88
100
  };
101
+ type ActionFormValueType = "text" | "number" | "money" | "date" | "timestamp"; // How a preview value or success fact is formatted, by the same formatters a list cell uses.
89
102
  type AppSchema = {
90
103
  features: FeatureSchema[];
91
104
  workspaces?: WorkspaceSchema[];
@@ -154,6 +167,7 @@ type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState
154
167
  id: string;
155
168
  label: string;
156
169
  query: string;
170
+ showTotal?: true | Pick<DashboardListShowTotal, "text">; // Shows the count in the panel head, right-aligned like a list panel's `showTotal`: `{total}` is the query's `total`, else the rows returned.
157
171
  };
158
172
  type DashboardFilterDefinition = {
159
173
  id: string;
@@ -166,7 +180,7 @@ type DashboardFilterDefinition = {
166
180
  };
167
181
  type DashboardLayout = "main-side"; // "main-side": from `lg` up the main column (2/3) stacks every panel without `column`, the side column (1/3) every `column: "side"` panel, each with its own heights; `column: "top"` panels span both columns above them; below `lg` they stack, below `sm` by `narrowOrder`.
168
182
  type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
169
- label: string;
183
+ label?: string; // i18n key of the link text.
170
184
  moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
171
185
  narrowMoreText?: string; // i18n key used instead of `moreText` below `sm`.
172
186
  narrowOnly?: boolean; // Draw the link only below `sm`, where it is the target of the "line" layout; from `sm` up the panel shows no footer link.
@@ -229,6 +243,8 @@ type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmp
229
243
  kind: "progress-list";
230
244
  id: string;
231
245
  label: string;
246
+ labelParams?: Readonly<Record<string, string>>; // Fills the translated `label` from the query answer: maps a label placeholder to a top-level answer field, e.g. `{ month: "monthName" }` for "Quota {month}" with `{ rows, monthName: "November" }`.
247
+ subtitleField?: string; // Top-level answer field holding a text shown muted at the right end of the panel head, e.g. the period ("November").
232
248
  query: string;
233
249
  };
234
250
  type DashboardProgressTone = "default" | "danger";
@@ -309,6 +325,7 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & Dash
309
325
  valueField: string;
310
326
  labelField?: string; // Field of the query answer holding the label text, e.g. "Contracts ending by 31.01.2027"; it replaces the static `label` while it holds a non-empty string.
311
327
  narrowLabel?: string; // i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests").
328
+ labelNarrow?: string; // i18n key replacing `label` below the `sm` breakpoint wherever the stat draws its label (a dynamic `labelField` text still wins).
312
329
  subField?: string;
313
330
  toneField?: string;
314
331
  valueFormat?: DashboardValueFormat; // Formats a numeric value as currency (minor units) or, with `relativeTime`, as a ticking "5 minutes ago" from epoch ms; ignored for string values.
@@ -375,7 +392,7 @@ type DerivedCellRoundingTarget = {
375
392
  type: EmbeddedSubFieldDef["type"];
376
393
  scale?: number;
377
394
  };
378
- type EditExtensionSection = {
395
+ type EditExtensionSection = EditSectionPresentation & {
379
396
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
380
397
  visibleWhen?: Exclude<FieldCondition, boolean>; // projectionDetail only: shows the section (and its tab) only while the loaded record matches, same `{ field, eq | ne | in | notIn }` syntax as a field's `visibleWhen`.
381
398
  kind: "extension";
@@ -395,6 +412,7 @@ type EditLayout = {
395
412
  sections: EditSectionSpec[];
396
413
  width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
397
414
  mode?: "single" | "wizard" | "tabs"; // Default "single".
415
+ narrowTabs?: false; // `false` (tabs mode): below `sm` there is no tab strip, the visible sections of every tab stand one under the other.
398
416
  variant?: "form" | "settings-list"; // "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.
399
417
  hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
400
418
  allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
@@ -408,7 +426,7 @@ type EditLayout = {
408
426
  submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
409
427
  }; // Wizard layouts only.
410
428
  };
411
- type EditStepListSection = { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
429
+ type EditStepListSection = EditSectionPresentation & { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
412
430
  id?: string;
413
431
  visibleWhen?: Exclude<FieldCondition, boolean>;
414
432
  kind: "stepList";
@@ -416,18 +434,20 @@ type EditStepListSection = { // Vertical numbered step list (circles joined by a
416
434
  field: string; // Output field of the detail query holding a `StepListItem[]`.
417
435
  actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
418
436
  };
419
- type EditWriteFormSection = {
437
+ type EditWriteFormSection = EditSectionPresentation & {
420
438
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
421
439
  visibleWhen?: Exclude<FieldCondition, boolean>; // projectionDetail only: shows the section (and its tab) only while the loaded record matches, same `{ field, eq | ne | in | notIn }` syntax as a field's `visibleWhen`.
422
440
  kind: "writeForm";
423
441
  title?: string;
424
442
  description?: string;
443
+ descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
425
444
  columns?: number;
426
445
  icon?: IconKey;
427
446
  fieldDefs: Readonly<Record<string, FieldDefinition>>; // Field-type map for this section's own form — same shape as `ActionFormScreenDefinition.fields`.
428
447
  fields: EditFieldSpec[]; // Rendered fields, in order — same shape as `EditFieldsSection.fields`.
429
448
  handler: string; // Write-handler QN dispatched on submit.
430
449
  submitLabel?: string; // i18n-key for the submit button.
450
+ submitWith?: string; // Id of a writeHandler action in the screen's `actions`.
431
451
  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
432
452
  };
433
453
  type EmbeddedDerivedCellDef = ({ op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; } | { op: "inRange"; from: string[]; inside: string; outside: string; }) & { // A cell computed from other cells of the same row.
@@ -480,6 +500,16 @@ type FieldAiAssistChip = { // One toggle chip: while active, its `params` are me
480
500
  label: string; // i18n key of the chip label.
481
501
  params: Readonly<Record<string, string | number | boolean>>;
482
502
  };
503
+ type FieldBadge = // Pill next to a field label: a fixed i18n `label`, or the text of another value `field`.
504
+ | {
505
+ label: string;
506
+ tone: SelectOptionTone;
507
+ }
508
+ | {
509
+ field: string;
510
+ tone: SelectOptionTone;
511
+ }
512
+ ;
483
513
  type FieldFillAction = {
484
514
  label: string; // i18n key (falls back to the literal) of the button label.
485
515
  query: string; // Qualified query name, run with the current form values picked by `params`.
@@ -505,11 +535,7 @@ type FormDerivationScreen = {
505
535
  type FormWidth = "3xl" | "4xl" | "full";
506
536
  type Formality = "formal" | "informal";
507
537
  type IconKey = NavIconKey;
508
- type ListBulkAction = { // An action that runs a writeHandler row action once per checkbox-selected row.
509
- id: string; // Stable id, kebab-case, unique among the screen's bulk actions.
510
- rowAction: string; // Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`.
511
- confirm?: string; // i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`.
512
- };
538
+ type ListBulkAction = ListBulkRowAction | ListBulkFormAction; // An action over checkbox-selected rows: a writeHandler row action per row (`rowAction`) or one form for all rows (`screen` + `idsField`).
513
539
  type ListColumnHint = {
514
540
  detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
515
541
  narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
@@ -560,6 +586,7 @@ type QualifiedContentCollection = ContentCollectionDefinition & {
560
586
  };
561
587
  type RecordBannerSpec = {
562
588
  field: string; // Holds `RecordNotice | null`; null shows no banner.
589
+ iconless?: true; // Draws the notice without the tone icon.
563
590
  actions?: RecordGuidanceAction[];
564
591
  };
565
592
  type RecordBreadcrumbItem = {
@@ -659,7 +686,7 @@ type RowActionClientAction = {
659
686
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
660
687
  successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
661
688
  };
662
- type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
689
+ type RowActionDisplay = "button" | "link" | "icon" | "responsive" | "text"; // How a row action renders inline in the row-action column.
663
690
  type RowActionDrawer = {
664
691
  kind: "drawer";
665
692
  id: string;
@@ -50,7 +50,7 @@ function FileViewAction(props: { fileId: string; }): ReactNode; // "View" action
50
50
  function FloatingPanel(props: FloatingPanelProps): ReactNode; // Non-modal panel floating above the page: draggable by its header, resizable from all edges and corners, clamped to the viewport, geometry optionally remembered.
51
51
  function FormScreenShell(props: { children: ReactNode; className?: string; testId?: string; maxWidth?: FormScreenShellWidth; fillHeight?: boolean; }): ReactNode;
52
52
  function HeaderActionGroup(props: HeaderActionGroupProps): ReactNode;
53
- function HeaderActionPinned(props: { children: ReactNode; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
53
+ function HeaderActionPinned(props: { children: ReactNode; hideOnListScreens?: boolean; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
54
54
  function HtmlMailFrame(props: { html: string; title: string; allowRemoteImages: boolean; testId?: string; }): ReactNode; // Renders server-sanitized mail HTML in a script-free sandboxed iframe that grows to its content.
55
55
  function Icon(props: { name: NavIconKey; className?: string; }): ReactNode;
56
56
  function InfinityList<TData = unknown, TRow = Readonly<Record<string, unknown>>>(props: InfinityListProps<TData, TRow>): ReactNode; // Cursor-paginated scroll list (mail inbox, activity feeds) — loads the next page when the end sentinel becomes visible (IntersectionObserver), instead of a pager bar like QueryTable/entityList.
@@ -262,7 +262,7 @@ type AvatarProps = {
262
262
  type AvatarShape = "square" | "round";
263
263
  type AvatarSize = "xs" | "sm" | "md" | "lg";
264
264
  type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
265
- variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done").
265
+ variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok" | "assist"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done"), "assist" for an AI hint: soft primary surface, primary text, no border.
266
266
  inline?: boolean; // Title and text run on one line (text right behind the bold title); the text is dropped below sm, so a phone shows title and actions only.
267
267
  density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
268
268
  icon?: NavIconKey; // Icon left of the text.
@@ -445,6 +445,7 @@ type DataTableProps = DataTableTableBlock & {
445
445
  columns: ListColumnViewModel[];
446
446
  rows: ListRowViewModel[];
447
447
  rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
448
+ rowMuted?: (row: ListRowViewModel) => boolean; // Draws the whole row in the muted text colour.
448
449
  onRowClick?: (row: ListRowViewModel) => void;
449
450
  sort?: DataTableSort | null; // Current sorting, or null when unsorted.
450
451
  onSortChange?: (next: DataTableSort | null) => void; // Called with the next sort state after a header click (asc → desc → null); the caller updates URL state or the query parameter and refetches.
@@ -482,6 +483,8 @@ type DataTableProps = DataTableTableBlock & {
482
483
  getCellTestId?: (row: ListRowViewModel, field: string) => string; // Overrides the cell `data-testid` (default `cell-${row.id}-${field}`).
483
484
  chromeless?: boolean; // Drops the table's own rounded/border/card background — for a host that already provides the surrounding boundary (a tab panel) and would otherwise show a card nested inside that boundary.
484
485
  scrollBody?: boolean; // Fills the available height of its flex container and scrolls rows internally instead of growing with row count — for a host that would otherwise have a long table stretch the whole page, or a short table leave dead space below it (a tab panel).
486
+ hideCountFooter?: boolean; // Drops the "n entries" footer of a `scrollBody` table (a pager stays).
487
+ plainPhoneCards?: boolean; // Phone cards as a plain feed: no sort line, the above-title meta joined with commas, the last meta line in the text colour.
485
488
  screenPadding?: boolean; // Uses the shared screen padding (wider bottom inset) instead of the table's symmetric embedded inset — for a table that IS the screen body (entityList/projectionList), so a list screen ends at the same footer distance as a form or custom screen.
486
489
  expandedRowIds?: ReadonlySet<string>; // Ids of the rows whose expansion area is currently open (controlled by the host; several rows can be open at once).
487
490
  onToggleRowExpanded?: (rowId: string) => void; // User toggled a row's expand control.
@@ -674,12 +677,14 @@ type FormProps = { // Submit wrapper.
674
677
  title: string;
675
678
  subtitle?: string;
676
679
  }; // Drawer-hosted forms: context box above the fields.
680
+ topBanner?: ReactNode; // Rendered above everything else in the form body (above `summary`), e.g. the submit error.
677
681
  sectionNav?: FormSectionNavItem[]; // Titled sections for the "on this page" navigation next to a `screenForm`.
678
682
  sideRail?: ReactNode; // Leading column next to the scroll surface of a `screenForm` (wizard step navigation).
679
683
  };
680
684
  type GridCellProps = { // Span wrapper for a child within a grid.
681
685
  span?: number;
682
686
  width?: FieldCellWidth; // Only read inside a `flow` grid.
687
+ hideOnNarrow?: boolean; // Hidden below the `sm` breakpoint.
683
688
  children: ReactNode;
684
689
  };
685
690
  type GridProps = { // Column-based layout.
@@ -691,6 +696,7 @@ type GridProps = { // Column-based layout.
691
696
  list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
692
697
  ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
693
698
  tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
699
+ facts?: boolean; // Read-only label/value facts: a true `columns`-wide grid with a tight gap, at most 2 columns below `sm`.
694
700
  };
695
701
  type HeaderActionGroupProps = {
696
702
  children: ReactNode;
@@ -1363,8 +1369,15 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1363
1369
  valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
1364
1370
  hideSectionTitles?: boolean; // Suppresses every section's own title (fields-section header, relatedList Section title) AND the form's own top-level title/subtitle — for a host that already renders that label itself elsewhere (e.g. a tab strip whose label duplicates it, or a page-level header above RenderEdit).
1365
1371
  activeTabId?: string; // Id of the active tab of a tabbed projectionDetail; handed to the `afterForm` slot.
1372
+ recordSections?: {
1373
+ labelTitles?: true; // Section titles render as small uppercase labels without separators.
1374
+ omitFirstTitle?: true; // The first section's title is the tab label right above it and is left out.
1375
+ pageNavigation?: false; // `false` leaves out the "On this page" navigation.
1376
+ photosBeside?: true; // Fields sections and the photo-grid relatedList sit side by side from `lg` up.
1377
+ }; // Record-view look of a projectionDetail; each key is opt-in.
1366
1378
  fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
1367
1379
  leadContent?: ReactNode; // Rendered first inside the form, above the sections, in the same column and rhythm — for content that belongs to the form but is no field (e.g. the secret a confirm step refers to).
1380
+ belowSections?: (values: Readonly<Record<string, unknown>>) => ReactNode; // Rendered after the sections, above the form actions, with the live form values.
1368
1381
  submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
1369
1382
  formDerivation?: FormDerivationScreen; // actionForm `derive`: derived fields are recomputed into the form state on every change and render read-only.
1370
1383
  actionFormScreenQn?: string; // QN of the actionForm screen this form renders; its file fields upload as pending for that screen.
@@ -1439,6 +1452,8 @@ type RenderListProps = DataTableTableBlockProps & {
1439
1452
  onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed (set URL state + refetch).
1440
1453
  chromeless?: boolean; // Forwarded to `DataTableProps.chromeless` — drops the table's own card frame for a host that already provides one (relatedList in a tabs-mode section).
1441
1454
  scrollBody?: boolean; // Forwarded to `DataTableProps.scrollBody` — bounds the table height and scrolls rows internally instead of growing the page (relatedList in a tabs-mode section).
1455
+ hideCountFooter?: boolean; // Forwarded to `DataTableProps.hideCountFooter` (relatedList: the tab label already says how many).
1456
+ plainPhoneCards?: boolean; // Forwarded to `DataTableProps.plainPhoneCards` (relatedList: a history reads as a plain feed on the phone).
1442
1457
  screenPadding?: boolean; // Forwarded to `DataTableProps.screenPadding` — `true`: the table carries the shared screen padding because it is the screen body (entityList/ projectionList).
1443
1458
  expandedRowIds?: ReadonlySet<string>; // Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` / `renderExpandedRow` (entityList `expandableRow`).
1444
1459
  onToggleRowExpanded?: (rowId: string) => void;
@@ -1465,6 +1480,12 @@ type SectionProps = { // Titled group of fields.
1465
1480
  actions?: ReactNode; // Rendered top-right in the title row — never a footer.
1466
1481
  layout?: "stacked" | "settings-list"; // "settings-list": title + subtitle form a left header column and the children (field rows) the right one on `md:` and up.
1467
1482
  variant?: "default" | "destructive"; // "destructive" marks the Section as a warning/danger area (e.g. account deletion, restrict processing) — border color only, no content change.
1483
+ titleStyle?: "heading" | "label"; // "label": the title is a small uppercase muted label and the section has no separator line above it.
1484
+ hint?: {
1485
+ text: string;
1486
+ textNarrow?: string;
1487
+ testId: string;
1488
+ }; // Small muted note under the section content on `sm` and up, above it on a phone.
1468
1489
  testId?: string;
1469
1490
  icon?: IconKey; // Rendered left of the title, `text-muted-foreground`, same optical size as the title.
1470
1491
  };
@@ -1621,6 +1642,8 @@ interface TextFieldProps extends FieldBase {
1621
1642
  type TextProps = { // Semantic text.
1622
1643
  variant?: "body" | "small" | "code" | "required-mark" | "muted";
1623
1644
  decorative?: boolean; // Pure ornament (e.g. a separator glyph): hidden from assistive tech.
1645
+ concealed?: boolean; // A value the viewer may not see: drawn muted with a lock icon before it.
1646
+ narrow?: string; // Phone wording: `children` show from `sm` up, this text below it.
1624
1647
  children: ReactNode;
1625
1648
  testId?: string;
1626
1649
  };