@makolabs/ripple 2.5.9 → 3.0.0

package/dist/filters/FilterPopover.svelte

@@ -0,0 +1,346 @@
+<script lang="ts">
+	import { cn } from '../helper/cls.js';
+	import { fly } from 'svelte/transition';
+	import { quintOut } from 'svelte/easing';
+	import DateRange from '../forms/DateRange.svelte';
+	import { defaultDatePresets, toIsoDate, fromIsoDate } from './date-presets.js';
+	import type {
+		FilterGroup,
+		FilterSelectionValue,
+		DateRangeValue,
+		CompactFiltersProps
+	} from '../index.js';
+
+	// Reuse CompactFiltersProps shape for consistency — same `filterGroups`,
+	// `selections`, `onfilterchange`, `defaults`, `showClearAll`, `clearAllLabel`.
+	let {
+		filterGroups = [],
+		selections = $bindable<Record<string, FilterSelectionValue>>({}),
+		onfilterchange,
+		defaults,
+		showClearAll = false,
+		clearAllLabel = 'Clear',
+		class: className,
+		testId
+	}: Pick<
+		CompactFiltersProps,
+		| 'filterGroups'
+		| 'selections'
+		| 'onfilterchange'
+		| 'defaults'
+		| 'showClearAll'
+		| 'clearAllLabel'
+		| 'class'
+		| 'testId'
+	> = $props();
+
+	let openKey = $state<string | null>(null);
+	let popoverRefs = $state<Record<string, HTMLDivElement | undefined>>({});
+
+	function isDateRangeGroup(group: FilterGroup): boolean {
+		return !!group.dateRange;
+	}
+
+	function dateRangeConfig(group: FilterGroup) {
+		const cfg = group.dateRange;
+		if (cfg && typeof cfg === 'object') {
+			return {
+				presets: cfg.presets ?? defaultDatePresets,
+				minDate: cfg.minDate,
+				maxDate: cfg.maxDate
+			};
+		}
+		return { presets: defaultDatePresets, minDate: undefined, maxDate: undefined };
+	}
+
+	function asDateRange(v: FilterSelectionValue | undefined): DateRangeValue | null {
+		if (v && typeof v === 'object' && !Array.isArray(v)) return v as DateRangeValue;
+		return null;
+	}
+
+	function getSelected(group: FilterGroup): FilterSelectionValue {
+		const v = selections[group.key];
+		if (v !== undefined) return v;
+		if (isDateRangeGroup(group)) return null;
+		return group.multiple ? [] : '';
+	}
+
+	function isSelected(group: FilterGroup, value: string): boolean {
+		const current = getSelected(group);
+		return Array.isArray(current) ? current.includes(value) : current === value;
+	}
+
+	function getSelectedLabel(group: FilterGroup, current: FilterSelectionValue): string {
+		if (isDateRangeGroup(group)) {
+			const dr = asDateRange(current);
+			if (!dr) return 'Any';
+			if (dr.preset) {
+				const cfg = dateRangeConfig(group);
+				const preset = cfg.presets.find((p) => p.value === dr.preset);
+				if (preset) return preset.label;
+			}
+			return `${dr.from} → ${dr.to}`;
+		}
+		const tabs = group.tabs ?? [];
+		if (Array.isArray(current)) {
+			if (current.length === 0) return 'Any';
+			if (current.length === 1) {
+				return tabs.find((t) => t.value === current[0])?.label ?? current[0];
+			}
+			return `${current.length} selected`;
+		}
+		if (!current || typeof current !== 'string') return 'Any';
+		return tabs.find((t) => t.value === current)?.label ?? current;
+	}
+
+	function handlePresetPick(
+		group: FilterGroup,
+		preset: { value: string; range: () => { from: Date; to: Date } }
+	) {
+		const { from, to } = preset.range();
+		const next: DateRangeValue = {
+			from: toIsoDate(from),
+			to: toIsoDate(to),
+			preset: preset.value
+		};
+		selections = { ...selections, [group.key]: next };
+		onfilterchange?.(group.key, next);
+		openKey = null;
+	}
+
+	function handleCustomRange(group: FilterGroup, from: Date | undefined, to: Date | undefined) {
+		if (!from || !to) return;
+		const next: DateRangeValue = { from: toIsoDate(from), to: toIsoDate(to) };
+		selections = { ...selections, [group.key]: next };
+		onfilterchange?.(group.key, next);
+	}
+
+	function clearDateRange(group: FilterGroup) {
+		selections = { ...selections, [group.key]: null };
+		onfilterchange?.(group.key, null);
+	}
+
+	function handleSelect(group: FilterGroup, value: string) {
+		let next: FilterSelectionValue;
+		if (group.multiple) {
+			const current = getSelected(group);
+			const arr: string[] = Array.isArray(current)
+				? (current as string[])
+				: typeof current === 'string' && current
+					? [current]
+					: [];
+			next = arr.includes(value) ? arr.filter((v) => v !== value) : [...arr, value];
+		} else {
+			next = value;
+		}
+		selections = { ...selections, [group.key]: next };
+		onfilterchange?.(group.key, next);
+		if (!group.multiple) openKey = null;
+	}
+
+	function toggleGroup(key: string) {
+		openKey = openKey === key ? null : key;
+	}
+
+	function closeAll() {
+		openKey = null;
+	}
+
+	function handleKey(e: KeyboardEvent) {
+		if (e.key === 'Escape') closeAll();
+	}
+
+	function handleClickOutside(e: MouseEvent) {
+		if (!openKey) return;
+		const ref = popoverRefs[openKey];
+		const target = e.target as Node;
+		if (ref && !ref.contains(target)) closeAll();
+	}
+
+	const isDirty = $derived.by(() => {
+		if (!defaults) return Object.keys(selections).length > 0;
+		for (const key of new Set([...Object.keys(defaults), ...Object.keys(selections)])) {
+			if (JSON.stringify(selections[key] ?? null) !== JSON.stringify(defaults[key] ?? null))
+				return true;
+		}
+		return false;
+	});
+
+	function clearAll() {
+		selections = defaults ? { ...defaults } : {};
+		for (const group of filterGroups) {
+			onfilterchange?.(group.key, getSelected(group));
+		}
+	}
+
+	function hasActiveSelection(group: FilterGroup): boolean {
+		const current = getSelected(group);
+		const def = defaults?.[group.key];
+		if (isDateRangeGroup(group)) return !!asDateRange(current);
+		if (Array.isArray(current)) return current.length > 0;
+		if (def !== undefined) return current !== def;
+		return !!current;
+	}
+</script>
+
+<svelte:window onkeydown={handleKey} onmousedown={handleClickOutside} />
+
+<div
+	class={cn('flex flex-wrap items-center gap-2', className)}
+	data-testid={testId ? `${testId}-filter-popover` : undefined}
+>
+	{#each filterGroups as group (group.key)}
+		{@const selectedValue = getSelected(group)}
+		{@const active = hasActiveSelection(group)}
+		<div class="relative" bind:this={popoverRefs[group.key]}>
+			<button
+				type="button"
+				onclick={() => toggleGroup(group.key)}
+				class={cn(
+					'inline-flex cursor-pointer items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium whitespace-nowrap transition-colors',
+					active
+						? 'bg-primary-50 text-primary-700 border-primary-200 hover:bg-primary-100'
+						: 'border-default-200 text-default-700 hover:bg-default-50 bg-white',
+					openKey === group.key && 'ring-primary-300 ring-2'
+				)}
+				aria-expanded={openKey === group.key}
+				aria-haspopup="listbox"
+			>
+				<span class="text-default-500">{group.label}:</span>
+				<span>{getSelectedLabel(group, selectedValue)}</span>
+				<svg
+					class={cn('size-3 transition-transform', openKey === group.key && 'rotate-180')}
+					viewBox="0 0 20 20"
+					fill="currentColor"
+					aria-hidden="true"
+				>
+					<path
+						fill-rule="evenodd"
+						d="M5.22 8.22a.75.75 0 0 1 1.06 0L10 11.94l3.72-3.72a.75.75 0 1 1 1.06 1.06l-4.25 4.25a.75.75 0 0 1-1.06 0L5.22 9.28a.75.75 0 0 1 0-1.06z"
+						clip-rule="evenodd"
+					/>
+				</svg>
+			</button>
+
+			{#if openKey === group.key && isDateRangeGroup(group)}
+				{@const drCfg = dateRangeConfig(group)}
+				{@const drValue = asDateRange(selectedValue)}
+				<div
+					role="dialog"
+					transition:fly={{ y: -4, duration: 180, easing: quintOut }}
+					class="border-default-200 absolute z-50 mt-1 min-w-[18rem] rounded-lg border bg-white p-3 shadow-lg"
+				>
+					<div class="mb-2 flex flex-col gap-1">
+						{#each drCfg.presets as preset (preset.value)}
+							{@const presetSelected = drValue?.preset === preset.value}
+							<button
+								type="button"
+								onclick={() => handlePresetPick(group, preset)}
+								class={cn(
+									'flex w-full cursor-pointer items-center rounded-md px-3 py-1.5 text-left text-xs',
+									presetSelected
+										? 'bg-primary-50 text-primary-700 font-medium'
+										: 'text-default-700 hover:bg-default-50'
+								)}
+							>
+								{preset.label}
+							</button>
+						{/each}
+					</div>
+					<div class="border-default-100 mt-2 border-t pt-2">
+						<div class="text-default-500 mb-1 text-[10px] font-semibold uppercase">Custom</div>
+						<DateRange
+							startDate={drValue?.from ? fromIsoDate(drValue.from) : undefined}
+							endDate={drValue?.to ? fromIsoDate(drValue.to) : undefined}
+							onselect={({ startDate, endDate }) => handleCustomRange(group, startDate, endDate)}
+							minDate={drCfg.minDate}
+							maxDate={drCfg.maxDate}
+						/>
+					</div>
+					{#if drValue}
+						<button
+							type="button"
+							onclick={() => clearDateRange(group)}
+							class="text-default-500 hover:text-default-700 mt-2 w-full cursor-pointer rounded-md text-center text-xs underline"
+						>
+							Clear range
+						</button>
+					{/if}
+				</div>
+			{:else if openKey === group.key}
+				<div
+					role="listbox"
+					transition:fly={{ y: -4, duration: 180, easing: quintOut }}
+					class="border-default-200 absolute z-50 mt-1 min-w-[10rem] rounded-lg border bg-white p-1 shadow-lg"
+				>
+					{#each group.tabs ?? [] as tab (tab.value)}
+						{@const tabSelected = isSelected(group, tab.value)}
+						<button
+							type="button"
+							role="option"
+							aria-selected={tabSelected}
+							onclick={() => handleSelect(group, tab.value)}
+							class={cn(
+								'flex w-full cursor-pointer items-center justify-between rounded-md px-3 py-1.5 text-xs whitespace-nowrap',
+								tabSelected
+									? 'bg-primary-50 text-primary-700 font-medium'
+									: 'text-default-700 hover:bg-default-50'
+							)}
+						>
+							<span class="flex items-center gap-2">
+								{#if group.multiple}
+									<span
+										class={cn(
+											'flex size-4 shrink-0 items-center justify-center rounded border',
+											tabSelected
+												? 'bg-primary-600 border-primary-600'
+												: 'border-default-300 bg-white'
+										)}
+									>
+										{#if tabSelected}
+											<svg
+												class="size-3 text-white"
+												viewBox="0 0 12 12"
+												fill="none"
+												aria-hidden="true"
+											>
+												<path
+													d="M2 6l3 3 5-6"
+													stroke="currentColor"
+													stroke-width="2"
+													stroke-linecap="round"
+													stroke-linejoin="round"
+												/>
+											</svg>
+										{/if}
+									</span>
+								{/if}
+								<span>{tab.label}</span>
+							</span>
+							{#if tab.count !== undefined}
+								<span
+									class={cn(
+										'ml-4 text-[10px]',
+										tabSelected ? 'text-primary-500' : 'text-default-400'
+									)}
+								>
+									{tab.count}
+								</span>
+							{/if}
+						</button>
+					{/each}
+				</div>
+			{/if}
+		</div>
+	{/each}
+
+	{#if showClearAll && isDirty}
+		<button
+			type="button"
+			onclick={clearAll}
+			class="text-default-500 hover:bg-default-100 hover:text-default-700 cursor-pointer rounded-md px-2 py-1 text-xs font-medium"
+		>
+			{clearAllLabel}
+		</button>
+	{/if}
+</div>

package/dist/filters/FilterPopover.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { CompactFiltersProps } from '../index.js';
+declare const FilterPopover: import("svelte").Component<Pick<CompactFiltersProps, "class" | "testId" | "filterGroups" | "selections" | "onfilterchange" | "defaults" | "showClearAll" | "clearAllLabel">, {}, "selections">;
+type FilterPopover = ReturnType<typeof FilterPopover>;
+export default FilterPopover;

package/dist/filters/date-presets.d.ts

@@ -0,0 +1,15 @@
+import type { DatePreset } from './filter-types.js';
+/**
+ * Curated list of common date-range shortcuts. Used by default when a
+ * FilterGroup has `dateRange: true` without a custom preset list.
+ */
+export declare const defaultDatePresets: DatePreset[];
+/** Format a `Date` as an ISO date string (YYYY-MM-DD) in local time. */
+export declare function toIsoDate(d: Date): string;
+/**
+ * Parse an ISO date string (YYYY-MM-DD) back to a local-time `Date`.
+ * Throws if the input doesn't match `YYYY-MM-DD` exactly or if the
+ * resulting date is invalid — silent normalization of bad input hides
+ * bugs in URL/filter-state handling.
+ */
+export declare function fromIsoDate(s: string): Date;

package/dist/filters/date-presets.js

@@ -0,0 +1,107 @@
+/**
+ * Start-of-day / end-of-day helpers so presets produce deterministic ranges.
+ * Kept as a tiny utility rather than pulling in a date lib.
+ */
+function startOfDay(d) {
+    const x = new Date(d);
+    x.setHours(0, 0, 0, 0);
+    return x;
+}
+function endOfDay(d) {
+    const x = new Date(d);
+    x.setHours(23, 59, 59, 999);
+    return x;
+}
+function addDays(d, days) {
+    const x = new Date(d);
+    x.setDate(x.getDate() + days);
+    return x;
+}
+function startOfMonth(d) {
+    const x = new Date(d.getFullYear(), d.getMonth(), 1);
+    return startOfDay(x);
+}
+function endOfMonth(d) {
+    const x = new Date(d.getFullYear(), d.getMonth() + 1, 0);
+    return endOfDay(x);
+}
+/**
+ * Curated list of common date-range shortcuts. Used by default when a
+ * FilterGroup has `dateRange: true` without a custom preset list.
+ */
+export const defaultDatePresets = [
+    {
+        value: 'today',
+        label: 'Today',
+        range: () => {
+            const now = new Date();
+            return { from: startOfDay(now), to: endOfDay(now) };
+        }
+    },
+    {
+        value: 'yesterday',
+        label: 'Yesterday',
+        range: () => {
+            const y = addDays(new Date(), -1);
+            return { from: startOfDay(y), to: endOfDay(y) };
+        }
+    },
+    {
+        value: 'last-7',
+        label: 'Last 7 days',
+        range: () => {
+            const now = new Date();
+            return { from: startOfDay(addDays(now, -6)), to: endOfDay(now) };
+        }
+    },
+    {
+        value: 'last-30',
+        label: 'Last 30 days',
+        range: () => {
+            const now = new Date();
+            return { from: startOfDay(addDays(now, -29)), to: endOfDay(now) };
+        }
+    },
+    {
+        value: 'this-month',
+        label: 'This month',
+        range: () => {
+            const now = new Date();
+            return { from: startOfMonth(now), to: endOfDay(now) };
+        }
+    },
+    {
+        value: 'last-month',
+        label: 'Last month',
+        range: () => {
+            const now = new Date();
+            const lastMonthAnchor = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+            return { from: startOfMonth(lastMonthAnchor), to: endOfMonth(lastMonthAnchor) };
+        }
+    }
+];
+/** Format a `Date` as an ISO date string (YYYY-MM-DD) in local time. */
+export function toIsoDate(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+/**
+ * Parse an ISO date string (YYYY-MM-DD) back to a local-time `Date`.
+ * Throws if the input doesn't match `YYYY-MM-DD` exactly or if the
+ * resulting date is invalid — silent normalization of bad input hides
+ * bugs in URL/filter-state handling.
+ */
+export function fromIsoDate(s) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+        throw new Error(`fromIsoDate: expected "YYYY-MM-DD", got "${s}"`);
+    }
+    const [y, m, d] = s.split('-').map(Number);
+    const date = new Date(y, m - 1, d);
+    // Guard against e.g. "2026-02-30" — `new Date` silently rolls over.
+    if (date.getFullYear() !== y || date.getMonth() !== m - 1 || date.getDate() !== d) {
+        throw new Error(`fromIsoDate: "${s}" is not a real calendar date`);
+    }
+    return date;
+}

package/dist/filters/filter-types.d.ts

@@ -3,17 +3,83 @@ import type { Component } from 'svelte';
 export type FilterTab = {
     value: string;
     label: string;
+    /** Optional count badge rendered next to the label, e.g. "Active (23)". */
+    count?: number;
+};
+/**
+ * A named date-range shortcut, e.g. "Last 7 days". The `range` function is
+ * called when the user picks the preset to produce concrete from/to dates.
+ */
+export type DatePreset = {
+    value: string;
+    label: string;
+    range: () => {
+        from: Date;
+        to: Date;
+    };
+};
+/**
+ * Config for a date-range filter group. Pass `true` for sensible defaults
+ * (curated preset list + no min/max), or an object for customization.
+ */
+export type DateRangeConfig = {
+    /** Preset buttons shown above the calendar. Defaults to `defaultDatePresets`. */
+    presets?: DatePreset[];
+    /** Earliest selectable date in the calendar. */
+    minDate?: Date;
+    /** Latest selectable date in the calendar. */
+    maxDate?: Date;
 };
 export type FilterGroup = {
     key: string;
     label: string;
-    tabs: FilterTab[];
-    selectedValue: string;
-    onChange: (value: string) => void;
     minWidth?: string;
+    /**
+     * Tabs for a tab-based filter group. Mutually exclusive with `dateRange`.
+     * One of `tabs` or `dateRange` is required.
+     */
+    tabs?: FilterTab[];
+    /**
+     * Opt into a date-range filter group. `true` uses default presets; pass a
+     * `DateRangeConfig` for custom presets / min / max. Mutually exclusive
+     * with `tabs`.
+     */
+    dateRange?: boolean | DateRangeConfig;
+    /**
+     * For tab groups: allow multiple simultaneous selections. `selections[key]`
+     * becomes `string[]` instead of `string`. Ignored for date-range groups.
+     * @default false
+     */
+    multiple?: boolean;
+};
+/**
+ * Date-range selection value. ISO-8601 date strings (YYYY-MM-DD) for easy
+ * URL serialization. `preset` is the preset `value` when a preset was picked,
+ * so consumers can still render "Last 7 days" instead of the date range.
+ */
+export type DateRangeValue = {
+    from: string;
+    to: string;
+    preset?: string;
 };
+/**
+ * Per-group selection value.
+ * - `string` — single-tab selection
+ * - `string[]` — multi-tab selection
+ * - `DateRangeValue` — date-range group selection
+ * - `null` / `undefined` — unset
+ */
+export type FilterSelectionValue = string | string[] | DateRangeValue | null;
 export type CompactFiltersProps = {
     filterGroups: FilterGroup[];
+    selections?: Record<string, FilterSelectionValue>;
+    onfilterchange?: (key: string, value: FilterSelectionValue) => void;
+    defaults?: Record<string, FilterSelectionValue>;
+    showClearAll?: boolean;
+    clearAllLabel?: string;
+    searchQuery?: string;
+    searchPlaceholder?: string;
+    chipSummary?: boolean;
     isExpanded?: boolean;
     title?: string;
     class?: ClassValue;

package/dist/filters/index.d.ts

@@ -1 +1,6 @@
 export { default as CompactFilters } from './CompactFilters.svelte';
+export { default as FilterPopover } from './FilterPopover.svelte';
+export { default as FilterBar } from './FilterBar.svelte';
+export { syncFiltersToUrl } from './sync-filters-to-url.svelte.js';
+export { defaultDatePresets, toIsoDate, fromIsoDate } from './date-presets.js';
+export type { FilterTab, FilterGroup, FilterSelectionValue, DatePreset, DateRangeConfig, DateRangeValue, CompactFiltersProps } from './filter-types.js';

package/dist/filters/index.js

@@ -1 +1,5 @@
 export { default as CompactFilters } from './CompactFilters.svelte';
+export { default as FilterPopover } from './FilterPopover.svelte';
+export { default as FilterBar } from './FilterBar.svelte';
+export { syncFiltersToUrl } from './sync-filters-to-url.svelte.js';
+export { defaultDatePresets, toIsoDate, fromIsoDate } from './date-presets.js';

package/dist/filters/sync-filters-to-url.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { FilterSelectionValue } from './filter-types.js';
+/**
+ * Sync a reactive `selections` object to/from URL query params.
+ *
+ * - On first call: reads current URL params into the setter.
+ * - On every subsequent change to `getter()`: writes back to the URL.
+ *
+ * Designed for use inside a Svelte 5 component with `$effect` semantics — call
+ * it at the top level of `<script>` and it will register its own `$effect`.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { CompactFilters, syncFiltersToUrl } from '@makolabs/ripple';
+ *   let selections = $state({ status: 'all' });
+ *   syncFiltersToUrl(() => selections, (v) => (selections = v));
+ * </script>
+ *
+ * <CompactFilters {filterGroups} bind:selections />
+ * ```
+ *
+ * Environment:
+ * - Uses `window.location` and `history.replaceState` — no-ops on the server.
+ * - Multi-select values (`string[]`) are serialized as comma-joined strings.
+ * - Removes a key from the URL when its value is empty / empty array.
+ * - Leaves unrelated URL params untouched.
+ */
+export declare function syncFiltersToUrl(getter: () => Record<string, FilterSelectionValue>, setter: (next: Record<string, FilterSelectionValue>) => void, options?: {
+    /** Group keys to manage. If omitted, all keys returned by `getter` are managed. */
+    keys?: string[];
+    /** Debounce writes by this many ms. @default 150 */
+    debounceMs?: number;
+    /** Keys whose values should be parsed as arrays (multi-select). */
+    arrayKeys?: string[];
+    /** Keys whose values are date ranges. Serialized as `<key>_from`, `<key>_to`, `<key>_preset`. */
+    dateRangeKeys?: string[];
+}): void;