weloop-kosign-ui

v1.0.4

Published

3 months ago

WeLoop Kosign UI component library with Radix UI and Recharts

0High
0Medium
0Low

kosign_cambodia

react typescript ui components radix-ui recharts design-system accessible weloop kosign

WeLoop Kosign UI

A beautiful and accessible UI component library built with React, TypeScript, and SCSS.

🚀 Quick Start

1. Install

# React 18
npm install weloop-kosign-ui@^1.0.4 react@^18 react-dom@^18
# (Only if you use forms)
npm install react-hook-form@^7 @hookform/resolvers@^3

# React 19
npm install weloop-kosign-ui@^1.0.4 react@^19 react-dom@^19
# (Only if you use forms)
npm install react-hook-form@^8 @hookform/resolvers@^4

2. Import Styles

Add this to your main CSS file (e.g., src/index.css or src/App.css):

@import "weloop-kosign-ui/styles";

3. Import Components

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "weloop-kosign-ui";

4. Use Components

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "weloop-kosign-ui";

function App() {
  return (
    <div className="wl-container">
      <Card>
        <CardHeader>
          <CardTitle>Welcome to WeLoop Kosign UI</CardTitle>
        </CardHeader>
        <CardContent>
          <Button>Click me</Button>
        </CardContent>
      </Card>
    </div>
  );
}

⚠️ Notes on React 19

The core library builds and installs on React 19.
Some form-related components rely on react-hook-form. It is not a peer; install it only if you use forms.
Install react-hook-form and @hookform/resolvers with versions compatible to your React version (see commands above).

🎯 Features

⚛️ React 18–19 - Tested install on React 18 and 19
🎨 Beautiful Design - Modern, accessible components
🌙 Dark Mode - Built-in dark mode support
📱 Responsive - Mobile-first design approach
♿ Accessible - WCAG compliant components
🎯 TypeScript - Full type safety
🎨 Customizable - Easy theming with CSS variables
📦 Zero Setup - No additional dependencies required
🚀 Optimized - Tree-shaking friendly with clean exports
🎨 SCSS-based Styling - Consistent design with SCSS classes
🔧 Pure SCSS - No external styling dependencies
📊 Chart Components - Built-in Recharts integration
🎯 Form Handling - React Hook Form integration
🎨 Icon Support - Lucide React icons included
🆕 v1.0.4 - Patch release with bug fixes and improvements

🆕 What's New in v1.0.4

Patch Release

Bug fixes and stability improvements
Enhanced component reliability
Updated dependencies and build optimizations

Previous Release: v1.0.3

Build & Package Improvements (v1.0.3)

Optimized npm package structure with proper file exports
Enhanced build process with tsup v8.5.0
Improved TypeScript definitions and source maps
Better tree-shaking support for smaller bundle sizes
Streamlined styles compilation and distribution

Package Structure

Clean dist folder with only necessary files
Proper ESM exports configuration
Separate styles export (weloop-kosign-ui/styles)
Complete TypeScript definitions included

🧩 Available Components

Layout & Structure

Accordion - Collapsible content sections
AppBar - Application header with navigation
AspectRatio - Maintain aspect ratio for content
Badge - Status indicators and labels
Banner - Prominent notification banners
Breadcrumb - Navigation breadcrumbs
Button - Interactive buttons with variants
ButtonGroup - Grouped button components
Card - Container components
Chip - Compact information chips
ChipGroup - Grouped chip components
Collapsible - Collapsible content areas
EmptyState - Empty state placeholders
Separator - Visual dividers
Sheet - Slide-out panels
Skeleton - Loading placeholders

Navigation

Menubar - Horizontal menu bars
NavigationMenu - Main navigation
Pagination - Page navigation
Sidebar - Side navigation with advanced features including SidebarHeaderText for section headers
TabBar - Tabbed interfaces with enhanced controls
TabPanel - Tab panel components

Forms & Inputs

Checkbox - Checkbox inputs with group support
Command - Command palette
Form - Form handling with validation
Input - Text inputs with variants
InputOTP - One-time password inputs
Label - Form labels
Radio - Radio button component
Select - Dropdown selects
Slider - Range sliders
Switch - Toggle switches
TagInput - Tag input component
Textarea - Multi-line text inputs
Toggle - Toggle buttons
ToggleGroup - Grouped toggle buttons
Segment - Segmented control component

Overlays & Modals

AlertDialog - Confirmation dialogs
ContextMenu - Right-click menus
Dialog - Modal dialogs
Drawer - Slide-out panels
DropdownMenu - Dropdown menus
HoverCard - Hover-triggered cards
Popover - Floating content with positioning
Tooltip - Information tooltips

Data Display

Alert - Status messages
Avatar - User avatars
Calendar - Date picker with range support
Carousel - Image carousels
Chart - Data visualization container
AreaChart - Area chart visualization
BarChart - Bar chart visualization
LineChart - Line chart visualization
PieChart - Pie chart visualization
RadarChart - Radar chart visualization
RadialChart - Radial bar chart visualization
FileUpload - File upload component
Progress - Progress indicators
ResizablePanel - Resizable panel groups
ScrollArea - Custom scrollbars
Table - Data tables

Utilities

useToast - Toast notifications
Toaster - Toast container
Snackbar - Custom snackbar container
useSnackbar - Snackbar management hook
useMobile - Mobile detection hook
useCheckboxGroup - Checkbox group management hook

Banners & Notifications

Banner - Single and multi-line banners
BannerProvider - Banner context provider
useBanner - Banner management hook

🎨 Styling Approach

SCSS-based Styling System

WeLoop ShadCN UI uses a pure SCSS styling approach:

SCSS-based Components: All components are styled with SCSS for consistent design
Pre-built Classes: Components come with ready-to-use SCSS classes
No External Dependencies: Pure SCSS without Tailwind or other styling frameworks

Using SCSS Classes

Components come with pre-built SCSS classes that you can use directly:

<Button className="wl-button wl-button-primary">Click me</Button>
<Card className="wl-card wl-card-elevated">Content</Card>

Responsive Design

All components include responsive SCSS classes:

<Button className="wl-button wl-button-responsive">Responsive Button</Button>

📱 Responsive Design

All components are built with a mobile-first approach and include responsive SCSS classes:

<Button className="wl-button wl-button-responsive">Responsive Button</Button>

♿ Accessibility

Components follow WCAG guidelines and include:

Proper ARIA attributes
Keyboard navigation support
Screen reader compatibility
Focus management
Color contrast compliance

🔧 Development

Building the Library

npm run build

This command builds both the TypeScript/JavaScript code and SCSS styles together.

For individual builds:

npm run build:js    # Build only JavaScript/TypeScript
npm run build:styles # Build only SCSS styles

Verifying the Package

Before publishing, verify the package contents:

npm pack --dry-run

This will show you exactly what files will be included in the npm package. The package includes:

dist/index.js - Main library bundle (ESM)
dist/index.d.ts - TypeScript definitions
dist/index.js.map - Source maps for debugging
dist/styles.css - Compiled styles
package.json - Package metadata
README.md - Documentation
LICENSE - License file

Publishing to npm

npm publish

The prepublishOnly script will automatically run the build before publishing.

Running the Demo

npm run dev

The demo will be available at http://localhost:5173/

Building the Demo

npm run preview

📦 Package Structure

weloop-kosign-ui/
├── dist/                  # Built library files
│   ├── index.js          # Main library bundle
│   ├── index.d.ts        # TypeScript definitions
│   └── styles.css        # Compiled styles
├── src/
│   ├── components/ui/    # UI components
│   ├── hooks/           # Custom hooks
│   └── lib/             # Utilities and variants
└── demo/                 # Demo application (not included in package)

📚 Resources

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

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

Built with ❤️ by the WeLoop Team