# Tabbed Interface Web Component

[![npm version](https://img.shields.io/npm/v/@aarongustafson/tabbed-interface.svg)](https://www.npmjs.com/package/@aarongustafson/tabbed-interface)
[![CI status](https://img.shields.io/github/actions/workflow/status/aarongustafson/tabbed-interface/ci.yml?branch=main&label=CI)](https://github.com/aarongustafson/tabbed-interface/actions/workflows/ci.yml)
[![Minified + gzipped size](https://img.shields.io/bundlejs/size/@aarongustafson/tabbed-interface?format=minzip&label=min%2Bgzip)](https://bundlejs.com/?q=@aarongustafson/tabbed-interface)
[![License](https://img.shields.io/npm/l/@aarongustafson/tabbed-interface)](https://github.com/aarongustafson/tabbed-interface/blob/main/LICENSE)
[![Type definitions](https://img.shields.io/npm/types/@aarongustafson/tabbed-interface)](https://github.com/aarongustafson/tabbed-interface/blob/main/tabbed-interface.d.ts)

A web component that turns heading-structured content into tabs with keyboard
navigation and named panels. When the tabs do not fit, it shows the original
sections in reading order. Without JavaScript, or if the module fails to load,
the authored headings and content remain readable.

This is a web component port of Aaron Gustafson’s original
[TabInterface](https://github.com/easy-designs/TabInterface.js).

## Demo

- [Live Demo](https://aarongustafson.github.io/tabbed-interface/demo/) ([Source](./demo/index.html))
- [unpkg Demo](https://aarongustafson.github.io/tabbed-interface/demo/unpkg.html) ([Source](./demo/unpkg.html))
- [esm.sh Demo](https://aarongustafson.github.io/tabbed-interface/demo/esm.html) ([Source](./demo/esm.html))

## Features

- **Progressive Enhancement**: Works with semantic HTML structure
- **Accessibility**: Full ARIA support and keyboard navigation
- **Customizable**: Extensive CSS custom properties for styling
- **Lightweight**: No dependencies, pure vanilla JavaScript
- **Modern**: Uses Shadow DOM and ES Modules
- **TypeScript-ready**: Ships bundled type definitions for editors and build tooling

## TypeScript & Framework Support

- Bundled `.d.ts` files describe both `TabbedInterfaceElement` and `defineTabbedInterface`, so editors, bundlers, and framework toolchains get type information automatically.
- The `showHeaders`, `tablistAfter`, `autoActivate`, and `defaultTab` properties reflect to attributes, keeping declarative markup and imperative code in sync.
- A private `upgradeProperty` helper replays any property assignments that happen before the browser upgrades the element, which is especially helpful for SSR and hydration workflows.
- The `defaultTab` property accepts either zero-based indices or heading IDs, making it easy to drive tab selection from reactive state or router parameters.

## Installation

```bash
npm install @aarongustafson/tabbed-interface
```

## Usage

### Basic Usage

```html
<tabbed-interface>
  <h2>First Tab</h2>
  <p>Content for the first tab panel.</p>

  <h2>Second Tab</h2>
  <p>Content for the second tab panel.</p>

  <h2>Third Tab</h2>
  <p>Content for the third tab panel.</p>
</tabbed-interface>

<script type="module">
  import '@aarongustafson/tabbed-interface/define.js';
</script>
```

### Import Options

**Auto-define (browser environments only):**

```javascript
import '@aarongustafson/tabbed-interface/define.js';
// Registers <tabbed-interface> when customElements is available
```

Prefer to control when registration happens? Call the helper directly:

```javascript
import { defineTabbedInterface } from '@aarongustafson/tabbed-interface/define.js';

defineTabbedInterface();
```

**Manual registration:**

```javascript
import { TabbedInterfaceElement } from '@aarongustafson/tabbed-interface';
customElements.define('my-tabs', TabbedInterfaceElement);
```

## Attributes

| Attribute       | Type    | Default | Description                                                                    |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------ |
| `show-headers`  | boolean | `false` | When present, shows headings in tab panels                                     |
| `tablist-after` | boolean | `false` | When present, positions tab list after content                                 |
| `default-tab`   | string  | `"0"`   | Initial active tab (index or heading ID)                                       |
| `auto-activate` | boolean | `false` | When present, tabs activate on focus; when absent, use Enter/Space to activate |
| `fixed-tabs`    | boolean | `false` | When present, keeps tabs active even when the complete tablist does not fit    |

### Examples

```html
<!-- Show headings in panels -->
<tabbed-interface show-headers> ... </tabbed-interface>

<!-- Tabs after content -->
<tabbed-interface tablist-after> ... </tabbed-interface>

<!-- Start on specific tab -->
<tabbed-interface default-tab="2"> ... </tabbed-interface>

<!-- Start on tab by heading ID -->
<tabbed-interface default-tab="features">
  <h2 id="intro">Introduction</h2>
  <p>...</p>
  <h2 id="features">Features</h2>
  <p>...</p>
</tabbed-interface>

<!-- Auto-activation (tabs activate on focus) -->
<tabbed-interface auto-activate> ... </tabbed-interface>

<!-- Always use tabs; the implementor handles any overflow -->
<tabbed-interface fixed-tabs> ... </tabbed-interface>
```

## Responsive Behavior

The component uses tabs only when the complete, styled tablist fits on one horizontal row. Tab labels may wrap within their buttons. If the tablist does not fit, the component automatically presents the original content as fully expanded linear sections with visible headings.

Fit is based on rendered styles rather than a viewport breakpoint. Fonts, padding, borders, CSS parts, custom properties, selected-tab styling, translated labels, and container resizing all participate in the calculation.

Use `fixed-tabs` only when you want tabs at every available width and will handle overflow yourself.

The current presentation is reflected as `data-layout="tabs"` or `data-layout="linear"` on the component for state-specific styling:

```css
tabbed-interface[data-layout='linear'] {
  margin-block: 2rem;
}
```

## Properties

| Property       | Type    | Description                                             |
| -------------- | ------- | ------------------------------------------------------- |
| `activeIndex`  | number  | Get/set the currently active tab index                  |
| `showHeaders`  | boolean | Get/set header visibility                               |
| `tablistAfter` | boolean | Get/set tablist position                                |
| `autoActivate` | boolean | Get/set auto-activation behavior                        |
| `fixedTabs`    | boolean | Get/set whether tabs remain active when they do not fit |

## Methods

| Method       | Description                  |
| ------------ | ---------------------------- |
| `next()`     | Navigate to the next tab     |
| `previous()` | Navigate to the previous tab |
| `first()`    | Navigate to the first tab    |
| `last()`     | Navigate to the last tab     |

### Programmatic Control

```javascript
const $tabs = document.querySelector('tabbed-interface');

// Navigate
$tabs.next();
$tabs.previous();
$tabs.first();
$tabs.last();

// Set active tab directly
$tabs.activeIndex = 2;
```

## Events

| Event                     | Detail                            | Description                   |
| ------------------------- | --------------------------------- | ----------------------------- |
| `tabbed-interface:change` | `{ tabId, tabpanelId, tabIndex }` | Fired when active tab changes |

```javascript
document
  .querySelector('tabbed-interface')
  .addEventListener('tabbed-interface:change', (e) => {
    console.log(`Switched to tab ${e.detail.tabIndex}`);
  });
```

## Keyboard Navigation

| Key                | Action                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------- |
| `Arrow Left/Up`    | Previous tab                                                                           |
| `Arrow Right/Down` | Next tab                                                                               |
| `Home`             | First tab                                                                              |
| `End`              | Last tab                                                                               |
| `Enter/Space`      | Activate tab (when auto-activate is absent) and focus first focusable element in panel |

## Styling

### Authored panel content

Panel content remains in light DOM and retains its original node identity. Style the content you own with ordinary selectors:

```css
.article tabbed-interface p {
  max-inline-size: 65ch;
}

.article tabbed-interface .callout {
  padding: 1rem;
  background: var(--callout-background);
}
```

Event listeners, live form values, form ownership, nested custom elements, IDs, and runtime state remain attached to the visible authored nodes.

### Component structure

Style the component's shadow DOM elements using CSS `::part()` selectors:

### Available Parts

| Part       | Description                     |
| ---------- | ------------------------------- |
| `tablist`  | The container for all tabs      |
| `tab`      | Individual tab buttons          |
| `selected` | The currently selected tab      |
| `tabpanel` | Individual tab panel containers |

### Styling Examples

Defaults use `ButtonText` on `ButtonFace` for ordinary and hovered/focused tabs,
and `CanvasText` on `Canvas` for the selected tab. In forced colors, selection
also has a two-pixel underline so it remains distinguishable when user colors
flatten the surfaces. The underline is off in ordinary light/dark mode and
does not change the tab’s measured size. Browsers without `forced-colors`
media-query support retain the underline as a fallback.

Keyboard focus uses the browser’s native outline unless you set
`--tabbed-interface-tab-focus-outline` or a `::part(tab):focus-visible` rule.
Selection and focus are separate: with manual activation, an arrow key can
focus an unselected tab without changing selection or, in forced colors,
moving the selected underline.

Pair every custom background with a readable foreground, including hover/focus
and selected states. Panels are transparent and inherit their host foreground
by default; if you paint a panel, set its foreground with `::part(tabpanel)`.
Keep automatic forced-color adjustment enabled, and check your actual
surfaces, keyboard focus, and reading order. System-color pairs and automated
checks do not guarantee contrast for every browser or user palette.

**Migration:** hover/focus text previously inherited the host foreground.
It now defaults to `ButtonText`. If your theme overrides a hover/focus fill,
set `--tabbed-interface-tab-hover-color` too. Existing color hooks and parts
remain supported. To replace the forced-color selected underline, provide an
equally clear non-color selected cue through `::part(selected)`.

**Basic styling:**

```css
tabbed-interface::part(tablist) {
  gap: 4px;
  background: #f0f0f0;
  padding: 8px;
}

tabbed-interface::part(tab) {
  padding: 0.75em 1.5em;
  background: white;
  color: #202020;
  border: 1px solid #202020;
  border-radius: 4px 4px 0 0;
  font-weight: 500;
}

tabbed-interface::part(tab):hover {
  background: #e9e9e9;
  color: #202020;
}

tabbed-interface::part(tabpanel) {
  padding: 2em;
  border: 1px solid #202020;
  background: white;
  color: #202020;
}
```

**Targeting specific states:**

```css
/* Active tab */
tabbed-interface::part(selected) {
  background: white;
  color: #202020;
  border-bottom-color: white;
  font-weight: bold;
}

/* Focus styles */
tabbed-interface::part(tab):focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 2px;
}
```

**Themed variations:**

```css
/* Pills style */
.pills::part(tablist) {
  gap: 8px;
  background: transparent;
}

.pills::part(tab) {
  border-radius: 20px;
  background: ButtonFace;
  color: ButtonText;
  border: 1px solid ButtonText;
}

.pills::part(selected) {
  background: CanvasText;
  color: Canvas;
  border-color: CanvasText;
}

/* Minimal style */
.minimal::part(tab) {
  border: none;
  border-bottom: 2px solid transparent;
  border-radius: 0;
  background: Canvas;
  color: CanvasText;
}

.minimal::part(selected) {
  background: Canvas;
  color: CanvasText;
  border-bottom-color: CanvasText;
}

.minimal::part(tabpanel) {
  border: none;
  padding-top: 1.5em;
}
```

The responsive measurement probe receives the same parts and inherited styles as the visible tablist. Keep hover and focus styles metric-stable; normal and selected states are included in fit calculation.

### CSS custom properties

CSS custom properties offer convenient theme-level control without replacing parts:

| Property                                   | Purpose                                              |
| ------------------------------------------ | ---------------------------------------------------- |
| `--tabbed-interface-font-family`           | Component font family                                |
| `--tabbed-interface-tablist-display`       | Tablist display mode                                 |
| `--tabbed-interface-tablist-gap`           | Gap between tabs                                     |
| `--tabbed-interface-tablist-padding`       | Tablist padding                                      |
| `--tabbed-interface-tablist-margin`        | Tablist margin                                       |
| `--tabbed-interface-tablist-background`    | Tablist background                                   |
| `--tabbed-interface-tablist-border`        | Tablist border                                       |
| `--tabbed-interface-tab-padding`           | Tab padding                                          |
| `--tabbed-interface-tab-background`        | Default tab background (`ButtonFace`)                |
| `--tabbed-interface-tab-color`             | Default tab text color (`ButtonText`)                |
| `--tabbed-interface-tab-border`            | Tab border (`1px solid currentColor`)                |
| `--tabbed-interface-tab-border-radius`     | Tab border radius                                    |
| `--tabbed-interface-tab-active-background` | Selected tab background (`Canvas`)                   |
| `--tabbed-interface-tab-active-color`      | Selected tab text color (`CanvasText`)               |
| `--tabbed-interface-tab-hover-background`  | Hover/focus background (`ButtonFace`)                |
| `--tabbed-interface-tab-hover-color`       | Hover/focus text color (`ButtonText`)                |
| `--tabbed-interface-tab-focus-outline`     | Keyboard focus outline (browser-native via `revert`) |
| `--tabbed-interface-tabpanel-padding`      | Panel padding                                        |
| `--tabbed-interface-tabpanel-background`   | Panel background                                     |
| `--tabbed-interface-tabpanel-border`       | Panel border                                         |

## Printing

Print mode hides the tab controls and reveals every section and original heading in source order. The on-screen selected tab and responsive presentation are restored after printing.

## Custom Tab Titles

Use `data-tab-short-name` to show a different label in the tab than the heading. The full heading text is set as the `aria-label` for screen readers:

```html
<tabbed-interface>
  <h2 data-tab-short-name="Intro">Introduction and Getting Started Guide</h2>
  <p>Full content with the complete heading visible in the panel.</p>
</tabbed-interface>
```

## Hash Navigation

The component supports URL hash navigation. Link to specific tabs:

```html
<a href="#features">Go to Features</a>

<tabbed-interface>
  <h2 id="intro">Introduction</h2>
  <p>...</p>
  <h2 id="features">Features</h2>
  <p>...</p>
</tabbed-interface>
```

## Browser Support

Works in all modern browsers supporting:

- Custom Elements v1
- Shadow DOM v1
- ES Modules

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests once
npm run test:run

# Lint
npm run lint

# Format code
npm run format
```

## License

MIT - See [LICENSE](LICENSE)

## Credits

Based on the [jQuery TabInterface plugin](https://github.com/easy-designs/jquery.TabInterface.js) by Aaron Gustafson, which is itself a port of his original [TabInterface](https://github.com/easy-designs/TabInterface.js).
