@cosmicdrift/kumiko-framework 0.415.0 → 0.417.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -28,6 +28,10 @@ query and the fields to read, the query does the counting.
28
28
  `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
29
29
  over the whole WHERE clause, so no rows are loaded just to be counted.
30
30
  - **Labels are translation keys**: declared with `r.translations`.
31
+ - **`progress-list` head from the answer**: `labelParams` fills the `{month}` of the
32
+ label from the query answer and `subtitleField` shows the period muted at the head's right.
33
+ - **List footer without a link**: `footerLink` with only `moreText` (no `label`)
34
+ shows the muted "k more" count under the list.
31
35
  - **Record-bound dashboard**: `ticket-record-dashboard` binds to a record with `record`
32
36
  and embeds the `ticket-card` projectionDetail as a screen panel; the record id
33
37
  becomes its entityId.
@@ -299,8 +303,33 @@ export const ticketFeature = defineFeature("tickets", (r) => {
299
303
  access: readerRoles,
300
304
  });
301
305
 
306
+ // Three newest rows plus the total, so the panel can say how many more exist.
307
+ r.queryHandler({
308
+ name: "ticket:recent",
309
+ schema: z.object({}),
310
+ handler: async (query, ctx) => {
311
+ const page = await ticketExecutor.list({ limit: 3, totalCount: true }, query.user, ctx.db);
312
+ return { rows: page.rows, nextCursor: null, total: page.total ?? page.rows.length };
313
+ },
314
+ access: readerRoles,
315
+ });
316
+
317
+ r.queryHandler({
318
+ name: "ticket:quota",
319
+ schema: z.object({}),
320
+ handler: async () => ({
321
+ month: "November",
322
+ period: "01.11. - 30.11.",
323
+ rows: [{ label: "Tickets handled", used: 18, limit: 25, sub: "7 left" }],
324
+ }),
325
+ access: readerRoles,
326
+ });
327
+
302
328
  r.translations({
303
329
  keys: {
330
+ "tickets.dashboard.recent": { en: "Recent tickets" },
331
+ "tickets.dashboard.recent-more": { en: "{count} more tickets" },
332
+ "tickets.dashboard.quota": { en: "Quota {month}" },
304
333
  "screen:ticket-list.title": { en: "Tickets" },
305
334
  "screen:ticket-card.title": { en: "Ticket" },
306
335
  "screen:ticket-record-dashboard.title": { en: "Ticket overview" },
@@ -314,6 +343,7 @@ export const ticketFeature = defineFeature("tickets", (r) => {
314
343
  "tickets.dashboard.open": { en: "Open" },
315
344
  "tickets.dashboard.closed": { en: "Closed" },
316
345
  "tickets.dashboard.total": { en: "All tickets" },
346
+ "tickets.dashboard.total-narrow": { en: { one: "{count} ticket", other: "{count} tickets" } },
317
347
  "tickets.dashboard.open-work": { en: "Open work" },
318
348
  "tickets.filter.open-work": { en: "Open work" },
319
349
  "screen:ticket-queue.title": { en: "Ticket queue" },
@@ -349,6 +379,8 @@ export const ticketFeature = defineFeature("tickets", (r) => {
349
379
  kind: "stat",
350
380
  id: "total",
351
381
  label: "tickets.dashboard.total",
382
+ // Below sm the label is replaced by this plural key, resolved with { count: <value> }.
383
+ labelNarrow: "tickets.dashboard.total-narrow",
352
384
  query: TICKET_STATS_QUERY,
353
385
  valueField: "total",
354
386
  },
@@ -362,6 +394,25 @@ export const ticketFeature = defineFeature("tickets", (r) => {
362
394
  params: { namedFilter: "open-work", limit: 1, totalCount: true },
363
395
  navigate: { screen: "ticket-queue", namedFilter: "open-work" },
364
396
  },
397
+ // Without `label` the footer is only the muted "k more" count, no link.
398
+ {
399
+ kind: "list",
400
+ id: "recent",
401
+ label: "tickets.dashboard.recent",
402
+ query: "tickets:query:ticket:recent",
403
+ // `badgeIcon: "sparkles"` draws an AI-prepared value as the soft blue AI pill with an icon.
404
+ columns: ["title", { field: "status", display: "badge", badgeIcon: "sparkles" }],
405
+ footerLink: { moreText: "tickets.dashboard.recent-more", screen: "ticket-queue" },
406
+ },
407
+ // The title takes its month from the answer and the period shows muted at the head's right.
408
+ {
409
+ kind: "progress-list",
410
+ id: "quota",
411
+ label: "tickets.dashboard.quota",
412
+ labelParams: { month: "month" },
413
+ subtitleField: "period",
414
+ query: "tickets:query:ticket:quota",
415
+ },
365
416
  ],
366
417
  access: readerRoles,
367
418
  });
@@ -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({
@@ -229,6 +229,59 @@ describe("Event Sourcing Showcase", () => {
229
229
  expect(byCustomer.get("Globex")).toMatchObject({ paidInvoices: 1, totalCents: 300 });
230
230
  });
231
231
 
232
+ test("loadByTypes: statuses of the requested invoices from approved/paid events only", async () => {
233
+ const requestedPaid = await stack.http.writeOk<{ id: string }>(
234
+ "showcase:write:invoice:create",
235
+ { customer: "Acme" },
236
+ admin,
237
+ );
238
+ const requestedApproved = await stack.http.writeOk<{ id: string }>(
239
+ "showcase:write:invoice:create",
240
+ { customer: "Acme" },
241
+ admin,
242
+ );
243
+ const notRequested = await stack.http.writeOk<{ id: string }>(
244
+ "showcase:write:invoice:create",
245
+ { customer: "Globex" },
246
+ admin,
247
+ );
248
+ for (const invoice of [requestedPaid, requestedApproved, notRequested]) {
249
+ await stack.http.writeOk(
250
+ "showcase:write:invoice:approve",
251
+ { id: invoice.id, amountCents: 100, approvedBy: "cfo" },
252
+ admin,
253
+ );
254
+ }
255
+ await stack.http.writeOk(
256
+ "showcase:write:invoice:pay",
257
+ { id: requestedPaid.id, amountCents: 100 },
258
+ admin,
259
+ );
260
+ await stack.http.writeOk(
261
+ "showcase:write:invoice:pay",
262
+ { id: notRequested.id, amountCents: 100 },
263
+ admin,
264
+ );
265
+ await stack.http.writeOk(
266
+ "showcase:write:invoice:acknowledge",
267
+ { id: requestedApproved.id, approverId: "cfo" },
268
+ admin,
269
+ );
270
+
271
+ const { statuses } = await stack.http.queryOk<{
272
+ statuses: Array<{ id: string; status: string }>;
273
+ }>(
274
+ "showcase:query:invoice:payment-statuses",
275
+ { ids: [requestedPaid.id, requestedApproved.id] },
276
+ admin,
277
+ );
278
+
279
+ expect(statuses).toEqual([
280
+ { id: requestedPaid.id, status: "paid" },
281
+ { id: requestedApproved.id, status: "approved" },
282
+ ]);
283
+ });
284
+
232
285
  test("asOf point-in-time read: invoice state before the pay event", async () => {
233
286
  const { id } = await stack.http.writeOk<{ id: string }>(
234
287
  "showcase:write:invoice:create",
@@ -837,6 +890,7 @@ describe("role-restricted write handlers", () => {
837
890
  // - r.projection — single-stream read model (inline in the write TX)
838
891
  // - r.multiStreamProjection — cross-aggregate async read model
839
892
  // - ctx.events.load with { asOf } — point-in-time aggregate state
893
+ // - ctx.events.loadByTypes — events of many aggregates, filtered by type, in one query
840
894
  // - ctx.events.archive / ctx.events.restore — Marten ArchiveStream
841
895
  // - ctx.dispatch.queryProjection — tenant-scoped read of a projection table
842
896
  // - ctx.events.snapshot + ctx.events.loadWithSnapshot — perf path
@@ -1225,6 +1279,36 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
1225
1279
  },
1226
1280
  });
1227
1281
 
1282
+ // List page over many invoices: ONE query for just the approved/paid events of the
1283
+ // requested aggregates instead of ctx.events.load per invoice.
1284
+ r.queryHandler({
1285
+ name: "invoice:payment-statuses",
1286
+ schema: z.object({ ids: z.array(z.uuid()).max(200) }),
1287
+ handler: async (query, ctx) => {
1288
+ const events = await ctx.events.loadByTypes({
1289
+ aggregateIds: query.payload.ids,
1290
+ eventTypes: [approved.name, paid.name],
1291
+ });
1292
+ const lastEventByInvoice = new Map<string, string>();
1293
+ for (const evt of events) {
1294
+ lastEventByInvoice.set(evt.aggregateId, evt.type);
1295
+ }
1296
+ return {
1297
+ statuses: [...lastEventByInvoice].map(([id, lastEventType]) => ({
1298
+ id,
1299
+ status: lastEventType === paid.name ? "paid" : "approved",
1300
+ })),
1301
+ };
1302
+ },
1303
+ access: {
1304
+ openToAll: {
1305
+ reason:
1306
+ "demo recipe: any signed-in user may read invoice payment statuses; " +
1307
+ "there is no per-user invoice ownership in this sample",
1308
+ },
1309
+ },
1310
+ });
1311
+
1228
1312
  // Snapshot-aware fast path. Uses the latest snapshot if available and
1229
1313
  // only replays delta events past it. Identical state shape to
1230
1314
  // invoice:state — the two are interchangeable modulo the perf profile.
@@ -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
+ ```
@@ -35,6 +35,15 @@ the `table` block renders and behaves as before.
35
35
  offers grouping by priority or none.
36
36
  - `table.totals`: a footer row with the estimate sum over the filtered list.
37
37
  - `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
38
+ - `mutedRowField: "parked"`: a parked task is drawn entirely in the muted colour.
39
+ - `toolbarSort: true`: the desktop "Sorted by" select in the filter row (opt-in).
40
+ - Column options: `ellipsis` (one truncated line), `multiline` (line breaks stay),
41
+ `tone: "muted"`, `cardAbove` (phone card line above the title), `hideWhenDocked`,
42
+ `emptyPlaceholder` (`false` keeps the cell blank, a string shows muted text),
43
+ `cardBadge` (phone-card pill), `dateOnlyAfterDays` on a timestamp column,
44
+ `pillField` / `pillToneField` (a second pill beside the cell value).
45
+ - Row action `display: "text"`: muted text without a button, shown for done tasks.
46
+ - `hideCountFooter` is not set here: no screen declaration reaches it (relatedList sets it itself).
38
47
  - The same block on a `projectionList`, and `task:workload`, a hand-written list
39
48
  query that keeps grouping and totals by accepting `aggregate`
40
49
  (`entityListSchema`) and answering it with `answerListAggregate`.
@@ -145,9 +154,21 @@ describe("list-table-options recipe", () => {
145
154
  );
146
155
  });
147
156
 
148
- test("a hidden column needs the column picker", () => {
149
- expect(() => validateBoot([featureWithBlock({ rememberState: true, resetAll: true })])).toThrow(
150
- /column "estimateHours" is hidden but table\.columnPicker is not enabled/,
157
+ // A hidden column that backs a facet needs no picker (the facet is its UI), so the recipe's
158
+ // own hidden estimateHours column does not trip the rule; a plain hidden column does.
159
+ test("a hidden column without a facet needs the column picker", () => {
160
+ const feature = defineFeature("task-board", (r) => {
161
+ r.crud("task", taskEntity, { write: openAccess, read: openAccess });
162
+ r.screen({
163
+ id: "task-list",
164
+ type: "entityList",
165
+ entity: "task",
166
+ columns: ["title", { field: "assignee", hidden: true }],
167
+ table: { rememberState: true },
168
+ });
169
+ });
170
+ expect(() => validateBoot([feature])).toThrow(
171
+ /column "assignee" is hidden but table\.columnPicker is not enabled/,
151
172
  );
152
173
  });
153
174
 
@@ -248,11 +269,13 @@ import {
248
269
  createEventStoreExecutor,
249
270
  } from "@cosmicdrift/kumiko-framework/db";
250
271
  import {
272
+ createBooleanField,
251
273
  createDateField,
252
274
  createEntity,
253
275
  createNumberField,
254
276
  createSelectField,
255
277
  createTextField,
278
+ createTimestampField,
256
279
  defineFeature,
257
280
  entityListSchema,
258
281
  type FeatureDefinition,
@@ -285,6 +308,14 @@ export const taskEntity = createEntity({
285
308
  dueDate: createDateField({ sortable: true }),
286
309
  assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
287
310
  estimateHours: createNumberField({ sortable: true, filterable: true }),
311
+ parked: createBooleanField({ default: false }),
312
+ note: createTextField({ personal: false, reason: "is_business_data" }),
313
+ team: createTextField({ personal: false, reason: "is_business_data" }),
314
+ teamTone: createSelectField({
315
+ options: ["positive", "warn", "negative", "neutral"] as const,
316
+ default: "neutral",
317
+ }),
318
+ lastUpdate: createTimestampField({ sortable: true }),
288
319
  },
289
320
  });
290
321
 
@@ -320,9 +351,29 @@ export function createTaskBoardFeature(
320
351
  // Starts pinned left; width and minWidth are start values for resizing.
321
352
  { field: "title", pinned: "left", width: 280, minWidth: 160 },
322
353
  "status",
323
- "priority",
354
+ // The phone card shows the priority as its outlined pill instead of the first select column.
355
+ { field: "priority", cardBadge: true },
324
356
  { field: "dueDate", hideOnNarrow: true },
325
- { field: "assignee", hideOnNarrow: true },
357
+ // The team pill sits beside the assignee name; its tone comes from the row.
358
+ {
359
+ field: "assignee",
360
+ hideOnNarrow: true,
361
+ pillField: "team",
362
+ pillToneField: "teamTone",
363
+ emptyPlaceholder: "Unassigned",
364
+ },
365
+ // One truncated line in the table; a line break starts a new line on the phone card.
366
+ {
367
+ field: "note",
368
+ ellipsis: true,
369
+ multiline: true,
370
+ tone: "muted",
371
+ cardAbove: true,
372
+ hideWhenDocked: true,
373
+ emptyPlaceholder: false,
374
+ },
375
+ // Recent edits show date and time, older ones the date only.
376
+ { field: "lastUpdate", dateOnlyAfterDays: 7, hideOnNarrow: true },
326
377
  // Starts hidden; the user can add it back in the view menu.
327
378
  { field: "estimateHours", hidden: true, hideOnNarrow: true },
328
379
  ],
@@ -330,7 +381,22 @@ export function createTaskBoardFeature(
330
381
  defaultSort: { field: "dueDate", dir: "asc" },
331
382
  searchable: true,
332
383
  table: taskTable,
384
+ mutedRowField: "parked",
385
+ toolbarSort: true,
386
+ sortOptions: [
387
+ { field: "dueDate", dir: "asc", label: "Due date" },
388
+ { field: "priority", dir: "desc", label: "Priority" },
389
+ ],
333
390
  rowActions: [
391
+ // A closed state as muted text instead of a button.
392
+ {
393
+ kind: "navigate",
394
+ id: "closed",
395
+ label: "Closed",
396
+ screen: "task-edit",
397
+ display: "text",
398
+ visible: { field: "status", eq: "done" },
399
+ },
334
400
  { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
335
401
  {
336
402
  kind: "writeHandler",
@@ -404,7 +404,14 @@ export const integrationsFeature = defineFeature(FEATURE, (r) => {
404
404
  default: "smtp.platform.example",
405
405
  write: access.roles("SystemAdmin", "Admin"),
406
406
  read: access.admin,
407
- mask: { title: "integrations.smtp-host", icon: "mail", order: 2 },
407
+ // compact: the generated screen drops origin icons and accent bars; section: groups the key under its own titled section.
408
+ mask: {
409
+ title: "integrations.smtp-host",
410
+ icon: "mail",
411
+ order: 2,
412
+ compact: true,
413
+ section: "integrations.mail",
414
+ },
408
415
  }),
409
416
  },
410
417
  });
@@ -426,6 +433,7 @@ export const integrationsFeature = defineFeature(FEATURE, (r) => {
426
433
  "integrations.settings": { de: "Integrationen", en: "Integrations" },
427
434
  "integrations.payment-api-key": { de: "Zahlungs-API-Schlüssel", en: "Payment API Key" },
428
435
  "integrations.smtp-host": { de: "SMTP-Server", en: "SMTP Host" },
436
+ "integrations.mail": { de: "E-Mail-Versand", en: "Mail delivery" },
429
437
  },
430
438
  });
431
439
  });