@coreui/data-grid 0.1.0-rc.0

package/src/types.ts

@@ -0,0 +1,334 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid types.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import type {
+ Column, ColumnFiltersState, ColumnOrderState, ColumnPinningState, ColumnSizingState, PaginationState,
+ RowSelectionState, SortingState, Table, VisibilityState
+} from '@tanstack/table-core'
+import type { CsvDownloadOptions } from './util/csv'
+
+export type {
+  Column,
+  ColumnFiltersState,
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  PaginationState,
+  RowSelectionState,
+  SortingState,
+  Table,
+  VisibilityState
+} from '@tanstack/table-core'
+
+export type DataGridItem = Record<string, unknown>
+
+export interface DataGridColumnFilterContext {
+  column: Column<DataGridItem, unknown>
+  table: Table<DataGridItem>
+  labels: DataGridLabels
+}
+
+export type DataGridColumnFilterFactory = (context: DataGridColumnFilterContext) => DataGridSlot
+
+export type DataGridFilterType = 'text' | 'number' | 'date' | 'select'
+
+export type DataGridFilterOperator =
+  | 'contains'
+  | 'notContains'
+  | 'equals'
+  | 'notEquals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'blank'
+  | 'notBlank'
+  | 'greaterThan'
+  | 'greaterThanOrEqual'
+  | 'lessThan'
+  | 'lessThanOrEqual'
+  | 'between'
+
+export interface DataGridFilterCondition {
+  operator: DataGridFilterOperator
+  value?: unknown
+  // 'between' upper bound.
+  value2?: unknown
+}
+
+// The shape carried inside the TanStack columnFilters state: a plain string
+// stays "text contains" (the quick input), the menu writes the structured
+// forms.
+export type DataGridColumnFilterValue =
+  | string
+  | { conditions: DataGridFilterCondition[]; join: 'and' | 'or' }
+  | { operator: 'in'; value: unknown[] }
+
+export type DataGridEditorType = 'text' | 'number' | 'select'
+
+export interface DataGridEditableOptions {
+  type?: DataGridEditorType
+  // number editor bounds/step.
+  min?: number
+  max?: number
+  step?: number
+  // select editor options: primitives or explicit label/value pairs.
+  options?: Array<string | number | { label: string; value: unknown }>
+}
+
+export interface DataGridEditorContext {
+  item: DataGridItem
+  column: DataGridColumn
+  value: unknown
+  commit: (value: unknown) => void
+  cancel: () => void
+  labels: DataGridLabels
+}
+
+// The editor contract. Inline editors render inside the cell; popup: true
+// renders into an overlay anchored to the cell (rich editors whose UI extends
+// beyond the cell - date pickers, autocompletes, multi-selects). getValue
+// feeds Enter/Tab/blur commits; contains() extends the edit scope to overlays
+// portaled outside the editor element.
+export interface DataGridEditor {
+  element: HTMLElement
+  contains?: (target: Node) => boolean
+  dispose?: () => void
+  focus?: () => void
+  getValue?: () => unknown
+  popup?: boolean
+}
+
+export type DataGridEditorFactory = (context: DataGridEditorContext) => DataGridEditor
+
+// The editCommit payload. The grid never mutates items - the app applies the
+// change and stays the single source of truth.
+export interface DataGridEditCommitEvent {
+  item: DataGridItem
+  columnId: string
+  value: unknown
+  previousValue: unknown
+}
+
+export interface DataGridColumn {
+  key: string
+  editable?: boolean | DataGridEditableOptions
+  editor?: DataGridEditorFactory
+  editValidate?: (value: unknown, item: DataGridItem) => true | string
+  filter?: DataGridColumnFilterFactory
+  filterable?: boolean
+  filterFn?: (value: unknown, filterValue: unknown, item: DataGridItem) => boolean
+  filterType?: DataGridFilterType
+  formatter?: (value: unknown, item: DataGridItem) => string
+  hideable?: boolean
+  label?: string
+  movable?: boolean
+  render?: (item: DataGridItem, index: number) => Node | string
+  resizable?: boolean
+  sortable?: boolean
+  style?: Partial<CSSStyleDeclaration>
+  width?: number
+}
+
+export interface DataGridMenuAction {
+  key: string
+  label: string
+  disabled?: boolean
+  group?: string
+  icon?: string
+  run: () => void
+}
+
+export interface DataGridColumnMenuContext {
+  column: DataGridColumn
+  defaultActions: DataGridMenuAction[]
+}
+
+export type DataGridColumnMenuBuilder = (context: DataGridColumnMenuContext) => DataGridMenuAction[]
+
+export interface DataGridLabels {
+  addCondition: string
+  applyFilter: string
+  clearFilter: string
+  clearSort: string
+  columnMenu: string
+  filterAction: string
+  filterColumn: string
+  firstPage: string
+  globalFilterLabel: string
+  globalFilterPlaceholder: string
+  hideColumn: string
+  itemsInfo: string
+  joinAnd: string
+  joinOr: string
+  lastPage: string
+  loadError: string
+  loading: string
+  moveLeft: string
+  moveRight: string
+  nextPage: string
+  operatorBetween: string
+  operatorBlank: string
+  operatorContains: string
+  operatorEndsWith: string
+  operatorEquals: string
+  operatorGreaterThan: string
+  operatorGreaterThanOrEqual: string
+  operatorLessThan: string
+  operatorLessThanOrEqual: string
+  operatorNotBlank: string
+  operatorNotContains: string
+  operatorNotEquals: string
+  operatorStartsWith: string
+  pageSizeLabel: string
+  paginationLabel: string
+  pinLeft: string
+  pinRight: string
+  previousPage: string
+  redoneAnnouncement: string
+  resetColumns: string
+  resultsAnnouncement: string
+  searchValues: string
+  selectAllRows: string
+  selectAllValues: string
+  selectRow: string
+  showAllColumns: string
+  sortAscending: string
+  sortDescending: string
+  toolbarColumns: string
+  toolbarExport: string
+  toolbarRedo: string
+  toolbarUndo: string
+  undoneAnnouncement: string
+  unpin: string
+}
+
+export interface DataGridColumnSizingOptions {
+  mode?: 'onChange' | 'onEnd'
+}
+
+export interface DataGridSlotContext {
+  table: Table<DataGridItem>
+  labels: DataGridLabels
+}
+
+export interface DataGridSlot {
+  element: HTMLElement
+  update?: () => void
+  dispose?: () => void
+}
+
+export type DataGridSlotFactory = (context: DataGridSlotContext) => DataGridSlot
+
+export interface DataGridSlots {
+  toolbar: DataGridSlotFactory
+  pagination: DataGridSlotFactory
+  empty: DataGridSlotFactory
+}
+
+export interface DataGridToolbarOptions {
+  columns?: boolean
+  export?: boolean | CsvDownloadOptions
+  history?: boolean
+  search?: boolean
+}
+
+export interface DataGridSortingOptions {
+  multiple?: boolean
+  resetable?: boolean
+}
+
+export type DataGridSorterVisibility = 'always' | 'hover' | false
+
+export interface DataGridRowSelectionOptions {
+  selectAll?: boolean
+}
+
+export interface DataGridPaginationInfoState {
+  pageCount: number
+  pageIndex: number
+  pageSize: number
+  totalRows: number
+}
+
+export interface DataGridPaginationOptions {
+  info?: boolean | ((state: DataGridPaginationInfoState) => string)
+  pageSize?: number
+  pageSizeOptions?: number[]
+  position?: 'top' | 'bottom' | 'both'
+}
+
+// The serializable grid state snapshot: every user-adjustable TanStack slice.
+// getState() returns it, restoreState() applies it, and `stateKey` persists
+// it to localStorage (scroll position and edit drafts are not state).
+export interface DataGridState {
+  columnFilters: ColumnFiltersState
+  columnOrder: ColumnOrderState
+  columnPinning: ColumnPinningState
+  columnSizing: ColumnSizingState
+  columnVisibility: VisibilityState
+  globalFilter: string
+  pagination: PaginationState
+  rowSelection: RowSelectionState
+  sorting: SortingState
+}
+
+export interface DataGridDataRequest {
+  columnFilters: ColumnFiltersState
+  globalFilter: string
+  pagination: PaginationState
+  sorting: SortingState
+}
+
+export interface DataGridDataResponse {
+  items: DataGridItem[]
+  totalRows: number
+}
+
+export interface DataGridOptions {
+  cellNavigation: boolean
+  columnFilters: boolean
+  columnMenu: boolean | DataGridColumnMenuBuilder
+  columnMenuIcon: string
+  columnOrder: boolean | ColumnOrderState
+  columnPinning: boolean | ColumnPinningState
+  columnSizing: boolean | DataGridColumnSizingOptions
+  columnVisibility: boolean | VisibilityState
+  columns: DataGridColumn[]
+  dataProvider: ((request: DataGridDataRequest) => Promise<DataGridDataResponse>) | null
+  editing: boolean
+  empty: string | (() => Node | string)
+  filterIcon: string
+  globalFilter: boolean
+  hideColumnIcon: string
+  history: boolean
+  itemKey: ((item: DataGridItem, index: number) => string) | null
+  items: DataGridItem[]
+  labels: Partial<DataGridLabels>
+  moveLeftIcon: string
+  moveRightIcon: string
+  overscan: number
+  pagination: boolean | DataGridPaginationOptions
+  pinLeftIcon: string
+  pinRightIcon: string
+  rowHeight: number
+  rowSelection: boolean | DataGridRowSelectionOptions
+  sanitize: boolean
+  sanitizeFn: ((html: string) => string) | null
+  slots: Partial<DataGridSlots>
+  sortAscendingIcon: string
+  sortDescendingIcon: string
+  sortNeutralIcon: string
+  sorterVisibility: DataGridSorterVisibility
+  sorting: boolean | DataGridSortingOptions
+  stateKey: string | null
+  toolbar: boolean | DataGridToolbarOptions
+  toolbarColumnsIcon: string
+  toolbarExportIcon: string
+  toolbarRedoIcon: string
+  toolbarUndoIcon: string
+  unpinIcon: string
+  virtualization: boolean
+}

package/src/ui/body.ts

@@ -0,0 +1,348 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid ui/body.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import type { Row } from '@tanstack/table-core'
+import type { GridVirtualizerInstance } from '../engine/virtualizer'
+import type { DataGridColumn, DataGridItem, DataGridLabels } from '../types'
+import { applyPinnedCell, type GridPinning } from './pinning'
+
+const CLASS_NAME_EMPTY = 'data-grid-empty'
+const FOCUSABLE_SELECTOR = 'a[href], button, input, select, textarea, [tabindex]'
+const CLASS_NAME_ROW_ODD = 'data-grid-row-odd'
+const CLASS_NAME_ROW_SELECTED = 'table-active'
+const CLASS_NAME_SELECT_CELL = 'data-grid-select-cell'
+const CLASS_NAME_SPACER = 'data-grid-spacer'
+
+export interface GridBodyContext {
+  // With cellNavigation on, rows/cells carry grid roles, every cell (and the
+  // interactive content inside it) drops out of the tab order, and cells are
+  // addressable by data-coreui-column - the roving tabindex pass in the grid
+  // root owns which single cell is tabbable.
+  cellNavigation: boolean
+  headerRowCount: number
+  labels: DataGridLabels
+  getDataVersion: () => number
+  // Inline editing: the cell being edited (keyed by rowId + columnId, NOT
+  // index - recycling changes indexes) renders the editor element instead of
+  // its content until commit/cancel. Null when editing is off or idle.
+  getEditingCell: () => { rowId: string; columnId: string } | null
+  getEditorElement: () => HTMLElement | null
+  getPinning: () => GridPinning | null
+  // Absolute index of the page's first row (pagination mode), else 0 - keeps
+  // aria-rowindex absolute like aria-rowcount.
+  getRowIndexOffset: () => number
+  getRows: () => Array<Row<DataGridItem>>
+  // Visible leaf columns in table order (pinning + columnOrder + visibility).
+  getVisibleColumns: () => DataGridColumn[]
+  getVirtualizer: () => GridVirtualizerInstance | null
+  renderEmpty: () => Node | string
+  // Guards every string injected via innerHTML (render results, empty state).
+  sanitizeContent: (html: string) => string
+  selection: boolean
+}
+
+export interface GridBody {
+  element: HTMLTableSectionElement
+  update: () => void
+}
+
+const setCellContent = (
+  cellElement: HTMLTableCellElement,
+  content: Node | string,
+  sanitizeContent: (html: string) => string
+): void => {
+  if (typeof content === 'string') {
+    cellElement.innerHTML = sanitizeContent(content)
+    return
+  }
+
+  // Re-inserting the same node detaches it (losing focus/selection in a custom
+  // empty slot); skip when it is already the sole child.
+  if (cellElement.childNodes.length === 1 && cellElement.firstChild === content) {
+    return
+  }
+
+  cellElement.replaceChildren(content)
+}
+
+export const createBody = (context: GridBodyContext): GridBody => {
+  const element = document.createElement('tbody')
+
+  // Snapshot of the current layout, refreshed once per update() — cells are
+  // rebuilt (not recycled) when the visible column set or order changes.
+  let currentColumns: DataGridColumn[] = context.getVisibleColumns()
+  let layoutSignature = currentColumns.map(column => column.key).join('|')
+  let cellCount = currentColumns.length + (context.selection ? 1 : 0)
+
+  const buildRowCells = (rowElement: HTMLTableRowElement): void => {
+    rowElement.replaceChildren()
+
+    if (context.cellNavigation) {
+      rowElement.setAttribute('role', 'row')
+    }
+
+    const offset = context.selection ? 1 : 0
+
+    if (context.selection) {
+      const cellElement = document.createElement('td')
+      cellElement.classList.add(CLASS_NAME_SELECT_CELL)
+      const input = document.createElement('input')
+      input.type = 'checkbox'
+      input.classList.add('form-check-input')
+      input.setAttribute('aria-label', context.labels.selectRow)
+      input.dataset.coreuiRowSelect = ''
+      if (context.cellNavigation) {
+        cellElement.setAttribute('role', 'gridcell')
+        cellElement.setAttribute('aria-colindex', '1')
+        input.tabIndex = -1
+      }
+
+      cellElement.append(input)
+      rowElement.append(cellElement)
+    }
+
+    for (const [index, column] of currentColumns.entries()) {
+      const cellElement = document.createElement('td')
+      if (context.cellNavigation) {
+        cellElement.setAttribute('role', 'gridcell')
+        cellElement.setAttribute('aria-colindex', String(offset + index + 1))
+        cellElement.dataset.coreuiColumn = column.key
+        cellElement.tabIndex = -1
+      }
+
+      rowElement.append(cellElement)
+    }
+
+    rowElement.dataset.coreuiLayout = layoutSignature
+  }
+
+  const createRowElement = (): HTMLTableRowElement => {
+    const rowElement = document.createElement('tr')
+    buildRowCells(rowElement)
+    return rowElement
+  }
+
+  const updateRowCells = (rowElement: HTMLTableRowElement, row: Row<DataGridItem>, index: number): void => {
+    const offset = context.selection ? 1 : 0
+    const editingCell = context.getEditingCell()
+
+    for (const [cellIndex, column] of currentColumns.entries()) {
+      const cellElement = rowElement.children[cellIndex + offset] as HTMLTableCellElement
+
+      if (editingCell && editingCell.rowId === row.id && editingCell.columnId === column.key) {
+        const editorElement = context.getEditorElement()
+        if (editorElement) {
+          cellElement.replaceChildren(editorElement)
+          continue
+        }
+      }
+
+      if (column.render) {
+        setCellContent(cellElement, column.render(row.original, index), context.sanitizeContent)
+        if (context.cellNavigation) {
+          for (const focusable of cellElement.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)) {
+            focusable.tabIndex = -1
+          }
+        }
+
+        continue
+      }
+
+      const value = row.getValue(column.key)
+      cellElement.textContent = column.formatter ?
+        column.formatter(value, row.original) :
+        String(value ?? '')
+    }
+  }
+
+  const updateRowElement = (rowElement: HTMLTableRowElement, row: Row<DataGridItem>, index: number): void => {
+    if (rowElement.dataset.coreuiLayout !== layoutSignature) {
+      buildRowCells(rowElement)
+      delete rowElement.dataset.coreuiRow
+    }
+
+    if (context.selection) {
+      const input = rowElement.firstElementChild!.firstElementChild as HTMLInputElement
+      const selected = row.getIsSelected()
+      input.checked = selected
+      rowElement.classList.toggle(CLASS_NAME_ROW_SELECTED, selected)
+      rowElement.setAttribute('aria-selected', String(selected))
+    }
+
+    // Cell content is immutable for a given (data version, row id, index)
+    // triple — data replacements (dataProvider loads, update()) bump the
+    // version — so recycled elements skip the cell pass. This keeps custom
+    // render callbacks off the scroll hot path, where all three are stable.
+    const rowKey = `${context.getDataVersion()}:${row.id}`
+    if (rowElement.dataset.coreuiRow !== rowKey || rowElement.dataset.coreuiIndex !== String(index)) {
+      updateRowCells(rowElement, row, index)
+      rowElement.dataset.coreuiRow = rowKey
+    }
+
+    rowElement.dataset.coreuiIndex = String(index)
+    rowElement.setAttribute('aria-rowindex', String(context.headerRowCount + context.getRowIndexOffset() + index + 1))
+    rowElement.classList.toggle(CLASS_NAME_ROW_ODD, index % 2 === 1)
+
+    if (currentPinning) {
+      const pinning = currentPinning
+      const offset = context.selection ? 1 : 0
+      if (context.selection) {
+        applyPinnedCell(rowElement.children[0] as HTMLTableCellElement, pinning.select)
+      }
+
+      for (const [cellIndex, column] of currentColumns.entries()) {
+        applyPinnedCell(rowElement.children[cellIndex + offset] as HTMLTableCellElement, pinning.columns[column.key] ?? null)
+      }
+    }
+  }
+
+  const createSpacer = (): HTMLTableRowElement => {
+    const rowElement = document.createElement('tr')
+    rowElement.classList.add(CLASS_NAME_SPACER)
+    rowElement.setAttribute('aria-hidden', 'true')
+
+    const cellElement = document.createElement('td')
+    cellElement.colSpan = Math.max(cellCount, 1)
+    rowElement.append(cellElement)
+
+    return rowElement
+  }
+
+  const setSpacerHeight = (spacerElement: HTMLTableRowElement, height: number): void => {
+    spacerElement.style.height = `${height}px`;
+    (spacerElement.firstElementChild as HTMLTableCellElement).style.height = `${height}px`
+    spacerElement.style.display = height > 0 ? '' : 'none'
+  }
+
+  const topSpacer = createSpacer()
+  const bottomSpacer = createSpacer()
+  let spacersAttached = false
+  let emptyElement: HTMLTableRowElement | null = null
+  let rowElements: HTMLTableRowElement[] = []
+  let currentPinning: GridPinning | null = null
+  const rowPool: HTMLTableRowElement[] = []
+
+  const renderEmpty = () => {
+    spacersAttached = false
+    rowPool.push(...rowElements)
+    rowElements = []
+
+    if (!emptyElement) {
+      emptyElement = document.createElement('tr')
+      emptyElement.classList.add(CLASS_NAME_EMPTY)
+      emptyElement.append(document.createElement('td'))
+    }
+
+    const cellElement = emptyElement.firstElementChild as HTMLTableCellElement
+    cellElement.colSpan = Math.max(cellCount, 1)
+    setCellContent(cellElement, context.renderEmpty(), context.sanitizeContent)
+
+    element.replaceChildren(emptyElement)
+  }
+
+  const renderAll = (rows: Array<Row<DataGridItem>>) => {
+    if (emptyElement) {
+      emptyElement.remove()
+    }
+
+    while (rowElements.length > rows.length) {
+      const rowElement = rowElements.pop()!
+      rowElement.remove()
+      rowPool.push(rowElement)
+    }
+
+    while (rowElements.length < rows.length) {
+      const rowElement = rowPool.pop() ?? createRowElement()
+      element.append(rowElement)
+      rowElements.push(rowElement)
+    }
+
+    for (const [index, row] of rows.entries()) {
+      updateRowElement(rowElements[index], row, index)
+    }
+  }
+
+  const renderWindow = (rows: Array<Row<DataGridItem>>, virtualizer: GridVirtualizerInstance) => {
+    if (!spacersAttached) {
+      element.replaceChildren(topSpacer, bottomSpacer)
+      spacersAttached = true
+      rowElements = []
+    }
+
+    const virtualItems = virtualizer.getVirtualItems()
+    const totalSize = virtualizer.getTotalSize()
+    const paddingTop = virtualItems.length > 0 ? virtualItems[0].start : 0
+    const paddingBottom = virtualItems.length > 0 ?
+      totalSize - virtualItems[virtualItems.length - 1].end :
+      totalSize
+
+    setSpacerHeight(topSpacer, paddingTop)
+    setSpacerHeight(bottomSpacer, paddingBottom)
+
+    while (rowElements.length > virtualItems.length) {
+      const rowElement = rowElements.pop()!
+      rowElement.remove()
+      rowPool.push(rowElement)
+    }
+
+    while (rowElements.length < virtualItems.length) {
+      const rowElement = rowPool.pop() ?? createRowElement()
+      bottomSpacer.before(rowElement)
+      rowElements.push(rowElement)
+    }
+
+    for (const [index, virtualItem] of virtualItems.entries()) {
+      updateRowElement(rowElements[index], rows[virtualItem.index], virtualItem.index)
+    }
+  }
+
+  let editingSignature: string | null = null
+
+  return {
+    element,
+    update() {
+      const rows = context.getRows()
+      currentPinning = context.getPinning()
+
+      // The immutable-cell contract skips the cell pass on recycled rows, so
+      // an editing transition (start, commit, cancel, move) must force the
+      // rendered rows to rebuild their cells - once, not per frame.
+      const editingCell = context.getEditingCell()
+      const nextEditingSignature = editingCell ? `${editingCell.rowId}:${editingCell.columnId}` : null
+      if (nextEditingSignature !== editingSignature) {
+        editingSignature = nextEditingSignature
+        for (const rowElement of rowElements) {
+          delete rowElement.dataset.coreuiRow
+        }
+      }
+
+      const columns = context.getVisibleColumns()
+      const signature = columns.map(column => column.key).join('|')
+      if (signature !== layoutSignature) {
+        currentColumns = columns
+        layoutSignature = signature
+        cellCount = currentColumns.length + (context.selection ? 1 : 0);
+        (topSpacer.firstElementChild as HTMLTableCellElement).colSpan = Math.max(cellCount, 1);
+        (bottomSpacer.firstElementChild as HTMLTableCellElement).colSpan = Math.max(cellCount, 1)
+      }
+
+      if (rows.length === 0) {
+        renderEmpty()
+        return
+      }
+
+      const virtualizer = context.getVirtualizer()
+
+      if (virtualizer) {
+        renderWindow(rows, virtualizer)
+        return
+      }
+
+      renderAll(rows)
+    }
+  }
+}