@cosmicdrift/kumiko-framework 0.415.0 → 0.417.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -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
  }
@@ -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);
@@ -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.";
@@ -109,6 +114,16 @@ export declare const PROJECTION_DETAIL_RULES: {
109
114
  readonly summary: "Every rendered writeForm field has a fieldDefs entry.";
110
115
  readonly fix: "Add the field to fieldDefs.";
111
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
+ };
112
127
  readonly wizardWriteForm: {
113
128
  readonly id: "projection-detail/wizard-write-form";
114
129
  readonly summary: "A wizard-mode layout has no writeForm section.";
@@ -14,6 +14,11 @@ export const PROJECTION_DETAIL_RULES = {
14
14
  summary: "A projectionDetail with a header sets no recordTitleField.",
15
15
  fix: "Drop recordTitleField; header.title names the record.",
16
16
  },
17
+ initialTabInvalid: {
18
+ id: "projection-detail/initial-tab-invalid",
19
+ summary: "initialTab needs layout.mode tabs and each rule names an existing section id; footerHint needs footerActions.",
20
+ fix: "Use tabs mode and section ids from the layout for initialTab, or declare footerActions next to footerHint.",
21
+ },
17
22
  tabsSectionGroupsAndActions: {
18
23
  id: "projection-detail/tabs-section-groups-and-actions",
19
24
  summary: "A tabs-mode section declares groups or actions, not both.",
@@ -109,6 +114,16 @@ export const PROJECTION_DETAIL_RULES = {
109
114
  summary: "Every rendered writeForm field has a fieldDefs entry.",
110
115
  fix: "Add the field to fieldDefs.",
111
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
+ },
112
127
  wizardWriteForm: {
113
128
  id: "projection-detail/wizard-write-form",
114
129
  summary: "A wizard-mode layout has no writeForm section.",
@@ -1,6 +1,7 @@
1
1
  import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
+ import { validateRelativeTimeFormat } from "./relative-time-format.js";
4
5
  import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateActionHasIcon, validatePrimaryActionTarget, } from "./screens-actions.js";
5
6
  import { rejectWriteOnlyFormField, validateFieldsXorGroups, validateFormSelectOptions, validateTabSections, } from "./screens-forms.js";
6
7
  import { validateProjectionDetailGuidance } from "./screens-kind-projection-detail-guidance.js";
@@ -51,6 +52,108 @@ function validateProjectionDetailTabs(featureName, screenId, screen) {
51
52
  }
52
53
  }
53
54
  }
55
+ function validateProjectionDetailInitialTab(featureName, screenId, screen) {
56
+ const where = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
57
+ if (screen.footerHint !== undefined && (screen.footerActions ?? []).length === 0) {
58
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
59
+ message: `${where} sets footerHint without footerActions — the footer bar only exists with footer actions.`,
60
+ });
61
+ }
62
+ // skip: the first tab opens first
63
+ if (screen.initialTab === undefined)
64
+ return;
65
+ if (screen.layout.mode !== "tabs") {
66
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
67
+ message: `${where} sets initialTab without layout.mode "tabs".`,
68
+ });
69
+ }
70
+ for (const rule of screen.initialTab) {
71
+ if (!screen.layout.sections.some((section) => section.id === rule.tab)) {
72
+ throw bootRuleError(PROJECTION_DETAIL_RULES.initialTabInvalid, {
73
+ message: `${where} initialTab names tab "${rule.tab}", which is not a section id on this screen.`,
74
+ });
75
+ }
76
+ }
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
+ }
54
157
  function validateProjectionDetailMetricNavigate(ctx, screenId, screen, field, navigate) {
55
158
  const featureName = ctx.feature.name;
56
159
  if (navigate.screen === undefined && navigate.entity === undefined) {
@@ -77,6 +180,7 @@ function validateProjectionDetailMetric(ctx, screenId, screen, metric) {
77
180
  `there is no fallback to the raw column name.`,
78
181
  });
79
182
  }
183
+ validateRelativeTimeFormat(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail)`, `metric "${metric.field}"`, metric.format);
80
184
  if (metric.navigate !== undefined) {
81
185
  validateProjectionDetailMetricNavigate(ctx, screenId, screen, metric.field, metric.navigate);
82
186
  }
@@ -252,6 +356,10 @@ function validateProjectionDetailSection(ctx, screenId, screen, section) {
252
356
  else if (isWriteFormEditSection(section)) {
253
357
  validateProjectionDetailWriteForm(ctx, screenId, screen, section);
254
358
  }
359
+ else if (section.kind === "stepList") {
360
+ // field existence is checked against the outputSchema in query-output-columns
361
+ return;
362
+ }
255
363
  else {
256
364
  validateProjectionDetailFieldsSection(ctx, screenId, section);
257
365
  }
@@ -283,6 +391,8 @@ export function validateProjectionDetailScreen(ctx, screenId, screen) {
283
391
  validateProjectionDetailFlags(featureName, screenId, screen);
284
392
  rejectEmptySections(featureName, screenId, "projectionDetail", screen.layout.sections.length);
285
393
  validateProjectionDetailTabs(featureName, screenId, screen);
394
+ validateProjectionDetailInitialTab(featureName, screenId, screen);
395
+ validateProjectionDetailPresentation(featureName, screenId, screen);
286
396
  for (const metric of screen.metrics ?? []) {
287
397
  validateProjectionDetailMetric(ctx, screenId, screen, metric);
288
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
@@ -44,6 +44,11 @@ export declare const LIST_SCREEN_RULES: {
44
44
  readonly summary: "A column renderer's react.__component is a non-empty string.";
45
45
  readonly fix: "Set react.__component to the name of a client columnRenderers entry.";
46
46
  };
47
+ readonly relativeTimeOptionsInvalid: {
48
+ readonly id: "list/relative-time-options-invalid";
49
+ readonly summary: "relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid.";
50
+ readonly fix: "Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone.";
51
+ };
47
52
  readonly enumOptionTonesInvalid: {
48
53
  readonly id: "list/enum-option-tones-invalid";
49
54
  readonly summary: "enumOption column tones are known select option tones.";
@@ -44,6 +44,11 @@ export const LIST_SCREEN_RULES = {
44
44
  summary: "A column renderer's react.__component is a non-empty string.",
45
45
  fix: "Set react.__component to the name of a client columnRenderers entry.",
46
46
  },
47
+ relativeTimeOptionsInvalid: {
48
+ id: "list/relative-time-options-invalid",
49
+ summary: "relativeTime format options (style, absoluteAfterDays, withTime, timeZone) are valid.",
50
+ fix: "Use style long, short or narrow, an integer absoluteAfterDays of at least 1 and a boolean withTime and an IANA timeZone.",
51
+ },
47
52
  enumOptionTonesInvalid: {
48
53
  id: "list/enum-option-tones-invalid",
49
54
  summary: "enumOption column tones are known select option tones.",
@@ -7,11 +7,12 @@ import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, scre
7
7
  import { bootRuleError } from "./boot-rule.js";
8
8
  import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
9
9
  import { validateListBulkActions } from "./list-bulk-actions.js";
10
- import { validateListRowGuidance } from "./list-row-guidance.js";
10
+ import { validateListRowGuidance, validatePhotoGrid } from "./list-row-guidance.js";
11
11
  import { LIST_ROW_GUIDANCE_RULES } from "./list-row-guidance-rules.js";
12
12
  import { rejectSummaryRowOnRelatedList } from "./list-sort-summary.js";
13
13
  import { validateListTableOptions } from "./list-table-options.js";
14
14
  import { validateRelatedListGroupingRules } from "./related-list-table-rules.js";
15
+ import { validateRelativeTimeFormat } from "./relative-time-format.js";
15
16
  import { assertWriteHandlerRegistered, isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
16
17
  import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
17
18
  import { SCREEN_KIND_RULES } from "./screens-kind-rules.js";
@@ -94,6 +95,7 @@ function validateRelatedListTableAndBulk(args) {
94
95
  // swallow a summaryRow with a less specific message.
95
96
  rejectSummaryRowOnRelatedList(`[Feature ${featureName}] ${where}`, section.table);
96
97
  validateRelatedListGroupingRules(`[Feature ${featureName}] ${where}`, section, args.screenType === "entityList expandableRow");
98
+ validatePhotoGrid(`[Feature ${featureName}] ${where}`, section);
97
99
  validateListTableOptions(`[Feature ${featureName}] ${where}`, section.table, section.columns);
98
100
  if (section.rowActions !== undefined)
99
101
  validateRelatedListRowActions(args, section.rowActions);
@@ -278,6 +280,7 @@ export function rejectInertColumnSortable(featureName, screenId, screenType, col
278
280
  // failure.
279
281
  export function validateColumnRendererForm(featureName, screenId, column) {
280
282
  validateEnumOptionTones(`[Feature ${featureName}] Screen "${screenId}"`, column);
283
+ validateRelativeTimeFormat(`[Feature ${featureName}] Screen "${screenId}"`, `column "${column.field}"`, column.renderer);
281
284
  if (column.linkParamsField !== undefined && column.linkScreenField === undefined) {
282
285
  throw bootRuleError(LIST_ROW_GUIDANCE_RULES.linkParamsWithoutScreenField, {
283
286
  message: `[Feature ${featureName}] Screen "${screenId}" column "${column.field}" sets linkParamsField ` +
@@ -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"),
@@ -16,12 +16,12 @@
16
16
  // refs (buildNavRegistrySliceForApp qualifies them itself).
17
17
  import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
18
18
  import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
19
+ import { rolesToAccess, unionAccessRules } from "./config-access-rules.js";
19
20
  import { isEncryptedAtRest } from "./config-helpers.js";
20
21
  import { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
21
22
  import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
22
23
  import { isKebabSegment, toKebab } from "./qualified-name.js";
23
24
  import { isFieldsEditSection, sectionFieldSpecs, } from "./screen-helpers.js";
24
- import { isOpenToAllGranted } from "./types/handlers.js";
25
25
  // Namespace under which buildAppSchema attaches the generated screens/navs
26
26
  // (find-or-create FeatureSchema). It MUST match CONFIG_FEATURE from the config
27
27
  // bundled feature. The framework cannot import that constant because of the
@@ -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(fieldId), 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
  }
@@ -809,6 +832,9 @@ function collectMaskedKeys(registry) {
809
832
  if (def.group !== undefined && !isKebabSegment(def.group)) {
810
833
  throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`);
811
834
  }
835
+ if (def.mask?.readOnly === true && def.required === true) {
836
+ throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" is mask.readOnly and required — nobody could fill it.`);
837
+ }
812
838
  // computed keys derive their value — there is no row to set, so a
813
839
  // configEdit screen could not write them. Skip even when masked.
814
840
  if (def.mask === undefined || def.computed !== undefined)
@@ -835,36 +861,3 @@ function maskOrder(k) {
835
861
  function minMaskOrder(keys) {
836
862
  return Math.min(...keys.map(maskOrder));
837
863
  }
838
- // The hub is for editing: anyone allowed to WRITE at least one key in the group
839
- // sees the Settings entry (write, not read). This keeps system-scope (write
840
- // default `["system"]`) hidden from humans until the author opts in with
841
- // write: SystemAdmin, while user-scope (write `all`) is shown to everyone.
842
- // `all` can only be represented as openToAll in AccessRule; writes remain
843
- // gated per key on the server.
844
- // Access rules for navs are unioned: an openToAll nav opens the whole gate;
845
- // otherwise roles are combined. Navs without access rules contribute nothing.
846
- function unionAccessRules(rules) {
847
- const roles = [];
848
- for (const rule of rules) {
849
- if (rule === undefined)
850
- continue;
851
- if ("openToAll" in rule) {
852
- if (isOpenToAllGranted(rule))
853
- return rule;
854
- continue;
855
- }
856
- roles.push(...rule.roles);
857
- }
858
- return rolesToAccess(roles);
859
- }
860
- // `all` can only be represented as openToAll in AccessRule; writes remain gated
861
- // per key on the server.
862
- function rolesToAccess(roles) {
863
- if (roles.includes("all"))
864
- return {
865
- openToAll: {
866
- reason: 'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
867
- },
868
- };
869
- return { roles: [...new Set(roles)] };
870
- }
@@ -0,0 +1,3 @@
1
+ import type { AccessRule } from "./types/handlers.ts";
2
+ export declare function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRule;
3
+ export declare function rolesToAccess(roles: readonly string[]): AccessRule;
@@ -0,0 +1,34 @@
1
+ import { isOpenToAllGranted } from "./types/handlers.js";
2
+ // The hub is for editing: anyone allowed to WRITE at least one key in the group
3
+ // sees the Settings entry (write, not read). This keeps system-scope (write
4
+ // default `["system"]`) hidden from humans until the author opts in with
5
+ // write: SystemAdmin, while user-scope (write `all`) is shown to everyone.
6
+ // `all` can only be represented as openToAll in AccessRule; writes remain
7
+ // gated per key on the server.
8
+ // Access rules for navs are unioned: an openToAll nav opens the whole gate;
9
+ // otherwise roles are combined. Navs without access rules contribute nothing.
10
+ export function unionAccessRules(rules) {
11
+ const roles = [];
12
+ for (const rule of rules) {
13
+ if (rule === undefined)
14
+ continue;
15
+ if ("openToAll" in rule) {
16
+ if (isOpenToAllGranted(rule))
17
+ return rule;
18
+ continue;
19
+ }
20
+ roles.push(...rule.roles);
21
+ }
22
+ return rolesToAccess(roles);
23
+ }
24
+ // `all` can only be represented as openToAll in AccessRule; writes remain gated
25
+ // per key on the server.
26
+ export function rolesToAccess(roles) {
27
+ if (roles.includes("all"))
28
+ return {
29
+ openToAll: {
30
+ reason: 'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
31
+ },
32
+ };
33
+ return { roles: [...new Set(roles)] };
34
+ }
@@ -219,4 +219,6 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
219
219
  readonly transferable?: boolean;
220
220
  /** See EntityDefinition.attachedFileAccess. */
221
221
  readonly attachedFileAccess?: EntityDefinition["attachedFileAccess"];
222
+ /** See EntityDefinition.crossTenantFileRead. */
223
+ readonly crossTenantFileRead?: EntityDefinition["crossTenantFileRead"];
222
224
  }): F extends FieldsMap ? EntityDefinition<F, T> : never;
@@ -324,6 +324,8 @@ function projectEditSection(section, feature, indices, keptScreenQns) {
324
324
  switch (section.kind) {
325
325
  case "relatedList":
326
326
  return projectRelatedListSection(section, feature, indices, keptScreenQns);
327
+ case "stepList":
328
+ return section;
327
329
  case "extension": {
328
330
  const { actions, ...rest } = section;
329
331
  const kept = projectActionArray(actions, feature, indices, keptScreenQns);