@cosmicdrift/kumiko-renderer-web 0.134.0 → 0.135.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.134.0",
+  "version": "0.135.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.134.0",
-    "@cosmicdrift/kumiko-headless": "0.134.0",
-    "@cosmicdrift/kumiko-renderer": "0.134.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.135.0",
+    "@cosmicdrift/kumiko-headless": "0.135.0",
+    "@cosmicdrift/kumiko-renderer": "0.135.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/index.ts

@@ -156,9 +156,11 @@ export {
 export { SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider } from "./ui/sidebar";
 export type {
   FeedRow,
+  NumberFieldProps,
   ProgressListRow,
   QueryTableColumn,
   QueryTableProps,
+  ResultColumn,
   StatDelta,
   StatTone,
   StatusBarEntry,
@@ -174,9 +176,14 @@ export {
   LoadingState,
   MiniStat,
   ModeSwitch,
+  MoneyField,
+  NumberField,
+  PercentField,
   ProgressBar,
   ProgressList,
   QueryTable,
+  ResultPanel,
+  ResultTable,
   SectionCard,
   Sparkline,
   STATUS_TONE_TEXT,
@@ -185,4 +192,5 @@ export {
   StatusBarChart,
   smoothPath,
   TimeseriesChart,
+  useDraft,
 } from "./widgets";

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

@@ -0,0 +1,103 @@
+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 { useDraft } from "../use-draft";
+
+describe("useDraft", () => {
+  test("field() liefert verdrahtete Props, onChange patcht den Draft", () => {
+    const { result } = renderHook(() => useDraft<{ sum: number | undefined }>({ sum: 100 }));
+    expect(result.current.field("sum")).toMatchObject({ id: "sum", name: "sum", value: 100 });
+    act(() => result.current.field("sum").onChange(250));
+    expect(result.current.draft.sum).toBe(250);
+  });
+
+  test("reset stellt die Defaults wieder her", () => {
+    const { result } = renderHook(() => useDraft<{ a: number | undefined }>({ a: 1 }));
+    act(() => result.current.patch({ a: 9 }));
+    expect(result.current.draft.a).toBe(9);
+    act(() => result.current.reset());
+    expect(result.current.draft.a).toBe(1);
+  });
+});
+
+describe("NumberField", () => {
+  test("rendert Label und meldet Zahl bei Eingabe", () => {
+    const onChange = mock();
+    render(<NumberField label="Summe" id="sum" name="sum" value={300} onChange={onChange} />);
+    expect(screen.getByText("Summe")).toBeTruthy();
+    fireEvent.change(screen.getByRole("spinbutton"), { target: { value: "42" } });
+    expect(onChange).toHaveBeenCalledWith(42);
+  });
+
+  test("leeres Feld meldet undefined", () => {
+    const onChange = mock();
+    render(<NumberField label="X" id="x" name="x" value={5} onChange={onChange} />);
+    fireEvent.change(screen.getByRole("spinbutton"), { target: { value: "" } });
+    expect(onChange).toHaveBeenCalledWith(undefined);
+  });
+
+  test("MoneyField/PercentField zeigen ihre Einheit", () => {
+    const noop = (): void => {};
+    const { rerender } = render(
+      <MoneyField label="Betrag" id="b" name="b" value={1} onChange={noop} />,
+    );
+    expect(screen.getByText("€")).toBeTruthy();
+    rerender(<PercentField label="Zins" id="z" name="z" value={1} onChange={noop} />);
+    expect(screen.getByText("%")).toBeTruthy();
+  });
+});
+
+describe("DetailList emphasize", () => {
+  test("emphasize hebt Label und Wert hervor", () => {
+    render(
+      <DetailList
+        testId="dl"
+        rows={[
+          { label: "Summe", value: "100" },
+          { label: "Effektiv", value: "3,1 %", emphasize: true },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Effektiv").className).toContain("font-semibold");
+    expect(screen.getByText("Summe").className).not.toContain("font-semibold");
+  });
+});
+
+describe("ResultPanel", () => {
+  test("empty zeigt den Platzhalter, keine Liste", () => {
+    render(<ResultPanel title="Ergebnis" empty emptyText="Werte eingeben" />);
+    expect(screen.getByText("Werte eingeben")).toBeTruthy();
+  });
+
+  test("gefüllt zeigt Kennzahlen und children", () => {
+    render(
+      <ResultPanel title="Ergebnis" rows={[{ label: "Rate", value: "890 €" }]}>
+        <span>extra</span>
+      </ResultPanel>,
+    );
+    expect(screen.getByText("Rate")).toBeTruthy();
+    expect(screen.getByText("extra")).toBeTruthy();
+  });
+});
+
+describe("ResultTable", () => {
+  test("rendert Header, Zeilen und rechtsbündige Zahlenspalte", () => {
+    render(
+      <ResultTable
+        testId="rt"
+        columns={[
+          { header: "Tranche", cell: (r: { name: string; sum: string }) => r.name },
+          { header: "Summe", align: "right", cell: (r) => r.sum },
+        ]}
+        rows={[{ name: "Bank", sum: "300.000 €" }]}
+        rowKey={(r) => r.name}
+      />,
+    );
+    expect(screen.getByText("Tranche")).toBeTruthy();
+    expect(screen.getByText("Bank")).toBeTruthy();
+    expect(screen.getByText("Summe").className).toContain("text-right");
+    expect(screen.getByText("300.000 €").className).toContain("tabular-nums");
+  });
+});

package/src/widgets/detail-list.tsx

@@ -1,12 +1,18 @@
 import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
 
 /** Read-only Schlüssel-Wert-Liste für Detail-Masken (Label links gedimmt,
- *  Wert rechts). Wert ist ReactNode → Badges/Chips möglich. */
+ *  Wert rechts). Wert ist ReactNode → Badges/Chips möglich. `emphasize` hebt
+ *  eine Zeile hervor (z.B. das Endergebnis in einem Rechner). */
 export function DetailList({
   rows,
   testId,
 }: {
-  readonly rows: readonly { readonly label: string; readonly value: ReactNode }[];
+  readonly rows: readonly {
+    readonly label: string;
+    readonly value: ReactNode;
+    readonly emphasize?: boolean;
+  }[];
   readonly testId?: string;
 }): ReactNode {
   return (
@@ -16,8 +22,17 @@ export function DetailList({
           key={row.label}
           className="grid grid-cols-1 gap-0.5 py-2.5 sm:grid-cols-[200px_1fr] sm:gap-4"
         >
-          <dt className="text-sm text-muted-foreground">{row.label}</dt>
-          <dd className="text-sm font-medium">{row.value}</dd>
+          <dt
+            className={cn(
+              "text-sm text-muted-foreground",
+              row.emphasize === true && "font-semibold text-foreground",
+            )}
+          >
+            {row.label}
+          </dt>
+          <dd className={cn("text-sm font-medium", row.emphasize === true && "font-semibold")}>
+            {row.value}
+          </dd>
         </div>
       ))}
     </dl>

package/src/widgets/form-fields.tsx

@@ -0,0 +1,66 @@
+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;
+  /** Einheit rechts neben dem Label (z.B. "€", "%"). */
+  readonly unit?: string;
+  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. */
+export function NumberField({
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  required,
+  disabled,
+  unit,
+  testId,
+}: NumberFieldProps): ReactNode {
+  const { Field, Input } = usePrimitives();
+  return (
+    <Field
+      id={id}
+      label={label}
+      required={required}
+      labelAppendix={
+        unit !== undefined ? (
+          <span className="text-xs text-muted-foreground">{unit}</span>
+        ) : undefined
+      }
+      testId={testId}
+    >
+      <Input
+        kind="number"
+        id={id}
+        name={name}
+        value={value ?? ""}
+        onChange={onChange}
+        required={required}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
+/** Euro-Betrag in ganzen Einheiten (kein Cent-Integer wie Input kind:"money").
+ *  Preset über NumberField mit "€"-Einheit. */
+export function MoneyField(props: Omit<NumberFieldProps, "unit">): ReactNode {
+  return <NumberField {...props} unit="€" />;
+}
+
+/** Prozentwert (Zins, Tilgung, Rendite). Preset über NumberField mit "%". */
+export function PercentField(props: Omit<NumberFieldProps, "unit">): ReactNode {
+  return <NumberField {...props} unit="%" />;
+}

package/src/widgets/index.ts

@@ -13,11 +13,14 @@ 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 { 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 { 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/result-panel.tsx

@@ -0,0 +1,101 @@
+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,
+  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;
+  }[];
+  readonly children?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  const { Banner } = usePrimitives();
+  return (
+    <SectionCard title={title} subtitle={subtitle} 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;
+}
+
+/** 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,
+}: {
+  readonly columns: readonly ResultColumn<Row>[];
+  readonly rows: readonly Row[];
+  readonly rowKey: (row: Row, index: number) => string;
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <div className="overflow-x-auto">
+      <table data-testid={testId} className="w-full text-sm">
+        <thead>
+          <tr className="border-b text-left text-muted-foreground">
+            {columns.map((col) => (
+              <th
+                key={col.header}
+                className={cn("py-1.5 font-medium", 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", col.align === "right" && "text-right tabular-nums")}
+                >
+                  {col.cell(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/widgets/use-draft.ts

@@ -0,0 +1,35 @@
+import { useCallback, useState } from "react";
+
+/** Formular-State für Rechner-Screens: ein Draft-Objekt + `patch` für
+ *  Teil-Updates + `field(name)` das die `{ id, name, value, onChange }`-Props
+ *  fertig für die Feld-Widgets (NumberField/MoneyField/PercentField) liefert.
+ *  Ersetzt das pro Screen wiederholte Draft-Interface + patch-Helper. */
+export function useDraft<T extends object>(
+  defaults: T,
+): {
+  readonly draft: T;
+  readonly patch: (changes: Partial<T>) => void;
+  readonly reset: () => void;
+  readonly field: <K extends keyof T>(
+    name: K,
+  ) => {
+    readonly id: string;
+    readonly name: string;
+    readonly value: T[K];
+    readonly onChange: (v: T[K]) => void;
+  };
+} {
+  const [draft, setDraft] = useState<T>(defaults);
+  const patch = useCallback((changes: Partial<T>) => setDraft((d) => ({ ...d, ...changes })), []);
+  const reset = useCallback(() => setDraft(defaults), [defaults]);
+  const field = useCallback(
+    <K extends keyof T>(name: K) => ({
+      id: String(name),
+      name: String(name),
+      value: draft[name],
+      onChange: (v: T[K]) => setDraft((d) => ({ ...d, [name]: v })),
+    }),
+    [draft],
+  );
+  return { draft, patch, reset, field };
+}