@fr0mpy/component-system 2.0.0

package/templates/component-recipes/dropdown-menu.md

@@ -0,0 +1,263 @@
+# Dropdown Menu Component Recipe
+
+## Structure
+- Trigger button/element
+- Menu content with items
+- Support for submenus
+- Checkboxes and radio items
+- Keyboard navigation
+- Separators and labels
+
+## Tailwind Classes
+
+### Content
+```
+z-50 min-w-[8rem] overflow-hidden {tokens.radius} border border-border
+bg-background p-1 text-foreground {tokens.shadow}
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0
+data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95
+data-[side=bottom]:slide-in-from-top-2
+data-[side=left]:slide-in-from-right-2
+data-[side=right]:slide-in-from-left-2
+data-[side=top]:slide-in-from-bottom-2
+```
+
+### Item
+```
+relative flex cursor-pointer select-none items-center {tokens.radius} px-2 py-1.5
+text-sm outline-none
+transition-colors
+focus:bg-muted focus:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Item with Icon
+```
+[&>svg]:mr-2 [&>svg]:h-4 [&>svg]:w-4
+```
+
+### Checkbox Item
+```
+relative flex cursor-pointer select-none items-center {tokens.radius} py-1.5 pl-8 pr-2
+text-sm outline-none
+focus:bg-muted focus:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Radio Item
+```
+relative flex cursor-pointer select-none items-center {tokens.radius} py-1.5 pl-8 pr-2
+text-sm outline-none
+focus:bg-muted focus:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Item Indicator (check/radio)
+```
+absolute left-2 flex h-3.5 w-3.5 items-center justify-center
+```
+
+### Label
+```
+px-2 py-1.5 text-sm font-semibold text-foreground
+```
+
+### Separator
+```
+-mx-1 my-1 h-px bg-border
+```
+
+### Shortcut
+```
+ml-auto text-xs tracking-widest text-muted-foreground
+```
+
+### Sub Trigger
+```
+flex cursor-pointer select-none items-center {tokens.radius} px-2 py-1.5
+text-sm outline-none
+focus:bg-muted
+data-[state=open]:bg-muted
+```
+
+### Sub Content
+```
+z-50 min-w-[8rem] overflow-hidden {tokens.radius} border border-border
+bg-background p-1 {tokens.shadow}
+```
+
+## Props Interface
+```typescript
+interface DropdownMenuProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  modal?: boolean
+  children: React.ReactNode
+}
+
+interface DropdownMenuItemProps {
+  disabled?: boolean
+  onSelect?: () => void
+  children: React.ReactNode
+}
+
+interface DropdownMenuCheckboxItemProps {
+  checked?: boolean
+  onCheckedChange?: (checked: boolean) => void
+  disabled?: boolean
+  children: React.ReactNode
+}
+
+interface DropdownMenuRadioGroupProps {
+  value?: string
+  onValueChange?: (value: string) => void
+  children: React.ReactNode
+}
+
+interface DropdownMenuRadioItemProps {
+  value: string
+  disabled?: boolean
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use Radix DropdownMenu for accessibility
+- Support keyboard navigation (arrows, enter, escape)
+- Include focus management
+- Support nested submenus
+
+## Don't
+- Hardcode colors
+- Forget keyboard shortcuts display
+- Skip disabled state handling
+- Use for navigation (use NavigationMenu)
+
+## Example
+```tsx
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'
+import { Check, ChevronRight, Circle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const DropdownMenu = DropdownMenuPrimitive.Root
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
+const DropdownMenuGroup = DropdownMenuPrimitive.Group
+const DropdownMenuPortal = DropdownMenuPrimitive.Portal
+const DropdownMenuSub = DropdownMenuPrimitive.Sub
+const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup
+
+const DropdownMenuContent = ({ className, sideOffset = 4, ...props }) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 min-w-[8rem] overflow-hidden rounded-md border border-border bg-background p-1 shadow-md',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out',
+        'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+        'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+        'data-[side=bottom]:slide-in-from-top-2',
+        className
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+)
+
+const DropdownMenuItem = ({ className, inset, ...props }) => (
+  <DropdownMenuPrimitive.Item
+    className={cn(
+      'relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none',
+      'transition-colors focus:bg-muted focus:text-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  />
+)
+
+const DropdownMenuCheckboxItem = ({ className, checked, children, ...props }) => (
+  <DropdownMenuPrimitive.CheckboxItem
+    className={cn(
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none',
+      'focus:bg-muted focus:text-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    checked={checked}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.CheckboxItem>
+)
+
+const DropdownMenuRadioItem = ({ className, children, ...props }) => (
+  <DropdownMenuPrimitive.RadioItem
+    className={cn(
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none',
+      'focus:bg-muted focus:text-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Circle className="h-2 w-2 fill-current" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.RadioItem>
+)
+
+const DropdownMenuLabel = ({ className, inset, ...props }) => (
+  <DropdownMenuPrimitive.Label
+    className={cn('px-2 py-1.5 text-sm font-semibold', inset && 'pl-8', className)}
+    {...props}
+  />
+)
+
+const DropdownMenuSeparator = ({ className, ...props }) => (
+  <DropdownMenuPrimitive.Separator
+    className={cn('-mx-1 my-1 h-px bg-border', className)}
+    {...props}
+  />
+)
+
+const DropdownMenuShortcut = ({ className, ...props }) => (
+  <span className={cn('ml-auto text-xs tracking-widest text-muted-foreground', className)} {...props} />
+)
+
+const DropdownMenuSubTrigger = ({ className, inset, children, ...props }) => (
+  <DropdownMenuPrimitive.SubTrigger
+    className={cn(
+      'flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none',
+      'focus:bg-muted data-[state=open]:bg-muted',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto h-4 w-4" />
+  </DropdownMenuPrimitive.SubTrigger>
+)
+
+const DropdownMenuSubContent = ({ className, ...props }) => (
+  <DropdownMenuPrimitive.SubContent
+    className={cn(
+      'z-50 min-w-[8rem] overflow-hidden rounded-md border border-border bg-background p-1 shadow-lg',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      className
+    )}
+    {...props}
+  />
+)
+```

package/templates/component-recipes/hover-card.md

@@ -0,0 +1,230 @@
+# Hover Card Component Recipe
+
+## Structure
+- Trigger element (usually a link or button)
+- Floating card that appears on hover
+- Arrow pointing to trigger
+- Rich content support (images, text, actions)
+- Delay before showing/hiding
+
+## Tailwind Classes
+
+### Content
+```
+z-50 w-64 {tokens.radius} border border-border bg-background p-4 text-foreground {tokens.shadow}
+outline-none
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0
+data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95
+data-[side=bottom]:slide-in-from-top-2
+data-[side=left]:slide-in-from-right-2
+data-[side=right]:slide-in-from-left-2
+data-[side=top]:slide-in-from-bottom-2
+```
+
+### Arrow
+```
+fill-background
+```
+
+### Arrow with Border
+```
+fill-background stroke-border
+```
+
+### User Card Layout
+```
+Container: flex flex-col gap-4
+Avatar section: flex items-center gap-4
+Info section: space-y-1
+Stats section: flex gap-4 pt-2
+```
+
+### Link Preview Layout
+```
+Container: space-y-3
+Image: aspect-video w-full rounded-md object-cover
+Title: font-medium leading-none
+Description: text-sm text-muted-foreground line-clamp-2
+```
+
+## Props Interface
+```typescript
+interface HoverCardProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+  openDelay?: number // default 700ms
+  closeDelay?: number // default 300ms
+  children: React.ReactNode
+}
+
+interface HoverCardTriggerProps {
+  asChild?: boolean
+  children: React.ReactNode
+}
+
+interface HoverCardContentProps {
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  sideOffset?: number
+  align?: 'start' | 'center' | 'end'
+  alignOffset?: number
+  className?: string
+  children: React.ReactNode
+}
+
+interface HoverCardArrowProps {
+  className?: string
+  width?: number
+  height?: number
+}
+```
+
+## Configuration
+- Default open delay: 700ms (prevents accidental triggers)
+- Default close delay: 300ms (allows moving to card)
+- Supports collision detection
+
+## Do
+- Use for supplementary, non-essential information
+- Keep content scannable (not too much)
+- Include visual hierarchy in content
+- Support touch devices with click fallback
+
+## Don't
+- Use for critical information (use tooltip or inline)
+- Put interactive forms inside
+- Use too short delay (annoying)
+- Block content underneath
+
+## Example
+```tsx
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card'
+import { cn } from '@/lib/utils'
+
+const HoverCard = HoverCardPrimitive.Root
+const HoverCardTrigger = HoverCardPrimitive.Trigger
+
+const HoverCardContent = ({
+  className,
+  align = 'center',
+  sideOffset = 4,
+  ...props
+}) => (
+  <HoverCardPrimitive.Content
+    align={align}
+    sideOffset={sideOffset}
+    className={cn(
+      'z-50 w-64 rounded-lg border border-border bg-background p-4 shadow-md outline-none',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+      'data-[side=bottom]:slide-in-from-top-2',
+      'data-[side=left]:slide-in-from-right-2',
+      'data-[side=right]:slide-in-from-left-2',
+      'data-[side=top]:slide-in-from-bottom-2',
+      className
+    )}
+    {...props}
+  />
+)
+
+const HoverCardArrow = ({ className, ...props }) => (
+  <HoverCardPrimitive.Arrow
+    className={cn('fill-background', className)}
+    {...props}
+  />
+)
+
+// User profile card
+const UserHoverCard = ({ user, children }) => (
+  <HoverCard>
+    <HoverCardTrigger asChild>{children}</HoverCardTrigger>
+    <HoverCardContent className="w-80">
+      <div className="flex justify-between space-x-4">
+        <Avatar>
+          <AvatarImage src={user.avatar} />
+          <AvatarFallback>{user.initials}</AvatarFallback>
+        </Avatar>
+        <div className="space-y-1">
+          <h4 className="text-sm font-semibold">{user.name}</h4>
+          <p className="text-sm text-muted-foreground">@{user.username}</p>
+          <p className="text-sm">{user.bio}</p>
+          <div className="flex items-center pt-2">
+            <span className="text-xs text-muted-foreground">
+              Joined {user.joinedDate}
+            </span>
+          </div>
+        </div>
+      </div>
+      <HoverCardArrow />
+    </HoverCardContent>
+  </HoverCard>
+)
+
+// Link preview card
+const LinkHoverCard = ({ url, title, description, image, children }) => (
+  <HoverCard>
+    <HoverCardTrigger asChild>{children}</HoverCardTrigger>
+    <HoverCardContent className="w-80">
+      <div className="space-y-3">
+        {image && (
+          <img
+            src={image}
+            alt={title}
+            className="aspect-video w-full rounded-md object-cover"
+          />
+        )}
+        <div className="space-y-1">
+          <h4 className="text-sm font-semibold leading-none">{title}</h4>
+          <p className="text-sm text-muted-foreground line-clamp-2">
+            {description}
+          </p>
+          <p className="text-xs text-muted-foreground">{url}</p>
+        </div>
+      </div>
+      <HoverCardArrow />
+    </HoverCardContent>
+  </HoverCard>
+)
+
+// Product preview card
+const ProductHoverCard = ({ product, children }) => (
+  <HoverCard>
+    <HoverCardTrigger asChild>{children}</HoverCardTrigger>
+    <HoverCardContent className="w-72">
+      <div className="space-y-3">
+        <img
+          src={product.image}
+          alt={product.name}
+          className="aspect-square w-full rounded-md object-cover"
+        />
+        <div className="space-y-1">
+          <div className="flex items-center justify-between">
+            <h4 className="font-medium">{product.name}</h4>
+            <span className="font-semibold">${product.price}</span>
+          </div>
+          <p className="text-sm text-muted-foreground line-clamp-2">
+            {product.description}
+          </p>
+          <div className="flex items-center gap-1">
+            {Array.from({ length: 5 }).map((_, i) => (
+              <Star
+                key={i}
+                className={cn(
+                  'h-3 w-3',
+                  i < product.rating ? 'fill-yellow-400 text-yellow-400' : 'text-muted'
+                )}
+              />
+            ))}
+            <span className="text-xs text-muted-foreground">
+              ({product.reviewCount})
+            </span>
+          </div>
+        </div>
+      </div>
+      <HoverCardArrow />
+    </HoverCardContent>
+  </HoverCard>
+)
+```

package/templates/component-recipes/input.md

@@ -0,0 +1,113 @@
+# Input Component Recipe
+
+## Structure
+- Use `<input>` element
+- Support common types: text, email, password, number, search, tel, url
+- Include states: disabled, error, with icon
+- Optionally wrap with label and error message
+
+## Tailwind Classes
+
+### Base Input
+```
+flex h-10 w-full {tokens.radius} border border-border bg-background px-3 py-2
+text-sm text-foreground placeholder:text-muted-foreground
+transition-colors
+focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
+disabled:cursor-not-allowed disabled:opacity-50
+```
+
+### Error State
+```
+border-destructive focus:ring-destructive
+```
+
+### With Icon (left)
+```
+pl-10
+Icon wrapper: absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground
+```
+
+### With Icon (right)
+```
+pr-10
+Icon wrapper: absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground
+```
+
+## Props Interface
+```typescript
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: boolean
+  errorMessage?: string
+  label?: string
+  leftIcon?: React.ReactNode
+  rightIcon?: React.ReactNode
+}
+```
+
+## Wrapper Components
+
+### InputWrapper (with label and error)
+```tsx
+<div className="space-y-2">
+  {label && <Label htmlFor={id}>{label}</Label>}
+  <Input ... />
+  {errorMessage && <p className="text-sm text-destructive">{errorMessage}</p>}
+</div>
+```
+
+## Do
+- Use `bg-background` for input background
+- Include `placeholder:text-muted-foreground`
+- Add focus ring with primary color
+- Support error states with destructive color
+- Use relative/absolute for icon positioning
+
+## Don't
+- Hardcode colors
+- Forget focus states
+- Skip placeholder styling
+- Use fixed widths (default to `w-full`)
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+import { forwardRef } from 'react'
+
+const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type = 'text', error, leftIcon, rightIcon, ...props }, ref) => {
+    return (
+      <div className="relative">
+        {leftIcon && (
+          <div className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground">
+            {leftIcon}
+          </div>
+        )}
+        <input
+          type={type}
+          className={cn(
+            'flex h-10 w-full rounded-lg border border-border bg-background px-3 py-2',
+            'text-sm text-foreground placeholder:text-muted-foreground',
+            'transition-colors',
+            'focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2',
+            'disabled:cursor-not-allowed disabled:opacity-50',
+            error && 'border-destructive focus:ring-destructive',
+            leftIcon && 'pl-10',
+            rightIcon && 'pr-10',
+            className
+          )}
+          ref={ref}
+          {...props}
+        />
+        {rightIcon && (
+          <div className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground">
+            {rightIcon}
+          </div>
+        )}
+      </div>
+    )
+  }
+)
+
+Input.displayName = 'Input'
+```