ab-nextjs-components 0.1.7 → 0.1.9

package/server/ab-logo/index.tsx

@@ -27,69 +27,128 @@
 * @project: ab-nextjs-components
 * @name: AbLogo - Server
 * @file: server/ab-logo/index.tsx
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🖥️ server build (no 'use client'; the client twin lives in `ab-logo`)
 
-import type { ReactElement } from 'react';
+// 🧩 React types only
+import type { CSSProperties, ReactElement } from 'react';
+// 🧵 class-name joiner
 import clsx from 'clsx';
+// 🎨 package-shipped CSS module (Tailwind-independent)
 import styles from './styles.module.css';
 
+// 🅰️ the four logo looks
 export type AbLogoType = 'contained' | 'outlined' | 'hollow' | 'naked';
 
+// 📐 public props
 export interface AbLogoProps {
+  // 🅰️ look of the mark (default: naked)
   type?: AbLogoType;
+  // 🏷️ consumer classes
   className?: string;
-  /** Optional image src (contained). Defaults to the Ab logo shipped in this package (data URI). */
+  /** 🖼️ Optional image src. Defaults to the Ab mark shipped in this package (data URI). */
   src?: string;
-  /** Optional CSS mask value for outlined/hollow/naked. */
+  /** 🎭 Optional CSS mask value for outlined/hollow/naked. */
   mask?: string;
+  // 🗣️ accessible name of the mark
   alt?: string;
+  // 📏 mark size (or wordmark font-size when `wordmark` is on)
   size?: number | string;
+  /** 🔤 Show the wordmark next to the mark: `true` → "Elements", or any string. */
+  wordmark?: boolean | string;
+  /** 🎨 Mark + wordmark color (CSS color). Defaults to bronze (light) / #FFF8F5 (dark). */
+  color?: string;
 }
 
-/** Inlined Ab logo shipped with this package (also at `ab-logo/ab-logo.svg`). */
-const DEFAULT_SRC = 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E';
+/** 🅰️ Inlined Ab logo shipped with this package (also at `ab-logo/ab-logo.svg`). */
+export const AB_LOGO_DEFAULT_SRC = 'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E';
+
+// 🔤 the default wordmark text (a brand name, never translated)
+export const AB_LOGO_DEFAULT_WORDMARK = 'Elements';
+
+// 📏 number → px, string → as is
+const toCssSize = (size?: number | string): string | undefined =>
+  size != null ? (typeof size === 'number' ? `${size}px` : size) : undefined;
 
 const AbLogo = ({
-  type = 'naked',
-  className,
-  src,
-  mask,
-  alt = 'Ab',
-  size,
+  type = 'naked', // 🅰️ naked by default
+  className, // 🏷️ consumer classes
+  src, // 🖼️ optional image
+  mask, // 🎭 optional mask
+  alt = 'Ab', // 🗣️ default name
+  size, // 📏 optional size
+  wordmark, // 🔤 optional wordmark
+  color, // 🎨 optional color
 }: AbLogoProps): ReactElement => {
-  const dim = size != null ? (typeof size === 'number' ? `${size}px` : size) : undefined;
+  // 📏 normalized size
+  const dim = toCssSize(size);
+  // 🔤 wordmark text (null = no wordmark)
+  const text = wordmark === true ? AB_LOGO_DEFAULT_WORDMARK : typeof wordmark === 'string' && wordmark ? wordmark : null;
+  // 🎨 color as a custom property consumed by the CSS module
+  const colorVar = (color ? { '--ab-logo-color': color } : {}) as CSSProperties;
 
+  // 🖼️ build the mark
+  let mark: ReactElement;
   if (type === 'contained') {
-    return (
+    // 🖼️ contained = a real <img>
+    mark = (
+      // eslint-disable-next-line @next/next/no-img-element -- 🖼️ the default src is an inline data-URI SVG (nothing for next/image to optimize), and this package must not require next/image's loader config in consumer apps
       <img
-        className={clsx('AbLogo', 'app-logo', styles.abLogoContained, className)}
-        src={src ?? DEFAULT_SRC}
-        alt={alt}
+        className={clsx(!text && ['AbLogo', 'app-logo', className], styles.abLogoContained, text && styles.abLogo__mark)}
+        src={src ?? AB_LOGO_DEFAULT_SRC}
+        alt={text ? '' : alt}
+        aria-hidden={text ? true : undefined}
         data-type="contained"
-        style={dim ? { width: dim, height: dim } : undefined}
+        style={!text && dim ? { width: dim, height: dim } : undefined}
+      />
+    );
+  } else {
+    // 🎭 explicit mask/src wins; otherwise the CSS module masks with `--app-logo-url` or the shipped mark (no brown square ✅)
+    const maskValue = mask ?? (src ? `url('${src}') no-repeat 50% 50%` : undefined);
+    mark = (
+      <span
+        className={clsx(!text && ['AbLogo', 'app-logo', className], styles.abLogo, text && styles.abLogo__mark)}
+        data-type={type}
+        role={text ? undefined : 'img'}
+        aria-label={text ? undefined : alt}
+        aria-hidden={text ? true : undefined}
+        style={{
+          ...(!text ? colorVar : {}), // 🎨 color (standalone mark only; lockup sets it on the wrapper)
+          ...(!text && dim ? { width: dim, height: dim } : {}), // 📏 size
+          ...(maskValue ? { WebkitMask: maskValue, mask: maskValue, WebkitMaskSize: 'cover', maskSize: 'cover' } : {}), // 🎭 custom mask
+        }}
       />
     );
   }
 
-  // With no `mask`/`src`, leave the mask to `ab-nextjs-theme` (`--app-logo-url` / `.app-logo`).
-  // When `mask` or `src` is set, apply it inline (src becomes a CSS mask url).
-  const maskValue = mask ?? (src ? `url('${src}') no-repeat 50% 50%` : undefined);
+  // 🅰️ no wordmark → just the mark (unchanged API)
+  if (!text) return mark;
+
+  // 🔤 lockup: mark + wordmark, one accessible image
   return (
     <span
-      className={clsx('AbLogo', 'app-logo', styles.abLogo, className)}
+      className={clsx('AbLogo', 'AbLogo--wordmark', styles.abLogo__lockup, className)}
       data-type={type}
       role="img"
-      aria-label={alt}
-      style={{
-        ...(dim ? { width: dim, height: dim } : {}),
-        ...(maskValue
-          ? { WebkitMask: maskValue, mask: maskValue, WebkitMaskSize: 'cover', maskSize: 'cover' }
-          : {}),
-      }}
-    />
+      aria-label={`${alt} ${text}`.trim()}
+      style={{ ...colorVar, ...(dim ? { fontSize: dim } : {}) }}
+    >
+      {/* 🅰️ the mark */}
+      {mark}
+      {/* 🔤 the wordmark — Quicksand Bold from ab-nextjs-fonts */}
+      <span className={clsx('font-quicksand-bold', styles.abLogo__wordmark)} aria-hidden="true">{text}</span>
+    </span>
   );
 };
 
+// 📦 exports
 export default AbLogo;
 export { AbLogo };

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

@@ -4,7 +4,31 @@
 * ab-nextjs-components
 * ~~~~~~~~~~~~ 
 * Copyright (c) 2026 Abraham Ukachi. The abElements Project.
-* Plain CSS modules — no Tailwind Tailwind apply (Turbopack-safe).
+*
+* 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: AbLogo - Component Stylesheet (plain CSS, Tailwind-independent)
+* @file: server/ab-logo/styles.module.css
+* @type: CSS Module
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
 */
 
 /*
@@ -13,18 +37,62 @@
 * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 */
 
+/* 🅰️ masked mark (naked / outlined / hollow) */
 .abLogo {
-  display: block;
-  position: relative;
-  width: 1.5rem;
-  height: 1.5rem;
-  background-color: var(--app-logo-color, #a67c52);
+  display: block; /* 🧱 block box */
+  position: relative; /* 📌 positioning context */
+  width: 1.5rem; /* ↔️ default size */
+  height: 1.5rem; /* ↕️ default size */
+  /* 🎨 bronze by default; `--app-logo-color` (chrome) or `--ab-logo-color` (prop) override */
+  background-color: var(--app-logo-color, var(--ab-logo-color, #A67C52));
+  /* 🎭 the shipped Ab mark as mask → no brown square without chrome CSS ✅ */
+  -webkit-mask: var(--app-logo-url, url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E")) no-repeat 50% 50%;
+  mask: var(--app-logo-url, url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20xml%3Aspace%3D%22preserve%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22%23A67C52%22%20d%3D%22m1.8%2020.5%209.3-17v17zM22.2%207.7l-9.3-4.2v17l9.3-4.2-4.7-4.3z%22/%3E%3Cpath%20d%3D%22m12.9%2020.5%209.3-4.2-9.3-8.6z%22%20opacity%3D%22.1%22/%3E%3C/svg%3E")) no-repeat 50% 50%;
+  -webkit-mask-size: contain; /* 📐 keep proportions */
+  mask-size: contain; /* 📐 keep proportions */
+}
+
+/* 🌙 dark: light mark on dark surfaces */
+:global(html.dark) .abLogo:not(.abLogo__mark) {
+  background-color: var(--app-logo-color, var(--ab-logo-color, #FFF8F5));
 }
 
+/* 🖼️ contained mark (a real <img>) */
 .abLogoContained {
-  display: block;
-  position: relative;
-  width: 1.5rem;
-  height: 1.5rem;
-  object-fit: contain;
+  display: block; /* 🧱 block box */
+  position: relative; /* 📌 positioning context */
+  width: 1.5rem; /* ↔️ default size */
+  height: 1.5rem; /* ↕️ default size */
+  object-fit: contain; /* 📐 keep proportions */
+}
+
+/* 🔤 lockup = mark + wordmark */
+.abLogo__lockup {
+  display: inline-flex; /* ➡️ one row */
+  align-items: center; /* ↕️ centered */
+  gap: 0.28em; /* ↔️ gap scales with the text */
+  font-size: 2rem; /* 📏 default lockup size (override with `size`) */
+  line-height: 1; /* 📐 tight */
+  color: var(--ab-logo-color, #A67C52); /* 🎨 bronze */
+}
+
+/* 🌙 dark lockup */
+:global(html.dark) .abLogo__lockup {
+  color: var(--ab-logo-color, #FFF8F5);
+}
+
+/* 🅰️ the mark inside a lockup follows the text size & color */
+.abLogo__mark {
+  width: 1.15em; /* ↔️ ≈ cap height + descender, as in the splash mock */
+  height: 1.15em; /* ↕️ square */
+  flex: none; /* 🚫 never shrink */
+  background-color: currentColor; /* 🎨 same as the wordmark */
+}
+
+/* 🔤 the wordmark — Quicksand Bold (font files ship with ab-nextjs-fonts/quicksand/styles.css) */
+.abLogo__wordmark {
+  font-family: 'Quicksand-Bold', 'Quicksand', ui-rounded, system-ui, sans-serif; /* 🔤 */
+  font-weight: 700; /* 💪 bold */
+  letter-spacing: 0.01em; /* ↔️ as in the mock */
+  white-space: nowrap; /* 🚫 no wrap */
 }

package/styles.css

@@ -0,0 +1,14 @@
+/*
+ * ab-nextjs-components — component chrome (dialog, toast, logo, spinner, doodle)
+ *
+ * Import after ab-nextjs-theme/styles.css:
+ *   @import "ab-nextjs-theme/styles.css";
+ *   @import "ab-nextjs-components/styles.css";
+ */
+
+@import "./css/dialog.css";
+@import "./css/toast.css";
+@import "./css/logo.css";
+@import "./css/spinner.css";
+@import "./css/doodle.css";
+@import "./css/chrome-mq.css";

package/types/css.d.ts

@@ -0,0 +1,43 @@
+/* 
+* @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: CSS module typings (for `tsc --noEmit` outside Next.js)
+* @file: types/css.d.ts
+* @authors: Abraham Ukachi <abrahamukachi@gmail.com>
+*/
+
+/*
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* MOTTO: We'll always do more 😜!!!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*/
+
+// 🎨 every `*.module.css` import is a readonly class-name map
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string } // 🗺️ class map
+  export default classes // 📦 default export
+}

package/types/index.d.ts

@@ -17,6 +17,8 @@ export default abComponents;
 
 export { default as AbIcon } from '../ab-icon/index.tsx';
 export { default as AbLogo } from '../ab-logo/index.tsx';
+// 📶 progress bar (ported from core)
+export { default as AbLinearProgress } from '../ab-linear-progress/index.tsx';
 export { default as AbButton } from '../ab-button/index.tsx';
 export { default as AbIconButton } from '../ab-icon-button/index.tsx';
 export { default as AbInput } from '../ab-input/index.tsx';