@cosmicdrift/kumiko-framework 0.414.0 → 0.416.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/agents/api/framework-engine.md +46 -8
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +69 -4
  4. package/agents/api/renderer-web.md +27 -4
  5. package/agents/api/types.md +68 -16
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +39 -7
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/embedded.md +24 -1
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/record-detail-layout.md +113 -7
  12. package/agents/examples/signature.md +186 -0
  13. package/agents/examples/writeform-section.md +1 -0
  14. package/agents/examples.md +2 -0
  15. package/agents/features-index.md +4 -0
  16. package/agents/features.md +14 -0
  17. package/agents/widgets.md +7 -0
  18. package/dist/api/request-context-internals.d.ts +2 -0
  19. package/dist/api/request-context-scopes.js +9 -2
  20. package/dist/api/request-context.js +1 -1
  21. package/dist/api/routes.js +4 -4
  22. package/dist/api/server-event-dispatcher.js +3 -0
  23. package/dist/api/server-routes.js +2 -0
  24. package/dist/db/parent-ref-clause.js +31 -3
  25. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  26. package/dist/db/parent-ref-global-hosts.js +50 -12
  27. package/dist/db/queries/rls-boot-catalog.js +5 -6
  28. package/dist/db/queries/rls-shape.d.ts +1 -0
  29. package/dist/db/queries/rls-shape.js +21 -6
  30. package/dist/db/table-builder.js +3 -1
  31. package/dist/engine/boot-validator/boot-phases.js +5 -0
  32. package/dist/engine/boot-validator/boot-rules.d.ts +144 -9
  33. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  34. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  35. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  36. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  37. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  38. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  39. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  40. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  41. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +17 -2
  42. package/dist/engine/boot-validator/list-row-guidance-rules.js +17 -2
  43. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  44. package/dist/engine/boot-validator/list-row-guidance.js +45 -1
  45. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  46. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  47. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  48. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  49. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  50. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  51. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  52. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  53. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  54. package/dist/engine/boot-validator/query-refs.js +14 -1
  55. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  56. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  57. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  58. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  59. package/dist/engine/boot-validator/screens-actions.js +56 -16
  60. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  61. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  62. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  63. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  64. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  65. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  68. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  69. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  70. package/dist/engine/boot-validator/screens-forms.js +108 -2
  71. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  72. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  73. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  74. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  75. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  76. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  77. package/dist/engine/boot-validator/screens-lists.js +4 -1
  78. package/dist/engine/build-config-feature-schema.js +5 -35
  79. package/dist/engine/config-access-rules.d.ts +3 -0
  80. package/dist/engine/config-access-rules.js +34 -0
  81. package/dist/engine/factories.d.ts +2 -0
  82. package/dist/engine/named-filter-roles.js +6 -14
  83. package/dist/engine/project-app-schema-for-roles.js +2 -0
  84. package/dist/engine/schema-builder.js +3 -1
  85. package/dist/engine/soft-delete-cleanup.js +2 -0
  86. package/dist/errors/reasons.d.ts +1 -0
  87. package/dist/errors/reasons.js +4 -0
  88. package/dist/files/file-routes.d.ts +2 -0
  89. package/dist/files/file-routes.js +85 -22
  90. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  91. package/dist/files/foreign-tenant-file-read.js +64 -0
  92. package/dist/i18n/required-surface-keys.js +28 -7
  93. package/dist/jobs/job-runner-execution.js +3 -0
  94. package/dist/jobs/job-runner-types.d.ts +1 -0
  95. package/dist/jobs/job-runner.js +8 -0
  96. package/dist/pipeline/context-services.d.ts +1 -1
  97. package/dist/pipeline/context-services.js +1 -1
  98. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  99. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  100. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  101. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  102. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  103. package/dist/search/meilisearch-adapter-internals.js +5 -0
  104. package/dist/search/meilisearch-adapter.d.ts +1 -0
  105. package/dist/search/meilisearch-adapter.js +3 -2
  106. package/dist/ui-types/card-column-roles.d.ts +2 -0
  107. package/dist/ui-types/card-column-roles.js +15 -0
  108. package/dist/ui-types/index.d.ts +2 -2
  109. package/dist/ui-types/index.js +1 -1
  110. package/package.json +3 -3
  111. package/presets/biome-plugins/no-date-api.grit +3 -1
  112. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  113. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  114. package/presets/biome-rules.json +12 -10
  115. package/src/changes.json +99 -0
@@ -81,6 +81,17 @@ deletion grace period.
81
81
  projection rebuild recomputes it from the (now undecryptable) ciphertext
82
82
  to `NULL`.
83
83
 
84
+ ## Irreversible operations in jobs
85
+
86
+ `forget`, hard deletes, `kms.eraseKey` and writes to `readAsInstruction` fields are gated: they run only from a
87
+ handler marked `agent: { risk: "high" }`. A job or an event consumer has no handler entry, so it must declare
88
+ `irreversibleWithoutEntryHandler` on `r.job` or `r.multiStreamProjection`, or the gate refuses with
89
+ `irreversible_operation_without_entry_handler`. The value names why no entry handler exists:
90
+ `rebuildable-derived-data` (the data is derived and a rebuild recreates it), `high-risk-or-cron-pipeline`
91
+ (a maintenance pipeline that is high-risk by design, like `purge-archived-comments`) or
92
+ `per-dispatch-record-key` (the key belongs to one dispatch record). Hooks and routes never inherit the
93
+ declaration; they dispatch a `risk: "high"` handler instead.
94
+
84
95
  ## Source files
85
96
 
86
97
  ### src/__tests__/feature.integration.test.ts
@@ -114,6 +125,7 @@ import {
114
125
  resetBlindIndexKeyForTests,
115
126
  resetPiiSubjectKmsForTests,
116
127
  resetTestTables,
128
+ waitFor,
117
129
  } from "@cosmicdrift/kumiko-testing/helpers";
118
130
  import {
119
131
  setupTestStack,
@@ -128,7 +140,7 @@ let kms: InMemoryKmsAdapter;
128
140
  const admin = TestUsers.admin;
129
141
 
130
142
  beforeAll(async () => {
131
- stack = await setupTestStack({ features: [hrFeature] });
143
+ stack = await setupTestStack({ features: [hrFeature], jobs: { consumerLane: "worker" } });
132
144
  await unsafeCreateEntityTable(stack.db, employeeEntity);
133
145
  await unsafeCreateEntityTable(stack.db, hrCommentEntity);
134
146
  await createEventsTable(stack.db);
@@ -210,6 +222,29 @@ describe("crypto-shredding-hr", () => {
210
222
  expect(rows[0]?.body).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${employeeId}:`);
211
223
  });
212
224
 
225
+ test("purge-archived-comments job forgets the comment row; its declaration lets the cron run past the gate", async () => {
226
+ const employeeId = await createEmployee();
227
+ const comment = await stack.http.writeOk<SaveContext>(
228
+ "hr:write:hr-comment:create",
229
+ { employeeId, body: "archived note", authorName: "Manager X" },
230
+ admin,
231
+ );
232
+ const commentId = String(comment.id);
233
+
234
+ await stack.jobRunner?.dispatch("hr:job:purge-archived-comments", {
235
+ commentIds: [commentId],
236
+ tenantId: admin.tenantId,
237
+ });
238
+
239
+ await waitFor(async () => {
240
+ const rows = await asRawClient(stack.db).unsafe(
241
+ "SELECT id FROM read_hr_comments WHERE id = $1",
242
+ [commentId],
243
+ );
244
+ expect(rows).toHaveLength(0);
245
+ });
246
+ });
247
+
213
248
  test("forget: eraseKey renders [[erased]] for the employee AND comments about them", async () => {
214
249
  const employeeId = await createEmployee();
215
250
  await stack.http.writeOk<SaveContext>(
@@ -278,7 +313,9 @@ describe("crypto-shredding-hr — blind-index lookups", () => {
278
313
  ### src/feature.ts
279
314
 
280
315
  ```ts
316
+ import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
281
317
  import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
318
+ import * as z from "zod";
282
319
 
283
320
  export const employeeEntity = createEntity({
284
321
  table: "read_hr_employees",
@@ -300,6 +337,13 @@ export const hrCommentEntity = createEntity({
300
337
  softDelete: true,
301
338
  });
302
339
 
340
+ const hrCommentTable = buildEntityTable("hr-comment", hrCommentEntity);
341
+ const hrCommentExecutor = createEventStoreExecutor(hrCommentTable, hrCommentEntity, {
342
+ entityName: "hr-comment",
343
+ });
344
+
345
+ const purgeArchivedCommentsPayload = z.object({ commentIds: z.array(z.uuid()) });
346
+
303
347
  const hrWrite = { access: { roles: ["Admin"] } } as const;
304
348
  const hrRead = { access: { roles: ["Admin"] } } as const;
305
349
 
@@ -315,5 +359,23 @@ export const hrFeature = defineFeature("hr", (r) => {
315
359
  read: hrRead,
316
360
  verbs: { update: false, delete: false, restore: false, list: false },
317
361
  });
362
+
363
+ // A job runs without a write-handler entry, so the irreversible-operation gate refuses
364
+ // `forget` here unless the job declares why it may. Remove the declaration and the run fails.
365
+ r.job(
366
+ "purge-archived-comments",
367
+ {
368
+ trigger: { maintenance: true },
369
+ runIn: "worker",
370
+ irreversibleWithoutEntryHandler: "high-risk-or-cron-pipeline",
371
+ },
372
+ async (payload, ctx) => {
373
+ const { commentIds } = purgeArchivedCommentsPayload.parse(payload);
374
+ for (const id of commentIds) {
375
+ const result = await hrCommentExecutor.forget({ id }, ctx.systemUser, ctx.db);
376
+ if (!result.isSuccess) throw new Error(`purge of hr-comment ${id} failed`);
377
+ }
378
+ },
379
+ );
318
380
  });
319
381
  ```
@@ -34,6 +34,10 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
34
34
  entries (`{ label, from }`). The handler wraps its schema with
35
35
  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
36
36
  so totals sent by the client are replaced on the server.
37
+ - **Redirect with search params**: after submit, `invoice-receive` redirects to
38
+ `invoice-list` with `searchParams: { "invoice-list.q": "invoiceNumber" }`, so the list opens
39
+ with the number the handler returns in its search box. The receive handler stores nothing in
40
+ this recipe; the search finds invoices saved through `invoice-edit` with that number.
37
41
 
38
42
  ## When to reach for it
39
43
 
@@ -410,6 +414,7 @@ describe("invoice line items with select/reference/derived/totals metadata", ()
410
414
 
411
415
  describe("invoice receive form derives its totals on the server", () => {
412
416
  type ReceiveTotals = {
417
+ invoiceNumber: string;
413
418
  netTotal: { amount: number; currency: string };
414
419
  vatTotal: { amount: number; currency: string };
415
420
  grossTotal: { amount: number; currency: string };
@@ -432,7 +437,10 @@ describe("invoice receive form derives its totals on the server", () => {
432
437
  },
433
438
  admin,
434
439
  );
440
+ // The screen's redirect searchParams read `invoiceNumber` from this payload; the
441
+ // stack booted, so boot validation accepted the redirect to the invoice list.
435
442
  expect(totals).toEqual({
443
+ invoiceNumber: "RE-2026-0042",
436
444
  netTotal: eur(30.05),
437
445
  vatTotal: eur(3.31),
438
446
  grossTotal: eur(33.36),
@@ -534,6 +542,12 @@ export const invoiceEntity = createEntity({
534
542
  table: "read_sample_invoices",
535
543
  fields: {
536
544
  customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
545
+ // Business data, so the list can search it: invoice-receive redirects here by number.
546
+ invoiceNumber: createTextField({
547
+ personal: false,
548
+ reason: "is_business_data",
549
+ searchable: true,
550
+ }),
537
551
  lines: createEmbeddedListField(
538
552
  {
539
553
  product: { type: "reference", entity: "product", required: true },
@@ -638,10 +652,16 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
638
652
  type: "entityEdit",
639
653
  entity: "invoice",
640
654
  layout: {
641
- sections: [{ columns: 1, fields: ["customer", "lines"] }],
655
+ sections: [{ columns: 1, fields: ["invoiceNumber", "customer", "lines"] }],
642
656
  },
643
657
  });
644
658
 
659
+ r.screen({
660
+ id: "invoice-list",
661
+ type: "entityList",
662
+ entity: "invoice",
663
+ columns: ["invoiceNumber", "customer"],
664
+ });
645
665
  r.screen(invoiceReceiveScreen);
646
666
  });
647
667
  ```
@@ -755,6 +775,7 @@ export const invoiceReceive = defineWriteHandler({
755
775
  handler: async (event) => ({
756
776
  isSuccess: true,
757
777
  data: {
778
+ invoiceNumber: event.payload.invoiceNumber,
758
779
  netTotal: event.payload.netTotal,
759
780
  vatTotal: event.payload.vatTotal,
760
781
  grossTotal: event.payload.grossTotal,
@@ -798,6 +819,8 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
798
819
  id: "invoice-receive",
799
820
  type: "actionForm",
800
821
  handler: "contacts:write:invoice:receive",
822
+ // Lands on the invoice list with its search box filled from the result.
823
+ redirect: { screen: "invoice-list", searchParams: { "invoice-list.q": "invoiceNumber" } },
801
824
  fields: {
802
825
  supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
803
826
  invoiceNumber: createTextField({
@@ -0,0 +1,129 @@
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/handbook-knowledge. Do not edit. -->
2
+
3
+ # handbook-knowledge
4
+
5
+ The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools.
6
+
7
+ ## README
8
+
9
+ # Handbook knowledge
10
+
11
+ Serves the app's handbook to the AI assistant. `kumiko handbuch knowledge` exports
12
+ the pages per locale as JSON; the `handbook-knowledge` bundled feature mounts them
13
+ as two query tools, so the assistant can answer how-do-I questions from the real
14
+ handbook text.
15
+
16
+ ## What it shows
17
+
18
+ - **Feature** — `createHandbookKnowledgeFeature({ pages, access, publicPath })`.
19
+ No entity, no migration; `access` decides which roles see the tools.
20
+ - **list-pages** — catalog of id, kind, title and questions in the caller's language.
21
+ - **read-page** — one page body; the language falls back to the handbook's default
22
+ language, long pages are cut with a visible notice, unknown ids are `not_found`.
23
+ - **Test** — `setupTestStack` and HTTP with an `X-Locale` header.
24
+
25
+ ## Files
26
+
27
+ ```
28
+ src/feature.ts fixed handbook JSON and the feature
29
+ src/__tests__/feature.integration.test.ts list-pages, read-page, fallback, not found
30
+ ```
31
+
32
+ ## Source files
33
+
34
+ ### src/__tests__/feature.integration.test.ts
35
+
36
+ ```ts
37
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
38
+ import { createTestUser } from "@cosmicdrift/kumiko-framework/seeding";
39
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
40
+ import { handbookKnowledgeFeature } from "../feature";
41
+
42
+ const LIST_PAGES = "handbook-knowledge:query:list-pages";
43
+ const READ_PAGE = "handbook-knowledge:query:read-page";
44
+
45
+ type ListResult = { locale: string; pages: { id: string; title: string }[] };
46
+ type ReadResult = { id: string; locale: string; bodyMd: string; publicPath?: string };
47
+
48
+ const user = createTestUser({ roles: ["User"] });
49
+ let stack: TestStack;
50
+
51
+ beforeAll(async () => {
52
+ stack = await setupTestStack({ features: [handbookKnowledgeFeature] });
53
+ });
54
+
55
+ afterAll(async () => {
56
+ await stack.cleanup();
57
+ });
58
+
59
+ async function queryIn<T>(type: string, payload: unknown, locale: string): Promise<T> {
60
+ const res = await stack.http.queryWithHeaders(type, payload, user, { "X-Locale": locale });
61
+ expect(res.status).toBe(200);
62
+ return ((await res.json()) as { data: T }).data;
63
+ }
64
+
65
+ describe("handbook-knowledge recipe", () => {
66
+ test("list-pages returns the catalog in the caller's language", async () => {
67
+ const de = await queryIn<ListResult>(LIST_PAGES, {}, "de");
68
+ expect(de.pages[0]).toMatchObject({ id: "prozess-add-tenant", title: "Mieter hinzufügen" });
69
+ });
70
+
71
+ test("read-page falls back to the default language and links the public handbook", async () => {
72
+ const page = await queryIn<ReadResult>(READ_PAGE, { id: "lease-detail" }, "de");
73
+ expect(page).toMatchObject({ locale: "en", publicPath: "/handbuch/lease-detail" });
74
+ expect(page.bodyMd).toContain("tenants, rent and documents");
75
+ });
76
+
77
+ test("read-page rejects an unknown id", async () => {
78
+ const error = await stack.http.queryErr(READ_PAGE, { id: "missing" }, user);
79
+ expect(error.code).toBe("not_found");
80
+ });
81
+ });
82
+ ```
83
+
84
+ ### src/feature.ts
85
+
86
+ ```ts
87
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
88
+
89
+ // In an app this object is the output of `kumiko handbuch knowledge <config> --out <file>`.
90
+ const handbook = {
91
+ defaultLocale: "en",
92
+ locales: {
93
+ en: [
94
+ {
95
+ id: "prozess-add-tenant",
96
+ kind: "process" as const,
97
+ title: "Add a tenant",
98
+ questions: ["How do I add a tenant?"],
99
+ screens: [],
100
+ bodyMd: "Open the lease, choose Add tenant and confirm the change.",
101
+ },
102
+ {
103
+ id: "lease-detail",
104
+ kind: "screen" as const,
105
+ title: "Lease",
106
+ questions: [],
107
+ screens: [],
108
+ bodyMd: "The lease screen shows tenants, rent and documents.",
109
+ },
110
+ ],
111
+ de: [
112
+ {
113
+ id: "prozess-add-tenant",
114
+ kind: "process" as const,
115
+ title: "Mieter hinzufügen",
116
+ questions: ["Wie füge ich einen Mieter hinzu?"],
117
+ screens: [],
118
+ bodyMd: "Vertrag öffnen, Mieter hinzufügen wählen und die Änderung bestätigen.",
119
+ },
120
+ ],
121
+ },
122
+ };
123
+
124
+ export const handbookKnowledgeFeature = createHandbookKnowledgeFeature({
125
+ pages: handbook,
126
+ access: { roles: ["User"] },
127
+ publicPath: "/handbuch",
128
+ });
129
+ ```
@@ -1018,6 +1018,7 @@ import { z } from "zod";
1018
1018
  import { createOrderDeskFeature } from "../feature";
1019
1019
  import {
1020
1020
  answerBriefing,
1021
+ answerNextReminder,
1021
1022
  answerOrderDetail,
1022
1023
  answerOrderList,
1023
1024
  answerOrderSummary,
@@ -1135,6 +1136,7 @@ describe("record-detail-layout showcase — work queue", () => {
1135
1136
  display: "select",
1136
1137
  showCounts: true,
1137
1138
  label: "order-desk.orders.todo",
1139
+ narrowPlacement: "behind-filter",
1138
1140
  });
1139
1141
  const buttons = (screen.rowActions ?? []).filter((action) => action.display === "button");
1140
1142
  expect(buttons.map((action) => [action.id, action.visible])).toEqual([
@@ -1279,6 +1281,34 @@ describe("record-detail-layout showcase — phone variants", () => {
1279
1281
  });
1280
1282
  });
1281
1283
 
1284
+ describe("record-detail-layout showcase — board gaps round 8", () => {
1285
+ test("two narrow-only value columns stand side by side on the phone card", () => {
1286
+ const screen = registry.getScreen("order-desk:screen:orders");
1287
+ if (screen?.type !== "projectionList") throw new Error("expected projectionList");
1288
+ const inline = screen.columns
1289
+ .map((column) => normalizeListColumn(column))
1290
+ .filter((column) => column.narrowInline === true);
1291
+ expect(inline.map((column) => [column.field, column.showOnNarrowOnly])).toEqual([
1292
+ ["narrowOpen", true],
1293
+ ["narrowStatus", true],
1294
+ ]);
1295
+ const first = answerOrderList(orderListSchema.parse({}));
1296
+ expect("rows" in first && first.rows[0]?.narrowOpen).toBe("€ 312.00 open");
1297
+ });
1298
+
1299
+ test("the reminder-due empty state takes its description params from a registered query", () => {
1300
+ const screen = registry.getScreen("order-desk:screen:orders");
1301
+ if (screen?.type !== "projectionList") throw new Error("expected projectionList");
1302
+ const reminder = screen.namedFilters?.find((filter) => filter.id === "reminder-due");
1303
+ expect(reminder?.emptyState).toEqual({
1304
+ title: "order-desk.orders.all-done",
1305
+ description: "order-desk.orders.next-reminder",
1306
+ paramsQuery: "order-desk:query:order:next-reminder",
1307
+ });
1308
+ expect(answerNextReminder()).toEqual({ customer: "Aiko Tanaka", due: "by Friday" });
1309
+ });
1310
+ });
1311
+
1282
1312
  describe("record-detail-layout showcase — empty states", () => {
1283
1313
  test("the payments tab declares a record-dependent empty text ahead of its default", () => {
1284
1314
  const screen = registry.getScreen("order-desk:screen:order-detail");
@@ -1355,6 +1385,43 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
1355
1385
  });
1356
1386
  ```
1357
1387
 
1388
+ ### src/__tests__/next-reminder.integration.test.ts
1389
+
1390
+ ```ts
1391
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
1392
+ import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
1393
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
1394
+ import { createOrderDeskFeature } from "../feature";
1395
+
1396
+ let stack: TestStack;
1397
+ const support = createTestUser({ roles: ["Support"], tenantId: testTenantId(1) });
1398
+
1399
+ beforeAll(async () => {
1400
+ stack = await setupTestStack({ features: [createOrderDeskFeature()], systemHooks: [] });
1401
+ });
1402
+
1403
+ afterAll(async () => {
1404
+ await stack.cleanup();
1405
+ });
1406
+
1407
+ describe("emptyState.paramsQuery over HTTP", () => {
1408
+ test("the query the reminder-due empty state names answers the params of its description", async () => {
1409
+ const params = await stack.http.queryOk<{ customer: string; due: string }>(
1410
+ "order-desk:query:order:next-reminder",
1411
+ {},
1412
+ support,
1413
+ );
1414
+ expect(params).toEqual({ customer: "Aiko Tanaka", due: "by Friday" });
1415
+ });
1416
+
1417
+ test("a caller without the list's roles cannot read the params", async () => {
1418
+ const outsider = createTestUser({ roles: ["User"], tenantId: testTenantId(1) });
1419
+ const denied = await stack.http.queryErr("order-desk:query:order:next-reminder", {}, outsider);
1420
+ expect(denied.code).toBe("access_denied");
1421
+ });
1422
+ });
1423
+ ```
1424
+
1358
1425
  ### src/feature.ts
1359
1426
 
1360
1427
  ```ts
@@ -1387,6 +1454,10 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
1387
1454
  // 10. `focus: true` gives the detail a focused shell; phones get a top bar with the
1388
1455
  // record title, a back arrow to the list and the page-header overflow menu.
1389
1456
  //
1457
+ // 11. Phone card values: two `showOnNarrowOnly` columns with `narrowInline` stand side by side on one line.
1458
+ // The named-filter select sits behind the filter icon on phones (`narrowPlacement: "behind-filter"`),
1459
+ // and the "reminder due" empty state fills its description from a query (`emptyState.paramsQuery`).
1460
+ //
1390
1461
  // projectionDetail binds to an explicit query, not an entity: every field name below
1391
1462
  // (header, metrics, fields) is a column of that query's row.
1392
1463
 
@@ -1397,6 +1468,7 @@ import {
1397
1468
  answerCustomers,
1398
1469
  answerDeadlines,
1399
1470
  answerMoney,
1471
+ answerNextReminder,
1400
1472
  answerNowList,
1401
1473
  answerOrderDetail,
1402
1474
  answerOrderList,
@@ -1436,6 +1508,13 @@ export function createOrderDeskFeature(): FeatureDefinition {
1436
1508
  access: accessRoles,
1437
1509
  });
1438
1510
 
1511
+ r.queryHandler({
1512
+ name: "order:next-reminder",
1513
+ schema: noPayloadSchema,
1514
+ handler: async () => answerNextReminder(),
1515
+ access: accessRoles,
1516
+ });
1517
+
1439
1518
  r.queryHandler({
1440
1519
  name: "order:briefing",
1441
1520
  schema: noPayloadSchema,
@@ -1523,6 +1602,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1523
1602
  "order-desk.orders.nothing-open": { en: "Nothing to do" },
1524
1603
  "order-desk.orders.all-done": { en: "All done" },
1525
1604
  "order-desk.orders.all-done-hint": { en: "No order needs you right now." },
1605
+ "order-desk.orders.next-reminder": { en: "Next reminder: {customer}, due {due}." },
1526
1606
  "order-desk.filter.action-needed": { en: "Needs action" },
1527
1607
  "order-desk.filter.reminder-due": { en: "Reminder due" },
1528
1608
  "order-desk.filter.ending-soon": { en: "Ending soon" },
@@ -1548,7 +1628,8 @@ export function createOrderDeskFeature(): FeatureDefinition {
1548
1628
  "order-desk.today.inbox-link": { en: "All orders" },
1549
1629
  "order-desk.today.deadlines": { en: "Deadlines" },
1550
1630
  "order-desk.today.deadlines-all": { en: "All deadlines" },
1551
- "order-desk.col.narrow-meta": { en: "Details" },
1631
+ "order-desk.col.narrow-open": { en: "Open amount" },
1632
+ "order-desk.col.narrow-status": { en: "Status" },
1552
1633
  "order-desk.today.customers": { en: "Customers" },
1553
1634
  "order-desk.today.money": { en: "Money" },
1554
1635
  "order-desk.today.money-sub": { en: "Across all open orders" },
@@ -1592,7 +1673,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1592
1673
  rowToneField: "tone",
1593
1674
  columns: [
1594
1675
  { field: "orderNumber", label: "order-desk.col.order" },
1595
- { field: "customerName", label: "order-desk.col.customer" },
1676
+ { field: "customerName", label: "order-desk.col.customer", hideOnNarrow: true },
1596
1677
  {
1597
1678
  field: "urgencyLabel",
1598
1679
  label: "order-desk.col.urgency",
@@ -1614,7 +1695,18 @@ export function createOrderDeskFeature(): FeatureDefinition {
1614
1695
  minWidth: 240,
1615
1696
  },
1616
1697
  { field: "openAmount", label: "order-desk.col.open-amount", hideOnNarrow: true },
1617
- { field: "narrowMeta", label: "order-desk.col.narrow-meta", showOnNarrowOnly: true },
1698
+ {
1699
+ field: "narrowOpen",
1700
+ label: "order-desk.col.narrow-open",
1701
+ showOnNarrowOnly: true,
1702
+ narrowInline: true,
1703
+ },
1704
+ {
1705
+ field: "narrowStatus",
1706
+ label: "order-desk.col.narrow-status",
1707
+ showOnNarrowOnly: true,
1708
+ narrowInline: true,
1709
+ },
1618
1710
  ],
1619
1711
  defaultSort: { field: "urgency", dir: "desc" },
1620
1712
  sortOptions: [
@@ -1636,12 +1728,18 @@ export function createOrderDeskFeature(): FeatureDefinition {
1636
1728
  label: "order-desk.filter.reminder-due",
1637
1729
  emptyState: {
1638
1730
  title: "order-desk.orders.all-done",
1639
- description: "order-desk.orders.all-done-hint",
1731
+ description: "order-desk.orders.next-reminder",
1732
+ paramsQuery: "order-desk:query:order:next-reminder",
1640
1733
  },
1641
1734
  },
1642
1735
  { id: "ending-soon", label: "order-desk.filter.ending-soon" },
1643
1736
  ],
1644
- namedFilterFacet: { display: "select", showCounts: true, label: "order-desk.orders.todo" },
1737
+ namedFilterFacet: {
1738
+ display: "select",
1739
+ showCounts: true,
1740
+ label: "order-desk.orders.todo",
1741
+ narrowPlacement: "behind-filter",
1742
+ },
1645
1743
  narrowFacets: "pills",
1646
1744
  table: {
1647
1745
  frame: "card",
@@ -2288,7 +2386,8 @@ export type OrderListAnswer =
2288
2386
  }
2289
2387
  | {
2290
2388
  readonly rows: readonly (OrderRow & {
2291
- readonly narrowMeta: string;
2389
+ readonly narrowOpen: string;
2390
+ readonly narrowStatus: string;
2292
2391
  readonly actionScreen?: string;
2293
2392
  readonly actionParams?: { readonly entityId: string };
2294
2393
  })[];
@@ -2316,7 +2415,8 @@ export function answerOrderList(payload: OrderListPayload): OrderListAnswer {
2316
2415
  const offset = payload.offset ?? 0;
2317
2416
  const rows = ordered.slice(offset, offset + (payload.limit ?? DEFAULT_PAGE_SIZE)).map((row) => ({
2318
2417
  ...row,
2319
- narrowMeta: `${euro(row.openAmount)} open · ${row.status}`,
2418
+ narrowOpen: `${euro(row.openAmount)} open`,
2419
+ narrowStatus: row.status,
2320
2420
  nextStepShort: row.nextStepDue === "" ? "" : `${row.nextStepDue} · ${euro(row.openAmount)}`,
2321
2421
  ...(row.nextStep !== "" && {
2322
2422
  actionScreen: ORDER_DETAIL_SCREEN_QN,
@@ -2371,6 +2471,12 @@ export function answerNowList() {
2371
2471
  };
2372
2472
  }
2373
2473
 
2474
+ // The params of the "reminder due" empty state; null while no order is waiting for a reminder.
2475
+ export function answerNextReminder(): { readonly customer: string; readonly due: string } | null {
2476
+ const next = ORDER_ROWS.find((row) => row.canRemind);
2477
+ return next === undefined ? null : { customer: next.customerName, due: next.nextStepDue };
2478
+ }
2479
+
2374
2480
  export function answerBriefing() {
2375
2481
  const open = actionNeededRows(ORDER_ROWS.length);
2376
2482
  const [first] = open;