@cosmicdrift/kumiko-framework 0.410.0 → 0.412.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-db.md +1 -1
- package/agents/api/framework-engine.md +50 -1
- package/agents/api/framework-errors.md +2 -0
- package/agents/api/framework-ui-types.md +10 -0
- package/agents/api/renderer-web.md +113 -10
- package/agents/api/types.md +30 -0
- package/agents/api.md +3 -3
- package/agents/boot-rules.md +4 -0
- package/agents/examples/api-docs.md +702 -0
- package/agents/examples/realtime-sse.md +37 -2
- package/agents/examples/record-detail-layout.md +35 -2
- package/agents/examples/wizard-form.md +96 -5
- package/agents/examples.md +1 -0
- package/agents/features.md +6 -0
- package/agents/widgets.md +6 -0
- package/dist/api/auth-middleware.d.ts +1 -0
- package/dist/api/index.d.ts +3 -0
- package/dist/api/index.js +3 -0
- package/dist/api/pat-auth-reject.d.ts +7 -0
- package/dist/api/pat-auth-reject.js +7 -0
- package/dist/api/server-middleware.js +2 -1
- package/dist/compliance/sub-processors.js +2 -2
- package/dist/config/index.d.ts +25 -0
- package/dist/config/index.js +28 -1
- package/dist/db/event-store-executor-read-paging.d.ts +1 -0
- package/dist/db/event-store-executor-read-paging.js +2 -1
- package/dist/db/queries/session-advisory-lock.js +3 -0
- package/dist/db/read-gate-clause.js +26 -7
- package/dist/db/table-builder.d.ts +1 -2
- package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
- package/dist/engine/boot-validator/list-table-options.js +1 -0
- package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
- package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
- package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
- package/dist/engine/boot-validator/screens-forms.js +60 -3
- 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 +19 -0
- package/dist/engine/boot-validator/screens-lists.js +2 -2
- package/dist/engine/define-feature.js +3 -0
- package/dist/engine/entity-list-runtime-options.js +12 -0
- package/dist/engine/factories.d.ts +2 -0
- package/dist/engine/feature-builder-state.d.ts +2 -1
- package/dist/engine/feature-builder-state.js +1 -0
- package/dist/engine/index.d.ts +5 -2
- package/dist/engine/index.js +4 -1
- package/dist/engine/project-app-schema-for-roles.js +11 -10
- package/dist/engine/registry-facade.js +13 -0
- package/dist/engine/screen-helpers.d.ts +1 -0
- package/dist/engine/screen-helpers.js +1 -1
- package/dist/engine/webhook-contracts.d.ts +12 -0
- package/dist/engine/webhook-contracts.js +172 -0
- package/dist/engine/webhook-events.d.ts +34 -0
- package/dist/engine/webhook-events.js +71 -0
- package/dist/errors/docs-url.js +2 -19
- package/dist/errors/error-codes.d.ts +20 -0
- package/dist/errors/error-codes.js +19 -0
- package/dist/errors/index.d.ts +2 -0
- package/dist/errors/index.js +1 -0
- package/dist/i18n/required-surface-keys.d.ts +4 -0
- package/dist/i18n/required-surface-keys.js +15 -0
- package/dist/pipeline/context-services.d.ts +1 -0
- package/dist/pipeline/context-services.js +1 -0
- package/dist/pipeline/handler-context-scope.js +5 -1
- package/dist/pipeline/user-live-signals.d.ts +5 -0
- package/dist/pipeline/user-live-signals.js +20 -0
- package/package.json +3 -3
- package/src/changes.json +78 -0
|
@@ -109,7 +109,7 @@ function listEventTenantIds(db: AnyDb): Promise<string[]>;
|
|
|
109
109
|
function loadSnapshotJson(path: string): Snapshot | null;
|
|
110
110
|
function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
|
|
111
111
|
function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
|
|
112
|
-
function physicalColumnName(table:
|
|
112
|
+
function physicalColumnName(table: unknown, field: string): string;
|
|
113
113
|
function primaryKey(opts: { columns: ColumnHandle[]; name?: string; }): PrimaryKeyDescriptor;
|
|
114
114
|
function readDatabaseNow(db: TenantDb): Promise<Date>; // Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree.
|
|
115
115
|
function recordEventsOwnedExclusivelyByTenant(db: DbRunner, aggregateType: string, aggregateId: string, tenantId: string): Promise<boolean>;
|
|
@@ -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; 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; 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;
|
|
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;
|
|
@@ -60,6 +60,7 @@ function createTextField<R extends true | false = false>(overrides: Partial<Omit
|
|
|
60
60
|
function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TimestampFieldDef & { required: R; }; // UTC instant for events occurring at a specific point in time (createdAt, loginAt, actualPickupAt).
|
|
61
61
|
function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TzFieldDef & { required: R; }; // IANA time-zone name (for example, "Europe/Berlin").
|
|
62
62
|
function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
|
|
63
|
+
function createWebhookContractResolver(features: FeatureDefinition[]): WebhookContractResolver; // Works on the feature list so a boot check, which has no registry, resolves the same contracts.
|
|
63
64
|
function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
|
|
64
65
|
function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
|
|
65
66
|
function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
|
|
@@ -95,9 +96,11 @@ function findForbiddenMembershipRole(roles: string[]): string | undefined;
|
|
|
95
96
|
function findForbiddenRoleAssignment(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
|
|
96
97
|
function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: string[]): string[] | undefined;
|
|
97
98
|
function findTierResolverUsage(features: FeatureDefinition[]): RegistrarExtensionRegistration | undefined;
|
|
99
|
+
function formatWebhookPayloadIssues(issues: WebhookPayloadIssue[]): string;
|
|
98
100
|
function from(ref: OwnershipRef, column?: string): FromRule;
|
|
99
101
|
function getStep(kind: StepKind): StepDef | undefined;
|
|
100
102
|
function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void; // Asserts a state transition is allowed.
|
|
103
|
+
function handlerDescriptionKey(handlerQn: string): string;
|
|
101
104
|
function handlerFieldLabelKey(handlerQn: string, fieldName: string): string;
|
|
102
105
|
function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;
|
|
103
106
|
function handlerTitleKey(handlerQn: string): string;
|
|
@@ -131,6 +134,7 @@ function parseQn(value: string): ParsedQn;
|
|
|
131
134
|
function parseRefTarget(raw: string, currentFeature: string): ParsedRefTarget;
|
|
132
135
|
function parseRefTargetEntityName(raw: string): string;
|
|
133
136
|
function parseTenantId(value: unknown): TenantId | null;
|
|
137
|
+
function parseWebhookPayload(contract: Pick<WebhookEventContract, "payload">, payload: unknown): WebhookPayloadResult; // Delivery sends the returned payload, never the input: zod strips keys the contract does not declare, so a field added to the source row cannot leak into a webhook by accident.
|
|
134
138
|
function projectAppSchemaForRoles(schema: AppSchema, roles: string[]): AppSchema;
|
|
135
139
|
function qn(scope: string, type: QnType, name: string): string;
|
|
136
140
|
function readClaim<T extends ClaimKeyType>(user: SessionUser, handle: ClaimKeyHandle<T>): ClaimKeyJsType<T> | undefined;
|
|
@@ -149,6 +153,7 @@ function setFields(table: ProjectionTable, fields: Record<string, unknown> | ((e
|
|
|
149
153
|
function stepsPipeline<TPayload = unknown, TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>>(closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => StepInstance[]): PipelineDef<TPayload, TData, TAwaits>;
|
|
150
154
|
function templateVariablesToZod(variables: TemplateVariables): z.ZodObject;
|
|
151
155
|
function tenantChannel(tenantId: TenantId): string;
|
|
156
|
+
function toEntityWebhookPayload(contract: Pick<WebhookEventContract, "payload" | "verb">, event: { aggregateId: string; payload: Readonly<Record<string, unknown>>; }): WebhookPayloadResult; // Maps a stored entity lifecycle event to the contract's payload: the aggregate id joins the event payload, and the contract parse drops every field it does not release, personal ones included, even when the event payload carries them.
|
|
152
157
|
function toKebab(input: string): string;
|
|
153
158
|
function typedPayload<TPayload>(event: { type: string; payload: Record<string, unknown>; }, eventDef: EventDef<TPayload>): TPayload;
|
|
154
159
|
function unwrapWorkflowStepError(error: unknown): unknown;
|
|
@@ -157,6 +162,8 @@ function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<
|
|
|
157
162
|
function validateBoot(rawFeatures: FeatureDefinition[], options?: ValidateBootOptions): void; // Validates all feature configurations at boot time.
|
|
158
163
|
function validateBundledListsOptions(options: unknown): void;
|
|
159
164
|
function walkStepInstances(steps: StepInstance[], where: string): Generator<StepInstance, void, void>;
|
|
165
|
+
function webhookEventDescriptionKey(webhookEventQn: string): string;
|
|
166
|
+
function webhookEventFieldKey(webhookEventQn: string, fieldPath: string): string; // `fieldPath` is the payload row name as the docs list it, nested fields dotted.
|
|
160
167
|
function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>; // Server counterpart of an actionForm's `derive`: recomputes the derived head fields before the schema validates them, so client-sent totals never count.
|
|
161
168
|
function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T>; // Override the success-side `data` of a WriteResult while forwarding the failure half untouched.
|
|
162
169
|
```
|
|
@@ -170,6 +177,7 @@ const BUILT_IN_MEMBERSHIP_ROLES: string[]; // Every membership role the engine r
|
|
|
170
177
|
const CODEMOD_PLACEHOLDER_REASON_MARKER: "state the operator use case here";
|
|
171
178
|
const ConfigScopes: { system: "system"; tenant: "tenant"; user: "user"; };
|
|
172
179
|
const DEFAULT_CURRENCIES: ["EUR", "USD", "GBP", "CHF", "JPY", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "NZD", "CNY", "INR"];
|
|
180
|
+
const DEFAULT_LIST_LIMIT: 50;
|
|
173
181
|
const DEFAULT_LOCALES: ["de", "en", "es"];
|
|
174
182
|
const DELIVERY_FAILURE_CODES;
|
|
175
183
|
const DELIVERY_SKIP_REASONS: ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
|
|
@@ -559,6 +567,7 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
|
|
|
559
567
|
softDelete?: boolean;
|
|
560
568
|
tenancy?: T; // "tenant" (default): auto-filtered by every db accessor.
|
|
561
569
|
systemStream?: boolean; // This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the creator's tenant.
|
|
570
|
+
webhookEvents?: boolean; // Lets token scopes release `<entity>.created/.updated/.deleted` as webhook events.
|
|
562
571
|
eventVersion?: number; // Schema version stamped on every lifecycle event (default 1, integer 1..999).
|
|
563
572
|
eventMigrations?: EntityEventMigration[]; // One step per version, fromVersion → fromVersion+1.
|
|
564
573
|
searchWeight?: number;
|
|
@@ -706,6 +715,7 @@ type FeatureDefinition = {
|
|
|
706
715
|
referenceData: ReferenceDataDef[];
|
|
707
716
|
notifications: Readonly<Record<string, NotificationDefinition>>;
|
|
708
717
|
events: Readonly<Record<string, EventDef>>;
|
|
718
|
+
webhookEvents?: Readonly<Record<string, WebhookEventDef>>; // Public webhook contracts from r.defineWebhookEvent, keyed by QN.
|
|
709
719
|
eventMigrations: Readonly<Record<string, EventMigrationDef[]>>;
|
|
710
720
|
configReads: string[];
|
|
711
721
|
handlerEntityMappings: Readonly<Record<string, string>>;
|
|
@@ -763,6 +773,7 @@ type FeatureRegistrar<TFeature extends string = string> = { // `TFeature` is the
|
|
|
763
773
|
notification(definition: { name: string; trigger?: { on: NameOrRef; }; recipient?: NotificationRecipientFn; data?: NotificationDataFn; templates?: Readonly<Record<string, NotificationTemplateFn>>; variables?: TemplateVariables; record?: NotificationRecordMapping; template?: Readonly<Record<string, NotificationTemplateBody>>; meta?: Readonly<Record<string, NotificationTemplateMeta>>; localizedTemplate?: () => NotificationLocalizedTemplate; renamedFrom?: string[]; systemOnly?: boolean; unsubscribe?: boolean; tenantTransport?: boolean; }): void;
|
|
764
774
|
translations(def: TranslationsDef): void;
|
|
765
775
|
defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: { version?: number; piiFields: EventPiiStance; migrations?: { fromVersion: number; toVersion: number; transform: EventUpcastFn | DeclarativeEventMigration; }[]; }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
|
|
776
|
+
defineWebhookEvent(definition: { name: string; description: string; payload: z.ZodObject; version: number; wireName?: string; }): WebhookEventHandle;
|
|
766
777
|
readsConfig(...qualifiedKeys: string[]): void;
|
|
767
778
|
readsConfig(options: { keys: string[]; }): void;
|
|
768
779
|
referenceData(entity: NameOrRef, data: Record<string, unknown>[], options?: { upsertKey?: string; }): void;
|
|
@@ -1061,6 +1072,7 @@ type ListTableOptions = { // Opt-in table behaviour of a list.
|
|
|
1061
1072
|
pinning?: boolean; // Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`.
|
|
1062
1073
|
resizing?: boolean; // Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize.
|
|
1063
1074
|
keyboardNavigation?: boolean; // Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click.
|
|
1075
|
+
compactHeader?: boolean; // Renders the header row smaller (12px) and semibold.
|
|
1064
1076
|
density?: {
|
|
1065
1077
|
default?: ListTableDensity; // Row density on first visit.
|
|
1066
1078
|
userChoice?: boolean; // Shows the density choice in the view menu and remembers it per session.
|
|
@@ -1457,6 +1469,8 @@ type Registry = {
|
|
|
1457
1469
|
getJob(qualifiedName: string): JobDefinition | undefined;
|
|
1458
1470
|
getAllJobs(): ReadonlyMap<string, JobDefinition>;
|
|
1459
1471
|
getEvent(qualifiedName: string): EventDef | undefined;
|
|
1472
|
+
getWebhookEventContract(qualifiedName: string): WebhookEventContract | undefined;
|
|
1473
|
+
getWebhookEventContracts(): WebhookEventContract[];
|
|
1460
1474
|
getEventUpcasters(): ReadonlyMap<string, { currentVersion: number; chain: ReadonlyMap<number, EventUpcastFn>; }>;
|
|
1461
1475
|
getExtension(name: string): RegistrarExtensionDef | undefined;
|
|
1462
1476
|
getExtensionUsages(extensionName: string): RegistrarExtensionRegistration[];
|
|
@@ -1527,6 +1541,7 @@ type RowActionWriteHandler = {
|
|
|
1527
1541
|
confirm?: string; // i18n key for the confirm dialog description.
|
|
1528
1542
|
confirmLabel?: string; // i18n key for the confirm button text in the dialog.
|
|
1529
1543
|
visible?: FieldCondition; // Conditional visibility per row.
|
|
1544
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
1530
1545
|
style?: "primary" | "secondary" | "danger"; // Visual style.
|
|
1531
1546
|
icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
|
|
1532
1547
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
@@ -1770,6 +1785,40 @@ type ValidationError = {
|
|
|
1770
1785
|
error: string;
|
|
1771
1786
|
};
|
|
1772
1787
|
type ValidationHookFn = (data: Readonly<Record<string, unknown>>) => ValidationError[] | null;
|
|
1788
|
+
type WebhookContractResolver = {
|
|
1789
|
+
get(qualifiedName: string): WebhookEventContract | undefined; // Declared contract, or one derived from an entity lifecycle event (`entity.verb`).
|
|
1790
|
+
declared(): WebhookEventContract[]; // Declared contracts only, sorted by QN.
|
|
1791
|
+
};
|
|
1792
|
+
type WebhookEntityVerb = "created" | "updated" | "deleted"; // Lifecycle verbs of an entity that can be released as webhook events.
|
|
1793
|
+
type WebhookEventContract = { // Public payload contract of a webhook event: declared by a feature or derived from an entity.
|
|
1794
|
+
qn: string;
|
|
1795
|
+
wireName: string; // The event name receivers see in the delivered webhook: `wireName` of a declared event, `entity.verb` of a derived one.
|
|
1796
|
+
description: string;
|
|
1797
|
+
payload: z.ZodObject;
|
|
1798
|
+
version: number;
|
|
1799
|
+
origin: "declared" | "entity";
|
|
1800
|
+
entity?: string;
|
|
1801
|
+
verb?: WebhookEntityVerb;
|
|
1802
|
+
};
|
|
1803
|
+
type WebhookEventHandle = {
|
|
1804
|
+
name: string;
|
|
1805
|
+
payload: z.ZodObject;
|
|
1806
|
+
version: number;
|
|
1807
|
+
};
|
|
1808
|
+
type WebhookPayloadIssue = {
|
|
1809
|
+
path: string;
|
|
1810
|
+
message: string;
|
|
1811
|
+
};
|
|
1812
|
+
type WebhookPayloadResult =
|
|
1813
|
+
| {
|
|
1814
|
+
ok: true;
|
|
1815
|
+
payload: Record<string, unknown>;
|
|
1816
|
+
}
|
|
1817
|
+
| {
|
|
1818
|
+
ok: false;
|
|
1819
|
+
issues: WebhookPayloadIssue[];
|
|
1820
|
+
}
|
|
1821
|
+
;
|
|
1773
1822
|
type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = { // Workflow definition — the result of defineWorkflow().
|
|
1774
1823
|
__kind: "workflow";
|
|
1775
1824
|
name: string;
|
|
@@ -21,6 +21,7 @@ function writeFailure(err: KumikoError): WriteFailure;
|
|
|
21
21
|
|
|
22
22
|
```ts
|
|
23
23
|
const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
|
|
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 };
|
|
24
25
|
```
|
|
25
26
|
|
|
26
27
|
## Classes
|
|
@@ -103,6 +104,7 @@ type FieldIssue = {
|
|
|
103
104
|
i18nKey: string;
|
|
104
105
|
params?: Readonly<Record<string, unknown>>;
|
|
105
106
|
};
|
|
107
|
+
type FrameworkErrorCode = keyof typeof frameworkErrorHttpStatus;
|
|
106
108
|
type WriteErrorInfo = {
|
|
107
109
|
code: string;
|
|
108
110
|
httpStatus: number;
|
|
@@ -322,6 +322,10 @@ type EditExtensionSection = {
|
|
|
322
322
|
id?: string; // Kebab-case tab id, used as the `?tab=` value.
|
|
323
323
|
kind: "extension";
|
|
324
324
|
title: string;
|
|
325
|
+
description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
|
|
326
|
+
subtitle?: string; // Wizard layouts only: short line under this step's title in the step rail and the "up next" box.
|
|
327
|
+
upNextHint?: string; // Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`.
|
|
328
|
+
summaryField?: string; // Wizard layouts only: field whose formatted value shows under the step label once the step is done.
|
|
325
329
|
component: PlatformComponent;
|
|
326
330
|
contributesToFormSubmit?: boolean; // When true, the extension registers via `useExtensionFormSubmit` and the surrounding form's Save button should activate for its dirty state.
|
|
327
331
|
entityName?: string; // Overrides the host-derived entity name passed to the mounted component.
|
|
@@ -334,11 +338,15 @@ type EditLayout = {
|
|
|
334
338
|
width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
|
|
335
339
|
mode?: "single" | "wizard" | "tabs"; // Default "single".
|
|
336
340
|
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.
|
|
341
|
+
hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
|
|
337
342
|
draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
|
|
338
343
|
wizard?: {
|
|
339
344
|
aside?: {
|
|
340
345
|
upNext: true;
|
|
346
|
+
finishDescription?: string;
|
|
341
347
|
};
|
|
348
|
+
saveAndCloseOnCreate?: boolean; // Also offers "Save and close" while creating a record (default: update mode only).
|
|
349
|
+
submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
|
|
342
350
|
}; // Wizard layouts only.
|
|
343
351
|
};
|
|
344
352
|
type EditWriteFormSection = {
|
|
@@ -458,6 +466,7 @@ type RowActionClientAction = {
|
|
|
458
466
|
confirm?: string; // i18n key for the confirm dialog description.
|
|
459
467
|
confirmLabel?: string; // i18n key for the confirm button, default `label`.
|
|
460
468
|
visible?: FieldCondition; // Conditional visibility per row.
|
|
469
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
461
470
|
style?: "primary" | "secondary" | "danger"; // Visual style.
|
|
462
471
|
icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
|
|
463
472
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
@@ -471,6 +480,7 @@ type RowActionDrawer = {
|
|
|
471
480
|
screen: string; // Short, unqualified id of an `actionForm` screen in the same feature.
|
|
472
481
|
params?: RowFieldExtractor; // Declarative prefill extracted from the clicked row.
|
|
473
482
|
visible?: FieldCondition; // Per-row conditional visibility.
|
|
483
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
474
484
|
style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
|
|
475
485
|
icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
|
|
476
486
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
@@ -18,13 +18,14 @@ function Avatar(props: AvatarProps): ReactNode;
|
|
|
18
18
|
function BareFormProvider(props: { children: ReactNode; }): ReactNode;
|
|
19
19
|
function BooleanField(props: BooleanFieldProps): ReactNode; // Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean").
|
|
20
20
|
function Card(props: CardProps): ReactNode;
|
|
21
|
-
function ChoiceCards<T extends string>(props: { value: T | null; options: { value: T; title: string; description?: string; aside?: string; disabled?: boolean; }[]; onChange: (value: T) => void; ariaLabel?: string; testId?: string; }): ReactNode; // Card-styled radio group for mutually exclusive choices that need a description or price line.
|
|
21
|
+
function ChoiceCards<T extends string>(props: { value: T | null; options: { value: T; title: string; description?: string; aside?: string; disabled?: boolean; }[]; onChange: (value: T) => void; ariaLabel?: string; label?: string; columns?: 1 | 2 | 3 | 4; variant?: "check" | "radio"; testId?: string; }): ReactNode; // Card-styled radio group for mutually exclusive choices that need a description or price line.
|
|
22
22
|
function ClampedText(props: { children: ReactNode; lines?: number; moreLabelKey?: string; maxHeightPx?: number; testId?: string; }): ReactNode; // Clamps content to `lines`; the toggle shows only while the content actually overflows.
|
|
23
23
|
function CollapsibleSection(props: { title: string; defaultOpen?: boolean; children: ReactNode; testId?: string; }): ReactNode; // Collapsible section using native <details> with React-controlled state; otherwise the open attribute resets to its initial value on every parent re-render.
|
|
24
24
|
function ComparisonTable<Col>(props: { columns: Col[]; columnHeader: (col: Col, index: number) => string; columnKey: (col: Col, index: number) => string; metrics: ComparisonMetric<Col>[]; metricLabel: string; testId?: string; className?: string; card?: boolean; }): ReactNode; // Transposed comparison table: row = metric, column = variant, with the best column optionally highlighted for each metric.
|
|
25
|
+
function Composer(props: ComposerProps): ReactNode; // Chat input: a label-less textarea with a text send button inside the field frame, bottom right.
|
|
25
26
|
function DateField(props: DateFieldProps): ReactNode; // Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd.
|
|
26
27
|
function DefaultAppShell(props: DefaultAppShellProps): ReactNode;
|
|
27
|
-
function DetailList(props: { rows: { id?: string; label: string; value: ReactNode; emphasize?: boolean; }[]; testId?: string; }): ReactNode; // Read-only key-value list for detail views (dimmed label on the left, value on the right).
|
|
28
|
+
function DetailList(props: { valueWeight?: "medium" | "normal"; layout?: "default" | "sidebar"; rows: { id?: string; label: string; value: ReactNode; emphasize?: boolean; }[]; testId?: string; }): ReactNode; // Read-only key-value list for detail views (dimmed label on the left, value on the right).
|
|
28
29
|
function DispatcherProvider(props: DispatcherProviderProps): ReactNode;
|
|
29
30
|
function Drawer(props: DrawerProps): ReactNode; // Slide-in panel beside a list (e.g. mail reader next to the inbox) — thin wrapper over the Sheet primitive with header/body/footer slots so screens skip per-route Radix boilerplate.
|
|
30
31
|
function DropdownMenuCheckboxItem(props: ComponentPropsWithoutRef<typeof Primitive.CheckboxItem>): ReactNode;
|
|
@@ -53,7 +54,7 @@ function MessageReader(props: MessageReaderProps): ReactNode; // Mail thread wit
|
|
|
53
54
|
function MessageThread(props: MessageThreadProps): ReactNode; // Mail conversation, oldest first: older messages fold to one line, the last one is open on a sheet.
|
|
54
55
|
function MiniStat(props: { label: string; value: string; tone?: StatTone; emphasize?: boolean; testId?: string; labelTestId?: string; valueTestId?: string; }): ReactNode; // Compact metric tile (without an icon) — for dense KPI grids.
|
|
55
56
|
function MobileTopBar(props: MobileTopBarProps): ReactNode; // Phone-only bar for focused screens: the shell header is hidden there, so the screen brings its own.
|
|
56
|
-
function ModeSwitch<T extends string>(props: { value: T | null; options: { value: T; label: string; count?: number; }[]; onChange: (value: T) => void; ariaLabel?: string; variant?: ModeSwitchVariant; className?: string; testId?: string; }): ReactNode; // Segmented control for mutually exclusive modes—the prominent alternative to the buried <select>.
|
|
57
|
+
function ModeSwitch<T extends string>(props: { value: T | null; options: { value: T; label: string; count?: number; disabled?: boolean; tone?: "warning"; }[]; onChange: (value: T) => void; ariaLabel?: string; variant?: ModeSwitchVariant; segmentWidth?: "auto" | "wide"; className?: string; testId?: string; }): ReactNode; // Segmented control for mutually exclusive modes—the prominent alternative to the buried <select>.
|
|
57
58
|
function NavProvider(props: NavProviderProps): ReactNode;
|
|
58
59
|
function NavTree(props: NavTreeProps): ReactNode;
|
|
59
60
|
function NumberField(props: NumberFieldProps): ReactNode; // Number field = Field + Input(kind:"number"); avoids repeating the id/name/value/onChange wiring at each screen.
|
|
@@ -63,6 +64,8 @@ function PhotoSlots(props: PhotoSlotsProps): ReactNode; // Guided photo capture:
|
|
|
63
64
|
function PlainContentEditor(props: ContentEditorProps): ReactNode;
|
|
64
65
|
function PlanCard(props: PlanCardProps): ReactNode;
|
|
65
66
|
function PlanGrid(props: PlanGridProps): ReactNode;
|
|
67
|
+
function PresenceAvatars(props: PresenceAvatarsProps): ReactNode; // Small round avatars of the people on a row, with "+n" for the rest; for list rows.
|
|
68
|
+
function PresenceNotice(props: PresenceNoticeProps): ReactNode; // One quiet line above a record: who else is on it and for how long.
|
|
66
69
|
function PrimitivesProvider(props: PrimitivesProviderProps): ReactNode;
|
|
67
70
|
function ProfileMenu(props: ProfileMenuProps): ReactNode;
|
|
68
71
|
function ProgressBar(props: { value: number; tone?: ProgressTone; size?: "default" | "thin"; ariaLabel?: string; className?: string; testId?: string; }): ReactNode; // Progress bar, `value` 0..1 (clamped).
|
|
@@ -77,13 +80,14 @@ function ResizableHandle(props: ResizablePrimitive.SeparatorProps & { withHandle
|
|
|
77
80
|
function ResizablePanel(props: ResizablePrimitive.PanelProps): JSX.Element;
|
|
78
81
|
function ResizablePanelGroup(props: ResizablePrimitive.GroupProps): JSX.Element;
|
|
79
82
|
function ResultPanel(props: { title: string; subtitle?: string; empty?: boolean; emptyText?: ReactNode; rows?: { label: string; value: ReactNode; emphasize?: boolean; }[]; footer?: ReactNode; children?: ReactNode; testId?: string; }): ReactNode; // Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes).
|
|
80
|
-
function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
|
|
83
|
+
function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; compactHeader?: boolean; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
|
|
81
84
|
function ScreenWidthProvider(props: { width: FormWidth | undefined; children: ReactNode; }): ReactNode;
|
|
82
85
|
function SectionCard(props: { title: string; subtitle?: string; action?: ReactNode; footer?: ReactNode; children: ReactNode; testId?: string; }): ReactNode; // Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens.
|
|
86
|
+
function SectionNavLayout(props: SectionNavLayoutProps): ReactNode; // Content column plus an "On this page" navigation in a right column (from xl), for custom screens.
|
|
83
87
|
function SelectField(props: SelectFieldProps): ReactNode; // Select field = Field + Input(kind:"select").
|
|
84
88
|
function SenderFrame(props: { children: ReactNode; label?: string; testId?: string; }): ReactNode; // Sand frame with one white sheet inside, for content that mimics a letter or mail.
|
|
85
89
|
function SenderSheet(props: { children: ReactNode; testId?: string; compact?: boolean; }): ReactNode; // The white sheet alone, for a frame that holds several sheets (PDF pages, thumbnails).
|
|
86
|
-
function SideBySideTable(props: { caption: string; rowHeaderLabel: string; columns: SideBySideTableColumn[]; rows: SideBySideTableRow[]; rowHeaderWidth?: number; testId?: string; }): ReactNode; // Small read-only grid with real table semantics (`th scope`) whose cells are arbitrary React nodes — for side-by-side comparisons like "from the document" vs.
|
|
90
|
+
function SideBySideTable(props: { caption: string; rowHeaderLabel: string; columns: SideBySideTableColumn[]; rows: SideBySideTableRow[]; rowHeaderWidth?: number; rowHeaderTone?: "muted" | "foreground"; testId?: string; }): ReactNode; // Small read-only grid with real table semantics (`th scope`) whose cells are arbitrary React nodes — for side-by-side comparisons like "from the document" vs.
|
|
87
91
|
function Sidebar(props: SidebarProps): ReactNode;
|
|
88
92
|
function SidebarBrand(props: SidebarBrandProps): ReactNode;
|
|
89
93
|
function SidebarMenu(props: React.ComponentProps<"ul">): React.JSX.Element;
|
|
@@ -154,6 +158,8 @@ function useIsViewportBelow(breakpointPx: number): boolean;
|
|
|
154
158
|
function useLiveEvents(): LiveEventSubscriber; // Hook for a useQuery-like consumer.
|
|
155
159
|
function useLocale(): LocaleResolver; // Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes.
|
|
156
160
|
function useNav(): NavApi;
|
|
161
|
+
function usePresence(props: UsePresenceOptions): UsePresenceResult; // Announces the user on one record: a heartbeat right away and every 15 s, a leave when the record closes.
|
|
162
|
+
function usePresenceList(props: UsePresenceListOptions): UsePresenceListResult; // Who else is on each of the given rows, for badges in a list.
|
|
157
163
|
function usePrimitives(): PrimitivesRegistry;
|
|
158
164
|
function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;
|
|
159
165
|
function useResolvers(): ReadonlyMap<string, ResolverComponent>;
|
|
@@ -225,15 +231,21 @@ type AvatarProps = {
|
|
|
225
231
|
id: string; // Stable identifier—the source for the background-color hash.
|
|
226
232
|
label: string; // Full name or email—the initials are extracted from this value.
|
|
227
233
|
size?: AvatarSize;
|
|
234
|
+
shape?: AvatarShape; // Default square; round suits inline presence markers.
|
|
228
235
|
testId?: string;
|
|
229
236
|
};
|
|
230
|
-
type
|
|
237
|
+
type AvatarShape = "square" | "round";
|
|
238
|
+
type AvatarSize = "xs" | "sm" | "md" | "lg";
|
|
231
239
|
type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
|
|
232
|
-
variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint"; // "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`).
|
|
240
|
+
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, nothing left to do here").
|
|
241
|
+
density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
|
|
242
|
+
icon?: NavIconKey; // Icon left of the text.
|
|
233
243
|
title?: ReactNode; // Bold heading above `children`, inside the text column.
|
|
234
244
|
titleTestId?: string;
|
|
235
|
-
children
|
|
245
|
+
children?: ReactNode;
|
|
246
|
+
parts?: { text: string; strong?: boolean; }[]; // Structured text after `children`; `strong` parts render emphasized.
|
|
236
247
|
actions?: ReactNode; // Optional—additional buttons or elements to the right of the text (for example, "Neu laden").
|
|
248
|
+
actionsPlacement?: "end" | "below"; // Where `actions` sit: `end` (default) right of the text, `below` under it.
|
|
237
249
|
padded?: boolean; // Adds outer spacing around the banner for page states where it renders alone in the main area (KumikoScreen "not-found", "loading", etc.).
|
|
238
250
|
testId?: string;
|
|
239
251
|
id?: string; // Set when a `<Field>` wraps this Banner as its control (no actual input exists for the label to target — see render-field.tsx's unsupported-field-type fallback).
|
|
@@ -292,6 +304,17 @@ interface ComparisonMetric<Col> {
|
|
|
292
304
|
value: (col: Col, index: number) => ReactNode;
|
|
293
305
|
bestIndex?: (cols: Col[]) => number; // Index of the best column for this row (highlighted); -1 = none.
|
|
294
306
|
}
|
|
307
|
+
type ComposerProps = {
|
|
308
|
+
value: string;
|
|
309
|
+
onChange: (value: string) => void;
|
|
310
|
+
onSubmit: () => void;
|
|
311
|
+
placeholder?: string;
|
|
312
|
+
disabled?: boolean;
|
|
313
|
+
submitLabel: string; // Text of the send button.
|
|
314
|
+
docked?: boolean; // Sticks to the bottom of a full-height flex-column parent so it stays visible while the thread scrolls; it also covers the bottom padding of the screen scroll.
|
|
315
|
+
rows?: number;
|
|
316
|
+
testId?: string;
|
|
317
|
+
};
|
|
295
318
|
type CorePrimitives = {
|
|
296
319
|
Button: ComponentType<ButtonProps>;
|
|
297
320
|
Banner: ComponentType<BannerProps>;
|
|
@@ -520,6 +543,18 @@ type FloatingPanelGeometry = {
|
|
|
520
543
|
width: number;
|
|
521
544
|
height: number;
|
|
522
545
|
};
|
|
546
|
+
type FloatingPanelPlacement =
|
|
547
|
+
| {
|
|
548
|
+
mode: "free";
|
|
549
|
+
}
|
|
550
|
+
| {
|
|
551
|
+
mode: "fixed";
|
|
552
|
+
rightPx: number;
|
|
553
|
+
bottomPx: number;
|
|
554
|
+
widthPx: number;
|
|
555
|
+
heightPx: number;
|
|
556
|
+
}
|
|
557
|
+
;
|
|
523
558
|
type FloatingPanelProps = {
|
|
524
559
|
title: ReactNode; // Header content; the header is the move handle.
|
|
525
560
|
headerActions?: ReactNode; // Header buttons (dock, minimize, close).
|
|
@@ -530,6 +565,9 @@ type FloatingPanelProps = {
|
|
|
530
565
|
minHeightPx?: number;
|
|
531
566
|
maxWidthPx?: number; // Default: viewport width minus twice the margin.
|
|
532
567
|
maxHeightPx?: number; // Default: viewport height minus twice the margin.
|
|
568
|
+
placement?: FloatingPanelPlacement; // "fixed" anchors the panel to the bottom right: no drag, no resize, nothing persisted.
|
|
569
|
+
bodyLayout?: "scroll" | "fill"; // "scroll" (default) pads and scrolls the body; "fill" gives children the whole body to pad and scroll themselves.
|
|
570
|
+
surface?: "default" | "ai"; // "ai" paints header and body with the AI surface.
|
|
533
571
|
testId?: string;
|
|
534
572
|
};
|
|
535
573
|
type FontTokens = {
|
|
@@ -579,8 +617,8 @@ type HeaderActionGroupProps = {
|
|
|
579
617
|
children: ReactNode;
|
|
580
618
|
className?: string;
|
|
581
619
|
};
|
|
582
|
-
type HeadingProps = { // Heading with
|
|
583
|
-
variant?: "page" | "section";
|
|
620
|
+
type HeadingProps = { // Heading with three roles: `page` is a page title (web: h1), `section` is a group subheading (web: h2 with uppercase and muted styling) and `group` is a plain 16px semibold sub-title (web: h2, normal case).
|
|
621
|
+
variant?: "page" | "section" | "group";
|
|
584
622
|
children: ReactNode;
|
|
585
623
|
testId?: string;
|
|
586
624
|
};
|
|
@@ -1106,6 +1144,17 @@ type PlanGridProps = {
|
|
|
1106
1144
|
children: ReactNode;
|
|
1107
1145
|
testId?: string;
|
|
1108
1146
|
};
|
|
1147
|
+
type PresenceAvatarsProps = {
|
|
1148
|
+
entries: PresenceEntry[];
|
|
1149
|
+
max?: number;
|
|
1150
|
+
testId?: string;
|
|
1151
|
+
};
|
|
1152
|
+
type PresenceNoticeProps = {
|
|
1153
|
+
entries: PresenceEntry[];
|
|
1154
|
+
describe?: (entry: PresenceEntry) => ReactNode; // Replaces the default "is looking at this / is editing this" text of the first entry.
|
|
1155
|
+
nowMs?: number; // Fixed "now" in epoch ms; without it the notice follows the clock once a minute.
|
|
1156
|
+
testId?: string;
|
|
1157
|
+
};
|
|
1109
1158
|
type PrimitivesProviderProps = {
|
|
1110
1159
|
children: ReactNode;
|
|
1111
1160
|
value: PrimitivesRegistry;
|
|
@@ -1314,10 +1363,17 @@ interface ResultColumn<Row> {
|
|
|
1314
1363
|
align?: "left" | "right";
|
|
1315
1364
|
cell: (row: Row) => ReactNode;
|
|
1316
1365
|
}
|
|
1366
|
+
type SectionNavLayoutProps = {
|
|
1367
|
+
items: FormSectionNavItem[]; // One entry per section; `id` must equal the DOM `id` of the section element in `children`.
|
|
1368
|
+
children: ReactNode;
|
|
1369
|
+
width?: keyof typeof screenFormColumnWidthClassName; // Content column width, default "4xl".
|
|
1370
|
+
testId?: string;
|
|
1371
|
+
};
|
|
1317
1372
|
type SectionProps = { // Titled group of fields.
|
|
1318
1373
|
id?: string; // DOM id — the scroll target of a form's "on this page" navigation.
|
|
1319
1374
|
title?: string; // Optional; without a title, the Section renders only the grouping and no header.
|
|
1320
1375
|
subtitle?: ReactNode; // Optional muted subtitle below the title, providing section context rather than only a label (analogous to `FormProps.subtitle`).
|
|
1376
|
+
subtitleBelowLgOnly?: boolean; // Shows the subtitle only below the `lg` breakpoint: a wizard's step rail carries the same text from `lg` up.
|
|
1321
1377
|
children: ReactNode;
|
|
1322
1378
|
actions?: ReactNode; // Rendered top-right in the title row — never a footer.
|
|
1323
1379
|
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.
|
|
@@ -1406,6 +1462,8 @@ type StepListItem = {
|
|
|
1406
1462
|
};
|
|
1407
1463
|
sources?: StepSource[]; // Where the step comes from, e.g. "Quelle: Seite 3, § 5" (caller-localized); each renders as a link under the description.
|
|
1408
1464
|
highlighted?: boolean; // Marks the step the reader is looking at (warm background).
|
|
1465
|
+
selectable?: StepSelectability; // Read only when the list has `selection`.
|
|
1466
|
+
dependsOn?: string[]; // Ids of prerequisite steps; selecting this step selects them too.
|
|
1409
1467
|
actions?: StepAction[]; // Rendered only while status is "open".
|
|
1410
1468
|
};
|
|
1411
1469
|
type StepListProps = {
|
|
@@ -1423,9 +1481,35 @@ type StepListProps = {
|
|
|
1423
1481
|
fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
|
|
1424
1482
|
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.
|
|
1425
1483
|
emptyContent?: ReactNode;
|
|
1484
|
+
selection?: StepListSelection; // Adds a checkbox per selectable step, a select-all row and selection footer actions.
|
|
1426
1485
|
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.
|
|
1427
1486
|
testId?: string;
|
|
1428
1487
|
};
|
|
1488
|
+
type StepListSelection = {
|
|
1489
|
+
selectedIds: string[]; // Explicitly chosen step ids (controlled); prerequisites are added on top.
|
|
1490
|
+
onSelectionChange: (selectedIds: string[]) => void;
|
|
1491
|
+
actions: StepSelectionAction[]; // Replace `footerActions` while at least one step is selected.
|
|
1492
|
+
};
|
|
1493
|
+
type StepSelectability =
|
|
1494
|
+
| {
|
|
1495
|
+
kind: "selectable";
|
|
1496
|
+
}
|
|
1497
|
+
| {
|
|
1498
|
+
kind: "missing-input";
|
|
1499
|
+
reason: string;
|
|
1500
|
+
}
|
|
1501
|
+
| {
|
|
1502
|
+
kind: "none";
|
|
1503
|
+
}
|
|
1504
|
+
;
|
|
1505
|
+
type StepSelectionAction = {
|
|
1506
|
+
id: string;
|
|
1507
|
+
label: string; // Without a number: the list appends " (n)" with the effective selection size.
|
|
1508
|
+
onClick: (stepIds: string[]) => void; // Receives the effective selection in list order, prerequisites included.
|
|
1509
|
+
variant?: "primary" | "secondary" | "ghost";
|
|
1510
|
+
disabled?: boolean;
|
|
1511
|
+
pending?: boolean;
|
|
1512
|
+
};
|
|
1429
1513
|
type StepSource = {
|
|
1430
1514
|
label: string;
|
|
1431
1515
|
onClick: () => void;
|
|
@@ -1452,6 +1536,7 @@ interface TextareaFieldProps extends FieldBase {
|
|
|
1452
1536
|
value: string;
|
|
1453
1537
|
onChange: (v: string) => void;
|
|
1454
1538
|
rows?: number;
|
|
1539
|
+
placeholder?: string;
|
|
1455
1540
|
}
|
|
1456
1541
|
type ThemeMenuItemProps = {
|
|
1457
1542
|
lightIcon?: ReactNode;
|
|
@@ -1560,6 +1645,24 @@ type UseFormResult<TValues extends FormValues> = {
|
|
|
1560
1645
|
controller: FormController<TValues>;
|
|
1561
1646
|
snapshot: FormSnapshot<TValues>;
|
|
1562
1647
|
};
|
|
1648
|
+
type UsePresenceListOptions = {
|
|
1649
|
+
entity: string;
|
|
1650
|
+
ids: string[];
|
|
1651
|
+
enabled?: boolean;
|
|
1652
|
+
};
|
|
1653
|
+
type UsePresenceListResult = {
|
|
1654
|
+
byId: Readonly<Record<string, PresenceEntry[]>>;
|
|
1655
|
+
};
|
|
1656
|
+
type UsePresenceOptions = {
|
|
1657
|
+
entity: string;
|
|
1658
|
+
id: string;
|
|
1659
|
+
activity: PresenceActivity;
|
|
1660
|
+
focus?: string; // Which part of the record the user is on, e.g. `field:title`.
|
|
1661
|
+
enabled?: boolean;
|
|
1662
|
+
};
|
|
1663
|
+
type UsePresenceResult = {
|
|
1664
|
+
others: PresenceEntry[];
|
|
1665
|
+
};
|
|
1563
1666
|
type UseQueryOptions = {
|
|
1564
1667
|
enabled?: boolean;
|
|
1565
1668
|
live?: boolean;
|
package/agents/api/types.md
CHANGED
|
@@ -1806,6 +1806,7 @@ type DataTableTableBlock = { // The DataTable props a screen's `table` block fee
|
|
|
1806
1806
|
view?: DataTableViewOptions; // View menu (column picker, density); absent = no menu.
|
|
1807
1807
|
resetAll?: DataTableResetAll; // Replaces the facet reset with one that also covers sort, search and page size.
|
|
1808
1808
|
exportList?: DataTableExport; // Present: the toolbar has an export button (web only).
|
|
1809
|
+
compactHeader?: boolean; // Smaller (12px) semibold header row.
|
|
1809
1810
|
serverGroups?: DataTableServerGroups; // Present: the rows are grouped on the server; replaces pager and infinite scroll.
|
|
1810
1811
|
totals?: DataTableTotals; // Present: a footer row with the server-computed totals of the filtered list.
|
|
1811
1812
|
notice?: DataTableListNotice; // Present: the toolbar says the answer is incomplete and asks to narrow the list.
|
|
@@ -3339,6 +3340,7 @@ type ParentVisibilityGateOption = {
|
|
|
3339
3340
|
};
|
|
3340
3341
|
type ParentVisibilityOption = {
|
|
3341
3342
|
entities: ReadonlyMap<string, EntityDefinition>;
|
|
3343
|
+
readModelEntities?: ReadonlyMap<string, { entity: EntityDefinition; table: SchemaTable; }>;
|
|
3342
3344
|
canReadEntity?: (entityName: string) => boolean;
|
|
3343
3345
|
resolveTable?: (entityName: string) => SchemaTable;
|
|
3344
3346
|
};
|
|
@@ -3459,6 +3461,13 @@ type UiHints = {
|
|
|
3459
3461
|
recommended?: boolean;
|
|
3460
3462
|
configurableOptions?: UiHintOption[];
|
|
3461
3463
|
};
|
|
3464
|
+
type WebhookEventDef = { // What `r.defineWebhookEvent` stores; `qn` is `<feature>:<name>`.
|
|
3465
|
+
qn: string;
|
|
3466
|
+
wireName: string;
|
|
3467
|
+
description: string;
|
|
3468
|
+
payload: z.ZodObject;
|
|
3469
|
+
version: number;
|
|
3470
|
+
};
|
|
3462
3471
|
```
|
|
3463
3472
|
|
|
3464
3473
|
## packages/types/src/field-state-conditions.ts
|
|
@@ -3950,6 +3959,7 @@ type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
|
|
|
3950
3959
|
type ContextServices = { // Infrastructure the app wired at boot, as the handler or job sees it.
|
|
3951
3960
|
redis?: Redis;
|
|
3952
3961
|
cacheSync?: CacheSyncBus;
|
|
3962
|
+
userLiveSignals?: UserLiveSignals;
|
|
3953
3963
|
jobRunner?: JobRunnerRef;
|
|
3954
3964
|
searchAdapter?: SearchAdapter;
|
|
3955
3965
|
entityCache?: EntityCache;
|
|
@@ -3980,6 +3990,9 @@ type HandlerTenants = {
|
|
|
3980
3990
|
writeTarget?: (tenantId: TenantId) => TenantWriteTarget; // Write target for ANOTHER tenant: a tenant-mode db bound to it plus the `streamTenantId` to hand the executor, so the event actor stays the operator.
|
|
3981
3991
|
};
|
|
3982
3992
|
type JobLifecycle = Pick<HandlerLifecycle, "signal">;
|
|
3993
|
+
type UserLiveSignals = { // Addressed live signal: the SSE frame reaches only the listed users of the caller's own tenant.
|
|
3994
|
+
push(userIds: string[], signal: { type: string; entity?: string; id?: string; }): Promise<void>;
|
|
3995
|
+
};
|
|
3983
3996
|
```
|
|
3984
3997
|
|
|
3985
3998
|
## packages/types/src/handlers.ts
|
|
@@ -4164,6 +4177,7 @@ type SessionUserOrigin = "member-resolution";
|
|
|
4164
4177
|
type SharedContextFields = {
|
|
4165
4178
|
redis?: Redis;
|
|
4166
4179
|
cacheSync?: CacheSyncBus;
|
|
4180
|
+
userLiveSignals?: UserLiveSignals;
|
|
4167
4181
|
jobRunner?: JobRunnerRef;
|
|
4168
4182
|
configResolver?: ConfigResolver;
|
|
4169
4183
|
config?: ConfigAccessor;
|
|
@@ -4611,6 +4625,19 @@ type PersonalSubject =
|
|
|
4611
4625
|
;
|
|
4612
4626
|
```
|
|
4613
4627
|
|
|
4628
|
+
## packages/types/src/presence-types.ts
|
|
4629
|
+
|
|
4630
|
+
```ts
|
|
4631
|
+
type PresenceActivity = "viewing" | "editing";
|
|
4632
|
+
type PresenceEntry = {
|
|
4633
|
+
userId: string;
|
|
4634
|
+
displayName: string;
|
|
4635
|
+
activity: PresenceActivity;
|
|
4636
|
+
focus?: string;
|
|
4637
|
+
since: string; // ISO timestamp from which the user has been in this activity and focus.
|
|
4638
|
+
};
|
|
4639
|
+
```
|
|
4640
|
+
|
|
4614
4641
|
## packages/types/src/projection.ts
|
|
4615
4642
|
|
|
4616
4643
|
```ts
|
|
@@ -4794,6 +4821,8 @@ type EditFieldsSectionBase = {
|
|
|
4794
4821
|
icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
|
|
4795
4822
|
countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
|
|
4796
4823
|
subtitle?: string; // Short line (i18n key) under this step's title in the wizard step rail and in the "up next" box.
|
|
4824
|
+
upNextHint?: string; // Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`.
|
|
4825
|
+
summaryField?: string; // Wizard layouts only: field of this section whose formatted value shows under the step label in the step rail once the step is done.
|
|
4797
4826
|
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.
|
|
4798
4827
|
};
|
|
4799
4828
|
type EntityEditActionPlacement = "inline" | "menu";
|
|
@@ -4823,6 +4852,7 @@ type RowActionNavigateBase = {
|
|
|
4823
4852
|
params?: RowFieldExtractor; // Declarative URL search params extracted from the clicked row.
|
|
4824
4853
|
tab?: string; // Section id of the tab to activate on the target projectionDetail (layout.mode "tabs"); merged into the navigate search params next to returnTo.
|
|
4825
4854
|
visible?: FieldCondition; // Conditional visibility per row.
|
|
4855
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
4826
4856
|
style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
|
|
4827
4857
|
rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
|
|
4828
4858
|
icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
|
package/agents/api.md
CHANGED
|
@@ -8,13 +8,13 @@ Format: one line per function or constant, object and options types as property
|
|
|
8
8
|
|
|
9
9
|
| Import path | File | Exports |
|
|
10
10
|
| --- | --- | --- |
|
|
11
|
-
| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` |
|
|
12
|
-
| `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` |
|
|
11
|
+
| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 440 |
|
|
12
|
+
| `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
|
|
13
13
|
| `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 156 |
|
|
14
14
|
| `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 151 |
|
|
15
15
|
| `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
|
|
16
16
|
| `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
|
|
17
|
-
| `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` |
|
|
17
|
+
| `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 344 |
|
|
18
18
|
| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 22 |
|
|
19
19
|
| `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
|
|
20
20
|
| `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |
|
package/agents/boot-rules.md
CHANGED
|
@@ -366,7 +366,10 @@
|
|
|
366
366
|
| <a id="form-tab-title-missing"></a>`form/tab-title-missing` | Every tab section has a non-empty title. | Give each tab section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
367
367
|
| <a id="form-tabs-too-few-sections"></a>`form/tabs-too-few-sections` | A tabs layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
368
368
|
| <a id="form-tabs-unsupported-screen-type"></a>`form/tabs-unsupported-screen-type` | Tabs layout is used only on projectionDetail and entityEdit screens. | Use mode: "wizard" or "single". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
369
|
+
| <a id="form-wizard-option-without-wizard"></a>`form/wizard-option-without-wizard` | layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout. | Remove the option or set mode: "wizard". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
369
370
|
| <a id="form-wizard-step-title-missing"></a>`form/wizard-step-title-missing` | Every wizard section has a non-empty title. | Give each wizard section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
371
|
+
| <a id="form-wizard-submit-condition-field-unknown"></a>`form/wizard-submit-condition-field-unknown` | layout.wizard.submitDisabledWhen names a field of the layout. | Use a field name declared in one of the sections. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
372
|
+
| <a id="form-wizard-summary-field-unknown"></a>`form/wizard-summary-field-unknown` | A wizard section summaryField names a field of that section. | Use a field name declared in the section. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
370
373
|
| <a id="form-wizard-too-few-sections"></a>`form/wizard-too-few-sections` | A wizard layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
371
374
|
| <a id="form-write-form-section-unsupported"></a>`form/write-form-section-unsupported` | Inline form layouts have no writeForm sections. | Move the section to a projectionDetail screen or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
|
|
372
375
|
| <a id="form-write-only-field"></a>`form/write-only-field` | Inline form fields do not declare writeOnly. | Remove writeOnly; use format: "password" for a masked input. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
|
|
@@ -642,6 +645,7 @@
|
|
|
642
645
|
|
|
643
646
|
| Rule | Summary | Fix | Source |
|
|
644
647
|
| --- | --- | --- | --- |
|
|
648
|
+
| <a id="projection-detail-action-show-on-tabs-invalid"></a>`projection-detail/action-show-on-tabs-invalid` | A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs". | List existing section ids or remove showOnTabs. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
|
|
645
649
|
| <a id="projection-detail-extension-contributes-to-form-submit"></a>`projection-detail/extension-contributes-to-form-submit` | A projectionDetail extension section does not set contributesToFormSubmit. | Omit contributesToFormSubmit and persist through the extension's own dispatcher writes. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
|
|
646
650
|
| <a id="projection-detail-extension-entity-name-missing"></a>`projection-detail/extension-entity-name-missing` | A projectionDetail extension section declares entityName. | Set entityName to the domain entity the extension persists against. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
|
|
647
651
|
| <a id="projection-detail-header-with-record-title-field"></a>`projection-detail/header-with-record-title-field` | A projectionDetail with a header sets no recordTitleField. | Drop recordTitleField; header.title names the record. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
|