@cosmicdrift/kumiko-framework 0.415.0 → 0.417.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 (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -1537,10 +1537,12 @@ type CardRoleColumn = {
1537
1537
  renderer?: unknown;
1538
1538
  hideOnNarrow?: boolean;
1539
1539
  narrowInline?: boolean;
1540
+ cardBadge?: boolean;
1540
1541
  fileDisplay?: {
1541
1542
  kind: string;
1542
1543
  };
1543
1544
  hint?: unknown; // A "to do" hint column: never the default card title.
1545
+ emphasis?: boolean; // Leads the card like a hint column; covers computed columns, which need a renderer and so cannot take `hint`.
1544
1546
  };
1545
1547
  ```
1546
1548
 
@@ -1660,6 +1662,7 @@ type ExtensionSectionProps = {
1660
1662
  isLast: boolean;
1661
1663
  }; // Current wizard step, only set for `layout.mode === "wizard"` forms.
1662
1664
  reportStepComplete?: (complete: boolean) => void; // Only set for extension steps of a `layout.mode: "wizard"` entityEdit editing an existing record (update mode); undefined everywhere else.
1665
+ 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.
1663
1666
  };
1664
1667
  ```
1665
1668
 
@@ -1693,6 +1696,7 @@ type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erwe
1693
1696
  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.
1694
1697
  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.
1695
1698
  headerLayout?: "stacked" | "inline"; // "inline": title and subtitle on one baseline row at 16px inset, compact padding (the board's side panel).
1699
+ titleStyle?: "heading" | "label"; // "label": the title is a small uppercase muted label.
1696
1700
  };
1697
1701
  ```
1698
1702
 
@@ -1734,6 +1738,8 @@ type RenderEditAction = {
1734
1738
  confirmLabel?: string;
1735
1739
  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
1736
1740
  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`).
1741
+ align?: "start"; // "start" sets the button apart on the left of the form footer.
1742
+ pinnedOnPhone?: true; // Stays a visible button in the pinned footer below `sm` instead of folding into the "…" menu.
1737
1743
  };
1738
1744
  ```
1739
1745
 
@@ -2217,7 +2223,7 @@ type EditFieldViewModel = {
2217
2223
  query: string;
2218
2224
  payload: OptionsQueryPayload;
2219
2225
  }; // Set for `type: "select"` / `"multiSelect"` when optionsAvailabilityQuery is set: the renderer loads `{ rows: { value, disabled?, hint?
2220
- 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.
2226
+ 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.
2221
2227
  optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // `type: "select"` only: tone per option, shown on the selected radio segment.
2222
2228
  columns?: 1 | 2 | 3 | 4; // Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is defined — column count for the checkbox grid at the widest breakpoint.
2223
2229
  maxRows?: number; // Set for `type: "multiSelect"` when MultiSelectFieldDef.maxRows is defined — grid rows visible before the checkbox grid becomes scrollable.
@@ -2251,6 +2257,12 @@ type EditFieldViewModel = {
2251
2257
  prefix?: FieldAffix; // From EditFieldSpec.prefix / suffix.
2252
2258
  suffix?: FieldAffix;
2253
2259
  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
2260
+ aiAssist?: FieldAiAssist; // From EditFieldSpec.aiAssist, chip labels and the prompt placeholder already translated.
2261
+ valueChips?: FieldValueChips; // From EditFieldSpec.valueChips.
2262
+ concealed?: true; // From EditFieldSpec.concealed.
2263
+ badge?: FieldBadge; // From EditFieldSpec.badge, a fixed `label` already translated.
2264
+ hintField?: string; // From EditFieldSpec.hintField.
2265
+ hideOnNarrow?: true; // From EditFieldSpec.hideOnNarrow.
2254
2266
  embeddedListCells?: EmbeddedListCellViewModel[]; // Only set for an embedded-LIST field (`multiple: true`) — the per-cell metadata the renderer needs to draw each column/cell.
2255
2267
  embeddedListMinItems?: number; // Minimum row count for the embedded list.
2256
2268
  embeddedListMaxItems?: number; // Maximum row count for the embedded list.
@@ -2327,6 +2339,7 @@ type ListColumnViewModel = {
2327
2339
  refLabelField?: string; // Only for `type: "reference"` — which field of the referenced entity appears as the display value in the cell (default "id").
2328
2340
  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.
2329
2341
  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
2342
+ hideWhenDocked?: true; // Mirrors `ListColumnSpec.hideWhenDocked`: a table in a narrow container skips the column.
2330
2343
  showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2331
2344
  narrowInline?: boolean; // Mirrors `ListColumnSpec.narrowInline`: the card draws consecutive such columns on one line.
2332
2345
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
@@ -2337,7 +2350,16 @@ type ListColumnViewModel = {
2337
2350
  display?: ListColumnCellDisplay; // `ListColumnSpec.display` for list tables: a status pill or a link drawn as a button.
2338
2351
  badgeToneField?: string; // Row field naming the pill tone; only with `display: "badge"`.
2339
2352
  badgeDot?: false; // `false`: the pill has no leading dot.
2340
- emptyPlaceholder?: false; // `false`: an empty cell stays blank instead of showing "—".
2353
+ pillField?: string; // Row field with the label of a pill drawn beside the cell value (`ListColumnSpec.pillField`).
2354
+ pillToneField?: string; // Row field naming the pill tone.
2355
+ emptyPlaceholder?: string | false; // An empty cell stays blank; a string is shown muted in its place.
2356
+ ellipsis?: true; // Mirrors `ListColumnSpec.ellipsis`: one line, cut with an ellipsis.
2357
+ multiline?: true; // Mirrors `ListColumnSpec.multiline`: `\n` in the value breaks the line.
2358
+ cardAbove?: true; // Mirrors `ListColumnSpec.cardAbove`.
2359
+ emphasis?: true; // Mirrors `ListColumnSpec.emphasis`: medium weight, foreground colour.
2360
+ tone?: "muted"; // Mirrors `ListColumnSpec.tone`.
2361
+ cardBadge?: true; // Mirrors `ListColumnSpec.cardBadge`.
2362
+ dateOnlyAfterDays?: number; // Mirrors `ListColumnSpec.dateOnlyAfterDays`.
2341
2363
  };
2342
2364
  type ListRowViewModel = {
2343
2365
  id: string;
@@ -2381,6 +2403,10 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2381
2403
  ## packages/renderer/src/primitives-record-guidance.ts
2382
2404
 
2383
2405
  ```ts
2406
+ type PhotoGridProps = { // Grid of image tiles; each tile shows a stored file and its own action buttons underneath.
2407
+ tiles: { id: string; imageId?: string; caption?: string; badge?: string; leadsOnNarrow?: true; actions?: ReactNode; }[];
2408
+ testId?: string;
2409
+ };
2384
2410
  type RecordBreadcrumbProps = { // Path above a record header; an item with a `link` is a link, the last item without one names the current record.
2385
2411
  items: { label: string; link?: CellLink; }[];
2386
2412
  ariaLabel: string;
@@ -2394,6 +2420,7 @@ type RecordStepsProps = { // "Next steps" panel; an item's `reason` sits behind
2394
2420
  narrowLimit?: number; // Below the sm breakpoint only this many steps show; the rest sits behind a toggle.
2395
2421
  moreLabel?: (hiddenCount: number) => string; // Toggle label for the hidden steps; receives their count.
2396
2422
  lessLabel?: string;
2423
+ moreActionsLabel?: string; // Label before the further actions of each item.
2397
2424
  items: { id: string; title: string; narrowTitle?: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2398
2425
  count?: number; // Total number of steps, shown small beside the heading even when `narrowLimit` shortens the list.
2399
2426
  testId?: string;
@@ -2402,6 +2429,71 @@ type RecordSummaryProps = { // One emphasized sentence below a record header; `t
2402
2429
  text: string;
2403
2430
  narrowText?: string; // Shown instead of `text` below the sm breakpoint.
2404
2431
  tone?: SelectOptionTone;
2432
+ icon?: NavIconKey; // Leads the sentence; the sentence then has no bordered box.
2433
+ testId?: string;
2434
+ };
2435
+ type StepListProps = { // Vertical numbered steps joined by a line; each step has a title, an optional status pill and a description line.
2436
+ items: { id: string; title: string; status?: string; statusTone?: SelectOptionTone; description?: string; }[];
2437
+ testId?: string;
2438
+ };
2439
+ ```
2440
+
2441
+ ## packages/renderer/src/primitives-share-types.ts
2442
+
2443
+ ```ts
2444
+ type CopyButtonProps = { // Copies `text` to the clipboard; the label flips to `copiedLabel` once the platform confirmed the write.
2445
+ text: string;
2446
+ label: string;
2447
+ copiedLabel: string;
2448
+ variant?: "primary" | "secondary";
2449
+ className?: string; // Layout extras, merged via cn().
2450
+ testId?: string;
2451
+ };
2452
+ type PromoPanelAction =
2453
+ | {
2454
+ label: string;
2455
+ href: string;
2456
+ testId?: string;
2457
+ }
2458
+ | {
2459
+ label: string;
2460
+ onClick: () => void;
2461
+ testId?: string;
2462
+ }
2463
+ ;
2464
+ type PromoPanelProps = { // Offer surface for upsells (e.g. "create an account"): its own tinted panel with eyebrow, headline, benefit content and one call to action, so an offer never reads like an info or error banner.
2465
+ title: string;
2466
+ eyebrow?: string;
2467
+ children?: ReactNode;
2468
+ action?: PromoPanelAction;
2469
+ testId?: string;
2470
+ };
2471
+ type SecretRevealProps = { // One-time secret reveal — mint-form confirm phase.
2472
+ values: SecretRevealValue[];
2473
+ copyLabel: string;
2474
+ copiedLabel: string;
2475
+ testId?: string;
2476
+ };
2477
+ type SecretRevealValue = { // One revealed value on a `secretMint` screen's confirm phase.
2478
+ label: string;
2479
+ value: string;
2480
+ copyable: boolean;
2481
+ multiline: boolean;
2482
+ qr?: boolean; // Render `value` as a scannable QR code instead of monospaced text — for an otpauth://-style enrollment URI.
2483
+ };
2484
+ type ShareButtonProps = ({ target: "whatsapp"; phone?: string; } | { target: "system"; title?: string; url?: string; }) & { // Hands `text` to another app.
2485
+ text: string;
2486
+ label: string;
2487
+ variant?: "primary" | "secondary";
2488
+ className?: string; // Layout extras, merged via cn().
2489
+ testId?: string;
2490
+ };
2491
+ type StickyActionBarProps = { // Thumb-reach action row for custom screens: pinned to the bottom edge on narrow viewports (above the device's safe-area inset), inline otherwise.
2492
+ children: ReactNode;
2493
+ back?: {
2494
+ onBack: () => void;
2495
+ label: string;
2496
+ };
2405
2497
  testId?: string;
2406
2498
  };
2407
2499
  ```
@@ -2457,19 +2549,12 @@ type ConfigCascadeViewProps = { // Cascade view for a config-edit field: one ori
2457
2549
  qualifiedKey?: string;
2458
2550
  required?: boolean; // The key declares `required: true` — a missing value reads "Not set.
2459
2551
  renderValue?: (value: string | number | boolean) => ReactNode; // Display form of a level value (e.g. a select's label instead of its raw value).
2552
+ compact?: boolean; // Origin shown as an info icon with a tooltip instead of text lines; the level disclosure is dropped.
2460
2553
  };
2461
2554
  type ConfigSourceBadgeProps = { // Source-badge for one cascade step (User / Tenant / System / …).
2462
2555
  source: ConfigValueSource;
2463
2556
  screenScope?: ConfigScope; // Scope of the hosting screen.
2464
2557
  };
2465
- type CopyButtonProps = { // Copies `text` to the clipboard; the label flips to `copiedLabel` once the platform confirmed the write.
2466
- text: string;
2467
- label: string;
2468
- copiedLabel: string;
2469
- variant?: "primary" | "secondary";
2470
- className?: string; // Layout extras, merged via cn().
2471
- testId?: string;
2472
- };
2473
2558
  type DataAttributes = Readonly<Record<`data-${string}`, string>>; // Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't warrant a dedicated typed prop.
2474
2559
  type DataTableRowAction = {
2475
2560
  id: string; // Stable ID for aria-labels and data-testids.
@@ -2577,6 +2662,7 @@ type ModalProps = { // Bare content shell for hosting an existing self-contained
2577
2662
  type PageHeaderProps = { // Page title area rendered by the app shell's header instead of inside the screen: `title` replaces the last breadcrumb, `status` sits right after it, `actions` at the right edge.
2578
2663
  title?: string;
2579
2664
  recordTitle?: string; // Name of the loaded record; shown as an extra breadcrumb before the last one.
2665
+ narrowRecordTitle?: string; // Short record title for the phone top bar; wins over `recordTitle` there.
2580
2666
  status?: ReactNode;
2581
2667
  actions?: ReactNode;
2582
2668
  bodyTitle?: boolean; // Screen renders its own h1: the shell header shows only the parent crumb, as text.
@@ -2598,45 +2684,6 @@ type ProgressProps = {
2598
2684
  testId?: string;
2599
2685
  };
2600
2686
  type ProgressTone = "default" | "success" | "warn" | "danger"; // Determinate progress bar (e.g. wizard step progress).
2601
- type PromoPanelAction =
2602
- | {
2603
- label: string;
2604
- href: string;
2605
- testId?: string;
2606
- }
2607
- | {
2608
- label: string;
2609
- onClick: () => void;
2610
- testId?: string;
2611
- }
2612
- ;
2613
- type PromoPanelProps = { // Offer surface for upsells (e.g. "create an account"): its own tinted panel with eyebrow, headline, benefit content and one call to action, so an offer never reads like an info or error banner.
2614
- title: string;
2615
- eyebrow?: string;
2616
- children?: ReactNode;
2617
- action?: PromoPanelAction;
2618
- testId?: string;
2619
- };
2620
- type SecretRevealProps = { // One-time secret reveal — mint-form confirm phase.
2621
- values: SecretRevealValue[];
2622
- copyLabel: string;
2623
- copiedLabel: string;
2624
- testId?: string;
2625
- };
2626
- type SecretRevealValue = { // One revealed value on a `secretMint` screen's confirm phase.
2627
- label: string;
2628
- value: string;
2629
- copyable: boolean;
2630
- multiline: boolean;
2631
- qr?: boolean; // Render `value` as a scannable QR code instead of monospaced text — for an otpauth://-style enrollment URI.
2632
- };
2633
- type ShareButtonProps = ({ target: "whatsapp"; phone?: string; } | { target: "system"; title?: string; url?: string; }) & { // Hands `text` to another app.
2634
- text: string;
2635
- label: string;
2636
- variant?: "primary" | "secondary";
2637
- className?: string; // Layout extras, merged via cn().
2638
- testId?: string;
2639
- };
2640
2687
  type StatusBadgeProps = { // Status pill.
2641
2688
  value: string;
2642
2689
  tone?: StatusBadgeOptionTone;
@@ -2662,14 +2709,6 @@ type StepBarProps = { // Wizard step overview — numbered chips, one per step l
2662
2709
  testId?: string;
2663
2710
  compactTestId?: string;
2664
2711
  };
2665
- type StickyActionBarProps = { // Thumb-reach action row for custom screens: pinned to the bottom edge on narrow viewports (above the device's safe-area inset), inline otherwise.
2666
- children: ReactNode;
2667
- back?: {
2668
- onBack: () => void;
2669
- label: string;
2670
- };
2671
- testId?: string;
2672
- };
2673
2712
  type TabsProps = { // Tab strip for a projectionDetail `layout.mode: "tabs"`.
2674
2713
  items: { id: string; label: string; count?: number; icon?: ReactNode; detail?: string; }[];
2675
2714
  activeId: string;
@@ -3169,6 +3208,9 @@ type ConfigMask = {
3169
3208
  description?: string; // i18n key for help text shown under the field label.
3170
3209
  icon?: NavIconKey;
3171
3210
  order?: number;
3211
+ readOnly?: boolean; // Shows the value on the generated settings screen without an input; a read-only key cannot also be `required`.
3212
+ compact?: true; // Draws the generated settings screen of this key compact (like `configEdit` `compact: true`: no origin icon or reset link, no accent bar, large section labels, no name-derived field icons).
3213
+ section?: string; // i18n key of a section title: keys sharing it form their own titled section on the generated settings screen, after the untitled-by-mask keys.
3172
3214
  };
3173
3215
  type ConfigSeedDef = {
3174
3216
  key: string;
@@ -3924,7 +3966,7 @@ type MultiSelectFieldDef<TOptions extends string[] = string[]> = PiiAndFieldStat
3924
3966
  sensitive?: boolean;
3925
3967
  default?: TOptions[number][]; // Default selection.
3926
3968
  access?: FieldAccess;
3927
- display?: "checkboxes" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3969
+ display?: "checkboxes" | "chips" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3928
3970
  columns?: 1 | 2 | 3 | 4; // Renderer metadata: column count for the `"checkboxes"` grid at the widest breakpoint; narrow viewports always collapse to one column.
3929
3971
  maxRows?: number; // Renderer metadata: how many grid rows stay visible before the `"checkboxes"` grid becomes scrollable.
3930
3972
  optionsAvailabilityQuery?: string; // Query returning `{ rows: { value, disabled?, hint?
@@ -5002,7 +5044,7 @@ type DashboardValueFormat = DashboardCurrencyFormat | DashboardRelativeTimeForma
5002
5044
  type EditFieldGroup = {
5003
5045
  title: string;
5004
5046
  fields: EditFieldSpec[];
5005
- columns?: number; // Default 2.
5047
+ columns?: number; // Edit mode renders 2 columns by default.
5006
5048
  };
5007
5049
  type EditFieldPrefill =
5008
5050
  | {
@@ -5013,11 +5055,13 @@ type EditFieldPrefill =
5013
5055
  property: "displayName" | "email" | "id";
5014
5056
  }
5015
5057
  ;
5016
- type EditFieldsSectionBase = {
5058
+ type EditFieldsSectionBase = EditSectionPresentation & {
5017
5059
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
5060
+ 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`.
5018
5061
  kind?: "fields";
5019
5062
  title?: string; // Optional.
5020
5063
  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.
5064
+ descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
5021
5065
  columns?: number;
5022
5066
  icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
5023
5067
  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
@@ -5026,6 +5070,13 @@ type EditFieldsSectionBase = {
5026
5070
  summaryField?: string; // Wizard layouts only: field of this section whose formatted value shows under the step label in the step rail once the step is done.
5027
5071
  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.
5028
5072
  };
5073
+ type EditSectionPresentation = { // Presentation options every section kind of a projectionDetail takes.
5074
+ tabLabel?: string; // i18n key of the tab name when the layout is in tabs mode; the section `title` stays the card heading.
5075
+ after?: PlatformComponent; // Component drawn directly under this section's card, in its column (also beside photos); same `{ react: { __component } }` form as `slots.afterForm`, receiving the same props.
5076
+ hideOnNarrow?: true; // Leaves the section out below `sm`.
5077
+ showOnNarrowOnly?: true; // Shows the section only below `sm` (e.g. a compact facts block for phones).
5078
+ titleOnNarrow?: false; // `false` leaves the section title out below `sm` (phone); the title stays from `sm` up.
5079
+ };
5029
5080
  type EntityEditActionPlacement = "inline" | "menu";
5030
5081
  type EntityWriteExcludedFields = {
5031
5082
  create?: string[];
@@ -5056,7 +5107,7 @@ type RowActionNavigateBase = {
5056
5107
  showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
5057
5108
  style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
5058
5109
  rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
5059
- icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
5110
+ icon?: IconKey | false; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
5060
5111
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
5061
5112
  };
5062
5113
  type ScreenFilter = {
@@ -5125,12 +5176,14 @@ type MetricSpec = {
5125
5176
  subFieldNarrow?: string; // Record field shown instead of `subField` below `sm` ("of 2,850 €" instead of "0 of 2,850.00 €").
5126
5177
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
5127
5178
  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
5179
+ visibleWhen?: Exclude<FieldCondition, boolean>; // Shows the metric only while the loaded record matches; same `{ field, eq | ne | in | notIn }` syntax as a section's `visibleWhen`.
5128
5180
  };
5129
5181
  type RecordHeaderSpec = {
5130
5182
  title: string;
5131
5183
  shortTitle?: string; // Field holding a short title for the desktop top bar ("Orders › SO-10482 ● processing"); the body keeps the full `title` as the h1.
5132
5184
  subtitle?: string | RecordHeaderSubtitlePart[]; // Field name, or several parts (field name or `{ field, navigate }`) joined by a separator; parts with an empty value are dropped.
5133
5185
  narrowSubtitle?: string; // Field holding a plain-text subtitle shown instead of `subtitle` below `sm` (e.g. "Main St 12, Berlin · 3 rooms").
5186
+ narrowTitle?: string; // i18n key of a short title for the phone top bar ("Approval") instead of the record title.
5134
5187
  status?: string;
5135
5188
  statusFormat?: FormatSpec; // Formats the badge text (typically `enumOption` with a `keyPrefix`); tones still resolve on the raw value.
5136
5189
  subtitleHref?: string; // Record field holding an absolute http(s) URL.
package/agents/api.md CHANGED
@@ -10,7 +10,7 @@ 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` | 180 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 190 |
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 |
@@ -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` |
@@ -663,7 +685,7 @@
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, badgeToneField or badgeDot. | 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` |
669
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` |
@@ -675,12 +697,16 @@
675
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` |
676
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` |
677
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` |
678
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` |
679
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` |
680
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` |
681
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` |
682
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` |
683
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` |
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` |
684
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` |
685
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` |
686
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` |
@@ -760,7 +786,7 @@
760
786
  | <a id="list-table-grouping-not-object"></a>`list-table/grouping-not-object` | table.grouping is an object. | Write table.grouping as { field: "status" }. | `packages/framework/src/engine/boot-validator/list-table-aggregate-rules.ts` |
761
787
  | <a id="list-table-grouping-value-invalid"></a>`list-table/grouping-value-invalid` | Each table.grouping option has the value type its schema expects. | Change the option to the type named in the message. | `packages/framework/src/engine/boot-validator/list-table-aggregate-rules.ts` |
762
788
  | <a id="list-table-hidden-not-boolean"></a>`list-table/hidden-not-boolean` | A column's hidden flag is a boolean. | Set hidden to true or remove it. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
763
- | <a id="list-table-hidden-without-column-picker"></a>`list-table/hidden-without-column-picker` | Hidden columns need table.columnPicker, otherwise the user can never show them. | Set table: { columnPicker: true } or remove hidden from the column. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
789
+ | <a id="list-table-hidden-without-column-picker"></a>`list-table/hidden-without-column-picker` | Hidden columns need table.columnPicker, otherwise the user can never show them; a hidden column that backs a facet is exempt. | Set table: { columnPicker: true } or remove hidden from the column. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
764
790
  | <a id="list-table-hides-every-column"></a>`list-table/hides-every-column` | At least one list column starts visible. | Remove hidden from one column. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
765
791
  | <a id="list-table-not-object"></a>`list-table/not-object` | A list's table option is an object. | Write table as an object such as { rememberState: true } using only the allowed keys. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
766
792
  | <a id="list-table-option-not-boolean"></a>`list-table/option-not-boolean` | The boolean table switches (rememberState, columnPicker, pinning, ...) are booleans. | Set the table option to true or false. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
@@ -938,14 +964,17 @@
938
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` |
939
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` |
940
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` |
941
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` |
942
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` |
970
+ | <a id="projection-detail-presentation-option-invalid"></a>`projection-detail/presentation-option-invalid` | tabLabel and layout.narrowTabs need layout.mode "tabs"; hideOnNarrow and showOnNarrowOnly exclude each other on a section; photoGrid.badgeFirst needs badgeField. | Use tabs mode for tabLabel/narrowTabs, set only one of hideOnNarrow/showOnNarrowOnly, and set badgeField next to badgeFirst. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
943
971
  | <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` |
944
972
  | <a id="projection-detail-singleton-with-detail-for"></a>`projection-detail/singleton-with-detail-for` | A singleton projectionDetail sets no detailFor. | Remove detailFor, or declare an explicit edit action. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
945
973
  | <a id="projection-detail-singleton-with-id-param"></a>`projection-detail/singleton-with-id-param` | A singleton projectionDetail sets no idParam. | Remove idParam. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
946
974
  | <a id="projection-detail-status-format-without-status"></a>`projection-detail/status-format-without-status` | header.statusFormat is only set together with header.status. | Set header.status or remove statusFormat. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
947
975
  | <a id="projection-detail-status-tone-invalid"></a>`projection-detail/status-tone-invalid` | header.statusTones values are known select option tones. | Use one of SELECT_OPTION_TONES. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
948
976
  | <a id="projection-detail-steps-narrow-limit-invalid"></a>`projection-detail/steps-narrow-limit-invalid` | steps.narrowLimit is a positive integer. | Set narrowLimit to a whole number of at least 1 or remove it. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
977
+ | <a id="projection-detail-submit-with-invalid"></a>`projection-detail/submit-with-invalid` | A writeForm submitWith names a writeHandler action of the screen, no other form uses the same action, and no form field shares a name with the action's payload keys. | Point submitWith at a writeHandler action id in screen.actions, give each form its own action, and rename the colliding field or payload key. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
949
978
  | <a id="projection-detail-subtitle-href-with-multi-part"></a>`projection-detail/subtitle-href-with-multi-part` | header.subtitleHref is only set with the string form of header.subtitle. | Use a single-field subtitle or remove subtitleHref. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
950
979
  | <a id="projection-detail-subtitle-part-duplicate"></a>`projection-detail/subtitle-part-duplicate` | Each field appears once in header.subtitle. | List each field once. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
951
980
  | <a id="projection-detail-subtitle-part-navigate-target-missing"></a>`projection-detail/subtitle-part-navigate-target-missing` | A header.subtitle part navigate names a screen or an entity. | Set screen or entity on the part's navigate. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
@@ -1075,6 +1104,7 @@
1075
1104
  | <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` |
1076
1105
  | <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` |
1077
1106
  | <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` |
1107
+ | <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` |
1078
1108
  | <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` |
1079
1109
  | <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` |
1080
1110
  | <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` |
@@ -1093,12 +1123,14 @@
1093
1123
  | <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` |
1094
1124
  | <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` |
1095
1125
  | <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` |
1096
- | <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` |
1126
+ | <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` |
1097
1127
  | <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` |
1098
1128
  | <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` |
1099
1129
  | <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` |
1100
1130
  | <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` |
1101
1131
  | <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` |
1132
+ | <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` |
1133
+ | <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` |
1102
1134
  | <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` |
1103
1135
  | <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` |
1104
1136
  | <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` |