@cosmicdrift/kumiko-framework 0.416.0 → 0.418.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/agents/api/framework-engine.md +32 -9
  2. package/agents/api/framework-ui-types.md +37 -10
  3. package/agents/api/renderer-web.md +25 -2
  4. package/agents/api/types.md +121 -64
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +23 -1
  7. package/agents/examples/crypto-shredding-hr.md +2 -2
  8. package/agents/examples/dashboard-stats.md +51 -0
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/list-table-options.md +346 -12
  11. package/agents/examples/managed-config.md +9 -1
  12. package/agents/examples/record-detail-layout.md +71 -6
  13. package/agents/examples/secrets-demo.md +3 -1
  14. package/agents/examples/signature.md +3 -2
  15. package/agents/examples/writeform-section.md +329 -0
  16. package/agents/features.md +1 -1
  17. package/dist/api/server-boot-checks.d.ts +1 -0
  18. package/dist/api/server-boot-checks.js +25 -0
  19. package/dist/api/server-rate-limit-wiring.js +2 -1
  20. package/dist/db/queries/event-store.d.ts +3 -0
  21. package/dist/db/queries/event-store.js +12 -0
  22. package/dist/engine/boot-validator/action-form-preview-rules.d.ts +22 -0
  23. package/dist/engine/boot-validator/action-form-preview-rules.js +22 -0
  24. package/dist/engine/boot-validator/action-form-preview.d.ts +2 -0
  25. package/dist/engine/boot-validator/action-form-preview.js +54 -0
  26. package/dist/engine/boot-validator/boot-rules.d.ts +87 -1
  27. package/dist/engine/boot-validator/boot-rules.js +2 -0
  28. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  29. package/dist/engine/boot-validator/config-key-rules.d.ts +5 -0
  30. package/dist/engine/boot-validator/config-key-rules.js +5 -0
  31. package/dist/engine/boot-validator/date-only-after-days.d.ts +4 -0
  32. package/dist/engine/boot-validator/date-only-after-days.js +32 -0
  33. package/dist/engine/boot-validator/entity-handler.d.ts +1 -0
  34. package/dist/engine/boot-validator/entity-handler.js +1 -1
  35. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +40 -0
  36. package/dist/engine/boot-validator/list-bulk-actions-rules.js +40 -0
  37. package/dist/engine/boot-validator/list-bulk-actions.d.ts +2 -1
  38. package/dist/engine/boot-validator/list-bulk-actions.js +79 -9
  39. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  40. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  41. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  42. package/dist/engine/boot-validator/list-table-options.js +8 -6
  43. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  44. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  45. package/dist/engine/boot-validator/query-output-columns.js +29 -2
  46. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  47. package/dist/engine/boot-validator/query-refs.js +3 -0
  48. package/dist/engine/boot-validator/screens-actions.d.ts +7 -2
  49. package/dist/engine/boot-validator/screens-actions.js +4 -2
  50. package/dist/engine/boot-validator/screens-forms.js +2 -0
  51. package/dist/engine/boot-validator/screens-kind-entity-list.js +5 -3
  52. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  53. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  54. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  55. package/dist/engine/boot-validator/screens-kind-projection-list.js +2 -2
  56. package/dist/engine/boot-validator/screens-kind-shared.d.ts +1 -1
  57. package/dist/engine/boot-validator/screens-kind-shared.js +3 -1
  58. package/dist/engine/boot-validator/screens-lists-rules.d.ts +10 -0
  59. package/dist/engine/boot-validator/screens-lists-rules.js +10 -0
  60. package/dist/engine/boot-validator/screens-lists.js +13 -1
  61. package/dist/engine/boot-validator/screens.js +1 -2
  62. package/dist/engine/boot-validator/url-prefill-fields.js +8 -1
  63. package/dist/engine/boot-validator/zod-shape.d.ts +1 -0
  64. package/dist/engine/boot-validator/zod-shape.js +7 -0
  65. package/dist/engine/bridge-stub.js +1 -0
  66. package/dist/engine/build-config-feature-schema.js +30 -3
  67. package/dist/engine/screen-helpers.js +7 -3
  68. package/dist/engine/types/screen.d.ts +1 -1
  69. package/dist/engine/types/screen.js +1 -1
  70. package/dist/event-store/archive.d.ts +1 -0
  71. package/dist/event-store/archive.js +5 -1
  72. package/dist/event-store/event-store.d.ts +5 -0
  73. package/dist/event-store/event-store.js +23 -3
  74. package/dist/i18n/required-surface-keys.js +53 -13
  75. package/dist/pipeline/handler-context-events.js +15 -1
  76. package/dist/ui-types/card-column-roles.d.ts +3 -0
  77. package/dist/ui-types/card-column-roles.js +9 -5
  78. package/dist/ui-types/index.d.ts +1 -1
  79. package/package.json +3 -3
  80. package/src/changes.json +36 -0
@@ -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
 
@@ -1694,6 +1696,7 @@ type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erwe
1694
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.
1695
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.
1696
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.
1697
1700
  };
1698
1701
  ```
1699
1702
 
@@ -1822,13 +1825,19 @@ type DataTableBulk = {
1822
1825
  actions: DataTableBulkAction[];
1823
1826
  reload: () => Promise<void>; // Reloads the list once after a run.
1824
1827
  };
1825
- type DataTableBulkAction = {
1828
+ type DataTableBulkAction = DataTableBulkWriteAction | DataTableBulkFormAction;
1829
+ type DataTableBulkActionBase = {
1826
1830
  id: string;
1827
- label: string; // Translated label of the underlying row action.
1831
+ label: string; // Translated label of the underlying row action or form action.
1828
1832
  style?: "primary" | "secondary" | "danger";
1829
1833
  icon?: IconKey;
1830
1834
  confirmText?: (count: number) => string; // Present: one confirm dialog for the whole selection, with this text for `count` rows.
1831
1835
  confirmLabel?: string;
1836
+ };
1837
+ type DataTableBulkFormAction = DataTableBulkActionBase & {
1838
+ openForm: (rows: ListRowViewModel[]) => void; // Hands the whole selection to one form instead of running writes in the table.
1839
+ };
1840
+ type DataTableBulkWriteAction = DataTableBulkActionBase & {
1832
1841
  appliesTo: (row: ListRowViewModel) => boolean; // False: the row action's `visible` hides it for this row; the run skips the row.
1833
1842
  writeRow: (row: ListRowViewModel) => Promise<BulkRowOutcome>; // Exactly one server write for one row.
1834
1843
  };
@@ -2220,7 +2229,7 @@ type EditFieldViewModel = {
2220
2229
  query: string;
2221
2230
  payload: OptionsQueryPayload;
2222
2231
  }; // Set for `type: "select"` / `"multiSelect"` when optionsAvailabilityQuery is set: the renderer loads `{ rows: { value, disabled?, hint?
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.
2232
+ display?: "checkboxes" | "chips" | "dropdown" | "radio" | "count"; // 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.
2224
2233
  optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // `type: "select"` only: tone per option, shown on the selected radio segment.
2225
2234
  columns?: 1 | 2 | 3 | 4; // Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is defined — column count for the checkbox grid at the widest breakpoint.
2226
2235
  maxRows?: number; // Set for `type: "multiSelect"` when MultiSelectFieldDef.maxRows is defined — grid rows visible before the checkbox grid becomes scrollable.
@@ -2256,6 +2265,10 @@ type EditFieldViewModel = {
2256
2265
  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
2257
2266
  aiAssist?: FieldAiAssist; // From EditFieldSpec.aiAssist, chip labels and the prompt placeholder already translated.
2258
2267
  valueChips?: FieldValueChips; // From EditFieldSpec.valueChips.
2268
+ concealed?: true; // From EditFieldSpec.concealed.
2269
+ badge?: FieldBadge; // From EditFieldSpec.badge, a fixed `label` already translated.
2270
+ hintField?: string; // From EditFieldSpec.hintField.
2271
+ hideOnNarrow?: true; // From EditFieldSpec.hideOnNarrow.
2259
2272
  embeddedListCells?: EmbeddedListCellViewModel[]; // Only set for an embedded-LIST field (`multiple: true`) — the per-cell metadata the renderer needs to draw each column/cell.
2260
2273
  embeddedListMinItems?: number; // Minimum row count for the embedded list.
2261
2274
  embeddedListMaxItems?: number; // Maximum row count for the embedded list.
@@ -2332,6 +2345,7 @@ type ListColumnViewModel = {
2332
2345
  refLabelField?: string; // Only for `type: "reference"` — which field of the referenced entity appears as the display value in the cell (default "id").
2333
2346
  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.
2334
2347
  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
2348
+ hideWhenDocked?: true; // Mirrors `ListColumnSpec.hideWhenDocked`: a table in a narrow container skips the column.
2335
2349
  showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2336
2350
  narrowInline?: boolean; // Mirrors `ListColumnSpec.narrowInline`: the card draws consecutive such columns on one line.
2337
2351
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
@@ -2344,7 +2358,14 @@ type ListColumnViewModel = {
2344
2358
  badgeDot?: false; // `false`: the pill has no leading dot.
2345
2359
  pillField?: string; // Row field with the label of a pill drawn beside the cell value (`ListColumnSpec.pillField`).
2346
2360
  pillToneField?: string; // Row field naming the pill tone.
2347
- emptyPlaceholder?: false; // `false`: an empty cell stays blank instead of showing "—".
2361
+ emptyPlaceholder?: string | false; // An empty cell stays blank; a string is shown muted in its place.
2362
+ ellipsis?: true; // Mirrors `ListColumnSpec.ellipsis`: one line, cut with an ellipsis.
2363
+ multiline?: true; // Mirrors `ListColumnSpec.multiline`: `\n` in the value breaks the line.
2364
+ cardAbove?: true; // Mirrors `ListColumnSpec.cardAbove`.
2365
+ emphasis?: true; // Mirrors `ListColumnSpec.emphasis`: medium weight, foreground colour.
2366
+ tone?: "muted"; // Mirrors `ListColumnSpec.tone`.
2367
+ cardBadge?: true; // Mirrors `ListColumnSpec.cardBadge`.
2368
+ dateOnlyAfterDays?: number; // Mirrors `ListColumnSpec.dateOnlyAfterDays`.
2348
2369
  };
2349
2370
  type ListRowViewModel = {
2350
2371
  id: string;
@@ -2389,7 +2410,7 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2389
2410
 
2390
2411
  ```ts
2391
2412
  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; }[];
2413
+ tiles: { id: string; imageId?: string; caption?: string; badge?: string; leadsOnNarrow?: true; actions?: ReactNode; }[];
2393
2414
  testId?: string;
2394
2415
  };
2395
2416
  type RecordBreadcrumbProps = { // Path above a record header; an item with a `link` is a link, the last item without one names the current record.
@@ -2423,6 +2444,66 @@ type StepListProps = { // Vertical numbered steps joined by a line; each step ha
2423
2444
  };
2424
2445
  ```
2425
2446
 
2447
+ ## packages/renderer/src/primitives-share-types.ts
2448
+
2449
+ ```ts
2450
+ type CopyButtonProps = { // Copies `text` to the clipboard; the label flips to `copiedLabel` once the platform confirmed the write.
2451
+ text: string;
2452
+ label: string;
2453
+ copiedLabel: string;
2454
+ variant?: "primary" | "secondary";
2455
+ className?: string; // Layout extras, merged via cn().
2456
+ testId?: string;
2457
+ };
2458
+ type PromoPanelAction =
2459
+ | {
2460
+ label: string;
2461
+ href: string;
2462
+ testId?: string;
2463
+ }
2464
+ | {
2465
+ label: string;
2466
+ onClick: () => void;
2467
+ testId?: string;
2468
+ }
2469
+ ;
2470
+ 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.
2471
+ title: string;
2472
+ eyebrow?: string;
2473
+ children?: ReactNode;
2474
+ action?: PromoPanelAction;
2475
+ testId?: string;
2476
+ };
2477
+ type SecretRevealProps = { // One-time secret reveal — mint-form confirm phase.
2478
+ values: SecretRevealValue[];
2479
+ copyLabel: string;
2480
+ copiedLabel: string;
2481
+ testId?: string;
2482
+ };
2483
+ type SecretRevealValue = { // One revealed value on a `secretMint` screen's confirm phase.
2484
+ label: string;
2485
+ value: string;
2486
+ copyable: boolean;
2487
+ multiline: boolean;
2488
+ qr?: boolean; // Render `value` as a scannable QR code instead of monospaced text — for an otpauth://-style enrollment URI.
2489
+ };
2490
+ type ShareButtonProps = ({ target: "whatsapp"; phone?: string; } | { target: "system"; title?: string; url?: string; }) & { // Hands `text` to another app.
2491
+ text: string;
2492
+ label: string;
2493
+ variant?: "primary" | "secondary";
2494
+ className?: string; // Layout extras, merged via cn().
2495
+ testId?: string;
2496
+ };
2497
+ 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.
2498
+ children: ReactNode;
2499
+ back?: {
2500
+ onBack: () => void;
2501
+ label: string;
2502
+ };
2503
+ testId?: string;
2504
+ };
2505
+ ```
2506
+
2426
2507
  ## packages/renderer/src/primitives.tsx
2427
2508
 
2428
2509
  ```ts
@@ -2474,19 +2555,12 @@ type ConfigCascadeViewProps = { // Cascade view for a config-edit field: one ori
2474
2555
  qualifiedKey?: string;
2475
2556
  required?: boolean; // The key declares `required: true` — a missing value reads "Not set.
2476
2557
  renderValue?: (value: string | number | boolean) => ReactNode; // Display form of a level value (e.g. a select's label instead of its raw value).
2558
+ compact?: boolean; // Origin shown as an info icon with a tooltip instead of text lines; the level disclosure is dropped.
2477
2559
  };
2478
2560
  type ConfigSourceBadgeProps = { // Source-badge for one cascade step (User / Tenant / System / …).
2479
2561
  source: ConfigValueSource;
2480
2562
  screenScope?: ConfigScope; // Scope of the hosting screen.
2481
2563
  };
2482
- type CopyButtonProps = { // Copies `text` to the clipboard; the label flips to `copiedLabel` once the platform confirmed the write.
2483
- text: string;
2484
- label: string;
2485
- copiedLabel: string;
2486
- variant?: "primary" | "secondary";
2487
- className?: string; // Layout extras, merged via cn().
2488
- testId?: string;
2489
- };
2490
2564
  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.
2491
2565
  type DataTableRowAction = {
2492
2566
  id: string; // Stable ID for aria-labels and data-testids.
@@ -2594,6 +2668,7 @@ type ModalProps = { // Bare content shell for hosting an existing self-contained
2594
2668
  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.
2595
2669
  title?: string;
2596
2670
  recordTitle?: string; // Name of the loaded record; shown as an extra breadcrumb before the last one.
2671
+ narrowRecordTitle?: string; // Short record title for the phone top bar; wins over `recordTitle` there.
2597
2672
  status?: ReactNode;
2598
2673
  actions?: ReactNode;
2599
2674
  bodyTitle?: boolean; // Screen renders its own h1: the shell header shows only the parent crumb, as text.
@@ -2615,45 +2690,6 @@ type ProgressProps = {
2615
2690
  testId?: string;
2616
2691
  };
2617
2692
  type ProgressTone = "default" | "success" | "warn" | "danger"; // Determinate progress bar (e.g. wizard step progress).
2618
- type PromoPanelAction =
2619
- | {
2620
- label: string;
2621
- href: string;
2622
- testId?: string;
2623
- }
2624
- | {
2625
- label: string;
2626
- onClick: () => void;
2627
- testId?: string;
2628
- }
2629
- ;
2630
- 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.
2631
- title: string;
2632
- eyebrow?: string;
2633
- children?: ReactNode;
2634
- action?: PromoPanelAction;
2635
- testId?: string;
2636
- };
2637
- type SecretRevealProps = { // One-time secret reveal — mint-form confirm phase.
2638
- values: SecretRevealValue[];
2639
- copyLabel: string;
2640
- copiedLabel: string;
2641
- testId?: string;
2642
- };
2643
- type SecretRevealValue = { // One revealed value on a `secretMint` screen's confirm phase.
2644
- label: string;
2645
- value: string;
2646
- copyable: boolean;
2647
- multiline: boolean;
2648
- qr?: boolean; // Render `value` as a scannable QR code instead of monospaced text — for an otpauth://-style enrollment URI.
2649
- };
2650
- type ShareButtonProps = ({ target: "whatsapp"; phone?: string; } | { target: "system"; title?: string; url?: string; }) & { // Hands `text` to another app.
2651
- text: string;
2652
- label: string;
2653
- variant?: "primary" | "secondary";
2654
- className?: string; // Layout extras, merged via cn().
2655
- testId?: string;
2656
- };
2657
2693
  type StatusBadgeProps = { // Status pill.
2658
2694
  value: string;
2659
2695
  tone?: StatusBadgeOptionTone;
@@ -2679,14 +2715,6 @@ type StepBarProps = { // Wizard step overview — numbered chips, one per step l
2679
2715
  testId?: string;
2680
2716
  compactTestId?: string;
2681
2717
  };
2682
- 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.
2683
- children: ReactNode;
2684
- back?: {
2685
- onBack: () => void;
2686
- label: string;
2687
- };
2688
- testId?: string;
2689
- };
2690
2718
  type TabsProps = { // Tab strip for a projectionDetail `layout.mode: "tabs"`.
2691
2719
  items: { id: string; label: string; count?: number; icon?: ReactNode; detail?: string; }[];
2692
2720
  activeId: string;
@@ -3187,6 +3215,8 @@ type ConfigMask = {
3187
3215
  icon?: NavIconKey;
3188
3216
  order?: number;
3189
3217
  readOnly?: boolean; // Shows the value on the generated settings screen without an input; a read-only key cannot also be `required`.
3218
+ 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).
3219
+ 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.
3190
3220
  };
3191
3221
  type ConfigSeedDef = {
3192
3222
  key: string;
@@ -3942,7 +3972,7 @@ type MultiSelectFieldDef<TOptions extends string[] = string[]> = PiiAndFieldStat
3942
3972
  sensitive?: boolean;
3943
3973
  default?: TOptions[number][]; // Default selection.
3944
3974
  access?: FieldAccess;
3945
- display?: "checkboxes" | "chips" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3975
+ display?: "checkboxes" | "chips" | "dropdown" | "count"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
3946
3976
  columns?: 1 | 2 | 3 | 4; // Renderer metadata: column count for the `"checkboxes"` grid at the widest breakpoint; narrow viewports always collapse to one column.
3947
3977
  maxRows?: number; // Renderer metadata: how many grid rows stay visible before the `"checkboxes"` grid becomes scrollable.
3948
3978
  optionsAvailabilityQuery?: string; // Query returning `{ rows: { value, disabled?, hint?
@@ -5020,7 +5050,7 @@ type DashboardValueFormat = DashboardCurrencyFormat | DashboardRelativeTimeForma
5020
5050
  type EditFieldGroup = {
5021
5051
  title: string;
5022
5052
  fields: EditFieldSpec[];
5023
- columns?: number; // Default 2.
5053
+ columns?: number; // Edit mode renders 2 columns by default.
5024
5054
  };
5025
5055
  type EditFieldPrefill =
5026
5056
  | {
@@ -5031,12 +5061,13 @@ type EditFieldPrefill =
5031
5061
  property: "displayName" | "email" | "id";
5032
5062
  }
5033
5063
  ;
5034
- type EditFieldsSectionBase = {
5064
+ type EditFieldsSectionBase = EditSectionPresentation & {
5035
5065
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
5036
5066
  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`.
5037
5067
  kind?: "fields";
5038
5068
  title?: string; // Optional.
5039
5069
  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.
5070
+ descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
5040
5071
  columns?: number;
5041
5072
  icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
5042
5073
  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).
@@ -5045,6 +5076,13 @@ type EditFieldsSectionBase = {
5045
5076
  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.
5046
5077
  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.
5047
5078
  };
5079
+ type EditSectionPresentation = { // Presentation options every section kind of a projectionDetail takes.
5080
+ tabLabel?: string; // i18n key of the tab name when the layout is in tabs mode; the section `title` stays the card heading.
5081
+ 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.
5082
+ hideOnNarrow?: true; // Leaves the section out below `sm`.
5083
+ showOnNarrowOnly?: true; // Shows the section only below `sm` (e.g. a compact facts block for phones).
5084
+ titleOnNarrow?: false; // `false` leaves the section title out below `sm` (phone); the title stays from `sm` up.
5085
+ };
5048
5086
  type EntityEditActionPlacement = "inline" | "menu";
5049
5087
  type EntityWriteExcludedFields = {
5050
5088
  create?: string[];
@@ -5075,7 +5113,7 @@ type RowActionNavigateBase = {
5075
5113
  showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
5076
5114
  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.
5077
5115
  rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
5078
- 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.
5116
+ 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.
5079
5117
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
5080
5118
  };
5081
5119
  type ScreenFilter = {
@@ -5099,6 +5137,23 @@ type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoice" | "f
5099
5137
  };
5100
5138
  ```
5101
5139
 
5140
+ ## packages/types/src/screen-list-bulk.ts
5141
+
5142
+ ```ts
5143
+ type ListBulkFormAction = { // Opens an `actionForm` screen for the whole selection.
5144
+ id: string; // Stable id, kebab-case, unique among the screen's bulk actions.
5145
+ label: string; // i18n key of the button label.
5146
+ icon?: IconKey;
5147
+ screen: string; // Short id (same feature) or `<feature>:screen:<id>` of an `actionForm` screen.
5148
+ idsField: string; // Field of that form which receives the selected row ids: a `multiSelect` with `display: "count"`.
5149
+ };
5150
+ type ListBulkRowAction = { // Runs a writeHandler row action once per checkbox-selected row.
5151
+ id: string; // Stable id, kebab-case, unique among the screen's bulk actions.
5152
+ rowAction: string; // Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`.
5153
+ confirm?: string; // i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`.
5154
+ };
5155
+ ```
5156
+
5102
5157
  ## packages/types/src/screen-list-table.ts
5103
5158
 
5104
5159
  ```ts
@@ -5144,12 +5199,14 @@ type MetricSpec = {
5144
5199
  subFieldNarrow?: string; // Record field shown instead of `subField` below `sm` ("of 2,850 €" instead of "0 of 2,850.00 €").
5145
5200
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
5146
5201
  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
5202
+ 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`.
5147
5203
  };
5148
5204
  type RecordHeaderSpec = {
5149
5205
  title: string;
5150
5206
  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.
5151
5207
  subtitle?: string | RecordHeaderSubtitlePart[]; // Field name, or several parts (field name or `{ field, navigate }`) joined by a separator; parts with an empty value are dropped.
5152
5208
  narrowSubtitle?: string; // Field holding a plain-text subtitle shown instead of `subtitle` below `sm` (e.g. "Main St 12, Berlin · 3 rooms").
5209
+ narrowTitle?: string; // i18n key of a short title for the phone top bar ("Approval") instead of the record title.
5153
5210
  status?: string;
5154
5211
  statusFormat?: FormatSpec; // Formats the badge text (typically `enumOption` with a `keyPrefix`); tones still resolve on the raw value.
5155
5212
  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` | 189 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 193 |
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 |
@@ -4,6 +4,15 @@
4
4
 
5
5
  `validateBoot` reports every violation as `- [<id>] <message>`, followed by a `Fix:` and a `Rule:` line that links the entry below. Violations with an `unclassified/<check>` id have no entry yet. `kumiko-schema validate --json` returns the same ids.
6
6
 
7
+ ## action-form-preview
8
+
9
+ | Rule | Summary | Fix | Source |
10
+ | --- | --- | --- | --- |
11
+ | <a id="action-form-preview-empty"></a>`action-form-preview/empty` | A preview shows facts or a list. | Add facts or list, or remove preview. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
12
+ | <a id="action-form-preview-field-unknown"></a>`action-form-preview/field-unknown` | preview.fields names fields of the form. | Name an existing field of the form, or drop fields to send all of them. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
13
+ | <a id="action-form-preview-label-missing"></a>`action-form-preview/label-missing` | Every preview fact and list column has a label. | Add label: the i18n key of the fact or column header. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
14
+ | <a id="action-form-preview-list-field-missing"></a>`action-form-preview/list-field-missing` | preview.list names the result field of its rows and at least one column. | Set list.field to the array in the query result and list the columns to show. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
15
+
7
16
  ## agent-effect
8
17
 
9
18
  | Rule | Summary | Fix | Source |
@@ -112,6 +121,7 @@
112
121
  | <a id="config-key-conditional-options"></a>`config-key/conditional-options` | A config key does not declare conditionalOptions, which only entity select fields support. | Remove conditionalOptions from the config key. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
113
122
  | <a id="config-key-default-above-max"></a>`config-key/default-above-max` | A config key's default is not above its bounds.max. | Lower the default or raise bounds.max. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
114
123
  | <a id="config-key-default-below-min"></a>`config-key/default-below-min` | A config key's default is not below its bounds.min. | Raise the default or lower bounds.min. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
124
+ | <a id="config-key-mask-read-only-required"></a>`config-key/mask-read-only-required` | A config key is not both mask.readOnly and required, because nobody could fill it. | Drop required or mask.readOnly. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
115
125
  | <a id="config-key-options-and-options-query"></a>`config-key/options-and-options-query` | A config key declares either static options or optionsQuery, not both. | Remove options or optionsQuery. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
116
126
  | <a id="config-key-options-query-empty"></a>`config-key/options-query-empty` | A config key's optionsQuery is a non-empty query name when present. | Set it to a query name or remove it. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
117
127
  | <a id="config-key-options-query-not-select"></a>`config-key/options-query-not-select` | A config key declares optionsQuery only when its type is "select". | Change the key type to "select" or remove optionsQuery. | `packages/framework/src/engine/boot-validator/config-key-rules.ts` |
@@ -676,6 +686,8 @@
676
686
  | <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` |
677
687
  | <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` |
678
688
  | <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` |
689
+ | <a id="list-date-only-after-days-invalid"></a>`list/date-only-after-days-invalid` | A column's dateOnlyAfterDays is a non-negative whole number of days. | Set dateOnlyAfterDays to 0 or a positive integer. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
690
+ | <a id="list-date-only-after-days-wrong-type"></a>`list/date-only-after-days-wrong-type` | dateOnlyAfterDays sits on a timestamp, locatedTimestamp or date column or a relativeTime column. | Remove dateOnlyAfterDays from the column or point it at a timestamp, locatedTimestamp or date field. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
679
691
  | <a id="list-empty-state-action-params"></a>`list/empty-state-action-params` | Empty-state actions set no params, because an empty list has no row to read them from. | Remove the params. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
680
692
  | <a id="list-enum-option-tones-invalid"></a>`list/enum-option-tones-invalid` | enumOption column tones are known select option tones. | Use only the allowed tones (SELECT_OPTION_TONES). | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
681
693
  | <a id="list-facet-duplicate"></a>`list/facet-duplicate` | Each facet field is declared once. | Declare each facet field once. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
@@ -727,6 +739,14 @@
727
739
  | Rule | Summary | Fix | Source |
728
740
  | --- | --- | --- | --- |
729
741
  | <a id="list-bulk-entry-not-object"></a>`list-bulk/entry-not-object` | Every bulkActions entry is an object with id and rowAction. | Write each entry as { id, rowAction }. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
742
+ | <a id="list-bulk-form-ids-field-missing"></a>`list-bulk/form-ids-field-missing` | A bulk form action names the form field that receives the selected ids. | Set idsField to a field of the target form. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
743
+ | <a id="list-bulk-form-ids-field-not-list"></a>`list-bulk/form-ids-field-not-list` | A bulk form action's idsField is a multiSelect field with display: "count". | Declare the field as { type: "multiSelect", options: [], display: "count" } on the target form. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
744
+ | <a id="list-bulk-form-ids-field-not-rendered"></a>`list-bulk/form-ids-field-not-rendered` | A bulk form action's idsField is shown by the target form's layout and not sensitive. | Add the field to the form layout (visible: false hides it but keeps the value) and drop sensitive. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
745
+ | <a id="list-bulk-form-ids-field-unknown"></a>`list-bulk/form-ids-field-unknown` | A bulk form action's idsField is a field of the target form. | Declare the field on the target form or point idsField at a declared one. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
746
+ | <a id="list-bulk-form-label-missing"></a>`list-bulk/form-label-missing` | A bulk form action has a label (i18n key) for its button. | Set label to an i18n key. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
747
+ | <a id="list-bulk-form-screen-missing"></a>`list-bulk/form-screen-missing` | A bulk form action names the screen it opens in screen. | Set screen to the id of an actionForm screen. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
748
+ | <a id="list-bulk-form-screen-not-action-form"></a>`list-bulk/form-screen-not-action-form` | A bulk form action opens an actionForm screen. | Point screen at an actionForm screen. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
749
+ | <a id="list-bulk-form-screen-unresolved"></a>`list-bulk/form-screen-unresolved` | A bulk form action's screen resolves to a registered screen. | Use the id of a screen in this feature or a fully-qualified <feature>:screen:<id>. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
730
750
  | <a id="list-bulk-id-duplicate"></a>`list-bulk/id-duplicate` | Bulk action ids are unique within a list. | Rename or remove the duplicate bulk action. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
731
751
  | <a id="list-bulk-id-not-kebab"></a>`list-bulk/id-not-kebab` | A bulk action id is a kebab-case string. | Rename the id to kebab-case. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
732
752
  | <a id="list-bulk-not-array"></a>`list-bulk/not-array` | bulkActions is a non-empty array. | Write bulkActions as [{ id: "archive", rowAction: "archive" }] or remove it. | `packages/framework/src/engine/boot-validator/list-bulk-actions-rules.ts` |
@@ -786,7 +806,7 @@
786
806
  | <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` |
787
807
  | <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` |
788
808
  | <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` |
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. | Set table: { columnPicker: true } or remove hidden from the column. | `packages/framework/src/engine/boot-validator/list-table-rules.ts` |
809
+ | <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` |
790
810
  | <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` |
791
811
  | <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` |
792
812
  | <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` |
@@ -967,12 +987,14 @@
967
987
  | <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` |
968
988
  | <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` |
969
989
  | <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` |
990
+ | <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` |
970
991
  | <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` |
971
992
  | <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` |
972
993
  | <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` |
973
994
  | <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` |
974
995
  | <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` |
975
996
  | <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` |
997
+ | <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` |
976
998
  | <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` |
977
999
  | <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` |
978
1000
  | <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` |
@@ -88,7 +88,7 @@ handler marked `agent: { risk: "high" }`. A job or an event consumer has no hand
88
88
  `irreversibleWithoutEntryHandler` on `r.job` or `r.multiStreamProjection`, or the gate refuses with
89
89
  `irreversible_operation_without_entry_handler`. The value names why no entry handler exists:
90
90
  `rebuildable-derived-data` (the data is derived and a rebuild recreates it), `high-risk-or-cron-pipeline`
91
- (a maintenance pipeline that is high-risk by design, like `purge-archived-comments`) or
91
+ (a manually started or cron pipeline that is high-risk by design, like `purge-archived-comments`) or
92
92
  `per-dispatch-record-key` (the key belongs to one dispatch record). Hooks and routes never inherit the
93
93
  declaration; they dispatch a `risk: "high"` handler instead.
94
94
 
@@ -365,7 +365,7 @@ export const hrFeature = defineFeature("hr", (r) => {
365
365
  r.job(
366
366
  "purge-archived-comments",
367
367
  {
368
- trigger: { maintenance: true },
368
+ trigger: { manual: true },
369
369
  runIn: "worker",
370
370
  irreversibleWithoutEntryHandler: "high-risk-or-cron-pipeline",
371
371
  },
@@ -28,6 +28,10 @@ query and the fields to read, the query does the counting.
28
28
  `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
29
29
  over the whole WHERE clause, so no rows are loaded just to be counted.
30
30
  - **Labels are translation keys**: declared with `r.translations`.
31
+ - **`progress-list` head from the answer**: `labelParams` fills the `{month}` of the
32
+ label from the query answer and `subtitleField` shows the period muted at the head's right.
33
+ - **List footer without a link**: `footerLink` with only `moreText` (no `label`)
34
+ shows the muted "k more" count under the list.
31
35
  - **Record-bound dashboard**: `ticket-record-dashboard` binds to a record with `record`
32
36
  and embeds the `ticket-card` projectionDetail as a screen panel; the record id
33
37
  becomes its entityId.
@@ -299,8 +303,33 @@ export const ticketFeature = defineFeature("tickets", (r) => {
299
303
  access: readerRoles,
300
304
  });
301
305
 
306
+ // Three newest rows plus the total, so the panel can say how many more exist.
307
+ r.queryHandler({
308
+ name: "ticket:recent",
309
+ schema: z.object({}),
310
+ handler: async (query, ctx) => {
311
+ const page = await ticketExecutor.list({ limit: 3, totalCount: true }, query.user, ctx.db);
312
+ return { rows: page.rows, nextCursor: null, total: page.total ?? page.rows.length };
313
+ },
314
+ access: readerRoles,
315
+ });
316
+
317
+ r.queryHandler({
318
+ name: "ticket:quota",
319
+ schema: z.object({}),
320
+ handler: async () => ({
321
+ month: "November",
322
+ period: "01.11. - 30.11.",
323
+ rows: [{ label: "Tickets handled", used: 18, limit: 25, sub: "7 left" }],
324
+ }),
325
+ access: readerRoles,
326
+ });
327
+
302
328
  r.translations({
303
329
  keys: {
330
+ "tickets.dashboard.recent": { en: "Recent tickets" },
331
+ "tickets.dashboard.recent-more": { en: "{count} more tickets" },
332
+ "tickets.dashboard.quota": { en: "Quota {month}" },
304
333
  "screen:ticket-list.title": { en: "Tickets" },
305
334
  "screen:ticket-card.title": { en: "Ticket" },
306
335
  "screen:ticket-record-dashboard.title": { en: "Ticket overview" },
@@ -314,6 +343,7 @@ export const ticketFeature = defineFeature("tickets", (r) => {
314
343
  "tickets.dashboard.open": { en: "Open" },
315
344
  "tickets.dashboard.closed": { en: "Closed" },
316
345
  "tickets.dashboard.total": { en: "All tickets" },
346
+ "tickets.dashboard.total-narrow": { en: { one: "{count} ticket", other: "{count} tickets" } },
317
347
  "tickets.dashboard.open-work": { en: "Open work" },
318
348
  "tickets.filter.open-work": { en: "Open work" },
319
349
  "screen:ticket-queue.title": { en: "Ticket queue" },
@@ -349,6 +379,8 @@ export const ticketFeature = defineFeature("tickets", (r) => {
349
379
  kind: "stat",
350
380
  id: "total",
351
381
  label: "tickets.dashboard.total",
382
+ // Below sm the label is replaced by this plural key, resolved with { count: <value> }.
383
+ labelNarrow: "tickets.dashboard.total-narrow",
352
384
  query: TICKET_STATS_QUERY,
353
385
  valueField: "total",
354
386
  },
@@ -362,6 +394,25 @@ export const ticketFeature = defineFeature("tickets", (r) => {
362
394
  params: { namedFilter: "open-work", limit: 1, totalCount: true },
363
395
  navigate: { screen: "ticket-queue", namedFilter: "open-work" },
364
396
  },
397
+ // Without `label` the footer is only the muted "k more" count, no link.
398
+ {
399
+ kind: "list",
400
+ id: "recent",
401
+ label: "tickets.dashboard.recent",
402
+ query: "tickets:query:ticket:recent",
403
+ // `badgeIcon: "sparkles"` draws an AI-prepared value as the soft blue AI pill with an icon.
404
+ columns: ["title", { field: "status", display: "badge", badgeIcon: "sparkles" }],
405
+ footerLink: { moreText: "tickets.dashboard.recent-more", screen: "ticket-queue" },
406
+ },
407
+ // The title takes its month from the answer and the period shows muted at the head's right.
408
+ {
409
+ kind: "progress-list",
410
+ id: "quota",
411
+ label: "tickets.dashboard.quota",
412
+ labelParams: { month: "month" },
413
+ subtitleField: "period",
414
+ query: "tickets:query:ticket:quota",
415
+ },
365
416
  ],
366
417
  access: readerRoles,
367
418
  });