ab-nextjs-components 0.1.9 → 0.1.11

package/css/dialog.css

@@ -1,7 +1,41 @@
+/* 
+* @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: Dialog chrome styles (moved out of ab-nextjs-theme)
+* @file: css/dialog.css
+* @type: CSS
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
 /*
- * ab-nextjs-components — chrome styles moved out of ab-nextjs-theme
- * Copyright (c) 2026 Abraham Ukachi. MIT.
- */
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
 
 /* Dialogs */
 #dialogs, .Dialogs {
@@ -104,6 +138,7 @@ li.dialog-list-item {
   transform-origin: left;
   opacity: var(--opacity-dialog-list-item, 0.68);
   user-select: none;
+  /* ⚠️ named motion exception (James review): consumer-rendered markup, no component can add an ab-motion-* class; pinned in __tests__/motion-from-animations.test.tsx */
   transition: all 0.2s ease-in-out;
 }
 

package/index.ts

@@ -5,11 +5,38 @@
 * ~~~~~~~~~~~~ 
 * 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: Components - Package Catalog
 * @file: index.ts
+* @type: Package catalog + barrel
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 import type { ComponentCatalogEntry } from './types'
 
 /**
@@ -24,6 +51,8 @@ const supportedComponents: Array<ComponentCatalogEntry> = [
   { name: 'AbLinearProgress', file: 'ab-linear-progress/index.tsx', kind: 'client', status: 'Done' },
   // 💦 AbSplash: subpath-only (`ab-nextjs-components/ab-splash`)
   { name: 'AbSplash', file: 'ab-splash/index.tsx', kind: 'client', status: 'Done' },
+  // 🎠 G31 AbCarousel (Welcome v6): subpath-only (`ab-nextjs-components/ab-carousel`), needs ab-nextjs-hooks >= 0.1.6
+  { name: 'AbCarousel', file: 'ab-carousel/index.tsx', kind: 'client', status: 'Done' },
   { name: 'AbButton', file: 'ab-button/index.tsx', kind: 'client', status: 'Done' },
   { name: 'AbIconButton', file: 'ab-icon-button/index.tsx', kind: 'client', status: 'Done' },
   { name: 'AbInput', file: 'ab-input/index.tsx', kind: 'client', status: 'Done' },
@@ -75,6 +104,18 @@ const supportedComponents: Array<ComponentCatalogEntry> = [
   { name: 'AbTestHello', file: 'server/ab-test-hello/index.tsx', kind: 'server', status: 'Done' },
   { name: 'AbKeyFeature', file: 'server/ab-key-feature/index.tsx', kind: 'server', status: 'Done' },
   { name: 'AbSwitchBack', file: 'server/ab-switch-back/index.tsx', kind: 'server', status: 'Done' },
+  // 🆕 Welcome v6 (AbThemeToggle)
+  { name: 'AbThemeToggle', file: 'ab-theme-toggle/index.tsx', kind: 'client', status: 'Done' },
+  // 🆕 Welcome v6 (AbChip)
+  { name: 'AbChip', file: 'ab-chip/index.tsx', kind: 'server', status: 'Done' },
+  // 🆕 Welcome v6 (AbPill)
+  { name: 'AbPill', file: 'ab-pill/index.tsx', kind: 'server', status: 'Done' },
+  // 🆕 Welcome v6 (AbInstallSnippet)
+  { name: 'AbInstallSnippet', file: 'ab-install-snippet/index.tsx', kind: 'client', status: 'Done' },
+  // 🆕 Welcome v6 (AbLocaleSwitcher)
+  { name: 'AbLocaleSwitcher', file: 'ab-locale-switcher/index.tsx', kind: 'client', status: 'Done' },
+  // 🆕 Welcome v6 (AbFlowDiagram)
+  { name: 'AbFlowDiagram', file: 'ab-flow-diagram/index.tsx', kind: 'server', status: 'Done' },
 ]
 
 const abComponents = { supportedComponents }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ab-nextjs-components",
-  "version": "0.1.9",
-  "description": "\ud83d\ude80 A lightweight collection of server & client React components created by Abraham Ukachi, and optimized for Next.js applications \ud83d\ude0e.",
+  "version": "0.1.11",
+  "description": "🚀 A lightweight collection of server & client React components created by Abraham Ukachi, and optimized for Next.js applications 😎.",
   "type": "module",
   "main": "index.ts",
   "types": "types/index.d.ts",
@@ -40,28 +40,33 @@
   },
   "license": "MIT",
   "peerDependencies": {
+    "ab-nextjs-animations": "^0.2.4",
+    "ab-nextjs-hooks": "^0.1.6",
+    "ab-nextjs-icons": "^0.2.3",
+    "ab-nextjs-theme": "^0.3.1",
     "clsx": "^2",
     "next": "^16.3.4",
     "react": "^19",
-    "react-dom": "^19",
-    "ab-nextjs-theme": "*",
-    "ab-nextjs-icons": "*",
-    "ab-nextjs-hooks": "*",
-    "ab-nextjs-animations": "*"
+    "react-dom": "^19"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^20",
     "@types/react": "^19",
+    "ab-nextjs-animations": "^0.2.4",
+    "ab-nextjs-hooks": "^0.1.6",
+    "ab-nextjs-icons": "^0.2.3",
+    "ab-nextjs-theme": "^0.3.1",
+    "clsx": "^2.1.1",
+    "esbuild": "^0.28.2",
     "eslint": "^9.39.0",
     "eslint-config-next": "16.3.4",
+    "happy-dom": "^20.14.6",
     "next": "16.3.4",
     "react": "^19",
     "react-dom": "^19",
     "typescript": "^5",
-    "vitest": "^3",
-    "clsx": "^2.1.1",
-    "ab-nextjs-hooks": "^0.1.2",
-    "esbuild": "^0.28.2"
+    "vitest": "^3"
   },
   "files": [
     "index.ts",
@@ -108,6 +113,13 @@
     "ab-demo-code",
     "ab-splash",
     "ab-linear-progress",
+    "ab-carousel",
+    "ab-flow-diagram",
+    "ab-locale-switcher",
+    "ab-install-snippet",
+    "ab-pill",
+    "ab-chip",
+    "ab-theme-toggle",
     "ab-logo/ab-logo.svg",
     "styles.css",
     "css",
@@ -123,6 +135,16 @@
     "./ab-logo": "./ab-logo/index.tsx",
     "./ab-linear-progress": "./ab-linear-progress/index.tsx",
     "./ab-splash": "./ab-splash/index.tsx",
+    "./ab-carousel": "./ab-carousel/index.tsx",
+    "./ab-carousel/helpers": "./ab-carousel/helpers.ts",
+    "./ab-theme-toggle": "./ab-theme-toggle/index.tsx",
+    "./ab-chip": "./ab-chip/index.tsx",
+    "./ab-pill": "./ab-pill/index.tsx",
+    "./ab-install-snippet": "./ab-install-snippet/index.tsx",
+    "./ab-install-snippet/helpers": "./ab-install-snippet/helpers.ts",
+    "./ab-locale-switcher": "./ab-locale-switcher/index.tsx",
+    "./ab-flow-diagram": "./ab-flow-diagram/index.tsx",
+    "./ab-flow-diagram/helpers": "./ab-flow-diagram/helpers.ts",
     "./ab-splash/gate": "./ab-splash/gate.ts",
     "./ab-splash/csp": {
       "types": "./ab-splash/csp.d.ts",
@@ -188,14 +210,8 @@
     "ab-nextjs-theme": {
       "optional": true
     },
-    "ab-nextjs-icons": {
-      "optional": true
-    },
     "ab-nextjs-hooks": {
       "optional": true
-    },
-    "ab-nextjs-animations": {
-      "optional": true
     }
   }
 }

package/server/ab-brand/index.tsx

@@ -5,9 +5,35 @@
 * ~~~~~~~~~~~~ 
 * 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: AbBrand - Server (port of lyd-brand)
 * @file: server/ab-brand/index.tsx
+* @type: TypeScript (React)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
 
@@ -16,6 +42,8 @@ import Link from 'next/link';
 import Image from 'next/image';
 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 AbBrandProps {
   className?: string;
@@ -70,7 +98,7 @@ const AbBrand = ({
       style={style}
     >
       <div className={styles.abBrandImageWrap}>
-        <Image className={styles.abBrandImage} src={image} alt={imageAlt ?? name} width={640} height={360} unoptimized />
+        <Image className={clsx(styles.abBrandImage, AB_MOTION.transform)} src={image} alt={imageAlt ?? name} width={640} height={360} unoptimized />
       </div>
       <div className={styles.abBrandMeta}>
         <Image className={styles.abBrandLogo} src={logo} alt={logoAlt ?? shortName} width={40} height={40} unoptimized />

package/server/ab-brand/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-brand - styles
+* @file: server/ab-brand/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 .abBrand {
   position: relative;
   display: flex;
@@ -28,7 +67,7 @@
   object-fit: cover;
   width: 100%;
   height: 100%;
-  transition: transform 0.35s ease;
+  --ab-motion-duration: 350ms; /* 🔍 zoom tween = .ab-motion-transform (ab-nextjs-animations) */
 }
 .abBrandLogo {
   width: 2.5rem;

package/server/ab-button/index.tsx

@@ -22,117 +22,133 @@
 * 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: AbButton - Server (no onClick; href→<a> or submit)
 * @file: server/ab-button/index.tsx
+* @type: Server component — G22 parity with the client twin
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
+// ⚛️ types
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
+// 🧵 class joiner
 import clsx from 'clsx';
+// 🎨 styles (server copy)
 import styles from './styles.module.css';
+// 🧮 the SAME rules as the client twin
+import {
+  getAbButtonDisabledMode,
+  getAbButtonSrReason,
+  type AbButtonBadgeTone,
+  type AbButtonColor,
+  type AbButtonType,
+} from '../../ab-button/helpers';
 
-export type AbButtonType = 'contained' | 'outlined' | 'text';
-export type AbButtonColor = 'primary' | 'secondary' | 'tertiary' | 'white' | 'black';
+// 📦 shared types
+export type { AbButtonBadgeTone, AbButtonColor, AbButtonType, AbButtonDisabledMode } from '../../ab-button/helpers';
 
+// ⚙️ props (no onClick on the server)
 export interface AbButtonProps {
-  id?: string;
-  type?: AbButtonType;
-  htmlType?: 'button' | 'submit' | 'reset';
-  className?: string;
-  hidden?: boolean;
-  style?: CSSProperties;
-  rounded?: boolean;
-  raised?: boolean;
-  shrinks?: boolean;
-  expands?: boolean;
-  withIcon?: boolean;
-  disabled?: boolean;
-  iconPosition?: 'left' | 'right';
-  label: string;
-  icon?: string;
-  color?: AbButtonColor;
-  href?: string;
-  children?: ReactNode;
+  id?: string; // 🆔
+  type?: AbButtonType; // 🎨
+  htmlType?: 'button' | 'submit' | 'reset'; // 🧾
+  className?: string; // 🏷️
+  hidden?: boolean; // 🙈
+  style?: CSSProperties; // 🎨
+  rounded?: boolean; // 💊
+  raised?: boolean; // 🏔️
+  shrinks?: boolean; // 🤏
+  expands?: boolean; // 🔍
+  withIcon?: boolean; // 🔣
+  disabled?: boolean; // 🚫
+  iconPosition?: 'left' | 'right'; // ↔️
+  label: string; // 🏷️
+  icon?: string; // 🔣
+  color?: AbButtonColor; // 🎨
+  href?: string; // 🔗
+  children?: ReactNode; // 🧩
+  startIcon?: ReactNode; // 🖼️ G22
+  endIcon?: ReactNode; // 🖼️ G22
+  badge?: ReactNode; // 🏷️ G22
+  badgeTone?: AbButtonBadgeTone; // 🎨 G22
+  disabledReason?: string; // 💬 G22
+  focusableWhenDisabled?: boolean; // ⌨️ G22
 }
 
-/** Server AbButton — no onClick. Use href for links or htmlType for form submit. */
+/** 🖥️ Server AbButton: no onClick. Use href for links or htmlType for form submit. No-JS safe. */
 const AbButton = ({
-  id,
-  type = 'contained',
-  htmlType = 'button',
-  className,
-  hidden = false,
-  style,
-  rounded = true,
-  raised = false,
-  shrinks = false,
-  expands = false,
-  withIcon = false,
-  disabled = false,
-  iconPosition = 'left',
-  label,
-  icon,
-  color = 'primary',
-  href,
-  children,
+  id, type = 'contained', htmlType = 'button', className, hidden = false, style, rounded = true, raised = false,
+  shrinks = false, expands = false, withIcon = false, disabled = false, iconPosition = 'left', label, icon,
+  color = 'primary', href, children, startIcon, endIcon, badge, badgeTone = 'neutral', disabledReason, focusableWhenDisabled,
 }: AbButtonProps): ReactElement => {
-  const classNames = clsx(
-    'AbButton',
-    styles.abButton,
-    className,
-    rounded && styles.abButtonRounded,
-    disabled && styles.isDisabled,
-  );
+  // 🚦 shared disabled rules
+  const mode = getAbButtonDisabledMode({ disabled, badge, disabledReason, focusableWhenDisabled });
+  // 💬 hidden reason
+  const srReason = getAbButtonSrReason({ disabled, disabledReason });
 
+  // 🏷️ classes
+  const classNames = clsx('AbButton', styles.abButton, className, rounded && styles.abButtonRounded, mode === 'native' && styles.isDisabled);
+
+  // 🗂️ data attributes
   const dataAttrs = {
-    'data-type': type,
-    'data-raised': raised ? 'true' : 'false',
-    'data-shrinks': shrinks ? 'true' : 'false',
-    'data-expands': expands ? 'true' : 'false',
-    'data-rounded': rounded ? 'true' : 'false',
-    'data-iconpos': iconPosition,
-    'data-color': color,
+    'data-type': type, // 🎨
+    'data-raised': raised ? 'true' : 'false', // 🏔️
+    'data-shrinks': shrinks ? 'true' : 'false', // 🤏
+    'data-expands': expands ? 'true' : 'false', // 🔍
+    'data-rounded': rounded ? 'true' : 'false', // 💊
+    'data-iconpos': iconPosition, // ↔️
+    'data-color': color, // 🎨
+    'data-disabled-mode': mode, // 🚦
   } as const;
 
+  // 🔣 legacy icon (decorative)
+  const legacyIcon = withIcon && icon ? <span className={clsx('material-symbols-rounded', 'icon')} aria-hidden="true">{icon}</span> : null;
+
+  // 🧱 content (same order as the client twin)
   const content = (
     <>
-      {withIcon && iconPosition === 'left' && icon ? (
-        <span className={clsx('material-symbols-rounded', 'icon')}>{icon}</span>
-      ) : null}
+      {iconPosition === 'left' ? legacyIcon : null}
+      {startIcon ? <span className={styles.abButtonSlot} aria-hidden="true">{startIcon}</span> : null}
       <span>{children ?? label}</span>
-      {withIcon && iconPosition === 'right' && icon ? (
-        <span className={clsx('material-symbols-rounded', 'icon')}>{icon}</span>
+      {badge ? (
+        <>
+          <span className={styles.srOnly}>, </span>
+          <span className={styles.abButtonBadge} data-tone={badgeTone} data-ab-part="badge" aria-hidden={srReason ? true : undefined}>{badge}</span>
+        </>
       ) : null}
+      {srReason ? <span className={styles.srOnly}>, {srReason}</span> : null}
+      {endIcon ? <span className={styles.abButtonSlot} aria-hidden="true">{endIcon}</span> : null}
+      {iconPosition === 'right' ? legacyIcon : null}
     </>
   );
 
+  // 🔗 link mode
   if (href) {
-    return (
-      <a
-        id={id}
-        href={disabled ? undefined : href}
-        role="button"
-        className={classNames}
-        style={style}
-        hidden={hidden}
-        aria-disabled={disabled}
-        {...dataAttrs}
-      >
-        {content}
-      </a>
-    );
+    if (mode !== 'none') {
+      // 🚫 blocked link: no href, role=link, focusable only in aria mode
+      return <span id={id} role="link" aria-disabled="true" tabIndex={mode === 'aria' ? 0 : -1} className={classNames} style={style} hidden={hidden} {...dataAttrs}>{content}</span>;
+    }
+    // ✅ a link is a link (no role=button)
+    return <a id={id} href={href} className={classNames} style={style} hidden={hidden} {...dataAttrs}>{content}</a>;
   }
 
+  // 🔘 button: aria mode is type="button" so a disabled CTA can never submit, even without JS
   return (
     <button
-      id={id}
-      type={htmlType}
-      className={classNames}
-      style={style}
-      hidden={hidden}
-      disabled={disabled}
+      id={id} // 🆔
+      type={mode === 'aria' ? 'button' : htmlType} // 🧾
+      className={classNames} // 🏷️
+      style={style} // 🎨
+      hidden={hidden} // 🙈
+      disabled={mode === 'native'} // 🚫
+      aria-disabled={mode === 'aria' ? true : undefined} // 🚦
       {...dataAttrs}
     >
       {content}
@@ -140,5 +156,6 @@ const AbButton = ({
   );
 };
 
+// 📦 exports
 export default AbButton;
 export { AbButton };

package/server/ab-button/styles.module.css

@@ -2,7 +2,32 @@
 * @license MIT
 * ~~~~~~~~~~~~
 * ab-nextjs-components
-* Plain CSS modules — no Tailwind Tailwind apply (Turbopack-safe).
+* ~~~~~~~~~~~~ 
+* 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: styles.module.css
+* @file: server/ab-button/styles.module.css
+* @type: CSS
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -11,6 +36,7 @@
 * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
+
 .abButton {
   position: relative;
   display: inline-flex;
@@ -61,3 +87,55 @@
 
 .hidden { display: none !important; }
 .invisible { visibility: hidden; }
+
+/* ===== G22: start/end icons, badge, aria-disabled ===== */
+
+/* 🖼️ icon slots (any ReactNode, e.g. <AbIcon name="github" />) */
+.abButtonSlot {
+  display: inline-flex; /* 📐 align with label */
+  flex: none; /* 🚫 never squash */
+  width: 1.25em; /* 📏 icon box */
+  height: 1.25em; /* 📏 */
+  align-items: center; /* ↕️ */
+  justify-content: center; /* ↔️ */
+}
+
+/* 🏷️ "Coming soon" style badge inside the button */
+.abButtonBadge {
+  display: inline-flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  padding: 0.125rem 0.5rem; /* 🧱 */
+  border-radius: 9999px; /* 💊 */
+  font-size: 0.75rem; /* 🔡 small */
+  font-weight: 600; /* 💪 */
+  line-height: 1.2; /* 📏 */
+  white-space: nowrap; /* 🚫 no wrap */
+  /* ⚪ neutral tone (default) */
+  color: var(--ab-color-on-surface-variant, currentColor);
+  background: var(--ab-color-surface-variant, rgb(0 0 0 / 0.06));
+}
+
+/* 🥉 accent tone: small text → the AA bronze text token (theme 0.3.1) */
+.abButtonBadge[data-tone="accent"] {
+  color: var(--ab-color-bronze-text, #8A6440); /* ♿ 5.02:1 on #fff8f3 */
+  background: color-mix(in srgb, var(--ab-color-bronze, #A67C52) 14%, transparent); /* 🎨 soft wash */
+}
+
+/* 🚦 aria-disabled: looks disabled, stays focusable (no pointer-events:none so tooltips/focus still work) */
+.abButton[aria-disabled="true"] {
+  cursor: not-allowed; /* 🚫 */
+  opacity: 0.6; /* 🌫️ */
+}
+
+/* 🙈 visually hidden, still announced */
+.srOnly {
+  position: absolute; /* 📌 */
+  width: 1px; /* 📏 */
+  height: 1px; /* 📏 */
+  padding: 0; /* 🧹 */
+  margin: -1px; /* 🧹 */
+  overflow: hidden; /* ✂️ */
+  clip: rect(0 0 0 0); /* ✂️ */
+  white-space: nowrap; /* 🚫 */
+  border: 0; /* 🧹 */
+}