ab-nextjs-components 0.1.8 → 0.1.10

package/ab-carousel/styles.module.css

@@ -0,0 +1,206 @@
+/*
+* @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: AbCarousel - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: ab-carousel/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 🎛️ Tunables (override on the carousel or any ancestor):
+*   --ab-carousel-duration   slide step (default 280ms)  → --ab-slide-step-duration (ab-nextjs-animations)
+*   --ab-carousel-ease       easing (default cubic-bezier(.2,.8,.2,1)) → --ab-slide-step-easing
+*   --ab-carousel-shift      enter / exit offset (default 24px) → --ab-slide-step-distance
+*   🎬 all motion comes from ab-nextjs-animations (slide-step + motion); nothing animates in this file
+*   --ab-carousel-nav-size   prev / next diameter (default 40px; 44px on mobile)
+*   --ab-carousel-dot-color  inactive dot colour
+*   --ab-carousel-accent     active dot + filled button colour (default --ab-primary)
+*/
+
+/* 🎠 region */
+.carousel {
+  position: relative; /* 📌 anchor for the hidden live region */
+  /* 🎛️ tokens handed to ab-nextjs-animations (slide-step + motion) */
+  --ab-slide-step-duration: var(--ab-carousel-duration, 280ms); /* ⏱️ */
+  --ab-slide-step-easing: var(--ab-carousel-ease, cubic-bezier(0.2, 0.8, 0.2, 1)); /* 📈 */
+  --ab-slide-step-distance: var(--ab-carousel-shift, 24px); /* ↔️ */
+  --ab-slide-step-flip: 1; /* 🌍 LTR */
+  --_accent: var(--ab-carousel-accent, var(--ab-primary, #a67c52)); /* 🟤 bronze */
+}
+
+/* 🌍 RTL: mirror the slide offsets */
+.carousel[data-dir='rtl'] {
+  --ab-slide-step-flip: -1; /* 🌍 slide steps mirror */
+}
+
+/* 🎞️ track: every slide shares one grid cell → height = tallest slide (CLS 0) */
+.track {
+  display: grid; /* 🧱 */
+  touch-action: pan-y; /* 👆 vertical scroll stays native; horizontal moves reach useAbSwipe */
+}
+
+/* 🖼️ slide (inactive by default; enter / leave motion = .ab-slide-step-in / -out from ab-nextjs-animations) */
+.slide {
+  grid-area: 1 / 1; /* 🧱 stacked */
+  min-width: 0; /* 📏 allow long words to wrap */
+  opacity: 0; /* 🙈 */
+  visibility: hidden; /* 🙈 not focusable, not read (also before hydration) */
+  pointer-events: none; /* 🚫 */
+}
+
+/* ✅ active slide */
+.slide[data-position='active'] {
+  opacity: 1; /* 👀 */
+  visibility: visible; /* 👀 */
+  pointer-events: auto; /* 🖱️ */
+}
+
+/* ⏮️⏭️ round prev / next buttons */
+.nav {
+  display: inline-flex; /* 🎯 center the icon */
+  align-items: center;
+  justify-content: center;
+  width: var(--ab-carousel-nav-size, 40px); /* 📏 ≥ 40 on laptop */
+  height: var(--ab-carousel-nav-size, 40px);
+  padding: 0;
+  margin: 0;
+  border-radius: 9999px; /* ⚪ */
+  border: 1px solid var(--ab-outline, color-mix(in srgb, currentColor 24%, transparent)); /* 🖊️ */
+  background: transparent;
+  color: var(--ab-on-surface, currentColor);
+  cursor: pointer;
+  /* 🎨 hover / 🤏 press motion: .ab-motion-interactive + .ab-motion-press (ab-nextjs-animations) */
+}
+.nav:hover {
+  background-color: color-mix(in srgb, currentColor 8%, transparent); /* 🌫️ */
+}
+.nav[data-variant='filled'] {
+  border-color: transparent;
+  background: var(--_accent); /* 🟤 primary-filled next */
+  color: var(--ab-on-primary, #fff);
+}
+.nav[data-variant='filled']:hover {
+  background: color-mix(in srgb, var(--_accent) 88%, #000);
+}
+.nav[aria-disabled='true'] {
+  opacity: 0.4; /* 🚦 edge */
+  cursor: not-allowed;
+}
+
+/* 🎯 visible focus ring (theme focus-ring token when G18 lands) */
+.nav:focus-visible,
+.dot:focus-visible {
+  outline: 2px solid var(--ab-focus-ring, var(--_accent));
+  outline-offset: 2px;
+}
+
+/* ➡️ the arrow icon (mirrors in RTL) */
+.navIcon {
+  flex: none; /* 🚫 squash (stroke comes from AbIcon weight 300 = 1.5) */
+}
+.carousel[data-dir='rtl'] .navIcon {
+  transform: scaleX(-1); /* 🌍 */
+}
+
+/* 📱 mobile: 44×44 targets (brief §5) */
+@media (max-width: 639px) {
+  .nav {
+    width: var(--ab-carousel-nav-size, 44px);
+    height: var(--ab-carousel-nav-size, 44px);
+  }
+}
+
+/* 🔘 dots row */
+.dots {
+  display: inline-flex;
+  align-items: center;
+  gap: 0;
+}
+
+/* 🔘 one dot = a 24×24 button (WCAG 2.5.8) holding an 8px mark */
+.dot {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 24px;
+  height: 24px;
+  padding: 0 4px;
+  margin: 0;
+  border: 0;
+  border-radius: 9999px;
+  background: transparent;
+  cursor: pointer;
+}
+
+/* ⚪ the visible mark */
+.dotMark {
+  display: block;
+  width: 8px;
+  height: 8px;
+  border-radius: 9999px;
+  background: var(--ab-carousel-dot-color, color-mix(in srgb, currentColor 28%, transparent));
+  /* 📏 8 → 24px motion: .ab-motion-size (ab-nextjs-animations) */
+}
+
+/* ✅ active = long bronze pill */
+.dot[data-active='true'] .dotMark {
+  width: 24px;
+  background: var(--_accent);
+}
+
+/* ♿ reduced motion (OS or reducedMotion prop) is handled by ab-nextjs-animations via data-ab-reduced-motion */
+
+/* 🔢 counter "02 / 09" */
+.counter {
+  font-family: var(--ab-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-size: 0.8125rem;
+  letter-spacing: 0.04em;
+  color: var(--ab-on-surface-variant, color-mix(in srgb, currentColor 64%, transparent));
+}
+.counter b {
+  font-weight: 700;
+  color: var(--ab-on-surface, currentColor);
+}
+
+/* 🙈 visually hidden but announced */
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}

package/ab-chip/index.tsx

@@ -0,0 +1,75 @@
+/* 
+* @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: AbChip - Server (G36)
+* @file: ab-chip/index.tsx
+* @type: Server component (static, no JS)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <ul><AbChip as="li" dot>Tokens</AbChip><AbChip as="li">Light &amp; dark</AbChip></ul>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚛️ types
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+// 🧵 classes
+import clsx from 'clsx';
+// 🎨 styles
+import styles from './styles.module.css';
+
+// 🎨 dot colours
+export type AbChipDot = 'sage' | 'bronze';
+
+// ⚙️ props
+export interface AbChipProps {
+  children: ReactNode; // 🏷️ text
+  dot?: boolean | AbChipDot; // 🟢 leading dot (true = bronze)
+  icon?: ReactNode; // 🖼️ leading icon (decorative)
+  as?: 'span' | 'li'; // 🧱 'li' inside a <ul> for lists of chips
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
+}
+
+/** 🏷️ Static chip: plain text, never interactive (use AbButton for actions). */
+export function AbChip({ children, dot, icon, as: Tag = 'span', className, style }: AbChipProps): ReactElement {
+  const tone = dot === true ? 'bronze' : dot || undefined; // 🎨 resolve dot colour
+  return (
+    <Tag className={clsx('AbChip', styles.chip, className)} style={style} data-ab-part="chip">
+      {tone ? <span className={styles.dot} data-tone={tone} aria-hidden="true" /> : null /* 🟢 decorative */}
+      {icon ? <span className={styles.icon} aria-hidden="true">{icon}</span> : null /* 🖼️ decorative */}
+      <span>{children}</span>
+    </Tag>
+  );
+}
+
+// 📦 default export
+export default AbChip;

package/ab-chip/styles.module.css

@@ -0,0 +1,87 @@
+/* 
+* @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: AbChip / AbPill - Styles
+* @file: ab-chip/styles.module.css
+* @type: CSS module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 🏷️ chip */
+.chip {
+  display: inline-flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  gap: 0.375rem; /* 🧱 */
+  padding: 0.25rem 0.75rem; /* 🧱 */
+  border-radius: 9999px; /* 💊 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface-container, transparent); /* 🎨 */
+  color: var(--ab-color-on-surface, currentColor); /* 🎨 */
+  font-size: 0.875rem; /* 🔡 */
+  line-height: 1.4; /* 📏 */
+  white-space: nowrap; /* 🚫 wrap */
+  list-style: none; /* 🧹 when as="li" */
+}
+
+/* 💊 pill (eyebrow): small text → AA bronze text token in light mode */
+.pill {
+  composes: chip; /* ♻️ */
+  color: var(--ab-color-bronze-text, #8A6440); /* ♿ 5.02:1 on #fff8f3 */
+  border-color: color-mix(in srgb, var(--ab-color-bronze, #A67C52) 35%, transparent); /* 🖊️ */
+  background: color-mix(in srgb, var(--ab-color-bronze, #A67C52) 8%, transparent); /* 🎨 */
+  font-size: 0.8125rem; /* 🔡 */
+  font-weight: 600; /* 💪 */
+}
+
+/* ⌨️ mono eyebrow (package names like ab-nextjs-core) */
+.mono {
+  font-family: var(--ab-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); /* 🔤 */
+}
+
+/* 🟢 dot */
+.dot {
+  flex: none; /* 🚫 squash */
+  width: 0.5rem; /* 📏 */
+  height: 0.5rem; /* 📏 */
+  border-radius: 50%; /* ⚪ */
+  background: var(--ab-color-bronze, #A67C52); /* 🥉 default */
+}
+.dot[data-tone='sage'] {
+  background: var(--ab-color-sage, #7C9A7E); /* 🌿 "live" / "free forever" */
+}
+
+/* 🖼️ icon box */
+.icon {
+  display: inline-flex; /* 📐 */
+  width: 1em; /* 📏 */
+  height: 1em; /* 📏 */
+}

package/ab-collapsible/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: AbCollapsible - Client (port of lyd-collapsible)
 * @file: ab-collapsible/index.tsx
+* @type: TypeScript (React)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 'use client';
 
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
@@ -17,6 +44,8 @@ import { useState } 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-*
 
 export interface AbCollapsibleProps {
   href?: string | null;
@@ -137,7 +166,7 @@ const AbCollapsible = ({
         </button>
       ) : null}
       <span
-        className={clsx('material-symbols-rounded', styles.abCollapsibleExpand, open && styles.expanded)}
+        className={clsx('material-symbols-rounded', styles.abCollapsibleExpand, AB_MOTION.transform, open && styles.expanded)} // 🔄 rotation tween from ab-nextjs-animations
         aria-hidden
       >
         {expandIcon}

package/ab-collapsible/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-collapsible - styles
+* @file: ab-collapsible/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+
 .abCollapsible {
   display: flex;
   flex-direction: column;
@@ -79,7 +118,7 @@
 }
 
 .abCollapsibleExpand {
-  transition: transform 0.2s ease;
+  /* 🔄 rotation tween = .ab-motion-transform (ab-nextjs-animations) */
 }
 
 .abCollapsibleExpand.expanded {

package/ab-flow-diagram/helpers.ts

@@ -0,0 +1,77 @@
+/* 
+* @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: AbFlowDiagram - Helpers (G38)
+* @file: ab-flow-diagram/helpers.ts
+* @type: TypeScript (pure, server-safe)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚛️ ReactNode for node icons
+import type { ReactNode } from 'react';
+
+// 🔵 a node (x/y in 0–100 scene units)
+export interface AbFlowNode {
+  id: string; // 🆔
+  label: string; // 🏷️ visible text (package/component names are not translated)
+  x: number; // ↔️ 0–100
+  y: number; // ↕️ 0–100
+  icon?: ReactNode; // 🖼️ e.g. <AbIcon name="widgets" />
+  tone?: 'hub' | 'node' | 'accent'; // 🎨 hub = centre logo
+}
+
+// 〰️ a wire
+export interface AbFlowEdge {
+  from: string; // 🔵 node id
+  to: string; // 🔵 node id
+  curve?: number; // 🌙 -1…1 bend (0 = straight)
+}
+
+// ✂️ clamp into the scene
+const clamp = (v: number) => Math.min(100, Math.max(0, v));
+
+/**
+ * @name getAbFlowEdgePath
+ * @description 〰️ SVG path between two nodes: straight, or a quadratic curve bent sideways.
+ */
+export function getAbFlowEdgePath(a: Pick<AbFlowNode, 'x' | 'y'>, b: Pick<AbFlowNode, 'x' | 'y'>, curve = 0): string {
+  const [x1, y1, x2, y2] = [clamp(a.x), clamp(a.y), clamp(b.x), clamp(b.y)]; // 📍
+  if (!curve) return `M ${x1} ${y1} L ${x2} ${y2}`; // ➖ straight
+  const mx = (x1 + x2) / 2; // 🎯 midpoint
+  const my = (y1 + y2) / 2; // 🎯
+  const dx = x2 - x1; // ↔️
+  const dy = y2 - y1; // ↕️
+  const k = Math.max(-1, Math.min(1, curve)) * 0.5; // 🌙 bend strength
+  const cx = mx - dy * k; // ⤴️ perpendicular offset
+  const cy = my + dx * k; // ⤵️
+  return `M ${x1} ${y1} Q ${+cx.toFixed(2)} ${+cy.toFixed(2)} ${x2} ${y2}`; // 〰️
+}