@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

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

@@ -1,207 +0,0 @@
-// useListUrlState — bündelt sort/dir/page/q einer entityList in einen
-// per-screen-id namespaced URL-State. Mit Screen-ID-Prefix damit zwei
-// Listen auf derselben Route (z.B. Dashboard mit Orders + Incidents)
-// 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>.f.<field> — Faceted-Filter: comma-joined selected values
-//
-// Schreibt mit setSearchParams (replaceState — kein push), damit
-// Sort/Filter-Toggles nicht die Browser-History fluten.
-
-import { useCallback, useMemo } from "react";
-import { useNav } from "../app/nav";
-import type { DataTableSort, DataTableSortDir } from "../primitives";
-
-// ListSort + DataTableSort hatten dieselbe Shape und drohten zu driften
-// — aliased auf den primitives-Type (eine Quelle, kein Cast in RenderList).
-export type ListSortDir = DataTableSortDir;
-export type ListSort = DataTableSort;
-
-export type ListUrlState = {
-  /** Aktive Sortierung (oder null = unsorted, Server liefert Default-Order). */
-  readonly sort: ListSort | null;
-  /** Search-Term (leer wenn nicht gesetzt). */
-  readonly q: string;
-  /** 1-basierte Page-Nummer. Bei pagination="infinite" oder false ist
-   *  der Wert ignoriert; Caller liest ihn nur wenn relevant. */
-  readonly page: number;
-  /** User-chosen page size from `PAGE_SIZE_OPTIONS`; undefined = screen default. */
-  readonly pageSize: number | undefined;
-  /** 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 & {
-  /** Setzt sort + dir atomar. null = unsorted (löscht beide Keys). */
-  readonly setSort: (next: ListSort | null) => void;
-  /** Setzt den Search-Term. Empty-String löscht den Key. Caller debounced
-   *  selber (z.B. useDebouncedCallback in der Search-Input-Komponente). */
-  readonly setQ: (next: string) => void;
-  /** Setzt die Page. 1 oder kleiner löscht den Key (Default-Page). */
-  readonly setPage: (next: number) => void;
-  /** Sets the page size and resets the page; undefined clears the key. */
-  readonly setPageSize: (next: number | undefined) => 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;
-  /** Sets both bounds of a dateRange facet in ONE params update — two
-   *  setFilter calls would overwrite each other, since the second still sees
-   *  the old searchParams. An empty string clears that bound. Resets the page
-   *  like setFilter. */
-  readonly setDateRange: (
-    field: string,
-    next: { readonly from: string; readonly to: string },
-  ) => void;
-};
-
-// `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
-// üblichen Field-Namen (kebab- oder camelCase ohne Punkt). Boot-Validator
-// pinnt screen.id ohne Punkt — siehe boot-validator entityList Section.
-export const PAGE_SIZE_OPTIONS: readonly number[] = [25, 50, 100];
-
-function parsePageSize(value: string | undefined): number | undefined {
-  if (value === undefined) return undefined;
-  const n = Number.parseInt(value, 10);
-  return PAGE_SIZE_OPTIONS.includes(n) ? n : undefined;
-}
-
-function key(screenId: string, suffix: string): string {
-  return `${screenId}.${suffix}`;
-}
-
-function parseDir(value: string | undefined): ListSortDir | undefined {
-  return value === "asc" || value === "desc" ? value : undefined;
-}
-
-function parsePage(value: string | undefined): number {
-  if (value === undefined) return 1;
-  const n = Number.parseInt(value, 10);
-  return Number.isFinite(n) && n > 0 ? n : 1;
-}
-
-export function useListUrlState(screenId: string): ListUrlStateApi {
-  const nav = useNav();
-  const params = nav.searchParams;
-
-  const sort = useMemo<ListSort | null>(() => {
-    const field = params[key(screenId, "sort")];
-    const dir = parseDir(params[key(screenId, "dir")]);
-    if (field === undefined || field === "" || dir === undefined) return null;
-    return { field, dir };
-  }, [params, screenId]);
-
-  const q = params[key(screenId, "q")] ?? "";
-  const page = parsePage(params[key(screenId, "page")]);
-  const pageSize = parsePageSize(params[key(screenId, "size")]);
-
-  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
-      // Page (sonst wäre der User auf "Seite 5 von alter Sortierung"
-      // hängen, was visuell verwirrend ist). Page-Reset gilt auch bei
-      // null — gleiche Logik.
-      nav.setSearchParams({
-        [key(screenId, "sort")]: next === null ? null : next.field,
-        [key(screenId, "dir")]: next === null ? null : next.dir,
-        [key(screenId, "page")]: null,
-      });
-    },
-    [nav, screenId],
-  );
-
-  const setQ = useCallback(
-    (next: string) => {
-      // Search-Change resettet Page (gleicher Grund wie Sort) UND
-      // Sort? Nein — User kann mit aktivem Sort suchen wollen, das
-      // soll die Sortierung nicht zerlegen. Nur Page wird gereset.
-      nav.setSearchParams({
-        [key(screenId, "q")]: next === "" ? null : next,
-        [key(screenId, "page")]: null,
-      });
-    },
-    [nav, screenId],
-  );
-
-  const setPage = useCallback(
-    (next: number) => {
-      nav.setSearchParams({
-        [key(screenId, "page")]: next <= 1 ? null : String(next),
-      });
-    },
-    [nav, screenId],
-  );
-
-  const setPageSize = useCallback(
-    (next: number | undefined) => {
-      nav.setSearchParams({
-        [key(screenId, "size")]: next === undefined ? null : String(next),
-        [key(screenId, "page")]: null,
-      });
-    },
-    [nav, screenId],
-  );
-
-  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 setDateRange = useCallback(
-    (field: string, next: { readonly from: string; readonly to: string }) => {
-      nav.setSearchParams({
-        [key(screenId, `f.${field}.from`)]: next.from === "" ? null : next.from,
-        [key(screenId, `f.${field}.to`)]: next.to === "" ? null : next.to,
-        [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,
-    pageSize,
-    filters,
-    setSort,
-    setQ,
-    setPage,
-    setPageSize,
-    setFilter,
-    clearFilters,
-    setDateRange,
-  };
-}

package/src/hooks/use-mutation.ts

@@ -1,61 +0,0 @@
-import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context";
-
-// React wrapper around dispatcher.write — the write-side sibling of
-// useQuery. One hook instance per handler-type; `mutate` carries the
-// payload so a single instance serves list-row actions with varying
-// payloads.
-//
-// `mutate` resolves with the raw WriteResult so callers can branch
-// (navigate on success, keep the form open on failure) without waiting
-// for a re-render of `error`/`data`.
-
-export type UseMutationResult<TData> = {
-  readonly mutate: (payload: unknown) => Promise<WriteResult<TData>>;
-  readonly pending: boolean;
-  readonly error: DispatcherError | null;
-  readonly data: TData | null;
-  readonly reset: () => void;
-};
-
-export function useMutation<TData = unknown>(type: string): UseMutationResult<TData> {
-  const dispatcher = useDispatcher();
-  const [pending, setPending] = useState(false);
-  const [error, setError] = useState<DispatcherError | null>(null);
-  const [data, setData] = useState<TData | null>(null);
-  // Sequence guard: `mutate` has no abort (unlike useQuery's GETs, a write
-  // already landed server-side and can't be cancelled). Two overlapping
-  // calls on one instance (e.g. two list-row actions) must not let the
-  // first-to-resolve clobber pending/error/data set by the second — only
-  // the most recently STARTED call's outcome may update shared state.
-  const sequence = useRef(0);
-
-  const mutate = useCallback(
-    async (payload: unknown): Promise<WriteResult<TData>> => {
-      const callSeq = ++sequence.current;
-      setPending(true);
-      setError(null);
-      const result = await dispatcher.write<TData>(type, payload);
-      if (callSeq === sequence.current) {
-        if (result.isSuccess) {
-          setData(result.data);
-        } else {
-          setError(result.error);
-        }
-        setPending(false);
-      }
-      return result;
-    },
-    [dispatcher, type],
-  );
-
-  const reset = useCallback(() => {
-    sequence.current++; // invalidate any in-flight mutate's late update
-    setPending(false);
-    setError(null);
-    setData(null);
-  }, []);
-
-  return { mutate, pending, error, data, reset };
-}

package/src/hooks/use-query.ts

@@ -1,166 +0,0 @@
-import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context";
-import { useLiveEvents } from "../sse/live-events";
-
-// React wrapper around dispatcher.query. Fires on mount, re-fires
-// whenever `type` or the serialized payload change, and exposes a
-// `refetch` imperative hook for after-mutation reloads.
-//
-// Cancellation: each fetch owns an AbortController; a newer fetch
-// (change in deps or manual refetch) aborts the older one's network
-// call before firing, so a slow request can't overwrite a fresh one.
-// Unmount aborts any in-flight call too — React will throw the
-// "state on unmounted" warning if we set state after unmount, and
-// aborting pre-emptively makes that path a no-op.
-//
-// Result shape modeled on the dispatcher's own QueryResult: a
-// discriminated state so callers can branch on `loading | data | error`
-// without undefined-juggling. The first render is `loading: true,
-// data: null, error: null` (no optimistic "online" cache — add that
-// later if needed).
-
-export type UseQueryResult<TData> = {
-  readonly data: TData | null;
-  readonly error: DispatcherError | null;
-  readonly loading: boolean;
-  readonly refetch: () => Promise<void>;
-};
-
-export type UseQueryOptions = {
-  // When false, skips the automatic fetch-on-mount and re-fetch on
-  // dep-change. Useful for lazy queries that only run after a user
-  // action. `refetch()` still works as an imperative trigger.
-  readonly enabled?: boolean;
-  // When true, subscribe to SSE events for the entity this query
-  // targets and refetch on any create/update/delete/restore event.
-  // The entity-name is parsed from the query type using Kumiko's
-  // `<feature>:query:<entity>:<verb>` convention — if the type
-  // doesn't follow that shape, live-mode is a no-op.
-  readonly live?: boolean;
-  // Re-runs the query every N ms while enabled. Ticks are silent (no
-  // `loading` flip) and skipped while a fetch is still in flight. Only
-  // timers are used, so it behaves the same on web and React Native.
-  readonly refetchIntervalMs?: number;
-};
-
-// Extract the entity-name from a standard Kumiko query type. Returns
-// undefined for non-conforming types so the live-mode silently skips
-// them instead of subscribing to a channel no event will ever match.
-export function entityFromQueryType(type: string): string | undefined {
-  // Expected shape: "<feature>:query:<entity>:<verb>"
-  const parts = type.split(":");
-  if (parts.length !== 4) return undefined;
-  if (parts[1] !== "query") return undefined;
-  return parts[2];
-}
-
-export function useQuery<TData = unknown>(
-  type: string,
-  payload: unknown,
-  options: UseQueryOptions = {},
-): UseQueryResult<TData> {
-  const dispatcher = useDispatcher();
-  const { enabled = true, live = false, refetchIntervalMs } = options;
-
-  const [data, setData] = useState<TData | null>(null);
-  const [error, setError] = useState<DispatcherError | null>(null);
-  const [loading, setLoading] = useState<boolean>(enabled);
-
-  // Track the AbortController for the most recent fetch so a newer
-  // call can cancel the older one. Ref, not state, because the
-  // controller identity shouldn't trigger a re-render.
-  const activeCtrl = useRef<AbortController | null>(null);
-  // A tick that aborted a running fetch would starve slow queries, so
-  // ticks consult this flag instead.
-  const fetchInFlight = useRef(false);
-
-  // Serialize payload so object-identity-changes across renders (the
-  // caller building a fresh `{}` every render) don't loop. Strings are
-  // stable by reference in React's dep-array check.
-  const payloadKey = JSON.stringify(payload);
-
-  // `dispatcher` is stable (context identity); `type` + `payloadKey`
-  // are the meaningful re-run triggers. `payload` itself is intentionally
-  // not in deps — it's serialized into payloadKey above.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
-  const runFetch = useCallback(
-    async (background: boolean): Promise<void> => {
-      // Abort whatever's in flight. observer on Safari 17+ handles this
-      // without raising a fetch-throw in the previous caller — they
-      // already set the error path.
-      activeCtrl.current?.abort();
-      const ctrl = new AbortController();
-      activeCtrl.current = ctrl;
-
-      fetchInFlight.current = true;
-      if (!background) setLoading(true);
-      let result: Awaited<ReturnType<typeof dispatcher.query<TData>>>;
-      try {
-        result = await dispatcher.query<TData>(type, payload, { signal: ctrl.signal });
-      } finally {
-        // A rejected fetch must not leave polling stuck; a superseded one must
-        // not clear the newer fetch's flag.
-        if (activeCtrl.current === ctrl) fetchInFlight.current = false;
-      }
-      // skip: a newer fetch already superseded this one, don't clobber its state
-      if (ctrl.signal.aborted) return;
-      if (result.isSuccess) {
-        setData(result.data);
-        setError(null);
-      } else {
-        // A cancelled request comes back with code "aborted" from the
-        // skip: aborted request, a newer run already replaces this result
-        if (result.error.code === "aborted") return;
-        setError(result.error);
-      }
-      setLoading(false);
-    },
-    [dispatcher, type, payloadKey],
-  );
-
-  const run = useCallback((): Promise<void> => runFetch(false), [runFetch]);
-
-  useEffect(() => {
-    if (!enabled) {
-      setLoading(false);
-      // skip: query disabled, loading state already cleared above
-      return;
-    }
-    void run();
-    return () => {
-      activeCtrl.current?.abort();
-      fetchInFlight.current = false;
-    };
-  }, [enabled, run]);
-
-  useEffect(() => {
-    // skip: polling off or disabled query
-    if (!enabled || refetchIntervalMs === undefined) return;
-    // skip: non-positive or non-finite interval disables polling
-    if (!Number.isFinite(refetchIntervalMs) || refetchIntervalMs <= 0) return;
-    const timer = setInterval(() => {
-      // skip: a fetch is still running, the next tick retries
-      if (fetchInFlight.current) return;
-      void runFetch(true);
-    }, refetchIntervalMs);
-    return () => clearInterval(timer);
-  }, [enabled, refetchIntervalMs, runFetch]);
-
-  // Live-mode: auf SSE-Events für die Query-Entity hören und refetchen.
-  // Separater Effect, damit eine Änderung an `live` oder `type` das
-  // Subscription-Lifecycle genau einmal durchwalzt.
-  const subscribeLive = useLiveEvents();
-  useEffect(() => {
-    // skip: live mode or query disabled, no SSE subscription needed
-    if (!live || !enabled) return;
-    const entity = entityFromQueryType(type);
-    // skip: query type has no mapped entity, nothing to subscribe to
-    if (entity === undefined) return;
-    return subscribeLive(entity, () => {
-      void run();
-    });
-  }, [live, enabled, type, run, subscribeLive]);
-
-  return { data, error, loading, refetch: run };
-}

package/src/hooks/use-reference-lookup.ts

@@ -1,76 +0,0 @@
-// Tier 2.7e-4: Renderer-Side Eagerload für Reference-Felder.
-//
-// Pro Reference-Spalte einer Liste wird einmal `<feature>:query:
-// <refEntity>:list` (limit:200) gerufen, eine Map<uuid, displayValue>
-// gebaut, und der Renderer nutzt sie als Cell-Display-Renderer.
-//
-// Strategy-Trade-offs:
-//   - Server-side Drizzle-Joins wären effizienter (eine Query statt
-//     N+1), würden aber die executor-API um lookupTables erweitern
-//     müssen. Für das MVP geht der Renderer-Side-Pfad vor.
-//   - Limit:200 ist eine harte UX-Grenze: bei mehr Entries in der
-//     referenced Entity zeigen die letzten Rows nur noch UUIDs.
-//     Searchable-Combobox (Tier 2.1c) + Server-Eagerload mit
-//     ID-Whitelist heben das später auf.
-//
-// Dieser Hook ist call-stable: Lookup-Map wird durch useQuery's
-// internen Cache shared zwischen List + Edit-Form für die gleiche
-// Entity, Live-Updates kommen via SSE (use-query-live).
-
-import {
-  REFERENCE_LOOKUP_SOURCES,
-  SYSTEM_REFERENCE_LABELS,
-} from "@cosmicdrift/kumiko-framework/ui-types";
-import { useMemo } from "react";
-import { toKebab } from "../app/qn";
-import { useTranslation } from "../i18n";
-import { REFERENCE_LIST_LOOKUP_LIMIT } from "./reference-limits";
-import { useQuery } from "./use-query";
-
-export type ReferenceLookupMap = ReadonlyMap<string, string>;
-
-/** Where a reference target's label rows come from: the central override for
- *  that `feature:entity` if one exists, else the entity-convention list
- *  handler plus the caller's own label field. */
-export function referenceLookupSource(
-  refFeature: string,
-  refEntity: string,
-  labelField: string,
-): { readonly queryQn: string; readonly labelKey: string } {
-  const override = REFERENCE_LOOKUP_SOURCES[`${refFeature}:${refEntity}`];
-  if (override !== undefined) return override;
-  return {
-    queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
-    labelKey: labelField,
-  };
-}
-
-/** Empty while the query loads (or fails), so callers fall back to the raw id.
- *  `featureName` is the reference's target feature, not the screen's. */
-export function useReferenceLookup(
-  featureName: string,
-  refEntity: string,
-  labelField: string,
-): { readonly map: ReferenceLookupMap; readonly loading: boolean } {
-  const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
-  const result = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
-    limit: REFERENCE_LIST_LOOKUP_LIMIT,
-  });
-  const translate = useTranslation();
-  const systemLabel = SYSTEM_REFERENCE_LABELS[`${featureName}:${refEntity}`];
-  const map = useMemo(() => {
-    const out = new Map<string, string>();
-    for (const row of result.data?.rows ?? []) {
-      const id = row["id"];
-      if (id === undefined || id === null) continue;
-      const idStr = String(id);
-      const label = row[labelKey] ?? id;
-      out.set(idStr, String(label));
-    }
-    // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row, so
-    // the bulk lookup above never covers them — inject the label directly.
-    if (systemLabel !== undefined) out.set(systemLabel.id, translate(systemLabel.labelKey));
-    return out;
-  }, [result.data, labelKey, systemLabel, translate]);
-  return { map, loading: result.loading };
-}

package/src/hooks/use-store.ts

@@ -1,48 +0,0 @@
-import type { Store } from "@cosmicdrift/kumiko-headless";
-import { useRef, useSyncExternalStore } from "react";
-
-// React-Bindings für Kumikos Store-Primitive (`createStore` aus
-// @cosmicdrift/kumiko-headless). Beide Hooks sind dünne Wrapper um React's
-// useSyncExternalStore — die ganze Subscribe/Notify-Mechanik lebt im
-// Store selbst, hier wird nur React verdrahtet.
-//
-// useStore: gibt den ganzen Snapshot zurück. Re-rendert wenn der
-// Store seine Identität wechselt. Object.is-Gate im Store selbst
-// verhindert no-op-Updates.
-//
-// useStoreSelector: gibt eine abgeleitete Sicht zurück. Selectors die
-// Object-/Array-Literale zurückgeben (z.B. `s => ({ a, b })`) erzeugen
-// pro Render eine neue Identität — useSyncExternalStore würde das als
-// "Change" lesen und in eine Re-Render-Schleife laufen. Der dritte
-// Arg `equals` dient genau dafür: gleiche Auswahl → cached
-// Identität zurück, kein Re-Render.
-
-// @wrapper-known semantic-alias
-export function useStore<T>(store: Store<T>): T {
-  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
-}
-
-export function useStoreSelector<T, S>(
-  store: Store<T>,
-  select: (snapshot: T) => S,
-  equals: (a: S, b: S) => boolean = Object.is,
-): S {
-  // Cache der letzten Auswahl. Beim nächsten getSnapshot-Call vergleicht
-  // der Wrapper die neu berechnete Auswahl mit dem Cache und gibt — falls
-  // gleich — die cached Identität zurück. Das ist der Trick, der
-  // Selector-Returns wie `s => ({ a, b })` stabil hält.
-  const lastSelected = useRef<S>(undefined as S);
-  const initialized = useRef(false);
-
-  const getSelectedSnapshot = (): S => {
-    const next = select(store.getSnapshot());
-    if (initialized.current && equals(lastSelected.current, next)) {
-      return lastSelected.current;
-    }
-    lastSelected.current = next;
-    initialized.current = true;
-    return next;
-  };
-
-  return useSyncExternalStore(store.subscribe, getSelectedSnapshot, getSelectedSnapshot);
-}