ab-nextjs-components 0.1.8 → 0.1.10

package/ab-searchbar/styles.module.css

@@ -1,3 +1,42 @@
+/* 
+* @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: ab-searchbar - styles
+* @file: ab-searchbar/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 .abSearchbar {
   position: relative;
   display: flex;
@@ -10,7 +49,7 @@
   border-radius: 9999px;
   overflow: hidden;
   background: color-mix(in srgb, var(--ab-surface-container-high, #e6e0e9) 90%, transparent);
-  transition: background 0.3s ease;
+  --ab-motion-duration: 300ms; /* 🎨 focus fade = .ab-motion-colors (ab-nextjs-animations) */
 }
 .abSearchbar:focus-within {
   background: var(--ab-surface-container-high, #e6e0e9);
@@ -65,10 +104,7 @@
   border: 2px solid color-mix(in srgb, currentColor 25%, transparent);
   border-top-color: currentColor;
   border-radius: 50%;
-  animation: abSearchbarSpin 0.7s linear infinite;
-}
-@keyframes abSearchbarSpin {
-  to { transform: rotate(360deg); }
+  /* 🌀 rotation = .ab-spin (ab-nextjs-animations) */
 }
 .isDisabled {
   opacity: 0.55;

package/ab-splash/csp.d.ts

@@ -0,0 +1,54 @@
+/* 
+* @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 (types for csp.mjs)
+* @file: ab-splash/csp.d.ts
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚙️ gate options (mirror of `AbSplashGateOptions` in ./gate.ts)
+export interface AbSplashGateOptions {
+  // 🌍 every configured locale
+  locales?: readonly string[]
+  // 🏠 the default (unprefixed) locale
+  defaultLocale?: string
+  // 🚪 extra root sub-paths (default ['welcome'])
+  rootSubPaths?: readonly string[]
+}
+
+// 🔐 `'sha256-<base64>'` CSP source for an inline script
+export declare function getAbSplashGateSha256(script: string): string
+// 🔐 the gate script + its hash, from the same options
+export declare function buildAbSplashGate(options?: AbSplashGateOptions): { script: string; sha256: string }
+// 🔐 hash of the default `abSplashGateScript`
+export declare const AB_SPLASH_GATE_SHA256: string

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,140 @@
+/* 
+* @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';
+import { AB_MOTION } from 'ab-nextjs-animations/motion'; // 🎬 fade-out transition (ab-nextjs-animations >= 0.2.4)
+import 'ab-nextjs-animations/motion/styles.css'; // 🌫️ .ab-motion-colors (covers opacity)
+
+// 📦 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, AB_MOTION.colors, 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 };