@automattic/agenttic-ui 0.1.0

package/README.md

@@ -0,0 +1,488 @@
+# @automattic/agenttic-ui
+
+React UI components for AI agent chat interfaces. A pure UI layer designed to work seamlessly with `@automattic/agenttic-client` hooks or any agent communication system.
+
+## Installation
+
+```bash
+npm install @automattic/agenttic-ui
+```
+
+## Key Features
+
+- Pure UI components with no agent communication logic
+- Floating and embedded chat variants
+- Smooth animations and drag-and-drop positioning
+- Message actions and markdown rendering
+- TypeScript support with comprehensive types
+- Storybook component documentation
+- Modular component architecture for custom layouts
+
+## Quick Start
+
+### Complete Chat Interface
+
+```tsx
+import { useAgentChat } from '@automattic/agenttic-client';
+import { AgentUI } from '@automattic/agenttic-ui';
+
+function ChatApplication() {
+  const {
+    messages,
+    isProcessing,
+    error,
+    onSubmit,
+    suggestions,
+    clearSuggestions,
+    messageRenderer
+  } = useAgentChat({
+    agentId: 'big-sky',
+    sessionId: 'my-session'
+  });
+
+  return (
+    <AgentUI
+      messages={messages}
+      isProcessing={isProcessing}
+      error={error}
+      onSubmit={onSubmit}
+      suggestions={suggestions}
+      clearSuggestions={clearSuggestions}
+      messageRenderer={messageRenderer}
+      variant="floating"
+      placeholder="Ask me anything..."
+    />
+  );
+}
+```
+
+### Embedded Chat
+
+```tsx
+<AgentUI
+  messages={messages}
+  isProcessing={isProcessing}
+  error={error}
+  onSubmit={onSubmit}
+  variant="embedded"
+  placeholder="How can I help you?"
+/>
+```
+
+## Core Components
+
+### AgentUI
+
+The main component that provides a complete chat interface.
+
+```tsx
+interface AgentUIProps {
+  // Core chat data
+  messages: Message[];
+  isProcessing: boolean;
+  error?: string | null;
+  onSubmit: (message: string) => void;
+
+  // UI configuration
+  variant?: 'floating' | 'embedded';
+  placeholder?: string;
+  triggerIcon?: React.ReactNode;
+  notice?: NoticeConfig;
+  emptyView?: React.ReactNode;
+
+  // Chat state management (floating variant)
+  floatingChatState?: ChatState;
+  onOpen?: () => void;
+  onExpand?: () => void;
+  onClose?: () => void;
+
+  // Suggestions
+  suggestions?: Suggestion[];
+  clearSuggestions?: () => void;
+
+  // Message rendering
+  messageRenderer?: ComponentType<{ children: string }>;
+
+  // Styling
+  className?: string;
+  style?: React.CSSProperties;
+}
+```
+
+**Variants:**
+- `floating` - Draggable chat widget with collapsed/compact/expanded states
+- `embedded` - Fixed chat interface for integration in existing layouts
+
+### Individual Components
+
+For custom chat layouts, use individual components:
+
+```tsx
+import {
+  Chat,
+  Messages,
+  Message,
+  ChatInput,
+  Suggestions
+} from '@automattic/agenttic-ui';
+
+function CustomChat() {
+  return (
+    <div className="my-chat-container">
+      <Messages messages={messages} messageRenderer={messageRenderer} />
+      <Suggestions 
+        suggestions={suggestions} 
+        onSuggestionClick={onSubmit}
+        onClear={clearSuggestions}
+      />
+      <ChatInput
+        value={inputValue}
+        onChange={setInputValue}
+        onSubmit={onSubmit}
+        placeholder="Type a message..."
+        isProcessing={isProcessing}
+      />
+    </div>
+  );
+}
+```
+
+## Component APIs
+
+### Chat
+
+Main chat component supporting both floating and embedded variants.
+
+```tsx
+<Chat
+  messages={messages}
+  isProcessing={isProcessing}
+  error={error}
+  onSubmit={onSubmit}
+  variant="floating"
+  placeholder="Ask anything..."
+  suggestions={suggestions}
+  clearSuggestions={clearSuggestions}
+  messageRenderer={messageRenderer}
+/>
+```
+
+### Messages
+
+Container for displaying message history.
+
+```tsx
+<Messages 
+  messages={messages}
+  messageRenderer={messageRenderer}
+  emptyView={<div>No messages yet</div>}
+/>
+```
+
+### Message
+
+Individual message component with action support.
+
+```tsx
+<Message
+  message={message}
+  messageRenderer={messageRenderer}
+  showIcon={true}
+/>
+```
+
+### ChatInput
+
+Text input with auto-resize and submit handling.
+
+```tsx
+<ChatInput
+  value={value}
+  onChange={setValue}
+  onSubmit={handleSubmit}
+  onKeyDown={handleKeyDown}
+  placeholder="Type a message..."
+  isProcessing={false}
+  textareaRef={textareaRef}
+/>
+```
+
+### Suggestions
+
+Quick action suggestions for users.
+
+```tsx
+<Suggestions
+  suggestions={[
+    { id: '1', label: 'Help me code', prompt: 'Can you help me write code?' },
+    { id: '2', label: 'Explain concept', prompt: 'Explain this concept to me' }
+  ]}
+  onSuggestionClick={onSubmit}
+  onClear={clearSuggestions}
+/>
+```
+
+## Hooks
+
+### useChat
+
+Manages chat state for floating variant.
+
+```tsx
+const {
+  state,        // 'collapsed' | 'compact' | 'expanded'
+  setState,
+  isOpen,       // boolean
+  open,         // () => void
+  close,        // () => void
+  toggle        // () => void
+} = useChat(initialState);
+```
+
+### useInput
+
+Manages text input state with auto-resize and keyboard handling.
+
+```tsx
+const {
+  value,
+  setValue,
+  clear,
+  textareaRef,
+  handleKeyDown,
+  adjustHeight
+} = useInput({
+  value: inputValue,
+  setValue: setInputValue,
+  onSubmit: handleSubmit,
+  isProcessing: false
+});
+```
+
+## Icons
+
+Pre-built icon components for consistent UI:
+
+```tsx
+import {
+  ThumbsUpIcon,
+  ThumbsDownIcon,
+  CopyIcon,
+  StopIcon,
+  ArrowUpIcon,
+  XIcon,
+  BigSkyIcon,
+  StylesIcon
+} from '@automattic/agenttic-ui';
+```
+
+## Type Definitions
+
+```tsx
+interface Message {
+  id: string;
+  role: 'user' | 'agent';
+  content: Array<{
+    type: 'text' | 'image_url' | 'component';
+    text?: string;
+    image_url?: string;
+    component?: React.ComponentType;
+    componentProps?: any;
+  }>;
+  timestamp: number;
+  archived: boolean;
+  showIcon: boolean;
+  icon?: string;
+  actions?: MessageAction[];
+}
+
+interface MessageAction {
+  id: string;
+  icon: React.ReactNode;
+  label: string;
+  onClick: (message: Message) => void | Promise<void>;
+  tooltip?: string;
+  disabled?: boolean;
+}
+
+interface Suggestion {
+  id: string;
+  label: string;
+  prompt: string;
+}
+
+interface NoticeConfig {
+  icon?: React.ReactNode;
+  message: string;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  dismissible?: boolean;
+  onDismiss?: () => void;
+}
+
+type ChatState = 'collapsed' | 'compact' | 'expanded';
+```
+
+## Styling
+
+### CSS Import
+
+Components automatically import their styles. For manual control:
+
+```css
+/* In your CSS */
+@import '@automattic/agenttic-ui/index.css';
+```
+
+```tsx
+// In JavaScript/TypeScript
+import '@automattic/agenttic-ui/index.css';
+```
+
+### Customization
+
+Components use CSS Modules with design tokens. Override styles using CSS custom properties:
+
+```css
+:root {
+  --agenttic-primary-color: #your-brand-color;
+  --agenttic-border-radius: 8px;
+  --agenttic-spacing-unit: 16px;
+}
+```
+
+## Advanced Usage
+
+### Custom Message Renderer
+
+Provide a custom markdown renderer:
+
+```tsx
+import { ReactMarkdown } from 'react-markdown';
+
+const customRenderer = ({ children }: { children: string }) => (
+  <ReactMarkdown 
+    remarkPlugins={[remarkGfm]}
+    components={{
+      code: ({ children }) => <code className="custom-code">{children}</code>
+    }}
+  >
+    {children}
+  </ReactMarkdown>
+);
+
+<AgentUI
+  messages={messages}
+  messageRenderer={customRenderer}
+  // ... other props
+/>
+```
+
+### Message Actions
+
+Messages can include interactive actions:
+
+```tsx
+const messagesWithActions = messages.map(message => ({
+  ...message,
+  actions: message.role === 'agent' ? [
+    {
+      id: 'copy',
+      icon: <CopyIcon />,
+      label: 'Copy',
+      onClick: () => navigator.clipboard.writeText(message.content[0].text)
+    },
+    {
+      id: 'feedback',
+      icon: <ThumbsUpIcon />,
+      label: 'Good response',
+      onClick: () => console.log('Positive feedback')
+    }
+  ] : []
+}));
+```
+
+### Controlled Chat State
+
+For floating variant, control the chat state externally:
+
+```tsx
+const [chatState, setChatState] = useState<ChatState>('collapsed');
+
+<AgentUI
+  variant="floating"
+  floatingChatState={chatState}
+  onOpen={() => setChatState('compact')}
+  onExpand={() => setChatState('expanded')}
+  onClose={() => setChatState('collapsed')}
+  // ... other props
+/>
+```
+
+### Custom Empty View
+
+Provide custom content when there are no messages:
+
+```tsx
+<AgentUI
+  messages={[]}
+  emptyView={
+    <div className="welcome-message">
+      <h3>Welcome to AI Assistant</h3>
+      <p>I'm here to help you with any questions.</p>
+    </div>
+  }
+  // ... other props
+/>
+```
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Run in development mode
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Type checking
+pnpm type-check
+
+# Start Storybook
+pnpm storybook
+```
+
+## Storybook Documentation
+
+Interactive component documentation is available via Storybook:
+
+```bash
+pnpm storybook
+```
+
+Visit `http://localhost:6006` to explore component examples and documentation.
+
+## Integration with agenttic-client
+
+This UI package is designed to work seamlessly with `@automattic/agenttic-client`:
+
+```tsx
+import { useAgentChat } from '@automattic/agenttic-client';
+import { AgentUI } from '@automattic/agenttic-ui';
+
+function App() {
+  const agentProps = useAgentChat({
+    agentId: 'big-sky',
+    // ... configuration
+  });
+
+  return <AgentUI {...agentProps} variant="floating" />;
+}
+```
+
+The `useAgentChat` hook returns props that match the `AgentUI` interface perfectly, making integration seamless.

package/dist/index.css

@@ -0,0 +1 @@
+:root{--color-background: oklch(.99 0 0);--color-foreground: oklch(.241 0 0);--color-primary: oklch(.53 .22 268.05);--color-primary-foreground: oklch(1 0 0);--color-ring: var(--color-primary);--color-destructive: oklch(.492 .2095 28.09);--color-muted: color-mix(in srgb, var(--color-foreground) 10%, var(--color-background));--color-muted-foreground: color-mix(in srgb, var(--color-background) 40%, var(--color-foreground));--font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-weight-medium: 450;--text-sm: .875rem;--text-sm--line-height: 1.65;--text-base: .9375rem;--text-base--line-height: 1.625;--text-base--tracking: -.01em;--spacing: .25rem;--spacing-1: var(--spacing);--spacing-1\.5: calc(var(--spacing) * 1.5);--spacing-2: calc(var(--spacing) * 2);--spacing-3: calc(var(--spacing) * 3);--spacing-4: calc(var(--spacing) * 4);--spacing-5: calc(var(--spacing) * 5);--spacing-6: calc(var(--spacing) * 6);--spacing-7: calc(var(--spacing) * 7);--spacing-8: calc(var(--spacing) * 8);--spacing-9: calc(var(--spacing) * 9);--spacing-10: calc(var(--spacing) * 10);--spacing-20: calc(var(--spacing) * 20);--radius: 1rem;--radius-xs: calc(var(--radius) - 10px);--radius-sm: calc(var(--radius) - 8px);--radius-md: calc(var(--radius) - 2px);--radius-lg: var(--radius);--radius-xl: calc(var(--radius) + 8px);--radius-full: 9999px;--shadow-sm: 0 0 0 1px color-mix(in srgb, var(--color-foreground) 10%, transparent), 0 0 6px color-mix(in srgb, var(--color-foreground) 5%, transparent);--shadow-lg: 0 0 0 1px rgba(0, 0, 0, .075), 0 2px 24px rgba(0, 0, 0, .075);--shadow-outline: 0 0 0 1px rgba(0, 0, 0, .1);--transition-colors: color, background-color, border-color, text-decoration-color, fill, stroke .15s cubic-bezier(.4, 0, .2, 1)}@layer base{*,:before,:after,::backdrop,::file-selector-button{box-sizing:border-box;margin:0;padding:0;border:0 solid}*{outline-color:var(--color-ring)}button,input,select,optgroup,textarea,::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;background-color:transparent;opacity:1}input,select,optgroup,textarea,::file-selector-button{color:inherit;border-radius:0}}.button-module_button{align-items:center;border-radius:var(--radius-sm);border:1px solid transparent;cursor:pointer;display:inline-flex;flex-shrink:0;font-weight:var(--font-weight-medium);font-size:var(--text-sm);gap:calc(var(--spacing) * .5);justify-content:center;outline:none;transition-duration:.1s;transition:var(--transition-colors);letter-spacing:var(--text-base--tracking);white-space:nowrap;height:var(--spacing-8);padding:var(--spacing-2) var(--spacing-3)}.button-module_button:disabled{pointer-events:none;background-color:var(--color-muted);color:var(--color-muted-foreground)}.button-module_button:focus-visible{outline:2px solid var(--color-ring);outline-offset:1.5px}.button-module_primary{background-color:var(--color-primary);color:var(--color-primary-foreground)}.button-module_primary:hover:not(:disabled){background-color:color-mix(in srgb,var(--color-primary) 85%,#000)}.button-module_ghost{background-color:transparent;color:var(--color-foreground)}.button-module_ghost svg{color:var(--color-muted-foreground)}.button-module_ghost:hover:not(:disabled){background:transparent;color:var(--color-primary)}.button-module_ghost:hover:not(:disabled) svg{color:var(--color-foreground)}.button-module_ghost:focus-visible{outline-offset:0}.button-module_outline{box-shadow:var(--shadow-outline);background-color:var(--color-background);height:calc(var(--spacing-8) - 1px)}.button-module_outline:hover:not(:disabled){color:var(--color-primary)}.button-module_outline:focus-visible{outline-offset:2.5px}.button-module_link{background-color:transparent;color:var(--color-primary);font-weight:var(--font-weight-medium)}.button-module_link:hover:not(:disabled){color:color-mix(in srgb,var(--color-primary) 85%,#000)}.button-module_icon{border-radius:var(--radius-xs);height:var(--spacing-8);width:var(--spacing-8);padding:0}.button-module_sm{height:var(--spacing-6);width:var(--spacing-6);padding:0}.button-module_withTextAndIcon{padding-left:var(--spacing-1)}.button-module_button svg{flex-shrink:0;pointer-events:none;height:var(--spacing-6);width:var(--spacing-6)}.CollapsedView-module_button{border-radius:var(--radius-lg);height:var(--spacing-10);width:var(--spacing-10)}.Textarea-module_textarea{display:flex;width:100%;border-radius:var(--radius-md);border:0;background-color:transparent;min-height:var(--spacing-10);padding-left:var(--spacing-3);padding-right:var(--spacing-3);padding-top:var(--spacing-2);padding-bottom:var(--spacing-2);scrollbar-width:none;resize:none}.Textarea-module_textarea::-moz-placeholder{color:var(--color-muted-foreground);font-weight:var(--font-weight-medium)}.Textarea-module_textarea::placeholder{color:var(--color-muted-foreground);font-weight:var(--font-weight-medium)}.Textarea-module_textarea:focus-visible{outline:none}.Textarea-module_textarea:disabled{cursor:not-allowed;opacity:.5}.ChatInput-module_container{display:flex;align-items:end;gap:var(--spacing)}.ChatInput-module_textareaContainer{flex:1;width:100%}.ChatInput-module_actions{display:flex;flex-direction:row;padding-left:var(--spacing);padding-right:var(--spacing);height:var(--spacing-10);gap:var(--spacing);align-items:center}.ChatInput-module_button{border-radius:var(--radius-full)}.ChatHeader-module_container{display:flex;align-items:center;justify-content:flex-end;gap:var(--spacing);cursor:grab}.ChatHeader-module_container:active{cursor:grabbing}.MessageActions-module_container{display:flex;gap:var(--spacing-1);align-items:center;margin-top:var(--spacing-2)}.MessageActions-module_container button[aria-hidden=true]{display:none}.Message-module_message{display:flex;align-items:flex-start;padding:0 var(--spacing-3);color:var(--color-foreground)}.Message-module_message.Message-module_user .Message-module_bubble{background-color:var(--color-muted);max-width:85%;padding:var(--spacing-3) var(--spacing-4);border-radius:var(--radius-xl);border-bottom-right-radius:var(--radius-sm)}.Message-module_message.Message-module_error{color:var(--color-destructive)}.Message-module_content{flex:1;text-align:start;word-break:break-word;white-space:normal}.Message-module_message.Message-module_user .Message-module_content{display:flex;justify-content:flex-end}.Message-module_message p{text-wrap-style:pretty;margin-bottom:var(--spacing-3)}.Message-module_message a{color:var(--color-primary)}.Message-module_message p:last-child{margin-bottom:0}.Message-module_message strong{font-weight:550}.Message-module_message ol,.Message-module_message ul{margin-bottom:var(--spacing-3);padding-left:var(--spacing-5)}.Message-module_message p+:where(ol,ul){margin-top:0}.Message-module_message li{margin-bottom:var(--spacing-2)}.Message-module_message li::marker{font-size:var(--text-sm)}.Message-module_message table{width:100%;margin:12px 0;border-collapse:collapse}.Message-module_message th,.Message-module_message td{padding:8px 12px;border:1px solid #ddd;text-align:left}.Message-module_message th{background-color:var(--color-muted);font-weight:600}.Messages-module_container{display:flex;flex-direction:column;flex:1;padding-top:var(--spacing-2);padding-bottom:var(--spacing-20);gap:var(--spacing-8);overflow-y:auto;height:100%;position:relative;z-index:10}.Messages-module_container [data-role=user]:has(+[data-role=user]),.Messages-module_container [data-role=agent]:has(+[data-role=agent]){margin-bottom:calc(-1 * var(--spacing-6))}.Messages-module_emptyState{display:flex;flex-direction:column;align-items:center;justify-content:center}.Thinking-module_container{display:flex;align-items:center;gap:var(--spacing-2);padding-left:var(--spacing-3);padding-right:var(--spacing-3);color:var(--color-muted-foreground);font-size:var(--text-sm)}.Thinking-module_icon{display:flex;align-items:center;justify-content:center}.Thinking-module_icon svg{width:var(--spacing-4);height:var(--spacing-4)}.Thinking-module_content{background:linear-gradient(90deg,color-mix(in srgb,currentColor 30%,transparent),currentColor,color-mix(in srgb,currentColor 30%,transparent));background-size:200% 100%;background-clip:text;-webkit-background-clip:text;-webkit-text-fill-color:transparent;animation:Thinking-module_shimmer 2s infinite linear 0ms}@keyframes Thinking-module_shimmer{0%{background-position:200% 0}to{background-position:-200% 0}}.Notice-module_container{position:relative;display:flex;align-items:center;min-height:var(--spacing-10);padding:var(--spacing) var(--spacing) var(--spacing) var(--spacing-4);gap:var(--spacing-3);background-color:var(--color-muted);border-radius:var(--radius-sm);color:var(--color-foreground);font-size:var(--text-sm);font-weight:var(--font-weight-medium);line-height:var(--text-sm--line-height)}.Notice-module_containerWithIcon{padding-left:var(--spacing-3)}.Notice-module_content{align-items:center;display:flex;flex:1;gap:var(--spacing);min-width:0}.Notice-module_actions{align-items:center;display:flex;flex-shrink:0;gap:var(--spacing)}.Notice-module_icon{align-items:center;display:flex;flex-shrink:0;justify-content:center}.Notice-module_icon svg{display:block;height:var(--spacing-5);width:var(--spacing-5)}.Notice-module_dismissible{position:absolute;top:calc(var(--spacing) * -1.5);right:calc(var(--spacing) * -1.5);opacity:0;transform:scale(.9);border-radius:var(--radius-full);transition:all .15s ease}.Notice-module_dismissible:focus,.Notice-module_dismissible:focus-visible,.Notice-module_container:hover .Notice-module_dismissible{opacity:1;transform:scale(1)}.Notice-module_dismissible svg{display:block;width:var(--spacing-4);height:var(--spacing-4);background-color:var(--color-muted-foreground);color:var(--color-background);border-radius:inherit;box-shadow:0 0 0 2.5px var(--color-background);opacity:.8}.Notice-module_dismissible:hover svg{opacity:1}.Suggestions-module_container{position:absolute;top:0;left:0;right:0;display:flex;flex-wrap:nowrap;gap:var(--spacing-2);padding:var(--spacing-2) var(--spacing-1\.5);overflow-x:auto;overflow-y:hidden;scrollbar-width:none;-ms-overflow-style:none}.Suggestions-module_container::-webkit-scrollbar{display:none}.ConversationView-module_container{display:flex;flex-direction:column;height:100%;justify-content:flex-end}.ConversationView-module_container.ConversationView-module_withHeader{justify-content:space-between}.ConversationView-module_inputWrapper{position:relative}.ConversationView-module_inputContainer{box-shadow:var(--shadow-sm);padding:var(--spacing-2);background-color:var(--color-background);border-radius:calc(var(--radius-lg) + 1px);color:var(--color-foreground);position:relative;z-index:10;filter:brightness(1.1)}.ConversationView-module_inputContainerInner{display:flex;flex-direction:column;gap:var(--spacing-2)}.Chat-module_container{font-size:var(--text-base);line-height:var(--text-base--line-height);font-weight:400;font-family:var(--font-sans);letter-spacing:var(--text-base--tracking);text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased}.Chat-module_container.Chat-module_embedded{height:100%}.Chat-module_container.Chat-module_floating{position:fixed;z-index:50}.Chat-module_container.Chat-module_floating .Chat-module_content{background-color:var(--color-background);color:var(--color-foreground);overflow:hidden;min-height:56px;padding:var(--spacing-2);box-shadow:var(--shadow-lg)}