ab-nextjs-components 0.1.8 → 0.1.10

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

@@ -0,0 +1,129 @@
+/* 
+* @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 Linear Progress
+* @file: ab-linear-progress/index.tsx
+* @type: Component (server-safe, no hooks) — ported from the reviewed ab-nextjs-core version
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🧩 React types only (no runtime hooks → works in server components too)
+import type { CSSProperties, ReactElement } from 'react';
+// 🧵 tiny class-name joiner
+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 {
+  // 🏷️ extra class names from the consumer
+  className?: string;
+  // 🎨 bar color (any CSS color); defaults to the bronze brand color
+  color?: string;
+  // 🙈 hide the whole bar (kept for API parity with LYD chrome)
+  hidden?: boolean;
+  // 🔁 indeterminate mode: no known value, bar sweeps back and forth
+  isIndeterminate?: boolean;
+  // 📊 determinate value from 0 to 100
+  progress?: number;
+  // 🗣️ accessible name for screen readers
+  label?: string;
+}
+
+// 🔒 clamp any number into the 0..100 range (NaN → 0)
+export const clampAbProgress = (value: number): number => {
+  // 🚫 non-finite values become 0
+  if (!Number.isFinite(value)) return 0;
+  // ✂️ clamp and return
+  return Math.min(100, Math.max(0, value));
+};
+
+/**
+ * 📊 AbLinearProgress — determinate (`progress`) or indeterminate (`isIndeterminate`)
+ * linear progress bar. Respects prefers-reduced-motion and html.dark.
+ */
+const AbLinearProgress = ({
+  className, // 🏷️ consumer classes
+  color, // 🎨 optional custom color
+  hidden = false, // 👀 visible by default
+  isIndeterminate = false, // 🔁 determinate by default
+  progress = 0, // 📊 start empty
+  label = 'Loading', // 🗣️ default accessible name
+}: AbLinearProgressProps): ReactElement => {
+  // ✂️ safe 0..100 value
+  const value = clampAbProgress(progress);
+  // 🎨 expose the color as a CSS custom property (only when provided)
+  const rootStyle = (color ? { '--ab-linear-progress-color': color } : undefined) as CSSProperties | undefined;
+
+  // 🧱 render the track + bar
+  return (
+    <div
+      // 🏷️ stable public class + module class + consumer class
+      className={clsx('AbLinearProgress', styles.abLinearProgress, className)}
+      // 🎨 custom color, if any
+      style={rootStyle}
+      // 🙈 native hidden attribute
+      hidden={hidden}
+      // ♿ ARIA progressbar role
+      role="progressbar"
+      // 🗣️ accessible name (dropped when empty, e.g. inside an aria-hidden overlay)
+      aria-label={label ? label : undefined}
+      // 📏 range lower bound
+      aria-valuemin={0}
+      // 📏 range upper bound
+      aria-valuemax={100}
+      // 📊 current value only in determinate mode (omitted = indeterminate per ARIA)
+      aria-valuenow={isIndeterminate ? undefined : value}
+      // ⏳ tell AT we're busy while indeterminate
+      aria-busy={isIndeterminate ? true : undefined}
+      // 🙈 hide from AT when hidden
+      aria-hidden={hidden ? true : undefined}
+      // 🔖 mode hook for styling/tests
+      data-ab-mode={isIndeterminate ? 'indeterminate' : 'determinate'}
+    >
+      {/* 🟫 the moving / filling bar */}
+      <div
+        // 🏷️ bar class (indeterminate gets the sweep class)
+        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})` }}
+      />
+    </div>
+  );
+};
+
+// 📦 default export
+export default AbLinearProgress;

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

@@ -0,0 +1,105 @@
+/* 
+* @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 Linear Progress - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: ab-linear-progress/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* ===== 📊 AB LINEAR PROGRESS ===== */
+
+/* 🧱 track */
+.abLinearProgress {
+  /* 🎨 default bronze color (light) */
+  --_ab-lp-color: var(--ab-linear-progress-color, #A67C52);
+  /* 📏 default height, overridable */
+  --_ab-lp-height: var(--ab-linear-progress-height, 4px);
+  position: relative; /* 📌 anchor for the bar */
+  display: block; /* 🧱 full-width block */
+  width: 100%; /* ↔️ fill the parent */
+  height: var(--_ab-lp-height); /* ↕️ thin bar */
+  overflow: hidden; /* ✂️ clip the sweeping bar */
+  border-radius: 9999px; /* 💊 pill */
+  /* 🌫️ faint track tinted by the bar color */
+  background-color: color-mix(in srgb, var(--_ab-lp-color) 18%, transparent);
+}
+
+/* 🙈 honor the hidden attribute even if display is set */
+.abLinearProgress[hidden] {
+  display: none;
+}
+
+/* 🌙 dark mode: lighter bronze on dark surfaces */
+:global(html.dark) .abLinearProgress {
+  --_ab-lp-color: var(--ab-linear-progress-color, #C9A27A);
+  background-color: color-mix(in srgb, var(--_ab-lp-color) 22%, transparent);
+}
+
+/* 🟫 bar */
+.abLinearProgress__bar {
+  position: absolute; /* 📌 sits on the track */
+  inset: 0; /* 📐 full size, scaled via transform */
+  border-radius: inherit; /* 💊 same pill */
+  background-color: var(--_ab-lp-color); /* 🎨 bar color */
+  transform-origin: left center; /* ⬅️ grow from the start */
+  --ab-motion-duration: 240ms; /* 🎞️ value tween = .ab-motion-transform (ab-nextjs-animations) */
+  --ab-motion-easing: ease-out;
+}
+
+/* ↔️ RTL: grow from the right */
+:global([dir='rtl']) .abLinearProgress__bar {
+  transform-origin: right center;
+}
+
+/* 🔁 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 */
+}
+
+/* ↔️ 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 */
+}
+
+/* ♿ 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_indeterminate,
+  :global([dir='rtl']) .abLinearProgress__bar_indeterminate {
+    left: 0; /* 📌 */
+    right: 0; /* 📌 */
+    width: 100%; /* 🟫 full static bar */
+  }
+}
+

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;