@fr0mpy/component-system 2.0.0

package/templates/component-recipes/progress.md

@@ -0,0 +1,185 @@
+# Progress Component Recipe
+
+## Structure
+- Track container with filled indicator
+- Support determinate (percentage) and indeterminate (loading)
+- Optional label and value display
+- Circular variant option
+
+## Tailwind Classes
+
+### Linear Progress
+
+#### Root/Track
+```
+relative h-2 w-full overflow-hidden rounded-full bg-muted
+```
+
+#### Indicator (filled)
+```
+h-full w-full flex-1 bg-primary transition-all
+```
+
+#### Indeterminate Animation
+```
+animate-progress-indeterminate
+@keyframes progress-indeterminate {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(100%); }
+}
+```
+
+### Sizes
+```
+sm: h-1
+md: h-2 (default)
+lg: h-3
+xl: h-4
+```
+
+### Variants
+```
+default:     bg-primary
+success:     bg-green-500
+warning:     bg-yellow-500
+destructive: bg-destructive
+```
+
+### With Label
+```
+Container: space-y-2
+Label row: flex justify-between text-sm
+Label: text-muted-foreground
+Value: font-medium
+```
+
+### Circular Progress
+```
+Container: relative inline-flex
+SVG: -rotate-90 transform
+Track circle: stroke-muted
+Indicator circle: stroke-primary transition-all
+  stroke-dasharray: circumference
+  stroke-dashoffset: circumference - (value/100 * circumference)
+```
+
+## Props Interface
+```typescript
+interface ProgressProps {
+  value?: number // 0-100, undefined = indeterminate
+  max?: number
+  variant?: 'default' | 'success' | 'warning' | 'destructive'
+  size?: 'sm' | 'md' | 'lg' | 'xl'
+  showValue?: boolean
+  label?: string
+}
+
+interface CircularProgressProps extends ProgressProps {
+  strokeWidth?: number
+  diameter?: number
+}
+```
+
+## Do
+- Use Radix Progress for accessibility
+- Support both determinate and indeterminate states
+- Include aria-valuenow, aria-valuemin, aria-valuemax
+- Animate smoothly between values
+
+## Don't
+- Hardcode colors
+- Forget accessibility attributes
+- Use jerky animations
+- Skip indeterminate state support
+
+## Example
+```tsx
+import * as ProgressPrimitive from '@radix-ui/react-progress'
+import { cn } from '@/lib/utils'
+
+const progressVariants = {
+  default: 'bg-primary',
+  success: 'bg-green-500',
+  warning: 'bg-yellow-500',
+  destructive: 'bg-destructive',
+}
+
+const progressSizes = {
+  sm: 'h-1',
+  md: 'h-2',
+  lg: 'h-3',
+  xl: 'h-4',
+}
+
+const Progress = ({
+  value,
+  variant = 'default',
+  size = 'md',
+  className,
+  ...props
+}) => (
+  <ProgressPrimitive.Root
+    className={cn(
+      'relative w-full overflow-hidden rounded-full bg-muted',
+      progressSizes[size],
+      className
+    )}
+    {...props}
+  >
+    <ProgressPrimitive.Indicator
+      className={cn(
+        'h-full w-full flex-1 transition-all',
+        progressVariants[variant],
+        value === undefined && 'animate-progress-indeterminate'
+      )}
+      style={{ transform: value !== undefined ? `translateX(-${100 - value}%)` : undefined }}
+    />
+  </ProgressPrimitive.Root>
+)
+
+// With label and value
+const ProgressWithLabel = ({ label, value, ...props }) => (
+  <div className="space-y-2">
+    <div className="flex justify-between text-sm">
+      <span className="text-muted-foreground">{label}</span>
+      <span className="font-medium">{value}%</span>
+    </div>
+    <Progress value={value} {...props} />
+  </div>
+)
+
+// Circular progress
+const CircularProgress = ({ value, size = 40, strokeWidth = 4 }) => {
+  const radius = (size - strokeWidth) / 2
+  const circumference = radius * 2 * Math.PI
+  const offset = value !== undefined
+    ? circumference - (value / 100) * circumference
+    : 0
+
+  return (
+    <svg width={size} height={size} className="-rotate-90 transform">
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={strokeWidth}
+        className="text-muted"
+      />
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={strokeWidth}
+        strokeDasharray={circumference}
+        strokeDashoffset={offset}
+        strokeLinecap="round"
+        className="text-primary transition-all"
+      />
+    </svg>
+  )
+}
+```

package/templates/component-recipes/radio.md

@@ -0,0 +1,148 @@
+# Radio Component Recipe
+
+## Structure
+- Radio group container
+- Individual radio items with circular indicator
+- Label for each option
+- Optional description per item
+
+## Tailwind Classes
+
+### Radio Group
+```
+grid gap-2
+```
+
+### Radio Item
+```
+aspect-square h-4 w-4 rounded-full border border-border
+ring-offset-background
+focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2
+disabled:cursor-not-allowed disabled:opacity-50
+data-[state=checked]:border-primary
+```
+
+### Radio Indicator (inner dot)
+```
+flex items-center justify-center
+after:content-[''] after:block after:h-2 after:w-2 after:rounded-full after:bg-primary
+```
+
+### Radio Item Wrapper (with label)
+```
+flex items-center space-x-2
+```
+
+### Label
+```
+text-sm font-medium leading-none text-foreground
+peer-disabled:cursor-not-allowed peer-disabled:opacity-70
+```
+
+### Card Style Variant (selectable cards)
+```
+flex cursor-pointer items-start space-x-3 {tokens.radius} border border-border p-4
+hover:bg-surface
+data-[state=checked]:border-primary data-[state=checked]:bg-primary/5
+```
+
+## Props Interface
+```typescript
+interface RadioGroupProps {
+  value?: string
+  onValueChange?: (value: string) => void
+  disabled?: boolean
+  orientation?: 'horizontal' | 'vertical'
+  children: React.ReactNode
+}
+
+interface RadioGroupItemProps {
+  value: string
+  disabled?: boolean
+  id?: string
+}
+
+interface RadioCardProps {
+  value: string
+  label: string
+  description?: string
+  disabled?: boolean
+}
+```
+
+## Do
+- Use Radix RadioGroup for accessibility
+- Support horizontal and vertical layouts
+- Include focus ring
+- Animate indicator appearance
+- Support card-style radio buttons
+
+## Don't
+- Hardcode colors
+- Use actual `<input type="radio">` without styling
+- Forget group semantics
+- Skip disabled state
+
+## Example
+```tsx
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group'
+import { Circle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const RadioGroup = ({ className, ...props }) => (
+  <RadioGroupPrimitive.Root className={cn('grid gap-2', className)} {...props} />
+)
+
+const RadioGroupItem = ({ className, ...props }) => (
+  <RadioGroupPrimitive.Item
+    className={cn(
+      'aspect-square h-4 w-4 rounded-full border border-border',
+      'ring-offset-background',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+      'disabled:cursor-not-allowed disabled:opacity-50',
+      'data-[state=checked]:border-primary',
+      className
+    )}
+    {...props}
+  >
+    <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
+      <Circle className="h-2 w-2 fill-primary text-primary" />
+    </RadioGroupPrimitive.Indicator>
+  </RadioGroupPrimitive.Item>
+)
+
+// With label
+const RadioWithLabel = ({ value, label, description, id }) => (
+  <div className="flex items-start space-x-2">
+    <RadioGroupItem value={value} id={id} />
+    <div className="grid gap-1.5 leading-none">
+      <label htmlFor={id} className="text-sm font-medium text-foreground">
+        {label}
+      </label>
+      {description && (
+        <p className="text-sm text-muted-foreground">{description}</p>
+      )}
+    </div>
+  </div>
+)
+
+// Card style variant
+const RadioCard = ({ value, label, description }) => (
+  <RadioGroupPrimitive.Item
+    value={value}
+    className={cn(
+      'flex cursor-pointer items-start space-x-3 rounded-lg border border-border p-4',
+      'hover:bg-surface',
+      'data-[state=checked]:border-primary data-[state=checked]:bg-primary/5'
+    )}
+  >
+    <RadioGroupPrimitive.Indicator className="mt-1">
+      <Circle className="h-2 w-2 fill-primary text-primary" />
+    </RadioGroupPrimitive.Indicator>
+    <div>
+      <p className="font-medium text-foreground">{label}</p>
+      {description && <p className="text-sm text-muted-foreground">{description}</p>}
+    </div>
+  </RadioGroupPrimitive.Item>
+)
+```

package/templates/component-recipes/select.md

@@ -0,0 +1,154 @@
+# Select/Dropdown Component Recipe
+
+## Structure
+- Trigger button that shows current value
+- Dropdown content with scrollable list
+- Option items with optional icons/checkmarks
+- Support for groups and separators
+
+## Tailwind Classes
+
+### Trigger
+```
+flex h-10 w-full items-center justify-between {tokens.radius} border border-border
+bg-background px-3 py-2 text-sm text-foreground
+placeholder:text-muted-foreground
+focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
+disabled:cursor-not-allowed disabled:opacity-50
+```
+
+### Content (Dropdown)
+```
+relative z-50 max-h-96 min-w-[8rem] overflow-hidden {tokens.radius}
+border border-border bg-background 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=top]:slide-in-from-bottom-2
+```
+
+### Viewport (scrollable area)
+```
+p-1 max-h-[300px] overflow-y-auto
+```
+
+### Item
+```
+relative flex w-full cursor-pointer select-none items-center {tokens.radius} py-1.5 pl-8 pr-2
+text-sm outline-none
+focus:bg-surface focus:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Selected Indicator
+```
+absolute left-2 flex h-3.5 w-3.5 items-center justify-center
+```
+
+### Separator
+```
+-mx-1 my-1 h-px bg-border
+```
+
+### Group Label
+```
+py-1.5 pl-8 pr-2 text-sm font-semibold text-foreground
+```
+
+## Props Interface
+```typescript
+interface SelectProps {
+  value?: string
+  onValueChange?: (value: string) => void
+  placeholder?: string
+  disabled?: boolean
+  children: React.ReactNode
+}
+
+interface SelectItemProps {
+  value: string
+  disabled?: boolean
+  children: React.ReactNode
+}
+
+interface SelectGroupProps {
+  label: string
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use Radix Select for accessibility
+- Show checkmark for selected item
+- Include chevron icon on trigger
+- Support keyboard navigation
+- Handle long lists with scrolling
+
+## Don't
+- Hardcode colors
+- Forget hover/focus states on items
+- Skip selected state indicator
+- Use custom scroll behavior
+
+## Example
+```tsx
+import * as SelectPrimitive from '@radix-ui/react-select'
+import { Check, ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Select = SelectPrimitive.Root
+
+const SelectTrigger = ({ className, children, ...props }) => (
+  <SelectPrimitive.Trigger
+    className={cn(
+      'flex h-10 w-full items-center justify-between rounded-lg border border-border',
+      'bg-background px-3 py-2 text-sm',
+      'focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2',
+      'disabled:cursor-not-allowed disabled:opacity-50',
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <SelectPrimitive.Icon>
+      <ChevronDown className="h-4 w-4 opacity-50" />
+    </SelectPrimitive.Icon>
+  </SelectPrimitive.Trigger>
+)
+
+const SelectContent = ({ className, children, ...props }) => (
+  <SelectPrimitive.Portal>
+    <SelectPrimitive.Content
+      className={cn(
+        'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-lg',
+        'border border-border bg-background shadow-md',
+        className
+      )}
+      {...props}
+    >
+      <SelectPrimitive.Viewport className="p-1">
+        {children}
+      </SelectPrimitive.Viewport>
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Portal>
+)
+
+const SelectItem = ({ className, children, ...props }) => (
+  <SelectPrimitive.Item
+    className={cn(
+      'relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm',
+      'outline-none focus:bg-surface',
+      '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">
+      <SelectPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </SelectPrimitive.ItemIndicator>
+    </span>
+    <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+  </SelectPrimitive.Item>
+)
+```

package/templates/component-recipes/separator.md

@@ -0,0 +1,124 @@
+# Separator Component Recipe
+
+## Structure
+- Simple divider line
+- Support horizontal and vertical orientations
+- Decorative by default (not announced by screen readers)
+- Optional label in center
+
+## Tailwind Classes
+
+### Base
+```
+shrink-0 bg-border
+```
+
+### Horizontal (default)
+```
+h-px w-full
+```
+
+### Vertical
+```
+h-full w-px
+```
+
+### With Label
+```
+Container: relative flex items-center
+Line: flex-1 h-px bg-border
+Label: mx-4 text-xs text-muted-foreground uppercase tracking-wider
+```
+
+### Spacing Variants
+```
+sm: my-2 (horizontal) / mx-2 (vertical)
+md: my-4 (horizontal) / mx-4 (vertical)
+lg: my-6 (horizontal) / mx-6 (vertical)
+```
+
+### Style Variants
+```
+solid:  bg-border (default)
+dashed: border-t border-dashed border-border bg-transparent h-0
+dotted: border-t border-dotted border-border bg-transparent h-0
+```
+
+## Props Interface
+```typescript
+interface SeparatorProps {
+  orientation?: 'horizontal' | 'vertical'
+  decorative?: boolean
+  className?: string
+}
+
+interface SeparatorWithLabelProps extends SeparatorProps {
+  label: string
+}
+```
+
+## Do
+- Use Radix Separator for semantic correctness
+- Set decorative={true} for visual-only separators
+- Use consistent spacing in lists/groups
+- Support both orientations
+
+## Don't
+- Hardcode colors
+- Use <hr> without proper styling
+- Forget to set decorative prop appropriately
+- Over-use separators (whitespace often suffices)
+
+## Example
+```tsx
+import * as SeparatorPrimitive from '@radix-ui/react-separator'
+import { cn } from '@/lib/utils'
+
+const Separator = ({
+  className,
+  orientation = 'horizontal',
+  decorative = true,
+  ...props
+}) => (
+  <SeparatorPrimitive.Root
+    decorative={decorative}
+    orientation={orientation}
+    className={cn(
+      'shrink-0 bg-border',
+      orientation === 'horizontal' ? 'h-px w-full' : 'h-full w-px',
+      className
+    )}
+    {...props}
+  />
+)
+
+// With label
+const SeparatorWithLabel = ({ label, className, ...props }) => (
+  <div className={cn('relative flex items-center', className)} {...props}>
+    <div className="flex-1 h-px bg-border" />
+    <span className="mx-4 text-xs text-muted-foreground uppercase tracking-wider">
+      {label}
+    </span>
+    <div className="flex-1 h-px bg-border" />
+  </div>
+)
+
+// Usage examples
+<div className="space-y-4">
+  <div>Content above</div>
+  <Separator />
+  <div>Content below</div>
+</div>
+
+// Vertical in flex container
+<div className="flex h-5 items-center space-x-4 text-sm">
+  <div>Blog</div>
+  <Separator orientation="vertical" />
+  <div>Docs</div>
+  <Separator orientation="vertical" />
+  <div>Source</div>
+</div>
+
+// With label
+<SeparatorWithLabel label="Or continue with" />
+```