@cosmicdrift/kumiko-framework 0.416.0 → 0.418.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agents/api/framework-engine.md +32 -9
- package/agents/api/framework-ui-types.md +37 -10
- package/agents/api/renderer-web.md +25 -2
- package/agents/api/types.md +121 -64
- package/agents/api.md +1 -1
- package/agents/boot-rules.md +23 -1
- package/agents/examples/crypto-shredding-hr.md +2 -2
- package/agents/examples/dashboard-stats.md +51 -0
- package/agents/examples/event-sourcing.md +84 -0
- package/agents/examples/list-table-options.md +346 -12
- 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 +3 -2
- package/agents/examples/writeform-section.md +329 -0
- package/agents/features.md +1 -1
- package/dist/api/server-boot-checks.d.ts +1 -0
- package/dist/api/server-boot-checks.js +25 -0
- package/dist/api/server-rate-limit-wiring.js +2 -1
- package/dist/db/queries/event-store.d.ts +3 -0
- package/dist/db/queries/event-store.js +12 -0
- package/dist/engine/boot-validator/action-form-preview-rules.d.ts +22 -0
- package/dist/engine/boot-validator/action-form-preview-rules.js +22 -0
- package/dist/engine/boot-validator/action-form-preview.d.ts +2 -0
- package/dist/engine/boot-validator/action-form-preview.js +54 -0
- package/dist/engine/boot-validator/boot-rules.d.ts +87 -1
- package/dist/engine/boot-validator/boot-rules.js +2 -0
- package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
- package/dist/engine/boot-validator/config-key-rules.d.ts +5 -0
- package/dist/engine/boot-validator/config-key-rules.js +5 -0
- package/dist/engine/boot-validator/date-only-after-days.d.ts +4 -0
- package/dist/engine/boot-validator/date-only-after-days.js +32 -0
- package/dist/engine/boot-validator/entity-handler.d.ts +1 -0
- package/dist/engine/boot-validator/entity-handler.js +1 -1
- package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +40 -0
- package/dist/engine/boot-validator/list-bulk-actions-rules.js +40 -0
- package/dist/engine/boot-validator/list-bulk-actions.d.ts +2 -1
- package/dist/engine/boot-validator/list-bulk-actions.js +79 -9
- package/dist/engine/boot-validator/list-row-guidance.d.ts +1 -0
- package/dist/engine/boot-validator/list-row-guidance.js +1 -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 +29 -2
- package/dist/engine/boot-validator/query-output-guidance.js +1 -0
- package/dist/engine/boot-validator/query-refs.js +3 -0
- package/dist/engine/boot-validator/screens-actions.d.ts +7 -2
- package/dist/engine/boot-validator/screens-actions.js +4 -2
- package/dist/engine/boot-validator/screens-forms.js +2 -0
- package/dist/engine/boot-validator/screens-kind-entity-list.js +5 -3
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +10 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +10 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail.js +80 -0
- package/dist/engine/boot-validator/screens-kind-projection-list.js +2 -2
- package/dist/engine/boot-validator/screens-kind-shared.d.ts +1 -1
- package/dist/engine/boot-validator/screens-kind-shared.js +3 -1
- package/dist/engine/boot-validator/screens-lists-rules.d.ts +10 -0
- package/dist/engine/boot-validator/screens-lists-rules.js +10 -0
- package/dist/engine/boot-validator/screens-lists.js +13 -1
- package/dist/engine/boot-validator/screens.js +1 -2
- package/dist/engine/boot-validator/url-prefill-fields.js +8 -1
- package/dist/engine/boot-validator/zod-shape.d.ts +1 -0
- package/dist/engine/boot-validator/zod-shape.js +7 -0
- package/dist/engine/bridge-stub.js +1 -0
- package/dist/engine/build-config-feature-schema.js +30 -3
- package/dist/engine/screen-helpers.js +7 -3
- package/dist/engine/types/screen.d.ts +1 -1
- package/dist/engine/types/screen.js +1 -1
- 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/i18n/required-surface-keys.js +53 -13
- 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 +36 -0
|
@@ -300,6 +300,7 @@ type ActionFormScreenDefinition = {
|
|
|
300
300
|
successLinks?: ActionFormSuccessLink[]; // Links shown in the success box after a successful submit while the screen stays put.
|
|
301
301
|
successFacts?: ActionFormSuccessFact[]; // Key figures from the handler's success payload, shown in the success box while the screen stays put (e.g. charged/skipped/failed of a batch run).
|
|
302
302
|
successItems?: ActionFormSuccessItems; // One hint per entry of a success-payload array, each with its own link (e.g. "this file is already in the inbox" with "Open" per uploaded file).
|
|
303
|
+
preview?: ActionFormPreview; // Preview of what the submit will do, computed by a query from the current form values.
|
|
303
304
|
resetOnSuccess?: boolean; // Reset the form to its initial values after a successful submit (prefill kept, typed values cleared).
|
|
304
305
|
load?: ActionFormLoad; // Load the initial values from a query.
|
|
305
306
|
cancelTarget?: string | false; // Target of the Cancel button.
|
|
@@ -415,6 +416,7 @@ type ConfigEditScreenDefinition = {
|
|
|
415
416
|
fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
|
|
416
417
|
requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
|
|
417
418
|
submitLabel?: string; // i18n key for the submit button.
|
|
419
|
+
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.
|
|
418
420
|
actions?: ConfigEditAction[]; // Handler buttons drawn as their own row after `afterField` (settings-list layout).
|
|
419
421
|
slots?: ScreenSlots;
|
|
420
422
|
access?: AccessRule;
|
|
@@ -537,6 +539,10 @@ type EditFieldSpec =
|
|
|
537
539
|
fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
|
|
538
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.
|
|
539
541
|
valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
|
|
542
|
+
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
|
+
badge?: FieldBadge; // Pill next to the label, e.g. "price source open" in `warn`.
|
|
544
|
+
hintField?: string; // Value field whose non-empty text shows as a muted small hint under the field (e.g. "From the buyer: Skoda Octavia").
|
|
545
|
+
hideOnNarrow?: true; // Leaves the field out below `sm`; its value is still submitted.
|
|
540
546
|
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.
|
|
541
547
|
refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
|
|
542
548
|
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.
|
|
@@ -544,7 +550,7 @@ type EditFieldSpec =
|
|
|
544
550
|
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.
|
|
545
551
|
}
|
|
546
552
|
;
|
|
547
|
-
type EditRelatedListSection = {
|
|
553
|
+
type EditRelatedListSection = EditSectionPresentation & {
|
|
548
554
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
549
555
|
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`.
|
|
550
556
|
kind: "relatedList";
|
|
@@ -579,7 +585,9 @@ type EditRelatedListSection = {
|
|
|
579
585
|
emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
|
|
580
586
|
photoGrid?: {
|
|
581
587
|
imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
|
|
582
|
-
captionField?: string; // Row field printed under the image.
|
|
588
|
+
captionField?: string; // Row field printed under the image; without it the tile reads "Photo n".
|
|
589
|
+
badgeField?: string; // Row field whose non-empty text shows as a warn badge on the image's top left.
|
|
590
|
+
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.
|
|
583
591
|
}; // Draws the rows as a tile grid of images instead of a table.
|
|
584
592
|
};
|
|
585
593
|
type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
|
|
@@ -667,6 +675,7 @@ type EntityListScreenDefinition = {
|
|
|
667
675
|
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.
|
|
668
676
|
columns: ListColumnSpec[];
|
|
669
677
|
rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
|
|
678
|
+
mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
|
|
670
679
|
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.
|
|
671
680
|
rowRenderer?: PlatformComponent;
|
|
672
681
|
rowActions?: RowAction[]; // Per-row actions, rendered as an actions column on the right.
|
|
@@ -880,7 +889,7 @@ interface FieldFormatRegistry {
|
|
|
880
889
|
absoluteAfterDays?: number;
|
|
881
890
|
withTime?: boolean;
|
|
882
891
|
timeZone?: string; // IANA zone id for the clock time and the day boundary.
|
|
883
|
-
}; // Epoch ms or ISO timestamp, shown as "5
|
|
892
|
+
}; // Epoch ms or ISO timestamp, shown as "5 min.
|
|
884
893
|
date: {
|
|
885
894
|
locale?: string;
|
|
886
895
|
dateStyle?: "full" | "long" | "medium" | "short";
|
|
@@ -967,6 +976,7 @@ type HandlerEvents<TMap extends object = KumikoEventTypeMap> = { // Event-store
|
|
|
967
976
|
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.
|
|
968
977
|
fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
|
|
969
978
|
load: (aggregateId: string, options?: { asOf?: Temporal.Instant; atVersion?: never; includeArchived?: boolean; } | { atVersion?: number; asOf?: never; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
|
|
979
|
+
loadByTypes: (args: { aggregateIds: string[]; eventTypes: string[]; includeArchived?: boolean; }) => Promise<StoredEvent[]>;
|
|
970
980
|
archive: (aggregateId: string, args: { aggregateType: string; reason?: string; }) => Promise<void>;
|
|
971
981
|
restore: (aggregateId: string) => Promise<void>;
|
|
972
982
|
isArchived: (aggregateId: string) => Promise<boolean>;
|
|
@@ -1073,18 +1083,27 @@ type ListColumnSpec =
|
|
|
1073
1083
|
refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
|
|
1074
1084
|
sortable?: boolean; // Marks this column as sortable via a clickable header — for relatedList columns, which have no `EntityDefinition` field to carry `sortable` on.
|
|
1075
1085
|
valueType?: "number" | "decimal" | "bigInt" | "money"; // Value type of a projectionList or relatedList column, which has no `EntityDefinition` field to derive it from.
|
|
1076
|
-
emptyPlaceholder?: false; //
|
|
1077
|
-
hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (
|
|
1086
|
+
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".
|
|
1087
|
+
hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (phone viewport).
|
|
1088
|
+
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.
|
|
1078
1089
|
showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
|
|
1079
1090
|
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.
|
|
1091
|
+
ellipsis?: true; // One line with a trailing ellipsis in the table; the full text is the cell's `title`.
|
|
1092
|
+
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).
|
|
1093
|
+
cardAbove?: true; // Phone card: the column's line stands above the title (muted, e.g. "date, channel") instead of below it.
|
|
1094
|
+
emphasis?: true; // Cell text in medium weight and foreground colour, like the title column of a board.
|
|
1095
|
+
tone?: "muted"; // `"muted"` draws every cell of the column in the muted text colour (e.g. a free-text message beside primary columns).
|
|
1096
|
+
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).
|
|
1097
|
+
dateOnlyAfterDays?: number; // Timestamp or relativeTime column: a value older than this many days shows the date only, without the time.
|
|
1080
1098
|
hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
|
|
1081
1099
|
pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
|
|
1082
1100
|
width?: number; // Start width in px.
|
|
1083
1101
|
minWidth?: number; // Smallest width in px the user can resize to.
|
|
1084
1102
|
display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
|
|
1085
1103
|
variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
|
|
1086
|
-
badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
|
|
1104
|
+
badgeToneField?: string; // Row field naming the badge tone: a `ListBadgeTone` word or a `SelectOptionTone` word (`ok`, `bad`, `critical`, `accent`); only with `display: "badge"`.
|
|
1087
1105
|
badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
|
|
1106
|
+
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"`.
|
|
1088
1107
|
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).
|
|
1089
1108
|
pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
|
|
1090
1109
|
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.
|
|
@@ -1410,8 +1429,11 @@ type ProjectionDetailScreenDefinition = {
|
|
|
1410
1429
|
metrics?: MetricSpec[]; // Metric band above the layout — column names in the query row, each with its own i18n `label`.
|
|
1411
1430
|
metricsStyle?: "band" | "tiles"; // "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band.
|
|
1412
1431
|
metricsPlacement?: {
|
|
1413
|
-
narrow?: "after-guidance";
|
|
1414
|
-
}; // `narrow: "after-guidance"` moves the metrics below the summary, banner and steps
|
|
1432
|
+
narrow?: "after-guidance" | "before-steps";
|
|
1433
|
+
}; // 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.
|
|
1434
|
+
mobileSummary?: string; // Record field holding one line of text shown instead of the metrics below `sm`.
|
|
1435
|
+
pageNavigation?: false; // `false` leaves out the "On this page" navigation of a stacked (non-tabs) layout.
|
|
1436
|
+
photosBeside?: true; // A tab holding fields sections and a relatedList with `photoGrid` shows the fields left and the photos right from `lg` up.
|
|
1415
1437
|
breadcrumb?: RecordBreadcrumbSpec; // Path above the header (query column holding items).
|
|
1416
1438
|
summary?: RecordSummarySpec; // One emphasized sentence below the header.
|
|
1417
1439
|
banner?: RecordBannerSpec; // Notice below the summary.
|
|
@@ -1420,7 +1442,7 @@ type ProjectionDetailScreenDefinition = {
|
|
|
1420
1442
|
listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
|
|
1421
1443
|
slots?: ScreenSlots;
|
|
1422
1444
|
access?: AccessRule;
|
|
1423
|
-
actions?:
|
|
1445
|
+
actions?: EntityEditAction[]; // Header action buttons.
|
|
1424
1446
|
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).
|
|
1425
1447
|
inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
|
|
1426
1448
|
footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
|
|
@@ -1442,6 +1464,7 @@ type ProjectionListScreenDefinition = {
|
|
|
1442
1464
|
query: string;
|
|
1443
1465
|
columns: ListColumnSpec[];
|
|
1444
1466
|
rowToneField?: string; // Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned.
|
|
1467
|
+
mutedRowField?: string; // Row field (boolean): a row with a true value is drawn entirely in the muted text colour.
|
|
1445
1468
|
rowDecoration?: ListRowDecoration; // Computed row fields from an app query, merged into the query rows; see `ListRowDecoration`.
|
|
1446
1469
|
rowRenderer?: PlatformComponent;
|
|
1447
1470
|
rowActions?: RowAction[];
|
|
@@ -67,6 +67,17 @@ type ActionFormLoad = {
|
|
|
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
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.
|
|
69
69
|
};
|
|
70
|
+
type ActionFormPreview = { // Preview panel above the submit button: runs a query over the current form values and shows what the submit would do.
|
|
71
|
+
query: string; // Query QN.
|
|
72
|
+
fields?: string[]; // Form fields sent to the query; they also trigger a rerun when they change.
|
|
73
|
+
title?: string; // Panel title (i18n key).
|
|
74
|
+
facts?: ActionFormSuccessFact[]; // Key figures from the query result, shown like the success box facts.
|
|
75
|
+
list?: ActionFormPreviewList; // Table of rows from the query result.
|
|
76
|
+
};
|
|
77
|
+
type ActionFormPreviewList = { // Rows of the preview panel, read from an array in the preview query's result.
|
|
78
|
+
field: string; // Flat field name of an array in the query result; an entry that is no object is skipped.
|
|
79
|
+
columns: { field: string; label: string; type?: ActionFormValueType; }[];
|
|
80
|
+
};
|
|
70
81
|
type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
|
|
71
82
|
screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
|
|
72
83
|
idFrom?: string; // Flat field name in the handler's success payload, e.g. "leaseId".
|
|
@@ -76,6 +87,7 @@ type ActionFormRedirect = { // Redirect target plus the success-payload field ca
|
|
|
76
87
|
type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
|
|
77
88
|
field: string; // Flat field name in the handler's success payload.
|
|
78
89
|
label: string; // Label (i18n key).
|
|
90
|
+
type?: ActionFormValueType; // Format of the value (a money object, a date string, a number); default `text`.
|
|
79
91
|
};
|
|
80
92
|
type ActionFormSuccessItems = { // Per-entry hints of the success box, read from an array in the handler's success payload.
|
|
81
93
|
field: string; // Flat field name of an array in the success payload.
|
|
@@ -86,6 +98,7 @@ type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom" | "searchParams">
|
|
|
86
98
|
params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
|
|
87
99
|
label: string; // Link text (i18n key).
|
|
88
100
|
};
|
|
101
|
+
type ActionFormValueType = "text" | "number" | "money" | "date" | "timestamp"; // How a preview value or success fact is formatted, by the same formatters a list cell uses.
|
|
89
102
|
type AppSchema = {
|
|
90
103
|
features: FeatureSchema[];
|
|
91
104
|
workspaces?: WorkspaceSchema[];
|
|
@@ -154,6 +167,7 @@ type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState
|
|
|
154
167
|
id: string;
|
|
155
168
|
label: string;
|
|
156
169
|
query: string;
|
|
170
|
+
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.
|
|
157
171
|
};
|
|
158
172
|
type DashboardFilterDefinition = {
|
|
159
173
|
id: string;
|
|
@@ -166,7 +180,7 @@ type DashboardFilterDefinition = {
|
|
|
166
180
|
};
|
|
167
181
|
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`.
|
|
168
182
|
type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
|
|
169
|
-
label
|
|
183
|
+
label?: string; // i18n key of the link text.
|
|
170
184
|
moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
|
|
171
185
|
narrowMoreText?: string; // i18n key used instead of `moreText` below `sm`.
|
|
172
186
|
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.
|
|
@@ -229,6 +243,8 @@ type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmp
|
|
|
229
243
|
kind: "progress-list";
|
|
230
244
|
id: string;
|
|
231
245
|
label: string;
|
|
246
|
+
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" }`.
|
|
247
|
+
subtitleField?: string; // Top-level answer field holding a text shown muted at the right end of the panel head, e.g. the period ("November").
|
|
232
248
|
query: string;
|
|
233
249
|
};
|
|
234
250
|
type DashboardProgressTone = "default" | "danger";
|
|
@@ -309,6 +325,7 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & Dash
|
|
|
309
325
|
valueField: string;
|
|
310
326
|
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.
|
|
311
327
|
narrowLabel?: string; // i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests").
|
|
328
|
+
labelNarrow?: string; // i18n key replacing `label` below the `sm` breakpoint wherever the stat draws its label (a dynamic `labelField` text still wins).
|
|
312
329
|
subField?: string;
|
|
313
330
|
toneField?: string;
|
|
314
331
|
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.
|
|
@@ -375,7 +392,7 @@ type DerivedCellRoundingTarget = {
|
|
|
375
392
|
type: EmbeddedSubFieldDef["type"];
|
|
376
393
|
scale?: number;
|
|
377
394
|
};
|
|
378
|
-
type EditExtensionSection = {
|
|
395
|
+
type EditExtensionSection = EditSectionPresentation & {
|
|
379
396
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
380
397
|
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`.
|
|
381
398
|
kind: "extension";
|
|
@@ -395,6 +412,7 @@ type EditLayout = {
|
|
|
395
412
|
sections: EditSectionSpec[];
|
|
396
413
|
width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
|
|
397
414
|
mode?: "single" | "wizard" | "tabs"; // Default "single".
|
|
415
|
+
narrowTabs?: false; // `false` (tabs mode): below `sm` there is no tab strip, the visible sections of every tab stand one under the other.
|
|
398
416
|
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.
|
|
399
417
|
hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
|
|
400
418
|
allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
|
|
@@ -408,7 +426,7 @@ type EditLayout = {
|
|
|
408
426
|
submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
|
|
409
427
|
}; // Wizard layouts only.
|
|
410
428
|
};
|
|
411
|
-
type EditStepListSection = { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
|
|
429
|
+
type EditStepListSection = EditSectionPresentation & { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
|
|
412
430
|
id?: string;
|
|
413
431
|
visibleWhen?: Exclude<FieldCondition, boolean>;
|
|
414
432
|
kind: "stepList";
|
|
@@ -416,18 +434,20 @@ type EditStepListSection = { // Vertical numbered step list (circles joined by a
|
|
|
416
434
|
field: string; // Output field of the detail query holding a `StepListItem[]`.
|
|
417
435
|
actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
|
|
418
436
|
};
|
|
419
|
-
type EditWriteFormSection = {
|
|
437
|
+
type EditWriteFormSection = EditSectionPresentation & {
|
|
420
438
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
421
439
|
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`.
|
|
422
440
|
kind: "writeForm";
|
|
423
441
|
title?: string;
|
|
424
442
|
description?: string;
|
|
443
|
+
descriptionNarrow?: string; // i18n key of a short text shown instead of `description` below `sm`.
|
|
425
444
|
columns?: number;
|
|
426
445
|
icon?: IconKey;
|
|
427
446
|
fieldDefs: Readonly<Record<string, FieldDefinition>>; // Field-type map for this section's own form — same shape as `ActionFormScreenDefinition.fields`.
|
|
428
447
|
fields: EditFieldSpec[]; // Rendered fields, in order — same shape as `EditFieldsSection.fields`.
|
|
429
448
|
handler: string; // Write-handler QN dispatched on submit.
|
|
430
449
|
submitLabel?: string; // i18n-key for the submit button.
|
|
450
|
+
submitWith?: string; // Id of a writeHandler action in the screen's `actions`.
|
|
431
451
|
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.
|
|
432
452
|
};
|
|
433
453
|
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.
|
|
@@ -480,6 +500,16 @@ type FieldAiAssistChip = { // One toggle chip: while active, its `params` are me
|
|
|
480
500
|
label: string; // i18n key of the chip label.
|
|
481
501
|
params: Readonly<Record<string, string | number | boolean>>;
|
|
482
502
|
};
|
|
503
|
+
type FieldBadge = // Pill next to a field label: a fixed i18n `label`, or the text of another value `field`.
|
|
504
|
+
| {
|
|
505
|
+
label: string;
|
|
506
|
+
tone: SelectOptionTone;
|
|
507
|
+
}
|
|
508
|
+
| {
|
|
509
|
+
field: string;
|
|
510
|
+
tone: SelectOptionTone;
|
|
511
|
+
}
|
|
512
|
+
;
|
|
483
513
|
type FieldFillAction = {
|
|
484
514
|
label: string; // i18n key (falls back to the literal) of the button label.
|
|
485
515
|
query: string; // Qualified query name, run with the current form values picked by `params`.
|
|
@@ -505,11 +535,7 @@ type FormDerivationScreen = {
|
|
|
505
535
|
type FormWidth = "3xl" | "4xl" | "full";
|
|
506
536
|
type Formality = "formal" | "informal";
|
|
507
537
|
type IconKey = NavIconKey;
|
|
508
|
-
type ListBulkAction =
|
|
509
|
-
id: string; // Stable id, kebab-case, unique among the screen's bulk actions.
|
|
510
|
-
rowAction: string; // Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`.
|
|
511
|
-
confirm?: string; // i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`.
|
|
512
|
-
};
|
|
538
|
+
type ListBulkAction = ListBulkRowAction | ListBulkFormAction; // An action over checkbox-selected rows: a writeHandler row action per row (`rowAction`) or one form for all rows (`screen` + `idsField`).
|
|
513
539
|
type ListColumnHint = {
|
|
514
540
|
detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
|
|
515
541
|
narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
|
|
@@ -560,6 +586,7 @@ type QualifiedContentCollection = ContentCollectionDefinition & {
|
|
|
560
586
|
};
|
|
561
587
|
type RecordBannerSpec = {
|
|
562
588
|
field: string; // Holds `RecordNotice | null`; null shows no banner.
|
|
589
|
+
iconless?: true; // Draws the notice without the tone icon.
|
|
563
590
|
actions?: RecordGuidanceAction[];
|
|
564
591
|
};
|
|
565
592
|
type RecordBreadcrumbItem = {
|
|
@@ -659,7 +686,7 @@ type RowActionClientAction = {
|
|
|
659
686
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
660
687
|
successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
|
|
661
688
|
};
|
|
662
|
-
type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
|
|
689
|
+
type RowActionDisplay = "button" | "link" | "icon" | "responsive" | "text"; // How a row action renders inline in the row-action column.
|
|
663
690
|
type RowActionDrawer = {
|
|
664
691
|
kind: "drawer";
|
|
665
692
|
id: string;
|
|
@@ -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.
|
|
@@ -445,6 +445,7 @@ type DataTableProps = DataTableTableBlock & {
|
|
|
445
445
|
columns: ListColumnViewModel[];
|
|
446
446
|
rows: ListRowViewModel[];
|
|
447
447
|
rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
|
|
448
|
+
rowMuted?: (row: ListRowViewModel) => boolean; // Draws the whole row in the muted text colour.
|
|
448
449
|
onRowClick?: (row: ListRowViewModel) => void;
|
|
449
450
|
sort?: DataTableSort | null; // Current sorting, or null when unsorted.
|
|
450
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.
|
|
@@ -482,6 +483,8 @@ type DataTableProps = DataTableTableBlock & {
|
|
|
482
483
|
getCellTestId?: (row: ListRowViewModel, field: string) => string; // Overrides the cell `data-testid` (default `cell-${row.id}-${field}`).
|
|
483
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.
|
|
484
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.
|
|
485
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.
|
|
486
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).
|
|
487
490
|
onToggleRowExpanded?: (rowId: string) => void; // User toggled a row's expand control.
|
|
@@ -674,12 +677,14 @@ type FormProps = { // Submit wrapper.
|
|
|
674
677
|
title: string;
|
|
675
678
|
subtitle?: string;
|
|
676
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.
|
|
677
681
|
sectionNav?: FormSectionNavItem[]; // Titled sections for the "on this page" navigation next to a `screenForm`.
|
|
678
682
|
sideRail?: ReactNode; // Leading column next to the scroll surface of a `screenForm` (wizard step navigation).
|
|
679
683
|
};
|
|
680
684
|
type GridCellProps = { // Span wrapper for a child within a grid.
|
|
681
685
|
span?: number;
|
|
682
686
|
width?: FieldCellWidth; // Only read inside a `flow` grid.
|
|
687
|
+
hideOnNarrow?: boolean; // Hidden below the `sm` breakpoint.
|
|
683
688
|
children: ReactNode;
|
|
684
689
|
};
|
|
685
690
|
type GridProps = { // Column-based layout.
|
|
@@ -691,6 +696,7 @@ type GridProps = { // Column-based layout.
|
|
|
691
696
|
list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
|
|
692
697
|
ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
|
|
693
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`.
|
|
694
700
|
};
|
|
695
701
|
type HeaderActionGroupProps = {
|
|
696
702
|
children: ReactNode;
|
|
@@ -1363,8 +1369,15 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1363
1369
|
valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
|
|
1364
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).
|
|
1365
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.
|
|
1366
1378
|
fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
|
|
1367
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).
|
|
1380
|
+
belowSections?: (values: Readonly<Record<string, unknown>>) => ReactNode; // Rendered after the sections, above the form actions, with the live form values.
|
|
1368
1381
|
submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
|
|
1369
1382
|
formDerivation?: FormDerivationScreen; // actionForm `derive`: derived fields are recomputed into the form state on every change and render read-only.
|
|
1370
1383
|
actionFormScreenQn?: string; // QN of the actionForm screen this form renders; its file fields upload as pending for that screen.
|
|
@@ -1439,6 +1452,8 @@ type RenderListProps = DataTableTableBlockProps & {
|
|
|
1439
1452
|
onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed (set URL state + refetch).
|
|
1440
1453
|
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).
|
|
1441
1454
|
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).
|
|
1455
|
+
hideCountFooter?: boolean; // Forwarded to `DataTableProps.hideCountFooter` (relatedList: the tab label already says how many).
|
|
1456
|
+
plainPhoneCards?: boolean; // Forwarded to `DataTableProps.plainPhoneCards` (relatedList: a history reads as a plain feed on the phone).
|
|
1442
1457
|
screenPadding?: boolean; // Forwarded to `DataTableProps.screenPadding` — `true`: the table carries the shared screen padding because it is the screen body (entityList/ projectionList).
|
|
1443
1458
|
expandedRowIds?: ReadonlySet<string>; // Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` / `renderExpandedRow` (entityList `expandableRow`).
|
|
1444
1459
|
onToggleRowExpanded?: (rowId: string) => void;
|
|
@@ -1465,6 +1480,12 @@ type SectionProps = { // Titled group of fields.
|
|
|
1465
1480
|
actions?: ReactNode; // Rendered top-right in the title row — never a footer.
|
|
1466
1481
|
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.
|
|
1467
1482
|
variant?: "default" | "destructive"; // "destructive" marks the Section as a warning/danger area (e.g. account deletion, restrict processing) — border color only, no content change.
|
|
1483
|
+
titleStyle?: "heading" | "label"; // "label": the title is a small uppercase muted label and the section has no separator line above it.
|
|
1484
|
+
hint?: {
|
|
1485
|
+
text: string;
|
|
1486
|
+
textNarrow?: string;
|
|
1487
|
+
testId: string;
|
|
1488
|
+
}; // Small muted note under the section content on `sm` and up, above it on a phone.
|
|
1468
1489
|
testId?: string;
|
|
1469
1490
|
icon?: IconKey; // Rendered left of the title, `text-muted-foreground`, same optical size as the title.
|
|
1470
1491
|
};
|
|
@@ -1621,6 +1642,8 @@ interface TextFieldProps extends FieldBase {
|
|
|
1621
1642
|
type TextProps = { // Semantic text.
|
|
1622
1643
|
variant?: "body" | "small" | "code" | "required-mark" | "muted";
|
|
1623
1644
|
decorative?: boolean; // Pure ornament (e.g. a separator glyph): hidden from assistive tech.
|
|
1645
|
+
concealed?: boolean; // A value the viewer may not see: drawn muted with a lock icon before it.
|
|
1646
|
+
narrow?: string; // Phone wording: `children` show from `sm` up, this text below it.
|
|
1624
1647
|
children: ReactNode;
|
|
1625
1648
|
testId?: string;
|
|
1626
1649
|
};
|