keymap

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 30, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyConfig

func ApplyConfig(r *Registry, cfg *Config)

ApplyConfig applies user configuration overrides to the registry.

func CommandHelp

func CommandHelp(cmd Command) string

CommandHelp returns help info for a specific command

func ConfigPath

func ConfigPath(baseDir string) string

ConfigPath returns the path to the keymap config file

func ContextToSidecar added in v0.4.14

func ContextToSidecar(ctx Context) string

ContextToSidecar converts a TD context to its sidecar equivalent.

func IsPrintable

func IsPrintable(key tea.KeyMsg) bool

IsPrintable returns true if the key represents a printable character

func KeyToString

func KeyToString(key tea.KeyMsg) string

KeyToString converts a tea.KeyMsg to a string representation

func RegisterDefaults

func RegisterDefaults(r *Registry)

RegisterDefaults registers all default bindings with the registry.

func SaveConfig

func SaveConfig(path string, cfg *Config) error

SaveConfig saves the config to a JSON file.

Types

type Binding

type Binding struct {
	Key         string  // e.g., "tab", "ctrl+d", "g g"
	Command     Command // Command ID
	Context     Context // "global", "main", "modal", etc.
	Description string  // Human-readable description for help text
}

Binding maps a key or key sequence to a command in a specific context

func DefaultBindings

func DefaultBindings() []Binding

DefaultBindings returns the default key bindings for the monitor TUI. Bindings are organized by context and follow vim conventions where applicable.

type Command

type Command string

Command represents a named command that can be triggered by key bindings

const (
	// Global commands
	CmdQuit       Command = "quit"
	CmdToggleHelp Command = "toggle-help"
	CmdRefresh    Command = "refresh"

	// Navigation commands
	CmdNextPanel    Command = "next-panel"
	CmdPrevPanel    Command = "prev-panel"
	CmdCursorDown   Command = "cursor-down"
	CmdCursorUp     Command = "cursor-up"
	CmdCursorTop    Command = "cursor-top"
	CmdCursorBottom Command = "cursor-bottom"
	CmdHalfPageDown Command = "half-page-down"
	CmdHalfPageUp   Command = "half-page-up"
	CmdFullPageDown Command = "full-page-down"
	CmdFullPageUp   Command = "full-page-up"
	CmdScrollDown   Command = "scroll-down"
	CmdScrollUp     Command = "scroll-up"
	CmdSelect       Command = "select"
	CmdBack         Command = "back"
	CmdClose        Command = "close"
	CmdNavigatePrev Command = "navigate-prev"
	CmdNavigateNext Command = "navigate-next"

	// Action commands
	CmdOpenDetails   Command = "open-details"
	CmdOpenStats     Command = "open-stats"
	CmdSearch        Command = "search"
	CmdToggleClosed  Command = "toggle-closed"
	CmdMarkForReview Command = "mark-for-review"
	CmdApprove       Command = "approve"
	CmdDelete        Command = "delete"
	CmdConfirm       Command = "confirm"
	CmdCancel        Command = "cancel"
	CmdCycleSortMode Command = "cycle-sort-mode"

	// Search-specific commands
	CmdSearchConfirm   Command = "search-confirm"
	CmdSearchCancel    Command = "search-cancel"
	CmdSearchClear     Command = "search-clear"
	CmdSearchBackspace Command = "search-backspace"
	CmdSearchInput     Command = "search-input"

	// Epic task navigation commands
	CmdFocusTaskSection Command = "focus-task-section"
	CmdOpenEpicTask     Command = "open-epic-task"

	// Parent epic navigation
	CmdOpenParentEpic Command = "open-parent-epic"

	// Blocked-by/blocks navigation
	CmdOpenBlockedByIssue Command = "open-blocked-by-issue"
	CmdOpenBlocksIssue    Command = "open-blocks-issue"

	// Handoffs modal
	CmdOpenHandoffs Command = "open-handoffs"

	// Clipboard
	CmdCopyToClipboard   Command = "copy-to-clipboard"
	CmdCopyIDToClipboard Command = "copy-id-to-clipboard"

	// Form commands
	CmdNewIssue         Command = "new-issue"
	CmdEditIssue        Command = "edit-issue"
	CmdFormSubmit       Command = "form-submit"
	CmdFormCancel       Command = "form-cancel"
	CmdFormToggleExtend Command = "form-toggle-extend"
	CmdFormOpenEditor   Command = "form-open-editor"

	// Issue actions
	CmdCloseIssue  Command = "close-issue"
	CmdReopenIssue Command = "reopen-issue"

	// Filters
	CmdCycleTypeFilter Command = "cycle-type-filter"

	// Button navigation (for confirmation dialogs and forms)
	CmdNextButton Command = "next-button"
	CmdPrevButton Command = "prev-button"

	// Board commands
	CmdOpenBoardPicker        Command = "boards"
	CmdSelectBoard            Command = "select-board"
	CmdCloseBoardPicker       Command = "close-picker"
	CmdMoveIssueUp            Command = "move-up"
	CmdMoveIssueDown          Command = "move-down"
	CmdMoveIssueToTop         Command = "move-to-top"
	CmdMoveIssueToBottom      Command = "move-to-bottom"
	CmdExitBoardMode          Command = "exit"
	CmdToggleBoardClosed      Command = "closed"
	CmdCycleBoardStatusFilter Command = "status-filter"
	CmdToggleBoardView        Command = "view"

	// External integration commands
	CmdSendToWorktree Command = "send-to-worktree"

	// Board editor commands
	CmdEditBoard         Command = "edit-board"
	CmdNewBoard          Command = "new-board"
	CmdBoardEditorSave   Command = "board-editor-save"
	CmdBoardEditorCancel Command = "board-editor-cancel"
	CmdBoardEditorDelete Command = "board-editor-delete"

	// Getting started commands
	CmdOpenGettingStarted  Command = "open-getting-started"
	CmdInstallInstructions Command = "install-instructions"
)

All available commands

func AllCommands

func AllCommands() []Command

AllCommands returns all defined commands sorted alphabetically

type Config

type Config struct {
	// Bindings maps "context:key" to command ID
	// Example: {"main:ctrl+s": "open-stats", "modal:q": "close"}
	Bindings map[string]string `json:"bindings"`
}

Config represents user key binding configuration. Stored in .todos/keymap.json

func ExampleConfig

func ExampleConfig() *Config

ExampleConfig returns an example configuration for documentation

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig loads key binding overrides from a JSON file. Returns an empty config if the file doesn't exist.

type Context

type Context string

Context represents a UI context for keybindings

const (
	ContextGlobal            Context = "global"
	ContextMain              Context = "main"
	ContextModal             Context = "modal"
	ContextStats             Context = "stats"
	ContextSearch            Context = "search"
	ContextConfirm           Context = "confirm"
	ContextEpicTasks         Context = "epic-tasks"          // When task list in epic modal is focused
	ContextParentEpicFocused Context = "parent-epic-focused" // When parent epic row is focused
	ContextBlockedByFocused  Context = "blocked-by-focused"  // When blocked-by section is focused
	ContextBlocksFocused     Context = "blocks-focused"      // When blocks section is focused
	ContextHandoffs          Context = "handoffs"            // When handoffs modal is open
	ContextForm              Context = "form"                // When form modal is open
	ContextHelp              Context = "help"                // When help modal is open
	ContextBoardPicker       Context = "board-picker"        // When board picker is open
	ContextBoard             Context = "board"               // When board mode is active
	ContextGettingStarted    Context = "getting-started"     // When getting started modal is open
	ContextTDQHelp           Context = "tdq-help"            // When TDQ help modal is open
	ContextBoardEditor       Context = "board-editor"        // When board edit/create modal is open
)

type ExportedBinding added in v0.4.14

type ExportedBinding struct {
	Key     string // e.g., "tab", "ctrl+d", "g g"
	Command string // Command ID string
	Context string // Sidecar context: "td-monitor", "td-modal", etc.
}

ExportedBinding is a binding format that sidecar can consume. Context is mapped to sidecar's td-prefixed context names.

type ExportedCommand added in v0.4.14

type ExportedCommand struct {
	ID          string // Command ID
	Name        string // Short display name for footer (1-2 words)
	Description string // Full description for palette
	Context     string // Sidecar context
	Priority    int    // 1-3 = footer visible, 4+ = palette only
}

ExportedCommand provides command metadata for sidecar's command palette.

type HelpBinding

type HelpBinding struct {
	Keys        string // Combined keys like "j / k" or "↑ / ↓"
	Description string
}

HelpBinding represents a single binding for display

type HelpSection

type HelpSection struct {
	Title    string
	Bindings []HelpBinding
}

HelpSection represents a group of bindings in help text

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages key bindings and command dispatch

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new keymap registry

func (*Registry) AllContexts

func (r *Registry) AllContexts() []Context

AllContexts returns all contexts that have bindings

func (*Registry) BindingsByCommand

func (r *Registry) BindingsByCommand(context Context) map[Command][]string

BindingsByCommand groups bindings by command for help generation

func (*Registry) BindingsForContext

func (r *Registry) BindingsForContext(context Context) []Binding

BindingsForContext returns all bindings for a given context (including global)

func (*Registry) BoardFooterHelp added in v0.23.0

func (r *Registry) BoardFooterHelp() string

BoardFooterHelp generates help text for board mode footer

func (*Registry) ExportBindings added in v0.4.14

func (r *Registry) ExportBindings() []ExportedBinding

ExportBindings returns all bindings in a format sidecar can consume.

func (*Registry) ExportCommands added in v0.4.14

func (r *Registry) ExportCommands() []ExportedCommand

ExportCommands returns command metadata for sidecar's command palette. Returns unique commands with their metadata, mapped to sidecar contexts.

func (*Registry) FooterHelp

func (r *Registry) FooterHelp() string

FooterHelp generates a compact help string for the footer

func (*Registry) GenerateHelp

func (r *Registry) GenerateHelp() string

GenerateHelp generates help text from the registry bindings

func (*Registry) GenerateTDQHelp

func (r *Registry) GenerateTDQHelp() string

GenerateTDQHelp generates help text for TDQ query language

func (*Registry) HasPending

func (r *Registry) HasPending() bool

HasPending returns true if there's a pending key sequence

func (*Registry) Lookup

func (r *Registry) Lookup(key tea.KeyMsg, activeContext Context) (Command, bool)

Lookup finds the command for a given key in the specified context Returns the command and whether a binding was found Checks: user overrides -> context bindings -> global bindings

func (*Registry) ModalFooterHelp

func (r *Registry) ModalFooterHelp() string

ModalFooterHelp generates help text for the modal footer

func (*Registry) PendingKey

func (r *Registry) PendingKey() string

PendingKey returns the current pending key (for UI display)

func (*Registry) RegisterBinding

func (r *Registry) RegisterBinding(b Binding)

RegisterBinding adds a key binding

func (*Registry) RegisterBindings

func (r *Registry) RegisterBindings(bindings []Binding)

RegisterBindings adds multiple key bindings

func (*Registry) ResetPending

func (r *Registry) ResetPending()

ResetPending clears any pending key sequence

func (*Registry) SetUserOverride

func (r *Registry) SetUserOverride(context Context, key string, cmd Command)

SetUserOverride sets a user-configured key override for a specific context

func (*Registry) StatsFooterHelp

func (r *Registry) StatsFooterHelp() string

StatsFooterHelp generates help text for the stats modal footer

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL