@fragments-sdk/ui 0.1.0

package/src/components/Toast/Toast.module.scss

@@ -0,0 +1,227 @@
+@use '../../tokens/variables' as *;
+
+// ============================================
+// Toast Container
+// ============================================
+
+.container {
+  position: fixed;
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-2, $fui-space-2);
+  max-width: 420px;
+  width: calc(100% - var(--fui-space-4, $fui-space-4) * 2);
+  pointer-events: none;
+
+  > * {
+    pointer-events: auto;
+  }
+}
+
+// Position variants
+.topleft {
+  top: var(--fui-space-4, $fui-space-4);
+  left: var(--fui-space-4, $fui-space-4);
+}
+
+.topcenter {
+  top: var(--fui-space-4, $fui-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+.topright {
+  top: var(--fui-space-4, $fui-space-4);
+  right: var(--fui-space-4, $fui-space-4);
+}
+
+.bottomleft {
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: var(--fui-space-4, $fui-space-4);
+  flex-direction: column-reverse;
+}
+
+.bottomcenter {
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  flex-direction: column-reverse;
+}
+
+.bottomright {
+  bottom: var(--fui-space-4, $fui-space-4);
+  right: var(--fui-space-4, $fui-space-4);
+  flex-direction: column-reverse;
+}
+
+// ============================================
+// Toast Item
+// ============================================
+
+.toast {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border, $fui-border);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  // Animation
+  animation: toastEnter 0.2s ease-out;
+}
+
+@keyframes toastEnter {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+// ============================================
+// Variant Styles
+// ============================================
+
+.default {
+  .icon {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}
+
+.success {
+  border-left: 3px solid var(--fui-color-success, $fui-color-success);
+
+  .icon {
+    color: var(--fui-color-success, $fui-color-success);
+  }
+}
+
+.error {
+  border-left: 3px solid var(--fui-color-danger, $fui-color-danger);
+
+  .icon {
+    color: var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+.warning {
+  border-left: 3px solid var(--fui-color-warning, $fui-color-warning);
+
+  .icon {
+    color: var(--fui-color-warning, $fui-color-warning);
+  }
+}
+
+.info {
+  border-left: 3px solid var(--fui-color-info, $fui-color-info);
+
+  .icon {
+    color: var(--fui-color-info, $fui-color-info);
+  }
+}
+
+// ============================================
+// Toast Parts
+// ============================================
+
+.icon {
+  flex-shrink: 0;
+  width: 1.25rem;
+  height: 1.25rem;
+  margin-top: 1px;
+
+  svg {
+    width: 100%;
+    height: 100%;
+  }
+}
+
+.content {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.description {
+  margin-top: 2px;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// ============================================
+// Action Button
+// ============================================
+
+.action {
+  flex-shrink: 0;
+  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);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-color-accent, $fui-color-accent);
+  background: transparent;
+  border: none;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  cursor: pointer;
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
+  }
+}
+
+// ============================================
+// Close Button
+// ============================================
+
+.close {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  margin: -2px -4px -2px 0;
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  cursor: pointer;
+  transition:
+    background-color var(--fui-transition-fast, $fui-transition-fast),
+    color var(--fui-transition-fast, $fui-transition-fast);
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+
+  &:focus-visible {
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
+  }
+}

package/src/components/Toast/index.tsx

@@ -0,0 +1,315 @@
+import * as React from 'react';
+import styles from './Toast.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.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 ToastProps extends Omit<ToastData, 'id'> {
+  /** Callback when toast should be dismissed */
+  onDismiss?: () => void;
+  /** Additional class name */
+  className?: string;
+}
+
+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: Omit<ToastData, 'id'>) => 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: Omit<ToastData, 'id'>) => {
+    return context.addToast(options);
+  }, [context]);
+
+  const success = React.useCallback((title: string, description?: string) => {
+    return context.addToast({ title, description, variant: 'success' });
+  }, [context]);
+
+  const error = React.useCallback((title: string, description?: string) => {
+    return context.addToast({ title, description, variant: 'error' });
+  }, [context]);
+
+  const warning = React.useCallback((title: string, description?: string) => {
+    return context.addToast({ title, description, variant: 'warning' });
+  }, [context]);
+
+  const info = React.useCallback((title: string, description?: string) => {
+    return context.addToast({ title, description, variant: 'info' });
+  }, [context]);
+
+  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({
+  title,
+  description,
+  variant = 'default',
+  action,
+  onDismiss,
+  className,
+}: ToastProps) {
+  const Icon = variantIcons[variant];
+
+  const toastClasses = [
+    styles.toast,
+    styles[variant],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div className={toastClasses} role="alert">
+      {Icon && (
+        <span className={styles.icon}>
+          <Icon />
+        </span>
+      )}
+      <div className={styles.content}>
+        {title && <div className={styles.title}>{title}</div>}
+        {description && <div 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"
+        >
+          <CloseIcon />
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ============================================
+// Toast Container
+// ============================================
+
+function ToastContainer({
+  toasts,
+  position,
+  onDismiss,
+}: {
+  toasts: ToastData[];
+  position: ToastPosition;
+  onDismiss: (id: string) => void;
+}) {
+  const containerClasses = [
+    styles.container,
+    styles[position.replace('-', '')],
+  ].filter(Boolean).join(' ');
+
+  if (toasts.length === 0) return null;
+
+  return (
+    <div className={containerClasses}>
+      {toasts.map((toast) => (
+        <ToastItem
+          key={toast.id}
+          {...toast}
+          onDismiss={() => onDismiss(toast.id)}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ============================================
+// Toast Provider
+// ============================================
+
+let toastCounter = 0;
+
+export function ToastProvider({
+  position = 'bottom-right',
+  duration = 5000,
+  max = 5,
+  children,
+}: ToastProviderProps) {
+  const [toasts, setToasts] = React.useState<ToastData[]>([]);
+
+  const addToast = React.useCallback((toast: Omit<ToastData, 'id'>) => {
+    const id = `toast-${++toastCounter}`;
+    const toastDuration = toast.duration ?? duration;
+
+    setToasts((prev) => {
+      const newToasts = [...prev, { ...toast, id }];
+      // Limit to max toasts
+      return newToasts.slice(-max);
+    });
+
+    // Auto-dismiss
+    if (toastDuration > 0) {
+      setTimeout(() => {
+        setToasts((prev) => prev.filter((t) => t.id !== id));
+      }, toastDuration);
+    }
+
+    return id;
+  }, [duration, max]);
+
+  const removeToast = React.useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const clearToasts = React.useCallback(() => {
+    setToasts([]);
+  }, []);
+
+  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}
+      />
+    </ToastContext.Provider>
+  );
+}
+
+// ============================================
+// Export Toast as compound component
+// ============================================
+
+export const Toast = Object.assign(ToastItem, {
+  Provider: ToastProvider,
+});

package/src/components/Toggle/Toggle.fragment.tsx

@@ -0,0 +1,174 @@
+import React, { useState } from 'react';
+import { defineSegment } from '@fragments/core';
+import { Toggle } from './index.js';
+
+// Stateful wrapper for interactive demos
+function StatefulToggle(props: React.ComponentProps<typeof Toggle>) {
+  const [checked, setChecked] = useState(props.checked ?? false);
+  return <Toggle {...props} checked={checked} onChange={setChecked} />;
+}
+
+export default defineSegment({
+  component: Toggle,
+
+  meta: {
+    name: 'Toggle',
+    description: 'Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['switch', 'toggle', 'boolean', 'settings', 'preference'],
+    since: '0.1.0',
+  },
+
+  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: [
+      'Toggle 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 a description for toggles whose effect isn\'t obvious from the label',
+      'Group related toggles 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',
+    ],
+  },
+
+  props: {
+    checked: {
+      type: 'boolean',
+      description: 'Whether the toggle is in the on state',
+      default: 'false',
+    },
+    onChange: {
+      type: 'function',
+      description: 'Callback with new checked state: (checked: boolean) => void',
+    },
+    label: {
+      type: 'string',
+      description: 'Visible label text',
+    },
+    description: {
+      type: 'string',
+      description: 'Helper text shown below the label',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Whether the toggle is non-interactive',
+      default: 'false',
+    },
+    size: {
+      type: 'enum',
+      description: 'Toggle track size',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+  },
+
+  relations: [
+    { component: 'Input', relationship: 'sibling', note: 'Input handles text/number entry; Toggle handles boolean state' },
+    { component: 'Checkbox', relationship: 'alternative', note: 'Use Checkbox when change requires form submission' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'checked: boolean - on/off state',
+      'onChange: (checked) => void - state change handler',
+      'label: string - visible label text',
+      'description: string - helper text below label',
+      'disabled: boolean - non-interactive state',
+      'size: sm|md - toggle size',
+    ],
+    scenarioTags: [
+      'form.boolean',
+      'settings.toggle',
+      'settings.preference',
+      'form.switch',
+    ],
+    a11yRules: ['A11Y_SWITCH_ROLE', 'A11Y_SWITCH_LABEL', 'A11Y_SWITCH_FOCUS'],
+  },
+
+  variants: [
+    {
+      name: 'Default Off',
+      description: 'Toggle in the off state',
+      render: () => <StatefulToggle label="Email notifications" />,
+      args: { label: 'Email notifications' },
+    },
+    {
+      name: 'Checked',
+      description: 'Toggle in the on state',
+      render: () => <StatefulToggle checked label="Dark mode" />,
+      args: { checked: true, label: 'Dark mode' },
+    },
+    {
+      name: 'With Description',
+      description: 'Toggle with explanatory helper text',
+      render: () => (
+        <StatefulToggle
+          checked
+          label="Auto-save"
+          description="Automatically save changes as you type"
+        />
+      ),
+      args: { checked: true, label: 'Auto-save', description: 'Automatically save changes as you type' },
+    },
+    {
+      name: 'Small Size',
+      description: 'Compact toggle for dense settings panels',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <StatefulToggle size="sm" checked label="Show line numbers" />
+          <StatefulToggle size="sm" label="Word wrap" />
+          <StatefulToggle size="sm" checked label="Minimap" />
+        </div>
+      ),
+    },
+    {
+      name: 'Disabled States',
+      description: 'Non-interactive toggles showing both states',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <Toggle disabled label="Premium feature (upgrade required)" />
+          <Toggle disabled checked label="System managed (read-only)" />
+        </div>
+      ),
+    },
+    {
+      name: 'Settings Panel',
+      description: 'Multiple toggles in a realistic settings layout',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>
+          <StatefulToggle
+            checked
+            label="Push notifications"
+            description="Receive push notifications on your device"
+          />
+          <StatefulToggle
+            checked
+            label="Email digest"
+            description="Weekly summary of your activity"
+          />
+          <StatefulToggle
+            label="Marketing emails"
+            description="Product updates and promotional offers"
+          />
+        </div>
+      ),
+    },
+  ],
+});