@cosmicdrift/kumiko-framework 0.413.0 → 0.414.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 (467) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +64 -13
  4. package/agents/api/framework-event-store.md +14 -0
  5. package/agents/api/framework-ui-types.md +149 -21
  6. package/agents/api/renderer-web.md +93 -9
  7. package/agents/api/testing-helpers.md +3 -2
  8. package/agents/api/testing-stack.md +3 -0
  9. package/agents/api/types.md +205 -14
  10. package/agents/api.md +7 -7
  11. package/agents/boot-rules.md +63 -9
  12. package/agents/examples/api-docs.md +2 -6
  13. package/agents/examples/auth-mfa.md +57 -10
  14. package/agents/examples/chat-channels.md +2 -0
  15. package/agents/examples/currencies-global.md +1 -0
  16. package/agents/examples/env-composition.md +7 -11
  17. package/agents/examples/helpdesk.md +15 -8
  18. package/agents/examples/managed-pages.md +90 -1
  19. package/agents/examples/pwa-shell.md +210 -0
  20. package/agents/examples/rate-limiting.md +3 -3
  21. package/agents/examples/record-detail-layout.md +1537 -67
  22. package/agents/examples/workflow-engine.md +16 -12
  23. package/agents/examples.md +1 -0
  24. package/agents/features-index.md +4 -2
  25. package/agents/features.md +22 -7
  26. package/agents/widgets.md +19 -1
  27. package/dist/api/api-constants.d.ts +1 -0
  28. package/dist/api/api-constants.js +4 -0
  29. package/dist/api/auth-middleware.js +4 -3
  30. package/dist/api/auth-routes-shared.js +2 -1
  31. package/dist/api/entity-read-access.d.ts +1 -0
  32. package/dist/api/entity-read-access.js +18 -0
  33. package/dist/api/export/export-route.d.ts +6 -1
  34. package/dist/api/export/export-route.js +27 -1
  35. package/dist/api/export/export-rows.js +19 -3
  36. package/dist/api/routes.d.ts +2 -0
  37. package/dist/api/routes.js +9 -1
  38. package/dist/api/server-extra-routes.js +2 -1
  39. package/dist/api/server-feature-http-routes.d.ts +9 -0
  40. package/dist/api/server-feature-http-routes.js +109 -0
  41. package/dist/api/server-middleware.js +2 -19
  42. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  43. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  44. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  45. package/dist/api/server-rate-limit-wiring.js +37 -0
  46. package/dist/api/server-routes.d.ts +4 -12
  47. package/dist/api/server-routes.js +12 -171
  48. package/dist/api/server-schema-route.d.ts +3 -0
  49. package/dist/api/server-schema-route.js +58 -0
  50. package/dist/api/server-wiring.js +2 -37
  51. package/dist/api/server.js +3 -1
  52. package/dist/compliance/override-schema.js +5 -5
  53. package/dist/compliance/sub-processors.js +10 -1
  54. package/dist/crypto/index.d.ts +1 -1
  55. package/dist/crypto/index.js +1 -1
  56. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  57. package/dist/crypto/pii-field-encryption.js +16 -1
  58. package/dist/db/apply-entity-event.js +4 -0
  59. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  60. package/dist/db/bun-sql-connection-codes.js +7 -0
  61. package/dist/db/collect-table-metas.js +4 -1
  62. package/dist/db/config-seed.js +1 -1
  63. package/dist/db/derived-field-sql.js +15 -13
  64. package/dist/db/derived-related-sql.d.ts +2 -2
  65. package/dist/db/derived-related-sql.js +4 -2
  66. package/dist/db/dialect.d.ts +3 -0
  67. package/dist/db/dialect.js +1 -3
  68. package/dist/db/driver-row-coercion.js +2 -2
  69. package/dist/db/driver-value-preparation.js +1 -1
  70. package/dist/db/eagerload.js +15 -12
  71. package/dist/db/entity-table-meta.d.ts +2 -0
  72. package/dist/db/entity-table-meta.js +7 -0
  73. package/dist/db/event-store-executor-context.js +13 -8
  74. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  75. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  76. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  77. package/dist/db/event-store-executor-read-filter.js +28 -11
  78. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  79. package/dist/db/event-store-executor-read-search.js +6 -6
  80. package/dist/db/event-store-executor-read-sort.js +3 -3
  81. package/dist/db/event-store-executor-read-where.js +14 -5
  82. package/dist/db/event-store-executor-read.js +7 -7
  83. package/dist/db/event-store-executor-write.js +50 -95
  84. package/dist/db/executor-managed-tables.js +4 -1
  85. package/dist/db/index.d.ts +4 -2
  86. package/dist/db/index.js +4 -2
  87. package/dist/db/known-table-names.d.ts +1 -0
  88. package/dist/db/known-table-names.js +7 -5
  89. package/dist/db/list-aggregate-labels.d.ts +1 -0
  90. package/dist/db/list-aggregate-labels.js +9 -1
  91. package/dist/db/migrate-generator.js +23 -4
  92. package/dist/db/migrate-rls-diff.d.ts +1 -0
  93. package/dist/db/migrate-rls-diff.js +15 -1
  94. package/dist/db/migrate-runner.js +2 -2
  95. package/dist/db/money.d.ts +1 -1
  96. package/dist/db/money.js +1 -4
  97. package/dist/db/parent-ref-clause.d.ts +6 -2
  98. package/dist/db/parent-ref-clause.js +76 -23
  99. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  100. package/dist/db/parent-ref-global-hosts.js +47 -0
  101. package/dist/db/production-schema-command-hint.d.ts +1 -0
  102. package/dist/db/production-schema-command-hint.js +3 -0
  103. package/dist/db/queries/backfill-pii.js +55 -29
  104. package/dist/db/queries/ddl.js +13 -2
  105. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  106. package/dist/db/queries/event-store-open-streams.js +33 -0
  107. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  108. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  109. package/dist/db/queries/event-store.js +0 -1
  110. package/dist/db/queries/raw-sql.js +0 -1
  111. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  112. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  113. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  114. package/dist/db/queries/rls-boot-catalog.js +13 -8
  115. package/dist/db/queries/rls-shape.d.ts +2 -1
  116. package/dist/db/queries/rls-shape.js +10 -0
  117. package/dist/db/queries/session-advisory-lock.js +2 -1
  118. package/dist/db/queries/test-stack.js +7 -7
  119. package/dist/db/query.js +16 -11
  120. package/dist/db/rebuild-marker.js +11 -2
  121. package/dist/db/render-rls-ddl.d.ts +2 -0
  122. package/dist/db/render-rls-ddl.js +16 -11
  123. package/dist/db/replay-migration-sql.js +1 -1
  124. package/dist/db/row-level-security-boot-check.js +18 -5
  125. package/dist/db/row-level-security-connection.js +25 -12
  126. package/dist/db/row-level-security-scope.d.ts +2 -1
  127. package/dist/db/row-level-security-scope.js +9 -5
  128. package/dist/db/sql-identifier.d.ts +1 -0
  129. package/dist/db/sql-identifier.js +3 -0
  130. package/dist/db/system-tenant-read-db.d.ts +5 -0
  131. package/dist/db/system-tenant-read-db.js +28 -0
  132. package/dist/db/table-builder.d.ts +3 -1
  133. package/dist/db/table-builder.js +18 -8
  134. package/dist/db/table-info.d.ts +1 -2
  135. package/dist/db/table-introspection.d.ts +3 -0
  136. package/dist/db/table-introspection.js +6 -0
  137. package/dist/db/table-push.d.ts +1 -0
  138. package/dist/db/table-push.js +7 -1
  139. package/dist/db/tenant-db-runner.d.ts +3 -0
  140. package/dist/db/tenant-db-runner.js +19 -1
  141. package/dist/db/transaction-serialization.d.ts +1 -0
  142. package/dist/db/transaction-serialization.js +20 -3
  143. package/dist/db/where-clause.js +11 -2
  144. package/dist/db/write-ownership-failures.d.ts +25 -0
  145. package/dist/db/write-ownership-failures.js +82 -0
  146. package/dist/engine/boot-validator/boot-check.js +7 -1
  147. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  148. package/dist/engine/boot-validator/boot-phases.js +3 -2
  149. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  150. package/dist/engine/boot-validator/boot-rules.js +4 -0
  151. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  152. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  153. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  154. package/dist/engine/boot-validator/config-deps.js +0 -28
  155. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  156. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  157. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  158. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  160. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  162. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  163. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  164. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  165. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  166. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  167. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  168. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  170. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  171. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  173. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  174. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  177. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  178. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  179. package/dist/engine/boot-validator/list-table-options.js +15 -1
  180. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  181. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  182. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  183. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  184. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  185. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  186. package/dist/engine/boot-validator/ownership.js +10 -1
  187. package/dist/engine/boot-validator/parent-ref.js +87 -50
  188. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  189. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  190. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  191. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  192. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  193. package/dist/engine/boot-validator/query-refs.js +24 -1
  194. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  195. package/dist/engine/boot-validator/row-decoration.js +16 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  197. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  199. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  200. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  202. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  203. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  209. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  211. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  212. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  213. package/dist/engine/boot-validator/screens-lists.js +19 -3
  214. package/dist/engine/boot-validator/screens.js +1 -1
  215. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  216. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  217. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  218. package/dist/engine/boot-validator/zod-shape.js +19 -1
  219. package/dist/engine/build-app-schema.js +4 -0
  220. package/dist/engine/config-helpers.d.ts +1 -2
  221. package/dist/engine/config-helpers.js +6 -7
  222. package/dist/engine/define-feature.js +1 -0
  223. package/dist/engine/define-handler.d.ts +1 -0
  224. package/dist/engine/define-handler.js +4 -2
  225. package/dist/engine/definition-violations.js +2 -2
  226. package/dist/engine/entity-handlers.js +3 -8
  227. package/dist/engine/entity-list-runtime-options.js +9 -8
  228. package/dist/engine/factories.d.ts +2 -0
  229. package/dist/engine/feature-config-events-jobs.js +1 -0
  230. package/dist/engine/feature-entity-handlers.js +5 -2
  231. package/dist/engine/field-access.d.ts +1 -1
  232. package/dist/engine/field-access.js +7 -10
  233. package/dist/engine/find-entity.js +3 -3
  234. package/dist/engine/form-derivations.js +3 -3
  235. package/dist/engine/index.d.ts +3 -3
  236. package/dist/engine/index.js +2 -2
  237. package/dist/engine/named-filter-roles.d.ts +3 -0
  238. package/dist/engine/named-filter-roles.js +23 -0
  239. package/dist/engine/pipeline.js +0 -1
  240. package/dist/engine/project-app-schema-for-roles.js +17 -2
  241. package/dist/engine/qualified-name.js +0 -1
  242. package/dist/engine/registry-facade.js +1 -2
  243. package/dist/engine/registry-state.d.ts +1 -1
  244. package/dist/engine/registry-state.js +5 -2
  245. package/dist/engine/registry-validate.d.ts +1 -0
  246. package/dist/engine/registry-validate.js +9 -1
  247. package/dist/engine/registry.js +2 -1
  248. package/dist/engine/resolve-named-list-filters.js +5 -2
  249. package/dist/engine/schema-builder.js +6 -10
  250. package/dist/engine/screen-helpers.d.ts +12 -0
  251. package/dist/engine/screen-helpers.js +17 -1
  252. package/dist/engine/soft-delete-cleanup.js +5 -8
  253. package/dist/engine/state-machine.js +0 -1
  254. package/dist/engine/steps/_database-clock.d.ts +2 -0
  255. package/dist/engine/steps/_database-clock.js +6 -0
  256. package/dist/engine/steps/compute.js +1 -1
  257. package/dist/engine/steps/retry.js +5 -1
  258. package/dist/engine/steps/return.js +0 -1
  259. package/dist/engine/steps/wait-for-event.js +2 -1
  260. package/dist/engine/steps/wait.js +2 -1
  261. package/dist/engine/system-user.d.ts +2 -2
  262. package/dist/engine/system-user.js +2 -2
  263. package/dist/engine/types/handlers.d.ts +1 -1
  264. package/dist/engine/types/handlers.js +1 -1
  265. package/dist/engine/types/screen.d.ts +1 -1
  266. package/dist/engine/types/screen.js +1 -1
  267. package/dist/engine/webhook-contracts.d.ts +2 -3
  268. package/dist/engine/webhook-contracts.js +2 -25
  269. package/dist/engine/webhook-events.js +48 -29
  270. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  271. package/dist/engine/webhook-payload-strictness.js +53 -0
  272. package/dist/env/_zod-introspect.d.ts +1 -0
  273. package/dist/env/dry-run.d.ts +1 -1
  274. package/dist/env/dry-run.js +1 -1
  275. package/dist/env/field-meta.d.ts +4 -0
  276. package/dist/env/field-meta.js +67 -0
  277. package/dist/env/field-rules.d.ts +9 -0
  278. package/dist/env/field-rules.js +46 -0
  279. package/dist/env/index.d.ts +3 -3
  280. package/dist/env/index.js +16 -71
  281. package/dist/env/internals.d.ts +3 -0
  282. package/dist/env/internals.js +1 -2
  283. package/dist/env/required-env.d.ts +3 -1
  284. package/dist/env/required-env.js +5 -2
  285. package/dist/errors/serialize.js +2 -2
  286. package/dist/errors/write-error-info.js +0 -2
  287. package/dist/es-ops/operations-schema.js +18 -7
  288. package/dist/event-store/admin-api.js +3 -3
  289. package/dist/event-store/event-store.js +0 -3
  290. package/dist/event-store/index.d.ts +1 -0
  291. package/dist/event-store/index.js +1 -0
  292. package/dist/event-store/transfer.js +1 -1
  293. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  294. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  295. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  296. package/dist/files/bind-pending-file-refs.js +54 -27
  297. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  298. package/dist/files/create-file-ref.d.ts +4 -1
  299. package/dist/files/create-file-ref.js +14 -3
  300. package/dist/files/default-file-guard.js +4 -1
  301. package/dist/files/feature.js +1 -0
  302. package/dist/files/file-claim.d.ts +6 -0
  303. package/dist/files/file-claim.js +17 -0
  304. package/dist/files/file-field-slots.d.ts +2 -0
  305. package/dist/files/file-field-slots.js +28 -0
  306. package/dist/files/file-ref-entity.d.ts +3 -0
  307. package/dist/files/file-ref-entity.js +2 -0
  308. package/dist/files/file-ref-table.d.ts +3 -0
  309. package/dist/files/file-routes.d.ts +4 -1
  310. package/dist/files/file-routes.js +80 -16
  311. package/dist/files/in-memory-provider.d.ts +1 -1
  312. package/dist/files/in-memory-provider.js +2 -1
  313. package/dist/files/index.d.ts +1 -1
  314. package/dist/files/index.js +1 -1
  315. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  316. package/dist/files/invalid-file-ref-error.js +15 -0
  317. package/dist/files/local-provider.js +9 -2
  318. package/dist/files/provider-resolver.js +1 -1
  319. package/dist/files/rebind-file-ref.d.ts +3 -2
  320. package/dist/files/rebind-file-ref.js +24 -18
  321. package/dist/files/resolve-file-handles.d.ts +13 -0
  322. package/dist/files/resolve-file-handles.js +57 -0
  323. package/dist/files/storage-tracking.d.ts +1 -1
  324. package/dist/files/storage-tracking.js +5 -2
  325. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  326. package/dist/files/types.d.ts +4 -0
  327. package/dist/files/types.js +10 -0
  328. package/dist/files/upload-field-resolution.d.ts +1 -0
  329. package/dist/files/upload-field-resolution.js +16 -2
  330. package/dist/files/upload-ledger.js +1 -1
  331. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  332. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  333. package/dist/i18n/required-surface-keys.js +19 -4
  334. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  335. package/dist/internal/boot-rule-table-expectations.js +29 -0
  336. package/dist/internal/row-level-security.d.ts +1 -0
  337. package/dist/internal/row-level-security.js +1 -0
  338. package/dist/internal/testing.d.ts +1 -0
  339. package/dist/internal/testing.js +1 -0
  340. package/dist/jobs/index.d.ts +1 -0
  341. package/dist/jobs/index.js +1 -0
  342. package/dist/jobs/job-load-events.d.ts +10 -0
  343. package/dist/jobs/job-load-events.js +12 -0
  344. package/dist/jobs/job-runner-context.js +6 -158
  345. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  346. package/dist/jobs/job-runner-dispatch.js +57 -0
  347. package/dist/jobs/job-runner-event-triggers.js +18 -9
  348. package/dist/jobs/job-runner-execution.js +2 -2
  349. package/dist/jobs/job-runner-facets.d.ts +48 -0
  350. package/dist/jobs/job-runner-facets.js +156 -0
  351. package/dist/jobs/job-runner-gates.js +24 -12
  352. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  353. package/dist/jobs/job-runner-helpers.js +18 -3
  354. package/dist/jobs/job-runner-scope.d.ts +1 -0
  355. package/dist/jobs/job-runner-scope.js +2 -0
  356. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  357. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  358. package/dist/jobs/job-runner.js +31 -70
  359. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  360. package/dist/jobs/obliterate-job-queues.js +23 -0
  361. package/dist/lifecycle/lifecycle.js +1 -1
  362. package/dist/migrations/event-header-scrub.d.ts +11 -0
  363. package/dist/migrations/event-header-scrub.js +33 -0
  364. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  365. package/dist/migrations/event-payload-scrub.js +36 -4
  366. package/dist/migrations/index.d.ts +1 -0
  367. package/dist/migrations/index.js +2 -0
  368. package/dist/migrations/kumiko-drift.d.ts +5 -2
  369. package/dist/migrations/kumiko-drift.js +51 -14
  370. package/dist/migrations/pending-rebuilds.js +4 -5
  371. package/dist/observability/sensitive-filter.js +0 -12
  372. package/dist/pipeline/aggregate-type-removal.js +17 -4
  373. package/dist/pipeline/context-services.d.ts +2 -0
  374. package/dist/pipeline/context-services.js +5 -2
  375. package/dist/pipeline/dispatch-batch.js +4 -3
  376. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  377. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  378. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  379. package/dist/pipeline/dispatch-nested-write.js +119 -0
  380. package/dist/pipeline/dispatch-query.js +10 -3
  381. package/dist/pipeline/dispatch-scope.js +4 -3
  382. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  383. package/dist/pipeline/dispatch-shared.js +6 -38
  384. package/dist/pipeline/dispatch-write.d.ts +0 -1
  385. package/dist/pipeline/dispatch-write.js +3 -302
  386. package/dist/pipeline/dispatcher-utils.js +6 -0
  387. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  388. package/dist/pipeline/effective-system-scope.js +22 -0
  389. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  390. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  391. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  392. package/dist/pipeline/event-dispatcher.js +6 -7
  393. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  394. package/dist/pipeline/handler-context-auth.js +3 -4
  395. package/dist/pipeline/handler-context-db.js +11 -4
  396. package/dist/pipeline/handler-context-dispatch.js +2 -2
  397. package/dist/pipeline/handler-context-events.d.ts +8 -3
  398. package/dist/pipeline/handler-context-events.js +20 -65
  399. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  400. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  401. package/dist/pipeline/handler-context-notify.js +2 -0
  402. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  403. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  404. package/dist/pipeline/handler-context-projection.js +39 -0
  405. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  406. package/dist/pipeline/handler-context-scope.js +14 -2
  407. package/dist/pipeline/index.d.ts +1 -1
  408. package/dist/pipeline/index.js +1 -1
  409. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  410. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  411. package/dist/pipeline/member-reader.js +4 -2
  412. package/dist/pipeline/msp-rebuild.js +1 -1
  413. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  414. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  415. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  416. package/dist/pipeline/projection-rebuild.js +16 -7
  417. package/dist/pipeline/projection-state.js +4 -6
  418. package/dist/pipeline/system-hooks.js +36 -6
  419. package/dist/pipeline/write-result-masking.js +31 -3
  420. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  421. package/dist/pipeline/write-transition-guard.js +95 -0
  422. package/dist/schema-cli/shared.d.ts +2 -0
  423. package/dist/schema-cli/shared.js +4 -2
  424. package/dist/schema-cli/validate-command.js +43 -28
  425. package/dist/search/meilisearch-adapter.js +14 -9
  426. package/dist/search/reindex-entity.d.ts +2 -0
  427. package/dist/search/reindex-entity.js +32 -4
  428. package/dist/search/reindex-tenants-search.js +20 -4
  429. package/dist/time/tz-context.js +1 -1
  430. package/dist/ui-types/card-column-roles.d.ts +4 -0
  431. package/dist/ui-types/card-column-roles.js +6 -3
  432. package/dist/ui-types/index.d.ts +2 -2
  433. package/dist/ui-types/index.js +1 -1
  434. package/dist/utils/ids.js +0 -1
  435. package/dist/utils/index.d.ts +1 -0
  436. package/dist/utils/index.js +1 -0
  437. package/dist/utils/return-path-limit.d.ts +1 -0
  438. package/dist/utils/return-path-limit.js +1 -0
  439. package/package.json +5 -3
  440. package/presets/biome-app.json +39 -21
  441. package/presets/biome-plugins/admin-api.grit +10 -0
  442. package/presets/biome-plugins/error-reasons.grit +53 -0
  443. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  444. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  445. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  446. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  447. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  448. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  449. package/presets/biome-plugins/no-date-api.grit +9 -0
  450. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  451. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  452. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  453. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  454. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  455. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  456. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  457. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  458. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  459. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  460. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  461. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  462. package/presets/biome-plugins/test-title.grit +20 -0
  463. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  464. package/presets/biome-rules.json +465 -0
  465. package/src/changes.json +309 -0
  466. package/dist/engine/minor-units.d.ts +0 -2
  467. package/dist/engine/minor-units.js +0 -8
@@ -23,9 +23,9 @@ function isFormatSpec(r: unknown): r is FormatSpec;
23
23
  function isMissingRequiredValue(value: unknown): boolean;
24
24
  function isRecordLocked(lockedWhen: FieldCondition | undefined, row: Readonly<Record<string, unknown>>): boolean;
25
25
  function isUiAccessGranted(access: AccessRule | undefined, userRoles: string[] | undefined): boolean;
26
- function isUnchangedValue(a: unknown, b: unknown): boolean;
27
26
  function isUnusedFallbackOperand(screen: FormDerivationScreen, values: unknown, field: string): boolean; // True when `field` is only read as a `whenEmpty` operand of `listSum` derivations whose lists all have rows: nothing reads it, so it is locked rather than inviting an input that is silently dropped.
28
27
  function isWriteFormEditSection(section: EditSectionSpec): section is EditWriteFormSection;
28
+ function pickEmptyStateText<Variant extends EmptyStateText & { when: FieldCondition; }, EmptyState extends EmptyStateText & { variants?: Variant[]; }>(emptyState: EmptyState | undefined, record: Readonly<Record<string, unknown>>): EmptyState | Variant | undefined; // Picks the first emptyState variant whose `when` matches the record, else the base emptyState.
29
29
  function resolveNavParentScreen(screens: ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
30
30
  function resolveTranslationValue(value: TranslationValue, locale: string, params?: Readonly<Record<string, unknown>>): string; // Resolve a TranslationValue to display text: a plural entry picks its CLDR category via `Intl.PluralRules` from `params.count`, falling back to `other` when `count` is missing, non-finite, or `locale` is invalid.
31
31
  function roundDerivedCellValue(value: number, target: DerivedCellRoundingTarget): number; // Rounds a derived cell's computed value to the precision its target sub-field declares — commercial rounding (round-half-away-from-zero, correct for signed minor-unit money).
@@ -116,7 +116,7 @@ type DashboardChartMarkerKind = { // Look of the markers whose `kind` matches: a
116
116
  color?: string;
117
117
  label?: string; // i18n key; with `markerLegend: "legend"` the chart legend lists the markers of this kind under it.
118
118
  };
119
- type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
119
+ type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
120
120
  kind: "chart";
121
121
  id: string;
122
122
  label: string;
@@ -146,7 +146,7 @@ type DashboardDateParam = { // Epoch ms, rendered as a medium date in the user t
146
146
  kind: "date";
147
147
  atMs: number;
148
148
  };
149
- type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
149
+ type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
150
150
  kind: "feed";
151
151
  id: string;
152
152
  label: string;
@@ -161,13 +161,39 @@ type DashboardFilterDefinition = {
161
161
  options?: { value: string; label: string; }[];
162
162
  optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
163
163
  };
164
- type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
164
+ type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
165
+ label: string;
166
+ moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
167
+ narrowMoreText?: string; // i18n key used instead of `moreText` below `sm`.
168
+ 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.
169
+ screen: string;
170
+ namedFilter?: string;
171
+ params?: Readonly<Record<string, string>>;
172
+ };
173
+ type DashboardListNarrow = { // "cards": one card per row (tone stripe; badge column and `hint.detailField` on top, the hint sentence bold, button column bottom right, `showOnNarrowOnly` columns bottom left; the button column bottom right).
174
+ limit?: number;
175
+ layout?: "cards" | "line";
176
+ field?: string; // Query output field whose value of the first row stands behind the label in the "line" layout; it need not be a column of the panel.
177
+ moreText?: string; // i18n key replacing "k more" in the "line" layout; `{count}` is the total minus the first row.
178
+ titleField?: string; // Row field replacing the card title (the hint sentence) in the "cards" layout, e.g. a shorter sentence for the phone.
179
+ };
180
+ type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
165
181
  kind: "list";
166
182
  id: string;
167
183
  label: string;
168
184
  query: string;
169
185
  columns: ListColumnSpec[];
170
- };
186
+ rowToneField?: string; // Row field holding a SelectOptionTone; tints the row and is the default tone of `hint` columns.
187
+ rowToneMarker?: DashboardListRowToneMarker; // How `rowToneField` marks a table row from `sm` up: "bar" (default) draws a stripe at the left edge, "dot" a small dot in front of the first cell.
188
+ icon?: PlatformComponent; // Icon left of the one-line phone variant (`narrow.layout: "line"`); not drawn from `sm` up.
189
+ showHeader?: boolean; // `false` drops the column header row; default true.
190
+ subtitle?: string; // i18n key, a line under `label`; with `showTotal` it stands before the count.
191
+ showTotal?: true | DashboardListShowTotal; // Adds "n of m" to the subtitle from the rows shown and the query's `total`.
192
+ footerLink?: DashboardListFooterLink; // Link under the table to the full list; with a known `total` above the rows shown, "k more" stands before it.
193
+ narrow?: DashboardListNarrow; // Phone layout below `sm`; the table stays from `sm` up.
194
+ rowLink?: DashboardListRowLink; // Makes each table row a link to a screen; a small icon at the right edge marks it.
195
+ };
196
+ type DashboardListRowToneMarker = "bar" | "dot"; // "bar": stripe at the left edge of the row.
171
197
  type DashboardMoneyParam = { // Minor units (like Money fields), formatted with the user locale.
172
198
  kind: "money";
173
199
  amountMinor: number;
@@ -179,17 +205,21 @@ type DashboardPanelEmptyState = {
179
205
  emptyLabel?: string;
180
206
  emptyHint?: string; // Second line under `emptyLabel`.
181
207
  };
208
+ type DashboardPanelNarrow = { // Phone layout switch shared by every panel kind.
209
+ hideOnNarrow?: true; // Leaves the panel out below the `sm` breakpoint (phone).
210
+ 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.
211
+ };
182
212
  type DashboardPanelQueryOptions = {
183
213
  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.
184
214
  ignoreScreenFilter?: boolean; // The screen `filter` value is NOT merged into this panel's query (a tenant picker must not hit sources without a tenant column).
185
215
  };
186
- type DashboardPanelSpan = "half" | "full";
216
+ type DashboardPanelSpan = "half" | "full" | "third" | "two-thirds";
187
217
  type DashboardPanelVisibility = {
188
218
  query: string;
189
219
  field: string;
190
220
  eq: string | number | boolean | null;
191
221
  };
192
- type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
222
+ type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
193
223
  kind: "progress-list";
194
224
  id: string;
195
225
  label: string;
@@ -229,11 +259,11 @@ type DashboardScreenDefinition = {
229
259
  filter?: DashboardFilterDefinition;
230
260
  timeRange?: DashboardTimeRangeDefinition; // Segmented control in the toolbar; the value lives in URL search param `id` and is merged into EVERY panel query (also ignoreScreenFilter ones).
231
261
  scope?: DashboardScopeDefinition; // Marks the screen as spanning more than the caller's own scope.
232
- showUpdatedAt?: boolean; // Show the "Updated at" timestamp in the toolbar.
262
+ showUpdatedAt?: boolean; // Show today's date (server clock, weekday and day, no time) in the top bar next to the title; hidden below `sm`.
233
263
  slots?: ScreenSlots;
234
264
  access?: AccessRule;
235
265
  };
236
- type DashboardScreenPanel = {
266
+ type DashboardScreenPanel = DashboardPanelNarrow & {
237
267
  kind: "screen";
238
268
  id: string;
239
269
  screen: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>`.
@@ -242,20 +272,36 @@ type DashboardScreenPanel = {
242
272
  fallback?: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` embedded in this panel's place when `visibleWhen` is unmet or its query fails (nothing while it loads).
243
273
  chromeless?: boolean; // Render the embedded form without its own card frame and padding, aligned to the dashboard's page grid like a standalone settings screen.
244
274
  };
245
- type DashboardStatGroupPanel = DashboardPanelGate & {
275
+ type DashboardStatGroupLayout = "cards" | "strip";
276
+ type DashboardStatGroupLink = { // Link at the right edge of a stat-group panel; `label` is an i18n key.
277
+ label: string;
278
+ screen: string;
279
+ params?: Readonly<Record<string, string>>;
280
+ };
281
+ type DashboardStatGroupNarrow = {
282
+ tone?: SelectOptionTone; // Tints the one-line phone strip (background and border) in this tone, e.g. "accent" for a promo-blue inbox line.
283
+ };
284
+ type DashboardStatGroupPanel = DashboardPanelGate & DashboardPanelNarrow & {
246
285
  kind: "stat-group";
247
286
  id: string;
248
287
  label?: string;
249
288
  subtitle?: string; // i18n key, a line under `label`; the boot validator requires `label`.
250
289
  span?: DashboardPanelSpan;
290
+ layout?: DashboardStatGroupLayout; // Default: "strip" without `label`, "cards" with.
291
+ icon?: PlatformComponent; // Icon left of the one-line phone strip (below `sm`); not drawn on wider screens.
292
+ link?: DashboardStatGroupLink; // Link at the right edge of the panel (label + chevron).
293
+ narrow?: DashboardStatGroupNarrow; // Phone look of the one-line strip; needs a label and layout "strip".
294
+ columns?: 2 | 3 | 4; // Tiles per row from `md` up, only with `layout: "cards"`; one column below `sm`.
251
295
  stats: DashboardStatPanel[];
252
296
  };
253
- type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
297
+ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & DashboardPanelNarrow & {
254
298
  kind: "stat";
255
299
  id: string; // Stable id: kebab-case, unique within the panel set.
256
300
  label: string; // Display text (i18n key).
257
301
  query: string;
258
302
  valueField: string;
303
+ 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.
304
+ narrowLabel?: string; // i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests").
259
305
  subField?: string;
260
306
  toneField?: string;
261
307
  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.
@@ -269,22 +315,23 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
269
315
  navigate?: {
270
316
  screen: string;
271
317
  namedFilter?: string;
318
+ params?: Readonly<Record<string, string>>; // Search params for the target list, e.g. { tab: "failed" }; merged with the namedFilter param.
272
319
  }; // Makes the tile a link to a list screen (qualified screen id).
273
320
  };
274
321
  type DashboardText = string | DashboardI18nText; // Plain string is displayed as-is; DashboardI18nText is translated by the renderer.
275
322
  type DashboardTextBlock =
276
323
  | {
277
324
  kind: "heading";
278
- text: string;
325
+ text: DashboardText;
279
326
  }
280
327
  | {
281
328
  kind: "paragraph";
282
- text: string;
283
- emphasis?: "muted" | "strong"; // Default "muted", like body copy inside panels.
329
+ text: DashboardText;
330
+ emphasis?: "muted" | "strong" | "lead"; // Default "muted", like body copy inside panels.
284
331
  }
285
332
  | {
286
333
  kind: "list";
287
- items: string[];
334
+ items: DashboardText[];
288
335
  }
289
336
  | {
290
337
  kind: "code";
@@ -292,21 +339,23 @@ type DashboardTextBlock =
292
339
  }
293
340
  | {
294
341
  kind: "hint";
295
- text: string;
342
+ text: DashboardText;
296
343
  }
297
344
  | {
298
345
  kind: "link";
299
- text: string; // Link label (i18n key).
346
+ text: DashboardText; // Link label (i18n key or DashboardI18nText).
300
347
  screen: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>`.
301
348
  roles?: string[]; // Show the link only to users holding one of these roles.
302
349
  }
303
350
  ;
304
- type DashboardTextPanel = DashboardPanelGate & {
351
+ type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & DashboardPanelNarrow & {
305
352
  kind: "text";
306
353
  id: string;
307
354
  label?: string; // Panel title (i18n key).
308
355
  span?: DashboardPanelSpan;
309
- blocks: DashboardTextBlock[];
356
+ query?: string; // Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
357
+ blocks?: DashboardTextBlock[];
358
+ narrowBlocks?: DashboardTextBlock[]; // Shown instead of `blocks` below `sm`; a query answering `{ blocks, narrowBlocks }` replaces both.
310
359
  };
311
360
  type DashboardTextParam = string | number | DashboardI18nText | DashboardMoneyParam | DashboardDateParam | DashboardRelativeTimeParam; // Nested DashboardI18nText params resolve first (e.g. a duration "{years} {months}" with one plural key each); numbers stay raw so plural rules can read `count`.
312
361
  type DashboardTimeRangeDefinition = {
@@ -416,15 +465,36 @@ type ListBulkAction = { // An action that runs a writeHandler row action once pe
416
465
  rowAction: string; // Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`.
417
466
  confirm?: string; // i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`.
418
467
  };
468
+ type ListColumnHint = {
469
+ detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
470
+ narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
471
+ toneField?: string; // Row field holding a SelectOptionTone; defaults to the screen's `rowToneField`.
472
+ reasonField?: string; // Row field with a longer reason, shown behind a "Why?" toggle in the cell.
473
+ 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.
474
+ reasonTitleField?: string; // Row field with a bold lead-in of the reason paragraph ("Rule 10 · Case open."); without it the reason has none.
475
+ emptyLabel?: string; // i18n key for an empty sentence; default `kumiko.list.hint.empty`.
476
+ plainSentence?: true; // The sentence keeps the normal text color (still bold); the tone stays on the row stripe, a badge and the detail line.
477
+ };
419
478
  type ListEmptyStateSpec = { // Replacement for the default "no rows" box of a list.
420
479
  title: string;
421
480
  description?: string;
422
481
  action?: RowAction;
423
482
  };
483
+ type ListRowDecoration = { // Computed fields for the loaded rows: one `query` call per page answer with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
484
+ query: string;
485
+ params?: Readonly<Record<string, unknown>>;
486
+ };
487
+ type ListSortOption = ListSortSpec & { // One entry of a list's "Sorted by" select; `label` is an i18n key.
488
+ label: string;
489
+ };
424
490
  type ListSortSpec = {
425
491
  field: string;
426
492
  dir: ListSortDir;
427
493
  };
494
+ type ListTableSummaryRow = { // The query receives the list's current search, filters and named filter (no paging, no sort) plus `params`, and answers `{ items: [{ label?, value, tone?, column?
495
+ query: string; // Qualified query name, e.g. `feature:query:order:summary`.
496
+ params?: Readonly<Record<string, unknown>>; // Extra payload keys merged over the list's own.
497
+ };
428
498
  type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
429
499
  type ParsedRefTarget = {
430
500
  featureName: string;
@@ -437,6 +507,18 @@ type PlatformComponent = {
437
507
  type QualifiedContentCollection = ContentCollectionDefinition & {
438
508
  navQn: string;
439
509
  };
510
+ type RecordBannerSpec = {
511
+ field: string; // Holds `RecordNotice | null`; null shows no banner.
512
+ actions?: RecordGuidanceAction[];
513
+ };
514
+ type RecordBreadcrumbItem = {
515
+ label: string;
516
+ entity?: string; // With `id`, the item links to that record's detail screen when the user may open it.
517
+ id?: string;
518
+ };
519
+ type RecordBreadcrumbSpec = { // Path above the header; `field` holds `RecordBreadcrumbItem[]`.
520
+ field: string;
521
+ };
440
522
  type RecordHeaderSubtitlePart =
441
523
  | string
442
524
  | {
@@ -445,6 +527,52 @@ type RecordHeaderSubtitlePart =
445
527
  format?: FormatSpec; // Formats the raw field value (e.g. `timestamp`); an empty value is still dropped.
446
528
  }
447
529
  ;
530
+ type RecordNotice = {
531
+ title: string;
532
+ text?: string;
533
+ tone?: SelectOptionTone;
534
+ [field: string]: unknown;
535
+ };
536
+ type RecordProgress = { // A process chain the record is part of.
537
+ title: string;
538
+ steps: RecordProgressStep[];
539
+ currentIndex: number;
540
+ };
541
+ type RecordProgressSpec = {
542
+ field: string; // Holds `RecordProgress[]`; an empty array shows no block.
543
+ placement?: "beside-steps"; // "beside-steps": the chains sit as a vertical stage list in a 4/12 column next to the steps panel (8/12) from lg, stacked below it under lg.
544
+ hideOnNarrow?: true; // Leaves the chains out below `sm`.
545
+ };
546
+ type RecordProgressStep = {
547
+ id: string;
548
+ label: string;
549
+ done: boolean;
550
+ detail?: string;
551
+ };
552
+ type RecordStep = {
553
+ id: string;
554
+ title: string;
555
+ detail?: string;
556
+ narrowDetail?: string; // Shown instead of `detail` below `sm`.
557
+ tone?: SelectOptionTone;
558
+ why?: string; // Explanation behind a toggle next to the step.
559
+ whyOpen?: true; // With `why`: the explanation stands open as a box under the step from `sm` up; the toggle closes it.
560
+ whyTitle?: string; // Bold lead-in of the `why` paragraph.
561
+ [field: string]: unknown;
562
+ };
563
+ type RecordStepsSpec = {
564
+ field: string; // Holds `RecordStep[]`.
565
+ title?: string; // i18n key, default `kumiko.detail.steps.title`.
566
+ subtitleField?: string; // Record field with a plain-text subtitle.
567
+ emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
568
+ narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
569
+ actions?: RecordGuidanceAction[];
570
+ };
571
+ type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
572
+ field: string;
573
+ toneField?: string; // Row field holding a SelectOptionTone for the sentence's accent.
574
+ narrowField?: string; // Row field with a shorter sentence shown instead of `field` below `sm`.
575
+ };
448
576
  type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
449
577
  variants?: RelatedListEmptyStateVariant[];
450
578
  };
@@ -488,7 +616,7 @@ type RowActionDrawer = {
488
616
  subtitle?: string; // Line under the drawer heading (i18n key or a bare `{name}` template), resolved like `title`.
489
617
  rowClick?: boolean; // Clicking the row opens this drawer with that row's `params`.
490
618
  };
491
- type RowActionMode = "adaptive" | "inline"; // Row-action column layout.
619
+ type RowActionMode = "adaptive" | "inline" | "menu"; // Row-action column layout.
492
620
  type RowActionNavigate = RowActionNavigateBase & ({ screen: string; entity?: never; } | { entity: string; screen?: never; }); // Exactly one of `screen` / `entity` — mutual exclusivity is type-enforced (boot validator still rejects both/neither for untyped schemas).
493
621
  type RowFieldExtractor = // Declarative row-field extractor — JSON-safe (no function prop, survives GET /api/schema / buildAppSchema).
494
622
  | {
@@ -568,4 +696,4 @@ type WorkspaceSchema = {
568
696
  };
569
697
  ```
570
698
 
571
- Also exported here, documented in `api/framework-engine.md`: `AccessRule`, `ActionFormScreenDefinition`, `ConfigEditScreenDefinition`, `DashboardCustomPanel`, `DashboardI18nText`, `EditFieldSpec`, `EditRelatedListSection`, `EditSectionSpec`, `EntityDefinition`, `EntityEditScreenDefinition`, `EntityListScreenDefinition`, `FieldCondition`, `FieldDefinition`, `ListColumnSpec`, `ListFacetSpec`, `ListTableOptions`, `MetricNavigate`, `NavDefinition`, `NavIconKey`, `ProjectionDetailScreenDefinition`, `ProjectionListScreenDefinition`, `RowAction`, `RowActionWriteHandler`, `ScreenDefinition`, `SecretMintScreenDefinition`, `TargetRef`, `ToolbarAction`, `TreeAction`, `WorkspaceDefinition`, `handlerFieldLabelKey`, `handlerTitleKey`, `isFieldsEditSection`, `isOpenToAllGranted`, `normalizeEditField`, `normalizeListColumn`, `parseRefTarget`, `sectionFieldSpecs`
699
+ Also exported here, documented in `api/framework-engine.md`: `AccessRule`, `ActionFormScreenDefinition`, `ConfigEditScreenDefinition`, `DashboardCustomPanel`, `DashboardI18nText`, `EditFieldSpec`, `EditRelatedListSection`, `EditSectionSpec`, `EntityDefinition`, `EntityEditScreenDefinition`, `EntityListScreenDefinition`, `FieldCondition`, `FieldDefinition`, `ListColumnSpec`, `ListFacetSpec`, `ListTableOptions`, `MetricNavigate`, `NavDefinition`, `NavIconKey`, `ProjectionDetailScreenDefinition`, `ProjectionListScreenDefinition`, `RowAction`, `RowActionWriteHandler`, `ScreenDefinition`, `SecretMintScreenDefinition`, `TargetRef`, `ToolbarAction`, `TreeAction`, `WorkspaceDefinition`, `handlerFieldLabelKey`, `handlerTitleKey`, `isFieldsEditSection`, `isOpenToAllGranted`, `isUnchangedValue`, `normalizeEditField`, `normalizeListColumn`, `parseRefTarget`, `sectionFieldSpecs`
@@ -33,14 +33,25 @@ function DropdownMenuContent(props: ComponentPropsWithoutRef<typeof Primitive.Co
33
33
  function DropdownMenuItem(props: ComponentPropsWithoutRef<typeof Primitive.Item>): ReactNode;
34
34
  function DropdownMenuLabel(props: ComponentPropsWithoutRef<typeof Primitive.Label>): ReactNode;
35
35
  function DropdownMenuSeparator(props: ComponentPropsWithoutRef<typeof Primitive.Separator>): ReactNode;
36
+ function EditorBody(props: { left?: ReactNode; center: ReactNode; right: ReactNode; testId?: string; }): ReactNode;
37
+ function EditorFooter(props: { testIdPrefix: string; actionTestIds?: EditorActionTestIds; message: { tone: FooterTone; text: string; } | null; pendingMessage?: string; saveError: string | null; modifiedAt: string | null; dirty: boolean; busy: boolean; canSave: boolean; canPublish?: boolean; onDiscard: () => void; onSave: () => void; saveLabel?: string; onPublish?: () => void; }): ReactNode;
38
+ function EditorFrame(props: { testId: string; children: ReactNode; }): ReactNode;
39
+ function EditorHeader(props: { title: string; status?: ReactNode; actions: EditorSaveActions; testIds?: EditorHeaderTestIds; children: ReactNode; }): ReactNode;
40
+ function EditorInfoBar(props: { tone: InfoBarTone; testId: string; origin?: ReactNode; controls?: ReactNode; links?: ReactNode; overlays?: ReactNode; children: ReactNode; }): ReactNode;
41
+ function EditorLocaleSwitch(props: { testIdPrefix: string; locales: string[]; locale: string; onLocale: (locale: string) => void; }): ReactNode;
42
+ function EditorModeSwitch(props: { testIdPrefix: string; mode: EditorMode; onMode: (mode: EditorMode) => void; }): ReactNode;
36
43
  function EditorPanel(props: EditorPanelProps): ReactNode;
44
+ function EditorWorkbench(props: EditorWorkbenchProps): ReactNode;
37
45
  function EmptyState(props: { icon?: ReactNode; title: string; description?: string; action?: ReactNode; testId?: string; }): ReactNode; // Empty state with an optional icon and CTA, using the dashed-box style of entityList empty states as a standalone widget for custom screens.
38
46
  function ErrorState(props: { error: DispatcherError; onRetry?: () => void; testId?: string; }): ReactNode; // Error state based on the Banner primitive, with a retry button.
39
47
  function FeedList(props: { rows: FeedRow[]; emptyContent?: ReactNode; testId?: string; }): ReactNode; // Non-tabular compact list (e.g. "upcoming appointments") — primary text plus an optional right-aligned trailing value for each row.
40
48
  function FileField(props: FileFieldProps): ReactNode; // File upload = Field + Input(kind:"file"|"image"), based on FileRef.
49
+ function FileViewAction(props: { fileId: string; }): ReactNode; // "View" action for a stored file: renders only for PDFs and opens the viewer in a drawer.
41
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.
42
51
  function FormScreenShell(props: { children: ReactNode; className?: string; testId?: string; maxWidth?: FormScreenShellWidth; fillHeight?: boolean; }): ReactNode;
43
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.
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.
44
55
  function Icon(props: { name: NavIconKey; className?: string; }): ReactNode;
45
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.
46
57
  function KumikoLink(props: KumikoLinkProps): ReactNode;
@@ -66,12 +77,17 @@ function PlanCard(props: PlanCardProps): ReactNode;
66
77
  function PlanGrid(props: PlanGridProps): ReactNode;
67
78
  function PresenceAvatars(props: PresenceAvatarsProps): ReactNode; // Small round avatars of the people on a row, with "+n" for the rest; for list rows.
68
79
  function PresenceNotice(props: PresenceNoticeProps): ReactNode; // One quiet line above a record: who else is on it and for how long.
80
+ function PreviewWidthFrame(props: { device: PreviewDevice; children: ReactNode; testId?: string; }): ReactNode;
69
81
  function PrimitivesProvider(props: PrimitivesProviderProps): ReactNode;
70
82
  function ProfileMenu(props: ProfileMenuProps): ReactNode;
71
83
  function ProgressBar(props: { value: number; tone?: ProgressTone; size?: "default" | "thin"; ariaLabel?: string; className?: string; testId?: string; }): ReactNode; // Progress bar, `value` 0..1 (clamped).
72
84
  function ProgressList(props: { rows: ProgressListRow[]; emptyContent?: ReactNode; testId?: string; }): ReactNode; // Label/value header and progress bar for each entry (for example, loan repayment progress).
73
85
  function PublicShell(props: PublicShellProps): ReactNode; // One header and footer for anonymous pages; `focus` narrows to a task column, `card` centers a single card (sign-in).
74
86
  function QueryTable<TData = unknown>(props: QueryTableProps<TData>): ReactNode;
87
+ function RailField(props: { children: ReactNode; }): ReactNode;
88
+ function RailHint(props: { children: ReactNode; }): ReactNode;
89
+ function RailRow(props: { symbol?: string; label: string; nameHint?: string; required?: boolean; trailing?: ReactNode; trailingTone?: keyof typeof TRAILING_TONE; action?: ReactNode; bad?: boolean; testId?: string; onPress?: () => void; }): ReactNode;
90
+ function RailSection(props: { title: string; action?: ReactNode; testId?: string; children: ReactNode; }): ReactNode;
75
91
  function RangeField(props: RangeFieldProps): ReactNode; // Slider = Field + Input(kind:"range").
76
92
  function RenderEdit<TValues extends FormValues, TCtx = unknown>(rawProps: RenderEditProps<TValues, TCtx>): ReactNode;
77
93
  function RenderField(props: RenderFieldProps): ReactNode;
@@ -82,7 +98,7 @@ function ResizablePanelGroup(props: ResizablePrimitive.GroupProps): JSX.Element;
82
98
  function ResultPanel(props: { title: string; subtitle?: string; empty?: boolean; emptyText?: ReactNode; rows?: { label: string; value: ReactNode; emphasize?: boolean; }[]; footer?: ReactNode; children?: ReactNode; testId?: string; }): ReactNode; // Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes).
83
99
  function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; compactHeader?: boolean; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
84
100
  function ScreenWidthProvider(props: { width: FormWidth | undefined; children: ReactNode; }): ReactNode;
85
- function SectionCard(props: { title: string; subtitle?: string; action?: ReactNode; footer?: ReactNode; children: ReactNode; testId?: string; }): ReactNode; // Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens.
101
+ function SectionCard(props: { title?: string; subtitle?: string; action?: ReactNode; footer?: ReactNode; children: ReactNode; testId?: string; }): ReactNode; // Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens.
86
102
  function SectionNavLayout(props: SectionNavLayoutProps): ReactNode; // Content column plus an "On this page" navigation in a right column (from xl), for custom screens.
87
103
  function SelectField(props: SelectFieldProps): ReactNode; // Select field = Field + Input(kind:"select").
88
104
  function SenderFrame(props: { children: ReactNode; label?: string; testId?: string; }): ReactNode; // Sand frame with one white sheet inside, for content that mimics a letter or mail.
@@ -98,10 +114,10 @@ function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: bo
98
114
  function SidebarUser(props: SidebarUserProps): ReactNode;
99
115
  function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
100
116
  function Stack(props: StackProps): ReactNode;
101
- 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; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
102
- function StatusBadge(props: { tone: StatusBadgeTone; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
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.
118
+ function StatusBadge(props: { tone: StatusBadgeTone; dot?: boolean; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
103
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.
104
- function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical"; 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.
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.
105
121
  function StepList(props: StepListProps): ReactNode; // Ordered plan of steps with status icons, progress header and per-step actions.
106
122
  function TextField(props: TextFieldProps): ReactNode; // Text field = Field + Input(kind:"text").
107
123
  function TextareaField(props: TextareaFieldProps): ReactNode; // Multi-line text field = Field + Input(kind:"textarea").
@@ -134,6 +150,7 @@ function filterAppSchemaNavsByAllowlist(schema: AppSchema, allowedNavQns: Readon
134
150
  function filterByAccess(workspaces: WorkspaceSchema[], userRoles: string[] | undefined): WorkspaceSchema[];
135
151
  function formatMoney(amountMinor: number, currency: string, locale?: string, fractionDigits?: number): string;
136
152
  function formatPath(target: ScreenTarget): string;
153
+ function formatRelativeWhen(value: string, now?: number): string;
137
154
  function parsePath(pathname: string, hasWorkspaces?: boolean): NavRoute | undefined;
138
155
  function parseTargetFromSearchParams(params: Readonly<Record<string, string>>): TargetRef | undefined; // Parses the current search parameters back into a TargetRef.
139
156
  function postWithDownload(dispatcher: Dispatcher, type: string, payload: unknown): Promise<DispatcherError | null>;
@@ -145,13 +162,14 @@ function saveBlobAsFile(fileName: string, blob: Blob, options?: { bom?: boolean;
145
162
  function smoothPath(pts: ReadonlyArray<{ x: number; y: number; }>): string; // Quadratic midpoint technique: smooths the zigzag line without overshoot (~5 lines instead of a Catmull-Rom/Bezier fit).
146
163
  function synthesizeActionFormEntity(fields: Readonly<Record<string, FieldDefinition>>): EntityDefinition; // Builds a minimal EntityDefinition from the inline fields of an ActionForm or SecretMint screen.
147
164
  function synthesizeActionFormScreen(screen: ActionFormScreenDefinition | SecretMintScreenDefinition): EntityEditScreenDefinition; // Converts an ActionFormScreenDefinition or SecretMintScreenDefinition to the EntityEditScreen shape expected by RenderEdit.
148
- function uploadFileRef(file: Blob, target?: FileRefTarget): Promise<string>; // Posts one file to the stack's file endpoint (double-submit CSRF) and returns the new FileRef id.
165
+ function uploadFileRef(file: Blob, target?: FileRefTarget): Promise<string>; // Posts one file to the stack's file endpoint (double-submit CSRF) and returns the new FileRef id, or the claim handle when the server issued one (anonymous uploads), which a save must submit.
149
166
  function useBrowserNavApi(options?: { hasWorkspaces?: boolean; basePath?: string; features?: FeatureSchema[]; }): NavApi; // React hook that builds a NavApi from browser history.
150
167
  function useBrowserTokensApi(): TokensApi; // Builds a TokensApi for the browser.
151
168
  function useDispatchTarget(): (target: TargetRef) => void; // Recommended production dispatch.
152
169
  function useDispatcher(): Dispatcher;
153
170
  function useDispatcherStatus(): DispatcherStatus;
154
171
  function useDraft<T extends object>(defaults: T, options?: { idPrefix?: string; }): { draft: T; patch: (changes: Partial<T>) => void; reset: () => void; field: <K extends keyof T>(name: K) => { id: string; name: string; value: T[K]; onChange: (v: T[K]) => void; }; }; // Form state for calculator screens: a draft object plus `patch` for partial updates, and `field(name)` that provides `{ id, name, value, onChange }` props ready for field widgets (NumberField/MoneyField/PercentField).
172
+ function useFileMeta(fileId: string): FileMeta | null;
155
173
  function useForm<TValues extends FormValues, TCtx = unknown>(options: UseFormOptions<TValues, TCtx>): UseFormResult<TValues>;
156
174
  function useIsNarrowViewport(): boolean;
157
175
  function useIsViewportBelow(breakpointPx: number): boolean;
@@ -237,7 +255,8 @@ type AvatarProps = {
237
255
  type AvatarShape = "square" | "round";
238
256
  type AvatarSize = "xs" | "sm" | "md" | "lg";
239
257
  type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
240
- 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, nothing left to do here").
258
+ 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").
259
+ 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.
241
260
  density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
242
261
  icon?: NavIconKey; // Icon left of the text.
243
262
  title?: ReactNode; // Bold heading above `children`, inside the text column.
@@ -276,6 +295,7 @@ type ClientFeatureDefinition = {
276
295
  navEntities?: Readonly<Record<string, string[]>>; // SSE entity lists per nav ID for live refresh of navProviders, analogous to `treeEntities`.
277
296
  navProvidersFromCollections?: (collections: QualifiedContentCollection[]) => CollectionNavProviders; // Nav providers derived from the app schema — called with every `r.contentCollection()` the app declares.
278
297
  contentEditors?: Partial<Record<ContentEditorFormat, ContentEditorComponent>>; // Content editor components — map `contentFormat` ("plain" | "document") → React component.
298
+ contentPreviews?: ContentPreviewsMap; // Preview renderers for the editor workbench's preview mode, keyed by target ("pdf" | "mail" | "web" | "text").
279
299
  resolvers?: Readonly<Record<string, ComponentType<{ target: TargetRef; onClose: () => void; }>>>; // Editor resolver components keyed by featureId:action.
280
300
  };
281
301
  type ColorTokens = {
@@ -347,6 +367,9 @@ type CorePrimitives = {
347
367
  FillContainer?: ComponentType<FillContainerProps>; // 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.
348
368
  PageHeader?: ComponentType<PageHeaderProps>; // Optional — additive rollout, see StickyActionBar.
349
369
  MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
370
+ RecordBreadcrumb?: ComponentType<RecordBreadcrumbProps>; // Optional — without it the detail screen renders the path as plain links.
371
+ RecordSummary?: ComponentType<RecordSummaryProps>; // Optional — without it the summary renders as plain text.
372
+ RecordSteps?: ComponentType<RecordStepsProps>; // Optional — without it the steps render as a plain card.
350
373
  ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
351
374
  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.
352
375
  StickyActionBar?: ComponentType<StickyActionBarProps>; // 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.
@@ -413,8 +436,10 @@ type DataTableProps = DataTableTableBlock & {
413
436
  rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
414
437
  onRowClick?: (row: ListRowViewModel) => void;
415
438
  sort?: DataTableSort | null; // Current sorting, or null when unsorted.
416
- onSortChange?: (next: DataTableSort | null) => void; // Called with the next sort state after a header click.
417
- rowActions?: DataTableRowAction[]; // Per-row actions rendered in a right-hand column as inline buttons (≤2 actions) or a kebab dropdown (>2).
439
+ 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.
440
+ sortOptions?: (DataTableSort & { label: string; })[];
441
+ toolbarSort?: true;
442
+ rowActions?: DataTableRowAction[]; // Per-row actions in a right-hand column: inline buttons (≤2) or a kebab (>2).
418
443
  rowActionMode?: DataTableRowActionMode; // How the row-action column renders: - `"adaptive"` (default): with `onRowClick` all actions except the `rowClick` one go in the kebab (no kebab or column if none remain); without it the primary action is a link button and the rest go in the kebab (a single action gets no kebab).
419
444
  bulk?: DataTableBulk; // Present: row checkboxes plus a selection bar that runs these actions once per selected row.
420
445
  emptyState?: ReactNode; // Custom empty-state content (e.g. Icon + Heading + CTA-Button).
@@ -499,9 +524,46 @@ type DrawerProps = {
499
524
  panelClassName?: string; // Extra classes for the panel, merged over the built-in ones.
500
525
  fillBody?: boolean; // The body becomes a plain flex column with no padding or scrolling of its own, for children that bring their own scroll area and pinned footer.
501
526
  };
527
+ type EditorActionTestIds = {
528
+ discard: string;
529
+ save: string;
530
+ publish: string;
531
+ };
532
+ type EditorHeaderTestIds = {
533
+ save: string;
534
+ publish: string;
535
+ };
536
+ type EditorMode = "edit" | "preview";
502
537
  type EditorPanelProps = {
503
538
  resolvers: ReadonlyMap<string, ResolverComponent>;
504
539
  };
540
+ type EditorSaveActions = {
541
+ busy: boolean;
542
+ canSave: boolean;
543
+ onSave: () => void;
544
+ saveLabel?: string; // Replaces "Save", e.g. "Create" for a record that does not exist yet.
545
+ canPublish?: boolean; // Without them the header has no publish button.
546
+ onPublish?: () => void;
547
+ };
548
+ type EditorWorkbenchProps = {
549
+ testId: string;
550
+ title: string;
551
+ status?: ReactNode;
552
+ info: {
553
+ edit: ReactNode;
554
+ preview: ReactNode;
555
+ }; // Info bar text per mode.
556
+ controls?: ReactNode; // Info bar controls shared by both modes, e.g. the locale switch.
557
+ banners?: ReactNode;
558
+ edit: ReactNode;
559
+ preview: ReactNode;
560
+ rail: {
561
+ edit: ReactNode;
562
+ preview: ReactNode;
563
+ left?: ReactNode;
564
+ }; // Right rail per mode; `left` adds a rail on the left (a placeholder list) shown in both modes.
565
+ save: WorkbenchSave;
566
+ };
505
567
  type FeedRow = {
506
568
  id: string;
507
569
  primary: string;
@@ -536,6 +598,10 @@ interface FileFieldProps extends FieldBase {
536
598
  entityType?: string; // Binds the upload to a specific entity field; the `/api/files` endpoint then validates `accept`/`maxSize` server-side against that field's definition.
537
599
  fieldName?: string;
538
600
  }
601
+ type FileMeta = {
602
+ fileName: string;
603
+ mimeType: string | undefined;
604
+ };
539
605
  type FileRefTarget = Pick<FileUploadFormDataInput, "entityType" | "entityId" | "fieldName" | "subField" | "actionForm">;
540
606
  type FloatingPanelGeometry = {
541
607
  x: number;
@@ -575,6 +641,7 @@ type FontTokens = {
575
641
  heading: string;
576
642
  mono: string;
577
643
  };
644
+ type FooterTone = "bad" | "warn" | "ok";
578
645
  type FormProps = { // Submit wrapper.
579
646
  onSubmit: (e?: FormEvent) => void;
580
647
  focusFirstErrorKey?: number; // Bumped by the host each time a submit fails on field errors; the form then moves focus to its first invalid control.
@@ -645,6 +712,7 @@ type InfinityListSelection = { // Position of the selected row among the rows lo
645
712
  nextId: string | null;
646
713
  hasMore: boolean;
647
714
  };
715
+ type InfoBarTone = "active" | "muted" | "warn";
648
716
  type InputProps =
649
717
  | {
650
718
  kind: "text";
@@ -1155,6 +1223,7 @@ type PresenceNoticeProps = {
1155
1223
  nowMs?: number; // Fixed "now" in epoch ms; without it the notice follows the clock once a minute.
1156
1224
  testId?: string;
1157
1225
  };
1226
+ type PreviewDevice = "desktop" | "mobile";
1158
1227
  type PrimitivesProviderProps = {
1159
1228
  children: ReactNode;
1160
1229
  value: PrimitivesRegistry;
@@ -1324,12 +1393,15 @@ type RenderListProps = DataTableTableBlockProps & {
1324
1393
  description?: string; // Hint at the left of the toolbar (already translated).
1325
1394
  emptyContent?: ListEmptyStateContent; // Author-declared replacement for the default empty box (already translated).
1326
1395
  narrowed?: boolean; // Search or filters changed the result; the empty box then says "no matches".
1396
+ namedFilterEmpty?: NamedFilterEmptyContent; // Empty sentence of the active named filter (already translated) with its reset; shown instead of "no matches" when no search term is set.
1327
1397
  defaultFilterActive?: boolean; // Nothing was narrowed by the user, but a default filter is still on; the empty box then offers "show all" instead of "create the first one".
1328
1398
  itemNounKey?: string; // Plural-forms key for the footer count noun; default is the entity's `:noun` convention key.
1329
1399
  searchValue?: string; // Current search term (from URL state / the parent).
1330
1400
  onSearchChange?: (next: string) => void; // Called when the debounced search term changes.
1331
1401
  sort?: ListSort | null; // Current sorting, or null for the server's default order.
1332
1402
  onSortChange?: (next: ListSort | null) => void; // Called with the next sort state after a header click.
1403
+ sortOptions?: DataTableProps["sortOptions"]; // Labelled sort choices (labels already translated) for the "Sorted by" select.
1404
+ toolbarSort?: DataTableProps["toolbarSort"];
1333
1405
  pager?: {
1334
1406
  page: number;
1335
1407
  limit: number;
@@ -1430,7 +1502,7 @@ type StatDelta = {
1430
1502
  tone?: StatTone;
1431
1503
  };
1432
1504
  type StatTone = DashboardStatTone;
1433
- type StatusBadgeTone = StatusTone | "accent"; // `accent` is a brand-colored call-out (e.g. "3 suggestions"), not a status — hence not part of `StatusTone`, which toasts and select options share.
1505
+ type StatusBadgeTone = StatusBadgeOptionTone; // `accent` is a brand tone select options can request; toasts only use `StatusTone`.
1434
1506
  type StatusBarEntry = {
1435
1507
  key: string; // Stable key (z.B.
1436
1508
  level: number; // Bar height from 0 to 1 (e.g. operational=1, degraded=0.75, outage=0.25).
@@ -1639,6 +1711,8 @@ type UploadZoneProps = {
1639
1711
  describeError?: (cause: unknown) => string; // Turns a failed upload into the row's error text.
1640
1712
  onRemove?: (value: string) => void; // Controlled use, for a form field: a string returned by `onUpload` becomes the row's value and done rows get a remove button that calls this with it.
1641
1713
  doneValues?: string[]; // The values the owner currently holds.
1714
+ trackUpload?: TrackFormUpload; // Wraps the whole per-file work, image resize included, so a surrounding form can hold back submit while the file is still being prepared.
1715
+ labelForValue?: (value: string) => ReactNode; // Row label of a value the owner already held (e.g. a FileRef id resolved to its file name).
1642
1716
  };
1643
1717
  type UseFormOptions<TValues extends FormValues, TCtx = unknown> = FormControllerOptions<TValues, TCtx>;
1644
1718
  type UseFormResult<TValues extends FormValues> = {
@@ -1679,6 +1753,16 @@ type UserRolesProviderProps = {
1679
1753
  roles: string[] | undefined;
1680
1754
  children: ReactNode;
1681
1755
  };
1756
+ type WorkbenchSave = {
1757
+ busy: boolean;
1758
+ canSave: boolean;
1759
+ dirty: boolean;
1760
+ onSave: () => void;
1761
+ saveLabel?: string;
1762
+ onDiscard: () => void;
1763
+ saveError: string | null;
1764
+ modifiedAt?: string | null;
1765
+ };
1682
1766
  type WorkspaceShellProps = {
1683
1767
  brand: ReactNode; // Branding / logo on the left side of the topbar.
1684
1768
  schema: AppSchema | FeatureSchema; // Schema with `workspaces` populated — the engine builds this from registry.getAllWorkspaces() + getWorkspaceNavs().
@@ -42,9 +42,10 @@ function resetTestTables(db: AnyDb, tables: ClearableTable[]): Promise<void>; //
42
42
  function rolesOf(access: AccessRule | undefined): string[];
43
43
  function runInRowLevelSecurityScope<T>(scope: RowLevelSecurityScope, fn: () => T): T;
44
44
  function runInSystemRowLevelSecurityScope<T>(reason: string, fn: () => T): T;
45
- function seedRow<TRow = unknown>(db: AnyDb, table: SeedTable, values: Record<string, unknown>): Promise<TRow | undefined>;
45
+ function seedRow<TRow = unknown>(db: AnyDb, table: SeedTable, values: Record<string, unknown>, options?: SeedOptions): Promise<TRow | undefined>;
46
46
  function seedRowViaEventStore(db: DbConnection, table: EventStoreWriteTarget["table"], values: Readonly<Record<string, unknown>>): Promise<void>;
47
- function seedRows<TRow = unknown>(db: AnyDb, table: SeedTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
47
+ function seedRows<TRow = unknown>(db: AnyDb, table: SeedTable, rows: ReadonlyArray<Record<string, unknown>>, options?: SeedOptions): Promise<TRow[]>;
48
+ function seedRowsViaEventStore(db: DbConnection, table: EventStoreWriteTarget["table"], rows: ReadonlyArray<Readonly<Record<string, unknown>>>): Promise<void>;
48
49
  function sleep(ms: number): Promise<unknown>;
49
50
  function tenantRowLevelSecurityScope(tenantId: TenantId): RowLevelSecurityScope;
50
51
  function terminateBackendsByApplicationName(admin: AdminClient, applicationName: string): Promise<void>;