create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/setup/12-components-api.md

@@ -0,0 +1,665 @@
+# Components API Reference
+
+**UI Component Library**
+
+---
+
+## Overview
+
+Lego-One provides a set of reusable UI components built with Radix UI primitives and styled with Tailwind CSS. All components support dark mode and follow accessibility best practices.
+
+---
+
+## Installation
+
+Components are available via `@lego/kernel/components`:
+
+```typescript
+import { Button, Input, Card } from '@lego/kernel/components';
+```
+
+---
+
+## Form Components
+
+### Button
+
+A versatile button component with multiple variants and sizes.
+
+**Import:**
+```typescript
+import { Button } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+  size?: 'default' | 'sm' | 'lg' | 'icon';
+  asChild?: boolean;
+}
+```
+
+**Variants:**
+- `default` - Primary action button (blue)
+- `destructive` - Dangerous actions (red)
+- `outline` - Secondary action with border
+- `secondary` - Alternative secondary action
+- `ghost` - Minimal styling, hover background
+- `link` - Text link style
+
+**Sizes:**
+- `default` - 40px height (h-10)
+- `sm` - 36px height (h-9)
+- `lg` - 44px height (h-11)
+- `icon` - Square button (40px x 40px)
+
+**Examples:**
+```tsx
+<Button>Click me</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline" size="sm">Cancel</Button>
+<Button size="icon"><Icon /></Button>
+<Button disabled>Disabled</Button>
+```
+
+---
+
+### Input
+
+A text input field with consistent styling.
+
+**Import:**
+```typescript
+import { Input } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {}
+```
+
+**Examples:**
+```tsx
+<Input placeholder="Enter email..." />
+<Input type="password" placeholder="Password" />
+<Input disabled value="Disabled" />
+<Input className="w-full" />
+```
+
+---
+
+### Label
+
+Form label with proper accessibility.
+
+**Import:**
+```typescript
+import { Label } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {}
+```
+
+**Examples:**
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+---
+
+### Select
+
+Dropdown select component using Radix UI.
+
+**Import:**
+```typescript
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Select option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="1">Option 1</SelectItem>
+    <SelectItem value="2">Option 2</SelectItem>
+    <SelectItem value="3">Option 3</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+---
+
+### Switch
+
+Toggle switch component.
+
+**Import:**
+```typescript
+import { Switch } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface SwitchProps extends React.ComponentProps<typeof SwitchPrimitive.Root> {}
+```
+
+**Examples:**
+```tsx
+<Switch checked={enabled} onCheckedChange={setEnabled} />
+<Switch disabled />
+```
+
+---
+
+## Layout Components
+
+### Card
+
+Container component with header, content, and footer sections.
+
+**Import:**
+```typescript
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description goes here</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card content</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+### Separator
+
+Visual separator/divider line.
+
+**Import:**
+```typescript
+import { Separator } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface SeparatorProps extends React.ComponentProps<typeof SeparatorPrimitive.Root> {}
+```
+
+**Orientation:**
+- `horizontal` (default)
+- `vertical`
+
+**Examples:**
+```tsx
+<Separator />
+<Separator orientation="vertical" className="h-8" />
+```
+
+---
+
+### ScrollArea
+
+Custom scrollable container with styled scrollbars.
+
+**Import:**
+```typescript
+import { ScrollArea } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<ScrollArea className="h-96">
+  <div className="p-4">
+    {/* Long content */}
+  </div>
+</ScrollArea>
+```
+
+---
+
+## Feedback Components
+
+### Alert
+
+Notification alert with different severity levels.
+
+**Import:**
+```typescript
+import { Alert, AlertDescription, AlertTitle } from '@lego/kernel/components';
+```
+
+**Variants:**
+- `default` - Neutral info
+- `destructive` - Error/warning
+
+**Examples:**
+```tsx
+<Alert>
+  <AlertCircle className="h-4 w-4" />
+  <AlertTitle>Info</AlertTitle>
+  <AlertDescription>This is an informational message.</AlertDescription>
+</Alert>
+
+<Alert variant="destructive">
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>Something went wrong.</AlertDescription>
+</Alert>
+```
+
+---
+
+### Badge
+
+Small status or label indicator.
+
+**Import:**
+```typescript
+import { Badge } from '@lego/kernel/components';
+```
+
+**Props:**
+```typescript
+interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: 'default' | 'secondary' | 'destructive' | 'outline';
+}
+```
+
+**Examples:**
+```tsx
+<Badge>Default</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+---
+
+### Progress
+
+Progress bar indicator.
+
+**Import:**
+```typescript
+import { Progress } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Progress value={33} />
+<Progress value={66} className="w-96" />
+```
+
+---
+
+### Skeleton
+
+Loading placeholder content.
+
+**Import:**
+```typescript
+import { Skeleton } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Skeleton className="h-12 w-12 rounded-full" />
+<Skeleton className="h-4 w-64" />
+<Skeleton className="h-96 w-full" />
+```
+
+---
+
+### Toast
+
+Notification toast messages.
+
+**Import:**
+```typescript
+import { useToast } from '@lego/kernel/components';
+import { ToastProvider, Toast, ToastTitle, ToastDescription } from '@lego/kernel/components';
+```
+
+**Usage:**
+```tsx
+function App() {
+  return (
+    <ToastProvider>
+      {/* Your app */}
+      <Toaster />
+    </ToastProvider>
+  );
+}
+
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <Button onClick={() => {
+      toast({
+        title: 'Success',
+        description: 'Operation completed successfully',
+      });
+    }}>
+      Show Toast
+    </Button>
+  );
+}
+```
+
+---
+
+## Navigation Components
+
+### Tabs
+
+Tabbed content interface.
+
+**Import:**
+```typescript
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+    <TabsTrigger value="tab3">Tab 3</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">
+    Content 1
+  </TabsContent>
+  <TabsContent value="tab2">
+    Content 2
+  </TabsContent>
+  <TabsContent value="tab3">
+    Content 3
+  </TabsContent>
+</Tabs>
+```
+
+---
+
+### Dropdown Menu
+
+Context menu or dropdown menu.
+
+**Import:**
+```typescript
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost">Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>My Account</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuItem>Settings</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+---
+
+## Display Components
+
+### Avatar
+
+User avatar with image and fallback.
+
+**Import:**
+```typescript
+import { Avatar, AvatarImage, AvatarFallback } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+
+<Avatar>
+  <AvatarFallback className="bg-primary text-primary-foreground">
+    <User className="h-4 w-4" />
+  </AvatarFallback>
+</Avatar>
+```
+
+---
+
+### Table
+
+Data table with consistent styling.
+
+**Import:**
+```typescript
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+} from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John Doe</TableCell>
+      <TableCell>john@example.com</TableCell>
+      <TableCell>Active</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+## Overlay Components
+
+### Dialog
+
+Modal dialog component.
+
+**Import:**
+```typescript
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Are you sure?</DialogTitle>
+      <DialogDescription>
+        This action cannot be undone.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+---
+
+### Popover
+
+Floating popover content.
+
+**Import:**
+```typescript
+import { Popover, PopoverContent, PopoverTrigger } from '@lego/kernel/components';
+```
+
+**Examples:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="ghost">Trigger</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <div className="grid gap-4">
+      <h4 className="font-medium">Popover Content</h4>
+      <p className="text-sm text-muted-foreground">
+        Additional information here.
+      </p>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+---
+
+### Tooltip
+
+Hover tooltip for additional context.
+
+**Import:**
+```typescript
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@lego/kernel/components';
+```
+
+**Usage:**
+```tsx
+// Wrap your app in TooltipProvider once
+function App() {
+  return (
+    <TooltipProvider>
+      {/* Your app */}
+    </TooltipProvider>
+  );
+}
+
+// Use tooltips
+<Tooltip>
+  <TooltipTrigger>Hover me</TooltipTrigger>
+  <TooltipContent>
+    <p>Additional information</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+---
+
+## Utility Components
+
+### useToast Hook
+
+Programmatically show toast notifications.
+
+```typescript
+const { toast } = useToast();
+
+toast({
+  title: 'Success',
+  description: 'File uploaded successfully',
+  variant: 'default', // or 'destructive'
+});
+```
+
+---
+
+## Theming
+
+All components support CSS variables for theming:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --primary: 221.2 83.2% 53.3%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --accent: 210 40% 96.1%;
+  --accent-foreground: 222.2 47.4% 11.2%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 221.2 83.2% 53.3%;
+  --radius: 0.5rem;
+}
+```
+
+Dark mode support is built-in via the `dark:` class prefix.
+
+---
+
+## Accessibility
+
+All components follow WCAG 2.1 AA guidelines:
+
+- Keyboard navigation support
+- ARIA attributes included
+- Focus management
+- Screen reader support
+- High contrast mode support
+
+---
+
+## Best Practices
+
+1. **Always provide labels** for form inputs
+2. **Use semantic HTML** when building custom components
+3. **Test keyboard navigation** in your application
+4. **Provide sufficient color contrast** for text
+5. **Include loading states** for async actions
+6. **Handle errors gracefully** with user feedback
+7. **Use consistent spacing** via spacing scale
+
+---
+
+**Next:** Read [`13-deployment-guide.md`](./13-deployment-guide.md) for deployment instructions.