robobyte-front-builder 1.0.19 → 1.0.21

package/src/views/builder/viewer/renderers/dataGridComponents.jsx

@@ -0,0 +1,824 @@
+/**
+ * Custom AG Grid cell renderers and editors for DataGridRenderer.
+ *
+ * Register via the `components` prop on <AgGridReact>.
+ * Reference by string name in colDef: cellRenderer: 'ChipRenderer', etc.
+ *
+ * ── Cell Renderers ────────────────────────────────────────────────────────────
+ *  All renderers accept either a single value or an array of strings/values.
+ *  valueFormatter controls what arrives — if it returns a string or array of
+ *  strings the renderer will handle both transparently.
+ *  - Multi-item renderers (ChipRenderer, LinkRenderer, IconRenderer) render one
+ *    component per array element.
+ *  - Scalar renderers (BooleanRenderer, CurrencyRenderer, DateRenderer,
+ *    ProgressRenderer, AvatarRenderer) use the first array element.
+ *
+ *  ChipRenderer       — MUI Chip with color mapping per value
+ *  BooleanRenderer    — check / cross icon for truthy/falsy values
+ *  LinkRenderer       — clickable anchor; href from params or value
+ *  CurrencyRenderer   — formatted number with prefix/suffix/decimals
+ *  DateRenderer       — formatted date string
+ *  ProgressRenderer   — LinearProgress bar (value 0-100 or custom max)
+ *  AvatarRenderer     — circular image or initials avatar
+ *  IconRenderer       — MUI icon by name stored in the cell value
+ *
+ * ── Cell Editors ─────────────────────────────────────────────────────────────
+ *  SelectEditor       — MUI Select with options list
+ *  AutocompleteEditor — MUI Autocomplete (searchable Select)
+ *  CheckboxEditor     — boolean MUI Checkbox
+ *  DateEditor         — native <input type="date">
+ *  NumberEditor       — numeric input with min / max / step
+ *
+ * ── cellRendererParams reference ─────────────────────────────────────────────
+ *  ChipRenderer:       { colorMap: { Active:'success', Closed:'error' }, defaultColor:'default', size:'small'|'medium', variant:'filled'|'outlined' }
+ *  BooleanRenderer:    { trueColor:'success.main', falseColor:'error.main', trueIcon:'CheckCircle', falseIcon:'Cancel' }
+ *  LinkRenderer:       { href: 'https://...', hrefField:'url', target:'_blank', label:'Open' }
+ *  CurrencyRenderer:   { prefix:'$', suffix:'', decimals:2, locale:'en-US' }
+ *  DateRenderer:       { format:'short'|'medium'|'long'|'iso' | Intl options object, locale:'en-US' }
+ *  ProgressRenderer:   { max:100, color:'primary'|'secondary'|'success'|'error'|'warning'|'info', showLabel:true }
+ *  AvatarRenderer:     { srcField:'avatarUrl', size:32, shape:'circle'|'square' }
+ *  IconRenderer:       { size:'small'|'medium'|'large', color:'inherit'|'primary'|'error'|... }
+ *
+ * ── cellEditorParams reference ────────────────────────────────────────────────
+ *  SelectEditor:       { options: ['A','B'] | [{ value, label }], placeholder:'Select...' }
+ *  AutocompleteEditor: { options: ['A','B'] | [{ value, label }], placeholder:'Search...' }
+ *  CheckboxEditor:     { color:'primary'|'secondary'|'success'|'error' }
+ *  DateEditor:         { min:'2020-01-01', max:'2099-12-31' }
+ *  NumberEditor:       { min:0, max:100, step:1, decimals:2 }
+ *  MultiSelectEditor:  Static options via settings; overridable with async code.
+ *    options         — static array: string[] | object[]  (configured in column settings)
+ *    asyncFetchOptions — async (searchTerm?) => object[]  (code override, takes precedence)
+ *    isSingle        — boolean, default false (multi-select)
+ *    fieldName       — string | string[]  property path(s) to use as label (default 'name')
+ *    groupByField    — string  property path to group options by
+ *    targetValue     — string | string[]  property path(s) to extract as final getValue() result
+ */
+
+import { forwardRef, useImperativeHandle, useRef, useState, useEffect } from 'react'
+import {
+  Chip, Box, LinearProgress, Typography, Avatar,
+  Checkbox, Select, MenuItem, TextField, Autocomplete,
+} from '@mui/material'
+import {
+  CheckCircleOutlined, CancelOutlined, OpenInNew,
+} from '@mui/icons-material'
+import { resolveIcon } from 'services/builderHelper/iconResolver'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MUI_COLOR_MAP = {
+  success: 'success', error: 'error', warning: 'warning',
+  info: 'info', primary: 'primary', secondary: 'secondary', default: 'default',
+}
+
+function normaliseMuiColor(c) { return MUI_COLOR_MAP[c] ?? 'default' }
+
+/**
+ * Normalise a cell value to a non-empty array of primitives.
+ * Handles: undefined, null, '', single value, array.
+ * Objects are skipped — use valueFormatter to extract the display string first.
+ */
+function toArray(value) {
+  if (value === null || value === undefined || value === '') return []
+  const arr = Array.isArray(value) ? value : [value]
+  return arr.filter(v => v !== null && v !== undefined && v !== '' && typeof v !== 'object')
+}
+
+/**
+ * Resolve the display value for a renderer.
+ * AG Grid passes the RAW value as `value` and the valueFormatter result as `valueFormatted`.
+ * Prefer `valueFormatted` so formatters that return arrays of strings are honoured.
+ */
+function resolveDisplay(value, valueFormatted) {
+  // If formatter returned something useful (string or array), use it
+  if (valueFormatted !== null && valueFormatted !== undefined && valueFormatted !== '') {
+    return valueFormatted
+  }
+  return value
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Cell Renderers ────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * ChipRenderer
+ * Renders a MUI Chip whose color is looked up from `colorMap[value]`.
+ * colorMap values should be MUI palette keys: success | error | warning | info | primary | secondary | default
+ */
+export function ChipRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const items = toArray(resolveDisplay(value, valueFormatted))
+  if (!items.length) return null
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 0.5, height: '100%' }}>
+      {items.map((item, i) => (
+        <Chip
+          key={i}
+          label={String(item)}
+          color={normaliseMuiColor(p.colorMap?.[item] ?? p.defaultColor)}
+          size={p.size ?? 'small'}
+          variant={p.variant ?? 'filled'}
+        />
+      ))}
+    </Box>
+  )
+}
+
+/**
+ * BooleanRenderer
+ * Shows a check or cross icon for truthy/falsy values.
+ */
+export function BooleanRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const display = resolveDisplay(value, valueFormatted)
+  // For arrays use the first element; an array itself is truthy so unwrap first
+  const scalar = Array.isArray(display) ? display[0] : display
+  const isTrue = Boolean(scalar)
+  const TrueIcon  = resolveIcon(p.trueIcon  ?? 'CheckCircleOutlined')  ?? CheckCircleOutlined
+  const FalseIcon = resolveIcon(p.falseIcon ?? 'CancelOutlined') ?? CancelOutlined
+  const Icon = isTrue ? TrueIcon : FalseIcon
+  const color = isTrue ? (p.trueColor ?? 'success.main') : (p.falseColor ?? 'error.main')
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', height: '100%' }}>
+      <Icon sx={{ fontSize: 18, color }} />
+    </Box>
+  )
+}
+
+/**
+ * LinkRenderer
+ * Renders the cell value as a hyperlink.
+ * href is resolved from: colDef.cellRendererParams.href (static)
+ *   OR colDef.cellRendererParams.hrefField (row field name)
+ *   OR the cell value itself (if it looks like a URL).
+ */
+export function LinkRenderer({ value, valueFormatted, data, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const display = resolveDisplay(value, valueFormatted)
+  // Static href / hrefField always renders a single link regardless of value type
+  const staticHref = p.href ?? (p.hrefField ? data?.[p.hrefField] : null)
+  const items = staticHref ? [{ href: staticHref, label: p.label ?? (Array.isArray(display) ? display.join(', ') : display) }]
+    : toArray(display).map(v => ({ href: String(v), label: p.label ?? v }))
+  if (!items.length) return null
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 0.5, height: '100%' }}>
+      {items.map((item, i) => (
+        <a
+          key={i}
+          href={String(item.href)}
+          target={p.target ?? '_blank'}
+          rel='noreferrer'
+          style={{ display: 'inline-flex', alignItems: 'center', gap: 4, color: 'inherit', textDecoration: 'underline' }}
+          onClick={e => e.stopPropagation()}
+        >
+          {item.label}
+          {(p.target ?? '_blank') === '_blank' && <OpenInNew sx={{ fontSize: 12 }} />}
+        </a>
+      ))}
+    </Box>
+  )
+}
+
+/**
+ * CurrencyRenderer
+ * Formats the value as a number with a prefix, suffix, and decimal places.
+ */
+export function CurrencyRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const display = resolveDisplay(value, valueFormatted)
+  // Use first element if array
+  const scalar = Array.isArray(display) ? display[0] : display
+  if (scalar === null || scalar === undefined || scalar === '') return null
+  const num = Number(scalar)
+  if (isNaN(num)) return <span>{String(scalar)}</span>
+  const decimals = p.decimals ?? 2
+  const formatted = num.toLocaleString(p.locale ?? 'en-US', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  })
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', height: '100%', justifyContent: 'flex-end' }}>
+      <span>{(p.prefix ?? '') + formatted + (p.suffix ?? '')}</span>
+    </Box>
+  )
+}
+
+/**
+ * DateRenderer
+ * Formats the value as a localised date string.
+ * format: 'short' | 'medium' | 'long' | 'iso' | Intl.DateTimeFormat options object
+ */
+export function DateRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const display = resolveDisplay(value, valueFormatted)
+  // Use first element if array
+  const scalar = Array.isArray(display) ? display[0] : display
+  if (!scalar) return null
+  try {
+    const date = new Date(scalar)
+    if (isNaN(date.getTime())) return <span>{String(scalar)}</span>
+
+    let display
+    const fmt = p.format ?? 'short'
+    if (fmt === 'iso') {
+      display = date.toISOString().slice(0, 10)
+    } else {
+      const presets = {
+        short:  { year: 'numeric', month: 'short',  day: '2-digit' },
+        medium: { year: 'numeric', month: 'long',   day: '2-digit' },
+        long:   { year: 'numeric', month: 'long',   day: '2-digit', weekday: 'long' },
+      }
+      const opts = (typeof fmt === 'object' && fmt !== null) ? fmt : (presets[fmt] ?? presets.short)
+      display = date.toLocaleDateString(p.locale ?? undefined, opts)
+    }
+    return (
+      <Box sx={{ display: 'flex', alignItems: 'center', height: '100%' }}>
+        <span>{display}</span>
+      </Box>
+    )
+  } catch {
+    return <span>{String(scalar)}</span>
+  }
+}
+
+/**
+ * ProgressRenderer
+ * Renders value as a LinearProgress bar (0–max, default max=100).
+ */
+export function ProgressRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const max = p.max ?? 100
+  const display = resolveDisplay(value, valueFormatted)
+  // Use first element if array
+  const scalar = Array.isArray(display) ? display[0] : display
+  const num = Math.min(Math.max(Number(scalar) || 0, 0), max)
+  const pct = (num / max) * 100
+  const color = p.color ?? 'primary'
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', height: '100%', gap: 1, width: '100%', pr: 1 }}>
+      <LinearProgress
+        variant='determinate'
+        value={pct}
+        color={color}
+        sx={{ flexGrow: 1, borderRadius: 1, height: 6 }}
+      />
+      {p.showLabel !== false && (
+        <Typography variant='caption' sx={{ whiteSpace: 'nowrap', minWidth: 32, textAlign: 'right' }}>
+          {num}{p.unit ?? ''}
+        </Typography>
+      )}
+    </Box>
+  )
+}
+
+/**
+ * AvatarRenderer
+ * Renders an Avatar: image from `srcField` row property, or initials from value.
+ */
+export function AvatarRenderer({ value, valueFormatted, data, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const src = p.srcField ? data?.[p.srcField] : null
+  const size = p.size ?? 28
+  const display = resolveDisplay(value, valueFormatted)
+  // Use first element if array
+  const scalar = Array.isArray(display) ? display[0] : display
+  const initials = scalar
+    ? String(scalar).split(' ').slice(0, 2).map(w => w[0]).join('').toUpperCase()
+    : '?'
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', height: '100%', gap: 1 }}>
+      <Avatar
+        src={src ?? undefined}
+        sx={{
+          width: size, height: size, fontSize: size * 0.4,
+          borderRadius: p.shape === 'square' ? 1 : '50%',
+        }}
+      >
+        {!src && initials}
+      </Avatar>
+      {scalar && <span>{String(scalar)}</span>}
+    </Box>
+  )
+}
+
+/**
+ * IconRenderer
+ * Renders an MUI icon whose name is the cell value.
+ * e.g. value = 'CheckCircle' renders the CheckCircle icon.
+ */
+export function IconRenderer({ value, valueFormatted, colDef }) {
+  const p = colDef?.cellRendererParams ?? {}
+  const items = toArray(resolveDisplay(value, valueFormatted))
+  if (!items.length) return null
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 0.5, height: '100%' }}>
+      {items.map((item, i) => {
+        const Icon = resolveIcon(String(item))
+        return Icon
+          ? <Icon key={i} fontSize={p.size ?? 'small'} color={p.color ?? 'inherit'} />
+          : <span key={i}>{String(item)}</span>
+      })}
+    </Box>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ── Cell Editors ─────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * SelectEditor
+ * A MUI Select populated from cellEditorParams.options.
+ * options: string[] | { value, label }[]
+ */
+export const SelectEditor = forwardRef(function SelectEditor(props, ref) {
+  const p = props.colDef?.cellEditorParams ?? {}
+  const rawOptions = p.options ?? []
+  const options = rawOptions.map(o =>
+    typeof o === 'object' && o !== null ? o : { value: o, label: String(o) }
+  )
+
+  const [value, setValue] = useState(props.value ?? '')
+
+  useImperativeHandle(ref, () => ({
+    getValue() { return value },
+    isCancelBeforeStart() { return false },
+  }))
+
+  return (
+    <Select
+      value={value}
+      onChange={e => setValue(e.target.value)}
+      size='small'
+      autoFocus
+      open
+      displayEmpty
+      sx={{ width: '100%', height: '100%', '& .MuiSelect-select': { py: 0.5 } }}
+    >
+      {p.placeholder && <MenuItem value=''><em>{p.placeholder}</em></MenuItem>}
+      {options.map(o => (
+        <MenuItem key={o.value} value={o.value}>{o.label}</MenuItem>
+      ))}
+    </Select>
+  )
+})
+
+/**
+ * AutocompleteEditor
+ * A MUI Autocomplete (searchable) populated from cellEditorParams.options.
+ */
+export const AutocompleteEditor = forwardRef(function AutocompleteEditor(props, ref) {
+  const p = props.colDef?.cellEditorParams ?? {}
+  const rawOptions = p.options ?? []
+  const options = rawOptions.map(o =>
+    typeof o === 'object' && o !== null ? o : { value: o, label: String(o) }
+  )
+
+  const initialOpt = options.find(o => o.value === props.value) ?? { value: props.value ?? '', label: String(props.value ?? '') }
+  const [selected, setSelected] = useState(initialOpt)
+  const inputRef = useRef(null)
+
+  useEffect(() => { setTimeout(() => inputRef.current?.focus(), 0) }, [])
+
+  useImperativeHandle(ref, () => ({
+    getValue() { return selected?.value ?? '' },
+    isCancelBeforeStart() { return false },
+  }))
+
+  return (
+    <Autocomplete
+      options={options}
+      value={selected}
+      onChange={(_, newVal) => setSelected(newVal ?? { value: '', label: '' })}
+      getOptionLabel={o => o?.label ?? ''}
+      isOptionEqualToValue={(o, v) => o?.value === v?.value}
+      openOnFocus
+      disableClearable
+      size='small'
+      sx={{ width: '100%' }}
+      renderInput={params => (
+        <TextField
+          {...params}
+          inputRef={inputRef}
+          placeholder={p.placeholder ?? 'Search...'}
+          variant='outlined'
+          size='small'
+          sx={{ '& .MuiInputBase-root': { height: '100%' } }}
+        />
+      )}
+    />
+  )
+})
+
+/**
+ * CheckboxEditor
+ * Toggles a boolean value in-cell.
+ */
+export const CheckboxEditor = forwardRef(function CheckboxEditor(props, ref) {
+  const p = props.colDef?.cellEditorParams ?? {}
+  const [checked, setChecked] = useState(Boolean(props.value))
+
+  useImperativeHandle(ref, () => ({
+    getValue() { return checked },
+    isCancelBeforeStart() { return false },
+  }))
+
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', height: '100%', px: 0.5 }}>
+      <Checkbox
+        checked={checked}
+        onChange={e => setChecked(e.target.checked)}
+        color={p.color ?? 'primary'}
+        size='small'
+        autoFocus
+      />
+    </Box>
+  )
+})
+
+/**
+ * DateEditor
+ * Native date input — lightweight, no extra MUI dependency.
+ * Stores value as ISO date string (YYYY-MM-DD).
+ */
+export const DateEditor = forwardRef(function DateEditor(props, ref) {
+  const p = props.colDef?.cellEditorParams ?? {}
+  // Normalise stored value to YYYY-MM-DD for the input
+  const toInputValue = v => {
+    if (!v) return ''
+    try {
+      const d = new Date(v)
+      if (isNaN(d.getTime())) return v
+      return d.toISOString().slice(0, 10)
+    } catch { return v }
+  }
+
+  const [value, setValue] = useState(toInputValue(props.value))
+  const inputRef = useRef(null)
+  useEffect(() => { inputRef.current?.focus() }, [])
+
+  useImperativeHandle(ref, () => ({
+    getValue() { return value },
+    isCancelBeforeStart() { return false },
+  }))
+
+  return (
+    <input
+      ref={inputRef}
+      type='date'
+      value={value}
+      min={p.min ?? undefined}
+      max={p.max ?? undefined}
+      onChange={e => setValue(e.target.value)}
+      style={{
+        width: '100%', height: '100%', border: 'none', outline: 'none',
+        padding: '0 8px', fontSize: 13, background: 'transparent',
+        boxSizing: 'border-box', cursor: 'pointer',
+      }}
+    />
+  )
+})
+
+/**
+ * NumberEditor
+ * Numeric text input with optional min / max / step / decimals.
+ */
+export const NumberEditor = forwardRef(function NumberEditor(props, ref) {
+  const p = props.colDef?.cellEditorParams ?? {}
+  const [value, setValue] = useState(props.value ?? '')
+  const inputRef = useRef(null)
+  useEffect(() => { inputRef.current?.focus(); inputRef.current?.select() }, [])
+
+  useImperativeHandle(ref, () => ({
+    getValue() {
+      const num = parseFloat(value)
+      if (isNaN(num)) return props.value ?? null
+      const dec = p.decimals ?? null
+      return dec !== null ? parseFloat(num.toFixed(dec)) : num
+    },
+    isCancelBeforeStart() { return false },
+  }))
+
+  return (
+    <input
+      ref={inputRef}
+      type='number'
+      value={value}
+      min={p.min ?? undefined}
+      max={p.max ?? undefined}
+      step={p.step ?? 'any'}
+      onChange={e => setValue(e.target.value)}
+      style={{
+        width: '100%', height: '100%', border: 'none', outline: 'none',
+        padding: '0 8px', fontSize: 13, background: 'transparent',
+        boxSizing: 'border-box', textAlign: 'right',
+      }}
+    />
+  )
+})
+
+/**
+ * MultiSelectEditor
+ *
+ * Rendered as an AG Grid popup editor (isPopup = true).
+ * AG Grid's popup mode means it does NOT close the editor when the user clicks
+ * inside it — no event propagation fights needed.
+ *
+ * cellEditorParams shape:
+ *   options           string[] | object[]            static options
+ *   asyncFetchOptions async (search?: string) => []  dynamic options (takes precedence)
+ *   isSingle          boolean   single vs multi       default: false
+ *   fieldName         string | string[]  label path   default: 'name'
+ *   groupByField      string             group-by path
+ *   targetValue       string | string[]  getValue() extraction path
+ */
+export const MultiSelectEditor = forwardRef(function MultiSelectEditor(props, ref) {
+  const rawCep = props.colDef?.cellEditorParams
+  const cepObj = (rawCep && typeof rawCep === 'object' && typeof rawCep !== 'function') ? rawCep : {}
+
+  // Params come from props root when cellEditorParams was a function (AG Grid merges result),
+  // or from cepObj when it was a plain object.
+  const asyncFetchOptions = props.asyncFetchOptions ?? cepObj.asyncFetchOptions ?? null
+  const isSingle          = props.isSingle     ?? cepObj.isSingle     ?? false
+  const fieldName         = props.fieldName    ?? cepObj.fieldName    ?? 'name'
+  const targetValue       = props.targetValue  ?? cepObj.targetValue  ?? null
+  const groupByField      = props.groupByField ?? cepObj.groupByField ?? null
+  const staticOptions     = props.options      ?? cepObj.options      ?? []
+
+  // getViewerContext() returns the latest viewerContext from DataGridRenderer —
+  // used to provide fresh data / setData / reportRefs to asyncFetchOptions.
+  const getViewerContext = props.context?.getViewerContext ?? (() => ({}))
+
+  const initialValue = props.value ?? (isSingle ? null : [])
+  const selectedRef  = useRef(initialValue)        // sync ref for getValue()
+  const [selected,  setSelected]  = useState(initialValue)
+  const [options,   setOptions]   = useState(staticOptions)
+  const [search,    setSearch]    = useState('')
+  const [debSearch, setDebSearch] = useState('')
+  const [loading,   setLoading]   = useState(false)
+  const searchRef = useRef(null)
+
+  // Build the second-arg scope for asyncFetchOptions — mirrors what convertStringToFunction injects.
+  // This lets users write: async (search, { data, setData, dataRef, reportRefs }) => { ... }
+  // and get live values even when called without the second argument.
+  const buildAsyncScope = () => {
+    const vCtx = getViewerContext()
+    return {
+      data:       vCtx.data       ?? {},
+      setData:    vCtx.setData    ?? (() => {}),
+      dataRef:    vCtx.dataRef    ?? { current: {} },
+      reportRefs: vCtx.reportRefs ?? { current: {} },
+    }
+  }
+
+  useEffect(() => { setTimeout(() => searchRef.current?.focus(), 0) }, [])
+
+  // Debounce search
+  useEffect(() => {
+    const t = setTimeout(() => setDebSearch(search), 300)
+    return () => clearTimeout(t)
+  }, [search])
+
+  // Initial async fetch
+  useEffect(() => {
+    if (!asyncFetchOptions) return
+    setLoading(true)
+    Promise.resolve(asyncFetchOptions('', buildAsyncScope()))
+      .then(res => setOptions(Array.isArray(res) ? res : []))
+      .catch(e => console.error('[MultiSelectEditor] asyncFetchOptions error:', e))
+      .finally(() => setLoading(false))
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Re-fetch on debounced search (async only; static filtered client-side below)
+  useEffect(() => {
+    if (!asyncFetchOptions || debSearch === '') return
+    setLoading(true)
+    Promise.resolve(asyncFetchOptions(debSearch, buildAsyncScope()))
+      .then(res => setOptions(Array.isArray(res) ? res : []))
+      .catch(e => console.error('[MultiSelectEditor] asyncFetchOptions search error:', e))
+      .finally(() => setLoading(false))
+  }, [debSearch]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  function getNestedProperty(obj, path) {
+    if (!path || !obj) return obj
+    if (Array.isArray(path)) {
+      return path.map(k => k.split('.').reduce((a, p) => a?.[p], obj)).filter(Boolean).join(' - ')
+    }
+    return path.split('.').reduce((a, k) => a?.[k], obj)
+  }
+
+  function getLabel(opt) {
+    if (opt === null || opt === undefined) return ''
+    if (typeof opt !== 'object') return String(opt)
+    const label = Array.isArray(fieldName)
+      ? fieldName.map(f => getNestedProperty(opt, f)).filter(Boolean).join(' - ')
+      : (getNestedProperty(opt, fieldName) ?? opt?.name ?? '')
+    return label != null ? String(label) : ''
+  }
+
+  function optionId(opt) {
+    return opt?.id ?? JSON.stringify(opt)
+  }
+
+  function isOptSelected(opt) {
+    if (isSingle) return optionId(selectedRef.current) === optionId(opt)
+    return (Array.isArray(selectedRef.current) ? selectedRef.current : [])
+      .some(s => optionId(s) === optionId(opt))
+  }
+
+  // Compute the final committed value — mirrors what getValue() exposes via the ref.
+  // Called directly inside commit() because AG Grid v33 React destroys the popup
+  // component before invoking getValue() through the ref, so we can't rely on that path.
+  const getEditorValue = () => {
+    const val = selectedRef.current
+    if (targetValue != null && val != null) {
+      if (Array.isArray(val)) return val.map(v => getNestedProperty(v, targetValue))
+      return getNestedProperty(val, targetValue)
+    }
+    return val
+  }
+
+  useImperativeHandle(ref, () => ({
+    // Kept for AG Grid compatibility — may be called in non-popup scenarios.
+    getValue() {
+      const result = getEditorValue()
+      console.log('[MultiSelectEditor] getValue() via ref → returning:', result)
+      return result
+    },
+    isCancelBeforeStart() { return false },
+    isPopup() { return true },
+    getPopupPosition() { return 'under' },
+  }))
+
+  const commit = () => {
+    const value = getEditorValue()
+    console.log('[MultiSelectEditor] commit() — final value:', value, 'field:', props.colDef?.field)
+
+    // AG Grid v33 React destroys popup editors before calling getValue() through the ref.
+    // Work around by setting the data value directly, which triggers valueSetter +
+    // onCellValueChanged exactly the same as the normal AG Grid commit flow.
+    if (props.node && props.colDef?.field) {
+      props.node.setDataValue(props.colDef.field, value)
+    }
+
+    // Temporarily remove valueSetter before stopEditing(true) so AG Grid's cancel/revert
+    // path does not call it with the old (pre-edit) value and overwrite what we just committed.
+    // The revert call is synchronous, so restoring immediately after is safe.
+    const savedVS = props.colDef?.valueSetter
+    if (props.colDef) delete props.colDef.valueSetter
+
+    if (typeof props.stopEditing === 'function') {
+      props.stopEditing(true)
+    } else {
+      props.api?.stopEditing?.(true)
+    }
+
+    if (props.colDef && savedVS) props.colDef.valueSetter = savedVS
+  }
+
+  const handleSelect = (opt) => {
+    let next
+    if (isSingle) {
+      next = opt
+    } else {
+      const cur = Array.isArray(selectedRef.current) ? selectedRef.current : []
+      next = isOptSelected(opt)
+        ? cur.filter(s => optionId(s) !== optionId(opt))
+        : [...cur, opt]
+    }
+    selectedRef.current = next
+    setSelected(next)
+    console.log('[MultiSelectEditor] handleSelect → next:', next, 'isSingle:', isSingle)
+    if (isSingle) setTimeout(commit, 0)
+  }
+
+  // Static options: filter client-side; async options: server filters via debSearch
+  const visibleOptions = asyncFetchOptions
+    ? options
+    : options.filter(opt => getLabel(opt).toLowerCase().includes(search.toLowerCase()))
+
+  const grouped = groupByField
+    ? visibleOptions.reduce((acc, opt) => {
+        const g = getNestedProperty(opt, groupByField) ?? 'Other'
+        ;(acc[g] = acc[g] ?? []).push(opt)
+        return acc
+      }, {})
+    : null
+
+  const selectedArr = Array.isArray(selected) ? selected : []
+
+  return (
+    <Box
+      sx={{
+        width: 260,
+        maxHeight: 340,
+        bgcolor: '#fff',
+        border: '1px solid #e0e0e0',
+        borderRadius: 1,
+        boxShadow: '0 4px 16px rgba(0,0,0,0.18)',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+      }}
+    >
+      {/* Search */}
+      <Box sx={{ p: 0.75, borderBottom: '1px solid #f0f0f0' }}>
+        <input
+          ref={searchRef}
+          value={search}
+          onChange={e => setSearch(e.target.value)}
+          placeholder='Search…'
+          style={{
+            width: '100%', border: '1px solid #e0e0e0', borderRadius: 4,
+            padding: '4px 8px', fontSize: 13, outline: 'none', boxSizing: 'border-box',
+          }}
+        />
+      </Box>
+
+      {/* Options */}
+      <Box sx={{ overflowY: 'auto', flex: 1 }}>
+        {loading && <Typography sx={{ p: 1, fontSize: 12, color: '#999' }}>Loading…</Typography>}
+        {!loading && visibleOptions.length === 0 && (
+          <Typography sx={{ p: 1, fontSize: 12, color: '#999' }}>No options</Typography>
+        )}
+        {!loading && (grouped
+          ? Object.entries(grouped).map(([group, opts]) => (
+              <Box key={group}>
+                <Typography sx={{ px: 1.5, py: 0.5, fontSize: 11, fontWeight: 700, color: '#888', textTransform: 'uppercase', letterSpacing: '0.05em', bgcolor: '#fafafa' }}>
+                  {group}
+                </Typography>
+                {opts.map((opt, i) => (
+                  <OptionRow key={optionId(opt) ?? i} opt={opt} selected={isOptSelected(opt)} label={getLabel(opt)} isSingle={isSingle} onSelect={handleSelect} />
+                ))}
+              </Box>
+            ))
+          : visibleOptions.map((opt, i) => (
+              <OptionRow key={optionId(opt) ?? i} opt={opt} selected={isOptSelected(opt)} label={getLabel(opt)} isSingle={isSingle} onSelect={handleSelect} />
+            ))
+        )}
+      </Box>
+
+      {/* Footer — multi only */}
+      {!isSingle && (
+        <Box sx={{ p: 0.75, borderTop: '1px solid #f0f0f0', display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <Typography sx={{ fontSize: 11, color: '#888' }}>{selectedArr.length} selected</Typography>
+          <Box
+            component='button'
+            onClick={commit}
+            sx={{
+              px: 1.5, py: 0.4, fontSize: 12, fontWeight: 600,
+              bgcolor: 'primary.main', color: '#fff', border: 'none',
+              borderRadius: 1, cursor: 'pointer',
+              '&:hover': { bgcolor: 'primary.dark' },
+            }}
+          >
+            Confirm
+          </Box>
+        </Box>
+      )}
+    </Box>
+  )
+})
+
+function OptionRow({ opt, selected, label, isSingle, onSelect }) {
+  return (
+    <Box
+      onClick={() => onSelect(opt)}
+      sx={{
+        display: 'flex', alignItems: 'center', gap: 1,
+        px: 1.5, py: 0.6, cursor: 'pointer', fontSize: 13,
+        bgcolor: selected ? '#e8f0fe' : 'transparent',
+        '&:hover': { bgcolor: selected ? '#d2e3fc' : '#f5f5f5' },
+      }}
+    >
+      {!isSingle && <Checkbox checked={selected} size='small' sx={{ p: 0 }} readOnly tabIndex={-1} />}
+      {label}
+    </Box>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AG Grid components map — pass this to <AgGridReact components={AG_COMPONENTS}>
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AG_COMPONENTS = {
+  // Renderers
+  ChipRenderer,
+  BooleanRenderer,
+  LinkRenderer,
+  CurrencyRenderer,
+  DateRenderer,
+  ProgressRenderer,
+  AvatarRenderer,
+  IconRenderer,
+  // Editors
+  SelectEditor,
+  AutocompleteEditor,
+  CheckboxEditor,
+  DateEditor,
+  NumberEditor,
+  MultiSelectEditor,
+}