@exxatdesignux/ui 0.2.19 → 0.4.0

package/src/globals.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Ambient declarations for `@exxatdesignux/ui`.
+ *
+ * We avoid taking a dependency on `@types/node` (the package is a browser /
+ * RSC library, not a Node API consumer) but a handful of patterns still want
+ * to check `process.env.NODE_ENV` to gate dev-mode `console.warn` calls
+ * (same pattern as React, Radix UI, Chakra UI). Declare just the slice we
+ * touch so TypeScript stays happy without pulling in the whole Node typings.
+ *
+ * Both bundlers (tsup / esbuild, Webpack, Vite, Turbopack) and Next.js's RSC
+ * compiler statically replace `process.env.NODE_ENV` at build time with the
+ * configured environment string (`"development"` / `"production"`), so this
+ * declaration only affects type-checking — not runtime.
+ */
+
+declare const process: {
+  readonly env: {
+    readonly NODE_ENV?: "development" | "production" | "test" | string
+  }
+}

package/src/index.ts

@@ -1,4 +1,57 @@
+// Data table (multi-file primitive)
+// Use subpath imports (`@exxatdesignux/ui/components/data-table/*`) when
+// you only need one file from this group — the barrel pulls the whole
+// DataTable surface in for any consumer of the main `@exxatdesignux/ui`
+// entry.
+export * from "./components/data-table"
+export * from "./components/data-table/types"
+export * from "./components/data-table/use-table-state"
+export * from "./components/data-table/pagination"
+export * from "./components/data-table/filter-date-calendar"
+export * from "./components/data-table/filter-text-value-input"
+
+// Data views (list-page view bodies + binding layer)
+// `HubTable<TRow>` is the binding layer: pass columns + rows + a renderers
+// map, get a complete list-page hub body for every supported view tab.
+// Subpath imports: `@exxatdesignux/ui/components/data-views/<file>` for
+// individual modules.
+export * from "./components/data-views"
+
+// Templates (page-scale compositions: list page, dedicated-search shells, nested secondary panel).
+// Composition-aware shells that mount product-specific chrome (PrimaryPageTemplate,
+// SecondaryPanelHubTemplate, DiscoveryHubTemplate, NewFocusTemplate) stay in the app.
+export * from "./components/templates"
+
+// Table properties (drawer + button + sort/filter/column rows)
+// Sibling to `data-table`; consumes the same `useTableState` row shape.
+// Use the subpath `@exxatdesignux/ui/components/table-properties` for
+// the full barrel, or individual file paths for tree-shakable imports.
+export {
+  TablePropertiesDrawer,
+  TablePropertiesDrawerButton,
+  DrawerFilterCard,
+  DrawerSortCard,
+  ColumnRow,
+  useDraggableList,
+  createListPageEditViewHandler,
+  isDataListSurfaceViewType,
+  type TablePropertiesDrawerProps,
+  type TablePropertiesDrawerButtonProps,
+  type TablePropertiesDrawerButtonState,
+  type DrawerSortCardProps,
+  type OpenTablePropertiesHandle,
+} from "./components/table-properties"
+
+// Shared list-page / data-list lib
+export * from "./lib/list-page-table-properties"
+export * from "./lib/data-list-view"
+export * from "./lib/data-list-view-registry"
+export * from "./lib/data-list-view-surface"
+export * from "./lib/data-list-display-options"
+
 // Components
+export * from "./components/ui/accordion"
+export * from "./components/ui/alert-dialog"
 export * from "./components/ui/avatar"
 export * from "./components/ui/badge"
 export * from "./components/ui/banner"
@@ -11,11 +64,14 @@ export * from "./components/ui/checkbox"
 export * from "./components/ui/coach-mark"
 export * from "./components/ui/collapsible"
 export * from "./components/ui/command"
+export * from "./components/ui/context-menu"
 export * from "./components/ui/date-picker-field"
 export * from "./components/ui/dialog"
 export * from "./components/ui/drag-handle-grip"
 export * from "./components/ui/drawer"
 export * from "./components/ui/dropdown-menu"
+export * from "./components/ui/export-drawer"
+export * from "./components/ui/hover-card"
 export * from "./components/ui/field"
 export * from "./components/ui/form"
 export * from "./components/ui/input-group"
@@ -23,15 +79,20 @@ export * from "./components/ui/input"
 export * from "./components/ui/input-mask"
 export * from "./components/ui/payment-card-fields"
 export * from "./components/ui/kbd"
+export * from "./components/ui/key-metrics"
 export * from "./components/ui/label"
+export * from "./components/ui/list-page-view-frame"
+export * from "./components/ui/page-header"
 export * from "./components/ui/popover"
 export * from "./components/ui/radio-group"
+export * from "./components/ui/scroll-area"
 export * from "./components/ui/select"
 export * from "./components/ui/selection-tile-grid"
 export * from "./components/ui/separator"
 export * from "./components/ui/sheet"
 export * from "./components/ui/sidebar"
 export * from "./components/ui/skeleton"
+export * from "./components/ui/slider"
 export * from "./components/ui/sonner"
 export * from "./components/ui/status-badge"
 export * from "./components/ui/table"
@@ -51,6 +112,12 @@ export * from "./hooks/use-mobile"
 export * from "./hooks/use-mod-key-label"
 
 // Utilities
+export * from "./lib/conditional-rule-match"
+export * from "./lib/date-filter"
+export * from "./lib/dev-log"
 export * from "./lib/dropdown-menu-surface"
+export * from "./lib/editable-target"
+export * from "./lib/raf-throttle"
+export * from "./lib/row-height"
+export * from "./lib/table-properties-types"
 export * from "./lib/utils"
-export * from "./lib/date-filter"

package/src/lib/conditional-rule-match.ts

@@ -0,0 +1,119 @@
+import type {
+  ConditionalRule,
+  FilterTextMask,
+} from "./table-properties-types"
+
+/**
+ * Conditional-formatting matchers shared by `DataTable` cells,
+ * `data-row-list` rows, and board card backgrounds. Keeping the logic
+ * here ensures the table grid and the list / board derivatives all
+ * paint the same row with the same rule (no UI drift between views).
+ *
+ * `columns` is optional and only used when the consumer needs to:
+ *   - read from a different row key than the rule's `fieldKey`
+ *     (`sortKey`-aliased columns), or
+ *   - apply a `textMask` (phone / zip) so "contains 555" matches the
+ *     raw digits of "(415) 555-0100".
+ */
+
+export type ConditionalColumnHint = {
+  key: string
+  sortKey?: string
+  filter?: { type?: string; textMask?: FilterTextMask }
+}
+
+function rowValueForRule<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): string {
+  const col = columns?.find((c) => c.key === rule.fieldKey)
+  const dataKey = (col?.sortKey ?? rule.fieldKey) as keyof T
+  return String(row[dataKey] ?? "")
+}
+
+function ruleHasActiveValues(
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (rule.values.length === 0) return false
+  const col = columns?.find((c) => c.key === rule.fieldKey)
+  if (col?.filter?.type === "text")
+    return (rule.values[0] ?? "").trim().length > 0
+  return true
+}
+
+function conditionalTextMatches(
+  cellVal: string,
+  needle: string,
+  op: "contains" | "not_contains",
+  textMask: FilterTextMask | undefined,
+) {
+  const v = cellVal.trim()
+  const n = needle.trim()
+  if (!n) return op === "not_contains"
+  if (textMask === "phone" || textMask === "zip") {
+    const nd = n.replace(/\D/g, "")
+    const hay = v.replace(/\D/g, "")
+    if (!nd) return op === "not_contains"
+    const hit = hay.includes(nd)
+    return op === "contains" ? hit : !hit
+  }
+  const hit = v.toLowerCase().includes(n.toLowerCase())
+  return op === "contains" ? hit : !hit
+}
+
+/** Whether a conditional rule matches a row (same logic as DataTable cells). */
+export function conditionalRuleMatchesRow<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (!ruleHasActiveValues(rule, columns)) return false
+  const v = rowValueForRule(row, rule, columns).trim()
+  const col = columns?.find((c) => c.key === rule.fieldKey)
+  const textMask =
+    col?.filter?.type === "text" ? col.filter.textMask : undefined
+  switch (rule.operator) {
+    case "is":
+      return rule.values.includes(v)
+    case "is_not":
+      return !rule.values.includes(v)
+    case "contains":
+      return rule.values.some((val) =>
+        conditionalTextMatches(v, val, "contains", textMask),
+      )
+    case "not_contains":
+      return !rule.values.some((val) =>
+        conditionalTextMatches(v, val, "contains", textMask),
+      )
+    default:
+      return false
+  }
+}
+
+/** First matching conditional rule background for a row (list/board row tint). */
+export function getConditionalRowBackground<T extends Record<string, unknown>>(
+  row: T,
+  rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
+): string | undefined {
+  if (!rules?.length) return undefined
+  for (const rule of rules) {
+    if (conditionalRuleMatchesRow(row, rule, columns)) return rule.bgColor
+  }
+  return undefined
+}
+
+/** Background for one table cell from conditional rules on that column. */
+export function getConditionalCellBackground<T extends Record<string, unknown>>(
+  row: T,
+  colKey: string,
+  rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
+): string | undefined {
+  if (!rules?.length) return undefined
+  const rule = rules.find((r) => r.fieldKey === colKey)
+  if (!rule || !conditionalRuleMatchesRow(row, rule, columns)) return undefined
+  return rule.bgColor
+}

package/src/lib/data-list-display-options.ts

@@ -0,0 +1,35 @@
+/**
+ * Display options for Data list (table / board / etc.) — shared across view types
+ * so hide/show preferences persist when switching views.
+ */
+
+export type BoardLineCount = 1 | 2 | 3
+
+export interface DataListDisplayOptions {
+  /**
+   * Board swimlanes: dataset field (table column key) used to split cards into columns.
+   * Each hub passes allowed keys via `TablePropertiesDrawer` `boardGroupByColumnOptions`.
+   */
+  boardGroupByColumnKey: string
+  /** Max lines for primary text blocks on board cards */
+  boardLineCount: BoardLineCount
+  /** Page title block (Placements + subtitle) */
+  showViewTitle: boolean
+  /** Board: phase column titles + descriptions. Table: column header row. */
+  showColumnLabels: boolean
+  /** Board: “N cards” under each phase column */
+  showBoardColumnCounts: boolean
+  boardNewCardAbove: boolean
+  /** Toolbar search control (table view) */
+  showToolbarSearch: boolean
+}
+
+export const DEFAULT_DATA_LIST_DISPLAY_OPTIONS: DataListDisplayOptions = {
+  boardGroupByColumnKey: "topic",
+  boardLineCount: 2,
+  showViewTitle: true,
+  showColumnLabels: true,
+  showBoardColumnCounts: true,
+  boardNewCardAbove: true,
+  showToolbarSearch: true,
+}

package/src/lib/data-list-view-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * Central registry for list-page view types — labels, render kinds, and hub chrome rules.
+ *
+ * **Add a new view once here** (plus a body in `components/data-views/`). Hubs declare
+ * `supportedViewTypes` on `ListPageTemplate`; table components branch with
+ * `getDataListViewRenderKind` + `ListPageConnectedViewBody` (never a dashboard fallback).
+ *
+ * @see `docs/data-views-pattern.md` — "View registry and connected bodies"
+ */
+
+import {
+  DATA_LIST_VIEW_TILES,
+  type DataListViewType,
+  dataListViewAddShortcut,
+  dataListViewIcon,
+  dataListViewLabel,
+} from "./data-list-view"
+import {
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+} from "./data-list-view-surface"
+
+export interface DataListViewDefinition {
+  value: DataListViewType
+  label: string
+  icon: string
+  renderKind: DataListViewRenderKind
+  /** `ListPageTemplate` metrics slot above the views toolbar. */
+  hubMetricsStrip: boolean
+}
+
+const DEFINITIONS: DataListViewDefinition[] = DATA_LIST_VIEW_TILES.map(tile => {
+  const renderKind = getDataListViewRenderKind(tile.value)
+  const hubMetricsStrip = renderKind !== "calendar-with-toolbar" && renderKind !== "dashboard-with-toolbar"
+  return {
+    value: tile.value,
+    label: tile.label,
+    icon: tile.icon,
+    renderKind,
+    hubMetricsStrip,
+  }
+})
+
+const BY_VALUE = new Map<DataListViewType, DataListViewDefinition>(
+  DEFINITIONS.map(d => [d.value, d]),
+)
+
+export const DATA_LIST_VIEW_REGISTRY: readonly DataListViewDefinition[] = DEFINITIONS
+
+export function dataListViewDefinition(view: DataListViewType): DataListViewDefinition {
+  const def = BY_VALUE.get(view)
+  if (!def) {
+    throw new Error(`Unknown DataListViewType: ${view}`)
+  }
+  return def
+}
+
+/** `ListPageTemplate` hub KPI strip — false for calendar and dashboard (inline KPIs). */
+export function showsListPageHubMetricsStrip(view: DataListViewType): boolean {
+  return dataListViewDefinition(view).hubMetricsStrip
+}
+
+/** Tiles for Add view + Properties when a hub only supports a subset of views. */
+export function dataListViewTilesForHub(supported: readonly DataListViewType[]) {
+  const allowed = new Set(supported)
+  return DATA_LIST_VIEW_REGISTRY.filter(d => allowed.has(d.value)).map(d => ({
+    type: d.value,
+    label: d.label,
+    icon: d.icon,
+  }))
+}
+
+/** `SelectionTileGrid` options for Properties when a hub supports a subset of views. */
+export function dataListViewSelectionTilesForHub(supported: readonly DataListViewType[]) {
+  return dataListViewTilesForHub(supported).map(t => ({
+    value: t.type,
+    label: t.label,
+    icon: t.icon,
+  }))
+}
+
+/** View types that expose Table Properties (all registered `DataListViewType` values). */
+export const DATA_LIST_SURFACE_VIEW_TYPES: ReadonlySet<DataListViewType> = new Set(
+  DATA_LIST_VIEW_REGISTRY.map(d => d.value),
+)
+
+export function isDataListSurfaceViewType(viewType: string): viewType is DataListViewType {
+  return DATA_LIST_SURFACE_VIEW_TYPES.has(viewType as DataListViewType)
+}
+
+export function isDataListViewTypeSupported(
+  view: DataListViewType,
+  supported: readonly DataListViewType[],
+): boolean {
+  return supported.includes(view)
+}
+
+export {
+  dataListViewAddShortcut,
+  dataListViewIcon,
+  dataListViewLabel,
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+}

package/src/lib/data-list-view-surface.ts

@@ -0,0 +1,83 @@
+/**
+ * Maps `DataListViewType` to the UI surface pattern for list pages.
+ *
+ * **Data:** One `useTableState(fullRows, columns, …)` per tab; **filtered/sorted rows**
+ * (`tableState.rows`) are the single source of truth for List, Board, and Dashboard.
+ * Table view renders the same state via `DataTable`.
+ *
+ * | View        | Surface |
+ * |------------|---------|
+ * | `table`    | `DataTable` |
+ * | `list`     | `DataTableToolbar` + list layout |
+ * | `board`    | `DataTableToolbar` + board / kanban |
+ * | `dashboard`| `DataTableToolbar` + KPI (`KeyMetrics`) + optional charts (`ChartCard`, Recharts, etc.) |
+ * | `calendar` | `DataTableToolbar` + `ListPageCalendarView` (month grid + day detail) |
+ * | `folder`   | `DataTableToolbar` + icon grid (macOS-Finder-style) |
+ * | `panel`    | `DataTableToolbar` + resizable split (list / tree column + detail inspector) |
+ */
+
+import type { DataListViewType } from "./data-list-view"
+
+export { showsListPageHubMetricsStrip } from "./data-list-view-registry"
+
+/** What to render for the active view tab (routing / branching). */
+export type DataListViewRenderKind =
+  | "data-table"
+  | "list-with-toolbar"
+  | "board-with-toolbar"
+  | "dashboard-with-toolbar"
+  | "calendar-with-toolbar"
+  | "folder-with-toolbar"
+  | "panel-with-toolbar"
+  | "tree-panel-with-toolbar"
+
+/**
+ * Stable classification for switch/if chains. **Every** `DataListViewType` maps to exactly one kind.
+ * Use this so `dashboard` is never mistaken for `board` (a common bug when only `list` is special-cased).
+ */
+export function getDataListViewRenderKind(view: DataListViewType): DataListViewRenderKind {
+  switch (view) {
+    case "table":
+      return "data-table"
+    case "list":
+      return "list-with-toolbar"
+    case "board":
+      return "board-with-toolbar"
+    case "dashboard":
+      return "dashboard-with-toolbar"
+    case "calendar":
+      return "calendar-with-toolbar"
+    case "folder":
+      return "folder-with-toolbar"
+    case "panel":
+      return "panel-with-toolbar"
+    case "tree-panel":
+      return "tree-panel-with-toolbar"
+    default: {
+      const _x: never = view
+      return _x
+    }
+  }
+}
+
+export function usesDataTableComponent(view: DataListViewType): boolean {
+  return view === "table"
+}
+
+/** KPI band + optional charts — not the kanban board. */
+export function usesDashboardSurface(view: DataListViewType): boolean {
+  return view === "dashboard"
+}
+
+/** Shared toolbar (search, filters, properties); body differs by view. */
+export function usesToolbarWithFilteredRows(view: DataListViewType): boolean {
+  return (
+    view === "list" ||
+    view === "board" ||
+    view === "dashboard" ||
+    view === "calendar" ||
+    view === "folder" ||
+    view === "panel" ||
+    view === "tree-panel"
+  )
+}

package/src/lib/data-list-view.ts

@@ -0,0 +1,47 @@
+/**
+ * Data list “view type” — shared by Properties drawer, ListPageTemplate tabs, and client state.
+ *
+ * **Single source of truth** for view labels/icons: use `DATA_LIST_VIEW_TILES` and
+ * `dataListViewLabel` / `dataListViewIcon` on every page so Table / List / Board / Dashboard
+ * stay consistent and stay wired to the same `useTableState` dataset (see `docs/data-views-pattern.md`).
+ */
+export type DataListViewType =
+  | "table"
+  | "list"
+  | "board"
+  | "dashboard"
+  | "calendar"
+  | "folder"
+  | "panel"
+  | "tree-panel"
+
+export const DATA_LIST_VIEW_TILES: readonly {
+  value: DataListViewType
+  label: string
+  icon: string
+}[] = [
+  { value: "table",     icon: "fa-table",         label: "Table view" },
+  { value: "list",      icon: "fa-list",          label: "List view" },
+  { value: "board",     icon: "fa-table-columns", label: "Board view" },
+  { value: "dashboard", icon: "fa-chart-mixed",   label: "Dashboard view" },
+  { value: "calendar",  icon: "fa-calendar-days", label: "Calendar view" },
+  { value: "folder",    icon: "fa-grid-2",        label: "Folder view" },
+  { value: "panel",      icon: "fa-sidebar",      label: "List & details" },
+  { value: "tree-panel", icon: "fa-sitemap",      label: "Tree & details" },
+]
+
+/** User-facing name for tabs, Properties summary rows, and tooltips (not entity-specific). */
+export function dataListViewLabel(view: DataListViewType): string {
+  return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.label ?? view
+}
+
+/** Font Awesome icon class (no prefix) for tab / toolbar state when view changes. */
+export function dataListViewIcon(view: DataListViewType): string {
+  return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.icon ?? "fa-table"
+}
+
+/** Add-view menu hint + `<Shortcut>` keys (1–9). Skipped in inputs via `useShortcut`. */
+export function dataListViewAddShortcut(index: number): string | undefined {
+  if (index < 0 || index > 8) return undefined
+  return String(index + 1)
+}

package/src/lib/dev-log.ts

@@ -0,0 +1,10 @@
+/**
+ * Logs only in development. Use for mock flows (export, submit) instead of
+ * raw `console.log`. Bundlers replace `process.env.NODE_ENV` at build time,
+ * so the call site disappears entirely in production bundles.
+ */
+export function devLog(...args: unknown[]): void {
+  if (process.env.NODE_ENV === "development") {
+    console.log(...args)
+  }
+}

package/src/lib/editable-target.ts

@@ -0,0 +1,20 @@
+/**
+ * True when focus is in a field where global shortcuts should not fire.
+ *
+ * Mirrors the same skip logic baked into Radix `useShortcut` so global
+ * hotkey handlers (export ⌘⇧E, rename F2, etc.) don't steal keystrokes
+ * that the user clearly intends for the input. Covers native form
+ * fields and any element marked `contenteditable="true"` (richtext
+ * editors, comment composers).
+ */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null
+  if (!el) return false
+  if (
+    el instanceof HTMLInputElement ||
+    el instanceof HTMLTextAreaElement ||
+    el instanceof HTMLSelectElement
+  )
+    return true
+  return el.getAttribute?.("contenteditable") === "true"
+}

package/src/lib/list-page-table-properties.ts

@@ -0,0 +1,48 @@
+/**
+ * Connects ListPageTemplate “View → Edit” to a surface that hosts TablePropertiesDrawer
+ * (PlacementsTable, TeamTable, ComplianceTable, …). Import from `@/components/table-properties`
+ * or use here — see `createListPageEditViewHandler`.
+ *
+ * View **labels** for tabs and Properties are centralized in `@/lib/data-list-view`
+ * (`DATA_LIST_VIEW_TILES`, `dataListViewLabel`, `dataListViewIcon`).
+ */
+
+import * as React from "react"
+
+import { dataListViewIcon, type DataListViewType } from "./data-list-view"
+import { isDataListSurfaceViewType } from "./data-list-view-registry"
+
+export { isDataListSurfaceViewType }
+
+/** Minimal ref API any list/table surface exposes for the shared Properties drawer. */
+export interface OpenTablePropertiesHandle {
+  openPropertiesDrawer: () => void
+}
+
+export interface CreateListPageEditViewHandlerOptions {
+  /** Delay before opening Properties after switching to table (ms). Default 160. */
+  switchDelayMs?: number
+}
+
+/**
+ * Returns `ListPageTemplate`’s `onEditView` handler: optionally coerces the tab to `table`
+ * when the view type is unknown, then calls `ref.current.openPropertiesDrawer()`.
+ */
+export function createListPageEditViewHandler(
+  tableRef: React.RefObject<OpenTablePropertiesHandle | null>,
+  options?: CreateListPageEditViewHandlerOptions
+) {
+  const delay = options?.switchDelayMs ?? 160
+  return (
+    tab: { viewType: string },
+    { updateTab }: { updateTab: (patch: { viewType?: DataListViewType; icon?: string }) => void }
+  ) => {
+    const mustSwitchToTableSurface = !isDataListSurfaceViewType(tab.viewType)
+    if (mustSwitchToTableSurface) {
+      updateTab({ viewType: "table", icon: dataListViewIcon("table") })
+    }
+    window.setTimeout(() => {
+      tableRef.current?.openPropertiesDrawer()
+    }, mustSwitchToTableSurface ? delay : 0)
+  }
+}

package/src/lib/raf-throttle.ts

@@ -0,0 +1,45 @@
+/**
+ * Coalesce many calls to `fn` into one per animation frame.
+ *
+ * Use for high-frequency layout-reading event handlers (scroll, resize,
+ * visualViewport, ResizeObserver) where the work must happen in a frame but
+ * doing it on every event call (60+/s for resize, hundreds/s for capture
+ * scrolls) wastes layout/paint cycles. The returned function exposes
+ * `.cancel()` so effect cleanup can drop a pending frame.
+ *
+ * Pattern:
+ *   const apply = () => { ...layout reads + setState... }
+ *   const scheduled = rafThrottle(apply)
+ *   window.addEventListener("scroll", scheduled, { passive: true, capture: true })
+ *   return () => {
+ *     scheduled.cancel()
+ *     window.removeEventListener("scroll", scheduled, { capture: true })
+ *   }
+ */
+export function rafThrottle<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+): ((...args: TArgs) => void) & { cancel: () => void } {
+  let rafId = 0
+  let lastArgs: TArgs | null = null
+
+  const scheduled = ((...args: TArgs) => {
+    lastArgs = args
+    if (rafId !== 0) return
+    rafId = requestAnimationFrame(() => {
+      rafId = 0
+      const a = lastArgs
+      lastArgs = null
+      if (a) fn(...a)
+    })
+  }) as ((...args: TArgs) => void) & { cancel: () => void }
+
+  scheduled.cancel = () => {
+    if (rafId !== 0) {
+      cancelAnimationFrame(rafId)
+      rafId = 0
+    }
+    lastArgs = null
+  }
+
+  return scheduled
+}

package/src/lib/row-height.ts

@@ -0,0 +1,19 @@
+/**
+ * Table row density — shared by Properties drawer tiles and useTableState.
+ *
+ * Three steps modelled after Linear / Notion / Airtable density toggles.
+ * `default` is the design-system baseline (`h-9` rows, `text-sm`); the
+ * other two scale the row height + vertical padding without changing the
+ * font size, so dense tables stay legible.
+ */
+export type RowHeight = "compact" | "default" | "comfortable"
+
+export const ROW_HEIGHT_TILES: readonly {
+  value: RowHeight
+  label: string
+  icon: string
+}[] = [
+  { value: "compact",     label: "Compact",     icon: "fa-down-to-line"   },
+  { value: "default",     label: "Default",     icon: "fa-arrows-up-down" },
+  { value: "comfortable", label: "Comfortable", icon: "fa-up-to-line"     },
+]