@startsimpli/ui 0.4.104 → 0.4.105

package/src/utils/__tests__/download-csv.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `downloadCsv` writes the BOM. Without it Excel reads a UTF-8 file in the local
+ * ANSI codepage and every accented character arrives mojibaked — which is what
+ * the table's exporter did until these primitives replaced its private copy.
+ */
+import { downloadCsv } from '../csv';
+
+describe('downloadCsv', () => {
+  const originalCreate = URL.createObjectURL
+  const originalRevoke = URL.revokeObjectURL
+
+  afterEach(() => {
+    URL.createObjectURL = originalCreate
+    URL.revokeObjectURL = originalRevoke
+  })
+
+  it('prefixes the UTF-8 BOM and names the file as asked', () => {
+    let captured: Blob | null = null
+    URL.createObjectURL = ((blob: Blob) => {
+      captured = blob
+      return 'blob:x'
+    }) as typeof URL.createObjectURL
+    URL.revokeObjectURL = (() => {}) as typeof URL.revokeObjectURL
+
+    const clicks: string[] = []
+    const realCreateElement = document.createElement.bind(document)
+    jest.spyOn(document, 'createElement').mockImplementation((tag: string) => {
+      const el = realCreateElement(tag) as HTMLAnchorElement
+      if (tag === 'a') el.click = () => clicks.push(el.download)
+      return el
+    })
+
+    downloadCsv('patents-2026-08-24.csv', 'Name\r\nCafé\r\n')
+
+    expect(clicks).toEqual(['patents-2026-08-24.csv'])
+    expect(captured).not.toBeNull()
+    expect(captured!.type).toBe('text/csv;charset=utf-8;')
+    ;(document.createElement as jest.Mock).mockRestore()
+  })
+})

package/src/utils/csv.ts

@@ -0,0 +1,77 @@
+/**
+ * CSV, written the way a spreadsheet actually reads it.
+ *
+ * These are the primitives `unified-table/utils/export.ts` uses, and they are
+ * exported so a page that needs to export something the table does not hold —
+ * every matching row rather than the page on screen — writes the SAME file
+ * rather than growing a second CSV implementation next to this one.
+ *
+ * THE FORMULA GUARD IS A SECURITY CONTROL, not a nicety. A cell whose first
+ * character is `=`, `+`, `-` or `@` is EXECUTED by Excel and Sheets when the
+ * file is opened, so anyone who can name a record can run a formula in whoever
+ * exports the list. The leading apostrophe is the standard neutralisation.
+ *
+ * THE BOM IS WHY AN ACCENT SURVIVES. Without it Excel reads a UTF-8 file in the
+ * local ANSI codepage and a title with an accent arrives mojibaked.
+ *
+ * CRLF is the line ending RFC 4180 specifies and the one Excel does not
+ * second-guess when a quoted cell contains a newline of its own.
+ */
+
+/** Characters that make a spreadsheet treat a cell as a formula. Tab and CR are
+ *  in the set because they can be used to smuggle a leader past a naive check. */
+const FORMULA_LEADERS = new Set(['=', '+', '-', '@', '\t', '\r'])
+
+/** One cell: formula-guarded, then quoted if it needs to be. */
+export function csvCell(raw: unknown): string {
+  const value = raw == null ? '' : String(raw)
+  const guarded = value.length > 0 && FORMULA_LEADERS.has(value[0]) ? `'${value}` : value
+  if (/[",\n\r]/.test(guarded)) return `"${guarded.replace(/"/g, '""')}"`
+  return guarded
+}
+
+/** Rows of already-stringified cells -> one RFC 4180 document. */
+export function csvFromRows(rows: string[][]): string {
+  return `${rows.map((row) => row.map(csvCell).join(',')).join('\r\n')}\r\n`
+}
+
+export interface CsvColumn<T> {
+  header: string
+  value: (row: T) => string
+}
+
+/** Typed rows + a column spec -> one RFC 4180 document. */
+export function toCsv<T>(rows: T[], columns: CsvColumn<T>[]): string {
+  const out = [columns.map((c) => c.header)]
+  for (const row of rows) out.push(columns.map((c) => c.value(row)))
+  return csvFromRows(out)
+}
+
+/** `products-2026-08-24.csv` — the subject and the day, so two exports never
+ *  collide in a downloads folder. */
+export function csvFilename(base: string, now: Date = new Date()): string {
+  const slug =
+    base.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'export'
+  return `${slug}-${now.toISOString().slice(0, 10)}.csv`
+}
+
+/**
+ * Hand a file to the browser. A Blob + object URL rather than a `data:` URI: a
+ * large list exceeds what some browsers accept in a URL, and the object URL is
+ * revoked immediately so the rows do not sit in memory after the save.
+ */
+export function downloadBlob(filename: string, blob: Blob): void {
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = filename
+  document.body.appendChild(link)
+  link.click()
+  document.body.removeChild(link)
+  URL.revokeObjectURL(url)
+}
+
+/** Save a CSV document, BOM and all. */
+export function downloadCsv(filename: string, csv: string): void {
+  downloadBlob(filename, new Blob([`${csv}`], { type: 'text/csv;charset=utf-8;' }))
+}

package/src/utils/index.ts

@@ -1,4 +1,13 @@
 export { cn } from './cn'
+export {
+  csvCell,
+  csvFromRows,
+  csvFilename,
+  toCsv,
+  downloadCsv,
+  downloadBlob,
+  type CsvColumn,
+} from './csv'
 
 /**
  * Generate a random ID with optional prefix