import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
import * as CardPatternsStories from './card-patterns.stories';

<Meta of={CardPatternsStories} />

<Title />
<Subtitle>Pre-composed card blocks for dashboards and feature pages — plus matching skeleton variants for loading states.</Subtitle>

<Description />

<Primary />

---

## Overview

Six composed card components built exclusively from `ui/` primitives — no external dependencies. Each card has a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders for use while data is loading.

| Card                | Skeleton companion         |
| ------------------- | -------------------------- |
| `ActivityCard`      | `ActivityCardSkeleton`     |
| `ProfileCard`       | `ProfileCardSkeleton`      |
| `ProjectCard`       | `ProjectCardSkeleton`      |
| `NotificationCard`  | `NotificationCardSkeleton` |
| `QuickActionCard`   | `QuickActionCardSkeleton`  |
| `FeatureCard`       | `FeatureCardSkeleton`      |

> A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`).

---

## Import

```tsx
// All cards and skeletons are re-exported from the root barrel
import {
  ActivityCard, ActivityCardSkeleton,
  ProfileCard, ProfileCardSkeleton,
  ProjectCard, ProjectCardSkeleton,
  NotificationCard, NotificationCardSkeleton,
  QuickActionCard, QuickActionCardSkeleton,
  FeatureCard, FeatureCardSkeleton,
} from 'xertica-ui';
```

---

## When to Use Cards

- You need a recurring dashboard pattern (activity feed, KPI, project status, notifications) and don't want to re-compose it from scratch in every feature.
- The pattern is stable and reused across multiple pages.

## When NOT to Use Cards

- One-off layouts specific to a single page — compose directly from `Card` and `ui/` primitives instead.
- When the pattern has significant data-fetching logic — keep the block as a pure presentational component and handle state in the feature layer.

---

## Loading-state pattern

Always pair each card with its matching `*Skeleton` for loading states — never render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives.

```tsx
function ActivityFeed() {
  const { data: items, isLoading } = useActivityItems();

  if (isLoading) return <ActivityCardSkeleton rows={5} />;
  return <ActivityCard items={items!} />;
}
```

For grids, render one skeleton per expected card:

```tsx
{isLoading ? (
  <>
    <FeatureCardSkeleton showAction />
    <FeatureCardSkeleton showAction />
    <FeatureCardSkeleton showAction />
  </>
) : (
  data.map(item => <FeatureCard key={item.id} {...item} />)
)}
```

---

## Skeleton configuration

Each skeleton accepts props that tune which layout regions are rendered, so the placeholder matches the loaded state exactly.

| Skeleton                   | Props                                       |
| -------------------------- | ------------------------------------------- |
| `ActivityCardSkeleton`     | `rows` (default `5`)                        |
| `ProfileCardSkeleton`      | `showStats`, `showActions`                  |
| `ProjectCardSkeleton`      | `memberCount` (default `3`)                 |
| `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll`         |
| `QuickActionCardSkeleton`  | —                                           |
| `FeatureCardSkeleton`      | `showAction`                                |
| `StatsCardSkeleton`        | `showIcon`, `showTrend`                     |

Set `rows={maxItems}` on list-style skeletons to match the loaded state's row count.

---

## Stories

<Stories />

---

## AI Rules

> [!IMPORTANT]
>
> - **Import block components from `xertica-ui`** — they are included in the root barrel.
> - **Pass all data as props** — never embed fetch calls inside block components.
> - **Keep `maxItems` at a sensible limit (4–6)** to avoid overflow in fixed-height containers.
> - **Always pair each card with its matching `*Skeleton`** — do not render a spinner or empty container while data fetches.
> - **Skeleton row counts should match the expected data count** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton`.
> - **For chart panels**, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`.
> - **`FeatureCard` badge wraps to a new line** when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout.