@exegia/specular 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel De Freitas
+
+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

@@ -1,10 +1,32 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="" width="132" height="132">
+
 # @exegia/specular
 
-Specular lighting for Tailwind v4 + React: a highlight that tracks the pointer.
-Declare a surface, get a utility
-family that draws a two-layer inset "bezel" one axis at a time, a
-tailwind-merge config that keeps those utilities alive in `cn()`, and React
-primitives that light the surface with the pointer.
+**✨ Specular lighting for Tailwind v4 + React — a two-layer inset bezel as
+utilities, a `cn()` that keeps them alive, and a rim highlight that tracks the
+pointer.**
+
+[![npm](https://img.shields.io/npm/v/@exegia/specular?color=6366f1&labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular) [![types](https://img.shields.io/npm/types/@exegia/specular?color=38bdf8&labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular) [![provenance](https://img.shields.io/badge/npm-provenance-a855f7?labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular#provenance) [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-f43f5e?labelColor=1c1917)](#install) [![license](https://img.shields.io/npm/l/@exegia/specular?color=fbbf24&labelColor=1c1917)](LICENSE)
+
+<img src="assets/demo.gif" alt="Six avatars whose rim highlights turn to follow the pointer as it moves across them" width="100%">
+
+<sub>Six discs, one window listener. Recorded from <a href="examples/vite-react"><code>examples/vite-react</code></a>.</sub>
+
+</div>
+
+---
+
+Declare a surface, get a utility family that draws a two-layer inset "bezel"
+one axis at a time, a tailwind-merge config that keeps those utilities alive
+in `cn()`, and React primitives that light the surface with the pointer.
+
+## Install
+
+```bash
+npm i @exegia/specular      # or: bun add / pnpm add / yarn add
+```
 
 | export | contents |
 |---|---|
@@ -97,8 +119,8 @@ For a surface `S` and a layer `L`. Every utility also emits the base
 | utility | writes |
 |---|---|
 | `S-base` (or `baseClass`) | `box-shadow: var(--tw-S-shadow)` |
-| `S-L` | `--tw-S-L-alpha: 100` |
-| `S-L/40`, `S-L/[0.4]` | `--tw-S-L-alpha: 40` (fractions are scaled; `/80` ≡ `/[0.8]`) |
+| `S-L` | the base `box-shadow` only: layer `L` at its configured alpha, so the `dark` preset applies |
+| `S-L/40`, `S-L/[0.4]` | `--tw-S-L-alpha: 40` (fractions are scaled; `/80` ≡ `/[0.8]`); `/100` is explicit full strength |
 | `S-L-t-N` | `--tw-S-L-y: calc(N * 1px)` — light enters from the top, pushes the layer down |
 | `S-L-b-N` | `--tw-S-L-y: calc(N * -1px)` |
 | `S-L-l-N` / `S-L-r-N` | `--tw-S-L-x` |
@@ -221,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/plugin.js

@@ -20,6 +20,9 @@ export function normalizeAlpha(raw) {
         return String(Math.round(parseFloat(v) * 10000) / 100);
     return v;
 }
+/** The `DEFAULT` value handed to the bare layer class. A sentinel, not a
+ * number, so `S-L-[100]` (an arbitrary value) still writes the alpha. */
+const CONFIGURED = "configured";
 const instanceVar = (s, l, p) => `--tw-${s}-${l}-${p}`;
 const presetVar = (s, l, p) => `--${s}-${l}-${p}`;
 function chain(s, l, p) {
@@ -75,8 +78,14 @@ export function createPlugin(surfaces, options = {}) {
                 const n = `${s.name}-${l.name}`;
                 const v = (p) => instanceVar(s.name, l.name, p);
                 const set = (p, f = (x) => x) => (value) => ({ ...base, [v(p)]: f(value) });
-                // Bare = full alpha; `/40` and `/[0.4]` = 40.
-                matchUtilities({ [n]: (value, { modifier }) => ({ ...base, [v("alpha")]: normalizeAlpha(modifier ?? value) }) }, { values: { DEFAULT: "100" }, modifiers: "any" });
+                // Bare = the configured alpha: the class emits only the composed
+                // box-shadow, so the alpha chain falls through to the preset (the
+                // `dark` block) and then the config. Writing 100 here would make the
+                // canonical `bezel-lit bezel-dim` ignore both. `/40` and `/[0.4]` = 40;
+                // `/100` is the explicit full-strength form.
+                matchUtilities({
+                    [n]: (value, { modifier }) => modifier === null && value === CONFIGURED ? base : { ...base, [v("alpha")]: normalizeAlpha(modifier ?? value) },
+                }, { values: { DEFAULT: CONFIGURED }, modifiers: "any" });
                 // The letter names the edge the light enters from.
                 matchUtilities({ [`${n}-t`]: set("y"), [`${n}-l`]: set("x"), [`${n}-blur`]: set("blur"), [`${n}-spread`]: set("spread") }, lengths(false));
                 matchUtilities({ [`${n}-b`]: set("y", negate), [`${n}-r`]: set("x", negate) }, lengths(true));

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.0",
+  "version": "0.1.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/emmanuel-defreitas/specular.git"