@fragments-sdk/ui 0.17.0 → 0.18.0

package/src/components/Toast/Toast.contract.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Toast",
+  "description": "Brief, non-blocking notification messages",
+  "category": "feedback",
+  "tags": [
+    "notification",
+    "alert",
+    "message",
+    "feedback"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Toast/index.tsx",
+  "exportName": "Toast",
+  "propsSummary": [
+    "onDismiss: function",
+    "title: string",
+    "description: string",
+    "variant: default|success|error|warning|info (default: default)",
+    "duration: number",
+    "action: object",
+    "id: string",
+    "onPause: function",
+    "onResume: function"
+  ],
+  "props": {
+    "onDismiss": {
+      "type": "function",
+      "description": "Callback when toast should be dismissed",
+      "required": false
+    },
+    "title": {
+      "type": "string",
+      "description": "Toast title",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "description": "Additional message content",
+      "required": false
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual variant indicating message type",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "success",
+        "error",
+        "warning",
+        "info"
+      ]
+    },
+    "duration": {
+      "type": "number",
+      "description": "Auto-dismiss duration in ms (0 = no auto-dismiss)",
+      "default": 5000,
+      "required": false
+    },
+    "action": {
+      "type": "object",
+      "description": "Optional action button { label, onClick }",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "onPause": {
+      "type": "function",
+      "description": "Callback when auto-dismiss timer should pause",
+      "required": false
+    },
+    "onResume": {
+      "type": "function",
+      "description": "Callback when auto-dismiss timer should resume",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Providing feedback after an action",
+      "Showing success/error status of operations",
+      "Non-critical information that doesn't require action",
+      "Temporary messages that auto-dismiss"
+    ],
+    "whenNot": [
+      "Critical errors requiring user action (use Dialog)",
+      "Persistent information (use Alert)",
+      "Inline validation (use form error states)",
+      "System-wide announcements (use Banner)"
+    ],
+    "guidelines": [
+      "Keep messages brief and actionable",
+      "Use appropriate variant for the message type",
+      "Auto-dismiss after reasonable duration (3-5s)",
+      "Allow manual dismissal for longer messages",
+      "Limit number of simultaneous toasts",
+      "useToast() variant helpers accept either (title, description?) or an options object for action/duration/id"
+    ],
+    "accessibility": [
+      "Use role=\"alert\" for important messages",
+      "Ensure sufficient display time for reading",
+      "Don't rely solely on color for meaning",
+      "Provide dismiss button with accessible label"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Interactive toast demo - click buttons to trigger toasts (includes helper object syntax example)",
+      "code": "<ToastDemoWrapper />"
+    },
+    {
+      "name": "Success",
+      "description": "Success message variant",
+      "code": "<Toast\n  title=\"Success!\"\n  description=\"Your changes have been saved.\"\n  variant=\"success\"\n/>"
+    },
+    {
+      "name": "Error",
+      "description": "Error message variant",
+      "code": "<Toast\n  title=\"Error\"\n  description=\"Failed to save changes. Please try again.\"\n  variant=\"error\"\n/>"
+    },
+    {
+      "name": "Warning",
+      "description": "Warning message variant",
+      "code": "<Toast\n  title=\"Warning\"\n  description=\"This action cannot be undone.\"\n  variant=\"warning\"\n/>"
+    },
+    {
+      "name": "Info",
+      "description": "Informational message variant",
+      "code": "<Toast\n  title=\"New Update\"\n  description=\"Version 2.0 is now available.\"\n  variant=\"info\"\n/>"
+    },
+    {
+      "name": "With Action",
+      "description": "Toast with an action button",
+      "code": "<Toast\n  title=\"File deleted\"\n  description=\"The file has been moved to trash.\"\n  action={{\n    label: 'Undo',\n    onClick: () => console.log('Undo clicked'),\n  }}\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for persistent inline messages"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "alternative",
+      "note": "Use Dialog for messages requiring user action"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "title: string - toast title",
+      "description: string - additional message",
+      "variant: default|success|error|warning|info",
+      "duration: number - ms before auto-dismiss",
+      "action: { label, onClick } - optional action",
+      "ToastInput (useToast): optional id for deterministic creation/replacement flows",
+      "useToast().success/error/warning/info: (title, description?) or ({ title, description, action, duration, id })"
+    ],
+    "a11yRules": [
+      "A11Y_ALERT_ROLE",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Provider"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.259Z"
+  }
+}

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"
+  }
+}

package/src/components/ToggleGroup/ToggleGroup.contract.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "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",
+  "tags": [
+    "toggle",
+    "group",
+    "fragmented",
+    "control",
+    "tabs",
+    "switch"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ToggleGroup/index.tsx",
+  "exportName": "ToggleGroup",
+  "propsSummary": [
+    "value: string",
+    "defaultValue: string",
+    "onChange: function",
+    "onValueChange: function",
+    "children: node (required)",
+    "variant: default|pills|outline|outlined (default: default)",
+    "size: sm|md|lg (default: md)",
+    "gap: sm|none|xs (default: xs)",
+    "selectionMode: single (default: single)"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "description": "Currently selected value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Initial selected value (uncontrolled)",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called with new value when selection changes",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Alias for onChange (Radix convention): (value: string) => void",
+      "required": false
+    },
+    "children": {
+      "type": "node",
+      "description": "ToggleGroup.Item components",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "pills",
+        "outline",
+        "outlined"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Gap between items (pills/outline variants)",
+      "default": "xs",
+      "required": false,
+      "values": [
+        "sm",
+        "none",
+        "xs"
+      ]
+    },
+    "selectionMode": {
+      "type": "enum",
+      "description": "Selection behavior",
+      "default": "single",
+      "required": false,
+      "values": [
+        "single"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Switching between mutually exclusive views or modes",
+      "Selecting one option from a small set (2-5 options)",
+      "Fragmented 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 Switch 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=\"radiogroup\" for single-selection semantics",
+      "Each item has role=\"radio\" with aria-checked",
+      "Keyboard navigable with Tab and arrow keys",
+      "Focus visible on active item"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic toggle group",
+      "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"left\">Left</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"center\">Center</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"right\">Right</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Pills Variant",
+      "description": "Pill-shaped toggle buttons",
+      "code": "<ToggleGroup value={value} onChange={setValue} variant=\"pills\">\n  <ToggleGroup.Item value=\"all\">All</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"active\">Active</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"completed\">Completed</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Outline Variant",
+      "description": "Outlined toggle buttons",
+      "code": "<ToggleGroup value={value} onChange={setValue} variant=\"outlined\">\n  <ToggleGroup.Item value=\"day\">Day</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"week\">Week</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"month\">Month</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Uncontrolled",
+      "description": "Use defaultValue for simple single-select state",
+      "code": "<ToggleGroup defaultValue=\"list\">\n  <ToggleGroup.Item value=\"grid\">Grid</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\">List</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Different size variants",
+      "code": "<ToggleGroup value={value} onChange={setValue} size=\"sm\">\n  <ToggleGroup.Item value=\"a\">Small</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>\n<ToggleGroup value={value} onChange={setValue} size=\"md\">\n  <ToggleGroup.Item value=\"a\">Medium</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"b\">Size</ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "View Switcher",
+      "description": "Common pattern for switching between views",
+      "code": "<ToggleGroup value={view} onChange={setView} size=\"sm\">\n  <ToggleGroup.Item value=\"grid\"><GridIcon /></ToggleGroup.Item>\n  <ToggleGroup.Item value=\"list\"><ListIcon /></ToggleGroup.Item>\n</ToggleGroup>"
+    },
+    {
+      "name": "With Disabled Item",
+      "description": "Toggle group with a disabled option",
+      "code": "<ToggleGroup value={value} onChange={setValue}>\n  <ToggleGroup.Item value=\"basic\">Basic</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"pro\">Pro</ToggleGroup.Item>\n  <ToggleGroup.Item value=\"enterprise\" disabled>Enterprise</ToggleGroup.Item>\n</ToggleGroup>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "RadioGroup",
+      "relationship": "alternative",
+      "note": "RadioGroup for form-style single selection"
+    },
+    {
+      "component": "Tabs",
+      "relationship": "alternative",
+      "note": "Tabs for content panel switching"
+    },
+    {
+      "component": "Switch",
+      "relationship": "sibling",
+      "note": "Switch for single on/off control"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value?: string - controlled selected value",
+      "defaultValue?: string - initial selected value (uncontrolled)",
+      "onChange: (value: string) => void - change handler (or onValueChange)",
+      "children: ToggleGroup.Item[] - toggle items",
+      "variant: default|pills|outline|outlined - visual style (outlined aliases outline)",
+      "size: sm|md - size variant",
+      "gap: none|xs|sm - spacing",
+      "selectionMode: single (default: single)"
+    ],
+    "a11yRules": [
+      "A11Y_GROUP_ROLE",
+      "A11Y_KEYBOARD_ACCESSIBLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:07.233Z"
+  }
+}