@exxatdesignux/ui 0.2.18 → 0.3.0

package/src/components/table-properties/drawer-button.tsx

@@ -0,0 +1,300 @@
+"use client"
+
+/**
+ * TablePropertiesDrawerButton — reusable Properties button + drawer combo.
+ *
+ * Centralises the "sliders" icon button and the full `TablePropertiesDrawer` that was
+ * previously duplicated per hub (TeamDrawerToolbar, ComplianceDrawerToolbar, …).
+ *
+ * Pass any `useTableState<T>` return object as `state` — the component only reads
+ * display-agnostic fields so it is compatible with any row shape.
+ */
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../ui/tooltip"
+import { Button } from "../ui/button"
+import { TablePropertiesDrawer } from "./drawer"
+import type {
+  ActiveFilter,
+  ConditionalRule,
+  FilterFieldDef,
+  SortRule,
+} from "../../lib/table-properties-types"
+import type { RowHeight } from "../../lib/row-height"
+import type { DataListViewType } from "../../lib/data-list-view"
+import type { DataListDisplayOptions } from "../../lib/data-list-display-options"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// State interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Structural interface over the fields consumed from `useTableState`.
+ * Any `ReturnType<typeof useTableState<T>>` is assignable to this type because:
+ *  - All non-row fields have the same shape regardless of `T`.
+ *  - `rows: T[]` is assignable to `rows: { length: number }` (arrays expose `.length`).
+ */
+export interface TablePropertiesDrawerButtonState {
+  sheetOpen: boolean
+  setSheetOpen: (v: boolean) => void
+  /**
+   * Optional deep-link target consumed by `TablePropertiesDrawer`'s `initialPanel`.
+   * Required only if the hub deep-links into a specific drawer panel (e.g. the
+   * column header's **Add Conditional Rule** sets it to `"conditional-rules"`).
+   * Default state is `null`, which makes the drawer open on its index panel.
+   */
+  sheetInitialPanel?: string | null
+  setSheetInitialPanel?: (v: string | null) => void
+  showGridlines: boolean
+  setShowGridlines: (v: boolean) => void
+  rowHeight: RowHeight
+  setRowHeight: (v: RowHeight) => void
+  activeFilters: ActiveFilter[]
+  addFilter: (fieldKey: string, fromDrawer?: boolean) => void
+  updateFilter: (id: string, patch: Partial<ActiveFilter>) => void
+  removeFilter: (id: string) => void
+  getConnector: (leftFilterId: string) => "and" | "or"
+  toggleConnector: (leftFilterId: string) => void
+  filterBarVisible: boolean
+  setFilterBarVisible: (v: boolean) => void
+  drawerExpandedFilters: Set<string>
+  setDrawerExpandedFilters: React.Dispatch<React.SetStateAction<Set<string>>>
+  /** Only `.length` is read — compatible with any `T[]`. */
+  rows: { length: number }
+  sortRules: SortRule[]
+  setSortRules: (rules: SortRule[]) => void
+  addSortRule: (fieldKey: string) => void
+  removeSortRule: (id: string) => void
+  toggleSortDir: (id: string) => void
+  colOrder: string[]
+  setColOrder: (order: string[]) => void
+  hiddenCols: Set<string>
+  toggleColVisibility: (key: string) => void
+  moveCol: (key: string, dir: "up" | "down") => void
+  groupBy: string | null
+  setGroupBy: (key: string | null) => void
+  sortKey?: string
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Props
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TablePropertiesDrawerButtonProps {
+  /** Pass any `useTableState<T>` return value. */
+  state: TablePropertiesDrawerButtonState
+  totalRows: number
+  filterFields: FilterFieldDef[]
+  /**
+   * Column definitions for the drawer's Sort / Group / Columns panels.
+   * Required — derive from your column defs (`columnsToFieldDefinitions`) so
+   * the drawer never falls back to product-specific defaults.
+   */
+  fieldDefinitions: { key: string; label: string; sortable?: boolean }[]
+  resolveColumnLabel?: (key: string) => string
+  displayOptions: DataListDisplayOptions
+  onDisplayOptionsChange: (patch: Partial<DataListDisplayOptions>) => void
+  conditionalRules: ConditionalRule[]
+  onAddConditionalRule: (rule: Omit<ConditionalRule, "id">) => void
+  onRemoveConditionalRule: (id: string) => void
+  onUpdateConditionalRule: (id: string, patch: Partial<ConditionalRule>) => void
+  /**
+   * Whether pagination is enabled. Defaults to `false`.
+   * Placements passes `true` because it supports server-side pagination.
+   */
+  pagination?: boolean
+  onPaginationChange?: (v: boolean) => void
+  /** View type shown in the drawer header tile grid. */
+  currentView?: DataListViewType
+  onViewChange?: (v: DataListViewType) => void
+  /**
+   * Subset of view types this hub implements. When provided, the drawer's view-type tile grid is
+   * filtered so users cannot select an unsupported view (e.g. List hub never offers Dashboard).
+   */
+  supportedViewTypes?: readonly DataListViewType[]
+  /** Shown below the "Properties" title in the drawer header (e.g. "Team", "Compliance"). */
+  lifecycleTabLabel?: string
+  /**
+   * When the active view is Board and more than one entry is provided, the drawer renders
+   * a selector for which field splits the board into swimlane columns.
+   */
+  boardGroupByColumnOptions?: { key: string; label: string }[]
+  /** Extra controls rendered before the Properties button (e.g. a dashboard-edit button). */
+  extraActions?: React.ReactNode
+  /** Optional custom option renderer for filter values (e.g. status chips). */
+  renderFilterOptionValue?: (fieldKey: string, value: string) => React.ReactNode
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function TablePropertiesDrawerButton({
+  state,
+  totalRows,
+  filterFields,
+  fieldDefinitions,
+  resolveColumnLabel,
+  displayOptions,
+  onDisplayOptionsChange,
+  conditionalRules,
+  onAddConditionalRule,
+  onRemoveConditionalRule,
+  onUpdateConditionalRule,
+  pagination = false,
+  onPaginationChange,
+  currentView,
+  onViewChange,
+  supportedViewTypes,
+  lifecycleTabLabel,
+  boardGroupByColumnOptions,
+  extraActions,
+  renderFilterOptionValue,
+}: TablePropertiesDrawerButtonProps) {
+  // Only destructure the read-only state slices we render directly.
+  // Mutators (addFilter, setSortRules, toggleColVisibility, …) are
+  // intentionally accessed via `stateRef.current.X` so the portaled Sheet
+  // always sees the latest reducers without re-binding event handlers on
+  // every render.
+  const {
+    sheetOpen, setSheetOpen,
+    sheetInitialPanel,
+    setSheetInitialPanel,
+    showGridlines, setShowGridlines,
+    rowHeight, setRowHeight,
+    activeFilters,
+    filterBarVisible,
+    drawerExpandedFilters,
+    rows,
+    sortRules,
+    colOrder,
+    hiddenCols,
+    groupBy,
+    sortKey,
+  } = state
+
+  // Sheet is portaled; keep latest handlers so sort/filter/conditional edits are not lost.
+  // Writes to ref.current MUST happen after commit (not during render) — React 19 +
+  // react-hooks v6 lints `Cannot access refs during render`. Use `useLayoutEffect` so
+  // the ref points at the just-rendered values before any effects fire.
+  const stateRef = React.useRef(state)
+  const ruleHandlersRef = React.useRef({
+    onAddConditionalRule,
+    onRemoveConditionalRule,
+    onUpdateConditionalRule,
+    onDisplayOptionsChange,
+    onPaginationChange,
+  })
+  React.useLayoutEffect(() => {
+    stateRef.current = state
+  })
+  React.useLayoutEffect(() => {
+    ruleHandlersRef.current = {
+      onAddConditionalRule,
+      onRemoveConditionalRule,
+      onUpdateConditionalRule,
+      onDisplayOptionsChange,
+      onPaginationChange,
+    }
+  })
+
+  // Stable callback that defers the ref read to invocation time. Used for
+  // `onDrawerExpandedFiltersChange` which is read-by-reference (not invoked
+  // through an inline arrow), so we wrap it explicitly to avoid reading
+  // `stateRef.current` during render.
+  const onDrawerExpandedFiltersChange = React.useCallback<
+    React.Dispatch<React.SetStateAction<Set<string>>>
+  >((next) => stateRef.current.setDrawerExpandedFilters(next), [])
+
+  return (
+    <>
+      {extraActions}
+
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-sm"
+              aria-label="Properties"
+              onClick={() => {
+                // The toolbar button always opens to the drawer's "main" index
+                // panel — clear any pending deep-link target from a previous
+                // column-menu interaction so this open lands on main.
+                setSheetInitialPanel?.(null)
+                setSheetOpen(true)
+              }}
+              className={cn(
+                sheetOpen
+                  ? "bg-accent text-accent-foreground"
+                  : "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover",
+              )}
+            >
+              <i className="fa-light fa-sliders text-[13px]" aria-hidden="true" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Properties</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+
+      <TablePropertiesDrawer
+        open={sheetOpen}
+        onOpenChange={setSheetOpen}
+        initialPanel={sheetInitialPanel}
+        showGridlines={showGridlines}
+        onShowGridlinesChange={setShowGridlines}
+        rowHeight={rowHeight}
+        onRowHeightChange={setRowHeight}
+        pagination={pagination}
+        onPaginationChange={v => ruleHandlersRef.current.onPaginationChange?.(v)}
+        activeFilters={activeFilters}
+        onAddFilter={fieldKey => stateRef.current.addFilter(fieldKey, true)}
+        onUpdateFilter={(id, patch) => stateRef.current.updateFilter(id, patch)}
+        onRemoveFilter={id => stateRef.current.removeFilter(id)}
+        getFilterConnector={leftId => stateRef.current.getConnector(leftId)}
+        onToggleFilterConnector={leftId => stateRef.current.toggleConnector(leftId)}
+        filterBarVisible={filterBarVisible}
+        onFilterBarVisibleChange={v => stateRef.current.setFilterBarVisible(v)}
+        drawerExpandedFilters={drawerExpandedFilters}
+        onDrawerExpandedFiltersChange={onDrawerExpandedFiltersChange}
+        totalRows={totalRows}
+        filteredRows={rows.length}
+        sortRules={sortRules}
+        onSortRulesChange={rules => stateRef.current.setSortRules(rules)}
+        onAddSortRule={fieldKey => stateRef.current.addSortRule(fieldKey)}
+        onRemoveSortRule={id => stateRef.current.removeSortRule(id)}
+        onToggleSortDir={id => stateRef.current.toggleSortDir(id)}
+        colOrder={colOrder}
+        onColOrderChange={order => stateRef.current.setColOrder(order)}
+        hiddenCols={hiddenCols}
+        onToggleColVisibility={key => stateRef.current.toggleColVisibility(key)}
+        onMoveCol={(key, dir) => stateRef.current.moveCol(key, dir)}
+        groupBy={groupBy}
+        onGroupByChange={key => stateRef.current.setGroupBy(key)}
+        primarySortKey={sortKey}
+        conditionalRules={conditionalRules}
+        onAddConditionalRule={rule => ruleHandlersRef.current.onAddConditionalRule(rule)}
+        onRemoveConditionalRule={id => ruleHandlersRef.current.onRemoveConditionalRule(id)}
+        onUpdateConditionalRule={(id, patch) => ruleHandlersRef.current.onUpdateConditionalRule(id, patch)}
+        filterFields={filterFields}
+        lifecycleTabLabel={lifecycleTabLabel}
+        fieldDefinitions={fieldDefinitions}
+        resolveColumnLabel={resolveColumnLabel}
+        displayOptions={displayOptions}
+        onDisplayOptionsChange={patch => ruleHandlersRef.current.onDisplayOptionsChange(patch)}
+        currentView={currentView}
+        onViewChange={onViewChange}
+        supportedViewTypes={supportedViewTypes}
+        boardGroupByColumnOptions={boardGroupByColumnOptions}
+        renderFilterOptionValue={renderFilterOptionValue}
+      />
+    </>
+  )
+}