@reykjavik/hanna-react 0.10.103 → 0.10.104

package/utils/browserSide.js

@@ -1,6 +1,158 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useIsServerSide = exports.useIsBrowserSide = void 0;
-var hooks_1 = require("@hugsmidjan/react/hooks");
-Object.defineProperty(exports, "useIsBrowserSide", { enumerable: true, get: function () { return hooks_1.useIsBrowserSide; } });
-Object.defineProperty(exports, "useIsServerSide", { enumerable: true, get: function () { return hooks_1.useIsServerSide; } });
+exports.setDefaultSSR = exports.useIsBrowserSide = exports.useIsServerSide = void 0;
+const react_1 = require("react");
+let alreadyBrowserSide = false;
+const defaultSSRSupport = true;
+/**
+ * The default value use for the optional `ssrSupport` parameter
+ * on the `useIsBRowserSide` and `useIsServerSide` hooks.`
+ */
+let DEFAULT_SSR_SUPPORT = defaultSSRSupport;
+/**
+ * Low-level useState wrapper that initializes the state to one value
+ * during initial render and then updates it to another value
+ * once the component has been mounted.
+ *
+ * After that it's just a normal [value, setValue] pair.
+ *
+ * NOTE: The optional `ssrSupport` parameter is ignored after the initial render
+ */
+const useClientState = (serverState, clientState, 
+/**
+ * Indicates whether server-side rendering is supported or not.
+ *
+ * The `ssr-only` value is useful for cases where you need
+ * to demo the server-rendered version in a browser.
+ */
+ssrSupport = DEFAULT_SSR_SUPPORT) => {
+    const stateTuple = (0, react_1.useState)(() => (ssrSupport === 'ssr-only'
+        ? serverState
+        : ssrSupport && !alreadyBrowserSide
+            ? serverState
+            : clientState) // TODO: Remove this type assertion once @types/react and typescript have been updated
+    );
+    (0, react_1.useEffect)(() => {
+        alreadyBrowserSide = true;
+        if (ssrSupport !== 'ssr-only') {
+            stateTuple[1](clientState);
+        }
+    }, []);
+    return stateTuple;
+};
+/**
+ * Returns `true` if `useEffect` has not executed yet.
+ *
+ * This signals that we're in "server-side rendering" mode
+ * and it's not yet appropriate to do JS-driven UI enhancements.
+ *
+ * ```js
+ * const Knob = (props) => {
+ *   const [visible, setVisible] = useState(false);
+ *   const isServer = useIsServerSide();
+ *   const handleClick = () => {
+ *     setVisible(!visible);
+ *     props.onClick && props.onClick(!visible);
+ *   };
+ *
+ *   if (isServer) {
+ *     return <span className="Knob">{props.label}</span>
+ *   }
+ *   return (
+ *     <button className="Knob" aria-pressed={visible} onClick={handleClick}>
+ *       {props.label}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * SSR support mode can optionally be set to:
+ *
+ * - `true` (the default) enables the serve-side phase (returns `true` then `undefined`).
+ * - `false` disables (skips) the serve-side phase (always returns `undefined`).
+ * - `"ssr-only"` disables (skips) the browser-side phase (always returns `true`).
+ *
+ * NOTE: The `ssrSupport` parameter is ignored after the initial render.
+ */
+const useIsServerSide = (ssrSupport) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+useClientState(true, false, ssrSupport)[0] || undefined;
+exports.useIsServerSide = useIsServerSide;
+/**
+ * Returns `true` when `useEffect` has executed.
+ *
+ * This signals the time to apply Progressive Enhancement.
+ *
+ * ```js
+ * const Knob = (props) => {
+ *   const [visible, setVisible] = useState(false);
+ *   const isBrowser = useIsBrowserSide();
+ *   const handleClick = () => {
+ *     setVisible(!visible);
+ *     props.onClick && props.onClick(!visible);
+ *   };
+ *
+ *   if (isBrowser) {
+ *     return (
+ *       <button className="Knob" aria-pressed={visible} onClick={handleClick}>
+ *         {props.label}
+ *       </button>
+ *     );
+ *   }
+ *   return <span className="Knob">{props.label}</span>
+ * }
+ * ```
+ *
+ * SSR support mode can optionally be set to:
+ *
+ * - `true` (the default) enables the serve-side phase (returns `true` then `undefined`).
+ * - `false` disables (skips) the serve-side phase (always returns `true`).
+ * - `"ssr-only"` disables (skips) the browser-side phase (always returns `undefined`).
+ *
+ * NOTE: The `ssrSupport` parameter is ignored after the initial render.
+ */
+const useIsBrowserSide = (ssrSupport) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+useClientState(false, true, ssrSupport)[0] || undefined;
+exports.useIsBrowserSide = useIsBrowserSide;
+// ---------------------------------------------------------------------------
+const _history = [];
+/**
+ * Allows you to set a the default SSRSupport value for the `useIsBRowserSide`
+ * and `useIsServerSide` hooks.
+ *
+ * Example use:
+ *
+ * ```js
+ * setDefaultSSR(false);
+ * ```
+ *
+ * The values are pushed to a simple stack, and if you want to revert
+ * a temporarily set value, use the `setDefaultSSR.pop()` method
+ * to go back to the previous value. Example:
+ *
+ * ```js
+ * setDefaultSSR('ssr-only');
+ * // ...render some components...
+ * setDefaultSSR.pop(); // go back to the previous state
+ * ```
+ *
+ * You explicitly switch to using the library's default by passing `undefined`
+ * as an argument — like so:
+ *
+ * ```js
+ * setDefaultSSR(undefined);
+ * ```
+ */
+const setDefaultSSR = (ssrSupport) => {
+    DEFAULT_SSR_SUPPORT = ssrSupport != null ? ssrSupport : defaultSSRSupport;
+    _history.unshift(DEFAULT_SSR_SUPPORT);
+};
+exports.setDefaultSSR = setDefaultSSR;
+/**
+ * Unsets the last pushed defaultSSR value
+ */
+exports.setDefaultSSR.pop = () => {
+    _history.shift();
+    DEFAULT_SSR_SUPPORT = _history[0] != null ? _history[0] : defaultSSRSupport;
+};

package/utils/config.d.ts

@@ -1,14 +1 @@
-import { SSRSupport } from '@hugsmidjan/react/hooks';
-export type { LinkRenderer } from '../_abstract/_Link.js';
-export { setLinkRenderer } from '../_abstract/_Link.js';
-export { setDefaultSSR } from '@hugsmidjan/react/hooks';
-export type SSRSupportProps = {
-    /**
-     * Indicates whether server-side rendering is supported or not.
-     *
-     * The `ssr-only` value is useful for cases where you need
-     * to demo the server-rendered version in a browser.
-     */
-    ssr?: SSRSupport;
-};
-export type { SSRSupport };
+export { type LinkRenderer, setLinkRenderer } from '../_abstract/_Link.js';

package/utils/config.js

@@ -1,8 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setDefaultSSR = exports.setLinkRenderer = void 0;
+exports.setLinkRenderer = void 0;
 var _Link_js_1 = require("../_abstract/_Link.js");
 Object.defineProperty(exports, "setLinkRenderer", { enumerable: true, get: function () { return _Link_js_1.setLinkRenderer; } });
-// ---------------------------------------------------------------------------
-var hooks_1 = require("@hugsmidjan/react/hooks");
-Object.defineProperty(exports, "setDefaultSSR", { enumerable: true, get: function () { return hooks_1.setDefaultSSR; } });

package/utils/useCallbackOnEsc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Performs a callback whenever the user hits the ESC key.
+ *
+ * Pass `undefined` to remove the event listener
+ */
+export declare const useCallbackOnEsc: (callback: (() => void) | undefined) => void;

package/utils/useCallbackOnEsc.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCallbackOnEsc = void 0;
+const react_1 = require("react");
+/**
+ * Performs a callback whenever the user hits the ESC key.
+ *
+ * Pass `undefined` to remove the event listener
+ */
+const useCallbackOnEsc = (callback) => {
+    const cb = (0, react_1.useRef)(callback);
+    const active = !!callback;
+    cb.current = callback;
+    (0, react_1.useEffect)(() => {
+        if (!active) {
+            return;
+        }
+        const callbackOnEsc = (e) => {
+            if (e.key === 'Escape') {
+                cb.current && cb.current();
+            }
+        };
+        document.addEventListener('keydown', callbackOnEsc);
+        return () => {
+            document.removeEventListener('keydown', callbackOnEsc);
+        };
+    }, [active]);
+};
+exports.useCallbackOnEsc = useCallbackOnEsc;

package/utils/useDomid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a stable, unique ID string.
+ *
+ * Uses useId from React@18 when available, but falls back on a custom id
+ * generator. (The custom generator causes angry hydration warnings in dev
+ * mode).
+ */
+export declare const useDomid: (staticId?: string) => string;

package/utils/useDomid.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDomid = void 0;
+const tslib_1 = require("tslib");
+const React = tslib_1.__importStar(require("react"));
+const domid_1 = tslib_1.__importDefault(require("@hugsmidjan/qj/domid"));
+// @ts-expect-error  (transparently feature-detect useId hook, which is introduced in React@18)
+const useId = React.useId;
+/**
+ * Returns a stable, unique ID string.
+ *
+ * Uses useId from React@18 when available, but falls back on a custom id
+ * generator. (The custom generator causes angry hydration warnings in dev
+ * mode).
+ */
+exports.useDomid = useId
+    ? (staticId) => {
+        const id = useId();
+        return staticId || id;
+    }
+    : (staticId) => React.useRef(staticId || (0, domid_1.default)()).current;

package/utils/useLaggedState.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A `useState` alternative with in-built support for delayed (debounced) effect.
+ *
+ * This is especially useful when emulating "focusin"/"focusout" events,
+ * and a less jittery 'onMouseEnter'/'onMouseLeave' behavior.
+ *
+ * The returned `setState` function accepts an optional `customDelay` parameter.
+ *
+ * An explicitly falsy delay (`0` | `false` | `null`) results in a
+ * immediate (normal) `setState` invocation, whereas any other value uses
+ * `setTimeout` to delay the update.
+ *
+ * Each `setState` call automatically cancels any pending scheduled update.
+ *
+ * You can also use the `setState.cancel()` helper to to cancel the last
+ * scheduled update, without explicitly setting a new value.
+ */
+export declare const useLaggedState: <S>(initialState: S | (() => S), defaultDelay?: number, thenState?: S | (() => S) | undefined) => [currentState: S, setState: (newState: S | ((prevState: S, upcomingState: S) => S), customDelay?: number | false) => void, nextState: S, isTransitioning: true | undefined];

package/utils/useLaggedState.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLaggedState = void 0;
+const react_1 = require("react");
+// ---------------------------------------------------------------------------
+/**
+ * A `useState` alternative with in-built support for delayed (debounced) effect.
+ *
+ * This is especially useful when emulating "focusin"/"focusout" events,
+ * and a less jittery 'onMouseEnter'/'onMouseLeave' behavior.
+ *
+ * The returned `setState` function accepts an optional `customDelay` parameter.
+ *
+ * An explicitly falsy delay (`0` | `false` | `null`) results in a
+ * immediate (normal) `setState` invocation, whereas any other value uses
+ * `setTimeout` to delay the update.
+ *
+ * Each `setState` call automatically cancels any pending scheduled update.
+ *
+ * You can also use the `setState.cancel()` helper to to cancel the last
+ * scheduled update, without explicitly setting a new value.
+ */
+const useLaggedState = (initialState, 
+/**
+ * Default delay in milliseconds.  A value of `0` results in a
+ * immediate (normal) setState invocation.
+ *
+ * NOTE: The `defaultDelay` parameter is ignored after the initial render.
+ */
+defaultDelay = 0, 
+/**
+ * A state that should be automatically transitioned to after the initial mounting.
+ *
+ * Syntatic sugar equivalent to the following:
+ *
+ * ```js
+ *   const [value, _, setValue] = useLaggedState(initialState, defaultDelay);
+ *   useEffect(() => {
+ *     setValue(thenState, defaultDelay);
+ *   }, [])
+ * ```
+ */
+thenState) => {
+    const timeout = (0, react_1.useRef)();
+    const [[currentState, nextState], setLocalState] = (0, react_1.useState)(() => {
+        const initial = typeof initialState === 'function' ? initialState() : initialState;
+        return [initial, initial];
+    });
+    const setState = (0, react_1.useMemo)(() => {
+        const _setter = (newState, customDelay) => {
+            timeout.current && clearTimeout(timeout.current);
+            const delay = customDelay !== undefined ? customDelay : defaultDelay;
+            setLocalState((prevState) => {
+                const [current, upcoming] = prevState;
+                const newValue = typeof newState === 'function'
+                    ? newState(current, upcoming)
+                    : newState;
+                if (!delay || newValue === current) {
+                    // Instant update!
+                    return newValue === current && newValue === upcoming
+                        ? prevState
+                        : [newValue, newValue];
+                }
+                // Debounced update!
+                timeout.current = setTimeout(() => setLocalState([newValue, newValue]), delay);
+                return [current, newValue];
+            });
+        };
+        _setter.cancel = () => {
+            _setter((prevState) => prevState, null);
+        };
+        return _setter;
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+    // defaultDelay,
+    ]);
+    (0, react_1.useEffect)(() => {
+        thenState !== undefined && setState(thenState);
+        return () => {
+            timeout.current && clearTimeout(timeout.current);
+        };
+    }, [] // eslint-disable-line react-hooks/exhaustive-deps
+    );
+    const isTransitioning = currentState !== nextState || undefined;
+    return [currentState, setState, nextState, isTransitioning];
+};
+exports.useLaggedState = useLaggedState;

package/utils/useOnClickOutside.d.ts

@@ -0,0 +1,9 @@
+import { MutableRefObject, RefObject } from 'react';
+type Ref<E extends HTMLElement> = MutableRefObject<E> | RefObject<E>;
+/**
+ *
+ * @param ref single or array of refs to check for click outside
+ * @param handler callback to run when clicked outside of the ref
+ */
+declare const useOnClickOutside: <E extends HTMLElement>(ref: Ref<E> | Ref<E>[], handler: (event: globalThis.MouseEvent | globalThis.TouchEvent) => void) => void;
+export { useOnClickOutside };

package/utils/useOnClickOutside.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOnClickOutside = void 0;
+const react_1 = require("react");
+/**
+ *
+ * @param ref single or array of refs to check for click outside
+ * @param handler callback to run when clicked outside of the ref
+ */
+const useOnClickOutside = (ref, handler) => {
+    const refs = Array.isArray(ref) ? ref : [ref];
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const stableRefs = (0, react_1.useMemo)(() => refs, refs);
+    (0, react_1.useEffect)(() => {
+        const listener = (event) => {
+            const shouldTrigger = !stableRefs.some((r) => {
+                const node = r.current;
+                if (!node) {
+                    return false;
+                }
+                return node.contains(event.target);
+            });
+            if (shouldTrigger) {
+                handler(event);
+            }
+        };
+        document.addEventListener('mousedown', listener);
+        document.addEventListener('touchstart', listener);
+        return () => {
+            document.removeEventListener('mousedown', listener);
+            document.removeEventListener('touchstart', listener);
+        };
+    }, [handler, stableRefs]);
+};
+exports.useOnClickOutside = useOnClickOutside;

package/utils/useScrollEdgeDetect.d.ts

@@ -0,0 +1,15 @@
+import { RefObject } from 'react';
+type ScrollAxis = 'horizontal' | 'vertical';
+type AtState = {
+    start: boolean;
+    end: boolean;
+};
+export type ScrollEdgeDetectOptions<RefElm extends HTMLElement = HTMLElement> = {
+    axis: ScrollAxis;
+    /** **NOTE:** Make sure this function is stable to avoid unnecessary re-runs */
+    getElm?: (elm: RefElm | null | undefined) => HTMLElement | undefined | null | false;
+    /** Initial `at` status */
+    startAt?: AtState;
+};
+export declare const useScrollEdgeDetect: <RefElm extends HTMLElement = HTMLElement>(options: ScrollAxis | ScrollEdgeDetectOptions<RefElm>, scrollerRef?: RefObject<RefElm> | undefined) => [scrollElmRef: RefObject<RefElm>, at: AtState];
+export {};

package/utils/useScrollEdgeDetect.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useScrollEdgeDetect = void 0;
+const tslib_1 = require("tslib");
+const react_1 = require("react");
+const throttle_1 = tslib_1.__importDefault(require("@hugsmidjan/qj/throttle"));
+const tolerance = 8; // px
+const throttleMs = 100;
+const useScrollEdgeDetect = (options, scrollerRef) => {
+    const opts = typeof options === 'string' ? { axis: options } : options;
+    const _scrollerRef = (0, react_1.useRef)(null);
+    scrollerRef = scrollerRef || _scrollerRef;
+    const [at, setAt] = (0, react_1.useState)(opts.startAt || { start: true, end: true });
+    const scrollerRefElm = scrollerRef.current;
+    const { getElm, axis } = opts;
+    (0, react_1.useEffect)(() => {
+        const scrollerElm = scrollerRefElm && getElm ? getElm(scrollerRefElm) : scrollerRefElm;
+        if (!(scrollerElm instanceof HTMLElement)) {
+            return;
+        }
+        const checkScroll = (0, throttle_1.default)(() => setAt((at) => {
+            let scroll, offsetSize, totalSize;
+            if (axis === 'horizontal') {
+                scroll = scrollerElm.scrollLeft;
+                offsetSize = scrollerElm.offsetWidth;
+                totalSize = scrollerElm.scrollWidth;
+            }
+            else {
+                scroll = scrollerElm.scrollTop;
+                offsetSize = scrollerElm.offsetHeight;
+                totalSize = scrollerElm.scrollHeight;
+            }
+            const start = scroll < tolerance;
+            const end = totalSize - (offsetSize + scroll) < tolerance;
+            if (at.start === start && at.end === end) {
+                return at;
+            }
+            return { start, end };
+        }), throttleMs);
+        scrollerElm.addEventListener('scroll', checkScroll);
+        window.addEventListener('resize', checkScroll);
+        checkScroll();
+        return () => {
+            scrollerElm.removeEventListener('scroll', checkScroll);
+            window.removeEventListener('resize', checkScroll);
+        };
+    }, [scrollerRefElm, getElm, axis]);
+    return [scrollerRef, at];
+};
+exports.useScrollEdgeDetect = useScrollEdgeDetect;

package/utils/useShortState.d.ts

@@ -0,0 +1,2 @@
+/** State variable that always snaps back to `undefined` after `duration` milliseconds. */
+export declare const useShortState: <S>(initialState?: S | (() => S) | undefined, defaultDuration?: number) => readonly [S | undefined, (newState: S | (() => S), duration?: number) => void];

package/utils/useShortState.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useShortState = void 0;
+const react_1 = require("react");
+const DEFAULT_DURATION = 0;
+// TODO: Add function signtures allowing either zero args, or 2.
+/** State variable that always snaps back to `undefined` after `duration` milliseconds. */
+const useShortState = (
+/** Initial temporary state that then gets reverted back
+ * to `undefined` after `duration` milliseconds
+ * */
+initialState, 
+/** Default duration, can be overridden on a case-by-case basis
+ * by passing a custom duration to the `setState` function
+ * */
+defaultDuration = DEFAULT_DURATION) => {
+    const [state, _setState] = (0, react_1.useState)(initialState);
+    const timeout = (0, react_1.useRef)();
+    const cancelTimeout = () => {
+        timeout.current && clearTimeout(timeout.current);
+    };
+    const setState = (0, react_1.useRef)((newState, duration = defaultDuration) => {
+        _setState(newState);
+        cancelTimeout();
+        timeout.current = setTimeout(() => {
+            timeout.current = null;
+            _setState(undefined);
+        }, duration);
+    }).current;
+    (0, react_1.useEffect)(() => {
+        if (initialState !== undefined) {
+            setState(initialState, defaultDuration);
+        }
+        return cancelTimeout;
+    }, []);
+    return [state, setState];
+};
+exports.useShortState = useShortState;

package/utils.d.ts

@@ -3,6 +3,7 @@ export * from './utils/browserSide.js';
 export * from './utils/config.js';
 export { HannaUIState, useHannaUIState } from './utils/HannaUIState.js';
 export * from './utils/useDidChange.js';
+export * from './utils/useDomid.js';
 export * from './utils/useFormatMonitor.js';
 export * from './utils/useGetSVGtext.js';
 export * from './utils/useMenuToggling.js';

package/utils.js

@@ -8,6 +8,7 @@ var HannaUIState_js_1 = require("./utils/HannaUIState.js");
 Object.defineProperty(exports, "HannaUIState", { enumerable: true, get: function () { return HannaUIState_js_1.HannaUIState; } });
 Object.defineProperty(exports, "useHannaUIState", { enumerable: true, get: function () { return HannaUIState_js_1.useHannaUIState; } });
 tslib_1.__exportStar(require("./utils/useDidChange.js"), exports);
+tslib_1.__exportStar(require("./utils/useDomid.js"), exports);
 tslib_1.__exportStar(require("./utils/useFormatMonitor.js"), exports);
 tslib_1.__exportStar(require("./utils/useGetSVGtext.js"), exports);
 tslib_1.__exportStar(require("./utils/useMenuToggling.js"), exports);