@agentxjs/ui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Deepractice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @agentxjs/ui
+
+React component library for building AI agent interfaces.
+
+## Features
+
+- React components optimized for AI agent UIs
+- TypeScript support with full type definitions
+- Tailwind CSS for styling with custom design tokens
+- Storybook for component development and documentation
+- Tree-shakeable ESM exports
+
+## Installation
+
+```bash
+pnpm add @agentxjs/ui
+```
+
+## Usage
+
+```tsx
+import { Button } from "@agentxjs/ui";
+import "@agentxjs/ui/styles.css";
+
+function App() {
+  return <Button>Click me</Button>;
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run Storybook
+pnpm storybook
+
+# Build the library
+pnpm build
+
+# Type checking
+pnpm typecheck
+
+# Linting
+pnpm lint
+```
+
+## Architecture
+
+This package follows a layered architecture:
+
+- `src/api/` - Public API (skin layer)
+- `src/types/` - Public type definitions
+- `src/components/` - React components
+- `src/styles/` - Global styles and design tokens
+- `src/utils/` - Utility functions
+
+## Design System
+
+The component library uses a semantic token system based on Tailwind CSS:
+
+- **Primary**: Computational intelligence (Blue)
+- **Secondary**: Generative creativity (Amber)
+- **Accent**: Interactive highlights (Orange)
+- **Success/Warning/Error**: Feedback states
+
+Dark mode is supported via CSS custom properties.
+
+## Related Packages
+
+- **[agentxjs](../agentx)** - Platform API (createAgentX, defineAgent)
+- **[@agentxjs/types](../agentx-types)** - Message and event type definitions
+- **[@agentxjs/agent](../agentx-agent)** - Agent runtime
+
+## License
+
+MIT

package/dist/api/index.d.ts

@@ -0,0 +1,9 @@
+export * from '../hooks';
+export * from '../components/container';
+export * from '../components/studio';
+export * from '../components/message';
+export * from '../components/input';
+export * from '../components/layout';
+export * from '../components/element';
+export * from '../components/typography';
+export * from '../utils';

package/dist/components/container/AgentPane.d.ts

@@ -0,0 +1,56 @@
+import { AgentError, AgentState, Message } from '@agentxjs/types';
+import { AgentDefinitionItem, SessionItem } from './types';
+export interface AgentPaneProps {
+    /**
+     * Current agent definition (for display)
+     */
+    definition: AgentDefinitionItem | null;
+    /**
+     * Current session (for display)
+     */
+    session: SessionItem | null;
+    /**
+     * Current agent ID (for display)
+     */
+    agentId?: string | null;
+    /**
+     * Messages to display
+     */
+    messages?: Message[];
+    /**
+     * Streaming message content
+     */
+    streaming?: string;
+    /**
+     * Error messages
+     */
+    errors?: AgentError[];
+    /**
+     * Agent status
+     */
+    status?: AgentState;
+    /**
+     * Loading state
+     */
+    isLoading?: boolean;
+    /**
+     * Callback to abort current request
+     */
+    onAbort?: () => void;
+    /**
+     * Callback to create a new session
+     */
+    onCreateSession?: () => void;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * AgentPane - Agent message display area (pure presentation)
+ *
+ * States:
+ * 1. isLoading + no messages → Connecting/Loading
+ * 2. Ready → Show MessagePane (may be empty)
+ */
+export declare function AgentPane({ definition, session, agentId, messages, streaming, errors, status, isLoading, onAbort, className, }: AgentPaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/ContainerView.d.ts

@@ -0,0 +1,119 @@
+import { ReactNode } from 'react';
+import { Message, AgentError } from '@agentxjs/types';
+import { AgentDefinitionItem } from './types';
+import { SessionItem } from '../../hooks/useSession';
+/**
+ * Props for ContainerView component
+ *
+ * All data is passed in, no internal state management.
+ */
+export interface ContainerViewProps {
+    /**
+     * Available agent definitions
+     */
+    definitions: AgentDefinitionItem[];
+    /**
+     * User's sessions
+     */
+    sessions: SessionItem[];
+    /**
+     * Currently selected definition
+     */
+    currentDefinition: AgentDefinitionItem | null;
+    /**
+     * Currently selected session
+     */
+    currentSession: SessionItem | null;
+    /**
+     * Messages in current conversation
+     */
+    messages: Message[];
+    /**
+     * Current streaming text (assistant response in progress)
+     */
+    streaming?: string;
+    /**
+     * Errors from agent
+     */
+    errors?: AgentError[];
+    /**
+     * Whether agent is processing
+     */
+    isLoading: boolean;
+    /**
+     * Called when user selects a definition
+     */
+    onSelectDefinition: (definition: AgentDefinitionItem) => void;
+    /**
+     * Called when user selects a session
+     */
+    onSelectSession: (session: SessionItem) => void;
+    /**
+     * Called when user wants to create a new session
+     */
+    onCreateSession: () => void;
+    /**
+     * Called when user sends a message
+     */
+    onSend: (text: string) => void;
+    /**
+     * Called when user wants to abort current response
+     */
+    onAbort?: () => void;
+    /**
+     * Called when user wants to add a definition
+     */
+    onAddDefinition?: () => void;
+    /**
+     * Called when user wants to delete a session
+     */
+    onDeleteSession?: (sessionId: string) => void;
+    /**
+     * Custom render for the entire layout
+     * If provided, takes full control of rendering
+     */
+    children?: (props: ContainerViewRenderProps) => ReactNode;
+    /**
+     * Custom className for container
+     */
+    className?: string;
+}
+/**
+ * Props passed to custom render function
+ */
+export interface ContainerViewRenderProps {
+    definitions: AgentDefinitionItem[];
+    sessions: SessionItem[];
+    currentDefinition: AgentDefinitionItem | null;
+    currentSession: SessionItem | null;
+    messages: Message[];
+    streaming?: string;
+    errors?: AgentError[];
+    isLoading: boolean;
+    onSelectDefinition: (definition: AgentDefinitionItem) => void;
+    onSelectSession: (session: SessionItem) => void;
+    onCreateSession: () => void;
+    onSend: (text: string) => void;
+    onAbort?: () => void;
+    onAddDefinition?: () => void;
+    onDeleteSession?: (sessionId: string) => void;
+}
+/**
+ * ContainerView - Pure UI layout component
+ *
+ * Default layout (3-column):
+ * ```
+ * ┌──────────┬────────────┬──────────────────────────┐
+ * │          │            │                          │
+ * │ Def.Pane │ Sess.Pane  │      AgentPane           │
+ * │  (60px)  │  (240px)   │                          │
+ * │          │            ├──────────────────────────┤
+ * │          │            │      InputPane           │
+ * └──────────┴────────────┴──────────────────────────┘
+ * ```
+ *
+ * When `children` is provided, it acts as a render props container.
+ */
+export declare function ContainerView({ definitions, sessions, currentDefinition, currentSession, messages, streaming, errors, isLoading, onSelectDefinition, onSelectSession, onCreateSession, onSend, onAbort, onAddDefinition, onDeleteSession, children, className, }: ContainerViewProps): import("react/jsx-runtime").JSX.Element;
+export type { AgentDefinitionItem } from './types';
+export type { SessionItem } from '../../hooks/useSession';

package/dist/components/container/DefinitionPane.d.ts

@@ -0,0 +1,27 @@
+import { AgentDefinitionItem } from './types';
+export interface DefinitionPaneProps {
+    /**
+     * Available agent definitions
+     */
+    definitions: AgentDefinitionItem[];
+    /**
+     * Currently selected definition
+     */
+    current: AgentDefinitionItem | null;
+    /**
+     * Callback when an agent is selected
+     */
+    onSelect: (definition: AgentDefinitionItem) => void;
+    /**
+     * Callback when settings button is clicked
+     */
+    onSettings?: () => void;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * DefinitionPane - Agent selection for ActivityBar
+ */
+export declare function DefinitionPane({ definitions, current, onSelect, onSettings, className, }: DefinitionPaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/InputPane.d.ts

@@ -0,0 +1,44 @@
+/**
+ * InputPane - Business container for user input
+ *
+ * Expanded input area with toolbar and full-width input box.
+ * Designed to be used inside a resizable Panel.
+ *
+ * @example
+ * ```tsx
+ * <Allotment.Pane minSize={120} maxSize={600}>
+ *   <InputPane
+ *     onSend={send}
+ *     onFileAttach={handleFiles}
+ *     disabled={isLoading}
+ *   />
+ * </Allotment.Pane>
+ * ```
+ */
+export interface InputPaneProps {
+    /**
+     * Callback when user sends a message
+     */
+    onSend: (text: string) => void;
+    /**
+     * Whether input is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string;
+    /**
+     * Callback when user uploads files via toolbar
+     */
+    onFileAttach?: (files: File[]) => void;
+    /**
+     * Show toolbar
+     */
+    showToolbar?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+export declare function InputPane({ onSend, disabled, placeholder, onFileAttach, showToolbar, className, }: InputPaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/InputToolBar.d.ts

@@ -0,0 +1,22 @@
+/**
+ * InputToolBar - Toolbar for input area with file upload and other tools
+ *
+ * Provides utility buttons for the input pane:
+ * - File upload (read files)
+ * - Future: Model selector, settings, etc.
+ */
+export interface InputToolBarProps {
+    /**
+     * Callback when user uploads files
+     */
+    onFileAttach?: (files: File[]) => void;
+    /**
+     * Whether the toolbar is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+export declare function InputToolBar({ onFileAttach, disabled, className, }: InputToolBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/MessagePane.d.ts

@@ -0,0 +1,32 @@
+import { Message, AgentError, AgentState } from '@agentxjs/types';
+export interface MessagePaneProps {
+    /**
+     * Messages to display
+     */
+    messages: Message[];
+    /**
+     * Current streaming text
+     */
+    streaming?: string;
+    /**
+     * Errors to display
+     */
+    errors?: AgentError[];
+    /**
+     * Current agent state
+     */
+    status?: AgentState;
+    /**
+     * Whether agent is loading
+     */
+    isLoading?: boolean;
+    /**
+     * Callback to abort current operation
+     */
+    onAbort?: () => void;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+export declare function MessagePane({ messages, streaming, errors, status, isLoading, onAbort, className, }: MessagePaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/SessionPane.d.ts

@@ -0,0 +1,35 @@
+import { SessionItem } from './types';
+export interface SessionPaneProps {
+    /**
+     * Sessions to display
+     */
+    sessions: SessionItem[];
+    /**
+     * Currently selected session
+     */
+    current: SessionItem | null;
+    /**
+     * Agent name for header display
+     */
+    agentName?: string;
+    /**
+     * Callback when a session is selected
+     */
+    onSelect: (session: SessionItem) => void;
+    /**
+     * Callback when create button is clicked
+     */
+    onCreate?: () => void;
+    /**
+     * Callback when delete is requested
+     */
+    onDelete?: (sessionId: string) => void;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * SessionPane - Session list for Sidebar
+ */
+export declare function SessionPane({ sessions, current, agentName: _agentName, onSelect, onCreate, onDelete, className, }: SessionPaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/container/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Container Components - Pure UI Panes
+ *
+ * Part of UI-Backend API Consistency design (see index.ts ADR #5):
+ * - These are pure UI components (presentational)
+ * - For integration, use Studio from ~/components/studio
+ */
+export { ContainerView } from './ContainerView';
+export type { ContainerViewProps, ContainerViewRenderProps } from './ContainerView';
+export { DefinitionPane } from './DefinitionPane';
+export type { DefinitionPaneProps } from './DefinitionPane';
+export { SessionPane } from './SessionPane';
+export type { SessionPaneProps } from './SessionPane';
+export { AgentPane } from './AgentPane';
+export type { AgentPaneProps } from './AgentPane';
+export { MessagePane } from './MessagePane';
+export type { MessagePaneProps } from './MessagePane';
+export { InputPane } from './InputPane';
+export type { InputPaneProps } from './InputPane';
+export { InputToolBar } from './InputToolBar';
+export type { InputToolBarProps } from './InputToolBar';
+export type { SessionItem, AgentDefinitionItem } from './types';

package/dist/components/container/types.d.ts

@@ -0,0 +1,67 @@
+import { AgentDefinition } from '@agentxjs/types';
+/**
+ * Session item for UI display (pure data, no methods)
+ *
+ * Core fields come from Session interface (Docker-style architecture).
+ * Additional fields (preview, unreadCount) are computed/derived by UI.
+ *
+ * Part of Docker-style layered architecture:
+ * Definition → build → Image → run → Agent
+ *                        ↓
+ *                    Session (userId + imageId)
+ */
+export interface SessionItem {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Owner user ID
+     */
+    userId: string;
+    /**
+     * Associated image ID (frozen runtime snapshot)
+     */
+    imageId: string;
+    /**
+     * Display title (can be AI-generated summary)
+     */
+    title: string | null;
+    /**
+     * Session creation timestamp (Unix ms)
+     */
+    createdAt: number;
+    /**
+     * Last update timestamp (Unix ms)
+     */
+    updatedAt: number;
+    /**
+     * Preview text (last message snippet) - computed from messages
+     */
+    preview?: string;
+    /**
+     * Unread message count - computed by UI
+     */
+    unreadCount?: number;
+}
+/**
+ * Extended AgentDefinition with UI metadata
+ */
+export interface AgentDefinitionItem extends AgentDefinition {
+    /**
+     * Icon identifier or emoji
+     */
+    icon?: string;
+    /**
+     * Badge color for visual distinction
+     */
+    color?: string;
+    /**
+     * Whether this agent is online/available
+     */
+    isOnline?: boolean;
+    /**
+     * Number of active sessions
+     */
+    activeSessionCount?: number;
+}

package/dist/components/element/ActionBar.d.ts

@@ -0,0 +1,43 @@
+import { buttonVariants } from './Button';
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+export interface ActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Children (ActionBar.Primary, ActionBar.Icon, ActionBar.Group)
+     */
+    children: React.ReactNode;
+}
+export interface ActionBarPrimaryProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    /**
+     * Button content
+     */
+    children: React.ReactNode;
+    /**
+     * Show loading state
+     */
+    loading?: boolean;
+}
+export interface ActionBarIconProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    /**
+     * Icon element
+     */
+    children: React.ReactNode;
+    /**
+     * Show loading state
+     */
+    loading?: boolean;
+}
+export interface ActionBarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Group children
+     */
+    children: React.ReactNode;
+}
+/**
+ * Compound component export
+ */
+export declare const ActionBar: React.ForwardRefExoticComponent<ActionBarProps & React.RefAttributes<HTMLDivElement>> & {
+    Primary: React.ForwardRefExoticComponent<ActionBarPrimaryProps & React.RefAttributes<HTMLButtonElement>>;
+    Icon: React.ForwardRefExoticComponent<ActionBarIconProps & React.RefAttributes<HTMLButtonElement>>;
+    Group: React.ForwardRefExoticComponent<ActionBarGroupProps & React.RefAttributes<HTMLDivElement>>;
+};

package/dist/components/element/AgentLogo.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+export interface AgentLogoProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+    /**
+     * Custom icon source URL. Defaults to "/icons/agent-ai-icon.svg"
+     */
+    src?: string;
+}
+/**
+ * AgentLogo - Display the Agent AI logo
+ *
+ * Single Responsibility: Display a logo image with consistent sizing
+ *
+ * @example
+ * ```tsx
+ * <AgentLogo />
+ * <AgentLogo className="w-8 h-8" />
+ * <AgentLogo src="/custom-logo.svg" />
+ * ```
+ */
+declare const AgentLogo: React.ForwardRefExoticComponent<AgentLogoProps & React.RefAttributes<HTMLImageElement>>;
+export { AgentLogo };

package/dist/components/element/AppHeader.d.ts

@@ -0,0 +1,84 @@
+import * as React from "react";
+export interface AppHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Logo element (icon or image)
+     */
+    logo?: React.ReactNode;
+    /**
+     * Application title
+     */
+    title: string;
+    /**
+     * Subtitle or description (optional)
+     */
+    subtitle?: string;
+    /**
+     * Additional actions on the right side
+     */
+    actions?: React.ReactNode;
+    /**
+     * Whether to show border at bottom
+     * @default true
+     */
+    showBorder?: boolean;
+    /**
+     * Whether in mobile mode (compact layout)
+     * @default false
+     */
+    isMobile?: boolean;
+    /**
+     * Whether running as PWA (adds safe area padding)
+     * @default false
+     */
+    isPWA?: boolean;
+}
+/**
+ * AppHeader - Application header with logo, title, and actions
+ *
+ * A flexible header component for application layouts. Supports logos,
+ * titles, subtitles, and action buttons. Automatically adapts to mobile
+ * and PWA environments.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <AppHeader
+ *   logo={<MessageSquare className="w-4 h-4" />}
+ *   title="Deepractice Agent"
+ * />
+ *
+ * // With subtitle
+ * <AppHeader
+ *   logo={<Bot className="w-4 h-4" />}
+ *   title="AI Assistant"
+ *   subtitle="Powered by Claude"
+ * />
+ *
+ * // With actions
+ * <AppHeader
+ *   logo={<Logo />}
+ *   title="My App"
+ *   actions={
+ *     <Button variant="ghost" size="sm">
+ *       <Settings className="w-4 h-4" />
+ *     </Button>
+ *   }
+ * />
+ *
+ * // Mobile mode
+ * <AppHeader
+ *   logo={<MessageSquare />}
+ *   title="Agent"
+ *   isMobile
+ * />
+ *
+ * // PWA with safe area
+ * <AppHeader
+ *   logo={<Logo />}
+ *   title="App"
+ *   isPWA
+ *   isMobile
+ * />
+ * ```
+ */
+export declare const AppHeader: React.ForwardRefExoticComponent<AppHeaderProps & React.RefAttributes<HTMLDivElement>>;