@aznabee/freehand-ui 0.1.1 → 0.1.2

package/README.md

@@ -84,6 +84,8 @@ function Card() {
 
 - 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.
+- The handwriting font is fetched automatically — see [Handwriting
+  font](#handwriting-font) to use `next/font` or self-host instead.
 - `disabled` skips drawing entirely — useful behind a reduced-motion check or a
   feature flag.
 - TypeScript definitions ship with the package for both entry points.
@@ -96,13 +98,51 @@ doodle(".card", {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 8,
-  radius: 20,       // optional override; auto-detected from CSS when omitted
+  padding: 0,        // gap between the element's edge and the frame
+  radius: 20,        // optional override; auto-detected from CSS when omitted
   opacity: 0.9,
-  addBreaks: false, // lift the pen at random points around the outline
+  addBreaks: false,  // lift the pen at random points around the outline
+  fontFamily: null,  // override the handwriting stack
+  autoLoadFont: true,
 });
 ```
 
+The frame traces the element's own edge by default. Raise `padding` to stand it
+off — `padding: 8` leaves a comfortable margin around a card.
+
+## Handwriting font
+
+Notes are set in [Caveat](https://fonts.google.com/specimen/Caveat). The library
+loads it for you the first time a note is drawn, so the handwriting looks right
+in a plain app with no font setup of its own — without it the text falls back to
+the generic `cursive` family, which on macOS is a calligraphic serif rather than
+anything handwritten.
+
+It skips the request when the page already provides the family, and only ever
+requests it once. To take over:
+
+```javascript
+// self-hosted, or already loaded elsewhere on the page
+doodle(".card", { note: "hi", autoLoadFont: false });
+
+// your own family — a next/font CSS variable, for instance
+doodle(".card", { note: "hi", fontFamily: "var(--font-caveat)" });
+```
+
+```jsx
+import { Caveat } from "next/font/google";
+const caveat = Caveat({ subsets: ["latin"], variable: "--font-caveat" });
+
+<Doodle note="start chat" fontFamily="var(--font-caveat)" autoLoadFont={false}>
+  <Button />
+</Doodle>;
+```
+
+Setting `autoLoadFont: false` without a `fontFamily` falls back to whatever
+handwriting faces the system has (Bradley Hand, Segoe Script, Comic Sans MS).
+Notes are re-measured when a font finishes loading, so the underline always
+matches the final glyph widths.
+
 ## Broken outlines
 
 `addBreaks` cuts randomly sized gaps into the border, so it reads as a few

package/dist/freehand-ui.cjs

@@ -29,14 +29,19 @@ var DEFAULT_OPTIONS = {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 8,
+  // The frame traces the element's own edge. Raise this to stand it off.
+  padding: 0,
   radius: null,
   opacity: 0.9,
   children: null,
   note: null,
   arrow: false,
   decorations: false,
-  addBreaks: false
+  addBreaks: false,
+  /** Override the handwriting stack, e.g. a next/font CSS variable. */
+  fontFamily: null,
+  /** Fetch Caveat when the page has not provided it. */
+  autoLoadFont: true
 };
 function resolveElement(target) {
   if (!target) return null;
@@ -262,7 +267,7 @@ function annotationAnchor(position, rect, offset = 12) {
 
 // src/renderer.js
 var SVG_NS = "http://www.w3.org/2000/svg";
-var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", cursive';
+var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
 function clearSvg(svg) {
   while (svg.firstChild) {
@@ -741,7 +746,7 @@ function createNoteText(svg, text, style) {
   textEl.setAttribute("fill", style.color);
   textEl.setAttribute("opacity", String(style.opacity));
   textEl.setAttribute("font-size", String(fontSize));
-  textEl.setAttribute("font-family", HANDWRITTEN_FONT);
+  textEl.setAttribute("font-family", style.fontFamily || HANDWRITTEN_FONT);
   textEl.setAttribute("font-weight", "600");
   textEl.setAttribute("letter-spacing", "0.4");
   textEl.setAttribute("text-anchor", "start");
@@ -1314,6 +1319,27 @@ function renderDecorations(svg, rect, decorationOptions, style, seed, context =
   }
 }
 
+// src/fonts.js
+var FONT_NAME = "Caveat";
+var FONT_HREF = "https://fonts.googleapis.com/css2?family=Caveat:wght@400;600&display=swap";
+var MARKER = "data-freehand-font";
+var requested = false;
+function ensureHandwrittenFont() {
+  if (requested) return;
+  if (typeof document === "undefined" || !document.head) return;
+  requested = true;
+  try {
+    if (document.fonts?.check?.(`600 19px "${FONT_NAME}"`)) return;
+  } catch {
+  }
+  if (document.querySelector(`link[${MARKER}]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = FONT_HREF;
+  link.setAttribute(MARKER, "");
+  document.head.appendChild(link);
+}
+
 // src/doodle.js
 var instances = /* @__PURE__ */ new WeakMap();
 function localViewport(overlayRect, inset = 8) {
@@ -1365,7 +1391,12 @@ var DoodleOverlay = class {
     }
     window.addEventListener("resize", this.onResize, { passive: true });
     this.scrollTargets.push({ target: window, type: "resize" });
-    document.fonts?.ready?.then(() => this.scheduleUpdate()).catch(() => {
+    if (this.options.note && this.options.autoLoadFont && !this.options.fontFamily) {
+      ensureHandwrittenFont();
+    }
+    this.onFontsLoaded = () => this.scheduleUpdate();
+    document.fonts?.addEventListener?.("loadingdone", this.onFontsLoaded);
+    document.fonts?.ready?.then(this.onFontsLoaded).catch(() => {
     });
     this.update();
   }
@@ -1408,7 +1439,13 @@ var DoodleOverlay = class {
     this.svg.style.width = `${overlayRect.width}px`;
     this.svg.style.height = `${overlayRect.height}px`;
     const strokeStyle = { color, strokeWidth, roughness, opacity };
-    const noteStyle = { color, opacity, strokeWidth, roughness };
+    const noteStyle = {
+      color,
+      opacity,
+      strokeWidth,
+      roughness,
+      fontFamily: this.options.fontFamily
+    };
     const noteGroups = [];
     const noteLayout = {
       viewport: localViewport(overlayRect),
@@ -1483,6 +1520,10 @@ var DoodleOverlay = class {
       this.mutationObserver.disconnect();
       this.mutationObserver = null;
     }
+    if (this.onFontsLoaded) {
+      document.fonts?.removeEventListener?.("loadingdone", this.onFontsLoaded);
+      this.onFontsLoaded = null;
+    }
     for (const { target, type } of this.scrollTargets) {
       target.removeEventListener(type, type === "scroll" ? this.onScroll : this.onResize);
     }

package/dist/freehand-ui.js

@@ -4,14 +4,19 @@ var DEFAULT_OPTIONS = {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 8,
+  // The frame traces the element's own edge. Raise this to stand it off.
+  padding: 0,
   radius: null,
   opacity: 0.9,
   children: null,
   note: null,
   arrow: false,
   decorations: false,
-  addBreaks: false
+  addBreaks: false,
+  /** Override the handwriting stack, e.g. a next/font CSS variable. */
+  fontFamily: null,
+  /** Fetch Caveat when the page has not provided it. */
+  autoLoadFont: true
 };
 function resolveElement(target) {
   if (!target) return null;
@@ -237,7 +242,7 @@ function annotationAnchor(position, rect, offset = 12) {
 
 // src/renderer.js
 var SVG_NS = "http://www.w3.org/2000/svg";
-var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", cursive';
+var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
 function clearSvg(svg) {
   while (svg.firstChild) {
@@ -716,7 +721,7 @@ function createNoteText(svg, text, style) {
   textEl.setAttribute("fill", style.color);
   textEl.setAttribute("opacity", String(style.opacity));
   textEl.setAttribute("font-size", String(fontSize));
-  textEl.setAttribute("font-family", HANDWRITTEN_FONT);
+  textEl.setAttribute("font-family", style.fontFamily || HANDWRITTEN_FONT);
   textEl.setAttribute("font-weight", "600");
   textEl.setAttribute("letter-spacing", "0.4");
   textEl.setAttribute("text-anchor", "start");
@@ -1289,6 +1294,27 @@ function renderDecorations(svg, rect, decorationOptions, style, seed, context =
   }
 }
 
+// src/fonts.js
+var FONT_NAME = "Caveat";
+var FONT_HREF = "https://fonts.googleapis.com/css2?family=Caveat:wght@400;600&display=swap";
+var MARKER = "data-freehand-font";
+var requested = false;
+function ensureHandwrittenFont() {
+  if (requested) return;
+  if (typeof document === "undefined" || !document.head) return;
+  requested = true;
+  try {
+    if (document.fonts?.check?.(`600 19px "${FONT_NAME}"`)) return;
+  } catch {
+  }
+  if (document.querySelector(`link[${MARKER}]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = FONT_HREF;
+  link.setAttribute(MARKER, "");
+  document.head.appendChild(link);
+}
+
 // src/doodle.js
 var instances = /* @__PURE__ */ new WeakMap();
 function localViewport(overlayRect, inset = 8) {
@@ -1340,7 +1366,12 @@ var DoodleOverlay = class {
     }
     window.addEventListener("resize", this.onResize, { passive: true });
     this.scrollTargets.push({ target: window, type: "resize" });
-    document.fonts?.ready?.then(() => this.scheduleUpdate()).catch(() => {
+    if (this.options.note && this.options.autoLoadFont && !this.options.fontFamily) {
+      ensureHandwrittenFont();
+    }
+    this.onFontsLoaded = () => this.scheduleUpdate();
+    document.fonts?.addEventListener?.("loadingdone", this.onFontsLoaded);
+    document.fonts?.ready?.then(this.onFontsLoaded).catch(() => {
     });
     this.update();
   }
@@ -1383,7 +1414,13 @@ var DoodleOverlay = class {
     this.svg.style.width = `${overlayRect.width}px`;
     this.svg.style.height = `${overlayRect.height}px`;
     const strokeStyle = { color, strokeWidth, roughness, opacity };
-    const noteStyle = { color, opacity, strokeWidth, roughness };
+    const noteStyle = {
+      color,
+      opacity,
+      strokeWidth,
+      roughness,
+      fontFamily: this.options.fontFamily
+    };
     const noteGroups = [];
     const noteLayout = {
       viewport: localViewport(overlayRect),
@@ -1458,6 +1495,10 @@ var DoodleOverlay = class {
       this.mutationObserver.disconnect();
       this.mutationObserver = null;
     }
+    if (this.onFontsLoaded) {
+      document.fonts?.removeEventListener?.("loadingdone", this.onFontsLoaded);
+      this.onFontsLoaded = null;
+    }
     for (const { target, type } of this.scrollTargets) {
       target.removeEventListener(type, type === "scroll" ? this.onScroll : this.onResize);
     }

package/dist/index.d.ts

@@ -59,6 +59,7 @@ export interface DoodleOptions {
   color?: string;
   strokeWidth?: number;
   roughness?: number;
+  /** Gap between the element's edge and the frame. Default `0`. */
   padding?: number;
   /** Auto-detected from CSS when omitted. */
   radius?: number | null;
@@ -70,6 +71,18 @@ export interface DoodleOptions {
   decorations?: boolean | DecorationOptions;
   /** Lift the pen at random points around the outline. */
   addBreaks?: boolean | number | BreakOptions;
+  /**
+   * Font stack for handwritten notes. Point this at your own family — a
+   * `next/font` CSS variable, for instance — to take over from the built-in one.
+   */
+  fontFamily?: string | null;
+  /**
+   * Fetch the Caveat webfont when the page has not already provided it.
+   * Default `true`. Set `false` if a strict CSP blocks Google Fonts, or if you
+   * self-host the family; the notes then use `fontFamily` or the system
+   * handwriting fallbacks.
+   */
+  autoLoadFont?: boolean;
 }
 
 export interface DoodleInstance {

package/dist/react.cjs

@@ -34,14 +34,19 @@ var DEFAULT_OPTIONS = {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 8,
+  // The frame traces the element's own edge. Raise this to stand it off.
+  padding: 0,
   radius: null,
   opacity: 0.9,
   children: null,
   note: null,
   arrow: false,
   decorations: false,
-  addBreaks: false
+  addBreaks: false,
+  /** Override the handwriting stack, e.g. a next/font CSS variable. */
+  fontFamily: null,
+  /** Fetch Caveat when the page has not provided it. */
+  autoLoadFont: true
 };
 function resolveElement(target) {
   if (!target) return null;
@@ -267,7 +272,7 @@ function annotationAnchor(position, rect, offset = 12) {
 
 // src/renderer.js
 var SVG_NS = "http://www.w3.org/2000/svg";
-var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", cursive';
+var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
 function clearSvg(svg) {
   while (svg.firstChild) {
@@ -746,7 +751,7 @@ function createNoteText(svg, text, style) {
   textEl.setAttribute("fill", style.color);
   textEl.setAttribute("opacity", String(style.opacity));
   textEl.setAttribute("font-size", String(fontSize));
-  textEl.setAttribute("font-family", HANDWRITTEN_FONT);
+  textEl.setAttribute("font-family", style.fontFamily || HANDWRITTEN_FONT);
   textEl.setAttribute("font-weight", "600");
   textEl.setAttribute("letter-spacing", "0.4");
   textEl.setAttribute("text-anchor", "start");
@@ -1319,6 +1324,27 @@ function renderDecorations(svg, rect, decorationOptions, style, seed, context =
   }
 }
 
+// src/fonts.js
+var FONT_NAME = "Caveat";
+var FONT_HREF = "https://fonts.googleapis.com/css2?family=Caveat:wght@400;600&display=swap";
+var MARKER = "data-freehand-font";
+var requested = false;
+function ensureHandwrittenFont() {
+  if (requested) return;
+  if (typeof document === "undefined" || !document.head) return;
+  requested = true;
+  try {
+    if (document.fonts?.check?.(`600 19px "${FONT_NAME}"`)) return;
+  } catch {
+  }
+  if (document.querySelector(`link[${MARKER}]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = FONT_HREF;
+  link.setAttribute(MARKER, "");
+  document.head.appendChild(link);
+}
+
 // src/doodle.js
 var instances = /* @__PURE__ */ new WeakMap();
 function localViewport(overlayRect, inset = 8) {
@@ -1370,7 +1396,12 @@ var DoodleOverlay = class {
     }
     window.addEventListener("resize", this.onResize, { passive: true });
     this.scrollTargets.push({ target: window, type: "resize" });
-    document.fonts?.ready?.then(() => this.scheduleUpdate()).catch(() => {
+    if (this.options.note && this.options.autoLoadFont && !this.options.fontFamily) {
+      ensureHandwrittenFont();
+    }
+    this.onFontsLoaded = () => this.scheduleUpdate();
+    document.fonts?.addEventListener?.("loadingdone", this.onFontsLoaded);
+    document.fonts?.ready?.then(this.onFontsLoaded).catch(() => {
     });
     this.update();
   }
@@ -1413,7 +1444,13 @@ var DoodleOverlay = class {
     this.svg.style.width = `${overlayRect.width}px`;
     this.svg.style.height = `${overlayRect.height}px`;
     const strokeStyle = { color, strokeWidth, roughness, opacity };
-    const noteStyle = { color, opacity, strokeWidth, roughness };
+    const noteStyle = {
+      color,
+      opacity,
+      strokeWidth,
+      roughness,
+      fontFamily: this.options.fontFamily
+    };
     const noteGroups = [];
     const noteLayout = {
       viewport: localViewport(overlayRect),
@@ -1488,6 +1525,10 @@ var DoodleOverlay = class {
       this.mutationObserver.disconnect();
       this.mutationObserver = null;
     }
+    if (this.onFontsLoaded) {
+      document.fonts?.removeEventListener?.("loadingdone", this.onFontsLoaded);
+      this.onFontsLoaded = null;
+    }
     for (const { target, type } of this.scrollTargets) {
       target.removeEventListener(type, type === "scroll" ? this.onScroll : this.onResize);
     }
@@ -1530,7 +1571,9 @@ var OPTION_KEYS = [
   "note",
   "arrow",
   "decorations",
-  "addBreaks"
+  "addBreaks",
+  "fontFamily",
+  "autoLoadFont"
 ];
 function collectOptions(props) {
   const options = {};
@@ -1580,6 +1623,8 @@ var Doodle = (0, import_react.forwardRef)(function Doodle2(props, forwardedRef)
     arrow,
     decorations,
     addBreaks,
+    fontFamily,
+    autoLoadFont,
     childSelector,
     ...rest
   } = props;
@@ -1597,6 +1642,8 @@ var Doodle = (0, import_react.forwardRef)(function Doodle2(props, forwardedRef)
       arrow,
       decorations,
       addBreaks,
+      fontFamily,
+      autoLoadFont,
       childSelector
     }),
     [
@@ -1612,6 +1659,8 @@ var Doodle = (0, import_react.forwardRef)(function Doodle2(props, forwardedRef)
       JSON.stringify(arrow ?? null),
       JSON.stringify(decorations ?? null),
       JSON.stringify(addBreaks ?? null),
+      fontFamily,
+      autoLoadFont,
       childSelector
     ]
   );

package/dist/react.js

@@ -17,14 +17,19 @@ var DEFAULT_OPTIONS = {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 8,
+  // The frame traces the element's own edge. Raise this to stand it off.
+  padding: 0,
   radius: null,
   opacity: 0.9,
   children: null,
   note: null,
   arrow: false,
   decorations: false,
-  addBreaks: false
+  addBreaks: false,
+  /** Override the handwriting stack, e.g. a next/font CSS variable. */
+  fontFamily: null,
+  /** Fetch Caveat when the page has not provided it. */
+  autoLoadFont: true
 };
 function resolveElement(target) {
   if (!target) return null;
@@ -250,7 +255,7 @@ function annotationAnchor(position, rect, offset = 12) {
 
 // src/renderer.js
 var SVG_NS = "http://www.w3.org/2000/svg";
-var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", cursive';
+var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
 function clearSvg(svg) {
   while (svg.firstChild) {
@@ -729,7 +734,7 @@ function createNoteText(svg, text, style) {
   textEl.setAttribute("fill", style.color);
   textEl.setAttribute("opacity", String(style.opacity));
   textEl.setAttribute("font-size", String(fontSize));
-  textEl.setAttribute("font-family", HANDWRITTEN_FONT);
+  textEl.setAttribute("font-family", style.fontFamily || HANDWRITTEN_FONT);
   textEl.setAttribute("font-weight", "600");
   textEl.setAttribute("letter-spacing", "0.4");
   textEl.setAttribute("text-anchor", "start");
@@ -1302,6 +1307,27 @@ function renderDecorations(svg, rect, decorationOptions, style, seed, context =
   }
 }
 
+// src/fonts.js
+var FONT_NAME = "Caveat";
+var FONT_HREF = "https://fonts.googleapis.com/css2?family=Caveat:wght@400;600&display=swap";
+var MARKER = "data-freehand-font";
+var requested = false;
+function ensureHandwrittenFont() {
+  if (requested) return;
+  if (typeof document === "undefined" || !document.head) return;
+  requested = true;
+  try {
+    if (document.fonts?.check?.(`600 19px "${FONT_NAME}"`)) return;
+  } catch {
+  }
+  if (document.querySelector(`link[${MARKER}]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = FONT_HREF;
+  link.setAttribute(MARKER, "");
+  document.head.appendChild(link);
+}
+
 // src/doodle.js
 var instances = /* @__PURE__ */ new WeakMap();
 function localViewport(overlayRect, inset = 8) {
@@ -1353,7 +1379,12 @@ var DoodleOverlay = class {
     }
     window.addEventListener("resize", this.onResize, { passive: true });
     this.scrollTargets.push({ target: window, type: "resize" });
-    document.fonts?.ready?.then(() => this.scheduleUpdate()).catch(() => {
+    if (this.options.note && this.options.autoLoadFont && !this.options.fontFamily) {
+      ensureHandwrittenFont();
+    }
+    this.onFontsLoaded = () => this.scheduleUpdate();
+    document.fonts?.addEventListener?.("loadingdone", this.onFontsLoaded);
+    document.fonts?.ready?.then(this.onFontsLoaded).catch(() => {
     });
     this.update();
   }
@@ -1396,7 +1427,13 @@ var DoodleOverlay = class {
     this.svg.style.width = `${overlayRect.width}px`;
     this.svg.style.height = `${overlayRect.height}px`;
     const strokeStyle = { color, strokeWidth, roughness, opacity };
-    const noteStyle = { color, opacity, strokeWidth, roughness };
+    const noteStyle = {
+      color,
+      opacity,
+      strokeWidth,
+      roughness,
+      fontFamily: this.options.fontFamily
+    };
     const noteGroups = [];
     const noteLayout = {
       viewport: localViewport(overlayRect),
@@ -1471,6 +1508,10 @@ var DoodleOverlay = class {
       this.mutationObserver.disconnect();
       this.mutationObserver = null;
     }
+    if (this.onFontsLoaded) {
+      document.fonts?.removeEventListener?.("loadingdone", this.onFontsLoaded);
+      this.onFontsLoaded = null;
+    }
     for (const { target, type } of this.scrollTargets) {
       target.removeEventListener(type, type === "scroll" ? this.onScroll : this.onResize);
     }
@@ -1513,7 +1554,9 @@ var OPTION_KEYS = [
   "note",
   "arrow",
   "decorations",
-  "addBreaks"
+  "addBreaks",
+  "fontFamily",
+  "autoLoadFont"
 ];
 function collectOptions(props) {
   const options = {};
@@ -1563,6 +1606,8 @@ var Doodle = forwardRef(function Doodle2(props, forwardedRef) {
     arrow,
     decorations,
     addBreaks,
+    fontFamily,
+    autoLoadFont,
     childSelector,
     ...rest
   } = props;
@@ -1580,6 +1625,8 @@ var Doodle = forwardRef(function Doodle2(props, forwardedRef) {
       arrow,
       decorations,
       addBreaks,
+      fontFamily,
+      autoLoadFont,
       childSelector
     }),
     [
@@ -1595,6 +1642,8 @@ var Doodle = forwardRef(function Doodle2(props, forwardedRef) {
       JSON.stringify(arrow ?? null),
       JSON.stringify(decorations ?? null),
       JSON.stringify(addBreaks ?? null),
+      fontFamily,
+      autoLoadFont,
       childSelector
     ]
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aznabee/freehand-ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer",
   "type": "module",
   "main": "./dist/freehand-ui.cjs",