@viliha/vui-ui 1.9.0 → 1.11.0

package/AGENT.md

@@ -336,6 +336,10 @@ Never hand-build an HTML table; always use `RecordView`. Configure columns throu
 
 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>`.
+
+Dependent/cascading options: make `options` (form) or `filterable.options` (filter) a function — `(draft) => …` in the form, `(values) => …` in the filter — and one field's choices depend on another; RecordView clears the child when the parent change invalidates it. Keep `options` a static array for the bulk "Set {label}" action. If a field has both a function `options` and `renderInput`, guard with `Array.isArray(field.options)` before mapping (renderInput doesn't get the draft to resolve it).
+
 ## 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,52 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.11.0 — 2026-07-26
+
+### Added
+
+- **Dependent (cascading) options in `RecordView`** — a choice field's
+  options can now depend on another field's current value, in both the
+  Add/Edit form and the Filter panel. Opt-in, backward compatible.
+  - Form: `RecordField.options` may be a **function of the draft** —
+    `((draft) => { value, label }[])` — recomputed as the draft changes.
+  - Filter: `FieldFilter.options` may be a **function of the current filter
+    values** — `((values) => { value, label }[])`. `FieldFilter` is now generic
+    (`FieldFilter<T>`).
+  - **Auto-clear:** when the parent changes and the child&apos;s value is no
+    longer a valid option, RecordView clears it (form and filter). Static-array
+    options are unchanged; the bulk "Set {label}" action only lists static-option
+    fields (no single draft to resolve a function against).
+
+  **For agents:** for a dependent picker (e.g. Country → State) pass a function
+  to `options` / `filterable.options`; don&apos;t manually reset the child. If a
+  field uses a function `options` *and* `renderInput`, guard with
+  `Array.isArray(field.options)` before mapping. Demo: `system/cities`
+  (Country → State) in both form and filter. Docs: `/docs/data-table`.
+
+## 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

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.9.0",
+  "version": "1.11.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,
@@ -186,16 +187,21 @@ export type FilterControl =
  *  `{ 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 {
+export interface FieldFilter<T = Record<string, unknown>> {
   /** 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 }[];
+  /** Choices for `select` / `combobox` / `checkbox`. A static array, or a
+   *  function of the current filter values for cascading filters (e.g. Country
+   *  options derived from the selected Region) — the panel recomputes it on every
+   *  change and clears a value that's no longer valid. Falls back to the field's
+   *  own (static) `options` when omitted. */
+  options?:
+    | { value: string; label: string }[]
+    | ((values: FilterValues<T>) => { value: string; label: string }[]);
 }
 
 /** Values collected by the Filter panel, keyed by field. Single-value controls
@@ -235,19 +241,38 @@ export interface RecordField<T> {
   /** 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 }[];
+   *  `Select` (or `Combobox`), and the selection toolbar offers a "Set {label}"
+   *  bulk action. A static array, or a function of the current draft for
+   *  dependent/cascading options (e.g. Country choices derived from the selected
+   *  Region) — the form recomputes it as the draft changes and clears the field
+   *  when its value is no longer a valid option. (Bulk "Set {label}" only lists
+   *  static-array option fields, since it has no single draft to resolve against.) */
+  options?:
+    | { value: string; label: string }[]
+    | ((draft: Partial<T>) => { 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
    *  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;
+  filterable?: boolean | FieldFilter<T>;
 }
 
 /**
@@ -303,6 +328,15 @@ function clearPersisted(key: string | undefined) {
   }
 }
 
+/** Resolve a choice field's form options against the current draft: a static
+ *  array, or a function of the draft (cascading pickers). */
+function resolveOptions<T>(
+  opts: RecordField<T>["options"],
+  draft: Partial<T>,
+): { value: string; label: string }[] {
+  return typeof opts === "function" ? opts(draft) : (opts ?? []);
+}
+
 interface RecordViewProps<T extends { id: RowId }> {
   title: string;
   singular: string;
@@ -563,6 +597,32 @@ export function RecordView<T extends { id: RowId }>({
     setPage(1);
   }, [filter, pageSize, setPage]);
 
+  // Cascading filter options: when the values change, drop any filter value no
+  // longer valid once its options recompute (e.g. changing Region invalidates a
+  // Country filter). Only function-options filters cascade. Strings clear; multi
+  // (checkbox) arrays keep the still-valid entries.
+  React.useEffect(() => {
+    let changed = false;
+    const next: FilterValues<T> = { ...filterValues };
+    for (const f of fields) {
+      const cfg = typeof f.filterable === "object" ? f.filterable : null;
+      if (!cfg || typeof cfg.options !== "function") continue;
+      const valid = new Set(cfg.options(filterValues).map((o) => o.value));
+      const v = filterValues[f.key];
+      if (typeof v === "string" && v && !valid.has(v)) {
+        next[f.key] = "";
+        changed = true;
+      } else if (Array.isArray(v)) {
+        const kept = v.filter((x) => valid.has(x));
+        if (kept.length !== v.length) {
+          next[f.key] = kept;
+          changed = true;
+        }
+      }
+    }
+    if (changed) setFilterValues(next);
+  }, [filterValues, fields, setFilterValues]);
+
   function startEdit(row: T, key: string) {
     setEditing({ id: row.id, key });
     setDraft(String(row[key as keyof T] ?? ""));
@@ -805,7 +865,11 @@ export function RecordView<T extends { id: RowId }>({
   const allSelected =
     processed.length > 0 && selected.size === processed.length;
   // Choice fields (with `options`) power the "Set …" bulk actions.
-  const bulkFields = fields.filter((f) => f.options && f.options.length > 0);
+  // Only static-array option fields — bulk "Set {label}" has no single draft to
+  // resolve a function-options field against.
+  const bulkFields = fields.filter(
+    (f) => Array.isArray(f.options) && f.options.length > 0,
+  );
   // Per-column alignment (auto: numbers + short codes center).
   const columnAligns = React.useMemo(
     () => computeColumnAligns(fields, initialData),
@@ -1059,7 +1123,7 @@ export function RecordView<T extends { id: RowId }>({
               {bulkFields.map((f) => (
                 <React.Fragment key={f.key}>
                   <DropdownLabel>Set {f.label}</DropdownLabel>
-                  {f.options?.map((o) => (
+                  {(Array.isArray(f.options) ? f.options : []).map((o) => (
                     <DropdownItem
                       key={o.value}
                       onSelect={() => bulkSetField(f.key, o.value)}
@@ -1085,11 +1149,18 @@ export function RecordView<T extends { id: RowId }>({
                 <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 =
+                    const cfg: FieldFilter<T> =
                       typeof f.filterable === "object" ? f.filterable : {};
                     const control = cfg.control ?? "text";
                     const label = cfg.label ?? f.label;
-                    const opts = cfg.options ?? f.options ?? [];
+                    // Options: cfg's static array or function of the current
+                    // filter values (cascading); fall back to the field's static
+                    // options (a draft-function can't resolve here).
+                    const opts =
+                      typeof cfg.options === "function"
+                        ? cfg.options(filterValues)
+                        : (cfg.options ??
+                          (Array.isArray(f.options) ? f.options : []));
                     const raw = filterValues[f.key];
                     const setVal = (v: string | string[]) =>
                       setFilterValues((prev) => ({ ...prev, [f.key]: v }));
@@ -1098,7 +1169,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}
@@ -1680,6 +1762,25 @@ function RecordDetailPanel<T extends { id: RowId }>({
     setDraft(row);
   }, [row, setDraft]);
 
+  // Cascading options: after the draft changes, clear any choice field whose
+  // value is no longer valid once its options recompute (e.g. changing Region
+  // drops a now-invalid Country). Only function-options fields cascade; static
+  // ones never invalidate. Settles in one pass — cleared values are "" and skip.
+  React.useEffect(() => {
+    const stale = fields.filter((f) => {
+      if (typeof f.options !== "function") return false;
+      const v = draft[f.key as keyof T];
+      if (v == null || v === "") return false;
+      return !f.options(draft).some((o) => o.value === String(v));
+    });
+    if (stale.length === 0) return;
+    setDraft((d) => {
+      let next = d;
+      for (const f of stale) next = { ...next, [f.key]: "" };
+      return next;
+    });
+  }, [draft, fields, setDraft]);
+
   const primary = getPrimary(draft);
   const HeaderIcon = TitleIcon ?? DEFAULT_FIELD_ICON;
 
@@ -1767,15 +1868,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={resolveOptions(f.options, draft)}
+                        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={resolveOptions(f.options, draft)}
+                        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">
+        {(Array.isArray(field.options) ? 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/cities/cities-table.tsx

@@ -1,28 +1,100 @@
 "use client";
 
+import { useMemo, useState } from "react";
 import {
   BookmarkIcon as Flag,
   HomeIcon as Landmark,
   SewingPinFilledIcon as MapPin,
 } 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 { cities, type City } from "@/lib/mock-data";
 
+// Option lists derived from the data.
+const COUNTRIES = [...new Set(cities.map((c) => c.country))]
+  .sort()
+  .map((c) => ({ value: c, label: c }));
+const statesFor = (country?: string) =>
+  [...new Set(cities.filter((c) => c.country === country).map((c) => c.state))]
+    .sort()
+    .map((s) => ({ value: s, label: s }));
+
+// Cascading options: State choices depend on the selected Country. `options` as
+// a function receives the live draft (form) or filter values (filter); when the
+// parent changes, RecordView clears a now-invalid State automatically.
 const fields: RecordField<City>[] = [
   { key: "name", label: "Name", editable: true, required: true, group: "General", hideInTable: true },
-  { key: "state", label: "State", icon: MapPin, editable: true, group: "General" },
-  { key: "country", label: "Country", icon: Flag, editable: true, group: "General" },
+  {
+    key: "country",
+    label: "Country",
+    icon: Flag,
+    editable: true,
+    group: "General",
+    input: "combobox",
+    options: COUNTRIES,
+    filterable: { control: "select", options: COUNTRIES },
+  },
+  {
+    key: "state",
+    label: "State",
+    icon: MapPin,
+    editable: true,
+    group: "General",
+    input: "combobox",
+    // Form: states for the country in the current draft.
+    options: (draft) => statesFor(draft.country),
+    filterable: {
+      control: "combobox",
+      // Filter: states for the country in the current filter values.
+      options: (values) =>
+        statesFor(typeof values.country === "string" ? values.country : undefined),
+    },
+  },
 ];
 
 export function CitiesTable() {
+  const [all, setAll] = useState<City[]>(cities);
+  const [filters, setFilters] = useState<FilterValues<City>>({});
+
+  // Demo: match the cascading filter values client-side (swap for a server query).
+  const rows = useMemo(
+    () =>
+      all.filter((r) =>
+        Object.entries(filters).every(([k, v]) => {
+          const needle = String(v ?? "").toLowerCase();
+          return !needle || String(r[k as keyof City]).toLowerCase() === needle;
+        }),
+      ),
+    [all, filters],
+  );
+
+  const handleChange = (next: City[]) => {
+    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))
+        .map((r) => nextById.get(r.id) ?? r);
+      const added = next.filter((r) => !prev.some((p) => p.id === r.id));
+      return [...kept, ...added];
+    });
+  };
+
   return (
     <RecordView
       title="Cities"
       singular="City"
       icon={Landmark}
+      persistKey="/system/cities"
       fields={fields}
-      initialData={cities}
+      initialData={rows}
+      data={rows}
+      onDataChange={handleChange}
+      onFilter={setFilters}
       getPrimary={(row) => ({
         title: row.name,
         subtitle: row.country,