@fragments-sdk/ui 0.1.0

package/src/components/Avatar/Avatar.module.scss

@@ -0,0 +1,136 @@
+@use '../../tokens/variables' as *;
+
+// ============================================
+// Avatar Component Styles
+// ============================================
+
+.avatar {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  overflow: hidden;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  user-select: none;
+}
+
+// Shape variant
+.square {
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+}
+
+// ============================================
+// Size Variants
+// ============================================
+
+.xs {
+  width: 1.5rem;   // 24px
+  height: 1.5rem;
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+.sm {
+  width: 2rem;     // 32px
+  height: 2rem;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.md {
+  width: 2.5rem;   // 40px
+  height: 2.5rem;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+.lg {
+  width: 3rem;     // 48px
+  height: 3rem;
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.xl {
+  width: 4rem;     // 64px
+  height: 4rem;
+  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+}
+
+// ============================================
+// Image
+// ============================================
+
+.image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+// ============================================
+// Initials / Fallback
+// ============================================
+
+.initials {
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+  text-transform: uppercase;
+  line-height: 1;
+}
+
+.fallbackIcon {
+  width: 60%;
+  height: 60%;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// ============================================
+// Avatar Group
+// ============================================
+
+.group {
+  display: inline-flex;
+  flex-direction: row-reverse;
+  justify-content: flex-end;
+}
+
+.groupItem {
+  margin-left: -0.5rem;
+  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
+
+  &:last-child {
+    margin-left: 0;
+  }
+}
+
+// Adjust overlap for different sizes
+.group .xs.groupItem {
+  margin-left: -0.375rem;
+}
+
+.group .sm.groupItem {
+  margin-left: -0.5rem;
+}
+
+.group .md.groupItem {
+  margin-left: -0.625rem;
+}
+
+.group .lg.groupItem {
+  margin-left: -0.75rem;
+}
+
+.group .xl.groupItem {
+  margin-left: -1rem;
+}
+
+// Overflow count indicator
+.overflow {
+  margin-left: -0.625rem;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border: 2px solid var(--fui-bg-primary, $fui-bg-primary);
+
+  .initials {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}

package/src/components/Avatar/index.tsx

@@ -0,0 +1,177 @@
+import * as React from 'react';
+import styles from './Avatar.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface AvatarProps {
+  /** Image source URL */
+  src?: string;
+  /** Alt text for the image */
+  alt?: string;
+  /** Fallback initials (1-2 characters recommended) */
+  initials?: string;
+  /** Full name - used to generate initials if not provided */
+  name?: string;
+  /** Size variant */
+  size?: AvatarSize;
+  /** Shape variant */
+  shape?: 'circle' | 'square';
+  /** Custom background color for fallback */
+  color?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface AvatarGroupProps {
+  /** Maximum number of avatars to display */
+  max?: number;
+  /** Size for all avatars in the group */
+  size?: AvatarSize;
+  /** Children (Avatar components) */
+  children: React.ReactNode;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function getInitials(name: string): string {
+  const parts = name.trim().split(/\s+/);
+  if (parts.length === 1) {
+    return parts[0].charAt(0).toUpperCase();
+  }
+  return (parts[0].charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase();
+}
+
+function stringToColor(str: string): string {
+  // Generate a consistent color from a string
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  const hue = Math.abs(hash % 360);
+  return `hsl(${hue}, 65%, 50%)`;
+}
+
+// ============================================
+// Avatar Component
+// ============================================
+
+const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
+  function AvatarBase(
+    {
+      src,
+      alt = '',
+      initials,
+      name,
+      size = 'md',
+      shape = 'circle',
+      color,
+      className,
+    },
+    ref
+  ) {
+    const [imageError, setImageError] = React.useState(false);
+
+    // Reset error state when src changes
+    React.useEffect(() => {
+      setImageError(false);
+    }, [src]);
+
+    const showFallback = !src || imageError;
+    const displayInitials = initials || (name ? getInitials(name) : '');
+    const fallbackColor = color || (name ? stringToColor(name) : undefined);
+
+    const avatarClasses = [
+      styles.avatar,
+      styles[size],
+      shape === 'square' && styles.square,
+      className,
+    ].filter(Boolean).join(' ');
+
+    const style: React.CSSProperties = {};
+    if (showFallback && fallbackColor) {
+      style.backgroundColor = fallbackColor;
+    }
+
+    return (
+      <div ref={ref} className={avatarClasses} style={style}>
+        {!showFallback && (
+          <img
+            src={src}
+            alt={alt}
+            className={styles.image}
+            onError={() => setImageError(true)}
+          />
+        )}
+        {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>
+    );
+  }
+);
+
+// ============================================
+// Avatar Group Component
+// ============================================
+
+function AvatarGroup({
+  max,
+  size = 'md',
+  children,
+  className,
+}: 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(' ');
+
+  return (
+    <div className={groupClasses}>
+      {childArray.slice(0, displayCount).map((child, index) => {
+        if (React.isValidElement<AvatarProps>(child)) {
+          return React.cloneElement(child, {
+            key: index,
+            size: child.props.size || size,
+            className: [styles.groupItem, child.props.className].filter(Boolean).join(' '),
+          });
+        }
+        return child;
+      })}
+      {overflowCount > 0 && (
+        <div className={[styles.avatar, styles[size], styles.overflow].join(' ')}>
+          <span className={styles.initials}>+{overflowCount}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ============================================
+// Compound Component Export
+// ============================================
+
+export const Avatar = Object.assign(AvatarBase, {
+  Group: AvatarGroup,
+});

package/src/components/Badge/Badge.fragment.tsx

@@ -0,0 +1,151 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Badge } from './index.js';
+
+export default defineSegment({
+  component: Badge,
+
+  meta: {
+    name: 'Badge',
+    description: 'Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['status', 'label', 'tag', 'count', 'chip'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Showing item status (active, pending, archived)',
+      'Displaying counts or quantities inline',
+      'Categorizing or tagging content',
+      'Highlighting new or updated items',
+    ],
+    whenNot: [
+      'Conveying critical errors (use Alert instead)',
+      'Long-form status messages (use Alert)',
+      'Interactive filtering (use chip/toggle group)',
+      'Navigation labels (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',
+      'Use onRemove for user-created tags only, not system-generated badges',
+    ],
+    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',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Badge label text',
+      required: true,
+    },
+    variant: {
+      type: 'enum',
+      description: 'Visual style indicating severity or category',
+      values: ['default', 'success', 'warning', 'error', 'info'],
+      default: 'default',
+    },
+    size: {
+      type: 'enum',
+      description: 'Badge size',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+    dot: {
+      type: 'boolean',
+      description: 'Show a colored dot indicator before the label',
+      default: 'false',
+    },
+    icon: {
+      type: 'node',
+      description: 'Optional icon element before the text',
+    },
+    onRemove: {
+      type: 'function',
+      description: 'Makes the badge removable. Called when X is clicked.',
+    },
+  },
+
+  relations: [
+    { component: 'Alert', relationship: 'alternative', note: 'Use Alert for prominent, longer messages with actions' },
+    { component: 'Tag', relationship: 'sibling', note: 'Tag is interactive (clickable/filterable); Badge is display-only' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - badge label (required)',
+      'variant: default|success|warning|error|info - visual style',
+      'size: sm|md - badge size',
+      'dot: boolean - show status dot indicator',
+      'onRemove: () => void - makes badge removable',
+    ],
+    scenarioTags: [
+      'feedback.status',
+      'display.label',
+      'display.count',
+      'content.tag',
+    ],
+    a11yRules: ['A11Y_BADGE_CONTRAST', 'A11Y_BADGE_DISMISS'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Neutral badge for general labels',
+      render: () => <Badge>Default</Badge>,
+    },
+    {
+      name: 'Status Variants',
+      description: 'All severity variants for different contexts',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+          <Badge variant="default">Default</Badge>
+          <Badge variant="success">Active</Badge>
+          <Badge variant="warning">Pending</Badge>
+          <Badge variant="error">Failed</Badge>
+          <Badge variant="info">New</Badge>
+        </div>
+      ),
+    },
+    {
+      name: 'With Dot',
+      description: 'Live status indicators using dot prefix',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+          <Badge variant="success" dot>Online</Badge>
+          <Badge variant="warning" dot>Away</Badge>
+          <Badge variant="error" dot>Offline</Badge>
+        </div>
+      ),
+    },
+    {
+      name: 'Small Size',
+      description: 'Compact badges for dense UIs',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          <Badge size="sm" variant="info">v2.1</Badge>
+          <Badge size="sm" variant="success">Stable</Badge>
+          <Badge size="md" variant="info">Standard</Badge>
+        </div>
+      ),
+    },
+    {
+      name: 'Removable',
+      description: 'User-created tags that can be dismissed',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Badge variant="info" onRemove={() => {}}>React</Badge>
+          <Badge variant="info" onRemove={() => {}}>TypeScript</Badge>
+          <Badge variant="info" onRemove={() => {}}>CSS</Badge>
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Badge/Badge.module.scss

@@ -0,0 +1,87 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  line-height: 1;
+  white-space: nowrap;
+}
+
+// Sizes
+.sm {
+  padding: 2px var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}
+
+.md {
+  padding: var(--fui-space-1, $fui-space-1) 10px;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+// Variants
+.default {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.success {
+  background-color: var(--fui-color-success-bg, $fui-color-success-bg);
+  color: var(--fui-color-success, $fui-color-success);
+}
+
+.warning {
+  background-color: var(--fui-color-warning-bg, $fui-color-warning-bg);
+  color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.error {
+  background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  color: var(--fui-color-danger, $fui-color-danger);
+}
+
+.info {
+  background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+  color: var(--fui-color-info, $fui-color-info);
+}
+
+.dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background-color: currentColor;
+
+  .sm & {
+    width: 5px;
+    height: 5px;
+  }
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+}
+
+.remove {
+  @include button-reset;
+  @include interactive-base;
+
+  padding: 0 2px;
+  font-size: 14px;
+  color: inherit;
+  opacity: 0.6;
+  line-height: 1;
+  border-radius: 2px;
+
+  .sm & {
+    font-size: 12px;
+  }
+
+  &:hover {
+    opacity: 1;
+  }
+}

package/src/components/Badge/index.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react';
+import { Button as BaseButton } from '@base-ui/react/button';
+import styles from './Badge.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface BadgeProps {
+  children: React.ReactNode;
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
+  size?: 'sm' | 'md';
+  dot?: boolean;
+  icon?: React.ReactNode;
+  onRemove?: () => void;
+  className?: string;
+}
+
+export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
+  function Badge(
+    {
+      children,
+      variant = 'default',
+      size = 'md',
+      dot = false,
+      icon,
+      onRemove,
+      className,
+    },
+    ref
+  ) {
+    const classes = [styles.badge, styles[size], styles[variant], className]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <span ref={ref} className={classes}>
+        {dot && <span className={styles.dot} aria-hidden="true" />}
+        {icon && (
+          <span className={styles.icon} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        {children}
+        {onRemove && (
+          <BaseButton
+            onClick={onRemove}
+            aria-label="Remove"
+            className={styles.remove}
+          >
+            &times;
+          </BaseButton>
+        )}
+      </span>
+    );
+  }
+);