npm package: @polarityio/pi-tab
Description: Tab, tab group, and tab panel components for tabbed navigation
Latest version: 1.0.3

# Polarity Integration Component Library

## Tab Component

A tab interface consisting of three components — `<pi-tab>`, `<pi-tab-group>`, and `<pi-tab-panel>` — that work together to provide accessible tabbed navigation with keyboard support.

## Installation

```bash
npm install @polarityio/pi-tab
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-tab';
```

### Basic Tabs

```html
<pi-tab-group>
  <pi-tab slot="tab" panel="general" active>General</pi-tab>
  <pi-tab slot="tab" panel="settings">Settings</pi-tab>
  <pi-tab slot="tab" panel="advanced">Advanced</pi-tab>

  <pi-tab-panel slot="panel" active>General content here.</pi-tab-panel>
  <pi-tab-panel slot="panel">Settings content here.</pi-tab-panel>
  <pi-tab-panel slot="panel">Advanced content here.</pi-tab-panel>
</pi-tab-group>
```

### Vertical Tabs with Auto Activation

```html
<pi-tab-group placement="start" activation="auto">
  <pi-tab slot="tab" panel="one">Tab One</pi-tab>
  <pi-tab slot="tab" panel="two">Tab Two</pi-tab>
  <pi-tab slot="tab" panel="three" disabled>Disabled</pi-tab>

  <pi-tab-panel slot="panel">Content one.</pi-tab-panel>
  <pi-tab-panel slot="panel">Content two.</pi-tab-panel>
  <pi-tab-panel slot="panel">Content three.</pi-tab-panel>
</pi-tab-group>
```

---

## API Reference

### `<pi-tab-group>`

The container component that manages tab selection, keyboard navigation, and panel visibility.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `'top' \| 'bottom' \| 'start' \| 'end'` | `'top'` | Position of tabs relative to the panels. `start`/`end` produce a vertical layout. Reflected to attribute. |
| `activation` | `'manual' \| 'auto'` | `'manual'` | Tab activation mode. `manual` requires Enter/Space to activate; `auto` activates on arrow key focus. Reflected to attribute. |

#### Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-tab-change` | `{ tab: PiTab, tabIndex: number }` | Fired when the active tab changes. Bubbles and is composed. |

#### Slots

| Slot Name | Description |
| --- | --- |
| `tab` | Slot for `<pi-tab>` elements. |
| `panel` | Slot for `<pi-tab-panel>` elements. |

#### CSS Parts

| Part Name | Description |
| --- | --- |
| `tab-nav` | The tab navigation container (has `role="tablist"`). |
| `tab-panels` | The tab panels container. |

#### Keyboard Navigation

| Key | Horizontal (`top`/`bottom`) | Vertical (`start`/`end`) |
| --- | --- | --- |
| Arrow Right | Focus next tab | — |
| Arrow Left | Focus previous tab | — |
| Arrow Down | — | Focus next tab |
| Arrow Up | — | Focus previous tab |
| Home | Focus first enabled tab | Focus first enabled tab |
| End | Focus last enabled tab | Focus last enabled tab |
| Enter / Space | Activate focused tab | Activate focused tab |

In `auto` activation mode, arrow keys both move focus and activate the tab. Navigation wraps around and skips disabled tabs.

---

### `<pi-tab>`

An individual tab element placed inside a `<pi-tab-group>`.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Whether this tab is currently active. Reflected to attribute. |
| `disabled` | `boolean` | `false` | Disables the tab, preventing interaction. Reflected to attribute. |
| `panel` | `string` | `''` | Identifier of the associated tab panel. |

#### Slots

| Slot Name | Description |
| --- | --- |
| `prefix-icon` | Icon displayed before the tab label. |
| _(default)_ | Tab label content. |
| `counter` | Badge or counter displayed alongside the label. |
| `suffix-icon` | Icon displayed after the tab label. |

#### CSS Parts

| Part Name | Description |
| --- | --- |
| `tab` | The main tab element container. |

---

### `<pi-tab-panel>`

A content panel associated with a tab, shown when its corresponding tab is active.

#### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Whether this panel is visible. Reflected to attribute. |

#### Slots

| Slot Name | Description |
| --- | --- |
| _(default)_ | Panel content displayed when active. |

#### CSS Parts

| Part Name | Description |
| --- | --- |
| `panel` | The panel container element. |

---

## Accessibility

- `<pi-tab>` elements have `role="tab"` with `aria-selected` and `aria-disabled`.
- `<pi-tab-group>` manages `role="tablist"` on the navigation container.
- `<pi-tab-panel>` elements have `role="tabpanel"` with `aria-hidden` when inactive.
- ARIA relationships (`aria-controls`, `aria-labelledby`) are automatically linked between tabs and panels.
- Focus management follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apd/patterns/tabs/).

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

## License

MIT