@voila.dev/ui-filter 1.1.9

package/README.md

@@ -0,0 +1,72 @@
+# @voila.dev/ui-filter
+
+Composable, responsive list filters: a screen declares which fields are
+filterable, and this package renders the editor, the active-filter chips and the
+search-shaped trigger that opens them — so every admin list filters the same way.
+
+## Usage
+
+```tsx
+import { FilterBar } from "@voila.dev/ui-filter/components/filter-bar";
+import type { FilterDefinition, FilterValues } from "@voila.dev/ui-filter/types";
+
+const definitions: ReadonlyArray<FilterDefinition> = [
+  { kind: "text", key: "recipient", label: "Recipient", allowExclusion: true },
+  {
+    kind: "select",
+    key: "status",
+    label: "Status",
+    multiple: true,
+    options: [
+      { value: "sent", label: "Sent" },
+      { value: "failed", label: "Failed" },
+    ],
+  },
+  { kind: "dateRange", key: "sentAt", label: "Sent" },
+  { kind: "moneyRange", key: "price", label: "Price", currency: "EUR" },
+];
+
+<FilterBar
+  definitions={definitions}
+  values={values}
+  onValuesChange={setValues}
+  searchValue={search}
+  onSearchChange={setSearch}
+  resultCount={total}
+  labels={{ trigger: m.filters_trigger(), /* … */ }}
+  locale="fr-FR"
+/>;
+```
+
+## Kinds
+
+| kind          | value                       | exclusion |
+| ------------- | --------------------------- | --------- |
+| `text`        | `{ text, excluded? }`       | yes       |
+| `number`      | `{ number }`                | no        |
+| `numberRange` | `{ min?, max? }`            | no        |
+| `moneyRange`  | `{ min?, max? }` (cents)    | no        |
+| `select`      | `{ values[], excluded? }`   | yes       |
+| `dateRange`   | `{ from?, to? }` (ISO days) | no        |
+| `boolean`     | `{ value }`                 | n/a       |
+
+`FilterValues` never holds an empty filter: clearing a field removes its key, so
+`Object.keys(values).length` is the active count and the record round-trips to a
+query string unchanged.
+
+## Conventions
+
+- **Responsive by construction.** The editor is a centered dialog on desktop and
+  a bottom drawer under 768px; date bounds are the calendar popover on desktop
+  and the OS picker on mobile.
+- **Draft, then apply.** Edits inside the panel are committed on "Apply" — a
+  filtered list refetches, and refetching per keystroke is neither fast nor
+  legible. Chips still remove a filter in one tap, outside the panel.
+- **No translations inside.** Every string comes from the `labels` prop
+  (`defaultFilterLabels` is English); apps pass their Paraglide messages.
+
+## Composition
+
+`FilterBar` is the assembled surface. Its parts are exported for screens that
+need a different arrangement: `FilterTrigger`, `FilterPanel`, `FilterForm`,
+`FilterField` and `FilterChips`.

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@voila.dev/ui-filter",
+	"version": "1.1.9",
+	"type": "module",
+	"description": "Composable filters that survive real product requirements — including geo.",
+	"license": "MIT",
+	"homepage": "https://ui.voila.dev/components/filter-bar",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/voila-voila-dev/ui.git",
+		"directory": "packages/ui-filter"
+	},
+	"keywords": [
+		"react",
+		"filters",
+		"list",
+		"faceted-search",
+		"tailwindcss"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"!src/**/*.stories.ts",
+		"!src/**/*.stories.tsx"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		"./styles.css": "./src/styles.css",
+		"./types": "./src/types.ts",
+		"./lib/*": "./src/lib/*.ts",
+		"./components/*": "./src/components/*.tsx",
+		"./components/fields/*": "./src/components/fields/*.tsx"
+	},
+	"imports": {
+		"#/*": "./src/*"
+	},
+	"scripts": {
+		"check": "biome check",
+		"check-types": "tsc --noEmit",
+		"format": "biome format",
+		"lint": "biome lint",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@phosphor-icons/react": "2.1.10",
+		"@voila.dev/ui": "0.0.0",
+		"@voila.dev/ui-map": "0.0.0"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tailwindcss": "^4.0.0"
+	}
+}

package/src/components/fields/boolean-filter-field.tsx

@@ -0,0 +1,67 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import { FilterFieldFrame } from "#/components/fields/field-frame.tsx";
+import type {
+	BooleanFilterDefinition,
+	BooleanFilterValue,
+	FilterLabels,
+} from "#/types.ts";
+
+/**
+ * Three states, not two: yes, no, and "any" (the filter unset). A switch can
+ * only say yes/no, which silently turns "I don't care" into "must be false" —
+ * so the third state gets its own segment.
+ */
+export function BooleanFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: BooleanFilterDefinition;
+	readonly value: BooleanFilterValue | undefined;
+	readonly onValueChange: (value: BooleanFilterValue | undefined) => void;
+	readonly labels: FilterLabels;
+}) {
+	const states: ReadonlyArray<{ key: string; label: string; set?: boolean }> = [
+		{ key: "any", label: labels.any },
+		{ key: "true", label: definition.trueLabel, set: true },
+		{ key: "false", label: definition.falseLabel, set: false },
+	];
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			labels={labels}
+		>
+			<fieldset className="inline-flex w-full items-center gap-1 rounded-full bg-muted p-1 sm:w-auto">
+				<legend className="sr-only">{definition.label}</legend>
+				{states.map((state) => {
+					const active = value?.value === state.set;
+					return (
+						<button
+							key={state.key}
+							type="button"
+							aria-pressed={active}
+							onClick={() =>
+								onValueChange(
+									state.set === undefined
+										? undefined
+										: { kind: "boolean", value: state.set },
+								)
+							}
+							className={cn(
+								"flex-1 cursor-pointer rounded-full px-3 py-1 text-sm transition-colors sm:flex-none",
+								active
+									? "bg-background font-medium text-foreground shadow-xs"
+									: "text-muted-foreground hover:text-foreground",
+							)}
+						>
+							{state.label}
+						</button>
+					);
+				})}
+			</fieldset>
+		</FilterFieldFrame>
+	);
+}

package/src/components/fields/date-range-filter-field.tsx

@@ -0,0 +1,135 @@
+import { DatePicker } from "@voila.dev/ui/components/date-picker";
+import { NativeDatePicker } from "@voila.dev/ui/components/native-date-picker";
+import { useIsMobile } from "@voila.dev/ui/hooks/use-mobile";
+import { useId } from "react";
+import {
+	FilterFieldFrame,
+	FilterRangeRow,
+} from "#/components/fields/field-frame.tsx";
+import type {
+	DateRangeFilterDefinition,
+	DateRangeFilterValue,
+	FilterLabels,
+} from "#/types.ts";
+
+// Bounds are `YYYY-MM-DD` strings: that is what a native date input reads and
+// writes, what a query string carries, and what survives a time zone unchanged.
+const toIsoDay = (date: Date): string => {
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${date.getFullYear()}-${month}-${day}`;
+};
+
+const fromIsoDay = (isoDate: string | undefined): Date | null => {
+	if (isoDate === undefined) return null;
+	const parsed = new Date(`${isoDate}T00:00:00`);
+	return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+
+/**
+ * One bound, on the surface that suits the device: the calendar popover on
+ * desktop, the OS date picker under the mobile breakpoint.
+ */
+function DateBoundField({
+	id,
+	value,
+	onValueChange,
+	placeholder,
+	min,
+	max,
+	locale,
+}: {
+	readonly id?: string;
+	readonly value: string | undefined;
+	readonly onValueChange: (isoDate: string | undefined) => void;
+	readonly placeholder: string;
+	readonly min?: string;
+	readonly max?: string;
+	readonly locale: string;
+}) {
+	const isMobile = useIsMobile();
+
+	if (isMobile) {
+		return (
+			<NativeDatePicker
+				id={id}
+				wrapperClassName="w-full"
+				aria-label={placeholder}
+				value={value ?? ""}
+				min={min}
+				max={max}
+				onChange={(event) =>
+					onValueChange(
+						event.target.value === "" ? undefined : event.target.value,
+					)
+				}
+			/>
+		);
+	}
+
+	return (
+		<DatePicker
+			id={id}
+			className="w-full"
+			locale={locale}
+			placeholder={placeholder}
+			aria-label={placeholder}
+			value={fromIsoDay(value)}
+			onValueChange={(date) =>
+				onValueChange(date === null ? undefined : toIsoDay(date))
+			}
+		/>
+	);
+}
+
+/** A start and an end date, either of which may be left open. */
+export function DateRangeFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+	locale,
+}: {
+	readonly definition: DateRangeFilterDefinition;
+	readonly value: DateRangeFilterValue | undefined;
+	readonly onValueChange: (value: DateRangeFilterValue) => void;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+}) {
+	const controlId = useId();
+	const isEmpty = value?.from === undefined && value?.to === undefined;
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={controlId}
+			labels={labels}
+			onClear={isEmpty ? undefined : () => onValueChange({ kind: "dateRange" })}
+		>
+			<FilterRangeRow>
+				<DateBoundField
+					id={controlId}
+					value={value?.from}
+					placeholder={labels.from}
+					min={definition.min}
+					max={value?.to ?? definition.max}
+					locale={locale}
+					onValueChange={(from) =>
+						onValueChange({ kind: "dateRange", from, to: value?.to })
+					}
+				/>
+				<DateBoundField
+					value={value?.to}
+					placeholder={labels.to}
+					min={value?.from ?? definition.min}
+					max={definition.max}
+					locale={locale}
+					onValueChange={(to) =>
+						onValueChange({ kind: "dateRange", from: value?.from, to })
+					}
+				/>
+			</FilterRangeRow>
+		</FilterFieldFrame>
+	);
+}

package/src/components/fields/field-frame.tsx

@@ -0,0 +1,130 @@
+import { XIcon } from "@phosphor-icons/react";
+import { Button } from "@voila.dev/ui/components/button";
+import { cn } from "@voila.dev/ui/lib/utils";
+import type { ReactNode } from "react";
+import type { FilterLabels } from "#/types.ts";
+
+/**
+ * The chrome every filter field shares: a label row that also hosts the
+ * "is / is not" switch and the clear action, then the control itself. One frame
+ * for all kinds is what makes a screenful of mixed filters read as one thing.
+ */
+export function FilterFieldFrame({
+	label,
+	description,
+	controlId,
+	operator,
+	onClear,
+	labels,
+	children,
+}: {
+	readonly label: string;
+	readonly description?: string;
+	/**
+	 * Ties the visible label to the control it names. Omitted by the group
+	 * fields (a `<label>` would otherwise rename their first button), which name
+	 * themselves through their fieldset legend.
+	 */
+	readonly controlId?: string;
+	/** The "is / is not" switch, when the field supports exclusion. */
+	readonly operator?: ReactNode;
+	/** Omitted while the field is empty — nothing to clear. */
+	readonly onClear?: () => void;
+	readonly labels: FilterLabels;
+	readonly children: ReactNode;
+}) {
+	return (
+		<div className="flex min-w-0 flex-col gap-2" data-slot="filter-field">
+			{/* `min-h-9` is the clear button's height: the row reserves it whether or
+			    not the button is there, so filling a field doesn't shove the one
+			    below it down. */}
+			<div className="flex min-h-9 flex-wrap items-center gap-x-3 gap-y-1">
+				<label
+					htmlFor={controlId}
+					className="font-medium text-foreground text-sm"
+				>
+					{label}
+				</label>
+				{operator}
+				{onClear !== undefined && (
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						className="ml-auto text-muted-foreground"
+						onClick={onClear}
+					>
+						<XIcon />
+						{labels.clear}
+					</Button>
+				)}
+			</div>
+			{description !== undefined && (
+				<p className="text-muted-foreground text-xs">{description}</p>
+			)}
+			{children}
+		</div>
+	);
+}
+
+/**
+ * The inversion switch: two segments, "is" and "is not". A checkbox reads as
+ * an option you might miss; two segments state the operator outright, which is
+ * what an exclusion filter has to do to be trusted.
+ */
+export function FilterOperatorToggle({
+	excluded,
+	onExcludedChange,
+	labels,
+	disabled = false,
+}: {
+	readonly excluded: boolean;
+	readonly onExcludedChange: (excluded: boolean) => void;
+	readonly labels: FilterLabels;
+	/**
+	 * An empty field has nothing to invert — "is not <nothing>" filters nothing —
+	 * so the switch stays inert until the field holds a value.
+	 */
+	readonly disabled?: boolean;
+}) {
+	return (
+		<fieldset
+			data-slot="filter-operator"
+			disabled={disabled}
+			className={cn(
+				"inline-flex items-center gap-0.5 rounded-full bg-muted p-1",
+				disabled && "opacity-50",
+			)}
+		>
+			<legend className="sr-only">{`${labels.is} / ${labels.isNot}`}</legend>
+			{[false, true].map((isExcluded) => (
+				<button
+					key={String(isExcluded)}
+					type="button"
+					// Also on the button, not only the fieldset: assistive tech and
+					// tests read the property, which a fieldset does not propagate.
+					disabled={disabled}
+					aria-pressed={excluded === isExcluded}
+					onClick={() => onExcludedChange(isExcluded)}
+					// Segments are thumb-sized (min 44px wide, 28px tall inside a 36px
+					// row): the earlier text-xs pills were a mouse-only target.
+					className={cn(
+						"min-h-7 min-w-11 cursor-pointer rounded-full px-3 text-sm transition-colors disabled:cursor-not-allowed",
+						excluded === isExcluded
+							? "bg-background font-medium text-foreground shadow-xs"
+							: "text-muted-foreground hover:text-foreground",
+					)}
+				>
+					{isExcluded ? labels.isNot : labels.is}
+				</button>
+			))}
+		</fieldset>
+	);
+}
+
+/** Two bounds side by side — the layout shared by every range field. */
+export function FilterRangeRow({ children }: { readonly children: ReactNode }) {
+	return (
+		<div className="grid grid-cols-1 gap-2 sm:grid-cols-2">{children}</div>
+	);
+}

package/src/components/fields/geo-radius-filter-field.tsx

@@ -0,0 +1,215 @@
+import { MapPinIcon, SpinnerGapIcon } from "@phosphor-icons/react";
+import { Button } from "@voila.dev/ui/components/button";
+import { Input } from "@voila.dev/ui/components/input";
+import { Slider } from "@voila.dev/ui/components/slider";
+import { RadiusMap } from "@voila.dev/ui-map/components/radius-map";
+import { useEffect, useId, useState } from "react";
+import { FilterFieldFrame } from "#/components/fields/field-frame.tsx";
+import type {
+	FilterLabels,
+	GeoRadiusFilterDefinition,
+	GeoRadiusFilterValue,
+	PlaceSuggestion,
+} from "#/types.ts";
+
+const DEFAULT_MIN_KM = 5;
+const DEFAULT_MAX_KM = 200;
+const DEFAULT_STEP_KM = 5;
+const DEFAULT_RADIUS_KM = 30;
+const SEARCH_DEBOUNCE_MS = 300;
+
+/** Debounced place lookup: a keystroke is not a query. */
+function usePlaceSearch(
+	query: string,
+	searchPlaces: GeoRadiusFilterDefinition["searchPlaces"],
+): {
+	readonly results: ReadonlyArray<PlaceSuggestion>;
+	readonly busy: boolean;
+} {
+	const [results, setResults] = useState<ReadonlyArray<PlaceSuggestion>>([]);
+	const [busy, setBusy] = useState(false);
+
+	useEffect(() => {
+		const trimmed = query.trim();
+		if (trimmed.length < 2) {
+			setResults([]);
+			setBusy(false);
+			return;
+		}
+		setBusy(true);
+		let cancelled = false;
+		const handle = setTimeout(() => {
+			searchPlaces(trimmed)
+				.then((found) => {
+					if (!cancelled) {
+						setResults(found);
+					}
+				})
+				.catch(() => {
+					if (!cancelled) {
+						setResults([]);
+					}
+				})
+				.finally(() => {
+					if (!cancelled) {
+						setBusy(false);
+					}
+				});
+		}, SEARCH_DEBOUNCE_MS);
+		return () => {
+			cancelled = true;
+			clearTimeout(handle);
+		};
+	}, [query, searchPlaces]);
+
+	return { results, busy };
+}
+
+function PlaceResults({
+	results,
+	busy,
+	query,
+	labels,
+	onPick,
+}: {
+	readonly results: ReadonlyArray<PlaceSuggestion>;
+	readonly busy: boolean;
+	readonly query: string;
+	readonly labels: FilterLabels;
+	readonly onPick: (place: PlaceSuggestion) => void;
+}) {
+	if (busy) {
+		return (
+			<p className="flex items-center gap-2 text-muted-foreground text-sm">
+				<SpinnerGapIcon className="size-4 animate-spin" />
+				{labels.search}
+			</p>
+		);
+	}
+	if (query.trim().length >= 2 && results.length === 0) {
+		return (
+			<p className="text-muted-foreground text-sm">{labels.placeNoResults}</p>
+		);
+	}
+	return (
+		<ul className="flex flex-col gap-1">
+			{results.map((place) => (
+				<li key={place.id}>
+					<button
+						type="button"
+						onClick={() => onPick(place)}
+						className="flex w-full cursor-pointer items-center gap-2 rounded-lg px-2 py-2 text-left text-sm transition-colors hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-2"
+					>
+						<MapPinIcon className="size-4 shrink-0 text-muted-foreground" />
+						<span className="truncate">{place.label}</span>
+					</button>
+				</li>
+			))}
+		</ul>
+	);
+}
+
+/**
+ * "Within N km of somewhere": pick a place, then size the circle. The map is
+ * the answer to "is that the area I meant?" — a lat/lon pair and a number are
+ * not something anyone can picture.
+ */
+export function GeoRadiusFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: GeoRadiusFilterDefinition;
+	readonly value: GeoRadiusFilterValue | undefined;
+	readonly onValueChange: (value: GeoRadiusFilterValue | undefined) => void;
+	readonly labels: FilterLabels;
+}) {
+	const controlId = useId();
+	const [query, setQuery] = useState("");
+	const { results, busy } = usePlaceSearch(query, definition.searchPlaces);
+
+	const minKm = definition.minKm ?? DEFAULT_MIN_KM;
+	const maxKm = definition.maxKm ?? DEFAULT_MAX_KM;
+
+	if (value === undefined) {
+		return (
+			<FilterFieldFrame
+				label={definition.label}
+				description={definition.description}
+				controlId={controlId}
+				labels={labels}
+			>
+				<Input
+					id={controlId}
+					value={query}
+					placeholder={labels.placePlaceholder}
+					onChange={(event) => setQuery(event.target.value)}
+				/>
+				<PlaceResults
+					results={results}
+					busy={busy}
+					query={query}
+					labels={labels}
+					onPick={(place) => {
+						setQuery("");
+						onValueChange({
+							kind: "geoRadius",
+							place,
+							radiusKm: definition.defaultKm ?? DEFAULT_RADIUS_KM,
+						});
+					}}
+				/>
+			</FilterFieldFrame>
+		);
+	}
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			labels={labels}
+			onClear={() => onValueChange(undefined)}
+		>
+			<div className="flex items-center gap-2">
+				<MapPinIcon className="size-4 shrink-0 text-muted-foreground" />
+				<span className="min-w-0 flex-1 truncate text-sm">
+					{value.place.label}
+				</span>
+				<Button
+					type="button"
+					variant="ghost"
+					size="sm"
+					onClick={() => onValueChange(undefined)}
+				>
+					{labels.changePlace}
+				</Button>
+			</div>
+
+			<RadiusMap center={value.place} radiusKm={value.radiusKm} />
+
+			<div className="flex items-center gap-3">
+				<span className="shrink-0 text-muted-foreground text-sm">
+					{labels.radius}
+				</span>
+				<Slider
+					aria-label={labels.radius}
+					className="flex-1"
+					min={minKm}
+					max={maxKm}
+					step={definition.stepKm ?? DEFAULT_STEP_KM}
+					value={value.radiusKm}
+					onValueChange={(next) =>
+						onValueChange({
+							...value,
+							radiusKm: Array.isArray(next) ? (next[0] ?? minKm) : next,
+						})
+					}
+				/>
+				<span className="w-16 shrink-0 text-right text-sm tabular-nums">
+					{`${value.radiusKm} km`}
+				</span>
+			</div>
+		</FilterFieldFrame>
+	);
+}