@zhangt58/svelte-vtable 0.4.3 → 0.5.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 CHANGED
@@ -142,26 +142,32 @@ A virtualized table component for efficient rendering of large datasets. The com
142
142
 
143
143
  #### Props
144
144
 
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). |
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). |
165
171
 
166
172
  #### Row Snippet Parameters
167
173
 
@@ -180,15 +186,20 @@ The `rowSnippet` receives an object with:
180
186
  // @type {import('@zhangt58/svelte-vtable').ColumnDef}
181
187
  ```
182
188
 
183
- | Field | Type | Default | Description |
184
- | --------------- | --------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
185
- | `key` | `string` | required | Data key. Must match a property on the row item. |
186
- | `label` | `string` | `key` | Column header label. Defaults to `key`. |
187
- | `width` | `number \| string` | `1` | Stretch weight (number) or CSS value (e.g. `'120px'`). |
188
- | `sortable` | `boolean` | `true` | Whether clicking the header sorts the table. |
189
- | `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`. |
190
- | `headerSnippet` | `Snippet<[{key, label, sortKey, sortDir}]>` | `undefined` | Custom Svelte 5 snippet rendered inside `<th>`. |
191
- | `cellSnippet` | `Snippet<[{item, value, index}]>` | `undefined` | Custom Svelte 5 snippet rendered inside each `<td>`. Used for default row rendering when `rowSnippet` is not provided. |
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. |
192
203
 
193
204
  #### Minimal example using `columns`
194
205
 
@@ -262,6 +273,94 @@ Column widths can be specified as:
262
273
  - **Stretch weights** (numbers): Distributed proportionally, e.g., `{ name: 1, description: 3 }`
263
274
  - **Pixel values** (strings): Fixed widths, e.g., `{ id: '80px', name: '200px' }`
264
275
 
276
+ A CSS-length width (or `minWidth`) is a real minimum: when the columns' minimums are
277
+ wider than the container, the table scrolls sideways instead of squeezing them.
278
+
279
+ #### Sticky columns
280
+
281
+ Set `sticky: 'left'` or `sticky: 'right'` on a column to keep it in view while the
282
+ table scrolls sideways — e.g. an identifier and a name on the left, row actions on
283
+ the right:
284
+
285
+ ```js
286
+ const columns = [
287
+ { key: 'id', label: 'ID', width: '80px', sticky: 'left' },
288
+ { key: 'name', label: 'Name', width: '200px', sticky: 'left' },
289
+ // … wide columns …
290
+ { key: 'actions', label: 'Actions', width: '140px', sticky: 'right' },
291
+ ];
292
+ ```
293
+
294
+ - Several columns may stick per side; their offsets are measured, so any width type works.
295
+ - Put left-sticky columns first and right-sticky columns last: a sticky cell only stays
296
+ within its row, so a right-sticky column in the middle still scrolls off to the left.
297
+ - The innermost sticky column of each side casts a soft shadow while columns are
298
+ scrolled under it. The table root carries `data-scrolled-start` / `data-scrolled-end`
299
+ while it is scrolled away from the start / not at the end, for custom styling.
300
+ - Sticky body cells take their row's background (striping, hover, selection).
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
+
265
364
  #### Row Snippet Parameters
266
365
 
267
366
  The `rowSnippet` receives an object with:
@@ -454,9 +553,14 @@ svelte-vtable exposes a set of CSS custom properties (variables) as its theming
454
553
 
455
554
  --vtable-radius: 0.375rem; /* rounded-md */
456
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) */
457
559
  }
458
560
  ```
459
561
 
562
+ The resize separator turns `--vtable-color-accent-border` on the handle and while dragging.
563
+
460
564
  ### Overriding the theme
461
565
 
462
566
  Set any property on `:root` for a global override, or on a wrapper element for a scoped override:
@@ -497,6 +601,22 @@ The live example at `examples/ThemedExample.svelte` lets you switch between gree
497
601
 
498
602
  The library is written in JavaScript with JSDoc annotations. Type checking is available via `svelte-check`.
499
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
+
500
620
  ## License
501
621
 
502
622
  MIT © [zhangt58](https://github.com/zhangt58)