@usefragments/ui 1.0.0

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

@@ -0,0 +1,213 @@
+{
+  "$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",
+      "Tabs",
+      "Tab",
+      "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

@@ -0,0 +1,346 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Prompt Root
+// ============================================
+
+.prompt {
+  @include surface-elevated;
+  display: flex;
+  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 var(--fui-transition-normal, $fui-transition-normal);
+  }
+
+  // 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;
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  width: calc(100% - var(--fui-space-8, $fui-space-8));
+  max-width: 800px;
+  z-index: 100;
+  box-shadow: var(--fui-shadow-lg, $fui-shadow-lg);
+}
+
+// Sticky variant - for content-area fixed prompts (accounts for sidebar)
+// Use --fui-prompt-inset-left CSS variable to offset from sidebar
+.sticky {
+  position: fixed;
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: var(--fui-prompt-inset-left, 0);
+  right: 0;
+  margin-left: auto;
+  margin-right: auto;
+  width: calc(100% - var(--fui-prompt-inset-left, 0px) - var(--fui-space-8, $fui-space-8));
+  max-width: 800px;
+  z-index: 100;
+  box-shadow: var(--fui-shadow-lg, $fui-shadow-lg);
+
+  // Center within the available space (after sidebar)
+  left: calc(var(--fui-prompt-inset-left, 0px) + ((100% - var(--fui-prompt-inset-left, 0px)) / 2));
+  transform: translateX(-50%);
+}
+
+// ============================================
+// Textarea
+// ============================================
+
+.textarea {
+  @include button-reset;
+  @include text-base;
+
+  display: block;
+  width: 100%;
+  min-height: var(--fui-input-height, $fui-input-height);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  background: transparent;
+  border: none;
+  resize: none;
+  overflow-y: auto;
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  // Focus is shown on the prompt container via :focus-within instead
+  &:focus,
+  &:focus-visible {
+    outline: none;
+    box-shadow: none;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+// ============================================
+// 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: var(--fui-space-px, $fui-space-px);
+  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: var(--fui-space-0-75, $fui-space-0-75) var(--fui-space-0-75, $fui-space-0-75) 0;
+  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:
+    color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
+  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
+// ============================================
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  border-top: 1px solid var(--fui-border, $fui-border);
+}
+
+// ============================================
+// Actions & Info
+// ============================================
+
+.actions {
+  display: flex;
+  align-items: center;
+  align-self: flex-end;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.info {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-left: auto;
+}
+
+// ============================================
+// Action Button (circular, e.g. "+")
+// ============================================
+
+.actionButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// ============================================
+// Mode Button (text button, e.g. "Auto")
+// ============================================
+
+.modeButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.modeButtonActive {
+  color: var(--fui-text-primary, $fui-text-primary);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+}
+
+// ============================================
+// Usage indicator
+// ============================================
+
+.usage {
+  @include helper-text;
+  white-space: nowrap;
+}
+
+// ============================================
+// Submit Button
+// ============================================
+
+.submit {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-on-accent, $fui-color-on-accent);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+.submitLoading {
+  pointer-events: none;
+}
+
+.submitSpinner {
+  line-height: 0;
+}

package/src/components/Prompt/Prompt.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Prompt } from '.';
+
+/**
+ * Prompt is a multi-line input with toolbar for AI and chat interfaces.
+ * It is a compound component composed from Prompt.Textarea, Prompt.Toolbar,
+ * Prompt.Actions, Prompt.Info, and Prompt.Submit.
+ */
+const meta = {
+  title: 'Ai/Prompt',
+  component: Prompt,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Multi-line input with toolbar for AI and chat interfaces.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'fixed', 'sticky'],
+      description: 'Visual/positioning variant',
+    },
+    disabled: { control: 'boolean', description: 'Disable the entire prompt' },
+    loading: { control: 'boolean', description: 'Show loading state' },
+    submitOnEnter: {
+      control: 'boolean',
+      description: 'Submit on Enter (Shift+Enter for newline)',
+    },
+    autoResize: { control: 'boolean', description: 'Enable auto-resize based on content' },
+    placeholder: { control: 'text', description: 'Placeholder text for the textarea' },
+  },
+  args: {
+    placeholder: 'Ask, Search or Chat...',
+    variant: 'default',
+    children: (
+      <>
+        <Prompt.Textarea />
+        <Prompt.Toolbar>
+          <Prompt.Actions />
+          <Prompt.Info>
+            <Prompt.Submit />
+          </Prompt.Info>
+        </Prompt.Toolbar>
+      </>
+    ),
+  },
+  render: (args) => (
+    <Prompt {...args} onSubmit={(value) => console.log(value)}>
+      <Prompt.Textarea />
+      <Prompt.Toolbar>
+        <Prompt.Actions />
+        <Prompt.Info>
+          <Prompt.Submit />
+        </Prompt.Info>
+      </Prompt.Toolbar>
+    </Prompt>
+  ),
+} satisfies Meta<typeof Prompt>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {};
+
+export const WithActions: Story = {
+  render: (args) => (
+    <Prompt {...args} onSubmit={(value) => console.log(value)}>
+      <Prompt.Textarea />
+      <Prompt.Toolbar>
+        <Prompt.Actions>
+          <Prompt.ActionButton aria-label="Add attachment">+</Prompt.ActionButton>
+          <Prompt.ModeButton active>Auto</Prompt.ModeButton>
+        </Prompt.Actions>
+        <Prompt.Info>
+          <Prompt.Usage>52% used</Prompt.Usage>
+          <Prompt.Submit />
+        </Prompt.Info>
+      </Prompt.Toolbar>
+    </Prompt>
+  ),
+};
+
+export const Loading: Story = {
+  args: { loading: true, defaultValue: 'Tell me about the weather...' },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};