import { Canvas, Meta, Title, Subtitle } from '@storybook/addon-docs/blocks'
import * as UsePlaceholderRowsStories from './usePlaceholderRows.stories'
import { LifecycleTag } from '../../docs/components'

<Meta of={UsePlaceholderRowsStories} />

<Title>usePlaceholderRows</Title>
<Subtitle>
  A hook for generating placeholder rows during loading states, ideal for
  DataTable skeleton loading.
</Subtitle>
<LifecycleTag variant="Stable" />

<Canvas of={UsePlaceholderRowsStories.Default} sourceState="shown" />

## Overview

`usePlaceholderRows` generates an array of placeholder rows when loading, allowing you to render skeleton UI that matches the expected data length. When not loading, it returns the actual data.

> **When to use**: Use this hook when building custom table or list components that need skeleton loading states. If you're using `DataTable` or other table primitives, they handle loading states internally.

## Import

```tsx
import { usePlaceholderRows } from '@chainlink/blocks'
```

## Usage

```tsx
const tableData = usePlaceholderRows({
  data: myData,
  isLoading: isLoading,
  pageSize: 10,
})

<DataTable
  data={tableData.data}
  isLoading={tableData.isLoading}
/>
```

## API

### Options

| Property           | Type      | Description                                               |
| ------------------ | --------- | --------------------------------------------------------- |
| `data`             | `TData[]` | Actual data to display when loaded                        |
| `isLoading`        | `boolean` | Loading state                                             |
| `pageSize`         | `number`  | Page size for dynamic placeholder count (from pagination) |
| `placeholderCount` | `number`  | Custom placeholder count - overrides all other logic      |

### Returns

| Property    | Type                | Description                                    |
| ----------- | ------------------- | ---------------------------------------------- |
| `data`      | `TData[] \| null[]` | Actual data or array of nulls for placeholders |
| `isLoading` | `boolean`           | Loading state                                  |

## Placeholder Count Priority

When loading, the placeholder count is determined in this order:

1. **`placeholderCount`** - If provided, always uses this value
2. **`data.length`** - If data has items, uses data length
3. **`pageSize`** - If pagination is provided, uses pageSize
4. **Default**: 5

## Examples

### Custom Placeholder Count

<Canvas of={UsePlaceholderRowsStories.WithCustomCount} sourceState="shown" />