@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
@@ -16,6 +16,8 @@
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 { bootRuleError } from "./boot-validator/boot-rule.js";
20
+ import { CONFIG_KEY_RULES } from "./boot-validator/config-key-rules.js";
19
21
  import { rolesToAccess, unionAccessRules } from "./config-access-rules.js";
20
22
  import { isEncryptedAtRest } from "./config-helpers.js";
21
23
  import { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
@@ -681,7 +683,29 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
681
683
  if (k.def.required === true)
682
684
  requiredFields.push(id);
683
685
  }
684
- const { section, screenDescription } = buildSettingsSection(feature, scope, keys.map((k) => k.def.mask?.readOnly === true ? { field: fieldId(k), readOnly: true } : fieldId(k)), hub, options);
686
+ const specOf = (k) => k.def.mask?.readOnly === true ? { field: fieldId(k), readOnly: true } : fieldId(k);
687
+ const plainKeys = keys.filter((k) => k.def.mask?.section === undefined);
688
+ const { section, screenDescription } = buildSettingsSection(feature, scope, plainKeys.map(specOf), hub, options);
689
+ const sectionTitles = [
690
+ ...new Set(keys.flatMap((k) => (k.def.mask?.section === undefined ? [] : [k.def.mask.section]))),
691
+ ];
692
+ const titledSections = sectionTitles.map((title) => ({
693
+ title,
694
+ fields: keys.filter((k) => k.def.mask?.section === title).map(specOf),
695
+ }));
696
+ // Every key sectioned: the base section is gone, its description moves to the first generated one.
697
+ const [firstTitled, ...otherTitled] = titledSections;
698
+ const sections = plainKeys.length > 0
699
+ ? [section, ...titledSections]
700
+ : firstTitled === undefined
701
+ ? []
702
+ : [
703
+ {
704
+ ...firstTitled,
705
+ ...(section.description !== undefined && { description: section.description }),
706
+ },
707
+ ...otherTitled,
708
+ ];
685
709
  return {
686
710
  id: shortId,
687
711
  type: "configEdit",
@@ -689,10 +713,11 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
689
713
  configKeys,
690
714
  fields,
691
715
  fieldLabels,
716
+ ...(keys.some((k) => k.def.mask?.compact === true) && { compact: true }),
692
717
  ...(Object.keys(fieldDescriptions).length > 0 && { fieldDescriptions }),
693
718
  ...(requiredFields.length > 0 && { requiredFields }),
694
719
  ...(screenDescription !== undefined && { description: screenDescription }),
695
- layout: { sections: [section], width: "full", variant: "settings-list" },
720
+ layout: { sections, width: "full", variant: "settings-list" },
696
721
  access,
697
722
  };
698
723
  }
@@ -810,7 +835,9 @@ function collectMaskedKeys(registry) {
810
835
  throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`);
811
836
  }
812
837
  if (def.mask?.readOnly === true && def.required === true) {
813
- throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" is mask.readOnly and required — nobody could fill it.`);
838
+ throw bootRuleError(CONFIG_KEY_RULES.maskReadOnlyRequired, {
839
+ message: `[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" is mask.readOnly and required — nobody could fill it.`,
840
+ });
814
841
  }
815
842
  // computed keys derive their value — there is no row to set, so a
816
843
  // configEdit screen could not write them. Skip even when masked.
@@ -32,11 +32,15 @@ export function resolveNavParentScreen(screens, detail, getId) {
32
32
  ? screens.find((s) => screenShortId(getId(s)) === screenShortId(explicitId))
33
33
  : undefined;
34
34
  })();
35
- // rowActions, toolbarActions, and drawer-kind actions (which mount inline
36
- // and have no page of their own) all count as "reached from" this list.
35
+ // rowActions, toolbarActions, the `actions` of a record screen, and drawer-kind actions (which
36
+ // mount inline and have no page of their own) all count as "reached from" that screen.
37
37
  const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") &&
38
38
  a.screen !== undefined &&
39
39
  screenShortId(a.screen) === detailScreenId);
40
+ // A form opened only from a record screen (e.g. a status dialog) has that record as its parent.
41
+ const recordFromAction = screens.find((s) => (s.type === "projectionDetail" || s.type === "entityEdit") &&
42
+ screenShortId(getId(s)) !== detailScreenId &&
43
+ navigatesToDetail(s.actions));
40
44
  // The create button of an entityList navigates to its createScreen, so the
41
45
  // list is that screen's parent just like for a rowAction target.
42
46
  const listFromRowAction = screens.find((s) => {
@@ -51,7 +55,7 @@ export function resolveNavParentScreen(screens, detail, getId) {
51
55
  const listFromEntity = detail.type === "entityEdit"
52
56
  ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
53
57
  : undefined;
54
- return listFromExplicit ?? listFromRowAction ?? listFromEntity;
58
+ return listFromExplicit ?? listFromRowAction ?? recordFromAction ?? listFromEntity;
55
59
  }
56
60
  // Shared by boot-validators that walk the EditLayout shape (entityEdit's
57
61
  // layout, reused verbatim by projectionDetail/actionForm/configEdit/secretMint).
@@ -1,2 +1,2 @@
1
1
  export type * from "@cosmicdrift/kumiko-types/screen";
2
- export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_FRAMES, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_SUMMARY_ROW_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
2
+ export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_BULK_FORM_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_FRAMES, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_SUMMARY_ROW_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
@@ -1 +1 @@
1
- export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_FRAMES, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_SUMMARY_ROW_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
1
+ export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_BULK_FORM_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_FRAMES, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_SUMMARY_ROW_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
@@ -11,4 +11,5 @@ export type ArchiveStreamArgs = {
11
11
  };
12
12
  export declare function archiveStream(db: DbRunner, args: ArchiveStreamArgs): Promise<void>;
13
13
  export declare function isStreamArchived(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<boolean>;
14
+ export declare function selectArchivedAggregateIds(db: DbRunner, tenantId: TenantId, aggregateIds: readonly string[]): Promise<ReadonlySet<string>>;
14
15
  export declare function restoreStream(db: DbRunner, tenantId: TenantId, aggregateId: string): Promise<void>;
@@ -1,6 +1,6 @@
1
1
  // sql now comes from native dialect
2
2
  import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/dialect.js";
3
- import { upsertArchivedStream } from "../db/queries/event-store.js";
3
+ import { selectArchivedAggregateIdsOf, upsertArchivedStream } from "../db/queries/event-store.js";
4
4
  import { deleteMany, fetchOne } from "../db/query.js";
5
5
  import { tableExists } from "../db/schema-inspection.js";
6
6
  import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
@@ -48,6 +48,10 @@ export async function isStreamArchived(db, tenantId, aggregateId) {
48
48
  const row = await fetchOne(db, archivedStreamsTable, { tenantId, aggregateId });
49
49
  return row !== undefined;
50
50
  }
51
+ // One query for a whole page of aggregates instead of one isStreamArchived probe each.
52
+ export async function selectArchivedAggregateIds(db, tenantId, aggregateIds) {
53
+ return new Set(await selectArchivedAggregateIdsOf(db, tenantId, aggregateIds));
54
+ }
51
55
  // Undo an archive — restores the stream to writable state. Ops tool. The
52
56
  // historical archivedAt is lost; if auditing needs the archive-history,
53
57
  // use domain events on the aggregate (e.g. "stream.archived" / "stream.
@@ -21,6 +21,11 @@ export declare function loadAggregate(db: DbRunner, aggregateId: string, tenantI
21
21
  readonly aggregateType?: string;
22
22
  readonly atVersion?: number;
23
23
  }): Promise<readonly StoredEvent[]>;
24
+ export declare function loadEventsOfAggregatesByType(db: DbRunner, tenantId: TenantId, args: {
25
+ readonly aggregateIds: readonly string[];
26
+ readonly eventTypes: readonly string[];
27
+ readonly includeArchived?: boolean;
28
+ }): Promise<readonly StoredEvent[]>;
24
29
  export declare function loadAggregateForWriting(db: DbRunner, aggregateId: string, tenantId: TenantId, options: {
25
30
  readonly aggregateType: string;
26
31
  }): Promise<{
@@ -5,9 +5,10 @@ import { requestContext } from "../api/request-context.js";
5
5
  import { encryptEventPayloadPii } from "../crypto/event-pii.js";
6
6
  import { instantToTimestamptzParam } from "../db/driver-value-preparation.js";
7
7
  import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
8
- import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
9
- import { selectMany } from "../db/query.js";
10
- import { isStreamArchived } from "./archive.js";
8
+ import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventRowsOfAggregatesByType, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
9
+ import { coerceRow, selectMany } from "../db/query.js";
10
+ import { extractTableInfo } from "../db/table-info.js";
11
+ import { isStreamArchived, selectArchivedAggregateIds } from "./archive.js";
11
12
  import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
12
13
  import { eventsTable } from "./events-schema.js";
13
14
  import { toStoredEvent } from "./row-to-stored-event.js";
@@ -224,6 +225,25 @@ export async function loadAggregate(db, aggregateId, tenantId, options) {
224
225
  return rows.map(toStoredEvent);
225
226
  });
226
227
  }
228
+ // Events of several aggregates filtered by event type in one query, so a list page does not
229
+ // load every stream (N+1). Ordered by the global id: within one aggregate that is version order.
230
+ // Archived streams are left out unless includeArchived, as in loadAggregate.
231
+ export async function loadEventsOfAggregatesByType(db, tenantId, args) {
232
+ const { aggregateIds, eventTypes, includeArchived } = args;
233
+ if (aggregateIds.length === 0 || eventTypes.length === 0)
234
+ return [];
235
+ return inEventStreamScope(tenantId, async () => {
236
+ const archivedIds = includeArchived
237
+ ? new Set()
238
+ : await selectArchivedAggregateIds(db, tenantId, aggregateIds);
239
+ const rawRows = await selectEventRowsOfAggregatesByType(db, tenantId, aggregateIds, eventTypes);
240
+ const info = extractTableInfo(eventsTable);
241
+ return rawRows
242
+ .map((raw) => coerceRow(raw, info))
243
+ .filter((row) => !archivedIds.has(row.aggregateId))
244
+ .map(toStoredEvent);
245
+ });
246
+ }
227
247
  // Events and the stream's latest version from ONE read, so both come from the same
228
248
  // snapshot: a commit landing between two separate statements would leave the caller
229
249
  // pinning a version its loaded events never covered. The aggregateType filter is applied
@@ -58,6 +58,12 @@ function pushKey(out, value, treatAsKey = false) {
58
58
  if (value !== undefined && (treatAsKey || isI18nKey(value)))
59
59
  out.add(value);
60
60
  }
61
+ function pushBulkActionKeys(out, bulk) {
62
+ if ("screen" in bulk)
63
+ pushKey(out, bulk.label);
64
+ else
65
+ pushKey(out, bulk.confirm);
66
+ }
61
67
  function editFieldName(f) {
62
68
  return typeof f === "string" ? f : f.field;
63
69
  }
@@ -279,7 +285,7 @@ function pushListChromeKeys(out, list) {
279
285
  for (const action of list.toolbarActions ?? [])
280
286
  pushToolbarActionKeys(out, action);
281
287
  for (const bulk of list.bulkActions ?? [])
282
- pushKey(out, bulk.confirm);
288
+ pushBulkActionKeys(out, bulk);
283
289
  }
284
290
  function collectEntityListKeys(ctx, list) {
285
291
  for (const col of list.columns) {
@@ -325,6 +331,13 @@ function collectEntityEditKeys(ctx, edit) {
325
331
  pushKey(ctx.out, edit.titleTemplate);
326
332
  pushEditLayoutSectionKeys(ctx, edit.layout.sections, edit.entity, edit.fieldLabels);
327
333
  }
334
+ function pushPreviewKeys(ctx, preview) {
335
+ pushKey(ctx.out, preview?.title);
336
+ for (const fact of preview?.facts ?? [])
337
+ pushKey(ctx.out, fact.label);
338
+ for (const column of preview?.list?.columns ?? [])
339
+ pushKey(ctx.out, column.label);
340
+ }
328
341
  function collectActionFormKeys(ctx, form) {
329
342
  pushKey(ctx.out, form.submitLabel);
330
343
  pushKey(ctx.out, form.summary?.title);
@@ -341,6 +354,7 @@ function collectActionFormKeys(ctx, form) {
341
354
  pushKey(ctx.out, link.label);
342
355
  for (const fact of form.successFacts ?? [])
343
356
  pushKey(ctx.out, fact.label);
357
+ pushPreviewKeys(ctx, form.preview);
344
358
  pushKey(ctx.out, form.successItems?.link?.label);
345
359
  for (const fieldName of Object.keys(form.fields)) {
346
360
  pushFieldLabelOrOverrideKey(ctx, ACTION_FORM_ENTITY, fieldName, form.fieldLabels);
@@ -415,6 +429,12 @@ function pushWriteFormSectionKeys(ctx, section) {
415
429
  function collectProjectionDetailKeys(ctx, detail) {
416
430
  for (const metric of detail.metrics ?? [])
417
431
  pushKey(ctx.out, metric.label);
432
+ pushKey(ctx.out, detail.header?.narrowTitle);
433
+ for (const section of detail.layout.sections) {
434
+ pushKey(ctx.out, section.tabLabel);
435
+ if ("descriptionNarrow" in section)
436
+ pushKey(ctx.out, section.descriptionNarrow);
437
+ }
418
438
  pushDetailGuidanceKeys(detail, (value) => pushKey(ctx.out, value), (action) => pushRowActionKeys(ctx.out, action));
419
439
  for (const section of detail.layout.sections) {
420
440
  if (isExtensionEditSection(section)) {
@@ -424,7 +444,7 @@ function collectProjectionDetailKeys(ctx, detail) {
424
444
  if (section.kind === "relatedList") {
425
445
  pushRelatedListSectionKeys(ctx.out, section);
426
446
  for (const bulk of section.bulkActions ?? [])
427
- pushKey(ctx.out, bulk.confirm);
447
+ pushBulkActionKeys(ctx.out, bulk);
428
448
  continue;
429
449
  }
430
450
  if (section.kind === "stepList") {
@@ -587,6 +607,7 @@ export function findTranslationLocaleGaps(features) {
587
607
  return gaps;
588
608
  }
589
609
  const LOCALE_PACKAGE_PREFIX = "locale-";
610
+ const PLURAL_FORM_NAMES = ["zero", "one", "two", "few", "many", "other"];
590
611
  function collectLocalesByName(features) {
591
612
  // A plain key of a regular feature is only its own; registering it raw would let two
592
613
  // features with the same plain key cover each other's missing locales.
@@ -594,20 +615,42 @@ function collectLocalesByName(features) {
594
615
  ? [`${featureName}:${key}`, key]
595
616
  : [`${featureName}:${key}`];
596
617
  const localesByName = new Map();
618
+ const blankLocalesByName = new Map();
619
+ const addAll = (target, name, locales) => {
620
+ const set = target.get(name) ?? new Set();
621
+ for (const locale of locales)
622
+ set.add(locale);
623
+ target.set(name, set);
624
+ };
597
625
  for (const feature of features) {
598
626
  for (const [key, byLocale] of Object.entries(feature.translations ?? {})) {
599
- const present = Object.entries(byLocale)
627
+ const entries = Object.entries(byLocale);
628
+ const present = entries
600
629
  .filter(([, value]) => hasLocaleValue(value))
601
630
  .map(([locale]) => locale);
631
+ const blank = entries.filter(([, value]) => !hasLocaleValue(value)).map(([locale]) => locale);
602
632
  for (const name of namesOf(feature.name, key)) {
603
- const locales = localesByName.get(name) ?? new Set();
604
- for (const locale of present)
605
- locales.add(locale);
606
- localesByName.set(name, locales);
633
+ addAll(localesByName, name, present);
634
+ addAll(blankLocalesByName, name, blank);
635
+ }
636
+ }
637
+ }
638
+ return { localesByName, blankLocalesByName };
639
+ }
640
+ function presentLocalesForKey(effective, key, localesByName, blankLocalesByName) {
641
+ // Locale packages spell plurals as flat `.one`/`.other` keys; `other` is the form every locale has.
642
+ const present = new Set([effective, key, `${effective}.other`, `${key}.other`].flatMap((name) => [
643
+ ...(localesByName.get(name) ?? []),
644
+ ]));
645
+ // A blank flat form (`.one`) leaves the plural incomplete even when `.other` is filled.
646
+ for (const name of [effective, key]) {
647
+ for (const form of PLURAL_FORM_NAMES) {
648
+ for (const locale of blankLocalesByName.get(`${name}.${form}`) ?? []) {
649
+ present.delete(locale);
607
650
  }
608
651
  }
609
652
  }
610
- return localesByName;
653
+ return present;
611
654
  }
612
655
  /**
613
656
  * Per translation key, the union of locales over ALL features must cover
@@ -621,7 +664,7 @@ function collectLocalesByName(features) {
621
664
  */
622
665
  export function findRequiredLocaleGaps(features, requiredLocales) {
623
666
  const featureNames = new Set(features.map((feature) => feature.name));
624
- const localesByName = collectLocalesByName(features);
667
+ const { localesByName, blankLocalesByName } = collectLocalesByName(features);
625
668
  const gaps = [];
626
669
  const reported = new Set();
627
670
  for (const feature of features) {
@@ -635,10 +678,7 @@ export function findRequiredLocaleGaps(features, requiredLocales) {
635
678
  const effective = key.includes(":") ? key : `${feature.name}:${key}`;
636
679
  if (reported.has(effective))
637
680
  continue;
638
- // Locale packages spell plurals as flat `.one`/`.other` keys; `other` is the form every locale has.
639
- const present = new Set([effective, key, `${effective}.other`, `${key}.other`].flatMap((name) => [
640
- ...(localesByName.get(name) ?? []),
641
- ]));
681
+ const present = presentLocalesForKey(effective, key, localesByName, blankLocalesByName);
642
682
  const missingLocales = requiredLocales.filter((locale) => !present.has(locale));
643
683
  if (missingLocales.length > 0) {
644
684
  reported.add(effective);
@@ -3,7 +3,7 @@ import { InternalError, VersionConflictError } from "../errors/index.js";
3
3
  import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
4
4
  import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
5
5
  import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
6
- import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
6
+ import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, loadEventsOfAggregatesByType, } from "../event-store/event-store.js";
7
7
  import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
8
8
  import { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
9
9
  import { appendDomainEventCore } from "./append-event-core.js";
@@ -120,6 +120,19 @@ export async function loadUpcastedAggregate(source, aggregateId, loadOptions) {
120
120
  });
121
121
  return upcastStoredEvents(events, registry.getEventUpcasters(), makeUpcastCtx(db, tenantId));
122
122
  }
123
+ /** Upcasters keep the event type, so the SQL type filter stays valid after upcasting. */
124
+ async function loadUpcastedEventsByTypes(source, args) {
125
+ const { db, registry, tenantId } = source;
126
+ const events = await loadEventsOfAggregatesByType(db, tenantId, args);
127
+ return upcastStoredEvents(events, registry.getEventUpcasters(), makeUpcastCtx(db, tenantId));
128
+ }
129
+ function buildLoadByTypes(scope) {
130
+ const { ctx, user, tx, registry } = scope;
131
+ return (args) => {
132
+ const db = requireDbSource(ctx, tx, "ctx.events.loadByTypes");
133
+ return loadUpcastedEventsByTypes({ db, registry, tenantId: user.tenantId }, args);
134
+ };
135
+ }
123
136
  function buildLoadAggregate(scope) {
124
137
  const { ctx, user, tx, registry } = scope;
125
138
  return (aggregateId, loadOptions) => {
@@ -174,6 +187,7 @@ export function buildEventStoreFacet(scope) {
174
187
  tryAppend: buildTryAppendEvent(scope),
175
188
  fetchForWriting: buildFetchForWriting(scope),
176
189
  load: buildLoadAggregate(scope),
190
+ loadByTypes: buildLoadByTypes(scope),
177
191
  archive: async (aggregateId, archiveArgs) => {
178
192
  const dbSource = requireDbSource(ctx, tx, `ctx.events.archive("${aggregateId}")`);
179
193
  await archiveStreamHelper(dbSource, {
@@ -6,11 +6,14 @@ export type CardRoleColumn = {
6
6
  readonly renderer?: unknown;
7
7
  readonly hideOnNarrow?: boolean;
8
8
  readonly narrowInline?: boolean;
9
+ readonly cardBadge?: boolean;
9
10
  readonly fileDisplay?: {
10
11
  readonly kind: string;
11
12
  };
12
13
  /** A "to do" hint column: never the default card title. */
13
14
  readonly hint?: unknown;
15
+ /** Leads the card like a hint column; covers computed columns, which need a renderer and so cannot take `hint`. */
16
+ readonly emphasis?: boolean;
14
17
  };
15
18
  export type CardColumnRoles<C extends CardRoleColumn> = {
16
19
  readonly image: C | undefined;
@@ -22,11 +22,15 @@ export function cardColumnRoles(columns) {
22
22
  const image = columns.find((col) => isImage(col) && col.hideOnNarrow !== true);
23
23
  // A narrow-hidden image must not turn into the title just because it is not the preview.
24
24
  const textColumns = columns.filter((col) => col !== image && !(isImage(col) && col.hideOnNarrow === true));
25
- const title = textColumns.find((col) => col.highlighted === true) ??
26
- textColumns.find((col) => col.hint === undefined) ??
27
- textColumns[0];
28
- const status = textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
29
- const lead = textColumns.find((col) => col !== title && col !== status && col.hint !== undefined && col.hideOnNarrow !== true);
25
+ // A column the phone hides cannot be the card title.
26
+ const titleCandidates = textColumns.filter((col) => col.hideOnNarrow !== true);
27
+ const isLeadCandidate = (col) => col.hint !== undefined || col.emphasis === true;
28
+ const title = titleCandidates.find((col) => col.highlighted === true) ??
29
+ titleCandidates.find((col) => !isLeadCandidate(col)) ??
30
+ titleCandidates[0];
31
+ const status = textColumns.find((col) => col !== title && col.cardBadge === true && col.hideOnNarrow !== true) ??
32
+ textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
33
+ const lead = textColumns.find((col) => col !== title && col !== status && isLeadCandidate(col) && col.hideOnNarrow !== true);
30
34
  const meta = textColumns.filter((col) => col !== title && col !== status && col !== lead && col.hideOnNarrow !== true);
31
35
  return { image, lead, title, status, meta };
32
36
  }
@@ -11,7 +11,7 @@ export type { EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, Options
11
11
  export type { AccessRule } from "../engine/types/handlers.ts";
12
12
  export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
13
13
  export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
14
- export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardLayout, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelColumn, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditStepListSection, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldAiAssist, FieldAiAssistChip, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FieldTextRef, FieldValueChips, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, ListToolbarActionsPlacement, MetricNavigate, PlatformComponent, ProjectionDetailInitialTab, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, StepListItem, ToolbarAction, } from "../engine/types/screen.ts";
14
+ export type { ActionFormFooterAction, ActionFormLoad, ActionFormPreview, ActionFormPreviewList, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ActionFormValueType, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardLayout, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelColumn, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditStepListSection, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldAiAssist, FieldAiAssistChip, FieldBadge, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FieldTextRef, FieldValueChips, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, ListToolbarActionsPlacement, MetricNavigate, PlatformComponent, ProjectionDetailInitialTab, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, StepListItem, ToolbarAction, } from "../engine/types/screen.ts";
15
15
  export { MAX_BULK_SELECTION } from "../engine/types/screen.ts";
16
16
  export type { TargetRef } from "../engine/types/target-ref.ts";
17
17
  export type { TreeAction } from "../engine/types/tree-node.ts";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.416.0",
3
+ "version": "0.418.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -204,7 +204,7 @@
204
204
  "./package.json": "./package.json"
205
205
  },
206
206
  "dependencies": {
207
- "@cosmicdrift/kumiko-types": "0.416.0",
207
+ "@cosmicdrift/kumiko-types": "0.418.0",
208
208
  "bullmq": "^5.81.5",
209
209
  "hono": "^4.13.14",
210
210
  "i18next": "^26.5.12",
@@ -226,7 +226,7 @@
226
226
  }
227
227
  },
228
228
  "devDependencies": {
229
- "@cosmicdrift/kumiko-testing": "0.416.0",
229
+ "@cosmicdrift/kumiko-testing": "0.418.0",
230
230
  "bun-types": "^1.4.4",
231
231
  "fflate": "^0.8.3",
232
232
  "meilisearch": "^0.62.0",
package/src/changes.json CHANGED
@@ -1,4 +1,40 @@
1
1
  [
2
+ {
3
+ "version": "0.418.0",
4
+ "type": "improvement",
5
+ "title": "Bulk action opens an actionForm with all selected ids",
6
+ "detail": "A list `bulkActions` entry `{ id, label, icon?, screen, idsField }` opens the actionForm `screen` once for the checkbox selection. The selected ids arrive as a `string[]` in `idsField`, so the form's handler runs once for all rows. `idsField` must be a `multiSelect` with the new `display: \"count\"`, which shows \"n selected\" read-only. The ids travel in memory, so only the 100-row selection cap applies. The `rowAction` form is unchanged. The boot validator checks label, screen, actionForm type, field and layout (rules `list-bulk/form-*`)."
7
+ },
8
+ {
9
+ "version": "0.418.0",
10
+ "type": "improvement",
11
+ "title": "actionForm preview from a query over the form values",
12
+ "detail": "An actionForm `preview` `{ query, fields?, title?, facts?, list? }` shows a panel above the submit button. The query runs over the current form values 300 ms after the last change, not while a required sent field is empty; empty optional fields stay out of the query payload, an untouched money field that holds only its currency included. Its result renders as facts and a table. A failing query shows a hint and never blocks the submit. The boot validator checks the query, the sent fields and the labels (rules `action-form-preview/*`). A form bulk action's write handler must bound the id list with `.max(MAX_BULK_SELECTION)` and check every id itself. Facts (also the success box ones) and list columns take an optional `type` (`number`, `money`, `date`, `timestamp`); a money value is `{ amount, currency }` in major units."
13
+ },
14
+ {
15
+ "version": "0.418.0",
16
+ "type": "fix",
17
+ "title": "Boot validator checks dateOnlyAfterDays on list columns",
18
+ "detail": "A column's `dateOnlyAfterDays` must be a non-negative whole number on every list kind. On an entityList column it requires a timestamp, locatedTimestamp or date field or a `relativeTime` format; on a projectionList or relatedList column a numeric `valueType` (number, decimal, bigInt, money) is rejected, and a relatedList column with an entity is checked against that entity's field type. Number columns that showed 42 as 1 January 1970 now fail at boot (rules `list/date-only-after-days-invalid` and `list/date-only-after-days-wrong-type`)."
19
+ },
20
+ {
21
+ "version": "0.418.0",
22
+ "type": "fix",
23
+ "title": "Boot warns on tenant or user rate limits without a RateLimitResolver",
24
+ "detail": "A handler `rateLimit` with a `tenant` or `user` bucket needs a `RateLimitResolver`. Without one the server still boots but logs a warning naming the handlers, which answer every call with a 500. Wire a Redis client on `context.redis` or pass `context.rateLimit`."
25
+ },
26
+ {
27
+ "version": "0.418.0",
28
+ "type": "fix",
29
+ "title": "URL prefill and the hidden-required boot rule follow navigate targets given as a QN",
30
+ "detail": "`urlPrefillFields` and the boot rule `submit-prefilled-hidden-required` resolved a navigate `screen` only by its short id, so a target written as `<feature>:screen:<id>` was skipped silently. Its `params` keys now prefill the target form and seed its hidden required fields like a short-id target does."
31
+ },
32
+ {
33
+ "version": "0.417.0",
34
+ "type": "improvement",
35
+ "title": "ctx.events.loadByTypes reads several aggregates by event type in one query",
36
+ "detail": "`ctx.events.loadByTypes({ aggregateIds, eventTypes, includeArchived })` returns the matching events of all given aggregates in append order, upcasted, and leaves out archived streams unless `includeArchived` is set. Use it for list pages that need only a few event types of many aggregates."
37
+ },
2
38
  {
3
39
  "version": "0.416.0",
4
40
  "type": "improvement",