scroll-arrows 0.1.3 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as ScrollArrowOptions } from './types-CDd8JqZX.js';
-export { A as ArrowHead, E as ElementRef, P as Point, a as ScrollOptions, b as Socket } from './types-CDd8JqZX.js';
+import { S as ScrollArrowOptions, a as ScrollArrowGroupOptions } from './types-CgHPWybd.js';
+export { A as ArrowHead, E as ElementRef, L as LabelPosition, P as Point, b as ScrollOptions, c as Socket } from './types-CgHPWybd.js';
 
 /** A single hand-drawn arrow that draws itself between two elements on scroll. */
 declare class ScrollArrow {
@@ -18,13 +18,38 @@ declare class ScrollArrow {
     private segments;
     /** Representative line stroke + label nodes, when a label is set. */
     private lineEl;
+    /**
+     * The smooth ideal path `d` (pre-roughjs). Label placement measures against
+     * this, not `lineEl`: rough.js bakes its double stroke into one path with two
+     * subpaths, so `lineEl.getTotalLength()` is ~2x the visible curve and would
+     * put `labelAt` at twice its intended fraction.
+     */
+    private lineD;
     private labelEl;
     private labelBgEl;
+    /** `opts.labelAt` resolved to a 0..1 fraction; cached by renderLabel for the draw loop. */
+    private resolvedLabelAt;
     private progress;
     private ro?;
+    /**
+     * Lazily armed only while an anchor is hidden/zero-size, so the common path
+     * (both anchors visible) wires no extra observer. Fires render() on reveal.
+     */
+    private revealObs?;
     private rafId;
     private destroyed;
+    /** Render static + fully drawn: user prefers reduced motion and we honor it. */
+    private reducedMotion;
+    /** When false the arrow is hidden and skips all draw/scroll work (no teardown). */
+    private enabled;
     constructor(options: ScrollArrowOptions);
+    /**
+     * Suspend or restore the arrow without tearing it down. Disabling hides it and
+     * stops all draw/scroll work; enabling shows it and recomputes geometry (so it
+     * reflects any layout change that happened while hidden). Idempotent. Wire it
+     * to `matchMedia` to switch arrows off below a breakpoint.
+     */
+    setEnabled(on: boolean): void;
     /** Manually set draw progress (0..1). Only meaningful when scroll is false. */
     setProgress(p: number): void;
     /** Recompute geometry (call after layout changes you control). */
@@ -44,14 +69,64 @@ declare class ScrollArrow {
      * once the line is complete.
      */
     private applyProgress;
+    /**
+     * Watch the anchors for the moment a hidden one becomes laid out, then redraw.
+     * IntersectionObserver fires when a previously `display:none` element gains a
+     * box — a transition ResizeObserver does not reliably report. Armed lazily and
+     * idempotently; torn down by the next successful render(). Guarded so it no-ops
+     * in environments without IntersectionObserver (older engines, some SSR/jsdom).
+     */
+    private armReveal;
+    private teardownReveal;
+    private bind;
+    private onScroll;
+    private update;
+}
+
+/**
+ * A coordinated set of arrows that draw in a staggered sequence off one shared
+ * scroll trigger (or manual `setProgress`). Owns its arrows; `destroy()` tears
+ * them all down.
+ */
+declare class ScrollArrowGroup {
+    private opts;
+    private arrows;
+    private windows;
+    private elements;
+    private target;
+    private progress;
+    private rafId;
+    private destroyed;
+    /** Render every arrow static + fully drawn when reduced motion is honored. */
+    private reducedMotion;
+    /** When false every arrow is hidden and the group does no scroll work. */
+    private enabled;
+    constructor(options: ScrollArrowGroupOptions);
+    /** Manually set group progress (0..1). Only meaningful when scroll is false. */
+    setProgress(p: number): void;
+    /** Recompute geometry for every arrow (call after layout changes). */
+    refresh(): void;
+    /**
+     * Suspend or restore the whole group without tearing it down. Hides every
+     * arrow and stops scroll work when off; restores and recomputes when on.
+     * Idempotent. Wire to `matchMedia` for breakpoint-aware diagrams.
+     */
+    setEnabled(on: boolean): void;
+    destroy(): void;
     private bind;
     private onScroll;
     private update;
+    /** Push each arrow to its sliced local progress for the current group value. */
+    private distribute;
+    /** Synthetic rect spanning every endpoint, used as the default trigger. */
+    private groupRect;
 }
 
 declare function easeInOutCubic(t: number): number;
 
 /** Convenience factory. `const a = scrollArrow({ start, end })`. */
 declare function scrollArrow(options: ScrollArrowOptions): ScrollArrow;
+/** Convenience factory. `const g = scrollArrowGroup({ arrows: [...] })`. */
+declare function scrollArrowGroup(options: ScrollArrowGroupOptions): ScrollArrowGroup;
 
-export { ScrollArrow, ScrollArrowOptions, easeInOutCubic, scrollArrow };
+export { ScrollArrow, ScrollArrowGroup, ScrollArrowGroupOptions, ScrollArrowOptions, easeInOutCubic, scrollArrow, scrollArrowGroup };

package/dist/index.js

@@ -1,11 +1,14 @@
-import { ScrollArrow } from './chunk-GKWBGFLA.js';
-export { ScrollArrow, easeInOutCubic } from './chunk-GKWBGFLA.js';
+import { ScrollArrow, ScrollArrowGroup } from './chunk-GX722UDR.js';
+export { ScrollArrow, ScrollArrowGroup, easeInOutCubic } from './chunk-GX722UDR.js';
 
 // src/index.ts
 function scrollArrow(options) {
   return new ScrollArrow(options);
 }
+function scrollArrowGroup(options) {
+  return new ScrollArrowGroup(options);
+}
 
-export { scrollArrow };
+export { scrollArrow, scrollArrowGroup };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react.cjs

@@ -25,20 +25,24 @@ function docRect(el) {
     height: r2.height
   };
 }
+function isDegenerateRect(r2) {
+  return r2.width <= 0 || r2.height <= 0;
+}
 function center(r2) {
   return { x: r2.left + r2.width / 2, y: r2.top + r2.height / 2 };
 }
-function socketPoint(r2, side) {
+function socketPoint(r2, side, offset = 0) {
   const c = center(r2);
+  const o = offset < -0.5 ? -0.5 : offset > 0.5 ? 0.5 : offset;
   switch (side) {
     case "top":
-      return { x: c.x, y: r2.top };
+      return { x: c.x + o * r2.width, y: r2.top };
     case "bottom":
-      return { x: c.x, y: r2.top + r2.height };
+      return { x: c.x + o * r2.width, y: r2.top + r2.height };
     case "left":
-      return { x: r2.left, y: c.y };
+      return { x: r2.left, y: c.y + o * r2.height };
     case "right":
-      return { x: r2.left + r2.width, y: c.y };
+      return { x: r2.left + r2.width, y: c.y + o * r2.height };
     default:
       return c;
   }
@@ -71,12 +75,12 @@ function autoSide(self, other) {
   }
   return best;
 }
-function resolveEndpoints(startRect, endRect, startSocket, endSocket) {
+function resolveEndpoints(startRect, endRect, startSocket, endSocket, startOffset = 0, endOffset = 0) {
   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),
+    start: socketPoint(startRect, s, startOffset),
+    end: socketPoint(endRect, e, endOffset),
     startNormal: socketNormal(s),
     endNormal: socketNormal(e)
   };
@@ -99,6 +103,26 @@ function buildPath(ep, curvature, belly = { x: 0, y: 0 }) {
   };
   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 buildElbowPath(ep) {
+  const { start: s, end: e, startNormal: sn, endNormal: en } = ep;
+  const dx = e.x - s.x;
+  const dy = e.y - s.y;
+  const startVertical = sn.y !== 0 || sn.x === 0 && Math.abs(dy) >= Math.abs(dx);
+  const endVertical = en.y !== 0 || en.x === 0 && Math.abs(dy) >= Math.abs(dx);
+  let pts;
+  if (startVertical && endVertical) {
+    const midY = (s.y + e.y) / 2;
+    pts = [s, { x: s.x, y: midY }, { x: e.x, y: midY }, e];
+  } else if (!startVertical && !endVertical) {
+    const midX = (s.x + e.x) / 2;
+    pts = [s, { x: midX, y: s.y }, { x: midX, y: e.y }, e];
+  } else if (startVertical) {
+    pts = [s, { x: s.x, y: e.y }, e];
+  } else {
+    pts = [s, { x: e.x, y: s.y }, e];
+  }
+  return `M ${r(pts[0].x)} ${r(pts[0].y)}` + pts.slice(1).map((p) => ` L ${r(p.x)} ${r(p.y)}`).join("");
+}
 function routeOffset(start, end, obstacles, padding = 14) {
   const dx = end.x - start.x;
   const dy = end.y - start.y;
@@ -174,12 +198,29 @@ function easeInOutCubic(t) {
 function clamp01(t) {
   return t < 0 ? 0 : t > 1 ? 1 : t;
 }
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
 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 staggerWindows(n, stagger) {
+  if (n <= 0) return [];
+  const s = clamp01(stagger);
+  const span = 1 / (1 + (n - 1) * s);
+  const step = span * s;
+  return Array.from({ length: n }, (_, i) => ({ start: i * step, span }));
+}
+function windowProgress(p, w) {
+  if (w.span <= 0) return p > w.start ? 1 : 0;
+  return clamp01((p - w.start) / w.span);
+}
 function midpointRect(a, b) {
   const ra = docRect(a);
   const rb = docRect(b);
@@ -269,6 +310,25 @@ function clamp012(t) {
 }
 
 // src/draw.ts
+var LABEL_KEYWORDS = {
+  start: 0,
+  middle: 0.5,
+  end: 1
+};
+function resolveLabelAt(value, fallback = 0.5) {
+  if (value == null) return fallback;
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? clamp01(value) : fallback;
+  }
+  const key = value.trim().toLowerCase();
+  const keyword = LABEL_KEYWORDS[key];
+  if (keyword !== void 0) return keyword;
+  if (key.endsWith("%")) {
+    const n = Number.parseFloat(key.slice(0, -1));
+    return Number.isFinite(n) ? clamp01(n / 100) : fallback;
+  }
+  return fallback;
+}
 function lengths(segs) {
   let lineLen = 0;
   let headLen = 0;
@@ -298,7 +358,8 @@ function lineProgress(segs, eased) {
   return lineLen > 0 ? clamp01(drawn / lineLen) : 1;
 }
 function labelOpacity(lineProg, labelAt, fade = 0.08) {
-  return clamp01((lineProg - clamp01(labelAt)) / (fade || 1));
+  const start = Math.min(clamp01(labelAt), 1 - fade);
+  return clamp01((lineProg - start) / (fade || 1));
 }
 
 // src/scroll-arrow.ts
@@ -312,8 +373,17 @@ var ScrollArrow = class {
     this.segments = [];
     /** Representative line stroke + label nodes, when a label is set. */
     this.lineEl = null;
+    /**
+     * The smooth ideal path `d` (pre-roughjs). Label placement measures against
+     * this, not `lineEl`: rough.js bakes its double stroke into one path with two
+     * subpaths, so `lineEl.getTotalLength()` is ~2x the visible curve and would
+     * put `labelAt` at twice its intended fraction.
+     */
+    this.lineD = "";
     this.labelEl = null;
     this.labelBgEl = null;
+    /** `opts.labelAt` resolved to a 0..1 fraction; cached by renderLabel for the draw loop. */
+    this.resolvedLabelAt = 0.5;
     this.rafId = 0;
     this.destroyed = false;
     this.onScroll = () => {
@@ -337,14 +407,36 @@ var ScrollArrow = class {
     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.reducedMotion = this.opts.respectReducedMotion !== false && prefersReducedMotion();
+    this.progress = this.reducedMotion ? 1 : 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.enabled = this.opts.enabled ?? true;
+    if (!this.enabled) this.group.style.display = "none";
     this.render();
     this.bind();
     this.update();
   }
+  /**
+   * Suspend or restore the arrow without tearing it down. Disabling hides it and
+   * stops all draw/scroll work; enabling shows it and recomputes geometry (so it
+   * reflects any layout change that happened while hidden). Idempotent. Wire it
+   * to `matchMedia` to switch arrows off below a breakpoint.
+   */
+  setEnabled(on) {
+    if (on === this.enabled || this.destroyed) return;
+    this.enabled = on;
+    if (on) {
+      this.group.style.display = "";
+      this.render();
+      this.update();
+    } else {
+      this.group.style.display = "none";
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
   /** Manually set draw progress (0..1). Only meaningful when scroll is false. */
   setProgress(p) {
     this.progress = clamp01(p);
@@ -358,6 +450,7 @@ var ScrollArrow = class {
   destroy() {
     this.destroyed = true;
     this.ro?.disconnect();
+    this.teardownReveal();
     window.removeEventListener("scroll", this.onScroll, true);
     window.removeEventListener("resize", this.onScroll);
     cancelAnimationFrame(this.rafId);
@@ -383,17 +476,30 @@ var ScrollArrow = class {
     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);
+  computeEndpoints(sr, er) {
     const ss = this.opts.startSocket ?? "auto";
     const es = this.opts.endSocket ?? "auto";
-    return resolveEndpoints(sr, er, ss, es);
+    return resolveEndpoints(
+      sr,
+      er,
+      ss,
+      es,
+      this.opts.startSocketOffset ?? 0,
+      this.opts.endSocketOffset ?? 0
+    );
   }
   render() {
     while (this.group.firstChild) this.group.removeChild(this.group.firstChild);
     this.segments = [];
-    const ep = this.computeEndpoints();
+    if (!this.enabled) return;
+    const sr = docRect(this.refs.start);
+    const er = docRect(this.refs.end);
+    if (isDegenerateRect(sr) || isDegenerateRect(er)) {
+      this.armReveal();
+      return;
+    }
+    this.teardownReveal();
+    const ep = this.computeEndpoints(sr, er);
     const origin = overlayOrigin(this.svg);
     const shift = (e) => ({
       start: { x: e.start.x - origin.x, y: e.start.y - origin.y },
@@ -410,24 +516,30 @@ var ScrollArrow = class {
       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);
+    let d;
+    if (this.opts.route === "elbow") {
+      d = buildElbowPath(local);
+    } else {
+      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 };
+      d = buildPath(local, curvature, belly);
+    }
+    this.lineD = d;
     this.appendDrawable(this.rc.path(d, roughOpts), "line");
     const head = this.opts.head;
     const size = this.opts.headSize;
@@ -464,25 +576,26 @@ var ScrollArrow = class {
     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);
+    if (!text || !this.lineEl || !this.lineD) return;
+    const at = resolveLabelAt(this.opts.labelAt);
+    this.resolvedLabelAt = at;
+    const measure = createSvgEl("path");
+    measure.setAttribute("d", this.lineD);
+    this.group.appendChild(measure);
+    const total = measure.getTotalLength();
+    const pt = measure.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 before = measure.getPointAtLength(Math.max(0, at * total - eps));
+      const after = measure.getPointAtLength(Math.min(total, at * total + eps));
       const n = unitNormal(before, after);
       x += n.x * offset;
       y += n.y * offset;
     }
+    this.group.removeChild(measure);
     const label = createSvgEl("text");
     label.textContent = text;
     label.setAttribute("x", String(x));
@@ -532,25 +645,43 @@ var ScrollArrow = class {
     if (this.labelEl) {
       const op = labelOpacity(
         lineProgress(this.segments, eased),
-        this.opts.labelAt ?? 0.5
+        this.resolvedLabelAt
       );
       this.labelEl.style.opacity = String(op);
       if (this.labelBgEl) this.labelBgEl.style.opacity = String(op);
     }
   }
+  /**
+   * Watch the anchors for the moment a hidden one becomes laid out, then redraw.
+   * IntersectionObserver fires when a previously `display:none` element gains a
+   * box — a transition ResizeObserver does not reliably report. Armed lazily and
+   * idempotently; torn down by the next successful render(). Guarded so it no-ops
+   * in environments without IntersectionObserver (older engines, some SSR/jsdom).
+   */
+  armReveal() {
+    if (this.revealObs || this.destroyed) return;
+    if (typeof IntersectionObserver === "undefined") return;
+    this.revealObs = new IntersectionObserver(() => this.render());
+    this.revealObs.observe(this.refs.start);
+    this.revealObs.observe(this.refs.end);
+  }
+  teardownReveal() {
+    this.revealObs?.disconnect();
+    this.revealObs = void 0;
+  }
   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) {
+    if (this.opts.scroll !== false && !this.reducedMotion) {
       window.addEventListener("scroll", this.onScroll, true);
       window.addEventListener("resize", this.onScroll);
     }
   }
   update() {
-    if (this.destroyed) return;
-    if (this.opts.scroll === false) {
+    if (this.destroyed || !this.enabled) return;
+    if (this.opts.scroll === false || this.reducedMotion) {
       this.applyProgress();
       return;
     }
@@ -568,8 +699,139 @@ function resolve(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/group.ts
+var ScrollArrowGroup = class {
+  constructor(options) {
+    this.elements = [];
+    this.target = null;
+    this.progress = 0;
+    this.rafId = 0;
+    this.destroyed = false;
+    this.onScroll = () => {
+      if (this.rafId) return;
+      this.rafId = requestAnimationFrame(() => {
+        this.rafId = 0;
+        this.update();
+      });
+    };
+    if (!options.arrows || options.arrows.length === 0) {
+      throw new Error("[scroll-arrows] group needs at least one arrow");
+    }
+    this.opts = {
+      stagger: 1,
+      speed: 1,
+      easing: (t) => t,
+      ...options
+    };
+    this.reducedMotion = this.opts.respectReducedMotion !== false && prefersReducedMotion();
+    this.enabled = this.opts.enabled ?? true;
+    this.arrows = options.arrows.map(
+      (a) => new ScrollArrow({
+        ...a,
+        scroll: false,
+        progress: 0,
+        respectReducedMotion: false,
+        enabled: this.enabled
+      })
+    );
+    this.windows = staggerWindows(this.arrows.length, this.opts.stagger);
+    for (const a of options.arrows) {
+      const s = resolve2(a.start);
+      const e = resolve2(a.end);
+      if (s) this.elements.push(s);
+      if (e) this.elements.push(e);
+    }
+    const scroll = this.opts.scroll;
+    if (scroll !== false && scroll?.target) {
+      this.target = resolve2(scroll.target);
+    }
+    if (this.reducedMotion) this.progress = 1;
+    this.bind();
+    this.update();
+  }
+  /** Manually set group progress (0..1). Only meaningful when scroll is false. */
+  setProgress(p) {
+    this.progress = clamp01(p);
+    this.distribute();
+  }
+  /** Recompute geometry for every arrow (call after layout changes). */
+  refresh() {
+    this.arrows.forEach((a) => a.refresh());
+    this.update();
+  }
+  /**
+   * Suspend or restore the whole group without tearing it down. Hides every
+   * arrow and stops scroll work when off; restores and recomputes when on.
+   * Idempotent. Wire to `matchMedia` for breakpoint-aware diagrams.
+   */
+  setEnabled(on) {
+    if (on === this.enabled || this.destroyed) return;
+    this.enabled = on;
+    this.arrows.forEach((a) => a.setEnabled(on));
+    if (on) {
+      this.bind();
+      this.update();
+    } else {
+      window.removeEventListener("scroll", this.onScroll, true);
+      window.removeEventListener("resize", this.onScroll);
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    window.removeEventListener("scroll", this.onScroll, true);
+    window.removeEventListener("resize", this.onScroll);
+    cancelAnimationFrame(this.rafId);
+    this.arrows.forEach((a) => a.destroy());
+  }
+  // --- internals ---------------------------------------------------------
+  bind() {
+    if (this.opts.scroll === false || this.reducedMotion || !this.enabled)
+      return;
+    window.addEventListener("scroll", this.onScroll, true);
+    window.addEventListener("resize", this.onScroll);
+  }
+  update() {
+    if (this.destroyed || !this.enabled) return;
+    if (this.opts.scroll === false || this.reducedMotion) {
+      this.distribute();
+      return;
+    }
+    const scroll = this.opts.scroll ?? {};
+    const range = scroll.range ?? [0.85, 0.35];
+    const rect = this.target ? docRect(this.target) : this.groupRect();
+    const raw = scrollProgress(rect, range);
+    this.progress = clamp01(raw * this.opts.speed);
+    this.distribute();
+  }
+  /** Push each arrow to its sliced local progress for the current group value. */
+  distribute() {
+    const eased = clamp01(this.opts.easing(this.progress));
+    this.arrows.forEach((arrow, i) => {
+      arrow.setProgress(windowProgress(eased, this.windows[i]));
+    });
+  }
+  /** Synthetic rect spanning every endpoint, used as the default trigger. */
+  groupRect() {
+    const rects = this.elements.map(docRect);
+    if (rects.length === 0) return { left: 0, top: 0, width: 0, height: 0 };
+    let left = Infinity;
+    let top = Infinity;
+    let right = -Infinity;
+    let bottom = -Infinity;
+    for (const r2 of rects) {
+      left = Math.min(left, r2.left);
+      top = Math.min(top, r2.top);
+      right = Math.max(right, r2.left + r2.width);
+      bottom = Math.max(bottom, r2.top + r2.height);
+    }
+    return { left, top, width: right - left, height: bottom - top };
+  }
+};
+function resolve2(ref) {
+  return typeof ref === "string" ? document.querySelector(ref) : ref;
 }
 
 // src/react.tsx
@@ -597,8 +859,33 @@ function ScrollArrowLine(props) {
   useScrollArrow(props);
   return null;
 }
+function useScrollArrowGroup(options) {
+  const groupRef = react.useRef(null);
+  const { arrows, deps = [], ...rest } = options;
+  react.useEffect(() => {
+    const resolved = arrows.map((a) => {
+      const s = read(a.start);
+      const e = read(a.end);
+      if (!s || !e) return null;
+      return { ...a, start: s, end: e };
+    }).filter((a) => a !== null);
+    if (resolved.length === 0) return;
+    const group = new ScrollArrowGroup({ ...rest, arrows: resolved });
+    groupRef.current = group;
+    return () => {
+      group.destroy();
+      groupRef.current = null;
+    };
+  }, deps);
+}
+function ScrollArrowGroupLines(props) {
+  useScrollArrowGroup(props);
+  return null;
+}
 
+exports.ScrollArrowGroupLines = ScrollArrowGroupLines;
 exports.ScrollArrowLine = ScrollArrowLine;
 exports.useScrollArrow = useScrollArrow;
+exports.useScrollArrowGroup = useScrollArrowGroup;
 //# sourceMappingURL=react.cjs.map
 //# sourceMappingURL=react.cjs.map