@fr0mpy/component-system 2.0.0

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

@@ -0,0 +1,310 @@
+# Navigation Menu Component Recipe
+
+## Structure
+- Horizontal navigation bar
+- Support for dropdown menus with content panels
+- Trigger items with optional indicators
+- Content areas for mega-menu style layouts
+- Animated transitions for open/close
+
+## Tailwind Classes
+
+### Root
+```
+relative z-10 flex max-w-max flex-1 items-center justify-center
+```
+
+### List
+```
+group flex flex-1 list-none items-center justify-center space-x-1
+```
+
+### Trigger
+```
+group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2
+text-sm font-medium transition-colors
+hover:bg-muted hover:text-foreground
+focus:bg-muted focus:text-foreground focus:outline-none
+disabled:pointer-events-none disabled:opacity-50
+data-[state=open]:bg-muted/50
+```
+
+### Trigger Indicator (Chevron)
+```
+relative top-[1px] ml-1 h-3 w-3 transition duration-300
+group-data-[state=open]:rotate-180
+```
+
+### Content
+```
+left-0 top-0 w-full
+data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out
+data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out
+data-[motion=from-end]:slide-in-from-right-52
+data-[motion=from-start]:slide-in-from-left-52
+data-[motion=to-end]:slide-out-to-right-52
+data-[motion=to-start]:slide-out-to-left-52
+md:absolute md:w-auto
+```
+
+### Viewport
+```
+origin-top-center relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)]
+w-full overflow-hidden rounded-lg border border-border bg-popover text-popover-foreground shadow-lg
+data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90
+md:w-[var(--radix-navigation-menu-viewport-width)]
+```
+
+### Link
+```
+block select-none space-y-1 rounded-md p-3 leading-none no-underline outline-none
+transition-colors hover:bg-muted hover:text-foreground focus:bg-muted focus:text-foreground
+```
+
+### Link Title
+```
+text-sm font-medium leading-none
+```
+
+### Link Description
+```
+line-clamp-2 text-sm leading-snug text-muted-foreground
+```
+
+### Indicator
+```
+top-full z-[1] flex h-1.5 items-end justify-center overflow-hidden
+data-[state=visible]:animate-in data-[state=hidden]:animate-out
+data-[state=hidden]:fade-out data-[state=visible]:fade-in
+```
+
+### Indicator Arrow
+```
+relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md
+```
+
+## Props Interface
+```typescript
+interface NavigationMenuProps {
+  children: React.ReactNode
+  className?: string
+  orientation?: 'horizontal' | 'vertical'
+  delayDuration?: number
+  skipDelayDuration?: number
+}
+
+interface NavigationMenuListProps {
+  children: React.ReactNode
+  className?: string
+}
+
+interface NavigationMenuItemProps {
+  children: React.ReactNode
+  value?: string
+}
+
+interface NavigationMenuTriggerProps {
+  children: React.ReactNode
+  className?: string
+}
+
+interface NavigationMenuContentProps {
+  children: React.ReactNode
+  className?: string
+}
+
+interface NavigationMenuLinkProps {
+  href: string
+  children: React.ReactNode
+  className?: string
+  active?: boolean
+}
+```
+
+## Do
+- Use Radix NavigationMenu primitive
+- Support keyboard navigation (arrow keys)
+- Include proper ARIA attributes
+- Allow for mega-menu content layouts
+- Handle hover/focus delays appropriately
+
+## Don't
+- Hardcode colors or sizes
+- Nest navigation menus
+- Skip focus management
+- Forget mobile responsiveness (consider hamburger on small screens)
+
+## Example
+```tsx
+import * as NavigationMenuPrimitive from '@radix-ui/react-navigation-menu'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const NavigationMenu = ({ className, children, ...props }) => (
+  <NavigationMenuPrimitive.Root
+    className={cn(
+      'relative z-10 flex max-w-max flex-1 items-center justify-center',
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <NavigationMenuViewport />
+  </NavigationMenuPrimitive.Root>
+)
+
+const NavigationMenuList = ({ className, ...props }) => (
+  <NavigationMenuPrimitive.List
+    className={cn(
+      'group flex flex-1 list-none items-center justify-center space-x-1',
+      className
+    )}
+    {...props}
+  />
+)
+
+const NavigationMenuItem = NavigationMenuPrimitive.Item
+
+const NavigationMenuTrigger = ({ className, children, ...props }) => (
+  <NavigationMenuPrimitive.Trigger
+    className={cn(
+      'group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2',
+      'text-sm font-medium transition-colors',
+      'hover:bg-muted hover:text-foreground',
+      'focus:bg-muted focus:text-foreground focus:outline-none',
+      'disabled:pointer-events-none disabled:opacity-50',
+      'data-[state=open]:bg-muted/50',
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronDown
+      className="relative top-[1px] ml-1 h-3 w-3 transition duration-300 group-data-[state=open]:rotate-180"
+      aria-hidden="true"
+    />
+  </NavigationMenuPrimitive.Trigger>
+)
+
+const NavigationMenuContent = ({ className, ...props }) => (
+  <NavigationMenuPrimitive.Content
+    className={cn(
+      'left-0 top-0 w-full',
+      'data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out',
+      'data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out',
+      'data-[motion=from-end]:slide-in-from-right-52',
+      'data-[motion=from-start]:slide-in-from-left-52',
+      'data-[motion=to-end]:slide-out-to-right-52',
+      'data-[motion=to-start]:slide-out-to-left-52',
+      'md:absolute md:w-auto',
+      className
+    )}
+    {...props}
+  />
+)
+
+const NavigationMenuLink = NavigationMenuPrimitive.Link
+
+const NavigationMenuViewport = ({ className, ...props }) => (
+  <div className="absolute left-0 top-full flex justify-center">
+    <NavigationMenuPrimitive.Viewport
+      className={cn(
+        'origin-top-center relative mt-1.5',
+        'h-[var(--radix-navigation-menu-viewport-height)]',
+        'w-full overflow-hidden rounded-lg border border-border',
+        'bg-popover text-popover-foreground shadow-lg',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out',
+        'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90',
+        'md:w-[var(--radix-navigation-menu-viewport-width)]',
+        className
+      )}
+      {...props}
+    />
+  </div>
+)
+
+const NavigationMenuIndicator = ({ className, ...props }) => (
+  <NavigationMenuPrimitive.Indicator
+    className={cn(
+      'top-full z-[1] flex h-1.5 items-end justify-center overflow-hidden',
+      'data-[state=visible]:animate-in data-[state=hidden]:animate-out',
+      'data-[state=hidden]:fade-out data-[state=visible]:fade-in',
+      className
+    )}
+    {...props}
+  >
+    <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
+  </NavigationMenuPrimitive.Indicator>
+)
+
+// List item component for content
+const ListItem = ({ className, title, children, href, ...props }) => (
+  <li>
+    <NavigationMenuLink asChild>
+      <a
+        href={href}
+        className={cn(
+          'block select-none space-y-1 rounded-md p-3 leading-none no-underline outline-none',
+          'transition-colors hover:bg-muted hover:text-foreground focus:bg-muted focus:text-foreground',
+          className
+        )}
+        {...props}
+      >
+        <div className="text-sm font-medium leading-none">{title}</div>
+        <p className="line-clamp-2 text-sm leading-snug text-muted-foreground">
+          {children}
+        </p>
+      </a>
+    </NavigationMenuLink>
+  </li>
+)
+
+// Usage example
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <ul className="grid gap-3 p-6 md:w-[400px] lg:w-[500px] lg:grid-cols-2">
+          <ListItem href="/products/analytics" title="Analytics">
+            Track user behavior and measure performance.
+          </ListItem>
+          <ListItem href="/products/automation" title="Automation">
+            Automate workflows and save time.
+          </ListItem>
+          <ListItem href="/products/security" title="Security">
+            Protect your data with enterprise-grade security.
+          </ListItem>
+          <ListItem href="/products/integrations" title="Integrations">
+            Connect with your favorite tools.
+          </ListItem>
+        </ul>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Resources</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <ul className="grid w-[400px] gap-3 p-4 md:w-[500px] md:grid-cols-2">
+          <ListItem href="/docs" title="Documentation">
+            Learn how to use our platform.
+          </ListItem>
+          <ListItem href="/blog" title="Blog">
+            Read the latest updates and tutorials.
+          </ListItem>
+        </ul>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+
+    <NavigationMenuItem>
+      <NavigationMenuLink
+        href="/pricing"
+        className="inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-muted"
+      >
+        Pricing
+      </NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```

package/templates/component-recipes/pagination.md

@@ -0,0 +1,223 @@
+# Pagination Component Recipe
+
+## Structure
+- Previous/Next navigation buttons
+- Page number buttons
+- Ellipsis for truncated ranges
+- Current page indicator
+- Optional: items per page selector, total count
+
+## Tailwind Classes
+
+### Container
+```
+flex items-center justify-center space-x-1
+```
+
+### Navigation Button (Previous/Next)
+```
+inline-flex items-center justify-center whitespace-nowrap {tokens.radius} text-sm font-medium
+h-9 px-3 gap-1
+border border-border bg-transparent
+hover:bg-muted hover:text-foreground
+disabled:pointer-events-none disabled:opacity-50
+```
+
+### Page Button
+```
+inline-flex items-center justify-center whitespace-nowrap {tokens.radius} text-sm font-medium
+h-9 w-9
+border border-border bg-transparent
+hover:bg-muted hover:text-foreground
+```
+
+### Active Page Button
+```
+border-primary bg-primary text-primary-foreground
+hover:bg-primary/90 hover:text-primary-foreground
+```
+
+### Ellipsis
+```
+flex h-9 w-9 items-center justify-center
+```
+
+### With Info
+```
+Container: flex items-center justify-between
+Info: text-sm text-muted-foreground
+Controls: flex items-center space-x-6 lg:space-x-8
+```
+
+### Items Per Page Selector
+```
+flex items-center space-x-2
+Label: text-sm font-medium
+Select: h-8 w-16
+```
+
+## Props Interface
+```typescript
+interface PaginationProps {
+  currentPage: number
+  totalPages: number
+  onPageChange: (page: number) => void
+  siblingCount?: number // Pages shown on each side of current
+  showFirstLast?: boolean
+}
+
+interface PaginationWithInfoProps extends PaginationProps {
+  totalItems: number
+  itemsPerPage: number
+  onItemsPerPageChange?: (count: number) => void
+  itemsPerPageOptions?: number[]
+}
+```
+
+## Logic
+```typescript
+// Generate page numbers with ellipsis
+function generatePagination(current, total, siblings = 1) {
+  const range = (start, end) =>
+    Array.from({ length: end - start + 1 }, (_, i) => start + i)
+
+  const totalNumbers = siblings * 2 + 3 // siblings + current + first + last
+  const totalBlocks = totalNumbers + 2 // + 2 ellipsis
+
+  if (total <= totalBlocks) {
+    return range(1, total)
+  }
+
+  const leftSiblingIndex = Math.max(current - siblings, 1)
+  const rightSiblingIndex = Math.min(current + siblings, total)
+
+  const showLeftEllipsis = leftSiblingIndex > 2
+  const showRightEllipsis = rightSiblingIndex < total - 1
+
+  if (!showLeftEllipsis && showRightEllipsis) {
+    const leftRange = range(1, 3 + 2 * siblings)
+    return [...leftRange, 'ellipsis', total]
+  }
+
+  if (showLeftEllipsis && !showRightEllipsis) {
+    const rightRange = range(total - (2 + 2 * siblings), total)
+    return [1, 'ellipsis', ...rightRange]
+  }
+
+  const middleRange = range(leftSiblingIndex, rightSiblingIndex)
+  return [1, 'ellipsis', ...middleRange, 'ellipsis', total]
+}
+```
+
+## Do
+- Show current page clearly
+- Disable prev on first page, next on last
+- Use ellipsis for large page counts
+- Keep total width manageable
+
+## Don't
+- Hardcode colors
+- Show all page numbers for large sets
+- Forget mobile responsiveness
+- Skip keyboard navigation
+
+## Example
+```tsx
+import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from './Button'
+
+const Pagination = ({
+  currentPage,
+  totalPages,
+  onPageChange,
+  siblingCount = 1,
+}) => {
+  const pages = generatePagination(currentPage, totalPages, siblingCount)
+
+  return (
+    <nav className="flex items-center justify-center space-x-1" aria-label="Pagination">
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => onPageChange(currentPage - 1)}
+        disabled={currentPage <= 1}
+        className="gap-1"
+      >
+        <ChevronLeft className="h-4 w-4" />
+        <span className="sr-only sm:not-sr-only">Previous</span>
+      </Button>
+
+      {pages.map((page, i) =>
+        page === 'ellipsis' ? (
+          <span key={`ellipsis-${i}`} className="flex h-9 w-9 items-center justify-center">
+            <MoreHorizontal className="h-4 w-4" />
+          </span>
+        ) : (
+          <Button
+            key={page}
+            variant={currentPage === page ? 'default' : 'outline'}
+            size="sm"
+            onClick={() => onPageChange(page)}
+            className="h-9 w-9"
+          >
+            {page}
+          </Button>
+        )
+      )}
+
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => onPageChange(currentPage + 1)}
+        disabled={currentPage >= totalPages}
+        className="gap-1"
+      >
+        <span className="sr-only sm:not-sr-only">Next</span>
+        <ChevronRight className="h-4 w-4" />
+      </Button>
+    </nav>
+  )
+}
+
+// With info and items per page
+const PaginationWithInfo = ({
+  currentPage,
+  totalPages,
+  totalItems,
+  itemsPerPage,
+  onPageChange,
+  onItemsPerPageChange,
+}) => {
+  const start = (currentPage - 1) * itemsPerPage + 1
+  const end = Math.min(currentPage * itemsPerPage, totalItems)
+
+  return (
+    <div className="flex items-center justify-between px-2">
+      <div className="text-sm text-muted-foreground">
+        Showing {start} to {end} of {totalItems} results
+      </div>
+      <div className="flex items-center space-x-6">
+        {onItemsPerPageChange && (
+          <div className="flex items-center space-x-2">
+            <span className="text-sm font-medium">Rows per page</span>
+            <Select
+              value={String(itemsPerPage)}
+              onValueChange={(v) => onItemsPerPageChange(Number(v))}
+            >
+              {[10, 20, 50, 100].map((n) => (
+                <SelectItem key={n} value={String(n)}>{n}</SelectItem>
+              ))}
+            </Select>
+          </div>
+        )}
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          onPageChange={onPageChange}
+        />
+      </div>
+    </div>
+  )
+}
+```

package/templates/component-recipes/popover.md

@@ -0,0 +1,156 @@
+# Popover Component Recipe
+
+## Structure
+- Trigger element
+- Floating content panel
+- Arrow pointing to trigger (optional)
+- Support multiple placements
+- Click outside to close
+
+## Tailwind Classes
+
+### Content
+```
+z-50 w-72 {tokens.radius} border border-border bg-background p-4 text-foreground {tokens.shadow}
+outline-none
+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
+```
+
+### Arrow
+```
+fill-background stroke-border
+```
+
+### Close Button (optional)
+```
+absolute right-2 top-2 rounded-sm opacity-70 hover:opacity-100
+focus:outline-none focus:ring-1 focus:ring-primary
+```
+
+### Header (if structured content)
+```
+mb-2
+```
+
+### Title
+```
+font-medium leading-none
+```
+
+### Description
+```
+text-sm text-muted-foreground mt-1
+```
+
+## Props Interface
+```typescript
+interface PopoverProps {
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean
+  modal?: boolean
+  children: React.ReactNode
+}
+
+interface PopoverTriggerProps {
+  asChild?: boolean
+  children: React.ReactNode
+}
+
+interface PopoverContentProps {
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  sideOffset?: number
+  align?: 'start' | 'center' | 'end'
+  alignOffset?: number
+  className?: string
+  children: React.ReactNode
+}
+
+interface PopoverArrowProps {
+  className?: string
+  width?: number
+  height?: number
+}
+```
+
+## Do
+- Use Radix Popover for accessibility
+- Include enter/exit animations
+- Support arrow pointing to trigger
+- Handle viewport collision (flip/shift)
+
+## Don't
+- Hardcode dimensions (use sensible defaults but allow override)
+- Forget focus management
+- Skip keyboard support (Escape to close)
+- Use for tooltips (use Tooltip component)
+
+## Example
+```tsx
+import * as PopoverPrimitive from '@radix-ui/react-popover'
+import { cn } from '@/lib/utils'
+
+const Popover = PopoverPrimitive.Root
+const PopoverTrigger = PopoverPrimitive.Trigger
+const PopoverAnchor = PopoverPrimitive.Anchor
+
+const PopoverContent = ({
+  className,
+  align = 'center',
+  sideOffset = 4,
+  ...props
+}) => (
+  <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 w-72 rounded-lg border border-border bg-background p-4 shadow-md outline-none',
+        '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',
+        className
+      )}
+      {...props}
+    />
+  </PopoverPrimitive.Portal>
+)
+
+const PopoverArrow = ({ className, ...props }) => (
+  <PopoverPrimitive.Arrow
+    className={cn('fill-background stroke-border', className)}
+    {...props}
+  />
+)
+
+// Usage
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Open popover</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <div className="grid gap-4">
+      <div className="space-y-2">
+        <h4 className="font-medium leading-none">Dimensions</h4>
+        <p className="text-sm text-muted-foreground">
+          Set the dimensions for the layer.
+        </p>
+      </div>
+      <div className="grid gap-2">
+        <Input placeholder="Width" />
+        <Input placeholder="Height" />
+      </div>
+    </div>
+  </PopoverContent>
+</Popover>
+```