svelte-tably 1.0.0-next.9 → 1.0.1-next.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,93 +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
-- [x] sorting
-- [x] select
-- [ ] filtering
-- [ ] orderable table
-- [ ] row context-menu
-- [ ] dropout section
-- [ ] csv export
-
-### 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,39 @@
+<!-- @component
+
+	This is a description, \
+	on how to use this.
+
+@example
+<Component />
+
+-->
+
+<script module lang='ts'>
+
+	export function getDefaultHeader<T extends AnyRecord,V>(title: string) {
+		return (
+			(anchor: Comment) => snippetLiteral(defaultHeader)(anchor, () => title)
+		) as unknown as () => any
+	}
+
+</script>
+
+<script lang='ts'>
+
+	import { fromProps, snippetLiteral, type AnyRecord } from '../utility.svelte.js'
+	import { ColumnState, type ColumnProps, type HeaderCtx, type ColumnSnippets } from './column-state.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>
+
+
+{#snippet defaultHeader(title: string)}
+	{title}
+{/snippet}

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

@@ -0,0 +1,46 @@
+export declare function getDefaultHeader<T extends AnyRecord, V>(title: string): () => any;
+import { type AnyRecord } from '../utility.svelte.js';
+import { type HeaderCtx } from './column-state.svelte.js';
+declare class __sveltets_Render<T extends Record<PropertyKey, any>, V> {
+    props(): {
+        id: string;
+        table?: import("../index.js").TableState<T> | undefined;
+        header?: string | import("svelte").Snippet<[ctx: HeaderCtx<T>]> | undefined;
+        row?: import("svelte").Snippet<[item: T, ctx: import("./column-state.svelte.js").RowColumnCtx<T, V>]> | undefined;
+        statusbar?: import("svelte").Snippet<[ctx: import("./column-state.svelte.js").StatusbarCtx<T>]> | undefined;
+        sticky?: boolean | undefined;
+        show?: boolean | undefined;
+        sortby?: boolean | undefined;
+        width?: number | undefined;
+        fixed?: boolean | undefined;
+        value?: ((item: T) => V) | undefined;
+        sort?: boolean | ((a: V, b: V) => number) | undefined;
+        resizeable?: boolean | undefined;
+        filter?: ((value: V) => boolean) | undefined;
+        style?: string | undefined;
+        class?: string | undefined;
+        onclick?: ((event: MouseEvent, rowColumnCtx: import("./column-state.svelte.js").RowColumnCtx<T, V>) => void) | undefined;
+        pad?: "row" | "header" | "both" | undefined;
+    };
+    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-state.svelte.d.ts

@@ -0,0 +1,138 @@
+import { type Snippet } from 'svelte';
+import { TableState, type RowCtx } from '../table/table-state.svelte.js';
+import { type AnyRecord } from '../utility.svelte.js';
+export type ColumnProps<T extends AnyRecord, V> = ({
+    id: string;
+    table?: TableState<T>;
+} & ColumnSnippets<T, V> & ColumnDefaults<T> & ColumnOptions<T, V>) extends infer K ? {
+    [P in keyof K]: K[P];
+} : never;
+export interface HeaderCtx<T> {
+    readonly data: T[];
+    /**
+     * Is true when displaying in the header,
+     * so additional content can be shown if desired,
+     * so the header snippet can be re-used.
+     */
+    readonly header?: boolean;
+}
+export interface RowColumnCtx<T extends AnyRecord, V> extends RowCtx<T> {
+    readonly value: V;
+    readonly columnHovered: boolean;
+}
+export type StatusbarCtx<T extends AnyRecord> = {
+    readonly data: T[];
+};
+export type ColumnSnippets<T extends AnyRecord, V> = {
+    header?: Snippet<[ctx: HeaderCtx<T>]> | string;
+    row?: Snippet<[item: T, ctx: RowColumnCtx<T, V>]>;
+    statusbar?: Snippet<[ctx: StatusbarCtx<T>]>;
+};
+type ColumnDefaults<T> = {
+    /**
+     * Is this column sticky by default?
+     * @default false
+    */
+    sticky?: boolean;
+    /**
+     * Is this column visible by default?
+     * @default true
+     */
+    show?: boolean;
+    /**
+     * Is this column sorted by default?
+     * @default false
+    */
+    sortby?: boolean;
+    /**
+     * The width of the column in pixels by default
+     * @default 150
+     */
+    width?: number;
+};
+type ColumnOptions<T extends AnyRecord, V> = {
+    /**
+     * Fixed is like sticky, but in its own category — meant to not be moved/hidden ex. select-boxes
+     * @default false
+    */
+    fixed?: boolean;
+    /**
+     * The value of the row. Required for sorting/filtering
+     * @example row => row.name
+    */
+    value?: (item: T) => V;
+    /**
+     * Makes the column sortable. Sorts based of a sorting function.
+     *
+     * **Important**   `value`-attribute is required adjacent to this.
+     *
+     * If `true` uses the default `.sort()` algorithm.
+     *
+     * @default false
+    */
+    sort?: boolean | ((a: V, b: V) => number);
+    /**
+     * Is this column resizeable?
+     * Can not be resized if Table is marked as `resizeable={false}`
+     * @default true
+    */
+    resizeable?: boolean;
+    /**
+     *
+     * @example (value) => value.includes(search)
+    */
+    filter?: (value: V) => boolean;
+    /** Styling for the column element (td) */
+    style?: string;
+    /** Class for the column element (td) */
+    class?: string;
+    /** Event when the row-column is clicked */
+    onclick?: (event: MouseEvent, rowColumnCtx: RowColumnCtx<T, V>) => void;
+    /**
+     * Pad child element of `td`/`th` instead of the column element itself.
+     * This ensures the child element "fills" the whole column.
+     * Ex. good if you want to make the column an anchor link; `<a href='...'>`
+    */
+    pad?: 'row' | 'header' | 'both';
+};
+export declare class ColumnState<T extends AnyRecord = any, V = any> {
+    #private;
+    id: string;
+    /**
+     * Associated table
+    */
+    table: TableState<T>;
+    snippets: {
+        header: Snippet<[ctx: HeaderCtx<T>]> | (() => any) | undefined;
+        /** Title is the header-snippet, with header-ctx: `{ header: false }` */
+        title: (...args: any[]) => any;
+        row: Snippet<[item: T, ctx: RowColumnCtx<T, V>]> | undefined;
+        statusbar: Snippet<[ctx: StatusbarCtx<T>]> | undefined;
+    };
+    /**
+     * Variables that can be saved (e.g. localStorage)
+     * and re-provided, where these are default-fallbacks
+    */
+    defaults: {
+        sticky: boolean;
+        show: boolean;
+        sortby: boolean;
+        width: number;
+    };
+    /** Static options */
+    options: {
+        fixed: boolean;
+        sort: boolean | ((a: V, b: V) => number);
+        filter: ((value: V) => boolean) | undefined;
+        value: ((item: T) => V) | undefined;
+        resizeable: boolean;
+        style: string | undefined;
+        class: string | undefined;
+        onclick: ((event: MouseEvent, rowColumnCtx: RowColumnCtx<T, V>) => void) | undefined;
+        padRow: boolean;
+        padHeader: boolean;
+    };
+    toggleVisiblity(): void;
+    constructor(props: ColumnProps<T, V>);
+}
+export {};