@humanspeak/svelte-headless-table 6.0.2 → 6.0.3

package/dist/utils/css.d.ts

@@ -1 +1,12 @@
+/**
+ * Converts a CSS style object into an inline style string.
+ *
+ * @param style - An object containing CSS property-value pairs.
+ * @returns A semicolon-separated string of CSS declarations.
+ * @example
+ * ```typescript
+ * stringifyCss({ color: 'red', fontSize: '14px' })
+ * // Returns 'color:red;fontSize:14px'
+ * ```
+ */
 export declare const stringifyCss: (style: Record<string, unknown>) => string;

package/dist/utils/css.js

@@ -1,3 +1,14 @@
+/**
+ * Converts a CSS style object into an inline style string.
+ *
+ * @param style - An object containing CSS property-value pairs.
+ * @returns A semicolon-separated string of CSS declarations.
+ * @example
+ * ```typescript
+ * stringifyCss({ color: 'red', fontSize: '14px' })
+ * // Returns 'color:red;fontSize:14px'
+ * ```
+ */
 export const stringifyCss = (style) => {
     return Object.entries(style)
         .map(([name, value]) => `${name}:${value}`)

package/dist/utils/event.d.ts

@@ -1 +1,15 @@
+/**
+ * Determines if an event is a mouse click with the Shift key held down.
+ *
+ * @param event - The DOM event to check.
+ * @returns True if the event is a MouseEvent with shiftKey pressed, false otherwise.
+ * @example
+ * ```typescript
+ * element.addEventListener('click', (e) => {
+ *   if (isShiftClick(e)) {
+ *     // Handle shift+click
+ *   }
+ * })
+ * ```
+ */
 export declare const isShiftClick: (event: Event) => boolean;

package/dist/utils/event.js

@@ -1,3 +1,17 @@
+/**
+ * Determines if an event is a mouse click with the Shift key held down.
+ *
+ * @param event - The DOM event to check.
+ * @returns True if the event is a MouseEvent with shiftKey pressed, false otherwise.
+ * @example
+ * ```typescript
+ * element.addEventListener('click', (e) => {
+ *   if (isShiftClick(e)) {
+ *     // Handle shift+click
+ *   }
+ * })
+ * ```
+ */
 export const isShiftClick = (event) => {
     if (!(event instanceof MouseEvent))
         return false;

package/dist/utils/filter.d.ts

@@ -1,4 +1,51 @@
+/**
+ * Type guard that checks if a value is not null.
+ *
+ * @template T - The non-null type.
+ * @param value - The value to check.
+ * @returns True if the value is not null.
+ * @example
+ * ```typescript
+ * const items = [1, null, 2, null, 3]
+ * const filtered = items.filter(nonNull) // Type: number[]
+ * ```
+ */
 export declare const nonNull: <T>(value: T | null) => value is T;
+/**
+ * Type guard that checks if a value is not undefined.
+ *
+ * @template T - The defined type.
+ * @param value - The value to check.
+ * @returns True if the value is not undefined.
+ * @example
+ * ```typescript
+ * const items = [1, undefined, 2, undefined, 3]
+ * const filtered = items.filter(nonUndefined) // Type: number[]
+ * ```
+ */
 export declare const nonUndefined: <T>(value: T | undefined) => value is T;
+/**
+ * Type guard that checks if a value is neither null nor undefined.
+ *
+ * @template T - The non-nullish type.
+ * @param value - The value to check.
+ * @returns True if the value is not null and not undefined.
+ * @example
+ * ```typescript
+ * const items = [1, null, 2, undefined, 3]
+ * const filtered = items.filter(nonNullish) // Type: number[]
+ * ```
+ */
 export declare const nonNullish: <T>(value: T | null | undefined) => value is T;
+/**
+ * Type guard that checks if a value is a number.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is of type number.
+ * @example
+ * ```typescript
+ * isNumber(42) // Returns true
+ * isNumber('42') // Returns false
+ * ```
+ */
 export declare const isNumber: (value: unknown) => value is number;

package/dist/utils/filter.js

@@ -1,4 +1,51 @@
+/**
+ * Type guard that checks if a value is not null.
+ *
+ * @template T - The non-null type.
+ * @param value - The value to check.
+ * @returns True if the value is not null.
+ * @example
+ * ```typescript
+ * const items = [1, null, 2, null, 3]
+ * const filtered = items.filter(nonNull) // Type: number[]
+ * ```
+ */
 export const nonNull = (value) => value !== null;
+/**
+ * Type guard that checks if a value is not undefined.
+ *
+ * @template T - The defined type.
+ * @param value - The value to check.
+ * @returns True if the value is not undefined.
+ * @example
+ * ```typescript
+ * const items = [1, undefined, 2, undefined, 3]
+ * const filtered = items.filter(nonUndefined) // Type: number[]
+ * ```
+ */
 export const nonUndefined = (value) => value !== undefined;
+/**
+ * Type guard that checks if a value is neither null nor undefined.
+ *
+ * @template T - The non-nullish type.
+ * @param value - The value to check.
+ * @returns True if the value is not null and not undefined.
+ * @example
+ * ```typescript
+ * const items = [1, null, 2, undefined, 3]
+ * const filtered = items.filter(nonNullish) // Type: number[]
+ * ```
+ */
 export const nonNullish = (value) => value != null;
+/**
+ * Type guard that checks if a value is a number.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is of type number.
+ * @example
+ * ```typescript
+ * isNumber(42) // Returns true
+ * isNumber('42') // Returns false
+ * ```
+ */
 export const isNumber = (value) => typeof value === 'number';

package/dist/utils/math.d.ts

@@ -1,2 +1,24 @@
+/**
+ * Calculates the sum of an array of numbers.
+ *
+ * @param nums - The array of numbers to sum.
+ * @returns The sum of all numbers in the array, or 0 for an empty array.
+ * @example
+ * ```typescript
+ * sum([1, 2, 3, 4, 5]) // Returns 15
+ * sum([]) // Returns 0
+ * ```
+ */
 export declare const sum: (nums: number[]) => number;
+/**
+ * Calculates the arithmetic mean (average) of an array of numbers.
+ *
+ * @param nums - The array of numbers to average.
+ * @returns The mean of all numbers, or 0 for an empty array.
+ * @example
+ * ```typescript
+ * mean([1, 2, 3, 4, 5]) // Returns 3
+ * mean([]) // Returns 0
+ * ```
+ */
 export declare const mean: (nums: number[]) => number;

package/dist/utils/math.js

@@ -1,2 +1,24 @@
+/**
+ * Calculates the sum of an array of numbers.
+ *
+ * @param nums - The array of numbers to sum.
+ * @returns The sum of all numbers in the array, or 0 for an empty array.
+ * @example
+ * ```typescript
+ * sum([1, 2, 3, 4, 5]) // Returns 15
+ * sum([]) // Returns 0
+ * ```
+ */
 export const sum = (nums) => nums.reduce((a, b) => a + b, 0);
+/**
+ * Calculates the arithmetic mean (average) of an array of numbers.
+ *
+ * @param nums - The array of numbers to average.
+ * @returns The mean of all numbers, or 0 for an empty array.
+ * @example
+ * ```typescript
+ * mean([1, 2, 3, 4, 5]) // Returns 3
+ * mean([]) // Returns 0
+ * ```
+ */
 export const mean = (nums) => (nums.length === 0 ? 0 : sum(nums) / nums.length);

package/dist/utils/matrix.d.ts

@@ -1,3 +1,27 @@
 import type { Matrix } from '../types/Matrix.js';
+/**
+ * Creates a matrix of the specified dimensions filled with null values.
+ *
+ * @param width - The number of columns in the matrix.
+ * @param height - The number of rows in the matrix.
+ * @returns A new matrix with all elements set to null.
+ * @example
+ * ```typescript
+ * getNullMatrix(3, 2)
+ * // Returns [[null, null, null], [null, null, null]]
+ * ```
+ */
 export declare const getNullMatrix: (width: number, height: number) => Matrix<null>;
+/**
+ * Transposes a matrix, swapping rows and columns.
+ *
+ * @template T - The type of elements in the matrix.
+ * @param matrix - The matrix to transpose.
+ * @returns A new matrix with rows and columns swapped.
+ * @example
+ * ```typescript
+ * getTransposed([[1, 2, 3], [4, 5, 6]])
+ * // Returns [[1, 4], [2, 5], [3, 6]]
+ * ```
+ */
 export declare const getTransposed: <T>(matrix: Matrix<T>) => Matrix<T>;

package/dist/utils/matrix.js

@@ -1,3 +1,15 @@
+/**
+ * Creates a matrix of the specified dimensions filled with null values.
+ *
+ * @param width - The number of columns in the matrix.
+ * @param height - The number of rows in the matrix.
+ * @returns A new matrix with all elements set to null.
+ * @example
+ * ```typescript
+ * getNullMatrix(3, 2)
+ * // Returns [[null, null, null], [null, null, null]]
+ * ```
+ */
 export const getNullMatrix = (width, height) => {
     const result = [];
     // Use a loop to create a new array instance per row.
@@ -6,6 +18,18 @@ export const getNullMatrix = (width, height) => {
     }
     return result;
 };
+/**
+ * Transposes a matrix, swapping rows and columns.
+ *
+ * @template T - The type of elements in the matrix.
+ * @param matrix - The matrix to transpose.
+ * @returns A new matrix with rows and columns swapped.
+ * @example
+ * ```typescript
+ * getTransposed([[1, 2, 3], [4, 5, 6]])
+ * // Returns [[1, 4], [2, 5], [3, 6]]
+ * ```
+ */
 export const getTransposed = (matrix) => {
     const height = matrix.length;
     if (height === 0) {

package/dist/utils/store.d.ts

@@ -1,37 +1,144 @@
 import { type Readable, type Writable } from 'svelte/store';
+/** Union type representing either a Readable or Writable Svelte store. */
 export type ReadOrWritable<T> = Readable<T> | Writable<T>;
+/**
+ * Type guard that checks if a value is a Svelte Readable store.
+ *
+ * @template T - The type of the store's value.
+ * @param value - The value to check.
+ * @returns True if the value has a subscribe method.
+ * @example
+ * ```typescript
+ * if (isReadable(maybeStore)) {
+ *   maybeStore.subscribe(value => console.log(value))
+ * }
+ * ```
+ */
 export declare const isReadable: <T>(value: any) => value is Readable<T>;
+/**
+ * Type guard that checks if a value is a Svelte Writable store.
+ *
+ * @template T - The type of the store's value.
+ * @param store - The value to check.
+ * @returns True if the value has both update and set methods.
+ * @example
+ * ```typescript
+ * if (isWritable(maybeStore)) {
+ *   maybeStore.set(newValue)
+ * }
+ * ```
+ */
 export declare const isWritable: <T>(store: any) => store is Writable<T>;
+/**
+ * Maps each key of T to a Writable store containing that key's value type.
+ * @template T - The object type to map.
+ */
 export type WritableKeys<T> = {
     [K in keyof T]: T[K] extends undefined ? Writable<T[K] | undefined> : Writable<T[K]>;
 };
+/**
+ * Maps each key of T to a Readable store containing that key's value type.
+ * @template T - The object type to map.
+ */
 export type ReadableKeys<T> = {
     [K in keyof T]: T[K] extends undefined ? Readable<T[K] | undefined> : Readable<T[K]>;
 };
+/**
+ * Maps each key of T to either a Readable or Writable store.
+ * @template T - The object type to map.
+ */
 export type ReadOrWritableKeys<T> = {
     [K in keyof T]: T[K] extends undefined ? ReadOrWritable<T[K] | undefined> : ReadOrWritable<T[K]>;
 };
+/** A readable store that always contains undefined. */
 export declare const Undefined: Readable<undefined>;
+/**
+ * Returns the Undefined store typed as a Readable of type T.
+ * Useful for providing a default store value.
+ *
+ * @template T - The type to cast the undefined store to.
+ * @returns A Readable store typed as Readable<T>.
+ */
 export declare const UndefinedAs: <T>() => Readable<T>;
+/**
+ * Options for toggle operations in set stores.
+ */
 export interface ToggleOptions {
+    /** If true, removes all other items when toggling an item on. */
     clearOthers?: boolean;
 }
+/**
+ * Configuration options for creating an ArraySetStore.
+ * @template T - The type of elements in the array.
+ */
 export interface ArraySetStoreOptions<T> {
-    isEqual?: (a: T, b: T) => boolean;
+    /** Custom equality function for comparing items. Defaults to strict equality. */
+    isEqual?: (_a: T, _b: T) => boolean;
 }
+/**
+ * A Svelte store that maintains a unique set of items as an array.
+ * Extends Writable with set-like operations.
+ *
+ * @template T - The type of elements in the set.
+ */
 export interface ArraySetStore<T> extends Writable<T[]> {
-    toggle: (item: T, options?: ToggleOptions) => void;
-    add: (item: T) => void;
-    remove: (item: T) => void;
+    /** Toggles an item in the set (adds if absent, removes if present). */
+    toggle: (_item: T, _options?: ToggleOptions) => void;
+    /** Adds an item to the set if not already present. */
+    add: (_item: T) => void;
+    /** Removes an item from the set if present. */
+    remove: (_item: T) => void;
+    /** Removes all items from the set. */
     clear: () => void;
 }
+/**
+ * Creates a Svelte store that maintains a unique set of items as an array.
+ * Supports toggle, add, remove, and clear operations.
+ *
+ * @template T - The type of elements in the set.
+ * @param initial - The initial array of items.
+ * @param options - Configuration options including custom equality function.
+ * @returns An ArraySetStore with set-like operations.
+ * @example
+ * ```typescript
+ * const selectedIds = arraySetStore<string>(['id1'])
+ * selectedIds.toggle('id2') // Adds 'id2'
+ * selectedIds.toggle('id1') // Removes 'id1'
+ * ```
+ */
 export declare const arraySetStore: <T>(initial?: T[], { isEqual }?: ArraySetStoreOptions<T>) => ArraySetStore<T>;
+/**
+ * A Svelte store that maintains a set using a Record with boolean values.
+ * More efficient for string/number keys than ArraySetStore.
+ *
+ * @template T - The type of keys (must be string or number).
+ */
 export interface RecordSetStore<T extends string | number> extends Writable<Record<T, boolean>> {
-    toggle: (item: T) => void;
-    add: (item: T) => void;
-    addAll: (items: T[]) => void;
-    remove: (item: T) => void;
-    removeAll: (items: T[]) => void;
+    /** Toggles a key in the set (adds if absent, removes if present). */
+    toggle: (_item: T) => void;
+    /** Adds a key to the set. */
+    add: (_item: T) => void;
+    /** Adds multiple keys to the set. */
+    addAll: (_items: T[]) => void;
+    /** Removes a key from the set. */
+    remove: (_item: T) => void;
+    /** Removes multiple keys from the set. */
+    removeAll: (_items: T[]) => void;
+    /** Removes all keys from the set. */
     clear: () => void;
 }
+/**
+ * Creates a Svelte store that maintains a set using a Record with boolean values.
+ * False values are automatically removed to keep the record clean.
+ *
+ * @template T - The type of keys (must be string or number).
+ * @param initial - The initial record of key-boolean pairs.
+ * @returns A RecordSetStore with set-like operations.
+ * @example
+ * ```typescript
+ * const expandedIds = recordSetStore<string>({ row1: true })
+ * expandedIds.toggle('row2') // Adds 'row2'
+ * expandedIds.toggle('row1') // Removes 'row1'
+ * ```
+ */
 export declare const recordSetStore: <T extends string | number>(initial?: Record<T, boolean>) => RecordSetStore<T>;

package/dist/utils/store.js

@@ -1,14 +1,63 @@
 import { readable, writable } from 'svelte/store';
+/**
+ * Type guard that checks if a value is a Svelte Readable store.
+ *
+ * @template T - The type of the store's value.
+ * @param value - The value to check.
+ * @returns True if the value has a subscribe method.
+ * @example
+ * ```typescript
+ * if (isReadable(maybeStore)) {
+ *   maybeStore.subscribe(value => console.log(value))
+ * }
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const isReadable = (value) => {
     return value?.subscribe instanceof Function;
 };
+/**
+ * Type guard that checks if a value is a Svelte Writable store.
+ *
+ * @template T - The type of the store's value.
+ * @param store - The value to check.
+ * @returns True if the value has both update and set methods.
+ * @example
+ * ```typescript
+ * if (isWritable(maybeStore)) {
+ *   maybeStore.set(newValue)
+ * }
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const isWritable = (store) => {
     return store?.update instanceof Function && store.set instanceof Function;
 };
+/** A readable store that always contains undefined. */
 export const Undefined = readable(undefined);
+/**
+ * Returns the Undefined store typed as a Readable of type T.
+ * Useful for providing a default store value.
+ *
+ * @template T - The type to cast the undefined store to.
+ * @returns A Readable store typed as Readable<T>.
+ */
 export const UndefinedAs = () => Undefined;
+/**
+ * Creates a Svelte store that maintains a unique set of items as an array.
+ * Supports toggle, add, remove, and clear operations.
+ *
+ * @template T - The type of elements in the set.
+ * @param initial - The initial array of items.
+ * @param options - Configuration options including custom equality function.
+ * @returns An ArraySetStore with set-like operations.
+ * @example
+ * ```typescript
+ * const selectedIds = arraySetStore<string>(['id1'])
+ * selectedIds.toggle('id2') // Adds 'id2'
+ * selectedIds.toggle('id1') // Removes 'id1'
+ * ```
+ */
 export const arraySetStore = (initial = [], { isEqual = (a, b) => a === b } = {}) => {
     const { subscribe, update, set } = writable(initial);
     const toggle = (item, { clearOthers = false } = {}) => {
@@ -57,6 +106,20 @@ export const arraySetStore = (initial = [], { isEqual = (a, b) => a === b } = {}
         clear
     };
 };
+/**
+ * Creates a Svelte store that maintains a set using a Record with boolean values.
+ * False values are automatically removed to keep the record clean.
+ *
+ * @template T - The type of keys (must be string or number).
+ * @param initial - The initial record of key-boolean pairs.
+ * @returns A RecordSetStore with set-like operations.
+ * @example
+ * ```typescript
+ * const expandedIds = recordSetStore<string>({ row1: true })
+ * expandedIds.toggle('row2') // Adds 'row2'
+ * expandedIds.toggle('row1') // Removes 'row1'
+ * ```
+ */
 export const recordSetStore = (initial = {}) => {
     const withFalseRemoved = (record) => {
         return Object.fromEntries(Object.entries(record).filter(([, v]) => v));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-headless-table",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "A powerful, headless table library for Svelte that provides complete control over table UI while handling complex data operations like sorting, filtering, pagination, grouping, and row expansion. Build custom, accessible data tables with zero styling opinions.",
   "keywords": [
     "svelte",
@@ -58,55 +58,55 @@
     "!dist/**/*.spec.*"
   ],
   "dependencies": {
-    "@humanspeak/memory-cache": "^1.0.1",
+    "@humanspeak/memory-cache": "^1.0.4",
     "@humanspeak/svelte-keyed": "^5.0.1",
     "@humanspeak/svelte-render": "^5.1.1",
     "@humanspeak/svelte-subscribe": "^5.0.0"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.0",
+    "@eslint/compat": "^2.0.2",
     "@eslint/js": "^9.39.2",
-    "@faker-js/faker": "^10.1.0",
-    "@playwright/test": "^1.57.0",
+    "@faker-js/faker": "^10.2.0",
+    "@playwright/test": "^1.58.1",
     "@sveltejs/adapter-auto": "^7.0.0",
-    "@sveltejs/kit": "^2.49.2",
+    "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@types/eslint": "9.6.1",
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.51.0",
-    "@typescript-eslint/parser": "^8.51.0",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-svelte": "3.13.1",
+    "eslint-plugin-svelte": "3.14.0",
     "eslint-plugin-unused-imports": "4.3.0",
-    "globals": "^16.5.0",
+    "globals": "^17.2.0",
     "husky": "^9.1.7",
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-sort-json": "^4.1.1",
+    "prettier-plugin-sort-json": "^4.2.0",
     "prettier-plugin-svelte": "^3.4.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "publint": "^0.3.16",
-    "svelte": "^5.46.1",
+    "publint": "^0.3.17",
+    "svelte": "^5.49.1",
     "svelte-check": "^4.3.5",
     "tslib": "^2.8.1",
-    "type-fest": "^5.3.1",
+    "type-fest": "^5.4.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.51.0",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16"
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "svelte": "^5.30.0"
   },
   "volta": {
-    "node": "22.21.1"
+    "node": "24.12.0"
   },
   "scripts": {
     "build": "vite build && npm run package",