@fragments-sdk/ui 0.17.1 → 0.18.0

package/src/components/Popover/Popover.contract.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Popover",
+  "description": "Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context.",
+  "category": "feedback",
+  "tags": [
+    "popover",
+    "overlay",
+    "dropdown",
+    "floating",
+    "contextual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Popover/index.tsx",
+  "exportName": "Popover",
+  "propsSummary": [
+    "children: node (required)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "modal: boolean (default: false)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Popover trigger and content",
+      "required": true
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state (uncontrolled)",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Called when open state changes",
+      "required": false
+    },
+    "modal": {
+      "type": "boolean",
+      "description": "Whether to block page interaction",
+      "default": "false",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Inline editing forms",
+      "Rich preview content",
+      "Filter panels",
+      "Date/color pickers",
+      "Content that needs more space than a tooltip"
+    ],
+    "whenNot": [
+      "Simple hints (use Tooltip)",
+      "Action lists (use Menu)",
+      "Blocking user interaction (use Dialog)",
+      "System notifications (use Toast or Alert)"
+    ],
+    "guidelines": [
+      "Keep popover content focused and minimal",
+      "Include a clear way to close (X button or action buttons)",
+      "Position to avoid covering important content",
+      "Use arrow to visually connect popover to trigger",
+      "Popover.Trigger and Popover.Close support asChild for links/router-link components (single valid element child required)"
+    ],
+    "accessibility": [
+      "Focus is moved to popover content on open",
+      "Closes on Escape key",
+      "Focus returns to trigger on close"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic popover with content",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Open Popover</Button>\n  </Popover.Trigger>\n  <Popover.Content>\n    <Popover.Close />\n    <Popover.Title>Popover Title</Popover.Title>\n    <Popover.Description>\n      This is a popover with some content. It can contain text, forms, or other elements.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "With Form",
+      "description": "Popover containing a form",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Edit Name</Button>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Close />\n    <Popover.Title>Edit Name</Popover.Title>\n    <Popover.Body>\n      <Input label=\"Display Name\" placeholder=\"Enter name\" />\n    </Popover.Body>\n    <Popover.Footer>\n      <Popover.Close asChild>\n        <Button variant=\"secondary\" size=\"sm\">Cancel</Button>\n      </Popover.Close>\n      <Button variant=\"primary\" size=\"sm\">Save</Button>\n    </Popover.Footer>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "With Arrow",
+      "description": "Popover with pointing arrow",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <Button variant=\"secondary\">Info</Button>\n  </Popover.Trigger>\n  <Popover.Content arrow>\n    <Popover.Title>Quick Tip</Popover.Title>\n    <Popover.Description>\n      This popover has an arrow pointing to its trigger element.\n    </Popover.Description>\n  </Popover.Content>\n</Popover>"
+    },
+    {
+      "name": "Positions",
+      "description": "Popover on different sides",
+      "code": "<div style={{ display: 'flex', gap: '16px', padding: '60px' }}>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Top</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"top\" size=\"sm\">\n      <Popover.Description>Popover on top</Popover.Description>\n    </Popover.Content>\n  </Popover>\n  <Popover>\n    <Popover.Trigger asChild>\n      <Button variant=\"secondary\">Bottom</Button>\n    </Popover.Trigger>\n    <Popover.Content side=\"bottom\" size=\"sm\">\n      <Popover.Description>Popover on bottom</Popover.Description>\n    </Popover.Content>\n  </Popover>\n</div>"
+    },
+    {
+      "name": "Link Trigger",
+      "description": "Use asChild with a non-button trigger element",
+      "code": "<Popover>\n  <Popover.Trigger asChild>\n    <a href=\"#popover-help\">Open help</a>\n  </Popover.Trigger>\n  <Popover.Content size=\"sm\">\n    <Popover.Description>Popover trigger can be an anchor when using asChild.</Popover.Description>\n  </Popover.Content>\n</Popover>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Tooltip",
+      "relationship": "alternative",
+      "note": "Use Tooltip for brief, non-interactive hints"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu for action lists"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "alternative",
+      "note": "Use Dialog for blocking interactions"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "open: boolean - controlled open state",
+      "onOpenChange: (open) => void - state handler",
+      "modal: boolean - blocks page interaction (default: false)",
+      "Popover.Trigger / Popover.Close asChild support non-button children",
+      "Popover.Content side: top|bottom|left|right - position"
+    ],
+    "a11yRules": [
+      "A11Y_POPOVER_FOCUS",
+      "A11Y_POPOVER_ESCAPE",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Trigger",
+      "Content",
+      "Close",
+      "Title",
+      "Description",
+      "Body",
+      "Footer"
+    ],
+    "requiredChildren": [
+      "Trigger",
+      "Content"
+    ],
+    "commonPatterns": [
+      "<Popover><Popover.Trigger asChild><Button>Open</Button></Popover.Trigger><Popover.Content><Popover.Close /><Popover.Title>{title}</Popover.Title><Popover.Description>{description}</Popover.Description></Popover.Content></Popover>",
+      "<Popover><Popover.Trigger asChild><a href=\"#help\">Open help</a></Popover.Trigger><Popover.Content>...</Popover.Content></Popover>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.154Z"
+  }
+}

package/src/components/Progress/Progress.contract.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Progress",
+  "description": "Visual indicator of task completion or loading state. Available in linear and circular variants.",
+  "category": "feedback",
+  "tags": [
+    "progress",
+    "loading",
+    "indicator",
+    "percentage",
+    "status"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Progress/index.tsx",
+  "exportName": "Progress",
+  "propsSummary": [
+    "value: number (default: null)",
+    "min: number (default: 0)",
+    "max: number (default: 100)",
+    "size: sm|md|lg (default: md)",
+    "variant: default|success|warning|danger (default: default)",
+    "label: string",
+    "showValue: boolean (default: false)",
+    "formatValue: function"
+  ],
+  "props": {
+    "value": {
+      "type": "number",
+      "description": "Current progress value (0-100). Null for indeterminate.",
+      "default": "null",
+      "required": false
+    },
+    "min": {
+      "type": "number",
+      "description": "Minimum value",
+      "default": "0",
+      "required": false
+    },
+    "max": {
+      "type": "number",
+      "description": "Maximum value",
+      "default": "100",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size of the progress bar",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Color variant",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "success",
+        "warning",
+        "danger"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text above the progress bar",
+      "required": false
+    },
+    "showValue": {
+      "type": "boolean",
+      "description": "Show percentage value",
+      "default": "false",
+      "required": false
+    },
+    "formatValue": {
+      "type": "function",
+      "description": "Custom formatter for displayed progress value",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Showing upload/download progress",
+      "Displaying task completion percentage",
+      "Form completion indicators",
+      "Loading states with known duration"
+    ],
+    "whenNot": [
+      "Unknown loading duration (use Spinner)",
+      "Step-based progress (use Stepper)",
+      "Status without percentage (use Badge)"
+    ],
+    "guidelines": [
+      "Use determinate progress when you know the completion percentage",
+      "Use indeterminate for unknown durations",
+      "Include a label for context when the purpose isnt obvious",
+      "Use appropriate color variants for success/warning/danger states",
+      "Determinate values are clamped to the min/max range for display"
+    ],
+    "accessibility": [
+      "Uses role=\"progressbar\" with aria-valuenow",
+      "Label is associated with the progress bar",
+      "State changes are announced to screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic progress bar with percentage",
+      "code": "<Progress value={60} label=\"Uploading...\" showValue />"
+    },
+    {
+      "name": "Variants",
+      "description": "Different color variants for different states",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={75} variant=\"default\" label=\"Processing\" showValue />\n  <Progress value={100} variant=\"success\" label=\"Complete\" showValue />\n  <Progress value={80} variant=\"warning\" label=\"Almost full\" showValue />\n  <Progress value={95} variant=\"danger\" label=\"Storage critical\" showValue />\n</div>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Different progress bar sizes",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={50} size=\"sm\" label=\"Small\" />\n  <Progress value={50} size=\"md\" label=\"Medium\" />\n  <Progress value={50} size=\"lg\" label=\"Large\" />\n</div>"
+    },
+    {
+      "name": "Indeterminate",
+      "description": "Loading state with unknown duration",
+      "code": "<Progress value={null} label=\"Loading...\" />"
+    },
+    {
+      "name": "Circular",
+      "description": "Circular progress indicator",
+      "code": "<div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>\n  <CircularProgress value={25} size=\"sm\" />\n  <CircularProgress value={50} size=\"md\" showValue />\n  <CircularProgress value={75} size=\"lg\" showValue variant=\"success\" />\n  <CircularProgress value={null} size=\"md\" />\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "alternative",
+      "note": "Use Badge for status without percentage"
+    },
+    {
+      "component": "Alert",
+      "relationship": "sibling",
+      "note": "Use Alert for completion messages"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: number|null - progress percentage (null for indeterminate)",
+      "size: sm|md|lg - bar thickness",
+      "variant: default|success|warning|danger - color",
+      "label: string - descriptive label",
+      "showValue: boolean - display percentage",
+      "Determinate display values are clamped (and invalid min/max ranges render as 0%)"
+    ],
+    "a11yRules": [
+      "A11Y_PROGRESS_ROLE",
+      "A11Y_PROGRESS_VALUE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root",
+      "Circular"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.339Z"
+  }
+}

package/src/components/Prompt/Prompt.contract.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Prompt",
+  "description": "Multi-line input with toolbar for AI/chat interfaces",
+  "category": "ai",
+  "tags": [
+    "prompt",
+    "chat",
+    "ai",
+    "input",
+    "textarea",
+    "form"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Prompt/index.tsx",
+  "exportName": "Prompt",
+  "propsSummary": [
+    "children: node (required)",
+    "value: string",
+    "defaultValue: string (default: )",
+    "onChange: function",
+    "onSubmit: function",
+    "placeholder: string (default: Ask, Search or Chat...)",
+    "disabled: boolean (default: false)",
+    "loading: boolean (default: false)",
+    "minRows: number (default: 1)",
+    "maxRows: number (default: 8)",
+    "autoResize: boolean (default: true)",
+    "submitOnEnter: boolean (default: true)",
+    "variant: default|fixed|sticky (default: default)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Prompt composition using Prompt sub-components",
+      "required": true
+    },
+    "value": {
+      "type": "string",
+      "description": "Controlled input value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Uncontrolled default value",
+      "default": "",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called when value changes",
+      "required": false
+    },
+    "onSubmit": {
+      "type": "function",
+      "description": "Called on form submission",
+      "required": false
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Placeholder text for the textarea",
+      "default": "Ask, Search or Chat...",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the entire prompt",
+      "default": "false",
+      "required": false
+    },
+    "loading": {
+      "type": "boolean",
+      "description": "Show loading state",
+      "default": "false",
+      "required": false
+    },
+    "minRows": {
+      "type": "number",
+      "description": "Minimum number of visible rows",
+      "default": "1",
+      "required": false
+    },
+    "maxRows": {
+      "type": "number",
+      "description": "Maximum number of visible rows",
+      "default": "8",
+      "required": false
+    },
+    "autoResize": {
+      "type": "boolean",
+      "description": "Enable auto-resize based on content",
+      "default": "true",
+      "required": false
+    },
+    "submitOnEnter": {
+      "type": "boolean",
+      "description": "Submit on Enter (Shift+Enter for newline)",
+      "default": "true",
+      "required": false
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual/positioning variant",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "fixed",
+        "sticky"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Building chat or AI assistant interfaces",
+      "Need multi-line input with submit action",
+      "Require toolbar with actions like attachments or model selection"
+    ],
+    "whenNot": [
+      "Simple single-line text input (use Input)",
+      "Basic multi-line without toolbar (use Textarea)",
+      "Search-only interface (use Input with search variant)"
+    ],
+    "guidelines": [
+      "Always provide an onSubmit handler",
+      "Use loading state during API calls",
+      "Prompt.Textarea forwards native textarea props (autoComplete, inputMode, aria-*, data-*, handlers)",
+      "Prompt.Textarea composes your onChange/onKeyDown handlers with built-in submit and auto-resize behavior",
+      "Consider showing usage/token limits for AI contexts"
+    ],
+    "accessibility": [
+      "Enter submits, Shift+Enter for newline",
+      "Submit button is keyboard accessible",
+      "Loading state prevents duplicate submissions"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Basic",
+      "description": "Simple prompt with submit button",
+      "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions />\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
+    {
+      "name": "With Actions",
+      "description": "Prompt with attachment and mode buttons",
+      "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
+    {
+      "name": "With Usage",
+      "description": "Shows token usage indicator",
+      "code": "<Prompt onSubmit={(value) => console.log(value)}>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton active>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Usage>52% used</Prompt.Usage>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
+    {
+      "name": "Loading State",
+      "description": "During API submission",
+      "code": "<Prompt\n  onSubmit={(value) => console.log(value)}\n  loading\n  defaultValue=\"Tell me about the weather...\"\n>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n      <Prompt.ModeButton>Auto</Prompt.ModeButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Usage>52% used</Prompt.Usage>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive prompt",
+      "code": "<Prompt onSubmit={(value) => console.log(value)} disabled>\n  <Prompt.Textarea />\n  <Prompt.Toolbar>\n    <Prompt.Actions>\n      <Prompt.ActionButton aria-label=\"Add attachment\">\n        +\n      </Prompt.ActionButton>\n    </Prompt.Actions>\n    <Prompt.Info>\n      <Prompt.Submit />\n    </Prompt.Info>\n  </Prompt.Toolbar>\n</Prompt>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for simple single-line text input"
+    },
+    {
+      "component": "Textarea",
+      "relationship": "alternative",
+      "note": "Use Textarea for multi-line without toolbar"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - controlled input value",
+      "onSubmit: (value: string) => void - submission handler",
+      "placeholder: string - hint text (default: \"Ask, Search or Chat...\")",
+      "disabled: boolean - disables interaction",
+      "loading: boolean - shows loading state",
+      "minRows/maxRows: number - row constraints (default: 1/8)",
+      "submitOnEnter: boolean - Enter key behavior (default: true)",
+      "Prompt.Textarea accepts native textarea props and optional aria-label override"
+    ],
+    "a11yRules": [
+      "A11Y_TEXTAREA_LABEL",
+      "A11Y_BUTTON_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Textarea",
+      "Toolbar",
+      "Actions",
+      "Info",
+      "ActionButton",
+      "ModeButton",
+      "Usage",
+      "Submit"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.513Z"
+  }
+}