@cosmicdrift/kumiko-framework 0.415.0 → 0.417.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -35,7 +35,7 @@ function createDecimalField<R extends true | false = false>(config: { precision:
35
35
  function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
36
36
  function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
37
37
  function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
38
- function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; systemRowsReadable?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
38
+ function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; systemRowsReadable?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; crossTenantFileRead?: EntityDefinition["crossTenantFileRead"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
39
39
  function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
40
40
  function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
41
41
  function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
@@ -281,14 +281,19 @@ type ActionFormScreenDefinition = {
281
281
  fields: Readonly<Record<string, FormFieldDefinition>>; // Form shape: field map by name.
282
282
  derive?: Readonly<Record<string, FormFieldDerivation>>; // Fields computed from other fields, shown read-only and recomputed on every change.
283
283
  layout: EditLayout; // Layout analogous to EntityEditScreen: sections with fields from the fields map above.
284
- fieldLabels?: Readonly<Record<string, string>>; // Per-field label i18n key override, same type/semantics as `EntityEditScreenDefinition.fieldLabels`.
284
+ fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Per-field label i18n key override, same type/semantics as `EntityEditScreenDefinition.fieldLabels`.
285
285
  submitLabel?: string; // i18n key for the submit button.
286
286
  footerActions?: ActionFormFooterAction[]; // Extra buttons in the form footer next to the submit button.
287
287
  summary?: {
288
288
  title: string;
289
289
  subtitle?: string;
290
290
  params?: Readonly<Record<string, string>>;
291
+ paramsFromLoad?: string[]; // Fields of the `load` result that fill `{name}` placeholders too (static `params` win).
291
292
  }; // Context box above the fields (i18n keys).
293
+ fieldDescriptions?: Readonly<Record<string, FieldTextRef>>; // Help text under a field (field name -> i18n key).
294
+ infoBand?: string; // i18n key of a short note in a banner above the fields, with a sparkles icon (e.g. "the AI prepared everything, read the text, then send").
295
+ fieldBadges?: Readonly<Record<string, { label: string; tone: SelectOptionTone; }>>; // Badge next to a field's label (field name -> `{ label: i18n key, tone }`), e.g. "price source open" in `warn`.
296
+ formErrorOnTop?: boolean; // Shows a failed submit's error banner above the fields instead of below them.
292
297
  submitStyle?: "primary" | "danger"; // Visual style of the submit button.
293
298
  successMessage?: string; // i18n key of a confirmation shown above the form after a successful submit when the screen stays put (no `redirect`, not drawer-hosted).
294
299
  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful submit: either a short ID (e.g. "item-list" — same feature, the nav-router resolves to the full path) or a fully-qualified cross-feature QN (`<feature>:screen:<id>`).
@@ -410,6 +415,7 @@ type ConfigEditScreenDefinition = {
410
415
  fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
411
416
  requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
412
417
  submitLabel?: string; // i18n key for the submit button.
418
+ compact?: true; // Compact rows: no origin icon, no reset link, no accent bar on changed fields; the form column is capped to a readable width.
413
419
  actions?: ConfigEditAction[]; // Handler buttons drawn as their own row after `afterField` (settings-list layout).
414
420
  slots?: ScreenSlots;
415
421
  access?: AccessRule;
@@ -530,6 +536,12 @@ type EditFieldSpec =
530
536
  prefix?: FieldAffix; // Static text shown before the input (i18n key, falls back to the literal), or `{ field }` for the current form value of another field (a hidden field carrying e.g. a base domain).
531
537
  suffix?: FieldAffix; // Same as `prefix`, shown after the input.
532
538
  fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
539
+ aiAssist?: FieldAiAssist; // Helper under a `text` or `longText` input: stackable chips and an optional free instruction call a query and write its `resultField` into the field.
540
+ valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
541
+ concealed?: true; // Read-only display of a value the viewer may not see: the value (or the mask the query returns) shows muted with a lock icon instead of a replacement text.
542
+ badge?: FieldBadge; // Pill next to the label, e.g. "price source open" in `warn`.
543
+ hintField?: string; // Value field whose non-empty text shows as a muted small hint under the field (e.g. "From the buyer: Skoda Octavia").
544
+ hideOnNarrow?: true; // Leaves the field out below `sm`; its value is still submitted.
533
545
  refEntity?: string; // Marks this field as a reference lookup instead of a plain value — for projectionDetail fields, which have no `EntityDefinition` to carry a real `reference` field type.
534
546
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
535
547
  format?: "email" | "phone"; // Text format for projectionDetail fields, which have no `EntityDefinition` to carry it: a read-only value renders as a `mailto:`/`tel:` link.
@@ -537,8 +549,9 @@ type EditFieldSpec =
537
549
  prefill?: EditFieldPrefill; // Fills an empty value when the create form opens; the update form and values from URL params or a handoff are never touched.
538
550
  }
539
551
  ;
540
- type EditRelatedListSection = {
552
+ type EditRelatedListSection = EditSectionPresentation & {
541
553
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
554
+ 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`.
542
555
  kind: "relatedList";
543
556
  title: string;
544
557
  readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
@@ -569,8 +582,14 @@ type EditRelatedListSection = {
569
582
  count?: true; // Tab badge counted from this section's own query (`limit: 1, totalCount: true` → `total`), so it matches the tab's rows and stays live.
570
583
  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the parent record.
571
584
  emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
572
- };
573
- type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
585
+ photoGrid?: {
586
+ imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
587
+ captionField?: string; // Row field printed under the image; without it the tile reads "Photo n".
588
+ badgeField?: string; // Row field whose non-empty text shows as a warn badge on the image's top left.
589
+ badgeFirst?: true; // On a phone (below `sm`) tiles whose `badgeField` has text come first, the rest keep their order; from `sm` up the natural order stays.
590
+ }; // Draws the rows as a tile grid of images instead of a table.
591
+ };
592
+ type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
574
593
  type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & { // Resolver callback shape: synchronous (on the dispatcher's hot path), per tenant.
575
594
  trialGate?: TrialGate; // Optional live-trial gate, consulted by the dispatcher feature gate ONLY when the synchronous resolver reports a feature as disabled.
576
595
  };
@@ -602,6 +621,10 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
602
621
  description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
603
622
  transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
604
623
  attachedFileAccess?: "record-only"; // Attached files are readable only through the record's detail query: the files feature's privilegedRoles do not bypass it, the uploader check stays.
624
+ crossTenantFileRead?: {
625
+ query: string;
626
+ reason: string;
627
+ }; // Files of this entity may be read from another tenant when `query`, run with `{ id: <entityId> }` as the requesting user, returns the record with that id.
605
628
  };
606
629
  type EntityEditScreenDefinition = {
607
630
  id: string;
@@ -628,7 +651,7 @@ type EntityEditScreenDefinition = {
628
651
  singleton?: boolean; // Default false.
629
652
  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful save (create or update).
630
653
  listScreenId?: string; // Parent list screen (short id) for breadcrumb + nav highlighting when this screen has no nav entry of its own.
631
- fieldLabels?: Readonly<Record<string, string>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
654
+ fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
632
655
  actions?: EntityEditAction[]; // Record actions.
633
656
  slots?: ScreenSlots;
634
657
  access?: AccessRule;
@@ -651,6 +674,7 @@ type EntityListScreenDefinition = {
651
674
  allowCreate?: boolean; // `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action.
652
675
  columns: ListColumnSpec[];
653
676
  rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
677
+ mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
654
678
  rowDecoration?: ListRowDecoration; // Computed row fields from an app query, readable by `rowToneField`, column `hint`, `linkScreenField`/`linkParamsField` and rowAction `visible`/`params`/`payload`; a column may name a decoration field.
655
679
  rowRenderer?: PlatformComponent;
656
680
  rowActions?: RowAction[]; // Per-row actions, rendered as an actions column on the right.
@@ -858,10 +882,18 @@ interface FieldFormatRegistry {
858
882
  timeStyle?: "full" | "long" | "medium" | "short";
859
883
  timeZone?: string; // IANA zone id (e.g. "Europe/Berlin").
860
884
  };
885
+ relativeTime: {
886
+ locale?: string;
887
+ style?: "long" | "short" | "narrow";
888
+ absoluteAfterDays?: number;
889
+ withTime?: boolean;
890
+ timeZone?: string; // IANA zone id for the clock time and the day boundary.
891
+ }; // Epoch ms or ISO timestamp, shown as "5 min.
861
892
  date: {
862
893
  locale?: string;
863
894
  dateStyle?: "full" | "long" | "medium" | "short";
864
895
  };
896
+ phone: Record<never, never>; // Telephone number shown as a `tel:` link in list cells, like a read-only `format: "phone"` field.
865
897
  boolean: {
866
898
  trueLabel?: string;
867
899
  falseLabel?: string;
@@ -943,6 +975,7 @@ type HandlerEvents<TMap extends object = KumikoEventTypeMap> = { // Event-store
943
975
  tryAppend: TryAppendEventFn; // Optimistic append: runs in a savepoint and returns a version conflict as a result instead of throwing, so the handler can continue after losing a race on the same aggregate stream.
944
976
  fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
945
977
  load: (aggregateId: string, options?: { asOf?: Temporal.Instant; atVersion?: never; includeArchived?: boolean; } | { atVersion?: number; asOf?: never; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
978
+ loadByTypes: (args: { aggregateIds: string[]; eventTypes: string[]; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
946
979
  archive: (aggregateId: string, args: { aggregateType: string; reason?: string; }) => Promise<void>;
947
980
  restore: (aggregateId: string) => Promise<void>;
948
981
  isArchived: (aggregateId: string) => Promise<boolean>;
@@ -1049,17 +1082,29 @@ type ListColumnSpec =
1049
1082
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
1050
1083
  sortable?: boolean; // Marks this column as sortable via a clickable header — for relatedList columns, which have no `EntityDefinition` field to carry `sortable` on.
1051
1084
  valueType?: "number" | "decimal" | "bigInt" | "money"; // Value type of a projectionList or relatedList column, which has no `EntityDefinition` field to derive it from.
1052
- emptyPlaceholder?: false; // `false` leaves an empty cell blank instead of drawing the "—" placeholder.
1053
- hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
1085
+ emptyPlaceholder?: string | false; // An empty cell stays blank by default; a string (i18n key or literal) is shown muted in its place, e.g. "No vehicle".
1086
+ hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (phone viewport).
1087
+ hideWhenDocked?: true; // Leaves the column out of a table whose container is narrower than `md` (docked assistant panel); the viewport is not looked at, so the phone card still shows it.
1054
1088
  showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
1055
1089
  narrowInline?: true; // In the compact card, consecutive `narrowInline` columns stand side by side on one line (12px gap, no separator) instead of one line each.
1090
+ ellipsis?: true; // One line with a trailing ellipsis in the table; the full text is the cell's `title`.
1091
+ multiline?: true; // Free text: the cell wraps instead of ending in "…", and a line break (`\n`) in the value starts a new line (table and phone card).
1092
+ cardAbove?: true; // Phone card: the column's line stands above the title (muted, e.g. "date, channel") instead of below it.
1093
+ emphasis?: true; // Cell text in medium weight and foreground colour, like the title column of a board.
1094
+ tone?: "muted"; // `"muted"` draws every cell of the column in the muted text colour (e.g. a free-text message beside primary columns).
1095
+ cardBadge?: true; // The phone card shows this column as its badge: right of the title, as an outlined neutral pill (a `display: "badge"` column keeps its own pill).
1096
+ dateOnlyAfterDays?: number; // Timestamp or relativeTime column: a value older than this many days shows the date only, without the time.
1056
1097
  hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
1057
1098
  pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
1058
1099
  width?: number; // Start width in px.
1059
1100
  minWidth?: number; // Smallest width in px the user can resize to.
1060
1101
  display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
1061
- badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
1102
+ variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
1103
+ badgeToneField?: string; // Row field naming the badge tone: a `ListBadgeTone` word or a `SelectOptionTone` word (`ok`, `bad`, `critical`, `accent`); only with `display: "badge"`.
1062
1104
  badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
1105
+ badgeIcon?: "sparkles"; // `"sparkles"` marks an AI-prepared value: the dashboard list draws the badge as the soft blue AI pill with a sparkles icon, like an AI row action; only with `display: "badge"`.
1106
+ pillField?: string; // Row field holding a second label, drawn as a pill next to the cell's own value (e.g. a vehicle name with a "free" pill).
1107
+ pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
1063
1108
  linkScreenField?: string; // Row field holding a screen QN (`<feature>:screen:<id>`): the cell links to that screen when the row sets it and the user may open it.
1064
1109
  linkParamsField?: string; // Row field holding a params object for the linkScreenField target: `entityId` opens that record, the other keys become search params (e.g. actionForm prefill).
1065
1110
  hint?: ListColumnHint; // "To do" cell: the column's field holds a sentence, shown emphasized in the row tone; an empty value shows `emptyLabel`.
@@ -1383,8 +1428,11 @@ type ProjectionDetailScreenDefinition = {
1383
1428
  metrics?: MetricSpec[]; // Metric band above the layout — column names in the query row, each with its own i18n `label`.
1384
1429
  metricsStyle?: "band" | "tiles"; // "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band.
1385
1430
  metricsPlacement?: {
1386
- narrow?: "after-guidance";
1387
- }; // `narrow: "after-guidance"` moves the metrics below the summary, banner and steps on screens under md, ahead of the tabs.
1431
+ narrow?: "after-guidance" | "before-steps";
1432
+ }; // On screens under md, `narrow: "after-guidance"` moves the metrics below the summary, banner and steps, ahead of the tabs; `"before-steps"` puts them below the summary and banner, ahead of the next step.
1433
+ mobileSummary?: string; // Record field holding one line of text shown instead of the metrics below `sm`.
1434
+ pageNavigation?: false; // `false` leaves out the "On this page" navigation of a stacked (non-tabs) layout.
1435
+ photosBeside?: true; // A tab holding fields sections and a relatedList with `photoGrid` shows the fields left and the photos right from `lg` up.
1388
1436
  breadcrumb?: RecordBreadcrumbSpec; // Path above the header (query column holding items).
1389
1437
  summary?: RecordSummarySpec; // One emphasized sentence below the header.
1390
1438
  banner?: RecordBannerSpec; // Notice below the summary.
@@ -1393,9 +1441,12 @@ type ProjectionDetailScreenDefinition = {
1393
1441
  listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
1394
1442
  slots?: ScreenSlots;
1395
1443
  access?: AccessRule;
1396
- actions?: RowAction[]; // Header action buttons.
1444
+ actions?: EntityEditAction[]; // Header action buttons.
1397
1445
  primaryAction?: string; // Id of the action that stays the visible header button when the actions collapse into a menu (and the one that keeps the phone icon slot when it has an icon and no confirm).
1398
1446
  inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
1447
+ footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
1448
+ footerHint?: string; // i18n key of a note on the left of the footer bar ("Changes go out with the release"); hidden below `sm`.
1449
+ initialTab?: ProjectionDetailInitialTab[]; // Tab that opens first when the URL names none: the first rule whose condition holds on the record wins, else the first visible tab.
1399
1450
  valueDisplay?: "form" | "text"; // How head fields render.
1400
1451
  };
1401
1452
  type ProjectionListScreenDefinition = {
@@ -1412,6 +1463,7 @@ type ProjectionListScreenDefinition = {
1412
1463
  query: string;
1413
1464
  columns: ListColumnSpec[];
1414
1465
  rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
1466
+ mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
1415
1467
  rowDecoration?: ListRowDecoration; // Computed row fields from an app query, merged into the query rows; see `ListRowDecoration`.
1416
1468
  rowRenderer?: PlatformComponent;
1417
1469
  rowActions?: RowAction[];
@@ -1584,7 +1636,9 @@ type RoleAccessRule = {
1584
1636
  personalData?: RoleAccessPersonalData;
1585
1637
  anySignedIn?: true;
1586
1638
  };
1587
- type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
1639
+ type RowAction = (RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction) & {
1640
+ align?: "start"; // projectionDetail `footerActions` only: "start" sets the button apart on the left of the footer.
1641
+ };
1588
1642
  type RowActionWriteHandler = {
1589
1643
  kind?: "writeHandler"; // Default for RowActions without an explicitly set `kind` — backwards-compatible form.
1590
1644
  id: string; // Stable id per screen — kebab-case, unique within the action set.
@@ -65,11 +65,13 @@ type ActionFormLoad = {
65
65
  query: string; // Query QN that returns the record.
66
66
  idParam?: string; // Payload key carrying the record id (default "id").
67
67
  singleton?: boolean; // The query picks the row from the caller's tenant/session context, so the form loads without a record id and the query is called WITHOUT `idParam` (same semantics as `ProjectionDetailScreenDefinition.singleton`).
68
+ passPrefill?: boolean; // Sends the values a drawer opens the form with (row-action params, e.g. `vehicleId`) in the load payload next to `idParam`, so the query can pre-fill for the chosen item.
68
69
  };
69
70
  type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
70
71
  screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
71
- idFrom: string; // Flat field name in the handler's success payload, e.g. "leaseId".
72
+ idFrom?: string; // Flat field name in the handler's success payload, e.g. "leaseId".
72
73
  tab?: string; // Section id to open on the target `projectionDetail` with `layout.mode: "tabs"` (the `tab` search param, same as `ToolbarAction` navigate `tab`).
74
+ searchParams?: Readonly<Record<string, string>>; // URL search params of the target, each read from a flat success-payload field (`{ cmd: "threadId" }` opens `?cmd=<threadId>`).
73
75
  };
74
76
  type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
75
77
  field: string; // Flat field name in the handler's success payload.
@@ -79,7 +81,7 @@ type ActionFormSuccessItems = { // Per-entry hints of the success box, read from
79
81
  field: string; // Flat field name of an array in the success payload.
80
82
  link?: ActionFormSuccessLink; // Link of each hint.
81
83
  };
82
- type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & { // A redirect target rendered as a link in the success box.
84
+ type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom" | "searchParams"> & { // A redirect target rendered as a link in the success box.
83
85
  idFrom?: string; // Success-payload field carrying the navigation id.
84
86
  params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
85
87
  label: string; // Link text (i18n key).
@@ -152,6 +154,7 @@ type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState
152
154
  id: string;
153
155
  label: string;
154
156
  query: string;
157
+ showTotal?: true | Pick<DashboardListShowTotal, "text">; // Shows the count in the panel head, right-aligned like a list panel's `showTotal`: `{total}` is the query's `total`, else the rows returned.
155
158
  };
156
159
  type DashboardFilterDefinition = {
157
160
  id: string;
@@ -162,8 +165,9 @@ type DashboardFilterDefinition = {
162
165
  options?: { value: string; label: string; }[];
163
166
  optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
164
167
  };
168
+ type DashboardLayout = "main-side"; // "main-side": from `lg` up the main column (2/3) stacks every panel without `column`, the side column (1/3) every `column: "side"` panel, each with its own heights; `column: "top"` panels span both columns above them; below `lg` they stack, below `sm` by `narrowOrder`.
165
169
  type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
166
- label: string;
170
+ label?: string; // i18n key of the link text.
167
171
  moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
168
172
  narrowMoreText?: string; // i18n key used instead of `moreText` below `sm`.
169
173
  narrowOnly?: boolean; // Draw the link only below `sm`, where it is the target of the "line" layout; from `sm` up the panel shows no footer link.
@@ -200,6 +204,7 @@ type DashboardMoneyParam = { // Minor units (like Money fields), formatted with
200
204
  amountMinor: number;
201
205
  currency: string;
202
206
  };
207
+ type DashboardPanelColumn = "side" | "top"; // "top" spans both columns above the main and side column, in declared order.
203
208
  type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
204
209
  type DashboardPanelEmptyState = {
205
210
  span?: DashboardPanelSpan;
@@ -209,6 +214,7 @@ type DashboardPanelEmptyState = {
209
214
  type DashboardPanelNarrow = { // Phone layout switch shared by every panel kind.
210
215
  hideOnNarrow?: true; // Leaves the panel out below the `sm` breakpoint (phone).
211
216
  narrowOrder?: number; // Position below `sm`, like CSS `order`: panels are laid out by ascending value, a panel without one counts as 0, equal values keep the declared order.
217
+ column?: DashboardPanelColumn; // "side" puts the panel in the narrow right column of a `layout: "main-side"` dashboard, "top" in a full-width block above both columns; panels without it fill the main column.
212
218
  };
213
219
  type DashboardPanelQueryOptions = {
214
220
  params?: Readonly<Record<string, unknown>>; // Static, author-set query parameters merged on top of the screen's dynamic filterParams — lets a panel pin a value (e.g. a status facet) the screen-wide filter doesn't cover, without needing its own query.
@@ -224,6 +230,8 @@ type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmp
224
230
  kind: "progress-list";
225
231
  id: string;
226
232
  label: string;
233
+ labelParams?: Readonly<Record<string, string>>; // Fills the translated `label` from the query answer: maps a label placeholder to a top-level answer field, e.g. `{ month: "monthName" }` for "Quota {month}" with `{ rows, monthName: "November" }`.
234
+ subtitleField?: string; // Top-level answer field holding a text shown muted at the right end of the panel head, e.g. the period ("November").
227
235
  query: string;
228
236
  };
229
237
  type DashboardProgressTone = "default" | "danger";
@@ -254,6 +262,7 @@ type DashboardScreenDefinition = {
254
262
  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
255
263
  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
256
264
  panels: DashboardPanelDefinition[];
265
+ layout?: DashboardLayout; // Panel arrangement, see DashboardLayout.
257
266
  record?: DashboardRecordBinding; // Binds the dashboard to one record via a URL search param, see DashboardRecordBinding.
258
267
  actions?: RowAction[]; // Header actions on the bound record (writeHandler, navigate, clientAction).
259
268
  refresh?: DashboardRefresh;
@@ -303,6 +312,7 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & Dash
303
312
  valueField: string;
304
313
  labelField?: string; // Field of the query answer holding the label text, e.g. "Contracts ending by 31.01.2027"; it replaces the static `label` while it holds a non-empty string.
305
314
  narrowLabel?: string; // i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests").
315
+ labelNarrow?: string; // i18n key replacing `label` below the `sm` breakpoint wherever the stat draws its label (a dynamic `labelField` text still wins).
306
316
  subField?: string;
307
317
  toneField?: string;
308
318
  valueFormat?: DashboardValueFormat; // Formats a numeric value as currency (minor units) or, with `relativeTime`, as a ticking "5 minutes ago" from epoch ms; ignored for string values.
@@ -353,6 +363,7 @@ type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & Dash
353
363
  kind: "text";
354
364
  id: string;
355
365
  label?: string; // Panel title (i18n key).
366
+ icon?: PlatformComponent; // Icon shown before the text blocks (resolved like `DashboardStatGroupPanel.icon`).
356
367
  span?: DashboardPanelSpan;
357
368
  query?: string; // Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
358
369
  blocks?: DashboardTextBlock[];
@@ -368,8 +379,9 @@ type DerivedCellRoundingTarget = {
368
379
  type: EmbeddedSubFieldDef["type"];
369
380
  scale?: number;
370
381
  };
371
- type EditExtensionSection = {
382
+ type EditExtensionSection = EditSectionPresentation & {
372
383
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
384
+ 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`.
373
385
  kind: "extension";
374
386
  title: string;
375
387
  description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
@@ -387,8 +399,10 @@ type EditLayout = {
387
399
  sections: EditSectionSpec[];
388
400
  width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
389
401
  mode?: "single" | "wizard" | "tabs"; // Default "single".
402
+ narrowTabs?: false; // `false` (tabs mode): below `sm` there is no tab strip, the visible sections of every tab stand one under the other.
390
403
  variant?: "form" | "settings-list"; // "settings-list" lays each section out as a band with a title column on the left and one hairline-separated row per field (label + help left, control right) — the familiar settings pattern, for screens that are a list of independent preferences rather than one record form.
391
404
  hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
405
+ allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
392
406
  draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
393
407
  wizard?: {
394
408
  aside?: {
@@ -399,17 +413,28 @@ type EditLayout = {
399
413
  submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
400
414
  }; // Wizard layouts only.
401
415
  };
402
- type EditWriteFormSection = {
416
+ type EditStepListSection = EditSectionPresentation & { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
417
+ id?: string;
418
+ visibleWhen?: Exclude<FieldCondition, boolean>;
419
+ kind: "stepList";
420
+ title?: string;
421
+ field: string; // Output field of the detail query holding a `StepListItem[]`.
422
+ actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
423
+ };
424
+ type EditWriteFormSection = EditSectionPresentation & {
403
425
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
426
+ 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`.
404
427
  kind: "writeForm";
405
428
  title?: string;
406
429
  description?: string;
430
+ descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
407
431
  columns?: number;
408
432
  icon?: IconKey;
409
433
  fieldDefs: Readonly<Record<string, FieldDefinition>>; // Field-type map for this section's own form — same shape as `ActionFormScreenDefinition.fields`.
410
434
  fields: EditFieldSpec[]; // Rendered fields, in order — same shape as `EditFieldsSection.fields`.
411
435
  handler: string; // Write-handler QN dispatched on submit.
412
436
  submitLabel?: string; // i18n-key for the submit button.
437
+ submitWith?: string; // Id of a writeHandler action in the screen's `actions`.
413
438
  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.
414
439
  };
415
440
  type EmbeddedDerivedCellDef = ({ op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; } | { op: "inRange"; from: string[]; inside: string; outside: string; }) & { // A cell computed from other cells of the same row.
@@ -447,6 +472,31 @@ type FieldAffix =
447
472
  field: string;
448
473
  }
449
474
  ;
475
+ type FieldAiAssist = {
476
+ query: string; // Qualified query name, run with the form's context payload (the `load` id of an actionForm, else the drawer row's prefill values) plus the `params` of the active chips.
477
+ resultField: string; // Key in the query result written into the field; the value must be a string.
478
+ noteField?: string; // Key in the query result with a short note for the user (e.g. "could not rewrite, draft unchanged").
479
+ contextFields?: string[]; // Other fields of the same form whose current values are sent in the payload (under their field names).
480
+ chips?: FieldAiAssistChip[];
481
+ prompt?: {
482
+ param: string;
483
+ placeholder?: string; // i18n key of the input's placeholder.
484
+ }; // Adds an input where the user types a free instruction; it is sent under `param`.
485
+ };
486
+ type FieldAiAssistChip = { // One toggle chip: while active, its `params` are merged into the query payload.
487
+ label: string; // i18n key of the chip label.
488
+ params: Readonly<Record<string, string | number | boolean>>;
489
+ };
490
+ type FieldBadge = // Pill next to a field label: a fixed i18n `label`, or the text of another value `field`.
491
+ | {
492
+ label: string;
493
+ tone: SelectOptionTone;
494
+ }
495
+ | {
496
+ field: string;
497
+ tone: SelectOptionTone;
498
+ }
499
+ ;
450
500
  type FieldFillAction = {
451
501
  label: string; // i18n key (falls back to the literal) of the button label.
452
502
  query: string; // Qualified query name, run with the current form values picked by `params`.
@@ -455,6 +505,16 @@ type FieldFillAction = {
455
505
  };
456
506
  type FieldIconKey = "mail" | "lock" | "hash" | "search" | "user" | "phone" | "calendar" | "link" | "tag" | "building" | "globe" | "key" | "map-pin";
457
507
  type FieldRenderer = PlatformComponent | string | FormatSpec;
508
+ type FieldTextRef = // A label or help text: an i18n key, or a key whose `{placeholder}`s are filled from form values.
509
+ | string
510
+ | {
511
+ key: string;
512
+ params: Readonly<Record<string, string>>;
513
+ }
514
+ ;
515
+ type FieldValueChips = {
516
+ from: string; // Name of a field of the same form whose value is an array of numbers.
517
+ };
458
518
  type FormDerivationScreen = {
459
519
  fields: Readonly<Record<string, FormFieldDefinition>>;
460
520
  derive?: Readonly<Record<string, FormFieldDerivation>>;
@@ -508,11 +568,16 @@ type PlatformComponent = {
508
568
  react?: unknown;
509
569
  native?: unknown;
510
570
  };
571
+ type ProjectionDetailInitialTab = { // One `initialTab` rule: `tab` is a section id of the layout.
572
+ when: Exclude<FieldCondition, boolean>;
573
+ tab: string;
574
+ };
511
575
  type QualifiedContentCollection = ContentCollectionDefinition & {
512
576
  navQn: string;
513
577
  };
514
578
  type RecordBannerSpec = {
515
579
  field: string; // Holds `RecordNotice | null`; null shows no banner.
580
+ iconless?: true; // Draws the notice without the tone icon.
516
581
  actions?: RecordGuidanceAction[];
517
582
  };
518
583
  type RecordBreadcrumbItem = {
@@ -575,12 +640,15 @@ type RecordStepsSpec = {
575
640
  emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
576
641
  narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
577
642
  narrowMoreLabel?: string; // Plural base key for the toggle of the hidden rest: define `<key>.one` and `<key>.other` (the latter with `{count}`).
643
+ moreActionsLabel?: string; // i18n key of a short label before each step's further actions ("Clarify first?").
644
+ visibleWhen?: Exclude<FieldCondition, boolean>; // The whole panel is drawn only while the condition holds on the record.
578
645
  actions?: RecordGuidanceAction[];
579
646
  };
580
647
  type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
581
648
  field: string;
582
649
  toneField?: string; // Row field holding a SelectOptionTone for the sentence's accent.
583
650
  narrowField?: string; // Row field with a shorter sentence shown instead of `field` below `sm`.
651
+ icon?: IconKey; // Draws the sentence as plain text led by this icon (e.g. "sparkles" for an AI statement) instead of the bordered box.
584
652
  };
585
653
  type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
586
654
  variants?: RelatedListEmptyStateVariant[];
@@ -607,9 +675,9 @@ type RowActionClientAction = {
607
675
  style?: "primary" | "secondary" | "danger"; // Visual style.
608
676
  icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
609
677
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
610
- successMessage?: string; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`).
678
+ successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
611
679
  };
612
- type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
680
+ type RowActionDisplay = "button" | "link" | "icon" | "responsive" | "text"; // How a row action renders inline in the row-action column.
613
681
  type RowActionDrawer = {
614
682
  kind: "drawer";
615
683
  id: string;
@@ -678,6 +746,12 @@ type SecretsEditScreenDefinition = {
678
746
  access?: AccessRule;
679
747
  };
680
748
  type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
749
+ type StepListItem = { // One step of an `EditStepListSection`; `status` renders as a pill in `statusTone`.
750
+ title: string;
751
+ status?: string;
752
+ statusTone?: SelectOptionTone;
753
+ description?: string;
754
+ };
681
755
  type TextFieldDef = PiiAndFieldState & {
682
756
  type: "text";
683
757
  description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
@@ -50,7 +50,7 @@ function FileViewAction(props: { fileId: string; }): ReactNode; // "View" action
50
50
  function FloatingPanel(props: FloatingPanelProps): ReactNode; // Non-modal panel floating above the page: draggable by its header, resizable from all edges and corners, clamped to the viewport, geometry optionally remembered.
51
51
  function FormScreenShell(props: { children: ReactNode; className?: string; testId?: string; maxWidth?: FormScreenShellWidth; fillHeight?: boolean; }): ReactNode;
52
52
  function HeaderActionGroup(props: HeaderActionGroupProps): ReactNode;
53
- function HeaderActionPinned(props: { children: ReactNode; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
53
+ function HeaderActionPinned(props: { children: ReactNode; hideOnListScreens?: boolean; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
54
54
  function HtmlMailFrame(props: { html: string; title: string; allowRemoteImages: boolean; testId?: string; }): ReactNode; // Renders server-sanitized mail HTML in a script-free sandboxed iframe that grows to its content.
55
55
  function Icon(props: { name: NavIconKey; className?: string; }): ReactNode;
56
56
  function InfinityList<TData = unknown, TRow = Readonly<Record<string, unknown>>>(props: InfinityListProps<TData, TRow>): ReactNode; // Cursor-paginated scroll list (mail inbox, activity feeds) — loads the next page when the end sentinel becomes visible (IntersectionObserver), instead of a pager bar like QueryTable/entityList.
@@ -262,7 +262,7 @@ type AvatarProps = {
262
262
  type AvatarShape = "square" | "round";
263
263
  type AvatarSize = "xs" | "sm" | "md" | "lg";
264
264
  type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
265
- variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done").
265
+ variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok" | "assist"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done"), "assist" for an AI hint: soft primary surface, primary text, no border.
266
266
  inline?: boolean; // Title and text run on one line (text right behind the bold title); the text is dropped below sm, so a phone shows title and actions only.
267
267
  density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
268
268
  icon?: NavIconKey; // Icon left of the text.
@@ -378,6 +378,8 @@ type CorePrimitives = {
378
378
  MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
379
379
  RecordBreadcrumb?: ComponentType<RecordBreadcrumbProps>; // Optional — without it the detail screen renders the path as plain links.
380
380
  RecordSummary?: ComponentType<RecordSummaryProps>; // Optional — without it the summary renders as plain text.
381
+ PhotoGrid?: ComponentType<PhotoGridProps>; // Optional — without it a relatedList with `photoGrid` falls back to its table.
382
+ StepList?: ComponentType<StepListProps>; // Optional — without it a stepList section renders nothing.
381
383
  RecordSteps?: ComponentType<RecordStepsProps>; // Optional — without it the steps render as a plain card.
382
384
  ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
383
385
  SecretReveal?: ComponentType<SecretRevealProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
@@ -443,6 +445,7 @@ type DataTableProps = DataTableTableBlock & {
443
445
  columns: ListColumnViewModel[];
444
446
  rows: ListRowViewModel[];
445
447
  rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
448
+ rowMuted?: (row: ListRowViewModel) => boolean; // Draws the whole row in the muted text colour.
446
449
  onRowClick?: (row: ListRowViewModel) => void;
447
450
  sort?: DataTableSort | null; // Current sorting, or null when unsorted.
448
451
  onSortChange?: (next: DataTableSort | null) => void; // Called with the next sort state after a header click (asc → desc → null); the caller updates URL state or the query parameter and refetches.
@@ -480,6 +483,8 @@ type DataTableProps = DataTableTableBlock & {
480
483
  getCellTestId?: (row: ListRowViewModel, field: string) => string; // Overrides the cell `data-testid` (default `cell-${row.id}-${field}`).
481
484
  chromeless?: boolean; // Drops the table's own rounded/border/card background — for a host that already provides the surrounding boundary (a tab panel) and would otherwise show a card nested inside that boundary.
482
485
  scrollBody?: boolean; // Fills the available height of its flex container and scrolls rows internally instead of growing with row count — for a host that would otherwise have a long table stretch the whole page, or a short table leave dead space below it (a tab panel).
486
+ hideCountFooter?: boolean; // Drops the "n entries" footer of a `scrollBody` table (a pager stays).
487
+ plainPhoneCards?: boolean; // Phone cards as a plain feed: no sort line, the above-title meta joined with commas, the last meta line in the text colour.
483
488
  screenPadding?: boolean; // Uses the shared screen padding (wider bottom inset) instead of the table's symmetric embedded inset — for a table that IS the screen body (entityList/projectionList), so a list screen ends at the same footer distance as a form or custom screen.
484
489
  expandedRowIds?: ReadonlySet<string>; // Ids of the rows whose expansion area is currently open (controlled by the host; several rows can be open at once).
485
490
  onToggleRowExpanded?: (rowId: string) => void; // User toggled a row's expand control.
@@ -672,12 +677,14 @@ type FormProps = { // Submit wrapper.
672
677
  title: string;
673
678
  subtitle?: string;
674
679
  }; // Drawer-hosted forms: context box above the fields.
680
+ topBanner?: ReactNode; // Rendered above everything else in the form body (above `summary`), e.g. the submit error.
675
681
  sectionNav?: FormSectionNavItem[]; // Titled sections for the "on this page" navigation next to a `screenForm`.
676
682
  sideRail?: ReactNode; // Leading column next to the scroll surface of a `screenForm` (wizard step navigation).
677
683
  };
678
684
  type GridCellProps = { // Span wrapper for a child within a grid.
679
685
  span?: number;
680
686
  width?: FieldCellWidth; // Only read inside a `flow` grid.
687
+ hideOnNarrow?: boolean; // Hidden below the `sm` breakpoint.
681
688
  children: ReactNode;
682
689
  };
683
690
  type GridProps = { // Column-based layout.
@@ -688,6 +695,8 @@ type GridProps = { // Column-based layout.
688
695
  flow?: boolean; // Fields flow left to right in wrapping rows sized by `GridCell.width` instead of equal-width tracks (screen forms and drawers).
689
696
  list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
690
697
  ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
698
+ tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
699
+ facts?: boolean; // Read-only label/value facts: a true `columns`-wide grid with a tight gap, at most 2 columns below `sm`.
691
700
  };
692
701
  type HeaderActionGroupProps = {
693
702
  children: ReactNode;
@@ -1332,6 +1341,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1332
1341
  onDirtyChange?: (dirty: boolean) => void; // Fires when the form gains or loses unsaved input (field changes or a dirty extension section).
1333
1342
  onCopyLink?: () => Promise<void> | void; // Copy-link action — only set in update mode (create mode has no entity id yet, hence no permalink).
1334
1343
  actions?: RenderEditAction[]; // Header action buttons, rendered before the built-in copy-link/ delete/cancel/save controls.
1344
+ footerHint?: string; // Translated note on the left of the form footer (hidden below `sm`).
1335
1345
  menuActions?: RenderEditAction[]; // Record actions declared with `placement: "menu"`, resolved like `actions`.
1336
1346
  onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void; // Opens a relatedList section row's drawer-kind action.
1337
1347
  submitLabel?: string; // i18n key for the submit button.
@@ -1345,7 +1355,8 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1345
1355
  labelAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content inline after the label (e.g. ConfigSourceBadge).
1346
1356
  fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
1347
1357
  fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
1348
- fieldDescription?: (fieldName: string) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
1358
+ formErrorOnTop?: boolean; // Renders the form-error banner above the sections instead of below them.
1359
+ fieldDescription?: (fieldName: string, values: Readonly<Record<string, unknown>>) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
1349
1360
  rowAfterField?: (fieldName: string, state: { dirty: boolean; }) => ReactNode | undefined; // Extra full-width row drawn right after a field's cell (configEdit actions).
1350
1361
  fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
1351
1362
  markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
@@ -1357,6 +1368,13 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1357
1368
  hideActions?: boolean; // Renders the fields without RenderEdit's own action bar (save, cancel, delete, copy-link).
1358
1369
  valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
1359
1370
  hideSectionTitles?: boolean; // Suppresses every section's own title (fields-section header, relatedList Section title) AND the form's own top-level title/subtitle — for a host that already renders that label itself elsewhere (e.g. a tab strip whose label duplicates it, or a page-level header above RenderEdit).
1371
+ activeTabId?: string; // Id of the active tab of a tabbed projectionDetail; handed to the `afterForm` slot.
1372
+ recordSections?: {
1373
+ labelTitles?: true; // Section titles render as small uppercase labels without separators.
1374
+ omitFirstTitle?: true; // The first section's title is the tab label right above it and is left out.
1375
+ pageNavigation?: false; // `false` leaves out the "On this page" navigation.
1376
+ photosBeside?: true; // Fields sections and the photo-grid relatedList sit side by side from `lg` up.
1377
+ }; // Record-view look of a projectionDetail; each key is opt-in.
1360
1378
  fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
1361
1379
  leadContent?: ReactNode; // Rendered first inside the form, above the sections, in the same column and rhythm — for content that belongs to the form but is no field (e.g. the secret a confirm step refers to).
1362
1380
  submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
@@ -1433,6 +1451,8 @@ type RenderListProps = DataTableTableBlockProps & {
1433
1451
  onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed (set URL state + refetch).
1434
1452
  chromeless?: boolean; // Forwarded to `DataTableProps.chromeless` — drops the table's own card frame for a host that already provides one (relatedList in a tabs-mode section).
1435
1453
  scrollBody?: boolean; // Forwarded to `DataTableProps.scrollBody` — bounds the table height and scrolls rows internally instead of growing the page (relatedList in a tabs-mode section).
1454
+ hideCountFooter?: boolean; // Forwarded to `DataTableProps.hideCountFooter` (relatedList: the tab label already says how many).
1455
+ plainPhoneCards?: boolean; // Forwarded to `DataTableProps.plainPhoneCards` (relatedList: a history reads as a plain feed on the phone).
1436
1456
  screenPadding?: boolean; // Forwarded to `DataTableProps.screenPadding` — `true`: the table carries the shared screen padding because it is the screen body (entityList/ projectionList).
1437
1457
  expandedRowIds?: ReadonlySet<string>; // Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` / `renderExpandedRow` (entityList `expandableRow`).
1438
1458
  onToggleRowExpanded?: (rowId: string) => void;
@@ -1459,6 +1479,12 @@ type SectionProps = { // Titled group of fields.
1459
1479
  actions?: ReactNode; // Rendered top-right in the title row — never a footer.
1460
1480
  layout?: "stacked" | "settings-list"; // "settings-list": title + subtitle form a left header column and the children (field rows) the right one on `md:` and up.
1461
1481
  variant?: "default" | "destructive"; // "destructive" marks the Section as a warning/danger area (e.g. account deletion, restrict processing) — border color only, no content change.
1482
+ titleStyle?: "heading" | "label"; // "label": the title is a small uppercase muted label and the section has no separator line above it.
1483
+ hint?: {
1484
+ text: string;
1485
+ textNarrow?: string;
1486
+ testId: string;
1487
+ }; // Small muted note under the section content on `sm` and up, above it on a phone.
1462
1488
  testId?: string;
1463
1489
  icon?: IconKey; // Rendered left of the title, `text-muted-foreground`, same optical size as the title.
1464
1490
  };
@@ -1615,6 +1641,8 @@ interface TextFieldProps extends FieldBase {
1615
1641
  type TextProps = { // Semantic text.
1616
1642
  variant?: "body" | "small" | "code" | "required-mark" | "muted";
1617
1643
  decorative?: boolean; // Pure ornament (e.g. a separator glyph): hidden from assistive tech.
1644
+ concealed?: boolean; // A value the viewer may not see: drawn muted with a lock icon before it.
1645
+ narrow?: string; // Phone wording: `children` show from `sm` up, this text below it.
1618
1646
  children: ReactNode;
1619
1647
  testId?: string;
1620
1648
  };