@slipstream-ui/ai 0.0.0-stage → 0.4.0

package/src/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/src/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/src/test/jest-axe.d.ts

@@ -0,0 +1,16 @@
+declare module 'jest-axe' {
+  export interface AxeResult {
+    violations: unknown[];
+  }
+
+  /**
+   * Run axe-core against rendered HTML or an element.
+   * Returns a promise compatible with the toHaveNoViolations matcher.
+   */
+  export function axe(html: string | Element): Promise<AxeResult>;
+
+  /** Matcher extension object for expect(). */
+  export const toHaveNoViolations: {
+    toHaveNoViolations: () => { pass: boolean; message: () => string };
+  };
+}

package/src/test/setup.ts

@@ -0,0 +1,18 @@
+import '@testing-library/jest-dom/vitest';
+import * as jestAxe from 'jest-axe';
+import { cleanup } from '@testing-library/react';
+import { afterEach, beforeAll, expect, vi } from 'vitest';
+
+expect.extend(jestAxe.toHaveNoViolations);
+
+// jsdom does not implement scroll layout APIs used by auto-scrolling components.
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn();
+  // Container-scoped scrolling (Conversation) uses Element.scrollTo, which
+  // jsdom also lacks — without this mock the auto-scroll effect throws.
+  Element.prototype.scrollTo = vi.fn();
+});
+
+afterEach(() => {
+  cleanup();
+});

package/src/test/vitest-matchers.d.ts

@@ -0,0 +1,10 @@
+import 'vitest';
+
+declare module 'vitest' {
+  interface Assertion {
+    toHaveNoViolations(): void;
+  }
+  interface AsymmetricMatchersContaining {
+    toHaveNoViolations(): void;
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,40 @@
+/**
+ * AI Component Types
+ * 
+ * Shared types for AI interaction components like Message, Conversation, etc.
+ */
+
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+
+export type Message = {
+  id: string;
+  role: MessageRole;
+  content: string;
+  timestamp?: Date;
+  metadata?: Record<string, unknown>;
+};
+
+export type ToolCall = {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  result?: string | number | boolean | Record<string, unknown> | unknown[];
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /** Error detail rendered when status is failed. */
+  error?: string;
+};
+
+export type ReasoningStep = {
+  id: string;
+  content: string;
+  timestamp?: Date;
+};
+
+
+/** A single citation or reference attached to an AI response. */
+export type SourceItem = {
+  id: string;
+  title: string;
+  url?: string;
+  snippet?: string;
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.