@fr0mpy/component-system 2.0.0

package/templates/component-recipes/checkbox.md

@@ -0,0 +1,117 @@
+# Checkbox Component Recipe
+
+## Structure
+- Clickable box with check indicator
+- Optional label alongside
+- Support indeterminate state
+- Group wrapper for multiple checkboxes
+
+## Tailwind Classes
+
+### Checkbox Box
+```
+peer h-4 w-4 shrink-0 {tokens.radius} border border-border
+ring-offset-background
+focus-visible: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]:bg-primary data-[state=checked]:border-primary data-[state=checked]:text-primary-foreground
+data-[state=indeterminate]:bg-primary data-[state=indeterminate]:border-primary
+```
+
+### Check Icon
+```
+h-3.5 w-3.5 text-current
+```
+
+### Label
+```
+text-sm font-medium leading-none text-foreground
+peer-disabled:cursor-not-allowed peer-disabled:opacity-70
+```
+
+### Wrapper (checkbox + label)
+```
+flex items-center space-x-2
+```
+
+### Description (optional)
+```
+text-sm text-muted-foreground
+```
+
+## Props Interface
+```typescript
+interface CheckboxProps {
+  checked?: boolean | 'indeterminate'
+  onCheckedChange?: (checked: boolean | 'indeterminate') => void
+  disabled?: boolean
+  id?: string
+  name?: string
+}
+
+interface CheckboxWithLabelProps extends CheckboxProps {
+  label: string
+  description?: string
+}
+```
+
+## Do
+- Use `peer` class for label styling based on checkbox state
+- Include focus ring for accessibility
+- Support indeterminate state (for "select all" patterns)
+- Use semantic color tokens
+- Animate check appearance
+
+## Don't
+- Hardcode colors
+- Use actual `<input type="checkbox">` without styling wrapper
+- Forget disabled state styling
+- Skip focus indicators
+
+## Example
+```tsx
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox'
+import { Check, Minus } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Checkbox = ({ className, ...props }) => (
+  <CheckboxPrimitive.Root
+    className={cn(
+      'peer h-4 w-4 shrink-0 rounded border border-border',
+      'ring-offset-background',
+      'focus-visible: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]:bg-primary data-[state=checked]:border-primary data-[state=checked]:text-primary-foreground',
+      'data-[state=indeterminate]:bg-primary data-[state=indeterminate]:border-primary data-[state=indeterminate]:text-primary-foreground',
+      className
+    )}
+    {...props}
+  >
+    <CheckboxPrimitive.Indicator className="flex items-center justify-center text-current">
+      {props.checked === 'indeterminate' ? (
+        <Minus className="h-3.5 w-3.5" />
+      ) : (
+        <Check className="h-3.5 w-3.5" />
+      )}
+    </CheckboxPrimitive.Indicator>
+  </CheckboxPrimitive.Root>
+)
+
+// With label wrapper
+const CheckboxWithLabel = ({ label, description, id, ...props }) => (
+  <div className="flex items-start space-x-2">
+    <Checkbox id={id} {...props} />
+    <div className="grid gap-1.5 leading-none">
+      <label
+        htmlFor={id}
+        className="text-sm font-medium leading-none text-foreground peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
+      >
+        {label}
+      </label>
+      {description && (
+        <p className="text-sm text-muted-foreground">{description}</p>
+      )}
+    </div>
+  </div>
+)
+```

package/templates/component-recipes/collapsible.md

@@ -0,0 +1,201 @@
+# Collapsible Component Recipe
+
+## Structure
+- Trigger element to toggle
+- Content area that expands/collapses
+- Smooth height animation
+- Optional chevron indicator
+
+## Tailwind Classes
+
+### Root
+```
+w-full
+```
+
+### Trigger
+```
+flex items-center justify-between w-full [&[data-state=open]>svg]:rotate-180
+```
+
+### Trigger with default styling
+```
+flex items-center justify-between w-full py-2 font-medium
+transition-all hover:underline
+```
+
+### Chevron Icon
+```
+h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-200
+```
+
+### Content
+```
+overflow-hidden
+data-[state=closed]:animate-collapsible-up
+data-[state=open]:animate-collapsible-down
+```
+
+### Content Inner (for padding)
+```
+pt-2 pb-4
+```
+
+## Animations (add to tailwind.config.js)
+```js
+keyframes: {
+  'collapsible-down': {
+    from: { height: '0' },
+    to: { height: 'var(--radix-collapsible-content-height)' },
+  },
+  'collapsible-up': {
+    from: { height: 'var(--radix-collapsible-content-height)' },
+    to: { height: '0' },
+  },
+},
+animation: {
+  'collapsible-down': 'collapsible-down 0.2s ease-out',
+  'collapsible-up': 'collapsible-up 0.2s ease-out',
+},
+```
+
+## Props Interface
+```typescript
+interface CollapsibleProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+  disabled?: boolean
+  children: React.ReactNode
+}
+
+interface CollapsibleTriggerProps {
+  asChild?: boolean
+  children: React.ReactNode
+}
+
+interface CollapsibleContentProps {
+  forceMount?: boolean
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Use Cases
+- FAQ sections
+- Sidebar navigation groups
+- Settings panels
+- Advanced options sections
+- Code snippets with preview
+
+## Do
+- Use Radix Collapsible for accessibility
+- Animate height smoothly
+- Include visual indicator of state (chevron)
+- Support keyboard toggle (Enter/Space)
+
+## Don't
+- Hardcode colors
+- Use abrupt show/hide (animate it)
+- Nest collapsibles too deeply
+- Use for primary content that should always be visible
+
+## Example
+```tsx
+import * as CollapsiblePrimitive from '@radix-ui/react-collapsible'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Collapsible = CollapsiblePrimitive.Root
+
+const CollapsibleTrigger = CollapsiblePrimitive.Trigger
+
+const CollapsibleContent = ({ className, children, ...props }) => (
+  <CollapsiblePrimitive.Content
+    className={cn(
+      'overflow-hidden',
+      'data-[state=closed]:animate-collapsible-up',
+      'data-[state=open]:animate-collapsible-down',
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </CollapsiblePrimitive.Content>
+)
+
+// Simple usage
+const SimpleCollapsible = ({ title, children }) => (
+  <Collapsible>
+    <CollapsibleTrigger className="flex items-center justify-between w-full py-2 font-medium hover:underline [&[data-state=open]>svg]:rotate-180">
+      {title}
+      <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+    </CollapsibleTrigger>
+    <CollapsibleContent>
+      <div className="pt-2 pb-4">{children}</div>
+    </CollapsibleContent>
+  </Collapsible>
+)
+
+// With border styling
+const CollapsibleCard = ({ title, defaultOpen = false, children }) => (
+  <Collapsible defaultOpen={defaultOpen} className="rounded-lg border border-border">
+    <CollapsibleTrigger className="flex items-center justify-between w-full p-4 font-medium [&[data-state=open]>svg]:rotate-180">
+      {title}
+      <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-200" />
+    </CollapsibleTrigger>
+    <CollapsibleContent>
+      <div className="px-4 pb-4 pt-0 border-t border-border">
+        {children}
+      </div>
+    </CollapsibleContent>
+  </Collapsible>
+)
+
+// Sidebar navigation example
+const SidebarGroup = ({ label, items, defaultOpen = true }) => (
+  <Collapsible defaultOpen={defaultOpen} className="space-y-2">
+    <CollapsibleTrigger className="flex items-center justify-between w-full px-2 py-1.5 text-sm font-semibold text-muted-foreground hover:text-foreground [&[data-state=open]>svg]:rotate-180">
+      {label}
+      <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+    </CollapsibleTrigger>
+    <CollapsibleContent>
+      <div className="space-y-1">
+        {items.map((item) => (
+          <a
+            key={item.href}
+            href={item.href}
+            className="block rounded-md px-2 py-1.5 text-sm hover:bg-muted"
+          >
+            {item.label}
+          </a>
+        ))}
+      </div>
+    </CollapsibleContent>
+  </Collapsible>
+)
+
+// Code preview with expand
+const CodePreview = ({ preview, code }) => {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen}>
+      <div className="rounded-lg border border-border">
+        <div className="p-4">{preview}</div>
+        <div className="border-t border-border">
+          <CollapsibleTrigger className="flex items-center justify-center w-full py-2 text-sm text-muted-foreground hover:text-foreground">
+            {open ? 'Hide code' : 'Show code'}
+            <ChevronDown className={cn('ml-1 h-4 w-4 transition-transform', open && 'rotate-180')} />
+          </CollapsibleTrigger>
+        </div>
+        <CollapsibleContent>
+          <pre className="p-4 bg-muted text-sm overflow-x-auto">
+            <code>{code}</code>
+          </pre>
+        </CollapsibleContent>
+      </div>
+    </Collapsible>
+  )
+}
+```

package/templates/component-recipes/combobox.md

@@ -0,0 +1,193 @@
+# Combobox Component Recipe
+
+## Structure
+- Text input for searching/filtering
+- Dropdown list of options
+- Support for single and multi-select
+- Keyboard navigation (arrows, enter, escape)
+- Option for creating new items
+
+## Tailwind Classes
+
+### Trigger/Input Container
+```
+flex h-10 w-full items-center justify-between {tokens.radius} border border-border
+bg-background px-3 py-2 text-sm
+focus-within:outline-none focus-within:ring-2 focus-within:ring-primary focus-within:ring-offset-2
+disabled:cursor-not-allowed disabled:opacity-50
+```
+
+### Input
+```
+flex-1 bg-transparent outline-none placeholder:text-muted-foreground
+```
+
+### Trigger Button
+```
+ml-2 shrink-0 opacity-50 hover:opacity-100
+```
+
+### Content (Dropdown)
+```
+relative z-50 max-h-96 min-w-[8rem] overflow-hidden {tokens.radius}
+border border-border bg-background text-foreground {tokens.shadow}
+```
+
+### Viewport
+```
+p-1 max-h-[300px] overflow-y-auto
+```
+
+### Empty State
+```
+py-6 text-center text-sm text-muted-foreground
+```
+
+### Item
+```
+relative flex cursor-pointer select-none items-center {tokens.radius} py-1.5 pl-2 pr-8
+text-sm outline-none
+data-[highlighted]:bg-muted data-[highlighted]:text-foreground
+data-[disabled]:pointer-events-none data-[disabled]:opacity-50
+```
+
+### Item Indicator (check)
+```
+absolute right-2 flex h-3.5 w-3.5 items-center justify-center
+```
+
+### Group
+```
+overflow-hidden p-1
+```
+
+### Group Label
+```
+px-2 py-1.5 text-xs font-medium text-muted-foreground
+```
+
+### Separator
+```
+-mx-1 my-1 h-px bg-border
+```
+
+## Props Interface
+```typescript
+interface ComboboxProps {
+  value?: string | string[]
+  onValueChange?: (value: string | string[]) => void
+  options: { value: string; label: string; disabled?: boolean }[]
+  placeholder?: string
+  searchPlaceholder?: string
+  emptyText?: string
+  disabled?: boolean
+  multiple?: boolean
+  allowCreate?: boolean
+  onCreate?: (value: string) => void
+}
+```
+
+## Do
+- Use Radix Combobox or cmdk for accessibility
+- Support type-ahead filtering
+- Clear search on selection (single) or keep (multi)
+- Show loading state while filtering
+
+## Don't
+- Hardcode colors
+- Forget empty state message
+- Skip keyboard navigation
+- Load all options upfront for large lists (use virtualization)
+
+## Example
+```tsx
+import { useState } from 'react'
+import { Command } from 'cmdk'
+import { Check, ChevronsUpDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Popover, PopoverContent, PopoverTrigger } from './Popover'
+import { Button } from './Button'
+
+const Combobox = ({
+  options,
+  value,
+  onValueChange,
+  placeholder = 'Select option...',
+  searchPlaceholder = 'Search...',
+  emptyText = 'No results found.',
+}) => {
+  const [open, setOpen] = useState(false)
+  const [search, setSearch] = useState('')
+
+  const selected = options.find(opt => opt.value === value)
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          className="w-full justify-between"
+        >
+          {selected?.label ?? placeholder}
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-full p-0">
+        <Command>
+          <Command.Input
+            placeholder={searchPlaceholder}
+            value={search}
+            onValueChange={setSearch}
+            className="h-9 border-b border-border px-3 outline-none"
+          />
+          <Command.Empty className="py-6 text-center text-sm text-muted-foreground">
+            {emptyText}
+          </Command.Empty>
+          <Command.List className="max-h-[300px] overflow-y-auto p-1">
+            {options.map(option => (
+              <Command.Item
+                key={option.value}
+                value={option.value}
+                onSelect={() => {
+                  onValueChange?.(option.value)
+                  setOpen(false)
+                }}
+                className={cn(
+                  'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm',
+                  'data-[highlighted]:bg-muted'
+                )}
+              >
+                {option.label}
+                {value === option.value && (
+                  <Check className="absolute right-2 h-4 w-4" />
+                )}
+              </Command.Item>
+            ))}
+          </Command.List>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+// Multi-select variant
+const MultiCombobox = ({ options, value = [], onValueChange, ...props }) => {
+  const toggleOption = (optionValue) => {
+    const newValue = value.includes(optionValue)
+      ? value.filter(v => v !== optionValue)
+      : [...value, optionValue]
+    onValueChange?.(newValue)
+  }
+
+  return (
+    <Combobox
+      {...props}
+      options={options}
+      value={value}
+      onValueChange={toggleOption}
+    />
+  )
+}
+```