@cosmicdrift/kumiko-renderer-web 1.0.0 → 2.0.0

package/src/widgets/drawer.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "../ui/sheet";
+
+export type DrawerProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly side?: "left" | "right" | "top" | "bottom";
+  readonly title?: ReactNode;
+  readonly description?: ReactNode;
+  readonly footer?: ReactNode;
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
+/** 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. */
+export function Drawer({
+  open,
+  onOpenChange,
+  side = "right",
+  title,
+  description,
+  footer,
+  children,
+  testId,
+}: DrawerProps): ReactNode {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side={side} data-testid={testId}>
+        {(title !== undefined || description !== undefined) && (
+          <SheetHeader>
+            {title !== undefined && <SheetTitle>{title}</SheetTitle>}
+            {description !== undefined && <SheetDescription>{description}</SheetDescription>}
+          </SheetHeader>
+        )}
+        <div className="flex-1 overflow-y-auto px-4">{children}</div>
+        {footer !== undefined && <SheetFooter>{footer}</SheetFooter>}
+      </SheetContent>
+    </Sheet>
+  );
+}

package/src/widgets/feed-list.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+
+export type FeedRow = {
+  readonly id: string;
+  readonly primary: string;
+  readonly trailing?: string;
+};
+
+/** Nicht-tabellarische Kurzliste (z.B. "nächste Termine") — Primary-Text +
+ *  optionaler rechtsbündiger Trailing-Wert pro Zeile. */
+export function FeedList({
+  rows,
+  emptyContent,
+  testId,
+}: {
+  readonly rows: readonly FeedRow[];
+  readonly emptyContent?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  if (rows.length === 0) {
+    return <div data-testid={testId}>{emptyContent}</div>;
+  }
+  return (
+    <ul data-testid={testId} className="flex max-h-64 flex-col overflow-y-auto pr-1 text-sm">
+      {rows.map((row) => (
+        <li key={row.id} className="flex justify-between gap-4 border-b py-1.5 last:border-b-0">
+          <span>{row.primary}</span>
+          {row.trailing !== undefined && (
+            <span className="tabular-nums text-muted-foreground">{row.trailing}</span>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/widgets/form-fields.tsx

@@ -0,0 +1,326 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+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 testId?: string;
+}
+
+/** 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,
+  testId,
+}: NumberFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="number"
+        id={id}
+        name={name}
+        value={value ?? ""}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
+// 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;
+
+interface FieldBase {
+  readonly label: string;
+  readonly id: string;
+  readonly name: string;
+  readonly required?: boolean;
+  readonly disabled?: 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 function TextField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  required,
+  disabled,
+  placeholder,
+  autoComplete,
+  testId,
+}: TextFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="text"
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+        {...(placeholder !== undefined && { placeholder })}
+        {...(autoComplete !== undefined && { autoComplete })}
+      />
+    </Field>
+  );
+}
+
+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 function SelectField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  options,
+  required,
+  disabled,
+  testId,
+}: SelectFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="select"
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        options={options}
+        required={required}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
+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 function DateField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  min,
+  max,
+  required,
+  disabled,
+  testId,
+}: DateFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="date"
+        id={id}
+        name={name}
+        value={value}
+        onChange={(v) => onChange(v ?? "")}
+        required={required}
+        disabled={disabled}
+        {...(min !== undefined && { min })}
+        {...(max !== undefined && { max })}
+      />
+    </Field>
+  );
+}
+
+export interface BooleanFieldProps extends FieldBase {
+  readonly value: boolean;
+  readonly onChange: (v: boolean) => void;
+}
+
+/** Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean"). */
+export function BooleanField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  required,
+  disabled,
+  testId,
+}: BooleanFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} layout="inline" testId={testId}>
+      <Input
+        kind="boolean"
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
+export interface TextareaFieldProps extends FieldBase {
+  readonly value: string;
+  readonly onChange: (v: string) => void;
+  readonly rows?: number;
+}
+
+/** Mehrzeiliges Textfeld = Field + Input(kind:"textarea"). */
+export function TextareaField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  rows,
+  required,
+  disabled,
+  testId,
+}: TextareaFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="textarea"
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+        {...(rows !== undefined && { rows })}
+      />
+    </Field>
+  );
+}
+
+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 function RangeField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  min,
+  max,
+  step,
+  required,
+  disabled,
+  testId,
+}: RangeFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind="range"
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        min={min}
+        max={max}
+        required={required}
+        disabled={disabled}
+        {...(step !== undefined && { step })}
+      />
+    </Field>
+  );
+}
+
+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 function FileField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  accept,
+  variant = "file",
+  entityType,
+  fieldName,
+  required,
+  disabled,
+  testId,
+}: FileFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field id={id} label={label} required={required} testId={testId}>
+      <Input
+        kind={variant}
+        id={id}
+        name={name}
+        value={value}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+        {...(accept !== undefined && { accept })}
+        {...(entityType !== undefined && { entityType })}
+        {...(fieldName !== undefined && { fieldName })}
+      />
+    </Field>
+  );
+}

package/src/widgets/index.ts

@@ -0,0 +1,59 @@
+// 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,
+  type AiTextAreaProps,
+  AiTextField,
+  type AiTextFieldProps,
+} from "./ai-text-field";
+export {
+  StatusBarChart,
+  type StatusBarEntry,
+  smoothPath,
+  TimeseriesChart,
+  type TimeseriesPoint,
+} from "./charts";
+export { CollapsibleSection } from "./collapsible-section";
+export { DetailList } from "./detail-list";
+export { Drawer, type DrawerProps } from "./drawer";
+export { FeedList, type FeedRow } from "./feed-list";
+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";
+export { InfinityList, type InfinityListProps } from "./infinity-list";
+export { ModeSwitch } from "./mode-switch";
+export { ProgressBar } from "./progress-bar";
+export { ProgressList, type ProgressListRow } from "./progress-list";
+export { QueryTable, type QueryTableColumn, type QueryTableProps } from "./query-table";
+export {
+  type ComparisonMetric,
+  ComparisonTable,
+  type ResultColumn,
+  ResultPanel,
+  ResultTable,
+} from "./result-panel";
+export { SectionCard } from "./section-card";
+export { MiniStat, Sparkline, StatCard, type StatDelta, type StatTone } from "./stat";
+export { EmptyState, ErrorState, LoadingState } from "./states";
+export { STATUS_TONE_TEXT, StatusBadge, type StatusTone } from "./status-badge";
+export { useDraft } from "./use-draft";

package/src/widgets/infinity-list.tsx

@@ -0,0 +1,112 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { useDispatcher, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import { EmptyState, ErrorState, LoadingState } from "./states";
+
+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;
+  readonly rowId: (row: TRow, index: number) => string;
+  readonly renderRow: (row: TRow) => ReactNode;
+  readonly emptyState?: ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+type State<TRow> =
+  | { readonly kind: "loading" }
+  | { readonly kind: "error"; readonly error: DispatcherError }
+  | { readonly kind: "ready"; readonly rows: readonly TRow[]; readonly cursor: string | null };
+
+/** 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<TData = unknown, TRow = Readonly<Record<string, unknown>>>({
+  query,
+  payload,
+  pageSize = 50,
+  rows,
+  nextCursor,
+  rowId,
+  renderRow,
+  emptyState,
+  className,
+  testId,
+}: InfinityListProps<TData, TRow>): ReactNode {
+  const dispatcher = useDispatcher();
+  const t = useTranslation();
+  const [state, setState] = useState<State<TRow>>({ kind: "loading" });
+  const sentinelRef = useRef<HTMLDivElement | null>(null);
+  const payloadKey = JSON.stringify(payload ?? {});
+
+  // rows/nextCursor are fresh closures on every caller render (inline
+  // arrow props). As useCallback deps that would recreate `load` every
+  // render → the mount effect below would refetch in a loop. Refs keep
+  // `load` stable while always reading the current selector.
+  const rowsRef = useRef(rows);
+  rowsRef.current = rows;
+  const nextCursorRef = useRef(nextCursor);
+  nextCursorRef.current = nextCursor;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
+  const load = useCallback(
+    async (cursor: string | null): Promise<void> => {
+      const res = await dispatcher.query<TData>(query, {
+        ...payload,
+        limit: pageSize,
+        ...(cursor !== null && { cursor }),
+      });
+      if (!res.isSuccess) {
+        setState({ kind: "error", error: res.error });
+        return;
+      }
+      const nextRows = rowsRef.current(res.data);
+      setState((prev) => ({
+        kind: "ready",
+        rows: cursor === null || prev.kind !== "ready" ? nextRows : [...prev.rows, ...nextRows],
+        cursor: nextCursorRef.current(res.data),
+      }));
+    },
+    [dispatcher, query, pageSize, payloadKey],
+  );
+
+  useEffect(() => {
+    setState({ kind: "loading" });
+    void load(null);
+  }, [load]);
+
+  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]);
+
+  if (state.kind === "loading") return <LoadingState rows={4} testId={testId} />;
+  if (state.kind === "error")
+    return <ErrorState error={state.error} onRetry={() => void load(null)} testId={testId} />;
+  if (state.rows.length === 0)
+    return <>{emptyState ?? <EmptyState title={t("kumiko.list.no-entries")} testId={testId} />}</>;
+
+  return (
+    <div data-testid={testId} className={className ?? "flex flex-col overflow-y-auto"}>
+      {state.rows.map((row, index) => (
+        <div key={rowId(row, index)}>{renderRow(row)}</div>
+      ))}
+      <div ref={sentinelRef} className="h-px" />
+    </div>
+  );
+}

package/src/widgets/mode-switch.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/** Segmented-Control für sich ausschließende Modi — die prominente
+ *  Alternative zum vergrabenen <select>. */
+export function ModeSwitch<T extends string>({
+  value,
+  options,
+  onChange,
+  testId,
+}: {
+  readonly value: T;
+  readonly options: readonly { readonly value: T; readonly label: string }[];
+  readonly onChange: (value: T) => void;
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: fieldset bringt Browser-Default-Chrome (Border/legend) mit, das für ein Button-Segmented-Control falsch ist
+    <div data-testid={testId} role="group" className="flex flex-wrap gap-1">
+      {options.map((o) => {
+        const active = o.value === value;
+        return (
+          <button
+            key={o.value}
+            type="button"
+            aria-pressed={active}
+            onClick={() => onChange(o.value)}
+            className={cn(
+              "rounded-md border px-3 py-1.5 text-sm transition-colors",
+              active
+                ? "border-transparent bg-secondary font-semibold text-secondary-foreground"
+                : "text-muted-foreground hover:bg-muted",
+            )}
+          >
+            {o.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/widgets/progress-bar.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/** Fortschrittsbalken, `value` 0..1 (wird geclampt). */
+export function ProgressBar({
+  value,
+  className,
+  testId,
+}: {
+  readonly value: number;
+  readonly className?: string;
+  readonly testId?: string;
+}): ReactNode {
+  const pct = Math.max(0, Math.min(1, value));
+  return (
+    <div
+      data-testid={testId}
+      role="progressbar"
+      aria-valuenow={Math.round(pct * 100)}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      className={cn("h-2 w-full overflow-hidden rounded-full bg-muted", className)}
+    >
+      <div className="h-full rounded-full bg-primary" style={{ width: `${pct * 100}%` }} />
+    </div>
+  );
+}

package/src/widgets/progress-list.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import { ProgressBar } from "./progress-bar";
+
+export type ProgressListRow = {
+  readonly id: string;
+  readonly label: string;
+  readonly value: string;
+  readonly fraction: number;
+};
+
+/** Liste aus Label/Wert-Kopfzeile + Fortschrittsbalken pro Eintrag (z.B.
+ *  Tilgungsfortschritt pro Kredit). */
+export function ProgressList({
+  rows,
+  emptyContent,
+  testId,
+}: {
+  readonly rows: readonly ProgressListRow[];
+  readonly emptyContent?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  if (rows.length === 0) {
+    return <div data-testid={testId}>{emptyContent}</div>;
+  }
+  return (
+    <ul data-testid={testId} className="flex max-h-64 flex-col gap-3 overflow-y-auto pr-1">
+      {rows.map((row) => (
+        <li key={row.id} className="flex flex-col gap-1">
+          <div className="flex items-baseline justify-between gap-2 text-sm">
+            <span className="font-medium">{row.label}</span>
+            <span className="tabular-nums text-muted-foreground">{row.value}</span>
+          </div>
+          <ProgressBar value={row.fraction} />
+        </li>
+      ))}
+    </ul>
+  );
+}