@voila.dev/ui-filter 1.1.9

package/src/components/filter-field.tsx

@@ -0,0 +1,111 @@
+import { BooleanFilterField } from "#/components/fields/boolean-filter-field.tsx";
+import { DateRangeFilterField } from "#/components/fields/date-range-filter-field.tsx";
+import { GeoRadiusFilterField } from "#/components/fields/geo-radius-filter-field.tsx";
+import { MoneyRangeFilterField } from "#/components/fields/money-range-filter-field.tsx";
+import {
+	NumberFilterField,
+	NumberRangeFilterField,
+} from "#/components/fields/number-filter-field.tsx";
+import { SelectFilterField } from "#/components/fields/select-filter-field.tsx";
+import { TextFilterField } from "#/components/fields/text-filter-field.tsx";
+import type { FilterDefinition, FilterLabels, FilterValue } from "#/types.ts";
+
+/**
+ * Renders the editor a definition asks for. The value union is discriminated by
+ * the same `kind` as the definition, so each branch narrows both at once — a new
+ * filter kind is a compile error here until it has an editor.
+ */
+export function FilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+	locale,
+}: {
+	readonly definition: FilterDefinition;
+	readonly value: FilterValue | undefined;
+	readonly onValueChange: (value: FilterValue | undefined) => void;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+}) {
+	const valueOfKind = <Kind extends FilterValue["kind"]>(kind: Kind) =>
+		value?.kind === kind
+			? (value as Extract<FilterValue, { kind: Kind }>)
+			: undefined;
+
+	switch (definition.kind) {
+		case "text":
+			return (
+				<TextFilterField
+					definition={definition}
+					value={valueOfKind("text")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "number":
+			return (
+				<NumberFilterField
+					definition={definition}
+					value={valueOfKind("number")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "numberRange":
+			return (
+				<NumberRangeFilterField
+					definition={definition}
+					value={valueOfKind("numberRange")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "moneyRange":
+			return (
+				<MoneyRangeFilterField
+					definition={definition}
+					value={valueOfKind("moneyRange")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "select":
+			return (
+				<SelectFilterField
+					definition={definition}
+					value={valueOfKind("select")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "dateRange":
+			return (
+				<DateRangeFilterField
+					definition={definition}
+					value={valueOfKind("dateRange")}
+					onValueChange={onValueChange}
+					labels={labels}
+					locale={locale}
+				/>
+			);
+		case "geoRadius":
+			return (
+				<GeoRadiusFilterField
+					definition={definition}
+					value={valueOfKind("geoRadius")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+		case "boolean":
+			return (
+				<BooleanFilterField
+					definition={definition}
+					value={valueOfKind("boolean")}
+					onValueChange={onValueChange}
+					labels={labels}
+				/>
+			);
+	}
+}

package/src/components/filter-form.tsx

@@ -0,0 +1,43 @@
+import { Separator } from "@voila.dev/ui/components/separator";
+import { Fragment } from "react";
+import { FilterField } from "#/components/filter-field.tsx";
+import { setFilterValue } from "#/lib/filter-values.ts";
+import type { FilterDefinition, FilterLabels, FilterValues } from "#/types.ts";
+
+/**
+ * The editor: every declared filter, in declaration order, separated so a long
+ * panel stays scannable. It edits a whole `FilterValues` record — clearing a
+ * field removes its key, so the record never carries empty filters.
+ */
+export function FilterForm({
+	definitions,
+	values,
+	onValuesChange,
+	labels,
+	locale,
+}: {
+	readonly definitions: ReadonlyArray<FilterDefinition>;
+	readonly values: FilterValues;
+	readonly onValuesChange: (values: FilterValues) => void;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+}) {
+	return (
+		<div className="flex flex-col gap-5" data-slot="filter-form">
+			{definitions.map((definition, index) => (
+				<Fragment key={definition.key}>
+					{index > 0 && <Separator />}
+					<FilterField
+						definition={definition}
+						value={values[definition.key]}
+						locale={locale}
+						labels={labels}
+						onValueChange={(value) =>
+							onValuesChange(setFilterValue(values, definition.key, value))
+						}
+					/>
+				</Fragment>
+			))}
+		</div>
+	);
+}

package/src/components/filter-panel.tsx

@@ -0,0 +1,130 @@
+import { Button } from "@voila.dev/ui/components/button";
+import { Input } from "@voila.dev/ui/components/input";
+import {
+	ResponsiveDialog,
+	ResponsiveDialogBody,
+	ResponsiveDialogContent,
+	ResponsiveDialogDescription,
+	ResponsiveDialogFooter,
+	ResponsiveDialogHeader,
+	ResponsiveDialogTitle,
+} from "@voila.dev/ui/components/responsive-dialog";
+import { useEffect, useState } from "react";
+import { FilterForm } from "#/components/filter-form.tsx";
+import { countActiveFilters } from "#/lib/filter-values.ts";
+import type { FilterDefinition, FilterLabels, FilterValues } from "#/types.ts";
+
+/**
+ * The editor as an overlay: a centered dialog on desktop, a bottom drawer on
+ * mobile. Edits are a draft committed on "Apply" — a filtered list refetches,
+ * and refetching on every keystroke of a half-typed filter is both slower and
+ * harder to reason about than one deliberate commit. Dismissing discards.
+ */
+export function FilterPanel({
+	open,
+	onOpenChange,
+	definitions,
+	values,
+	onValuesChange,
+	labels,
+	locale,
+	searchValue,
+	onSearchChange,
+}: {
+	readonly open: boolean;
+	readonly onOpenChange: (open: boolean) => void;
+	readonly definitions: ReadonlyArray<FilterDefinition>;
+	readonly values: FilterValues;
+	/** Called once, on apply, with the committed record. */
+	readonly onValuesChange: (values: FilterValues) => void;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+	/** Free-text search, kept beside the filters when the list has one. */
+	readonly searchValue?: string;
+	readonly onSearchChange?: (value: string) => void;
+}) {
+	const [draft, setDraft] = useState<FilterValues>(values);
+	const [draftSearch, setDraftSearch] = useState(searchValue ?? "");
+
+	// Reopening starts from what is applied — including changes made meanwhile
+	// by removing a chip outside the panel.
+	useEffect(() => {
+		if (open) {
+			setDraft(values);
+			setDraftSearch(searchValue ?? "");
+		}
+	}, [open, values, searchValue]);
+
+	const apply = () => {
+		onValuesChange(draft);
+		onSearchChange?.(draftSearch);
+		onOpenChange(false);
+	};
+
+	const draftCount = countActiveFilters(draft);
+
+	return (
+		<ResponsiveDialog open={open} onOpenChange={onOpenChange}>
+			{/* No autofocus: the first field is the search box, and focusing it on
+			    open throws the phone keyboard over the filters you came to read. */}
+			{/* `overflow-hidden` on the shell leaves exactly one scroll container —
+			    the body below. The dialog half scrolls itself by default, which
+			    would stack a second scrollbar next to it. */}
+			<ResponsiveDialogContent
+				size="lg"
+				className="overflow-hidden"
+				closeButtonLabel={labels.close}
+				autoFocus={false}
+			>
+				<ResponsiveDialogHeader>
+					<ResponsiveDialogTitle>{labels.title}</ResponsiveDialogTitle>
+					{labels.description !== undefined && (
+						<ResponsiveDialogDescription>
+							{labels.description}
+						</ResponsiveDialogDescription>
+					)}
+				</ResponsiveDialogHeader>
+
+				{/* The scroll container would clip the focus ring of a field sitting
+				    against its edge (the search box does). The inset gutter gives the
+				    ring its room back without narrowing the fields — the mobile half
+				    already has `px-4` for that. */}
+				<ResponsiveDialogBody className="no-scrollbar flex max-h-[60vh] min-w-0 flex-col gap-5 overflow-x-hidden overflow-y-auto py-1 md:-mx-1 md:px-1">
+					{onSearchChange !== undefined && (
+						<Input
+							type="search"
+							aria-label={labels.search}
+							placeholder={labels.searchPlaceholder}
+							value={draftSearch}
+							onChange={(event) => setDraftSearch(event.target.value)}
+						/>
+					)}
+					<FilterForm
+						definitions={definitions}
+						values={draft}
+						onValuesChange={setDraft}
+						labels={labels}
+						locale={locale}
+					/>
+				</ResponsiveDialogBody>
+
+				<ResponsiveDialogFooter>
+					<Button
+						type="button"
+						variant="ghost"
+						disabled={draftCount === 0 && draftSearch === ""}
+						onClick={() => {
+							setDraft({});
+							setDraftSearch("");
+						}}
+					>
+						{labels.clearAll}
+					</Button>
+					<Button type="button" onClick={apply}>
+						{labels.apply}
+					</Button>
+				</ResponsiveDialogFooter>
+			</ResponsiveDialogContent>
+		</ResponsiveDialog>
+	);
+}

package/src/components/filter-trigger.tsx

@@ -0,0 +1,57 @@
+import {
+	MagnifyingGlassIcon,
+	SlidersHorizontalIcon,
+} from "@phosphor-icons/react";
+import { Badge } from "@voila.dev/ui/components/badge";
+import { cn } from "@voila.dev/ui/lib/utils";
+import type { FilterLabels } from "#/types.ts";
+
+/**
+ * The one control a filtered list shows at rest: a search-field-shaped button.
+ * It reads as a search box because searching is what people come to a list to
+ * do, and it carries the active-filter count so a filtered list never looks
+ * like a short one. Tapping it opens the editor.
+ */
+export function FilterTrigger({
+	summary,
+	activeCount,
+	labels,
+	className,
+	...props
+}: React.ComponentProps<"button"> & {
+	/** Current search text, or the placeholder when nothing is searched yet. */
+	readonly summary?: string;
+	readonly activeCount: number;
+	readonly labels: FilterLabels;
+}) {
+	return (
+		<button
+			type="button"
+			data-slot="filter-trigger"
+			aria-label={labels.trigger}
+			className={cn(
+				"flex h-9 w-full cursor-pointer items-center gap-2 rounded-lg border border-input bg-background px-3 text-left text-sm transition-colors hover:bg-accent focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-none dark:bg-input/30",
+				className,
+			)}
+			{...props}
+		>
+			<MagnifyingGlassIcon className="size-4 shrink-0 text-muted-foreground" />
+			<span
+				className={cn(
+					"truncate",
+					summary === undefined && "text-muted-foreground",
+				)}
+			>
+				{summary ?? labels.searchPlaceholder}
+			</span>
+			<span className="ml-auto flex shrink-0 items-center gap-2">
+				{activeCount > 0 && (
+					<Badge variant="default" size="sm">
+						{activeCount}
+					</Badge>
+				)}
+				<SlidersHorizontalIcon className="size-4 text-muted-foreground" />
+			</span>
+		</button>
+	);
+}

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+// Side-effect CSS imports (e.g. maplibre-gl's stylesheet) carry no type
+// declarations; the app bundlers get this from `vite/client`, but this package
+// typechecks standalone, so declare the module shape here.
+declare module "*.css" {}

package/src/lib/filter-values.ts

@@ -0,0 +1,217 @@
+import type {
+	BooleanFilterValue,
+	DateRangeFilterValue,
+	FilterDefinition,
+	FilterLabels,
+	FilterValue,
+	FilterValues,
+	MoneyRangeFilterValue,
+	NumberRangeFilterValue,
+	SelectFilterValue,
+} from "#/types.ts";
+
+/**
+ * Is this value worth keeping? An "empty" value (blank text, no selection, both
+ * range bounds missing) is indistinguishable from no filter at all, so the
+ * record drops it — that keeps the active count, the chips and the query in
+ * agreement without every caller re-deriving emptiness.
+ */
+export function isFilterValueEmpty(value: FilterValue): boolean {
+	switch (value.kind) {
+		case "text":
+			return value.text.trim() === "";
+		case "number":
+			return Number.isNaN(value.number);
+		case "numberRange":
+		case "moneyRange":
+			return value.min === undefined && value.max === undefined;
+		case "select":
+			return value.values.length === 0;
+		case "dateRange":
+			return value.from === undefined && value.to === undefined;
+		case "geoRadius":
+			return false;
+		case "boolean":
+			return false;
+	}
+}
+
+/** Set (or clear, when empty) one filter, returning a new record. */
+export function setFilterValue(
+	values: FilterValues,
+	key: string,
+	value: FilterValue | undefined,
+): FilterValues {
+	const next = { ...values };
+	if (value === undefined || isFilterValueEmpty(value)) {
+		delete next[key];
+	} else {
+		next[key] = value;
+	}
+	return next;
+}
+
+/** Drop one filter, returning a new record. */
+export function clearFilterValue(
+	values: FilterValues,
+	key: string,
+): FilterValues {
+	return setFilterValue(values, key, undefined);
+}
+
+/** How many filters are set — the badge on the trigger. */
+export function countActiveFilters(values: FilterValues): number {
+	return Object.keys(values).length;
+}
+
+const formatNumber = (value: number, locale: string): string =>
+	new Intl.NumberFormat(locale).format(value);
+
+const formatMoney = (
+	minorUnits: number,
+	currency: string,
+	locale: string,
+): string =>
+	new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency,
+		maximumFractionDigits: minorUnits % 100 === 0 ? 0 : 2,
+	}).format(minorUnits / 100);
+
+const formatDate = (isoDate: string, locale: string): string => {
+	const parsed = new Date(`${isoDate}T00:00:00`);
+	return Number.isNaN(parsed.getTime())
+		? isoDate
+		: new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(parsed);
+};
+
+/** `10 – 20`, `≥ 10`, `≤ 20` — the shape every range chip reads in. */
+function describeBounds(
+	min: string | undefined,
+	max: string | undefined,
+): string {
+	if (min !== undefined && max !== undefined) return `${min} – ${max}`;
+	if (min !== undefined) return `≥ ${min}`;
+	if (max !== undefined) return `≤ ${max}`;
+	return "";
+}
+
+/** What every describer needs beyond the value itself. */
+type DescribeContext = {
+	readonly definition: FilterDefinition;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+};
+
+const operatorOf = (
+	excluded: boolean | undefined,
+	{ labels }: DescribeContext,
+): string => (excluded === true ? labels.isNot : labels.is);
+
+/** A value kind can outlive the definition it was written against (a stale URL). */
+const unitOf = ({ definition }: DescribeContext): string =>
+	(definition.kind === "number" || definition.kind === "numberRange") &&
+	definition.unit !== undefined
+		? ` ${definition.unit}`
+		: "";
+
+function describeNumberRange(
+	value: NumberRangeFilterValue,
+	context: DescribeContext,
+): string {
+	const unit = unitOf(context);
+	const format = (bound: number | undefined) =>
+		bound === undefined
+			? undefined
+			: `${formatNumber(bound, context.locale)}${unit}`;
+	return describeBounds(format(value.min), format(value.max));
+}
+
+function describeMoneyRange(
+	value: MoneyRangeFilterValue,
+	{ definition, locale }: DescribeContext,
+): string {
+	const currency =
+		definition.kind === "moneyRange" ? definition.currency : "EUR";
+	const format = (bound: number | undefined) =>
+		bound === undefined ? undefined : formatMoney(bound, currency, locale);
+	return describeBounds(format(value.min), format(value.max));
+}
+
+function describeSelect(
+	value: SelectFilterValue,
+	context: DescribeContext,
+): string {
+	const { definition, labels } = context;
+	const options = definition.kind === "select" ? definition.options : [];
+	const labelOf = (optionValue: string) =>
+		options.find((option) => option.value === optionValue)?.label ??
+		optionValue;
+	// Beyond two selections the chip states the count: a chip is a summary, not
+	// a list, and the panel is one tap away for the detail.
+	const rendered =
+		value.values.length > 2
+			? labels.selectedCount(value.values.length)
+			: value.values.map(labelOf).join(", ");
+	return `${definition.label} ${operatorOf(value.excluded, context)} ${rendered}`;
+}
+
+function describeBoolean(
+	value: BooleanFilterValue,
+	{ definition }: DescribeContext,
+): string {
+	if (definition.kind !== "boolean") return String(value.value);
+	return value.value ? definition.trueLabel : definition.falseLabel;
+}
+
+function describeDateRange(
+	value: DateRangeFilterValue,
+	{ locale }: DescribeContext,
+): string {
+	const format = (bound: string | undefined) =>
+		bound === undefined ? undefined : formatDate(bound, locale);
+	return describeBounds(format(value.from), format(value.to));
+}
+
+/**
+ * The human sentence for one active filter, as shown on its chip: the label,
+ * the operator when the filter is inverted, and the value in the reader's
+ * locale. Returns `null` for a value that has no definition anymore (a filter
+ * removed from the screen but still in a bookmarked URL).
+ */
+export function describeFilterValue({
+	definition,
+	value,
+	labels,
+	locale,
+}: {
+	definition: FilterDefinition | undefined;
+	value: FilterValue;
+	labels: FilterLabels;
+	locale: string;
+}): string | null {
+	if (definition === undefined) return null;
+	const context: DescribeContext = { definition, labels, locale };
+	const labelled = (rendered: string) => `${definition.label}: ${rendered}`;
+
+	switch (value.kind) {
+		case "text":
+			return `${definition.label} ${operatorOf(value.excluded, context)} ${value.text}`;
+		case "number":
+			return labelled(
+				`${formatNumber(value.number, locale)}${unitOf(context)}`,
+			);
+		case "numberRange":
+			return labelled(describeNumberRange(value, context));
+		case "moneyRange":
+			return labelled(describeMoneyRange(value, context));
+		case "select":
+			return describeSelect(value, context);
+		case "dateRange":
+			return labelled(describeDateRange(value, context));
+		case "geoRadius":
+			return labelled(labels.around(value.place.label, value.radiusKm));
+		case "boolean":
+			return labelled(describeBoolean(value, context));
+	}
+}

package/src/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind must scan this package or none of its classes are generated — the
+ * components ship as .tsx source, not as compiled CSS.
+ *
+ * `@source` resolves relative to the file that declares it, so this works
+ * wherever the package ends up: node_modules in an app, a symlink in a
+ * workspace. Consumers import this file and add nothing of their own.
+ */
+@source "./";
+@source not "./**/*.test.*";