@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.
Files changed (36) hide show
  1. package/README.md +177 -44
  2. package/dist/components/DataTable.svelte +489 -0
  3. package/dist/components/DataTable.svelte.d.ts +31 -0
  4. package/dist/components/DataTableControls.svelte +576 -0
  5. package/dist/components/DataTableControls.svelte.d.ts +39 -0
  6. package/dist/components/DataTableFilters.svelte +215 -0
  7. package/dist/components/DataTableFilters.svelte.d.ts +37 -0
  8. package/dist/components/FiltersModal.svelte +65 -0
  9. package/dist/components/FiltersModal.svelte.d.ts +25 -0
  10. package/dist/components/PaginationBar.svelte +86 -0
  11. package/dist/components/PaginationBar.svelte.d.ts +15 -0
  12. package/dist/components/filters/FilterColumn.svelte +53 -0
  13. package/dist/components/filters/FilterColumn.svelte.d.ts +19 -0
  14. package/dist/components/filters/FilterDateRange.svelte +341 -0
  15. package/dist/components/filters/FilterDateRange.svelte.d.ts +19 -0
  16. package/dist/components/filters/FilterValueList.svelte +437 -0
  17. package/dist/components/filters/FilterValueList.svelte.d.ts +33 -0
  18. package/dist/components/filters/useFilterState.svelte.d.ts +25 -0
  19. package/dist/components/filters/useFilterState.svelte.js +132 -0
  20. package/dist/components/flowbite/DataTableControls.svelte +525 -0
  21. package/dist/components/flowbite/DataTableControls.svelte.d.ts +39 -0
  22. package/{src/components → dist/components/flowbite}/FiltersModal.svelte +5 -15
  23. package/dist/components/flowbite/FiltersModal.svelte.d.ts +25 -0
  24. package/dist/filterUtils.d.ts +76 -0
  25. package/{src/lib → dist}/filterUtils.js +48 -46
  26. package/dist/index.d.ts +60 -0
  27. package/dist/index.flowbite.d.ts +3 -0
  28. package/dist/index.flowbite.js +9 -0
  29. package/dist/index.js +49 -0
  30. package/{src/lib → dist}/styles.css +26 -3
  31. package/package.json +38 -17
  32. package/src/components/DataTable.svelte +0 -252
  33. package/src/components/DataTableControls.svelte +0 -500
  34. package/src/components/DataTableFilters.svelte +0 -1225
  35. package/src/lib/dist/styles.css +0 -273
  36. 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 to be installed in your project:
24
+ This library requires the following peer dependencies:
25
25
 
26
26
  ```bash
27
- npm install svelte@^5.0.0 tailwindcss@^4.0.0 flowbite-svelte@^1.0.0 flowbite-svelte-icons@^3.0.0 svelte-virtuallists@^1.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
- filterChange={({ allFilters }) => (activeFilters = allFilters)}
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
- pagechange={(e) => (ui.currentPage = e.currentPage)}
74
- searchchange={(e) => (ui.searchQuery = e.search)}
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
- sortCallback={(key) => {
84
- /* handle sort */
83
+ bind:sortKey={ui.sortKey}
84
+ bind:sortDir={ui.sortDir}
85
+ onsort={({ key, dir }) => {
86
+ /* optionally trigger a server fetch here */
85
87
  }}
86
- selectCallback={(detail) => {
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 | Type | Default | Description |
110
- | ---------------- | ----------------- | ------------------------ | ------------------------------------------------------------ |
111
- | `items` | `Array` | `[]` | Array of data items to display |
112
- | `visibleKeys` | `Array` | `[]` | Array of keys/titles to display as column headers |
113
- | `sortKey` | `string \| null` | `null` | Current sort key (column header) |
114
- | `sortDir` | `'asc' \| 'desc'` | `'asc'` | Sort direction |
115
- | `className` | `string` | `''` | Additional CSS classes |
116
- | `style` | `string` | `''` | Inline styles |
117
- | `emptyMessage` | `string` | `'No items to display.'` | Message when no items |
118
- | `colWidths` | `object \| Array` | `{}` | Column width configuration (stretch weights or pixel values) |
119
- | `selected` | `any` | `null` | Currently selected item |
120
- | `selectCallback` | `function` | `() => {}` | Callback when a row is selected: `({item, index}) => void` |
121
- | `sortCallback` | `function` | `defaultSort` | Callback when sorting: `(headerKey) => void` |
122
- | `rowSnippet` | `Snippet` | required | Svelte 5 snippet for rendering rows |
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 | Type | Default | Description |
201
- | -------------- | ---------- | ---------- | ---------------------------------------------------- |
202
- | `search` | `string` | `''` | Current search query |
203
- | `currentPage` | `number` | `1` | Current page number |
204
- | `perPage` | `number` | `25` | Items per page |
205
- | `totalItems` | `number` | `0` | Total number of items |
206
- | `pagechange` | `function` | `() => {}` | Callback for page changes: `({currentPage}) => void` |
207
- | `searchchange` | `function` | `() => {}` | Callback for search changes: `({search}) => void` |
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
- | `filterChange` | `function` | `() => {}` | Callback when filters change |
221
- | `className` | `string` | `''` | Additional CSS classes |
222
- | `showCounts` | `boolean` | `true` | Whether to show value counts |
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
- filterChange={({ allFilters }) => (activeFilters = allFilters)}
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
- ## CSS Custom Properties
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
- Override these CSS variables to customize appearance:
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
- --tbl-head-bg: #f8f9fa; /* Header background */
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`.