@nascentdigital/funnel-ui 4.4.18

package/dist/client/hooks/ui-lock/useUILock.d.ts

@@ -0,0 +1,16 @@
+import { Subject } from 'rxjs';
+import { UILockRef } from './UILockRef';
+export declare function useUILock(element?: HTMLElement | null | undefined): UILock;
+export declare class UILock {
+    private readonly eventBus;
+    private readonly refs;
+    private readonly element;
+    constructor(eventBus: Subject<UILockRef.Event>, refs: Array<UILockRef>, element: HTMLElement | null | undefined);
+    get isLocked(): boolean;
+    get canLock(): boolean;
+    lock({ lockChildren, delegationRule }: UILock.LockArgs): void;
+    unlock(): void;
+}
+export declare namespace UILock {
+    type LockArgs = UILockRef.Config;
+}

package/dist/client/hooks/ui-lock/useUILock.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UILock = void 0;
+exports.useUILock = useUILock;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+const UILockContext_1 = require("./UILockContext");
+const UILockRef_1 = require("./UILockRef");
+// hook
+function useUILock(element) {
+    // state
+    const { eventBus, refs } = (0, react_1.useContext)(UILockContext_1.UILockContext);
+    // return
+    return (0, react_1.useMemo)(() => {
+        return new UILock(eventBus, refs, element);
+    }, [eventBus, refs, element]);
+}
+// ui lock
+class UILock {
+    constructor(eventBus, refs, element) {
+        this.eventBus = eventBus;
+        this.refs = refs;
+        this.element = element;
+    }
+    get isLocked() {
+        // check if any other items are locked if client is an observer (element === undefined instead of NULL)
+        const { refs, element } = this;
+        if (element === undefined) {
+            return refs.length > 0;
+        }
+        // or skip if we don't have an element bounded yet
+        else if (element === null) {
+            return false;
+        }
+        // return if there is no lock yet
+        const lock = funnel_core_1.ArrayUtils.last(refs);
+        if (!lock) {
+            return false;
+        }
+        // return if the given element is the latest lock holder
+        else if (element === lock.lockHolder) {
+            return false;
+        }
+        // otherwise if the element is a child of the lock holder
+        else if (lock.lockHolder.contains(element)) {
+            // determine based on the lock holder's `lockChildren` config
+            return lock.config.lockChildren;
+        }
+        // otherwise the element is locked
+        else {
+            return true;
+        }
+    }
+    get canLock() {
+        // skip if we don't have an element bounded yet
+        const { refs, element } = this;
+        if (!element) {
+            return false;
+        }
+        // return if there is no lock yet
+        const lock = funnel_core_1.ArrayUtils.last(refs);
+        if (!lock) {
+            return true;
+        }
+        // return if the given element is the latest lock holder
+        else if (element === lock.lockHolder) {
+            return false;
+        }
+        // determine based on the lock holder's config
+        else {
+            switch (lock.config.delegationRule) {
+                // return false if no one can lock
+                case 'none':
+                    return false;
+                // if the element is a child of the lock holder return true otherwise false
+                case 'children':
+                    return lock.lockHolder.contains(element);
+                // otherwise everyone can lock
+                default:
+                    return true;
+            }
+        }
+    }
+    lock({ lockChildren, delegationRule }) {
+        // throw if we don't have an element bounded yet
+        if (!this.element) {
+            throw new funnel_core_1.InvalidOperationError(`Cannot lock unless an element is provided`);
+        }
+        // throw if element is not allowed to lock
+        else if (!this.canLock) {
+            throw new funnel_core_1.InvalidOperationError(`${this.element} is not allowed to lock the UI`);
+        }
+        // create and send a lock event
+        this.eventBus.next(UILockRef_1.UILockRef.Event.create({
+            action: 'lock',
+            lock: {
+                lockHolder: this.element,
+                config: {
+                    lockChildren,
+                    delegationRule
+                }
+            }
+        }));
+    }
+    unlock() {
+        // throw if we don't have an element bounded yet
+        if (!this.element) {
+            throw new funnel_core_1.InvalidOperationError(`Cannot unlock unless an element is provided`);
+        }
+        // throw if the element hasn't requested a lock before
+        else if (!this.refs.some(({ lockHolder }) => this.element === lockHolder)) {
+            throw new funnel_core_1.InvalidOperationError(`Attempt to unlock without issuing a lock by element ${this.element}`);
+        }
+        // create and send an unlock event
+        this.eventBus.next(UILockRef_1.UILockRef.Event.create({
+            action: 'unlock',
+            lockHolder: this.element
+        }));
+    }
+}
+exports.UILock = UILock;

package/dist/client/hooks/useCounter.d.ts

@@ -0,0 +1,11 @@
+export declare function useCounter(initial?: number): Counter;
+export declare class Counter {
+    private _count$;
+    constructor(count?: number);
+    get count(): number;
+    get count$(): import("rxjs").Observable<number>;
+    set(count: number): void;
+    up(): void;
+    down(): void;
+    change(delta: number): number;
+}

package/dist/client/hooks/useCounter.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Counter = void 0;
+exports.useCounter = useCounter;
+const react_1 = require("react");
+const rxjs_1 = require("rxjs");
+const useTouch_1 = require("./useTouch");
+// hook
+function useCounter(initial = 0) {
+    // memoize counter
+    const counter = (0, react_1.useMemo)(() => new Counter(initial), [initial]);
+    const touch = (0, useTouch_1.useTouch)();
+    // refresh on count changes
+    (0, react_1.useEffect)(() => {
+        // touch when counter changes
+        const subscription = counter.count$
+            .pipe((0, rxjs_1.distinctUntilChanged)())
+            .subscribe(() => touch());
+        // unsubscribe on unmount
+        return () => subscription.unsubscribe();
+    }, [counter, touch]);
+    // return counter
+    return counter;
+}
+// counter
+class Counter {
+    constructor(count = 0) {
+        // initialize instance variables
+        this._count$ = new rxjs_1.BehaviorSubject(count);
+    }
+    get count() {
+        return this._count$.getValue();
+    }
+    get count$() {
+        return this._count$.asObservable();
+    }
+    set(count) {
+        // update count
+        this._count$.next(count);
+    }
+    up() {
+        this.change(1);
+    }
+    down() {
+        this.change(-1);
+    }
+    change(delta) {
+        // determine new value
+        const { count, _count$ } = this;
+        const newCount = count + delta;
+        // update count
+        _count$.next(newCount);
+        // return it
+        return newCount;
+    }
+}
+exports.Counter = Counter;

package/dist/client/hooks/useCycle.d.ts

@@ -0,0 +1,5 @@
+export declare function useCycle<T>(options: T[]): useCycle.Hook<T>;
+export declare namespace useCycle {
+    type Hook<T> = [T, NextMethod];
+    type NextMethod = () => void;
+}

package/dist/client/hooks/useCycle.js

@@ -0,0 +1,15 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCycle = useCycle;
+const react_1 = require("react");
+// hook
+function useCycle(options) {
+    // bind state
+    const [optionIndex, setOptionIndex] = (0, react_1.useState)(0);
+    const option = options[optionIndex];
+    // next method
+    const next = () => setOptionIndex((optionIndex + 1) % options.length);
+    // return hook
+    return [option, next];
+}

package/dist/client/hooks/useElementRect.d.ts

@@ -0,0 +1,2 @@
+import { Rect } from '@nascentdigital/funnel-core';
+export declare function useElementRect(element: HTMLElement | null): Rect | undefined;

package/dist/client/hooks/useElementRect.js

@@ -0,0 +1,63 @@
+'use client';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useElementRect = useElementRect;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const useResizeObserver_1 = require("./useResizeObserver");
+const react_1 = __importStar(require("react"));
+// hook
+function useElementRect(element) {
+    // bind hooks
+    const [rect, setRect] = react_1.default.useState();
+    // bind initial size
+    (0, react_1.useLayoutEffect)(() => {
+        if (element) {
+            setRect(funnel_core_1.Rect.fromRect(element.getBoundingClientRect()));
+        }
+    }, [element]);
+    // bind resize on any additional change
+    (0, useResizeObserver_1.useResizeObserver)(element, () => {
+        // skip if there's no element
+        if (!element) {
+            setRect(new funnel_core_1.Rect(0, 0, 0, 0));
+            return;
+        }
+        // or use client rect
+        setRect(funnel_core_1.Rect.fromRect(element.getBoundingClientRect()));
+    });
+    // return size changes
+    return rect;
+}

package/dist/client/hooks/useElementScrolled.d.ts

@@ -0,0 +1,17 @@
+import { RefObject } from 'react';
+export declare function useElementScrolled<TElement extends HTMLElement = HTMLElement>(container: RefObject<TElement | null> | undefined, { direction }?: useElementScrolled.Options): useElementScrolled.Result;
+export declare namespace useElementScrolled {
+    type Options = {
+        direction?: ScrollDirection;
+    };
+    type Result = {
+        scrollX?: ScrollState;
+        scrollY?: ScrollState;
+    };
+    type ScrollDirection = 'x' | 'y' | 'xy';
+    type ScrollPosition = 'start' | 'between' | 'end';
+    type ScrollState = {
+        position: ScrollPosition;
+        offset: number;
+    };
+}

package/dist/client/hooks/useElementScrolled.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useElementScrolled = useElementScrolled;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("motion/react");
+const react_2 = require("react");
+// component
+function useElementScrolled(container, { direction = 'y' } = {}) {
+    // bind hooks + props
+    const [scrollX, setScrollX] = (0, react_2.useState)();
+    const [scrollY, setScrollY] = (0, react_2.useState)();
+    const { scrollXProgress, scrollYProgress } = (0, react_1.useScroll)({ container });
+    // x-scroll
+    (0, react_1.useMotionValueEvent)(scrollXProgress, "change", direction === 'x'
+        ? offset => setScrollX({
+            position: getPosition(container, offset),
+            offset
+        })
+        : funnel_core_1.Fn.Identity);
+    // y-scroll
+    (0, react_1.useMotionValueEvent)(scrollYProgress, "change", direction === 'y'
+        ? offset => setScrollY({
+            position: getPosition(container, offset),
+            offset,
+        })
+        : funnel_core_1.Fn.Identity);
+    // return scrolled
+    return {
+        scrollX,
+        scrollY
+    };
+}
+// helpers
+function getPosition(containerRef, offset) {
+    var _a;
+    // handle top
+    if (offset === 0) {
+        return 'start';
+    }
+    // handle bottom (might be top if it can't scroll)
+    else if (offset === 1) {
+        // determine if scrolled at all
+        return ((_a = containerRef === null || containerRef === void 0 ? void 0 : containerRef.current) === null || _a === void 0 ? void 0 : _a.scrollTop) === 0
+            ? 'start'
+            : 'end';
+    }
+    // or in between
+    else {
+        return 'between';
+    }
+}

package/dist/client/hooks/useElementSelector.d.ts

@@ -0,0 +1,2 @@
+import { RefObject } from 'react';
+export declare function useElementSelector<TElement extends HTMLElement = HTMLElement>(selectorOrRef: string | RefObject<TElement | null> | undefined): RefObject<TElement | null>;

package/dist/client/hooks/useElementSelector.js

@@ -0,0 +1,160 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useElementSelector = useElementSelector;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+// hook
+function useElementSelector(selectorOrRef) {
+    // bind hooks
+    const [, setUpdatedAt] = (0, react_1.useState)(0);
+    const observer = SharedElementObserver.instance;
+    const selector = typeof selectorOrRef === 'string'
+        ? selectorOrRef
+        : undefined;
+    const elementRef = (0, react_1.useRef)(selector && typeof window !== 'undefined'
+        ? document.querySelector(selector)
+        : null);
+    // monitor for element changes
+    (0, react_1.useLayoutEffect)(() => {
+        // skip if selector isn't defined
+        if (!selector) {
+            return;
+        }
+        // bind selector
+        observer.subscribe(selector, elementRef);
+        // mark updated
+        setUpdatedAt(Date.now());
+        // unbind on unmount
+        return () => observer.unsubscribe(selector, elementRef);
+    }, [observer, selector]);
+    // return element
+    return typeof selectorOrRef === 'string'
+        ? elementRef
+        : selectorOrRef !== null && selectorOrRef !== void 0 ? selectorOrRef : elementRef;
+}
+// helper
+class SharedElementObserver {
+    static get instance() {
+        // create if required
+        if (!SharedElementObserver._instance) {
+            SharedElementObserver._instance = new SharedElementObserver();
+        }
+        // throw if we don't have the instance
+        const instance = SharedElementObserver._instance;
+        if (!instance) {
+            throw new funnel_core_1.IllegalStateError('Unable to instantiate SharedElementObserver');
+        }
+        // return instance
+        return instance;
+    }
+    constructor() {
+        // bind callback
+        this.onMutate = this.onMutate.bind(this);
+        // initialize instance
+        this._observer = typeof window === 'undefined'
+            ? undefined
+            : new MutationObserver(this.onMutate);
+        this._selectorRefs = new Map();
+        this._liveSelectors = new Set();
+    }
+    subscribe(selector, ref) {
+        // skip if there's no observer
+        const { _observer, _selectorRefs, _liveSelectors } = this;
+        if (!_observer) {
+            return;
+        }
+        // start observing if there are no active callbacks
+        if (_selectorRefs.size === 0) {
+            _observer.observe(document, { attributes: false, childList: true, subtree: true });
+        }
+        // get refs (or create it)
+        let refs = _selectorRefs.get(selector);
+        if (!refs) {
+            refs = [];
+            _selectorRefs.set(selector, refs);
+        }
+        // add ref to list
+        refs.push(ref);
+        // sync element refs
+        const element = document.querySelector(selector);
+        refs.forEach(ref => ref.current = element);
+        // sync live tracker
+        if (element) {
+            _liveSelectors.add(selector);
+        }
+        else {
+            _liveSelectors.delete(selector);
+        }
+    }
+    unsubscribe(selector, ref) {
+        // skip if there's no observer
+        const { _observer, _selectorRefs, _liveSelectors } = this;
+        if (!_observer) {
+            return;
+        }
+        // skip if it's not bound
+        const refs = _selectorRefs.get(selector);
+        if (!refs) {
+            return;
+        }
+        // or remove list if it's the last one
+        else if (refs.length === 1) {
+            // prune entry
+            _selectorRefs.delete(selector);
+            _liveSelectors.delete(selector);
+            // stop observer if there are no more entries
+            if (_selectorRefs.size === 0) {
+                _observer.disconnect();
+            }
+        }
+        // or just remove one
+        else {
+            // find index of callback (remove it found
+            const refIndex = refs.indexOf(ref);
+            if (refIndex >= 0) {
+                refs.splice(refIndex, 1);
+            }
+        }
+    }
+    onMutate(mutations) {
+        // look for removed matches
+        const { _selectorRefs, _liveSelectors } = this;
+        const liveSelectors = Array.from(_liveSelectors);
+        if (liveSelectors.length > 0) {
+            // check all live selectors
+            liveSelectors.forEach(selector => {
+                // skip if there's no refs
+                const refs = _selectorRefs.get(selector);
+                if (!refs || refs.length === 0) {
+                    return;
+                }
+                // clear element if it's missing or if the node was in the removed set
+                const element = refs[0].current;
+                if (!element || mutations.flatMap(mutation => Array.from(mutation.removedNodes)).includes(element)) {
+                    // clear refs
+                    refs.forEach(ref => ref.current = null);
+                    // remove from live selectors
+                    _liveSelectors.delete(selector);
+                }
+            });
+        }
+        // sync any refs that aren't live (only if there were added refs)
+        const deadSelectors = Array.from(_selectorRefs.keys())
+            .filter(selector => !liveSelectors.includes(selector));
+        if (deadSelectors.length > 0
+            && mutations.flatMap(mutation => Array.from(mutation.addedNodes)).length > 0) {
+            deadSelectors.forEach(selector => {
+                var _a;
+                const element = document.querySelector(selector);
+                if (element) {
+                    // update refs
+                    const refs = (_a = _selectorRefs.get(selector)) !== null && _a !== void 0 ? _a : [];
+                    refs.forEach(ref => ref.current = element);
+                    // update live selectors
+                    _liveSelectors.add(selector);
+                }
+            });
+        }
+    }
+}

package/dist/client/hooks/useElementSize.d.ts

@@ -0,0 +1,2 @@
+import { Size } from '@nascentdigital/funnel-core';
+export declare function useElementSize(element: HTMLElement | null): Size | undefined;

package/dist/client/hooks/useElementSize.js

@@ -0,0 +1,64 @@
+'use client';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useElementSize = useElementSize;
+const useResizeObserver_1 = require("./useResizeObserver");
+const react_1 = __importStar(require("react"));
+// hook
+function useElementSize(element) {
+    // bind hooks
+    const [size, setSize] = react_1.default.useState();
+    // bind initial size
+    (0, react_1.useLayoutEffect)(() => {
+        if (element) {
+            const { width, height } = element.getBoundingClientRect();
+            setSize({ width, height });
+        }
+    }, [element]);
+    // bind resize on any additional change
+    (0, useResizeObserver_1.useResizeObserver)(element, () => {
+        // skip if there's no element
+        if (!element) {
+            setSize({ width: 0, height: 0 });
+            return;
+        }
+        // or use client rect
+        const clientRect = element.getBoundingClientRect();
+        setSize({ width: clientRect.width, height: clientRect.height });
+    });
+    // return size changes
+    return size;
+}

package/dist/client/hooks/useFindElements.d.ts

@@ -0,0 +1,9 @@
+import { Tagged } from 'type-fest';
+export declare function useFindElements<TElement extends HTMLElement = HTMLElement>(selector: string): useFindElements.Match<TElement>[];
+export declare namespace useFindElements {
+    type ElementIdentifier = Tagged<string, 'useFindElements.ElementIdentifier'>;
+    type Match<TElement extends HTMLElement = HTMLElement> = {
+        id: ElementIdentifier;
+        element: TElement;
+    };
+}