ab-nextjs-components 0.1.9 → 0.1.11

package/ab-flow-diagram/index.tsx

@@ -0,0 +1,152 @@
+/* 
+* @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 - Server (G38, Welcome illustrations)
+* @file: ab-flow-diagram/index.tsx
+* @type: Server component — animated node/wire scene, zero JS
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <AbFlowDiagram title="Live Playground" caption="ab-nextjs-core" alt={t('s02.illustrationAlt')} active={index === 1}
+*    -|>   nodes={[{ id: 'hub', label: 'AbProvider', x: 50, y: 50, tone: 'hub' }, { id: 'cfg', label: 'config', x: 20, y: 25 }]} edges={[{ from: 'cfg', to: 'hub' }]} />
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// ⚛️ types
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+// 🧵 classes
+import clsx from 'clsx';
+// 🧮 pure geometry
+import { getAbFlowEdgePath, type AbFlowEdge, type AbFlowNode } from './helpers';
+// 🎨 styles (all motion is CSS: draw-on, pulses, reduced motion, pause)
+import styles from './styles.module.css';
+// 🎬 wire draw-on + pulse come from ab-nextjs-animations (>= 0.2.4); this component only sets its tokens
+import { AB_WIRE_DRAW_CLASS, AB_WIRE_PULSE_CLASS } from 'ab-nextjs-animations/wire';
+import 'ab-nextjs-animations/wire/styles.css'; // 〰️ .ab-wire-draw / .ab-wire-pulse
+
+// 📦 re-export helpers + types
+export * from './helpers';
+
+// ⚙️ props
+export interface AbFlowDiagramProps {
+  nodes: readonly AbFlowNode[]; // 🔵 nodes in 0–100 coordinates
+  edges: readonly AbFlowEdge[]; // 〰️ wires between node ids
+  alt: string; // ♿ one-sentence description (Welcome.sNN.illustrationAlt)
+  title?: string; // 🏷️ card title, e.g. "Live Playground" (visual)
+  caption?: string; // 🏷️ PKG label, e.g. "ab-nextjs-core" (visual, mono)
+  live?: boolean | string; // 🟢 sage "live" dot; a string sets its visible text
+  active?: boolean; // ▶️ animate only while its slide is active (default true)
+  loops?: number | 'infinite'; // 🔁 pulse loops (default infinite; mobile CSS caps at 3)
+  variant?: 'full' | 'compact'; // 📐 compact = mobile 276px scene
+  posterAt?: number; // 🖼️ 0–1, frozen pulse position for reduced motion (mock MID = 0.45)
+  duration?: number; // ⏱️ pulse loop ms (default 2400)
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
+  children?: ReactNode; // 🧩 optional extra overlay (decorative)
+}
+
+// ✂️ 0–100 (same clamp as the wires, so a node and its wire end always agree)
+const pct = (v: number): number => Math.min(100, Math.max(0, v));
+
+/** 📍 node position + proportional anchor (CSS keeps every node inside the stage, see styles.module.css) */
+const nodeStyle = (n: AbFlowNode): CSSProperties =>
+  ({ left: `${pct(n.x)}%`, top: `${pct(n.y)}%`, '--ab-flow-node-x': String(pct(n.x)), '--ab-flow-node-y': String(pct(n.y)) }) as CSSProperties;
+
+/** 🎨 Live Playground scene: SVG wires + HTML nodes, CSS-only motion, one accessible image. */
+export function AbFlowDiagram(props: AbFlowDiagramProps): ReactElement {
+  // 🧩 props
+  const { nodes, edges, alt, title, caption, live = false, active = true, loops = 'infinite', variant = 'full', posterAt = 0.45, duration = 2400, className, style, children } = props;
+  // 🗺️ id → node
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  // 🎛️ ab-nextjs-animations wire tokens drive all timing
+  const vars = {
+    ...style, // 🎨
+    '--ab-wire-pulse-duration': `${duration}ms`, // ⏱️
+    // 🔁 explicit loops win; default = infinite on laptop, 3 on phones (set in styles.module.css)
+    ...(loops === 'infinite' ? {} : { '--ab-wire-pulse-iterations': String(loops) }),
+    '--ab-wire-poster': String(100 - Math.min(1, Math.max(0, posterAt)) * 100), // 🖼️ dashoffset at the poster frame
+  } as CSSProperties;
+
+  // 🏷️ is there a header row? (drives the header-safe stage inset in CSS)
+  const hasHeader = Boolean(title || live || caption);
+
+  return (
+    <figure
+      role="img" // ♿ the whole scene is ONE image
+      aria-label={alt} // 🗣️
+      className={clsx('AbFlowDiagram', styles.root, className)} // 🏷️
+      style={vars} // 🎛️
+      data-ab-part="flow-diagram" // 🗂️
+      data-active={String(active)} // ▶️ / ⏸️
+      data-ab-paused={String(!active)} // ⏸️ ab-nextjs-animations pauses wires on inactive slides
+      data-variant={variant} // 📐
+      data-ab-header={String(hasHeader)} // 🏷️ header-safe stage: nodes + wires start below the header
+    >
+      {/* 🏷️ card header (decorative: alt already describes it) */}
+      {hasHeader ? (
+        <div className={styles.header} aria-hidden="true">
+          {title ? <span className={styles.title}>{title}</span> : null}
+          {live ? <span className={styles.live}><span className={styles.liveDot} />{typeof live === 'string' ? live : null}</span> : null}
+          {caption ? <span className={styles.caption}>{caption}</span> : null}
+        </div>
+      ) : null}
+      {/* 〰️ wires layer */}
+      <svg className={styles.wires} viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true" focusable="false">
+        {edges.map((e, i) => {
+          const a = byId.get(e.from); // 🔵
+          const b = byId.get(e.to); // 🔵
+          if (!a || !b) return null; // 🧯 unknown id: skip, don't crash the slide
+          const d = getAbFlowEdgePath(a, b, e.curve); // 〰️
+          const delay = { '--ab-wire-index': String(i) } as CSSProperties; // ⏱️ stagger (ab-nextjs-animations)
+          return (
+            <g key={`${e.from}-${e.to}-${i}`} style={delay}>
+              <path className={clsx(styles.wire, AB_WIRE_DRAW_CLASS)} d={d} pathLength={100} />{/* 🖊️ draws on */}
+              <path className={clsx(styles.pulse, AB_WIRE_PULSE_CLASS)} d={d} pathLength={100} />{/* ✨ travelling pulse */}
+            </g>
+          );
+        })}
+      </svg>
+      {/* 🔵 nodes layer (HTML: crisp text, real fonts) */}
+      <div className={styles.nodes} aria-hidden="true">
+        {nodes.map((n) => (
+          <span key={n.id} className={styles.node} data-tone={n.tone ?? 'node'} style={nodeStyle(n)}>
+            {n.icon ? <span className={styles.nodeIcon}>{n.icon}</span> : null}
+            <span>{n.label}</span>
+          </span>
+        ))}
+      </div>
+      {children ? <div className={styles.overlay} aria-hidden="true">{children}</div> : null}
+    </figure>
+  );
+}
+
+// 📦 default export
+export default AbFlowDiagram;

package/ab-flow-diagram/styles.module.css

@@ -0,0 +1,158 @@
+/* 
+* @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 - Styles (G38)
+* @file: ab-flow-diagram/styles.module.css
+* @type: CSS module — transform/opacity/dash only (CLS 0)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+/* 🃏 scene card (laptop 760×600 ratio) */
+.root {
+  position: relative; /* 📌 layers */
+  margin: 0; /* 🧹 figure default */
+  width: 100%; /* ↔️ */
+  aspect-ratio: 760 / 600; /* 📐 mock card */
+  border-radius: 1.25rem; /* 🔲 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface-container, transparent); /* 🎨 */
+  overflow: hidden; /* ✂️ */
+  color: var(--ab-color-on-surface, currentColor); /* 🎨 */
+  container-type: inline-size; /* 📦 nodes scale with the card width (cqi units below) */
+  /* 🎛️ stage insets (tunable): where nodes + wires may sit. Top is 0 unless a header renders (below) */
+  --ab-flow-diagram-stage-top: 0px;
+  --ab-flow-diagram-stage-x: var(--ab-flow-diagram-inset-x, 0.5rem); /* ↔️ side margin: nodes never touch the card edge */
+}
+/* 🏷️ header-safe stage: with a title / live dot / caption, nodes + wires start BELOW the header band, so a
+ *    node near the top (e.g. "core" at 390px) can't cover the header. Override with --ab-flow-diagram-inset-top */
+.root[data-ab-header='true'] {
+  --ab-flow-diagram-stage-top: var(--ab-flow-diagram-inset-top, 2.75rem); /* 📏 0.875rem header top + ~1.25rem row + gap */
+}
+.root[data-variant='compact'] {
+  aspect-ratio: auto; /* 📐 */
+  height: 276px; /* 📏 mobile scene */
+}
+
+/* 🏷️ header row */
+.header {
+  position: absolute; /* 📌 */
+  inset: 0.875rem 1rem auto; /* 📍 top */
+  display: flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  gap: 0.5rem; /* 🧱 */
+  font-size: 0.8125rem; /* 🔡 */
+  z-index: 2; /* 🧱 */
+}
+.title { font-weight: 600; } /* 💪 */
+.caption {
+  margin-inline-start: auto; /* ➡️ end */
+  font-family: var(--ab-font-mono, ui-monospace, monospace); /* 🔤 PKG label */
+  color: var(--ab-color-bronze-text, #8A6440); /* ♿ small text */
+}
+.live { display: inline-flex; align-items: center; gap: 0.25rem; } /* 🟢 */
+.liveDot {
+  width: 0.5rem; height: 0.5rem; border-radius: 50%; /* ⚪ */
+  background: var(--ab-color-sage, #7C9A7E); /* 🌿 */
+}
+
+/* 〰️ wires layer */
+.wires {
+  position: absolute; /* 📌 */
+  inset: var(--ab-flow-diagram-stage-top) var(--ab-flow-diagram-stage-x) 0; /* 📐 the stage (below the header, inside the side margins) */
+  width: calc(100% - 2 * var(--ab-flow-diagram-stage-x)); /* ↔️ same box as .nodes */
+  height: calc(100% - var(--ab-flow-diagram-stage-top)); /* ↕️ same box as .nodes, so wires meet the nodes */
+  overflow: visible; /* 🚫 clip */
+}
+.wire,
+.pulse {
+  fill: none; /* 🫥 */
+  vector-effect: non-scaling-stroke; /* 📏 stroke stays crisp with preserveAspectRatio="none" */
+  stroke-linecap: round; /* ⚪ */
+}
+.wire {
+  stroke: color-mix(in srgb, currentColor 28%, transparent); /* 🌫️ */
+  stroke-width: 1.5; /* 📏 px */
+  /* 🖊️ draw-on = .ab-wire-draw (ab-nextjs-animations) */
+}
+.pulse {
+  stroke: var(--ab-color-bronze, #A67C52); /* 🥉 */
+  stroke-width: 3; /* 📏 */
+  /* ✨ dash, reveal + travel = .ab-wire-pulse (ab-nextjs-animations) */
+}
+
+/* 🔵 nodes layer */
+.nodes { position: absolute; inset: var(--ab-flow-diagram-stage-top) var(--ab-flow-diagram-stage-x) 0; } /* 📐 same stage as .wires */
+.node {
+  position: absolute; /* 📌 x/y */
+  /* 🎯 orbit that scales with the box: each node is anchored at the SAME fraction of its own box as its
+   *    position in the stage (x = 8 → 8% of the pill sits left of the point, x = 92 → 92%). So the outer edge
+   *    of the orbit pulls in by exactly the node's width: a side node can never cross the card edge, at any
+   *    box size, and the wire end (the point) is always inside the pill. x = y = 50 is the old centring. */
+  transform: translate(calc(var(--ab-flow-node-x, 50) * -1%), calc(var(--ab-flow-node-y, 50) * -1%));
+  max-width: 100%; /* 📏 an over-long label can't be wider than the stage… */
+  overflow: hidden; /* ✂️ …it ellipsises instead */
+  text-overflow: ellipsis; /* … */
+  display: inline-flex; /* 📐 */
+  align-items: center; /* ↕️ */
+  gap: 0.375rem; /* 🧱 */
+  /* 📏 scales with the card (cqi = 1% of its width): 760px card → 13px text, 390px → 11px; clamped both ways */
+  padding: clamp(0.25rem, 0.8cqi, 0.375rem) clamp(0.4375rem, 1.4cqi, 0.625rem); /* 🧱 */
+  border-radius: clamp(0.5rem, 1.4cqi, 0.625rem); /* 🔲 */
+  border: 1px solid var(--ab-color-outline-variant, rgb(0 0 0 / 0.12)); /* 🖊️ */
+  background: var(--ab-color-surface, #fff); /* 🎨 */
+  font-size: clamp(0.6875rem, 1.75cqi, 0.8125rem); /* 🔡 */
+  white-space: nowrap; /* 🚫 wrap */
+}
+.node[data-tone='hub'] {
+  padding: clamp(0.4375rem, 1.4cqi, 0.625rem) clamp(0.625rem, 1.9cqi, 0.875rem); /* 🧱 bigger (scales too) */
+  border-color: var(--ab-color-bronze, #A67C52); /* 🥉 */
+  font-weight: 700; /* 💪 */
+  box-shadow: 0 0 0 clamp(3px, 0.8cqi, 6px) color-mix(in srgb, var(--ab-color-bronze, #A67C52) 12%, transparent); /* ✨ glow */
+}
+.node[data-tone='accent'] { color: var(--ab-color-bronze-text, #8A6440); } /* ♿ */
+.nodeIcon { display: inline-flex; width: 1.125rem; height: 1.125rem; } /* 🖼️ */
+.root[data-variant='compact'] .node { font-size: 0.6875rem; padding: 0.25rem 0.5rem; } /* 📱 */
+.overlay { position: absolute; inset: 0; pointer-events: none; } /* 🧩 */
+
+/* 🖱️ hover glow on laptop only */
+@media (hover: hover) and (min-width: 1024px) {
+  .node:hover { box-shadow: 0 0 0 4px color-mix(in srgb, var(--ab-color-bronze, #A67C52) 18%, transparent); }
+}
+
+/* ⏸️ inactive slide: paused by ab-nextjs-animations via data-ab-paused */
+
+/* 📱 battery: 3 pulse loops on small screens (token only; an explicit `loops` prop wins via inline style) */
+@media (max-width: 639px) {
+  .root { --ab-wire-pulse-iterations: 3; } /* 🔋 */
+}
+
+/* 🧘 reduced motion: handled by ab-nextjs-animations (wires drawn, pulses frozen at --ab-wire-poster) */

package/ab-icon/builtin.ts

@@ -0,0 +1,61 @@
+/* 
+* @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: AbIcon - Built-in glyphs (G2)
+* @file: ab-icon/builtin.ts
+* @type: TypeScript — the only icons components draw themselves
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🔣 one module per icon (ab-nextjs-icons ≥ 0.2.3): bundlers keep only these 8
+import arrowBack from 'ab-nextjs-icons/ab-icons/icons/arrow_back'; // ⏮️ AbCarouselPrev
+import arrowForward from 'ab-nextjs-icons/ab-icons/icons/arrow_forward'; // ⏭️ AbCarouselNext
+import lightMode from 'ab-nextjs-icons/ab-icons/icons/light_mode'; // 🌞 AbThemeToggle
+import darkMode from 'ab-nextjs-icons/ab-icons/icons/dark_mode'; // 🌙 AbThemeToggle
+import computer from 'ab-nextjs-icons/ab-icons/icons/computer'; // 🖥️ AbThemeToggle (system)
+import language from 'ab-nextjs-icons/ab-icons/icons/language'; // 🌐 AbLocaleSwitcher
+import contentCopy from 'ab-nextjs-icons/ab-icons/icons/content_copy'; // 📋 AbInstallSnippet
+import check from 'ab-nextjs-icons/ab-icons/icons/check'; // ✅ AbInstallSnippet (copied)
+// 🧾 shape
+import type { AbIconSvgData } from './helpers';
+
+/** 🗂️ Icons the component library renders internally (always registered by AbIcon). */
+export const AB_ICON_BUILTINS: Record<string, AbIconSvgData> = {
+  arrow_back: arrowBack, // ⏮️
+  arrow_forward: arrowForward, // ⏭️
+  light_mode: lightMode, // 🌞
+  dark_mode: darkMode, // 🌙
+  computer, // 🖥️
+  language, // 🌐
+  content_copy: contentCopy, // 📋
+  check, // ✅
+};

package/ab-icon/helpers.ts

@@ -0,0 +1,102 @@
+/* 
+* @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: AbIcon - Shared helpers + registry (G2)
+* @file: ab-icon/helpers.ts
+* @type: TypeScript (pure, server-safe)
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> import arrowBack from 'ab-nextjs-icons/ab-icons/icons/arrow_back' // 📦 icons ≥ 0.2.3, one icon per module
+*    -|> registerAbIcons({ arrow_back: arrowBack }) // 🗂️ at module scope (same on server + client → no hydration mismatch)
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🧾 one icon's SVG markup (same shape as ab-nextjs-icons `AbIconSvgEntry`)
+export interface AbIconSvgData {
+  outlined: string; // ✏️ outlined markup (stroke = currentColor)
+  filled?: string; // ⬛ filled markup (optional)
+}
+
+// 🎚️ variants + weights (mirrors ab-nextjs-icons ≥ 0.2.0)
+export type AbIconVariant = 'outlined' | 'filled';
+export type AbIconWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700;
+
+// 📏 weight → stroke width. Copied from ab-nextjs-icons `abIconWeightStroke`
+//    (importing it would pull the whole 378 KB icon map into client bundles).
+export const AB_ICON_WEIGHT_STROKE: Record<AbIconWeight, number> = {
+  100: 1.0, 200: 1.25, 300: 1.5, 400: 1.85, 500: 2.2, 600: 2.5, 700: 2.85, // ✅ test guards drift
+};
+
+// 🧭 package default weight (icons 0.2.0+: 200)
+export const AB_ICON_DEFAULT_WEIGHT: AbIconWeight = 200;
+
+// 🗂️ module-level registry: name → markup (client bundles only carry what you register)
+const registry = new Map<string, AbIconSvgData>();
+
+/**
+ * @name registerAbIcons
+ * @description 🗂️ Make icons available to the client `<AbIcon name>`. Call at module
+ *   scope so server render + hydration see the same set. Later calls overwrite names.
+ */
+export function registerAbIcons(icons: Record<string, AbIconSvgData>): void {
+  for (const [name, data] of Object.entries(icons)) registry.set(name, data); // ➕
+}
+
+// 🔍 registry lookup (tests + server twin fallback)
+export function getRegisteredAbIcon(name: string): AbIconSvgData | undefined {
+  return registry.get(name); // 🎯
+}
+
+/**
+ * @name pickAbIconMarkup
+ * @description 🎯 Choose markup for a variant; filled falls back to outlined (like getAbIconSvg).
+ */
+export function pickAbIconMarkup(data: AbIconSvgData | undefined, variant: AbIconVariant): string | undefined {
+  if (!data) return undefined; // 🙅
+  return variant === 'filled' ? (data.filled ?? data.outlined) : data.outlined; // ✅
+}
+
+/**
+ * @name getAbIconStroke
+ * @description 📏 Stroke width for a weight (snaps to the nearest supported weight).
+ */
+export function getAbIconStroke(weight: number = AB_ICON_DEFAULT_WEIGHT): number {
+  const keys = Object.keys(AB_ICON_WEIGHT_STROKE).map(Number) as AbIconWeight[]; // 🔢
+  const nearest = keys.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a)); // 🎯
+  return AB_ICON_WEIGHT_STROKE[nearest]; // 📏
+}
+
+// 📏 normalise size → CSS length
+export function toAbIconSize(size: number | string | undefined): string {
+  if (size == null) return '24px'; // 🧭 default 24
+  return typeof size === 'number' ? `${size}px` : size; // 📏
+}

package/ab-icon/index.tsx

@@ -22,42 +22,103 @@
 * 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: AbIcon - Client
+* @name: AbIcon - Client (G2)
 * @file: ab-icon/index.tsx
+* @type: Component (client) — AbIcons SVG, no icon font
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*
+* Example usage:
+*   1+|> <AbIcon name="arrow_back" /> // 🙈 decorative
+*    -|> <AbIcon name="github" label="GitHub" svg={github} /> // 🖼️ named image
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
 'use client';
 
-import type { ReactElement } from 'react';
+// ⚛️ types
+import type { CSSProperties, ReactElement } from 'react';
+// 🧵 classes
 import clsx from 'clsx';
+// 🧮 shared helpers (NO icon map import: client bundles stay small)
+import { getAbIconStroke, getRegisteredAbIcon, pickAbIconMarkup, registerAbIcons, toAbIconSize, type AbIconSvgData, type AbIconVariant, type AbIconWeight } from './helpers';
+// 🗂️ the 8 glyphs components draw themselves (per-icon modules, not the map)
+import { AB_ICON_BUILTINS } from './builtin';
+// 🎨 styles
 import styles from './styles.module.css';
 
+// 📦 helpers for consumers (registerAbIcons, types)
+export * from './helpers';
+export { AB_ICON_BUILTINS } from './builtin';
+
+// 🗂️ register built-ins at module scope (same on server render + hydration → no mismatch)
+registerAbIcons(AB_ICON_BUILTINS);
+
+// ⚙️ props
 export interface AbIconProps {
-  name: string;
-  className?: string;
-  filled?: boolean;
-  size?: number | string;
-  title?: string;
+  name: string; // 🗂️ AbIcons name (snake_case); Material ligature fallback if unknown
+  variant?: AbIconVariant; // 🎚️ outlined (default) | filled
+  filled?: boolean; // 🕰️ legacy alias for variant="filled"
+  weight?: AbIconWeight | number; // 📏 100–700 (outlined), default 200
+  size?: number | string; // 📐 default 24px
+  label?: string; // ♿ NEW: accessible name; omitted = decorative (aria-hidden)
+  title?: string; // 💬 legacy tooltip + name
+  svg?: AbIconSvgData; // 🧾 NEW: explicit markup (tree-shaken per-icon import)
+  className?: string; // 🏷️
+  style?: CSSProperties; // 🎨
 }
 
-/** Material Symbols ligature icon (client). */
-const AbIcon = ({ name, className, filled = false, size, title }: AbIconProps): ReactElement => {
+/** 🔣 AbIcons SVG icon (client): `svg` prop → registry → Material ligature fallback. */
+const AbIcon = ({ name, variant, filled = false, weight, size, label, title, svg, className, style }: AbIconProps): ReactElement => {
+  // 🔍 resolve markup without the full map
+  const markup = pickAbIconMarkup(svg ?? getRegisteredAbIcon(name), variant ?? (filled ? 'filled' : 'outlined'));
+  // 🎚️ legacy `filled` → variant
+  const v: AbIconVariant = variant ?? (filled ? 'filled' : 'outlined');
+  // 🏷️ accessible name: `label` (new) or `title` (legacy)
+  const name_ = label ?? title;
+  // 🎨 size + weight as CSS variables (weight overrides SVG stroke-width via CSS)
+  const vars = { ...style, '--ab-icon-size': toAbIconSize(size), '--ab-icon-stroke': String(getAbIconStroke(weight)) } as CSSProperties;
+  // ♿ labelled = image, else decorative
+  const a11y = name_ ? { role: 'img' as const, 'aria-label': name_ } : { 'aria-hidden': true as const };
+
+  // ✅ AbIcons SVG
+  if (markup) {
+    return (
+      <span
+        className={clsx('AbIcon', styles.abIcon, className)} // 🏷️
+        style={vars} // 🎨
+        data-variant={v} // 🎚️
+        data-icon={name} // 🗂️
+        title={title} // 💬 legacy tooltip only
+        {...a11y} // ♿
+        // 🔒 trusted, package-generated static markup (never user input)
+        dangerouslySetInnerHTML={{ __html: markup }}
+      />
+    );
+  }
+
+  // 🕰️ fallback: Material Symbols ligature (pre-G2 behaviour) for names not in AbIcons
   return (
     <span
-      className={clsx('material-symbols-rounded', 'icon', styles.abIcon, className)}
-      style={size != null ? { fontSize: typeof size === 'number' ? `${size}px` : size } : undefined}
-      title={title}
-      aria-hidden={title ? undefined : true}
-      role={title ? 'img' : undefined}
-      data-filled={filled ? 'true' : 'false'}
+      className={clsx('material-symbols-rounded', 'icon', styles.abIconFont, className)} // 🏷️
+      style={{ ...style, fontSize: toAbIconSize(size) }} // 📏
+      data-filled={v === 'filled' ? 'true' : 'false'} // 🎚️
+      data-icon={name} // 🗂️
+      data-ab-icon-fallback="font" // 🔎 easy to audit
+      title={title} // 💬
+      {...a11y} // ♿
     >
       {name}
     </span>
   );
 };
 
+// 📦 exports
 export default AbIcon;
 export { AbIcon };