Skip to content

Reusable Bubble Tea Components

shelfctl's TUI components have been extracted to five standalone Go modules. Each handles a common Bubble Tea pattern with production-tested behavior and consistent keyboard shortcuts.

Components

Component Package Purpose LOC
Base Picker bubbletea-picker Foundation for selection UIs — handles key bindings, resize, borders, error management ~200
Multi-Select bubbletea-multiselect Checkbox wrapper for any list.Item with persistent selection state ~300
Miller Columns bubbletea-millercolumns Hierarchical column navigation (macOS Finder style) ~400
Carousel bubbletea-carousel Peeking card layout with centered active card and adjacent previews ~350
Command Palette bubbletea-commandpalette Fuzzy-search action overlay (VS Code Ctrl+P style) ~365

Installation

go get github.com/blackwell-systems/bubbletea-picker
go get github.com/blackwell-systems/bubbletea-multiselect
go get github.com/blackwell-systems/bubbletea-millercolumns
go get github.com/blackwell-systems/bubbletea-carousel
go get github.com/blackwell-systems/bubbletea-commandpalette

Dependencies are limited to official Bubble Tea libraries (bubbles, bubbletea, lipgloss, x/ansi) plus sahilm/fuzzy for the command palette.

Usage in shelfctl

Base Picker

  • Shelf picker — select which shelf to operate on
  • Book picker — select books for edit/delete/move
  • Reduces picker boilerplate by ~60%

Multi-Select

  • Batch delete — select multiple books to remove
  • Batch move — select multiple books to relocate
  • Cache clear — select cached books to remove locally
  • Multi-file shelve — select multiple PDFs to add in one session
  • Selection state persists across list navigation

Miller Columns

  • File browser — navigate directories to select files for shelving
  • 3 columns visible simultaneously for hierarchy context
  • Combined with multi-select for checkbox state across directories
  • Batch edit — navigate between selected books as cards
  • Center card shows full metadata form, adjacent cards peek from edges
  • Green border = saved, orange = active, dot indicator for position

Command Palette

  • Hub quick actions — Ctrl+P opens fuzzy-search over all menu items
  • Searches by label, description, and hidden keywords
  • Selection emits NavigateMsg for instant view switching

API Documentation

Each component repository contains full API reference, usage examples, and integration guides. See the links in the table above.