import { Meta, Canvas, ArgTypes } from '@storybook/addon-docs/blocks'
import * as ColumnSpanStories from './column-spans.stories.tsx'

<Meta title="pv-grid/Components/Grid/Column spans" />

# Column spans

Column spans are used to render a single cell that spans multiple columns in the grid. Currently, only body cells in the grid can be spanned, but which cells are spanned can be configured per row.

## Configuration

Spanning is configured by adding a `colSpan` property to the cell object in the column definition. The `colSpan` property can be an array of column ids or a function that returns an array of column ids. The function will be called with the following parameters:

- `row` - the row object for the current row
- `rowMeta` - the row meta object for the current row
- `columnId` - the id of the column for which the cell is being rendered
- `sortedColumnIds` - the current array of visible, sorted column ids. Return this object from the callback if you want your cell to span all columns in the grid.

## Best practices and considerations

- Use column spans sparingly. Too many merged cells can make the grid difficult to read and understand.
- Be sure to consider other grid features such as reordering, hiding, and grouping. In some cases it may be better to turn off a feature than risk confusion with spanned cells.
- When sticky columns are used, the column spans only work within their region: Sticky left, middle, sticky right. A column span cannot span across sticky regions.
- Column spans are not supported in the header or footer rows.

## Usage

```tsx
/* Only colSpan relevant details included below, see source of the demo below for full code */
const columns: Columns<UserWithSkill> = [
    {
        id: 'firstName',
        label: 'First',
        cell: {
            /* Always merge cells */
            colSpan: ['firstName', 'lastName'],
        },
    },
    {
        id: 'lastName',
        label: 'Last',
    },
    {
        id: 'age',
        label: 'Age',
    },
    {
        id: 'skill',
        label: 'Skill',
        cell: {
            colSpan: ({ row }) => {
                if (row.skill === 'None') {
                    /* Merge cells only if skill is none */
                    return ['skill', 'skillDetails']
                }
                return []
            },
        },
    },
    {
        id: 'skillDetails',
        label: 'Skill Details',
    },
]
```

In the example below, some cells are always merged and some cells are merged only if the row data meets certain criteria. The merged cells are shown with a different background color for this example only so you can see the impact of moving columns around.

<Canvas of={ColumnSpanStories.BasicUsage} />