@cosmicdrift/kumiko-framework 0.410.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.
Files changed (32) hide show
  1. package/agents/api/framework-engine.md +2 -0
  2. package/agents/api/framework-ui-types.md +10 -0
  3. package/agents/api/renderer-web.md +113 -10
  4. package/agents/api/types.md +22 -0
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +4 -0
  7. package/agents/examples/realtime-sse.md +37 -2
  8. package/agents/examples/record-detail-layout.md +35 -2
  9. package/agents/examples/wizard-form.md +96 -5
  10. package/agents/features.md +6 -0
  11. package/agents/widgets.md +6 -0
  12. package/dist/db/queries/session-advisory-lock.js +3 -0
  13. package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
  14. package/dist/engine/boot-validator/list-table-options.js +1 -0
  15. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
  16. package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
  17. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  18. package/dist/engine/boot-validator/screens-forms.js +60 -3
  19. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  20. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  21. package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
  22. package/dist/engine/boot-validator/screens-lists.js +2 -2
  23. package/dist/engine/project-app-schema-for-roles.js +11 -10
  24. package/dist/engine/screen-helpers.d.ts +1 -0
  25. package/dist/engine/screen-helpers.js +1 -1
  26. package/dist/pipeline/context-services.d.ts +1 -0
  27. package/dist/pipeline/context-services.js +1 -0
  28. package/dist/pipeline/handler-context-scope.js +5 -1
  29. package/dist/pipeline/user-live-signals.d.ts +5 -0
  30. package/dist/pipeline/user-live-signals.js +20 -0
  31. package/package.json +3 -3
  32. package/src/changes.json +48 -0
@@ -1061,6 +1061,7 @@ type ListTableOptions = { // Opt-in table behaviour of a list.
1061
1061
  pinning?: boolean; // Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`.
1062
1062
  resizing?: boolean; // Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize.
1063
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.
1064
1065
  density?: {
1065
1066
  default?: ListTableDensity; // Row density on first visit.
1066
1067
  userChoice?: boolean; // Shows the density choice in the view menu and remembers it per session.
@@ -1527,6 +1528,7 @@ type RowActionWriteHandler = {
1527
1528
  confirm?: string; // i18n key for the confirm dialog description.
1528
1529
  confirmLabel?: string; // i18n key for the confirm button text in the dialog.
1529
1530
  visible?: FieldCondition; // Conditional visibility per row.
1531
+ showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
1530
1532
  style?: "primary" | "secondary" | "danger"; // Visual style.
1531
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.
1532
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 AvatarSize = "sm" | "md" | "lg";
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: ReactNode;
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 two roles: `page` is a page title (web: h1), while `section` is a group subheading (web: h2 with uppercase and muted styling).
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;
@@ -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` | 325 |
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 |
@@ -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` |
@@ -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
  ```
@@ -17,6 +17,7 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
17
17
  rendered from the columns of the screen's own query row
18
18
  - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
19
19
  and one `fields` tab (master data) — each `relatedList` runs its own query
20
+ - a header action with `showOnTabs: ["payments"]`, shown only while that tab is active
20
21
  - boot-validator catching two common author mistakes: a `metrics` entry
21
22
  with an empty `label`, and a `tabs` layout with fewer than two
22
23
  sections
@@ -571,6 +572,24 @@ test.describe("record-detail-layout — tall tab panel scrolls", () => {
571
572
  await expect(end).toBeInViewport();
572
573
  });
573
574
  });
575
+
576
+ test.describe("record-detail-layout — header action per tab", () => {
577
+ const recordPayment = "order-desk.action.recordPayment";
578
+
579
+ test("record-payment shows on the payments tab only", async ({ page }) => {
580
+ await page.goto("/?tab=payments");
581
+ await expect(page.getByTestId("kumiko-screen-projection-detail-tabs")).toBeVisible();
582
+ // The third header action lands in the overflow menu.
583
+ await page.getByRole("button", { name: "More actions" }).last().click();
584
+ await expect(page.getByText(recordPayment)).toBeVisible();
585
+
586
+ await page.goto("/?tab=items");
587
+ await expect(page.getByTestId("render-list-table")).toBeVisible();
588
+ // Only two actions remain, so no overflow menu is rendered.
589
+ await expect(page.getByRole("button", { name: "More actions" })).toHaveCount(0);
590
+ await expect(page.getByText(recordPayment)).toHaveCount(0);
591
+ });
592
+ });
574
593
  ```
575
594
 
576
595
  ### e2e/padding-parity-screenshots.spec.ts
@@ -795,10 +814,14 @@ describe("record-detail-layout showcase — registration", () => {
795
814
  ]);
796
815
  });
797
816
 
798
- test("screen-level actions carry refresh-order and keep download-invoice inline", () => {
817
+ test("screen-level actions carry refresh-order, inline download-invoice and the payments-only record-payment", () => {
799
818
  const screen = registry.getScreen("order-desk:screen:order-detail");
800
819
  if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
801
- expect(screen.actions?.map((a) => a.id)).toEqual(["refresh-order", "download-invoice"]);
820
+ expect(screen.actions?.map((a) => a.id)).toEqual([
821
+ "refresh-order",
822
+ "download-invoice",
823
+ "record-payment",
824
+ ]);
802
825
  expect(screen.inlineActions).toEqual(["download-invoice"]);
803
826
  });
804
827
 
@@ -890,6 +913,8 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
890
913
  // not inside any tab's Card. `inlineActions` keeps download-invoice a visible
891
914
  // button next to it where the page header would otherwise fold it into the menu.
892
915
  //
916
+ // 6. `showOnTabs` limits the record-payment action to the payments tab.
917
+ //
893
918
  // projectionDetail has no entity — it binds to an explicit query instead, so
894
919
  // every field name below (header, metrics, fields) is a column of that
895
920
  // query's row, not an entity field.
@@ -1032,6 +1057,14 @@ export function createOrderDeskFeature(): FeatureDefinition {
1032
1057
  screen: "order-detail",
1033
1058
  icon: "download",
1034
1059
  },
1060
+ {
1061
+ kind: "navigate",
1062
+ id: "record-payment",
1063
+ label: "order-desk.action.recordPayment",
1064
+ screen: "order-detail",
1065
+ icon: "plus",
1066
+ showOnTabs: ["payments"],
1067
+ },
1035
1068
  ],
1036
1069
  inlineActions: ["download-invoice"],
1037
1070
  access: { roles: ["Support", "Admin"] },