@kala-ui/react

Comprehensive React UI component library built with Radix UI and Tailwind CSS. This package provides 65+ production-ready, accessible components for building modern web applications.

Overview

This package contains:

• 65+ React Components: Buttons, inputs, dialogs, dropdowns, data tables, charts, and more
• Radix UI Primitives: Accessible, unstyled component primitives
• Tailwind CSS Styling: Utility-first CSS framework with design tokens
• TypeScript: Fully typed components with strict mode
• Storybook: Interactive component documentation and visual testing
• Testing: Comprehensive test coverage with Vitest and Testing Library

Installation & Usage

NPM Installation

Install the package from npm:

npm install @kala-ui/react

Or using pnpm:

pnpm add @kala-ui/react

Or using yarn:

yarn add @kala-ui/react

Then import components:

import { Button } from '@kala-ui/react/button';
import { Input } from '@kala-ui/react/input';
import { Dialog } from '@kala-ui/react/dialog';

function MyComponent() {
  return (
    <Dialog>
      <Input placeholder="Enter text" />
      <Button>Submit</Button>
    </Dialog>
  );
}

Available Components

Form Controls

• button, input, textarea, checkbox, switch, select, radio-group, label, field

Import from:

import { Button } from '@kala-ui/react/button';
import { Input } from '@kala-ui/react/input';
import { Field } from '@kala-ui/react/field';

Layout

• header, footer, navigation, sidebar, card, separator, tabs, accordion

Import from:

import { Header } from '@kala-ui/react/header';
import { Card } from '@kala-ui/react/card';
import { Tabs } from '@kala-ui/react/tabs';

Feedback

• alert, alert-dialog, dialog, tooltip, popover, banner, spinner, skeleton

Import from:

import { Alert } from '@kala-ui/react/alert';
import { Dialog } from '@kala-ui/react/dialog';
import { Spinner } from '@kala-ui/react/spinner';

Data Display

• avatar, badge, table, data-table, breadcrumbs, charts, metric-card

Import from:

import { Avatar } from '@kala-ui/react/avatar';
import { Badge } from '@kala-ui/react/badge';
import { Table } from '@kala-ui/react/table';
import { DataTable } from '@kala-ui/react/data-table';
import { AreaChart, LineChart, BarChart } from '@kala-ui/react/charts';

Notifications

• toast - Toast notification system with full Sonner API support

Import from:

import { toast, Toast } from '@kala-ui/react/toast';

// Use the API
toast.success('Success message');
toast.error('Error message');
toast.dismiss(toastId);

// Use the component
<Toast />

// Promise-based toasts
toast.promise(promise, {
  loading: 'Loading...',
  success: 'Success!',
  error: 'Error',
});

Advanced

• dropdown-menu, user-menu-dropdown, social-login-button, password-strength-indicator, session-card

Import from:

import { DropdownMenu } from '@kala-ui/react/dropdown-menu';
import { SocialLoginButton } from '@kala-ui/react/social-login-button';

Utilities

Import utilities:

import { cn } from '@kala-ui/react/lib/utils';

Styles

Import global styles in JavaScript/TypeScript files:

import '@kala-ui/react/styles';

Or import in CSS files:

@import '@kala-ui/react/styles';

Key Components

DataTable - Advanced data table with server-side support

• Sorting, filtering, searching, pagination
• Row selection and bulk actions
• Server-side callbacks for large datasets (10,000+ records)
• See data-table README for details

Charts - Data visualization components

• Area, Bar, Line, Donut, Pie, Radial Bar charts
• Built with ApexCharts
• Dark mode support

DND - Drag and drop components

• Sortable lists and grids with animations
• Built with @dnd-kit/core

See the Storybook documentation for complete component catalog.

Development

Running Storybook

Start the development server to view and test components interactively:

# From workspace root
pnpm --filter @repo/ui storybook

# Or from packages/ui
pnpm storybook

This starts Storybook at http://localhost:6006

Building Storybook

Build a static version for deployment:

pnpm --filter @repo/ui build-storybook

Output is in storybook-static/ directory.

Scripts

| Script | Description | |--------|-------------| | pnpm storybook | Run Storybook dev server on port 6006 | | pnpm build-storybook | Build static Storybook for production | | pnpm test | Run all component tests once | | pnpm test:watch | Run tests in watch mode | | pnpm test:coverage | Generate test coverage report | | pnpm type-check | Run TypeScript type checking | | pnpm lint | Run Biome linter | | pnpm build | type-check only (no build output) |

CI/CD Integration

Storybook is built and validated in the CI pipeline:

• Workflow: .github/workflows/ci.yml (storybook job)
• Triggers: Pull requests and pushes to main branch
• Build Time: ~2-4 minutes with cache
• Artifacts: Static build available for 7 days

The Storybook build must pass for PRs to be merged. This ensures component stories don't break.

Testing Before Push

Before pushing changes, verify locally:

# Run same checks as CI
pnpm type-check
pnpm lint
pnpm test
pnpm build-storybook

Or use the full validation command:

pnpm validate:all

Adding New Components

1. Create component directory:

   packages/ui/src/components/my-component/
   ├── index.ts              # Public exports
   ├── my-component.tsx      # Component implementation
   ├── my-component.test.tsx # Tests
   └── my-component.stories.tsx # Storybook story

2. Implement component with:

   • TypeScript for type safety
   • React 19 features (use client/server as needed)
   • Tailwind CSS classes for styling
   • Radix UI primitives where applicable
   • cn() utility for class merging

3. Write tests:

   • Use Vitest + Testing Library
   • Test rendering, interactions, accessibility
   • Aim for >80% coverage

4. Create Storybook story:

   • Document all component variants
   • Add interactive controls for props
   • Include usage examples
   • See docs/STORYBOOK.md for guidelines

5. Add package export in package.json:

   {
     "exports": {
       "./my-component": {
         "types": "./src/components/my-component/index.ts",
         "default": "./src/components/my-component/index.ts"
       }
     }
   }

6. Run validation:

   pnpm type-check  # Check types
   pnpm lint        # Check code style
   pnpm test        # Run tests
   pnpm storybook   # Verify story appears

Package Structure

packages/ui/
├── .storybook/          # Storybook configuration
│   ├── main.ts          # Addons, builders, features
│   └── preview.tsx      # Global decorators, parameters
├── src/
│   ├── components/      # All React components
│   │   └── [component]/
│   │       ├── index.ts              # Exports
│   │       ├── [component].tsx       # Implementation
│   │       ├── [component].test.tsx  # Tests
│   │       └── [component].stories.tsx # Story
│   ├── hooks/           # Shared React hooks
│   ├── lib/             # Utility functions
│   └── styles/          # Global styles, Tailwind CSS
├── package.json         # Exports, scripts, dependencies
├── tsconfig.json        # TypeScript config
├── tailwind.config.ts   # Tailwind CSS config
└── vitest.config.ts     # Vitest config

Technologies

• React 19: UI framework
• Radix UI: Accessible component primitives
• Tailwind CSS: Utility-first CSS framework
• TypeScript: Type safety with strict mode
• Storybook 8: Component development and documentation
• Vitest: Fast unit testing
• Testing Library: React component testing

Documentation

📚 Live Storybook Documentation - Interactive component examples and usage guides

• Main Storybook Guide: docs/STORYBOOK.md
• Architecture: docs/ARCHITECTURE.md
• Testing: docs/TESTING.md
• Development Workflow: docs/DEVELOPMENT.md

Related Packages

• @kala-ui/design-tokens - Design system tokens

Credits

This component library is built using excellent open-source libraries. We'd like to thank the following projects:

Core Dependencies

• Tailwind CSS - Utility-first CSS framework for rapid UI development
• Radix UI - Unstyled, accessible UI primitives for building high-quality design systems
• shadcn/ui - Beautifully designed components built with Radix UI and Tailwind CSS

Component Libraries

• Vaul - Drawer component with accessible primitives
• Sonner - Opinionated toast component for React
• cmdk - Fast, composable command menu component for React

Data Visualization

• ApexCharts - Modern and interactive JavaScript charts

Drag & Drop

• @dnd-kit/core - Modern, lightweight drag and drop library for React

For detailed component usage, props, and examples, see the Storybook documentation or run pnpm storybook.