A modern, beautifully crafted UI component library for building conversational interfaces and support chat experiences. Built with Lit Element and TypeScript, featuring a shadcn-inspired design system with full dark mode support. 🚀

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

🎯 Features

Complete Chat UI — Ready-to-use conversation components with message threads, typing indicators, and file attachments
Floating Action Button — Eye-catching FAB with smooth gradient animations and glow effects
PDF Viewer — Built-in PDF rendering with zoom, pagination, and download capabilities
Image Lightbox — Full-featured lightbox with zoom, pan, and keyboard navigation
Design Token System — Comprehensive tokens for colors, spacing, typography, shadows, and animations
Dark Mode Ready — Full light/dark theme support out of the box via bdTheme() helper
Accessibility — Keyboard navigation and proper ARIA attributes throughout
TypeScript First — Full type definitions and IntelliSense for all components
Lazy-loaded Libraries — rrweb for session recording is loaded on-demand from CDN via SioServiceLibLoader

📦 Installation

pnpm add @social.io/catalog

🚀 Quick Start

import { SioFab, SioCombox } from '@social.io/catalog';

// Components auto-register as custom elements — just drop them into your HTML:

<!-- Floating Action Button that opens the chat -->
<sio-fab></sio-fab>

<!-- Or use the full chat box directly -->
<sio-combox></sio-combox>

🧩 Components

Core Components

Component	Tag	Description
`SioFab`	`<sio-fab>`	Floating action button with animated gradient, glow effects, and pulse animation
`SioCombox`	`<sio-combox>`	Complete chat interface combining conversation list, message view, and input
`SioButton`	`<sio-button>`	Styled button with variants: `primary`, `secondary`, `destructive`, `outline`, `ghost`
`SioIcon`	`<sio-icon>`	Lucide icon wrapper with size, color, and strokeWidth customization
`SioDropdownMenu`	`<sio-dropdown-menu>`	Animated dropdown menu with keyboard support and auto-positioning

Conversation Components

Component	Tag	Description
`SioConversationSelector`	`<sio-conversation-selector>`	Searchable list of conversations with unread indicators and status badges
`SioConversationView`	`<sio-conversation-view>`	Message thread with typing indicators, timestamps, and file attachment support
`SioMessageInput`	`<sio-message-input>`	Auto-expanding textarea with file upload capabilities

Media Components

Component	Tag	Description
`SioImageLightbox`	`<sio-image-lightbox>`	Fullscreen image viewer with zoom, pan, and keyboard navigation; also handles PDF files
`SioPdfViewer`	`<sio-pdf-viewer>`	PDF renderer with page navigation, zoom controls, and download button

Utility Components

Component	Tag	Description
`SioRecorder`	`<sio-recorder>`	Session recording and playback using rrweb, lazy-loaded from CDN

Services

Export	Description
`SioServiceLibLoader`	CDN-based lazy loader for rrweb and rrweb-player libraries

💅 Design System

The library ships a comprehensive, shadcn/ui-inspired design token system. All tokens are exported so you can use them in your own components.

Colors

import { colors, bdTheme } from '@social.io/catalog/elements/00colors.js';

Includes primary, secondary, accent, destructive, muted, success, background, foreground, card, popover, border, input, ring, and 5 chart colors — each with light and dark variants.

Spacing, Radius, Shadows & More

import { spacing, radius, shadows, transitions, sizes, zIndex, breakpoints } from '@social.io/catalog/elements/00tokens.js';

Spacing — Tailwind-compatible scale from 0 to 96 (0–384px)
Radius — From sm (2px) through full (9999px)
Shadows — Elevation system from sm to 2xl, plus theme-aware card and dropdown shadows
Transitions — Presets (all, colors, opacity, shadow, transform) with timing functions
Z-index — Semantic layers: dropdown, sticky, fixed, modal, popover, tooltip
Breakpoints — sm (640px) through 2xl (1536px)

Dark Mode

Dark mode is automatically supported. Use the bdTheme() helper for theme-aware values:

import { bdTheme } from '@social.io/catalog/elements/00colors.js';

// Returns the correct value based on the current theme
css`
  background: ${bdTheme('hsl(0 0% 100%)', 'hsl(0 0% 10%)')};
`

📖 Usage Examples

💬 Chat FAB

<sio-fab></sio-fab>

The FAB positions itself at the bottom-right corner and opens a complete chat interface when clicked. It features:

Animated gradient background (indigo → violet → purple)
Glow effect on hover
Smooth scale and pulse animations

🔘 Buttons

<sio-button>Default</sio-button>
<sio-button type="primary">Submit</sio-button>
<sio-button type="destructive">Delete</sio-button>
<sio-button type="outline">Cancel</sio-button>
<sio-button type="ghost" size="sm">
  <sio-icon icon="settings"></sio-icon>
</sio-button>
<sio-button size="lg">Large</sio-button>
<sio-button disabled>Disabled</sio-button>

Sizes: sm, default, lg. Status: normal, pending, success, error.

const lightbox = document.querySelector('sio-image-lightbox');

// Open with an image
await lightbox.open({
  url: 'https://example.com/photo.jpg',
  name: 'My Photo',
  size: 1024000
});

// Or open with a PDF
await lightbox.open({
  url: 'https://example.com/document.pdf',
  name: 'report.pdf',
  type: 'application/pdf',
  size: 565000
});

📄 PDF Viewer

<sio-pdf-viewer
  url="https://example.com/document.pdf"
  fileName="document.pdf"
></sio-pdf-viewer>

<sio-dropdown-menu
  .items=${[
    { id: 'edit', label: 'Edit', icon: 'pencil' },
    { id: 'divider', label: '', divider: true },
    { id: 'delete', label: 'Delete', icon: 'trash', destructive: true }
  ]}
  @item-selected=${(e) => console.log('Selected:', e.detail.item)}
>
  <sio-button type="ghost">
    <sio-icon icon="more-vertical"></sio-icon>
  </sio-button>
</sio-dropdown-menu>

🎨 Icons

Uses the full Lucide icon set. Pass kebab-case icon names:

<sio-icon icon="search"></sio-icon>
<sio-icon icon="message-square" color="#3b82f6"></sio-icon>
<sio-icon icon="x" size="32"></sio-icon>
<sio-icon icon="send" .strokeWidth=${3}></sio-icon>

🔧 Development

# Install dependencies
pnpm install

# Start development server with hot reload
pnpm watch

# Build for production
pnpm build

# Run tests (Chromium browser tests)
pnpm test

📚 Dependencies

Package	Purpose
`@design.estate/dees-element`	Lit Element base class with theming utilities
`@design.estate/dees-domtools`	DOM manipulation and convenience helpers
`@design.estate/dees-wcctools`	Web component catalog tools
`lucide`	Beautiful, consistent open-source icon set
`rrweb`	Session recording/replay (lazy-loaded from CDN)

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md Unescape Escape

@social.io/catalog