@jsenv/navi 0.0.1 → 0.1.1

package/src/components/selection/selection_context.jsx

@@ -1,262 +0,0 @@
-import { canInterceptKeys } from "@jsenv/dom";
-import { createContext } from "preact";
-import { useContext, useLayoutEffect, useRef } from "preact/hooks";
-
-const SelectionContext = createContext(null);
-
-export const SelectionProvider = ({ value = [], onChange, children }) => {
-  const selection = value || [];
-  const registryRef = useRef([]); // Array<value>
-  const anchorRef = useRef(null);
-
-  const contextValue = {
-    selection,
-
-    register: (value) => {
-      const registry = registryRef.current;
-      const existingIndex = registry.indexOf(value);
-      if (existingIndex >= 0) {
-        console.warn(
-          `SelectionContext: Attempted to register an already registered value: ${value}. All values must be unique.`,
-        );
-        return;
-      }
-      registry.push(value);
-    },
-    unregister: (value) => {
-      const registry = registryRef.current;
-      const index = registry.indexOf(value);
-      if (index >= 0) {
-        registry.splice(index, 1);
-      }
-    },
-    setAnchor: (value) => {
-      anchorRef.current = value;
-    },
-    isSelected: (itemValue) => {
-      return selection.includes(itemValue);
-    },
-    getAllItems: () => {
-      return registryRef.current;
-    },
-    getRange: (fromValue, toValue) => {
-      const registry = registryRef.current;
-
-      // Find indices of fromValue and toValue
-      let fromIndex = -1;
-      let toIndex = -1;
-      let index = 0;
-      for (const valueCandidate of registry) {
-        if (valueCandidate === fromValue) {
-          fromIndex = index;
-        }
-        if (valueCandidate === toValue) {
-          toIndex = index;
-        }
-        index++;
-      }
-
-      if (fromIndex >= 0 && toIndex >= 0) {
-        // Select all items between fromIndex and toIndex (inclusive)
-        const start = Math.min(fromIndex, toIndex);
-        const end = Math.max(fromIndex, toIndex);
-        const valueInRangeArray = registry.slice(start, end + 1);
-        return valueInRangeArray;
-      }
-      return [];
-    },
-
-    // basic methods to manipulate selection
-    set: (newSelection, event = null) => {
-      if (
-        newSelection.length === selection.length &&
-        newSelection.every((value, index) => value === selection[index])
-      ) {
-        return;
-      }
-      onChange?.(newSelection, event);
-    },
-    add: (arrayOfValueToAddToSelection, event = null) => {
-      const selectionWithValues = [];
-      for (const value of selection) {
-        selectionWithValues.push(value);
-      }
-      let modified = false;
-      for (const valueToAdd of arrayOfValueToAddToSelection) {
-        if (selectionWithValues.includes(valueToAdd)) {
-          continue;
-        }
-        modified = true;
-        selectionWithValues.push(valueToAdd);
-      }
-      if (modified) {
-        onChange?.(selectionWithValues, event);
-      }
-    },
-    remove: (arrayOfValueToRemoveFromSelection, event = null) => {
-      let modified = false;
-      const selectionWithoutValues = [];
-      for (const value of selection) {
-        if (arrayOfValueToRemoveFromSelection.includes(value)) {
-          modified = true;
-          // If we're removing the last selected value, clear it
-          if (value === anchorRef.current) {
-            anchorRef.current = null;
-          }
-        } else {
-          selectionWithoutValues.push(value);
-        }
-      }
-
-      if (modified) {
-        onChange?.(selectionWithoutValues, event);
-      }
-    },
-
-    // Convenience method for multi-select: toggle, addFromLastSelectedTo
-    toggle: (value, event = null) => {
-      if (selection.includes(value)) {
-        contextValue.remove([value], event);
-      } else {
-        contextValue.add([value], event);
-      }
-    },
-    // Convenience method for shift-click: add range from last selected to target value
-    setFromAnchorTo: (value, event = null) => {
-      const anchorValue = anchorRef.current;
-
-      // Make sure the last selected value is still in the current selection
-      if (anchorValue && selection.includes(anchorValue)) {
-        const range = contextValue.getRange(anchorValue, value);
-        contextValue.set(range, event);
-      } else {
-        // No valid previous selection, just select this one
-        contextValue.set([value], event);
-      }
-    },
-
-    getValueAfter: (value) => {
-      const registry = registryRef.current;
-      const index = registry.indexOf(value);
-      if (index < 0 || index >= registry.length - 1) {
-        return null; // No next value
-      }
-      return registry[index + 1];
-    },
-    getValueBefore: (value) => {
-      const registry = registryRef.current;
-      const index = registry.indexOf(value);
-      if (index <= 0) {
-        return null; // No previous value
-      }
-      return registry[index - 1];
-    },
-  };
-
-  return (
-    <SelectionContext.Provider value={contextValue}>
-      {children}
-    </SelectionContext.Provider>
-  );
-};
-
-export const useSelectionContext = () => {
-  return useContext(SelectionContext);
-};
-
-export const useRegisterSelectionValue = (value) => {
-  const selectionContext = useSelectionContext();
-
-  useLayoutEffect(() => {
-    if (selectionContext) {
-      selectionContext.register(value);
-      return () => selectionContext.unregister(value);
-    }
-    return undefined;
-  }, [selectionContext, value]);
-};
-
-export const clickToSelect = (clickEvent, { selectionContext, value }) => {
-  if (clickEvent.defaultPrevented) {
-    // If the click was prevented by another handler, do not interfere
-    return;
-  }
-
-  const isMultiSelect = clickEvent.metaKey || clickEvent.ctrlKey;
-  const isShiftSelect = clickEvent.shiftKey;
-  const isSingleSelect = !isMultiSelect && !isShiftSelect;
-
-  if (isSingleSelect) {
-    // Single select - replace entire selection with just this item
-    selectionContext.set([value], clickEvent);
-    return;
-  }
-  if (isMultiSelect) {
-    // here no need to prevent nav on <a> but it means cmd + click will both multi select
-    // and open in a new tab
-    selectionContext.toggle(value, clickEvent);
-    return;
-  }
-  if (isShiftSelect) {
-    clickEvent.preventDefault(); // Prevent navigation
-    selectionContext.setFromAnchorTo(value, clickEvent);
-    return;
-  }
-};
-
-export const keydownToSelect = (keydownEvent, { selectionContext, value }) => {
-  if (!canInterceptKeys(keydownEvent)) {
-    return;
-  }
-
-  if (keydownEvent.key === "Shift") {
-    selectionContext.setAnchor(value);
-    return;
-  }
-
-  const isMultiSelect = keydownEvent.metaKey || keydownEvent.ctrlKey;
-  const isShiftSelect = keydownEvent.shiftKey;
-  const { key } = keydownEvent;
-  if (key === "a") {
-    if (!isMultiSelect) {
-      return;
-    }
-    keydownEvent.preventDefault(); // prevent default select all text behavior
-    selectionContext.set(selectionContext.getAllItems(), keydownEvent);
-    return;
-  }
-  if (key === "ArrowDown") {
-    const nextValue = selectionContext.getValueAfter(value);
-    if (!nextValue) {
-      return; // No next value to select
-    }
-    keydownEvent.preventDefault(); // Prevent default scrolling behavior
-    if (isShiftSelect) {
-      selectionContext.setFromAnchorTo(nextValue, keydownEvent);
-      return;
-    }
-    if (isMultiSelect) {
-      selectionContext.add([nextValue], keydownEvent);
-      return;
-    }
-    selectionContext.set([nextValue], keydownEvent);
-    return;
-  }
-  if (key === "ArrowUp") {
-    const previousValue = selectionContext.getValueBefore(value);
-    if (!previousValue) {
-      return; // No previous value to select
-    }
-    keydownEvent.preventDefault(); // Prevent default scrolling behavior
-    if (isShiftSelect) {
-      selectionContext.setFromAnchorTo(previousValue, keydownEvent);
-      return;
-    }
-    if (isMultiSelect) {
-      selectionContext.add([previousValue], keydownEvent);
-      return;
-    }
-    selectionContext.set([previousValue], keydownEvent);
-    return;
-  }
-};

package/src/components/shortcut/shortcut_context.jsx

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

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