svelte-tably 1.0.0-next.8 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Svelte Tably
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,92 +1,299 @@
-# svelte-tably
-
-Work in progress. I needed a break from my primary project, so here's a little side-project exploring the amazing capabilities of Svelte 5 with a Dynamic table!
-
-Example on [Svelte 5 Playground](https://svelte.dev/playground/a16d71c97445455e80a55b77ec1cf915?version=5)
-
-A high performant dynamic table
-
-- [x] Sticky columns
-- [x] Show/hide columns
-- [x] Re-order columns
-- [x] Resize columns
-- [x] Statusbar
-- [x] "Virtual" data (for sorting/filtering)
-- [x] Panels
-- [x] Virtual elements
-- [ ] sorting
-- [x] select
-- [ ] filtering
-- [ ] orderable table
-- [ ] row context-menu
-- [ ] dropout section
-
-### Usage Notes
-
-```html
-<script lang='ts'>
-    import Table from 'svelte-tably'
-
-    const data = $state([
-        { name: 'John Doe', age: 30, email: 'johndoe@example.com' },
-        { name: 'Jane Doe', age: 25, email: 'janedoe@example.com' },
-    ])
-
-    let activePanel = $state('columns') as string | undefined
-	let selected = $state([]) as typeof data
-</script>
-
-<Table {data} panel={activePanel} select bind:selected>
-    {#snippet content({ Column, Panel, state, data })}
-        <Column id='name' sticky>
-            {#snippet header()}
-                Name
-            {/snippet}
-            {#snippet row(row)}
-                {row.name}
-            {/snippet}
-
-            <!-- Optional per column. -->
-            {#snippet statusbar()}
-                {data.length}
-            {/snippet}
-        </Column>
-        <Column ...>
-           ...
-        </Column>
-        <!-- If you want to sort/filter a virtual value, that does not exist in the data -->
-        <Column id='virtual' value={row => row.age > 18}>
-            ...
-            {#snippet row(row, virtual)}
-                {virtual ? 'Adult' : 'Adolescent'}
-            {/snippet}
-            ...
-        </Column>
-
-        <Panel id='columns'>
-            <!-- Anything you might like -->
-        </Panel>
-        <Panel ... backdrop={false}>
-            ...
-        </Panel>
-    {/snippet}
-</Table>
-```
-
-#### Styling
-
-For quick styling
-
-| CSS Variable | Description | Default |
-| - | - | - |
-| --tably-bg | background-color | `hsl(0, 0%, 100%)` |
-| --tably-color | color | `hsl(0, 0%, 0%)` |
-| --tably-border | border | `hsl(0, 0%, 90%)` |
-| --tably-statusbar | background-color for the statusbar | `hsl(0, 0%, 98%)` |
-| --tably-padding-y | Padding above/below each column | `.5rem` |
-| --tably-padding-x | Padding left of each column | `1rem` |
-| --tably-radius | Table radius | `.25rem` |
-
-Advanced styling can be done via `:global .svelte-tably`
-
-
+# Svelte Tably
+
+Via the amazing capabilities braught to us by Svelte 5 — a performant, dynamic, flexible, feature rich table. It's as simple, or as flexible as you need it to be.
+
+Simple example on [Svelte 5 Playground](https://svelte.dev/playground/f79124e8473546d29433a95a68440d6d?version=5.16.0)
+<br>
+Fledged out example on [Svelte 5 Playground](https://svelte.dev/playground/a16d71c97445455e80a55b77ec1cf915?version=5)
+
+- [x] Columns
+    - [x] Sticky
+    - [x] Show/hide
+    - [x] Re-order
+    - [x] Resize
+- [x] Data manipulation
+    - [x] "Virtual" data
+    - [x] Sorting
+    - [x] Select
+    - [x] Filtering
+    - [x] Reorderable
+- [x] Statusbar
+- [x] Panels
+- [x] Row context
+- [x] Expandable rows
+- [x] Virtual rendering
+- [x] To CSV
+- [x] Auto: Create columns based on data
+
+On top of that, the library API is extensive, so the table can meet your needs.
+
+## Usage Notes
+
+`bun add -D svelte-tably`
+
+```html
+<script lang='ts'>
+    import Table from 'svelte-tably'
+
+    const data = $state([
+        { name: 'Giraffe', age: 26, email: 'giraffe@example.com' },
+        { name: 'Shiboo', age: 21, email: 'shiboo@example.com' }
+    ])
+
+    let activePanel = $state('columns') as string | undefined
+    let selected = $state([]) as typeof data
+</script>
+
+<!-- Auto: Generate Columns based on data properties -->
+<Table auto {data} resizeable={false} filters={[...]} />
+
+<Table {data} panel={activePanel} select bind:selected>
+    {#snippet content({ Column, Panel, Expandable, Row, state, table })}
+        <Column id='name' sticky sort value={r => r.name} filter={v => v.includes('Giraffe')}>
+            {#snippet header(ctx)}
+                Name
+            {/snippet}
+            {#snippet row(row, ctx)}
+                {row.name}
+            {/snippet}
+            {#snippet statusbar(ctx)}
+                {table.data.length}
+            {/snippet}
+        </Column>
+        
+        <!-- Simplified -->
+        <Column id='age' header='Age' value={r => r.age} sort={(a,b) => a - b} />
+
+        <Expandable click={false}>
+            {#snippet content(item, ctx)}
+                ...
+            {/snippet}
+        </Expandable>
+
+        <Row onclick={...} oncontextmenu={...}>
+            {#snippet contextHeader()}
+                <button ...> <Icon icon='add' /> </button>
+            {/snippet}
+            {#snippet context(item, ctx)}
+                <button ...> <Icon icon='menu' /> </button>
+            {/snippet}
+        </Row>
+
+        <Panel id='columns'>
+            <!-- Anything you might like -->
+        </Panel>
+        <Panel ... backdrop={false}>
+            ...
+        </Panel>
+    {/snippet}
+</Table>
+```
+
+### Styling
+
+For quick styling
+
+| CSS Variable | Description | Default |
+| - | - | - |
+| --tably-bg | Background color | `hsl(0, 0%, 100%)` |
+| --tably-color | Text color | `hsl(0, 0%, 0%)` |
+| --tably-border | Border for sticky columns and header | `hsl(0, 0%, 90%)` |
+| --tably-border-grid | Border for the table-grid | `hsl(0, 0%, 98%)` |
+| --tably-statusbar | background-color for the statusbar | `hsl(0, 0%, 98%)` |
+| --tably-padding-y | Padding above/below each column | `.5rem` |
+| --tably-padding-x | Padding left of each column | `1rem` |
+| --tably-radius | Table radius | `.25rem` |
+
+> [!TIP]  
+> For the CSS variables, apply them to `:global(:root) { ... }`
+
+> [!NOTE]  
+> Advanced styling can be done via `:global(.svelte-tably)`  
+> `table > thead > tr > th, table > tbody > tr > td, table > tfoot > tr > td`
+
+<br>
+<br>
+
+## Components
+
+All components except Table are meant to be children of the `Table` component.
+
+However, you can safely create a `Component.svelte` and use these components,
+and then provide `<Component/>` as a child to `<Table>`. 
+
+```ts
+import Table from 'svelte-tably'
+```
+
+### Table
+
+The table component.
+
+```html
+<Table auto {data} />
+
+<Table {data} ...>
+    {#snippet content?({ Column, Row, Expandable, Panel, table })}
+        ...
+    {/snippet}
+</Table>
+```
+
+Where `table` is `TableState<T>` and the rest are typed; `Component<T>`.
+
+| Attribute | Description | Type |
+| - | - | - |
+| content? | The contents of the table | `Snippet<[ctx: ContentCtx<T>]>?` |
+|   |  |  |
+| id? | The `#id` for the table | `string` |
+| data | An array of objects for the table | `T[]` |
+| bind:selected? | The currently selected items | `T[]` |
+| bind:panel? | The currently open panel | `string` | 
+| filters? | An array of filters applied to the table | `((item: T) => boolean)[]` |
+| reorderable? | Whether the rows can be re-ordered (via [runic-reorder](https://github.com/Refzlund/runic-reorder)) | `boolean` |
+| resizeable? | Whether or not the columns can be resized | `boolean` |
+| select? | Whether ot not the rows items can be selected | `boolean \| SelectOptions<T>` |
+| auto? | Create missing columns automatically? | `boolean` |
+
+#### SelectOptions
+
+| Properties | Description | Type |
+| - | - | - |
+| show? | When to show the row-select when not selected | `'hover' \| 'always' \| 'never'` |
+| headerSnippet? | Custom snippet for the header select-input | `Snippet<[context: HeaderSelectCtx]>` |
+| rowSnippet? | Custom snippet for the row select-input | `Snippet<[context: RowSelectCtx<T>]>` |
+
+<br>
+
+### Column
+
+```ts
+import { Column } from 'svelte-tably'
+```
+
+This component designates a column where options like sorting, filtering etc. are provided.
+
+```html
+<Column id='...' header='...' value={row => row.value} />
+
+<Column id='...' ...>
+    {#snippet header?(ctx: HeaderCtx<T>)}
+        ...
+    {/snippet}
+    {#snippet row?(item: T, ctx: RowColumnCtx<T>)}
+        ...
+    {/snippet}
+    {#snippet statusbar?(ctx: StatusbarCtx<T>)}
+        ...
+    {/snippet}
+</Column>
+```
+
+| Attribute | Description | Type |
+| - | - | - |
+| header? | The header element/contents | `string \| Snippet<[ctx: HeaderCtx<T>]>` |
+| row? | The row element. If not provided, `value: V` will be used. | `Snippet<[item: T, ctx: RowColumnCtx<T, V>]>` |
+| statusbar? | The statusbar element | `Snippet<[ctx: StatusbarCtx<T>]>` |
+|   |  |  |
+| sticky? | Should be sticky by default | `boolean` |
+| show? | Should be visible by default | `boolean` |
+| sortby? | Should sort by this by default | `boolean` |
+| width? | Default width | `number` |
+| value? | The value this column contains | `(item: T) => V` |
+| sort? | A boolean (`localeCompare`) or sorting function | `boolean \| ((a: V, b: V) => number)` |
+| resizeable? | Whether this column is resizeable | `boolean` |
+| filter? | A filter for this columns value | `(item: V) => boolean` |
+| style? | Styling the `td` (row-column) element | `string` |
+| pad? | Apply padding to the child-element of `td`/`th` instead of the column element itself | `'row' \| 'header' \| 'both'` |
+| onclick? | When the column is clicked | `(event: MouseEvent, ctx: RowColumnCtx<T, V>) => void` |
+
+<br>
+
+### Row
+
+```ts
+import { Row } from 'svelte-tably'
+```
+
+This component can add a context-menu on the side of each row, as well as provide event handlers to the row element.
+
+```html
+<Row ... />
+
+<Row ...>
+    {#snippet context?(item: T, ctx: RowCtx<T>)}
+        ...
+    {/snippet}
+    {#snippet contextHeader?()}
+        ...
+    {/snippet}
+</Row>
+```
+
+| Attribute | Description | Type |
+| - | - | - |
+| context? | A sticky column on the right for each row | `Snippet<[item: T, ctx: RowCtx<T>]>` |
+| contextHeader? | A sticky column on the right for the header | `Snippet<[item: T, ctx: RowCtx<T>]>` |
+|   |  |  |
+| contextOptions? | Options for the Context-column | `ContextOptions<T>` |
+| onclick? | When row is clicked | `(event: MouseEvent, ctx: RowCtx<T>) => void` |
+| oncontextmenu? | When row is right-clicked | `(event: MouseEvent, ctx: RowCtx<T>) => void` |
+
+#### ContextOptions
+
+| Properties | Description | Type |
+| - | - | - |
+| hover? | Only show when hovering? | `boolean` |
+| width? | The width for the context-column | `string` |
+
+<br>
+
+### Expandable
+
+```ts
+import { Expandable } from 'svelte-tably'
+```
+
+This component gives your rows the ability to be expanded.
+
+```html
+<Expandable ...>
+    {#snippet content(item: T, ctx: RowCtx<T>)}
+        ...
+    {/snippet}
+</Expandable>
+```
+
+| Attribute | Description | Type |
+| - | - | - |
+| content | The contents of the expanded row. | `Snippet<[item: T, ctx: RowCtx<T>]>` |
+|   |  |  |
+| slide? | Options for sliding the expanding part | `{ duration?: number, easing?: EasingFunction }` |
+| click? | Whether you can click on a row to expand/collapse it | `boolean` |
+| chevron? | Whether to show the chevron on the left fixed column | `'always' \| 'hover' \| 'never'` |
+| multiple? | Can multiple rows be open at the same time? | `boolean` |
+
+<br>
+
+### Panel
+
+```ts
+import { Panel } from 'svelte-tably'
+```
+
+This component creates a panel that can be opened on the side of the table.
+
+```html
+<Panel id='...' ...>
+    {#snippet children(ctx: PanelCtx<T>)}
+        ...
+    {/snippet}
+</Panel>
+```
+
+| Attribute | Description | Type |
+| - | - | - |
+| children | The contents of the panel | `Snippet<[ctx: PanelCtx<T>]>` |
+|   |  |  |
+| id | The id for the panel that determines whether it's open or closed, from the Table attribute | `string` |
+| backdrop? | Whether there should be a backdrop or not | `boolean` |

package/dist/column/Column.svelte

@@ -0,0 +1,41 @@
+<!-- @component
+
+	This is a description, \
+	on how to use this.
+
+@example
+<Component />
+
+-->
+
+<script lang="ts">
+
+	import { fromProps, type AnyRecord } from '../utility.svelte.js'
+	import type { Snippet } from 'svelte'
+	import { ColumnState, type ColumnProps, type HeaderCtx, type ColumnSnippets } from './column.svelte.js'
+
+	type T = $$Generic<Record<PropertyKey, any>>
+	type V = $$Generic
+
+	let {...props}: ColumnProps<T, V> = $props()
+	const properties = fromProps(props)
+	
+	new ColumnState<T, V>(properties)
+	
+</script>
+
+<script module lang='ts'>
+	
+	declare const defaultHeader: <T extends AnyRecord>(anchor: unknown, title: () => string, ctx: HeaderCtx<T>) => ReturnType<Snippet>
+	
+	export function getDefaultHeader<T extends AnyRecord,V>(title: string) {
+		return (
+			(anchor: unknown, ctx: HeaderCtx<T>) => defaultHeader<T>(anchor, () => title, ctx)
+		) as Exclude<ColumnSnippets<T, V>['header'], string>
+	}
+
+</script>
+
+{#snippet defaultHeader(title: string, ctx: HeaderCtx<T>)}
+	{title}
+{/snippet}

package/dist/column/Column.svelte.d.ts

@@ -0,0 +1,27 @@
+export declare function getDefaultHeader<T extends AnyRecord, V>(title: string): Exclude<ColumnSnippets<T, V>["header"], string>;
+import { type AnyRecord } from '../utility.svelte.js';
+import { type ColumnSnippets } from './column.svelte.js';
+declare class __sveltets_Render<T extends Record<PropertyKey, any>, V> {
+    props(): ColumnProps<T_1, V_1>;
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends Record<PropertyKey, any>, V>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, V>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, V>['props']>, ReturnType<__sveltets_Render<T, V>['events']>, ReturnType<__sveltets_Render<T, V>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, V>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, V>['exports']>;
+    <T extends Record<PropertyKey, any>, V>(internal: unknown, props: ReturnType<__sveltets_Render<T, V>['props']> & {}): ReturnType<__sveltets_Render<T, V>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+/**
+ * This is a description, \
+ * on how to use this.
+ *
+ * @example
+ * <Component />
+ */
+declare const Column: $$IsomorphicComponent;
+type Column<T extends Record<PropertyKey, any>, V> = InstanceType<typeof Column<T, V>>;
+export default Column;

package/dist/column/column.svelte.js

@@ -0,0 +1,64 @@
+import { TableState } from '../table/table.svelte.js';
+import { getDefaultHeader } from './Column.svelte';
+export class ColumnState {
+    #props = {};
+    id = $derived(this.#props.id);
+    /**
+     * Associated table
+    */
+    table;
+    snippets = $derived({
+        header: typeof this.#props.header === 'string' ? getDefaultHeader(this.#props.header) : this.#props.header,
+        /** Title is the header-snippet, with header-ctx: `{ header: false }` */
+        title: (...args) => {
+            const getData = () => this.table.dataState.current;
+            return this.snippets.header?.(...[args[0], () => ({
+                    get header() { return false; },
+                    get data() {
+                        return getData();
+                    }
+                })]);
+        },
+        row: this.#props.row,
+        statusbar: this.#props.statusbar
+    });
+    /**
+     * Variables that can be saved (e.g. localStorage)
+     * and re-provided, where these are default-fallbacks
+    */
+    defaults = $derived({
+        sticky: this.#props.sticky ?? false,
+        show: this.#props.show ?? true,
+        sortby: this.#props.sortby ?? false,
+        width: this.#props.width ?? 150
+    });
+    /** Static options */
+    options = $derived({
+        fixed: this.#props.fixed ?? false,
+        sort: this.#props.sort ?? false,
+        filter: this.#props.filter,
+        value: this.#props.value,
+        resizeable: this.#props.resizeable ?? true,
+        style: this.#props.style,
+        class: this.#props.class,
+        onclick: this.#props.onclick,
+        padRow: this.#props.pad === 'row' || this.#props.pad === 'both',
+        padHeader: this.#props.pad === 'header' || this.#props.pad === 'both'
+    });
+    toggleVisiblity() {
+        const index = this.table.positions.hidden.indexOf(this);
+        if (index > -1)
+            this.table.positions.hidden.splice(index, 1);
+        else
+            this.table.positions.hidden.push(this);
+    }
+    constructor(props) {
+        this.#props = props;
+        this.table = props.table ?? TableState.getContext();
+        if (!this.table) {
+            throw new Error('svelte-tably: Column must be associated with a Table');
+        }
+        const remove = this.table.add(this);
+        $effect(() => remove);
+    }
+}

package/dist/conditional.svelte.d.ts

@@ -0,0 +1,10 @@
+type Actionable<A extends unknown | unknown[]> = {
+    destroy?: () => void;
+    update?: (args: A) => void;
+};
+export declare function conditional<A extends unknown | unknown[]>(node: HTMLElement, arg: [
+    condition: (() => boolean) | boolean,
+    action: ((node: HTMLElement, args?: A) => void | Actionable<A>),
+    args?: A
+]): void;
+export {};

package/dist/conditional.svelte.js

@@ -0,0 +1,26 @@
+import { untrack } from 'svelte';
+/*
+    use:conditional={[condition, action, arg]}
+    use:conditional={[condition, (node) => action(node, arg), updatedArg]}
+*/
+export function conditional(node, arg) {
+    let prev;
+    let clean;
+    $effect(() => {
+        prev?.destroy?.();
+        clean?.();
+        if (typeof arg[0] === 'function' ? arg[0]() : arg[0]) {
+            untrack(() => {
+                prev = arg[1](node, arg[2]);
+                if (prev?.update) {
+                    clean = $effect.root(() => {
+                        $effect(() => {
+                            prev.update(arg[2]);
+                        });
+                    });
+                }
+            });
+            return clean;
+        }
+    });
+}

package/dist/expandable/Expandable.svelte

@@ -0,0 +1,24 @@
+<!-- @component
+
+	This is a description, \
+	on how to use this.
+
+@example
+<Component />
+
+-->
+
+<script lang='ts'>
+
+	import { ExpandableState, type ExpandableProps } from './expandable.svelte.js'
+	import type { AnyRecord } from '../utility.svelte.js'
+	import { fromProps } from '../utility.svelte.js'
+
+	type T = $$Generic<AnyRecord>
+
+	let { ...restProps }: ExpandableProps<T> = $props()
+	
+	const properties = fromProps(restProps)
+	new ExpandableState<T>(properties)
+
+</script>

package/dist/expandable/Expandable.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { AnyRecord } from '../utility.svelte.js';
+declare class __sveltets_Render<T extends AnyRecord> {
+    props(): ExpandableProps<T_1>;
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends AnyRecord>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends AnyRecord>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * This is a description, \
+ * on how to use this.
+ *
+ * @example
+ * <Component />
+ */
+declare const Expandable: $$IsomorphicComponent;
+type Expandable<T extends AnyRecord> = InstanceType<typeof Expandable<T>>;
+export default Expandable;

package/dist/expandable/expandable.svelte.js

@@ -0,0 +1,27 @@
+import { TableState } from '../table/table.svelte.js';
+import { sineInOut } from 'svelte/easing';
+export class ExpandableState {
+    #table;
+    #props = {};
+    snippets = $derived({
+        content: this.#props.content
+    });
+    options = $derived({
+        slide: {
+            duration: this.#props.slide?.duration ?? 150,
+            easing: this.#props.slide?.easing ?? sineInOut
+        },
+        click: this.#props.click ?? true,
+        chevron: this.#props.chevron ?? 'hover',
+        multiple: this.#props.multiple ?? false
+    });
+    constructor(props) {
+        this.#props = props;
+        this.#table = TableState.getContext();
+        if (!this.#table) {
+            throw new Error('svelte-tably: Expandable must be associated with a Table');
+        }
+        this.#table.expandable = this;
+        $effect(() => () => this.#table.expandable === this && (this.#table.expandable = undefined));
+    }
+}