@jsenv/navi 0.10.2 → 0.11.0

package/src/components/use_auto_focus.js

@@ -1,94 +0,0 @@
-// autoFocus does not work so we focus in a useLayoutEffect,
-// see https://github.com/preactjs/preact/issues/1255
-
-import { useEffect, useLayoutEffect } from "preact/hooks";
-
-let blurEvent = null;
-let timeout;
-document.body.addEventListener(
-  "blur",
-  (e) => {
-    blurEvent = e;
-    setTimeout(() => {
-      blurEvent = null;
-    });
-  },
-  { capture: true },
-);
-document.body.addEventListener(
-  "focus",
-  () => {
-    clearTimeout(timeout);
-    blurEvent = null;
-  },
-  { capture: true },
-);
-
-export const useAutoFocus = (
-  focusableElementRef,
-  autoFocus,
-  { autoFocusVisible, autoSelect } = {},
-) => {
-  useLayoutEffect(() => {
-    if (!autoFocus) {
-      return null;
-    }
-    const activeElement = document.activeElement;
-    const focusableElement = focusableElementRef.current;
-    focusableElement.focus({ focusVisible: autoFocusVisible });
-    if (autoSelect) {
-      focusableElement.select();
-      // Keep the beginning of the text visible instead of scrolling to the end
-      focusableElement.scrollLeft = 0;
-    }
-    return () => {
-      const focusIsOnSelfOrInsideSelf =
-        document.activeElement === focusableElement ||
-        focusableElement.contains(document.activeElement);
-      if (
-        !focusIsOnSelfOrInsideSelf &&
-        document.activeElement !== document.body
-      ) {
-        // focus is not on our element (or body) anymore
-        // keep it where it is
-        return;
-      }
-
-      // We have focus but we are unmounted
-      // -> try to move focus back to something more meaningful that what browser would do
-      // (browser would put it to document.body)
-      // -> We'll try to move focus back to the element that had focus before we moved it to this element
-
-      if (!document.body.contains(activeElement)) {
-        // previously active element is no longer in the document
-        return;
-      }
-
-      if (blurEvent) {
-        // But if this element is unmounted during a blur, the element that is about to receive focus should prevail
-        const elementAboutToReceiveFocus = blurEvent.relatedTarget;
-        const isSelfOrInsideSelf =
-          elementAboutToReceiveFocus === focusableElement ||
-          focusableElement.contains(elementAboutToReceiveFocus);
-        const isPreviouslyActiveElementOrInsideIt =
-          elementAboutToReceiveFocus === activeElement ||
-          (activeElement && activeElement.contains(elementAboutToReceiveFocus));
-        if (!isSelfOrInsideSelf && !isPreviouslyActiveElementOrInsideIt) {
-          // the element about to receive focus is not the input itself or inside it
-          // and is not the previously active element or inside it
-          // -> the element about to receive focus should prevail
-          return;
-        }
-      }
-
-      activeElement.focus();
-    };
-  }, []);
-
-  useEffect(() => {
-    if (autoFocus) {
-      const focusableElement = focusableElementRef.current;
-      focusableElement.scrollIntoView({ inline: "nearest", block: "nearest" });
-    }
-  }, []);
-};

package/src/components/use_batch_during_render.js

@@ -1,33 +0,0 @@
-import { useLayoutEffect, useMemo, useRef } from "preact/hooks";
-
-import { useStableCallback } from "./use_stable_callback.js";
-
-export const useBatchDuringRender = (callback) => {
-  const pendingCallArrayRef = useRef([]);
-  const pendingCallArray = pendingCallArrayRef.current;
-
-  callback = useStableCallback(callback);
-  const callbackWithBatching = useMemo(() => {
-    return (...args) => {
-      if (isRenderingRef.current) {
-        pendingCallArray.push(args);
-        return;
-      }
-      callback(...args);
-    };
-  }, []);
-
-  const isRenderingRef = useRef();
-  isRenderingRef.current = true;
-  useLayoutEffect(() => {
-    isRenderingRef.current = false;
-    if (pendingCallArray.length === 0) {
-      return;
-    }
-    const copy = [...pendingCallArray];
-    pendingCallArray.length = 0;
-    callback(copy);
-  });
-
-  return callbackWithBatching;
-};

package/src/components/use_debounce_true.js

@@ -1,31 +0,0 @@
-import { useLayoutEffect, useRef, useState } from "preact/hooks";
-
-export const useDebounceTrue = (value, delay = 300) => {
-  const [debouncedTrue, setDebouncedTrue] = useState(false);
-  const timerRef = useRef(null);
-
-  useLayoutEffect(() => {
-    // If value is true or becomes true, start a timer
-    if (value) {
-      timerRef.current = setTimeout(() => {
-        setDebouncedTrue(true);
-      }, delay);
-    } else {
-      // If value becomes false, clear any pending timer and immediately set to false
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-      setDebouncedTrue(false);
-    }
-
-    // Cleanup function
-    return () => {
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-      }
-    };
-  }, [value, delay]);
-
-  return debouncedTrue;
-};

package/src/components/use_dependencies_diff.js

@@ -1,35 +0,0 @@
-/*
- * - Usage
- * useEffect(() => {
- *   // here you want to know what has changed, causing useEffect to be called
- * }, [name, value])
- *
- * const diff = useDependenciesDiff({ name, value })
- * useEffect(() => {
- *   console.log('useEffect called because', diff)
- * }, [name, value])
- */
-
-import { useMemo, useRef } from "preact/hooks";
-
-export const useDependenciesDiff = (inputs) => {
-  const oldInputsRef = useRef(inputs);
-  const inputValuesArray = Object.values(inputs);
-  const inputKeysArray = Object.keys(inputs);
-  const diffRef = useRef();
-  useMemo(() => {
-    const oldInputs = oldInputsRef.current;
-    const diff = {};
-    for (const key of inputKeysArray) {
-      const previous = oldInputs[key];
-      const current = inputs[key];
-      if (previous !== current) {
-        diff[key] = { previous, current };
-      }
-    }
-    diffRef.current = diff;
-    oldInputsRef.current = inputs;
-  }, inputValuesArray);
-
-  return diffRef.current;
-};

package/src/components/use_focus_group.js

@@ -1,20 +0,0 @@
-import { initFocusGroup } from "@jsenv/dom";
-import { useLayoutEffect } from "preact/hooks";
-
-export const useFocusGroup = (
-  elementRef,
-  { enabled = true, direction, skipTab, loop, name } = {},
-) => {
-  useLayoutEffect(() => {
-    if (!enabled) {
-      return null;
-    }
-    const focusGroup = initFocusGroup(elementRef.current, {
-      direction,
-      skipTab,
-      loop,
-      name,
-    });
-    return focusGroup.cleanup;
-  }, [direction, skipTab, loop, name]);
-};

package/src/components/use_initial_value.js

@@ -1,78 +0,0 @@
-import { useRef } from "preact/hooks";
-
-let debug = false;
-
-/**
- * Picks the best initial value from three options using a simple priority system.
- *
- * @param {any} externalValue - Value from props or parent component
- * @param {any} fallbackValue - Backup value if external value isn't useful
- * @param {any} defaultValue - Final fallback (usually empty/neutral value)
- *
- * @returns {any} The chosen value using this priority:
- *   1. externalValue (if provided and different from default)
- *   2. fallbackValue (if external value is missing/same as default)
- *   3. defaultValue (if nothing else works)
- *
- * @example
- * resolveInitialValue("hello", "backup", "") → "hello"
- * resolveInitialValue(undefined, "backup", "") → "backup"
- * resolveInitialValue("", "backup", "") → "backup" (empty same as default)
- */
-export const resolveInitialValue = (
-  externalValue,
-  fallbackValue,
-  defaultValue,
-) => {
-  if (externalValue !== undefined && externalValue !== defaultValue) {
-    return externalValue;
-  }
-  if (fallbackValue !== undefined) {
-    return fallbackValue;
-  }
-  return defaultValue;
-};
-
-/**
- * Hook that syncs external value changes to a setState function.
- * Always syncs when external value changes, regardless of what it changes to.
- *
- * @param {any} externalValue - Value from props or parent component to watch for changes
- * @param {any} defaultValue - Default value to use when external value is undefined
- * @param {Function} setValue - Function to call when external value changes
- * @param {string} name - Parameter name for debugging
- */
-export const useExternalValueSync = (
-  externalValue,
-  defaultValue,
-  setValue,
-  name = "",
-) => {
-  // Track external value changes and sync them
-  const previousExternalValueRef = useRef(externalValue);
-  if (externalValue !== previousExternalValueRef.current) {
-    previousExternalValueRef.current = externalValue;
-    // Always sync external value changes - use defaultValue only when external is undefined
-    const valueToSet =
-      externalValue === undefined ? defaultValue : externalValue;
-    if (debug) {
-      console.debug(
-        `useExternalValueSync(${name}) syncing external value change: ${valueToSet}`,
-      );
-    }
-    setValue(valueToSet);
-  }
-};
-
-const UNSET = {};
-export const useInitialValue = (compute) => {
-  const initialValueRef = useRef(UNSET);
-  let initialValue = initialValueRef.current;
-  if (initialValue !== UNSET) {
-    return initialValue;
-  }
-
-  initialValue = compute();
-  initialValueRef.current = initialValue;
-  return initialValue;
-};

package/src/components/use_is_visited.js

@@ -1,19 +0,0 @@
-import {
-  isVisited,
-  visitedUrlsSignal,
-} from "../browser_integration/browser_integration.js";
-
-/**
- * Hook that reactively checks if a URL is visited.
- * Re-renders when the visited URL set changes.
- *
- * @param {string} url - The URL to check
- * @returns {boolean} Whether the URL has been visited
- */
-export const useIsVisited = (url) => {
-  // Access the signal to create reactive dependency
-  // eslint-disable-next-line no-unused-expressions
-  visitedUrlsSignal.value;
-
-  return isVisited(url);
-};

package/src/components/use_ref_array.js

@@ -1,38 +0,0 @@
-import { createRef } from "preact";
-import { useMemo, useRef } from "preact/hooks";
-
-export const useRefArray = (items, keyFromItem) => {
-  const refMapRef = useRef(new Map());
-  const previousKeySetRef = useRef(new Set());
-
-  return useMemo(() => {
-    const refMap = refMapRef.current;
-    const previousKeySet = previousKeySetRef.current;
-    const currentKeySet = new Set();
-    const refArray = [];
-
-    for (let i = 0; i < items.length; i++) {
-      const item = items[i];
-      const key = keyFromItem(item);
-      currentKeySet.add(key);
-
-      const refForKey = refMap.get(key);
-      if (refForKey) {
-        refArray[i] = refForKey;
-      } else {
-        const newRef = createRef();
-        refMap.set(key, newRef);
-        refArray[i] = newRef;
-      }
-    }
-
-    for (const key of previousKeySet) {
-      if (!currentKeySet.has(key)) {
-        refMap.delete(key);
-      }
-    }
-    previousKeySetRef.current = currentKeySet;
-
-    return refArray;
-  }, [items]);
-};

package/src/components/use_signal_sync.js

@@ -1,50 +0,0 @@
-import { useSignal } from "@preact/signals";
-import { useRef } from "preact/hooks";
-
-/**
- * Creates a signal that stays synchronized with an external value,
- * only updating the signal when the value actually changes.
- *
- * This hook solves a common reactive UI pattern where:
- * 1. A signal controls a UI element (like an input field)
- * 2. The UI element can be modified by user interaction
- * 3. When the external "source of truth" changes, it should take precedence
- *
- * @param {any} value - The external value to sync with (the "source of truth")
- * @param {any} [initialValue] - Optional initial value for the signal (defaults to value)
- * @returns {Signal} A signal that tracks the external value but allows temporary local changes
- *
- * @example
- * const FileNameEditor = ({ file }) => {
- *   // Signal stays in sync with file.name, but allows user editing
- *   const nameSignal = useSignalSync(file.name);
- *
- *   return (
- *     <Editable
- *       valueSignal={nameSignal}  // User can edit this
- *       action={renameFileAction} // Saves changes
- *     />
- *   );
- * };
- *
- * // Scenario:
- * // 1. file.name = "doc.txt", nameSignal.value = "doc.txt"
- * // 2. User types "report" -> nameSignal.value = "report.txt"
- * // 3. External update: file.name = "shared-doc.txt"
- * // 4. Next render: nameSignal.value = "shared-doc.txt" (model wins!)
- *
- */
-
-export const useSignalSync = (value, initialValue = value) => {
-  const signal = useSignal(initialValue);
-  const previousValueRef = useRef(value);
-
-  // Only update signal when external value actually changes
-  // This preserves user input between external changes
-  if (previousValueRef.current !== value) {
-    previousValueRef.current = value;
-    signal.value = value; // Model takes precedence
-  }
-
-  return signal;
-};

package/src/components/use_stable_callback.js

@@ -1,68 +0,0 @@
-/**
- * Custom hook creating a stable callback that doesn't trigger re-renders.
- *
- * PROBLEM: Parent components often forget to use useCallback, causing library
- * components to re-render unnecessarily when receiving callback props.
- *
- * SOLUTION: Library components can use this hook to create stable callback
- * references internally, making them defensive against parents who don't
- * optimize their callbacks. This ensures library components don't force
- * consumers to think about useCallback.
- *
- * USAGE:
- * ```js
- * // Parent component (consumer) - no useCallback needed
- * const Parent = () => {
- *   const [count, setCount] = useState(0);
- *
- *   // Parent naturally creates new function reference each render
- *   // (forgetting useCallback is common and shouldn't break performance)
- *   return <LibraryButton onClick={(e) => setCount(count + 1)} />;
- * };
- *
- * // Library component - defensive against changing callbacks
- * const LibraryButton = ({ onClick }) => {
- *   // ✅ Create stable reference from parent's potentially changing callback
- *   const stableClick = useStableCallback(onClick);
- *
- *   // Internal expensive components won't re-render when parent updates
- *   return <ExpensiveInternalButton onClick={stableClick} />;
- * };
- *
- * // Deep internal component gets stable reference
- * const ExpensiveInternalButton = memo(({ onClick }) => {
- *   // This won't re-render when Parent's count changes
- *   // But onClick will always call the latest Parent callback
- *   return <button onClick={onClick}>Click me</button>;
- * });
- * ```
- *
- * Perfect for library components that need performance without burdening consumers.
- */
-
-import { useRef } from "preact/hooks";
-
-export const useStableCallback = (callback, mapper) => {
-  const callbackRef = useRef();
-  callbackRef.current = callback;
-  const stableCallbackRef = useRef();
-
-  // Return original falsy value directly when callback is not a function
-  if (!callback) {
-    return callback;
-  }
-
-  const existingStableCallback = stableCallbackRef.current;
-  if (existingStableCallback) {
-    return existingStableCallback;
-  }
-  const stableCallback = (...args) => {
-    const currentCallback = callbackRef.current;
-    if (mapper) {
-      args = mapper(...args);
-    }
-    return currentCallback(...args);
-  };
-  stableCallbackRef.current = stableCallback;
-  return stableCallback;
-};

package/src/components/use_state_array.js

@@ -1,47 +0,0 @@
-import { useCallback, useRef, useState } from "preact/hooks";
-import { addIntoArray, removeFromArray } from "../utils/array_add_remove.js";
-import {
-  resolveInitialValue,
-  useExternalValueSync,
-} from "./use_initial_value.js";
-
-const FIRST_MOUNT = {};
-export const useStateArray = (
-  externalValue,
-  fallbackValue,
-  defaultValue = [],
-) => {
-  const initialValueRef = useRef(FIRST_MOUNT);
-  if (initialValueRef.current === FIRST_MOUNT) {
-    const initialValue = resolveInitialValue(
-      externalValue,
-      fallbackValue,
-      defaultValue,
-    );
-    initialValueRef.current = initialValue;
-  }
-  const initialValue = initialValueRef.current;
-  const [array, setArray] = useState(initialValue);
-
-  // Only sync external value changes if externalValue was explicitly provided
-  useExternalValueSync(externalValue, defaultValue, setArray, "state_array");
-
-  const add = useCallback((valueToAdd) => {
-    setArray((array) => {
-      const newArray = addIntoArray(array, valueToAdd);
-      return newArray;
-    });
-  }, []);
-
-  const remove = useCallback((valueToRemove) => {
-    setArray((array) => {
-      return removeFromArray(array, valueToRemove);
-    });
-  }, []);
-
-  const reset = useCallback(() => {
-    setArray(initialValue);
-  }, [initialValue]);
-
-  return [array, add, remove, reset];
-};