@inglorious/ui 0.1.0 → 1.0.1

package/src/data-display/data-grid/handlers.js

@@ -0,0 +1,523 @@
+/**
+ * @typedef {import('../../../types/data-display/data-grid').DataGridProps} DataGridEntity
+ * @typedef {import('../../../types/data-display/data-grid').Column} Column
+ */
+
+import { getRowKeyValue, getRows, getTotalRows } from "./helpers.js"
+
+const MIN_COLUMN_WIDTH = 72
+const VIRTUAL_START = 0
+const VIRTUAL_DEFAULT_END = 20
+const DEFAULT_VIEWPORT_HEIGHT = 600
+const DEFAULT_BUFFER_SIZE = 5
+const DEFAULT_ESTIMATED_HEIGHT = 50
+
+/**
+ * Resets the table entity with default state.
+ * @param {DataGridEntity} entity
+ */
+export function create(entity) {
+  initDataGrid(entity)
+}
+
+/**
+ * Toggles sorting for a column.
+ * @param {DataGridEntity} entity
+ * @param {string} columnId
+ */
+export function sortChange(entity, columnId) {
+  const column = entity.columns.find((c) => c.id === columnId)
+  if (!column?.isSortable) return
+
+  const existingIndex = entity.sorts.findIndex((s) => s.column === columnId)
+
+  if (existingIndex !== -1) {
+    // Toggle direction
+    const existing = entity.sorts[existingIndex]
+    if (existing.direction === "asc") {
+      existing.direction = "desc"
+    } else {
+      // Remove from sort if going from desc back to nothing
+      entity.sorts.splice(existingIndex, 1)
+    }
+  } else {
+    // Add new sort
+    entity.sorts.push({ column: columnId, direction: "asc" })
+  }
+
+  if (entity.pagination) {
+    entity.pagination.page = 0
+  }
+}
+
+/**
+ * Clears all sorts.
+ * @param {DataGridEntity} entity
+ */
+export function sortsClear(entity) {
+  entity.sorts = []
+}
+
+/**
+ * Updates a filter value for a column.
+ * @param {DataGridEntity} entity
+ * @param {{ columnId: string, value: any }} payload
+ */
+export function filterChange(entity, { columnId, value }) {
+  if (value == null || value === "") {
+    delete entity.filters[columnId]
+  } else {
+    entity.filters[columnId] = value
+  }
+
+  if (entity.pagination) {
+    entity.pagination.page = 0
+  }
+}
+
+/**
+ * Clears all filters.
+ * @param {DataGridEntity} entity
+ */
+export function filtersClear(entity) {
+  entity.filters = {}
+
+  if (entity.pagination) {
+    entity.pagination.page = 0
+  }
+}
+
+/**
+ * Updates the search term.
+ * @param {DataGridEntity} entity
+ * @param {string} search
+ */
+export function searchChange(entity, search) {
+  entity.search.value = search
+
+  if (entity.pagination) {
+    entity.pagination.page = 0
+  }
+}
+
+/**
+ * Changes the current page.
+ * @param {DataGridEntity} entity
+ * @param {number} page
+ */
+export function pageChange(entity, page) {
+  if (!entity.pagination) return
+
+  const totalPages = Math.ceil(
+    getTotalRows(entity) / entity.pagination.pageSize,
+  )
+  entity.pagination.page = Math.max(0, Math.min(page, totalPages - 1))
+}
+
+/**
+ * Moves to the next page.
+ * @param {DataGridEntity} entity
+ */
+export function pageNext(entity) {
+  if (!entity.pagination) return
+  const totalPages = Math.ceil(
+    getTotalRows(entity) / entity.pagination.pageSize,
+  )
+  entity.pagination.page = Math.min(entity.pagination.page + 1, totalPages - 1)
+}
+
+/**
+ * Moves to the previous page.
+ * @param {DataGridEntity} entity
+ */
+export function pagePrev(entity) {
+  if (!entity.pagination) return
+  entity.pagination.page = Math.max(entity.pagination.page - 1, 0)
+}
+
+/**
+ * Changes the page size.
+ * @param {DataGridEntity} entity
+ * @param {number} pageSize
+ */
+export function pageSizeChange(entity, pageSize) {
+  if (!entity.pagination) return
+
+  entity.pagination.pageSize = pageSize
+  entity.pagination.page = 0
+}
+
+/**
+ * Changes the width of a column.
+ * @param {DataGridEntity} entity
+ * @param {{ columnId: string, width: number }} payload
+ */
+export function columnResize(entity, { columnId, width }) {
+  const column = entity.columns.find((item) => item.id === columnId)
+  if (!column || Number.isNaN(width)) return
+
+  column.width = Math.max(MIN_COLUMN_WIDTH, Math.round(width))
+}
+
+/**
+ * Selects a row.
+ * @param {DataGridEntity} entity
+ * @param {string|number} rowId
+ */
+export function rowSelect(entity, rowId) {
+  if (!entity.isMultiSelect) {
+    entity.selection = []
+  }
+
+  if (!entity.selection.includes(rowId)) {
+    entity.selection.push(rowId)
+  }
+}
+
+/**
+ * Deselects a row.
+ * @param {DataGridEntity} entity
+ * @param {string|number} rowId
+ */
+export function rowDeselect(entity, rowId) {
+  const index = entity.selection.indexOf(rowId)
+  if (index !== -1) {
+    entity.selection.splice(index, 1)
+  }
+}
+
+/**
+ * Toggles row selection.
+ * @param {DataGridEntity} entity
+ * @param {string|number} rowId
+ */
+export function rowToggle(entity, rowId) {
+  const index = entity.selection.indexOf(rowId)
+
+  if (index === -1) {
+    if (!entity.isMultiSelect) {
+      entity.selection = [rowId] // Replace entirely
+    } else {
+      entity.selection.push(rowId)
+    }
+  } else {
+    entity.selection.splice(index, 1)
+  }
+}
+
+/**
+ * Handles row selection from click interactions, including modifier keys.
+ * @param {DataGridEntity} entity
+ * @param {{ rowId: string|number, shiftKey?: boolean, metaKey?: boolean, ctrlKey?: boolean }} payload
+ */
+export function rowClick(
+  entity,
+  { rowId, shiftKey = false, metaKey = false, ctrlKey = false },
+) {
+  if (!entity.isMultiSelect) {
+    entity.selection = [rowId]
+    entity.selectionAnchor = rowId
+    return
+  }
+
+  if (shiftKey && entity.selectionAnchor != null) {
+    selectRowRange(entity, entity.selectionAnchor, rowId)
+    return
+  }
+
+  if (metaKey || ctrlKey) {
+    rowToggle(entity, rowId)
+    entity.selectionAnchor = rowId
+    return
+  }
+
+  entity.selection = [rowId]
+  entity.selectionAnchor = rowId
+}
+
+/**
+ * Toggles selection of all currently visible rows.
+ * @param {DataGridEntity} entity
+ */
+export function rowsToggleAll(entity) {
+  const rows = getRows(entity)
+  const allSelected = rows.every((row) =>
+    entity.selection.includes(getRowKeyValue(entity, row)),
+  )
+
+  if (allSelected) {
+    // Deselect all visible
+    rows.forEach((row) => {
+      const rowId = getRowKeyValue(entity, row)
+      const index = entity.selection.indexOf(rowId)
+      if (index !== -1) entity.selection.splice(index, 1)
+    })
+  } else {
+    // Select all visible
+    rows.forEach((row) => {
+      const rowId = getRowKeyValue(entity, row)
+      if (!entity.selection.includes(rowId)) {
+        entity.selection.push(rowId)
+      }
+    })
+  }
+}
+
+/**
+ * Selects all currently visible rows.
+ * @param {DataGridEntity} entity
+ */
+export function rowsSelectAll(entity) {
+  const rows = getRows(entity)
+  rows.forEach((row) => {
+    const rowId = getRowKeyValue(entity, row)
+    if (!entity.selection.includes(rowId)) {
+      entity.selection.push(rowId)
+    }
+  })
+}
+
+/**
+ * Clears all row selections.
+ * @param {DataGridEntity} entity
+ */
+export function selectionClear(entity) {
+  entity.selection.length = 0
+}
+
+/**
+ * Handles the scroll event to update the virtualized visible range.
+ * @param {DataGridEntity} entity
+ * @param {HTMLElement} containerEl
+ */
+export function virtualScroll(entity, containerEl) {
+  if (!entity.isVirtualized) return
+  initVirtualization(entity)
+
+  const rows = getRows(entity)
+  const totalItems = rows.length
+  const scrollTop = containerEl.scrollTop
+  const { bufferSize, itemHeight, estimatedHeight, viewportHeight } =
+    entity.virtualization
+  const height = itemHeight || estimatedHeight
+
+  const start = Math.max(
+    VIRTUAL_START,
+    Math.floor(scrollTop / height) - bufferSize,
+  )
+  const visibleCount = Math.ceil(viewportHeight / height)
+  const end = Math.min(start + visibleCount + bufferSize, totalItems)
+
+  if (
+    entity.virtualization.visibleRange.start === start &&
+    entity.virtualization.visibleRange.end === end
+  ) {
+    return
+  }
+
+  entity.virtualization.scrollTop = scrollTop
+  entity.virtualization.visibleRange = { start, end }
+}
+
+/**
+ * Measures the virtualized rows container to update item and viewport height.
+ * @param {DataGridEntity} entity
+ * @param {HTMLElement} containerEl
+ */
+export function virtualMount(entity, containerEl) {
+  if (!entity.isVirtualized) return
+  initVirtualization(entity)
+
+  const viewportHeight = containerEl.clientHeight || containerEl.offsetHeight
+  if (viewportHeight) {
+    entity.virtualization.viewportHeight = viewportHeight
+  }
+
+  const firstRow = containerEl.querySelector("[data-index]")
+  if (!firstRow) return
+
+  entity.virtualization.itemHeight = firstRow.offsetHeight
+  const height =
+    entity.virtualization.itemHeight || entity.virtualization.estimatedHeight
+  const totalItems = getRows(entity).length
+  const end = Math.min(
+    Math.ceil(entity.virtualization.viewportHeight / height),
+    totalItems,
+  )
+
+  entity.virtualization.visibleRange = { start: 0, end }
+}
+
+/**
+ * Initializes the table state.
+ * @param {DataGridEntity} entity
+ */
+function initDataGrid(entity) {
+  entity.rows ??= []
+  entity.rowId ??= "id"
+
+  // Auto-generate columns from first data item if not provided
+  if (!entity.columns && entity.rows.length) {
+    const [firstRow] = entity.rows
+
+    entity.columns = Object.keys(firstRow).map((key) => {
+      const value = firstRow[key]
+      const type = getDefaultColumnType(value)
+      const filter = getDefaultColumnFilter(type)
+
+      return {
+        id: key,
+        title: capitalize(key),
+        type,
+        isSortable: false,
+        isFilterable: false,
+        filter,
+        width: getDefaultColumnWidth(filter.type),
+      }
+    })
+  } else {
+    entity.columns ??= []
+    entity.columns.forEach((column) => {
+      column.title ??= capitalize(column.id)
+      column.type ??= getDefaultColumnType()
+      column.filter ??= getDefaultColumnFilter(column.type)
+      column.width ??= getDefaultColumnWidth(column.filter.type)
+    })
+  }
+
+  // State
+  entity.sorts ??= []
+  entity.filters ??= {}
+  entity.search ??= null
+  if (entity.search) {
+    entity.search.value ??= ""
+  }
+  entity.selection ??= []
+  entity.selectionAnchor ??= null
+  entity.isMultiSelect ??= true
+  entity.isVirtualized ??= false
+
+  entity.pagination ??= null
+  if (entity.pagination) {
+    entity.pagination.page ??= 0
+  }
+
+  if (entity.isVirtualized) {
+    initVirtualization(entity)
+  }
+
+  assertRowKeys(entity)
+}
+
+/**
+ * Ensures virtualization defaults are set.
+ * @param {DataGridEntity} entity
+ */
+function initVirtualization(entity) {
+  entity.virtualization ??= {}
+  entity.virtualization.scrollTop ??= 0
+  entity.virtualization.visibleRange ??= {
+    start: VIRTUAL_START,
+    end: VIRTUAL_DEFAULT_END,
+  }
+  entity.virtualization.viewportHeight ??= DEFAULT_VIEWPORT_HEIGHT
+  entity.virtualization.bufferSize ??= DEFAULT_BUFFER_SIZE
+  entity.virtualization.itemHeight ??= null
+  entity.virtualization.estimatedHeight ??= DEFAULT_ESTIMATED_HEIGHT
+}
+
+/**
+ * Infers the column type from a value.
+ * @param {any} value
+ * @returns {string}
+ */
+function getDefaultColumnType(value) {
+  if (typeof value === "number") return "number"
+  if (typeof value === "boolean") return "boolean"
+  if (value instanceof Date) return "date"
+  return "string"
+}
+
+/**
+ * Gets the default filter configuration for a column type.
+ * @param {string} type
+ * @returns {object}
+ */
+function getDefaultColumnFilter(type) {
+  if (type === "number") return { type: "range" }
+  if (type === "boolean") return { type: "select", options: ["", true, false] }
+  if (type === "date") return { type: "date" }
+  return { type: "text" }
+}
+
+/**
+ * Gets the default column width based on filter type.
+ * @param {string} filterType
+ * @returns {number}
+ */
+function getDefaultColumnWidth(filterType) {
+  if (filterType === "number") return 70
+  if (filterType === "range") return 120
+  if (filterType === "select") return 70
+  if (filterType === "date") return 120
+  if (filterType === "time") return 120
+  if (filterType === "datetime") return 170
+  return 200
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ * @param {string} str
+ * @returns {string}
+ */
+function capitalize(str) {
+  const [firstChar, ...rest] = str
+  return [firstChar.toUpperCase(), ...rest].join("")
+}
+
+/**
+ * Selects a contiguous range of visible rows.
+ * @param {DataGridEntity} entity
+ * @param {string|number} fromRowId
+ * @param {string|number} toRowId
+ */
+function selectRowRange(entity, fromRowId, toRowId) {
+  const visibleRows = getRows(entity)
+  const visibleRowIds = visibleRows.map((row) => getRowKeyValue(entity, row))
+  const start = visibleRowIds.indexOf(fromRowId)
+  const end = visibleRowIds.indexOf(toRowId)
+
+  if (start === -1 || end === -1) {
+    entity.selection = [toRowId]
+    entity.selectionAnchor = toRowId
+    return
+  }
+
+  const [rangeStart, rangeEnd] = start < end ? [start, end] : [end, start]
+  entity.selection = visibleRowIds.slice(rangeStart, rangeEnd + 1)
+}
+
+/**
+ * Ensures all rows have unique and stable keys.
+ * @param {DataGridEntity} entity
+ */
+function assertRowKeys(entity) {
+  if (!entity.rows.length) return
+
+  const seen = new Set()
+  entity.rows.forEach((row, index) => {
+    const rowKey = getRowKeyValue(entity, row)
+    const isValidType = typeof rowKey === "string" || typeof rowKey === "number"
+    if (!isValidType) {
+      throw new Error(
+        `[table] Invalid row key at row ${index} for field "${entity.rowId}". Keys must be string or number. Set entity.rowId to a stable key field.`,
+      )
+    }
+    if (seen.has(rowKey)) {
+      throw new Error(
+        `[table] Duplicate row key "${rowKey}" for field "${entity.rowId}". Keys must be unique.`,
+      )
+    }
+    seen.add(rowKey)
+  })
+}