@fragments-sdk/ui 0.17.1 → 0.19.0

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/Toggle/Toggle.module.scss

@@ -62,7 +62,7 @@
   width: var(--fui-toggle-width-sm, $fui-toggle-width-sm);
   height: var(--fui-toggle-height-sm, $fui-toggle-height-sm);
   --_toggle-thumb-size: calc(var(--fui-toggle-height-sm, #{$fui-toggle-height-sm}) - 4px);
-  --_toggle-inset: 2px;
+  --_toggle-inset: 1px;
   --_toggle-translate: calc(
     var(--fui-toggle-width-sm, #{$fui-toggle-width-sm}) -
     var(--_toggle-thumb-size) -
@@ -75,7 +75,7 @@
   width: var(--fui-toggle-width-lg, $fui-toggle-width-lg);
   height: var(--fui-toggle-height-lg, $fui-toggle-height-lg);
   --_toggle-thumb-size: calc(var(--fui-toggle-height-lg, #{$fui-toggle-height-lg}) - 4px);
-  --_toggle-inset: 2px;
+  --_toggle-inset: 1px;
   --_toggle-translate: calc(
     var(--fui-toggle-width-lg, #{$fui-toggle-width-lg}) -
     var(--_toggle-thumb-size) -
@@ -88,7 +88,7 @@
   width: var(--fui-toggle-width-md, $fui-toggle-width-md);
   height: var(--fui-toggle-height-md, $fui-toggle-height-md);
   --_toggle-thumb-size: calc(var(--fui-toggle-height-md, #{$fui-toggle-height-md}) - 4px);
-  --_toggle-inset: 2px;
+  --_toggle-inset: 1px;
   --_toggle-translate: calc(
     var(--fui-toggle-width-md, #{$fui-toggle-width-md}) -
     var(--_toggle-thumb-size) -

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

package/src/components/Tooltip/Tooltip.contract.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Tooltip",
+  "description": "Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context.",
+  "category": "feedback",
+  "tags": [
+    "tooltip",
+    "hint",
+    "help",
+    "hover",
+    "contextual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Tooltip/index.tsx",
+  "exportName": "Tooltip",
+  "propsSummary": [
+    "children: element (required)",
+    "content: node (required)",
+    "side: top|bottom|left|right (default: top)",
+    "align: start|center|end (default: center)",
+    "sideOffset: number (default: 6)",
+    "delay: number",
+    "closeDelay: number",
+    "disabled: boolean (default: false)",
+    "arrow: boolean (default: true)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "contentProps: object",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "element",
+      "description": "The element that triggers the tooltip",
+      "required": true
+    },
+    "content": {
+      "type": "node",
+      "description": "Content to display in the tooltip",
+      "required": true
+    },
+    "side": {
+      "type": "enum",
+      "description": "Which side to show the tooltip",
+      "default": "top",
+      "required": false,
+      "values": [
+        "top",
+        "bottom",
+        "left",
+        "right"
+      ]
+    },
+    "align": {
+      "type": "enum",
+      "description": "Alignment along the side",
+      "default": "center",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end"
+      ]
+    },
+    "sideOffset": {
+      "type": "number",
+      "description": "Distance from trigger in pixels",
+      "default": "6",
+      "required": false
+    },
+    "delay": {
+      "type": "number",
+      "description": "Delay before showing (ms)",
+      "default": "400",
+      "required": false
+    },
+    "closeDelay": {
+      "type": "number",
+      "description": "Delay before hiding (ms)",
+      "default": "0",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the tooltip",
+      "default": "false",
+      "required": false
+    },
+    "arrow": {
+      "type": "boolean",
+      "description": "Show arrow pointing to trigger",
+      "default": "true",
+      "required": false
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Callback when open state changes",
+      "required": false
+    },
+    "contentProps": {
+      "type": "object",
+      "description": "Props forwarded to the tooltip popup element (preferred way to pass popup attrs/className/style)",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Explaining icon-only buttons",
+      "Showing full text for truncated content",
+      "Providing keyboard shortcuts",
+      "Brief contextual help that fits in one line"
+    ],
+    "whenNot": [
+      "Long-form help content (use Popover)",
+      "Critical information users must see (use Alert)",
+      "Interactive content (use Popover or Menu)",
+      "Mobile-primary interfaces (tooltips require hover)"
+    ],
+    "guidelines": [
+      "Keep tooltip text concise (under 80 characters)",
+      "Use sentence case, no period for single sentences",
+      "Avoid duplicating visible label text",
+      "Consider mobile users who cannot hover",
+      "Use contentProps for tooltip popup attributes/styling; top-level HTML attrs are applied to the popup for backward compatibility"
+    ],
+    "accessibility": [
+      "Accessible via focus as well as hover",
+      "Uses role=\"tooltip\" with proper aria association",
+      "Delay prevents tooltips from appearing during navigation"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic tooltip on hover",
+      "code": "<Tooltip content=\"Save your changes\">\n  <Button>Save</Button>\n</Tooltip>"
+    },
+    {
+      "name": "Positions",
+      "description": "Tooltips on different sides",
+      "code": "<div style={{ display: 'flex', gap: '16px', padding: '40px' }}>\n  <Tooltip content=\"Top tooltip\" side=\"top\">\n    <Button variant=\"secondary\">Top</Button>\n  </Tooltip>\n  <Tooltip content=\"Bottom tooltip\" side=\"bottom\">\n    <Button variant=\"secondary\">Bottom</Button>\n  </Tooltip>\n  <Tooltip content=\"Left tooltip\" side=\"left\">\n    <Button variant=\"secondary\">Left</Button>\n  </Tooltip>\n  <Tooltip content=\"Right tooltip\" side=\"right\">\n    <Button variant=\"secondary\">Right</Button>\n  </Tooltip>\n</div>"
+    },
+    {
+      "name": "With Shortcut",
+      "description": "Tooltip showing keyboard shortcut",
+      "code": "<Tooltip content=\"Undo (Ctrl+Z)\">\n  <Button variant=\"ghost\">Undo</Button>\n</Tooltip>"
+    },
+    {
+      "name": "No Arrow",
+      "description": "Tooltip without arrow",
+      "code": "<Tooltip content=\"Clean tooltip\" arrow={false}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+    },
+    {
+      "name": "With Content Props",
+      "description": "Pass popup attributes/styling using contentProps",
+      "code": "<Tooltip content=\"Custom popup attrs\" contentProps={{ id: 'custom-tooltip-popup' }}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Popover",
+      "relationship": "alternative",
+      "note": "Use Popover for interactive or longer content"
+    },
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for critical information that must be visible"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "content: ReactNode - tooltip content",
+      "side: top|bottom|left|right - position",
+      "delay: number - show delay in ms (default: 400)",
+      "arrow: boolean - show arrow (default: true)",
+      "contentProps: HTMLAttributes<HTMLDivElement> - popup element props"
+    ],
+    "a11yRules": [
+      "A11Y_TOOLTIP_FOCUS",
+      "A11Y_TOOLTIP_ROLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root",
+      "Provider"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:07.058Z"
+  }
+}