@@ -1,647 +0,0 @@
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.