@cosmicdrift/kumiko-framework 0.414.0 → 0.416.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 (115) hide show
  1. package/agents/api/framework-engine.md +46 -8
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +69 -4
  4. package/agents/api/renderer-web.md +27 -4
  5. package/agents/api/types.md +68 -16
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +39 -7
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/embedded.md +24 -1
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/record-detail-layout.md +113 -7
  12. package/agents/examples/signature.md +186 -0
  13. package/agents/examples/writeform-section.md +1 -0
  14. package/agents/examples.md +2 -0
  15. package/agents/features-index.md +4 -0
  16. package/agents/features.md +14 -0
  17. package/agents/widgets.md +7 -0
  18. package/dist/api/request-context-internals.d.ts +2 -0
  19. package/dist/api/request-context-scopes.js +9 -2
  20. package/dist/api/request-context.js +1 -1
  21. package/dist/api/routes.js +4 -4
  22. package/dist/api/server-event-dispatcher.js +3 -0
  23. package/dist/api/server-routes.js +2 -0
  24. package/dist/db/parent-ref-clause.js +31 -3
  25. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  26. package/dist/db/parent-ref-global-hosts.js +50 -12
  27. package/dist/db/queries/rls-boot-catalog.js +5 -6
  28. package/dist/db/queries/rls-shape.d.ts +1 -0
  29. package/dist/db/queries/rls-shape.js +21 -6
  30. package/dist/db/table-builder.js +3 -1
  31. package/dist/engine/boot-validator/boot-phases.js +5 -0
  32. package/dist/engine/boot-validator/boot-rules.d.ts +144 -9
  33. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  34. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  35. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  36. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  37. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  38. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  39. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  40. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  41. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +17 -2
  42. package/dist/engine/boot-validator/list-row-guidance-rules.js +17 -2
  43. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  44. package/dist/engine/boot-validator/list-row-guidance.js +45 -1
  45. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  46. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  47. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  48. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  49. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  50. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  51. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  52. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  53. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  54. package/dist/engine/boot-validator/query-refs.js +14 -1
  55. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  56. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  57. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  58. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  59. package/dist/engine/boot-validator/screens-actions.js +56 -16
  60. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  61. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  62. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  63. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  64. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  65. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  68. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  69. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  70. package/dist/engine/boot-validator/screens-forms.js +108 -2
  71. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  72. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  73. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  74. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  75. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  76. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  77. package/dist/engine/boot-validator/screens-lists.js +4 -1
  78. package/dist/engine/build-config-feature-schema.js +5 -35
  79. package/dist/engine/config-access-rules.d.ts +3 -0
  80. package/dist/engine/config-access-rules.js +34 -0
  81. package/dist/engine/factories.d.ts +2 -0
  82. package/dist/engine/named-filter-roles.js +6 -14
  83. package/dist/engine/project-app-schema-for-roles.js +2 -0
  84. package/dist/engine/schema-builder.js +3 -1
  85. package/dist/engine/soft-delete-cleanup.js +2 -0
  86. package/dist/errors/reasons.d.ts +1 -0
  87. package/dist/errors/reasons.js +4 -0
  88. package/dist/files/file-routes.d.ts +2 -0
  89. package/dist/files/file-routes.js +85 -22
  90. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  91. package/dist/files/foreign-tenant-file-read.js +64 -0
  92. package/dist/i18n/required-surface-keys.js +28 -7
  93. package/dist/jobs/job-runner-execution.js +3 -0
  94. package/dist/jobs/job-runner-types.d.ts +1 -0
  95. package/dist/jobs/job-runner.js +8 -0
  96. package/dist/pipeline/context-services.d.ts +1 -1
  97. package/dist/pipeline/context-services.js +1 -1
  98. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  99. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  100. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  101. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  102. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  103. package/dist/search/meilisearch-adapter-internals.js +5 -0
  104. package/dist/search/meilisearch-adapter.d.ts +1 -0
  105. package/dist/search/meilisearch-adapter.js +3 -2
  106. package/dist/ui-types/card-column-roles.d.ts +2 -0
  107. package/dist/ui-types/card-column-roles.js +15 -0
  108. package/dist/ui-types/index.d.ts +2 -2
  109. package/dist/ui-types/index.js +1 -1
  110. package/package.json +3 -3
  111. package/presets/biome-plugins/no-date-api.grit +3 -1
  112. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  113. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  114. package/presets/biome-rules.json +12 -10
  115. package/src/changes.json +99 -0
@@ -1276,6 +1276,7 @@ type JobRunner = {
1276
1276
  handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
1277
1277
  attachDispatcher(ref: DispatchWriteRef): void;
1278
1278
  countPendingJobs(): Promise<number>;
1279
+ isJobPending?(jobName: string, jobId: string): Promise<boolean>;
1279
1280
  };
1280
1281
  type JobRunnerOptions = {
1281
1282
  registry: Registry;
@@ -1436,6 +1437,7 @@ type EventConsumer = {
1436
1437
  featureName?: string;
1437
1438
  delivery?: "shared" | "per-instance";
1438
1439
  startFrom?: "beginning" | "now";
1440
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
1439
1441
  };
1440
1442
  type EventConsumerBatchHandler = (events: StoredEvent[], ctx: AppContext, turn: BatchTurnControl) => Promise<void>;
1441
1443
  type EventConsumerErrorPolicy = {
@@ -1534,6 +1536,7 @@ type CardRoleColumn = {
1534
1536
  type?: string;
1535
1537
  renderer?: unknown;
1536
1538
  hideOnNarrow?: boolean;
1539
+ narrowInline?: boolean;
1537
1540
  fileDisplay?: {
1538
1541
  kind: string;
1539
1542
  };
@@ -1657,6 +1660,7 @@ type ExtensionSectionProps = {
1657
1660
  isLast: boolean;
1658
1661
  }; // Current wizard step, only set for `layout.mode === "wizard"` forms.
1659
1662
  reportStepComplete?: (complete: boolean) => void; // Only set for extension steps of a `layout.mode: "wizard"` entityEdit editing an existing record (update mode); undefined everywhere else.
1663
+ activeTabId?: string; // Id of the active tab; only set in the `afterForm` slot of a projectionDetail screen with tabs, so the component can limit itself to one tab.
1660
1664
  };
1661
1665
  ```
1662
1666
 
@@ -1678,6 +1682,21 @@ type ScreenTarget = {
1678
1682
  };
1679
1683
  ```
1680
1684
 
1685
+ ## packages/renderer/src/card-options.ts
1686
+
1687
+ ```ts
1688
+ type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar.
1689
+ padded?: boolean; // Body-Padding (px-6 py-6).
1690
+ radius?: "lg" | "xl"; // Eckenradius.
1691
+ footerBordered?: boolean; // Separates the footer with `border-t` and `bg-muted/30`.
1692
+ footerInset?: boolean; // Footer horizontal padding.
1693
+ fillHeight?: boolean; // Joins the ancestor fillHeight flex chain — a tabs-mode relatedList table sizing to the panel instead of the page — instead of normal document-flow height.
1694
+ framed?: boolean; // false drops border, background, shadow and radius but keeps padding and header slots — a panel inside a host surface such as a tab panel.
1695
+ screenBody?: boolean; // The card is the whole screen body (secretMint reveal and done phase): no frame, the shared screen insets and width of form screens, children stacked with a gap.
1696
+ headerLayout?: "stacked" | "inline"; // "inline": title and subtitle on one baseline row at 16px inset, compact padding (the board's side panel).
1697
+ };
1698
+ ```
1699
+
1681
1700
  ## packages/renderer/src/components/form-pending-uploads.tsx
1682
1701
 
1683
1702
  ```ts
@@ -1695,6 +1714,10 @@ type ListEmptyStateContent = {
1695
1714
  type NamedFilterEmptyContent = {
1696
1715
  title: string;
1697
1716
  description?: string;
1717
+ describedByQuery?: {
1718
+ query: string;
1719
+ describe: (params: Readonly<Record<string, unknown>>) => string;
1720
+ }; // The description needs params from a query; it renders only once the query returned an object.
1698
1721
  onReset: () => void;
1699
1722
  };
1700
1723
  ```
@@ -1712,6 +1735,8 @@ type RenderEditAction = {
1712
1735
  confirmLabel?: string;
1713
1736
  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
1714
1737
  icon?: IconKey; // Resolved icon (author `RowAction.icon` or the id-derived default) — drives both the icon-left-of-text render and the icon-only collapse rule (see `shouldRenderActionsIconOnly`).
1738
+ align?: "start"; // "start" sets the button apart on the left of the form footer.
1739
+ pinnedOnPhone?: true; // Stays a visible button in the pinned footer below `sm` instead of folding into the "…" menu.
1715
1740
  };
1716
1741
  ```
1717
1742
 
@@ -1826,6 +1851,7 @@ type DataTableFacet = {
1826
1851
  display?: "select"; // Chips only: "select" renders the chips as one single-choice dropdown instead of a row of toggles.
1827
1852
  showCounts?: boolean; // Chips only: show each chip's `count` next to its label.
1828
1853
  hideEmpty?: boolean; // Chips only: hide chips whose `count` is 0 (unless pressed).
1854
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field instead of standing as a pill.
1829
1855
  onSearchChange?: (query: string) => void; // Present: the options come from a server-side search (reference facets), so the dropdown shows a search field and reports the typed term instead of filtering `options` itself.
1830
1856
  searching?: boolean; // The search is loading; the option list may still show the previous term's rows.
1831
1857
  };
@@ -1833,6 +1859,7 @@ type DataTableFacetChip = {
1833
1859
  id: string;
1834
1860
  label: string; // Translated chip label.
1835
1861
  values: string[]; // Selection a click sets; `[]` clears the facet.
1862
+ separatorAfter?: boolean; // Select display: a divider line follows this chip.
1836
1863
  count?: number; // Matching row count, undefined while unknown.
1837
1864
  };
1838
1865
  ```
@@ -2193,7 +2220,7 @@ type EditFieldViewModel = {
2193
2220
  query: string;
2194
2221
  payload: OptionsQueryPayload;
2195
2222
  }; // Set for `type: "select"` / `"multiSelect"` when optionsAvailabilityQuery is set: the renderer loads `{ rows: { value, disabled?, hint?
2196
- display?: "checkboxes" | "dropdown" | "radio"; // Set for `type: "multiSelect"` when MultiSelectFieldDef.display is "checkboxes" — the renderer shows a checkbox grid with a select-all toggle instead of the default combobox dropdown.
2223
+ display?: "checkboxes" | "chips" | "dropdown" | "radio"; // Set for `type: "multiSelect"` when MultiSelectFieldDef.display is "checkboxes" — the renderer shows a checkbox grid with a select-all toggle instead of the default combobox dropdown.
2197
2224
  optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // `type: "select"` only: tone per option, shown on the selected radio segment.
2198
2225
  columns?: 1 | 2 | 3 | 4; // Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is defined — column count for the checkbox grid at the widest breakpoint.
2199
2226
  maxRows?: number; // Set for `type: "multiSelect"` when MultiSelectFieldDef.maxRows is defined — grid rows visible before the checkbox grid becomes scrollable.
@@ -2227,6 +2254,8 @@ type EditFieldViewModel = {
2227
2254
  prefix?: FieldAffix; // From EditFieldSpec.prefix / suffix.
2228
2255
  suffix?: FieldAffix;
2229
2256
  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
2257
+ aiAssist?: FieldAiAssist; // From EditFieldSpec.aiAssist, chip labels and the prompt placeholder already translated.
2258
+ valueChips?: FieldValueChips; // From EditFieldSpec.valueChips.
2230
2259
  embeddedListCells?: EmbeddedListCellViewModel[]; // Only set for an embedded-LIST field (`multiple: true`) — the per-cell metadata the renderer needs to draw each column/cell.
2231
2260
  embeddedListMinItems?: number; // Minimum row count for the embedded list.
2232
2261
  embeddedListMaxItems?: number; // Maximum row count for the embedded list.
@@ -2278,6 +2307,7 @@ type ListColumnFileDisplay = // How a list cell shows a FileRef value (id or id
2278
2307
  type ListColumnHintViewModel = {
2279
2308
  detailField?: string;
2280
2309
  narrowDetailField?: string; // `ListColumnHint.narrowDetailField`: replaces `detailField` in the phone card.
2310
+ narrowField?: string; // `ListColumnHint.narrowField`: replaces the sentence value in the phone card.
2281
2311
  toneField?: string;
2282
2312
  reasonField?: string;
2283
2313
  reasonOpenField?: string;
@@ -2303,6 +2333,7 @@ type ListColumnViewModel = {
2303
2333
  highlighted?: boolean; // Set by the caller at runtime (not schema-derived) to emphasize one column — e.g. the currently selected base-year column in a multi-year statement grid.
2304
2334
  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
2305
2335
  showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2336
+ narrowInline?: boolean; // Mirrors `ListColumnSpec.narrowInline`: the card draws consecutive such columns on one line.
2306
2337
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
2307
2338
  fileDisplay?: ListColumnFileDisplay; // Set for file/image columns: from the entity field type, or from a `{ format: "image" | "file" }` renderer.
2308
2339
  hint?: ListColumnHintViewModel; // "To do" cell (`ListColumnSpec.hint`), `emptyLabel` already translated.
@@ -2311,6 +2342,8 @@ type ListColumnViewModel = {
2311
2342
  display?: ListColumnCellDisplay; // `ListColumnSpec.display` for list tables: a status pill or a link drawn as a button.
2312
2343
  badgeToneField?: string; // Row field naming the pill tone; only with `display: "badge"`.
2313
2344
  badgeDot?: false; // `false`: the pill has no leading dot.
2345
+ pillField?: string; // Row field with the label of a pill drawn beside the cell value (`ListColumnSpec.pillField`).
2346
+ pillToneField?: string; // Row field naming the pill tone.
2314
2347
  emptyPlaceholder?: false; // `false`: an empty cell stays blank instead of showing "—".
2315
2348
  };
2316
2349
  type ListRowViewModel = {
@@ -2348,12 +2381,17 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2348
2381
  tone?: DashboardStatTone;
2349
2382
  icon?: NavIconKey;
2350
2383
  sub?: string; // Small muted line under the value (see `MetricSpec.subField`).
2384
+ narrowSub?: string; // Replaces `sub` below `sm` (see `MetricSpec.subFieldNarrow`).
2351
2385
  };
2352
2386
  ```
2353
2387
 
2354
2388
  ## packages/renderer/src/primitives-record-guidance.ts
2355
2389
 
2356
2390
  ```ts
2391
+ type PhotoGridProps = { // Grid of image tiles; each tile shows a stored file and its own action buttons underneath.
2392
+ tiles: { id: string; imageId?: string; caption?: string; actions?: ReactNode; }[];
2393
+ testId?: string;
2394
+ };
2357
2395
  type RecordBreadcrumbProps = { // Path above a record header; an item with a `link` is a link, the last item without one names the current record.
2358
2396
  items: { label: string; link?: CellLink; }[];
2359
2397
  ariaLabel: string;
@@ -2367,7 +2405,8 @@ type RecordStepsProps = { // "Next steps" panel; an item's `reason` sits behind
2367
2405
  narrowLimit?: number; // Below the sm breakpoint only this many steps show; the rest sits behind a toggle.
2368
2406
  moreLabel?: (hiddenCount: number) => string; // Toggle label for the hidden steps; receives their count.
2369
2407
  lessLabel?: string;
2370
- items: { id: string; title: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2408
+ moreActionsLabel?: string; // Label before the further actions of each item.
2409
+ items: { id: string; title: string; narrowTitle?: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2371
2410
  count?: number; // Total number of steps, shown small beside the heading even when `narrowLimit` shortens the list.
2372
2411
  testId?: string;
2373
2412
  };
@@ -2375,6 +2414,11 @@ type RecordSummaryProps = { // One emphasized sentence below a record header; `t
2375
2414
  text: string;
2376
2415
  narrowText?: string; // Shown instead of `text` below the sm breakpoint.
2377
2416
  tone?: SelectOptionTone;
2417
+ icon?: NavIconKey; // Leads the sentence; the sentence then has no bordered box.
2418
+ testId?: string;
2419
+ };
2420
+ type StepListProps = { // Vertical numbered steps joined by a line; each step has a title, an optional status pill and a description line.
2421
+ items: { id: string; title: string; status?: string; statusTone?: SelectOptionTone; description?: string; }[];
2378
2422
  testId?: string;
2379
2423
  };
2380
2424
  ```
@@ -2415,15 +2459,6 @@ type ButtonBaseProps = {
2415
2459
  iconEnd?: NavIconKey; // Icon after the label (e.g. "Continue →").
2416
2460
  dataAttributes?: DataAttributes;
2417
2461
  };
2418
- type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar.
2419
- padded?: boolean; // Body-Padding (px-6 py-6).
2420
- radius?: "lg" | "xl"; // Eckenradius.
2421
- footerBordered?: boolean; // Separates the footer with `border-t` and `bg-muted/30`.
2422
- footerInset?: boolean; // Footer horizontal padding.
2423
- fillHeight?: boolean; // Joins the ancestor fillHeight flex chain — a tabs-mode relatedList table sizing to the panel instead of the page — instead of normal document-flow height.
2424
- framed?: boolean; // false drops border, background, shadow and radius but keeps padding and header slots — a panel inside a host surface such as a tab panel.
2425
- screenBody?: boolean; // The card is the whole screen body (secretMint reveal and done phase): no frame, the shared screen insets and width of form screens, children stacked with a gap.
2426
- };
2427
2462
  type CardSlots = { // Card slots are named content regions, all optional.
2428
2463
  header?: ReactNode;
2429
2464
  title?: ReactNode;
@@ -2718,6 +2753,12 @@ type DefaultAppShellUser = {
2718
2753
  };
2719
2754
  ```
2720
2755
 
2756
+ ## packages/renderer/src/web/layout/shell-style.tsx
2757
+
2758
+ ```ts
2759
+ type ShellNavStyle = "default" | "plain";
2760
+ ```
2761
+
2721
2762
  ## packages/renderer/src/web/layout/sidebar-panel.tsx
2722
2763
 
2723
2764
  ```ts
@@ -3145,6 +3186,7 @@ type ConfigMask = {
3145
3186
  description?: string; // i18n key for help text shown under the field label.
3146
3187
  icon?: NavIconKey;
3147
3188
  order?: number;
3189
+ readOnly?: boolean; // Shows the value on the generated settings screen without an input; a read-only key cannot also be `required`.
3148
3190
  };
3149
3191
  type ConfigSeedDef = {
3150
3192
  key: string;
@@ -3180,6 +3222,8 @@ type ExtensionSelectorDef = {
3180
3222
  panels?: ExtensionSelectorPanel[];
3181
3223
  };
3182
3224
  type ExtensionSelectorPanel = DashboardCustomPanel | Omit<DashboardScreenPanel, "label">;
3225
+ const IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES: ["rebuildable-derived-data", "high-risk-or-cron-pipeline", "per-dispatch-record-key"];
3226
+ type IrreversibleWithoutEntryHandler = (typeof IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES)[number];
3183
3227
  type JobBackoff =
3184
3228
  | JobBackoffStrategy
3185
3229
  | {
@@ -3898,7 +3942,7 @@ type MultiSelectFieldDef<TOptions extends string[] = string[]> = PiiAndFieldStat
3898
3942
  sensitive?: boolean;
3899
3943
  default?: TOptions[number][]; // Default selection.
3900
3944
  access?: FieldAccess;
3901
- display?: "checkboxes" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3945
+ display?: "checkboxes" | "chips" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3902
3946
  columns?: 1 | 2 | 3 | 4; // Renderer metadata: column count for the `"checkboxes"` grid at the widest breakpoint; narrow viewports always collapse to one column.
3903
3947
  maxRows?: number; // Renderer metadata: how many grid rows stay visible before the `"checkboxes"` grid becomes scrollable.
3904
3948
  optionsAvailabilityQuery?: string; // Query returning `{ rows: { value, disabled?, hint?
@@ -4116,7 +4160,6 @@ type ContextServices = { // Infrastructure the app wired at boot, as the handler
4116
4160
  _notifyFactory?: NotifyFactory;
4117
4161
  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4118
4162
  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4119
- _deliveryAttemptLogFactory?: DeliveryAttemptLogFactory;
4120
4163
  _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
4121
4164
  _escapeHatchAuditSink?: EscapeHatchAuditSink;
4122
4165
  extensions: Readonly<Record<string, unknown>>;
@@ -4256,6 +4299,7 @@ type JobRunnerRef = {
4256
4299
  handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
4257
4300
  handleCatchUpEvent?(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
4258
4301
  dispatch?(jobName: string, payload: Record<string, unknown>, meta?: { priority?: number; jobId?: string; }): Promise<unknown>;
4302
+ isJobPending?(jobName: string, jobId: string): Promise<boolean>;
4259
4303
  };
4260
4304
  type JobTriggerEvent = {
4261
4305
  id: string;
@@ -4533,7 +4577,7 @@ type Logger = {
4533
4577
  ```ts
4534
4578
  type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
4535
4579
  appendEvent: AppendEventFn<TMap>;
4536
- unsafeAppendEvent: UnsafeAppendEventFn;
4580
+ unsafeAppendEvent: (args: Parameters<UnsafeAppendEventFn>[0] & { expectedVersion?: number; }) => Promise<void>;
4537
4581
  loadAggregate: (aggregateId: string, options?: { asOf?: Temporal.Instant; }) => Promise<StoredEvent[]>;
4538
4582
  registry: Registry;
4539
4583
  files?: FileContext;
@@ -4552,6 +4596,8 @@ type ListSortDir = "asc" | "desc";
4552
4596
  type NamedFilterFacetOptions = { // How the named filters appear in the toolbar: toggle chips (default) or one single-choice select.
4553
4597
  display?: "chips" | "select";
4554
4598
  showCounts?: boolean; // Ask the list query for each filter's hit count and show it next to the label.
4599
+ hideEmpty?: boolean; // Select entries with zero hits are left out (the active one and "all" stay).
4600
+ narrowPlacement?: "behind-filter"; // "behind-filter": the select opens behind the filter icon next to the search field instead of standing as a pill.
4555
4601
  label?: string; // i18n key for the select's label, e.g. "To do".
4556
4602
  };
4557
4603
  type NamedListFilterCondition = {
@@ -4568,11 +4614,13 @@ type NamedListFilterRef = { // Screen-side reference to an entity-defined named
4568
4614
  id: string;
4569
4615
  label: string;
4570
4616
  sort?: ListSortSpec; // Order while this filter is active and the URL carries no sort of its own; wins over `defaultSort`.
4617
+ separatorAfter?: boolean; // Select display: draws a divider line below this entry in the dropdown.
4571
4618
  emptyState?: {
4572
4619
  title: string;
4573
4620
  description?: string;
4574
- }; // Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; both are i18n keys.
4575
- roles?: string[]; // Set by the framework from the entity filter's role rule; the chip is offered only to users holding one of them.
4621
+ paramsQuery?: string;
4622
+ }; // Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; `title` and `description` are i18n keys.
4623
+ access?: AccessRule; // Set by the framework from the entity filter's access rule; the client offers the chip only where `isUiAccessGranted` allows it.
4576
4624
  };
4577
4625
  type NamedListFilterScope = {
4578
4626
  ctx: HandlerContext;
@@ -4985,6 +5033,7 @@ type EditFieldPrefill =
4985
5033
  ;
4986
5034
  type EditFieldsSectionBase = {
4987
5035
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
5036
+ 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`.
4988
5037
  kind?: "fields";
4989
5038
  title?: string; // Optional.
4990
5039
  description?: string; // Optional help text under the block heading (i18n key or raw string, like `title`) — makes a form usable without training instead of falling back to custom JSX for help text.
@@ -5011,6 +5060,7 @@ type EntityListFacetExtraOption = { // An extra choice on a facet next to the fi
5011
5060
  label: string; // i18n key.
5012
5061
  values: string[]; // Option values this choice selects; `[]` selects nothing, i.e. no filter.
5013
5062
  position?: "start" | "end"; // Where the chip sits relative to the field's own options.
5063
+ separatorAfter?: boolean; // Draws a divider line below this choice in the select dropdown (e.g. after a "needs action" bundle).
5014
5064
  };
5015
5065
  type ListColumnDisplay = "bar" | "badge" | "datetime" | "button";
5016
5066
  type ListPaginationMode = "pages" | "infinite" | false;
@@ -5056,6 +5106,7 @@ const LIST_COLUMN_PINS: ["left", "right"];
5056
5106
  const LIST_NARROW_FACETS: ["pills"];
5057
5107
  const LIST_TABLE_DENSITIES: ["comfortable", "compact", "relaxed"];
5058
5108
  const LIST_TABLE_FRAMES: ["card"];
5109
+ const LIST_TOOLBAR_ACTIONS_PLACEMENTS: ["header", "toolbar"];
5059
5110
  type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
5060
5111
  type ListNarrowFacets = (typeof LIST_NARROW_FACETS)[number];
5061
5112
  type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
@@ -5090,6 +5141,7 @@ type MetricSpec = {
5090
5141
  tone?: DashboardStatTone; // Tile color as on dashboard stat panels; not applied while the value is 0.
5091
5142
  toneField?: string; // Record field of the detail query holding a SelectOptionTone; a valid value overrides `tone`, also at value 0.
5092
5143
  subField?: string; // Record field of the detail query shown as a small line under the value; the value stays the number.
5144
+ subFieldNarrow?: string; // Record field shown instead of `subField` below `sm` ("of 2,850 €" instead of "0 of 2,850.00 €").
5093
5145
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
5094
5146
  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
5095
5147
  };
package/agents/api.md CHANGED
@@ -10,11 +10,11 @@ Format: one line per function or constant, object and options types as property
10
10
  | --- | --- | --- |
11
11
  | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 446 |
12
12
  | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
- | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 178 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 189 |
14
14
  | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 157 |
15
15
  | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 41 |
16
16
  | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
17
- | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 372 |
17
+ | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 379 |
18
18
  | `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 23 |
19
19
  | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 72 |
20
20
  | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |
@@ -166,6 +166,8 @@
166
166
  | <a id="dashboard-filter-options-empty"></a>`dashboard/filter-options-empty` | Static filter options are non-empty. | Declare at least one option or use optionsQuery. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
167
167
  | <a id="dashboard-filter-options-query-empty"></a>`dashboard/filter-options-query-empty` | filter.optionsQuery is non-empty when set. | Set optionsQuery to a query name or remove it. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
168
168
  | <a id="dashboard-filter-options-xor"></a>`dashboard/filter-options-xor` | The dashboard filter sets exactly one of options and optionsQuery. | Keep either options or optionsQuery. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
169
+ | <a id="dashboard-layout-invalid"></a>`dashboard/layout-invalid` | A dashboard layout is "main-side"; a panel column is "side" or "top", used only with that layout and never on a stat-group child. | Set layout: "main-side" on the dashboard to use column: "side" or "top", or remove column. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
170
+ | <a id="dashboard-list-column-variant-invalid"></a>`dashboard/list-column-variant-invalid` | A list column variant is "primary" and needs display: "button". | Set display: "button" on the column or remove variant. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
169
171
  | <a id="dashboard-list-narrow-field-unknown"></a>`dashboard/list-narrow-field-unknown` | A list panel's narrow.field is set only with narrow.layout "line" and names a non-empty query output field; narrow.titleField needs the cards layout and a hint column. | Set narrow.layout "line" and name a field of the query output, or remove narrow.field. For narrow.titleField keep the cards layout and a hint column. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
170
172
  | <a id="dashboard-list-narrow-invalid"></a>`dashboard/list-narrow-invalid` | A list panel's narrow.limit is a positive integer, narrow.layout is "cards" or "line", and narrow.moreText and icon appear only with the "line" layout. | Set narrow.limit to a whole number of at least 1 and narrow.layout to "cards" or "line"; use narrow.moreText and icon only with "line". | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
171
173
  | <a id="dashboard-list-narrow-line-without-footer-link"></a>`dashboard/list-narrow-line-without-footer-link` | A list panel with narrow.layout "line" declares footerLink, the target of the line. | Add footerLink or use narrow.layout "cards". | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
@@ -188,7 +190,7 @@
188
190
  | <a id="dashboard-refresh-field-without-record-query"></a>`dashboard/refresh-field-without-record-query` | A field-driven refresh has a record.query to read the seconds from. | Add record: { param, query } or use refresh: { seconds }. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
189
191
  | <a id="dashboard-refresh-seconds-and-field"></a>`dashboard/refresh-seconds-and-field` | A dashboard refresh sets either seconds or field, not both. | Keep exactly one of seconds and field. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
190
192
  | <a id="dashboard-refresh-seconds-too-short"></a>`dashboard/refresh-seconds-too-short` | refresh.seconds is a number of at least DASHBOARD_MIN_REFRESH_SECONDS. | Raise refresh.seconds to the minimum or more. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
191
- | <a id="dashboard-stat-group-child-hide-on-narrow"></a>`dashboard/stat-group-child-hide-on-narrow` | Stat-group children do not set hideOnNarrow. | Set hideOnNarrow on the whole group instead. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
193
+ | <a id="dashboard-stat-group-child-hide-on-narrow"></a>`dashboard/stat-group-child-hide-on-narrow` | A stat-group keeps at least one child on a phone: not every child sets hideOnNarrow. | Set hideOnNarrow on the whole group instead, or keep one child visible. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
192
194
  | <a id="dashboard-stat-group-child-visible-when"></a>`dashboard/stat-group-child-visible-when` | Stat-group children do not set visibleWhen. | Gate the whole group with visibleWhen instead. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
193
195
  | <a id="dashboard-stat-group-columns-invalid"></a>`dashboard/stat-group-columns-invalid` | A stat-group's columns is 2, 3 or 4 and needs layout "cards". | Set columns to 2, 3 or 4 and give the group a label or layout: "cards", or remove columns. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
194
196
  | <a id="dashboard-stat-group-empty"></a>`dashboard/stat-group-empty` | A stat-group declares at least one stat. | Add at least one stat. | `packages/framework/src/engine/boot-validator/screens-dashboard-rules.ts` |
@@ -429,6 +431,13 @@
429
431
  | --- | --- | --- | --- |
430
432
  | <a id="file-storage-provider-env-missing"></a>`file-storage/provider-env-missing` | An app with file or image fields sets the FILE_STORAGE_PROVIDER environment variable. | Set FILE_STORAGE_PROVIDER in the environment. | `packages/framework/src/engine/boot-validator/boot-environment-rules.ts` |
431
433
 
434
+ ## files
435
+
436
+ | Rule | Summary | Fix | Source |
437
+ | --- | --- | --- | --- |
438
+ | <a id="files-cross-tenant-read-query-unregistered"></a>`files/cross-tenant-read-query-unregistered` | crossTenantFileRead.query names a registered query handler. | Use the qualified name of a query handler (<feature>:query:<name>) and register it. | `packages/framework/src/engine/boot-validator/entity-declaration-rules.ts` |
439
+ | <a id="files-cross-tenant-read-reason-missing"></a>`files/cross-tenant-read-reason-missing` | crossTenantFileRead declares a non-empty reason. | State why files of this entity are readable across tenants. | `packages/framework/src/engine/boot-validator/entity-declaration-rules.ts` |
440
+
432
441
  ## folders
433
442
 
434
443
  | Rule | Summary | Fix | Source |
@@ -440,6 +449,13 @@
440
449
  | Rule | Summary | Fix | Source |
441
450
  | --- | --- | --- | --- |
442
451
  | <a id="form-affix-unknown-field"></a>`form/affix-unknown-field` | A { field } prefix or suffix names another field of the same form. | Name a field of the same form. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
452
+ | <a id="form-ai-assist-chip-invalid"></a>`form/ai-assist-chip-invalid` | An aiAssist chip has a label and at least one param. | Set a non-empty label and params such as { style: "short" }. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
453
+ | <a id="form-ai-assist-context-field-unknown"></a>`form/ai-assist-context-field-unknown` | aiAssist.contextFields names fields of the same form. | Name other fields of the same form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
454
+ | <a id="form-ai-assist-empty"></a>`form/ai-assist-empty` | aiAssist declares at least one chip or a prompt. | Add chips or prompt, or remove aiAssist. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
455
+ | <a id="form-ai-assist-field-type"></a>`form/ai-assist-field-type` | aiAssist targets a text or longText field. | Remove aiAssist or use a text or longText field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
456
+ | <a id="form-ai-assist-prompt-param-empty"></a>`form/ai-assist-prompt-param-empty` | aiAssist.prompt names a non-empty param. | Set prompt.param to the query payload key that receives the typed instruction. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
457
+ | <a id="form-ai-assist-result-field-empty"></a>`form/ai-assist-result-field-empty` | aiAssist names a non-empty resultField. | Set resultField to the key of the query result that holds the text. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
458
+ | <a id="form-ai-assist-sensitive-field"></a>`form/ai-assist-sensitive-field` | aiAssist does not target a sensitive, writeOnly or password field. | Remove aiAssist; the field text would be sent to the AI. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
443
459
  | <a id="form-config-secret-also-config-key"></a>`form/config-secret-also-config-key` | A configEdit field is mapped in configKeys or secretKeys, not both. | Keep one of the mappings. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
444
460
  | <a id="form-config-secret-field-type"></a>`form/config-secret-field-type` | A secret-mapped configEdit field is a writeOnly text field. | Make the field a writeOnly text field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
445
461
  | <a id="form-config-secret-scope"></a>`form/config-secret-scope` | Secret-mapped configEdit fields are on a tenant- or system-scope screen. | Use scope "tenant" or "system", or drop the secret mapping. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -454,6 +470,9 @@
454
470
  | <a id="form-embedded-list-on-non-list-field"></a>`form/embedded-list-on-non-list-field` | embeddedList is set only on an embedded list field. | Remove embeddedList or point it at an embedded list field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
455
471
  | <a id="form-embedded-list-unknown-sub-field"></a>`form/embedded-list-unknown-sub-field` | embeddedList cell options name sub-fields of the embedded schema. | Name an existing sub-field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
456
472
  | <a id="form-extension-section-no-component"></a>`form/extension-section-no-component` | An extension section declares a react or native component. | Declare a react/native component marker. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
473
+ | <a id="form-field-badge-unknown-field"></a>`form/field-badge-unknown-field` | actionForm fieldBadges keys name fields of the form. | Name a field of the form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
474
+ | <a id="form-field-description-unknown-field"></a>`form/field-description-unknown-field` | actionForm fieldDescriptions keys name fields of the form. | Name a field of the form or remove the entry. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
475
+ | <a id="form-field-text-param-unknown-field"></a>`form/field-text-param-unknown-field` | actionForm fieldLabels and fieldDescriptions params name fields of the form. | Point each param at a field of the form or use the plain i18n key. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
457
476
  | <a id="form-field-type-missing"></a>`form/field-type-missing` | Every inline form field declares a type. | Declare a type such as "text", "number" or "select". | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
458
477
  | <a id="form-fields-empty"></a>`form/fields-empty` | An inline form declares at least one field. | Declare at least one field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
459
478
  | <a id="form-fill-action-field-type"></a>`form/fill-action-field-type` | fillAction targets a text, number, decimal or bigInt field. | Remove fillAction or use a fitting field type. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -481,6 +500,7 @@
481
500
  | <a id="form-select-options-and-query"></a>`form/select-options-and-query` | A select field declares static options or optionsQuery, not both. | Pick one of options and optionsQuery. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
482
501
  | <a id="form-select-options-query-empty"></a>`form/select-options-query-empty` | A select field's optionsQuery is non-empty when set. | Set it to a query name or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
483
502
  | <a id="form-select-query-and-availability"></a>`form/select-query-and-availability` | optionsAvailabilityQuery is not combined with optionsQuery. | Remove optionsAvailabilityQuery or use static options. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
503
+ | <a id="form-step-list-section-unsupported"></a>`form/step-list-section-unsupported` | Inline form layouts have no stepList sections. | Move the section to a projectionDetail screen or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
484
504
  | <a id="form-success-facts-with-redirect"></a>`form/success-facts-with-redirect` | An actionForm sets either redirect or successFacts. | Use one of them. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
485
505
  | <a id="form-success-links-with-redirect"></a>`form/success-links-with-redirect` | An actionForm sets either redirect or successLinks. | Use one of them. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
486
506
  | <a id="form-tab-id-duplicate"></a>`form/tab-id-duplicate` | Tab section ids are unique. | Give each tab section a unique id. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
@@ -489,6 +509,8 @@
489
509
  | <a id="form-tab-title-missing"></a>`form/tab-title-missing` | Every tab section has a non-empty title. | Give each tab section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
490
510
  | <a id="form-tabs-too-few-sections"></a>`form/tabs-too-few-sections` | A tabs layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
491
511
  | <a id="form-tabs-unsupported-screen-type"></a>`form/tabs-unsupported-screen-type` | Tabs layout is used only on projectionDetail and entityEdit screens. | Use mode: "wizard" or "single". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
512
+ | <a id="form-value-chips-field-type"></a>`form/value-chips-field-type` | valueChips targets a number, decimal, bigInt or money field. | Remove valueChips or use a numeric or money field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
513
+ | <a id="form-value-chips-unknown-field"></a>`form/value-chips-unknown-field` | valueChips.from names a field of the same form. | Name a field of the same form (hidden and submit: false is fine) that holds the numbers. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
492
514
  | <a id="form-wizard-option-without-wizard"></a>`form/wizard-option-without-wizard` | layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout. | Remove the option or set mode: "wizard". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
493
515
  | <a id="form-wizard-step-title-missing"></a>`form/wizard-step-title-missing` | Every wizard section has a non-empty title. | Give each wizard section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
494
516
  | <a id="form-wizard-submit-condition-field-unknown"></a>`form/wizard-submit-condition-field-unknown` | layout.wizard.submitDisabledWhen names a field of the layout. | Use a field name declared in one of the sections. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
@@ -650,7 +672,7 @@
650
672
  | --- | --- | --- | --- |
651
673
  | <a id="list-button-column-in-list-table"></a>`list/button-column-in-list-table` | display "button" is drawn only in dashboard list panels; entityList and projectionList tables (RenderList) keep a row button as a rowAction. | Declare the button as a rowAction with display: "button" or remove display: "button" from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
652
674
  | <a id="list-button-column-without-link"></a>`list/button-column-without-link` | A column with display "button" has a link (linkScreenField or refEntity) to draw as the button. | Set linkScreenField or refEntity on the column, or remove display: "button". | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
653
- | <a id="list-card-meta-overflow"></a>`list/card-meta-overflow` | A card list shows at most the maximum number of meta columns. | Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true. | `packages/framework/src/engine/boot-validator/card-meta-overflow-rules.ts` |
675
+ | <a id="list-card-meta-overflow"></a>`list/card-meta-overflow` | A card list shows at most the maximum number of meta lines. | Reduce each list to the maximum number of meta lines or mark the other columns hideOnNarrow: true. | `packages/framework/src/engine/boot-validator/card-meta-overflow-rules.ts` |
654
676
  | <a id="list-column-renderer-component-invalid"></a>`list/column-renderer-component-invalid` | A column renderer's react.__component is a non-empty string. | Set react.__component to the name of a client columnRenderers entry. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
655
677
  | <a id="list-column-renderer-react-not-object"></a>`list/column-renderer-react-not-object` | A column renderer's react branch is an object. | Use { react: { __component: "Name" } }. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
656
678
  | <a id="list-column-sortable-inert"></a>`list/column-sortable-inert` | A column only sets sortable where the screen type honors it. | Remove sortable from the column. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
@@ -663,9 +685,11 @@
663
685
  | <a id="list-guidance-field-empty"></a>`list/guidance-field-empty` | rowToneField, linkParamsField and the hint field names are non-empty strings. | Name a row field or remove the option. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
664
686
  | <a id="list-hint-column-display"></a>`list/hint-column-display` | A hint column owns its cell rendering and sets no display. | Remove display or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
665
687
  | <a id="list-hint-column-empty-placeholder"></a>`list/hint-column-empty-placeholder` | A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder. | Remove emptyPlaceholder, or name the empty sentence with hint.emptyLabel. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
666
- | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity or badgeToneField. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
688
+ | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField, badgeDot or pillField. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
667
689
  | <a id="list-hint-column-renderer"></a>`list/hint-column-renderer` | A hint column owns its cell rendering and sets no renderer. | Remove renderer or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
668
690
  | <a id="list-link-params-without-screen-field"></a>`list/link-params-without-screen-field` | linkParamsField only parametrizes the linkScreenField target. | Set linkScreenField on the column or remove linkParamsField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
691
+ | <a id="list-named-filter-empty-state-params-query-empty"></a>`list/named-filter-empty-state-params-query-empty` | A named filter's emptyState.paramsQuery is a non-empty query QN. | Name the query or remove paramsQuery from the emptyState. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
692
+ | <a id="list-named-filter-empty-state-params-query-without-description"></a>`list/named-filter-empty-state-params-query-without-description` | A named filter's emptyState.paramsQuery feeds the description, so it needs one. | Set emptyState.description (an i18n key with {params}) or remove paramsQuery. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
669
693
  | <a id="list-named-filter-empty-state-title-empty"></a>`list/named-filter-empty-state-title-empty` | A named filter's emptyState.title is a non-empty i18n key. | Name the title key or remove emptyState from the filter. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
670
694
  | <a id="list-named-filter-facet-without-filters"></a>`list/named-filter-facet-without-filters` | namedFilterFacet only presents the screen's namedFilters. | Declare namedFilters on the screen or remove namedFilterFacet. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
671
695
  | <a id="list-named-filter-sort-not-listed"></a>`list/named-filter-sort-not-listed` | A named filter's sort.field is one of the listed columns. | Pick a field from columns or add it there. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
@@ -673,21 +697,25 @@
673
697
  | <a id="list-narrow-detail-field-without-detail-field"></a>`list/narrow-detail-field-without-detail-field` | hint.narrowDetailField replaces hint.detailField below sm, so it needs detailField. | Set hint.detailField or remove narrowDetailField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
674
698
  | <a id="list-narrow-facets-invalid"></a>`list/narrow-facets-invalid` | narrowFacets is "pills". | Use "pills", or remove narrowFacets. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
675
699
  | <a id="list-narrow-only-conflict"></a>`list/narrow-only-conflict` | A showOnNarrowOnly column sets none of hideOnNarrow: true, hidden: true or pinned. | Remove the conflicting option or showOnNarrowOnly. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
700
+ | <a id="list-photo-grid-field-not-in-columns"></a>`list/photo-grid-field-not-in-columns` | photoGrid.imageField and photoGrid.captionField name a field of the section's columns, so the query output is checked. | Add the field to the section's columns or name another field. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
701
+ | <a id="list-pill-tone-without-pill"></a>`list/pill-tone-without-pill` | pillToneField colors the pillField pill, so it needs pillField. | Set pillField on the column or remove pillToneField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
702
+ | <a id="list-pill-with-display"></a>`list/pill-with-display` | pillField adds a pill beside the cell value and is not combined with display. | Remove display or pillField from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
676
703
  | <a id="list-reason-option-without-reason-field"></a>`list/reason-option-without-reason-field` | hint.reasonOpenField and hint.reasonTitleField shape the reason text, so they need reasonField. | Set hint.reasonField or remove reasonOpenField and reasonTitleField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
677
704
  | <a id="list-ref-target-entity-unknown"></a>`list/ref-target-entity-unknown` | An entity reference target resolves to a registered entity. | Name an entity the target feature registers. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
678
705
  | <a id="list-ref-target-feature-not-mounted"></a>`list/ref-target-feature-not-mounted` | An entity reference target belongs to a mounted feature. | Mount the feature and declare it in r.requires({ features }). | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
679
706
  | <a id="list-related-read-only-with-row-interaction"></a>`list/related-read-only-with-row-interaction` | A readOnly relatedList section declares no rowClick or rowActions. | Remove readOnly or the row interaction. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
680
707
  | <a id="list-related-row-click-no-detail"></a>`list/related-row-click-no-detail` | A relatedList rowClick entity target has a screen declaring detailFor for it. | Add detailFor to the screen that shows the entity. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
681
708
  | <a id="list-related-toolbar-visible-when"></a>`list/related-toolbar-visible-when` | relatedList toolbarActions use visible instead of visibleWhen. | Use visible, a condition on the enclosing record. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
682
- | <a id="list-row-decoration-ids-missing"></a>`list/row-decoration-ids-missing` | The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call. | Add `ids: z.array(z.string())` to the decoration query's schema. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
709
+ | <a id="list-relative-time-options-invalid"></a>`list/relative-time-options-invalid` | relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid. | Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
710
+ | <a id="list-row-decoration-ids-missing"></a>`list/row-decoration-ids-missing` | The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call. | Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
683
711
  | <a id="list-row-decoration-query-empty"></a>`list/row-decoration-query-empty` | rowDecoration.query is a non-empty query QN. | Name the decoration query or remove rowDecoration. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
684
712
  | <a id="list-screen-id-unresolved"></a>`list/screen-id-unresolved` | listScreenId names a mounted screen. | Fix the listScreenId or mount the list screen. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
685
713
  | <a id="list-screen-unreachable"></a>`list/screen-unreachable` | A screen without a nav entry has a resolvable list, or is marked dormant. | Declare listScreenId, add a standalone r.nav() pointing at it, or set dormant: true. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
686
- | <a id="list-sort-option-not-sortable"></a>`list/sort-option-not-sortable` | Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when sort is an enum, lists every option field. | Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
714
+ | <a id="list-sort-option-not-sortable"></a>`list/sort-option-not-sortable` | Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when they are enums, lists every option field and dir. | Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
687
715
  | <a id="list-sort-options-default-not-listed"></a>`list/sort-options-default-not-listed` | A defaultSort is one of the sortOptions, so the select opens on an entry. | Add the defaultSort field and dir to sortOptions or change defaultSort. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
688
716
  | <a id="list-sort-options-invalid"></a>`list/sort-options-invalid` | sortOptions is not empty and lists each field and dir once. | Remove sortOptions, or list each field and dir pair once. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
689
717
  | <a id="list-summary-row-on-related-list"></a>`list/summary-row-on-related-list` | A relatedList section or expandableRow sets no table.summaryRow; only entityList and projectionList screens have a list payload to carry it. | Remove summaryRow from the relatedList, or put the summary on the list screen itself. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
690
- | <a id="list-summary-row-query-accepts-list-keys"></a>`list/summary-row-query-accepts-list-keys` | The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters). | Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
718
+ | <a id="list-summary-row-query-accepts-list-keys"></a>`list/summary-row-query-accepts-list-keys` | The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters) and every summaryRow.params key. | Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
691
719
  | <a id="list-summary-row-query-unknown"></a>`list/summary-row-query-unknown` | table.summaryRow.query names a registered query handler. | Use the qualified name of a query handler (feature:query:name) or remove summaryRow. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
692
720
  | <a id="list-summary-row-shape"></a>`list/summary-row-shape` | table.summaryRow is an object with a query string and optional params object. | Write table.summaryRow as { query: "feature:query:order:summary" }. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
693
721
  | <a id="list-summary-row-with-totals"></a>`list/summary-row-with-totals` | A table sets summaryRow or totals, not both; two footers under one table read as two answers. | Drop totals and put the figures into the summary query, or drop summaryRow. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
@@ -936,6 +964,7 @@
936
964
  | <a id="projection-detail-guidance-action-show-on-tabs"></a>`projection-detail/guidance-action-show-on-tabs` | Banner and steps actions set no showOnTabs. | Remove showOnTabs. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
937
965
  | <a id="projection-detail-guidance-field-empty"></a>`projection-detail/guidance-field-empty` | The field names of breadcrumb, summary, banner, steps and progress are non-empty strings. | Name a query output field or remove the block. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
938
966
  | <a id="projection-detail-header-with-record-title-field"></a>`projection-detail/header-with-record-title-field` | A projectionDetail with a header sets no recordTitleField. | Drop recordTitleField; header.title names the record. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
967
+ | <a id="projection-detail-initial-tab-invalid"></a>`projection-detail/initial-tab-invalid` | initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions. | Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
939
968
  | <a id="projection-detail-metric-label-missing"></a>`projection-detail/metric-label-missing` | Every metric has an i18n label key. | Set label on the metric. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
940
969
  | <a id="projection-detail-metric-navigate-tab-unknown"></a>`projection-detail/metric-navigate-tab-unknown` | A metric navigate.tab names a section id of the screen. | Navigate to an existing section id or remove navigate.tab. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
941
970
  | <a id="projection-detail-progress-beside-steps-without-steps"></a>`projection-detail/progress-beside-steps-without-steps` | progress.placement "beside-steps" needs a steps block to sit next to. | Add steps to the projectionDetail or remove progress.placement. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
@@ -1073,6 +1102,7 @@
1073
1102
  | <a id="screen-fallback-unknown-reason"></a>`screen/fallback-unknown-reason` | Fallback map keys are known fallback reasons. | Use only the documented fallback reasons. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1074
1103
  | <a id="screen-fallback-without-visible-when"></a>`screen/fallback-without-visible-when` | A screen with a fallback also declares visibleWhen. | Add visibleWhen or remove fallback. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1075
1104
  | <a id="screen-filter-in-needs-array"></a>`screen/filter-in-needs-array` | A filter with op in has an array value. | Pass an array as filter.value. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1105
+ | <a id="screen-footer-action-conflict"></a>`screen/footer-action-conflict` | A footerActions id is neither the primaryAction nor in inlineActions. | Keep each action in one place: header (primaryAction), inline row or pinned footer. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1076
1106
  | <a id="screen-header-action-row-click"></a>`screen/header-action-row-click` | Record header actions do not set rowClick, because a record screen has no row. | Remove rowClick. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1077
1107
  | <a id="screen-id-duplicate"></a>`screen/id-duplicate` | Screen ids are unique per feature. | Rename one of the screens. | `packages/framework/src/engine/boot-validator/definition-ui-extensions-rules.ts` |
1078
1108
  | <a id="screen-id-not-kebab"></a>`screen/id-not-kebab` | Screen ids are kebab-case. | Rename the screen id to lowercase letters, digits and dashes. | `packages/framework/src/engine/boot-validator/definition-ui-extensions-rules.ts` |
@@ -1091,12 +1121,14 @@
1091
1121
  | <a id="screen-prefill-param-not-rendered"></a>`screen/prefill-param-not-rendered` | Prefill params only name fields the target form renders in its layout. | Add the field to the target layout or remove the param. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1092
1122
  | <a id="screen-prefill-param-sensitive-field"></a>`screen/prefill-param-sensitive-field` | Prefill params never name sensitive or password fields of the target form. | Remove the param or prefill a non-sensitive field. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1093
1123
  | <a id="screen-prefill-param-unknown-field"></a>`screen/prefill-param-unknown-field` | Prefill params only name fields the target form declares. | Name a field the target form declares, or remove the param. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1094
- | <a id="screen-primary-action-unknown"></a>`screen/primary-action-unknown` | primaryAction and inlineActions name a declared action id or the default edit. | Use a declared action id, or "edit" when the screen sets detailFor. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1124
+ | <a id="screen-primary-action-unknown"></a>`screen/primary-action-unknown` | primaryAction, inlineActions and footerActions name a declared action id or the default edit. | Use a declared action id, or "edit" when the screen sets detailFor. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1095
1125
  | <a id="screen-query-empty"></a>`screen/query-empty` | A screen or section query is a non-empty string. | Set query to a registered query name. | `packages/framework/src/engine/boot-validator/screens-kind-rules.ts` |
1096
1126
  | <a id="screen-redirect-id-from-empty"></a>`screen/redirect-id-from-empty` | A redirect object's idFrom is a non-empty string. | Name the success-payload field carrying the navigation id, or use the plain string redirect. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1097
1127
  | <a id="screen-redirect-id-from-on-idless-target"></a>`screen/redirect-id-from-on-idless-target` | A redirect idFrom only targets entityEdit or projectionDetail screens. | Use the plain string redirect form. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1098
1128
  | <a id="screen-redirect-id-from-whitespace"></a>`screen/redirect-id-from-whitespace` | A redirect idFrom has no leading or trailing whitespace. | Remove the whitespace from idFrom. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1099
1129
  | <a id="screen-redirect-on-list-row-action"></a>`screen/redirect-on-list-row-action` | List and related-list row actions do not set redirect. | Remove redirect; it is only honored on record actions. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1130
+ | <a id="screen-redirect-search-params-empty"></a>`screen/redirect-search-params-empty` | A redirect searchParams entry has a non-empty param name and payload field. | Map each search param name to a success-payload field. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1131
+ | <a id="screen-redirect-search-params-only-action-form"></a>`screen/redirect-search-params-only-action-form` | A redirect searchParams is only set on actionForm redirects. | Remove searchParams; other screen kinds do not read it. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1100
1132
  | <a id="screen-renderer-function"></a>`screen/renderer-function` | Field and column renderers are FormatSpecs, not functions. | Use a FormatSpec ({ format: "..." }). | `packages/framework/src/engine/boot-validator/screens-rules.ts` |
1101
1133
  | <a id="screen-row-click-at-most-one"></a>`screen/row-click-at-most-one` | At most one row-body click target (rowClick) is declared per list. | Mark at most one rowAction with rowClick: true. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
1102
1134
  | <a id="screen-short-id-collision"></a>`screen/short-id-collision` | A screen short id is registered by at most one feature. | Give each screen a distinct id. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |