@spaethtech/svelte-ui 0.17.1-dev.80.6b8fb45 → 0.17.1-dev.82.2748ef4

package/.claude/skills/svelte-ui/SKILL.md

@@ -184,7 +184,12 @@ examples):
   For a start–end range use **`DatePicker range`** (`bind:value` = `{ start, end }`) — it composes
   `Calendar mode="range"`.
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
-  (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`). · **`Pagination`** (standalone
+  (query-language parser/AST via `parseQuery`, `createGrid`, `DataGrid<T>`, `DataSet`). For a
+  **client-held array**, use **`localFetch(rows, columns, opts?)`** as the grid's `fetch` — it parses
+  the query, filters via **`matchesRow(row, ast)`** (the in-memory AST evaluator: cmp/and/or/not/
+  match/in/range/search, honouring column `id`/`searchable`/`sortKey`), then sorts + paginates. Only a
+  remote/DB backend needs to compile the AST itself; do NOT hand-roll a "strip `$` + substring" filter.
+  · **`Pagination`** (standalone
   pager styled like the DataTable footer: tinted band, per-page `Select`, range total, and a
   `First·Prev·[page]/N·Next·Last` stepper whose indicator is an editable `NumberInput` quick-jump;
   `bind:page`/`bind:perPage`, `total`, `perPageOptions`, `showEdges`/`showTotal`, `borderless`;

package/dist/components/DataTable.svelte

@@ -103,10 +103,11 @@
   /** Font size for the WHOLE table. Applied as `font-size` on the
    *  outer container; every descendant inherits via standard CSS
    *  cascade — headers, cells, footer text all follow. */
-  // DataTable's own density is set via inline-style CSS vars + cell padding that already bakes in its
-  // own `md:` responsive step — neither can be re-prefixed per size tier. So the TABLE'S density keys
-  // off the base tier of a responsive `size` (via resolveScalar); the responsive `size` is still passed
-  // through to child controls (Button/Select/Checkbox), which DO resize at every breakpoint.
+  // DataTable's own density (font size + row height + cell padding) is a pure function of `size` — it
+  // NEVER changes with the viewport. It keys off the base tier of a responsive `size` (via
+  // resolveScalar) because its font-size/height are single inline-style CSS vars that can't carry
+  // per-breakpoint variants; the responsive `size` is still passed through to child controls
+  // (Button/Select/Checkbox), which DO resize at every breakpoint.
   const sSize = $derived(resolveScalar(size, "md"));
   const textVar = $derived(
     sSize === "lg" ? "var(--ui-text-lg)" : sSize === "md" ? "var(--ui-text)" : "var(--ui-text-sm)",
@@ -121,15 +122,10 @@
         ? "var(--ui-height)"
         : "var(--ui-height-sm)",
   );
-  /** Cell padding scales with size. Mobile-first: base padding is
-   *  tight; the md: variant applies at ≥ 768px so tables feel
-   *  chunkier on desktop but stay dense on phones. */
+  /** Cell padding — a pure function of `size` (no viewport step), so a table's density is exactly its
+   *  `size` at every width. The values pair with `heightVar` (sm 24 / md 32 / lg 40px). */
   const cellPad = $derived(
-    sSize === "lg"
-      ? "py-3 px-4 md:py-4 md:px-5"
-      : sSize === "md"
-        ? "py-2 px-3 md:py-3 md:px-4"
-        : "py-1 px-2 md:py-2 md:px-3",
+    sSize === "lg" ? "py-3 px-4" : sSize === "md" ? "py-2 px-3" : "py-1 px-2",
   );
   /** Inter-column gap. Tracks the same size axis so lead/cell/tail
    *  spacing stays proportional to cell padding. */

package/dist/data/query/eval.d.ts

@@ -0,0 +1,16 @@
+import { type QueryNode } from "./ast.js";
+export interface RowEvalOptions {
+    /** Resolve a row's value for a column id. Default: `row[colId]`. */
+    getValue?: (row: unknown, colId: string) => unknown;
+    /** Column ids scanned by a bare-text `search` node (the columns marked `searchable`). */
+    searchColumns?: string[];
+    /** Instant used to resolve `now()` values. Default: `new Date()` at call time. */
+    now?: Date;
+    /** Case-insensitive string comparison + search. Default: `true`. */
+    caseInsensitive?: boolean;
+}
+/**
+ * Test a single `row` against a parsed query `ast`. `null`/`undefined` ast matches every row (an empty
+ * query is "no filter"). See {@link RowEvalOptions} for value access, searchable columns, and `now()`.
+ */
+export declare function matchesRow(row: unknown, ast: QueryNode | null | undefined, opts?: RowEvalOptions): boolean;

package/dist/data/query/eval.js

@@ -0,0 +1,156 @@
+// In-memory evaluator for the query AST — tests a plain row object against a parsed `QueryNode`.
+// Framework-agnostic (no Svelte deps), the client-side counterpart to a server `toConditions`:
+// where a DB backend compiles the AST to SQL, an in-memory grid filters an array with `matchesRow`.
+// Handles all node kinds — and/or/not · cmp · match · in · range · search.
+import { isNow, resolveNow, } from "./ast.js";
+const getProp = (row, col) => row == null ? undefined : row[col];
+const toStr = (v) => v == null ? "" : v instanceof Date ? v.toISOString() : String(v);
+const isNumericLike = (v) => typeof v === "number"
+    ? Number.isFinite(v)
+    : typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v));
+const toBool = (v) => v === true || v === 1 || v === "1" || (typeof v === "string" && v.toLowerCase() === "true");
+const toDateMs = (v) => v instanceof Date ? v.getTime() : new Date(v).getTime();
+/** Resolve a query `Value` (possibly a `now()` marker) to a concrete comparand. */
+const resolveVal = (v, now) => (isNow(v) ? resolveNow(v, now) : v);
+/** Total order for a cell vs a comparand under an optional cast. Returns -1/0/1, or `NaN` if either
+ *  side can't be coerced to the compared type (an incomparable pair never satisfies an ordering op). */
+function order(cell, val, cast, _now) {
+    if (cast === "date" || val instanceof Date) {
+        const a = toDateMs(cell);
+        const b = val instanceof Date ? val.getTime() : toDateMs(val);
+        if (Number.isNaN(a) || Number.isNaN(b))
+            return NaN;
+        return a === b ? 0 : a < b ? -1 : 1;
+    }
+    if (cast === "bool")
+        return (toBool(cell) ? 1 : 0) - (toBool(val) ? 1 : 0);
+    if (cast === "number" || (cast == null && isNumericLike(cell) && isNumericLike(val))) {
+        const a = Number(cell);
+        const b = Number(val);
+        if (Number.isNaN(a) || Number.isNaN(b))
+            return NaN;
+        return a === b ? 0 : a < b ? -1 : 1;
+    }
+    const cmp = toStr(cell).localeCompare(toStr(val));
+    return cmp < 0 ? -1 : cmp > 0 ? 1 : 0;
+}
+/** Equality with the same coercion rules as `order`, but string-equality honours `caseInsensitive`. */
+function eq(cell, val, cast, ci) {
+    if (cast === "date" || val instanceof Date)
+        return toDateMs(cell) === (val instanceof Date ? val.getTime() : toDateMs(val));
+    if (cast === "bool")
+        return toBool(cell) === toBool(val);
+    if (cast === "number" || (cast == null && isNumericLike(cell) && isNumericLike(val)))
+        return Number(cell) === Number(val);
+    const a = toStr(cell);
+    const b = toStr(val);
+    return ci ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function safeRegExp(source, flags) {
+    try {
+        return new RegExp(source, flags);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Test a single `row` against a parsed query `ast`. `null`/`undefined` ast matches every row (an empty
+ * query is "no filter"). See {@link RowEvalOptions} for value access, searchable columns, and `now()`.
+ */
+export function matchesRow(row, ast, opts = {}) {
+    if (!ast)
+        return true;
+    const get = opts.getValue ?? getProp;
+    const ci = opts.caseInsensitive ?? true;
+    const now = opts.now ?? new Date();
+    const searchCols = opts.searchColumns ?? [];
+    const strOp = (cell, val, op) => {
+        let s = toStr(cell);
+        let t = toStr(val);
+        if (ci) {
+            s = s.toLowerCase();
+            t = t.toLowerCase();
+        }
+        return op === "contains"
+            ? s.includes(t)
+            : op === "ncontains"
+                ? !s.includes(t)
+                : op === "starts"
+                    ? s.startsWith(t)
+                    : s.endsWith(t); // "ends"
+    };
+    const inInterval = (x, interval, cast) => {
+        const { lower, upper } = interval;
+        if (lower) {
+            const o = order(x, resolveVal(lower.value, now), cast, now);
+            if (Number.isNaN(o) || (lower.inclusive ? o < 0 : o <= 0))
+                return false;
+        }
+        if (upper) {
+            const o = order(x, resolveVal(upper.value, now), cast, now);
+            if (Number.isNaN(o) || (upper.inclusive ? o > 0 : o >= 0))
+                return false;
+        }
+        return true;
+    };
+    const ev = (node) => {
+        switch (node.kind) {
+            case "and":
+                return node.children.every(ev);
+            case "or":
+                return node.children.some(ev);
+            case "not":
+                return !ev(node.child);
+            case "cmp": {
+                const cell = get(row, node.col);
+                const op = node.op;
+                if (op === "contains" || op === "ncontains" || op === "starts" || op === "ends")
+                    return strOp(cell, node.value, op);
+                const val = resolveVal(node.value, now);
+                if (op === "eq")
+                    return eq(cell, val, node.cast, ci);
+                if (op === "ne")
+                    return !eq(cell, val, node.cast, ci);
+                const o = order(cell, val, node.cast, now);
+                if (Number.isNaN(o))
+                    return false;
+                return op === "gt" ? o > 0 : op === "gte" ? o >= 0 : op === "lt" ? o < 0 : o <= 0;
+            }
+            case "match": {
+                const re = safeRegExp(node.source, node.flags);
+                if (!re)
+                    return false;
+                const hit = re.test(toStr(get(row, node.col)));
+                return node.negated ? !hit : hit;
+            }
+            case "in": {
+                const cell = get(row, node.col);
+                const members = node.values.map((v) => resolveVal(v, now));
+                if (Array.isArray(cell)) {
+                    const inCell = (m) => cell.some((c) => eq(c, m, node.cast, ci));
+                    return node.mode === "all" ? members.every(inCell) : members.some(inCell);
+                }
+                const hits = members.map((m) => eq(cell, m, node.cast, ci));
+                return node.mode === "all" ? hits.every(Boolean) : hits.some(Boolean);
+            }
+            case "range": {
+                const cell = get(row, node.col);
+                const test = (x) => inInterval(x, node.interval, node.cast);
+                if (Array.isArray(cell))
+                    return node.mode === "all" ? cell.every(test) : cell.some(test);
+                return test(cell);
+            }
+            case "search": {
+                const needle = ci ? node.text.toLowerCase() : node.text;
+                if (!needle)
+                    return true;
+                return searchCols.some((c) => {
+                    const s = toStr(get(row, c));
+                    return (ci ? s.toLowerCase() : s).includes(needle);
+                });
+            }
+        }
+    };
+    return ev(ast);
+}

package/dist/data/query/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./ast";
 export { parseQuery, tryParseQuery, type ParseResult } from "./parser";
+export { matchesRow, type RowEvalOptions } from "./eval";
 export { lex, type Token } from "./lexer";

package/dist/data/query/index.js

@@ -1,3 +1,4 @@
 export * from "./ast";
 export { parseQuery, tryParseQuery } from "./parser";
+export { matchesRow } from "./eval";
 export { lex } from "./lexer";

package/dist/data/table/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./types";
 export { createGrid, DataGrid, type GridOptions } from "./grid.svelte";
+export { localFetch, type LocalFetchOptions } from "./local";

package/dist/data/table/index.js

@@ -1,2 +1,3 @@
 export * from "./types";
 export { createGrid, DataGrid } from "./grid.svelte";
+export { localFetch } from "./local";

package/dist/data/table/local.d.ts

@@ -0,0 +1,21 @@
+import type { Column, FetchFn } from "./types.js";
+export interface LocalFetchOptions<T> {
+    /** Resolve a row's value for a column id (filter + sort + search). Default: `row[colId]`. */
+    getValue?: (row: T, colId: string) => unknown;
+    /** Case-insensitive filtering/search. Default: `true`. */
+    caseInsensitive?: boolean;
+    /** Instant for resolving `now()` in the query. Called per fetch. Default: `new Date()`. */
+    now?: () => Date;
+}
+/**
+ * Build a `FetchFn` that runs entirely in memory over `source`.
+ *
+ * ```ts
+ * const grid = createGrid({ columns, getRowId: (r) => r.id, fetch: localFetch(() => rows, columns) });
+ * ```
+ *
+ * Pass a getter (`() => rows`) rather than a bare array if the data is reactive (`$state`) and should
+ * re-filter when it changes. Filtering honours the columns' `id` (`$token`) and `searchable` flags; a
+ * bare-text search scans the `searchable` columns (or every column if none are marked).
+ */
+export declare function localFetch<T>(source: T[] | (() => T[]), columns: Column<T>[], opts?: LocalFetchOptions<T>): FetchFn<T>;

package/dist/data/table/local.js

@@ -0,0 +1,63 @@
+// In-memory `FetchFn` for `createGrid`/`DataTable` — the client-side counterpart to a remote
+// `query()`. Parses the grid's query string, filters the array with `matchesRow`, then sorts and
+// paginates. Drop the whole "compile the AST to your storage" step for client-held data.
+import { parseQuery } from "../query/index.js";
+import { matchesRow } from "../query/eval.js";
+const naturalCompare = (a, b) => {
+    if (a == null && b == null)
+        return 0;
+    if (a == null)
+        return 1; // nullish sorts last (asc)
+    if (b == null)
+        return -1;
+    const an = typeof a === "number" || (typeof a === "string" && a.trim() !== "" && !Number.isNaN(Number(a)));
+    const bn = typeof b === "number" || (typeof b === "string" && b.trim() !== "" && !Number.isNaN(Number(b)));
+    if (an && bn)
+        return Number(a) - Number(b);
+    return String(a).localeCompare(String(b));
+};
+/**
+ * Build a `FetchFn` that runs entirely in memory over `source`.
+ *
+ * ```ts
+ * const grid = createGrid({ columns, getRowId: (r) => r.id, fetch: localFetch(() => rows, columns) });
+ * ```
+ *
+ * Pass a getter (`() => rows`) rather than a bare array if the data is reactive (`$state`) and should
+ * re-filter when it changes. Filtering honours the columns' `id` (`$token`) and `searchable` flags; a
+ * bare-text search scans the `searchable` columns (or every column if none are marked).
+ */
+export function localFetch(source, columns, opts = {}) {
+    const getRows = typeof source === "function" ? source : () => source;
+    const marked = columns.filter((c) => c.searchable).map((c) => c.id);
+    const searchColumns = marked.length ? marked : columns.map((c) => c.id);
+    const sortKeyOf = (id) => columns.find((c) => c.id === id)?.sortKey ?? id;
+    const value = (row, col) => opts.getValue ? opts.getValue(row, col) : row[col];
+    return (state) => {
+        const all = getRows();
+        let ast = null;
+        try {
+            ast = parseQuery(state.q);
+        }
+        catch {
+            ast = null; // invalid query → show everything (the Query input surfaces the error separately)
+        }
+        const filtered = ast
+            ? all.filter((r) => matchesRow(r, ast, {
+                getValue: (row, col) => value(row, col),
+                searchColumns,
+                caseInsensitive: opts.caseInsensitive,
+                now: opts.now?.(),
+            }))
+            : all.slice();
+        if (state.sort) {
+            const key = sortKeyOf(state.sort.col);
+            const dir = state.sort.dir === "desc" ? -1 : 1;
+            filtered.sort((a, b) => naturalCompare(value(a, key), value(b, key)) * dir);
+        }
+        const total = filtered.length;
+        const start = (state.page - 1) * state.perPage;
+        const rows = filtered.slice(start, start + state.perPage);
+        return { current: { rows, total }, loading: false, error: undefined };
+    };
+}

package/docs/components.md

@@ -367,7 +367,9 @@ under the active tab. Fully demoed at `/tabstrip`.
 ## Data Components
 
 These pair with the headless **`@spaethtech/svelte-ui/data`** layer (query-language parser/AST, `createGrid`,
-`DataSet`). See `docs/usage.md`.
+`DataSet`). For a **client-held array**, `fetch: localFetch(rows, columns)` gives full query support in
+memory (`matchesRow` evaluates the AST — filter + sort + page); only a DB backend compiles the query
+itself. See `docs/usage.md`.
 
 ### DataTable
 

package/docs/usage.md

@@ -1103,24 +1103,31 @@ bar with `Query` over a `DataSet`.
   import { createGrid } from "@spaethtech/svelte-ui/data";
   import IconPencil from "~icons/mdi/pencil";
 
-  const grid = createGrid({
-    columns: [
-      { id: "name", label: "Name" },
-      { id: "email", label: "Email" },
-      { id: "status", label: "Status", sortKey: "status" },
-    ],
-    fetch: (request) => /* a reactive query returning { rows, total } */ myQuery(request),
-  });
+  const columns = [
+    { id: "name", label: "Name", searchable: true, cell: nameCell },
+    { id: "email", label: "Email", searchable: true, cell: emailCell },
+    { id: "status", label: "Status", filter: { kind: "enum", options: ["active", "invited"] }, cell: statusCell },
+  ];
+
+  // REMOTE (DB): compile request.q to your storage.
+  // const grid = createGrid({ columns, fetch: (request) => myQuery(request) });
+
+  // CLIENT array: `localFetch` parses the query, filters (matchesRow), sorts + paginates for you —
+  // full query support ($status == active, $name ~= /re/, ranges, bare search…). No hand-rolled filter.
+  const grid = createGrid({ columns, getRowId: (r) => r.id, fetch: localFetch(() => rows, columns) });
 </script>
 
 <DataTable
   {grid}
+  {columns}
   selectable
   rowActions={(row) => [{ label: "Edit", icon: IconPencil, onclick: () => edit(row) }]}
 />
 ```
 
-See the live demo for the full DataTable + Query walkthrough — http://localhost:5173.
+`import { createGrid, localFetch, matchesRow } from "@spaethtech/svelte-ui/data";` — `localFetch` is the
+client-side counterpart to a remote `query()`; `matchesRow(row, ast)` is the underlying AST evaluator if
+you need to filter an array yourself. See the live demo for the full DataTable + Query walkthrough.
 
 ## Theme Integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.17.1-dev.80.6b8fb45",
+  "version": "0.17.1-dev.82.2748ef4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"