@cosmicdrift/kumiko-framework 0.416.0 → 0.418.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 (80) hide show
  1. package/agents/api/framework-engine.md +32 -9
  2. package/agents/api/framework-ui-types.md +37 -10
  3. package/agents/api/renderer-web.md +25 -2
  4. package/agents/api/types.md +121 -64
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +23 -1
  7. package/agents/examples/crypto-shredding-hr.md +2 -2
  8. package/agents/examples/dashboard-stats.md +51 -0
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/list-table-options.md +346 -12
  11. package/agents/examples/managed-config.md +9 -1
  12. package/agents/examples/record-detail-layout.md +71 -6
  13. package/agents/examples/secrets-demo.md +3 -1
  14. package/agents/examples/signature.md +3 -2
  15. package/agents/examples/writeform-section.md +329 -0
  16. package/agents/features.md +1 -1
  17. package/dist/api/server-boot-checks.d.ts +1 -0
  18. package/dist/api/server-boot-checks.js +25 -0
  19. package/dist/api/server-rate-limit-wiring.js +2 -1
  20. package/dist/db/queries/event-store.d.ts +3 -0
  21. package/dist/db/queries/event-store.js +12 -0
  22. package/dist/engine/boot-validator/action-form-preview-rules.d.ts +22 -0
  23. package/dist/engine/boot-validator/action-form-preview-rules.js +22 -0
  24. package/dist/engine/boot-validator/action-form-preview.d.ts +2 -0
  25. package/dist/engine/boot-validator/action-form-preview.js +54 -0
  26. package/dist/engine/boot-validator/boot-rules.d.ts +87 -1
  27. package/dist/engine/boot-validator/boot-rules.js +2 -0
  28. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  29. package/dist/engine/boot-validator/config-key-rules.d.ts +5 -0
  30. package/dist/engine/boot-validator/config-key-rules.js +5 -0
  31. package/dist/engine/boot-validator/date-only-after-days.d.ts +4 -0
  32. package/dist/engine/boot-validator/date-only-after-days.js +32 -0
  33. package/dist/engine/boot-validator/entity-handler.d.ts +1 -0
  34. package/dist/engine/boot-validator/entity-handler.js +1 -1
  35. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +40 -0
  36. package/dist/engine/boot-validator/list-bulk-actions-rules.js +40 -0
  37. package/dist/engine/boot-validator/list-bulk-actions.d.ts +2 -1
  38. package/dist/engine/boot-validator/list-bulk-actions.js +79 -9
  39. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  40. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  41. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  42. package/dist/engine/boot-validator/list-table-options.js +8 -6
  43. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  44. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  45. package/dist/engine/boot-validator/query-output-columns.js +29 -2
  46. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  47. package/dist/engine/boot-validator/query-refs.js +3 -0
  48. package/dist/engine/boot-validator/screens-actions.d.ts +7 -2
  49. package/dist/engine/boot-validator/screens-actions.js +4 -2
  50. package/dist/engine/boot-validator/screens-forms.js +2 -0
  51. package/dist/engine/boot-validator/screens-kind-entity-list.js +5 -3
  52. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  53. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  54. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  55. package/dist/engine/boot-validator/screens-kind-projection-list.js +2 -2
  56. package/dist/engine/boot-validator/screens-kind-shared.d.ts +1 -1
  57. package/dist/engine/boot-validator/screens-kind-shared.js +3 -1
  58. package/dist/engine/boot-validator/screens-lists-rules.d.ts +10 -0
  59. package/dist/engine/boot-validator/screens-lists-rules.js +10 -0
  60. package/dist/engine/boot-validator/screens-lists.js +13 -1
  61. package/dist/engine/boot-validator/screens.js +1 -2
  62. package/dist/engine/boot-validator/url-prefill-fields.js +8 -1
  63. package/dist/engine/boot-validator/zod-shape.d.ts +1 -0
  64. package/dist/engine/boot-validator/zod-shape.js +7 -0
  65. package/dist/engine/bridge-stub.js +1 -0
  66. package/dist/engine/build-config-feature-schema.js +30 -3
  67. package/dist/engine/screen-helpers.js +7 -3
  68. package/dist/engine/types/screen.d.ts +1 -1
  69. package/dist/engine/types/screen.js +1 -1
  70. package/dist/event-store/archive.d.ts +1 -0
  71. package/dist/event-store/archive.js +5 -1
  72. package/dist/event-store/event-store.d.ts +5 -0
  73. package/dist/event-store/event-store.js +23 -3
  74. package/dist/i18n/required-surface-keys.js +53 -13
  75. package/dist/pipeline/handler-context-events.js +15 -1
  76. package/dist/ui-types/card-column-roles.d.ts +3 -0
  77. package/dist/ui-types/card-column-roles.js +9 -5
  78. package/dist/ui-types/index.d.ts +1 -1
  79. package/package.json +3 -3
  80. package/src/changes.json +36 -0
@@ -51,6 +51,13 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
51
51
  - round 6 (board gaps): `rowLink.screenField` / `paramsField` (target screen from a query field),
52
52
  list panel `icon`, `narrow.moreText`, `narrow.field` as any query output field,
53
53
  `footerLink.narrowOnly`, `narrow.titleField` on cards and `rowToneMarker: "dot"`
54
+ - round 7 (board look): `header.narrowTitle` (short phone top-bar title), banner `iconless`,
55
+ `metricsPlacement: { narrow: "before-steps" }`, `mobileSummary` (one line instead of the
56
+ metrics below `sm`), `MetricSpec.visibleWhen`, field option `concealed` (muted value with a lock),
57
+ section `hideOnNarrow` and `after` (a registered component under the items tab card), and a
58
+ second screen `order-facts` with a stacked layout and `pageNavigation: false`
59
+ - not shown: `photosBeside` (needs a stored image file for `photoGrid`) and `recordSections.omitFirstTitle`
60
+ (a renderer prop, not reachable from a screen declaration)
54
61
  - boot-validator catching two common author mistakes: a `metrics` entry
55
62
  with an empty `label`, and a `tabs` layout with fewer than two
56
63
  sections
@@ -334,6 +341,10 @@ function OrderInternalNote(): ReactNode {
334
341
  );
335
342
  }
336
343
 
344
+ function OrderItemsFooter(): ReactNode {
345
+ return <p data-testid="order-items-footer">Prices include VAT.</p>;
346
+ }
347
+
337
348
  function OrderInboxIcon(): ReactNode {
338
349
  return (
339
350
  <svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16" fill="none">
@@ -372,7 +383,9 @@ function Shell({
372
383
  schema={schema}
373
384
  user={{ id: "u1", roles: ["Admin"] }}
374
385
  >
375
- <ExtensionSectionsProvider value={{ OrderInboxIcon, DeadlinesIcon, OrderInternalNote }}>
386
+ <ExtensionSectionsProvider
387
+ value={{ OrderInboxIcon, DeadlinesIcon, OrderInternalNote, OrderItemsFooter }}
388
+ >
376
389
  {isPinnedRecord && feature !== undefined ? (
377
390
  <KumikoScreen schema={feature} qn={ORDER_DETAIL_SCREEN_QN} entityId="order-1" />
378
391
  ) : (
@@ -471,6 +484,7 @@ function orderDetailForUrl(id: string): Record<string, unknown> {
471
484
  summaryLine,
472
485
  summaryShort,
473
486
  summaryTone,
487
+ mobileLine,
474
488
  notice,
475
489
  steps,
476
490
  progress,
@@ -478,7 +492,17 @@ function orderDetailForUrl(id: string): Record<string, unknown> {
478
492
  } = answerOrderDetail(id);
479
493
  const withGuidance = new URLSearchParams(window.location.search).has("guidance");
480
494
  return withGuidance
481
- ? { ...withoutGuidance, path, summaryLine, summaryShort, summaryTone, notice, steps, progress }
495
+ ? {
496
+ ...withoutGuidance,
497
+ path,
498
+ summaryLine,
499
+ summaryShort,
500
+ summaryTone,
501
+ mobileLine,
502
+ notice,
503
+ steps,
504
+ progress,
505
+ }
482
506
  : withoutGuidance;
483
507
  }
484
508
 
@@ -632,7 +656,8 @@ test.describe("record-detail-layout — tab-panel height", () => {
632
656
  expect(region.y + region.height).toBeLessThanOrEqual(main.y + main.height + 4);
633
657
  expect(table.height).toBeLessThan(region.height);
634
658
  expect(table.height).toBeLessThan(main.height * 0.4);
635
- await expect(page.getByTestId("render-list-table-footer")).toBeVisible();
659
+ // A tab's table has no count footer: the tab label already says how many rows there are.
660
+ await expect(page.getByTestId("render-list-table-footer")).toHaveCount(0);
636
661
  });
637
662
 
638
663
  test("long list: the tab-panel card is capped at the panel's available height and the table scrolls internally", async ({
@@ -1049,6 +1074,7 @@ describe("record-detail-layout showcase — registration", () => {
1049
1074
  expect(screen.header).toEqual({
1050
1075
  title: "customerName",
1051
1076
  shortTitle: "shortTitle",
1077
+ narrowTitle: "order-desk.header.narrow-title",
1052
1078
  narrowSubtitle: "narrowSubtitle",
1053
1079
  subtitle: [
1054
1080
  "orderNumber",
@@ -1225,7 +1251,7 @@ describe("record-detail-layout showcase — board gaps", () => {
1225
1251
  const detail = registry.getScreen("order-desk:screen:order-detail");
1226
1252
  if (detail?.type !== "projectionDetail") throw new Error("expected projectionDetail");
1227
1253
  expect(detail.progress?.placement).toBe("beside-steps");
1228
- expect(detail.metricsPlacement).toEqual({ narrow: "after-guidance" });
1254
+ expect(detail.metricsPlacement).toEqual({ narrow: "before-steps" });
1229
1255
  expect(detail.metrics?.map((metric) => metric.subField)).toContain("totalNote");
1230
1256
  });
1231
1257
  });
@@ -1657,6 +1683,10 @@ export function createOrderDeskFeature(): FeatureDefinition {
1657
1683
  "order-desk.metric.outstandingAmount": { en: "Outstanding" },
1658
1684
  "order-desk.metric.itemCount": { en: "Items" },
1659
1685
  "order-desk.metric.placedAt": { en: "Placed" },
1686
+ "order-desk.header.narrow-title": { en: "Order" },
1687
+ "screen:order-facts.title": { en: "Order facts" },
1688
+ "order-desk.facts.contact": { en: "Contact" },
1689
+ "order-desk.facts.address": { en: "Address" },
1660
1690
  "order-desk.tab.items": { en: "Items" },
1661
1691
  "order-desk.tab.payments": { en: "Payments" },
1662
1692
  "order-desk.tab.details": { en: "Details" },
@@ -1709,6 +1739,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1709
1739
  },
1710
1740
  ],
1711
1741
  defaultSort: { field: "urgency", dir: "desc" },
1742
+ toolbarSort: true,
1712
1743
  sortOptions: [
1713
1744
  { field: "urgency", dir: "desc", label: "order-desk.sort.urgency" },
1714
1745
  { field: "customerName", dir: "asc", label: "order-desk.sort.customer" },
@@ -1950,6 +1981,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1950
1981
  header: {
1951
1982
  title: "customerName",
1952
1983
  shortTitle: "shortTitle",
1984
+ narrowTitle: "order-desk.header.narrow-title",
1953
1985
  // Parts are joined by a separator; `format` formats the raw field value.
1954
1986
  narrowSubtitle: "narrowSubtitle",
1955
1987
  subtitle: [
@@ -1962,6 +1994,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1962
1994
  summary: { field: "summaryLine", narrowField: "summaryShort", toneField: "summaryTone" },
1963
1995
  banner: {
1964
1996
  field: "notice",
1997
+ iconless: true,
1965
1998
  actions: [
1966
1999
  {
1967
2000
  kind: "navigate",
@@ -1999,8 +2032,9 @@ export function createOrderDeskFeature(): FeatureDefinition {
1999
2032
  },
2000
2033
  ],
2001
2034
  },
2035
+ mobileSummary: "mobileLine",
2002
2036
  metricsStyle: "tiles",
2003
- metricsPlacement: { narrow: "after-guidance" },
2037
+ metricsPlacement: { narrow: "before-steps" },
2004
2038
  metrics: [
2005
2039
  {
2006
2040
  field: "totalAmount",
@@ -2014,6 +2048,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
2014
2048
  subField: "outstandingNote",
2015
2049
  tone: "warn",
2016
2050
  toneField: "outstandingTone",
2051
+ visibleWhen: { field: "status", ne: "delivered" },
2017
2052
  navigate: { tab: "payments" },
2018
2053
  },
2019
2054
  {
@@ -2031,6 +2066,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
2031
2066
  kind: "relatedList",
2032
2067
  title: "order-desk.tab.items",
2033
2068
  countField: "itemsCount",
2069
+ after: { react: { __component: "OrderItemsFooter" } },
2034
2070
  query: "order-desk:query:order:items",
2035
2071
  columns: [
2036
2072
  { field: "sku", label: "order-desk.col.sku" },
@@ -2073,11 +2109,12 @@ export function createOrderDeskFeature(): FeatureDefinition {
2073
2109
  id: "details",
2074
2110
  kind: "fields",
2075
2111
  title: "order-desk.tab.details",
2076
- fields: ["shippingAddress", "billingAddress", "salesRep"],
2112
+ fields: ["shippingAddress", { field: "billingAddress", concealed: true }, "salesRep"],
2077
2113
  },
2078
2114
  {
2079
2115
  id: "internal-note",
2080
2116
  kind: "extension",
2117
+ hideOnNarrow: true,
2081
2118
  title: "order-desk.tab.internalNote",
2082
2119
  component: { react: { __component: "OrderInternalNote" } },
2083
2120
  entityName: "order",
@@ -2111,6 +2148,33 @@ export function createOrderDeskFeature(): FeatureDefinition {
2111
2148
  inlineActions: ["download-invoice"],
2112
2149
  access: accessRoles,
2113
2150
  });
2151
+
2152
+ r.screen({
2153
+ id: "order-facts",
2154
+ type: "projectionDetail",
2155
+ query: "order-desk:query:order:detail",
2156
+ listScreenId: "orders",
2157
+ header: { title: "customerName" },
2158
+ // Two short stacked sections need no "On this page" index.
2159
+ pageNavigation: false,
2160
+ layout: {
2161
+ sections: [
2162
+ {
2163
+ id: "contact",
2164
+ kind: "fields",
2165
+ title: "order-desk.facts.contact",
2166
+ fields: ["salesRep"],
2167
+ },
2168
+ {
2169
+ id: "address",
2170
+ kind: "fields",
2171
+ title: "order-desk.facts.address",
2172
+ fields: ["shippingAddress", "billingAddress"],
2173
+ },
2174
+ ],
2175
+ },
2176
+ access: accessRoles,
2177
+ });
2114
2178
  });
2115
2179
  }
2116
2180
  ```
@@ -2614,6 +2678,7 @@ export function answerOrderDetail(id: string) {
2614
2678
  path: [{ label: "Orders" }, { label: "Aiko Tanaka" }, { label: "SO-10482" }],
2615
2679
  summaryLine: "Waiting for the second payment",
2616
2680
  summaryShort: "Second payment open.",
2681
+ mobileLine: "€ 312.00 open of € 1,248.00",
2617
2682
  summaryTone: "warn",
2618
2683
  narrowSubtitle: "SO-10482 · placed 21 Aug",
2619
2684
  notice: { title: "Payment overdue", text: "312 EUR is 14 days overdue", tone: "bad" },
@@ -14,7 +14,7 @@ Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
14
14
 
15
15
  - `r.secret` + `ctx.services.secrets.get` (audited reads)
16
16
  - Charge-style handler that never returns the plaintext key
17
- - A system-scope secret edited on a `configEdit` screen (`secretKeys`) with a handler button row (`actions`)
17
+ - A system-scope secret edited on a `configEdit` screen (`secretKeys`) with a handler button row (`actions`) and `compact: true` (no origin icon, reset link or accent bar)
18
18
 
19
19
  ## Source
20
20
 
@@ -498,6 +498,8 @@ export function createBillingFeature(): FeatureDefinition {
498
498
  }),
499
499
  },
500
500
  layout: { variant: "settings-list", sections: [{ fields: ["signingKey"] }] },
501
+ // One write-only field needs no origin icon, reset link or accent bar.
502
+ compact: true,
501
503
  // A button row calls a handler with {} on the stored values; it is disabled while the
502
504
  // form has unsaved changes.
503
505
  actions: [
@@ -41,7 +41,7 @@ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sess
41
41
  import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
42
42
  import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
43
43
  import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
44
- import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
44
+ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
45
45
  import {
46
46
  createFilesFeature,
47
47
  createInMemoryFileProvider,
@@ -83,6 +83,7 @@ afterAll(async () => {
83
83
  await stack.cleanup();
84
84
  });
85
85
 
86
+ // The requester uploads the contract: a request needs a document its caller may open.
86
87
  async function seedContract(): Promise<string> {
87
88
  const bytes = await (async () => {
88
89
  const pdf = await PDFDocument.create();
@@ -101,7 +102,7 @@ async function seedContract(): Promise<string> {
101
102
  entityName: "fileRef",
102
103
  }).create(
103
104
  { storageKey, fileName: "contract.pdf", mimeType: "application/pdf", size: bytes.length },
104
- createSystemUser(TENANT),
105
+ admin,
105
106
  db,
106
107
  );
107
108
  if (!created.isSuccess) throw new Error(created.error.message);
@@ -20,6 +20,10 @@ shared chrome (footer, submit button) can be compared side by side.
20
20
  - `note-detail`, a `projectionDetail` screen whose only section is
21
21
  `kind: "writeForm"` with the identical field set, dispatching its own
22
22
  `note-desk:write:note:comment` handler on submit
23
+ - `note-triage`, an `actionForm`: `infoBand` draws the `assist` banner; the layout field
24
+ options `badge` (`{ label, tone }`) and `hintField` (a value field as muted hint) and a
25
+ `suffix` behind the number field. `FormProps.topBanner` is not shown: no screen
26
+ declaration reaches it
23
27
  - an e2e layout-parity spec (`e2e/writeform-parity.spec.ts`) proving both
24
28
  submit buttons render the same width, sit right-aligned in their form's
25
29
  footer, and never stretch full-width — the regression this recipe guards
@@ -606,6 +610,7 @@ import {
606
610
  sectionFieldSpecs,
607
611
  validateBoot as validateBootRaw,
608
612
  } from "@cosmicdrift/kumiko-framework/engine";
613
+ import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
609
614
  import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
610
615
  import { z } from "zod";
611
616
  import { noteDeskFeature } from "../feature";
@@ -712,6 +717,233 @@ describe("writeform-section sample — boot-validator catches author mistakes",
712
717
  );
713
718
  });
714
719
  });
720
+
721
+ describe("writeform-section sample — submitWith and narrow options", () => {
722
+ test("note-approval registers the form with submitWith and tab labels", () => {
723
+ expect(() => validateBoot([noteDeskFeature])).not.toThrow();
724
+ const screen = registry.getScreen("note-desk:screen:note-approval");
725
+ if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
726
+ const form = screen.layout.sections[0];
727
+ if (form?.kind !== "writeForm") throw new Error("expected writeForm section");
728
+ expect(form.submitWith).toBe("approve");
729
+ expect(screen.layout.sections.map((s) => s.tabLabel)).toEqual(["Review", "History"]);
730
+ expect(screen.layout.narrowTabs).toBe(false);
731
+ });
732
+
733
+ function approvalFeature(options: {
734
+ readonly submitWith: string;
735
+ readonly payload?: { readonly map: Record<string, string> };
736
+ readonly fields?: readonly string[];
737
+ }) {
738
+ return defineFeature("approval-desk", (r) => {
739
+ r.translations({
740
+ keys: {
741
+ "screen:x.title": { en: "X" },
742
+ "approval-desk:entity:__write-form-section__:field:name": { en: "Name" },
743
+ "approval-desk:entity:__write-form-section__:field:noteId": { en: "Note" },
744
+ },
745
+ });
746
+ const access = {
747
+ openToAll: { reason: "test handler callable by any signed-in test user" },
748
+ } as const;
749
+ r.queryHandler({
750
+ name: "foo:detail",
751
+ schema: z.object({ id: z.string() }),
752
+ handler: async () => ({}),
753
+ access,
754
+ });
755
+ r.writeHandler({
756
+ name: "approve",
757
+ schema: z.object({}).passthrough(),
758
+ handler: async () => ({ isSuccess: true as const, data: null }),
759
+ access,
760
+ });
761
+ const text = createTextField({ personal: false, reason: "is_business_data" });
762
+ r.screen({
763
+ id: "x",
764
+ type: "projectionDetail",
765
+ query: "approval-desk:query:foo:detail",
766
+ layout: {
767
+ sections: [
768
+ {
769
+ kind: "writeForm",
770
+ title: "s",
771
+ fieldDefs: { name: text, noteId: text },
772
+ fields: options.fields ?? ["name"],
773
+ handler: "approval-desk:write:approve",
774
+ submitWith: options.submitWith,
775
+ },
776
+ ],
777
+ },
778
+ actions: [
779
+ {
780
+ id: "approve",
781
+ label: "Approve",
782
+ handler: "approval-desk:write:approve",
783
+ ...(options.payload !== undefined && { payload: options.payload }),
784
+ },
785
+ ],
786
+ });
787
+ });
788
+ }
789
+
790
+ test("in a tabs layout the submitWith action must be limited to the form's tab", () => {
791
+ const tabsFeature = (showOnTabs: readonly string[] | undefined) =>
792
+ defineFeature("tabs-desk", (r) => {
793
+ r.translations({
794
+ keys: {
795
+ "screen:x.title": { en: "X" },
796
+ "tabs-desk:entity:__write-form-section__:field:name": { en: "Name" },
797
+ },
798
+ });
799
+ const access = {
800
+ openToAll: { reason: "test handler callable by any signed-in test user" },
801
+ } as const;
802
+ r.queryHandler({
803
+ name: "foo:detail",
804
+ schema: z.object({ id: z.string() }),
805
+ handler: async () => ({}),
806
+ access,
807
+ });
808
+ r.writeHandler({
809
+ name: "approve",
810
+ schema: z.object({}).passthrough(),
811
+ handler: async () => ({ isSuccess: true as const, data: null }),
812
+ access,
813
+ });
814
+ const text = createTextField({ personal: false, reason: "is_business_data" });
815
+ r.screen({
816
+ id: "x",
817
+ type: "projectionDetail",
818
+ query: "tabs-desk:query:foo:detail",
819
+ layout: {
820
+ mode: "tabs",
821
+ sections: [
822
+ {
823
+ id: "review",
824
+ kind: "writeForm",
825
+ title: "s",
826
+ fieldDefs: { name: text },
827
+ fields: ["name"],
828
+ handler: "tabs-desk:write:approve",
829
+ submitWith: "approve",
830
+ },
831
+ { id: "log", title: "Log", fields: ["name"] },
832
+ ],
833
+ },
834
+ actions: [
835
+ {
836
+ id: "approve",
837
+ label: "Approve",
838
+ handler: "tabs-desk:write:approve",
839
+ ...(showOnTabs !== undefined && { showOnTabs }),
840
+ },
841
+ ],
842
+ });
843
+ });
844
+ expect(() => validateBoot([tabsFeature(undefined)])).toThrow('showOnTabs: ["<that id>"]');
845
+ expect(() => validateBoot([tabsFeature(["review", "log"])])).toThrow("showOnTabs");
846
+ expect(() => validateBoot([tabsFeature(["review"])])).not.toThrow();
847
+ });
848
+
849
+ test("submitWith that names no action of the screen fails boot", () => {
850
+ expect(() => validateBoot([approvalFeature({ submitWith: "missing" })])).toThrow(
851
+ 'sets submitWith "missing"',
852
+ );
853
+ });
854
+
855
+ test("a form field that the action also sends in its payload fails boot", () => {
856
+ expect(() =>
857
+ validateBoot([
858
+ approvalFeature({
859
+ submitWith: "approve",
860
+ payload: { map: { noteId: "id" } },
861
+ fields: ["name", "noteId"],
862
+ }),
863
+ ]),
864
+ ).toThrow('has the field "noteId"');
865
+ });
866
+
867
+ test("a valid submitWith boots", () => {
868
+ expect(() =>
869
+ validateBoot([
870
+ approvalFeature({ submitWith: "approve", payload: { map: { noteId: "id" } } }),
871
+ ]),
872
+ ).not.toThrow();
873
+ });
874
+ });
875
+
876
+ describe("writeform-section sample — presentation options are checked at boot", () => {
877
+ function detailFeature(
878
+ layout: ProjectionDetailScreenDefinition["layout"],
879
+ actions?: ProjectionDetailScreenDefinition["actions"],
880
+ ) {
881
+ return defineFeature("layout-desk", (r) => {
882
+ r.translations({ keys: { "screen:x.title": { en: "X" } } });
883
+ r.queryHandler({
884
+ name: "foo:detail",
885
+ schema: z.object({ id: z.string() }),
886
+ handler: async () => ({}),
887
+ access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
888
+ });
889
+ r.screen({
890
+ id: "x",
891
+ type: "projectionDetail",
892
+ query: "layout-desk:query:foo:detail",
893
+ layout,
894
+ ...(actions !== undefined && { actions }),
895
+ });
896
+ });
897
+ }
898
+ const fields = ["name"];
899
+
900
+ test("hideOnNarrow together with showOnNarrowOnly fails", () => {
901
+ expect(() =>
902
+ validateBoot([
903
+ detailFeature({ sections: [{ fields, hideOnNarrow: true, showOnNarrowOnly: true }] }),
904
+ ]),
905
+ ).toThrow("hideOnNarrow and showOnNarrowOnly");
906
+ });
907
+
908
+ test("tabLabel and narrowTabs without tabs mode fail", () => {
909
+ expect(() =>
910
+ validateBoot([detailFeature({ sections: [{ fields, tabLabel: "Tab" }] })]),
911
+ ).toThrow("tabLabel without layout.mode");
912
+ expect(() =>
913
+ validateBoot([detailFeature({ narrowTabs: false, sections: [{ fields }] })]),
914
+ ).toThrow("narrowTabs without layout.mode");
915
+ });
916
+
917
+ test("photoGrid.badgeFirst without badgeField fails", () => {
918
+ expect(() =>
919
+ validateBoot([
920
+ detailFeature({
921
+ sections: [
922
+ {
923
+ kind: "relatedList",
924
+ title: "Photos",
925
+ query: "layout-desk:query:foo:detail",
926
+ parentParam: "id",
927
+ columns: [{ field: "name", label: "Name" }],
928
+ photoGrid: { imageField: "name", badgeFirst: true },
929
+ },
930
+ ],
931
+ }),
932
+ ]),
933
+ ).toThrow("badgeFirst without badgeField");
934
+ });
935
+
936
+ test("a navigate action with icon: false needs no icon", () => {
937
+ const action = {
938
+ kind: "navigate" as const,
939
+ id: "open-board",
940
+ label: "Board",
941
+ screen: "x",
942
+ icon: false as const,
943
+ };
944
+ expect(() => validateBoot([detailFeature({ sections: [{ fields }] }, [action])])).not.toThrow();
945
+ });
946
+ });
715
947
  ```
716
948
 
717
949
  ### src/feature.ts
@@ -771,11 +1003,21 @@ const commentPayloadSchema = z.object({
771
1003
  priority: z.number().optional(),
772
1004
  });
773
1005
 
1006
+ const approvePayloadSchema = z.object({
1007
+ noteId: z.string(),
1008
+ title: z.string().optional(),
1009
+ body: z.string().optional(),
1010
+ });
1011
+
774
1012
  export const noteDeskFeature = defineFeature("note-desk", (r) => {
775
1013
  r.translations({
776
1014
  keys: {
777
1015
  "screen:note-edit.title": { en: "Edit note" },
778
1016
  "screen:note-detail.title": { en: "Note" },
1017
+ "screen:note-triage.title": { en: "Triage note" },
1018
+ "note-desk:triage.info-band": { en: "Check the category, then send the note on." },
1019
+ "note-desk:triage.badge-review": { en: "Needs review" },
1020
+ "note-desk:triage.priority-suffix": { en: "pts" },
779
1021
  "note-desk:entity:note:field:title": { en: "Title" },
780
1022
  "note-desk:entity:note:field:body": { en: "Body" },
781
1023
  "note-desk:entity:note:field:category": { en: "Category" },
@@ -839,6 +1081,93 @@ export const noteDeskFeature = defineFeature("note-desk", (r) => {
839
1081
  },
840
1082
  access: open.access,
841
1083
  });
1084
+
1085
+ // An actionForm reaches the "assist" banner through `infoBand`; the layout field options
1086
+ // `badge`, `hintField` and `suffix` work on any form layout.
1087
+ r.screen({
1088
+ id: "note-triage",
1089
+ type: "actionForm",
1090
+ handler: "note-desk:write:note:comment",
1091
+ dormant: true,
1092
+ infoBand: "note-desk:triage.info-band",
1093
+ fields: {
1094
+ title: NOTE_FIELDS.title,
1095
+ body: NOTE_FIELDS.body,
1096
+ category: NOTE_FIELDS.category,
1097
+ priority: NOTE_FIELDS.priority,
1098
+ },
1099
+ layout: {
1100
+ sections: [
1101
+ {
1102
+ columns: 1,
1103
+ fields: [
1104
+ { field: "title", badge: { label: "note-desk:triage.badge-review", tone: "warn" } },
1105
+ { field: "category" },
1106
+ { field: "body", hintField: "category" },
1107
+ { field: "priority", suffix: "note-desk:triage.priority-suffix" },
1108
+ ],
1109
+ },
1110
+ ],
1111
+ },
1112
+ access: open.access,
1113
+ });
1114
+
1115
+ r.writeHandler({
1116
+ name: "note:approve",
1117
+ schema: approvePayloadSchema,
1118
+ handler: async () => ({ isSuccess: true as const, data: null }),
1119
+ ...open,
1120
+ });
1121
+
1122
+ // The footer action "approve" submits the form: one write with its own payload (noteId)
1123
+ // plus the form values, after form validation. The tab strip is phone-free; the "Review"
1124
+ // section stands above the "History" section there.
1125
+ r.screen({
1126
+ id: "note-approval",
1127
+ type: "projectionDetail",
1128
+ query: "note-desk:query:note:summary",
1129
+ layout: {
1130
+ mode: "tabs",
1131
+ narrowTabs: false,
1132
+ sections: [
1133
+ {
1134
+ id: "review",
1135
+ tabLabel: "Review",
1136
+ kind: "writeForm",
1137
+ title: "Decision",
1138
+ description: "Confirm the note and leave a reason.",
1139
+ descriptionNarrow: "Leave a reason.",
1140
+ columns: 1,
1141
+ fieldDefs: {
1142
+ title: NOTE_FIELDS.title,
1143
+ body: NOTE_FIELDS.body,
1144
+ },
1145
+ fields: ["title", { field: "body", hideOnNarrow: true }],
1146
+ handler: "note-desk:write:note:approve",
1147
+ submitWith: "approve",
1148
+ },
1149
+ {
1150
+ id: "history",
1151
+ tabLabel: "History",
1152
+ title: "History",
1153
+ titleOnNarrow: false,
1154
+ fields: ["category", "priority"],
1155
+ },
1156
+ ],
1157
+ },
1158
+ actions: [
1159
+ {
1160
+ id: "approve",
1161
+ label: "Approve",
1162
+ handler: "note-desk:write:note:approve",
1163
+ payload: { map: { noteId: "id" } },
1164
+ // Tabs layout: only the tab that mounts the form may show the action.
1165
+ showOnTabs: ["review"],
1166
+ },
1167
+ ],
1168
+ footerActions: ["approve"],
1169
+ access: open.access,
1170
+ });
842
1171
  });
843
1172
  ```
844
1173
 
@@ -668,7 +668,7 @@ Exposes APIs: `sessions.revokeAllForUser`
668
668
 
669
669
  ## signature
670
670
 
671
- Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.
671
+ Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined, expired and failed report the outcome; signer name, email, image, IP and user agent are personal data.
672
672
 
673
673
  Category: data
674
674
 
@@ -3,6 +3,7 @@ import type { createFallbackLogger } from "../logging/index.ts";
3
3
  import type { AuthRoutesConfig } from "./auth-routes.ts";
4
4
  export type BootLogger = ReturnType<typeof createFallbackLogger>;
5
5
  export declare function assertNoPayloadRateLimitsWithoutResolver(registry: Registry): void;
6
+ export declare function warnNonIpRateLimitsWithoutResolver(registry: Registry, bootLog: BootLogger): void;
6
7
  export declare function assertFileStorageProviderForFileFields(registry: Registry, context: AppContext): void;
7
8
  export declare function warnSearchableScreensWithoutSearchAdapter(registry: Registry, context: AppContext, bootLog: BootLogger): void;
8
9
  export declare function resolveServerInstanceId(explicitInstanceId: string | undefined, bootLog: BootLogger): string;
@@ -1,3 +1,5 @@
1
+ import { declaredRateLimitOptions } from "@cosmicdrift/kumiko-types/handlers";
2
+ import { IP_BUCKETED_RATE_LIMIT_PER } from "../engine/boot-validator/entity-handler.js";
1
3
  import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
2
4
  import { holdsFileRefs } from "../files/file-field-slots.js";
3
5
  import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
@@ -20,6 +22,29 @@ export function assertNoPayloadRateLimitsWithoutResolver(registry) {
20
22
  "Wire a Redis client on context.redis (or pass context.rateLimit), or drop the payload buckets " +
21
23
  "(for the waitlist: emailRateLimits: []).");
22
24
  }
25
+ // ip buckets pass through without a client IP; tenant/user buckets always need the resolver, so
26
+ // the first call would answer 500 (InternalError in enforceRateLimit). Only a warning: Redis-less
27
+ // dev and self-hosting setups must still boot.
28
+ export function warnNonIpRateLimitsWithoutResolver(registry, bootLog) {
29
+ const hasNonIpBucket = (rateLimit) => declaredRateLimitOptions(rateLimit).some((option) => !IP_BUCKETED_RATE_LIMIT_PER.has(option.per));
30
+ const offenders = [];
31
+ for (const feature of registry.features.values()) {
32
+ for (const [name, handler] of Object.entries(feature.writeHandlers)) {
33
+ if (hasNonIpBucket(handler.rateLimit))
34
+ offenders.push(`${feature.name}:write:${name}`);
35
+ }
36
+ for (const [name, handler] of Object.entries(feature.queryHandlers)) {
37
+ if (hasNonIpBucket(handler.rateLimit))
38
+ offenders.push(`${feature.name}:query:${name}`);
39
+ }
40
+ }
41
+ // skip: no handler has a tenant/user bucket
42
+ if (offenders.length === 0)
43
+ return;
44
+ bootLog.warn(`Handlers declare a tenant/user rateLimit but no RateLimitResolver is configured, so they answer ` +
45
+ `every call with a 500: ${offenders.join(", ")}. ` +
46
+ "Wire a Redis client on context.redis (or pass context.rateLimit) to enable the resolver.");
47
+ }
23
48
  export function assertFileStorageProviderForFileFields(registry, context) {
24
49
  // File-storage is resolved per-tenant through file-foundation: a mounted
25
50
  // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for