@slipstream-ui/ai 0.0.0-stage → 0.3.0

package/src/manifests/conversation.manifest.json

@@ -0,0 +1,290 @@
+{
+  "id": "conversation",
+  "name": "Conversation",
+  "tier": "organism",
+  "description": "A container for displaying a list of chat messages with auto-scroll and loading states",
+  "designIntent": "The Conversation component manages the display of multiple messages in a chat interface. It handles auto-scrolling to show new messages, distinct avatar configurations for users and assistants, and a loading state when the AI is generating a response.",
+  "props": [
+    {
+      "name": "messages",
+      "type": "Message[]",
+      "required": true,
+      "description": "Array of message objects to display",
+      "examples": [
+        "[{ id: '1', role: 'user', content: 'Hello' }, { id: '2', role: 'assistant', content: 'Hi!' }]"
+      ]
+    },
+    {
+      "name": "showAvatars",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Whether to show avatars for messages",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "userAvatarSrc",
+      "type": "string",
+      "required": false,
+      "description": "Custom avatar image URL for user messages",
+      "examples": [
+        "https://example.com/user-avatar.png"
+      ]
+    },
+    {
+      "name": "userAvatarFallback",
+      "type": "string",
+      "required": false,
+      "description": "Fallback text for user avatar",
+      "examples": [
+        "JD",
+        "User"
+      ]
+    },
+    {
+      "name": "assistantAvatarSrc",
+      "type": "string",
+      "required": false,
+      "description": "Custom avatar image URL for assistant messages",
+      "examples": [
+        "https://example.com/ai-avatar.png"
+      ]
+    },
+    {
+      "name": "assistantAvatarFallback",
+      "type": "string",
+      "required": false,
+      "description": "Fallback text for assistant avatar",
+      "examples": [
+        "AI",
+        "Bot"
+      ]
+    },
+    {
+      "name": "isLoading",
+      "type": "boolean",
+      "defaultValue": "false",
+      "required": false,
+      "description": "Whether the assistant is currently generating a response",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "loadingMessage",
+      "type": "string",
+      "defaultValue": "Thinking...",
+      "required": false,
+      "description": "Text to display while loading",
+      "examples": [
+        "Thinking...",
+        "Generating response...",
+        "Processing..."
+      ]
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply to the conversation container"
+    },
+    {
+      "name": "renderContent",
+      "type": "(content: string) => ReactNode",
+      "required": false,
+      "description": "Custom renderer applied to every message (e.g. markdown)."
+    },
+    {
+      "name": "streamingMessageId",
+      "type": "string",
+      "required": false,
+      "description": "ID of the message still generating; renders its streaming cursor and auto-scrolls."
+    },
+    {
+      "name": "showScrollButton",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Show the scroll-to-latest button when the user scrolls up"
+    },
+    {
+      "name": "showDownload",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Show the transcript download action"
+    },
+    {
+      "name": "messageErrors",
+      "type": "Record<string, string>",
+      "required": false,
+      "description": "Map of message id to error text; renders an error card on that message"
+    },
+    {
+      "name": "onRetryMessage",
+      "type": "(message: MessageData) => void",
+      "required": false,
+      "description": "Called when the user retries a failed message"
+    },
+    {
+      "name": "welcomeTitle",
+      "type": "string",
+      "required": false,
+      "description": "Title shown in the empty/welcome state"
+    },
+    {
+      "name": "welcomeDescription",
+      "type": "string",
+      "required": false,
+      "description": "Supporting text in the welcome state"
+    },
+    {
+      "name": "welcomeSuggestions",
+      "type": "string[]",
+      "required": false,
+      "description": "Starter prompts shown in the welcome state"
+    },
+    {
+      "name": "onWelcomeSelect",
+      "type": "(prompt: string) => void",
+      "required": false,
+      "description": "Called when a welcome suggestion is clicked"
+    },
+    {
+      "name": "hasMoreHistory",
+      "type": "boolean",
+      "required": false,
+      "description": "Whether older history pages exist (enables infinite scroll)"
+    },
+    {
+      "name": "isLoadingMore",
+      "type": "boolean",
+      "required": false,
+      "description": "Whether a history page is currently loading"
+    },
+    {
+      "name": "onLoadMore",
+      "type": "() => void",
+      "required": false,
+      "description": "Called when the user scrolls to the top to load older messages"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Basic conversation",
+      "code": "<Conversation \n  messages={[\n    { id: '1', role: 'user', content: 'Hello' },\n    { id: '2', role: 'assistant', content: 'Hi there!' }\n  ]}\n/>",
+      "description": "Simple conversation with user and assistant messages"
+    },
+    {
+      "title": "With custom avatars",
+      "code": "<Conversation \n  messages={messages}\n  userAvatarSrc=\"/user.png\"\n  userAvatarFallback=\"JD\"\n  assistantAvatarSrc=\"/ai.png\"\n  assistantAvatarFallback=\"AI\"\n/>",
+      "description": "Conversation with custom avatar images and fallbacks"
+    },
+    {
+      "title": "With loading state",
+      "code": "<Conversation \n  messages={messages}\n  isLoading={true}\n  loadingMessage=\"Generating your response...\"\n/>",
+      "description": "Conversation showing loading indicator while AI responds"
+    },
+    {
+      "title": "Without avatars",
+      "code": "<Conversation \n  messages={messages}\n  showAvatars={false}\n/>",
+      "description": "More compact conversation without avatars"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't manage state inside Conversation",
+      "explanation": "Conversation should be a controlled component. State should be managed by the parent.",
+      "example": "// Avoid: Conversation managing its own message state\n<Conversation />\n\n// Prefer: Pass messages as props from parent\n<Conversation messages={messages} />"
+    },
+    {
+      "title": "Don't use for non-chat content",
+      "explanation": "Conversation is specifically for chat messages, not general data display",
+      "example": "// Avoid: Using Conversation for general lists\n<Conversation messages={dataItems} />\n\n// Prefer: Use appropriate list components\n<DataList items={dataItems} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Live regions",
+      "implementation": "Consider adding aria-live to the container for screen readers to announce new messages",
+      "userRequirements": "For streaming responses, use aria-live='polite' to avoid interrupting users"
+    },
+    {
+      "feature": "Keyboard navigation",
+      "implementation": "Container is scrollable with keyboard. Focus management depends on parent component",
+      "userRequirements": "Ensure users can navigate through messages with keyboard if needed"
+    },
+    {
+      "feature": "Loading announcement",
+      "implementation": "Loading state is visually indicated but not announced to screen readers by default",
+      "userRequirements": "Consider adding aria-live region for loading state if needed"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Loading message",
+      "guidelines": [
+        "Keep loading messages brief and informative",
+        "Avoid specific time estimates (which are often inaccurate)",
+        "Use consistent loading text across the application",
+        "Consider the context (what action is being performed)"
+      ],
+      "goodExamples": [
+        "Thinking...",
+        "Generating response...",
+        "Processing your request"
+      ],
+      "badExamples": [
+        "Please wait about 5 seconds",
+        "Loading loading loading",
+        "Wait"
+      ]
+    },
+    {
+      "contentType": "Avatar fallback text",
+      "guidelines": [
+        "Use consistent abbreviations for user and assistant",
+        "User fallback should be based on user's name or identity",
+        "Assistant fallback should clearly indicate it's an AI",
+        "Keep to 1-2 characters for best appearance"
+      ],
+      "goodExamples": [
+        "JD",
+        "AI",
+        "Bot",
+        "U"
+      ],
+      "badExamples": [
+        "JohnDoe",
+        "Assistant Bot",
+        "very-long-text"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Message",
+      "relationship": "Conversation renders multiple Message components internally",
+      "example": "Conversation maps over messages array and renders Message for each item"
+    },
+    {
+      "component": "PromptInput",
+      "relationship": "PromptInput is typically used alongside Conversation to submit new messages",
+      "example": "Conversation displays messages, PromptInput adds new ones to the messages array"
+    }
+  ],
+  "relatedComponents": [
+    "Message",
+    "PromptInput",
+    "ChatLayout"
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "conversation",
+  "exportName": "Conversation"
+}

package/src/manifests/inline-citation.manifest.json

@@ -0,0 +1,46 @@
+{
+  "id": "inline-citation",
+  "name": "InlineCitation",
+  "tier": "atom",
+  "description": "Perplexity-style inline citation chip that reveals the source title and snippet on hover or keyboard focus.",
+  "designIntent": "Attribute individual claims inside a response to their source without leaving the paragraph.",
+  "props": [
+    {
+      "name": "source",
+      "type": "SourceItem",
+      "required": true,
+      "description": "Cited source powering the preview card."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "description": "Wrapped text; defaults to the source title."
+    }
+  ],
+  "examples": [
+    {
+      "title": "Wrap a claim",
+      "code": "<InlineCitation source={sources[0]}>as reported</InlineCitation>"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Do not stack many citations on one word",
+      "explanation": "Use Sources footer for long lists; keep inline citations to one claim each."
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Keyboard access",
+      "implementation": "Trigger is a focusable button; card opens on focus-within."
+    },
+    {
+      "feature": "Tooltip semantics",
+      "implementation": "Card has role=tooltip linked via aria-describedby."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1"
+}

package/src/manifests/message-actions.manifest.json

@@ -0,0 +1,35 @@
+{
+  "id": "message-actions",
+  "name": "MessageActions",
+  "tier": "atom",
+  "description": "Feedback toolbar for an AI response: copy to clipboard, thumbs up/down rating, and regenerate. Every action is a callback; the component holds no conversation state.",
+  "designIntent": "Collect user trust signals (copy, rating, regeneration) with minimal API surface; consumers own what happens after each action.",
+  "props": [
+    { "name": "content", "type": "string", "required": false, "description": "Text to copy; omit to hide the copy action." },
+    { "name": "onCopy", "type": "(content: string) => void", "required": false, "description": "Called after copy with the copied text." },
+    { "name": "onFeedback", "type": "(rating: 'up' | 'down' | undefined) => void", "required": false, "description": "Rating callback; selecting the active rating again passes undefined." },
+    { "name": "onRegenerate", "type": "() => void", "required": false, "description": "Regeneration request; omit to hide the action." },
+    { "name": "labels", "type": "{ copy?, copied?, thumbUp?, thumbDown?, regenerate? }", "required": false, "description": "Overrides for all visible labels; enables localization." }
+  ],
+  "examples": [
+    {
+      "title": "Full feedback bar",
+      "code": "<MessageActions content={message.content} onCopy={copy} onFeedback={(r) => track(r)} onRegenerate={regen} />"
+    },
+    {
+      "title": "Ratings only",
+      "code": "<MessageActions onFeedback={(r) => save(r)} />"
+    }
+  ],
+  "antiPatterns": [
+    { "title": "Do not place MessageActions inside the message text flow", "explanation": "Render it below the Message bubble so actions remain visually and semantically separate from content." }
+  ],
+  "accessibility": [
+    { "feature": "Toolbar semantics", "implementation": "Root has role=toolbar with an aria-label." },
+    { "feature": "Toggle state", "implementation": "Rating buttons expose aria-pressed so screen readers announce selection." },
+    { "feature": "Icon buttons", "implementation": "All icon-only controls have accessible labels; labels are localizable." }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1"
+}

package/src/manifests/message.manifest.json

@@ -0,0 +1,235 @@
+{
+  "id": "message",
+  "name": "Message",
+  "tier": "molecule",
+  "description": "A chat message component that displays messages from users, assistants, or system prompts with optional avatars",
+  "designIntent": "The Message component renders individual chat messages with proper styling based on the message role (user, assistant, system, tool). It handles avatar display, timestamps, and different visual treatments to distinguish between message types in a conversation interface.",
+  "props": [
+    {
+      "name": "message",
+      "type": "Message",
+      "required": true,
+      "description": "The message object containing role, content, and optional metadata",
+      "examples": [
+        "{ id: '1', role: 'user', content: 'Hello' }",
+        "{ id: '2', role: 'assistant', content: 'Hi there!' }"
+      ]
+    },
+    {
+      "name": "showAvatar",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Whether to show the avatar for the message",
+      "examples": [
+        true,
+        false
+      ]
+    },
+    {
+      "name": "avatarSrc",
+      "type": "string",
+      "required": false,
+      "description": "Optional custom avatar image URL",
+      "examples": [
+        "https://example.com/avatar.png"
+      ]
+    },
+    {
+      "name": "avatarFallback",
+      "type": "string",
+      "required": false,
+      "description": "Fallback text to show when avatar image is not available",
+      "examples": [
+        "JD",
+        "AI",
+        "Bot"
+      ]
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Additional CSS classes to apply to the message container"
+    },
+    {
+      "name": "renderContent",
+      "type": "(content: string) => ReactNode",
+      "required": false,
+      "description": "Custom renderer (e.g. markdown); replaces default plain-text rendering."
+    },
+    {
+      "name": "isStreaming",
+      "type": "boolean",
+      "defaultValue": false,
+      "required": false,
+      "description": "Shows a typing cursor and sets aria-busy while the response is still generating."
+    },
+    {
+      "name": "userLabel",
+      "type": "string",
+      "defaultValue": "You",
+      "required": false,
+      "description": "Display name for user messages; enables localization."
+    },
+    {
+      "name": "assistantLabel",
+      "type": "string",
+      "defaultValue": "Assistant",
+      "required": false,
+      "description": "Display name for assistant messages; enables localization."
+    },
+    {
+      "name": "error",
+      "type": "string",
+      "required": false,
+      "description": "Error text to render on the message; shows an error card with retry"
+    },
+    {
+      "name": "onRetry",
+      "type": "() => void",
+      "required": false,
+      "description": "Called when the user requests a retry after error; omit to hide the action"
+    },
+    {
+      "name": "labels",
+      "type": "{ retry?: string; edit?: string; save?: string; cancel?: string }",
+      "required": false,
+      "description": "Override button labels in the message actions"
+    },
+    {
+      "name": "onEditContent",
+      "type": "(content: string) => void",
+      "required": false,
+      "description": "Enables edit-and-resubmit; called with the edited content"
+    }
+  ],
+  "examples": [
+    {
+      "title": "User message",
+      "code": "<Message message={{ id: '1', role: 'user', content: 'Hello, how are you?' }} />",
+      "description": "Message from the user with default avatar"
+    },
+    {
+      "title": "Assistant message",
+      "code": "<Message message={{ id: '2', role: 'assistant', content: 'I\\'m doing well, thank you!' }} />",
+      "description": "Message from the AI assistant"
+    },
+    {
+      "title": "System message",
+      "code": "<Message message={{ id: '3', role: 'system', content: 'System initialized' }} />",
+      "description": "System-level message with distinct styling"
+    },
+    {
+      "title": "With custom avatar",
+      "code": "<Message \n  message={{ id: '4', role: 'assistant', content: 'Hello' }}\n  avatarSrc=\"/ai-avatar.png\"\n  avatarFallback=\"AI\"\n/>",
+      "description": "Message with custom avatar image and fallback"
+    },
+    {
+      "title": "Without avatar",
+      "code": "<Message \n  message={{ id: '5', role: 'user', content: 'Quick message' }}\n  showAvatar={false}\n/>",
+      "description": "Message with avatar hidden for more compact display"
+    },
+    {
+      "title": "Markdown rendering (opt-in)",
+      "code": "<Message message={m} renderContent={(c) => <ReactMarkdown>{c}</ReactMarkdown>} />"
+    },
+    {
+      "title": "Streaming response",
+      "code": "<Message message={partial} isStreaming />"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Don't use for complex content",
+      "explanation": "Message content should be plain text. For complex UI, use additional components.",
+      "example": "// Avoid: Putting complex UI inside message content\n<Message message={{ \n  role: 'assistant', \n  content: '<div>Complex HTML</div>' \n}} />\n\n// Prefer: Use separate components for complex content\n<Message message={{ role: 'assistant', content: 'Here is the data:' }} />\n<DataDisplay data={...} />"
+    },
+    {
+      "title": "Don't hardcode message data",
+      "explanation": "Messages should come from a conversation state, not be hardcoded",
+      "example": "// Avoid: Hardcoded message\n<Message message={{ id: '1', role: 'user', content: 'Fixed text' }} />\n\n// Prefer: Dynamic message from state\n<Message message={messages[currentIndex]} />"
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Screen reader support",
+      "implementation": "Message role and content are announced. Avatar has proper alt text from fallback or role",
+      "userRequirements": "Ensure avatarFallback is meaningful when avatarSrc is used"
+    },
+    {
+      "feature": "Color contrast",
+      "implementation": "User and assistant messages have distinct background colors with proper contrast",
+      "userRequirements": "Test color contrast in both light and dark modes"
+    },
+    {
+      "feature": "Semantic structure",
+      "implementation": "Message is rendered as a div with proper ARIA attributes for role identification",
+      "userRequirements": "Consider adding aria-live regions for streaming messages"
+    }
+  ],
+  "contentGuidelines": [
+    {
+      "contentType": "Message content",
+      "guidelines": [
+        "Content should be plain text, not HTML",
+        "Support markdown formatting if needed (apply at wrapper level)",
+        "Keep messages focused and concise",
+        "Use proper punctuation and grammar for assistant messages",
+        "For user messages, preserve user's original formatting"
+      ],
+      "goodExamples": [
+        "I can help you with that task.",
+        "Here's the code you requested:",
+        "Let me explain step by step."
+      ],
+      "badExamples": [
+        "<b>Bold text</b>",
+        "Lorem ipsum dolor sit amet",
+        "Click here to continue"
+      ]
+    },
+    {
+      "contentType": "Avatar fallback",
+      "guidelines": [
+        "Use 1-2 characters maximum",
+        "Use initials for user names",
+        "Use meaningful abbreviations for bots",
+        "Ensure high contrast with avatar background"
+      ],
+      "goodExamples": [
+        "JD",
+        "AI",
+        "Bot",
+        "S"
+      ],
+      "badExamples": [
+        "John Doe",
+        "Assistant",
+        "long-text"
+      ]
+    }
+  ],
+  "compositionRules": [
+    {
+      "component": "Conversation",
+      "relationship": "Messages are typically rendered within a Conversation component that manages the message list",
+      "example": "<Conversation>\n  {messages.map(msg => <Message key={msg.id} message={msg} />)}\n</Conversation>"
+    },
+    {
+      "component": "PromptInput",
+      "relationship": "New messages from PromptInput should be added to the message list and rendered as Message components",
+      "example": "const handleSubmit = (text) => {\n  const newMessage = { id: Date.now(), role: 'user', content: text };\n  setMessages([...messages, newMessage]);\n}"
+    }
+  ],
+  "relatedComponents": [
+    "Conversation",
+    "PromptInput",
+    "Avatar"
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1",
+  "sourceDir": "message",
+  "exportName": "Message"
+}