ab-nextjs-components 0.1.7 → 0.1.9

package/ab-splash/csp.mjs

@@ -0,0 +1,82 @@
+/*
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+* (MIT license text: see LICENSE)
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - CSP hash helpers (COMPILED, do not edit — run `node scripts/build-csp.mjs`)
+* @file: ab-splash/csp.mjs
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+// 🤖 generated from ab-splash/csp.ts + ab-splash/gate.ts (bundled, ESM, Node)
+
+// ab-splash/csp.ts
+import { createHash } from "node:crypto";
+
+// ab-splash/gate.ts
+var AB_SPLASH_ATTRIBUTE = "data-ab-splash";
+var AB_SPLASH_VISITED_KEY = "ab-splash-visited";
+var AB_SPLASH_SESSION_KEY = "ab-splash-session";
+var AB_SPLASH_BOT_PATTERN = "bot|crawl|spider|slurp|bingpreview|facebookexternalhit|embedly|quora link preview|whatsapp|telegrambot|discordbot|headlesschrome|lighthouse|pagespeed|prerender";
+var escapeRe = (value) => value.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+function buildAbSplashRootPathPattern(options = {}) {
+  const prefixed = (options.locales ?? []).filter((locale) => locale && locale !== options.defaultLocale).map(escapeRe);
+  const subPaths = (options.rootSubPaths ?? ["welcome"]).filter(Boolean).map(escapeRe);
+  const localePart = prefixed.length ? `(?:\\/(?:${prefixed.join("|")}))?` : "";
+  const subPart = subPaths.length ? `(?:\\/(?:${subPaths.join("|")}))?` : "";
+  return `^${localePart}${subPart}\\/?$`;
+}
+function buildAbSplashGateScript(options = {}) {
+  const pattern = JSON.stringify(buildAbSplashRootPathPattern(options));
+  const bots = JSON.stringify(AB_SPLASH_BOT_PATTERN);
+  return `(function () {
+  // \u{1F9ED} shortcuts
+  var w = window, d = document, nav = w.navigator || {};
+  // \u{1F916} skip automation and bots (no Splash for crawlers, previews or headless tests)
+  if (nav.webdriver || new RegExp(${bots}, 'i').test(nav.userAgent || '')) return;
+  // \u{1F4D6} safe storage read: a failing get counts as "already seen" ('1')
+  function get(store, key) { try { return w[store].getItem(key); } catch (e) { return '1'; } }
+  // \u270D\uFE0F safe storage write: a failing set is ignored
+  function set(store, key) { try { w[store].setItem(key, '1'); } catch (e) {} }
+  // \u{1F4F1} installed PWA? (matchMedia OR iOS navigator.standalone)
+  var mm = false;
+  try { mm = !!(w.matchMedia && w.matchMedia('(display-mode: standalone)').matches); } catch (e) {}
+  var isStandalone = mm || nav.standalone === true;
+  // \u{1F3E0} a root page? (/, /<locale>, /welcome, /<locale>/welcome \u2014 never the default locale prefix)
+  var isRootPage = false;
+  try { isRootPage = new RegExp(${pattern}).test(w.location.pathname); } catch (e) {}
+  // \u{1F6A6} decision
+  var show = false;
+  // \u{1F4F1} standalone: once per session
+  if (isStandalone) {
+    if (!get('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)})) show = true;
+    set('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)});
+  }
+  // \u{1F463} first ever visit, on a root page only
+  if (!get('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)})) {
+    if (isRootPage) show = true;
+    set('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)});
+  }
+  // \u{1F6A9} last step: turn the Splash on
+  if (show) { try { d.documentElement.setAttribute(${JSON.stringify(AB_SPLASH_ATTRIBUTE)}, 'on'); } catch (e) {} }
+})();`;
+}
+var abSplashGateScript = buildAbSplashGateScript();
+
+// ab-splash/csp.ts
+function getAbSplashGateSha256(script) {
+  return `'sha256-${createHash("sha256").update(script, "utf8").digest("base64")}'`;
+}
+function buildAbSplashGate(options = {}) {
+  const script = buildAbSplashGateScript(options);
+  return { script, sha256: getAbSplashGateSha256(script) };
+}
+var AB_SPLASH_GATE_SHA256 = getAbSplashGateSha256(abSplashGateScript);
+export {
+  AB_SPLASH_GATE_SHA256,
+  buildAbSplashGate,
+  getAbSplashGateSha256
+};

package/ab-splash/csp.ts

@@ -0,0 +1,60 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* 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.
+
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - CSP hash helpers
+* @file: ab-splash/csp.ts
+* @type: TypeScript (Node only: use it in next.config / proxy, never in the browser)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🔐 Node's crypto (sync sha256 for build-time CSP)
+import { createHash } from 'node:crypto';
+// 🚦 the gate script builders
+import { abSplashGateScript, buildAbSplashGateScript, type AbSplashGateOptions } from './gate';
+
+// 🔐 CSP source for an inline script: `'sha256-<base64>'`
+export function getAbSplashGateSha256(script: string): string {
+  // 🧮 hash the exact bytes that go into the <script> tag
+  return `'sha256-${createHash('sha256').update(script, 'utf8').digest('base64')}'`;
+}
+
+// 🔐 build the script AND its CSP hash in one go (keep both from the same options!)
+export function buildAbSplashGate(options: AbSplashGateOptions = {}): { script: string; sha256: string } {
+  // 🚦 the script
+  const script = buildAbSplashGateScript(options);
+  // 📦 script + hash
+  return { script, sha256: getAbSplashGateSha256(script) };
+}
+
+// 🔐 hash of the default `abSplashGateScript` (static CSP)
+export const AB_SPLASH_GATE_SHA256: string = getAbSplashGateSha256(abSplashGateScript);

package/ab-splash/gate.ts

@@ -0,0 +1,216 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* 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.
+
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - Gate script & timing helpers
+* @file: ab-splash/gate.ts
+* @type: TypeScript (isomorphic, no Node or DOM imports)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🚩 the `<html>` data attribute that turns the Splash on (set by the gate script, before the first paint ⚡️)
+export const AB_SPLASH_ATTRIBUTE = 'data-ab-splash';
+// 👣 the localStorage key that remembers the first ever visit
+export const AB_SPLASH_VISITED_KEY = 'ab-splash-visited';
+// 📱 the sessionStorage key that remembers the Splash was shown in this (standalone) session
+export const AB_SPLASH_SESSION_KEY = 'ab-splash-session';
+// ⏱️ the Splash never stays longer than this (in ms)
+export const AB_SPLASH_MAX_MS = 1200;
+// 🌫️ the fade-out duration (in ms), when motion is allowed
+export const AB_SPLASH_FADE_MS = 200;
+// 🤖 user agents that never get a Splash (crawlers, previews, headless tools)
+export const AB_SPLASH_BOT_PATTERN = 'bot|crawl|spider|slurp|bingpreview|facebookexternalhit|embedly|quora link preview|whatsapp|telegrambot|discordbot|headlesschrome|lighthouse|pagespeed|prerender';
+
+// ⚙️ gate options
+export interface AbSplashGateOptions {
+  // 🌍 every configured locale (e.g. ['en', 'fr', 'es', 'ru'])
+  locales?: readonly string[];
+  // 🏠 the default locale (served without a prefix, so `/en` is NOT a root page)
+  defaultLocale?: string;
+  // 🚪 extra "root" sub-paths that also show the Splash on first visit (default: ['welcome'])
+  rootSubPaths?: readonly string[];
+}
+
+// 🛡️ escape a string for use inside a RegExp
+const escapeRe = (value: string): string => value.replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&');
+
+/**
+ * 🧭 Build the root-path RegExp source from the configured locales minus the default.
+ * e.g. locales en/fr/es/ru + default en → `^(?:\/(?:fr|es|ru))?(?:\/(?:welcome))?\/?$`
+ */
+export function buildAbSplashRootPathPattern(options: AbSplashGateOptions = {}): string {
+  // 🌍 prefixed locales only (the default one has no prefix)
+  const prefixed = (options.locales ?? []).filter((locale) => locale && locale !== options.defaultLocale).map(escapeRe);
+  // 🚪 sub-paths (welcome by default)
+  const subPaths = (options.rootSubPaths ?? ['welcome']).filter(Boolean).map(escapeRe);
+  // 🧱 optional locale prefix
+  const localePart = prefixed.length ? `(?:\\/(?:${prefixed.join('|')}))?` : '';
+  // 🧱 optional sub-path
+  const subPart = subPaths.length ? `(?:\\/(?:${subPaths.join('|')}))?` : '';
+  // 🏁 anchored pattern (optional trailing slash)
+  return `^${localePart}${subPart}\\/?$`;
+}
+
+/*
+ * 💡 Why the gate does its own storage + the CSS does its own fade/failsafe:
+ *    this script runs inline in <head>, BEFORE React hydrates. Hooks (useAbLocalStorage)
+ *    and ab-nextjs-animations can't run there yet, and waiting for them would flash the page.
+ *    So it stays tiny, dependency-free ES5 with its own try-wrapped storage access.
+ */
+
+/**
+ * 🚦 Build the inline gate script (runs in <head>, before the first paint).
+ * Inject with `<script dangerouslySetInnerHTML={{ __html: script }} />` and allow its hash in the CSP
+ * (see `getAbSplashGateSha256` in `ab-nextjs-components/ab-splash/csp`).
+ */
+export function buildAbSplashGateScript(options: AbSplashGateOptions = {}): string {
+  // 🧭 root-path pattern, injected as a JSON string literal (never raw-concatenated)
+  const pattern = JSON.stringify(buildAbSplashRootPathPattern(options));
+  // 🤖 bot pattern, also JSON-injected
+  const bots = JSON.stringify(AB_SPLASH_BOT_PATTERN);
+  // 🧾 the script (plain ES5, comments allowed: newlines are kept)
+  return `(function () {
+  // 🧭 shortcuts
+  var w = window, d = document, nav = w.navigator || {};
+  // 🤖 skip automation and bots (no Splash for crawlers, previews or headless tests)
+  if (nav.webdriver || new RegExp(${bots}, 'i').test(nav.userAgent || '')) return;
+  // 📖 safe storage read: a failing get counts as "already seen" ('1')
+  function get(store, key) { try { return w[store].getItem(key); } catch (e) { return '1'; } }
+  // ✍️ safe storage write: a failing set is ignored
+  function set(store, key) { try { w[store].setItem(key, '1'); } catch (e) {} }
+  // 📱 installed PWA? (matchMedia OR iOS navigator.standalone)
+  var mm = false;
+  try { mm = !!(w.matchMedia && w.matchMedia('(display-mode: standalone)').matches); } catch (e) {}
+  var isStandalone = mm || nav.standalone === true;
+  // 🏠 a root page? (/, /<locale>, /welcome, /<locale>/welcome — never the default locale prefix)
+  var isRootPage = false;
+  try { isRootPage = new RegExp(${pattern}).test(w.location.pathname); } catch (e) {}
+  // 🚦 decision
+  var show = false;
+  // 📱 standalone: once per session
+  if (isStandalone) {
+    if (!get('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)})) show = true;
+    set('sessionStorage', ${JSON.stringify(AB_SPLASH_SESSION_KEY)});
+  }
+  // 👣 first ever visit, on a root page only
+  if (!get('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)})) {
+    if (isRootPage) show = true;
+    set('localStorage', ${JSON.stringify(AB_SPLASH_VISITED_KEY)});
+  }
+  // 🚩 last step: turn the Splash on
+  if (show) { try { d.documentElement.setAttribute(${JSON.stringify(AB_SPLASH_ATTRIBUTE)}, 'on'); } catch (e) {} }
+})();`;
+}
+
+// 🚦 the default gate script (no locale prefixes; build your own with `buildAbSplashGateScript`)
+export const abSplashGateScript: string = buildAbSplashGateScript();
+
+// ⏳ time left before the cap (never below 0, never above the max)
+export function getAbSplashRemainingMs(elapsedMs: number, maxMs: number = AB_SPLASH_MAX_MS): number {
+  return Math.min(maxMs, Math.max(0, maxMs - elapsedMs));
+}
+
+// 🌫️ fade duration (0 with reduced motion ♿)
+export function getAbSplashFadeMs(prefersReducedMotion: boolean): number {
+  return prefersReducedMotion ? 0 : AB_SPLASH_FADE_MS;
+}
+
+// 🏁 resolve when fonts are ready or the timeout hits, whichever comes first
+export function waitForAbSplashReady(fontsReady: Promise<unknown> | undefined, timeoutMs: number): Promise<'fonts' | 'timeout'> {
+  // ⏱️ the timeout racer
+  const timeout = new Promise<'timeout'>((resolve) => setTimeout(() => resolve('timeout'), timeoutMs));
+  // 🤷 no Font Loading API → timeout only
+  if (!fontsReady) return timeout;
+  // 🔤 a failing font load counts as ready too
+  const fonts = fontsReady.then(() => 'fonts' as const, () => 'fonts' as const);
+  // 🏁 first one wins
+  return Promise.race([fonts, timeout]);
+}
+
+// 🙈 minimal element shape used by the inert helper (keeps it testable without a DOM)
+export interface AbInertNode {
+  parentElement: AbInertNode | null;
+  children: ArrayLike<AbInertNode>;
+  inert?: boolean;
+  tagName?: string;
+}
+
+/**
+ * 🙈 Make everything behind `overlay` inert (siblings on the path up to <body>).
+ * Returns a restore function that only un-inerts what it changed.
+ */
+export function setAbSplashBackgroundInert(overlay: AbInertNode): () => void {
+  // 📝 nodes we changed
+  const changed: AbInertNode[] = [];
+  // ⬆️ walk up from the overlay to <body>
+  let node: AbInertNode | null = overlay;
+  while (node && node.parentElement) {
+    // 👪 the parent
+    const parent: AbInertNode = node.parentElement;
+    // 🔁 every sibling of the current node
+    for (const sibling of Array.from(parent.children)) {
+      // ✅ skip the overlay's own branch, scripts/styles and already-inert nodes
+      if (sibling === node || sibling.inert || /^(SCRIPT|STYLE|LINK|TEMPLATE)$/.test(sibling.tagName ?? '')) continue;
+      // 🙈 make it inert
+      sibling.inert = true;
+      // 📝 remember it
+      changed.push(sibling);
+    }
+    // 🛑 stop at <body>
+    if ((parent.tagName ?? '').toUpperCase() === 'BODY') break;
+    // ⬆️ go up
+    node = parent;
+  }
+  // ↩️ restore
+  return () => { for (const el of changed) el.inert = false; };
+}
+
+// ⏲️ pending teardown (module-level: survives React StrictMode's dev unmount → remount)
+let abSplashPendingFinish: ReturnType<typeof setTimeout> | undefined
+
+/**
+ * 🔁 Schedule the final teardown (flag off + inert restored) on the next task instead of running it
+ * synchronously in an effect cleanup. StrictMode (dev) unmounts and immediately remounts: the remount
+ * cancels this with `cancelAbSplashFinish()`, so the Splash isn't killed by its own cleanup.
+ */
+export function scheduleAbSplashFinish(finish: () => void, delayMs: number = 0): void {
+  cancelAbSplashFinish() // 🧹 only one pending teardown
+  abSplashPendingFinish = setTimeout(() => { abSplashPendingFinish = undefined; finish() }, delayMs) // ⏲️
+}
+
+/** 🛑 Cancel a pending teardown; returns true when one was pending (i.e. this is a remount). */
+export function cancelAbSplashFinish(): boolean {
+  if (abSplashPendingFinish === undefined) return false // 😴 nothing pending
+  clearTimeout(abSplashPendingFinish) // 🛑 cancel
+  abSplashPendingFinish = undefined // 🧹 reset
+  return true // 🔁 remount
+}

package/ab-splash/index.tsx

@@ -0,0 +1,138 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* 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.
+
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - Client
+* @file: ab-splash/index.tsx
+* @type: Client Component
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client'; // 💧 hides itself after hydration
+
+// ⚛️ React hooks
+import { useEffect, useRef, useState, type ReactElement } from 'react';
+// 🧵 class-name joiner
+import clsx from 'clsx';
+// 🅰️ the Ab mark + "Elements" wordmark (this package)
+import AbLogo from '../ab-logo';
+// 📶 the linear progress (this package)
+import AbLinearProgress from '../ab-linear-progress';
+// 🚦 gate constants & helpers
+import {
+  AB_SPLASH_ATTRIBUTE,
+  getAbSplashFadeMs,
+  getAbSplashRemainingMs,
+  setAbSplashBackgroundInert,
+  scheduleAbSplashFinish,
+  cancelAbSplashFinish,
+  waitForAbSplashReady,
+  type AbInertNode,
+} from './gate';
+// 🎨 package-shipped styles
+import styles from './styles.module.css';
+
+// 📦 re-export the gate so `import { abSplashGateScript } from 'ab-nextjs-components/ab-splash'` works
+export * from './gate';
+
+// 📐 props
+export interface AbSplashProps {
+  // 🏷️ consumer classes
+  className?: string;
+  // 🔤 wordmark text (default "Elements")
+  wordmark?: string;
+  // ⏱️ hard cap in ms (default 1200)
+  maxMs?: number;
+}
+
+/** 💦 AbSplash — brand overlay shown only when the gate script set `html[data-ab-splash]`. */
+export default function AbSplash({ className, wordmark = 'Elements', maxMs }: AbSplashProps): ReactElement {
+  // 📶 progress (25% until hydration)
+  const [progress, setProgress] = useState<number>(25);
+  // 📌 the overlay element
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // 🔁 StrictMode remount? cancel the teardown the previous cleanup scheduled (keeps the flag on)
+    cancelAbSplashFinish();
+    // 🌳 the <html> element
+    const root = document.documentElement;
+    // 😴 gate said no → nothing to do
+    if (root.getAttribute(AB_SPLASH_ATTRIBUTE) !== 'on') return;
+    // 🛟 unmount guard
+    let alive = true;
+    // ⏲️ fade timer
+    let fadeTimer: ReturnType<typeof setTimeout> | undefined;
+    // 🙈 make the page behind inert while we show
+    const restoreInert = ref.current ? setAbSplashBackgroundInert(ref.current as unknown as AbInertNode) : () => {};
+    // 👋 final cleanup: flag off + page interactive again
+    const finish = () => { root.removeAttribute(AB_SPLASH_ATTRIBUTE); restoreInert(); };
+    // ➡️ hydrated: move the progress on (next frame)
+    const frame = requestAnimationFrame(() => setProgress(60));
+    // ♿ reduced motion?
+    const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    // ⏳ time left before the cap
+    const remaining = getAbSplashRemainingMs(performance.now(), maxMs);
+    // 🔤 wait for fonts (or the cap), then hide
+    waitForAbSplashReady(document.fonts?.ready, remaining).then(() => {
+      // 🛟 unmounted meanwhile
+      if (!alive) return;
+      // ✅ fill the bar
+      setProgress(100);
+      // 🌫️ start the CSS fade
+      root.setAttribute(AB_SPLASH_ATTRIBUTE, 'leaving');
+      // 👋 remove for good (at once with reduced motion)
+      fadeTimer = setTimeout(finish, getAbSplashFadeMs(reduced));
+    });
+    // 🧹 cleanup
+    return () => {
+      alive = false; // 🛟 dead
+      cancelAnimationFrame(frame); // 🚫 frame
+      if (fadeTimer) clearTimeout(fadeTimer); // 🚫 timer
+      restoreInert(); // 🙉 page interactive again right away (a remount re-applies inert)
+      scheduleAbSplashFinish(finish); // 👋 remove data-ab-splash on the next task unless we remount (StrictMode)
+    };
+  }, [maxMs]);
+
+  return (
+    // 💦 the overlay (decorative → hidden from assistive tech)
+    <div ref={ref} className={clsx('AbSplash', styles.abSplash, className)} aria-hidden="true">
+      {/* 🅰️ mark + wordmark */}
+      <AbLogo wordmark={wordmark} alt="" className={styles.abSplash__brand} />
+      {/* 📶 progress */}
+      <AbLinearProgress className={styles.abSplash__progress} progress={progress} label="" />
+    </div>
+  );
+}
+
+// 📦 named export too
+export { AbSplash };

package/ab-splash/styles.module.css

@@ -0,0 +1,106 @@
+/* 
+* @license MIT
+* ~~~~~~~~~~~~
+* ab-nextjs-components
+* ~~~~~~~~~~~~ 
+* Copyright (c) 2026 Abraham Ukachi. The abElements Project.
+*
+* 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.
+
+*
+* @project: ab-nextjs-components
+* @name: AbSplash - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: ab-splash/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 💦 overlay: hidden by default (JS off = no Splash 🙈) */
+.abSplash {
+  display: none; /* 🙈 off unless the gate turned it on */
+  position: fixed; /* 📌 cover the viewport */
+  inset: 0; /* 📐 edge to edge */
+  z-index: 1000; /* 🔝 above everything */
+  flex-direction: column; /* ⬇️ brand above progress */
+  align-items: center; /* ↔️ centered */
+  justify-content: center; /* ↕️ centered */
+  gap: 2.25rem; /* ↕️ brand ↔ bar */
+  background-color: #FFF8F3; /* ☀️ light surface (matches the splash mocks) */
+  color: #A67C52; /* 🎨 bronze brand */
+  transition: opacity 200ms ease; /* 🌫️ fade-out */
+  animation: abSplashFailsafe 0s linear 1.2s forwards; /* ⏱️ never longer than 1.2 s, even without hydration */
+}
+
+/* 🌙 dark */
+:global(html.dark) .abSplash {
+  background-color: #1A1310; /* 🌙 dark surface (matches the splash mocks) */
+  color: #FFF8F5; /* 🤍 light brand */
+}
+
+/* 🚦 gate said "on" (or leaving) */
+:global(html[data-ab-splash]) .abSplash {
+  display: flex;
+}
+
+/* 🔒 no scrolling behind the overlay — with the same 1.2 s failsafe as the overlay itself */
+:global(html[data-ab-splash='on']) {
+  overflow: hidden; /* 🔒 lock */
+  animation: abSplashUnlock 0s linear 1.2s forwards; /* ⏱️ unlock even if hydration never happens */
+}
+
+/* ⏱️ failsafe unlock keyframes (overflow animates discretely) */
+@keyframes abSplashUnlock {
+  to { overflow: visible; }
+}
+
+/* 👋 leaving: fade out */
+:global(html[data-ab-splash='leaving']) .abSplash {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* 🅰️ brand lockup size */
+.abSplash__brand {
+  font-size: clamp(2.5rem, 6vw, 3.25rem); /* 📏 as in the mock */
+  color: inherit; /* 🎨 follow light/dark */
+  --ab-logo-color: currentColor; /* 🎨 mark + wordmark follow the overlay color */
+}
+
+/* 📶 progress track */
+.abSplash__progress {
+  width: min(18rem, 28vw); /* ↔️ mobile + laptop, as in the mock */
+  --ab-linear-progress-height: 0.375rem; /* ↕️ 6 px */
+  --ab-linear-progress-color: #A67C52; /* 🎨 bronze bar in both themes */
+}
+
+/* ♿ reduced motion: no fade */
+@media (prefers-reduced-motion: reduce) {
+  .abSplash { transition: none; }
+}
+
+/* ⏱️ failsafe keyframes */
+@keyframes abSplashFailsafe {
+  to { visibility: hidden; pointer-events: none; }
+}

package/assets/logos/ab-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 24 24"><path fill="#A67C52" d="m1.8 20.5 9.3-17v17zM22.2 7.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z"/><path d="m12.9 20.5 9.3-4.2-9.3-8.6z" opacity=".1"/></svg>

package/assets/spinners/12-dots-scale-rotate.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><style>@keyframes spinner_grm3{0%,50%{animation-timing-function:cubic-bezier(.27,.42,.37,.99);r:1px}25%{animation-timing-function:cubic-bezier(.53,0,.61,.73);r:2px}}@keyframes spinner_T3O6{0%{transform:rotate(360deg)}}.spinner_EUy1{animation:spinner_grm3 1.2s infinite}.spinner_f6oS{animation-delay:.1s}.spinner_g3nX{animation-delay:.2s}.spinner_nvEs{animation-delay:.3s}.spinner_MaNM{animation-delay:.4s}.spinner_4nle{animation-delay:.5s}.spinner_ZETM{animation-delay:.6s}.spinner_HXuO{animation-delay:.7s}.spinner_YaQo{animation-delay:.8s}.spinner_GOx1{animation-delay:.9s}.spinner_4vv9{animation-delay:1s}.spinner_NTs9{animation-delay:1.1s}.spinner_auJJ{transform-origin:center;animation:spinner_T3O6 6s linear infinite}</style><g class="spinner_auJJ"><circle cx="12" cy="3" r="1" class="spinner_EUy1"/><circle cx="16.5" cy="4.21" r="1" class="spinner_EUy1 spinner_f6oS"/><circle cx="7.5" cy="4.21" r="1" class="spinner_EUy1 spinner_NTs9"/><circle cx="19.79" cy="7.5" r="1" class="spinner_EUy1 spinner_g3nX"/><circle cx="4.21" cy="7.5" r="1" class="spinner_EUy1 spinner_4vv9"/><circle cx="21" cy="12" r="1" class="spinner_EUy1 spinner_nvEs"/><circle cx="3" cy="12" r="1" class="spinner_EUy1 spinner_GOx1"/><circle cx="19.79" cy="16.5" r="1" class="spinner_EUy1 spinner_MaNM"/><circle cx="4.21" cy="16.5" r="1" class="spinner_EUy1 spinner_YaQo"/><circle cx="16.5" cy="19.79" r="1" class="spinner_EUy1 spinner_4nle"/><circle cx="7.5" cy="19.79" r="1" class="spinner_EUy1 spinner_HXuO"/><circle cx="12" cy="21" r="1" class="spinner_EUy1 spinner_ZETM"/></g></svg>

package/assets/spinners/3-dots-scale.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><style>@keyframes spinner_xe7Q{93.75%{r:3px}46.875%{r:.2px}}.spinner_b2T7{animation:spinner_xe7Q .8s linear infinite}.spinner_YRVV{animation-delay:-.65s}.spinner_c9oY{animation-delay:-.5s}</style><circle cx="4" cy="12" r="3" class="spinner_b2T7"/><circle cx="12" cy="12" r="3" class="spinner_b2T7 spinner_YRVV"/><circle cx="20" cy="12" r="3" class="spinner_b2T7 spinner_c9oY"/></svg>

package/assets/spinners/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) Utkarsh Verma
+
+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.