@slipstream-ui/ai 0.0.0-stage → 0.4.0

package/dist/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/dist/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/dist/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/dist/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"
+}

package/dist/manifests/suggestions.manifest.json

@@ -0,0 +1,45 @@
+{
+  "id": "suggestions",
+  "name": "Suggestions",
+  "tier": "molecule",
+  "description": "Displays clickable follow-up prompts for AI interactions.",
+  "designIntent": "Help users discover useful next actions without composing every prompt from scratch.",
+  "props": [
+    {
+      "name": "suggestions",
+      "type": "Suggestion[]",
+      "required": true,
+      "description": "Suggestions to display."
+    },
+    {
+      "name": "onSelect",
+      "type": "(suggestion: Suggestion) => void",
+      "required": false,
+      "description": "Called when a suggestion is selected."
+    },
+    {
+      "name": "maxDisplay",
+      "required": false,
+      "defaultValue": "4",
+      "type": "number",
+      "description": "Maximum number of suggestions to display before truncating"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Follow-up prompts",
+      "code": "<Suggestions suggestions={[{ id: '1', text: 'Show me an example' }]} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Keyboard activation",
+      "implementation": "Suggestions are native buttons."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "suggestion",
+  "exportName": "Suggestions"
+}

package/dist/manifests/tool-call.manifest.json

@@ -0,0 +1,158 @@
+{
+  "id": "tool-call",
+  "name": "ToolCall",
+  "tier": "molecule",
+  "description": "A component for displaying AI tool/function calls with status, arguments, and results",
+  "designIntent": "The ToolCall component visualizes when an AI agent uses tools or functions. It shows the tool name, status (pending, running, completed, failed), arguments passed, and the result returned. This provides transparency into the AI's actions.",
+  "props": [
+    {
+      "name": "toolCall",
+      "type": "ToolCall",
+      "required": true,
+      "description": "The tool call object containing name, arguments, status, and result",
+      "examples": [
+        "{ id: '1', name: 'search', arguments: { query: 'React' }, status: 'completed' }"
+      ]
+    },
+    {
+      "name": "showResult",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Whether to display the tool result",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Completed tool call",
+      "code": "<ToolCall \n  toolCall={{\n    id: '1',\n    name: 'search',\n    arguments: { query: 'React components' },\n    status: 'completed',\n    result: { results: [...] }\n  }}\n/>",
+      "description": "Tool call that completed successfully with result"
+    },
+    {
+      "title": "Running tool call",
+      "code": "<ToolCall \n  toolCall={{\n    id: '2',\n    name: 'calculate',\n    arguments: { expression: '2 + 2' },\n    status: 'running'\n  }}\n/>",
+      "description": "Tool call currently in progress"
+    },
+    {
+      "title": "Failed tool call",
+      "code": "<ToolCall \n  toolCall={{\n    id: '3',\n    name: 'api_request',\n    arguments: { endpoint: '/users' },\n    status: 'failed',\n    result: { error: 'Timeout' }\n  }}\n/>",
+      "description": "Tool call that failed with error message"
+    },
+    {
+      "title": "Without result",
+      "code": "<ToolCall \n  toolCall={toolCall}\n  showResult={false}\n/>",
+      "description": "Tool call with result hidden"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't show tool calls for simple operations",
+      "explanation": "Tool calls should be shown for meaningful operations, not trivial ones.",
+      "example": "// Avoid: Showing trivial tool calls\n<ToolCall toolCall={{ name: 'echo', arguments: { text: 'hello' }, status: 'completed' }} />\n\n// Prefer: Only show meaningful tool usage\n<ToolCall toolCall={{ name: 'search_database', arguments: { query: complexQuery }, status: 'completed' }} />"
+    },
+    {
+      "title": "Don't expose sensitive data in arguments",
+      "explanation": "Never display sensitive credentials or personal data in tool call arguments.",
+      "example": "// Avoid: Including sensitive data\n<ToolCall toolCall={{ \n  name: 'api_call', \n  arguments: { apiKey: 'secret-key' }, \n  status: 'completed' \n}} />\n\n// Prefer: Redact sensitive information\n<ToolCall toolCall={{ \n  name: 'api_call', \n  arguments: { apiKey: '[REDACTED]' }, \n  status: 'completed' \n}} />"
+    },
+    {
+      "title": "Don't ignore failed tool calls",
+      "explanation": "Failed tool calls should be clearly indicated with error information.",
+      "example": "// Avoid: Not addressing failures\n<ToolCall toolCall={{ name: 'save', status: 'failed' }} />\n\n// Prefer: Handle and display failures appropriately\n<ToolCall toolCall={{ name: 'save', status: 'failed', result: { error: 'Permission denied' } }} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Status indication",
+      "implementation": "Status is shown with both color and text label for clarity",
+      "userRequirements": "Ensure status colors have sufficient contrast in both light and dark modes"
+    },
+    {
+      "feature": "Code readability",
+      "implementation": "Arguments and results are displayed in pre/code blocks with proper formatting",
+      "userRequirements": "Test JSON display with screen readers for complex nested structures"
+    },
+    {
+      "feature": "Structure",
+      "implementation": "Tool call information is organized in clear sections (header, arguments, result)",
+      "userRequirements": "Use semantic headings for screen reader navigation"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Tool names",
+      "guidelines": [
+        "Use clear, descriptive tool names",
+        "Use snake_case or camelCase consistently",
+        "Names should indicate what the tool does",
+        "Avoid abbreviations unless universally understood",
+        "Prefix related tools with a common namespace"
+      ],
+      "goodExamples": [
+        "search_database",
+        "calculate_expression",
+        "send_email",
+        "weather_api.get_current"
+      ],
+      "badExamples": [
+        "tool1",
+        "proc",
+        "do_it",
+        "wthr.get"
+      ]
+    },
+    {
+      "contentType": "Status messages",
+      "guidelines": [
+        "Use standard status terminology (pending, running, completed, failed)",
+        "Be consistent with status labels across the application",
+        "For failed states, include error information when available",
+        "Use color coding to reinforce status meaning"
+      ],
+      "goodExamples": [
+        "Completed",
+        "Failed: Timeout",
+        "Running",
+        "Pending"
+      ],
+      "badExamples": [
+        "Done",
+        "Bad",
+        "Working",
+        "Waiting"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Message",
+      "relationship": "ToolCall components are typically displayed within assistant messages to show tool usage",
+      "example": "Message component can contain ToolCall to show when the AI used tools during its response"
+    },
+    {
+      "component": "Reasoning",
+      "relationship": "Reasoning often precedes ToolCall to explain why a tool is being invoked",
+      "example": "Reasoning explains the decision to use a tool, ToolCall shows the actual invocation"
+    }
+  ],
+  "relatedComponents": [
+    "Message",
+    "Reasoning",
+    "Conversation"
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "tool-call",
+  "exportName": "ToolCall"
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@slipstream-ui/ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelmcshinsky/slipstream-ui.git",
+    "directory": "packages/ai"
+  },
+  "description": "AI interaction components for Slipstream UI",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "prism-react-renderer": "^2.4.1",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^2.2.0",
+    "@slipstream-ui/core": "0.4.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@types/react": "^18.2.0",
+    "eslint": "^8.56.0",
+    "jest-axe": "^9.0.0",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^5.0.5",
+    "@slipstream-ui/eslint-config": "0.0.1",
+    "@slipstream-ui/tailwind-config": "0.0.1",
+    "@slipstream-ui/typescript-config": "0.0.1",
+    "@slipstream-ui/vitest-config": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "scripts": {
+    "build": "tsup && node -e \"require('fs').cpSync('src/manifests','dist/manifests',{recursive:true})\"",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "vitest run"
+  }
 }