@jcsoftdev/ui 0.1.7 → 0.2.0

package/src/primitives/popper/popper.tsx

@@ -0,0 +1,434 @@
+"use client";
+
+import {
+  type ComponentProps,
+  createContext,
+  type ReactNode,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useComposedRefs } from "../../utils/compose.js";
+import { Slot } from "../../utils/slot.js";
+import {
+  type Align,
+  type ArrowGeometry,
+  computePlacement,
+  type Direction,
+  intersectRects,
+  type Padding,
+  type Rect,
+  type Side,
+} from "./geometry.js";
+
+/**
+ * Anchored positioning primitive: `Root` > `Anchor` + `Content` (+ `Arrow`).
+ *
+ * `Content` renders a fixed-position wrapper (`[data-ui-popper-wrapper]`) holding
+ * the element you style. It exposes `data-side`/`data-align` on that element and
+ * these CSS variables, inherited from the wrapper:
+ * `--ui-popper-available-width`, `--ui-popper-available-height`,
+ * `--ui-popper-anchor-width`, `--ui-popper-anchor-height`, `--ui-popper-transform-origin`.
+ */
+
+interface PopperContextValue {
+  anchor: HTMLElement | null;
+  setAnchor: (node: HTMLElement | null) => void;
+  arrow: ArrowGeometry | null;
+  setArrow: (arrow: ArrowGeometry | null) => void;
+}
+
+const PopperContext = createContext<PopperContextValue | null>(null);
+
+function usePopperContext(part: string): PopperContextValue {
+  const context = useContext(PopperContext);
+  if (!context) throw new Error(`<${part}> must be rendered inside <Popper.Root>`);
+  return context;
+}
+
+export function Root({ children }: { children?: ReactNode }) {
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  const [arrow, setArrow] = useState<ArrowGeometry | null>(null);
+  const value = useMemo(() => ({ anchor, setAnchor, arrow, setArrow }), [anchor, arrow]);
+  return <PopperContext.Provider value={value}>{children}</PopperContext.Provider>;
+}
+
+export interface PopperAnchorProps extends ComponentProps<"div"> {
+  asChild?: boolean;
+}
+
+/** The element the content is positioned against. */
+export function Anchor({ asChild, ref, ...props }: PopperAnchorProps) {
+  const { setAnchor } = usePopperContext("PopperAnchor");
+  const composedRef = useComposedRefs<HTMLDivElement>(ref, setAnchor);
+  const Comp = asChild ? Slot : "div";
+  return <Comp {...props} ref={composedRef as never} />;
+}
+
+interface ContentContextValue {
+  side: Side;
+  arrowX: number | undefined;
+  arrowY: number | undefined;
+  arrowHidden: boolean;
+}
+
+const ContentContext = createContext<ContentContextValue | null>(null);
+
+export interface PopperContentProps extends ComponentProps<"div"> {
+  side?: Side;
+  align?: Align;
+  /** Gap between the anchor and the content, in px. */
+  sideOffset?: number;
+  /** Shift along the edge, in px. Follows the reading direction for `start`/`end`. */
+  alignOffset?: number;
+  /** Distance kept from the boundary edges. */
+  collisionPadding?: Padding;
+  /** Element(s) the content must stay inside, intersected with the viewport. Keep the reference stable. */
+  collisionBoundary?: Element | null | Array<Element | null>;
+  /** Flip and shift to avoid the boundary. Defaults to true. */
+  avoidCollisions?: boolean;
+  /** `partial` keeps the content touching the anchor while shifting. Defaults to `partial`. */
+  sticky?: "partial" | "always";
+  /** Hide the content while the anchor is scrolled out of the boundary. */
+  hideWhenDetached?: boolean;
+  /** Minimum distance between the arrow and the content corners. */
+  arrowPadding?: number;
+  /** Reading direction; read from the anchor element when omitted. */
+  dir?: Direction;
+}
+
+interface Placed {
+  side: Side;
+  align: Align;
+  positioned: boolean;
+  arrowX: number | undefined;
+  arrowY: number | undefined;
+  arrowHidden: boolean;
+}
+
+const samePlaced = (a: Placed, b: Placed) =>
+  a.side === b.side &&
+  a.align === b.align &&
+  a.positioned === b.positioned &&
+  a.arrowX === b.arrowX &&
+  a.arrowY === b.arrowY &&
+  a.arrowHidden === b.arrowHidden;
+
+function paddingKey(padding: Padding): string {
+  return typeof padding === "number" ? String(padding) : JSON.stringify(padding);
+}
+
+function boundaryRect(boundary: PopperContentProps["collisionBoundary"]): Rect {
+  const root = document.documentElement;
+  const viewport = window.visualViewport;
+  const rects: Rect[] = [
+    viewport
+      ? {
+          x: viewport.offsetLeft,
+          y: viewport.offsetTop,
+          width: viewport.width,
+          height: viewport.height,
+        }
+      : { x: 0, y: 0, width: root.clientWidth, height: root.clientHeight },
+  ];
+  for (const element of [boundary].flat()) {
+    if (!element) continue;
+    const { left, top, width, height } = element.getBoundingClientRect();
+    rects.push({ x: left, y: top, width, height });
+  }
+  return intersectRects(rects);
+}
+
+/**
+ * Top-left of the closest ancestor that becomes the containing block of fixed
+ * descendants (transform, filter, contain, will-change...), in viewport coordinates.
+ */
+function containingBlockOrigin(node: HTMLElement): { x: number; y: number } {
+  for (let parent = node.parentElement; parent; parent = parent.parentElement) {
+    const style = getComputedStyle(parent);
+    const creates =
+      style.transform !== "none" ||
+      style.perspective !== "none" ||
+      style.filter !== "none" ||
+      (style.backdropFilter !== undefined && style.backdropFilter !== "none") ||
+      /paint|layout|strict|content/.test(style.contain) ||
+      /transform|perspective|filter/.test(style.willChange) ||
+      (style.containerType !== undefined && !["", "normal"].includes(style.containerType));
+    if (creates) {
+      const box = parent.getBoundingClientRect();
+      // A scrolled containing block carries its fixed descendants along with its content.
+      return {
+        x: box.left + parent.clientLeft - parent.scrollLeft,
+        y: box.top + parent.clientTop - parent.scrollTop,
+      };
+    }
+  }
+  return { x: 0, y: 0 };
+}
+
+export function Content({
+  side = "bottom",
+  align = "center",
+  sideOffset = 0,
+  alignOffset = 0,
+  collisionPadding = 0,
+  collisionBoundary,
+  avoidCollisions = true,
+  sticky = "partial",
+  hideWhenDetached = false,
+  arrowPadding = 0,
+  dir,
+  ref,
+  style,
+  ...props
+}: PopperContentProps) {
+  const { anchor, arrow } = usePopperContext("PopperContent");
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const [content, setContent] = useState<HTMLDivElement | null>(null);
+  const composedRef = useComposedRefs<HTMLDivElement>(ref, setContent);
+  const [placed, setPlaced] = useState<Placed>({
+    side,
+    align,
+    positioned: false,
+    arrowX: undefined,
+    arrowY: undefined,
+    arrowHidden: false,
+  });
+  const boundaryRef = useRef(collisionBoundary);
+  boundaryRef.current = collisionBoundary;
+  const padding = paddingKey(collisionPadding);
+  const paddingRef = useRef(collisionPadding);
+  paddingRef.current = collisionPadding;
+
+  // The wrapper owns the stacking context; the styled content decides its z-index.
+  useLayoutEffect(() => {
+    if (content && wrapperRef.current) {
+      wrapperRef.current.style.zIndex = getComputedStyle(content).zIndex;
+    }
+  }, [content]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `padding` is the stable key of `collisionPadding`, read through a ref
+  useLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper || !content || !anchor) return;
+    let frame = 0;
+
+    const update = () => {
+      const anchorBox = anchor.getBoundingClientRect();
+      const anchorRect: Rect = {
+        x: anchorBox.left,
+        y: anchorBox.top,
+        width: anchorBox.width,
+        height: anchorBox.height,
+      };
+      // The content is portaled, so the anchor is the one that sits inside the app's `dir`.
+      const direction = dir ?? (getComputedStyle(anchor).direction === "rtl" ? "rtl" : "ltr");
+      wrapper.setAttribute("dir", direction);
+      const boundary = boundaryRect(boundaryRef.current);
+      const place = () =>
+        computePlacement({
+          anchor: anchorRect,
+          content: { width: content.offsetWidth, height: content.offsetHeight },
+          boundary,
+          side,
+          align,
+          sideOffset,
+          alignOffset,
+          collisionPadding: paddingRef.current,
+          avoidCollisions,
+          sticky,
+          dir: direction,
+          ...(arrow ? { arrow: { ...arrow, padding: arrowPadding } } : {}),
+        });
+      const set = (name: string, value: string) => wrapper.style.setProperty(name, value);
+      const publish = (placement: ReturnType<typeof place>) => {
+        set("--ui-popper-available-width", `${placement.availableWidth}px`);
+        set("--ui-popper-available-height", `${placement.availableHeight}px`);
+        set("--ui-popper-anchor-width", `${anchorRect.width}px`);
+        set("--ui-popper-anchor-height", `${anchorRect.height}px`);
+        set("--ui-popper-transform-origin", placement.transformOrigin);
+      };
+      let result = place();
+      publish(result);
+      // The available-size variables usually drive max-height/max-width: measure again
+      // with them applied so the first frame is not placed for the unlimited size.
+      for (let pass = 0; pass < 2; pass++) {
+        const again = place();
+        if (again.x === result.x && again.y === result.y && again.side === result.side) break;
+        result = again;
+        publish(result);
+      }
+      const ratio = window.devicePixelRatio || 1;
+      const snap = (value: number) => Math.round(value * ratio) / ratio;
+      const origin = containingBlockOrigin(wrapper);
+      wrapper.style.transform = `translate3d(${snap(result.x - origin.x)}px, ${snap(result.y - origin.y)}px, 0)`;
+      const hidden = hideWhenDetached && result.anchorHidden;
+      wrapper.style.visibility = hidden ? "hidden" : "";
+      wrapper.style.pointerEvents = hidden ? "none" : "";
+      const next: Placed = {
+        side: result.side,
+        align: result.align,
+        positioned: true,
+        arrowX: result.arrow?.x,
+        arrowY: result.arrow?.y,
+        arrowHidden: result.arrow?.shouldHide ?? false,
+      };
+      setPlaced((current) => (samePlaced(current, next) ? current : next));
+    };
+
+    const schedule = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        update();
+      });
+    };
+
+    update();
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, { capture: true, passive: true });
+    const viewport = window.visualViewport;
+    viewport?.addEventListener("resize", schedule);
+    viewport?.addEventListener("scroll", schedule);
+    const observer =
+      typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => update());
+    observer?.observe(anchor);
+    observer?.observe(content);
+    return () => {
+      if (frame) cancelAnimationFrame(frame);
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
+      viewport?.removeEventListener("resize", schedule);
+      viewport?.removeEventListener("scroll", schedule);
+      observer?.disconnect();
+    };
+  }, [
+    anchor,
+    content,
+    arrow,
+    side,
+    align,
+    sideOffset,
+    alignOffset,
+    padding,
+    avoidCollisions,
+    sticky,
+    hideWhenDetached,
+    arrowPadding,
+    dir,
+  ]);
+
+  const contentValue = useMemo(
+    () => ({
+      side: placed.side,
+      arrowX: placed.arrowX,
+      arrowY: placed.arrowY,
+      arrowHidden: placed.arrowHidden,
+    }),
+    [placed.side, placed.arrowX, placed.arrowY, placed.arrowHidden],
+  );
+
+  return (
+    <div
+      data-ui-popper-wrapper=""
+      ref={wrapperRef}
+      style={{
+        position: "fixed",
+        left: 0,
+        top: 0,
+        // Parked off-screen until the first measurement lands, so nothing flashes.
+        transform: "translate3d(0px, -200%, 0)",
+        minWidth: "max-content",
+        willChange: "transform",
+      }}
+    >
+      <ContentContext.Provider value={contentValue}>
+        <div
+          data-side={placed.side}
+          data-align={placed.align}
+          {...props}
+          ref={composedRef}
+          style={placed.positioned ? style : { ...style, animation: "none" }}
+        />
+      </ContentContext.Provider>
+    </div>
+  );
+}
+
+export interface PopperArrowProps extends ComponentProps<"span"> {
+  /** Length of the base along the content edge, in px. */
+  width?: number;
+  /** Protrusion from the content edge, in px; it is added to `sideOffset`. */
+  height?: number;
+}
+
+const BASE_SIDE: Record<Side, Side> = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left",
+};
+const OUTWARD: Record<Side, string> = {
+  top: "translateY(-100%)",
+  bottom: "translateY(100%)",
+  left: "translateX(-100%)",
+  right: "translateX(100%)",
+};
+
+/** Triangle inside a `w` x `h` box, pointing back at the anchor from the content's `side`. */
+function arrowPoints(side: Side, w: number, h: number): string {
+  if (side === "bottom") return `0,${h} ${w},${h} ${w / 2},0`;
+  if (side === "top") return `0,0 ${w},0 ${w / 2},${h}`;
+  if (side === "right") return `${w},0 ${w},${h} 0,${h / 2}`;
+  return `0,0 0,${h} ${w},${h / 2}`;
+}
+
+/**
+ * Pointer towards the anchor. Renders a triangle filled with `currentColor`
+ * unless you pass children. Place it as the last child of `Content`.
+ */
+export function Arrow({ width = 10, height = 5, children, style, ...props }: PopperArrowProps) {
+  const { setArrow } = usePopperContext("PopperArrow");
+  const content = useContext(ContentContext);
+  useLayoutEffect(() => {
+    setArrow({ width, height });
+    return () => setArrow(null);
+  }, [width, height, setArrow]);
+  if (!content) throw new Error("<PopperArrow> must be rendered inside <Popper.Content>");
+  const { side, arrowX, arrowY, arrowHidden } = content;
+  const vertical = side === "top" || side === "bottom";
+  const base = BASE_SIDE[side];
+  const boxWidth = vertical ? width : height;
+  const boxHeight = vertical ? height : width;
+  return (
+    <span
+      data-side={side}
+      {...props}
+      style={{
+        position: "absolute",
+        [base]: 0,
+        ...(vertical ? { left: arrowX } : { top: arrowY }),
+        transform: OUTWARD[base],
+        lineHeight: 0,
+        pointerEvents: "none",
+        ...(arrowHidden ? { visibility: "hidden" } : null),
+        ...style,
+      }}
+    >
+      {children ?? (
+        <svg
+          aria-hidden="true"
+          width={boxWidth}
+          height={boxHeight}
+          viewBox={`0 0 ${boxWidth} ${boxHeight}`}
+          fill="currentColor"
+          style={{ display: "block" }}
+        >
+          <polygon points={arrowPoints(side, boxWidth, boxHeight)} />
+        </svg>
+      )}
+    </span>
+  );
+}

package/src/primitives/portal.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { type ReactNode, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+
+const noop = () => () => {};
+
+/** Renders into `container` (default `document.body`); nothing on the server or before hydration. */
+export function Portal({
+  children,
+  container,
+}: {
+  children?: ReactNode;
+  container?: HTMLElement | null;
+}) {
+  const isClient = useSyncExternalStore(
+    noop,
+    () => true,
+    () => false,
+  );
+  if (!isClient) return null;
+  return createPortal(children, container ?? document.body);
+}

package/src/primitives/scroll-lock.ts

@@ -0,0 +1,114 @@
+import { globalSingleton } from "./global-singleton.js";
+
+/** Ref-counted lock: `apply` runs on the first acquire, its returned `restore` on the last release. */
+export function createRefCountedLock(apply: () => () => void): () => () => void {
+  let count = 0;
+  let restore: (() => void) | null = null;
+  return () => {
+    if (count === 0) restore = apply();
+    count += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      count -= 1;
+      if (count === 0) {
+        restore?.();
+        restore = null;
+      }
+    };
+  };
+}
+
+type Axis = "x" | "y";
+
+const SCROLLABLE_OVERFLOW = new Set(["auto", "scroll", "overlay"]);
+
+/** Whether `element` can move further in the drag direction (`delta` > 0 pulls content toward the start). */
+function canScrollFurther(element: Element, axis: Axis, delta: number): boolean {
+  const style = getComputedStyle(element);
+  if (axis === "y") {
+    if (!SCROLLABLE_OVERFLOW.has(style.overflowY) || element.scrollHeight <= element.clientHeight) {
+      return false;
+    }
+    return delta > 0
+      ? element.scrollTop > 0
+      : element.scrollTop + element.clientHeight < element.scrollHeight - 1;
+  }
+  if (!SCROLLABLE_OVERFLOW.has(style.overflowX) || element.scrollWidth <= element.clientWidth) {
+    return false;
+  }
+  // `scrollLeft` is negative in RTL, so compare magnitudes.
+  const offset = Math.abs(element.scrollLeft);
+  return delta > 0 ? offset > 0 : offset + element.clientWidth < element.scrollWidth - 1;
+}
+
+/** Controls that handle their own touch drag (sliders, text areas) and must never be cancelled. */
+const OWN_DRAG =
+  'input[type="range"], textarea, select, [contenteditable]:not([contenteditable="false"])';
+
+let touchStart: { x: number; y: number } | null = null;
+
+function onTouchStart(event: TouchEvent) {
+  const touch = event.touches[0];
+  touchStart = touch && event.touches.length === 1 ? { x: touch.clientX, y: touch.clientY } : null;
+}
+
+/**
+ * iOS Safari ignores `overflow: hidden` on body for touch drags. Cancel drags that
+ * cannot move anything: allowed are form controls that drag on their own and any
+ * ancestor that can still scroll along the drag axis (vertical or horizontal);
+ * at a scroll edge the drag falls through to the page and is cancelled.
+ */
+function onTouchMove(event: TouchEvent) {
+  const touch = event.touches[0];
+  if (event.touches.length > 1 || !event.cancelable || !touch || !touchStart) return;
+  const dx = touch.clientX - touchStart.x;
+  const dy = touch.clientY - touchStart.y;
+  const axis: Axis = Math.abs(dx) > Math.abs(dy) ? "x" : "y";
+  const delta = axis === "x" ? dx : dy;
+  const target = event.target;
+  if (target instanceof Element && target.closest(OWN_DRAG)) return;
+  for (let node = target as Element | null; node; node = node.parentElement) {
+    if (node === document.body || node === document.documentElement) break;
+    if (canScrollFurther(node, axis, delta)) return;
+  }
+  event.preventDefault();
+}
+
+function applyBodyScrollLock(): () => void {
+  const { body, documentElement: root } = document;
+  const previous = {
+    bodyOverflow: body.style.overflow,
+    rootOverflow: root.style.overflow,
+    paddingRight: body.style.paddingRight,
+  };
+  const before = root.clientWidth;
+  const rootExplicit = getComputedStyle(root).overflowY !== "visible";
+  const basePadding = Number.parseFloat(getComputedStyle(body).paddingRight) || 0;
+  body.style.overflow = "hidden";
+  // An explicit `overflow` on <html> (e.g. `overflow-y: scroll`) stops body's value propagating to the viewport.
+  if (rootExplicit) root.style.overflow = "hidden";
+  // Pad only for width actually lost: with `scrollbar-gutter: stable` the gutter stays and nothing shifts.
+  const lost = Math.max(0, root.clientWidth - before);
+  if (lost > 0) body.style.paddingRight = `${basePadding + lost}px`;
+  body.setAttribute("data-scroll-locked", "");
+  document.addEventListener("touchstart", onTouchStart, { passive: true });
+  document.addEventListener("touchmove", onTouchMove, { passive: false });
+  return () => {
+    document.removeEventListener("touchstart", onTouchStart);
+    document.removeEventListener("touchmove", onTouchMove);
+    touchStart = null;
+    body.style.overflow = previous.bodyOverflow;
+    root.style.overflow = previous.rootOverflow;
+    body.style.paddingRight = previous.paddingRight;
+    body.removeAttribute("data-scroll-locked");
+  };
+}
+
+/** Locks page scroll, compensating for the scrollbar gap; returns the release function. */
+export function lockBodyScroll(): () => void {
+  return globalSingleton("@jcsoftdev/ui/body-scroll-lock", () =>
+    createRefCountedLock(applyBodyScrollLock),
+  )();
+}