build-tui-view

📝 SELF-UPDATING DOCUMENT: This skill automatically updates itself when inaccuracies are discovered or new patterns are learned. Always verify information against the actual codebase and update this file when needed.

Overview

This skill provides instructions for creating and maintaining Terminal User Interface (TUI) views in the Hatchet CLI using bubbletea and lipgloss. The TUI system uses a modular view architecture where individual views are isolated in separate files within the

views/

directory.

IMPORTANT: Always start by finding the corresponding view in the frontend application to understand the structure, columns, and API calls.

Self-Updating Skill Instructions

CRITICAL - READ FIRST: This skill document is designed to be continuously improved and kept accurate.

When to Update This Skill

You MUST update this skill file in the following situations:

Discovering Inaccuracies
- When you find incorrect file paths or directory structures
- When code examples don't compile or don't match actual implementations
- When API signatures have changed
- When referenced files don't exist at specified locations
Learning New Patterns
- When implementing a new view and discovering better approaches
- When the user teaches you new conventions or patterns
- When you find reusable patterns that should be documented
- When you discover common pitfalls that should be warned about
Finding Missing Information
- When you need information that isn't documented here
- When new components or utilities are added to the codebase
- When new bubbletea/lipgloss patterns are adopted
User Corrections
- When the user corrects any information in this document
- When the user provides updated approaches or conventions
- When the user points out outdated information

How to Update This Skill

When updating this skill:

Verify Before Adding: Always verify paths, code, and API signatures against the actual codebase before adding to this document
Use Read/Glob/Grep: Check the actual files to ensure accuracy
Test Code Examples: Ensure code examples compile and follow current patterns
Be Specific: Include exact file paths, function signatures, and working code examples
Update Immediately: Make updates as soon as inaccuracies are discovered, not at the end of a session
Preserve Structure: Maintain the existing document structure and formatting
Add Context: When adding new sections, explain why the pattern is recommended

Verification Checklist

Before using information from this skill, verify:

File paths exist and are correct
Code examples match current implementations
API signatures match the generated REST client
Reusable components are correctly referenced
Directory structures are accurate

Self-Correction Process

If you discover an inaccuracy while working:

Immediately note the issue
Verify the correct information by reading the actual files
Update this skill document with the correction
Continue with the user's task using the corrected information

Remember: This skill should be a living document that grows more accurate and comprehensive with each use.

Project Context

Framework: bubbletea (TUI framework)
Styling: lipgloss (style definitions)
TUI Command Location:
```
cmd/hatchet-cli/cli/tui.go
```
Views Location:
```
cmd/hatchet-cli/cli/tui/
```
directory

Theme: Pre-defined Hatchet theme in

cmd/hatchet-cli/cli/internal/styles/styles.go

Frontend Reference:
```
frontend/app/src/pages/main/v1/
```
directory

Finding Frontend Prior Art

CRITICAL FIRST STEP: Before implementing any TUI view, locate the corresponding frontend view to understand:

Column structure and names
API endpoints and query parameters
Data types and fields used
Filtering and sorting logic

Process for Finding Frontend Reference:

Locate the Frontend View

bash

# Navigate to frontend pages
cd frontend/app/src/pages/main/v1/

# Find views related to your feature (e.g., workflow-runs, tasks, events)
ls -la

Study the Column Definitions

Look for files like
```
{feature}-columns.tsx
```
Note the column keys, titles, and accessors

Example:

frontend/app/src/pages/main/v1/workflow-runs-v1/components/v1/task-runs-columns.tsx

typescript

export const TaskRunColumn = {
  taskName: "Task Name",
  status: "Status",
  workflow: "Workflow",
  createdAt: "Created At",
  startedAt: "Started At",
  duration: "Duration",
};

Identify the Data Hook
- Look for
```
use-{feature}.tsx
```
  files in the
```
hooks/
```
  directory
- These contain the API query logic
- Example:
```
frontend/app/src/pages/main/v1/workflow-runs-v1/hooks/use-runs.tsx
```

Find the API Query

Check
```
frontend/app/src/lib/api/queries.ts
```
for the query definition
Note the endpoint name and parameters
Example:

typescript

v1WorkflowRuns: {
  list: (tenant: string, query: V2ListWorkflowRunsQuery) => ({
    queryKey: ['v1:workflow-run:list', tenant, query],
    queryFn: async () => (await api.v1WorkflowRunList(tenant, query)).data,
  }),
}

Map to Go REST Client

The frontend

api.v1WorkflowRunList()

maps to Go's

client.API().V1WorkflowRunListWithResponse()

Frontend query parameters map to Go struct parameters
Example mapping:

typescript

// Frontend
api.v1WorkflowRunList(tenantId, {
  offset: 0,
  limit: 100,
  since: createdAfter,
  only_tasks: true,
})

// Go equivalent
client.API().V1WorkflowRunListWithResponse(
  ctx,
  client.TenantId(),
  &rest.V1WorkflowRunListParams{
    Offset: int64Ptr(0),
    Limit: int64Ptr(100),
    Since: &since,
    OnlyTasks: true,
  },
)

Example: Implementing Tasks View from Frontend Reference

Frontend Structure:

frontend/app/src/pages/main/v1/workflow-runs-v1/

Columns:
```
task-runs-columns.tsx
```
Hook:
```
use-runs.tsx
```
Table:
```
runs-table.tsx
```

Extract Column Names:

typescript

taskName, status, workflow, createdAt, startedAt, duration;

Identify API Call:

typescript

queries.v1WorkflowRuns.list(tenantId, {
  offset,
  limit,
  statuses,
  workflow_ids,
  since,
  until,
  only_tasks: true,
});

Implement in TUI:

// Create matching columns
columns := []table.Column{
  {Title: "Task Name", Width: 30},
  {Title: "Status", Width: 12},
  {Title: "Workflow", Width: 25},
  {Title: "Created At", Width: 16},
  {Title: "Started At", Width: 16},
  {Title: "Duration", Width: 12},
}

// Call matching API endpoint
response, err := client.API().V1WorkflowRunListWithResponse(
  ctx,
  client.TenantId(),
  &rest.V1WorkflowRunListParams{
    Offset: int64Ptr(0),
    Limit: int64Ptr(100),
    Since: &since,
    OnlyTasks: true,
  },
)

Reusable Components (CRITICAL - READ FIRST)

IMPORTANT: All TUI views MUST use the standardized reusable components defined in

view.go

to ensure consistency across the application. DO NOT copy-paste header/footer styling code.

Header Component

CRITICAL: ALL headers throughout the TUI use the magenta highlight color (

styles.HighlightColor

) for the title to provide consistent visual emphasis across all views (primary views, detail views, modals, etc.).

For Detail Views and Modals

Always use
RenderHeader()
for detail views, modals, and secondary screens:

header := RenderHeader("Workflow Details", v.Ctx.ProfileName, v.Width)
header := RenderHeader("Task Details", v.Ctx.ProfileName, v.Width)
header := RenderHeader("Filter Tasks", v.Ctx.ProfileName, v.Width)

For Primary Views

Use
RenderHeaderWithViewIndicator()
for primary/list views:

// For primary list views - shows just the view name, no repetitive "Hatchet Workflows [Workflows]"
header := RenderHeaderWithViewIndicator("Runs", v.Ctx.ProfileName, v.Width)
header := RenderHeaderWithViewIndicator("Workflows", v.Ctx.ProfileName, v.Width)

This function renders just the view name (e.g., "Runs" or "Workflows") in the highlight color, keeping it simple and non-repetitive.

Features of both header functions:

Title rendered in magenta highlight color (
```
styles.HighlightColor
```
) - consistent across ALL views
Includes the logo (text-based: "HATCHET TUI") on the right
Shows profile name
Bordered bottom edge
Responsive to terminal width

❌ NEVER do this:

// Bad: Copy-pasting header styles
headerStyle := lipgloss.NewStyle().
    Bold(true).
    Foreground(styles.AccentColor).
    BorderStyle(lipgloss.NormalBorder()).
    // ... more styling
header := headerStyle.Render(fmt.Sprintf("My View - Profile: %s", profile))

// Bad: Calling RenderHeaderWithLogo directly (bypasses highlight color)
header := RenderHeaderWithLogo(fmt.Sprintf("My View - Profile: %s", profile), v.Width)

✅ ALWAYS do this:

// Good: Use the reusable component for detail views
header := RenderHeader("Task Details", v.Ctx.ProfileName, v.Width)

// Good: Use the view indicator variant for primary views
header := RenderHeaderWithViewIndicator("Runs", v.Ctx.ProfileName, v.Width)

Instructions Component

Use

RenderInstructions()

to display contextual help text:

instructions := RenderInstructions(
    "Your instructions here  •  Use bullets to separate items",
    v.Width,
)

Features:

Muted color styling for reduced visual noise
Automatically handles width constraints
Consistent padding
Uses bullet separators (•)

Footer Component

Always use
RenderFooter()
for navigation/control hints:

footer := RenderFooter([]string{
    "↑/↓: Navigate",
    "Enter: Select",
    "Esc: Cancel",
    "q: Quit",
}, v.Width)

Features:

Consistent styling with top border
Automatically joins control items with bullets (•)
Muted color for non-intrusive display
Responsive to terminal width

Standard View Structure

Every view should follow this consistent structure:

func (v *YourView) View() string {
    var b strings.Builder

    // 1. Header (always) - USE REUSABLE COMPONENT
    header := RenderHeader("View Title", v.Ctx.ProfileName, v.Width)
    b.WriteString(header)
    b.WriteString("\n\n")

    // 2. Instructions (when helpful) - USE REUSABLE COMPONENT
    instructions := RenderInstructions("Your instructions", v.Width)
    b.WriteString(instructions)
    b.WriteString("\n\n")

    // 3. Main content
    // ... your view-specific content ...

    // 4. Footer (always) - USE REUSABLE COMPONENT
    footer := RenderFooter([]string{
        "control1: Action1",
        "control2: Action2",
    }, v.Width)
    b.WriteString(footer)

    return b.String()
}

Architecture

Root TUI Model (

tui.go

)

The root TUI command is responsible for:

Profile selection and validation
Initializing the Hatchet client
Creating the view context
Managing the current view
Delegating updates to views

View System (

views/

directory)

Each view is a separate file that implements the

View

interface:

```
view.go
```
- Base view interface, context, and reusable components
```
{viewname}.go
```
- Individual view implementations (e.g.,
```
tasks.go
```
)

Core Principles

1. File Structure

TUI Command File

File:
```
cmd/hatchet-cli/cli/tui.go
```
Purpose: Command setup, profile selection, client initialization, view management

View Files

Location:
```
cmd/hatchet-cli/cli/tui/
```
Files:
- ```
view.go
```
  - View interface and base types
- ```
{viewname}.go
```
  - Individual view implementations

2. View Interface

All views must implement this interface (defined in

views/view.go

package views

import (
	tea "github.com/charmbracelet/bubbletea"
	"github.com/hatchet-dev/hatchet/pkg/client"
)

// ViewContext contains the shared context passed to all views
type ViewContext struct {
	// Profile name for display
	ProfileName string

	// Hatchet client for API calls
	Client client.Client

	// Terminal dimensions
	Width  int
	Height int
}

// View represents a TUI view component
type View interface {
	// Init initializes the view and returns any initial commands
	Init() tea.Cmd

	// Update handles messages and updates the view state
	Update(msg tea.Msg) (View, tea.Cmd)

	// View renders the view to a string
	View() string

	// SetSize updates the view dimensions
	SetSize(width, height int)
}

3. Base Model Pattern

Use

BaseModel

for common view fields:

// BaseModel contains common fields for all views
type BaseModel struct {
	Ctx    ViewContext
	Width  int
	Height int
	Err    error
}

// Your view embeds BaseModel
type YourView struct {
	BaseModel
	// Your view-specific fields
	table table.Model
	items []YourDataType
}

4. Creating a New View

Step 1: Create View File

Create

cmd/hatchet-cli/cli/tui/{viewname}.go

package views

import (
	tea "github.com/charmbracelet/bubbletea"
	"github.com/hatchet-dev/hatchet/cmd/hatchet-cli/cli/internal/styles"
	"github.com/hatchet-dev/hatchet/pkg/client/rest"
)

type YourView struct {
	BaseModel
	// View-specific fields
}

// NewYourView creates a new instance of your view
func NewYourView(ctx ViewContext) *YourView {
	v := &YourView{
		BaseModel: BaseModel{
			Ctx: ctx,
		},
	}

	// Initialize view components

	return v
}

func (v *YourView) Init() tea.Cmd {
	return nil
}

func (v *YourView) Update(msg tea.Msg) (View, tea.Cmd) {
	var cmd tea.Cmd

	switch msg := msg.(type) {
	case tea.WindowSizeMsg:
		v.SetSize(msg.Width, msg.Height)
		return v, nil

	case tea.KeyMsg:
		switch msg.String() {
		case "r":
			// Refresh logic
			return v, nil
		}
	}

	// Update sub-components
	return v, cmd
}

func (v *YourView) View() string {
	if v.Width == 0 {
		return "Initializing..."
	}

	// Build your view
	return "Your view content"
}

func (v *YourView) SetSize(width, height int) {
	v.BaseModel.SetSize(width, height)
	// Update view-specific components
}

Step 2: Use View in TUI

The root TUI model manages views:

// In tui.go
func newTUIModel(profileName string, hatchetClient client.Client) tuiModel {
	ctx := views.ViewContext{
		ProfileName: profileName,
		Client:      hatchetClient,
	}

	// Initialize with your view
	currentView := views.NewYourView(ctx)

	return tuiModel{
		currentView: currentView,
	}
}

5. Client Initialization Pattern

Always initialize the Hatchet client in

tui.go

import (
	"github.com/rs/zerolog"
	"github.com/hatchet-dev/hatchet/pkg/client"
)

// In the cobra command Run function
profile, err := cli.GetProfile(selectedProfile)
if err != nil {
	cli.Logger.Fatalf("could not get profile '%s': %v", selectedProfile, err)
}

// Initialize Hatchet client
nopLogger := zerolog.Nop()
hatchetClient, err := client.New(
	client.WithToken(profile.Token),
	client.WithLogger(&nopLogger),
)
if err != nil {
	cli.Logger.Fatalf("could not create Hatchet client: %v", err)
}

6. Accessing the Client in Views

The Hatchet client is available through the view context:

func (v *YourView) fetchData() tea.Cmd {
	return func() tea.Msg {
		// Access the client
		client := v.Ctx.Client

		// Make API calls
		// response, err := client.API().SomeEndpoint(...)

		return yourDataMsg{
			data: data,
			err:  err,
		}
	}
}

7. Hatchet Theme Integration

CRITICAL: NEVER hardcode colors or styles in view files. Always use the pre-defined Hatchet theme colors and utilities from

cmd/hatchet-cli/cli/internal/styles

Available Theme Colors

import "github.com/hatchet-dev/hatchet/cmd/hatchet-cli/cli/internal/styles"

// Primary theme colors:
// - styles.AccentColor
// - styles.PrimaryColor
// - styles.SuccessColor
// - styles.HighlightColor
// - styles.MutedColor
// - styles.Blue, styles.Cyan, styles.Magenta

// Status colors (matching frontend badge variants):
// - styles.StatusSuccessColor / styles.StatusSuccessBg
// - styles.StatusFailedColor / styles.StatusFailedBg
// - styles.StatusInProgressColor / styles.StatusInProgressBg
// - styles.StatusQueuedColor / styles.StatusQueuedBg
// - styles.StatusCancelledColor / styles.StatusCancelledBg
// - styles.ErrorColor

// Available styles:
// - styles.H1, styles.H2
// - styles.Bold, styles.Italic
// - styles.Primary, styles.Accent, styles.Success
// - styles.Code
// - styles.Box, styles.InfoBox, styles.SuccessBox

Status Rendering

Per-Cell Coloring in Tables: Use the custom

TableWithStyleFunc

wrapper to enable per-cell styling.

For status rendering in tables:

// Create table with StyleFunc support
t := NewTableWithStyleFunc(
    table.WithColumns(columns),
    table.WithFocused(true),
    table.WithHeight(20),
)

// Set StyleFunc for per-cell styling
t.SetStyleFunc(func(row, col int) lipgloss.Style {
    // Column 1 is the status column
    if col == 1 && row < len(v.tasks) {
        statusStyle := styles.GetV1TaskStatusStyle(v.tasks[row].Status)
        return lipgloss.NewStyle().Foreground(statusStyle.Foreground)
    }
    return lipgloss.NewStyle()
})

// In updateTableRows, use plain text (StyleFunc applies colors)
statusStyle := styles.GetV1TaskStatusStyle(task.Status)
status := statusStyle.Text  // "Succeeded", "Failed", etc.

For non-table contexts (headers, footers, standalone text):

// Render V1TaskStatus with proper colors
status := styles.RenderV1TaskStatus(task.Status)

// Render error messages
errorMsg := styles.RenderError(fmt.Sprintf("Error: %v", err))

Why custom TableWithStyleFunc?

Standard bubbles table doesn't support per-cell or per-column styling
```
TableWithStyleFunc
```
wraps bubbles table and adds StyleFunc support
StyleFunc allows dynamic cell styling based on row/column index
Located in
```
cmd/hatchet-cli/cli/tui/table_custom.go
```
Maintains bubbles table interactivity (cursor, selection, keyboard nav)

Table Styling

s := table.DefaultStyles()
s.Header = s.Header.
    BorderStyle(lipgloss.NormalBorder()).
    BorderForeground(styles.AccentColor).
    BorderBottom(true).
    Bold(true).
    Foreground(styles.AccentColor)
s.Selected = s.Selected.
    Foreground(lipgloss.AdaptiveColor{Light: "#ffffff", Dark: "#0A1029"}).
    Background(styles.Blue).
    Bold(true)

Note: Use

lipgloss.AdaptiveColor

even for basic colors like white/black to support light/dark terminals.

Adding New Status Colors

If you need to add new status colors:

Add the color constants to

cmd/hatchet-cli/cli/internal/styles/styles.go

Create or update the utility function in

cmd/hatchet-cli/cli/internal/styles/status.go

Reference the frontend badge variants in
```
frontend/app/src/components/v1/ui/badge.tsx
```
for color values
Use adaptive colors for light/dark terminal support

8. Standard Keyboard Controls

Use consistent key mappings across all views to provide a predictable user experience.

Global Controls (handled in tui.go)

```
q
```
or
```
ctrl+c
```
: Quit the TUI

View-Specific Controls

Implement these in individual views:

Navigation:
```
↑/↓
```
or arrow keys for list navigation
Selection:
```
Enter
```
to select/confirm
Tab Navigation:
```
Tab
```
/
```
Shift+Tab
```
for form fields
Cancel:
```
Esc
```
to go back/cancel
Refresh:
```
r
```
to manually refresh data
Filter:
```
f
```
to open filter modal (where applicable)
Debug:
```
d
```
to toggle debug view (see Debug Logging section)
Clear:
```
c
```
to clear debug logs (when in debug view)
Tab Views:
```
1
```
,
```
2
```
,
```
3
```
, etc. or
```
tab
```
/
```
shift+tab
```
for switching tabs

Important: Always document keyboard controls in the footer using

RenderFooter()

9. Layout Components

CRITICAL: Use the reusable components from

view.go

for headers, instructions, and footers. See "Reusable Components" section above.

Header

✅ Use the reusable component:

header := RenderHeader("View Title", v.Ctx.ProfileName, v.Width)

❌ DO NOT manually create headers:

// Bad: Don't do this
headerStyle := lipgloss.NewStyle().
    Bold(true).
    Foreground(styles.AccentColor).
    // ... (this violates DRY principle)

Footer

✅ Use the reusable component:

footer := RenderFooter([]string{
    "↑/↓: Navigate",
    "r: Refresh",
    "q: Quit",
}, v.Width)

❌ DO NOT manually create footers:

// Bad: Don't do this
footerStyle := lipgloss.NewStyle().
    Foreground(styles.MutedColor).
    // ... (this violates DRY principle)

Instructions

✅ Use the reusable component:

instructions := RenderInstructions("Your helpful instructions here", v.Width)

Stats Bar

Custom stats bars are fine for view-specific metrics:

statsStyle := lipgloss.NewStyle().
    Foreground(styles.MutedColor).
    Padding(0, 1)

stats := statsStyle.Render(fmt.Sprintf(
    "Total: %d  |  Status1: %d  |  Status2: %d",
    total, status1Count, status2Count,
))

10. Data Integration

REST API Types

Use generated REST types from:

import "github.com/hatchet-dev/hatchet/pkg/client/rest"

Common types:

```
rest.V1TaskSummary
```
```
rest.V1TaskSummaryList
```
```
rest.V1WorkflowRun
```
```
rest.V1WorkflowRunDetails
```
```
rest.Worker
```
```
rest.WorkerRuntimeInfo
```
```
rest.Workflow
```
```
rest.APIResourceMeta
```

Async Data Fetching Pattern

// Define custom message types in your view file
type yourDataMsg struct {
    items []YourDataType
    err   error
}

// Create fetch command
func (v *YourView) fetchData() tea.Cmd {
    return func() tea.Msg {
        // Use v.Ctx.Client to make API calls
        // Return yourDataMsg
    }
}

// Handle in Update
case yourDataMsg:
    v.loading = false
    if msg.err != nil {
        v.HandleError(msg.err)
    } else {
        v.items = msg.items
        v.ClearError()
    }

11. Modal Views

When creating modal overlays (like filter forms or confirmation dialogs):

Still show the header with updated title using
```
RenderHeader()
```
Show instructions specific to the modal interaction using
```
RenderInstructions()
```
Show the modal content
Show a footer with modal-specific controls using
```
RenderFooter()
```

Example Modal Structure:

func (v *TasksView) renderFilterModal() string {
    var b strings.Builder

    // 1. Header - USE REUSABLE COMPONENT
    header := RenderHeader("Filter Tasks", v.Ctx.ProfileName, v.Width)
    b.WriteString(header)
    b.WriteString("\n\n")

    // 2. Instructions - USE REUSABLE COMPONENT
    instructions := RenderInstructions("Configure filters and press Enter to apply", v.Width)
    b.WriteString(instructions)
    b.WriteString("\n\n")

    // 3. Modal content (form, etc.)
    b.WriteString(v.filterForm.View())
    b.WriteString("\n")

    // 4. Footer - USE REUSABLE COMPONENT
    footer := RenderFooter([]string{"Enter: Apply", "Esc: Cancel"}, v.Width)
    b.WriteString(footer)

    return b.String()
}

Important: Modals should maintain the same visual structure as regular views (header, instructions, content, footer) for consistency.

12. Form Integration

When using

huh

forms in views:

Set the Hatchet theme:
```
.WithTheme(styles.HatchetTheme())
```
Integrate forms directly into the main tea.Program (don't run separate programs)
Handle form completion by checking
```
form.State == huh.StateCompleted
```
Pass ALL messages to the form when it's active (not just key messages)

Example:

import "github.com/charmbracelet/huh"

// In Update()
if v.showingFilter && v.filterForm != nil {
    // Pass ALL messages to form when active
    form, cmd := v.filterForm.Update(msg)
    v.filterForm = form.(*huh.Form)

    // Check if form completed
    if v.filterForm.State == huh.StateCompleted {
        v.showingFilter = false
        // Process form values
    }

    return v, cmd
}

13. Table Component

Using

github.com/charmbracelet/bubbles/table

import "github.com/charmbracelet/bubbles/table"

// Define columns
columns := []table.Column{
    {Title: "Column1", Width: 20},
    {Title: "Column2", Width: 30},
}

// Create table
t := table.New(
    table.WithColumns(columns),
    table.WithFocused(true),
    table.WithHeight(20),
)

// Apply Hatchet styles
s := table.DefaultStyles()
s.Header = s.Header.
    BorderStyle(lipgloss.NormalBorder()).
    BorderForeground(styles.AccentColor).
    BorderBottom(true).
    Bold(true).
    Foreground(styles.AccentColor)
s.Selected = s.Selected.
    Foreground(lipgloss.AdaptiveColor{Light: "#ffffff", Dark: "#0A1029"}).
    Background(styles.Blue).
    Bold(true)
t.SetStyles(s)

// Update rows
rows := make([]table.Row, len(items))
for i, item := range items {
    rows[i] = table.Row{item.Field1, item.Field2}
}
t.SetRows(rows)

14. Table Height Calculations and Layout Optimization

CRITICAL: Proper table height calculation is essential for optimal use of terminal space. Different view types require different calculations based on the UI elements displayed above and below the table.

Standard Height Calculations by View Type

Primary List Views (e.g., runs_list, workflows):

Calculation:
```
height - 12
```
Accounts for: header (3 lines), stats bar (2 lines), spacing (2 lines), footer (2 lines), buffer (3 lines)

func (v *RunsListView) Update(msg tea.Msg) (View, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        v.SetSize(msg.Width, msg.Height)
        v.table.SetHeight(msg.Height - 12)  // Primary view calculation
        return v, nil
    }
    // ...
}

func (v *RunsListView) SetSize(width, height int) {
    v.BaseModel.SetSize(width, height)
    if height > 12 {
        v.table.SetHeight(height - 12)
    }
}

Detail Views with Additional Info Sections (e.g., workflow_details with workflow info + runs table):

Calculation:
```
height - 16
```
(or adjust based on info section size)
Accounts for: header (3 lines), info section (4 lines), section header (2 lines), spacing (2 lines), footer (2 lines), buffer (3 lines)

func (v *WorkflowDetailsView) Update(msg tea.Msg) (View, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        v.SetSize(msg.Width, msg.Height)
        v.table.SetHeight(msg.Height - 16)  // Detail view with extra info
        return v, nil
    }
    // ...
}

func (v *WorkflowDetailsView) SetSize(width, height int) {
    v.BaseModel.SetSize(width, height)
    if height > 16 {
        v.table.SetHeight(height - 16)
    }
}

Guidelines for Height Calculation

Count Your UI Elements: List all elements that appear above and below the table
Estimate Line Counts:
- Header: ~3 lines (with spacing)
- Stats bar: ~2 lines (with spacing)
- Section headers: ~2 lines each
- Info sections: ~3-5 lines depending on content
- Footer: ~2 lines (with spacing)
- Buffer: ~2-3 lines for safety
Test at Different Sizes: Verify the table has adequate space at minimum terminal size (80x24)
Iterate if Needed: If the table feels cramped, reduce the height offset by 2-4 lines

Common Mistake: Using the same height calculation for all views without accounting for additional UI elements.

❌ Wrong:

// Detail view with extra info section but using primary view calculation
v.table.SetHeight(msg.Height - 12)  // Table will be too large, overlapping footer

✅ Correct:

// Adjust calculation based on actual UI elements in the view
v.table.SetHeight(msg.Height - 16)  // Accounts for extra info section

15. Column Consistency Between Related Views

CRITICAL: When a detail view displays a list that's conceptually similar to a primary list view (e.g., workflow details showing recent runs, same as the main runs list), the columns MUST match exactly to maintain consistency and user expectations.

Why Column Consistency Matters

User Experience: Users expect the same information in the same format across views
Cognitive Load: Consistent columns reduce mental overhead when switching contexts
Visual Familiarity: Same column structure reinforces the relationship between views

Example: Runs List Columns

Primary View (

runs_list.go

columns := []table.Column{
    {Title: "Task Name", Width: 30},
    {Title: "Status", Width: 12},
    {Title: "Workflow", Width: 25},
    {Title: "Created At", Width: 16},
    {Title: "Started At", Width: 16},
    {Title: "Duration", Width: 12},
}

Detail View (

workflow_details.go

showing recent runs for a workflow):

// MUST use the same columns as runs_list.go
columns := []table.Column{
    {Title: "Task Name", Width: 30},
    {Title: "Status", Width: 12},
    {Title: "Workflow", Width: 25},      // Keep this even if redundant
    {Title: "Created At", Width: 16},
    {Title: "Started At", Width: 16},
    {Title: "Duration", Width: 12},
}

Implementing Column Consistency

When implementing a detail view with a related list:

Reference the primary view: Check which columns the primary list view uses
Copy the column structure exactly: Same titles, same order, same widths
Keep all columns: Don't remove columns even if they seem redundant in the detail context
Update row population: Ensure
```
updateTableRows()
```
populates all columns correctly

❌ Wrong:

// Workflow details view using different columns than runs list
columns := []table.Column{
    {Title: "Name", Width: 40},          // Different title
    {Title: "Created At", Width: 16},
    {Title: "Status", Width: 12},        // Different order
    // Missing: Workflow, Started At, Duration
}

✅ Correct:

// Workflow details view matching runs list exactly
columns := []table.Column{
    {Title: "Task Name", Width: 30},     // Same titles
    {Title: "Status", Width: 12},
    {Title: "Workflow", Width: 25},      // Same order
    {Title: "Created At", Width: 16},
    {Title: "Started At", Width: 16},
    {Title: "Duration", Width: 12},      // All columns included
}

16. View Navigation and Modal Selector

The TUI uses a navigation stack system for drilling down into details and a modal selector for switching between primary views.

Navigation Stack Pattern

The root TUI model maintains a

viewStack

for back navigation:

type tuiModel struct {
    currentView       tui.View
    viewStack         []tui.View     // Stack for back navigation
    // ...
}

Navigating to a Detail View:

case tui.NavigateToWorkflowMsg:
    // Push current view onto stack
    m.viewStack = append(m.viewStack, m.currentView)

    // Create and initialize detail view
    detailView := tui.NewWorkflowDetailsView(m.ctx, msg.WorkflowID)
    detailView.SetSize(m.width, m.height)
    m.currentView = detailView

    return m, detailView.Init()

Navigating Back:

case tui.NavigateBackMsg:
    // Pop view from stack
    if len(m.viewStack) > 0 {
        m.currentView = m.viewStack[len(m.viewStack)-1]
        m.viewStack = m.viewStack[:len(m.viewStack)-1]
        m.currentView.SetSize(m.width, m.height)
    }
    return m, nil

In Detail Views (handle Esc key for back navigation):

case tea.KeyMsg:
    switch msg.String() {
    case "esc":
        // Navigate back to previous view
        return v, NewNavigateBackMsg()
    }

Modal View Selector Pattern

The modal selector allows switching between primary views using

Shift+Tab

Opening the Modal:

case tea.KeyMsg:
    switch msg.String() {
    case "shift+tab":
        // Find current view type in the list
        for i, opt := range availableViews {
            if opt.Type == m.currentViewType {
                m.selectedViewIndex = i
                break
            }
        }
        m.showViewSelector = true
        return m, nil
    }

Modal Navigation (supports Tab, arrow keys, vim keys):

if m.showViewSelector {
    switch msg.String() {
    case "shift+tab", "tab", "down", "j":
        // Cycle forward
        m.selectedViewIndex = (m.selectedViewIndex + 1) % len(availableViews)
        return m, nil
    case "up", "k":
        // Cycle backward
        m.selectedViewIndex = (m.selectedViewIndex - 1 + len(availableViews)) % len(availableViews)
        return m, nil
    case "enter":
        // Confirm selection and switch view
        selectedType := availableViews[m.selectedViewIndex].Type
        if selectedType != m.currentViewType {
            // Only switch if in a primary view
            if m.isInPrimaryView() {
                m.currentViewType = selectedType
                m.currentView = m.createViewForType(selectedType)
                m.currentView.SetSize(m.width, m.height)
                m.showViewSelector = false
                return m, m.currentView.Init()
            }
        }
        m.showViewSelector = false
        return m, nil
    case "esc":
        // Cancel without switching
        m.showViewSelector = false
        return m, nil
    }
    return m, nil
}

Rendering the Modal:

func (m tuiModel) renderViewSelector() string {
    var b strings.Builder

    // Use reusable header component
    header := tui.RenderHeader("Select View", m.ctx.ProfileName, m.width)
    b.WriteString(header)
    b.WriteString("\n\n")

    // Instructions
    instructions := tui.RenderInstructions(
        "↑/↓ or Tab: Navigate  •  Enter: Confirm  •  Esc: Cancel",
        m.width,
    )
    b.WriteString(instructions)
    b.WriteString("\n\n")

    // View options with highlighting
    for i, opt := range availableViews {
        if i == m.selectedViewIndex {
            // Highlighted option
            selectedStyle := lipgloss.NewStyle().
                Foreground(lipgloss.AdaptiveColor{Light: "#ffffff", Dark: "#0A1029"}).
                Background(styles.Blue).
                Bold(true).
                Padding(0, 2)

            b.WriteString(selectedStyle.Render(fmt.Sprintf("▶ %s - %s", opt.Name, opt.Description)))
        } else {
            // Non-highlighted option
            normalStyle := lipgloss.NewStyle().
                Foreground(styles.MutedColor).
                Padding(0, 2)

            b.WriteString(normalStyle.Render(fmt.Sprintf("  %s - %s", opt.Name, opt.Description)))
        }
        b.WriteString("\n")
    }

    // Footer
    footer := tui.RenderFooter([]string{
        "Tab: Cycle",
        "Enter: Confirm",
        "Esc: Cancel",
    }, m.width)
    b.WriteString("\n")
    b.WriteString(footer)

    return b.String()
}

Key Principles:

Navigation Stack: Use for hierarchical navigation (list → detail → back)
Modal Selector: Use for switching between top-level views
Primary View Check: Only allow view switching when not in a detail view
Consistent Key Bindings:
- ```
Shift+Tab
```
  : Open view selector
- ```
Esc
```
  : Go back (in detail views) or cancel (in modals)
- ```
Enter
```
  : Select item or confirm action
- Arrow keys/vim keys: Navigate within lists and modals

Common Patterns

Formatting Utilities

Duration Formatting

func formatDuration(ms int) string {
    duration := time.Duration(ms) * time.Millisecond
    if duration < time.Second {
        return fmt.Sprintf("%dms", ms)
    }
    seconds := duration.Seconds()
    if seconds < 60 {
        return fmt.Sprintf("%.1fs", seconds)
    }
    minutes := int(seconds / 60)
    secs := int(seconds) % 60
    return fmt.Sprintf("%dm%ds", minutes, secs)
}

ID Truncation

func truncateID(id string, length int) string {
    if len(id) > length {
        return id[:length]
    }
    return id
}

Status Rendering

IMPORTANT: Do not manually style statuses. Use the status utility functions:

// For V1TaskStatus (from REST API)
status := styles.RenderV1TaskStatus(task.Status)

// The utility automatically handles:
// - COMPLETED -> Green "Succeeded"
// - FAILED -> Red "Failed"
// - CANCELLED -> Orange "Cancelled"
// - RUNNING -> Yellow "Running"
// - QUEUED -> Gray "Queued"
// All colors match frontend badge variants

Auto-refresh Pattern

// Define tick message in your view file
type tickMsg time.Time

// Create tick command
func tick() tea.Cmd {
    return tea.Tick(5*time.Second, func(t time.Time) tea.Msg {
        return tickMsg(t)
    })
}

// Handle in Update
case tickMsg:
    // Refresh data
    return v, tea.Batch(v.fetchData(), tick())

Debug Logging Pattern

Important: For views that make API calls or have complex state management, implement a debug logging system using a ring buffer to prevent memory leaks.

Step 1: Create Debug Logger (if not exists)

Create

cmd/hatchet-cli/cli/tui/debug.go

package views

import (
	"fmt"
	"sync"
	"time"
)

// DebugLog represents a single debug log entry
type DebugLog struct {
	Timestamp time.Time
	Message   string
}

// DebugLogger is a fixed-size ring buffer for debug logs
type DebugLogger struct {
	mu       sync.RWMutex
	logs     []DebugLog
	capacity int
	index    int
	size     int
}

// NewDebugLogger creates a new debug logger with the specified capacity
func NewDebugLogger(capacity int) *DebugLogger {
	return &DebugLogger{
		logs:     make([]DebugLog, capacity),
		capacity: capacity,
		index:    0,
		size:     0,
	}
}

// Log adds a new log entry to the ring buffer
func (d *DebugLogger) Log(format string, args ...interface{}) {
	d.mu.Lock()
	defer d.mu.Unlock()

	d.logs[d.index] = DebugLog{
		Timestamp: time.Now(),
		Message:   fmt.Sprintf(format, args...),
	}

	d.index = (d.index + 1) % d.capacity
	if d.size < d.capacity {
		d.size++
	}
}

// GetLogs returns all logs in chronological order
func (d *DebugLogger) GetLogs() []DebugLog {
	d.mu.RLock()
	defer d.mu.RUnlock()

	if d.size == 0 {
		return []DebugLog{}
	}

	result := make([]DebugLog, d.size)

	if d.size < d.capacity {
		// Buffer not full yet, logs are from 0 to index-1
		copy(result, d.logs[:d.size])
	} else {
		// Buffer is full, logs wrap around
		// Copy from index to end (older logs)
		n := copy(result, d.logs[d.index:])
		// Copy from start to index (newer logs)
		copy(result[n:], d.logs[:d.index])
	}

	return result
}

// Clear removes all logs
func (d *DebugLogger) Clear() {
	d.mu.Lock()
	defer d.mu.Unlock()

	d.index = 0
	d.size = 0
}

// Size returns the current number of logs
func (d *DebugLogger) Size() int {
	d.mu.RLock()
	defer d.mu.RUnlock()
	return d.size
}

// Capacity returns the maximum capacity
func (d *DebugLogger) Capacity() int {
	return d.capacity
}

Step 2: Integrate Debug Logger in Your View

type YourView struct {
	BaseModel
	// ... other fields
	debugLogger *DebugLogger
	showDebug   bool // Whether to show debug overlay
}

func NewYourView(ctx ViewContext) *YourView {
	v := &YourView{
		BaseModel: BaseModel{
			Ctx: ctx,
		},
		debugLogger: NewDebugLogger(5000), // 5000 log entries max
		showDebug:   false,
	}

	v.debugLogger.Log("YourView initialized")

	return v
}

Step 3: Add Debug Logging Throughout View

// Log important events
func (v *YourView) fetchData() tea.Cmd {
	return func() tea.Msg {
		v.debugLogger.Log("Fetching data...")

		// Make API call
		response, err := v.Ctx.Client.API().SomeEndpoint(...)

		if err != nil {
			v.debugLogger.Log("Error fetching data: %v", err)
			return dataMsg{err: err}
		}

		v.debugLogger.Log("Successfully fetched %d items", len(response.Items))
		return dataMsg{data: response.Items}
	}
}

Step 4: Add Toggle Key Handler

func (v *YourView) Update(msg tea.Msg) (View, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyMsg:
		switch msg.String() {
		case "d":
			// Toggle debug view
			v.showDebug = !v.showDebug
			v.debugLogger.Log("Debug view toggled: %v", v.showDebug)
			return v, nil
		case "c":
			// Clear debug logs (only when in debug view)
			if v.showDebug {
				v.debugLogger.Clear()
				v.debugLogger.Log("Debug logs cleared")
			}
			return v, nil
		}
	}
	// ... rest of update logic
}

Step 5: Implement Debug View Rendering

func (v *YourView) View() string {
	if v.Width == 0 {
		return "Initializing..."
	}

	// If debug view is enabled, show debug overlay
	if v.showDebug {
		return v.renderDebugView()
	}

	// ... normal view rendering
}

func (v *YourView) renderDebugView() string {
	logs := v.debugLogger.GetLogs()

	// Header
	headerStyle := lipgloss.NewStyle().
		Bold(true).
		Foreground(styles.AccentColor).
		BorderStyle(lipgloss.NormalBorder()).
		BorderBottom(true).
		BorderForeground(styles.AccentColor).
		Width(v.Width-4).
		Padding(0, 1)

	header := headerStyle.Render(fmt.Sprintf(
		"Debug Logs - %d/%d entries",
		v.debugLogger.Size(),
		v.debugLogger.Capacity(),
	))

	// Log entries
	logStyle := lipgloss.NewStyle().
		Padding(0, 1).
		Width(v.Width - 4)

	var b strings.Builder
	b.WriteString(header)
	b.WriteString("\n\n")

	// Calculate how many logs we can show
	maxLines := v.Height - 8 // Reserve space for header, footer, controls
	if maxLines < 1 {
		maxLines = 1
	}

	// Show most recent logs first
	startIdx := 0
	if len(logs) > maxLines {
		startIdx = len(logs) - maxLines
	}

	for i := startIdx; i < len(logs); i++ {
		log := logs[i]
		timestamp := log.Timestamp.Format("15:04:05.000")
		logLine := fmt.Sprintf("[%s] %s", timestamp, log.Message)
		b.WriteString(logStyle.Render(logLine))
		b.WriteString("\n")
	}

	// Footer with controls
	footerStyle := lipgloss.NewStyle().
		Foreground(styles.MutedColor).
		BorderStyle(lipgloss.NormalBorder()).
		BorderTop(true).
		BorderForeground(styles.AccentColor).
		Width(v.Width-4).
		Padding(0, 1)

	controls := footerStyle.Render("d: Close Debug  |  c: Clear Logs  |  q: Quit")
	b.WriteString("\n")
	b.WriteString(controls)

	return b.String()
}

Step 6: Update Footer Controls

Add debug controls to your normal view footer:

controls := footerStyle.Render("↑/↓: Navigate  |  r: Refresh  |  d: Debug  |  q: Quit")

Benefits:

Fixed-size ring buffer prevents memory leaks
Thread-safe with mutex protection
Toggle on/off without restarting TUI
Helps diagnose API issues and state changes
No performance impact when not viewing logs

Testing Approach

Dummy Data Generation

During development, create dummy data generators in your view file:

func generateDummyData() []YourDataType {
    now := time.Now()
    return []YourDataType{
        {
            Field1: "value1",
            Field2: "value2",
            CreatedAt: now.Add(-5 * time.Minute),
        },
        // ... more dummy items
    }
}

Example Reference

File Structure Example

cmd/hatchet-cli/cli/
├── tui.go                    # Root TUI command
└── views/
    ├── view.go               # View interface and base types
    ├── tasks.go              # Tasks view implementation
    └── workflows.go          # Workflows view implementation (future)

Complete View Example

See

cmd/hatchet-cli/cli/tui/tasks.go

for a complete implementation.

Compilation and Testing

CRITICAL: Always ensure the CLI binary compiles before considering work complete.

Compilation Check

After implementing or modifying any view:

bash

# Build the CLI binary
go build -o /tmp/hatchet-test ./cmd/hatchet-cli

# Check for errors
echo $?  # Should be 0 for success

Common Compilation Issues

UUID Type Mismatches

// ❌ Wrong - string to UUID
client.API().SomeMethod(ctx, client.TenantId(), ...)

// ✅ Correct - parse and convert
tenantUUID, err := uuid.Parse(client.TenantId())
if err != nil {
    return msg{err: fmt.Errorf("invalid tenant ID: %w", err)}
}
client.API().SomeMethod(ctx, openapi_types.UUID(tenantUUID), ...)

Required Imports

import (
    "github.com/google/uuid"
    openapi_types "github.com/oapi-codegen/runtime/types"
)

Type Conversions for API Params
- ```
*int64
```
  not
```
*int
```
  for offset/limit
- ```
time.Time
```
  not
```
*time.Time
```
  for Since parameter (check the generated types)
- ```
openapi_types.UUID
```
  for tenant and workflow IDs
- Check
```
pkg/client/rest/gen.go
```
  for exact parameter types

Pointer Helper Functions

func int64Ptr(i int64) *int64 {
    return &i
}

Testing Workflow

Compilation Test

bash

go build -o /tmp/hatchet-test ./cmd/hatchet-cli

Linting Test

After the build succeeds, run the linting checks:
bash
```
task pre-commit-run
```
Continue running this command until it succeeds. Fix any linting issues that are reported before proceeding.

Basic Functionality Test

bash

# Test with profile selection
/tmp/hatchet-test tui

# Test with specific profile
/tmp/hatchet-test tui --profile your-profile

Error Handling Test
- Try without profiles configured
- Try with invalid profile
- Test keyboard controls (q, r, arrows)
Visual/Layout Testing

When implementing a new view:
- Test at various terminal sizes (minimum 80x24)
- Ensure header and footer are always visible
- Verify instructions are clear and helpful
- Check that navigation controls are consistent with other views
- Test with both light and dark terminal backgrounds
- Verify all reusable components render correctly

Checklist for New TUI Views

Before You Start

Find the corresponding frontend view in
```
frontend/app/src/pages/main/v1/
```
Identify column structure and API calls from frontend
Note the exact API endpoint and parameters used

Creating the View

Create new file in
```
cmd/hatchet-cli/cli/tui/{viewname}.go
```
Add required imports (including
```
uuid
```
and
```
openapi_types
```
if needed)
Define view struct that embeds
```
BaseModel
```
Create
```
NewYourView(ctx ViewContext)
```
constructor
Implement
```
Init()
```
method
Implement
```
Update(msg tea.Msg)
```
method
Implement
```
View()
```
method following standard structure
Implement
```
SetSize(width, height int)
```
method

USE REUSABLE COMPONENTS:

RenderHeader()

RenderInstructions()

RenderFooter()

DO NOT copy-paste header/footer styling code
Apply Hatchet theme colors and styles for custom components only
Implement view-specific keyboard controls
Document all keyboard controls in footer using
```
RenderFooter()
```
Use appropriate REST API types
Add error handling using
```
BaseModel.HandleError()
```
Add responsive layout (handle WindowSizeMsg)

API Integration

Parse tenant ID to UUID if needed
Use correct parameter types (
```
*int64
```
,
```
time.Time
```
, etc.)
Handle API response errors
Format data for table display
Add loading states and error display

Integration and Testing

Import view in
```
tui.go
```
Update
```
newTUIModel()
```
to instantiate your view
Compile the CLI binary (
```
go build ./cmd/hatchet-cli
```
)
Fix any compilation errors
Test basic functionality with real profile
Test error cases (no profile, invalid profile)
Test keyboard controls (q, r, arrows)
Update TUI command documentation

Best Practices

CRITICAL: Use reusable components (

RenderHeader

RenderInstructions

RenderFooter

)

NEVER copy-paste header/footer styling code - this violates DRY principle
Keep view logic isolated in the view file
Use
```
ViewContext
```
to access client and profile info
Handle all messages gracefully (return
```
v, nil
```
for unhandled)
Always check
```
v.Width == 0
```
before rendering
Use consistent styling with other views (use Hatchet theme colors)
Document ALL keyboard controls in footer using
```
RenderFooter()
```
Follow the standard view structure (header, instructions, content, footer)
Always verify compilation before submitting

Post-Implementation

Update this skill document with any new patterns or learnings discovered
Document any issues encountered and their solutions
Add any new utility functions or patterns to the appropriate sections
Verify all code examples and file paths are accurate

Lessons Learned & Updates

This section documents recent learnings and updates to maintain accuracy.

Recent Updates

2026-01-10: Major updates based on workers view implementation and bug fixes:
- Added workers list view and worker details view as reference implementations
- Updated common REST API types list to include Worker, WorkerRuntimeInfo, Workflow
- Documented detail view header patterns (showing specific resource names in titles)
- Added section on filtering with multi-select forms and custom key maps
- Documented per-cell table styling using TableWithStyleFunc wrapper
- Added examples of status badge rendering in detail views
- Documented navigation messages (NavigateToWorkerMsg pattern)
- Added column alignment best practices (matching header format strings to row rendering)
- Workflow TUI implementation updates:
  - Updated header component documentation: ALL headers (primary, detail, modal) now use highlight color for consistency
  - Added
    RenderHeaderWithViewIndicator()
    for primary views (shows just view name, non-repetitive)
  - Added section 14: Table Height Calculations and Layout Optimization (height - 12 vs height - 16)
  - Added section 15: Column Consistency Between Related Views (critical for UX)
  - Added section 16: View Navigation and Modal Selector patterns
  - Documented modal selector with Shift+Tab and arrow key support
  - Documented navigation stack pattern for detail view drilling
2026-01-09: Added self-updating instructions and verification checklist
Document initialized with comprehensive TUI view building guidelines

Known Issues & Solutions

Issue: Table Column Alignment Mismatches

Problem: Header columns don't align with table rows due to format string width mismatch.

Example: In run details tasks tab, header used

%-3s

for selector column but rows only rendered 2 characters ("▸ " or " "), causing status column and all subsequent columns to be misaligned.

Solution: Ensure header format string widths exactly match row rendering:

// Header format - 2 chars for selector to match "▸ " or "  "
headerStyle.Render(fmt.Sprintf("%-2s %-30s %-12s", "", "NAME", "STATUS"))

// Row rendering - also 2 chars
if selected {
    b.WriteString("▸ ")  // 2 characters
} else {
    b.WriteString("  ")  // 2 characters
}

Prevention: Always count the exact characters rendered in rows and match header format widths precisely.

Issue: Detail View Headers Too Generic

Problem: Detail views showed generic titles like "Task Details" or "Workflow Run Details" without identifying the specific resource being viewed.

Solution: Include the resource name in the header title:

// For task details
title := "Task Details"
if v.task != nil {
    title = fmt.Sprintf("Task Details: %s", v.task.DisplayName)
}

// For workflow details
title := "Workflow Details"
if v.workflow != nil {
    title = fmt.Sprintf("Workflow Details: %s", v.workflow.Name)
}

// For run details
title := "Run Details"
if v.details != nil && v.details.Run.DisplayName != "" {
    title = fmt.Sprintf("Run Details: %s", v.details.Run.DisplayName)
}

Pattern: Use format

"{View Type} Details: {Resource Name}"

for all detail views.

Issue: Filter Form Navigation Conflicts

Problem: Global Shift+Tab handler for view switching conflicts with form navigation, preventing Tab/Shift+Tab from working in filter modals.

Solution: Process filter form messages BEFORE checking global key handlers:

// In Update(), handle form FIRST
if v.showingFilter && v.filterForm != nil {
    form, cmd := v.filterForm.Update(msg)
    if f, ok := form.(*huh.Form); ok {
        v.filterForm = f

        if v.filterForm.State == huh.StateCompleted {
            // Apply filters
            v.selectedStatuses = v.tempStatusFilters
            v.showingFilter = false
            v.updateTableRows()
            return v, nil
        }

        // Check for ESC to cancel
        if keyMsg, ok := msg.(tea.KeyMsg); ok {
            if keyMsg.String() == "esc" {
                v.showingFilter = false
                return v, nil
            }
        }
    }
    return v, cmd
}

// THEN handle global keys
switch msg := msg.(type) {
case tea.KeyMsg:
    switch msg.String() {
    case "shift+tab":
        // Global view switcher
    }
}

Pattern: Always delegate to active modal/form components before processing global keyboard shortcuts.

Issue: Filtered Workers Not Reflected in Navigation

Problem: When navigating to worker details via Enter key, code used unfiltered

v.workers

list instead of filtered list, causing cursor index mismatch with displayed rows.

Solution: Use the filtered/displayed list for navigation:

case "enter":
    // Use filteredWorkers, not workers
    if len(v.filteredWorkers) > 0 {
        selectedIdx := v.table.Cursor()
        if selectedIdx >= 0 && selectedIdx < len(v.filteredWorkers) {
            worker := v.filteredWorkers[selectedIdx]
            workerID := worker.Metadata.Id
            return v, NewNavigateToWorkerMsg(workerID)
        }
    }

Pattern: Always use the same data source for rendering and navigation. If you cache filtered data for StyleFunc, use that cached data for navigation too.

Future Improvements

(This section will track potential improvements to the TUI system or this skill document)

build-tui-view

NPX Install

Tags

SKILL.md Content

Overview

Self-Updating Skill Instructions

When to Update This Skill

How to Update This Skill

Verification Checklist

Self-Correction Process

Project Context

Finding Frontend Prior Art

Process for Finding Frontend Reference:

Example: Implementing Tasks View from Frontend Reference

Reusable Components (CRITICAL - READ FIRST)

Header Component

For Detail Views and Modals

For Primary Views

Instructions Component

Footer Component

Standard View Structure

Architecture

Root TUI Model (tui.go)

View System (views/ directory)

Core Principles

1. File Structure

TUI Command File

View Files

2. View Interface

3. Base Model Pattern

4. Creating a New View

Step 1: Create View File

Step 2: Use View in TUI

5. Client Initialization Pattern

6. Accessing the Client in Views

7. Hatchet Theme Integration

Available Theme Colors

Status Rendering

Table Styling

Adding New Status Colors

8. Standard Keyboard Controls

Global Controls (handled in tui.go)

View-Specific Controls

9. Layout Components

Header

Footer

Instructions

Stats Bar

10. Data Integration

REST API Types

Async Data Fetching Pattern

11. Modal Views

12. Form Integration

13. Table Component

14. Table Height Calculations and Layout Optimization

Standard Height Calculations by View Type

Guidelines for Height Calculation

15. Column Consistency Between Related Views

Why Column Consistency Matters

Example: Runs List Columns

Implementing Column Consistency

16. View Navigation and Modal Selector

Navigation Stack Pattern

Modal View Selector Pattern

Common Patterns

Formatting Utilities

Duration Formatting

ID Truncation

Status Rendering

Auto-refresh Pattern

Debug Logging Pattern

Step 1: Create Debug Logger (if not exists)

Step 2: Integrate Debug Logger in Your View

Step 3: Add Debug Logging Throughout View

Step 4: Add Toggle Key Handler

Step 5: Implement Debug View Rendering

Step 6: Update Footer Controls

Testing Approach

Dummy Data Generation

Example Reference

Root TUI Model (
`tui.go`
)

View System (
`views/`
directory)