@usefragments/ui 1.0.0

package/src/components/Toast/index.tsx

@@ -0,0 +1,439 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Toast.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type ToastVariant = 'default' | 'success' | 'error' | 'warning' | 'info';
+export type ToastPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+export interface ToastData {
+  id: string;
+  title?: string;
+  description?: string;
+  variant?: ToastVariant;
+  duration?: number;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}
+
+export interface ToastInput extends Omit<ToastData, 'id'> {
+  /** Optional explicit id (useful for deterministic tests / replacing a known toast) */
+  id?: string;
+}
+
+export interface ToastProps extends Omit<ToastData, 'id'>, Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Callback when toast should be dismissed */
+  onDismiss?: () => void;
+}
+
+export interface ToastProviderProps {
+  /** Position of the toast container */
+  position?: ToastPosition;
+  /** Default duration in ms (0 = no auto-dismiss) */
+  duration?: number;
+  /** Maximum number of toasts to show */
+  max?: number;
+  /** Children */
+  children: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface ToastContextValue {
+  toasts: ToastData[];
+  addToast: (toast: ToastInput) => string;
+  removeToast: (id: string) => void;
+  clearToasts: () => void;
+}
+
+const ToastContext = React.createContext<ToastContextValue | null>(null);
+
+// ============================================
+// Hook to use toast
+// ============================================
+
+export function useToast() {
+  const context = React.useContext(ToastContext);
+  if (!context) {
+    throw new Error('useToast must be used within a ToastProvider');
+  }
+
+  const toast = React.useCallback((options: ToastInput) => {
+    return context.addToast(options);
+  }, [context]);
+
+  const makeVariantHelper = React.useCallback(
+    (variant: ToastVariant) =>
+      (titleOrOptions: string | Omit<ToastInput, 'variant'>, description?: string) => {
+        if (typeof titleOrOptions === 'string') {
+          return context.addToast({ title: titleOrOptions, description, variant });
+        }
+        return context.addToast({ ...titleOrOptions, variant });
+      },
+    [context]
+  );
+
+  const success = React.useMemo(() => makeVariantHelper('success'), [makeVariantHelper]);
+  const error = React.useMemo(() => makeVariantHelper('error'), [makeVariantHelper]);
+  const warning = React.useMemo(() => makeVariantHelper('warning'), [makeVariantHelper]);
+  const info = React.useMemo(() => makeVariantHelper('info'), [makeVariantHelper]);
+
+  return {
+    toast,
+    success,
+    error,
+    warning,
+    info,
+    dismiss: context.removeToast,
+    dismissAll: context.clearToasts,
+  };
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function SuccessIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" />
+      <path d="m9 12 2 2 4-4" />
+    </svg>
+  );
+}
+
+function ErrorIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" />
+      <line x1="15" y1="9" x2="9" y2="15" />
+      <line x1="9" y1="9" x2="15" y2="15" />
+    </svg>
+  );
+}
+
+function WarningIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
+      <line x1="12" y1="9" x2="12" y2="13" />
+      <line x1="12" y1="17" x2="12.01" y2="17" />
+    </svg>
+  );
+}
+
+function InfoIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="10" />
+      <line x1="12" y1="16" x2="12" y2="12" />
+      <line x1="12" y1="8" x2="12.01" y2="8" />
+    </svg>
+  );
+}
+
+function CloseIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+const variantIcons: Record<ToastVariant, React.ComponentType | null> = {
+  default: null,
+  success: SuccessIcon,
+  error: ErrorIcon,
+  warning: WarningIcon,
+  info: InfoIcon,
+};
+
+// ============================================
+// Toast Component
+// ============================================
+
+function ToastItem({
+  id,
+  title,
+  description,
+  variant = 'default',
+  action,
+  onDismiss,
+  onPause,
+  onResume,
+  className,
+  ...htmlProps
+}: ToastProps & {
+  id?: string;
+  onPause?: () => void;
+  onResume?: () => void;
+}) {
+  const Icon = variantIcons[variant];
+  const uniqueId = React.useId();
+  const toastRef = React.useRef<HTMLDivElement>(null);
+  const titleId = title ? `toast-title-${id || uniqueId}` : undefined;
+  const descId = description ? `toast-desc-${id || uniqueId}` : undefined;
+  const liveRole = variant === 'error' || variant === 'warning' ? 'alert' : 'status';
+
+  const toastClasses = [
+    styles.toast,
+    styles[variant],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div
+      ref={toastRef}
+      {...htmlProps}
+      className={toastClasses}
+      role={liveRole}
+      aria-atomic="true"
+      aria-labelledby={titleId}
+      aria-describedby={descId}
+      onMouseEnter={onPause}
+      onMouseLeave={() => {
+        requestAnimationFrame(() => {
+          if (!toastRef.current?.contains(document.activeElement)) {
+            onResume?.();
+          }
+        });
+      }}
+      onFocusCapture={onPause}
+      onBlurCapture={() => {
+        requestAnimationFrame(() => {
+          if (!toastRef.current?.contains(document.activeElement)) {
+            onResume?.();
+          }
+        });
+      }}
+    >
+      {Icon && (
+        <span className={styles.icon}>
+          <Icon />
+        </span>
+      )}
+      <div className={styles.content}>
+        {title && <div id={titleId} className={styles.title}>{title}</div>}
+        {description && <div id={descId} className={styles.description}>{description}</div>}
+      </div>
+      {action && (
+        <button
+          type="button"
+          className={styles.action}
+          onClick={action.onClick}
+        >
+          {action.label}
+        </button>
+      )}
+      {onDismiss && (
+        <button
+          type="button"
+          className={styles.close}
+          onClick={onDismiss}
+          aria-label="Dismiss notification"
+        >
+          <CloseIcon />
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ============================================
+// Toast Container
+// ============================================
+
+function ToastContainer({
+  toasts,
+  position,
+  onDismiss,
+  onPause,
+  onResume,
+}: {
+  toasts: ToastData[];
+  position: ToastPosition;
+  onDismiss: (id: string) => void;
+  onPause: (id: string) => void;
+  onResume: (id: string) => void;
+}) {
+  const containerClasses = [
+    styles.container,
+    styles[position.replace('-', '')],
+  ].filter(Boolean).join(' ');
+
+  // Always render the container for screen reader live region to work properly
+  // The live region must exist before announcements are made
+  return (
+    <div className={containerClasses} role="region" aria-label="Notifications">
+      {toasts.map((toast) => (
+        <ToastItem
+          key={toast.id}
+          {...toast}
+          onDismiss={() => onDismiss(toast.id)}
+          onPause={() => onPause(toast.id)}
+          onResume={() => onResume(toast.id)}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ============================================
+// Toast Provider
+// ============================================
+
+export function ToastProvider({
+  position = 'bottom-right',
+  duration = 8000,
+  max = 5,
+  children,
+}: ToastProviderProps) {
+  const [toasts, setToasts] = React.useState<ToastData[]>([]);
+  const idCounterRef = React.useRef(0);
+  const timeoutRef = React.useRef(new Map<string, ReturnType<typeof setTimeout>>());
+  const remainingRef = React.useRef(new Map<string, number>());
+  const startTimeRef = React.useRef(new Map<string, number>());
+
+  const clearRemovalTimer = React.useCallback((id: string) => {
+    const timeout = timeoutRef.current.get(id);
+    if (timeout) {
+      clearTimeout(timeout);
+      timeoutRef.current.delete(id);
+    }
+  }, []);
+
+  const scheduleRemoval = React.useCallback(
+    (id: string, delay: number) => {
+      if (delay <= 0) return;
+      clearRemovalTimer(id);
+      remainingRef.current.set(id, delay);
+      startTimeRef.current.set(id, Date.now());
+
+      const timeout = setTimeout(() => {
+        setToasts((prev) => prev.filter((t) => t.id !== id));
+        clearRemovalTimer(id);
+        remainingRef.current.delete(id);
+        startTimeRef.current.delete(id);
+      }, delay);
+
+      timeoutRef.current.set(id, timeout);
+    },
+    [clearRemovalTimer]
+  );
+
+  const addToast = React.useCallback((toast: ToastInput) => {
+    const id = toast.id ?? `toast-${++idCounterRef.current}`;
+    const toastDuration = toast.duration ?? (toast.action ? 0 : duration);
+
+    setToasts((prev) => {
+      const nextToasts = [...prev, { ...toast, id }];
+      const overflowCount = Math.max(0, nextToasts.length - max);
+
+      if (overflowCount > 0) {
+        const removedToasts = nextToasts.slice(0, overflowCount);
+        removedToasts.forEach((removedToast) => {
+          clearRemovalTimer(removedToast.id);
+          remainingRef.current.delete(removedToast.id);
+          startTimeRef.current.delete(removedToast.id);
+        });
+      }
+
+      return overflowCount > 0 ? nextToasts.slice(overflowCount) : nextToasts;
+    });
+
+    // Auto-dismiss
+    if (toastDuration > 0) {
+      scheduleRemoval(id, toastDuration);
+    }
+
+    return id;
+  }, [clearRemovalTimer, duration, max, scheduleRemoval]);
+
+  const removeToast = React.useCallback((id: string) => {
+    clearRemovalTimer(id);
+    remainingRef.current.delete(id);
+    startTimeRef.current.delete(id);
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, [clearRemovalTimer]);
+
+  const pauseToast = React.useCallback((id: string) => {
+    const remaining = remainingRef.current.get(id);
+    if (remaining === undefined) return;
+
+    const startedAt = startTimeRef.current.get(id);
+    if (startedAt) {
+      const elapsed = Date.now() - startedAt;
+      remainingRef.current.set(id, Math.max(remaining - elapsed, 0));
+    }
+    clearRemovalTimer(id);
+  }, [clearRemovalTimer]);
+
+  const resumeToast = React.useCallback((id: string) => {
+    const remaining = remainingRef.current.get(id);
+    if (remaining === undefined || remaining <= 0) return;
+    scheduleRemoval(id, remaining);
+  }, [scheduleRemoval]);
+
+  const clearToasts = React.useCallback(() => {
+    timeoutRef.current.forEach((timeout) => {
+      clearTimeout(timeout);
+    });
+    timeoutRef.current.clear();
+    remainingRef.current.clear();
+    startTimeRef.current.clear();
+    setToasts([]);
+  }, []);
+
+  React.useEffect(
+    () => () => {
+      timeoutRef.current.forEach((timeout) => {
+        clearTimeout(timeout);
+      });
+      timeoutRef.current.clear();
+      remainingRef.current.clear();
+      startTimeRef.current.clear();
+    },
+    []
+  );
+
+  const value = React.useMemo(
+    () => ({ toasts, addToast, removeToast, clearToasts }),
+    [toasts, addToast, removeToast, clearToasts]
+  );
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <ToastContainer
+        toasts={toasts}
+        position={position}
+        onDismiss={removeToast}
+        onPause={pauseToast}
+        onResume={resumeToast}
+      />
+    </ToastContext.Provider>
+  );
+}
+
+// ============================================
+// Export Toast as compound component
+// ============================================
+
+export const Toast = Object.assign(ToastItem, {
+  Provider: ToastProvider,
+});

package/src/components/Toggle/Toggle.contract.json

@@ -0,0 +1,231 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Switch",
+  "description": "Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly.",
+  "category": "forms",
+  "tags": [
+    "switch",
+    "toggle",
+    "boolean",
+    "settings",
+    "preference"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Toggle/index.tsx",
+  "exportName": "Switch",
+  "propsSummary": [
+    "checked: boolean",
+    "defaultChecked: boolean",
+    "onCheckedChange: function",
+    "onChange: function",
+    "label: string",
+    "helperText: string",
+    "description: string",
+    "disabled: boolean (default: false)",
+    "size: sm|md|lg (default: md)",
+    "className: string",
+    "name: string",
+    "id: string",
+    "aria-label: string",
+    "aria-labelledby: string",
+    "aria-describedby: string"
+  ],
+  "props": {
+    "checked": {
+      "type": "boolean",
+      "description": "Whether the switch is in the on state",
+      "default": "false",
+      "required": false
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "description": "Default checked state (uncontrolled)",
+      "required": false
+    },
+    "onCheckedChange": {
+      "type": "function",
+      "description": "Called when the switch is toggled: (checked: boolean) => void",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Alias for onCheckedChange: (checked: boolean) => void",
+      "required": false
+    },
+    "label": {
+      "type": "string",
+      "description": "Visible label text",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text shown below the label (preferred)",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "description": "Deprecated alias for helperText",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether the switch is non-interactive",
+      "default": "false",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Switch track size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "className": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "aria-describedby": {
+      "type": "string",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Binary settings that take effect immediately (e.g., dark mode, notifications)",
+      "Enabling/disabling features in a settings panel",
+      "Options where the result is immediately visible",
+      "Mobile-friendly boolean inputs"
+    ],
+    "whenNot": [
+      "Multiple options in a group (use checkbox group)",
+      "Selection requires form submission to take effect (use checkbox)",
+      "Yes/No questions in forms (use radio buttons)",
+      "Complex multi-state options (use select or radio)"
+    ],
+    "guidelines": [
+      "Switch should always have a visible label explaining what it controls",
+      "The \"on\" state should be the positive/enabling action",
+      "Changes should take effect immediately - no save button needed",
+      "Include helperText for switches whose effect isn't obvious from the label",
+      "Group related switches visually in settings panels"
+    ],
+    "accessibility": [
+      "Uses role=\"switch\" with aria-checked for proper semantics",
+      "Must have an accessible label (visible or aria-label)",
+      "Focus indicator must be clearly visible",
+      "State change must be announced by screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default Off",
+      "description": "Switch in the off state",
+      "code": "<StatefulSwitch label=\"Email notifications\" />",
+      "args": {
+        "label": "Email notifications"
+      }
+    },
+    {
+      "name": "Checked",
+      "description": "Switch in the on state",
+      "code": "<StatefulSwitch checked label=\"Dark mode\" />",
+      "args": {
+        "checked": true,
+        "label": "Dark mode"
+      }
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Switch with explanatory helper text",
+      "code": "<StatefulSwitch\n  checked\n  label=\"Auto-save\"\n  helperText=\"Automatically save changes as you type\"\n/>",
+      "args": {
+        "checked": true,
+        "label": "Auto-save",
+        "helperText": "Automatically save changes as you type"
+      }
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size variants",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulSwitch size=\"sm\" checked label=\"Small switch\" />\n  <StatefulSwitch size=\"md\" checked label=\"Medium switch (default)\" />\n  <StatefulSwitch size=\"lg\" checked label=\"Large switch\" />\n</div>"
+    },
+    {
+      "name": "Disabled States",
+      "description": "Non-interactive switches showing both states",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Switch disabled label=\"Premium feature (upgrade required)\" />\n  <Switch disabled checked label=\"System managed (read-only)\" />\n</div>"
+    },
+    {
+      "name": "Settings Panel",
+      "description": "Multiple switches in a realistic settings layout",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>\n  <StatefulSwitch\n    checked\n    label=\"Push notifications\"\n    helperText=\"Receive push notifications on your device\"\n  />\n  <StatefulSwitch\n    checked\n    label=\"Email digest\"\n    helperText=\"Weekly summary of your activity\"\n  />\n  <StatefulSwitch\n    label=\"Marketing emails\"\n    helperText=\"Product updates and promotional offers\"\n  />\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "sibling",
+      "note": "Input handles text/number entry; Switch handles boolean state"
+    },
+    {
+      "component": "Checkbox",
+      "relationship": "alternative",
+      "note": "Use Checkbox when change requires form submission"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "checked: boolean - on/off state",
+      "onCheckedChange: (checked) => void - state change handler",
+      "onChange: (checked) => void - alias for onCheckedChange",
+      "label: string - visible label text",
+      "helperText: string - helper text below label (preferred)",
+      "description: string - deprecated alias for helperText",
+      "disabled: boolean - non-interactive state",
+      "size: sm|md|lg - switch size"
+    ],
+    "a11yRules": [
+      "A11Y_SWITCH_ROLE",
+      "A11Y_SWITCH_LABEL",
+      "A11Y_SWITCH_FOCUS",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.429Z"
+  }
+}