@carto/ps-react-ui 5.0.0 → 6.0.0

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

@@ -1,244 +1,233 @@
 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)
-    })
+import {
+  compareValues,
+  deriveVisibleRows,
+  paginateRows,
+  resolveColumns,
+  sortRows,
+  tableDataToCsv,
+} from './helpers'
+import type { TableColumn, TableRow } from './types'
+
+const ROWS: TableRow[] = [
+  { id: 1, name: 'Alpha', score: 12 },
+  { id: 2, name: 'beta', score: 7 },
+  { id: 3, name: 'Gamma', score: 25 },
+  { id: 4, name: null, score: null },
+]
+
+describe('compareValues', () => {
+  it('orders strings via locale compare', () => {
+    expect(compareValues('a', 'b', 'asc')).toBeLessThan(0)
+    expect(compareValues('b', 'a', 'asc')).toBeGreaterThan(0)
+  })
 
-    it('should format array of strings with quotes', () => {
-      expect(getCellValue(['a', 'b', 'c'])).toBe('["a", "b", "c"]')
-    })
+  it('orders numbers numerically', () => {
+    expect(compareValues(1, 10, 'asc')).toBeLessThan(0)
+    expect(compareValues(10, 1, 'asc')).toBeGreaterThan(0)
+  })
 
-    it('should format array of numbers without quotes', () => {
-      expect(getCellValue([1, 2, 3])).toBe('[1, 2, 3]')
-    })
+  it('flips comparison for desc', () => {
+    expect(compareValues(1, 10, 'desc')).toBeGreaterThan(0)
+  })
 
-    it('should format mixed array', () => {
-      expect(getCellValue(['hello', 42, true])).toBe('["hello", 42, true]')
-    })
+  it('sorts null/undefined to the end', () => {
+    expect(compareValues(null, 5, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(5, null, 'asc')).toBeLessThan(0)
+  })
+})
 
-    it('should format empty array', () => {
-      expect(getCellValue([])).toBe('[]')
-    })
+describe('sortRows', () => {
+  it('sorts numeric column ascending and descending', () => {
+    expect(sortRows(ROWS, 'score', 'asc').map((r) => r.id)).toEqual([
+      2, 1, 3, 4,
+    ])
+    expect(sortRows(ROWS, 'score', 'desc').map((r) => r.id)).toEqual([
+      3, 1, 2, 4,
+    ])
+  })
 
-    it('should stringify object', () => {
-      expect(getCellValue({ key: 'value' })).toBe('{"key":"value"}')
-    })
+  it('does not mutate the input', () => {
+    const before = [...ROWS]
+    sortRows(ROWS, 'score', 'asc')
+    expect(ROWS).toEqual(before)
+  })
+})
 
-    it('should stringify nested object', () => {
-      expect(getCellValue({ a: { b: 'c' } })).toBe('{"a":{"b":"c"}}')
-    })
+describe('paginateRows', () => {
+  it('returns the requested slice', () => {
+    expect(paginateRows([1, 2, 3, 4, 5], 0, 2)).toEqual([1, 2])
+    expect(paginateRows([1, 2, 3, 4, 5], 1, 2)).toEqual([3, 4])
+    expect(paginateRows([1, 2, 3, 4, 5], 2, 2)).toEqual([5])
   })
 
-  describe('compareValues', () => {
-    describe('null/undefined handling', () => {
-      it('should sort null to end (return 1)', () => {
-        expect(compareValues(null, 'a', 'asc')).toBe(1)
-      })
+  it('returns empty for out-of-range pages', () => {
+    expect(paginateRows([1, 2, 3], 5, 2)).toEqual([])
+  })
+})
 
-      it('should sort undefined to end (return 1)', () => {
-        expect(compareValues(undefined, 'a', 'asc')).toBe(1)
-      })
+describe('resolveColumns', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+    { id: 'c', label: 'C' },
+  ]
 
-      it('should sort non-null before null (return -1)', () => {
-        expect(compareValues('a', null, 'asc')).toBe(-1)
-      })
+  it('returns input unchanged when no order is provided', () => {
+    expect(resolveColumns(cols, undefined)).toBe(cols)
+  })
 
-      it('should sort non-undefined before undefined (return -1)', () => {
-        expect(compareValues('a', undefined, 'asc')).toBe(-1)
-      })
-    })
+  it('reorders by id', () => {
+    expect(resolveColumns(cols, ['c', 'a', 'b']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
 
-    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)
-      })
-    })
+  it('skips unknown ids and appends columns missing from the order', () => {
+    expect(resolveColumns(cols, ['c', 'unknown']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
+})
 
-    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('deriveVisibleRows', () => {
+  it('paginates without sort when sort columnId is null', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: null, direction: 'asc' },
+      page: 0,
+      pageSize: 2,
     })
+    expect(out.visible.map((r) => r.id)).toEqual([1, 2])
+    expect(out.sorted.length).toBe(4)
+  })
 
-    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)
-      })
+  it('sorts then paginates', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: 'score', direction: 'asc' },
+      page: 0,
+      pageSize: 2,
     })
+    expect(out.visible.map((r) => r.id)).toEqual([2, 1])
+  })
+})
 
-    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('compareValues — broader types', () => {
+  it('ranks booleans (false < true)', () => {
+    expect(compareValues(false, true, 'asc')).toBeLessThan(0)
+    expect(compareValues(true, false, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(true, true, 'asc')).toBe(0)
   })
 
-  describe('sortData', () => {
-    const testData = [
-      { id: 1, name: 'Charlie', age: 30 },
-      { id: 2, name: 'Alice', age: 25 },
-      { id: 3, name: 'Bob', age: 35 },
-    ]
+  it('compares objects/arrays via JSON serialization', () => {
+    expect(compareValues({ a: 1 }, { a: 2 }, 'asc')).toBeLessThan(0)
+    expect(compareValues([1, 2], [1, 1], 'desc')).toBeLessThan(0)
+  })
 
-    it('should sort by string column ascending', () => {
-      const sorted = sortData(testData, 'name', 'asc')
-      expect(sorted.map((r) => r.name)).toEqual(['Alice', 'Bob', 'Charlie'])
-    })
+  it('returns 0 when both sides are null/undefined', () => {
+    expect(compareValues(null, undefined, 'asc')).toBe(0)
+    expect(compareValues(undefined, null, 'desc')).toBe(0)
+  })
 
-    it('should sort by string column descending', () => {
-      const sorted = sortData(testData, 'name', 'desc')
-      expect(sorted.map((r) => r.name)).toEqual(['Charlie', 'Bob', 'Alice'])
-    })
+  it('returns 0 for mismatched primitive types it does not know how to order', () => {
+    // Not a documented contract but the implementation falls through to cmp = 0
+    // when types don't match — guard the fallthrough behavior so future
+    // refactors notice if they change it.
+    expect(compareValues(1, 'a', 'asc')).toBe(0)
+  })
+})
 
-    it('should sort by number column ascending', () => {
-      const sorted = sortData(testData, 'age', 'asc')
-      expect(sorted.map((r) => r.age)).toEqual([25, 30, 35])
-    })
+describe('paginateRows — edge cases', () => {
+  it('returns a copy when pageSize is 0 or negative', () => {
+    const rows = [1, 2, 3]
+    const out = paginateRows(rows, 0, 0)
+    expect(out).toEqual(rows)
+    expect(out).not.toBe(rows)
+    expect(paginateRows(rows, 0, -5)).toEqual(rows)
+  })
+})
 
-    it('should sort by number column descending', () => {
-      const sorted = sortData(testData, 'age', 'desc')
-      expect(sorted.map((r) => r.age)).toEqual([35, 30, 25])
-    })
+describe('resolveColumns — edge cases', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+  ]
+  it('returns input unchanged when order is empty', () => {
+    expect(resolveColumns(cols, [])).toBe(cols)
+  })
 
-    it('should not mutate original array', () => {
-      const original = [...testData]
-      sortData(testData, 'name', 'asc')
-      expect(testData).toEqual(original)
-    })
+  it('deduplicates repeated ids in the order', () => {
+    expect(resolveColumns(cols, ['a', 'a', 'b']).map((c) => c.id)).toEqual([
+      'a',
+      'b',
+    ])
+  })
+})
 
-    it('should handle empty array', () => {
-      expect(sortData([], 'name', 'asc')).toEqual([])
-    })
+describe('tableDataToCsv', () => {
+  const cols: TableColumn[] = [
+    { id: 'name', label: 'Name' },
+    { id: 'score', label: 'Score' },
+  ]
+
+  it('emits header row + cell rows', () => {
+    const csv = tableDataToCsv(ROWS, cols)
+    const lines = csv.split('\n')
+    expect(lines[0]).toBe('Name,Score')
+    expect(lines[1]).toBe('Alpha,12')
+    expect(lines[2]).toBe('beta,7')
+  })
 
-    it('should handle single item array', () => {
-      const single = [{ id: 1, name: 'Alice' }]
-      expect(sortData(single, 'name', 'asc')).toEqual(single)
-    })
+  it('escapes commas, newlines, and quotes', () => {
+    const csv = tableDataToCsv([{ id: 1, name: 'a, b "c"\nd', score: 1 }], cols)
+    expect(csv).toContain('"a, b ""c""\nd",1')
+  })
 
-    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])
-    })
+  it('renders null cells as empty strings', () => {
+    const csv = tableDataToCsv([ROWS[3]!], cols)
+    expect(csv.split('\n')[1]).toBe(',')
   })
 
-  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('coerces numeric/boolean header labels and skips ReactNode labels', () => {
+    const numericLabel: TableColumn[] = [
+      { id: 'a', label: 7 as unknown as TableColumn['label'] },
+      { id: 'b', label: true as unknown as TableColumn['label'] },
+      // ReactNode (object) labels degrade to empty string by design.
+      { id: 'c', label: { type: 'span' } as unknown as TableColumn['label'] },
     ]
+    const csv = tableDataToCsv([], numericLabel)
+    expect(csv).toBe('7,true,')
+  })
 
-    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('serialises array and object cell values as JSON', () => {
+    const csv = tableDataToCsv(
+      [{ id: 1, name: ['x', 'y'], score: { z: 1 } }],
+      cols,
+    )
+    // The JSON contains quotes so the cell wraps + escapes.
+    expect(csv).toContain('"[""x"",""y""]"')
+    expect(csv).toContain('"{""z"":1}"')
+  })
 
-    it('should handle empty array', () => {
-      expect(paginateData([], 0, 10)).toEqual([])
-    })
+  it('guards against formula injection by prefixing leading =,+,-,@', () => {
+    const csv = tableDataToCsv(
+      [
+        { id: 1, name: '=SUM(A1)', score: '+1' },
+        { id: 2, name: '-2', score: '@cmd' },
+      ],
+      cols,
+    )
+    const lines = csv.split('\n')
+    expect(lines[1]).toBe("'=SUM(A1),'+1")
+    expect(lines[2]).toBe("'-2,'@cmd")
+  })
 
-    it('should handle single item', () => {
-      const result = paginateData([{ id: 1 }], 0, 10)
-      expect(result.map((r) => r.id)).toEqual([1])
-    })
+  it('still wraps a formula cell that also contains a comma', () => {
+    const csv = tableDataToCsv([{ id: 1, name: '=A1,B2', score: 1 }], cols)
+    // Prefixed against injection, then quoted for the embedded comma.
+    expect(csv.split('\n')[1]).toBe('"\'=A1,B2",1')
   })
 })

package/src/widgets/table/helpers.ts

@@ -1,107 +1,131 @@
-import type { ReactNode } from 'react'
+import { toCsvString } from '../actions/download'
+import type {
+  TableColumn,
+  TableRow,
+  TableSortDirection,
+  TableWidgetData,
+} from './types'
 
 /**
- * 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)
+ * Compares two values with a consistent ordering across primitive types.
+ * Strings use locale comparison; numbers subtract; booleans rank false < true;
+ * objects/arrays compare by JSON serialization. Null/undefined sort to the end
+ * regardless of direction.
  */
 export function compareValues(
   a: unknown,
   b: unknown,
-  direction: 'asc' | 'desc',
+  direction: TableSortDirection,
 ): 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 (a == null && b == null) return 0
+  if (a == null) return 1
+  if (b == null) return -1
+  let cmp = 0
   if (typeof a === 'string' && typeof b === 'string') {
-    comparison = a.localeCompare(b)
+    cmp = a.localeCompare(b)
   } else if (typeof a === 'number' && typeof b === 'number') {
-    comparison = a - b
+    cmp = a - b
   } else if (typeof a === 'boolean' && typeof b === 'boolean') {
-    comparison = a === b ? 0 : a ? 1 : -1
+    cmp = 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
+    cmp = JSON.stringify(a).localeCompare(JSON.stringify(b))
   }
-
-  return direction === 'asc' ? comparison : -comparison
+  return direction === 'asc' ? cmp : -cmp
 }
 
-/**
- * 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[],
+/** Returns a new array sorted by the named column. Does not mutate the input. */
+export function sortRows<T extends TableRow>(
+  rows: readonly T[],
   columnId: string,
-  direction: 'asc' | 'desc',
+  direction: TableSortDirection,
 ): T[] {
-  return [...data].sort((a, b) =>
+  return [...rows].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[],
+/** Returns the slice for the requested page. Out-of-range pages return []. */
+export function paginateRows<T>(
+  rows: readonly T[],
   page: number,
-  rowsPerPage: number,
+  pageSize: number,
 ): T[] {
-  const start = page * rowsPerPage
-  const end = start + rowsPerPage
-  return data.slice(start, end)
+  if (pageSize <= 0) return rows.slice()
+  const start = page * pageSize
+  return rows.slice(start, start + pageSize)
+}
+
+/**
+ * Resolves the effective column list. When the widget store has a
+ * `columnOrder` set (e.g. ChangeColumn was used), the column array is
+ * reordered to match. Unknown ids in the order are skipped; columns not
+ * present in the order keep their original relative position at the end.
+ */
+export function resolveColumns(
+  columns: readonly TableColumn[],
+  columnOrder: readonly string[] | undefined,
+): readonly TableColumn[] {
+  if (!columnOrder || columnOrder.length === 0) return columns
+  const byId = new Map(columns.map((c) => [c.id, c]))
+  const ordered: TableColumn[] = []
+  const seen = new Set<string>()
+  for (const id of columnOrder) {
+    const c = byId.get(id)
+    if (c && !seen.has(id)) {
+      ordered.push(c)
+      seen.add(id)
+    }
+  }
+  for (const c of columns) {
+    if (!seen.has(c.id)) ordered.push(c)
+  }
+  return ordered
+}
+
+/** Applies sort and pagination to the input data. Pure. */
+export function deriveVisibleRows<T extends TableRow>(
+  rows: readonly T[],
+  options: {
+    sort?: { columnId: string | null; direction: TableSortDirection }
+    page: number
+    pageSize: number
+  },
+): { sorted: readonly T[]; visible: T[] } {
+  const sorted =
+    options.sort?.columnId != null
+      ? sortRows(rows, options.sort.columnId, options.sort.direction)
+      : rows
+  const visible = paginateRows(sorted, options.page, options.pageSize)
+  return { sorted, visible }
+}
+
+export function tableDataToCsv(
+  data: TableWidgetData,
+  columns: readonly TableColumn[],
+): string {
+  // Pre-stringify with the table's own header/cell rules, then delegate the
+  // CSV assembly (quoting + spreadsheet formula-injection guard) to the shared
+  // `toCsvString` so escaping stays identical to every other widget's export.
+  const rows: string[][] = [columns.map((c) => stringifyHeader(c.label))]
+  for (const row of data) {
+    rows.push(columns.map((c) => stringifyCell(row[c.id])))
+  }
+  return toCsvString(rows)
+}
+
+function stringifyHeader(label: unknown): string {
+  if (typeof label === 'string') return label
+  if (typeof label === 'number' || typeof label === 'boolean')
+    return String(label)
+  return ''
+}
+
+function stringifyCell(value: unknown): string {
+  if (value == null) return ''
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean')
+    return String(value)
+  if (Array.isArray(value) || typeof value === 'object')
+    return JSON.stringify(value)
+  return ''
 }