@cosmicdrift/kumiko-framework 0.416.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 (48) hide show
  1. package/agents/api/framework-engine.md +31 -9
  2. package/agents/api/framework-ui-types.md +23 -5
  3. package/agents/api/renderer-web.md +24 -2
  4. package/agents/api/types.md +94 -60
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +3 -1
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/event-sourcing.md +84 -0
  9. package/agents/examples/list-table-options.md +71 -5
  10. package/agents/examples/managed-config.md +9 -1
  11. package/agents/examples/record-detail-layout.md +71 -6
  12. package/agents/examples/secrets-demo.md +3 -1
  13. package/agents/examples/signature.md +3 -2
  14. package/agents/examples/writeform-section.md +329 -0
  15. package/dist/db/queries/event-store.d.ts +3 -0
  16. package/dist/db/queries/event-store.js +12 -0
  17. package/dist/engine/boot-validator/boot-rules.d.ts +11 -1
  18. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  19. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  20. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  21. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  22. package/dist/engine/boot-validator/list-table-options.js +8 -6
  23. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  24. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  25. package/dist/engine/boot-validator/query-output-columns.js +4 -0
  26. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  27. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  28. package/dist/engine/boot-validator/screens-actions.js +2 -0
  29. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  30. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  31. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  32. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  33. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  34. package/dist/engine/boot-validator/screens.js +1 -2
  35. package/dist/engine/bridge-stub.js +1 -0
  36. package/dist/engine/build-config-feature-schema.js +25 -2
  37. package/dist/engine/screen-helpers.js +7 -3
  38. package/dist/event-store/archive.d.ts +1 -0
  39. package/dist/event-store/archive.js +5 -1
  40. package/dist/event-store/event-store.d.ts +5 -0
  41. package/dist/event-store/event-store.js +23 -3
  42. package/dist/i18n/required-surface-keys.js +6 -0
  43. package/dist/pipeline/handler-context-events.js +15 -1
  44. package/dist/ui-types/card-column-roles.d.ts +3 -0
  45. package/dist/ui-types/card-column-roles.js +9 -5
  46. package/dist/ui-types/index.d.ts +1 -1
  47. package/package.json +3 -3
  48. package/src/changes.json +6 -0
@@ -1696,6 +1696,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1696
1696
  readonly summary: "Every rendered writeForm field has a fieldDefs entry.";
1697
1697
  readonly fix: "Add the field to fieldDefs.";
1698
1698
  };
1699
+ readonly submitWithInvalid: {
1700
+ readonly id: "projection-detail/submit-with-invalid";
1701
+ readonly summary: "A writeForm submitWith names a writeHandler action of the screen, no other form uses the same action, and no form field shares a name with the action's payload keys.";
1702
+ readonly fix: "Point submitWith at a writeHandler action id in screen.actions, give each form its own action, and rename the colliding field or payload key.";
1703
+ };
1704
+ readonly presentationOptionInvalid: {
1705
+ readonly id: "projection-detail/presentation-option-invalid";
1706
+ readonly summary: 'tabLabel and layout.narrowTabs need layout.mode "tabs"; hideOnNarrow and showOnNarrowOnly exclude each other on a section; photoGrid.badgeFirst needs badgeField.';
1707
+ readonly fix: "Use tabs mode for tabLabel/narrowTabs, set only one of hideOnNarrow/showOnNarrowOnly, and set badgeField next to badgeFirst.";
1708
+ };
1699
1709
  readonly wizardWriteForm: {
1700
1710
  readonly id: "projection-detail/wizard-write-form";
1701
1711
  readonly summary: "A wizard-mode layout has no writeForm section.";
@@ -2518,7 +2528,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2518
2528
  };
2519
2529
  readonly hiddenWithoutColumnPicker: {
2520
2530
  readonly id: "list-table/hidden-without-column-picker";
2521
- readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them.";
2531
+ readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them; a hidden column that backs a facet is exempt.";
2522
2532
  readonly fix: "Set table: { columnPicker: true } or remove hidden from the column.";
2523
2533
  };
2524
2534
  readonly hidesEveryColumn: {
@@ -29,11 +29,15 @@ function countOverflow(feature, screen, location, columns, storedTypeOf, entity)
29
29
  renderer: col.renderer,
30
30
  hideOnNarrow: col.hideOnNarrow,
31
31
  narrowInline: col.narrowInline,
32
+ cardBadge: col.cardBadge,
33
+ cardAbove: col.cardAbove,
32
34
  hint: col.hint,
35
+ emphasis: col.emphasis,
33
36
  ...(fileKind !== undefined && { fileDisplay: { kind: fileKind } }),
34
37
  };
35
38
  });
36
- const { meta } = cardColumnRoles(cardColumns);
39
+ // The card draws `cardAbove` columns above the title, not as meta lines.
40
+ const meta = cardColumnRoles(cardColumns).meta.filter((col) => col.cardAbove !== true);
37
41
  const lineCount = cardMetaLines(meta).length;
38
42
  if (lineCount <= CARD_META_MAX)
39
43
  return undefined;
@@ -20,6 +20,7 @@ export declare function validatePhotoGrid(where: string, section: {
20
20
  readonly photoGrid?: {
21
21
  readonly imageField: string;
22
22
  readonly captionField?: string;
23
+ readonly badgeField?: string;
23
24
  };
24
25
  }): void;
25
26
  type GuidanceListKind = "entityList" | "projectionList" | "dashboard" | "relatedList";
@@ -69,6 +69,7 @@ export function validatePhotoGrid(where, section) {
69
69
  for (const [option, field] of [
70
70
  ["imageField", photoGrid.imageField],
71
71
  ["captionField", photoGrid.captionField],
72
+ ["badgeField", photoGrid.badgeField],
72
73
  ]) {
73
74
  if (field === undefined || columnFields.has(field))
74
75
  continue;
@@ -1,3 +1,3 @@
1
1
  import { type ListColumnSpec } from "../types/screen.ts";
2
2
  /** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
3
- export declare function validateListTableOptions(where: string, table: unknown, columns: readonly ListColumnSpec[], exportAllowed?: boolean): void;
3
+ export declare function validateListTableOptions(where: string, table: unknown, columns: readonly ListColumnSpec[], exportAllowed?: boolean, facetFields?: readonly string[]): void;
@@ -43,7 +43,7 @@ function validateDensity(where, density) {
43
43
  });
44
44
  }
45
45
  }
46
- function validateHiddenColumns(where, columnPickerOn, columns) {
46
+ function validateHiddenColumns(where, columnPickerOn, columns, facetFields) {
47
47
  const normalized = columns.map(normalizeListColumn);
48
48
  for (const col of normalized) {
49
49
  if (col.hidden !== undefined && typeof col.hidden !== "boolean") {
@@ -56,9 +56,11 @@ function validateHiddenColumns(where, columnPickerOn, columns) {
56
56
  // skip: no hidden columns, nothing to validate
57
57
  if (hidden.length === 0)
58
58
  return;
59
- if (!columnPickerOn) {
59
+ // A hidden column that only backs a facet never needs to be shown; the facet is its UI.
60
+ const unreachable = hidden.find((col) => !facetFields.includes(col.field));
61
+ if (!columnPickerOn && unreachable !== undefined) {
60
62
  throw bootRuleError(LIST_TABLE_RULES.hiddenWithoutColumnPicker, {
61
- message: `${where} column "${hidden[0]?.field}" is hidden but table.columnPicker is not enabled, ` +
63
+ message: `${where} column "${unreachable.field}" is hidden but table.columnPicker is not enabled, ` +
62
64
  `so the user could never show it. Set table: { columnPicker: true } or remove "hidden".`,
63
65
  });
64
66
  }
@@ -69,9 +71,9 @@ function validateHiddenColumns(where, columnPickerOn, columns) {
69
71
  }
70
72
  }
71
73
  /** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
72
- export function validateListTableOptions(where, table, columns, exportAllowed = false) {
74
+ export function validateListTableOptions(where, table, columns, exportAllowed = false, facetFields = []) {
73
75
  if (table === undefined) {
74
- validateHiddenColumns(where, false, columns);
76
+ validateHiddenColumns(where, false, columns, facetFields);
75
77
  validateColumnLayout(where, { pinning: false, resizing: false }, columns);
76
78
  // skip: no table block: nothing else to check
77
79
  return;
@@ -107,6 +109,6 @@ export function validateListTableOptions(where, table, columns, exportAllowed =
107
109
  message: `${where} sets table.summaryRow and table.totals; a table has one footer. Keep one of them.`,
108
110
  });
109
111
  }
110
- validateHiddenColumns(where, table["columnPicker"] === true, columns);
112
+ validateHiddenColumns(where, table["columnPicker"] === true, columns, facetFields);
111
113
  validateColumnLayout(where, { pinning: table["pinning"] === true, resizing: table["resizing"] === true }, columns);
112
114
  }
@@ -46,7 +46,7 @@ export declare const LIST_TABLE_RULES: {
46
46
  };
47
47
  readonly hiddenWithoutColumnPicker: {
48
48
  readonly id: "list-table/hidden-without-column-picker";
49
- readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them.";
49
+ readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them; a hidden column that backs a facet is exempt.";
50
50
  readonly fix: "Set table: { columnPicker: true } or remove hidden from the column.";
51
51
  };
52
52
  readonly hidesEveryColumn: {
@@ -46,7 +46,7 @@ export const LIST_TABLE_RULES = {
46
46
  },
47
47
  hiddenWithoutColumnPicker: {
48
48
  id: "list-table/hidden-without-column-picker",
49
- summary: "Hidden columns need table.columnPicker, otherwise the user can never show them.",
49
+ summary: "Hidden columns need table.columnPicker, otherwise the user can never show them; a hidden column that backs a facet is exempt.",
50
50
  fix: "Set table: { columnPicker: true } or remove hidden from the column.",
51
51
  },
52
52
  hidesEveryColumn: {
@@ -133,6 +133,10 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
133
133
  for (const metric of screen.metrics ?? []) {
134
134
  const field = metric.field;
135
135
  checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
136
+ if (metric.visibleWhen !== undefined) {
137
+ const conditionField = metric.visibleWhen.field;
138
+ checkFieldExists(recordShape, conditionField, () => `${prefix} metric "${field}" visibleWhen references field "${conditionField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
139
+ }
136
140
  }
137
141
  for (const { option, field } of detailGuidanceFieldRefs(screen)) {
138
142
  checkFieldExists(recordShape, field, () => `${prefix} ${option} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
@@ -12,6 +12,7 @@ export function detailGuidanceFieldRefs(screen) {
12
12
  { option: "steps.field", field: screen.steps?.field },
13
13
  { option: "steps.subtitleField", field: screen.steps?.subtitleField },
14
14
  { option: "progress.field", field: screen.progress?.field },
15
+ { option: "mobileSummary", field: screen.mobileSummary },
15
16
  ...(screen.metrics ?? []).flatMap((metric) => [
16
17
  { option: "metrics.toneField", field: metric.toneField },
17
18
  { option: "metrics.subField", field: metric.subField },
@@ -12,7 +12,7 @@ export declare function validateRowActionNavigateParams(featureName: string, scr
12
12
  } | undefined, actionLabel?: "rowAction" | "emptyState action"): void;
13
13
  export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList" | "dashboard", context: string, action: {
14
14
  readonly id: string;
15
- readonly icon?: IconKey;
15
+ readonly icon?: IconKey | false;
16
16
  }): void;
17
17
  export declare function validateActionFieldRefs(featureName: string, screenId: string, actionKind: "rowAction" | "toolbarAction", actionId: string, action: RowAction | ToolbarAction | RelatedListToolbarAction, fieldNames: ReadonlySet<string>, rowMeta: ReadonlySet<string>): void;
18
18
  export declare function validateScreenShortIdCollisions(screensByShortId: ReadonlyMap<string, ReadonlyArray<{
@@ -125,6 +125,8 @@ function isRegisteredIcon(icon) {
125
125
  return isOneOf(NAV_ICON_KEYS, icon);
126
126
  }
127
127
  export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
128
+ if (action.icon === false)
129
+ return;
128
130
  const resolved = resolveActionIcon(action.id, action.icon);
129
131
  if (resolved === undefined || !isRegisteredIcon(resolved)) {
130
132
  throw bootRuleError(SCREEN_ACTION_RULES.actionIcon, {
@@ -236,7 +236,9 @@ export function validateEntityListScreen(ctx, screenId, screen) {
236
236
  });
237
237
  }
238
238
  const where = `[Feature ${featureName}] Screen "${screenId}" (entityList)`;
239
- validateListTableOptions(where, screen.table, screen.columns, true);
239
+ validateListTableOptions(where, screen.table, screen.columns, true, Object.entries(screen.facets ?? {})
240
+ .filter(([, facet]) => facet !== false)
241
+ .map(([field]) => field));
240
242
  validateEntityListAggregateOptions(where, screen, fields.entityDef);
241
243
  if (screen.defaultSort !== undefined) {
242
244
  validateEntityListDefaultSort(featureName, screenId, screen.defaultSort, fields);
@@ -114,6 +114,16 @@ export declare const PROJECTION_DETAIL_RULES: {
114
114
  readonly summary: "Every rendered writeForm field has a fieldDefs entry.";
115
115
  readonly fix: "Add the field to fieldDefs.";
116
116
  };
117
+ readonly submitWithInvalid: {
118
+ readonly id: "projection-detail/submit-with-invalid";
119
+ readonly summary: "A writeForm submitWith names a writeHandler action of the screen, no other form uses the same action, and no form field shares a name with the action's payload keys.";
120
+ readonly fix: "Point submitWith at a writeHandler action id in screen.actions, give each form its own action, and rename the colliding field or payload key.";
121
+ };
122
+ readonly presentationOptionInvalid: {
123
+ readonly id: "projection-detail/presentation-option-invalid";
124
+ readonly summary: 'tabLabel and layout.narrowTabs need layout.mode "tabs"; hideOnNarrow and showOnNarrowOnly exclude each other on a section; photoGrid.badgeFirst needs badgeField.';
125
+ readonly fix: "Use tabs mode for tabLabel/narrowTabs, set only one of hideOnNarrow/showOnNarrowOnly, and set badgeField next to badgeFirst.";
126
+ };
117
127
  readonly wizardWriteForm: {
118
128
  readonly id: "projection-detail/wizard-write-form";
119
129
  readonly summary: "A wizard-mode layout has no writeForm section.";
@@ -114,6 +114,16 @@ export const PROJECTION_DETAIL_RULES = {
114
114
  summary: "Every rendered writeForm field has a fieldDefs entry.",
115
115
  fix: "Add the field to fieldDefs.",
116
116
  },
117
+ submitWithInvalid: {
118
+ id: "projection-detail/submit-with-invalid",
119
+ summary: "A writeForm submitWith names a writeHandler action of the screen, no other form uses the same action, and no form field shares a name with the action's payload keys.",
120
+ fix: "Point submitWith at a writeHandler action id in screen.actions, give each form its own action, and rename the colliding field or payload key.",
121
+ },
122
+ presentationOptionInvalid: {
123
+ id: "projection-detail/presentation-option-invalid",
124
+ summary: 'tabLabel and layout.narrowTabs need layout.mode "tabs"; hideOnNarrow and showOnNarrowOnly exclude each other on a section; photoGrid.badgeFirst needs badgeField.',
125
+ fix: "Use tabs mode for tabLabel/narrowTabs, set only one of hideOnNarrow/showOnNarrowOnly, and set badgeField next to badgeFirst.",
126
+ },
117
127
  wizardWriteForm: {
118
128
  id: "projection-detail/wizard-write-form",
119
129
  summary: "A wizard-mode layout has no writeForm section.",
@@ -75,6 +75,85 @@ function validateProjectionDetailInitialTab(featureName, screenId, screen) {
75
75
  }
76
76
  }
77
77
  }
78
+ function payloadKeysOf(action) {
79
+ const { payload } = action;
80
+ if (payload === undefined)
81
+ return ["id"];
82
+ return "pick" in payload ? [...payload.pick] : Object.keys(payload.map);
83
+ }
84
+ function validateSectionPresentationFlags(where, label, section, isTabs) {
85
+ if (section.tabLabel !== undefined && !isTabs) {
86
+ throw bootRuleError(PROJECTION_DETAIL_RULES.presentationOptionInvalid, {
87
+ message: `${where} section "${label}" sets tabLabel without layout.mode "tabs".`,
88
+ });
89
+ }
90
+ if (section.hideOnNarrow === true && section.showOnNarrowOnly === true) {
91
+ throw bootRuleError(PROJECTION_DETAIL_RULES.presentationOptionInvalid, {
92
+ message: `${where} section "${label}" sets both hideOnNarrow and showOnNarrowOnly — the section would never show.`,
93
+ });
94
+ }
95
+ if (section.kind === "relatedList" &&
96
+ section.photoGrid?.badgeFirst === true &&
97
+ section.photoGrid.badgeField === undefined) {
98
+ throw bootRuleError(PROJECTION_DETAIL_RULES.presentationOptionInvalid, {
99
+ message: `${where} section "${label}" sets photoGrid.badgeFirst without badgeField.`,
100
+ });
101
+ }
102
+ }
103
+ function validateSubmitWithSection(where, label, screen, section, submitWith, isTabs, submitWithIds) {
104
+ const action = (screen.actions ?? []).find((a) => a.id === submitWith);
105
+ if (action === undefined ||
106
+ action.kind === "navigate" ||
107
+ action.kind === "drawer" ||
108
+ action.kind === "clientAction") {
109
+ throw bootRuleError(PROJECTION_DETAIL_RULES.submitWithInvalid, {
110
+ message: `${where} section "${label}" sets submitWith "${submitWith}", which is not a writeHandler action in screen.actions.`,
111
+ });
112
+ }
113
+ if (submitWithIds.has(submitWith)) {
114
+ throw bootRuleError(PROJECTION_DETAIL_RULES.submitWithInvalid, {
115
+ message: `${where} action "${submitWith}" is the submitWith of more than one writeForm — it can send one form only.`,
116
+ });
117
+ }
118
+ submitWithIds.add(submitWith);
119
+ // In tabs mode only the active tab's form is mounted, so the action must not show on any other tab.
120
+ if (isTabs &&
121
+ (section.id === undefined ||
122
+ action.showOnTabs === undefined ||
123
+ action.showOnTabs.length === 0 ||
124
+ action.showOnTabs.some((tab) => tab !== section.id))) {
125
+ throw bootRuleError(PROJECTION_DETAIL_RULES.submitWithInvalid, {
126
+ message: `${where} action "${action.id}" is the submitWith of section "${label}" in a tabs layout, so it needs an id on that section and showOnTabs: ["<that id>"] — a form on another tab is not mounted and would not be sent.`,
127
+ });
128
+ }
129
+ const payloadKeys = payloadKeysOf(action);
130
+ const clash = section.fields
131
+ .map((f) => normalizeEditField(f).field)
132
+ .find((name) => payloadKeys.includes(name));
133
+ if (clash !== undefined) {
134
+ throw bootRuleError(PROJECTION_DETAIL_RULES.submitWithInvalid, {
135
+ message: `${where} section "${label}" has the field "${clash}", which action "${action.id}" also sends in its payload — the write would be ambiguous. Rename the field or the payload key.`,
136
+ });
137
+ }
138
+ }
139
+ // A wrong submitWith or a flag the renderer would ignore must fail at boot, not silently do nothing.
140
+ function validateProjectionDetailPresentation(featureName, screenId, screen) {
141
+ const where = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
142
+ const isTabs = screen.layout.mode === "tabs";
143
+ if (screen.layout.narrowTabs !== undefined && !isTabs) {
144
+ throw bootRuleError(PROJECTION_DETAIL_RULES.presentationOptionInvalid, {
145
+ message: `${where} sets layout.narrowTabs without layout.mode "tabs".`,
146
+ });
147
+ }
148
+ const submitWithIds = new Set();
149
+ for (const section of screen.layout.sections) {
150
+ const label = editSectionLabel(section);
151
+ validateSectionPresentationFlags(where, label, section, isTabs);
152
+ if (!isWriteFormEditSection(section) || section.submitWith === undefined)
153
+ continue;
154
+ validateSubmitWithSection(where, label, screen, section, section.submitWith, isTabs, submitWithIds);
155
+ }
156
+ }
78
157
  function validateProjectionDetailMetricNavigate(ctx, screenId, screen, field, navigate) {
79
158
  const featureName = ctx.feature.name;
80
159
  if (navigate.screen === undefined && navigate.entity === undefined) {
@@ -313,6 +392,7 @@ export function validateProjectionDetailScreen(ctx, screenId, screen) {
313
392
  rejectEmptySections(featureName, screenId, "projectionDetail", screen.layout.sections.length);
314
393
  validateProjectionDetailTabs(featureName, screenId, screen);
315
394
  validateProjectionDetailInitialTab(featureName, screenId, screen);
395
+ validateProjectionDetailPresentation(featureName, screenId, screen);
316
396
  for (const metric of screen.metrics ?? []) {
317
397
  validateProjectionDetailMetric(ctx, screenId, screen, metric);
318
398
  }
@@ -41,7 +41,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
41
41
  validateListColumnRendering(ctx, screenId, "projectionList", normalizeListColumn(col));
42
42
  }
43
43
  validateListRowGuidance(featureName, screenId, "projectionList", screen);
44
- validateListTableOptions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.table, screen.columns, true);
44
+ validateListTableOptions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.table, screen.columns, true, screen.facets?.map((facet) => facet.field));
45
45
  validateListToolbarOptions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen);
46
46
  // Screen filter: field existence can't be checked without an entity (columns
47
47
  // aren't a complete field inventory of the underlying query), so only the
@@ -1,7 +1,7 @@
1
1
  import { bootRuleError } from "./boot-rule.js";
2
2
  import { SCREEN_RULES } from "./screens-rules.js";
3
3
  import { qualifyEntityName } from "../qualified-name.js";
4
- import { validateActionHasIcon, validateScreenVisibleWhen } from "./screens-actions.js";
4
+ import { validateScreenVisibleWhen } from "./screens-actions.js";
5
5
  import { validateDashboardActions, validateDashboardRecordBinding, validateDashboardScreen, } from "./screens-dashboard.js";
6
6
  import { validateInlineFormScreen } from "./screens-forms.js";
7
7
  import { validateConfigEditScreen } from "./screens-kind-config-edit.js";
@@ -80,7 +80,6 @@ function buildScreenValidationContext(feature, featureMap, allWriteHandlerQns, a
80
80
  function validateListEmptyStateAction(ctx, screenId, screen) {
81
81
  if ((screen.type === "entityList" || screen.type === "projectionList") &&
82
82
  screen.emptyState?.action !== undefined) {
83
- validateActionHasIcon(ctx.feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action);
84
83
  validateListActionTargets(listActionContext(ctx, screenId, screen.type, undefined, `Screen "${screenId}" (${screen.type})`), "emptyState action", screen.emptyState.action);
85
84
  }
86
85
  }
@@ -44,6 +44,7 @@ export function bridgeStub(opts) {
44
44
  tryAppend: notAvailable("events.tryAppend"),
45
45
  fetchForWriting: notAvailable("events.fetchForWriting"),
46
46
  load: notAvailable("events.load"),
47
+ loadByTypes: notAvailable("events.loadByTypes"),
47
48
  archive: notAvailable("events.archive"),
48
49
  restore: notAvailable("events.restore"),
49
50
  isArchived: notAvailable("events.isArchived"),
@@ -681,7 +681,29 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
681
681
  if (k.def.required === true)
682
682
  requiredFields.push(id);
683
683
  }
684
- const { section, screenDescription } = buildSettingsSection(feature, scope, keys.map((k) => k.def.mask?.readOnly === true ? { field: fieldId(k), readOnly: true } : fieldId(k)), hub, options);
684
+ const specOf = (k) => k.def.mask?.readOnly === true ? { field: fieldId(k), readOnly: true } : fieldId(k);
685
+ const plainKeys = keys.filter((k) => k.def.mask?.section === undefined);
686
+ const { section, screenDescription } = buildSettingsSection(feature, scope, plainKeys.map(specOf), hub, options);
687
+ const sectionTitles = [
688
+ ...new Set(keys.flatMap((k) => (k.def.mask?.section === undefined ? [] : [k.def.mask.section]))),
689
+ ];
690
+ const titledSections = sectionTitles.map((title) => ({
691
+ title,
692
+ fields: keys.filter((k) => k.def.mask?.section === title).map(specOf),
693
+ }));
694
+ // Every key sectioned: the base section is gone, its description moves to the first generated one.
695
+ const [firstTitled, ...otherTitled] = titledSections;
696
+ const sections = plainKeys.length > 0
697
+ ? [section, ...titledSections]
698
+ : firstTitled === undefined
699
+ ? []
700
+ : [
701
+ {
702
+ ...firstTitled,
703
+ ...(section.description !== undefined && { description: section.description }),
704
+ },
705
+ ...otherTitled,
706
+ ];
685
707
  return {
686
708
  id: shortId,
687
709
  type: "configEdit",
@@ -689,10 +711,11 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
689
711
  configKeys,
690
712
  fields,
691
713
  fieldLabels,
714
+ ...(keys.some((k) => k.def.mask?.compact === true) && { compact: true }),
692
715
  ...(Object.keys(fieldDescriptions).length > 0 && { fieldDescriptions }),
693
716
  ...(requiredFields.length > 0 && { requiredFields }),
694
717
  ...(screenDescription !== undefined && { description: screenDescription }),
695
- layout: { sections: [section], width: "full", variant: "settings-list" },
718
+ layout: { sections, width: "full", variant: "settings-list" },
696
719
  access,
697
720
  };
698
721
  }
@@ -32,11 +32,15 @@ export function resolveNavParentScreen(screens, detail, getId) {
32
32
  ? screens.find((s) => screenShortId(getId(s)) === screenShortId(explicitId))
33
33
  : undefined;
34
34
  })();
35
- // rowActions, toolbarActions, and drawer-kind actions (which mount inline
36
- // and have no page of their own) all count as "reached from" this list.
35
+ // rowActions, toolbarActions, the `actions` of a record screen, and drawer-kind actions (which
36
+ // mount inline and have no page of their own) all count as "reached from" that screen.
37
37
  const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") &&
38
38
  a.screen !== undefined &&
39
39
  screenShortId(a.screen) === detailScreenId);
40
+ // A form opened only from a record screen (e.g. a status dialog) has that record as its parent.
41
+ const recordFromAction = screens.find((s) => (s.type === "projectionDetail" || s.type === "entityEdit") &&
42
+ screenShortId(getId(s)) !== detailScreenId &&
43
+ navigatesToDetail(s.actions));
40
44
  // The create button of an entityList navigates to its createScreen, so the
41
45
  // list is that screen's parent just like for a rowAction target.
42
46
  const listFromRowAction = screens.find((s) => {
@@ -51,7 +55,7 @@ export function resolveNavParentScreen(screens, detail, getId) {
51
55
  const listFromEntity = detail.type === "entityEdit"
52
56
  ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
53
57
  : undefined;
54
- return listFromExplicit ?? listFromRowAction ?? listFromEntity;
58
+ return listFromExplicit ?? listFromRowAction ?? recordFromAction ?? listFromEntity;
55
59
  }
56
60
  // Shared by boot-validators that walk the EditLayout shape (entityEdit's
57
61
  // layout, reused verbatim by projectionDetail/actionForm/configEdit/secretMint).
@@ -11,4 +11,5 @@ export type ArchiveStreamArgs = {
11
11
  };
12
12
  export declare function archiveStream(db: DbRunner, args: ArchiveStreamArgs): Promise<void>;
13
13
  export declare function isStreamArchived(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<boolean>;
14
+ export declare function selectArchivedAggregateIds(db: DbRunner, tenantId: TenantId, aggregateIds: readonly string[]): Promise<ReadonlySet<string>>;
14
15
  export declare function restoreStream(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<void>;
@@ -1,6 +1,6 @@
1
1
  // sql now comes from native dialect
2
2
  import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/dialect.js";
3
- import { upsertArchivedStream } from "../db/queries/event-store.js";
3
+ import { selectArchivedAggregateIdsOf, upsertArchivedStream } from "../db/queries/event-store.js";
4
4
  import { deleteMany, fetchOne } from "../db/query.js";
5
5
  import { tableExists } from "../db/schema-inspection.js";
6
6
  import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
@@ -48,6 +48,10 @@ export async function isStreamArchived(db, tenantId, aggregateId) {
48
48
  const row = await fetchOne(db, archivedStreamsTable, { tenantId, aggregateId });
49
49
  return row !== undefined;
50
50
  }
51
+ // One query for a whole page of aggregates instead of one isStreamArchived probe each.
52
+ export async function selectArchivedAggregateIds(db, tenantId, aggregateIds) {
53
+ return new Set(await selectArchivedAggregateIdsOf(db, tenantId, aggregateIds));
54
+ }
51
55
  // Undo an archive — restores the stream to writable state. Ops tool. The
52
56
  // historical archivedAt is lost; if auditing needs the archive-history,
53
57
  // use domain events on the aggregate (e.g. "stream.archived" / "stream.
@@ -21,6 +21,11 @@ export declare function loadAggregate(db: DbRunner, aggregateId: string, tenantI
21
21
  readonly aggregateType?: string;
22
22
  readonly atVersion?: number;
23
23
  }): Promise<readonly StoredEvent[]>;
24
+ export declare function loadEventsOfAggregatesByType(db: DbRunner, tenantId: TenantId, args: {
25
+ readonly aggregateIds: readonly string[];
26
+ readonly eventTypes: readonly string[];
27
+ readonly includeArchived?: boolean;
28
+ }): Promise<readonly StoredEvent[]>;
24
29
  export declare function loadAggregateForWriting(db: DbRunner, aggregateId: string, tenantId: TenantId, options: {
25
30
  readonly aggregateType: string;
26
31
  }): Promise<{
@@ -5,9 +5,10 @@ import { requestContext } from "../api/request-context.js";
5
5
  import { encryptEventPayloadPii } from "../crypto/event-pii.js";
6
6
  import { instantToTimestamptzParam } from "../db/driver-value-preparation.js";
7
7
  import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
8
- import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
9
- import { selectMany } from "../db/query.js";
10
- import { isStreamArchived } from "./archive.js";
8
+ import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventRowsOfAggregatesByType, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
9
+ import { coerceRow, selectMany } from "../db/query.js";
10
+ import { extractTableInfo } from "../db/table-info.js";
11
+ import { isStreamArchived, selectArchivedAggregateIds } from "./archive.js";
11
12
  import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
12
13
  import { eventsTable } from "./events-schema.js";
13
14
  import { toStoredEvent } from "./row-to-stored-event.js";
@@ -224,6 +225,25 @@ export async function loadAggregate(db, aggregateId, tenantId, options) {
224
225
  return rows.map(toStoredEvent);
225
226
  });
226
227
  }
228
+ // Events of several aggregates filtered by event type in one query, so a list page does not
229
+ // load every stream (N+1). Ordered by the global id: within one aggregate that is version order.
230
+ // Archived streams are left out unless includeArchived, as in loadAggregate.
231
+ export async function loadEventsOfAggregatesByType(db, tenantId, args) {
232
+ const { aggregateIds, eventTypes, includeArchived } = args;
233
+ if (aggregateIds.length === 0 || eventTypes.length === 0)
234
+ return [];
235
+ return inEventStreamScope(tenantId, async () => {
236
+ const archivedIds = includeArchived
237
+ ? new Set()
238
+ : await selectArchivedAggregateIds(db, tenantId, aggregateIds);
239
+ const rawRows = await selectEventRowsOfAggregatesByType(db, tenantId, aggregateIds, eventTypes);
240
+ const info = extractTableInfo(eventsTable);
241
+ return rawRows
242
+ .map((raw) => coerceRow(raw, info))
243
+ .filter((row) => !archivedIds.has(row.aggregateId))
244
+ .map(toStoredEvent);
245
+ });
246
+ }
227
247
  // Events and the stream's latest version from ONE read, so both come from the same
228
248
  // snapshot: a commit landing between two separate statements would leave the caller
229
249
  // pinning a version its loaded events never covered. The aggregateType filter is applied
@@ -415,6 +415,12 @@ function pushWriteFormSectionKeys(ctx, section) {
415
415
  function collectProjectionDetailKeys(ctx, detail) {
416
416
  for (const metric of detail.metrics ?? [])
417
417
  pushKey(ctx.out, metric.label);
418
+ pushKey(ctx.out, detail.header?.narrowTitle);
419
+ for (const section of detail.layout.sections) {
420
+ pushKey(ctx.out, section.tabLabel);
421
+ if ("descriptionNarrow" in section)
422
+ pushKey(ctx.out, section.descriptionNarrow);
423
+ }
418
424
  pushDetailGuidanceKeys(detail, (value) => pushKey(ctx.out, value), (action) => pushRowActionKeys(ctx.out, action));
419
425
  for (const section of detail.layout.sections) {
420
426
  if (isExtensionEditSection(section)) {
@@ -3,7 +3,7 @@ import { InternalError, VersionConflictError } from "../errors/index.js";
3
3
  import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
4
4
  import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
5
5
  import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
6
- import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
6
+ import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, loadEventsOfAggregatesByType, } from "../event-store/event-store.js";
7
7
  import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
8
8
  import { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
9
9
  import { appendDomainEventCore } from "./append-event-core.js";
@@ -120,6 +120,19 @@ export async function loadUpcastedAggregate(source, aggregateId, loadOptions) {
120
120
  });
121
121
  return upcastStoredEvents(events, registry.getEventUpcasters(), makeUpcastCtx(db, tenantId));
122
122
  }
123
+ /** Upcasters keep the event type, so the SQL type filter stays valid after upcasting. */
124
+ async function loadUpcastedEventsByTypes(source, args) {
125
+ const { db, registry, tenantId } = source;
126
+ const events = await loadEventsOfAggregatesByType(db, tenantId, args);
127
+ return upcastStoredEvents(events, registry.getEventUpcasters(), makeUpcastCtx(db, tenantId));
128
+ }
129
+ function buildLoadByTypes(scope) {
130
+ const { ctx, user, tx, registry } = scope;
131
+ return (args) => {
132
+ const db = requireDbSource(ctx, tx, "ctx.events.loadByTypes");
133
+ return loadUpcastedEventsByTypes({ db, registry, tenantId: user.tenantId }, args);
134
+ };
135
+ }
123
136
  function buildLoadAggregate(scope) {
124
137
  const { ctx, user, tx, registry } = scope;
125
138
  return (aggregateId, loadOptions) => {
@@ -174,6 +187,7 @@ export function buildEventStoreFacet(scope) {
174
187
  tryAppend: buildTryAppendEvent(scope),
175
188
  fetchForWriting: buildFetchForWriting(scope),
176
189
  load: buildLoadAggregate(scope),
190
+ loadByTypes: buildLoadByTypes(scope),
177
191
  archive: async (aggregateId, archiveArgs) => {
178
192
  const dbSource = requireDbSource(ctx, tx, `ctx.events.archive("${aggregateId}")`);
179
193
  await archiveStreamHelper(dbSource, {
@@ -6,11 +6,14 @@ export type CardRoleColumn = {
6
6
  readonly renderer?: unknown;
7
7
  readonly hideOnNarrow?: boolean;
8
8
  readonly narrowInline?: boolean;
9
+ readonly cardBadge?: boolean;
9
10
  readonly fileDisplay?: {
10
11
  readonly kind: string;
11
12
  };
12
13
  /** A "to do" hint column: never the default card title. */
13
14
  readonly hint?: unknown;
15
+ /** Leads the card like a hint column; covers computed columns, which need a renderer and so cannot take `hint`. */
16
+ readonly emphasis?: boolean;
14
17
  };
15
18
  export type CardColumnRoles<C extends CardRoleColumn> = {
16
19
  readonly image: C | undefined;
@@ -22,11 +22,15 @@ export function cardColumnRoles(columns) {
22
22
  const image = columns.find((col) => isImage(col) && col.hideOnNarrow !== true);
23
23
  // A narrow-hidden image must not turn into the title just because it is not the preview.
24
24
  const textColumns = columns.filter((col) => col !== image && !(isImage(col) && col.hideOnNarrow === true));
25
- const title = textColumns.find((col) => col.highlighted === true) ??
26
- textColumns.find((col) => col.hint === undefined) ??
27
- textColumns[0];
28
- const status = textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
29
- const lead = textColumns.find((col) => col !== title && col !== status && col.hint !== undefined && col.hideOnNarrow !== true);
25
+ // A column the phone hides cannot be the card title.
26
+ const titleCandidates = textColumns.filter((col) => col.hideOnNarrow !== true);
27
+ const isLeadCandidate = (col) => col.hint !== undefined || col.emphasis === true;
28
+ const title = titleCandidates.find((col) => col.highlighted === true) ??
29
+ titleCandidates.find((col) => !isLeadCandidate(col)) ??
30
+ titleCandidates[0];
31
+ const status = textColumns.find((col) => col !== title && col.cardBadge === true && col.hideOnNarrow !== true) ??
32
+ textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
33
+ const lead = textColumns.find((col) => col !== title && col !== status && isLeadCandidate(col) && col.hideOnNarrow !== true);
30
34
  const meta = textColumns.filter((col) => col !== title && col !== status && col !== lead && col.hideOnNarrow !== true);
31
35
  return { image, lead, title, status, meta };
32
36
  }
@@ -11,7 +11,7 @@ export type { EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, Options
11
11
  export type { AccessRule } from "../engine/types/handlers.ts";
12
12
  export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
13
13
  export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
14
- export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardLayout, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelColumn, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditStepListSection, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldAiAssist, FieldAiAssistChip, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FieldTextRef, FieldValueChips, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, ListToolbarActionsPlacement, MetricNavigate, PlatformComponent, ProjectionDetailInitialTab, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, StepListItem, ToolbarAction, } from "../engine/types/screen.ts";
14
+ export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardLayout, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelColumn, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditStepListSection, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldAiAssist, FieldAiAssistChip, FieldBadge, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FieldTextRef, FieldValueChips, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, ListToolbarActionsPlacement, MetricNavigate, PlatformComponent, ProjectionDetailInitialTab, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, StepListItem, ToolbarAction, } from "../engine/types/screen.ts";
15
15
  export { MAX_BULK_SELECTION } from "../engine/types/screen.ts";
16
16
  export type { TargetRef } from "../engine/types/target-ref.ts";
17
17
  export type { TreeAction } from "../engine/types/tree-node.ts";