@pothooks/react 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pothooks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @pothooks/react
+
+React component for replaying handwriting recorded by
+[Pothooks](https://pothooks.com). Wraps
+[`@pothooks/core`](https://github.com/danbillson/pothooks/tree/main/packages/core).
+
+```bash
+npm install @pothooks/react
+```
+
+```tsx
+import { Handwriting } from '@pothooks/react';
+
+<Handwriting payload={payload} trigger="visible" speed={1} loop color="#111" />
+```
+
+Renders the finished SVG on the server, then animates after hydration — never a
+blank first paint, and never a blank box under `prefers-reduced-motion`.
+
+## Props
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `payload` | — | The exported Pothooks payload. |
+| `trigger` | `"visible"` | `"mount"`, `"visible"`, `"hover"` or `"manual"`. |
+| `speed` | `1` | `1` is the recorded cadence. |
+| `loop` | `false` | `true`, or ms to pause between loops. |
+| `startDelay` | `0` | Ms before the first stroke. |
+| `color` | inherits | Ink colour. The ink is `currentColor`, so this just sets `color`. |
+| `title` | `payload.meta.text` | Accessible name. Without either, the SVG is decorative. |
+| `reducedMotion` | `"respect"` | `"ignore"` only if the motion *is* the content. |
+| `onDone` | — | Fires each time the piece finishes, including on every loop. |
+
+Any other SVG prop (`className`, `style`, `width`, …) passes through to the
+root `<svg>`.
+
+`trigger="visible"` uses an `IntersectionObserver`; it starts playback the first
+time the piece is on screen and then keeps feeding the pause gate, so scrolling
+away stops the loop rather than leaving it burning frames.
+
+## Manual control
+
+```tsx
+const playback = useRef<Playback>(null);
+
+<Handwriting ref={playback} payload={payload} trigger="manual" />
+<button onClick={() => playback.current?.restart()}>Replay</button>
+```
+
+The ref is a stable [`Playback`][playback] facade — it keeps working when a
+prop change rebuilds the underlying loop.
+
+[playback]: https://github.com/danbillson/pothooks/tree/main/packages/core#playsvg-opts-playback
+
+`react` is a peer dependency (>=18).

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { CSSProperties, SVGProps } from "react";
+import { Payload, Payload as Payload$1, Playback, Playback as Playback$1, Stroke } from "@pothooks/core";
+//#region src/Handwriting.d.ts
+/** How playback starts. `"manual"` waits for a call on the forwarded ref. */
+type Trigger = 'mount' | 'visible' | 'hover' | 'manual';
+interface HandwritingProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'children' | 'color' | 'dangerouslySetInnerHTML'> {
+  payload: Payload$1;
+  /** 1 = the recorded cadence. */
+  speed?: number;
+  /** `true` loops immediately; a number loops after that many ms. */
+  loop?: boolean | number;
+  startDelay?: number;
+  trigger?: Trigger;
+  /** CSS colour for the ink. Defaults to inheriting `currentColor`. */
+  color?: string;
+  /** Accessible name. Defaults to `payload.meta.text`. */
+  title?: string;
+  reducedMotion?: 'respect' | 'ignore';
+  /** Fires each time the piece finishes drawing, including on every loop. */
+  onDone?: () => void;
+  style?: CSSProperties;
+}
+/**
+ * Renders the finished SVG — on the server too — then animates after
+ * hydration. There is never a blank first paint.
+ */
+export declare const Handwriting: import("react").ForwardRefExoticComponent<HandwritingProps & import("react").RefAttributes<Playback$1 | null>>;
+//#endregion
+export type { HandwritingProps, Payload, Playback, Stroke, Trigger };

package/dist/index.js

@@ -0,0 +1,100 @@
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef } from "react";
+import { play, renderMarkup } from "@pothooks/core";
+import { jsx } from "react/jsx-runtime";
+//#region src/Handwriting.tsx
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/**
+* Renders the finished SVG — on the server too — then animates after
+* hydration. There is never a blank first paint.
+*/
+const Handwriting = forwardRef(function Handwriting({ payload, speed = 1, loop = false, startDelay, trigger = "visible", color, title, reducedMotion, onDone, style, onMouseEnter, onFocus, ...rest }, ref) {
+	const svgRef = useRef(null);
+	const playbackRef = useRef(null);
+	const idPrefix = useId();
+	const { attrs, inner } = useMemo(() => renderMarkup(payload, {
+		idPrefix,
+		title
+	}), [
+		payload,
+		idPrefix,
+		title
+	]);
+	const onDoneRef = useRef(onDone);
+	onDoneRef.current = onDone;
+	useIsomorphicLayoutEffect(() => {
+		const svg = svgRef.current;
+		if (!svg) return;
+		const playback = play(svg, {
+			speed,
+			loop,
+			startDelay,
+			reducedMotion,
+			autoplay: trigger === "mount",
+			onDone: () => onDoneRef.current?.()
+		});
+		playbackRef.current = playback;
+		let started = trigger !== "visible";
+		let observer;
+		if (typeof IntersectionObserver !== "undefined") {
+			observer = new IntersectionObserver((entries) => {
+				const visible = entries.some((entry) => entry.isIntersecting);
+				if (visible && !started) {
+					started = true;
+					playback.play();
+				}
+				playback.setInView(visible);
+			}, { threshold: .01 });
+			observer.observe(svg);
+		} else if (trigger === "visible") playback.play();
+		return () => {
+			observer?.disconnect();
+			playback.destroy();
+			playbackRef.current = null;
+		};
+	}, [
+		speed,
+		loop,
+		startDelay,
+		trigger,
+		reducedMotion,
+		inner
+	]);
+	const facade = useMemo(() => ({
+		play: () => playbackRef.current?.play(),
+		pause: () => playbackRef.current?.pause(),
+		restart: () => playbackRef.current?.restart(),
+		seek: (t) => playbackRef.current?.seek(t),
+		setInView: (v) => playbackRef.current?.setInView(v),
+		destroy: () => playbackRef.current?.destroy(),
+		get duration() {
+			return playbackRef.current?.duration ?? 0;
+		},
+		get playing() {
+			return playbackRef.current?.playing ?? false;
+		}
+	}), []);
+	useImperativeHandle(ref, () => facade, [facade]);
+	const startOnHover = useCallback(() => {
+		if (trigger === "hover") playbackRef.current?.restart();
+	}, [trigger]);
+	return /* @__PURE__ */ jsx("svg", {
+		...attrs,
+		...rest,
+		ref: svgRef,
+		style: color ? {
+			...style,
+			color
+		} : style,
+		onMouseEnter: (event) => {
+			startOnHover();
+			onMouseEnter?.(event);
+		},
+		onFocus: (event) => {
+			startOnHover();
+			onFocus?.(event);
+		},
+		dangerouslySetInnerHTML: { __html: inner }
+	});
+});
+//#endregion
+export { Handwriting };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pothooks/react",
+  "version": "0.0.0",
+  "description": "Animate handwriting on the web — React component",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danbillson/pothooks.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/danbillson/pothooks/issues"
+  },
+  "homepage": "https://pothooks.com",
+  "keywords": [
+    "handwriting",
+    "signature",
+    "animation",
+    "svg",
+    "react",
+    "pothooks"
+  ],
+  "dependencies": {
+    "@pothooks/core": "^0.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "happy-dom": "^20.14.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint src test"
+  }
+}