@jsenv/navi 0.0.1

package/src/components/link/link.jsx

@@ -0,0 +1,291 @@
+import { closeValidationMessage, useConstraints } from "@jsenv/validation";
+import { forwardRef } from "preact/compat";
+import { useImperativeHandle, useLayoutEffect, useRef } from "preact/hooks";
+import { useIsVisited } from "../../browser_integration/use_is_visited.js";
+import { useActionStatus } from "../../use_action_status.js";
+import { renderActionableComponent } from "../action_execution/render_actionable_component.jsx";
+import { LoaderBackground } from "../loader/loader_background.jsx";
+import {
+  clickToSelect,
+  keydownToSelect,
+  useRegisterSelectionValue,
+  useSelectionContext,
+} from "../selection/selection_context.jsx";
+import {
+  ShortcutProvider,
+  useShortcutContext,
+} from "../shortcut/shortcut_context.jsx";
+import { useAutoFocus } from "../use_auto_focus.js";
+
+/*
+ * Apply opacity to child content, not the link element itself.
+ *
+ * Why not apply opacity directly to .navi_link?
+ * - Would make focus outlines semi-transparent too (accessibility issue)
+ * - We want dimmed text but full-opacity focus indicators for visibility
+ *
+ * This approach dims the content while preserving focus outline visibility.
+ */
+import.meta.css = /* css */ `
+  .navi_link {
+    border-radius: 2px;
+  }
+
+  .navi_link:focus {
+    position: relative;
+    z-index: 1; /* Ensure focus outline is above other elements */
+  }
+
+  .navi_link[data-readonly] > *,
+  .navi_link[inert] > * {
+    opacity: 0.5;
+  }
+
+  .navi_link[inert] {
+    pointer-events: none;
+  }
+
+  .navi_link[data-with-selection] {
+    position: relative;
+  }
+
+  .navi_link[data-with-selection] input[type="checkbox"] {
+    position: absolute;
+    opacity: 0;
+  }
+
+  /* Visual feedback for selected state */
+  .navi_link[data-selected] {
+    background-color: light-dark(#bbdefb, #2563eb);
+  }
+
+  .navi_link[data-active] {
+    font-weight: bold;
+  }
+
+  .navi_link[data-visited] {
+    color: light-dark(#6a1b9a, #ab47bc);
+  }
+`;
+
+export const Link = forwardRef((props, ref) => {
+  return renderActionableComponent(props, ref, {
+    Basic: LinkBasic,
+    WithAction: LinkWithAction,
+  });
+});
+
+const LinkBasic = forwardRef((props, ref) => {
+  const selectionContext = useSelectionContext();
+
+  if (selectionContext) {
+    return (
+      <LinkWithSelection
+        ref={ref}
+        selectionContext={selectionContext}
+        {...props}
+      />
+    );
+  }
+  return <LinkPlain ref={ref} {...props} />;
+});
+
+const LinkPlain = forwardRef((props, ref) => {
+  const {
+    className = "",
+    loading,
+    readOnly,
+    disabled,
+    children,
+    autoFocus,
+    active,
+    visited,
+    spaceToClick = true,
+    constraints = [],
+    onClick,
+    onKeyDown,
+    href,
+    ...rest
+  } = props;
+
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  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)">
+      <a
+        {...rest}
+        href={href}
+        ref={innerRef}
+        className={["navi_link", ...className.split(" ")].join(" ")}
+        aria-busy={loading}
+        inert={disabled}
+        data-field=""
+        data-readonly={readOnly ? "" : undefined}
+        data-active={active ? "" : undefined}
+        data-visited={visited || isVisited ? "" : undefined}
+        onClick={(e) => {
+          closeValidationMessage(e.target, "click");
+          if (readOnly) {
+            e.preventDefault();
+            return;
+          }
+          onClick?.(e);
+        }}
+        onKeyDown={(e) => {
+          if (spaceToClick && e.key === " ") {
+            e.preventDefault(); // Prevent page scroll
+            if (!readOnly && !disabled) {
+              e.target.click();
+            }
+          }
+          onKeyDown?.(e);
+        }}
+      >
+        {children}
+      </a>
+    </LoaderBackground>
+  );
+});
+
+const LinkWithSelection = forwardRef((props, ref) => {
+  const {
+    selectionContext,
+    name,
+    value,
+    children,
+    onClick,
+    onKeyDown,
+    ...rest
+  } = props;
+  const isSelected = selectionContext.isSelected(value);
+  useRegisterSelectionValue(value);
+
+  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}
+    >
+      <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>
+  );
+});
+
+/*
+ * Custom hook to apply semi-transparent color when an element should be dimmed.
+ *
+ * Why we do it this way:
+ * 1. **Precise timing**: Captures the element's natural color exactly when transitioning
+ *    from normal to dimmed state (not before, not after)
+ * 2. **Avoids CSS inheritance issues**: CSS `currentColor` and `color-mix()` don't work
+ *    reliably for creating true transparency that matches `opacity: 0.5`
+ * 3. **Performance**: Only executes when the dimmed state actually changes, not on every render
+ * 4. **Color accuracy**: Uses `color(from ... / 0.5)` syntax to preserve the exact visual
+ *    appearance of `opacity: 0.5` but applied only to color
+ * 5. **Works with any color**: Handles default blue, visited purple, inherited colors, etc.
+ * 6. **Maintains focus outline**: Since we only dim the text color, focus outlines remain
+ *    fully visible for accessibility
+ */
+const useDimColorWhen = (elementRef, shouldDim) => {
+  const shouldDimPreviousRef = useRef();
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+    const shouldDimPrevious = shouldDimPreviousRef.current;
+
+    if (shouldDim === shouldDimPrevious) {
+      return;
+    }
+    shouldDimPreviousRef.current = shouldDim;
+    if (shouldDim) {
+      // Capture color just before applying disabled state
+      const computedStyle = getComputedStyle(element);
+      const currentColor = computedStyle.color;
+      element.style.color = `color(from ${currentColor} srgb r g b / 0.5)`;
+    } else {
+      // Clear the inline style to let CSS take over
+      element.style.color = "";
+    }
+  });
+};
+
+const LinkWithAction = forwardRef((props, ref) => {
+  const {
+    shortcuts = [],
+    onActionPrevented,
+    onActionStart,
+    onActionAbort,
+    onActionError,
+    onActionEnd,
+    ...rest
+  } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  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);
+
+  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>
+    </>
+  );
+});

package/src/components/loader/loader_background.jsx

@@ -0,0 +1,324 @@
+import { resolveCSSSize } from "@jsenv/dom";
+import { createPortal } from "preact/compat";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
+import { useDebounceTrue } from "../use_debounce_true.js";
+import { RectangleLoading } from "./rectangle_loading.jsx";
+
+import.meta.css = /* css */ `
+  [name="element_with_loader_wrapper"] {
+    display: inline-flex;
+    position: relative;
+    width: fit-content;
+  }
+
+  [name="loading_rectangle_wrapper"] {
+    pointer-events: none;
+    position: absolute;
+    z-index: 1;
+  }
+
+  [name="rectangle_loading"] {
+    position: relative;
+    width: 100%;
+    height: 100%;
+  }
+`;
+
+export const LoaderBackground = ({
+  loading,
+  containerRef,
+  targetSelector,
+  color,
+  inset = 0,
+  spacingTop = 0,
+  spacingLeft = 0,
+  spacingBottom = 0,
+  spacingRight = 0,
+  children,
+}) => {
+  if (containerRef) {
+    const container = containerRef.current;
+    if (!container) {
+      return children;
+    }
+    return createPortal(
+      <LoaderBackgroundWithPortal
+        container={container}
+        loading={loading}
+        color={color}
+        inset={inset}
+        spacingTop={spacingTop}
+        spacingLeft={spacingLeft}
+        spacingBottom={spacingBottom}
+        spacingRight={spacingRight}
+      >
+        {children}
+      </LoaderBackgroundWithPortal>,
+      container,
+    );
+  }
+
+  return (
+    <LoaderBackgroundWithWrapper
+      targetSelector={targetSelector}
+      loading={loading}
+      color={color}
+      inset={inset}
+      spacingTop={spacingTop}
+      spacingLeft={spacingLeft}
+      spacingBottom={spacingBottom}
+      spacingRight={spacingRight}
+    >
+      {children}
+    </LoaderBackgroundWithWrapper>
+  );
+};
+
+const LoaderBackgroundWithPortal = ({
+  container,
+  loading,
+  color,
+  inset,
+  spacingTop,
+  spacingLeft,
+  spacingBottom,
+  spacingRight,
+  children,
+}) => {
+  const shouldShowSpinner = useDebounceTrue(loading, 300);
+
+  if (!shouldShowSpinner) {
+    return children;
+  }
+
+  container.style.position = "relative";
+  let paddingTop = 0;
+  if (container.nodeName === "DETAILS") {
+    paddingTop = container.querySelector("summary").offsetHeight;
+  }
+
+  return (
+    <>
+      <div
+        style={{
+          position: "absolute",
+          top: `${inset + paddingTop + spacingTop}px`,
+          bottom: `${inset + spacingBottom}px`,
+          left: `${inset + spacingLeft}px`,
+          right: `${inset + spacingRight}px`,
+        }}
+      >
+        {shouldShowSpinner && <RectangleLoading color={color} />}
+      </div>
+      {children}
+    </>
+  );
+};
+
+const LoaderBackgroundWithWrapper = ({
+  loading,
+  targetSelector,
+  color,
+  spacingTop,
+  spacingLeft,
+  spacingBottom,
+  spacingRight,
+  inset,
+  children,
+}) => {
+  const shouldShowSpinner = useDebounceTrue(loading, 300);
+  const containerRef = useRef(null);
+  const [outlineOffset, setOutlineOffset] = useState(0);
+  const [borderRadius, setBorderRadius] = useState(0);
+  const [borderTopWidth, setBorderTopWidth] = useState(0);
+  const [borderLeftWidth, setBorderLeftWidth] = useState(0);
+  const [borderRightWidth, setBorderRightWidth] = useState(0);
+  const [borderBottomWidth, setBorderBottomWidth] = useState(0);
+  const [marginTop, setMarginTop] = useState(0);
+  const [marginBottom, setMarginBottom] = useState(0);
+  const [marginLeft, setMarginLeft] = useState(0);
+  const [marginRight, setMarginRight] = useState(0);
+  const [paddingTop, setPaddingTop] = useState(0);
+  const [paddingLeft, setPaddingLeft] = useState(0);
+  const [paddingRight, setPaddingRight] = useState(0);
+  const [paddingBottom, setPaddingBottom] = useState(0);
+  const [flexGrow, setFlexGrow] = useState(0);
+  const [flexShrink, setFlexShrink] = useState(1);
+  const [flexBasis, setFlexBasis] = useState("auto");
+
+  const [currentColor, setCurrentColor] = useState(color);
+
+  useLayoutEffect(() => {
+    let animationFrame;
+    const updateStyles = () => {
+      const container = containerRef.current;
+      const containedElement = container.lastElementChild;
+      const target = targetSelector
+        ? container.querySelector(targetSelector)
+        : containedElement;
+      if (target) {
+        const { width, height } = target.getBoundingClientRect();
+
+        const containedComputedStyle =
+          window.getComputedStyle(containedElement);
+        const targetComputedStyle = window.getComputedStyle(target);
+
+        // Read flex properties from the contained element to mirror its behavior
+        const newFlexGrow = containedComputedStyle.flexGrow || "0";
+        const newFlexShrink = containedComputedStyle.flexShrink || "1";
+        const newFlexBasis = containedComputedStyle.flexBasis || "auto";
+
+        const newBorderTopWidth = resolveCSSSize(
+          targetComputedStyle.borderTopWidth,
+        );
+        const newBorderLeftWidth = resolveCSSSize(
+          targetComputedStyle.borderLeftWidth,
+        );
+        const newBorderRightWidth = resolveCSSSize(
+          targetComputedStyle.borderRightWidth,
+        );
+        const newBorderBottomWidth = resolveCSSSize(
+          targetComputedStyle.borderBottomWidth,
+        );
+        const newBorderRadius = resolveCSSSize(
+          targetComputedStyle.borderRadius,
+          {
+            availableSize: Math.min(width, height),
+          },
+        );
+        const newOutlineColor = targetComputedStyle.outlineColor;
+        const newBorderColor = targetComputedStyle.borderColor;
+        const newDetectedColor = targetComputedStyle.color;
+        const newOutlineOffset = resolveCSSSize(
+          targetComputedStyle.outlineOffset,
+        );
+        const newMarginTop = resolveCSSSize(targetComputedStyle.marginTop);
+        const newMarginBottom = resolveCSSSize(
+          targetComputedStyle.marginBottom,
+        );
+        const newMarginLeft = resolveCSSSize(targetComputedStyle.marginLeft);
+        const newMarginRight = resolveCSSSize(targetComputedStyle.marginRight);
+
+        const paddingTop = resolveCSSSize(containedComputedStyle.paddingTop);
+        const paddingLeft = resolveCSSSize(containedComputedStyle.paddingLeft);
+        const paddingRight = resolveCSSSize(
+          containedComputedStyle.paddingRight,
+        );
+        const paddingBottom = resolveCSSSize(
+          containedComputedStyle.paddingBottom,
+        );
+
+        setBorderTopWidth(newBorderTopWidth);
+        setBorderLeftWidth(newBorderLeftWidth);
+        setBorderRightWidth(newBorderRightWidth);
+        setBorderBottomWidth(newBorderBottomWidth);
+        setBorderRadius(newBorderRadius);
+        setOutlineOffset(newOutlineOffset);
+        setMarginTop(newMarginTop);
+        setMarginBottom(newMarginBottom);
+        setMarginLeft(newMarginLeft);
+        setMarginRight(newMarginRight);
+        setPaddingTop(paddingTop);
+        setPaddingLeft(paddingLeft);
+        setPaddingRight(paddingRight);
+        setPaddingBottom(paddingBottom);
+        setFlexGrow(newFlexGrow);
+        setFlexShrink(newFlexShrink);
+        setFlexBasis(newFlexBasis);
+
+        if (color) {
+          setCurrentColor(color);
+        } else if (
+          newOutlineColor &&
+          newOutlineColor !== "rgba(0, 0, 0, 0)" &&
+          (document.activeElement === containedElement ||
+            newBorderColor === "rgba(0, 0, 0, 0)")
+        ) {
+          setCurrentColor(newOutlineColor);
+        } else if (newBorderColor && newBorderColor !== "rgba(0, 0, 0, 0)") {
+          setCurrentColor(newBorderColor);
+        } else {
+          setCurrentColor(newDetectedColor);
+        }
+      }
+
+      // updateStyles is very cheap so we run it every frame
+      animationFrame = requestAnimationFrame(updateStyles);
+    };
+    updateStyles();
+
+    return () => {
+      cancelAnimationFrame(animationFrame);
+    };
+  }, [color, targetSelector]);
+
+  spacingTop += inset;
+  spacingTop += outlineOffset;
+  spacingTop -= borderTopWidth;
+  spacingTop += marginTop;
+  spacingLeft += inset;
+  spacingLeft += outlineOffset;
+  spacingLeft -= borderLeftWidth;
+  spacingLeft += marginLeft;
+  spacingRight += inset;
+  spacingRight += outlineOffset;
+  spacingRight -= borderRightWidth;
+  spacingRight += marginRight;
+  spacingBottom += inset;
+  spacingBottom += outlineOffset;
+  spacingBottom -= borderBottomWidth;
+  spacingBottom += marginBottom;
+  if (targetSelector) {
+    // oversimplification that actually works
+    // (simplified because it assumes the targeted element is a direct child of the contained element which may have padding)
+    spacingTop += paddingTop;
+    spacingLeft += paddingLeft;
+    spacingRight += paddingRight;
+    spacingBottom += paddingBottom;
+  }
+
+  const maxBorderWidth = Math.max(
+    borderTopWidth,
+    borderLeftWidth,
+    borderRightWidth,
+    borderBottomWidth,
+  );
+  const size = Math.max(2, maxBorderWidth / 2);
+
+  spacingTop += size / 4;
+  spacingLeft += size / 4;
+  spacingRight += size / 4;
+  spacingBottom += size / 4;
+
+  return (
+    <div
+      name="element_with_loader_wrapper"
+      ref={containerRef}
+      data-loader-visible={shouldShowSpinner ? "" : undefined}
+      style={{
+        flexGrow,
+        flexShrink,
+        flexBasis,
+      }}
+    >
+      {shouldShowSpinner && (
+        <div
+          name="loading_rectangle_wrapper"
+          style={{
+            top: `${spacingTop}px`,
+            left: `${spacingLeft}px`,
+            bottom: `${spacingBottom}px`,
+            right: `${spacingRight}px`,
+          }}
+        >
+          <RectangleLoading
+            color={currentColor}
+            radius={borderRadius}
+            size={size}
+          />
+        </div>
+      )}
+      {children}
+    </div>
+  );
+};

package/src/components/loader/loading_spinner.jsx

@@ -0,0 +1,68 @@
+export const LoadingSpinner = ({ color = "FF156D" }) => {
+  return (
+    <svg
+      viewBox="0 0 200 200"
+      width="100%"
+      height="100%"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <rect
+        fill={color}
+        stroke={color}
+        stroke-width="15"
+        width="30"
+        height="30"
+        x="25"
+        y="85"
+      >
+        <animate
+          attributeName="opacity"
+          calcMode="spline"
+          dur="2"
+          values="1;0;1;"
+          keySplines=".5 0 .5 1;.5 0 .5 1"
+          repeatCount="indefinite"
+          begin="-.4"
+        ></animate>
+      </rect>
+      <rect
+        fill={color}
+        stroke={color}
+        stroke-width="15"
+        width="30"
+        height="30"
+        x="85"
+        y="85"
+      >
+        <animate
+          attributeName="opacity"
+          calcMode="spline"
+          dur="2"
+          values="1;0;1;"
+          keySplines=".5 0 .5 1;.5 0 .5 1"
+          repeatCount="indefinite"
+          begin="-.2"
+        ></animate>
+      </rect>
+      <rect
+        fill={color}
+        stroke={color}
+        stroke-width="15"
+        width="30"
+        height="30"
+        x="145"
+        y="85"
+      >
+        <animate
+          attributeName="opacity"
+          calcMode="spline"
+          dur="2"
+          values="1;0;1;"
+          keySplines=".5 0 .5 1;.5 0 .5 1"
+          repeatCount="indefinite"
+          begin="0"
+        ></animate>
+      </rect>
+    </svg>
+  );
+};