@jsenv/navi 0.0.1

package/src/components/shortcut/shortcut_context.jsx

@@ -0,0 +1,390 @@
+import { canInterceptKeys } from "@jsenv/dom";
+import { requestAction } from "@jsenv/validation";
+import { createContext } from "preact";
+import { useContext, useEffect, useRef, useState } from "preact/hooks";
+import { useAction } from "../action_execution/use_action.js";
+import { useExecuteAction } from "../action_execution/use_execute_action.js";
+import { useActionEvents } from "../use_action_events.js";
+import { isMac } from "./os.js";
+
+import.meta.css = /* css */ `
+  .navi_shortcut_container {
+    /* Visually hidden container - doesn't affect layout */
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+
+    /* Ensure it's not interactable */
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .navi_shortcut_button {
+    /* Visually hidden but accessible to screen readers */
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+
+    /* Ensure it's not focusable via tab navigation */
+    opacity: 0;
+    pointer-events: none;
+  }
+`;
+
+const ShortcutContext = createContext();
+export const useShortcutContext = () => {
+  return useContext(ShortcutContext);
+};
+
+export const ShortcutProvider = ({
+  elementRef,
+  shortcuts,
+  onActionPrevented,
+  onActionStart,
+  onActionAbort,
+  onActionError,
+  onActionEnd,
+  allowConcurrentActions,
+  children,
+}) => {
+  if (!elementRef) {
+    throw new Error(
+      "ShortcutProvider requires an elementRef to attach shortcuts to.",
+    );
+  }
+
+  const shortcutElements = [];
+  shortcuts.forEach((shortcut) => {
+    const combinationString = useAriaKeyShortcuts(shortcut.key);
+    shortcutElements.push(
+      <button
+        className="navi_shortcut_button"
+        key={combinationString}
+        aria-keyshortcuts={combinationString}
+        tabIndex="-1"
+        action={shortcut.action}
+        data-action={shortcut.action.name}
+        data-confirm-message={shortcut.confirmMessage}
+      >
+        {shortcut.description}
+      </button>,
+    );
+  });
+  const shortcutElementRef = useRef();
+  const shortcutHiddenElement = (
+    <div ref={shortcutElementRef} className="navi_shortcut_container">
+      {shortcutElements}
+    </div>
+  );
+
+  const executeAction = useExecuteAction(shortcutElementRef);
+  const [shortcutActionIsBusy, setShortcutActionIsBusy] = useState(false);
+  useActionEvents(shortcutElementRef, {
+    onPrevented: onActionPrevented,
+    onAction: (actionEvent) => {
+      // action can be a function or an action object, whem a function we must "wrap" it in a function returning that function
+      // otherwise setState would call that action immediately
+      setAction(() => actionEvent.detail.action);
+      executeAction(actionEvent, { requester: elementRef.current });
+    },
+    onStart: (e) => {
+      if (!allowConcurrentActions) {
+        setShortcutActionIsBusy(true);
+      }
+      onActionStart?.(e);
+    },
+    onAbort: (e) => {
+      setShortcutActionIsBusy(false);
+      onActionAbort?.(e);
+    },
+    onError: (e) => {
+      setShortcutActionIsBusy(false);
+      onActionError?.(e);
+    },
+    onEnd: (e) => {
+      setShortcutActionIsBusy(false);
+      onActionEnd?.(e);
+    },
+  });
+
+  const [action, setAction] = useState(null);
+  for (const shortcut of shortcuts) {
+    shortcut.action = useAction(shortcut.action);
+  }
+
+  useKeyboardShortcuts(elementRef, shortcuts, (shortcut, event) => {
+    if (shortcutActionIsBusy) {
+      return;
+    }
+    event.preventDefault();
+    const { action } = shortcut;
+    requestAction(action, {
+      event,
+      target: shortcutElementRef.current,
+      requester: elementRef.current,
+      confirmMessage: shortcut.confirmMessage,
+    });
+  });
+
+  return (
+    <ShortcutContext.Provider
+      value={{
+        shortcutAction: action,
+        shortcutActionIsBusy,
+      }}
+    >
+      {children}
+      {shortcutHiddenElement}
+    </ShortcutContext.Provider>
+  );
+};
+
+export const useKeyboardShortcuts = (elementRef, shortcuts, onShortcut) => {
+  const shortcutsRef = useRef(shortcuts);
+  shortcutsRef.current = shortcuts;
+
+  const onShortcutRef = useRef(onShortcut);
+  onShortcutRef.current = onShortcut;
+
+  useEffect(() => {
+    const element = elementRef.current;
+
+    const onKeydown = (event) => {
+      if (!canInterceptKeys(event)) {
+        return;
+      }
+
+      let shortcutFound;
+      for (const shortcutCandidate of shortcutsRef.current) {
+        const { enabled = true, key } = shortcutCandidate;
+        if (!enabled) {
+          continue;
+        }
+
+        // Handle platform-specific combination objects
+        let actualCombination;
+        let crossPlatformCombination;
+
+        if (typeof key === "object" && key !== null) {
+          actualCombination = isMac ? key.mac : key.other;
+        } else {
+          actualCombination = key;
+
+          // Auto-generate cross-platform combination if needed
+          if (containsPlatformSpecificKeys(key)) {
+            crossPlatformCombination = generateCrossPlatformCombination(key);
+          }
+        }
+
+        // Check both the actual combination and cross-platform combination
+        const matchesActual =
+          actualCombination &&
+          eventIsMatchingKeyCombination(event, actualCombination);
+        const matchesCrossPlatform =
+          crossPlatformCombination &&
+          crossPlatformCombination !== actualCombination &&
+          eventIsMatchingKeyCombination(event, crossPlatformCombination);
+
+        if (!matchesActual && !matchesCrossPlatform) {
+          continue;
+        }
+        if (shortcutCandidate.when && !shortcutCandidate.when(event)) {
+          continue;
+        }
+        shortcutFound = shortcutCandidate;
+        break;
+      }
+      if (!shortcutFound) {
+        return;
+      }
+      onShortcutRef.current(shortcutFound, event);
+    };
+
+    element.addEventListener("keydown", onKeydown);
+    return () => {
+      element.removeEventListener("keydown", onKeydown);
+    };
+  }, []);
+};
+
+// Configuration for mapping shortcut key names to browser event properties
+const modifierKeyMapping = {
+  metaKey: {
+    names: ["meta"],
+    macNames: ["command", "cmd"],
+  },
+  ctrlKey: {
+    names: ["control", "ctrl"],
+  },
+  shiftKey: {
+    names: ["shift"],
+  },
+  altKey: {
+    names: ["alt"],
+    macNames: ["option"],
+  },
+};
+// Maps canonical browser key names to their user-friendly aliases.
+// Used for both event matching and ARIA normalization.
+const keyMapping = {
+  " ": { alias: ["space"] },
+  "escape": { alias: ["esc"] },
+  "arrowup": { alias: ["up"] },
+  "arrowdown": { alias: ["down"] },
+  "arrowleft": { alias: ["left"] },
+  "arrowright": { alias: ["right"] },
+  "delete": { alias: ["del"] },
+  // Platform-specific mappings
+  ...(isMac
+    ? { delete: { alias: ["backspace"] } }
+    : { backspace: { alias: ["delete"] } }),
+};
+const keyToAriaKeyMapping = {
+  // Platform-specific ARIA names
+  command: "meta",
+  option: "altgraph", // Mac option key uses "altgraph" in ARIA spec
+
+  // Regular keys - platform-specific normalization
+  delete: isMac ? "backspace" : "delete", // Mac delete key is backspace semantically
+  backspace: isMac ? "backspace" : "delete",
+};
+
+const eventIsMatchingKeyCombination = (event, keyCombination) => {
+  const keys = keyCombination.toLowerCase().split("+");
+
+  for (const key of keys) {
+    let modifierFound = false;
+
+    // Check if this key is a modifier
+    for (const [eventProperty, config] of Object.entries(modifierKeyMapping)) {
+      const allNames = [...config.names];
+
+      // Add Mac-specific names only if we're on Mac and they exist
+      if (isMac && config.macNames) {
+        allNames.push(...config.macNames);
+      }
+
+      if (allNames.includes(key)) {
+        // Check if the corresponding event property is pressed
+        if (!event[eventProperty]) {
+          return false;
+        }
+        modifierFound = true;
+        break;
+      }
+    }
+    if (modifierFound) {
+      continue;
+    }
+
+    // If it's not a modifier, check if it matches the actual key
+    if (!isSameKey(event.key, key)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const isSameKey = (browserEventKey, key) => {
+  browserEventKey = browserEventKey.toLowerCase();
+  key = key.toLowerCase();
+
+  if (browserEventKey === key) {
+    return true;
+  }
+
+  // Check if either key is an alias for the other
+  for (const [canonicalKey, config] of Object.entries(keyMapping)) {
+    const allKeys = [canonicalKey, ...config.alias];
+    if (allKeys.includes(browserEventKey) && allKeys.includes(key)) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const normalizeKey = (key) => {
+  key = key.toLowerCase();
+
+  // Find the canonical form for this key
+  for (const [canonicalKey, config] of Object.entries(keyMapping)) {
+    const allKeys = [canonicalKey, ...config.alias];
+    if (allKeys.includes(key)) {
+      return canonicalKey;
+    }
+  }
+
+  return key;
+};
+
+const normalizeKeyCombination = (combination) => {
+  const lowerCaseCombination = combination.toLowerCase();
+  const keys = lowerCaseCombination.split("+");
+
+  // First normalize keys to their canonical form, then apply ARIA mapping
+  for (let i = 0; i < keys.length; i++) {
+    let key = normalizeKey(keys[i]);
+
+    // Then apply ARIA-specific mappings if they exist
+    if (keyToAriaKeyMapping[key]) {
+      key = keyToAriaKeyMapping[key];
+    }
+
+    keys[i] = key;
+  }
+
+  return keys.join("+");
+};
+
+// http://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts
+const useAriaKeyShortcuts = (key) => {
+  let actualCombination;
+
+  // Handle platform-specific combination objects
+  if (typeof key === "object" && key !== null) {
+    actualCombination = isMac ? key.mac : key.other;
+  } else {
+    actualCombination = key;
+  }
+
+  if (actualCombination) {
+    return normalizeKeyCombination(actualCombination);
+  }
+
+  return "";
+};
+
+const containsPlatformSpecificKeys = (combination) => {
+  const lowerCombination = combination.toLowerCase();
+  const macSpecificKeys = ["command", "cmd"];
+
+  return macSpecificKeys.some((key) => lowerCombination.includes(key));
+};
+
+const generateCrossPlatformCombination = (combination) => {
+  let crossPlatform = combination;
+
+  if (isMac) {
+    // No need to convert anything TO Windows/Linux-specific format since we're on Mac
+    return null;
+  }
+
+  // If not on Mac but combination contains Mac-specific keys, generate Windows equivalent
+  crossPlatform = crossPlatform.replace(/\bcommand\b/gi, "control");
+  crossPlatform = crossPlatform.replace(/\bcmd\b/gi, "control");
+
+  return crossPlatform;
+};

package/src/components/use_action_events.js

@@ -0,0 +1,37 @@
+import { useLayoutEffect } from "preact/hooks";
+import { addManyEventListeners } from "../utils/add_many_event_listeners.js";
+
+export const useActionEvents = (
+  elementRef,
+  {
+    /**
+     * @param {Event} e - L'événement original
+     * @param {"form_reset" | "blur_invalid" | "escape_key"} reason - Raison du cancel
+     */
+    onCancel,
+    onPrevented,
+    onAction,
+    onStart,
+    onAbort,
+    onError,
+    onEnd,
+  },
+) => {
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+
+    return addManyEventListeners(element, {
+      cancel: (e) => {
+        onCancel?.(e, e.detail.reason);
+      },
+      actionprevented: onPrevented,
+      action: onAction,
+      actionstart: onStart,
+      actionabort: onAbort,
+      actionerror: (e) => {
+        onError?.(e.detail.error);
+      },
+      actionend: onEnd,
+    });
+  }, [onCancel, onPrevented, onAction, onStart, onError, onEnd]);
+};

package/src/components/use_auto_focus.js

@@ -0,0 +1,43 @@
+// autoFocus does not work so we focus in a useLayoutEffect,
+// see https://github.com/preactjs/preact/issues/1255
+
+import { useEffect, useLayoutEffect } from "preact/hooks";
+
+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 () => {
+      if (
+        document.activeElement === focusableElement ||
+        document.activeElement === document.body
+      ) {
+        // if the input is focused when the component is unmounted,
+        // we restore focus to the element that was focused before
+        // the input was focused
+        if (document.body.contains(activeElement)) {
+          activeElement.focus();
+        }
+      }
+    };
+  }, []);
+  useEffect(() => {
+    if (autoFocus) {
+      const focusableElement = focusableElementRef.current;
+      focusableElement.scrollIntoView({ inline: "nearest", block: "nearest" });
+    }
+  }, []);
+};

package/src/components/use_debounce_true.js

@@ -0,0 +1,31 @@
+import { useEffect, useRef, useState } from "preact/hooks";
+
+export const useDebounceTrue = (value, delay = 300) => {
+  const [debouncedValue, setDebouncedValue] = useState(false);
+  const timerRef = useRef(null);
+
+  useEffect(() => {
+    // If value becomes true, start a timer
+    if (value) {
+      timerRef.current = setTimeout(() => {
+        setDebouncedValue(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;
+      }
+      setDebouncedValue(false);
+    }
+
+    // Cleanup function
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+};

package/src/components/use_focus_group.js

@@ -0,0 +1,19 @@
+import { initFocusGroup } from "@jsenv/dom";
+import { useLayoutEffect } from "preact/hooks";
+
+export const useFocusGroup = (elementRef, options) => {
+  const { direction, skipTab, loop, name, enabled } = options;
+
+  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

@@ -0,0 +1,104 @@
+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);
+  }
+};
+
+/**
+ * Hook that handles initial value setup and external value synchronization.
+ *
+ * @param {string} name - Parameter name for debugging
+ * @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 value
+ * @param {Function} setValue - Function to call when value needs to be set
+ *
+ * @returns {any} The resolved initial value
+ */
+export const useInitialValue = (
+  name,
+  externalValue,
+  fallbackValue,
+  defaultValue,
+  setValue,
+) => {
+  const initialValue = resolveInitialValue(
+    externalValue,
+    fallbackValue,
+    defaultValue,
+  );
+
+  // Set initial value on mount
+  const mountedRef = useRef(false);
+  if (!mountedRef.current) {
+    mountedRef.current = true;
+    if (name) {
+      setValue(initialValue);
+    }
+  }
+
+  // Use the new sync hook
+  useExternalValueSync(externalValue, defaultValue, setValue, name);
+
+  return initialValue;
+};

package/src/components/use_is_visited.js

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,38 @@
+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]);
+};