@cosmicdrift/kumiko-framework 0.416.0 → 0.418.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/agents/api/framework-engine.md +32 -9
  2. package/agents/api/framework-ui-types.md +37 -10
  3. package/agents/api/renderer-web.md +25 -2
  4. package/agents/api/types.md +121 -64
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +23 -1
  7. package/agents/examples/crypto-shredding-hr.md +2 -2
  8. package/agents/examples/dashboard-stats.md +51 -0
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/list-table-options.md +346 -12
  11. package/agents/examples/managed-config.md +9 -1
  12. package/agents/examples/record-detail-layout.md +71 -6
  13. package/agents/examples/secrets-demo.md +3 -1
  14. package/agents/examples/signature.md +3 -2
  15. package/agents/examples/writeform-section.md +329 -0
  16. package/agents/features.md +1 -1
  17. package/dist/api/server-boot-checks.d.ts +1 -0
  18. package/dist/api/server-boot-checks.js +25 -0
  19. package/dist/api/server-rate-limit-wiring.js +2 -1
  20. package/dist/db/queries/event-store.d.ts +3 -0
  21. package/dist/db/queries/event-store.js +12 -0
  22. package/dist/engine/boot-validator/action-form-preview-rules.d.ts +22 -0
  23. package/dist/engine/boot-validator/action-form-preview-rules.js +22 -0
  24. package/dist/engine/boot-validator/action-form-preview.d.ts +2 -0
  25. package/dist/engine/boot-validator/action-form-preview.js +54 -0
  26. package/dist/engine/boot-validator/boot-rules.d.ts +87 -1
  27. package/dist/engine/boot-validator/boot-rules.js +2 -0
  28. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  29. package/dist/engine/boot-validator/config-key-rules.d.ts +5 -0
  30. package/dist/engine/boot-validator/config-key-rules.js +5 -0
  31. package/dist/engine/boot-validator/date-only-after-days.d.ts +4 -0
  32. package/dist/engine/boot-validator/date-only-after-days.js +32 -0
  33. package/dist/engine/boot-validator/entity-handler.d.ts +1 -0
  34. package/dist/engine/boot-validator/entity-handler.js +1 -1
  35. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +40 -0
  36. package/dist/engine/boot-validator/list-bulk-actions-rules.js +40 -0
  37. package/dist/engine/boot-validator/list-bulk-actions.d.ts +2 -1
  38. package/dist/engine/boot-validator/list-bulk-actions.js +79 -9
  39. package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
  40. package/dist/engine/boot-validator/list-row-guidance.js +1 -0
  41. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  42. package/dist/engine/boot-validator/list-table-options.js +8 -6
  43. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  44. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  45. package/dist/engine/boot-validator/query-output-columns.js +29 -2
  46. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  47. package/dist/engine/boot-validator/query-refs.js +3 -0
  48. package/dist/engine/boot-validator/screens-actions.d.ts +7 -2
  49. package/dist/engine/boot-validator/screens-actions.js +4 -2
  50. package/dist/engine/boot-validator/screens-forms.js +2 -0
  51. package/dist/engine/boot-validator/screens-kind-entity-list.js +5 -3
  52. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
  53. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
  54. package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
  55. package/dist/engine/boot-validator/screens-kind-projection-list.js +2 -2
  56. package/dist/engine/boot-validator/screens-kind-shared.d.ts +1 -1
  57. package/dist/engine/boot-validator/screens-kind-shared.js +3 -1
  58. package/dist/engine/boot-validator/screens-lists-rules.d.ts +10 -0
  59. package/dist/engine/boot-validator/screens-lists-rules.js +10 -0
  60. package/dist/engine/boot-validator/screens-lists.js +13 -1
  61. package/dist/engine/boot-validator/screens.js +1 -2
  62. package/dist/engine/boot-validator/url-prefill-fields.js +8 -1
  63. package/dist/engine/boot-validator/zod-shape.d.ts +1 -0
  64. package/dist/engine/boot-validator/zod-shape.js +7 -0
  65. package/dist/engine/bridge-stub.js +1 -0
  66. package/dist/engine/build-config-feature-schema.js +30 -3
  67. package/dist/engine/screen-helpers.js +7 -3
  68. package/dist/engine/types/screen.d.ts +1 -1
  69. package/dist/engine/types/screen.js +1 -1
  70. package/dist/event-store/archive.d.ts +1 -0
  71. package/dist/event-store/archive.js +5 -1
  72. package/dist/event-store/event-store.d.ts +5 -0
  73. package/dist/event-store/event-store.js +23 -3
  74. package/dist/i18n/required-surface-keys.js +53 -13
  75. package/dist/pipeline/handler-context-events.js +15 -1
  76. package/dist/ui-types/card-column-roles.d.ts +3 -0
  77. package/dist/ui-types/card-column-roles.js +9 -5
  78. package/dist/ui-types/index.d.ts +1 -1
  79. package/package.json +3 -3
  80. package/src/changes.json +36 -0
@@ -1,5 +1,5 @@
1
1
  import { createPayloadDigest, createRateLimitResolver } from "../rate-limit/index.js";
2
- import { assertNoPayloadRateLimitsWithoutResolver, warnUnlimitedSystemScopeFeatures, } from "./server-boot-checks.js";
2
+ import { assertNoPayloadRateLimitsWithoutResolver, warnNonIpRateLimitsWithoutResolver, warnUnlimitedSystemScopeFeatures, } from "./server-boot-checks.js";
3
3
  export function resolveServerRateLimit(options, tracedRedis, bootLog) {
4
4
  // Auto-wire the rate-limit resolver, but ONLY when at least one
5
5
  // handler actually declared a rateLimit option. Apps that don't use
@@ -22,6 +22,7 @@ export function resolveServerRateLimit(options, tracedRedis, bootLog) {
22
22
  (tracedRedis && wantsResolver ? createRateLimitResolver({ redis: tracedRedis }) : undefined);
23
23
  if (!rateLimitResolver) {
24
24
  assertNoPayloadRateLimitsWithoutResolver(options.registry);
25
+ warnNonIpRateLimitsWithoutResolver(options.registry, bootLog);
25
26
  warnUnlimitedSystemScopeFeatures(options.registry, bootLog);
26
27
  }
27
28
  return { resolver: rateLimitResolver, middlewareRequested: wantsL1L2, payloadDigest };
@@ -30,6 +30,9 @@ export declare function insertFirstEventRow(db: AnyDb, params: FirstEventInsertP
30
30
  export declare function insertSubsequentEventRow(db: AnyDb, params: SubsequentEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
31
31
  export declare function selectStreamMaxVersion(db: AnyDb, aggregateId: string, tenantId: string): Promise<number>;
32
32
  export declare function selectStreamMaxVersions(db: AnyDb, aggregateIds: readonly string[], tenantId: string): Promise<Map<string, number>>;
33
+ /** Raw driver rows of the matching events (columns as in kumiko_events), ordered by the global id. */
34
+ export declare function selectEventRowsOfAggregatesByType(db: AnyDb, tenantId: string, aggregateIds: readonly string[], eventTypes: readonly string[]): Promise<readonly Record<string, unknown>[]>;
35
+ export declare function selectArchivedAggregateIdsOf(db: AnyDb, tenantId: string, aggregateIds: readonly string[]): Promise<readonly string[]>;
33
36
  /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
34
37
  export declare function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number>;
35
38
  export declare function selectEventsHighWaterMark(db: AnyDb): Promise<bigint>;
@@ -217,6 +217,18 @@ export async function selectStreamMaxVersions(db, aggregateIds, tenantId) {
217
217
  }
218
218
  return versions;
219
219
  }
220
+ /** Raw driver rows of the matching events (columns as in kumiko_events), ordered by the global id. */
221
+ export async function selectEventRowsOfAggregatesByType(db, tenantId, aggregateIds, eventTypes) {
222
+ if (aggregateIds.length === 0 || eventTypes.length === 0)
223
+ return [];
224
+ return unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[]) AND "type" = ANY($3::text[]) ORDER BY "id" ASC`, [tenantId, toPostgresArrayLiteral(aggregateIds), toPostgresArrayLiteral(eventTypes)]);
225
+ }
226
+ export async function selectArchivedAggregateIdsOf(db, tenantId, aggregateIds) {
227
+ if (aggregateIds.length === 0)
228
+ return [];
229
+ const rows = await unsafeReadRetrying(db, `SELECT "aggregate_id" FROM "kumiko_archived_streams" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[])`, [tenantId, toPostgresArrayLiteral(aggregateIds)]);
230
+ return rows.map((row) => row.aggregate_id);
231
+ }
220
232
  /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
221
233
  export async function selectAggregateMaxVersion(db, aggregateId) {
222
234
  const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]);
@@ -0,0 +1,22 @@
1
+ export declare const ACTION_FORM_PREVIEW_RULES: {
2
+ readonly fieldUnknown: {
3
+ readonly id: "action-form-preview/field-unknown";
4
+ readonly summary: "preview.fields names fields of the form.";
5
+ readonly fix: "Name an existing field of the form, or drop fields to send all of them.";
6
+ };
7
+ readonly labelMissing: {
8
+ readonly id: "action-form-preview/label-missing";
9
+ readonly summary: "Every preview fact and list column has a label.";
10
+ readonly fix: "Add label: the i18n key of the fact or column header.";
11
+ };
12
+ readonly listFieldMissing: {
13
+ readonly id: "action-form-preview/list-field-missing";
14
+ readonly summary: "preview.list names the result field of its rows and at least one column.";
15
+ readonly fix: "Set list.field to the array in the query result and list the columns to show.";
16
+ };
17
+ readonly empty: {
18
+ readonly id: "action-form-preview/empty";
19
+ readonly summary: "A preview shows facts or a list.";
20
+ readonly fix: "Add facts or list, or remove preview.";
21
+ };
22
+ };
@@ -0,0 +1,22 @@
1
+ export const ACTION_FORM_PREVIEW_RULES = {
2
+ fieldUnknown: {
3
+ id: "action-form-preview/field-unknown",
4
+ summary: "preview.fields names fields of the form.",
5
+ fix: "Name an existing field of the form, or drop fields to send all of them.",
6
+ },
7
+ labelMissing: {
8
+ id: "action-form-preview/label-missing",
9
+ summary: "Every preview fact and list column has a label.",
10
+ fix: "Add label: the i18n key of the fact or column header.",
11
+ },
12
+ listFieldMissing: {
13
+ id: "action-form-preview/list-field-missing",
14
+ summary: "preview.list names the result field of its rows and at least one column.",
15
+ fix: "Set list.field to the array in the query result and list the columns to show.",
16
+ },
17
+ empty: {
18
+ id: "action-form-preview/empty",
19
+ summary: "A preview shows facts or a list.",
20
+ fix: "Add facts or list, or remove preview.",
21
+ },
22
+ };
@@ -0,0 +1,2 @@
1
+ import type { ActionFormScreenDefinition } from "../types/screen.ts";
2
+ export declare function validateActionFormPreview(featureName: string, screenId: string, screen: ActionFormScreenDefinition, fieldNames: ReadonlySet<string>): void;
@@ -0,0 +1,54 @@
1
+ import { ACTION_FORM_PREVIEW_RULES } from "./action-form-preview-rules.js";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ function isBlank(value) {
4
+ return typeof value !== "string" || value === "";
5
+ }
6
+ function validateSentFields(where, preview, fieldNames) {
7
+ for (const field of preview.fields ?? []) {
8
+ if (fieldNames.has(field))
9
+ continue;
10
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.fieldUnknown, {
11
+ message: `${where} sends field "${field}", which the form does not declare. Form fields: ${[...fieldNames].sort().join(", ") || "(none)"}.`,
12
+ });
13
+ }
14
+ }
15
+ function validateFacts(where, facts) {
16
+ for (const fact of facts) {
17
+ if (!isBlank(fact.label))
18
+ continue;
19
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.labelMissing, {
20
+ message: `${where} fact "${fact.field}" needs label: the i18n key shown before the value.`,
21
+ });
22
+ }
23
+ }
24
+ function validateList(where, list) {
25
+ if (isBlank(list.field) || list.columns.length === 0) {
26
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.listFieldMissing, {
27
+ message: `${where} list needs field (the array in the query result) and at least one column.`,
28
+ });
29
+ }
30
+ for (const column of list.columns) {
31
+ if (!isBlank(column.label))
32
+ continue;
33
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.labelMissing, {
34
+ message: `${where} list column "${column.field}" needs label: the i18n key of its header.`,
35
+ });
36
+ }
37
+ }
38
+ export function validateActionFormPreview(featureName, screenId, screen, fieldNames) {
39
+ const { preview } = screen;
40
+ // skip: no preview declared
41
+ if (preview === undefined)
42
+ return;
43
+ const where = `[Feature ${featureName}] Screen "${screenId}" (actionForm) preview`;
44
+ validateSentFields(where, preview, fieldNames);
45
+ const facts = preview.facts ?? [];
46
+ if (facts.length === 0 && preview.list === undefined) {
47
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.empty, {
48
+ message: `${where} has neither facts nor list, so the panel would stay empty. Add facts: [{ field, label }] or list: { field, columns }.`,
49
+ });
50
+ }
51
+ validateFacts(where, facts);
52
+ if (preview.list !== undefined)
53
+ validateList(where, preview.list);
54
+ }
@@ -1364,6 +1364,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1364
1364
  readonly summary: "relatedList toolbarActions use visible instead of visibleWhen.";
1365
1365
  readonly fix: "Use visible, a condition on the enclosing record.";
1366
1366
  };
1367
+ readonly dateOnlyAfterDaysInvalid: {
1368
+ readonly id: "list/date-only-after-days-invalid";
1369
+ readonly summary: "A column's dateOnlyAfterDays is a non-negative whole number of days.";
1370
+ readonly fix: "Set dateOnlyAfterDays to 0 or a positive integer.";
1371
+ };
1372
+ readonly dateOnlyAfterDaysWrongType: {
1373
+ readonly id: "list/date-only-after-days-wrong-type";
1374
+ readonly summary: "dateOnlyAfterDays sits on a timestamp, locatedTimestamp or date column or a relativeTime column.";
1375
+ readonly fix: "Remove dateOnlyAfterDays from the column or point it at a timestamp, locatedTimestamp or date field.";
1376
+ };
1367
1377
  readonly columnSortableInert: {
1368
1378
  readonly id: "list/column-sortable-inert";
1369
1379
  readonly summary: "A column only sets sortable where the screen type honors it.";
@@ -1696,6 +1706,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1696
1706
  readonly summary: "Every rendered writeForm field has a fieldDefs entry.";
1697
1707
  readonly fix: "Add the field to fieldDefs.";
1698
1708
  };
1709
+ readonly submitWithInvalid: {
1710
+ readonly id: "projection-detail/submit-with-invalid";
1711
+ 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.";
1712
+ 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.";
1713
+ };
1714
+ readonly presentationOptionInvalid: {
1715
+ readonly id: "projection-detail/presentation-option-invalid";
1716
+ readonly summary: 'tabLabel and layout.narrowTabs need layout.mode "tabs"; hideOnNarrow and showOnNarrowOnly exclude each other on a section; photoGrid.badgeFirst needs badgeField.';
1717
+ readonly fix: "Use tabs mode for tabLabel/narrowTabs, set only one of hideOnNarrow/showOnNarrowOnly, and set badgeField next to badgeFirst.";
1718
+ };
1699
1719
  readonly wizardWriteForm: {
1700
1720
  readonly id: "projection-detail/wizard-write-form";
1701
1721
  readonly summary: "A wizard-mode layout has no writeForm section.";
@@ -2518,7 +2538,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2518
2538
  };
2519
2539
  readonly hiddenWithoutColumnPicker: {
2520
2540
  readonly id: "list-table/hidden-without-column-picker";
2521
- readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them.";
2541
+ readonly summary: "Hidden columns need table.columnPicker, otherwise the user can never show them; a hidden column that backs a facet is exempt.";
2522
2542
  readonly fix: "Set table: { columnPicker: true } or remove hidden from the column.";
2523
2543
  };
2524
2544
  readonly hidesEveryColumn: {
@@ -2875,6 +2895,67 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2875
2895
  readonly summary: "Bulk actions run one server write per row, so they point at writeHandler row actions.";
2876
2896
  readonly fix: "Point rowAction at a writeHandler row action.";
2877
2897
  };
2898
+ readonly formLabelMissing: {
2899
+ readonly id: "list-bulk/form-label-missing";
2900
+ readonly summary: "A bulk form action has a label (i18n key) for its button.";
2901
+ readonly fix: "Set label to an i18n key.";
2902
+ };
2903
+ readonly formScreenMissing: {
2904
+ readonly id: "list-bulk/form-screen-missing";
2905
+ readonly summary: "A bulk form action names the screen it opens in screen.";
2906
+ readonly fix: "Set screen to the id of an actionForm screen.";
2907
+ };
2908
+ readonly formScreenUnresolved: {
2909
+ readonly id: "list-bulk/form-screen-unresolved";
2910
+ readonly summary: "A bulk form action's screen resolves to a registered screen.";
2911
+ readonly fix: "Use the id of a screen in this feature or a fully-qualified <feature>:screen:<id>.";
2912
+ };
2913
+ readonly formScreenNotActionForm: {
2914
+ readonly id: "list-bulk/form-screen-not-action-form";
2915
+ readonly summary: "A bulk form action opens an actionForm screen.";
2916
+ readonly fix: "Point screen at an actionForm screen.";
2917
+ };
2918
+ readonly formIdsFieldMissing: {
2919
+ readonly id: "list-bulk/form-ids-field-missing";
2920
+ readonly summary: "A bulk form action names the form field that receives the selected ids.";
2921
+ readonly fix: "Set idsField to a field of the target form.";
2922
+ };
2923
+ readonly formIdsFieldUnknown: {
2924
+ readonly id: "list-bulk/form-ids-field-unknown";
2925
+ readonly summary: "A bulk form action's idsField is a field of the target form.";
2926
+ readonly fix: "Declare the field on the target form or point idsField at a declared one.";
2927
+ };
2928
+ readonly formIdsFieldNotList: {
2929
+ readonly id: "list-bulk/form-ids-field-not-list";
2930
+ readonly summary: 'A bulk form action\'s idsField is a multiSelect field with display: "count".';
2931
+ readonly fix: 'Declare the field as { type: "multiSelect", options: [], display: "count" } on the target form.';
2932
+ };
2933
+ readonly formIdsFieldNotRendered: {
2934
+ readonly id: "list-bulk/form-ids-field-not-rendered";
2935
+ readonly summary: "A bulk form action's idsField is shown by the target form's layout and not sensitive.";
2936
+ readonly fix: "Add the field to the form layout (visible: false hides it but keeps the value) and drop sensitive.";
2937
+ };
2938
+ }, {
2939
+ readonly fieldUnknown: {
2940
+ readonly id: "action-form-preview/field-unknown";
2941
+ readonly summary: "preview.fields names fields of the form.";
2942
+ readonly fix: "Name an existing field of the form, or drop fields to send all of them.";
2943
+ };
2944
+ readonly labelMissing: {
2945
+ readonly id: "action-form-preview/label-missing";
2946
+ readonly summary: "Every preview fact and list column has a label.";
2947
+ readonly fix: "Add label: the i18n key of the fact or column header.";
2948
+ };
2949
+ readonly listFieldMissing: {
2950
+ readonly id: "action-form-preview/list-field-missing";
2951
+ readonly summary: "preview.list names the result field of its rows and at least one column.";
2952
+ readonly fix: "Set list.field to the array in the query result and list the columns to show.";
2953
+ };
2954
+ readonly empty: {
2955
+ readonly id: "action-form-preview/empty";
2956
+ readonly summary: "A preview shows facts or a list.";
2957
+ readonly fix: "Add facts or list, or remove preview.";
2958
+ };
2878
2959
  }, {
2879
2960
  readonly notRegistered: {
2880
2961
  readonly id: "query/not-registered";
@@ -2968,6 +3049,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2968
3049
  readonly summary: "A config key that declares optionsQueryPayload also declares optionsQuery.";
2969
3050
  readonly fix: "Set optionsQuery or remove optionsQueryPayload.";
2970
3051
  };
3052
+ readonly maskReadOnlyRequired: {
3053
+ readonly id: "config-key/mask-read-only-required";
3054
+ readonly summary: "A config key is not both mask.readOnly and required, because nobody could fill it.";
3055
+ readonly fix: "Drop required or mask.readOnly.";
3056
+ };
2971
3057
  readonly optionsQueryEmpty: {
2972
3058
  readonly id: "config-key/options-query-empty";
2973
3059
  readonly summary: "A config key's optionsQuery is a non-empty query name when present.";
@@ -1,3 +1,4 @@
1
+ import { ACTION_FORM_PREVIEW_RULES } from "./action-form-preview-rules.js";
1
2
  import { AGENT_EFFECT_RULES } from "./agent-effect-rules.js";
2
3
  import { API_EXT_RULES } from "./api-ext-rules.js";
3
4
  import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
@@ -79,6 +80,7 @@ export const FRAMEWORK_BOOT_RULE_TABLES = [
79
80
  LIST_QUERY_RULES,
80
81
  LIST_SORT_SUMMARY_RULES,
81
82
  LIST_BULK_ACTION_RULES,
83
+ ACTION_FORM_PREVIEW_RULES,
82
84
  QUERY_RULES,
83
85
  BOOT_ENVIRONMENT_RULES,
84
86
  CONFIG_KEY_RULES,
@@ -29,11 +29,15 @@ function countOverflow(feature, screen, location, columns, storedTypeOf, entity)
29
29
  renderer: col.renderer,
30
30
  hideOnNarrow: col.hideOnNarrow,
31
31
  narrowInline: col.narrowInline,
32
+ cardBadge: col.cardBadge,
33
+ cardAbove: col.cardAbove,
32
34
  hint: col.hint,
35
+ emphasis: col.emphasis,
33
36
  ...(fileKind !== undefined && { fileDisplay: { kind: fileKind } }),
34
37
  };
35
38
  });
36
- const { meta } = cardColumnRoles(cardColumns);
39
+ // The card draws `cardAbove` columns above the title, not as meta lines.
40
+ const meta = cardColumnRoles(cardColumns).meta.filter((col) => col.cardAbove !== true);
37
41
  const lineCount = cardMetaLines(meta).length;
38
42
  if (lineCount <= CARD_META_MAX)
39
43
  return undefined;
@@ -44,6 +44,11 @@ export declare const CONFIG_KEY_RULES: {
44
44
  readonly summary: "A config key that declares optionsQueryPayload also declares optionsQuery.";
45
45
  readonly fix: "Set optionsQuery or remove optionsQueryPayload.";
46
46
  };
47
+ readonly maskReadOnlyRequired: {
48
+ readonly id: "config-key/mask-read-only-required";
49
+ readonly summary: "A config key is not both mask.readOnly and required, because nobody could fill it.";
50
+ readonly fix: "Drop required or mask.readOnly.";
51
+ };
47
52
  readonly optionsQueryEmpty: {
48
53
  readonly id: "config-key/options-query-empty";
49
54
  readonly summary: "A config key's optionsQuery is a non-empty query name when present.";
@@ -44,6 +44,11 @@ export const CONFIG_KEY_RULES = {
44
44
  summary: "A config key that declares optionsQueryPayload also declares optionsQuery.",
45
45
  fix: "Set optionsQuery or remove optionsQueryPayload.",
46
46
  },
47
+ maskReadOnlyRequired: {
48
+ id: "config-key/mask-read-only-required",
49
+ summary: "A config key is not both mask.readOnly and required, because nobody could fill it.",
50
+ fix: "Drop required or mask.readOnly.",
51
+ },
47
52
  optionsQueryEmpty: {
48
53
  id: "config-key/options-query-empty",
49
54
  summary: "A config key's optionsQuery is a non-empty query name when present.",
@@ -0,0 +1,4 @@
1
+ import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
2
+ import type { normalizeListColumn } from "../screen-helpers.ts";
3
+ export declare function entityColumnType(entity: EntityDefinition, field: string): string | undefined;
4
+ export declare function validateDateOnlyAfterDays(prefix: string, column: ReturnType<typeof normalizeListColumn>, entityType: string | undefined): void;
@@ -0,0 +1,32 @@
1
+ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
2
+ import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
3
+ import { bootRuleError } from "./boot-rule.js";
4
+ import { LIST_SCREEN_RULES } from "./screens-lists-rules.js";
5
+ const DATE_FIELD_TYPES = ["timestamp", "date", "locatedTimestamp"];
6
+ // Mirrors how the list view-model types a column: stored field, then derived field, then row meta.
7
+ export function entityColumnType(entity, field) {
8
+ return (entity.fields[field]?.type ??
9
+ entity.derivedFields?.[field]?.valueType ??
10
+ LIST_ROW_META_COLUMNS[field]);
11
+ }
12
+ // `entityType` is the column's type on a known entity; without one only the column's own
13
+ // `valueType` is known, and a column without any type information stays allowed.
14
+ export function validateDateOnlyAfterDays(prefix, column, entityType) {
15
+ const days = column.dateOnlyAfterDays;
16
+ if (days === undefined)
17
+ return;
18
+ const where = `${prefix} column "${column.field}"`;
19
+ if (!Number.isInteger(days) || days < 0) {
20
+ throw bootRuleError(LIST_SCREEN_RULES.dateOnlyAfterDaysInvalid, {
21
+ message: `${where} sets dateOnlyAfterDays to ${String(days)}, which is not a non-negative whole number of days. Use 0 or a positive integer.`,
22
+ });
23
+ }
24
+ if (propertyOf(column.renderer, "format") === "relativeTime")
25
+ return;
26
+ const type = entityType ?? column.valueType;
27
+ if (type === undefined || DATE_FIELD_TYPES.includes(type))
28
+ return;
29
+ throw bootRuleError(LIST_SCREEN_RULES.dateOnlyAfterDaysWrongType, {
30
+ message: `${where} sets dateOnlyAfterDays on a ${type} column. It only applies to timestamp, locatedTimestamp or date fields and relativeTime columns; remove it.`,
31
+ });
32
+ }
@@ -7,6 +7,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
7
7
  /** Extensions with preSave must target an entity that has mapped write handlers. */
8
8
  export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
9
9
  export declare function validateHandlerAccess(feature: FeatureDefinition): void;
10
+ export declare const IP_BUCKETED_RATE_LIMIT_PER: ReadonlySet<string>;
10
11
  export declare function validateAdditionalRateLimits(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
11
12
  export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
12
13
  export declare function validateRateLimitCost(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
@@ -157,7 +157,7 @@ export function validateHandlerAccess(feature) {
157
157
  validateAgentProposalEffect(feature.name, "query", name, handler.agent);
158
158
  }
159
159
  }
160
- const IP_BUCKETED_RATE_LIMIT_PER = new Set(["ip", "ip+handler"]);
160
+ export const IP_BUCKETED_RATE_LIMIT_PER = new Set(["ip", "ip+handler"]);
161
161
  // Payload buckets only complement the per-IP bucket: an anonymous caller
162
162
  // who rotates IPs is what they exist for, and without the IP bucket a single
163
163
  // IP could still burn through unlimited distinct addresses.
@@ -39,4 +39,44 @@ export declare const LIST_BULK_ACTION_RULES: {
39
39
  readonly summary: "Bulk actions run one server write per row, so they point at writeHandler row actions.";
40
40
  readonly fix: "Point rowAction at a writeHandler row action.";
41
41
  };
42
+ readonly formLabelMissing: {
43
+ readonly id: "list-bulk/form-label-missing";
44
+ readonly summary: "A bulk form action has a label (i18n key) for its button.";
45
+ readonly fix: "Set label to an i18n key.";
46
+ };
47
+ readonly formScreenMissing: {
48
+ readonly id: "list-bulk/form-screen-missing";
49
+ readonly summary: "A bulk form action names the screen it opens in screen.";
50
+ readonly fix: "Set screen to the id of an actionForm screen.";
51
+ };
52
+ readonly formScreenUnresolved: {
53
+ readonly id: "list-bulk/form-screen-unresolved";
54
+ readonly summary: "A bulk form action's screen resolves to a registered screen.";
55
+ readonly fix: "Use the id of a screen in this feature or a fully-qualified <feature>:screen:<id>.";
56
+ };
57
+ readonly formScreenNotActionForm: {
58
+ readonly id: "list-bulk/form-screen-not-action-form";
59
+ readonly summary: "A bulk form action opens an actionForm screen.";
60
+ readonly fix: "Point screen at an actionForm screen.";
61
+ };
62
+ readonly formIdsFieldMissing: {
63
+ readonly id: "list-bulk/form-ids-field-missing";
64
+ readonly summary: "A bulk form action names the form field that receives the selected ids.";
65
+ readonly fix: "Set idsField to a field of the target form.";
66
+ };
67
+ readonly formIdsFieldUnknown: {
68
+ readonly id: "list-bulk/form-ids-field-unknown";
69
+ readonly summary: "A bulk form action's idsField is a field of the target form.";
70
+ readonly fix: "Declare the field on the target form or point idsField at a declared one.";
71
+ };
72
+ readonly formIdsFieldNotList: {
73
+ readonly id: "list-bulk/form-ids-field-not-list";
74
+ readonly summary: 'A bulk form action\'s idsField is a multiSelect field with display: "count".';
75
+ readonly fix: 'Declare the field as { type: "multiSelect", options: [], display: "count" } on the target form.';
76
+ };
77
+ readonly formIdsFieldNotRendered: {
78
+ readonly id: "list-bulk/form-ids-field-not-rendered";
79
+ readonly summary: "A bulk form action's idsField is shown by the target form's layout and not sensitive.";
80
+ readonly fix: "Add the field to the form layout (visible: false hides it but keeps the value) and drop sensitive.";
81
+ };
42
82
  };
@@ -39,4 +39,44 @@ export const LIST_BULK_ACTION_RULES = {
39
39
  summary: "Bulk actions run one server write per row, so they point at writeHandler row actions.",
40
40
  fix: "Point rowAction at a writeHandler row action.",
41
41
  },
42
+ formLabelMissing: {
43
+ id: "list-bulk/form-label-missing",
44
+ summary: "A bulk form action has a label (i18n key) for its button.",
45
+ fix: "Set label to an i18n key.",
46
+ },
47
+ formScreenMissing: {
48
+ id: "list-bulk/form-screen-missing",
49
+ summary: "A bulk form action names the screen it opens in screen.",
50
+ fix: "Set screen to the id of an actionForm screen.",
51
+ },
52
+ formScreenUnresolved: {
53
+ id: "list-bulk/form-screen-unresolved",
54
+ summary: "A bulk form action's screen resolves to a registered screen.",
55
+ fix: "Use the id of a screen in this feature or a fully-qualified <feature>:screen:<id>.",
56
+ },
57
+ formScreenNotActionForm: {
58
+ id: "list-bulk/form-screen-not-action-form",
59
+ summary: "A bulk form action opens an actionForm screen.",
60
+ fix: "Point screen at an actionForm screen.",
61
+ },
62
+ formIdsFieldMissing: {
63
+ id: "list-bulk/form-ids-field-missing",
64
+ summary: "A bulk form action names the form field that receives the selected ids.",
65
+ fix: "Set idsField to a field of the target form.",
66
+ },
67
+ formIdsFieldUnknown: {
68
+ id: "list-bulk/form-ids-field-unknown",
69
+ summary: "A bulk form action's idsField is a field of the target form.",
70
+ fix: "Declare the field on the target form or point idsField at a declared one.",
71
+ },
72
+ formIdsFieldNotList: {
73
+ id: "list-bulk/form-ids-field-not-list",
74
+ summary: 'A bulk form action\'s idsField is a multiSelect field with display: "count".',
75
+ fix: 'Declare the field as { type: "multiSelect", options: [], display: "count" } on the target form.',
76
+ },
77
+ formIdsFieldNotRendered: {
78
+ id: "list-bulk/form-ids-field-not-rendered",
79
+ summary: "A bulk form action's idsField is shown by the target form's layout and not sensitive.",
80
+ fix: "Add the field to the form layout (visible: false hides it but keeps the value) and drop sensitive.",
81
+ },
42
82
  };
@@ -1,3 +1,4 @@
1
1
  import { type RowAction } from "../types/screen.ts";
2
+ import { type NavigateTargetLookups } from "./screens-actions.ts";
2
3
  /** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
3
- export declare function validateListBulkActions(where: string, bulkActions: unknown, rowActions: readonly RowAction[] | undefined): void;
4
+ export declare function validateListBulkActions(where: string, bulkActions: unknown, rowActions: readonly RowAction[] | undefined, featureName: string, lookups: NavigateTargetLookups): void;
@@ -1,8 +1,9 @@
1
1
  import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
2
2
  import { isKebabSegment } from "../qualified-name.js";
3
- import { LIST_BULK_ACTION_KEYS } from "../types/screen.js";
3
+ import { LIST_BULK_ACTION_KEYS, LIST_BULK_FORM_ACTION_KEYS, } from "../types/screen.js";
4
4
  import { bootRuleError } from "./boot-rule.js";
5
5
  import { LIST_BULK_ACTION_RULES } from "./list-bulk-actions-rules.js";
6
+ import { findNavTargetEntry, isSensitiveOrPasswordField, renderedEditFieldNames, } from "./screens-actions.js";
6
7
  function validateBulkActionTarget(where, bulkId, target, rowActions) {
7
8
  if (typeof target !== "string" || target === "") {
8
9
  throw bootRuleError(LIST_BULK_ACTION_RULES.rowActionMissing, {
@@ -24,8 +25,73 @@ function validateBulkActionTarget(where, bulkId, target, rowActions) {
24
25
  });
25
26
  }
26
27
  }
28
+ function resolveBulkFormScreen(where, bulkId, entry, featureName, lookups) {
29
+ const label = entry["label"];
30
+ if (typeof label !== "string" || label === "") {
31
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formLabelMissing, {
32
+ message: `${where} bulk action "${bulkId}" needs label: the i18n key of its button.`,
33
+ });
34
+ }
35
+ const screenId = entry["screen"];
36
+ if (typeof screenId !== "string" || screenId === "") {
37
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formScreenMissing, {
38
+ message: `${where} bulk action "${bulkId}" needs screen: the id of an actionForm screen.`,
39
+ });
40
+ }
41
+ const target = findNavTargetEntry({ name: featureName }, screenId, lookups);
42
+ if (target === undefined) {
43
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formScreenUnresolved, {
44
+ message: `${where} bulk action "${bulkId}" opens screen "${screenId}", which does not resolve to a ` +
45
+ `registered screen. Use the id of a screen in this feature or <feature>:screen:<id>.`,
46
+ });
47
+ }
48
+ const form = target.screen;
49
+ if (form.type !== "actionForm") {
50
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formScreenNotActionForm, {
51
+ message: `${where} bulk action "${bulkId}" opens screen "${screenId}", a "${form.type}" screen. ` +
52
+ `Point screen at an actionForm screen; it receives the selected ids in idsField.`,
53
+ });
54
+ }
55
+ return { screenId, form };
56
+ }
57
+ function validateBulkIdsField(where, bulkId, entry, screenId, form) {
58
+ const idsField = entry["idsField"];
59
+ if (typeof idsField !== "string" || idsField === "") {
60
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formIdsFieldMissing, {
61
+ message: `${where} bulk action "${bulkId}" needs idsField: the field of form "${screenId}" that ` +
62
+ `receives the selected ids.`,
63
+ });
64
+ }
65
+ const field = Object.hasOwn(form.fields, idsField) ? form.fields[idsField] : undefined;
66
+ if (field === undefined) {
67
+ const known = Object.keys(form.fields).sort().join(", ") || "(none)";
68
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formIdsFieldUnknown, {
69
+ message: `${where} bulk action "${bulkId}" has idsField "${idsField}", which form "${screenId}" does ` +
70
+ `not declare. Form fields: ${known}.`,
71
+ });
72
+ }
73
+ if (field.type !== "multiSelect" || field.display !== "count") {
74
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formIdsFieldNotList, {
75
+ message: `${where} bulk action "${bulkId}" has idsField "${idsField}", which is not a list field. ` +
76
+ `Declare it on form "${screenId}" as { type: "multiSelect", options: [], display: "count" }; ` +
77
+ `the handler then receives the ids as a string array.`,
78
+ });
79
+ }
80
+ if (isSensitiveOrPasswordField(field) ||
81
+ !renderedEditFieldNames(form.layout.sections).has(idsField)) {
82
+ throw bootRuleError(LIST_BULK_ACTION_RULES.formIdsFieldNotRendered, {
83
+ message: `${where} bulk action "${bulkId}" has idsField "${idsField}", which form "${screenId}" ` +
84
+ `marks sensitive or leaves out of its layout; the renderer would drop the ids. Add the ` +
85
+ `field to the layout (visible: false still carries the value) and remove sensitive.`,
86
+ });
87
+ }
88
+ }
89
+ function validateBulkFormTarget(where, bulkId, entry, featureName, lookups) {
90
+ const { screenId, form } = resolveBulkFormScreen(where, bulkId, entry, featureName, lookups);
91
+ validateBulkIdsField(where, bulkId, entry, screenId, form);
92
+ }
27
93
  /** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
28
- export function validateListBulkActions(where, bulkActions, rowActions) {
94
+ export function validateListBulkActions(where, bulkActions, rowActions, featureName, lookups) {
29
95
  // skip: no bulk actions declared
30
96
  if (bulkActions === undefined)
31
97
  return;
@@ -38,7 +104,7 @@ export function validateListBulkActions(where, bulkActions, rowActions) {
38
104
  for (const entry of bulkActions) {
39
105
  if (!isPlainObject(entry)) {
40
106
  throw bootRuleError(LIST_BULK_ACTION_RULES.entryNotObject, {
41
- message: `${where} bulkActions entries must be objects with id and rowAction.`,
107
+ message: `${where} bulkActions entries must be objects with id and rowAction, or id, label, screen and idsField.`,
42
108
  });
43
109
  }
44
110
  const id = entry["id"];
@@ -52,16 +118,20 @@ export function validateListBulkActions(where, bulkActions, rowActions) {
52
118
  message: `${where} declares bulk action "${id}" twice.`,
53
119
  });
54
120
  seen.add(id);
55
- const unknown = Object.keys(entry).filter((key) => !isOneOfBulkKeys(key));
121
+ const opensForm = Object.hasOwn(entry, "screen");
122
+ const allowedKeys = opensForm
123
+ ? LIST_BULK_FORM_ACTION_KEYS
124
+ : LIST_BULK_ACTION_KEYS;
125
+ const unknown = Object.keys(entry).filter((key) => !allowedKeys.includes(key));
56
126
  if (unknown.length > 0) {
57
127
  throw bootRuleError(LIST_BULK_ACTION_RULES.unknownKey, {
58
128
  message: `${where} bulk action "${id}" has unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")}. ` +
59
- `Allowed keys: ${LIST_BULK_ACTION_KEYS.join(", ")}.`,
129
+ `Allowed keys: ${allowedKeys.join(", ")}.`,
60
130
  });
61
131
  }
62
- validateBulkActionTarget(where, id, entry["rowAction"], rowActions ?? []);
132
+ if (opensForm)
133
+ validateBulkFormTarget(where, id, entry, featureName, lookups);
134
+ else
135
+ validateBulkActionTarget(where, id, entry["rowAction"], rowActions ?? []);
63
136
  }
64
137
  }
65
- function isOneOfBulkKeys(key) {
66
- return LIST_BULK_ACTION_KEYS.some((allowed) => allowed === key);
67
- }
@@ -20,6 +20,7 @@ export declare function validatePhotoGrid(where: string, section: {
20
20
  readonly photoGrid?: {
21
21
  readonly imageField: string;
22
22
  readonly captionField?: string;
23
+ readonly badgeField?: string;
23
24
  };
24
25
  }): void;
25
26
  type GuidanceListKind = "entityList" | "projectionList" | "dashboard" | "relatedList";
@@ -69,6 +69,7 @@ export function validatePhotoGrid(where, section) {
69
69
  for (const [option, field] of [
70
70
  ["imageField", photoGrid.imageField],
71
71
  ["captionField", photoGrid.captionField],
72
+ ["badgeField", photoGrid.badgeField],
72
73
  ]) {
73
74
  if (field === undefined || columnFields.has(field))
74
75
  continue;
@@ -1,3 +1,3 @@
1
1
  import { type ListColumnSpec } from "../types/screen.ts";
2
2
  /** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
3
- export declare function validateListTableOptions(where: string, table: unknown, columns: readonly ListColumnSpec[], exportAllowed?: boolean): void;
3
+ export declare function validateListTableOptions(where: string, table: unknown, columns: readonly ListColumnSpec[], exportAllowed?: boolean, facetFields?: readonly string[]): void;