@cosmicdrift/kumiko-framework 0.413.1 → 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 (463) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +63 -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/managed-pages.md +90 -1
  18. package/agents/examples/pwa-shell.md +210 -0
  19. package/agents/examples/rate-limiting.md +3 -3
  20. package/agents/examples/record-detail-layout.md +1537 -67
  21. package/agents/examples/workflow-engine.md +16 -12
  22. package/agents/examples.md +1 -0
  23. package/agents/features-index.md +4 -2
  24. package/agents/features.md +22 -7
  25. package/agents/widgets.md +19 -1
  26. package/dist/api/api-constants.d.ts +1 -0
  27. package/dist/api/api-constants.js +4 -0
  28. package/dist/api/auth-middleware.js +4 -3
  29. package/dist/api/auth-routes-shared.js +2 -1
  30. package/dist/api/entity-read-access.d.ts +1 -0
  31. package/dist/api/entity-read-access.js +18 -0
  32. package/dist/api/export/export-route.d.ts +6 -1
  33. package/dist/api/export/export-route.js +27 -1
  34. package/dist/api/export/export-rows.js +19 -3
  35. package/dist/api/routes.d.ts +2 -0
  36. package/dist/api/routes.js +9 -1
  37. package/dist/api/server-extra-routes.js +2 -1
  38. package/dist/api/server-feature-http-routes.d.ts +9 -0
  39. package/dist/api/server-feature-http-routes.js +109 -0
  40. package/dist/api/server-middleware.js +2 -19
  41. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  42. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  43. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  44. package/dist/api/server-rate-limit-wiring.js +37 -0
  45. package/dist/api/server-routes.d.ts +4 -12
  46. package/dist/api/server-routes.js +12 -171
  47. package/dist/api/server-schema-route.d.ts +3 -0
  48. package/dist/api/server-schema-route.js +58 -0
  49. package/dist/api/server-wiring.js +2 -37
  50. package/dist/api/server.js +3 -1
  51. package/dist/compliance/override-schema.js +5 -5
  52. package/dist/compliance/sub-processors.js +10 -1
  53. package/dist/crypto/index.d.ts +1 -1
  54. package/dist/crypto/index.js +1 -1
  55. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  56. package/dist/crypto/pii-field-encryption.js +16 -1
  57. package/dist/db/apply-entity-event.js +4 -0
  58. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  59. package/dist/db/bun-sql-connection-codes.js +7 -0
  60. package/dist/db/collect-table-metas.js +4 -1
  61. package/dist/db/config-seed.js +1 -1
  62. package/dist/db/derived-field-sql.js +15 -13
  63. package/dist/db/derived-related-sql.d.ts +2 -2
  64. package/dist/db/derived-related-sql.js +4 -2
  65. package/dist/db/dialect.d.ts +3 -0
  66. package/dist/db/dialect.js +1 -3
  67. package/dist/db/driver-row-coercion.js +2 -2
  68. package/dist/db/driver-value-preparation.js +1 -1
  69. package/dist/db/eagerload.js +15 -12
  70. package/dist/db/entity-table-meta.d.ts +2 -0
  71. package/dist/db/entity-table-meta.js +7 -0
  72. package/dist/db/event-store-executor-context.js +13 -8
  73. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  74. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  75. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  76. package/dist/db/event-store-executor-read-filter.js +28 -11
  77. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  78. package/dist/db/event-store-executor-read-search.js +6 -6
  79. package/dist/db/event-store-executor-read-sort.js +3 -3
  80. package/dist/db/event-store-executor-read-where.js +14 -5
  81. package/dist/db/event-store-executor-read.js +7 -7
  82. package/dist/db/event-store-executor-write.js +50 -95
  83. package/dist/db/executor-managed-tables.js +4 -1
  84. package/dist/db/index.d.ts +4 -2
  85. package/dist/db/index.js +4 -2
  86. package/dist/db/known-table-names.d.ts +1 -0
  87. package/dist/db/known-table-names.js +7 -5
  88. package/dist/db/list-aggregate-labels.d.ts +1 -0
  89. package/dist/db/list-aggregate-labels.js +9 -1
  90. package/dist/db/migrate-generator.js +23 -4
  91. package/dist/db/migrate-rls-diff.d.ts +1 -0
  92. package/dist/db/migrate-rls-diff.js +15 -1
  93. package/dist/db/migrate-runner.js +2 -2
  94. package/dist/db/money.d.ts +1 -1
  95. package/dist/db/money.js +1 -4
  96. package/dist/db/parent-ref-clause.d.ts +6 -2
  97. package/dist/db/parent-ref-clause.js +76 -23
  98. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  99. package/dist/db/parent-ref-global-hosts.js +47 -0
  100. package/dist/db/production-schema-command-hint.d.ts +1 -0
  101. package/dist/db/production-schema-command-hint.js +3 -0
  102. package/dist/db/queries/backfill-pii.js +55 -29
  103. package/dist/db/queries/ddl.js +13 -2
  104. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  105. package/dist/db/queries/event-store-open-streams.js +33 -0
  106. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  107. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  108. package/dist/db/queries/event-store.js +0 -1
  109. package/dist/db/queries/raw-sql.js +0 -1
  110. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  111. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  112. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  113. package/dist/db/queries/rls-boot-catalog.js +13 -8
  114. package/dist/db/queries/rls-shape.d.ts +2 -1
  115. package/dist/db/queries/rls-shape.js +10 -0
  116. package/dist/db/queries/session-advisory-lock.js +2 -1
  117. package/dist/db/queries/test-stack.js +7 -7
  118. package/dist/db/query.js +16 -11
  119. package/dist/db/rebuild-marker.js +11 -2
  120. package/dist/db/render-rls-ddl.d.ts +2 -0
  121. package/dist/db/render-rls-ddl.js +16 -11
  122. package/dist/db/replay-migration-sql.js +1 -1
  123. package/dist/db/row-level-security-boot-check.js +18 -5
  124. package/dist/db/row-level-security-connection.js +25 -12
  125. package/dist/db/row-level-security-scope.d.ts +2 -1
  126. package/dist/db/row-level-security-scope.js +9 -5
  127. package/dist/db/sql-identifier.d.ts +1 -0
  128. package/dist/db/sql-identifier.js +3 -0
  129. package/dist/db/system-tenant-read-db.d.ts +5 -0
  130. package/dist/db/system-tenant-read-db.js +28 -0
  131. package/dist/db/table-builder.d.ts +3 -1
  132. package/dist/db/table-builder.js +18 -8
  133. package/dist/db/table-info.d.ts +1 -2
  134. package/dist/db/table-introspection.d.ts +3 -0
  135. package/dist/db/table-introspection.js +6 -0
  136. package/dist/db/table-push.d.ts +1 -0
  137. package/dist/db/table-push.js +7 -1
  138. package/dist/db/tenant-db-runner.d.ts +3 -0
  139. package/dist/db/tenant-db-runner.js +19 -1
  140. package/dist/db/transaction-serialization.d.ts +1 -0
  141. package/dist/db/transaction-serialization.js +20 -3
  142. package/dist/db/where-clause.js +11 -2
  143. package/dist/db/write-ownership-failures.d.ts +25 -0
  144. package/dist/db/write-ownership-failures.js +82 -0
  145. package/dist/engine/boot-validator/boot-check.js +7 -1
  146. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  147. package/dist/engine/boot-validator/boot-phases.js +3 -2
  148. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  149. package/dist/engine/boot-validator/boot-rules.js +4 -0
  150. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  151. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  152. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  153. package/dist/engine/boot-validator/config-deps.js +0 -28
  154. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  155. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  156. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  157. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  158. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  160. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  162. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  163. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  164. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  165. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  166. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  167. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  168. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  169. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  170. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  171. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  173. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  174. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  177. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  178. package/dist/engine/boot-validator/list-table-options.js +15 -1
  179. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  180. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  181. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  182. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  183. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  184. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  185. package/dist/engine/boot-validator/ownership.js +10 -1
  186. package/dist/engine/boot-validator/parent-ref.js +87 -50
  187. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  188. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  189. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  190. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  191. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  192. package/dist/engine/boot-validator/query-refs.js +24 -1
  193. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  194. package/dist/engine/boot-validator/row-decoration.js +16 -0
  195. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  197. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  199. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  200. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  202. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  203. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  209. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  211. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  212. package/dist/engine/boot-validator/screens-lists.js +19 -3
  213. package/dist/engine/boot-validator/screens.js +1 -1
  214. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  215. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  216. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  217. package/dist/engine/boot-validator/zod-shape.js +19 -1
  218. package/dist/engine/build-app-schema.js +4 -0
  219. package/dist/engine/config-helpers.d.ts +1 -2
  220. package/dist/engine/config-helpers.js +6 -7
  221. package/dist/engine/define-feature.js +1 -0
  222. package/dist/engine/define-handler.d.ts +1 -0
  223. package/dist/engine/define-handler.js +4 -2
  224. package/dist/engine/definition-violations.js +2 -2
  225. package/dist/engine/entity-handlers.js +3 -8
  226. package/dist/engine/entity-list-runtime-options.js +9 -8
  227. package/dist/engine/factories.d.ts +2 -0
  228. package/dist/engine/feature-config-events-jobs.js +1 -0
  229. package/dist/engine/feature-entity-handlers.js +5 -2
  230. package/dist/engine/field-access.d.ts +1 -1
  231. package/dist/engine/field-access.js +7 -10
  232. package/dist/engine/find-entity.js +3 -3
  233. package/dist/engine/form-derivations.js +3 -3
  234. package/dist/engine/index.d.ts +3 -3
  235. package/dist/engine/index.js +2 -2
  236. package/dist/engine/named-filter-roles.d.ts +3 -0
  237. package/dist/engine/named-filter-roles.js +23 -0
  238. package/dist/engine/pipeline.js +0 -1
  239. package/dist/engine/project-app-schema-for-roles.js +17 -2
  240. package/dist/engine/qualified-name.js +0 -1
  241. package/dist/engine/registry-facade.js +1 -2
  242. package/dist/engine/registry-state.d.ts +1 -1
  243. package/dist/engine/registry-state.js +5 -2
  244. package/dist/engine/registry-validate.js +2 -1
  245. package/dist/engine/resolve-named-list-filters.js +5 -2
  246. package/dist/engine/schema-builder.js +6 -10
  247. package/dist/engine/screen-helpers.d.ts +12 -0
  248. package/dist/engine/screen-helpers.js +17 -1
  249. package/dist/engine/soft-delete-cleanup.js +1 -5
  250. package/dist/engine/state-machine.js +0 -1
  251. package/dist/engine/steps/_database-clock.d.ts +2 -0
  252. package/dist/engine/steps/_database-clock.js +6 -0
  253. package/dist/engine/steps/compute.js +1 -1
  254. package/dist/engine/steps/retry.js +5 -1
  255. package/dist/engine/steps/return.js +0 -1
  256. package/dist/engine/steps/wait-for-event.js +2 -1
  257. package/dist/engine/steps/wait.js +2 -1
  258. package/dist/engine/system-user.d.ts +2 -2
  259. package/dist/engine/system-user.js +2 -2
  260. package/dist/engine/types/handlers.d.ts +1 -1
  261. package/dist/engine/types/handlers.js +1 -1
  262. package/dist/engine/types/screen.d.ts +1 -1
  263. package/dist/engine/types/screen.js +1 -1
  264. package/dist/engine/webhook-contracts.d.ts +2 -3
  265. package/dist/engine/webhook-contracts.js +2 -25
  266. package/dist/engine/webhook-events.js +48 -29
  267. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  268. package/dist/engine/webhook-payload-strictness.js +53 -0
  269. package/dist/env/_zod-introspect.d.ts +1 -0
  270. package/dist/env/dry-run.d.ts +1 -1
  271. package/dist/env/dry-run.js +1 -1
  272. package/dist/env/field-meta.d.ts +4 -0
  273. package/dist/env/field-meta.js +67 -0
  274. package/dist/env/field-rules.d.ts +9 -0
  275. package/dist/env/field-rules.js +46 -0
  276. package/dist/env/index.d.ts +3 -3
  277. package/dist/env/index.js +16 -71
  278. package/dist/env/internals.d.ts +3 -0
  279. package/dist/env/internals.js +1 -2
  280. package/dist/env/required-env.d.ts +3 -1
  281. package/dist/env/required-env.js +5 -2
  282. package/dist/errors/serialize.js +2 -2
  283. package/dist/errors/write-error-info.js +0 -2
  284. package/dist/es-ops/operations-schema.js +18 -7
  285. package/dist/event-store/admin-api.js +3 -3
  286. package/dist/event-store/event-store.js +0 -3
  287. package/dist/event-store/index.d.ts +1 -0
  288. package/dist/event-store/index.js +1 -0
  289. package/dist/event-store/transfer.js +1 -1
  290. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  291. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  292. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  293. package/dist/files/bind-pending-file-refs.js +54 -27
  294. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  295. package/dist/files/create-file-ref.d.ts +4 -1
  296. package/dist/files/create-file-ref.js +14 -3
  297. package/dist/files/default-file-guard.js +4 -1
  298. package/dist/files/file-claim.d.ts +6 -0
  299. package/dist/files/file-claim.js +17 -0
  300. package/dist/files/file-field-slots.d.ts +2 -0
  301. package/dist/files/file-field-slots.js +28 -0
  302. package/dist/files/file-ref-entity.d.ts +3 -0
  303. package/dist/files/file-ref-entity.js +2 -0
  304. package/dist/files/file-ref-table.d.ts +3 -0
  305. package/dist/files/file-routes.d.ts +4 -1
  306. package/dist/files/file-routes.js +80 -16
  307. package/dist/files/in-memory-provider.d.ts +1 -1
  308. package/dist/files/in-memory-provider.js +2 -1
  309. package/dist/files/index.d.ts +1 -1
  310. package/dist/files/index.js +1 -1
  311. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  312. package/dist/files/invalid-file-ref-error.js +15 -0
  313. package/dist/files/local-provider.js +9 -2
  314. package/dist/files/provider-resolver.js +1 -1
  315. package/dist/files/rebind-file-ref.d.ts +3 -2
  316. package/dist/files/rebind-file-ref.js +24 -18
  317. package/dist/files/resolve-file-handles.d.ts +13 -0
  318. package/dist/files/resolve-file-handles.js +57 -0
  319. package/dist/files/storage-tracking.d.ts +1 -1
  320. package/dist/files/storage-tracking.js +5 -2
  321. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  322. package/dist/files/types.d.ts +4 -0
  323. package/dist/files/types.js +10 -0
  324. package/dist/files/upload-field-resolution.d.ts +1 -0
  325. package/dist/files/upload-field-resolution.js +16 -2
  326. package/dist/files/upload-ledger.js +1 -1
  327. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  328. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  329. package/dist/i18n/required-surface-keys.js +19 -4
  330. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  331. package/dist/internal/boot-rule-table-expectations.js +29 -0
  332. package/dist/internal/row-level-security.d.ts +1 -0
  333. package/dist/internal/row-level-security.js +1 -0
  334. package/dist/internal/testing.d.ts +1 -0
  335. package/dist/internal/testing.js +1 -0
  336. package/dist/jobs/index.d.ts +1 -0
  337. package/dist/jobs/index.js +1 -0
  338. package/dist/jobs/job-load-events.d.ts +10 -0
  339. package/dist/jobs/job-load-events.js +12 -0
  340. package/dist/jobs/job-runner-context.js +6 -158
  341. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  342. package/dist/jobs/job-runner-dispatch.js +57 -0
  343. package/dist/jobs/job-runner-event-triggers.js +18 -9
  344. package/dist/jobs/job-runner-execution.js +2 -2
  345. package/dist/jobs/job-runner-facets.d.ts +48 -0
  346. package/dist/jobs/job-runner-facets.js +156 -0
  347. package/dist/jobs/job-runner-gates.js +19 -11
  348. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  349. package/dist/jobs/job-runner-helpers.js +18 -3
  350. package/dist/jobs/job-runner-scope.d.ts +1 -0
  351. package/dist/jobs/job-runner-scope.js +2 -0
  352. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  353. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  354. package/dist/jobs/job-runner.js +31 -70
  355. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  356. package/dist/jobs/obliterate-job-queues.js +23 -0
  357. package/dist/lifecycle/lifecycle.js +1 -1
  358. package/dist/migrations/event-header-scrub.d.ts +11 -0
  359. package/dist/migrations/event-header-scrub.js +33 -0
  360. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  361. package/dist/migrations/event-payload-scrub.js +36 -4
  362. package/dist/migrations/index.d.ts +1 -0
  363. package/dist/migrations/index.js +2 -0
  364. package/dist/migrations/kumiko-drift.d.ts +5 -2
  365. package/dist/migrations/kumiko-drift.js +51 -14
  366. package/dist/migrations/pending-rebuilds.js +4 -5
  367. package/dist/observability/sensitive-filter.js +0 -12
  368. package/dist/pipeline/aggregate-type-removal.js +17 -4
  369. package/dist/pipeline/context-services.d.ts +2 -0
  370. package/dist/pipeline/context-services.js +5 -2
  371. package/dist/pipeline/dispatch-batch.js +4 -3
  372. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  373. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  374. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  375. package/dist/pipeline/dispatch-nested-write.js +119 -0
  376. package/dist/pipeline/dispatch-query.js +10 -3
  377. package/dist/pipeline/dispatch-scope.js +4 -3
  378. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  379. package/dist/pipeline/dispatch-shared.js +6 -38
  380. package/dist/pipeline/dispatch-write.d.ts +0 -1
  381. package/dist/pipeline/dispatch-write.js +3 -302
  382. package/dist/pipeline/dispatcher-utils.js +6 -0
  383. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  384. package/dist/pipeline/effective-system-scope.js +22 -0
  385. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  386. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  387. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  388. package/dist/pipeline/event-dispatcher.js +6 -7
  389. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  390. package/dist/pipeline/handler-context-auth.js +3 -4
  391. package/dist/pipeline/handler-context-db.js +11 -4
  392. package/dist/pipeline/handler-context-dispatch.js +2 -2
  393. package/dist/pipeline/handler-context-events.d.ts +8 -3
  394. package/dist/pipeline/handler-context-events.js +20 -65
  395. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  396. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  397. package/dist/pipeline/handler-context-notify.js +2 -0
  398. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  399. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  400. package/dist/pipeline/handler-context-projection.js +39 -0
  401. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  402. package/dist/pipeline/handler-context-scope.js +14 -2
  403. package/dist/pipeline/index.d.ts +1 -1
  404. package/dist/pipeline/index.js +1 -1
  405. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  406. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  407. package/dist/pipeline/member-reader.js +4 -2
  408. package/dist/pipeline/msp-rebuild.js +1 -1
  409. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  410. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  411. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  412. package/dist/pipeline/projection-rebuild.js +16 -7
  413. package/dist/pipeline/projection-state.js +4 -6
  414. package/dist/pipeline/system-hooks.js +36 -6
  415. package/dist/pipeline/write-result-masking.js +31 -3
  416. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  417. package/dist/pipeline/write-transition-guard.js +95 -0
  418. package/dist/schema-cli/shared.d.ts +2 -0
  419. package/dist/schema-cli/shared.js +4 -2
  420. package/dist/schema-cli/validate-command.js +43 -28
  421. package/dist/search/meilisearch-adapter.js +14 -9
  422. package/dist/search/reindex-entity.d.ts +2 -0
  423. package/dist/search/reindex-entity.js +32 -4
  424. package/dist/search/reindex-tenants-search.js +20 -4
  425. package/dist/time/tz-context.js +1 -1
  426. package/dist/ui-types/card-column-roles.d.ts +4 -0
  427. package/dist/ui-types/card-column-roles.js +6 -3
  428. package/dist/ui-types/index.d.ts +2 -2
  429. package/dist/ui-types/index.js +1 -1
  430. package/dist/utils/ids.js +0 -1
  431. package/dist/utils/index.d.ts +1 -0
  432. package/dist/utils/index.js +1 -0
  433. package/dist/utils/return-path-limit.d.ts +1 -0
  434. package/dist/utils/return-path-limit.js +1 -0
  435. package/package.json +5 -3
  436. package/presets/biome-app.json +39 -21
  437. package/presets/biome-plugins/admin-api.grit +10 -0
  438. package/presets/biome-plugins/error-reasons.grit +53 -0
  439. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  440. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  441. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  442. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  443. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  444. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  445. package/presets/biome-plugins/no-date-api.grit +9 -0
  446. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  447. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  448. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  449. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  450. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  451. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  452. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  453. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  454. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  455. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  456. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  457. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  458. package/presets/biome-plugins/test-title.grit +20 -0
  459. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  460. package/presets/biome-rules.json +465 -0
  461. package/src/changes.json +309 -0
  462. package/dist/engine/minor-units.d.ts +0 -2
  463. package/dist/engine/minor-units.js +0 -8
@@ -18,6 +18,39 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
18
18
  - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
19
19
  and one `fields` tab (master data) — each `relatedList` runs its own query
20
20
  - a header action with `showOnTabs: ["payments"]`, shown only while that tab is active
21
+ - guidance for a non-expert reader: a `projectionList` with `rowToneField` (row tint),
22
+ a `hint` column (sentence, detail, tone, "Why?" reason) and a row action shown
23
+ only when `visible` holds; on the detail screen `breadcrumb`, `summary`, `banner`
24
+ and `steps`, each filled from a query field and dropped when the value is empty
25
+ - `focus: true` on the detail screen: the app header actions leave the shell header and the
26
+ sidebar shows the focus rail; below 768 px a top bar replaces the header with the record
27
+ title, a back arrow to the list screen and the page-header overflow menu
28
+ - on phones the `orders` list draws cards in the order lead sentence (the hint column, with
29
+ detail and "Why?"), title, up to three values, then the row action; a hint column is never
30
+ the title and a `hideOnNarrow` one stays out of the card
31
+ - a work queue on that list: named filters as one select with hit counts (`namedFilterFacet`),
32
+ a per-filter `sort` and `emptyState` with a reset button, a badge column, per-row button
33
+ actions (a write "Send reminder" or a link "Open order", shown by `visible`) and a summary row footer
34
+ - a `today` dashboard on the 12-column grid: a `lead` briefing (two thirds), count tiles that
35
+ use the list's own query and link into the filtered list, a headerless "Now" list, two third
36
+ width lists and a money group. List and dashboard answer from `src/order-board.ts`, which the
37
+ e2e mock dispatcher shares
38
+ - on the detail screen: a second step action as a link button, metric tiles with `tone`,
39
+ `toneField` and `navigate: { tab }`, and tab counts via `countField`; the breadcrumb stays
40
+ unlinked because the recipe has no entity with a `detailFor` screen to link to
41
+ - phone variants: `hideOnNarrow` on dashboard panels and the progress chain, a list panel's
42
+ `narrow` (`cards` with a `limit`, or a one-line `line` link), `narrowBlocks` on the briefing,
43
+ `hint.plainSentence`, `showOnNarrowOnly` list columns, stat-group `columns`, and on the detail
44
+ `summary.narrowField` and `steps.narrowLimit`; the reason of a hint stays behind its toggle unless `reasonOpenField` opens it (with `reasonTitleField` as bold lead-in; steps use `whyOpen`/`whyTitle`)
45
+ - round 5 (board gaps): a titled `stat-group` strip with a panel `icon` and per-stat `narrowLabel`,
46
+ `narrowOrder` on a panel, `showTotal: { text, narrowText }`, `footerLink.moreText` and
47
+ `narrowMoreText`, `narrow: { layout: "line", field }`, `rowLink` on a list panel (arrow, or
48
+ `icon: "chevron"` for a date list), `hint.narrowDetailField` on cards, summary row items placed
49
+ under their `column`, and on the detail `header.narrowSubtitle`, a banner action `narrowLabel`,
50
+ `RecordStep.narrowDetail` and a `hideOnNarrow` metric. Phone cards leave out the reason toggle
51
+ - round 6 (board gaps): `rowLink.screenField` / `paramsField` (target screen from a query field),
52
+ list panel `icon`, `narrow.moreText`, `narrow.field` as any query output field,
53
+ `footerLink.narrowOnly`, `narrow.titleField` on cards and `rowToneMarker: "dot"`
21
54
  - boot-validator catching two common author mistakes: a `metrics` entry
22
55
  with an empty `label`, and a `tabs` layout with fewer than two
23
56
  sections
@@ -35,6 +68,71 @@ bun test
35
68
 
36
69
  ## Source files
37
70
 
71
+ ### e2e/board-screenshots.spec.ts
72
+
73
+ ```ts
74
+ // Manual visual evidence for the board blocks (dashboard, work queue, case file), desktop and
75
+ // phone via the screenshot projects in playwright.config.ts (PADDING_PARITY_SCREENSHOTS=1).
76
+ // Captures only; the behaviour is asserted in work-queue.spec.ts.
77
+
78
+ import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
79
+ import type { Page } from "@playwright/test";
80
+
81
+ const PHONE_FULL_HEIGHT = 2600;
82
+ const FILTER_FACET = "facet-__namedFilter";
83
+
84
+ // Phones keep the facets behind a "Filters" button.
85
+ async function openFilterSelect(page: Page): Promise<void> {
86
+ const facet = page.getByTestId(FILTER_FACET);
87
+ if (!(await facet.isVisible())) await page.getByRole("button", { name: "Filters" }).click();
88
+ await facet.click();
89
+ }
90
+
91
+ test("board: today dashboard", async ({ page }, testInfo) => {
92
+ await page.goto("/today");
93
+ await expect(page.getByText("Inbox")).toBeVisible();
94
+ await expect(page.getByText("Send payment reminder").first()).toBeVisible();
95
+ await page.screenshot({ path: testInfo.outputPath("today.png"), fullPage: true });
96
+ });
97
+
98
+ test("board: orders list in its states", async ({ page }, testInfo) => {
99
+ await page.goto("/orders");
100
+ await expect(page.getByText("SO-10483")).toBeVisible();
101
+ await page.screenshot({ path: testInfo.outputPath("orders.png"), fullPage: true });
102
+
103
+ await openFilterSelect(page);
104
+ await page.screenshot({ path: testInfo.outputPath("orders-select-open.png"), fullPage: true });
105
+ await page.getByTestId(`${FILTER_FACET}-action-needed`).click();
106
+ await expect(page.getByText("SO-10483")).toHaveCount(0);
107
+ await page.screenshot({ path: testInfo.outputPath("orders-filtered.png"), fullPage: true });
108
+
109
+ // The reason sits behind its toggle in the table; the phone cards leave it out.
110
+ const reasonToggle = page.locator("[data-hint-reason-toggle]").first();
111
+ if (await reasonToggle.isVisible()) {
112
+ await reasonToggle.click();
113
+ await expect(page.locator("[data-hint-reason]").first()).toBeVisible();
114
+ }
115
+ await page.screenshot({ path: testInfo.outputPath("orders-reason-open.png"), fullPage: true });
116
+
117
+ await openFilterSelect(page);
118
+ await page.getByTestId(`${FILTER_FACET}-reminder-due`).click();
119
+ await expect(page.getByTestId("render-list-empty-reset-filter")).toBeVisible();
120
+ await page.screenshot({ path: testInfo.outputPath("orders-empty.png"), fullPage: true });
121
+ });
122
+
123
+ test("board: order detail with a step reason open", async ({ page }, testInfo) => {
124
+ await page.goto("/order-detail/o1?guidance=1");
125
+ await expect(page.getByTestId("render-edit-form")).toBeVisible();
126
+ await page.getByRole("button", { name: /why/i }).first().click();
127
+ // The shell scrolls inside <main>, so fullPage alone would cut a phone capture at the viewport.
128
+ const viewport = page.viewportSize();
129
+ if (viewport !== null && viewport.width < 768) {
130
+ await page.setViewportSize({ width: viewport.width, height: PHONE_FULL_HEIGHT });
131
+ }
132
+ await page.screenshot({ path: testInfo.outputPath("order-detail.png"), fullPage: true });
133
+ });
134
+ ```
135
+
38
136
  ### e2e/build-server.ts
39
137
 
40
138
  ```ts
@@ -236,13 +334,33 @@ function OrderInternalNote(): ReactNode {
236
334
  );
237
335
  }
238
336
 
337
+ function OrderInboxIcon(): ReactNode {
338
+ return (
339
+ <svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16" fill="none">
340
+ <path d="M2 9h3l1 2h4l1-2h3v4H2z" stroke="currentColor" strokeWidth="1.5" />
341
+ </svg>
342
+ );
343
+ }
344
+
345
+ function DeadlinesIcon(): ReactNode {
346
+ return (
347
+ <svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16" fill="none">
348
+ <rect x="2" y="3" width="12" height="11" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
349
+ <path d="M2 7h12M5 1.5v3M11 1.5v3" stroke="currentColor" strokeWidth="1.5" />
350
+ </svg>
351
+ );
352
+ }
353
+
239
354
  function Shell({
240
355
  schema,
356
+ children,
241
357
  }: {
242
358
  readonly children: ReactNode;
243
359
  readonly schema: AppSchema;
244
360
  }): ReactNode {
245
361
  const feature = schema.features[0];
362
+ // Only the root path pins the record; other paths (/today, /orders) render the routed screen.
363
+ const isPinnedRecord = window.location.pathname === "/";
246
364
  // KumikoScreen sits directly under DefaultAppShell's <main> — same as the
247
365
  // real RoutedScreen (create-app.tsx) — so RenderEdit's `fillHeight` chain
248
366
  // (h-full all the way down) resolves against `main`'s own, genuinely
@@ -254,11 +372,13 @@ function Shell({
254
372
  schema={schema}
255
373
  user={{ id: "u1", roles: ["Admin"] }}
256
374
  >
257
- {feature !== undefined && (
258
- <ExtensionSectionsProvider value={{ OrderInternalNote }}>
375
+ <ExtensionSectionsProvider value={{ OrderInboxIcon, DeadlinesIcon, OrderInternalNote }}>
376
+ {isPinnedRecord && feature !== undefined ? (
259
377
  <KumikoScreen schema={feature} qn={ORDER_DETAIL_SCREEN_QN} entityId="order-1" />
260
- </ExtensionSectionsProvider>
261
- )}
378
+ ) : (
379
+ children
380
+ )}
381
+ </ExtensionSectionsProvider>
262
382
  </DefaultAppShell>
263
383
  );
264
384
  }
@@ -319,20 +439,48 @@ import type {
319
439
  WriteOpts,
320
440
  WriteResult,
321
441
  } from "@cosmicdrift/kumiko-renderer/headless";
322
-
442
+ import {
443
+ answerBriefing,
444
+ answerCustomers,
445
+ answerDeadlines,
446
+ answerMoney,
447
+ answerNowList,
448
+ answerOrderDetail,
449
+ answerOrderList,
450
+ answerOrderSummary,
451
+ orderListSchema,
452
+ orderSummarySchema,
453
+ } from "../../src/order-board";
454
+
455
+ const QUERY_ORDER_LIST = "order-desk:query:order:list";
456
+ const QUERY_ORDER_SUMMARY = "order-desk:query:order:summary";
457
+ const QUERY_ORDER_NOW = "order-desk:query:order:now";
458
+ const QUERY_ORDER_BRIEFING = "order-desk:query:order:briefing";
459
+ const QUERY_ORDER_DEADLINES = "order-desk:query:order:deadlines";
460
+ const QUERY_ORDER_CUSTOMERS = "order-desk:query:order:customers";
461
+ const QUERY_ORDER_MONEY = "order-desk:query:order:money";
323
462
  const QUERY_ORDER_DETAIL = "order-desk:query:order:detail";
324
463
  const QUERY_ORDER_ITEMS = "order-desk:query:order:items";
325
464
  const QUERY_ORDER_PAYMENTS = "order-desk:query:order:payments";
326
465
 
327
- const ORDER_DETAIL_FIELDS = {
328
- customerName: "Aiko Tanaka",
329
- orderNumber: "SO-10482",
330
- status: "processing",
331
- totalAmount: "€ 1,248.00",
332
- outstandingAmount: "€ 312.00",
333
- itemCount: "3",
334
- placedAt: "2026-08-21",
335
- };
466
+ // The guidance blocks (breadcrumb, summary, banner, progress, steps) stack tall above the tabs;
467
+ // the height specs measure the tab panel and run without them, `?guidance=1` turns them on.
468
+ function orderDetailForUrl(id: string): Record<string, unknown> {
469
+ const {
470
+ path,
471
+ summaryLine,
472
+ summaryShort,
473
+ summaryTone,
474
+ notice,
475
+ steps,
476
+ progress,
477
+ ...withoutGuidance
478
+ } = answerOrderDetail(id);
479
+ const withGuidance = new URLSearchParams(window.location.search).has("guidance");
480
+ return withGuidance
481
+ ? { ...withoutGuidance, path, summaryLine, summaryShort, summaryTone, notice, steps, progress }
482
+ : withoutGuidance;
483
+ }
336
484
 
337
485
  function itemsCountFromUrl(): number {
338
486
  const raw = new URLSearchParams(window.location.search).get("items");
@@ -367,7 +515,30 @@ export function createMockDispatcher(): Dispatcher {
367
515
  if (type === QUERY_ORDER_DETAIL) {
368
516
  const data = (payload ?? {}) as Record<string, unknown>; // @cast-boundary mock-dispatcher wire payload
369
517
  const id = (data["id"] as string | undefined) ?? "order-1";
370
- return { isSuccess: true, data: { id, ...ORDER_DETAIL_FIELDS } as unknown as TData };
518
+ return { isSuccess: true, data: orderDetailForUrl(id) as unknown as TData };
519
+ }
520
+ if (type === QUERY_ORDER_LIST) {
521
+ const answer = answerOrderList(orderListSchema.parse(payload ?? {}));
522
+ return { isSuccess: true, data: answer as unknown as TData };
523
+ }
524
+ if (type === QUERY_ORDER_SUMMARY) {
525
+ const answer = answerOrderSummary(orderSummarySchema.parse(payload ?? {}));
526
+ return { isSuccess: true, data: answer as unknown as TData };
527
+ }
528
+ if (type === QUERY_ORDER_NOW) {
529
+ return { isSuccess: true, data: answerNowList() as unknown as TData };
530
+ }
531
+ if (type === QUERY_ORDER_BRIEFING) {
532
+ return { isSuccess: true, data: answerBriefing() as unknown as TData };
533
+ }
534
+ if (type === QUERY_ORDER_DEADLINES) {
535
+ return { isSuccess: true, data: answerDeadlines() as unknown as TData };
536
+ }
537
+ if (type === QUERY_ORDER_CUSTOMERS) {
538
+ return { isSuccess: true, data: answerCustomers() as unknown as TData };
539
+ }
540
+ if (type === QUERY_ORDER_MONEY) {
541
+ return { isSuccess: true, data: answerMoney() as unknown as TData };
371
542
  }
372
543
  if (type === QUERY_ORDER_ITEMS) {
373
544
  return { isSuccess: true, data: { rows: buildItemRows(itemsCountFromUrl()) } as TData };
@@ -574,20 +745,20 @@ test.describe("record-detail-layout — tall tab panel scrolls", () => {
574
745
  });
575
746
 
576
747
  test.describe("record-detail-layout — header action per tab", () => {
577
- const recordPayment = "order-desk.action.recordPayment";
748
+ const recordPayment = "Record payment";
578
749
 
579
750
  test("record-payment shows on the payments tab only", async ({ page }) => {
580
751
  await page.goto("/?tab=payments");
581
752
  await expect(page.getByTestId("kumiko-screen-projection-detail-tabs")).toBeVisible();
582
753
  // The third header action lands in the overflow menu.
583
754
  await page.getByRole("button", { name: "More actions" }).last().click();
584
- await expect(page.getByText(recordPayment)).toBeVisible();
755
+ await expect(page.getByRole("menuitem", { name: recordPayment })).toBeVisible();
585
756
 
586
757
  await page.goto("/?tab=items");
587
758
  await expect(page.getByTestId("render-list-table")).toBeVisible();
588
759
  // Only two actions remain, so no overflow menu is rendered.
589
760
  await expect(page.getByRole("button", { name: "More actions" })).toHaveCount(0);
590
- await expect(page.getByText(recordPayment)).toHaveCount(0);
761
+ await expect(page.getByRole("menuitem", { name: recordPayment })).toHaveCount(0);
591
762
  });
592
763
  });
593
764
  ```
@@ -701,7 +872,7 @@ export default defineConfig({
701
872
  projects: [
702
873
  {
703
874
  name: "chromium",
704
- testIgnore: /(phone-viewport|padding-parity-screenshots)\.spec\.ts$/,
875
+ testIgnore: /(phone-viewport|padding-parity-screenshots|board-screenshots)\.spec\.ts$/,
705
876
  use: { ...devices["Desktop Chrome"], viewport: { width: 1440, height: 900 } },
706
877
  },
707
878
  // Desktop copy of padding-parity-screenshots.spec.ts, distinct from the
@@ -712,7 +883,7 @@ export default defineConfig({
712
883
  ? [
713
884
  {
714
885
  name: "chromium-desktop-screenshots",
715
- testMatch: /padding-parity-screenshots\.spec\.ts$/,
886
+ testMatch: /(padding-parity-screenshots|board-screenshots)\.spec\.ts$/,
716
887
  use: { ...devices["Desktop Chrome"], viewport: { width: 1440, height: 900 } },
717
888
  },
718
889
  ]
@@ -725,7 +896,7 @@ export default defineConfig({
725
896
  {
726
897
  name: "chromium-phone",
727
898
  testMatch: WITH_PARITY_SCREENSHOTS
728
- ? /(phone-viewport|padding-parity-screenshots)\.spec\.ts$/
899
+ ? /(phone-viewport|padding-parity-screenshots|board-screenshots)\.spec\.ts$/
729
900
  : /phone-viewport\.spec\.ts$/,
730
901
  use: { ...devices["Desktop Chrome"], viewport: { width: 390, height: 844 } },
731
902
  },
@@ -743,6 +914,86 @@ export default defineConfig({
743
914
  });
744
915
  ```
745
916
 
917
+ ### e2e/work-queue.spec.ts
918
+
919
+ ```ts
920
+ // The orders work queue: named filters in one select with hit counts, a filter-owned sort,
921
+ // a filter-owned empty state with a reset button, and the summary row footer.
922
+
923
+ import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
924
+
925
+ const FILTER_FACET = "facet-__namedFilter";
926
+ // The open reason box renders as its own table row under the data row; count data rows only.
927
+ const DATA_ROWS = "tbody tr:not([data-reason-row])";
928
+
929
+ test("picking a named filter narrows the list and sorts it by the filter's own order", async ({
930
+ page,
931
+ }) => {
932
+ await page.goto("/orders");
933
+ await expect(page.getByText("SO-10483")).toBeVisible();
934
+
935
+ await page.getByTestId(FILTER_FACET).click();
936
+ await expect(page.getByTestId(`${FILTER_FACET}-action-needed`)).toContainText("5");
937
+ await page.getByTestId(`${FILTER_FACET}-action-needed`).click();
938
+
939
+ await expect(page.getByText("SO-10483")).toHaveCount(0);
940
+ const rowTexts = await page.locator(DATA_ROWS).allInnerTexts();
941
+ const orderNumbers = rowTexts.map((text) => /SO-\d+/.exec(text)?.[0]);
942
+ expect(orderNumbers).toEqual(["SO-10482", "SO-10488", "SO-10484", "SO-10485", "SO-10486"]);
943
+ });
944
+
945
+ test("a filter without hits shows its own empty state, and its reset button brings the list back", async ({
946
+ page,
947
+ }) => {
948
+ await page.goto("/orders");
949
+ await page.getByTestId(FILTER_FACET).click();
950
+ await page.getByTestId(`${FILTER_FACET}-reminder-due`).click();
951
+
952
+ await expect(page.getByTestId("render-list-empty-reset-filter")).toBeVisible();
953
+ await expect(page.getByText("SO-10482")).toHaveCount(0);
954
+
955
+ await page.getByTestId("render-list-empty-reset-filter").click();
956
+ await expect(page.getByText("SO-10482")).toBeVisible();
957
+ await expect(page.getByTestId("render-list-empty-reset-filter")).toHaveCount(0);
958
+ });
959
+
960
+ test("the summary row is the only footer and carries the open amount", async ({ page }) => {
961
+ await page.goto("/orders");
962
+ await expect(page.getByTestId("list-summary")).toContainText("2,497.00");
963
+ await expect(page.getByTestId("list-totals")).toHaveCount(0);
964
+ });
965
+
966
+ test("the sort select reorders the list by the chosen option", async ({ page }) => {
967
+ await page.goto("/orders");
968
+ const select = page.getByTestId("render-list-table-sort-options");
969
+ await expect(page.getByTestId("render-list-table-sort-options-label")).toContainText("Sorted by");
970
+ await select.selectOption({ label: "Customer A-Z" });
971
+ await expect(page.getByTestId("render-list-table-sort-options-label")).toContainText(
972
+ "Customer A-Z",
973
+ );
974
+ const rowTexts = await page.locator(DATA_ROWS).allInnerTexts();
975
+ const customers = rowTexts.map(
976
+ (text) => /Aiko|Emma|Jonas|Kenji|Lars|Maria|Priya|Tom/.exec(text)?.[0],
977
+ );
978
+ expect(customers).toEqual([...customers].sort());
979
+ });
980
+
981
+ test("the summary row follows the filter", async ({ page }) => {
982
+ await page.goto("/orders");
983
+ await expect(page.getByTestId("list-summary")).toContainText(/^8€/);
984
+ await page.getByTestId(FILTER_FACET).click();
985
+ await page.getByTestId(`${FILTER_FACET}-action-needed`).click();
986
+ await expect(page.getByTestId("list-summary")).toContainText(/^5€/);
987
+ });
988
+
989
+ test("a stat tile on the dashboard links into the filtered list", async ({ page }) => {
990
+ await page.goto("/today");
991
+ await page.getByText("Need action").click();
992
+ await expect(page).toHaveURL(/orders/);
993
+ await expect(page.getByText("SO-10483")).toHaveCount(0);
994
+ });
995
+ ```
996
+
746
997
  ### src/__tests__/feature.test.ts
747
998
 
748
999
  ```ts
@@ -765,6 +1016,14 @@ import {
765
1016
  import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
766
1017
  import { z } from "zod";
767
1018
  import { createOrderDeskFeature } from "../feature";
1019
+ import {
1020
+ answerBriefing,
1021
+ answerOrderDetail,
1022
+ answerOrderList,
1023
+ answerOrderSummary,
1024
+ orderListSchema,
1025
+ orderSummarySchema,
1026
+ } from "../order-board";
768
1027
 
769
1028
  function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
770
1029
  validateBootRaw(withBootValidatorFixture(features));
@@ -788,6 +1047,8 @@ describe("record-detail-layout showcase — registration", () => {
788
1047
  if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
789
1048
  expect(screen.header).toEqual({
790
1049
  title: "customerName",
1050
+ shortTitle: "shortTitle",
1051
+ narrowSubtitle: "narrowSubtitle",
791
1052
  subtitle: [
792
1053
  "orderNumber",
793
1054
  { field: "placedAt", format: { format: "date", dateStyle: "medium" } },
@@ -825,12 +1086,196 @@ describe("record-detail-layout showcase — registration", () => {
825
1086
  expect(screen.inlineActions).toEqual(["download-invoice"]);
826
1087
  });
827
1088
 
828
- test("relatedList columns collapse string shorthand into the object form", () => {
1089
+ test("relatedList columns carry their own header label, there is no entity to resolve it from", () => {
829
1090
  const screen = registry.getScreen("order-desk:screen:order-detail");
830
1091
  if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
831
1092
  const itemsSection = screen.layout.sections[0];
832
1093
  if (itemsSection?.kind !== "relatedList") throw new Error("expected relatedList");
833
- expect(normalizeListColumn(itemsSection.columns[0]!)).toEqual({ field: "sku" });
1094
+ expect(normalizeListColumn(itemsSection.columns[0]!)).toEqual({
1095
+ field: "sku",
1096
+ label: "order-desk.col.sku",
1097
+ });
1098
+ });
1099
+ });
1100
+
1101
+ describe("record-detail-layout showcase — guidance", () => {
1102
+ test("the orders list carries rowToneField and a hint column", () => {
1103
+ const screen = registry.getScreen("order-desk:screen:orders");
1104
+ if (screen?.type !== "projectionList") throw new Error("expected projectionList");
1105
+ expect(screen.rowToneField).toBe("tone");
1106
+ const hint = screen.columns.map((c) => normalizeListColumn(c)).find((c) => c.hint);
1107
+ expect(hint?.hint?.detailField).toBe("nextStepDue");
1108
+ });
1109
+
1110
+ test("the detail screen declares breadcrumb, summary, banner and steps from query fields", () => {
1111
+ const screen = registry.getScreen("order-desk:screen:order-detail");
1112
+ if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
1113
+ expect(screen.breadcrumb).toEqual({ field: "path" });
1114
+ expect(screen.summary).toEqual({
1115
+ field: "summaryLine",
1116
+ narrowField: "summaryShort",
1117
+ toneField: "summaryTone",
1118
+ });
1119
+ expect(screen.banner?.field).toBe("notice");
1120
+ expect(screen.steps?.field).toBe("steps");
1121
+ expect(screen.progress?.field).toBe("progress");
1122
+ });
1123
+ });
1124
+
1125
+ describe("record-detail-layout showcase — work queue", () => {
1126
+ test("the orders list offers named filters as a counted select, with sort and empty state", () => {
1127
+ const screen = registry.getScreen("order-desk:screen:orders");
1128
+ if (screen?.type !== "projectionList") throw new Error("expected projectionList");
1129
+ expect(screen.namedFilters?.map((filter) => filter.id)).toEqual([
1130
+ "action-needed",
1131
+ "reminder-due",
1132
+ "ending-soon",
1133
+ ]);
1134
+ expect(screen.namedFilterFacet).toEqual({
1135
+ display: "select",
1136
+ showCounts: true,
1137
+ label: "order-desk.orders.todo",
1138
+ });
1139
+ const buttons = (screen.rowActions ?? []).filter((action) => action.display === "button");
1140
+ expect(buttons.map((action) => [action.id, action.visible])).toEqual([
1141
+ ["remind", { field: "canRemind", eq: true }],
1142
+ ["open-order", { field: "canRemind", eq: false }],
1143
+ ]);
1144
+ expect(screen.namedFilters?.[0]?.sort).toEqual({ field: "urgency", dir: "desc" });
1145
+ expect(screen.namedFilters?.[0]?.emptyState?.title).toBe("order-desk.orders.all-done");
1146
+ expect(screen.table?.totals).toBeUndefined();
1147
+ });
1148
+
1149
+ test("the list query filters, sorts, counts and aggregates like the screen asks", () => {
1150
+ const ask = (payload: object) => answerOrderList(orderListSchema.parse(payload));
1151
+ const open = ask({ namedFilter: "action-needed", sort: "urgency", sortDirection: "desc" });
1152
+ if (!("rows" in open)) throw new Error("expected rows");
1153
+ expect(open.rows.map((row) => row.id)).toEqual(["o1", "o7", "o3", "o4", "o5"]);
1154
+
1155
+ const counted = ask({ namedFilter: "action-needed", limit: 1, totalCount: true });
1156
+ if (!("rows" in counted)) throw new Error("expected rows");
1157
+ expect(counted.rows).toHaveLength(1);
1158
+ expect(counted.total).toBe(5);
1159
+
1160
+ const none = ask({ namedFilter: "reminder-due", totalCount: true });
1161
+ if (!("rows" in none)) throw new Error("expected rows");
1162
+ expect(none.rows).toHaveLength(0);
1163
+
1164
+ const totals = ask({
1165
+ aggregate: { measures: [{ field: "openAmount", kind: "sum" }] },
1166
+ });
1167
+ if (!("groups" in totals)) throw new Error("expected groups");
1168
+ expect(totals.groups[0]?.measures).toEqual([2497]);
1169
+ });
1170
+
1171
+ test("the today dashboard counts through the list query and links into the filtered list", () => {
1172
+ const screen = registry.getScreen("order-desk:screen:today");
1173
+ if (screen?.type !== "dashboard") throw new Error("expected dashboard");
1174
+ expect(screen.panels.map((panel) => panel.kind)).toEqual([
1175
+ "text",
1176
+ "stat-group",
1177
+ "list",
1178
+ "list",
1179
+ "list",
1180
+ "stat-group",
1181
+ ]);
1182
+ const counts = screen.panels.find((panel) => panel.id === "queue-counts");
1183
+ if (counts?.kind !== "stat-group") throw new Error("expected stat-group");
1184
+ expect(counts.stats.map((stat) => stat.navigate?.namedFilter)).toEqual([
1185
+ "action-needed",
1186
+ "reminder-due",
1187
+ "ending-soon",
1188
+ ]);
1189
+ });
1190
+ });
1191
+
1192
+ describe("record-detail-layout showcase — board gaps", () => {
1193
+ test("the orders list declares sort options, a summary query and a self-sizing hint column", () => {
1194
+ const screen = registry.getScreen("order-desk:screen:orders");
1195
+ if (screen?.type !== "projectionList") throw new Error("expected projectionList");
1196
+ expect(screen.sortOptions?.map((option) => [option.field, option.dir])).toEqual([
1197
+ ["urgency", "desc"],
1198
+ ["customerName", "asc"],
1199
+ ]);
1200
+ expect(screen.table?.summaryRow?.query).toBe("order-desk:query:order:summary");
1201
+ const hint = screen.columns.map((c) => normalizeListColumn(c)).find((c) => c.hint);
1202
+ expect([hint?.width, hint?.minWidth]).toEqual([320, 240]);
1203
+ });
1204
+
1205
+ test("the summary query follows the named filter", () => {
1206
+ const all = answerOrderSummary(orderSummarySchema.parse({}));
1207
+ const open = answerOrderSummary(orderSummarySchema.parse({ namedFilter: "action-needed" }));
1208
+ expect(all.items[0]?.value).toBe(8);
1209
+ expect(open.items[0]?.value).toBe(5);
1210
+ expect(all.items.map((item) => item.label)).toEqual(["Orders", "Open", "Overdue"]);
1211
+ });
1212
+
1213
+ test("the today board links its list and stat group and the detail places progress beside the steps", () => {
1214
+ const today = registry.getScreen("order-desk:screen:today");
1215
+ if (today?.type !== "dashboard") throw new Error("expected dashboard");
1216
+ const now = today.panels.find((panel) => panel.id === "now");
1217
+ if (now?.kind !== "list") throw new Error("expected the now list");
1218
+ expect(now.footerLink?.namedFilter).toBe("action-needed");
1219
+ const counts = today.panels.find((panel) => panel.id === "queue-counts");
1220
+ if (counts?.kind !== "stat-group") throw new Error("expected stat-group");
1221
+ expect([counts.layout, counts.link?.screen]).toEqual(["strip", "orders"]);
1222
+
1223
+ const detail = registry.getScreen("order-desk:screen:order-detail");
1224
+ if (detail?.type !== "projectionDetail") throw new Error("expected projectionDetail");
1225
+ expect(detail.progress?.placement).toBe("beside-steps");
1226
+ expect(detail.metricsPlacement).toEqual({ narrow: "after-guidance" });
1227
+ expect(detail.metrics?.map((metric) => metric.subField)).toContain("totalNote");
1228
+ });
1229
+ });
1230
+
1231
+ describe("record-detail-layout showcase — phone variants", () => {
1232
+ test("the today board limits, collapses and hides panels under sm", () => {
1233
+ const today = registry.getScreen("order-desk:screen:today");
1234
+ if (today?.type !== "dashboard") throw new Error("expected dashboard");
1235
+ const panel = (id: string) => today.panels.find((candidate) => candidate.id === id);
1236
+ const now = panel("now");
1237
+ const deadlines = panel("deadlines");
1238
+ if (now?.kind !== "list" || deadlines?.kind !== "list") throw new Error("expected lists");
1239
+ expect(now.narrow).toEqual({ layout: "cards", limit: 3 });
1240
+ expect(deadlines.narrow?.field).toBe("title");
1241
+ expect(deadlines.narrow?.moreText).toBe("order-desk.today.deadlines-more-narrow");
1242
+ expect(deadlines.icon).toEqual({ react: { __component: "DeadlinesIcon" } });
1243
+ expect(deadlines.footerLink?.narrowOnly).toBe(true);
1244
+ expect(deadlines.rowLink).toEqual({
1245
+ screenField: "screen",
1246
+ paramsField: "params",
1247
+ icon: "chevron",
1248
+ });
1249
+ expect(panel("customers")?.kind === "list" && panel("customers")).toBeTruthy();
1250
+ expect(panel("customers")?.hideOnNarrow).toBe(true);
1251
+ expect(panel("money")?.hideOnNarrow).toBe(true);
1252
+ });
1253
+
1254
+ test("the detail shortens summary and steps and drops the chain under sm", () => {
1255
+ const detail = registry.getScreen("order-desk:screen:order-detail");
1256
+ if (detail?.type !== "projectionDetail") throw new Error("expected projectionDetail");
1257
+ expect(detail.steps?.narrowLimit).toBe(3);
1258
+ expect(detail.progress?.hideOnNarrow).toBe(true);
1259
+ expect(answerOrderDetail("o1").steps.length).toBeGreaterThan(3);
1260
+ });
1261
+
1262
+ test("the board uses the round-5 phone and row options", () => {
1263
+ const today = registry.getScreen("order-desk:screen:today");
1264
+ if (today?.type !== "dashboard") throw new Error("expected dashboard");
1265
+ const customers = today.panels.find((candidate) => candidate.id === "customers");
1266
+ if (customers?.kind !== "list") throw new Error("expected the customers list");
1267
+ expect(customers.rowLink).toEqual({ screen: "order-detail", paramField: "params" });
1268
+ expect(customers.rowToneMarker).toBe("dot");
1269
+ expect(today.panels.find((candidate) => candidate.id === "briefing")?.narrowOrder).toBe(1);
1270
+ expect(answerOrderSummary(orderSummarySchema.parse({})).items.map((i) => i.column)).toEqual([
1271
+ "orderNumber",
1272
+ "openAmount",
1273
+ "urgencyLabel",
1274
+ ]);
1275
+ });
1276
+
1277
+ test("the briefing answers a shorter variant for phones", () => {
1278
+ expect(answerBriefing().narrowBlocks.length).toBeGreaterThan(0);
834
1279
  });
835
1280
  });
836
1281
 
@@ -869,6 +1314,24 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
869
1314
  expect(() => validateBoot([broken])).toThrow(/metric "totalAmount" has no "label"/);
870
1315
  });
871
1316
 
1317
+ test("a hint column naming an empty detail field fails boot", () => {
1318
+ const broken = defineFeature("broken-order-desk-hint", (r) => {
1319
+ r.queryHandler({
1320
+ name: "order:list",
1321
+ schema: z.object({}),
1322
+ handler: async () => ({ rows: [] }),
1323
+ access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
1324
+ });
1325
+ r.screen({
1326
+ id: "orders",
1327
+ type: "projectionList",
1328
+ query: "broken-order-desk-hint:query:order:list",
1329
+ columns: [{ field: "nextStep", hint: { detailField: "" } }],
1330
+ });
1331
+ });
1332
+ expect(() => validateBoot([broken])).toThrow(/list\/guidance-field-empty/);
1333
+ });
1334
+
872
1335
  test("tabs with only one section fails boot", () => {
873
1336
  const broken = defineFeature("broken-order-desk-tabs", (r) => {
874
1337
  r.queryHandler({
@@ -895,56 +1358,128 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
895
1358
  ### src/feature.ts
896
1359
 
897
1360
  ```ts
898
- // Record Detail Layout Showcase — a projectionDetail screen with the
899
- // "Akte" (case file) layout:
1361
+ // Record Detail Layout Showcase — a work queue, a briefing dashboard and a
1362
+ // projectionDetail screen with the "Akte" (case file) layout:
900
1363
  // 1. `header` renders the query row's customer/order/status columns above
901
1364
  // the layout — the identity a support agent scans first.
902
- // 2. `metrics` renders a labeled band of key numbers from the same row —
903
- // each metric carries its own i18n `label`, there is no fallback to the
904
- // raw column name.
905
- // 3. `layout.mode: "tabs"` splits the record into four tabs: two
906
- // `relatedList` sections (own query, own pagination, mounts only when
907
- // active), one `fields` section (master data from the detail row), and
908
- // one `extension` section (a plugin-mounted component, fw#3234 padding-
909
- // parity check — every tab kind must sit in the same Card padding, no
910
- // section carries extra chrome of its own).
1365
+ // 2. `metrics` renders a labeled band of key numbers from the same row; each metric
1366
+ // carries its own i18n `label`, there is no fallback to the raw column name. Tiles take a
1367
+ // fixed `tone` or a per-record `toneField` and can jump to a tab with `navigate`.
1368
+ // 3. `layout.mode: "tabs"` splits the record into four tabs: two `relatedList`
1369
+ // sections (own query, own pagination, mounts only when active, badge via `countField`),
1370
+ // one `fields` section (master data) and one `extension` section (plugin-mounted component;
1371
+ // every tab kind sits in the same Card padding, no extra chrome).
911
1372
  // 4. The payments tab's emptyState picks its text from the order record through `variants`.
912
1373
  // 5. A screen-level `actions` entry (fw#3234) renders next to the header,
913
1374
  // not inside any tab's Card. `inlineActions` keeps download-invoice a visible
914
1375
  // button next to it where the page header would otherwise fold it into the menu.
915
- //
916
1376
  // 6. `showOnTabs` limits the record-payment action to the payments tab.
1377
+ // 7. Guidance: the `orders` projectionList tints rows via `rowToneField`, shows a
1378
+ // "to do" hint column (sentence, detail, tone, a "Why?" reason), a badge column and
1379
+ // per-row button actions (send a reminder, or open the record). Named filters sit in one select with hit counts,
1380
+ // each with its own sort and empty state; the summary row totals the rows. The detail screen adds
1381
+ // `breadcrumb`, `summary`, `banner` and `steps`, each reading a query field; empty values drop out.
1382
+ // 8. The `today` dashboard composes a lead briefing, count tiles that link into the filtered
1383
+ // list, a headerless "Now" list and two narrow lists on a 12-column grid.
1384
+ // 9. Phone variants: `hideOnNarrow` drops panels, a list panel's `narrow` turns it into limited cards or a
1385
+ // one-line link, `narrowBlocks` shortens the briefing, `showOnNarrowOnly` adds card-only meta, and the
1386
+ // detail shows `summary.narrowField`, `steps.narrowLimit` and no `progress` chain under sm.
1387
+ // 10. `focus: true` gives the detail a focused shell; phones get a top bar with the
1388
+ // record title, a back arrow to the list and the page-header overflow menu.
917
1389
  //
918
- // projectionDetail has no entity — it binds to an explicit query instead, so
919
- // every field name below (header, metrics, fields) is a column of that
920
- // query's row, not an entity field.
1390
+ // projectionDetail binds to an explicit query, not an entity: every field name below
1391
+ // (header, metrics, fields) is a column of that query's row.
921
1392
 
922
1393
  import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
923
1394
  import { z } from "zod";
1395
+ import {
1396
+ answerBriefing,
1397
+ answerCustomers,
1398
+ answerDeadlines,
1399
+ answerMoney,
1400
+ answerNowList,
1401
+ answerOrderDetail,
1402
+ answerOrderList,
1403
+ answerOrderSummary,
1404
+ orderListSchema,
1405
+ orderSummarySchema,
1406
+ } from "./order-board.ts";
924
1407
 
925
1408
  const rowIdSchema = z.object({ id: z.string() });
1409
+ const noPayloadSchema = z.object({});
1410
+ const accessRoles = { roles: ["Support", "Admin"] } as const;
1411
+
1412
+ export const ORDER_LIST_QUERY = "order-desk:query:order:list";
926
1413
 
927
1414
  export function createOrderDeskFeature(): FeatureDefinition {
928
1415
  return defineFeature("order-desk", (r) => {
929
1416
  r.systemScope();
930
1417
 
1418
+ r.queryHandler({
1419
+ name: "order:list",
1420
+ schema: orderListSchema,
1421
+ handler: async (query) => answerOrderList(query.payload),
1422
+ access: accessRoles,
1423
+ });
1424
+
1425
+ r.queryHandler({
1426
+ name: "order:summary",
1427
+ schema: orderSummarySchema,
1428
+ handler: async (query) => answerOrderSummary(query.payload),
1429
+ access: accessRoles,
1430
+ });
1431
+
1432
+ r.queryHandler({
1433
+ name: "order:now",
1434
+ schema: noPayloadSchema,
1435
+ handler: async () => answerNowList(),
1436
+ access: accessRoles,
1437
+ });
1438
+
1439
+ r.queryHandler({
1440
+ name: "order:briefing",
1441
+ schema: noPayloadSchema,
1442
+ handler: async () => answerBriefing(),
1443
+ access: accessRoles,
1444
+ });
1445
+
1446
+ r.queryHandler({
1447
+ name: "order:deadlines",
1448
+ schema: noPayloadSchema,
1449
+ handler: async () => answerDeadlines(),
1450
+ outputSchema: z.object({
1451
+ rows: z.array(
1452
+ z.object({
1453
+ id: z.string(),
1454
+ due: z.string(),
1455
+ title: z.string(),
1456
+ screen: z.string(),
1457
+ params: z.object({ entityId: z.string() }),
1458
+ }),
1459
+ ),
1460
+ }),
1461
+ access: accessRoles,
1462
+ });
1463
+
1464
+ r.queryHandler({
1465
+ name: "order:customers",
1466
+ schema: noPayloadSchema,
1467
+ handler: async () => answerCustomers(),
1468
+ access: accessRoles,
1469
+ });
1470
+
1471
+ r.queryHandler({
1472
+ name: "order:money",
1473
+ schema: noPayloadSchema,
1474
+ handler: async () => answerMoney(),
1475
+ access: accessRoles,
1476
+ });
1477
+
931
1478
  r.queryHandler({
932
1479
  name: "order:detail",
933
1480
  schema: rowIdSchema,
934
- handler: async (query) => ({
935
- id: query.payload.id,
936
- customerName: "Aiko Tanaka",
937
- orderNumber: "SO-10482",
938
- status: "processing",
939
- totalAmount: "€ 1,248.00",
940
- outstandingAmount: "€ 312.00",
941
- itemCount: "3",
942
- placedAt: "2026-08-21",
943
- shippingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
944
- billingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
945
- salesRep: "Jonas Weber",
946
- }),
947
- access: { roles: ["Support", "Admin"] },
1481
+ handler: async (query) => answerOrderDetail(query.payload.id),
1482
+ access: accessRoles,
948
1483
  });
949
1484
 
950
1485
  r.queryHandler({
@@ -957,7 +1492,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
957
1492
  { sku: "PAD-01", description: "Desk mat", quantity: 1, unitPrice: 22 },
958
1493
  ],
959
1494
  }),
960
- access: { roles: ["Support", "Admin"] },
1495
+ access: accessRoles,
961
1496
  });
962
1497
 
963
1498
  r.queryHandler({
@@ -969,27 +1504,426 @@ export function createOrderDeskFeature(): FeatureDefinition {
969
1504
  { paidAt: "2026-08-25", amount: 312, method: "invoice", status: "pending" },
970
1505
  ],
971
1506
  }),
972
- access: { roles: ["Support", "Admin"] },
1507
+ access: accessRoles,
1508
+ });
1509
+
1510
+ r.writeHandler({
1511
+ name: "order:remind",
1512
+ schema: rowIdSchema,
1513
+ handler: async (event) => ({ isSuccess: true as const, data: { id: event.payload.id } }),
1514
+ access: accessRoles,
1515
+ });
1516
+
1517
+ r.translations({
1518
+ keys: {
1519
+ "screen:orders.title": { en: "Orders" },
1520
+ "screen:order-detail.title": { en: "Order" },
1521
+ "screen:today.title": { en: "Today" },
1522
+ "order-desk.orders.todo": { en: "To do" },
1523
+ "order-desk.orders.nothing-open": { en: "Nothing to do" },
1524
+ "order-desk.orders.all-done": { en: "All done" },
1525
+ "order-desk.orders.all-done-hint": { en: "No order needs you right now." },
1526
+ "order-desk.filter.action-needed": { en: "Needs action" },
1527
+ "order-desk.filter.reminder-due": { en: "Reminder due" },
1528
+ "order-desk.filter.ending-soon": { en: "Ending soon" },
1529
+ "order-desk.col.order": { en: "Order" },
1530
+ "order-desk.col.customer": { en: "Customer" },
1531
+ "order-desk.col.urgency": { en: "Urgency" },
1532
+ "order-desk.col.todo": { en: "To do" },
1533
+ "order-desk.col.open-amount": { en: "Open" },
1534
+ "order-desk.col.sku": { en: "SKU" },
1535
+ "order-desk.col.description": { en: "Description" },
1536
+ "order-desk.col.quantity": { en: "Quantity" },
1537
+ "order-desk.col.unit-price": { en: "Unit price" },
1538
+ "order-desk.col.paid-at": { en: "Paid on" },
1539
+ "order-desk.col.amount": { en: "Amount" },
1540
+ "order-desk.col.method": { en: "Method" },
1541
+ "order-desk.col.status": { en: "Status" },
1542
+ "order-desk.sort.urgency": { en: "Urgency" },
1543
+ "order-desk.sort.customer": { en: "Customer A-Z" },
1544
+ "order-desk.today.now": { en: "Now" },
1545
+ "order-desk.today.now-all": { en: "All orders needing action" },
1546
+ "order-desk.today.inbox": { en: "Inbox" },
1547
+ "order-desk.today.inbox-sub": { en: "Orders waiting for you" },
1548
+ "order-desk.today.inbox-link": { en: "All orders" },
1549
+ "order-desk.today.deadlines": { en: "Deadlines" },
1550
+ "order-desk.today.deadlines-all": { en: "All deadlines" },
1551
+ "order-desk.col.narrow-meta": { en: "Details" },
1552
+ "order-desk.today.customers": { en: "Customers" },
1553
+ "order-desk.today.money": { en: "Money" },
1554
+ "order-desk.today.money-sub": { en: "Across all open orders" },
1555
+ "order-desk.today.stat.action-needed": { en: "Need action" },
1556
+ "order-desk.today.stat.reminder-due": { en: "Reminders due" },
1557
+ "order-desk.today.stat.ending-soon": { en: "Ending soon" },
1558
+ "order-desk.today.now-total": { en: "The {shown} most urgent of {total} orders" },
1559
+ "order-desk.today.now-total-narrow": { en: "{shown} of {total}" },
1560
+ "order-desk.today.deadlines-more": { en: "{count} more deadlines" },
1561
+ "order-desk.today.deadlines-more-narrow": { en: "{count} more" },
1562
+ "order-desk.action.record-short": { en: "Record" },
1563
+ "order-desk.today.stat.open": { en: "Open" },
1564
+ "order-desk.today.stat.overdue": { en: "Overdue" },
1565
+ "order-desk.today.stat.collected": { en: "Collected" },
1566
+ "order-desk.action.open": { en: "Open" },
1567
+ "order-desk.action.remind": { en: "Send reminder" },
1568
+ "order-desk.action.open-order": { en: "Open order" },
1569
+ "order-desk.action.prepare": { en: "Let the assistant prepare" },
1570
+ "order-desk.action.recordPayment": { en: "Record payment" },
1571
+ "order-desk.action.refreshOrder": { en: "Refresh" },
1572
+ "order-desk.action.downloadInvoice": { en: "Download invoice" },
1573
+ "order-desk.steps.title": { en: "Next steps" },
1574
+ "order-desk.steps.empty": { en: "Nothing left to do" },
1575
+ "order-desk.metric.totalAmount": { en: "Total" },
1576
+ "order-desk.metric.outstandingAmount": { en: "Outstanding" },
1577
+ "order-desk.metric.itemCount": { en: "Items" },
1578
+ "order-desk.metric.placedAt": { en: "Placed" },
1579
+ "order-desk.tab.items": { en: "Items" },
1580
+ "order-desk.tab.payments": { en: "Payments" },
1581
+ "order-desk.tab.details": { en: "Details" },
1582
+ "order-desk.tab.internalNote": { en: "Internal note" },
1583
+ "order-desk.payments.empty": { en: "No payments yet" },
1584
+ "order-desk.payments.empty-pending": { en: "A payment is pending" },
1585
+ },
1586
+ });
1587
+
1588
+ r.screen({
1589
+ id: "orders",
1590
+ type: "projectionList",
1591
+ query: ORDER_LIST_QUERY,
1592
+ rowToneField: "tone",
1593
+ columns: [
1594
+ { field: "orderNumber", label: "order-desk.col.order" },
1595
+ { field: "customerName", label: "order-desk.col.customer" },
1596
+ {
1597
+ field: "urgencyLabel",
1598
+ label: "order-desk.col.urgency",
1599
+ display: "badge",
1600
+ badgeToneField: "urgencyTone",
1601
+ },
1602
+ {
1603
+ field: "nextStep",
1604
+ label: "order-desk.col.todo",
1605
+ hint: {
1606
+ detailField: "nextStepDue",
1607
+ narrowDetailField: "nextStepShort",
1608
+ reasonField: "nextStepReason",
1609
+ reasonTitleField: "nextStepReasonTitle",
1610
+ reasonOpenField: "nextStepReasonOpen",
1611
+ emptyLabel: "order-desk.orders.nothing-open",
1612
+ },
1613
+ width: 320,
1614
+ minWidth: 240,
1615
+ },
1616
+ { field: "openAmount", label: "order-desk.col.open-amount", hideOnNarrow: true },
1617
+ { field: "narrowMeta", label: "order-desk.col.narrow-meta", showOnNarrowOnly: true },
1618
+ ],
1619
+ defaultSort: { field: "urgency", dir: "desc" },
1620
+ sortOptions: [
1621
+ { field: "urgency", dir: "desc", label: "order-desk.sort.urgency" },
1622
+ { field: "customerName", dir: "asc", label: "order-desk.sort.customer" },
1623
+ ],
1624
+ namedFilters: [
1625
+ {
1626
+ id: "action-needed",
1627
+ label: "order-desk.filter.action-needed",
1628
+ sort: { field: "urgency", dir: "desc" },
1629
+ emptyState: {
1630
+ title: "order-desk.orders.all-done",
1631
+ description: "order-desk.orders.all-done-hint",
1632
+ },
1633
+ },
1634
+ {
1635
+ id: "reminder-due",
1636
+ label: "order-desk.filter.reminder-due",
1637
+ emptyState: {
1638
+ title: "order-desk.orders.all-done",
1639
+ description: "order-desk.orders.all-done-hint",
1640
+ },
1641
+ },
1642
+ { id: "ending-soon", label: "order-desk.filter.ending-soon" },
1643
+ ],
1644
+ namedFilterFacet: { display: "select", showCounts: true, label: "order-desk.orders.todo" },
1645
+ narrowFacets: "pills",
1646
+ table: {
1647
+ frame: "card",
1648
+ summaryRow: { query: "order-desk:query:order:summary" },
1649
+ },
1650
+ rowActions: [
1651
+ {
1652
+ kind: "navigate",
1653
+ id: "open",
1654
+ label: "order-desk.action.open",
1655
+ screen: "order-detail",
1656
+ rowClick: true,
1657
+ },
1658
+ {
1659
+ id: "remind",
1660
+ label: "order-desk.action.remind",
1661
+ handler: "order-desk:write:order:remind",
1662
+ display: "button",
1663
+ visible: { field: "canRemind", eq: true },
1664
+ },
1665
+ {
1666
+ kind: "navigate",
1667
+ id: "open-order",
1668
+ label: "order-desk.action.open-order",
1669
+ screen: "order-detail",
1670
+ display: "button",
1671
+ visible: { field: "canRemind", eq: false },
1672
+ },
1673
+ ],
1674
+ access: accessRoles,
1675
+ });
1676
+
1677
+ r.screen({
1678
+ id: "today",
1679
+ type: "dashboard",
1680
+ panels: [
1681
+ {
1682
+ kind: "text",
1683
+ id: "briefing",
1684
+ span: "two-thirds",
1685
+ narrowOrder: 1,
1686
+ query: "order-desk:query:order:briefing",
1687
+ },
1688
+ {
1689
+ kind: "stat-group",
1690
+ id: "queue-counts",
1691
+ label: "order-desk.today.inbox",
1692
+ subtitle: "order-desk.today.inbox-sub",
1693
+ span: "full",
1694
+ layout: "strip",
1695
+ icon: { react: { __component: "OrderInboxIcon" } },
1696
+ link: { label: "order-desk.today.inbox-link", screen: "orders" },
1697
+ stats: [
1698
+ {
1699
+ kind: "stat",
1700
+ id: "action-needed",
1701
+ label: "order-desk.today.stat.action-needed",
1702
+ query: ORDER_LIST_QUERY,
1703
+ valueField: "total",
1704
+ params: { namedFilter: "action-needed", limit: 1, totalCount: true },
1705
+ tone: "negative",
1706
+ navigate: { screen: "orders", namedFilter: "action-needed" },
1707
+ },
1708
+ {
1709
+ kind: "stat",
1710
+ id: "reminder-due",
1711
+ label: "order-desk.today.stat.reminder-due",
1712
+ query: ORDER_LIST_QUERY,
1713
+ valueField: "total",
1714
+ params: { namedFilter: "reminder-due", limit: 1, totalCount: true },
1715
+ tone: "warn",
1716
+ navigate: { screen: "orders", namedFilter: "reminder-due" },
1717
+ },
1718
+ {
1719
+ kind: "stat",
1720
+ id: "ending-soon",
1721
+ label: "order-desk.today.stat.ending-soon",
1722
+ query: ORDER_LIST_QUERY,
1723
+ valueField: "total",
1724
+ params: { namedFilter: "ending-soon", limit: 1, totalCount: true },
1725
+ navigate: { screen: "orders", namedFilter: "ending-soon" },
1726
+ },
1727
+ ],
1728
+ },
1729
+ {
1730
+ kind: "list",
1731
+ id: "now",
1732
+ label: "order-desk.today.now",
1733
+ span: "two-thirds",
1734
+ showHeader: false,
1735
+ showTotal: {
1736
+ text: "order-desk.today.now-total",
1737
+ narrowText: "order-desk.today.now-total-narrow",
1738
+ },
1739
+ narrow: { layout: "cards", limit: 3 },
1740
+ footerLink: {
1741
+ label: "order-desk.today.now-all",
1742
+ screen: "orders",
1743
+ namedFilter: "action-needed",
1744
+ },
1745
+ query: "order-desk:query:order:now",
1746
+ rowToneField: "tone",
1747
+ columns: [
1748
+ { field: "urgencyLabel", display: "badge", badgeToneField: "urgencyTone" },
1749
+ {
1750
+ field: "nextStep",
1751
+ hint: {
1752
+ detailField: "nextStepDue",
1753
+ narrowDetailField: "nextStepShort",
1754
+ reasonField: "nextStepReason",
1755
+ reasonTitleField: "nextStepReasonTitle",
1756
+ reasonOpenField: "nextStepReasonOpen",
1757
+ plainSentence: true,
1758
+ },
1759
+ },
1760
+ {
1761
+ field: "actionLabel",
1762
+ display: "button",
1763
+ linkScreenField: "actionScreen",
1764
+ linkParamsField: "actionParams",
1765
+ },
1766
+ ],
1767
+ },
1768
+ {
1769
+ kind: "list",
1770
+ id: "deadlines",
1771
+ label: "order-desk.today.deadlines",
1772
+ span: "third",
1773
+ showHeader: false,
1774
+ icon: { react: { __component: "DeadlinesIcon" } },
1775
+ narrow: {
1776
+ layout: "line",
1777
+ field: "title",
1778
+ moreText: "order-desk.today.deadlines-more-narrow",
1779
+ },
1780
+ rowLink: { screenField: "screen", paramsField: "params", icon: "chevron" },
1781
+ footerLink: {
1782
+ narrowOnly: true,
1783
+ label: "order-desk.today.deadlines-all",
1784
+ moreText: "order-desk.today.deadlines-more",
1785
+ narrowMoreText: "order-desk.today.deadlines-more-narrow",
1786
+ screen: "orders",
1787
+ },
1788
+ query: "order-desk:query:order:deadlines",
1789
+ columns: [{ field: "due", display: "datetime" }, { field: "title" }],
1790
+ },
1791
+ {
1792
+ kind: "list",
1793
+ id: "customers",
1794
+ label: "order-desk.today.customers",
1795
+ span: "third",
1796
+ showHeader: false,
1797
+ hideOnNarrow: true,
1798
+ rowLink: { screen: "order-detail", paramField: "params" },
1799
+ query: "order-desk:query:order:customers",
1800
+ rowToneField: "tone",
1801
+ rowToneMarker: "dot",
1802
+ columns: [
1803
+ { field: "customerName" },
1804
+ { field: "openCount", display: "badge", badgeToneField: "openTone" },
1805
+ ],
1806
+ },
1807
+ {
1808
+ kind: "stat-group",
1809
+ id: "money",
1810
+ label: "order-desk.today.money",
1811
+ subtitle: "order-desk.today.money-sub",
1812
+ span: "two-thirds",
1813
+ layout: "cards",
1814
+ columns: 3,
1815
+ hideOnNarrow: true,
1816
+ stats: [
1817
+ {
1818
+ kind: "stat",
1819
+ id: "open",
1820
+ label: "order-desk.today.stat.open",
1821
+ query: "order-desk:query:order:money",
1822
+ valueField: "open",
1823
+ },
1824
+ {
1825
+ kind: "stat",
1826
+ id: "overdue",
1827
+ label: "order-desk.today.stat.overdue",
1828
+ query: "order-desk:query:order:money",
1829
+ valueField: "overdue",
1830
+ tone: "negative",
1831
+ },
1832
+ {
1833
+ kind: "stat",
1834
+ id: "collected",
1835
+ label: "order-desk.today.stat.collected",
1836
+ query: "order-desk:query:order:money",
1837
+ valueField: "collected",
1838
+ tone: "positive",
1839
+ },
1840
+ ],
1841
+ },
1842
+ ],
1843
+ access: accessRoles,
973
1844
  });
974
1845
 
975
1846
  r.screen({
976
1847
  id: "order-detail",
977
1848
  type: "projectionDetail",
978
1849
  query: "order-desk:query:order:detail",
1850
+ focus: true,
1851
+ listScreenId: "orders",
979
1852
  header: {
980
1853
  title: "customerName",
1854
+ shortTitle: "shortTitle",
981
1855
  // Parts are joined by a separator; `format` formats the raw field value.
1856
+ narrowSubtitle: "narrowSubtitle",
982
1857
  subtitle: [
983
1858
  "orderNumber",
984
1859
  { field: "placedAt", format: { format: "date", dateStyle: "medium" } },
985
1860
  ],
986
1861
  status: "status",
987
1862
  },
1863
+ breadcrumb: { field: "path" },
1864
+ summary: { field: "summaryLine", narrowField: "summaryShort", toneField: "summaryTone" },
1865
+ banner: {
1866
+ field: "notice",
1867
+ actions: [
1868
+ {
1869
+ kind: "navigate",
1870
+ id: "banner-open",
1871
+ label: "order-desk.action.recordPayment",
1872
+ screen: "order-detail",
1873
+ icon: "plus",
1874
+ hideIcon: true,
1875
+ narrowLabel: "order-desk.action.record-short",
1876
+ },
1877
+ ],
1878
+ },
1879
+ progress: { field: "progress", placement: "beside-steps", hideOnNarrow: true },
1880
+ steps: {
1881
+ field: "steps",
1882
+ narrowLimit: 3,
1883
+ title: "order-desk.steps.title",
1884
+ emptyLabel: "order-desk.steps.empty",
1885
+ actions: [
1886
+ {
1887
+ kind: "navigate",
1888
+ id: "step-open",
1889
+ label: "order-desk.action.refreshOrder",
1890
+ screen: "order-detail",
1891
+ icon: "refresh",
1892
+ },
1893
+ {
1894
+ kind: "navigate",
1895
+ id: "prepare",
1896
+ label: "order-desk.action.prepare",
1897
+ screen: "order-detail",
1898
+ display: "link",
1899
+ icon: "sparkles",
1900
+ visible: { field: "canPrepare", eq: true },
1901
+ },
1902
+ ],
1903
+ },
1904
+ metricsStyle: "tiles",
1905
+ metricsPlacement: { narrow: "after-guidance" },
988
1906
  metrics: [
989
- { field: "totalAmount", label: "order-desk.metric.totalAmount" },
990
- { field: "outstandingAmount", label: "order-desk.metric.outstandingAmount" },
991
- { field: "itemCount", label: "order-desk.metric.itemCount" },
992
- { field: "placedAt", label: "order-desk.metric.placedAt" },
1907
+ {
1908
+ field: "totalAmount",
1909
+ label: "order-desk.metric.totalAmount",
1910
+ subField: "totalNote",
1911
+ },
1912
+ {
1913
+ field: "outstandingAmount",
1914
+ label: "order-desk.metric.outstandingAmount",
1915
+ labelField: "outstandingLabel",
1916
+ subField: "outstandingNote",
1917
+ tone: "warn",
1918
+ toneField: "outstandingTone",
1919
+ navigate: { tab: "payments" },
1920
+ },
1921
+ {
1922
+ field: "itemCount",
1923
+ label: "order-desk.metric.itemCount",
1924
+ navigate: { tab: "items" },
1925
+ },
1926
+ { field: "placedAt", label: "order-desk.metric.placedAt", hideOnNarrow: true },
993
1927
  ],
994
1928
  layout: {
995
1929
  mode: "tabs",
@@ -998,24 +1932,34 @@ export function createOrderDeskFeature(): FeatureDefinition {
998
1932
  id: "items",
999
1933
  kind: "relatedList",
1000
1934
  title: "order-desk.tab.items",
1935
+ countField: "itemsCount",
1001
1936
  query: "order-desk:query:order:items",
1002
1937
  columns: [
1003
- "sku",
1004
- "description",
1005
- "quantity",
1006
- { field: "unitPrice", renderer: { format: "currency", symbol: "€" } },
1938
+ { field: "sku", label: "order-desk.col.sku" },
1939
+ { field: "description", label: "order-desk.col.description" },
1940
+ { field: "quantity", label: "order-desk.col.quantity" },
1941
+ {
1942
+ field: "unitPrice",
1943
+ label: "order-desk.col.unit-price",
1944
+ renderer: { format: "currency", symbol: "€" },
1945
+ },
1007
1946
  ],
1008
1947
  },
1009
1948
  {
1010
1949
  id: "payments",
1011
1950
  kind: "relatedList",
1012
1951
  title: "order-desk.tab.payments",
1952
+ countField: "paymentsCount",
1013
1953
  query: "order-desk:query:order:payments",
1014
1954
  columns: [
1015
- "paidAt",
1016
- { field: "amount", renderer: { format: "currency", symbol: "€" } },
1017
- "method",
1018
- "status",
1955
+ { field: "paidAt", label: "order-desk.col.paid-at" },
1956
+ {
1957
+ field: "amount",
1958
+ label: "order-desk.col.amount",
1959
+ renderer: { format: "currency", symbol: "€" },
1960
+ },
1961
+ { field: "method", label: "order-desk.col.method" },
1962
+ { field: "status", label: "order-desk.col.status" },
1019
1963
  ],
1020
1964
  emptyState: {
1021
1965
  title: "order-desk.payments.empty",
@@ -1067,8 +2011,534 @@ export function createOrderDeskFeature(): FeatureDefinition {
1067
2011
  },
1068
2012
  ],
1069
2013
  inlineActions: ["download-invoice"],
1070
- access: { roles: ["Support", "Admin"] },
2014
+ access: accessRoles,
1071
2015
  });
1072
2016
  });
1073
2017
  }
1074
2018
  ```
2019
+
2020
+ ### src/order-board.ts
2021
+
2022
+ ```ts
2023
+ // In-memory order data shared by the real query handlers (feature.ts) and the e2e
2024
+ // mock dispatcher, so the browser fixture answers exactly what the server would.
2025
+
2026
+ import { z } from "zod";
2027
+
2028
+ export const ORDER_DETAIL_SCREEN_QN = "order-desk:screen:order-detail";
2029
+
2030
+ export const NAMED_FILTER_IDS = ["action-needed", "reminder-due", "ending-soon"] as const;
2031
+ export type OrderNamedFilterId = (typeof NAMED_FILTER_IDS)[number];
2032
+
2033
+ const AGGREGATE_MEASURE_KINDS = ["sum", "avg", "count", "min", "max"] as const;
2034
+
2035
+ export const orderListSchema = z.object({
2036
+ namedFilter: z.enum(NAMED_FILTER_IDS).optional(),
2037
+ search: z.string().optional(),
2038
+ sort: z.string().optional(),
2039
+ sortDirection: z.enum(["asc", "desc"]).optional(),
2040
+ limit: z.number().int().positive().max(200).optional(),
2041
+ offset: z.number().int().nonnegative().optional(),
2042
+ totalCount: z.boolean().optional(),
2043
+ aggregate: z
2044
+ .object({
2045
+ groupBy: z.string().optional(),
2046
+ measures: z
2047
+ .array(z.object({ field: z.string(), kind: z.enum(AGGREGATE_MEASURE_KINDS) }))
2048
+ .default([]),
2049
+ })
2050
+ .optional(),
2051
+ });
2052
+
2053
+ export type OrderListPayload = z.infer<typeof orderListSchema>;
2054
+
2055
+ // The list sends its narrowing (named filter, search) to the summary query as well; limit and paging never reach it.
2056
+ export const orderSummarySchema = z.object({
2057
+ namedFilter: z.enum(NAMED_FILTER_IDS).optional(),
2058
+ search: z.string().optional(),
2059
+ });
2060
+
2061
+ export type OrderSummaryPayload = z.infer<typeof orderSummarySchema>;
2062
+
2063
+ type RowTone = "ok" | "warn" | "bad" | "critical" | "neutral";
2064
+ type UrgencyTone = "negative" | "warn" | "neutral" | "positive";
2065
+
2066
+ export type OrderRow = {
2067
+ readonly id: string;
2068
+ readonly orderNumber: string;
2069
+ readonly customerName: string;
2070
+ readonly tone: RowTone;
2071
+ readonly urgency: number;
2072
+ readonly urgencyLabel: string;
2073
+ readonly urgencyTone: UrgencyTone;
2074
+ readonly nextStep: string;
2075
+ readonly nextStepDue: string;
2076
+ readonly nextStepReason: string;
2077
+ readonly nextStepReasonTitle?: string;
2078
+ readonly nextStepReasonOpen?: boolean;
2079
+ readonly openAmount: number;
2080
+ readonly status: "processing" | "shipped" | "closing" | "delivered";
2081
+ readonly actionLabel: string;
2082
+ readonly canRemind: boolean;
2083
+ };
2084
+
2085
+ const ORDER_ROWS: readonly OrderRow[] = [
2086
+ {
2087
+ id: "o1",
2088
+ orderNumber: "SO-10482",
2089
+ customerName: "Aiko Tanaka",
2090
+ tone: "bad",
2091
+ urgency: 92,
2092
+ urgencyLabel: "Critical",
2093
+ urgencyTone: "negative",
2094
+ nextStep: "Send payment reminder",
2095
+ nextStepDue: "by Friday",
2096
+ nextStepReason: "312 EUR is 14 days overdue.\nTwo earlier mails stayed unanswered.",
2097
+ nextStepReasonTitle: "Rule 10 · Payment overdue.",
2098
+ nextStepReasonOpen: true,
2099
+ openAmount: 312,
2100
+ status: "processing",
2101
+ actionLabel: "Send reminder",
2102
+ canRemind: true,
2103
+ },
2104
+ {
2105
+ id: "o2",
2106
+ orderNumber: "SO-10483",
2107
+ customerName: "Jonas Weber",
2108
+ tone: "ok",
2109
+ urgency: 0,
2110
+ urgencyLabel: "",
2111
+ urgencyTone: "neutral",
2112
+ nextStep: "",
2113
+ nextStepDue: "",
2114
+ nextStepReason: "",
2115
+ openAmount: 0,
2116
+ status: "delivered",
2117
+ actionLabel: "",
2118
+ canRemind: false,
2119
+ },
2120
+ {
2121
+ id: "o3",
2122
+ orderNumber: "SO-10484",
2123
+ customerName: "Maria Lopez",
2124
+ tone: "warn",
2125
+ urgency: 74,
2126
+ urgencyLabel: "Overdue",
2127
+ urgencyTone: "negative",
2128
+ nextStep: "Confirm the delivery slot",
2129
+ nextStepDue: "Tuesday",
2130
+ nextStepReason: "The carrier asked twice for a date.",
2131
+ openAmount: 180,
2132
+ status: "shipped",
2133
+ actionLabel: "Open order",
2134
+ canRemind: false,
2135
+ },
2136
+ {
2137
+ id: "o4",
2138
+ orderNumber: "SO-10485",
2139
+ customerName: "Tom Becker",
2140
+ tone: "warn",
2141
+ urgency: 61,
2142
+ urgencyLabel: "Urgent",
2143
+ urgencyTone: "warn",
2144
+ nextStep: "Call about the backorder",
2145
+ nextStepDue: "tomorrow",
2146
+ nextStepReason: "Two of five items are backordered.\nThe customer expects a full delivery.",
2147
+ openAmount: 540,
2148
+ status: "processing",
2149
+ actionLabel: "Open order",
2150
+ canRemind: false,
2151
+ },
2152
+ {
2153
+ id: "o5",
2154
+ orderNumber: "SO-10486",
2155
+ customerName: "Priya Nair",
2156
+ tone: "neutral",
2157
+ urgency: 35,
2158
+ urgencyLabel: "Due",
2159
+ urgencyTone: "neutral",
2160
+ nextStep: "Review the credit limit",
2161
+ nextStepDue: "next week",
2162
+ nextStepReason: "The open balance grew past the agreed limit.",
2163
+ openAmount: 1190,
2164
+ status: "closing",
2165
+ actionLabel: "Open order",
2166
+ canRemind: false,
2167
+ },
2168
+ {
2169
+ id: "o6",
2170
+ orderNumber: "SO-10487",
2171
+ customerName: "Lars Hansen",
2172
+ tone: "ok",
2173
+ urgency: 0,
2174
+ urgencyLabel: "",
2175
+ urgencyTone: "neutral",
2176
+ nextStep: "",
2177
+ nextStepDue: "",
2178
+ nextStepReason: "",
2179
+ openAmount: 0,
2180
+ status: "delivered",
2181
+ actionLabel: "",
2182
+ canRemind: false,
2183
+ },
2184
+ {
2185
+ id: "o7",
2186
+ orderNumber: "SO-10488",
2187
+ customerName: "Emma Rossi",
2188
+ tone: "bad",
2189
+ urgency: 80,
2190
+ urgencyLabel: "Overdue",
2191
+ urgencyTone: "negative",
2192
+ nextStep: "Send payment reminder",
2193
+ nextStepDue: "Thursday",
2194
+ nextStepReason: "180 EUR is 9 days overdue.",
2195
+ openAmount: 180,
2196
+ status: "processing",
2197
+ actionLabel: "Send reminder",
2198
+ canRemind: true,
2199
+ },
2200
+ {
2201
+ id: "o8",
2202
+ orderNumber: "SO-10489",
2203
+ customerName: "Kenji Mori",
2204
+ tone: "ok",
2205
+ urgency: 0,
2206
+ urgencyLabel: "",
2207
+ urgencyTone: "neutral",
2208
+ nextStep: "",
2209
+ nextStepDue: "",
2210
+ nextStepReason: "",
2211
+ openAmount: 95,
2212
+ status: "closing",
2213
+ actionLabel: "",
2214
+ canRemind: false,
2215
+ },
2216
+ ];
2217
+
2218
+ const NAMED_FILTER_PREDICATES: Readonly<Record<OrderNamedFilterId, (row: OrderRow) => boolean>> = {
2219
+ "action-needed": (row) => row.nextStep !== "",
2220
+ "reminder-due": (row) => row.canRemind && row.nextStepDue === "today",
2221
+ "ending-soon": (row) => row.status === "closing",
2222
+ };
2223
+
2224
+ const DEFAULT_PAGE_SIZE = 50;
2225
+
2226
+ function matchesSearch(row: OrderRow, search: string | undefined): boolean {
2227
+ if (search === undefined || search === "") return true;
2228
+ const needle = search.toLowerCase();
2229
+ return (
2230
+ row.orderNumber.toLowerCase().includes(needle) ||
2231
+ row.customerName.toLowerCase().includes(needle)
2232
+ );
2233
+ }
2234
+
2235
+ function fieldValue(row: OrderRow, field: string): unknown {
2236
+ return Object.entries(row).find(([key]) => key === field)?.[1];
2237
+ }
2238
+
2239
+ function compareRows(
2240
+ field: string,
2241
+ direction: "asc" | "desc",
2242
+ ): (a: OrderRow, b: OrderRow) => number {
2243
+ const sign = direction === "asc" ? 1 : -1;
2244
+ return (a, b) => {
2245
+ const left = fieldValue(a, field);
2246
+ const right = fieldValue(b, field);
2247
+ if (typeof left === "number" && typeof right === "number") return sign * (left - right);
2248
+ return sign * String(left).localeCompare(String(right));
2249
+ };
2250
+ }
2251
+
2252
+ function filteredRows(payload: OrderListPayload): readonly OrderRow[] {
2253
+ const predicate =
2254
+ payload.namedFilter === undefined ? undefined : NAMED_FILTER_PREDICATES[payload.namedFilter];
2255
+ return ORDER_ROWS.filter(
2256
+ (row) => (predicate === undefined || predicate(row)) && matchesSearch(row, payload.search),
2257
+ );
2258
+ }
2259
+
2260
+ function numericValues(rows: readonly OrderRow[], field: string): number[] {
2261
+ return rows.flatMap((row) => {
2262
+ const value = fieldValue(row, field);
2263
+ return typeof value === "number" ? [value] : [];
2264
+ });
2265
+ }
2266
+
2267
+ function measureOf(
2268
+ kind: (typeof AGGREGATE_MEASURE_KINDS)[number],
2269
+ rows: readonly OrderRow[],
2270
+ field: string,
2271
+ ): number | null {
2272
+ if (kind === "count") return rows.length;
2273
+ const values = numericValues(rows, field);
2274
+ if (values.length === 0) return null;
2275
+ const sum = values.reduce((total, value) => total + value, 0);
2276
+ if (kind === "sum") return sum;
2277
+ if (kind === "avg") return sum / values.length;
2278
+ return kind === "min" ? Math.min(...values) : Math.max(...values);
2279
+ }
2280
+
2281
+ export type OrderListAnswer =
2282
+ | {
2283
+ readonly groups: readonly {
2284
+ readonly key: null;
2285
+ readonly count: number;
2286
+ readonly measures: readonly (number | null)[];
2287
+ }[];
2288
+ }
2289
+ | {
2290
+ readonly rows: readonly (OrderRow & {
2291
+ readonly narrowMeta: string;
2292
+ readonly actionScreen?: string;
2293
+ readonly actionParams?: { readonly entityId: string };
2294
+ })[];
2295
+ readonly nextCursor: null;
2296
+ readonly total?: number;
2297
+ };
2298
+
2299
+ export function answerOrderList(payload: OrderListPayload): OrderListAnswer {
2300
+ const matching = filteredRows(payload);
2301
+ if (payload.aggregate !== undefined) {
2302
+ return {
2303
+ groups: [
2304
+ {
2305
+ key: null,
2306
+ count: matching.length,
2307
+ measures: payload.aggregate.measures.map((m) => measureOf(m.kind, matching, m.field)),
2308
+ },
2309
+ ],
2310
+ };
2311
+ }
2312
+ const ordered =
2313
+ payload.sort === undefined
2314
+ ? matching
2315
+ : [...matching].sort(compareRows(payload.sort, payload.sortDirection ?? "asc"));
2316
+ const offset = payload.offset ?? 0;
2317
+ const rows = ordered.slice(offset, offset + (payload.limit ?? DEFAULT_PAGE_SIZE)).map((row) => ({
2318
+ ...row,
2319
+ narrowMeta: `${euro(row.openAmount)} open · ${row.status}`,
2320
+ nextStepShort: row.nextStepDue === "" ? "" : `${row.nextStepDue} · ${euro(row.openAmount)}`,
2321
+ ...(row.nextStep !== "" && {
2322
+ actionScreen: ORDER_DETAIL_SCREEN_QN,
2323
+ actionParams: { entityId: row.id },
2324
+ }),
2325
+ }));
2326
+ return {
2327
+ rows,
2328
+ nextCursor: null,
2329
+ ...(payload.totalCount === true && { total: matching.length }),
2330
+ };
2331
+ }
2332
+
2333
+ export function answerOrderSummary(payload: OrderSummaryPayload) {
2334
+ const matching = filteredRows(payload);
2335
+ const overdue = matching.filter((row) => row.urgencyTone === "negative");
2336
+ return {
2337
+ items: [
2338
+ { label: "Orders", value: matching.length, column: "orderNumber" },
2339
+ {
2340
+ label: "Open",
2341
+ value: euro(matching.reduce((total, row) => total + row.openAmount, 0)),
2342
+ column: "openAmount",
2343
+ },
2344
+ {
2345
+ label: "Overdue",
2346
+ value: euro(overdue.reduce((total, row) => total + row.openAmount, 0)),
2347
+ tone: "bad",
2348
+ column: "urgencyLabel",
2349
+ },
2350
+ ],
2351
+ };
2352
+ }
2353
+
2354
+ function actionNeededRows(limit: number): readonly OrderRow[] {
2355
+ return ORDER_ROWS.filter(NAMED_FILTER_PREDICATES["action-needed"])
2356
+ .sort(compareRows("urgency", "desc"))
2357
+ .slice(0, limit);
2358
+ }
2359
+
2360
+ const NOW_LIST_LIMIT = 4;
2361
+
2362
+ export function answerNowList() {
2363
+ return {
2364
+ rows: actionNeededRows(NOW_LIST_LIMIT).map((row) => ({
2365
+ ...row,
2366
+ nextStepShort: `${row.nextStepDue} · ${euro(row.openAmount)}`,
2367
+ actionScreen: ORDER_DETAIL_SCREEN_QN,
2368
+ actionParams: { entityId: row.id },
2369
+ })),
2370
+ total: actionNeededRows(ORDER_ROWS.length).length,
2371
+ };
2372
+ }
2373
+
2374
+ export function answerBriefing() {
2375
+ const open = actionNeededRows(ORDER_ROWS.length);
2376
+ const [first] = open;
2377
+ return {
2378
+ blocks: [
2379
+ {
2380
+ kind: "paragraph",
2381
+ emphasis: "lead",
2382
+ text: `${open.length} orders need you today.${
2383
+ first === undefined
2384
+ ? ""
2385
+ : ` Most pressing is ${first.orderNumber} from ${first.customerName}.`
2386
+ }`,
2387
+ },
2388
+ {
2389
+ kind: "hint",
2390
+ text: "Sorted by urgency. Open an order and let the assistant prepare the step.",
2391
+ },
2392
+ ],
2393
+ narrowBlocks: [
2394
+ { kind: "paragraph", emphasis: "lead", text: `${open.length} orders need you today.` },
2395
+ { kind: "hint", text: "Tuesday, 3 November · as of 06:00" },
2396
+ ],
2397
+ };
2398
+ }
2399
+
2400
+ const DEADLINES = [
2401
+ { id: "d1", due: "2026-11-06T09:00:00Z", title: "Reminder SO-10482", orderId: "o1" },
2402
+ { id: "d2", due: "2026-11-05T14:00:00Z", title: "Call Tom Becker", orderId: "o4" },
2403
+ { id: "d3", due: "2026-11-10T10:30:00Z", title: "Credit review SO-10486", orderId: "o5" },
2404
+ { id: "d4", due: "2026-11-12T08:00:00Z", title: "Delivery slot SO-10484", orderId: "o3" },
2405
+ ] as const;
2406
+
2407
+ export function answerDeadlines() {
2408
+ return {
2409
+ rows: [...DEADLINES]
2410
+ .sort((a, b) => a.due.localeCompare(b.due))
2411
+ .map((deadline) => ({
2412
+ id: deadline.id,
2413
+ due: deadline.due,
2414
+ title: deadline.title,
2415
+ screen: ORDER_DETAIL_SCREEN_QN,
2416
+ params: { entityId: deadline.orderId },
2417
+ })),
2418
+ };
2419
+ }
2420
+
2421
+ const CUSTOMERS = [
2422
+ {
2423
+ id: "c1",
2424
+ customerName: "Aiko Tanaka",
2425
+ openCount: 3,
2426
+ openTone: "negative",
2427
+ tone: "bad",
2428
+ orderId: "o1",
2429
+ },
2430
+ {
2431
+ id: "c2",
2432
+ customerName: "Priya Nair",
2433
+ openCount: 2,
2434
+ openTone: "warn",
2435
+ tone: "warn",
2436
+ orderId: "o5",
2437
+ },
2438
+ {
2439
+ id: "c3",
2440
+ customerName: "Tom Becker",
2441
+ openCount: 1,
2442
+ openTone: "neutral",
2443
+ tone: "neutral",
2444
+ orderId: "o4",
2445
+ },
2446
+ {
2447
+ id: "c4",
2448
+ customerName: "Jonas Weber",
2449
+ openCount: 0,
2450
+ openTone: "positive",
2451
+ tone: "ok",
2452
+ orderId: "o2",
2453
+ },
2454
+ ] as const;
2455
+
2456
+ export function answerCustomers() {
2457
+ return {
2458
+ rows: CUSTOMERS.map((customer) => ({
2459
+ id: customer.id,
2460
+ customerName: customer.customerName,
2461
+ openCount: customer.openCount,
2462
+ openTone: customer.openTone,
2463
+ tone: customer.tone,
2464
+ screen: ORDER_DETAIL_SCREEN_QN,
2465
+ params: { entityId: customer.orderId },
2466
+ })),
2467
+ };
2468
+ }
2469
+
2470
+ function euro(amount: number): string {
2471
+ return `€ ${amount.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
2472
+ }
2473
+
2474
+ export function answerMoney() {
2475
+ const open = ORDER_ROWS.reduce((total, row) => total + row.openAmount, 0);
2476
+ const overdue = ORDER_ROWS.filter((row) => row.urgencyTone === "negative").reduce(
2477
+ (total, row) => total + row.openAmount,
2478
+ 0,
2479
+ );
2480
+ return {
2481
+ open: euro(open),
2482
+ overdue: euro(overdue),
2483
+ collected: euro(1860),
2484
+ openOrders: String(ORDER_ROWS.filter((row) => row.openAmount > 0).length),
2485
+ };
2486
+ }
2487
+
2488
+ export function answerOrderDetail(id: string) {
2489
+ return {
2490
+ id,
2491
+ customerName: "Aiko Tanaka",
2492
+ orderNumber: "SO-10482",
2493
+ shortTitle: "SO-10482",
2494
+ status: "processing",
2495
+ totalAmount: "€ 1,248.00",
2496
+ totalNote: "2 payments",
2497
+ outstandingAmount: "€ 312.00",
2498
+ outstandingNote: "14 days overdue",
2499
+ outstandingLabel: "Outstanding since 01.12.",
2500
+ outstandingTone: "bad",
2501
+ itemCount: "3",
2502
+ itemsCount: 3,
2503
+ paymentsCount: 2,
2504
+ placedAt: "2026-08-21",
2505
+ shippingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
2506
+ billingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
2507
+ salesRep: "Jonas Weber",
2508
+ path: [{ label: "Orders" }, { label: "Aiko Tanaka" }, { label: "SO-10482" }],
2509
+ summaryLine: "Waiting for the second payment",
2510
+ summaryShort: "Second payment open.",
2511
+ summaryTone: "warn",
2512
+ narrowSubtitle: "SO-10482 · placed 21 Aug",
2513
+ notice: { title: "Payment overdue", text: "312 EUR is 14 days overdue", tone: "bad" },
2514
+ steps: [
2515
+ {
2516
+ id: "remind",
2517
+ title: "Send payment reminder",
2518
+ detail: "by Friday",
2519
+ narrowDetail: "Fri",
2520
+ tone: "warn",
2521
+ whyOpen: true,
2522
+ whyTitle: "Rule 10 · Payment overdue.",
2523
+ why: "The invoice is 14 days overdue.\nTwo earlier mails stayed unanswered.\nThe credit limit is 1,500 EUR.",
2524
+ canPrepare: true,
2525
+ },
2526
+ { id: "escalate", title: "Escalate to accounting", canPrepare: false },
2527
+ { id: "credit", title: "Review the credit limit", canPrepare: false },
2528
+ { id: "handover", title: "Plan the handover", canPrepare: false },
2529
+ { id: "close", title: "Close the order", canPrepare: false },
2530
+ ],
2531
+ progress: [
2532
+ {
2533
+ title: "Order to cash",
2534
+ currentIndex: 1,
2535
+ steps: [
2536
+ { id: "placed", label: "Placed", done: true, detail: "21 Aug" },
2537
+ { id: "paid", label: "Paid", done: false, detail: "312 EUR open" },
2538
+ { id: "shipped", label: "Shipped", done: false },
2539
+ ],
2540
+ },
2541
+ ],
2542
+ };
2543
+ }
2544
+ ```