@cosmicdrift/kumiko-framework 0.414.0 → 0.416.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 +46 -8
- package/agents/api/framework-errors.md +1 -1
- package/agents/api/framework-ui-types.md +69 -4
- package/agents/api/renderer-web.md +27 -4
- package/agents/api/types.md +68 -16
- package/agents/api.md +2 -2
- package/agents/boot-rules.md +39 -7
- package/agents/examples/crypto-shredding-hr.md +63 -1
- package/agents/examples/embedded.md +24 -1
- package/agents/examples/handbook-knowledge.md +129 -0
- package/agents/examples/record-detail-layout.md +113 -7
- package/agents/examples/signature.md +186 -0
- package/agents/examples/writeform-section.md +1 -0
- package/agents/examples.md +2 -0
- package/agents/features-index.md +4 -0
- package/agents/features.md +14 -0
- package/agents/widgets.md +7 -0
- package/dist/api/request-context-internals.d.ts +2 -0
- package/dist/api/request-context-scopes.js +9 -2
- package/dist/api/request-context.js +1 -1
- package/dist/api/routes.js +4 -4
- package/dist/api/server-event-dispatcher.js +3 -0
- package/dist/api/server-routes.js +2 -0
- package/dist/db/parent-ref-clause.js +31 -3
- package/dist/db/parent-ref-global-hosts.d.ts +4 -1
- package/dist/db/parent-ref-global-hosts.js +50 -12
- package/dist/db/queries/rls-boot-catalog.js +5 -6
- package/dist/db/queries/rls-shape.d.ts +1 -0
- package/dist/db/queries/rls-shape.js +21 -6
- 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 +144 -9
- package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
- package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
- package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
- 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/entity-list-screens.js +2 -7
- package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +17 -2
- package/dist/engine/boot-validator/list-row-guidance-rules.js +17 -2
- package/dist/engine/boot-validator/list-row-guidance.d.ts +7 -0
- package/dist/engine/boot-validator/list-row-guidance.js +45 -1
- package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
- package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
- package/dist/engine/boot-validator/list-sort-summary.js +31 -20
- package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
- package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
- package/dist/engine/boot-validator/named-filter-rules.js +10 -0
- package/dist/engine/boot-validator/projection-list-screens.js +5 -4
- package/dist/engine/boot-validator/query-output-columns.js +18 -0
- package/dist/engine/boot-validator/query-output-guidance.js +3 -0
- package/dist/engine/boot-validator/query-refs.js +14 -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.js +56 -16
- 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-projection-detail-rules.d.ts +5 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail.js +30 -0
- 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/build-config-feature-schema.js +5 -35
- 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/named-filter-roles.js +6 -14
- package/dist/engine/project-app-schema-for-roles.js +2 -0
- package/dist/engine/schema-builder.js +3 -1
- package/dist/engine/soft-delete-cleanup.js +2 -0
- package/dist/errors/reasons.d.ts +1 -0
- package/dist/errors/reasons.js +4 -0
- 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 +28 -7
- package/dist/jobs/job-runner-execution.js +3 -0
- package/dist/jobs/job-runner-types.d.ts +1 -0
- package/dist/jobs/job-runner.js +8 -0
- package/dist/pipeline/context-services.d.ts +1 -1
- package/dist/pipeline/context-services.js +1 -1
- package/dist/pipeline/event-dispatcher-delivery.js +3 -0
- package/dist/pipeline/event-dispatcher.d.ts +2 -0
- package/dist/pipeline/handler-context-phase-denials.js +1 -1
- package/dist/pipeline/irreversible-operation-gate.js +36 -10
- package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
- package/dist/search/meilisearch-adapter-internals.js +5 -0
- package/dist/search/meilisearch-adapter.d.ts +1 -0
- package/dist/search/meilisearch-adapter.js +3 -2
- package/dist/ui-types/card-column-roles.d.ts +2 -0
- package/dist/ui-types/card-column-roles.js +15 -0
- package/dist/ui-types/index.d.ts +2 -2
- package/dist/ui-types/index.js +1 -1
- package/package.json +3 -3
- package/presets/biome-plugins/no-date-api.grit +3 -1
- package/presets/biome-plugins/no-direct-fetch.grit +1 -1
- package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
- package/presets/biome-rules.json +12 -10
- package/src/changes.json +99 -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>`).
|
|
@@ -530,6 +535,8 @@ type EditFieldSpec =
|
|
|
530
535
|
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
536
|
suffix?: FieldAffix; // Same as `prefix`, shown after the input.
|
|
532
537
|
fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
|
|
538
|
+
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
|
+
valueChips?: FieldValueChips; // Quick-pick chips under a `number`, `decimal`, `bigInt` or `money` input; a chip sets the field to its value.
|
|
533
540
|
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
541
|
refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
|
|
535
542
|
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.
|
|
@@ -539,6 +546,7 @@ type EditFieldSpec =
|
|
|
539
546
|
;
|
|
540
547
|
type EditRelatedListSection = {
|
|
541
548
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
549
|
+
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
550
|
kind: "relatedList";
|
|
543
551
|
title: string;
|
|
544
552
|
readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
|
|
@@ -569,8 +577,12 @@ type EditRelatedListSection = {
|
|
|
569
577
|
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
578
|
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
579
|
emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
|
|
580
|
+
photoGrid?: {
|
|
581
|
+
imageField: string; // Row field holding a FileRef id (or an id array, the first shows).
|
|
582
|
+
captionField?: string; // Row field printed under the image.
|
|
583
|
+
}; // Draws the rows as a tile grid of images instead of a table.
|
|
572
584
|
};
|
|
573
|
-
type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
|
|
585
|
+
type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection | EditStepListSection;
|
|
574
586
|
type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & { // Resolver callback shape: synchronous (on the dispatcher's hot path), per tenant.
|
|
575
587
|
trialGate?: TrialGate; // Optional live-trial gate, consulted by the dispatcher feature gate ONLY when the synchronous resolver reports a feature as disabled.
|
|
576
588
|
};
|
|
@@ -602,6 +614,10 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
|
|
|
602
614
|
description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
|
|
603
615
|
transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
|
|
604
616
|
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.
|
|
617
|
+
crossTenantFileRead?: {
|
|
618
|
+
query: string;
|
|
619
|
+
reason: string;
|
|
620
|
+
}; // 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
621
|
};
|
|
606
622
|
type EntityEditScreenDefinition = {
|
|
607
623
|
id: string;
|
|
@@ -628,7 +644,7 @@ type EntityEditScreenDefinition = {
|
|
|
628
644
|
singleton?: boolean; // Default false.
|
|
629
645
|
redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful save (create or update).
|
|
630
646
|
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,
|
|
647
|
+
fieldLabels?: Readonly<Record<string, FieldTextRef>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
|
|
632
648
|
actions?: EntityEditAction[]; // Record actions.
|
|
633
649
|
slots?: ScreenSlots;
|
|
634
650
|
access?: AccessRule;
|
|
@@ -670,10 +686,10 @@ type EntityListScreenDefinition = {
|
|
|
670
686
|
namedFilterFacet?: NamedFilterFacetOptions; // Presentation of `namedFilters` in the toolbar; needs `namedFilters`.
|
|
671
687
|
emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
|
|
672
688
|
createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
|
|
673
|
-
createPlacement?: "header" | "toolbar"; // "toolbar": from `
|
|
689
|
+
createPlacement?: "header" | "toolbar"; // "toolbar": from `md` up (below md the compact header keeps its "+") the create button ends the filter row instead of standing in the header.
|
|
674
690
|
toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
|
|
675
691
|
narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
|
|
676
|
-
toolbarActionsPlacement?:
|
|
692
|
+
toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
|
|
677
693
|
itemNounKey?: string; // i18n key of the plural noun for the list size in the phone sort line (`{count}` pluralised).
|
|
678
694
|
searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
|
|
679
695
|
searchable?: boolean;
|
|
@@ -858,10 +874,18 @@ interface FieldFormatRegistry {
|
|
|
858
874
|
timeStyle?: "full" | "long" | "medium" | "short";
|
|
859
875
|
timeZone?: string; // IANA zone id (e.g. "Europe/Berlin").
|
|
860
876
|
};
|
|
877
|
+
relativeTime: {
|
|
878
|
+
locale?: string;
|
|
879
|
+
style?: "long" | "short" | "narrow";
|
|
880
|
+
absoluteAfterDays?: number;
|
|
881
|
+
withTime?: boolean;
|
|
882
|
+
timeZone?: string; // IANA zone id for the clock time and the day boundary.
|
|
883
|
+
}; // Epoch ms or ISO timestamp, shown as "5 minutes ago" at render time (a table cell does not tick).
|
|
861
884
|
date: {
|
|
862
885
|
locale?: string;
|
|
863
886
|
dateStyle?: "full" | "long" | "medium" | "short";
|
|
864
887
|
};
|
|
888
|
+
phone: Record<never, never>; // Telephone number shown as a `tel:` link in list cells, like a read-only `format: "phone"` field.
|
|
865
889
|
boolean: {
|
|
866
890
|
trueLabel?: string;
|
|
867
891
|
falseLabel?: string;
|
|
@@ -1002,6 +1026,7 @@ type JobDefinition = {
|
|
|
1002
1026
|
escapeHatch?: EscapeHatchDeclaration | undefined;
|
|
1003
1027
|
tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
|
|
1004
1028
|
tenantVisibleRun?: { subjectFields?: string[] | undefined; } | undefined;
|
|
1029
|
+
irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler | undefined;
|
|
1005
1030
|
};
|
|
1006
1031
|
type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
|
|
1007
1032
|
type JobEvents = Pick<HandlerEvents, "append" | "load">;
|
|
@@ -1051,13 +1076,17 @@ type ListColumnSpec =
|
|
|
1051
1076
|
emptyPlaceholder?: false; // `false` leaves an empty cell blank instead of drawing the "—" placeholder.
|
|
1052
1077
|
hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
|
|
1053
1078
|
showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
|
|
1079
|
+
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.
|
|
1054
1080
|
hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
|
|
1055
1081
|
pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
|
|
1056
1082
|
width?: number; // Start width in px.
|
|
1057
1083
|
minWidth?: number; // Smallest width in px the user can resize to.
|
|
1058
1084
|
display?: ListColumnDisplay; // One of "bar" | "badge" | "datetime" | "button".
|
|
1085
|
+
variant?: "primary"; // `"primary"` draws a `display: "button"` link as a filled primary button instead of the outline default (dashboard list panels only).
|
|
1059
1086
|
badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
|
|
1060
1087
|
badgeDot?: false; // `false` draws the badge pill without its leading dot; only with `display: "badge"`.
|
|
1088
|
+
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
|
+
pillToneField?: string; // Row field naming the tone of the `pillField` pill (a `ListBadgeTone`).
|
|
1061
1090
|
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.
|
|
1062
1091
|
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).
|
|
1063
1092
|
hint?: ListColumnHint; // "To do" cell: the column's field holds a sentence, shown emphasized in the row tone; an empty value shows `emptyLabel`.
|
|
@@ -1068,12 +1097,14 @@ type ListFacetSpec =
|
|
|
1068
1097
|
field: string;
|
|
1069
1098
|
type: "select";
|
|
1070
1099
|
label: string;
|
|
1100
|
+
narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
|
|
1071
1101
|
options: { value: string; label: string; }[];
|
|
1072
1102
|
}
|
|
1073
1103
|
| {
|
|
1074
1104
|
field: string;
|
|
1075
1105
|
type: "boolean";
|
|
1076
1106
|
label: string;
|
|
1107
|
+
narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
|
|
1077
1108
|
trueLabel: string;
|
|
1078
1109
|
falseLabel: string;
|
|
1079
1110
|
}
|
|
@@ -1081,6 +1112,7 @@ type ListFacetSpec =
|
|
|
1081
1112
|
field: string;
|
|
1082
1113
|
type: "reference";
|
|
1083
1114
|
label: string;
|
|
1115
|
+
narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
|
|
1084
1116
|
entity: string; // Entity name (same feature) or `feature:entity` (cross-feature), same convention as `ListColumnSpec.refEntity`.
|
|
1085
1117
|
labelField?: string; // Row field on the referenced entity shown as the option label (default "id").
|
|
1086
1118
|
}
|
|
@@ -1178,6 +1210,7 @@ type MultiStreamProjectionDefinition = {
|
|
|
1178
1210
|
runIn?: RunIn;
|
|
1179
1211
|
delivery?: "shared" | "per-instance";
|
|
1180
1212
|
startFrom?: "beginning" | "now";
|
|
1213
|
+
irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
|
|
1181
1214
|
};
|
|
1182
1215
|
type NavDefinition = {
|
|
1183
1216
|
id: string;
|
|
@@ -1390,6 +1423,9 @@ type ProjectionDetailScreenDefinition = {
|
|
|
1390
1423
|
actions?: RowAction[]; // Header action buttons.
|
|
1391
1424
|
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).
|
|
1392
1425
|
inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
|
|
1426
|
+
footerActions?: string[]; // Ids of `actions` shown in the pinned footer bar instead of the header, in declaration order.
|
|
1427
|
+
footerHint?: string; // i18n key of a note on the left of the footer bar ("Changes go out with the release"); hidden below `sm`.
|
|
1428
|
+
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.
|
|
1393
1429
|
valueDisplay?: "form" | "text"; // How head fields render.
|
|
1394
1430
|
};
|
|
1395
1431
|
type ProjectionListScreenDefinition = {
|
|
@@ -1412,7 +1448,7 @@ type ProjectionListScreenDefinition = {
|
|
|
1412
1448
|
rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
|
|
1413
1449
|
bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
|
|
1414
1450
|
toolbarActions?: ToolbarAction[];
|
|
1415
|
-
toolbarActionsPlacement?:
|
|
1451
|
+
toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select, instead of standing in the page header.
|
|
1416
1452
|
toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
|
|
1417
1453
|
narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
|
|
1418
1454
|
pagination?: ListPaginationMode;
|
|
@@ -1578,7 +1614,9 @@ type RoleAccessRule = {
|
|
|
1578
1614
|
personalData?: RoleAccessPersonalData;
|
|
1579
1615
|
anySignedIn?: true;
|
|
1580
1616
|
};
|
|
1581
|
-
type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction
|
|
1617
|
+
type RowAction = (RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction) & {
|
|
1618
|
+
align?: "start"; // projectionDetail `footerActions` only: "start" sets the button apart on the left of the footer.
|
|
1619
|
+
};
|
|
1582
1620
|
type RowActionWriteHandler = {
|
|
1583
1621
|
kind?: "writeHandler"; // Default for RowActions without an explicitly set `kind` — backwards-compatible form.
|
|
1584
1622
|
id: string; // Stable id per screen — kebab-case, unique within the action set.
|
|
@@ -20,7 +20,7 @@ function writeFailure(err: KumikoError): WriteFailure;
|
|
|
20
20
|
## Constants
|
|
21
21
|
|
|
22
22
|
```ts
|
|
23
|
-
const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
|
|
23
|
+
const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; irreversibleOperationWithoutEntryHandler; subjectErased; fileRejected; fileViolatesBindTarget };
|
|
24
24
|
const frameworkErrorHttpStatus: { validation_error; feature_disabled; access_denied; unauthenticated; not_found; conflict; version_conflict; precondition_failed; record_locked; idempotent_replay; unique_violation; unprocessable; unconfigured; internal_error; member_read_timeout; rate_limited; rate_limit_unavailable };
|
|
25
25
|
```
|
|
26
26
|
|
|
@@ -10,6 +10,7 @@ Import from `@cosmicdrift/kumiko-framework/ui-types`. Types used here but not ex
|
|
|
10
10
|
function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown; // Recomputes every derived head field of an action form from its inputs.
|
|
11
11
|
function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): string[]; // Options of a select field that are offered for the given row values, in declaration order.
|
|
12
12
|
function cardColumnRoles<C extends CardRoleColumn>(columns: C[]): CardColumnRoles<C>;
|
|
13
|
+
function cardMetaLines<C extends CardRoleColumn>(meta: C[]): (C[])[];
|
|
13
14
|
function computeDerivedCellValue(op: NumericDerivedOp, values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
|
|
14
15
|
function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean; // Evaluates a declarative FieldCondition against the current row/form values.
|
|
15
16
|
function findMissingConditionalRequirements(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): string[]; // Paths of fields (and embedded sub-fields) whose `requiredWhen` holds while the value is missing.
|
|
@@ -64,11 +65,13 @@ type ActionFormLoad = {
|
|
|
64
65
|
query: string; // Query QN that returns the record.
|
|
65
66
|
idParam?: string; // Payload key carrying the record id (default "id").
|
|
66
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.
|
|
67
69
|
};
|
|
68
70
|
type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
|
|
69
71
|
screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
|
|
70
|
-
idFrom
|
|
72
|
+
idFrom?: string; // Flat field name in the handler's success payload, e.g. "leaseId".
|
|
71
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>`).
|
|
72
75
|
};
|
|
73
76
|
type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
|
|
74
77
|
field: string; // Flat field name in the handler's success payload.
|
|
@@ -78,7 +81,7 @@ type ActionFormSuccessItems = { // Per-entry hints of the success box, read from
|
|
|
78
81
|
field: string; // Flat field name of an array in the success payload.
|
|
79
82
|
link?: ActionFormSuccessLink; // Link of each hint.
|
|
80
83
|
};
|
|
81
|
-
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.
|
|
82
85
|
idFrom?: string; // Success-payload field carrying the navigation id.
|
|
83
86
|
params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
|
|
84
87
|
label: string; // Link text (i18n key).
|
|
@@ -161,6 +164,7 @@ type DashboardFilterDefinition = {
|
|
|
161
164
|
options?: { value: string; label: string; }[];
|
|
162
165
|
optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
|
|
163
166
|
};
|
|
167
|
+
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`.
|
|
164
168
|
type DashboardListFooterLink = { // Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens.
|
|
165
169
|
label: string;
|
|
166
170
|
moreText?: string; // i18n key of the text before the link when more rows exist than shown; `{count}` is the rest.
|
|
@@ -199,6 +203,7 @@ type DashboardMoneyParam = { // Minor units (like Money fields), formatted with
|
|
|
199
203
|
amountMinor: number;
|
|
200
204
|
currency: string;
|
|
201
205
|
};
|
|
206
|
+
type DashboardPanelColumn = "side" | "top"; // "top" spans both columns above the main and side column, in declared order.
|
|
202
207
|
type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
|
|
203
208
|
type DashboardPanelEmptyState = {
|
|
204
209
|
span?: DashboardPanelSpan;
|
|
@@ -208,6 +213,7 @@ type DashboardPanelEmptyState = {
|
|
|
208
213
|
type DashboardPanelNarrow = { // Phone layout switch shared by every panel kind.
|
|
209
214
|
hideOnNarrow?: true; // Leaves the panel out below the `sm` breakpoint (phone).
|
|
210
215
|
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.
|
|
216
|
+
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.
|
|
211
217
|
};
|
|
212
218
|
type DashboardPanelQueryOptions = {
|
|
213
219
|
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.
|
|
@@ -253,6 +259,7 @@ type DashboardScreenDefinition = {
|
|
|
253
259
|
visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
|
|
254
260
|
fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
|
|
255
261
|
panels: DashboardPanelDefinition[];
|
|
262
|
+
layout?: DashboardLayout; // Panel arrangement, see DashboardLayout.
|
|
256
263
|
record?: DashboardRecordBinding; // Binds the dashboard to one record via a URL search param, see DashboardRecordBinding.
|
|
257
264
|
actions?: RowAction[]; // Header actions on the bound record (writeHandler, navigate, clientAction).
|
|
258
265
|
refresh?: DashboardRefresh;
|
|
@@ -352,6 +359,7 @@ type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & Dash
|
|
|
352
359
|
kind: "text";
|
|
353
360
|
id: string;
|
|
354
361
|
label?: string; // Panel title (i18n key).
|
|
362
|
+
icon?: PlatformComponent; // Icon shown before the text blocks (resolved like `DashboardStatGroupPanel.icon`).
|
|
355
363
|
span?: DashboardPanelSpan;
|
|
356
364
|
query?: string; // Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
|
|
357
365
|
blocks?: DashboardTextBlock[];
|
|
@@ -369,6 +377,7 @@ type DerivedCellRoundingTarget = {
|
|
|
369
377
|
};
|
|
370
378
|
type EditExtensionSection = {
|
|
371
379
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
380
|
+
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`.
|
|
372
381
|
kind: "extension";
|
|
373
382
|
title: string;
|
|
374
383
|
description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
|
|
@@ -388,6 +397,7 @@ type EditLayout = {
|
|
|
388
397
|
mode?: "single" | "wizard" | "tabs"; // Default "single".
|
|
389
398
|
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.
|
|
390
399
|
hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
|
|
400
|
+
allRequiredHint?: false; // `false` switches off the "all fields are required" hint when every field is required; each label then carries its own asterisk.
|
|
391
401
|
draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
|
|
392
402
|
wizard?: {
|
|
393
403
|
aside?: {
|
|
@@ -398,8 +408,17 @@ type EditLayout = {
|
|
|
398
408
|
submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
|
|
399
409
|
}; // Wizard layouts only.
|
|
400
410
|
};
|
|
411
|
+
type EditStepListSection = { // Vertical numbered step list (circles joined by a line), fed from one field of the detail query.
|
|
412
|
+
id?: string;
|
|
413
|
+
visibleWhen?: Exclude<FieldCondition, boolean>;
|
|
414
|
+
kind: "stepList";
|
|
415
|
+
title?: string;
|
|
416
|
+
field: string; // Output field of the detail query holding a `StepListItem[]`.
|
|
417
|
+
actions?: undefined; // Present only so section-actions readers accept the union; a step list has no title-row actions.
|
|
418
|
+
};
|
|
401
419
|
type EditWriteFormSection = {
|
|
402
420
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
421
|
+
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`.
|
|
403
422
|
kind: "writeForm";
|
|
404
423
|
title?: string;
|
|
405
424
|
description?: string;
|
|
@@ -427,6 +446,7 @@ type EntityListFacetConfig = {
|
|
|
427
446
|
showCounts?: boolean; // Chips show how many rows each option matches (other facets and the search apply).
|
|
428
447
|
hideEmpty?: boolean; // Chips with zero matching rows are not shown.
|
|
429
448
|
extraOptions?: EntityListFacetExtraOption[];
|
|
449
|
+
narrowPlacement?: "behind-filter"; // "behind-filter": the facet opens behind the filter icon next to the search field instead of standing as a pill.
|
|
430
450
|
};
|
|
431
451
|
type FeatureSchema = {
|
|
432
452
|
featureName: string;
|
|
@@ -445,6 +465,21 @@ type FieldAffix =
|
|
|
445
465
|
field: string;
|
|
446
466
|
}
|
|
447
467
|
;
|
|
468
|
+
type FieldAiAssist = {
|
|
469
|
+
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.
|
|
470
|
+
resultField: string; // Key in the query result written into the field; the value must be a string.
|
|
471
|
+
noteField?: string; // Key in the query result with a short note for the user (e.g. "could not rewrite, draft unchanged").
|
|
472
|
+
contextFields?: string[]; // Other fields of the same form whose current values are sent in the payload (under their field names).
|
|
473
|
+
chips?: FieldAiAssistChip[];
|
|
474
|
+
prompt?: {
|
|
475
|
+
param: string;
|
|
476
|
+
placeholder?: string; // i18n key of the input's placeholder.
|
|
477
|
+
}; // Adds an input where the user types a free instruction; it is sent under `param`.
|
|
478
|
+
};
|
|
479
|
+
type FieldAiAssistChip = { // One toggle chip: while active, its `params` are merged into the query payload.
|
|
480
|
+
label: string; // i18n key of the chip label.
|
|
481
|
+
params: Readonly<Record<string, string | number | boolean>>;
|
|
482
|
+
};
|
|
448
483
|
type FieldFillAction = {
|
|
449
484
|
label: string; // i18n key (falls back to the literal) of the button label.
|
|
450
485
|
query: string; // Qualified query name, run with the current form values picked by `params`.
|
|
@@ -453,6 +488,16 @@ type FieldFillAction = {
|
|
|
453
488
|
};
|
|
454
489
|
type FieldIconKey = "mail" | "lock" | "hash" | "search" | "user" | "phone" | "calendar" | "link" | "tag" | "building" | "globe" | "key" | "map-pin";
|
|
455
490
|
type FieldRenderer = PlatformComponent | string | FormatSpec;
|
|
491
|
+
type FieldTextRef = // A label or help text: an i18n key, or a key whose `{placeholder}`s are filled from form values.
|
|
492
|
+
| string
|
|
493
|
+
| {
|
|
494
|
+
key: string;
|
|
495
|
+
params: Readonly<Record<string, string>>;
|
|
496
|
+
}
|
|
497
|
+
;
|
|
498
|
+
type FieldValueChips = {
|
|
499
|
+
from: string; // Name of a field of the same form whose value is an array of numbers.
|
|
500
|
+
};
|
|
456
501
|
type FormDerivationScreen = {
|
|
457
502
|
fields: Readonly<Record<string, FormFieldDefinition>>;
|
|
458
503
|
derive?: Readonly<Record<string, FormFieldDerivation>>;
|
|
@@ -468,6 +513,7 @@ type ListBulkAction = { // An action that runs a writeHandler row action once pe
|
|
|
468
513
|
type ListColumnHint = {
|
|
469
514
|
detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
|
|
470
515
|
narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
|
|
516
|
+
narrowField?: string; // Row field shown as the sentence on the phone card instead of the column's own value (a shorter sentence); the table keeps the column value.
|
|
471
517
|
toneField?: string; // Row field holding a SelectOptionTone; defaults to the screen's `rowToneField`.
|
|
472
518
|
reasonField?: string; // Row field with a longer reason, shown behind a "Why?" toggle in the cell.
|
|
473
519
|
reasonOpenField?: string; // Row field (boolean): while true, the `reasonField` text stands open as a box under the row, over the full row width, in the table view (entity/projection lists from `md` up, dashboard lists from `sm` up); the (i) stays and closes it.
|
|
@@ -480,7 +526,7 @@ type ListEmptyStateSpec = { // Replacement for the default "no rows" box of a li
|
|
|
480
526
|
description?: string;
|
|
481
527
|
action?: RowAction;
|
|
482
528
|
};
|
|
483
|
-
type ListRowDecoration = { // Computed fields for the loaded rows:
|
|
529
|
+
type ListRowDecoration = { // Computed fields for the loaded rows: `query` calls with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
|
|
484
530
|
query: string;
|
|
485
531
|
params?: Readonly<Record<string, unknown>>;
|
|
486
532
|
};
|
|
@@ -495,6 +541,7 @@ type ListTableSummaryRow = { // The query receives the list's current search, fi
|
|
|
495
541
|
query: string; // Qualified query name, e.g. `feature:query:order:summary`.
|
|
496
542
|
params?: Readonly<Record<string, unknown>>; // Extra payload keys merged over the list's own.
|
|
497
543
|
};
|
|
544
|
+
type ListToolbarActionsPlacement = (typeof LIST_TOOLBAR_ACTIONS_PLACEMENTS)[number];
|
|
498
545
|
type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
|
|
499
546
|
type ParsedRefTarget = {
|
|
500
547
|
featureName: string;
|
|
@@ -504,6 +551,10 @@ type PlatformComponent = {
|
|
|
504
551
|
react?: unknown;
|
|
505
552
|
native?: unknown;
|
|
506
553
|
};
|
|
554
|
+
type ProjectionDetailInitialTab = { // One `initialTab` rule: `tab` is a section id of the layout.
|
|
555
|
+
when: Exclude<FieldCondition, boolean>;
|
|
556
|
+
tab: string;
|
|
557
|
+
};
|
|
507
558
|
type QualifiedContentCollection = ContentCollectionDefinition & {
|
|
508
559
|
navQn: string;
|
|
509
560
|
};
|
|
@@ -525,11 +576,14 @@ type RecordHeaderSubtitlePart =
|
|
|
525
576
|
field: string;
|
|
526
577
|
navigate?: MetricNavigate;
|
|
527
578
|
format?: FormatSpec; // Formats the raw field value (e.g. `timestamp`); an empty value is still dropped.
|
|
579
|
+
prefix?: string; // i18n key of a text before the value ("Owner "); it stays plain text, a `navigate` link covers only the value.
|
|
528
580
|
}
|
|
529
581
|
;
|
|
530
582
|
type RecordNotice = {
|
|
531
583
|
title: string;
|
|
532
584
|
text?: string;
|
|
585
|
+
narrowTitle?: string; // Shown instead of `title` below `sm`.
|
|
586
|
+
narrowText?: string; // Shown instead of `text` below `sm`.
|
|
533
587
|
tone?: SelectOptionTone;
|
|
534
588
|
[field: string]: unknown;
|
|
535
589
|
};
|
|
@@ -552,6 +606,7 @@ type RecordProgressStep = {
|
|
|
552
606
|
type RecordStep = {
|
|
553
607
|
id: string;
|
|
554
608
|
title: string;
|
|
609
|
+
narrowTitle?: string; // Shown instead of `title` below `sm`.
|
|
555
610
|
detail?: string;
|
|
556
611
|
narrowDetail?: string; // Shown instead of `detail` below `sm`.
|
|
557
612
|
tone?: SelectOptionTone;
|
|
@@ -566,12 +621,16 @@ type RecordStepsSpec = {
|
|
|
566
621
|
subtitleField?: string; // Record field with a plain-text subtitle.
|
|
567
622
|
emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
|
|
568
623
|
narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
|
|
624
|
+
narrowMoreLabel?: string; // Plural base key for the toggle of the hidden rest: define `<key>.one` and `<key>.other` (the latter with `{count}`).
|
|
625
|
+
moreActionsLabel?: string; // i18n key of a short label before each step's further actions ("Clarify first?").
|
|
626
|
+
visibleWhen?: Exclude<FieldCondition, boolean>; // The whole panel is drawn only while the condition holds on the record.
|
|
569
627
|
actions?: RecordGuidanceAction[];
|
|
570
628
|
};
|
|
571
629
|
type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
|
|
572
630
|
field: string;
|
|
573
631
|
toneField?: string; // Row field holding a SelectOptionTone for the sentence's accent.
|
|
574
632
|
narrowField?: string; // Row field with a shorter sentence shown instead of `field` below `sm`.
|
|
633
|
+
icon?: IconKey; // Draws the sentence as plain text led by this icon (e.g. "sparkles" for an AI statement) instead of the bordered box.
|
|
575
634
|
};
|
|
576
635
|
type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
|
|
577
636
|
variants?: RelatedListEmptyStateVariant[];
|
|
@@ -598,7 +657,7 @@ type RowActionClientAction = {
|
|
|
598
657
|
style?: "primary" | "secondary" | "danger"; // Visual style.
|
|
599
658
|
icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
|
|
600
659
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
601
|
-
successMessage?: string; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`).
|
|
660
|
+
successMessage?: string | false; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`); `false` shows no toast.
|
|
602
661
|
};
|
|
603
662
|
type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
|
|
604
663
|
type RowActionDrawer = {
|
|
@@ -669,6 +728,12 @@ type SecretsEditScreenDefinition = {
|
|
|
669
728
|
access?: AccessRule;
|
|
670
729
|
};
|
|
671
730
|
type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
|
|
731
|
+
type StepListItem = { // One step of an `EditStepListSection`; `status` renders as a pill in `statusTone`.
|
|
732
|
+
title: string;
|
|
733
|
+
status?: string;
|
|
734
|
+
statusTone?: SelectOptionTone;
|
|
735
|
+
description?: string;
|
|
736
|
+
};
|
|
672
737
|
type TextFieldDef = PiiAndFieldState & {
|
|
673
738
|
type: "text";
|
|
674
739
|
description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
|
|
@@ -114,7 +114,7 @@ function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: bo
|
|
|
114
114
|
function SidebarUser(props: SidebarUserProps): ReactNode;
|
|
115
115
|
function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
|
|
116
116
|
function Stack(props: StackProps): ReactNode;
|
|
117
|
-
function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
|
|
117
|
+
function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; inset?: boolean; subBelow?: boolean; boardPadding?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
|
|
118
118
|
function StatusBadge(props: { tone: StatusBadgeTone; dot?: boolean; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
|
|
119
119
|
function StatusBarChart(props: { entries: StatusBarEntry[]; ariaLabel: string; startLabel?: string; endLabel?: string; highlightLast?: boolean; dense?: boolean; testId?: string; }): ReactNode; // Status bar strip (e.g. 90-day uptime): variable-height bars with gradient fade + tick line on top; the last entry gets a "now" accent stripe.
|
|
120
120
|
function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical" | "stacked"; heading?: string; description?: string; subtitles?: (string | undefined)[]; upNext?: { heading: string; title: string; subtitle?: string; }; testId?: string; compactTestId?: string; }): ReactNode; // Wizard step overview — numbered chips with a connector line between them.
|
|
@@ -135,6 +135,7 @@ function applyTokensToCssVars(_tokens: Tokens): void; // Historically wrote toke
|
|
|
135
135
|
function buildFileUploadFormData(input: FileUploadFormDataInput): FormData;
|
|
136
136
|
function buildNavRegistrySlice(schema: FeatureSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
|
|
137
137
|
function buildNavRegistrySliceForApp(app: AppSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
|
|
138
|
+
function clearNavCollapseState(): void; // Forgets the collapsed containers and the revealed screen; logout calls it so the next user starts expanded.
|
|
138
139
|
function clearRememberedListState(): void; // Forgets all remembered list state and the identity marker.
|
|
139
140
|
function cn(...inputs: ClassValue[]): string; // Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`).
|
|
140
141
|
function createBrowserDraftStorage(options?: CreateBrowserDraftStorageOptions): DraftStorage; // Default DraftStorage when createKumikoApp boots without one.
|
|
@@ -195,6 +196,12 @@ function useUserRoles(): string[] | undefined;
|
|
|
195
196
|
|
|
196
197
|
```ts
|
|
197
198
|
const BROWSER_LOCALE_STORAGE_KEY: "kumiko:locale";
|
|
199
|
+
const DrawnFilter: LucideIcon;
|
|
200
|
+
const DrawnPanel: LucideIcon;
|
|
201
|
+
const DrawnPencil: LucideIcon;
|
|
202
|
+
const DrawnSearch: LucideIcon;
|
|
203
|
+
const DrawnSparkles: LucideIcon;
|
|
204
|
+
const DrawnWand: LucideIcon;
|
|
198
205
|
const DropdownMenu: FC<Primitive.DropdownMenuProps>;
|
|
199
206
|
const DropdownMenuPortal: FC<Primitive.DropdownMenuPortalProps>;
|
|
200
207
|
const DropdownMenuTrigger: ForwardRefExoticComponent<Primitive.DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>>;
|
|
@@ -260,6 +267,8 @@ type BannerProps = { // Banner for an inline message or page state (for example,
|
|
|
260
267
|
density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
|
|
261
268
|
icon?: NavIconKey; // Icon left of the text.
|
|
262
269
|
title?: ReactNode; // Bold heading above `children`, inside the text column.
|
|
270
|
+
narrowTitle?: ReactNode; // Replaces `title` below sm.
|
|
271
|
+
narrowText?: ReactNode; // Replaces `children` below sm and stays visible there even when `inline` drops the text.
|
|
263
272
|
titleTestId?: string;
|
|
264
273
|
children?: ReactNode;
|
|
265
274
|
parts?: { text: string; strong?: boolean; }[]; // Structured text after `children`; `strong` parts render emphasized.
|
|
@@ -369,6 +378,8 @@ type CorePrimitives = {
|
|
|
369
378
|
MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
|
|
370
379
|
RecordBreadcrumb?: ComponentType<RecordBreadcrumbProps>; // Optional — without it the detail screen renders the path as plain links.
|
|
371
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.
|
|
372
383
|
RecordSteps?: ComponentType<RecordStepsProps>; // Optional — without it the steps render as a plain card.
|
|
373
384
|
ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
|
|
374
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.
|
|
@@ -679,6 +690,7 @@ type GridProps = { // Column-based layout.
|
|
|
679
690
|
flow?: boolean; // Fields flow left to right in wrapping rows sized by `GridCell.width` instead of equal-width tracks (screen forms and drawers).
|
|
680
691
|
list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
|
|
681
692
|
ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
|
|
693
|
+
tight?: boolean; // With `columns: "auto"`: the small gap of a chip row instead of the tile gap.
|
|
682
694
|
};
|
|
683
695
|
type HeaderActionGroupProps = {
|
|
684
696
|
children: ReactNode;
|
|
@@ -1323,6 +1335,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1323
1335
|
onDirtyChange?: (dirty: boolean) => void; // Fires when the form gains or loses unsaved input (field changes or a dirty extension section).
|
|
1324
1336
|
onCopyLink?: () => Promise<void> | void; // Copy-link action — only set in update mode (create mode has no entity id yet, hence no permalink).
|
|
1325
1337
|
actions?: RenderEditAction[]; // Header action buttons, rendered before the built-in copy-link/ delete/cancel/save controls.
|
|
1338
|
+
footerHint?: string; // Translated note on the left of the form footer (hidden below `sm`).
|
|
1326
1339
|
menuActions?: RenderEditAction[]; // Record actions declared with `placement: "menu"`, resolved like `actions`.
|
|
1327
1340
|
onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void; // Opens a relatedList section row's drawer-kind action.
|
|
1328
1341
|
submitLabel?: string; // i18n key for the submit button.
|
|
@@ -1336,7 +1349,8 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1336
1349
|
labelAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content inline after the label (e.g. ConfigSourceBadge).
|
|
1337
1350
|
fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
|
|
1338
1351
|
fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
|
|
1339
|
-
|
|
1352
|
+
formErrorOnTop?: boolean; // Renders the form-error banner above the sections instead of below them.
|
|
1353
|
+
fieldDescription?: (fieldName: string, values: Readonly<Record<string, unknown>>) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
|
|
1340
1354
|
rowAfterField?: (fieldName: string, state: { dirty: boolean; }) => ReactNode | undefined; // Extra full-width row drawn right after a field's cell (configEdit actions).
|
|
1341
1355
|
fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
|
|
1342
1356
|
markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
|
|
@@ -1348,6 +1362,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
|
|
|
1348
1362
|
hideActions?: boolean; // Renders the fields without RenderEdit's own action bar (save, cancel, delete, copy-link).
|
|
1349
1363
|
valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
|
|
1350
1364
|
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
|
+
activeTabId?: string; // Id of the active tab of a tabbed projectionDetail; handed to the `afterForm` slot.
|
|
1351
1366
|
fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
|
|
1352
1367
|
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).
|
|
1353
1368
|
submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
|
|
@@ -1547,11 +1562,12 @@ type StepListProps = {
|
|
|
1547
1562
|
}; // Badge next to the title, e.g. "Erledigt" for a finished list.
|
|
1548
1563
|
steps: StepListItem[];
|
|
1549
1564
|
footerActions?: StepAction[]; // Footer row: a ghost action for the whole list next to the primary next-step action.
|
|
1565
|
+
footerNote?: string; // Quiet line under the footer actions, e.g. "Nothing is saved without you."
|
|
1550
1566
|
collapsedAfter?: number; // Show only the first n steps plus "und k weitere Schritte" (expands on click).
|
|
1551
1567
|
collapseWhen?: "always" | "overflow"; // "always" (default) folds after `collapsedAfter`; "overflow" folds a `fill` list only when its steps do not fit its height, then shows as many as fit but at least `collapsedAfter`.
|
|
1552
1568
|
surface?: "ai" | "plain"; // "ai" (default) = AiSurface background, "plain" = no background.
|
|
1553
1569
|
fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
|
|
1554
|
-
progress?: "full" | "count" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "none" = neither, e.g. when `status` already says the list is done.
|
|
1570
|
+
progress?: "full" | "count" | "total" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "total" = only "n steps" (rejected ones left out), "none" = neither, e.g. when `status` already says the list is done.
|
|
1555
1571
|
emptyContent?: ReactNode;
|
|
1556
1572
|
selection?: StepListSelection; // Adds a checkbox per selectable step, a select-all row and selection footer actions.
|
|
1557
1573
|
phoneCard?: boolean; // On a phone the list reads as a card: the header sits inside the surface and the steps in a framed white box.
|
|
@@ -1561,6 +1577,7 @@ type StepListSelection = {
|
|
|
1561
1577
|
selectedIds: string[]; // Explicitly chosen step ids (controlled); prerequisites are added on top.
|
|
1562
1578
|
onSelectionChange: (selectedIds: string[]) => void;
|
|
1563
1579
|
actions: StepSelectionAction[]; // Replace `footerActions` while at least one step is selected.
|
|
1580
|
+
compact?: true; // Phone-card style: no select-all row, the actions stay visible at 0 selected (disabled unless `ignoresSelection`), a muted header and left-aligned footer.
|
|
1564
1581
|
};
|
|
1565
1582
|
type StepSelectability =
|
|
1566
1583
|
| {
|
|
@@ -1576,7 +1593,9 @@ type StepSelectability =
|
|
|
1576
1593
|
;
|
|
1577
1594
|
type StepSelectionAction = {
|
|
1578
1595
|
id: string;
|
|
1579
|
-
label: string; // Without a number: the list appends " (n)" with the effective selection size.
|
|
1596
|
+
label: string; // Without a number: the list appends " (n)" with the effective selection size (see `labelForCount`).
|
|
1597
|
+
labelForCount?: (count: number) => string; // Replaces the appended " (n)": the label for the effective selection size.
|
|
1598
|
+
ignoresSelection?: true; // No counter, never disabled by an empty selection (e.g. "Review one by one"); `onClick` still gets the selection.
|
|
1580
1599
|
onClick: (stepIds: string[]) => void; // Receives the effective selection in list order, prerequisites included.
|
|
1581
1600
|
variant?: "primary" | "secondary" | "ghost";
|
|
1582
1601
|
disabled?: boolean;
|
|
@@ -1591,6 +1610,7 @@ type StepTag = {
|
|
|
1591
1610
|
label: string;
|
|
1592
1611
|
tone?: "accent" | "muted" | "warn" | "ok" | "bad";
|
|
1593
1612
|
afterWaiting?: boolean; // A note about the step's history (e.g. just changed) reads after what it waits for.
|
|
1613
|
+
side?: true; // Sits in the right column of the row, above a trailing link (e.g. a risk chip over "Preview").
|
|
1594
1614
|
};
|
|
1595
1615
|
interface TextFieldProps extends FieldBase {
|
|
1596
1616
|
value: string;
|
|
@@ -1773,6 +1793,9 @@ type WorkspaceShellProps = {
|
|
|
1773
1793
|
focusRailNavQns?: string[]; // Top-level nav QNs the focus rail shows as tiles; the others sit behind a "More" tile that opens the full sidebar.
|
|
1774
1794
|
navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell.
|
|
1775
1795
|
fill?: boolean; // Viewport-fit shell.
|
|
1796
|
+
contentSurface?: "card" | "background"; // Surface behind the screen content.
|
|
1797
|
+
navStyle?: ShellNavStyle; // `"plain"` renders the sidebar without leading icons while expanded (the focus rail and the collapsed rail keep them), with uppercase group labels, quiet active entries, a panel-symbol sidebar trigger and a 58px title bar.
|
|
1798
|
+
notificationBellPlacement?: "header" | "overflow"; // `"header"` (default) draws the notification bell in the title bar; `"overflow"` moves it into the "…" menu, which then shows on every width.
|
|
1776
1799
|
children: ReactNode; // Screen content.
|
|
1777
1800
|
};
|
|
1778
1801
|
type WorkspaceShellUser = {
|