create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/setup/08-component-library.md

@@ -0,0 +1,658 @@
+# Component Library
+
+**UI Components, Styling, and Design System**
+
+---
+
+## Overview
+
+Lego-One uses **Radix UI primitives** styled with **Tailwind CSS** for accessible, customizable UI components. All components support dark mode and follow WCAG accessibility guidelines.
+
+---
+
+## Design System
+
+### Colors
+
+CSS variables enable theming and dark mode:
+
+```css
+:root {
+  --background: 0 0% 100%;        /* White background */
+  --foreground: 222.2 84% 4.9%;   /* Dark text */
+  --primary: 221.2 83.2% 53.3%;   /* Primary blue */
+  --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;
+}
+```
+
+**Usage:**
+```tsx
+<div className="bg-background text-foreground">
+  <h1 className="text-primary">Primary colored heading</h1>
+  <p className="text-muted-foreground">Muted text</p>
+</div>
+```
+
+### Dark Mode
+
+Dark mode is automatic via the `dark:` class prefix:
+
+```tsx
+<div className="bg-background dark:bg-gray-950">
+  <p className="text-foreground dark:text-gray-100">
+    Adapts to dark mode
+  </p>
+</div>
+```
+
+**Tailwind Config:**
+```typescript
+darkMode: ['class'], // Enables .dark class on html element
+```
+
+### Typography
+
+**Font:** Inter (via system fonts)
+
+**Scale:**
+```tsx
+<h1 className="text-3xl font-bold">Heading 1</h1>
+<h2 className="text-2xl font-semibold">Heading 2</h2>
+<h3 className="text-xl font-medium">Heading 3</h3>
+<p className="text-sm">Body text</p>
+<span className="text-xs">Small text</span>
+```
+
+### Spacing
+
+**Scale:** 4px base unit (Tailwind default)
+
+```tsx
+<div className="p-4">    /* 16px padding */
+<div className="px-6">   /* 24px horizontal padding */
+<div className="py-2">   /* 8px vertical padding */
+<div className="m-8">    /* 32px margin */
+<div className="gap-4">  /* 16px gap (flex/grid) */
+```
+
+---
+
+## Available Components
+
+### Form Components
+
+#### Button
+
+**Import:** `import { Button } from '@lego/kernel/components'`
+
+**Variants:**
+```tsx
+<Button>Default</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="link">Link</Button>
+```
+
+**Sizes:**
+```tsx
+<Button size="default">Default</Button>
+<Button size="sm">Small</Button>
+<Button size="lg">Large</Button>
+<Button size="icon"><Icon /></Button>
+```
+
+**States:**
+```tsx
+<Button disabled>Disabled</Button>
+```
+
+---
+
+#### Input
+
+**Import:** `import { Input } from '@lego/kernel/components'`
+
+```tsx
+<Input placeholder="Enter text..." />
+<Input type="password" placeholder="Password" />
+<Input type="email" placeholder="Email" />
+<Input disabled value="Disabled" />
+```
+
+---
+
+#### Label
+
+**Import:** `import { Label } from '@lego/kernel/components'`
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+---
+
+#### Textarea
+
+**Import:** `import { Textarea } from '@lego/kernel/components'`
+
+```tsx
+<Textarea placeholder="Enter description..." rows={5} />
+```
+
+---
+
+#### Select
+
+**Import:** `import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue }`
+
+```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>
+```
+
+---
+
+#### Checkbox
+
+**Import:** `import { Checkbox } from '@lego/kernel/components'`
+
+```tsx
+<Checkbox checked={checked} onCheckedChange={setChecked} />
+<Checkbox disabled />
+```
+
+---
+
+#### Switch
+
+**Import:** `import { Switch } from '@lego/kernel/components'`
+
+```tsx
+<Switch checked={enabled} onCheckedChange={setEnabled} />
+<Switch disabled />
+```
+
+---
+
+### Layout Components
+
+#### Card
+
+**Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }`
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card content</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+#### Separator
+
+**Import:** `import { Separator } from '@lego/kernel/components'`
+
+```tsx
+<Separator />                 {/* Horizontal */}
+<Separator orientation="vertical" className="h-8" />  {/* Vertical */}
+```
+
+---
+
+#### ScrollArea
+
+**Import:** `import { ScrollArea } from '@lego/kernel/components'`
+
+```tsx
+<ScrollArea className="h-96">
+  <div className="p-4">
+    {/* Long content */}
+  </div>
+</ScrollArea>
+```
+
+---
+
+### Feedback Components
+
+#### Alert
+
+**Import:** `import { Alert, AlertDescription, AlertTitle }`
+
+```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
+
+**Import:** `import { Badge } from '@lego/kernel/components'`
+
+```tsx
+<Badge>Default</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+---
+
+#### Progress
+
+**Import:** `import { Progress } from '@lego/kernel/components'`
+
+```tsx
+<Progress value={33} />
+<Progress value={66} className="w-96" />
+```
+
+---
+
+#### Skeleton
+
+**Import:** `import { Skeleton } from '@lego/kernel/components'`
+
+```tsx
+<Skeleton className="h-12 w-12 rounded-full" />
+<Skeleton className="h-4 w-64" />
+<Skeleton className="h-96 w-full" />
+```
+
+---
+
+#### Toast
+
+**Import:** `import { useToast } from '@lego/kernel/components'`
+
+```tsx
+// In root App.tsx
+<Toaster />
+
+// In component
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <Button onClick={() => {
+      toast({
+        title: 'Success',
+        description: 'Operation completed',
+      });
+    }}>
+      Show Toast
+    </Button>
+  );
+}
+```
+
+---
+
+### Navigation Components
+
+#### Tabs
+
+**Import:** `import { Tabs, TabsList, TabsTrigger, TabsContent }`
+
+```tsx
+<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>
+```
+
+---
+
+#### Dropdown Menu
+
+**Import:** `import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator }`
+
+```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
+
+**Import:** `import { Avatar, AvatarImage, AvatarFallback }`
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+#### Table
+
+**Import:** `import { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell }`
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John Doe</TableCell>
+      <TableCell>john@example.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+### Overlay Components
+
+#### Dialog
+
+**Import:** `import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger }`
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm Action</DialogTitle>
+      <DialogDescription>
+        This action cannot be undone.
+      </DialogDescription>
+    </DialogHeader>
+    <div className="flex justify-end gap-2">
+      <Button variant="outline">Cancel</Button>
+      <Button>Confirm</Button>
+    </div>
+  </DialogContent>
+</Dialog>
+```
+
+---
+
+#### Popover
+
+**Import:** `import { Popover, PopoverContent, PopoverTrigger }`
+
+```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
+      </p>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+---
+
+#### Tooltip
+
+**Import:** `import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }`
+
+```tsx
+// Wrap app with TooltipProvider once
+<TooltipProvider>
+  <App />
+</TooltipProvider>
+
+// Use tooltips
+<Tooltip>
+  <TooltipTrigger>Hover me</TooltipTrigger>
+  <TooltipContent>
+    <p>Additional information</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+---
+
+## Utility Functions
+
+### cn() - Class Name Merger
+
+**Import:** `import { cn } from '@lego/kernel/lib/utils'`
+
+Merges Tailwind classes with conditional logic:
+
+```tsx
+import { cn } from '@lego/kernel/lib/utils';
+
+function MyComponent({ isActive }: { isActive: boolean }) {
+  return (
+    <div className={cn(
+      'base-classes',
+      isActive && 'active-classes',
+      'always-applied'
+    )}>
+      Content
+    </div>
+  );
+}
+```
+
+---
+
+## Using Components in Plugins
+
+Plugins can use kernel components via the window bridge or by importing if bundled:
+
+```typescript
+// In plugin (bundled production)
+import { Button, Card, Dialog } from '@lego/kernel/components';
+
+function MyPluginComponent() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>My Plugin</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Click me</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Component Patterns
+
+### Form with Validation
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button, Input, Label } from '@lego/kernel/components';
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+function LoginForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <div>
+        <Label htmlFor="email">Email</Label>
+        <Input {...register('email')} />
+        {errors.email && <span className="text-destructive">{errors.email.message}</span>}
+      </div>
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+```
+
+### Data Table with Actions
+
+```tsx
+import { Button, DropdownMenu, Table } from '@lego/kernel/components';
+import { MoreHorizontal } from 'lucide-react';
+
+function DataTable({ data }: { data: Item[] }) {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Name</TableHead>
+          <TableHead>Actions</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {data.map((item) => (
+          <TableRow key={item.id}>
+            <TableCell>{item.name}</TableCell>
+            <TableCell>
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <Button size="icon" variant="ghost">
+                    <MoreHorizontal className="h-4 w-4" />
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <DropdownMenuItem>Edit</DropdownMenuItem>
+                  <DropdownMenuItem className="text-destructive">Delete</DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Loading States
+
+```tsx
+import { Skeleton, Card, CardHeader, CardContent } from '@lego/kernel/components';
+
+function LoadingCard() {
+  return (
+    <Card>
+      <CardHeader>
+        <Skeleton className="h-6 w-48" />
+      </CardHeader>
+      <CardContent>
+        <Skeleton className="h-4 w-full mb-2" />
+        <Skeleton className="h-4 w-3/4" />
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Icons (Lucide React)
+
+**Import:** `import { IconName } from 'lucide-react'`
+
+```tsx
+import { Home, Settings, User, Search, Plus, Trash } from 'lucide-react';
+
+<Home className="h-5 w-5" />
+<Settings className="h-6 w-6" />
+<User className="h-4 w-4" />
+```
+
+**Common Icons:**
+- **Navigation:** `Home`, `Settings`, `LayoutDashboard`, `CheckSquare`
+- **Actions:** `Plus`, `Trash`, `Edit`, `Save`, `X`
+- **UI:** `Menu`, `Bell`, `Search`, `ChevronDown`, `ChevronRight`
+- **Status:** `Check`, `XCircle`, `AlertCircle`, `Loader2`
+
+---
+
+## Best Practices
+
+1. **Use existing components** - Don't recreate what exists
+2. **Follow accessibility** - All Radix components are accessible by default
+3. **Support dark mode** - Use `dark:` prefix for dark mode styles
+4. **Use semantic HTML** - Button, Dialog, etc. render proper elements
+5. **Handle loading/error states** - Use Skeleton, Alert for feedback
+6. **Responsive design** - Mobile-first approach with Tailwind breakpoints
+
+---
+
+**Next:** Read [`09-data-integration.md`](./09-data-integration.md) for PocketBase and data fetching patterns.