Clara UI SDK (Sidebar Library)

A lightweight, modern React sidebar library with WebSocket integration. Built with functional programming, React Hooks, and Vite.

Features

• ✅ Simple - No over-engineering, straightforward API
• ✅ Functional - Pure functions and hooks-based architecture
• ✅ Modern - React 17+ and 18+ compatible
• ✅ Lightweight - Minimal dependencies (React, socket.io-client)
• ✅ Flexible - Easy to customize with configuration options
• ✅ WebSocket Integration - Real-time messaging with socket.io
• ✅ Responsive - Mobile-friendly with adaptive widths
• ✅ Dark Mode - Automatic dark mode support

Installation

npm install clara-ui-sdk

Quick Start

1. Wrap your app with SidebarProvider

import React from 'react';
import { SidebarProvider } from 'clara-ui-sdk';

function App() {
  const handleMessage = (message) => {
    console.log('Message received:', message);
  };

  return (
    <SidebarProvider
      socketUrl="wss://api.example.com"
      userToken="your-auth-token"
      onMessage={handleMessage}
      position="right"
      width="320px"
    >
      <YourApp />
    </SidebarProvider>
  );
}

2. Control the sidebar

import React from 'react';
import { useSidebar } from 'clara-ui-sdk';

const Header = () => {
  const { toggleSidebar, isVisible } = useSidebar();

  return (
    <header>
      <button onClick={toggleSidebar}>
        {isVisible ? 'Close' : 'Open'} Sidebar
      </button>
    </header>
  );
};

3. Send and receive messages

import React, { useState } from 'react';
import { useSocket, useSocketMessage } from 'clara-ui-sdk';

const ChatComponent = () => {
  const [text, setText] = useState('');
  const { sendMessage, isConnected } = useSocket();

  // Listen for incoming messages
  useSocketMessage('chat', (message) => {
    console.log('Chat message:', message.payload);
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    if (text.trim() && isConnected) {
      sendMessage({
        type: 'chat',
        payload: { text }
      });
      setText('');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        disabled={!isConnected}
        placeholder={isConnected ? 'Type a message...' : 'Connecting...'}
      />
      <button type="submit" disabled={!isConnected}>
        Send
      </button>
    </form>
  );
};

API Reference

SidebarProvider

The main provider component that wraps your application.

Props:

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | socketUrl | string | Yes | - | WebSocket server URL (ws:// or wss://) | | userToken | string | Yes | - | Authentication token for WebSocket connection | | position | 'left' | 'right' | No | 'right' | Sidebar position | | width | string | No | '320px' | Sidebar width (CSS value) | | onMessage | function | No | - | Global message handler callback | | onConnect | function | No | - | Connection established callback | | onDisconnect | function | No | - | Disconnection callback | | onError | function | No | - | Error handler callback |

Hooks

useSidebar()

Control sidebar visibility and state.

const {
  isVisible,      // boolean - Sidebar visibility state
  toggleSidebar,  // function - Toggle sidebar
  openSidebar,    // function - Open sidebar
  closeSidebar,   // function - Close sidebar
  position,       // string - Current position ('left' | 'right')
  width          // string - Current width
} = useSidebar();

useSocket()

Interact with the WebSocket connection.

const {
  isConnected,    // boolean - Connection status
  sendMessage,    // function(message) - Send message to server
  subscribe      // function(callback) - Subscribe to all messages
} = useSocket();

sendMessage(message):

• Returns: boolean - true if sent, false if not connected
• Example: sendMessage({ type: 'chat', payload: { text: 'Hello' } })

subscribe(callback):

• Returns: function - Unsubscribe function
• Example:

  useEffect(() => {
    const unsubscribe = subscribe((message) => {
      console.log('Message:', message);
    });
    return unsubscribe;
  }, []);

useSocketMessage(messageTypes, callback)

Listen for specific message types.

// Single message type
useSocketMessage('notification', (message) => {
  console.log('Notification:', message);
});

// Multiple message types
useSocketMessage(['alert', 'warning'], (message) => {
  console.log('Alert/Warning:', message);
});

Parameters:

• messageTypes: string | string[] - Message type(s) to listen for
• callback: function(message) - Handler function

Constants

import { SIDEBAR_POSITIONS } from 'clara-ui-sdk';

// Available positions
SIDEBAR_POSITIONS.LEFT   // 'left'
SIDEBAR_POSITIONS.RIGHT  // 'right'

Advanced Usage

Custom Message Handlers

import { useSocketMessage } from 'clara-ui-sdk';

const NotificationComponent = () => {
  // Handle notifications
  useSocketMessage('notification', (message) => {
    // Show toast notification
    showToast(message.payload.text);
  });

  // Handle multiple types
  useSocketMessage(['alert', 'warning', 'error'], (message) => {
    // Log to console
    console.warn(message.type, message.payload);
  });

  return null;
};

Programmatic Control

import { useSidebar } from 'clara-ui-sdk';

const MyComponent = () => {
  const { openSidebar, closeSidebar } = useSidebar();

  useEffect(() => {
    // Open sidebar on mount
    openSidebar();

    // Close after 5 seconds
    const timer = setTimeout(() => {
      closeSidebar();
    }, 5000);

    return () => clearTimeout(timer);
  }, []);

  return <div>Content</div>;
};

Connection Status Monitoring

import { useSocket } from 'clara-ui-sdk';

const ConnectionStatus = () => {
  const { isConnected } = useSocket();

  return (
    <div className={isConnected ? 'connected' : 'disconnected'}>
      {isConnected ? '🟢 Connected' : '🔴 Disconnected'}
    </div>
  );
};

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library for production
npm run build

# Preview production build
npm run preview

Architecture

• Hooks-based: Uses React Hooks for state management
• Context API: Centralized state with React Context
• Socket.io: WebSocket communication
• Vite: Fast build tool with library mode
• Functional Programming: Pure functions, immutable data

Browser Support

• Chrome/Edge (latest 2 versions)
• Firefox (latest 2 versions)
• Safari 14+
• Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT

What's NOT Included (By Design)

This library intentionally stays simple and focused:

• ❌ Message queuing / offline support
• ❌ Complex state management
• ❌ Multiple socket connections
• ❌ TypeScript (uses JSDoc for IDE support)

These features can be added in your application layer if needed.