# CardStack Section Pattern

This document covers the CardStack pattern used in Feature, Product, Pricing, Testimonial, Team, Blog, and Metrics section components.

## Required Type Imports

```tsx
// Centralized type definitions
import type { TextboxLayout, InvertedBackground } from "@/providers/themeProvider/config/constants";
import type { ButtonConfig, GridVariant, CardAnimationType, ContainerStyle, TitleSegment } from "@/components/cardStack/types";
```

**Key Types:**
- `TextboxLayout` - Layout options for section headers ("default" | "split" | "split-actions" | "split-description" | "inline-image")
- `InvertedBackground` - Background inversion options ("noInvert" | "invertDefault" | "invertCard")
- `TitleSegment` - Type for inline image segments ({ type: "text" | "image", content/src, alt? })
- `ButtonConfig` - Button configuration interface
- `GridVariant` - Grid layout variants
- `CardAnimationType` - Card animation types
- `ContainerStyle` - Container styling options

## Overview

CardStack is an intelligent layout component that automatically switches between grid, carousel, and timeline layouts based on item count and configuration.

**Mode Selection (Automatic):**
- **1-4 items**: Grid mode (displays as bento grid)
- **5+ items**: Carousel mode (auto-scrolling or button-controlled)
- **3-6 items with timeline variant**: Timeline layout (or carousel if 7+)

## Grid Variants

There are 9 bento grid layouts plus uniform layouts:

### Uniform Layouts
- `uniform-all-items-equal` - All items same size (default)
- `uniform-2-items` - Two equal columns
- `uniform-3-items` - Three equal columns
- `uniform-4-items` - Four equal columns

### Bento Layouts (Asymmetric)
- `two-columns-alternating-heights` - Alternating tall/short columns
- `asymmetric-60-wide-40-narrow` - 60% wide left, 40% narrow right
- `three-columns-all-equal-width` - Three equal columns
- `four-items-2x2-equal-grid` - Perfect 2x2 grid
- `one-large-right-three-stacked-left` - Left: 3 items, Right: 1 large
- `items-top-row-full-width-bottom` - Top: full width, Bottom: items
- `full-width-top-items-bottom-row` - Full width top, items below
- `one-large-left-three-stacked-right` - Left: 1 large, Right: 3 items
- `timeline` - Zigzag timeline layout

## Height Control Pattern

### uniformGridCustomHeightClasses Prop

All CardStack-based components should accept this optional prop to control item heights in both grid and carousel modes.

```tsx
interface SectionCardProps {
  items: ItemType[];
  gridVariant: GridVariant;
  uniformGridCustomHeightClasses?: string;
  carouselMode?: "auto" | "buttons";
  // ... other props
}
```

### Default Values by Component Type

**Most components (Feature, Product, Pricing, Team, Metrics, Blog):**
```tsx
uniformGridCustomHeightClasses = "min-h-80 2xl:min-h-90"
```

**Testimonial components (need flexible heights):**
```tsx
uniformGridCustomHeightClasses = "min-h-none"
```

**Hero carousel components (no minimum):**
```tsx
uniformGridCustomHeightClasses = "min-h-0"
```

**Feature components (optimized for compact layout):**
```tsx
// Hardcoded in FeatureCardFour
uniformGridCustomHeightClasses = "min-h-0"
```

### Implementation Pattern

The prop flows: Section Component → CardStack → GridLayout/Carousel

```tsx
// In section component (e.g., ProductCardOne.tsx)
const ProductCardOne = ({
  products,
  gridVariant,
  uniformGridCustomHeightClasses = "min-h-80 2xl:min-h-90",
  // ... other props
}: ProductCardOneProps) => {
  return (
    <CardStack
      gridVariant={gridVariant}
      uniformGridCustomHeightClasses={uniformGridCustomHeightClasses}
      // ... other props
    >
      {products.map((product) => (
        <div className="card">...</div>
      ))}
    </CardStack>
  );
};
```

**Individual card elements must use `min-h-0`:**
```tsx
<div className={cls("card p-6 rounded-theme-capped h-full min-h-0")}>
  {/* Product content */}
</div>
```

This prevents height conflicts and ensures proper flex behavior.

## Carousel Modes

### carouselMode Prop

```tsx
carouselMode?: "auto" | "buttons"
```

- **`"auto"`** - Auto-scrolling carousel (uses AutoCarousel with embla-carousel-auto-scroll)
- **`"buttons"`** - Button-controlled carousel (uses ButtonCarousel with prev/next buttons)

**Default is typically `"buttons"`** for better accessibility and user control.

## TextBox Integration

CardStack components integrate with TextBox for section headers.

### TextBox Layout Options

```tsx
import type { TextboxLayout } from "@/providers/themeProvider/config/constants";

textboxLayout: TextboxLayout // "default" | "split" | "split-actions" | "split-description" | "inline-image"
```

**Layout Modes:**

1. **`"default"`** - Title and description stacked vertically, centered or left-aligned
   ```
   [Tag]
   Title
   Description
   [Buttons]
   ```

2. **`"split"`** - Title and description on left (60%), buttons on right (40%)
   ```
   [Tag]
   Title | Description    |  [Buttons]
   ```

3. **`"split-actions"`** - Title and description on left, buttons on right (no description on right)
   ```
   [Tag]
   Title                   |  [Buttons]
   Description             |
   ```

4. **`"split-description"`** - Title on left, description on right, buttons below
   ```
   [Tag]
   Title                   |  Description
   [Buttons]
   ```

5. **`"inline-image"`** - Centered heading with inline images between text segments, buttons below
   ```
   Text [Image] Text [Image] Text
   [Buttons]
   ```

   **Special props for inline-image layout:**
   ```tsx
   import type { TitleSegment } from "@/components/cardStack/types";

   titleSegments?: TitleSegment[] // Array of text and image segments
   titleImageWrapperClassName?: string // Styling for image wrapper
   titleImageClassName?: string // Styling for the image itself
   ```

   **Example usage:**
   ```tsx
   <FeatureCardOne
     titleSegments={[
       { type: "text", content: "Discover" },
       { type: "image", src: "/icon.png", alt: "Icon" },
       { type: "text", content: "powerful features" }
     ]}
     textboxLayout="inline-image"
     // ... other props
   />
   ```

   **Inline Image Behavior:**
   - Images are styled with `primary-button` background
   - Automatic rotation alternation: 1st: -rotate-12, 2nd: rotate-12, etc.
   - Square aspect ratio (1.1em height)
   - Proper spacing with mx-1 margins
   - Supports both local paths and external URLs

### TextBox Props in CardStack

```tsx
<CardStack
  title="Our Products"
  titleSegments={[
    { type: "text", content: "Our" },
    { type: "image", src: "/icon.png", alt: "Product Icon" },
    { type: "text", content: "Products" }
  ]} // Optional: use titleSegments for inline-image layout
  description="Discover our latest offerings"
  tag="Products"
  tagIcon={Package}
  buttons={[
    { text: "View All", href: "/products" }
  ]}
  textboxLayout="split" // or "inline-image" with titleSegments
  useInvertedBackground="noInvert" // "noInvert" | "invertDefault" | "invertCard"
  // TextBox className overrides
  textBoxClassName=""
  titleClassName=""
  titleImageWrapperClassName="" // For inline-image layout
  titleImageClassName="" // For inline-image layout
  descriptionClassName=""
  tagClassName=""
  buttonContainerClassName=""
  buttonClassName=""
  buttonTextClassName=""
  // ... other props
>
```

## Button System

### ButtonConfig Interface

```tsx
interface ButtonConfig {
  text: string;
  onClick?: () => void;
  href?: string;
  props?: Partial<ButtonPropsForVariant<CTAButtonVariant>>;
  // NO variant property - controlled by ThemeProvider
}
```

### Button Rendering Logic

Buttons are rendered with automatic primary/secondary styling:

- **Index 0**: Primary button (`primary-button` class)
- **Index 1+**: Secondary button (`secondary-button` class)

**Maximum 2 buttons** per section (enforced in TextBox component).

```tsx
const buttons: ButtonConfig[] = [
  { text: "Get Started", href: "/signup" },     // Primary
  { text: "Learn More", onClick: () => {} }      // Secondary
];
```

The `variant` is determined by ThemeProvider's `defaultButtonVariant` setting.

## Complete CardStack Section Example

```tsx
"use client";

import React, { memo } from "react";
import CardStack from "@/components/cardStack/CardStack";
import { cls } from "@/lib/utils";
import type { GridVariant, ButtonConfig } from "@/components/cardStack/types";
import type { LucideIcon } from "lucide-react";

type Product = {
  title: string;
  description: string;
  price: string;
  image: string;
};

interface ProductCardOneProps {
  products: Product[];
  carouselMode?: "auto" | "buttons";
  gridVariant: GridVariant;
  uniformGridCustomHeightClasses?: string;
  title: string;
  description: string;
  tag?: string;
  tagIcon?: LucideIcon;
  buttons?: ButtonConfig[];
  textboxLayout: "default" | "split" | "split-actions" | "split-description";
  ariaLabel?: string;
  // Main wrapper
  className?: string;
  // CardStack customization
  cardStackClassName?: string;
  // TextBox customization
  textBoxClassName?: string;
  titleClassName?: string;
  descriptionClassName?: string;
  tagClassName?: string;
  buttonsWrapperClassName?: string;
  // Card customization
  cardClassName?: string;
  cardTitleClassName?: string;
  cardDescriptionClassName?: string;
  cardPriceClassName?: string;
  cardImageClassName?: string;
}

const ProductCardOne = ({
  products,
  carouselMode = "buttons",
  gridVariant,
  uniformGridCustomHeightClasses = "min-h-80 2xl:min-h-90",
  title,
  description,
  tag,
  tagIcon,
  buttons,
  textboxLayout,
  ariaLabel = "Product section",
  className = "",
  cardStackClassName = "",
  textBoxClassName = "",
  titleClassName = "",
  descriptionClassName = "",
  tagClassName = "",
  buttonsWrapperClassName = "",
  cardClassName = "",
  cardTitleClassName = "",
  cardDescriptionClassName = "",
  cardPriceClassName = "",
  cardImageClassName = "",
}: ProductCardOneProps) => {
  return (
    <section
      aria-label={ariaLabel}
      className={cls("w-full py-20", className)}
    >
      <div className="w-content-width mx-auto">
        <CardStack
          mode={carouselMode}
          gridVariant={gridVariant}
          uniformGridCustomHeightClasses={uniformGridCustomHeightClasses}
          title={title}
          description={description}
          tag={tag}
          tagIcon={tagIcon}
          buttons={buttons}
          textboxLayout={textboxLayout}
          className={cardStackClassName}
          textBoxClassName={textBoxClassName}
          titleClassName={titleClassName}
          descriptionClassName={descriptionClassName}
          tagClassName={tagClassName}
          buttonsWrapperClassName={buttonsWrapperClassName}
        >
          {products.map((product, index) => (
            <div
              key={`${product.title}-${index}`}
              className={cls(
                "card p-6 rounded-theme-capped h-full min-h-0 flex flex-col",
                cardClassName
              )}
            >
              <img
                src={product.image}
                alt={product.title}
                className={cls("w-full h-48 object-cover mb-4", cardImageClassName)}
              />
              <h3 className={cls("text-xl font-semibold mb-2", cardTitleClassName)}>
                {product.title}
              </h3>
              <p className={cls("text-foreground/75 flex-1", cardDescriptionClassName)}>
                {product.description}
              </p>
              <p className={cls("text-2xl font-bold mt-4", cardPriceClassName)}>
                {product.price}
              </p>
            </div>
          ))}
        </CardStack>
      </div>
    </section>
  );
};

ProductCardOne.displayName = "ProductCardOne";

export default memo(ProductCardOne);
```

## Animation Types

CardStack supports GSAP-powered scroll-triggered animations:

```tsx
animationType?: "none" | "opacity" | "slide-up" | "scale-rotate" | "blur-reveal"
```

**Animation Descriptions:**
- **`none`** - No animation
- **`opacity`** - Fade in
- **`slide-up`** - Slide up from below with stagger
- **`scale-rotate`** - Scale + rotate entrance with stagger
- **`blur-reveal`** - Blur to clear reveal with stagger

Each animation uses GSAP ScrollTrigger with staggered effect on children.

## Best Practices

### ✅ DO:

- Accept `uniformGridCustomHeightClasses` as optional prop with sensible default
- Use `min-h-0` on individual card elements for proper flex behavior
- Pass through all CardStack customization props (className overrides)
- Use appropriate default height for your component type
- Document the default value in registry propsSchema
- Provide className props for all card sub-elements
- Use `card` class for consistent card styling (theme-aware)
- Use `rounded-theme-capped` for card border radius
- Set `carouselMode` default to `"buttons"` for accessibility

### ❌ DO NOT:

- Hardcode height classes in CardStack (let it be controlled via prop)
- Remove the `uniformGridCustomHeightClasses` prop without specific reason
- Use different height classes for grid vs carousel (they should match)
- Forget to apply `min-h-0` on card wrapper divs
- Specify button `variant` in ButtonConfig (controlled by ThemeProvider)
- Create more than 2 buttons per section
- Use `lg:` or `xl:` breakpoints for layout changes

## CardStack Component Checklist

When creating a new CardStack-based section component:

### Props & Configuration
- [ ] Accept `uniformGridCustomHeightClasses` prop with appropriate default
- [ ] Accept `carouselMode` prop (default: `"buttons"`)
- [ ] Accept `gridVariant` as required prop (or hardcode if single variant)
- [ ] Accept `textboxLayout` for TextBox configuration
- [ ] Accept `animationType` for scroll animations (optional)

### CardStack Integration
- [ ] Pass `uniformGridCustomHeightClasses` to CardStack
- [ ] Pass all TextBox props (title, description, tag, tagIcon, buttons)
- [ ] Pass all TextBox className overrides
- [ ] Pass cardStackClassName for CardStack wrapper customization

### Card Implementation
- [ ] Apply `min-h-0` to individual card wrapper divs
- [ ] Use `card` class for card background/border styling
- [ ] Use `rounded-theme-capped` for border radius
- [ ] Provide className override props for all card sub-elements
- [ ] Use `h-full` on cards for consistent heights within grid

### Button System
- [ ] Use ButtonConfig type for buttons array
- [ ] Do NOT specify variant in ButtonConfig
- [ ] Maximum 2 buttons
- [ ] Let ThemeProvider control button variant

### Section Structure
- [ ] Use semantic `<section>` tag with aria-label
- [ ] Use `w-full py-20` on section
- [ ] Use `w-content-width mx-auto` wrapper
- [ ] Provide section className override

### Documentation
- [ ] Document `uniformGridCustomHeightClasses` default in registry
- [ ] Document all grid variants supported
- [ ] Document carousel mode options
- [ ] Include usage example with typical props