@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/primitives/menu/navigation.ts

@@ -0,0 +1,15 @@
+export type MenuMove = "next" | "prev" | "first" | "last";
+
+/**
+ * Index to focus after `move`, over `count` enabled items. `current` is -1 when
+ * focus sits on the menu itself: `next` then enters at the start, `prev` at the end.
+ */
+export function moveIndex(count: number, current: number, move: MenuMove, loop = true): number {
+  if (count === 0) return -1;
+  if (move === "first") return 0;
+  if (move === "last") return count - 1;
+  if (current < 0) return move === "next" ? 0 : count - 1;
+  const next = current + (move === "next" ? 1 : -1);
+  if (next >= 0 && next < count) return next;
+  return loop ? (next + count) % count : current;
+}

package/src/primitives/menu/typeahead.ts

@@ -0,0 +1,22 @@
+/**
+ * Index of the item a typeahead `search` should focus, or -1. A repeated single
+ * character ("aaa") cycles through items starting with it, beginning after
+ * `currentIndex`; a longer search keeps the current item when it still matches.
+ */
+export function nextTypeaheadIndex(
+  values: readonly string[],
+  search: string,
+  currentIndex: number,
+): number {
+  if (search === "" || values.length === 0) return -1;
+  const repeated = search.length > 1 && [...search].every((char) => char === search[0]);
+  const needle = (repeated ? (search[0] as string) : search).toLowerCase();
+  const cycle = needle.length === 1;
+  const start = Math.max(currentIndex, 0);
+  for (let step = 0; step < values.length; step++) {
+    const index = (start + step) % values.length;
+    if (cycle && index === currentIndex) continue;
+    if ((values[index] as string).toLowerCase().startsWith(needle)) return index;
+  }
+  return -1;
+}

package/src/primitives/pointer-events-lock.ts

@@ -0,0 +1,48 @@
+"use client";
+
+import { type RefObject, useLayoutEffect } from "react";
+import { globalSingleton } from "./global-singleton.js";
+
+const state = globalSingleton("@jcsoftdev/ui/pointer-events-lock", () => ({
+  count: 0,
+  previous: "",
+}));
+
+/**
+ * Makes everything outside layers that set `pointer-events: auto` inert to the
+ * pointer. Ref-counted; returns the release function.
+ */
+export function blockOutsidePointerEvents(): () => void {
+  if (state.count++ === 0) {
+    state.previous = document.body.style.pointerEvents;
+    document.body.style.pointerEvents = "none";
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--state.count === 0) document.body.style.pointerEvents = state.previous;
+  };
+}
+
+/** Whether a modal layer currently makes everything outside it inert to the pointer. */
+export function isPointerEventsBlocked(): boolean {
+  return state.count > 0;
+}
+
+/**
+ * Layers opened while the lock is held (a dialog or popover launched from a modal
+ * menu, a nested menu) would inherit `pointer-events: none` from `<body>`. This
+ * re-enables the pointer on the layer element itself, like Radix does for every
+ * dismissable layer above the lock holder.
+ */
+export function useEnabledPointerEvents(ref: RefObject<HTMLElement | null>, active: boolean) {
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!active || !node || !isPointerEventsBlocked() || node.style.pointerEvents !== "") return;
+    node.style.pointerEvents = "auto";
+    return () => {
+      if (node.style.pointerEvents === "auto") node.style.pointerEvents = "";
+    };
+  }, [ref, active]);
+}

package/src/primitives/popover/popover.tsx

@@ -0,0 +1,316 @@
+"use client";
+
+import {
+  type ComponentProps,
+  createContext,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+  type RefObject,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { composeHandlers, useComposedRefs } from "../../utils/compose.js";
+import { Slot } from "../../utils/slot.js";
+import { useControllableState } from "../../utils/use-controllable-state.js";
+import { getTabbables, resolveTabOut } from "../focusable.js";
+import { hideOthers } from "../hide-others.js";
+import * as PopperPrimitive from "../popper/popper.js";
+import { Portal } from "../portal.js";
+import { lockBodyScroll } from "../scroll-lock.js";
+import {
+  type FocusOutsideEvent,
+  type InteractOutsideEvent,
+  type PointerDownOutsideEvent,
+  useDismissableLayer,
+} from "../use-dismissable-layer.js";
+import { useFocusScope } from "../use-focus-scope.js";
+import { useLayer } from "../use-layer.js";
+import { usePresence } from "../use-presence.js";
+
+/**
+ * In-house popover primitive. Same part names, callbacks and ARIA contract as the
+ * Radix popover it replaced, positioned by the in-house popper. Unstyled.
+ */
+
+interface PopoverContextValue {
+  open: boolean;
+  modal: boolean;
+  setOpen: (open: boolean) => void;
+  triggerRef: RefObject<HTMLElement | null>;
+  contentId: string;
+  hasCustomAnchor: boolean;
+  setHasCustomAnchor: (value: boolean) => void;
+}
+
+const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+function usePopoverContext(part: string): PopoverContextValue {
+  const context = useContext(PopoverContext);
+  if (!context) throw new Error(`<${part}> must be rendered inside <Popover>`);
+  return context;
+}
+
+const stateOf = (open: boolean) => (open ? "open" : "closed");
+
+export interface PopoverRootProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Traps focus, hides the page and locks scroll while open. Defaults to false. */
+  modal?: boolean;
+  children?: ReactNode;
+}
+
+export function Root({
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  modal = false,
+  children,
+}: PopoverRootProps) {
+  const [open, setOpen] = useControllableState({
+    prop: openProp,
+    defaultProp: defaultOpen,
+    onChange: onOpenChange,
+  });
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const contentId = useId();
+  const [hasCustomAnchor, setHasCustomAnchor] = useState(false);
+  const value = useMemo<PopoverContextValue>(
+    () => ({ open, modal, setOpen, triggerRef, contentId, hasCustomAnchor, setHasCustomAnchor }),
+    [open, modal, setOpen, contentId, hasCustomAnchor],
+  );
+  return (
+    <PopoverContext.Provider value={value}>
+      <PopperPrimitive.Root>{children}</PopperPrimitive.Root>
+    </PopoverContext.Provider>
+  );
+}
+
+type ButtonProps = ComponentProps<"button"> & { asChild?: boolean };
+
+/** Positions the content against this element instead of the trigger. */
+export function Anchor(props: PopperPrimitive.PopperAnchorProps) {
+  const { setHasCustomAnchor } = usePopoverContext("PopoverAnchor");
+  useEffect(() => {
+    setHasCustomAnchor(true);
+    return () => setHasCustomAnchor(false);
+  }, [setHasCustomAnchor]);
+  return <PopperPrimitive.Anchor {...props} />;
+}
+
+export function Trigger({ asChild, onClick, ref, ...props }: ButtonProps) {
+  const context = usePopoverContext("PopoverTrigger");
+  const composedRef = useComposedRefs<HTMLButtonElement>(
+    ref,
+    context.triggerRef as RefObject<HTMLButtonElement | null>,
+  );
+  const Comp = asChild ? Slot : "button";
+  const trigger = (
+    <Comp
+      type={asChild ? undefined : "button"}
+      aria-haspopup="dialog"
+      aria-expanded={context.open}
+      aria-controls={context.open ? context.contentId : undefined}
+      data-state={stateOf(context.open)}
+      {...props}
+      ref={composedRef as never}
+      onClick={composeHandlers(onClick, () => context.setOpen(!context.open))}
+    />
+  );
+  return context.hasCustomAnchor ? (
+    trigger
+  ) : (
+    <PopperPrimitive.Anchor asChild>{trigger}</PopperPrimitive.Anchor>
+  );
+}
+
+export function Close({ asChild, onClick, ...props }: ButtonProps) {
+  const context = usePopoverContext("PopoverClose");
+  const Comp = asChild ? Slot : "button";
+  return (
+    <Comp
+      type={asChild ? undefined : "button"}
+      {...props}
+      onClick={composeHandlers(onClick, () => context.setOpen(false))}
+    />
+  );
+}
+
+export { Portal };
+export const Arrow = PopperPrimitive.Arrow;
+
+export interface PopoverContentProps extends PopperPrimitive.PopperContentProps {
+  /** Keep mounted while closed, for your own animation or measurement. */
+  forceMount?: boolean;
+  onOpenAutoFocus?: (event: Event) => void;
+  onCloseAutoFocus?: (event: Event) => void;
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
+  onFocusOutside?: (event: FocusOutsideEvent) => void;
+  onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+
+export function Content({ forceMount, ref, ...props }: PopoverContentProps) {
+  const context = usePopoverContext("PopoverContent");
+  const nodeRef = useRef<HTMLDivElement | null>(null);
+  const composedRef = useComposedRefs<HTMLDivElement>(ref, nodeRef);
+  const mounted = usePresence(forceMount || context.open, nodeRef);
+  if (!mounted) return null;
+  return (
+    <ContentImpl
+      {...props}
+      ref={composedRef}
+      nodeRef={nodeRef}
+      engaged={context.open || !forceMount}
+    />
+  );
+}
+
+interface ContentImplProps extends Omit<PopoverContentProps, "forceMount"> {
+  nodeRef: RefObject<HTMLDivElement | null>;
+  /** False only for a force-mounted content that is currently closed. */
+  engaged: boolean;
+}
+
+function ContentImpl({
+  nodeRef,
+  engaged,
+  onOpenAutoFocus,
+  onCloseAutoFocus,
+  onEscapeKeyDown,
+  onPointerDownOutside,
+  onFocusOutside,
+  onInteractOutside,
+  onPointerDownCapture,
+  onFocusCapture,
+  onBlurCapture,
+  onKeyDown,
+  ...props
+}: ContentImplProps) {
+  const context = usePopoverContext("PopoverContent");
+  const { open, modal, setOpen, triggerRef } = context;
+  const listening = open && engaged;
+  const isTop = useLayer(listening);
+  const interactedOutside = useRef(false);
+  /** A press that landed on the trigger a moment ago: the focus it causes elsewhere is not a dismissal. */
+  const pressedTrigger = useRef(false);
+  const pressedTriggerTimer = useRef<number | undefined>(undefined);
+  const focusInTree = useRef<() => boolean>(() => false);
+
+  useEffect(() => {
+    if (listening) interactedOutside.current = false;
+  }, [listening]);
+
+  useEffect(() => {
+    if (!engaged || !modal) return;
+    const unlock = lockBodyScroll();
+    const show = hideOthers([nodeRef.current]);
+    return () => {
+      show();
+      unlock();
+    };
+  }, [engaged, modal, nodeRef]);
+
+  useFocusScope({
+    ref: nodeRef,
+    active: engaged,
+    trapped: modal && open,
+    isTop,
+    allowFocus: () => focusInTree.current(),
+    onMountAutoFocus: onOpenAutoFocus,
+    onUnmountAutoFocus: (event) => {
+      onCloseAutoFocus?.(event);
+      if (event.defaultPrevented) return;
+      // Closed by pressing elsewhere: leave focus where the user put it.
+      if (!modal && interactedOutside.current) {
+        event.preventDefault();
+        return;
+      }
+      const trigger = triggerRef.current;
+      if (trigger && document.contains(trigger)) {
+        event.preventDefault();
+        trigger.focus({ preventScroll: true });
+      }
+    },
+  });
+
+  const layerProps = useDismissableLayer({
+    ref: nodeRef,
+    active: listening,
+    isTop,
+    onEscapeKeyDown,
+    onPointerDownOutside: (event) => {
+      onPointerDownOutside?.(event);
+      const original = event.detail.originalEvent;
+      const contextClick = original.button === 2 || (original.button === 0 && original.ctrlKey);
+      if (modal && contextClick) event.preventDefault();
+    },
+    onFocusOutside: (event) => {
+      onFocusOutside?.(event);
+      // A modal traps focus, so a stray focus event must not close it. Pressing the trigger
+      // can focus a focusable ancestor (Safari buttons, a tabindex container): the trigger's
+      // own click closes the popover, so closing here too would reopen it.
+      if (modal || pressedTrigger.current) event.preventDefault();
+    },
+    onInteractOutside: (event) => {
+      onInteractOutside?.(event);
+      const target = event.detail.originalEvent.target as Node | null;
+      // The trigger toggles on its own click; closing here too would reopen it.
+      if (target && triggerRef.current?.contains(target)) {
+        event.preventDefault();
+        if (event.detail.originalEvent.type === "pointerdown") {
+          pressedTrigger.current = true;
+          window.clearTimeout(pressedTriggerTimer.current);
+          pressedTriggerTimer.current = window.setTimeout(() => {
+            pressedTrigger.current = false;
+          }, 300);
+        }
+      }
+      if (!event.defaultPrevented) interactedOutside.current = true;
+    },
+    onDismiss: () => setOpen(false),
+  });
+
+  focusInTree.current = layerProps.isFocusInTree;
+  useEffect(() => () => window.clearTimeout(pressedTriggerTimer.current), []);
+
+  // A non-modal popover is portaled to the end of <body>, so the browser would send Tab off
+  // the page. Hand focus to the neighbours of the trigger and close instead.
+  const leaveWithTab = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    const node = nodeRef.current;
+    const trigger = triggerRef.current;
+    const active = document.activeElement;
+    if (modal || event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey) return;
+    if (!node || !trigger || !active || !node.contains(active) || !isTop()) return;
+    const items = getTabbables(node);
+    const first = items[0];
+    const last = items[items.length - 1];
+    const leavingForward = !event.shiftKey && (active === last || items.length === 0);
+    const leavingBackward = event.shiftKey && (active === first || active === node);
+    if (!leavingForward && !leavingBackward) return;
+    event.preventDefault();
+    const next = resolveTabOut(trigger, node, !leavingForward);
+    interactedOutside.current = true;
+    (next ?? trigger).focus({ preventScroll: true });
+    setOpen(false);
+  };
+
+  return (
+    <PopperPrimitive.Content
+      id={context.contentId}
+      role="dialog"
+      data-state={stateOf(open)}
+      tabIndex={-1}
+      {...props}
+      onPointerDownCapture={composeHandlers(onPointerDownCapture, layerProps.onPointerDownCapture)}
+      onFocusCapture={composeHandlers(onFocusCapture, layerProps.onFocusCapture)}
+      onBlurCapture={composeHandlers(onBlurCapture, layerProps.onBlurCapture)}
+      onKeyDown={composeHandlers(onKeyDown, leaveWithTab)}
+    />
+  );
+}

package/src/primitives/popper/geometry.ts

@@ -0,0 +1,250 @@
+/**
+ * Pure placement maths for anchored floating content. No DOM access, so it runs
+ * in node tests. All rectangles share one coordinate space (the viewport).
+ */
+
+export type Side = "top" | "right" | "bottom" | "left";
+export type Align = "start" | "center" | "end";
+export type Direction = "ltr" | "rtl";
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export type Padding = number | Partial<Record<Side, number>>;
+
+export interface ArrowGeometry {
+  /** Length of the arrow base, along the edge of the content. */
+  width: number;
+  /** How far the arrow protrudes from the content. It is added to `sideOffset`. */
+  height: number;
+  /** Minimum distance between the arrow and the corners of the content. */
+  padding?: number;
+}
+
+export interface PlacementInput {
+  anchor: Rect;
+  content: Size;
+  /** Area content must stay inside (the viewport, or an intersection of elements). */
+  boundary: Rect;
+  side?: Side;
+  align?: Align;
+  sideOffset?: number;
+  alignOffset?: number;
+  collisionPadding?: Padding;
+  /** Flip to the opposite side and shift along the edge to stay in the boundary. Defaults to true. */
+  avoidCollisions?: boolean;
+  /** `partial` keeps the content touching the anchor while shifting; `always` never lets go of the boundary. */
+  sticky?: "partial" | "always";
+  dir?: Direction;
+  arrow?: ArrowGeometry;
+}
+
+export interface Placement {
+  x: number;
+  y: number;
+  side: Side;
+  align: Align;
+  /** Free width/height for the content on the placed side, for `max-width`/`max-height`. */
+  availableWidth: number;
+  availableHeight: number;
+  /** `transform-origin` pointing at the anchor centre, in content-local pixels. */
+  transformOrigin: string;
+  /** The anchor is entirely outside the boundary (scrolled out of view). */
+  anchorHidden: boolean;
+  /** Arrow offset along the content edge (`x` for top/bottom, `y` for left/right). */
+  arrow?: { x?: number; y?: number; centerOffset: number; shouldHide: boolean };
+}
+
+const OPPOSITE: Record<Side, Side> = { top: "bottom", bottom: "top", left: "right", right: "left" };
+
+const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+export function normalizePadding(padding: Padding | undefined): Record<Side, number> {
+  if (typeof padding === "number") {
+    return { top: padding, right: padding, bottom: padding, left: padding };
+  }
+  return {
+    top: padding?.top ?? 0,
+    right: padding?.right ?? 0,
+    bottom: padding?.bottom ?? 0,
+    left: padding?.left ?? 0,
+  };
+}
+
+/** Intersection of rectangles; an empty intersection collapses to a zero-sized rect. */
+export function intersectRects(rects: readonly Rect[]): Rect {
+  let left = Number.NEGATIVE_INFINITY;
+  let top = Number.NEGATIVE_INFINITY;
+  let right = Number.POSITIVE_INFINITY;
+  let bottom = Number.POSITIVE_INFINITY;
+  for (const rect of rects) {
+    left = Math.max(left, rect.x);
+    top = Math.max(top, rect.y);
+    right = Math.min(right, rect.x + rect.width);
+    bottom = Math.min(bottom, rect.y + rect.height);
+  }
+  return { x: left, y: top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+}
+
+/** Where the content's top-left corner goes for a side and alignment, before collision handling. */
+function coordsFor(
+  side: Side,
+  align: Align,
+  anchor: Rect,
+  content: Size,
+  offset: number,
+  alignOffset: number,
+  dir: Direction,
+): { x: number; y: number } {
+  const rtl = dir === "rtl";
+  // A centred content has no edge to offset from.
+  if (align === "center") alignOffset = 0;
+  if (side === "top" || side === "bottom") {
+    // Along the inline axis, `start` follows the reading direction.
+    let x: number;
+    if (align === "center") {
+      x = anchor.x + (anchor.width - content.width) / 2 + (rtl ? -alignOffset : alignOffset);
+    } else if ((align === "start") !== rtl) {
+      x = anchor.x + alignOffset;
+    } else {
+      x = anchor.x + anchor.width - content.width - alignOffset;
+    }
+    const y =
+      side === "bottom" ? anchor.y + anchor.height + offset : anchor.y - content.height - offset;
+    return { x, y };
+  }
+  let y: number;
+  if (align === "center") y = anchor.y + (anchor.height - content.height) / 2 + alignOffset;
+  else if (align === "start") y = anchor.y + alignOffset;
+  else y = anchor.y + anchor.height - content.height - alignOffset;
+  const x = side === "right" ? anchor.x + anchor.width + offset : anchor.x - content.width - offset;
+  return { x, y };
+}
+
+/** Positive when the content sticks out of the boundary on its main side. */
+function mainOverflow(
+  side: Side,
+  at: { x: number; y: number },
+  content: Size,
+  inner: { left: number; top: number; right: number; bottom: number },
+): number {
+  if (side === "top") return inner.top - at.y;
+  if (side === "bottom") return at.y + content.height - inner.bottom;
+  if (side === "left") return inner.left - at.x;
+  return at.x + content.width - inner.right;
+}
+
+export function computePlacement(input: PlacementInput): Placement {
+  const {
+    anchor,
+    content,
+    boundary,
+    side: preferredSide = "bottom",
+    align = "center",
+    sideOffset = 0,
+    alignOffset = 0,
+    avoidCollisions = true,
+    sticky = "partial",
+    dir = "ltr",
+    arrow,
+  } = input;
+  const pad = normalizePadding(input.collisionPadding);
+  const inner = {
+    left: boundary.x + pad.left,
+    top: boundary.y + pad.top,
+    right: boundary.x + boundary.width - pad.right,
+    bottom: boundary.y + boundary.height - pad.bottom,
+  };
+  const offset = sideOffset + (arrow?.height ?? 0);
+  const at = (side: Side) => coordsFor(side, align, anchor, content, offset, alignOffset, dir);
+
+  let side = preferredSide;
+  let { x, y } = at(side);
+
+  if (avoidCollisions) {
+    const overflow = mainOverflow(side, { x, y }, content, inner);
+    if (overflow > 0) {
+      const other = OPPOSITE[side];
+      const otherAt = at(other);
+      if (mainOverflow(other, otherAt, content, inner) < overflow) {
+        side = other;
+        ({ x, y } = otherAt);
+      }
+    }
+
+    // Shift along the edge. Content larger than the boundary pins to its start edge.
+    if (side === "top" || side === "bottom") {
+      const shifted = clamp(x, inner.left, Math.max(inner.left, inner.right - content.width));
+      x =
+        sticky === "partial"
+          ? clamp(shifted, anchor.x - content.width, anchor.x + anchor.width)
+          : shifted;
+    } else {
+      const shifted = clamp(y, inner.top, Math.max(inner.top, inner.bottom - content.height));
+      y =
+        sticky === "partial"
+          ? clamp(shifted, anchor.y - content.height, anchor.y + anchor.height)
+          : shifted;
+    }
+  }
+
+  const horizontal = side === "top" || side === "bottom";
+  const innerWidth = Math.max(0, inner.right - inner.left);
+  const innerHeight = Math.max(0, inner.bottom - inner.top);
+  let availableWidth = innerWidth;
+  let availableHeight = innerHeight;
+  if (side === "bottom") availableHeight = inner.bottom - (anchor.y + anchor.height + offset);
+  else if (side === "top") availableHeight = anchor.y - offset - inner.top;
+  else if (side === "right") availableWidth = inner.right - (anchor.x + anchor.width + offset);
+  else availableWidth = anchor.x - offset - inner.left;
+
+  const centerX = anchor.x + anchor.width / 2;
+  const centerY = anchor.y + anchor.height / 2;
+  const originX = clamp(centerX - x, 0, content.width);
+  const originY = clamp(centerY - y, 0, content.height);
+  const transformOrigin = horizontal
+    ? `${originX}px ${side === "bottom" ? "0px" : `${content.height}px`}`
+    : `${side === "right" ? "0px" : `${content.width}px`} ${originY}px`;
+
+  let arrowResult: Placement["arrow"];
+  if (arrow) {
+    const edgePadding = arrow.padding ?? 0;
+    const length = horizontal ? content.width : content.height;
+    const wanted = (horizontal ? centerX - x : centerY - y) - arrow.width / 2;
+    const max = Math.max(edgePadding, length - arrow.width - edgePadding);
+    const placed = clamp(wanted, edgePadding, max);
+    arrowResult = {
+      ...(horizontal ? { x: placed } : { y: placed }),
+      centerOffset: (horizontal ? centerX - x : centerY - y) - length / 2,
+      // The arrow cannot point at the anchor centre (clamped to a corner or content too short).
+      shouldHide: placed !== wanted || length < arrow.width + 2 * edgePadding,
+    };
+  }
+
+  const anchorHidden =
+    anchor.x + anchor.width <= boundary.x ||
+    anchor.x >= boundary.x + boundary.width ||
+    anchor.y + anchor.height <= boundary.y ||
+    anchor.y >= boundary.y + boundary.height;
+
+  return {
+    x,
+    y,
+    side,
+    align,
+    availableWidth,
+    availableHeight,
+    transformOrigin,
+    anchorHidden,
+    ...(arrowResult ? { arrow: arrowResult } : {}),
+  };
+}