gentleman-bubbletea_skill

Overview

This skill provides Bubbletea TUI patterns and conventions for the Gentleman.Dots installer. It documents required screen constants, state layout, input handling, key handler contracts, and scrolling patterns so new UI features integrate consistently. Use it to add screens, navigation, or scrollable components with predictable behavior.

How this skill works

The patterns define a single Model struct that holds all UI state and a Screen enum for every TUI screen. All messages flow through Update() with a type switch; input is delegated to per-screen key handlers that return (tea.Model, tea.Cmd). View rendering uses a switch on m.Screen and GetScreenTitle() supplies screen titles. Scroll, cursor, and back-navigation state are explicit fields on the Model so transitions and state restoration are simple.

When to use it

• Adding a new installer screen or category
• Implementing keyboard navigation or selection handling
• Creating scrollable lists or long content views
• Introducing Lipgloss-styled components or new layout states
• Saving and restoring navigation/scroll state across screens

Best practices

• Declare every screen as a Screen constant in model.go using iota
• Keep all UI state in the Model struct; add explicit fields for new screens (cursor, scroll, selections)
• Handle all msg types in Update() and delegate key events to screen-specific handlers
• Always return (tea.Model, tea.Cmd) from key handlers to follow Bubbletea conventions
• Reset cursor/scroll when exiting a screen and use PrevScreen for back navigation
• Compute visible items from m.Height and clamp scroll ranges before applying changes

Example use cases

• Add ScreenNewFeature constant, add NewFeatureData and scroll fields to Model, wire handler in handleKeyPress, add view case and title entry
• Implement a category list: build GetCurrentOptions() to include separators and a Back item, handle up/down skipping separators, handle enter to open category screen
• Create a long README viewer: add ScreenReadme, ReadmeScroll int, compute visibleItems from m.Height, clamp maxScroll and update on up/down
• Load remote data asynchronously: return a custom msg from a command, handle newFeatureLoadedMsg in Update to populate Model and clear errors
• Test TUI code: build installer binary or run targeted tests in installer/internal/tui