stellar-drive 1.0.0

package/dist/actions/remoteChange.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Remote Change Animation Action
+ *
+ * A Svelte action that automatically adds remote change animations to elements.
+ * Use this on list items, cards, or any element that can be updated remotely
+ * (e.g., via Supabase Realtime subscriptions).
+ *
+ * The action detects the ACTION TYPE from the remote change and applies
+ * the appropriate CSS animation class:
+ *   - `'create'`    --> `item-created`       (slide in with burst)
+ *   - `'delete'`    --> `item-deleting`       (slide out with fade)
+ *   - `'toggle'`    --> `item-toggled`        (+ checkbox-animating + completion-ripple)
+ *   - `'increment'` --> `counter-increment`   (bump up)
+ *   - `'decrement'` --> `counter-decrement`   (bump down)
+ *   - `'reorder'`   --> `item-reordering`     (slide to new position)
+ *   - `'rename'`    --> `text-changed`        (highlight flash)
+ *   - `'update'`    --> `item-changed`        (default highlight)
+ *
+ * @example
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   ...
+ * </div>
+ * ```
+ *
+ * @see {@link remoteChangeAnimation} for the main Svelte action
+ * @see {@link trackEditing} for deferred-change tracking on forms
+ * @see {@link triggerLocalAnimation} for programmatic local animations
+ */
+import { type RemoteActionType } from '../stores/remoteChanges';
+/**
+ * Configuration options for the {@link remoteChangeAnimation} Svelte action.
+ */
+interface RemoteChangeOptions {
+    /** The unique identifier of the entity being watched (e.g., a row UUID). */
+    entityId: string;
+    /** The entity type / table name (e.g., `'goals'`, `'tasks'`). */
+    entityType: string;
+    /**
+     * Optional list of field names to watch. When provided, animations are
+     * only triggered if the remote change includes at least one of these
+     * fields (or the wildcard `'*'`). Omit to animate on any field change.
+     */
+    fields?: string[];
+    /**
+     * Optional CSS class override. When set, this class is used instead of
+     * the default mapping from {@link ACTION_ANIMATION_MAP}.
+     */
+    animationClass?: string;
+    /**
+     * Optional callback invoked when a remote action is detected.
+     * Useful for component-specific handling beyond CSS animations
+     * (e.g., updating local state, playing sounds, showing toasts).
+     *
+     * @param actionType - The type of remote action detected.
+     * @param fields - The list of fields that changed.
+     */
+    onAction?: (actionType: RemoteActionType, fields: string[]) => void;
+}
+/**
+ * Svelte action that watches for remote changes on a specific entity and
+ * applies the appropriate CSS animation class to the host element.
+ *
+ * **Lifecycle:**
+ *   1. On mount, checks for a recent change that may have arrived before
+ *      the element was rendered (important for CREATE animations on new items).
+ *   2. Subscribes to the `remoteChangesStore` for future changes.
+ *   3. Subscribes to a pending-delete indicator for delete animations.
+ *   4. On update, re-subscribes if the entity identity changes.
+ *   5. On destroy, unsubscribes and cleans up CSS classes.
+ *
+ * @param node - The DOM element to animate.
+ * @param options - Configuration specifying which entity to watch.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ *
+ * @example
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   {item.name}
+ * </div>
+ * ```
+ */
+export declare function remoteChangeAnimation(node: HTMLElement, options: RemoteChangeOptions): {
+    /**
+     * Called when the action's options change. If the entity identity
+     * (`entityId` or `entityType`) has changed, tears down old subscriptions
+     * and creates new ones for the updated entity.
+     *
+     * @param newOptions - The updated {@link RemoteChangeOptions}.
+     */
+    update(newOptions: RemoteChangeOptions): void;
+    /**
+     * Cleanup handler — unsubscribes from all stores, removes the base
+     * CSS class, and clears the element from the animation tracking set.
+     */
+    destroy(): void;
+};
+/**
+ * Svelte action for form elements that should track editing state.
+ * Use this on modal forms with Save buttons to defer remote changes
+ * while the user is actively editing, preventing disruptive overwrites.
+ *
+ * When the form is destroyed (e.g., modal closes), any deferred changes
+ * are passed to the `onDeferredChanges` callback so the component can
+ * decide how to reconcile them.
+ *
+ * @example
+ * ```svelte
+ * <form use:trackEditing={{ entityId: item.id, entityType: 'goals', formType: 'manual-save' }}>
+ *   ...
+ * </form>
+ * ```
+ */
+/**
+ * Configuration options for the {@link trackEditing} Svelte action.
+ */
+interface TrackEditingOptions {
+    /** The unique identifier of the entity being edited. */
+    entityId: string;
+    /** The entity type / table name (e.g., `'goals'`, `'tasks'`). */
+    entityType: string;
+    /**
+     * The save behaviour of the form:
+     *   - `'auto-save'` — changes are saved immediately (e.g., inline editing).
+     *   - `'manual-save'` — changes are saved on explicit submit (e.g., modal form).
+     */
+    formType: 'auto-save' | 'manual-save';
+    /**
+     * Optional list of field names this form edits. When provided, only
+     * remote changes to these fields are deferred; changes to other fields
+     * are applied immediately.
+     */
+    fields?: string[];
+    /**
+     * Callback invoked when the form closes and there are deferred changes
+     * that need processing (e.g., conflict resolution, data refresh).
+     *
+     * @param changes - The array of deferred remote change objects.
+     */
+    onDeferredChanges?: (changes: unknown[]) => void;
+}
+/**
+ * Svelte action that marks an entity as "being edited" in the remote changes
+ * store. While editing, incoming remote changes for the same entity are
+ * deferred instead of applied immediately.
+ *
+ * **Lifecycle:**
+ *   1. On mount, calls `remoteChangesStore.startEditing()` to begin deferral.
+ *   2. Periodically checks for deferred changes and toggles a CSS class
+ *      (`has-deferred-changes`) on the node for visual indication.
+ *   3. On update, re-registers if the entity identity changes.
+ *   4. On destroy, calls `remoteChangesStore.stopEditing()` and invokes
+ *      `onDeferredChanges` if any changes were deferred.
+ *
+ * @param node - The form DOM element.
+ * @param options - Configuration specifying which entity is being edited.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ */
+export declare function trackEditing(node: HTMLElement, options: TrackEditingOptions): {
+    /**
+     * Called when the action's options change. If the entity identity
+     * changes, stops tracking the old entity and starts tracking the new one.
+     *
+     * @param newOptions - The updated {@link TrackEditingOptions}.
+     */
+    update(newOptions: TrackEditingOptions): void;
+    /**
+     * Cleanup handler — stops the polling interval, removes CSS classes,
+     * stops editing in the store, and notifies the callback of any
+     * deferred changes that accumulated during the editing session.
+     */
+    destroy(): void;
+};
+/**
+ * Trigger a local action animation on an element.
+ *
+ * Use this to make local user actions (e.g., tapping a checkbox, incrementing
+ * a counter) animate with the same visual treatment as remote changes, giving
+ * the UI a consistent feel.
+ *
+ * For `increment` and `decrement` actions, rapid repeated invocations will
+ * restart the animation instead of being blocked — this allows the counter
+ * to visually "bump" on each tap.
+ *
+ * @param element - The DOM element to animate (or `null`, in which case this is a no-op).
+ * @param actionType - The type of animation to apply.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { triggerLocalAnimation } from 'stellar-drive';
+ *   let element: HTMLElement;
+ *
+ *   function handleToggle() {
+ *     triggerLocalAnimation(element, 'toggle');
+ *     onToggle?.();
+ *   }
+ * </script>
+ * <div bind:this={element}>...</div>
+ * ```
+ */
+export declare function triggerLocalAnimation(element: HTMLElement | null, actionType: RemoteActionType): void;
+export {};
+//# sourceMappingURL=remoteChange.d.ts.map

package/dist/actions/remoteChange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteChange.d.ts","sourceRoot":"","sources":["../../src/actions/remoteChange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAMjC;;GAEG;AACH,UAAU,mBAAmB;IAC3B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACrE;AAsDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;IAgJjF;;;;;;OAMG;uBACgB,mBAAmB;IA4BtC;;;OAGG;;EAQN;AAMD;;;;;;;;;;;;;;;GAeG;AAEH;;GAEG;AACH,UAAU,mBAAmB;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,WAAW,GAAG,aAAa,CAAC;IAEtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB;IAwBxE;;;;;OAKG;uBACgB,mBAAmB;IAatC;;;;OAIG;;EAcN;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CA8DN"}

package/dist/actions/remoteChange.js

@@ -0,0 +1,424 @@
+/**
+ * @fileoverview Remote Change Animation Action
+ *
+ * A Svelte action that automatically adds remote change animations to elements.
+ * Use this on list items, cards, or any element that can be updated remotely
+ * (e.g., via Supabase Realtime subscriptions).
+ *
+ * The action detects the ACTION TYPE from the remote change and applies
+ * the appropriate CSS animation class:
+ *   - `'create'`    --> `item-created`       (slide in with burst)
+ *   - `'delete'`    --> `item-deleting`       (slide out with fade)
+ *   - `'toggle'`    --> `item-toggled`        (+ checkbox-animating + completion-ripple)
+ *   - `'increment'` --> `counter-increment`   (bump up)
+ *   - `'decrement'` --> `counter-decrement`   (bump down)
+ *   - `'reorder'`   --> `item-reordering`     (slide to new position)
+ *   - `'rename'`    --> `text-changed`        (highlight flash)
+ *   - `'update'`    --> `item-changed`        (default highlight)
+ *
+ * @example
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   ...
+ * </div>
+ * ```
+ *
+ * @see {@link remoteChangeAnimation} for the main Svelte action
+ * @see {@link trackEditing} for deferred-change tracking on forms
+ * @see {@link triggerLocalAnimation} for programmatic local animations
+ */
+import { remoteChangesStore, createRecentChangeIndicator, createPendingDeleteIndicator } from '../stores/remoteChanges';
+// =============================================================================
+//                     ACTION-TO-CSS ANIMATION MAPPING
+// =============================================================================
+/**
+ * Maps each {@link RemoteActionType} to the CSS class name that triggers
+ * the corresponding animation. The consuming app must define these CSS
+ * classes (keyframes + durations) in its stylesheet.
+ */
+const ACTION_ANIMATION_MAP = {
+    create: 'item-created',
+    delete: 'item-deleting',
+    toggle: 'item-toggled',
+    increment: 'counter-increment',
+    decrement: 'counter-decrement',
+    reorder: 'item-reordering',
+    rename: 'text-changed',
+    update: 'item-changed'
+};
+/**
+ * Maps each {@link RemoteActionType} to its animation duration in
+ * milliseconds. Used for fallback cleanup timers in case the
+ * `animationend` DOM event never fires (e.g., display:none elements).
+ */
+const ACTION_DURATION_MAP = {
+    create: 600,
+    delete: 500,
+    toggle: 600,
+    increment: 400,
+    decrement: 400,
+    reorder: 400,
+    rename: 700,
+    update: 1600
+};
+// =============================================================================
+//                    ANIMATION OVERLAP PREVENTION
+// =============================================================================
+/**
+ * Tracks elements that currently have an active animation. Prevents
+ * overlapping animations on the same element which would cause visual
+ * glitches. Uses `WeakSet` so entries are automatically garbage-collected
+ * when the element is removed from the DOM.
+ */
+const animatingElements = new WeakSet();
+// =============================================================================
+//                   SVELTE ACTION: remoteChangeAnimation
+// =============================================================================
+/**
+ * Svelte action that watches for remote changes on a specific entity and
+ * applies the appropriate CSS animation class to the host element.
+ *
+ * **Lifecycle:**
+ *   1. On mount, checks for a recent change that may have arrived before
+ *      the element was rendered (important for CREATE animations on new items).
+ *   2. Subscribes to the `remoteChangesStore` for future changes.
+ *   3. Subscribes to a pending-delete indicator for delete animations.
+ *   4. On update, re-subscribes if the entity identity changes.
+ *   5. On destroy, unsubscribes and cleans up CSS classes.
+ *
+ * @param node - The DOM element to animate.
+ * @param options - Configuration specifying which entity to watch.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ *
+ * @example
+ * ```svelte
+ * <div use:remoteChangeAnimation={{ entityId: item.id, entityType: 'goals' }}>
+ *   {item.name}
+ * </div>
+ * ```
+ */
+export function remoteChangeAnimation(node, options) {
+    let { entityId, entityType, fields, animationClass, onAction } = options;
+    /* Add base class for styling hooks (e.g., transition defaults) */
+    node.classList.add('syncable-item');
+    // ---------------------------------------------------------------------------
+    //                    ANIMATION APPLICATION LOGIC
+    // ---------------------------------------------------------------------------
+    /**
+     * Apply the appropriate CSS animation to the node based on the change's
+     * action type and affected fields.
+     *
+     * Handles special cases for toggle (checkbox + ripple), increment/decrement
+     * (counter sub-element), and delete (no class removal — element will be
+     * removed from DOM by the parent component).
+     *
+     * @param change - The remote change descriptor with `actionType` and `fields`.
+     */
+    function applyAnimation(change) {
+        /* If specific fields are configured, only animate if at least one matches */
+        if (fields && fields.length > 0) {
+            const fieldsList = fields; /* Capture for closure safety */
+            const hasRelevantChange = change.fields.some((f) => f === '*' || fieldsList.includes(f));
+            if (!hasRelevantChange)
+                return;
+        }
+        /* Prevent overlapping animations on the same element */
+        if (animatingElements.has(node))
+            return;
+        animatingElements.add(node);
+        /* Determine animation class based on action type */
+        const actionType = change.actionType;
+        const cssClass = animationClass || ACTION_ANIMATION_MAP[actionType] || 'item-changed';
+        const duration = ACTION_DURATION_MAP[actionType] || 1600;
+        /* Call action callback if provided (for component-specific handling) */
+        if (onAction) {
+            onAction(actionType, change.fields);
+        }
+        /* Apply animation class */
+        node.classList.add(cssClass);
+        /* For toggle actions, also add checkbox animation to child checkbox elements */
+        if (actionType === 'toggle') {
+            const checkbox = node.querySelector('.checkbox, [class*="checkbox"]');
+            if (checkbox) {
+                checkbox.classList.add('checkbox-animating');
+                setTimeout(() => checkbox.classList.remove('checkbox-animating'), 500);
+            }
+            /* Add completion ripple effect — a temporary <span> that auto-removes */
+            const ripple = document.createElement('span');
+            ripple.className = 'completion-ripple';
+            node.appendChild(ripple);
+            setTimeout(() => ripple.remove(), 700);
+        }
+        /* For increment/decrement, animate the counter sub-element specifically */
+        if (actionType === 'increment' || actionType === 'decrement') {
+            const counter = node.querySelector('[class*="value"], [class*="counter"], [class*="current"]');
+            if (counter) {
+                counter.classList.add(cssClass);
+                setTimeout(() => counter.classList.remove(cssClass), duration);
+            }
+        }
+        /* For delete animations, don't remove the class — the element will be
+         * removed from DOM after the animation. Removing it early causes the item
+         * to briefly reappear between animation end and DOM removal. */
+        if (actionType === 'delete')
+            return;
+        /* Remove class after animation completes */
+        const handleAnimationEnd = () => {
+            node.classList.remove(cssClass);
+            animatingElements.delete(node);
+            node.removeEventListener('animationend', handleAnimationEnd);
+        };
+        node.addEventListener('animationend', handleAnimationEnd);
+        /* Fallback removal in case animationend doesn't fire
+         * (e.g., element is display:none or animation is interrupted) */
+        setTimeout(() => {
+            node.classList.remove(cssClass);
+            animatingElements.delete(node);
+        }, duration + 100);
+    }
+    // ---------------------------------------------------------------------------
+    //            INITIAL CHECK (HANDLES CREATE-ON-MOUNT SCENARIO)
+    // ---------------------------------------------------------------------------
+    /* Check for a recent change immediately on mount. This handles the case
+     * where the element mounts after a remote INSERT — the store already has
+     * the change recorded, and we need to animate the newly-rendered item. */
+    const initialChange = remoteChangesStore.getRecentChange(entityId, entityType);
+    if (initialChange) {
+        /* Use requestAnimationFrame to ensure DOM is fully ready */
+        requestAnimationFrame(() => {
+            applyAnimation(initialChange);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    //                   STORE SUBSCRIPTIONS
+    // ---------------------------------------------------------------------------
+    /* Create derived stores to watch for future changes and pending deletes */
+    let changeIndicator = createRecentChangeIndicator(entityId, entityType);
+    let deleteIndicator = createPendingDeleteIndicator(entityId, entityType);
+    /* Track the current unsubscribe functions */
+    let unsubscribeChange = changeIndicator.subscribe((change) => {
+        /* Skip if no change or if this is the same change we already animated on mount */
+        if (!change)
+            return;
+        if (initialChange && change.timestamp === initialChange.timestamp)
+            return;
+        applyAnimation(change);
+    });
+    /* Watch for pending deletes to apply delete animation */
+    let unsubscribeDelete = deleteIndicator.subscribe((isPendingDelete) => {
+        if (isPendingDelete) {
+            /* Apply delete animation immediately */
+            const deleteClass = ACTION_ANIMATION_MAP['delete'];
+            node.classList.add(deleteClass);
+            /* Call action callback if provided */
+            if (onAction) {
+                onAction('delete', ['*']);
+            }
+        }
+    });
+    // ---------------------------------------------------------------------------
+    //                 SVELTE ACTION LIFECYCLE
+    // ---------------------------------------------------------------------------
+    return {
+        /**
+         * Called when the action's options change. If the entity identity
+         * (`entityId` or `entityType`) has changed, tears down old subscriptions
+         * and creates new ones for the updated entity.
+         *
+         * @param newOptions - The updated {@link RemoteChangeOptions}.
+         */
+        update(newOptions) {
+            /* If entity changed, re-subscribe with new entity */
+            if (newOptions.entityId !== entityId || newOptions.entityType !== entityType) {
+                unsubscribeChange();
+                unsubscribeDelete();
+                entityId = newOptions.entityId;
+                entityType = newOptions.entityType;
+                fields = newOptions.fields;
+                animationClass = newOptions.animationClass;
+                onAction = newOptions.onAction;
+                changeIndicator = createRecentChangeIndicator(entityId, entityType);
+                deleteIndicator = createPendingDeleteIndicator(entityId, entityType);
+                unsubscribeChange = changeIndicator.subscribe((change) => {
+                    if (!change)
+                        return;
+                    applyAnimation(change);
+                });
+                unsubscribeDelete = deleteIndicator.subscribe((isPendingDelete) => {
+                    if (isPendingDelete) {
+                        const deleteClass = ACTION_ANIMATION_MAP['delete'];
+                        node.classList.add(deleteClass);
+                        if (onAction) {
+                            onAction('delete', ['*']);
+                        }
+                    }
+                });
+            }
+        },
+        /**
+         * Cleanup handler — unsubscribes from all stores, removes the base
+         * CSS class, and clears the element from the animation tracking set.
+         */
+        destroy() {
+            unsubscribeChange();
+            unsubscribeDelete();
+            node.classList.remove('syncable-item');
+            animatingElements.delete(node);
+        }
+    };
+}
+/**
+ * Svelte action that marks an entity as "being edited" in the remote changes
+ * store. While editing, incoming remote changes for the same entity are
+ * deferred instead of applied immediately.
+ *
+ * **Lifecycle:**
+ *   1. On mount, calls `remoteChangesStore.startEditing()` to begin deferral.
+ *   2. Periodically checks for deferred changes and toggles a CSS class
+ *      (`has-deferred-changes`) on the node for visual indication.
+ *   3. On update, re-registers if the entity identity changes.
+ *   4. On destroy, calls `remoteChangesStore.stopEditing()` and invokes
+ *      `onDeferredChanges` if any changes were deferred.
+ *
+ * @param node - The form DOM element.
+ * @param options - Configuration specifying which entity is being edited.
+ * @returns A Svelte action lifecycle object with `update` and `destroy` methods.
+ */
+export function trackEditing(node, options) {
+    const { entityId, entityType, formType, fields, onDeferredChanges } = options;
+    /* Start tracking when the element mounts */
+    remoteChangesStore.startEditing(entityId, entityType, formType, fields);
+    /**
+     * Update the `has-deferred-changes` CSS class based on whether
+     * remote changes have been deferred for this entity.
+     */
+    const updateDeferredIndicator = () => {
+        const hasDeferred = remoteChangesStore.hasDeferredChanges(entityId, entityType);
+        if (hasDeferred) {
+            node.classList.add('has-deferred-changes');
+        }
+        else {
+            node.classList.remove('has-deferred-changes');
+        }
+    };
+    /* Check periodically for deferred changes (1-second polling interval) */
+    const interval = setInterval(updateDeferredIndicator, 1000);
+    updateDeferredIndicator();
+    return {
+        /**
+         * Called when the action's options change. If the entity identity
+         * changes, stops tracking the old entity and starts tracking the new one.
+         *
+         * @param newOptions - The updated {@link TrackEditingOptions}.
+         */
+        update(newOptions) {
+            /* If entity changed, stop old tracking and start new */
+            if (newOptions.entityId !== entityId || newOptions.entityType !== entityType) {
+                remoteChangesStore.stopEditing(entityId, entityType);
+                remoteChangesStore.startEditing(newOptions.entityId, newOptions.entityType, newOptions.formType, newOptions.fields);
+            }
+        },
+        /**
+         * Cleanup handler — stops the polling interval, removes CSS classes,
+         * stops editing in the store, and notifies the callback of any
+         * deferred changes that accumulated during the editing session.
+         */
+        destroy() {
+            clearInterval(interval);
+            node.classList.remove('has-deferred-changes');
+            /* Stop tracking and get any deferred changes */
+            const deferredChanges = remoteChangesStore.stopEditing(entityId, entityType);
+            /* Notify callback if there are deferred changes */
+            if (deferredChanges.length > 0 && onDeferredChanges) {
+                onDeferredChanges(deferredChanges);
+            }
+        }
+    };
+}
+// =============================================================================
+//             PROGRAMMATIC LOCAL ANIMATION TRIGGER
+// =============================================================================
+/**
+ * Trigger a local action animation on an element.
+ *
+ * Use this to make local user actions (e.g., tapping a checkbox, incrementing
+ * a counter) animate with the same visual treatment as remote changes, giving
+ * the UI a consistent feel.
+ *
+ * For `increment` and `decrement` actions, rapid repeated invocations will
+ * restart the animation instead of being blocked — this allows the counter
+ * to visually "bump" on each tap.
+ *
+ * @param element - The DOM element to animate (or `null`, in which case this is a no-op).
+ * @param actionType - The type of animation to apply.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { triggerLocalAnimation } from 'stellar-drive';
+ *   let element: HTMLElement;
+ *
+ *   function handleToggle() {
+ *     triggerLocalAnimation(element, 'toggle');
+ *     onToggle?.();
+ *   }
+ * </script>
+ * <div bind:this={element}>...</div>
+ * ```
+ */
+export function triggerLocalAnimation(element, actionType) {
+    if (!element)
+        return;
+    const cssClass = ACTION_ANIMATION_MAP[actionType] || 'item-changed';
+    const duration = ACTION_DURATION_MAP[actionType] || 1600;
+    /* For increment/decrement, restart animation on rapid taps instead of blocking */
+    if (actionType === 'increment' || actionType === 'decrement') {
+        if (animatingElements.has(element)) {
+            /* Force restart: remove class, trigger reflow via offsetWidth read, re-add */
+            element.classList.remove(cssClass);
+            void element.offsetWidth;
+        }
+    }
+    else {
+        /* Prevent overlapping animations for other types */
+        if (animatingElements.has(element))
+            return;
+    }
+    animatingElements.add(element);
+    /* Apply animation class */
+    element.classList.add(cssClass);
+    /* For toggle actions, also animate checkbox elements */
+    if (actionType === 'toggle') {
+        const checkbox = element.querySelector('.checkbox, [class*="checkbox"]');
+        if (checkbox) {
+            checkbox.classList.add('checkbox-animating');
+            setTimeout(() => checkbox.classList.remove('checkbox-animating'), 500);
+        }
+        /* Add completion ripple effect */
+        const ripple = document.createElement('span');
+        ripple.className = 'completion-ripple';
+        element.appendChild(ripple);
+        setTimeout(() => ripple.remove(), 700);
+    }
+    /* For increment/decrement, animate the counter sub-element specifically */
+    if (actionType === 'increment' || actionType === 'decrement') {
+        const counter = element.querySelector('[class*="value"], [class*="counter"], [class*="current"]');
+        if (counter) {
+            counter.classList.add(cssClass);
+            setTimeout(() => counter.classList.remove(cssClass), duration);
+        }
+    }
+    /* Remove class after animation completes */
+    const handleAnimationEnd = () => {
+        element.classList.remove(cssClass);
+        animatingElements.delete(element);
+        element.removeEventListener('animationend', handleAnimationEnd);
+    };
+    element.addEventListener('animationend', handleAnimationEnd);
+    /* Fallback removal in case animationend doesn't fire */
+    setTimeout(() => {
+        element.classList.remove(cssClass);
+        animatingElements.delete(element);
+    }, duration + 100);
+}
+//# sourceMappingURL=remoteChange.js.map

package/dist/actions/remoteChange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteChange.js","sourceRoot":"","sources":["../../src/actions/remoteChange.ts"],"names":[],"mappings":"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"}