@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Avatar/index.tsx

@@ -1,19 +1,19 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './Avatar.module.scss';
+import * as React from "react";
+import styles from "./Avatar.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 
 /**
  * Avatar for user photos, initials, or placeholder icons.
  * @see https://usefragments.com/components/avatar
  */
-export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'> {
+export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
   /** Image source URL */
   src?: string;
   /** Alt text for the image */
@@ -22,12 +22,14 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   initials?: string;
   /** Full name - used to generate initials if not provided */
   name?: string;
+  /** Visual fallback rendered after initials/name and before the generic icon */
+  fallback?: React.ReactNode;
   /** Size variant */
   size?: AvatarSize;
   /** Custom avatar size (overrides size width/height) */
   customSize?: number | string;
   /** Shape variant */
-  shape?: 'circle' | 'square';
+  shape?: "circle" | "square";
   /** Custom background color for fallback */
   color?: string;
   /** Inline style for the underlying image element */
@@ -35,7 +37,7 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   /** Additional props for the underlying img element */
   imageProps?: Omit<
     React.ImgHTMLAttributes<HTMLImageElement>,
-    'src' | 'alt' | 'className' | 'style'
+    "src" | "alt" | "className" | "style"
   >;
 }
 
@@ -94,22 +96,39 @@ function stringToColor(str: string): string {
 function contrastForHsl(h: number, s: number, l: number): string {
   // HSL → RGB
   const c = (1 - Math.abs(2 * l - 1)) * s;
-  const x = c * (1 - Math.abs((h / 60) % 2 - 1));
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
   const m = l - c / 2;
-  let r = 0, g = 0, b = 0;
-  if (h < 60) { r = c; g = x; }
-  else if (h < 120) { r = x; g = c; }
-  else if (h < 180) { g = c; b = x; }
-  else if (h < 240) { g = x; b = c; }
-  else if (h < 300) { r = x; b = c; }
-  else { r = c; b = x; }
-  r += m; g += m; b += m;
+  let r = 0,
+    g = 0,
+    b = 0;
+  if (h < 60) {
+    r = c;
+    g = x;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+  } else if (h < 180) {
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+  r += m;
+  g += m;
+  b += m;
 
   // Relative luminance (sRGB → linear)
-  const lin = (v: number) => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  const lin = (v: number) => (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
   const lum = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
 
-  return lum > 0.179 ? '#000000' : '#ffffff';
+  return lum > 0.179 ? "#000000" : "#ffffff";
 }
 
 /**
@@ -124,158 +143,143 @@ function getContrastTextColor(bgColor: string): string | undefined {
     /light-dark\(\s*hsl\((\d+)\s+(\d+)%\s+(\d+)%\)\s*,\s*hsl\((\d+)\s+(\d+)%\s+(\d+)%\)\s*\)/
   );
   if (ld) {
-    const lightText = contrastForHsl(
-      parseInt(ld[1]),
-      parseInt(ld[2]) / 100,
-      parseInt(ld[3]) / 100
-    );
-    const darkText = contrastForHsl(
-      parseInt(ld[4]),
-      parseInt(ld[5]) / 100,
-      parseInt(ld[6]) / 100
-    );
-    return lightText === darkText
-      ? lightText
-      : `light-dark(${lightText}, ${darkText})`;
+    const lightText = contrastForHsl(parseInt(ld[1]), parseInt(ld[2]) / 100, parseInt(ld[3]) / 100);
+    const darkText = contrastForHsl(parseInt(ld[4]), parseInt(ld[5]) / 100, parseInt(ld[6]) / 100);
+    return lightText === darkText ? lightText : `light-dark(${lightText}, ${darkText})`;
   }
 
   // Legacy / custom single HSL color
   const match = bgColor.match(/hsl\((\d+),\s*(\d+)%,\s*(\d+)%\)/);
   if (!match) return undefined;
-  return contrastForHsl(
-    parseInt(match[1]),
-    parseInt(match[2]) / 100,
-    parseInt(match[3]) / 100
-  );
+  return contrastForHsl(parseInt(match[1]), parseInt(match[2]) / 100, parseInt(match[3]) / 100);
 }
 
 // ============================================
 // Avatar Component
 // ============================================
 
-const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
-  function AvatarBase(
-    {
-      src,
-      alt = '',
-      initials,
-      name,
-      size = 'md',
-      customSize,
-      shape = 'circle',
-      color,
-      imageStyle,
-      imageProps,
-      className,
-      style: styleProp,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const imgRef = React.useRef<HTMLImageElement>(null);
-    const [imageError, setImageError] = React.useState(false);
+const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(function AvatarBase(
+  {
+    src,
+    alt = "",
+    initials,
+    name,
+    fallback,
+    size = "md",
+    customSize,
+    shape = "circle",
+    color,
+    imageStyle,
+    imageProps,
+    className,
+    style: styleProp,
+    ...htmlProps
+  },
+  ref
+) {
+  const imgRef = React.useRef<HTMLImageElement>(null);
+  const [imageError, setImageError] = React.useState(false);
 
-    // Reset error state when src changes; check if already-loaded image failed
-    React.useEffect(() => {
-      setImageError(false);
-      const img = imgRef.current;
-      if (img && img.complete && img.naturalWidth === 0) {
-        setImageError(true);
-      }
-    }, [src]);
+  // Reset error state when src changes; check if already-loaded image failed
+  React.useEffect(() => {
+    setImageError(false);
+    const img = imgRef.current;
+    if (img && img.complete && img.naturalWidth === 0) {
+      setImageError(true);
+    }
+  }, [src]);
 
-    const showFallback = !src || imageError;
-    const displayInitials = initials || (name ? getInitials(name) : '');
-    const fallbackColor = color || (name ? stringToColor(name) : undefined);
-    const fallbackLabel = alt || name;
-    const hasFallbackLabel = showFallback && Boolean(fallbackLabel && fallbackLabel.trim().length > 0);
+  const showFallback = !src || imageError;
+  const displayInitials = initials || (name ? getInitials(name) : "");
+  const fallbackColor = color || (name ? stringToColor(name) : undefined);
+  const fallbackLabel = alt || name;
+  const hasFallbackLabel =
+    showFallback && Boolean(fallbackLabel && fallbackLabel.trim().length > 0);
 
-    const avatarClasses = [
-      styles.avatar,
-      styles[size],
-      shape === 'square' && styles.square,
-      className,
-    ].filter(Boolean).join(' ');
+  const avatarClasses = [
+    styles.avatar,
+    styles[size],
+    shape === "square" && styles.square,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
 
-    const style: React.CSSProperties = { ...styleProp };
-    if (customSize !== undefined) {
-      const resolvedSize = typeof customSize === 'number' ? `${customSize}px` : customSize;
-      style.width = resolvedSize;
-      style.height = resolvedSize;
-      if (style.fontSize === undefined) {
-        style.fontSize = `calc(${resolvedSize} * 0.4)`;
-      }
+  const style: React.CSSProperties = { ...styleProp };
+  if (customSize !== undefined) {
+    const resolvedSize = typeof customSize === "number" ? `${customSize}px` : customSize;
+    style.width = resolvedSize;
+    style.height = resolvedSize;
+    if (style.fontSize === undefined) {
+      style.fontSize = `calc(${resolvedSize} * 0.4)`;
     }
+  }
 
-    if (showFallback && fallbackColor) {
-      style.backgroundColor = fallbackColor;
-      const textColor = getContrastTextColor(fallbackColor);
-      if (textColor) {
-        (style as Record<string, string>)['--avatar-initials-color'] = textColor;
-      }
+  if (showFallback && fallbackColor) {
+    style.backgroundColor = fallbackColor;
+    const textColor = getContrastTextColor(fallbackColor);
+    if (textColor) {
+      (style as Record<string, string>)["--avatar-initials-color"] = textColor;
     }
-
-    return (
-      <div
-        ref={ref}
-        {...htmlProps}
-        className={avatarClasses}
-        style={style}
-        role={hasFallbackLabel ? 'img' : undefined}
-        aria-label={hasFallbackLabel ? fallbackLabel : undefined}
-        aria-hidden={showFallback && !hasFallbackLabel ? true : undefined}
-      >
-        {!showFallback && (
-          <img
-            ref={imgRef}
-            {...imageProps}
-            src={src}
-            alt={alt}
-            className={styles.image}
-            onError={(event) => {
-              imageProps?.onError?.(event);
-              if (!event.defaultPrevented) {
-                setImageError(true);
-              }
-            }}
-            style={{ ...imageStyle }}
-          />
-        )}
-        {showFallback && displayInitials && (
-          <span className={styles.initials}>{displayInitials}</span>
-        )}
-        {showFallback && !displayInitials && (
-          <svg
-            className={styles.fallbackIcon}
-            xmlns="http://www.w3.org/2000/svg"
-            viewBox="0 0 24 24"
-            fill="currentColor"
-            aria-hidden="true"
-          >
-            <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" />
-          </svg>
-        )}
-      </div>
-    );
   }
-);
+
+  return (
+    <div
+      ref={ref}
+      {...htmlProps}
+      className={avatarClasses}
+      style={style}
+      role={hasFallbackLabel ? "img" : undefined}
+      aria-label={hasFallbackLabel ? fallbackLabel : undefined}
+      aria-hidden={showFallback && !hasFallbackLabel ? true : undefined}
+    >
+      {!showFallback && (
+        <img
+          ref={imgRef}
+          {...imageProps}
+          src={src}
+          alt={alt}
+          className={styles.image}
+          onError={(event) => {
+            imageProps?.onError?.(event);
+            if (!event.defaultPrevented) {
+              setImageError(true);
+            }
+          }}
+          style={{ ...imageStyle }}
+        />
+      )}
+      {showFallback && displayInitials && (
+        <span className={styles.initials}>{displayInitials}</span>
+      )}
+      {showFallback && !displayInitials && fallback !== undefined && (
+        <span className={styles.fallback}>{fallback}</span>
+      )}
+      {showFallback && !displayInitials && fallback === undefined && (
+        <svg
+          className={styles.fallbackIcon}
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="currentColor"
+          aria-hidden="true"
+        >
+          <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" />
+        </svg>
+      )}
+    </div>
+  );
+});
 
 // ============================================
 // Avatar Group Component
 // ============================================
 
-function AvatarGroup({
-  max,
-  size = 'md',
-  children,
-  className,
-  ...htmlProps
-}: AvatarGroupProps) {
+function AvatarGroup({ max, size = "md", children, className, ...htmlProps }: AvatarGroupProps) {
   const childArray = React.Children.toArray(children);
   const displayCount = max && max < childArray.length ? max : childArray.length;
   const overflowCount = max && childArray.length > max ? childArray.length - max : 0;
 
-  const groupClasses = [styles.group, className].filter(Boolean).join(' ');
+  const groupClasses = [styles.group, className].filter(Boolean).join(" ");
 
   return (
     <div {...htmlProps} className={groupClasses}>
@@ -284,18 +288,20 @@ function AvatarGroup({
           return React.cloneElement(child, {
             key: index,
             size: child.props.size || size,
-            className: [styles.groupItem, child.props.className].filter(Boolean).join(' '),
+            className: [styles.groupItem, child.props.className].filter(Boolean).join(" "),
           });
         }
         return child;
       })}
       {overflowCount > 0 && (
         <div
-          className={[styles.avatar, styles[size], styles.overflow].join(' ')}
+          className={[styles.avatar, styles[size], styles.groupItem, styles.overflow].join(" ")}
           role="img"
-          aria-label={`${overflowCount} more ${overflowCount === 1 ? 'person' : 'people'}`}
+          aria-label={`${overflowCount} more ${overflowCount === 1 ? "person" : "people"}`}
         >
-          <span className={styles.initials} aria-hidden="true">+{overflowCount}</span>
+          <span className={styles.initials} aria-hidden="true">
+            +{overflowCount}
+          </span>
         </div>
       )}
     </div>

package/src/components/Badge/Badge.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Badge",
-  "description": "Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.",
+  "description": "Labels a status, count, or category without pulling focus.",
   "category": "display",
   "tags": ["status", "label", "tag", "count", "chip"],
   "status": "stable",
@@ -87,71 +87,66 @@
   },
   "usage": {
     "when": [
-      "Showing item status (active, pending, archived)",
-      "Displaying counts or quantities inline",
-      "Categorizing or tagging content",
-      "Highlighting new or updated items"
+      "Marking item status: active, pending, archived",
+      "Showing a count inline",
+      "Tagging or categorising content",
+      "Flagging what is new or changed"
     ],
     "whenNot": [
-      "Conveying critical errors (use Alert instead)",
-      "Long-form status messages (use Alert)",
-      "Interactive filtering (use Chip/ToggleGroup)",
-      "Navigation labels (use Tabs or links)"
+      "Real errors that need attention — use Alert",
+      "Anything longer than a few words — use Alert",
+      "Clickable filters — use Chip or ToggleGroup",
+      "View switching — use Tabs or links"
     ],
     "guidelines": [
-      "Keep badge text under 20 characters",
-      "Use dot variant for live status indicators",
-      "Pair success/error variants with meaningful labels, not just colors",
-      "Semantic status badges are borderless pills using shared semantic bg/text tokens",
-      "Use onRemove for user-created tags only, not system-generated badges",
-      "Badges are not announced as live status updates by default; use announce for screen-reader status announcements when appropriate"
+      "Under 20 characters",
+      "dot for live status; add dotPulse only while it is still changing",
+      "Semantic variants are borderless pills on shared status tokens",
+      "label pairs with dotColor; dim pairs with active for filter chrome",
+      "onRemove for user-created tags only, never system labels"
     ],
     "accessibility": [
-      "Badge text must be meaningful without relying on color alone",
-      "Removable badges must have accessible dismiss button labels",
-      "Avoid using badges as the sole indicator of important state changes"
+      "The text must carry the meaning — colour alone never does",
+      "Removable badges need a named dismiss button",
+      "Badges are silent to screen readers unless you pass announce",
+      "Do not make a badge the only signal that something changed"
     ]
   },
   "examples": [
-    {
-      "name": "Default",
-      "description": "Neutral badge for general labels",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge>Default</Badge>"
-    },
     {
       "name": "Status Variants",
-      "description": "All severity variants for different contexts",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
-    },
-    {
-      "name": "Delivery Status",
-      "description": "Reference status pills with deep semantic fill and bright text",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" size=\"lg\">Delivered</Badge>\n  <Badge variant=\"error\" size=\"lg\">Bounced</Badge>\n</Stack>"
+      "description": "Neutral through info, on shared status tokens.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
     },
     {
       "name": "With Dot",
-      "description": "Live status indicators using dot prefix",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n</Stack>"
+      "description": "Leading dot for live state; it breathes while still moving.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n  <Badge variant=\"info\" dot dotPulse>Syncing</Badge>\n</Stack>"
     },
     {
-      "name": "Announced Status",
-      "description": "Opt into screen-reader status announcement behavior",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"success\" announce>Saved</Badge>"
+      "name": "Label and Filter",
+      "description": "Hairline metadata pill, and filter chrome that marks the active one.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"label\" dotColor=\"var(--fui-color-accent)\">Design</Badge>\n  <Badge variant=\"label\" dotColor=\"var(--fui-color-success)\">Shipped</Badge>\n  <Badge variant=\"dim\" active>All</Badge>\n  <Badge variant=\"dim\">Archived</Badge>\n</Stack>"
     },
     {
       "name": "Outline",
-      "description": "Minimal bordered badge for neutral emphasis",
-      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"outline\">Outline</Badge>"
+      "description": "Bordered and transparent, when a fill would shout.",
+      "code": "<Badge variant=\"outline\">Outline</Badge>"
     },
     {
-      "name": "Small Size",
-      "description": "Compact badges for dense UIs",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge size=\"sm\" variant=\"info\">v2.1</Badge>\n  <Badge size=\"sm\" variant=\"success\">Stable</Badge>\n  <Badge size=\"md\" variant=\"info\">Standard</Badge>\n</Stack>"
+      "name": "Sizes",
+      "description": "sm for dense tables, lg for reference status pills.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge variant=\"success\" size=\"sm\">Small</Badge>\n  <Badge variant=\"success\" size=\"md\">Medium</Badge>\n  <Badge variant=\"success\" size=\"lg\">Large</Badge>\n</Stack>"
     },
     {
       "name": "Removable",
-      "description": "User-created tags that can be dismissed",
-      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+      "description": "Dismissible tags the user added themselves.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+    },
+    {
+      "name": "Announced Status",
+      "description": "Looks the same, but screen readers now hear the change.",
+      "code": "<Badge variant=\"success\" announce>Saved</Badge>"
     }
   ],
   "relations": [