@coreui/data-grid 0.1.0-rc.0

package/src/ui/pagination.ts

@@ -0,0 +1,150 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid ui/pagination.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import { interpolate } from '../labels'
+import type { DataGridLabels, DataGridPaginationInfoState } from '../types'
+
+const CLASS_NAME_PAGINATION = 'data-grid-pagination'
+const CLASS_NAME_PAGINATION_INFO = 'data-grid-pagination-info'
+
+const PAGE_WINDOW = 5
+
+export interface GridPaginationContext {
+  info: boolean | ((state: DataGridPaginationInfoState) => string)
+  labels: DataGridLabels
+  pageSizeOptions: number[]
+}
+
+export interface GridPagination {
+  element: HTMLDivElement
+  update: (state: DataGridPaginationInfoState) => void
+}
+
+const createPageItem = (
+  label: string,
+  page: string,
+  options: { active?: boolean; disabled?: boolean; ariaLabel?: string } = {}
+): HTMLLIElement => {
+  const item = document.createElement('li')
+  item.classList.add('page-item')
+  if (options.active) {
+    item.classList.add('active')
+    item.setAttribute('aria-current', 'page')
+  }
+
+  if (options.disabled) {
+    item.classList.add('disabled')
+  }
+
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.classList.add('page-link')
+  button.textContent = label
+  button.disabled = Boolean(options.disabled)
+  button.dataset.coreuiPage = page
+  if (options.ariaLabel) {
+    button.setAttribute('aria-label', options.ariaLabel)
+  }
+
+  item.append(button)
+
+  return item
+}
+
+export const createPagination = (context: GridPaginationContext): GridPagination => {
+  const element = document.createElement('div')
+  element.classList.add(CLASS_NAME_PAGINATION)
+
+  const nav = document.createElement('nav')
+  nav.setAttribute('aria-label', context.labels.paginationLabel)
+  const list = document.createElement('ul')
+  list.classList.add('pagination', 'pagination-sm')
+  nav.append(list)
+
+  const info = context.info === false ? null : document.createElement('span')
+  if (info) {
+    info.classList.add(CLASS_NAME_PAGINATION_INFO)
+  }
+
+  const select = document.createElement('select')
+  select.classList.add('form-select', 'form-select-sm')
+  select.setAttribute('aria-label', context.labels.pageSizeLabel)
+  select.dataset.coreuiPageSize = ''
+  for (const size of context.pageSizeOptions) {
+    const option = document.createElement('option')
+    option.value = String(size)
+    option.textContent = String(size)
+    select.append(option)
+  }
+
+  element.append(nav, ...(info ? [info] : []), select)
+
+  return {
+    element,
+    update(state) {
+      const lastPageIndex = Math.max(state.pageCount - 1, 0)
+      const windowStart = Math.max(
+        Math.min(state.pageIndex - Math.floor(PAGE_WINDOW / 2), state.pageCount - PAGE_WINDOW),
+        0
+      )
+      // No pages (server mode before the first load, rejected provider) - no
+      // page buttons, only the disabled first/prev/next/last chrome.
+      const windowEnd = state.pageCount === 0 ? -1 : Math.min(windowStart + PAGE_WINDOW - 1, lastPageIndex)
+
+      const items = [
+        createPageItem('«', 'first', {
+          ariaLabel: context.labels.firstPage,
+          disabled: state.pageIndex === 0
+        }),
+        createPageItem('‹', 'prev', {
+          ariaLabel: context.labels.previousPage,
+          disabled: state.pageIndex === 0
+        })
+      ]
+      for (let page = windowStart; page <= windowEnd; page++) {
+        items.push(createPageItem(String(page + 1), String(page), { active: page === state.pageIndex }))
+      }
+
+      items.push(
+        createPageItem('›', 'next', {
+          ariaLabel: context.labels.nextPage,
+          disabled: state.pageIndex >= lastPageIndex
+        }),
+        createPageItem('»', 'last', {
+          ariaLabel: context.labels.lastPage,
+          disabled: state.pageIndex >= lastPageIndex
+        })
+      )
+      list.replaceChildren(...items)
+
+      if (info) {
+        if (typeof context.info === 'function') {
+          info.textContent = context.info(state)
+        } else {
+          const first = state.totalRows === 0 ? 0 : (state.pageIndex * state.pageSize) + 1
+          const last = Math.min((state.pageIndex + 1) * state.pageSize, state.totalRows)
+          info.textContent = interpolate(context.labels.itemsInfo, {
+            first,
+            last,
+            total: state.totalRows
+          })
+        }
+      }
+
+      // A configured pageSize outside pageSizeOptions would leave the select
+      // blank; surface it as an extra option in numeric position.
+      if (![...select.options].some(option => option.value === String(state.pageSize))) {
+        const option = document.createElement('option')
+        option.value = String(state.pageSize)
+        option.textContent = String(state.pageSize)
+        select.insertBefore(option, [...select.options].find(item => Number(item.value) > state.pageSize) ?? null)
+      }
+
+      select.value = String(state.pageSize)
+    }
+  }
+}

package/src/ui/pinning.ts

@@ -0,0 +1,53 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid ui/pinning.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+const CLASS_LEFT = 'data-grid-cell-pinned-left'
+const CLASS_RIGHT = 'data-grid-cell-pinned-right'
+const CLASS_LEFT_LAST = 'data-grid-cell-pinned-left-last'
+const CLASS_RIGHT_FIRST = 'data-grid-cell-pinned-right-first'
+
+export interface PinnedCellInfo {
+  side: 'left' | 'right'
+  offset: number
+  edge: boolean
+  // A left offset that has to clear the (sticky) selection cell; expressed as a
+  // CSS calc so the select-cell width stays a single source of truth in CSS.
+  afterSelect: boolean
+}
+
+export interface GridPinning {
+  columns: Record<string, PinnedCellInfo>
+  select: PinnedCellInfo | null
+}
+
+export const applyPinnedCell = (cell: HTMLTableCellElement, info: PinnedCellInfo | null): void => {
+  cell.classList.remove(CLASS_LEFT, CLASS_RIGHT, CLASS_LEFT_LAST, CLASS_RIGHT_FIRST)
+  cell.style.left = ''
+  cell.style.right = ''
+
+  if (!info) {
+    return
+  }
+
+  if (info.side === 'left') {
+    cell.classList.add(CLASS_LEFT)
+    if (info.edge) {
+      cell.classList.add(CLASS_LEFT_LAST)
+    }
+
+    cell.style.left = info.afterSelect ?
+      `calc(var(--cui-data-grid-select-cell-width) + ${info.offset}px)` :
+      `${info.offset}px`
+  } else {
+    cell.classList.add(CLASS_RIGHT)
+    if (info.edge) {
+      cell.classList.add(CLASS_RIGHT_FIRST)
+    }
+
+    cell.style.right = `${info.offset}px`
+  }
+}

package/src/ui/toolbar.ts

@@ -0,0 +1,144 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid ui/toolbar.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import type { CsvDownloadOptions } from '../util/csv'
+import type { DataGridLabels, DataGridOptions } from '../types'
+
+const CLASS_NAME_TOOLBAR = 'data-grid-toolbar'
+const CLASS_NAME_ACTIONS = 'data-grid-toolbar-actions'
+const CLASS_NAME_SEARCH = 'data-grid-toolbar-search'
+
+export interface GridToolbarContext {
+  labels: DataGridLabels
+  columns: boolean
+  export: boolean
+  // Undo/redo of edit commits - both buttons start disabled, the grid
+  // toggles them as the history stacks fill.
+  history: boolean
+  search: boolean
+  icons: {
+    columns: string
+    export: string
+    redo: string
+    undo: string
+  }
+}
+
+export interface GridToolbar {
+  element: HTMLDivElement
+}
+
+export interface ResolvedToolbar {
+  columns: boolean
+  export: boolean
+  exportOptions: CsvDownloadOptions
+  history: boolean
+  search: boolean
+}
+
+// Normalizes `toolbar` + `globalFilter` into the individual actions. `toolbar:
+// true` enables each action whose underlying feature is on; a granular object
+// picks individually. `globalFilter: true` stays shorthand for the search input.
+export const resolveToolbar = (options: DataGridOptions): ResolvedToolbar => {
+  const { toolbar } = options
+  const columnVisibility = Boolean(options.columnVisibility)
+
+  if (toolbar === true) {
+    return {
+      columns: columnVisibility,
+      export: true,
+      exportOptions: {},
+      history: options.history,
+      search: true
+    }
+  }
+
+  if (typeof toolbar === 'object') {
+    const exportOption = toolbar.export ?? false
+    return {
+      columns: (toolbar.columns ?? false) && columnVisibility,
+      export: Boolean(exportOption),
+      exportOptions: typeof exportOption === 'object' ? exportOption : {},
+      history: (toolbar.history ?? false) && options.history,
+      search: (toolbar.search ?? false) || Boolean(options.globalFilter)
+    }
+  }
+
+  return {
+    columns: false,
+    export: false,
+    exportOptions: {},
+    history: false,
+    search: Boolean(options.globalFilter)
+  }
+}
+
+export const isGlobalFilterEnabled = (options: DataGridOptions): boolean =>
+  resolveToolbar(options).search
+
+const createActionButton = (icon: string, label: string, dataAttribute: string): HTMLButtonElement => {
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.classList.add('btn', 'btn-ghost', 'btn-sm')
+  button.innerHTML = icon
+  button.setAttribute(dataAttribute, '')
+  button.setAttribute('data-coreui-tooltip', label)
+  const text = document.createElement('span')
+  text.classList.add('visually-hidden')
+  text.textContent = label
+  button.append(text)
+  return button
+}
+
+export const createToolbar = (context: GridToolbarContext): GridToolbar => {
+  const element = document.createElement('div')
+  element.classList.add(CLASS_NAME_TOOLBAR)
+
+  if (context.columns || context.export || context.history) {
+    const actions = document.createElement('div')
+    actions.classList.add(CLASS_NAME_ACTIONS)
+
+    if (context.columns) {
+      actions.append(
+        createActionButton(context.icons.columns, context.labels.toolbarColumns, 'data-coreui-toolbar-columns')
+      )
+    }
+
+    if (context.export) {
+      actions.append(
+        createActionButton(context.icons.export, context.labels.toolbarExport, 'data-coreui-toolbar-export')
+      )
+    }
+
+    if (context.history) {
+      const undoButton = createActionButton(context.icons.undo, context.labels.toolbarUndo, 'data-coreui-toolbar-undo')
+      const redoButton = createActionButton(context.icons.redo, context.labels.toolbarRedo, 'data-coreui-toolbar-redo')
+      undoButton.disabled = true
+      redoButton.disabled = true
+      actions.append(undoButton, redoButton)
+    }
+
+    element.append(actions)
+  }
+
+  if (context.search) {
+    const search = document.createElement('div')
+    search.classList.add(CLASS_NAME_SEARCH)
+
+    const input = document.createElement('input')
+    input.type = 'search'
+    input.classList.add('form-control', 'form-control-sm')
+    input.placeholder = context.labels.globalFilterPlaceholder
+    input.setAttribute('aria-label', context.labels.globalFilterLabel)
+    input.dataset.coreuiGlobalFilter = ''
+
+    search.append(input)
+    element.append(search)
+  }
+
+  return { element }
+}

package/src/ui/tooltip.ts

@@ -0,0 +1,113 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid ui/tooltip.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+const CLASS_NAME_TOOLTIP = 'data-grid-tooltip'
+const ATTRIBUTE = 'data-coreui-tooltip'
+const SELECTOR = `[${ATTRIBUTE}]`
+const SHOW_DELAY = 200
+const GAP = 6
+const EDGE = 4
+
+export interface GridTooltip {
+  dispose: () => void
+}
+
+// A single shared, delegated tooltip for grid-owned icon controls. Positioned
+// with position: fixed so it escapes the viewport's overflow, above the anchor
+// with a flip below when there isn't room. Purely visual (aria-hidden) - the
+// anchors already carry their accessible name via aria-label / hidden text.
+export const createTooltip = (root: HTMLElement): GridTooltip => {
+  const element = document.createElement('div')
+  element.className = CLASS_NAME_TOOLTIP
+  element.setAttribute('role', 'tooltip')
+  element.setAttribute('aria-hidden', 'true')
+  element.hidden = true
+  root.append(element)
+
+  let anchor: HTMLElement | null = null
+  let showTimer: ReturnType<typeof setTimeout> | undefined
+
+  const anchorFrom = (target: EventTarget | null): HTMLElement | null => {
+    const element_ = target instanceof Element ? target.closest(SELECTOR) : null
+    return element_ instanceof HTMLElement && element_.getAttribute(ATTRIBUTE) ? element_ : null
+  }
+
+  const position = (): void => {
+    if (!anchor) {
+      return
+    }
+
+    const rect = anchor.getBoundingClientRect()
+    const width = element.offsetWidth
+    const height = element.offsetHeight
+    const above = rect.top - height - GAP
+    const top = above >= 0 ? above : rect.bottom + GAP
+    const left = Math.max(EDGE, Math.min(rect.left + ((rect.width - width) / 2), window.innerWidth - width - EDGE))
+    element.style.top = `${top}px`
+    element.style.left = `${left}px`
+    element.style.visibility = 'visible'
+  }
+
+  const show = (target: HTMLElement): void => {
+    anchor = target
+    element.textContent = target.getAttribute(ATTRIBUTE)
+    element.style.visibility = 'hidden'
+    element.hidden = false
+    position()
+  }
+
+  const hide = (): void => {
+    clearTimeout(showTimer)
+    anchor = null
+    element.hidden = true
+  }
+
+  const onPointerOver = (event: PointerEvent): void => {
+    const target = anchorFrom(event.target)
+    if (!target || target === anchor) {
+      return
+    }
+
+    clearTimeout(showTimer)
+    showTimer = setTimeout(() => show(target), SHOW_DELAY)
+  }
+
+  const onPointerOut = (event: PointerEvent): void => {
+    if (anchor && event.relatedTarget instanceof Node && anchor.contains(event.relatedTarget)) {
+      return
+    }
+
+    hide()
+  }
+
+  const onFocusIn = (event: FocusEvent): void => {
+    const target = anchorFrom(event.target)
+    if (target) {
+      show(target)
+    }
+  }
+
+  root.addEventListener('pointerover', onPointerOver as EventListener)
+  root.addEventListener('pointerout', onPointerOut as EventListener)
+  root.addEventListener('pointerdown', hide)
+  root.addEventListener('focusin', onFocusIn as EventListener)
+  root.addEventListener('focusout', hide)
+  window.addEventListener('scroll', hide, true)
+
+  return {
+    dispose() {
+      clearTimeout(showTimer)
+      root.removeEventListener('pointerover', onPointerOver as EventListener)
+      root.removeEventListener('pointerout', onPointerOut as EventListener)
+      root.removeEventListener('pointerdown', hide)
+      root.removeEventListener('focusin', onFocusIn as EventListener)
+      root.removeEventListener('focusout', hide)
+      window.removeEventListener('scroll', hide, true)
+      element.remove()
+    }
+  }
+}

package/src/util/config.d.ts

@@ -0,0 +1,11 @@
+// Hand-written types for the vendored config.js (see the provenance header there)
+export default class Config {
+  static get Default(): unknown
+  static get DefaultType(): unknown
+  static get NAME(): string
+
+  _getConfig(config?: unknown): any
+  _configAfterMerge(config: any): any
+  _mergeConfigObj(config?: unknown, element?: Element): any
+  _typeCheckConfig(config: Record<string, unknown>, configTypes?: Record<string, string>): void
+}

package/src/util/config.js

@@ -0,0 +1,69 @@
+// Vendored from https://github.com/coreui/coreui-pro/blob/bc4daf1cd79d527bf665d615c0a31f53ab0c3d4e/js/src/util/config.js — sync manually
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI util/config.js
+ * Licensed under MIT (https://github.com/coreui/coreui/blob/main/LICENSE)
+ *
+ * This is a modified version of the Bootstrap's util/config.js
+ * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
+ * --------------------------------------------------------------------------
+ */
+
+import Manipulator from '../dom/manipulator.js'
+import { isElement, toType } from './index.js'
+
+/**
+ * Class definition
+ */
+
+class Config {
+  // Getters
+  static get Default() {
+    return {}
+  }
+
+  static get DefaultType() {
+    return {}
+  }
+
+  static get NAME() {
+    throw new Error('You have to implement the static method "NAME", for each component!')
+  }
+
+  _getConfig(config) {
+    config = this._mergeConfigObj(config)
+    config = this._configAfterMerge(config)
+    this._typeCheckConfig(config)
+    return config
+  }
+
+  _configAfterMerge(config) {
+    return config
+  }
+
+  _mergeConfigObj(config, element) {
+    const jsonConfig = isElement(element) ? Manipulator.getDataAttribute(element, 'config') : {} // try to parse
+
+    return {
+      ...this.constructor.Default,
+      ...(typeof jsonConfig === 'object' ? jsonConfig : {}),
+      ...(isElement(element) ? Manipulator.getDataAttributes(element) : {}),
+      ...(typeof config === 'object' ? config : {})
+    }
+  }
+
+  _typeCheckConfig(config, configTypes = this.constructor.DefaultType) {
+    for (const [property, expectedTypes] of Object.entries(configTypes)) {
+      const value = config[property]
+      const valueType = isElement(value) ? 'element' : toType(value)
+
+      if (!new RegExp(expectedTypes).test(valueType)) {
+        throw new TypeError(
+          `${this.constructor.NAME.toUpperCase()}: Option "${property}" provided type "${valueType}" but expected type "${expectedTypes}".`
+        )
+      }
+    }
+  }
+}
+
+export default Config

package/src/util/csv.ts

@@ -0,0 +1,85 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid util/csv.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+import type { Table } from '@tanstack/table-core'
+import type { DataGridItem } from '../types'
+
+export interface CsvOptions {
+  scope?: 'filtered' | 'all' | 'selected'
+  delimiter?: string
+  bom?: boolean
+  sanitize?: boolean
+}
+
+export interface CsvDownloadOptions extends CsvOptions {
+  filename?: string
+}
+
+interface CsvColumnMeta {
+  label?: string
+  formatter?: (value: unknown, item: DataGridItem) => string
+}
+
+const escapeField = (value: string, delimiter: string): string =>
+  /["\r\n]/.test(value) || value.includes(delimiter) ? `"${value.replace(/"/g, '""')}"` : value
+
+// CSV formula injection: a leading =, +, -, @, tab or CR makes spreadsheets treat
+// the cell as a formula. Opt-in guard prefixes such fields with an apostrophe.
+const sanitizeField = (value: string): string =>
+  /^[=+\-@\t\r]/.test(value) ? `'${value}` : value
+
+const rowsFor = (table: Table<DataGridItem>, scope: CsvOptions['scope']) => {
+  if (scope === 'all') {
+    return table.getCoreRowModel().rows
+  }
+
+  if (scope === 'selected') {
+    return table.getSelectedRowModel().rows
+  }
+
+  return table.getSortedRowModel().rows
+}
+
+export const exportCsv = (table: Table<DataGridItem>, options: CsvOptions = {}): string => {
+  const delimiter = options.delimiter ?? ','
+  // Export follows the rendered layout: pinning, column order and visibility.
+  const columns = [
+    ...table.getLeftVisibleLeafColumns(),
+    ...table.getCenterVisibleLeafColumns(),
+    ...table.getRightVisibleLeafColumns()
+  ]
+
+  const process = (field: string) => escapeField(options.sanitize ? sanitizeField(field) : field, delimiter)
+  const line = (fields: string[]) => fields.map(process).join(delimiter)
+
+  const header = line(columns.map(column => String((column.columnDef.meta as CsvColumnMeta)?.label ?? column.id)))
+  const body = rowsFor(table, options.scope).map(row =>
+    line(columns.map(column => {
+      const value = row.getValue(column.id)
+      const meta = column.columnDef.meta as CsvColumnMeta
+      // Coerce: a formatter may return a number/null in plain-JS usage.
+      return meta?.formatter ? String(meta.formatter(value, row.original) ?? '') : String(value ?? '')
+    }))
+  )
+
+  const csv = [header, ...body].join('\r\n')
+  return options.bom ? `\uFEFF${csv}` : csv
+}
+
+export const downloadCsv = (table: Table<DataGridItem>, options: CsvDownloadOptions = {}): void => {
+  const blob = new Blob([exportCsv(table, options)], { type: 'text/csv;charset=utf-8;' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = options.filename ?? 'export.csv'
+  anchor.style.display = 'none'
+  // Attach before clicking (older Firefox) and defer revoke (Safari race).
+  document.body.append(anchor)
+  anchor.click()
+  anchor.remove()
+  setTimeout(() => URL.revokeObjectURL(url))
+}

package/src/util/debounce.ts

@@ -0,0 +1,18 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid util/debounce.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+export const debounce = <Args extends unknown[]>(
+  callback: (...args: Args) => void,
+  delay: number
+): ((...args: Args) => void) => {
+  let timeout: ReturnType<typeof setTimeout> | undefined
+
+  return (...args: Args) => {
+    clearTimeout(timeout)
+    timeout = setTimeout(() => callback(...args), delay)
+  }
+}

package/src/util/index.d.ts

@@ -0,0 +1,10 @@
+// Hand-written types for the vendored util/index.js (see the provenance header there)
+export function defineJQueryPlugin(plugin: { NAME: string; jQueryInterface: (this: any, ...args: any[]) => unknown }): void
+export function executeAfterTransition(callback: () => void, transitionElement: Element, waitForTransition?: boolean): void
+export function getElement(object: unknown): HTMLElement | null
+export function getjQuery(): unknown
+export function getUID(prefix: string): string
+export function isElement(object: unknown): boolean
+export function isRTL(): boolean
+export function isVisible(element: Element): boolean
+export function toType(object: unknown): string