apex-ui-kit 2.5.0 → 2.7.0

package/dist/ApexUI-Kit/templates/HorizonGlow/HorizonGlow.jsx

@@ -0,0 +1,259 @@
+import React, { useEffect, useRef } from "react";
+import { Color, Mesh, OrthographicCamera, PlaneGeometry, Scene, ShaderMaterial, Vector2, WebGLRenderer } from "three";
+
+/*
+ * Horizon Glow: a soft, wide light rising from below the bottom edge, fading
+ * from a pale core through an accent band and a mid tone into a deep sky,
+ * drawn in one WebGL shader. A thin luminous arc marks the horizon, faint
+ * volumetric rays climb out of it and specks of dust drift up through the
+ * light. It rises in on mount, breathes slowly and leans toward the pointer;
+ * a filmic tone curve and dithering keep the long gradient silky.
+ */
+
+const PRESETS = {
+    lilac: { sky: "#0d1438", mid: "#6f4c86", accent: "#ff9fd2", core: "#fff1f8" },
+    ocean: { sky: "#020f1c", mid: "#195a78", accent: "#58e1ff", core: "#e9fbff" },
+    ember: { sky: "#100606", mid: "#7a2f1e", accent: "#ff9b54", core: "#fff0dc" },
+    mint: { sky: "#04131a", mid: "#22625a", accent: "#6dffc4", core: "#ecfff6" },
+    mono: { sky: "#08080a", mid: "#45454d", accent: "#c9c9d6", core: "#ffffff" },
+};
+
+const VERT = `void main(){ gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+
+const FRAG = `
+precision highp float;
+uniform vec2 uRes; uniform float uTime; uniform float uRise; uniform vec2 uMouse;
+uniform vec3 uSky; uniform vec3 uMid; uniform vec3 uAccent; uniform vec3 uCore;
+uniform float uSpread; uniform float uIntensity; uniform float uShimmer; uniform float uBreath; uniform float uGrain;
+uniform float uArc; uniform float uRays; uniform float uDust;
+
+float h2(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+float n2(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p); vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(h2(i), h2(i + vec2(1, 0)), u.x), mix(h2(i + vec2(0, 1)), h2(i + vec2(1, 1)), u.x), u.y);
+}
+float fbm(vec2 p){ float v = 0.0; float a = 0.5; for (int i = 0; i < 4; i++) { v += a * n2(p); p *= 2.02; a *= 0.5; } return v; }
+
+// Drifting dust: one speck per cell, rising slowly and twinkling.
+float dust(vec2 p, float scale, float speed, float seed){
+  vec2 q = p * scale + vec2(seed, -uTime * speed);
+  vec2 id = floor(q); vec2 f = fract(q) - 0.5;
+  vec2 o = vec2(h2(id + seed), h2(id + seed + 3.1)) - 0.5;
+  float r = length(f - o * 0.7);
+  float tw = 0.5 + 0.5 * sin(uTime * (1.5 + h2(id) * 2.5) + h2(id + 9.0) * 6.28);
+  return smoothstep(0.06, 0.0, r) * step(0.55, h2(id + seed + 7.7)) * tw;
+}
+
+void main(){
+  vec2 uv = gl_FragCoord.xy / uRes;
+  float asp = uRes.x / uRes.y;
+  // Work in height units; wide screens get a wider glow, phones a taller one.
+  vec2 p = vec2((uv.x - 0.5) * asp, uv.y);
+  float width = max(asp, 0.8) * 0.82;
+
+  float rise = uRise;
+  float breath = 1.0 + uBreath * 0.035 * sin(uTime * 0.55) + uBreath * 0.015 * sin(uTime * 1.3 + 1.7);
+  vec2 c = vec2(uMouse.x * 0.06 * asp, mix(-1.1, -0.06, rise) + uMouse.y * 0.025);
+
+  // Elliptical distance from the light source below the edge.
+  vec2 e = (p - c) / vec2(width, 1.0);
+  float d0 = length(e);
+  // A slow shimmer that bends the falloff a little.
+  float s = fbm(vec2(p.x * 1.4, p.y * 1.1 - uTime * 0.035) + uTime * 0.02) - 0.5;
+  float d = d0 + s * 0.12 * uShimmer * smoothstep(1.4, 0.3, d0);
+
+  float reach = uSpread * breath * mix(0.35, 1.0, rise);
+  float t = clamp(d / reach, 0.0, 1.0);
+
+  // Core -> accent band -> mid tone -> sky.
+  vec3 col = mix(uCore, uMid, smoothstep(0.0, 0.62, t));
+  col = mix(col, uSky, smoothstep(0.38, 1.0, t));
+  float band = exp(-pow((t - 0.3) / 0.13, 2.0));
+  col = mix(col, col * 0.55 + uAccent * 0.55, band * 0.45);
+  col += uCore * exp(-d * d * 9.0 / (reach * reach)) * 0.25 * uIntensity;
+
+  // Volumetric rays climbing out of the source.
+  float ang = atan(p.x - c.x, (p.y - c.y) * 1.6);
+  float beams = n2(vec2(ang * 8.0, uTime * 0.07)) * 0.65 + n2(vec2(ang * 21.0, -uTime * 0.05)) * 0.35;
+  col += mix(uAccent, uCore, 0.5) * smoothstep(0.5, 1.0, beams) * exp(-t * 2.4) * smoothstep(0.02, 0.2, t) * 0.28 * uRays;
+
+  // Horizon arc: a thin bright rim where the light meets the edge of the world.
+  float pr = 0.9;
+  vec2 pc = vec2(c.x, c.y + 0.24 - pr);
+  float rd = length((p - pc) / vec2(max(asp, 0.8) * 1.05, 1.0)) - pr;
+  float fade = exp(-abs(p.x - c.x) / (width * 0.9));
+  col += mix(uAccent, uCore, 0.7) * (exp(-abs(rd) * 140.0) * 0.9 + exp(-max(rd, 0.0) * 14.0) * 0.18) * fade * uArc * rise;
+  col *= mix(1.0, 0.82, smoothstep(0.0, -0.08, rd) * uArc);
+
+  // Dust lit by the glow.
+  float lit = exp(-t * 2.2);
+  col += uCore * (dust(p, 9.0, 0.05, 1.0) + dust(p, 16.0, 0.09, 7.0) * 0.7) * lit * 0.55 * uDust * rise;
+
+  col = mix(uSky, col, clamp(uIntensity * (0.25 + 0.75 * rise), 0.0, 1.4));
+  // Darker corners at the top keep text readable.
+  col *= 1.0 - 0.12 * smoothstep(0.45, 1.1, uv.y) * smoothstep(0.1, 0.9, abs(uv.x - 0.5) * 2.0);
+  // Filmic shoulder so the core rolls off instead of clipping.
+  col = col / (1.0 + max(col - 0.85, 0.0));
+
+  col += (h2(gl_FragCoord.xy + fract(uTime * 7.0) * 91.0) - 0.5) * (1.0 + 7.0 * uGrain) / 255.0;
+  gl_FragColor = vec4(col, 1.0);
+}`;
+
+const HorizonGlow = ({
+    preset = "lilac",
+    skyColor,
+    midColor,
+    accentColor,
+    coreColor,
+    spread = 1.3,
+    intensity = 1,
+    duration = 2.4,
+    autoRise = true,
+    breathe = 1,
+    shimmer = 1,
+    arc = 0.7,
+    rays = 1,
+    dust = 1,
+    grain = 0.4,
+    speed = 1,
+    interactive = true,
+    replay = 0,
+    className = "",
+    children,
+}) => {
+    const wrap = useRef(null);
+    const p = PRESETS[preset] ?? PRESETS.lilac;
+    const live = useRef({});
+    live.current = { sky: skyColor ?? p.sky, mid: midColor ?? p.mid, accent: accentColor ?? p.accent, core: coreColor ?? p.core, spread, intensity, duration, autoRise, breathe, shimmer, arc, rays, dust, grain, speed, interactive };
+    const rise = useRef({ start: 0 });
+
+    useEffect(() => {
+        rise.current.start = performance.now();
+    }, [replay, autoRise]);
+
+    useEffect(() => {
+        const el = wrap.current;
+        const renderer = new WebGLRenderer({ antialias: false, alpha: false, powerPreference: "high-performance" });
+        renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 1.5));
+        Object.assign(renderer.domElement.style, { position: "absolute", inset: "0", width: "100%", height: "100%", display: "block" });
+        el.prepend(renderer.domElement);
+        const scene = new Scene();
+        const camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+        const u = {
+            uRes: { value: new Vector2(1, 1) },
+            uTime: { value: 0 },
+            uRise: { value: 0 },
+            uMouse: { value: new Vector2() },
+            uSky: { value: new Color() },
+            uMid: { value: new Color() },
+            uAccent: { value: new Color() },
+            uCore: { value: new Color() },
+            uSpread: { value: 1 },
+            uIntensity: { value: 1 },
+            uShimmer: { value: 1 },
+            uBreath: { value: 1 },
+            uGrain: { value: 0.4 },
+            uArc: { value: 0.7 },
+            uRays: { value: 1 },
+            uDust: { value: 1 },
+        };
+        const material = new ShaderMaterial({ vertexShader: VERT, fragmentShader: FRAG, uniforms: u, depthTest: false, depthWrite: false });
+        const geometry = new PlaneGeometry(2, 2);
+        scene.add(new Mesh(geometry, material));
+
+        const reduced = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+        const mouse = { x: 0, y: 0, tx: 0, ty: 0 };
+        let raf = 0;
+        let last = 0;
+        let time = 0;
+        let visible = true;
+
+        const draw = (now) => {
+            const o = live.current;
+            const dt = last ? Math.min(0.05, (now - last) / 1000) : 1 / 60;
+            last = now;
+            time += dt * o.speed;
+            const t = o.autoRise && !reduced ? Math.min(1, (now - rise.current.start) / (Math.max(0.1, o.duration) * 1000)) : 1;
+            // Ease out with a touch of overshoot-free settle.
+            u.uRise.value = 1 - Math.pow(1 - t, 4);
+            const k = 1 - Math.exp(-dt / 0.6);
+            mouse.x += ((o.interactive ? mouse.tx : 0) - mouse.x) * k;
+            mouse.y += ((o.interactive ? mouse.ty : 0) - mouse.y) * k;
+            u.uMouse.value.set(mouse.x, mouse.y);
+            u.uTime.value = time;
+            u.uSky.value.set(o.sky);
+            u.uMid.value.set(o.mid);
+            u.uAccent.value.set(o.accent);
+            u.uCore.value.set(o.core);
+            u.uSpread.value = o.spread;
+            u.uIntensity.value = o.intensity;
+            u.uShimmer.value = reduced ? 0 : o.shimmer;
+            u.uBreath.value = reduced ? 0 : o.breathe;
+            u.uGrain.value = o.grain;
+            u.uArc.value = o.arc;
+            u.uRays.value = reduced ? o.rays * 0.6 : o.rays;
+            u.uDust.value = reduced ? 0 : o.dust;
+            renderer.render(scene, camera);
+        };
+        const loop = (now) => {
+            raf = 0;
+            draw(now);
+            if (visible && !reduced) raf = requestAnimationFrame(loop);
+        };
+        const start = () => {
+            if (!raf && visible && !reduced) {
+                last = 0;
+                raf = requestAnimationFrame(loop);
+            }
+        };
+        const fit = () => {
+            const { width, height } = el.getBoundingClientRect();
+            if (!width || !height) return;
+            renderer.setSize(width, height, false);
+            renderer.getDrawingBufferSize(u.uRes.value);
+            if (!raf) draw(performance.now());
+        };
+
+        const onMove = (e) => {
+            const r = el.getBoundingClientRect();
+            mouse.tx = ((e.clientX - r.left) / r.width) * 2 - 1;
+            mouse.ty = -(((e.clientY - r.top) / r.height) * 2 - 1);
+        };
+        const onLeave = () => {
+            mouse.tx = 0;
+            mouse.ty = 0;
+        };
+        el.addEventListener("pointermove", onMove);
+        el.addEventListener("pointerleave", onLeave);
+        const ro = new ResizeObserver(fit);
+        ro.observe(el);
+        const io = new IntersectionObserver(([entry]) => {
+            visible = entry.isIntersecting;
+            if (visible) start();
+        });
+        io.observe(el);
+        fit();
+        start();
+
+        return () => {
+            cancelAnimationFrame(raf);
+            ro.disconnect();
+            io.disconnect();
+            el.removeEventListener("pointermove", onMove);
+            el.removeEventListener("pointerleave", onLeave);
+            geometry.dispose();
+            material.dispose();
+            renderer.dispose();
+            renderer.forceContextLoss();
+            renderer.domElement.remove();
+        };
+    }, []);
+
+    return (
+        <div ref={wrap} className={`relative h-full w-full overflow-hidden bg-[#0d1438] ${className}`}>
+            {children && <div className="relative z-10 h-full w-full">{children}</div>}
+        </div>
+    );
+};
+
+export default HorizonGlow;

package/dist/ApexUI-Kit/templates/LoadingScreen/LoadingScreen.jsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useRef, useState } from "react";
 import { AnimatePresence, motion, useAnimationControls, useReducedMotion } from "framer-motion";
+import { usePageProgress } from "./usePageProgress.js";
 
 /*
  * Loading Screen: five ways to wait.
@@ -9,50 +10,27 @@ import { AnimatePresence, motion, useAnimationControls, useReducedMotion } from
  *  catch    – a mini game: tap the orb before its ring runs out and build a combo
  *  runner   – a mini game: jump the neon pillars (Space / ↑ / tap) while things load
  *  racer    – a mini game: steer through traffic (← → / tap a side) while things load
- * Pass `progress` (0–100) yourself, or leave it out and it runs on its own.
+ * By default it shows the real page load: the bar and the count follow the
+ * images, scripts, styles and fonts the page is actually loading, and it
+ * hides itself once everything has loaded (autoHide). Pass `progress`
+ * (0 to 100) to drive it yourself instead.
  */
 
-const MESSAGES = ["Warming up the engines", "Fetching your components", "Polishing pixels", "Almost there"];
+const MESSAGES = ["Starting up", "Loading page", "Loading content", "Almost ready"];
 const messageFor = (v) => MESSAGES[Math.min(MESSAGES.length - 1, Math.floor(v / (100 / MESSAGES.length)))];
 
-// Simulated progress that eases toward 100 over `duration` ms, then calls onComplete.
-function useProgress(progress, duration, loop, onComplete) {
-    const [auto, setAuto] = useState(0);
+// Real progress: your own `progress` when given, otherwise the page's real load.
+function useProgress(progress, onComplete) {
+    const controlled = typeof progress === "number";
+    const page = usePageProgress(!controlled);
+    const value = Math.round(Math.max(0, Math.min(100, controlled ? progress : page.progress)));
     const doneRef = useRef(onComplete);
     doneRef.current = onComplete;
-    const controlled = typeof progress === "number";
-
-    useEffect(() => {
-        if (controlled) return undefined;
-        let raf = 0;
-        let start = performance.now();
-        let fired = false;
-        const tick = (now) => {
-            const t = Math.min(1, Math.max(0, (now - start) / duration));
-            // Fast start, slow middle, quick finish — the way real loads feel.
-            const eased = t < 0.85 ? 0.92 * (1 - Math.pow(1 - t / 0.85, 2.2)) : 0.92 + 0.08 * ((t - 0.85) / 0.15);
-            setAuto(Math.round(eased * 100));
-            if (t >= 1) {
-                if (!fired) {
-                    fired = true;
-                    doneRef.current?.();
-                }
-                if (loop) {
-                    start = now + 900;
-                    fired = false;
-                } else return;
-            }
-            raf = requestAnimationFrame(tick);
-        };
-        raf = requestAnimationFrame(tick);
-        return () => cancelAnimationFrame(raf);
-    }, [controlled, duration, loop]);
-
+    const complete = value >= 100 && (controlled || page.done);
     useEffect(() => {
-        if (controlled && progress >= 100) doneRef.current?.();
-    }, [controlled, progress]);
-
-    return Math.round(Math.max(0, Math.min(100, controlled ? progress : auto)));
+        if (complete) doneRef.current?.();
+    }, [complete]);
+    return { value, complete };
 }
 
 function Bar({ value, color, track }) {
@@ -108,8 +86,8 @@ function Orbit({ value, color, moving }) {
     );
 }
 
-function ProgressView({ value, color, track, moving }) {
-    const message = messageFor(value);
+function ProgressView({ value, color, track, moving, statusText }) {
+    const message = statusText ?? `${messageFor(value)}…`;
     return (
         <div className="w-[min(22rem,80vw)]">
             <p className="font-mono text-[clamp(3.5rem,12vw,5.5rem)] font-bold leading-none tabular-nums tracking-tight">
@@ -122,7 +100,7 @@ function ProgressView({ value, color, track, moving }) {
             <div className="mt-3 h-5 overflow-hidden text-sm opacity-70">
                 <AnimatePresence mode="wait" initial={false}>
                     <motion.p key={message} initial={{ y: 14, opacity: 0 }} animate={{ y: 0, opacity: 1 }} exit={{ y: -14, opacity: 0 }} transition={{ duration: moving ? 0.25 : 0 }}>
-                        {message}…
+                        {message}
                     </motion.p>
                 </AnimatePresence>
             </div>
@@ -760,30 +738,39 @@ function RacerGame({ value, color, track, dark, statusText }) {
 const LoadingScreen = ({
     variant = "orbit",
     progress,
-    duration = 6000,
-    loop = true,
     accentColor = "#a3e635",
     theme = "dark",
     title = "Loading",
     fullScreen = false,
+    autoHide = true,
     onComplete,
     statusText,
     className = "",
 }) => {
     const moving = !useReducedMotion();
-    const value = useProgress(progress, duration, loop, onComplete);
+    const { value, complete } = useProgress(progress, onComplete);
+    const [gone, setGone] = useState(false);
     const dark = theme !== "light";
     const track = dark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.08)";
-    const shared = { value, color: accentColor, track, moving, dark, statusText };
+    // Page-style status ("Loading page…", "Almost ready…"), or your own text.
+    const status = statusText ?? (complete ? "Page ready" : undefined);
+    const shared = { value, color: accentColor, track, moving, dark, statusText: status };
     const game = variant === "catch" || variant === "runner" || variant === "racer";
+    const hiding = autoHide && complete;
 
+    if (gone) return null;
     return (
-        <div
+        <motion.div
             data-loading-screen=""
             role="status"
             aria-live="polite"
+            aria-busy={!complete}
             aria-label={`${title} ${value}%`}
-            className={`flex flex-col items-center justify-center gap-6 p-6 sm:p-8 ${fullScreen ? "fixed inset-0 z-[100]" : "relative h-full w-full"} ${dark ? "bg-neutral-950 text-white" : "bg-white text-neutral-900"} ${className}`}
+            initial={false}
+            animate={{ opacity: hiding ? 0 : 1 }}
+            transition={{ duration: 0.45, delay: hiding ? 0.35 : 0 }}
+            onAnimationComplete={() => hiding && setGone(true)}
+            className={`flex flex-col items-center justify-center gap-6 p-6 sm:p-8 ${fullScreen ? "fixed inset-0 z-[100]" : "relative h-full w-full"} ${hiding ? "pointer-events-none" : ""} ${dark ? "bg-neutral-950 text-white" : "bg-white text-neutral-900"} ${className}`}
             style={dark ? { backgroundImage: `radial-gradient(60% 50% at 50% 40%, ${accentColor}14, transparent 70%)` } : undefined}
         >
             {game && (
@@ -798,8 +785,13 @@ const LoadingScreen = ({
             {variant === "catch" && <CatchGame {...shared} />}
             {variant === "runner" && <RunnerGame {...shared} />}
             {variant === "racer" && <RacerGame {...shared} />}
-            {!game && variant !== "progress" && <p className="text-[0.7rem] font-semibold uppercase tracking-[0.3em] opacity-50">{title}</p>}
-        </div>
+            {!game && variant !== "progress" && (
+                <p className="text-center">
+                    <span className="block text-[0.7rem] font-semibold uppercase tracking-[0.3em] opacity-50">{title}</span>
+                    <span className="mt-1.5 block text-[0.75rem] opacity-60">{status ?? `${messageFor(value)}…`}</span>
+                </p>
+            )}
+        </motion.div>
     );
 };
 

package/dist/ApexUI-Kit/templates/LoadingScreen/usePageProgress.js

@@ -0,0 +1,135 @@
+import { useEffect, useState } from "react";
+
+/*
+ * Real page-load progress, used by <LoadingScreen /> when you don't pass
+ * your own `progress`. It counts what the page is actually loading:
+ *
+ *  - every <img> still loading (including ones added later),
+ *  - scripts, stylesheets, fonts and fetches as the browser finishes them,
+ *  - web fonts (document.fonts.ready) and the window "load" event.
+ *
+ * `progress` is finished / total (0 to 100) and only reaches 100 once the
+ * page has fully loaded and nothing new has started for a moment, so the
+ * bar and the count always match what really happened.
+ */
+
+const SETTLE_MS = 350;
+
+export function usePageProgress(enabled = true) {
+    const [state, setState] = useState({ loaded: 0, total: 0, done: false });
+
+    useEffect(() => {
+        if (!enabled || typeof window === "undefined") return undefined;
+        let loaded = 0;
+        let total = 0;
+        let waitingForPage = document.readyState !== "complete";
+        let settle = 0;
+        let finished = false;
+        const seen = new WeakSet();
+        const cleanups = [];
+
+        const update = () => {
+            if (finished) return;
+            const idle = !waitingForPage && loaded >= total;
+            setState({ loaded, total, done: false });
+            clearTimeout(settle);
+            if (idle) {
+                // Wait a moment: a page often starts a few more requests right after load.
+                settle = setTimeout(() => {
+                    if (!waitingForPage && loaded >= total) {
+                        finished = true;
+                        setState({ loaded, total: Math.max(total, loaded), done: true });
+                    }
+                }, SETTLE_MS);
+            }
+        };
+        const add = (n = 1) => {
+            total += n;
+            update();
+        };
+        const finish = () => {
+            loaded += 1;
+            update();
+        };
+
+        // Only what is still loading (or starts) after the loader appears is counted,
+        // so the bar runs from 0 to 100 for this load.
+        // Images: pending ones count until they load or fail.
+        const trackImage = (img) => {
+            if (seen.has(img)) return;
+            seen.add(img);
+            if (img.complete) return;
+            add();
+            const end = () => {
+                img.removeEventListener("load", end);
+                img.removeEventListener("error", end);
+                finish();
+            };
+            img.addEventListener("load", end);
+            img.addEventListener("error", end);
+            cleanups.push(() => {
+                img.removeEventListener("load", end);
+                img.removeEventListener("error", end);
+            });
+        };
+        Array.from(document.images).forEach(trackImage);
+        const mo = new MutationObserver((list) => {
+            for (const m of list) {
+                m.addedNodes.forEach((n) => {
+                    if (n.nodeType !== 1) return;
+                    if (n.tagName === "IMG") trackImage(n);
+                    else n.querySelectorAll?.("img").forEach(trackImage);
+                });
+            }
+        });
+        mo.observe(document.documentElement, { childList: true, subtree: true });
+
+        // Other files (scripts, CSS, fonts, fetch) are counted as the browser finishes them.
+        let po;
+        if (typeof PerformanceObserver !== "undefined") {
+            po = new PerformanceObserver((list) => {
+                const fresh = list.getEntries().filter((e) => e.initiatorType !== "img");
+                if (!fresh.length) return;
+                total += fresh.length;
+                loaded += fresh.length;
+                update();
+            });
+            try {
+                po.observe({ type: "resource", buffered: false });
+            } catch {
+                po = undefined;
+            }
+        }
+
+        // The page itself.
+        if (waitingForPage) {
+            total += 1;
+            const onLoad = () => {
+                waitingForPage = false;
+                finish();
+            };
+            window.addEventListener("load", onLoad, { once: true });
+            cleanups.push(() => window.removeEventListener("load", onLoad));
+        }
+        // Web fonts.
+        if (document.fonts && document.fonts.status !== "loaded") {
+            total += 1;
+            document.fonts.ready.then(finish, finish);
+        }
+        update();
+
+        return () => {
+            finished = true;
+            clearTimeout(settle);
+            mo.disconnect();
+            po?.disconnect();
+            cleanups.forEach((fn) => fn());
+        };
+    }, [enabled]);
+
+    const total = Math.max(1, state.total);
+    const progress = state.done ? 100 : Math.min(99, Math.round((state.loaded / total) * 100));
+    return { progress, loaded: state.loaded, total: state.total, done: state.done };
+}
+
+export default usePageProgress;

package/dist/ApexUI-Kit/templates/MagneticButton/MagneticButton.jsx

@@ -0,0 +1,69 @@
+import React, { useRef } from "react";
+import { motion, useMotionValue, useReducedMotion, useSpring, useTransform } from "framer-motion";
+
+/*
+ * Magnetic Button: when the pointer comes near, the button leans toward it
+ * like a magnet, and its label follows a little further for a layered
+ * parallax. A soft glow tracks the pointer across the surface. Springs back
+ * when the pointer leaves. Renders a <button>, or a link with `as="a"`.
+ */
+
+const MagneticButton = ({ as = "button", children = "Get started", strength = 0.35, radius = 1.6, accentColor = "#a3e635", theme = "dark", className = "", ...rest }) => {
+    const reduced = useReducedMotion();
+    const ref = useRef(null);
+    const mx = useMotionValue(0);
+    const my = useMotionValue(0);
+    const gx = useMotionValue(50);
+    const gy = useMotionValue(50);
+    const spring = { stiffness: 220, damping: 18, mass: 0.6 };
+    const x = useSpring(mx, spring);
+    const y = useSpring(my, spring);
+    // The label travels a bit further than the button: layered parallax.
+    const lx = useTransform(x, (v) => v * 0.45);
+    const ly = useTransform(y, (v) => v * 0.45);
+    const glow = useTransform([gx, gy], ([a, b]) => `radial-gradient(120px circle at ${a}% ${b}%, ${accentColor}55, transparent 70%)`);
+    const Tag = motion[as] ?? motion.button;
+    const dark = theme !== "light";
+
+    const onMove = (e) => {
+        const el = ref.current;
+        if (!el || reduced) return;
+        const r = el.getBoundingClientRect();
+        const cx = r.left + r.width / 2;
+        const cy = r.top + r.height / 2;
+        const dx = e.clientX - cx;
+        const dy = e.clientY - cy;
+        // Only pull while the pointer is within `radius` × the button size.
+        const reach = Math.max(r.width, r.height) * radius;
+        const pull = Math.max(0, 1 - Math.hypot(dx, dy) / reach);
+        mx.set(dx * strength * pull * 1.6);
+        my.set(dy * strength * pull * 1.6);
+        gx.set(((e.clientX - r.left) / r.width) * 100);
+        gy.set(((e.clientY - r.top) / r.height) * 100);
+    };
+    const reset = () => {
+        mx.set(0);
+        my.set(0);
+    };
+
+    return (
+        // The wrapper is larger than the button so the pull starts before you touch it.
+        <span className="inline-block p-6" onPointerMove={onMove} onPointerLeave={reset}>
+            <Tag
+                ref={ref}
+                {...(as === "button" ? { type: "button" } : {})}
+                {...rest}
+                style={{ x, y }}
+                whileTap={{ scale: 0.96 }}
+                className={`group relative inline-flex select-none items-center justify-center overflow-hidden rounded-full px-8 py-4 text-[0.95rem] font-semibold outline-none ring-1 transition-shadow focus-visible:ring-2 ${dark ? "bg-neutral-950 text-white ring-white/15 focus-visible:ring-white/40" : "bg-white text-neutral-900 ring-black/10 focus-visible:ring-black/30"} ${className}`}
+            >
+                <motion.span aria-hidden="true" className="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-300 group-hover:opacity-100" style={{ background: glow }} />
+                <motion.span className="relative inline-flex items-center gap-2" style={{ x: lx, y: ly }}>
+                    {children}
+                </motion.span>
+            </Tag>
+        </span>
+    );
+};
+
+export default MagneticButton;