@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/table/config.ts

@@ -0,0 +1,71 @@
+import { downloadToCSV, downloadToPNG } from '../actions'
+import type { ConfigProps } from '../loader/types'
+import type {
+  TableDownloadConfig,
+  TableWidgetConfig,
+  TableColumn,
+  Mode,
+  SortDirection,
+} from './types'
+
+export const DEFAULT_MODE: Mode = 'local'
+export const DEFAULT_PAGE = 0
+export const DEFAULT_ROWS_PER_PAGE = 10
+export const DEFAULT_ROWS_PER_PAGE_OPTIONS = [5, 10, 25, 50]
+
+export const DEFAULT_COLUMN_ID = null
+export const DEFAULT_DIRECTION: SortDirection = 'asc'
+
+/**
+ * Default table download configuration
+ * Supports PNG export (screenshot) and CSV export (data)
+ */
+export function tableDownloadConfig({
+  refUI,
+}: ConfigProps): TableDownloadConfig {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        if (!data?.length) {
+          return downloadToCSV.modifier([])
+        }
+
+        // Convert table data to CSV format
+        // First row contains headers (column keys)
+        const firstRow = data[0]
+        if (!firstRow) {
+          return downloadToCSV.modifier([])
+        }
+
+        const headers = Object.keys(firstRow).filter((key) => key !== 'id')
+        const rows = data.map((row) =>
+          headers.map((header) => {
+            const value = row[header]
+            if (value === null || value === undefined) return ''
+            if (typeof value === 'object') return JSON.stringify(value)
+            return value
+          }),
+        )
+
+        return downloadToCSV.modifier([headers, ...rows])
+      },
+    },
+  ]
+}
+
+/**
+ * Default table widget configuration
+ */
+export function tableConfig(columns: TableColumn[] = []): TableWidgetConfig {
+  return {
+    columns,
+    selectable: false,
+    selected: [],
+    mode: DEFAULT_MODE,
+  }
+}

package/src/widgets/table/helpers.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+import { getCellValue, compareValues, sortData, paginateData } from './helpers'
+
+describe('helpers', () => {
+  describe('getCellValue', () => {
+    it('should return empty string for null', () => {
+      expect(getCellValue(null)).toBe('')
+    })
+
+    it('should return empty string for undefined', () => {
+      expect(getCellValue(undefined)).toBe('')
+    })
+
+    it('should return string as-is', () => {
+      expect(getCellValue('hello')).toBe('hello')
+    })
+
+    it('should return number as-is', () => {
+      expect(getCellValue(42)).toBe(42)
+    })
+
+    it('should return boolean as-is', () => {
+      expect(getCellValue(true)).toBe(true)
+      expect(getCellValue(false)).toBe(false)
+    })
+
+    it('should format array of strings with quotes', () => {
+      expect(getCellValue(['a', 'b', 'c'])).toBe('["a", "b", "c"]')
+    })
+
+    it('should format array of numbers without quotes', () => {
+      expect(getCellValue([1, 2, 3])).toBe('[1, 2, 3]')
+    })
+
+    it('should format mixed array', () => {
+      expect(getCellValue(['hello', 42, true])).toBe('["hello", 42, true]')
+    })
+
+    it('should format empty array', () => {
+      expect(getCellValue([])).toBe('[]')
+    })
+
+    it('should stringify object', () => {
+      expect(getCellValue({ key: 'value' })).toBe('{"key":"value"}')
+    })
+
+    it('should stringify nested object', () => {
+      expect(getCellValue({ a: { b: 'c' } })).toBe('{"a":{"b":"c"}}')
+    })
+  })
+
+  describe('compareValues', () => {
+    describe('null/undefined handling', () => {
+      it('should sort null to end (return 1)', () => {
+        expect(compareValues(null, 'a', 'asc')).toBe(1)
+      })
+
+      it('should sort undefined to end (return 1)', () => {
+        expect(compareValues(undefined, 'a', 'asc')).toBe(1)
+      })
+
+      it('should sort non-null before null (return -1)', () => {
+        expect(compareValues('a', null, 'asc')).toBe(-1)
+      })
+
+      it('should sort non-undefined before undefined (return -1)', () => {
+        expect(compareValues('a', undefined, 'asc')).toBe(-1)
+      })
+    })
+
+    describe('string comparison', () => {
+      it('should compare strings ascending', () => {
+        expect(compareValues('apple', 'banana', 'asc')).toBeLessThan(0)
+        expect(compareValues('banana', 'apple', 'asc')).toBeGreaterThan(0)
+        expect(compareValues('apple', 'apple', 'asc')).toBe(0)
+      })
+
+      it('should compare strings descending', () => {
+        expect(compareValues('apple', 'banana', 'desc')).toBeGreaterThan(0)
+        expect(compareValues('banana', 'apple', 'desc')).toBeLessThan(0)
+        // When values are equal, result is 0 (could be -0 or +0, both equal 0)
+        expect(compareValues('apple', 'apple', 'desc') === 0).toBe(true)
+      })
+    })
+
+    describe('number comparison', () => {
+      it('should compare numbers ascending', () => {
+        expect(compareValues(1, 2, 'asc')).toBeLessThan(0)
+        expect(compareValues(2, 1, 'asc')).toBeGreaterThan(0)
+        expect(compareValues(1, 1, 'asc')).toBe(0)
+      })
+
+      it('should compare numbers descending', () => {
+        expect(compareValues(1, 2, 'desc')).toBeGreaterThan(0)
+        expect(compareValues(2, 1, 'desc')).toBeLessThan(0)
+        // When values are equal, result is 0 (could be -0 or +0, both equal 0)
+        expect(compareValues(1, 1, 'desc') === 0).toBe(true)
+      })
+
+      it('should handle negative numbers', () => {
+        expect(compareValues(-5, 5, 'asc')).toBeLessThan(0)
+        expect(compareValues(5, -5, 'asc')).toBeGreaterThan(0)
+      })
+
+      it('should handle decimal numbers', () => {
+        expect(compareValues(1.5, 2.5, 'asc')).toBeLessThan(0)
+        expect(compareValues(2.5, 1.5, 'asc')).toBeGreaterThan(0)
+      })
+    })
+
+    describe('boolean comparison', () => {
+      it('should compare booleans ascending (false before true)', () => {
+        expect(compareValues(false, true, 'asc')).toBeLessThan(0)
+        expect(compareValues(true, false, 'asc')).toBeGreaterThan(0)
+        expect(compareValues(true, true, 'asc')).toBe(0)
+        expect(compareValues(false, false, 'asc')).toBe(0)
+      })
+
+      it('should compare booleans descending (true before false)', () => {
+        expect(compareValues(false, true, 'desc')).toBeGreaterThan(0)
+        expect(compareValues(true, false, 'desc')).toBeLessThan(0)
+      })
+    })
+
+    describe('object comparison', () => {
+      it('should compare objects as JSON strings', () => {
+        const objA = { a: 1 }
+        const objB = { b: 2 }
+        // Compares '{"a":1}' vs '{"b":2}'
+        expect(compareValues(objA, objB, 'asc')).toBeLessThan(0)
+      })
+
+      it('should handle array comparison', () => {
+        const arrA = [1, 2]
+        const arrB = [3, 4]
+        // Compares '[1,2]' vs '[3,4]'
+        expect(compareValues(arrA, arrB, 'asc')).toBeLessThan(0)
+      })
+    })
+  })
+
+  describe('sortData', () => {
+    const testData = [
+      { id: 1, name: 'Charlie', age: 30 },
+      { id: 2, name: 'Alice', age: 25 },
+      { id: 3, name: 'Bob', age: 35 },
+    ]
+
+    it('should sort by string column ascending', () => {
+      const sorted = sortData(testData, 'name', 'asc')
+      expect(sorted.map((r) => r.name)).toEqual(['Alice', 'Bob', 'Charlie'])
+    })
+
+    it('should sort by string column descending', () => {
+      const sorted = sortData(testData, 'name', 'desc')
+      expect(sorted.map((r) => r.name)).toEqual(['Charlie', 'Bob', 'Alice'])
+    })
+
+    it('should sort by number column ascending', () => {
+      const sorted = sortData(testData, 'age', 'asc')
+      expect(sorted.map((r) => r.age)).toEqual([25, 30, 35])
+    })
+
+    it('should sort by number column descending', () => {
+      const sorted = sortData(testData, 'age', 'desc')
+      expect(sorted.map((r) => r.age)).toEqual([35, 30, 25])
+    })
+
+    it('should not mutate original array', () => {
+      const original = [...testData]
+      sortData(testData, 'name', 'asc')
+      expect(testData).toEqual(original)
+    })
+
+    it('should handle empty array', () => {
+      expect(sortData([], 'name', 'asc')).toEqual([])
+    })
+
+    it('should handle single item array', () => {
+      const single = [{ id: 1, name: 'Alice' }]
+      expect(sortData(single, 'name', 'asc')).toEqual(single)
+    })
+
+    it('should handle null values in data', () => {
+      const dataWithNull = [
+        { id: 1, name: 'Bob' },
+        { id: 2, name: null },
+        { id: 3, name: 'Alice' },
+      ]
+      const sorted = sortData(dataWithNull, 'name', 'asc')
+      // Null should be sorted to end
+      expect(sorted.map((r) => r.name)).toEqual(['Alice', 'Bob', null])
+    })
+  })
+
+  describe('paginateData', () => {
+    const testData = [
+      { id: 1 },
+      { id: 2 },
+      { id: 3 },
+      { id: 4 },
+      { id: 5 },
+      { id: 6 },
+      { id: 7 },
+      { id: 8 },
+      { id: 9 },
+      { id: 10 },
+    ]
+
+    it('should return first page', () => {
+      const result = paginateData(testData, 0, 3)
+      expect(result.map((r) => r.id)).toEqual([1, 2, 3])
+    })
+
+    it('should return second page', () => {
+      const result = paginateData(testData, 1, 3)
+      expect(result.map((r) => r.id)).toEqual([4, 5, 6])
+    })
+
+    it('should return partial last page', () => {
+      const result = paginateData(testData, 3, 3)
+      expect(result.map((r) => r.id)).toEqual([10])
+    })
+
+    it('should return empty array for page beyond data', () => {
+      const result = paginateData(testData, 10, 3)
+      expect(result).toEqual([])
+    })
+
+    it('should handle page size larger than data', () => {
+      const result = paginateData(testData, 0, 100)
+      expect(result.map((r) => r.id)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    })
+
+    it('should handle empty array', () => {
+      expect(paginateData([], 0, 10)).toEqual([])
+    })
+
+    it('should handle single item', () => {
+      const result = paginateData([{ id: 1 }], 0, 10)
+      expect(result.map((r) => r.id)).toEqual([1])
+    })
+  })
+})

package/src/widgets/table/helpers.ts

@@ -0,0 +1,107 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Get formatted cell value for display
+ * Handles primitives, arrays, objects, and custom formatters
+ *
+ * @param cellValue - Raw cell value
+ * @param formatter - Optional formatter function
+ * @returns Formatted value for display
+ */
+export function getCellValue<T>(cellValue: T): ReactNode {
+  // Handle null/undefined
+  if (cellValue === null || cellValue === undefined) {
+    return ''
+  }
+
+  // Handle arrays - format as [item1, item2, ...]
+  if (Array.isArray(cellValue)) {
+    const formatted = cellValue
+      .map((item) => (typeof item === 'string' ? `"${item}"` : String(item)))
+      .join(', ')
+    return `[${formatted}]`
+  }
+
+  // Handle objects - stringify to JSON
+  if (typeof cellValue === 'object') {
+    return JSON.stringify(cellValue)
+  }
+
+  // Return primitives as-is (string, number, boolean)
+  return cellValue as ReactNode
+}
+
+/**
+ * Compare two values for sorting
+ * Handles strings, numbers, and other types
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @param direction - Sort direction
+ * @returns Comparison result (-1, 0, 1)
+ */
+export function compareValues(
+  a: unknown,
+  b: unknown,
+  direction: 'asc' | 'desc',
+): number {
+  // Handle null/undefined - always sort to end
+  if (a === null || a === undefined) return 1
+  if (b === null || b === undefined) return -1
+
+  let comparison = 0
+
+  if (typeof a === 'string' && typeof b === 'string') {
+    comparison = a.localeCompare(b)
+  } else if (typeof a === 'number' && typeof b === 'number') {
+    comparison = a - b
+  } else if (typeof a === 'boolean' && typeof b === 'boolean') {
+    comparison = a === b ? 0 : a ? 1 : -1
+  } else if (typeof a === 'object' || typeof b === 'object') {
+    // Compare objects/arrays as JSON strings
+    const strA = JSON.stringify(a)
+    const strB = JSON.stringify(b)
+    comparison = strA.localeCompare(strB)
+  } else {
+    // Fallback for other primitives (bigint, symbol, etc.)
+    comparison = 0
+  }
+
+  return direction === 'asc' ? comparison : -comparison
+}
+
+/**
+ * Sort data array by column
+ *
+ * @param data - Data array to sort
+ * @param columnId - Column ID to sort by
+ * @param direction - Sort direction
+ * @returns Sorted data array (new array, does not mutate original)
+ */
+export function sortData<T extends Record<string, unknown>>(
+  data: T[],
+  columnId: string,
+  direction: 'asc' | 'desc',
+): T[] {
+  return [...data].sort((a, b) =>
+    compareValues(a[columnId], b[columnId], direction),
+  )
+}
+
+/**
+ * Paginate data array
+ *
+ * @param data - Data array to paginate
+ * @param page - Current page (0-indexed)
+ * @param rowsPerPage - Number of rows per page
+ * @returns Paginated data slice
+ */
+export function paginateData<T>(
+  data: T[],
+  page: number,
+  rowsPerPage: number,
+): T[] {
+  const start = page * rowsPerPage
+  const end = start + rowsPerPage
+  return data.slice(start, end)
+}

package/src/widgets/table/hooks/index.ts

@@ -0,0 +1,7 @@
+export { usePagination } from './use-pagination'
+export { useSort } from './use-sort'
+export { useSelection } from './use-selection'
+
+export type { UsePaginationResult } from './use-pagination'
+export type { UseSortResult } from './use-sort'
+export type { UseSelectionOptions, UseSelectionResult } from './use-selection'