@humanspeak/svelte-headless-table 6.0.1 → 6.0.3

package/dist/utils/compare.js

@@ -1,3 +1,18 @@
+/**
+ * Compares two values or arrays for sorting purposes.
+ * Returns a negative number if a < b, positive if a > b, and 0 if equal.
+ *
+ * @template T - The type of elements being compared (string or number).
+ * @param a - The first value or array to compare.
+ * @param b - The second value or array to compare.
+ * @returns A number indicating the sort order.
+ * @example
+ * ```typescript
+ * compare(1, 2) // Returns -1
+ * compare('b', 'a') // Returns 1
+ * compare([1, 2], [1, 3]) // Returns -1
+ * ```
+ */
 export const compare = (a, b) => {
     if (Array.isArray(a) && Array.isArray(b)) {
         return compareArray(a, b);
@@ -6,6 +21,20 @@ export const compare = (a, b) => {
         return a - b;
     return a < b ? -1 : a > b ? 1 : 0;
 };
+/**
+ * Compares two arrays element by element for sorting purposes.
+ * Comparison stops at the first non-equal element.
+ *
+ * @template T - The type of elements in the arrays (string or number).
+ * @param a - The first array to compare.
+ * @param b - The second array to compare.
+ * @returns A number indicating the sort order based on the first differing element.
+ * @example
+ * ```typescript
+ * compareArray([1, 2, 3], [1, 2, 4]) // Returns -1
+ * compareArray(['a', 'b'], ['a', 'a']) // Returns 1
+ * ```
+ */
 export const compareArray = (a, b) => {
     const minLength = Math.min(a.length, b.length);
     for (let i = 0; i < minLength; i++) {

package/dist/utils/counter.d.ts

@@ -1 +1,13 @@
+/**
+ * Creates a Map that counts the occurrences of each element in an array.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The array of items to count.
+ * @returns A Map where keys are unique items and values are their occurrence counts.
+ * @example
+ * ```typescript
+ * getCounter(['a', 'b', 'a', 'c', 'a'])
+ * // Returns Map { 'a' => 3, 'b' => 1, 'c' => 1 }
+ * ```
+ */
 export declare const getCounter: <T>(items: T[]) => Map<T, number>;

package/dist/utils/counter.js

@@ -1,3 +1,15 @@
+/**
+ * Creates a Map that counts the occurrences of each element in an array.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The array of items to count.
+ * @returns A Map where keys are unique items and values are their occurrence counts.
+ * @example
+ * ```typescript
+ * getCounter(['a', 'b', 'a', 'c', 'a'])
+ * // Returns Map { 'a' => 3, 'b' => 1, 'c' => 1 }
+ * ```
+ */
 export const getCounter = (items) => {
     const result = new Map();
     items.forEach((item) => {

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));