WIP: feat(tarko-agent-ui): ui sdk

[ulivz]

Summary

Implement comprehensive composable component API for @tarko/agent-ui enabling flexible, slot-based UI composition while maintaining full backward compatibility.

Key Features:

• 🎯 Composable API: Slot-based component composition with lifecycle hooks
• 🔧 Flexible Layouts: Default, minimal, and completely custom layout options
• 🎨 Theme Support: Light, dark, and auto theme modes
• 📱 Responsive Design: Built-in responsive layout handling
• ⚡ Zero Breaking Changes: Full backward compatibility maintained
• 📚 TypeScript Support: Comprehensive type definitions

New Composable API

Basic Usage

import { App, Home, Sidebar, Navbar } from '@tarko/agent-ui';

const CustomLayout = () => (
  <App
    // Lifecycle hooks
    onBeforeInit={() => console.log('Initializing...')}
    onAfterInit={() => console.log('Ready!')}
    
    // Slot-based composition
    navbar={
      <Navbar 
        items={<CustomNavContent />}
        leftActions={<Logo />}
        rightActions={<UserMenu />}
      />
    }
    
    sidebar={
      <Sidebar 
        items={<CustomSidebarContent />}
        header={<div>Custom Header</div>}
        footer={<div>Custom Footer</div>}
        width={300}
      />
    }
    
    main={<Home />}
    
    // Configuration
    layout="default"
    theme="auto"
  />
);

Advanced Customization

// Custom Home Page
<Home
  welcomeMessage={<CustomWelcome />}
  quickActions={[
    <button>New Chat</button>,
    <button>Upload File</button>
  ]}
  customSections={[<StatsCard />, <RecentActivity />]}
  variant="dashboard"
  layout="grid"
/>

// Minimal Layout
<App
  layout="minimal"
  main={<ChatPanel />}
/>

// Completely Custom Layout
<App layout="custom">
  <div className="h-screen flex flex-col">
    <header>Custom Header</header>
    <main className="flex-1">
      <ChatPanel />
    </main>
    <footer>Custom Footer</footer>
  </div>
</App>

Component API

App Component

• Lifecycle: onBeforeInit, onAfterInit hooks
• Slots: navbar, sidebar, main composition
• Layouts: default, minimal, custom variants
• Themes: light, dark, auto modes

Home Component

• Content: Custom welcome messages and sections
• Actions: Configurable quick action buttons
• Variants: default, minimal, dashboard layouts
• Events: onNewChat, onUploadFile handlers

Sidebar Component

• Content: Custom items, header, footer slots
• Configuration: Width, variants, session management
• Events: Session selection and management handlers

Navbar Component

• Actions: Left and right action slots
• Configuration: Model/agent selectors, settings
• Events: Model change, agent change handlers

Exports

// Composable Components (New API)
export { App, Home, Sidebar, Navbar } from '@tarko/agent-ui';

// Original Components (Direct access)
export { 
  OriginalApp, 
  OriginalHome, 
  OriginalSidebar, 
  OriginalNavbar 
} from '@tarko/agent-ui';

// Legacy Support (Unchanged)
export { AgentWebUI, WebUIConfigProvider } from '@tarko/agent-ui';

// Hooks & State
export { 
  useSession, 
  useReplayMode, 
  layoutModeAtom 
} from '@tarko/agent-ui';

Migration Path

Current (Still Works):

import { AgentWebUI, WebUIConfigProvider } from '@tarko/agent-ui';

<WebUIConfigProvider>
  <AgentWebUI />
</WebUIConfigProvider>

New Composable API:

import { App, Navbar, Sidebar, ChatPanel } from '@tarko/agent-ui';

<App
  navbar={<Navbar />}
  sidebar={<Sidebar />}
  main={<ChatPanel />}
/>

File Structure

• @tarko/agent-ui-app: 7 files (minimal wrapper)
• @tarko/agent-ui: Enhanced with composable components
• src/components/: New composable component implementations
• src/examples/: Usage examples and patterns
• README.md: Comprehensive documentation

Benefits

• ✅ Flexible Composition: Mix and match components as needed
• ✅ Lifecycle Control: Hook into initialization and setup
• ✅ Custom Layouts: From minimal to completely custom
• ✅ Event Handling: Full control over user interactions
• ✅ TypeScript Support: Complete type safety
• ✅ Zero Breaking Changes: Existing code continues to work
• ✅ Progressive Enhancement: Adopt new API incrementally

Checklist

• Added or updated necessary tests (Optional).
• Updated documentation to align with changes (Optional).
• Verified no breaking changes, or prepared solutions for any occurring breaking changes (Optional).
• My change does not involve the above items.

[netlify]

❌ Deploy Preview for agent-tars-docs failed.

Name	Link
🔨 Latest commit	1ae55fc
🔍 Latest deploy log	https://app.netlify.com/projects/agent-tars-docs/deploys/68c5f11db78e300008921465

[ulivz]

Close this since we need more time to design well