Add a filter — click a chip to edit it.

new Promise((r) => window.setTimeout(r, 650))} />

{shown.map((it) => { const d = new Date(`${it.updated}T12:00:00`); return ( {it.id} {it.title} {it.failing && ( Failing )} {it.estimate} {MONTHS[d.getMonth()]} {d.getDate()} {it.assignee === "Unassigned" ? "–" : it.assignee .split(" ") .map((s) => s[0]) .join("")} ); })}

{!shown.length && (

No issues match

Loosen a filter or switch to “or”.

)}

); } ``` ## Accessibility & performance Honors `prefers-reduced-motion` with a designed static frame or fade (never a blank box) and passes `className` through. ## Source (`sift.tsx`) ```tsx "use client"; import { AnimatePresence, LayoutGroup, motion, useInView, type Transition } from "motion/react"; import * as React from "react"; import { cn } from "@/lib/utils"; import { useReducedMotion } from "@/hooks/use-reduced-motion"; import { Tally } from "@/components/crucible/tally"; /* ================================================================ types */ /** How a field's values are compared and edited. */ export type SiftFieldType = "text" | "select" | "number" | "date" | "boolean"; /** One choice of a `select` field. */ export interface SiftOption { /** Stored / compared value. */ value: string; /** Visible label. @default value */ label?: string; /** Optional status dot color (any CSS color). */ color?: string; } /** A filterable property of your rows. */ export interface SiftField { /** Row key read by `applyFilters` (`row[key]`). */ key: string; /** Visible name in the property list and on chips. */ label: string; /** Decides the operators and the value editor. */ type: SiftFieldType; /** Choices for `select` fields (strings or `{ value, label, color }`). */ options?: (string | SiftOption)[]; /** 14px glyph (uses `currentColor`). A type glyph is used when omitted. */ icon?: React.ReactNode; } /** * Comparison operator. Per field type: * text `contains | is | is-not | starts-with`; select `any-of | none-of`; * number `eq | neq | gt | lt | between`; date `is | before | after | between`; * boolean `is-true | is-false`. */ export type SiftOperator = | "contains" | "is" | "is-not" | "starts-with" | "any-of" | "none-of" | "eq" | "neq" | "gt" | "lt" | "between" | "before" | "after" | "is-true" | "is-false"; /** Relative date ranges, resolved against "today" when filtering. */ export type SiftDatePreset = "today" | "last-7" | "last-30" | "this-month"; /** * A filter's operand: `string` (text, or a `YYYY-MM-DD` date), `string[]` * (select), `number`, `[min, max]` (number between), `[from, to]` date keys * (date between) or `null` (boolean / preset). */ export type SiftFilterValue = string | number | boolean | string[] | [number, number] | [string, string] | null; /** One applied filter (one chip). */ export interface SiftFilter { /** Stable id (chip key). */ id: string; /** `SiftField.key` this filter targets. */ field: string; operator: SiftOperator; value: SiftFilterValue; /** Date fields only: a relative range that overrides `value`. */ preset?: SiftDatePreset; } /** How chips combine: every filter must match (`and`) or any (`or`). */ export type SiftConjunction = "and" | "or"; /** A named, saved chip set. */ export interface SiftView { id: string; label: string; filters: SiftFilter[]; /** @default "and" */ conjunction?: SiftConjunction; } /** Imperative verbs exposed through the `ref` prop. */ export interface SiftHandle { /** Open the filter popover — at the operator step when `fieldKey` is given. */ open: (fieldKey?: string) => void; /** Close the popover (and views menu) if open. */ close: () => void; /** Remove every filter. */ clear: () => void; /** Replay the intro. */ replay: () => void; } export interface SiftProps extends Omit, "onChange" | "defaultValue" | "children"> { /** * Filterable properties. * @default issue-tracker sample fields (Status, Priority, Assignee, Title, Estimate, Updated, Failing checks) */ fields?: SiftField[]; /** Controlled filters. Omit for uncontrolled use. */ value?: SiftFilter[]; /** * Initial filters (uncontrolled). * @default the "Active work" sample view when `fields` is omitted, otherwise none */ defaultValue?: SiftFilter[]; /** Fires with the full next filter list on every add, edit, removal, clear or view switch. */ onChange?: (filters: SiftFilter[]) => void; /** Controlled conjunction. */ conjunction?: SiftConjunction; /** Initial conjunction (uncontrolled). @default "and" */ defaultConjunction?: SiftConjunction; /** Fires when the and / or toggle between chips flips. */ onConjunctionChange?: (conjunction: SiftConjunction) => void; /** * Saved views in the views menu. Pass `[]` to hide the menu. * @default sample views (All issues, Active work, My open, Failing this week, Urgent & high) when `fields` is omitted */ views?: SiftView[]; /** Id of the view selected initially. @default "active" for the sample views, else the first view */ defaultView?: string; /** Fires when a view is picked from the menu. */ onViewChange?: (view: SiftView) => void; /** * Called when a view is saved from "Save view". Return a Promise to show a * pending state; rejecting keeps the name field open with the error. The * view is added to the menu on success. Omit to hide "Save view". */ onSaveView?: (view: SiftView) => void | Promise; /** Result count shown at the right; rolls on Tally drums when it changes. */ count?: number; /** Optional total, shown as "24 of 40". */ total?: number; /** Result noun. @default { one: "result", other: "results" } */ noun?: { one: string; other: string }; /** "Today" for date presets and the calendar (YYYY-MM-DD or Date). @default the viewer's local today */ today?: string | Date; /** Accent for focus rings, the active chip, values and the Apply button. @default "#e4e4e7" */ accentColor?: string; /** Imperative handle (`open(fieldKey?)`, `close()`, `clear()`, `replay()`). React 19 ref-as-prop. */ ref?: React.Ref; /** Extra classes for the root. */ className?: string; } /* ================================================================ constants */ const DEFAULT_ACCENT = "#e4e4e7"; const EASE: [number, number, number, number] = [0.22, 1, 0.36, 1]; const SPRING: Transition = { type: "spring", stiffness: 520, damping: 34, mass: 0.7 }; const SLIDE: Transition = { type: "spring", stiffness: 480, damping: 40 }; const FADE: Transition = { duration: 0.18, ease: "easeOut" }; /** Reduced motion: geometry snaps, only opacity fades. */ const REDUCED_T: Transition = { duration: 0, opacity: { duration: 0.18, ease: "easeOut" } }; const POP_W = 304; const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; const MONTHS_LONG = [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December", ]; const WEEKDAYS = ["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"]; const PRESETS: { id: SiftDatePreset; label: string }[] = [ { id: "today", label: "Today" }, { id: "last-7", label: "Last 7 days" }, { id: "last-30", label: "Last 30 days" }, { id: "this-month", label: "This month" }, ]; const PRESET_LABEL: Record = { today: "Today", "last-7": "Last 7 days", "last-30": "Last 30 days", "this-month": "This month", }; interface OpDef { id: SiftOperator; label: string; hint?: string; } const OPS: Record = { text: [ { id: "contains", label: "contains" }, { id: "is", label: "is" }, { id: "is-not", label: "is not" }, { id: "starts-with", label: "starts with" }, ], select: [ { id: "any-of", label: "is any of" }, { id: "none-of", label: "is none of" }, ], number: [ { id: "eq", label: "=", hint: "equals" }, { id: "neq", label: "≠", hint: "not equal" }, { id: "gt", label: ">", hint: "greater than" }, { id: "lt", label: "<", hint: "less than" }, { id: "between", label: "between", hint: "inclusive" }, ], date: [ { id: "is", label: "is" }, { id: "before", label: "before" }, { id: "after", label: "after" }, { id: "between", label: "between" }, ], boolean: [ { id: "is-true", label: "is true" }, { id: "is-false", label: "is false" }, ], }; function opLabel(type: SiftFieldType, op: SiftOperator): string { return OPS[type].find((o) => o.id === op)?.label ?? op; } /* ================================================================ icons */ const svg = (d: React.ReactNode) => ( ); const Icon = { plus: svg(), x: svg(), back: svg(), chevron: svg(), chevL: svg(), chevR: svg(), check: svg(), search: svg( <> ), views: svg( <> ), funnel: svg(), text: svg(), select: svg( <> ), number: svg(), date: svg( <> ), boolean: svg( <> ), status: svg( <> ), priority: svg(), person: svg( <> ), estimate: svg( <> ), clock: svg( <> ), alert: svg( <> ), }; const TYPE_ICON: Record = { text: Icon.text, select: Icon.select, number: Icon.number, date: Icon.date, boolean: Icon.boolean, }; /* ================================================================ sample data */ /** Sample issue-tracker fields used when `fields` is omitted. */ export const defaultSiftFields: SiftField[] = [ { key: "status", label: "Status", type: "select", icon: Icon.status, options: [ { value: "Backlog", color: "#71717a" }, { value: "Todo", color: "#d4d4d8" }, { value: "In progress", color: "#fbbf24" }, { value: "In review", color: "#818cf8" }, { value: "Done", color: "#4ade80" }, { value: "Canceled", color: "#52525b" }, ], }, { key: "priority", label: "Priority", type: "select", icon: Icon.priority, options: [ { value: "Urgent", color: "#f87171" }, { value: "High", color: "#fb923c" }, { value: "Medium", color: "#facc15" }, { value: "Low", color: "#a1a1aa" }, { value: "None", color: "#52525b" }, ], }, { key: "assignee", label: "Assignee", type: "select", icon: Icon.person, options: ["Mara Quill", "Jonah Reyes", "Ines Varga", "Kofi Mensah", "Priya Raman", "Unassigned"], }, { key: "title", label: "Title", type: "text", icon: Icon.text }, { key: "estimate", label: "Estimate", type: "number", icon: Icon.estimate }, { key: "updated", label: "Updated", type: "date", icon: Icon.clock }, { key: "failing", label: "Failing checks", type: "boolean", icon: Icon.alert }, ]; /** Sample saved views for `defaultSiftFields`. */ export const defaultSiftViews: SiftView[] = [ { id: "all", label: "All issues", filters: [] }, { id: "active", label: "Active work", filters: [ { id: "v-active-status", field: "status", operator: "any-of", value: ["Todo", "In progress", "In review"] }, { id: "v-active-est", field: "estimate", operator: "gt", value: 1 }, ], }, { id: "mine", label: "My open", filters: [ { id: "v-mine-who", field: "assignee", operator: "any-of", value: ["Mara Quill"] }, { id: "v-mine-status", field: "status", operator: "none-of", value: ["Done", "Canceled"] }, ], }, { id: "failing", label: "Failing this week", filters: [ { id: "v-fail-bool", field: "failing", operator: "is-true", value: null }, { id: "v-fail-date", field: "updated", operator: "is", value: null, preset: "last-7" }, ], }, { id: "urgent", label: "Urgent & high", filters: [{ id: "v-urgent", field: "priority", operator: "any-of", value: ["Urgent", "High"] }], }, ]; /* ================================================================ date helpers */ const pad = (n: number) => String(n).padStart(2, "0"); function dkey(d: Date): string { return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; } function fromKey(k: string): Date { const [y, m, d] = k.split("-").map(Number); return new Date(y, (m ?? 1) - 1, d ?? 1); } function addDays(k: string, n: number): string { const d = fromKey(k); d.setDate(d.getDate() + n); return dkey(d); } function addMonths(month: string, n: number): string { const [y, m] = month.split("-").map(Number); const d = new Date(y, m - 1 + n, 1); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}`; } /** Coerces a row value (Date, epoch ms, ISO string) to a local `YYYY-MM-DD` key. */ function toKey(v: unknown): string | null { if (v instanceof Date) return Number.isNaN(v.getTime()) ? null : dkey(v); if (typeof v === "number") return Number.isFinite(v) ? dkey(new Date(v)) : null; if (typeof v === "string") { if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return v; const d = new Date(v); return Number.isNaN(d.getTime()) ? null : dkey(d); } return null; } function presetRange(p: SiftDatePreset, today: string): [string, string] { if (p === "today") return [today, today]; if (p === "last-7") return [addDays(today, -6), today]; if (p === "last-30") return [addDays(today, -29), today]; const first = `${today.slice(0, 7)}-01`; return [first, addDays(`${addMonths(today.slice(0, 7), 1)}-01`, -1)]; } function fmtDay(k: string): string { const d = fromKey(k); return `${MONTHS[d.getMonth()]} ${d.getDate()}`; } const subscribeNoop = () => () => {}; /** Local today as `YYYY-MM-DD`; null on the server / during hydration. */ function useTodayKey(override?: string | Date): string | null { const live = React.useSyncExternalStore( subscribeNoop, () => dkey(new Date()), () => null ); if (override) return toKey(override); return live; } /* ================================================================ pure filtering */ function optionsOf(field: SiftField | undefined): Required[] { return (field?.options ?? []).map((o) => typeof o === "string" ? { value: o, label: o, color: "" } : { value: o.value, label: o.label ?? o.value, color: o.color ?? "" } ); } function matches(row: Record, f: SiftFilter, field: SiftField, today: string): boolean { const raw = row[field.key]; switch (field.type) { case "text": { const hay = String(raw ?? "").toLowerCase(); const needle = String(f.value ?? "").toLowerCase(); if (!needle) return true; if (f.operator === "is") return hay === needle; if (f.operator === "is-not") return hay !== needle; if (f.operator === "starts-with") return hay.startsWith(needle); return hay.includes(needle); } case "select": { const sel = Array.isArray(f.value) ? f.value.map(String) : f.value == null ? [] : [String(f.value)]; if (!sel.length) return true; const vals = Array.isArray(raw) ? raw.map(String) : raw == null ? [] : [String(raw)]; const hit = vals.some((v) => sel.includes(v)); return f.operator === "none-of" ? !hit : hit; } case "number": { const n = typeof raw === "number" ? raw : Number(raw); if (raw == null || Number.isNaN(n)) return false; if (f.operator === "between" && Array.isArray(f.value)) { const [a, b] = (f.value as number[]).map(Number); return n >= Math.min(a, b) && n <= Math.max(a, b); } const v = Number(f.value); if (f.operator === "neq") return n !== v; if (f.operator === "gt") return n > v; if (f.operator === "lt") return n < v; return n === v; } case "date": { const k = toKey(raw); if (!k) return false; if (f.preset) { const [a, b] = presetRange(f.preset, today); return k >= a && k <= b; } if (f.operator === "between" && Array.isArray(f.value)) { const [a, b] = (f.value as string[]).map(String).sort(); return k >= a && k <= b; } const v = String(f.value ?? ""); if (!v) return true; if (f.operator === "before") return k < v; if (f.operator === "after") return k > v; return k === v; } case "boolean": return Boolean(raw) === (f.operator === "is-true"); } } /** * Pure helper: returns the rows that satisfy `filters` (AND by default, or OR), * reading `row[field.key]`. Filters for unknown fields are ignored. Date * values may be `Date`s, epoch ms or ISO strings; presets resolve against * `options.now` (default: the current date). */ export function applyFilters( rows: readonly T[], filters: readonly SiftFilter[], fields: readonly SiftField[] = defaultSiftFields, options: { conjunction?: SiftConjunction; now?: Date | string } = {} ): T[] { const active = filters .map((f) => ({ f, field: fields.find((x) => x.key === f.field) })) .filter((x): x is { f: SiftFilter; field: SiftField } => !!x.field); if (!active.length) return rows.slice(); const today = toKey(options.now ?? new Date()) ?? dkey(new Date()); const any = options.conjunction === "or"; return rows.filter((row) => { const r = row as Record; return any ? active.some((x) => matches(r, x.f, x.field, today)) : active.every((x) => matches(r, x.f, x.field, today)); }); } /* ================================================================ misc helpers */ function inkFor(hex: string): string { const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim()); if (!m) return "#0a0a0a"; const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1]; const [r, g, b] = [0, 2, 4].map((i) => { const c = parseInt(h.slice(i, i + 2), 16) / 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; }); const L = 0.2126 * r + 0.7152 * g + 0.0722 * b; return L > 0.36 ? "#0a0a0a" : "#ffffff"; } function sig(filters: readonly SiftFilter[], conj: SiftConjunction): string { return JSON.stringify([conj, filters.map((f) => [f.field, f.operator, f.value, f.preset ?? null])]); } function summarize(field: SiftField, f: SiftFilter): string { switch (field.type) { case "text": return `“${String(f.value ?? "")}”`; case "select": { const opts = optionsOf(field); const labels = (Array.isArray(f.value) ? f.value : []).map( (v) => opts.find((o) => o.value === v)?.label ?? String(v) ); return labels.length > 2 ? `${labels.slice(0, 2).join(", ")} +${labels.length - 2}` : labels.join(", "); } case "number": return Array.isArray(f.value) ? `${f.value[0]} – ${f.value[1]}` : String(f.value ?? ""); case "date": if (f.preset) return PRESET_LABEL[f.preset]; if (Array.isArray(f.value)) { const [a, b] = (f.value as string[]).map(String).sort(); return a === b ? fmtDay(a) : `${fmtDay(a)} – ${fmtDay(b)}`; } return f.value ? fmtDay(String(f.value)) : ""; case "boolean": return ""; } } function describe(field: SiftField, f: SiftFilter): string { const v = summarize(field, f); return `${field.label} ${opLabel(field.type, f.operator)}${v ? ` ${v}` : ""}`; } /* ================================================================ draft */ interface Draft { editingId: string | null; field: string | null; operator: SiftOperator | null; text: string; sel: string[]; numA: string; numB: string; dateA: string | null; dateB: string | null; preset: SiftDatePreset | null; } const EMPTY_DRAFT: Draft = { editingId: null, field: null, operator: null, text: "", sel: [], numA: "", numB: "", dateA: null, dateB: null, preset: null, }; function draftFrom(f: SiftFilter): Draft { const d: Draft = { ...EMPTY_DRAFT, editingId: f.id, field: f.field, operator: f.operator }; const v = f.value; if (typeof v === "string") { d.text = v; d.dateA = /^\d{4}-\d{2}-\d{2}$/.test(v) ? v : null; } if (Array.isArray(v)) { if (typeof v[0] === "number") { d.numA = String(v[0]); d.numB = String(v[1] ?? ""); } else if (f.operator === "between" && v.length === 2 && /^\d{4}-/.test(String(v[0]))) { d.dateA = String(v[0]); d.dateB = String(v[1]); } else d.sel = v.map(String); } if (typeof v === "number") d.numA = String(v); d.preset = f.preset ?? null; return d; } const isNum = (s: string) => s.trim() !== "" && Number.isFinite(Number(s)); function buildFilter(d: Draft, field: SiftField, id: string): SiftFilter | null { const op = d.operator; if (!op) return null; const base = { id, field: field.key, operator: op }; switch (field.type) { case "text": return d.text.trim() ? { ...base, value: d.text.trim() } : null; case "select": return d.sel.length ? { ...base, value: d.sel } : null; case "number": if (op === "between") return isNum(d.numA) && isNum(d.numB) ? { ...base, value: [Number(d.numA), Number(d.numB)].sort((a, b) => a - b) as [number, number] } : null; return isNum(d.numA) ? { ...base, value: Number(d.numA) } : null; case "date": if (d.preset) return { ...base, operator: "is", value: null, preset: d.preset }; if (!d.dateA) return null; if (op === "between") { const pair = [d.dateA, d.dateB ?? d.dateA].sort() as [string, string]; return { ...base, value: pair }; } return { ...base, value: d.dateA }; case "boolean": return op === "is-true" || op === "is-false" ? { ...base, value: null } : null; } } /* ================================================================ small pieces */ type Step = "field" | "operator" | "value"; const STEP_INDEX: Record = { field: 0, operator: 1, value: 2 }; function Dot({ color }: { color: string }) { if (!color) return null; return ; } const FOCUS = "outline-none focus-visible:ring-2 focus-visible:ring-[var(--sift-accent)] focus-visible:ring-offset-1 focus-visible:ring-offset-neutral-900"; /** Keyboard model shared by the listboxes: Up/Down/Home/End move, Enter picks. */ function listKeys( e: React.KeyboardEvent, count: number, active: number, setActive: (n: number) => void, pick: (n: number) => void ) { if (!count) return; if (e.key === "ArrowDown") { e.preventDefault(); setActive((active + 1) % count); } else if (e.key === "ArrowUp") { e.preventDefault(); setActive((active - 1 + count) % count); } else if (e.key === "Home") { e.preventDefault(); setActive(0); } else if (e.key === "End") { e.preventDefault(); setActive(count - 1); } else if (e.key === "Enter") { e.preventDefault(); pick(active); } } function useFocusOnMount() { const ref = React.useRef(null); React.useEffect(() => { ref.current?.focus({ preventScroll: true }); }, []); return ref; } /* ---------------------------------------------------------------- field step */ function FieldStep({ uid, fields, selected, onPick, }: { uid: string; fields: SiftField[]; selected: string | null; onPick: (key: string) => void; }) { const [q, setQ] = React.useState(""); const [active, setActive] = React.useState(() => Math.max(0, fields.findIndex((f) => f.key === selected))); const input = useFocusOnMount(); const shown = React.useMemo(() => { const s = q.trim().toLowerCase(); return s ? fields.filter((f) => f.label.toLowerCase().includes(s)) : fields; }, [fields, q]); const act = Math.min(active, shown.length - 1); const listId = `${uid}-fields`; return (

{Icon.search} { setQ(e.target.value); setActive(0); }} onKeyDown={(e) => listKeys(e, shown.length, act, setActive, (i) => shown[i] && onPick(shown[i].key))} role="combobox" aria-expanded aria-controls={listId} aria-activedescendant={shown[act] ? `${listId}-${shown[act].key}` : undefined} aria-label="Filter by property" placeholder="Filter by…" className="h-9 w-full rounded-lg border border-white/[0.08] bg-white/[0.03] pl-8 pr-2.5 text-[13px] text-white placeholder:text-white/35 outline-none transition-colors focus:border-[color-mix(in_srgb,var(--sift-accent)_45%,transparent)]" />

); } /* ---------------------------------------------------------------- operator step */ function OperatorStep({ uid, type, selected, onPick, }: { uid: string; type: SiftFieldType; selected: SiftOperator | null; onPick: (op: SiftOperator) => void; }) { const ops = OPS[type]; const [active, setActive] = React.useState(() => Math.max(0, ops.findIndex((o) => o.id === selected))); const list = useFocusOnMount(); const listId = `${uid}-ops`; return (

); } /* ---------------------------------------------------------------- value editors */ const INPUT = "h-9 w-full min-w-0 rounded-lg border border-white/[0.08] bg-white/[0.03] px-2.5 text-[13px] text-white tabular-nums placeholder:text-white/30 outline-none transition-colors focus:border-[color-mix(in_srgb,var(--sift-accent)_45%,transparent)]"; function TextEditor({ draft, set, submit }: { draft: Draft; set: (p: Partial) => void; submit: () => void }) { const ref = useFocusOnMount(); return (

set({ text: e.target.value })} onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); submit(); } }} aria-label="Value" placeholder="Type a value…" className={INPUT} />

); } function SelectEditor({ uid, field, draft, set, submit, }: { uid: string; field: SiftField; draft: Draft; set: (p: Partial) => void; submit: () => void; }) { const opts = React.useMemo(() => optionsOf(field), [field]); const [q, setQ] = React.useState(""); const [active, setActive] = React.useState(0); const input = useFocusOnMount(); const shown = React.useMemo(() => { const s = q.trim().toLowerCase(); return s ? opts.filter((o) => o.label.toLowerCase().includes(s)) : opts; }, [opts, q]); const act = Math.min(active, shown.length - 1); const toggle = (v: string) => set({ sel: draft.sel.includes(v) ? draft.sel.filter((x) => x !== v) : [...draft.sel, v] }); const listId = `${uid}-opts`; return (

{Icon.search} { setQ(e.target.value); setActive(0); }} onKeyDown={(e) => { if (e.key === " " && !q) { e.preventDefault(); if (shown[act]) toggle(shown[act].value); return; } if (e.key === "Enter") { e.preventDefault(); // Enter toggles while searching an unselected option; otherwise applies. if (q && shown[act] && !draft.sel.includes(shown[act].value)) { toggle(shown[act].value); setQ(""); } else submit(); return; } listKeys(e, shown.length, act, setActive, () => {}); }} role="combobox" aria-expanded aria-controls={listId} aria-activedescendant={shown[act] ? `${listId}-${act}` : undefined} aria-label={`Search ${field.label.toLowerCase()} (Space toggles, Enter applies)`} placeholder={`Search ${field.label.toLowerCase()}…`} className={cn(INPUT, "pl-8")} />

); } function NumberEditor({ draft, set, submit }: { draft: Draft; set: (p: Partial) => void; submit: () => void }) { const ref = useFocusOnMount(); const between = draft.operator === "between"; const onKey = (e: React.KeyboardEvent) => { if (e.key === "Enter") { e.preventDefault(); submit(); } }; const bad = (s: string) => s.trim() !== "" && !isNum(s); return (

set({ numA: e.target.value })} onKeyDown={onKey} aria-label={between ? "Minimum" : "Value"} aria-invalid={bad(draft.numA) || undefined} placeholder={between ? "Min" : "0"} className={cn(INPUT, bad(draft.numA) && "border-red-400/50")} /> {between && ( <> and set({ numB: e.target.value })} onKeyDown={onKey} aria-label="Maximum" aria-invalid={bad(draft.numB) || undefined} placeholder="Max" className={cn(INPUT, bad(draft.numB) && "border-red-400/50")} /> )}

); } function monthGrid(month: string): string[] { const first = fromKey(`${month}-01`); const offset = (first.getDay() + 6) % 7; const start = addDays(`${month}-01`, -offset); return Array.from({ length: 42 }, (_, i) => addDays(start, i)); } function Calendar({ range, a, b, today, onSelect, submit, }: { range: boolean; a: string | null; b: string | null; today: string; onSelect: (a: string, b: string | null) => void; submit: () => void; }) { const init = a ?? today; const [month, setMonth] = React.useState(init.slice(0, 7)); const [focusKey, setFocusKey] = React.useState(init); const [hover, setHover] = React.useState(null); const [kbd, setKbd] = React.useState(0); const grid = React.useRef(null); const days = React.useMemo(() => monthGrid(month), [month]); const [y, m] = month.split("-").map(Number); React.useEffect(() => { if (!kbd) return; grid.current?.querySelector(`[data-day="${focusKey}"]`)?.focus({ preventScroll: true }); }, [kbd, focusKey]); const lo = a && range ? [a, b ?? hover ?? a].sort()[0] : a; const hi = a && range ? [a, b ?? hover ?? a].sort()[1] : a; const pick = (k: string) => { if (!range) return onSelect(k, null); if (!a || b) return onSelect(k, null); return onSelect(k < a ? k : a, k < a ? a : k); }; const move = (n: number) => { const next = addDays(focusKey, n); setFocusKey(next); if (next.slice(0, 7) !== month) setMonth(next.slice(0, 7)); setKbd((x) => x + 1); }; return (

{MONTHS_LONG[m - 1]} {y}

{[ { d: -1, icon: Icon.chevL, label: "Previous month" }, { d: 1, icon: Icon.chevR, label: "Next month" }, ].map((x) => ( ))}

setHover(null)} onKeyDown={(e) => { const map: Record = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7 }; if (map[e.key] !== undefined) { e.preventDefault(); move(map[e.key]); } else if (e.key === "PageUp" || e.key === "PageDown") { e.preventDefault(); move(e.key === "PageUp" ? -28 : 28); } else if (e.key === "Enter" && a && (!range || b) && focusKey === (range ? b : a)) { e.preventDefault(); submit(); } }} >

{WEEKDAYS.map((w) => ( {w} ))}

{[0, 1, 2, 3, 4, 5].map((r) => (

{days.slice(r * 7, r * 7 + 7).map((k) => { const out = k.slice(0, 7) !== month; const isEnd = k === lo || k === hi; const inside = !!lo && !!hi && k > lo && k < hi; const d = fromKey(k); return (

{(inside || (isEnd && lo !== hi)) && ( )}

); })}

))}

); } function DateEditor({ draft, set, today, submit, }: { draft: Draft; set: (p: Partial) => void; today: string; submit: () => void; }) { const first = useFocusOnMount(); return (

{PRESETS.map((p) => { const on = draft.preset === p.id; return ( ); })}

set({ dateA: a, dateB: b, preset: null })} submit={submit} />

); } /* ================================================================ views menu */ function ViewsMenu({ uid, views, activeId, edited, open, setOpen, onPick, }: { uid: string; views: SiftView[]; activeId: string | null; edited: boolean; open: boolean; setOpen: (o: boolean) => void; onPick: (v: SiftView) => void; }) { const btn = React.useRef(null); const menu = React.useRef(null); const reduced = useReducedMotion(); const active = views.find((v) => v.id === activeId); const menuId = `${uid}-views`; React.useEffect(() => { if (!open) return; const idx = Math.max(0, views.findIndex((v) => v.id === activeId)); const id = requestAnimationFrame(() => menu.current?.querySelectorAll("[role=menuitemradio]")[idx]?.focus({ preventScroll: true }) ); const onDown = (e: PointerEvent) => { if (!menu.current?.contains(e.target as Node) && !btn.current?.contains(e.target as Node)) setOpen(false); }; document.addEventListener("pointerdown", onDown); return () => { cancelAnimationFrame(id); document.removeEventListener("pointerdown", onDown); }; }, [open, views, activeId, setOpen]); const close = () => { setOpen(false); btn.current?.focus({ preventScroll: true }); }; return (

{open && ( )}

); } /* ================================================================ main */ /** * Sift — a structured filter builder for any list or table. "+ Filter" opens * one popover that slides property → operator → value; applied filters become * editable chips joined by an and/or toggle; saved views swap chip sets with a * crossfade. Pair it with the exported `applyFilters(rows, filters, fields)`. */ export function Sift({ fields: fieldsProp, value, defaultValue, onChange, conjunction: conjProp, defaultConjunction = "and", onConjunctionChange, views: viewsProp, defaultView, onViewChange, onSaveView, count, total, noun = { one: "result", other: "results" }, today: todayProp, accentColor = DEFAULT_ACCENT, ref, className, style, onKeyDown, ...rest }: SiftProps) { const reduced = useReducedMotion(); const uid = React.useId().replace(/:/g, ""); const sample = !fieldsProp; const fields = fieldsProp ?? defaultSiftFields; const baseViews = React.useMemo(() => viewsProp ?? (sample ? defaultSiftViews : []), [viewsProp, sample]); const initialViewId = defaultView ?? (sample && !viewsProp ? "active" : baseViews[0]?.id) ?? null; /* ----- state */ const [innerFilters, setInnerFilters] = React.useState( () => defaultValue ?? (sample ? (baseViews.find((v) => v.id === initialViewId)?.filters ?? []) : []) ); const filters = value ?? innerFilters; const [innerConj, setInnerConj] = React.useState(defaultConjunction); const conj = conjProp ?? innerConj; const [saved, setSaved] = React.useState([]); const views = React.useMemo(() => [...baseViews, ...saved], [baseViews, saved]); const [activeViewId, setActiveViewId] = React.useState(initialViewId); const activeView = views.find((v) => v.id === activeViewId); const edited = activeView ? sig(activeView.filters, activeView.conjunction ?? "and") !== sig(filters, conj) : filters.length > 0; const [epoch, setEpoch] = React.useState(0); const [announce, setAnnounce] = React.useState(""); const idSeq = React.useRef(0); const freshId = (prefix: string, taken: string[]) => { let id = ""; do id = `${prefix}-${uid}-${(idSeq.current++).toString(36)}`; while (taken.includes(id)); return id; }; const todayKey = useTodayKey(todayProp) ?? "2026-01-01"; const [pop, setPop] = React.useState<{ anchor: string; step: Step; dir: 1 | -1 } | null>(null); const [popPos, setPopPos] = React.useState<{ left: number; top: number; width: number } | null>(null); const [draft, setDraft] = React.useState(EMPTY_DRAFT); const [viewsOpen, setViewsOpen] = React.useState(false); const [saving, setSaving] = React.useState( null ); const rootRef = React.useRef(null); const addRef = React.useRef(null); const popRef = React.useRef(null); const anchorEl = React.useRef(null); const restoreEl = React.useRef(null); const saveInput = React.useRef(null); /* ----- intro (once in view; falls back on a timer so it never stays hidden) */ const inView = useInView(rootRef, { once: true, amount: 0.2 }); const [forced, setForced] = React.useState(false); const [introKey, setIntroKey] = React.useState(0); React.useEffect(() => { const t = window.setTimeout(() => setForced(true), 1200); return () => window.clearTimeout(t); }, []); const play = reduced || inView || forced; const [introDone, setIntroDone] = React.useState(false); React.useEffect(() => { if (!play || introDone) return; const t = window.setTimeout(() => setIntroDone(true), 900); return () => window.clearTimeout(t); }, [play, introDone, introKey]); /* ----- commits */ const commit = React.useCallback( (next: SiftFilter[], msg?: string, keepView = true) => { if (value === undefined) setInnerFilters(next); onChange?.(next); if (msg) setAnnounce(msg); if (!keepView) setActiveViewId(null); }, [value, onChange] ); const setConj = (c: SiftConjunction) => { if (conjProp === undefined) setInnerConj(c); onConjunctionChange?.(c); setAnnounce(c === "and" ? "Matching all filters" : "Matching any filter"); }; const fieldOf = (key: string | null) => fields.find((f) => f.key === key); /* ----- popover */ const place = React.useCallback(() => { const root = rootRef.current; const a = anchorEl.current; if (!root || !a) return; const r = root.getBoundingClientRect(); const ar = a.getBoundingClientRect(); const width = Math.min(POP_W, r.width - 12); const left = Math.max(6, Math.min(ar.left - r.left, r.width - width - 6)); setPopPos({ left, top: ar.bottom - r.top + 6, width }); }, []); const openAt = (anchor: string, el: HTMLElement | null, step: Step, d: Draft) => { setViewsOpen(false); setSaving(null); anchorEl.current = el; restoreEl.current = (document.activeElement as HTMLElement) ?? el; setDraft(d); setPop({ anchor, step, dir: 1 }); place(); }; const openAdd = (fieldKey?: string) => { const f = fieldKey ? fieldOf(fieldKey) : undefined; openAt("add", addRef.current, f ? "operator" : "field", { ...EMPTY_DRAFT, field: f?.key ?? null }); }; const openEdit = (filter: SiftFilter, step: Step, el: HTMLElement | null) => { if (pop?.anchor === filter.id && pop.step === step) return closePop(true); openAt(filter.id, el, step, draftFrom(filter)); }; const closePop = (restore: boolean) => { setPop(null); if (restore) { const el = restoreEl.current; requestAnimationFrame(() => (el?.isConnected ? el : addRef.current)?.focus({ preventScroll: true })); } }; const go = (step: Step) => setPop((p) => (p ? { ...p, step, dir: STEP_INDEX[step] >= STEP_INDEX[p.step] ? 1 : -1 } : p)); const apply = (d: Draft = draft) => { const field = fieldOf(d.field); if (!field) return; const id = d.editingId ?? freshId("f", filters.map((x) => x.id)); const f = buildFilter(d, field, id); if (!f) return; if (d.editingId) { commit( filters.map((x) => (x.id === d.editingId ? f : x)), `Filter updated: ${describe(field, f)}` ); } else { commit([...filters, f], `Filter added: ${describe(field, f)}`); restoreEl.current = addRef.current; } closePop(true); }; const pickField = (key: string) => { const nf = fieldOf(key); if (!nf) return; const prev = fieldOf(draft.field); const keep = prev && prev.type === nf.type && prev.key === nf.key; const sameType = prev && prev.type === nf.type; setDraft((d) => ({ ...(keep ? d : sameType && nf.type !== "select" ? d : { ...EMPTY_DRAFT, editingId: d.editingId }), field: key, })); go("operator"); }; const pickOperator = (op: SiftOperator) => { const field = fieldOf(draft.field); if (!field) return; let d: Draft = { ...draft, operator: op }; if (field.type === "date" && op !== "is") d = { ...d, preset: null }; if (field.type === "date" && op !== "between") d = { ...d, dateB: null }; if (field.type === "boolean") return apply(d); setDraft(d); // Editing in place: an operator swap that keeps a valid value applies at once. if (draft.editingId && buildFilter(d, field, draft.editingId) && pop?.step === "operator" && draft.operator) { const prevBetween = draft.operator === "between"; if (prevBetween === (op === "between")) return apply(d); } go("value"); }; React.useEffect(() => { if (!pop) return; const root = rootRef.current; const ro = new ResizeObserver(() => place()); if (root) ro.observe(root); const onDown = (e: PointerEvent) => { const t = e.target as Node; if (popRef.current?.contains(t) || anchorEl.current?.contains(t)) return; setPop(null); }; document.addEventListener("pointerdown", onDown); return () => { ro.disconnect(); document.removeEventListener("pointerdown", onDown); }; }, [pop, place]); /* ----- chip ops */ const removeChip = (id: string, focusAfter = false) => { const i = filters.findIndex((x) => x.id === id); if (i < 0) return; const f = filters[i]; const field = fieldOf(f.field); const next = filters.filter((x) => x.id !== id); commit(next, field ? `Removed ${describe(field, f)}` : "Filter removed"); if (pop?.anchor === id) setPop(null); if (focusAfter) { const target = next[Math.max(0, i - 1)]?.id; requestAnimationFrame(() => { const el = target ? rootRef.current?.querySelector(`[data-chip="${target}"] [data-part="field"]`) : addRef.current; el?.focus({ preventScroll: true }); }); } }; const clearAll = () => { if (!filters.length) return; commit([], "All filters cleared"); setPop(null); requestAnimationFrame(() => addRef.current?.focus({ preventScroll: true })); }; const pickView = (v: SiftView) => { setActiveViewId(v.id); setEpoch((e) => e + 1); commit(v.filters, `View: ${v.label}, ${v.filters.length} filter${v.filters.length === 1 ? "" : "s"}`); const c = v.conjunction ?? "and"; if (c !== conj) { if (conjProp === undefined) setInnerConj(c); onConjunctionChange?.(c); } setPop(null); onViewChange?.(v); }; const startSave = () => { setPop(null); setViewsOpen(false); setSaving({ name: "", status: "idle" }); requestAnimationFrame(() => saveInput.current?.focus({ preventScroll: true })); }; const submitSave = async () => { if (!saving || saving.status === "pending") return; const name = saving.name.trim(); if (!name) { setSaving({ ...saving, status: "error", error: "Name the view" }); return; } const view: SiftView = { id: freshId("view", views.map((v) => v.id)), label: name, filters: filters.map((f) => ({ ...f })), conjunction: conj, }; try { const r = onSaveView?.(view); if (r && typeof (r as Promise).then === "function") { setSaving({ name, status: "pending" }); await r; } setSaved((s) => [...s, view]); setActiveViewId(view.id); setSaving(null); setAnnounce(`View saved: ${name}`); } catch (err) { setSaving({ name, status: "error", error: err instanceof Error ? err.message : "Couldn't save view" }); requestAnimationFrame(() => saveInput.current?.focus({ preventScroll: true })); } }; /* ----- handle */ React.useImperativeHandle( ref, () => ({ open: (k?: string) => openAdd(k), close: () => { setPop(null); setViewsOpen(false); }, clear: () => commit([], "All filters cleared"), replay: () => { setIntroDone(false); setIntroKey((k) => k + 1); }, }) ); /* ----- keyboard */ const onRootKey = (e: React.KeyboardEvent) => { onKeyDown?.(e); if (e.defaultPrevented) return; const t = e.target as HTMLElement; const typing = t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable; if (e.key === "Escape" && pop) { e.preventDefault(); closePop(true); return; } if (pop && e.key === "Tab" && popRef.current?.contains(t)) { // Trap focus within the popover. const items = [ ...popRef.current.querySelectorAll( 'button:not([disabled]), input, [tabindex="0"]' ), ].filter((el) => el.offsetParent !== null); if (items.length) { const i = items.indexOf(t); const n = e.shiftKey ? (i <= 0 ? items.length - 1 : i - 1) : i === items.length - 1 ? 0 : i + 1; e.preventDefault(); items[n].focus({ preventScroll: true }); } return; } if (!typing && !pop && e.key.toLowerCase() === "f" && !e.metaKey && !e.ctrlKey && !e.altKey) { e.preventDefault(); addRef.current?.focus({ preventScroll: true }); } }; const onChipKey = (e: React.KeyboardEvent, i: number, id: string) => { if (e.key === "Backspace" || e.key === "Delete") { e.preventDefault(); e.stopPropagation(); removeChip(id, true); } else if (e.key === "ArrowLeft" || e.key === "ArrowRight") { e.preventDefault(); const n = i + (e.key === "ArrowRight" ? 1 : -1); if (n < 0) return; const target = filters[n]?.id; const el = target ? rootRef.current?.querySelector(`[data-chip="${target}"] [data-part="field"]`) : addRef.current; el?.focus({ preventScroll: true }); } }; /* ----- derived render bits */ const accentStyle = { "--sift-accent": accentColor, "--sift-ink": inkFor(accentColor), ...style, } as React.CSSProperties; const popField = fieldOf(draft.field); const popOp = draft.operator && popField ? opLabel(popField.type, draft.operator) : null; const canApply = !!(popField && buildFilter(draft, popField, "x")); const showViews = views.length > 0; const prevCount = usePrev(count); const layoutOn = !reduced; const chipTransition = (i: number): Transition => reduced ? REDUCED_T : { ...SPRING, delay: introDone ? 0 : 0.14 + i * 0.05 }; /* ----- step body */ let body: React.ReactNode = null; if (pop) { if (pop.step === "field") body = ; else if (pop.step === "operator" && popField) body = ; else if (pop.step === "value" && popField) { const set = (p: Partial) => setDraft((d) => ({ ...d, ...p })); const submit = () => apply(); body = popField.type === "text" ? ( ) : popField.type === "select" ? ( ) : popField.type === "number" ? ( ) : popField.type === "date" ? ( ) : null; } } return (

{/* header: views · count · save */}

{showViews ? ( { if (o) setPop(null); setViewsOpen(o); }} onPick={pickView} /> ) : ( {Icon.funnel}Filters )}

{count !== undefined && ( {reduced ? ( {count} ) : ( )} {total !== undefined && of {total}} {count === 1 ? noun.one : noun.other} )} {onSaveView && ( {saving ? ( { e.preventDefault(); void submitSave(); }} className="flex items-center gap-1" > setSaving({ name: e.target.value, status: "idle" })} onKeyDown={(e) => { if (e.key === "Escape") { e.preventDefault(); e.stopPropagation(); setSaving(null); } }} onBlur={(e) => { if (!saving.name.trim() && !e.currentTarget.form?.contains(e.relatedTarget as Node)) setSaving(null); }} animate={saving.status === "error" && !reduced ? { x: [0, -4, 4, -2, 0] } : { x: 0 }} transition={{ duration: 0.3 }} aria-label="View name" aria-invalid={saving.status === "error" || undefined} title={saving.error} placeholder={saving.error ?? "View name"} maxLength={40} className={cn( "h-8 w-[min(11rem,40cqw)] rounded-lg border bg-white/[0.04] px-2.5 text-[13px] text-white placeholder:text-white/35 outline-none transition-colors focus:border-[color-mix(in_srgb,var(--sift-accent)_50%,transparent)] disabled:opacity-60", saving.status === "error" ? "border-red-400/50 placeholder:text-red-300/70" : "border-white/10" )} /> ) : ( Save view )} )}

{/* chips row — views crossfade by stacking epochs in one grid cell */}

{filters.map((f, i) => { const field = fieldOf(f.field); if (!field) return null; const val = summarize(field, f); const on = pop?.anchor === f.id; const opts = field.type === "select" ? optionsOf(field) : []; const firstColor = field.type === "select" && Array.isArray(f.value) && f.value.length === 1 ? (opts.find((o) => o.value === (f.value as string[])[0])?.color ?? "") : ""; return ( {i > 0 && ( )}

onChipKey(e, i, f.id)} className={cn( "flex h-8 max-w-full items-stretch overflow-hidden rounded-[9px] border bg-white/[0.035] transition-[border-color,box-shadow,background-color] duration-200", on ? "border-[color-mix(in_srgb,var(--sift-accent)_55%,transparent)] bg-[color-mix(in_srgb,var(--sift-accent)_7%,transparent)] shadow-[0_0_0_3px_color-mix(in_srgb,var(--sift-accent)_12%,transparent)]" : "border-white/[0.09] hover:border-white/[0.14]" )} > openEdit(f, "field", e.currentTarget.closest("[data-chip]"))} className="gap-1.5 pl-2.5 text-white/60" > {field.icon ?? TYPE_ICON[field.type]} {field.label} openEdit(f, "operator", e.currentTarget.closest("[data-chip]"))} className={cn("text-white/40", opLabel(field.type, f.operator).length === 1 && "font-mono")} > {opLabel(field.type, f.operator)} {val && ( openEdit(f, "value", e.currentTarget.closest("[data-chip]"))} className="min-w-0 gap-1.5 font-medium text-[var(--sift-accent)]" > {val} )}

); })} {/* Add + Clear all wrap together, so "Clear all" never lands alone on a row. */} (pop?.anchor === "add" ? closePop(true) : openAdd())} initial={{ opacity: 0, y: 3 }} animate={play ? { opacity: 1, y: 0 } : undefined} transition={reduced ? REDUCED_T : { ...SPRING, delay: introDone ? 0 : 0.14 + filters.length * 0.05 }} className={cn( "flex h-8 items-center gap-1.5 rounded-[9px] border border-dashed px-2.5 text-[12.5px] font-medium transition-colors", pop?.anchor === "add" ? "border-[color-mix(in_srgb,var(--sift-accent)_55%,transparent)] bg-white/[0.05] text-white" : "border-white/15 text-white/60 hover:border-white/25 hover:bg-white/[0.03] hover:text-white", FOCUS )} > {Icon.plus} Filter F {!filters.length && ( No filters — showing everything )} {filters.length > 0 && ( Clear all )}

{/* popover */} {pop && popPos && ( )} {announce}

); } /* ================================================================ internals */ function usePrev(value: T): T | undefined { const [state, setState] = React.useState<{ current: T; previous: T | undefined }>({ current: value, previous: undefined }); if (!Object.is(state.current, value)) setState({ current: value, previous: state.current }); return state.previous; } function ChipPart({ part, label, onClick, className, children, }: { part: string; label: string; onClick: (e: React.MouseEvent) => void; className?: string; children: React.ReactNode; }) { return ( ); } function StepDots({ step }: { step: Step }) { const n = STEP_INDEX[step]; return ( {[0, 1, 2].map((i) => ( ))} ); } /** Slides step content horizontally and springs the popover height to fit. */ function PopBody({ stepKey, dir, reduced, children, }: { stepKey: string; dir: 1 | -1; reduced: boolean; children: React.ReactNode; }) { const inner = React.useRef(null); const [h, setH] = React.useState("auto"); React.useEffect(() => { const el = inner.current; if (!el) return; const ro = new ResizeObserver(() => setH(el.offsetHeight)); ro.observe(el); return () => ro.disconnect(); }, []); return (

(reduced ? { opacity: 0 } : { opacity: 0, x: d * 28 }), center: { opacity: 1, x: 0 }, exit: (d: number) => (reduced ? { opacity: 0 } : { opacity: 0, x: d * -28 }), }} initial="enter" animate="center" exit="exit" transition={reduced ? FADE : { ...SLIDE, opacity: { duration: 0.16 } }} className="w-full" > {children}

); } ```