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`

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 This Plugin 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.

Why It Matters

For developers: Prepared Actions keep navigation and optional integrations out of public Blade queries while the theme owns its progressive-enhancement boundary.

For teams: Visitors get a fast keyboard-first way to browse a content-heavy site, while ordinary links remain available for touch, assistive technology, and no-JavaScript use.

Screens And Workflow

The public chrome, command bar, no-JavaScript index, and optional integrations are defined in the screenshot contract. Screenshot files are release evidence only when produced by the supported capture runner.

Quick Start

Install the package: composer require capell-app/theme-switchboard.

The package has no migrations or settings.

Select the switchboard theme through Capell’s normal theme management surface.
In a disposable environment, install demo content with php artisan capell:theme-switchboard-demo --force.

Technical Shape

Typed Actions prepare the chrome and public index; package Blade components render the theme, and availability adapters keep optional integrations package-safe.

Data Model

Switchboard has no schema impact. It consumes prepared Core navigation and page data and keeps visitor trail and shortcut preferences in guarded browser storage.

Install Impact

Required packages: capell-app/core, capell-app/navigation, capell-app/theme-foundation, capell-app/frontend, and capell-app/layout-builder.
Database changes: none.
Command: capell:theme-switchboard-demo.
Public routes: none declared by the theme.

Common Pitfalls

Do not hand-maintain a second page index; use the prepared navigation render model.
Do not render a search form unless the Search package exposes the named route.
Keep visitor-specific trail and preference state in guarded browser storage, never server-rendered HTML.

Troubleshooting

If the theme is not visible after installation, refresh Composer autoload and clear host theme/config caches. If optional controls are absent, verify the corresponding package and named public routes are installed.

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

Run npm install --prefix packages/theme-switchboard, then npm run --prefix packages/theme-switchboard build, and finally 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 for package boundaries and integration details.