@cosmicdrift/kumiko-framework 0.409.0 → 0.411.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.md +4 -2
- package/agents/api/framework-engine.md +4 -0
- package/agents/api/framework-ui-types.md +10 -0
- package/agents/api/renderer-web.md +113 -10
- package/agents/api/types.md +22 -0
- package/agents/api.md +1 -1
- package/agents/boot-rules.md +5 -0
- package/agents/examples/anonymous-access.md +23 -1
- package/agents/examples/contact.md +11 -5
- 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/features-index.md +1 -1
- package/agents/features.md +9 -2
- package/agents/widgets.md +6 -0
- package/dist/db/queries/session-advisory-lock.js +3 -0
- package/dist/engine/access.js +5 -1
- package/dist/engine/boot-validator/access-declarations.js +19 -0
- package/dist/engine/boot-validator/boot-rules.d.ts +25 -0
- package/dist/engine/boot-validator/handler-declaration-rules.d.ts +5 -0
- package/dist/engine/boot-validator/handler-declaration-rules.js +5 -0
- package/dist/engine/boot-validator/list-table-options.js +1 -0
- package/dist/engine/boot-validator/nav.js +4 -2
- 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/project-app-schema-for-roles.js +11 -10
- package/dist/engine/screen-helpers.d.ts +1 -0
- package/dist/engine/screen-helpers.js +1 -1
- 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 +54 -0
package/AGENTS.md
CHANGED
|
@@ -100,8 +100,10 @@ that holds global data calls `r.systemScope()`.
|
|
|
100
100
|
`{ access: { roles: ["Admin", "User"] } }`, or
|
|
101
101
|
`{ access: { openToAll: { reason: "<why every signed-in user may>" } } }`.
|
|
102
102
|
Screens and nav entries can narrow visibility further with their own
|
|
103
|
-
`access`. Anonymous endpoints use the `anonymous` role
|
|
104
|
-
|
|
103
|
+
`access`. Anonymous endpoints use the `anonymous` role; add `anySignedIn: true`
|
|
104
|
+
(`{ roles: ["anonymous"], anySignedIn: true }`) so a visitor who is signed in
|
|
105
|
+
passes whatever roles the session carries. Field level and row level rules
|
|
106
|
+
exist as well (see the table below).
|
|
105
107
|
An `openToAll` write handler whose payload contains personal fields must
|
|
106
108
|
say that every tenant member may write them:
|
|
107
109
|
`{ openToAll: { reason: "...", personalData: "tenant-members" } }`. The
|
|
@@ -276,6 +276,7 @@ type ActionFormScreenDefinition = {
|
|
|
276
276
|
summary?: {
|
|
277
277
|
title: string;
|
|
278
278
|
subtitle?: string;
|
|
279
|
+
params?: Readonly<Record<string, string>>;
|
|
279
280
|
}; // Context box above the fields (i18n keys).
|
|
280
281
|
submitStyle?: "primary" | "danger"; // Visual style of the submit button.
|
|
281
282
|
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).
|
|
@@ -1060,6 +1061,7 @@ type ListTableOptions = { // Opt-in table behaviour of a list.
|
|
|
1060
1061
|
pinning?: boolean; // Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`.
|
|
1061
1062
|
resizing?: boolean; // Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize.
|
|
1062
1063
|
keyboardNavigation?: boolean; // Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click.
|
|
1064
|
+
compactHeader?: boolean; // Renders the header row smaller (12px) and semibold.
|
|
1063
1065
|
density?: {
|
|
1064
1066
|
default?: ListTableDensity; // Row density on first visit.
|
|
1065
1067
|
userChoice?: boolean; // Shows the density choice in the view menu and remembers it per session.
|
|
@@ -1514,6 +1516,7 @@ type RoleAccessPersonalData = "public-intake";
|
|
|
1514
1516
|
type RoleAccessRule = {
|
|
1515
1517
|
roles: string[];
|
|
1516
1518
|
personalData?: RoleAccessPersonalData;
|
|
1519
|
+
anySignedIn?: true;
|
|
1517
1520
|
};
|
|
1518
1521
|
type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
|
|
1519
1522
|
type RowActionWriteHandler = {
|
|
@@ -1525,6 +1528,7 @@ type RowActionWriteHandler = {
|
|
|
1525
1528
|
confirm?: string; // i18n key for the confirm dialog description.
|
|
1526
1529
|
confirmLabel?: string; // i18n key for the confirm button text in the dialog.
|
|
1527
1530
|
visible?: FieldCondition; // Conditional visibility per row.
|
|
1531
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
1528
1532
|
style?: "primary" | "secondary" | "danger"; // Visual style.
|
|
1529
1533
|
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.
|
|
1530
1534
|
display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
|
|
@@ -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.
|
|
@@ -3950,6 +3951,7 @@ type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
|
|
|
3950
3951
|
type ContextServices = { // Infrastructure the app wired at boot, as the handler or job sees it.
|
|
3951
3952
|
redis?: Redis;
|
|
3952
3953
|
cacheSync?: CacheSyncBus;
|
|
3954
|
+
userLiveSignals?: UserLiveSignals;
|
|
3953
3955
|
jobRunner?: JobRunnerRef;
|
|
3954
3956
|
searchAdapter?: SearchAdapter;
|
|
3955
3957
|
entityCache?: EntityCache;
|
|
@@ -3980,6 +3982,9 @@ type HandlerTenants = {
|
|
|
3980
3982
|
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
3983
|
};
|
|
3982
3984
|
type JobLifecycle = Pick<HandlerLifecycle, "signal">;
|
|
3985
|
+
type UserLiveSignals = { // Addressed live signal: the SSE frame reaches only the listed users of the caller's own tenant.
|
|
3986
|
+
push(userIds: string[], signal: { type: string; entity?: string; id?: string; }): Promise<void>;
|
|
3987
|
+
};
|
|
3983
3988
|
```
|
|
3984
3989
|
|
|
3985
3990
|
## packages/types/src/handlers.ts
|
|
@@ -4164,6 +4169,7 @@ type SessionUserOrigin = "member-resolution";
|
|
|
4164
4169
|
type SharedContextFields = {
|
|
4165
4170
|
redis?: Redis;
|
|
4166
4171
|
cacheSync?: CacheSyncBus;
|
|
4172
|
+
userLiveSignals?: UserLiveSignals;
|
|
4167
4173
|
jobRunner?: JobRunnerRef;
|
|
4168
4174
|
configResolver?: ConfigResolver;
|
|
4169
4175
|
config?: ConfigAccessor;
|
|
@@ -4611,6 +4617,19 @@ type PersonalSubject =
|
|
|
4611
4617
|
;
|
|
4612
4618
|
```
|
|
4613
4619
|
|
|
4620
|
+
## packages/types/src/presence-types.ts
|
|
4621
|
+
|
|
4622
|
+
```ts
|
|
4623
|
+
type PresenceActivity = "viewing" | "editing";
|
|
4624
|
+
type PresenceEntry = {
|
|
4625
|
+
userId: string;
|
|
4626
|
+
displayName: string;
|
|
4627
|
+
activity: PresenceActivity;
|
|
4628
|
+
focus?: string;
|
|
4629
|
+
since: string; // ISO timestamp from which the user has been in this activity and focus.
|
|
4630
|
+
};
|
|
4631
|
+
```
|
|
4632
|
+
|
|
4614
4633
|
## packages/types/src/projection.ts
|
|
4615
4634
|
|
|
4616
4635
|
```ts
|
|
@@ -4794,6 +4813,8 @@ type EditFieldsSectionBase = {
|
|
|
4794
4813
|
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
4814
|
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
4815
|
subtitle?: string; // Short line (i18n key) under this step's title in the wizard step rail and in the "up next" box.
|
|
4816
|
+
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`.
|
|
4817
|
+
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
4818
|
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
4819
|
};
|
|
4799
4820
|
type EntityEditActionPlacement = "inline" | "menu";
|
|
@@ -4823,6 +4844,7 @@ type RowActionNavigateBase = {
|
|
|
4823
4844
|
params?: RowFieldExtractor; // Declarative URL search params extracted from the clicked row.
|
|
4824
4845
|
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
4846
|
visible?: FieldCondition; // Conditional visibility per row.
|
|
4847
|
+
showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
|
|
4826
4848
|
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
4849
|
rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
|
|
4828
4850
|
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
|
@@ -14,7 +14,7 @@ Format: one line per function or constant, object and options types as property
|
|
|
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` |
|
|
@@ -399,6 +402,7 @@
|
|
|
399
402
|
| <a id="handler-access-missing"></a>`handler/access-missing` | Every write, query and stream handler declares an access rule. | Set access: { roles: [...] } or { openToAll: { reason } }. | `packages/framework/src/engine/boot-validator/entity-handler-access-rules.ts` |
|
|
400
403
|
| <a id="handler-access-personal-data-unknown"></a>`handler/access-personal-data-unknown` | access.personalData is "public-intake" when set. | Use personalData: "public-intake" or remove it. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
401
404
|
| <a id="handler-anonymous-personal-data-undeclared"></a>`handler/anonymous-personal-data-undeclared` | A write handler that allows anonymous callers and accepts personal-data fields declares access.personalData "public-intake". | Declare access: { roles: [..., "anonymous"], personalData: "public-intake" }. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
405
|
+
| <a id="handler-any-signed-in-invalid"></a>`handler/any-signed-in-invalid` | access.anySignedIn is true when set and appears only next to the anonymous role, on endpoints that are public anyway. | Add "anonymous" to access.roles, or use { openToAll: { reason } } for every signed-in user without anonymous callers. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
402
406
|
| <a id="handler-escape-hatch-grants-invalid"></a>`handler/escape-hatch-grants-invalid` | An escapeHatch declares valid grants. | Correct the escapeHatch grants as named in the error message. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
403
407
|
| <a id="handler-escape-hatch-reason-invalid"></a>`handler/escape-hatch-reason-invalid` | An escapeHatch carries a valid reason. | Write an escapeHatch reason that explains the bypass. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
404
408
|
| <a id="handler-input-schema-not-introspectable"></a>`handler/input-schema-not-introspectable` | A write handler's input schema is a Zod shape whose keys boot can collect. | Use an object schema the boot validator can walk, as named in the error message. | `packages/framework/src/engine/boot-validator/handler-declaration-rules.ts` |
|
|
@@ -641,6 +645,7 @@
|
|
|
641
645
|
|
|
642
646
|
| Rule | Summary | Fix | Source |
|
|
643
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` |
|
|
644
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` |
|
|
645
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` |
|
|
646
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` |
|
|
@@ -14,6 +14,8 @@ Public endpoints without a logged-in user.
|
|
|
14
14
|
|
|
15
15
|
- `access: "anonymous"` on handlers that must stay public
|
|
16
16
|
- Rate limits that still bind anonymous callers (`per: "ip+handler"`)
|
|
17
|
+
- `anySignedIn: true` next to `anonymous`, so a visitor who is signed in with a role the
|
|
18
|
+
handler does not list is not turned away from a public form
|
|
17
19
|
|
|
18
20
|
## Source
|
|
19
21
|
|
|
@@ -63,6 +65,7 @@ const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
|
|
|
63
65
|
// Each value is written by exactly one test; the tenant is fixed, so rows are told apart by value, not by reset.
|
|
64
66
|
const PRODUCT_NAME = "Espresso Beans (anonymous read)";
|
|
65
67
|
const GUEST_EMAIL = "guest-checkout@example.com";
|
|
68
|
+
const DRIVER_EMAIL = "driver-checkout@example.com";
|
|
66
69
|
|
|
67
70
|
let stack: TestStack;
|
|
68
71
|
|
|
@@ -126,6 +129,19 @@ describe("guest checkout: anonymous write lands with placedBy=anonymous", () =>
|
|
|
126
129
|
expect(orders[0]?.placedBy).toBe(ANONYMOUS_USER_ID);
|
|
127
130
|
expect(orders[0]?.email).toBe(GUEST_EMAIL);
|
|
128
131
|
});
|
|
132
|
+
|
|
133
|
+
test("a signed-in caller with a role the handler does not list still checks out", async () => {
|
|
134
|
+
await stack.http.writeOk(
|
|
135
|
+
"shop:write:guest-order:place",
|
|
136
|
+
{ productId: "00000000-0000-4000-8000-000000000098", email: DRIVER_EMAIL },
|
|
137
|
+
TestUsers.driver,
|
|
138
|
+
);
|
|
139
|
+
const orders = (await selectMany(stack.db, guestOrderTable)).filter(
|
|
140
|
+
(order) => order.email === DRIVER_EMAIL,
|
|
141
|
+
);
|
|
142
|
+
expect(orders).toHaveLength(1);
|
|
143
|
+
expect(orders[0]?.placedBy).toBe(TestUsers.driver.id);
|
|
144
|
+
});
|
|
129
145
|
});
|
|
130
146
|
|
|
131
147
|
describe("regression guards", () => {
|
|
@@ -259,7 +275,13 @@ export const anonymousAccessFeature = defineFeature("shop", (r) => {
|
|
|
259
275
|
// anonymous root handler — the runtime personal-data gate
|
|
260
276
|
// (write-origin.ts) requires this explicit opt-in, the same way the
|
|
261
277
|
// boot validator would reject an openToAll declaration missing it.
|
|
262
|
-
|
|
278
|
+
// The browser sends the session cookie along, so a signed-in visitor arrives with its
|
|
279
|
+
// roles; anySignedIn keeps the checkout open to them whatever those roles are.
|
|
280
|
+
access: {
|
|
281
|
+
roles: [...access.anonymous, "User"],
|
|
282
|
+
personalData: "public-intake",
|
|
283
|
+
anySignedIn: true,
|
|
284
|
+
},
|
|
263
285
|
rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
|
|
264
286
|
});
|
|
265
287
|
|
|
@@ -10,7 +10,7 @@ Public contact form backend: the contact bundled feature with its required compa
|
|
|
10
10
|
|
|
11
11
|
Public contact form backend. The `contact` bundled feature stores questions, contact
|
|
12
12
|
requests and problem reports from website visitors and notifies every SystemAdmin (mail,
|
|
13
|
-
|
|
13
|
+
Telegram only when the app turns it on). The notification names only the kind, the app and a link into the inbox:
|
|
14
14
|
no name, address, phone, subject or message. Telegram is a third party where nothing can be
|
|
15
15
|
shredded or recalled, so it gets the same minimal text. Website senders get a fixed
|
|
16
16
|
acknowledgement that repeats nothing they typed; signed-in admin reports get a copy.
|
|
@@ -48,10 +48,16 @@ bun test --config=bunfig.integration.toml samples/recipes/contact
|
|
|
48
48
|
## Integration into a real app
|
|
49
49
|
|
|
50
50
|
1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
|
|
51
|
-
`files` with a file provider
|
|
51
|
+
`files` with a file provider and `config`.
|
|
52
52
|
2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
|
|
53
|
-
3. SystemAdmins set `contact:config:reply-to`
|
|
54
|
-
4. Embed `/contact/client.js` on the website; the form is yours.
|
|
53
|
+
3. SystemAdmins set `contact:config:reply-to` in the admin.
|
|
54
|
+
4. Embed `/contact/client.js` on the website; the form is yours. A website served by another
|
|
55
|
+
server can serve the same script from `CONTACT_CLIENT_SOURCE` and type its calls with
|
|
56
|
+
`ContactWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/contact/client`.
|
|
57
|
+
|
|
58
|
+
Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
|
|
59
|
+
that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
|
|
60
|
+
token, and SystemAdmins set `contact:config:telegram-chat`.
|
|
55
61
|
|
|
56
62
|
## Source files
|
|
57
63
|
|
|
@@ -152,7 +158,7 @@ describe("contact sample", () => {
|
|
|
152
158
|
//
|
|
153
159
|
// Prerequisites the app wires itself:
|
|
154
160
|
// - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
|
|
155
|
-
// - delivery with a mail channel (
|
|
161
|
+
// - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
|
|
156
162
|
// - a file provider, because the entities carry file fields
|
|
157
163
|
// - `kumiko schema generate` for the new tables
|
|
158
164
|
|
|
@@ -14,6 +14,7 @@ Server-sent events — live updates without F5.
|
|
|
14
14
|
|
|
15
15
|
- Entity writes that fan out over SSE
|
|
16
16
|
- Client subscription shape for live lists
|
|
17
|
+
- Presence: `createPresenceFeature({ entities: ["message"] })` answers who else has a message open; the heartbeat is a write, the others get an SSE frame addressed to their user id (no names inside)
|
|
17
18
|
|
|
18
19
|
## Source
|
|
19
20
|
|
|
@@ -48,7 +49,7 @@ import {
|
|
|
48
49
|
type TestStack,
|
|
49
50
|
unsafeCreateEntityTable,
|
|
50
51
|
} from "@cosmicdrift/kumiko-testing/stack";
|
|
51
|
-
import { chatFeature, messageEntity } from "../feature";
|
|
52
|
+
import { chatFeature, messageEntity, presenceFeature } from "../feature";
|
|
52
53
|
|
|
53
54
|
let stack: TestStack;
|
|
54
55
|
|
|
@@ -56,7 +57,7 @@ const admin = TestUsers.admin;
|
|
|
56
57
|
const user = createTestUser({ id: 2, roles: ["User"] });
|
|
57
58
|
|
|
58
59
|
beforeAll(async () => {
|
|
59
|
-
stack = await setupTestStack({ features: [chatFeature] });
|
|
60
|
+
stack = await setupTestStack({ features: [chatFeature, presenceFeature] });
|
|
60
61
|
await unsafeCreateEntityTable(stack.db, messageEntity);
|
|
61
62
|
await createEventsTable(stack.db);
|
|
62
63
|
});
|
|
@@ -151,11 +152,37 @@ describe("SSE broadcast on delete", () => {
|
|
|
151
152
|
expect(deleteEvent?.data["id"]).toBe(created.id);
|
|
152
153
|
});
|
|
153
154
|
});
|
|
155
|
+
|
|
156
|
+
describe("Presence frames", () => {
|
|
157
|
+
test("a user opening a message they share signals the others on it, by user id", async () => {
|
|
158
|
+
const created = await stack.http.writeOk<SaveContext>(
|
|
159
|
+
"chat:write:message:create",
|
|
160
|
+
{ channel: "general", text: "Shared" },
|
|
161
|
+
user,
|
|
162
|
+
);
|
|
163
|
+
await stack.eventDispatcher?.runOnce();
|
|
164
|
+
stack.events.reset();
|
|
165
|
+
const open = { entity: "message", id: created.id, activity: "viewing" };
|
|
166
|
+
|
|
167
|
+
await stack.http.writeOk("presence:write:heartbeat", open, user);
|
|
168
|
+
const seen = await stack.http.writeOk<{ others: Array<{ userId: string }> }>(
|
|
169
|
+
"presence:write:heartbeat",
|
|
170
|
+
open,
|
|
171
|
+
admin,
|
|
172
|
+
);
|
|
173
|
+
|
|
174
|
+
expect(seen.others.map((other) => other.userId)).toEqual([user.id]);
|
|
175
|
+
const frames = stack.events.sse.filter((e) => e.type === "presence:event:changed");
|
|
176
|
+
expect(frames.map((frame) => frame.data["userId"])).toEqual([user.id]);
|
|
177
|
+
expect(frames[0]?.data).not.toHaveProperty("displayName");
|
|
178
|
+
});
|
|
179
|
+
});
|
|
154
180
|
```
|
|
155
181
|
|
|
156
182
|
### src/feature.ts
|
|
157
183
|
|
|
158
184
|
```ts
|
|
185
|
+
import { createPresenceFeature } from "@cosmicdrift/kumiko-bundled-features/presence";
|
|
159
186
|
import {
|
|
160
187
|
createEntity,
|
|
161
188
|
createTextField,
|
|
@@ -183,4 +210,12 @@ export const chatFeature = defineFeature("chat", (r) => {
|
|
|
183
210
|
});
|
|
184
211
|
r.writeHandler(defineEntityDeleteHandler("message", messageEntity, adminWrite));
|
|
185
212
|
});
|
|
213
|
+
|
|
214
|
+
// Who else has a message open. The heartbeat is an ordinary write; the others learn about a
|
|
215
|
+
// change through an SSE frame addressed to them (`presence:event:changed`, no names inside),
|
|
216
|
+
// then refetch with `usePresence` / `usePresenceList` on the client.
|
|
217
|
+
export const presenceFeature = createPresenceFeature({
|
|
218
|
+
entities: ["message"],
|
|
219
|
+
roles: ["Admin", "User"],
|
|
220
|
+
});
|
|
186
221
|
```
|