"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: `verticalResizeSeparatorAria()` (role="separator" + valuemin/max/now)
 */

import * as React from "react"
import { createPortal } from "react-dom"
import { cn } from "../../lib/utils"
import { EDGE_RESIZE_HANDLE_CLASS, verticalResizeSeparatorAria } from "../../lib/edge-resize-handle"
import {
  bindVerticalScrollListeners,
  getStickyTableHeaderOffset,
} from "../../lib/page-scroll-port"
import {
  DATA_TABLE_GRID_INSET_CLASS,
  DATA_TABLE_TOOLBAR_INSET_CLASS,
  warnIfStackedTableEdgeInset,
} from "../../lib/table-edge-inset"
import { runWithPreservedPageScroll } from "../../lib/preserve-page-scroll"
import { rafThrottle } from "../../lib/raf-throttle"
import { Button } from "../ui/button"
import { railTriggerProps } from "../ui/floating-sheet-panel"
import { ScrollRegion } from "../ui/scroll-region"

/**
 * DataTable cells use `max-w-0` + `overflow-hidden` for truncation. Outset
 * focus rings paint outside the control and get clipped to corner stubs.
 * Force inset rings on common focusable descendants (hub cell renderers,
 * links, icon buttons, checkboxes, Tip `tabIndex={0}` glyphs).
 *
 * `p-1 -m-1` covers what `ring-inset` cannot: a plain `outline`, which several
 * focusable descendants use instead of a ring and which has no inset form. The
 * padding grows the clip box while the negative margin keeps the content box the
 * same size and in the same place, so truncation is unchanged and a link or Tip
 * glyph flush with the cell's leading edge keeps its whole indicator.
 */
const CELL_CLIP_FOCUS_INSET_CLASS =
  "p-1 -m-1 [&_a:focus-visible]:ring-inset [&_button:focus-visible]:ring-inset [&_[role=checkbox]:focus-visible]:ring-inset [&_[tabindex]:focus-visible]:ring-inset"
import {
  FilterBar,
  FilterBarAddButton,
  FilterBarClearButton,
} from "../ui/filter-bar"
import { FilterButton } from "../ui/filter-button"
import { Input } from "../ui/input"
import { Kbd, KbdGroup } from "../ui/kbd"
import {
  ResponsiveActionRow,
  useResponsiveActionWidth,
  useWrapCrowding,
} from "../ui/responsive-action-row"
import type { ResponsiveAction } from "../ui/responsive-action-row"
import { BulkSelectionBar } from "./bulk-selection-bar"
import { Tip } from "../ui/tip"
import { useDismissBeforeOverlay } from "../../hooks/use-dismiss-before-overlay"
import { useModKeyLabel, useAltKeyLabel } from "../../hooks/use-mod-key-label"
import { useIsMobile } from "../../hooks/use-mobile"
import { useSidebarReflowZoom } from "../../hooks/use-sidebar-reflow-zoom"
import { isEditableTarget } from "../../lib/editable-target"
import {
  augmentColumnsWithCompanionFilters,
  filterableColumns,
  resolveColumnFilter,
} from "../../lib/column-filter"
import type { FilterFieldRuntimeContext } from "../../lib/column-filter-context"
import { filterPresetForCellKind } from "../../lib/column-cell-kind"
import { initialsFromDisplayName } from "../../lib/column-filter-range-policy"
import { AvatarInitials } from "../ui/avatar"
import { Badge } from "../ui/badge"
import { StatusBadge } from "../ui/status-badge"
import {
  PeopleAvatarRailCell,
  PillCell,
  type PersonStub,
} from "../data-views/table-cells"
import { groupRowAccessibilityLabel, GROUP_ROW_EMPTY_KEY } from "../../lib/group-row-key"
import { Checkbox } from "../ui/checkbox"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  Shortcut,
} from "../ui/dropdown-menu"
import {
  Popover,
  PopoverAnchor,
  PopoverContent,
  PopoverTrigger,
} from "../ui/popover"
import { TableSearchRecentsPopover } from "./table-search-recents-popover"
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "../ui/tooltip"
import { OPERATOR_LABELS, FILTER_TEXT_MASK_FORMAT_HINT } from "../../lib/table-properties-types"
import type { ActiveFilter } from "../../lib/table-properties-types"
import { getConditionalCellBackground, ruleHasActiveValues } from "../../lib/conditional-rule-match"
import { formatYmdForDisplay } from "../../lib/date-filter"
import { useIncrementalRender } from "../../lib/lazy-loading"
import { useIsClient } from "../../hooks/use-is-client"
import { FilterDateCalendar } from "./filter-date-calendar"
import { FilterDateRangeControl } from "./filter-date-range-control"
import { FilterPersonOptionList } from "./filter-person-option-list"
import { FilterRangeControl } from "./filter-range-control"
import { FilterTextValueInput } from "./filter-text-value-input"
import type {
  DataTableProps,
  ColumnDef,
  ColumnCellKind,
  SortDir,
  StatusBadgeTone,
} 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
  }
}

/**
 * Side padding for a column whose content is a control rather than text.
 *
 * `px-3` is right for text, which has nothing to lose by starting 12px in. It is
 * wrong for a fixed-size control: a 48px actions column left 24px of cell for a
 * 32px icon button, and since cells clip (`max-w-0` + `overflow-hidden`, so long
 * text truncates) the button lost 4px off each side along with the near edges of
 * its focus ring. Keyboard focus then read as a ring sliced flat top and bottom.
 *
 * 4px keeps the control's own box intact in a 48px column and still reads as a
 * gutter, because the control is centred and narrower than the cell.
 */
const CONTROL_COLUMN_PADDING = "px-1"

/**
 * The group divider's own box. Shared by the row in the table and by the
 * clone that pins under the column header, because the clone only reads as
 * the same bar if it is measured and painted as one — the pin maths uses the
 * real row's height for the hand-off.
 */
const GROUP_BAR_CLASS =
  "flex w-full items-center gap-2 px-4 py-1 text-xs font-semibold leading-none text-muted-foreground tracking-wide bg-dt-group-bg select-none"

/**
 * With a checkbox leading the bar, the bar's own start padding is dropped: the
 * checkbox is centred inside a slot the width of the select column instead, so
 * it lands on the same axis as the row checkboxes beneath it rather than 4px to
 * their right (the column is 40px with a 16px control, so its centre is 20px;
 * `px-4` put the bar's box at 16px).
 */
const GROUP_BAR_WITH_SELECT_CLASS = "ps-0 gap-3"

const GROUP_DIVIDER_BADGE_SIZE = "sm" as const

/** Slightly shorter than table-row chips so the band lands ~30px tall. */
const GROUP_CHIP_CLASS = "!h-5 !min-h-0 gap-1 !px-1.5 !py-0 !text-xs leading-none"

function isBadgeGroupKind(
  kind: ColumnCellKind | undefined,
): kind is "status" | "pill" {
  return kind === "status" || kind === "pill"
}

/** Status or pill chip for a group heading. */
function groupBadgeNode(
  label: string,
  kind: "status" | "pill",
  option?: { tone?: StatusBadgeTone; icon?: string },
): React.ReactNode {
  if (kind === "status") {
    return (
      <StatusBadge
        label={label}
        tone={option?.tone}
        icon={option?.icon}
        size={GROUP_DIVIDER_BADGE_SIZE}
        className={GROUP_CHIP_CLASS}
      />
    )
  }
  return (
    <PillCell
      label={label}
      icon={option?.icon ?? filterPresetForCellKind("pill").icon}
      iconClassName="text-[0.6875rem]"
      className={GROUP_CHIP_CLASS}
    />
  )
}

/** Group band fill — the same token the status badge uses for its background. */
function groupBarTint(tone: StatusBadgeTone): string {
  return `var(--status-badge-${tone}-fill)`
}

/**

 * `select` is the group's own checkbox, and the slot it sits in is the select
 * column's box. `gap-3` after it matches the data columns' `px-3`, so the group
 * label starts on the same axis as the first column's text.
 *
 * The pinned clone passes a non-interactive mirror, so the bar does not change
 * shape as it pins.
 */
function groupBarContent(
  groupLabel: React.ReactNode,
  count: number,
  select?: React.ReactNode,
  selectSlotWidth?: number,
): React.ReactNode {
  return (
    <>
      {select ? (
        <span
          className="flex shrink-0 items-center justify-center"
          style={{ width: selectSlotWidth }}
        >
          {select}
        </span>
      ) : null}
      <span className="flex min-w-0 flex-1 items-center gap-1.5">{groupLabel}</span>
      <Badge
        variant="secondary"
        className={cn(GROUP_CHIP_CLASS, "ms-auto shrink-0 min-w-5 justify-center tabular-nums font-semibold")}
        aria-label={`${count} record${count !== 1 ? "s" : ""}`}
      >
        {count}
      </Badge>
    </>
  )
}

/**
 * What `useTableState` groups rows under when the grouped field is empty.
 * The divider says `None` instead: a lone dash is not a word, and the band is
 * a heading (`exxat-copy-discipline`).
 */
const GROUP_EMPTY_KEY = GROUP_ROW_EMPTY_KEY

/** Cell kinds whose own icon would say less than the group's name already does. */
const GROUP_KIND_PLAIN: ReadonlySet<ColumnCellKind> = new Set<ColumnCellKind>([
  "text",
  "tags",
  "attachment",
  "external-link",
])

/**
 * A group heading in the grouped column's own vocabulary, for columns that do
 * not ship `filter.options` to render from.
 *
 * A person column groups on the display name, so the divider can rebuild the
 * identity the cells show — avatar plus name, no email, because the band is one
 * line and a heading, not a record (`exxat-person-identity-display`). Every
 * other kind leads with the icon its filter menu uses, so "Type", "Level", and
 * "Due" dividers are told apart at a glance by the same mark the reader already
 * associates with that column.
 */
function groupKindNode(
  label: string,
  kind: ColumnCellKind | undefined,
): React.ReactNode {
  if (!kind) return label
  if (kind === "person") {
    return (
      <span className="flex min-w-0 items-center gap-2">
        <AvatarInitials
          initials={initialsFromDisplayName(label)}
          className="size-5 text-[0.625rem]"
        />
        <span className="truncate text-foreground">{label}</span>
      </span>
    )
  }
  if (GROUP_KIND_PLAIN.has(kind)) return label
  return (
    <span className="flex min-w-0 items-center gap-1.5">
      <i
        className={cn("fa-light text-[0.7rem] opacity-70", filterPresetForCellKind(kind).icon)}
        aria-hidden="true"
      />
      <span className="truncate">{label}</span>
    </span>
  )
}

/** Columns the table lays out around a control, not around text. */
function isControlColumn(key: string): boolean {
  return key === "select" || key === "actions"
}

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>[]
  fieldContext?: FilterFieldRuntimeContext
  /**
   * Whether this pill's editor is the open one. Controlled from the toolbar's
   * single `openFilterId` rather than per-pill state: two editors open at once
   * is never a state the user asked for, and it happened whenever an overlay
   * that Radix would not dismiss (any modal menu) sat between them.
   */
  open?: boolean
  onOpenChange?: (open: boolean) => void
  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,
  fieldContext,
  open = false,
  onOpenChange,
  onUpdate,
  onRemove,
  renderOptionValue,
}: FilterPillProps<TData>) {
  const [optSearch, setOptSearch] = React.useState("")
  const deferredOptSearch = React.useDeferredValue(optSearch)
  const justAutoOpenedRef = React.useRef(false)
  const [contentEl, setContentEl] = React.useState<HTMLElement | null>(null)
  const [triggerEl, setTriggerEl] = React.useState<HTMLElement | null>(null)
  const setOpen = React.useCallback(
    (next: boolean) => onOpenChange?.(next),
    [onOpenChange],
  )
  /** Roving tabindex over the option list (same pattern as `ViewSegmentedControl`). */
  const optionRefs = React.useRef<(HTMLButtonElement | null)[]>([])
  const [activeOptionIndex, setActiveOptionIndex] = React.useState(0)

  React.useEffect(() => {
    setActiveOptionIndex(0)
  }, [optSearch])

  const moveActiveOption = React.useCallback((index: number, len: number) => {
    if (len === 0) return
    const i = ((index % len) + len) % len
    setActiveOptionIndex(i)
    requestAnimationFrame(() => {
      optionRefs.current[i]?.focus()
    })
  }, [])

  const onOptionKeyDown = React.useCallback(
    (e: React.KeyboardEvent<HTMLButtonElement>, index: number, len: number) => {
      if (e.key === "ArrowDown") {
        e.preventDefault()
        moveActiveOption(index + 1, len)
      } else if (e.key === "ArrowUp") {
        e.preventDefault()
        moveActiveOption(index - 1, len)
      } else if (e.key === "Home") {
        e.preventDefault()
        moveActiveOption(0, len)
      } else if (e.key === "End") {
        e.preventDefault()
        moveActiveOption(len - 1, len)
      }
    },
    [moveActiveOption],
  )

  /**
   * A pill added from the **Add filter** menu mounts already open, and the tail
   * of the interaction that chose it — the menu closing and handing focus back —
   * reads as an interaction outside the editor that just appeared. Ignore
   * dismissals for a beat so the new editor survives its own arrival.
   */
  React.useEffect(() => {
    if (!open) return
    justAutoOpenedRef.current = true
    const reset = setTimeout(() => { justAutoOpenedRef.current = false }, 400)
    return () => clearTimeout(reset)
  // Mount only: a user re-opening this pill later is not an arrival.
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [])

  // Radix will not dismiss this editor when a modal overlay opens above it; see
  // `useDismissBeforeOverlay`.
  useDismissBeforeOverlay(open, contentEl, triggerEl, () => {
    if (justAutoOpenedRef.current) return
    setOpen(false)
  })

  const col = React.useMemo(() => {
    const augmented = augmentColumnsWithCompanionFilters(columns)
    return augmented.find(c => c.key === filter.fieldKey)
  }, [columns, filter.fieldKey])
  const filterDef = col ? resolveColumnFilter(col) : null

  if (!col || !filterDef) return null

  const isPersonSelect =
    filterDef.type === "select" && filterDef.selectVariant === "person"
  const personOptions = fieldContext?.personOptions ?? []
  const options = isPersonSelect
    ? personOptions.map(p => ({ value: p.value, label: p.label }))
    : (filterDef.options ?? [])
  const showSearch = !isPersonSelect && options.length > 8
  const needle = deferredOptSearch.toLowerCase()
  const filteredOpts = deferredOptSearch
    ? options.filter(o => o.label.toLowerCase().includes(needle))
    : options
  const selectedValueSet = new Set(filter.values)

  const operators = filterDef.operators ?? (
    filterDef.type === "select" || filterDef.type === "date" || filterDef.type === "date-range"
      ? (["is", "is_not"] as const)
      : filterDef.type === "range"
        ? (["is"] as const)
        : (["contains", "not_contains"] as const)
  )

  const rangeMin = fieldContext?.rangeMin ?? filterDef.rangeMin ?? 0
  const rangeMax = fieldContext?.rangeMax ?? filterDef.rangeMax ?? 100
  const rangeStep = fieldContext?.rangeStep ?? filterDef.rangeStep ?? 1

  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) : "…"
    }
    if (filterDef.type === "date-range") {
      const start = filter.values[0]
      const end = filter.values[1]
      if (start && end) {
        return `${formatYmdForDisplay(start)} to ${formatYmdForDisplay(end)}`
      }
      if (start) return formatYmdForDisplay(start)
      return "…"
    }
    if (filterDef.type === "range") {
      if (filter.values.length >= 2) {
        const unit = filterDef.rangeUnit ?? ""
        return `${filter.values[0]} to ${filter.values[1]}${unit}`
      }
      return "…"
    }
    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])
      : filterDef.type === "date-range"
        ? Boolean(filter.values[0] || filter.values[1])
        : filterDef.type === "range"
          ? filter.values.length >= 2
          : filter.values.length > 0
  const hasSelection = isActive
  const iconWeight = hasSelection ? "fa-solid" : "fa-light"
  const iconClass = filterDef.icon
    ? `${iconWeight} ${filterDef.icon}`
    : `${iconWeight} fa-filter`

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverAnchor asChild>
      <div
        className={cn(
          // The height lives here, not on the inner button: the wrapper owns the
          // border, so sizing the child leaves the chip 2px taller than the
          // Add filter button sitting next to it.
          "inline-flex h-8 cursor-pointer items-stretch rounded border text-xs transition-colors",
          isActive ? "border-brand/45 bg-brand/10" : "border-input bg-background"
        )}
      >
        <PopoverTrigger asChild>
          <button
            ref={setTriggerEl}
            type="button"
            className={cn(
              "inline-flex cursor-pointer items-center gap-1 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-icon-button-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 w-8 cursor-pointer items-center justify-center rounded-e transition-colors",
            "text-muted-foreground hover:text-destructive-ink",
            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
        ref={setContentEl}
        className={cn(
          "p-0",
          filterDef.type === "date" || filterDef.type === "date-range"
            ? "w-auto max-w-[min(calc(100vw-2rem),22rem)]"
            : isPersonSelect
              ? "flex max-h-[min(70vh,20rem)] w-80 flex-col overflow-hidden"
              : filterDef.type === "range"
                ? "w-72"
                : "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-ink 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={`Choose ${col.label} date`}
              valueYmd={filter.values[0]}
              onChangeYmd={(ymd) =>
                onUpdate(filter.id, { values: ymd ? [ymd] : [] })
              }
            />
          </div>
        )}

        {filterDef.type === "date-range" && (
          <div className="p-2">
            <FilterDateRangeControl
              label={`Choose ${col.label} date range`}
              values={filter.values}
              onChangeYmd={(start, end) => {
                const next = [start ?? "", end ?? ""]
                onUpdate(filter.id, { values: next.some(Boolean) ? next : [] })
              }}
            />
          </div>
        )}

        {filterDef.type === "select" && isPersonSelect ? (
          <FilterPersonOptionList
            options={personOptions}
            selectedValues={filter.values}
            onToggleValue={toggleValue}
            className="max-h-64"
          />
        ) : 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="icon-button-chrome absolute end-1 top-1/2 -translate-y-1/2 inline-flex size-8 items-center justify-center rounded transition-colors 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.length > 0 ? (
              <div
                role="listbox"
                aria-multiselectable={true}
                aria-label={`${col.label} options`}
              >
                {filteredOpts.map((opt, optIndex) => {
                  const checked = selectedValueSet.has(opt.value)
                  const activeIndex =
                    activeOptionIndex < filteredOpts.length ? activeOptionIndex : 0
                  return (
                    <button
                      key={opt.value}
                      ref={el => {
                        optionRefs.current[optIndex] = el
                      }}
                      type="button"
                      role="option"
                      aria-selected={checked}
                      tabIndex={optIndex === activeIndex ? 0 : -1}
                      onKeyDown={e => onOptionKeyDown(e, optIndex, filteredOpts.length)}
                      onClick={() => 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 text-start"
                    >
                      <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-2xs text-current" aria-hidden="true" />}
                      </span>
                      {renderOptionValue
                        ? renderOptionValue(filter.fieldKey, opt.value)
                        : "node" in opt && opt.node != null
                          ? (opt.node as React.ReactNode)
                          : <span className="text-foreground">{opt.label}</span>
                      }
                    </button>
                  )
                })}
              </div>
            ) : (
              <p className="px-3 py-2 text-xs text-muted-foreground">No options found</p>
            )}
          </div>
        ) : null}

        {filterDef.type === "text" && (
          <div className="space-y-1.5 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
            />
            {filterDef.textMask ? (
              <p className="px-0.5 text-xs text-muted-foreground">
                Format: {FILTER_TEXT_MASK_FORMAT_HINT[filterDef.textMask]}
              </p>
            ) : null}
          </div>
        )}

        {filterDef.type === "range" && (
          <div className="p-2">
            <FilterRangeControl
              min={rangeMin}
              max={rangeMax}
              step={rangeStep}
              unit={filterDef.rangeUnit}
              values={
                filter.values.length >= 2
                  ? filter.values
                  : [String(rangeMin), String(rangeMax)]
              }
              onValuesChange={(lo, hi) =>
                onUpdate(filter.id, { values: [String(lo), String(hi)] })
              }
            />
          </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)]",
  )
}

/** Trailing / pin-seam vertical rules for header and body cells. */
function cellColumnEndBorder(
  colKey: string,
  colIndex: number,
  colCount: number,
  pin: "left" | "right" | undefined,
  showGridlines: boolean,
  lastLeftPinKey: string | undefined,
  firstRightPinKey: string | undefined,
  lastRightPinKey: string | undefined,
): string {
  const isLastCol = colIndex === colCount - 1

  // Pin block ↔ scrollport (always visible — gradient shadow alone is too faint)
  const pinSeam =
    (colKey === firstRightPinKey && pin === "right" ? "border-s border-border" : "") ||
    (colKey === lastLeftPinKey && pin === "left" ? "border-e border-border" : "")

  // Between columns: edge-pin cells used to skip border-e, which dropped dividers
  // inside a multi-column pin block (e.g. Reviewers | Actions) and beside scrollport.
  const trailing =
    showGridlines && (colKey === lastRightPinKey || !isLastCol)
      ? "border-e border-border"
      : colKey === lastRightPinKey
        ? "border-e border-border"
        : ""

  return cn(pinSeam, trailing)
}

/** Cumulative pin-block boundaries measured from the scrollport edge (px). */
function pinBlockSeamOffsets<TData>(
  displayCols: ColumnDef<TData>[],
  effectivePins: Record<string, "left" | "right">,
  colWidths: Record<string, number>,
  side: "left" | "right",
): number[] {
  const seams: number[] = []
  let cumulative = 0
  if (side === "right") {
    for (let i = displayCols.length - 1; i >= 0; i -= 1) {
      const col = displayCols[i]
      if (effectivePins[col.key] !== "right") break
      cumulative += colWidths[col.key] ?? col.width ?? 100
      seams.push(cumulative)
    }
    return seams
  }
  for (const col of displayCols) {
    if (effectivePins[col.key] !== "left") break
    cumulative += colWidths[col.key] ?? col.width ?? 100
    seams.push(cumulative)
  }
  return seams
}

/** Pin seams on full-bleed group bars — colspan rows have no per-column cells. */
function GroupBarPinSeams({
  rightSeams,
  leftSeams,
}: {
  rightSeams: number[]
  leftSeams: number[]
}) {
  if (rightSeams.length === 0 && leftSeams.length === 0) return null
  return (
    <>
      {rightSeams.map(offset => (
        <div
          key={`pin-seam-r-${offset}`}
          aria-hidden="true"
          className="pointer-events-none absolute inset-y-0 z-[1] border-s border-border"
          style={{ right: offset }}
        />
      ))}
      {leftSeams.map(offset => (
        <div
          key={`pin-seam-l-${offset}`}
          aria-hidden="true"
          className="pointer-events-none absolute inset-y-0 z-[1] border-e border-border"
          style={{ left: offset }}
        />
      ))}
    </>
  )
}

/**
 * A mouse click leaves DOM focus parked on the element (a column's ⋯ trigger)
 * with no visible ring, and Radix restores that focus when the menu closes.
 * The sticky header only needs to yield to focus that is actually *drawn*, so
 * plain `:focus` would let one mouse click suppress the sticky clone for the
 * rest of the session.
 */
function hasVisibleFocus(el: Element | null | undefined): boolean {
  if (!el) return false
  try {
    return el.matches(":focus-visible")
  } catch {
    // Engines without `:focus-visible` (older jsdom) keep the permissive path.
    return true
  }
}

// ─────────────────────────────────────────────────────────────────────────────
// DataTableToolbar — search, filter bar, properties slot (shared by table + board)
// ─────────────────────────────────────────────────────────────────────────────

function TableSearchFieldAnchor({
  searchRef,
  search,
  setSearch,
  setSearchOpen,
  setSearchRecentsOpen,
  recentItems,
  onSearchRecentRecord,
  searchAriaLabel,
}: {
  searchRef: React.RefObject<HTMLInputElement | null>
  search: string
  setSearch: (value: string) => void
  setSearchOpen: (open: boolean) => void
  setSearchRecentsOpen: (open: boolean) => void
  recentItems: string[]
  onSearchRecentRecord?: (query: string) => void
  searchAriaLabel: string
}) {
  return (
    <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)}
        onFocus={() => {
          if (!search.trim() && recentItems.length > 0) setSearchRecentsOpen(true)
        }}
        onBlur={() => {
          const trimmed = search.trim()
          if (trimmed) onSearchRecentRecord?.(trimmed)
          window.setTimeout(() => setSearchRecentsOpen(false), 120)
          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="icon-button-chrome absolute end-1.5 top-1/2 -translate-y-1/2 inline-flex cursor-pointer size-8 items-center justify-center rounded transition-colors 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>
  )
}

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,
  toolbarActions,
  searchAriaLabel = "Search table",
  searchRecentQueries,
  onSearchRecentSelect,
  onSearchRecentClear,
  onSearchRecentRecord,
  edgeInset = true,
}: {
  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
  /**
   * Record commands for the toolbar, rendered after Properties behind a
   * separator. See `HubTableProps.toolbarActions`.
   */
  toolbarActions?: ResponsiveAction[]
  /** Passed to the search input `aria-label` (e.g. "Search placements") */
  searchAriaLabel?: string
  /** Recent toolbar queries — shown on focus when the field is empty. */
  searchRecentQueries?: string[]
  onSearchRecentSelect?: (query: string) => void
  onSearchRecentClear?: () => void
  /** Called when the user leaves the field with a non-empty query. */
  onSearchRecentRecord?: (query: string) => void
  /** When false, toolbar omits horizontal inset (parent owns page padding). */
  edgeInset?: boolean
}) {
  const {
    search, setSearch, searchOpen, setSearchOpen, searchRef,
    activeFilters, setActiveFilters, openFilterId, setOpenFilterId,
    filterBarVisible, setFilterBarVisible,
    addFilter, updateFilter, removeFilter,
    openFilterPanelInDrawer,
    filterFieldContext,
  } = state

  const isMobile = useIsMobile()
  const reflowZoom = useSidebarReflowZoom()
  /** Mobile or browser zoom ≥ ~200% — hide inline filter chips; filter icon opens Properties. */
  const compactFilterToolbar = isMobile || reflowZoom

  const hasToolbarActions = Boolean(toolbarActions?.length)
  /**
   * Measured on the toolbar row rather than the action group: the group is
   * `shrink-0`, so its own box never narrows no matter how little room the row
   * has left after the chip rail. The row is what actually runs out of space.
   */
  const {
    ref: toolbarRowRef,
    width: toolbarRowWidth,
    compact: actionsCompact,
    overflowOnly: actionsOverflowOnly,
  } = useResponsiveActionWidth<HTMLDivElement>()
  /**
   * Chips wrapping to a second line is the row saying it is full at a width no
   * tier would call narrow, so the labels go before the chips do.
   */
  const filterRailRef = React.useRef<HTMLDivElement | null>(null)
  const actionsCrowded = useWrapCrowding({
    railRef: filterRailRef,
    rowWidth: toolbarRowWidth,
    resetKey: activeFilters.length,
    enabled: hasToolbarActions,
  })

  const filterableCols = React.useMemo(() => filterableColumns(columns), [columns])
  const searchModLabel = useModKeyLabel()
  const effectiveSearchable = showQueryControls && searchable
  const [searchRecentsOpen, setSearchRecentsOpen] = React.useState(false)
  const recentItems = searchRecentQueries ?? []

  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
      ref={toolbarRowRef}
      className={cn(
        "flex items-center gap-1.5",
        edgeInset && DATA_TABLE_TOOLBAR_INSET_CLASS,
        showQueryControls ? "min-h-10 pt-2 pb-2" : "min-h-0 justify-end py-1.5",
      )}
    >

      {showQueryControls && filterBarVisible && filterableCols.length > 0 && !compactFilterToolbar && (
        <FilterBar ref={filterRailRef}>
          {activeFilters.map(filter => (
            <React.Fragment key={filter.id}>
              <FilterPill
                filter={filter}
                columns={columns}
                fieldContext={filterFieldContext[filter.fieldKey]}
                open={filter.id === openFilterId}
                // A close that arrives after a sibling has opened must not
                // clobber it: pressing pill B dismisses A's editor and opens B's
                // as two separate events, in that order.
                onOpenChange={next =>
                  setOpenFilterId(prev =>
                    next ? filter.id : prev === filter.id ? null : prev,
                  )
                }
                onUpdate={updateFilter}
                onRemove={removeFilter}
                renderOptionValue={renderFilterOptionValue}
              />
            </React.Fragment>
          ))}

          {/* Opening the field menu closes whichever editor was open: the user
              has moved on to picking a new field, and Radix leaves a non-modal
              popover behind a modal menu on screen but inert. */}
          <DropdownMenu onOpenChange={next => { if (next) setOpenFilterId(null) }}>
            <DropdownMenuTrigger asChild>
              <FilterBarAddButton />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuLabel className="text-xs">Filter by field</DropdownMenuLabel>
              <DropdownMenuSeparator />
              {filterableCols.map(c => {
                const icon = resolveColumnFilter(c)?.icon
                return (
                  <DropdownMenuItem key={c.key} onClick={() => addFilter(c.key)}>
                    {icon ? <i className={`fa-light ${icon}`} aria-hidden="true" /> : null}
                    {c.label}
                  </DropdownMenuItem>
                )
              })}
            </DropdownMenuContent>
          </DropdownMenu>

          {activeFilters.length > 0 ? (
            <FilterBarClearButton onClick={() => setActiveFilters([])} />
          ) : null}
        </FilterBar>
      )}

      <div
        className={cn(
          "flex items-center gap-1 shrink-0",
          showQueryControls && "ms-auto",
        )}
      >

        {effectiveSearchable && (
          searchOpen ? (
            <TableSearchRecentsPopover
              open={searchRecentsOpen && !search.trim() && recentItems.length > 0}
              onOpenChange={setSearchRecentsOpen}
              items={recentItems}
              onSelect={query => {
                setSearch(query)
                onSearchRecentSelect?.(query)
              }}
              onClear={onSearchRecentClear}
              anchor={
                <TableSearchFieldAnchor
                  searchRef={searchRef}
                  search={search}
                  setSearch={setSearch}
                  setSearchOpen={setSearchOpen}
                  setSearchRecentsOpen={setSearchRecentsOpen}
                  recentItems={recentItems}
                  onSearchRecentRecord={onSearchRecentRecord}
                  searchAriaLabel={searchAriaLabel}
                />
              }
            />
          ) : (
            <TooltipProvider>
              <Tooltip>
                <TooltipTrigger asChild>
                  <button type="button" aria-label="Search"
                    onClick={() => { setSearchOpen(true); setTimeout(() => searchRef.current?.focus(), 10) }}
                    className="icon-button-chrome inline-flex shrink-0 cursor-pointer items-center justify-center size-8 rounded-md 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-icon" 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" />
            {compactFilterToolbar ? (
              <TooltipProvider>
                <Tooltip>
                  <TooltipTrigger asChild>
                    <FilterButton
                      activeCount={activeFilters.length}
                      aria-label={
                        activeFilters.length > 0
                          ? `Filters (${activeFilters.length} active). Open filter settings.`
                          : "Open filter settings"
                      }
                      onClick={() => openFilterPanelInDrawer()}
                    />
                  </TooltipTrigger>
                  <TooltipContent side="bottom">
                    {activeFilters.length > 0
                      ? `${activeFilters.length} filter${activeFilters.length !== 1 ? "s" : ""} active. Open settings.`
                      : "Filter settings"}
                  </TooltipContent>
                </Tooltip>
              </TooltipProvider>
            ) : activeFilters.length > 0 ? (
              <TooltipProvider>
                <Tooltip>
                  <TooltipTrigger asChild>
                    <FilterButton
                      activeCount={activeFilters.length}
                      highlighted={filterBarVisible}
                      aria-label={filterBarVisible ? "Hide filters" : "Show filters"}
                      onClick={() => setFilterBarVisible(v => !v)}
                    />
                  </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>
                        <FilterButton
                          aria-label="Add filter"
                          onClick={() => setFilterBarVisible(true)}
                        />
                      </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 => {
                    const icon = resolveColumnFilter(c)?.icon
                    return (
                      <DropdownMenuItem key={c.key} onClick={() => addFilter(c.key)}>
                        {icon ? <i className={`fa-light ${icon}`} aria-hidden="true" /> : null}
                        {c.label}
                      </DropdownMenuItem>
                    )
                  })}
                </DropdownMenuContent>
              </DropdownMenu>
            )}
          </>
        )}

        {toolbarSlot && toolbarSlot(state)}

        {/* Record commands sit last, after the controls that shape the view, so
            the row reads left-to-right as "what you are looking at" then "what
            you can do". The rule keeps Add from being mistaken for one more
            view control. */}
        {hasToolbarActions ? (
          <>
            <div className="h-4 w-px bg-border/70" aria-hidden="true" />
            <ResponsiveActionRow
              items={toolbarActions ?? []}
              compact={actionsCompact || actionsCrowded}
              overflowOnly={actionsOverflowOnly}
              ariaLabel="Table actions"
              dataSlot="data-table-toolbar-actions"
              debugOwner="DataTableToolbar"
              // gap-1.5 not gap-2: this row shares its line with filter chips
              // and the icon buttons before it, both of which sit on 1.5.
              className="gap-1.5"
            />
          </>
        ) : null}
      </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
  /** Record commands rendered after Properties. See `HubTableProps.toolbarActions`. */
  toolbarActions?: ResponsiveAction[]
  /** Slot rendered inside the floating bulk-action bar (after the count badge) */
  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
  /**
   * Chrome rendered under the grid in a sticky foot stack (bulk bar + this node).
   * Prefer this over a sibling footer so selection actions stick with pagination.
   */
  stickyFooter?: React.ReactNode
  /**
   * When false, table toolbar and grid omit `mx-4 lg:mx-6` / `px-4 lg:px-6` insets.
   * Use on embedded surfaces where the page shell or content rail already pads horizontally.
   */
  edgeInset?: boolean
  /**
   * When false, hides toolbar search/filter chrome (e.g. catalog API prop matrices).
   * Grid column resize, sort, and header menus still work.
   */
  showQueryControls?: 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>>
  /**
   * Incremental row rendering for very large datasets. Keeps initial paint fast
   * and appends remaining rows in idle slices while showing a loading hint.
   */
  lazyLoading?: {
    enabled?: boolean
    threshold?: number
    chunkSize?: number
    intervalMs?: number
    loadingLabel?: string
  }
}

type DataTableInnerProps<TData extends Record<string, unknown>> = DataTableExtendedProps<TData> & {
  state: ReturnType<typeof useTableState<TData>>
}

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,
  openRowId,
  defaultSort: _defaultSort,
  toolbarSlot,
  toolbarActions,
  bulkActionsSlot,
  addRowLabel = false,
  renderFilterOptionValue,
  hasFooter = false,
  stickyFooter,
  edgeInset = true,
  showQueryControls = true,
  conditionalRules,
  showColumnHeaders = true,
  lazyLoading,
  state,
}: DataTableInnerProps<TData>) {
  const reflowZoom = useSidebarReflowZoom()
  // A defined `openRowId` — `null` included — is the consumer saying "rows open
  // a rail on this hub". That turns on the open-row marker and exempts rows from
  // the rail's outside-click dismissal, so clicking a second row retargets the
  // rail rather than closing it and opening it again a frame later.
  const rowsOpenRail = openRowId !== undefined
  const useStickyFootStack = stickyFooter != null
  const {
    setSortRules,
    sortKey, sortDir,
    handleSortByKey,
    openColumnFilterInDrawer,
    activeFilters,
    groupBy, setGroupBy,
    colMenuSearch, setColMenuSearch,
    selected, setSelected, toggleRow, toggleAll, setRowsSelected, getRowId,
    colWidths, startResize,
    colPins, lockedPins,
    pinColumn, unpinColumn,
    colWrap, toggleWrap,
    draggedKey, dragOverKey,
    handleDragStart, handleDragOver, handleDrop, handleDragEnd,
    scrollRef, handleScroll, checkOverflow,
    isOverflowing,
    rows, pagedRows, groupedRows,
    effectivePins, displayCols,
    stickyPinsDisabled,
    stickyStyle,
    totalWidth,
    rowHeight,
    showGridlines,
    setSheetOpen,
    setSheetInitialPanel,
  } = state

  /** Last width published to `--dt-scrollport-width`; skips redundant writes. */
  const lastScrollportVarWidth = React.useRef(-1)

  // Mount overflow check + scrollport width for sticky group headers on horizontal scroll.
  // Re-run when column widths / visibility change — scrollWidth alone is unreliable when
  // the table used to stretch with `w-full` (scrollWidth === clientWidth even with many cols).
  React.useLayoutEffect(() => {
    const syncScrollport = () => {
      // Reads before writes. Setting the custom property first made
      // `checkOverflow`'s `clientWidth` read flush layout again, so a rail drag
      // paid a forced synchronous layout on every frame. The guard also keeps
      // the write off frames where the width is unchanged (vertical scroll).
      checkOverflow()
      const el = scrollRef.current
      if (!el) return
      const width = el.clientWidth
      if (lastScrollportVarWidth.current === width) return
      lastScrollportVarWidth.current = width
      el.style.setProperty("--dt-scrollport-width", `${width}px`)
    }
    // Re-subscribing may mean a fresh scroll element, which carries no custom
    // property yet — force the first write of this subscription.
    lastScrollportVarWidth.current = -1
    syncScrollport()
    const el = scrollRef.current
    if (!el) return
    const ro = new ResizeObserver(syncScrollport)
    ro.observe(el)
    const table = el.querySelector("table")
    if (table) ro.observe(table)
    return () => ro.disconnect()
  }, [totalWidth, displayCols.length, checkOverflow, scrollRef])

  /** 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 || stickyPinsDisabled || 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, stickyPinsDisabled, colPins, scrollRef])

  const lastLeftPinKey   = [...displayCols].reverse().find(c => effectivePins[c.key] === "left")?.key
  const firstRightPinKey = displayCols.find(c => effectivePins[c.key] === "right")?.key
  const lastRightPinKey  = [...displayCols].reverse().find(c => effectivePins[c.key] === "right")?.key

  const rightPinSeams = React.useMemo(
    () =>
      stickyPinsDisabled
        ? []
        : pinBlockSeamOffsets(displayCols, effectivePins, colWidths, "right"),
    [colWidths, displayCols, effectivePins, stickyPinsDisabled],
  )

  const leftPinSeams = React.useMemo(
    () =>
      stickyPinsDisabled
        ? []
        : pinBlockSeamOffsets(displayCols, effectivePins, colWidths, "left"),
    [colWidths, displayCols, effectivePins, stickyPinsDisabled],
  )

  function floatingHeaderPinnedStyle(key: string): React.CSSProperties | undefined {
    const pin = effectivePins[key]
    if (!pin) return undefined

    // Use the sticky header's INNER scrollport width (body's `clientWidth`),
    // not the outer rectangle (`floatingHeaderStyle.width`), so the
    // right-pinned column locks to the visible inner edge and not 2px past it.
    const visibleWidth =
      floatingHeaderInnerWidth > 0
        ? floatingHeaderInnerWidth
        : tableWrapRef.current?.clientWidth ?? floatingHeaderTableWidth
    const maxScroll = Math.max(0, floatingHeaderTableWidth - visibleWidth)
    const scrollLeft = headerScrollLeftRef.current
    const translateX = pin === "left"
      ? scrollLeft
      : scrollLeft - maxScroll

    // The floating sticky header is horizontally translated as one table.
    // Counter-translate pinned header cells so they remain locked to the viewport edge.
    // `data-dt-floating-pin` lets scroll sync mutate this transform without React.
    return { position: "relative", transform: `translateX(${translateX}px)` }
  }

  const tableGroups = React.useMemo(
    () =>
      pagedRows !== rows
        ? [{
            groupKey: null as string | null,
            groupLabel: null as string | null,
            groupValue: null as unknown,
            rows: pagedRows,
          }]
        : groupedRows,
    [groupedRows, pagedRows, rows],
  )

  const totalRenderableRows = React.useMemo(
    () => tableGroups.reduce((sum, group) => sum + group.rows.length, 0),
    [tableGroups],
  )

  const { renderCount, isLazyLoading } = useIncrementalRender(totalRenderableRows, {
    enabled: lazyLoading?.enabled ?? true,
    threshold: lazyLoading?.threshold,
    chunkSize: lazyLoading?.chunkSize,
    intervalMs: lazyLoading?.intervalMs,
  })

  const displayedGroups = React.useMemo(() => {
    if (!isLazyLoading) return tableGroups
    let remaining = renderCount
    const next: typeof tableGroups = []
    for (const group of tableGroups) {
      if (remaining <= 0) break
      const take = Math.min(group.rows.length, remaining)
      if (take > 0) {
        next.push({
          ...group,
          rows: group.rows.slice(0, take),
        })
      }
      remaining -= take
    }
    return next
  }, [isLazyLoading, renderCount, tableGroups])

  const lazyLoadingLabel = lazyLoading?.loadingLabel ?? "Loading more rows..."

  // Row IDs for rows currently rendered (respects embedded cap / pagination / lazy slice).
  const visibleRows = React.useMemo(() => {
    const groups = isLazyLoading ? displayedGroups : tableGroups
    return groups.flatMap(group => group.rows)
  }, [displayedGroups, isLazyLoading, tableGroups])

  const visibleRowIds = React.useMemo(
    () => visibleRows.map((r, i) => getRowId(r, i, getRowIdProp)),
    [visibleRows, getRowId, getRowIdProp],
  )

  const allSelected =
    visibleRowIds.length > 0 && visibleRowIds.every(id => selected.has(id))
  const someSelected =
    visibleRowIds.some(id => selected.has(id)) && !allSelected
  const anySelected  = selected.size > 0
  // The standalone (no `stickyFooter`) bulk bar used to render *inside* the
  // grid shell, which sets `overflow-hidden` to clip horizontal scroll and
  // rounded corners — a `position: sticky` descendant of an `overflow-hidden`
  // ancestor never sticks, it just scrolls off with the rows once the page
  // (not this component) is what actually scrolls past table-height content.
  // Rendering it as a sibling *after* the shell closes, exactly like the
  // `stickyFooter` stack below already does, is what makes `sticky bottom-0`
  // able to find the page's real scrollport.
  const showInShellBulkBar = !useStickyFootStack && anySelected
  // Whether a footer/bulk stack renders below the grid shell at all. When it
  // does, the shell and the stack are two independent boxes (the stack has to
  // live outside the shell's `overflow-hidden` — see above) that must still
  // read as one continuous card. Painting `border-x` + the `mx-*` inset on
  // each of them separately relies on both boxes laying out to the exact same
  // sub-pixel width, which a `position: sticky` box isn't guaranteed to match
  // (browsers can round a sticky box's geometry a hair differently from an
  // in-flow sibling), producing a visible 1-2px step in the side borders right
  // at the seam. Owning the side borders + inset on one shared wrapper instead
  // (see the outer `<div>` below) makes that impossible by construction.
  const hasBottomStack = useStickyFootStack || showInShellBulkBar
  const bulkMod = useModKeyLabel()
  const bulkAlt = useAltKeyLabel()
  // Prefer ⌘⌥ / Ctrl+Alt — never ⌘⇧E (Finder eject / Edge Collections) or ⌘⌫ (Mac delete).
  const defaultBulkExportShortcut = `${bulkMod}${bulkAlt}E`
  const defaultBulkDeleteShortcut = `${bulkMod}${bulkAlt}⌫`

  // Polaris IndexTable parity: Esc clears the row selection while the bulk
  // bar is visible. `isEditableTarget` keeps Esc inside <input>/<textarea>/
  // contenteditable acting as "cancel edit" — only un-focused Esc clears.
  // Bind only when a selection exists so idle tables don't sit on a global
  // keydown listener.
  React.useEffect(() => {
    if (!anySelected) return
    function onKeyDown(e: KeyboardEvent) {
      if (e.key !== "Escape") return
      if (isEditableTarget(e.target)) return
      e.preventDefault()
      setSelected(new Set())
    }
    document.addEventListener("keydown", onKeyDown)
    return () => document.removeEventListener("keydown", onKeyDown)
  }, [anySelected, setSelected])

  const tableWrapRef = React.useRef<HTMLDivElement | null>(null)
  const tableHeadRef = React.useRef<HTMLTableSectionElement | null>(null)
  const [headerIsStuck, setHeaderIsStuck] = React.useState(false)
  /**
   * Visible keyboard focus (or an open column menu) in the real `<thead>` while
   * sticky — unhide it and drop the floating clone so the focus ring + ⋯ show.
   * Parent `opacity-0` otherwise hides children even when Tip portals the label.
   * Gated on `:focus-visible`, not `:focus`: a mouse click on a column ⋯ leaves
   * focus parked there, which would otherwise keep the clone unmounted for good.
   */
  const [headerKeyboardActive, setHeaderKeyboardActive] = React.useState(false)
  const [headerMenuOpenCount, setHeaderMenuOpenCount] = React.useState(0)
  const headerSurfaceActive = headerKeyboardActive || headerMenuOpenCount > 0
  const effectiveHeaderStuck = showColumnHeaders && headerIsStuck && !headerSurfaceActive

  const bumpHeaderMenuOpen = React.useCallback((open: boolean) => {
    setHeaderMenuOpenCount(n => Math.max(0, n + (open ? 1 : -1)))
  }, [])

  // Document-level sync — Tip + Dropdown can make thead focusCapture alone flaky.
  // Portaled menus are covered by `headerMenuOpenCount` (real thead only), not
  // by treating every `[role=menu]` as active (that would unmount the floating clone).
  React.useLayoutEffect(() => {
    if (!headerIsStuck) {
      setHeaderKeyboardActive(false)
      return
    }
    const sync = () => {
      const head = tableHeadRef.current
      const active = document.activeElement
      const inHead = !!(active && head?.contains(active))
      setHeaderKeyboardActive(inHead && hasVisibleFocus(active))
    }
    document.addEventListener("focusin", sync)
    document.addEventListener("focusout", sync)
    sync()
    return () => {
      document.removeEventListener("focusin", sync)
      document.removeEventListener("focusout", sync)
    }
  }, [headerIsStuck])
  /**
   * Column keys carrying a filter that actually narrows the rows. Mirrors the
   * `activeWithValues` gate in `use-table-state` — a filter row whose value is
   * still blank changes nothing, so it must not claim a header indicator.
   */
  const filteredColumnKeys = React.useMemo(() => {
    const keys = new Set<string>()
    for (const filter of activeFilters) {
      if (!filter.values.some(value => String(value ?? "").trim().length > 0)) continue
      keys.add(filter.fieldKey)
    }
    return keys
  }, [activeFilters])

  /** Column keys with a conditional-formatting rule that can paint a cell. */
  const conditionalRuleColumnKeys = React.useMemo(() => {
    const keys = new Set<string>()
    for (const rule of conditionalRules ?? []) {
      if (ruleHasActiveValues(rule, columns)) keys.add(rule.fieldKey)
    }
    return keys
  }, [conditionalRules, columns])

  const sortRuleIdRef = React.useRef(0)
  // Horizontal scroll for the floating header — DOM-mutated (same rationale as
  // floatingHeaderWrapperRef). React state here re-rendered the whole sticky
  // thead on every horizontal tick.
  const headerScrollLeftRef = React.useRef(0)
  const floatingHeaderTranslateRef = React.useRef<HTMLDivElement | null>(null)

  // The sticky-header position is mutated **directly on the DOM** rather
  // than going through React state. State updates on every scroll tick
  // were re-rendering the entire `<thead>` (with its full DropdownMenu per
  // column) on each rAF — visibly sluggish on long tables. The wrapper
  // ref's style is updated inside `apply()` below; the gate stays in
  // React state via `headerIsStuck` (a boolean that flips rarely).
  const floatingHeaderWrapperRef = React.useRef<HTMLDivElement | null>(null)
  // Cache last-applied position so we skip DOM writes when nothing
  // changed. Pure vertical scroll doesn't move `rect.left`/`rect.width`,
  // so the wrapper's style stays untouched and the browser keeps layout
  // cached frame-to-frame. Without this, every rAF wrote 4 style props →
  // browser invalidated layout → next read forced a layout flush →
  // visible scroll jank.
  const lastFloatingHeaderApplied = React.useRef<{
    left: number
    width: number
    top: number
  }>({ left: -1, width: -1, top: -1 })
  // Inner `<table>` element of the scroll wrapper, captured once when the
  // header pins. Avoids `querySelector + getBoundingClientRect` on every
  // scroll tick (the latter forces a full layout pass on the table tree).
  const innerTableElRef = React.useRef<HTMLTableElement | null>(null)
  const [floatingHeaderTableWidth, setFloatingHeaderTableWidth] = React.useState(totalWidth)
  /**
   * Inner scrollport width of the sticky header (body's `clientWidth` —
   * already excludes the wrapper's `border-x`). Tracked separately from
   * the wrapper's outer width (which has its own `border border-border`
   * that overlays the body's borders exactly). Used by
   * `floatingHeaderPinnedStyle` to compute max-scroll for right-pinned columns.
   */
  const [floatingHeaderInnerWidth, setFloatingHeaderInnerWidth] = React.useState(0)

  const syncFloatingHeaderScroll = React.useCallback((scrollLeft: number) => {
    if (headerScrollLeftRef.current === scrollLeft) return
    headerScrollLeftRef.current = scrollLeft
    const translateEl = floatingHeaderTranslateRef.current
    if (translateEl) {
      translateEl.style.transform = `translateX(${-scrollLeft}px)`
    }
    const visibleWidth =
      floatingHeaderInnerWidth > 0
        ? floatingHeaderInnerWidth
        : tableWrapRef.current?.clientWidth ?? floatingHeaderTableWidth
    const maxScroll = Math.max(0, floatingHeaderTableWidth - visibleWidth)
    const pinned = translateEl?.querySelectorAll<HTMLElement>("[data-dt-floating-pin]")
    pinned?.forEach(el => {
      const pin = el.dataset.dtFloatingPin
      if (pin !== "left" && pin !== "right") return
      const translateX = pin === "left" ? scrollLeft : scrollLeft - maxScroll
      el.style.transform = `translateX(${translateX}px)`
    })
  }, [floatingHeaderInnerWidth, floatingHeaderTableWidth])

  const isClient = useIsClient()

  React.useEffect(() => {
    if (!showColumnHeaders) return

    const wrapEl = tableWrapRef.current
    const headEl = tableHeadRef.current
    if (!wrapEl || !headEl) return

    const update = () => {
      const wrapRect = wrapEl.getBoundingClientRect()
      const headHeight = headEl.getBoundingClientRect().height || 0
      const headerOffset = getStickyTableHeaderOffset()
      const stuck = wrapRect.top <= headerOffset && wrapRect.bottom > (headHeight + headerOffset + 1)
      setHeaderIsStuck(prev => (prev === stuck ? prev : stuck))
    }

    const scheduled = rafThrottle(update)
    const rafId = requestAnimationFrame(update)
    // Hub pages scroll in `[data-page-scroll]`, not `window` — bind both plus resize.
    const unbindVerticalScroll = bindVerticalScrollListeners(scheduled)
    wrapEl.addEventListener("scroll", scheduled, { passive: true })
    const resizeObserver = new ResizeObserver(() => scheduled())
    resizeObserver.observe(wrapEl)
    resizeObserver.observe(headEl)
    return () => {
      cancelAnimationFrame(rafId)
      scheduled.cancel()
      unbindVerticalScroll()
      resizeObserver.disconnect()
      wrapEl.removeEventListener("scroll", scheduled)
    }
  }, [showColumnHeaders])

  React.useLayoutEffect(() => {
    if (!effectiveHeaderStuck) return
    const wrapEl = tableWrapRef.current
    if (!wrapEl) return

    // Capture once — cheaper than `querySelector` per scroll tick, and
    // the inner table element is stable while the wrapper is mounted.
    innerTableElRef.current = wrapEl.querySelector("table")

    const last = lastFloatingHeaderApplied.current
    // Reset cache so the first `apply()` after pin always writes.
    last.left = -1
    last.width = -1
    last.top = -1

    let pendingTableMeasure = true

    const apply = () => {
      const rect = wrapEl.getBoundingClientRect()
      const headerOffset = getStickyTableHeaderOffset()

      // 1) Wrapper position — DOM mutation guarded by a cache. On pure
      //    vertical scroll `rect.left`/`rect.width` don't change, so we
      //    write nothing → browser keeps layout cached → no scroll jank.
      const wrapperEl = floatingHeaderWrapperRef.current
      if (wrapperEl) {
        if (last.top !== headerOffset) {
          wrapperEl.style.position = "fixed"
          wrapperEl.style.top = `${headerOffset}px`
          wrapperEl.style.zIndex = "50"
          last.top = headerOffset
        }
        if (last.left !== rect.left) {
          wrapperEl.style.left = `${rect.left}px`
          last.left = rect.left
        }
        if (last.width !== rect.width) {
          wrapperEl.style.width = `${rect.width}px`
          last.width = rect.width
        }
      }

      // 2) Inner / table widths — only re-measure when the wrapper or
      //    underlying table actually resized. The dedicated ResizeObserver
      //    below sets `pendingTableMeasure` so a pure-scroll tick skips the
      //    expensive `getBoundingClientRect` on the inner `<table>`.
      // `clientWidth` already excludes the wrapper's `border-x`, so we use
      // it directly as the inner scrollport width.
      const innerWidth = Math.max(0, wrapEl.clientWidth)
      setFloatingHeaderInnerWidth(prev => (prev === innerWidth ? prev : innerWidth))

      if (pendingTableMeasure) {
        const innerTableWidth =
          innerTableElRef.current?.getBoundingClientRect().width ?? 0
        const renderedTableWidth = Math.max(totalWidth, innerWidth, innerTableWidth)
        setFloatingHeaderTableWidth(prev => (prev === renderedTableWidth ? prev : renderedTableWidth))
        pendingTableMeasure = false
      }

      // 3) Horizontal scroll — DOM sync (no React commit).
      syncFloatingHeaderScroll(wrapEl.scrollLeft)
    }

    apply()
    const scheduled = rafThrottle(apply)
    // Wrap-element resize → re-measure the inner table next tick.
    const wrapRO = new ResizeObserver(() => {
      pendingTableMeasure = true
      scheduled()
    })
    wrapRO.observe(wrapEl)
    // Inner table resize (e.g. column resize) → also re-measure.
    let tableRO: ResizeObserver | undefined
    if (innerTableElRef.current) {
      tableRO = new ResizeObserver(() => {
        pendingTableMeasure = true
        scheduled()
      })
      tableRO.observe(innerTableElRef.current)
    }
    const unbindVerticalScroll = bindVerticalScrollListeners(scheduled)
    return () => {
      scheduled.cancel()
      unbindVerticalScroll()
      wrapRO.disconnect()
      tableRO?.disconnect()
    }
  }, [effectiveHeaderStuck, totalWidth, displayCols.length, syncFloatingHeaderScroll])

  /*
   * ── Pinned group divider ────────────────────────────────────────────────
   *
   * Grouping used to read as "the header stopped sticking": the column header
   * still pinned, but the divider that says *which group you are in* scrolled
   * away with its rows, so a long group left you reading a header with no
   * subject. The divider carried `sticky start-0`, which pins it horizontally
   * inside the scroll wrapper and does nothing vertically.
   *
   * So the divider gets the same treatment the column header already has: a
   * clone in the fixed wrapper, directly under the header. It names the group
   * whose rows are under the pin line, and when the next group's real divider
   * arrives it pushes the clone up out of a clipped window and takes over — the
   * hand-off you get in a phone contacts list, rather than a label that
   * teleports between groups.
   */
  const floatingHeaderBoxRef = React.useRef<HTMLDivElement | null>(null)
  const groupClipRef = React.useRef<HTMLDivElement | null>(null)
  const groupSlideRef = React.useRef<HTMLDivElement | null>(null)
  const groupsWithLabels = React.useMemo(
    () => displayedGroups.filter(g => g.groupLabel),
    [displayedGroups],
  )
  const hasGroupDividers = groupsWithLabels.length > 0
  /** Index into `groupsWithLabels`; -1 while no group owns the pin line. */
  const [pinnedGroupIndex, setPinnedGroupIndex] = React.useState(-1)

  React.useLayoutEffect(() => {
    if (!effectiveHeaderStuck || !hasGroupDividers) {
      setPinnedGroupIndex(-1)
      return
    }
    const wrapEl = tableWrapRef.current
    if (!wrapEl) return

    // Re-read on structural change only; the list is stable while scrolling.
    let dividers = Array.from(
      wrapEl.querySelectorAll<HTMLElement>("[data-dt-group-header]"),
    )
    let lastSlide = Number.NaN

    const apply = () => {
      const boxEl = floatingHeaderBoxRef.current
      const slideEl = groupSlideRef.current
      const clipEl = groupClipRef.current
      if (!boxEl) return
      // Bottom of the column header — the line a divider pins to.
      const pinLine = boxEl.getBoundingClientRect().bottom

      // Past the end of the table there is no group to be inside of.
      if (wrapEl.getBoundingClientRect().bottom <= pinLine) {
        setPinnedGroupIndex(prev => (prev === -1 ? prev : -1))
        return
      }

      let index = -1
      for (let i = 0; i < dividers.length; i++) {
        if (dividers[i].getBoundingClientRect().top <= pinLine + 0.5) index = i
        else break
      }
      setPinnedGroupIndex(prev => (prev === index ? prev : index))
      if (index === -1) return

      // How far the next divider has pushed into the pinned one. Measured off
      // the real row so the clone leaves at exactly the speed the row arrives.
      const barHeight = dividers[index].getBoundingClientRect().height
      const next = dividers[index + 1]
      const overlap = next
        ? Math.max(0, barHeight - (next.getBoundingClientRect().top - pinLine))
        : 0
      if (clipEl && clipEl.style.height !== `${barHeight}px`) {
        clipEl.style.height = `${barHeight}px`
      }
      if (slideEl && lastSlide !== overlap) {
        slideEl.style.transform = `translateY(${-overlap}px)`
        lastSlide = overlap
      }
    }

    apply()
    const scheduled = rafThrottle(apply)
    const unbindVerticalScroll = bindVerticalScrollListeners(scheduled)
    const resizeObserver = new ResizeObserver(() => scheduled())
    resizeObserver.observe(wrapEl)
    // Rows collapse, load, or regroup without a scroll — re-collect and re-pin.
    const mutationObserver = new MutationObserver(() => {
      dividers = Array.from(
        wrapEl.querySelectorAll<HTMLElement>("[data-dt-group-header]"),
      )
      scheduled()
    })
    mutationObserver.observe(wrapEl, { childList: true, subtree: true })
    return () => {
      scheduled.cancel()
      unbindVerticalScroll()
      resizeObserver.disconnect()
      mutationObserver.disconnect()
    }
  }, [effectiveHeaderStuck, hasGroupDividers, groupsWithLabels.length])

  const pinnedGroup = pinnedGroupIndex >= 0 ? groupsWithLabels[pinnedGroupIndex] : undefined

  /**
   * The select column's rendered box, which is the slot the group checkbox sits
   * in. Read from the live width so a consumer that ships a wider select column
   * keeps the two checkboxes on one axis.
   */
  const selectColumnWidth = React.useMemo(() => {
    const col = displayCols.find(c => c.key === "select")
    if (!col) return undefined
    return colWidths[col.key] ?? col.width ?? col.minWidth ?? 40
  }, [colWidths, displayCols])

  /**
   * The grouped column's own vocabulary for its values, keyed by raw value —
   * grouping keys on `String(row[groupBy])`, so a status group arrives as
   * `approved`, not as the chip the column paints in its cells.
   *
   * Read off `ColumnDef.filter.options` rather than the resolved filter, because
   * only the column def carries `node` and `tone`; the resolved def is narrowed
   * to value and label for the filter menus.
   */
  const groupValueOptions = React.useMemo(() => {
    if (!groupBy) return undefined
    const options = columns.find(c => c.key === groupBy)?.filter?.options
    if (!options?.length) return undefined
    return new Map(options.map(o => [o.value, o]))
  }, [columns, groupBy])

  /** The kind of thing the grouped column shows, so the divider can speak it. */
  const groupedColumnKind = groupBy
    ? columns.find(c => c.key === groupBy)?.cellKind
    : undefined

  /**
   * What a divider shows for one group: the column's chip when it has one, so
   * the divider names the value the way the rows beneath it do, and the fill the
   * band carries.
   *
   * When `filter.options[].tone` is set, the band uses the same fill token as
   * the status badge (`--status-badge-*-fill`). Pill and other kinds without a
   * tone keep neutral grey. Status / pill headings render as md badges.
   */
  function groupDisplay(groupLabel: string, groupValue?: unknown): {
    node: React.ReactNode
    label: string
    tint?: string
  } {
    const option = groupValueOptions?.get(groupLabel)
    const tone = option?.tone
    const tint = tone ? groupBarTint(tone) : undefined
    const empty = groupLabel === GROUP_EMPTY_KEY
    const rawLabel = option?.label ?? (empty ? "None" : groupLabel)
    const label = groupRowAccessibilityLabel(groupValue, groupedColumnKind, rawLabel)

    if (!empty && groupedColumnKind === "people-rail" && Array.isArray(groupValue)) {
      return {
        node: (
          <PeopleAvatarRailCell
            people={groupValue as PersonStub[]}
            size="sm"
          />
        ),
        label,
        tint,
      }
    }

    if (!empty && isBadgeGroupKind(groupedColumnKind)) {
      return {
        node: groupBadgeNode(rawLabel, groupedColumnKind, option),
        label,
        tint,
      }
    }

    if (option?.node) return { node: option.node, label, tint }

    // An empty group has no identity to rebuild — no avatar for a missing
    // person, no calendar for a missing date.
    return {
      node: empty ? label : groupKindNode(rawLabel, groupedColumnKind),
      label,
      tint,
    }
  }

  const pinnedGroupDisplay = pinnedGroup?.groupLabel
    ? groupDisplay(pinnedGroup.groupLabel, pinnedGroup.groupValue)
    : undefined

  /**
   * A group's checkbox, shown in its divider bar. Row ids are derived with the
   * group-local index so they match the ids the body rows register under, and
   * the toggle adds or removes only this group's ids — a group is a subset of
   * the selection, not a replacement for it.
   *
   * `interactive: false` renders the mirror for the pinned clone: same box, no
   * pointer, no Tab stop, because the real bar is still in the table for the
   * keyboard and screen reader.
   */
  function renderGroupSelect(
    groupLabel: string | null,
    groupRows: TData[],
    opts?: { interactive?: boolean },
  ): React.ReactNode {
    if (!selectable || groupRows.length === 0) return null
    const interactive = opts?.interactive !== false
    const ids = groupRows.map((row, i) => getRowId(row, i, getRowIdProp))
    let selectedCount = 0
    for (const id of ids) if (selected.has(id)) selectedCount += 1
    const allInGroup = selectedCount === ids.length
    const someInGroup = selectedCount > 0 && !allInGroup
    const label = `Select ${ids.length} record${ids.length !== 1 ? "s" : ""} in ${groupLabel ?? "group"}`
    return (
      <Checkbox
        data-dt-group-select=""
        checked={allInGroup ? true : someInGroup ? "indeterminate" : false}
        tabIndex={interactive ? undefined : -1}
        onCheckedChange={interactive ? () => setRowsSelected(ids, !allInGroup) : undefined}
        aria-label={label}
        className={cn(!interactive && "pointer-events-none")}
      />
    )
  }

  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)
  }

  /**
   * Shared header-cell inner content — label / sort button / select-checkbox
   * + ⋯ kebab menu (pin, sort, wrap, filter, group, conditional rule,
   * quick-search). Rendered identically by the inline `<thead>` and the
   * portal sticky `<thead>`. The `<th>` shells now also share drag-reorder
   * attributes and the resize handle, so the only practical difference
   * between the two thead variants is the `style` prop (sticky uses
   * `floatingHeaderPinnedStyle`, inline uses `stickyStyle`).
   */
  function renderHeaderCellInner(
    col: ColumnDef<TData>,
    opts?: { /** When false, exclude from Tab order (floating sticky clone). */ tabbable?: boolean },
  ): React.ReactNode {
    const tabbable = opts?.tabbable !== false
    const tabIndex = tabbable ? undefined : -1
    const isLocked = !!lockedPins[col.key]
    const columnLabel = resolvedColumnLabel(col)
    /**
     * What is applied to this column, so a filtered / grouped / conditionally
     * formatted column is legible without opening the ⋯ menu or the rail.
     * Solid weight reads as "on" against the light-weight header chrome.
     */
    const appliedIndicators = isControlColumn(col.key)
      ? []
      : [
          filteredColumnKeys.has(col.key) && {
            icon: "fa-filter",
            label: `Filtered by ${columnLabel}`,
          },
          groupBy === col.key && {
            icon: "fa-layer-group",
            label: `Grouped by ${columnLabel}`,
          },
          conditionalRuleColumnKeys.has(col.key) && {
            icon: "fa-palette",
            label: `Conditional formatting on ${columnLabel}`,
          },
        ].filter((entry): entry is { icon: string; label: string } => Boolean(entry))
    const showColumnMenu =
      col.key !== "select" &&
      !lockedPins[col.key]?.includes("right") &&
      col.key !== columns.find(c => c.lockPin && c.defaultPin === "right")?.key
    return (
      <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 w-full items-center justify-center">
                <span className="sr-only">{resolvedColumnLabel(col)}</span>
                <Checkbox
                  tabIndex={tabIndex}
                  checked={allSelected ? true : someSelected ? "indeterminate" : false}
                  onCheckedChange={() => toggleAll(visibleRowIds)}
                  aria-label="Select all rows"
                />
              </span>
            )
          ) : col.sortable && col.sortKey ? (
            <Tip label={`Sort by ${resolvedColumnLabel(col)}`} side="top">
              <button
                type="button"
                tabIndex={tabIndex}
                onClick={() => handleSortByKey(col.key)}
                className={cn(
                  "inline-flex items-center rounded-sm whitespace-nowrap transition-colors",
                  "hover:text-interactive-hover-foreground",
                  // Inset ring — th + scrollport clip outset rings.
                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
                  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>
          )}

          {appliedIndicators.length > 0 && (
            <span className="ms-1.5 inline-flex shrink-0 items-center gap-1">
              {appliedIndicators.map(indicator => (
                <Tip key={indicator.icon} label={indicator.label} side="top">
                  <span
                    role="img"
                    aria-label={indicator.label}
                    tabIndex={tabbable ? 0 : -1}
                    className={cn(
                      "inline-flex cursor-default items-center rounded-sm text-2xs text-foreground",
                      // Inset ring — th + scrollport clip outset rings.
                      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
                    )}
                  >
                    <i className={cn("fa-solid", indicator.icon)} aria-hidden="true" />
                  </span>
                </Tip>
              ))}
            </span>
          )}
        </div>

        {showColumnMenu && (
          <DropdownMenu
            onOpenChange={open => {
              // Only the real (tabbable) thead — bumping from the floating
              // clone would set `headerSurfaceActive` and unmount that clone
              // mid-open, killing the menu.
              if (tabbable) bumpHeaderMenuOpen(open)
            }}
          >
            <Tip label="Column options" side="top">
              <DropdownMenuTrigger asChild>
                <button
                  type="button"
                  tabIndex={tabIndex}
                  aria-label={`${resolvedColumnLabel(col)} column options`}
                  // Filter and Add conditional rule both land in the Properties
                  // rail, so opening this menu must not dismiss the rail those
                  // items are about to retarget.
                  {...railTriggerProps()}
                  onClick={e => e.stopPropagation()}
                  className={cn(
                    "inline-flex aspect-square shrink-0 items-center justify-center size-7 rounded-md",
                    // Quiet until wanted: one kebab per column is noise across a
                    // wide header. Revealed by hover, by focus landing anywhere
                    // in the cell (so a keyboard user sees the control before
                    // reaching it — an earlier hover-only version showed the
                    // tooltip but not the ⋯), and for as long as the menu is
                    // open. Stays painted below `md`, where there is no hover to
                    // reveal it with.
                    "transition-opacity md:opacity-0",
                    "group-hover/th:opacity-100 group-focus-within/th:opacity-100 focus-visible:opacity-100 data-[state=open]:opacity-100",
                    "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover-row",
                    "data-[state=open]:bg-interactive-hover-row data-[state=open]:text-interactive-hover-foreground",
                    // Inset ring — header row is h-9 inside overflow-x-auto /
                    // sticky overflow-hidden; outset rings clip on all sides.
                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
                  )}
                >
                  <i className="fa-light fa-ellipsis-vertical text-xs" aria-hidden="true" />
                </button>
              </DropdownMenuTrigger>
            </Tip>
            <DropdownMenuContent
              align="start"
              // The menu is portalled, so it is outside the rail as well as the
              // trigger is. Choosing Filter would otherwise dismiss the rail
              // that the queued action is about to open onto that filter.
              {...railTriggerProps()}
              onCloseAutoFocus={event => {
                const action = columnMenuPendingActionRef.current
                if (!action) return
                columnMenuPendingActionRef.current = null
                event.preventDefault()
                runWithPreservedPageScroll(action, scrollRef.current)
              }}
            >
              <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 />

              {!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 />
                </>
              )}

              {col.sortable && col.sortKey && (
                <>
                  <DropdownMenuItem onClick={() => setSortRules(prev => {
                    const filtered = prev.filter(r => r.fieldKey !== col.key)
                    return [{ id: `sort-${++sortRuleIdRef.current}`, 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-${++sortRuleIdRef.current}`, 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 />
                </>
              )}

              <DropdownMenuItem onClick={() => toggleWrap(col.key)}>
                <i className="fa-light fa-text-width" aria-hidden="true" />
                {colWrap[col.key] ? "Unwrap Text" : "Wrap Text"}
              </DropdownMenuItem>

              <DropdownMenuSeparator />
              {col.filter && (
                <DropdownMenuItem
                  onSelect={() => {
                    // Defer until the column menu closes — same pattern as
                    // **Add Conditional Rule** so the Properties Sheet does
                    // not race Radix DropdownMenu focus / dismiss cycles
                    // (especially from the sticky floating header portal).
                    columnMenuPendingActionRef.current = () => {
                      openColumnFilterInDrawer(col.key)
                    }
                  }}
                >
                  <i className="fa-light fa-filter" aria-hidden="true" />
                  Filter by this column
                </DropdownMenuItem>
              )}
              <DropdownMenuItem
                onClick={() => setGroupBy(prev => prev === 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>

              <DropdownMenuSeparator />
              <DropdownMenuItem
                onSelect={() => {
                  // See note in inline thead — `onCloseAutoFocus` is the only safe
                  // moment to open the non-modal Properties Sheet without racing
                  // the DropdownMenu close cycle.
                  columnMenuPendingActionRef.current = () => {
                    setSheetInitialPanel("conditional-rules")
                    setSheetOpen(true)
                  }
                }}
              >
                <i className="fa-light fa-palette" aria-hidden="true" />
                Add Conditional Rule
              </DropdownMenuItem>
            </DropdownMenuContent>
          </DropdownMenu>
        )}
      </div>
    )
  }

  const tableRootRef = React.useRef<HTMLDivElement>(null)

  React.useEffect(() => {
    warnIfStackedTableEdgeInset(tableRootRef.current)
  }, [])

  // ─── Render ───────────────────────────────────────────────────────────────
  return (
    <div ref={tableRootRef} className="flex min-w-0 w-full flex-col gap-0">

      <DataTableToolbar
        state={state}
        columns={columns}
        searchable={searchable}
        showQueryControls={showQueryControls}
        renderFilterOptionValue={renderFilterOptionValue}
        toolbarSlot={toolbarSlot}
        toolbarActions={toolbarActions}
        searchAriaLabel="Search table"
        edgeInset={edgeInset}
      />

      {isClient && effectiveHeaderStuck
        ? createPortal(
          <div
            ref={floatingHeaderWrapperRef}
            className="pointer-events-auto"
          >
            <div
              ref={floatingHeaderBoxRef}
              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
                ref={floatingHeaderTranslateRef}
                style={{ transform: `translateX(${-headerScrollLeftRef.current}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}
                        data-dt-col={col.key}
                        style={{ width: colWidths[col.key] ?? col.width ?? 100 }}
                      />
                    ))}
                  </colgroup>
                  <thead className="bg-dt-header-bg">
                    <tr>
                      {displayCols.map((col, colIndex) => {
                        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"
                            data-dt-floating-pin={effectivePins[col.key] || undefined}
                            aria-sort={col.sortable && col.sortKey ? ariaSortAttr(col.sortKey as string) : undefined}
                            // Drag-reorder parity with the inline thead — users
                            // can grab a column from the sticky header too.
                            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={floatingHeaderPinnedStyle(col.key)}
                            className={cn(
                              "group/th relative h-9 align-middle select-none",
                              isControlColumn(col.key)
                                ? cn(CONTROL_COLUMN_PADDING, "text-center")
                                : "px-3 text-start",
                              "text-xs font-medium text-muted-foreground tracking-wide",
                              "bg-dt-header-bg border-b border-border",
                              cellColumnEndBorder(
                                col.key,
                                colIndex,
                                displayCols.length,
                                effectivePins[col.key],
                                showGridlines,
                                lastLeftPinKey,
                                firstRightPinKey,
                                lastRightPinKey,
                              ),
                              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]),
                            )}
                          >
                            {renderHeaderCellInner(col, { tabbable: false })}

                            {/* Resize handle — parity with the inline thead.
                                Same affordance, same cursor, same `startResize`
                                handler (which uses pageX deltas, so it works
                                regardless of which thead the drag began in). */}
                            {isResizable && col.key !== "select" && (
                              // Resize handle: mouse-drag affordance only. Was
                              // `tabIndex={0}` historically, which added one
                              // tabstop per column AND had no `:focus-visible`
                              // ring — together producing the "focus loops
                              // through invisible resize handles" symptom and a
                              // WCAG 2.4.7 violation. Removed from Tab order
                              // (mouse drag still works via `onMouseDown`);
                              // keyboard-driven column resize is a follow-up
                              // (Cmd/Ctrl + Arrow on the column-header sort
                              // button, tracked in the DataTable backlog).
                              // Floating clone stays mouse-only (`tabbable: false`
                              // on header controls) so Tab hits the real thead.
                              <div
                                {...verticalResizeSeparatorAria({
                                  label: `Resize ${resolvedColumnLabel(col)} column`,
                                  valueNow: colWidths[col.key] ?? col.width ?? 100,
                                  valueMin: col.minWidth ?? 60,
                                })}
                                onMouseDown={e => startResize(col.key, e)}
                                className={EDGE_RESIZE_HANDLE_CLASS}
                              />
                            )}
                          </th>
                        )
                      })}
                    </tr>
                  </thead>
                </table>
              </div>
            </div>

            {/*
              The pinned group divider. The clip window is transparent and
              exactly one bar tall, so an outgoing divider slides up behind the
              column header and the incoming real row shows through the space
              it vacates. Nothing here is interactive, and the real divider is
              still in the table for a screen reader to read in order, so the
              clone stays out of the pointer and accessibility trees.
            */}
            {pinnedGroup ? (
              <div
                ref={groupClipRef}
                aria-hidden="true"
                className="overflow-hidden border-x border-b border-border pointer-events-none"
              >
                <div
                  ref={groupSlideRef}
                  data-dt-group-bar=""
                  className={cn(
                    GROUP_BAR_CLASS,
                    "relative w-full",
                    selectable && GROUP_BAR_WITH_SELECT_CLASS,
                  )}
                  style={{ background: pinnedGroupDisplay?.tint }}
                >
                  {groupBarContent(
                    pinnedGroupDisplay?.node,
                    pinnedGroup.rows.length,
                    renderGroupSelect(pinnedGroupDisplay?.label ?? null, pinnedGroup.rows, {
                      interactive: false,
                    }),
                    selectColumnWidth,
                  )}
                  <GroupBarPinSeams
                    rightSeams={rightPinSeams}
                    leftSeams={leftPinSeams}
                  />
                </div>
              </div>
            ) : null}
          </div>,
          document.body,
        )
        : null}

      {/* ── Table grid shell (horizontal scroll). Bulk bar lives in sticky foot
            when `stickyFooter` is set so it sticks with pagination.
            When a footer/bulk stack follows, the shared side border + inset
            move to the wrapper below (`hasBottomStack` doc comment above);
            the shell only owns them when it's the whole card by itself. */}
      <div
        className={cn(
          hasBottomStack && "border-x border-border rounded-lg",
          hasBottomStack && edgeInset && DATA_TABLE_GRID_INSET_CLASS,
        )}
      >
      <div
        className={cn(
          // No `w-full` with `mx-*` inset — that overflows the page scrollport
          // (width 100% + horizontal margins). Flex stretch keeps full width.
          "relative flex min-w-0 flex-col overflow-hidden",
          "border-t border-border",
          hasBottomStack ? "rounded-t-lg" : "border-x border-b rounded-lg",
          !hasBottomStack && edgeInset && DATA_TABLE_GRID_INSET_CLASS,
        )}
      >
      <ScrollRegion
        label="Table data"
        ref={el => {
          tableWrapRef.current = el
          scrollRef.current = el
        }}
        onScroll={e => {
          handleScroll()
          syncFloatingHeaderScroll((e.currentTarget as HTMLDivElement).scrollLeft)
        }}
        className={cn(
          "overflow-x-auto",
          showInShellBulkBar && "border-b border-border",
        )}
      >
        <table
          className="text-sm border-separate border-spacing-0"
          style={{
            tableLayout: "fixed",
            // Natural column sum when wide; fill the scrollport when columns are narrow.
            // Pin gating still uses `totalWidth > clientWidth` (not scrollWidth) so
            // `min(100%)` here does not re-break auto-pin on overflow.
            width: `max(${totalWidth}px, 100%)`,
          }}
        >
          <colgroup>
            {displayCols.map(col => (
              <col
                key={col.key}
                data-dt-col={col.key}
                style={{ width: colWidths[col.key] ?? col.width ?? 100 }}
              />
            ))}
          </colgroup>

          {/* ── Table head ──────────────────────────────────────────────── */}
          <thead
            ref={tableHeadRef}
            // Sticky clone is mouse chrome only (`tabbable: false`). Real
            // thead stays in Tab order. While stuck it is `opacity-0` so the
            // clone can paint on top — but parent opacity hides children, so
            // on *visible* focus / open menu we flip `headerSurfaceActive`,
            // drop the clone, and restore full opacity so the ring + ⋯ show.
            onFocusCapture={e => {
              if (!hasVisibleFocus(e.target)) return
              setHeaderKeyboardActive(true)
              if (headerIsStuck) {
                tableHeadRef.current?.scrollIntoView({ block: "nearest", behavior: "instant" })
              }
            }}
            className={cn(
              "bg-dt-header-bg",
              headerIsStuck && !headerSurfaceActive && "opacity-0",
              // Belt-and-suspenders: restore paint the same frame focus enters,
              // even before React state commits.
              headerIsStuck &&
                "has-[:focus-visible]:!opacity-100 has-[:focus-visible]:relative has-[:focus-visible]:z-[60]",
              headerIsStuck && headerSurfaceActive && "relative z-[60]",
              !showColumnHeaders && "hidden"
            )}
          >
            <tr>
              {displayCols.map((col, colIndex) => {
                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 align-middle select-none",
                      isControlColumn(col.key)
                        ? cn(CONTROL_COLUMN_PADDING, "text-center")
                        : "px-3 text-start",
                      "text-xs font-medium text-muted-foreground tracking-wide",
                      "bg-dt-header-bg border-b border-border",
                      cellColumnEndBorder(
                        col.key,
                        colIndex,
                        displayCols.length,
                        effectivePins[col.key],
                        showGridlines,
                        lastLeftPinKey,
                        firstRightPinKey,
                        lastRightPinKey,
                      ),
                      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])
                    )}
                  >
                    {renderHeaderCellInner(col)}

                    {/* Resize handle — inline-only (configuration-time action,
                        not exposed in the sticky variant). */}
                    {isResizable && col.key !== "select" && (
                      <div
                        {...verticalResizeSeparatorAria({
                          label: `Resize ${resolvedColumnLabel(col)} column`,
                          valueNow: colWidths[col.key] ?? col.width ?? 100,
                          valueMin: col.minWidth ?? 60,
                        })}
                        onMouseDown={e => startResize(col.key, e)}
                        className={EDGE_RESIZE_HANDLE_CLASS}
                      />
                    )}
                  </th>
                )
              })}
            </tr>
          </thead>

          {/* ── Table body ───────────────────────────────────────────────── */}
          <tbody>
            {displayedGroups.map(({ groupKey, groupLabel, groupValue, rows: groupRows }) => {
              const display = groupLabel ? groupDisplay(groupLabel, groupValue) : undefined
              return (
              <React.Fragment key={groupKey ?? "__all__"}>
                {groupLabel && (
                  <tr>
                    {/* The cell carries the tint too: the bar inside it is only
                        as wide as the scrollport, so on a horizontal scroll the
                        cell is what shows past the bar's trailing edge. */}
                    <td
                      colSpan={displayCols.length}
                      data-dt-group-bar=""
                      className="p-0 border-b border-border bg-dt-group-bg"
                      style={{ background: display?.tint }}
                    >
                      <div
                        data-dt-group-header=""
                        data-dt-group-bar=""
                        className={cn(
                          "sticky start-0 z-[25] relative",
                          GROUP_BAR_CLASS,
                          selectable && GROUP_BAR_WITH_SELECT_CLASS,
                          !stickyPinsDisabled && "shadow-[4px_0_8px_-4px_var(--sticky-edge-fade)]",
                        )}
                        style={{
                          width: "var(--dt-scrollport-width, 100%)",
                          background: display?.tint,
                        }}
                      >
                        {groupBarContent(
                          display?.node,
                          groupRows.length,
                          renderGroupSelect(display?.label ?? groupLabel, groupRows),
                          selectColumnWidth,
                        )}
                        <GroupBarPinSeams
                          rightSeams={rightPinSeams}
                          leftSeams={leftPinSeams}
                        />
                      </div>
                    </td>
                  </tr>
                )}
                {groupRows.map((row, rowIndex) => {
                  const rowId = getRowId(row, rowIndex, getRowIdProp)
                  const isSelected = selected.has(rowId)
                  const isOpen = rowsOpenRail && rowId === openRowId
                  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}
                      onClick={rowClickable ? handleRowClick : undefined}
                      data-new={Boolean((row as Record<string, unknown>).isNew) || undefined}
                      // Selection and openness are different facts about a row and
                      // it can hold both, so they get different channels: the tint
                      // stays selection's, the leading bar (drawn by the first
                      // cell) is openness'. `aria-current` carries the same news to
                      // a screen reader, which cannot see either.
                      data-open={isOpen || undefined}
                      aria-current={isOpen || undefined}
                      {...(rowsOpenRail ? railTriggerProps() : {})}
                      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",
                        // Skip layout/paint for offscreen rows (MessageScroller pattern).
                        "[contain-intrinsic-size:auto_2.75rem] [content-visibility:auto]",
                      )}
                    >
                      {displayCols.map((col, colIndex) => {
                        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(
                          `${isControlColumn(col.key) ? CONTROL_COLUMN_PADDING : "px-3"} ${rowPy} align-middle max-w-0`,
                          cellColumnEndBorder(
                            col.key,
                            colIndex,
                            displayCols.length,
                            effectivePins[col.key],
                            showGridlines,
                            lastLeftPinKey,
                            firstRightPinKey,
                            lastRightPinKey,
                          ),
                          "border-b border-border group-last/row:border-b-0",
                          // Open-row bar. A `<tr>` cannot carry a reliable border
                          // under `border-collapse`, so the leading cell draws it.
                          // A shape rather than a fill keeps it legible next to the
                          // selection tint and survives forced-colors, where fills
                          // are replaced by system colours.
                          colIndex === 0 && [
                            "relative",
                            "group-data-[open]/row:before:absolute group-data-[open]/row:before:inset-y-0",
                            "group-data-[open]/row:before:start-0 group-data-[open]/row:before:w-0.5",
                            "group-data-[open]/row:before:bg-dt-row-open-marker",
                          ],
                          isPinned && [
                            "z-20 pinned-cell relative",
                            "bg-dt-row-bg",
                            "group-data-[new]/row:bg-dt-new-row-bg",
                            "group-data-[state=selected]/row:bg-dt-row-selected",
                            "group-hover/row:bg-dt-row-hover",
                            "group-data-[new]/row: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="inline-flex items-center justify-center"
                                  onClick={e => e.stopPropagation()}
                                >
                                  <Checkbox
                                    checked={isSelected}
                                    onCheckedChange={() => toggleRow(rowId)}
                                    aria-label={ariaLabel}
                                    onClick={e => e.stopPropagation()}
                                  />
                                </span>
                              )}
                            </td>
                          )
                        }

                        // When wrap is on, override every common truncation
                        // pattern any cell renderer might use:
                        //   • `.truncate`         → single-line + ellipsis
                        //   • `.line-clamp-N`     → multi-line + ellipsis
                        //   • `.whitespace-nowrap` → forced single line
                        // We also flip the inner wrapper from `overflow-hidden`
                        // to `overflow-visible` so the cell can grow vertically.
                        // `wrap-break-word` breaks long tokens (camelCase IDs, URLs)
                        // that `whitespace-normal` alone would bleed into neighbors.
                        const wrapCellContentClass = "min-w-0 break-words wrap-break-word"
                        const wrapOverride = wrap && cn(
                          wrapCellContentClass,
                          "[&_.truncate]:!whitespace-normal [&_.truncate]:!overflow-visible [&_.truncate]:!text-clip",
                          "[&_.truncate]:break-words [&_.truncate]:wrap-break-word",
                          "[&_[class*=line-clamp-]]:!line-clamp-none",
                          "[&_[class*=line-clamp-]]:break-words [&_[class*=line-clamp-]]:wrap-break-word",
                          "[&_.whitespace-nowrap]:!whitespace-normal",
                        )
                        const innerWrap = wrap
                          ? wrapCellContentClass
                          : cn("min-w-0 overflow-hidden", CELL_CLIP_FOCUS_INSET_CLASS)

                        // Custom cell renderer
                        if (col.cell) {
                          return (
                            <td
                              key={col.key}
                              className={cn(tdBase, wrapOverride)}
                              style={tdStyle}
                            >
                              <div className={innerWrap}>
                                {col.cell(row, {
                                  rowIndex,
                                  selected: isSelected,
                                  onSelect: checked => checked ? setSelected(prev => new Set([...prev, rowId])) : toggleRow(rowId),
                                })}
                              </div>
                            </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", wrapOverride)} style={tdStyle}>
                            <div className={innerWrap}>
                              <span className={wrap ? cn("whitespace-normal", wrapCellContentClass) : "block truncate"} title={!wrap ? rawVal : undefined}>
                                {rawVal}
                              </span>
                            </div>
                          </td>
                        )
                      })}
                    </tr>
                  )
                })}
              </React.Fragment>
              )
            })}

            {isLazyLoading && rows.length > 0 && (
              <tr>
                <td colSpan={displayCols.length} className="border-b border-border px-3 py-6">
                  <output
                    className="flex items-center justify-center gap-2 text-sm text-muted-foreground"
                    aria-live="polite"
                    aria-label={lazyLoadingLabel}
                  >
                    <i className="fa-light fa-loader animate-spin text-sm" aria-hidden="true" />
                    <span>{lazyLoadingLabel}</span>
                  </output>
                </td>
              </tr>
            )}

            {/* 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 className="hover:bg-dt-row-hover transition-colors">
                <td colSpan={displayCols.length} className="p-0 align-middle">
                  <button
                    type="button"
                    className="flex w-full items-center gap-1.5 px-3 py-2.5 text-start text-sm text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
                    aria-label={`Add new ${addRowLabel}`}
                  >
                    <i className="fa-light fa-plus text-xs" aria-hidden="true" />
                    {addRowLabel}
                  </button>
                </td>
              </tr>
            )}
          </tbody>
        </table>
      </ScrollRegion>

      </div>

      {/* Standalone bulk bar (no `stickyFooter` supplied) — a sibling of the
          shell, not a child of it, so `sticky bottom-0` has a real scrollport
          to stick within instead of the shell's own `overflow-hidden`. See
          `showInShellBulkBar`'s doc comment above. Side border + inset live on
          the shared wrapper (see `hasBottomStack`), not here. */}
      {showInShellBulkBar ? (
        <div
          className={cn(
            "z-40 border-b border-border overflow-hidden bg-background",
            hasFooter ? "rounded-none" : "rounded-b-lg",
            reflowZoom ? "relative" : "sticky bottom-0",
          )}
        >
          <BulkSelectionBar
            selected={selected}
            rows={rows}
            onClear={() => setSelected(new Set())}
            actionsSlot={bulkActionsSlot}
            exportShortcut={defaultBulkExportShortcut}
            deleteShortcut={defaultBulkDeleteShortcut}
          />
        </div>
      ) : null}

      {useStickyFootStack ? (
        <div
          className={cn(
            "z-40 border-b border-border rounded-b-lg overflow-hidden bg-background",
            // Match HubTable / Paginated footer: sticky to the page scrollport so
            // bulk actions stay visible with pagination while rows scroll away.
            // Reflow zoom disables sticky (same as PaginationBar hosts).
            reflowZoom ? "relative" : "sticky bottom-0",
          )}
        >
          {anySelected ? (
            <BulkSelectionBar
              selected={selected}
              rows={rows}
              onClear={() => setSelected(new Set())}
              actionsSlot={bulkActionsSlot}
              exportShortcut={defaultBulkExportShortcut}
              deleteShortcut={defaultBulkDeleteShortcut}
            />
          ) : null}
          {stickyFooter}
        </div>
      ) : null}
      </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} />
}