@cosmicdrift/kumiko-renderer 0.64.0 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.57.2",
-    "@cosmicdrift/kumiko-headless": "0.57.2",
+    "@cosmicdrift/kumiko-framework": "0.66.0",
+    "@cosmicdrift/kumiko-headless": "0.66.0",
     "react": "^19.2.6"
   },
   "devDependencies": {

package/src/__tests__/use-list-url-state.test.tsx

@@ -145,4 +145,57 @@ describe("useListUrlState", () => {
     const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
     expect(result.current.page).toBe(1);
   });
+
+  test("liest Faceted-Filter aus .f.<field>-Keys (comma-split), namespaced", () => {
+    const nav = makeNav({
+      "orders.f.status": "draft,published",
+      "orders.f.active": "true",
+      "incidents.f.status": "open", // andere Liste → ignoriert
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.filters).toEqual({
+      status: ["draft", "published"],
+      active: ["true"],
+    });
+  });
+
+  test("setFilter schreibt comma-joined Werte + resettet page", () => {
+    const nav = makeNav({ "orders.page": "4" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setFilter("status", ["draft", "review"]);
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.f.status": "draft,review",
+      "orders.page": null,
+    });
+  });
+
+  test("setFilter mit leerem Array löscht den Facet-Key", () => {
+    const nav = makeNav({ "orders.f.status": "draft" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setFilter("status", []);
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.f.status": null,
+      "orders.page": null,
+    });
+  });
+
+  test("clearFilters löscht alle aktiven .f.<field>-Keys", () => {
+    const nav = makeNav({
+      "orders.f.status": "draft",
+      "orders.f.active": "true",
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.clearFilters();
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.page": null,
+      "orders.f.status": null,
+      "orders.f.active": null,
+    });
+  });
 });

package/src/app/kumiko-screen.tsx

@@ -20,6 +20,7 @@ import type {
   SubmitResult,
   Translate,
 } from "@cosmicdrift/kumiko-headless";
+import { fieldLabelKey } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { RenderEdit } from "../components/render-edit";
 import { RenderList, type ToolbarActionButton } from "../components/render-list";
@@ -27,7 +28,7 @@ import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-cont
 import { useListUrlState } from "../hooks/use-list-url-state";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
-import { type DataTableRowAction, usePrimitives } from "../primitives";
+import { type DataTableFacet, type DataTableRowAction, usePrimitives } from "../primitives";
 import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./action-form-shim";
 import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config-edit-shim";
 import { useCustomScreenComponent } from "./custom-screens";
@@ -327,6 +328,7 @@ function EntityEditCreateBody({
       writeCommand={writeCommand}
       onSubmit={handleSubmitted}
       onCancel={navigateToList}
+      {...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel })}
       {...(translate !== undefined && { translate })}
     />
   );
@@ -485,6 +487,7 @@ function EntityEditUpdateForm({
       {...(screen.allowDelete !== false && { onDelete: handleDelete })}
       onCancel={navigateToList}
       onReload={() => void onReload()}
+      {...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel })}
       {...(translate !== undefined && { translate })}
     />
   );
@@ -594,6 +597,23 @@ function EntityListBody({
     setHasMore(true);
   }, [useInfinite, sortQKey]);
 
+  // User-gewählte Faceted-Filter aus dem URL-State → payload.filters.
+  // Boolean-Felder: "true"/"false"-Strings zu echten Booleans coercen
+  // (DB-Spalte ist boolean). Alles als op:"in" (Multi-Select-Semantik).
+  const filterPayload = useMemo(() => {
+    const out: { field: string; op: "in"; value: unknown }[] = [];
+    for (const [field, values] of Object.entries(urlState.filters)) {
+      if (values.length === 0) continue;
+      // entity.fields ist am Renderer-Layer schwach getypt (vom Schema
+      // deserialisiert) — Boundary-Cast wie buildInitialValues.
+      const def = entity.fields[field] as { type?: string } | undefined;
+      if (def === undefined) continue;
+      const value = def.type === "boolean" ? values.map((v) => v === "true") : values;
+      out.push({ field, op: "in", value });
+    }
+    return out;
+  }, [urlState.filters, entity.fields]);
+
   // Payload für den Server-Query-Handler (LIST_PAYLOAD_SCHEMA):
   // search/sort/sortDirection/limit + offset/totalCount für Pager-Mode
   // ODER cursor für Infinite-Scroll.
@@ -611,6 +631,9 @@ function EntityListBody({
     if (screen.filter !== undefined) {
       payload["filter"] = screen.filter;
     }
+    if (filterPayload.length > 0) {
+      payload["filters"] = filterPayload;
+    }
     if (usePager) {
       // page=1 → offset=0, page=2 → offset=limit, etc. Server
       // clampt selbst wenn offset >= total.
@@ -629,6 +652,7 @@ function EntityListBody({
     urlState.q,
     effectiveSort,
     screen.filter,
+    filterPayload,
     usePager,
     urlState.page,
     useInfinite,
@@ -678,6 +702,48 @@ function EntityListBody({
   // sonst kollidieren die Hook-Slots zwischen Renders.
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
+
+  // Faceted-Filter: ein Dropdown pro filterable select/boolean-Feld.
+  // Labels + select-Option-Labels über dieselbe i18n-Konvention wie die
+  // Spalten-Header (fieldLabelKey / :option:<value>).
+  const filterFacets = useMemo<DataTableFacet[]>(() => {
+    const out: DataTableFacet[] = [];
+    for (const [field, rawDef] of Object.entries(entity.fields)) {
+      // entity.fields ist am Renderer-Layer schwach getypt (Record<string,
+      // unknown>, vom Schema deserialisiert) — Boundary-Cast wie buildInitialValues.
+      const def = rawDef as {
+        type?: string;
+        filterable?: boolean;
+        options?: readonly string[];
+      };
+      if (def.filterable !== true) continue;
+      const label = effectiveTranslate(fieldLabelKey(featureName, screen.entity, field));
+      if (def.type === "select" && Array.isArray(def.options)) {
+        out.push({
+          field,
+          label,
+          options: def.options.map((value) => ({
+            value,
+            label: effectiveTranslate(
+              `${featureName}:entity:${screen.entity}:field:${field}:option:${value}`,
+            ),
+          })),
+        });
+      } else if (def.type === "boolean") {
+        out.push({
+          field,
+          label,
+          // ponytail: Yes/No literal — boolean-Facet-Labels i18n'en wenn eine App es braucht
+          options: [
+            { value: "true", label: "Yes" },
+            { value: "false", label: "No" },
+          ],
+        });
+      }
+    }
+    return out;
+  }, [entity.fields, featureName, screen.entity, effectiveTranslate]);
+
   // Soft-Dispatcher: in Tests die ohne DispatcherProvider mounten,
   // bleibt rowActions undefined statt zu crashen. Echte Apps haben
   // den Provider via createKumikoApp — wenn nicht, ist es vermutlich
@@ -909,6 +975,12 @@ function EntityListBody({
       {...(onCreate !== undefined && { onCreate })}
       {...(translate !== undefined && { translate })}
       {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
+      {...(filterFacets.length > 0 && {
+        filterFacets,
+        filterValues: urlState.filters,
+        onFilterChange: urlState.setFilter,
+        onFilterReset: urlState.clearFilters,
+      })}
     />
   );
 }

package/src/components/render-edit.tsx

@@ -361,21 +361,38 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     </>
   );
 
-  // Title-Resolution analog zu RenderList: i18n-Key `screen:<id>.title`,
-  // mit screenId als Fallback wenn das Bundle den Key nicht kennt.
-  const titleKey = `screen:${screen.id}.title`;
-  const resolvedTitle = translate(titleKey);
-  const formTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
+  // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
+  //   screen:<id>.<mode>.title / .<mode>.subtitle
+  // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
+  // title fällt zuletzt auf screenId, subtitle auf undefined (kein Untertitel).
+  const isCreate = (() => {
+    const id = resolveExtensionEntityId(entityIdProp, vm.id);
+    return id == null || id === "";
+  })();
+  const formMode = isCreate ? "create" : "edit";
+  const resolveScreenText = (suffix: string): string | undefined => {
+    for (const key of [
+      `screen:${screen.id}.${formMode}.${suffix}`,
+      `screen:${screen.id}.${suffix}`,
+    ]) {
+      const value = translate(key);
+      if (value !== key) return value;
+    }
+    return undefined;
+  };
+  const formTitle = resolveScreenText("title") ?? screen.id;
+  const formSubtitle = resolveScreenText("subtitle");
 
   return (
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>
       <Form
         onSubmit={() => void handleSubmit()}
         title={formTitle}
+        {...(formSubtitle !== undefined && { subtitle: formSubtitle })}
         actions={formActions}
         testId="render-edit-form"
       >
-        {vm.sections.map((section: EditSectionViewModel) => {
+        {vm.sections.map((section: EditSectionViewModel, sectionIndex: number) => {
           if (section.kind === "extension") {
             return (
               <ExtensionSectionMount
@@ -391,11 +408,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-
           // ActionForms, deren Section-Label = Screen-Titel ist).
           const sectionTitle = section.title === formTitle ? undefined : section.title;
+          // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
+          const sectionKey = section.title ?? `section-${sectionIndex}`;
           return (
             <Section
-              key={section.title}
+              key={sectionKey}
               {...(sectionTitle !== undefined && { title: sectionTitle })}
-              testId={`section-${section.title}`}
+              testId={`section-${sectionKey}`}
             >
               <Grid columns={section.columns}>
                 {section.fields.map((field: EditFieldViewModel) => (

package/src/components/render-field.tsx

@@ -73,6 +73,7 @@ export function RenderField({
       {...(issues !== undefined && { issues })}
       {...(labelAppendix !== undefined && { labelAppendix })}
       {...(fieldAppendix !== undefined && { fieldAppendix })}
+      {...(field.type === "boolean" && { layout: "inline" as const })}
       testId={`field-${field.field}`}
     >
       {control}
@@ -292,6 +293,23 @@ function renderInput({
         />
       );
     }
+    case "file":
+    case "image": {
+      const kind = field.type === "image" ? ("image" as const) : ("file" as const);
+      const fileId = typeof field.value === "string" && field.value !== "" ? field.value : null;
+      return (
+        <Input
+          kind={kind}
+          {...common}
+          value={fileId}
+          onChange={(v) => onChange(v)}
+          {...(field.accept !== undefined && { accept: field.accept })}
+          {...(field.maxSize !== undefined && { maxSize: field.maxSize })}
+          {...(field.entityType !== undefined && { entityType: field.entityType })}
+          {...(field.fieldName !== undefined && { fieldName: field.fieldName })}
+        />
+      );
+    }
     default: {
       // text + unknown → text input. Wenn TextFieldDef.multiline gesetzt
       // ist (das ViewModel hält's), wechselt der Renderer auf textarea.

package/src/components/render-list.tsx

@@ -16,7 +16,7 @@ import { extensionSectionName, useExtensionSectionComponent } from "../app/exten
 import type { ListSort } from "../hooks/use-list-url-state";
 import { type ReferenceLookupMap, useReferenceLookup } from "../hooks/use-reference-lookup";
 import { useTranslation } from "../i18n";
-import { type DataTableRowAction, usePrimitives } from "../primitives";
+import { type DataTableFacet, type DataTableRowAction, usePrimitives } from "../primitives";
 
 // RenderList — präsentationaler View für entityList-Screens.
 //
@@ -90,6 +90,15 @@ export type RenderListProps = {
    *  → useNav, handler-QN → dispatcher-Call). RenderList rendert die
    *  Buttons rechts in der Toolbar, vor "+ Neu". */
   readonly toolbarActions?: readonly ToolbarActionButton[];
+  /** Faceted-Filter-Dropdowns — KumikoScreen baut sie aus den filterable
+   *  select/boolean-Feldern; RenderList reicht sie an die DataTable durch. */
+  readonly filterFacets?: readonly DataTableFacet[];
+  /** Aktuell gewählte Facet-Werte je Feld (vom URL-State). */
+  readonly filterValues?: Readonly<Record<string, readonly string[]>>;
+  /** Toggle eines Facet-Werts (URL-State setzen + refetch). */
+  readonly onFilterChange?: (field: string, values: readonly string[]) => void;
+  /** Reset aller aktiven Facets. */
+  readonly onFilterReset?: () => void;
 };
 
 // Resolved-Form einer Toolbar-Action: KumikoScreen baut das aus dem
@@ -130,6 +139,10 @@ export function RenderList(props: RenderListProps): ReactNode {
     hasMore,
     rowActions,
     toolbarActions,
+    filterFacets,
+    filterValues,
+    onFilterChange,
+    onFilterReset,
   } = props;
   // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
   // wären Column-Header raw i18n-Keys.
@@ -331,6 +344,10 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(loadingMore !== undefined && { loadingMore })}
         {...(hasMore !== undefined && { hasMore })}
         {...(rowActions !== undefined && { rowActions })}
+        {...(filterFacets !== undefined && { filterFacets })}
+        {...(filterValues !== undefined && { filterValues })}
+        {...(onFilterChange !== undefined && { onFilterChange })}
+        {...(onFilterReset !== undefined && { onFilterReset })}
         testId="render-list-table"
       />
     </>

package/src/hooks/use-list-url-state.ts

@@ -4,10 +4,11 @@
 // nicht über dieselben Query-Keys streiten.
 //
 // Param-Schema pro Liste:
-//   <screenId>.sort  — field name (string)
-//   <screenId>.dir   — "asc" | "desc"
-//   <screenId>.q     — search term (URL-encoded)
-//   <screenId>.page  — 1-based page number (nur bei pagination="pages")
+//   <screenId>.sort     — field name (string)
+//   <screenId>.dir      — "asc" | "desc"
+//   <screenId>.q        — search term (URL-encoded)
+//   <screenId>.page     — 1-based page number (nur bei pagination="pages")
+//   <screenId>.f.<field> — Faceted-Filter: comma-joined selected values
 //
 // Schreibt mit setSearchParams (replaceState — kein push), damit
 // Sort/Filter-Toggles nicht die Browser-History fluten.
@@ -29,6 +30,9 @@ export type ListUrlState = {
   /** 1-basierte Page-Nummer. Bei pagination="infinite" oder false ist
    *  der Wert ignoriert; Caller liest ihn nur wenn relevant. */
   readonly page: number;
+  /** Aktive Faceted-Filter: field → ausgewählte Werte (Strings; Caller
+   *  coerced pro Field-Type). Leer wenn kein Filter gesetzt. */
+  readonly filters: Readonly<Record<string, readonly string[]>>;
 };
 
 export type ListUrlStateApi = ListUrlState & {
@@ -39,6 +43,11 @@ export type ListUrlStateApi = ListUrlState & {
   readonly setQ: (next: string) => void;
   /** Setzt die Page. 1 oder kleiner löscht den Key (Default-Page). */
   readonly setPage: (next: number) => void;
+  /** Setzt die ausgewählten Werte eines Facet-Felds. Leeres Array löscht
+   *  den Key. Resettet die Page (wie sort/search). */
+  readonly setFilter: (field: string, values: readonly string[]) => void;
+  /** Löscht alle aktiven Faceted-Filter (Reset-Button). */
+  readonly clearFilters: () => void;
 };
 
 // `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
@@ -72,6 +81,20 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
   const q = params[key(screenId, "q")] ?? "";
   const page = parsePage(params[key(screenId, "page")]);
 
+  const filterPrefix = `${screenId}.f.`;
+  const filters = useMemo<Readonly<Record<string, readonly string[]>>>(() => {
+    const out: Record<string, readonly string[]> = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (!k.startsWith(filterPrefix) || v === "") continue;
+      const field = k.slice(filterPrefix.length);
+      if (field === "") continue;
+      // ponytail: comma-join — Facet-Werte sind select-Options/booleans
+      // ohne Komma; upgrade auf repeated-keys falls je Komma-Werte nötig.
+      out[field] = v.split(",").filter((s) => s !== "");
+    }
+    return out;
+  }, [params, filterPrefix]);
+
   const setSort = useCallback(
     (next: ListSort | null) => {
       // Atomares Update: bei jedem Sort-Wechsel resetten wir auch die
@@ -109,5 +132,21 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
     [nav, screenId],
   );
 
-  return { sort, q, page, setSort, setQ, setPage };
+  const setFilter = useCallback(
+    (field: string, values: readonly string[]) => {
+      nav.setSearchParams({
+        [key(screenId, `f.${field}`)]: values.length === 0 ? null : values.join(","),
+        [key(screenId, "page")]: null,
+      });
+    },
+    [nav, screenId],
+  );
+
+  const clearFilters = useCallback(() => {
+    const updates: Record<string, string | null> = { [key(screenId, "page")]: null };
+    for (const field of Object.keys(filters)) updates[key(screenId, `f.${field}`)] = null;
+    nav.setSearchParams(updates);
+  }, [nav, screenId, filters]);
+
+  return { sort, q, page, filters, setSort, setQ, setPage, setFilter, clearFilters };
 }

package/src/i18n-defaults.ts

@@ -23,6 +23,13 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     // Version — Update-Awareness-Banner (UpdateChecker).
     "kumiko.version.update-available": "Eine neue Version ist verfügbar.",
 
+    // Toast — Self-service Docs-Link-Default (useToast docsLinkLabel).
+    "kumiko.toast.learn-more": "Mehr erfahren",
+
+    // Field — aria-Labels der Date/Timestamp-Primitives.
+    "kumiko.field.open-calendar": "Kalender öffnen",
+    "kumiko.field.time": "Uhrzeit",
+
     // List — DataTable Toolbar, Empty-State, Search.
     "kumiko.list.search-placeholder": "Suchen…",
     "kumiko.list.empty.title": "Noch keine Einträge.",
@@ -104,6 +111,11 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
 
     "kumiko.version.update-available": "A new version is available.",
 
+    "kumiko.toast.learn-more": "Learn more",
+
+    "kumiko.field.open-calendar": "Open calendar",
+    "kumiko.field.time": "Time",
+
     "kumiko.list.search-placeholder": "Search…",
     "kumiko.list.empty.title": "No entries yet.",
     "kumiko.list.empty.hint": "Create the first one to get started.",

package/src/index.ts

@@ -92,6 +92,7 @@ export type {
   BannerProps,
   ButtonProps,
   CorePrimitives,
+  DataTableFacet,
   DataTableProps,
   DataTableRowAction,
   DataTableRowActionMode,

package/src/primitives.tsx

@@ -99,6 +99,10 @@ export type FieldProps = {
   readonly labelAppendix?: ReactNode;
   readonly fieldAppendix?: ReactNode;
   readonly children: ReactNode;
+  /** Label-Layout. `stacked` (Default): Label über dem Control. `inline`:
+   *  Control + Label nebeneinander (Box links, Label rechts) — für
+   *  Checkbox/Switch-Felder (boolean), wie das shadcn-Muster. */
+  readonly layout?: "stacked" | "inline";
   readonly testId?: string;
 };
 
@@ -170,6 +174,24 @@ export type InputProps =
       readonly required?: boolean;
       readonly hasError?: boolean;
     }
+  | {
+      readonly kind: "file" | "image";
+      readonly id: string;
+      readonly name: string;
+      /** FileRef-UUID (gespeicherte Datei) oder null (kein Upload). */
+      readonly value: string | null;
+      readonly onChange: (fileId: string | null) => void;
+      readonly disabled?: boolean;
+      readonly required?: boolean;
+      readonly hasError?: boolean;
+      /** Erlaubte Extensions/MIME (z.B. ["jpg","png"]) → `accept`-Attribut. */
+      readonly accept?: readonly string[];
+      readonly maxSize?: string;
+      /** Für den Upload-POST `/api/files` — der Endpoint prüft maxSize/accept
+       *  gegen die Field-Def von (entityType, fieldName). */
+      readonly entityType?: string;
+      readonly fieldName?: string;
+    }
   | {
       readonly kind: "date";
       readonly id: string;
@@ -344,6 +366,19 @@ export type DataTableRowAction = {
   readonly isVisible?: (row: ListRowViewModel) => boolean;
 };
 
+// Ein Faceted-Filter-Slot in der Toolbar: ein Outline-Dropdown-Button
+// (wie shadcns "Columns"-Toggle) mit Multi-Select-Checkboxen. KumikoScreen
+// baut das aus den filterable select/boolean-Feldern des Entity.
+export type DataTableFacet = {
+  /** Entity-Feldname (= URL-State-Key + payload.filters[].field). */
+  readonly field: string;
+  /** Translated Button-Label ("Status", "Active"). */
+  readonly label: string;
+  /** Auswählbare Werte mit Anzeige-Label. value = roher Filterwert
+   *  (select-option / "true"|"false"), als String transportiert. */
+  readonly options: readonly { readonly value: string; readonly label: string }[];
+};
+
 export type DataTableProps = {
   readonly columns: readonly ListColumnViewModel[];
   readonly rows: readonly ListRowViewModel[];
@@ -384,6 +419,16 @@ export type DataTableProps = {
   /** Toolbar-Slot rechts (typisch + Neu Button, Filter, View-Switch).
    *  Web zieht den Cluster mit ml-auto an die rechte Kante. */
   readonly toolbarEnd?: ReactNode;
+  /** Faceted-Filter-Dropdowns (select/boolean-Felder) — der Renderer
+   *  setzt sie neben das Search-Input. Leer/undefined → keine Filter. */
+  readonly filterFacets?: readonly DataTableFacet[];
+  /** Aktuell ausgewählte Werte je Facet-Feld (vom URL-State). */
+  readonly filterValues?: Readonly<Record<string, readonly string[]>>;
+  /** Toggle eines Facet-Werts → Caller schreibt URL-State + refetch. */
+  readonly onFilterChange?: (field: string, values: readonly string[]) => void;
+  /** Reset-Button: löscht alle aktiven Facets. Renderer zeigt ihn nur
+   *  wenn mindestens ein Facet aktiv ist. */
+  readonly onFilterReset?: () => void;
   /** Pagination-State + Callback. Wenn gesetzt, rendert der Renderer
    *  einen Pager unter der Tabelle (Web: Footer-Bar mit ← 1 ... N →).
    *  total/limit/page sind 1-basiert für die UI; Server-Translation
@@ -425,6 +470,9 @@ export type FormProps = {
   readonly onSubmit: (e?: FormEvent) => void;
   readonly children: ReactNode;
   readonly title?: ReactNode;
+  /** Optionaler muted Untertitel unter dem Titel (z.B. "Add a new item to
+   *  your catalog") — gibt dem Form-Header Kontext statt nur ein Label. */
+  readonly subtitle?: ReactNode;
   readonly actions?: ReactNode;
   readonly testId?: string;
 };