@cosmicdrift/kumiko-framework 0.419.0 → 0.420.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 (31) hide show
  1. package/agents/api/framework-engine.md +4 -0
  2. package/agents/api/framework-ui-types.md +18 -1
  3. package/agents/api/renderer-web.md +3 -0
  4. package/agents/api/types.md +8 -1
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +10 -0
  7. package/dist/crypto/subject-resolver.d.ts +1 -0
  8. package/dist/crypto/subject-resolver.js +8 -2
  9. package/dist/db/queries/backfill-pii.js +29 -3
  10. package/dist/engine/boot-validator/action-form-preview-rules.d.ts +5 -0
  11. package/dist/engine/boot-validator/action-form-preview-rules.js +5 -0
  12. package/dist/engine/boot-validator/action-form-preview.js +13 -0
  13. package/dist/engine/boot-validator/boot-phases-app.js +2 -0
  14. package/dist/engine/boot-validator/boot-rules.d.ts +26 -0
  15. package/dist/engine/boot-validator/boot-rules.js +2 -0
  16. package/dist/engine/boot-validator/page-help-rules.d.ts +17 -0
  17. package/dist/engine/boot-validator/page-help-rules.js +17 -0
  18. package/dist/engine/boot-validator/page-help.d.ts +2 -0
  19. package/dist/engine/boot-validator/page-help.js +109 -0
  20. package/dist/engine/boot-validator/screens-actions.d.ts +5 -0
  21. package/dist/engine/boot-validator/screens-actions.js +15 -6
  22. package/dist/engine/boot-validator/screens-forms-rules.d.ts +5 -0
  23. package/dist/engine/boot-validator/screens-forms-rules.js +5 -0
  24. package/dist/engine/boot-validator/screens-forms.js +13 -1
  25. package/dist/engine/boot-validator/url-prefill-fields.js +5 -11
  26. package/dist/i18n/required-surface-keys.d.ts +2 -0
  27. package/dist/i18n/required-surface-keys.js +11 -1
  28. package/dist/migrations/pii-event-backfill.js +4 -1
  29. package/dist/ui-types/index.d.ts +1 -1
  30. package/package.json +3 -3
  31. package/src/changes.json +12 -0
@@ -538,6 +538,7 @@ type EditFieldSpec =
538
538
  suffix?: FieldAffix; // Same as `prefix`, shown after the input.
539
539
  fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
540
540
  aiAssist?: FieldAiAssist; // Helper under a `text` or `longText` input: stackable chips and an optional free instruction call a query and write its `resultField` into the field.
541
+ editor?: "document"; // `longText` fields only: edits the value with the rich-text editor registered for "document" (the value is an HTML string) instead of a textarea.
541
542
  valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
542
543
  concealed?: true; // Read-only display of a value the viewer may not see: the value (or the mask the query returns) shows muted with a lock icon instead of a replacement text.
543
544
  badge?: FieldBadge; // Pill next to the label, e.g. "price source open" in `warn`.
@@ -555,6 +556,7 @@ type EditRelatedListSection = EditSectionPresentation & {
555
556
  visibleWhen?: Exclude<FieldCondition, boolean>; // projectionDetail only: shows the section (and its tab) only while the loaded record matches, same `{ field, eq | ne | in | notIn }` syntax as a field's `visibleWhen`.
556
557
  kind: "relatedList";
557
558
  title: string;
559
+ pageHelp?: PageHelpSpec; // Joins the help of the surrounding screen; a status section's entity defaults to `entity` of this section.
558
560
  readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
559
561
  query: string; // Fully qualified query QN.
560
562
  parentParam?: string; // Query-payload key the parent record's id is passed under.
@@ -699,6 +701,7 @@ type EntityListScreenDefinition = {
699
701
  toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
700
702
  narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
701
703
  toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
704
+ pageHelp?: PageHelpSpec; // General help of the page: a question-mark button in the shell header opens a drawer with the sections.
702
705
  itemNounKey?: string; // i18n key of the plural noun for the list size in the phone sort line (`{count}` pluralised).
703
706
  searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
704
707
  searchable?: boolean;
@@ -1442,6 +1445,7 @@ type ProjectionDetailScreenDefinition = {
1442
1445
  listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
1443
1446
  slots?: ScreenSlots;
1444
1447
  access?: AccessRule;
1448
+ pageHelp?: PageHelpSpec; // General help of the page, plus the help sections of its relatedList sections; a status section needs `entity` here.
1445
1449
  actions?: EntityEditAction[]; // Header action buttons.
1446
1450
  primaryAction?: string; // Id of the action that stays the visible header button when the actions collapse into a menu (and the one that keeps the phone icon slot when it has an icon and no confirm).
1447
1451
  inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
@@ -71,6 +71,7 @@ type ActionFormPreview = { // Preview panel above the submit button: runs a quer
71
71
  query: string; // Query QN.
72
72
  fields?: string[]; // Form fields sent to the query; they also trigger a rerun when they change.
73
73
  title?: string; // Panel title (i18n key).
74
+ section?: string; // Id of a layout section: the panel renders at the end of that section instead of below the form.
74
75
  facts?: ActionFormSuccessFact[]; // Key figures from the query result, shown like the success box facts.
75
76
  list?: ActionFormPreviewList; // Table of rows from the query result.
76
77
  };
@@ -87,7 +88,7 @@ type ActionFormRedirect = { // Redirect target plus the success-payload field ca
87
88
  type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
88
89
  field: string; // Flat field name in the handler's success payload.
89
90
  label: string; // Label (i18n key).
90
- type?: ActionFormValueType; // Format of the value (a money object, a date string, a number); default `text`.
91
+ type?: ActionFormValueType | "file"; // Format of the value (a money object, a date string, a number); default `text`.
91
92
  };
92
93
  type ActionFormSuccessItems = { // Per-entry hints of the success box, read from an array in the handler's success payload.
93
94
  field: string; // Flat field name of an array in the success payload.
@@ -490,6 +491,7 @@ type FieldAiAssist = {
490
491
  resultField: string; // Key in the query result written into the field; the value must be a string.
491
492
  noteField?: string; // Key in the query result with a short note for the user (e.g. "could not rewrite, draft unchanged").
492
493
  contextFields?: string[]; // Other fields of the same form whose current values are sent in the payload (under their field names).
494
+ autoRun?: boolean; // Default `true`: a change of a `contextFields` field re-runs the query while the field is empty or AI-written.
493
495
  chips?: FieldAiAssistChip[];
494
496
  prompt?: {
495
497
  param: string;
@@ -569,6 +571,21 @@ type ListTableSummaryRow = { // The query receives the list's current search, fi
569
571
  };
570
572
  type ListToolbarActionsPlacement = (typeof LIST_TOOLBAR_ACTIONS_PLACEMENTS)[number];
571
573
  type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
574
+ type PageHelpSection = PageHelpStatusSection | PageHelpTextSection;
575
+ type PageHelpSpec = { // General help of a page: a question-mark button at the end of the shell header actions opens a drawer with one card per section.
576
+ sections: PageHelpSection[];
577
+ };
578
+ type PageHelpStatusSection = { // Explains every option of one select field (typically a status).
579
+ kind: "status";
580
+ field: string;
581
+ entity?: string;
582
+ title?: string; // i18n key of the card heading.
583
+ };
584
+ type PageHelpTextSection = { // Free help text; `title` and `text` are i18n keys.
585
+ kind: "text";
586
+ title: string;
587
+ text: string;
588
+ };
572
589
  type ParsedRefTarget = {
573
590
  featureName: string;
574
591
  entityName: string;
@@ -698,6 +698,8 @@ type GridProps = { // Column-based layout.
698
698
  ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
699
699
  tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
700
700
  facts?: boolean; // Read-only label/value facts: a true `columns`-wide grid with a tight gap, at most 2 columns below `sm`.
701
+ legend?: boolean; // Legend rows as flat child pairs (term, explanation): the first column is as wide as its widest term and never wraps, the second takes the rest, with a fixed gap between them.
702
+ ruled?: boolean; // With `legend`: the term column is a fixed 13rem (12rem plus gap) in every grid (sentences start at one x across cards) and the rows are separated by hairlines.
701
703
  };
702
704
  type HeaderActionGroupProps = {
703
705
  children: ReactNode;
@@ -1381,6 +1383,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1381
1383
  fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
1382
1384
  leadContent?: ReactNode; // Rendered first inside the form, above the sections, in the same column and rhythm — for content that belongs to the form but is no field (e.g. the secret a confirm step refers to).
1383
1385
  belowSections?: (values: Readonly<Record<string, unknown>>) => ReactNode; // Rendered after the sections, above the form actions, with the live form values.
1386
+ afterSection?: (sectionId: string, values: Readonly<Record<string, unknown>>) => ReactNode; // Rendered at the end of the fields section with this id, with the live form values.
1384
1387
  submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
1385
1388
  formDerivation?: FormDerivationScreen; // actionForm `derive`: derived fields are recomputed into the form state on every change and render read-only.
1386
1389
  actionFormScreenQn?: string; // QN of the actionForm screen this form renders; its file fields upload as pending for that screen.
@@ -1605,6 +1605,7 @@ type ContentEditorProps = {
1605
1605
  onChange: (value: string) => void;
1606
1606
  variables: string[]; // Variable names insertable as chips (from the collection's variableSchema).
1607
1607
  readOnly: boolean;
1608
+ formatting?: "text"; // "text" asks for plain text formatting only (bold, italic, lists, link): no images, tables or other blocks.
1608
1609
  };
1609
1610
  ```
1610
1611
 
@@ -2264,6 +2265,8 @@ type EditFieldViewModel = {
2264
2265
  suffix?: FieldAffix;
2265
2266
  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
2266
2267
  aiAssist?: FieldAiAssist; // From EditFieldSpec.aiAssist, chip labels and the prompt placeholder already translated.
2268
+ editor?: "document"; // From EditFieldSpec.editor.
2269
+ contextDocumentFields?: string[]; // aiAssist.contextFields that name a document-editor field of the same form (their HTML is sent as text).
2267
2270
  valueChips?: FieldValueChips; // From EditFieldSpec.valueChips.
2268
2271
  concealed?: true; // From EditFieldSpec.concealed.
2269
2272
  badge?: FieldBadge; // From EditFieldSpec.badge, a fixed `label` already translated.
@@ -2531,6 +2534,7 @@ type ButtonBaseProps = {
2531
2534
  size?: "sm" | "md" | "icon"; // Size—default="md".
2532
2535
  ariaLabel?: string; // Accessible label—required for icon-only buttons (when children contain only an icon or character), otherwise the button has no accessible name.
2533
2536
  title?: string; // Tooltip — rendered as the `title` attribute.
2537
+ collapseLabel?: boolean; // Below the `sm` breakpoint only the icon shows (in a square), the label stays the accessible name.
2534
2538
  pressed?: boolean; // Toggle state for toggle buttons — web sets `aria-pressed`; leave unset for plain buttons.
2535
2539
  expanded?: boolean; // Disclosure state for buttons that open a menu or panel — web sets `aria-expanded`.
2536
2540
  width?: "full" | "auto"; // Width—default="auto" (content width).
@@ -2590,6 +2594,7 @@ type DialogProps = { // Modal dialog for confirmations or compact sub-forms.
2590
2594
  description?: string; // Optional description, typically a sentence explaining the consequence ("This action cannot be undone.").
2591
2595
  confirmLabel?: string; // Confirm-button label.
2592
2596
  cancelLabel?: string; // Cancel-Button-Label.
2597
+ hideCancel?: boolean; // Leaves out the cancel button, for an information dialog whose only button closes it.
2593
2598
  variant?: "default" | "danger"; // `default` = Confirm primary, `danger` = Confirm danger.
2594
2599
  initialFocus?: "confirm" | "cancel"; // Which button takes focus on open.
2595
2600
  onConfirm: () => void | Promise<void>; // Called when the user confirms.
@@ -2672,6 +2677,7 @@ type PageHeaderProps = { // Page title area rendered by the app shell's header i
2672
2677
  recordTitle?: string; // Name of the loaded record; shown as an extra breadcrumb before the last one.
2673
2678
  narrowRecordTitle?: string; // Short record title for the phone top bar; wins over `recordTitle` there.
2674
2679
  status?: ReactNode;
2680
+ help?: ReactNode; // Page help trigger, shown at the end of the shell header actions.
2675
2681
  actions?: ReactNode;
2676
2682
  bodyTitle?: boolean; // Screen renders its own h1: the shell header shows only the parent crumb, as text.
2677
2683
  overflowItems?: ActionMenuItemSpec[]; // Land in the shell header's overflow menu at phone width.
@@ -5071,6 +5077,7 @@ type EditFieldsSectionBase = EditSectionPresentation & {
5071
5077
  description?: string; // Optional help text under the block heading (i18n key or raw string, like `title`) — makes a form usable without training instead of falling back to custom JSX for help text.
5072
5078
  descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
5073
5079
  columns?: number;
5080
+ flow?: boolean; // Screen forms and drawers lay fields out as a flow: each field is sized by its type and `columns` is ignored.
5074
5081
  icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
5075
5082
  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
5076
5083
  subtitle?: string; // Short line (i18n key) under this step's title in the wizard step rail and in the "up next" box.
@@ -5129,7 +5136,7 @@ type ScreenFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
5129
5136
  ## packages/types/src/screen-expandable-row.ts
5130
5137
 
5131
5138
  ```ts
5132
- type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "count" | "table" | "bulkActions"> & { // Expandable area of an `entityList` row: a relatedList of the row's record.
5139
+ type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "count" | "table" | "bulkActions" | "pageHelp"> & { // Expandable area of an `entityList` row: a relatedList of the row's record.
5133
5140
  table?: {
5134
5141
  grouping?: ExpandableRowGrouping;
5135
5142
  };
package/agents/api.md CHANGED
@@ -10,7 +10,7 @@ Format: one line per function or constant, object and options types as property
10
10
  | --- | --- | --- |
11
11
  | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 446 |
12
12
  | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
- | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 193 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 197 |
14
14
  | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 157 |
15
15
  | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 41 |
16
16
  | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
@@ -12,6 +12,7 @@
12
12
  | <a id="action-form-preview-field-unknown"></a>`action-form-preview/field-unknown` | preview.fields names fields of the form. | Name an existing field of the form, or drop fields to send all of them. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
13
13
  | <a id="action-form-preview-label-missing"></a>`action-form-preview/label-missing` | Every preview fact and list column has a label. | Add label: the i18n key of the fact or column header. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
14
14
  | <a id="action-form-preview-list-field-missing"></a>`action-form-preview/list-field-missing` | preview.list names the result field of its rows and at least one column. | Set list.field to the array in the query result and list the columns to show. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
15
+ | <a id="action-form-preview-section-unknown"></a>`action-form-preview/section-unknown` | preview.section names a fields section of the layout. | Give a layout section that id, or drop section to show the preview below the form. | `packages/framework/src/engine/boot-validator/action-form-preview-rules.ts` |
15
16
 
16
17
  ## agent-effect
17
18
 
@@ -476,6 +477,7 @@
476
477
  | <a id="form-confirm-layout-mode"></a>`form/confirm-layout-mode` | A secretMint confirm layout is a single-step form. | Remove mode or set it to "single". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
477
478
  | <a id="form-draft-feature-missing"></a>`form/draft-feature-missing` | A draft layout needs the form-draft feature mounted. | Add createFormDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's features. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
478
479
  | <a id="form-draft-without-wizard"></a>`form/draft-without-wizard` | layout.draft is set only on a wizard layout. | Remove draft: true or set mode: "wizard". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
480
+ | <a id="form-editor-field-type"></a>`form/editor-field-type` | The editor option targets a longText field without fillAction or valueChips. | Remove editor, or use a longText field and drop fillAction and valueChips. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
479
481
  | <a id="form-embedded-list-card-hidden-editable"></a>`form/embedded-list-card-hidden-editable` | embeddedList.cardHiddenCells lists only read-only cells. | Add the cell to readOnlyCells or remove it from cardHiddenCells. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
480
482
  | <a id="form-embedded-list-on-non-list-field"></a>`form/embedded-list-on-non-list-field` | embeddedList is set only on an embedded list field. | Remove embeddedList or point it at an embedded list field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
481
483
  | <a id="form-embedded-list-unknown-sub-field"></a>`form/embedded-list-unknown-sub-field` | embeddedList cell options name sub-fields of the embedded schema. | Name an existing sub-field. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -898,6 +900,14 @@
898
900
  | <a id="ownership-where-on-field-read"></a>`ownership/where-on-field-read` | A field-level read access map uses from(...) rules, not where(...). | Replace the where rule with a from rule on the field read path. | `packages/framework/src/engine/boot-validator/ownership-rules.ts` |
899
901
  | <a id="ownership-where-on-write-path"></a>`ownership/where-on-write-path` | A write access map uses from(...) rules, not where(...), because where is read-only SQL. | Replace the where rule with a from rule on the write path. | `packages/framework/src/engine/boot-validator/ownership-rules.ts` |
900
902
 
903
+ ## page-help
904
+
905
+ | Rule | Summary | Fix | Source |
906
+ | --- | --- | --- | --- |
907
+ | <a id="page-help-option-help-missing"></a>`page-help/option-help-missing` | Every option of the pageHelp field has a `:help` translation, in the feature that owns the entity, in each locale its option label has. | Add `<option label key>:help` via r.translations(...) in the owning feature for the listed options and locales. | `packages/framework/src/engine/boot-validator/page-help-rules.ts` |
908
+ | <a id="page-help-status-field-invalid"></a>`page-help/status-field-invalid` | Every status section of a pageHelp names a select field of an existing entity, bare for the own feature or `<feature>:<entity>` for another one (entity is required on a projectionDetail; a relatedList defaults to its section entity). | Point the status section's field at a select field and its entity at an existing entity (`<feature>:<entity>` for a foreign one). | `packages/framework/src/engine/boot-validator/page-help-rules.ts` |
909
+ | <a id="page-help-unsupported-site"></a>`page-help/unsupported-site` | A relatedList's pageHelp only joins the help of a projectionDetail; on a relatedList of an entityEdit it would be ignored. | Declare pageHelp on the projectionDetail or entityList instead. | `packages/framework/src/engine/boot-validator/page-help-rules.ts` |
910
+
901
911
  ## parent-ref
902
912
 
903
913
  | Rule | Summary | Fix | Source |
@@ -13,6 +13,7 @@ export interface ResolveSubjectOptions {
13
13
  readonly ignoreWhenAbsent?: boolean;
14
14
  }
15
15
  export declare function nonEmptyString(value: unknown): string | null;
16
+ export declare function usableOwnerId(value: unknown): string | null;
16
17
  /**
17
18
  * Maps a pii-annotated field to the subject whose key encrypts it.
18
19
  * Returns null for fields without any PII annotation (stored plaintext).
@@ -1,7 +1,8 @@
1
1
  import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { isFileField } from "../engine/field-helpers.js";
3
3
  import { isSelfPiiField } from "./is-self-pii-field.js";
4
- import { RECORD_ENTITY_PATTERN } from "./kms-adapter.js";
4
+ import { PII_ERASED_SENTINEL, RECORD_ENTITY_PATTERN } from "./kms-adapter.js";
5
+ import { isPiiCiphertext } from "./pii-ciphertext-format.js";
5
6
  // Thrown when a field IS pii-annotated but the row can't name its subject —
6
7
  // that must surface as an error, not fall back to plaintext.
7
8
  export class SubjectResolutionError extends Error {
@@ -15,6 +16,11 @@ export class SubjectResolutionError extends Error {
15
16
  export function nonEmptyString(value) {
16
17
  return typeof value === "string" && value.length > 0 ? value : null;
17
18
  }
19
+ // A stored ciphertext or the erased sentinel in an owner column is not a user id.
20
+ export function usableOwnerId(value) {
21
+ const id = nonEmptyString(value);
22
+ return id === null || id === PII_ERASED_SENTINEL || isPiiCiphertext(id) ? null : id;
23
+ }
18
24
  function rowIdAsString(row) {
19
25
  const id = row["id"];
20
26
  return nonEmptyString(id) ?? (typeof id === "number" ? String(id) : null);
@@ -32,7 +38,7 @@ function resolveRecordSubject(fieldName, row, opts) {
32
38
  }
33
39
  function resolveUserOwnedSubject(userOwned, fieldName, row, opts) {
34
40
  const { ownerField } = userOwned;
35
- const userId = nonEmptyString(row[ownerField]) ?? nonEmptyString(opts.ownerFallback?.[ownerField]);
41
+ const userId = usableOwnerId(row[ownerField]) ?? usableOwnerId(opts.ownerFallback?.[ownerField]);
36
42
  if (userId !== null)
37
43
  return { kind: "user", userId };
38
44
  if (opts.ignoreWhenAbsent !== true) {
@@ -66,7 +66,7 @@ import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
66
66
  import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
67
67
  import { isPlainUserOwnedField } from "../../crypto/owner-transition-rekey.js";
68
68
  import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
69
- import { collectPiiEncryptedFields, nonEmptyString, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
69
+ import { collectPiiEncryptedFields, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, usableOwnerId, } from "../../crypto/subject-resolver.js";
70
70
  import { resolveTableName } from "../entity-table-meta.js";
71
71
  import { asRawClient } from "../query.js";
72
72
  import { tableExists } from "../schema-inspection.js";
@@ -517,6 +517,8 @@ async function rekeyTenantKeyedValue(deps, target) {
517
517
  const fieldDef = entity.fields[field];
518
518
  if (fieldDef === undefined || !isPlainUserOwnedField(fieldDef))
519
519
  return { kind: "unchanged" };
520
+ if (fieldDef.userOwned.ownerField === field)
521
+ return rekeySelfOwnedValue(deps, target);
520
522
  const keyedUnder = ciphertextSubjectOrNull(ciphertext);
521
523
  const userSubject = keyedUnder?.kind === "tenant" && keyedUnder.tenantId === target.tenantId
522
524
  ? rekeyTargetOfTenantKeyedValue(target)
@@ -529,6 +531,30 @@ async function rekeyTenantKeyedValue(deps, target) {
529
531
  (target.isSupersededHistory || (await deps.hasNewerValueOfField(field)))) {
530
532
  return { kind: "unchanged" };
531
533
  }
534
+ return moveUnderUserSubject(deps, userSubject, ciphertext, field, () => decryptPiiValueForSubject(deps.subjectKms, ciphertext, deps.kmsCtx, field));
535
+ }
536
+ // The field is its own owner: the key follows the value, so no event history or
537
+ // projection decides it, and a stored ciphertext must never be read as the owner id.
538
+ async function rekeySelfOwnedValue(deps, target) {
539
+ const { field, ciphertext } = target;
540
+ const keyedUnder = ciphertextSubjectOrNull(ciphertext);
541
+ if (keyedUnder === null)
542
+ return { kind: "unchanged" };
543
+ const ownTenantKey = keyedUnder.kind === "tenant" && keyedUnder.tenantId === target.tenantId;
544
+ if (!ownTenantKey && keyedUnder.kind !== "user")
545
+ return { kind: "unchanged" };
546
+ const plaintext = await decryptPiiValueForSubject(deps.subjectKms, ciphertext, deps.kmsCtx, field);
547
+ if (plaintext === PII_ERASED_SENTINEL)
548
+ return { kind: "erased" };
549
+ const ownerId = usableOwnerId(plaintext);
550
+ if (ownerId === null)
551
+ return { kind: "unchanged" };
552
+ if (keyedUnder.kind === "user" && keyedUnder.userId === ownerId)
553
+ return { kind: "unchanged" };
554
+ return moveUnderUserSubject(deps, { kind: "user", userId: ownerId }, ciphertext, field, async () => plaintext);
555
+ }
556
+ // Forgotten and dryRun are decided before the plaintext is read.
557
+ async function moveUnderUserSubject(deps, userSubject, ciphertext, field, readPlaintext) {
532
558
  if (await deps.isForgottenSubject(userSubject))
533
559
  return { kind: "erased" };
534
560
  if (deps.dryRun) {
@@ -536,7 +562,7 @@ async function rekeyTenantKeyedValue(deps, target) {
536
562
  ? { kind: "erased" }
537
563
  : { kind: "rekeyed", value: ciphertext };
538
564
  }
539
- const plaintext = await decryptPiiValueForSubject(deps.subjectKms, ciphertext, deps.kmsCtx, field);
565
+ const plaintext = await readPlaintext();
540
566
  if (plaintext === PII_ERASED_SENTINEL)
541
567
  return { kind: "erased" };
542
568
  try {
@@ -563,7 +589,7 @@ function rekeyTargetOfTenantKeyedValue(target) {
563
589
  // projection of the event's own tenant is authoritative here: the payload of
564
590
  // an old created event still names the owner the row had back then.
565
591
  function currentProjectionOwnerIfOther(target, ownerField, keyedUserId) {
566
- const owner = nonEmptyString(target.projectionOwnerRow?.[ownerField]);
592
+ const owner = usableOwnerId(target.projectionOwnerRow?.[ownerField]);
567
593
  return owner === null || owner === keyedUserId ? null : { kind: "user", userId: owner };
568
594
  }
569
595
  // Only the row's own tenant key or a user key counts: another tenant's key is
@@ -14,6 +14,11 @@ export declare const ACTION_FORM_PREVIEW_RULES: {
14
14
  readonly summary: "preview.list names the result field of its rows and at least one column.";
15
15
  readonly fix: "Set list.field to the array in the query result and list the columns to show.";
16
16
  };
17
+ readonly sectionUnknown: {
18
+ readonly id: "action-form-preview/section-unknown";
19
+ readonly summary: "preview.section names a fields section of the layout.";
20
+ readonly fix: "Give a layout section that id, or drop section to show the preview below the form.";
21
+ };
17
22
  readonly empty: {
18
23
  readonly id: "action-form-preview/empty";
19
24
  readonly summary: "A preview shows facts or a list.";
@@ -14,6 +14,11 @@ export const ACTION_FORM_PREVIEW_RULES = {
14
14
  summary: "preview.list names the result field of its rows and at least one column.",
15
15
  fix: "Set list.field to the array in the query result and list the columns to show.",
16
16
  },
17
+ sectionUnknown: {
18
+ id: "action-form-preview/section-unknown",
19
+ summary: "preview.section names a fields section of the layout.",
20
+ fix: "Give a layout section that id, or drop section to show the preview below the form.",
21
+ },
17
22
  empty: {
18
23
  id: "action-form-preview/empty",
19
24
  summary: "A preview shows facts or a list.",
@@ -1,3 +1,4 @@
1
+ import { isFieldsEditSection } from "../screen-helpers.js";
1
2
  import { ACTION_FORM_PREVIEW_RULES } from "./action-form-preview-rules.js";
2
3
  import { bootRuleError } from "./boot-rule.js";
3
4
  function isBlank(value) {
@@ -12,6 +13,17 @@ function validateSentFields(where, preview, fieldNames) {
12
13
  });
13
14
  }
14
15
  }
16
+ function validateSection(where, preview, screen) {
17
+ // skip: no placement, the panel stays below the form
18
+ if (preview.section === undefined)
19
+ return;
20
+ const sectionIds = screen.layout.sections.flatMap((section) => isFieldsEditSection(section) && section.id !== undefined ? [section.id] : []);
21
+ if (sectionIds.includes(preview.section))
22
+ return;
23
+ throw bootRuleError(ACTION_FORM_PREVIEW_RULES.sectionUnknown, {
24
+ message: `${where} section "${preview.section}" is no fields section id of the layout. Section ids: ${sectionIds.join(", ") || "(none)"}.`,
25
+ });
26
+ }
15
27
  function validateFacts(where, facts) {
16
28
  for (const fact of facts) {
17
29
  if (!isBlank(fact.label))
@@ -42,6 +54,7 @@ export function validateActionFormPreview(featureName, screenId, screen, fieldNa
42
54
  return;
43
55
  const where = `[Feature ${featureName}] Screen "${screenId}" (actionForm) preview`;
44
56
  validateSentFields(where, preview, fieldNames);
57
+ validateSection(where, preview, screen);
45
58
  const facts = preview.facts ?? [];
46
59
  if (facts.length === 0 && preview.list === undefined) {
47
60
  throw bootRuleError(ACTION_FORM_PREVIEW_RULES.empty, {
@@ -14,6 +14,7 @@ import { validateGlobalTenancyEntities } from "./global-tenancy.js";
14
14
  import { validateFieldValueTranslations, validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
15
15
  import { validateListSortAndSummary } from "./list-sort-summary.js";
16
16
  import { validateNavCycles } from "./nav.js";
17
+ import { validatePageHelp } from "./page-help.js";
17
18
  import { validateProjectionListScreens, validateRelatedListSectionQueries, } from "./projection-list-screens.js";
18
19
  import { validateQueryOutputColumns } from "./query-output-columns.js";
19
20
  import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
@@ -33,6 +34,7 @@ const APP_CHECKS_AFTER_I18N = [
33
34
  run: (c) => validateFieldValueTranslations(c.features, c.options?.requireFieldValueTranslations),
34
35
  },
35
36
  { check: "validateEntityListScreens", run: (c) => validateEntityListScreens(c.features) },
37
+ { check: "validatePageHelp", run: (c) => validatePageHelp(c.features) },
36
38
  {
37
39
  check: "validateSubmitPrefilledHiddenFields",
38
40
  run: (c) => validateSubmitPrefilledHiddenFields(c.features),
@@ -141,6 +141,22 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
141
141
  readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
142
142
  readonly fix: "Fix the column field name or give the column a label.";
143
143
  };
144
+ }, {
145
+ readonly statusFieldInvalid: {
146
+ readonly id: "page-help/status-field-invalid";
147
+ readonly summary: "Every status section of a pageHelp names a select field of an existing entity, bare for the own feature or `<feature>:<entity>` for another one (entity is required on a projectionDetail; a relatedList defaults to its section entity).";
148
+ readonly fix: "Point the status section's field at a select field and its entity at an existing entity (`<feature>:<entity>` for a foreign one).";
149
+ };
150
+ readonly optionHelpMissing: {
151
+ readonly id: "page-help/option-help-missing";
152
+ readonly summary: "Every option of the pageHelp field has a `:help` translation, in the feature that owns the entity, in each locale its option label has.";
153
+ readonly fix: "Add `<option label key>:help` via r.translations(...) in the owning feature for the listed options and locales.";
154
+ };
155
+ readonly unsupportedSite: {
156
+ readonly id: "page-help/unsupported-site";
157
+ readonly summary: "A relatedList's pageHelp only joins the help of a projectionDetail; on a relatedList of an entityEdit it would be ignored.";
158
+ readonly fix: "Declare pageHelp on the projectionDetail or entityList instead.";
159
+ };
144
160
  }, {
145
161
  readonly projectionQueryAcceptsNamedFilter: {
146
162
  readonly id: "named-filter/projection-query-accepts-named-filter";
@@ -961,6 +977,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
961
977
  readonly summary: "actionForm fieldBadges keys name fields of the form.";
962
978
  readonly fix: "Name a field of the form or remove the entry.";
963
979
  };
980
+ readonly editorFieldType: {
981
+ readonly id: "form/editor-field-type";
982
+ readonly summary: "The editor option targets a longText field without fillAction or valueChips.";
983
+ readonly fix: "Remove editor, or use a longText field and drop fillAction and valueChips.";
984
+ };
964
985
  readonly aiAssistContextFieldUnknown: {
965
986
  readonly id: "form/ai-assist-context-field-unknown";
966
987
  readonly summary: "aiAssist.contextFields names fields of the same form.";
@@ -2951,6 +2972,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2951
2972
  readonly summary: "preview.list names the result field of its rows and at least one column.";
2952
2973
  readonly fix: "Set list.field to the array in the query result and list the columns to show.";
2953
2974
  };
2975
+ readonly sectionUnknown: {
2976
+ readonly id: "action-form-preview/section-unknown";
2977
+ readonly summary: "preview.section names a fields section of the layout.";
2978
+ readonly fix: "Give a layout section that id, or drop section to show the preview below the form.";
2979
+ };
2954
2980
  readonly empty: {
2955
2981
  readonly id: "action-form-preview/empty";
2956
2982
  readonly summary: "A preview shows facts or a list.";
@@ -37,6 +37,7 @@ import { LIST_TABLE_RULES } from "./list-table-rules.js";
37
37
  import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
38
38
  import { NAV_RULES } from "./nav-rules.js";
39
39
  import { OWNERSHIP_RULES } from "./ownership-rules.js";
40
+ import { PAGE_HELP_RULES } from "./page-help-rules.js";
40
41
  import { PII_RULES } from "./pii-retention-rules.js";
41
42
  import { QUERY_RULES } from "./query-rules.js";
42
43
  import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
@@ -51,6 +52,7 @@ import { SCREEN_RULES } from "./screens-rules.js";
51
52
  export const FRAMEWORK_BOOT_RULE_TABLES = [
52
53
  PII_RULES,
53
54
  ENTITY_LIST_RULES,
55
+ PAGE_HELP_RULES,
54
56
  NAMED_FILTER_RULES,
55
57
  I18N_RULES,
56
58
  CARD_META_OVERFLOW_RULES,
@@ -0,0 +1,17 @@
1
+ export declare const PAGE_HELP_RULES: {
2
+ readonly statusFieldInvalid: {
3
+ readonly id: "page-help/status-field-invalid";
4
+ readonly summary: "Every status section of a pageHelp names a select field of an existing entity, bare for the own feature or `<feature>:<entity>` for another one (entity is required on a projectionDetail; a relatedList defaults to its section entity).";
5
+ readonly fix: "Point the status section's field at a select field and its entity at an existing entity (`<feature>:<entity>` for a foreign one).";
6
+ };
7
+ readonly optionHelpMissing: {
8
+ readonly id: "page-help/option-help-missing";
9
+ readonly summary: "Every option of the pageHelp field has a `:help` translation, in the feature that owns the entity, in each locale its option label has.";
10
+ readonly fix: "Add `<option label key>:help` via r.translations(...) in the owning feature for the listed options and locales.";
11
+ };
12
+ readonly unsupportedSite: {
13
+ readonly id: "page-help/unsupported-site";
14
+ readonly summary: "A relatedList's pageHelp only joins the help of a projectionDetail; on a relatedList of an entityEdit it would be ignored.";
15
+ readonly fix: "Declare pageHelp on the projectionDetail or entityList instead.";
16
+ };
17
+ };
@@ -0,0 +1,17 @@
1
+ export const PAGE_HELP_RULES = {
2
+ statusFieldInvalid: {
3
+ id: "page-help/status-field-invalid",
4
+ summary: "Every status section of a pageHelp names a select field of an existing entity, bare for the own feature or `<feature>:<entity>` for another one (entity is required on a projectionDetail; a relatedList defaults to its section entity).",
5
+ fix: "Point the status section's field at a select field and its entity at an existing entity (`<feature>:<entity>` for a foreign one).",
6
+ },
7
+ optionHelpMissing: {
8
+ id: "page-help/option-help-missing",
9
+ summary: "Every option of the pageHelp field has a `:help` translation, in the feature that owns the entity, in each locale its option label has.",
10
+ fix: "Add `<option label key>:help` via r.translations(...) in the owning feature for the listed options and locales.",
11
+ },
12
+ unsupportedSite: {
13
+ id: "page-help/unsupported-site",
14
+ summary: "A relatedList's pageHelp only joins the help of a projectionDetail; on a relatedList of an entityEdit it would be ignored.",
15
+ fix: "Declare pageHelp on the projectionDetail or entityList instead.",
16
+ },
17
+ };
@@ -0,0 +1,2 @@
1
+ import type { FeatureDefinition } from "../types/index.ts";
2
+ export declare function validatePageHelp(features: readonly FeatureDefinition[]): void;
@@ -0,0 +1,109 @@
1
+ import { hasLocaleValue, selectFacetOptionKey } from "../../i18n/required-surface-keys.js";
2
+ import { parseRefTarget } from "../parse-ref-target.js";
3
+ import { collectBootRuleViolations } from "./boot-report.js";
4
+ import { bootRuleError } from "./boot-rule.js";
5
+ import { PAGE_HELP_RULES } from "./page-help-rules.js";
6
+ function statusSitesOf(where, pageHelp, defaultEntity) {
7
+ const found = [];
8
+ for (const section of pageHelp?.sections ?? []) {
9
+ if (section.kind !== "status")
10
+ continue;
11
+ found.push({ where, section, ...(defaultEntity !== undefined && { defaultEntity }) });
12
+ }
13
+ return found;
14
+ }
15
+ function pageHelpSitesOf(feature) {
16
+ const found = [];
17
+ for (const screen of Object.values(feature.screens)) {
18
+ const where = `screen "${screen.id}"`;
19
+ if (screen.type === "entityList" || screen.type === "projectionDetail") {
20
+ found.push(...statusSitesOf(where, screen.pageHelp, screen.type === "entityList" ? screen.entity : undefined));
21
+ }
22
+ if (screen.type !== "projectionDetail")
23
+ continue;
24
+ for (const section of screen.layout.sections) {
25
+ if (!("kind" in section) || section.kind !== "relatedList")
26
+ continue;
27
+ found.push(...statusSitesOf(`${where} relatedList "${section.title}"`, section.pageHelp, section.entity));
28
+ }
29
+ }
30
+ return found;
31
+ }
32
+ /** Places a relatedList carries a pageHelp that no screen renders: only a projectionDetail shows it. */
33
+ function unsupportedSitesOf(feature) {
34
+ const found = [];
35
+ for (const screen of Object.values(feature.screens)) {
36
+ if (screen.type !== "entityEdit")
37
+ continue;
38
+ for (const section of screen.layout.sections) {
39
+ if (!("kind" in section) || section.kind !== "relatedList")
40
+ continue;
41
+ if (section.pageHelp !== undefined) {
42
+ found.push(`screen "${screen.id}" relatedList "${section.title}"`);
43
+ }
44
+ }
45
+ }
46
+ return found;
47
+ }
48
+ function translationByLocale(owner, fullKey) {
49
+ const local = fullKey.slice(owner.name.length + 1);
50
+ return owner.translations?.[local] ?? owner.translations?.[fullKey];
51
+ }
52
+ function checkPageHelpSite(features, feature, site) {
53
+ const prefix = `[pageHelp] Feature "${feature.name}" ${site.where}`;
54
+ const statusField = site.section.field;
55
+ const rawEntity = site.section.entity ?? site.defaultEntity;
56
+ if (rawEntity === undefined) {
57
+ throw bootRuleError(PAGE_HELP_RULES.statusFieldInvalid, {
58
+ message: `${prefix}: pageHelp.entity is required on a projectionDetail.`,
59
+ });
60
+ }
61
+ const target = parseRefTarget(rawEntity, feature.name);
62
+ const owner = features.find((candidate) => candidate.name === target.featureName);
63
+ if (owner === undefined) {
64
+ throw bootRuleError(PAGE_HELP_RULES.statusFieldInvalid, {
65
+ message: `${prefix}: pageHelp.entity "${rawEntity}" names unknown feature "${target.featureName}".`,
66
+ });
67
+ }
68
+ const entityName = target.entityName;
69
+ const entity = owner.entities?.[entityName];
70
+ if (entity === undefined) {
71
+ throw bootRuleError(PAGE_HELP_RULES.statusFieldInvalid, {
72
+ message: `${prefix}: pageHelp.entity "${rawEntity}" is not an entity of feature "${owner.name}".`,
73
+ });
74
+ }
75
+ const field = entity.fields[statusField];
76
+ if (field === undefined || field.type !== "select") {
77
+ throw bootRuleError(PAGE_HELP_RULES.statusFieldInvalid, {
78
+ message: `${prefix}: pageHelp status field "${statusField}" is not a select field of entity "${entityName}".`,
79
+ });
80
+ }
81
+ const missing = [];
82
+ for (const value of field.options) {
83
+ const labelKey = selectFacetOptionKey(owner.name, entityName, statusField, value);
84
+ const helpKey = `${labelKey}:help`;
85
+ const labelLocales = Object.keys(translationByLocale(owner, labelKey) ?? {});
86
+ const help = translationByLocale(owner, helpKey);
87
+ const gaps = labelLocales.filter((locale) => !hasLocaleValue(help?.[locale]));
88
+ if (help === undefined && labelLocales.length === 0)
89
+ missing.push(`${value} -> ${helpKey}`);
90
+ else if (gaps.length > 0)
91
+ missing.push(`${value} -> ${helpKey} (${gaps.join(", ")})`);
92
+ }
93
+ if (missing.length > 0) {
94
+ throw bootRuleError(PAGE_HELP_RULES.optionHelpMissing, {
95
+ message: `${prefix}: pageHelp field "${statusField}" lacks help text for option(s): ${missing.join("; ")}. Add them via r.translations(...) in feature "${owner.name}".`,
96
+ });
97
+ }
98
+ }
99
+ export function validatePageHelp(features) {
100
+ const checks = features.flatMap((feature) => [
101
+ ...unsupportedSitesOf(feature).map((where) => () => {
102
+ throw bootRuleError(PAGE_HELP_RULES.unsupportedSite, {
103
+ message: `[pageHelp] Feature "${feature.name}" ${where}: pageHelp on a relatedList of an entityEdit is never shown.`,
104
+ });
105
+ }),
106
+ ...pageHelpSitesOf(feature).map((site) => () => checkPageHelpSite(features, feature, site)),
107
+ ]);
108
+ collectBootRuleViolations(checks, (check) => check());
109
+ }
@@ -20,6 +20,11 @@ export declare function validateScreenShortIdCollisions(screensByShortId: Readon
20
20
  readonly screen: ScreenDefinition;
21
21
  }>>): void;
22
22
  export declare function resolveScreenTargetQn(featureName: string, target: string): string;
23
+ export declare function findScreenEntryForNavTarget<E extends {
24
+ readonly featureName: string;
25
+ }>(screensByShortId: ReadonlyMap<string, ReadonlyArray<E>>, target: string): (E & {
26
+ readonly shortId: string;
27
+ }) | undefined;
23
28
  export declare function validateScreenNavTarget(featureName: string, screenId: string, screenKind: string, fieldName: string, value: string, allScreenQns: ReadonlySet<string>, screens: FeatureDefinition["screens"]): void;
24
29
  export declare function validateDrawerTargetAction(featureName: string, screenId: string, screenKind: string, actionLabel: "toolbarAction" | "rowAction" | "emptyState action" | "action", action: {
25
30
  readonly id: string;
@@ -2,7 +2,7 @@ import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
2
2
  import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
3
3
  import { fallbackTargets, SCREEN_FALLBACK_REASONS, } from "@cosmicdrift/kumiko-types/screen";
4
4
  import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
5
- import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
5
+ import { isKebabSegment, isValidQn, parseQn, qualifyEntityName } from "../qualified-name.js";
6
6
  import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
7
7
  import { bootRuleError } from "./boot-rule.js";
8
8
  import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
@@ -215,6 +215,19 @@ export function validateScreenShortIdCollisions(screensByShortId) {
215
215
  export function resolveScreenTargetQn(featureName, target) {
216
216
  return isValidQn(target) ? target : qualifyEntityName(featureName, "screen", target);
217
217
  }
218
+ // A navigate `screen` target is a short id (first feature registering it, like the
219
+ // router) or a screen QN (the entry of exactly that feature).
220
+ export function findScreenEntryForNavTarget(screensByShortId, target) {
221
+ if (!isValidQn(target)) {
222
+ const match = screensByShortId.get(target)?.[0];
223
+ return match === undefined ? undefined : { ...match, shortId: target };
224
+ }
225
+ const { scope, type, name } = parseQn(target);
226
+ if (type !== "screen")
227
+ return undefined;
228
+ const match = screensByShortId.get(name)?.find((entry) => entry.featureName === scope);
229
+ return match === undefined ? undefined : { ...match, shortId: name };
230
+ }
218
231
  export function validateScreenNavTarget(featureName, screenId, screenKind, fieldName, value, allScreenQns, screens) {
219
232
  const candidateQn = resolveScreenTargetQn(featureName, value);
220
233
  if (!allScreenQns.has(candidateQn)) {
@@ -380,11 +393,7 @@ export function resolveRowActionNavigateTarget(featureName, screenId, screenType
380
393
  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`,
381
394
  });
382
395
  }
383
- const targetIsQn = isValidQn(action.screen);
384
- const screensWithShortId = screensByShortId.get(targetIsQn ? action.screen.slice(action.screen.lastIndexOf(":") + 1) : action.screen);
385
- const target = targetIsQn
386
- ? screensWithShortId?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === candidateQn)
387
- : screensWithShortId?.[0];
396
+ const target = findScreenEntryForNavTarget(screensByShortId, action.screen);
388
397
  validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, target);
389
398
  return target;
390
399
  }
@@ -59,6 +59,11 @@ export declare const FORM_FIELD_RULES: {
59
59
  readonly summary: "actionForm fieldBadges keys name fields of the form.";
60
60
  readonly fix: "Name a field of the form or remove the entry.";
61
61
  };
62
+ readonly editorFieldType: {
63
+ readonly id: "form/editor-field-type";
64
+ readonly summary: "The editor option targets a longText field without fillAction or valueChips.";
65
+ readonly fix: "Remove editor, or use a longText field and drop fillAction and valueChips.";
66
+ };
62
67
  readonly aiAssistContextFieldUnknown: {
63
68
  readonly id: "form/ai-assist-context-field-unknown";
64
69
  readonly summary: "aiAssist.contextFields names fields of the same form.";
@@ -59,6 +59,11 @@ export const FORM_FIELD_RULES = {
59
59
  summary: "actionForm fieldBadges keys name fields of the form.",
60
60
  fix: "Name a field of the form or remove the entry.",
61
61
  },
62
+ editorFieldType: {
63
+ id: "form/editor-field-type",
64
+ summary: "The editor option targets a longText field without fillAction or valueChips.",
65
+ fix: "Remove editor, or use a longText field and drop fillAction and valueChips.",
66
+ },
62
67
  aiAssistContextFieldUnknown: {
63
68
  id: "form/ai-assist-context-field-unknown",
64
69
  summary: "aiAssist.contextFields names fields of the same form.",
@@ -126,7 +126,19 @@ function validateAssistTargets(where, fieldSpec, fieldDef) {
126
126
  // skip: the field is unknown (reported elsewhere)
127
127
  if (fieldDef === undefined)
128
128
  return;
129
- const { aiAssist, valueChips } = fieldSpec;
129
+ const { aiAssist, valueChips, editor } = fieldSpec;
130
+ if (editor !== undefined) {
131
+ if (fieldDef.type !== "longText") {
132
+ throw bootRuleError(FORM_FIELD_RULES.editorFieldType, {
133
+ message: `${where} editor "${editor}" needs a longText field, not "${fieldDef.type}".`,
134
+ });
135
+ }
136
+ if (fieldSpec.fillAction !== undefined || valueChips !== undefined) {
137
+ throw bootRuleError(FORM_FIELD_RULES.editorFieldType, {
138
+ message: `${where} editor "${editor}" cannot be combined with fillAction or valueChips; they target a plain input.`,
139
+ });
140
+ }
141
+ }
130
142
  if (valueChips !== undefined && !VALUE_CHIPS_FIELD_TYPES.includes(fieldDef.type)) {
131
143
  throw bootRuleError(FORM_FIELD_RULES.valueChipsFieldType, {
132
144
  message: `${where} valueChips needs a ${VALUE_CHIPS_FIELD_TYPES.join(", ")} field, not "${fieldDef.type}".`,
@@ -1,7 +1,8 @@
1
- import { isValidQn, parseQn, qualifyEntityName } from "../qualified-name.js";
1
+ import { qualifyEntityName } from "../qualified-name.js";
2
2
  import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { collectScreensByShortId, readsNavigateParamsAsFormPrefill, rowFieldExtractorKeys, validateDrawerPrefillKeys, } from "./screens.js";
5
+ import { findScreenEntryForNavTarget } from "./screens-actions.js";
5
6
  import { SCREEN_RULES } from "./screens-rules.js";
6
7
  function isNavigateKind(action) {
7
8
  return action.kind === undefined || action.kind === "navigate";
@@ -125,21 +126,14 @@ export function collectUrlPrefillFieldsByScreenQn(features) {
125
126
  return result;
126
127
  }
127
128
  // Runtime resolution: a bare screen id matches the first feature registering
128
- // it (create-app's router); an entity target opens its detailFor screen with an id.
129
+ // it (create-app's router), a screen QN the screen of exactly that feature;
130
+ // an entity target opens its detailFor screen with an id.
129
131
  function resolveTarget(source, screensByShortId, detailForByEntity) {
130
132
  if (source.entity !== undefined)
131
133
  return detailForByEntity.get(source.entity);
132
134
  if (source.screen === undefined)
133
135
  return undefined;
134
- if (isValidQn(source.screen)) {
135
- const { scope, type, name } = parseQn(source.screen);
136
- if (type !== "screen")
137
- return undefined;
138
- const match = screensByShortId.get(name)?.find((entry) => entry.featureName === scope);
139
- return match === undefined ? undefined : { ...match, shortId: name };
140
- }
141
- const match = screensByShortId.get(source.screen)?.[0];
142
- return match === undefined ? undefined : { ...match, shortId: source.screen };
136
+ return findScreenEntryForNavTarget(screensByShortId, source.screen);
143
137
  }
144
138
  function assertHiddenRequiredFieldsSeeded(featureName, screenId, screen, seeded) {
145
139
  for (const section of screen.layout.sections) {
@@ -2,6 +2,7 @@ import type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
2
2
  import type { ScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
3
3
  import type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
4
4
  import type { FeatureDefinition } from "../engine/types/index.ts";
5
+ import type { TranslationValue } from "../ui-types/plural.ts";
5
6
  /** Pseudo-entity for actionForm field labels (renderer action-form-shim). */
6
7
  export declare const ACTION_FORM_ENTITY = "__action-form__";
7
8
  /** Pseudo-entity for configEdit field labels (renderer config-edit-shim). */
@@ -38,6 +39,7 @@ export type TranslationLocaleGap = {
38
39
  readonly key: string;
39
40
  readonly missingLocales: readonly string[];
40
41
  };
42
+ export declare function hasLocaleValue(value: TranslationValue | undefined): boolean;
41
43
  /**
42
44
  * Per feature, every translation key must carry every locale that any key of the
43
45
  * same feature carries. A feature with a single locale across all keys is
@@ -223,6 +223,13 @@ function pushToolbarActionKeys(out, action) {
223
223
  pushKey(out, action.subtitle);
224
224
  }
225
225
  }
226
+ function pushPageHelpKeys(out, pageHelp) {
227
+ for (const section of pageHelp?.sections ?? []) {
228
+ pushKey(out, section.title);
229
+ if (section.kind === "text")
230
+ pushKey(out, section.text);
231
+ }
232
+ }
226
233
  function pushRelatedListSectionKeys(out, section) {
227
234
  pushKey(out, section.title);
228
235
  pushKey(out, section.description);
@@ -298,6 +305,7 @@ function collectEntityListKeys(ctx, list) {
298
305
  }
299
306
  }
300
307
  pushListChromeKeys(ctx.out, list);
308
+ pushPageHelpKeys(ctx.out, list.pageHelp);
301
309
  if (list.expandableRow !== undefined)
302
310
  pushExpandableRowKeys(ctx.out, list.expandableRow);
303
311
  }
@@ -430,6 +438,7 @@ function collectProjectionDetailKeys(ctx, detail) {
430
438
  for (const metric of detail.metrics ?? [])
431
439
  pushKey(ctx.out, metric.label);
432
440
  pushKey(ctx.out, detail.header?.narrowTitle);
441
+ pushPageHelpKeys(ctx.out, detail.pageHelp);
433
442
  for (const section of detail.layout.sections) {
434
443
  pushKey(ctx.out, section.tabLabel);
435
444
  if ("descriptionNarrow" in section)
@@ -443,6 +452,7 @@ function collectProjectionDetailKeys(ctx, detail) {
443
452
  }
444
453
  if (section.kind === "relatedList") {
445
454
  pushRelatedListSectionKeys(ctx.out, section);
455
+ pushPageHelpKeys(ctx.out, section.pageHelp);
446
456
  for (const bulk of section.bulkActions ?? [])
447
457
  pushBulkActionKeys(ctx.out, bulk);
448
458
  continue;
@@ -575,7 +585,7 @@ export function buildEffectiveTranslationKeys(features) {
575
585
  }
576
586
  return out;
577
587
  }
578
- function hasLocaleValue(value) {
588
+ export function hasLocaleValue(value) {
579
589
  if (value === undefined)
580
590
  return false;
581
591
  const forms = typeof value === "string" ? [value] : Object.values(value);
@@ -80,7 +80,7 @@ export function piiAnnotationEntries(registry) {
80
80
  // Bump when the backfill gains a transform stage: completed states keyed by the
81
81
  // old fingerprint must run one more full pass. Kept out of piiAnnotationEntries,
82
82
  // whose emptiness gates no_pii.
83
- const PII_BACKFILL_TRANSFORM_VERSION = "jsonb-objects-v3";
83
+ const PII_BACKFILL_TRANSFORM_VERSION = "self-owned-rekey-v4";
84
84
  export function piiAnnotationFingerprint(registry) {
85
85
  return createHash("sha256")
86
86
  .update([...piiAnnotationEntries(registry), PII_BACKFILL_TRANSFORM_VERSION].join("\n"))
@@ -206,6 +206,9 @@ function reportRunOutcome(log, progress) {
206
206
  "backfillEventPiiEncryption(..., { eraseUnresolvableSubjects: true })", {
207
207
  failureCount: progress.failures.length,
208
208
  eventIds: progress.failures.slice(0, MAX_LOGGED_FAILURE_IDS).map((f) => f.eventId),
209
+ failures: progress.failures
210
+ .slice(0, MAX_LOGGED_FAILURE_IDS)
211
+ .map((f) => ({ eventId: f.eventId, reason: f.reason })),
209
212
  });
210
213
  }
211
214
  }
@@ -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, 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";
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, PageHelpSection, PageHelpSpec, PageHelpStatusSection, PageHelpTextSection, 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.419.0",
3
+ "version": "0.420.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.419.0",
207
+ "@cosmicdrift/kumiko-types": "0.420.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.419.0",
229
+ "@cosmicdrift/kumiko-testing": "0.420.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,16 @@
1
1
  [
2
+ {
3
+ "version": "0.420.0",
4
+ "type": "fix",
5
+ "title": "PII event backfill stops growing self-owned personal fields",
6
+ "detail": "A personal field that is its own owner (for example invitedBy) was re-keyed under its own ciphertext on every boot. The backfill now keys it under the decrypted user id, repairs values already keyed wrongly, and logs the failure reason per event."
7
+ },
8
+ {
9
+ "version": "0.420.0",
10
+ "type": "fix",
11
+ "title": "Navigate targets resolve through one shared boot-validator helper",
12
+ "detail": "Navigate targets given as a screen QN or a short id now resolve through one shared boot-validator helper."
13
+ },
2
14
  {
3
15
  "version": "0.419.0",
4
16
  "type": "improvement",