@cosmicdrift/kumiko-renderer-web 0.136.1 → 0.138.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.136.1",
+  "version": "0.138.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.136.1",
-    "@cosmicdrift/kumiko-headless": "0.136.1",
-    "@cosmicdrift/kumiko-renderer": "0.136.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.138.0",
+    "@cosmicdrift/kumiko-headless": "0.138.0",
+    "@cosmicdrift/kumiko-renderer": "0.138.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/__tests__/dashboard-screen.test.tsx

@@ -110,6 +110,8 @@ const richScreen: DashboardScreenDefinition = {
       deltaField: "delta",
       deltaDirectionField: "deltaDirection",
       deltaToneField: "deltaTone",
+      icon: { react: { __component: "rich-dashboard-kpi-icon" } },
+      accentColor: "#123456",
     },
     {
       kind: "stat-group",
@@ -282,6 +284,50 @@ describe("KumikoScreen dashboard — neue Panel-Kinds", () => {
     expect(screen.getByText("↓23 %")).toBeTruthy();
   });
 
+  test("stat-Panel: registriertes Icon rendert, unregistriertes rendert nichts (kein Crash)", async () => {
+    function KpiIcon(): ReactNode {
+      return <svg data-testid="kpi-icon" />;
+    }
+    const dispatcher = createMockDispatcher({
+      query: (async (type: string) => {
+        if (type === "widgets:query:metrics:kpi") {
+          return { isSuccess: true, data: { value: "92.753 €" } };
+        }
+        return { isSuccess: true, data: {} };
+      }) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <ExtensionSectionsProvider value={{ "rich-dashboard-kpi-icon": KpiIcon }}>
+          <DashboardBodyProvider value={WebDashboardBody}>
+            <KumikoScreen schema={richSchema} qn="widgets:screen:rich" />
+          </DashboardBodyProvider>
+        </ExtensionSectionsProvider>
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.getByTestId("kpi-icon")).toBeTruthy());
+  });
+
+  test("stat-Panel: unregistriertes Icon rendert nichts, wirft nicht", async () => {
+    const dispatcher = createMockDispatcher({
+      query: (async (type: string) => {
+        if (type === "widgets:query:metrics:kpi") {
+          return { isSuccess: true, data: { value: "92.753 €" } };
+        }
+        return { isSuccess: true, data: {} };
+      }) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <DashboardBodyProvider value={WebDashboardBody}>
+          <KumikoScreen schema={richSchema} qn="widgets:screen:rich" />
+        </DashboardBodyProvider>
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("92.753 €")).toBeTruthy());
+    expect(screen.queryByTestId("kpi-icon")).toBeNull();
+  });
+
   test("stat-Panel: fehlende deltaDirection unterdrückt den Chip (kein Crash)", async () => {
     const dispatcher = createMockDispatcher({
       query: (async (type: string) => {

package/src/app/dashboard-body.tsx

@@ -10,6 +10,9 @@
 //                   deltaField/deltaDirectionField(+deltaToneField) sind
 //                   optional — nur wenn BEIDE Felder gesetzt sind UND geliefert
 //                   werden, zeigt die Kachel einen Delta-Chip ("↓ 23 %").
+//                   icon/accentColor sind statisch am Panel (keine Query-
+//                   Felder) — icon über extensionSectionComponents wie bei
+//                   custom-Panels, accentColor ein roher CSS-Farbwert.
 //   stat-group    → mehrere stat-Panels unter einem Sektions-Titel, jedes
 //                   Kind bleibt eine eigenständige Query.
 //   chart         → { points: { atMs, value | null }[], windowStartMs,
@@ -58,13 +61,41 @@ const STAT_TONES: ReadonlySet<string> = new Set(["default", "positive", "warn"])
 const WIDE_PANEL = "sm:col-span-2 lg:col-span-4";
 const HALF_PANEL = "sm:col-span-2 lg:col-span-2";
 
+function StatPanelIcon({
+  panel,
+  screenId,
+  filterParams,
+}: {
+  readonly panel: DashboardStatPanel;
+  readonly screenId: string;
+  readonly filterParams: Readonly<Record<string, unknown>>;
+}): ReactNode {
+  const name = panel.icon !== undefined ? extensionSectionName(panel.icon) : undefined;
+  const Icon = useExtensionSectionComponent(name);
+  useEffect(() => {
+    if (panel.icon !== undefined && name !== undefined && Icon === undefined) {
+      // biome-ignore lint/suspicious/noConsole: dev-warning für Setup-Fehler
+      console.warn(
+        `[kumiko] Dashboard stat-panel "${panel.id}" on screen "${screenId}" references icon ` +
+          `"${name}", which is not registered in clientFeatures.extensionSectionComponents.`,
+      );
+    }
+  }, [panel.icon, panel.id, name, Icon, screenId]);
+  if (Icon === undefined) return null;
+  return (
+    <Icon entityName={screenId} entityId={null} screenId={screenId} filterParams={filterParams} />
+  );
+}
+
 function StatPanelBody({
   panel,
   label,
+  screenId,
   filterParams,
 }: {
   readonly panel: DashboardStatPanel;
   readonly label: string;
+  readonly screenId: string;
   readonly filterParams: Readonly<Record<string, unknown>>;
 }): ReactNode {
   const { data, error, loading, refetch } = useQuery<Readonly<Record<string, unknown>>>(
@@ -82,9 +113,15 @@ function StatPanelBody({
   const delta = readDelta(panel, record);
   return (
     <StatCard
+      icon={
+        panel.icon !== undefined ? (
+          <StatPanelIcon panel={panel} screenId={screenId} filterParams={filterParams} />
+        ) : undefined
+      }
       label={label}
       value={String(record[panel.valueField] ?? "—")}
       tone={tone}
+      accentColor={panel.accentColor}
       {...(sub !== undefined && sub !== null && { sub: String(sub) })}
       {...(delta !== undefined && { delta })}
       testId={`dashboard-panel-${panel.id}`}
@@ -110,10 +147,12 @@ function readDelta(
 function StatGroupPanelBody({
   panel,
   label,
+  screenId,
   filterParams,
 }: {
   readonly panel: DashboardStatGroupPanel;
   readonly label: string;
+  readonly screenId: string;
   readonly filterParams: Readonly<Record<string, unknown>>;
 }): ReactNode {
   const t = useTranslation();
@@ -125,6 +164,7 @@ function StatGroupPanelBody({
             key={stat.id}
             panel={stat}
             label={t(stat.label)}
+            screenId={screenId}
             filterParams={filterParams}
           />
         ))}
@@ -365,9 +405,18 @@ function PanelBody({
   readonly filterParams: Readonly<Record<string, unknown>>;
 }): ReactNode {
   if (panel.kind === "stat")
-    return <StatPanelBody panel={panel} label={label} filterParams={filterParams} />;
+    return (
+      <StatPanelBody panel={panel} label={label} screenId={screenId} filterParams={filterParams} />
+    );
   if (panel.kind === "stat-group") {
-    return <StatGroupPanelBody panel={panel} label={label} filterParams={filterParams} />;
+    return (
+      <StatGroupPanelBody
+        panel={panel}
+        label={label}
+        screenId={screenId}
+        filterParams={filterParams}
+      />
+    );
   }
   if (panel.kind === "chart")
     return <ChartPanelBody panel={panel} label={label} filterParams={filterParams} />;

package/src/index.ts

@@ -155,20 +155,29 @@ export {
 } from "./tokens";
 export { SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider } from "./ui/sidebar";
 export type {
+  BooleanFieldProps,
+  ComparisonMetric,
+  DateFieldProps,
   FeedRow,
   NumberFieldProps,
   ProgressListRow,
   QueryTableColumn,
   QueryTableProps,
   ResultColumn,
+  SelectFieldProps,
   StatDelta,
   StatTone,
   StatusBarEntry,
   StatusTone,
+  TextareaFieldProps,
+  TextFieldProps,
   TimeseriesPoint,
 } from "./widgets";
 export {
+  BooleanField,
   CollapsibleSection,
+  ComparisonTable,
+  DateField,
   DetailList,
   EmptyState,
   ErrorState,
@@ -185,12 +194,15 @@ export {
   ResultPanel,
   ResultTable,
   SectionCard,
+  SelectField,
   Sparkline,
   STATUS_TONE_TEXT,
   StatCard,
   StatusBadge,
   StatusBarChart,
   smoothPath,
+  TextareaField,
+  TextField,
   TimeseriesChart,
   useDraft,
 } from "./widgets";

package/src/widgets/__tests__/form-kit.test.tsx

@@ -1,8 +1,17 @@
 import { describe, expect, mock, test } from "bun:test";
 import { act, fireEvent, render, renderHook, screen } from "../../__tests__/test-utils";
 import { DetailList } from "../detail-list";
-import { MoneyField, NumberField, PercentField } from "../form-fields";
-import { ResultPanel, ResultTable } from "../result-panel";
+import {
+  BooleanField,
+  DateField,
+  MoneyField,
+  NumberField,
+  PercentField,
+  SelectField,
+  TextareaField,
+  TextField,
+} from "../form-fields";
+import { ComparisonTable, ResultPanel, ResultTable } from "../result-panel";
 import { useDraft } from "../use-draft";
 
 describe("useDraft", () => {
@@ -103,3 +112,105 @@ describe("ResultTable", () => {
     expect(screen.getByText("300.000 €").className).toContain("tabular-nums");
   });
 });
+
+describe("Feld-Widgets (Select/Date/Text/Boolean/Textarea)", () => {
+  const noopStr = (): void => {};
+
+  test("SelectField rendert Label und den aktuell gewählten Wert", () => {
+    render(
+      <SelectField
+        label="Land"
+        id="l"
+        name="l"
+        value="NW"
+        onChange={noopStr}
+        options={[
+          { value: "NW", label: "Nordrhein-Westfalen" },
+          { value: "BY", label: "Bayern" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Land")).toBeTruthy();
+    expect(screen.getByText("Nordrhein-Westfalen")).toBeTruthy();
+  });
+
+  test("TextField meldet Eingabe", () => {
+    const onChange = mock();
+    render(<TextField label="Name" id="n" name="n" value="A" onChange={onChange} />);
+    fireEvent.change(screen.getByRole("textbox"), { target: { value: "Neu" } });
+    expect(onChange).toHaveBeenCalledWith("Neu");
+  });
+
+  test("DateField rendert mit Wert", () => {
+    render(
+      <DateField
+        label="Datum"
+        id="d"
+        name="d"
+        value="2026-07-10"
+        onChange={noopStr}
+        max="2030-01-01"
+      />,
+    );
+    expect(screen.getByText("Datum")).toBeTruthy();
+  });
+
+  test("BooleanField meldet Umschalten", () => {
+    const onChange = mock();
+    render(<BooleanField label="Aktiv" id="b" name="b" value={false} onChange={onChange} />);
+    fireEvent.click(screen.getByRole("checkbox"));
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
+  test("TextareaField meldet Eingabe", () => {
+    const onChange = mock();
+    render(<TextareaField label="Notiz" id="t" name="t" value="" onChange={onChange} rows={3} />);
+    fireEvent.change(screen.getByRole("textbox"), { target: { value: "Text" } });
+    expect(onChange).toHaveBeenCalledWith("Text");
+  });
+});
+
+describe("ResultPanel footer", () => {
+  test("rendert den footer-Slot", () => {
+    render(
+      <ResultPanel
+        title="R"
+        rows={[{ label: "X", value: "1" }]}
+        footer={<button type="button">Los</button>}
+      >
+        <span>body</span>
+      </ResultPanel>,
+    );
+    expect(screen.getByRole("button", { name: "Los" })).toBeTruthy();
+  });
+});
+
+describe("ComparisonTable", () => {
+  test("transponierte Matrix mit Best-Highlight je Kennzahl", () => {
+    const cols = [
+      { name: "A", rate: 900 },
+      { name: "B", rate: 850 },
+    ];
+    render(
+      <ComparisonTable
+        testId="cmp"
+        columns={cols}
+        columnHeader={(c) => c.name}
+        columnKey={(c) => c.name}
+        metricLabel="Kennzahl"
+        metrics={[
+          {
+            label: "Rate",
+            value: (c: { name: string; rate: number }) => `${c.rate} €`,
+            bestIndex: (cs) => ((cs[0]?.rate ?? 0) <= (cs[1]?.rate ?? 0) ? 0 : 1),
+          },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Kennzahl")).toBeTruthy();
+    expect(screen.getByText("A")).toBeTruthy();
+    // B (850) ist günstiger → hervorgehoben (font-semibold text-primary span)
+    expect(screen.getByText("850 €").className).toContain("text-primary");
+    expect(screen.getByText("900 €").className).not.toContain("text-primary");
+  });
+});

package/src/widgets/form-fields.tsx

@@ -52,3 +52,192 @@ export function MoneyField(props: NumberFieldProps): ReactNode {
 export function PercentField(props: NumberFieldProps): ReactNode {
   return <NumberField {...props} />;
 }
+
+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 | undefined) => 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={onChange}
+        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>
+  );
+}

package/src/widgets/index.ts

@@ -13,12 +13,33 @@ export {
 export { CollapsibleSection } from "./collapsible-section";
 export { DetailList } from "./detail-list";
 export { FeedList, type FeedRow } from "./feed-list";
-export { MoneyField, NumberField, type NumberFieldProps, PercentField } from "./form-fields";
+export {
+  BooleanField,
+  type BooleanFieldProps,
+  DateField,
+  type DateFieldProps,
+  MoneyField,
+  NumberField,
+  type NumberFieldProps,
+  PercentField,
+  SelectField,
+  type SelectFieldProps,
+  TextareaField,
+  type TextareaFieldProps,
+  TextField,
+  type TextFieldProps,
+} from "./form-fields";
 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 ResultColumn, ResultPanel, ResultTable } from "./result-panel";
+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";

package/src/widgets/result-panel.tsx

@@ -13,6 +13,7 @@ export function ResultPanel({
   empty,
   emptyText,
   rows,
+  footer,
   children,
   testId,
 }: {
@@ -25,12 +26,14 @@ export function ResultPanel({
     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} testId={testId}>
+    <SectionCard title={title} subtitle={subtitle} footer={footer} testId={testId}>
       {empty === true ? (
         <Banner variant="info" padded>
           {emptyText}
@@ -99,3 +102,67 @@ export function ResultTable<Row>({
     </div>
   );
 }
+
+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,
+}: {
+  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;
+}): ReactNode {
+  return (
+    <div className="overflow-x-auto">
+      <table data-testid={testId} className="w-full min-w-[24rem] text-sm">
+        <thead>
+          <tr className="border-b text-left text-muted-foreground">
+            <th className="py-1.5 font-medium">{metricLabel}</th>
+            {columns.map((col, i) => (
+              <th key={columnKey(col, i)} className="py-1.5 text-right font-medium">
+                {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="py-1.5 text-muted-foreground">{metric.label}</td>
+                {columns.map((col, i) => (
+                  <td key={columnKey(col, i)} className="py-1.5 text-right tabular-nums">
+                    {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>
+  );
+}