@cosmicdrift/kumiko-framework 0.414.0 → 0.416.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/agents/api/framework-engine.md +46 -8
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +69 -4
  4. package/agents/api/renderer-web.md +27 -4
  5. package/agents/api/types.md +68 -16
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +39 -7
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/embedded.md +24 -1
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/record-detail-layout.md +113 -7
  12. package/agents/examples/signature.md +186 -0
  13. package/agents/examples/writeform-section.md +1 -0
  14. package/agents/examples.md +2 -0
  15. package/agents/features-index.md +4 -0
  16. package/agents/features.md +14 -0
  17. package/agents/widgets.md +7 -0
  18. package/dist/api/request-context-internals.d.ts +2 -0
  19. package/dist/api/request-context-scopes.js +9 -2
  20. package/dist/api/request-context.js +1 -1
  21. package/dist/api/routes.js +4 -4
  22. package/dist/api/server-event-dispatcher.js +3 -0
  23. package/dist/api/server-routes.js +2 -0
  24. package/dist/db/parent-ref-clause.js +31 -3
  25. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  26. package/dist/db/parent-ref-global-hosts.js +50 -12
  27. package/dist/db/queries/rls-boot-catalog.js +5 -6
  28. package/dist/db/queries/rls-shape.d.ts +1 -0
  29. package/dist/db/queries/rls-shape.js +21 -6
  30. package/dist/db/table-builder.js +3 -1
  31. package/dist/engine/boot-validator/boot-phases.js +5 -0
  32. package/dist/engine/boot-validator/boot-rules.d.ts +144 -9
  33. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  34. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  35. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  36. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  37. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  38. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  39. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  40. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  41. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +17 -2
  42. package/dist/engine/boot-validator/list-row-guidance-rules.js +17 -2
  43. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  44. package/dist/engine/boot-validator/list-row-guidance.js +45 -1
  45. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  46. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  47. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  48. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  49. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  50. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  51. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  52. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  53. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  54. package/dist/engine/boot-validator/query-refs.js +14 -1
  55. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  56. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  57. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  58. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  59. package/dist/engine/boot-validator/screens-actions.js +56 -16
  60. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  61. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  62. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  63. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  64. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  65. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  68. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  69. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  70. package/dist/engine/boot-validator/screens-forms.js +108 -2
  71. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  72. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  73. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  74. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  75. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  76. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  77. package/dist/engine/boot-validator/screens-lists.js +4 -1
  78. package/dist/engine/build-config-feature-schema.js +5 -35
  79. package/dist/engine/config-access-rules.d.ts +3 -0
  80. package/dist/engine/config-access-rules.js +34 -0
  81. package/dist/engine/factories.d.ts +2 -0
  82. package/dist/engine/named-filter-roles.js +6 -14
  83. package/dist/engine/project-app-schema-for-roles.js +2 -0
  84. package/dist/engine/schema-builder.js +3 -1
  85. package/dist/engine/soft-delete-cleanup.js +2 -0
  86. package/dist/errors/reasons.d.ts +1 -0
  87. package/dist/errors/reasons.js +4 -0
  88. package/dist/files/file-routes.d.ts +2 -0
  89. package/dist/files/file-routes.js +85 -22
  90. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  91. package/dist/files/foreign-tenant-file-read.js +64 -0
  92. package/dist/i18n/required-surface-keys.js +28 -7
  93. package/dist/jobs/job-runner-execution.js +3 -0
  94. package/dist/jobs/job-runner-types.d.ts +1 -0
  95. package/dist/jobs/job-runner.js +8 -0
  96. package/dist/pipeline/context-services.d.ts +1 -1
  97. package/dist/pipeline/context-services.js +1 -1
  98. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  99. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  100. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  101. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  102. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  103. package/dist/search/meilisearch-adapter-internals.js +5 -0
  104. package/dist/search/meilisearch-adapter.d.ts +1 -0
  105. package/dist/search/meilisearch-adapter.js +3 -2
  106. package/dist/ui-types/card-column-roles.d.ts +2 -0
  107. package/dist/ui-types/card-column-roles.js +15 -0
  108. package/dist/ui-types/index.d.ts +2 -2
  109. package/dist/ui-types/index.js +1 -1
  110. package/package.json +3 -3
  111. package/presets/biome-plugins/no-date-api.grit +3 -1
  112. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  113. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  114. package/presets/biome-rules.json +12 -10
  115. package/src/changes.json +99 -0
@@ -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>`).
@@ -530,6 +535,8 @@ type EditFieldSpec =
530
535
  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
536
  suffix?: FieldAffix; // Same as `prefix`, shown after the input.
532
537
  fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
538
+ 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.
539
+ valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
533
540
  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
541
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
535
542
  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.
@@ -539,6 +546,7 @@ type EditFieldSpec =
539
546
  ;
540
547
  type EditRelatedListSection = {
541
548
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
549
+ 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
550
  kind: "relatedList";
543
551
  title: string;
544
552
  readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
@@ -569,8 +577,12 @@ type EditRelatedListSection = {
569
577
  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
578
  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
579
  emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
580
+ photoGrid?: {
581
+ imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
582
+ captionField?: string; // Row field printed under the image.
583
+ }; // Draws the rows as a tile grid of images instead of a table.
572
584
  };
573
- type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
585
+ type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
574
586
  type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & { // Resolver callback shape: synchronous (on the dispatcher's hot path), per tenant.
575
587
  trialGate?: TrialGate; // Optional live-trial gate, consulted by the dispatcher feature gate ONLY when the synchronous resolver reports a feature as disabled.
576
588
  };
@@ -602,6 +614,10 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
602
614
  description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
603
615
  transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
604
616
  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.
617
+ crossTenantFileRead?: {
618
+ query: string;
619
+ reason: string;
620
+ }; // 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
621
  };
606
622
  type EntityEditScreenDefinition = {
607
623
  id: string;
@@ -628,7 +644,7 @@ type EntityEditScreenDefinition = {
628
644
  singleton?: boolean; // Default false.
629
645
  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful save (create or update).
630
646
  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>`.
647
+ fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
632
648
  actions?: EntityEditAction[]; // Record actions.
633
649
  slots?: ScreenSlots;
634
650
  access?: AccessRule;
@@ -670,10 +686,10 @@ type EntityListScreenDefinition = {
670
686
  namedFilterFacet?: NamedFilterFacetOptions; // Presentation of `namedFilters` in the toolbar; needs `namedFilters`.
671
687
  emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
672
688
  createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
673
- createPlacement?: "header" | "toolbar"; // "toolbar": from `sm` up the create button ends the filter row instead of standing in the header.
689
+ createPlacement?: "header" | "toolbar"; // "toolbar": from `md` up (below md the compact header keeps its "+") the create button ends the filter row instead of standing in the header.
674
690
  toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
675
691
  narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
676
- toolbarActionsPlacement?: "header" | "toolbar"; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
692
+ toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
677
693
  itemNounKey?: string; // i18n key of the plural noun for the list size in the phone sort line (`{count}` pluralised).
678
694
  searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
679
695
  searchable?: boolean;
@@ -858,10 +874,18 @@ interface FieldFormatRegistry {
858
874
  timeStyle?: "full" | "long" | "medium" | "short";
859
875
  timeZone?: string; // IANA zone id (e.g. "Europe/Berlin").
860
876
  };
877
+ relativeTime: {
878
+ locale?: string;
879
+ style?: "long" | "short" | "narrow";
880
+ absoluteAfterDays?: number;
881
+ withTime?: boolean;
882
+ timeZone?: string; // IANA zone id for the clock time and the day boundary.
883
+ }; // Epoch ms or ISO timestamp, shown as "5 minutes ago" at render time (a table cell does not tick).
861
884
  date: {
862
885
  locale?: string;
863
886
  dateStyle?: "full" | "long" | "medium" | "short";
864
887
  };
888
+ phone: Record<never, never>; // Telephone number shown as a `tel:` link in list cells, like a read-only `format: "phone"` field.
865
889
  boolean: {
866
890
  trueLabel?: string;
867
891
  falseLabel?: string;
@@ -1002,6 +1026,7 @@ type JobDefinition = {
1002
1026
  escapeHatch?: EscapeHatchDeclaration | undefined;
1003
1027
  tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
1004
1028
  tenantVisibleRun?: { subjectFields?: string[] | undefined; } | undefined;
1029
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler | undefined;
1005
1030
  };
1006
1031
  type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
1007
1032
  type JobEvents = Pick<HandlerEvents, "append" | "load">;
@@ -1051,13 +1076,17 @@ type ListColumnSpec =
1051
1076
  emptyPlaceholder?: false; // `false` leaves an empty cell blank instead of drawing the "—" placeholder.
1052
1077
  hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
1053
1078
  showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
1079
+ 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.
1054
1080
  hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
1055
1081
  pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
1056
1082
  width?: number; // Start width in px.
1057
1083
  minWidth?: number; // Smallest width in px the user can resize to.
1058
1084
  display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
1085
+ variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
1059
1086
  badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
1060
1087
  badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
1088
+ 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).
1089
+ pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
1061
1090
  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.
1062
1091
  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).
1063
1092
  hint?: ListColumnHint; // "To do" cell: the column's field holds a sentence, shown emphasized in the row tone; an empty value shows `emptyLabel`.
@@ -1068,12 +1097,14 @@ type ListFacetSpec =
1068
1097
  field: string;
1069
1098
  type: "select";
1070
1099
  label: string;
1100
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1071
1101
  options: { value: string; label: string; }[];
1072
1102
  }
1073
1103
  | {
1074
1104
  field: string;
1075
1105
  type: "boolean";
1076
1106
  label: string;
1107
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1077
1108
  trueLabel: string;
1078
1109
  falseLabel: string;
1079
1110
  }
@@ -1081,6 +1112,7 @@ type ListFacetSpec =
1081
1112
  field: string;
1082
1113
  type: "reference";
1083
1114
  label: string;
1115
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1084
1116
  entity: string; // Entity name (same feature) or `feature:entity` (cross-feature), same convention as `ListColumnSpec.refEntity`.
1085
1117
  labelField?: string; // Row field on the referenced entity shown as the option label (default "id").
1086
1118
  }
@@ -1178,6 +1210,7 @@ type MultiStreamProjectionDefinition = {
1178
1210
  runIn?: RunIn;
1179
1211
  delivery?: "shared" | "per-instance";
1180
1212
  startFrom?: "beginning" | "now";
1213
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
1181
1214
  };
1182
1215
  type NavDefinition = {
1183
1216
  id: string;
@@ -1390,6 +1423,9 @@ type ProjectionDetailScreenDefinition = {
1390
1423
  actions?: RowAction[]; // Header action buttons.
1391
1424
  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).
1392
1425
  inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
1426
+ footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
1427
+ footerHint?: string; // i18n key of a note on the left of the footer bar ("Changes go out with the release"); hidden below `sm`.
1428
+ 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.
1393
1429
  valueDisplay?: "form" | "text"; // How head fields render.
1394
1430
  };
1395
1431
  type ProjectionListScreenDefinition = {
@@ -1412,7 +1448,7 @@ type ProjectionListScreenDefinition = {
1412
1448
  rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
1413
1449
  bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
1414
1450
  toolbarActions?: ToolbarAction[];
1415
- toolbarActionsPlacement?: "header" | "toolbar"; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select, instead of standing in the page header.
1451
+ toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select, instead of standing in the page header.
1416
1452
  toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
1417
1453
  narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
1418
1454
  pagination?: ListPaginationMode;
@@ -1578,7 +1614,9 @@ type RoleAccessRule = {
1578
1614
  personalData?: RoleAccessPersonalData;
1579
1615
  anySignedIn?: true;
1580
1616
  };
1581
- type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
1617
+ type RowAction = (RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction) & {
1618
+ align?: "start"; // projectionDetail `footerActions` only: "start" sets the button apart on the left of the footer.
1619
+ };
1582
1620
  type RowActionWriteHandler = {
1583
1621
  kind?: "writeHandler"; // Default for RowActions without an explicitly set `kind` — backwards-compatible form.
1584
1622
  id: string; // Stable id per screen — kebab-case, unique within the action set.
@@ -20,7 +20,7 @@ function writeFailure(err: KumikoError): WriteFailure;
20
20
  ## Constants
21
21
 
22
22
  ```ts
23
- const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
23
+ const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; irreversibleOperationWithoutEntryHandler; subjectErased; fileRejected; fileViolatesBindTarget };
24
24
  const frameworkErrorHttpStatus: { validation_error; feature_disabled; access_denied; unauthenticated; not_found; conflict; version_conflict; precondition_failed; record_locked; idempotent_replay; unique_violation; unprocessable; unconfigured; internal_error; member_read_timeout; rate_limited; rate_limit_unavailable };
25
25
  ```
26
26
 
@@ -10,6 +10,7 @@ Import from `@cosmicdrift/kumiko-framework/ui-types`. Types used here but not ex
10
10
  function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown; // Recomputes every derived head field of an action form from its inputs.
11
11
  function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): string[]; // Options of a select field that are offered for the given row values, in declaration order.
12
12
  function cardColumnRoles<C extends CardRoleColumn>(columns: C[]): CardColumnRoles<C>;
13
+ function cardMetaLines<C extends CardRoleColumn>(meta: C[]): (C[])[];
13
14
  function computeDerivedCellValue(op: NumericDerivedOp, values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
14
15
  function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean; // Evaluates a declarative FieldCondition against the current row/form values.
15
16
  function findMissingConditionalRequirements(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): string[]; // Paths of fields (and embedded sub-fields) whose `requiredWhen` holds while the value is missing.
@@ -64,11 +65,13 @@ type ActionFormLoad = {
64
65
  query: string; // Query QN that returns the record.
65
66
  idParam?: string; // Payload key carrying the record id (default "id").
66
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.
67
69
  };
68
70
  type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
69
71
  screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
70
- 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".
71
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>`).
72
75
  };
73
76
  type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
74
77
  field: string; // Flat field name in the handler's success payload.
@@ -78,7 +81,7 @@ type ActionFormSuccessItems = { // Per-entry hints of the success box, read from
78
81
  field: string; // Flat field name of an array in the success payload.
79
82
  link?: ActionFormSuccessLink; // Link of each hint.
80
83
  };
81
- 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.
82
85
  idFrom?: string; // Success-payload field carrying the navigation id.
83
86
  params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
84
87
  label: string; // Link text (i18n key).
@@ -161,6 +164,7 @@ type DashboardFilterDefinition = {
161
164
  options?: { value: string; label: string; }[];
162
165
  optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
163
166
  };
167
+ 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`.
164
168
  type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
165
169
  label: string;
166
170
  moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
@@ -199,6 +203,7 @@ type DashboardMoneyParam = { // Minor units (like Money fields), formatted with
199
203
  amountMinor: number;
200
204
  currency: string;
201
205
  };
206
+ type DashboardPanelColumn = "side" | "top"; // "top" spans both columns above the main and side column, in declared order.
202
207
  type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
203
208
  type DashboardPanelEmptyState = {
204
209
  span?: DashboardPanelSpan;
@@ -208,6 +213,7 @@ type DashboardPanelEmptyState = {
208
213
  type DashboardPanelNarrow = { // Phone layout switch shared by every panel kind.
209
214
  hideOnNarrow?: true; // Leaves the panel out below the `sm` breakpoint (phone).
210
215
  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.
216
+ 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.
211
217
  };
212
218
  type DashboardPanelQueryOptions = {
213
219
  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.
@@ -253,6 +259,7 @@ type DashboardScreenDefinition = {
253
259
  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
254
260
  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
255
261
  panels: DashboardPanelDefinition[];
262
+ layout?: DashboardLayout; // Panel arrangement, see DashboardLayout.
256
263
  record?: DashboardRecordBinding; // Binds the dashboard to one record via a URL search param, see DashboardRecordBinding.
257
264
  actions?: RowAction[]; // Header actions on the bound record (writeHandler, navigate, clientAction).
258
265
  refresh?: DashboardRefresh;
@@ -352,6 +359,7 @@ type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & Dash
352
359
  kind: "text";
353
360
  id: string;
354
361
  label?: string; // Panel title (i18n key).
362
+ icon?: PlatformComponent; // Icon shown before the text blocks (resolved like `DashboardStatGroupPanel.icon`).
355
363
  span?: DashboardPanelSpan;
356
364
  query?: string; // Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
357
365
  blocks?: DashboardTextBlock[];
@@ -369,6 +377,7 @@ type DerivedCellRoundingTarget = {
369
377
  };
370
378
  type EditExtensionSection = {
371
379
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
380
+ 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`.
372
381
  kind: "extension";
373
382
  title: string;
374
383
  description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
@@ -388,6 +397,7 @@ type EditLayout = {
388
397
  mode?: "single" | "wizard" | "tabs"; // Default "single".
389
398
  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.
390
399
  hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
400
+ allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
391
401
  draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
392
402
  wizard?: {
393
403
  aside?: {
@@ -398,8 +408,17 @@ type EditLayout = {
398
408
  submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
399
409
  }; // Wizard layouts only.
400
410
  };
411
+ type EditStepListSection = { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
412
+ id?: string;
413
+ visibleWhen?: Exclude<FieldCondition, boolean>;
414
+ kind: "stepList";
415
+ title?: string;
416
+ field: string; // Output field of the detail query holding a `StepListItem[]`.
417
+ actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
418
+ };
401
419
  type EditWriteFormSection = {
402
420
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
421
+ 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`.
403
422
  kind: "writeForm";
404
423
  title?: string;
405
424
  description?: string;
@@ -427,6 +446,7 @@ type EntityListFacetConfig = {
427
446
  showCounts?: boolean; // Chips show how many rows each option matches (other facets and the search apply).
428
447
  hideEmpty?: boolean; // Chips with zero matching rows are not shown.
429
448
  extraOptions?: EntityListFacetExtraOption[];
449
+ narrowPlacement?: "behind-filter"; // "behind-filter": the facet opens behind the filter icon next to the search field instead of standing as a pill.
430
450
  };
431
451
  type FeatureSchema = {
432
452
  featureName: string;
@@ -445,6 +465,21 @@ type FieldAffix =
445
465
  field: string;
446
466
  }
447
467
  ;
468
+ type FieldAiAssist = {
469
+ 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.
470
+ resultField: string; // Key in the query result written into the field; the value must be a string.
471
+ noteField?: string; // Key in the query result with a short note for the user (e.g. "could not rewrite, draft unchanged").
472
+ contextFields?: string[]; // Other fields of the same form whose current values are sent in the payload (under their field names).
473
+ chips?: FieldAiAssistChip[];
474
+ prompt?: {
475
+ param: string;
476
+ placeholder?: string; // i18n key of the input's placeholder.
477
+ }; // Adds an input where the user types a free instruction; it is sent under `param`.
478
+ };
479
+ type FieldAiAssistChip = { // One toggle chip: while active, its `params` are merged into the query payload.
480
+ label: string; // i18n key of the chip label.
481
+ params: Readonly<Record<string, string | number | boolean>>;
482
+ };
448
483
  type FieldFillAction = {
449
484
  label: string; // i18n key (falls back to the literal) of the button label.
450
485
  query: string; // Qualified query name, run with the current form values picked by `params`.
@@ -453,6 +488,16 @@ type FieldFillAction = {
453
488
  };
454
489
  type FieldIconKey = "mail" | "lock" | "hash" | "search" | "user" | "phone" | "calendar" | "link" | "tag" | "building" | "globe" | "key" | "map-pin";
455
490
  type FieldRenderer = PlatformComponent | string | FormatSpec;
491
+ type FieldTextRef = // A label or help text: an i18n key, or a key whose `{placeholder}`s are filled from form values.
492
+ | string
493
+ | {
494
+ key: string;
495
+ params: Readonly<Record<string, string>>;
496
+ }
497
+ ;
498
+ type FieldValueChips = {
499
+ from: string; // Name of a field of the same form whose value is an array of numbers.
500
+ };
456
501
  type FormDerivationScreen = {
457
502
  fields: Readonly<Record<string, FormFieldDefinition>>;
458
503
  derive?: Readonly<Record<string, FormFieldDerivation>>;
@@ -468,6 +513,7 @@ type ListBulkAction = { // An action that runs a writeHandler row action once pe
468
513
  type ListColumnHint = {
469
514
  detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
470
515
  narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
516
+ narrowField?: string; // Row field shown as the sentence on the phone card instead of the column's own value (a shorter sentence); the table keeps the column value.
471
517
  toneField?: string; // Row field holding a SelectOptionTone; defaults to the screen's `rowToneField`.
472
518
  reasonField?: string; // Row field with a longer reason, shown behind a "Why?" toggle in the cell.
473
519
  reasonOpenField?: string; // Row field (boolean): while true, the `reasonField` text stands open as a box under the row, over the full row width, in the table view (entity/projection lists from `md` up, dashboard lists from `sm` up); the (i) stays and closes it.
@@ -480,7 +526,7 @@ type ListEmptyStateSpec = { // Replacement for the default "no rows" box of a li
480
526
  description?: string;
481
527
  action?: RowAction;
482
528
  };
483
- type ListRowDecoration = { // Computed fields for the loaded rows: one `query` call per page answer with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
529
+ type ListRowDecoration = { // Computed fields for the loaded rows: `query` calls with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
484
530
  query: string;
485
531
  params?: Readonly<Record<string, unknown>>;
486
532
  };
@@ -495,6 +541,7 @@ type ListTableSummaryRow = { // The query receives the list's current search, fi
495
541
  query: string; // Qualified query name, e.g. `feature:query:order:summary`.
496
542
  params?: Readonly<Record<string, unknown>>; // Extra payload keys merged over the list's own.
497
543
  };
544
+ type ListToolbarActionsPlacement = (typeof LIST_TOOLBAR_ACTIONS_PLACEMENTS)[number];
498
545
  type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
499
546
  type ParsedRefTarget = {
500
547
  featureName: string;
@@ -504,6 +551,10 @@ type PlatformComponent = {
504
551
  react?: unknown;
505
552
  native?: unknown;
506
553
  };
554
+ type ProjectionDetailInitialTab = { // One `initialTab` rule: `tab` is a section id of the layout.
555
+ when: Exclude<FieldCondition, boolean>;
556
+ tab: string;
557
+ };
507
558
  type QualifiedContentCollection = ContentCollectionDefinition & {
508
559
  navQn: string;
509
560
  };
@@ -525,11 +576,14 @@ type RecordHeaderSubtitlePart =
525
576
  field: string;
526
577
  navigate?: MetricNavigate;
527
578
  format?: FormatSpec; // Formats the raw field value (e.g. `timestamp`); an empty value is still dropped.
579
+ prefix?: string; // i18n key of a text before the value ("Owner "); it stays plain text, a `navigate` link covers only the value.
528
580
  }
529
581
  ;
530
582
  type RecordNotice = {
531
583
  title: string;
532
584
  text?: string;
585
+ narrowTitle?: string; // Shown instead of `title` below `sm`.
586
+ narrowText?: string; // Shown instead of `text` below `sm`.
533
587
  tone?: SelectOptionTone;
534
588
  [field: string]: unknown;
535
589
  };
@@ -552,6 +606,7 @@ type RecordProgressStep = {
552
606
  type RecordStep = {
553
607
  id: string;
554
608
  title: string;
609
+ narrowTitle?: string; // Shown instead of `title` below `sm`.
555
610
  detail?: string;
556
611
  narrowDetail?: string; // Shown instead of `detail` below `sm`.
557
612
  tone?: SelectOptionTone;
@@ -566,12 +621,16 @@ type RecordStepsSpec = {
566
621
  subtitleField?: string; // Record field with a plain-text subtitle.
567
622
  emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
568
623
  narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
624
+ narrowMoreLabel?: string; // Plural base key for the toggle of the hidden rest: define `<key>.one` and `<key>.other` (the latter with `{count}`).
625
+ moreActionsLabel?: string; // i18n key of a short label before each step's further actions ("Clarify first?").
626
+ visibleWhen?: Exclude<FieldCondition, boolean>; // The whole panel is drawn only while the condition holds on the record.
569
627
  actions?: RecordGuidanceAction[];
570
628
  };
571
629
  type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
572
630
  field: string;
573
631
  toneField?: string; // Row field holding a SelectOptionTone for the sentence's accent.
574
632
  narrowField?: string; // Row field with a shorter sentence shown instead of `field` below `sm`.
633
+ icon?: IconKey; // Draws the sentence as plain text led by this icon (e.g. "sparkles" for an AI statement) instead of the bordered box.
575
634
  };
576
635
  type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
577
636
  variants?: RelatedListEmptyStateVariant[];
@@ -598,7 +657,7 @@ type RowActionClientAction = {
598
657
  style?: "primary" | "secondary" | "danger"; // Visual style.
599
658
  icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
600
659
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
601
- successMessage?: string; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`).
660
+ successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
602
661
  };
603
662
  type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
604
663
  type RowActionDrawer = {
@@ -669,6 +728,12 @@ type SecretsEditScreenDefinition = {
669
728
  access?: AccessRule;
670
729
  };
671
730
  type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
731
+ type StepListItem = { // One step of an `EditStepListSection`; `status` renders as a pill in `statusTone`.
732
+ title: string;
733
+ status?: string;
734
+ statusTone?: SelectOptionTone;
735
+ description?: string;
736
+ };
672
737
  type TextFieldDef = PiiAndFieldState & {
673
738
  type: "text";
674
739
  description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
@@ -114,7 +114,7 @@ function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: bo
114
114
  function SidebarUser(props: SidebarUserProps): ReactNode;
115
115
  function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
116
116
  function Stack(props: StackProps): ReactNode;
117
- function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
117
+ function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; inset?: boolean; subBelow?: boolean; boardPadding?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
118
118
  function StatusBadge(props: { tone: StatusBadgeTone; dot?: boolean; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
119
119
  function StatusBarChart(props: { entries: StatusBarEntry[]; ariaLabel: string; startLabel?: string; endLabel?: string; highlightLast?: boolean; dense?: boolean; testId?: string; }): ReactNode; // Status bar strip (e.g. 90-day uptime): variable-height bars with gradient fade + tick line on top; the last entry gets a "now" accent stripe.
120
120
  function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical" | "stacked"; heading?: string; description?: string; subtitles?: (string | undefined)[]; upNext?: { heading: string; title: string; subtitle?: string; }; testId?: string; compactTestId?: string; }): ReactNode; // Wizard step overview — numbered chips with a connector line between them.
@@ -135,6 +135,7 @@ function applyTokensToCssVars(_tokens: Tokens): void; // Historically wrote toke
135
135
  function buildFileUploadFormData(input: FileUploadFormDataInput): FormData;
136
136
  function buildNavRegistrySlice(schema: FeatureSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
137
137
  function buildNavRegistrySliceForApp(app: AppSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
138
+ function clearNavCollapseState(): void; // Forgets the collapsed containers and the revealed screen; logout calls it so the next user starts expanded.
138
139
  function clearRememberedListState(): void; // Forgets all remembered list state and the identity marker.
139
140
  function cn(...inputs: ClassValue[]): string; // Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`).
140
141
  function createBrowserDraftStorage(options?: CreateBrowserDraftStorageOptions): DraftStorage; // Default DraftStorage when createKumikoApp boots without one.
@@ -195,6 +196,12 @@ function useUserRoles(): string[] | undefined;
195
196
 
196
197
  ```ts
197
198
  const BROWSER_LOCALE_STORAGE_KEY: "kumiko:locale";
199
+ const DrawnFilter: LucideIcon;
200
+ const DrawnPanel: LucideIcon;
201
+ const DrawnPencil: LucideIcon;
202
+ const DrawnSearch: LucideIcon;
203
+ const DrawnSparkles: LucideIcon;
204
+ const DrawnWand: LucideIcon;
198
205
  const DropdownMenu: FC<Primitive.DropdownMenuProps>;
199
206
  const DropdownMenuPortal: FC<Primitive.DropdownMenuPortalProps>;
200
207
  const DropdownMenuTrigger: ForwardRefExoticComponent<Primitive.DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>>;
@@ -260,6 +267,8 @@ type BannerProps = { // Banner for an inline message or page state (for example,
260
267
  density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
261
268
  icon?: NavIconKey; // Icon left of the text.
262
269
  title?: ReactNode; // Bold heading above `children`, inside the text column.
270
+ narrowTitle?: ReactNode; // Replaces `title` below sm.
271
+ narrowText?: ReactNode; // Replaces `children` below sm and stays visible there even when `inline` drops the text.
263
272
  titleTestId?: string;
264
273
  children?: ReactNode;
265
274
  parts?: { text: string; strong?: boolean; }[]; // Structured text after `children`; `strong` parts render emphasized.
@@ -369,6 +378,8 @@ type CorePrimitives = {
369
378
  MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
370
379
  RecordBreadcrumb?: ComponentType<RecordBreadcrumbProps>; // Optional — without it the detail screen renders the path as plain links.
371
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.
372
383
  RecordSteps?: ComponentType<RecordStepsProps>; // Optional — without it the steps render as a plain card.
373
384
  ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
374
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.
@@ -679,6 +690,7 @@ type GridProps = { // Column-based layout.
679
690
  flow?: boolean; // Fields flow left to right in wrapping rows sized by `GridCell.width` instead of equal-width tracks (screen forms and drawers).
680
691
  list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
681
692
  ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
693
+ tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
682
694
  };
683
695
  type HeaderActionGroupProps = {
684
696
  children: ReactNode;
@@ -1323,6 +1335,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1323
1335
  onDirtyChange?: (dirty: boolean) => void; // Fires when the form gains or loses unsaved input (field changes or a dirty extension section).
1324
1336
  onCopyLink?: () => Promise<void> | void; // Copy-link action — only set in update mode (create mode has no entity id yet, hence no permalink).
1325
1337
  actions?: RenderEditAction[]; // Header action buttons, rendered before the built-in copy-link/ delete/cancel/save controls.
1338
+ footerHint?: string; // Translated note on the left of the form footer (hidden below `sm`).
1326
1339
  menuActions?: RenderEditAction[]; // Record actions declared with `placement: "menu"`, resolved like `actions`.
1327
1340
  onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void; // Opens a relatedList section row's drawer-kind action.
1328
1341
  submitLabel?: string; // i18n key for the submit button.
@@ -1336,7 +1349,8 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1336
1349
  labelAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content inline after the label (e.g. ConfigSourceBadge).
1337
1350
  fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
1338
1351
  fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
1339
- fieldDescription?: (fieldName: string) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
1352
+ formErrorOnTop?: boolean; // Renders the form-error banner above the sections instead of below them.
1353
+ fieldDescription?: (fieldName: string, values: Readonly<Record<string, unknown>>) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
1340
1354
  rowAfterField?: (fieldName: string, state: { dirty: boolean; }) => ReactNode | undefined; // Extra full-width row drawn right after a field's cell (configEdit actions).
1341
1355
  fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
1342
1356
  markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
@@ -1348,6 +1362,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1348
1362
  hideActions?: boolean; // Renders the fields without RenderEdit's own action bar (save, cancel, delete, copy-link).
1349
1363
  valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
1350
1364
  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).
1365
+ activeTabId?: string; // Id of the active tab of a tabbed projectionDetail; handed to the `afterForm` slot.
1351
1366
  fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
1352
1367
  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).
1353
1368
  submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
@@ -1547,11 +1562,12 @@ type StepListProps = {
1547
1562
  }; // Badge next to the title, e.g. "Erledigt" for a finished list.
1548
1563
  steps: StepListItem[];
1549
1564
  footerActions?: StepAction[]; // Footer row: a ghost action for the whole list next to the primary next-step action.
1565
+ footerNote?: string; // Quiet line under the footer actions, e.g. "Nothing is saved without you."
1550
1566
  collapsedAfter?: number; // Show only the first n steps plus "und k weitere Schritte" (expands on click).
1551
1567
  collapseWhen?: "always" | "overflow"; // "always" (default) folds after `collapsedAfter`; "overflow" folds a `fill` list only when its steps do not fit its height, then shows as many as fit but at least `collapsedAfter`.
1552
1568
  surface?: "ai" | "plain"; // "ai" (default) = AiSurface background, "plain" = no background.
1553
1569
  fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
1554
- progress?: "full" | "count" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "none" = neither, e.g. when `status` already says the list is done.
1570
+ progress?: "full" | "count" | "total" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "total" = only "n steps" (rejected ones left out), "none" = neither, e.g. when `status` already says the list is done.
1555
1571
  emptyContent?: ReactNode;
1556
1572
  selection?: StepListSelection; // Adds a checkbox per selectable step, a select-all row and selection footer actions.
1557
1573
  phoneCard?: boolean; // On a phone the list reads as a card: the header sits inside the surface and the steps in a framed white box.
@@ -1561,6 +1577,7 @@ type StepListSelection = {
1561
1577
  selectedIds: string[]; // Explicitly chosen step ids (controlled); prerequisites are added on top.
1562
1578
  onSelectionChange: (selectedIds: string[]) => void;
1563
1579
  actions: StepSelectionAction[]; // Replace `footerActions` while at least one step is selected.
1580
+ compact?: true; // Phone-card style: no select-all row, the actions stay visible at 0 selected (disabled unless `ignoresSelection`), a muted header and left-aligned footer.
1564
1581
  };
1565
1582
  type StepSelectability =
1566
1583
  | {
@@ -1576,7 +1593,9 @@ type StepSelectability =
1576
1593
  ;
1577
1594
  type StepSelectionAction = {
1578
1595
  id: string;
1579
- label: string; // Without a number: the list appends " (n)" with the effective selection size.
1596
+ label: string; // Without a number: the list appends " (n)" with the effective selection size (see `labelForCount`).
1597
+ labelForCount?: (count: number) => string; // Replaces the appended " (n)": the label for the effective selection size.
1598
+ ignoresSelection?: true; // No counter, never disabled by an empty selection (e.g. "Review one by one"); `onClick` still gets the selection.
1580
1599
  onClick: (stepIds: string[]) => void; // Receives the effective selection in list order, prerequisites included.
1581
1600
  variant?: "primary" | "secondary" | "ghost";
1582
1601
  disabled?: boolean;
@@ -1591,6 +1610,7 @@ type StepTag = {
1591
1610
  label: string;
1592
1611
  tone?: "accent" | "muted" | "warn" | "ok" | "bad";
1593
1612
  afterWaiting?: boolean; // A note about the step's history (e.g. just changed) reads after what it waits for.
1613
+ side?: true; // Sits in the right column of the row, above a trailing link (e.g. a risk chip over "Preview").
1594
1614
  };
1595
1615
  interface TextFieldProps extends FieldBase {
1596
1616
  value: string;
@@ -1773,6 +1793,9 @@ type WorkspaceShellProps = {
1773
1793
  focusRailNavQns?: string[]; // Top-level nav QNs the focus rail shows as tiles; the others sit behind a "More" tile that opens the full sidebar.
1774
1794
  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell.
1775
1795
  fill?: boolean; // Viewport-fit shell.
1796
+ contentSurface?: "card" | "background"; // Surface behind the screen content.
1797
+ navStyle?: ShellNavStyle; // `"plain"` renders the sidebar without leading icons while expanded (the focus rail and the collapsed rail keep them), with uppercase group labels, quiet active entries, a panel-symbol sidebar trigger and a 58px title bar.
1798
+ notificationBellPlacement?: "header" | "overflow"; // `"header"` (default) draws the notification bell in the title bar; `"overflow"` moves it into the "…" menu, which then shows on every width.
1776
1799
  children: ReactNode; // Screen content.
1777
1800
  };
1778
1801
  type WorkspaceShellUser = {