@fr0mpy/component-system 2.0.0

package/templates/component-recipes/toast.md

@@ -0,0 +1,209 @@
+# Toast/Notification Component Recipe
+
+## Structure
+- Viewport container (fixed position, stacks toasts)
+- Individual toast with title, description, action
+- Auto-dismiss with progress indicator (optional)
+- Support variants: default, success, error, warning
+
+## Tailwind Classes
+
+### Viewport (container for all toasts)
+```
+fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4
+sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]
+```
+
+### Toast
+```
+group pointer-events-auto relative flex w-full items-center justify-between space-x-2
+overflow-hidden {tokens.radius} border border-border p-4 pr-6 {tokens.shadow}
+transition-all
+data-[swipe=cancel]:translate-x-0
+data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)]
+data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)]
+data-[swipe=move]:transition-none
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[swipe=end]:animate-out
+data-[state=closed]:fade-out-80
+data-[state=closed]:slide-out-to-right-full
+data-[state=open]:slide-in-from-top-full
+data-[state=open]:sm:slide-in-from-bottom-full
+```
+
+### Variants
+```
+default:     bg-background text-foreground
+success:     bg-green-500 text-white border-green-600
+error:       bg-destructive text-destructive-foreground border-destructive
+warning:     bg-yellow-500 text-white border-yellow-600
+```
+
+### Title
+```
+text-sm font-semibold [&+div]:text-xs
+```
+
+### Description
+```
+text-sm opacity-90
+```
+
+### Action Button
+```
+inline-flex h-8 shrink-0 items-center justify-center {tokens.radius}
+border border-border bg-transparent px-3 text-sm font-medium
+transition-colors hover:bg-secondary
+focus:outline-none focus:ring-1 focus:ring-ring
+disabled:pointer-events-none disabled:opacity-50
+group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30
+group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground
+group-[.destructive]:focus:ring-destructive
+```
+
+### Close Button
+```
+absolute right-1 top-1 rounded-md p-1 text-foreground/50
+opacity-0 transition-opacity hover:text-foreground
+focus:opacity-100 focus:outline-none focus:ring-1
+group-hover:opacity-100
+group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50
+group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600
+```
+
+## Props Interface
+```typescript
+interface ToastProps {
+  id: string
+  title?: string
+  description?: string
+  action?: React.ReactNode
+  variant?: 'default' | 'success' | 'error' | 'warning'
+  duration?: number
+  onOpenChange?: (open: boolean) => void
+}
+
+interface ToastActionProps {
+  altText: string
+  onClick: () => void
+  children: React.ReactNode
+}
+
+// Hook interface
+function useToast(): {
+  toast: (props: Omit<ToastProps, 'id'>) => void
+  dismiss: (id?: string) => void
+  toasts: ToastProps[]
+}
+```
+
+## Do
+- Use a toast provider at app root
+- Support swipe-to-dismiss on mobile
+- Include close button
+- Use appropriate variant for context
+- Limit visible toasts (3-5 max)
+
+## Don't
+- Hardcode colors
+- Skip auto-dismiss (except for errors)
+- Use for critical information (use Alert)
+- Stack too many toasts
+
+## Example
+```tsx
+import * as ToastPrimitives from '@radix-ui/react-toast'
+import { X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const ToastProvider = ToastPrimitives.Provider
+
+const ToastViewport = ({ className, ...props }) => (
+  <ToastPrimitives.Viewport
+    className={cn(
+      'fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4',
+      'sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]',
+      className
+    )}
+    {...props}
+  />
+)
+
+const toastVariants = {
+  default: 'bg-background text-foreground border-border',
+  success: 'bg-green-500 text-white border-green-600',
+  error: 'bg-destructive text-destructive-foreground border-destructive',
+  warning: 'bg-yellow-500 text-white border-yellow-600',
+}
+
+const Toast = ({ className, variant = 'default', ...props }) => (
+  <ToastPrimitives.Root
+    className={cn(
+      'group pointer-events-auto relative flex w-full items-center justify-between space-x-2',
+      'overflow-hidden rounded-lg border p-4 pr-6 shadow-lg transition-all',
+      'data-[swipe=cancel]:translate-x-0',
+      'data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)]',
+      'data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)]',
+      'data-[swipe=move]:transition-none',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      'data-[swipe=end]:animate-out data-[state=closed]:fade-out-80',
+      'data-[state=closed]:slide-out-to-right-full',
+      'data-[state=open]:slide-in-from-top-full',
+      'data-[state=open]:sm:slide-in-from-bottom-full',
+      toastVariants[variant],
+      className
+    )}
+    {...props}
+  />
+)
+
+const ToastAction = ({ className, ...props }) => (
+  <ToastPrimitives.Action
+    className={cn(
+      'inline-flex h-8 shrink-0 items-center justify-center rounded-md',
+      'border bg-transparent px-3 text-sm font-medium',
+      'hover:bg-secondary focus:outline-none focus:ring-1',
+      className
+    )}
+    {...props}
+  />
+)
+
+const ToastClose = ({ className, ...props }) => (
+  <ToastPrimitives.Close
+    className={cn(
+      'absolute right-1 top-1 rounded-md p-1 text-foreground/50',
+      'opacity-0 transition-opacity hover:text-foreground',
+      'focus:opacity-100 focus:outline-none group-hover:opacity-100',
+      className
+    )}
+    {...props}
+  >
+    <X className="h-4 w-4" />
+  </ToastPrimitives.Close>
+)
+
+const ToastTitle = ({ className, ...props }) => (
+  <ToastPrimitives.Title className={cn('text-sm font-semibold', className)} {...props} />
+)
+
+const ToastDescription = ({ className, ...props }) => (
+  <ToastPrimitives.Description className={cn('text-sm opacity-90', className)} {...props} />
+)
+
+// Usage with hook
+const { toast } = useToast()
+
+toast({
+  title: 'Success!',
+  description: 'Your changes have been saved.',
+  variant: 'success',
+})
+
+toast({
+  title: 'Error',
+  description: 'Something went wrong.',
+  variant: 'error',
+  action: <ToastAction altText="Try again" onClick={retry}>Try again</ToastAction>,
+})
+```

package/templates/component-recipes/toggle-group.md

@@ -0,0 +1,216 @@
+# Toggle Group Component Recipe
+
+## Structure
+- Group of toggle buttons
+- Single or multiple selection modes
+- Mutually exclusive options (single) or multi-select (multiple)
+- Often used for view switchers, formatting options, filters
+
+## Tailwind Classes
+
+### Container
+```
+inline-flex items-center justify-center {tokens.radius} bg-muted p-1
+```
+
+### Item (Base)
+```
+inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5
+text-sm font-medium ring-offset-background transition-all
+focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2
+disabled:pointer-events-none disabled:opacity-50
+```
+
+### Item States
+```
+Default: text-muted-foreground hover:bg-background/50 hover:text-foreground
+Active: bg-background text-foreground shadow-sm
+```
+
+### Variant: Outline
+```
+Container: inline-flex items-center rounded-lg border border-border
+Item: border-r border-border last:border-r-0
+Item Active: bg-muted
+```
+
+### Sizes
+```
+sm: h-8 px-2.5 text-xs
+md: h-9 px-3 text-sm (default)
+lg: h-10 px-4 text-sm
+```
+
+### With Icons
+```
+Item: gap-2
+Icon: h-4 w-4
+```
+
+### Full Width
+```
+Container: flex w-full
+Item: flex-1
+```
+
+## Props Interface
+```typescript
+interface ToggleGroupProps {
+  type: 'single' | 'multiple'
+  value?: string | string[]
+  defaultValue?: string | string[]
+  onValueChange?: (value: string | string[]) => void
+  disabled?: boolean
+  className?: string
+  children: React.ReactNode
+}
+
+interface ToggleGroupItemProps {
+  value: string
+  disabled?: boolean
+  className?: string
+  children: React.ReactNode
+}
+
+// Single selection
+interface ToggleGroupSingleProps {
+  type: 'single'
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string) => void
+}
+
+// Multiple selection
+interface ToggleGroupMultipleProps {
+  type: 'multiple'
+  value?: string[]
+  defaultValue?: string[]
+  onValueChange?: (value: string[]) => void
+}
+```
+
+## Do
+- Use Radix ToggleGroup primitive
+- Clearly indicate selected state
+- Support keyboard navigation
+- Include proper ARIA attributes
+- Group related options logically
+
+## Don't
+- Hardcode colors or dimensions
+- Mix toggle group with regular buttons
+- Use for navigation (use tabs or nav)
+- Forget disabled states
+
+## Example
+```tsx
+import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'
+import { cn } from '@/lib/utils'
+
+const ToggleGroup = ({ className, variant = 'default', size = 'md', ...props }) => (
+  <ToggleGroupPrimitive.Root
+    className={cn(
+      'inline-flex items-center justify-center rounded-lg',
+      variant === 'default' && 'bg-muted p-1',
+      variant === 'outline' && 'border border-border',
+      className
+    )}
+    {...props}
+  />
+)
+
+const toggleGroupItemSizes = {
+  sm: 'h-8 px-2.5 text-xs',
+  md: 'h-9 px-3 text-sm',
+  lg: 'h-10 px-4 text-sm',
+}
+
+const ToggleGroupItem = ({ className, variant = 'default', size = 'md', ...props }) => (
+  <ToggleGroupPrimitive.Item
+    className={cn(
+      'inline-flex items-center justify-center whitespace-nowrap rounded-md',
+      'font-medium ring-offset-background transition-all',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      variant === 'default' && [
+        'text-muted-foreground hover:bg-background/50 hover:text-foreground',
+        'data-[state=on]:bg-background data-[state=on]:text-foreground data-[state=on]:shadow-sm',
+      ],
+      variant === 'outline' && [
+        'border-r border-border last:border-r-0',
+        'text-muted-foreground hover:bg-muted hover:text-foreground',
+        'data-[state=on]:bg-muted data-[state=on]:text-foreground',
+      ],
+      toggleGroupItemSizes[size],
+      className
+    )}
+    {...props}
+  />
+)
+
+// Usage examples
+
+// View switcher (single selection)
+import { LayoutGrid, List, Rows } from 'lucide-react'
+
+const ViewToggle = ({ value, onChange }) => (
+  <ToggleGroup type="single" value={value} onValueChange={onChange}>
+    <ToggleGroupItem value="grid" aria-label="Grid view">
+      <LayoutGrid className="h-4 w-4" />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="list" aria-label="List view">
+      <List className="h-4 w-4" />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="rows" aria-label="Rows view">
+      <Rows className="h-4 w-4" />
+    </ToggleGroupItem>
+  </ToggleGroup>
+)
+
+// Text formatting (multiple selection)
+import { Bold, Italic, Underline, Strikethrough } from 'lucide-react'
+
+const TextFormatting = ({ value, onChange }) => (
+  <ToggleGroup type="multiple" value={value} onValueChange={onChange}>
+    <ToggleGroupItem value="bold" aria-label="Bold">
+      <Bold className="h-4 w-4" />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="italic" aria-label="Italic">
+      <Italic className="h-4 w-4" />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="underline" aria-label="Underline">
+      <Underline className="h-4 w-4" />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="strikethrough" aria-label="Strikethrough">
+      <Strikethrough className="h-4 w-4" />
+    </ToggleGroupItem>
+  </ToggleGroup>
+)
+
+// Filter options with text
+const FilterToggle = ({ value, onChange }) => (
+  <ToggleGroup type="single" value={value} onValueChange={onChange} variant="outline">
+    <ToggleGroupItem value="all">All</ToggleGroupItem>
+    <ToggleGroupItem value="active">Active</ToggleGroupItem>
+    <ToggleGroupItem value="completed">Completed</ToggleGroupItem>
+  </ToggleGroup>
+)
+
+// Full width toggle
+const PlanToggle = ({ value, onChange }) => (
+  <ToggleGroup type="single" value={value} onValueChange={onChange} className="w-full">
+    <ToggleGroupItem value="monthly" className="flex-1">Monthly</ToggleGroupItem>
+    <ToggleGroupItem value="yearly" className="flex-1">
+      Yearly
+      <span className="ml-1 text-xs text-primary">Save 20%</span>
+    </ToggleGroupItem>
+  </ToggleGroup>
+)
+
+// With controlled state
+const [view, setView] = useState('grid')
+const [formatting, setFormatting] = useState<string[]>([])
+
+<ViewToggle value={view} onChange={setView} />
+<TextFormatting value={formatting} onChange={setFormatting} />
+```

package/templates/component-recipes/tooltip.md

@@ -0,0 +1,115 @@
+# Tooltip Component Recipe
+
+## Structure
+- Trigger element (wraps any interactive element)
+- Content popup with arrow
+- Support multiple positions
+- Delay on hover before showing
+
+## Tailwind Classes
+
+### Content
+```
+z-50 overflow-hidden {tokens.radius} bg-foreground px-3 py-1.5 text-xs text-background
+animate-in fade-in-0 zoom-in-95
+data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-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-foreground
+```
+
+### Alternative Light Style
+```
+bg-background border border-border text-foreground {tokens.shadow}
+Arrow: fill-background stroke-border
+```
+
+## Props Interface
+```typescript
+interface TooltipProps {
+  content: React.ReactNode
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  align?: 'start' | 'center' | 'end'
+  delayDuration?: number
+  children: React.ReactNode
+}
+```
+
+## Configuration
+- Default delay: 200ms (adjust based on UX needs)
+- Default side: 'top'
+- Skip delay on hover when moving between tooltips
+
+## Do
+- Use Radix Tooltip for accessibility
+- Include enter/exit animations
+- Support arrow pointing to trigger
+- Use inverted colors (dark bg, light text) for contrast
+
+## Don't
+- Show tooltip on disabled elements without wrapper
+- Use too long delay (frustrating UX)
+- Put interactive content in tooltips (use popover instead)
+- Hardcode colors
+
+## Example
+```tsx
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+import { cn } from '@/lib/utils'
+
+const TooltipProvider = TooltipPrimitive.Provider
+
+const Tooltip = TooltipPrimitive.Root
+
+const TooltipTrigger = TooltipPrimitive.Trigger
+
+const TooltipContent = ({ className, sideOffset = 4, ...props }) => (
+  <TooltipPrimitive.Content
+    sideOffset={sideOffset}
+    className={cn(
+      'z-50 overflow-hidden rounded-md bg-foreground px-3 py-1.5 text-xs text-background',
+      'animate-in fade-in-0 zoom-in-95',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-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 TooltipArrow = ({ className, ...props }) => (
+  <TooltipPrimitive.Arrow
+    className={cn('fill-foreground', className)}
+    {...props}
+  />
+)
+
+// Simplified wrapper component
+const SimpleTooltip = ({ content, side = 'top', delayDuration = 200, children }) => (
+  <TooltipProvider>
+    <Tooltip delayDuration={delayDuration}>
+      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipContent side={side}>
+        {content}
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+  </TooltipProvider>
+)
+
+// Usage
+<SimpleTooltip content="Add to library">
+  <Button variant="ghost" size="icon">
+    <Plus className="h-4 w-4" />
+  </Button>
+</SimpleTooltip>
+```

package/templates/hooks/triggers.d/styling.json

@@ -0,0 +1,23 @@
+{
+  "styling": [
+    "style",
+    "styling",
+    "css",
+    "tailwind",
+    "theme",
+    "color",
+    "colours",
+    "spacing",
+    "design system",
+    "design tokens",
+    "dark mode",
+    "light mode",
+    "ui component",
+    "component library",
+    "className",
+    "aesthetic",
+    "visual",
+    "look and feel"
+  ],
+  "_comment": "Styling trigger extension for @claude-tools/component-system"
+}