@eifi1/ui-kit 0.24.1 → 0.25.1

package/src/components/ui.tsx

@@ -1614,7 +1614,10 @@ export function FieldHint({
   ...rest
 }: FieldHintProps) {
   return (
-    <Tooltip label={label} side={side} portal>
+    // `tap="toggle"` (0.25): the "?" exists only to explain, so a tap on a phone shows
+    // the bubble and the next tap hides it — the touch rule (no bubble left behind by a
+    // tap) would otherwise make it show nothing at all.
+    <Tooltip label={label} side={side} portal tap="toggle">
       <button
         {...rest}
         // `type` after the spread, not before. These render inside forms — that is the
@@ -2501,6 +2504,72 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
 });
 Select.displayName = "Select";
 
+/**
+ * The lower edge of {@link TEXTAREA_LABEL_STRIP} (0.25, Kurvenschmiede).
+ *
+ * The 0.24 strip ends on a hard line, and a line of text scrolled most of the way under
+ * it left its lower edge showing below that line: in a pasted table, a row of comma
+ * tails between the strip and the first whole line (`0,5;1,9` cut above its baseline is
+ * `, ,`). This layer, hung under the strip, closes that gap. What it draws depends on
+ * how much of the line on its way out is still below the strip ({@link labelEdge}):
+ *
+ * - **Half a line or less** — its descenders, the feet of its letters: covered, solid,
+ *   down to exactly where that line's box ends. The strip's bottom snaps to the line
+ *   box, so the row of tails is gone and the next line, which starts there, is not
+ *   touched.
+ * - **More than half** — a line you can still read: a soft edge, the strip's surface
+ *   fading into it over {@link LABEL_EDGE_SOFT_PX}, where 0.24 cut it hard. Never taller
+ *   than the part of that line already gone, so it grows from nothing as a line starts
+ *   to move and never reaches the next one.
+ * - **Nothing to cover** — at rest, or a line boundary right on the strip's edge:
+ *   nothing drawn. An unscrolled first line is never covered (at rest the strip covers
+ *   the top padding and nothing else, as in 0.24), and neither is any whole line.
+ *
+ * Why not one of the two alone. A plain fade under the strip, as tall as the tails,
+ * dims the top of the first WHOLE line whenever it sits right under the strip (its
+ * capitals start about 4px into a 20px line), and only half-hides the tails, which sit
+ * in its fading part. A plain snap to the line box would hide a whole line the moment
+ * one starts to scroll. The half-line threshold keeps what is shown legible: a line is
+ * either hidden or shown with most of its letters, never as a row of stray marks.
+ *
+ * Its height and solid part are `--label-strip-edge` / `--label-strip-edge-solid`,
+ * written by {@link TextareaLabelStrip} from the textarea's `scrollTop` and line height
+ * on every scroll; unset (no layout, no script yet) the height is 0 and nothing shows.
+ * A pseudo-element of the strip, so it inherits everything the strip already gets
+ * right: shown only while the label is floated, the same horizontal insets (stopped
+ * short of a classic scrollbar, on either side — RTL included), painted under the
+ * label. Its colour is INHERITED from the strip (`bg-inherit`): `--bg-surface`, and the
+ * disabled / `[readonly]` `--bg-surface-2`, in both themes, with no second copy of
+ * those selectors to keep in step. The soft part is a mask over that colour (alpha
+ * only — the `#000` is the mask's opacity, not a colour on screen).
+ */
+const TEXTAREA_LABEL_EDGE = cn(
+  "after:pointer-events-none after:absolute after:inset-x-0 after:top-full after:h-[var(--label-strip-edge,0px)] after:content-['']",
+  "after:bg-inherit after:[mask-image:linear-gradient(#000_var(--label-strip-edge-solid,0px),transparent)]",
+);
+
+/** The soft edge over a line still more than half in view, in px: "a few pixels" —
+ *  enough to take the cut off its letters, little enough to leave them legible. */
+const LABEL_EDGE_SOFT_PX = 3;
+
+/**
+ * {@link TEXTAREA_LABEL_EDGE}'s height and solid part, in px, for a field scrolled
+ * `scrollTop` with lines `lineHeight` tall.
+ *
+ * The strip covers the top padding exactly, so line boxes meet its lower edge whenever
+ * `scrollTop` is a whole number of lines; `gone` is how far the line now on its way out
+ * has passed under it, `left` how much of it is still below. A line height that is not
+ * a length (`normal`) gives no line boxes to snap to: only the soft edge then.
+ */
+function labelEdge(scrollTop: number, lineHeight: number): { height: number; solid: number } {
+  if (!(scrollTop > 0)) return { height: 0, solid: 0 };
+  if (!(lineHeight > 0)) return { height: Math.min(scrollTop, LABEL_EDGE_SOFT_PX), solid: 0 };
+  const gone = scrollTop % lineHeight;
+  const left = gone === 0 ? 0 : lineHeight - gone;
+  if (left > 0 && left <= lineHeight / 2) return { height: left, solid: left };
+  return { height: Math.min(gone, LABEL_EDGE_SOFT_PX), solid: 0 };
+}
+
 /**
  * The backdrop of a labelled {@link Textarea}'s label strip (Kurvenschmiede, 0.24).
  *
@@ -2542,11 +2611,15 @@ Select.displayName = "Select";
  *
  * The one thing CSS cannot know is a classic scrollbar's width, and a strip across the
  * whole inner width would hide the scrollbar's top arrow — see {@link TextareaLabelStrip}.
+ *
+ * Its lower edge, where a line scrolled half under it used to leave its tails showing,
+ * is {@link TEXTAREA_LABEL_EDGE} (0.25).
  */
 const TEXTAREA_LABEL_STRIP = cn(
   "pointer-events-none absolute inset-x-px top-px hidden h-4 rounded-t-[5px] bg-[var(--bg-surface)]",
   "peer-focus:block peer-[:not(:placeholder-shown)]:block",
   "peer-disabled:bg-[var(--bg-surface-2)] peer-[[readonly]]:bg-[var(--bg-surface-2)]",
+  TEXTAREA_LABEL_EDGE,
 );
 
 /**
@@ -2567,6 +2640,10 @@ const TEXTAREA_LABEL_STRIP = cn(
  * scrollbar comes or goes (it takes the content box with it) and when the field is
  * resized by hand. Not laid out — hidden in a closed panel, or jsdom — the CSS insets
  * stand until it is.
+ *
+ * It also writes the strip's lower edge (0.25, {@link TEXTAREA_LABEL_EDGE}) from the
+ * textarea's scroll position: a passive `scroll` listener, plus the same observer, since
+ * a resize can move the scroll without the user scrolling.
  */
 function TextareaLabelStrip() {
   const ref = useRef<HTMLSpanElement>(null);
@@ -2595,11 +2672,34 @@ function TextareaLabelStrip() {
       strip.style.borderStartEndRadius = bar && atEnd ? "0" : "";
       strip.style.borderStartStartRadius = bar && !atEnd ? "0" : "";
     };
+    // The edge under the strip follows the scroll — see TEXTAREA_LABEL_EDGE. The line
+    // height is read each time, since a caller's class can change the type. Nothing to
+    // draw is no property at all (the CSS default is a 0px edge), so a field at rest
+    // carries exactly the strip it did in 0.24.
+    const follow = () => {
+      const edge = labelEdge(field.scrollTop, parseFloat(getComputedStyle(field).lineHeight));
+      if (edge.height > 0) {
+        strip.style.setProperty("--label-strip-edge", `${edge.height}px`);
+        strip.style.setProperty("--label-strip-edge-solid", `${edge.solid}px`);
+      } else {
+        strip.style.removeProperty("--label-strip-edge");
+        strip.style.removeProperty("--label-strip-edge-solid");
+      }
+    };
     fit();
-    if (typeof ResizeObserver === "undefined") return;
-    const observer = new ResizeObserver(fit);
+    follow();
+    field.addEventListener("scroll", follow, { passive: true });
+    if (typeof ResizeObserver === "undefined") return () => field.removeEventListener("scroll", follow);
+    // A resize can move the scroll too (a taller field clamps it).
+    const observer = new ResizeObserver(() => {
+      fit();
+      follow();
+    });
     observer.observe(field);
-    return () => observer.disconnect();
+    return () => {
+      field.removeEventListener("scroll", follow);
+      observer.disconnect();
+    };
   }, []);
   return <span ref={ref} aria-hidden data-slot="label-strip" className={TEXTAREA_LABEL_STRIP} />;
 }

package/src/feedback/feedback-dialog.tsx

@@ -1,6 +1,7 @@
 import { useState } from "react";
 import type { ReactNode } from "react";
 import { Button, Input, PHONE_QUERY, Select, Textarea } from "../components/ui";
+import type { ButtonSize, ButtonVariant } from "../components/ui";
 import { Modal } from "../components/modal";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { useKitLabels } from "../i18n/kit-labels";
@@ -151,6 +152,21 @@ interface FeedbackDialogBaseProps {
    * dialog's behaviour until 0.14.2 (keksdose K1: its backend takes title-only reports).
    */
   requireBody?: boolean;
+  /**
+   * The attachment field's add and capture buttons: its `buttonVariant` (0.25.0),
+   * Button's own `variant`. Default `"secondary"`, the look they always had.
+   *
+   * The field took `buttonVariant` / `buttonSize` in 0.24.0 (keksdose's support chat),
+   * but the dialog builds its field itself and passed neither, so a host that wanted
+   * quieter buttons here — a dialog that already ends in a row of Cancel / Send — had
+   * no way to say so short of rebuilding the dialog. Named after the dialog's other
+   * attachment options (`attachmentAccept`, `onAttachmentError`) and handed through
+   * unchanged, in both `attachments` modes.
+   */
+  attachmentButtonVariant?: ButtonVariant;
+  /** The attachment field's `buttonSize` (0.25.0) — with {@link attachmentButtonVariant}.
+   *  Default `"md"`; `"sm"` draws the paperclip and camera at 14px. */
+  attachmentButtonSize?: ButtonSize;
 }
 
 /** One attachment — a screenshot, a picked or a pasted image; a second replaces
@@ -216,6 +232,8 @@ export function FeedbackDialog(props: FeedbackDialogProps) {
     maxAttachmentBytes = DEFAULT_MAX_ATTACHMENT_BYTES,
     onCaptureScreenshot,
     requireBody = true,
+    attachmentButtonVariant,
+    attachmentButtonSize,
   } = props;
   const [title, setTitle] = useState("");
   const [body, setBody] = useState("");
@@ -299,6 +317,9 @@ export function FeedbackDialog(props: FeedbackDialogProps) {
     accept: attachmentAccept,
     maxBytes: maxAttachmentBytes,
     onCaptureScreenshot,
+    // Left undefined they are the field's own defaults (secondary / md).
+    buttonVariant: attachmentButtonVariant,
+    buttonSize: attachmentButtonSize,
     // On `document`, not on the panel: the Modal focuses its own panel on open
     // and traps Tab inside it, so while this dialog is up every paste in the
     // page is meant for it — including the one made with nothing in

package/src/feedback/feedback-inbox.tsx

@@ -17,6 +17,7 @@ import {
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { Button, Textarea } from "../components/ui";
+import type { ButtonSize, ButtonVariant } from "../components/ui";
 import { Tooltip } from "../components/tooltip";
 import { FeedbackAttachmentField, type FeedbackAttachmentErrorInfo } from "./feedback-attachment";
 import type { FeedbackAttachmentLabels } from "./feedback-dialog";
@@ -539,6 +540,8 @@ export function FeedbackNoteEditor({
           maxBytes={attachment.maxBytes}
           onError={attachment.onError}
           onCaptureScreenshot={attachment.onCaptureScreenshot}
+          buttonVariant={attachment.buttonVariant}
+          buttonSize={attachment.buttonSize}
           // Within THIS editor's subtree, not on `document`: the editor sits
           // inline on a page that has other fields, so a paste made in one of
           // them is meant for that one. The textarea above is where the caret
@@ -560,8 +563,9 @@ export function FeedbackNoteEditor({
 }
 
 /** What {@link FeedbackNoteEditor} needs in order to offer a picture with the
- *  note: the same four things {@link FeedbackAttachmentField} takes, so the
- *  reply path is held to the app's own limits rather than to the defaults. */
+ *  note: the same things {@link FeedbackAttachmentField} takes, so the reply path is
+ *  held to the app's own limits — and drawn in its own look — rather than the
+ *  defaults. */
 export interface FeedbackNoteAttachment {
   labels: FeedbackAttachmentLabels;
   accept?: string[];
@@ -569,6 +573,19 @@ export interface FeedbackNoteAttachment {
   /** `info` (0.23.0) names the refused file and the limit. */
   onError?: (kind: "type" | "size", info: FeedbackAttachmentErrorInfo) => void;
   onCaptureScreenshot?: () => Promise<File | null>;
+  /**
+   * The add and capture buttons' look (0.25.0) — the field's `buttonVariant` (0.24.0),
+   * Button's own `variant`. Default `"secondary"`, as before.
+   *
+   * The note editor sits inline in a triage panel, and its buttons end in a ghost
+   * Cancel and a brand Save: two bordered full-size attachment buttons above them read
+   * as a second form. The field could already be told otherwise; the editor builds it
+   * itself and had nowhere to say so.
+   */
+  buttonVariant?: ButtonVariant;
+  /** The add and capture buttons' size (0.25.0) — the field's `buttonSize`. Default
+   *  `"md"`; `"sm"` draws their icons at 14px. */
+  buttonSize?: ButtonSize;
 }
 
 /**

package/src/hooks/use-body-scroll-lock.ts

@@ -24,6 +24,19 @@ import { useEffect } from "react";
 let lockCount = 0;
 let previousOverflow = "";
 let previousPaddingRight = "";
+let previousRootOverflow: { x: string; y: string } | null = null;
+
+/**
+ * Whether `overflow` on <body> reaches the viewport. It does only while <html>'s own
+ * overflow is `visible` on both axes; once an app clips or hides <html> (keksdose's
+ * `html, body { overflow-x: clip }` guard, 0.25), the body's `hidden` stays on the
+ * body and the page behind a "locked" dialog scrolls on (measured: the wheel moved
+ * 800px). Then <html> is locked too.
+ */
+function rootTakesOverflow(): boolean {
+  const style = getComputedStyle(document.documentElement);
+  return style.overflowX !== "visible" || style.overflowY !== "visible";
+}
 
 /**
  * How much width the scrollbar of the DOCUMENT is currently taking.
@@ -58,6 +71,13 @@ function acquire(): void {
     previousOverflow = document.body.style.overflow;
     previousPaddingRight = document.body.style.paddingRight;
     document.body.style.overflow = "hidden";
+    if (rootTakesOverflow()) {
+      // Per axis, so an app's own inline `overflow-x` comes back as it was.
+      const root = document.documentElement.style;
+      previousRootOverflow = { x: root.overflowX, y: root.overflowY };
+      root.overflowX = "hidden";
+      root.overflowY = "hidden";
+    }
     if (gap > 0) {
       // Added to whatever the body already had rather than assigned, so a consumer
       // that sets its own padding keeps it.
@@ -74,8 +94,13 @@ function release(): void {
   if (lockCount === 0) {
     document.body.style.overflow = previousOverflow;
     document.body.style.paddingRight = previousPaddingRight;
+    if (previousRootOverflow !== null) {
+      document.documentElement.style.overflowX = previousRootOverflow.x;
+      document.documentElement.style.overflowY = previousRootOverflow.y;
+    }
     previousOverflow = "";
     previousPaddingRight = "";
+    previousRootOverflow = null;
   }
 }
 

package/src/hooks/use-search-param-state.ts

@@ -1,4 +1,6 @@
-import { useLocation, useNavigate, useSearchParams } from "react-router";
+import { createContext, useContext, useMemo, type Context } from "react";
+import * as ReactRouter from "react-router";
+import { useLocation, useNavigate, useSearchParams, type Location, type NavigateFunction } from "react-router";
 
 type Updater<T> = T | ((prev: T) => T);
 
@@ -24,6 +26,9 @@ export interface SearchParamStateOptions<T> {
    *    which are not steps anyone wants Back to walk through.
    *  - `"replace-on-clear"`: push when a value is set, replace when it is cleared (the
    *    "open a form, close it" pattern).
+   *
+   * Several writes in one tick (one handler) add at most ONE entry — see
+   * {@link useSearchParamState}.
    */
   history?: "push" | "replace" | "replace-on-clear";
 }
@@ -37,6 +42,186 @@ function carriedState(state: unknown): Record<string, unknown> | undefined {
   return state && typeof state === "object" ? (state as Record<string, unknown>) : undefined;
 }
 
+/* ── One param: read and write ───────────────────────────────────────────── */
+
+/** One param's rules — the single hook's arguments, or one field of the multi-key hook. */
+interface ParamRule<T> {
+  key: string;
+  defaultValue: T;
+  parse?: (raw: string) => T | undefined;
+  serialize: (value: T) => string | null;
+  history: "push" | "replace" | "replace-on-clear";
+}
+
+function paramRule<T>(key: string, defaultValue: T, options: SearchParamStateOptions<T>): ParamRule<T> {
+  return {
+    key,
+    defaultValue,
+    parse: options.parse,
+    serialize: options.serialize ?? (defaultSerialize as (value: T) => string | null),
+    history: options.history ?? (options.replace ? "replace" : "push"),
+  };
+}
+
+/** An absent or unparseable param reads as the default. */
+function readParam<T>(params: URLSearchParams, rule: ParamRule<T>): T {
+  const raw = params.get(rule.key);
+  if (raw === null) return rule.defaultValue;
+  if (!rule.parse) return raw as unknown as T;
+  try {
+    const parsed = rule.parse(raw);
+    return parsed === undefined ? rule.defaultValue : parsed;
+  } catch {
+    return rule.defaultValue;
+  }
+}
+
+/**
+ * Writes `value` into `params` — the default removes the param. Returns `null` when
+ * the param already says that (a write that changes nothing has no say in the history),
+ * otherwise whether this change asks for an entry of its own.
+ */
+function putParam<T>(params: URLSearchParams, rule: ParamRule<T>, value: T): boolean | null {
+  const serialized = rule.serialize(value);
+  const next = serialized === rule.serialize(rule.defaultValue) ? null : serialized;
+  const current = params.getAll(rule.key);
+  if (next === null ? current.length === 0 : current.length === 1 && current[0] === next) return null;
+  if (next === null) params.delete(rule.key);
+  else params.set(rule.key, next);
+  return rule.history === "push" || (rule.history === "replace-on-clear" && next !== null);
+}
+
+/* ── Writes that compose ─────────────────────────────────────────────────── */
+
+/**
+ * The query as the writes made against ONE rendered location leave it — shared by every
+ * hook on that router, so a write builds on the one before it instead of on the render.
+ *
+ * Why this exists (keksdose live #378): react-router's `setSearchParams(updater)` hands
+ * its updater `new URLSearchParams(searchParams)` — the params of the RENDER the setter
+ * came from, in react-router 7 and 8 alike — not the previous call's result. keksdose
+ * wired TranslationReviewPanel's `onFilterChange` to four of these setters (status,
+ * source, ns, q); each started from the rendered URL, so the last wrote the old values
+ * of the other three back and no filter select had any effect.
+ *
+ * Keyed by react-router's location object, which is one object per committed location
+ * per router: every hook under a router reads the same one, a second router (another
+ * test) has its own, and when react-router renders the next location this record is
+ * unreachable — nothing queued outlives the navigation it belongs to. Until then a
+ * later write builds on it even a tick on (a transition or a data router's loaders still
+ * pending), which is what keeps two quick clicks from clobbering each other either. The
+ * one cost: a navigation a data router's blocker stops leaves its writes here, and the
+ * page's next write carries them again — the blocker asks again.
+ */
+interface QueuedQuery {
+  /** The query with every write against this location so far. */
+  params: URLSearchParams;
+  /** The route state of the entry those writes now sit on, carried over a replace. */
+  state: unknown;
+  /** A write in the current tick pushed; the tick's later writes rewrite that entry. */
+  pushedThisTick: boolean;
+  /** The last navigation sent was a push. */
+  lastPushed: boolean;
+}
+
+const queuedByLocation = new WeakMap<Location, QueuedQuery>();
+
+/**
+ * The data router's own state, read for ONE question: is a navigation still loading?
+ * A data router whose loaders run commits a navigation only when they finish, and a
+ * second `navigate` before then cancels the first — so a push followed by a replace
+ * in the same tick would land as a replace alone. `UNSAFE_DataRouterContext` is in
+ * react-router 6.4 through 8; read off the namespace with a stand-in, a release
+ * without it costs only that refinement, not the import.
+ */
+type DataRouterProbe = { router?: { state?: { navigation?: { state?: string } } } } | null;
+const NO_DATA_ROUTER = createContext<DataRouterProbe>(null);
+const DataRouterContext: Context<DataRouterProbe> = readDataRouterContext();
+
+/**
+ * A static member read (so a bundler still tree-shakes the namespace), inside a `try`:
+ * a test's `vi.mock("react-router", () => ({ … }))` without the original module throws
+ * on ANY export it does not define, and it threw here at import (keksdose, 0.25.0) —
+ * the hook then runs without the refinement, as on a router without the context.
+ */
+function readDataRouterContext(): Context<DataRouterProbe> {
+  try {
+    return (
+      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??
+      NO_DATA_ROUTER
+    );
+  } catch {
+    return NO_DATA_ROUTER;
+  }
+}
+
+/**
+ * One write: `change` edits the queued query in place and says whether a param it
+ * changed asks for its own entry. The navigation goes out at once — a lone write
+ * behaves exactly as before, and a test can assert right after `act` — carrying the
+ * whole queued query, so it includes every write before it.
+ *
+ * History, per tick (the writes one handler makes before a microtask runs):
+ *  - the FIRST write that asks to push pushes; every later write in the tick REPLACES
+ *    that entry, so a handler that sets four params adds one entry, and Back undoes
+ *    all four at once — they were one change;
+ *  - a write that asks to replace, before any push, rewrites the entry it found;
+ *  - so mixed modes combine as "push if any write asked to push", which keeps both
+ *    promises: a push-mode param's change is undone by Back, and a replace-mode param
+ *    never adds an entry of its own (it rides on the one the push made). A replace
+ *    write ahead of a push stays on the entry it rewrote, as it would one tick apart.
+ *  - a write that changes nothing has no say, and sends nothing.
+ */
+function writeQuery(
+  location: Location,
+  navigate: NavigateFunction,
+  dataRouter: DataRouterProbe,
+  change: (params: URLSearchParams) => boolean,
+): void {
+  let queued = queuedByLocation.get(location);
+  if (!queued) {
+    queued = {
+      params: new URLSearchParams(location.search),
+      state: location.state,
+      pushedThisTick: false,
+      lastPushed: false,
+    };
+    queuedByLocation.set(location, queued);
+  }
+  const before = queued.params.toString();
+  const wantsPush = change(queued.params);
+  const search = queued.params.toString();
+  if (search === before) return;
+
+  // A data router still loading our push has not written it to the history yet: a
+  // replace now would cancel it. Push again — the new navigation takes its place.
+  const loading = (dataRouter?.router?.state?.navigation?.state ?? "idle") !== "idle";
+  const push = (queued.lastPushed && loading) || (wantsPush && !queued.pushedThisTick);
+  if (push) {
+    queued.state = null;
+    if (!queued.pushedThisTick) {
+      queued.pushedThisTick = true;
+      const record = queued;
+      queueMicrotask(() => {
+        record.pushedThisTick = false;
+      });
+    }
+  }
+  queued.lastPushed = push;
+  void navigate(`?${search}`, push ? undefined : { replace: true, state: carriedState(queued.state) });
+}
+
+/** The rendered query, and a write that composes with every other one on the router. */
+function useQueryWriter(): [URLSearchParams, (change: (params: URLSearchParams) => boolean) => void] {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const dataRouter = useContext(DataRouterContext);
+  const params = useMemo(() => new URLSearchParams(location.search), [location.search]);
+  return [params, (change) => writeQuery(location, navigate, dataRouter, change)];
+}
+
+/* ── The hooks ───────────────────────────────────────────────────────────── */
+
 /**
  * One URL search param as React state: `const [view, setView] = useSearchParamState("view", "list")`.
  *
@@ -49,8 +234,17 @@ function carriedState(state: unknown): Record<string, unknown> | undefined {
  * * an absent or unparseable param reads as the default, and
  * * setting the default removes the param — the default view is the clean URL.
  *
- * Every other param in the query string is left as it is. Two updates in one tick do
- * not compose — react-router resolves each against the params of the last render.
+ * Every other param in the query string is left as it is.
+ *
+ * **Setters compose** (0.25, keksdose live #378): setters called in a row — of one hook,
+ * or of several hooks under the same router — each build on the write before them, so
+ * `setStatus("open"); setNs("legal")` in one handler leaves both in the URL. react-
+ * router's own `setSearchParams(updater)` does not: it hands every updater the params of
+ * the render, so the last call used to write the others' old values back. The tick's
+ * writes add at most one history entry; see `history`. When the params belong
+ * together, {@link useSearchParamsState} writes them with one setter. A functional
+ * update receives the value as the writes before it left it.
+ *
  * Requires a react-router Router.
  */
 export function useSearchParamState<T = string>(
@@ -58,49 +252,97 @@ export function useSearchParamState<T = string>(
   defaultValue: T,
   options: SearchParamStateOptions<T> = {},
 ): [T, (next: Updater<T>) => void] {
-  const { parse, serialize = defaultSerialize as (value: T) => string | null } = options;
-  const history = options.history ?? (options.replace ? "replace" : "push");
-  const [params, setParams] = useSearchParams();
-  const location = useLocation();
+  const [params, write] = useQueryWriter();
+  const rule = paramRule(key, defaultValue, options);
+  const value = readParam(params, rule);
 
-  const read = (raw: string | null): T => {
-    if (raw === null) return defaultValue;
-    if (!parse) return raw as unknown as T;
-    try {
-      const parsed = parse(raw);
-      return parsed === undefined ? defaultValue : parsed;
-    } catch {
-      return defaultValue;
-    }
-  };
-  const value = read(params.get(key));
-  const defaultSerialized = serialize(defaultValue);
-  const toParam = (v: T): string | null => {
-    const s = serialize(v);
-    return s === defaultSerialized ? null : s;
-  };
-
-  const setValue = (next: Updater<T>) => {
-    // Resolved against the rendered value only to choose the history mode; the write
-    // resolves again inside react-router's updater, against the params it hands over.
-    const preview = typeof next === "function" ? (next as (prev: T) => T)(value) : next;
-    const replace = history === "replace" || (history === "replace-on-clear" && toParam(preview) === null);
-    setParams(
-      (prev) => {
-        const p = new URLSearchParams(prev);
-        const resolved = typeof next === "function" ? (next as (prev: T) => T)(read(p.get(key))) : next;
-        const serialized = toParam(resolved);
-        if (serialized === null) p.delete(key);
-        else p.set(key, serialized);
-        return p;
-      },
-      replace ? { replace, state: carriedState(location.state) } : undefined,
-    );
-  };
+  const setValue = (next: Updater<T>) =>
+    write((query) => {
+      // Resolved against the queued query, not the render: a second update in the same
+      // handler sees the first one's result, as React's own functional updates do.
+      const resolved = typeof next === "function" ? (next as (prev: T) => T)(readParam(query, rule)) : next;
+      return putParam(query, rule, resolved) === true;
+    });
 
   return [value, setValue];
 }
 
+/** One field of {@link useSearchParamsState}: its default, and the single hook's options. */
+export interface SearchParamField<T> extends SearchParamStateOptions<T> {
+  /** The value when the param is absent or does not parse; writing it removes the param. */
+  default: T;
+  /** The param's name in the URL. Default: the field's name (`namespace: { param: "ns" }`). */
+  param?: string;
+}
+
+/** The fields of {@link useSearchParamsState}, one per key of the value object. */
+export type SearchParamFields<V> = { [K in keyof V]: SearchParamField<V[K]> };
+
+/** A partial value (fields left out — or `undefined` — stay as they are), or a function
+ *  of the current value returning one. */
+export type SearchParamsUpdate<V> = Partial<V> | ((prev: V) => Partial<V>);
+
+/**
+ * Several URL search params as ONE state object, with one setter that writes them in
+ * one navigation:
+ *
+ *     const [filter, setFilter] = useSearchParamsState({
+ *       status: { default: "all" as ReviewStatus | "all", parse: toStatus },
+ *       namespace: { param: "ns", default: "all" },
+ *       query: { param: "q", default: "", history: "replace" },
+ *     });
+ *     <TranslationReviewPanel filter={filter} onFilterChange={setFilter} />
+ *
+ * keksdose live #378: a filter bar reports all its filters on every change, and four
+ * single-param setters in a row clobbered each other (see {@link useSearchParamState},
+ * whose setters now compose too). This is the shape that never could: one setter, one
+ * write, every field's rules in one place.
+ *
+ * Each field takes what the single hook takes — `parse`, `serialize`, `history` /
+ * `replace` — and its `default` (the clean URL, as there) and optional `param` name.
+ * The setter takes a partial object or a function of the current one; fields it leaves
+ * out, or sets to `undefined`, stay as they are, and keys that are not fields are
+ * ignored, so a component's whole filter object can be handed over as it is. Its
+ * history is the single hook's rule over the fields that change: one entry, pushed if
+ * any of them asks to push, else the current entry rewritten. Setting what the URL
+ * already says navigates nowhere.
+ *
+ * The value object keeps its identity while its params do not change, so it can sit in
+ * a dependency array. Requires a react-router Router.
+ */
+export function useSearchParamsState<V extends object>(
+  fields: SearchParamFields<V>,
+): [V, (next: SearchParamsUpdate<V>) => void] {
+  const [params, write] = useQueryWriter();
+  const rules = (Object.keys(fields) as Array<keyof V & string>).map((name) => {
+    const field = fields[name];
+    return [name, paramRule(field.param ?? name, field.default, field)] as const;
+  });
+  const readAll = (query: URLSearchParams): V =>
+    Object.fromEntries(rules.map(([name, rule]) => [name, readParam(query, rule)])) as V;
+
+  // The fields' own params, not the whole query: another param changing (a tab, a
+  // dialog) leaves this object as it was. `fields` is a fresh literal every render;
+  // what it reads is the same while the params and the field names are.
+  const ownParams = JSON.stringify(rules.map(([name, rule]) => [name, params.getAll(rule.key)]));
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on what the value is read from; see above
+  const values = useMemo(() => readAll(params), [ownParams]);
+
+  const setValues = (next: SearchParamsUpdate<V>) =>
+    write((query) => {
+      const patch = typeof next === "function" ? next(readAll(query)) : next;
+      let push = false;
+      for (const [name, rule] of rules) {
+        const value = patch[name];
+        if (value === undefined) continue;
+        if (putParam(query, rule as ParamRule<unknown>, value) === true) push = true;
+      }
+      return push;
+    });
+
+  return [values, setValues];
+}
+
 /**
  * The active tab in `?tab=` (or `key`), with the default tab as the clean URL, for the
  * kit's `Tabs`: