@humanspeak/svelte-headless-table 6.0.2 → 6.0.3

package/dist/tableComponent.js

@@ -1,12 +1,31 @@
 import { finalizeAttributes, mergeAttributes } from './utils/attributes.js';
 import { derivedKeys } from '@humanspeak/svelte-subscribe';
 import { derived } from 'svelte/store';
+/**
+ * Abstract base class for all table components (rows, cells, etc.).
+ * Provides common functionality for state injection, hook application, and attribute merging.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @template Key - The component key type (e.g., 'tbody.tr', 'tbody.tr.td').
+ */
 export class TableComponent {
+    /** Unique identifier for the component. */
     id;
+    /**
+     * Creates a new TableComponent.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id }) {
         this.id = id;
     }
     attrsForName = {};
+    /**
+     * Gets the merged HTML attributes from all applied plugins.
+     *
+     * @returns A readable store of merged attributes.
+     */
     attrs() {
         return derived(Object.values(this.attrsForName), ($attrsArray) => {
             let $mergedAttrs = {};
@@ -17,13 +36,31 @@ export class TableComponent {
         });
     }
     propsForName = {};
+    /**
+     * Gets the merged props from all applied plugins.
+     *
+     * @returns A readable store of plugin props keyed by plugin name.
+     */
     props() {
         return derivedKeys(this.propsForName);
     }
+    /** Reference to the table state, injected after creation. */
     state;
+    /**
+     * Injects the table state reference into this component.
+     *
+     * @param state - The table state to inject.
+     */
     injectState(state) {
         this.state = state;
     }
+    /**
+     * Applies a plugin hook to this component.
+     * Hooks can provide both props and attributes.
+     *
+     * @param pluginName - The name of the plugin.
+     * @param hook - The element hook containing props and/or attrs.
+     */
     applyHook(pluginName, hook) {
         if (hook.props !== undefined) {
             this.propsForName[pluginName] = hook.props;

package/dist/types/Action.d.ts

@@ -1,5 +1,19 @@
+/**
+ * Return type for Svelte actions.
+ * Contains optional lifecycle methods for updating and destroying the action.
+ *
+ * @template Props - The type of props passed to the action.
+ */
 export type ActionReturnType<Props = any> = {
-    update?: (newProps: Props) => void;
+    /** Called when props change. */
+    update?: (_newProps: Props) => void;
+    /** Called when the element is removed from the DOM. */
     destroy?: () => void;
 };
-export type Action<Props> = (node: Element, props?: Props) => ActionReturnType<Props> | void;
+/**
+ * A Svelte action function that can be applied to DOM elements.
+ * Actions receive an element and optional props, returning lifecycle methods.
+ *
+ * @template Props - The type of props passed to the action.
+ */
+export type Action<Props> = (_node: Element, _props?: Props) => ActionReturnType<Props> | void;

package/dist/types/Entries.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Converts an object type to its entries type (array of [key, value] tuples).
+ * Similar to the return type of Object.entries() but with stronger typing.
+ *
+ * @template Obj - The object type to convert.
+ */
 export type Entries<Obj> = NonNullable<{
     [K in keyof Obj]: [K, NonNullable<Obj[K]>];
 }[keyof Obj]>[];

package/dist/types/KeyPath.d.ts

@@ -1,6 +1,26 @@
+/**
+ * Generates a union of all valid dot-notation key paths for an object type.
+ * Useful for type-safe property access with nested objects.
+ *
+ * @template T - The object type to extract paths from.
+ * @template D - Maximum depth to traverse (default 3 to avoid infinite recursion).
+ * @example
+ * ```typescript
+ * type Person = { name: string; address: { city: string } }
+ * type Paths = KeyPath<Person> // 'name' | 'address' | 'address.city'
+ * ```
+ */
 export type KeyPath<T, D extends number = 3> = KeyPath_<T, D, []>;
+/**
+ * Internal recursive helper for KeyPath.
+ * @internal
+ */
 type KeyPath_<T, D extends number, S extends unknown[]> = D extends S['length'] ? never : T extends object ? {
     [K in keyof T]-?: K extends string ? `${K}` | Join<K, KeyPath_<T[K], D, [never, ...S]>> : K extends number ? `[${K}]` | Join<`[${K}]`, KeyPath_<T[K], D, [never, ...S]>> : never;
 }[keyof T] : '';
+/**
+ * Internal helper for joining path segments with dots.
+ * @internal
+ */
 type Join<K, P> = K extends string | number ? P extends string | number ? P extends `[${string}` ? `${K}${P}` : `${K}${'' extends P ? '' : '.'}${P}` : never : never;
 export {};

package/dist/types/Label.d.ts

@@ -3,6 +3,29 @@ import type { DataBodyCell, DisplayBodyCell } from '../bodyCells.js';
 import type { TableState } from '../createViewModel.js';
 import type { HeaderCell } from '../headerCells.js';
 import type { AnyPlugins } from './TablePlugin.js';
-export type DataLabel<Item, Plugins extends AnyPlugins = AnyPlugins, Value = any> = (cell: DataBodyCell<Item, AnyPlugins, Value>, state: TableState<Item, Plugins>) => RenderConfig;
-export type DisplayLabel<Item, Plugins extends AnyPlugins = AnyPlugins> = (cell: DisplayBodyCell<Item>, state: TableState<Item, Plugins>) => RenderConfig;
-export type HeaderLabel<Item, Plugins extends AnyPlugins = AnyPlugins> = RenderConfig | ((cell: HeaderCell<Item, Plugins>, state: TableState<Item, Plugins>) => RenderConfig);
+/**
+ * A render function for data body cells.
+ * Receives the cell and table state, returns content to render.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @template Value - The type of the cell value.
+ */
+export type DataLabel<Item, Plugins extends AnyPlugins = AnyPlugins, Value = any> = (_cell: DataBodyCell<Item, AnyPlugins, Value>, _state: TableState<Item, Plugins>) => RenderConfig;
+/**
+ * A render function for display body cells.
+ * Receives the cell and table state, returns content to render.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
+export type DisplayLabel<Item, Plugins extends AnyPlugins = AnyPlugins> = (_cell: DisplayBodyCell<Item>, _state: TableState<Item, Plugins>) => RenderConfig;
+/**
+ * A label for header cells. Can be static content or a render function.
+ * If the function type is removed from the union, generics will not be
+ * inferred for subtypes.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
+export type HeaderLabel<Item, Plugins extends AnyPlugins = AnyPlugins> = RenderConfig | ((_cell: HeaderCell<Item, Plugins>, _state: TableState<Item, Plugins>) => RenderConfig);

package/dist/types/Matrix.d.ts

@@ -1 +1,7 @@
+/**
+ * A two-dimensional array (matrix) type.
+ * Used for header row/column matrices and other grid-like structures.
+ *
+ * @template T - The type of elements in the matrix.
+ */
 export type Matrix<T> = T[][];

package/dist/types/TablePlugin.d.ts

@@ -5,12 +5,41 @@ import type { DataColumn, FlatColumn } from '../columns.js';
 import type { PluginInitTableState, TableAttributes, TableBodyAttributes, TableHeadAttributes } from '../createViewModel.js';
 import type { HeaderCell, HeaderCellAttributes } from '../headerCells.js';
 import type { HeaderRow, HeaderRowAttributes } from '../headerRows.js';
-export type TablePlugin<Item, PluginState, ColumnOptions, TablePropSet extends AnyTablePropSet = AnyTablePropSet, TableAttributeSet extends AnyTableAttributeSet = AnyTableAttributeSet> = (init: TablePluginInit<Item, ColumnOptions>) => TablePluginInstance<Item, PluginState, ColumnOptions, TablePropSet, TableAttributeSet>;
+/**
+ * A table plugin factory function.
+ * Receives initialization options and returns a plugin instance.
+ *
+ * @template Item - The type of data items in the table.
+ * @template PluginState - The state exposed by the plugin.
+ * @template ColumnOptions - Per-column configuration options.
+ * @template TablePropSet - Props added to table components.
+ * @template TableAttributeSet - Attributes added to table components.
+ */
+export type TablePlugin<Item, PluginState, ColumnOptions, TablePropSet extends AnyTablePropSet = AnyTablePropSet, TableAttributeSet extends AnyTableAttributeSet = AnyTableAttributeSet> = (_init: TablePluginInit<Item, ColumnOptions>) => TablePluginInstance<Item, PluginState, ColumnOptions, TablePropSet, TableAttributeSet>;
+/**
+ * Initialization options passed to a table plugin.
+ *
+ * @template Item - The type of data items in the table.
+ * @template ColumnOptions - Per-column configuration options.
+ */
 export type TablePluginInit<Item, ColumnOptions> = {
+    /** The name/key of this plugin in the plugins object. */
     pluginName: string;
+    /** The table state during plugin initialization. */
     tableState: PluginInitTableState<Item>;
+    /** Column options keyed by column ID. */
     columnOptions: Record<string, ColumnOptions>;
 };
+/**
+ * A plugin instance returned by a TablePlugin factory.
+ * Contains state, transformation functions, and component hooks.
+ *
+ * @template Item - The type of data items in the table.
+ * @template PluginState - The state exposed by the plugin.
+ * @template ColumnOptions - Per-column configuration options.
+ * @template TablePropSet - Props added to table components.
+ * @template TableAttributeSet - Attributes added to table components.
+ */
 export type TablePluginInstance<Item, PluginState, ColumnOptions, TablePropSet extends AnyTablePropSet = AnyTablePropSet, TableAttributeSet extends AnyTableAttributeSet = AnyTableAttributeSet> = {
     pluginState: PluginState;
     transformFlatColumnsFn?: Readable<TransformFlatColumnsFn<Item>>;
@@ -23,65 +52,166 @@ export type TablePluginInstance<Item, PluginState, ColumnOptions, TablePropSet e
     columnOptions?: ColumnOptions;
     hooks?: TableHooks<Item, TablePropSet, TableAttributeSet>;
 };
+/**
+ * A record of table plugins, keyed by plugin name.
+ * Used as a type constraint for the plugins parameter.
+ */
 export type AnyPlugins = Record<any, TablePlugin<any, any, any, any, any>>;
+/**
+ * A record of plugin instances, keyed by plugin name.
+ * Used internally after plugins are initialized.
+ */
 export type AnyPluginInstances = Record<any, TablePluginInstance<any, any, any, any, any>>;
-export type TransformFlatColumnsFn<Item> = (flatColumns: DataColumn<Item>[]) => DataColumn<Item>[];
-export type DeriveFlatColumnsFn<Item> = <Col extends FlatColumn<Item>>(flatColumns: Readable<Col[]>) => Readable<Col[]>;
-export type DeriveRowsFn<Item> = <Row extends BodyRow<Item>>(rows: Readable<Row[]>) => Readable<Row[]>;
-export type DeriveFn<T> = (obj: Readable<T>) => Readable<T>;
+/**
+ * A synchronous function that transforms flat columns.
+ *
+ * @template Item - The type of data items in the table.
+ */
+export type TransformFlatColumnsFn<Item> = (_flatColumns: DataColumn<Item>[]) => DataColumn<Item>[];
+/**
+ * A reactive function that derives flat columns from a store.
+ *
+ * @template Item - The type of data items in the table.
+ */
+export type DeriveFlatColumnsFn<Item> = <Col extends FlatColumn<Item>>(_flatColumns: Readable<Col[]>) => Readable<Col[]>;
+/**
+ * A reactive function that derives rows from a store.
+ *
+ * @template Item - The type of data items in the table.
+ */
+export type DeriveRowsFn<Item> = <Row extends BodyRow<Item>>(_rows: Readable<Row[]>) => Readable<Row[]>;
+/**
+ * A generic reactive derivation function.
+ *
+ * @template T - The type being derived.
+ */
+export type DeriveFn<T> = (_obj: Readable<T>) => Readable<T>;
+/**
+ * Maps component keys to their corresponding component types.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type Components<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     'thead.tr': HeaderRow<Item, Plugins>;
     'thead.tr.th': HeaderCell<Item, Plugins>;
     'tbody.tr': BodyRow<Item, Plugins>;
     'tbody.tr.td': BodyCell<Item, Plugins>;
 };
+/**
+ * Maps component keys to their corresponding attribute types.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type AttributesForKey<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     'thead.tr': HeaderRowAttributes<Item, Plugins>;
     'thead.tr.th': HeaderCellAttributes<Item, Plugins>;
     'tbody.tr': BodyRowAttributes<Item, Plugins>;
     'tbody.tr.td': BodyCellAttributes<Item, Plugins>;
 };
+/**
+ * Valid keys for table components: header rows, header cells, body rows, body cells.
+ */
 export type ComponentKeys = keyof Components<unknown>;
 type TablePropSet<PropSet extends {
-    [K in ComponentKeys]?: unknown;
+    [_K in ComponentKeys]?: unknown;
 }> = {
     [K in ComponentKeys]: PropSet[K];
 };
+/**
+ * Creates a new table prop set type, filtering out undefined component props.
+ *
+ * @template PropSet - The prop set definition.
+ */
 export type NewTablePropSet<PropSet extends {
-    [K in ComponentKeys]?: unknown;
+    [_K in ComponentKeys]?: unknown;
 }> = {
     [K in ComponentKeys]: unknown extends PropSet[K] ? never : PropSet[K];
 };
+/**
+ * A table prop set with any types. Used as a type constraint.
+ */
 export type AnyTablePropSet = TablePropSet<any>;
+/**
+ * Internal type for mapping component keys to attribute sets.
+ * @internal
+ */
 type TableAttributeSet<AttributeSet extends {
-    [K in ComponentKeys]?: unknown;
+    [_K in ComponentKeys]?: unknown;
 }> = {
     [K in ComponentKeys]: AttributeSet[K];
 };
+/**
+ * Creates a new table attribute set type, filtering out undefined component attributes.
+ *
+ * @template AttributeSet - The attribute set definition.
+ */
 export type NewTableAttributeSet<AttributeSet extends {
-    [K in ComponentKeys]?: unknown;
+    [_K in ComponentKeys]?: unknown;
 }> = {
     [K in ComponentKeys]: unknown extends AttributeSet[K] ? never : AttributeSet[K];
 };
+/**
+ * A table attribute set with any types. Used as a type constraint.
+ */
 export type AnyTableAttributeSet = TableAttributeSet<any>;
+/**
+ * Hooks for attaching props and attributes to table components.
+ * Each hook receives a component and returns props/attrs stores.
+ *
+ * @template Item - The type of data items in the table.
+ * @template PropSet - The prop set type.
+ * @template AttributeSet - The attribute set type.
+ */
 export type TableHooks<Item, PropSet extends AnyTablePropSet = AnyTablePropSet, AttributeSet extends AnyTableAttributeSet = AnyTableAttributeSet> = {
-    [ComponentKey in keyof Components<Item>]?: (component: Components<Item>[ComponentKey]) => ElementHook<PropSet[ComponentKey], AttributeSet[ComponentKey]>;
+    [ComponentKey in keyof Components<Item>]?: (_component: Components<Item>[ComponentKey]) => ElementHook<PropSet[ComponentKey], AttributeSet[ComponentKey]>;
 };
+/**
+ * Return type for component hooks.
+ * Contains optional readable stores for props and attributes.
+ *
+ * @template Props - The props type.
+ * @template Attributes - The attributes type.
+ */
 export type ElementHook<Props, Attributes> = {
+    /** Reactive props store. */
     props?: Readable<Props>;
+    /** Reactive attributes store. */
     attrs?: Readable<Attributes>;
 };
+/**
+ * Extracts the plugin state types from a plugins record.
+ *
+ * @template Plugins - The plugins record type.
+ */
 export type PluginStates<Plugins extends AnyPlugins> = {
     [K in keyof Plugins]: ReturnType<Plugins[K]>['pluginState'];
 };
+/**
+ * Internal type for extracting prop sets from plugins.
+ * @internal
+ */
 type TablePropSetForPluginKey<Plugins extends AnyPlugins> = {
     [K in keyof Plugins]: Plugins[K] extends TablePlugin<any, any, any, infer TablePropSet> ? TablePropSet : never;
 };
+/**
+ * Combines prop sets from all plugins into a single type.
+ * Props are grouped by component key, then by plugin key.
+ *
+ * @template Plugins - The plugins record type.
+ */
 export type PluginTablePropSet<Plugins extends AnyPlugins> = {
     [ComponentKey in ComponentKeys]: {
         [PluginKey in keyof Plugins]: TablePropSetForPluginKey<Plugins>[PluginKey][ComponentKey];
     };
 };
+/**
+ * Extracts column configuration types from all plugins.
+ * Used to type the `plugins` option in column definitions.
+ *
+ * @template Plugins - The plugins record type.
+ */
 export type PluginColumnConfigs<Plugins extends AnyPlugins> = Partial<{
     [K in keyof Plugins]: ReturnType<Plugins[K]>['columnOptions'];
 }>;

package/dist/utils/array.d.ts

@@ -1,2 +1,26 @@
+/**
+ * Returns an array containing only the distinct elements from the input array.
+ * Preserves the order of first occurrence.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The input array potentially containing duplicates.
+ * @returns A new array with duplicate elements removed.
+ * @example
+ * ```typescript
+ * getDistinct([1, 2, 2, 3, 1]) // Returns [1, 2, 3]
+ * ```
+ */
 export declare const getDistinct: <T>(items: T[]) => T[];
+/**
+ * Returns an array containing only the elements that appear more than once
+ * in the input array.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The input array to check for duplicates.
+ * @returns A new array containing only duplicate elements.
+ * @example
+ * ```typescript
+ * getDuplicates([1, 2, 2, 3, 1]) // Returns [1, 2]
+ * ```
+ */
 export declare const getDuplicates: <T>(items: T[]) => T[];

package/dist/utils/array.js

@@ -1,7 +1,31 @@
 import { getCounter } from './counter.js';
+/**
+ * Returns an array containing only the distinct elements from the input array.
+ * Preserves the order of first occurrence.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The input array potentially containing duplicates.
+ * @returns A new array with duplicate elements removed.
+ * @example
+ * ```typescript
+ * getDistinct([1, 2, 2, 3, 1]) // Returns [1, 2, 3]
+ * ```
+ */
 export const getDistinct = (items) => {
     return Array.from(getCounter(items).keys());
 };
+/**
+ * Returns an array containing only the elements that appear more than once
+ * in the input array.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - The input array to check for duplicates.
+ * @returns A new array containing only duplicate elements.
+ * @example
+ * ```typescript
+ * getDuplicates([1, 2, 2, 3, 1]) // Returns [1, 2]
+ * ```
+ */
 export const getDuplicates = (items) => {
     return Array.from(getCounter(items).entries())
         .filter(([, count]) => count !== 1)

package/dist/utils/attributes.d.ts

@@ -1,2 +1,33 @@
+/**
+ * Merges two attribute objects, with special handling for style properties.
+ * Style objects are deeply merged rather than overwritten.
+ *
+ * @template T - The type of the first attributes object.
+ * @template U - The type of the second attributes object.
+ * @param a - The first attributes object.
+ * @param b - The second attributes object (takes precedence for non-style properties).
+ * @returns A merged attributes object with combined styles.
+ * @example
+ * ```typescript
+ * mergeAttributes(
+ *   { class: 'foo', style: { color: 'red' } },
+ *   { class: 'bar', style: { fontSize: '14px' } }
+ * )
+ * // Returns { class: 'bar', style: { color: 'red', fontSize: '14px' } }
+ * ```
+ */
 export declare const mergeAttributes: <T extends Record<string, unknown>, U extends Record<string, unknown>>(a: T, b: U) => T & U;
+/**
+ * Converts an attributes object's style property from an object to a CSS string.
+ * This prepares attributes for use in DOM elements.
+ *
+ * @template T - The type of the attributes object.
+ * @param attrs - The attributes object with a potential style object.
+ * @returns A new attributes object with the style converted to a string.
+ * @example
+ * ```typescript
+ * finalizeAttributes({ class: 'foo', style: { color: 'red' } })
+ * // Returns { class: 'foo', style: 'color:red' }
+ * ```
+ */
 export declare const finalizeAttributes: <T extends Record<string, unknown>>(attrs: T) => Record<string, unknown>;

package/dist/utils/attributes.js

@@ -1,4 +1,22 @@
 import { stringifyCss } from './css.js';
+/**
+ * Merges two attribute objects, with special handling for style properties.
+ * Style objects are deeply merged rather than overwritten.
+ *
+ * @template T - The type of the first attributes object.
+ * @template U - The type of the second attributes object.
+ * @param a - The first attributes object.
+ * @param b - The second attributes object (takes precedence for non-style properties).
+ * @returns A merged attributes object with combined styles.
+ * @example
+ * ```typescript
+ * mergeAttributes(
+ *   { class: 'foo', style: { color: 'red' } },
+ *   { class: 'bar', style: { fontSize: '14px' } }
+ * )
+ * // Returns { class: 'bar', style: { color: 'red', fontSize: '14px' } }
+ * ```
+ */
 export const mergeAttributes = (a, b) => {
     if (a.style === undefined && b.style === undefined) {
         return { ...a, ...b };
@@ -12,6 +30,19 @@ export const mergeAttributes = (a, b) => {
         }
     };
 };
+/**
+ * Converts an attributes object's style property from an object to a CSS string.
+ * This prepares attributes for use in DOM elements.
+ *
+ * @template T - The type of the attributes object.
+ * @param attrs - The attributes object with a potential style object.
+ * @returns A new attributes object with the style converted to a string.
+ * @example
+ * ```typescript
+ * finalizeAttributes({ class: 'foo', style: { color: 'red' } })
+ * // Returns { class: 'foo', style: 'color:red' }
+ * ```
+ */
 export const finalizeAttributes = (attrs) => {
     if (attrs.style === undefined || typeof attrs.style !== 'object') {
         return attrs;

package/dist/utils/clone.d.ts

@@ -1,6 +1,25 @@
+/**
+ * Interface for objects that can create a copy of themselves.
+ *
+ * @template T - The type of the cloned object.
+ */
 export interface Clonable<T> {
+    /** Creates and returns a copy of the object. */
     clone(): T;
 }
+/**
+ * Type guard that checks if an object implements the Clonable interface.
+ *
+ * @template T - The expected type of the cloned object.
+ * @param obj - The object to check.
+ * @returns True if the object has a clone method.
+ * @example
+ * ```typescript
+ * if (isClonable(obj)) {
+ *   const copy = obj.clone()
+ * }
+ * ```
+ */
 export declare const isClonable: <T>(obj: unknown) => obj is Clonable<T>;
 /**
  * Create a new instance of a class instance with all properties shallow

package/dist/utils/clone.js

@@ -1,3 +1,16 @@
+/**
+ * Type guard that checks if an object implements the Clonable interface.
+ *
+ * @template T - The expected type of the cloned object.
+ * @param obj - The object to check.
+ * @returns True if the object has a clone method.
+ * @example
+ * ```typescript
+ * if (isClonable(obj)) {
+ *   const copy = obj.clone()
+ * }
+ * ```
+ */
 export const isClonable = (obj) => {
     return typeof obj.clone === 'function';
 };

package/dist/utils/compare.d.ts

@@ -1,2 +1,31 @@
+/**
+ * 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 declare const compare: <T extends string | number>(a: T | T[], b: T | T[]) => number;
+/**
+ * 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 declare const compareArray: <T extends string | number>(a: T[], b: T[]) => number;

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) => {