scroll-arrows 0.1.3 → 0.2.0

package/README.md

@@ -57,13 +57,94 @@ arrow.destroy();
 - **Obstacle routing** — pass `avoid` (an element or array) and the curve bows
   around them with an `avoidPadding` gap instead of cutting through. Single-bend
   router: it clears the worst blocker, not a full path-finder.
+- **Shared-origin fan-out** — when several arrows leave the same element they all
+  resolve to the same edge point and stack. Slide each along its edge with
+  `startSocketOffset` / `endSocketOffset` (a fraction of the edge length, `0` =
+  centered, `±0.5` = corners) to spread them — e.g. `-0.25`, `0`, `+0.25` for
+  three siblings off one parent.
+- **Elbow routing** — set `route: 'elbow'` for right-angle connectors (the
+  classic tree / org-chart bracket) instead of a smooth curve. Same-axis sockets
+  get a centered Z-bracket, perpendicular sockets a single L-corner. Pair with
+  explicit `startSocket` / `endSocket` for predictable shapes. Elbow mode ignores
+  `avoid` and `curvature`.
+- **Hidden anchors (tabs / accordions)** — an anchor inside a `display:none`
+  container has no box, so the arrow can't be drawn yet. Instead of rendering a
+  collapsed/garbage line, it draws nothing and **auto-redraws the moment the
+  anchor is revealed** (via `IntersectionObserver`). For full control — or for
+  engines without `IntersectionObserver` — call `arrow.refresh()` from your
+  tab/accordion show handler:
+
+  ```ts
+  const arrow = scrollArrow({ start: '#a', end: '#tab-2-target' });
+
+  tabButton.addEventListener('click', () => {
+    showTabPanel(2); // your code reveals the panel
+    arrow.refresh(); // recompute now that the anchor has a box
+  });
+  ```
+
 - **Manual mode** — `scroll: false` + `setProgress(0..1)` to drive it yourself
   (e.g. from GSAP/Motion).
+- **Reduced motion** — arrows auto-respect `prefers-reduced-motion: reduce`,
+  rendering fully drawn and static (no scroll animation) while still tracking
+  layout. Opt out with `respectReducedMotion: false` to keep the animation.
+  Works the same for `scrollArrowGroup`.
 - **Labels** — `label` rides along the line at `labelAt` (0..1, default mid)
   and can sit off the line via `labelOffset` (perpendicular px; + = left of the
   draw direction, − = right). Fades in as the pen draws through it.
   `labelBackground` masks a gap in the line behind the text (the excalidraw
   look); style via `labelColor` / `font`.
+- **Staggered groups** — `scrollArrowGroup` owns N arrows and reveals them in
+  sequence off one shared trigger (`A then B then C`). `stagger` (0..1) controls
+  overlap: `1` draws each in its own slice, `0` draws them together.
+
+## Groups (staggered reveal)
+
+For diagrams (org/family trees, flows) where a set of arrows should draw in
+order rather than each on its own scroll, use a group. It creates the arrows in
+manual mode and drives their progress as one coordinated reveal.
+
+```ts
+import { scrollArrowGroup } from 'scroll-arrows';
+
+const group = scrollArrowGroup({
+  arrows: [
+    { start: '#a', end: '#b', roughness: 0.6 },
+    { start: '#b', end: '#c', roughness: 0.6 },
+    { start: '#b', end: '#d', roughness: 0.6 },
+  ],
+  stagger: 1, // 0 = all together, 1 = fully sequential (default)
+  scroll: { target: '#diagram' }, // shared trigger; defaults to all endpoints
+});
+
+// later
+group.destroy();
+```
+
+Each entry takes the usual per-arrow options. The group forces `scroll: false`
+on each arrow and slices its own progress across them. Pass `scroll: false` to
+drive the whole group yourself with `group.setProgress(0..1)`; `group.refresh()`
+recomputes every arrow's geometry. The default `scroll.target` is a synthetic
+rect spanning every endpoint, so the group reveals as it scrolls into view.
+
+## Breakpoints / responsive
+
+When a diagram reflows on small screens (absolute overlay → vertical stack), the
+arrows usually should disappear. Use `setEnabled(on)` to suspend and restore an
+arrow **without tearing it down** — disabling hides it and stops all scroll work;
+enabling shows it and recomputes geometry. Wire it to `matchMedia`:
+
+```ts
+const arrow = scrollArrow({ start: '#a', end: '#b' });
+
+const mq = window.matchMedia('(max-width: 30rem)');
+const sync = () => arrow.setEnabled(!mq.matches); // off below 30rem
+sync();
+mq.addEventListener('change', sync);
+```
+
+Pass `enabled: false` to start hidden. `scrollArrowGroup` has the same
+`enabled` option and `setEnabled(on)`, toggling the whole set at once.
 
 ## React
 
@@ -88,6 +169,19 @@ function Diagram() {
 arrow via effect and cleans up on unmount. `useScrollArrow(opts)` is the hook
 form. Pass `deps={[...]}` to re-create when inputs change.
 
+For a staggered group, `ScrollArrowGroupLines` (and the `useScrollArrowGroup`
+hook) take an `arrows` array whose `start`/`end` accept refs:
+
+```tsx
+<ScrollArrowGroupLines
+  arrows={[
+    { start: a, end: b },
+    { start: b, end: c },
+  ]}
+  stagger={1}
+/>
+```
+
 ## Astro
 
 The core is DOM-only, so run it in a client script (it must execute in the
@@ -112,14 +206,36 @@ For an Astro React island, use the React API and hydrate with `client:visible`:
 <Diagram client:visible />
 ```
 
+## SSR & progressive enhancement
+
+scroll-arrows is **progressive-enhancement only by design**. The arrow is an
+overlay `<svg>` created by the client script at runtime — there is no
+server-rendered or build-time output. In SSG/SSR setups (Astro, Next, etc.) the
+connector simply does not exist until the script runs, so:
+
+- **No-JS / pre-hydration users see nothing** where an arrow would be. Arrows
+  are treated as decorative enhancement, not content.
+- Don't encode meaning solely in an arrow. If a relationship must survive without
+  JS (accessibility, SEO, no-JS fallback), express it in the DOM too — adjacent
+  copy, a list, a caption, an `aria-label` — and let the arrow decorate it.
+- The library ships no static snapshot. Geometry depends on the live, laid-out
+  positions of both anchors (and the viewport), which aren't known at build time,
+  so a server-rendered arrow would usually be wrong anyway.
+
+If you genuinely need a static connector in the un-hydrated state, hand-author a
+plain `<svg>` in your markup and let scroll-arrows draw over it on hydration —
+the runtime arrow mounts in its own overlay and won't clash with your static one.
+
 ## API
 
 `scrollArrow(options)` / `new ScrollArrow(options)` → instance with
 `setProgress(p)`, `refresh()`, `destroy()`.
 
 Key options: `start`, `end`, `container`, `roughness`, `stroke`, `strokeWidth`,
-`seed`, `startSocket`, `endSocket`, `curvature`, `head`, `headSize`, `scroll`,
-`speed`, `easing`, `progress`. Full types ship with the package.
+`seed`, `startSocket`, `endSocket`, `startSocketOffset`, `endSocketOffset`,
+`curvature`, `route`, `head`, `headSize`, `scroll`, `speed`, `easing`,
+`progress`, `enabled`. Full types ship with the package. `setEnabled(on)` toggles
+an arrow (and a group) on/off without teardown.
 
 ## Develop
 

package/dist/{chunk-GKWBGFLA.js → chunk-LIT577GH.js}

@@ -16,20 +16,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;
   }
@@ -62,12 +66,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)
   };
@@ -90,6 +94,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;
@@ -165,12 +189,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);
@@ -328,14 +369,36 @@ var ScrollArrow = class {
     this.svg = getOverlay(this.container);
     this.rc = rough.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);
@@ -349,6 +412,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);
@@ -374,17 +438,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 },
@@ -401,24 +478,29 @@ 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.appendDrawable(this.rc.path(d, roughOpts), "line");
     const head = this.opts.head;
     const size = this.opts.headSize;
@@ -529,19 +611,37 @@ var ScrollArrow = class {
       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;
     }
@@ -563,6 +663,140 @@ function clampAt(t) {
   return t < 0 ? 0 : t > 1 ? 1 : t;
 }
 
-export { ScrollArrow, easeInOutCubic };
-//# sourceMappingURL=chunk-GKWBGFLA.js.map
-//# sourceMappingURL=chunk-GKWBGFLA.js.map
+// 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;
+}
+
+export { ScrollArrow, ScrollArrowGroup, easeInOutCubic };
+//# sourceMappingURL=chunk-LIT577GH.js.map
+//# sourceMappingURL=chunk-LIT577GH.js.map