@reinvented/design 1.0.0 → 1.2.0

package/skills/components/input.md

@@ -0,0 +1,107 @@
+# Input, Textarea, Label
+
+Text entry components. Never use raw `<input>` or `<textarea>`.
+
+```ts
+import { Input, Textarea, Label } from '@reinvented/design'
+```
+
+## Input
+
+Standard single-line text field with built-in styling for focus, disabled, and placeholder states.
+
+```tsx
+<div className="space-y-2">
+  <Label for="email">Email</Label>
+  <Input id="email" type="email" placeholder="sarah@example.com" defaultValue="email" />
+</div>
+```
+
+### Input with Icon
+
+```tsx
+<div className="relative">
+  <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+  <Input className="pl-9" placeholder="Search..." defaultValue="query" />
+</div>
+```
+
+Key: Use `pl-9` (36px) to make room for the icon. Icon is positioned with `absolute left-3 top-1/2 -translate-y-1/2`.
+
+### Input Sizes
+
+The default Input height matches `h-9` (36px). For different contexts:
+- Standard: default (no size prop needed)
+- Custom height: apply via class `className="h-8"` for compact, `className="h-10"` for larger
+
+### Disabled Input
+
+```tsx
+<Input disabled :value="user.email" />
+```
+
+### Form Field Pattern (Label + Input + Description + Error)
+
+```tsx
+<div className="space-y-2">
+  <Label for="name">Display Name</Label>
+  <Input id="name" defaultValue="name" placeholder="Your display name" />
+  <p className="text-xs text-muted-foreground">This is how others will see you.</p>
+</div>
+```
+
+For error state:
+```tsx
+<div className="space-y-2">
+  <Label for="name">Display Name</Label>
+  <Input id="name" defaultValue="name" className="border-destructive" />
+  <p className="text-xs text-destructive">Name is required.</p>
+</div>
+```
+
+## Textarea
+
+Multi-line text input.
+
+```tsx
+<div className="space-y-2">
+  <Label for="bio">Bio</Label>
+  <Textarea id="bio" defaultValue="bio" placeholder="Tell us about yourself..." rows="4" />
+</div>
+```
+
+Use `rows` to control initial height. Default is 3 rows.
+
+## Label
+
+Always pair with an input using matching `for`/`id` attributes.
+
+```tsx
+<Label for="username" className="text-sm font-medium">Username</Label>
+```
+
+Label is `text-sm font-medium` by default. Never use `text-base` or larger for form labels.
+
+## Anti-Patterns
+
+```tsx
+<!-- ❌ No label -->
+<Input placeholder="Enter name" />
+
+<!-- ✅ Always pair with Label -->
+<div className="space-y-2">
+  <Label for="name">Name</Label>
+  <Input id="name" placeholder="Enter name" />
+</div>
+```
+
+```tsx
+<!-- ❌ Using icon inside Input via slot (doesn't exist) -->
+<Input><SearchIcon /></Input>
+
+<!-- ✅ Use the absolute-positioned icon pattern -->
+<div className="relative">
+  <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+  <Input className="pl-9" placeholder="Search..." />
+</div>
+```

package/skills/components/map.md

@@ -0,0 +1,53 @@
+# Interactive Map
+
+Data-focused map visualization wrapper around Google Maps.
+
+```ts
+import { InteractiveMap } from '@reinvented/design'
+```
+
+## Basic Structure
+
+The `InteractiveMap` component renders a fluid, styled Google Map meant for spatial data visualization like finding locations, tracking fleets, or plotting regional data.
+
+```tsx
+<InteractiveMap
+  :markers="[
+    { id: 1, lat: 40.7128, lng: -74.0060, label: 'NYC Hub' },
+    { id: 2, lat: 34.0522, lng: -118.2437, label: 'LA Port' }
+  ]"
+  className="h-[400px]"
+/>
+```
+
+When `markers` are provided, the map will **automatically fit its bounds** to ensure all markers are visible. You do not need to provide a `center` or `zoom` when providing `markers`.
+
+## Usage Without Markers
+
+If you want to render a map without markers, explicitly provide `center` and `zoom`:
+
+```tsx
+<InteractiveMap
+  :center="{ lat: 51.5072, lng: -0.1276 }"
+  :zoom="12"
+  className="h-[400px]"
+/>
+```
+
+## Mock Mode (Mockups Only)
+
+When generating pure mockups without real data or needing a strict wireframe, use the `mock` prop to bypass the heavyweight map engine and display a beautiful placeholder.
+
+```tsx
+<InteractiveMap
+  mock
+  :markers="mockLocations"
+  className="h-[400px]"
+/>
+```
+
+## Component Rules
+
+- **Always set height**: The wrapper `<div className="relative w-full h-full">` inherits dimensions. Give the component an explicit absolute height (e.g., `className="h-96"`, `className="h-[400px]"`) or place it in a container that has explicit height.
+- **Data formats**: `lat` and `lng` must be **numbers**, not strings.
+- **Do not use `ComponentPlaceholder` for Maps**: Now that the design system formally provides `<InteractiveMap>`, never use a `ComponentPlaceholder` for maps in your layouts. Use this native component.

package/skills/components/navigation.md

@@ -0,0 +1,73 @@
+# Navigation Components
+
+Breadcrumbs, pagination, and navigation menus.
+
+```ts
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@reinvented/design'
+import { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationLast, PaginationNext, PaginationPrev } from '@reinvented/design'
+import { NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger } from '@reinvented/design'
+```
+
+## Breadcrumb
+
+Path navigation for hierarchies of 3+ levels. Shows the user where they are.
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Project Alpha</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+- The last item uses `BreadcrumbPage` (non-clickable, current location)
+- All intermediate items use `BreadcrumbLink` (clickable)
+- Only use breadcrumbs for 3+ level hierarchies. For simpler navigation, use a Back button.
+
+## Pagination
+
+Page-based navigation for large datasets.
+
+```tsx
+<div className="flex items-center justify-between">
+  <p className="text-sm text-muted-foreground">Showing 1–10 of 97 results</p>
+  <Pagination :total="97" :sibling-count="1" show-edges :default-page="1">
+    <PaginationContent>
+      <PaginationFirst />
+      <PaginationPrev />
+      <!-- Page buttons are auto-generated -->
+      <PaginationNext />
+      <PaginationLast />
+    </PaginationContent>
+  </Pagination>
+</div>
+```
+
+Place pagination at the bottom of data tables or list views, with a results count on the left.
+
+## Back Button
+
+For detail views, use a ghost button instead of breadcrumbs:
+
+```tsx
+<Button variant="ghost" size="sm" className="gap-1">
+  <ArrowLeft className="w-4 h-4" />
+  Back
+</Button>
+```
+
+## Rules
+- **Breadcrumbs**: Only for 3+ level hierarchies
+- **Back button**: Always present on detail/drill-down views
+- **Tabs**: For related content within a single view (not for navigation between views)
+- **Pagination**: Always show results count alongside page controls

package/skills/components/overlay.md

@@ -0,0 +1,77 @@
+# Sheet, ScrollArea
+
+Overlay and scroll components.
+
+```ts
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter, SheetTrigger, SheetClose } from '@reinvented/design'
+import { ScrollArea } from '@reinvented/design'
+```
+
+## Sheet
+
+Slide-out panel from the edge of the screen. Use for secondary forms, filters, or detail previews that don't warrant a full page.
+
+```tsx
+<Sheet>
+  <SheetTrigger as-child>
+    <Button variant="outline">View Details</Button>
+  </SheetTrigger>
+  <SheetContent side="right" className="w-full max-w-md sm:max-w-lg">
+    <SheetHeader>
+      <SheetTitle>Task Details</SheetTitle>
+      <SheetDescription>View and edit task information.</SheetDescription>
+    </SheetHeader>
+    <div className="space-y-6 py-6">
+      <!-- Content -->
+    </div>
+    <SheetFooter>
+      <SheetClose as-child>
+        <Button variant="outline">Cancel</Button>
+      </SheetClose>
+      <Button>Save Changes</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### Sheet Sides
+| Side | When to Use |
+|------|-------------|
+| `right` | Default. Detail panels, edit forms, filters. |
+| `left` | Mobile navigation drawer. |
+| `bottom` | Mobile action sheets, bottom drawers. |
+| `top` | Rarely used. Notification panels. |
+
+### Sheet vs Dialog
+| Use Case | Component |
+|----------|-----------|
+| Quick form (≤5 fields) | Dialog |
+| Detail panel / preview | Sheet (right) |
+| Complex edit form | Sheet (right, wider) |
+| Mobile navigation | Sheet (left) |
+| Destructive confirmation | AlertDialog |
+
+## ScrollArea
+
+Styled scrollbar container. Use when content might overflow.
+
+```tsx
+<ScrollArea className="h-72">
+  <div className="space-y-4 pr-4">
+    <!-- Scrollable content -->
+  </div>
+</ScrollArea>
+```
+
+### Common Uses
+- Long lists inside fixed-height containers
+- Sidebar navigation that exceeds viewport
+- Modal content that might overflow
+- Code preview areas
+
+### Rules
+- Add `pr-4` to content inside ScrollArea to prevent scrollbar overlapping text
+- **In Normal Containers**: Set an explicit height (`h-72`, `max-h-96`, or use a named size).
+- **In Flex/Grid Containers**: If placed inside a flex column or grid cell that stretches, DO NOT use a fixed height. Instead, ensure the parent has `flex-1 min-h-0` (or `min-w-0`) and make the `ScrollArea` `h-full` to fill the available space dynamically.
+- **Avoid Nested Scrolling**: Never put a vertical `<ScrollArea>` inside a page that also scrolls vertically ("scrolling within scrolling"). If you require an inner scrollable area (like a kanban column), ensure the root wrapper of the view is bounded and cannot scroll (e.g., `h-[100dvh] overflow-hidden`).
+- Use `<ScrollArea>` instead of `overflow-y-auto` for consistent scrollbar styling

package/skills/components/page-header.md

@@ -0,0 +1,51 @@
+# Component: PageHeader
+
+A structured set of components for building consistent, responsive page headers across the application. These prevent common layout errors when switching from desktop (horizontal) to mobile (vertical).
+
+## Components
+
+- `PageHeader`: The outer container. Handles responsive flex flow.
+- `PageHeaderHeading`: Groups the title and description vertically.
+- `PageHeaderTitle`: The main `<h1>`. Handles font scaling from mobile (`text-xl`) to desktop (`text-2xl`).
+- `PageHeaderDescription`: Secondary text below the title.
+- `PageHeaderActions`: The container for buttons. On mobile, elements stack to full width.
+
+## Usage
+
+```tsx
+// React Component
+import {
+  PageHeader,
+  PageHeaderHeading,
+  PageHeaderTitle,
+  PageHeaderDescription,
+  PageHeaderActions,
+  Button
+} from '@reinvented/design'
+// ...
+
+
+export default function Component() {
+  return (
+    <>
+  <PageHeader>
+    <PageHeaderHeading>
+      <PageHeaderTitle>Settings</PageHeaderTitle>
+      <PageHeaderDescription>Manage your account preferences and defaults.</PageHeaderDescription>
+    </PageHeaderHeading>
+    
+    <PageHeaderActions>
+      <Button variant="outline">Cancel</Button>
+      <Button>Save Changes</Button>
+    </PageHeaderActions>
+  </PageHeader>
+    </>
+  )
+}
+```
+
+## Rules
+
+- **Always use these components** instead of raw `<h1>` or `<div>` trees for primary page headers.
+- **Do not manually add sizing classes** to `<PageHeaderTitle>`: it inherently handles the `text-xl sm:text-2xl` scaling.
+- **Do not manually add width classes** to buttons inside `<PageHeaderActions>`: the container handles stretching them on mobile (`w-full`) and sizing them to content on desktop (`sm:w-auto`).

package/skills/components/select.md

@@ -0,0 +1,175 @@
+# Select, Checkbox, Switch, RadioGroup, Slider
+
+Form controls for choosing values.
+
+```ts
+import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue } from '@reinvented/design'
+import { Checkbox } from '@reinvented/design'
+import { Switch } from '@reinvented/design'
+import { RadioGroup, RadioGroupItem } from '@reinvented/design'
+import { Slider } from '@reinvented/design'
+```
+
+## Select
+
+Dropdown for choosing one value from a list. Use when there are 4+ options.
+
+```tsx
+<div className="space-y-2">
+  <Label>Status</Label>
+  <Select defaultValue="status">
+    <SelectTrigger className="w-48">
+      <SelectValue placeholder="Select status" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectGroup>
+        <SelectLabel>Status</SelectLabel>
+        <SelectItem value="active">Active</SelectItem>
+        <SelectItem value="inactive">Inactive</SelectItem>
+        <SelectItem value="pending">Pending</SelectItem>
+      </SelectGroup>
+    </SelectContent>
+  </Select>
+</div>
+```
+
+### Select Width
+- **Filter select** (in toolbar): `w-36` or `w-48`
+- **Form select** (in form): `w-full` (takes full width of form column)
+
+### Grouped Select
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Roles</SelectLabel>
+    <SelectItem value="admin">Admin</SelectItem>
+    <SelectItem value="editor">Editor</SelectItem>
+  </SelectGroup>
+  <SelectGroup>
+    <SelectLabel>Access</SelectLabel>
+    <SelectItem value="viewer">Viewer</SelectItem>
+    <SelectItem value="none">No Access</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+## Checkbox
+
+Boolean toggle with checkmark. Use for multi-select from a set of options.
+
+```tsx
+<div className="flex items-start gap-3">
+  <Checkbox id="terms" v-model:checked="agreed" className="mt-0.5" />
+  <div>
+    <Label for="terms" className="text-sm font-medium">Accept terms</Label>
+    <p className="text-xs text-muted-foreground">You agree to our Terms of Service and Privacy Policy.</p>
+  </div>
+</div>
+```
+
+### Checkbox Group
+```tsx
+<div className="space-y-3">
+  <Label className="text-sm font-medium">Notifications</Label>
+  <div v-for="opt in options" :key="opt.id" className="flex items-center gap-3">
+    <Checkbox :id="opt.id" v-model:checked="opt.enabled" />
+    <Label :for="opt.id" className="text-sm">{{ opt.label }}</Label>
+  </div>
+</div>
+```
+
+## Switch
+
+On/off toggle. Use for boolean settings where the effect is immediate.
+
+```tsx
+<div className="flex items-center justify-between">
+  <div>
+    <p className="text-sm font-medium">Email Notifications</p>
+    <p className="text-xs text-muted-foreground">Receive emails about account activity.</p>
+  </div>
+  <Switch v-model:checked="emailEnabled" />
+</div>
+```
+
+The standard pattern: label/description on the left, Switch on the right, separated by `justify-between`.
+
+## RadioGroup
+
+Single choice from a small set (2–5 options). Use when all options should be visible.
+
+```tsx
+<div className="space-y-3">
+  <Label className="text-sm font-medium">Plan</Label>
+  <RadioGroup defaultValue="plan" className="space-y-2">
+    <div className="flex items-center gap-3">
+      <RadioGroupItem value="free" id="free" />
+      <Label for="free" className="text-sm">Free — $0/month</Label>
+    </div>
+    <div className="flex items-center gap-3">
+      <RadioGroupItem value="pro" id="pro" />
+      <Label for="pro" className="text-sm">Pro — $19/month</Label>
+    </div>
+    <div className="flex items-center gap-3">
+      <RadioGroupItem value="team" id="team" />
+      <Label for="team" className="text-sm">Team — $49/month</Label>
+    </div>
+  </RadioGroup>
+</div>
+```
+
+### Color Swatch Selector (RadioGroup Variant)
+
+For e-commerce or customizable settings, use `RadioGroup` and style the items as color swatches to preserve visual aesthetics and keyboard accessibility.
+
+```tsx
+<div className="space-y-3">
+  <Label className="text-xs font-bold text-muted-foreground uppercase tracking-widest">Theme Color</Label>
+  <RadioGroup defaultValue="activeColor" className="flex items-center gap-3">
+    <RadioGroupItem 
+      v-for="color in colors" 
+      :key="color.id" 
+      :value="color.id"
+      :id="color.id"
+      className="w-8 h-8 rounded-full border border-black/10 dark:border-white/10 shadow-sm transition-all duration-200"
+      className={[
+        color.bgClass, // e.g., 'bg-amber-400'
+        activeColor === color.id ? 'ring-2 ring-offset-2 ring-foreground scale-110 border-transparent' : 'opacity-90 hover:opacity-100 hover:scale-105'
+      ]}
+    />
+  </RadioGroup>
+</div>
+```
+
+> **Warning:** When applying `ring` and `scale` transforms to active elements within collapsible panels, verify the parent container has enough bottom margin/padding (e.g. `pb-2`). Otherwise, strict `overflow-hidden` transitions will clip the focus ring.
+
+## Slider
+
+Numeric range input.
+
+```tsx
+<div className="space-y-3">
+  <div className="flex items-center justify-between">
+    <Label className="text-sm font-medium">Volume</Label>
+    <span className="text-sm text-muted-foreground">{{ volume }}%</span>
+  </div>
+  <Slider defaultValue="volume" :max="100" :step="1" className="w-full" />
+</div>
+```
+
+## Decision Tree
+
+```
+How many options?
+├─ 2 (on/off, yes/no)
+│  ├─ Setting that takes effect immediately? → Switch
+│  └─ Checkbox in a form submission? → Checkbox
+├─ 2–5 (all visible at once)
+│  └─ → RadioGroup
+├─ 4+ (too many for radio buttons)
+│  └─ → Select dropdown
+├─ Multi-select from options
+│  └─ → Checkbox group
+├─ Numeric range
+│  └─ → Slider
+```

package/skills/components/table.md

@@ -0,0 +1,102 @@
+# Table
+
+Data tables for structured, tabular content. Never use raw `<table>`.
+
+```ts
+import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow } from '@reinvented/design'
+```
+
+## Basic Table
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+      <TableHead>Role</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+      <TableHead className="w-10"></TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow v-for="user in users" :key="user.id">
+      <TableCell>
+        <div className="flex items-center gap-3">
+          <div className="w-8 h-8 rounded-full shrink-0 flex items-center justify-center text-xs font-medium bg-muted text-muted-foreground">
+            {{ user.name.split(' ').map(n => n[0]).join('') }}
+          </div>
+          <div className="min-w-0">
+            <p className="text-sm font-medium truncate">{{ user.name }}</p>
+            <p className="text-xs text-muted-foreground truncate">{{ user.email }}</p>
+          </div>
+        </div>
+      </TableCell>
+      <TableCell className="text-muted-foreground">{{ user.email }}</TableCell>
+      <TableCell>{{ user.role }}</TableCell>
+      <TableCell>
+        <Badge :variant="user.status === 'active' ? 'default' : 'secondary'">{{ user.status }}</Badge>
+      </TableCell>
+      <TableCell className="text-right font-medium">${{ user.amount.toLocaleString() }}</TableCell>
+      <TableCell>
+        <DropdownMenu>
+          <DropdownMenuTrigger as-child>
+            <Button variant="ghost" size="icon" className="h-8 w-8">
+              <MoreHorizontal className="w-4 h-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem><Pencil className="w-4 h-4" /> Edit</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem className="text-destructive"><Trash2 className="w-4 h-4" /> Delete</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Column Formatting Rules
+
+| Content Type | Alignment | Class |
+|-------------|-----------|-------|
+| Text (names, descriptions) | Left (default) | — |
+| Numbers, currency, amounts | Right | `className="text-right"` |
+| Status badges | Left | — |
+| Dates | Left | `className="text-muted-foreground"` |
+| Actions (menu) | Right | `className="w-10"` on the head |
+| Primary identifier (name) | Left | `className="font-medium"` |
+
+## Empty Table
+
+```tsx
+<TableBody>
+  <TableRow v-if="items.length === 0">
+    <TableCell :colspan="columns.length" className="h-32 text-center text-muted-foreground">
+      No results found.
+    </TableCell>
+  </TableRow>
+</TableBody>
+```
+
+## Table with Selection
+
+```tsx
+<TableHead className="w-10">
+  <Checkbox :checked="allSelected" @update:checked="toggleAll" />
+</TableHead>
+<!-- ... -->
+<TableCell>
+  <Checkbox :checked="selectedIds.includes(user.id)" @update:checked="toggleUser(user.id)" />
+</TableCell>
+```
+
+## Rules
+- **Primary identifier column**: Use `font-medium` on the main entity name
+- **Right-align numbers**: All currency, amounts, counts use `text-right`
+- **Actions column**: Always last. Use `w-10` on `TableHead` and a three-dot `DropdownMenu`
+- **Row count**: Show 5–8 rows for realistic density. Not 2, not 20.
+- **Wrap in Card**: Data tables should typically be inside a `Card` for containment. When wrapping in a Card, note that the `CardHeader` has 24px horizontal padding, but `Table` cells default to 16px. To visually align the table headers and values with the card title, always add `className="pl-6"` to the first `TableHead` and `TableCell`, and `className="pr-6"` to the last `TableHead` and `TableCell`.
+- **Always include a `TableHeader`**: Even if columns seem obvious.