# VisibilityPlugin

> _Since v0.1.1_

Column Visibility Plugin for tbw-grid

Gives users control over which columns are displayed. Hide less important columns
by default, let users toggle them via a column chooser UI, or programmatically
show/hide columns based on user preferences or screen size.

> **Optional Enhancement:** When ReorderPlugin is also loaded, columns in the
> visibility panel become draggable for reordering.

## Installation

```ts
import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';
```

## Column Configuration

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `visible` | `boolean` | `true` | Initial visibility state |
| `lockVisible` | `boolean` | `false` | Prevent user from toggling (legacy `meta.lockVisibility` is honored) |

## CSS Custom Properties

| Property | Default | Description |
|----------|---------|-------------|
| `--tbw-visibility-hover` | `var(--tbw-color-row-hover)` | Row hover background |
| `--tbw-panel-padding` | `0.75em` | Panel content padding |
| `--tbw-panel-gap` | `0.5em` | Gap between items |

## Examples

### Columns Hidden by Default

```ts
import { queryGrid } from '@toolbox-web/grid';
import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'phone', header: 'Phone', visible: false }, // Hidden by default
    { field: 'address', header: 'Address', visible: false },
  ],
  plugins: [new VisibilityPlugin()],
};

// Toggle programmatically
const plugin = grid.getPluginByName('visibility');
plugin.showColumn('phone');
```

### With Drag-to-Reorder

```ts
import { VisibilityPlugin } from '@toolbox-web/grid/plugins/visibility';
import { ReorderPlugin } from '@toolbox-web/grid/plugins/reorder-columns';

grid.gridConfig = {
  plugins: [
    new ReorderPlugin(),      // Enables drag-drop in visibility panel
    new VisibilityPlugin(),
  ],
};
```

## See Also

- [`VisibilityConfig`](/grid/plugins/visibility/interfaces/visibilityconfig.md) for configuration options
- ReorderPlugin for drag-to-reorder integration

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `PANEL_ID` | <code>columns</code> | Tool panel ID for shell integration |

## Methods

### show()

Show the visibility sidebar panel.
Opens the tool panel and ensures this section is expanded.

```ts
show(): void
```

***

### hide()

Hide the visibility sidebar panel.

```ts
hide(): void
```

***

### toggle()

Toggle the visibility sidebar panel section.

```ts
toggle(): void
```

***

### isColumnVisible()

Check if a specific column is visible.
Delegates to grid.isColumnVisible().

```ts
isColumnVisible(field: string): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name to check |

#### Returns

`boolean` - True if the column is visible

***

### setColumnVisible()

Set visibility for a specific column.
Delegates to grid.setColumnVisible().

```ts
setColumnVisible(field: string, visible: boolean): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name of the column |
| `visible` | <code>boolean</code> | Whether the column should be visible |

***

### getVisibleColumns()

Get list of all visible column fields.

```ts
getVisibleColumns(): string[]
```

#### Returns

`string[]` - Array of visible field names

***

### getHiddenColumns()

Get list of all hidden column fields.

```ts
getHiddenColumns(): string[]
```

#### Returns

`string[]` - Array of hidden field names

***

### showAll()

Show all columns.
Delegates to grid.showAllColumns().

```ts
showAll(): void
```

***

### toggleColumn()

Toggle visibility for a specific column.
Delegates to grid.toggleColumnVisibility().

```ts
toggleColumn(field: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name of the column |

***

### showColumn()

Show a specific column.
Delegates to grid.setColumnVisible().

```ts
showColumn(field: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name of the column to show |

***

### hideColumn()

Hide a specific column.
Delegates to grid.setColumnVisible().

```ts
hideColumn(field: string): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name of the column to hide |

***

### getAllColumns()

Get all columns with their visibility status.
Useful for building visibility UI.

```ts
getAllColumns(): object[]
```

#### Returns

`object[]` - Array of column info with visibility status

***

### isPanelVisible()

Check if the sidebar panel is currently open.

```ts
isPanelVisible(): boolean
```

#### Returns

`boolean` - True if the panel section is expanded

***