@dananai/sidebar-sdk

v1.0.11

Published

4 months ago

A powerful sidebar SDK for integrating AI chat interfaces into web applications

0High
0Medium
0Low

dananai

sidebar chat ai sdk react typescript ui interface

Sidebar SDK

A powerful and flexible sidebar SDK for integrating AI chat interfaces into web applications. Built with React, TypeScript, and modern web technologies.

Features

🤖 AI Chat Integration - Seamless integration with AI chat APIs
🎨 Modern UI - Beautiful, responsive sidebar interface with Tailwind CSS
📱 Mobile Friendly - Optimized for both desktop and mobile devices
🔧 Highly Configurable - Extensive customization options
📦 Multiple Formats - Available as UMD and ESM modules
🎯 TypeScript Support - Full TypeScript definitions included
⌨️ Keyboard Shortcuts - Built-in keyboard shortcuts (Cmd/Ctrl+B)
🎭 CSS Isolation - Scoped styles to prevent conflicts with host applications

Installation

NPM Package (Recommended)

npm install @dananai/sidebar-sdk

Yarn

yarn add @dananai/sidebar-sdk

PNPM

pnpm add @dananai/sidebar-sdk

Usage

Method 1: Auto-Initialization (Recommended)

The SDK automatically initializes when loaded. Simply include the CSS and the SDK will handle the rest:

import '@dananai/sidebar-sdk/dist/sidebar-sdk.css';

// The SDK automatically initializes with default settings
// You can access it globally via window.SidebarSdk

Method 2: Manual Initialization

import { SidebarSDK } from '@dananai/sidebar-sdk';
import '@dananai/sidebar-sdk/dist/sidebar-sdk.css';

// Create SDK instance with custom configuration
const sdk = new SidebarSDK({
  project_id: 'your-project-id',
  user_id: 'your-user-id',
  debug: true,
  width: '40vw',
  maxWidth: '600px',
  defaultOpen: false,
  keyboardShortcut: 'b',
  resizable: true
});

// Initialize the sidebar
sdk.init();

Method 3: Script Tag with Parameters

<!DOCTYPE html>
<html>
<head>
  <title>Sidebar SDK Demo</title>
  <!-- Include React and ReactDOM -->
  <script crossorigin src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>

  <!-- Include the Sidebar SDK CSS -->
  <link rel="stylesheet" href="https://unpkg.com/@dananai/[email protected]/dist/sidebar-sdk.css">

  <!-- Include the Sidebar SDK with configuration -->
  <script
    src="https://unpkg.com/@dananai/[email protected]/dist/index.js"
    data-project-id="your-project-id"
    data-user-id="your-user-id"
    data-debug="true"
    data-width="40vw"
    data-max-width="600px"
    data-default-open="false"
    data-keyboard-shortcut="b"
    data-resizable="true">
  </script>
</head>
<body>
  <div id="app">
    <h1>Your App Content</h1>
    <p>The sidebar will automatically initialize and be accessible via keyboard shortcuts.</p>
  </div>
</body>
</html>

Configuration Options

SDK Configuration

interface SidebarSDKConfig {
  // Required: Your project identifier
  project_id?: string;

  // Required: User identifier
  user_id?: string;

  // Enable debug logging
  debug?: boolean;

  // Sidebar width (default: '40vw')
  width?: string;

  // Maximum width (default: '600px')
  maxWidth?: string;

  // Initial state (default: false)
  defaultOpen?: boolean;

  // Keyboard shortcut key (default: 'b')
  keyboardShortcut?: string;

  // Enable resizing (default: true)
  resizable?: boolean;
}

Example Configuration

const sdk = new SidebarSDK({
  project_id: 'my-awesome-project',
  user_id: 'user-123',
  debug: true,
  width: '35vw',
  maxWidth: '500px',
  defaultOpen: true,
  keyboardShortcut: 's',
  resizable: false
});

API Reference

SidebarSDK Class

Constructor

new SidebarSDK(config?: SidebarSDKConfig)

Methods

`init()`

Initializes the sidebar with the current configuration.

sdk.init();

`show()`

Shows the sidebar.

sdk.show();

`hide()`

Hides the sidebar.

sdk.hide();

`toggle()`

Toggles the sidebar visibility.

sdk.toggle();

`triggerKeyboardShortcut()`

Programmatically triggers the configured keyboard shortcut.

sdk.triggerKeyboardShortcut();

`updateConfig(newConfig: Partial<SidebarSDKConfig>)`

Updates the SDK configuration and re-initializes if needed.

sdk.updateConfig({
  width: '50vw',
  debug: false
});

`getStatus(): SidebarSDKStatus`

Returns the current status of the sidebar.

const status = sdk.getStatus();
console.log(status.visible); // boolean
console.log(status.width); // string
console.log(status.config); // SidebarSDKConfig

`getProjectId(): string | undefined`

Returns the project ID from configuration or script parameters.

const projectId = sdk.getProjectId();

`getUserId(): string | undefined`

Returns the user ID from configuration or script parameters.

const userId = sdk.getUserId();

`getScriptParameters(): Record<string, string>`

Returns all script tag parameters.

const params = sdk.getScriptParameters();

`getScriptParameter(paramName: string, fallback?: string): string | undefined`

Returns a specific script parameter value.

const projectId = sdk.getScriptParameter('project_id', 'default-project');

`hasScriptParameter(paramName: string): boolean`

Checks if a script parameter exists.

if (sdk.hasScriptParameter('debug')) {
  console.log('Debug mode enabled via script tag');
}

Global Functions

When the sidebar is initialized, these functions become available globally:

// Toggle sidebar visibility
window.sidebarToggle();

// Show sidebar
window.sidebarShow();

// Hide sidebar
window.sidebarHide();

// Resize sidebar (if resizable is enabled)
window.resizeSidebar(500); // width in pixels

Global Variables

// Access the SDK instance
const sdk = window.SidebarSdk;

CSS Isolation (Shadow DOM)

The SDK uses Shadow DOM for complete CSS isolation from your host application. This ensures that:

✅ Zero CSS conflicts - Host styles cannot affect the sidebar
✅ Self-contained styling - All sidebar styles are isolated
✅ No external dependencies - All CSS is bundled within the Shadow DOM
✅ Cross-browser compatibility - Works in all modern browsers

How It Works

The sidebar is rendered inside a Shadow DOM, which creates a completely isolated DOM tree with its own CSS scope. This means:

Host CSS cannot penetrate the Shadow DOM boundary
Sidebar styles are self-contained and won't affect the host page
No CSS resets needed - The Shadow DOM provides complete isolation
Automatic styling - All necessary styles are injected automatically

No Additional CSS Needed!

With Shadow DOM, no additional CSS is required in your host application. The sidebar is completely self-contained and isolated.

Customization (Optional)

If you need to customize the sidebar appearance, you can do so through the SDK configuration:

const sdk = new SidebarSDK({
  // ... other config
  // The sidebar will automatically adapt to your preferences
  // while maintaining complete CSS isolation
});

Keyboard Shortcuts

The SDK includes built-in keyboard shortcuts:

Cmd/Ctrl + B (default): Toggle sidebar visibility
Enter: Submit chat message (when sidebar is open and input has content)

You can customize the toggle shortcut via the keyboardShortcut configuration option.

Examples

Basic Integration

import '@dananai/sidebar-sdk/dist/sidebar-sdk.css';

function App() {
  return (
    <div className="app">
      <h1>My Application</h1>
      <p>Press Cmd/Ctrl+B to toggle the sidebar!</p>

      {/* The sidebar will automatically initialize */}
    </div>
  );
}

Custom Configuration

import { SidebarSDK } from '@dananai/sidebar-sdk';
import '@dananai/sidebar-sdk/dist/sidebar-sdk.css';

function App() {
  useEffect(() => {
    const sdk = new SidebarSDK({
      project_id: 'my-project',
      user_id: 'user-123',
      debug: true,
      width: '35vw',
      defaultOpen: true,
      keyboardShortcut: 's'
    });

    sdk.init();

    // Expose SDK to window for debugging
    window.mySDK = sdk;
  }, []);

  return (
    <div className="app">
      <h1>My Application</h1>
      <button onClick={() => window.mySDK?.toggle()}>
        Toggle Sidebar
      </button>
    </div>
  );
}

Script Tag with Dynamic Configuration

<!DOCTYPE html>
<html>
<head>
  <title>Dynamic Sidebar Demo</title>
  <link rel="stylesheet" href="https://unpkg.com/@dananai/[email protected]/dist/sidebar-sdk.css">
</head>
<body>
  <div id="app">
    <h1>Dynamic Sidebar Demo</h1>
    <button onclick="toggleSidebar()">Toggle Sidebar</button>
    <button onclick="updateConfig()">Update Config</button>
  </div>

  <script src="https://unpkg.com/@dananai/[email protected]/dist/index.js"></script>
  <script>
    // Wait for SDK to load
    document.addEventListener('DOMContentLoaded', () => {
      // Access the global SDK instance
      const sdk = window.SidebarSdk;

      // Update configuration
      sdk.updateConfig({
        project_id: 'dynamic-project',
        user_id: 'dynamic-user',
        debug: true,
        width: '45vw'
      });
    });

    function toggleSidebar() {
      if (window.sidebarToggle) {
        window.sidebarToggle();
      }
    }

    function updateConfig() {
      const sdk = window.SidebarSdk;
      sdk.updateConfig({
        width: '50vw',
        debug: false
      });
    }
  </script>
</body>
</html>

Browser Support

Chrome 88+
Firefox 85+
Safari 14+
Edge 88+

Development

Building from Source

# Clone the repository
git clone https://github.com/dananai/sidebar-sdk.git
cd sidebar-sdk

# Install dependencies
pnpm install

# Build the library
pnpm run build

# Start development server
pnpm run dev

Available Scripts

pnpm run dev - Start development server
pnpm run build - Build the library for production
pnpm run build:watch - Build in watch mode
pnpm run lint - Run ESLint
pnpm run clean - Clean build artifacts

Troubleshooting

Common Issues

Sidebar not appearing: Check that React and ReactDOM are loaded before the SDK
CSS conflicts: Use the CSS reset provided above
Keyboard shortcuts not working: Ensure the page has focus and no other elements are capturing the events
Script parameters not detected: Make sure the script tag has the correct data-* attributes

Debug Mode

Enable debug mode to see detailed logs:

const sdk = new SidebarSDK({
  debug: true,
  // ... other config
});

Or via script tag:

<script
  src="https://unpkg.com/@dananai/[email protected]/dist/index.js"
  data-debug="true">
</script>

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki

Changelog

v1.0.4

Fixed dependency bundling issues
Improved CSS isolation
Enhanced script parameter detection
Added comprehensive API documentation

v1.0.3

Bundled all dependencies for easier installation
Fixed package entry point configuration
Improved build process

v1.0.2

Fixed package.json exports configuration
Corrected entry point paths

v1.0.1

Initial release with UMD and ESM support
Auto-initialization capability
Keyboard shortcuts
Script tag parameter support