@viliha/vui-ui 1.10.0 → 1.11.0

package/AGENT.md

@@ -338,6 +338,8 @@ Sorting follows column visibility by default; use `sortable` to decouple them
 
 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,29 @@ 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

package/package.json

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

@@ -187,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
@@ -236,8 +241,15 @@ 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. For a
    *  field with `options`: default renders a `Select`, and `"combobox"` renders
@@ -260,7 +272,7 @@ export interface RecordField<T> {
    *  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>;
 }
 
 /**
@@ -316,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;
@@ -576,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] ?? ""));
@@ -818,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),
@@ -1072,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)}
@@ -1098,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 }));
@@ -1704,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;
 
@@ -1804,7 +1881,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
                       <Combobox
                         value={String(draft[f.key as keyof T] ?? "")}
                         onValueChange={(v) => setField(f.key as keyof T, v)}
-                        options={f.options}
+                        options={resolveOptions(f.options, draft)}
                         ariaLabel={f.label}
                         placeholder={`Select ${f.label.toLowerCase()}…`}
                         className="w-full"
@@ -1813,7 +1890,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
                       <Select
                         value={String(draft[f.key as keyof T] ?? "")}
                         onValueChange={(v) => setField(f.key as keyof T, v)}
-                        options={f.options}
+                        options={resolveOptions(f.options, draft)}
                         ariaLabel={f.label}
                         placeholder={`Select ${f.label.toLowerCase()}…`}
                         className="w-full"

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

@@ -71,7 +71,7 @@ export const fields: RecordField<DemoOrganization>[] = [
     // 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) => (
+        {(Array.isArray(field.options) ? field.options : []).map((o) => (
           <label key={o.value} className="flex items-center gap-1.5 text-sm">
             <input
               type="radio"

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,