@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/components/choice-card.tsx

@@ -1,8 +1,19 @@
 import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useRef } from "react";
-import type { ButtonHTMLAttributes, ChangeEvent, ComponentType, InputHTMLAttributes, ReactNode } from "react";
+import type {
+  ButtonHTMLAttributes,
+  ChangeEvent,
+  ComponentType,
+  InputHTMLAttributes,
+  MouseEvent,
+  ReactElement,
+  ReactNode,
+  Ref,
+} from "react";
 import { Check, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
 import { assignRef, hasMessage, mergeDescribedBy } from "./choice-parts";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "./text-link";
 
 /**
  * A checkbox or a radio, presented as a bordered card: a title, a line of description,
@@ -231,6 +242,30 @@ const META_TONE: Record<ActionCardMetaTone, string> = {
   success: "text-[var(--success)]",
 };
 
+/** The colour of {@link ActionCardProps.icon}. `default` is the secondary text colour
+ *  the icon has always had; `brand` tints it (keksdose's privacy enrolment). */
+export type ActionCardIconTone = "default" | "muted" | "brand" | "warning" | "danger" | "info" | "success";
+
+const ICON_TONE: Record<ActionCardIconTone, string> = {
+  default: "text-[var(--text-secondary)]",
+  ...META_TONE,
+  brand: "text-[var(--brand)]",
+};
+
+/** What {@link ActionCardProps.renderLink} (and the provider's `linkComponent`) is
+ *  handed. Spread it onto your router's link — `({ href, ...p }) => <Link to={href} {...p} />`. */
+export interface ActionCardLinkProps {
+  href: string;
+  /** The card's whole look — keep it. */
+  className: string;
+  children: ReactNode;
+  ref?: Ref<HTMLAnchorElement>;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+  id?: string;
+  [key: `aria-${string}`]: string | boolean | number | undefined;
+  [key: `data-${string}`]: unknown;
+}
+
 export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> {
   /** What the card does — the button's accessible name. */
   title: ReactNode;
@@ -247,6 +282,21 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
   metaTone?: ActionCardMetaTone;
   /** A Lucide icon (or any component taking a `className`), shown at the card's start. */
   icon?: ChoiceCardProps["icon"];
+  /** The icon's colour. Default `default` (the secondary text colour). */
+  iconTone?: ActionCardIconTone;
+  /** Classes on the icon, after {@link iconTone} — a size, a tinted tile behind it. */
+  iconClassName?: string;
+  /**
+   * Makes the card a LINK to another page rather than a button that acts: kastlan's
+   * section tiles on the group overview (group-overview-page), each an icon, a name and
+   * a line on what is there. A real `<a href>`, so a middle click opens it in a new
+   * tab. A `disabled` card renders the inert button instead — a link cannot be
+   * disabled. The ref then reaches the `<a>`.
+   */
+  href?: string;
+  /** Your router's link for an in-app `href`. Default: the `<UiKitProvider
+   *  linkComponent>`, then a plain `<a>`. Ignored without `href`. */
+  renderLink?: (props: ActionCardLinkProps) => ReactElement;
 }
 
 /**
@@ -254,7 +304,8 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
  * card's icon, title and description, plus a `meta` line, that runs `onClick` the
  * moment it is pressed. keksdose's privacy enrolment (privacy-enroll-dialog:345,
  * `CustodyOption`) offers two custody modes this way — picking one IS the next step,
- * so there is no checked state to show and no "Continue" to press after it.
+ * so there is no checked state to show and no "Continue" to press after it. With
+ * `href` it is the same card as a link (kastlan's overview section tiles).
  *
  * A separate component rather than `ChoiceCard as="button"`: a ChoiceCard is an
  * `<input>` (its ref, its `checked`, its form value), and a button shares none of it.
@@ -262,9 +313,24 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
  * "Keep the key yourself, button" and then the explanation, not one long name.
  */
 export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(function ActionCard(
-  { title, description, meta, metaTone = "muted", icon: Icon, className, id, type = "button", ...rest },
+  {
+    title,
+    description,
+    meta,
+    metaTone = "muted",
+    icon: Icon,
+    iconTone = "default",
+    iconClassName,
+    href,
+    renderLink,
+    className,
+    id,
+    type = "button",
+    ...rest
+  },
   ref,
 ) {
+  const kitLink = useKitLink();
   const generated = useId();
   const baseId = id ?? generated;
   const titleId = `${baseId}-title`;
@@ -272,28 +338,23 @@ export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(functio
   const metaId = `${baseId}-meta`;
   const showDescription = hasMessage(description);
   const showMeta = hasMessage(meta);
-  return (
-    <button
-      ref={ref}
-      id={id}
-      type={type}
-      {...rest}
-      aria-labelledby={rest["aria-labelledby"] ?? titleId}
-      aria-describedby={mergeDescribedBy(
-        rest["aria-describedby"],
-        showDescription && descriptionId,
-        showMeta && metaId,
-      )}
-      className={cn(
-        "flex w-full items-start gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] p-3 text-start shadow-sm transition-colors",
-        "hover:border-[var(--brand)] hover:bg-[var(--bg-hover)]",
-        // The outline, as on ChoiceCard: the card is what the eye is on.
-        "focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
-        "disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:border-[var(--border)] disabled:hover:bg-[var(--bg-surface)]",
-        className,
-      )}
-    >
-      {Icon && <Icon aria-hidden className="mt-0.5 size-5 shrink-0 text-[var(--text-secondary)]" />}
+  const look = cn(
+    "flex w-full items-start gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] p-3 text-start shadow-sm transition-colors",
+    "hover:border-[var(--brand)] hover:bg-[var(--bg-hover)]",
+    // The outline, as on ChoiceCard: the card is what the eye is on.
+    "focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
+    "disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:border-[var(--border)] disabled:hover:bg-[var(--bg-surface)]",
+    className,
+  );
+  const labelledBy = rest["aria-labelledby"] ?? titleId;
+  const describedBy = mergeDescribedBy(
+    rest["aria-describedby"],
+    showDescription && descriptionId,
+    showMeta && metaId,
+  );
+  const body = (
+    <>
+      {Icon && <Icon aria-hidden className={cn("mt-0.5 size-5 shrink-0", ICON_TONE[iconTone], iconClassName)} />}
       <span className="min-w-0 flex-1 space-y-1">
         <span id={titleId} className="block text-sm font-medium leading-5 text-[var(--text-primary)]">
           {title}
@@ -309,11 +370,61 @@ export const ActionCard = forwardRef<HTMLButtonElement, ActionCardProps>(functio
           </span>
         )}
       </span>
+    </>
+  );
+
+  if (href !== undefined && !rest.disabled) {
+    // The button-only attributes stay behind; `aria-*`, `data-*` and handlers ride along.
+    const {
+      disabled: _disabled,
+      form: _form,
+      formAction: _formAction,
+      name: _name,
+      value: _value,
+      onClick,
+      ...anchorRest
+    } = rest;
+    const linkProps: ActionCardLinkProps = {
+      ...(anchorRest as Partial<ActionCardLinkProps>),
+      ref: ref as unknown as Ref<HTMLAnchorElement>,
+      id,
+      href,
+      "aria-labelledby": labelledBy,
+      "aria-describedby": describedBy,
+      onClick: onClick as unknown as ActionCardLinkProps["onClick"],
+      className: look,
+      children: body,
+    };
+    const render = pickLinkRenderer(renderLink, kitLink, href);
+    if (render) return <RenderedActionLink render={render} {...linkProps} />;
+    const { children: content, ...anchor } = linkProps;
+    return <a {...anchor}>{content}</a>;
+  }
+
+  return (
+    <button
+      ref={ref}
+      id={id}
+      type={type}
+      {...rest}
+      aria-labelledby={labelledBy}
+      aria-describedby={describedBy}
+      className={look}
+    >
+      {body}
     </button>
   );
 });
 ActionCard.displayName = "ActionCard";
 
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedActionLink({
+  render,
+  ...props
+}: ActionCardLinkProps & { render: (props: ActionCardLinkProps) => ReactElement }) {
+  return render(props);
+}
+
 /* ── ChoiceCardGroup ─────────────────────────────────────────────────────── */
 
 export interface ChoiceCardOption<T extends string> {

package/src/components/combobox-core.tsx

@@ -10,6 +10,7 @@ import type {
 } from "react";
 import { Check, Plus } from "lucide-react";
 import { cn } from "../lib/cn";
+import { CLIPS_ATTRIBUTE } from "../lib/clipping";
 import { DropdownSearchHeader } from "./dropdown";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import { useMediaQuery } from "../hooks/use-media-query";
@@ -260,7 +261,9 @@ export interface ComboboxCore<V extends string | number> {
   rect: AnchorRect | null;
   /** Where the dropdown goes, clamped to the visible viewport (feedback #135). */
   placement: AnchoredPanel;
-  cacheRef: RefObject<Map<V, ComboOption<V>>>;
+  /** Put an option in the label cache, so {@link ComboboxCore.resolve} still knows a
+   *  value the caller just chose after the result list has moved on. */
+  rememberOption: (o: ComboOption<V>) => void;
   resolve: (v: V) => ComboOption<V> | null;
   /** Close and hand focus back to the trigger — the keyboard paths only. See
    *  {@link useDropdown} for why a pointer dismissal must not do this. */
@@ -318,10 +321,23 @@ export function useComboboxCore<V extends string | number>({
   useOutsideClick([triggerRef, panelRef], close, open && !isPhone);
   useEscapeKey(closeToTrigger, open);
 
-  // Reset the query + focus the search box each time the panel opens.
+  // Reset the query each time the panel opens, and the highlighted row whenever the
+  // visible set changes (a new query, or the panel opening or closing). Adjusted while
+  // rendering against the previous values rather than in an effect, so the render that
+  // opens the panel already searches for "" and highlights the first row.
+  const [prevOpen, setPrevOpen] = useState(open);
+  const [prevQuery, setPrevQuery] = useState(query);
+  if (open !== prevOpen || query !== prevQuery) {
+    const opened = open && !prevOpen;
+    setPrevOpen(open);
+    setPrevQuery(opened ? "" : query);
+    if (opened) setQuery("");
+    setActive(0);
+  }
+
+  // Focus the search box each time the panel opens.
   useEffect(() => {
     if (!open) return;
-    setQuery("");
     const id = requestAnimationFrame(() => inputRef.current?.focus());
     return () => cancelAnimationFrame(id);
   }, [open]);
@@ -345,11 +361,9 @@ export function useComboboxCore<V extends string | number>({
   }, [options, results]);
   const resolve = (v: V): ComboOption<V> | null =>
     options?.find((o) => o.value === v) ?? cacheRef.current.get(v) ?? null;
-
-  // Reset the highlighted row whenever the visible set changes.
-  useEffect(() => {
-    setActive(0);
-  }, [query, open]);
+  const rememberOption = (o: ComboOption<V>) => {
+    cacheRef.current.set(o.value, o);
+  };
 
   return {
     triggerRef,
@@ -368,7 +382,7 @@ export function useComboboxCore<V extends string | number>({
     minChars,
     rect,
     placement,
-    cacheRef,
+    rememberOption,
     resolve,
     closeToTrigger,
   };
@@ -636,6 +650,10 @@ export function ComboboxPanel<V extends string | number>({
       // The rows are provisional while a lookup is in flight — whether or not the
       // previous query's are still showing.
       aria-busy={busy || undefined}
+      // It scrolls, and says so where jsdom can see it (see `CLIPS_ATTRIBUTE`): a
+      // Tooltip in a row then portals out in a test exactly as it does in the
+      // browser, instead of joining the option's accessible name (keksdose E8).
+      {...{ [CLIPS_ATTRIBUTE]: "" }}
       className={cn("min-h-0 flex-1 overflow-y-auto py-1", isPhone && "flex-none")}
     >
       {results.map((o, i) => {
@@ -772,6 +790,9 @@ export function ComboboxPanel<V extends string | number>({
         inputRef={inputRef}
         closeLabel={closeLabel}
       >
+        {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused
+            itself: it catches the listbox keys bubbling from the sheet's search <input>,
+            which holds focus while the list is up. */}
         <div onKeyDown={onKeyDown} className="relative">
           {list}
           {announcement}
@@ -791,6 +812,9 @@ export function ComboboxPanel<V extends string | number>({
       : { left: rect.left };
 
   return createPortal(
+    /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused
+       itself: it catches the listbox keys bubbling from the search <input> inside it,
+       which holds focus while the panel is open. */
     <div
       // Spread FIRST: `onKeyDown` below is the listbox keyboard (Up/Down/Home/End/
       // Enter/Tab) and the placement is measured rather than chosen, so neither is a

package/src/components/combobox.tsx

@@ -113,7 +113,7 @@ function SuggestionList({
       dir={dir}
       style={{ top, left: rect.left, width: rect.width }}
     >
-      <ul id={id} role="listbox" className={LIST_CLASS} style={{ maxHeight }}>
+      <ul id={id} role="listbox" data-clips="" className={LIST_CLASS} style={{ maxHeight }}>
         {children}
       </ul>
     </div>,
@@ -238,9 +238,19 @@ export function Combobox({
   onBlur,
   onSubmit,
   "aria-label": ariaLabel,
+  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+  // on the wrapper div the hint and required state described nothing.
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: ComboboxProps) {
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy,
+  );
   const generated = useId();
   const fieldId = id ?? generated;
   // Derived from the GENERATED id, never from `id`: a caller's id is theirs to
@@ -366,9 +376,9 @@ export function Combobox({
       : null;
 
   return (
-    // `rest` dresses the outer box — a `data-tour` anchor, a test id, a form-level
-    // `aria-describedby`. Not the NAME: that belongs on the <input> below, which is
-    // the combobox a reader meets. Spread FIRST, so the field's ARIA and the
+    // `rest` dresses the outer box — a `data-tour` anchor, a test id. Not the NAME,
+    // description, invalid or required state: those belong on the <input> below,
+    // which is the combobox a reader meets. Spread FIRST, so the field's ARIA and the
     // handlers carrying live #309 and dev#549 cannot be replaced from outside.
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> since lenkbank's tests met a field `getByLabelText` could
@@ -407,8 +417,10 @@ export function Combobox({
           aria-autocomplete="list"
           aria-invalid={field.isInvalid || undefined}
           aria-describedby={field.describedBy}
+          aria-required={ariaRequired}
           autoComplete="off"
           disabled={disabled}
+          // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
           autoFocus={autoFocus}
           onBlur={onBlur}
           onMouseDown={primaryOnly.onMouseDown}
@@ -729,12 +741,22 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   invalid,
   error,
   "aria-label": ariaLabel,
+  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+  // on the wrapper div the hint and required state described nothing.
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: InlineEntityComboboxProps<V, C>) {
   // The clear value reads as "nothing selected", whichever one the caller picked —
   // so from here down `value` is the id or `null`, as it always was.
   const value: V | null = rawValue == null || rawValue === clearValue ? null : (rawValue as V);
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy,
+  );
   const generated = useId();
   const fieldId = id ?? generated;
   // See the twin above on why these hang off the generated id.
@@ -853,9 +875,9 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   };
 
   return (
-    // `rest` dresses the outer box — a `data-tour` anchor, a test id, a form-level
-    // `aria-describedby`. Not the NAME: that belongs on the <input> below, which is
-    // the combobox a reader meets. Spread FIRST, so the field's ARIA and the
+    // `rest` dresses the outer box — a `data-tour` anchor, a test id. Not the NAME,
+    // description, invalid or required state: those belong on the <input> below,
+    // which is the combobox a reader meets. Spread FIRST, so the field's ARIA and the
     // handlers carrying live #309 and dev#549 cannot be replaced from outside.
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> — see {@link Combobox}. */}
@@ -889,8 +911,10 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
           aria-autocomplete="list"
           aria-invalid={field.isInvalid || undefined}
           aria-describedby={field.describedBy}
+          aria-required={ariaRequired}
           autoComplete="off"
           disabled={disabled}
+          // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
           autoFocus={autoFocus}
           // `inputMode="none"` rather than readOnly, for the same reason Combobox
           // above gives: the sheet carries the keyboard, and a readOnly field would

package/src/components/copy-button.tsx

@@ -56,7 +56,8 @@ export interface CopyButtonProps
   stopPropagation?: boolean;
   /** Icon variant only: where the result tooltip opens. */
   tooltipSide?: TooltipSide;
-  /** Pass through to the tooltip — needed inside a scroll container (see Tooltip). */
+  /** Pass through to the tooltip. Left unset, the Tooltip decides on its own — it
+   *  portals inside a clipping container (a DataTable's `data-clips` scroller). */
   tooltipPortal?: boolean;
   /** ms until the button returns to idle. Default 2000. */
   resetAfter?: number;
@@ -93,7 +94,7 @@ export function CopyButton({
   tone,
   stopPropagation,
   tooltipSide = "top",
-  tooltipPortal = false,
+  tooltipPortal,
   resetAfter = 2000,
   onCopied,
   labels,

package/src/components/data-table-cells.tsx

@@ -0,0 +1,119 @@
+import type { ReactNode } from "react";
+import { Check, Minus, X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_DATA_TABLE_LABELS, type DataTableLabels } from "./data-table-labels";
+import type { DataTableColumn } from "./data-table";
+
+export interface BooleanMarkProps {
+  /** `true` → a check, `false` → a cross (or a dash, see `falseAs`), `null` /
+   *  `undefined` → a dash. */
+  value: boolean | null | undefined;
+  /**
+   * How `false` is drawn. `"cross"` (default) when "no" is news worth seeing — a
+   * failed check, a missing document. `"dash"` for a column that is mostly `false` and
+   * reads as a list of the `true` ones (kastlan's BoolCell): a column of crosses is
+   * noise. The screen-reader text says "No" either way.
+   */
+  falseAs?: "cross" | "dash";
+  /** The spoken words, over `dataTable.booleanTrue` / `booleanFalse` / `booleanUnset`
+   *  from `<UiKitProvider labels>`. */
+  labels?: Partial<Pick<DataTableLabels, "booleanTrue" | "booleanFalse" | "booleanUnset">>;
+  className?: string;
+}
+
+/**
+ * A yes/no value in a table cell: a green check, a muted cross, or a faint dash for
+ * "not set" — with the word for a screen reader, since a glyph alone is announced as
+ * nothing at all (or as "image").
+ *
+ * kastlan's `BoolCell` (shared/components/data-table/bool-cell.tsx) drew the icons with
+ * no text, so a reader walking the table heard an empty cell for every row; the apps'
+ * Yes/No chips were the other answer, and too loud for a column of them.
+ */
+export function BooleanMark({ value, falseAs = "cross", labels: labelsProp, className }: BooleanMarkProps) {
+  const labels = useKitLabels("dataTable", DEFAULT_DATA_TABLE_LABELS, labelsProp);
+  const state = value === true ? "true" : value === false ? "false" : "unset";
+  const text =
+    state === "true" ? labels.booleanTrue : state === "false" ? labels.booleanFalse : labels.booleanUnset;
+  const Icon = state === "true" ? Check : state === "false" && falseAs === "cross" ? X : Minus;
+  return (
+    <span data-value={state} className={cn("inline-flex items-center align-middle", className)}>
+      <Icon
+        aria-hidden
+        className={cn(
+          "size-4",
+          state === "true"
+            ? "text-[var(--success)]"
+            : state === "false" && falseAs === "cross"
+              ? "text-[var(--text-muted)]"
+              : "text-[var(--text-placeholder)]",
+        )}
+      />
+      <span className="sr-only">{text}</span>
+    </span>
+  );
+}
+
+export interface BooleanColumnOptions<T> {
+  key: string;
+  header: ReactNode;
+  /** The value of this row. */
+  value: (row: T) => boolean | null | undefined;
+  /** See {@link BooleanMarkProps.falseAs}. */
+  falseAs?: "cross" | "dash";
+  /** Sortable, `true` first on the first click (a column is sorted to find the yes
+   *  rows). Default true. */
+  sortable?: boolean;
+  /**
+   * A select filter over the column, with these option labels — pass them translated.
+   * Omitted: no filter. The option values are `"true"` / `"false"` (and `"unset"` when
+   * `unset` is given), which is also what `filterHref` takes for this column.
+   */
+  filterOptions?: { true: string; false: string; unset?: string };
+  /** Further column settings (`mobileHidden`, `headClassName`, …), merged over. */
+  column?: Partial<DataTableColumn<T>>;
+}
+
+/**
+ * A {@link DataTableColumn} for a yes/no field: {@link BooleanMark} cells,
+ * sortable with `true` first, and optionally a Yes/No select filter.
+ */
+export function booleanColumn<T>({
+  key,
+  header,
+  value,
+  falseAs,
+  sortable = true,
+  filterOptions,
+  column,
+}: BooleanColumnOptions<T>): DataTableColumn<T> {
+  const asKey = (row: T) => {
+    const v = value(row);
+    return v === true ? "true" : v === false ? "false" : "unset";
+  };
+  return {
+    key,
+    header,
+    cell: (row) => <BooleanMark value={value(row)} falseAs={falseAs} />,
+    // 0 for yes, 1 for no, null for unset (which the table sorts last either way).
+    sortBy: sortable
+      ? (row) => {
+          const v = value(row);
+          return v == null ? null : v ? 0 : 1;
+        }
+      : undefined,
+    filter: filterOptions
+      ? {
+          type: "select",
+          getValue: asKey,
+          options: [
+            { value: "true", label: filterOptions.true },
+            { value: "false", label: filterOptions.false },
+            ...(filterOptions.unset !== undefined ? [{ value: "unset", label: filterOptions.unset }] : []),
+          ],
+        }
+      : undefined,
+    ...column,
+  };
+}

package/src/components/data-table-filter-popover.tsx

@@ -1,3 +1,4 @@
+import { useCallback } from "react";
 import { X } from "lucide-react";
 import { cn } from "../lib/cn";
 import { MiniCalendar } from "./mini-calendar";
@@ -53,6 +54,15 @@ export function FilterPopover<T>({
   // No `"en"` fallback any more: that pinned the calendar to English in a table that
   // was never handed a locale, under a provider that had one.
   const locale = useKitLocale(localeProp);
+  // What `autoFocus` did, done by hand: a callback ref runs in the same commit phase
+  // React's own autofocus does, once when the input mounts (it is stable across
+  // renders, so a re-render does not re-take focus).
+  const focusOnMount = useCallback(
+    (el: HTMLInputElement | null) => {
+      if (el && autoFocus) el.focus();
+    },
+    [autoFocus],
+  );
   const filter = resolveFilter(column);
   if (!filter) return null;
 
@@ -80,11 +90,9 @@ export function FilterPopover<T>({
         <input
           type="text"
           // A prop now, defaulting to what the popover needs; see `autoFocus` on the
-          // props above. Deliberately NOT an eslint-disable: `jsx-a11y/no-autofocus` is
-          // one of the config's ratcheted warnings and this is still one of the four it
-          // counts, because the default here is still to take focus. Silencing it would
-          // shrink the backlog without emptying it.
-          autoFocus={autoFocus}
+          // props above. Focused by `focusOnMount` rather than the `autoFocus`
+          // attribute, because here taking focus is the default, not an opt-in.
+          ref={focusOnMount}
           value={v.q}
           onChange={(e) => onChange({ type: "text", q: e.target.value })}
           placeholder={labels.filterPlaceholder}

package/src/components/data-table-filters.ts

@@ -174,3 +174,80 @@ export function decodeFilterValueOfType(type: FilterValue["type"], raw: string):
 export function decodeFilterValue<T>(filter: ColumnFilter<T>, raw: string): FilterValue {
   return decodeFilterValueOfType(filter.type, raw);
 }
+
+// ---------- Filter builders ----------
+//
+// Terse builders for `DataTableColumn.filter`, lifted from kastlan's column-filters.ts,
+// which every converted list page imports. The one that earns its keep is `selectFilter`:
+// in `serverPagination` mode a select filter MUST declare its options (the table would
+// otherwise derive them from the rows of the page on screen), and the options an app has
+// to hand are usually a translated `{ value: label }` map.
+
+/** A free-text filter over `getValue`. */
+export function textFilter<T>(getValue: (row: T) => string): ColumnFilter<T> {
+  return { type: "text", getValue };
+}
+
+/**
+ * A multi-select filter. `options` is an options array, or a `{ value: label }` record
+ * (a translated status map) — kept in its key order. Left out, the table derives the
+ * options from the rows it holds.
+ */
+export function selectFilter<T>(
+  getValue: (row: T) => string,
+  options?: { value: string; label?: string }[] | Record<string, string>,
+): ColumnFilter<T> {
+  const opts = Array.isArray(options)
+    ? options
+    : options
+      ? Object.entries(options).map(([value, label]) => ({ value, label }))
+      : undefined;
+  return { type: "select", getValue, options: opts };
+}
+
+/** A from/to date filter over an ISO date (or date-time) string. */
+export function dateFilter<T>(getValue: (row: T) => string | null | undefined): ColumnFilter<T> {
+  return { type: "date", getValue };
+}
+
+/** A min/max (and absolute-value) filter over a number. */
+export function numberFilter<T>(getValue: (row: T) => number | null | undefined): ColumnFilter<T> {
+  return { type: "number", getValue };
+}
+
+/**
+ * A link to a list page with one column filter already applied — in the table's own URL
+ * scheme (`f.<column>=<encoded>`), which a table with `urlSync` (or
+ * {@link useTableUrlState}) reads on mount. kastlan's `buildListUrl`, which had to
+ * restate the `f.` prefix to do it.
+ *
+ * `value` is a string for a text filter, an array for a select filter, or any
+ * {@link FilterValue}. A filter that narrows nothing returns `path` unchanged. A `path`
+ * that already carries a query keeps it; a `#fragment` stays at the end.
+ *
+ *     filterHref("/units", "status", ["vacant"]) // "/units?f.status=vacant"
+ */
+export function filterHref(
+  path: string,
+  column: string,
+  value: string | string[] | FilterValue,
+  /** The target table's `urlSync` prefix, if it has one (`{ prefix: "inv." }` →
+   *  `inv.f.<column>`). */
+  options?: { prefix?: string },
+): string {
+  const state: FilterValue =
+    typeof value === "string"
+      ? { type: "text", q: value }
+      : Array.isArray(value)
+        ? { type: "select", values: value }
+        : value;
+  const encoded = encodeFilterValue(state);
+  if (encoded == null) return path;
+  const hashAt = path.indexOf("#");
+  const base = hashAt >= 0 ? path.slice(0, hashAt) : path;
+  const hash = hashAt >= 0 ? path.slice(hashAt) : "";
+  const queryAt = base.indexOf("?");
+  const params = new URLSearchParams(queryAt >= 0 ? base.slice(queryAt + 1) : "");
+  params.set(`${options?.prefix ?? ""}f.${column}`, encoded);
+  return `${queryAt >= 0 ? base.slice(0, queryAt) : base}?${params.toString()}${hash}`;
+}