@cosmicdrift/kumiko-framework 0.414.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 (115) hide show
  1. package/agents/api/framework-engine.md +46 -8
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +69 -4
  4. package/agents/api/renderer-web.md +27 -4
  5. package/agents/api/types.md +68 -16
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +39 -7
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/embedded.md +24 -1
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/record-detail-layout.md +113 -7
  12. package/agents/examples/signature.md +186 -0
  13. package/agents/examples/writeform-section.md +1 -0
  14. package/agents/examples.md +2 -0
  15. package/agents/features-index.md +4 -0
  16. package/agents/features.md +14 -0
  17. package/agents/widgets.md +7 -0
  18. package/dist/api/request-context-internals.d.ts +2 -0
  19. package/dist/api/request-context-scopes.js +9 -2
  20. package/dist/api/request-context.js +1 -1
  21. package/dist/api/routes.js +4 -4
  22. package/dist/api/server-event-dispatcher.js +3 -0
  23. package/dist/api/server-routes.js +2 -0
  24. package/dist/db/parent-ref-clause.js +31 -3
  25. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  26. package/dist/db/parent-ref-global-hosts.js +50 -12
  27. package/dist/db/queries/rls-boot-catalog.js +5 -6
  28. package/dist/db/queries/rls-shape.d.ts +1 -0
  29. package/dist/db/queries/rls-shape.js +21 -6
  30. package/dist/db/table-builder.js +3 -1
  31. package/dist/engine/boot-validator/boot-phases.js +5 -0
  32. package/dist/engine/boot-validator/boot-rules.d.ts +144 -9
  33. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  34. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  35. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  36. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  37. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  38. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  39. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  40. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  41. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +17 -2
  42. package/dist/engine/boot-validator/list-row-guidance-rules.js +17 -2
  43. package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
  44. package/dist/engine/boot-validator/list-row-guidance.js +45 -1
  45. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  46. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  47. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  48. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  49. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  50. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  51. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  52. package/dist/engine/boot-validator/query-output-columns.js +18 -0
  53. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  54. package/dist/engine/boot-validator/query-refs.js +14 -1
  55. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  56. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  57. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  58. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  59. package/dist/engine/boot-validator/screens-actions.js +56 -16
  60. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  61. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  62. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  63. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  64. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  65. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  68. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  69. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  70. package/dist/engine/boot-validator/screens-forms.js +108 -2
  71. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  72. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  73. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  74. package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
  75. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  76. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  77. package/dist/engine/boot-validator/screens-lists.js +4 -1
  78. package/dist/engine/build-config-feature-schema.js +5 -35
  79. package/dist/engine/config-access-rules.d.ts +3 -0
  80. package/dist/engine/config-access-rules.js +34 -0
  81. package/dist/engine/factories.d.ts +2 -0
  82. package/dist/engine/named-filter-roles.js +6 -14
  83. package/dist/engine/project-app-schema-for-roles.js +2 -0
  84. package/dist/engine/schema-builder.js +3 -1
  85. package/dist/engine/soft-delete-cleanup.js +2 -0
  86. package/dist/errors/reasons.d.ts +1 -0
  87. package/dist/errors/reasons.js +4 -0
  88. package/dist/files/file-routes.d.ts +2 -0
  89. package/dist/files/file-routes.js +85 -22
  90. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  91. package/dist/files/foreign-tenant-file-read.js +64 -0
  92. package/dist/i18n/required-surface-keys.js +28 -7
  93. package/dist/jobs/job-runner-execution.js +3 -0
  94. package/dist/jobs/job-runner-types.d.ts +1 -0
  95. package/dist/jobs/job-runner.js +8 -0
  96. package/dist/pipeline/context-services.d.ts +1 -1
  97. package/dist/pipeline/context-services.js +1 -1
  98. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  99. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  100. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  101. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  102. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  103. package/dist/search/meilisearch-adapter-internals.js +5 -0
  104. package/dist/search/meilisearch-adapter.d.ts +1 -0
  105. package/dist/search/meilisearch-adapter.js +3 -2
  106. package/dist/ui-types/card-column-roles.d.ts +2 -0
  107. package/dist/ui-types/card-column-roles.js +15 -0
  108. package/dist/ui-types/index.d.ts +2 -2
  109. package/dist/ui-types/index.js +1 -1
  110. package/package.json +3 -3
  111. package/presets/biome-plugins/no-date-api.grit +3 -1
  112. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  113. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  114. package/presets/biome-rules.json +12 -10
  115. package/src/changes.json +99 -0
@@ -1,7 +1,7 @@
1
+ import { entityListDeclaresFilters, entityListDeclaresSearch, listPayloadKeysSent, } from "@cosmicdrift/kumiko-types/screen";
1
2
  import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
2
3
  import { LIST_TABLE_SUMMARY_ROW_KEYS } from "../types/screen.js";
3
4
  import { bootRuleError } from "./boot-rule.js";
4
- import { hasFilterableFields } from "./entity-list-screens.js";
5
5
  import { LIST_SORT_SUMMARY_RULES } from "./list-sort-summary-rules.js";
6
6
  import { rejectUnknownKeys } from "./list-table-reject-unknown-keys.js";
7
7
  import { buildQueryHandlerMap, schemaAccepts } from "./projection-list-screens.js";
@@ -32,32 +32,31 @@ export function rejectSummaryRowOnRelatedList(where, table) {
32
32
  });
33
33
  }
34
34
  }
35
- function entityListKeysSent(feature, screen) {
35
+ function entityListCapabilities(feature, screen) {
36
36
  const entity = feature.entities?.[screen.entity];
37
- const searchable = screen.searchable ??
38
- Object.values(entity?.fields ?? {}).some((f) => "searchable" in f && f.searchable === true);
39
- const hasRangeFacet = Object.values(screen.facets ?? {}).some((facet) => facet !== false && facet.display === "range");
40
- const filters = hasFilterableFields(feature, screen.entity) ||
41
- screen.defaultFilters !== undefined ||
42
- hasRangeFacet;
43
- return [...(searchable ? ["search"] : []), ...(filters ? ["filters"] : [])];
37
+ return {
38
+ searchable: entityListDeclaresSearch(screen, entity),
39
+ filters: entityListDeclaresFilters(screen, entity),
40
+ };
44
41
  }
45
- function projectionListKeysSent(screen, queryHandlers) {
42
+ function projectionListCapabilities(screen, queryHandlers) {
46
43
  const listSchema = queryHandlers.get(screen.query)?.schema;
47
- const searchable = screen.searchable !== false && schemaAccepts(listSchema, "search");
48
- return [...(searchable ? ["search"] : []), ...(screen.facets !== undefined ? ["filters"] : [])];
44
+ return {
45
+ searchable: screen.searchable !== false && schemaAccepts(listSchema, "search"),
46
+ filters: screen.facets !== undefined,
47
+ };
49
48
  }
50
49
  // The keys the list sends for what the screen declares (mirrors the renderer); the summary query
51
50
  // gets the same ones so its numbers follow the narrowing the user sees.
52
51
  function listKeysSentBy(feature, screen, queryHandlers) {
53
- const own = [
54
- ...(screen.namedFilters !== undefined ? ["namedFilter"] : []),
55
- ...(screen.filter !== undefined ? ["filter"] : []),
56
- ];
57
52
  const derived = screen.type === "entityList"
58
- ? entityListKeysSent(feature, screen)
59
- : projectionListKeysSent(screen, queryHandlers);
60
- return [...derived, ...own];
53
+ ? entityListCapabilities(feature, screen)
54
+ : projectionListCapabilities(screen, queryHandlers);
55
+ return listPayloadKeysSent({
56
+ ...derived,
57
+ namedFilters: screen.namedFilters !== undefined,
58
+ screenFilter: screen.filter !== undefined,
59
+ });
61
60
  }
62
61
  function validateSummaryRowQuery(prefix, feature, screen, summaryRow, queryHandlers) {
63
62
  const handler = queryHandlers.get(summaryRow.query);
@@ -67,7 +66,8 @@ function validateSummaryRowQuery(prefix, feature, screen, summaryRow, queryHandl
67
66
  });
68
67
  }
69
68
  const shape = getZodObjectShape(handler.schema);
70
- const missing = listKeysSentBy(feature, screen, queryHandlers).filter((key) => shape === undefined || !(key in shape));
69
+ const paramKeys = Object.keys(summaryRow.params ?? {});
70
+ const missing = [...listKeysSentBy(feature, screen, queryHandlers), ...paramKeys].filter((key) => shape === undefined || !(key in shape));
71
71
  if (missing.length === 0)
72
72
  return;
73
73
  throw bootRuleError(LIST_SORT_SUMMARY_RULES.summaryRowQueryAcceptsListKeys, {
@@ -101,6 +101,17 @@ function validateProjectionSortOptions(prefix, screen, queryHandlers) {
101
101
  `accepts for "sort" (${accepted.join(", ")}) - every pick would fail with a 422.`,
102
102
  });
103
103
  }
104
+ const acceptedDirections = getZodStringLiterals(shape["sortDirection"]);
105
+ // skip: "sortDirection" is an open string
106
+ if (acceptedDirections === undefined)
107
+ return;
108
+ const rejectedDirection = options.find((option) => !acceptedDirections.includes(option.dir));
109
+ if (rejectedDirection !== undefined) {
110
+ throw bootRuleError(LIST_SORT_SUMMARY_RULES.sortOptionNotSortable, {
111
+ message: `${prefix}: sortOptions dir "${rejectedDirection.dir}" is not one of the values query "${screen.query}" ` +
112
+ `accepts for "sortDirection" (${acceptedDirections.join(", ")}) - every pick would fail with a 422.`,
113
+ });
114
+ }
104
115
  }
105
116
  function validateSortOptionsList(prefix, screen) {
106
117
  const options = screen.sortOptions;
@@ -1,8 +1,7 @@
1
- import { LIST_NARROW_FACETS } from "@cosmicdrift/kumiko-types/screen";
1
+ import { LIST_NARROW_FACETS, LIST_TOOLBAR_ACTIONS_PLACEMENTS, } from "@cosmicdrift/kumiko-types/screen";
2
2
  import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { SCREEN_KIND_RULES } from "./screens-kind-rules.js";
5
- const TOOLBAR_ACTIONS_PLACEMENTS = ["header", "toolbar"];
6
5
  /** Toolbar options shared by entityList and projectionList. */
7
6
  export function validateListToolbarOptions(where, screen) {
8
7
  if (screen.toolbarSort === true && (screen.sortOptions ?? []).length === 0) {
@@ -18,9 +17,9 @@ export function validateListToolbarOptions(where, screen) {
18
17
  const placement = screen.toolbarActionsPlacement;
19
18
  if (placement === undefined)
20
19
  return;
21
- if (!isOneOf(TOOLBAR_ACTIONS_PLACEMENTS, placement)) {
20
+ if (!isOneOf(LIST_TOOLBAR_ACTIONS_PLACEMENTS, placement)) {
22
21
  throw bootRuleError(SCREEN_KIND_RULES.toolbarActionsPlacementInvalid, {
23
- message: `${where} sets toolbarActionsPlacement ${JSON.stringify(placement)} — must be "header" or "toolbar".`,
22
+ message: `${where} sets toolbarActionsPlacement ${JSON.stringify(placement)} — must be ${LIST_TOOLBAR_ACTIONS_PLACEMENTS.map((p) => `"${p}"`).join(" or ")}.`,
24
23
  });
25
24
  }
26
25
  if (placement === "toolbar" && (screen.toolbarActions ?? []).length === 0) {
@@ -34,6 +34,16 @@ export declare const NAMED_FILTER_RULES: {
34
34
  readonly summary: "A named filter's emptyState.title is a non-empty i18n key.";
35
35
  readonly fix: "Name the title key or remove emptyState from the filter.";
36
36
  };
37
+ readonly emptyStateParamsQueryEmpty: {
38
+ readonly id: "list/named-filter-empty-state-params-query-empty";
39
+ readonly summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.";
40
+ readonly fix: "Name the query or remove paramsQuery from the emptyState.";
41
+ };
42
+ readonly emptyStateParamsQueryWithoutDescription: {
43
+ readonly id: "list/named-filter-empty-state-params-query-without-description";
44
+ readonly summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.";
45
+ readonly fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.";
46
+ };
37
47
  readonly statNavigateTarget: {
38
48
  readonly id: "named-filter/stat-navigate-target";
39
49
  readonly summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.";
@@ -34,6 +34,16 @@ export const NAMED_FILTER_RULES = {
34
34
  summary: "A named filter's emptyState.title is a non-empty i18n key.",
35
35
  fix: "Name the title key or remove emptyState from the filter.",
36
36
  },
37
+ emptyStateParamsQueryEmpty: {
38
+ id: "list/named-filter-empty-state-params-query-empty",
39
+ summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.",
40
+ fix: "Name the query or remove paramsQuery from the emptyState.",
41
+ },
42
+ emptyStateParamsQueryWithoutDescription: {
43
+ id: "list/named-filter-empty-state-params-query-without-description",
44
+ summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.",
45
+ fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.",
46
+ },
37
47
  statNavigateTarget: {
38
48
  id: "named-filter/stat-navigate-target",
39
49
  summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.",
@@ -108,17 +108,18 @@ function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schem
108
108
  `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
109
109
  });
110
110
  }
111
- // showCounts asks the query once per filter with { limit: 1, totalCount: true, namedFilter }; a schema
111
+ // showCounts and hideEmpty ask the query once per filter with { limit: 1, totalCount: true, namedFilter }; a schema
112
112
  // without those keys 422s every count request.
113
113
  function validateProjectionListNamedFilterCountAcceptance(prefix, screen, schema) {
114
- if (screen.namedFilterFacet?.showCounts !== true)
114
+ if (screen.namedFilterFacet?.showCounts !== true && screen.namedFilterFacet?.hideEmpty !== true) {
115
115
  return;
116
+ }
116
117
  const missing = ["limit", "totalCount"].filter((key) => !schemaAccepts(schema, key));
117
118
  if (missing.length === 0)
118
119
  return;
119
120
  throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsCount, {
120
- message: `${prefix}: namedFilterFacet.showCounts needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
121
- `- add them or drop showCounts.`,
121
+ message: `${prefix}: namedFilterFacet.${screen.namedFilterFacet.showCounts === true ? "showCounts" : "hideEmpty"} needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
122
+ `- add them or drop showCounts and hideEmpty.`,
122
123
  });
123
124
  }
124
125
  // A filter's own sort travels as `payload.sort`/`sortDirection`; without them in the schema it 422s
@@ -149,6 +149,15 @@ function checkDetailSectionFields(recordShape, prefix, screen) {
149
149
  if (countField !== undefined) {
150
150
  checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
151
151
  }
152
+ if (section.visibleWhen !== undefined) {
153
+ const conditionField = section.visibleWhen.field;
154
+ checkFieldExists(recordShape, conditionField, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" 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.`);
155
+ }
156
+ if (section.kind === "stepList") {
157
+ const stepField = section.field;
158
+ checkFieldExists(recordShape, stepField, () => `${prefix} stepList section "${section.title ?? section.id ?? "(untitled)"}" references field "${stepField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
159
+ continue;
160
+ }
152
161
  if (section.kind !== undefined && section.kind !== "fields")
153
162
  continue;
154
163
  for (const entry of sectionFieldSpecs(section)) {
@@ -286,11 +295,20 @@ function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen)
286
295
  screen.type === "configEdit" ||
287
296
  screen.type === "secretMint") {
288
297
  checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
298
+ if (screen.type === "actionForm")
299
+ checkSummaryLoadFields(queryHandlers, featureName, screenId, screen);
289
300
  }
290
301
  else if (screen.type === "dashboard") {
291
302
  checkDashboardOutputFields(queryHandlers, featureName, screenId, screen);
292
303
  }
293
304
  }
305
+ // summary.paramsFromLoad reads the raw load result, so each name must be an output field of the load query.
306
+ function checkSummaryLoadFields(queryHandlers, featureName, screenId, screen) {
307
+ const shape = getZodObjectShape(screen.load === undefined ? undefined : queryHandlers.get(screen.load.query)?.outputSchema);
308
+ for (const field of screen.summary?.paramsFromLoad ?? []) {
309
+ 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
+ }
311
+ }
294
312
  export function validateQueryOutputColumns(features) {
295
313
  const queryHandlers = buildQueryHandlerMap(features);
296
314
  checkPagedHandlerOutputSchemaShape(queryHandlers);
@@ -27,8 +27,11 @@ export function listGuidanceFieldRefs(screen) {
27
27
  const hint = column.hint;
28
28
  return [
29
29
  { option: "linkParamsField", field: column.linkParamsField },
30
+ { option: "pillField", field: column.pillField },
31
+ { option: "pillToneField", field: column.pillToneField },
30
32
  { option: "hint.detailField", field: hint?.detailField },
31
33
  { option: "hint.narrowDetailField", field: hint?.narrowDetailField },
34
+ { option: "hint.narrowField", field: hint?.narrowField },
32
35
  { option: "hint.toneField", field: hint?.toneField },
33
36
  { option: "hint.reasonField", field: hint?.reasonField },
34
37
  { option: "hint.reasonOpenField", field: hint?.reasonOpenField },
@@ -48,7 +48,10 @@ function checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screenTy
48
48
  for (const section of layout.sections) {
49
49
  if (isFieldsEditSection(section)) {
50
50
  for (const fieldSpec of sectionFieldSpecs(section)) {
51
- const { field, fillAction } = normalizeEditField(fieldSpec);
51
+ const { field, fillAction, aiAssist } = normalizeEditField(fieldSpec);
52
+ if (aiAssist !== undefined) {
53
+ checkQueryRef(queryHandlers, aiAssist.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${field}" aiAssist`);
54
+ }
52
55
  if (fillAction === undefined)
53
56
  continue;
54
57
  checkQueryRef(queryHandlers, fillAction.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${field}" fillAction`);
@@ -139,6 +142,14 @@ function checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen
139
142
  message: `${prefix} query "${decoration.query}" does not declare "ids" in its input schema. The list sends the loaded row ids as "ids"; add ids: z.array(z.string()).`,
140
143
  });
141
144
  }
145
+ function checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen) {
146
+ for (const ref of screen.namedFilters ?? []) {
147
+ const query = ref.emptyState?.paramsQuery;
148
+ if (query === undefined)
149
+ continue;
150
+ checkQueryRef(queryHandlers, query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) namedFilters "${ref.id}" emptyState.paramsQuery`);
151
+ }
152
+ }
142
153
  function checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen) {
143
154
  for (const action of screen.toolbarActions ?? []) {
144
155
  if (action.visibleWhen === undefined)
@@ -161,10 +172,12 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
161
172
  checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
162
173
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
163
174
  checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
175
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
164
176
  }
165
177
  else if (screen.type === "entityList") {
166
178
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
167
179
  checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
180
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
168
181
  if (screen.expandableRow !== undefined) {
169
182
  checkQueryRef(queryHandlers, screen.expandableRow.query, () => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}"`);
170
183
  }
@@ -0,0 +1 @@
1
+ export declare function validateRelativeTimeFormat(prefix: string, label: string, format: unknown): void;
@@ -0,0 +1,51 @@
1
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ import { LIST_SCREEN_RULES } from "./screens-lists-rules.js";
4
+ const RELATIVE_TIME_STYLES = ["long", "short", "narrow"];
5
+ function isKnownTimeZone(value) {
6
+ if (typeof value !== "string")
7
+ return false;
8
+ try {
9
+ new Intl.DateTimeFormat("en", { timeZone: value });
10
+ return true;
11
+ }
12
+ catch {
13
+ return false;
14
+ }
15
+ }
16
+ function relativeTimeOptionProblem(format) {
17
+ const style = propertyOf(format, "style");
18
+ if (style !== undefined && !RELATIVE_TIME_STYLES.includes(style)) {
19
+ return `style ${String(style)} (expected long, short or narrow)`;
20
+ }
21
+ const absoluteAfterDays = propertyOf(format, "absoluteAfterDays");
22
+ if (absoluteAfterDays !== undefined &&
23
+ !(typeof absoluteAfterDays === "number" &&
24
+ Number.isInteger(absoluteAfterDays) &&
25
+ absoluteAfterDays >= 1)) {
26
+ return `absoluteAfterDays ${String(absoluteAfterDays)} (expected an integer of at least 1)`;
27
+ }
28
+ const timeZone = propertyOf(format, "timeZone");
29
+ if (timeZone !== undefined && !isKnownTimeZone(timeZone)) {
30
+ return `timeZone ${String(timeZone)} (expected an IANA zone id such as Europe/Berlin)`;
31
+ }
32
+ const withTime = propertyOf(format, "withTime");
33
+ if (withTime !== undefined && typeof withTime !== "boolean") {
34
+ return `withTime ${String(withTime)} (expected a boolean)`;
35
+ }
36
+ return undefined;
37
+ }
38
+ // A typo'd option would silently fall back to the plain relative text.
39
+ export function validateRelativeTimeFormat(prefix, label, format) {
40
+ // skip: only a relativeTime format has these options
41
+ if (typeof format !== "object" || format === null)
42
+ return;
43
+ if (propertyOf(format, "format") !== "relativeTime")
44
+ return;
45
+ const problem = relativeTimeOptionProblem(format);
46
+ if (problem === undefined)
47
+ return;
48
+ throw bootRuleError(LIST_SCREEN_RULES.relativeTimeOptionsInvalid, {
49
+ message: `${prefix} ${label} has relativeTime option ${problem}.`,
50
+ });
51
+ }
@@ -129,6 +129,16 @@ export declare const SCREEN_ACTION_RULES: {
129
129
  readonly summary: "A redirect idFrom only targets entityEdit or projectionDetail screens.";
130
130
  readonly fix: "Use the plain string redirect form.";
131
131
  };
132
+ readonly redirectSearchParamsOnlyActionForm: {
133
+ readonly id: "screen/redirect-search-params-only-action-form";
134
+ readonly summary: "A redirect searchParams is only set on actionForm redirects.";
135
+ readonly fix: "Remove searchParams; other screen kinds do not read it.";
136
+ };
137
+ readonly redirectSearchParamsEmpty: {
138
+ readonly id: "screen/redirect-search-params-empty";
139
+ readonly summary: "A redirect searchParams entry has a non-empty param name and payload field.";
140
+ readonly fix: "Map each search param name to a success-payload field.";
141
+ };
132
142
  readonly successLinkTargetsRecordScreen: {
133
143
  readonly id: "screen/success-link-targets-record-screen";
134
144
  readonly summary: "A success link without idFrom does not target a record screen.";
@@ -146,9 +156,14 @@ export declare const SCREEN_ACTION_RULES: {
146
156
  };
147
157
  readonly primaryActionUnknown: {
148
158
  readonly id: "screen/primary-action-unknown";
149
- readonly summary: "primaryAction and inlineActions name a declared action id or the default edit.";
159
+ readonly summary: "primaryAction, inlineActions and footerActions name a declared action id or the default edit.";
150
160
  readonly fix: 'Use a declared action id, or "edit" when the screen sets detailFor.';
151
161
  };
162
+ readonly footerActionConflict: {
163
+ readonly id: "screen/footer-action-conflict";
164
+ readonly summary: "A footerActions id is neither the primaryAction nor in inlineActions.";
165
+ readonly fix: "Keep each action in one place: header (primaryAction), inline row or pinned footer.";
166
+ };
152
167
  readonly fallbackWithoutVisibleWhen: {
153
168
  readonly id: "screen/fallback-without-visible-when";
154
169
  readonly summary: "A screen with a fallback also declares visibleWhen.";
@@ -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.",
@@ -116,7 +116,7 @@ export function validateRowActionNavigateParams(featureName, screenId, screenTyp
116
116
  //
117
117
  // Registration check (not just "resolved is not undefined"): action.icon is
118
118
  // typed IconKey, a closed union — but that only protects call sites this
119
- // repo's own `tsc --build` actually covers (samples and external consumers
119
+ // repo's own typecheck actually covers (samples and external consumers
120
120
  // aren't in that project graph). The renderer's actionIconFor
121
121
  // (renderer/src/web/primitives/index.tsx) already falls back to "no icon"
122
122
  // for an unregistered key instead of crashing — this check makes the same
@@ -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",