@viliha/vui-ui 1.8.0 → 1.10.0

package/AGENT.md

@@ -334,6 +334,10 @@ 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.
+
+Form controls come from the field: `options` → `Select`, `input: "combobox"` → a searchable `Combobox` (`@viliha/vui-ui/combobox`, use for long lists), `input: "number" | "date"` → native inputs. For anything the built-ins don't cover (checkbox, radio group, slider, custom widget), set `renderInput({ value, onChange, field, invalid })` on the field — it drops any component into the Add/Edit form while the field keeps its label, required mark, and Save validation. Don't hand-build a `<form>`.
+
 ## 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.

package/CHANGELOG.md

@@ -7,6 +7,48 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.10.0 — 2026-07-26
+
+### Added
+
+- **`Combobox`** (`@viliha/vui-ui/combobox`) — a searchable single-select. Same
+  API as `Select` (drop-in) but the popover leads with a type-to-filter input, so
+  it scales to long option lists (an FK / country picker). Keyboard: type to
+  filter, ↑/↓ to move, Enter to pick, Esc to close.
+- **`RecordView` choice fields can use the Combobox.** In the Add/Edit form set
+  `input: "combobox"` on an `options` field for a searchable control (default
+  stays `Select`). In the Filter panel, `control: "combobox"` now renders the
+  real searchable Combobox (previously it fell back to a plain Select).
+- **`RecordField.renderInput`** — an escape hatch to render **any** Add/Edit
+  control (checkbox, radio group, slider, date-range, a custom widget). It
+  overrides the default control and receives `{ value, onChange, field, invalid }`;
+  the field still owns the label, required mark, and Save validation. The
+  Organizations form demonstrates it (Status as a radio group).
+
+  **For agents:** for a long choice list use `input: "combobox"`; for a control
+  the built-ins don't cover use `renderInput` — never hand-build a `<form>`.
+  New demo: Organizations Status (radio via `renderInput`); Combobox is also in
+  the components gallery. Docs: `/docs/components`, `/docs/data-table`.
+
+## 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

package/README.md

@@ -249,9 +249,10 @@ place. If you'd rather keep a verbatim copy, run
 ## Components
 
 `avatar` · `badge` · `breadcrumbs` · `button` · `card` · `chart` (themed Recharts
-wrapper) · `checkbox` · `command-palette` (⌘K launcher) · `dialog` ·
-`confirm-dialog` · `dropdown-menu` · `input` · `kbd` (key caps + `Shortcut`) ·
-`menu` · `required-mark` · `select` · `steps` (multi-step wizard indicator) ·
+wrapper) · `checkbox` · `combobox` (searchable single-select) · `command-palette`
+(⌘K launcher) · `dialog` · `confirm-dialog` · `dropdown-menu` · `input` · `kbd`
+(key caps + `Shortcut`) · `menu` · `required-mark` · `select` · `steps`
+(multi-step wizard indicator) ·
 `table` · `record-view` (the full datatable + `RecordForm`) · plus the `utils`
 (`cn`) helper and the `theme.css` design tokens.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.8.0",
+  "version": "1.10.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/combobox.tsx

@@ -0,0 +1,233 @@
+"use client";
+
+import * as React from "react";
+import { createPortal } from "react-dom";
+import {
+  CheckIcon as Check,
+  ChevronDownIcon as ChevronDown,
+  MagnifyingGlassIcon as Search,
+} from "@radix-ui/react-icons";
+
+import { cn } from "./utils";
+import type { SelectOption } from "./select";
+
+type Placement = {
+  left: number;
+  width: number;
+  top?: number;
+  bottom?: number;
+  maxHeight: number;
+};
+
+/**
+ * Searchable single-select. Same trigger + portal-popover as {@link Select}, but
+ * the popover leads with a filter input that type-narrows the options, so it
+ * scales to long lists (an FK / country picker) where a plain Select doesn't.
+ * Same API as Select (drop-in), plus search/empty placeholders. Keyboard: type
+ * to filter, ↑/↓ to move, Enter to pick, Esc to close.
+ */
+export function Combobox({
+  value,
+  onValueChange,
+  options,
+  id,
+  ariaLabel,
+  placeholder = "Select…",
+  searchPlaceholder = "Search…",
+  emptyText = "No matches",
+  className,
+}: {
+  value: string;
+  onValueChange: (value: string) => void;
+  options: SelectOption[];
+  id?: string;
+  ariaLabel?: string;
+  placeholder?: string;
+  /** Placeholder for the filter input. */
+  searchPlaceholder?: string;
+  /** Shown when the query matches nothing. */
+  emptyText?: string;
+  /** Applied to the root (e.g. width in a flex row). */
+  className?: string;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [query, setQuery] = React.useState("");
+  const [active, setActive] = React.useState(0);
+  const [pos, setPos] = React.useState<Placement | null>(null);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const listRef = React.useRef<HTMLDivElement>(null);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const filtered = React.useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return q ? options.filter((o) => o.label.toLowerCase().includes(q)) : options;
+  }, [options, query]);
+
+  const place = React.useCallback(() => {
+    const el = triggerRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    const below = window.innerHeight - r.bottom;
+    const above = r.top;
+    const openUp = below < 280 && above > below;
+    setPos({
+      left: r.left,
+      width: r.width,
+      top: openUp ? undefined : r.bottom + 4,
+      bottom: openUp ? window.innerHeight - r.top + 4 : undefined,
+      maxHeight: Math.min(300, (openUp ? above : below) - 8),
+    });
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (!open) return;
+    place();
+    const reflow = () => place();
+    window.addEventListener("scroll", reflow, true);
+    window.addEventListener("resize", reflow);
+    return () => {
+      window.removeEventListener("scroll", reflow, true);
+      window.removeEventListener("resize", reflow);
+    };
+  }, [open, place]);
+
+  // Reset the query + focus the input each time it opens.
+  React.useEffect(() => {
+    if (!open) return;
+    setQuery("");
+    setActive(0);
+    const t = requestAnimationFrame(() => inputRef.current?.focus());
+    return () => cancelAnimationFrame(t);
+  }, [open]);
+
+  React.useEffect(() => {
+    if (!open) return;
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as Node;
+      if (rootRef.current?.contains(t) || listRef.current?.contains(t)) return;
+      setOpen(false);
+    };
+    document.addEventListener("mousedown", onDown);
+    return () => document.removeEventListener("mousedown", onDown);
+  }, [open]);
+
+  // Keep the active index in range as the filtered list shrinks/grows.
+  React.useEffect(() => {
+    setActive((i) => Math.min(i, Math.max(0, filtered.length - 1)));
+  }, [filtered.length]);
+
+  const selected = options.find((o) => o.value === value);
+  const commit = (v: string) => {
+    onValueChange(v);
+    setOpen(false);
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActive((i) => Math.min(i + 1, filtered.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      const o = filtered[active];
+      if (o) commit(o.value);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      setOpen(false);
+    }
+  };
+
+  return (
+    <div className={cn("relative", className)} ref={rootRef}>
+      <button
+        ref={triggerRef}
+        type="button"
+        id={id}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-label={ariaLabel}
+        onClick={() => setOpen((v) => !v)}
+        className={cn(
+          "flex h-8 w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-2.5 transition-colors",
+          "hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        )}
+      >
+        <span className={cn("truncate", !selected && "text-muted-foreground")}>
+          {selected ? selected.label : placeholder}
+        </span>
+        <ChevronDown
+          className={cn(
+            "size-3.5 shrink-0 text-muted-foreground transition-transform",
+            open && "rotate-180",
+          )}
+          aria-hidden="true"
+        />
+      </button>
+      {open &&
+        pos &&
+        typeof document !== "undefined" &&
+        createPortal(
+          <div
+            ref={listRef}
+            style={{
+              position: "fixed",
+              left: pos.left,
+              width: pos.width,
+              top: pos.top,
+              bottom: pos.bottom,
+              maxHeight: pos.maxHeight,
+            }}
+            className="vui-pop-in z-[200] flex flex-col overflow-hidden rounded-md border border-border bg-popover text-popover-foreground shadow-md"
+          >
+            <div className="relative border-b border-border p-1.5">
+              <Search className="pointer-events-none absolute left-3 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+              <input
+                ref={inputRef}
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+                onKeyDown={onKeyDown}
+                placeholder={searchPlaceholder}
+                aria-label={ariaLabel ? `Search ${ariaLabel}` : "Search"}
+                className="h-8 w-full rounded-sm bg-transparent pl-8 pr-2 text-sm outline-none placeholder:text-muted-foreground"
+              />
+            </div>
+            <div role="listbox" aria-label={ariaLabel} className="overflow-auto">
+              {filtered.length === 0 ? (
+                <div className="px-3 py-6 text-center text-sm text-muted-foreground">
+                  {emptyText}
+                </div>
+              ) : (
+                filtered.map((o, i) => {
+                  const isSelected = o.value === value;
+                  return (
+                    <button
+                      key={o.value}
+                      type="button"
+                      role="option"
+                      aria-selected={isSelected}
+                      onMouseEnter={() => setActive(i)}
+                      onClick={() => commit(o.value)}
+                      className={cn(
+                        "flex w-full items-center justify-between gap-2 border-b border-border px-3 py-2 text-left last:border-b-0",
+                        i === active && "bg-accent text-accent-foreground",
+                        isSelected && "bg-accent/60",
+                      )}
+                    >
+                      <span className="truncate">{o.label}</span>
+                      {isSelected && (
+                        <Check className="size-3.5 shrink-0 text-[var(--button-primary)]" />
+                      )}
+                    </button>
+                  );
+                })
+              )}
+            </div>
+          </div>,
+          document.body,
+        )}
+    </div>
+  );
+}

package/src/record-view.tsx

@@ -38,6 +38,7 @@ import { Button } from "./button";
 import { Checkbox } from "./checkbox";
 import { Input } from "./input";
 import { Select } from "./select";
+import { Combobox } from "./combobox";
 import {
   Table,
   TableBody,
@@ -226,15 +227,33 @@ 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
    *  `Select`, and the selection toolbar offers a "Set {label}" bulk action. */
   options?: { value: string; label: string }[];
   /** Form control for the Add/Edit panel/page. Default `"text"` (auto-growing
-   *  textarea). `"number"`/`"date"` render the matching native input; a field
-   *  with `options` always renders a `Select` regardless of this. */
-  input?: "text" | "number" | "date";
+   *  textarea). `"number"`/`"date"` render the matching native input. For a
+   *  field with `options`: default renders a `Select`, and `"combobox"` renders
+   *  a searchable `Combobox` (type-to-filter) — use it for long option lists. */
+  input?: "text" | "number" | "date" | "combobox";
+  /** Render a custom Add/Edit control — a checkbox, a radio group, a color
+   *  picker, anything. Overrides the default control entirely (and takes
+   *  priority over `options`/`input`). You get the current string value and an
+   *  `onChange` to write it back; the surrounding label, required mark, and Save
+   *  validation still come from the field. Read-only View uses `render`. */
+  renderInput?: (props: {
+    value: string;
+    onChange: (value: string) => void;
+    field: RecordField<T>;
+    invalid?: boolean;
+  }) => React.ReactNode;
   /** 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
@@ -460,6 +479,12 @@ 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);
@@ -1086,7 +1111,18 @@ export function RecordView<T extends { id: RowId }>({
                         <label className="text-xs font-medium text-muted-foreground">
                           {label}
                         </label>
-                        {control === "select" || control === "combobox" ? (
+                        {control === "combobox" ? (
+                          <Combobox
+                            value={typeof raw === "string" ? raw : ""}
+                            onValueChange={setVal}
+                            options={opts}
+                            ariaLabel={label}
+                            placeholder={
+                              cfg.placeholder ?? `Any ${label.toLowerCase()}`
+                            }
+                            className="w-full"
+                          />
+                        ) : control === "select" ? (
                           <Select
                             value={typeof raw === "string" ? raw : ""}
                             onValueChange={setVal}
@@ -1182,7 +1218,7 @@ export function RecordView<T extends { id: RowId }>({
 
           <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)}
@@ -1300,32 +1336,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>
                 );
@@ -1743,15 +1791,34 @@ function RecordDetailPanel<T extends { id: RowId }>({
                 {f.render ? (
                   <div>{f.render(draft)}</div>
                 ) : !readOnly && f.editable ? (
-                  f.options ? (
-                    <Select
-                      value={String(draft[f.key as keyof T] ?? "")}
-                      onValueChange={(v) => setField(f.key as keyof T, v)}
-                      options={f.options}
-                      ariaLabel={f.label}
-                      placeholder={`Select ${f.label.toLowerCase()}…`}
-                      className="w-full"
-                    />
+                  f.renderInput ? (
+                    // Consumer-supplied control (checkbox, radio, custom widget).
+                    f.renderInput({
+                      value: String(draft[f.key as keyof T] ?? ""),
+                      onChange: (v) => setField(f.key as keyof T, v),
+                      field: f,
+                      invalid: errors.has(f.key),
+                    })
+                  ) : f.options ? (
+                    f.input === "combobox" ? (
+                      <Combobox
+                        value={String(draft[f.key as keyof T] ?? "")}
+                        onValueChange={(v) => setField(f.key as keyof T, v)}
+                        options={f.options}
+                        ariaLabel={f.label}
+                        placeholder={`Select ${f.label.toLowerCase()}…`}
+                        className="w-full"
+                      />
+                    ) : (
+                      <Select
+                        value={String(draft[f.key as keyof T] ?? "")}
+                        onValueChange={(v) => setField(f.key as keyof T, v)}
+                        options={f.options}
+                        ariaLabel={f.label}
+                        placeholder={`Select ${f.label.toLowerCase()}…`}
+                        className="w-full"
+                      />
+                    )
                   ) : f.input === "number" || f.input === "date" ? (
                     <Input
                       type={f.input}

package/template/app/(app)/organizations/organizations-config.tsx

@@ -65,6 +65,26 @@ export const fields: RecordField<DemoOrganization>[] = [
       { value: "trial", label: "Trial" },
       { value: "suspended", label: "Suspended" },
     ],
+    // `renderInput` drops ANY component into the Add/Edit form — here a radio
+    // group instead of the default Select. Swap it for a checkbox, a slider, a
+    // color picker… the field still owns the label, required mark and Save
+    // validation. (View still shows the Badge via `render`.)
+    renderInput: ({ value, onChange, field }) => (
+      <div role="radiogroup" aria-label={field.label} className="flex flex-wrap gap-4">
+        {(field.options ?? []).map((o) => (
+          <label key={o.value} className="flex items-center gap-1.5 text-sm">
+            <input
+              type="radio"
+              name={`org-${field.key}`}
+              checked={value === o.value}
+              onChange={() => onChange(o.value)}
+              className="accent-[var(--button-primary)]"
+            />
+            {o.label}
+          </label>
+        ))}
+      </div>
+    ),
     render: (row) => {
       const status = statusBadge[row.status];
       return <Badge variant={status.variant}>{status.label}</Badge>;

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

@@ -21,6 +21,9 @@ const fields: RecordField<Region>[] = [
     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,
   },
   {