compote-ui 0.83.0 → 0.84.0

package/skills/data-table/references/column-options.md

@@ -1,177 +1,181 @@
-# Column Options
-
-Column helper:
-
-```ts
-const col = DataTable.createDataTableColumnHelper<Row>();
-```
-
-Accessors:
-
-```ts
-col.accessor('fieldName', { header: 'Field' });
-col.accessorFn((row) => row.a + row.b, { id: 'sum', header: 'Sum' });
-col.group('Group', [col.accessor('name', { header: 'Name' })]);
-col.columns([col.accessor('id', { header: 'ID' })]);
-```
-
-Common options:
-
-- `header: string`
-- `type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'url' | 'phone' | 'date' | 'time' | 'date-time' | 'action'`
-- `align?: 'left' | 'center' | 'right'`
-- `size?: number`
-- `minSize?: number`
-- `maxSize?: number`
-- `enableResizing?: boolean`
-- `enableHiding?: boolean`
-- `enableSorting?: boolean`
-- `enableColumnFilter?: boolean`
-- `filterFn?: FilterFn | string`
-- `formatOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions`
-- `formatLocale?: string`
-- `cell?: (value, row) => string | number | boolean | null | undefined`
-- `cellComponent?: Component`
-- `cellProps?: (value, row) => Record<string, unknown>`
-- `cellSnippet?: Snippet`
-- `pinned?: 'left' | 'right'` — sticky during horizontal scroll. Inside a `col.group(...)`, pinning
-  a member column also pins the group header fragment above it, so the label stays visible while
-  the rest of that group scrolls.
-- `grow?: boolean`
-- `sum?: boolean`
-- `footer?: (values: unknown[]) => string | number | undefined`
-
-Type defaults:
-
-- `number`, `currency`: right aligned, size `120`
-- `percent`: right aligned, size `100`
-- `date`: center aligned, size `110`
-- `time`: center aligned, size `80`
-- `date-time`: center aligned, size `160`
-- `boolean`: center aligned, size `90`
-- `url`: center aligned, sorting disabled, size `60`
-- `phone`: left aligned, size `160`
-- `action`: center aligned, size `60`, sorting/hiding/column-filter all disabled — layout-only,
-  carries no value to format or filter. Supply a `cellComponent`/`cellSnippet` for the row action
-  buttons; the defaults keep the actions column out of the column-visibility menu and filter
-  toolbar automatically.
-
-Use one `grow: true` column to absorb extra horizontal space.
-
-## Date columns: display and filter
-
-`date`, `time` and `date-time` cells are read the same way for display and for the date filter,
-in the column's display zone — `formatOptions.timeZone` when set, otherwise the viewer's local
-zone:
-
-- `'2024-03-15'` (and a `CalendarDate`) is a calendar day. It always shows and filters as
-  15 March, also in zones west of UTC — it is never turned into a midnight-UTC instant.
-- `Date`, epoch milliseconds, strings with an offset (`Z`, `+02:00`, DB `+02`) and
-  `ZonedDateTime` are instants, shown and filtered on the day they fall on in the display zone.
-- A datetime without an offset (`'2024-03-15T10:30'`) is wall-clock time in the display zone.
-- Unreadable values (e.g. `'2024-02-30'`) render as `-` and never match an active filter.
-
-`date` and `date-time` columns filter by calendar-day range. The filter value is
-`[from?, to?]`, each `YYYY-MM-DD` or empty (open-ended); both days are inclusive, a reversed
-range is swapped, and an empty range removes the filter. Instants are judged by their calendar
-day, so 23- and 25-hour DST days need no special handling. `time` columns keep the text filter.
-
-```ts
-table.getColumn('createdAt')?.setFilterValue(['2024-03-01', '2024-03-31']); // March
-table.getColumn('createdAt')?.setFilterValue([undefined, '2024-03-31']); // up to 31 March
-```
-
-## Select columns with multiple values
-
-A `type: 'select'` column may return an array (tags, multi-select attributes). The Funnel then
-lists each item as its own option with a row count, a row matches when any of its items is
-selected, and the cell renders the items joined with `, `. A row counts once per option even
-when its array repeats an item. Missing values — `null`, `undefined`, `''` or an empty array —
-share one `(empty)` option.
-
-The filter value is an array of selected options: each is the `String()` of the cell value, and
-the empty option is `null` — so a real `'null'` string stays its own option:
-
-```ts
-table.getColumn('tags')?.setFilterValue(['Battery', null]); // Battery or no tags
-```
-
-```ts
-col.accessorFn((row) => row.tags.map((tag) => tag.name), {
-	id: 'tags',
-	header: 'Tags',
-	type: 'select'
-});
-```
-
-## Locale for number/currency/percent
-
-Priority: `formatLocale` prop → `useLocaleContext().locale` → browser default. Wrap the app in
-`<LocaleProvider locale="sr-RS">` to set the context locale for every formatted column.
-
-## Custom cellComponent
-
-```svelte
-<!-- PriceCell.svelte -->
-<script lang="ts">
-	let { value, prices }: { value: number; prices: { vendor: string; price: number }[] } = $props();
-</script>
-
-<span>{value}</span>
-```
-
-```ts
-col.accessorFn((row) => Math.min(...row.prices.map((p) => p.price)), {
-	id: 'minPrice',
-	header: 'Best Price',
-	type: 'currency',
-	align: 'right',
-	cellComponent: PriceCell,
-	cellProps: (value, row) => ({ value, prices: row.prices })
-});
-```
-
-## Row height and cell alignment
-
-Body cells are fixed at `h-9` (36px), matching the header, with content vertically centered — any
-control up to 36px tall (every `Button` `icon-xs`/`icon-sm`/`icon`/`icon-lg` size) fits without
-changing row height. Do **not** add negative margins (e.g. `-my-1`) to cell components to
-compensate for row growth — in the virtualized table that fights the virtualizer's 37px row
-estimate. Cells are `truncate` (single-line, `overflow: hidden`), so give action columns a little
-extra `size` if a focus ring on a control near the edge gets clipped.
-
-## DataTable.Search
-
-Global filter input searching across all text columns, debounced (default 300ms).
-
-- `table: DataTableInstance<T>` — required
-- `placeholder?: string` (default `'Search...'`)
-- `class?: ClassValue`
-- `debounceMs?: number` (default `300`)
-
-Text/number columns stay searchable even when the first row's value is `null`/`undefined`;
-booleans and object-valued columns are excluded from global search. Also available as
-`VirtualDataTable.Search` for the virtualized variant.
-
-## DataTable.Root props
-
-`table: DataTableInstance<T>` (required), `caption?: string` (sr-only `<caption>`),
-`emptyMessage?: string` (default `'No rows found'`), `class?: ClassValue`,
-`headerFilters?: boolean` (default `false`; funnel filter popups in column headers — see
-"Filter from column headers" in SKILL.md),
-`onRowClick?: (details: { row: T; event: MouseEvent }) => void`,
-`onRowDoubleClick?: (details: { row: T; event: MouseEvent }) => void` — `row` is `row.original`.
-Clicks on the row-selection checkbox and url-cell buttons do **not** trigger either handler.
-`rowClass?: (row: T) => ClassValue` adds classes to the row's `<tr>` (e.g. a tint; also set
-`--row-bg` so pinned and selection cells match).
-`VirtualDataTable.Root` shares the same props.
-
-```svelte
-<DataTable.Root
-	{table}
-	onRowDoubleClick={({ row, event }) => {
-		if (event.ctrlKey || event.metaKey) openInNewTab(row.id);
-		else navigateTo(row.id);
-	}}
-/>
-```
+# Column Options
+
+Column helper:
+
+```ts
+const col = DataTable.createDataTableColumnHelper<Row>();
+```
+
+Accessors:
+
+```ts
+col.accessor('fieldName', { header: 'Field' });
+col.accessorFn((row) => row.a + row.b, { id: 'sum', header: 'Sum' });
+col.group('Group', [col.accessor('name', { header: 'Name' })]);
+col.columns([col.accessor('id', { header: 'ID' })]);
+```
+
+Common options:
+
+- `header: string`
+- `type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'url' | 'phone' | 'date' | 'time' | 'date-time' | 'action'`
+- `align?: 'left' | 'center' | 'right'`
+- `size?: number`
+- `minSize?: number`
+- `maxSize?: number`
+- `enableResizing?: boolean`
+- `enableHiding?: boolean`
+- `enableSorting?: boolean`
+- `enableColumnFilter?: boolean`
+- `filterFn?: FilterFn | string`
+- `formatOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions`
+- `formatLocale?: string`
+- `cell?: (value, row) => string | number | boolean | null | undefined`
+- `cellComponent?: Component`
+- `cellProps?: (value, row) => Record<string, unknown>`
+- `cellSnippet?: Snippet`
+- `pinned?: 'left' | 'right'` — sticky during horizontal scroll. Inside a `col.group(...)`, pinning
+  a member column also pins the group header fragment above it, so the label stays visible while
+  the rest of that group scrolls.
+- `grow?: boolean`
+- `sum?: boolean`
+- `footer?: (values: unknown[]) => string | number | undefined`
+- `exportValue?: (value, row) => unknown` — the value `DataTable.Export` writes instead of the
+  accessor value (e.g. a number out of an object a `cellComponent` renders). Without `cell`, its
+  text is formatted by `type`; it is never passed to `cell`. See [Export](export.md).
+- `enableExport?: boolean` — defaults to `true`, `false` for `type: 'action'`.
+
+Type defaults:
+
+- `number`, `currency`: right aligned, size `120`
+- `percent`: right aligned, size `100`
+- `date`: center aligned, size `110`
+- `time`: center aligned, size `80`
+- `date-time`: center aligned, size `160`
+- `boolean`: center aligned, size `90`
+- `url`: center aligned, sorting disabled, size `60`
+- `phone`: left aligned, size `160`
+- `action`: center aligned, size `60`, sorting/hiding/column-filter all disabled — layout-only,
+  carries no value to format or filter. Supply a `cellComponent`/`cellSnippet` for the row action
+  buttons; the defaults keep the actions column out of the column-visibility menu and filter
+  toolbar automatically.
+
+Use one `grow: true` column to absorb extra horizontal space.
+
+## Date columns: display and filter
+
+`date`, `time` and `date-time` cells are read the same way for display and for the date filter,
+in the column's display zone — `formatOptions.timeZone` when set, otherwise the viewer's local
+zone:
+
+- `'2024-03-15'` (and a `CalendarDate`) is a calendar day. It always shows and filters as
+  15 March, also in zones west of UTC — it is never turned into a midnight-UTC instant.
+- `Date`, epoch milliseconds, strings with an offset (`Z`, `+02:00`, DB `+02`) and
+  `ZonedDateTime` are instants, shown and filtered on the day they fall on in the display zone.
+- A datetime without an offset (`'2024-03-15T10:30'`) is wall-clock time in the display zone.
+- Unreadable values (e.g. `'2024-02-30'`) render as `-` and never match an active filter.
+
+`date` and `date-time` columns filter by calendar-day range. The filter value is
+`[from?, to?]`, each `YYYY-MM-DD` or empty (open-ended); both days are inclusive, a reversed
+range is swapped, and an empty range removes the filter. Instants are judged by their calendar
+day, so 23- and 25-hour DST days need no special handling. `time` columns keep the text filter.
+
+```ts
+table.getColumn('createdAt')?.setFilterValue(['2024-03-01', '2024-03-31']); // March
+table.getColumn('createdAt')?.setFilterValue([undefined, '2024-03-31']); // up to 31 March
+```
+
+## Select columns with multiple values
+
+A `type: 'select'` column may return an array (tags, multi-select attributes). The Funnel then
+lists each item as its own option with a row count, a row matches when any of its items is
+selected, and the cell renders the items joined with `, `. A row counts once per option even
+when its array repeats an item. Missing values — `null`, `undefined`, `''` or an empty array —
+share one `(empty)` option.
+
+The filter value is an array of selected options: each is the `String()` of the cell value, and
+the empty option is `null` — so a real `'null'` string stays its own option:
+
+```ts
+table.getColumn('tags')?.setFilterValue(['Battery', null]); // Battery or no tags
+```
+
+```ts
+col.accessorFn((row) => row.tags.map((tag) => tag.name), {
+	id: 'tags',
+	header: 'Tags',
+	type: 'select'
+});
+```
+
+## Locale for number/currency/percent
+
+Priority: `formatLocale` prop → `useLocaleContext().locale` → browser default. Wrap the app in
+`<LocaleProvider locale="sr-RS">` to set the context locale for every formatted column.
+
+## Custom cellComponent
+
+```svelte
+<!-- PriceCell.svelte -->
+<script lang="ts">
+	let { value, prices }: { value: number; prices: { vendor: string; price: number }[] } = $props();
+</script>
+
+<span>{value}</span>
+```
+
+```ts
+col.accessorFn((row) => Math.min(...row.prices.map((p) => p.price)), {
+	id: 'minPrice',
+	header: 'Best Price',
+	type: 'currency',
+	align: 'right',
+	cellComponent: PriceCell,
+	cellProps: (value, row) => ({ value, prices: row.prices })
+});
+```
+
+## Row height and cell alignment
+
+Body cells are fixed at `h-9` (36px), matching the header, with content vertically centered — any
+control up to 36px tall (every `Button` `icon-xs`/`icon-sm`/`icon`/`icon-lg` size) fits without
+changing row height. Do **not** add negative margins (e.g. `-my-1`) to cell components to
+compensate for row growth — in the virtualized table that fights the virtualizer's 37px row
+estimate. Cells are `truncate` (single-line, `overflow: hidden`), so give action columns a little
+extra `size` if a focus ring on a control near the edge gets clipped.
+
+## DataTable.Search
+
+Global filter input searching across all text columns, debounced (default 300ms).
+
+- `table: DataTableInstance<T>` — required
+- `placeholder?: string` (default `'Search...'`)
+- `class?: ClassValue`
+- `debounceMs?: number` (default `300`)
+
+Text/number columns stay searchable even when the first row's value is `null`/`undefined`;
+booleans and object-valued columns are excluded from global search. Also available as
+`VirtualDataTable.Search` for the virtualized variant.
+
+## DataTable.Root props
+
+`table: DataTableInstance<T>` (required), `caption?: string` (sr-only `<caption>`),
+`emptyMessage?: string` (default `'No rows found'`), `class?: ClassValue`,
+`headerFilters?: boolean` (default `false`; funnel filter popups in column headers — see
+"Filter from column headers" in SKILL.md),
+`onRowClick?: (details: { row: T; event: MouseEvent }) => void`,
+`onRowDoubleClick?: (details: { row: T; event: MouseEvent }) => void` — `row` is `row.original`.
+Clicks on the row-selection checkbox and url-cell buttons do **not** trigger either handler.
+`rowClass?: (row: T) => ClassValue` adds classes to the row's `<tr>` (e.g. a tint; also set
+`--row-bg` so pinned and selection cells match).
+`VirtualDataTable.Root` shares the same props.
+
+```svelte
+<DataTable.Root
+	{table}
+	onRowDoubleClick={({ row, event }) => {
+		if (event.ctrlKey || event.metaKey) openInNewTab(row.id);
+		else navigateTo(row.id);
+	}}
+/>
+```

package/skills/data-table/references/export.md

@@ -0,0 +1,158 @@
+# Export
+
+`DataTable.Export` downloads the table as a file. It sits in the toolbar like `ColumnVisibility`
+and takes the `table`.
+
+```svelte
+<script lang="ts">
+	import * as DataTable from 'compote-ui/data-table';
+</script>
+
+<DataTable.Toolbar>
+	{#snippet right()}
+		<DataTable.Export {table} filename="invoices" />
+		<DataTable.ColumnVisibility {table} />
+	{/snippet}
+</DataTable.Toolbar>
+```
+
+Props:
+
+- `table: DataTableInstance<T>`
+- `exporters?: DataTableExporter[]` — defaults to `[csvExporter]`.
+- `filename?: string` — without extension, defaults to `'export'`.
+- `triggerLabel?: string` — icon-only with a tooltip when omitted.
+
+One exporter and no selected rows renders a plain button. More exporters, or any selected row,
+renders a menu. When rows are selected the menu offers **All rows (n)** / **Selected rows (k)**.
+`k` counts the selected rows the current filter keeps, exactly what gets exported.
+
+## What gets exported
+
+- **Columns:** the visible ones, in the order the table shows them (pinned left, center, pinned
+  right). Columns with `enableExport: false` are skipped, and so are `type: 'action'` columns by
+  default. A grouped column's header is `Group / Column`.
+- **Rows:** the filtered and sorted rows (`table.getRowModel()`). The table has no pagination,
+  so this is every matching row, not one page.
+- **Cells:** the text the table shows (`cell`, else type formatting; `boolean`, `url` and
+  `phone` as the table draws them, which ignores `cell`). Empty cells are blank, not `-`. A
+  column with `exportValue` and no `cell` formats `exportValue` output by its `type`.
+
+## CSV
+
+`csvExporter` writes a UTF-8 BOM (so Excel reads č/ć/š/đ/ž correctly), `;` as the separator
+(what Excel expects under most European locales), and CRLF line endings. Fields starting with
+`= + - @`, tab or CR get a `'` prefix so spreadsheets don't run them as formulas. Exempt, so
+negative numbers and phone numbers stay as they are: text made only of digits, spaces and number
+punctuation (`-5`, `+381 60 123`), and number, currency and percent columns without their own
+`cell`.
+
+```ts
+import { createCsvExporter } from 'compote-ui/data-table';
+
+const commaCsv = createCsvExporter({ id: 'csv-comma', label: 'CSV (comma)', separator: ',' });
+// Also: bom?: boolean (default true)
+```
+
+CSV holds the formatted text (`1,234.56 RSD`), so a spreadsheet can't sum it.
+
+## Excel (.xlsx)
+
+`xlsxExporter` lives in its own subpath and needs the optional peer `write-excel-file`
+(about 19 KB gzip, loaded only when an export runs, so importing the subpath is SSR-safe):
+
+```sh
+bun add write-excel-file
+```
+
+```svelte
+<script lang="ts">
+	import * as DataTable from 'compote-ui/data-table';
+	import { xlsxExporter } from 'compote-ui/data-table/xlsx';
+</script>
+
+<DataTable.Export {table} filename="invoices" exporters={[DataTable.csvExporter, xlsxExporter]} />
+```
+
+Cells stay computable in Excel:
+
+- `number`, `currency`, `percent` → numbers, also from numeric strings (`"1234.56"`), with an
+  Excel format built from the column's Intl options: grouping, the decimals Intl would show,
+  `%`, and the currency code (`#,##0.00 "USD"`). Options Excel can't express (`notation`,
+  significant digits, `signDisplay`, `currencyDisplay: 'name'`, …) fall back to the text.
+- `date`, `time`, `date-time` → Excel dates, on the day and time the table shows in the column's
+  zone (`formatOptions.timeZone`, else local). A `date` column drops the time; a `time` column
+  keeps only the time of day, so it sorts by time. Formats default to `dd.mm.yyyy`, `hh:mm` and
+  `dd.mm.yyyy hh:mm`.
+- `boolean` → TRUE/FALSE for real `true`/`false`; other values are blank, as the table shows
+  `-` for them.
+- Everything else, and any column with its own `cell` but no `exportValue`, is the text the
+  table shows. Typed cells can't hold formulas, so there is no `'` prefix.
+
+The header row is bold and frozen; column widths follow the table's.
+
+```ts
+import { createXlsxExporter } from 'compote-ui/data-table/xlsx';
+
+const excel = createXlsxExporter({
+	sheet: 'Invoices',
+	date: 'yyyy-mm-dd',
+	dateTime: 'yyyy-mm-dd hh:mm'
+	// also: time, id, label
+});
+```
+
+`exportDataToXlsxBlob(data, options)` returns the file as a `Blob` (e.g. to upload instead of
+download), and `toXlsxCell` maps one cell.
+
+## Custom exporter
+
+An exporter is `{ id, label, icon?, export(context) }`. `context` holds `table`, `scope`
+(`'filtered' | 'selected'`), `filename` and `getData()`, which returns `{ columns, rows }`. Each
+cell is `{ value, text }`. If `export` returns a promise, the trigger stays busy until it
+settles. Errors are not caught.
+
+Export on the server, from the table state:
+
+```ts
+import type { DataTableExporter } from 'compote-ui/data-table';
+
+const serverExcel: DataTableExporter = {
+	id: 'server-xlsx',
+	label: 'Excel',
+	export: async ({ table }) => {
+		const url = await requestExport({
+			sorting: table.atoms.sorting.get(),
+			columnFilters: table.atoms.columnFilters.get(),
+			globalFilter: table.atoms.globalFilter.get(),
+			columns: table.getVisibleLeafColumns().map((column) => column.id)
+		});
+		window.location.assign(url);
+	}
+};
+```
+
+Use a library the app already has instead of `write-excel-file` (SheetJS here):
+
+```ts
+import { utils, writeFileXLSX } from 'xlsx';
+import type { DataTableExporter } from 'compote-ui/data-table';
+
+const sheetJs: DataTableExporter = {
+	id: 'xlsx',
+	label: 'Excel',
+	export: ({ filename, getData }) => {
+		const { columns, rows } = getData();
+		const sheet = utils.aoa_to_sheet([
+			columns.map((column) => column.header),
+			...rows.map((cells) => cells.map((cell) => cell.text))
+		]);
+		const book = utils.book_new();
+		utils.book_append_sheet(book, sheet, 'Sheet1');
+		writeFileXLSX(book, `${filename}.xlsx`);
+	}
+};
+```
+
+`getExportData(table, scope)`, `getExportRows(table, scope)` and `getExportColumns(table)` are
+exported for building export UI outside `DataTable.Export`.