@nascentdigital/funnel-ui 4.4.18

package/dist/client/hooks/useFindElements.js

@@ -0,0 +1,147 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFindElements = useFindElements;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+// hook
+function useFindElements(selector) {
+    // bind state + hooks
+    const [matches, setMatches] = (0, react_1.useState)([]);
+    const observer = SharedElementsObserver.instance;
+    // monitor for element changes
+    (0, react_1.useLayoutEffect)(() => {
+        // bind selector (and return unsubscribe)
+        return observer.subscribe(selector, elements => setMatches(elements.slice()));
+    }, [observer, selector]);
+    // return element
+    return matches;
+}
+class SharedElementsObserver {
+    static get instance() {
+        // create if required
+        if (!SharedElementsObserver._instance) {
+            SharedElementsObserver._instance = new SharedElementsObserver();
+        }
+        // throw if we don't have the instance
+        const instance = SharedElementsObserver._instance;
+        if (!instance) {
+            throw new funnel_core_1.IllegalStateError('Unable to instantiate SharedElementsObserver');
+        }
+        // return instance
+        return instance;
+    }
+    constructor() {
+        // initialize instance
+        this._observations = new Map();
+        this._observer = typeof window === 'undefined'
+            ? undefined
+            : new MutationObserver(mutations => this.onMutate(mutations));
+    }
+    subscribe(selector, onChange) {
+        // skip if there's no observer
+        const { _observer, _observations } = this;
+        if (!_observer) {
+            console.warn('[useFindElements/subscribe] attempt to subscribe before observer');
+            return funnel_core_1.Fn.NoOp;
+        }
+        // start observing if there are no active callbacks
+        if (_observations.size === 0) {
+            _observer.observe(document, { attributes: false, childList: true, subtree: true });
+        }
+        // get observation (or create it)
+        let observationGroup = _observations.get(selector);
+        if (!observationGroup) {
+            observationGroup = {
+                selector,
+                matches: document.querySelectorAll(selector).values().toArray().map(element => ({
+                    id: funnel_core_1.Value.uuid(),
+                    element: element
+                })),
+                subscribers: []
+            };
+            _observations.set(selector, observationGroup);
+        }
+        // add subscriber to list
+        const { matches, subscribers } = observationGroup;
+        const subscriber = {
+            id: funnel_core_1.Value.uuid(),
+            onChange
+        };
+        subscribers.push(subscriber);
+        // perform immediate callback
+        subscriber.onChange(matches);
+        // return unsubscribe
+        return () => this.unsubscribe(selector, subscriber.id);
+    }
+    unsubscribe(selector, subscriberId) {
+        // skip if there's no observer
+        const { _observer, _observations } = this;
+        if (!_observer) {
+            console.warn('[useFindElements/unsubscribe] cannot unsubscribe before init', selector);
+            return;
+        }
+        // skip if it's not bound
+        const observationGroup = _observations.get(selector);
+        if (!observationGroup) {
+            console.warn('[useFindElements/unsubscribe] ignoring unbound subscribers:', selector);
+            return;
+        }
+        // or remove list if it's the last one
+        const { subscribers } = observationGroup;
+        if (subscribers.length === 1) {
+            // prune entry
+            _observations.delete(selector);
+            // stop observer if there are no more entries
+            if (_observations.size === 0) {
+                _observer.disconnect();
+            }
+        }
+        // or just remove it
+        else {
+            observationGroup.subscribers = subscribers.filter(subscriber => subscriber.id !== subscriberId);
+        }
+    }
+    onMutate(mutations) {
+        // look for removed matches
+        const removedElements = mutations.flatMap(mutation => Array.from(mutation.removedNodes));
+        const observationGroups = this._observations.values().toArray();
+        if (removedElements.length > 0) {
+            observationGroups.forEach(observationGroup => {
+                // skip if there are no elements to prune
+                const { matches, subscribers } = observationGroup;
+                if (matches.length === 0) {
+                    return;
+                }
+                // clear any removed nodes
+                const prunedMatches = matches.filter(({ element }) => !removedElements.some(removedElement => removedElement === element || removedElement.contains(element)));
+                if (prunedMatches.length < matches.length) {
+                    // update elements list
+                    observationGroup.matches = prunedMatches;
+                    // raise change
+                    subscribers.forEach(subscriber => subscriber.onChange(prunedMatches));
+                }
+            });
+        }
+        // look for added nodes
+        const addedElements = mutations.flatMap(mutation => Array.from(mutation.addedNodes));
+        if (addedElements.length > 0) {
+            observationGroups.forEach(({ selector, matches, subscribers }) => {
+                // find any matching elements
+                const newElements = addedElements
+                    .flatMap(addedElement => addedElement.querySelectorAll(selector).values().toArray())
+                    .filter(newElement => !matches.some(({ element }) => element === newElement));
+                // add new elements (if any)
+                if (newElements.length > 0) {
+                    // track new elements
+                    matches.push(...newElements.map(element => ({
+                        id: funnel_core_1.Value.uuid(),
+                        element
+                    })));
+                    // notify subscribers
+                    subscribers.forEach(subscriber => subscriber.onChange(matches));
+                }
+            });
+        }
+    }
+}

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

@@ -0,0 +1,16 @@
+import { UseInViewOptions } from 'motion/react';
+import { RefObject } from 'react';
+export declare function useInViewport({ scrollerRef, targetRef, targetId, once, threshold, padding }: useInViewport.Options): (boolean | undefined)[];
+export declare namespace useInViewport {
+    type Options = {
+        scrollerRef?: RefObject<HTMLElement | null>;
+        targetRef: RefObject<HTMLElement | null>;
+        targetId: string;
+        once?: boolean;
+        threshold?: Threshold;
+        padding?: Padding;
+    };
+    type Threshold = UseInViewOptions['amount'];
+    type PaddingValue = `${number}${'px' | '%'}`;
+    type Padding = `${PaddingValue}` | `${PaddingValue} ${PaddingValue}` | `${PaddingValue} ${PaddingValue} ${PaddingValue} ${PaddingValue}`;
+}

package/dist/client/hooks/useInViewport.js

@@ -0,0 +1,46 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useInViewport = useInViewport;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("motion/react");
+const react_2 = require("react");
+// hook
+function useInViewport({ scrollerRef, targetRef, targetId, once, threshold, padding }) {
+    // bind refs + hooks
+    const [initial, setInitial] = (0, react_2.useState)(true);
+    const [inViewport, setInViewport] = (0, react_2.useState)();
+    const initializedRef = (0, react_2.useRef)(false);
+    const visible = (0, react_1.useInView)(targetRef, {
+        root: scrollerRef,
+        once,
+        amount: threshold,
+        margin: padding
+    });
+    // animate on entry
+    (0, react_2.useLayoutEffect)(() => {
+        // skip if not bound
+        const element = document.getElementById(targetId);
+        if (!element) {
+            return;
+        }
+        // use DOM to calculate for initial render (avoids false negatives)
+        if (!initializedRef.current) {
+            // mark as initialized
+            initializedRef.current = true;
+            // check client is in viewport
+            const elementRect = funnel_core_1.Rect.fromRect(element.getBoundingClientRect());
+            const viewportRect = new funnel_core_1.Rect(0, 0, window.innerWidth || document.documentElement.clientWidth, window.innerHeight || document.documentElement.clientHeight);
+            const intersectsViewport = viewportRect.overlaps(elementRect);
+            // update state
+            setInViewport(intersectsViewport);
+        }
+        // or just update based on visibility
+        else {
+            setInViewport(visible);
+            setInitial(false);
+        }
+    }, [targetId, visible]);
+    // return visibility
+    return [inViewport, initial];
+}

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

@@ -0,0 +1 @@
+export declare function useIsDesktop(): boolean | undefined;

package/dist/client/hooks/useIsDesktop.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useIsDesktop = useIsDesktop;
+const breakpoint_1 = require("./breakpoint");
+// hook
+function useIsDesktop() {
+    // get current breakpoint
+    const breakpoint = (0, breakpoint_1.useCurrentBreakpoint)();
+    // skip if indeterminate
+    if (!breakpoint) {
+        return undefined;
+    }
+    // otherwise, return based on breakpoint
+    switch (breakpoint) {
+        case 'md':
+        case 'lg':
+        case 'xl':
+            return true;
+        default:
+            return false;
+    }
+}

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

@@ -0,0 +1,7 @@
+export declare function useKeyboardFocus<TElement extends HTMLElement>(element?: TElement | null): useKeyboardFocus.Result;
+export declare namespace useKeyboardFocus {
+    type Result = {
+        hasKeyboardFocus?: boolean;
+        keyboardFocusElement?: HTMLElement;
+    };
+}

package/dist/client/hooks/useKeyboardFocus.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeyboardFocus = useKeyboardFocus;
+const react_1 = require("react");
+// hook
+function useKeyboardFocus(element) {
+    // create state
+    const [hasKeyboardFocus, setHasKeyboardFocus] = (0, react_1.useState)();
+    const [keyboardFocusElement, setKeyboardFocusElement] = (0, react_1.useState)();
+    // bind watcher (if ready/required)
+    (0, react_1.useEffect)(() => {
+        // ignore if no element or we're not watching
+        if (!element) {
+            return;
+        }
+        // add listeners on mount
+        const onFocusIn = (e) => {
+            var _a;
+            setHasKeyboardFocus(true);
+            setKeyboardFocusElement((_a = e.target) !== null && _a !== void 0 ? _a : undefined);
+        };
+        const onFocusOut = () => {
+            setHasKeyboardFocus(false);
+            setKeyboardFocusElement(undefined);
+        };
+        element.addEventListener('focusin', onFocusIn);
+        element.addEventListener('focusout', onFocusOut);
+        // TODO: check children for focus
+        // remove listeners on unmount
+        return () => {
+            element.removeEventListener('focusin', onFocusIn);
+            element.removeEventListener('focusout', onFocusOut);
+        };
+    }, [element]);
+    // return state and setter
+    return {
+        hasKeyboardFocus,
+        keyboardFocusElement
+    };
+}

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

@@ -0,0 +1 @@
+export declare function useLatestValue<TValue>(value: TValue): TValue;

package/dist/client/hooks/useLatestValue.js

@@ -0,0 +1,21 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLatestValue = useLatestValue;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+// hook
+function useLatestValue(value) {
+    // fetch prev value
+    const prevValueRef = (0, react_1.useRef)(value);
+    const prevValue = prevValueRef.current;
+    // return prev if it's unchanged
+    if (value === prevValue || funnel_core_1.Value.equals(value, prevValue)) {
+        return prevValue;
+    }
+    // or update and return the new value
+    else {
+        prevValueRef.current = value;
+        return value;
+    }
+}

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

@@ -0,0 +1,13 @@
+import { Tagged } from 'type-fest';
+export interface Lock {
+    readonly status: Lock.Status;
+    readonly isLocked: boolean;
+    lock(): Promise<void>;
+    unlock(): void;
+}
+export declare namespace Lock {
+    type Id = Tagged<string, 'Lock.Id'>;
+    function Id(value: string): Id;
+    type Status = 'unlocked' | 'locked' | 'waiting' | 'disposed';
+}
+export declare function useLock(id: Lock.Id): Lock;

package/dist/client/hooks/useLock.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lock = void 0;
+exports.useLock = useLock;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+var Lock;
+(function (Lock) {
+    function Id(value) {
+        return value;
+    }
+    Lock.Id = Id;
+})(Lock || (exports.Lock = Lock = {}));
+// hook
+function useLock(id) {
+    // obtain lock
+    const lock = (0, react_1.useMemo)(() => LockCoordinator.resolve(id).obtainLock(), [id]);
+    // release lock on unmount (might clear context)
+    (0, react_1.useEffect)(() => {
+        return () => LockCoordinator.resolve(id).releaseLock(lock);
+    }, [id, lock]);
+    // return lock
+    return lock;
+}
+class LockCoordinator {
+    constructor(id) {
+        this.id = id;
+        // initialize instance variables
+        this._locks = new Set();
+        this._lockDeferrals = [];
+    }
+    obtainLock() {
+        // create new lock
+        const lock = new LockImpl(this);
+        // bind it
+        const { id, _locks } = this;
+        _locks.add(lock);
+        console.debug(`[LockCoordinator/${id}/obtainLock] creating new lock:`, lock);
+        // return it
+        return lock;
+    }
+    releaseLock(lock) {
+        // remove it from the queue (if any)
+        const { id, _locks, _lockDeferrals } = this;
+        const queueIndex = _lockDeferrals.findIndex(lockDeferral => lockDeferral.lock === lock);
+        if (queueIndex >= 0) {
+            console.debug(`[LockCoordinator/${id}/releaseLock] removing lock from deferrals:`, lock);
+            _lockDeferrals.splice(queueIndex, 1);
+        }
+        // remove it from the lock set
+        _locks.delete(lock);
+        console.debug(`[LockCoordinator/${id}/releaseLock] releasing old lock:`, lock);
+        // destroy context if it's empty
+        if (_locks.size === 0) {
+            console.debug(`[LockCoordinator/${id}/releaseLock] destroying empty context`);
+            LockCoordinator._coordinators.delete(id);
+        }
+    }
+    getLockStatus(lock) {
+        // disposed if it's not bound
+        if (!this._locks.has(lock)) {
+            return 'disposed';
+        }
+        // locked if active
+        else if (this._activeLock === lock) {
+            return 'locked';
+        }
+        // waiting if queued
+        else if (this._lockDeferrals.some(lockDeferral => lockDeferral.lock === lock)) {
+            return 'waiting';
+        }
+        // otherwise, unlocked
+        else {
+            return 'unlocked';
+        }
+    }
+    activateLock(lock) {
+        // throw if attempting to activate disposed lock
+        const { _locks, _lockDeferrals, _activeLock } = this;
+        if (!_locks.has(lock)) {
+            throw new funnel_core_1.InvalidOperationError('Attempt to lock disposed Lock instance');
+        }
+        // return immediately if there's no active lock (OR this lock is already it)
+        else if (!_activeLock || _activeLock === lock) {
+            // make lock active
+            this._activeLock = lock;
+            // return undefined (indicates there's no deferral)
+            return undefined;
+        }
+        // find deferral (or queue a new one)
+        let lockDeferral = _lockDeferrals.find(lockDeferral => lockDeferral.lock === lock);
+        if (!lockDeferral) {
+            // create deferral
+            lockDeferral = {
+                lock,
+                deferral: new funnel_core_1.Deferral()
+            };
+            // queue it
+            _lockDeferrals.push(lockDeferral);
+        }
+        // return deferral
+        return lockDeferral.deferral;
+    }
+    deactivateLock(lock) {
+        // throw if not active
+        const { _activeLock, _lockDeferrals } = this;
+        if (_activeLock !== lock) {
+            throw new funnel_core_1.InvalidOperationError('Attempt to unlock Lock that is not active');
+        }
+        // activate next deferred lock
+        else if (_lockDeferrals.length > 0) {
+            // remove deferral
+            const [lockDeferral] = _lockDeferrals.splice(0, 1);
+            // move lock to active
+            this._activeLock = lockDeferral.lock;
+            // resolve deferral
+            lockDeferral.deferral.resolve();
+        }
+        // otherwise, just clear active lock
+        else {
+            delete this._activeLock;
+        }
+    }
+    static resolve(id) {
+        // get context (or create one)
+        const { _coordinators } = this;
+        let lockContext = _coordinators.get(id);
+        if (!lockContext) {
+            console.debug(`[LockCoordinator/${id}/releaseLock] creating new context`);
+            lockContext = new LockCoordinator(id);
+            _coordinators.set(id, lockContext);
+        }
+        // return context
+        return lockContext;
+    }
+}
+LockCoordinator._coordinators = new Map();
+// lock
+class LockImpl {
+    constructor(_context) {
+        this._context = _context;
+    }
+    get isLocked() {
+        return this.status === 'locked';
+    }
+    get status() {
+        return this._context.getLockStatus(this);
+    }
+    async lock() {
+        // try to activate
+        const deferral = this._context.activateLock(this);
+        // await if there's a deferral
+        if (deferral) {
+            await deferral.promise;
+        }
+        // now we're locked
+    }
+    unlock() {
+        this._context.deactivateLock(this);
+    }
+}

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

@@ -0,0 +1,2 @@
+import { MixedResponsiveValue } from '@nascentdigital/funnel-core';
+export declare function useMixedResponsiveValue<T>(value: MixedResponsiveValue<T>): T | undefined;

package/dist/client/hooks/useMixedResponsiveValue.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMixedResponsiveValue = useMixedResponsiveValue;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const breakpoint_1 = require("./breakpoint");
+// hook
+function useMixedResponsiveValue(value) {
+    // get current breakpoint
+    const breakpoint = (0, breakpoint_1.useCurrentBreakpoint)();
+    // if value is not a responsive value, just return raw value
+    if (!funnel_core_1.ResponsiveValue.isResponsive(value)) {
+        return value;
+    }
+    // exit it if no current breakpoint
+    if (!breakpoint) {
+        return undefined;
+    }
+    // resolve value for current breakpoint
+    return funnel_core_1.ResponsiveValue.resolve(value, breakpoint);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Next.js `usePath()` wrapper to avoid mismatch with rewrites.
+ *
+ * This is to be used as a workaround for hydration errors when the pathname on the server does not match what is
+ * on the client.
+ *
+ * Source: https://nextjs.org/docs/app/api-reference/functions/use-pathname#avoid-hydration-mismatch-with-rewrites
+ */
+export declare function usePathname(): string;

package/dist/client/hooks/usePathname.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePathname = usePathname;
+const navigation_1 = require("next/navigation");
+const react_1 = require("react");
+/**
+ * Next.js `usePath()` wrapper to avoid mismatch with rewrites.
+ *
+ * This is to be used as a workaround for hydration errors when the pathname on the server does not match what is
+ * on the client.
+ *
+ * Source: https://nextjs.org/docs/app/api-reference/functions/use-pathname#avoid-hydration-mismatch-with-rewrites
+ */
+function usePathname() {
+    // get pathname from Next.js
+    const pathname = (0, navigation_1.usePathname)();
+    // state holds the browser pathname (defaults to '#' while its getting ready)
+    const [clientPathname, setClientPathname] = (0, react_1.useState)('#');
+    // update path name to be the pathname found in browser
+    (0, react_1.useEffect)(() => {
+        setClientPathname(pathname);
+    }, [pathname]);
+    // return the client pathname that is found in browser
+    return clientPathname;
+}

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

@@ -0,0 +1,8 @@
+import { Callback } from '@nascentdigital/funnel-core';
+import { SharedMutationObserver } from '../utils';
+export declare function useRefElement<TElement extends HTMLElement = HTMLElement>({ watch }?: useRefElement.Options): [Callback<TElement | null>, TElement | null];
+export declare namespace useRefElement {
+    type Options = {
+        watch?: SharedMutationObserver.Scope | SharedMutationObserver.Scope[];
+    };
+}

package/dist/client/hooks/useRefElement.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRefElement = useRefElement;
+const react_1 = require("react");
+const utils_1 = require("../utils");
+// hook
+function useRefElement({ watch = 'children' } = {}) {
+    // create state
+    const [, setUpdatedAt] = (0, react_1.useState)(0);
+    const [element, setElement] = (0, react_1.useState)(null);
+    // create ref callback function
+    const setRef = (0, react_1.useCallback)((node) => {
+        setElement(node);
+    }, []);
+    // bind watcher (if ready/required)
+    (0, react_1.useEffect)(() => {
+        // ignore if no element or we're not watching
+        if (!element || !watch) {
+            return;
+        }
+        // watch element for changes
+        const watchScope = typeof watch === 'string'
+            ? [watch]
+            : watch.length === 0
+                ? ['children']
+                : watch;
+        const subscription = utils_1.SharedMutationObserver.instance.watch(element, watchScope)
+            .subscribe(change => setUpdatedAt(Date.now()));
+        // unsubscribe on unmount
+        return () => subscription.unsubscribe();
+    }, [element, watch]);
+    // return state and setter
+    return [setRef, element];
+}

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

@@ -0,0 +1,2 @@
+import { Duration } from '@nascentdigital/funnel-core';
+export declare function useRefresh(period: Duration): void;

package/dist/client/hooks/useRefresh.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRefresh = useRefresh;
+const funnel_core_1 = require("@nascentdigital/funnel-core");
+const react_1 = require("react");
+const rxjs_1 = require("rxjs");
+const useTouch_1 = require("./useTouch");
+// hook
+function useRefresh(period) {
+    // bind state, memoize touch, and return it
+    const touch = (0, useTouch_1.useTouch)();
+    // bind timer
+    (0, react_1.useEffect)(() => {
+        // for period to be at least 1s
+        let timeout = funnel_core_1.Duration.toMilliseconds(period);
+        if (timeout < 1000) {
+            console.warn('[useRefresh] period must be at lest 1s between refreshes - correcting');
+            timeout = 1000;
+        }
+        // setup interval
+        const subscription = (0, rxjs_1.interval)(timeout).subscribe(() => touch());
+        // destroy on unmount
+        return () => subscription.unsubscribe();
+    }, [touch, period]);
+}

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

@@ -0,0 +1,5 @@
+import * as React from 'react';
+export declare function useResizeObserver<T extends Element>(target: React.RefObject<T> | React.ForwardedRef<T> | T | null, callback: useResizeObserver.Callback): ResizeObserver | undefined;
+export declare namespace useResizeObserver {
+    type Callback = (entry: ResizeObserverEntry, observer: ResizeObserver) => any;
+}