@codeswayam/ui 1.0.0 → 1.1.0

package/README.md

@@ -1,597 +1,323 @@
-# @codeswayam/ui - UI Component Library
-
-## Overview
-
-**@codeswayam/ui** is a comprehensive UI component library built on **Radix UI** and **Tailwind CSS**. It provides reusable, accessible, and well-documented React components used across all CodeSwayam applications. The library ensures consistent design and user experience across the platform.
-
----
-
-## 🎯 Features
-
-- **Accessible Components**: Built with Radix UI for accessibility
-- **Tailwind CSS**: Utility-first styling
-- **Type-Safe**: Full TypeScript support
-- **Themeable**: Customizable colors and styles
-- **Responsive**: Mobile-first design
-- **Dark Mode**: Built-in dark mode support
-- **60+ Components**: Comprehensive component library
-- **Well-Documented**: Storybook documentation
-- **Composable**: Easy to extend and customize
-- **Zero Dependencies**: Uses peer dependencies only
-
----
-
-## 📦 Installation
-
-```bash
-npm install @codeswayam/ui
-```
-
----
-
-## 🔧 Setup
-
-### 1. Install Peer Dependencies
-
-```bash
-npm install react react-dom next tailwindcss
-```
-
-### 2. Configure Tailwind
-
-Add to `tailwind.config.ts`:
-
-```typescript
-import type { Config } from 'tailwindcss'
-
-const config: Config = {
-  content: [
-    './node_modules/@codeswayam/ui/**/*.{js,ts,jsx,tsx}',
-    './app/**/*.{js,ts,jsx,tsx}',
-    './components/**/*.{js,ts,jsx,tsx}'
-  ],
-  theme: {
-    extend: {}
-  },
-  plugins: []
-}
-
-export default config
-```
-
-### 3. Import Styles
-
-```typescript
-// app/globals.css or your global CSS file
-@import '@codeswayam/ui/globals.css'
-```
-
----
-
-## 🚀 Basic Usage
-
-### Import Components
-
-```tsx
-import {
-  Button,
-  Card,
-  Input,
-  Label,
-  Select,
-  Dialog,
-  Tabs,
-  Toast
-} from '@codeswayam/ui'
-```
-
-### Using Components
-
-```tsx
-import { Button } from '@codeswayam/ui'
-
-export function App() {
-  return <Button variant="primary">Click me</Button>
-}
-```
-
----
-
-## 📚 Component Library
-
-### Layout Components
-
-#### Container
-Responsive container with max width
-
-```tsx
-import { Container } from '@codeswayam/ui'
-
-<Container>
-  <h1>Your content</h1>
-</Container>
-```
-
-#### Grid
-Responsive grid layout
-
-```tsx
-import { Grid, GridItem } from '@codeswayam/ui'
-
-<Grid columns={3} gap={4}>
-  <GridItem>Item 1</GridItem>
-  <GridItem>Item 2</GridItem>
-  <GridItem>Item 3</GridItem>
-</Grid>
-```
-
-### Form Components
-
-#### Button
-Versatile button component
-
-```tsx
-import { Button } from '@codeswayam/ui'
-
-// Variants
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="outline">Outline</Button>
-<Button variant="ghost">Ghost</Button>
-
-// Sizes
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
-
-// States
-<Button disabled>Disabled</Button>
-<Button isLoading>Loading...</Button>
-```
-
-#### Input
-Text input field
-
-```tsx
-import { Input } from '@codeswayam/ui'
-
-<Input
-  type=\"email\"
-  placeholder=\"Enter email\"
-  onChange={(e) => setValue(e.target.value)}
-/>
-```
-
-#### Label
-Form label component
-
-```tsx
-import { Label } from '@codeswayam/ui'
-
-<Label htmlFor=\"email\">Email Address</Label>
-<Input id=\"email\" />
-```
-
-#### Select
-Dropdown select component
-
-```tsx
-import { Select, SelectContent, SelectItem, SelectTrigger } from '@codeswayam/ui'
-
-<Select defaultValue=\"option1\">
-  <SelectTrigger>
-    <span>Choose option</span>
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value=\"option1\">Option 1</SelectItem>
-    <SelectItem value=\"option2\">Option 2</SelectItem>
-    <SelectItem value=\"option3\">Option 3</SelectItem>
-  </SelectContent>
-</Select>
-```
-
-#### Textarea
-Multi-line text input
-
-```tsx
-import { Textarea } from '@codeswayam/ui'
-
-<Textarea
-  placeholder=\"Enter message\"
-  rows={5}
-  onChange={(e) => setValue(e.target.value)}
-/>
-```
-
-#### Checkbox
-Checkbox input
-
-```tsx
-import { Checkbox } from '@codeswayam/ui'
-
-<Checkbox
-  id=\"terms\"
-  onCheckedChange={setTermsAccepted}
-/>
-<Label htmlFor=\"terms\">I agree to terms</Label>
-```
-
-#### Radio Group
-Radio button group
-
-```tsx
-import { Radio, RadioGroup } from '@codeswayam/ui'
-
-<RadioGroup defaultValue=\"option1\">
-  <div className=\"flex items-center\">
-    <Radio value=\"option1\" id=\"option1\" />
-    <Label htmlFor=\"option1\">Option 1</Label>
-  </div>
-  <div className=\"flex items-center\">
-    <Radio value=\"option2\" id=\"option2\" />
-    <Label htmlFor=\"option2\">Option 2</Label>
-  </div>
-</RadioGroup>
-```
-
-#### Switch
-Toggle switch
-
-```tsx
-import { Switch } from '@codeswayam/ui'
-
-<Switch
-  checked={enabled}
-  onCheckedChange={setEnabled}
-/>
-```
-
-### Data Display Components
-
-#### Card
-Container component for content
-
-```tsx
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@codeswayam/ui'
-
-<Card>
-  <CardHeader>
-    <CardTitle>Card Title</CardTitle>
-    <CardDescription>Description</CardDescription>
-  </CardHeader>
-  <CardContent>
-    Card content here
-  </CardContent>
-</Card>
-```
-
-#### Badge
-Status/tag badge
-
-```tsx
-import { Badge } from '@codeswayam/ui'
-
-<Badge variant=\"default\">New</Badge>
-<Badge variant=\"success\">Active</Badge>
-<Badge variant=\"warning\">Pending</Badge>
-<Badge variant=\"destructive\">Error</Badge>
-```
-
-#### Table
-Data table component
-
-```tsx
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow
-} from '@codeswayam/ui'
-
-<Table>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Email</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>John</TableCell>
-      <TableCell>john@example.com</TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-```
-
-### Overlay Components
-
-#### Dialog
-Modal dialog
-
-```tsx
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-  DialogTrigger
-} from '@codeswayam/ui'
-
-<Dialog>
-  <DialogTrigger>Open Dialog</DialogTrigger>
-  <DialogContent>
-    <DialogHeader>
-      <DialogTitle>Dialog Title</DialogTitle>
-      <DialogDescription>Description</DialogDescription>
-    </DialogHeader>
-    Dialog content
-  </DialogContent>
-</Dialog>
-```
-
-#### Alert Dialog
-Confirmation dialog
-
-```tsx
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogHeader,
-  AlertDialogTitle,
-  AlertDialogTrigger
-} from '@codeswayam/ui'
-
-<AlertDialog>
-  <AlertDialogTrigger>Delete</AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
-      <AlertDialogDescription>
-        This action cannot be undone
-      </AlertDialogDescription>
-    </AlertDialogHeader>
-    <AlertDialogCancel>Cancel</AlertDialogCancel>
-    <AlertDialogAction>Delete</AlertDialogAction>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-#### Popover
-Floating content popover
-
-```tsx
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger
-} from '@codeswayam/ui'
-
-<Popover>
-  <PopoverTrigger>Open</PopoverTrigger>
-  <PopoverContent>
-    Popover content
-  </PopoverContent>
-</Popover>
-```
-
-#### Dropdown Menu
-Dropdown menu
-
-```tsx
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger
-} from '@codeswayam/ui'
-
-<DropdownMenu>
-  <DropdownMenuTrigger>Menu</DropdownMenuTrigger>
-  <DropdownMenuContent>
-    <DropdownMenuItem>Profile</DropdownMenuItem>
-    <DropdownMenuSeparator />
-    <DropdownMenuItem>Logout</DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
-```
-
-### Navigation Components
-
-#### Tabs
-Tabbed interface
-
-```tsx
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@codeswayam/ui'
-
-<Tabs defaultValue=\"tab1\">
-  <TabsList>
-    <TabsTrigger value=\"tab1\">Tab 1</TabsTrigger>
-    <TabsTrigger value=\"tab2\">Tab 2</TabsTrigger>
-  </TabsList>
-  <TabsContent value=\"tab1\">Content 1</TabsContent>
-  <TabsContent value=\"tab2\">Content 2</TabsContent>
-</Tabs>
-```
-
-### Feedback Components
-
-#### Toast
-Toast notification
-
-```tsx
-import { useToast } from '@codeswayam/ui/hooks'
-
-const { toast } = useToast()
-
-toast({
-  title: 'Success',
-  description: 'Operation completed',
-  variant: 'default'
-})
-```
-
-#### Progress
-Progress bar
-
-```tsx
-import { Progress } from '@codeswayam/ui'
-
-<Progress value={65} />
-```
-
-#### Skeleton
-Loading skeleton
-
-```tsx
-import { Skeleton } from '@codeswayam/ui'
-
-<Skeleton className=\"h-12 w-12 rounded-full\" />
-```
-
----
-
-## 🎨 Styling & Customization
-
-### Tailwind CSS Classes
-
-```tsx
-<Button className=\"custom-class\">
-  Custom Button
-</Button>
-```
-
-### Theme Customization
-
-```tsx
-// Extend tailwind config
-const config: Config = {
-  theme: {
-    extend: {
-      colors: {
-        brand: '#your-color'
-      }
-    }
-  }
-}
-```
-
-### Dark Mode
-
-Components automatically support dark mode:
-
-```tsx
-// Enable dark mode in HTML
-<html className=\"dark\">
-  <body>...</body>
-</html>
-```
-
----
-
-## 🔗 Component Props
-
-### Common Props
-
-Most components accept:
-- `className` - Tailwind CSS classes
-- `disabled` - Disable component
-- `aria-*` - Accessibility attributes
-
----
-
-## 🧪 Testing
-
-```tsx
-import { render, screen } from '@testing-library/react'
-import { Button } from '@codeswayam/ui'
-
-test('button renders', () => {
-  render(<Button>Click me</Button>)
-  expect(screen.getByRole('button')).toBeInTheDocument()
-})
-```
-
----
-
-## 📖 Storybook
-
-View all components in Storybook:
-
-```bash
-npm run storybook
-```
-
----
-
-## ♿ Accessibility
-
-All components are built with accessibility in mind:
-- Keyboard navigation
-- Screen reader support
-- ARIA labels
-- Focus management
-- Color contrast
-
----
-
-## 📋 Component Checklist
-
-Essential components:
-- [x] Button
-- [x] Input
-- [x] Card
-- [x] Dialog
-- [x] Select
-- [x] Tabs
-- [x] Badge
-- [x] Table
-- [x] Toast
-- [x] Checkbox
-- [x] Radio
-- [x] Switch
-- [x] Textarea
-- [x] Progress
-- [x] Skeleton
-- [x] Dropdown Menu
-- [x] Popover
-- [x] Alert Dialog
-
----
-
-## 🤝 Contributing
-
-### Adding New Components
-
-1. Create component in `src/components/`
-2. Export from `src/index.ts`
-3. Add Storybook story
-4. Document usage
-5. Test accessibility
-
----
-
-## 📄 License
-
-ISC License
-
----
-
-## 🔗 Related Packages
-
-- [@codeswayam/api-client](../api-client/README.md) - API client
-- [@codeswayam/auth](../auth-client/README.md) - Auth utilities
-- [@shared/database](../database/README.md) - Database utilities
-
----
-
-**Last Updated**: April 2026
-
-For more information, see the main [README.md](../../README.md)
+# @codeswayam/ui
+
+**Version:** 1.1.0
+
+Shared React UI component library for all CodeSwayam SaaS applications. Built on Radix UI primitives with Tailwind CSS. Includes base components, SaaS-specific components, layout components, and design tokens.
+
+---
+
+## Installation
+
+```bash
+npm install @codeswayam/ui
+```
+
+**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `next >= 13`
+
+---
+
+## Setup
+
+Include the package source in your app's Tailwind config so styles are picked up:
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@codeswayam/ui/dist/**/*.{js,mjs}",
+  ],
+};
+```
+
+Import the global CSS tokens in your root layout:
+
+```tsx
+// app/layout.tsx
+import "@codeswayam/ui/dist/globals.css"; // design tokens + base styles
+```
+
+---
+
+## Utility
+
+### `cn(...inputs)`
+
+Merges Tailwind classes with conflict resolution via `clsx` + `tailwind-merge`.
+
+```typescript
+import { cn } from "@codeswayam/ui";
+
+cn("px-4 py-2", isActive && "bg-primary", "px-6");
+// → "py-2 bg-primary px-6"
+```
+
+---
+
+## Base Components
+
+### `<Button>`
+
+Built with `class-variance-authority` and Radix `Slot` for polymorphic rendering.
+
+```tsx
+import { Button } from "@codeswayam/ui";
+
+<Button variant="default" size="default">Click me</Button>
+<Button variant="outline" size="sm">Cancel</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="ghost" size="icon"><TrashIcon /></Button>
+
+// Render as a link using asChild
+<Button asChild variant="default">
+  <a href="/dashboard">Go to Dashboard</a>
+</Button>
+```
+
+**Variants:** `default`, `destructive`, `outline`, `secondary`, `ghost`, `link`
+**Sizes:** `default`, `sm`, `lg`, `icon`
+
+---
+
+### `<Card>` family
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@codeswayam/ui";
+
+<Card>
+  <CardHeader>
+    <CardTitle>Plan Overview</CardTitle>
+    <CardDescription>Your current subscription details</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Pro Plan — ₹499/month</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Manage Plan</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+### `<Badge>`
+
+```tsx
+import { Badge } from "@codeswayam/ui";
+
+<Badge variant="default">Active</Badge>
+<Badge variant="secondary">Beta</Badge>
+<Badge variant="destructive">Expired</Badge>
+<Badge variant="outline">Free</Badge>
+<Badge variant="success">Paid</Badge>
+<Badge variant="warning">Pending</Badge>
+<Badge variant="info">Info</Badge>
+<Badge variant="purple">AI</Badge>
+```
+
+**Variants:** `default`, `secondary`, `destructive`, `outline`, `success`, `warning`, `info`, `purple`
+
+---
+
+### `<Input>`
+
+```tsx
+import { Input } from "@codeswayam/ui";
+
+<Input type="email" placeholder="Enter your email" />
+<Input type="password" disabled />
+```
+
+---
+
+### `<Label>`
+
+```tsx
+import { Label } from "@codeswayam/ui";
+
+<Label htmlFor="email">Email Address</Label>
+<Input id="email" type="email" />
+```
+
+---
+
+### `<Avatar>`, `<AvatarImage>`, `<AvatarFallback>`
+
+Built on Radix Avatar with automatic fallback to initials.
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@codeswayam/ui";
+
+<Avatar className="h-10 w-10 rounded-lg">
+  <AvatarImage src={user.image} alt={user.name} />
+  <AvatarFallback className="bg-primary/10 text-primary font-bold">
+    {initials}
+  </AvatarFallback>
+</Avatar>
+```
+
+---
+
+### `<DropdownMenu>` and sub-components
+
+Full Radix DropdownMenu with all primitives exported.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuGroup,
+  DropdownMenuShortcut,
+} from "@codeswayam/ui";
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost">Options</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuLabel>My Account</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onClick={handleProfile}>Profile</DropdownMenuItem>
+    <DropdownMenuItem onClick={handleLogout} className="text-destructive">
+      Sign Out
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+---
+
+## SaaS Components
+
+### `<UserMenu>`
+
+High-end user profile dropdown for SaaS navigation bars. Shows avatar, name, email, and action items (Profile Settings, Security, Sign Out).
+
+```tsx
+import { UserMenu } from "@codeswayam/ui";
+
+<UserMenu
+  user={{ name: "Niteesh", email: "niteesh@example.com", image: "/avatar.jpg" }}
+  onLogout={handleLogout}
+  onProfileClick={() => router.push("/settings")}
+  onSecurityClick={() => router.push("/settings/security")}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `user` | `{ name?, email, image? } \| null` | User to display. Renders nothing if null |
+| `onLogout` | `() => void` | Called when "Sign Out" is clicked |
+| `onProfileClick` | `() => void` | Called when "Profile Settings" is clicked |
+| `onSecurityClick` | `() => void` | Called when "Security" is clicked |
+| `className` | `string` | Additional CSS classes |
+
+---
+
+### `<AppLogo>`
+
+Standard CodeSwayam app logo for consistency across platforms.
+
+```tsx
+import { AppLogo } from "@codeswayam/ui";
+
+<AppLogo />                    // Icon + "CodeSwayam" text
+<AppLogo showText={false} />   // Icon only
+<AppLogo className="scale-90" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showText` | `boolean` | `true` | Whether to show the "CodeSwayam" text |
+| `className` | `string` | — | Additional CSS classes |
+
+---
+
+### `<StatusBadge>`
+
+Smart subscription status badge with automatic color coding.
+
+```tsx
+import { StatusBadge } from "@codeswayam/ui";
+
+<StatusBadge status="active" />               // Green — "Active"
+<StatusBadge status="pending_cancellation" /> // Amber — "Pending Cancel"
+<StatusBadge status="canceled" />             // Red — "Canceled"
+<StatusBadge status="past_due" />             // Red — "Past Due"
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `status` | `"active" \| "past_due" \| "canceled" \| "pending_cancellation" \| string` | Subscription status |
+| `className` | `string` | Additional CSS classes |
+
+---
+
+## Layout Components
+
+### `<GlobalNavbar>`
+
+Responsive marketing navbar for public-facing pages. Auto-hides on app routes (`/app/*`, `/dashboard/*`). Includes scroll-aware blur effect, desktop nav links, and mobile slide-in menu.
+
+```tsx
+import { GlobalNavbar } from "@codeswayam/ui";
+
+// In your root layout — renders only on public pages
+export default function RootLayout({ children }) {
+  return (
+    <>
+      <GlobalNavbar />
+      {children}
+    </>
+  );
+}
+```
+
+- Transparent on load, blurred dark background on scroll
+- Auth links route to `NEXT_PUBLIC_AUTH_URL` or `localhost:3003` in dev
+- Full-screen mobile menu with slide animation
+- Hidden automatically on `/app` and `/dashboard` routes
+
+---
+
+### `<GlobalFooter>`
+
+Standard marketing footer for public pages.
+
+```tsx
+import { GlobalFooter } from "@codeswayam/ui";
+
+<GlobalFooter />
+```
+
+---
+
+## Full Export List
+
+```typescript
+// Base
+Button, buttonVariants
+Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
+Badge, badgeVariants
+Input
+Label
+Avatar, AvatarImage, AvatarFallback
+DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel,
+DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup,
+DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent,
+DropdownMenuSubTrigger, DropdownMenuRadioGroup
+
+// SaaS
+UserMenu, AppLogo, StatusBadge
+
+// Layout
+GlobalNavbar, GlobalFooter
+
+// Utils
+cn
+```