@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/data-table/saved-views.js

@@ -0,0 +1,251 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, ChevronDown, Copy, Link2, MoreHorizontal, Pencil, Plus, Star, Trash2, Users } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { getCollator } from "../lib/text.js";
+import { useContainerWidth } from "../lib/use-container-width.js";
+import { ConfirmDialog } from "../components/alert-dialog.js";
+import { Button } from "../components/button.js";
+import { Checkbox } from "../components/checkbox.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader } from "../components/dialog.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger } from "../components/dropdown-menu.js";
+import { Field, Input } from "../components/input.js";
+import { RadioGroup } from "../components/radio-group.js";
+import { Tooltip } from "../components/tooltip.js";
+import { toast } from "../components/toast.js";
+import { viewStateEqual } from "./view-state.js";
+export const savedViewsLabels = {
+    label: "Views",
+    all: "All",
+    more: "More",
+    moreAria: "More views",
+    create: "View",
+    createAria: "Save current view",
+    modified: "Modified",
+    modifiedAnnounce: "View modified.",
+    save: "Save",
+    saveAs: "Save as new",
+    reset: "Reset",
+    readOnlyReason: "Only the owner can change this team view. Save a copy instead.",
+    actions: "View actions for {name}",
+    rename: "Rename",
+    duplicate: "Duplicate",
+    setDefault: "Set as default",
+    isDefault: "Default view",
+    copyLink: "Copy link",
+    linkCopied: "Link copied",
+    delete: "Delete view",
+    deleteTitle: "Delete “{name}”?",
+    deleteDescription: "The view is removed for everyone who can see it. The records stay as they are.",
+    deleteConfirm: "Delete view",
+    dialogCreate: "Save view",
+    dialogCreateDescription: "Saves the current filters, sort and columns.",
+    dialogRename: "Rename view",
+    name: "Name",
+    namePlaceholder: "e.g. Hot leads this month",
+    nameRequired: "Give the view a name.",
+    scope: "Visible to",
+    personal: "Only me",
+    team: "Everyone on the team",
+    makeDefault: "Open this view by default",
+    cancel: "Cancel",
+    confirmSave: "Save view",
+    confirmRename: "Rename",
+    saving: "Saving…",
+    saveError: "Couldn’t save the view. Try again.",
+    copyOf: "{name} copy",
+    teamView: "Team view",
+    selectAria: "Current view: {name}",
+};
+function defaultShareUrl(id) {
+    if (typeof window === "undefined")
+        return "";
+    const url = new URL(window.location.href);
+    url.searchParams.set("sv", id);
+    return url.toString();
+}
+/**
+ * Named list configurations — "My open deals", "Hot leads", "Probation ending" — as tabs above a
+ * list. Switching applies filters, sort and columns; changes show a "Modified" strip with Save,
+ * Save as new and Reset. Persistence is the app's job; the kit provides shape, dirty state and links.
+ *
+ * ```tsx
+ * <SavedViews views={views} {...table.savedViewsBinding(views)} onSave={create} onUpdate={update} />
+ * ```
+ */
+export const SavedViews = React.forwardRef(function SavedViews({ views, activeId, current, isDirty: dirtyProp, onSelect, onSave, onUpdate, onRename, onDelete, onSetDefault, onReset, getShareUrl = defaultShareUrl, permissions, variant = "auto", showAll = true, maxVisible = 4, sortByName, panelId, size = "md", labels, className, ...props }, ref) {
+    const t = useLabels("savedViews", savedViewsLabels, labels);
+    const { locale } = useLocale();
+    const { ref: measureRef, width } = useContainerWidth();
+    const asSelect = variant === "select" || (variant === "auto" && width !== undefined && width < 420);
+    const [dialog, setDialog] = React.useState(null);
+    const [confirmDelete, setConfirmDelete] = React.useState(null);
+    const [saving, setSaving] = React.useState(false);
+    const [announce, setAnnounce] = React.useState("");
+    const tabRefs = React.useRef(new Map());
+    const [focusKey, setFocusKey] = React.useState(null);
+    const ordered = React.useMemo(() => {
+        const list = [...views];
+        if (sortByName) {
+            const c = getCollator(locale);
+            list.sort((a, b) => Number(Boolean(b.system)) - Number(Boolean(a.system)) || c.compare(a.name, b.name));
+        }
+        return list;
+    }, [views, sortByName, locale]);
+    const active = activeId ? (views.find((v) => v.id === activeId) ?? null) : null;
+    const dirty = dirtyProp ?? (active ? !viewStateEqual(current, active.state) : false);
+    const canEdit = (v) => !v.system && (permissions?.canEdit ? permissions.canEdit(v) : true);
+    React.useEffect(() => {
+        if (dirty)
+            setAnnounce(t("modifiedAnnounce"));
+        else
+            setAnnounce("");
+    }, [dirty, t]);
+    const visible = ordered.slice(0, maxVisible);
+    if (active && !visible.includes(active))
+        visible.push(active);
+    const overflow = ordered.filter((v) => !visible.includes(v));
+    const keyOf = (id) => id ?? "__all";
+    const tabKeys = [...(showAll ? [null] : []), ...visible.map((v) => v.id)];
+    const activeKey = keyOf(activeId);
+    const rovingKey = focusKey && tabKeys.some((k) => keyOf(k) === focusKey) ? focusKey : activeKey;
+    const onTabKeyDown = (e, index) => {
+        const rtl = getComputedStyle(e.currentTarget).direction === "rtl";
+        let to = -1;
+        if (e.key === (rtl ? "ArrowLeft" : "ArrowRight"))
+            to = (index + 1) % tabKeys.length;
+        else if (e.key === (rtl ? "ArrowRight" : "ArrowLeft"))
+            to = (index - 1 + tabKeys.length) % tabKeys.length;
+        else if (e.key === "Home")
+            to = 0;
+        else if (e.key === "End")
+            to = tabKeys.length - 1;
+        if (to === -1)
+            return;
+        e.preventDefault();
+        const key = keyOf(tabKeys[to]);
+        setFocusKey(key);
+        tabRefs.current.get(key)?.focus();
+    };
+    const copyLink = async (id) => {
+        const url = getShareUrl(id);
+        try {
+            await navigator.clipboard.writeText(url);
+            toast.success(t("linkCopied"));
+        }
+        catch {
+            /* clipboard blocked: nothing to do */
+        }
+    };
+    const update = async () => {
+        if (!active || !onUpdate || !canEdit(active))
+            return;
+        setSaving(true);
+        try {
+            await onUpdate(active.id, current);
+        }
+        catch {
+            toast.danger(t("saveError"));
+        }
+        finally {
+            setSaving(false);
+        }
+    };
+    const duplicate = async (v) => {
+        if (!onSave)
+            return;
+        try {
+            const created = await onSave({ name: t("copyOf", { name: v.name }), scope: "personal", state: v.state });
+            if (created)
+                onSelect(created.id);
+        }
+        catch {
+            toast.danger(t("saveError"));
+        }
+    };
+    const tabClass = cn("group/tab relative inline-flex shrink-0 items-center gap-1.5 rounded-ui-sm px-2.5 font-medium whitespace-nowrap transition-colors focus-ring", size === "sm" ? "h-7 text-xs" : "h-8 text-[13px]", "text-fg-muted hover:bg-hover hover:text-fg aria-selected:bg-selected aria-selected:text-fg");
+    const tab = (v, index) => {
+        const key = keyOf(v?.id ?? null);
+        const selected = key === activeKey;
+        const Icon = v?.icon;
+        return (_jsxs("button", { ref: (el) => {
+                if (el)
+                    tabRefs.current.set(key, el);
+                else
+                    tabRefs.current.delete(key);
+            }, type: "button", role: "tab", id: `${key}-tab`, "aria-selected": selected, "aria-controls": panelId, tabIndex: key === rovingKey ? 0 : -1, onFocus: () => setFocusKey(key), onKeyDown: (e) => onTabKeyDown(e, index), onClick: () => !selected && onSelect(v?.id ?? null), className: tabClass, "data-slot": "saved-view-tab", children: [Icon ? _jsx(Icon, { className: "size-3.5 shrink-0 text-fg-subtle group-aria-selected/tab:text-fg-muted" }) : null, _jsx("span", { className: "max-w-[12rem] truncate", children: v ? v.name : t("all") }), v?.scope === "team" ? _jsx(Users, { "aria-label": t("teamView"), className: "size-3 shrink-0 text-fg-subtle" }) : null, selected && dirty ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-accent-ink" }), _jsxs("span", { className: "sr-only", children: [", ", t("modified")] })] })) : null] }, key));
+    };
+    const actionsMenu = active ? (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("actions", { name: active.name }), className: cn("inline-flex shrink-0 items-center justify-center rounded-ui-sm text-fg-subtle transition-colors hover:bg-hover hover:text-fg focus-ring", size === "sm" ? "size-7" : "size-8"), children: _jsx(MoreHorizontal, { "aria-hidden": true, className: "size-4" }) }) }), _jsxs(DropdownMenuContent, { align: "start", size: "sm", children: [onRename ? (_jsx(DropdownMenuItem, { icon: _jsx(Pencil, {}), disabled: !canEdit(active), onSelect: () => setDialog({ kind: "rename", view: active }), children: t("rename") })) : null, onSave ? (_jsx(DropdownMenuItem, { icon: _jsx(Copy, {}), onSelect: () => duplicate(active), children: t("duplicate") })) : null, onSetDefault ? (_jsx(DropdownMenuItem, { icon: active.isDefault ? _jsx(Check, {}) : _jsx(Star, {}), disabled: active.isDefault, onSelect: () => onSetDefault(active.id), children: active.isDefault ? t("isDefault") : t("setDefault") })) : null, _jsx(DropdownMenuItem, { icon: _jsx(Link2, {}), onSelect: () => copyLink(active.id), children: t("copyLink") }), onDelete && canEdit(active) ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { icon: _jsx(Trash2, {}), tone: "danger", onSelect: () => setConfirmDelete(active), children: t("delete") })] })) : null] })] })) : null;
+    const createButton = onSave ? (_jsxs("button", { type: "button", onClick: () => setDialog({ kind: "create" }), "aria-label": t("createAria"), className: cn("inline-flex shrink-0 items-center gap-1 rounded-ui-sm px-2 font-medium text-fg-subtle transition-colors hover:bg-hover hover:text-fg focus-ring", size === "sm" ? "h-7 text-xs" : "h-8 text-[13px]"), children: [_jsx(Plus, { "aria-hidden": true, className: "size-3.5", strokeWidth: 2.25 }), t("create")] })) : null;
+    const readOnlyActive = active ? !canEdit(active) : true;
+    const saveButton = (_jsx(Button, { size: "xs", variant: "ghost", className: "text-accent-ink", "aria-disabled": readOnlyActive || !onUpdate || undefined, loading: saving, onClick: () => (readOnlyActive ? undefined : update()), children: t("save") }));
+    const dirtyStrip = dirty && active ? (_jsxs("div", { "data-slot": "saved-views-dirty", className: "ui-fade flex shrink-0 items-center gap-0.5 ps-1 text-xs", children: [_jsxs("span", { className: "me-1 hidden items-center gap-1.5 text-fg-muted sm:inline-flex", children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-accent-ink" }), t("modified")] }), onUpdate ? readOnlyActive ? _jsx(Tooltip, { content: t("readOnlyReason"), children: saveButton }) : saveButton : null, onSave ? (_jsx(Button, { size: "xs", variant: "ghost", onClick: () => setDialog({ kind: "create" }), children: t("saveAs") })) : null, _jsx(Button, { size: "xs", variant: "ghost", className: "text-fg-muted", onClick: onReset, children: t("reset") })] })) : null;
+    const body = asSelect ? (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": t("selectAria", { name: active?.name ?? t("all") }), className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-ui-sm px-2.5 font-medium text-fg transition-colors hover:bg-hover focus-ring", size === "sm" ? "h-7 text-xs" : "h-8 text-[13px]"), children: [_jsx("span", { className: "truncate", children: active?.name ?? t("all") }), dirty ? _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-accent-ink" }) : null, _jsx(ChevronDown, { "aria-hidden": true, className: "size-3.5 shrink-0 text-fg-subtle" })] }) }), _jsxs(DropdownMenuContent, { align: "start", size: "md", children: [_jsx(DropdownMenuLabel, { children: t("label") }), _jsxs(DropdownMenuRadioGroup, { value: activeKey, onValueChange: (k) => onSelect(k === "__all" ? null : k), children: [showAll ? _jsx(DropdownMenuRadioItem, { value: "__all", children: t("all") }) : null, ordered.map((v) => (_jsx(DropdownMenuRadioItem, { value: v.id, children: v.name }, v.id)))] }), onSave ? (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { icon: _jsx(Plus, {}), onSelect: () => setDialog({ kind: "create" }), children: t("createAria") })] })) : null] })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { role: "tablist", "aria-label": t("label"), className: "flex min-w-0 items-center gap-0.5 overflow-x-auto scrollbar-none", children: tabKeys.map((k, i) => tab(k === null ? null : views.find((v) => v.id === k), i)) }), overflow.length ? (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": t("moreAria"), className: cn("inline-flex shrink-0 items-center gap-1 rounded-ui-sm px-2 font-medium text-fg-muted transition-colors hover:bg-hover hover:text-fg focus-ring", size === "sm" ? "h-7 text-xs" : "h-8 text-[13px]"), children: [t("more"), _jsx(ChevronDown, { "aria-hidden": true, className: "size-3.5 text-fg-subtle" })] }) }), _jsx(DropdownMenuContent, { align: "start", size: "md", children: overflow.map((v) => (_jsx(DropdownMenuItem, { onSelect: () => onSelect(v.id), children: v.name }, v.id))) })] })) : null] }));
+    return (_jsxs("div", { ref: (node) => {
+            measureRef(node);
+            if (typeof ref === "function")
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, "data-slot": "saved-views", "data-variant": asSelect ? "select" : "tabs", className: cn("flex min-w-0 items-center gap-1", className), ...props, children: [body, actionsMenu, createButton, dirtyStrip, _jsx("span", { "aria-live": "polite", className: "sr-only", children: announce }), _jsx(SavedViewDialog, { state: dialog, t: t, canCreateTeam: permissions?.canCreateTeam, saving: saving, onClose: () => setDialog(null), onSubmit: async ({ name, scope, isDefault }) => {
+                    setSaving(true);
+                    try {
+                        if (dialog?.kind === "rename") {
+                            await onRename?.(dialog.view.id, name);
+                        }
+                        else {
+                            const created = await onSave?.({ name, scope, isDefault });
+                            if (created)
+                                onSelect(created.id);
+                        }
+                        setDialog(null);
+                        return null;
+                    }
+                    catch {
+                        return t("saveError");
+                    }
+                    finally {
+                        setSaving(false);
+                    }
+                } }), _jsx(ConfirmDialog, { open: confirmDelete !== null, tone: "danger", title: t("deleteTitle", { name: confirmDelete?.name ?? "" }), description: t("deleteDescription"), confirmLabel: t("deleteConfirm"), onConfirm: async () => {
+                    if (confirmDelete)
+                        await onDelete?.(confirmDelete.id);
+                }, onResult: (ok) => {
+                    if (ok && confirmDelete && confirmDelete.id === activeId)
+                        onSelect(views.find((v) => v.isDefault && v.id !== confirmDelete.id)?.id ?? null);
+                    setConfirmDelete(null);
+                } })] }));
+});
+function SavedViewDialog({ state, t, canCreateTeam, saving, onClose, onSubmit, }) {
+    const [name, setName] = React.useState("");
+    const [scope, setScope] = React.useState("personal");
+    const [isDefault, setIsDefault] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const open = state !== null;
+    React.useEffect(() => {
+        if (!state)
+            return;
+        setName(state.kind === "rename" ? state.view.name : "");
+        setScope("personal");
+        setIsDefault(false);
+        setError(null);
+    }, [state]);
+    const rename = state?.kind === "rename";
+    const submit = async (e) => {
+        e.preventDefault();
+        if (!name.trim()) {
+            setError(t("nameRequired"));
+            return;
+        }
+        const err = await onSubmit({ name: name.trim(), scope, isDefault });
+        if (err)
+            setError(err);
+    };
+    return (_jsx(Dialog, { open: open, onOpenChange: (o) => !o && onClose(), children: _jsx(DialogContent, { size: "sm", children: _jsxs("form", { onSubmit: submit, noValidate: true, className: "contents", children: [_jsx(DialogHeader, { title: rename ? t("dialogRename") : t("dialogCreate"), description: rename ? undefined : t("dialogCreateDescription") }), _jsxs(DialogBody, { className: "grid gap-4", children: [_jsx(Field, { label: t("name"), error: error ?? undefined, required: true, children: _jsx(Input, { "data-autofocus": true, value: name, placeholder: t("namePlaceholder"), maxLength: 60, onChange: (e) => setName(e.target.value) }) }), !rename && canCreateTeam ? (_jsx(Field, { label: t("scope"), children: _jsx(RadioGroup, { value: scope, onValueChange: (v) => setScope(v), items: [
+                                        { value: "personal", label: t("personal") },
+                                        { value: "team", label: t("team") },
+                                    ] }) })) : null, !rename ? _jsx(Checkbox, { label: t("makeDefault"), checked: isDefault, onCheckedChange: (c) => setIsDefault(c === true) }) : null] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "ghost", onClick: onClose, children: t("cancel") }), _jsx(Button, { type: "submit", variant: "primary", loading: saving, loadingText: t("saving"), children: rename ? t("confirmRename") : t("confirmSave") })] })] }) }) }));
+}

package/dist/data-table/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Shared list-state contract for Data Table, Filter bar, Saved views, Kanban, Calendar and any
+ * other collection view. React-free at runtime (type-only React import), so it can be imported
+ * in server components and API routes: the same `ListState` drives the UI, the URL and the
+ * server query.
+ */
+import type { ComponentType, ReactNode } from "react";
+/** Value type of a field. Decides operators, value editor, formatting and sorting. */
+export type FieldType = "text" | "number" | "currency" | "percent" | "date" | "datetime" | "enum" | "boolean" | "user" | "tags";
+/** Filter operator. Semantics are documented in `filter-fns.ts` and are the same on the server. */
+export type FilterOp = "contains" | "notContains" | "eq" | "neq" | "startsWith" | "isEmpty" | "isNotEmpty" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "notIn" | "before" | "after" | "on" | "relative";
+export type RelativeDatePreset = "today" | "yesterday" | "this_week" | "last_7_days" | "last_30_days" | "last_90_days" | "this_month" | "last_month" | "this_quarter" | "this_year";
+/** A date range relative to "now", resolved at query time (so saved views stay current). */
+export type RelativeDate = RelativeDatePreset | {
+    last: number;
+    unit: "day" | "week" | "month";
+};
+/** One condition: `{ field: "stage", op: "in", value: ["proposal", "won"] }`. */
+export interface FilterClause {
+    /** Stable id (chip key, focus management). */
+    id: string;
+    field: string;
+    op: FilterOp;
+    /**
+     * `in`/`notIn` → `string[]`; `between` → `[min, max]` (numbers or `YYYY-MM-DD`);
+     * `relative` → `RelativeDate`; `isEmpty`/`isNotEmpty` → none; otherwise a scalar.
+     * Dates are `YYYY-MM-DD` strings, money a decimal string or number. `"$me"` = the current user.
+     */
+    value?: unknown;
+}
+/** A group of clauses. The root is always a group; nested groups are the advanced mode. */
+export interface FilterGroup {
+    logic: "and" | "or";
+    clauses: Array<FilterClause | FilterGroup>;
+}
+/** Symbolic "current user" value for user fields. Resolved at query time so team views work for everyone. */
+export declare const ME = "$me";
+/** Option of an enum / user / tags field. */
+export interface FilterOption {
+    value: string;
+    label: string;
+    /** Leading visual (avatar, status dot). */
+    icon?: ReactNode;
+    /** Badge tone used by the Data Table's default enum cell. */
+    tone?: "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+    /** Extra search terms. */
+    keywords?: string[];
+}
+/** A filterable field. Data Table generates these from its columns (`filterFieldsFromColumns`). */
+export interface FilterFieldDef {
+    field: string;
+    label: string;
+    type: FieldType;
+    /** Icon component (e.g. a lucide icon) shown in the field picker. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Allowed operators, in menu order. Default: `defaultOps(type)`. */
+    ops?: FilterOp[];
+    /** Enum / user / tags options. A function = async server search (`q` is the typed text). */
+    options?: FilterOption[] | ((q: string) => Promise<FilterOption[]>);
+    /** Pinned in the bar as an empty chip ("Status ▾") even without a value. */
+    quick?: boolean;
+    /** Enum: `false` → single value (`eq`) instead of `in`. Default `true`. */
+    multiple?: boolean;
+    /** Section in the field picker ("Contact", "Company"). */
+    group?: string;
+    /** ISO 4217 code for `currency` fields. Default: the locale provider's currency. */
+    currency?: string;
+    /** Client filtering: read the value from a row. Default `row[field]`. */
+    accessor?: (row: any) => unknown;
+    /** Input placeholder in the value editor. */
+    placeholder?: string;
+}
+export interface SortClause {
+    id: string;
+    desc: boolean;
+}
+export type OffsetPage = {
+    index: number;
+    size: number;
+};
+export type CursorPage = {
+    cursor: string | null;
+    size: number;
+};
+export type PageState = OffsetPage | CursorPage;
+export interface ColumnsState {
+    /** Missing key = visible. */
+    visible: Record<string, boolean>;
+    /** Column ids in display order. Missing ids keep their definition order after the listed ones. */
+    order: string[];
+    /** Widths in px. */
+    sizing: Record<string, number>;
+    /** Pinned to the inline start / end (RTL-aware). */
+    pinned: {
+        start: string[];
+        end: string[];
+    };
+}
+export type ListDensity = "compact" | "comfortable" | "spacious";
+/** Everything a list screen needs to reproduce what the user sees. Serializable. */
+export interface ListState {
+    q: string;
+    filters: FilterGroup;
+    sort: SortClause[];
+    page: PageState;
+    columns: ColumnsState;
+    density?: ListDensity;
+    /** Active saved view id. */
+    view?: string | null;
+    groupBy?: string | null;
+}
+export type ListStateChangeReason = "search" | "filters" | "sort" | "page" | "pageSize" | "columns" | "density" | "view" | "reset";
+/**
+ * Row selection. `ids` survives paging. `all` spans every page of a server-mode list: it carries
+ * a snapshot of the query it was made for (and resets when the query changes).
+ */
+export type DataTableSelection = {
+    mode: "ids";
+    ids: string[];
+} | {
+    mode: "all";
+    except: string[];
+    filters: FilterGroup;
+    q: string;
+    total: number;
+};
+export declare const emptySelection: () => DataTableSelection;
+export declare function selectionCount(s: DataTableSelection): number;
+export declare function isRowSelected(s: DataTableSelection, id: string): boolean;
+/** What a saved view stores: the list state without the position (page, cursor). */
+export type ViewState = Omit<ListState, "page" | "q" | "view"> & {
+    q?: string;
+    pageSize?: number;
+};
+export interface SavedView {
+    id: string;
+    name: string;
+    state: ViewState;
+    scope: "personal" | "team";
+    isDefault?: boolean;
+    /** Icon component shown before the name. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    ownerId?: string;
+    /** Built in (e.g. "All open deals"): cannot be renamed or deleted. */
+    system?: boolean;
+}
+export declare const emptyFilterGroup: () => FilterGroup;
+export declare const emptyColumnsState: () => ColumnsState;
+export declare const isFilterGroup: (c: FilterClause | FilterGroup) => c is FilterGroup;
+export declare const isCursorPage: (p: PageState) => p is CursorPage;
+/** A complete `ListState` from a partial one (missing parts get defaults). */
+export declare function createListState(partial?: Partial<ListState>, pageSize?: number): ListState;
+/** Root-level clauses (nested groups flattened depth-first). */
+export declare function flattenClauses(g: FilterGroup): FilterClause[];
+/** Operators per field type, in menu order. */
+export declare function defaultOps(type: FieldType): FilterOp[];
+/** Operators of a field, honouring `multiple: false` (single-valued enum → `eq`/`neq`). */
+export declare function fieldOps(field: FilterFieldDef): FilterOp[];
+/** Operators that take no value. */
+export declare const opTakesNoValue: (op: FilterOp) => boolean;
+/** `true` when a clause has what its operator needs (an incomplete clause is never applied). */
+export declare function isClauseComplete(c: FilterClause): boolean;
+/** A short unique clause id. */
+export declare const clauseId: () => string;

package/dist/data-table/types.js

@@ -0,0 +1,87 @@
+/** Symbolic "current user" value for user fields. Resolved at query time so team views work for everyone. */
+export const ME = "$me";
+export const emptySelection = () => ({ mode: "ids", ids: [] });
+export function selectionCount(s) {
+    return s.mode === "ids" ? s.ids.length : Math.max(0, s.total - s.except.length);
+}
+export function isRowSelected(s, id) {
+    return s.mode === "ids" ? s.ids.includes(id) : !s.except.includes(id);
+}
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+export const emptyFilterGroup = () => ({ logic: "and", clauses: [] });
+export const emptyColumnsState = () => ({ visible: {}, order: [], sizing: {}, pinned: { start: [], end: [] } });
+export const isFilterGroup = (c) => "clauses" in c;
+export const isCursorPage = (p) => "cursor" in p;
+/** A complete `ListState` from a partial one (missing parts get defaults). */
+export function createListState(partial = {}, pageSize = 25) {
+    return {
+        q: partial.q ?? "",
+        filters: partial.filters ?? emptyFilterGroup(),
+        sort: partial.sort ?? [],
+        page: partial.page ?? { index: 0, size: pageSize },
+        columns: { ...emptyColumnsState(), ...partial.columns, pinned: { start: [], end: [], ...partial.columns?.pinned } },
+        density: partial.density,
+        view: partial.view ?? null,
+        groupBy: partial.groupBy ?? null,
+    };
+}
+/** Root-level clauses (nested groups flattened depth-first). */
+export function flattenClauses(g) {
+    const out = [];
+    for (const c of g.clauses) {
+        if (isFilterGroup(c))
+            out.push(...flattenClauses(c));
+        else
+            out.push(c);
+    }
+    return out;
+}
+/** Operators per field type, in menu order. */
+export function defaultOps(type) {
+    switch (type) {
+        case "text":
+            return ["contains", "notContains", "eq", "startsWith", "isEmpty", "isNotEmpty"];
+        case "number":
+        case "currency":
+        case "percent":
+            return ["eq", "neq", "gt", "gte", "lt", "lte", "between", "isEmpty"];
+        case "date":
+        case "datetime":
+            return ["on", "before", "after", "between", "relative", "isEmpty"];
+        case "enum":
+        case "tags":
+            return ["in", "notIn", "isEmpty"];
+        case "boolean":
+            return ["eq"];
+        case "user":
+            return ["in", "notIn", "isEmpty"];
+    }
+}
+/** Operators of a field, honouring `multiple: false` (single-valued enum → `eq`/`neq`). */
+export function fieldOps(field) {
+    if (field.ops)
+        return field.ops;
+    if (field.type === "enum" && field.multiple === false)
+        return ["eq", "neq", "isEmpty"];
+    return defaultOps(field.type);
+}
+/** Operators that take no value. */
+export const opTakesNoValue = (op) => op === "isEmpty" || op === "isNotEmpty";
+/** `true` when a clause has what its operator needs (an incomplete clause is never applied). */
+export function isClauseComplete(c) {
+    if (opTakesNoValue(c.op))
+        return true;
+    const v = c.value;
+    if (v === undefined || v === null || v === "")
+        return false;
+    if (c.op === "in" || c.op === "notIn")
+        return Array.isArray(v) && v.length > 0;
+    if (c.op === "between")
+        return Array.isArray(v) && v.length === 2 && v[0] !== "" && v[1] !== "" && v[0] != null && v[1] != null;
+    return true;
+}
+let clauseSeq = 0;
+/** A short unique clause id. */
+export const clauseId = () => `c${Date.now().toString(36)}${(++clauseSeq).toString(36)}`;

package/dist/data-table/url-state.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `ListState` ⇄ URL search params. React-free: `parseListState()` runs in a server component so
+ * the first HTML already has the right rows.
+ *
+ * `?q=jane&f=stage.in:proposal|won;value.gte:5000;created.relative:last_30_days&sort=-createdAt,name&page=2&size=50&sv=v_8k2`
+ *
+ * - values are URI-encoded; `|` separates multiple values (`in`, `between`)
+ * - unknown fields / operators and malformed values are dropped silently
+ * - `page` is 1-based in the URL, 0-based in `ListState`
+ * - column widths / visibility are not written (they are preferences, not position)
+ */
+import { type FilterFieldDef, type FilterGroup, type ListState } from "./types.js";
+export interface UrlStateKeys {
+    q: string;
+    filters: string;
+    sort: string;
+    page: string;
+    size: string;
+    cursor: string;
+    view: string;
+    density: string;
+}
+export interface UrlStateOptions {
+    /** Prefix every key (two lists on one page): `prefix: "c_"` → `c_q`, `c_f`… */
+    prefix?: string;
+    /** Rename individual keys. */
+    keys?: Partial<UrlStateKeys>;
+    /** Where to read and write. Default: `createHistoryAdapter()`. */
+    adapter?: UrlStateAdapter;
+    /** `"replace"` (default) keeps the back button for real navigation; `"push"` adds an entry per change. */
+    history?: "replace" | "push";
+    /** Also write the table-local density. Default `false`. */
+    density?: boolean;
+}
+/** Reads and writes the query string. Swap it for a router (`router.replace`) or a hash adapter. */
+export interface UrlStateAdapter {
+    /** The current search string, with or without the leading `?`. */
+    read(): string;
+    write(search: string, mode: "replace" | "push"): void;
+    /** Called on back / forward. Returns an unsubscribe function. */
+    subscribe(cb: () => void): () => void;
+}
+export declare function resolveUrlKeys(o?: Pick<UrlStateOptions, "prefix" | "keys">): UrlStateKeys;
+/** `stage.in:proposal|won;value.gte:5000` — the `f` parameter. Nested groups are flattened (simple mode). */
+export declare function encodeFilters(g: FilterGroup): string;
+/**
+ * Parses the `f` parameter. With `fields`, unknown fields, operators a field does not allow and
+ * malformed values are dropped; without it every syntactically valid clause is kept as text.
+ */
+export declare function decodeFilters(raw: string, fields?: FilterFieldDef[]): FilterGroup;
+export interface SerializeOptions extends Pick<UrlStateOptions, "prefix" | "keys" | "density"> {
+    /** Values equal to these defaults are left out of the URL (clean links). */
+    defaults?: Partial<ListState>;
+}
+/** The owned parameters of a list state, in a stable order. Values are already encoded. */
+export declare function listStateToParams(state: ListState, o?: SerializeOptions): Array<[string, string]>;
+/**
+ * `ListState` → search string (no leading `?`). Defaults are omitted, so the canonical list has a clean URL.
+ *
+ * ```ts
+ * serializeListState(state, { defaults: { sort: [{ id: "createdAt", desc: true }] } });
+ * // "q=jane&f=stage.in:proposal|won&page=2"
+ * ```
+ */
+export declare function serializeListState(state: ListState, o?: SerializeOptions): string;
+/**
+ * Replaces the list's own parameters in an existing search string and keeps every other
+ * parameter (`?tab=deals&q=…`) in place.
+ */
+export declare function mergeListStateIntoSearch(search: string, state: ListState, o?: SerializeOptions): string;
+export interface ParseOptions extends Pick<UrlStateOptions, "prefix" | "keys"> {
+    /** Field definitions: unknown fields / operators are dropped, values typed. */
+    fields?: FilterFieldDef[];
+    /** Base state for anything the URL does not say. */
+    defaults?: Partial<ListState>;
+    /** Allowed sort column ids (others are dropped). */
+    sortable?: string[];
+    /** Allowed page sizes. A different `size` falls back to the default. */
+    pageSizes?: number[];
+}
+/**
+ * Search string (or `URLSearchParams`, or a Next.js `searchParams` object) → `ListState`.
+ * Safe on untrusted input: bad values fall back to the defaults.
+ */
+export declare function parseListState(input: string | URLSearchParams | Record<string, string | string[] | undefined>, o?: ParseOptions): ListState;
+/**
+ * The built-in adapter: `history.replaceState` / `pushState` on the current URL. Works with the
+ * Next.js App Router (`useSearchParams` observes `history` updates). SSR-safe.
+ */
+export declare function createHistoryAdapter(): UrlStateAdapter;
+/** An in-memory adapter for tests, previews and embedded lists. */
+export declare function createMemoryAdapter(initial?: string): UrlStateAdapter & {
+    readonly search: string;
+};