scroll-arrows 0.1.0

package/dist/react.cjs

@@ -0,0 +1,593 @@
+'use strict';
+
+var react = require('react');
+var rough = require('roughjs');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var rough__default = /*#__PURE__*/_interopDefault(rough);
+
+// src/react.tsx
+
+// src/geometry.ts
+var SIDES = [
+  "top",
+  "bottom",
+  "left",
+  "right"
+];
+function docRect(el) {
+  const r2 = el.getBoundingClientRect();
+  return {
+    left: r2.left + window.scrollX,
+    top: r2.top + window.scrollY,
+    width: r2.width,
+    height: r2.height
+  };
+}
+function center(r2) {
+  return { x: r2.left + r2.width / 2, y: r2.top + r2.height / 2 };
+}
+function socketPoint(r2, side) {
+  const c = center(r2);
+  switch (side) {
+    case "top":
+      return { x: c.x, y: r2.top };
+    case "bottom":
+      return { x: c.x, y: r2.top + r2.height };
+    case "left":
+      return { x: r2.left, y: c.y };
+    case "right":
+      return { x: r2.left + r2.width, y: c.y };
+    default:
+      return c;
+  }
+}
+function socketNormal(side) {
+  switch (side) {
+    case "top":
+      return { x: 0, y: -1 };
+    case "bottom":
+      return { x: 0, y: 1 };
+    case "left":
+      return { x: -1, y: 0 };
+    case "right":
+      return { x: 1, y: 0 };
+    default:
+      return { x: 0, y: 0 };
+  }
+}
+function autoSide(self, other) {
+  const target = center(other);
+  let best = "right";
+  let bestDist = Infinity;
+  for (const side of SIDES) {
+    const p = socketPoint(self, side);
+    const d = (p.x - target.x) ** 2 + (p.y - target.y) ** 2;
+    if (d < bestDist) {
+      bestDist = d;
+      best = side;
+    }
+  }
+  return best;
+}
+function resolveEndpoints(startRect, endRect, startSocket, endSocket) {
+  const s = startSocket === "auto" ? autoSide(startRect, endRect) : startSocket;
+  const e = endSocket === "auto" ? autoSide(endRect, startRect) : endSocket;
+  return {
+    start: socketPoint(startRect, s),
+    end: socketPoint(endRect, e),
+    startNormal: socketNormal(s),
+    endNormal: socketNormal(e)
+  };
+}
+function buildPath(ep, curvature, belly = { x: 0, y: 0 }) {
+  const { start, end, startNormal, endNormal } = ep;
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const dist = Math.hypot(dx, dy) || 1;
+  const reach = dist * (0.3 + curvature * 0.4);
+  const sn = startNormal.x || startNormal.y ? startNormal : unit(dx, dy);
+  const en = endNormal.x || endNormal.y ? endNormal : unit(-dx, -dy);
+  const c1 = { x: start.x + sn.x * reach + belly.x, y: start.y + sn.y * reach + belly.y };
+  const c2 = { x: end.x + en.x * reach + belly.x, y: end.y + en.y * reach + belly.y };
+  return `M ${r(start.x)} ${r(start.y)} C ${r(c1.x)} ${r(c1.y)} ${r(c2.x)} ${r(c2.y)} ${r(end.x)} ${r(end.y)}`;
+}
+function routeOffset(start, end, obstacles, padding = 14) {
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const t = { x: dx / len, y: dy / len };
+  const n = { x: dy / len, y: -dx / len };
+  let best = { x: 0, y: 0 };
+  let bestMag = 0;
+  for (const b of obstacles) {
+    const cx = b.left + b.width / 2;
+    const cy = b.top + b.height / 2;
+    const relx = cx - start.x;
+    const rely = cy - start.y;
+    const u = (relx * t.x + rely * t.y) / len;
+    if (u < 0 || u > 1) continue;
+    const signed = relx * n.x + rely * n.y;
+    const radius = Math.abs(b.width / 2 * n.x) + Math.abs(b.height / 2 * n.y);
+    const clearance = radius + padding;
+    if (Math.abs(signed) >= clearance) continue;
+    const sign = signed > 0 ? -1 : 1;
+    const offset = signed + sign * clearance;
+    if (Math.abs(offset) > bestMag) {
+      bestMag = Math.abs(offset);
+      best = { x: n.x * offset, y: n.y * offset };
+    }
+  }
+  return best;
+}
+function arrowHeadPath(tip, dir, size) {
+  const a = Math.atan2(dir.y, dir.x);
+  const spread = Math.PI / 7;
+  const p1 = {
+    x: tip.x - size * Math.cos(a - spread),
+    y: tip.y - size * Math.sin(a - spread)
+  };
+  const p2 = {
+    x: tip.x - size * Math.cos(a + spread),
+    y: tip.y - size * Math.sin(a + spread)
+  };
+  return `M ${r(p1.x)} ${r(p1.y)} L ${r(tip.x)} ${r(tip.y)} L ${r(p2.x)} ${r(p2.y)}`;
+}
+function endTangent(ep) {
+  const { end, endNormal } = ep;
+  if (endNormal.x || endNormal.y)
+    return { x: -endNormal.x + 0, y: -endNormal.y + 0 };
+  return unit(end.x - ep.start.x, end.y - ep.start.y);
+}
+function startTangent(ep) {
+  const { startNormal } = ep;
+  if (startNormal.x || startNormal.y)
+    return { x: -startNormal.x + 0, y: -startNormal.y + 0 };
+  return unit(ep.start.x - ep.end.x, ep.start.y - ep.end.y);
+}
+function unitNormal(a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const m = Math.hypot(dx, dy);
+  if (m === 0) return { x: 0, y: 0 };
+  return { x: dy / m + 0, y: -dx / m + 0 };
+}
+function unit(x, y) {
+  const m = Math.hypot(x, y) || 1;
+  return { x: x / m, y: y / m };
+}
+function r(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/progress.ts
+function easeInOutCubic(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+function clamp01(t) {
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+function scrollProgress(targetRect, range) {
+  const vh = window.innerHeight || 1;
+  const topFrac = (targetRect.top - window.scrollY) / vh;
+  const [enter, leave] = range;
+  return clamp01((enter - topFrac) / (enter - leave || 1));
+}
+function midpointRect(a, b) {
+  const ra = docRect(a);
+  const rb = docRect(b);
+  const ca = { x: ra.left + ra.width / 2, y: ra.top + ra.height / 2 };
+  const cb = { x: rb.left + rb.width / 2, y: rb.top + rb.height / 2 };
+  return {
+    left: (ca.x + cb.x) / 2,
+    top: (ca.y + cb.y) / 2,
+    width: 0,
+    height: 0
+  };
+}
+
+// src/overlay.ts
+var SVG_NS = "http://www.w3.org/2000/svg";
+var overlays = /* @__PURE__ */ new WeakMap();
+function getOverlay(container) {
+  var _a;
+  let svg = overlays.get(container);
+  if (svg && svg.isConnected) return svg;
+  svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("data-scroll-arrows", "");
+  Object.assign(svg.style, {
+    position: "absolute",
+    left: "0",
+    top: "0",
+    width: "100%",
+    height: "100%",
+    overflow: "visible",
+    pointerEvents: "none",
+    zIndex: "9999"
+  });
+  if (container === document.body) {
+    (_a = document.body.style).position || (_a.position = "relative");
+  } else {
+    const pos = getComputedStyle(container).position;
+    if (pos === "static") container.style.position = "relative";
+  }
+  container.appendChild(svg);
+  overlays.set(container, svg);
+  return svg;
+}
+function overlayOrigin(svg) {
+  const r2 = svg.getBoundingClientRect();
+  return { x: r2.left + window.scrollX, y: r2.top + window.scrollY };
+}
+function createGroup() {
+  return document.createElementNS(SVG_NS, "g");
+}
+function createSvgEl(tag) {
+  return document.createElementNS(SVG_NS, tag);
+}
+
+// src/roughness.ts
+function mapRoughness(roughness, curvatureOverride, stroke, strokeWidth, seed, anchorEnds = true) {
+  const r2 = clamp012(roughness);
+  return {
+    curvature: curvatureOverride ?? r2 * 0.6,
+    rough: {
+      roughness: r2 * 3.5,
+      bowing: r2 * 3,
+      maxRandomnessOffset: r2 * 4,
+      // Clean end of the spectrum: a single, near-exact stroke.
+      disableMultiStroke: r2 < 0.15,
+      // Pin endpoints to the sockets so the arrow always lands on its anchors,
+      // even when the middle of the stroke gets scratchy.
+      preserveVertices: anchorEnds,
+      stroke,
+      strokeWidth,
+      seed: seed | 0,
+      fill: "none"
+    }
+  };
+}
+function deriveSeed(a, b) {
+  let h = 2166136261;
+  const s = a + "->" + b;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0) % 1e5;
+}
+function clamp012(t) {
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+
+// src/draw.ts
+function lengths(segs) {
+  let lineLen = 0;
+  let headLen = 0;
+  for (const s of segs) {
+    if (s.kind === "line") lineLen = Math.max(lineLen, s.len);
+    else headLen += s.len;
+  }
+  return { lineLen, headLen };
+}
+function dashOffsets(segs, eased) {
+  const { lineLen, headLen } = lengths(segs);
+  const total = lineLen + headLen || 1;
+  const drawn = clamp01(eased) * total;
+  const lp = lineLen > 0 ? clamp01(drawn / lineLen) : 1;
+  let headDrawn = Math.max(0, drawn - lineLen);
+  return segs.map((seg) => {
+    if (seg.kind === "line") return seg.len * (1 - lp);
+    const show = Math.max(0, Math.min(seg.len, headDrawn));
+    headDrawn -= seg.len;
+    return seg.len - show;
+  });
+}
+function lineProgress(segs, eased) {
+  const { lineLen, headLen } = lengths(segs);
+  const total = lineLen + headLen || 1;
+  const drawn = clamp01(eased) * total;
+  return lineLen > 0 ? clamp01(drawn / lineLen) : 1;
+}
+function labelOpacity(lineProg, labelAt, fade = 0.08) {
+  return clamp01((lineProg - clamp01(labelAt)) / (fade || 1));
+}
+
+// src/scroll-arrow.ts
+var ScrollArrow = class {
+  constructor(options) {
+    this.group = createGroup();
+    /**
+     * Drawable segments. Line strokes (rough.js emits 1-2 overlapping ones) share
+     * a leading edge so they grow as a single pen tip; heads draw after the line.
+     */
+    this.segments = [];
+    /** Representative line stroke + label nodes, when a label is set. */
+    this.lineEl = null;
+    this.labelEl = null;
+    this.labelBgEl = null;
+    this.rafId = 0;
+    this.destroyed = false;
+    this.onScroll = () => {
+      if (this.rafId) return;
+      this.rafId = requestAnimationFrame(() => {
+        this.rafId = 0;
+        this.update();
+      });
+    };
+    this.opts = {
+      roughness: 0.5,
+      strokeWidth: 2,
+      head: "end",
+      headSize: 14,
+      speed: 1,
+      easing: easeInOutCubic,
+      progress: 0,
+      ...options
+    };
+    this.container = options.container ?? document.body;
+    this.svg = getOverlay(this.container);
+    this.rc = rough__default.default.svg(this.svg);
+    this.svg.appendChild(this.group);
+    this.progress = clamp01(this.opts.progress);
+    this.refs = this.resolveRefs();
+    this.stroke = options.stroke ?? getComputedStyle(this.container).color ?? "#222";
+    this.seed = options.seed ?? deriveSeed(refKey(options.start), refKey(options.end));
+    this.render();
+    this.bind();
+    this.update();
+  }
+  /** Manually set draw progress (0..1). Only meaningful when scroll is false. */
+  setProgress(p) {
+    this.progress = clamp01(p);
+    this.applyProgress();
+  }
+  /** Recompute geometry (call after layout changes you control). */
+  refresh() {
+    this.render();
+    this.update();
+  }
+  destroy() {
+    this.destroyed = true;
+    this.ro?.disconnect();
+    window.removeEventListener("scroll", this.onScroll, true);
+    window.removeEventListener("resize", this.onScroll);
+    cancelAnimationFrame(this.rafId);
+    this.group.remove();
+  }
+  // --- internals ---------------------------------------------------------
+  resolveRefs() {
+    const start = resolve(this.opts.start);
+    const end = resolve(this.opts.end);
+    if (!start || !end) {
+      throw new Error("[scroll-arrows] start/end element not found");
+    }
+    const scroll = this.opts.scroll;
+    let target = null;
+    if (scroll && scroll !== void 0 && scroll.target) {
+      target = resolve(scroll.target);
+    }
+    return { start, end, target };
+  }
+  resolveAvoid() {
+    const a = this.opts.avoid;
+    if (!a) return [];
+    const list = Array.isArray(a) ? a : [a];
+    return list.map(resolve).filter((el) => el !== null);
+  }
+  computeEndpoints() {
+    const sr = docRect(this.refs.start);
+    const er = docRect(this.refs.end);
+    const ss = this.opts.startSocket ?? "auto";
+    const es = this.opts.endSocket ?? "auto";
+    return resolveEndpoints(sr, er, ss, es);
+  }
+  render() {
+    while (this.group.firstChild) this.group.removeChild(this.group.firstChild);
+    this.segments = [];
+    const ep = this.computeEndpoints();
+    const origin = overlayOrigin(this.svg);
+    const shift = (e) => ({
+      start: { x: e.start.x - origin.x, y: e.start.y - origin.y },
+      end: { x: e.end.x - origin.x, y: e.end.y - origin.y },
+      startNormal: e.startNormal,
+      endNormal: e.endNormal
+    });
+    const local = shift(ep);
+    const { rough: roughOpts, curvature } = mapRoughness(
+      this.opts.roughness,
+      this.opts.curvature,
+      this.stroke,
+      this.opts.strokeWidth,
+      this.seed,
+      this.opts.anchorEnds ?? true
+    );
+    const obstacles = this.resolveAvoid().map((el) => {
+      const dr = docRect(el);
+      return {
+        left: dr.left - origin.x,
+        top: dr.top - origin.y,
+        width: dr.width,
+        height: dr.height
+      };
+    });
+    const clear = routeOffset(
+      local.start,
+      local.end,
+      obstacles,
+      this.opts.avoidPadding ?? 14
+    );
+    const BOW = 1.6;
+    const belly = { x: clear.x * BOW, y: clear.y * BOW };
+    const d = buildPath(local, curvature, belly);
+    this.appendDrawable(this.rc.path(d, roughOpts), "line");
+    const head = this.opts.head;
+    const size = this.opts.headSize;
+    if (head === "end" || head === "both") {
+      const dir = endTangent(local);
+      this.appendDrawable(
+        this.rc.path(arrowHeadPath(local.end, dir, size), roughOpts),
+        "head"
+      );
+    }
+    if (head === "start" || head === "both") {
+      const dir = startTangent(local);
+      this.appendDrawable(
+        this.rc.path(arrowHeadPath(local.start, dir, size), roughOpts),
+        "head"
+      );
+    }
+    this.lineEl = null;
+    let longest = 0;
+    for (const seg of this.segments) {
+      seg.len = seg.el.getTotalLength();
+      seg.el.style.strokeDasharray = String(seg.len);
+      seg.el.style.strokeDashoffset = String(seg.len);
+      if (seg.kind === "line" && seg.len >= longest) {
+        longest = seg.len;
+        this.lineEl = seg.el;
+      }
+    }
+    this.renderLabel();
+    this.applyProgress();
+  }
+  /** Place the label at a point along the line, with a masking background. */
+  renderLabel() {
+    this.labelEl = null;
+    this.labelBgEl = null;
+    const text = this.opts.label;
+    if (!text || !this.lineEl) return;
+    const total = this.lineEl.getTotalLength();
+    const at = clampAt(this.opts.labelAt ?? 0.5);
+    const pt = this.lineEl.getPointAtLength(at * total);
+    const offset = this.opts.labelOffset ?? 0;
+    let x = pt.x;
+    let y = pt.y;
+    if (offset && total > 0) {
+      const eps = Math.min(1, total / 2);
+      const before = this.lineEl.getPointAtLength(Math.max(0, at * total - eps));
+      const after = this.lineEl.getPointAtLength(Math.min(total, at * total + eps));
+      const n = unitNormal(before, after);
+      x += n.x * offset;
+      y += n.y * offset;
+    }
+    const label = createSvgEl("text");
+    label.textContent = text;
+    label.setAttribute("x", String(x));
+    label.setAttribute("y", String(y));
+    label.setAttribute("text-anchor", "middle");
+    label.setAttribute("dominant-baseline", "central");
+    label.style.font = this.opts.font ?? "600 16px sans-serif";
+    label.style.fill = this.opts.labelColor ?? this.stroke;
+    this.group.appendChild(label);
+    const bgColor = this.opts.labelBackground ?? getComputedStyle(this.container).backgroundColor;
+    if (bgColor && bgColor !== "none") {
+      const pad = 6;
+      const box = label.getBBox();
+      const rect = createSvgEl("rect");
+      rect.setAttribute("x", String(box.x - pad));
+      rect.setAttribute("y", String(box.y - pad / 2));
+      rect.setAttribute("width", String(box.width + pad * 2));
+      rect.setAttribute("height", String(box.height + pad));
+      rect.setAttribute("rx", "4");
+      rect.setAttribute("fill", bgColor);
+      this.group.insertBefore(rect, label);
+      this.labelBgEl = rect;
+    }
+    this.labelEl = label;
+  }
+  /** roughjs returns a <g> of one or more <path>; collect them in order. */
+  appendDrawable(g, kind) {
+    const paths = g.querySelectorAll("path");
+    paths.forEach((p) => {
+      const el = p;
+      el.setAttribute("fill", "none");
+      this.group.appendChild(el);
+      this.segments.push({ el, len: 0, kind });
+    });
+  }
+  /**
+   * Reveal the line as one growing pen tip (all line sub-strokes advance to the
+   * same leading fraction together), then draw the arrowhead(s) sequentially
+   * once the line is complete.
+   */
+  applyProgress() {
+    const eased = this.opts.easing(clamp01(this.progress));
+    const offsets = dashOffsets(this.segments, eased);
+    this.segments.forEach((seg, i) => {
+      seg.el.style.strokeDashoffset = String(offsets[i]);
+    });
+    if (this.labelEl) {
+      const op = labelOpacity(
+        lineProgress(this.segments, eased),
+        this.opts.labelAt ?? 0.5
+      );
+      this.labelEl.style.opacity = String(op);
+      if (this.labelBgEl) this.labelBgEl.style.opacity = String(op);
+    }
+  }
+  bind() {
+    const targets = [this.refs.start, this.refs.end, ...this.resolveAvoid()];
+    if (this.refs.target) targets.push(this.refs.target);
+    this.ro = new ResizeObserver(() => this.render());
+    targets.forEach((t) => this.ro.observe(t));
+    if (this.opts.scroll !== false) {
+      window.addEventListener("scroll", this.onScroll, true);
+      window.addEventListener("resize", this.onScroll);
+    }
+  }
+  update() {
+    if (this.destroyed) return;
+    if (this.opts.scroll === false) {
+      this.applyProgress();
+      return;
+    }
+    const scroll = this.opts.scroll ?? {};
+    const range = scroll.range ?? [0.85, 0.35];
+    const targetRect = this.refs.target ? docRect(this.refs.target) : midpointRect(this.refs.start, this.refs.end);
+    const raw = scrollProgress(targetRect, range);
+    this.progress = clamp01(raw * this.opts.speed);
+    this.applyProgress();
+  }
+};
+function resolve(ref) {
+  return typeof ref === "string" ? document.querySelector(ref) : ref;
+}
+function refKey(ref) {
+  return typeof ref === "string" ? ref : ref.tagName + (ref.id ? "#" + ref.id : "");
+}
+function clampAt(t) {
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+
+// src/react.tsx
+function read(a) {
+  if (typeof a === "string") return a;
+  if (a instanceof Element) return a;
+  return a.current;
+}
+function useScrollArrow(options) {
+  const arrowRef = react.useRef(null);
+  const { start, end, deps = [], ...rest } = options;
+  react.useEffect(() => {
+    const s = read(start);
+    const e = read(end);
+    if (!s || !e) return;
+    const arrow = new ScrollArrow({ ...rest, start: s, end: e });
+    arrowRef.current = arrow;
+    return () => {
+      arrow.destroy();
+      arrowRef.current = null;
+    };
+  }, deps);
+}
+function ScrollArrowLine(props) {
+  useScrollArrow(props);
+  return null;
+}
+
+exports.ScrollArrowLine = ScrollArrowLine;
+exports.useScrollArrow = useScrollArrow;
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map

package/dist/react.d.cts

@@ -0,0 +1,21 @@
+import { RefObject } from 'react';
+import { S as ScrollArrowOptions } from './types-DehQP2Hx.cjs';
+
+type Anchor = RefObject<Element | null> | Element | string;
+interface UseScrollArrowOptions extends Omit<ScrollArrowOptions, "start" | "end"> {
+    start: Anchor;
+    end: Anchor;
+    /** Re-create the arrow when any value here changes. */
+    deps?: unknown[];
+}
+/**
+ * Imperatively manage a ScrollArrow tied to two element refs. Returns nothing;
+ * the arrow lives in an overlay <svg>, not the React tree.
+ */
+declare function useScrollArrow(options: UseScrollArrowOptions): void;
+interface ScrollArrowProps extends UseScrollArrowOptions {
+}
+/** Declarative component form. Renders nothing itself. */
+declare function ScrollArrowLine(props: ScrollArrowProps): null;
+
+export { ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowOptions, useScrollArrow };

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+import { RefObject } from 'react';
+import { S as ScrollArrowOptions } from './types-DehQP2Hx.js';
+
+type Anchor = RefObject<Element | null> | Element | string;
+interface UseScrollArrowOptions extends Omit<ScrollArrowOptions, "start" | "end"> {
+    start: Anchor;
+    end: Anchor;
+    /** Re-create the arrow when any value here changes. */
+    deps?: unknown[];
+}
+/**
+ * Imperatively manage a ScrollArrow tied to two element refs. Returns nothing;
+ * the arrow lives in an overlay <svg>, not the React tree.
+ */
+declare function useScrollArrow(options: UseScrollArrowOptions): void;
+interface ScrollArrowProps extends UseScrollArrowOptions {
+}
+/** Declarative component form. Renders nothing itself. */
+declare function ScrollArrowLine(props: ScrollArrowProps): null;
+
+export { ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowOptions, useScrollArrow };

package/dist/react.js

@@ -0,0 +1,31 @@
+import { ScrollArrow } from './chunk-HLZXSGP5.js';
+import { useRef, useEffect } from 'react';
+
+function read(a) {
+  if (typeof a === "string") return a;
+  if (a instanceof Element) return a;
+  return a.current;
+}
+function useScrollArrow(options) {
+  const arrowRef = useRef(null);
+  const { start, end, deps = [], ...rest } = options;
+  useEffect(() => {
+    const s = read(start);
+    const e = read(end);
+    if (!s || !e) return;
+    const arrow = new ScrollArrow({ ...rest, start: s, end: e });
+    arrowRef.current = arrow;
+    return () => {
+      arrow.destroy();
+      arrowRef.current = null;
+    };
+  }, deps);
+}
+function ScrollArrowLine(props) {
+  useScrollArrow(props);
+  return null;
+}
+
+export { ScrollArrowLine, useScrollArrow };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map