@viliha/vui-ui 1.7.0 → 1.9.0

package/AGENT.md

@@ -334,6 +334,12 @@ Build forms with VUI and shadcn/ui together, reaching for shadcn Form, React Hoo
 
 Never hand-build an HTML table; always use `RecordView`. Configure columns through its field props (`editable`, `required`, `copyable`, `options`, `render`), and let `RecordView` own the rest: sorting, filtering, pagination, bulk actions, and import/export.
 
+Sorting follows column visibility by default; use `sortable` to decouple them — `sortable: true` sorts a field with no column (e.g. a `hideInTable` name shown via `getPrimary`), `sortable: false` locks a visible column. Set the flag; don't rewire the Sort dropdown or headers.
+
+## Filtering
+
+The Filter panel is a single keyword box by default (built in, matches all fields). For a labeled control per field, set `filterable` on the relevant fields and never hand-roll a filter form: `filterable: true` (text) or `filterable: { control, label, placeholder, options }` where `control` is `"text" | "number" | "date" | "select" | "combobox" | "checkbox"`. When any field is filterable the panel shows a control per field plus Search / Clear. It only **collects** values — handle `onFilter(values)` on `RecordView` to run a query or client filter (Search and Clear both call it). Types: `FilterControl`, `FieldFilter`, `FilterValues<T>`. Need a control kind that isn't listed? Extend the `FilterControl` union in the component.
+
 ## Add / edit form
 
 The buffered add/edit form renders in one of two layouts:

package/CHANGELOG.md

@@ -7,6 +7,49 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.9.0 — 2026-07-26
+
+### Added
+
+- **`sortable` field flag in `RecordView`** — decouples sorting from column
+  visibility. By default a field is sortable iff it's a visible column
+  (`!hideInTable`), unchanged. Now:
+  - `sortable: true` sorts a field with **no column** (e.g. a `hideInTable` name
+    shown via `getPrimary`) — it appears in the Sort dropdown.
+  - `sortable: false` keeps a **visible column unsortable** (its header stops
+    being a sort toggle).
+
+  Affects both the Sort dropdown and the column-header click. Fully backward
+  compatible — omit the flag for today's behavior.
+
+  **For agents:** to make a non-column field sortable (or lock a column), set
+  `sortable` on the `RecordField`; don't rewire the Sort dropdown or headers.
+  Demo: `system/regions` sorts by Name (which has no column).
+
+## 1.8.0 — 2026-07-26
+
+### Added
+
+- **Per-field filtering in `RecordView`** (opt-in, backward compatible). Mark a
+  field `filterable` and the Filter panel switches from the single keyword box to
+  a labeled control per field plus **Search / Clear**. The control is dynamic so
+  the front end can compose a different filter form per request:
+  - `filterable: true` → a text input.
+  - `filterable: { control, label, placeholder, options }` → pick the control:
+    `"text" | "number" | "date" | "select" | "combobox" | "checkbox"` (unknown or
+    omitted → text). `options` falls back to the field's own `options`.
+  - New exported types: `FilterControl`, `FieldFilter`, `FilterValues<T>`.
+  - The panel **gathers values only** — it does not match rows in per-field mode.
+    Wire matching through the new `RecordView` prop `onFilter(values)` (Search and
+    Clear both call it), typically a server query or your own client filter. The
+    single-keyword box (and its built-in row matching) is unchanged when no field
+    is `filterable`.
+
+  **For agents:** to add per-field filters, only set `filterable` on the relevant
+  `RecordField`s and handle `onFilter` — never hand-roll a filter form. Extend
+  `FilterControl` when a new control kind is needed. Demo: `system/regions`
+  (Name + Code). Docs: `/docs/data-table`.
+
 ## 1.7.0 — 2026-07-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Vui UI — a clean, token-driven React admin/CRM component library built on Tailwind CSS v4, shadcn-style patterns, and Radix Icons. Ships as TypeScript source (Just-in-Time), compiled by the consuming app.",
   "license": "MIT",
   "author": "Suman Bonakurthi",

package/src/record-view.tsx

@@ -171,6 +171,42 @@ export function usePageTitle(title: string, icon?: IconType) {
   }, [title]);
 }
 
+/** Control kinds the Filter panel can render for a `filterable` field. Omitted
+ *  or unknown kinds render a text input — extend this union as you add controls
+ *  (e.g. `"daterange"`, `"multiselect"`). */
+export type FilterControl =
+  | "text"
+  | "number"
+  | "date"
+  | "select"
+  | "combobox"
+  | "checkbox";
+
+/** Per-field Filter-panel config. `filterable: true` is shorthand for
+ *  `{ control: "text" }`; pass an object to pick the control and shape it, so
+ *  the front end can compose a different filter form per request (Name + Code as
+ *  text for one screen, a status dropdown + tag checkboxes for another). */
+export interface FieldFilter {
+  /** Which control to render. Default `"text"`. */
+  control?: FilterControl;
+  /** Label above the control. Defaults to the field's `label`. */
+  label?: string;
+  /** Placeholder for text / number / combobox inputs. */
+  placeholder?: string;
+  /** Choices for `select` / `combobox` / `checkbox`. Falls back to the field's
+   *  own `options` when omitted. */
+  options?: { value: string; label: string }[];
+}
+
+/** Values collected by the Filter panel, keyed by field. Single-value controls
+ *  yield a `string`; multi-select `checkbox` yields a `string[]`. This object is
+ *  the contract you hand to your own query / refetch via {@link RecordView}'s
+ *  `onFilter` — in per-field mode the panel gathers values but does not match
+ *  rows itself, so the search is yours (client-side or server-side). */
+export type FilterValues<T> = Partial<
+  Record<Extract<keyof T, string>, string | string[]>
+>;
+
 export interface RecordField<T> {
   key: Extract<keyof T, string>;
   label: string;
@@ -190,6 +226,12 @@ export interface RecordField<T> {
   copyable?: boolean;
   /** Show in the detail panel only, not as a table column (e.g. first/last name). */
   hideInTable?: boolean;
+  /** Whether this field can be sorted — decoupled from column visibility.
+   *  Default: sortable iff it's a visible column (`!hideInTable`), the historic
+   *  behavior. Set `true` to sort a field with no column (e.g. a `hideInTable`
+   *  name shown via `getPrimary`); set `false` to keep a visible column
+   *  unsortable. Controls both the Sort dropdown and the column-header toggle. */
+  sortable?: boolean;
   /** Custom, non-editable cell/value renderer. */
   render?: (row: T) => React.ReactNode;
   /** If set, the field becomes a choice field: the Add/Edit form renders a
@@ -199,6 +241,13 @@ export interface RecordField<T> {
    *  textarea). `"number"`/`"date"` render the matching native input; a field
    *  with `options` always renders a `Select` regardless of this. */
   input?: "text" | "number" | "date";
+  /** Expose this field in the Filter panel. When ANY field is filterable, the
+   *  panel switches from the single keyword box to a labeled control per field
+   *  plus Search / Clear. `true` = a text input; pass a {@link FieldFilter} to
+   *  choose the control (dropdown, checkbox, combobox, number, date …) so the
+   *  filter form is composed per request. The panel only gathers values — wire
+   *  matching through RecordView's `onFilter`. Omit to leave the field out. */
+  filterable?: boolean | FieldFilter;
 }
 
 /**
@@ -292,6 +341,11 @@ interface RecordViewProps<T extends { id: RowId }> {
   /** Allow dragging column edges to resize them. Off by default — columns
    *  auto-size, and no resize handle appears on hover. */
   resizableColumns?: boolean;
+  /** Called from the Filter panel's Search (and Clear) when fields are
+   *  `filterable`. Receives the collected per-field values; run your own query
+   *  or client-side filtering here. In per-field mode the panel does not match
+   *  rows itself, so the behavior is entirely yours. */
+  onFilter?: (values: FilterValues<T>) => void;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -313,6 +367,7 @@ export function RecordView<T extends { id: RowId }>({
   onEdit,
   persistKey,
   resizableColumns = false,
+  onFilter,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
@@ -339,6 +394,12 @@ export function RecordView<T extends { id: RowId }>({
     persistKey ? `${persistKey}::filter` : undefined,
     "",
   );
+  // Per-field Filter-panel values (opt-in via `field.filterable`). Kept apart
+  // from the single-keyword `filter`; persisted like the rest of the view.
+  const [filterValues, setFilterValues] = usePersistentState<FilterValues<T>>(
+    persistKey ? `${persistKey}::filterValues` : undefined,
+    {},
+  );
   const [sort, setSort] = usePersistentState<{
     key: string;
     dir: "asc" | "desc";
@@ -405,6 +466,15 @@ export function RecordView<T extends { id: RowId }>({
 
   const tableFields = fields.filter((f) => !f.hideInTable);
   const visibleFields = tableFields.filter((f) => !hidden.has(f.key));
+  // Sorting is decoupled from column visibility: a field is sortable when its
+  // `sortable` flag says so, else it falls back to "is a visible column".
+  const canSort = (f: RecordField<T>) => f.sortable ?? !f.hideInTable;
+  // Fields offered in the Sort dropdown (may include hidden-but-sortable fields
+  // and exclude visible-but-unsortable ones).
+  const sortFields = fields.filter(canSort);
+  // Fields opted into per-field filtering. Non-empty → the Filter panel renders
+  // a control per field instead of the single keyword box.
+  const filterFields = fields.filter((f) => f.filterable);
 
   // The primary "Name" column renders the record's name field, which is hidden
   // as a regular column (hideInTable) because it shows here. Mirror its
@@ -1007,24 +1077,124 @@ export function RecordView<T extends { id: RowId }>({
             </Dropdown>
           )}
           <Dropdown label="Filter" icon={<ListFilter className="size-3.5 text-amber-500" />}>
-            <DropdownLabel>Filter by keyword</DropdownLabel>
-            <div className="p-3">
-              <div className="relative">
-                <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
-                <Input
-                  value={filter}
-                  onChange={(e) => setFilter(e.target.value)}
-                  placeholder="Contains…"
-                  aria-label="Filter"
-                  className="h-8 pl-9"
-                />
-              </div>
-            </div>
+            {filterFields.length > 0 ? (
+              // Per-field mode: a labeled control per `filterable` field, plus
+              // Search / Clear. The panel only gathers values — matching is the
+              // consumer's job via `onFilter` (see the field's `filterable`).
+              <>
+                <DropdownLabel>Filter</DropdownLabel>
+                <div className="flex max-h-80 w-72 flex-col gap-3 overflow-y-auto p-3">
+                  {filterFields.map((f) => {
+                    const cfg: FieldFilter =
+                      typeof f.filterable === "object" ? f.filterable : {};
+                    const control = cfg.control ?? "text";
+                    const label = cfg.label ?? f.label;
+                    const opts = cfg.options ?? f.options ?? [];
+                    const raw = filterValues[f.key];
+                    const setVal = (v: string | string[]) =>
+                      setFilterValues((prev) => ({ ...prev, [f.key]: v }));
+                    return (
+                      <div key={f.key} className="flex flex-col gap-1">
+                        <label className="text-xs font-medium text-muted-foreground">
+                          {label}
+                        </label>
+                        {control === "select" || control === "combobox" ? (
+                          <Select
+                            value={typeof raw === "string" ? raw : ""}
+                            onValueChange={setVal}
+                            options={opts}
+                            ariaLabel={label}
+                            placeholder={
+                              cfg.placeholder ?? `Any ${label.toLowerCase()}`
+                            }
+                            className="w-full"
+                          />
+                        ) : control === "checkbox" ? (
+                          <div className="flex flex-col gap-1">
+                            {opts.map((o) => {
+                              const arr = Array.isArray(raw) ? raw : [];
+                              const on = arr.includes(o.value);
+                              return (
+                                <label
+                                  key={o.value}
+                                  className="flex items-center gap-2 text-sm"
+                                >
+                                  <input
+                                    type="checkbox"
+                                    checked={on}
+                                    onChange={() =>
+                                      setVal(
+                                        on
+                                          ? arr.filter((v) => v !== o.value)
+                                          : [...arr, o.value],
+                                      )
+                                    }
+                                  />
+                                  {o.label}
+                                </label>
+                              );
+                            })}
+                          </div>
+                        ) : (
+                          <Input
+                            type={
+                              control === "number"
+                                ? "number"
+                                : control === "date"
+                                  ? "date"
+                                  : "text"
+                            }
+                            value={typeof raw === "string" ? raw : ""}
+                            onChange={(e) => setVal(e.target.value)}
+                            placeholder={cfg.placeholder ?? "Contains…"}
+                            aria-label={label}
+                            className="h-8"
+                          />
+                        )}
+                      </div>
+                    );
+                  })}
+                  <div className="flex items-center justify-end gap-2 border-t border-border pt-3">
+                    <Button
+                      onClick={() => {
+                        setFilterValues({});
+                        onFilter?.({});
+                      }}
+                    >
+                      Clear
+                    </Button>
+                    <Button
+                      variant="primary"
+                      onClick={() => onFilter?.(filterValues)}
+                    >
+                      <Search className="size-3.5" />
+                      Search
+                    </Button>
+                  </div>
+                </div>
+              </>
+            ) : (
+              <>
+                <DropdownLabel>Filter by keyword</DropdownLabel>
+                <div className="p-3">
+                  <div className="relative">
+                    <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+                    <Input
+                      value={filter}
+                      onChange={(e) => setFilter(e.target.value)}
+                      placeholder="Contains…"
+                      aria-label="Filter"
+                      className="h-8 pl-9"
+                    />
+                  </div>
+                </div>
+              </>
+            )}
           </Dropdown>
 
           <Dropdown label="Sort" icon={<ArrowUpDown className="size-3.5 text-blue-500" />}>
             <DropdownLabel>Sort by</DropdownLabel>
-            {tableFields.map((f) => (
+            {sortFields.map((f) => (
               <DropdownItem
                 key={f.key}
                 onSelect={() => toggleSort(f.key)}
@@ -1142,32 +1312,44 @@ export function RecordView<T extends { id: RowId }>({
               </TableHead>
               {visibleFields.map((f) => {
                 const HeadIcon = f.icon ?? DEFAULT_FIELD_ICON;
+                const sortable = canSort(f);
+                const headInner = (
+                  <>
+                    <HeadIcon className="size-3.5 shrink-0 text-foreground" />
+                    <span className="flex items-center gap-1 whitespace-nowrap">
+                      {f.label}
+                      {f.required && <RequiredMark />}
+                    </span>
+                    {sort?.key === f.key &&
+                      (sort.dir === "asc" ? (
+                        <ArrowUp className="size-3 shrink-0" />
+                      ) : (
+                        <ArrowDown className="size-3 shrink-0" />
+                      ))}
+                  </>
+                );
+                const headClass = cn(
+                  "flex h-8 w-full items-center gap-1.5 whitespace-nowrap",
+                  ALIGN_BOX[alignOf(f.key)],
+                );
                 return (
                   <TableHead
                     key={f.key}
                     className="relative w-max"
                     style={{ width: colWidths[f.key] }}
                   >
-                    <button
-                      type="button"
-                      onClick={() => toggleSort(f.key)}
-                      className={cn(
-                        "flex h-8 w-full items-center gap-1.5 whitespace-nowrap hover:text-foreground",
-                        ALIGN_BOX[alignOf(f.key)],
-                      )}
-                    >
-                      <HeadIcon className="size-3.5 shrink-0 text-foreground" />
-                      <span className="flex items-center gap-1 whitespace-nowrap">
-                        {f.label}
-                        {f.required && <RequiredMark />}
-                      </span>
-                      {sort?.key === f.key &&
-                        (sort.dir === "asc" ? (
-                          <ArrowUp className="size-3 shrink-0" />
-                        ) : (
-                          <ArrowDown className="size-3 shrink-0" />
-                        ))}
-                    </button>
+                    {sortable ? (
+                      <button
+                        type="button"
+                        onClick={() => toggleSort(f.key)}
+                        className={cn(headClass, "hover:text-foreground")}
+                      >
+                        {headInner}
+                      </button>
+                    ) : (
+                      // Not sortable: a static label, no toggle / hover affordance.
+                      <span className={headClass}>{headInner}</span>
+                    )}
                     {resizeHandle(f.key, f.label)}
                   </TableHead>
                 );

package/template/app/(app)/system/regions/regions-table.tsx

@@ -1,26 +1,86 @@
 "use client";
 
-import {
-  CodeIcon as Hash,
-  GlobeIcon as Globe,
-} from "@radix-ui/react-icons";
+import { useMemo, useState } from "react";
+import { CodeIcon as Hash, GlobeIcon as Globe } from "@radix-ui/react-icons";
 
-import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
+import {
+  RecordView,
+  type FilterValues,
+  type RecordField,
+} from "@viliha/vui-ui/record-view";
 import { regions, type Region } from "@/lib/mock-data";
 
+// `filterable` opts a field into the Filter panel. With any field filterable the
+// panel shows a labeled control per field + Search/Clear instead of the single
+// keyword box. `true` = a text input; pass a config to pick the control.
 const fields: RecordField<Region>[] = [
-  { key: "name", label: "Name", editable: true, required: true, group: "General", hideInTable: true },
-  { key: "code", label: "Code", icon: Hash, editable: true, group: "General" },
+  {
+    key: "name",
+    label: "Name",
+    editable: true,
+    required: true,
+    group: "General",
+    hideInTable: true,
+    // No Name column (shown in the identity cell via getPrimary), but still
+    // sortable from the Sort dropdown — `sortable` decouples it from visibility.
+    sortable: true,
+    filterable: true,
+  },
+  {
+    key: "code",
+    label: "Code",
+    icon: Hash,
+    editable: true,
+    group: "General",
+    filterable: { control: "text", placeholder: "e.g. APAC" },
+  },
 ];
 
 export function RegionsTable() {
+  const [all, setAll] = useState<Region[]>(regions);
+  const [filters, setFilters] = useState<FilterValues<Region>>({});
+
+  // Demo: match the per-field values client-side. The component does NOT filter
+  // in per-field mode — `onFilter` hands you the values; swap this for a server
+  // query in a real app. ponytail: naive contains-match, fine for demo data.
+  const rows = useMemo(
+    () =>
+      all.filter((r) =>
+        Object.entries(filters).every(([k, v]) => {
+          const needle = String(v ?? "").toLowerCase();
+          return (
+            !needle ||
+            String(r[k as keyof Region]).toLowerCase().includes(needle)
+          );
+        }),
+      ),
+    [all, filters],
+  );
+
+  // Reconcile edits/adds/deletes made on the filtered view back into `all`.
+  const handleChange = (next: Region[]) => {
+    setAll((prev) => {
+      const nextById = new Map(next.map((r) => [r.id, r] as const));
+      const visible = new Set(rows.map((r) => r.id));
+      const kept = prev
+        .filter((r) => !visible.has(r.id) || nextById.has(r.id)) // drop deleted
+        .map((r) => nextById.get(r.id) ?? r); // apply edits
+      const added = next.filter((r) => !prev.some((p) => p.id === r.id));
+      return [...kept, ...added];
+    });
+  };
+
   return (
     <RecordView
       title="Regions"
       singular="Region"
       icon={Globe}
+      persistKey="/system/regions"
       fields={fields}
-      initialData={regions}
+      initialData={rows}
+      data={rows}
+      onDataChange={handleChange}
+      onFilter={setFilters}
       getPrimary={(row) => ({
         title: row.name,
         subtitle: row.code,