@@ -0,0 +1,647 @@
1+# Bubbletea Components Catalog
2+
3+Reusable components for building TUI applications. All components follow the Elm architecture pattern (Init, Update, View).
4+
5+## Panel System
6+
7+Pre-built panel layouts for different UI arrangements.
8+
9+### Single Panel
10+
11+Full-screen single view with optional title and status bars.
12+
13+**Use for:**
14+- Simple focused interfaces
15+- Full-screen text editors
16+- Single-purpose tools
17+
18+**Implementation:**
19+```go
20+func (m model) renderSinglePanel() string {
21+ contentWidth, contentHeight := m.calculateLayout()
22+
23+ // Create panel with full available space
24+ panel := m.styles.Panel.
25+ Width(contentWidth).
26+ Render(content)
27+
28+ return panel
29+}
30+```
31+
32+### Dual Pane
33+
34+Side-by-side panels with configurable split ratio and accordion mode.
35+
36+**Use for:**
37+- File browsers with preview
38+- Split editors
39+- Source/destination views
40+
41+**Features:**
42+- Dynamic split ratio (50/50, 66/33, 75/25)
43+- Accordion mode (focused panel expands)
44+- Responsive (stacks vertically on narrow terminals)
45+- Weight-based sizing for smooth resizing
46+
47+**Implementation:**
48+```go
49+func (m model) renderDualPane() string {
50+ contentWidth, contentHeight := m.calculateLayout()
51+
52+ // Calculate weights based on focus/accordion
53+ leftWeight, rightWeight := 1, 1
54+ if m.accordionMode && m.focusedPanel == "left" {
55+ leftWeight = 2
56+ }
57+
58+ // Calculate actual widths from weights
59+ totalWeight := leftWeight + rightWeight
60+ leftWidth := (contentWidth * leftWeight) / totalWeight
61+ rightWidth := contentWidth - leftWidth
62+
63+ // Render panels
64+ leftPanel := m.renderPanel("left", leftWidth, contentHeight)
65+ rightPanel := m.renderPanel("right", rightWidth, contentHeight)
66+
67+ return lipgloss.JoinHorizontal(lipgloss.Top, leftPanel, rightPanel)
68+}
69+```
70+
71+**Keyboard shortcuts:**
72+- `Tab` - Switch focus between panels
73+- `a` - Toggle accordion mode
74+- Arrow keys - Focus panel in direction
75+
76+**Mouse support:**
77+- Click panel to focus
78+- Works in both horizontal and vertical stack modes
79+
80+### Multi-Panel
81+
82+3+ panels with configurable sizes and arrangements.
83+
84+**Use for:**
85+- IDEs (file tree, editor, terminal, output)
86+- Dashboard views
87+- Complex workflows
88+
89+**Common layouts:**
90+- Three-column (25/50/25)
91+- Three-row
92+- Grid (2x2, 3x3)
93+- Sidebar + main + inspector
94+
95+**Implementation:**
96+```go
97+// Three-column example
98+mainWeight, leftWeight, rightWeight := 2, 1, 1 // 50/25/25
99+totalWeight := mainWeight + leftWeight + rightWeight
100+
101+leftWidth := (contentWidth * leftWeight) / totalWeight
102+mainWidth := (contentWidth * mainWeight) / totalWeight
103+rightWidth := contentWidth - leftWidth - mainWidth
104+```
105+
106+### Tabbed
107+
108+Multiple views with tab switching.
109+
110+**Use for:**
111+- Multiple documents
112+- Settings pages
113+- Different data views
114+
115+**Features:**
116+- Tab bar with active indicator
117+- Keyboard shortcuts (`1-9`, `Ctrl+Tab`)
118+- Mouse click to switch tabs
119+- Close tab support
120+
121+## Lists
122+
123+### Simple List
124+
125+Basic scrollable list of items.
126+
127+**Use for:**
128+- File listings
129+- Menu options
130+- Search results
131+
132+**Features:**
133+- Keyboard navigation (Up/Down, Home/End, PgUp/PgDn)
134+- Mouse scrolling and selection
135+- Visual selection indicator
136+- Viewport scrolling (only visible items rendered)
137+
138+**Integration:**
139+```go
140+import "github.com/charmbracelet/bubbles/list"
141+
142+type model struct {
143+ list list.Model
144+}
145+
146+func (m model) Init() tea.Cmd {
147+ items := []list.Item{
148+ item{title: "Item 1", desc: "Description 1"},
149+ item{title: "Item 2", desc: "Description 2"},
150+ }
151+ m.list = list.New(items, list.NewDefaultDelegate(), 0, 0)
152+ return nil
153+}
154+```
155+
156+### Filtered List
157+
158+List with fuzzy search/filter.
159+
160+**Use for:**
161+- Quick file finder
162+- Command palette
163+- Searchable settings
164+
165+**Features:**
166+- Real-time filtering as you type
167+- Fuzzy matching
168+- Highlighted matches
169+
170+**Dependencies:**
171+```go
172+github.com/koki-develop/go-fzf
173+```
174+
175+### Tree View
176+
177+Hierarchical list with expand/collapse.
178+
179+**Use for:**
180+- Directory trees
181+- Nested data structures
182+- Outline views
183+
184+**Features:**
185+- Expand/collapse nodes
186+- Indentation levels
187+- Parent/child relationships
188+- Recursive rendering
189+
190+## Input Components
191+
192+### Text Input
193+
194+Single-line text field.
195+
196+**Use for:**
197+- Forms
198+- Search boxes
199+- Prompts
200+
201+**Integration:**
202+```go
203+import "github.com/charmbracelet/bubbles/textinput"
204+
205+type model struct {
206+ input textinput.Model
207+}
208+
209+func (m model) Init() tea.Cmd {
210+ m.input = textinput.New()
211+ m.input.Placeholder = "Enter text..."
212+ m.input.Focus()
213+ return textinput.Blink
214+}
215+```
216+
217+### Multiline Input
218+
219+Text area for longer content.
220+
221+**Use for:**
222+- Commit messages
223+- Notes
224+- Configuration editing
225+
226+**Integration:**
227+```go
228+import "github.com/charmbracelet/bubbles/textarea"
229+
230+type model struct {
231+ textarea textarea.Model
232+}
233+```
234+
235+### Forms
236+
237+Structured input with multiple fields.
238+
239+**Use for:**
240+- Settings dialogs
241+- User registration
242+- Multi-field input
243+
244+**Integration:**
245+```go
246+import "github.com/charmbracelet/huh"
247+
248+form := huh.NewForm(
249+ huh.NewGroup(
250+ huh.NewInput().
251+ Title("Name").
252+ Value(&name),
253+ huh.NewInput().
254+ Title("Email").
255+ Value(&email),
256+ ),
257+)
258+```
259+
260+### Autocomplete
261+
262+Text input with suggestions.
263+
264+**Use for:**
265+- Command entry
266+- File paths
267+- Tag selection
268+
269+**Features:**
270+- Real-time suggestions
271+- Keyboard navigation of suggestions
272+- Tab completion
273+
274+## Dialogs
275+
276+### Confirm Dialog
277+
278+Yes/No confirmation.
279+
280+**Use for:**
281+- Delete confirmations
282+- Save prompts
283+- Destructive actions
284+
285+**Example:**
286+```
287+┌─────────────────────────────┐
288+│ Delete this file? │
289+│ │
290+│ [Yes] [No] │
291+└─────────────────────────────┘
292+```
293+
294+### Input Dialog
295+
296+Prompt for single value.
297+
298+**Use for:**
299+- Quick input
300+- Rename operations
301+- New file creation
302+
303+### Progress Dialog
304+
305+Show long-running operations.
306+
307+**Use for:**
308+- File uploads
309+- Build processes
310+- Data processing
311+
312+**Integration:**
313+```go
314+import "github.com/charmbracelet/bubbles/progress"
315+
316+type model struct {
317+ progress progress.Model
318+}
319+```
320+
321+### Modal
322+
323+Full overlay dialog.
324+
325+**Use for:**
326+- Settings
327+- Help screens
328+- Complex forms
329+
330+## Menus
331+
332+### Context Menu
333+
334+Right-click or keyboard-triggered menu.
335+
336+**Use for:**
337+- File operations
338+- Quick actions
339+- Tool integration
340+
341+**Example:**
342+```
343+┌─────────────┐
344+│ Open │
345+│ Copy │
346+│ Delete │
347+│ Properties │
348+└─────────────┘
349+```
350+
351+### Command Palette
352+
353+Fuzzy searchable command list.
354+
355+**Use for:**
356+- Command discovery
357+- Keyboard-first workflows
358+- Power user features
359+
360+**Keyboard:**
361+- `Ctrl+P` or `Ctrl+Shift+P` to open
362+- Type to filter
363+- Enter to execute
364+
365+### Menu Bar
366+
367+Top-level menu system.
368+
369+**Use for:**
370+- Traditional application menus
371+- Organized commands
372+- Discoverability
373+
374+**Example:**
375+```
376+File Edit View Help
377+```
378+
379+## Status Components
380+
381+### Status Bar
382+
383+Bottom bar showing state and help.
384+
385+**Use for:**
386+- Current mode/state
387+- Keyboard hints
388+- File info
389+
390+**Example:**
391+```
392+┌────────────────────────────────────┐
393+│ │
394+│ Content area │
395+│ │
396+├────────────────────────────────────┤
397+│ Normal | file.txt | Line 10/100 │
398+└────────────────────────────────────┘
399+```
400+
401+**Pattern:**
402+```go
403+func (m model) renderStatusBar() string {
404+ left := fmt.Sprintf("%s | %s", m.mode, m.filename)
405+ right := fmt.Sprintf("Line %d/%d", m.cursor, m.lineCount)
406+
407+ width := m.width
408+ gap := width - lipgloss.Width(left) - lipgloss.Width(right)
409+
410+ return left + strings.Repeat(" ", gap) + right
411+}
412+```
413+
414+### Title Bar
415+
416+Top bar with app title and context.
417+
418+**Use for:**
419+- Application name
420+- Current path/document
421+- Action buttons
422+
423+### Breadcrumbs
424+
425+Path navigation component.
426+
427+**Use for:**
428+- Directory navigation
429+- Nested views
430+- History trail
431+
432+**Example:**
433+```
434+Home > Projects > TUITemplate > components
435+```
436+
437+## Preview Components
438+
439+### Text Preview
440+
441+Rendered text with syntax highlighting.
442+
443+**Use for:**
444+- File preview
445+- Code display
446+- Log viewing
447+
448+**Integration:**
449+```go
450+import "github.com/alecthomas/chroma/v2/quick"
451+
452+func renderCode(code, language string) string {
453+ var buf bytes.Buffer
454+ quick.Highlight(&buf, code, language, "terminal256", "monokai")
455+ return buf.String()
456+}
457+```
458+
459+### Markdown Preview
460+
461+Rendered markdown.
462+
463+**Integration:**
464+```go
465+import "github.com/charmbracelet/glamour"
466+
467+func renderMarkdown(md string) (string, error) {
468+ renderer, _ := glamour.NewTermRenderer(
469+ glamour.WithAutoStyle(),
470+ glamour.WithWordWrap(80),
471+ )
472+ return renderer.Render(md)
473+}
474+```
475+
476+### Image Preview
477+
478+ASCII/Unicode art from images.
479+
480+**Use for:**
481+- Image thumbnails
482+- Visual file preview
483+- Logos/artwork
484+
485+**External tools:**
486+- `catimg` - Convert images to 256-color ASCII
487+- `viu` - View images in terminal with full color
488+
489+### Hex Preview
490+
491+Binary file viewer.
492+
493+**Use for:**
494+- Binary file inspection
495+- Debugging
496+- Data analysis
497+
498+**Example:**
499+```
500+00000000: 7f45 4c46 0201 0100 0000 0000 0000 0000 .ELF............
501+00000010: 0200 3e00 0100 0000 6009 4000 0000 0000 ..>.....`.@.....
502+```
503+
504+## Tables
505+
506+### Simple Table
507+
508+Static data display.
509+
510+**Use for:**
511+- Data display
512+- Reports
513+- Comparison views
514+
515+### Interactive Table
516+
517+Navigable table with selection.
518+
519+**Use for:**
520+- Database browsers
521+- CSV viewers
522+- Process lists
523+
524+**Integration:**
525+```go
526+import "github.com/evertras/bubble-table/table"
527+
528+type model struct {
529+ table table.Model
530+}
531+
532+func (m model) Init() tea.Cmd {
533+ m.table = table.New([]table.Column{
534+ table.NewColumn("id", "ID", 10),
535+ table.NewColumn("name", "Name", 20),
536+ })
537+ return nil
538+}
539+```
540+
541+**Features:**
542+- Sort by column
543+- Row selection
544+- Keyboard navigation
545+- Column resize
546+
547+## Component Integration Patterns
548+
549+### Composing Components
550+
551+```go
552+type model struct {
553+ // Multiple components in one view
554+ list list.Model
555+ preview string
556+ input textinput.Model
557+ focused string // which component has focus
558+}
559+
560+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
561+ switch msg := msg.(type) {
562+ case tea.KeyMsg:
563+ // Route to focused component
564+ switch m.focused {
565+ case "list":
566+ var cmd tea.Cmd
567+ m.list, cmd = m.list.Update(msg)
568+ return m, cmd
569+ case "input":
570+ var cmd tea.Cmd
571+ m.input, cmd = m.input.Update(msg)
572+ return m, cmd
573+ }
574+ }
575+ return m, nil
576+}
577+```
578+
579+### Lazy Loading Components
580+
581+Only initialize components when needed:
582+
583+```go
584+type model struct {
585+ preview *PreviewComponent // nil until needed
586+ previewPath string
587+}
588+
589+func (m *model) showPreview(path string) {
590+ if m.preview == nil {
591+ m.preview = NewPreviewComponent()
592+ }
593+ m.preview.Load(path)
594+}
595+```
596+
597+### Component Communication
598+
599+Use Bubbletea commands to communicate between components:
600+
601+```go
602+type fileSelectedMsg struct {
603+ path string
604+}
605+
606+// In list component Update
607+case tea.KeyMsg:
608+ if key.Matches(msg, m.keymap.Enter) {
609+ selectedFile := m.list.SelectedItem()
610+ return m, func() tea.Msg {
611+ return fileSelectedMsg{path: selectedFile.Path()}
612+ }
613+ }
614+
615+// In main model Update
616+case fileSelectedMsg:
617+ m.preview.Load(msg.path)
618+ return m, nil
619+```
620+
621+## Best Practices
622+
623+1. **Keep components focused** - Each component should have one responsibility
624+2. **Use bubbles package** - Don't reinvent standard components
625+3. **Lazy initialization** - Create components when needed, not upfront
626+4. **Proper sizing** - Always pass explicit width/height to components
627+5. **Clean interfaces** - Components should expose minimal, clear APIs
628+
629+## External Dependencies
630+
631+**Core Charm libraries:**
632+```
633+github.com/charmbracelet/bubbletea # Framework
634+github.com/charmbracelet/lipgloss # Styling
635+github.com/charmbracelet/bubbles # Standard components
636+```
637+
638+**Extended functionality:**
639+```
640+github.com/charmbracelet/glamour # Markdown rendering
641+github.com/charmbracelet/huh # Forms
642+github.com/alecthomas/chroma/v2 # Syntax highlighting
643+github.com/evertras/bubble-table # Interactive tables
644+github.com/koki-develop/go-fzf # Fuzzy finder
645+```
646+
647+See `go.mod` in template for complete list of optional dependencies.