UI — Display, Input & Styles¶

The UI package handles terminal rendering, user input, picker widgets, and visual styling.

Display¶

Display functions for task list UI — re-export facade.

jot.ui.display.display_all_categories_view(all_cat_data, project_dir, show_archived=False)[source]¶

Render the ALL_CATEGORIES grouped task view.

Parameters:

all_cat_data – List of (cat_name, is_global, tasks, archived) tuples.
project_dir – Path to the project directory (for category config).
show_archived – Whether to include archived tasks in the view.

jot.ui.display.display_all_projects(registry, show_categories=False)[source]¶: Display all projects with their tasks grouped by project.

jot.ui.display.display_archive(project_dir, filter_category=None)[source]¶: Display archived tasks with optional category filter.

jot.ui.display.display_category_stats(project_dir)[source]¶: Display statistics for all categories in a project.

jot.ui.display.display_categorized_shortcuts()[source]¶: Display keyboard shortcuts organized by category (non-modal).

jot.ui.display.display_help()[source]¶: Display comprehensive help information.

jot.ui.display.display_tasks(tasks, mode='quick_add', input_buffer='', project_name=None, category=None, is_global=False, show_archived=False, archived_tasks=None, selected_tasks=None, search_buffer='', archived_task_ids=None, include_archived_in_search=True, show_shortcuts=False, show_notes_inline=False, match_positions=None, collapsed_parents=None, all_tasks=None, claude_status='')[source]¶: Display current task list with mode indicator.

Task Display¶

Display function for the main task list view.

jot.ui.display_tasks.display_tasks(tasks, mode='quick_add', input_buffer='', project_name=None, category=None, is_global=False, show_archived=False, archived_tasks=None, selected_tasks=None, search_buffer='', archived_task_ids=None, include_archived_in_search=True, show_shortcuts=False, show_notes_inline=False, match_positions=None, collapsed_parents=None, all_tasks=None, claude_status='')[source]¶: Display current task list with mode indicator.

Footer Display¶

Mode-specific footer rendering for the main task display.

jot.ui.display_footer.render_mode_footer(mode, input_buffer, selected_tasks, search_buffer, tasks, archived_task_ids, include_archived_in_search, show_shortcuts)[source]¶: Render the mode-specific footer at the bottom.

jot.ui.display_footer.render_archived_section(archived_tasks)[source]¶: Render the archived tasks section below the active list.

Help Display¶

Display functions for help and keyboard shortcuts.

jot.ui.display_help.help_modal()[source]¶

Show a centered, scrollable help modal. Blocks until dismissed.

Controls:: ↑/↓ or j/k Scroll one line PgUp/PgDn Scroll one page Home/End Jump to top/bottom ESC/q/? Dismiss

jot.ui.display_help.display_categorized_shortcuts()[source]¶: Display keyboard shortcuts organized by category (non-modal).

jot.ui.display_help.display_help()[source]¶: Display comprehensive help information.

Projects Display¶

Display functions for project and category statistics.

jot.ui.display_projects.display_all_projects(registry, show_categories=False)[source]¶: Display all projects with their tasks grouped by project.

jot.ui.display_projects.display_category_stats(project_dir)[source]¶: Display statistics for all categories in a project.

Archive Display¶

Display functions for archive and all-categories views.

jot.ui.display_archive.display_archive(project_dir, filter_category=None)[source]¶: Display archived tasks with optional category filter.

jot.ui.display_archive.display_all_categories_view(all_cat_data, project_dir, show_archived=False)[source]¶

Render the ALL_CATEGORIES grouped task view.

Parameters:

all_cat_data – List of (cat_name, is_global, tasks, archived) tuples.
project_dir – Path to the project directory (for category config).
show_archived – Whether to include archived tasks in the view.

Formatting¶

UI formatting utilities for task display

jot.ui.formatting.format_inline_notes(notes, max_lines=3, max_width=70)[source]¶

Format task notes for inline display with truncation

Returns a list of formatted lines ready for printing.

jot.ui.formatting.format_category_badges(category_manager, cat_config, current_category, is_global_current)[source]¶: Format category badges for display header

Styles¶

Central terminal style definitions for jot

Single source of truth for all ANSI color codes, formatting constants, and semantic color mappings used across the UI.

jot.ui.styles.get_terminal_width()[source]¶: Return current terminal width, defaulting to 80.

jot.ui.styles.strip_ansi(text)[source]¶: Remove ANSI escape sequences from text.

jot.ui.styles.visible_len(text)[source]¶: Return the visible (non-ANSI) length of text.

Input¶

Terminal input utilities for jot

Uses prompt_toolkit when available for improved input handling (history, completion, proper key binding). Falls back to stdlib termios/readline if prompt_toolkit is not installed.

jot.ui.input.restore_terminal()[source]¶

Restore terminal to normal (cooked) mode and flush pending input.

Call this before using input() or other line-oriented IO after the main loop’s get_key() has been reading in raw mode.

jot.ui.input.flush_input()[source]¶: Flush any pending terminal input without changing mode.

jot.ui.input.get_key(timeout=1.0)¶

Read a single keypress using prompt_toolkit’s Vt100Parser.

Uses prompt_toolkit’s battle-tested escape sequence parser instead of manual character-by-character parsing. Returns the same values as _get_key_legacy for full compatibility: - None on timeout - ‘UP’, ‘DOWN’, ‘SHIFT_UP’, ‘SHIFT_DOWN’ for arrow keys - (‘PASTE’, text) for pasted content - Raw character for everything else

jot.ui.input.input_with_prefill(prompt_text, prefill='')¶

Get input with pre-filled text using prompt_toolkit.

Gains over readline version: - Persistent history at ~/.jot_history (Ctrl+R to search) - Proper line editing with cursor movement

Rendering¶

Rendering utilities for flicker-free terminal output.

jot.ui.rendering.buffered_output()[source]¶

Redirect stdout to a buffer, then flush in one write.

Wrapping a render pass in this context manager ensures the terminal receives the entire frame atomically, eliminating partial-frame tearing.

Picker¶

Reusable interactive terminal picker with fuzzy filtering.

Provides fuzzy_picker() for filterable lists and quick_picker() for small fixed-choice menus. Both use get_key() for raw keyboard input and render a visual selection indicator.

class jot.ui.picker.PickerItem(value, label, annotation='', color='', symbol='')[source]

Bases: object

A single item in a picker list.

value: Return value when this item is selected.

label: Display text shown in the list.

annotation: Optional dim text after the label (e.g., path, “[global]”).

color: Optional ANSI color code for the label.

symbol: Optional symbol prefix (e.g., priority symbol).

value: str

label: str

annotation: str = ''

color: str = ''

symbol: str = ''

class jot.ui.picker.PickerResult(value=None, is_freeform=False)[source]

Bases: object

Result from fuzzy_picker() or quick_picker().

value: Selected item’s value, freeform text, or None if cancelled.

is_freeform: True if value was typed by the user (not from the list).

value: object = None

is_freeform: bool = False

jot.ui.picker.fuzzy_picker(items, prompt='Select', *, enable_filter=True, max_display=15, allow_freeform=False, freeform_hint='Type a new name and press Enter', default_index=0)[source]

Interactive terminal picker with optional fuzzy filtering.

Parameters:

items – List of PickerItem objects.
prompt – Title text displayed at top.
enable_filter – If True, typing filters via fuzzy_match().
max_display – Max items visible at once.
allow_freeform – If True, Enter with no matches returns typed text.
freeform_hint – Hint shown when allow_freeform and no matches.
default_index – Pre-selected item index (0-based).

Returns:

PickerResult with value=None if cancelled (ESC).

jot.ui.picker.quick_picker(items, prompt='Select', *, default_index=0)[source]

Arrow-key picker for small lists (no fuzzy filtering).

Thin wrapper around fuzzy_picker() with filtering disabled.

jot.ui.picker.multiselect_picker(items, prompt='Select', *, max_display=20, select_all_default=True)[source]

Interactive checkbox picker — Space toggles, Enter confirms.

Parameters:

items – List of PickerItem objects.
prompt – Title text.
max_display – Max visible items.
select_all_default – If True, all items start checked.

Returns:

List of selected PickerItem.value values, or [] if cancelled.