@fragments-sdk/ui 0.17.1 → 0.19.0

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

package/src/components/Prompt/Prompt.module.scss

@@ -11,13 +11,77 @@
   flex-direction: column;
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   overflow: hidden;
+  position: relative;
+
+  // Beam border — rotating conic gradient clipped to a 1px border
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    pointer-events: none;
+  }
+
+  // Gradient layer (behind everything)
+  &::before {
+    inset: -1px;
+    z-index: 0;
+    background: conic-gradient(
+      from var(--beam-angle, 0deg) at 50% 50%,
+      transparent 0%,
+      transparent 25%,
+      var(--fui-color-accent, $fui-color-accent) 45%,
+      transparent 50%,
+      transparent 55%,
+      color-mix(in srgb, var(--fui-color-accent, $fui-color-accent) 40%, transparent) 70%,
+      transparent 75%,
+      transparent 100%
+    );
+    animation: beam-rotate 4s linear infinite;
+    opacity: 0.6;
+    transition: opacity 300ms ease;
+  }
+
+  // Mask layer — covers the interior, leaving only the 1px border visible
+  &::after {
+    inset: 1px;
+    z-index: 1;
+    background: var(--fui-bg-elevated, $fui-bg-elevated);
+  }
+
+  // Content must sit above the mask
+  > * {
+    position: relative;
+    z-index: 2;
+  }
+
+  &:focus-within::before {
+    opacity: 1;
+  }
 
   &[data-disabled] {
     opacity: 0.5;
     pointer-events: none;
+
+    &::before {
+      animation-play-state: paused;
+      opacity: 0.2;
+    }
   }
 }
 
+@keyframes beam-rotate {
+  from { --beam-angle: 0deg; }
+  to { --beam-angle: 360deg; }
+}
+
+@property --beam-angle {
+  syntax: '<angle>';
+  initial-value: 0deg;
+  inherits: false;
+}
+
 // Fixed variant - for viewport-fixed prompts (centered to page)
 .fixed {
   position: fixed;
@@ -71,9 +135,11 @@
     color: var(--fui-text-tertiary, $fui-text-tertiary);
   }
 
+  // Focus is shown on the prompt container via :focus-within instead
+  &:focus,
   &:focus-visible {
-    @include focus-ring;
-    border-radius: var(--fui-radius-md, $fui-radius-md);
+    outline: none;
+    box-shadow: none;
   }
 
   &:disabled {
@@ -81,6 +147,52 @@
   }
 }
 
+// ============================================
+// Tabs (floating above the prompt body)
+// ============================================
+
+.tabs {
+  display: flex;
+  justify-content: center;
+  margin-bottom: calc(-1 * var(--fui-space-1, $fui-space-1)); // overlap the prompt border
+  position: relative;
+  z-index: 1;
+}
+
+.tabsInner {
+  display: inline-flex;
+  gap: 1px;
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg) var(--fui-radius-lg, $fui-radius-lg) 0 0;
+  padding: 3px 3px 0 3px;
+  border: 1px solid var(--fui-border, $fui-border);
+  border-bottom: none;
+}
+
+.tabButton {
+  @include button-reset;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-md, $fui-radius-md) var(--fui-radius-md, $fui-radius-md) 0 0;
+  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-tertiary, $fui-text-tertiary);
+  transition: all 120ms ease;
+  white-space: nowrap;
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.tabButtonActive {
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
 // ============================================
 // Toolbar
 // ============================================
@@ -102,7 +214,9 @@
 .actions {
   display: flex;
   align-items: center;
+  align-self: flex-end;
   gap: var(--fui-space-1, $fui-space-1);
+  padding: 0 var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2) 0;
 }
 
 .info {
@@ -201,7 +315,7 @@
   height: 2rem;
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: var(--fui-color-accent, $fui-color-accent);
-  color: var(--fui-text-inverse, $fui-text-inverse);
+  color: var(--fui-color-on-accent, $fui-color-on-accent);
 
   &:hover:not(:disabled) {
     background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);

package/src/components/Prompt/index.tsx

@@ -55,6 +55,20 @@ export interface PromptToolbarProps {
   className?: string;
 }
 
+export interface PromptTabsProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface PromptTabProps {
+  children: React.ReactNode;
+  /** Whether this tab is currently active */
+  active?: boolean;
+  /** Click handler */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  className?: string;
+}
+
 export interface PromptActionsProps {
   children?: React.ReactNode;
   className?: string;
@@ -330,6 +344,28 @@ function PromptToolbar({ children, className }: PromptToolbarProps) {
   return <div className={classes}>{children}</div>;
 }
 
+function PromptTabs({ children, className }: PromptTabsProps) {
+  const classes = [styles.tabs, className].filter(Boolean).join(' ');
+  return (
+    <div className={classes}>
+      <div className={styles.tabsInner}>{children}</div>
+    </div>
+  );
+}
+
+function PromptTab({ children, active = false, onClick, className }: PromptTabProps) {
+  const classes = [
+    styles.tabButton,
+    active && styles.tabButtonActive,
+    className,
+  ].filter(Boolean).join(' ');
+  return (
+    <button type="button" className={classes} onClick={onClick} aria-pressed={active}>
+      {children}
+    </button>
+  );
+}
+
 function PromptActions({ children, className }: PromptActionsProps) {
   if (!children) return null;
   const classes = [styles.actions, className].filter(Boolean).join(' ');
@@ -444,6 +480,8 @@ function PromptSubmit({
 export const Prompt = Object.assign(PromptRoot, {
   Textarea: PromptTextarea,
   Toolbar: PromptToolbar,
+  Tabs: PromptTabs,
+  Tab: PromptTab,
   Actions: PromptActions,
   Info: PromptInfo,
   ActionButton: PromptActionButton,
@@ -456,6 +494,8 @@ export {
   PromptRoot,
   PromptTextarea,
   PromptToolbar,
+  PromptTabs,
+  PromptTab,
   PromptActions,
   PromptInfo,
   PromptActionButton,