@exegia/specular 0.1.1 → 0.1.2

package/README.md

@@ -243,6 +243,13 @@ make example-dev       # build the library, install the example, start Vite
 make example-build     # production build, what CI runs
 ```
 
+A focused `demo/` app shows just the apply steps and the hover behaviour
+(cards lift, glow buttons, press sink, pointer-following light and rims):
+
+```bash
+make demo-dev          # build the library, install the demo, start Vite
+```
+
 See [`examples/vite-react/README.md`](examples/vite-react/README.md) for what
 each section shows.
 

package/dist/index.d.ts

@@ -43,6 +43,22 @@ export type SurfaceConfig = {
 };
 export type Surfaces = Record<string, SurfaceConfig>;
 export declare function defineSurfaces<const T extends Surfaces>(surfaces: T): T;
+/** Instance-tier custom properties `litVars()` writes: `--tw-{surface}-lit-x/y`. */
+export type LitVars = {
+    [k: `--tw-${string}-lit-x`]: string;
+} & {
+    [k: `--tw-${string}-lit-y`]: string;
+};
+/**
+ * Instance-tier vars that turn a surface's lit edge toward a pointer bearing.
+ *
+ * Bearing 0 = 12 o'clock, clockwise. The offset is (-sin, +cos) · depth: an
+ * inset layer offset exposes the band OPPOSITE the offset, so a bearing of 0
+ * (cursor above) writes (−0, +depth) — the top edge lights up. Pair with
+ * `usePointerLight(ref)` and spread into `style`. `surface` must match the
+ * surface name in your `defineSurfaces` config.
+ */
+export declare function litVars(angle: number, depth?: number, surface?: string): LitVars;
 export type ResolvedLayer = {
     name: string;
     inset: boolean;

package/dist/index.js

@@ -40,6 +40,22 @@ export function defineSurfaces(surfaces) {
     }
     return surfaces;
 }
+/**
+ * Instance-tier vars that turn a surface's lit edge toward a pointer bearing.
+ *
+ * Bearing 0 = 12 o'clock, clockwise. The offset is (-sin, +cos) · depth: an
+ * inset layer offset exposes the band OPPOSITE the offset, so a bearing of 0
+ * (cursor above) writes (−0, +depth) — the top edge lights up. Pair with
+ * `usePointerLight(ref)` and spread into `style`. `surface` must match the
+ * surface name in your `defineSurfaces` config.
+ */
+export function litVars(angle, depth = 2.5, surface = "card") {
+    const rad = (angle * Math.PI) / 180;
+    return {
+        [`--tw-${surface}-lit-x`]: `${(-Math.sin(rad) * depth).toFixed(2)}px`,
+        [`--tw-${surface}-lit-y`]: `${(Math.cos(rad) * depth).toFixed(2)}px`,
+    };
+}
 export const LAYER_PROPS = ["x", "y", "blur", "spread", "color", "alpha"];
 export function length(v, fallback = "0") {
     if (v === undefined)

package/dist/pointer-light.d.ts

@@ -18,7 +18,7 @@ export declare function bearingFrom(cx: number, cy: number, x: number, y: number
  */
 export declare function unwrap(last: number, bearing: number): number | null;
 /** Register a target; the listener exists only while the set is non-empty. */
-export declare function subscribe(target: () => Element | null, emit: (angle: number) => void): () => void;
+export declare function subscribe(target: () => Element | null, emit: (angle: number) => void, damping?: number): () => void;
 /** For tests. */
 export declare const subscriberCount: () => number;
 /** `false` on the server and on first render; tracks the media query after. */
@@ -26,10 +26,12 @@ export declare function useReducedMotion(): boolean;
 export type PointerLightOptions = {
     mode?: "state";
     enabled?: boolean;
+    damping?: number;
 } | {
     mode: "var";
     property?: string;
     enabled?: boolean;
+    damping?: number;
 };
 /**
  * `mode: "state"` (default) returns the raw bearing and re-renders on change.
@@ -41,9 +43,11 @@ export type PointerLightOptions = {
 export declare function usePointerLight(ref: RefObject<Element | null>, options?: {
     mode?: "state";
     enabled?: boolean;
+    damping?: number;
 }): number;
 export declare function usePointerLight(ref: RefObject<Element | null>, options: {
     mode: "var";
     property?: string;
     enabled?: boolean;
+    damping?: number;
 }): void;

package/dist/pointer-light.js

@@ -39,6 +39,7 @@ function flush() {
     frame = 0;
     if (!pointer)
         return;
+    let unsettled = false;
     for (const s of subscribers) {
         const el = s.target();
         if (!el)
@@ -46,12 +47,39 @@ function flush() {
         const rect = el.getBoundingClientRect();
         if (rect.width === 0)
             continue;
-        const next = unwrap(s.last, bearingFrom(rect.left + rect.width / 2, rect.top + rect.height / 2, pointer.x, pointer.y));
-        if (next === null)
+        const bearing = bearingFrom(rect.left + rect.width / 2, rect.top + rect.height / 2, pointer.x, pointer.y);
+        if (s.damping >= 1) {
+            const next = unwrap(s.last, bearing);
+            if (next === null)
+                continue;
+            s.last = next;
+            s.emit(next);
             continue;
-        s.last = next;
-        s.emit(next);
+        }
+        // Damped: ease along the shortest arc each frame, self-scheduling until
+        // the residual is under a degree. `last` stays continuous.
+        if (Number.isNaN(s.last)) {
+            s.last = bearing;
+            s.emit(bearing);
+            continue;
+        }
+        let d = bearing - (((s.last % 360) + 360) % 360);
+        if (d > 180)
+            d -= 360;
+        if (d < -180)
+            d += 360;
+        if (Math.abs(d) <= ANGLE_EPSILON) {
+            s.last = bearing;
+            continue;
+        }
+        const moved = s.last + d * s.damping;
+        s.last = moved;
+        s.emit(moved);
+        if (Math.abs(d) * (1 - s.damping) > 0.5)
+            unsettled = true;
     }
+    if (unsettled && frame === 0)
+        frame = requestAnimationFrame(flush);
 }
 function onMove(event) {
     pointer = { x: event.clientX, y: event.clientY };
@@ -59,8 +87,8 @@ function onMove(event) {
         frame = requestAnimationFrame(flush);
 }
 /** Register a target; the listener exists only while the set is non-empty. */
-export function subscribe(target, emit) {
-    const sub = { target, last: Number.NaN, emit };
+export function subscribe(target, emit, damping = 1) {
+    const sub = { target, last: Number.NaN, emit, damping };
     if (subscribers.size === 0)
         window.addEventListener("pointermove", onMove, { passive: true });
     subscribers.add(sub);
@@ -96,6 +124,7 @@ export function usePointerLight(ref, options = {}) {
     const reduce = useReducedMotion();
     const enabled = options.enabled ?? true;
     const mode = options.mode ?? "state";
+    const damping = options.damping ?? 1;
     const property = options.mode === "var" ? (options.property ?? "--light-angle") : null;
     useEffect(() => {
         if (!enabled || reduce)
@@ -103,7 +132,7 @@ export function usePointerLight(ref, options = {}) {
         const emit = property === null
             ? setAngle
             : (a) => ref.current?.style.setProperty(property, `${a}deg`);
-        return subscribe(() => ref.current, emit);
-    }, [enabled, reduce, property, ref]);
+        return subscribe(() => ref.current, emit, damping);
+    }, [enabled, reduce, property, ref, damping]);
     return mode === "state" ? angle : undefined;
 }

package/dist/rim.d.ts

@@ -22,5 +22,5 @@ export type RimProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
     lo?: number;
 };
 /** transitions.dev `--duration-quick` / `--ease-smooth-out`. */
-export declare const RIM_TRANSITION = "transform 150ms cubic-bezier(0.22, 1, 0.36, 1)";
+export declare const RIM_TRANSITION = "transform 350ms cubic-bezier(0.22, 1, 0.36, 1)";
 export declare function Rim({ angle, hi, lo, style, ...rest }: RimProps): import("react").JSX.Element;

package/dist/rim.js

@@ -4,7 +4,7 @@ import { useReducedMotion } from "./pointer-light.js";
 const GRADIENT = "conic-gradient(from 180deg, var(--rim-lo) 0%, transparent 24%, transparent 28%, var(--rim-hi) 50%, transparent 72%, transparent 76%, var(--rim-lo) 100%)";
 const MASK = "radial-gradient(farthest-side, transparent 78%, #000 92%)";
 /** transitions.dev `--duration-quick` / `--ease-smooth-out`. */
-export const RIM_TRANSITION = "transform 150ms cubic-bezier(0.22, 1, 0.36, 1)";
+export const RIM_TRANSITION = "transform 350ms cubic-bezier(0.22, 1, 0.36, 1)";
 export function Rim({ angle = 0, hi, lo, style, ...rest }) {
     const reduce = useReducedMotion();
     const vars = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/specular",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/emmanuel-defreitas/specular.git"