// DocCard + DocCards — grid of clickable cards for docs landing pages
// (Fumadocs calls these `<Cards>` / `<Card>`). The wrapper handles the
// grid; each card is a Link with a hover indicator.
//
// Usage:
//   <DocCards>
//     <DocCard
//       title="Getting started"
//       description="Scaffold your first project and boot it locally."
//       href="/docs/intro/getting-started"
//       icon="🚀"
//     />
//     <DocCard … />
//   </DocCards>

import type { ComponentType, ReactNode } from 'react'
import { cn } from '../cn'
import type { ShellLinkProps } from '../compositions/docShell'

interface DocCardsProps {
  readonly children: ReactNode
  readonly className?: string
  /** Override the grid columns. Default: 1 on mobile, 2 on md+. */
  readonly cols?: 1 | 2 | 3
  /** Stagger the first paint — each card fades + slides up with a
   *  ~40ms delay. Respects prefers-reduced-motion. Default true. */
  readonly stagger?: boolean
}

interface DocCardProps {
  readonly title: ReactNode
  readonly description?: ReactNode
  readonly href: string
  readonly icon?: ReactNode
  readonly className?: string
  /** Optional client-router Link; falls back to plain <a>. */
  readonly LinkComponent?: ComponentType<ShellLinkProps>
}

const PlainLink = ({ to, className, children }: ShellLinkProps): ReactNode => (
  <a href={to} className={className}>{children}</a>
)

const colClass: Record<NonNullable<DocCardsProps['cols']>, string> = {
  1: 'grid-cols-1',
  2: 'grid-cols-1 md:grid-cols-2',
  3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
}

export const DocCards = ({
  children, className, cols = 2, stagger = true,
}: DocCardsProps): ReactNode => (
  <div
    className={cn(
      'not-prose my-6 grid gap-4',
      colClass[cols],
      stagger && 'stagger-in',
      className,
    )}
  >
    {children}
  </div>
)

export const DocCard = ({
  title, description, href, icon, className, LinkComponent = PlainLink,
}: DocCardProps): ReactNode => {
  const Link = LinkComponent
  return (
    <Link
      to={href}
      prefetch
      className={cn(
        'group relative block p-5 rounded-lg border border-border bg-card/30',
        'hover:bg-card/60 hover:border-primary/40 hover:-translate-y-0.5',
        'active:translate-y-0 active:scale-[0.99]',
        'transition-[transform,background-color,border-color] duration-150 ease-out',
        // Subtle gradient accent on the top edge — fades in on hover.
        'before:absolute before:inset-x-4 before:top-0 before:h-px before:bg-gradient-to-r before:from-transparent before:via-primary/50 before:to-transparent before:opacity-0 before:transition-opacity group-hover:before:opacity-100',
        className,
      )}
    >
      <div className={cn('flex items-center gap-4', description ? 'mb-4' : '')}>
        {icon ? (
          <div
            className="flex shrink-0 items-center justify-center w-9 h-9 rounded-md bg-primary/10 text-primary [&_svg]:w-5 [&_svg]:h-5"
            aria-hidden="true"
          >
            {icon}
          </div>
        ) : null}
        <div className="min-w-0 font-semibold text-foreground group-hover:text-primary transition-colors flex items-center gap-2">
          <span className="min-w-0">{title}</span>
          <span
            className="shrink-0 text-muted-foreground group-hover:text-primary group-hover:translate-x-0.5 transition-all"
            aria-hidden="true"
          >
            →
          </span>
        </div>
      </div>
      {description ? (
        <div className="text-sm text-muted-foreground leading-relaxed">
          {description}
        </div>
      ) : null}
    </Link>
  )
}