@cosmicdrift/kumiko-renderer-web 0.130.2 → 0.132.0

package/src/widgets/mode-switch.tsx

@@ -0,0 +1,40 @@
+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 (
+    <div data-testid={testId} 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/query-table.tsx

@@ -0,0 +1,103 @@
+import type { ListRowViewModel } from "@cosmicdrift/kumiko-headless";
+import {
+  type DataTableProps,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { EmptyState, ErrorState, LoadingState } from "./states";
+
+// Query-backed Tabelle für Custom-Screens: ein Widget statt der
+// handgebauten useState+fetch+<table>-Trios. Deklarativ: Query-Type +
+// Spalten rein, Loading/Error/Empty/Render übernimmt das Widget über
+// das DataTable-Primitive (gleiche Optik wie entityList-Screens).
+//
+// ponytail: Zellen rendern über die DataTable-Typ-Formatierung (text/
+// number/money/…), kein render-Prop pro Spalte — für Custom-Zellen die
+// entityList-columnRenderers nutzen oder das Widget erweitern, wenn eine
+// Migration es wirklich braucht.
+
+export type QueryTableColumn = {
+  readonly field: string;
+  /** Translated Header-Label (i18n-Key auflösen liegt beim Caller). */
+  readonly label: string;
+  /** Field-Type für die Zell-Formatierung. Default "text". */
+  readonly type?: string;
+};
+
+export type QueryTableProps<TData = unknown> = {
+  /** Dispatcher-Query-Type (`<feature>:query:<entity>:<verb>`). */
+  readonly query: string;
+  readonly payload?: unknown;
+  /** SSE-Invalidierung — refetcht bei Entity-Events (useQuery live-mode). */
+  readonly live?: boolean;
+  readonly columns: readonly QueryTableColumn[];
+  /** Rows aus dem Query-Result ziehen. Default: Result selbst als Array. */
+  readonly rows?: (data: TData) => readonly Readonly<Record<string, unknown>>[];
+  /** Row-Id für Keys/Row-Click. Default: `row.id`, sonst der Index. */
+  readonly rowId?: (row: Readonly<Record<string, unknown>>, index: number) => string;
+  readonly onRowClick?: DataTableProps["onRowClick"];
+  readonly rowActions?: DataTableProps["rowActions"];
+  /** Empty-Inhalt — Default ist der Standard-Empty-State der Listen. */
+  readonly emptyState?: ReactNode;
+  readonly toolbarTitle?: ReactNode;
+  readonly toolbarEnd?: ReactNode;
+  readonly testId?: string;
+};
+
+function defaultRows(data: unknown): readonly Readonly<Record<string, unknown>>[] {
+  return Array.isArray(data) ? (data as readonly Readonly<Record<string, unknown>>[]) : [];
+}
+
+export function QueryTable<TData = unknown>({
+  query,
+  payload,
+  live = false,
+  columns,
+  rows,
+  rowId,
+  onRowClick,
+  rowActions,
+  emptyState,
+  toolbarTitle,
+  toolbarEnd,
+  testId,
+}: QueryTableProps<TData>): ReactNode {
+  const { DataTable } = usePrimitives();
+  const t = useTranslation();
+  const { data, error, loading, refetch } = useQuery<TData>(query, payload ?? {}, { live });
+
+  if (loading && data === null) return <LoadingState rows={4} testId={testId} />;
+  if (error !== null)
+    return <ErrorState error={error} onRetry={() => void refetch()} testId={testId} />;
+
+  const rawRows = rows !== undefined ? rows(data as TData) : defaultRows(data);
+  const vmRows: readonly ListRowViewModel[] = rawRows.map((row, index) => ({
+    id:
+      rowId !== undefined
+        ? rowId(row, index)
+        : typeof row["id"] === "string"
+          ? row["id"]
+          : String(index),
+    values: row,
+  }));
+
+  return (
+    <DataTable
+      columns={columns.map((c) => ({
+        field: c.field,
+        label: c.label,
+        type: c.type ?? "text",
+        sortable: false,
+      }))}
+      rows={vmRows}
+      onRowClick={onRowClick}
+      rowActions={rowActions}
+      emptyState={emptyState ?? <EmptyState title={t("kumiko.list.no-entries")} />}
+      toolbarTitle={toolbarTitle}
+      toolbarEnd={toolbarEnd}
+      testId={testId}
+    />
+  );
+}

package/src/widgets/section-card.tsx

@@ -0,0 +1,30 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+
+/** Sektion mit Titel + optionalem Action-Slot (Range-Umschalter, Filter) —
+ *  ersetzt die wiederholten `<section className={CARD}>…<h2>`-Blöcke in
+ *  Custom-Screens. Dünner Wrapper über das Card-Primitive. */
+export function SectionCard({
+  title,
+  subtitle,
+  action,
+  footer,
+  children,
+  testId,
+}: {
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly action?: ReactNode;
+  readonly footer?: ReactNode;
+  readonly children: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  const { Card } = usePrimitives();
+  return (
+    <Card slots={{ title, subtitle, headerActions: action, footer }} testId={testId}>
+      {/* h-full füllt den Card-Body (grow) → ein Kind mit mt-auto kann sich unten
+          ankern, damit Card-Reihen über mehrere SectionCards fluchten. */}
+      <div className="flex h-full flex-col gap-4">{children}</div>
+    </Card>
+  );
+}

package/src/widgets/stat.tsx

@@ -0,0 +1,181 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// KPI-Kacheln. `tone` steuert Value-/Chip-Farbe semantisch (default |
+// positive | warn), `accentColor` färbt NUR den Icon-Chip mit einer
+// App-semantischen Farbe (z.B. Finanz-Rollen) — Value/Delta/Sparkline
+// bleiben an `tone`.
+
+export type StatTone = "default" | "positive" | "warn";
+
+const TONE_CHIP: Record<StatTone, string> = {
+  default: "bg-muted text-foreground",
+  positive: "bg-primary/10 text-primary",
+  warn: "bg-destructive/10 text-destructive",
+};
+
+const TONE_VALUE: Record<StatTone, string> = {
+  default: "text-foreground",
+  positive: "text-primary",
+  warn: "text-destructive",
+};
+
+export type StatDelta = {
+  readonly value: string;
+  readonly direction: "up" | "down";
+  readonly tone?: StatTone;
+};
+
+// Inline-SVG-Sparkline (kein Chart-Dep für eine 28px-Kurve): Linie +
+// schwacher Flächen-Verlauf, Farbe via currentColor (Caller setzt text-tone).
+export function Sparkline({
+  points,
+  className,
+}: {
+  readonly points: readonly number[];
+  readonly className?: string;
+}): ReactNode {
+  if (points.length < 2) return null;
+  const w = 100;
+  const h = 28;
+  const min = Math.min(...points);
+  const max = Math.max(...points);
+  const span = max - min || 1;
+  const line = points
+    .map((p, i) => {
+      const x = (i / (points.length - 1)) * w;
+      const y = h - ((p - min) / span) * h;
+      return `${i === 0 ? "M" : "L"}${x.toFixed(1)},${y.toFixed(1)}`;
+    })
+    .join(" ");
+  return (
+    <svg
+      viewBox={`0 0 ${w} ${h}`}
+      preserveAspectRatio="none"
+      className={className ?? "h-7 w-full"}
+      aria-hidden="true"
+    >
+      <path d={`${line} L${w},${h} L0,${h} Z`} fill="currentColor" fillOpacity={0.12} />
+      <path
+        d={line}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}
+
+/** Icon-tragende Kennzahl-Kachel mit optionalem Delta-Chip, Trend-Zeile
+ *  und Sparkline. `icon` ist ein fertiger Knoten (App liefert ihr SVG). */
+export function StatCard({
+  icon,
+  label,
+  value,
+  sub,
+  tone = "default",
+  accentColor,
+  delta,
+  trend,
+  spark,
+  testId,
+}: {
+  readonly icon?: ReactNode;
+  readonly label: string;
+  readonly value: string;
+  readonly sub?: string;
+  readonly tone?: StatTone;
+  readonly accentColor?: string;
+  readonly delta?: StatDelta;
+  readonly trend?: string;
+  readonly spark?: readonly number[];
+  readonly testId?: string;
+}): ReactNode {
+  const { Card } = usePrimitives();
+  return (
+    <Card options={{ padded: false }} className="p-4" testId={testId}>
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2 text-muted-foreground">
+          {icon !== undefined && (
+            <span
+              className={cn(
+                "flex size-7 items-center justify-center rounded-lg",
+                accentColor === undefined && TONE_CHIP[tone],
+              )}
+              style={
+                accentColor === undefined
+                  ? undefined
+                  : {
+                      color: accentColor,
+                      backgroundColor: `color-mix(in srgb, ${accentColor} 12%, transparent)`,
+                    }
+              }
+            >
+              {icon}
+            </span>
+          )}
+          <span className="text-xs font-medium">{label}</span>
+        </div>
+        {delta !== undefined && (
+          <span
+            className={cn(
+              "inline-flex items-center gap-0.5 rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums",
+              TONE_CHIP[delta.tone ?? tone],
+            )}
+          >
+            {delta.direction === "up" ? "↑" : "↓"}
+            {delta.value}
+          </span>
+        )}
+      </div>
+      <div className="mt-2 text-xl font-semibold tabular-nums text-foreground">{value}</div>
+      {sub !== undefined && <div className="mt-0.5 text-xs text-muted-foreground">{sub}</div>}
+      {trend !== undefined && (
+        <div className="mt-0.5 text-xs font-medium text-foreground/80">{trend}</div>
+      )}
+      {spark !== undefined && (
+        <Sparkline points={spark} className={cn("mt-2 h-7 w-full", TONE_VALUE[tone])} />
+      )}
+    </Card>
+  );
+}
+
+/** Kompakte Kennzahl-Kachel (ohne Icon) — für dichte KPI-Raster.
+ *  StatCard ist die icon-tragende Variante. */
+export function MiniStat({
+  label,
+  value,
+  tone = "default",
+  emphasize = false,
+  testId,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly tone?: StatTone;
+  readonly emphasize?: boolean;
+  readonly testId?: string;
+}): ReactNode {
+  const { Card } = usePrimitives();
+  return (
+    <Card
+      options={{ padded: false }}
+      className={cn("p-3", emphasize && "ring-1 ring-primary/30")}
+      testId={testId}
+    >
+      <div className="text-xs text-muted-foreground">{label}</div>
+      <div
+        className={cn(
+          "mt-0.5 font-semibold tabular-nums",
+          TONE_VALUE[tone],
+          emphasize ? "text-lg" : "text-sm",
+        )}
+      >
+        {value}
+      </div>
+    </Card>
+  );
+}

package/src/widgets/states.tsx

@@ -0,0 +1,89 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { dispatcherErrorText, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Skeleton } from "../ui/skeleton";
+
+/** Leerer-Zustand mit optionalem Icon + CTA — die dashed-Box-Optik der
+ *  entityList-Empty-States, als Standalone-Widget für Custom-Screens. */
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  testId,
+}: {
+  readonly icon?: ReactNode;
+  readonly title: string;
+  readonly description?: string;
+  readonly action?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <div
+      data-testid={testId}
+      className="flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed px-6 py-10 text-center"
+    >
+      {icon !== undefined && <div className="text-muted-foreground">{icon}</div>}
+      <div className="text-sm font-medium">{title}</div>
+      {description !== undefined && (
+        <div className="text-sm text-muted-foreground">{description}</div>
+      )}
+      {action !== undefined && <div className="mt-2">{action}</div>}
+    </div>
+  );
+}
+
+/** Lade-Zustand: Skeleton-Zeilen in Card-Optik. `rows` steuert die Höhe. */
+export function LoadingState({
+  rows = 3,
+  className,
+  testId,
+}: {
+  readonly rows?: number;
+  readonly className?: string;
+  readonly testId?: string;
+}): ReactNode {
+  const t = useTranslation();
+  return (
+    <output
+      data-testid={testId}
+      aria-label={t("kumiko.widget.loading")}
+      className={cn("flex w-full flex-col gap-2", className)}
+    >
+      {Array.from({ length: rows }, (_, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: statische Skeleton-Liste, Index ist stabil
+        <Skeleton key={i} className="h-9 w-full" />
+      ))}
+    </output>
+  );
+}
+
+/** Fehler-Zustand auf Basis des Banner-Primitives, mit Retry-Button. */
+export function ErrorState({
+  error,
+  onRetry,
+  testId,
+}: {
+  readonly error: DispatcherError;
+  readonly onRetry?: () => void;
+  readonly testId?: string;
+}): ReactNode {
+  const { Banner, Button } = usePrimitives();
+  const t = useTranslation();
+  return (
+    <Banner
+      variant="error"
+      testId={testId}
+      actions={
+        onRetry !== undefined ? (
+          <Button variant="secondary" onClick={onRetry}>
+            {t("kumiko.actions.reload")}
+          </Button>
+        ) : undefined
+      }
+    >
+      {t("kumiko.widget.error.title")} {dispatcherErrorText(error, t)}
+    </Banner>
+  );
+}

package/src/widgets/status-badge.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Semantische Status-Tones — eine Farb-Familie für Component-Status,
+// Incident-Status, Severity, Job-Zustände. Farben kommen aus den
+// --color-status-* Theme-Tokens (styles.css), Apps überschreiben zentral.
+export type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
+
+export const STATUS_TONE_TEXT: Record<StatusTone, string> = {
+  ok: "text-status-ok",
+  warn: "text-status-warn",
+  bad: "text-status-bad",
+  critical: "text-status-critical",
+  muted: "text-muted-foreground",
+};
+
+const TONE_PILL: Record<StatusTone, string> = {
+  ok: "bg-status-ok/10 text-status-ok",
+  warn: "bg-status-warn/10 text-status-warn",
+  bad: "bg-status-bad/10 text-status-bad",
+  critical: "bg-status-critical/15 text-status-critical",
+  muted: "bg-muted text-muted-foreground",
+};
+
+/** Pill-Badge für Status-Werte. Caller mappt Domain-Werte → Tone
+ *  (z.B. operational→ok, investigating→warn) und liefert das
+ *  translated Label als children. */
+export function StatusBadge({
+  tone,
+  children,
+  className,
+  testId,
+}: {
+  readonly tone: StatusTone;
+  readonly children: ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <span
+      data-testid={testId}
+      className={cn(
+        "inline-block rounded-xl px-2.5 py-1 text-xs font-semibold",
+        TONE_PILL[tone],
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}