Common Base Widgets

BaseFieldWidget

class BaseFieldWidget

Base mixin for common field widget patterns.

Key Properties:

mode: The current operational mode (CREATE or UPDATE)
field_id: Internal identifier for the field (e.g., “project”, “issue_type”)
jira_field_key: The Jira API field key used when sending values to the Jira API
required: Whether the field is mandatory

Key Methods:

setup_base_field(): Initializes common field properties and visual indicators (border title, required marker (*))
mark_required(): Dynamically marks a field as required after initialization

Use Case: Any widget that represents a Jira field should inherit from this mixin to ensure consistent initialization and UI presentation.

Important

This is a mixin, not a standalone widget. It should be combined with Textual widget classes via multiple inheritance.

setup_base_field(mode: jiratui.widgets.commons.base.FieldMode, field_id: str, jira_field_key: str | None = None, title: str | None = None, required: bool = False, compact: bool = True) → None

Initializes common field properties.

Parameters:

mode – the field mode (CREATE or UPDATE)
field_id – the field identifier (Jira field key).
jira_field_key – the Jira API field key. This is the id that it is used for setting the value of the field in work items. the field when requesting updates (creation/update) via the API.
title – display title for the field (defaults to field_id).
required – whether the field is required.
compact – whether to use Textual’s compact mode.

property required: bool: Checks if this field is required.

mark_required() → None: Marks this field as required by adding subtitle and CSS class.

BaseUpdateFieldWidget

class BaseUpdateFieldWidget

Base mixin for UPDATE mode widgets with change tracking.

Key Properties:

original_value: The original value from Jira before user modifications
value_has_changed: bool: A property that determines if the current value differs from the original (must be implemented by subclasses based on their value type)

Key Methods:

setup_base_field(): Initializes UPDATE mode properties including original value storage and update capability management.

Use Case: Widgets that support the UPDATE mode must inherit from this mixin to track changes and determine what needs to be sent back to Jira. This is used for widgets in the work_item_details context where we need to track changes from the original Jira value.

setup_update_field(jira_field_key: str, original_value: Any = None, field_supports_update: bool = True) → None

Initializes UPDATE mode specific properties.

Parameters:

jira_field_key – the Jira API field key. This is the id that it is used for setting the value of the field in work items.
original_value – the original value from Jira.
field_supports_update – whether Jira allows updating this field.

property original_value: Any: Retrieves the original value of the work item’s field as retrieved from the API.

abstract property value_has_changed: bool

Determines if the current value differs from the original value.

Must be implemented by subclasses based on their specific value types.

ProjectSelectionWidget

class ProjectSelectionWidget(mode: jiratui.widgets.commons.base.FieldMode, field_id: str, jira_field_key: str, title: str | None = None, required: bool = False, prompt: str | None = None, original_value: str | None = None, field_supports_update: bool = True)

Bases: textual.widgets.Select, jiratui.widgets.commons.base.BaseFieldWidget, jiratui.widgets.commons.base.BaseUpdateFieldWidget

A unified Select dropdown for choosing a Jira project that works in both CREATE and UPDATE modes.

Features:

Type-to-search capability for quick project lookup
Dynamic project population via the projects reactive property (CREATE mode only)
Original value restoration in UPDATE mode
Selection tracking with the selection property

Initialization Pattern:

# CREATE mode
project_widget = ProjectSelectionWidget(
    mode=FieldMode.CREATE,
    field_id='project',
    jira_field_key='project',
    title='Project',
    required=True,
)

# UPDATE mode
project_widget = ProjectSelectionWidget(
    mode=FieldMode.UPDATE,
    field_id='project',
    jira_field_key='project',
    original_value='PROJ',
    field_supports_update=True,
)

Initialization

Initializes a ProjectSelectionWidget.

Parameters:

mode – The field mode (CREATE or UPDATE)
field_id – Field identifier
title – Display title (defaults to field_id)
required – Whether the field is required
prompt – Custom prompt text (defaults based on required status)
original_value – Original value from Jira (UPDATE mode only)
field_supports_update – Whether field can be updated (UPDATE mode only)

projects: textual.reactive.Reactive[dict | None]

‘reactive(…)’

A dictionary with 2 keys:

projects: list selection: str | None

watch_projects(projects: dict | None = None) → None

Watches for changes to the projects reactive property (CREATE mode).

Expects a dict with ‘projects’ (list of Project objects) and optional ‘selection’.

property selection: str | None: Gets the current selection value.

property value_has_changed: bool: Determines if the current value differs from the original (UPDATE mode only).

get_value_for_update() → str | None: Returns the value formatted for Jira API updates (UPDATE mode).

IssueTypeSelectionWidget

class IssueTypeSelectionWidget(mode: jiratui.widgets.commons.base.FieldMode, field_id: str, jira_field_key: str, options: list[tuple[str, str]], title: str | None = None, required: bool = False, prompt: str | None = None, original_value: str | None = None, field_supports_update: bool = True)

Bases: textual.widgets.Select, jiratui.widgets.commons.base.BaseFieldWidget, jiratui.widgets.commons.base.BaseUpdateFieldWidget

A unified Select dropdown for choosing a Jira issue type, supporting both CREATE and UPDATE modes.

Features:

Pre-populated options provided at initialization (unlike ProjectSelectionWidget)
Type-to-search for quick issue type lookup
Mode-aware behavior with original value restoration in UPDATE mode

Initialization Pattern:

# CREATE mode with options
issue_type_widget = IssueTypeSelectionWidget(
    mode=FieldMode.CREATE,
    field_id='issue_type',
    jira_field_key='issuetype',
    options=[('Bug', '10001'), ('Story', '10002'), ('Task', '10003')],
    required=True,
)

Initialization

Initializes an IssueTypeSelectionWidget.

Parameters:

mode – The field mode (CREATE or UPDATE)
field_id – Field identifier
options – List of (display_name, value) tuples
title – Display title (defaults to field_id)
required – Whether the field is required
prompt – Custom prompt text
original_value – Original value from Jira (UPDATE mode only)
field_supports_update – Whether field can be updated (UPDATE mode only)

property selection: str | None: Get the current selection value.

property value_has_changed: bool: Determines if the current value differs from the original (UPDATE mode only).

get_value_for_update() → str | None: Returns the value formatted for Jira API updates (UPDATE mode).

LabelsAutoComplete

class LabelsAutoComplete(target: textual.widgets.Input, api_controller, required: bool = False, title: str | None = None)

Bases: textual_autocomplete.AutoComplete

Autocomplete for comma-separated labels that fetches suggestions from Jira as the user types.

Features:

Searches the Jira labels field for autocomplete suggestions
Handles comma-separated list input (user can add multiple labels)
Appends selected labels and allows continuation of typing
Minimum query length: 1 character

Workflow:

User types a partial label name
Widget calls _fetch_suggestions() asynchronously via Jira API
Suggestions are cached and dropdown is displayed
User selects a label
Widget appends it to the existing list and adds a comma for the next entry

Initialization

Initializes a LabelsAutoComplete widget.

Parameters:

target – the Input widget to attach autocomplete to
api_controller – APIController instance for fetching suggestions
required – whether the field is required
title – display title for the field (defaults to ‘labels’)

get_search_string(target_state: textual_autocomplete.TargetState) → str: Get the string to search within - just the last word for comma-separated labels.

should_show_dropdown(search_string: str) → bool

apply_completion(value: str, state: textual_autocomplete.TargetState) → None: Apply the selected completion to the input.

MultiUserPickerAutoComplete

class MultiUserPickerAutoComplete(target: textual.widgets.Input, api_controller: jiratui.api_controller.controller.APIController, required: bool = False, title: str | None = None, user_search_function: Callable | None = None)

Bases: textual_autocomplete.AutoComplete

AutoComplete for selecting multiple users.

Features:

Searches users by display name and email address
Handles comma-separated list of user names
Tracks account IDs separately from display names for API compatibility
Minimum query length: 2 characters (MIN_QUERY_TERM_LENGTH)
Supports custom search functions via the user_search_function parameter

Workflow:

User types user name or email (≥2 chars)
Widget calls the provided user_search_function asynchronously
Matching users are returned as suggestions with account IDs
User selects a user
Widget calls target.add_user() to store both name and account ID
Display refreshes to show user name; account ID stored internally

Important

The target Input widget will display a comma-separated list of names. However, the widget needs to keep track of the account ids of every user. To do that the target Input widget MUST implement a method called

add_user(account_id='', name='')

This will be used for storing the users selected in the target Input widget.

Initialization

Initializes a MultiUserPickerAutoComplete widget.

Parameters:

target – the Input widget to attach autocomplete to
api_controller – APIController instance for fetching suggestions
required – whether the field is required
title – display title for the field (defaults to ‘Users’)

Raises:: NotImplemented – if the target Input widget does not implement the required add_user method.

MIN_QUERY_TERM_LENGTH

2

The minimum length of the query used for searching users by email/display name.

get_search_string(target_state: textual_autocomplete.TargetState) → str: Gets the string to search within - just the last user’s name for comma-separated users names.

should_show_dropdown(search_string: str) → bool

apply_completion(value: str, state: textual_autocomplete.TargetState) → None: Applies the selected completion to the input.

MultiIssuePickerAutoComplete

class MultiIssuePickerAutoComplete(target: textual.widgets.Input, api_controller: jiratui.api_controller.controller.APIController, required: bool = False, title: str | None = None, issue_search_function: Callable | None = None)

Bases: textual_autocomplete.AutoComplete

AutoComplete for selecting multiple work items by key.

Features:

Searches issues by key and summary via Jira API issue picker
Handles comma-separated list of issue keys
Displays issue key + truncated summary in dropdown, but stores only the key
Minimum query length: 3 characters (MIN_QUERY_TERM_LENGTH)
Supports custom search functions via the issue_search_function parameter

Workflow:

User types issue key or summary (≥3 chars)
Widget calls the provided issue_search_function asynchronously
Matching issues are returned with key + summary preview
User selects an issue
Widget calls target.update_issues_data() to store the issue key
Display shows only the issue key (removes summary to keep input clean)

Important

The target Input widget will display a comma-separated list of issues keys. However, the widget needs to keep track of the keys of every selected issue. To do that the target Input widget MUST implement a method called

update_issues_data(issue_key='')

This will be used for storing the keys selected in the target Input widget.

Initialization

Initializes a MultiIssuePickerAutoComplete widget.

Parameters:

target – the Input widget to which the autocomplete will be applied.
api_controller – APIController instance for fetching suggestions
required – whether the field is required
title – display title for the field (defaults to ‘Issues’)

Raises:: NotImplemented – if the target Input widget does not implement the required update_issues_data method.

MIN_QUERY_TERM_LENGTH

3

The minimum length of the query used for searching issues by query term.

get_search_string(target_state: textual_autocomplete.TargetState) → str: Gets the string to search within - just the last key for comma-separated keys.

should_show_dropdown(search_string: str) → bool

apply_completion(value: str, state: textual_autocomplete.TargetState) → None: Applies the selected completion to the input.