@cosmicdrift/kumiko-framework 0.416.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 (48) hide show
  1. package/agents/api/framework-engine.md +31 -9
  2. package/agents/api/framework-ui-types.md +23 -5
  3. package/agents/api/renderer-web.md +24 -2
  4. package/agents/api/types.md +94 -60
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +3 -1
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/event-sourcing.md +84 -0
  9. package/agents/examples/list-table-options.md +71 -5
  10. package/agents/examples/managed-config.md +9 -1
  11. package/agents/examples/record-detail-layout.md +71 -6
  12. package/agents/examples/secrets-demo.md +3 -1
  13. package/agents/examples/signature.md +3 -2
  14. package/agents/examples/writeform-section.md +329 -0
  15. package/dist/db/queries/event-store.d.ts +3 -0
  16. package/dist/db/queries/event-store.js +12 -0
  17. package/dist/engine/boot-validator/boot-rules.d.ts +11 -1
  18. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  19. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  20. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  21. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  22. package/dist/engine/boot-validator/list-table-options.js +8 -6
  23. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  24. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  25. package/dist/engine/boot-validator/query-output-columns.js +4 -0
  26. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  27. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  28. package/dist/engine/boot-validator/screens-actions.js +2 -0
  29. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  30. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  31. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  32. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  33. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  34. package/dist/engine/boot-validator/screens.js +1 -2
  35. package/dist/engine/bridge-stub.js +1 -0
  36. package/dist/engine/build-config-feature-schema.js +25 -2
  37. package/dist/engine/screen-helpers.js +7 -3
  38. package/dist/event-store/archive.d.ts +1 -0
  39. package/dist/event-store/archive.js +5 -1
  40. package/dist/event-store/event-store.d.ts +5 -0
  41. package/dist/event-store/event-store.js +23 -3
  42. package/dist/i18n/required-surface-keys.js +6 -0
  43. package/dist/pipeline/handler-context-events.js +15 -1
  44. package/dist/ui-types/card-column-roles.d.ts +3 -0
  45. package/dist/ui-types/card-column-roles.js +9 -5
  46. package/dist/ui-types/index.d.ts +1 -1
  47. package/package.json +3 -3
  48. package/src/changes.json +6 -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
 
@@ -2256,6 +2259,10 @@ type EditFieldViewModel = {
2256
2259
  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
2257
2260
  aiAssist?: FieldAiAssist; // From EditFieldSpec.aiAssist, chip labels and the prompt placeholder already translated.
2258
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.
2259
2266
  embeddedListCells?: EmbeddedListCellViewModel[]; // Only set for an embedded-LIST field (`multiple: true`) — the per-cell metadata the renderer needs to draw each column/cell.
2260
2267
  embeddedListMinItems?: number; // Minimum row count for the embedded list.
2261
2268
  embeddedListMaxItems?: number; // Maximum row count for the embedded list.
@@ -2332,6 +2339,7 @@ type ListColumnViewModel = {
2332
2339
  refLabelField?: string; // Only for `type: "reference"` — which field of the referenced entity appears as the display value in the cell (default "id").
2333
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.
2334
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.
2335
2343
  showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2336
2344
  narrowInline?: boolean; // Mirrors `ListColumnSpec.narrowInline`: the card draws consecutive such columns on one line.
2337
2345
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
@@ -2344,7 +2352,14 @@ type ListColumnViewModel = {
2344
2352
  badgeDot?: false; // `false`: the pill has no leading dot.
2345
2353
  pillField?: string; // Row field with the label of a pill drawn beside the cell value (`ListColumnSpec.pillField`).
2346
2354
  pillToneField?: string; // Row field naming the pill tone.
2347
- emptyPlaceholder?: false; // `false`: an empty cell stays blank instead of showing "—".
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`.
2348
2363
  };
2349
2364
  type ListRowViewModel = {
2350
2365
  id: string;
@@ -2389,7 +2404,7 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2389
2404
 
2390
2405
  ```ts
2391
2406
  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; }[];
2407
+ tiles: { id: string; imageId?: string; caption?: string; badge?: string; leadsOnNarrow?: true; actions?: ReactNode; }[];
2393
2408
  testId?: string;
2394
2409
  };
2395
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.
@@ -2423,6 +2438,66 @@ type StepListProps = { // Vertical numbered steps joined by a line; each step ha
2423
2438
  };
2424
2439
  ```
2425
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
+ };
2497
+ testId?: string;
2498
+ };
2499
+ ```
2500
+
2426
2501
  ## packages/renderer/src/primitives.tsx
2427
2502
 
2428
2503
  ```ts
@@ -2474,19 +2549,12 @@ type ConfigCascadeViewProps = { // Cascade view for a config-edit field: one ori
2474
2549
  qualifiedKey?: string;
2475
2550
  required?: boolean; // The key declares `required: true` — a missing value reads "Not set.
2476
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.
2477
2553
  };
2478
2554
  type ConfigSourceBadgeProps = { // Source-badge for one cascade step (User / Tenant / System / …).
2479
2555
  source: ConfigValueSource;
2480
2556
  screenScope?: ConfigScope; // Scope of the hosting screen.
2481
2557
  };
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
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.
2491
2559
  type DataTableRowAction = {
2492
2560
  id: string; // Stable ID for aria-labels and data-testids.
@@ -2594,6 +2662,7 @@ type ModalProps = { // Bare content shell for hosting an existing self-contained
2594
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.
2595
2663
  title?: string;
2596
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.
2597
2666
  status?: ReactNode;
2598
2667
  actions?: ReactNode;
2599
2668
  bodyTitle?: boolean; // Screen renders its own h1: the shell header shows only the parent crumb, as text.
@@ -2615,45 +2684,6 @@ type ProgressProps = {
2615
2684
  testId?: string;
2616
2685
  };
2617
2686
  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
2687
  type StatusBadgeProps = { // Status pill.
2658
2688
  value: string;
2659
2689
  tone?: StatusBadgeOptionTone;
@@ -2679,14 +2709,6 @@ type StepBarProps = { // Wizard step overview — numbered chips, one per step l
2679
2709
  testId?: string;
2680
2710
  compactTestId?: string;
2681
2711
  };
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
2712
  type TabsProps = { // Tab strip for a projectionDetail `layout.mode: "tabs"`.
2691
2713
  items: { id: string; label: string; count?: number; icon?: ReactNode; detail?: string; }[];
2692
2714
  activeId: string;
@@ -3187,6 +3209,8 @@ type ConfigMask = {
3187
3209
  icon?: NavIconKey;
3188
3210
  order?: number;
3189
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.
3190
3214
  };
3191
3215
  type ConfigSeedDef = {
3192
3216
  key: string;
@@ -5020,7 +5044,7 @@ type DashboardValueFormat = DashboardCurrencyFormat | DashboardRelativeTimeForma
5020
5044
  type EditFieldGroup = {
5021
5045
  title: string;
5022
5046
  fields: EditFieldSpec[];
5023
- columns?: number; // Default 2.
5047
+ columns?: number; // Edit mode renders 2 columns by default.
5024
5048
  };
5025
5049
  type EditFieldPrefill =
5026
5050
  | {
@@ -5031,12 +5055,13 @@ type EditFieldPrefill =
5031
5055
  property: "displayName" | "email" | "id";
5032
5056
  }
5033
5057
  ;
5034
- type EditFieldsSectionBase = {
5058
+ type EditFieldsSectionBase = EditSectionPresentation & {
5035
5059
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
5036
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`.
5037
5061
  kind?: "fields";
5038
5062
  title?: string; // Optional.
5039
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`.
5040
5065
  columns?: number;
5041
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.
5042
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).
@@ -5045,6 +5070,13 @@ type EditFieldsSectionBase = {
5045
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.
5046
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.
5047
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
+ };
5048
5080
  type EntityEditActionPlacement = "inline" | "menu";
5049
5081
  type EntityWriteExcludedFields = {
5050
5082
  create?: string[];
@@ -5075,7 +5107,7 @@ type RowActionNavigateBase = {
5075
5107
  showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
5076
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.
5077
5109
  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.
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.
5079
5111
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
5080
5112
  };
5081
5113
  type ScreenFilter = {
@@ -5144,12 +5176,14 @@ type MetricSpec = {
5144
5176
  subFieldNarrow?: string; // Record field shown instead of `subField` below `sm` ("of 2,850 €" instead of "0 of 2,850.00 €").
5145
5177
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
5146
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`.
5147
5180
  };
5148
5181
  type RecordHeaderSpec = {
5149
5182
  title: string;
5150
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.
5151
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.
5152
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.
5153
5187
  status?: string;
5154
5188
  statusFormat?: FormatSpec; // Formats the badge text (typically `enumOption` with a `keyPrefix`); tones still resolve on the raw value.
5155
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` | 189 |
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 |
@@ -786,7 +786,7 @@
786
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` |
787
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` |
788
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` |
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` |
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` |
790
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` |
791
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` |
792
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` |
@@ -967,12 +967,14 @@
967
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` |
968
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` |
969
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` |
970
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` |
971
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` |
972
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` |
973
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` |
974
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` |
975
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` |
976
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` |
977
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` |
978
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` |
@@ -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
  });
@@ -229,6 +229,59 @@ describe("Event Sourcing Showcase", () => {
229
229
  expect(byCustomer.get("Globex")).toMatchObject({ paidInvoices: 1, totalCents: 300 });
230
230
  });
231
231
 
232
+ test("loadByTypes: statuses of the requested invoices from approved/paid events only", async () => {
233
+ const requestedPaid = await stack.http.writeOk<{ id: string }>(
234
+ "showcase:write:invoice:create",
235
+ { customer: "Acme" },
236
+ admin,
237
+ );
238
+ const requestedApproved = await stack.http.writeOk<{ id: string }>(
239
+ "showcase:write:invoice:create",
240
+ { customer: "Acme" },
241
+ admin,
242
+ );
243
+ const notRequested = await stack.http.writeOk<{ id: string }>(
244
+ "showcase:write:invoice:create",
245
+ { customer: "Globex" },
246
+ admin,
247
+ );
248
+ for (const invoice of [requestedPaid, requestedApproved, notRequested]) {
249
+ await stack.http.writeOk(
250
+ "showcase:write:invoice:approve",
251
+ { id: invoice.id, amountCents: 100, approvedBy: "cfo" },
252
+ admin,
253
+ );
254
+ }
255
+ await stack.http.writeOk(
256
+ "showcase:write:invoice:pay",
257
+ { id: requestedPaid.id, amountCents: 100 },
258
+ admin,
259
+ );
260
+ await stack.http.writeOk(
261
+ "showcase:write:invoice:pay",
262
+ { id: notRequested.id, amountCents: 100 },
263
+ admin,
264
+ );
265
+ await stack.http.writeOk(
266
+ "showcase:write:invoice:acknowledge",
267
+ { id: requestedApproved.id, approverId: "cfo" },
268
+ admin,
269
+ );
270
+
271
+ const { statuses } = await stack.http.queryOk<{
272
+ statuses: Array<{ id: string; status: string }>;
273
+ }>(
274
+ "showcase:query:invoice:payment-statuses",
275
+ { ids: [requestedPaid.id, requestedApproved.id] },
276
+ admin,
277
+ );
278
+
279
+ expect(statuses).toEqual([
280
+ { id: requestedPaid.id, status: "paid" },
281
+ { id: requestedApproved.id, status: "approved" },
282
+ ]);
283
+ });
284
+
232
285
  test("asOf point-in-time read: invoice state before the pay event", async () => {
233
286
  const { id } = await stack.http.writeOk<{ id: string }>(
234
287
  "showcase:write:invoice:create",
@@ -837,6 +890,7 @@ describe("role-restricted write handlers", () => {
837
890
  // - r.projection — single-stream read model (inline in the write TX)
838
891
  // - r.multiStreamProjection — cross-aggregate async read model
839
892
  // - ctx.events.load with { asOf } — point-in-time aggregate state
893
+ // - ctx.events.loadByTypes — events of many aggregates, filtered by type, in one query
840
894
  // - ctx.events.archive / ctx.events.restore — Marten ArchiveStream
841
895
  // - ctx.dispatch.queryProjection — tenant-scoped read of a projection table
842
896
  // - ctx.events.snapshot + ctx.events.loadWithSnapshot — perf path
@@ -1225,6 +1279,36 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
1225
1279
  },
1226
1280
  });
1227
1281
 
1282
+ // List page over many invoices: ONE query for just the approved/paid events of the
1283
+ // requested aggregates instead of ctx.events.load per invoice.
1284
+ r.queryHandler({
1285
+ name: "invoice:payment-statuses",
1286
+ schema: z.object({ ids: z.array(z.uuid()).max(200) }),
1287
+ handler: async (query, ctx) => {
1288
+ const events = await ctx.events.loadByTypes({
1289
+ aggregateIds: query.payload.ids,
1290
+ eventTypes: [approved.name, paid.name],
1291
+ });
1292
+ const lastEventByInvoice = new Map<string, string>();
1293
+ for (const evt of events) {
1294
+ lastEventByInvoice.set(evt.aggregateId, evt.type);
1295
+ }
1296
+ return {
1297
+ statuses: [...lastEventByInvoice].map(([id, lastEventType]) => ({
1298
+ id,
1299
+ status: lastEventType === paid.name ? "paid" : "approved",
1300
+ })),
1301
+ };
1302
+ },
1303
+ access: {
1304
+ openToAll: {
1305
+ reason:
1306
+ "demo recipe: any signed-in user may read invoice payment statuses; " +
1307
+ "there is no per-user invoice ownership in this sample",
1308
+ },
1309
+ },
1310
+ });
1311
+
1228
1312
  // Snapshot-aware fast path. Uses the latest snapshot if available and
1229
1313
  // only replays delta events past it. Identical state shape to
1230
1314
  // invoice:state — the two are interchangeable modulo the perf profile.
@@ -35,6 +35,15 @@ the `table` block renders and behaves as before.
35
35
  offers grouping by priority or none.
36
36
  - `table.totals`: a footer row with the estimate sum over the filtered list.
37
37
  - `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
38
+ - `mutedRowField: "parked"`: a parked task is drawn entirely in the muted colour.
39
+ - `toolbarSort: true`: the desktop "Sorted by" select in the filter row (opt-in).
40
+ - Column options: `ellipsis` (one truncated line), `multiline` (line breaks stay),
41
+ `tone: "muted"`, `cardAbove` (phone card line above the title), `hideWhenDocked`,
42
+ `emptyPlaceholder` (`false` keeps the cell blank, a string shows muted text),
43
+ `cardBadge` (phone-card pill), `dateOnlyAfterDays` on a timestamp column,
44
+ `pillField` / `pillToneField` (a second pill beside the cell value).
45
+ - Row action `display: "text"`: muted text without a button, shown for done tasks.
46
+ - `hideCountFooter` is not set here: no screen declaration reaches it (relatedList sets it itself).
38
47
  - The same block on a `projectionList`, and `task:workload`, a hand-written list
39
48
  query that keeps grouping and totals by accepting `aggregate`
40
49
  (`entityListSchema`) and answering it with `answerListAggregate`.
@@ -145,9 +154,21 @@ describe("list-table-options recipe", () => {
145
154
  );
146
155
  });
147
156
 
148
- test("a hidden column needs the column picker", () => {
149
- expect(() => validateBoot([featureWithBlock({ rememberState: true, resetAll: true })])).toThrow(
150
- /column "estimateHours" is hidden but table\.columnPicker is not enabled/,
157
+ // A hidden column that backs a facet needs no picker (the facet is its UI), so the recipe's
158
+ // own hidden estimateHours column does not trip the rule; a plain hidden column does.
159
+ test("a hidden column without a facet needs the column picker", () => {
160
+ const feature = defineFeature("task-board", (r) => {
161
+ r.crud("task", taskEntity, { write: openAccess, read: openAccess });
162
+ r.screen({
163
+ id: "task-list",
164
+ type: "entityList",
165
+ entity: "task",
166
+ columns: ["title", { field: "assignee", hidden: true }],
167
+ table: { rememberState: true },
168
+ });
169
+ });
170
+ expect(() => validateBoot([feature])).toThrow(
171
+ /column "assignee" is hidden but table\.columnPicker is not enabled/,
151
172
  );
152
173
  });
153
174
 
@@ -248,11 +269,13 @@ import {
248
269
  createEventStoreExecutor,
249
270
  } from "@cosmicdrift/kumiko-framework/db";
250
271
  import {
272
+ createBooleanField,
251
273
  createDateField,
252
274
  createEntity,
253
275
  createNumberField,
254
276
  createSelectField,
255
277
  createTextField,
278
+ createTimestampField,
256
279
  defineFeature,
257
280
  entityListSchema,
258
281
  type FeatureDefinition,
@@ -285,6 +308,14 @@ export const taskEntity = createEntity({
285
308
  dueDate: createDateField({ sortable: true }),
286
309
  assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
287
310
  estimateHours: createNumberField({ sortable: true, filterable: true }),
311
+ parked: createBooleanField({ default: false }),
312
+ note: createTextField({ personal: false, reason: "is_business_data" }),
313
+ team: createTextField({ personal: false, reason: "is_business_data" }),
314
+ teamTone: createSelectField({
315
+ options: ["positive", "warn", "negative", "neutral"] as const,
316
+ default: "neutral",
317
+ }),
318
+ lastUpdate: createTimestampField({ sortable: true }),
288
319
  },
289
320
  });
290
321
 
@@ -320,9 +351,29 @@ export function createTaskBoardFeature(
320
351
  // Starts pinned left; width and minWidth are start values for resizing.
321
352
  { field: "title", pinned: "left", width: 280, minWidth: 160 },
322
353
  "status",
323
- "priority",
354
+ // The phone card shows the priority as its outlined pill instead of the first select column.
355
+ { field: "priority", cardBadge: true },
324
356
  { field: "dueDate", hideOnNarrow: true },
325
- { field: "assignee", hideOnNarrow: true },
357
+ // The team pill sits beside the assignee name; its tone comes from the row.
358
+ {
359
+ field: "assignee",
360
+ hideOnNarrow: true,
361
+ pillField: "team",
362
+ pillToneField: "teamTone",
363
+ emptyPlaceholder: "Unassigned",
364
+ },
365
+ // One truncated line in the table; a line break starts a new line on the phone card.
366
+ {
367
+ field: "note",
368
+ ellipsis: true,
369
+ multiline: true,
370
+ tone: "muted",
371
+ cardAbove: true,
372
+ hideWhenDocked: true,
373
+ emptyPlaceholder: false,
374
+ },
375
+ // Recent edits show date and time, older ones the date only.
376
+ { field: "lastUpdate", dateOnlyAfterDays: 7, hideOnNarrow: true },
326
377
  // Starts hidden; the user can add it back in the view menu.
327
378
  { field: "estimateHours", hidden: true, hideOnNarrow: true },
328
379
  ],
@@ -330,7 +381,22 @@ export function createTaskBoardFeature(
330
381
  defaultSort: { field: "dueDate", dir: "asc" },
331
382
  searchable: true,
332
383
  table: taskTable,
384
+ mutedRowField: "parked",
385
+ toolbarSort: true,
386
+ sortOptions: [
387
+ { field: "dueDate", dir: "asc", label: "Due date" },
388
+ { field: "priority", dir: "desc", label: "Priority" },
389
+ ],
333
390
  rowActions: [
391
+ // A closed state as muted text instead of a button.
392
+ {
393
+ kind: "navigate",
394
+ id: "closed",
395
+ label: "Closed",
396
+ screen: "task-edit",
397
+ display: "text",
398
+ visible: { field: "status", eq: "done" },
399
+ },
334
400
  { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
335
401
  {
336
402
  kind: "writeHandler",