@coston/ui 0.1.1 → 0.2.2

package/llms.txt

@@ -0,0 +1,989 @@
+# @coston/ui
+
+> React UI component library built on Radix UI and Tailwind CSS.
+
+## Setup
+
+### Install
+
+```bash
+npm install @coston/ui @coston/design-tokens
+```
+
+Peer dependencies: `react`, `react-dom`
+
+### CSS (required — components render unstyled without this)
+
+Add to your root CSS file:
+
+```css
+@import 'tailwindcss';
+@import '@coston/design-tokens/tailwind.css';
+@import '@coston/ui/source.css';
+```
+
+### Import pattern
+
+```tsx
+// Each component is a named export from a separate entry point
+import { Button } from '@coston/ui/button';
+import { Card, CardHeader, CardTitle, CardContent } from '@coston/ui/card';
+import { cn } from '@coston/ui/lib/utils';
+import { useIsMobile } from '@coston/ui/hooks/use-mobile';
+```
+
+### Do NOT
+
+- Do not import from the package root: `import { Button } from '@coston/ui'` — there is no root export
+- Do not use default imports: `import Button from '@coston/ui/button'` — all exports are named
+- Do not skip the CSS setup — components will render without styles
+- Do not import `@coston/ui/source.css` without also importing `@coston/design-tokens/tailwind.css`
+
+## Optional peer dependencies
+
+| Component | Package |
+| --------- | ------- |
+| Chart | `recharts` |
+| Carousel | `embla-carousel-react` |
+| Sonner | `sonner` |
+| Drawer | `vaul` |
+| Command | `cmdk` |
+| Resizable | `react-resizable-panels` |
+| Calendar | `react-day-picker`, `date-fns` |
+
+## Components and exports
+
+### accordion
+Import: `@coston/ui/accordion`
+Exports: Accordion, AccordionItem, AccordionTrigger, AccordionContent
+
+### alert-dialog
+Import: `@coston/ui/alert-dialog`
+Exports: AlertDialog, AlertDialogPortal, AlertDialogOverlay, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel
+
+### alert
+Import: `@coston/ui/alert`
+Exports: Alert, AlertTitle, AlertDescription
+
+### aspect-ratio
+Import: `@coston/ui/aspect-ratio`
+Exports: AspectRatio
+
+### avatar
+Import: `@coston/ui/avatar`
+Exports: Avatar, AvatarImage, AvatarFallback
+
+### badge
+Import: `@coston/ui/badge`
+Exports: Badge, badgeVariants
+
+### breadcrumb
+Import: `@coston/ui/breadcrumb`
+Exports: Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis
+
+### button
+Import: `@coston/ui/button`
+Exports: Button, buttonVariants
+
+### calendar
+Import: `@coston/ui/calendar`
+Exports: Calendar
+
+### card
+Import: `@coston/ui/card`
+Exports: Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent
+
+### carousel
+Import: `@coston/ui/carousel`
+Exports: CarouselApi, Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
+
+### chart
+Import: `@coston/ui/chart`
+Exports: ChartContainer, ChartTooltip, ChartTooltipContent, ChartConfig
+
+### checkbox
+Import: `@coston/ui/checkbox`
+Exports: Checkbox
+
+### collapsible
+Import: `@coston/ui/collapsible`
+Exports: Collapsible, CollapsibleTrigger, CollapsibleContent
+
+### command
+Import: `@coston/ui/command`
+Exports: Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut
+
+### context-menu
+Import: `@coston/ui/context-menu`
+Exports: ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuShortcut, ContextMenuGroup, ContextMenuPortal, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuRadioGroup
+
+### dialog
+Import: `@coston/ui/dialog`
+Exports: Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription
+
+### drawer
+Import: `@coston/ui/drawer`
+Exports: Drawer, DrawerPortal, DrawerOverlay, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription
+
+### dropdown-menu
+Import: `@coston/ui/dropdown-menu`
+Exports: DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup
+
+### hover-card
+Import: `@coston/ui/hover-card`
+Exports: HoverCard, HoverCardTrigger, HoverCardContent
+
+### input
+Import: `@coston/ui/input`
+Exports: Input
+
+### label
+Import: `@coston/ui/label`
+Exports: Label
+
+### menubar
+Import: `@coston/ui/menubar`
+Exports: Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarLabel, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarPortal, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarGroup, MenubarShortcut
+
+### navigation-menu
+Import: `@coston/ui/navigation-menu`
+Exports: navigationMenuTriggerStyle, NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuContent, NavigationMenuTrigger, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport
+
+### pagination
+Import: `@coston/ui/pagination`
+Exports: Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
+
+### popover
+Import: `@coston/ui/popover`
+Exports: Popover, PopoverTrigger, PopoverContent
+
+### progress
+Import: `@coston/ui/progress`
+Exports: Progress
+
+### radio-group
+Import: `@coston/ui/radio-group`
+Exports: RadioGroup, RadioGroupItem
+
+### resizable
+Import: `@coston/ui/resizable`
+Exports: ResizablePanelGroup, ResizablePanel, ResizableHandle
+
+### scroll-area
+Import: `@coston/ui/scroll-area`
+Exports: ScrollArea, ScrollBar
+
+### select
+Import: `@coston/ui/select`
+Exports: Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton
+
+### separator
+Import: `@coston/ui/separator`
+Exports: Separator
+
+### sheet
+Import: `@coston/ui/sheet`
+Exports: Sheet, SheetPortal, SheetOverlay, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription
+
+### sidebar
+Import: `@coston/ui/sidebar`
+Exports: Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarSeparator, SidebarTrigger, useSidebar
+
+### skeleton
+Import: `@coston/ui/skeleton`
+Exports: Skeleton
+
+### slider
+Import: `@coston/ui/slider`
+Exports: Slider
+
+### sonner
+Import: `@coston/ui/sonner`
+Exports: Toaster
+
+### switch
+Import: `@coston/ui/switch`
+Exports: Switch
+
+### table
+Import: `@coston/ui/table`
+Exports: Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption
+
+### tabs
+Import: `@coston/ui/tabs`
+Exports: Tabs, TabsList, TabsTrigger, TabsContent
+
+### textarea
+Import: `@coston/ui/textarea`
+Exports: Textarea
+
+### toggle-group
+Import: `@coston/ui/toggle-group`
+Exports: ToggleGroup, ToggleGroupItem
+
+### toggle
+Import: `@coston/ui/toggle`
+Exports: Toggle, toggleVariants
+
+### tooltip
+Import: `@coston/ui/tooltip`
+Exports: Tooltip, TooltipTrigger, TooltipContent, TooltipProvider
+
+### Utilities
+
+- `cn(...classValues)` — `@coston/ui/lib/utils`
+- `useIsMobile()` — `@coston/ui/hooks/use-mobile`
+
+## Usage patterns
+
+### confirmation flow
+```tsx
+import { useState } from 'react';
+import { toast } from 'sonner';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@coston/ui/alert-dialog';
+import { Button } from '@coston/ui/button';
+import { Input } from '@coston/ui/input';
+import { Label } from '@coston/ui/label';
+
+function DestructiveConfirm() {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>
+        <Button variant="destructive">Delete project</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete project?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This action cannot be undone. All project data will be permanently removed.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+            onClick={() => toast.error('Project deleted')}
+          >
+            Delete
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+function TypeToConfirm() {
+  const [value, setValue] = useState('');
+  const confirmed = value === 'DELETE';
+
+  return (
+    <AlertDialog onOpenChange={() => setValue('')}>
+      <AlertDialogTrigger asChild>
+        <Button variant="outline">Delete account</Button>
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete your account?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This permanently deletes your account and all associated data. Type{' '}
+            <strong>DELETE</strong> to confirm.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <div className="grid gap-2 py-2">
+          <Label htmlFor="confirm-input">Confirmation</Label>
+          <Input
+            id="confirm-input"
+            value={value}
+            onChange={e => setValue(e.target.value)}
+            placeholder="Type DELETE"
+          />
+        </div>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            disabled={!confirmed}
+            className="bg-destructive text-destructive-foreground hover:bg-destructive/90 disabled:opacity-50"
+            onClick={() => toast.success('Account deleted')}
+          >
+            Delete account
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+export function ConfirmationFlow() {
+  return (
+    <div className="flex flex-wrap gap-4 p-6">
+      <DestructiveConfirm />
+      <TypeToConfirm />
+    </div>
+  );
+}
+```
+
+### contextual header
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@coston/ui/breadcrumb';
+import { Separator } from '@coston/ui/separator';
+import { SidebarTrigger } from '@coston/ui/sidebar';
+import { Tabs, TabsList, TabsTrigger } from '@coston/ui/tabs';
+
+const tabItems = ['Overview', 'Details', 'Projects', 'Notes'];
+
+/**
+ * Contextual Header
+ *
+ * Header with breadcrumb trail and inline sub-navigation tabs.
+ * Use for record detail pages (CRM accounts, project views, etc.)
+ * where the user navigated from a parent list into a specific record.
+ *
+ * Desktop: single row — SidebarTrigger | Breadcrumb | Tabs
+ * Mobile:  two rows  — [SidebarTrigger | Breadcrumb] / [scrollable Tabs]
+ */
+export function ContextualHeader() {
+  return (
+    <div className="flex shrink-0 flex-col border-b border-border/50">
+      {/* Primary row: trigger + breadcrumb (+ inline tabs on sm+) */}
+      <div className="flex h-12 items-center gap-1 px-4 lg:gap-2 lg:px-6">
+        <SidebarTrigger className="-ml-1" />
+        <Separator orientation="vertical" className="mx-2 data-[orientation=vertical]:h-4" />
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">External</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>Acme Inc.</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+
+        {/* Tabs inline — only on sm+ */}
+        <div className="ml-2 hidden items-center sm:flex">
+          <Separator orientation="vertical" className="mx-2 data-[orientation=vertical]:h-4" />
+          <Tabs defaultValue="overview">
+            <TabsList>
+              {tabItems.map(tab => (
+                <TabsTrigger key={tab} value={tab.toLowerCase()}>
+                  {tab}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+          </Tabs>
+        </div>
+      </div>
+
+      {/* Secondary row: tabs on mobile only */}
+      <div className="flex items-center overflow-x-auto border-t border-border/30 px-3 pb-1 pt-0.5 sm:hidden">
+        <Tabs defaultValue="overview">
+          <TabsList>
+            {tabItems.map(tab => (
+              <TabsTrigger key={tab} value={tab.toLowerCase()}>
+                {tab}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+        </Tabs>
+      </div>
+    </div>
+  );
+}
+```
+
+### data table toolbar
+```tsx
+import { useState } from 'react';
+import { DownloadIcon, PlusIcon, SearchIcon } from 'lucide-react';
+import { Badge } from '@coston/ui/badge';
+import { Button } from '@coston/ui/button';
+import { Input } from '@coston/ui/input';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@coston/ui/select';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@coston/ui/table';
+
+type Status = 'Active' | 'Inactive' | 'Archived';
+
+type Row = {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+  status: Status;
+  createdAt: string;
+};
+
+const data: Row[] = [
+  {
+    id: 1,
+    name: 'Alice Martin',
+    email: 'alice@example.com',
+    role: 'Admin',
+    status: 'Active',
+    createdAt: 'Jan 12, 2024',
+  },
+  {
+    id: 2,
+    name: 'Bob Chen',
+    email: 'bob@example.com',
+    role: 'Editor',
+    status: 'Active',
+    createdAt: 'Feb 3, 2024',
+  },
+  {
+    id: 3,
+    name: 'Carol Davis',
+    email: 'carol@example.com',
+    role: 'Viewer',
+    status: 'Inactive',
+    createdAt: 'Mar 8, 2024',
+  },
+  {
+    id: 4,
+    name: 'Dan Kim',
+    email: 'dan@example.com',
+    role: 'Editor',
+    status: 'Active',
+    createdAt: 'Mar 19, 2024',
+  },
+  {
+    id: 5,
+    name: 'Eva Rossi',
+    email: 'eva@example.com',
+    role: 'Admin',
+    status: 'Archived',
+    createdAt: 'Apr 2, 2024',
+  },
+  {
+    id: 6,
+    name: 'Frank Lee',
+    email: 'frank@example.com',
+    role: 'Viewer',
+    status: 'Active',
+    createdAt: 'Apr 15, 2024',
+  },
+  {
+    id: 7,
+    name: 'Grace Park',
+    email: 'grace@example.com',
+    role: 'Editor',
+    status: 'Inactive',
+    createdAt: 'May 7, 2024',
+  },
+  {
+    id: 8,
+    name: 'Henry Wu',
+    email: 'henry@example.com',
+    role: 'Viewer',
+    status: 'Active',
+    createdAt: 'May 20, 2024',
+  },
+];
+
+const statusVariant: Record<Status, 'default' | 'secondary' | 'outline'> = {
+  Active: 'default',
+  Inactive: 'secondary',
+  Archived: 'outline',
+};
+
+const PAGE_SIZE = 5;
+
+export function DataTableToolbar() {
+  const [search, setSearch] = useState('');
+  const [status, setStatus] = useState('all');
+  const [page, setPage] = useState(0);
+
+  const filtered = data.filter(row => {
+    const matchesSearch =
+      row.name.toLowerCase().includes(search.toLowerCase()) ||
+      row.email.toLowerCase().includes(search.toLowerCase());
+    const matchesStatus = status === 'all' || row.status === status;
+    return matchesSearch && matchesStatus;
+  });
+
+  const pageCount = Math.ceil(filtered.length / PAGE_SIZE);
+  const paged = filtered.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE);
+
+  return (
+    <div className="flex flex-col gap-4 p-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="relative min-w-[160px] flex-1">
+          <SearchIcon className="absolute left-2.5 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            placeholder="Search users…"
+            value={search}
+            onChange={e => {
+              setSearch(e.target.value);
+              setPage(0);
+            }}
+            className="pl-8"
+          />
+        </div>
+        <Select
+          value={status}
+          onValueChange={v => {
+            setStatus(v);
+            setPage(0);
+          }}
+        >
+          <SelectTrigger className="w-[140px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All statuses</SelectItem>
+            <SelectItem value="Active">Active</SelectItem>
+            <SelectItem value="Inactive">Inactive</SelectItem>
+            <SelectItem value="Archived">Archived</SelectItem>
+          </SelectContent>
+        </Select>
+        <Button variant="outline" size="sm">
+          <PlusIcon className="h-4 w-4" />
+          Add user
+        </Button>
+        <Button variant="ghost" size="sm">
+          <DownloadIcon className="h-4 w-4" />
+          Export
+        </Button>
+      </div>
+
+      <div className="rounded-md border border-border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead className="hidden sm:table-cell">Email</TableHead>
+              <TableHead className="hidden md:table-cell">Role</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead className="hidden lg:table-cell">Created</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {paged.length ? (
+              paged.map(row => (
+                <TableRow key={row.id}>
+                  <TableCell className="font-medium">{row.name}</TableCell>
+                  <TableCell className="hidden text-muted-foreground sm:table-cell">
+                    {row.email}
+                  </TableCell>
+                  <TableCell className="hidden md:table-cell">{row.role}</TableCell>
+                  <TableCell>
+                    <Badge variant={statusVariant[row.status]}>{row.status}</Badge>
+                  </TableCell>
+                  <TableCell className="hidden text-muted-foreground lg:table-cell">
+                    {row.createdAt}
+                  </TableCell>
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell colSpan={5} className="h-24 text-center text-muted-foreground">
+                  No results found.
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>
+          {filtered.length} result{filtered.length !== 1 ? 's' : ''}
+        </span>
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={page === 0}
+            onClick={() => setPage(p => p - 1)}
+          >
+            Previous
+          </Button>
+          <span>
+            Page {page + 1} of {Math.max(1, pageCount)}
+          </span>
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={page >= pageCount - 1}
+            onClick={() => setPage(p => p + 1)}
+          >
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### empty state
+```tsx
+import { SearchIcon, FolderIcon, AlertCircleIcon } from 'lucide-react';
+import { Button } from '@coston/ui/button';
+
+const variants = [
+  {
+    icon: SearchIcon,
+    title: 'No results',
+    description: 'Try adjusting your filters',
+    action: 'Clear filters',
+  },
+  {
+    icon: FolderIcon,
+    title: 'No items yet',
+    description: 'Get started by creating your first one',
+    action: 'Create item',
+  },
+  {
+    icon: AlertCircleIcon,
+    title: 'Something went wrong',
+    description: 'We had trouble loading this content',
+    action: 'Retry',
+  },
+];
+
+export function EmptyState() {
+  return (
+    <div className="grid grid-cols-1 gap-4 p-6 sm:grid-cols-3">
+      {variants.map(({ icon: Icon, title, description, action }) => (
+        <div
+          key={title}
+          className="flex flex-col items-center gap-3 rounded-lg border border-border p-8 text-center"
+        >
+          <div className="flex h-12 w-12 items-center justify-center rounded-full bg-muted">
+            <Icon className="h-6 w-6 text-muted-foreground" />
+          </div>
+          <div>
+            <p className="text-sm font-medium">{title}</p>
+            <p className="text-sm text-muted-foreground">{description}</p>
+          </div>
+          <Button variant="outline" size="sm">
+            {action}
+          </Button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### multi step form
+```tsx
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@coston/ui/button';
+import { Input } from '@coston/ui/input';
+import { Label } from '@coston/ui/label';
+import { Progress } from '@coston/ui/progress';
+import { Separator } from '@coston/ui/separator';
+import { Textarea } from '@coston/ui/textarea';
+
+type FormValues = {
+  email: string;
+  password: string;
+  name: string;
+  bio: string;
+};
+
+const steps = ['Account', 'Profile', 'Confirm'];
+
+function StepIndicator({ current }: { current: number }) {
+  return (
+    <div className="flex items-center justify-center">
+      {steps.map((label, i) => (
+        <div key={label} className="flex items-center">
+          <div className="flex flex-col items-center gap-1">
+            <div
+              className={[
+                'flex h-7 w-7 items-center justify-center rounded-full text-xs font-medium',
+                i < current
+                  ? 'bg-primary text-primary-foreground'
+                  : i === current
+                    ? 'text-primary ring-2 ring-primary'
+                    : 'bg-muted text-muted-foreground',
+              ].join(' ')}
+            >
+              {i < current ? '✓' : i + 1}
+            </div>
+            <span
+              className={`text-xs ${i === current ? 'font-medium text-foreground' : 'text-muted-foreground'}`}
+            >
+              {label}
+            </span>
+          </div>
+          {i < steps.length - 1 && (
+            <div className={`mx-2 mb-4 h-px w-12 ${i < current ? 'bg-primary' : 'bg-border'}`} />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function MultiStepForm() {
+  const [step, setStep] = useState(0);
+  const [values, setValues] = useState<FormValues>({ email: '', password: '', name: '', bio: '' });
+
+  const set =
+    (field: keyof FormValues) => (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) =>
+      setValues(v => ({ ...v, [field]: e.target.value }));
+
+  const handleSubmit = () => {
+    toast.success('Account created!');
+    setStep(0);
+    setValues({ email: '', password: '', name: '', bio: '' });
+  };
+
+  return (
+    <div className="p-6">
+      <div className="mx-auto flex max-w-md flex-col gap-6">
+        <Progress value={((step + 1) / steps.length) * 100} className="h-1" />
+        <StepIndicator current={step} />
+        <Separator />
+
+        {step === 0 && (
+          <div className="flex flex-col gap-4">
+            <div className="grid gap-2">
+              <Label htmlFor="email">Email</Label>
+              <Input
+                id="email"
+                type="email"
+                placeholder="you@example.com"
+                value={values.email}
+                onChange={set('email')}
+              />
+            </div>
+            <div className="grid gap-2">
+              <Label htmlFor="password">Password</Label>
+              <Input
+                id="password"
+                type="password"
+                placeholder="••••••••"
+                value={values.password}
+                onChange={set('password')}
+              />
+            </div>
+          </div>
+        )}
+
+        {step === 1 && (
+          <div className="flex flex-col gap-4">
+            <div className="grid gap-2">
+              <Label htmlFor="name">Full name</Label>
+              <Input
+                id="name"
+                placeholder="Jane Smith"
+                value={values.name}
+                onChange={set('name')}
+              />
+            </div>
+            <div className="grid gap-2">
+              <Label htmlFor="bio">Bio</Label>
+              <Textarea
+                id="bio"
+                placeholder="Tell us a little about yourself…"
+                value={values.bio}
+                onChange={set('bio')}
+              />
+            </div>
+          </div>
+        )}
+
+        {step === 2 && (
+          <div className="flex flex-col gap-3 text-sm">
+            <p className="font-medium">Review your details</p>
+            {(
+              [
+                ['Email', values.email || '—'],
+                ['Password', values.password ? '••••••••' : '—'],
+                ['Name', values.name || '—'],
+                ['Bio', values.bio || '—'],
+              ] as [string, string][]
+            ).map(([label, value]) => (
+              <div key={label} className="flex justify-between">
+                <span className="text-muted-foreground">{label}</span>
+                <span>{value}</span>
+              </div>
+            ))}
+          </div>
+        )}
+
+        <div className="flex justify-between">
+          <Button variant="outline" onClick={() => setStep(s => s - 1)} disabled={step === 0}>
+            Back
+          </Button>
+          {step < steps.length - 1 ? (
+            <Button onClick={() => setStep(s => s + 1)}>Next</Button>
+          ) : (
+            <Button onClick={handleSubmit}>Create account</Button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### split pane
+```tsx
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@coston/ui/resizable';
+import { ScrollArea } from '@coston/ui/scroll-area';
+
+const fileTree = [
+  'src/',
+  '  components/',
+  '    Button.tsx',
+  '    Input.tsx',
+  '  pages/',
+  '    Home.tsx',
+  '    Settings.tsx',
+  'package.json',
+  'tsconfig.json',
+];
+
+export function SplitPane() {
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">Horizontal — file explorer + document</p>
+        <ResizablePanelGroup
+          orientation="horizontal"
+          className="h-[260px] rounded-lg border border-border"
+        >
+          <ResizablePanel defaultSize={30} minSize={20}>
+            <ScrollArea className="h-full">
+              <div className="flex flex-col gap-0.5 p-2">
+                {fileTree.map((item, i) => (
+                  <div
+                    key={i}
+                    className="cursor-pointer rounded px-2 py-1 font-mono text-xs text-muted-foreground hover:bg-muted"
+                  >
+                    {item}
+                  </div>
+                ))}
+              </div>
+            </ScrollArea>
+          </ResizablePanel>
+          <ResizableHandle withHandle />
+          <ResizablePanel defaultSize={70}>
+            <ScrollArea className="h-full">
+              <div className="p-4">
+                <h3 className="mb-2 text-sm font-semibold">Button.tsx</h3>
+                <p className="text-sm leading-relaxed text-muted-foreground">
+                  Primary interactive element. Supports multiple variants (default, outline, ghost,
+                  destructive) and sizes (sm, default, lg, icon). Built on Radix Slot for
+                  polymorphic rendering.
+                </p>
+              </div>
+            </ScrollArea>
+          </ResizablePanel>
+        </ResizablePanelGroup>
+      </div>
+
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">Vertical — editor + preview</p>
+        <ResizablePanelGroup
+          orientation="vertical"
+          className="h-[300px] rounded-lg border border-border"
+        >
+          <ResizablePanel defaultSize={50}>
+            <ScrollArea className="h-full">
+              <pre className="p-4 font-mono text-xs text-muted-foreground">{`export function Hello() {
+  return (
+    <div className="p-4">
+      <h1>Hello, world!</h1>
+      <p>Edit this to see changes.</p>
+    </div>
+  );
+}`}</pre>
+            </ScrollArea>
+          </ResizablePanel>
+          <ResizableHandle withHandle />
+          <ResizablePanel defaultSize={50}>
+            <div className="flex h-full items-start p-4">
+              <div>
+                <h1 className="text-lg font-bold">Hello, world!</h1>
+                <p className="text-sm text-muted-foreground">Edit this to see changes.</p>
+              </div>
+            </div>
+          </ResizablePanel>
+        </ResizablePanelGroup>
+      </div>
+    </div>
+  );
+}
+```
+
+### toast feedback
+```tsx
+import { toast } from 'sonner';
+import { Button } from '@coston/ui/button';
+
+const variants = [
+  { label: 'Default', action: () => toast('Default notification') },
+  { label: 'Success', action: () => toast.success('Changes saved successfully') },
+  { label: 'Error', action: () => toast.error('Something went wrong') },
+  { label: 'Warning', action: () => toast.warning('Low disk space') },
+  { label: 'Info', action: () => toast.info('Update available') },
+  {
+    label: 'With description',
+    action: () =>
+      toast('File uploaded', {
+        description: 'report.pdf was uploaded to /documents',
+      }),
+  },
+  {
+    label: 'With action',
+    action: () =>
+      toast('Message sent', {
+        action: { label: 'Undo', onClick: () => toast.success('Message unsent') },
+      }),
+  },
+  {
+    label: 'Loading → done',
+    action: () => {
+      const id = toast.loading('Saving…');
+      setTimeout(() => toast.success('Saved!', { id }), 2000);
+    },
+  },
+  {
+    label: 'Promise',
+    action: () =>
+      toast.promise(new Promise(resolve => setTimeout(resolve, 2000)), {
+        loading: 'Uploading file…',
+        success: 'Upload complete',
+        error: 'Upload failed',
+      }),
+  },
+];
+
+export function ToastFeedback() {
+  return (
+    <div className="grid grid-cols-2 gap-2 p-6 sm:grid-cols-3">
+      {variants.map(({ label, action }) => (
+        <Button key={label} variant="outline" size="sm" onClick={action}>
+          {label}
+        </Button>
+      ))}
+    </div>
+  );
+}
+```