@jsenv/navi 0.0.1 → 0.1.0

package/src/components/keyboard_shortcuts/keyboard_key_meta.js

@@ -0,0 +1,17 @@
+import { isMac } from "./os.js";
+
+// Maps canonical browser key names to their user-friendly aliases.
+// Used for both event matching and ARIA normalization.
+export 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"] } }),
+};

package/src/components/keyboard_shortcuts/keyboard_shortcuts.js

@@ -0,0 +1,371 @@
+import { activeElementSignal, canInterceptKeys } from "@jsenv/dom";
+import { effect, signal } from "@preact/signals";
+import { useEffect, useRef } from "preact/hooks";
+
+import { requestAction } from "../../validation/custom_constraint_validation.js";
+import { useAction } from "../action_execution/use_action.js";
+import { useExecuteAction } from "../action_execution/use_execute_action.js";
+import { useActionEvents } from "../field/use_action_events.js";
+import { keyMapping } from "./keyboard_key_meta.js";
+import { isMac } from "./os.js";
+
+export const activeShortcutsSignal = signal([]);
+const shortcutsMap = new Map();
+
+const areShortcutsEqual = (shortcutA, shortcutB) => {
+  return (
+    shortcutA.key === shortcutB.key &&
+    shortcutA.description === shortcutB.description &&
+    shortcutA.enabled === shortcutB.enabled
+  );
+};
+
+const areShortcutArraysEqual = (arrayA, arrayB) => {
+  if (arrayA.length !== arrayB.length) {
+    return false;
+  }
+
+  for (let i = 0; i < arrayA.length; i++) {
+    if (!areShortcutsEqual(arrayA[i], arrayB[i])) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+const updateActiveShortcuts = () => {
+  const activeElement = activeElementSignal.peek();
+  const currentActiveShortcuts = activeShortcutsSignal.peek();
+  const activeShortcuts = [];
+  for (const [element, { shortcuts }] of shortcutsMap) {
+    if (element === activeElement || element.contains(activeElement)) {
+      activeShortcuts.push(...shortcuts);
+    }
+  }
+
+  // Only update if shortcuts have actually changed
+  if (!areShortcutArraysEqual(currentActiveShortcuts, activeShortcuts)) {
+    activeShortcutsSignal.value = activeShortcuts;
+  }
+};
+effect(() => {
+  // eslint-disable-next-line no-unused-expressions
+  activeElementSignal.value;
+  updateActiveShortcuts();
+});
+const addShortcuts = (element, shortcuts) => {
+  shortcutsMap.set(element, { shortcuts });
+  updateActiveShortcuts();
+};
+const removeShortcuts = (element) => {
+  shortcutsMap.delete(element);
+  updateActiveShortcuts();
+};
+
+export const useKeyboardShortcuts = (
+  elementRef,
+  shortcuts,
+  {
+    onActionPrevented,
+    onActionStart,
+    onActionAbort,
+    onActionError,
+    onActionEnd,
+    allowConcurrentActions,
+  } = {},
+) => {
+  if (!elementRef) {
+    throw new Error(
+      "useKeyboardShortcuts requires an elementRef to attach shortcuts to.",
+    );
+  }
+
+  const executeAction = useExecuteAction(elementRef);
+  const shortcutActionIsBusyRef = useRef(false);
+  useActionEvents(elementRef, {
+    actionOrigin: "keyboard_shortcut",
+    onPrevented: onActionPrevented,
+    onAction: (actionEvent) => {
+      const { shortcut } = actionEvent.detail.meta || {};
+      if (!shortcut) {
+        // not a shortcut (an other interaction triggered the action, don't request it again)
+        return;
+      }
+      // 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: document.activeElement,
+      });
+    },
+    onStart: (e) => {
+      const { shortcut } = e.detail.meta || {};
+      if (!shortcut) {
+        return;
+      }
+      if (!allowConcurrentActions) {
+        shortcutActionIsBusyRef.current = true;
+      }
+      shortcut.onStart?.(e);
+      onActionStart?.(e);
+    },
+    onAbort: (e) => {
+      const { shortcut } = e.detail.meta || {};
+      if (!shortcut) {
+        return;
+      }
+      shortcutActionIsBusyRef.current = false;
+      shortcut.onAbort?.(e);
+      onActionAbort?.(e);
+    },
+    onError: (error, e) => {
+      const { shortcut } = e.detail.meta || {};
+      if (!shortcut) {
+        return;
+      }
+      shortcutActionIsBusyRef.current = false;
+      shortcut.onError?.(error, e);
+      onActionError?.(error, e);
+    },
+    onEnd: (e) => {
+      const { shortcut } = e.detail.meta || {};
+      if (!shortcut) {
+        return;
+      }
+      shortcutActionIsBusyRef.current = false;
+      shortcut.onEnd?.(e);
+      onActionEnd?.(e);
+    },
+  });
+
+  const shortcutDeps = [];
+  for (const shortcut of shortcuts) {
+    shortcutDeps.push(
+      shortcut.key,
+      shortcut.description,
+      shortcut.enabled,
+      shortcut.confirmMessage,
+    );
+    shortcut.action = useAction(shortcut.action);
+  }
+
+  useEffect(() => {
+    const element = elementRef.current;
+    const shortcutsCopy = [];
+    for (const shortcutCandidate of shortcuts) {
+      shortcutsCopy.push({
+        ...shortcutCandidate,
+        handler: (keyboardEvent) => {
+          if (shortcutCandidate.handler) {
+            return shortcutCandidate.handler(keyboardEvent);
+          }
+          if (shortcutActionIsBusyRef.current) {
+            return false;
+          }
+          const { action } = shortcutCandidate;
+          return requestAction(element, action, {
+            event: keyboardEvent,
+            requester: document.activeElement,
+            confirmMessage: shortcutCandidate.confirmMessage,
+            actionOrigin: "keyboard_shortcut",
+            meta: {
+              shortcut: shortcutCandidate,
+            },
+          });
+        },
+      });
+    }
+
+    addShortcuts(element, shortcuts);
+
+    const onKeydown = (event) => {
+      applyKeyboardShortcuts(shortcutsCopy, event);
+    };
+    element.addEventListener("keydown", onKeydown);
+    return () => {
+      element.removeEventListener("keydown", onKeydown);
+      removeShortcuts(element);
+    };
+  }, [shortcutDeps]);
+};
+
+const applyKeyboardShortcuts = (shortcuts, keyboardEvent) => {
+  if (!canInterceptKeys(keyboardEvent)) {
+    return null;
+  }
+  for (const shortcutCandidate of shortcuts) {
+    let { enabled = true, key } = shortcutCandidate;
+    if (!enabled) {
+      continue;
+    }
+
+    if (typeof key === "function") {
+      const keyReturnValue = key(keyboardEvent);
+      if (!keyReturnValue) {
+        continue;
+      }
+      key = keyReturnValue;
+    }
+    if (!key) {
+      console.error(shortcutCandidate);
+      throw new TypeError(`key is required in keyboard shortcut, got ${key}`);
+    }
+
+    // Handle platform-specific combination objects
+    let actualCombination;
+    let crossPlatformCombination;
+    if (typeof key === "object" && key !== null) {
+      actualCombination = isMac ? key.mac : key.other;
+    } else {
+      actualCombination = key;
+      if (containsPlatformSpecificKeys(key)) {
+        crossPlatformCombination = generateCrossPlatformCombination(key);
+      }
+    }
+
+    // Check both the actual combination and cross-platform combination
+    const matchesActual =
+      actualCombination &&
+      keyboardEventIsMatchingKeyCombination(keyboardEvent, actualCombination);
+    const matchesCrossPlatform =
+      crossPlatformCombination &&
+      crossPlatformCombination !== actualCombination &&
+      keyboardEventIsMatchingKeyCombination(
+        keyboardEvent,
+        crossPlatformCombination,
+      );
+
+    if (!matchesActual && !matchesCrossPlatform) {
+      continue;
+    }
+    if (typeof enabled === "function" && !enabled(keyboardEvent)) {
+      continue;
+    }
+    const returnValue = shortcutCandidate.handler(keyboardEvent);
+    if (returnValue) {
+      keyboardEvent.preventDefault();
+    }
+    return shortcutCandidate;
+  }
+  return null;
+};
+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;
+};
+const keyboardEventIsMatchingKeyCombination = (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;
+    }
+
+    // Check if it's a range pattern like "a-z" or "0-9"
+    if (key.includes("-") && key.length === 3) {
+      const [startChar, dash, endChar] = key;
+      if (dash === "-") {
+        // Only check ranges for single alphanumeric characters
+        const eventKey = event.key.toLowerCase();
+        if (eventKey.length !== 1) {
+          return false; // Not a single character key
+        }
+
+        // Only allow a-z and 0-9 ranges
+        const isValidRange =
+          (startChar >= "a" && endChar <= "z") ||
+          (startChar >= "0" && endChar <= "9");
+
+        if (!isValidRange) {
+          return false; // Invalid range pattern
+        }
+
+        const eventKeyCode = eventKey.charCodeAt(0);
+        const startCode = startChar.charCodeAt(0);
+        const endCode = endChar.charCodeAt(0);
+
+        if (eventKeyCode >= startCode && eventKeyCode <= endCode) {
+          continue; // Range matched
+        }
+        return false; // Range not matched
+      }
+    }
+
+    // If it's not a modifier or range, check if it matches the actual key
+    if (!isSameKey(event.key, key)) {
+      return false;
+    }
+  }
+  return true;
+};
+// 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"],
+  },
+};
+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;
+};

package/src/components/link/link.jsx

@@ -1,20 +1,22 @@
-import { closeValidationMessage, useConstraints } from "@jsenv/validation";
 import { forwardRef } from "preact/compat";
-import { useImperativeHandle, useLayoutEffect, useRef } from "preact/hooks";
+import {
+  useContext,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+} from "preact/hooks";
+
 import { useIsVisited } from "../../browser_integration/use_is_visited.js";
-import { useActionStatus } from "../../use_action_status.js";
+import { closeValidationMessage } from "../../validation/custom_constraint_validation.js";
+import { useConstraints } from "../../validation/hooks/use_constraints.js";
 import { renderActionableComponent } from "../action_execution/render_actionable_component.jsx";
-import { LoaderBackground } from "../loader/loader_background.jsx";
+import { useRequestedActionStatus } from "../field/use_action_events.js";
+import { useKeyboardShortcuts } from "../keyboard_shortcuts/keyboard_shortcuts.js";
+import { LoadableInlineElement } from "../loader/loader_background.jsx";
 import {
-  clickToSelect,
-  keydownToSelect,
-  useRegisterSelectionValue,
-  useSelectionContext,
-} from "../selection/selection_context.jsx";
-import {
-  ShortcutProvider,
-  useShortcutContext,
-} from "../shortcut/shortcut_context.jsx";
+  SelectionContext,
+  useSelectableElement,
+} from "../selection/selection.jsx";
 import { useAutoFocus } from "../use_auto_focus.js";
 
 /*
@@ -45,17 +47,17 @@ import.meta.css = /* css */ `
     pointer-events: none;
   }
 
-  .navi_link[data-with-selection] {
+  .navi_link[aria-selected] {
     position: relative;
   }
 
-  .navi_link[data-with-selection] input[type="checkbox"] {
+  .navi_link[aria-selected] input[type="checkbox"] {
     position: absolute;
     opacity: 0;
   }
 
   /* Visual feedback for selected state */
-  .navi_link[data-selected] {
+  .navi_link[aria-selected="true"] {
     background-color: light-dark(#bbdefb, #2563eb);
   }
 
@@ -66,6 +68,10 @@ import.meta.css = /* css */ `
   .navi_link[data-visited] {
     color: light-dark(#6a1b9a, #ab47bc);
   }
+
+  .navi_link[data-no-text-decoration] {
+    text-decoration: none;
+  }
 `;
 
 export const Link = forwardRef((props, ref) => {
@@ -76,20 +82,12 @@ export const Link = forwardRef((props, ref) => {
 });
 
 const LinkBasic = forwardRef((props, ref) => {
-  const selectionContext = useSelectionContext();
-
+  const selectionContext = useContext(SelectionContext);
   if (selectionContext) {
-    return (
-      <LinkWithSelection
-        ref={ref}
-        selectionContext={selectionContext}
-        {...props}
-      />
-    );
+    return <LinkWithSelection ref={ref} {...props} />;
   }
   return <LinkPlain ref={ref} {...props} />;
 });
-
 const LinkPlain = forwardRef((props, ref) => {
   const {
     className = "",
@@ -107,24 +105,24 @@ const LinkPlain = forwardRef((props, ref) => {
     href,
     ...rest
   } = props;
-
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
+  const isVisited = useIsVisited(href);
 
   useAutoFocus(innerRef, autoFocus);
   useConstraints(innerRef, constraints);
-
   const shouldDimColor = readOnly || disabled;
   useDimColorWhen(innerRef, shouldDimColor);
 
-  const isVisited = useIsVisited(href);
-
   return (
-    <LoaderBackground loading={loading} color="light-dark(#355fcc, #3b82f6)">
+    <LoadableInlineElement
+      loading={loading}
+      color="light-dark(#355fcc, #3b82f6)"
+    >
       <a
         {...rest}
-        href={href}
         ref={innerRef}
+        href={href}
         className={["navi_link", ...className.split(" ")].join(" ")}
         aria-busy={loading}
         inert={disabled}
@@ -152,48 +150,26 @@ const LinkPlain = forwardRef((props, ref) => {
       >
         {children}
       </a>
-    </LoaderBackground>
+    </LoadableInlineElement>
   );
 });
-
 const LinkWithSelection = forwardRef((props, ref) => {
-  const {
-    selectionContext,
-    name,
-    value,
-    children,
-    onClick,
-    onKeyDown,
-    ...rest
-  } = props;
-  const isSelected = selectionContext.isSelected(value);
-  useRegisterSelectionValue(value);
+  const { selection, selectionController } = useContext(SelectionContext);
+  const { value = props.href, children, ...rest } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+  const { selected } = useSelectableElement(innerRef, {
+    selection,
+    selectionController,
+  });
 
   return (
     <LinkPlain
-      ref={ref}
       {...rest}
-      onClick={(e) => {
-        clickToSelect(e, { selectionContext, value });
-        onClick?.(e);
-      }}
-      onKeyDown={(e) => {
-        keydownToSelect(e, { selectionContext, value });
-        onKeyDown?.(e);
-      }}
-      data-with-selection=""
-      data-selected={isSelected ? "" : undefined}
+      ref={innerRef}
+      data-value={value}
+      aria-selected={selected}
     >
-      <input
-        className="navi_link_checkbox"
-        type="checkbox"
-        name={name}
-        value={value}
-        checked={isSelected}
-        // Prevent direct checkbox interaction - only via link clicks or keyboard nav (arrows)
-        disabled
-        tabIndex={-1} // Don't interfere with link tab order (might be overkill because there is already [disabled])
-      />
       {children}
     </LinkPlain>
   );
@@ -239,53 +215,40 @@ const useDimColorWhen = (elementRef, shouldDim) => {
 const LinkWithAction = forwardRef((props, ref) => {
   const {
     shortcuts = [],
+    readOnly,
     onActionPrevented,
     onActionStart,
     onActionAbort,
     onActionError,
     onActionEnd,
+    children,
+    loading,
     ...rest
   } = props;
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
+  const { actionPending } = useRequestedActionStatus(innerRef);
+  const innerLoading = Boolean(loading || actionPending);
 
-  return (
-    <ShortcutProvider
-      shortcuts={shortcuts}
-      elementRef={innerRef}
-      onActionPrevented={onActionPrevented}
-      onActionStart={onActionStart}
-      onActionAbort={onActionAbort}
-      onActionError={onActionError}
-      onActionEnd={onActionEnd}
-    >
-      <LinkWithShortcuts ref={innerRef} {...rest} />
-    </ShortcutProvider>
-  );
-});
-
-const LinkWithShortcuts = forwardRef((props, ref) => {
-  const { children, readOnly, loading, ...rest } = props;
-  const innerRef = useRef();
-  useImperativeHandle(ref, () => innerRef.current);
-  const { shortcutAction } = useShortcutContext();
-
-  const { loading: actionLoading } = useActionStatus(shortcutAction);
-  const innerLoading = Boolean(loading || actionLoading);
+  useKeyboardShortcuts(innerRef, shortcuts, {
+    onActionPrevented,
+    onActionStart,
+    onActionAbort,
+    onActionError,
+    onActionEnd,
+  });
 
   return (
-    <>
-      <LinkBasic
-        ref={innerRef}
-        {...rest}
-        loading={innerLoading}
-        readOnly={readOnly || actionLoading}
-        data-readonly-silent={actionLoading && !readOnly ? "" : undefined}
-        /* When we have keyboard shortcuts the link outline is visible on focus (not solely on focus-visible) */
-        data-focus-visible=""
-      >
-        {children}
-      </LinkBasic>
-    </>
+    <LinkBasic
+      {...rest}
+      ref={innerRef}
+      loading={innerLoading}
+      readOnly={readOnly || actionPending}
+      data-readonly-silent={actionPending && !readOnly ? "" : undefined}
+      /* When we have keyboard shortcuts the link outline is visible on focus (not solely on focus-visible) */
+      data-focus-visible=""
+    >
+      {children}
+    </LinkBasic>
   );
 });

package/src/components/link/link_with_icon.jsx

@@ -0,0 +1,52 @@
+import { FontSizedSvg } from "../svg/font_sized_svg.jsx";
+import { Link } from "./link.jsx";
+
+import.meta.css = /* css */ `
+  .link_with_icon {
+    white-space: nowrap;
+    align-items: center;
+    gap: 0.3em;
+    min-width: 0;
+    display: inline-flex;
+    flex-grow: 1;
+  }
+`;
+
+export const LinkWithIcon = ({
+  icon,
+  isCurrent,
+  children,
+  className = "",
+  ...rest
+}) => {
+  return (
+    <Link
+      className={["link_with_icon", ...className.split(" ")].join(" ")}
+      {...rest}
+    >
+      <FontSizedSvg>{icon}</FontSizedSvg>
+      {isCurrent && (
+        <FontSizedSvg>
+          <CurrentSvg />
+        </FontSizedSvg>
+      )}
+      {children}
+    </Link>
+  );
+};
+
+const CurrentSvg = () => {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      width="100%"
+      height="100%"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="m 8 0 c -3.3125 0 -6 2.6875 -6 6 c 0.007812 0.710938 0.136719 1.414062 0.386719 2.078125 l -0.015625 -0.003906 c 0.636718 1.988281 3.78125 5.082031 5.625 6.929687 h 0.003906 v -0.003906 c 1.507812 -1.507812 3.878906 -3.925781 5.046875 -5.753906 c 0.261719 -0.414063 0.46875 -0.808594 0.585937 -1.171875 l -0.019531 0.003906 c 0.25 -0.664063 0.382813 -1.367187 0.386719 -2.078125 c 0 -3.3125 -2.683594 -6 -6 -6 z m 0 3.691406 c 1.273438 0 2.308594 1.035156 2.308594 2.308594 s -1.035156 2.308594 -2.308594 2.308594 c -1.273438 -0.003906 -2.304688 -1.035156 -2.304688 -2.308594 c -0.003906 -1.273438 1.03125 -2.304688 2.304688 -2.308594 z m 0 0"
+        fill="#2e3436"
+      />
+    </svg>
+  );
+};