/** * Keyed List Diffing Algorithm * * Uses a simplified LIS (Longest Increasing Subsequence) approach * for optimal DOM operations. * * Benefits: * - Minimizes DOM operations (moves instead of recreate) * - Preserves element state (focus, scroll, animations) * - O(n) best case, O(n log n) worst case * * Usage with $for: * $for="item in items track by item.id" * ^^^^^^^^^^^^^^ * Key expression for efficient diffing */ export interface DiffOperation { type: "insert" | "remove" | "move" | "update"; /** Index in the old array (for remove/move/update) */ oldIndex?: number; /** Index in the new array (for insert/move/update) */ newIndex?: number; /** The item data */ item?: unknown; /** Key for keyed operations */ key?: unknown; } /** * Computes the minimal set of DOM operations to transform oldItems into newItems. * Uses keys for identity matching - items with the same key are considered the same. * * @param oldItems - Previous array items * @param newItems - New array items * @param getKey - Function to extract a unique key from an item * @returns Array of operations to perform * * @example * const ops = diffKeyed( * [{ id: 1, name: 'A' }, { id: 2, name: 'B' }], * [{ id: 2, name: 'B' }, { id: 1, name: 'A' }, { id: 3, name: 'C' }], * item => item.id * ); * // ops = [ * // { type: 'move', oldIndex: 1, newIndex: 0, key: 2 }, * // { type: 'move', oldIndex: 0, newIndex: 1, key: 1 }, * // { type: 'insert', newIndex: 2, key: 3, item: { id: 3, name: 'C' } } * // ] */ export declare function diffKeyed(oldItems: T[], newItems: T[], getKey: (item: T, index: number) => unknown): DiffOperation[]; /** * Simpler diff for non-keyed lists. * Less efficient but works when items don't have stable identity. * * @param oldLength - Previous array length * @param newLength - New array length * @param newItems - New array items * @returns Array of operations */ export declare function diffUnkeyed(oldLength: number, newLength: number, newItems: T[]): DiffOperation[]; /** * Computes the set of positions that form the longest increasing subsequence * of `source`, ignoring entries whose value is < 0 (used to mark brand-new * items that must always be (re)inserted). * * The loop renderer uses this to decide which reused elements are already in * correct relative DOM order and can therefore stay put — only the remaining * elements need to be moved. This turns an in-order content update into zero * DOM moves and minimizes moves for partial reorders. * * Runs in O(n log n) using patience sorting with predecessor links. * * @param source - For each new position, the element's previous index, or -1 if new * @returns Set of new-position indices that should NOT be moved */ export declare function getStableIndices(source: number[]): Set; /** * Creates a key getter function from a key expression. * * @param keyExpr - Key expression (e.g., "item.id" or just "id" if item is scope) * @param itemName - The loop variable name (e.g., "item") * @returns A function that extracts the key from an item * * @example * const getKey = createKeyGetter("item.id", "item"); * getKey({ id: 123, name: "foo" }) // 123 */ export declare function createKeyGetter(keyExpr: string | undefined, itemName: string): (item: T, index: number) => unknown; /** * Applies diff operations to a list of DOM elements. * This is the main integration point with the loop renderer. * * @param container - Parent element containing the list * @param elements - Current rendered elements * @param operations - Diff operations to apply * @param createFn - Function to create a new element for an item * @param updateFn - Function to update an existing element * @returns The new array of elements */ export declare function applyDiffOperations(container: Element | ShadowRoot, elements: Element[], operations: DiffOperation[], createFn: (item: T, index: number) => Element, updateFn: (element: Element, item: T, index: number) => void): Element[];