ab-nextjs-components 0.1.9 → 0.1.11

package/ab-install-snippet/styles.module.css

@@ -0,0 +1,104 @@
+/* 
+* @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: AbInstallSnippet - Styles
+* @file: ab-install-snippet/styles.module.css
+* @type: CSS module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 📦 box */
+.root {
+  display: grid; /* 📐 */
+  gap: 0.5rem; /* 🧱 */
+  padding: 0.75rem; /* 🧱 */
+  border-radius: 0.875rem; /* 🔲 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface-container, transparent); /* 🎨 */
+  max-width: 100%; /* 📏 */
+}
+
+/* 🗂️ tabs row */
+.tabs {
+  display: flex; /* 📐 */
+  gap: 0.25rem; /* 🧱 */
+}
+
+/* 🔘 tab */
+.tab {
+  min-height: 28px; /* 📏 ≥ 24px target */
+  padding: 0.25rem 0.625rem; /* 🧱 */
+  border: 0; /* 🧹 */
+  border-radius: 9999px; /* 💊 */
+  background: transparent; /* 🫥 */
+  color: var(--ab-color-on-surface-variant, currentColor); /* 🎨 */
+  font: inherit; /* 🔤 */
+  font-size: 0.8125rem; /* 🔡 */
+  cursor: pointer; /* 👆 */
+}
+.tab[aria-selected='true'] {
+  color: var(--ab-color-bronze-text, #8A6440); /* ♿ AA small text */
+  background: color-mix(in srgb, var(--ab-color-bronze, #A67C52) 12%, transparent); /* 🎨 */
+  font-weight: 600; /* 💪 */
+}
+.tab:focus-visible {
+  outline: 2px solid var(--ab-focus-ring, var(--ab-color-primary, #A67C52)); /* 💍 */
+  outline-offset: 2px; /* ↔️ */
+}
+
+/* 🧾 command row */
+.panel {
+  display: flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  gap: 0.5rem; /* 🧱 */
+  min-width: 0; /* 🚫 overflow */
+}
+.prompt {
+  opacity: 0.5; /* 🌫️ */
+  font-family: var(--ab-font-mono, ui-monospace, monospace); /* 🔤 */
+}
+.code {
+  flex: 1; /* ↔️ */
+  overflow-x: auto; /* 📜 long commands scroll */
+  white-space: nowrap; /* 🚫 wrap */
+  font-family: var(--ab-font-mono, ui-monospace, monospace); /* 🔤 */
+  font-size: 0.875rem; /* 🔡 */
+}
+.copy {
+  flex: none; /* 🚫 squash */
+}
+
+/* 🙈 visually hidden */
+.srOnly {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; /* 📏 */
+  overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; /* ✂️ */
+}

package/ab-like-button/index.tsx

@@ -5,17 +5,48 @@
 * ~~~~~~~~~~~~ 
 * 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: AbLikeButton - Client (port of lyd-like-button)
 * @file: ab-like-button/index.tsx
+* @type: TypeScript (React)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 'use client';
 
 import type { CSSProperties, MouseEvent, ReactElement } from 'react';
 import Link from 'next/link';
 import clsx from 'clsx';
 import styles from './styles.module.css';
+import { AB_MOTION } from 'ab-nextjs-animations/motion'; // 🎬 transition class names (ab-nextjs-animations >= 0.2.4)
+import 'ab-nextjs-animations/motion/styles.css'; // 🎨 .ab-motion-*
+import { AB_SPIN_CLASS } from 'ab-nextjs-animations/spin'; // 🌀 spinner (ab-nextjs-animations >= 0.2.4)
+import 'ab-nextjs-animations/spin/styles.css'; // 🌀 .ab-spin
 
 export interface AbLikeButtonProps {
   className?: string;
@@ -58,6 +89,7 @@ const AbLikeButton = ({
   const classNames = clsx(
     'AbLikeButton',
     styles.abLikeButton,
+    AB_MOTION.interactive, // 🎬 hover / state motion (ab-nextjs-animations)
     liked && styles.isLiked,
     isActive && styles.isActive,
     isNaked && styles.isNaked,
@@ -69,7 +101,7 @@ const AbLikeButton = ({
   );
 
   const inner = isLoading ? (
-    <span className={styles.abLikeButtonSpinner} aria-hidden />
+    <span className={clsx(styles.abLikeButtonSpinner, AB_SPIN_CLASS)} aria-hidden />
   ) : (
     <span className={clsx('material-symbols-rounded', styles.abLikeButtonIcon)} aria-hidden>
       {icon}

package/ab-like-button/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-like-button - styles
+* @file: ab-like-button/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 .abLikeButton {
   position: relative;
   display: inline-flex;
@@ -13,7 +52,7 @@
   color: inherit;
   text-decoration: none;
   cursor: pointer;
-  transition: transform 0.2s ease, background 0.2s ease;
+  /* 🎬 motion = .ab-motion-interactive (ab-nextjs-animations) */
 }
 
 .abLikeButton:hover:not(.isDisabled):not(.isNaked) {
@@ -52,9 +91,5 @@
   border: 2px solid color-mix(in srgb, currentColor 25%, transparent);
   border-top-color: currentColor;
   border-radius: 9999px;
-  animation: abLikeSpin 0.7s linear infinite;
-}
-
-@keyframes abLikeSpin {
-  to { transform: rotate(360deg); }
+  /* 🌀 rotation = .ab-spin (ab-nextjs-animations) */
 }

package/ab-linear-progress/index.tsx

@@ -42,6 +42,10 @@ import type { CSSProperties, ReactElement } from 'react';
 import clsx from 'clsx';
 // 🎨 package-shipped CSS module (no Tailwind scanning of node_modules needed)
 import styles from './styles.module.css';
+import { AB_MOTION } from 'ab-nextjs-animations/motion'; // 🎬 transition class names (ab-nextjs-animations >= 0.2.4)
+import 'ab-nextjs-animations/motion/styles.css'; // 🎨 .ab-motion-*
+import { AB_PROGRESS_SWEEP_CLASS } from 'ab-nextjs-animations/progress-sweep'; // 🔁 indeterminate sweep (ab-nextjs-animations >= 0.2.4)
+import 'ab-nextjs-animations/progress-sweep/styles.css'; // 🔁 .ab-progress-sweep
 
 // 📐 public props of <AbLinearProgress />
 export interface AbLinearProgressProps {
@@ -113,7 +117,7 @@ const AbLinearProgress = ({
       {/* 🟫 the moving / filling bar */}
       <div
         // 🏷️ bar class (indeterminate gets the sweep class)
-        className={clsx(styles.abLinearProgress__bar, isIndeterminate && styles.abLinearProgress__bar_indeterminate)}
+        className={clsx(styles.abLinearProgress__bar, isIndeterminate ? [styles.abLinearProgress__bar_indeterminate, AB_PROGRESS_SWEEP_CLASS] : AB_MOTION.transform)} // 🎬 sweep / value tween from ab-nextjs-animations
         // 📐 determinate width via transform (GPU friendly) — none in indeterminate
         style={isIndeterminate ? undefined : { transform: `scaleX(${value / 100})` }}
       />

package/ab-linear-progress/styles.module.css

@@ -72,7 +72,8 @@
   border-radius: inherit; /* 💊 same pill */
   background-color: var(--_ab-lp-color); /* 🎨 bar color */
   transform-origin: left center; /* ⬅️ grow from the start */
-  transition: transform 240ms ease-out; /* 🎞️ smooth value changes */
+  --ab-motion-duration: 240ms; /* 🎞️ value tween = .ab-motion-transform (ab-nextjs-animations) */
+  --ab-motion-easing: ease-out;
 }
 
 /* ↔️ RTL: grow from the right */
@@ -80,42 +81,25 @@
   transform-origin: right center;
 }
 
-/* 🔁 indeterminate: a 40% segment sweeping across */
+/* 🔁 indeterminate: a 40% segment; the sweep itself = .ab-progress-sweep (ab-nextjs-animations, RTL-mirrored) */
 .abLinearProgress__bar_indeterminate {
   right: auto; /* 🔓 free the right edge */
   width: 40%; /* 📏 segment width */
-  animation: abLinearProgressSweep 1.4s ease-in-out infinite; /* 🔁 loop */
 }
 
-/* 🎞️ sweep keyframes */
-@keyframes abLinearProgressSweep {
-  0% { transform: translateX(-100%); } /* ⬅️ off-screen left */
-  100% { transform: translateX(250%); } /* ➡️ off-screen right */
-}
-
-/* ↔️ RTL indeterminate: anchor on the right and sweep right → left (mirrored keyframes) */
+/* ↔️ RTL indeterminate: anchor on the right (the package mirrors the sweep) */
 :global([dir='rtl']) .abLinearProgress__bar_indeterminate {
   left: auto; /* 🔓 free the left edge */
   right: 0; /* 📌 start on the right */
-  animation-name: abLinearProgressSweepRtl; /* ⬅️ mirrored sweep */
-}
-
-/* 🎞️ mirrored sweep keyframes (RTL) */
-@keyframes abLinearProgressSweepRtl {
-  0% { transform: translateX(100%); } /* ➡️ off-screen right */
-  100% { transform: translateX(-250%); } /* ⬅️ off-screen left */
 }
 
-/* ♿ reduced motion: no animation, static bar */
+/* ♿ reduced motion: the package stops the sweep + tween; this only lays the static bar out across the track */
 @media (prefers-reduced-motion: reduce) {
-  .abLinearProgress__bar {
-    transition: none; /* 🚫 no value tween */
-  }
   .abLinearProgress__bar_indeterminate,
   :global([dir='rtl']) .abLinearProgress__bar_indeterminate {
-    animation: none; /* 🚫 no sweep (LTR + RTL) */
+    left: 0; /* 📌 */
+    right: 0; /* 📌 */
     width: 100%; /* 🟫 full static bar */
-    opacity: 0.55; /* 🌫️ softened so it reads as "busy", not "done" */
-    transform: none; /* 📐 in place */
   }
 }
+

package/ab-locale-switcher/index.tsx

@@ -0,0 +1,213 @@
+/* 
+* @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: AbLocaleSwitcher - Client (G7)
+* @file: ab-locale-switcher/index.tsx
+* @type: Component (client) — globe menu button (APG menu + menuitemradio)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> const { switchLocale } = useAbLocaleSwitch() // 🌍 from ab-nextjs-i18n/navigation
+*    -|> <AbLocaleSwitcher label={t('language')} current={locale} locales={[{ code: 'en', label: 'English' }, { code: 'fr', label: 'Français' }]} onSelect={switchLocale} />
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client';
+
+// ⚛️ React
+import type { CSSProperties, KeyboardEvent, ReactNode } from 'react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+// 🧵 classes
+import clsx from 'clsx';
+// 🔣 globe glyph
+import AbIcon from '../ab-icon';
+// 🎨 styles
+import styles from './styles.module.css';
+
+// 🌍 one locale option
+export interface AbLocaleOption {
+  code: string; // 🏷️ BCP 47, e.g. 'fr'
+  label: string; // 🗣️ endonym, e.g. 'Français' (shown in its own language)
+}
+
+// ⚙️ props
+export interface AbLocaleSwitcherProps {
+  locales: readonly AbLocaleOption[]; // 🌍 choices
+  current: string; // ✅ active locale code
+  label: string; // 🏷️ trigger name, e.g. "Language"
+  onSelect?: (code: string) => void; // 📣 button items (e.g. useAbLocaleSwitch().switchLocale)
+  getHref?: (code: string) => string; // 🔗 link items instead (real navigation, hreflang)
+  variant?: 'icon' | 'menu'; // 🎨 'icon' = globe only; 'menu' = globe + current endonym
+  align?: 'start' | 'end'; // ↔️ menu alignment under the trigger
+  icon?: ReactNode; // 🖼️ override the globe
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
+}
+
+/**
+ * @name getAbTypeaheadIndex
+ * @description 🔤 Index of the next option whose label starts with `char` (wraps), else -1.
+ */
+export function getAbTypeaheadIndex(labels: readonly string[], from: number, char: string): number {
+  const c = char.toLocaleLowerCase(); // 🔡
+  for (let step = 1; step <= labels.length; step++) {
+    const i = (from + step) % labels.length; // 🔁
+    if (labels[i].toLocaleLowerCase().startsWith(c)) return i; // ✅
+  }
+  return -1; // 🙅
+}
+
+export function AbLocaleSwitcher(props: AbLocaleSwitcherProps) {
+  // 🧩 props
+  const { locales, current, label, onSelect, getHref, variant = 'icon', align = 'end', icon, className, style } = props;
+  // 🚪 open?
+  const [open, setOpen] = useState(false);
+  // 🆔 ids
+  const base = useId();
+  // 📍 refs
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const itemRefs = useRef<Array<HTMLElement | null>>([]);
+  const rootRef = useRef<HTMLDivElement>(null);
+  // 🏷️ current option
+  const active = locales.find((l) => l.code === current);
+  const activeIndex = Math.max(0, locales.findIndex((l) => l.code === current));
+
+  // 🎯 focus an item
+  const focusItem = (i: number) => itemRefs.current[i]?.focus();
+  // 🚪 close and return focus to the trigger
+  const close = useCallback((returnFocus = true) => {
+    setOpen(false); // 🚪
+    if (returnFocus) triggerRef.current?.focus(); // 🎯
+  }, []);
+
+  // 🎯 on open, focus the checked item (after paint)
+  useEffect(() => {
+    if (!open) return; // 💤
+    const id = requestAnimationFrame(() => focusItem(activeIndex)); // ⏭️
+    return () => cancelAnimationFrame(id); // 🧹
+  }, [open, activeIndex]);
+
+  // 🖱️ click outside closes (no focus steal)
+  useEffect(() => {
+    if (!open) return; // 💤
+    const onDown = (e: PointerEvent) => { if (!rootRef.current?.contains(e.target as Node)) close(false); }; // 🚪
+    document.addEventListener('pointerdown', onDown); // 👂
+    return () => document.removeEventListener('pointerdown', onDown); // 🧹
+  }, [open, close]);
+
+  // ⌨️ trigger: ArrowDown/Up/Enter/Space open the menu
+  const onTriggerKey = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); setOpen(true); } // ⬇️
+  };
+
+  // ⌨️ menu keys
+  const onMenuKey = (e: KeyboardEvent<HTMLUListElement>) => {
+    const i = itemRefs.current.findIndex((el) => el === document.activeElement); // 📍
+    const n = locales.length; // 🔢
+    if (e.key === 'ArrowDown') { e.preventDefault(); focusItem((i + 1) % n); } // ⬇️
+    else if (e.key === 'ArrowUp') { e.preventDefault(); focusItem((i - 1 + n) % n); } // ⬆️
+    else if (e.key === 'Home') { e.preventDefault(); focusItem(0); } // ⏮️
+    else if (e.key === 'End') { e.preventDefault(); focusItem(n - 1); } // ⏭️
+    else if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); close(); } // 🚪
+    else if (e.key === 'Tab') { close(false); } // ⇥ let Tab move on
+    else if (e.key.length === 1 && /\S/.test(e.key)) { // 🔤 typeahead
+      const j = getAbTypeaheadIndex(locales.map((l) => l.label), Math.max(i, 0), e.key);
+      if (j >= 0) focusItem(j);
+    }
+  };
+
+  // ✅ choose
+  const choose = (code: string) => {
+    onSelect?.(code); // 📣
+    close(); // 🚪
+  };
+
+  return (
+    <div ref={rootRef} className={clsx('AbLocaleSwitcher', styles.root, className)} style={style} data-ab-part="locale-switcher" data-align={align}>
+      {/* 🌐 trigger */}
+      <button
+        ref={triggerRef} // 📍
+        id={`${base}-trigger`} // 🆔
+        type="button" // 🧾
+        className={clsx(styles.trigger, variant === 'menu' && styles.withText)} // 🎨
+        aria-haspopup="menu" // ♿
+        aria-expanded={open} // ♿
+        aria-controls={`${base}-menu`} // 🔗
+        aria-label={variant === 'icon' ? `${label}: ${active?.label ?? current}` : undefined} // 🏷️ "Language: Français"
+        title={label} // 💬
+        onClick={() => setOpen((o) => !o)} // 🖱️
+        onKeyDown={onTriggerKey} // ⌨️
+      >
+        <span aria-hidden="true">{icon ?? <AbIcon name="language" size={20} />}</span>
+        {variant === 'menu' ? <span lang={current}>{active?.label ?? current}</span> : null /* 🗣️ endonym */}
+      </button>
+      {/* 📜 menu */}
+      <ul
+        id={`${base}-menu`} // 🆔
+        role="menu" // ♿
+        aria-labelledby={`${base}-trigger`} // 🔗
+        hidden={!open} // 🙈
+        className={styles.menu} // 🎨
+        onKeyDown={onMenuKey} // ⌨️
+      >
+        {locales.map((l, i) => {
+          const checked = l.code === current; // ✅
+          const common = {
+            ref: (el: HTMLElement | null) => { itemRefs.current[i] = el; }, // 📍
+            role: 'menuitemradio' as const, // ♿
+            'aria-checked': checked, // ✅
+            tabIndex: -1, // ⌨️ focus managed by arrows
+            lang: l.code, // 🗣️ pronounced in its own language
+            className: styles.item, // 🎨
+          };
+          return (
+            <li key={l.code} role="none">
+              {getHref ? (
+                // 🔗 real navigation (works with middle-click, crawlers see hreflang)
+                <a {...common} href={getHref(l.code)} hrefLang={l.code} onClick={() => choose(l.code)}>
+                  <span className={styles.check} aria-hidden="true">{checked ? '✓' : ''}</span>{l.label}
+                </a>
+              ) : (
+                // 🔘 callback item
+                <button {...common} type="button" onClick={() => choose(l.code)}>
+                  <span className={styles.check} aria-hidden="true">{checked ? '✓' : ''}</span>{l.label}
+                </button>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+// 📦 default export
+export default AbLocaleSwitcher;

package/ab-locale-switcher/styles.module.css

@@ -0,0 +1,127 @@
+/* 
+* @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: AbLocaleSwitcher - Styles
+* @file: ab-locale-switcher/styles.module.css
+* @type: CSS module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 📦 anchor for the menu */
+.root {
+  position: relative; /* 📌 */
+  display: inline-block; /* 📐 */
+}
+
+/* 🌐 trigger (40px round, 44px on coarse pointers) */
+.trigger {
+  display: inline-flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  justify-content: center; /* ↔️ */
+  gap: 0.375rem; /* 🧱 */
+  min-width: 40px; /* 📏 */
+  height: 40px; /* 📏 */
+  padding: 0 0.5rem; /* 🧱 */
+  border: 0; /* 🧹 */
+  border-radius: 9999px; /* 💊 */
+  background: transparent; /* 🫥 */
+  color: inherit; /* 🎨 */
+  font: inherit; /* 🔤 */
+  cursor: pointer; /* 👆 */
+}
+.withText {
+  padding: 0 0.75rem; /* 🧱 room for the endonym */
+}
+.trigger:hover,
+.trigger[aria-expanded='true'] {
+  background: color-mix(in srgb, currentColor 10%, transparent); /* 🌫️ */
+}
+.trigger:focus-visible,
+.item:focus-visible {
+  outline: 2px solid var(--ab-focus-ring, var(--ab-color-primary, #A67C52)); /* 💍 */
+  outline-offset: 2px; /* ↔️ */
+}
+@media (pointer: coarse) {
+  .trigger { min-width: 44px; height: 44px; } /* 👆 mobile target */
+}
+
+/* 📜 menu */
+.menu {
+  position: absolute; /* 📌 */
+  top: calc(100% + 0.25rem); /* ⬇️ */
+  inset-inline-end: 0; /* ↔️ align end (RTL-aware) */
+  z-index: 50; /* 🧱 above content */
+  min-width: 11rem; /* 📏 */
+  margin: 0; /* 🧹 */
+  padding: 0.25rem; /* 🧱 */
+  list-style: none; /* 🧹 */
+  border-radius: 0.75rem; /* 🔲 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface, #fff); /* 🎨 */
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.12); /* 🌫️ */
+}
+.root[data-align='start'] .menu {
+  inset-inline-start: 0; /* ↔️ */
+  inset-inline-end: auto; /* 🧹 */
+}
+.menu[hidden] {
+  display: none; /* 🙈 */
+}
+
+/* 🗣️ item */
+.item {
+  display: flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  gap: 0.5rem; /* 🧱 */
+  width: 100%; /* ↔️ */
+  min-height: 40px; /* 📏 */
+  padding: 0 0.75rem; /* 🧱 */
+  border: 0; /* 🧹 */
+  border-radius: 0.5rem; /* 🔲 */
+  background: transparent; /* 🫥 */
+  color: inherit; /* 🎨 */
+  font: inherit; /* 🔤 */
+  text-align: start; /* ↔️ */
+  text-decoration: none; /* 🧹 links */
+  cursor: pointer; /* 👆 */
+}
+.item:hover,
+.item:focus-visible {
+  background: color-mix(in srgb, currentColor 8%, transparent); /* 🌫️ */
+}
+.item[aria-checked='true'] {
+  font-weight: 600; /* 💪 */
+}
+.check {
+  width: 1em; /* 📏 fixed column */
+  color: var(--ab-color-bronze-text, #8A6440); /* ♿ */
+}