phase 0.0.12 → 0.1.0

package/README.md

@@ -176,7 +176,7 @@ The main primitive. Composes a ticker, visibility observer, and reduced-motion l
 import { createLoop } from 'phase';
 
 const loop = createLoop({
-  element: el,
+  target: el,
   onTick: (frame) => {
     // frame.time    — browser rAF timestamp
     // frame.delta   — ms since last tick (clamped to 40ms)
@@ -229,7 +229,7 @@ Controls the loop's response when quality degrades. Same three-value pattern as
 
 ```ts
 createLoop({
-  element: el,
+  target: el,
   onTick: draw,
   degraded: 'throttle', // default
   degradedFps: 20, // only accepted when degraded is 'throttle'
@@ -240,7 +240,7 @@ createLoop({
 
 | Option          | Type                                | Default      | Description                               |
 | --------------- | ----------------------------------- | ------------ | ----------------------------------------- |
-| `element`       | `Element`                           | required     | Element to observe for visibility         |
+| `target`        | `Element`                           | required     | Element to observe for visibility         |
 | `onTick`        | `(frame: FrameState) => void`       | required     | Called each frame while running           |
 | `fps`           | `number`                            | —            | Cap frames per second                     |
 | `reducedMotion` | `'pause' \| 'complete' \| 'ignore'` | `'pause'`    | Behavior when user prefers reduced motion |
@@ -283,7 +283,7 @@ Answers one question: is this element visible right now? Combines `document.visi
 import { createSight } from 'phase';
 
 const sight = createSight({
-  element: el,
+  target: el,
   onPhaseChange: (phase, reason) => {
     // phase:  'visible' | 'hidden' | 'unknown'
     // reason: 'initial' | 'viewport' | 'document' | 'bfcache' | 'all-hidden'
@@ -303,7 +303,7 @@ Use `createLifecycle` when you own your render loop (a three.js/WebGL renderer,
 import { createLifecycle } from 'phase';
 
 const lifecycle = createLifecycle({
-  element: canvas,
+  target: canvas,
   onPhaseChange: (phase, reason) => {
     // phase:  'idle' | 'active' | 'paused' | 'stopped'
     // reason: 'started' | 'resumed' | 'sight' | 'reduced-motion' | 'manual' | 'disposed' | 'initial'
@@ -343,7 +343,7 @@ Reports what fraction of an element is currently visible in the viewport (0–1)
 import { createScrollProgress } from 'phase';
 
 const progress = createScrollProgress({
-  element: el,
+  target: el,
   onProgress: (ratio) => {
     el.style.opacity = String(ratio);
   },
@@ -361,7 +361,7 @@ The `steps` option controls threshold granularity. Default `20` generates 21 eve
 
 | Option       | Type                          | Default  | Description                        |
 | ------------ | ----------------------------- | -------- | ---------------------------------- |
-| `element`    | `Element`                     | required | Element to observe                 |
+| `target`     | `Element`                     | required | Element to observe                 |
 | `onProgress` | `(ratio: number) => void`     | required | Called at each threshold crossing  |
 | `steps`      | `number`                      | `20`     | Number of evenly-spaced thresholds |
 | `root`       | `Element \| Document \| null` | —        | IO root element                    |
@@ -377,7 +377,7 @@ Tracks a scroll container's offset and progress. Reads `scrollLeft`/`scrollTop`
 import { createScroll } from 'phase';
 
 const scroll = createScroll({
-  element: viewport,
+  target: viewport,
   onScroll: (s) => {
     // thumb CSS needs `transform-origin: left` so scaleX anchors to the track start
     thumb.style.transform = `translateX(${s.progressX * (1 - s.visibleX) * 100}%) scaleX(${s.visibleX})`;
@@ -401,7 +401,7 @@ scroll.stop();
 
 | Option                | Type                           | Default   | Description                                        |
 | --------------------- | ------------------------------ | --------- | -------------------------------------------------- |
-| `element`             | `Element`                      | required  | Scroll container to track                          |
+| `target`              | `Element`                      | required  | Scroll container to track                          |
 | `onScroll`            | `(state: ScrollState) => void` | required  | Called once per rAF frame with position + progress |
 | `onPhaseChange`       | `(phase, reason) => void`      | —         | Called on phase transitions                        |
 | `visibility`          | `'pause' \| 'ignore'`          | `'pause'` | Pause tracking when off-screen, or ignore          |
@@ -481,7 +481,7 @@ Reports whether the browser is rendering an element or skipping it under `conten
 import { createRenderState } from 'phase';
 
 const renderState = createRenderState({
-  element: el,
+  target: el,
   onPhaseChange: (phase) => {
     if (phase === 'skipped') clock.pause();
     else clock.resume();
@@ -518,7 +518,7 @@ A lifecycle-aware `MutationObserver`: records are coalesced into one callback pe
 import { createMutation } from 'phase';
 
 const mutation = createMutation({
-  element: list,
+  target: list,
   mutation: { childList: true },
   onMutations: (records) => syncItems(records),
 });
@@ -536,7 +536,7 @@ Tracks pointer position relative to an element, batching high-frequency events i
 import { createPointer } from 'phase';
 
 const pointer = createPointer({
-  element: surface,
+  target: surface,
   onPointer: (state) => {
     cursor.style.transform = `translate(${state.x}px, ${state.y}px)`;
   },
@@ -741,12 +741,12 @@ Animates a number from A to B over a duration. Calls `setState` per frame (appro
 ```tsx
 import { useTween } from 'phase/react';
 
-const opacity = useTween({ target: isVisible ? 1 : 0, duration: 300 });
+const opacity = useTween({ to: isVisible ? 1 : 0, duration: 300 });
 ```
 
 Use `useTween` for single values where the render is cheap (counters, progress bars, opacity). Use `useLoop` when animating many elements or doing canvas work, since per-frame `setState` doesn't scale.
 
-Reduced motion default: `'complete'` (jumps to target instantly). The value still reaches its destination; it skips the animation.
+Reduced motion default: `'complete'` (jumps to the destination instantly). The value still reaches its destination; it skips the animation.
 
 ### usePresence
 
@@ -1209,13 +1209,13 @@ Every error includes a machine-readable `code` and an actionable message.
 import { PhaseError, isPhaseError } from 'phase';
 ```
 
-| Code               | Trigger                                              |
-| ------------------ | ---------------------------------------------------- |
-| `server_context`   | Calling a browser-only primitive during SSR          |
-| `no_element`       | Passing a null or undefined `element` to a primitive |
-| `invalid_duration` | `useTween` duration is zero, negative, or NaN        |
-| `ticker_stopped`   | Calling `start`/`resume` on a stopped ticker         |
-| `missing_context`  | `<Swap.State>` used outside `<Swap>`                 |
+| Code               | Trigger                                             |
+| ------------------ | --------------------------------------------------- |
+| `server_context`   | Calling a browser-only primitive during SSR         |
+| `no_target`        | Passing a null or undefined `target` to a primitive |
+| `invalid_duration` | `useTween` duration is zero, negative, or NaN       |
+| `ticker_stopped`   | Calling `start`/`resume` on a stopped ticker        |
+| `missing_context`  | `<Swap.State>` used outside `<Swap>`                |
 
 ## Relationship to View Transitions
 
@@ -1232,18 +1232,18 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | Export                    | Size (min+brotli) |
 | ------------------------- | ----------------: |
 | **Core**                  |                   |
-| `createTicker`            |             846 B |
-| `createSight`             |             967 B |
+| `createTicker`            |             847 B |
+| `createSight`             |             970 B |
 | `createLifecycle`         |           1.48 kB |
-| `createLoop`              |           2.62 kB |
-| `createScrollProgress`    |             866 B |
-| `createRenderState`       |             495 B |
+| `createLoop`              |            2.6 kB |
+| `createScrollProgress`    |             865 B |
+| `createRenderState`       |             490 B |
 | `createDevicePixelRatio`  |             544 B |
-| `createMutation`          |           1.18 kB |
-| `createPointer`           |           1.27 kB |
-| `createScroll`            |           1.45 kB |
-| `createThrottle`          |             657 B |
-| `createDebounce`          |             559 B |
+| `createMutation`          |           1.17 kB |
+| `createPointer`           |           1.26 kB |
+| `createScroll`            |           1.46 kB |
+| `createThrottle`          |             659 B |
+| `createDebounce`          |             557 B |
 | `whenIdle`                |             409 B |
 | `prefersReducedMotion`    |             101 B |
 | **Ease**                  |                   |
@@ -1253,14 +1253,14 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | `useLifecycle`            |           1.68 kB |
 | `useSight`                |           1.18 kB |
 | `useCanvas`               |           3.47 kB |
-| `useMutation`             |           1.36 kB |
-| `usePointer`              |           1.47 kB |
+| `useMutation`             |           1.37 kB |
+| `usePointer`              |           1.48 kB |
 | `useScroll`               |           1.72 kB |
 | `useThrottledCallback`    |             797 B |
-| `useDebouncedCallback`    |             688 B |
+| `useDebouncedCallback`    |             687 B |
 | `useTween`                |             655 B |
 | `usePresence`             |             591 B |
-| `useScrollProgress`       |             997 B |
+| `useScrollProgress`       |             999 B |
 | `useSize`                 |             378 B |
 | `useContainerQuery`       |             384 B |
 | `useMediaQuery`           |             246 B |
@@ -1269,13 +1269,13 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | `useSyncedRef`            |              22 B |
 | `useStableCallback`       |              39 B |
 | `Presence`                |             741 B |
-| `WhenVisible`             |           1.44 kB |
+| `WhenVisible`             |           1.43 kB |
 | `WhenIdle`                |             593 B |
 | `Defer`                   |              86 B |
 | `useIdle`                 |             435 B |
-| `useWhenIdle`             |             445 B |
-| `useRenderState`          |             527 B |
-| `Swap`                    |           1.13 kB |
+| `useWhenIdle`             |             446 B |
+| `useRenderState`          |             521 B |
+| `Swap`                    |           1.12 kB |
 
 <!-- SIZE-TABLE:END -->
 

package/dist/{debounce-C0SgiTfm.js → debounce-BX3NrBak.js}

@@ -49,10 +49,10 @@ function serverContextError(fn) {
 		fix: "Move into a useEffect or client-only module."
 	});
 }
-function noElementError(fn) {
-	throw new PhaseError(`${fn}() requires a DOM element.`, {
-		code: "no_element",
-		reason: "The element was null or undefined.",
+function noTargetError(fn) {
+	throw new PhaseError(`${fn}() requires a target.`, {
+		code: "no_target",
+		reason: "The target was null or undefined.",
 		fix: "Pass a mounted Element, or use the React hook which manages the ref."
 	});
 }
@@ -280,7 +280,7 @@ const createPoolEntry$1 = (options) => {
 *
 * @example
 * const sight = createSight({
-*   element: el,
+*   target: el,
 *   onPhaseChange: (phase) => phase === 'visible' ? loop.start() : loop.pause(),
 * });
 * // cleanup:
@@ -291,8 +291,8 @@ const createPoolEntry$1 = (options) => {
 */
 function createSight(options) {
 	if (typeof document === "undefined") serverContextError("createSight");
-	const { element, intersectionOptions, onPhaseChange, signal } = options;
-	if (!element) noElementError("createSight");
+	const { target, intersectionOptions, onPhaseChange, signal } = options;
+	if (!target) noTargetError("createSight");
 	let _phase = "unknown";
 	let _reason = "initial";
 	let stopped = false;
@@ -323,7 +323,7 @@ function createSight(options) {
 	document.addEventListener("visibilitychange", onVisibilityChange);
 	window.addEventListener("pageshow", onPageShow);
 	const unobserveIO = observeIntersection({
-		element,
+		element: target,
 		onIntersect: onIntersection,
 		...intersectionOptions
 	});
@@ -416,7 +416,7 @@ const REDUCED_MOTION_QUERY$1 = "(prefers-reduced-motion: reduce)";
 *
 * @example
 * const lifecycle = createLifecycle({
-*   element: canvas,
+*   target: canvas,
 *   onPhaseChange: (phase) => {
 *     if (phase === 'active') renderer.start();
 *     else renderer.stop();
@@ -427,8 +427,8 @@ const REDUCED_MOTION_QUERY$1 = "(prefers-reduced-motion: reduce)";
 */
 function createLifecycle(options) {
 	if (typeof document === "undefined") serverContextError("createLifecycle");
-	const { element, reducedMotion = "pause", intersectionOptions, start: startMode = "auto", onPhaseChange, signal } = options;
-	if (!element) noElementError("createLifecycle");
+	const { target, reducedMotion = "pause", intersectionOptions, start: startMode = "auto", onPhaseChange, signal } = options;
+	if (!target) noTargetError("createLifecycle");
 	let _phase = "idle";
 	let _reason = "initial";
 	let sightVisible = false;
@@ -468,7 +468,7 @@ function createLifecycle(options) {
 		reconcile();
 	}
 	const sight = createSight({
-		element,
+		target,
 		intersectionOptions,
 		onPhaseChange: onSightChange
 	});
@@ -545,7 +545,7 @@ const RECOVERY_RETRY_MS = 2e3;
 *
 * @example
 * const loop = createLoop({
-*   element: el,
+*   target: el,
 *   onTick: (frame) => draw(ctx, frame),
 * });
 * // cleanup:
@@ -553,8 +553,8 @@ const RECOVERY_RETRY_MS = 2e3;
 */
 function createLoop(options) {
 	if (typeof requestAnimationFrame === "undefined") serverContextError("createLoop");
-	const { element, onTick, fps: baseFps, reducedMotion = "pause", degraded = "throttle", degradedFps: configuredDegradedFps, intersectionOptions, start: startMode = "auto", onPhaseChange, signal } = options;
-	if (!element) noElementError("createLoop");
+	const { target, onTick, fps: baseFps, reducedMotion = "pause", degraded = "throttle", degradedFps: configuredDegradedFps, intersectionOptions, start: startMode = "auto", onPhaseChange, signal } = options;
+	if (!target) noTargetError("createLoop");
 	const degradedFps = degraded === "throttle" ? configuredDegradedFps : void 0;
 	let _phase = "idle";
 	let _reason = "initial";
@@ -675,7 +675,7 @@ function createLoop(options) {
 		reconcileQuality();
 	}
 	const lifecycle = createLifecycle({
-		element,
+		target,
 		reducedMotion: reducedMotion === "pause" ? "pause" : "ignore",
 		intersectionOptions,
 		start: "manual",
@@ -745,7 +745,7 @@ function buildThresholds(steps) {
 *
 * @example
 * const progress = createScrollProgress({
-*   element: el,
+*   target: el,
 *   onProgress: (ratio) => {
 *     el.style.opacity = String(ratio);
 *   },
@@ -755,8 +755,8 @@ function buildThresholds(steps) {
 */
 function createScrollProgress(options) {
 	if (typeof IntersectionObserver === "undefined") serverContextError("createScrollProgress");
-	const { element, onProgress, steps = DEFAULT_STEPS, root, rootMargin, signal } = options;
-	if (!element) noElementError("createScrollProgress");
+	const { target: element, onProgress, steps = DEFAULT_STEPS, root, rootMargin, signal } = options;
+	if (!element) noTargetError("createScrollProgress");
 	let _ratio = 0;
 	let stopped = false;
 	const unobserve = observeIntersection({
@@ -802,7 +802,7 @@ function createScrollProgress(options) {
 *
 * @example
 * const render = createRenderState({
-*   element: el,
+*   target: el,
 *   onPhaseChange: (phase) => phase === 'skipped' ? clock.pause() : clock.resume(),
 * });
 * // cleanup:
@@ -817,8 +817,8 @@ function createScrollProgress(options) {
 */
 function createRenderState(options) {
 	if (typeof document === "undefined") serverContextError("createRenderState");
-	const { element, onPhaseChange, signal } = options;
-	if (!element) noElementError("createRenderState");
+	const { target: element, onPhaseChange, signal } = options;
+	if (!element) noTargetError("createRenderState");
 	let _phase = "rendered";
 	let stopped = false;
 	function onStateChange(event) {
@@ -947,8 +947,8 @@ function prefersReducedMotion() {
 /** Lifecycle-aware MutationObserver with rAF-coalesced callbacks. */
 function createMutation(options) {
 	if (typeof document === "undefined") serverContextError("createMutation");
-	const { element, mutation: mutationInit, onMutations, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
-	if (!element) noElementError("createMutation");
+	const { target: element, mutation: mutationInit, onMutations, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
+	if (!element) noTargetError("createMutation");
 	warnReflowStorm(mutationInit);
 	let _phase = "paused";
 	let _reason = "initial";
@@ -1065,8 +1065,8 @@ function warnReflowStorm(opts) {
 /** Lifecycle-aware pointer tracker with rAF-batched `getBoundingClientRect`. */
 function createPointer(options) {
 	if (typeof document === "undefined") serverContextError("createPointer");
-	const { element, onPointer, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
-	if (!element) noElementError("createPointer");
+	const { target: element, onPointer, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
+	if (!element) noTargetError("createPointer");
 	let _phase = "idle";
 	let _reason = "initial";
 	let stopped = false;
@@ -1254,8 +1254,8 @@ function getObserver() {
 */
 function createScroll(options) {
 	if (typeof document === "undefined") serverContextError("createScroll");
-	const { element, onScroll, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
-	if (!element) noElementError("createScroll");
+	const { target, onScroll, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
+	if (!target) noTargetError("createScroll");
 	let _phase = "paused";
 	let _reason = "initial";
 	let stopped = false;
@@ -1281,8 +1281,8 @@ function createScroll(options) {
 	}
 	function computePosition() {
 		const { maxX, maxY } = _state;
-		const x = element.scrollLeft;
-		const y = element.scrollTop;
+		const x = target.scrollLeft;
+		const y = target.scrollTop;
 		_state.x = x < 0 ? 0 : x > maxX ? maxX : x;
 		_state.y = y < 0 ? 0 : y > maxY ? maxY : y;
 		_state.progressX = maxX > 0 ? _state.x / maxX : 0;
@@ -1290,10 +1290,10 @@ function createScroll(options) {
 	}
 	function measure() {
 		if (stopped || !listenersAttached) return;
-		const scrollWidth = element.scrollWidth;
-		const clientWidth = element.clientWidth;
-		const scrollHeight = element.scrollHeight;
-		const clientHeight = element.clientHeight;
+		const scrollWidth = target.scrollWidth;
+		const clientWidth = target.clientWidth;
+		const scrollHeight = target.scrollHeight;
+		const clientHeight = target.clientHeight;
 		const maxX = scrollWidth - clientWidth;
 		const maxY = scrollHeight - clientHeight;
 		_state.maxX = maxX > 0 ? maxX : 0;
@@ -1333,14 +1333,14 @@ function createScroll(options) {
 	function attachListeners() {
 		if (listenersAttached) return;
 		listenersAttached = true;
-		element.addEventListener("scroll", onScrollEvent, { passive: true });
-		unobserveRO = observeResize(element, onROResize);
+		target.addEventListener("scroll", onScrollEvent, { passive: true });
+		unobserveRO = observeResize(target, onROResize);
 		measure();
 	}
 	function detachListeners() {
 		if (!listenersAttached) return;
 		listenersAttached = false;
-		element.removeEventListener("scroll", onScrollEvent);
+		target.removeEventListener("scroll", onScrollEvent);
 		unobserveRO?.();
 		unobserveRO = void 0;
 		cancelFlush();
@@ -1372,7 +1372,7 @@ function createScroll(options) {
 		document.addEventListener("visibilitychange", onVisChange);
 		window.addEventListener("pageshow", onPageShow);
 		const unobserveIO = observeIntersection({
-			element,
+			element: target,
 			onIntersect: (entry) => {
 				elementInView = entry.isIntersecting;
 				recompute();
@@ -1618,4 +1618,4 @@ function createDebounce(options) {
 //#endregion
 export { missingContextError as C, isPhaseError as S, linkAbortSignal as T, subscribeMediaQuery as _, createPointer as a, PhaseError as b, prefersReducedMotion as c, subscribeDpr as d, createRenderState as f, readMediaQuery as g, createLifecycle as h, observeResize as i, whenIdle as l, createLoop as m, createThrottle as n, createMutation as o, createScrollProgress as p, createScroll as r, REDUCED_MOTION_QUERY as s, createDebounce as t, readDpr as u, createSight as v, serverContextError as w, invalidDurationError as x, createTicker as y };
 
-//# sourceMappingURL=debounce-C0SgiTfm.js.map
+//# sourceMappingURL=debounce-BX3NrBak.js.map