@cosmicdrift/kumiko-framework 0.415.0 → 0.416.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/agents/api/framework-engine.md +37 -5
  2. package/agents/api/framework-ui-types.md +59 -3
  3. package/agents/api/renderer-web.md +7 -1
  4. package/agents/api/types.md +21 -2
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +33 -3
  7. package/agents/examples/embedded.md +24 -1
  8. package/agents/examples/handbook-knowledge.md +129 -0
  9. package/agents/examples/signature.md +186 -0
  10. package/agents/examples/writeform-section.md +1 -0
  11. package/agents/examples.md +2 -0
  12. package/agents/features-index.md +4 -0
  13. package/agents/features.md +14 -0
  14. package/dist/api/server-routes.js +2 -0
  15. package/dist/db/table-builder.js +3 -1
  16. package/dist/engine/boot-validator/boot-phases.js +5 -0
  17. package/dist/engine/boot-validator/boot-rules.d.ts +129 -4
  18. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  19. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  20. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  21. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  22. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  23. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  24. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  25. package/dist/engine/boot-validator/list-row-guidance.js +30 -0
  26. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  27. package/dist/engine/boot-validator/query-output-guidance.js +2 -0
  28. package/dist/engine/boot-validator/query-refs.js +4 -1
  29. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  30. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  31. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  33. package/dist/engine/boot-validator/screens-actions.js +55 -15
  34. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  35. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  36. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  37. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  38. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  39. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  40. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  41. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  42. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  43. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  44. package/dist/engine/boot-validator/screens-forms.js +108 -2
  45. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  46. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  47. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  48. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  49. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  50. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  51. package/dist/engine/boot-validator/screens-lists.js +4 -1
  52. package/dist/engine/build-config-feature-schema.js +5 -35
  53. package/dist/engine/config-access-rules.d.ts +3 -0
  54. package/dist/engine/config-access-rules.js +34 -0
  55. package/dist/engine/factories.d.ts +2 -0
  56. package/dist/engine/project-app-schema-for-roles.js +2 -0
  57. package/dist/files/file-routes.d.ts +2 -0
  58. package/dist/files/file-routes.js +85 -22
  59. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  60. package/dist/files/foreign-tenant-file-read.js +64 -0
  61. package/dist/i18n/required-surface-keys.js +26 -6
  62. package/dist/ui-types/index.d.ts +1 -1
  63. package/package.json +3 -3
  64. package/src/changes.json +42 -0
@@ -129,6 +129,16 @@ export const SCREEN_ACTION_RULES = {
129
129
  summary: "A redirect idFrom only targets entityEdit or projectionDetail screens.",
130
130
  fix: "Use the plain string redirect form.",
131
131
  },
132
+ redirectSearchParamsOnlyActionForm: {
133
+ id: "screen/redirect-search-params-only-action-form",
134
+ summary: "A redirect searchParams is only set on actionForm redirects.",
135
+ fix: "Remove searchParams; other screen kinds do not read it.",
136
+ },
137
+ redirectSearchParamsEmpty: {
138
+ id: "screen/redirect-search-params-empty",
139
+ summary: "A redirect searchParams entry has a non-empty param name and payload field.",
140
+ fix: "Map each search param name to a success-payload field.",
141
+ },
132
142
  successLinkTargetsRecordScreen: {
133
143
  id: "screen/success-link-targets-record-screen",
134
144
  summary: "A success link without idFrom does not target a record screen.",
@@ -146,9 +156,14 @@ export const SCREEN_ACTION_RULES = {
146
156
  },
147
157
  primaryActionUnknown: {
148
158
  id: "screen/primary-action-unknown",
149
- summary: "primaryAction and inlineActions name a declared action id or the default edit.",
159
+ summary: "primaryAction, inlineActions and footerActions name a declared action id or the default edit.",
150
160
  fix: 'Use a declared action id, or "edit" when the screen sets detailFor.',
151
161
  },
162
+ footerActionConflict: {
163
+ id: "screen/footer-action-conflict",
164
+ summary: "A footerActions id is neither the primaryAction nor in inlineActions.",
165
+ fix: "Keep each action in one place: header (primaryAction), inline row or pinned footer.",
166
+ },
152
167
  fallbackWithoutVisibleWhen: {
153
168
  id: "screen/fallback-without-visible-when",
154
169
  summary: "A screen with a fallback also declares visibleWhen.",
@@ -398,38 +398,67 @@ export function validateRedirectTarget(feature, screenId, screenKind, redirect,
398
398
  propertyPath = "redirect") {
399
399
  const { allScreenQns } = lookups;
400
400
  const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
401
- if (typeof redirect !== "string" &&
402
- (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")) {
401
+ if (typeof redirect !== "string") {
402
+ validateRedirectIdFromShape(feature.name, screenId, screenKind, propertyPath, redirect);
403
+ }
404
+ validateScreenNavTarget(feature.name, screenId, screenKind, propertyPath, redirectTarget, allScreenQns, feature.screens);
405
+ if (typeof redirect !== "string" && redirect.idFrom !== undefined) {
406
+ validateRedirectIdFromTarget(feature.name, screenId, screenKind, propertyPath, redirectTarget, feature.screens[redirectTarget]);
407
+ }
408
+ if (typeof redirect !== "string" && redirect.searchParams !== undefined) {
409
+ validateRedirectSearchParams(feature.name, screenId, screenKind, propertyPath, redirect.searchParams);
410
+ }
411
+ if (typeof redirect !== "string" && redirect.tab !== undefined) {
412
+ validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, findNavTargetEntry(feature, redirectTarget, lookups));
413
+ }
414
+ }
415
+ function validateRedirectIdFromShape(featureName, screenId, screenKind, propertyPath, redirect) {
416
+ const { idFrom } = redirect;
417
+ if (idFrom === undefined)
418
+ return;
419
+ if (typeof idFrom !== "string" || idFrom.trim() === "") {
403
420
  throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromEmpty, {
404
- message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is empty or not a string — ` +
421
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is empty or not a string — ` +
405
422
  `name the success-payload field carrying the navigation id, or use the plain string ` +
406
423
  `redirect form to navigate with the handler's own "id".`,
407
424
  });
408
425
  }
409
426
  // The renderer reads idFrom verbatim (Object.hasOwn), so stray whitespace
410
427
  // never matches and the navigation silently lands without an entityId.
411
- if (typeof redirect !== "string" && redirect.idFrom !== redirect.idFrom.trim()) {
428
+ if (idFrom !== idFrom.trim()) {
412
429
  throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromWhitespace, {
413
- message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom "${redirect.idFrom}" ` +
430
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom "${idFrom}" ` +
414
431
  `has leading/trailing whitespace — it would never match a payload field. Remove the whitespace from idFrom.`,
415
432
  });
416
433
  }
417
- validateScreenNavTarget(feature.name, screenId, screenKind, propertyPath, redirectTarget, allScreenQns, feature.screens);
418
- // idFrom only means something to a target that carries a record id; the
419
- // renderer drops it silently otherwise. Cross-feature QN targets can't be
420
- // typed from here and stay unchecked.
421
- const sameFeatureTarget = feature.screens[redirectTarget];
422
- if (typeof redirect !== "string" &&
423
- sameFeatureTarget !== undefined &&
434
+ }
435
+ // idFrom only means something to a target that carries a record id; the
436
+ // renderer drops it silently otherwise. Cross-feature QN targets can't be
437
+ // typed from here and stay unchecked.
438
+ function validateRedirectIdFromTarget(featureName, screenId, screenKind, propertyPath, redirectTarget, sameFeatureTarget) {
439
+ if (sameFeatureTarget !== undefined &&
424
440
  sameFeatureTarget.type !== "entityEdit" &&
425
441
  sameFeatureTarget.type !== "projectionDetail") {
426
442
  throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromOnIdlessTarget, {
427
- message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is set but target screen ` +
443
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is set but target screen ` +
428
444
  `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`,
429
445
  });
430
446
  }
431
- if (typeof redirect !== "string" && redirect.tab !== undefined) {
432
- validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, findNavTargetEntry(feature, redirectTarget, lookups));
447
+ }
448
+ function validateRedirectSearchParams(featureName, screenId, screenKind, propertyPath, searchParams) {
449
+ if (screenKind !== "actionForm") {
450
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectSearchParamsOnlyActionForm, {
451
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${propertyPath}.searchParams is only ` +
452
+ `read for actionForm redirects — remove it.`,
453
+ });
454
+ }
455
+ for (const [param, field] of Object.entries(searchParams)) {
456
+ if (param.trim() === "" || typeof field !== "string" || field.trim() === "") {
457
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectSearchParamsEmpty, {
458
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${propertyPath}.searchParams ` +
459
+ `entry "${param}" has an empty param name or payload field — map each search param name to a success-payload field.`,
460
+ });
461
+ }
433
462
  }
434
463
  }
435
464
  function findNavTargetEntry(feature, target, lookups) {
@@ -498,6 +527,15 @@ export function validateRecordActionRedirect(feature, screenId, screenKind, acti
498
527
  validateRedirectTarget(feature, screenId, screenKind, action.redirect, lookups);
499
528
  }
500
529
  }
530
+ function validateFooterActionsAreExclusive(featureName, screenId, screen) {
531
+ for (const id of screen.footerActions ?? []) {
532
+ if (id === screen.primaryAction || (screen.inlineActions ?? []).includes(id)) {
533
+ throw bootRuleError(SCREEN_ACTION_RULES.footerActionConflict, {
534
+ message: `[Feature ${featureName}] Screen "${screenId}" (projectionDetail) footerActions "${id}" is also the primaryAction or in inlineActions. Keep it in one place.`,
535
+ });
536
+ }
537
+ }
538
+ }
501
539
  // "edit" is the default edit action, which only exists when detailFor names
502
540
  // the entity; a typo would otherwise silently fall back to the default header layout.
503
541
  export function validatePrimaryActionTarget(featureName, screenId, screen) {
@@ -506,7 +544,9 @@ export function validatePrimaryActionTarget(featureName, screenId, screen) {
506
544
  ? [["primaryAction", screen.primaryAction]]
507
545
  : []),
508
546
  ...(screen.inlineActions ?? []).map((id) => ["inlineActions", id]),
547
+ ...(screen.footerActions ?? []).map((id) => ["footerActions", id]),
509
548
  ];
549
+ validateFooterActionsAreExclusive(featureName, screenId, screen);
510
550
  const declaredIds = (screen.actions ?? []).map((action) => action.id);
511
551
  const editIsAvailable = screen.detailFor !== undefined;
512
552
  for (const [option, id] of targets) {
@@ -1,4 +1,5 @@
1
- import type { DashboardListPanel, DashboardPanelDefinition } from "../types/screen.ts";
1
+ import type { DashboardListPanel, DashboardPanelDefinition, DashboardScreenDefinition } from "../types/screen.ts";
2
2
  /** The screen itself is checked by validateDashboardPanelLink; this covers the rest of the shape. */
3
3
  export declare function validateListRowLinkShape(context: string, panel: DashboardListPanel): void;
4
+ export declare function validateDashboardLayout(featureName: string, screenId: string, screen: DashboardScreenDefinition): void;
4
5
  export declare function validateDashboardPanelNarrow(featureName: string, screenId: string, panel: DashboardPanelDefinition): void;
@@ -112,15 +112,20 @@ function isTitledStrip(panel) {
112
112
  return panel.label !== undefined && panel.layout === "strip";
113
113
  }
114
114
  function validateStatGroupChildren(context, panel) {
115
+ if (panel.stats.length > 0 && panel.stats.every((stat) => stat.hideOnNarrow === true)) {
116
+ throw bootRuleError(DASHBOARD_RULES.statGroupChildHideOnNarrow, {
117
+ message: `${context} hides every child on narrow — set hideOnNarrow on the whole group instead.`,
118
+ });
119
+ }
115
120
  for (const stat of panel.stats) {
116
121
  if (stat.narrowLabel !== undefined && !isTitledStrip(panel)) {
117
122
  throw bootRuleError(DASHBOARD_RULES.statNarrowLabelOutsideGroup, {
118
123
  message: `${context} child "${stat.id}" sets narrowLabel, but only the one-line phone strip of a titled group with layout "strip" draws it. Give the group a label and layout "strip", or remove narrowLabel.`,
119
124
  });
120
125
  }
121
- if (stat.hideOnNarrow !== undefined) {
122
- throw bootRuleError(DASHBOARD_RULES.statGroupChildHideOnNarrow, {
123
- message: `${context} child "${stat.id}" sets hideOnNarrow — set it on the whole group instead; a hidden cell would leave a gap.`,
126
+ if (stat.column !== undefined) {
127
+ throw bootRuleError(DASHBOARD_RULES.layoutInvalid, {
128
+ message: `${context} child "${stat.id}" sets column — set it on the whole group instead.`,
124
129
  });
125
130
  }
126
131
  if (stat.narrowOrder !== undefined) {
@@ -195,14 +200,48 @@ function validateNarrowOrder(context, panel) {
195
200
  });
196
201
  }
197
202
  }
203
+ const PANEL_COLUMNS = ["side", "top"];
204
+ function validateListColumnVariants(context, panel) {
205
+ for (const spec of panel.columns) {
206
+ const column = normalizeListColumn(spec);
207
+ // skip: default outline look
208
+ if (column.variant === undefined)
209
+ continue;
210
+ if (column.variant !== "primary" || column.display !== "button") {
211
+ throw bootRuleError(DASHBOARD_RULES.listColumnVariantInvalid, {
212
+ message: `${context} column "${column.field}" sets variant "${String(column.variant)}", which must be "primary" and needs display: "button".`,
213
+ });
214
+ }
215
+ }
216
+ }
217
+ export function validateDashboardLayout(featureName, screenId, screen) {
218
+ const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard)`;
219
+ if (screen.layout !== undefined && screen.layout !== "main-side") {
220
+ throw bootRuleError(DASHBOARD_RULES.layoutInvalid, {
221
+ message: `${prefix} layout "${String(screen.layout)}" is not "main-side".`,
222
+ });
223
+ }
224
+ for (const panel of screen.panels) {
225
+ // skip: panel stays in the main column
226
+ if (panel.column === undefined)
227
+ continue;
228
+ if (screen.layout !== "main-side" || !PANEL_COLUMNS.includes(panel.column)) {
229
+ throw bootRuleError(DASHBOARD_RULES.layoutInvalid, {
230
+ message: `${prefix} panel "${panel.id}" sets column "${String(panel.column)}", which needs layout: "main-side" and the value "side" or "top".`,
231
+ });
232
+ }
233
+ }
234
+ }
198
235
  // Phone-layout options per panel kind; `hideOnNarrow` itself is a plain flag with no cross-field rule.
199
236
  export function validateDashboardPanelNarrow(featureName, screenId, panel) {
200
237
  const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard)`;
201
238
  validateNarrowOrder(`${prefix} panel "${panel.id}"`, panel);
202
239
  if (panel.kind === "stat")
203
240
  validateStatNarrowLabel(`${prefix} stat "${panel.id}"`, panel);
204
- if (panel.kind === "list")
241
+ if (panel.kind === "list") {
205
242
  validateListNarrow(`${prefix} list-panel "${panel.id}"`, panel);
243
+ validateListColumnVariants(`${prefix} list-panel "${panel.id}"`, panel);
244
+ }
206
245
  else if (panel.kind === "stat-group") {
207
246
  validateStatGroupNarrow(`${prefix} stat-group "${panel.id}"`, panel);
208
247
  }
@@ -184,10 +184,20 @@ export declare const DASHBOARD_RULES: {
184
184
  readonly summary: 'A stat-group\'s columns is 2, 3 or 4 and needs layout "cards".';
185
185
  readonly fix: 'Set columns to 2, 3 or 4 and give the group a label or layout: "cards", or remove columns.';
186
186
  };
187
+ readonly layoutInvalid: {
188
+ readonly id: "dashboard/layout-invalid";
189
+ readonly summary: 'A dashboard layout is "main-side"; a panel column is "side" or "top", used only with that layout and never on a stat-group child.';
190
+ readonly fix: 'Set layout: "main-side" on the dashboard to use column: "side" or "top", or remove column.';
191
+ };
192
+ readonly listColumnVariantInvalid: {
193
+ readonly id: "dashboard/list-column-variant-invalid";
194
+ readonly summary: 'A list column variant is "primary" and needs display: "button".';
195
+ readonly fix: 'Set display: "button" on the column or remove variant.';
196
+ };
187
197
  readonly statGroupChildHideOnNarrow: {
188
198
  readonly id: "dashboard/stat-group-child-hide-on-narrow";
189
- readonly summary: "Stat-group children do not set hideOnNarrow.";
190
- readonly fix: "Set hideOnNarrow on the whole group instead.";
199
+ readonly summary: "A stat-group keeps at least one child on a phone: not every child sets hideOnNarrow.";
200
+ readonly fix: "Set hideOnNarrow on the whole group instead, or keep one child visible.";
191
201
  };
192
202
  readonly listNarrowFieldUnknown: {
193
203
  readonly id: "dashboard/list-narrow-field-unknown";
@@ -184,10 +184,20 @@ export const DASHBOARD_RULES = {
184
184
  summary: 'A stat-group\'s columns is 2, 3 or 4 and needs layout "cards".',
185
185
  fix: 'Set columns to 2, 3 or 4 and give the group a label or layout: "cards", or remove columns.',
186
186
  },
187
+ layoutInvalid: {
188
+ id: "dashboard/layout-invalid",
189
+ summary: 'A dashboard layout is "main-side"; a panel column is "side" or "top", used only with that layout and never on a stat-group child.',
190
+ fix: 'Set layout: "main-side" on the dashboard to use column: "side" or "top", or remove column.',
191
+ },
192
+ listColumnVariantInvalid: {
193
+ id: "dashboard/list-column-variant-invalid",
194
+ summary: 'A list column variant is "primary" and needs display: "button".',
195
+ fix: 'Set display: "button" on the column or remove variant.',
196
+ },
187
197
  statGroupChildHideOnNarrow: {
188
198
  id: "dashboard/stat-group-child-hide-on-narrow",
189
- summary: "Stat-group children do not set hideOnNarrow.",
190
- fix: "Set hideOnNarrow on the whole group instead.",
199
+ summary: "A stat-group keeps at least one child on a phone: not every child sets hideOnNarrow.",
200
+ fix: "Set hideOnNarrow on the whole group instead, or keep one child visible.",
191
201
  },
192
202
  listNarrowFieldUnknown: {
193
203
  id: "dashboard/list-narrow-field-unknown",
@@ -5,7 +5,7 @@ import { validateListRowGuidance } from "./list-row-guidance.js";
5
5
  import { assertWriteHandlerRegistered, isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
6
6
  import { DASHBOARD_CHART_RULES } from "./screens-dashboard-chart-rules.js";
7
7
  import { validateDashboardPanelLink, validateListRowLinkTarget, } from "./screens-dashboard-links.js";
8
- import { validateDashboardPanelNarrow, validateListRowLinkShape, } from "./screens-dashboard-narrow.js";
8
+ import { validateDashboardLayout, validateDashboardPanelNarrow, validateListRowLinkShape, } from "./screens-dashboard-narrow.js";
9
9
  import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
10
10
  import { assertRefTargetRegistered, validateColumnRendererForm } from "./screens-lists.js";
11
11
  // Panel-driven, no entity — structural checks (unique panel ids, non-empty
@@ -18,6 +18,7 @@ export function validateDashboardScreen(featureName, screenId, screen, featureMa
18
18
  `declare at least one panel.`,
19
19
  });
20
20
  }
21
+ validateDashboardLayout(featureName, screenId, screen);
21
22
  const panelIds = new Set();
22
23
  const addPanelId = (id, context) => {
23
24
  if (panelIds.has(id)) {
@@ -89,6 +89,11 @@ export declare const FORM_LAYOUT_RULES: {
89
89
  readonly summary: "Inline form layouts have no relatedList sections.";
90
90
  readonly fix: "Move the section to a projectionDetail screen or remove it.";
91
91
  };
92
+ readonly stepListSectionUnsupported: {
93
+ readonly id: "form/step-list-section-unsupported";
94
+ readonly summary: "Inline form layouts have no stepList sections.";
95
+ readonly fix: "Move the section to a projectionDetail screen or remove it.";
96
+ };
92
97
  readonly writeFormSectionUnsupported: {
93
98
  readonly id: "form/write-form-section-unsupported";
94
99
  readonly summary: "Inline form layouts have no writeForm sections.";
@@ -89,6 +89,11 @@ export const FORM_LAYOUT_RULES = {
89
89
  summary: "Inline form layouts have no relatedList sections.",
90
90
  fix: "Move the section to a projectionDetail screen or remove it.",
91
91
  },
92
+ stepListSectionUnsupported: {
93
+ id: "form/step-list-section-unsupported",
94
+ summary: "Inline form layouts have no stepList sections.",
95
+ fix: "Move the section to a projectionDetail screen or remove it.",
96
+ },
92
97
  writeFormSectionUnsupported: {
93
98
  id: "form/write-form-section-unsupported",
94
99
  summary: "Inline form layouts have no writeForm sections.",
@@ -44,6 +44,66 @@ export declare const FORM_FIELD_RULES: {
44
44
  readonly summary: "fillAction does not target a sensitive, writeOnly or password field.";
45
45
  readonly fix: "Remove fillAction.";
46
46
  };
47
+ readonly fieldDescriptionUnknownField: {
48
+ readonly id: "form/field-description-unknown-field";
49
+ readonly summary: "actionForm fieldDescriptions keys name fields of the form.";
50
+ readonly fix: "Name a field of the form or remove the entry.";
51
+ };
52
+ readonly fieldTextParamUnknownField: {
53
+ readonly id: "form/field-text-param-unknown-field";
54
+ readonly summary: "actionForm fieldLabels and fieldDescriptions params name fields of the form.";
55
+ readonly fix: "Point each param at a field of the form or use the plain i18n key.";
56
+ };
57
+ readonly fieldBadgeUnknownField: {
58
+ readonly id: "form/field-badge-unknown-field";
59
+ readonly summary: "actionForm fieldBadges keys name fields of the form.";
60
+ readonly fix: "Name a field of the form or remove the entry.";
61
+ };
62
+ readonly aiAssistContextFieldUnknown: {
63
+ readonly id: "form/ai-assist-context-field-unknown";
64
+ readonly summary: "aiAssist.contextFields names fields of the same form.";
65
+ readonly fix: "Name other fields of the same form or remove the entry.";
66
+ };
67
+ readonly aiAssistFieldType: {
68
+ readonly id: "form/ai-assist-field-type";
69
+ readonly summary: "aiAssist targets a text or longText field.";
70
+ readonly fix: "Remove aiAssist or use a text or longText field.";
71
+ };
72
+ readonly aiAssistSensitiveField: {
73
+ readonly id: "form/ai-assist-sensitive-field";
74
+ readonly summary: "aiAssist does not target a sensitive, writeOnly or password field.";
75
+ readonly fix: "Remove aiAssist; the field text would be sent to the AI.";
76
+ };
77
+ readonly aiAssistChipInvalid: {
78
+ readonly id: "form/ai-assist-chip-invalid";
79
+ readonly summary: "An aiAssist chip has a label and at least one param.";
80
+ readonly fix: 'Set a non-empty label and params such as { style: "short" }.';
81
+ };
82
+ readonly aiAssistResultFieldEmpty: {
83
+ readonly id: "form/ai-assist-result-field-empty";
84
+ readonly summary: "aiAssist names a non-empty resultField.";
85
+ readonly fix: "Set resultField to the key of the query result that holds the text.";
86
+ };
87
+ readonly aiAssistPromptParamEmpty: {
88
+ readonly id: "form/ai-assist-prompt-param-empty";
89
+ readonly summary: "aiAssist.prompt names a non-empty param.";
90
+ readonly fix: "Set prompt.param to the query payload key that receives the typed instruction.";
91
+ };
92
+ readonly aiAssistEmpty: {
93
+ readonly id: "form/ai-assist-empty";
94
+ readonly summary: "aiAssist declares at least one chip or a prompt.";
95
+ readonly fix: "Add chips or prompt, or remove aiAssist.";
96
+ };
97
+ readonly valueChipsFieldType: {
98
+ readonly id: "form/value-chips-field-type";
99
+ readonly summary: "valueChips targets a number, decimal, bigInt or money field.";
100
+ readonly fix: "Remove valueChips or use a numeric or money field.";
101
+ };
102
+ readonly valueChipsUnknownField: {
103
+ readonly id: "form/value-chips-unknown-field";
104
+ readonly summary: "valueChips.from names a field of the same form.";
105
+ readonly fix: "Name a field of the same form (hidden and submit: false is fine) that holds the numbers.";
106
+ };
47
107
  readonly requiredFieldWithoutWidget: {
48
108
  readonly id: "form/required-field-without-widget";
49
109
  readonly summary: "A required entityEdit field has a widget to fill it.";
@@ -44,6 +44,66 @@ export const FORM_FIELD_RULES = {
44
44
  summary: "fillAction does not target a sensitive, writeOnly or password field.",
45
45
  fix: "Remove fillAction.",
46
46
  },
47
+ fieldDescriptionUnknownField: {
48
+ id: "form/field-description-unknown-field",
49
+ summary: "actionForm fieldDescriptions keys name fields of the form.",
50
+ fix: "Name a field of the form or remove the entry.",
51
+ },
52
+ fieldTextParamUnknownField: {
53
+ id: "form/field-text-param-unknown-field",
54
+ summary: "actionForm fieldLabels and fieldDescriptions params name fields of the form.",
55
+ fix: "Point each param at a field of the form or use the plain i18n key.",
56
+ },
57
+ fieldBadgeUnknownField: {
58
+ id: "form/field-badge-unknown-field",
59
+ summary: "actionForm fieldBadges keys name fields of the form.",
60
+ fix: "Name a field of the form or remove the entry.",
61
+ },
62
+ aiAssistContextFieldUnknown: {
63
+ id: "form/ai-assist-context-field-unknown",
64
+ summary: "aiAssist.contextFields names fields of the same form.",
65
+ fix: "Name other fields of the same form or remove the entry.",
66
+ },
67
+ aiAssistFieldType: {
68
+ id: "form/ai-assist-field-type",
69
+ summary: "aiAssist targets a text or longText field.",
70
+ fix: "Remove aiAssist or use a text or longText field.",
71
+ },
72
+ aiAssistSensitiveField: {
73
+ id: "form/ai-assist-sensitive-field",
74
+ summary: "aiAssist does not target a sensitive, writeOnly or password field.",
75
+ fix: "Remove aiAssist; the field text would be sent to the AI.",
76
+ },
77
+ aiAssistChipInvalid: {
78
+ id: "form/ai-assist-chip-invalid",
79
+ summary: "An aiAssist chip has a label and at least one param.",
80
+ fix: 'Set a non-empty label and params such as { style: "short" }.',
81
+ },
82
+ aiAssistResultFieldEmpty: {
83
+ id: "form/ai-assist-result-field-empty",
84
+ summary: "aiAssist names a non-empty resultField.",
85
+ fix: "Set resultField to the key of the query result that holds the text.",
86
+ },
87
+ aiAssistPromptParamEmpty: {
88
+ id: "form/ai-assist-prompt-param-empty",
89
+ summary: "aiAssist.prompt names a non-empty param.",
90
+ fix: "Set prompt.param to the query payload key that receives the typed instruction.",
91
+ },
92
+ aiAssistEmpty: {
93
+ id: "form/ai-assist-empty",
94
+ summary: "aiAssist declares at least one chip or a prompt.",
95
+ fix: "Add chips or prompt, or remove aiAssist.",
96
+ },
97
+ valueChipsFieldType: {
98
+ id: "form/value-chips-field-type",
99
+ summary: "valueChips targets a number, decimal, bigInt or money field.",
100
+ fix: "Remove valueChips or use a numeric or money field.",
101
+ },
102
+ valueChipsUnknownField: {
103
+ id: "form/value-chips-unknown-field",
104
+ summary: "valueChips.from names a field of the same form.",
105
+ fix: "Name a field of the same form (hidden and submit: false is fine) that holds the numbers.",
106
+ },
47
107
  requiredFieldWithoutWidget: {
48
108
  id: "form/required-field-without-widget",
49
109
  summary: "A required entityEdit field has a widget to fill it.",
@@ -9,7 +9,7 @@ export declare function validateFillActionTarget(where: string, fieldSpec: Exclu
9
9
  readonly type: string;
10
10
  } | undefined): void;
11
11
  export declare function validateNoWidgetRequiredField(featureName: string, screenId: string, entityDef: EntityDefinition, fieldSpec: Exclude<EditFieldSpec, string>): void;
12
- export declare function validateTabSections(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit", sections: readonly {
12
+ export declare function validateTabSections(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit", allSections: readonly {
13
13
  readonly id?: string;
14
14
  readonly title?: string;
15
15
  }[]): void;
@@ -78,6 +78,18 @@ export function validateEditFieldExtras(featureName, screenId, entityDef, fieldS
78
78
  // name must be a field of the same form — a typo would otherwise render no
79
79
  // affix or send an undefined param without a hint.
80
80
  export function validateFieldFormRefs(where, fieldSpec, formFieldNames) {
81
+ if (fieldSpec.valueChips !== undefined && !formFieldNames.has(fieldSpec.valueChips.from)) {
82
+ throw bootRuleError(FORM_FIELD_RULES.valueChipsUnknownField, {
83
+ message: `${where} valueChips.from "${fieldSpec.valueChips.from}" is not a field of this form. Known fields: ${[...formFieldNames].sort().join(", ")}`,
84
+ });
85
+ }
86
+ for (const contextField of fieldSpec.aiAssist?.contextFields ?? []) {
87
+ if (!formFieldNames.has(contextField)) {
88
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistContextFieldUnknown, {
89
+ message: `${where} aiAssist.contextFields names unknown field "${contextField}" — it must be another field of the same form.`,
90
+ });
91
+ }
92
+ }
81
93
  const affixes = [
82
94
  ["prefix", fieldSpec.prefix],
83
95
  ["suffix", fieldSpec.suffix],
@@ -104,10 +116,61 @@ export function validateFieldFormRefs(where, fieldSpec, formFieldNames) {
104
116
  }
105
117
  }
106
118
  }
107
- const FILL_ACTION_FIELD_TYPES = ["text", "number", "decimal", "bigInt"];
108
119
  // The fill button writes a plain text or numeric query result into the field;
109
120
  // a secret value must never be filled from a query response.
121
+ const FILL_ACTION_FIELD_TYPES = ["text", "number", "decimal", "bigInt"];
122
+ const AI_ASSIST_FIELD_TYPES = ["text", "longText"];
123
+ const VALUE_CHIPS_FIELD_TYPES = ["number", "decimal", "bigInt", "money"];
124
+ function validateAssistTargets(where, fieldSpec, fieldDef) {
125
+ // skip: the field is unknown (reported elsewhere)
126
+ if (fieldDef === undefined)
127
+ return;
128
+ const { aiAssist, valueChips } = fieldSpec;
129
+ if (valueChips !== undefined && !VALUE_CHIPS_FIELD_TYPES.includes(fieldDef.type)) {
130
+ throw bootRuleError(FORM_FIELD_RULES.valueChipsFieldType, {
131
+ message: `${where} valueChips needs a ${VALUE_CHIPS_FIELD_TYPES.join(", ")} field, not "${fieldDef.type}".`,
132
+ });
133
+ }
134
+ if (aiAssist === undefined)
135
+ return;
136
+ validateAiAssistTarget(where, aiAssist, fieldDef);
137
+ }
138
+ function validateAiAssistTarget(where, aiAssist, fieldDef) {
139
+ if (!AI_ASSIST_FIELD_TYPES.includes(fieldDef.type)) {
140
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistFieldType, {
141
+ message: `${where} aiAssist needs a text or longText field, not "${fieldDef.type}".`,
142
+ });
143
+ }
144
+ if (isSensitiveOrPasswordField(fieldDef)) {
145
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistSensitiveField, {
146
+ message: `${where} aiAssist targets a sensitive, writeOnly or password field. Remove aiAssist.`,
147
+ });
148
+ }
149
+ if ((aiAssist.chips ?? []).length === 0 && aiAssist.prompt === undefined) {
150
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistEmpty, {
151
+ message: `${where} aiAssist has neither chips nor a prompt.`,
152
+ });
153
+ }
154
+ if (aiAssist.resultField.trim() === "") {
155
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistResultFieldEmpty, {
156
+ message: `${where} aiAssist.resultField is empty. Name the query result key that holds the text.`,
157
+ });
158
+ }
159
+ if (aiAssist.prompt !== undefined && aiAssist.prompt.param.trim() === "") {
160
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistPromptParamEmpty, {
161
+ message: `${where} aiAssist.prompt.param is empty. Name the query payload key for the typed instruction.`,
162
+ });
163
+ }
164
+ for (const chip of aiAssist.chips ?? []) {
165
+ if (chip.label.trim() === "" || Object.keys(chip.params).length === 0) {
166
+ throw bootRuleError(FORM_FIELD_RULES.aiAssistChipInvalid, {
167
+ message: `${where} aiAssist chip "${chip.label}" needs a label and at least one param.`,
168
+ });
169
+ }
170
+ }
171
+ }
110
172
  export function validateFillActionTarget(where, fieldSpec, fieldDef) {
173
+ validateAssistTargets(where, fieldSpec, fieldDef);
111
174
  // skip: no fill action, or the field is unknown (reported elsewhere)
112
175
  if (fieldSpec.fillAction === undefined || fieldDef === undefined)
113
176
  return;
@@ -153,7 +216,11 @@ export function validateNoWidgetRequiredField(featureName, screenId, entityDef,
153
216
  // Shared by projectionDetail and entityEdit: a tab strip needs something to
154
217
  // label each tab with and a stable id per tab — the id anchors the ?tab=
155
218
  // param on projectionDetail and the jump-to-erroring-tab logic on entityEdit.
156
- export function validateTabSections(featureName, screenId, screenType, sections) {
219
+ export function validateTabSections(featureName, screenId, screenType, allSections) {
220
+ // projectionDetail: adjacent sections sharing an id are the blocks of one tab.
221
+ const sections = allSections.filter((section, index) => screenType !== "projectionDetail" ||
222
+ section.id === undefined ||
223
+ section.id !== allSections[index - 1]?.id);
157
224
  if (sections.length < 2) {
158
225
  throw bootRuleError(FORM_LAYOUT_RULES.tabsTooFewSections, {
159
226
  message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but only ` +
@@ -563,6 +630,12 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
563
630
  `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`,
564
631
  });
565
632
  }
633
+ if (section.kind === "stepList") {
634
+ throw bootRuleError(FORM_LAYOUT_RULES.stepListSectionUnsupported, {
635
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) stepList section ` +
636
+ `"${section.title ?? section.field}" is not supported — stepList is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`,
637
+ });
638
+ }
566
639
  if (isWriteFormEditSection(section)) {
567
640
  throw bootRuleError(FORM_LAYOUT_RULES.writeFormSectionUnsupported, {
568
641
  message: `[Feature ${featureName}] Screen "${screenId}" (${context}) writeForm section ` +
@@ -634,6 +707,38 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups)
634
707
  }
635
708
  // actionForm/secretMint have no entity link, only a write-handler QN +
636
709
  // inline fields: checks handler registration, field types, layout refs, and nav targets.
710
+ function validateActionFormFieldTexts(featureName, screenId, screen, fieldNames) {
711
+ for (const described of Object.keys(screen.fieldDescriptions ?? {})) {
712
+ if (fieldNames.has(described))
713
+ continue;
714
+ throw bootRuleError(FORM_FIELD_RULES.fieldDescriptionUnknownField, {
715
+ message: `[Feature ${featureName}] Screen "${screenId}" (actionForm) fieldDescriptions names unknown field "${described}". Known fields: ${[...fieldNames].sort().join(", ")}`,
716
+ });
717
+ }
718
+ for (const [owner, texts] of [
719
+ ["fieldLabels", screen.fieldLabels],
720
+ ["fieldDescriptions", screen.fieldDescriptions],
721
+ ]) {
722
+ for (const [fieldName, ref] of Object.entries(texts ?? {})) {
723
+ if (typeof ref === "string")
724
+ continue;
725
+ for (const param of Object.values(ref.params)) {
726
+ if (fieldNames.has(param))
727
+ continue;
728
+ throw bootRuleError(FORM_FIELD_RULES.fieldTextParamUnknownField, {
729
+ message: `[Feature ${featureName}] Screen "${screenId}" (actionForm) ${owner}.${fieldName} param names unknown field "${param}". Known fields: ${[...fieldNames].sort().join(", ")}`,
730
+ });
731
+ }
732
+ }
733
+ }
734
+ for (const badged of Object.keys(screen.fieldBadges ?? {})) {
735
+ if (fieldNames.has(badged))
736
+ continue;
737
+ throw bootRuleError(FORM_FIELD_RULES.fieldBadgeUnknownField, {
738
+ message: `[Feature ${featureName}] Screen "${screenId}" (actionForm) fieldBadges names unknown field "${badged}". Known fields: ${[...fieldNames].sort().join(", ")}`,
739
+ });
740
+ }
741
+ }
637
742
  export function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, lookups, featureMap) {
638
743
  validateWriteHandlerRegistered(feature.name, screenId, kind, screen.handler, allWriteHandlerQns);
639
744
  // Only a secretMint's own mint step may skip fields/sections entirely
@@ -643,6 +748,7 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
643
748
  validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
644
749
  validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap, fieldNames);
645
750
  if (screen.type === "actionForm") {
751
+ validateActionFormFieldTexts(feature.name, screenId, screen, fieldNames);
646
752
  validateFormDerivations(feature.name, screenId, screen);
647
753
  validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
648
754
  }
@@ -86,6 +86,7 @@ function layoutFieldNames(screen) {
86
86
  for (const section of screen.layout.sections) {
87
87
  if (isExtensionEditSection(section) ||
88
88
  section.kind === "relatedList" ||
89
+ section.kind === "stepList" ||
89
90
  section.kind === "writeForm") {
90
91
  continue;
91
92
  }
@@ -14,6 +14,11 @@ export declare const PROJECTION_DETAIL_RULES: {
14
14
  readonly summary: "A projectionDetail with a header sets no recordTitleField.";
15
15
  readonly fix: "Drop recordTitleField; header.title names the record.";
16
16
  };
17
+ readonly initialTabInvalid: {
18
+ readonly id: "projection-detail/initial-tab-invalid";
19
+ readonly summary: "initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions.";
20
+ readonly fix: "Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint.";
21
+ };
17
22
  readonly tabsSectionGroupsAndActions: {
18
23
  readonly id: "projection-detail/tabs-section-groups-and-actions";
19
24
  readonly summary: "A tabs-mode section declares groups or actions, not both.";