# Theme Switchboard

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/theme-switchboard` |
| Package slug | `theme-switchboard` |
| Product group | Capell Themes |
| Tier | premium |
| Bundle | `themes` |
| Runtime contexts | `frontend`, `console` |
| Capell version | `^1.0` |
| Catalogue role | extension |
| Release channel | Labs |
| Source repository | `capell-app/packages` |
| Source path | `packages/theme-switchboard` |
| Docs source | `packages/theme-switchboard/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/theme-switchboard/capell.json) |

Switchboard is a premium Capell theme for keyboard-first CLI products, developer tools, technical reference sites, recipe libraries, and changelogs. It requires Capell Navigation so the command index and the normal site navigation share one prepared render model.

Its permanent command bar is page chrome, not editor content. It renders on every page from the prepared navigation render model, preserves a complete server-rendered link index, and adds live content results only when the Search package and its named routes are available.

- Status: Available

## What it adds

- Three complete presets: Terminal, Card Catalogue, and Night Shift.
- Ten package-owned Layout Builder widgets plus man-page, ledger, and prompt section variants.
- A dependency-free frontend module for keyboard navigation, grouped results, a three-hop trail, card filtering, query recipe upgrades, clipboard controls, and the shortcut opt-out.
- Seven Hoist & Query demo surfaces installed with `capell:theme-switchboard-demo`.
- Optional Search, Bookings, Form Builder, Newsletter, Blog, Comments, and Widget Countdown enhancement points with useful fallbacks.

## Install

```bash
composer require capell-app/theme-switchboard
```

The package has no migrations or settings. Select Switchboard through Capell's normal theme management surface.

For demo content:

```bash
php artisan capell:theme-switchboard-demo --force
```

## Frontend behaviour

- `/` and `Cmd/Ctrl+K` open the command bar.
- Arrow keys move through results; `Alt+Arrow` and `PageUp/PageDown` move between result groups.
- `g h`, `g d`, and `g c` open Home, Browse, and Contact unless single-key shortcuts are disabled.
- `Tab` closes the panel without trapping focus.
- Without JavaScript, visitors retain the complete page index and all ordinary destination links. A GET search form is rendered only when the Search package provides the named route.

The module stores only `swb:hints-dismissed`, `swb:shortcuts-disabled`, and `swb:trail`. All storage access is guarded, and server output never varies by visitor state.

## Development

```bash
npm install --prefix packages/theme-switchboard
npm run --prefix packages/theme-switchboard build
vendor/bin/pest packages/theme-switchboard/tests --configuration=phpunit.xml
```

The generated module and `publishes/build/manifest.json` are committed package artifacts. Run `npm run --prefix packages/theme-switchboard build:check` to verify they are current.

See [docs/overview.md](overview.md) for package boundaries and integration details.