@sharadox/pointer-web-library 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,6 +4,7 @@ Pointer effects for React websites:
4
4
 
5
5
  - **`useSpotlight`:** the pointer's position inside an element as `--pointer-x` and `--pointer-y`, for lights that follow it.
6
6
  - **`useTilt(maximum)`:** `--tilt-x` and `--tilt-y` in degrees, for a 3D tilt towards the pointer. It eases back when the pointer leaves, and is off on touch screens.
7
+ - **`useParallax(ease)`:** where the pointer is over an element as `--parallax-x` and `--parallax-y` (-1 to 1) and `--parallax-hover` (0 to 1), eased every frame and back to 0 when it leaves, for scenes with depth. It is off on touch screens and with reduced motion.
7
8
  - **`<Cursor>`:** a dot and a lagging ring. The ring grows over clickable elements and turns dashed over draggable ones. It uses blend mode `difference`, so it shows on any background, and only runs on fine pointers.
8
9
 
9
10
  ## Install
@@ -25,6 +26,11 @@ const stage = useTilt<HTMLDivElement>(6);
25
26
  // .stage { transform: perspective(900px) rotateX(var(--tilt-x)) rotateY(var(--tilt-y)) }
26
27
  ```
27
28
 
29
+ ```tsx
30
+ const scene = useParallax<HTMLDivElement>(0.08);
31
+ // .phone { transform: translate3d(calc(var(--parallax-x, 0) * 14px), calc(var(--parallax-y, 0) * 10px), 60px) }
32
+ ```
33
+
28
34
  ```tsx
29
35
  <Cursor grabSelector="canvas, [data-grab]" />
30
36
  ```
@@ -35,6 +41,7 @@ const stage = useTilt<HTMLDivElement>(6);
35
41
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
36
42
  | `…/spotlight` | `useSpotlight<T>()` → reference |
37
43
  | `…/tilt` | `useTilt<T>(maximum = 8)` → reference |
44
+ | `…/parallax` | `useParallax<T>(ease = 0.1)` → reference; CSS variables `--parallax-x`, `--parallax-y`, `--parallax-hover` |
38
45
  | `…/cursor` | `<Cursor hotSelector? grabSelector? className?>`, `HOT_ELEMENTS`, `GRAB_ELEMENTS`; CSS variables `--cursor-color` and `--cursor-size` |
39
46
 
40
47
  ## Develop
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Where the pointer is over an element, eased, for depth that follows it. Sets three unitless CSS variables on the
3
+ * element, each eased towards its target every frame (`ease` is the share of the distance covered per frame):
4
+ * `--parallax-x` and `--parallax-y` (-1 at the left or top edge, 0 in the middle, 1 at the right or bottom edge) and
5
+ * `--parallax-hover` (1 while the pointer is over it, 0 once it has left). All three ease back to 0 when the pointer
6
+ * leaves. Use them with `calc()`, for example
7
+ * `transform: rotateY(calc(var(--parallax-x, 0) * 8deg)) translateX(calc(var(--parallax-x, 0) * 12px))`.
8
+ * Off on touch screens and when less motion is asked for, so the variables stay unset there.
9
+ */
10
+ export declare function useParallax<Target extends HTMLElement>(ease?: number): import("react").RefObject<Target | null>;
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/parallax/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,WAAW,EAAE,IAAI,SAAM,4CA8CjE"}
@@ -0,0 +1,62 @@
1
+ "use client";
2
+ import { useEffect, useRef } from "react";
3
+ import { clamp } from "@sharadox/web-library/math/clamp";
4
+ /**
5
+ * Where the pointer is over an element, eased, for depth that follows it. Sets three unitless CSS variables on the
6
+ * element, each eased towards its target every frame (`ease` is the share of the distance covered per frame):
7
+ * `--parallax-x` and `--parallax-y` (-1 at the left or top edge, 0 in the middle, 1 at the right or bottom edge) and
8
+ * `--parallax-hover` (1 while the pointer is over it, 0 once it has left). All three ease back to 0 when the pointer
9
+ * leaves. Use them with `calc()`, for example
10
+ * `transform: rotateY(calc(var(--parallax-x, 0) * 8deg)) translateX(calc(var(--parallax-x, 0) * 12px))`.
11
+ * Off on touch screens and when less motion is asked for, so the variables stay unset there.
12
+ */
13
+ export function useParallax(ease = 0.1) {
14
+ const reference = useRef(null);
15
+ useEffect(() => {
16
+ const element = reference.current;
17
+ if (!element || !matchMedia("(pointer: fine)").matches || matchMedia("(prefers-reduced-motion: reduce)").matches) {
18
+ return;
19
+ }
20
+ const target = { x: 0, y: 0, hover: 0 };
21
+ const current = { x: 0, y: 0, hover: 0 };
22
+ let frame = 0;
23
+ const step = () => {
24
+ let distance = 0;
25
+ for (const key of ["x", "y", "hover"]) {
26
+ current[key] += (target[key] - current[key]) * ease;
27
+ distance += Math.abs(target[key] - current[key]);
28
+ }
29
+ // Close enough: land exactly on the target and stop asking for frames.
30
+ if (distance < 0.001)
31
+ Object.assign(current, target);
32
+ element.style.setProperty("--parallax-x", current.x.toFixed(4));
33
+ element.style.setProperty("--parallax-y", current.y.toFixed(4));
34
+ element.style.setProperty("--parallax-hover", current.hover.toFixed(4));
35
+ frame = distance < 0.001 ? 0 : requestAnimationFrame(step);
36
+ };
37
+ const start = () => {
38
+ if (!frame)
39
+ frame = requestAnimationFrame(step);
40
+ };
41
+ const move = (event) => {
42
+ const bounds = element.getBoundingClientRect();
43
+ target.x = clamp(((event.clientX - bounds.left) / bounds.width) * 2 - 1, -1, 1);
44
+ target.y = clamp(((event.clientY - bounds.top) / bounds.height) * 2 - 1, -1, 1);
45
+ target.hover = 1;
46
+ start();
47
+ };
48
+ const leave = () => {
49
+ Object.assign(target, { x: 0, y: 0, hover: 0 });
50
+ start();
51
+ };
52
+ element.addEventListener("pointermove", move);
53
+ element.addEventListener("pointerleave", leave);
54
+ return () => {
55
+ element.removeEventListener("pointermove", move);
56
+ element.removeEventListener("pointerleave", leave);
57
+ cancelAnimationFrame(frame);
58
+ };
59
+ }, [ease]);
60
+ return reference;
61
+ }
62
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/parallax/index.ts"],"names":[],"mappings":"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"}
package/llms.txt CHANGED
@@ -4,5 +4,6 @@
4
4
 
5
5
  - /spotlight: useSpotlight<T>() → ref; sets --pointer-x/--pointer-y (px) on pointermove
6
6
  - /tilt: useTilt<T>(maximum=8) → ref; sets --tilt-x/--tilt-y (deg); resets on leave; fine pointers only
7
+ - /parallax: useParallax<T>(ease=0.1) → ref; sets unitless --parallax-x/--parallax-y (-1..1) and --parallax-hover (0..1), eased per animation frame, back to 0 on leave; fine pointers without reduced motion only
7
8
  - /cursor: <Cursor hotSelector grabSelector className /> dot + lagging ring, mix-blend difference; --cursor-color, --cursor-size; html gets class while active (hides system cursor)
8
9
  - Peer: react. License: Sharadox Open Source License 0.1.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sharadox/pointer-web-library",
3
- "version": "0.1.1",
4
- "description": "Pointer effects for React: a spotlight that follows the pointer, 3D tilt towards it and a custom cursor.",
3
+ "version": "0.2.0",
4
+ "description": "Pointer effects for React: a spotlight that follows the pointer, 3D tilt towards it, eased parallax and a custom cursor.",
5
5
  "private": false,
6
6
  "license": "SEE LICENSE IN LICENCA.md",
7
7
  "author": "Sharadox <contact@sharadox.com>",