@exxatdesignux/ui 0.2.18 → 0.3.0

package/src/components/data-table/index.tsx

@@ -0,0 +1,1678 @@
+"use client"
+
+/**
+ * DataTable<TData> — generic reusable table (no pagination)
+ *
+ * Column features:
+ *   • Resizable     — drag trailing-edge handle on any non-locked column
+ *   • Drag-to-reorder — drag header cell for free (unpinned) columns
+ *   • Pin Left / Pin Right / Unpin — per-column context menu
+ *   • Sort Asc / Desc — per-column context menu (sortable columns)
+ *   • Wrap Text / Unwrap — per-column context menu
+ *   • Per-column quick search
+ *   • Row selection (checkboxes + floating bulk action bar)
+ *   • Group by (collapsible group rows)
+ *   • Hidden columns
+ *
+ * WCAG 2.1 AA:
+ *   ✓ aria-sort on sortable <th>
+ *   ✓ aria-label on every icon-only button
+ *   ✓ Select / Actions columns: sr-only header text + resolved labels for controls
+ *   ✓ Row checkboxes: visible on row focus-within, stop row click propagation (default control size; extended hit slop on Checkbox)
+ *   ✓ Bulk-action bar: role="status" aria-live="polite"
+ *   ✓ Resize handles: role="separator" aria-label
+ */
+
+import * as React from "react"
+import { useTheme } from "next-themes"
+import { createPortal } from "react-dom"
+import { cn } from "../../lib/utils"
+import { rafThrottle } from "../../lib/raf-throttle"
+import { Button } from "../ui/button"
+import { Input } from "../ui/input"
+import { Kbd, KbdGroup } from "../ui/kbd"
+import { Tip } from "../ui/tip"
+import { useModKeyLabel } from "../../hooks/use-mod-key-label"
+import { isEditableTarget } from "../../lib/editable-target"
+import { Checkbox } from "../ui/checkbox"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "../ui/dropdown-menu"
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+  PopoverTrigger,
+} from "../ui/popover"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../ui/tooltip"
+import { OPERATOR_LABELS } from "../../lib/table-properties-types"
+import type { ActiveFilter } from "../../lib/table-properties-types"
+import { getConditionalCellBackground } from "../../lib/conditional-rule-match"
+import { formatYmdForDisplay } from "../../lib/date-filter"
+import { FilterDateCalendar } from "./filter-date-calendar"
+import { FilterTextValueInput } from "./filter-text-value-input"
+import type { DataTableProps, ColumnDef, SortDir } from "./types"
+import { useTableState } from "./use-table-state"
+
+/** When `ColumnDef.label` is empty, use a standard name for select/actions columns. */
+function defaultColumnHeaderLabel(key: string): string | undefined {
+  switch (key) {
+    case "select":
+      return "Select"
+    case "actions":
+      return "Actions"
+    default:
+      return undefined
+  }
+}
+
+function resolvedColumnLabel<TData>(col: ColumnDef<TData>): string {
+  const t = col.label?.trim()
+  if (t) return t
+  return defaultColumnHeaderLabel(col.key) ?? col.key
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal sub-components
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SortChevron = React.memo(function SortChevron({ dir }: { dir: SortDir }) {
+  return (
+    <i className={`fa-solid fa-arrow-${dir === "asc" ? "up" : "down"} ms-1 text-xs`} aria-hidden="true" />
+  )
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FilterPill — active filter pill with inline editor popover
+// (driven by ColumnDef.filter config rather than FILTER_FIELDS)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface FilterPillProps<TData> {
+  filter: ActiveFilter
+  columns: ColumnDef<TData>[]
+  defaultOpen?: boolean
+  onUpdate: (id: string, patch: Partial<ActiveFilter>) => void
+  onRemove: (id: string) => void
+  /** Optional custom cell renderer for filter option values */
+  renderOptionValue?: (fieldKey: string, value: string) => React.ReactNode
+}
+
+function FilterPillBase<TData>({
+  filter,
+  columns,
+  defaultOpen = false,
+  onUpdate,
+  onRemove,
+  renderOptionValue,
+}: FilterPillProps<TData>) {
+  const [open, setOpen] = React.useState(false)
+  const [optSearch, setOptSearch] = React.useState("")
+  const justAutoOpenedRef = React.useRef(false)
+
+  React.useEffect(() => {
+    if (defaultOpen) {
+      justAutoOpenedRef.current = true
+      const t = setTimeout(() => {
+        setOpen(true)
+        setTimeout(() => { justAutoOpenedRef.current = false }, 400)
+      }, 0)
+      return () => clearTimeout(t)
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const col = columns.find(c => c.key === filter.fieldKey)
+  const filterDef = col?.filter
+
+  React.useEffect(() => {
+    if (!filterDef) return
+    if (filterDef.type !== "select" && filterDef.type !== "date") return
+    if (filter.operator !== "is" && filter.operator !== "is_not") {
+      onUpdate(filter.id, { operator: "is" })
+    }
+  }, [filter.id, filterDef, filter.operator, onUpdate])
+
+  if (!filterDef) return null
+
+  const options = filterDef.options ?? []
+  const showSearch = options.length > 8
+  const filteredOpts = optSearch
+    ? options.filter(o => o.label.toLowerCase().includes(optSearch.toLowerCase()))
+    : options
+
+  const operators = filterDef.operators ?? (
+    filterDef.type === "select" || filterDef.type === "date"
+      ? (["is", "is_not"] as const)
+      : (["contains", "not_contains"] as const)
+  )
+
+  const valueLabel = (() => {
+    if (filterDef.type === "select") {
+      if (filter.values.length === 0) return "…"
+      if (filter.values.length === 1) {
+        return options.find(o => o.value === filter.values[0])?.label ?? filter.values[0]
+      }
+      return `${filter.values.length} selected`
+    }
+    if (filterDef.type === "date") {
+      const ymd = filter.values[0]
+      return ymd ? formatYmdForDisplay(ymd) : "…"
+    }
+    return filter.values[0] || "…"
+  })()
+
+  function toggleValue(val: string) {
+    const next = filter.values.includes(val)
+      ? filter.values.filter(v => v !== val)
+      : [...filter.values, val]
+    onUpdate(filter.id, { values: next })
+  }
+
+  function cycleOperator() {
+    const idx = operators.indexOf(filter.operator as typeof operators[number])
+    const i = idx === -1 ? 0 : idx
+    onUpdate(filter.id, { operator: operators[(i + 1) % operators.length] })
+  }
+
+  const isActive =
+    filterDef.type === "date"
+      ? Boolean(filter.values[0])
+      : filter.values.length > 0
+  const hasSelection = filter.values.length > 0
+  const iconClass = filterDef.icon ? `fa-light ${filterDef.icon}` : "fa-light fa-filter"
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverAnchor asChild>
+      <div
+        className={cn(
+          "inline-flex cursor-pointer items-center rounded border text-xs transition-colors",
+          isActive ? "border-brand/45 bg-brand/10" : "border-input bg-background"
+        )}
+      >
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            className={cn(
+              "inline-flex cursor-pointer items-center gap-1 h-6 ps-2 pe-1.5 rounded-s transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+              isActive ? "hover:bg-brand/15" : "hover:bg-interactive-hover",
+            )}
+          >
+            <i
+              className={cn(iconClass, "text-xs", isActive ? "text-brand" : "text-muted-foreground")}
+              aria-hidden="true"
+            />
+            <span className="text-foreground">{col.label}</span>
+            {isActive && <span className="text-foreground font-medium">{valueLabel}</span>}
+          </button>
+        </PopoverTrigger>
+        <button
+          type="button"
+          aria-label={`Remove ${col.label} filter`}
+          onClick={() => onRemove(filter.id)}
+          className={cn(
+            "inline-flex cursor-pointer items-center justify-center h-6 w-5 rounded-e transition-colors",
+            "text-muted-foreground hover:text-destructive",
+            isActive ? "hover:bg-brand/15" : "hover:bg-interactive-hover",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+          )}
+        >
+          <i className="fa-light fa-xmark text-xs" aria-hidden="true" />
+        </button>
+      </div>
+      </PopoverAnchor>
+
+      <PopoverContent
+        className={cn(
+          "p-0",
+          filterDef.type === "date"
+            ? "w-auto max-w-[min(calc(100vw-2rem),22rem)]"
+            : "w-64",
+        )}
+        align="start"
+        onFocusOutside={e => e.preventDefault()}
+        onInteractOutside={e => {
+          if (justAutoOpenedRef.current) {
+            e.preventDefault()
+            justAutoOpenedRef.current = false
+          }
+        }}
+      >
+        <div className="flex items-center justify-between px-3 py-2 border-b border-border">
+          <div className="flex items-center gap-1 text-sm text-foreground">
+            <span className="font-medium">{col.label}</span>
+            <button
+              type="button"
+              onClick={cycleOperator}
+              className="inline-flex items-center gap-0.5 text-muted-foreground hover:text-interactive-hover-foreground transition-colors rounded px-1 py-0.5 hover:bg-interactive-hover"
+            >
+              {OPERATOR_LABELS[filter.operator]}
+              <i className="fa-light fa-chevron-down text-xs" aria-hidden="true" />
+            </button>
+          </div>
+          <button
+            type="button"
+            aria-label="Remove filter"
+            onClick={() => onRemove(filter.id)}
+            className="text-muted-foreground hover:text-destructive transition-colors p-1 rounded hover:bg-interactive-hover"
+          >
+            <i className="fa-light fa-trash text-xs" aria-hidden="true" />
+          </button>
+        </div>
+
+        {filterDef.type === "date" && (
+          <div className="p-2">
+            <FilterDateCalendar
+              label={`${col.label} — choose date`}
+              valueYmd={filter.values[0]}
+              onChangeYmd={(ymd) =>
+                onUpdate(filter.id, { values: ymd ? [ymd] : [] })
+              }
+            />
+          </div>
+        )}
+
+        {filterDef.type === "select" && (
+          <div className="py-1 max-h-64 overflow-y-auto">
+            {showSearch && (
+              <div className="px-2 pt-1 pb-1">
+                <div className="relative">
+                  <Input
+                    type="text"
+                    placeholder="Search options…"
+                    value={optSearch}
+                    onChange={e => setOptSearch(e.target.value)}
+                    className={cn("h-7 text-xs", optSearch ? "pe-8" : "pe-2")}
+                    autoFocus
+                  />
+                  {optSearch ? (
+                    <button
+                      type="button"
+                      aria-label="Clear option search"
+                      onClick={() => setOptSearch("")}
+                      className="absolute end-1 top-1/2 -translate-y-1/2 inline-flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:text-interactive-hover-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    >
+                      <i className="fa-light fa-xmark text-xs" aria-hidden="true" />
+                    </button>
+                  ) : null}
+                </div>
+              </div>
+            )}
+            {filteredOpts.map(opt => {
+              const checked = filter.values.includes(opt.value)
+              return (
+                <div
+                  key={opt.value}
+                  role="option"
+                  aria-selected={checked}
+                  tabIndex={0}
+                  onClick={() => toggleValue(opt.value)}
+                  onKeyDown={e => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); toggleValue(opt.value) } }}
+                  className="flex w-full items-center gap-2.5 px-3 py-1.5 text-sm hover:bg-interactive-hover transition-colors cursor-pointer select-none focus-visible:outline-none focus-visible:bg-interactive-hover"
+                >
+                  <span
+                    aria-hidden="true"
+                    data-slot="checkbox"
+                    data-state={checked ? "checked" : "unchecked"}
+                    className={cn(
+                      "inline-flex items-center justify-center size-3.5 shrink-0 rounded-[4px] border transition-colors",
+                      checked ? "bg-primary border-primary text-primary-foreground" : "border-input bg-background"
+                    )}
+                  >
+                    {checked && <i className="fa-solid fa-check text-current" style={{ fontSize: "8px" }} />}
+                  </span>
+                  {renderOptionValue
+                    ? renderOptionValue(filter.fieldKey, opt.value)
+                    : <span className="text-foreground">{opt.label}</span>
+                  }
+                </div>
+              )
+            })}
+            {filteredOpts.length === 0 && (
+              <p className="px-3 py-2 text-xs text-muted-foreground">No options found</p>
+            )}
+          </div>
+        )}
+
+        {filterDef.type === "text" && (
+          <div className="p-2">
+            <FilterTextValueInput
+              mask={filterDef.textMask}
+              placeholder={`Enter ${col.label.toLowerCase()}…`}
+              value={filter.values[0] ?? ""}
+              onValueChange={next => onUpdate(filter.id, { values: [next] })}
+              aria-label={`${col.label} filter value`}
+              className="h-8 text-xs focus-visible:border-ring focus-visible:ring-ring/50"
+              autoFocus
+            />
+          </div>
+        )}
+        {hasSelection ? (
+          <div className="sticky bottom-0 border-t border-border bg-popover p-2">
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => onUpdate(filter.id, { values: [] })}
+              className="w-full justify-center gap-1.5 text-xs text-muted-foreground"
+            >
+              <i className="fa-light fa-xmark text-xs" aria-hidden="true" />
+              Clear selection
+            </Button>
+          </div>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+// React.memo wrapper — preserves generic signature via cast.
+// FilterPillBase is a pure function of its props; memoizing it prevents
+// re-renders when unrelated table state (hover, scroll) changes.
+const FilterPill = React.memo(FilterPillBase) as typeof FilterPillBase
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sticky shadow utility
+// ─────────────────────────────────────────────────────────────────────────────
+
+function stickyShadow(pin: "left" | "right" | undefined): string {
+  if (!pin) return ""
+  const base = "after:content-[''] after:absolute after:top-0 after:bottom-0 after:w-3 after:pointer-events-none"
+  if (pin === "left") {
+    return cn(
+      base,
+      "after:start-full",
+      "after:bg-[linear-gradient(to_right,var(--sticky-edge-fade),transparent)]",
+    )
+  }
+  return cn(
+    base,
+    "after:end-full",
+    "after:bg-[linear-gradient(to_left,var(--sticky-edge-fade),transparent)]",
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DataTableToolbar — search, filter bar, properties slot (shared by table + board)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function DataTableToolbar<TData extends Record<string, unknown>>({
+  state,
+  columns,
+  searchable = true,
+  /** When false, hides filter pills, search, and filter controls (e.g. dashboard canvas edit mode). */
+  showQueryControls = true,
+  renderFilterOptionValue,
+  toolbarSlot,
+  searchAriaLabel = "Search table",
+}: {
+  state: ReturnType<typeof useTableState<TData>>
+  columns: ColumnDef<TData>[]
+  searchable?: boolean
+  showQueryControls?: boolean
+  renderFilterOptionValue?: (fieldKey: string, value: string) => React.ReactNode
+  toolbarSlot?: (state: ReturnType<typeof useTableState<TData>>) => React.ReactNode
+  /** Passed to the search input `aria-label` (e.g. "Search placements") */
+  searchAriaLabel?: string
+}) {
+  const {
+    search, setSearch, searchOpen, setSearchOpen, searchRef,
+    activeFilters, setActiveFilters, openFilterId,
+    filterBarVisible, setFilterBarVisible,
+    addFilter, updateFilter, removeFilter,
+  } = state
+
+  const filterableCols = columns.filter(c => c.filter)
+  const searchModLabel = useModKeyLabel()
+  const effectiveSearchable = showQueryControls && searchable
+
+  React.useEffect(() => {
+    if (!effectiveSearchable) return
+    function onGlobalKeyDown(e: KeyboardEvent) {
+      if (!e.metaKey && !e.ctrlKey) return
+      if (e.altKey) return
+      if (e.key.toLowerCase() !== "k") return
+      if (isEditableTarget(e.target)) return
+      e.preventDefault()
+      setSearchOpen(true)
+      queueMicrotask(() => searchRef.current?.focus())
+    }
+    document.addEventListener("keydown", onGlobalKeyDown)
+    return () => document.removeEventListener("keydown", onGlobalKeyDown)
+  }, [effectiveSearchable, setSearchOpen, searchRef])
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-1.5 px-4 lg:px-6",
+        showQueryControls ? "min-h-10 pt-2 pb-2" : "min-h-0 justify-end py-1.5",
+      )}
+    >
+
+      {showQueryControls && filterBarVisible && filterableCols.length > 0 && (
+        <div className="flex flex-wrap items-center gap-1.5 flex-1 min-w-0">
+          {activeFilters.map(filter => (
+            <React.Fragment key={filter.id}>
+              <FilterPill
+                filter={filter}
+                columns={columns}
+                defaultOpen={filter.id === openFilterId}
+                onUpdate={updateFilter}
+                onRemove={removeFilter}
+                renderOptionValue={renderFilterOptionValue}
+              />
+            </React.Fragment>
+          ))}
+
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <button type="button"
+                className="inline-flex cursor-pointer items-center gap-1 h-6 px-2 rounded text-xs text-muted-foreground hover:text-interactive-hover-foreground border border-dashed border-input/70 hover:border-input hover:bg-interactive-hover-subtle transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+                Add filter
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="start">
+              <DropdownMenuLabel className="text-xs">Filter by field</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              {filterableCols.map(c => (
+                <DropdownMenuItem key={c.key} onClick={() => addFilter(c.key)}>
+                  {c.filter?.icon && <i className={`fa-light ${c.filter.icon}`} aria-hidden="true" />}
+                  {c.label}
+                </DropdownMenuItem>
+              ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+
+          {activeFilters.length > 0 && (
+            <button
+              type="button"
+              onClick={() => setActiveFilters([])}
+              className="cursor-pointer text-xs text-muted-foreground hover:text-interactive-hover-foreground transition-colors px-1"
+            >
+              Clear all
+            </button>
+          )}
+        </div>
+      )}
+
+      <div
+        className={cn(
+          "flex items-center gap-1 shrink-0",
+          showQueryControls && "ms-auto",
+        )}
+      >
+
+        {effectiveSearchable && (
+          searchOpen ? (
+            <div className="relative flex items-center">
+              <i className="fa-light fa-magnifying-glass absolute start-2.5 top-1/2 -translate-y-1/2 text-muted-foreground text-xs pointer-events-none" aria-hidden="true" />
+              <Input
+                ref={searchRef}
+                type="text"
+                role="searchbox"
+                inputMode="search"
+                autoComplete="off"
+                placeholder="Search…"
+                value={search}
+                onChange={e => setSearch(e.target.value)}
+                onBlur={() => { if (!search) setSearchOpen(false) }}
+                onKeyDown={e => { if (e.key === "Escape") { setSearch(""); setSearchOpen(false) } }}
+                className={cn("h-8 w-48 ps-7 text-xs", search ? "pe-8" : "pe-2")}
+                aria-label={searchAriaLabel}
+              />
+              {search ? (
+                <button
+                  type="button"
+                  aria-label="Clear search"
+                  onClick={() => setSearch("")}
+                  className="absolute end-1.5 top-1/2 -translate-y-1/2 inline-flex cursor-pointer size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:text-interactive-hover-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <i className="fa-light fa-xmark text-xs" aria-hidden="true" />
+                </button>
+              ) : null}
+            </div>
+          ) : (
+            <TooltipProvider>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <button type="button" aria-label="Search"
+                    onClick={() => { setSearchOpen(true); setTimeout(() => searchRef.current?.focus(), 10) }}
+                    className="inline-flex shrink-0 cursor-pointer items-center justify-center size-8 rounded-md text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    <i className="fa-light fa-magnifying-glass text-[13px]" aria-hidden="true" />
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="bottom">
+                  <span>{searchAriaLabel}</span>
+                  <KbdGroup>
+                    <Kbd>{searchModLabel}</Kbd>
+                    <Kbd>K</Kbd>
+                  </KbdGroup>
+                </TooltipContent>
+              </Tooltip>
+            </TooltipProvider>
+          )
+        )}
+
+        {showQueryControls && filterableCols.length > 0 && (
+          <>
+            <div className="h-4 w-px bg-border/70" aria-hidden="true" />
+            {activeFilters.length > 0 ? (
+              <TooltipProvider>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <button type="button"
+                      aria-label={filterBarVisible ? "Hide filters" : "Show filters"}
+                      onClick={() => setFilterBarVisible(v => !v)}
+                      className={cn(
+                        "inline-flex shrink-0 cursor-pointer items-center gap-1 size-8 justify-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                        filterBarVisible
+                          ? "bg-accent text-accent-foreground hover:bg-accent/90"
+                          : "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover",
+                      )}
+                    >
+                      <i className="fa-light fa-filter text-[13px]" aria-hidden="true" />
+                      <span className="text-xs font-semibold tabular-nums">{activeFilters.length}</span>
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom">
+                    {filterBarVisible ? "Hide filters" : "Show filters"}
+                  </TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+            ) : (
+              // NOTE: Tooltip MUST wrap DropdownMenuTrigger directly (not the
+              // surrounding <DropdownMenu> wrapper). Radix `asChild` Slot needs
+              // a real DOM child — `<DropdownMenu>` is a logical wrapper, so
+              // putting it inside TooltipTrigger swallows the tooltip handlers
+              // and the hover hint silently disappears.
+              <DropdownMenu>
+                <TooltipProvider>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <DropdownMenuTrigger asChild>
+                        <button type="button" aria-label="Add filter"
+                          onClick={() => setFilterBarVisible(true)}
+                          className="inline-flex shrink-0 cursor-pointer items-center justify-center size-8 rounded-md text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                        >
+                          <i className="fa-light fa-filter text-[13px]" aria-hidden="true" />
+                        </button>
+                      </DropdownMenuTrigger>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom">Add filter</TooltipContent>
+                  </Tooltip>
+                </TooltipProvider>
+                <DropdownMenuContent align="end">
+                  <DropdownMenuLabel className="text-xs">Filter by field</DropdownMenuLabel>
+                  <DropdownMenuSeparator />
+                  {filterableCols.map(c => (
+                    <DropdownMenuItem key={c.key} onClick={() => addFilter(c.key)}>
+                      {c.filter?.icon && <i className={`fa-light ${c.filter.icon}`} aria-hidden="true" />}
+                      {c.label}
+                    </DropdownMenuItem>
+                  ))}
+                </DropdownMenuContent>
+              </DropdownMenu>
+            )}
+          </>
+        )}
+
+        {toolbarSlot && toolbarSlot(state)}
+      </div>
+    </div>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DataTable<TData>
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DataTableExtendedProps<TData extends Record<string, unknown>>
+  extends DataTableProps<TData> {
+  /** Slot for a toolbar drawer button + drawer itself (e.g. TablePropertiesDrawer) */
+  toolbarSlot?: (state: ReturnType<typeof useTableState<TData>>) => React.ReactNode
+  /** Slot rendered inside the floating bulk-action bar (after the "N selected" label) */
+  bulkActionsSlot?: (selected: Set<string | number>, rows: TData[]) => React.ReactNode
+  /** Optional "add new row" row text — pass false to hide */
+  addRowLabel?: string | false
+  /** Custom option-value renderer for filter pills */
+  renderFilterOptionValue?: (fieldKey: string, value: string) => React.ReactNode
+  /** When set by DataTablePaginated — drives row slicing inside useTableState */
+  paginationOverride?: { page: number; pageSize: number }
+  /** When true, removes rounded bottom corners so a pagination bar can attach flush */
+  hasFooter?: boolean
+  /** Conditional formatting rules — apply bg color to cells based on value */
+  conditionalRules?: import("./types").ConditionalRule[]
+  /** When false, the column header row is hidden (Display options). */
+  showColumnHeaders?: boolean
+  /** When set, table uses this state (e.g. shared with board view) instead of internal useTableState. */
+  state?: ReturnType<typeof useTableState<TData>>
+}
+
+type DataTableInnerProps<TData extends Record<string, unknown>> = DataTableExtendedProps<TData> & {
+  state: ReturnType<typeof useTableState<TData>>
+}
+
+/** Max width for bulk bar in normal (non-reflow) zoom — ~28rem, centered in table. */
+const BULK_BAR_MAX_PX = 448
+
+/**
+ * When the app theme is `dark`, the bulk strip is a **light** surface; shadcn
+ * “dark:” button tokens are wrong — reapply light-look solid/outline/destructive/ghost.
+ */
+const BULK_BAR_ON_LIGHT_STRIP = cn(
+  "[&_button[data-variant=default]]:bg-zinc-900 [&_button[data-variant=default]]:text-zinc-50",
+  "hover:[&_button[data-variant=default]]:bg-zinc-800",
+  "[&_button[data-variant=outline]]:border-zinc-300/80 [&_button[data-variant=outline]]:bg-white [&_button[data-variant=outline]]:text-zinc-900",
+  "hover:[&_button[data-variant=outline]]:bg-zinc-100",
+  "[&_button[data-variant=destructive]]:border-rose-200/80 [&_button[data-variant=destructive]]:bg-rose-100 [&_button[data-variant=destructive]]:text-rose-800",
+  "hover:[&_button[data-variant=destructive]]:bg-rose-200/40",
+  "[&_button[data-variant=ghost]]:text-zinc-600 hover:[&_button[data-variant=ghost]]:bg-zinc-200/70 hover:[&_button[data-variant=ghost]]:text-zinc-900",
+)
+
+/**
+ * Pins the bulk bar to the viewport bottom, aligned to the table scroll
+ * wrapper. When `fullWidth` is false (normal zoom), width is
+ * `min(tableWidth, 28rem)` and centered; when true (reflow), matches table
+ * width.
+ */
+function useBulkBarFixedToTableScrollEl(
+  scrollRef: React.RefObject<HTMLDivElement | null>,
+  active: boolean,
+  fullWidth: boolean,
+): React.CSSProperties | undefined {
+  const [style, setStyle] = React.useState<React.CSSProperties | undefined>(undefined)
+  React.useLayoutEffect(() => {
+    if (!active) {
+      setStyle(undefined)
+      return
+    }
+    const el = scrollRef.current
+    if (!el) {
+      setStyle(undefined)
+      return
+    }
+    const apply = () => {
+      const r = el.getBoundingClientRect()
+      let left = r.left
+      let width = r.width
+      if (!fullWidth) {
+        const w = Math.min(r.width, BULK_BAR_MAX_PX)
+        left = r.left + (r.width - w) / 2
+        width = w
+      }
+      setStyle({
+        position: "fixed",
+        left,
+        width,
+        bottom: "max(0.5rem, env(safe-area-inset-bottom, 0px))",
+        zIndex: 50,
+        boxSizing: "border-box",
+        margin: 0,
+        right: "auto",
+      })
+    }
+    apply()
+    // rAF-coalesce so a single frame handles bursts of capture-phase scroll
+    // events plus the ResizeObserver firing — instead of N getBoundingClientRect
+    // + setState per second.
+    const scheduled = rafThrottle(apply)
+    const ro = new ResizeObserver(scheduled)
+    ro.observe(el)
+    window.addEventListener("resize", scheduled, { passive: true })
+    window.addEventListener("scroll", scheduled, { passive: true, capture: true })
+    return () => {
+      scheduled.cancel()
+      ro.disconnect()
+      window.removeEventListener("resize", scheduled)
+      window.removeEventListener("scroll", scheduled, { capture: true })
+    }
+  }, [active, fullWidth, scrollRef])
+  return style
+}
+
+function DataTableInner<TData extends Record<string, unknown>>({
+  // `data` / `defaultSort` flow into `useTableState` upstream; the inner table
+  // reads them via `state` and never directly here. Keep the prop slots so
+  // the public `DataTable<TData>` API stays unchanged.
+  data: _data,
+  columns,
+  getRowId: getRowIdProp,
+  getRowSelectionLabel,
+  selectable = true,
+  searchable = true,
+  emptyState,
+  onRowClick,
+  defaultSort: _defaultSort,
+  toolbarSlot,
+  bulkActionsSlot,
+  addRowLabel = false,
+  renderFilterOptionValue,
+  hasFooter = false,
+  conditionalRules,
+  showColumnHeaders = true,
+  state,
+}: DataTableInnerProps<TData>) {
+  const {
+    setSortRules,
+    sortKey, sortDir,
+    handleSortByKey,
+    addFilter,
+    groupBy, setGroupBy,
+    colMenuSearch, setColMenuSearch,
+    selected, setSelected, toggleRow, toggleAll, getRowId,
+    colWidths, startResize,
+    colPins, lockedPins,
+    pinColumn, unpinColumn,
+    colWrap, toggleWrap,
+    draggedKey, dragOverKey,
+    handleDragStart, handleDragOver, handleDrop, handleDragEnd,
+    scrollRef, handleScroll, checkOverflow,
+    isOverflowing,
+    setHoveredRow,
+    rows, pagedRows, groupedRows,
+    effectivePins, displayCols,
+    isReflowViewport,
+    stickyStyle,
+    totalWidth,
+    rowHeight,
+    showGridlines,
+    setSheetOpen,
+    setSheetInitialPanel,
+  } = state
+
+  // Mount overflow check + scrollport width for sticky group headers on horizontal scroll.
+  React.useEffect(() => {
+    const syncScrollport = () => {
+      const el = scrollRef.current
+      if (el) {
+        el.style.setProperty("--dt-scrollport-width", `${el.clientWidth}px`)
+      }
+      checkOverflow()
+    }
+    syncScrollport()
+    const el = scrollRef.current
+    if (!el) return
+    const ro = new ResizeObserver(syncScrollport)
+    ro.observe(el)
+    return () => ro.disconnect()
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  /** Pending action queued from a column-menu item that should run *after* the menu
+   * has fully closed. The Properties drawer is a non-modal Radix Sheet (`modal=false`)
+   * and Radix's DropdownMenu close cycle races with the Sheet's `onInteractOutside`
+   * / focus-return logic if we open the Sheet synchronously from `onSelect` / `onClick`.
+   * `onCloseAutoFocus` on `DropdownMenuContent` is the Radix-native hook that fires
+   * after the menu has unmounted and focus has returned — the safe moment to act. */
+  const columnMenuPendingActionRef = React.useRef<(() => void) | null>(null)
+
+  /** One-time horizontal nudge when the grid overflows and pins are active — hints that more columns scroll (overlay scrollbars, esp. Windows, are often invisible until interaction). */
+  const pinnedScrollHintDoneRef = React.useRef(false)
+  React.useEffect(() => {
+    if (!isOverflowing || isReflowViewport || Object.keys(colPins).length === 0) return
+    if (pinnedScrollHintDoneRef.current) return
+    const el = scrollRef.current
+    if (!el) return
+    if (el.scrollLeft > 2) return
+    const maxScroll = el.scrollWidth - el.clientWidth
+    if (maxScroll < 16) return
+    if (typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      pinnedScrollHintDoneRef.current = true
+      return
+    }
+
+    pinnedScrollHintDoneRef.current = true
+    const delta = Math.min(96, Math.max(28, Math.round(maxScroll * 0.14)))
+    const startDelayMs = 320
+    const dwellMs = 520
+
+    const t1 = window.setTimeout(() => {
+      el.scrollTo({ left: delta, behavior: "smooth" })
+    }, startDelayMs)
+    const t2 = window.setTimeout(() => {
+      el.scrollTo({ left: 0, behavior: "smooth" })
+    }, startDelayMs + dwellMs)
+
+    return () => {
+      window.clearTimeout(t1)
+      window.clearTimeout(t2)
+    }
+  }, [isOverflowing, isReflowViewport, colPins, scrollRef])
+
+  const lastLeftPinKey   = [...displayCols].reverse().find(c => effectivePins[c.key] === "left")?.key
+  const firstRightPinKey = displayCols.find(c => effectivePins[c.key] === "right")?.key
+
+  function floatingHeaderPinnedStyle(key: string): React.CSSProperties | undefined {
+    const pin = effectivePins[key]
+    if (!pin) return undefined
+
+    const visibleWidth =
+      typeof floatingHeaderStyle?.width === "number"
+        ? floatingHeaderStyle.width
+        : tableWrapRef.current?.clientWidth ?? floatingHeaderTableWidth
+    const maxScroll = Math.max(0, floatingHeaderTableWidth - visibleWidth)
+    const translateX = pin === "left"
+      ? headerScrollLeft
+      : headerScrollLeft - maxScroll
+
+    // The floating sticky header is horizontally translated as one table.
+    // Counter-translate pinned header cells so they remain locked to the viewport edge.
+    return { position: "relative", transform: `translateX(${translateX}px)` }
+  }
+
+  // Row IDs for the current visible rows
+  const allRowIds = rows.map((r, i) => getRowId(r, i, getRowIdProp))
+  const allSelected  = rows.length > 0 && selected.size === rows.length
+  const someSelected = selected.size > 0 && !allSelected
+  const anySelected  = selected.size > 0
+
+  const { resolvedTheme } = useTheme()
+  const isAppDark = resolvedTheme === "dark"
+
+  const bulkBarUseFixedLayout = anySelected
+  /** Reflow: bar spans table width. Normal zoom: bar centered, max 28rem. */
+  const bulkBarFixedStyle = useBulkBarFixedToTableScrollEl(
+    scrollRef,
+    bulkBarUseFixedLayout,
+    isReflowViewport,
+  )
+  const tableWrapRef = React.useRef<HTMLDivElement | null>(null)
+  const tableHeadRef = React.useRef<HTMLTableSectionElement | null>(null)
+  const [headerIsStuck, setHeaderIsStuck] = React.useState(false)
+  const [headerScrollLeft, setHeaderScrollLeft] = React.useState(0)
+  const [floatingHeaderStyle, setFloatingHeaderStyle] = React.useState<React.CSSProperties | undefined>(undefined)
+  const [floatingHeaderTableWidth, setFloatingHeaderTableWidth] = React.useState(totalWidth)
+  const [isClient, setIsClient] = React.useState(false)
+
+  React.useEffect(() => {
+    setIsClient(true)
+  }, [])
+
+  React.useEffect(() => {
+    const wrapEl = tableWrapRef.current
+    const headEl = tableHeadRef.current
+    if (!wrapEl || !headEl || !showColumnHeaders) {
+      setHeaderIsStuck(false)
+      return
+    }
+
+    const update = () => {
+      const wrapRect = wrapEl.getBoundingClientRect()
+      const headHeight = headEl.getBoundingClientRect().height || 0
+      const rootStyle = getComputedStyle(document.documentElement)
+      const headerOffset = Number.parseFloat(rootStyle.getPropertyValue("--header-height")) || 0
+      const stuck = wrapRect.top <= headerOffset && wrapRect.bottom > (headHeight + headerOffset + 1)
+      setHeaderIsStuck(prev => (prev === stuck ? prev : stuck))
+    }
+
+    update()
+    // rAF-coalesce: capture-phase scroll fires for every ancestor (sidebar,
+    // dashboard panels, anchored sheets), so a single getBoundingClientRect
+    // per frame is more than enough to keep the sticky header aligned.
+    const scheduled = rafThrottle(update)
+    window.addEventListener("scroll", scheduled, { passive: true, capture: true })
+    window.addEventListener("resize", scheduled, { passive: true })
+    return () => {
+      scheduled.cancel()
+      window.removeEventListener("scroll", scheduled, { capture: true })
+      window.removeEventListener("resize", scheduled)
+    }
+  }, [showColumnHeaders, rows.length, displayCols.length])
+
+  React.useLayoutEffect(() => {
+    if (!headerIsStuck || !showColumnHeaders) {
+      setFloatingHeaderStyle(undefined)
+      return
+    }
+    const wrapEl = tableWrapRef.current
+    if (!wrapEl) {
+      setFloatingHeaderStyle(undefined)
+      return
+    }
+
+    const apply = () => {
+      const rect = wrapEl.getBoundingClientRect()
+      const rootStyle = getComputedStyle(document.documentElement)
+      const headerOffset = Number.parseFloat(rootStyle.getPropertyValue("--header-height")) || 0
+      const cs = getComputedStyle(wrapEl)
+      const borderLeft = parseFloat(cs.borderLeftWidth) || 0
+      const borderRight = parseFloat(cs.borderRightWidth) || 0
+      const visibleWidth = Math.max(0, wrapEl.clientWidth - borderLeft - borderRight)
+      const renderedTableWidth = Math.max(
+        totalWidth,
+        visibleWidth,
+        wrapEl.querySelector("table")?.getBoundingClientRect().width ?? 0,
+      )
+      setFloatingHeaderStyle({
+        position: "fixed",
+        top: headerOffset,
+        left: rect.left + borderLeft,
+        width: visibleWidth,
+        zIndex: 50,
+      })
+      setFloatingHeaderTableWidth(renderedTableWidth)
+      setHeaderScrollLeft(wrapEl.scrollLeft)
+    }
+
+    apply()
+    const scheduled = rafThrottle(apply)
+    const ro = new ResizeObserver(scheduled)
+    ro.observe(wrapEl)
+    window.addEventListener("scroll", scheduled, { passive: true, capture: true })
+    window.addEventListener("resize", scheduled, { passive: true })
+    return () => {
+      scheduled.cancel()
+      ro.disconnect()
+      window.removeEventListener("scroll", scheduled, { capture: true })
+      window.removeEventListener("resize", scheduled)
+    }
+  }, [headerIsStuck, showColumnHeaders, totalWidth, displayCols.length])
+
+  function ariaSortAttr(colKey: string): React.AriaAttributes["aria-sort"] {
+    return sortKey !== colKey ? "none" : sortDir === "asc" ? "ascending" : "descending"
+  }
+
+  function cellStyle(key: string): React.CSSProperties {
+    return stickyStyle(key)
+  }
+
+  // ─── Render ───────────────────────────────────────────────────────────────
+  return (
+    <div className="flex min-w-0 w-full flex-col gap-0">
+
+      <DataTableToolbar
+        state={state}
+        columns={columns}
+        searchable={searchable}
+        renderFilterOptionValue={renderFilterOptionValue}
+        toolbarSlot={toolbarSlot}
+        searchAriaLabel="Search table"
+      />
+
+      {isClient && showColumnHeaders && headerIsStuck && floatingHeaderStyle
+        ? createPortal(
+          <div
+            style={floatingHeaderStyle}
+            className="pointer-events-auto"
+          >
+            <div className="overflow-hidden border border-border bg-dt-header-bg shadow-[0_10px_18px_-14px_rgba(15,23,42,0.5)] dark:shadow-[0_12px_20px_-14px_rgba(0,0,0,0.75)]">
+              <div style={{ transform: `translateX(${-headerScrollLeft}px)` }}>
+                <table
+                  className="w-full text-sm border-separate border-spacing-0"
+                  style={{ tableLayout: "fixed", width: floatingHeaderTableWidth }}
+                >
+                  <colgroup>
+                    {displayCols.map(col => (
+                      <col key={col.key} style={{ width: colWidths[col.key] ?? col.width ?? 100 }} />
+                    ))}
+                  </colgroup>
+                  <thead className="bg-dt-header-bg">
+                    <tr>
+                      {displayCols.map(col => {
+                        const isPinned = !!effectivePins[col.key]
+                        const isEdgePinCol = col.key === lastLeftPinKey || col.key === firstRightPinKey
+                        return (
+                          <th
+                            key={col.key}
+                            scope="col"
+                            style={floatingHeaderPinnedStyle(col.key)}
+                            className={cn(
+                              "h-9 px-3 text-start align-middle select-none",
+                              "text-xs font-medium text-muted-foreground tracking-wide",
+                              "bg-dt-header-bg border-b border-border",
+                              showGridlines && (!isEdgePinCol
+                                ? "border-e border-border last:border-e-0"
+                                : "last:border-e-0"),
+                              isPinned ? "z-40" : "z-30",
+                              isPinned && "relative",
+                              isEdgePinCol && stickyShadow(effectivePins[col.key]),
+                            )}
+                          >
+                            <div className="flex items-center justify-between gap-1 min-w-0">
+                              <div className="flex items-center min-w-0 flex-1">
+                                {col.key === "select" ? (
+                                  selectable && (
+                                    <span className="inline-flex items-center justify-center self-center">
+                                      <span className="sr-only">{resolvedColumnLabel(col)}</span>
+                                      <Checkbox
+                                        checked={allSelected ? true : someSelected ? "indeterminate" : false}
+                                        onCheckedChange={() => toggleAll(allRowIds)}
+                                        aria-label="Select all rows"
+                                      />
+                                    </span>
+                                  )
+                                ) : col.sortable && col.sortKey ? (
+                                  <button
+                                    type="button"
+                                    onClick={() => handleSortByKey(col.key)}
+                                    className={cn(
+                                      "inline-flex items-center hover:text-interactive-hover-foreground transition-colors whitespace-nowrap",
+                                      sortKey === col.key && "text-foreground",
+                                    )}
+                                  >
+                                    {col.label?.trim() ? col.label : resolvedColumnLabel(col)}
+                                    {sortKey === col.key ? <SortChevron dir={sortDir} /> : null}
+                                  </button>
+                                ) : (
+                                  <span className="truncate whitespace-nowrap">
+                                    {col.label?.trim()
+                                      ? col.label
+                                      : defaultColumnHeaderLabel(col.key) ?? col.key}
+                                  </span>
+                                )}
+                              </div>
+                            </div>
+                          </th>
+                        )
+                      })}
+                    </tr>
+                  </thead>
+                </table>
+              </div>
+            </div>
+          </div>,
+          document.body,
+        )
+        : null}
+
+      {/* ── Table ────────────────────────────────────────────────────────── */}
+      <div
+        ref={el => {
+          tableWrapRef.current = el
+          scrollRef.current = el
+        }}
+        onScroll={e => {
+          handleScroll()
+          setHeaderScrollLeft((e.currentTarget as HTMLDivElement).scrollLeft)
+        }}
+        className={cn(
+          "mx-4 lg:mx-6 overflow-x-auto border border-border",
+          hasFooter ? "rounded-t-lg" : "rounded-lg",
+        )}
+      >
+        <table
+          className="w-full text-sm border-separate border-spacing-0"
+          style={{
+            tableLayout: "fixed",
+            minWidth: totalWidth,
+            width: headerIsStuck ? floatingHeaderTableWidth : undefined,
+          }}
+        >
+          <colgroup>
+            {displayCols.map(col => (
+              <col key={col.key} style={{ width: colWidths[col.key] ?? col.width ?? 100 }} />
+            ))}
+          </colgroup>
+
+          {/* ── Table head ──────────────────────────────────────────────── */}
+          <thead
+            ref={tableHeadRef}
+            className={cn(
+              "bg-dt-header-bg",
+              headerIsStuck && "invisible",
+              !showColumnHeaders && "hidden"
+            )}
+          >
+            <tr>
+              {displayCols.map(col => {
+                const isPinned   = !!effectivePins[col.key]
+                const isLocked   = !!lockedPins[col.key]
+                const isFree     = !colPins[col.key]
+                const isResizable = !isLocked || (col.key !== "select")
+
+                const isEdgePinCol = col.key === lastLeftPinKey || col.key === firstRightPinKey
+
+                return (
+                  <th
+                    key={col.key}
+                    scope="col"
+                    aria-sort={col.sortable && col.sortKey ? ariaSortAttr(col.sortKey as string) : undefined}
+                    draggable={isFree}
+                    onDragStart={isFree ? e => handleDragStart(col.key, e) : undefined}
+                    onDragOver={isFree  ? e => handleDragOver(col.key, e)  : undefined}
+                    onDrop={isFree      ? () => handleDrop(col.key)        : undefined}
+                    onDragEnd={isFree   ? handleDragEnd                    : undefined}
+                    style={stickyStyle(col.key, false)}
+                    className={cn(
+                      "group/th relative h-9 px-3 text-start align-middle select-none",
+                      "text-xs font-medium text-muted-foreground tracking-wide",
+                      "bg-dt-header-bg border-b border-border",
+                      showGridlines && (!isEdgePinCol
+                        ? "border-e border-border last:border-e-0"
+                        : "last:border-e-0"),
+                      isPinned ? "z-40" : "z-30",
+                      isFree && "cursor-grab active:cursor-grabbing",
+                      dragOverKey === col.key && draggedKey.current !== col.key && "bg-accent/40",
+                      isEdgePinCol && stickyShadow(effectivePins[col.key])
+                    )}
+                  >
+                    <div className="flex items-center justify-between gap-1 min-w-0">
+                      <div className="flex items-center min-w-0 flex-1">
+                        {col.header ? (
+                          col.header()
+                        ) : col.key === "select" ? (
+                          selectable && (
+                            <span className="inline-flex items-center justify-center self-center">
+                              <span className="sr-only">{resolvedColumnLabel(col)}</span>
+                              <Checkbox
+                                checked={allSelected ? true : someSelected ? "indeterminate" : false}
+                                onCheckedChange={() => toggleAll(allRowIds)}
+                                aria-label="Select all rows"
+                              />
+                            </span>
+                          )
+                        ) : col.sortable && col.sortKey ? (
+                          <Tip label={`Sort by ${resolvedColumnLabel(col)}`} side="top">
+                            <button
+                              type="button"
+                              onClick={() => handleSortByKey(col.key)}
+                              className={cn(
+                                "inline-flex items-center hover:text-interactive-hover-foreground transition-colors whitespace-nowrap",
+                                sortKey === col.key && "text-foreground"
+                              )}
+                            >
+                              {col.label?.trim() ? col.label : resolvedColumnLabel(col)}
+                              {sortKey === col.key && <SortChevron dir={sortDir} />}
+                            </button>
+                          </Tip>
+                        ) : (
+                          <Tip label={resolvedColumnLabel(col)} side="top">
+                            <span className="whitespace-nowrap">
+                              {col.label?.trim() ? (
+                                col.label
+                              ) : defaultColumnHeaderLabel(col.key) ? (
+                                <span className="sr-only">{defaultColumnHeaderLabel(col.key)}</span>
+                              ) : (
+                                <span className="sr-only">{col.key}</span>
+                              )}
+                            </span>
+                          </Tip>
+                        )}
+                      </div>
+
+                      {/* Column context menu — not on checkbox or locked-right columns */}
+                      {col.key !== "select" && !lockedPins[col.key]?.includes("right") && col.key !== (columns.find(c => c.lockPin && c.defaultPin === "right")?.key) && (
+                        <DropdownMenu>
+                          <Tip label="Column options" side="top">
+                            <DropdownMenuTrigger asChild>
+                              <button
+                                type="button"
+                                aria-label={`${resolvedColumnLabel(col)} column options`}
+                                onClick={e => e.stopPropagation()}
+                                className={cn(
+                                  "opacity-0 group-hover/th:opacity-100 group-focus-within/th:opacity-100",
+                                  "inline-flex shrink-0 items-center justify-center size-7 rounded-md",
+                                  "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover-row",
+                                  "transition-opacity focus-visible:opacity-100",
+                                  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                                )}
+                              >
+                                <i className="fa-light fa-ellipsis-vertical text-xs" aria-hidden="true" />
+                              </button>
+                            </DropdownMenuTrigger>
+                          </Tip>
+                          <DropdownMenuContent
+                            align="start"
+                            onCloseAutoFocus={() => {
+                              const action = columnMenuPendingActionRef.current
+                              if (!action) return
+                              columnMenuPendingActionRef.current = null
+                              action()
+                            }}
+                          >
+
+                            {/* Column quick-search */}
+                            <div className="px-2 pt-2 pb-1">
+                              <div className="relative">
+                                <i className="fa-light fa-magnifying-glass absolute start-2 top-1/2 -translate-y-1/2 text-muted-foreground text-xs pointer-events-none" aria-hidden="true" />
+                                <Input
+                                  placeholder={`Search ${resolvedColumnLabel(col)}…`}
+                                  value={colMenuSearch[col.key] ?? ""}
+                                  onChange={e => setColMenuSearch(prev => ({ ...prev, [col.key]: e.target.value }))}
+                                  onKeyDown={e => e.stopPropagation()}
+                                  className="h-7 ps-6 text-xs"
+                                />
+                                {colMenuSearch[col.key] && (
+                                  <button
+                                    type="button"
+                                    aria-label="Clear search"
+                                    onClick={() => setColMenuSearch(prev => ({ ...prev, [col.key]: "" }))}
+                                    className="absolute end-1.5 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-interactive-hover-foreground transition-colors"
+                                  >
+                                    <i className="fa-light fa-xmark text-xs" aria-hidden="true" />
+                                  </button>
+                                )}
+                              </div>
+                            </div>
+                            <DropdownMenuSeparator />
+
+                            {/* Pin options */}
+                            {!isLocked && (
+                              <>
+                                <DropdownMenuItem
+                                  onClick={() => pinColumn(col.key, "left")}
+                                  disabled={colPins[col.key] === "left"}
+                                >
+                                  <i className="fa-light fa-arrow-left-to-line" aria-hidden="true" />
+                                  Pin Left
+                                </DropdownMenuItem>
+                                <DropdownMenuItem
+                                  onClick={() => pinColumn(col.key, "right")}
+                                  disabled={colPins[col.key] === "right"}
+                                >
+                                  <i className="fa-light fa-arrow-right-to-line" aria-hidden="true" />
+                                  Pin Right
+                                </DropdownMenuItem>
+                                {colPins[col.key] && (
+                                  <DropdownMenuItem onClick={() => unpinColumn(col.key)}>
+                                    <i className="fa-light fa-thumbtack-slash" aria-hidden="true" />
+                                    Unpin
+                                  </DropdownMenuItem>
+                                )}
+                                <DropdownMenuSeparator />
+                              </>
+                            )}
+
+                            {/* Sort options */}
+                            {col.sortable && col.sortKey && (
+                              <>
+                                <DropdownMenuItem onClick={() => setSortRules(prev => {
+                                  const filtered = prev.filter(r => r.fieldKey !== col.key)
+                                  return [{ id: `sort-${Date.now()}`, fieldKey: col.key, direction: "asc" as const }, ...filtered]
+                                })}>
+                                  <i className="fa-light fa-arrow-up-a-z text-xs shrink-0" aria-hidden="true" />
+                                  Sort Ascending
+                                </DropdownMenuItem>
+                                <DropdownMenuItem onClick={() => setSortRules(prev => {
+                                  const filtered = prev.filter(r => r.fieldKey !== col.key)
+                                  return [{ id: `sort-${Date.now()}`, fieldKey: col.key, direction: "desc" as const }, ...filtered]
+                                })}>
+                                  <i className="fa-light fa-arrow-down-a-z text-xs shrink-0" aria-hidden="true" />
+                                  Sort Descending
+                                </DropdownMenuItem>
+                                <DropdownMenuSeparator />
+                              </>
+                            )}
+
+                            {/* Text wrap toggle */}
+                            <DropdownMenuItem onClick={() => toggleWrap(col.key)}>
+                              <i className="fa-light fa-text-width" aria-hidden="true" />
+                              {colWrap[col.key] ? "Unwrap Text" : "Wrap Text"}
+                            </DropdownMenuItem>
+
+                            {/* Filter / Group by */}
+                            <DropdownMenuSeparator />
+                            {col.filter && (
+                              <DropdownMenuItem onClick={() => addFilter(col.key)}>
+                                <i className="fa-light fa-filter" aria-hidden="true" />
+                                Filter by this column
+                              </DropdownMenuItem>
+                            )}
+                            <DropdownMenuItem
+                              onClick={() => setGroupBy(groupBy === col.key ? null : col.key)}
+                            >
+                              <i className="fa-light fa-layer-group" aria-hidden="true" />
+                              {groupBy === col.key ? "Remove Grouping" : "Group by this Column"}
+                            </DropdownMenuItem>
+
+                            {/* Conditional rule shortcut */}
+                            <DropdownMenuSeparator />
+                            <DropdownMenuItem
+                              onSelect={() => {
+                                // Queue the deep-link into `onCloseAutoFocus` (above).
+                                // Opening the non-modal Properties Sheet synchronously
+                                // here races with the DropdownMenu close cycle and the
+                                // Sheet's outside-interaction listener — neither RAF
+                                // nor setTimeout(0) is enough. `onCloseAutoFocus` is
+                                // Radix's official "menu is fully closed and focus has
+                                // returned" hook, so it's the only safe moment.
+                                // Set the panel + open in the same batched action —
+                                // both setState calls land in one render so the drawer
+                                // opens already focused on the Conditional rules panel.
+                                columnMenuPendingActionRef.current = () => {
+                                  setSheetInitialPanel("conditional-rules")
+                                  setSheetOpen(true)
+                                }
+                              }}
+                            >
+                              <i className="fa-light fa-palette" aria-hidden="true" />
+                              Add Conditional Rule
+                            </DropdownMenuItem>
+
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      )}
+                    </div>
+
+                    {/* Resize handle */}
+                    {isResizable && col.key !== "select" && (
+                      <div
+                        role="separator"
+                        aria-label={`Resize ${resolvedColumnLabel(col)} column`}
+                        aria-orientation="vertical"
+                        onMouseDown={e => startResize(col.key, e)}
+                        className="absolute end-0 top-1 bottom-1 w-1.5 cursor-col-resize rounded-full hover:bg-interactive-hover-foreground/50 active:bg-muted-foreground/70 transition-colors"
+                      />
+                    )}
+                  </th>
+                )
+              })}
+            </tr>
+          </thead>
+
+          {/* ── Table body ───────────────────────────────────────────────── */}
+          <tbody>
+            {(pagedRows !== rows
+              ? [{ groupKey: null as string | null, groupLabel: null as string | null, rows: pagedRows }]
+              : groupedRows
+            ).map(({ groupKey, groupLabel, rows: groupRows }) => (
+              <React.Fragment key={groupKey ?? "__all__"}>
+                {groupLabel && (
+                  <tr>
+                    <td colSpan={displayCols.length} className="p-0 border-b border-border bg-dt-group-bg">
+                      <div
+                        className={cn(
+                          "sticky start-0 z-[25] px-4 py-1.5 text-xs font-semibold text-muted-foreground tracking-wide bg-dt-group-bg select-none",
+                          !isReflowViewport && "shadow-[4px_0_8px_-4px_var(--sticky-edge-fade)]",
+                        )}
+                        style={{ width: "var(--dt-scrollport-width, 100%)" }}
+                      >
+                        {groupLabel}
+                        <span className="ms-2 font-normal normal-case opacity-60 tracking-normal">
+                          {groupRows.length} record{groupRows.length !== 1 ? "s" : ""}
+                        </span>
+                      </div>
+                    </td>
+                  </tr>
+                )}
+                {groupRows.map((row, rowIndex) => {
+                  const rowId = getRowId(row, rowIndex, getRowIdProp)
+                  const isSelected = selected.has(rowId)
+                  const rowClickable = Boolean(onRowClick) || selectable
+                  function handleRowClick(e: React.MouseEvent<HTMLTableRowElement>) {
+                    if (!rowClickable) return
+                    const el = e.target as HTMLElement | null
+                    if (!el) return
+                    if (el.closest("button, a, input, textarea, select, label, [role='checkbox']")) return
+                    if (onRowClick) {
+                      onRowClick(row)
+                      return
+                    }
+                    if (selectable) {
+                      toggleRow(rowId)
+                    }
+                  }
+                  return (
+                    <tr
+                      key={String(rowId)}
+                      data-state={isSelected ? "selected" : undefined}
+                      onMouseEnter={() => setHoveredRow(rowId)}
+                      onMouseLeave={() => setHoveredRow(null)}
+                      onClick={rowClickable ? handleRowClick : undefined}
+                      data-new={Boolean((row as Record<string, unknown>).isNew) || undefined}
+                      className={cn(
+                        "group/row transition-colors",
+                        "hover:bg-dt-row-hover",
+                        isSelected && "bg-dt-row-selected text-dt-row-selected-fg",
+                        rowClickable && "cursor-pointer",
+                        Boolean((row as Record<string, unknown>).isNew) && "bg-dt-new-row-bg border-s-2 border-s-dt-new-row-border"
+                      )}
+                    >
+                      {displayCols.map(col => {
+                        const isPinned   = !!effectivePins[col.key]
+                        const wrap       = colWrap[col.key]
+                        const isEdgePin  = col.key === lastLeftPinKey || col.key === firstRightPinKey
+                        const rowPy      = rowHeight === "compact" ? "py-1" : rowHeight === "comfortable" ? "py-4" : "py-2.5"
+                        const cs         = cellStyle(col.key)
+
+                        const tdBase = cn(
+                          `px-3 ${rowPy} align-middle`,
+                          showGridlines && !isEdgePin && "border-e border-border last:border-e-0",
+                          "border-b border-border group-last/row:border-b-0",
+                          isPinned && [
+                            "z-20 pinned-cell",
+                            "bg-dt-row-bg",
+                            "group-data-[state=selected]/row:bg-dt-row-selected",
+                            "group-hover/row:bg-dt-row-hover",
+                            isEdgePin && stickyShadow(effectivePins[col.key]),
+                          ]
+                        )
+
+                        const conditionalBg = getConditionalCellBackground(
+                          row,
+                          col.key,
+                          conditionalRules,
+                          columns,
+                        )
+
+                        const tdStyle = conditionalBg
+                          ? { ...cs, background: conditionalBg }
+                          : cs
+
+                        // Special synthetic columns
+                        if (col.key === "select") {
+                          const selectionLabel = getRowSelectionLabel?.(row, rowIndex)
+                          const ariaLabel = selectionLabel
+                            ? `Select row, ${selectionLabel}`
+                            : `Select row ${rowIndex + 1}`
+                          return (
+                            <td key="select" className={cn(tdBase, "text-center")} style={tdStyle}>
+                              {selectable && (
+                                // inline-flex: inline elements inside <td> are never
+                                // stretched by table-cell height in Chrome/Safari/Firefox.
+                                // Block-level flex/grid always inherits full cell height at zoom.
+                                <span
+                                  className={cn(
+                                    "inline-flex items-center justify-center transition-opacity",
+                                    anySelected
+                                      ? "opacity-100"
+                                      : "opacity-0 group-hover/row:opacity-100 group-focus-within/row:opacity-100",
+                                  )}
+                                  onClick={e => e.stopPropagation()}
+                                >
+                                  <Checkbox
+                                    checked={isSelected}
+                                    onCheckedChange={() => toggleRow(rowId)}
+                                    aria-label={ariaLabel}
+                                    onClick={e => e.stopPropagation()}
+                                  />
+                                </span>
+                              )}
+                            </td>
+                          )
+                        }
+
+                        // Custom cell renderer
+                        if (col.cell) {
+                          return (
+                            <td
+                              key={col.key}
+                              className={cn(
+                                tdBase,
+                                // When wrap is on, override truncate/overflow on any descendant
+                                wrap && "[&_.truncate]:!whitespace-normal [&_.truncate]:!overflow-visible [&_.truncate]:!text-clip",
+                              )}
+                              style={tdStyle}
+                            >
+                              {col.cell(row, {
+                                rowIndex,
+                                selected: isSelected,
+                                onSelect: checked => checked ? setSelected(prev => new Set([...prev, rowId])) : toggleRow(rowId),
+                              })}
+                            </td>
+                          )
+                        }
+
+                        // Default: render string value with optional truncation
+                        const rawVal = String(row[col.key] ?? "")
+                        return (
+                          <td key={col.key} className={cn(tdBase, "text-sm text-foreground/80")} style={tdStyle}>
+                            <span className={wrap ? "whitespace-normal" : "block truncate"} title={!wrap ? rawVal : undefined}>
+                              {rawVal}
+                            </span>
+                          </td>
+                        )
+                      })}
+                    </tr>
+                  )
+                })}
+              </React.Fragment>
+            ))}
+
+            {/* Empty state */}
+            {rows.length === 0 && (
+              <tr>
+                <td colSpan={displayCols.length} className="h-24 px-3 text-center text-sm text-muted-foreground">
+                  {emptyState ?? "No results match your filters."}
+                </td>
+              </tr>
+            )}
+
+            {/* Add new row stub */}
+            {addRowLabel !== false && (
+              <tr
+                role="button"
+                tabIndex={0}
+                onKeyDown={e => { if (e.key === "Enter" || e.key === " ") e.preventDefault() }}
+                className="cursor-pointer hover:bg-dt-row-hover transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+                aria-label={`Add new ${addRowLabel}`}
+              >
+                <td colSpan={displayCols.length} className="px-3 py-2.5 align-middle">
+                  <span className="flex items-center gap-1.5 text-sm text-muted-foreground">
+                    <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+                    {addRowLabel}
+                  </span>
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {/* ── Bulk selection bar — dark strip in light app; light strip in dark app.
+            Normal zoom: max ~28rem, centered. Reflow: full table width. Inner
+            `dark` in light app → shadcn `dark:` buttons; in dark app → explicit
+            light-surface button overrides.
+      */}
+      {anySelected && (
+        <div
+          role="status"
+          aria-live="polite"
+          aria-label={`${selected.size} row${selected.size !== 1 ? "s" : ""} selected`}
+          data-exxat-bulk-bar=""
+          style={bulkBarFixedStyle}
+          className={cn(
+            "flex min-w-0 max-w-full items-stretch overflow-hidden",
+            isAppDark
+              ? "rounded-lg border border-zinc-300/80 bg-zinc-100 text-zinc-900 shadow-lg"
+              : "rounded-lg border border-zinc-800 bg-zinc-900 text-zinc-100 shadow-lg",
+            "animate-in fade-in-0 duration-150",
+            "w-auto max-w-none",
+          )}
+        >
+          <div
+            className={cn(
+              "flex shrink-0 items-center gap-2 border-e py-2.5 ps-3 pe-2",
+              isAppDark ? "border-zinc-300/50" : "border-zinc-600/50",
+            )}
+            aria-hidden="true"
+          >
+            <span
+              className={cn(
+                "inline-flex size-8 items-center justify-center rounded-md",
+                isAppDark ? "text-zinc-500" : "text-zinc-400",
+              )}
+              aria-hidden="true"
+            >
+              <i className="fa-light fa-clipboard-list text-[1.1rem] leading-none" />
+            </span>
+            <span
+              className={cn(
+                "min-w-6 rounded-md px-1.5 py-0.5 text-center text-xs font-semibold leading-none tabular-nums",
+                isAppDark ? "bg-zinc-200/90 text-zinc-900" : "bg-zinc-800 text-zinc-100",
+              )}
+            >
+              {selected.size}
+            </span>
+          </div>
+
+          <div
+            className={cn(
+              "flex min-w-0 min-h-0 flex-1 items-stretch",
+              !isAppDark && "dark",
+              isAppDark && BULK_BAR_ON_LIGHT_STRIP,
+            )}
+          >
+            <div
+              className={cn(
+                "min-w-0 flex-1 self-center",
+                "overflow-x-auto overscroll-x-contain [scrollbar-width:thin] [touch-action:pan-x]",
+              )}
+            >
+              <div className="flex w-max min-w-0 max-w-full flex-nowrap items-center gap-2 py-2.5 ps-2 pe-2">
+                {bulkActionsSlot ? (
+                  bulkActionsSlot(selected, rows)
+                ) : (
+                  <>
+                    <Button size="sm" variant="outline" className="shrink-0">
+                      <i className="fa-light fa-arrow-down-to-line" aria-hidden="true" /> Export
+                    </Button>
+                    <Button size="sm" variant="destructive" className="shrink-0">
+                      <i className="fa-light fa-trash" aria-hidden="true" /> Delete
+                    </Button>
+                  </>
+                )}
+              </div>
+            </div>
+
+            <div
+              className={cn(
+                "flex shrink-0 items-center border-e py-2.5 ps-2 pe-2.5",
+                isAppDark ? "border-zinc-300/50" : "border-zinc-600/50",
+              )}
+            >
+              <Tip label="Clear selection" side="top">
+                <Button
+                  type="button"
+                  size="icon-sm"
+                  variant="ghost"
+                  aria-label="Clear selection"
+                  onClick={() => setSelected(new Set())}
+                  className="shrink-0"
+                >
+                  <i className="fa-light fa-xmark" aria-hidden="true" />
+                </Button>
+              </Tip>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function DataTableWithInternalState<TData extends Record<string, unknown>>(props: DataTableExtendedProps<TData>) {
+  const state = useTableState(props.data, props.columns, props.defaultSort, props.paginationOverride)
+  return <DataTableInner {...props} state={state} />
+}
+
+export function DataTable<TData extends Record<string, unknown>>(props: DataTableExtendedProps<TData>) {
+  if (props.state) {
+    return <DataTableInner {...props} state={props.state} />
+  }
+  return <DataTableWithInternalState {...props} />
+}