@slipstream-ui/ai 0.0.0-stage → 0.4.0

package/src/manifests/prompt-input.manifest.json

@@ -0,0 +1,334 @@
+{
+  "id": "prompt-input",
+  "name": "PromptInput",
+  "tier": "molecule",
+  "description": "A textarea input for entering chat prompts with auto-resize, keyboard shortcuts, and send button",
+  "designIntent": "The PromptInput component provides a specialized input for chat interfaces. It handles auto-resizing as the user types, supports Enter to submit (Shift+Enter for new line), and integrates with the conversation flow. It's designed to be the primary way users interact with AI assistants.",
+  "props": [
+    {
+      "name": "onSubmit",
+      "type": "(value: string) => void",
+      "required": true,
+      "description": "Callback when the user submits the prompt",
+      "examples": [
+        "(value) => sendMessage(value)"
+      ]
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "defaultValue": "Type your message...",
+      "required": false,
+      "description": "Placeholder text to display when input is empty",
+      "examples": [
+        "Type your message...",
+        "Ask me anything...",
+        "Enter your prompt..."
+      ]
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "defaultValue": "false",
+      "required": false,
+      "description": "Whether the input is disabled",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "isLoading",
+      "type": "boolean",
+      "defaultValue": "false",
+      "required": false,
+      "description": "Whether a submission is currently in progress",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "autoFocus",
+      "type": "boolean",
+      "defaultValue": "false",
+      "required": false,
+      "description": "Whether to auto-focus the input on mount",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "maxLength",
+      "type": "number",
+      "required": false,
+      "description": "Maximum character count for the input",
+      "examples": [
+        500,
+        1000,
+        2000
+      ]
+    },
+    {
+      "name": "showSendButton",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Whether to show the send button",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "sendButtonText",
+      "type": "string",
+      "defaultValue": "Send",
+      "required": false,
+      "description": "Text or icon for the send button",
+      "examples": [
+        "Send",
+        "Submit",
+        "→"
+      ]
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply to the container"
+    },
+    {
+      "name": "onStop",
+      "type": "() => void",
+      "required": false,
+      "description": "While loading, the send button becomes a stop button that calls this handler."
+    },
+    {
+      "name": "stopButtonText",
+      "type": "string",
+      "defaultValue": "Stop generating",
+      "required": false,
+      "description": "Accessible label for the stop button; enables localization."
+    },
+    {
+      "name": "attachments",
+      "type": "AttachmentItem[]",
+      "required": false,
+      "description": "Controlled attachment list shown as chips above the input"
+    },
+    {
+      "name": "onRemoveAttachment",
+      "type": "(id: string) => void",
+      "required": false,
+      "description": "Called when the user removes an attachment chip"
+    },
+    {
+      "name": "onAttachmentsChange",
+      "type": "(attachments: AttachmentItem[]) => void",
+      "required": false,
+      "description": "Called when files are added via drag-and-drop, paste, or picker"
+    },
+    {
+      "name": "hasError",
+      "type": "boolean",
+      "required": false,
+      "description": "Styles the input in an error state (e.g. after a rejected file)"
+    },
+    {
+      "name": "accept",
+      "type": "string",
+      "required": false,
+      "description": "MIME types accepted for attachments (e.g. \"image/*\")"
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "required": false,
+      "description": "Allow selecting multiple files"
+    },
+    {
+      "name": "maxFiles",
+      "type": "number",
+      "required": false,
+      "description": "Maximum number of attachments allowed"
+    },
+    {
+      "name": "maxFileSize",
+      "type": "number",
+      "required": false,
+      "description": "Maximum file size in bytes; rejects larger files"
+    },
+    {
+      "name": "onAttachmentError",
+      "type": "(error: string) => void",
+      "required": false,
+      "description": "Called when an attachment is rejected (size, type, or count limit)"
+    },
+    {
+      "name": "globalDrop",
+      "type": "boolean",
+      "required": false,
+      "description": "Enable drop-anywhere-on-page file acceptance"
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Custom content rendered inside the input row (e.g. tool buttons)"
+    },
+    {
+      "name": "tooltip",
+      "required": false,
+      "type": "string | { content: ReactNode; shortcut?: string }",
+      "description": "Tooltip content for a toolbar button; optionally includes a keyboard shortcut hint (PromptInput.Button sub-component)"
+    },
+    {
+      "name": "active",
+      "required": false,
+      "defaultValue": "false",
+      "type": "boolean",
+      "description": "Toggles the active state on a toolbar button (PromptInput.Button sub-component)"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Basic prompt input",
+      "code": "<PromptInput onSubmit={(value) => console.log(value)} />",
+      "description": "Simple prompt input with default configuration"
+    },
+    {
+      "title": "With custom placeholder",
+      "code": "<PromptInput \n  onSubmit={handleSubmit}\n  placeholder=\"Ask me anything about coding...\"\n/>",
+      "description": "Prompt input with custom placeholder text"
+    },
+    {
+      "title": "With auto-focus",
+      "code": "<PromptInput \n  onSubmit={handleSubmit}\n  autoFocus={true}\n/>",
+      "description": "Auto-focuses the input when component mounts"
+    },
+    {
+      "title": "With character limit",
+      "code": "<PromptInput \n  onSubmit={handleSubmit}\n  maxLength={500}\n/>",
+      "description": "Limits input to 500 characters"
+    },
+    {
+      "title": "Without send button",
+      "code": "<PromptInput \n  onSubmit={handleSubmit}\n  showSendButton={false}\n/>",
+      "description": "Hides the send button (user must press Enter)"
+    },
+    {
+      "title": "With loading state",
+      "code": "<PromptInput \n  onSubmit={handleSubmit}\n  isLoading={isGenerating}\n  disabled={isGenerating}\n/>",
+      "description": "Shows loading state and disables while AI is responding"
+    },
+    {
+      "title": "Cancellable generation",
+      "code": "<PromptInput onSubmit={send} isLoading={loading} onStop={() => abortRef.current.abort()} />"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't use for non-chat input",
+      "explanation": "PromptInput is specifically for chat interactions, not general form input",
+      "example": "// Avoid: Using PromptInput for forms\n<PromptInput onSubmit={handleFormSubmit} />\n\n// Prefer: Use appropriate form input components\n<TextArea onChange={handleChange} />"
+    },
+    {
+      "title": "Don't ignore Enter key behavior",
+      "explanation": "Users expect Enter to submit. If you change this, communicate it clearly",
+      "example": "// Avoid: Confusing users by disabling Enter\n<PromptInput \n  onSubmit={handleSubmit}\n  // Users expect Enter to submit\n/>\n\n// If you need different behavior, document it clearly"
+    },
+    {
+      "title": "Don't validate after submission",
+      "explanation": "Disable the input when empty rather than validating in the handler",
+      "example": "// Avoid: Validating in onSubmit\n<PromptInput onSubmit={(value) => {\n  if (!value) return; // Validate before\n  sendMessage(value);\n}} />\n\n// Prefer: Disable button when empty\n<PromptInput \n  onSubmit={sendMessage}\n  disabled={!value}\n/>"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Keyboard navigation",
+      "implementation": "Full keyboard support with Enter to submit, Shift+Enter for new line",
+      "userRequirements": "Document keyboard shortcuts for users"
+    },
+    {
+      "feature": "Screen reader support",
+      "implementation": "Textarea has proper label and placeholder. Button state is announced",
+      "userRequirements": "Ensure placeholder text is descriptive and helpful"
+    },
+    {
+      "feature": "Form validation",
+      "implementation": "Button is disabled when input is empty, preventing invalid submissions",
+      "userRequirements": "Consider adding aria-invalid for custom validation if needed"
+    },
+    {
+      "feature": "Auto-resize",
+      "implementation": "Textarea automatically grows with content up to max-height",
+      "userRequirements": "Test with screen readers to ensure height changes are announced appropriately"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Placeholder text",
+      "guidelines": [
+        "Use action-oriented placeholder text",
+        "Be specific about what kind of input is expected",
+        "Keep placeholders concise (under 50 characters ideally)",
+        "Avoid generic placeholders like 'Enter text'",
+        "Consider the context of the conversation"
+      ],
+      "goodExamples": [
+        "Type your message...",
+        "Ask me anything about coding...",
+        "Describe what you'd like to build..."
+      ],
+      "badExamples": [
+        "Enter text here",
+        "Input",
+        "Type something",
+        "Lorem ipsum dolor sit amet"
+      ]
+    },
+    {
+      "contentType": "Send button",
+      "guidelines": [
+        "Use clear icons or text for the send button",
+        "Consider using an arrow icon (→) for a modern look",
+        "Show loading state when submitting",
+        "Disable button when input is empty"
+      ],
+      "goodExamples": [
+        "→",
+        "Send",
+        "Submit"
+      ],
+      "badExamples": [
+        "Click me",
+        "OK",
+        "Go"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Conversation",
+      "relationship": "PromptInput is typically used below a Conversation component to add new messages",
+      "example": "Conversation displays messages, PromptInput submits new ones to the same messages array"
+    },
+    {
+      "component": "ChatLayout",
+      "relationship": "PromptInput is often part of a ChatLayout that combines Conversation and input",
+      "example": "ChatLayout wraps Conversation and PromptInput in a complete chat interface"
+    }
+  ],
+  "relatedComponents": [
+    "Conversation",
+    "ChatLayout",
+    "Button"
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "prompt-input",
+  "exportName": "PromptInput"
+}

package/src/manifests/reasoning.manifest.json

@@ -0,0 +1,177 @@
+{
+  "id": "reasoning",
+  "name": "Reasoning",
+  "tier": "molecule",
+  "description": "A collapsible component for displaying AI reasoning steps and chain-of-thought processes",
+  "designIntent": "The Reasoning component displays the step-by-step thought process of an AI agent. It's collapsible to avoid cluttering the interface while still providing transparency into how the AI arrived at its conclusions.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "ReasoningStep[]",
+      "required": true,
+      "description": "Array of reasoning steps to display",
+      "examples": [
+        "[{ id: '1', content: 'Analyzing the request...' }, { id: '2', content: 'Formulating response...' }]"
+      ]
+    },
+    {
+      "name": "collapsible",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Whether the reasoning can be collapsed/expanded",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "defaultExpanded",
+      "type": "boolean",
+      "defaultValue": "false",
+      "required": false,
+      "description": "Whether the reasoning is expanded by default",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply"
+    },
+    {
+      "name": "duration",
+      "type": "number",
+      "required": false,
+      "description": "Elapsed reasoning time in seconds; renders a duration chip"
+    },
+    {
+      "name": "isStreaming",
+      "type": "boolean",
+      "required": false,
+      "description": "Shows a streaming indicator while reasoning is in progress"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Basic reasoning",
+      "code": "<Reasoning \n  steps={[\n    { id: '1', content: 'I need to analyze the user\\'s request.' },\n    { id: '2', content: 'The user wants to know about React components.' },\n    { id: '3', content: 'I should provide a comprehensive answer.' }\n  ]}\n/>",
+      "description": "Collapsible reasoning with multiple steps"
+    },
+    {
+      "title": "Expanded by default",
+      "code": "<Reasoning \n  steps={steps}\n  defaultExpanded={true}\n/>",
+      "description": "Reasoning that shows steps immediately"
+    },
+    {
+      "title": "Non-collapsible",
+      "code": "<Reasoning \n  steps={steps}\n  collapsible={false}\n/>",
+      "description": "Reasoning that cannot be collapsed"
+    },
+    {
+      "title": "With timestamps",
+      "code": "<Reasoning \n  steps={[\n    { id: '1', content: 'Step 1', timestamp: new Date() },\n    { id: '2', content: 'Step 2', timestamp: new Date() }\n  ]}\n/>",
+      "description": "Reasoning steps with timing information"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't show reasoning for simple responses",
+      "explanation": "Reasoning is valuable for complex tasks but adds noise for simple responses.",
+      "example": "// Avoid: Showing reasoning for trivial responses\n<Reasoning steps={[\n  { id: '1', content: 'I will say hello' }\n]} />\n<Message message={{ role: 'assistant', content: 'Hello!' }} />\n\n// Prefer: Only show reasoning for complex tasks\n<Reasoning steps={complexReasoning} />\n<Message message={{ role: 'assistant', content: complexResponse }} />"
+    },
+    {
+      "title": "Don't make steps too verbose",
+      "explanation": "Reasoning steps should be concise and focused on key decision points.",
+      "example": "// Avoid: Overly detailed steps\n{ id: '1', content: 'I am now processing the request by analyzing each word and considering multiple interpretations...' }\n\n// Prefer: Concise, clear steps\n{ id: '1', content: 'Analyzing the request for key terms and intent.' }"
+    },
+    {
+      "title": "Don't show empty reasoning",
+      "explanation": "The component returns null for empty arrays, but it's better to not render it at all.",
+      "example": "// Avoid: Rendering with no steps\n<Reasoning steps={[]} />\n\n// Prefer: Conditionally render\n{reasoningSteps.length > 0 && <Reasoning steps={reasoningSteps} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Collapsible state",
+      "implementation": "Uses aria-expanded to communicate collapsible state to screen readers",
+      "userRequirements": "Ensure the expanded/collapsed state is clear to all users"
+    },
+    {
+      "feature": "Keyboard navigation",
+      "implementation": "Collapsible button is keyboard accessible with Enter/Space to toggle",
+      "userRequirements": "Test keyboard navigation of the collapse/expand functionality"
+    },
+    {
+      "feature": "Visual hierarchy",
+      "implementation": "Steps are numbered and visually distinct with clear hierarchy",
+      "userRequirements": "Ensure step numbers and content have sufficient contrast"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Reasoning step content",
+      "guidelines": [
+        "Each step should represent a distinct decision or action",
+        "Use clear, concise language",
+        "Focus on the 'why' and 'how', not just the 'what'",
+        "Avoid overly technical jargon unless necessary",
+        "Structure steps logically (chronological or hierarchical)"
+      ],
+      "goodExamples": [
+        "Analyzing the user's request for key requirements",
+        "Considering multiple approaches to solve the problem",
+        "Selecting the most efficient solution based on constraints"
+      ],
+      "badExamples": [
+        "I am thinking about what to do",
+        "Processing...",
+        "Step 1",
+        "Lorem ipsum dolor sit amet"
+      ]
+    },
+    {
+      "contentType": "Step count",
+      "guidelines": [
+        "Show the total number of steps in the header",
+        "Number each step sequentially for easy reference",
+        "Keep step count reasonable (typically under 10 steps)",
+        "If there are many steps, consider grouping them"
+      ],
+      "goodExamples": [
+        "Reasoning (5 steps)",
+        "Step 1 of 5"
+      ],
+      "badExamples": [
+        "Reasoning",
+        "Step 1",
+        "Showing 47 steps"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Message",
+      "relationship": "Reasoning is typically displayed before or within an assistant's message to show thought process",
+      "example": "Message component can contain Reasoning to show the AI's thinking before the final response"
+    },
+    {
+      "component": "ToolCall",
+      "relationship": "Reasoning often precedes tool calls to explain why a tool is being used",
+      "example": "Reasoning explains the decision to use a tool, ToolCall shows the actual tool invocation"
+    }
+  ],
+  "relatedComponents": [
+    "Message",
+    "ToolCall",
+    "Conversation"
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "reasoning",
+  "exportName": "Reasoning"
+}

package/src/manifests/response.manifest.json

@@ -0,0 +1,51 @@
+{
+  "id": "response",
+  "name": "Response",
+  "tier": "molecule",
+  "description": "Streaming-optimized markdown renderer for AI responses with GFM support, streaming-safe repair of incomplete syntax, and highlighted code blocks with copy.",
+  "designIntent": "Render AI output as rich content without flicker or broken partial syntax while tokens arrive.",
+  "props": [
+    {
+      "name": "children",
+      "type": "string",
+      "required": true,
+      "description": "Markdown content to render."
+    },
+    {
+      "name": "parseIncompleteMarkdown",
+      "type": "boolean",
+      "defaultValue": true,
+      "required": false,
+      "description": "Close unclosed emphasis/inline-code/fences during streaming."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Basic response",
+      "code": "<Response>{assistantMessage.content}</Response>"
+    },
+    {
+      "title": "Inside Message",
+      "code": "<Message message={m} renderContent={(c) => <Response>{c}</Response>} />"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Do not use Response inside a code fence context",
+      "explanation": "Response is the top-level renderer; nested Response instances double-parse content."
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Semantic HTML",
+      "implementation": "Headings, lists and tables are real elements announced correctly."
+    },
+    {
+      "feature": "Code blocks",
+      "implementation": "Routed through CodeBlock with accessible copy button."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1"
+}

package/src/manifests/source.manifest.json

@@ -0,0 +1,78 @@
+{
+  "id": "source",
+  "name": "Source / Sources",
+  "tier": "molecule",
+  "description": "Displays citations and references for an AI response. `Source` renders a single citation; `Sources` renders a numbered list with an overflow count.",
+  "designIntent": "Make generated answers transparent by showing where information came from.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": false,
+      "description": "1-based citation marker rendered as [n]; omit on Source to hide numbering."
+    },
+    {
+      "name": "source",
+      "type": "SourceItem",
+      "required": true,
+      "description": "The single source to render (Source component)"
+    },
+    {
+      "name": "onSelect",
+      "type": "(source: SourceItem) => void",
+      "required": false,
+      "description": "Called when the source chip is clicked"
+    },
+    {
+      "name": "sources",
+      "type": "SourceItem[]",
+      "required": true,
+      "description": "List of sources to render (Sources component)"
+    },
+    {
+      "name": "maxDisplay",
+      "type": "number",
+      "defaultValue": "3",
+      "required": false,
+      "description": "Maximum number of source chips to show before collapsing (Sources component)"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "defaultValue": "Sources",
+      "required": false,
+      "description": "Section label above the source list (Sources component)"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Citations list",
+      "code": "<Sources sources={[{ id: '1', title: 'React docs', url: 'https://react.dev' }, { id: '2', title: 'MDN', url: 'https://developer.mozilla.org' }]} />"
+    },
+    {
+      "title": "Single inline citation",
+      "code": "<Source source={{ id: '1', title: 'React docs', url: 'https://react.dev' }} index={1} />"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Do not nest Sources inside Sources",
+      "explanation": "Sources is a list container; compose individual Source items only when building a custom layout."
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Link semantics",
+      "implementation": "References use native links with rel=noopener when URLs are provided."
+    },
+    {
+      "feature": "Decorative markers",
+      "implementation": "[n] citation markers are aria-hidden; titles are read as link text."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "source",
+  "exportName": "Source"
+}

package/src/manifests/streaming-indicator.manifest.json

@@ -0,0 +1,39 @@
+{
+  "id": "streaming-indicator",
+  "name": "StreamingIndicator",
+  "tier": "atom",
+  "description": "Shows that an AI response is currently streaming.",
+  "designIntent": "Give users immediate feedback while generated content is arriving.",
+  "props": [
+    {
+      "name": "isStreaming",
+      "type": "boolean",
+      "required": true,
+      "description": "Whether the indicator is visible."
+    },
+    {
+      "name": "text",
+      "type": "string",
+      "defaultValue": "Generating…",
+      "required": false,
+      "description": "Status text."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Generating state",
+      "code": "<StreamingIndicator isStreaming={true} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Status text",
+      "implementation": "The state includes human-readable text in addition to animation."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "streaming",
+  "exportName": "StreamingIndicator"
+}