@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
@@ -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: {
@@ -6,7 +6,7 @@ import { detailGuidanceFieldRefs, listGuidanceFieldRefs } from "./query-output-g
6
6
  import { QUERY_RULES } from "./query-rules.js";
7
7
  import { validateActionFieldRefs } from "./screens.js";
8
8
  import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
9
- import { getZodObjectShape, getZodRowShape } from "./zod-shape.js";
9
+ import { getZodArrayFieldElementShape, getZodObjectShape, getZodRowShape } from "./zod-shape.js";
10
10
  function checkFieldExists(shape, field, buildMessage) {
11
11
  // skip: capability absent (no introspectable shape) or field already present — nothing to validate
12
12
  if (shape === undefined || field in shape)
@@ -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.`);
@@ -295,8 +299,10 @@ function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen)
295
299
  screen.type === "configEdit" ||
296
300
  screen.type === "secretMint") {
297
301
  checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
298
- if (screen.type === "actionForm")
302
+ if (screen.type === "actionForm") {
299
303
  checkSummaryLoadFields(queryHandlers, featureName, screenId, screen);
304
+ checkPreviewOutputFields(queryHandlers, featureName, screenId, screen);
305
+ }
300
306
  }
301
307
  else if (screen.type === "dashboard") {
302
308
  checkDashboardOutputFields(queryHandlers, featureName, screenId, screen);
@@ -309,6 +315,27 @@ function checkSummaryLoadFields(queryHandlers, featureName, screenId, screen) {
309
315
  checkFieldExists(shape, field, () => `[Feature ${featureName}] Screen "${screenId}" (actionForm) summary.paramsFromLoad references field "${field}" which is not present in load query "${screen.load?.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
310
316
  }
311
317
  }
318
+ // preview facts and list read the preview query's result, so each name must be an output field of it.
319
+ function checkPreviewOutputFields(queryHandlers, featureName, screenId, screen) {
320
+ const { preview } = screen;
321
+ // skip: no preview declared
322
+ if (preview === undefined)
323
+ return;
324
+ const outputSchema = queryHandlers.get(preview.query)?.outputSchema;
325
+ const shape = getZodObjectShape(outputSchema);
326
+ const missing = (what, field) => `[Feature ${featureName}] Screen "${screenId}" (actionForm) preview ${what} "${field}" is not present in query "${preview.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`;
327
+ for (const fact of preview.facts ?? []) {
328
+ checkFieldExists(shape, fact.field, () => missing("fact", fact.field));
329
+ }
330
+ if (preview.list === undefined)
331
+ return;
332
+ const listField = preview.list.field;
333
+ checkFieldExists(shape, listField, () => missing("list field", listField));
334
+ const rowShape = getZodArrayFieldElementShape(outputSchema, listField);
335
+ for (const column of preview.list.columns) {
336
+ checkFieldExists(rowShape, column.field, () => missing("list column", column.field));
337
+ }
338
+ }
312
339
  export function validateQueryOutputColumns(features) {
313
340
  const queryHandlers = buildQueryHandlerMap(features);
314
341
  checkPagedHandlerOutputSchemaShape(queryHandlers);
@@ -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 },
@@ -119,6 +119,9 @@ function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, scre
119
119
  });
120
120
  }
121
121
  }
122
+ if (screen.type === "actionForm" && screen.preview !== undefined) {
123
+ checkQueryRef(queryHandlers, screen.preview.query, () => `[Feature ${featureName}] Screen "${screenId}" (actionForm) preview`);
124
+ }
122
125
  if (screen.type !== "entityEdit") {
123
126
  checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.fields);
124
127
  }
@@ -1,6 +1,6 @@
1
1
  import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
2
2
  import type { FeatureDefinition } from "../types/index.ts";
3
- import type { ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessLink, ProjectionDetailScreenDefinition, RelatedListToolbarAction, RowAction, RowActionNavigateBase, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
3
+ import type { ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessLink, EditLayout, ProjectionDetailScreenDefinition, RelatedListToolbarAction, RowAction, RowActionNavigateBase, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
4
4
  export declare function isRowClickAction(action: RowAction): boolean;
5
5
  export declare function validateAtMostOneRowClick(featureName: string, screenId: string, screenType: "entityList" | "projectionList", rowActions: readonly RowAction[]): void;
6
6
  export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
@@ -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<{
@@ -26,6 +26,7 @@ export declare function validateDrawerTargetAction(featureName: string, screenId
26
26
  readonly screen: string;
27
27
  readonly params?: RowFieldExtractor;
28
28
  }, screens: FeatureDefinition["screens"]): void;
29
+ export declare function renderedEditFieldNames(sections: EditLayout["sections"]): ReadonlySet<string>;
29
30
  export declare function isSensitiveOrPasswordField(field: object | undefined): boolean;
30
31
  export declare function validateDrawerPrefillKeys(where: string, targetLabel: "drawer-target" | "navigate-target", targetScreenId: string, target: ActionFormScreenDefinition | SecretMintScreenDefinition, params: RowFieldExtractor): void;
31
32
  type RowActionNavigateRuntime = RowActionNavigateBase & {
@@ -43,6 +44,10 @@ export declare function resolveRowActionNavigateTarget(featureName: string, scre
43
44
  readonly screen: ScreenDefinition;
44
45
  } | undefined;
45
46
  export declare function validateRedirectTarget(feature: FeatureDefinition, screenId: string, screenKind: "actionForm" | "secretMint" | "entityEdit" | "projectionDetail", redirect: string | ActionFormRedirect, lookups: NavigateTargetLookups, propertyPath?: string): void;
47
+ export declare function findNavTargetEntry(feature: Pick<FeatureDefinition, "name">, target: string, lookups: NavigateTargetLookups): {
48
+ readonly featureName: string;
49
+ readonly screen: ScreenDefinition;
50
+ } | undefined;
46
51
  export declare function validateIdlessSuccessLink(feature: FeatureDefinition, screenId: string, screenKind: "actionForm", link: ActionFormSuccessLink, lookups: NavigateTargetLookups, propertyPath: string): void;
47
52
  export declare function validateClientActionName(featureName: string, screenId: string, screenKind: string, actionLabel: "rowAction" | "emptyState action" | "action", action: Extract<RowAction, {
48
53
  readonly kind: "clientAction";
@@ -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, {
@@ -261,7 +263,7 @@ export function validateDrawerTargetAction(featureName, screenId, screenKind, ac
261
263
  return;
262
264
  validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}"`, "drawer-target", action.screen, target, action.params);
263
265
  }
264
- function renderedEditFieldNames(sections) {
266
+ export function renderedEditFieldNames(sections) {
265
267
  const names = new Set();
266
268
  for (const section of sections) {
267
269
  if (!isFieldsEditSection(section))
@@ -461,7 +463,7 @@ function validateRedirectSearchParams(featureName, screenId, screenKind, propert
461
463
  }
462
464
  }
463
465
  }
464
- function findNavTargetEntry(feature, target, lookups) {
466
+ export function findNavTargetEntry(feature, target, lookups) {
465
467
  const targetQn = resolveScreenTargetQn(feature.name, target);
466
468
  return lookups.screensByShortId
467
469
  .get(targetQn.slice(targetQn.lastIndexOf(":") + 1))
@@ -1,6 +1,7 @@
1
1
  import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isKebabSegment } from "../qualified-name.js";
3
3
  import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
4
+ import { validateActionFormPreview } from "./action-form-preview.js";
4
5
  import { bootRuleError } from "./boot-rule.js";
5
6
  import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
6
7
  import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
@@ -749,6 +750,7 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
749
750
  validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap, fieldNames);
750
751
  if (screen.type === "actionForm") {
751
752
  validateActionFormFieldTexts(feature.name, screenId, screen, fieldNames);
753
+ validateActionFormPreview(feature.name, screenId, screen, fieldNames);
752
754
  validateFormDerivations(feature.name, screenId, screen);
753
755
  validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
754
756
  }
@@ -56,7 +56,7 @@ function validateEntityListColumns(ctx, screenId, screen, fields, decoration) {
56
56
  message: buildUnknownFieldMessage(featureName, screenId, normalized.field, screen.entity, fields.columnFieldNames),
57
57
  });
58
58
  }
59
- validateListColumnRendering(ctx, screenId, "entityList", normalized);
59
+ validateListColumnRendering(ctx, screenId, "entityList", normalized, fields.entityDef);
60
60
  }
61
61
  }
62
62
  function validateEntityListDefaultSort(featureName, screenId, defaultSort, fields) {
@@ -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);
@@ -259,7 +261,7 @@ export function validateEntityListScreen(ctx, screenId, screen) {
259
261
  }
260
262
  validateAtMostOneRowClick(featureName, screenId, "entityList", screen.rowActions);
261
263
  }
262
- validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (entityList)`, screen.bulkActions, screen.rowActions);
264
+ validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (entityList)`, screen.bulkActions, screen.rowActions, featureName, ctx);
263
265
  for (const action of screen.toolbarActions ?? []) {
264
266
  validateEntityListToolbarAction(ctx, screenId, fields, action);
265
267
  }
@@ -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
@@ -55,7 +55,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
55
55
  if (screen.rowActions !== undefined) {
56
56
  validateProjectionListRowActions(ctx, screenId, screen.rowActions);
57
57
  }
58
- validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.bulkActions, screen.rowActions);
58
+ validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.bulkActions, screen.rowActions, featureName, ctx);
59
59
  if (screen.toolbarActions !== undefined) {
60
60
  validateProjectionListToolbarActions(ctx, screenId, screen.toolbarActions);
61
61
  }
@@ -18,7 +18,7 @@ export declare function listActionContext(ctx: ScreenValidationContext, screenId
18
18
  export declare function resolveScreenEntity(ctx: ScreenValidationContext, screenId: string, entityName: string): EntityDefinition;
19
19
  export declare function rejectMissingQuery(featureName: string, screenId: string, kind: "projectionList" | "projectionDetail", query: unknown): void;
20
20
  export declare function rejectEmptyColumns(featureName: string, screenId: string, kind: "projectionList" | "entityList", columnCount: number): void;
21
- export declare function validateListColumnRendering(ctx: ScreenValidationContext, screenId: string, kind: "projectionList" | "entityList", column: ReturnType<typeof normalizeListColumn>): void;
21
+ export declare function validateListColumnRendering(ctx: ScreenValidationContext, screenId: string, kind: "projectionList" | "entityList", column: ReturnType<typeof normalizeListColumn>, entity?: EntityDefinition): void;
22
22
  export declare function rejectNonArrayInFilter(featureName: string, screenId: string, kind: "projectionList" | "entityList", filter: {
23
23
  readonly op: string;
24
24
  readonly value?: unknown;
@@ -1,4 +1,5 @@
1
1
  import { bootRuleError } from "./boot-rule.js";
2
+ import { entityColumnType, validateDateOnlyAfterDays } from "./date-only-after-days.js";
2
3
  import { FORM_LAYOUT_RULES } from "./screens-forms-layout-rules.js";
3
4
  import { SCREEN_KIND_RULES } from "./screens-kind-rules.js";
4
5
  import { qualifyEntityName } from "../qualified-name.js";
@@ -66,9 +67,10 @@ export function rejectEmptyColumns(featureName, screenId, kind, columnCount) {
66
67
  });
67
68
  }
68
69
  }
69
- export function validateListColumnRendering(ctx, screenId, kind, column) {
70
+ export function validateListColumnRendering(ctx, screenId, kind, column, entity) {
70
71
  const featureName = ctx.feature.name;
71
72
  validateColumnRendererForm(featureName, screenId, column);
73
+ validateDateOnlyAfterDays(`[Feature ${featureName}] Screen "${screenId}" (${kind})`, column, entity === undefined ? undefined : entityColumnType(entity, column.field));
72
74
  rejectInertColumnSortable(featureName, screenId, kind, column);
73
75
  if (column.refEntity !== undefined) {
74
76
  assertRefTargetRegistered(`[Feature ${featureName}] Screen "${screenId}" (${kind})`, `column "${column.field}" (refEntity)`, column.refEntity, featureName, ctx.featureMap);
@@ -29,6 +29,16 @@ export declare const LIST_SCREEN_RULES: {
29
29
  readonly summary: "relatedList toolbarActions use visible instead of visibleWhen.";
30
30
  readonly fix: "Use visible, a condition on the enclosing record.";
31
31
  };
32
+ readonly dateOnlyAfterDaysInvalid: {
33
+ readonly id: "list/date-only-after-days-invalid";
34
+ readonly summary: "A column's dateOnlyAfterDays is a non-negative whole number of days.";
35
+ readonly fix: "Set dateOnlyAfterDays to 0 or a positive integer.";
36
+ };
37
+ readonly dateOnlyAfterDaysWrongType: {
38
+ readonly id: "list/date-only-after-days-wrong-type";
39
+ readonly summary: "dateOnlyAfterDays sits on a timestamp, locatedTimestamp or date column or a relativeTime column.";
40
+ readonly fix: "Remove dateOnlyAfterDays from the column or point it at a timestamp, locatedTimestamp or date field.";
41
+ };
32
42
  readonly columnSortableInert: {
33
43
  readonly id: "list/column-sortable-inert";
34
44
  readonly summary: "A column only sets sortable where the screen type honors it.";
@@ -29,6 +29,16 @@ export const LIST_SCREEN_RULES = {
29
29
  summary: "relatedList toolbarActions use visible instead of visibleWhen.",
30
30
  fix: "Use visible, a condition on the enclosing record.",
31
31
  },
32
+ dateOnlyAfterDaysInvalid: {
33
+ id: "list/date-only-after-days-invalid",
34
+ summary: "A column's dateOnlyAfterDays is a non-negative whole number of days.",
35
+ fix: "Set dateOnlyAfterDays to 0 or a positive integer.",
36
+ },
37
+ dateOnlyAfterDaysWrongType: {
38
+ id: "list/date-only-after-days-wrong-type",
39
+ summary: "dateOnlyAfterDays sits on a timestamp, locatedTimestamp or date column or a relativeTime column.",
40
+ fix: "Remove dateOnlyAfterDays from the column or point it at a timestamp, locatedTimestamp or date field.",
41
+ },
32
42
  columnSortableInert: {
33
43
  id: "list/column-sortable-inert",
34
44
  summary: "A column only sets sortable where the screen type honors it.",
@@ -5,6 +5,7 @@ import { parseRefTarget } from "../parse-ref-target.js";
5
5
  import { qualifyEntityName } from "../qualified-name.js";
6
6
  import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, screenShortId, } from "../screen-helpers.js";
7
7
  import { bootRuleError } from "./boot-rule.js";
8
+ import { entityColumnType, validateDateOnlyAfterDays } from "./date-only-after-days.js";
8
9
  import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
9
10
  import { validateListBulkActions } from "./list-bulk-actions.js";
10
11
  import { validateListRowGuidance, validatePhotoGrid } from "./list-row-guidance.js";
@@ -99,7 +100,7 @@ function validateRelatedListTableAndBulk(args) {
99
100
  validateListTableOptions(`[Feature ${featureName}] ${where}`, section.table, section.columns);
100
101
  if (section.rowActions !== undefined)
101
102
  validateRelatedListRowActions(args, section.rowActions);
102
- validateListBulkActions(`[Feature ${featureName}] ${where}`, section.bulkActions, section.rowActions);
103
+ validateListBulkActions(`[Feature ${featureName}] ${where}`, section.bulkActions, section.rowActions, featureName, args);
103
104
  }
104
105
  function assertReadOnlyHasNoRowInteraction(args) {
105
106
  const { section } = args;
@@ -110,6 +111,13 @@ function assertReadOnlyHasNoRowInteraction(args) {
110
111
  });
111
112
  }
112
113
  }
114
+ function resolveSectionEntity(args) {
115
+ const { section, featureName, featureMap } = args;
116
+ if (section.entity === undefined)
117
+ return undefined;
118
+ const target = parseRefTarget(section.entity, featureName);
119
+ return featureMap.get(target.featureName)?.entities?.[target.entityName];
120
+ }
113
121
  export function validateRelatedListSection(args) {
114
122
  const { featureName, featureMap, where, section } = args;
115
123
  if (!section.query || typeof section.query !== "string") {
@@ -122,10 +130,14 @@ export function validateRelatedListSection(args) {
122
130
  assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, "entity", section.entity, featureName, featureMap);
123
131
  }
124
132
  validateListRowGuidance(featureName, args.screenId, "relatedList", section, undefined, where);
133
+ const sectionEntity = resolveSectionEntity(args);
125
134
  for (const col of section.columns) {
126
135
  const normalizedCol = normalizeListColumn(col);
127
136
  validateColumnRendererForm(featureName, args.screenId, normalizedCol);
128
137
  validateEnumOptionTones(`[Feature ${featureName}] ${where}`, normalizedCol);
138
+ validateDateOnlyAfterDays(`[Feature ${featureName}] ${where}`, normalizedCol, sectionEntity === undefined
139
+ ? undefined
140
+ : entityColumnType(sectionEntity, normalizedCol.field));
129
141
  if (normalizedCol.refEntity !== undefined) {
130
142
  assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, `column "${normalizedCol.field}" (refEntity)`, normalizedCol.refEntity, featureName, featureMap);
131
143
  }
@@ -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
  }
@@ -1,4 +1,4 @@
1
- import { qualifyEntityName } from "../qualified-name.js";
1
+ import { isValidQn, parseQn, qualifyEntityName } from "../qualified-name.js";
2
2
  import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { collectScreensByShortId, readsNavigateParamsAsFormPrefill, rowFieldExtractorKeys, validateDrawerPrefillKeys, } from "./screens.js";
@@ -131,6 +131,13 @@ function resolveTarget(source, screensByShortId, detailForByEntity) {
131
131
  return detailForByEntity.get(source.entity);
132
132
  if (source.screen === undefined)
133
133
  return undefined;
134
+ if (isValidQn(source.screen)) {
135
+ const { scope, type, name } = parseQn(source.screen);
136
+ if (type !== "screen")
137
+ return undefined;
138
+ const match = screensByShortId.get(name)?.find((entry) => entry.featureName === scope);
139
+ return match === undefined ? undefined : { ...match, shortId: name };
140
+ }
134
141
  const match = screensByShortId.get(source.screen)?.[0];
135
142
  return match === undefined ? undefined : { ...match, shortId: source.screen };
136
143
  }
@@ -4,3 +4,4 @@ export declare function getZodStringLiterals(schema: ZodType | undefined): reado
4
4
  export declare function getZodObjectShape(schema: ZodType | undefined): Record<string, ZodType> | undefined;
5
5
  export declare function getZodRowShape(schema: ZodType | undefined): Record<string, ZodType> | undefined;
6
6
  export declare function collectZodObjectKeys(schema: $ZodType | undefined): ReadonlySet<string>;
7
+ export declare function getZodArrayFieldElementShape(schema: ZodType | undefined, field: string): Record<string, ZodType> | undefined;
@@ -1,3 +1,4 @@
1
+ import * as z from "zod";
1
2
  import { ZodArray, ZodCatch, ZodDefault, ZodEnum, ZodIntersection, ZodLazy, ZodLiteral, ZodMap, ZodNever, ZodNonOptional, ZodNullable, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPromise, ZodReadonly, ZodRecord, ZodSet, ZodTuple, ZodType, ZodUnion, ZodXor, } from "zod";
2
3
  import { bootRuleError } from "./boot-rule.js";
3
4
  import { HANDLER_FIELD_REFERENCE_RULES } from "./handler-field-references-rules.js";
@@ -145,3 +146,9 @@ export function collectZodObjectKeys(schema) {
145
146
  }
146
147
  return keys;
147
148
  }
149
+ // The element shape of an array field of an object schema, e.g. `tasks` in `{ count, tasks: T[] }`.
150
+ // Reuses the `{ rows: T[] }` walk instead of reading `.element` (core-vs-wrapper type gap).
151
+ export function getZodArrayFieldElementShape(schema, field) {
152
+ const arrayField = getZodObjectShape(schema)?.[field];
153
+ return arrayField === undefined ? undefined : getZodRowShape(z.object({ rows: arrayField }));
154
+ }
@@ -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"),