@zhangt58/svelte-vtable 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -32
- package/dist/components/DataTable.svelte +409 -16
- package/dist/components/DataTable.svelte.d.ts +11 -1
- package/dist/components/DataTableControls.svelte +102 -0
- package/dist/components/flowbite/DataTableControls.svelte +102 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +8 -0
- package/dist/styles.css +176 -62
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -142,27 +142,32 @@ A virtualized table component for efficient rendering of large datasets. The com
|
|
|
142
142
|
|
|
143
143
|
#### Props
|
|
144
144
|
|
|
145
|
-
| Prop
|
|
146
|
-
|
|
|
147
|
-
| `items`
|
|
148
|
-
| `columns`
|
|
149
|
-
| `visibleKeys`
|
|
150
|
-
| `sortKey`
|
|
151
|
-
| `sortDir`
|
|
152
|
-
| `className`
|
|
153
|
-
| `style`
|
|
154
|
-
| `emptyMessage`
|
|
155
|
-
| `colWidths`
|
|
156
|
-
| `selected`
|
|
157
|
-
| `onselect`
|
|
158
|
-
| `onsort`
|
|
159
|
-
| `inlineFilters`
|
|
160
|
-
| `columnFilters`
|
|
161
|
-
| `filterItems`
|
|
162
|
-
| `activeFilters`
|
|
163
|
-
| `onfilter`
|
|
164
|
-
| `rowSnippet`
|
|
165
|
-
| `density`
|
|
145
|
+
| Prop | Type | Default | Description |
|
|
146
|
+
| ---------------- | ---------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
147
|
+
| `items` | `Array` | `[]` | Array of data items to display |
|
|
148
|
+
| `columns` | `ColumnDef[]` | `undefined` | **Unified column definitions** (recommended). When provided, `visibleKeys`, `colWidths`, and `rowSnippet` may be omitted. See [ColumnDef](#columndef) below. |
|
|
149
|
+
| `visibleKeys` | `Array` | `[]` | _(Legacy)_ Array of keys to display as column headers. Ignored when `columns` is provided. |
|
|
150
|
+
| `sortKey` | `string \| null` | `null` | Current sort key (column header); supports `bind:sortKey` |
|
|
151
|
+
| `sortDir` | `'asc' \| 'desc'` | `'asc'` | Sort direction; supports `bind:sortDir` |
|
|
152
|
+
| `className` | `string` | `''` | Additional CSS classes |
|
|
153
|
+
| `style` | `string` | `''` | Inline styles |
|
|
154
|
+
| `emptyMessage` | `string` | `'No items to display.'` | Message when no items |
|
|
155
|
+
| `colWidths` | `object \| Array` | `{}` | _(Legacy)_ Column width configuration (stretch weights or pixel values). Ignored when `columns` is provided. |
|
|
156
|
+
| `selected` | `any` | `null` | Currently selected item |
|
|
157
|
+
| `onselect` | `function` | `undefined` | Callback when a row is selected: `({item, index}) => void` |
|
|
158
|
+
| `onsort` | `function` | `undefined` | Callback when sort changes: `({key, dir}) => void`. When provided, local sorting is skipped (server-side sort pattern). Omit entirely (do not pass `() => {}`) to enable local sorting. |
|
|
159
|
+
| `inlineFilters` | `boolean` | `false` | Renders column filter buttons in table headers. Without `onfilter`, filters are applied locally to `items`. |
|
|
160
|
+
| `columnFilters` | `Array \| null` | `null` | Optional explicit filter configurations, usually from `buildColumnFilters(rows, columns)`. Overrides derived filter options. |
|
|
161
|
+
| `filterItems` | `Array \| null` | `null` | Base data source used to derive inline filter options when `columnFilters` is omitted. Defaults to `items`; pass the unpaged/search-scoped rows when `items` is paged. |
|
|
162
|
+
| `activeFilters` | `Object` | `{}` | Controlled filter state for inline header filters. |
|
|
163
|
+
| `onfilter` | `function` | `undefined` | Callback when inline filters change: `({key, values, allFilters}) => void`. When provided, parent code is responsible for applying filters. |
|
|
164
|
+
| `rowSnippet` | `Snippet` | `undefined` | Svelte 5 snippet for rendering rows. Optional when `columns` is provided (a default row is rendered using each column's `cellSnippet` or raw value). |
|
|
165
|
+
| `density` | `'comfortable' \| 'compact'` | `'comfortable'` | Row density. `'compact'` tightens the body cell padding so more rows fit. |
|
|
166
|
+
| `resizable` | `boolean` | `false` | Drag a header's right edge to resize its column. See [Resizable columns](#resizable-columns). |
|
|
167
|
+
| `columnWidths` | `Record<string, number>` | `{}` | User column widths in px; supports `bind:columnWidths`. Empty means the declared widths. |
|
|
168
|
+
| `oncolumnresize` | `function` | `undefined` | Called when a resize ends: `({key, width, widths}) => void`. |
|
|
169
|
+
| `storageKey` | `string` | `undefined` | Save `columnWidths` to `localStorage` (`svelte-vtable:column-widths:<storageKey>`) and restore them on mount. |
|
|
170
|
+
| `wrap` | `boolean` | `true` | Wrap long cell text. `false` keeps cells on one line; cut-off text gets a tooltip. See [Long text](#long-text-wrap-or-truncate). |
|
|
166
171
|
|
|
167
172
|
#### Row Snippet Parameters
|
|
168
173
|
|
|
@@ -181,17 +186,20 @@ The `rowSnippet` receives an object with:
|
|
|
181
186
|
// @type {import('@zhangt58/svelte-vtable').ColumnDef}
|
|
182
187
|
```
|
|
183
188
|
|
|
184
|
-
| Field | Type | Default
|
|
185
|
-
| --------------- | --------------------------------------------------------------- |
|
|
186
|
-
| `key` | `string` | required
|
|
187
|
-
| `label` | `string` | `key`
|
|
188
|
-
| `width` | `number \| string` | `1`
|
|
189
|
-
| `minWidth` | `string` | `undefined`
|
|
190
|
-
| `sticky` | `'left' \| 'right'` | `undefined`
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
189
|
+
| Field | Type | Default | Description |
|
|
190
|
+
| --------------- | --------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
191
|
+
| `key` | `string` | required | Data key. Must match a property on the row item. |
|
|
192
|
+
| `label` | `string` | `key` | Column header label. Defaults to `key`. |
|
|
193
|
+
| `width` | `number \| string` | `1` | Stretch weight (number) or CSS value (e.g. `'120px'`). A CSS length is also the column's minimum width. |
|
|
194
|
+
| `minWidth` | `string` | `undefined` | Minimum width as a CSS length (e.g. `'12rem'`). When the minimums exceed the container, the table scrolls sideways. |
|
|
195
|
+
| `sticky` | `'left' \| 'right'` | `undefined` | Keep the column in view while the table scrolls sideways. See [Sticky columns](#sticky-columns). |
|
|
196
|
+
| `group` | `string` | `undefined` | Group label shown in a header row above this column; adjacent columns with the same group share one cell. See [Grouped headers](#grouped-headers). |
|
|
197
|
+
| `resizable` | `boolean` | `true` | Set `false` to keep this column's resize handle off when the table is `resizable`. |
|
|
198
|
+
| `wrap` | `boolean` | table `wrap` | Per-column override of the table's `wrap`. |
|
|
199
|
+
| `sortable` | `boolean` | `true` | Whether clicking the header sorts the table. |
|
|
200
|
+
| `filterType` | `'value' \| 'list' \| 'daterange' \| 'datetimerange' \| 'none'` | `'value'` | Filter UI for this column. `'list'` is an alias for value-list filters; `'none'` excludes it from `buildColumnFilters`. |
|
|
201
|
+
| `headerSnippet` | `Snippet<[{key, label, sortKey, sortDir}]>` | `undefined` | Custom Svelte 5 snippet rendered inside `<th>`. |
|
|
202
|
+
| `cellSnippet` | `Snippet<[{item, value, index}]>` | `undefined` | Custom Svelte 5 snippet rendered inside each `<td>`. Used for default row rendering when `rowSnippet` is not provided. |
|
|
195
203
|
|
|
196
204
|
#### Minimal example using `columns`
|
|
197
205
|
|
|
@@ -291,6 +299,68 @@ const columns = [
|
|
|
291
299
|
while it is scrolled away from the start / not at the end, for custom styling.
|
|
292
300
|
- Sticky body cells take their row's background (striping, hover, selection).
|
|
293
301
|
|
|
302
|
+
#### Resizable columns
|
|
303
|
+
|
|
304
|
+
With `resizable`, every header gets a handle on its right edge (`ColumnDef.resizable: false`
|
|
305
|
+
opts a column out):
|
|
306
|
+
|
|
307
|
+
- Drag it to resize the column, down to 40px. A user width may go below the column's
|
|
308
|
+
`minWidth` (or CSS width): those size the declared layout only.
|
|
309
|
+
- Double-click a handle to drop all user widths and return to the declared layout
|
|
310
|
+
(same as setting `columnWidths = {}`).
|
|
311
|
+
|
|
312
|
+
The first resize pins every column at its current width (in px) and switches the table
|
|
313
|
+
to a fixed layout whose width is the sum of the column widths: the table scrolls
|
|
314
|
+
sideways when wider than its container and leaves space on the right when narrower.
|
|
315
|
+
Columns without a user width (e.g. shown later) take their CSS `width`/`minWidth`, else
|
|
316
|
+
`10rem`.
|
|
317
|
+
|
|
318
|
+
Widths are kept in `columnWidths` (`bind:columnWidths`, or `oncolumnresize` when a resize
|
|
319
|
+
ends). Pass `storageKey` to save them per table in `localStorage`:
|
|
320
|
+
|
|
321
|
+
```svelte
|
|
322
|
+
<DataTable {items} {columns} resizable storageKey="orders" bind:columnWidths />
|
|
323
|
+
<button onclick={() => (columnWidths = {})}>Reset widths</button>
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
#### Grouped headers
|
|
327
|
+
|
|
328
|
+
Give columns a `group` to draw a header row above the column headers, with one cell
|
|
329
|
+
spanning each run of adjacent columns of the same group:
|
|
330
|
+
|
|
331
|
+
```js
|
|
332
|
+
const columns = [
|
|
333
|
+
{ key: 'id', label: 'Order' }, // no group: empty cell above
|
|
334
|
+
{ key: 'customer', label: 'Name', group: 'Customer' },
|
|
335
|
+
{ key: 'email', label: 'Email', group: 'Customer' },
|
|
336
|
+
{ key: 'status', label: 'Status', group: 'Order' },
|
|
337
|
+
{ key: 'total', label: 'Total', group: 'Order' },
|
|
338
|
+
{ key: 'carrier', label: 'Carrier', group: 'Delivery' },
|
|
339
|
+
];
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
- The group row sticks to the top together with the column headers.
|
|
343
|
+
- Groups follow the column order: the same group in two separate runs gets two cells.
|
|
344
|
+
- A run of sticky and non-sticky columns is split at the boundary so the sticky part
|
|
345
|
+
sticks with its columns; the label sits on the first part.
|
|
346
|
+
|
|
347
|
+
#### Long text: wrap or truncate
|
|
348
|
+
|
|
349
|
+
Cells wrap long text by default. With `wrap={false}` (or `ColumnDef.wrap: false` for one
|
|
350
|
+
column) cells stay on one line, columns keep their declared widths regardless of
|
|
351
|
+
content, and long text ends in an ellipsis — handy for a per-table "wrap long text"
|
|
352
|
+
toggle:
|
|
353
|
+
|
|
354
|
+
```svelte
|
|
355
|
+
<label><input type="checkbox" bind:checked={wrapText} /> Wrap long text</label>
|
|
356
|
+
<DataTable {items} {columns} wrap={wrapText} />
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
Hovering a cell whose text is cut off shows the full text in a tooltip, in either mode.
|
|
360
|
+
This also covers truncation inside a `cellSnippet` (e.g. a `truncate` or `line-clamp`
|
|
361
|
+
element) and truncated header labels. A `title` you set on a cell's content takes
|
|
362
|
+
precedence.
|
|
363
|
+
|
|
294
364
|
#### Row Snippet Parameters
|
|
295
365
|
|
|
296
366
|
The `rowSnippet` receives an object with:
|
|
@@ -483,9 +553,14 @@ svelte-vtable exposes a set of CSS custom properties (variables) as its theming
|
|
|
483
553
|
|
|
484
554
|
--vtable-radius: 0.375rem; /* rounded-md */
|
|
485
555
|
--vtable-row-height: 2.25rem; /* virtual-scroll row height hint */
|
|
556
|
+
|
|
557
|
+
--vtable-resize-line: #cbd5e1; /* column resize separator (gray-600 in dark mode) */
|
|
558
|
+
--vtable-resize-line-hover: #64748b; /* … while its header is hovered (gray-400 dark) */
|
|
486
559
|
}
|
|
487
560
|
```
|
|
488
561
|
|
|
562
|
+
The resize separator turns `--vtable-color-accent-border` on the handle and while dragging.
|
|
563
|
+
|
|
489
564
|
### Overriding the theme
|
|
490
565
|
|
|
491
566
|
Set any property on `:root` for a global override, or on a wrapper element for a scoped override:
|
|
@@ -526,6 +601,22 @@ The live example at `examples/ThemedExample.svelte` lets you switch between gree
|
|
|
526
601
|
|
|
527
602
|
The library is written in JavaScript with JSDoc annotations. Type checking is available via `svelte-check`.
|
|
528
603
|
|
|
604
|
+
## Local development
|
|
605
|
+
|
|
606
|
+
A `Makefile` wraps the npm scripts (`make` lists the targets):
|
|
607
|
+
|
|
608
|
+
| Target | What it does |
|
|
609
|
+
| -------------- | ---------------------------------------------------------------------------- |
|
|
610
|
+
| `make install` | Install dependencies for the library and `examples/` |
|
|
611
|
+
| `make dev` | Build `dist/`, rebuild it on every change in `src/lib`, and run the examples |
|
|
612
|
+
| `make build` | Build `dist/` (components and the compiled `styles.css`) |
|
|
613
|
+
| `make verify` | Build, type-check and test |
|
|
614
|
+
| `make pack` | Show what `npm publish` would ship |
|
|
615
|
+
|
|
616
|
+
The examples always use the built `dist/`, like a consumer would: with `make dev` an edit
|
|
617
|
+
in `src/lib` rebuilds `dist/` and the example page reloads. `PORT=5174 make dev` picks
|
|
618
|
+
another port (default 5173).
|
|
619
|
+
|
|
529
620
|
## License
|
|
530
621
|
|
|
531
622
|
MIT © [zhangt58](https://github.com/zhangt58)
|