@aznabee/freehand-ui 0.1.7 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@ Wrap any existing web element with a beautiful, responsive, hand-drawn doodle la
 
 ## What it does
 
-`freehand-ui` adds a subtle SVG overlay on top of your UI - thin pen strokes, handwritten notes, arrows, and small decorations. It does not change your element's own styling and never blocks clicks (`pointer-events: none`).
+`freehand-ui` adds a subtle SVG overlay on top of your UI - thin pen strokes, handwritten notes, arrows, and small decorations. It does **not** change your HTML layout or block clicks (`pointer-events: none`).
 
 **Good for:** call-to-action buttons, feature cards, onboarding hints, playful marketing UI.
 
@@ -19,8 +19,6 @@ Wrap any existing web element with a beautiful, responsive, hand-drawn doodle la
 | **Localised**   | Notes in the visitor's own language, right-to-left included          |
 | **Responsive**  | Stays aligned on resize, scroll, and reflow                          |
 
-**DOM note:** the element is wrapped in a plain positioning `<div>` so the overlay can be mounted beside it (last child, so it paints on top) - the wrapped element keeps its own display and, in a flex/grid parent, its own placement, but a selector depending on it being a *direct* child of its original parent (`.parent > .card`, `:nth-child`) will no longer match. The overlay is also clipped by an `overflow: hidden` ancestor, since it no longer escapes the page via `position: fixed`.
-
 **Live on [Aznabee.com](https://aznabee.com)** - see it in production on the real product.
 
 ## ![Basic hand-drawn border around a card](docs/images/basic.png)
@@ -257,7 +255,7 @@ A `dotted` arrow spends its dash pattern on the dots, and one pattern cannot bot
 Notes:
 
 - **`prefers-reduced-motion: reduce` turns both gestures off** and leaves the arrow fully drawn.
-- The overlay moves with the element for free through ordinary layout - scrolling, a sibling loading in above it - and is only rebuilt when the element's own size actually changes. Animations are placed by how long the overlay has been on the page rather than restarted, so repositioning never replays a draw or jolts a lean mid-cycle.
+- The overlay is rebuilt on every scroll and resize. Animations are placed by how long the overlay has been on the page rather than restarted, so scrolling never replays a draw or jolts a lean mid-cycle.
 
 ### Decorations
 
@@ -426,7 +424,41 @@ Server-rendered markup is unaffected: the overlay is drawn in an effect, so the
 
 - Inline object props (`note={{ text: "hi" }}`) are compared by value, so a re-render does not tear down and redraw the overlay with a new random seed.
 - `disabled` skips drawing entirely - useful behind a reduced-motion check or a feature flag.
-- TypeScript definitions ship with the package for both entry points.
+- TypeScript definitions ship with the package for every entry point.
+
+---
+
+## React Native
+
+The same doodles, drawn with [react-native-svg](https://github.com/software-mansion/react-native-svg). Import from the `native` entry point - it needs `react-native-svg` installed in the app.
+
+```bash
+npm install @aznabee/freehand-ui react-native-svg
+```
+
+```tsx
+import Doodle from "@aznabee/freehand-ui/native";
+
+<Doodle
+  note={{ text: "start chat", position: "bottom", underline: false }}
+  arrow={{ from: "left", to: "edge", style: "curved" }}
+  decorations={{ types: ["heart"] }}
+  radius={16}
+>
+  <TouchableOpacity onPress={start}>...</TouchableOpacity>
+</Doodle>
+```
+
+`<Doodle>` is a plain `View` - every `View` prop passes through - and takes the same options as the web component. The doodle is drawn in an absolutely positioned layer that ignores touches and never affects layout, so, as on the web, an ancestor with `overflow: "hidden"` clips it.
+
+Differences from the web:
+
+- **Corner radius** is not detected from the children. Pass `radius`, or it is read from the wrapper's own `borderRadius` style.
+- **Handwriting** uses the platform's built-in face - Noteworthy on iOS, `casual` on Android - because nothing is fetched at runtime. Link Caveat into the app and pass `fontFamily="Caveat"` to match the web exactly.
+- **Note width** is estimated from the glyphs rather than measured, which is close enough to place the note and its underline.
+- **Arrows** draw on and lean as they do on the web (the lean runs on the native driver). A dotted shaft stays still instead of crawling. Both are skipped when the OS asks for reduced motion.
+- **Language**: React Native has no `navigator.languages`, so pass `locale` (your app's i18n language) to choose from a multilingual note.
+- `childSelector` has no equivalent.
 
 ---
 
@@ -456,7 +488,7 @@ Then open:
 - **Framework agnostic** - plain JavaScript at the core; React is an optional entry point
 - **SVG based** - hand-drawn paths, not CSS borders
 - **Non-invasive** - `pointer-events: none`, no layout changes
-- **Responsive** - absolutely positioned beside the element, so it tracks scroll and layout shifts for free; `ResizeObserver` covers the rest
+- **Responsive** - `ResizeObserver`, scroll listeners, and `requestAnimationFrame`
 - **Lightweight** - zero runtime dependencies
 
 ---

package/dist/freehand-ui.cjs

@@ -312,6 +312,10 @@ var DEFAULT_OPTIONS = {
    */
   zIndex: null
 };
+var OVERLAY_CLASS = "doodle-ui-overlay";
+function isOverlayNode(node) {
+  return node?.classList?.contains(OVERLAY_CLASS) ?? false;
+}
 function resolveElement(target) {
   if (!target) return null;
   if (typeof target === "string") {
@@ -417,45 +421,21 @@ function resolveOverlayZIndex(element, override) {
   }
   return null;
 }
-var ITEM_PLACEMENT_PROPERTIES = [
-  "order",
-  "flexGrow",
-  "flexShrink",
-  "flexBasis",
-  "alignSelf",
-  "justifySelf",
-  "gridColumn",
-  "gridRow",
-  "gridArea"
-];
-function isInlineDisplay(computed) {
-  return computed.display.startsWith("inline");
-}
 function insertOverlaySvg(svg, element) {
-  const parent = element.parentNode;
-  if (!parent) {
-    document.body.appendChild(svg);
-    return null;
-  }
-  const wrapper = document.createElement("div");
-  wrapper.style.position = "relative";
-  const computed = getComputedStyle(element);
-  wrapper.style.display = isInlineDisplay(computed) ? "inline-block" : "block";
-  for (const property of ITEM_PLACEMENT_PROPERTIES) {
-    const value = computed[property];
-    if (value) wrapper.style[property] = value;
-  }
-  parent.replaceChild(wrapper, element);
-  wrapper.appendChild(element);
-  wrapper.appendChild(svg);
-  return wrapper;
-}
-function removeOverlaySvg(svg, wrapper, element) {
+  const setPosition = getComputedStyle(element).position === "static";
+  if (setPosition) {
+    element.style.position = "relative";
+  }
+  element.appendChild(svg);
+  return setPosition;
+}
+function removeOverlaySvg(svg, element, clearPosition) {
   if (svg.parentNode) {
     svg.parentNode.removeChild(svg);
   }
-  if (!wrapper || !wrapper.parentNode) return;
-  wrapper.parentNode.replaceChild(element, wrapper);
+  if (clearPosition) {
+    element.style.position = "";
+  }
 }
 function syncOverlayStacking(svg, element, zIndexOverride) {
   const zIndex = resolveOverlayZIndex(element, zIndexOverride);
@@ -482,7 +462,10 @@ function averageCornerRadius(element) {
 function detectBorderRadius(element) {
   const own = averageCornerRadius(element);
   if (own > 0) return own;
-  const child = element.children.length === 1 ? element.firstElementChild : null;
+  const content = Array.from(element.children).filter(
+    (node) => !isOverlayNode(node)
+  );
+  const child = content.length === 1 ? content[0] : null;
   if (!child) return 0;
   const outer = element.getBoundingClientRect();
   const inner = child.getBoundingClientRect();
@@ -513,22 +496,6 @@ function relativeRect(outer, inner) {
     radius: inner.radius
   };
 }
-function unionRects(rects, margin = 0) {
-  if (rects.length === 0) {
-    return { x: 0, y: 0, width: 0, height: 0, radius: 0 };
-  }
-  const minX = Math.min(...rects.map((r) => r.x)) - margin;
-  const minY = Math.min(...rects.map((r) => r.y)) - margin;
-  const maxX = Math.max(...rects.map((r) => r.x + r.width)) + margin;
-  const maxY = Math.max(...rects.map((r) => r.y + r.height)) + margin;
-  return {
-    x: minX,
-    y: minY,
-    width: maxX - minX,
-    height: maxY - minY,
-    radius: 0
-  };
-}
 function inflateRect(rect, amount) {
   return {
     x: rect.x - amount,
@@ -610,8 +577,13 @@ function annotationAnchor(position, rect, offset = 12) {
   return point;
 }
 
-// src/renderer.js
+// src/svg-dom.js
 var SVG_NS = "http://www.w3.org/2000/svg";
+function createSvgElement(tag) {
+  return document.createElementNS(SVG_NS, tag);
+}
+
+// src/renderer.js
 var XML_NS = "http://www.w3.org/XML/1998/namespace";
 var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
@@ -835,7 +807,7 @@ function createBorderBreaks(perimeter, config, random) {
   return breaks;
 }
 function createGroup(parent, x, y, rotation = 0) {
-  const group = document.createElementNS(SVG_NS, "g");
+  const group = createSvgElement("g");
   group.setAttribute(
     "transform",
     `translate(${fmt(x)} ${fmt(y)}) rotate(${rotation.toFixed(1)})`
@@ -844,7 +816,7 @@ function createGroup(parent, x, y, rotation = 0) {
   return group;
 }
 function appendPath(svg, d, style) {
-  const path = document.createElementNS(SVG_NS, "path");
+  const path = createSvgElement("path");
   path.setAttribute("d", d);
   path.setAttribute("fill", style.fill ?? "none");
   path.setAttribute("stroke", style.color);
@@ -859,7 +831,7 @@ function appendPath(svg, d, style) {
   return path;
 }
 function appendGlow(svg, radius, style) {
-  const circle = document.createElementNS(SVG_NS, "circle");
+  const circle = createSvgElement("circle");
   circle.setAttribute("r", fmt(radius));
   circle.setAttribute("fill", style.color);
   circle.setAttribute("opacity", String(style.opacity));
@@ -1163,7 +1135,7 @@ function drawArrow(svg, rect, arrowOptions, style, seed, origin = null, context
       tipAngle = Math.atan2(end.y - c2y, end.x - c2x);
     }
   }
-  const group = document.createElementNS(SVG_NS, "g");
+  const group = createSvgElement("g");
   svg.appendChild(group);
   const shaftPaths = [];
   if (ghost) {
@@ -1253,8 +1225,8 @@ function createNoteText(svg, text, style, options = {}) {
   const lines = wrapWords(text, options.wordsPerLine ?? DEFAULT_WORDS_PER_LINE);
   const lineHeight = fontSize * 1.05;
   const rtl = options.rtl ?? isRtlText(text);
-  const group = document.createElementNS(SVG_NS, "g");
-  const textEl = document.createElementNS(SVG_NS, "text");
+  const group = createSvgElement("g");
+  const textEl = createSvgElement("text");
   textEl.setAttribute("x", "0");
   textEl.setAttribute("y", "0");
   textEl.setAttribute("fill", style.color);
@@ -1273,7 +1245,7 @@ function createNoteText(svg, text, style, options = {}) {
     textEl.setAttributeNS(XML_NS, "xml:lang", options.locale);
   }
   const tspans = lines.map((line, index) => {
-    const tspan = document.createElementNS(SVG_NS, "tspan");
+    const tspan = createSvgElement("tspan");
     tspan.textContent = line;
     tspan.setAttribute("x", "0");
     tspan.setAttribute("dy", index === 0 ? "0" : String(lineHeight));
@@ -1337,8 +1309,8 @@ function placeNoteText(note, box, style, seed, options = {}) {
   return note.group;
 }
 function createOverlaySvg(left, top, width, height) {
-  const svg = document.createElementNS(SVG_NS, "svg");
-  svg.setAttribute("class", "doodle-ui-overlay");
+  const svg = createSvgElement("svg");
+  svg.setAttribute("class", OVERLAY_CLASS);
   svg.setAttribute("xmlns", SVG_NS);
   svg.setAttribute("width", String(width));
   svg.setAttribute("height", String(height));
@@ -1880,13 +1852,27 @@ var instances = /* @__PURE__ */ new WeakMap();
 function now() {
   return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
 }
-function localBand(overlayRect, inset = 8) {
+function localBand(originLeft, inset = 8) {
   const width = window.innerWidth || document.documentElement.clientWidth || 0;
   return {
-    x: -overlayRect.x + inset,
+    x: -originLeft + inset,
     width: Math.max(0, width - inset * 2)
   };
 }
+function paddingBox(element) {
+  const rect = element.getBoundingClientRect();
+  const style = getComputedStyle(element);
+  const left = parseFloat(style.borderLeftWidth) || 0;
+  const top = parseFloat(style.borderTopWidth) || 0;
+  const right = parseFloat(style.borderRightWidth) || 0;
+  const bottom = parseFloat(style.borderBottomWidth) || 0;
+  return {
+    left: rect.left + left,
+    top: rect.top + top,
+    width: Math.max(0, rect.width - left - right),
+    height: Math.max(0, rect.height - top - bottom)
+  };
+}
 var DoodleOverlay = class {
   /**
    * @param {Element} element
@@ -1898,7 +1884,7 @@ var DoodleOverlay = class {
     this.seed = Math.floor(Math.random() * 1e9);
     this.startedAt = now();
     this.svg = null;
-    this.wrapper = null;
+    this.setPosition = false;
     this.resizeObserver = null;
     this.mutationObserver = null;
     this.pendingFrame = null;
@@ -1910,14 +1896,17 @@ var DoodleOverlay = class {
   }
   mount() {
     this.svg = createOverlaySvg(0, 0, 0, 0);
-    this.wrapper = insertOverlaySvg(this.svg, this.element);
+    this.setPosition = insertOverlaySvg(this.svg, this.element);
     syncOverlayStacking(this.svg, this.element, this.options.zIndex);
     this.resizeObserver = new ResizeObserver(this.onResize);
     this.resizeObserver.observe(this.element);
     if (this.options.children) {
       this.observeChildren();
     }
-    this.mutationObserver = new MutationObserver(this.scheduleUpdate.bind(this));
+    this.mutationObserver = new MutationObserver((records) => {
+      const relevant = records.some((record) => !this.svg.contains(record.target));
+      if (relevant) this.scheduleUpdate();
+    });
     this.mutationObserver.observe(this.element, {
       childList: true,
       subtree: true,
@@ -1969,22 +1958,23 @@ var DoodleOverlay = class {
     if (!this.svg || !this.element.isConnected) return;
     const { padding, radius, color, strokeWidth, roughness, opacity } = this.options;
     const targets = this.getTargets();
-    const margin = this.overlayMargin();
     const elapsed = now() - this.startedAt;
     const absoluteRects = targets.map(
       (target) => getElementBounds(target, padding, radius)
     );
-    const overlayRect = unionRects(absoluteRects, margin);
     clearSvg(this.svg);
     syncOverlayStacking(this.svg, this.element, this.options.zIndex);
-    const origin = this.wrapper ? this.wrapper.getBoundingClientRect() : { left: 0, top: 0 };
-    this.svg.setAttribute("width", String(overlayRect.width));
-    this.svg.setAttribute("height", String(overlayRect.height));
-    this.svg.setAttribute("viewBox", `0 0 ${overlayRect.width} ${overlayRect.height}`);
-    this.svg.style.left = `${overlayRect.x - origin.left}px`;
-    this.svg.style.top = `${overlayRect.y - origin.top}px`;
-    this.svg.style.width = `${overlayRect.width}px`;
-    this.svg.style.height = `${overlayRect.height}px`;
+    const box = paddingBox(this.element);
+    const width = Math.max(1, box.width);
+    const height = Math.max(1, box.height);
+    const origin = { x: box.left, y: box.top };
+    this.svg.setAttribute("width", String(width));
+    this.svg.setAttribute("height", String(height));
+    this.svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
+    this.svg.style.left = "0px";
+    this.svg.style.top = "0px";
+    this.svg.style.width = `${width}px`;
+    this.svg.style.height = `${height}px`;
     const strokeStyle = { color, strokeWidth, roughness, opacity };
     const noteStyle = {
       color,
@@ -1995,12 +1985,12 @@ var DoodleOverlay = class {
     };
     const noteGroups = [];
     const noteLayout = {
-      band: localBand(overlayRect),
+      band: localBand(origin.x),
       gap: this.options.arrow ? 40 : 14
     };
     targets.forEach((target, index) => {
       const absolute = absoluteRects[index];
-      const local = relativeRect(overlayRect, absolute);
+      const local = relativeRect(origin, absolute);
       const seed = this.seed + index * 31;
       const note = this.options.note && index === 0 ? renderAnnotation(
         this.svg,
@@ -2046,15 +2036,6 @@ var DoodleOverlay = class {
       this.svg.appendChild(group);
     }
   }
-  /**
-   * Room the overlay needs beyond the element for notes, arrows and decorations.
-   */
-  overlayMargin() {
-    const { note, arrow, decorations } = this.options;
-    if (!note && !arrow && !decorations) return 48;
-    const { text } = resolveLocalizedText(note?.text, note?.locale);
-    return Math.max(96, Math.min(240, 80 + text.length * 8));
-  }
   destroy() {
     if (this.pendingFrame != null) {
       cancelFrame(this.pendingFrame);
@@ -2077,10 +2058,9 @@ var DoodleOverlay = class {
     }
     this.listeners = [];
     if (this.svg) {
-      removeOverlaySvg(this.svg, this.wrapper, this.element);
+      removeOverlaySvg(this.svg, this.element, this.setPosition);
     }
     this.svg = null;
-    this.wrapper = null;
     instances.delete(this.element);
   }
 };