@cosmicdrift/kumiko-renderer 0.373.0 → 0.377.0

package/dist/web/widgets/form-fields.d.ts

@@ -0,0 +1,93 @@
+import type { ReactNode } from "react";
+export interface NumberFieldProps {
+    readonly label: string;
+    readonly id: string;
+    readonly name: string;
+    readonly value: number | undefined;
+    readonly onChange: (v: number | undefined) => void;
+    readonly required?: boolean;
+    readonly disabled?: boolean;
+    readonly hideLabel?: boolean;
+    readonly testId?: string;
+    /** `false` renders without thousands separators (e.g. a year). Default `true`. */
+    readonly grouping?: boolean;
+}
+/** Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die
+ *  wiederholte id/name/value/onChange-Verdrahtung ab. `value` darf `undefined`
+ *  sein (leeres Feld), intern auf den `""`-Empty-State des Inputs gemappt.
+ *  Einheiten (€/%) gehören ins Label (`t("…Summe (€)")`), nicht als Badge. */
+export declare function NumberField({ label, id, name, value, onChange, required, disabled, hideLabel, testId, grouping, }: NumberFieldProps): ReactNode;
+export declare const MoneyField: typeof NumberField;
+export declare const PercentField: typeof NumberField;
+interface FieldBase {
+    readonly label: string;
+    readonly id: string;
+    readonly name: string;
+    readonly required?: boolean;
+    readonly disabled?: boolean;
+    readonly hideLabel?: boolean;
+    readonly testId?: string;
+}
+export interface TextFieldProps extends FieldBase {
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly placeholder?: string;
+    readonly autoComplete?: string;
+}
+/** Textfeld = Field + Input(kind:"text"). */
+export declare function TextField({ label, id, name, value, onChange, required, disabled, placeholder, autoComplete, hideLabel, testId, }: TextFieldProps): ReactNode;
+export interface SelectFieldProps extends FieldBase {
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly options: readonly string[] | readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+}
+/** Auswahlfeld = Field + Input(kind:"select"). */
+export declare function SelectField({ label, id, name, value, onChange, options, required, disabled, hideLabel, testId, }: SelectFieldProps): ReactNode;
+export interface DateFieldProps extends FieldBase {
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly min?: string;
+    readonly max?: string;
+}
+/** Datumsfeld = Field + Input(kind:"date"), ISO yyyy-mm-dd. */
+export declare function DateField({ label, id, name, value, onChange, min, max, required, disabled, hideLabel, testId, }: DateFieldProps): ReactNode;
+export interface BooleanFieldProps extends FieldBase {
+    readonly value: boolean;
+    readonly onChange: (v: boolean) => void;
+}
+/** Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean"). */
+export declare function BooleanField({ label, id, name, value, onChange, required, disabled, hideLabel, testId, }: BooleanFieldProps): ReactNode;
+export interface TextareaFieldProps extends FieldBase {
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly rows?: number;
+}
+/** Mehrzeiliges Textfeld = Field + Input(kind:"textarea"). */
+export declare function TextareaField({ label, id, name, value, onChange, rows, required, disabled, hideLabel, testId, }: TextareaFieldProps): ReactNode;
+export interface RangeFieldProps extends FieldBase {
+    readonly value: number;
+    readonly onChange: (v: number) => void;
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+}
+/** Schieberegler = Field + Input(kind:"range"). */
+export declare function RangeField({ label, id, name, value, onChange, min, max, step, required, disabled, hideLabel, testId, }: RangeFieldProps): ReactNode;
+export interface FileFieldProps extends FieldBase {
+    /** FileRef-UUID der gespeicherten Datei, oder null. */
+    readonly value: string | null;
+    readonly onChange: (fileId: string | null) => void;
+    readonly accept?: readonly string[];
+    /** "image" zeigt eine Vorschau, "file" nur den Dateinamen. Default "file". */
+    readonly variant?: "file" | "image";
+    /** Bindet den Upload an ein konkretes Entity-Feld — der `/api/files`-Endpoint
+     *  prüft `accept`/`maxSize` dann serverseitig gegen dessen Feld-Definition. */
+    readonly entityType?: string;
+    readonly fieldName?: string;
+}
+/** Datei-Upload = Field + Input(kind:"file"|"image") — FileRef-basiert. */
+export declare function FileField({ label, id, name, value, onChange, accept, variant, entityType, fieldName, required, disabled, hideLabel, testId, }: FileFieldProps): ReactNode;
+export {};

package/dist/web/widgets/form-fields.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePrimitives } from "../../index.js";
+/** Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die
+ *  wiederholte id/name/value/onChange-Verdrahtung ab. `value` darf `undefined`
+ *  sein (leeres Feld), intern auf den `""`-Empty-State des Inputs gemappt.
+ *  Einheiten (€/%) gehören ins Label (`t("…Summe (€)")`), nicht als Badge. */
+export function NumberField({ label, id, name, value, onChange, required, disabled, hideLabel, testId, grouping, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "number", id: id, name: name, value: value ?? "", onChange: onChange, required: required, disabled: disabled, ...(grouping !== undefined && { grouping }) }) }));
+}
+// Aliase markieren die Feld-Absicht am Call-Site (lesbarer als NumberField
+// überall) ohne eigene Wrapper-Funktion vorzutäuschen — beide sind identisch
+// zu NumberField, kein Ort für künftige geld-/prozent-spezifische Formatierung.
+export const MoneyField = NumberField;
+export const PercentField = NumberField;
+/** Textfeld = Field + Input(kind:"text"). */
+export function TextField({ label, id, name, value, onChange, required, disabled, placeholder, autoComplete, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "text", id: id, name: name, value: value, onChange: onChange, required: required, disabled: disabled, ...(placeholder !== undefined && { placeholder }), ...(autoComplete !== undefined && { autoComplete }) }) }));
+}
+/** Auswahlfeld = Field + Input(kind:"select"). */
+export function SelectField({ label, id, name, value, onChange, options, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "select", id: id, name: name, value: value, onChange: onChange, options: options, required: required, disabled: disabled }) }));
+}
+/** Datumsfeld = Field + Input(kind:"date"), ISO yyyy-mm-dd. */
+export function DateField({ label, id, name, value, onChange, min, max, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "date", id: id, name: name, value: value, onChange: (v) => onChange(v ?? ""), required: required, disabled: disabled, ...(min !== undefined && { min }), ...(max !== undefined && { max }) }) }));
+}
+/** Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean"). */
+export function BooleanField({ label, id, name, value, onChange, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, layout: "inline", hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "boolean", id: id, name: name, value: value, onChange: onChange, required: required, disabled: disabled }) }));
+}
+/** Mehrzeiliges Textfeld = Field + Input(kind:"textarea"). */
+export function TextareaField({ label, id, name, value, onChange, rows, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "textarea", id: id, name: name, value: value, onChange: onChange, required: required, disabled: disabled, ...(rows !== undefined && { rows }) }) }));
+}
+/** Schieberegler = Field + Input(kind:"range"). */
+export function RangeField({ label, id, name, value, onChange, min, max, step, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: "range", id: id, name: name, value: value, onChange: onChange, min: min, max: max, required: required, disabled: disabled, ...(step !== undefined && { step }) }) }));
+}
+/** Datei-Upload = Field + Input(kind:"file"|"image") — FileRef-basiert. */
+export function FileField({ label, id, name, value, onChange, accept, variant = "file", entityType, fieldName, required, disabled, hideLabel, testId, }) {
+    const { Field, Input } = usePrimitives();
+    return (_jsx(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: _jsx(Input, { kind: variant, id: id, name: name, value: value, onChange: onChange, required: required, disabled: disabled, ...(accept !== undefined && { accept }), ...(entityType !== undefined && { entityType }), ...(fieldName !== undefined && { fieldName }) }) }));
+}

package/dist/web/widgets/index.d.ts

@@ -0,0 +1,27 @@
+export { AiTextArea, type AiTextAreaProps, AiTextField, type AiTextFieldProps, } from "./ai-text-field.tsx";
+export type { StackedAreaDateFormat, StackedAreaInitialWindow, StackedAreaRangeOption, StackedAreaRanges, StackedAreaWindowSelection, } from "./chart-window.ts";
+export { type ChartMarker, type ChartSeries, type ChartTone, SegmentBarChart, type SegmentBarRow, StackedAreaChart, StackedBarChart, StatusBarChart, type StatusBarEntry, smoothPath, TimeseriesChart, type TimeseriesHeight, type TimeseriesPoint, type TimeseriesReferenceLine, type TimeseriesXAxis, type TimeseriesYAxis, } from "./charts.tsx";
+export { CollapsibleSection } from "./collapsible-section.tsx";
+export { type DashboardListColumn, DashboardListTable } from "./dashboard-list.tsx";
+export { DetailList } from "./detail-list.tsx";
+export { Drawer, type DrawerProps } from "./drawer.tsx";
+export { FeedList, type FeedRow } from "./feed-list.tsx";
+export { FloatingPanel, type FloatingPanelGeometry, type FloatingPanelProps, } from "./floating-panel.tsx";
+export { BooleanField, type BooleanFieldProps, DateField, type DateFieldProps, FileField, type FileFieldProps, MoneyField, NumberField, type NumberFieldProps, PercentField, RangeField, type RangeFieldProps, SelectField, type SelectFieldProps, TextareaField, type TextareaFieldProps, TextField, type TextFieldProps, } from "./form-fields.tsx";
+export { InfinityList, type InfinityListProps, type InfinityListSelection, } from "./infinity-list.tsx";
+export { ModeSwitch, type ModeSwitchVariant } from "./mode-switch.tsx";
+export { type PhotoSlotSpec, PhotoSlots, type PhotoSlotsProps } from "./photo-slots.tsx";
+export { PlanCard, type PlanCardActionSlot, type PlanCardLinkSlot, type PlanCardPrice, type PlanCardProps, PlanGrid, type PlanGridProps, } from "./plan-card.tsx";
+export { ProgressBar } from "./progress-bar.tsx";
+export { ProgressList, type ProgressListRow } from "./progress-list.tsx";
+export { PublicShell, type PublicShellProps, type PublicShellVariant } from "./public-shell.tsx";
+export { QueryTable, type QueryTableColumn, type QueryTableProps } from "./query-table.tsx";
+export { type ComparisonMetric, ComparisonTable, type ResultColumn, ResultPanel, ResultTable, } from "./result-panel.tsx";
+export { SectionCard } from "./section-card.tsx";
+export { SideBySideTable, type SideBySideTableCell, type SideBySideTableColumn, type SideBySideTableRow, } from "./side-by-side-table.tsx";
+export { MiniStat, Sparkline, StatCard, type StatDelta, StatStripCell, type StatTone, } from "./stat.tsx";
+export { EmptyState, ErrorState, LoadingState } from "./states.tsx";
+export { STATUS_TONE_TEXT, StatusBadge, type StatusBadgeTone, type StatusTone, } from "./status-badge.tsx";
+export { StepBar } from "./step-bar.tsx";
+export { UploadZone, type UploadZoneProps } from "./upload-zone.tsx";
+export { useDraft } from "./use-draft.ts";

package/dist/web/widgets/index.js

@@ -0,0 +1,30 @@
+// Mid-Level-Widgets — Kompositionen über den Primitives (Card, DataTable,
+// Banner) + Theme-Tokens. Für Custom-Screens: erst hier schauen, dann bauen.
+// Katalog: docs.kumiko.rocks → Guides → Widgets; visueller Überblick im
+// styleguide-Sample.
+export { AiTextArea, AiTextField, } from "./ai-text-field.js";
+export { SegmentBarChart, StackedAreaChart, StackedBarChart, StatusBarChart, smoothPath, TimeseriesChart, } from "./charts.js";
+export { CollapsibleSection } from "./collapsible-section.js";
+export { DashboardListTable } from "./dashboard-list.js";
+export { DetailList } from "./detail-list.js";
+export { Drawer } from "./drawer.js";
+export { FeedList } from "./feed-list.js";
+export { FloatingPanel, } from "./floating-panel.js";
+export { BooleanField, DateField, FileField, MoneyField, NumberField, PercentField, RangeField, SelectField, TextareaField, TextField, } from "./form-fields.js";
+export { InfinityList, } from "./infinity-list.js";
+export { ModeSwitch } from "./mode-switch.js";
+export { PhotoSlots } from "./photo-slots.js";
+export { PlanCard, PlanGrid, } from "./plan-card.js";
+export { ProgressBar } from "./progress-bar.js";
+export { ProgressList } from "./progress-list.js";
+export { PublicShell } from "./public-shell.js";
+export { QueryTable } from "./query-table.js";
+export { ComparisonTable, ResultPanel, ResultTable, } from "./result-panel.js";
+export { SectionCard } from "./section-card.js";
+export { SideBySideTable, } from "./side-by-side-table.js";
+export { MiniStat, Sparkline, StatCard, StatStripCell, } from "./stat.js";
+export { EmptyState, ErrorState, LoadingState } from "./states.js";
+export { STATUS_TONE_TEXT, StatusBadge, } from "./status-badge.js";
+export { StepBar } from "./step-bar.js";
+export { UploadZone } from "./upload-zone.js";
+export { useDraft } from "./use-draft.js";

package/dist/web/widgets/infinity-list.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from "react";
+/** Position of the selected row among the rows loaded so far. `total`
+ *  counts loaded rows only; `hasMore` says whether further pages exist. */
+export type InfinityListSelection = {
+    readonly index: number;
+    readonly total: number;
+    readonly prevId: string | null;
+    readonly nextId: string | null;
+    readonly hasMore: boolean;
+};
+export type InfinityListProps<TData = unknown, TRow = Readonly<Record<string, unknown>>> = {
+    /** Dispatcher-Query-Type (`<feature>:query:<entity>:<verb>`). */
+    readonly query: string;
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /** Rows per page — sent as `limit` in the query payload. Default 50. */
+    readonly pageSize?: number;
+    readonly rows: (data: TData) => readonly TRow[];
+    /** Pull the next-page cursor from the result; `null` means last page. */
+    readonly nextCursor: (data: TData) => string | null;
+    /** Must derive from row content (e.g. `row.id`), not from `index` — a
+     *  live refresh reorders rows (new/changed rows move to the front). */
+    readonly rowId: (row: TRow, index: number) => string;
+    readonly renderRow: (row: TRow) => ReactNode;
+    readonly emptyState?: ReactNode;
+    readonly className?: string;
+    readonly testId?: string;
+    /** Subscribe to SSE events for the entity parsed from `query`
+     *  (`<feature>:query:<entity>:<verb>`) and refetch the first page on
+     *  any create/update/delete/restore event, merging it into the
+     *  already-accumulated rows instead of collapsing them — see
+     *  `useQuery`'s `live` option for the same convention. Default false. */
+    readonly live?: boolean;
+    /** Row id (as returned by `rowId`) whose position `onSelectionChange`
+     *  reports. The list itself does not highlight it — `renderRow` does. */
+    readonly selectedId?: string | null;
+    /** Fires when the selected row's position or neighbours change, e.g. for
+     *  a "message 4 of 6" header with previous/next buttons. Not called while
+     *  nothing is selected or the selected row is not loaded. */
+    readonly onSelectionChange?: (selection: InfinityListSelection) => void;
+};
+/** Cursor-paginated scroll list (mail inbox, activity feeds) — loads the
+ *  next page when the end sentinel becomes visible (IntersectionObserver),
+ *  instead of a pager bar like QueryTable/entityList. The query handler
+ *  receives `{ ...payload, limit, cursor? }` and returns rows plus the next
+ *  cursor (same cursor convention as the audit-log screen). */
+export declare function InfinityList<TData = unknown, TRow = Readonly<Record<string, unknown>>>({ query, payload, pageSize, rows, nextCursor, rowId, renderRow, emptyState, className, testId, live, selectedId, onSelectionChange, }: InfinityListProps<TData, TRow>): ReactNode;

package/dist/web/widgets/infinity-list.js

@@ -0,0 +1,211 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { entityFromQueryType, useDispatcher, useLiveEvents, useTranslation } from "../../index.js";
+import { EmptyState, ErrorState, LoadingState } from "./states.js";
+/** Cursor-paginated scroll list (mail inbox, activity feeds) — loads the
+ *  next page when the end sentinel becomes visible (IntersectionObserver),
+ *  instead of a pager bar like QueryTable/entityList. The query handler
+ *  receives `{ ...payload, limit, cursor? }` and returns rows plus the next
+ *  cursor (same cursor convention as the audit-log screen). */
+export function InfinityList({ query, payload, pageSize = 50, rows, nextCursor, rowId, renderRow, emptyState, className, testId, live = false, selectedId, onSelectionChange, }) {
+    const dispatcher = useDispatcher();
+    const t = useTranslation();
+    const subscribeLive = useLiveEvents();
+    const [state, setState] = useState({ kind: "loading" });
+    const sentinelRef = useRef(null);
+    const payloadKey = JSON.stringify(payload ?? {});
+    // rows/nextCursor/rowId are fresh closures on every caller render
+    // (inline arrow props). As useCallback deps that would recreate
+    // `load`/`refreshFirstPage` every render → the effects below would
+    // refetch in a loop. Refs keep them stable while always reading the
+    // current selector.
+    const rowsRef = useRef(rows);
+    rowsRef.current = rows;
+    const nextCursorRef = useRef(nextCursor);
+    nextCursorRef.current = nextCursor;
+    const rowIdRef = useRef(rowId);
+    rowIdRef.current = rowId;
+    // Discards a response whose request was superseded by a newer one before
+    // it resolved (e.g. two searches fired in quick succession) — without
+    // this, a slow earlier response can land after a faster later one and
+    // overwrite it, leaving stale rows on screen (fw#1705).
+    const requestSeq = useRef(0);
+    // IDs of the most recently loaded first page. refreshFirstPage() needs
+    // this to tell "row dropped from page 1 elsewhere" (must be pruned) apart
+    // from "row belongs to an already-accumulated later page" (must survive)
+    // — both are simply absent from the fresh page's id set.
+    const firstPageIdsRef = useRef(new Set());
+    // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
+    const load = useCallback(async (cursor) => {
+        const mySeq = ++requestSeq.current;
+        const res = await dispatcher.query(query, {
+            ...payload,
+            limit: pageSize,
+            ...(cursor !== null && { cursor }),
+        });
+        if (mySeq !== requestSeq.current)
+            return;
+        if (!res.isSuccess) {
+            setState({ kind: "error", error: res.error });
+            return;
+        }
+        const nextRows = rowsRef.current(res.data);
+        if (cursor === null) {
+            // Same identity as refreshFirstPage's freshIds/staleRows diff below
+            // — this ref is what that diff's previousFirstPageIds reads, so it
+            firstPageIdsRef.current = new Set(nextRows.map((row, index) => rowIdRef.current(row, index)));
+        }
+        setState((prev) => {
+            if (cursor === null || prev.kind !== "ready") {
+                return { kind: "ready", rows: nextRows, cursor: nextCursorRef.current(res.data) };
+            }
+            // The live-merge above can re-sort a row to the front of page 1; an
+            // offset-based cursor then re-serves that same row in a later page.
+            // Dedupe on append so it doesn't land twice under duplicate React
+            // keys.
+            const existingIds = new Set(prev.rows.map((row, index) => rowIdRef.current(row, index)));
+            const newRows = nextRows.filter((row, index) => !existingIds.has(rowIdRef.current(row, index)));
+            return {
+                kind: "ready",
+                rows: [...prev.rows, ...newRows],
+                cursor: nextCursorRef.current(res.data),
+            };
+        });
+    }, [dispatcher, query, pageSize, payloadKey]);
+    useEffect(() => {
+        setState({ kind: "loading" });
+        void load(null);
+        return () => {
+            requestSeq.current += 1;
+        };
+    }, [load]);
+    // Live-mode: on an SSE event for the query's entity, refetch only the
+    // first page and merge it in — rows the fresh page still contains move
+    // to the front (newest-first feeds), rows it dropped (edited/deleted
+    // elsewhere) are pruned, and everything beyond page 1 stays untouched.
+    // A full reload would collapse already-accumulated pages and jump the
+    // scroll position; see fw#1827.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
+    const refreshFirstPage = useCallback(async () => {
+        // Read, don't bump: a concurrent load() (e.g. the mount fetch still
+        // in flight) must still land. Bumping here would make load()'s own
+        // sequence check discard it, and the refresh below then bails on
+        // `prev.kind !== "ready"` — the list gets stuck in loading forever.
+        const seqAtStart = requestSeq.current;
+        const res = await dispatcher.query(query, { ...payload, limit: pageSize });
+        if (seqAtStart !== requestSeq.current)
+            return;
+        // skip: background live refresh failed, keep showing the current rows
+        if (!res.isSuccess)
+            return;
+        const freshRows = rowsRef.current(res.data);
+        const freshIds = new Set(freshRows.map((row, index) => rowIdRef.current(row, index)));
+        // A row absent from freshIds is stale for one of two reasons: it was
+        // dropped from page 1 (deleted, or filtered out elsewhere) and must be
+        // pruned, or it belongs to an already-accumulated later page and must
+        // survive. previousFirstPageIds — captured before it's overwritten below
+        // — is what tells those two cases apart.
+        const previousFirstPageIds = firstPageIdsRef.current;
+        firstPageIdsRef.current = freshIds;
+        setState((prev) => {
+            // skip: the initial load() is still in flight and owns the eventual
+            // state — a concurrent refresh landing here has nothing accumulated
+            // to merge into yet.
+            if (prev.kind === "loading")
+                return prev;
+            if (prev.kind !== "ready") {
+                // prev.kind === "error": this refresh succeeded — promote straight
+                // to "ready" instead of leaving the list stuck on the earlier
+                // failure forever (a live event should be able to recover it).
+                return { kind: "ready", rows: freshRows, cursor: nextCursorRef.current(res.data) };
+            }
+            const staleRows = prev.rows.filter((row, index) => {
+                const id = rowIdRef.current(row, index);
+                return !freshIds.has(id) && !previousFirstPageIds.has(id);
+            });
+            return { kind: "ready", rows: [...freshRows, ...staleRows], cursor: prev.cursor };
+        });
+    }, [dispatcher, query, pageSize, payloadKey]);
+    // Trailing debounce + in-flight coalesce: bulk SSE storms must not fan out
+    // into one query per event (fw#1829). A refresh already running schedules
+    // exactly one trailing pass after it settles.
+    const liveTimerRef = useRef(null);
+    const liveInFlightRef = useRef(false);
+    const liveTrailingRef = useRef(false);
+    useEffect(() => {
+        // skip: live mode off, no SSE subscription needed
+        if (!live)
+            return;
+        const entity = entityFromQueryType(query);
+        // skip: query type has no mapped entity, nothing to subscribe to
+        if (entity === undefined)
+            return;
+        const runRefresh = () => {
+            liveInFlightRef.current = true;
+            void refreshFirstPage().finally(() => {
+                liveInFlightRef.current = false;
+                if (liveTrailingRef.current) {
+                    liveTrailingRef.current = false;
+                    runRefresh();
+                }
+            });
+        };
+        const scheduleRefresh = () => {
+            if (liveTimerRef.current !== null)
+                clearTimeout(liveTimerRef.current);
+            liveTimerRef.current = setTimeout(() => {
+                liveTimerRef.current = null;
+                if (liveInFlightRef.current) {
+                    liveTrailingRef.current = true;
+                    return;
+                }
+                runRefresh();
+            }, 250);
+        };
+        const unsubscribe = subscribeLive(entity, scheduleRefresh);
+        return () => {
+            unsubscribe();
+            if (liveTimerRef.current !== null) {
+                clearTimeout(liveTimerRef.current);
+                liveTimerRef.current = null;
+            }
+        };
+    }, [live, query, refreshFirstPage, subscribeLive]);
+    useEffect(() => {
+        const sentinel = sentinelRef.current;
+        // skip: no further page or not ready yet — observer not needed
+        if (sentinel === null || state.kind !== "ready" || state.cursor === null)
+            return;
+        const cursor = state.cursor;
+        const observer = new IntersectionObserver((entries) => {
+            if (entries[0]?.isIntersecting === true)
+                void load(cursor);
+        });
+        observer.observe(sentinel);
+        return () => observer.disconnect();
+    }, [state, load]);
+    const onSelectionChangeRef = useRef(onSelectionChange);
+    onSelectionChangeRef.current = onSelectionChange;
+    useEffect(() => {
+        if (selectedId === undefined || selectedId === null || state.kind !== "ready")
+            return;
+        const ids = state.rows.map((row, index) => rowIdRef.current(row, index));
+        const index = ids.indexOf(selectedId);
+        if (index === -1)
+            return;
+        onSelectionChangeRef.current?.({
+            index,
+            total: ids.length,
+            prevId: ids[index - 1] ?? null,
+            nextId: ids[index + 1] ?? null,
+            hasMore: state.cursor !== null,
+        });
+    }, [state, selectedId]);
+    if (state.kind === "loading")
+        return _jsx(LoadingState, { rows: 4, testId: testId });
+    if (state.kind === "error")
+        return _jsx(ErrorState, { error: state.error, onRetry: () => void load(null), testId: testId });
+    if (state.rows.length === 0)
+        return _jsx(_Fragment, { children: emptyState ?? _jsx(EmptyState, { title: t("kumiko.list.no-entries"), testId: testId }) });
+    return (_jsxs("div", { "data-testid": testId, className: className ?? "flex flex-col overflow-y-auto", children: [state.rows.map((row, index) => (_jsx("div", { children: renderRow(row) }, rowId(row, index)))), _jsx("div", { ref: sentinelRef, className: "h-px" })] }));
+}

package/dist/web/widgets/mode-switch.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+export type ModeSwitchVariant = "outline" | "pill";
+/** Segmented-Control für sich ausschließende Modi — die prominente
+ *  Alternative zum vergrabenen <select>. */
+export declare function ModeSwitch<T extends string>({ value, options, onChange, ariaLabel, variant, className, testId, }: {
+    /** `null`: no option active. */
+    readonly value: T | null;
+    readonly options: readonly {
+        readonly value: T;
+        readonly label: string;
+        /** Muted tabular counter after the label. */
+        readonly count?: number;
+    }[];
+    readonly onChange: (value: T) => void;
+    readonly ariaLabel?: string;
+    /** `outline` (default): bordered segments, active tinted. `pill`: grey
+     *  track with a raised active segment. */
+    readonly variant?: ModeSwitchVariant;
+    readonly className?: string;
+    readonly testId?: string;
+}): ReactNode;

package/dist/web/widgets/mode-switch.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+/** Segmented-Control für sich ausschließende Modi — die prominente
+ *  Alternative zum vergrabenen <select>. */
+export function ModeSwitch({ value, options, onChange, ariaLabel, variant = "outline", className, testId, }) {
+    const pill = variant === "pill";
+    return (_jsx("div", { "data-testid": testId, role: "group", "aria-label": ariaLabel, className: cn("flex min-h-8", pill
+            ? "gap-0.5 rounded-lg bg-muted p-0.5"
+            : "overflow-hidden rounded-md border border-input bg-background", className), children: options.map((o) => {
+            const active = o.value === value;
+            return (_jsxs("button", { type: "button", "aria-pressed": active, onClick: () => onChange(o.value), className: cn("grow px-3 text-sm transition-colors", "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", pill
+                    ? [
+                        "rounded-md",
+                        active
+                            ? "bg-card font-semibold text-foreground shadow-sm dark:bg-foreground/10"
+                            : "text-muted-foreground hover:text-foreground",
+                    ]
+                    : [
+                        "border-l border-input first:border-l-0",
+                        active
+                            ? "bg-primary/10 font-semibold text-primary"
+                            : "text-foreground hover:bg-muted",
+                    ]), children: [o.label, o.count !== undefined && (_jsx("span", { "data-testid": testId !== undefined ? `${testId}-count-${o.value}` : undefined, className: cn("ml-1.5 font-normal tabular-nums", !active && "text-muted-foreground"), children: o.count }))] }, o.value));
+        }) }));
+}

package/dist/web/widgets/photo-slots.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+export type PhotoSlotSpec = {
+    readonly id: string;
+    /** The shot this slot asks for ("Front, angled") — the empty slot's
+     *  caption and the filled thumbnail's alt text. */
+    readonly label: string;
+    /** Set once the app holds the photo; the slot then shows the thumbnail. */
+    readonly previewUrl?: string;
+    /** Corner tag on a filled slot, e.g. "Cover photo". */
+    readonly badge?: string;
+};
+export type PhotoSlotsProps = {
+    readonly slots: readonly PhotoSlotSpec[];
+    /** Stores the photo for `slotId`. Throws on failure — the message is shown
+     *  under the slot. The app then passes the slot's `previewUrl`. */
+    readonly onUpload: (slotId: string, file: File) => Promise<void>;
+    /** Second line on an empty slot, e.g. "Camera or gallery". */
+    readonly pickHint?: ReactNode;
+    readonly accept?: readonly string[];
+    /** Opens that camera directly on phones; unset keeps camera and gallery. */
+    readonly capture?: "environment" | "user";
+    /** The first slot spans the full row (cover photo). Defaults to true. */
+    readonly featureFirst?: boolean;
+    readonly disabled?: boolean;
+    readonly testId?: string;
+};
+/** Guided photo capture: one tile per requested shot in a two-column grid,
+ *  each its own camera/gallery picker, filled tiles show the thumbnail. */
+export declare function PhotoSlots({ slots, onUpload, pickHint, accept, capture, featureFirst, disabled, testId, }: PhotoSlotsProps): ReactNode;

package/dist/web/widgets/photo-slots.js

@@ -0,0 +1,52 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Camera, Check, Loader2 } from "lucide-react";
+import { useState } from "react";
+import { useTranslation } from "../../index.js";
+import { toAcceptAttr } from "../lib/accept-attr.js";
+import { cn } from "../lib/cn.js";
+import { resizeImageBeforeUpload } from "../lib/resize-image.js";
+import { matchesAccept } from "./upload-zone.js";
+const DEFAULT_ACCEPT = ["image/*"];
+/** Guided photo capture: one tile per requested shot in a two-column grid,
+ *  each its own camera/gallery picker, filled tiles show the thumbnail. */
+export function PhotoSlots({ slots, onUpload, pickHint, accept = DEFAULT_ACCEPT, capture, featureFirst = true, disabled, testId, }) {
+    const t = useTranslation();
+    const [uploadStates, setUploadStates] = useState({});
+    function setSlotState(slotId, state) {
+        setUploadStates((prev) => {
+            const { [slotId]: _previous, ...rest } = prev;
+            return state === undefined ? rest : { ...rest, [slotId]: state };
+        });
+    }
+    async function uploadIntoSlot(slotId, file) {
+        if (!matchesAccept(file, accept)) {
+            setSlotState(slotId, { kind: "error", message: t("kumiko.widget.upload.rejected-type") });
+            return;
+        }
+        setSlotState(slotId, { kind: "uploading" });
+        try {
+            await onUpload(slotId, await resizeImageBeforeUpload(file));
+            setSlotState(slotId, undefined);
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : t("kumiko.widget.upload.error");
+            setSlotState(slotId, { kind: "error", message });
+        }
+    }
+    const acceptAttr = toAcceptAttr(accept);
+    return (_jsx("div", { "data-testid": testId, className: "grid grid-cols-2 gap-2.5", children: slots.map((slot, index) => {
+            const uploadState = uploadStates[slot.id];
+            const isUploading = uploadState?.kind === "uploading";
+            const isFeatured = featureFirst && index === 0;
+            const slotTestId = testId !== undefined ? `${testId}-slot-${slot.id}` : undefined;
+            return (_jsxs("div", { className: cn("flex flex-col gap-1", isFeatured && "col-span-2"), children: [_jsxs("label", { "data-testid": slotTestId, "data-filled": slot.previewUrl !== undefined ? "true" : undefined, className: cn("relative flex cursor-pointer flex-col items-center justify-center gap-1 overflow-hidden rounded-lg border-2 text-center text-sm transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-offset-2", isFeatured ? "h-52" : "h-32", slot.previewUrl !== undefined
+                            ? "border-transparent"
+                            : "border-dashed border-primary/60 bg-primary/5 text-primary", (disabled === true || isUploading) && "cursor-not-allowed opacity-60"), children: [slot.previewUrl !== undefined ? (_jsxs(_Fragment, { children: [_jsx("img", { src: slot.previewUrl, alt: slot.label, className: "absolute inset-0 size-full object-cover" }), slot.badge !== undefined && (_jsx("span", { className: "absolute bottom-2 left-2 rounded-full bg-background/90 px-2 py-0.5 text-xs font-semibold text-foreground", children: slot.badge })), _jsx("span", { className: "absolute top-2 right-2 flex size-6 items-center justify-center rounded-full bg-status-ok text-background", children: _jsx(Check, { "aria-hidden": "true", className: "size-3.5" }) })] })) : (_jsxs(_Fragment, { children: [isUploading ? (_jsx(Loader2, { "aria-hidden": "true", className: "size-6 animate-spin" })) : (_jsx(Camera, { "aria-hidden": "true", className: "size-6" })), _jsx("span", { className: "font-semibold", children: slot.label }), pickHint !== undefined && _jsx("span", { className: "text-xs", children: pickHint })] })), isUploading && (_jsx("span", { className: "sr-only", children: t("kumiko.widget.upload.uploading") })), _jsx("input", { type: "file", className: "sr-only", "data-testid": slotTestId !== undefined ? `${slotTestId}-input` : undefined, "aria-label": slot.label, disabled: disabled === true || isUploading, ...(acceptAttr !== undefined && { accept: acceptAttr }), ...(capture !== undefined && { capture }), onChange: (e) => {
+                                    const file = e.target.files?.[0];
+                                    // Reset so picking the same file again after an error still fires change.
+                                    e.target.value = "";
+                                    if (file !== undefined)
+                                        void uploadIntoSlot(slot.id, file);
+                                } })] }), uploadState?.kind === "error" && (_jsx("p", { role: "alert", className: "text-xs text-destructive", children: uploadState.message }))] }, slot.id));
+        }) }));
+}

package/dist/web/widgets/plan-card.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+export type PlanCardPrice = {
+    readonly amount: string;
+    readonly period?: string;
+};
+export type PlanCardActionSlot = {
+    readonly label: string;
+    readonly onClick: () => void;
+    readonly disabled?: boolean;
+};
+export type PlanCardLinkSlot = {
+    readonly label: string;
+    readonly href: string;
+    readonly target?: "_blank";
+};
+export type PlanCardProps = {
+    readonly title: string;
+    readonly description?: string;
+    /** null renders the price-unavailable state; undefined renders no price row. */
+    readonly price?: PlanCardPrice | null;
+    readonly features?: readonly ReactNode[];
+    readonly current?: boolean;
+    readonly cta?: PlanCardActionSlot;
+    /** Link-styled cta (e.g. contact sales); wins over `cta` when both are set. */
+    readonly ctaLink?: PlanCardLinkSlot;
+    readonly secondaryAction?: PlanCardActionSlot;
+    /** compact: one-off purchases (e.g. credit packs) — title+price in one row, no feature emphasis, smaller padding. */
+    readonly variant?: "default" | "compact";
+    readonly testId?: string;
+};
+export type PlanGridProps = {
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+export declare function PlanCard({ title, description, price, features, current, cta, ctaLink, secondaryAction, variant, testId, }: PlanCardProps): ReactNode;
+export declare function PlanGrid({ children, testId }: PlanGridProps): ReactNode;