ab-nextjs-components 0.1.9 → 0.1.11

package/ab-pill/index.tsx

@@ -0,0 +1,74 @@
+/* 
+* @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: AbPill - Server (G36)
+* @file: ab-pill/index.tsx
+* @type: Server component (static, no JS)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <AbPill dot="sage">Free forever · MIT</AbPill>
+*    -|> <AbPill mono>ab-nextjs-core</AbPill>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚛️ types
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+// 🧵 classes
+import clsx from 'clsx';
+// 🎨 shares the chip stylesheet (pill composes chip)
+import styles from '../ab-chip/styles.module.css';
+// 🎨 dot colours
+import type { AbChipDot } from '../ab-chip';
+
+// ⚙️ props
+export interface AbPillProps {
+  children: ReactNode; // 🏷️ eyebrow text
+  dot?: AbChipDot; // 🟢 leading dot
+  icon?: ReactNode; // 🖼️ decorative icon
+  mono?: boolean; // ⌨️ monospace (package names)
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
+}
+
+/** 💊 Eyebrow pill above a title. Static text; dot + icon are decorative. */
+export function AbPill({ children, dot, icon, mono = false, className, style }: AbPillProps): ReactElement {
+  return (
+    <span className={clsx('AbPill', styles.pill, mono && styles.mono, className)} style={style} data-ab-part="pill">
+      {dot ? <span className={styles.dot} data-tone={dot} aria-hidden="true" /> : null /* 🟢 */}
+      {icon ? <span className={styles.icon} aria-hidden="true">{icon}</span> : null /* 🖼️ */}
+      <span>{children}</span>
+    </span>
+  );
+}
+
+// 📦 default export
+export default AbPill;

package/ab-progress-chips/index.tsx

@@ -5,17 +5,46 @@
 * ~~~~~~~~~~~~ 
 * 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: AbProgressChips - Client (port of lyd-progress-chips)
 * @file: ab-progress-chips/index.tsx
+* @type: TypeScript (React)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 'use client';
 
 import type { CSSProperties, ReactElement } from 'react';
 import { useState } from 'react';
 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-*
 
 export interface AbProgressChip {
   id: number;
@@ -91,7 +120,7 @@ const AbProgressChips = ({
               onChipClick?.(chip.id, chip.code, chip.name, chip.duration);
             }}
           >
-            <span className={styles.abProgressChipBar} aria-hidden />
+            <span className={clsx(styles.abProgressChipBar, AB_MOTION.size)} aria-hidden />{/* 📏 width fill = .ab-motion-size */}
             <span className={styles.abProgressChipCode}>{chip.code}</span>
             {!isChipNameHidden ? <span className={styles.abProgressChipName}>{chip.name}</span> : null}
           </button>

package/ab-progress-chips/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-progress-chips - styles
+* @file: ab-progress-chips/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 .abProgressChips {
   display: flex;
   flex-wrap: wrap;
@@ -29,7 +68,7 @@
   height: 3px;
   background: var(--ab-primary, #6750a4);
   width: var(--chip-progress, 0%);
-  transition: width 0.2s linear;
+  --ab-motion-easing: linear; /* 📏 fill motion = .ab-motion-size (ab-nextjs-animations) */
 }
 .abProgressChipName {
   font-size: 0.8125rem;

package/ab-searchbar/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: AbSearchbar - Client (port of lyd-searchbar)
 * @file: ab-searchbar/index.tsx
+* @type: TypeScript (React)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 'use client';
 
 import type { CSSProperties, KeyboardEvent, ReactElement } from 'react';
 import { useId, useRef, useState } from 'react';
 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 AbSearchbarProps {
   className?: string;
@@ -99,7 +130,7 @@ const AbSearchbar = ({
     <div
       hidden={hidden}
       style={style}
-      className={clsx('AbSearchbar', styles.abSearchbar, disabled && styles.isDisabled, className)}
+      className={clsx('AbSearchbar', styles.abSearchbar, AB_MOTION.colors, disabled && styles.isDisabled, className)}
       data-busy={busy ? 'true' : 'false'}
     >
       <span className={clsx('material-symbols-rounded', styles.abSearchbarIcon)} aria-hidden>
@@ -124,7 +155,7 @@ const AbSearchbar = ({
         }}
         onKeyUp={(e) => onKeyUp?.(e.currentTarget.value, e)}
       />
-      {busy ? <span className={styles.abSearchbarSpinner} aria-hidden /> : null}
+      {busy ? <span className={clsx(styles.abSearchbarSpinner, AB_SPIN_CLASS)} aria-hidden /> : null}
       {current && !disabled ? (
         <button type="button" className={styles.abSearchbarClear} aria-label={clearLabel} onClick={clear}>
           <span className="material-symbols-rounded" aria-hidden>close</span>

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/index.tsx

@@ -60,6 +60,8 @@ import {
 } 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';
@@ -125,7 +127,7 @@ export default function AbSplash({ className, wordmark = 'Elements', maxMs }: Ab
 
   return (
     // 💦 the overlay (decorative → hidden from assistive tech)
-    <div ref={ref} className={clsx('AbSplash', styles.abSplash, className)} aria-hidden="true">
+    <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 */}

package/ab-splash/styles.module.css

@@ -49,7 +49,7 @@
   gap: 2.25rem; /* ↕️ brand ↔ bar */
   background-color: #FFF8F3; /* ☀️ light surface (matches the splash mocks) */
   color: #A67C52; /* 🎨 bronze brand */
-  transition: opacity 200ms ease; /* 🌫️ fade-out */
+  --ab-motion-duration: 200ms; /* 🌫️ fade-out = .ab-motion-colors (ab-nextjs-animations; off under reduced motion) */
   animation: abSplashFailsafe 0s linear 1.2s forwards; /* ⏱️ never longer than 1.2 s, even without hydration */
 }
 
@@ -95,10 +95,7 @@
   --ab-linear-progress-color: #A67C52; /* 🎨 bronze bar in both themes */
 }
 
-/* ♿ reduced motion: no fade */
-@media (prefers-reduced-motion: reduce) {
-  .abSplash { transition: none; }
-}
+/* ♿ reduced motion: no fade (handled by ab-nextjs-animations .ab-motion-colors) */
 
 /* ⏱️ failsafe keyframes */
 @keyframes abSplashFailsafe {

package/ab-theme-toggle/index.tsx

@@ -0,0 +1,188 @@
+/* 
+* @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: AbThemeToggle - Client (G9/G34)
+* @file: ab-theme-toggle/index.tsx
+* @type: Component (client) — light / dark / system
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <AbThemeToggle labels={{ group: t('theme.label'), light: t('theme.light'), dark: t('theme.dark'), system: t('theme.system') }} />
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+'use client';
+
+// ⚛️ React
+import type { CSSProperties, KeyboardEvent, ReactNode } from 'react';
+import { useRef } from 'react';
+// 🧵 classes
+import clsx from 'clsx';
+// 🌗 theme engine (hooks ≥ 0.1.6, deep import = tree-shaken)
+import { useAbThemeMode, AB_THEME_MODES, type AbThemeMode } from 'ab-nextjs-hooks/useAbTheme';
+// 🔣 icons (SVG once G2 lands)
+import AbIcon from '../ab-icon';
+// 🎨 styles
+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-*
+
+// 📦 re-export the mode type for consumers
+export type { AbThemeMode } from 'ab-nextjs-hooks/useAbTheme';
+
+// 🏷️ i18n labels (required: no English defaults baked into a11y names)
+export interface AbThemeToggleLabels {
+  group: string; // 🗂️ "Theme"
+  light: string; // 🌞 "Light"
+  dark: string; // 🌙 "Dark"
+  system: string; // 🖥️ "System"
+}
+
+// ⚙️ props
+export interface AbThemeToggleProps {
+  labels: AbThemeToggleLabels; // 🏷️
+  variant?: 'segmented' | 'icon'; // 🎨 pill of radios, or one cycling icon button
+  modes?: readonly AbThemeMode[]; // 🎚️ default light, dark, system
+  value?: AbThemeMode; // 🎛️ controlled
+  onChange?: (mode: AbThemeMode) => void; // 📣
+  defaultMode?: AbThemeMode; // 🌱 before hydration (default 'light')
+  icons?: Partial<Record<AbThemeMode, ReactNode>>; // 🖼️ override glyphs
+  size?: 'sm' | 'md'; // 📏 sm = 32px, md = 40px segments (hit area ≥ 24px either way)
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
+}
+
+// 🔣 default glyphs (AbIcons names)
+const DEFAULT_ICON_NAMES: Record<AbThemeMode, string> = { light: 'light_mode', dark: 'dark_mode', system: 'computer' };
+
+/**
+ * @name getNextAbThemeMode
+ * @description 🔁 Radio-group arrow logic (pure): wraps, RTL flips Left/Right.
+ */
+export function getNextAbThemeMode(modes: readonly AbThemeMode[], current: AbThemeMode, key: string, dir: 'ltr' | 'rtl' = 'ltr'): AbThemeMode | null {
+  const i = Math.max(0, modes.indexOf(current)); // 📍
+  const forward = dir === 'rtl' ? 'ArrowLeft' : 'ArrowRight'; // ➡️
+  const backward = dir === 'rtl' ? 'ArrowRight' : 'ArrowLeft'; // ⬅️
+  if (key === forward || key === 'ArrowDown') return modes[(i + 1) % modes.length]; // ⏭️
+  if (key === backward || key === 'ArrowUp') return modes[(i - 1 + modes.length) % modes.length]; // ⏮️
+  if (key === 'Home') return modes[0]; // ⏮️⏮️
+  if (key === 'End') return modes[modes.length - 1]; // ⏭️⏭️
+  return null; // 🙅
+}
+
+export function AbThemeToggle(props: AbThemeToggleProps) {
+  // 🧩 props
+  const { labels, variant = 'segmented', modes = AB_THEME_MODES, value, onChange, defaultMode = 'light', icons, size = 'md', className, style } = props;
+  // 🌗 engine: persists + applies to <html>
+  const engine = useAbThemeMode(defaultMode);
+  // 🎛️ controlled or engine-driven
+  const current = (value ?? engine.mode) as AbThemeMode;
+  // 📍 refs to move focus with the selection
+  const refs = useRef<Array<HTMLButtonElement | null>>([]);
+
+  // ✍️ select a mode
+  const select = (mode: AbThemeMode) => {
+    if (value === undefined) engine.setMode(mode); // 🎚️ uncontrolled: apply + persist
+    onChange?.(mode); // 📣
+  };
+
+  // 🖼️ glyph for a mode (decorative: the label names it)
+  const glyph = (mode: AbThemeMode) => icons?.[mode] ?? <AbIcon name={DEFAULT_ICON_NAMES[mode]} size={20} />;
+
+  // 🔘 single cycling button variant
+  if (variant === 'icon') {
+    const next = modes[(Math.max(0, modes.indexOf(current)) + 1) % modes.length]; // ⏭️
+    return (
+      <button
+        type="button" // 🧾
+        className={clsx('AbThemeToggle', styles.icon, AB_MOTION.colors, className)} // 🏷️
+        style={style} // 🎨
+        data-ab-part="theme-toggle" // 🗂️
+        data-mode={current} // 🎚️
+        data-size={size} // 📏
+        aria-label={`${labels.group}: ${labels[current]}`} // ♿ "Theme: Dark"
+        title={`${labels.group}: ${labels[current]}`} // 💬
+        onClick={() => select(next)} // 🔁
+      >
+        <span aria-hidden="true">{glyph(current)}</span>
+      </button>
+    );
+  }
+
+  // ⌨️ roving radio keys
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const dir = (event.currentTarget.closest('[dir]')?.getAttribute('dir') === 'rtl' ? 'rtl' : 'ltr') as 'ltr' | 'rtl'; // 🌍
+    const target = getNextAbThemeMode(modes, current, event.key, dir); // 🎯
+    if (!target) return; // 🙅 other keys untouched
+    event.preventDefault(); // 🛑 no scroll
+    select(target); // ✅ selection follows focus (radio pattern)
+    refs.current[modes.indexOf(target)]?.focus(); // 🎯
+  };
+
+  // 🎛️ segmented radiogroup
+  return (
+    <div
+      role="radiogroup" // ♿
+      aria-label={labels.group} // 🏷️
+      className={clsx('AbThemeToggle', styles.group, className)} // 🏷️
+      style={style} // 🎨
+      data-ab-part="theme-toggle" // 🗂️
+      data-mode={current} // 🎚️
+      data-size={size} // 📏
+      onKeyDown={onKeyDown} // ⌨️
+    >
+      {modes.map((mode, i) => {
+        const checked = mode === current; // ✅
+        return (
+          <button
+            key={mode} // 🔑
+            ref={(el) => { refs.current[i] = el; }} // 📍
+            type="button" // 🧾
+            role="radio" // ♿
+            aria-checked={checked} // ✅
+            aria-label={labels[mode]} // 🏷️
+            title={labels[mode]} // 💬
+            tabIndex={checked ? 0 : -1} // ⌨️ roving: one tab stop
+            className={clsx(styles.segment, AB_MOTION.colors)} // 🎨 + colour fade (ab-nextjs-animations)
+            data-ab-part="theme-option" // 🗂️
+            data-mode={mode} // 🎚️
+            onClick={() => select(mode)} // 🖱️
+          >
+            <span aria-hidden="true">{glyph(mode)}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+// 📦 default export
+export default AbThemeToggle;

package/ab-theme-toggle/styles.module.css

@@ -0,0 +1,89 @@
+/* 
+* @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: AbThemeToggle - Styles
+* @file: ab-theme-toggle/styles.module.css
+* @type: CSS module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 💊 segmented pill */
+.group {
+  display: inline-flex; /* 📐 row */
+  gap: 2px; /* 🧱 */
+  padding: 3px; /* 🧱 */
+  border-radius: 9999px; /* 💊 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface-container, transparent); /* 🎨 */
+}
+
+/* 🔘 each option; md = 40px, sm = 32px (both ≥ 24px target, WCAG 2.5.8) */
+.segment,
+.icon {
+  display: inline-grid; /* 📐 */
+  place-items: center; /* 🎯 */
+  width: 40px; /* 📏 */
+  height: 40px; /* 📏 */
+  padding: 0; /* 🧹 */
+  border: 0; /* 🧹 */
+  border-radius: 9999px; /* 💊 */
+  color: var(--ab-color-on-surface-variant, currentColor); /* 🎨 */
+  background: transparent; /* 🫥 */
+  cursor: pointer; /* 👆 */
+  --ab-motion-duration: var(--ab-motion-duration-short, 160ms); /* 🎞️ colour fade = .ab-motion-colors (ab-nextjs-animations) */
+}
+[data-size='sm'] .segment,
+.icon[data-size='sm'] {
+  width: 32px; /* 📏 */
+  height: 32px; /* 📏 */
+}
+
+/* ✅ selected */
+.segment[aria-checked='true'] {
+  color: var(--ab-color-on-primary, #fff); /* 🎨 */
+  background: var(--ab-color-primary, #A67C52); /* 🥉 bronze */
+}
+
+/* 🖱️ hover (unselected only) */
+.segment[aria-checked='false']:hover,
+.icon:hover {
+  background: color-mix(in srgb, currentColor 10%, transparent); /* 🌫️ */
+}
+
+/* ♿ visible focus ring (theme token, G18) */
+.segment:focus-visible,
+.icon:focus-visible {
+  outline: 2px solid var(--ab-focus-ring, var(--ab-color-primary, #A67C52)); /* 💍 */
+  outline-offset: 2px; /* ↔️ */
+}
+
+/* 🧘 reduced motion: handled by ab-nextjs-animations (.ab-motion-colors) */