@voila.dev/ui-filter 1.1.9

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

@@ -0,0 +1,79 @@
+import { MoneyInput } from "@voila.dev/ui/components/money-input";
+import { useId } from "react";
+import {
+	FilterFieldFrame,
+	FilterRangeRow,
+} from "#/components/fields/field-frame.tsx";
+import type {
+	FilterLabels,
+	MoneyRangeFilterDefinition,
+	MoneyRangeFilterValue,
+} from "#/types.ts";
+
+// Values travel as minor units (cents) — the platform's money representation —
+// while the field edits a major-unit string, so the rounding happens once, here.
+const toAmountInput = (minorUnits: number | undefined): string =>
+	minorUnits === undefined ? "" : String(minorUnits / 100);
+
+const toMinorUnits = (raw: string): number | undefined =>
+	raw.trim() === "" || Number.isNaN(Number(raw))
+		? undefined
+		: Math.round(Number(raw) * 100);
+
+/** A price floor and ceiling, either of which may be left open. */
+export function MoneyRangeFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: MoneyRangeFilterDefinition;
+	readonly value: MoneyRangeFilterValue | undefined;
+	readonly onValueChange: (value: MoneyRangeFilterValue) => void;
+	readonly labels: FilterLabels;
+}) {
+	const controlId = useId();
+	const isEmpty = value?.min === undefined && value?.max === undefined;
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={controlId}
+			labels={labels}
+			onClear={
+				isEmpty ? undefined : () => onValueChange({ kind: "moneyRange" })
+			}
+		>
+			<FilterRangeRow>
+				<MoneyInput
+					id={controlId}
+					value={toAmountInput(value?.min)}
+					placeholder={labels.min}
+					currency={definition.currency}
+					currencyLabel={definition.currency}
+					onValueChange={(next) =>
+						onValueChange({
+							kind: "moneyRange",
+							min: toMinorUnits(next),
+							max: value?.max,
+						})
+					}
+				/>
+				<MoneyInput
+					value={toAmountInput(value?.max)}
+					placeholder={labels.max}
+					currency={definition.currency}
+					currencyLabel={definition.currency}
+					onValueChange={(next) =>
+						onValueChange({
+							kind: "moneyRange",
+							min: value?.min,
+							max: toMinorUnits(next),
+						})
+					}
+				/>
+			</FilterRangeRow>
+		</FilterFieldFrame>
+	);
+}

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

@@ -0,0 +1,170 @@
+import {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupInput,
+} from "@voila.dev/ui/components/input-group";
+import { useId } from "react";
+import {
+	FilterFieldFrame,
+	FilterRangeRow,
+} from "#/components/fields/field-frame.tsx";
+import type {
+	FilterLabels,
+	NumberFilterDefinition,
+	NumberFilterValue,
+	NumberRangeFilterDefinition,
+	NumberRangeFilterValue,
+} from "#/types.ts";
+
+/** `""` is a bound the reader cleared, not a zero — keep the two apart. */
+const parseBound = (raw: string): number | undefined =>
+	raw.trim() === "" || Number.isNaN(Number(raw)) ? undefined : Number(raw);
+
+const toInputValue = (bound: number | undefined): string =>
+	bound === undefined ? "" : String(bound);
+
+function NumberField({
+	id,
+	value,
+	onChange,
+	unit,
+	placeholder,
+	min,
+	max,
+	step,
+}: {
+	readonly id?: string;
+	readonly value: string;
+	readonly onChange: (raw: string) => void;
+	readonly unit?: string;
+	readonly placeholder?: string;
+	readonly min?: number;
+	readonly max?: number;
+	readonly step?: number;
+}) {
+	return (
+		<InputGroup>
+			<InputGroupInput
+				id={id}
+				type="number"
+				inputMode="decimal"
+				value={value}
+				placeholder={placeholder}
+				min={min}
+				max={max}
+				step={step}
+				onChange={(event) => onChange(event.target.value)}
+			/>
+			{unit !== undefined && (
+				<InputGroupAddon align="inline-end">{unit}</InputGroupAddon>
+			)}
+		</InputGroup>
+	);
+}
+
+/** A single numeric value. */
+export function NumberFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: NumberFilterDefinition;
+	readonly value: NumberFilterValue | undefined;
+	readonly onValueChange: (value: NumberFilterValue) => void;
+	readonly labels: FilterLabels;
+}) {
+	const controlId = useId();
+	const raw = value === undefined ? "" : String(value.number);
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={controlId}
+			labels={labels}
+			onClear={
+				raw === ""
+					? undefined
+					: () => onValueChange({ kind: "number", number: Number.NaN })
+			}
+		>
+			<NumberField
+				id={controlId}
+				value={raw}
+				unit={definition.unit}
+				min={definition.min}
+				max={definition.max}
+				step={definition.step}
+				onChange={(next) =>
+					onValueChange({
+						kind: "number",
+						number: parseBound(next) ?? Number.NaN,
+					})
+				}
+			/>
+		</FilterFieldFrame>
+	);
+}
+
+/** A lower and an upper bound, either of which may be left open. */
+export function NumberRangeFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: NumberRangeFilterDefinition;
+	readonly value: NumberRangeFilterValue | undefined;
+	readonly onValueChange: (value: NumberRangeFilterValue) => void;
+	readonly labels: FilterLabels;
+}) {
+	const controlId = useId();
+	const isEmpty = value?.min === undefined && value?.max === undefined;
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={controlId}
+			labels={labels}
+			onClear={
+				isEmpty ? undefined : () => onValueChange({ kind: "numberRange" })
+			}
+		>
+			<FilterRangeRow>
+				<NumberField
+					id={controlId}
+					value={toInputValue(value?.min)}
+					placeholder={labels.min}
+					unit={definition.unit}
+					min={definition.min}
+					max={definition.max}
+					step={definition.step}
+					onChange={(next) =>
+						onValueChange({
+							kind: "numberRange",
+							min: parseBound(next),
+							max: value?.max,
+						})
+					}
+				/>
+				<NumberField
+					value={toInputValue(value?.max)}
+					placeholder={labels.max}
+					unit={definition.unit}
+					min={definition.min}
+					max={definition.max}
+					step={definition.step}
+					onChange={(next) =>
+						onValueChange({
+							kind: "numberRange",
+							min: value?.min,
+							max: parseBound(next),
+						})
+					}
+				/>
+			</FilterRangeRow>
+		</FilterFieldFrame>
+	);
+}

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

@@ -0,0 +1,153 @@
+import { CheckIcon } from "@phosphor-icons/react";
+import { Input } from "@voila.dev/ui/components/input";
+import { cn } from "@voila.dev/ui/lib/utils";
+import { useId, useState } from "react";
+import {
+	FilterFieldFrame,
+	FilterOperatorToggle,
+} from "#/components/fields/field-frame.tsx";
+import type {
+	FilterLabels,
+	FilterOption,
+	SelectFilterDefinition,
+	SelectFilterValue,
+} from "#/types.ts";
+
+/** Past this many options the list gets its own search box. */
+const SEARCHABLE_FROM = 8;
+
+/**
+ * One option, as a toggle. Options are pressable pills rather than a dropdown:
+ * the whole choice set stays visible while you build a filter, which is what
+ * makes multi-select legible — and a pill is the same target size on a phone as
+ * a native option row, without the modal picker's round trip.
+ */
+function OptionToggle({
+	option,
+	selected,
+	onToggle,
+}: {
+	readonly option: FilterOption;
+	readonly selected: boolean;
+	readonly onToggle: () => void;
+}) {
+	return (
+		<button
+			type="button"
+			role="option"
+			aria-selected={selected}
+			onClick={onToggle}
+			className={cn(
+				"inline-flex cursor-pointer items-center gap-1.5 rounded-full border px-3 py-1.5 text-sm transition-colors",
+				"focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-2",
+				selected
+					? "border-primary bg-primary text-primary-foreground"
+					: "border-input bg-background text-foreground hover:bg-accent",
+			)}
+		>
+			{selected && <CheckIcon weight="bold" className="size-3.5 shrink-0" />}
+			{option.icon}
+			{option.label}
+		</button>
+	);
+}
+
+function toggleValue(
+	values: ReadonlyArray<string>,
+	value: string,
+	multiple: boolean,
+): ReadonlyArray<string> {
+	if (values.includes(value)) {
+		return values.filter((current) => current !== value);
+	}
+	return multiple ? [...values, value] : [value];
+}
+
+/** Single or multiple choice among a known set, optionally inverted. */
+export function SelectFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: SelectFilterDefinition;
+	readonly value: SelectFilterValue | undefined;
+	readonly onValueChange: (value: SelectFilterValue) => void;
+	readonly labels: FilterLabels;
+}) {
+	const searchId = useId();
+	const [query, setQuery] = useState("");
+	const selected = value?.values ?? [];
+	const excluded = value?.excluded ?? false;
+	const multiple = definition.multiple ?? false;
+
+	const searchable = definition.options.length >= SEARCHABLE_FROM;
+	const normalizedQuery = query.trim().toLowerCase();
+	const visibleOptions =
+		normalizedQuery === ""
+			? definition.options
+			: definition.options.filter((option) =>
+					option.label.toLowerCase().includes(normalizedQuery),
+				);
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={searchable ? searchId : undefined}
+			labels={labels}
+			operator={
+				definition.allowExclusion === true ? (
+					<FilterOperatorToggle
+						excluded={excluded}
+						disabled={selected.length === 0}
+						onExcludedChange={(next) =>
+							onValueChange({
+								kind: "select",
+								values: selected,
+								excluded: next,
+							})
+						}
+						labels={labels}
+					/>
+				) : undefined
+			}
+			onClear={
+				selected.length === 0
+					? undefined
+					: () => onValueChange({ kind: "select", values: [], excluded })
+			}
+		>
+			{searchable && (
+				<Input
+					id={searchId}
+					value={query}
+					placeholder={labels.optionSearchPlaceholder}
+					aria-label={`${definition.label} — ${labels.search}`}
+					onChange={(event) => setQuery(event.target.value)}
+				/>
+			)}
+			<div
+				role="listbox"
+				aria-multiselectable={multiple}
+				aria-label={definition.label}
+				className="flex flex-wrap gap-2"
+			>
+				{visibleOptions.map((option) => (
+					<OptionToggle
+						key={option.value}
+						option={option}
+						selected={selected.includes(option.value)}
+						onToggle={() =>
+							onValueChange({
+								kind: "select",
+								values: toggleValue(selected, option.value, multiple),
+								excluded,
+							})
+						}
+					/>
+				))}
+			</div>
+		</FilterFieldFrame>
+	);
+}

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

@@ -0,0 +1,63 @@
+import { Input } from "@voila.dev/ui/components/input";
+import { useId } from "react";
+import {
+	FilterFieldFrame,
+	FilterOperatorToggle,
+} from "#/components/fields/field-frame.tsx";
+import type {
+	FilterLabels,
+	TextFilterDefinition,
+	TextFilterValue,
+} from "#/types.ts";
+
+/** Free-text contains/does-not-contain filter. */
+export function TextFilterField({
+	definition,
+	value,
+	onValueChange,
+	labels,
+}: {
+	readonly definition: TextFilterDefinition;
+	readonly value: TextFilterValue | undefined;
+	readonly onValueChange: (value: TextFilterValue) => void;
+	readonly labels: FilterLabels;
+}) {
+	const controlId = useId();
+	const text = value?.text ?? "";
+	const excluded = value?.excluded ?? false;
+
+	return (
+		<FilterFieldFrame
+			label={definition.label}
+			description={definition.description}
+			controlId={controlId}
+			labels={labels}
+			operator={
+				definition.allowExclusion === true ? (
+					<FilterOperatorToggle
+						excluded={excluded}
+						disabled={text === ""}
+						onExcludedChange={(next) =>
+							onValueChange({ kind: "text", text, excluded: next })
+						}
+						labels={labels}
+					/>
+				) : undefined
+			}
+			onClear={
+				text === ""
+					? undefined
+					: () => onValueChange({ kind: "text", text: "", excluded })
+			}
+		>
+			<Input
+				id={controlId}
+				value={text}
+				placeholder={definition.placeholder}
+				onChange={(event) =>
+					onValueChange({ kind: "text", text: event.target.value, excluded })
+				}
+			/>
+		</FilterFieldFrame>
+	);
+}

package/src/components/filter-bar.tsx

@@ -0,0 +1,90 @@
+import { useState } from "react";
+import { FilterChips } from "#/components/filter-chips.tsx";
+import { FilterPanel } from "#/components/filter-panel.tsx";
+import { FilterTrigger } from "#/components/filter-trigger.tsx";
+import { countActiveFilters } from "#/lib/filter-values.ts";
+import {
+	defaultFilterLabels,
+	type FilterDefinition,
+	type FilterLabels,
+	type FilterValues,
+} from "#/types.ts";
+
+/**
+ * The whole filtering surface of a list, in one component: the search-shaped
+ * trigger, the overlay editor behind it, the chips stating what is active, and
+ * the result count. Screens declare their filters and hand over the applied
+ * record — everything else (draft handling, responsiveness, copy) lives here so
+ * every list filters the same way.
+ */
+export function FilterBar({
+	definitions,
+	values,
+	onValuesChange,
+	searchValue,
+	onSearchChange,
+	resultCount,
+	labels: labelOverrides,
+	locale = "en-US",
+}: {
+	readonly definitions: ReadonlyArray<FilterDefinition>;
+	readonly values: FilterValues;
+	readonly onValuesChange: (values: FilterValues) => void;
+	/** Omit both search props for a list that filters without free text. */
+	readonly searchValue?: string;
+	readonly onSearchChange?: (value: string) => void;
+	readonly resultCount?: number;
+	readonly labels?: Partial<FilterLabels>;
+	readonly locale?: string;
+}) {
+	const [open, setOpen] = useState(false);
+	const labels: FilterLabels = { ...defaultFilterLabels, ...labelOverrides };
+	const activeCount = countActiveFilters(values);
+
+	return (
+		<div className="flex w-full min-w-0 flex-col gap-3" data-slot="filter-bar">
+			{/* `min-w-0` on both children: without it a flex item refuses to shrink
+			    below its content, and the nowrap result count pushes the row past
+			    the viewport — a phone then scrolls sideways. */}
+			<div className="flex min-w-0 items-center gap-3">
+				<FilterTrigger
+					summary={
+						searchValue === undefined || searchValue === ""
+							? undefined
+							: searchValue
+					}
+					activeCount={activeCount}
+					labels={labels}
+					className="min-w-0 flex-1 sm:max-w-md"
+					onClick={() => setOpen(true)}
+				/>
+				{resultCount !== undefined && (
+					<span className="shrink-0 whitespace-nowrap text-muted-foreground text-sm">
+						{labels.resultCount(resultCount)}
+					</span>
+				)}
+			</div>
+
+			<FilterChips
+				definitions={definitions}
+				values={values}
+				onValuesChange={onValuesChange}
+				labels={labels}
+				locale={locale}
+				onChipClick={() => setOpen(true)}
+			/>
+
+			<FilterPanel
+				open={open}
+				onOpenChange={setOpen}
+				definitions={definitions}
+				values={values}
+				onValuesChange={onValuesChange}
+				labels={labels}
+				locale={locale}
+				searchValue={searchValue}
+				onSearchChange={onSearchChange}
+			/>
+		</div>
+	);
+}

package/src/components/filter-chips.tsx

@@ -0,0 +1,70 @@
+import { XIcon } from "@phosphor-icons/react";
+import { Chip, ChipRemove } from "@voila.dev/ui/components/chip";
+import { cn } from "@voila.dev/ui/lib/utils";
+import { clearFilterValue, describeFilterValue } from "#/lib/filter-values.ts";
+import type { FilterDefinition, FilterLabels, FilterValues } from "#/types.ts";
+
+/**
+ * What is currently filtered, stated in full: one removable chip per active
+ * filter. This is the "view" half of the pair — the editor is behind a trigger,
+ * so without it a filtered list would look like a short list.
+ */
+export function FilterChips({
+	definitions,
+	values,
+	onValuesChange,
+	labels,
+	locale,
+	onChipClick,
+	className,
+}: {
+	readonly definitions: ReadonlyArray<FilterDefinition>;
+	readonly values: FilterValues;
+	readonly onValuesChange: (values: FilterValues) => void;
+	readonly labels: FilterLabels;
+	readonly locale: string;
+	/** Opens the editor, usually scrolled to the clicked filter. */
+	readonly onChipClick?: (key: string) => void;
+	readonly className?: string;
+}) {
+	const entries = Object.entries(values);
+	if (entries.length === 0) {
+		return null;
+	}
+
+	return (
+		<div
+			data-slot="filter-chips"
+			className={cn("flex flex-wrap items-center gap-2", className)}
+		>
+			{entries.map(([key, value]) => {
+				const description = describeFilterValue({
+					definition: definitions.find((definition) => definition.key === key),
+					value,
+					labels,
+					locale,
+				});
+				if (description === null) {
+					return null;
+				}
+				return (
+					<Chip key={key} variant="outline" className="max-w-full">
+						<button
+							type="button"
+							className="cursor-pointer truncate text-left"
+							onClick={() => onChipClick?.(key)}
+						>
+							{description}
+						</button>
+						<ChipRemove
+							aria-label={`${labels.remove}: ${description}`}
+							onClick={() => onValuesChange(clearFilterValue(values, key))}
+						>
+							<XIcon />
+						</ChipRemove>
+					</Chip>
+				);
+			})}
+		</div>
+	);
+}