@cosmicdrift/kumiko-framework 0.415.0 → 0.417.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agents/api/framework-engine.md +67 -13
- package/agents/api/framework-ui-types.md +81 -7
- package/agents/api/renderer-web.md +31 -3
- package/agents/api/types.md +114 -61
- package/agents/api.md +1 -1
- package/agents/boot-rules.md +36 -4
- package/agents/examples/dashboard-stats.md +51 -0
- package/agents/examples/embedded.md +24 -1
- package/agents/examples/event-sourcing.md +84 -0
- package/agents/examples/handbook-knowledge.md +129 -0
- package/agents/examples/list-table-options.md +71 -5
- package/agents/examples/managed-config.md +9 -1
- package/agents/examples/record-detail-layout.md +71 -6
- package/agents/examples/secrets-demo.md +3 -1
- package/agents/examples/signature.md +187 -0
- package/agents/examples/writeform-section.md +330 -0
- package/agents/examples.md +2 -0
- package/agents/features-index.md +4 -0
- package/agents/features.md +14 -0
- package/dist/api/server-routes.js +2 -0
- package/dist/db/queries/event-store.d.ts +3 -0
- package/dist/db/queries/event-store.js +12 -0
- package/dist/db/table-builder.js +3 -1
- package/dist/engine/boot-validator/boot-phases.js +5 -0
- package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
- package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
- package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
- package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
- package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
- package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
- package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
- package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
- package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
- package/dist/engine/boot-validator/list-row-guidance.js +31 -0
- package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
- package/dist/engine/boot-validator/list-table-options.js +8 -6
- package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
- package/dist/engine/boot-validator/list-table-rules.js +1 -1
- package/dist/engine/boot-validator/query-output-columns.js +22 -0
- package/dist/engine/boot-validator/query-output-guidance.js +3 -0
- package/dist/engine/boot-validator/query-refs.js +4 -1
- package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
- package/dist/engine/boot-validator/relative-time-format.js +51 -0
- package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
- package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
- package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
- package/dist/engine/boot-validator/screens-actions.js +57 -15
- package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
- package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
- package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
- package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
- package/dist/engine/boot-validator/screens-dashboard.js +2 -1
- package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
- package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
- package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
- package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
- package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
- package/dist/engine/boot-validator/screens-forms.js +108 -2
- package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
- package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
- package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
- package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
- package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
- package/dist/engine/boot-validator/screens-lists.js +4 -1
- package/dist/engine/boot-validator/screens.js +1 -2
- package/dist/engine/bridge-stub.js +1 -0
- package/dist/engine/build-config-feature-schema.js +29 -36
- package/dist/engine/config-access-rules.d.ts +3 -0
- package/dist/engine/config-access-rules.js +34 -0
- package/dist/engine/factories.d.ts +2 -0
- package/dist/engine/project-app-schema-for-roles.js +2 -0
- package/dist/engine/screen-helpers.js +7 -3
- package/dist/event-store/archive.d.ts +1 -0
- package/dist/event-store/archive.js +5 -1
- package/dist/event-store/event-store.d.ts +5 -0
- package/dist/event-store/event-store.js +23 -3
- package/dist/files/file-routes.d.ts +2 -0
- package/dist/files/file-routes.js +85 -22
- package/dist/files/foreign-tenant-file-read.d.ts +13 -0
- package/dist/files/foreign-tenant-file-read.js +64 -0
- package/dist/i18n/required-surface-keys.js +32 -6
- package/dist/pipeline/handler-context-events.js +15 -1
- package/dist/ui-types/card-column-roles.d.ts +3 -0
- package/dist/ui-types/card-column-roles.js +9 -5
- package/dist/ui-types/index.d.ts +1 -1
- package/package.json +3 -3
- package/src/changes.json +48 -0
|
@@ -35,7 +35,7 @@ function createDecimalField<R extends true | false = false>(config: { precision:
|
|
|
35
35
|
function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
|
|
36
36
|
function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
|
|
37
37
|
function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
|
|
38
|
-
function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; systemRowsReadable?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
|
|
38
|
+
function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; systemRowsReadable?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; crossTenantFileRead?: EntityDefinition["crossTenantFileRead"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
|
|
39
39
|
function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
|
|
40
40
|
function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
|
|
41
41
|
function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
|
|
@@ -281,14 +281,19 @@ type ActionFormScreenDefinition = {
|
|
|
281
281
|
fields: Readonly<Record<string, FormFieldDefinition>>; // Form shape: field map by name.
|
|
282
282
|
derive?: Readonly<Record<string, FormFieldDerivation>>; // Fields computed from other fields, shown read-only and recomputed on every change.
|
|
283
283
|
layout: EditLayout; // Layout analogous to EntityEditScreen: sections with fields from the fields map above.
|
|
284
|
-
fieldLabels?: Readonly<Record<string,
|
|
284
|
+
fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Per-field label i18n key override, same type/semantics as `EntityEditScreenDefinition.fieldLabels`.
|
|
285
285
|
submitLabel?: string; // i18n key for the submit button.
|
|
286
286
|
footerActions?: ActionFormFooterAction[]; // Extra buttons in the form footer next to the submit button.
|
|
287
287
|
summary?: {
|
|
288
288
|
title: string;
|
|
289
289
|
subtitle?: string;
|
|
290
290
|
params?: Readonly<Record<string, string>>;
|
|
291
|
+
paramsFromLoad?: string[]; // Fields of the `load` result that fill `{name}` placeholders too (static `params` win).
|
|
291
292
|
}; // Context box above the fields (i18n keys).
|
|
293
|
+
fieldDescriptions?: Readonly<Record<string, FieldTextRef>>; // Help text under a field (field name -> i18n key).
|
|
294
|
+
infoBand?: string; // i18n key of a short note in a banner above the fields, with a sparkles icon (e.g. "the AI prepared everything, read the text, then send").
|
|
295
|
+
fieldBadges?: Readonly<Record<string, { label: string; tone: SelectOptionTone; }>>; // Badge next to a field's label (field name -> `{ label: i18n key, tone }`), e.g. "price source open" in `warn`.
|
|
296
|
+
formErrorOnTop?: boolean; // Shows a failed submit's error banner above the fields instead of below them.
|
|
292
297
|
submitStyle?: "primary" | "danger"; // Visual style of the submit button.
|
|
293
298
|
successMessage?: string; // i18n key of a confirmation shown above the form after a successful submit when the screen stays put (no `redirect`, not drawer-hosted).
|
|
294
299
|
redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful submit: either a short ID (e.g. "item-list" — same feature, the nav-router resolves to the full path) or a fully-qualified cross-feature QN (`<feature>:screen:<id>`).
|
|
@@ -410,6 +415,7 @@ type ConfigEditScreenDefinition = {
|
|
|
410
415
|
fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
|
|
411
416
|
requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
|
|
412
417
|
submitLabel?: string; // i18n key for the submit button.
|
|
418
|
+
compact?: true; // Compact rows: no origin icon, no reset link, no accent bar on changed fields; the form column is capped to a readable width.
|
|
413
419
|
actions?: ConfigEditAction[]; // Handler buttons drawn as their own row after `afterField` (settings-list layout).
|
|
414
420
|
slots?: ScreenSlots;
|
|
415
421
|
access?: AccessRule;
|
|
@@ -530,6 +536,12 @@ type EditFieldSpec =
|
|
|
530
536
|
prefix?: FieldAffix; // Static text shown before the input (i18n key, falls back to the literal), or `{ field }` for the current form value of another field (a hidden field carrying e.g. a base domain).
|
|
531
537
|
suffix?: FieldAffix; // Same as `prefix`, shown after the input.
|
|
532
538
|
fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
|
|
539
|
+
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.
|
|
540
|
+
valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
|
|
541
|
+
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.
|
|
542
|
+
badge?: FieldBadge; // Pill next to the label, e.g. "price source open" in `warn`.
|
|
543
|
+
hintField?: string; // Value field whose non-empty text shows as a muted small hint under the field (e.g. "From the buyer: Skoda Octavia").
|
|
544
|
+
hideOnNarrow?: true; // Leaves the field out below `sm`; its value is still submitted.
|
|
533
545
|
refEntity?: string; // Marks this field as a reference lookup instead of a plain value — for projectionDetail fields, which have no `EntityDefinition` to carry a real `reference` field type.
|
|
534
546
|
refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
|
|
535
547
|
format?: "email" | "phone"; // Text format for projectionDetail fields, which have no `EntityDefinition` to carry it: a read-only value renders as a `mailto:`/`tel:` link.
|
|
@@ -537,8 +549,9 @@ type EditFieldSpec =
|
|
|
537
549
|
prefill?: EditFieldPrefill; // Fills an empty value when the create form opens; the update form and values from URL params or a handoff are never touched.
|
|
538
550
|
}
|
|
539
551
|
;
|
|
540
|
-
type EditRelatedListSection = {
|
|
552
|
+
type EditRelatedListSection = EditSectionPresentation & {
|
|
541
553
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
554
|
+
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`.
|
|
542
555
|
kind: "relatedList";
|
|
543
556
|
title: string;
|
|
544
557
|
readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
|
|
@@ -569,8 +582,14 @@ type EditRelatedListSection = {
|
|
|
569
582
|
count?: true; // Tab badge counted from this section's own query (`limit: 1, totalCount: true` → `total`), so it matches the tab's rows and stays live.
|
|
570
583
|
actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the parent record.
|
|
571
584
|
emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
|
|
572
|
-
|
|
573
|
-
|
|
585
|
+
photoGrid?: {
|
|
586
|
+
imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
|
|
587
|
+
captionField?: string; // Row field printed under the image; without it the tile reads "Photo n".
|
|
588
|
+
badgeField?: string; // Row field whose non-empty text shows as a warn badge on the image's top left.
|
|
589
|
+
badgeFirst?: true; // On a phone (below `sm`) tiles whose `badgeField` has text come first, the rest keep their order; from `sm` up the natural order stays.
|
|
590
|
+
}; // Draws the rows as a tile grid of images instead of a table.
|
|
591
|
+
};
|
|
592
|
+
type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
|
|
574
593
|
type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & { // Resolver callback shape: synchronous (on the dispatcher's hot path), per tenant.
|
|
575
594
|
trialGate?: TrialGate; // Optional live-trial gate, consulted by the dispatcher feature gate ONLY when the synchronous resolver reports a feature as disabled.
|
|
576
595
|
};
|
|
@@ -602,6 +621,10 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
|
|
|
602
621
|
description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
|
|
603
622
|
transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
|
|
604
623
|
attachedFileAccess?: "record-only"; // Attached files are readable only through the record's detail query: the files feature's privilegedRoles do not bypass it, the uploader check stays.
|
|
624
|
+
crossTenantFileRead?: {
|
|
625
|
+
query: string;
|
|
626
|
+
reason: string;
|
|
627
|
+
}; // Files of this entity may be read from another tenant when `query`, run with `{ id: <entityId> }` as the requesting user, returns the record with that id.
|
|
605
628
|
};
|
|
606
629
|
type EntityEditScreenDefinition = {
|
|
607
630
|
id: string;
|
|
@@ -628,7 +651,7 @@ type EntityEditScreenDefinition = {
|
|
|
628
651
|
singleton?: boolean; // Default false.
|
|
629
652
|
redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful save (create or update).
|
|
630
653
|
listScreenId?: string; // Parent list screen (short id) for breadcrumb + nav highlighting when this screen has no nav entry of its own.
|
|
631
|
-
fieldLabels?: Readonly<Record<string,
|
|
654
|
+
fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
|
|
632
655
|
actions?: EntityEditAction[]; // Record actions.
|
|
633
656
|
slots?: ScreenSlots;
|
|
634
657
|
access?: AccessRule;
|
|
@@ -651,6 +674,7 @@ type EntityListScreenDefinition = {
|
|
|
651
674
|
allowCreate?: boolean; // `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action.
|
|
652
675
|
columns: ListColumnSpec[];
|
|
653
676
|
rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
|
|
677
|
+
mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
|
|
654
678
|
rowDecoration?: ListRowDecoration; // Computed row fields from an app query, readable by `rowToneField`, column `hint`, `linkScreenField`/`linkParamsField` and rowAction `visible`/`params`/`payload`; a column may name a decoration field.
|
|
655
679
|
rowRenderer?: PlatformComponent;
|
|
656
680
|
rowActions?: RowAction[]; // Per-row actions, rendered as an actions column on the right.
|
|
@@ -858,10 +882,18 @@ interface FieldFormatRegistry {
|
|
|
858
882
|
timeStyle?: "full" | "long" | "medium" | "short";
|
|
859
883
|
timeZone?: string; // IANA zone id (e.g. "Europe/Berlin").
|
|
860
884
|
};
|
|
885
|
+
relativeTime: {
|
|
886
|
+
locale?: string;
|
|
887
|
+
style?: "long" | "short" | "narrow";
|
|
888
|
+
absoluteAfterDays?: number;
|
|
889
|
+
withTime?: boolean;
|
|
890
|
+
timeZone?: string; // IANA zone id for the clock time and the day boundary.
|
|
891
|
+
}; // Epoch ms or ISO timestamp, shown as "5 min.
|
|
861
892
|
date: {
|
|
862
893
|
locale?: string;
|
|
863
894
|
dateStyle?: "full" | "long" | "medium" | "short";
|
|
864
895
|
};
|
|
896
|
+
phone: Record<never, never>; // Telephone number shown as a `tel:` link in list cells, like a read-only `format: "phone"` field.
|
|
865
897
|
boolean: {
|
|
866
898
|
trueLabel?: string;
|
|
867
899
|
falseLabel?: string;
|
|
@@ -943,6 +975,7 @@ type HandlerEvents<TMap extends object = KumikoEventTypeMap> = { // Event-store
|
|
|
943
975
|
tryAppend: TryAppendEventFn; // Optimistic append: runs in a savepoint and returns a version conflict as a result instead of throwing, so the handler can continue after losing a race on the same aggregate stream.
|
|
944
976
|
fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
|
|
945
977
|
load: (aggregateId: string, options?: { asOf?: Temporal.Instant; atVersion?: never; includeArchived?: boolean; } | { atVersion?: number; asOf?: never; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
|
|
978
|
+
loadByTypes: (args: { aggregateIds: string[]; eventTypes: string[]; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
|
|
946
979
|
archive: (aggregateId: string, args: { aggregateType: string; reason?: string; }) => Promise<void>;
|
|
947
980
|
restore: (aggregateId: string) => Promise<void>;
|
|
948
981
|
isArchived: (aggregateId: string) => Promise<boolean>;
|
|
@@ -1049,17 +1082,29 @@ type ListColumnSpec =
|
|
|
1049
1082
|
refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
|
|
1050
1083
|
sortable?: boolean; // Marks this column as sortable via a clickable header — for relatedList columns, which have no `EntityDefinition` field to carry `sortable` on.
|
|
1051
1084
|
valueType?: "number" | "decimal" | "bigInt" | "money"; // Value type of a projectionList or relatedList column, which has no `EntityDefinition` field to derive it from.
|
|
1052
|
-
emptyPlaceholder?: false; //
|
|
1053
|
-
hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (
|
|
1085
|
+
emptyPlaceholder?: string | false; // An empty cell stays blank by default; a string (i18n key or literal) is shown muted in its place, e.g. "No vehicle".
|
|
1086
|
+
hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (phone viewport).
|
|
1087
|
+
hideWhenDocked?: true; // Leaves the column out of a table whose container is narrower than `md` (docked assistant panel); the viewport is not looked at, so the phone card still shows it.
|
|
1054
1088
|
showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
|
|
1055
1089
|
narrowInline?: true; // In the compact card, consecutive `narrowInline` columns stand side by side on one line (12px gap, no separator) instead of one line each.
|
|
1090
|
+
ellipsis?: true; // One line with a trailing ellipsis in the table; the full text is the cell's `title`.
|
|
1091
|
+
multiline?: true; // Free text: the cell wraps instead of ending in "…", and a line break (`\n`) in the value starts a new line (table and phone card).
|
|
1092
|
+
cardAbove?: true; // Phone card: the column's line stands above the title (muted, e.g. "date, channel") instead of below it.
|
|
1093
|
+
emphasis?: true; // Cell text in medium weight and foreground colour, like the title column of a board.
|
|
1094
|
+
tone?: "muted"; // `"muted"` draws every cell of the column in the muted text colour (e.g. a free-text message beside primary columns).
|
|
1095
|
+
cardBadge?: true; // The phone card shows this column as its badge: right of the title, as an outlined neutral pill (a `display: "badge"` column keeps its own pill).
|
|
1096
|
+
dateOnlyAfterDays?: number; // Timestamp or relativeTime column: a value older than this many days shows the date only, without the time.
|
|
1056
1097
|
hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
|
|
1057
1098
|
pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
|
|
1058
1099
|
width?: number; // Start width in px.
|
|
1059
1100
|
minWidth?: number; // Smallest width in px the user can resize to.
|
|
1060
1101
|
display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
|
|
1061
|
-
|
|
1102
|
+
variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
|
|
1103
|
+
badgeToneField?: string; // Row field naming the badge tone: a `ListBadgeTone` word or a `SelectOptionTone` word (`ok`, `bad`, `critical`, `accent`); only with `display: "badge"`.
|
|
1062
1104
|
badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
|
|
1105
|
+
badgeIcon?: "sparkles"; // `"sparkles"` marks an AI-prepared value: the dashboard list draws the badge as the soft blue AI pill with a sparkles icon, like an AI row action; only with `display: "badge"`.
|
|
1106
|
+
pillField?: string; // Row field holding a second label, drawn as a pill next to the cell's own value (e.g. a vehicle name with a "free" pill).
|
|
1107
|
+
pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
|
|
1063
1108
|
linkScreenField?: string; // Row field holding a screen QN (`<feature>:screen:<id>`): the cell links to that screen when the row sets it and the user may open it.
|
|
1064
1109
|
linkParamsField?: string; // Row field holding a params object for the linkScreenField target: `entityId` opens that record, the other keys become search params (e.g. actionForm prefill).
|
|
1065
1110
|
hint?: ListColumnHint; // "To do" cell: the column's field holds a sentence, shown emphasized in the row tone; an empty value shows `emptyLabel`.
|
|
@@ -1383,8 +1428,11 @@ type ProjectionDetailScreenDefinition = {
|
|
|
1383
1428
|
metrics?: MetricSpec[]; // Metric band above the layout — column names in the query row, each with its own i18n `label`.
|
|
1384
1429
|
metricsStyle?: "band" | "tiles"; // "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band.
|
|
1385
1430
|
metricsPlacement?: {
|
|
1386
|
-
narrow?: "after-guidance";
|
|
1387
|
-
}; // `narrow: "after-guidance"` moves the metrics below the summary, banner and steps
|
|
1431
|
+
narrow?: "after-guidance" | "before-steps";
|
|
1432
|
+
}; // On screens under md, `narrow: "after-guidance"` moves the metrics below the summary, banner and steps, ahead of the tabs; `"before-steps"` puts them below the summary and banner, ahead of the next step.
|
|
1433
|
+
mobileSummary?: string; // Record field holding one line of text shown instead of the metrics below `sm`.
|
|
1434
|
+
pageNavigation?: false; // `false` leaves out the "On this page" navigation of a stacked (non-tabs) layout.
|
|
1435
|
+
photosBeside?: true; // A tab holding fields sections and a relatedList with `photoGrid` shows the fields left and the photos right from `lg` up.
|
|
1388
1436
|
breadcrumb?: RecordBreadcrumbSpec; // Path above the header (query column holding items).
|
|
1389
1437
|
summary?: RecordSummarySpec; // One emphasized sentence below the header.
|
|
1390
1438
|
banner?: RecordBannerSpec; // Notice below the summary.
|
|
@@ -1393,9 +1441,12 @@ type ProjectionDetailScreenDefinition = {
|
|
|
1393
1441
|
listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
|
|
1394
1442
|
slots?: ScreenSlots;
|
|
1395
1443
|
access?: AccessRule;
|
|
1396
|
-
actions?:
|
|
1444
|
+
actions?: EntityEditAction[]; // Header action buttons.
|
|
1397
1445
|
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).
|
|
1398
1446
|
inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
|
|
1447
|
+
footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
|
|
1448
|
+
footerHint?: string; // i18n key of a note on the left of the footer bar ("Changes go out with the release"); hidden below `sm`.
|
|
1449
|
+
initialTab?: ProjectionDetailInitialTab[]; // Tab that opens first when the URL names none: the first rule whose condition holds on the record wins, else the first visible tab.
|
|
1399
1450
|
valueDisplay?: "form" | "text"; // How head fields render.
|
|
1400
1451
|
};
|
|
1401
1452
|
type ProjectionListScreenDefinition = {
|
|
@@ -1412,6 +1463,7 @@ type ProjectionListScreenDefinition = {
|
|
|
1412
1463
|
query: string;
|
|
1413
1464
|
columns: ListColumnSpec[];
|
|
1414
1465
|
rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
|
|
1466
|
+
mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
|
|
1415
1467
|
rowDecoration?: ListRowDecoration; // Computed row fields from an app query, merged into the query rows; see `ListRowDecoration`.
|
|
1416
1468
|
rowRenderer?: PlatformComponent;
|
|
1417
1469
|
rowActions?: RowAction[];
|
|
@@ -1584,7 +1636,9 @@ type RoleAccessRule = {
|
|
|
1584
1636
|
personalData?: RoleAccessPersonalData;
|
|
1585
1637
|
anySignedIn?: true;
|
|
1586
1638
|
};
|
|
1587
|
-
type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction
|
|
1639
|
+
type RowAction = (RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction) & {
|
|
1640
|
+
align?: "start"; // projectionDetail `footerActions` only: "start" sets the button apart on the left of the footer.
|
|
1641
|
+
};
|
|
1588
1642
|
type RowActionWriteHandler = {
|
|
1589
1643
|
kind?: "writeHandler"; // Default for RowActions without an explicitly set `kind` — backwards-compatible form.
|
|
1590
1644
|
id: string; // Stable id per screen — kebab-case, unique within the action set.
|
|
@@ -65,11 +65,13 @@ type ActionFormLoad = {
|
|
|
65
65
|
query: string; // Query QN that returns the record.
|
|
66
66
|
idParam?: string; // Payload key carrying the record id (default "id").
|
|
67
67
|
singleton?: boolean; // The query picks the row from the caller's tenant/session context, so the form loads without a record id and the query is called WITHOUT `idParam` (same semantics as `ProjectionDetailScreenDefinition.singleton`).
|
|
68
|
+
passPrefill?: boolean; // Sends the values a drawer opens the form with (row-action params, e.g. `vehicleId`) in the load payload next to `idParam`, so the query can pre-fill for the chosen item.
|
|
68
69
|
};
|
|
69
70
|
type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
|
|
70
71
|
screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
|
|
71
|
-
idFrom
|
|
72
|
+
idFrom?: string; // Flat field name in the handler's success payload, e.g. "leaseId".
|
|
72
73
|
tab?: string; // Section id to open on the target `projectionDetail` with `layout.mode: "tabs"` (the `tab` search param, same as `ToolbarAction` navigate `tab`).
|
|
74
|
+
searchParams?: Readonly<Record<string, string>>; // URL search params of the target, each read from a flat success-payload field (`{ cmd: "threadId" }` opens `?cmd=<threadId>`).
|
|
73
75
|
};
|
|
74
76
|
type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
|
|
75
77
|
field: string; // Flat field name in the handler's success payload.
|
|
@@ -79,7 +81,7 @@ type ActionFormSuccessItems = { // Per-entry hints of the success box, read from
|
|
|
79
81
|
field: string; // Flat field name of an array in the success payload.
|
|
80
82
|
link?: ActionFormSuccessLink; // Link of each hint.
|
|
81
83
|
};
|
|
82
|
-
type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & { // A redirect target rendered as a link in the success box.
|
|
84
|
+
type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom" | "searchParams"> & { // A redirect target rendered as a link in the success box.
|
|
83
85
|
idFrom?: string; // Success-payload field carrying the navigation id.
|
|
84
86
|
params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
|
|
85
87
|
label: string; // Link text (i18n key).
|
|
@@ -152,6 +154,7 @@ type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState
|
|
|
152
154
|
id: string;
|
|
153
155
|
label: string;
|
|
154
156
|
query: string;
|
|
157
|
+
showTotal?: true | Pick<DashboardListShowTotal, "text">; // Shows the count in the panel head, right-aligned like a list panel's `showTotal`: `{total}` is the query's `total`, else the rows returned.
|
|
155
158
|
};
|
|
156
159
|
type DashboardFilterDefinition = {
|
|
157
160
|
id: string;
|
|
@@ -162,8 +165,9 @@ type DashboardFilterDefinition = {
|
|
|
162
165
|
options?: { value: string; label: string; }[];
|
|
163
166
|
optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
|
|
164
167
|
};
|
|
168
|
+
type DashboardLayout = "main-side"; // "main-side": from `lg` up the main column (2/3) stacks every panel without `column`, the side column (1/3) every `column: "side"` panel, each with its own heights; `column: "top"` panels span both columns above them; below `lg` they stack, below `sm` by `narrowOrder`.
|
|
165
169
|
type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
|
|
166
|
-
label
|
|
170
|
+
label?: string; // i18n key of the link text.
|
|
167
171
|
moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
|
|
168
172
|
narrowMoreText?: string; // i18n key used instead of `moreText` below `sm`.
|
|
169
173
|
narrowOnly?: boolean; // Draw the link only below `sm`, where it is the target of the "line" layout; from `sm` up the panel shows no footer link.
|
|
@@ -200,6 +204,7 @@ type DashboardMoneyParam = { // Minor units (like Money fields), formatted with
|
|
|
200
204
|
amountMinor: number;
|
|
201
205
|
currency: string;
|
|
202
206
|
};
|
|
207
|
+
type DashboardPanelColumn = "side" | "top"; // "top" spans both columns above the main and side column, in declared order.
|
|
203
208
|
type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
|
|
204
209
|
type DashboardPanelEmptyState = {
|
|
205
210
|
span?: DashboardPanelSpan;
|
|
@@ -209,6 +214,7 @@ type DashboardPanelEmptyState = {
|
|
|
209
214
|
type DashboardPanelNarrow = { // Phone layout switch shared by every panel kind.
|
|
210
215
|
hideOnNarrow?: true; // Leaves the panel out below the `sm` breakpoint (phone).
|
|
211
216
|
narrowOrder?: number; // Position below `sm`, like CSS `order`: panels are laid out by ascending value, a panel without one counts as 0, equal values keep the declared order.
|
|
217
|
+
column?: DashboardPanelColumn; // "side" puts the panel in the narrow right column of a `layout: "main-side"` dashboard, "top" in a full-width block above both columns; panels without it fill the main column.
|
|
212
218
|
};
|
|
213
219
|
type DashboardPanelQueryOptions = {
|
|
214
220
|
params?: Readonly<Record<string, unknown>>; // Static, author-set query parameters merged on top of the screen's dynamic filterParams — lets a panel pin a value (e.g. a status facet) the screen-wide filter doesn't cover, without needing its own query.
|
|
@@ -224,6 +230,8 @@ type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmp
|
|
|
224
230
|
kind: "progress-list";
|
|
225
231
|
id: string;
|
|
226
232
|
label: string;
|
|
233
|
+
labelParams?: Readonly<Record<string, string>>; // Fills the translated `label` from the query answer: maps a label placeholder to a top-level answer field, e.g. `{ month: "monthName" }` for "Quota {month}" with `{ rows, monthName: "November" }`.
|
|
234
|
+
subtitleField?: string; // Top-level answer field holding a text shown muted at the right end of the panel head, e.g. the period ("November").
|
|
227
235
|
query: string;
|
|
228
236
|
};
|
|
229
237
|
type DashboardProgressTone = "default" | "danger";
|
|
@@ -254,6 +262,7 @@ type DashboardScreenDefinition = {
|
|
|
254
262
|
visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
|
|
255
263
|
fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
|
|
256
264
|
panels: DashboardPanelDefinition[];
|
|
265
|
+
layout?: DashboardLayout; // Panel arrangement, see DashboardLayout.
|
|
257
266
|
record?: DashboardRecordBinding; // Binds the dashboard to one record via a URL search param, see DashboardRecordBinding.
|
|
258
267
|
actions?: RowAction[]; // Header actions on the bound record (writeHandler, navigate, clientAction).
|
|
259
268
|
refresh?: DashboardRefresh;
|
|
@@ -303,6 +312,7 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & Dash
|
|
|
303
312
|
valueField: string;
|
|
304
313
|
labelField?: string; // Field of the query answer holding the label text, e.g. "Contracts ending by 31.01.2027"; it replaces the static `label` while it holds a non-empty string.
|
|
305
314
|
narrowLabel?: string; // i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests").
|
|
315
|
+
labelNarrow?: string; // i18n key replacing `label` below the `sm` breakpoint wherever the stat draws its label (a dynamic `labelField` text still wins).
|
|
306
316
|
subField?: string;
|
|
307
317
|
toneField?: string;
|
|
308
318
|
valueFormat?: DashboardValueFormat; // Formats a numeric value as currency (minor units) or, with `relativeTime`, as a ticking "5 minutes ago" from epoch ms; ignored for string values.
|
|
@@ -353,6 +363,7 @@ type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & Dash
|
|
|
353
363
|
kind: "text";
|
|
354
364
|
id: string;
|
|
355
365
|
label?: string; // Panel title (i18n key).
|
|
366
|
+
icon?: PlatformComponent; // Icon shown before the text blocks (resolved like `DashboardStatGroupPanel.icon`).
|
|
356
367
|
span?: DashboardPanelSpan;
|
|
357
368
|
query?: string; // Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
|
|
358
369
|
blocks?: DashboardTextBlock[];
|
|
@@ -368,8 +379,9 @@ type DerivedCellRoundingTarget = {
|
|
|
368
379
|
type: EmbeddedSubFieldDef["type"];
|
|
369
380
|
scale?: number;
|
|
370
381
|
};
|
|
371
|
-
type EditExtensionSection = {
|
|
382
|
+
type EditExtensionSection = EditSectionPresentation & {
|
|
372
383
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
384
|
+
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`.
|
|
373
385
|
kind: "extension";
|
|
374
386
|
title: string;
|
|
375
387
|
description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
|
|
@@ -387,8 +399,10 @@ type EditLayout = {
|
|
|
387
399
|
sections: EditSectionSpec[];
|
|
388
400
|
width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
|
|
389
401
|
mode?: "single" | "wizard" | "tabs"; // Default "single".
|
|
402
|
+
narrowTabs?: false; // `false` (tabs mode): below `sm` there is no tab strip, the visible sections of every tab stand one under the other.
|
|
390
403
|
variant?: "form" | "settings-list"; // "settings-list" lays each section out as a band with a title column on the left and one hairline-separated row per field (label + help left, control right) — the familiar settings pattern, for screens that are a list of independent preferences rather than one record form.
|
|
391
404
|
hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
|
|
405
|
+
allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
|
|
392
406
|
draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
|
|
393
407
|
wizard?: {
|
|
394
408
|
aside?: {
|
|
@@ -399,17 +413,28 @@ type EditLayout = {
|
|
|
399
413
|
submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
|
|
400
414
|
}; // Wizard layouts only.
|
|
401
415
|
};
|
|
402
|
-
type
|
|
416
|
+
type EditStepListSection = EditSectionPresentation & { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
|
|
417
|
+
id?: string;
|
|
418
|
+
visibleWhen?: Exclude<FieldCondition, boolean>;
|
|
419
|
+
kind: "stepList";
|
|
420
|
+
title?: string;
|
|
421
|
+
field: string; // Output field of the detail query holding a `StepListItem[]`.
|
|
422
|
+
actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
|
|
423
|
+
};
|
|
424
|
+
type EditWriteFormSection = EditSectionPresentation & {
|
|
403
425
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
426
|
+
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`.
|
|
404
427
|
kind: "writeForm";
|
|
405
428
|
title?: string;
|
|
406
429
|
description?: string;
|
|
430
|
+
descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
|
|
407
431
|
columns?: number;
|
|
408
432
|
icon?: IconKey;
|
|
409
433
|
fieldDefs: Readonly<Record<string, FieldDefinition>>; // Field-type map for this section's own form — same shape as `ActionFormScreenDefinition.fields`.
|
|
410
434
|
fields: EditFieldSpec[]; // Rendered fields, in order — same shape as `EditFieldsSection.fields`.
|
|
411
435
|
handler: string; // Write-handler QN dispatched on submit.
|
|
412
436
|
submitLabel?: string; // i18n-key for the submit button.
|
|
437
|
+
submitWith?: string; // Id of a writeHandler action in the screen's `actions`.
|
|
413
438
|
actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
|
|
414
439
|
};
|
|
415
440
|
type EmbeddedDerivedCellDef = ({ op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; } | { op: "inRange"; from: string[]; inside: string; outside: string; }) & { // A cell computed from other cells of the same row.
|
|
@@ -447,6 +472,31 @@ type FieldAffix =
|
|
|
447
472
|
field: string;
|
|
448
473
|
}
|
|
449
474
|
;
|
|
475
|
+
type FieldAiAssist = {
|
|
476
|
+
query: string; // Qualified query name, run with the form's context payload (the `load` id of an actionForm, else the drawer row's prefill values) plus the `params` of the active chips.
|
|
477
|
+
resultField: string; // Key in the query result written into the field; the value must be a string.
|
|
478
|
+
noteField?: string; // Key in the query result with a short note for the user (e.g. "could not rewrite, draft unchanged").
|
|
479
|
+
contextFields?: string[]; // Other fields of the same form whose current values are sent in the payload (under their field names).
|
|
480
|
+
chips?: FieldAiAssistChip[];
|
|
481
|
+
prompt?: {
|
|
482
|
+
param: string;
|
|
483
|
+
placeholder?: string; // i18n key of the input's placeholder.
|
|
484
|
+
}; // Adds an input where the user types a free instruction; it is sent under `param`.
|
|
485
|
+
};
|
|
486
|
+
type FieldAiAssistChip = { // One toggle chip: while active, its `params` are merged into the query payload.
|
|
487
|
+
label: string; // i18n key of the chip label.
|
|
488
|
+
params: Readonly<Record<string, string | number | boolean>>;
|
|
489
|
+
};
|
|
490
|
+
type FieldBadge = // Pill next to a field label: a fixed i18n `label`, or the text of another value `field`.
|
|
491
|
+
| {
|
|
492
|
+
label: string;
|
|
493
|
+
tone: SelectOptionTone;
|
|
494
|
+
}
|
|
495
|
+
| {
|
|
496
|
+
field: string;
|
|
497
|
+
tone: SelectOptionTone;
|
|
498
|
+
}
|
|
499
|
+
;
|
|
450
500
|
type FieldFillAction = {
|
|
451
501
|
label: string; // i18n key (falls back to the literal) of the button label.
|
|
452
502
|
query: string; // Qualified query name, run with the current form values picked by `params`.
|
|
@@ -455,6 +505,16 @@ type FieldFillAction = {
|
|
|
455
505
|
};
|
|
456
506
|
type FieldIconKey = "mail" | "lock" | "hash" | "search" | "user" | "phone" | "calendar" | "link" | "tag" | "building" | "globe" | "key" | "map-pin";
|
|
457
507
|
type FieldRenderer = PlatformComponent | string | FormatSpec;
|
|
508
|
+
type FieldTextRef = // A label or help text: an i18n key, or a key whose `{placeholder}`s are filled from form values.
|
|
509
|
+
| string
|
|
510
|
+
| {
|
|
511
|
+
key: string;
|
|
512
|
+
params: Readonly<Record<string, string>>;
|
|
513
|
+
}
|
|
514
|
+
;
|
|
515
|
+
type FieldValueChips = {
|
|
516
|
+
from: string; // Name of a field of the same form whose value is an array of numbers.
|
|
517
|
+
};
|
|
458
518
|
type FormDerivationScreen = {
|
|
459
519
|
fields: Readonly<Record<string, FormFieldDefinition>>;
|
|
460
520
|
derive?: Readonly<Record<string, FormFieldDerivation>>;
|
|
@@ -508,11 +568,16 @@ type PlatformComponent = {
|
|
|
508
568
|
react?: unknown;
|
|
509
569
|
native?: unknown;
|
|
510
570
|
};
|
|
571
|
+
type ProjectionDetailInitialTab = { // One `initialTab` rule: `tab` is a section id of the layout.
|
|
572
|
+
when: Exclude<FieldCondition, boolean>;
|
|
573
|
+
tab: string;
|
|
574
|
+
};
|
|
511
575
|
type QualifiedContentCollection = ContentCollectionDefinition & {
|
|
512
576
|
navQn: string;
|
|
513
577
|
};
|
|
514
578
|
type RecordBannerSpec = {
|
|
515
579
|
field: string; // Holds `RecordNotice | null`; null shows no banner.
|
|
580
|
+
iconless?: true; // Draws the notice without the tone icon.
|
|
516
581
|
actions?: RecordGuidanceAction[];
|
|
517
582
|
};
|
|
518
583
|
type RecordBreadcrumbItem = {
|
|
@@ -575,12 +640,15 @@ type RecordStepsSpec = {
|
|
|
575
640
|
emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
|
|
576
641
|
narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
|
|
577
642
|
narrowMoreLabel?: string; // Plural base key for the toggle of the hidden rest: define `<key>.one` and `<key>.other` (the latter with `{count}`).
|
|
643
|
+
moreActionsLabel?: string; // i18n key of a short label before each step's further actions ("Clarify first?").
|
|
644
|
+
visibleWhen?: Exclude<FieldCondition, boolean>; // The whole panel is drawn only while the condition holds on the record.
|
|
578
645
|
actions?: RecordGuidanceAction[];
|
|
579
646
|
};
|
|
580
647
|
type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
|
|
581
648
|
field: string;
|
|
582
649
|
toneField?: string; // Row field holding a SelectOptionTone for the sentence's accent.
|
|
583
650
|
narrowField?: string; // Row field with a shorter sentence shown instead of `field` below `sm`.
|
|
651
|
+
icon?: IconKey; // Draws the sentence as plain text led by this icon (e.g. "sparkles" for an AI statement) instead of the bordered box.
|
|
584
652
|
};
|
|
585
653
|
type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
|
|
586
654
|
variants?: RelatedListEmptyStateVariant[];
|
|
@@ -607,9 +675,9 @@ type RowActionClientAction = {
|
|
|
607
675
|
style?: "primary" | "secondary" | "danger"; // Visual style.
|
|
608
676
|
icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
|
|
609
677
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
610
|
-
successMessage?: string; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`).
|
|
678
|
+
successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
|
|
611
679
|
};
|
|
612
|
-
type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
|
|
680
|
+
type RowActionDisplay = "button" | "link" | "icon" | "responsive" | "text"; // How a row action renders inline in the row-action column.
|
|
613
681
|
type RowActionDrawer = {
|
|
614
682
|
kind: "drawer";
|
|
615
683
|
id: string;
|
|
@@ -678,6 +746,12 @@ type SecretsEditScreenDefinition = {
|
|
|
678
746
|
access?: AccessRule;
|
|
679
747
|
};
|
|
680
748
|
type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
|
|
749
|
+
type StepListItem = { // One step of an `EditStepListSection`; `status` renders as a pill in `statusTone`.
|
|
750
|
+
title: string;
|
|
751
|
+
status?: string;
|
|
752
|
+
statusTone?: SelectOptionTone;
|
|
753
|
+
description?: string;
|
|
754
|
+
};
|
|
681
755
|
type TextFieldDef = PiiAndFieldState & {
|
|
682
756
|
type: "text";
|
|
683
757
|
description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
|
|
@@ -50,7 +50,7 @@ function FileViewAction(props: { fileId: string; }): ReactNode; // "View" action
|
|
|
50
50
|
function FloatingPanel(props: FloatingPanelProps): ReactNode; // Non-modal panel floating above the page: draggable by its header, resizable from all edges and corners, clamped to the viewport, geometry optionally remembered.
|
|
51
51
|
function FormScreenShell(props: { children: ReactNode; className?: string; testId?: string; maxWidth?: FormScreenShellWidth; fillHeight?: boolean; }): ReactNode;
|
|
52
52
|
function HeaderActionGroup(props: HeaderActionGroupProps): ReactNode;
|
|
53
|
-
function HeaderActionPinned(props: { children: ReactNode; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
|
|
53
|
+
function HeaderActionPinned(props: { children: ReactNode; hideOnListScreens?: boolean; }): ReactNode; // Marks an app header action (e.g. the assistant trigger) that stays in the bar on a phone, next to the bell; the rest of `headerActions` folds into the "…" menu.
|
|
54
54
|
function HtmlMailFrame(props: { html: string; title: string; allowRemoteImages: boolean; testId?: string; }): ReactNode; // Renders server-sanitized mail HTML in a script-free sandboxed iframe that grows to its content.
|
|
55
55
|
function Icon(props: { name: NavIconKey; className?: string; }): ReactNode;
|
|
56
56
|
function InfinityList<TData = unknown, TRow = Readonly<Record<string, unknown>>>(props: InfinityListProps<TData, TRow>): ReactNode; // Cursor-paginated scroll list (mail inbox, activity feeds) — loads the next page when the end sentinel becomes visible (IntersectionObserver), instead of a pager bar like QueryTable/entityList.
|
|
@@ -262,7 +262,7 @@ type AvatarProps = {
|
|
|
262
262
|
type AvatarShape = "square" | "round";
|
|
263
263
|
type AvatarSize = "xs" | "sm" | "md" | "lg";
|
|
264
264
|
type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
|
|
265
|
-
variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done").
|
|
265
|
+
variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok" | "assist"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`), "ok" for a completed state (e.g. "Done"), "assist" for an AI hint: soft primary surface, primary text, no border.
|
|
266
266
|
inline?: boolean; // Title and text run on one line (text right behind the bold title); the text is dropped below sm, so a phone shows title and actions only.
|
|
267
267
|
density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
|
|
268
268
|
icon?: NavIconKey; // Icon left of the text.
|
|
@@ -378,6 +378,8 @@ type CorePrimitives = {
|
|
|
378
378
|
MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
|
|
379
379
|
RecordBreadcrumb?: ComponentType<RecordBreadcrumbProps>; // Optional — without it the detail screen renders the path as plain links.
|
|
380
380
|
RecordSummary?: ComponentType<RecordSummaryProps>; // Optional — without it the summary renders as plain text.
|
|
381
|
+
PhotoGrid?: ComponentType<PhotoGridProps>; // Optional — without it a relatedList with `photoGrid` falls back to its table.
|
|
382
|
+
StepList?: ComponentType<StepListProps>; // Optional — without it a stepList section renders nothing.
|
|
381
383
|
RecordSteps?: ComponentType<RecordStepsProps>; // Optional — without it the steps render as a plain card.
|
|
382
384
|
ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
|
|
383
385
|
SecretReveal?: ComponentType<SecretRevealProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
|
|
@@ -443,6 +445,7 @@ type DataTableProps = DataTableTableBlock & {
|
|
|
443
445
|
columns: ListColumnViewModel[];
|
|
444
446
|
rows: ListRowViewModel[];
|
|
445
447
|
rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
|
|
448
|
+
rowMuted?: (row: ListRowViewModel) => boolean; // Draws the whole row in the muted text colour.
|
|
446
449
|
onRowClick?: (row: ListRowViewModel) => void;
|
|
447
450
|
sort?: DataTableSort | null; // Current sorting, or null when unsorted.
|
|
448
451
|
onSortChange?: (next: DataTableSort | null) => void; // Called with the next sort state after a header click (asc → desc → null); the caller updates URL state or the query parameter and refetches.
|
|
@@ -480,6 +483,8 @@ type DataTableProps = DataTableTableBlock & {
|
|
|
480
483
|
getCellTestId?: (row: ListRowViewModel, field: string) => string; // Overrides the cell `data-testid` (default `cell-${row.id}-${field}`).
|
|
481
484
|
chromeless?: boolean; // Drops the table's own rounded/border/card background — for a host that already provides the surrounding boundary (a tab panel) and would otherwise show a card nested inside that boundary.
|
|
482
485
|
scrollBody?: boolean; // Fills the available height of its flex container and scrolls rows internally instead of growing with row count — for a host that would otherwise have a long table stretch the whole page, or a short table leave dead space below it (a tab panel).
|
|
486
|
+
hideCountFooter?: boolean; // Drops the "n entries" footer of a `scrollBody` table (a pager stays).
|
|
487
|
+
plainPhoneCards?: boolean; // Phone cards as a plain feed: no sort line, the above-title meta joined with commas, the last meta line in the text colour.
|
|
483
488
|
screenPadding?: boolean; // Uses the shared screen padding (wider bottom inset) instead of the table's symmetric embedded inset — for a table that IS the screen body (entityList/projectionList), so a list screen ends at the same footer distance as a form or custom screen.
|
|
484
489
|
expandedRowIds?: ReadonlySet<string>; // Ids of the rows whose expansion area is currently open (controlled by the host; several rows can be open at once).
|
|
485
490
|
onToggleRowExpanded?: (rowId: string) => void; // User toggled a row's expand control.
|
|
@@ -672,12 +677,14 @@ type FormProps = { // Submit wrapper.
|
|
|
672
677
|
title: string;
|
|
673
678
|
subtitle?: string;
|
|
674
679
|
}; // Drawer-hosted forms: context box above the fields.
|
|
680
|
+
topBanner?: ReactNode; // Rendered above everything else in the form body (above `summary`), e.g. the submit error.
|
|
675
681
|
sectionNav?: FormSectionNavItem[]; // Titled sections for the "on this page" navigation next to a `screenForm`.
|
|
676
682
|
sideRail?: ReactNode; // Leading column next to the scroll surface of a `screenForm` (wizard step navigation).
|
|
677
683
|
};
|
|
678
684
|
type GridCellProps = { // Span wrapper for a child within a grid.
|
|
679
685
|
span?: number;
|
|
680
686
|
width?: FieldCellWidth; // Only read inside a `flow` grid.
|
|
687
|
+
hideOnNarrow?: boolean; // Hidden below the `sm` breakpoint.
|
|
681
688
|
children: ReactNode;
|
|
682
689
|
};
|
|
683
690
|
type GridProps = { // Column-based layout.
|
|
@@ -688,6 +695,8 @@ type GridProps = { // Column-based layout.
|
|
|
688
695
|
flow?: boolean; // Fields flow left to right in wrapping rows sized by `GridCell.width` instead of equal-width tracks (screen forms and drawers).
|
|
689
696
|
list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
|
|
690
697
|
ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
|
|
698
|
+
tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
|
|
699
|
+
facts?: boolean; // Read-only label/value facts: a true `columns`-wide grid with a tight gap, at most 2 columns below `sm`.
|
|
691
700
|
};
|
|
692
701
|
type HeaderActionGroupProps = {
|
|
693
702
|
children: ReactNode;
|
|
@@ -1332,6 +1341,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1332
1341
|
onDirtyChange?: (dirty: boolean) => void; // Fires when the form gains or loses unsaved input (field changes or a dirty extension section).
|
|
1333
1342
|
onCopyLink?: () => Promise<void> | void; // Copy-link action — only set in update mode (create mode has no entity id yet, hence no permalink).
|
|
1334
1343
|
actions?: RenderEditAction[]; // Header action buttons, rendered before the built-in copy-link/ delete/cancel/save controls.
|
|
1344
|
+
footerHint?: string; // Translated note on the left of the form footer (hidden below `sm`).
|
|
1335
1345
|
menuActions?: RenderEditAction[]; // Record actions declared with `placement: "menu"`, resolved like `actions`.
|
|
1336
1346
|
onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void; // Opens a relatedList section row's drawer-kind action.
|
|
1337
1347
|
submitLabel?: string; // i18n key for the submit button.
|
|
@@ -1345,7 +1355,8 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1345
1355
|
labelAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content inline after the label (e.g. ConfigSourceBadge).
|
|
1346
1356
|
fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
|
|
1347
1357
|
fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
|
|
1348
|
-
|
|
1358
|
+
formErrorOnTop?: boolean; // Renders the form-error banner above the sections instead of below them.
|
|
1359
|
+
fieldDescription?: (fieldName: string, values: Readonly<Record<string, unknown>>) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
|
|
1349
1360
|
rowAfterField?: (fieldName: string, state: { dirty: boolean; }) => ReactNode | undefined; // Extra full-width row drawn right after a field's cell (configEdit actions).
|
|
1350
1361
|
fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
|
|
1351
1362
|
markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
|
|
@@ -1357,6 +1368,13 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1357
1368
|
hideActions?: boolean; // Renders the fields without RenderEdit's own action bar (save, cancel, delete, copy-link).
|
|
1358
1369
|
valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
|
|
1359
1370
|
hideSectionTitles?: boolean; // Suppresses every section's own title (fields-section header, relatedList Section title) AND the form's own top-level title/subtitle — for a host that already renders that label itself elsewhere (e.g. a tab strip whose label duplicates it, or a page-level header above RenderEdit).
|
|
1371
|
+
activeTabId?: string; // Id of the active tab of a tabbed projectionDetail; handed to the `afterForm` slot.
|
|
1372
|
+
recordSections?: {
|
|
1373
|
+
labelTitles?: true; // Section titles render as small uppercase labels without separators.
|
|
1374
|
+
omitFirstTitle?: true; // The first section's title is the tab label right above it and is left out.
|
|
1375
|
+
pageNavigation?: false; // `false` leaves out the "On this page" navigation.
|
|
1376
|
+
photosBeside?: true; // Fields sections and the photo-grid relatedList sit side by side from `lg` up.
|
|
1377
|
+
}; // Record-view look of a projectionDetail; each key is opt-in.
|
|
1360
1378
|
fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
|
|
1361
1379
|
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).
|
|
1362
1380
|
submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
|
|
@@ -1433,6 +1451,8 @@ type RenderListProps = DataTableTableBlockProps & {
|
|
|
1433
1451
|
onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed (set URL state + refetch).
|
|
1434
1452
|
chromeless?: boolean; // Forwarded to `DataTableProps.chromeless` — drops the table's own card frame for a host that already provides one (relatedList in a tabs-mode section).
|
|
1435
1453
|
scrollBody?: boolean; // Forwarded to `DataTableProps.scrollBody` — bounds the table height and scrolls rows internally instead of growing the page (relatedList in a tabs-mode section).
|
|
1454
|
+
hideCountFooter?: boolean; // Forwarded to `DataTableProps.hideCountFooter` (relatedList: the tab label already says how many).
|
|
1455
|
+
plainPhoneCards?: boolean; // Forwarded to `DataTableProps.plainPhoneCards` (relatedList: a history reads as a plain feed on the phone).
|
|
1436
1456
|
screenPadding?: boolean; // Forwarded to `DataTableProps.screenPadding` — `true`: the table carries the shared screen padding because it is the screen body (entityList/ projectionList).
|
|
1437
1457
|
expandedRowIds?: ReadonlySet<string>; // Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` / `renderExpandedRow` (entityList `expandableRow`).
|
|
1438
1458
|
onToggleRowExpanded?: (rowId: string) => void;
|
|
@@ -1459,6 +1479,12 @@ type SectionProps = { // Titled group of fields.
|
|
|
1459
1479
|
actions?: ReactNode; // Rendered top-right in the title row — never a footer.
|
|
1460
1480
|
layout?: "stacked" | "settings-list"; // "settings-list": title + subtitle form a left header column and the children (field rows) the right one on `md:` and up.
|
|
1461
1481
|
variant?: "default" | "destructive"; // "destructive" marks the Section as a warning/danger area (e.g. account deletion, restrict processing) — border color only, no content change.
|
|
1482
|
+
titleStyle?: "heading" | "label"; // "label": the title is a small uppercase muted label and the section has no separator line above it.
|
|
1483
|
+
hint?: {
|
|
1484
|
+
text: string;
|
|
1485
|
+
textNarrow?: string;
|
|
1486
|
+
testId: string;
|
|
1487
|
+
}; // Small muted note under the section content on `sm` and up, above it on a phone.
|
|
1462
1488
|
testId?: string;
|
|
1463
1489
|
icon?: IconKey; // Rendered left of the title, `text-muted-foreground`, same optical size as the title.
|
|
1464
1490
|
};
|
|
@@ -1615,6 +1641,8 @@ interface TextFieldProps extends FieldBase {
|
|
|
1615
1641
|
type TextProps = { // Semantic text.
|
|
1616
1642
|
variant?: "body" | "small" | "code" | "required-mark" | "muted";
|
|
1617
1643
|
decorative?: boolean; // Pure ornament (e.g. a separator glyph): hidden from assistive tech.
|
|
1644
|
+
concealed?: boolean; // A value the viewer may not see: drawn muted with a lock icon before it.
|
|
1645
|
+
narrow?: string; // Phone wording: `children` show from `sm` up, this text below it.
|
|
1618
1646
|
children: ReactNode;
|
|
1619
1647
|
testId?: string;
|
|
1620
1648
|
};
|