@fragments-sdk/ui 0.3.0 → 0.5.0

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

@@ -63,7 +63,7 @@
   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);
+  padding: var(--fui-padding-inline-sm, $fui-padding-inline-sm) var(--fui-padding-inline-md, $fui-padding-inline-md);
   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);
@@ -225,3 +225,18 @@
     outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
   }
 }
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .toast {
+    animation: none;
+  }
+
+  .action,
+  .close {
+    transition: none;
+  }
+}

package/src/components/Toast/index.tsx

@@ -28,11 +28,9 @@ export interface ToastData {
   };
 }
 
-export interface ToastProps extends Omit<ToastData, 'id'> {
+export interface ToastProps extends Omit<ToastData, 'id'>, Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
   /** Callback when toast should be dismissed */
   onDismiss?: () => void;
-  /** Additional class name */
-  className?: string;
 }
 
 export interface ToastProviderProps {
@@ -165,14 +163,19 @@ const variantIcons: Record<ToastVariant, React.ComponentType | null> = {
 // ============================================
 
 function ToastItem({
+  id,
   title,
   description,
   variant = 'default',
   action,
   onDismiss,
   className,
-}: ToastProps) {
+  ...htmlProps
+}: ToastProps & { id?: string }) {
   const Icon = variantIcons[variant];
+  const uniqueId = React.useId();
+  const titleId = title ? `toast-title-${id || uniqueId}` : undefined;
+  const descId = description ? `toast-desc-${id || uniqueId}` : undefined;
 
   const toastClasses = [
     styles.toast,
@@ -181,15 +184,21 @@ function ToastItem({
   ].filter(Boolean).join(' ');
 
   return (
-    <div className={toastClasses} role="alert">
+    <div
+      {...htmlProps}
+      className={toastClasses}
+      role="alert"
+      aria-labelledby={titleId}
+      aria-describedby={descId}
+    >
       {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>}
+        {title && <div id={titleId} className={styles.title}>{title}</div>}
+        {description && <div id={descId} className={styles.description}>{description}</div>}
       </div>
       {action && (
         <button
@@ -205,7 +214,7 @@ function ToastItem({
           type="button"
           className={styles.close}
           onClick={onDismiss}
-          aria-label="Dismiss"
+          aria-label="Dismiss notification"
         >
           <CloseIcon />
         </button>
@@ -232,10 +241,17 @@ function ToastContainer({
     styles[position.replace('-', '')],
   ].filter(Boolean).join(' ');
 
-  if (toasts.length === 0) return null;
-
+  // 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}>
+    <div
+      className={containerClasses}
+      role="region"
+      aria-label="Notifications"
+      aria-live="polite"
+      aria-atomic="false"
+      aria-relevant="additions"
+    >
       {toasts.map((toast) => (
         <ToastItem
           key={toast.id}

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

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { defineSegment } from '@fragments/core';
-import { Toggle } from './index.js';
+import { Toggle } from '.';
 
 // Stateful wrapper for interactive demos
 function StatefulToggle(props: React.ComponentProps<typeof Toggle>) {

package/src/components/Toggle/Toggle.module.scss

@@ -21,7 +21,7 @@
   position: relative;
   flex-shrink: 0;
   border-radius: var(--fui-radius-full, $fui-radius-full);
-  margin-top: 2px;
+  margin-top: var(--fui-space-0-5, $fui-space-0-5);
   background-color: var(--fui-border-strong, $fui-border-strong);
 
   &[data-checked] {
@@ -45,8 +45,8 @@
 
 .thumb {
   position: absolute;
-  top: 2px;
-  left: 2px;
+  top: $fui-toggle-thumb-offset;
+  left: $fui-toggle-thumb-offset;
   border-radius: 50%;
   background-color: var(--fui-bg-primary, $fui-bg-primary);
   box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
@@ -59,20 +59,20 @@
 }
 
 .thumbSm {
-  width: 14px;
-  height: 14px;
+  width: $fui-toggle-thumb-sm;
+  height: $fui-toggle-thumb-sm;
 
   [data-checked] > & {
-    transform: translateX(14px);
+    transform: translateX($fui-toggle-thumb-sm);
   }
 }
 
 .thumbMd {
-  width: 18px;
-  height: 18px;
+  width: $fui-toggle-thumb-md;
+  height: $fui-toggle-thumb-md;
 
   [data-checked] > & {
-    transform: translateX(18px);
+    transform: translateX($fui-toggle-thumb-md);
   }
 }
 
@@ -92,12 +92,27 @@
 }
 
 .description {
+  display: block;
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-text-secondary, $fui-text-secondary);
-  margin-top: 2px;
+  margin-top: var(--fui-space-0-5, $fui-space-0-5);
   line-height: var(--fui-line-height-tight, $fui-line-height-tight);
 }
 
 .descriptionSm {
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
 }
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .thumb {
+    transition: none;
+  }
+
+  .track {
+    transition: none;
+  }
+}

package/src/components/Toggle/index.tsx

@@ -14,6 +14,10 @@ export interface ToggleProps {
   size?: 'sm' | 'md';
   className?: string;
   name?: string;
+  id?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
 }
 
 export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
@@ -28,6 +32,10 @@ export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
       size = 'md',
       className,
       name,
+      id,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
     },
     ref
   ) {
@@ -57,12 +65,16 @@ export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
     return (
       <Switch.Root
         ref={ref}
+        id={id}
         checked={checked}
         defaultChecked={defaultChecked}
         onCheckedChange={onChange}
         disabled={disabled}
         name={name}
         className={rootClasses}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
       >
         <Switch.Thumb className={trackClasses}>
           <span className={thumbClasses} aria-hidden="true" />

package/src/components/ToggleGroup/ToggleGroup.fragment.tsx

@@ -0,0 +1,207 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { ToggleGroup } from '.';
+
+export default defineSegment({
+  component: ToggleGroup,
+
+  meta: {
+    name: 'ToggleGroup',
+    description: 'A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['toggle', 'group', 'segmented', 'control', 'tabs', 'switch'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'Switching between mutually exclusive views or modes',
+      'Selecting one option from a small set (2-5 options)',
+      'Segmented controls like view switchers',
+      'Filter or sort options',
+    ],
+    whenNot: [
+      'Multiple selections allowed (use Checkbox group)',
+      'Many options (use Select or RadioGroup)',
+      'Navigation between pages (use Tabs)',
+      'On/off toggle (use Toggle component)',
+    ],
+    guidelines: [
+      'Keep options to 2-5 items for clarity',
+      'Use clear, concise labels',
+      'Consider icons for common actions (grid/list view)',
+      'Ensure adequate touch targets on mobile',
+    ],
+    accessibility: [
+      'Uses role="group" for semantic grouping',
+      'Each item has role="radio" with aria-checked',
+      'Keyboard navigable with Tab and arrow keys',
+      'Focus visible on active item',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Currently selected value',
+      required: true,
+    },
+    onChange: {
+      type: 'function',
+      description: 'Called with new value when selection changes',
+      required: true,
+    },
+    children: {
+      type: 'node',
+      description: 'ToggleGroup.Item components',
+      required: true,
+    },
+    variant: {
+      type: 'enum',
+      description: 'Visual style',
+      values: ['default', 'pills', 'outline'],
+      default: 'default',
+    },
+    size: {
+      type: 'enum',
+      description: 'Size variant',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+    gap: {
+      type: 'enum',
+      description: 'Gap between items (pills/outline variants)',
+      values: ['none', 'xs', 'sm'],
+      default: 'xs',
+    },
+  },
+
+  relations: [
+    { component: 'RadioGroup', relationship: 'alternative', note: 'RadioGroup for form-style single selection' },
+    { component: 'Tabs', relationship: 'alternative', note: 'Tabs for content panel switching' },
+    { component: 'Toggle', relationship: 'sibling', note: 'Toggle for single on/off control' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - selected value (required)',
+      'onChange: (value: string) => void - change handler (required)',
+      'children: ToggleGroup.Item[] - toggle items',
+      'variant: default|pills|outline - visual style',
+      'size: sm|md - size variant',
+      'gap: none|xs|sm - spacing',
+    ],
+    scenarioTags: [
+      'forms.selection',
+      'input.toggle',
+      'control.segmented',
+    ],
+    a11yRules: ['A11Y_GROUP_ROLE', 'A11Y_KEYBOARD_ACCESSIBLE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic toggle group',
+      render: () => {
+        const [value, setValue] = React.useState('left');
+        return (
+          <ToggleGroup value={value} onChange={setValue}>
+            <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+            <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+            <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+          </ToggleGroup>
+        );
+      },
+    },
+    {
+      name: 'Pills Variant',
+      description: 'Pill-shaped toggle buttons',
+      render: () => {
+        const [value, setValue] = React.useState('all');
+        return (
+          <ToggleGroup value={value} onChange={setValue} variant="pills">
+            <ToggleGroup.Item value="all">All</ToggleGroup.Item>
+            <ToggleGroup.Item value="active">Active</ToggleGroup.Item>
+            <ToggleGroup.Item value="completed">Completed</ToggleGroup.Item>
+          </ToggleGroup>
+        );
+      },
+    },
+    {
+      name: 'Outline Variant',
+      description: 'Outlined toggle buttons',
+      render: () => {
+        const [value, setValue] = React.useState('day');
+        return (
+          <ToggleGroup value={value} onChange={setValue} variant="outline">
+            <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
+            <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
+            <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
+          </ToggleGroup>
+        );
+      },
+    },
+    {
+      name: 'Sizes',
+      description: 'Different size variants',
+      render: () => {
+        const [value1, setValue1] = React.useState('a');
+        const [value2, setValue2] = React.useState('a');
+        return (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+            <ToggleGroup value={value1} onChange={setValue1} size="sm">
+              <ToggleGroup.Item value="a">Small</ToggleGroup.Item>
+              <ToggleGroup.Item value="b">Size</ToggleGroup.Item>
+            </ToggleGroup>
+            <ToggleGroup value={value2} onChange={setValue2} size="md">
+              <ToggleGroup.Item value="a">Medium</ToggleGroup.Item>
+              <ToggleGroup.Item value="b">Size</ToggleGroup.Item>
+            </ToggleGroup>
+          </div>
+        );
+      },
+    },
+    {
+      name: 'View Switcher',
+      description: 'Common pattern for switching between views',
+      render: () => {
+        const [view, setView] = React.useState('grid');
+        return (
+          <ToggleGroup value={view} onChange={setView} size="sm">
+            <ToggleGroup.Item value="grid">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                <rect x="3" y="3" width="7" height="7" />
+                <rect x="14" y="3" width="7" height="7" />
+                <rect x="3" y="14" width="7" height="7" />
+                <rect x="14" y="14" width="7" height="7" />
+              </svg>
+            </ToggleGroup.Item>
+            <ToggleGroup.Item value="list">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                <line x1="3" y1="6" x2="21" y2="6" />
+                <line x1="3" y1="12" x2="21" y2="12" />
+                <line x1="3" y1="18" x2="21" y2="18" />
+              </svg>
+            </ToggleGroup.Item>
+          </ToggleGroup>
+        );
+      },
+    },
+    {
+      name: 'With Disabled Item',
+      description: 'Toggle group with a disabled option',
+      render: () => {
+        const [value, setValue] = React.useState('basic');
+        return (
+          <ToggleGroup value={value} onChange={setValue}>
+            <ToggleGroup.Item value="basic">Basic</ToggleGroup.Item>
+            <ToggleGroup.Item value="pro">Pro</ToggleGroup.Item>
+            <ToggleGroup.Item value="enterprise" disabled>Enterprise</ToggleGroup.Item>
+          </ToggleGroup>
+        );
+      },
+    },
+  ],
+});

package/src/components/ToggleGroup/ToggleGroup.module.scss

@@ -0,0 +1,134 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Group Container
+// ============================================
+
+.group {
+  display: inline-flex;
+  align-items: center;
+}
+
+// Gap variants
+.gap-xs {
+  gap: 2px;
+}
+
+.gap-sm {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+// ============================================
+// Default variant (connected buttons)
+// ============================================
+
+.default {
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  padding: 2px;
+  gap: 2px;
+
+  .item {
+    background-color: transparent;
+    border: none;
+    border-radius: calc(var(--fui-radius-md, $fui-radius-md) - 2px);
+
+    &.selected {
+      background-color: var(--fui-bg-primary, $fui-bg-primary);
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+    }
+  }
+}
+
+// ============================================
+// Pills variant (separate pill buttons)
+// ============================================
+
+.pills {
+  .item {
+    background-color: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+
+    &:hover:not(:disabled):not(.selected) {
+      background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    }
+
+    &.selected {
+      background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+      border-color: var(--fui-border, $fui-border);
+    }
+  }
+}
+
+// ============================================
+// Outline variant (bordered buttons)
+// ============================================
+
+.outline {
+  .item {
+    background-color: transparent;
+    border: 1px solid var(--fui-border, $fui-border);
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+
+    &:hover:not(:disabled):not(.selected) {
+      background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    }
+
+    &.selected {
+      background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+      border-color: var(--fui-color-accent, $fui-color-accent);
+      color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+}
+
+// ============================================
+// Item base styles
+// ============================================
+
+.item {
+  @include button-reset;
+  @include interactive-base;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  user-select: none;
+  transition: all 150ms ease;
+
+  &.selected {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &.disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+// ============================================
+// Size variants
+// ============================================
+
+.size-sm {
+  .item {
+    min-height: 28px;
+    padding: 0 var(--fui-space-2, $fui-space-2);
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.size-md {
+  .item {
+    min-height: 32px;
+    padding: 0 var(--fui-space-3, $fui-space-3);
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+}