@humanspeak/svelte-headless-table 6.0.2 → 6.0.4

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/HeightManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * HeightManager handles row height caching and calculations for virtual scrolling.
+ * It maintains a cache of measured row heights and provides methods to calculate
+ * scroll positions, visible ranges, and total heights.
+ */
+export declare class HeightManager {
+    /** Cache of measured row heights by row ID. */
+    private heightCache;
+    /** Estimated height for unmeasured rows. */
+    private estimatedRowHeight;
+    /** Sum of all measured heights. */
+    private totalMeasuredHeight;
+    /** Number of measured rows. */
+    private measuredCount;
+    /**
+     * Creates a new HeightManager.
+     *
+     * @param estimatedRowHeight - Initial estimated height for unmeasured rows.
+     */
+    constructor(estimatedRowHeight?: number);
+    /**
+     * Set or update the height for a specific row.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @param height - The measured height of the row in pixels.
+     * @returns True if the height changed, false otherwise.
+     */
+    setHeight(rowId: string, height: number): boolean;
+    /**
+     * Get the height for a specific row.
+     * Returns the measured height if available, otherwise the estimated height.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns The height of the row in pixels.
+     */
+    getHeight(rowId: string): number;
+    /**
+     * Check if a row has been measured.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns True if the row has been measured.
+     */
+    hasMeasurement(rowId: string): boolean;
+    /**
+     * Get the average height of measured rows.
+     * Falls back to the estimated height if no rows have been measured.
+     *
+     * @returns The average row height in pixels.
+     */
+    getAverageHeight(): number;
+    /**
+     * Calculate the total height for a given number of rows.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @returns The total height in pixels.
+     */
+    getTotalHeight(rowIds: string[]): number;
+    /**
+     * Calculate the offset (top position) for a given row index.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param index - The index of the target row.
+     * @returns The offset from the top in pixels.
+     */
+    getOffsetForIndex(rowIds: string[], index: number): number;
+    /**
+     * Calculate which rows are visible given a scroll position and viewport height.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - Current scroll position.
+     * @param viewportHeight - Height of the visible area.
+     * @param bufferSize - Number of extra rows to render above/below.
+     * @returns Object with start and end indices of visible rows.
+     */
+    getVisibleRange(rowIds: string[], scrollTop: number, viewportHeight: number, bufferSize: number): {
+        start: number;
+        end: number;
+    };
+    /**
+     * Find the row index at a given scroll position.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - The scroll position to find.
+     * @returns The index of the row at that position.
+     */
+    getIndexAtOffset(rowIds: string[], scrollTop: number): number;
+    /**
+     * Clear all cached heights.
+     */
+    clear(): void;
+    /**
+     * Remove a specific row from the cache.
+     *
+     * @param rowId - The unique identifier of the row to remove.
+     */
+    remove(rowId: string): void;
+    /**
+     * Get the number of measured rows.
+     */
+    get size(): number;
+    /**
+     * Update the estimated row height.
+     *
+     * @param height - New estimated height in pixels.
+     */
+    setEstimatedRowHeight(height: number): void;
+}

package/dist/utils/HeightManager.js

@@ -0,0 +1,204 @@
+/**
+ * HeightManager handles row height caching and calculations for virtual scrolling.
+ * It maintains a cache of measured row heights and provides methods to calculate
+ * scroll positions, visible ranges, and total heights.
+ */
+export class HeightManager {
+    /** Cache of measured row heights by row ID. */
+    heightCache = new Map();
+    /** Estimated height for unmeasured rows. */
+    estimatedRowHeight;
+    /** Sum of all measured heights. */
+    totalMeasuredHeight = 0;
+    /** Number of measured rows. */
+    measuredCount = 0;
+    /**
+     * Creates a new HeightManager.
+     *
+     * @param estimatedRowHeight - Initial estimated height for unmeasured rows.
+     */
+    constructor(estimatedRowHeight = 40) {
+        this.estimatedRowHeight = estimatedRowHeight;
+    }
+    /**
+     * Set or update the height for a specific row.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @param height - The measured height of the row in pixels.
+     * @returns True if the height changed, false otherwise.
+     */
+    setHeight(rowId, height) {
+        const existing = this.heightCache.get(rowId);
+        if (existing === height) {
+            return false;
+        }
+        if (existing !== undefined) {
+            // Update existing measurement
+            this.totalMeasuredHeight -= existing;
+            this.totalMeasuredHeight += height;
+        }
+        else {
+            // New measurement
+            this.totalMeasuredHeight += height;
+            this.measuredCount++;
+        }
+        this.heightCache.set(rowId, height);
+        return true;
+    }
+    /**
+     * Get the height for a specific row.
+     * Returns the measured height if available, otherwise the estimated height.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns The height of the row in pixels.
+     */
+    getHeight(rowId) {
+        return this.heightCache.get(rowId) ?? this.getAverageHeight();
+    }
+    /**
+     * Check if a row has been measured.
+     *
+     * @param rowId - The unique identifier of the row.
+     * @returns True if the row has been measured.
+     */
+    hasMeasurement(rowId) {
+        return this.heightCache.has(rowId);
+    }
+    /**
+     * Get the average height of measured rows.
+     * Falls back to the estimated height if no rows have been measured.
+     *
+     * @returns The average row height in pixels.
+     */
+    getAverageHeight() {
+        if (this.measuredCount === 0) {
+            return this.estimatedRowHeight;
+        }
+        return this.totalMeasuredHeight / this.measuredCount;
+    }
+    /**
+     * Calculate the total height for a given number of rows.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @returns The total height in pixels.
+     */
+    getTotalHeight(rowIds) {
+        const avgHeight = this.getAverageHeight();
+        let total = 0;
+        for (const rowId of rowIds) {
+            total += this.heightCache.get(rowId) ?? avgHeight;
+        }
+        return total;
+    }
+    /**
+     * Calculate the offset (top position) for a given row index.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param index - The index of the target row.
+     * @returns The offset from the top in pixels.
+     */
+    getOffsetForIndex(rowIds, index) {
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        for (let i = 0; i < index && i < rowIds.length; i++) {
+            offset += this.heightCache.get(rowIds[i]) ?? avgHeight;
+        }
+        return offset;
+    }
+    /**
+     * Calculate which rows are visible given a scroll position and viewport height.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - Current scroll position.
+     * @param viewportHeight - Height of the visible area.
+     * @param bufferSize - Number of extra rows to render above/below.
+     * @returns Object with start and end indices of visible rows.
+     */
+    getVisibleRange(rowIds, scrollTop, viewportHeight, bufferSize) {
+        if (rowIds.length === 0) {
+            return { start: 0, end: 0 };
+        }
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        let start = 0;
+        let end = rowIds.length;
+        // Find start index (first row that's at least partially visible)
+        for (let i = 0; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset + height > scrollTop) {
+                start = Math.max(0, i - bufferSize);
+                break;
+            }
+            offset += height;
+        }
+        // Find end index (first row that's completely below the viewport)
+        const bottomEdge = scrollTop + viewportHeight;
+        for (let i = start; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset >= bottomEdge) {
+                end = Math.min(rowIds.length, i + bufferSize);
+                break;
+            }
+            offset += height;
+        }
+        // If we reached the end without finding bottomEdge, show all remaining rows
+        if (end === rowIds.length) {
+            end = rowIds.length;
+        }
+        return { start, end };
+    }
+    /**
+     * Find the row index at a given scroll position.
+     *
+     * @param rowIds - Array of row IDs in order.
+     * @param scrollTop - The scroll position to find.
+     * @returns The index of the row at that position.
+     */
+    getIndexAtOffset(rowIds, scrollTop) {
+        const avgHeight = this.getAverageHeight();
+        let offset = 0;
+        for (let i = 0; i < rowIds.length; i++) {
+            const height = this.heightCache.get(rowIds[i]) ?? avgHeight;
+            if (offset + height > scrollTop) {
+                return i;
+            }
+            offset += height;
+        }
+        return Math.max(0, rowIds.length - 1);
+    }
+    /**
+     * Clear all cached heights.
+     */
+    clear() {
+        this.heightCache.clear();
+        this.totalMeasuredHeight = 0;
+        this.measuredCount = 0;
+    }
+    /**
+     * Remove a specific row from the cache.
+     *
+     * @param rowId - The unique identifier of the row to remove.
+     */
+    remove(rowId) {
+        const height = this.heightCache.get(rowId);
+        if (height !== undefined) {
+            this.totalMeasuredHeight -= height;
+            this.measuredCount--;
+            this.heightCache.delete(rowId);
+        }
+    }
+    /**
+     * Get the number of measured rows.
+     */
+    get size() {
+        return this.measuredCount;
+    }
+    /**
+     * Update the estimated row height.
+     *
+     * @param height - New estimated height in pixels.
+     */
+    setEstimatedRowHeight(height) {
+        this.estimatedRowHeight = height;
+    }
+}

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