ab-nextjs-components 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 0.1.10 — 2026-10-14
+
+* **Motion comes from ab-nextjs-animations (>= 0.2.4, now a required peer):** no component CSS declares its own `transition`, `animation` or `@keyframes` any more. Each component imports the package stylesheet it needs:
+  * AbCarousel: `slide-step` (direction-aware enter / leave via `data-ab-direction`) + `motion` (buttons, dots)
+  * AbFlowDiagram: `wire` (`--ab-wire-*` tokens; `data-ab-paused`; 3 loops on phones unless `loops` is set)
+  * AbThemeToggle, AbSearchbar, AbSplash fade: `motion` colours
+  * AbIconButton: `motion` (`expands` → `ab-motion-lift`, `shrinks` → `ab-motion-press`)
+  * AbProgressChips: `motion` size
+  * AbLinearProgress: `motion` transform + `progress-sweep`
+  * AbCollapsible, AbBrand: `motion` transform
+  * AbLikeButton / AbSearchbar spinners: `spin`
+  * Reduced motion (OS, or `reducedMotion="always"` via `data-ab-reduced-motion`) is handled by the package
+* **AbCarousel:** context gains `direction` + `previousIndex`; `--ab-carousel-duration` / `-ease` / `-shift` map onto `--ab-slide-step-*`; the old positional slide offsets are gone
+* **Peers:** `ab-nextjs-icons` and `ab-nextjs-animations` are no longer optional. All four Welcome peers (and devDependencies) use caret ranges: `ab-nextjs-hooks ^0.1.6`, `ab-nextjs-theme ^0.3.1`, `ab-nextjs-icons ^0.2.3`, `ab-nextjs-animations ^0.2.4`
+* **Motion exceptions (named, test-guarded):** the dialog list-item transition (`css/dialog.css`) and the self-animating spinner SVGs stay local
+* **Lockfile:** refreshed against the published hooks 0.1.6, theme 0.3.1, icons 0.2.3 and animations 0.2.4 (`pnpm install --frozen-lockfile` verified on a fresh `node_modules`). `pnpm-workspace.yaml` exempts exactly the five Welcome releases (fonts 0.2.5 included) from pnpm 11's 1-day `minimumReleaseAge`, and that block should be removed once they are a day old
+
+* **AbCarousel (G31):** new subpath `ab-nextjs-components/ab-carousel` (+ server-safe `ab-carousel/helpers`). Compound parts `AbCarousel`, `AbCarouselTrack`, `AbCarouselSlide`, `AbCarouselPrev`, `AbCarouselNext`, `AbCarouselDots`, `AbCarouselCounter` + `useAbCarousel()`. APG carousel semantics (`aria-roledescription` carousel/slide, "n of total" labels, polite live region, inactive slides `inert` + `aria-hidden` after hydration), RTL-aware ←/→ + Home/End scoped to the region, swipe via `useAbSwipe`, reduced motion via `useAbReducedMotion` + CSS, controlled / uncontrolled, i18n labels on every control, `AB_CAROUSEL_NOSCRIPT_CSS` for the no-JS stack
+* **AbIconButton (G6):** `aria-label` + `title` now sit on the interactive element (never the wrapper span); new `label` prop (falls back to `title`); the `href` variant is named and no longer has `role="button"`; the ligature glyph is `aria-hidden`; disabled links leave the tab order; loading sets `aria-busy`
+* **AbButton (G22):** `startIcon` / `endIcon`, `badge` + `badgeTone` (e.g. "Coming soon"), `disabledReason` (visually hidden text appended to the accessible name), `focusableWhenDisabled`; with a badge / reason the button uses `aria-disabled` (stays focusable, clicks guarded) instead of native `disabled`; disabled links render as `span role="link" aria-disabled`; links no longer get `role="button"`; server twin matches
+* **AbThemeToggle (G34, new, `ab-nextjs-components/ab-theme-toggle`):** light / dark / system radiogroup (roving focus, RTL arrows, icon-only variant, i18n labels), driven by `useAbThemeMode()`; `getNextAbThemeMode` helper
+* **AbChip / AbPill (G36, new, server components):** `ab-chip`, `ab-pill`
+* **AbInstallSnippet (G35, new):** pnpm / npm / yarn / bun tabs (APG tablist), choice shared via `useAbLocalStorage`, copy button with polite status, `data-ab-swipe-ignore`; `getAbInstallCommand` helper
+* **AbLocaleSwitcher (G7, new):** menu button + `menuitemradio`, typeahead, `onSelect` or `getHref` (+ `hrefLang`)
+* **AbIcon (G2, new, `ab-nextjs-components/ab-icon`):** AbIcons as inline SVG; client twin resolves `svg` prop → `registerAbIcons` registry → Material Symbols font (never imports the full map); server twin renders any icon; weights 100–700 map to the icons package stroke table; 8 built-ins (arrows, theme, language, copy / check) imported per icon from `ab-nextjs-icons/ab-icons/icons/*` (needs icons >= 0.2.3)
+* **AbCarousel:** prev / next arrows now render through AbIcon (weight 300); `--ab-carousel-icon-stroke` removed (unreleased)
+* **AbFlowDiagram (G38, new, server component):** `figure role="img"` scenes, CSS-only draw + pulse, paused while inactive, 3 loops on mobile, reduced motion shows the poster frame; `getAbFlowEdgePath` helper
+* Dev: `happy-dom` + `@testing-library/react` for DOM tests
+
+## 0.1.9 — 2026-10-14
+
+- **AbLogo:** `wordmark` prop (`true` → "Elements", or any string) renders a mark + Quicksand Bold lockup (`font-quicksand-bold` from ab-nextjs-fonts); `color` prop (`--ab-logo-color`); light / dark (`html.dark`)
+- **AbLogo fix:** `naked` with no `src` now masks with the shipped Ab mark (via `--app-logo-url` fallback) instead of a bronze square when the chrome CSS isn't loaded
+- **AbSplash (new, `ab-nextjs-components/ab-splash`):** brand overlay + `abSplashGateScript` / `buildAbSplashGateScript({ locales, defaultLocale })`; root-path RegExp built from locales minus the default and JSON-injected; skips `navigator.webdriver` / bot UAs; standalone via `matchMedia` OR `navigator.standalone`; each storage get/set in its own try (failed get = seen); `data-ab-splash` set last; page behind is `inert` while shown; track `min(18rem, 28vw)`
+- **CSP:** `ab-nextjs-components/ab-splash/csp` → `getAbSplashGateSha256(script)`, `buildAbSplashGate(options)`, `AB_SPLASH_GATE_SHA256`
+- **AbLinearProgress (new here, `ab-nextjs-components/ab-linear-progress`):** ported from the reviewed core work — determinate / indeterminate, `color`, reduced motion, dark, RTL sweep, empty `aria-label` dropped; shipped CSS module. AbSplash uses it, so **no `ab-nextjs-core` peer is needed**
+- **CSP (P1):** `ab-nextjs-components/ab-splash/csp` now ships compiled `csp.mjs` + `csp.d.ts` (Node-loadable from `next.config.*`); `build:csp` script, `check:publish` / `prepublishOnly` fail when it's stale
+- **AbSplash:** unmount removes `data-ab-splash` + `inert`; scroll lock gets the same 1.2 s CSS failsafe; surfaces `#FFF8F3` / `#1A1310` (mocks)
+- **Tooling:** `esbuild ^0.28.2` is now an explicit devDependency (direct in `pnpm-lock.yaml`; frozen install verified)
+- **AbSplash:** StrictMode-safe teardown (`scheduleAbSplashFinish` / `cancelAbSplashFinish`); overflow failsafe verified in Chromium + WebKit
+- **Tooling:** `typecheck` script, `types/css.d.ts`, vitest automatic JSX, `scripts/build-demo.mjs`
+
 ## 0.1.8 — 2026-10-05
 
 - **Chrome styles:** dialog, toast, logo (`span.app-logo`), spinner, and empty-state doodle CSS + SVG assets now ship here via `@import "ab-nextjs-components/styles.css"` (import after `ab-nextjs-theme/styles.css`)

package/ab-brand/index.tsx

@@ -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: AbBrand - Client (port of lyd-brand)
 * @file: ab-brand/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';
@@ -17,6 +44,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;
@@ -71,7 +100,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/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: 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/ab-button/helpers.ts

@@ -0,0 +1,90 @@
+/* 
+* @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: AbButton - Shared helpers (G22)
+* @file: ab-button/helpers.ts
+* @type: TypeScript (pure, server-safe)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🎨 visual types shared by the client + server twins
+export type AbButtonType = 'contained' | 'outlined' | 'text';
+// 🎨 colour roles
+export type AbButtonColor = 'primary' | 'secondary' | 'tertiary' | 'white' | 'black';
+// 🏷️ badge tones (G22): neutral grey or bronze accent
+export type AbButtonBadgeTone = 'neutral' | 'accent';
+
+/**
+ * 🚦 How a button is disabled:
+ *  - 'none'   → interactive
+ *  - 'native' → `disabled` attribute (pre-G22 behaviour, skipped by Tab)
+ *  - 'aria'   → `aria-disabled="true"`: stays focusable so screen-reader users can
+ *               discover it and hear *why* (badge / reason); activation is suppressed
+ */
+export type AbButtonDisabledMode = 'none' | 'native' | 'aria';
+
+// ⚙️ inputs that decide the mode
+export interface AbButtonDisabledInput {
+  disabled?: boolean; // 🚫
+  isLoading?: boolean; // ⏳ loading also blocks activation
+  badge?: unknown; // 🏷️ a visible "Coming soon"-style badge
+  disabledReason?: string; // 💬 SR-only reason
+  focusableWhenDisabled?: boolean; // ⌨️ explicit override
+}
+
+/**
+ * @name getAbButtonDisabledMode
+ * @description 🚦 Pick the disabled mode. Explaining a disabled button (badge or
+ *   reason) only helps if it can be focused, so those switch to 'aria' by default.
+ */
+export function getAbButtonDisabledMode(input: AbButtonDisabledInput): AbButtonDisabledMode {
+  const blocked = Boolean(input.disabled || input.isLoading); // 🚫 anything blocking?
+  if (!blocked) return 'none'; // ✅ interactive
+  // 🧭 explicit choice wins; otherwise explainable buttons stay focusable
+  const focusable = input.focusableWhenDisabled ?? Boolean(input.disabledReason || (input.disabled && hasBadge(input.badge)));
+  return focusable ? 'aria' : 'native'; // 🎯
+}
+
+// 🔍 does the badge render anything?
+function hasBadge(badge: unknown): boolean {
+  return badge !== undefined && badge !== null && badge !== false && badge !== ''; // 🧮
+}
+
+/**
+ * @name getAbButtonSrReason
+ * @description 💬 Text appended (visually hidden) to the accessible name when blocked:
+ *   explicit `disabledReason`, else nothing (a visible badge is already in the name).
+ */
+export function getAbButtonSrReason(input: AbButtonDisabledInput): string | undefined {
+  if (!(input.disabled || input.isLoading)) return undefined; // ✅ nothing to explain
+  return input.disabledReason?.trim() || undefined; // 💬
+}

package/ab-button/index.tsx

@@ -22,137 +22,213 @@
 * 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 - Client (port of lyd-button)
 * @file: ab-button/index.tsx
+* @type: Component (client) — G22 disabled + badge + start/end icons
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <AbButton type="outlined" label="Continue with GitHub" startIcon={<AbIcon name="github" />} disabled badge="Coming soon" />
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
 'use client';
 
-import type { CSSProperties, MouseEvent, ReactNode } from 'react';
+// ⚛️ React types + forwardRef
+import type { CSSProperties, KeyboardEvent, MouseEvent, ReactNode, Ref } from 'react';
 import { forwardRef } from 'react';
+// 🧵 class joiner
 import clsx from 'clsx';
+// 🎨 styles
 import styles from './styles.module.css';
+// 🧮 shared (server-safe) rules
+import {
+  getAbButtonDisabledMode,
+  getAbButtonSrReason,
+  type AbButtonBadgeTone,
+  type AbButtonColor,
+  type AbButtonType,
+} from './helpers';
 
-export type AbButtonType = 'contained' | 'outlined' | 'text';
-export type AbButtonColor = 'primary' | 'secondary' | 'tertiary' | 'white' | 'black';
+// 📦 re-export the shared types (pre-G22 import paths keep working)
+export type { AbButtonBadgeTone, AbButtonColor, AbButtonType, AbButtonDisabledMode } from './helpers';
 
+// ⚙️ props
 export interface AbButtonProps {
-  id?: string;
-  type?: AbButtonType;
-  htmlType?: 'button' | 'submit' | 'reset';
-  className?: string;
-  spinnerClassName?: string;
-  hidden?: boolean;
-  style?: CSSProperties;
-  iconStyle?: CSSProperties;
-  rounded?: boolean;
-  raised?: boolean;
-  shrinks?: boolean;
-  expands?: boolean;
-  withIcon?: boolean;
-  disabled?: boolean;
-  isLoading?: boolean;
-  iconPosition?: 'left' | 'right';
-  label: string;
-  icon?: string;
-  color?: AbButtonColor;
-  href?: string;
-  children?: ReactNode;
-  onClick?: (event: MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void;
+  id?: string; // 🆔
+  type?: AbButtonType; // 🎨 contained / outlined / text
+  htmlType?: 'button' | 'submit' | 'reset'; // 🧾
+  className?: string; // 🏷️
+  spinnerClassName?: string; // ⏳ spinner class
+  hidden?: boolean; // 🙈
+  style?: CSSProperties; // 🎨
+  iconStyle?: CSSProperties; // 🎨 Material icon style
+  rounded?: boolean; // 💊
+  raised?: boolean; // 🏔️
+  shrinks?: boolean; // 🤏
+  expands?: boolean; // 🔍
+  withIcon?: boolean; // 🔣 legacy Material icon on/off
+  disabled?: boolean; // 🚫
+  isLoading?: boolean; // ⏳
+  iconPosition?: 'left' | 'right'; // ↔️ legacy icon side
+  label: string; // 🏷️ text (also the accessible name)
+  icon?: string; // 🔣 legacy Material ligature
+  color?: AbButtonColor; // 🎨
+  href?: string; // 🔗 link mode
+  children?: ReactNode; // 🧩 replaces label visually
+  onClick?: (event: MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void; // 🖱️
+  // ===== G22 =====
+  startIcon?: ReactNode; // 🖼️ NEW: any node before the label (e.g. GitHub mark via AbIcon)
+  endIcon?: ReactNode; // 🖼️ NEW: any node after the label (e.g. arrow_forward)
+  badge?: ReactNode; // 🏷️ NEW: visible badge, e.g. "Coming soon"; part of the accessible name
+  badgeTone?: AbButtonBadgeTone; // 🎨 NEW: 'neutral' (default) | 'accent'
+  disabledReason?: string; // 💬 NEW: SR-only reason, appended to the name while blocked
+  focusableWhenDisabled?: boolean; // ⌨️ NEW: force aria-disabled (true) or native disabled (false)
 }
 
 const AbButton = forwardRef<HTMLButtonElement | HTMLAnchorElement, AbButtonProps>(function AbButton(props, ref) {
+  // 🧩 props + defaults
   const {
-    id,
-    type = 'contained',
-    htmlType = 'button',
-    className,
-    spinnerClassName,
-    hidden = false,
-    style,
-    iconStyle,
-    rounded = true,
-    raised = false,
-    shrinks = false,
-    expands = false,
-    withIcon = false,
-    disabled = false,
-    isLoading = false,
-    iconPosition = 'left',
-    label,
-    icon,
-    color = 'primary',
-    href,
-    children,
-    onClick,
+    id, // 🆔
+    type = 'contained', // 🎨
+    htmlType = 'button', // 🧾
+    className, // 🏷️
+    spinnerClassName, // ⏳
+    hidden = false, // 🙈
+    style, // 🎨
+    iconStyle, // 🎨
+    rounded = true, // 💊
+    raised = false, // 🏔️
+    shrinks = false, // 🤏
+    expands = false, // 🔍
+    withIcon = false, // 🔣
+    disabled = false, // 🚫
+    isLoading = false, // ⏳
+    iconPosition = 'left', // ↔️
+    label, // 🏷️
+    icon, // 🔣
+    color = 'primary', // 🎨
+    href, // 🔗
+    children, // 🧩
+    onClick, // 🖱️
+    startIcon, // 🖼️
+    endIcon, // 🖼️
+    badge, // 🏷️
+    badgeTone = 'neutral', // 🎨
+    disabledReason, // 💬
+    focusableWhenDisabled, // ⌨️
   } = props;
 
+  // 🚦 how are we disabled? (shared with the server twin)
+  const mode = getAbButtonDisabledMode({ disabled, isLoading, badge, disabledReason, focusableWhenDisabled });
+  // 💬 hidden reason appended to the name
+  const srReason = getAbButtonSrReason({ disabled, isLoading, disabledReason });
+  // 🚫 any kind of blocked?
+  const blocked = mode !== 'none';
+
+  // 🏷️ classes: pointer-events:none only for native mode (aria mode must stay focusable/hoverable)
   const classNames = clsx(
-    'AbButton',
-    styles.abButton,
-    className,
-    rounded && styles.abButtonRounded,
-    type === 'contained' && styles.isContained,
-    (disabled || isLoading) && styles.isDisabled,
+    'AbButton', // 🏷️ public hook
+    styles.abButton, // 🎨
+    className, // 🏷️
+    rounded && styles.abButtonRounded, // 💊
+    type === 'contained' && styles.isContained, // 🎨
+    mode === 'native' && styles.isDisabled, // 🚫
   );
 
+  // 🗂️ data attributes for styling/tests
   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 Material icon (decorative)
+  const legacyIcon = withIcon && icon
+    ? <span className={clsx('material-symbols-rounded', 'icon', styles.abButtonIcon)} style={iconStyle} aria-hidden="true">{icon}</span>
+    : null;
+
+  // 🧱 inner content
   const content = (
     <>
-      {withIcon && iconPosition === 'left' && icon ? (
-        <span className={clsx('material-symbols-rounded', 'icon', styles.abButtonIcon)} style={iconStyle}>{icon}</span>
-      ) : null}
-      <span className={clsx(styles.abButtonSpinnerSlot, !isLoading && styles.hidden)}>
+      {iconPosition === 'left' ? legacyIcon : null /* 🔣 legacy left */}
+      {startIcon ? <span className={styles.abButtonSlot} aria-hidden="true">{startIcon}</span> : null /* 🖼️ decorative */}
+      <span className={clsx(styles.abButtonSpinnerSlot, !isLoading && styles.hidden)} aria-hidden="true">
         <span className={clsx('spinner', 'dot-3', styles.abButtonSpinner, spinnerClassName)} />
       </span>
       <span className={clsx(isLoading && styles.invisible)}>{children ?? label}</span>
-      {withIcon && iconPosition === 'right' && icon ? (
-        <span className={clsx('material-symbols-rounded', 'icon', styles.abButtonIcon)} style={iconStyle}>{icon}</span>
+      {badge ? (
+        <>
+          <span className={styles.srOnly}>, </span>{/* 🗣️ pause: "Continue with GitHub, Coming soon" */}
+          <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 /* 💬 hidden reason */}
+      {endIcon ? <span className={styles.abButtonSlot} aria-hidden="true">{endIcon}</span> : null /* 🖼️ */}
+      {iconPosition === 'right' ? legacyIcon : null /* 🔣 legacy right */}
     </>
   );
 
+  // 🛑 aria mode: swallow activation (mouse, Enter/Space, form submit)
+  const guardClick = (event: MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => {
+    if (blocked) { event.preventDefault(); return; } // 🚫 no submit / navigation / handler
+    onClick?.(event); // ✅
+  };
+
+  // 🔗 link mode
   if (href) {
+    // 🚫 a blocked link has no target: render a non-navigating span with role=link
+    if (blocked) {
+      return (
+        <span
+          ref={ref as Ref<HTMLAnchorElement> as unknown as Ref<HTMLSpanElement>} // 🔗
+          id={id} // 🆔
+          role="link" // ♿ still announced as a link
+          aria-disabled="true" // 🚦
+          tabIndex={mode === 'aria' ? 0 : -1} // ⌨️ focusable only in aria mode
+          className={classNames} // 🏷️
+          style={style} // 🎨
+          hidden={hidden} // 🙈
+          onKeyDown={(e: KeyboardEvent<HTMLSpanElement>) => { if (e.key === 'Enter') e.preventDefault(); }} // 🚫
+          {...dataAttrs}
+        >
+          {content}
+        </span>
+      );
+    }
+    // ✅ live link (no role=button: it navigates, so it is a link)
     return (
-      <a
-        ref={ref as React.Ref<HTMLAnchorElement>}
-        id={id}
-        href={disabled ? undefined : href}
-        role="button"
-        className={classNames}
-        style={style}
-        hidden={hidden}
-        aria-disabled={disabled || isLoading}
-        onClick={onClick}
-        {...dataAttrs}
-      >
+      <a ref={ref as Ref<HTMLAnchorElement>} id={id} href={href} className={classNames} style={style} hidden={hidden} onClick={guardClick} {...dataAttrs}>
         {content}
       </a>
     );
   }
 
+  // 🔘 button mode
   return (
     <button
-      ref={ref as React.Ref<HTMLButtonElement>}
-      id={id}
-      type={htmlType}
-      className={classNames}
-      style={style}
-      hidden={hidden}
-      disabled={disabled || isLoading}
-      onClick={onClick}
+      ref={ref as Ref<HTMLButtonElement>} // 🔗
+      id={id} // 🆔
+      type={mode === 'aria' ? 'button' : htmlType} // 🧾 aria-disabled must never submit
+      className={classNames} // 🏷️
+      style={style} // 🎨
+      hidden={hidden} // 🙈
+      disabled={mode === 'native'} // 🚫 native mode
+      aria-disabled={mode === 'aria' ? true : undefined} // 🚦 aria mode
+      aria-busy={isLoading || undefined} // ⏳
+      onClick={guardClick} // 🛑 guarded
       {...dataAttrs}
     >
       {content}
@@ -160,5 +236,6 @@ const AbButton = forwardRef<HTMLButtonElement | HTMLAnchorElement, AbButtonProps
   );
 });
 
+// 📦 exports
 export default AbButton;
 export { AbButton };

package/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: 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; /* 🧹 */
+}