@fr0mpy/component-system 2.0.0

package/templates/component-recipes/breadcrumb.md

@@ -0,0 +1,220 @@
+# Breadcrumb Component Recipe
+
+## Structure
+- Ordered list of navigation links
+- Separator between items (chevron or slash)
+- Current page indicator (not a link)
+- Optional: collapsible for long paths
+- Support for icons
+
+## Tailwind Classes
+
+### Nav Container
+```
+<nav aria-label="Breadcrumb">
+```
+
+### List
+```
+flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground
+sm:gap-2.5
+```
+
+### Item
+```
+inline-flex items-center gap-1.5
+```
+
+### Link
+```
+transition-colors hover:text-foreground
+```
+
+### Current Page (not a link)
+```
+font-normal text-foreground
+```
+
+### Separator
+```
+[&>svg]:h-3.5 [&>svg]:w-3.5
+text-muted-foreground
+```
+
+### Ellipsis (collapsed items)
+```
+flex h-9 w-9 items-center justify-center
+```
+
+### With Icons
+```
+[&>svg]:mr-1.5 [&>svg]:h-4 [&>svg]:w-4
+```
+
+## Props Interface
+```typescript
+interface BreadcrumbProps {
+  children: React.ReactNode
+  separator?: React.ReactNode
+  className?: string
+}
+
+interface BreadcrumbItemProps {
+  href?: string
+  current?: boolean
+  children: React.ReactNode
+}
+
+interface BreadcrumbListProps {
+  children: React.ReactNode
+  className?: string
+}
+
+interface BreadcrumbLinkProps {
+  href: string
+  asChild?: boolean
+  children: React.ReactNode
+}
+
+interface BreadcrumbPageProps {
+  children: React.ReactNode
+}
+
+interface BreadcrumbSeparatorProps {
+  children?: React.ReactNode
+}
+
+interface BreadcrumbEllipsisProps {
+  className?: string
+}
+```
+
+## Accessibility
+- Use `<nav aria-label="Breadcrumb">`
+- Use `<ol>` for ordered list semantics
+- Mark current page with `aria-current="page"`
+- Last item should not be a link
+
+## Do
+- Keep breadcrumb trails short (collapse if needed)
+- Use consistent separator throughout
+- Make all items except current clickable
+- Include home/root as first item
+
+## Don't
+- Hardcode colors
+- Make current page a link
+- Use for non-hierarchical navigation
+- Show breadcrumbs on home page
+
+## Example
+```tsx
+import { ChevronRight, MoreHorizontal } from 'lucide-react'
+import { Slot } from '@radix-ui/react-slot'
+import { cn } from '@/lib/utils'
+
+const Breadcrumb = ({ children, ...props }) => (
+  <nav aria-label="breadcrumb" {...props}>
+    {children}
+  </nav>
+)
+
+const BreadcrumbList = ({ className, ...props }) => (
+  <ol
+    className={cn(
+      'flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground sm:gap-2.5',
+      className
+    )}
+    {...props}
+  />
+)
+
+const BreadcrumbItem = ({ className, ...props }) => (
+  <li className={cn('inline-flex items-center gap-1.5', className)} {...props} />
+)
+
+const BreadcrumbLink = ({ asChild, className, ...props }) => {
+  const Comp = asChild ? Slot : 'a'
+  return (
+    <Comp
+      className={cn('transition-colors hover:text-foreground', className)}
+      {...props}
+    />
+  )
+}
+
+const BreadcrumbPage = ({ className, ...props }) => (
+  <span
+    role="link"
+    aria-disabled="true"
+    aria-current="page"
+    className={cn('font-normal text-foreground', className)}
+    {...props}
+  />
+)
+
+const BreadcrumbSeparator = ({ children, className, ...props }) => (
+  <li
+    role="presentation"
+    aria-hidden="true"
+    className={cn('[&>svg]:h-3.5 [&>svg]:w-3.5', className)}
+    {...props}
+  >
+    {children ?? <ChevronRight />}
+  </li>
+)
+
+const BreadcrumbEllipsis = ({ className, ...props }) => (
+  <span
+    role="presentation"
+    aria-hidden="true"
+    className={cn('flex h-9 w-9 items-center justify-center', className)}
+    {...props}
+  >
+    <MoreHorizontal className="h-4 w-4" />
+    <span className="sr-only">More</span>
+  </span>
+)
+
+// Usage
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Current Product</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+
+// With collapsed items
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <DropdownMenu>
+        <DropdownMenuTrigger>
+          <BreadcrumbEllipsis />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuItem>Products</DropdownMenuItem>
+          <DropdownMenuItem>Category</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Item</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```

package/templates/component-recipes/button.md

@@ -0,0 +1,90 @@
+# Button Component Recipe
+
+## Structure
+- Use `<button>` element with `type` attribute (default: "button")
+- Support variants: primary, secondary, outline, ghost, destructive
+- Support sizes: sm, md, lg
+- Include states: loading, disabled
+- Optionally support `asChild` for composition (render as link, etc.)
+
+## Tailwind Classes
+
+### Base
+```
+inline-flex items-center justify-center gap-2 font-medium transition-colors
+focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2
+disabled:pointer-events-none disabled:opacity-50
+```
+
+### Variants
+```
+primary:     bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-primary
+secondary:   bg-secondary text-secondary-foreground hover:bg-secondary/90 focus-visible:ring-secondary
+outline:     border border-border bg-transparent hover:bg-surface focus-visible:ring-primary
+ghost:       bg-transparent hover:bg-surface focus-visible:ring-primary
+destructive: bg-destructive text-destructive-foreground hover:bg-destructive/90 focus-visible:ring-destructive
+```
+
+### Sizes
+```
+sm: h-8 px-3 text-sm {tokens.radius}
+md: h-10 px-4 text-sm {tokens.radius}
+lg: h-12 px-6 text-base {tokens.radius}
+```
+
+### States
+```
+loading: relative [&>*]:invisible
+         Add spinner overlay with absolute positioning
+disabled: opacity-50 cursor-not-allowed
+```
+
+## Props Interface
+```typescript
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'
+  size?: 'sm' | 'md' | 'lg'
+  loading?: boolean
+  disabled?: boolean
+  asChild?: boolean
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use `cn()` utility for class merging
+- Include `focus-visible` ring for accessibility
+- Support icon-only buttons (square aspect ratio)
+- Use semantic color tokens from config
+
+## Don't
+- Hardcode colors (use `bg-primary` not `bg-blue-500`)
+- Forget hover states
+- Skip focus indicators
+- Use inline styles
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+
+const Button = ({ variant = 'primary', size = 'md', loading, disabled, className, children, ...props }) => {
+  return (
+    <button
+      className={cn(
+        'inline-flex items-center justify-center gap-2 font-medium transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+        'disabled:pointer-events-none disabled:opacity-50',
+        variants[variant],
+        sizes[size],
+        loading && 'relative [&>*]:invisible',
+        className
+      )}
+      disabled={disabled || loading}
+      {...props}
+    >
+      {loading && <Spinner className="absolute" />}
+      {children}
+    </button>
+  )
+}
+```

package/templates/component-recipes/card.md

@@ -0,0 +1,130 @@
+# Card Component Recipe
+
+## Structure
+- Container with `<div>` element
+- Optional subcomponents: CardHeader, CardTitle, CardDescription, CardContent, CardFooter
+- Composable pattern - each part is optional
+
+## Tailwind Classes
+
+### Card (Container)
+```
+{tokens.radius} border border-border bg-surface {tokens.shadow}
+```
+
+### CardHeader
+```
+flex flex-col space-y-1.5 p-{tokens.spacing.normal}
+```
+
+### CardTitle
+```
+{tokens.typography.heading} text-lg text-foreground
+```
+
+### CardDescription
+```
+text-sm text-muted-foreground
+```
+
+### CardContent
+```
+p-{tokens.spacing.normal} pt-0
+```
+
+### CardFooter
+```
+flex items-center p-{tokens.spacing.normal} pt-0
+```
+
+## Props Interface
+```typescript
+interface CardProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface CardHeaderProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface CardTitleProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface CardDescriptionProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface CardContentProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface CardFooterProps {
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use composable pattern (Card.Header, Card.Title, etc.)
+- Apply shadow from `{tokens.shadow}`
+- Use `bg-surface` for background (not `bg-white`)
+- Support flexible content layouts
+
+## Don't
+- Hardcode padding values
+- Use `bg-white` (use `bg-surface` for theme support)
+- Forget border for definition
+- Apply heavy shadows unless config specifies
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+
+const Card = ({ className, children, ...props }) => (
+  <div
+    className={cn(
+      'rounded-lg border border-border bg-surface shadow-sm',
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+)
+
+const CardHeader = ({ className, children, ...props }) => (
+  <div className={cn('flex flex-col space-y-1.5 p-4', className)} {...props}>
+    {children}
+  </div>
+)
+
+const CardTitle = ({ className, children, ...props }) => (
+  <h3 className={cn('font-semibold text-lg text-foreground', className)} {...props}>
+    {children}
+  </h3>
+)
+
+const CardDescription = ({ className, children, ...props }) => (
+  <p className={cn('text-sm text-muted-foreground', className)} {...props}>
+    {children}
+  </p>
+)
+
+const CardContent = ({ className, children, ...props }) => (
+  <div className={cn('p-4 pt-0', className)} {...props}>
+    {children}
+  </div>
+)
+
+const CardFooter = ({ className, children, ...props }) => (
+  <div className={cn('flex items-center p-4 pt-0', className)} {...props}>
+    {children}
+  </div>
+)
+```

package/templates/component-recipes/carousel.md

@@ -0,0 +1,277 @@
+# Carousel Component Recipe
+
+## Structure
+- Container with overflow hidden
+- Scrollable track with items
+- Previous/Next navigation buttons
+- Optional pagination dots
+- Support for auto-play
+- Touch/swipe support
+
+## Tailwind Classes
+
+### Container
+```
+relative w-full overflow-hidden
+```
+
+### Track
+```
+flex transition-transform duration-300 ease-out
+```
+
+### Item
+```
+min-w-0 shrink-0 grow-0
+```
+
+### Item Sizes
+```
+full: basis-full
+half: basis-1/2
+third: basis-1/3
+quarter: basis-1/4
+```
+
+### Navigation Buttons
+```
+absolute top-1/2 -translate-y-1/2 z-10
+inline-flex items-center justify-center
+h-10 w-10 {tokens.radius}
+bg-background/80 backdrop-blur-sm border border-border
+hover:bg-muted
+disabled:opacity-50 disabled:pointer-events-none
+transition-colors
+
+Previous: left-2
+Next: right-2
+```
+
+### Pagination Dots
+```
+Container: absolute bottom-4 left-1/2 -translate-x-1/2 flex gap-2
+Dot: h-2 w-2 rounded-full bg-background/50 transition-colors
+Dot active: bg-background
+```
+
+### With Gap
+```
+Track: -ml-4 (negative margin)
+Item: pl-4 (padding for gap)
+```
+
+## Props Interface
+```typescript
+interface CarouselProps {
+  children: React.ReactNode
+  slidesPerView?: number | 'auto'
+  spaceBetween?: number
+  loop?: boolean
+  autoplay?: boolean | { delay: number }
+  showNavigation?: boolean
+  showPagination?: boolean
+  className?: string
+}
+
+interface CarouselItemProps {
+  children: React.ReactNode
+  className?: string
+}
+
+interface CarouselApi {
+  scrollPrev: () => void
+  scrollNext: () => void
+  scrollTo: (index: number) => void
+  canScrollPrev: boolean
+  canScrollNext: boolean
+  selectedIndex: number
+}
+```
+
+## Do
+- Use embla-carousel for robust implementation
+- Support touch/swipe gestures
+- Provide keyboard navigation
+- Include aria labels for accessibility
+- Respect reduced-motion preferences
+
+## Don't
+- Hardcode colors or dimensions
+- Auto-play without user control to pause
+- Forget mobile responsiveness
+- Skip focus management
+
+## Example
+```tsx
+import { useCallback, useEffect, useState } from 'react'
+import useEmblaCarousel from 'embla-carousel-react'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Carousel = ({
+  children,
+  showNavigation = true,
+  showPagination = true,
+  loop = false,
+  className,
+  ...options
+}) => {
+  const [emblaRef, emblaApi] = useEmblaCarousel({ loop, ...options })
+  const [canScrollPrev, setCanScrollPrev] = useState(false)
+  const [canScrollNext, setCanScrollNext] = useState(false)
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [scrollSnaps, setScrollSnaps] = useState<number[]>([])
+
+  const scrollPrev = useCallback(() => emblaApi?.scrollPrev(), [emblaApi])
+  const scrollNext = useCallback(() => emblaApi?.scrollNext(), [emblaApi])
+  const scrollTo = useCallback((index: number) => emblaApi?.scrollTo(index), [emblaApi])
+
+  const onSelect = useCallback(() => {
+    if (!emblaApi) return
+    setSelectedIndex(emblaApi.selectedScrollSnap())
+    setCanScrollPrev(emblaApi.canScrollPrev())
+    setCanScrollNext(emblaApi.canScrollNext())
+  }, [emblaApi])
+
+  useEffect(() => {
+    if (!emblaApi) return
+    setScrollSnaps(emblaApi.scrollSnapList())
+    onSelect()
+    emblaApi.on('select', onSelect)
+    emblaApi.on('reInit', onSelect)
+    return () => {
+      emblaApi.off('select', onSelect)
+      emblaApi.off('reInit', onSelect)
+    }
+  }, [emblaApi, onSelect])
+
+  return (
+    <div className={cn('relative w-full', className)} aria-roledescription="carousel">
+      <div ref={emblaRef} className="overflow-hidden">
+        <div className="flex -ml-4">
+          {children}
+        </div>
+      </div>
+
+      {showNavigation && (
+        <>
+          <button
+            onClick={scrollPrev}
+            disabled={!canScrollPrev}
+            className={cn(
+              'absolute left-2 top-1/2 -translate-y-1/2 z-10',
+              'inline-flex items-center justify-center h-10 w-10 rounded-full',
+              'bg-background/80 backdrop-blur-sm border border-border',
+              'hover:bg-muted transition-colors',
+              'disabled:opacity-50 disabled:pointer-events-none'
+            )}
+            aria-label="Previous slide"
+          >
+            <ChevronLeft className="h-5 w-5" />
+          </button>
+          <button
+            onClick={scrollNext}
+            disabled={!canScrollNext}
+            className={cn(
+              'absolute right-2 top-1/2 -translate-y-1/2 z-10',
+              'inline-flex items-center justify-center h-10 w-10 rounded-full',
+              'bg-background/80 backdrop-blur-sm border border-border',
+              'hover:bg-muted transition-colors',
+              'disabled:opacity-50 disabled:pointer-events-none'
+            )}
+            aria-label="Next slide"
+          >
+            <ChevronRight className="h-5 w-5" />
+          </button>
+        </>
+      )}
+
+      {showPagination && scrollSnaps.length > 1 && (
+        <div className="absolute bottom-4 left-1/2 -translate-x-1/2 flex gap-2">
+          {scrollSnaps.map((_, index) => (
+            <button
+              key={index}
+              onClick={() => scrollTo(index)}
+              className={cn(
+                'h-2 w-2 rounded-full transition-colors',
+                index === selectedIndex
+                  ? 'bg-primary'
+                  : 'bg-primary/30 hover:bg-primary/50'
+              )}
+              aria-label={`Go to slide ${index + 1}`}
+              aria-current={index === selectedIndex ? 'true' : undefined}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+const CarouselItem = ({ children, className }) => (
+  <div
+    className={cn('min-w-0 shrink-0 grow-0 basis-full pl-4', className)}
+    role="group"
+    aria-roledescription="slide"
+  >
+    {children}
+  </div>
+)
+
+// With autoplay
+const AutoplayCarousel = ({ children, delay = 4000, ...props }) => {
+  const [emblaRef, emblaApi] = useEmblaCarousel({ loop: true })
+  const [isPaused, setIsPaused] = useState(false)
+
+  useEffect(() => {
+    if (!emblaApi || isPaused) return
+    const interval = setInterval(() => emblaApi.scrollNext(), delay)
+    return () => clearInterval(interval)
+  }, [emblaApi, delay, isPaused])
+
+  return (
+    <div
+      onMouseEnter={() => setIsPaused(true)}
+      onMouseLeave={() => setIsPaused(false)}
+    >
+      <Carousel {...props}>{children}</Carousel>
+    </div>
+  )
+}
+
+// Usage examples
+<Carousel>
+  <CarouselItem>
+    <img src="/slide-1.jpg" alt="Slide 1" className="w-full aspect-video object-cover rounded-lg" />
+  </CarouselItem>
+  <CarouselItem>
+    <img src="/slide-2.jpg" alt="Slide 2" className="w-full aspect-video object-cover rounded-lg" />
+  </CarouselItem>
+  <CarouselItem>
+    <img src="/slide-3.jpg" alt="Slide 3" className="w-full aspect-video object-cover rounded-lg" />
+  </CarouselItem>
+</Carousel>
+
+// Multiple slides visible
+<Carousel slidesPerView={3}>
+  {products.map((product) => (
+    <CarouselItem key={product.id} className="basis-1/3">
+      <ProductCard product={product} />
+    </CarouselItem>
+  ))}
+</Carousel>
+
+// Card carousel
+<Carousel showPagination={false}>
+  {testimonials.map((t) => (
+    <CarouselItem key={t.id}>
+      <Card className="mx-4">
+        <CardContent className="p-6">
+          <p className="text-muted-foreground">{t.quote}</p>
+          <p className="mt-4 font-medium">{t.author}</p>
+        </CardContent>
+      </Card>
+    </CarouselItem>
+  ))}
+</Carousel>
+```