@fr0mpy/component-system 2.0.0

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

@@ -0,0 +1,254 @@
+# Context Menu Component Recipe
+
+## Structure
+- Right-click triggered menu
+- Same item types as Dropdown Menu
+- Support for submenus
+- Keyboard shortcuts display
+- Checkboxes and radio items
+
+## Tailwind Classes
+
+### Trigger (wrapper around target element)
+```
+(invisible wrapper, no styles)
+```
+
+### Content
+```
+z-50 min-w-[8rem] overflow-hidden {tokens.radius} border border-border
+bg-background p-1 text-foreground {tokens.shadow}
+animate-in fade-in-80
+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
+focus:bg-muted focus:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Item with Inset (for alignment with checkbox items)
+```
+pl-8
+```
+
+### 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
+```
+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}
+data-[state=open]:animate-in data-[state=closed]:animate-out
+```
+
+## Props Interface
+```typescript
+interface ContextMenuProps {
+  children: React.ReactNode
+  onOpenChange?: (open: boolean) => void
+}
+
+interface ContextMenuTriggerProps {
+  children: React.ReactNode
+  disabled?: boolean
+  asChild?: boolean
+}
+
+interface ContextMenuContentProps {
+  className?: string
+  alignOffset?: number
+  children: React.ReactNode
+}
+
+interface ContextMenuItemProps {
+  inset?: boolean
+  disabled?: boolean
+  onSelect?: () => void
+  children: React.ReactNode
+}
+
+// Same as DropdownMenu for CheckboxItem, RadioGroup, RadioItem, etc.
+```
+
+## Do
+- Use Radix ContextMenu for accessibility
+- Support all item types (checkbox, radio, sub-menus)
+- Show keyboard shortcuts
+- Handle touch devices (long-press)
+
+## Don't
+- Hardcode colors
+- Use for primary navigation
+- Forget disabled states
+- Skip keyboard navigation
+
+## Example
+```tsx
+import * as ContextMenuPrimitive from '@radix-ui/react-context-menu'
+import { Check, ChevronRight, Circle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const ContextMenu = ContextMenuPrimitive.Root
+const ContextMenuTrigger = ContextMenuPrimitive.Trigger
+const ContextMenuGroup = ContextMenuPrimitive.Group
+const ContextMenuPortal = ContextMenuPrimitive.Portal
+const ContextMenuSub = ContextMenuPrimitive.Sub
+const ContextMenuRadioGroup = ContextMenuPrimitive.RadioGroup
+
+const ContextMenuContent = ({ className, ...props }) => (
+  <ContextMenuPrimitive.Portal>
+    <ContextMenuPrimitive.Content
+      className={cn(
+        'z-50 min-w-[8rem] overflow-hidden rounded-md border border-border bg-background p-1 shadow-md',
+        'animate-in fade-in-80',
+        '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}
+    />
+  </ContextMenuPrimitive.Portal>
+)
+
+const ContextMenuItem = ({ className, inset, ...props }) => (
+  <ContextMenuPrimitive.Item
+    className={cn(
+      'relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none',
+      'focus:bg-muted focus:text-foreground',
+      'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      inset && 'pl-8',
+      className
+    )}
+    {...props}
+  />
+)
+
+const ContextMenuCheckboxItem = ({ className, checked, children, ...props }) => (
+  <ContextMenuPrimitive.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">
+      <ContextMenuPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </ContextMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </ContextMenuPrimitive.CheckboxItem>
+)
+
+const ContextMenuRadioItem = ({ className, children, ...props }) => (
+  <ContextMenuPrimitive.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">
+      <ContextMenuPrimitive.ItemIndicator>
+        <Circle className="h-2 w-2 fill-current" />
+      </ContextMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </ContextMenuPrimitive.RadioItem>
+)
+
+const ContextMenuLabel = ({ className, inset, ...props }) => (
+  <ContextMenuPrimitive.Label
+    className={cn('px-2 py-1.5 text-sm font-semibold text-foreground', inset && 'pl-8', className)}
+    {...props}
+  />
+)
+
+const ContextMenuSeparator = ({ className, ...props }) => (
+  <ContextMenuPrimitive.Separator className={cn('-mx-1 my-1 h-px bg-border', className)} {...props} />
+)
+
+const ContextMenuShortcut = ({ className, ...props }) => (
+  <span className={cn('ml-auto text-xs tracking-widest text-muted-foreground', className)} {...props} />
+)
+
+// Usage
+<ContextMenu>
+  <ContextMenuTrigger className="flex h-32 w-full items-center justify-center rounded-md border border-dashed">
+    Right click here
+  </ContextMenuTrigger>
+  <ContextMenuContent className="w-64">
+    <ContextMenuItem>
+      Back
+      <ContextMenuShortcut>⌘[</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem disabled>
+      Forward
+      <ContextMenuShortcut>⌘]</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuCheckboxItem checked>
+      Show Bookmarks
+      <ContextMenuShortcut>⌘⇧B</ContextMenuShortcut>
+    </ContextMenuCheckboxItem>
+  </ContextMenuContent>
+</ContextMenu>
+```

package/templates/component-recipes/dialog.md

@@ -0,0 +1,193 @@
+# Dialog Component Recipe
+
+## Structure
+- Same as Modal but semantically for confirmations/actions
+- Typically smaller, more focused
+- Usually has cancel + confirm actions
+- Used for alerts, confirmations, forms
+
+## Tailwind Classes
+
+### Overlay
+```
+fixed inset-0 z-50 bg-black/80
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0
+```
+
+### Content
+```
+fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2
+gap-4 border border-border bg-background p-6 {tokens.shadow} {tokens.radius}
+duration-200
+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-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%]
+data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%]
+```
+
+### Header
+```
+flex flex-col space-y-1.5 text-center sm:text-left
+```
+
+### Footer
+```
+flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2
+```
+
+### Title
+```
+text-lg font-semibold leading-none tracking-tight
+```
+
+### Description
+```
+text-sm text-muted-foreground
+```
+
+### Close Button
+```
+absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background
+transition-opacity hover:opacity-100
+focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2
+disabled:pointer-events-none
+data-[state=open]:bg-accent data-[state=open]:text-muted-foreground
+```
+
+## Alert Dialog Variant (for destructive confirmations)
+```
+Same structure but:
+- No close button (must make explicit choice)
+- Cannot close by clicking overlay
+- Destructive action uses destructive button variant
+```
+
+## Props Interface
+```typescript
+interface DialogProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  children: React.ReactNode
+}
+
+interface DialogContentProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DialogHeaderProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DialogFooterProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DialogTitleProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DialogDescriptionProps {
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use for focused interactions requiring user decision
+- Include clear action buttons
+- Use AlertDialog for destructive actions
+- Focus first interactive element on open
+
+## Don't
+- Hardcode colors
+- Use for complex multi-step flows (use full modal)
+- Allow dismissal of AlertDialog by clicking outside
+- Forget keyboard navigation
+
+## Example
+```tsx
+import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Dialog = DialogPrimitive.Root
+const DialogTrigger = DialogPrimitive.Trigger
+const DialogPortal = DialogPrimitive.Portal
+const DialogClose = DialogPrimitive.Close
+
+const DialogOverlay = ({ className, ...props }) => (
+  <DialogPrimitive.Overlay
+    className={cn(
+      'fixed inset-0 z-50 bg-black/80',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      className
+    )}
+    {...props}
+  />
+)
+
+const DialogContent = ({ className, children, ...props }) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      className={cn(
+        'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2',
+        'gap-4 border border-border bg-background p-6 shadow-lg rounded-lg duration-200',
+        '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',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-primary">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DialogPortal>
+)
+
+const DialogHeader = ({ className, ...props }) => (
+  <div className={cn('flex flex-col space-y-1.5 text-center sm:text-left', className)} {...props} />
+)
+
+const DialogFooter = ({ className, ...props }) => (
+  <div className={cn('flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2', className)} {...props} />
+)
+
+const DialogTitle = ({ className, ...props }) => (
+  <DialogPrimitive.Title className={cn('text-lg font-semibold leading-none tracking-tight', className)} {...props} />
+)
+
+const DialogDescription = ({ className, ...props }) => (
+  <DialogPrimitive.Description className={cn('text-sm text-muted-foreground', className)} {...props} />
+)
+
+// Usage
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Edit Profile</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Edit profile</DialogTitle>
+      <DialogDescription>Make changes to your profile here.</DialogDescription>
+    </DialogHeader>
+    <div className="grid gap-4 py-4">
+      {/* Form fields */}
+    </div>
+    <DialogFooter>
+      <Button type="submit">Save changes</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```

package/templates/component-recipes/drawer.md

@@ -0,0 +1,196 @@
+# Drawer Component Recipe
+
+## Structure
+- Slide-out panel from edge of screen
+- Support for left, right, top, bottom positions
+- Overlay backdrop
+- Optional close button
+- Content area with header/body/footer
+
+## Tailwind Classes
+
+### Overlay
+```
+fixed inset-0 z-50 bg-black/80
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0
+```
+
+### Content (Base)
+```
+fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:duration-300 data-[state=open]:duration-500
+```
+
+### Position Variants
+```
+left:
+  inset-y-0 left-0 h-full w-3/4 sm:max-w-sm border-r border-border
+  data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left
+
+right:
+  inset-y-0 right-0 h-full w-3/4 sm:max-w-sm border-l border-border
+  data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right
+
+top:
+  inset-x-0 top-0 border-b border-border
+  data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top
+
+bottom:
+  inset-x-0 bottom-0 border-t border-border
+  data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom
+```
+
+### Header
+```
+flex flex-col space-y-2
+```
+
+### Title
+```
+text-lg font-semibold text-foreground
+```
+
+### Description
+```
+text-sm text-muted-foreground
+```
+
+### Footer
+```
+flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2
+```
+
+### Close Button
+```
+absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background
+transition-opacity hover:opacity-100
+focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
+```
+
+## Props Interface
+```typescript
+interface DrawerProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: 'left' | 'right' | 'top' | 'bottom'
+  children: React.ReactNode
+}
+
+interface DrawerContentProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DrawerHeaderProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DrawerTitleProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DrawerDescriptionProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface DrawerFooterProps {
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use Radix Dialog as base (or vaul for mobile-friendly)
+- Trap focus within drawer when open
+- Close on Escape key
+- Close on overlay click
+- Support swipe-to-close on mobile
+
+## Don't
+- Hardcode colors or dimensions
+- Forget scroll handling (body scroll lock)
+- Skip keyboard accessibility
+- Allow content behind to be interactive
+
+## Example
+```tsx
+import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Drawer = DialogPrimitive.Root
+const DrawerTrigger = DialogPrimitive.Trigger
+const DrawerClose = DialogPrimitive.Close
+const DrawerPortal = DialogPrimitive.Portal
+
+const drawerSideVariants = {
+  left: 'inset-y-0 left-0 h-full w-3/4 sm:max-w-sm border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left',
+  right: 'inset-y-0 right-0 h-full w-3/4 sm:max-w-sm border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right',
+  top: 'inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top',
+  bottom: 'inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom',
+}
+
+const DrawerOverlay = ({ className, ...props }) => (
+  <DialogPrimitive.Overlay
+    className={cn(
+      'fixed inset-0 z-50 bg-black/80',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      className
+    )}
+    {...props}
+  />
+)
+
+const DrawerContent = ({ side = 'right', className, children, ...props }) => (
+  <DrawerPortal>
+    <DrawerOverlay />
+    <DialogPrimitive.Content
+      className={cn(
+        'fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out',
+        'data-[state=closed]:duration-300 data-[state=open]:duration-500',
+        drawerSideVariants[side],
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-primary">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DrawerPortal>
+)
+
+const DrawerHeader = ({ className, ...props }) => (
+  <div className={cn('flex flex-col space-y-2', className)} {...props} />
+)
+
+const DrawerTitle = ({ className, ...props }) => (
+  <DialogPrimitive.Title
+    className={cn('text-lg font-semibold text-foreground', className)}
+    {...props}
+  />
+)
+
+const DrawerDescription = ({ className, ...props }) => (
+  <DialogPrimitive.Description
+    className={cn('text-sm text-muted-foreground', className)}
+    {...props}
+  />
+)
+
+const DrawerFooter = ({ className, ...props }) => (
+  <div
+    className={cn('flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2', className)}
+    {...props}
+  />
+)
+```