@usefragments/ui 1.5.3 → 1.6.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.module.scss

@@ -1,37 +1,37 @@
 @use "../../tokens/variables" as *;
-@use "../../tokens/mixins" as *;
-
-// Local component tokens
-$fui-badge-dot-sm: 5px !default;
-$fui-badge-dot-md: 6px !default;
+@use "../../recipes/action" as action;
+@use "../../recipes/representation" as representation;
+@use "../../recipes/target" as target;
 
 .badge {
   display: inline-flex;
   align-items: center;
-  width: max-content;
-  gap: var(--fui-space-1, $fui-space-1);
+  box-sizing: border-box;
+  inline-size: max-content;
+  gap: var(--fui-raw-space-4, 4px);
+  padding-block: 0;
   border: 0;
   border-radius: var(--fui-badge-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  line-height: 1;
   white-space: nowrap;
 }
 
 // Sizes
 .sm {
-  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  @include representation.badge("sm");
+
+  padding-inline: var(--fui-raw-space-4, 4px);
 }
 
 .md {
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include representation.badge("md");
+
+  padding-inline: var(--fui-raw-space-6, 6px);
 }
 
 .lg {
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include representation.badge("lg");
+
+  padding-inline: var(--fui-raw-space-8, 8px);
 }
 
 // Variants
@@ -63,34 +63,21 @@ $fui-badge-dot-md: 6px !default;
 .outline {
   background-color: transparent;
   color: var(--fui-text-primary, $fui-text-primary);
-  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border-strong, $fui-border-strong);
 }
 
-// Compact hairline-bordered label for dense dashboard metadata rows.
-// Overrides the base pill radius and padding — squared corners read as
-// data metadata rather than status chrome.
 .label {
-  height: var(--fui-target-size-min, $fui-target-size-min); // 32px control floor
-  padding: 0 calc(var(--fui-space-1, $fui-space-1) - var(--fui-space-px, $fui-space-px)); // ~6px
-  border: 1px solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   background-color: transparent;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 }
 
-// Dim filter-chip chrome for toolbar segmented controls. Transparent at
-// rest, panel-surface + hairline when marked active.
 .dim {
-  height: var(--fui-button-height-sm, $fui-button-height-sm); // 32px small control height
-  padding: 0 calc(var(--fui-space-1, $fui-space-1) + var(--fui-space-0-5, $fui-space-0-5)); // ~9px
-  border: 1px solid transparent;
+  border: var(--fui-stroke-hairline, 1px) solid transparent;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   background-color: transparent;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   transition:
     color var(--fui-transition-fast, $fui-transition-fast),
     border-color var(--fui-transition-fast, $fui-transition-fast),
@@ -104,15 +91,15 @@ $fui-badge-dot-md: 6px !default;
 }
 
 .dot {
-  width: $fui-badge-dot-md;
-  height: $fui-badge-dot-md;
+  inline-size: var(--fui-raw-space-6, 6px);
+  block-size: var(--fui-raw-space-6, 6px);
   border-radius: 50%;
   background-color: var(--fui-badge-dot-color, currentColor);
   flex-shrink: 0;
 
   .sm & {
-    width: $fui-badge-dot-sm;
-    height: $fui-badge-dot-sm;
+    inline-size: var(--fui-raw-space-4, 4px);
+    block-size: var(--fui-raw-space-4, 4px);
   }
 }
 
@@ -138,28 +125,46 @@ $fui-badge-dot-md: 6px !default;
 }
 
 .icon {
-  display: flex;
+  display: inline-flex;
   align-items: center;
+
+  .sm & {
+    @include representation.glyph("xs");
+  }
+
+  .md & {
+    @include representation.glyph("sm");
+  }
+
+  .lg & {
+    @include representation.glyph("md");
+  }
+
+  > svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
 }
 
-// Asymmetric padding when removable — tighter on right side near the × button
 .badge:has(.remove) {
-  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-1, $fui-space-1)
-    var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
+  padding-inline-end: var(--fui-raw-space-4, 4px);
 }
 
 .remove {
-  @include button-reset;
-  @include interactive-base;
-  @include touch-target;
+  @include action.base;
+  @include action.inline;
+  @include target.hit-area("compact");
 
-  margin-left: calc(-1 * var(--fui-space-0-5, $fui-space-0-5));
+  inline-size: 1em;
+  block-size: 1em;
+  margin-inline-start: calc(-1 * var(--fui-raw-space-2, 2px));
   padding: 0;
-  font-size: inherit;
+  border: 0;
+  background: transparent;
   color: inherit;
   opacity: 0.6;
-  line-height: 1;
   border-radius: var(--fui-radius-full, $fui-radius-full);
+  cursor: pointer;
 
   &:hover {
     opacity: 1;

package/src/components/BentoGrid/BentoGrid.module.scss

@@ -1,5 +1,7 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/layout" as layout;
+@use "../../recipes/surface" as surface;
 
 // ============================================
 // BentoGrid Container
@@ -49,22 +51,22 @@
 // ============================================
 
 .gapNone {
-  gap: 0;
+  gap: layout.gap("none");
 }
 .gapXs {
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: layout.gap("xs");
 }
 .gapSm {
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("sm");
 }
 .gapMd {
-  gap: var(--fui-space-3, $fui-space-3);
+  gap: layout.gap("md");
 }
 .gapLg {
-  gap: var(--fui-space-4, $fui-space-4);
+  gap: layout.gap("lg");
 }
 .gapXl {
-  gap: var(--fui-space-6, $fui-space-6);
+  gap: layout.gap("xl");
 }
 
 // ============================================
@@ -73,19 +75,9 @@
 
 .item {
   @include surface-elevated;
+  @include surface.apply-inset("compact");
 
   min-width: 0;
-  padding: var(--fui-space-2, $fui-space-2);
-  transition:
-    box-shadow var(--fui-transition-fast, $fui-transition-fast),
-    border-color var(--fui-transition-fast, $fui-transition-fast),
-    transform var(--fui-transition-fast, $fui-transition-fast);
-
-  &:hover {
-    border-color: var(--fui-border-strong, $fui-border-strong);
-    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
-    transform: translateY(-2px);
-  }
 
   // ---- Responsive span cascade ----
   --_col-span: var(--bento-col-span, 1);
@@ -133,28 +125,15 @@
   }
 }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
-
-@media (prefers-reduced-motion: reduce) {
-  .item {
-    transition: none;
-
-    &:hover {
-      transform: none;
-    }
-  }
-}
-
 // ============================================
 // Accessibility: High Contrast Mode
 // ============================================
 
 @media (prefers-contrast: more) {
   .item {
-    border-width: 2px;
     border-color: var(--fui-text-primary, $fui-text-primary);
+    outline: var(--fui-stroke-hairline, 1px) solid var(--fui-text-primary, $fui-text-primary);
+    outline-offset: calc(-1 * var(--fui-stroke-default, 2px));
   }
 }