@slipstream-ui/ai 0.0.0-stage → 0.3.0

package/dist/manifests/confirmation.manifest.json

@@ -0,0 +1,143 @@
+{
+  "id": "confirmation",
+  "name": "Confirmation",
+  "tier": "molecule",
+  "description": "Human-in-the-loop approval gate for agent actions. Pauses execution until the user approves or rejects.",
+  "designIntent": "Make destructive or consequential tool calls require explicit user consent.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "Summary of the action requiring approval."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Detail: affected resource or risk note."
+    },
+    {
+      "name": "toolName",
+      "type": "string",
+      "required": false,
+      "description": "Tool/action name shown as mono text."
+    },
+    {
+      "name": "status",
+      "type": "'pending' | 'approved' | 'rejected'",
+      "defaultValue": "pending",
+      "required": false,
+      "description": "Controlled outcome; omit for uncontrolled."
+    },
+    {
+      "name": "variant",
+      "type": "'default' | 'warning' | 'destructive' | 'info' | 'success'",
+      "defaultValue": "default",
+      "required": false,
+      "description": "Accent color of the pending card; outcome chips always follow the result.",
+      "enum": [
+        "default",
+        "warning",
+        "destructive",
+        "info",
+        "success"
+      ],
+      "examples": [
+        "destructive",
+        "info"
+      ]
+    },
+    {
+      "name": "onApprove",
+      "type": "() => void",
+      "required": false,
+      "description": "Called on approval."
+    },
+    {
+      "name": "onReject",
+      "type": "() => void",
+      "required": false,
+      "description": "Called on rejection."
+    },
+    {
+      "name": "labels",
+      "type": "object",
+      "required": false,
+      "description": "Overrides for approve/reject/approved/rejected labels."
+    },
+    {
+      "name": "approveVariant",
+      "type": "'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'",
+      "defaultValue": "default",
+      "required": false,
+      "description": "Button variant for the approve action.",
+      "enum": [
+        "default",
+        "destructive",
+        "outline",
+        "secondary",
+        "ghost",
+        "link"
+      ],
+      "examples": [
+        "destructive",
+        "default"
+      ]
+    },
+    {
+      "name": "rejectVariant",
+      "type": "'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'",
+      "defaultValue": "outline",
+      "required": false,
+      "description": "Button variant for the reject action.",
+      "enum": [
+        "default",
+        "destructive",
+        "outline",
+        "secondary",
+        "ghost",
+        "link"
+      ],
+      "examples": [
+        "ghost"
+      ]
+    },
+    {
+      "name": "showActions",
+      "type": "boolean",
+      "defaultValue": "true",
+      "required": false,
+      "description": "Hide the action buttons (controlled-only gate; status drives the chip).",
+      "examples": [
+        "true",
+        "false"
+      ]
+    }
+  ],
+  "examples": [
+    {
+      "title": "Gate a destructive tool",
+      "code": "<Confirmation title=\"Delete all files?\" toolName=\"delete_all\" onApprove={run} onReject={cancel} />"
+    }
+  ],
+  "antiPatterns": [
+    {
+      "title": "Do not auto-approve after timeout",
+      "explanation": "Silent approval defeats the safety purpose; keep waiting or fail explicitly."
+    }
+  ],
+  "accessibility": [
+    {
+      "feature": "Dialog semantics",
+      "implementation": "Pending state renders role=alertdialog labeled by the title."
+    },
+    {
+      "feature": "Outcome announcement",
+      "implementation": "Status chip text announces Approved/Rejected."
+    }
+  ],
+  "package": "@slipstream-ui/ai",
+  "importPath": "@slipstream-ui/ai",
+  "version": "0.0.1"
+}

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