@zhangt58/svelte-vtable 0.1.4 → 0.3.1
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 +177 -44
- package/dist/components/DataTable.svelte +489 -0
- package/dist/components/DataTable.svelte.d.ts +31 -0
- package/dist/components/DataTableControls.svelte +576 -0
- package/dist/components/DataTableControls.svelte.d.ts +39 -0
- package/dist/components/DataTableFilters.svelte +215 -0
- package/dist/components/DataTableFilters.svelte.d.ts +37 -0
- package/dist/components/FiltersModal.svelte +65 -0
- package/dist/components/FiltersModal.svelte.d.ts +25 -0
- package/dist/components/PaginationBar.svelte +86 -0
- package/dist/components/PaginationBar.svelte.d.ts +15 -0
- package/dist/components/filters/FilterColumn.svelte +53 -0
- package/dist/components/filters/FilterColumn.svelte.d.ts +19 -0
- package/dist/components/filters/FilterDateRange.svelte +341 -0
- package/dist/components/filters/FilterDateRange.svelte.d.ts +19 -0
- package/dist/components/filters/FilterValueList.svelte +437 -0
- package/dist/components/filters/FilterValueList.svelte.d.ts +33 -0
- package/dist/components/filters/useFilterState.svelte.d.ts +25 -0
- package/dist/components/filters/useFilterState.svelte.js +132 -0
- package/dist/components/flowbite/DataTableControls.svelte +525 -0
- package/dist/components/flowbite/DataTableControls.svelte.d.ts +39 -0
- package/{src/components → dist/components/flowbite}/FiltersModal.svelte +5 -15
- package/dist/components/flowbite/FiltersModal.svelte.d.ts +25 -0
- package/dist/filterUtils.d.ts +76 -0
- package/{src/lib → dist}/filterUtils.js +48 -46
- package/dist/index.d.ts +60 -0
- package/dist/index.flowbite.d.ts +3 -0
- package/dist/index.flowbite.js +9 -0
- package/dist/index.js +49 -0
- package/{src/lib → dist}/styles.css +26 -3
- package/package.json +38 -17
- package/src/components/DataTable.svelte +0 -252
- package/src/components/DataTableControls.svelte +0 -500
- package/src/components/DataTableFilters.svelte +0 -1225
- package/src/lib/dist/styles.css +0 -273
- package/src/lib/index.js +0 -16
package/README.md
CHANGED
|
@@ -21,12 +21,14 @@ npm install @zhangt58/svelte-vtable
|
|
|
21
21
|
|
|
22
22
|
## Peer Dependencies
|
|
23
23
|
|
|
24
|
-
This library requires the following peer dependencies
|
|
24
|
+
This library requires the following peer dependencies:
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
|
-
npm install svelte@^5.0.0 tailwindcss@^4.0.0
|
|
27
|
+
npm install svelte@^5.0.0 tailwindcss@^4.0.0 svelte-virtuallists@^1.0.0
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
+
`flowbite-svelte` and `flowbite-svelte-icons` are **optional** — only needed if you use the Flowbite adapter (see [Flowbite Adapter](#flowbite-adapter)).
|
|
31
|
+
|
|
30
32
|
## Quick Start
|
|
31
33
|
|
|
32
34
|
```svelte
|
|
@@ -61,7 +63,7 @@ npm install svelte@^5.0.0 tailwindcss@^4.0.0 flowbite-svelte@^1.0.0 flowbite-sve
|
|
|
61
63
|
<DataTableFilters
|
|
62
64
|
{columnFilters}
|
|
63
65
|
{activeFilters}
|
|
64
|
-
|
|
66
|
+
onfilter={({ allFilters }) => (activeFilters = allFilters)}
|
|
65
67
|
/>
|
|
66
68
|
|
|
67
69
|
<!-- Search and pagination controls -->
|
|
@@ -70,20 +72,20 @@ npm install svelte@^5.0.0 tailwindcss@^4.0.0 flowbite-svelte@^1.0.0 flowbite-sve
|
|
|
70
72
|
currentPage={ui.currentPage}
|
|
71
73
|
perPage={ui.perPage}
|
|
72
74
|
totalItems={items.length}
|
|
73
|
-
|
|
74
|
-
|
|
75
|
+
onpage={({ page }) => (ui.currentPage = page)}
|
|
76
|
+
onsearch={({ search }) => (ui.searchQuery = search)}
|
|
75
77
|
/>
|
|
76
78
|
|
|
77
79
|
<!-- Virtualized table -->
|
|
78
80
|
<DataTable
|
|
79
81
|
{items}
|
|
80
82
|
{visibleKeys}
|
|
81
|
-
sortKey={ui.sortKey}
|
|
82
|
-
sortDir={ui.sortDir}
|
|
83
|
-
|
|
84
|
-
/*
|
|
83
|
+
bind:sortKey={ui.sortKey}
|
|
84
|
+
bind:sortDir={ui.sortDir}
|
|
85
|
+
onsort={({ key, dir }) => {
|
|
86
|
+
/* optionally trigger a server fetch here */
|
|
85
87
|
}}
|
|
86
|
-
|
|
88
|
+
onselect={({ item, index }) => {
|
|
87
89
|
/* handle selection */
|
|
88
90
|
}}
|
|
89
91
|
{colWidths}
|
|
@@ -98,28 +100,64 @@ npm install svelte@^5.0.0 tailwindcss@^4.0.0 flowbite-svelte@^1.0.0 flowbite-sve
|
|
|
98
100
|
</DataTable>
|
|
99
101
|
```
|
|
100
102
|
|
|
103
|
+
## Flowbite Adapter
|
|
104
|
+
|
|
105
|
+
By default, `DataTableControls` uses **zero external UI-framework dependencies** — it renders using plain `<input>`, `<select>`, `<button>`, and `<nav>` elements with Tailwind utility classes.
|
|
106
|
+
|
|
107
|
+
If your project already uses **Flowbite**, you can opt in to the Flowbite-flavoured controls by importing from the `/flowbite` entrypoint:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# Install optional Flowbite peer dependencies
|
|
111
|
+
npm install flowbite-svelte@^1.0.0 flowbite-svelte-icons@^3.0.0
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
```svelte
|
|
115
|
+
<script>
|
|
116
|
+
// Import Flowbite-flavoured DataTableControls (Search, Badge, Select, Modal)
|
|
117
|
+
import { DataTable, DataTableControls, DataTableFilters } from '@zhangt58/svelte-vtable/flowbite';
|
|
118
|
+
</script>
|
|
119
|
+
|
|
120
|
+
<DataTableControls
|
|
121
|
+
search={searchQuery}
|
|
122
|
+
{currentPage}
|
|
123
|
+
bind:perPage
|
|
124
|
+
totalItems={items.length}
|
|
125
|
+
onpage={({ page }) => (currentPage = page)}
|
|
126
|
+
onsearch={({ search }) => (searchQuery = search)}
|
|
127
|
+
{columnFilters}
|
|
128
|
+
{activeFilters}
|
|
129
|
+
onfilter={handleFilterChange}
|
|
130
|
+
/>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The Flowbite entrypoint re-exports everything from the default entrypoint, so you can use a single import for all components and utilities.
|
|
134
|
+
|
|
135
|
+
See [`examples/flowbite/App.svelte`](./examples/flowbite/App.svelte) for a complete working example.
|
|
136
|
+
|
|
101
137
|
## Components
|
|
102
138
|
|
|
103
139
|
### DataTable (previously named VirtualDataTable)
|
|
104
140
|
|
|
105
141
|
A virtualized table component for efficient rendering of large datasets. The component was renamed to `DataTable`; `VirtualDataTable` is still exported for backward compatibility.
|
|
106
142
|
|
|
143
|
+
|
|
107
144
|
#### Props
|
|
108
145
|
|
|
109
|
-
| Prop
|
|
110
|
-
|
|
|
111
|
-
| `items`
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
146
|
+
| Prop | Type | Default | Description |
|
|
147
|
+
| -------------- | ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
148
|
+
| `items` | `Array` | `[]` | Array of data items to display |
|
|
149
|
+
| `columns` | `ColumnDef[]` | `undefined` | **Unified column definitions** (recommended). When provided, `visibleKeys`, `colWidths`, and `rowSnippet` may be omitted. See [ColumnDef](#columndef) below. |
|
|
150
|
+
| `visibleKeys` | `Array` | `[]` | _(Legacy)_ Array of keys to display as column headers. Ignored when `columns` is provided. |
|
|
151
|
+
| `sortKey` | `string \| null` | `null` | Current sort key (column header); supports `bind:sortKey` |
|
|
152
|
+
| `sortDir` | `'asc' \| 'desc'` | `'asc'` | Sort direction; supports `bind:sortDir` |
|
|
153
|
+
| `className` | `string` | `''` | Additional CSS classes |
|
|
154
|
+
| `style` | `string` | `''` | Inline styles |
|
|
155
|
+
| `emptyMessage` | `string` | `'No items to display.'` | Message when no items |
|
|
156
|
+
| `colWidths` | `object \| Array` | `{}` | _(Legacy)_ Column width configuration (stretch weights or pixel values). Ignored when `columns` is provided. |
|
|
157
|
+
| `selected` | `any` | `null` | Currently selected item |
|
|
158
|
+
| `onselect` | `function` | `undefined` | Callback when a row is selected: `({item, index}) => void` |
|
|
159
|
+
| `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. |
|
|
160
|
+
| `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). |
|
|
123
161
|
|
|
124
162
|
#### Row Snippet Parameters
|
|
125
163
|
|
|
@@ -130,6 +168,50 @@ The `rowSnippet` receives an object with:
|
|
|
130
168
|
- `select` - Function to call to select this row
|
|
131
169
|
- `selected` - Currently selected item (for comparison)
|
|
132
170
|
|
|
171
|
+
### ColumnDef
|
|
172
|
+
|
|
173
|
+
`ColumnDef` is the unified column configuration object. Import the JSDoc type via:
|
|
174
|
+
|
|
175
|
+
```js
|
|
176
|
+
// @type {import('@zhangt58/svelte-vtable').ColumnDef}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
| Field | Type | Default | Description |
|
|
180
|
+
| --------------- | ----------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| `key` | `string` | required | Data key. Must match a property on the row item. |
|
|
182
|
+
| `label` | `string` | `key` | Column header label. Defaults to `key`. |
|
|
183
|
+
| `width` | `number \| string` | `1` | Stretch weight (number) or CSS value (e.g. `'120px'`). |
|
|
184
|
+
| `sortable` | `boolean` | `true` | Whether clicking the header sorts the table. |
|
|
185
|
+
| `filterType` | `'value' \| 'daterange' \| 'datetimerange' \| 'none'` | `'value'` | Filter UI for this column. `'none'` excludes it from `buildColumnFilters`. |
|
|
186
|
+
| `headerSnippet` | `Snippet<[{key, label, sortKey, sortDir}]>` | `undefined` | Custom Svelte 5 snippet rendered inside `<th>`. |
|
|
187
|
+
| `cellSnippet` | `Snippet<[{item, value, index}]>` | `undefined` | Custom Svelte 5 snippet rendered inside each `<td>`. Used for default row rendering when `rowSnippet` is not provided. |
|
|
188
|
+
|
|
189
|
+
#### Minimal example using `columns`
|
|
190
|
+
|
|
191
|
+
```svelte
|
|
192
|
+
<script>
|
|
193
|
+
import { DataTable, buildColumnFilters, applyFilters } from '@zhangt58/svelte-vtable';
|
|
194
|
+
|
|
195
|
+
const items = [...]; // your data
|
|
196
|
+
|
|
197
|
+
/** @type {import('@zhangt58/svelte-vtable').ColumnDef[]} */
|
|
198
|
+
const columns = [
|
|
199
|
+
{ key: 'id', label: 'ID', width: 1, filterType: 'none' },
|
|
200
|
+
{ key: 'name', label: 'Name', width: 3, filterType: 'none' },
|
|
201
|
+
{ key: 'department', label: 'Department', width: 2, filterType: 'value' },
|
|
202
|
+
{ key: 'hireDate', label: 'Hire Date', width: 2, filterType: 'daterange' },
|
|
203
|
+
];
|
|
204
|
+
|
|
205
|
+
// Build filters directly from columns — filterType:'none' columns are skipped automatically
|
|
206
|
+
let columnFilters = buildColumnFilters(items, columns);
|
|
207
|
+
let activeFilters = $state({});
|
|
208
|
+
const filteredItems = $derived(applyFilters(items, activeFilters));
|
|
209
|
+
</script>
|
|
210
|
+
|
|
211
|
+
<!-- No visibleKeys, colWidths, or rowSnippet required -->
|
|
212
|
+
<DataTable items={filteredItems()} {columns} style="height: 400px" />
|
|
213
|
+
```
|
|
214
|
+
|
|
133
215
|
### Filter example (filterCallback)
|
|
134
216
|
|
|
135
217
|
Below is a minimal example showing how to wire the `filterCallback` prop on `VirtualDataTable` to apply per-column inline filters emitted by the header inputs. The idea: keep a small `filters` map in your component, compute a derived `filteredItems` list, and update `filters` when the table emits a column filter change.
|
|
@@ -197,14 +279,17 @@ Controls component for search and pagination.
|
|
|
197
279
|
|
|
198
280
|
#### Props
|
|
199
281
|
|
|
200
|
-
| Prop
|
|
201
|
-
|
|
|
202
|
-
| `search`
|
|
203
|
-
| `currentPage`
|
|
204
|
-
| `perPage`
|
|
205
|
-
| `totalItems`
|
|
206
|
-
| `
|
|
207
|
-
| `
|
|
282
|
+
| Prop | Type | Default | Description |
|
|
283
|
+
| ----------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------- |
|
|
284
|
+
| `search` | `string` | `''` | Current search query |
|
|
285
|
+
| `currentPage` | `number` | `1` | Current page number |
|
|
286
|
+
| `perPage` | `number` | `25` | Items per page |
|
|
287
|
+
| `totalItems` | `number` | `0` | Total number of items |
|
|
288
|
+
| `onpage` | `function` | `undefined` | Callback for page changes: `({page}) => void` |
|
|
289
|
+
| `onsearch` | `function` | `undefined` | Callback for search changes: `({search}) => void` |
|
|
290
|
+
| `onfilterstoggle` | `function` | `undefined` | Callback when filters panel toggled: `({visible}) => void` |
|
|
291
|
+
| `onperpage` | `function` | `undefined` | Callback when per-page changes: `({perPage}) => void` |
|
|
292
|
+
| `onfilter` | `function` | `undefined` | Callback when filters change (passed through to DataTableFilters): `({key, values, allFilters}) => void` |
|
|
208
293
|
|
|
209
294
|
### DataTableFilters
|
|
210
295
|
|
|
@@ -212,14 +297,15 @@ Multi-select filter component with flexible layout options. Implements OR logic
|
|
|
212
297
|
|
|
213
298
|
#### Props
|
|
214
299
|
|
|
215
|
-
| Prop | Type | Default | Description
|
|
216
|
-
| --------------- | ---------------------------- | -------------- |
|
|
217
|
-
| `columnFilters` | `Array` | `[]` | Array of filter configurations (see below)
|
|
218
|
-
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction for filter grid
|
|
219
|
-
| `activeFilters` | `Object` | `{}` | Current active filters `{ columnKey: [selectedValues] }`
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
300
|
+
| Prop | Type | Default | Description |
|
|
301
|
+
| --------------- | ---------------------------- | -------------- | ------------------------------------------------------------------- |
|
|
302
|
+
| `columnFilters` | `Array` | `[]` | Array of filter configurations (see below) |
|
|
303
|
+
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction for filter grid |
|
|
304
|
+
| `activeFilters` | `Object` | `{}` | Current active filters `{ columnKey: [selectedValues] }` |
|
|
305
|
+
| `onfilter` | `function` | `undefined` | Callback when filters change: `({key, values, allFilters}) => void` |
|
|
306
|
+
| `oncolumnsort` | `function` | `undefined` | Callback when column sort changes: `({key, mode, dir}) => void` |
|
|
307
|
+
| `className` | `string` | `''` | Additional CSS classes |
|
|
308
|
+
| `showCounts` | `boolean` | `true` | Whether to show value counts |
|
|
223
309
|
|
|
224
310
|
#### columnFilters Structure
|
|
225
311
|
|
|
@@ -284,7 +370,7 @@ Example usage with data filtering:
|
|
|
284
370
|
<DataTableFilters
|
|
285
371
|
{columnFilters}
|
|
286
372
|
{activeFilters}
|
|
287
|
-
|
|
373
|
+
onfilter={({ allFilters }) => (activeFilters = allFilters)}
|
|
288
374
|
direction="horizontal"
|
|
289
375
|
showCounts={true}
|
|
290
376
|
/>
|
|
@@ -348,16 +434,63 @@ Optional recommendation: add `prepare` to `package.json` so that `npm install` i
|
|
|
348
434
|
|
|
349
435
|
This is optional — the current `prepublishOnly` is sufficient for publishing.
|
|
350
436
|
|
|
351
|
-
##
|
|
437
|
+
## Theming
|
|
438
|
+
|
|
439
|
+
svelte-vtable exposes a set of CSS custom properties (variables) as its theming contract. All accent-coloured elements (active pagination button, active filter badge, filter button active state, dual-range slider) read from these variables, so you can re-theme the library without forking source or reconfiguring Tailwind.
|
|
440
|
+
|
|
441
|
+
### Default values
|
|
442
|
+
|
|
443
|
+
```css
|
|
444
|
+
:root {
|
|
445
|
+
--vtable-color-accent: #16a34a; /* green-600 — active elements */
|
|
446
|
+
--vtable-color-accent-light: #dcfce7; /* green-100 — active element background */
|
|
447
|
+
--vtable-color-accent-border: #22c55e; /* green-500 — active element border */
|
|
448
|
+
--vtable-color-accent-text: #15803d; /* green-700 — active element text */
|
|
449
|
+
|
|
450
|
+
--vtable-color-danger: #dc2626; /* red-600 — destructive actions */
|
|
451
|
+
--vtable-color-info: #3b82f6; /* blue-500 — dual-range slider */
|
|
452
|
+
|
|
453
|
+
--vtable-radius: 0.375rem; /* rounded-md */
|
|
454
|
+
--vtable-row-height: 2.25rem; /* virtual-scroll row height hint */
|
|
455
|
+
}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### Overriding the theme
|
|
352
459
|
|
|
353
|
-
|
|
460
|
+
Set any property on `:root` for a global override, or on a wrapper element for a scoped override:
|
|
354
461
|
|
|
355
462
|
```css
|
|
463
|
+
/* app.css — global purple theme */
|
|
356
464
|
:root {
|
|
357
|
-
--
|
|
465
|
+
--vtable-color-accent: #7c3aed;
|
|
466
|
+
--vtable-color-accent-light: #ede9fe;
|
|
467
|
+
--vtable-color-accent-border: #8b5cf6;
|
|
468
|
+
--vtable-color-accent-text: #6d28d9;
|
|
358
469
|
}
|
|
359
470
|
```
|
|
360
471
|
|
|
472
|
+
```svelte
|
|
473
|
+
<!-- Scoped to a single section of a page -->
|
|
474
|
+
<div
|
|
475
|
+
style="--vtable-color-accent: #7c3aed; --vtable-color-accent-light: #ede9fe; --vtable-color-accent-border: #8b5cf6; --vtable-color-accent-text: #6d28d9;"
|
|
476
|
+
>
|
|
477
|
+
<DataTableControls ... />
|
|
478
|
+
<DataTable ... />
|
|
479
|
+
</div>
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
### What changes with `--vtable-color-accent`
|
|
483
|
+
|
|
484
|
+
| Element | Before (default green) | After override |
|
|
485
|
+
| ------------------------------------ | ----------------------------- | --------------------------------- |
|
|
486
|
+
| Active pagination button | green-100 bg + green-600 text | `accent-light` bg + `accent` text |
|
|
487
|
+
| Active filter count badge (controls) | green-600 background | `accent` background |
|
|
488
|
+
| Active filter button border | green-500 | `accent-border` |
|
|
489
|
+
| Active filter badge (count / range) | green-600 background | `accent` background |
|
|
490
|
+
| "Show All" button | green-600 border + text | `accent` border + text |
|
|
491
|
+
|
|
492
|
+
The live example at `examples/ThemedExample.svelte` lets you switch between green, purple, orange, and rose themes at runtime.
|
|
493
|
+
|
|
361
494
|
## TypeScript
|
|
362
495
|
|
|
363
496
|
The library is written in JavaScript with JSDoc annotations. Type checking is available via `svelte-check`.
|