@cosmicdrift/kumiko-renderer-web 1.0.0 → 2.0.0

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/result-panel.tsx

@@ -0,0 +1,251 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { DetailList } from "./detail-list";
+import { SectionCard } from "./section-card";
+
+/** Ergebnis-Sektion eines Rechners: SectionCard mit Empty-Zustand (Banner)
+ *  oder Kennzahl-Liste (DetailList) + optionalen Extras (Tabelle, Hinweise).
+ *  Ersetzt die handgebauten `<dl>`/Banner-Blöcke in Custom-Screens. */
+export function ResultPanel({
+  title,
+  subtitle,
+  empty,
+  emptyText,
+  rows,
+  footer,
+  children,
+  testId,
+}: {
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly empty?: boolean;
+  readonly emptyText?: ReactNode;
+  readonly rows?: readonly {
+    readonly label: string;
+    readonly value: ReactNode;
+    readonly emphasize?: boolean;
+  }[];
+  /** Action-Slot am Karten-Fuß (z.B. „In Finanzierung übernehmen"). */
+  readonly footer?: ReactNode;
+  readonly children?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  const { Banner } = usePrimitives();
+  return (
+    <SectionCard title={title} subtitle={subtitle} footer={footer} testId={testId}>
+      {empty === true ? (
+        <Banner variant="info" padded>
+          {emptyText}
+        </Banner>
+      ) : (
+        <div className="flex flex-col gap-4">
+          {rows !== undefined && rows.length > 0 && <DetailList rows={rows} />}
+          {children}
+        </div>
+      )}
+    </SectionCard>
+  );
+}
+
+export interface ResultColumn<Row> {
+  readonly header: string;
+  readonly align?: "left" | "right";
+  readonly cell: (row: Row) => ReactNode;
+}
+
+export interface ResultTableFooterRow {
+  readonly label: string;
+  readonly value: ReactNode;
+  readonly emphasize?: boolean;
+}
+
+/** Statische, prop-getriebene Ergebnistabelle für berechnete Zeilen (Tranchen,
+ *  Szenarien). Nimmt dem Screen die `<table>`+tabular-nums-Ketten ab.
+ *  ponytail: bewusst die minimale Read-only-Tabelle — für Sort/Pager/Facets
+ *  stattdessen usePrimitives().DataTable bzw. QueryTable nutzen. */
+export function ResultTable<Row>({
+  columns,
+  rows,
+  rowKey,
+  testId,
+  className,
+  card,
+  footer,
+}: {
+  readonly columns: readonly ResultColumn<Row>[];
+  readonly rows: readonly Row[];
+  readonly rowKey: (row: Row, index: number) => string;
+  readonly testId?: string;
+  readonly className?: string;
+  /** Rahmen-Look wie die CRUD-Liste (DataTable): gerundeter Border-Container +
+   *  bg-muted-Header-Band. Default = bare (nur die Tabelle, ohne Container). */
+  readonly card?: boolean;
+  /** Summary rows (Subtotal/Tax/Total) rendered as real `<tr>`s in the same
+   *  `<table>` instead of a separate flex-div next to it — guarantees
+   *  column-alignment to the last (typically "Amount") column instead of
+   *  approximating it with an independent layout. */
+  readonly footer?: readonly ResultTableFooterRow[];
+}): ReactNode {
+  const table = (
+    <div className="overflow-x-auto">
+      <table data-testid={testId} className={cn("w-full text-sm", className)}>
+        <thead className={cn(card === true && "bg-muted")}>
+          <tr className="border-b text-left text-muted-foreground">
+            {columns.map((col) => (
+              <th
+                key={col.header}
+                className={cn(
+                  "py-1.5 font-medium",
+                  card === true && "px-3",
+                  col.align === "right" && "text-right",
+                )}
+              >
+                {col.header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, i) => (
+            <tr key={rowKey(row, i)} className="border-b last:border-0">
+              {columns.map((col) => (
+                <td
+                  key={col.header}
+                  className={cn(
+                    "py-1.5",
+                    card === true && "px-3",
+                    col.align === "right" && "text-right tabular-nums",
+                  )}
+                >
+                  {col.cell(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+          {footer?.map((row, i) => (
+            <tr
+              key={row.label}
+              className={cn(i === 0 && "border-t", row.emphasize === true && "font-semibold")}
+            >
+              <td
+                colSpan={columns.length > 1 ? Math.max(columns.length - 1, 1) : undefined}
+                className={cn(
+                  "py-1.5 text-muted-foreground",
+                  card === true && "px-3",
+                  row.emphasize === true && "text-foreground",
+                  columns.length === 1 && "flex items-center justify-between gap-4",
+                )}
+              >
+                {row.label}
+                {columns.length === 1 && (
+                  <span
+                    className={cn(
+                      "text-right tabular-nums",
+                      row.emphasize === true && "text-foreground",
+                    )}
+                  >
+                    {row.value}
+                  </span>
+                )}
+              </td>
+              {columns.length > 1 && (
+                <td className={cn("py-1.5 text-right tabular-nums", card === true && "px-3")}>
+                  {row.value}
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+  return card === true ? (
+    <div className="overflow-hidden rounded-lg border bg-card">{table}</div>
+  ) : (
+    table
+  );
+}
+
+export interface ComparisonMetric<Col> {
+  readonly label: string;
+  readonly value: (col: Col, index: number) => ReactNode;
+  /** Index der besten Spalte für diese Zeile (hervorgehoben); -1 = keine. */
+  readonly bestIndex?: (cols: readonly Col[]) => number;
+}
+
+/** Transponierte Vergleichstabelle: Zeile = Kennzahl, Spalte = Variante, je
+ *  Kennzahl optional die beste Spalte hervorgehoben. Für Szenario-/Angebots-
+ *  Vergleiche, wo ResultTable (Zeile=Datensatz) nicht passt. */
+export function ComparisonTable<Col>({
+  columns,
+  columnHeader,
+  columnKey,
+  metrics,
+  metricLabel,
+  testId,
+  className,
+  card,
+}: {
+  readonly columns: readonly Col[];
+  readonly columnHeader: (col: Col, index: number) => string;
+  readonly columnKey: (col: Col, index: number) => string;
+  readonly metrics: readonly ComparisonMetric<Col>[];
+  readonly metricLabel: string;
+  readonly testId?: string;
+  readonly className?: string;
+  /** Rahmen-Look wie die CRUD-Liste (DataTable): gerundeter Border-Container +
+   *  bg-muted-Header-Band. Default = bare. */
+  readonly card?: boolean;
+}): ReactNode {
+  const table = (
+    <div className="overflow-x-auto">
+      <table data-testid={testId} className={cn("w-full min-w-[24rem] text-sm", className)}>
+        <thead className={cn(card === true && "bg-muted")}>
+          <tr className="border-b text-left text-muted-foreground">
+            <th className={cn("py-1.5 font-medium", card === true && "px-3")}>{metricLabel}</th>
+            {columns.map((col, i) => (
+              <th
+                key={columnKey(col, i)}
+                className={cn("py-1.5 text-right font-medium", card === true && "px-3")}
+              >
+                {columnHeader(col, i)}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {metrics.map((metric) => {
+            const best = metric.bestIndex !== undefined ? metric.bestIndex(columns) : -1;
+            return (
+              <tr key={metric.label} className="border-b last:border-0">
+                <td className={cn("py-1.5 text-muted-foreground", card === true && "px-3")}>
+                  {metric.label}
+                </td>
+                {columns.map((col, i) => (
+                  <td
+                    key={columnKey(col, i)}
+                    className={cn("py-1.5 text-right tabular-nums", card === true && "px-3")}
+                  >
+                    {i === best ? (
+                      <span className="inline-block rounded bg-primary/10 px-2 py-0.5 font-semibold text-primary">
+                        {metric.value(col, i)}
+                      </span>
+                    ) : (
+                      metric.value(col, i)
+                    )}
+                  </td>
+                ))}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+  return card === true ? (
+    <div className="overflow-hidden rounded-lg border bg-card">{table}</div>
+  ) : (
+    table
+  );
+}

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>
+  );
+}