@aznabee/freehand-ui 0.1.2 → 0.1.4

package/README.md

@@ -1,96 +1,54 @@
-# freehand-ui
+![freehand-ui - make your UI delightfully human](docs/images/hero.png)
 
-Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer.
-
-`freehand-ui` adds a subtle SVG overlay — thin white pen strokes, handwritten notes, arrows, and sparse decorations — without changing your HTML layout or intercepting pointer events.
-
-## Install
-
-```bash
-npm install @aznabee/freehand-ui
-```
+# Freehand-ui
 
-## Basic usage
-
-```javascript
-import { doodle } from "@aznabee/freehand-ui";
+Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer.
 
-doodle(document.querySelector(".card"));
-// or
-doodle(".card");
-```
+## What it does
 
-This immediately draws a hand-drawn border around the element and keeps it aligned as the page resizes, scrolls, or reflows.
+`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`).
 
-## React / Next.js
+**Good for:** call-to-action buttons, feature cards, onboarding hints, playful marketing UI.
 
-```jsx
-import Doodle from "@aznabee/freehand-ui/react";
+| Feature         | One-liner                                                           |
+| --------------- | ------------------------------------------------------------------- |
+| **Border**      | Hand-drawn frame that follows the element's shape and border-radius |
+| **Notes**       | Caveat handwriting beside the element                               |
+| **Arrows**      | Curved, straight, dotted, or looped pointers into the element       |
+| **Decorations** | Corner accents, stars, hearts, and more                             |
+| **Responsive**  | Stays aligned on resize, scroll, and reflow                         |
 
-<Doodle note="start chat" strokeWidth={2}>
-  <Button />
-</Doodle>;
-```
+**Live on [Aznabee.com](https://aznabee.com)** - see it in production on the real product.
 
-Every option below works as a prop. The component ships `"use client"`, so it
-drops straight into the Next.js App Router without a wrapper of your own, and
-it renders on the server without warnings.
+## ![Basic hand-drawn border around a card](docs/images/basic.png)
 
-The doodle is drawn around **the wrapped component as a whole** — children are
-never decorated individually. To decorate descendants instead, opt in with
-`childSelector`:
+## Install
 
-```jsx
-<Doodle childSelector=".card">
-  {items.map((item) => <Card key={item.id} className="card" {...item} />)}
-</Doodle>
+```bash
+npm install @aznabee/freehand-ui
 ```
 
-### Wrapper element
+---
 
-`<Doodle>` renders a `<span style="display:inline-flex">` that shrink-wraps its
-child, so the frame hugs your component instead of stretching to the full width
-of its container. `inline-flex` specifically: an `inline-block` wrapper adds
-baseline leading beneath an inline-level child like a `<button>`, which would
-leave the frame visibly taller than the button.
+## Vanilla JavaScript
 
-Override it when you need different layout — any extra props go to the DOM node:
+Import from the main entry point and call `doodle()` on any element or CSS selector.
 
-```jsx
-<Doodle as="div" style={{ display: "block" }} className="w-full" note="hi">
-  <Card />
-</Doodle>
-```
-
-Border radius is picked up automatically: if the wrapper has none of its own,
-it inherits the radius of the child it hugs, so a wrapped pill button is still
-drawn as a pill.
-
-### Hook
+### Quick start
 
-For an element you already hold a ref to, skip the wrapper:
-
-```jsx
-import { useDoodle } from "@aznabee/freehand-ui/react";
+```javascript
+import { doodle } from "@aznabee/freehand-ui";
 
-function Card() {
-  const ref = useRef(null);
-  useDoodle(ref, { note: "new", decorations: true });
-  return <div ref={ref}>…</div>;
-}
+doodle(document.querySelector(".card"));
+// or
+doodle(".card");
 ```
 
-### Notes
+This draws a hand-drawn border around the element and keeps it aligned as the page resizes, scrolls, or reflows.
 
-- 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.
+### Configuration
 
-## Configuration
+Pass a second argument to `doodle()`:
 
 ```javascript
 doodle(".card", {
@@ -98,75 +56,54 @@ doodle(".card", {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 0,        // gap between the element's edge and the frame
-  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
-  fontFamily: null,  // override the handwriting stack
+  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.
+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
+### 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.
+Notes are set in [Caveat](https://fonts.google.com/specimen/Caveat). The library loads it the first time a note is drawn, so handwriting looks right in a plain app with no font setup. Without it, text falls back to the generic `cursive` family (on macOS that's a calligraphic serif, not handwriting).
 
-It skips the request when the page already provides the family, and only ever
-requests it once. To take over:
+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
+// your own family
 doodle(".card", { note: "hi", fontFamily: "var(--font-caveat)" });
 ```
 
-```jsx
-import { Caveat } from "next/font/google";
-const caveat = Caveat({ subsets: ["latin"], variable: "--font-caveat" });
+Setting `autoLoadFont: false` without a `fontFamily` falls back to system handwriting faces (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.
 
-<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
+### Broken outlines
 
-`addBreaks` cuts randomly sized gaps into the border, so it reads as a few
-confident dashes rather than one closed loop:
+`addBreaks` cuts randomly sized gaps into the border so it reads as a few confident dashes rather than one closed loop:
 
 ```javascript
 doodle(".cta", { addBreaks: true });
 
-doodle(".cta", { addBreaks: 5 });          // five gaps
+doodle(".cta", { addBreaks: 5 }); // five gaps
 
 doodle(".cta", {
   addBreaks: {
-    count: 4,   // omit for 2–5 gaps
-    min: 6,     // shortest gap, px
-    max: 30,    // longest gap, px
+    count: 4, // omit for 2–5 gaps
+    min: 6, // shortest gap, px
+    max: 30, // longest gap, px
   },
 });
 ```
 
-Gaps are spread one per section of the perimeter so they never clump, and their
-total is capped at a third of the outline so the frame still reads as a frame.
-On small elements the gaps shrink to fit.
+Gaps are spread one per section of the perimeter so they never clump, and their total is capped at a third of the outline so the frame still reads as a frame. On small elements the gaps shrink to fit.
 
-## Handwritten annotations
+### Handwritten annotations
 
 ```javascript
 doodle(".cta", {
@@ -178,79 +115,94 @@ doodle(".cta", {
 });
 ```
 
-Positions: `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`, `top-left`. Same names apply to `arrow.from`/`arrow.to`.
+**Positions:** `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`, `top-left`. Same names apply to `arrow.from` / `arrow.to`.
+
+Notes are measured from real glyph metrics and laid out so they never sit on top of the element. The underline is drawn to the measured text width; set `underline: false` for plain handwriting.
+
+### Placement behavior
+
+- **The side you ask for is the side you get.** When a note runs past the viewport edge it slides horizontally by exactly the amount it overhangs, so a narrowing viewport walks it gradually inward instead of snapping to the opposite side.
+- **Vertical placement is fixed** relative to the element and does not react to scrolling - a note stays pinned to what it annotates.
+- If an element is jammed against the viewport edge, a note may sit partly off screen - use a different `position` or an `offset` there.
+
+Nudge a note with `offset`:
 
-The position is a preference, not a command. Notes are measured from their real
-glyph metrics and laid out so they never sit on top of the element — if the
-preferred side would run off screen, the note flips to a side that fits. The
-underline is drawn to the measured text width; set `underline: false` for plain
-handwriting.
+```javascript
+doodle(".cta", {
+  note: { text: "start chat", position: "top", offset: { x: 40, y: -12 } },
+});
+```
+
+The offset moves the note from the spot `position` chose. A large horizontal offset slides back into the viewport rather than carrying the note off screen.
 
-## Arrows
+### Arrows
 
 ```javascript
 doodle(".cta", { arrow: true });
 
 doodle(".cta", {
   arrow: {
-    from: "top-right",
+    from: "top-right", // note | any position name
     to: "center",
-    style: "curved", // curved | straight | dotted
+    style: "curved", // curved | straight | dotted | looped
   },
 });
 ```
 
-When the element also has a `note`, the arrow ignores `from` and launches from
-the note itself. `to: "edge"` (the default) lands the tip just *outside* the
-frame; `to: "center"` is the one setting that deliberately points into the
-element.
+![Arrow styles - curved, straight, dotted, and looped](docs/images/arrows.png)
+
+**Styles:** `curved` (default), `straight`, `dotted`, `looped` - `looped` adds a flourish that doubles back before reaching the tip.
+
+**`from`** decides where the arrow leaves:
+
+- **With a note** - names a side of the note (where the pen lifts off the handwriting), then travels to the element.
+- **`"note"`** (default) - picks the side of the note facing the element.
+- **Without a note** - `from` names a side of the element itself.
+
+```javascript
+doodle(".cta", {
+  note: { text: "start chat", position: "top-right" },
+  arrow: { from: "bottom-left" }, // leaves the note's bottom-left corner
+});
+```
+
+**`to`:** `"edge"` (default) lands the tip just outside the frame; `"center"` points into the element.
 
-## Decorations
+### Decorations
 
 ```javascript
 doodle(".card", { decorations: true });
 
 doodle(".card", {
   decorations: {
-    count: 2,             // border marks, hard-capped at 2
-    style: "corners",     // corners | sides — omit to pick automatically
+    count: 2, // border marks, hard-capped at 2
+    style: "corners", // corners | sides - omit to pick automatically
     types: ["arcs", "twinkle", "heart"],
   },
 });
 ```
 
-A frame stays readable with **at most two marks around it**, so `count` is
-capped at 2 and the default composition is deliberately fixed:
+![Decoration types - corner accents, stars, handwriting marks, and more](docs/images/decorations.png)
 
-- **one corner accent** — `arcs` or `emphasis` — hugging a corner, aimed outward
-- **one corner star** — `twinkle` or `star` — on the corner farthest from it,
-  and sitting noticeably further off the border than the accent
-- **one handwriting accent** — `heart` or `sparkle` — beside the note, not the
-  component
+A frame stays readable with **at most two marks around it**. Default composition:
 
-Corner marks follow the *rounded* corner rather than the bounding box, so they
-hug a pill's cap as closely as a card's corner, and any mark too large for the
-gap it landed in is pushed further out. Everything keeps off the element, off
-the note, and off the arrow's sweep.
+- **one corner accent** - `arcs` or `emphasis` - hugging a corner, aimed outward
+- **one corner star** - `twinkle` or `star` - on the corner farthest from it
+- **one handwriting accent** - `heart` or `sparkle` - beside the note, not the component
+
+Corner marks follow the _rounded_ corner rather than the bounding box. Marks too large for their gap are pushed further out.
 
 ### Handwriting accents
 
-`heart` and `sparkle` belong to text: they are drawn at the far end of the
-note, on the side away from the element. With no `note` on the element they are
-skipped rather than moved to the border.
+`heart` and `sparkle` are drawn at the far end of the note, on the side away from the element. With no `note` they are skipped rather than moved to the border.
 
 ### Small components
 
-Chips and icon buttons have no corner worth pointing at, so they get a mirrored
-pair of two-stroke `emphasis` marks — one either side — instead of corner
-marks. This is chosen automatically when the element is under 48px on its short
-side or under 130px wide; `style: "sides"` forces it at any size and
-`style: "corners"` opts out.
+Chips and icon buttons get a mirrored pair of two-stroke `emphasis` marks - one either side - instead of corner marks. This is automatic when the element is under 48px on its short side or under 130px wide. `style: "sides"` forces it at any size; `style: "corners"` opts out.
 
-The remaining types — `star`, `smiley`, `dots`, `stroke`, `steam` — are still
-available and fill a corner slot when no accent or star was requested.
+Other types - `star`, `smiley`, `dots`, `stroke`, `steam` - fill a corner slot when no accent or star was requested.
 
-## Child selector mode
+### Child selector mode
 
 Decorate multiple children from a single parent overlay:
 
@@ -260,16 +212,113 @@ doodle("#hero", {
 });
 ```
 
-## Lifecycle
+### Lifecycle
 
 ```javascript
 const instance = doodle(".card");
 
-instance.update();  // recalculate geometry and redraw
+instance.update(); // recalculate geometry and redraw
 instance.destroy(); // remove overlay and disconnect observers
 ```
 
-Calling `doodle()` twice on the same element replaces the previous overlay — no duplicates.
+Calling `doodle()` twice on the same element replaces the previous overlay - no duplicates.
+
+---
+
+## React / Next.js
+
+Import from `@aznabee/freehand-ui/react`. Every option in the [Vanilla JavaScript](#vanilla-javascript) section works as a prop.
+
+### Component
+
+```jsx
+import Doodle from "@aznabee/freehand-ui/react";
+
+<Doodle note="start chat" strokeWidth={2}>
+  <Button />
+</Doodle>;
+```
+
+Ships `"use client"` - drops into the Next.js App Router without a wrapper, and renders on the server without warnings.
+
+The doodle is drawn around **the wrapped component as a whole** - children are never decorated individually. To decorate descendants instead, opt in with `childSelector`:
+
+```jsx
+<Doodle childSelector=".card">
+  {items.map((item) => (
+    <Card key={item.id} className="card" {...item} />
+  ))}
+</Doodle>
+```
+
+### Configuration
+
+Same options as `doodle()`, passed as props:
+
+```jsx
+<Doodle
+  border
+  color="#ffffff"
+  strokeWidth={1.5}
+  roughness={1.5}
+  padding={0}
+  radius={20}
+  opacity={0.9}
+  addBreaks={false}
+  autoLoadFont
+>
+  <Card />
+</Doodle>
+```
+
+### Wrapper element
+
+`<Doodle>` renders a `<span style="display:inline-flex">` that shrink-wraps its child, so the frame hugs your component instead of stretching to the full width of its container. `inline-flex` specifically: an `inline-block` wrapper adds baseline leading beneath an inline-level child like a `<button>`, which would leave the frame visibly taller than the button.
+
+Override when you need different layout - extra props go to the DOM node:
+
+```jsx
+<Doodle as="div" style={{ display: "block" }} className="w-full" note="hi">
+  <Card />
+</Doodle>
+```
+
+Border radius is picked up automatically: if the wrapper has none of its own, it inherits the radius of the child it hugs, so a wrapped pill button is still drawn as a pill.
+
+### Hook
+
+For an element you already hold a ref to, skip the wrapper:
+
+```jsx
+import { useDoodle } from "@aznabee/freehand-ui/react";
+
+function Card() {
+  const ref = useRef(null);
+  useDoodle(ref, { note: "new", decorations: true });
+  return <div ref={ref}>…</div>;
+}
+```
+
+### Handwriting font
+
+With `next/font`:
+
+```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>;
+```
+
+### React notes
+
+- 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.
+
+---
 
 ## Examples
 
@@ -285,16 +334,22 @@ Then open:
 
 - http://localhost:5173/examples/basic/
 - http://localhost:5173/examples/annotations/
+- http://localhost:5173/examples/arrows/
 - http://localhost:5173/examples/children/
 - http://localhost:5173/examples/decorations/
+- http://localhost:5173/examples/react/
+
+---
 
 ## Design principles
 
-- **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** — `ResizeObserver`, scroll listeners, and `requestAnimationFrame`
-- **Lightweight** — zero runtime dependencies
+- **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** - `ResizeObserver`, scroll listeners, and `requestAnimationFrame`
+- **Lightweight** - zero runtime dependencies
+
+---
 
 ## License