Widgets for Updating Work Items

This module contains the widgets used for displaying and updating fields associated to a work item.

IssueDetailsWidget

class IssueDetailsWidget

Bases: textual.containers.Vertical

Implements a form to allow the user to view and edit some of the fields associated to a work item.

The widget defines a form for viewing and updating some of the work item’s fields. The form includes both static and dynamic widgets.

Static widgets are composed into the form and are used for displaying and updating the following work item fields:

  • Summary

  • Assignee

  • Reporter

  • Status

  • Priority

  • Key

  • Parent

  • Sprint

  • Type

  • Project Key

  • Created Date

  • Last Update Date

  • Due Date

  • Resolved

  • Resolution

Dynamic widgets are composed dynamically based on the work item’s edit metadata and the configuration of the application, via the variables enable_updating_additional_fields and update_additional_fields_ignore_ids.

See Also:

Initialization

Initialize a Widget.

Parameters:

  • children – Child widgets.

  • name – The name of the widget.

  • id – The ID of the widget in the DOM.

  • classes – The CSS classes for the widget.

  • disabled – Whether the widget is disabled or not.

  • markup – Enable content markup?

issue: textual.reactive.Reactive[jiratui.models.JiraIssue | None]

‘reactive(…)’

Reactive variable that contains the work item currently being displayed.

clear_form: textual.reactive.Reactive[bool]

‘reactive(…)’

Reactive variable to clear the fields in the form.

compose() → textual.app.ComposeResult
on_mount() → None

Initializes the autocomplete fields after mounting.

action_focus_widget(key: str) → None

Focuses a widget depending on the key pressed.

This will only focus the following widgets:

  • assignee_selector (key x)

  • priority_selector (key y)

  • issue_status_selector (key z)

Parameters:

key – the key that was pressed.

Returns:

None.

action_flag_work_item() → None

Opens a modal screen to let the user add/remove a flag with an optional comment/note.

action_view_worklog() → None

Opens a pop-up modal to display the work log of a work item.

Returns:

None.

action_log_work() → None

Opens a pop-up modal to allow the user to log work for the current work item.

Returns:

None

watch_clear_form(clear: bool = False) → None

Resets the fields to make sure that there are no values from the previously selected work item.

Parameters:

clear – if True it will reset the form’s fields to their default values.

Returns:

None.

async action_save_work_item() → None

Updates the fields of a work item that have changed.

Returns:

None.

watch_issue(work_item: jiratui.models.JiraIssue | None) → None

Updates the form fields with the details of the work item selected by the user.

This method does the following:

  • resets the widgets in the form.

  • fills-in the (static) widgets in the form based on the currently selected work item.

    • retrieves the list of status codes applicable for the selected work item and its type

    • checks if the work item is flagged and displays the flag

  • if the app is configured to update additional fields, config.enable_updating_additional_fields, then this method will generate and mount widgets for every additional field based on the work item’s edit metadata.

Parameters:

work_item – a work item selected by the user in the left-hand side panel.

Returns:

None.

IssueDetailsStatusSelection

class IssueDetailsStatusSelection(statuses: list)

Bases: jiratui.widgets.filters.IssueStatusSelectionInput

A selection field that stores the status field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialize the Select control.

Parameters:

  • options – Options to select from. If no options are provided then allow_blank must be set to True.

  • prompt – Text to show in the control when no option is selected.

  • allow_blank – Enables or disables the ability to have the widget in a state with no selection made, in which case its value is set to the constant [Select.NULL][textual.widgets.Select.NULL].

  • value – Initial value selected. Should be one of the values in options. If no initial value is set and allow_blank is False, the widget will auto-select the first available option.

  • type_to_search – If True, typing will search for options.

  • name – The name of the select control.

  • id – The ID of the control in the DOM.

  • classes – The CSS classes of the control.

  • disabled – Whether the control is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact select (without borders).

Raises:

EmptySelectError – If no options are provided and allow_blank is False.

jira_field_key

‘status’

The key to used by Jira to identify this field in the edit-metadata.

IssueDetailsPrioritySelection

class IssueDetailsPrioritySelection(priorities: list[tuple[str, str]])

Bases: textual.widgets.Select

A widget to display and update the priority field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialize the Select control.

Parameters:

  • options – Options to select from. If no options are provided then allow_blank must be set to True.

  • prompt – Text to show in the control when no option is selected.

  • allow_blank – Enables or disables the ability to have the widget in a state with no selection made, in which case its value is set to the constant [Select.NULL][textual.widgets.Select.NULL].

  • value – Initial value selected. Should be one of the values in options. If no initial value is set and allow_blank is False, the widget will auto-select the first available option.

  • type_to_search – If True, typing will search for options.

  • name – The name of the select control.

  • id – The ID of the control in the DOM.

  • classes – The CSS classes of the control.

  • disabled – Whether the control is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact select (without borders).

Raises:

EmptySelectError – If no options are provided and allow_blank is False.

jira_field_key

‘priority’

The id used by Jira to identify this field in the edit-metadata.

update_is_enabled: bool

True

Indicates whether the work item allows editing/updating this field.

ProjectIDField

class ProjectIDField

Bases: jiratui.widgets.base.ReadOnlyField

A widget to display and update the project field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

IssueSprintField

class IssueSprintField

Bases: jiratui.widgets.base.ReadOnlyField

A widget to display and update the sprint field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

IssueKeyField

class IssueKeyField

Bases: jiratui.widgets.base.ReadOnlyField

A widget to display and update the key field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

IssueParentField

class IssueParentField

Bases: textual.widgets.Input

A widget to display and update the parent field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

jira_field_key

‘parent’

The id used by Jira to identify this field in the edit-metadata.

update_is_enabled

True

Indicates whether the work item allows editing/updating this field.

IssueSummaryField

class IssueSummaryField

Bases: textual.widgets.Input

A widget to display and update the summary field of a work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

jira_field_key

‘summary’

The id used by Jira to identify this field in the edit-metadata.

update_is_enabled

True

Indicates whether the work item allows editing/updating this field.

IssueTypeField

class IssueTypeField

Bases: jiratui.widgets.base.ReadOnlyField

A widget to display and update the type of work item.

This widget is part of widgets defined statically in the form that allows users to update a work item.

Initialization

Initialise the Input widget.

Parameters:

  • value – An optional default value for the input.

  • placeholder – Optional placeholder text for the input.

  • highlighter – An optional highlighter for the input.

  • password – Flag to say if the field should obfuscate its content.

  • restrict – A regex to restrict character inputs.

  • type – The type of the input.

  • max_length – The maximum length of the input, or 0 for no maximum length.

  • suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

  • validators – An iterable of validators that the Input value will be checked against.

  • validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

  • valid_empty – Empty values are valid.

  • select_on_focus – Whether to select all text on focus.

  • name – Optional name for the input widget.

  • id – Optional ID for the widget.

  • classes – Optional initial classes for the widget.

  • disabled – Whether the input is disabled or not.

  • tooltip – Optional tooltip.

  • compact – Enable compact style (without borders).

WorkItemDetailsDueDate

class WorkItemDetailsDueDate

Bases: jiratui.widgets.commons.widgets.DateInputWidget

A widget to display the due date of a work item and to allow the user to update its value.

Initialization

Initializes a DateInputWidget.

Parameters:

  • mode – The field mode (CREATE or UPDATE)

  • field_id – Field identifier (Jira field key)

  • jira_field_key – the key of the field that it is used for updating the field value in the API.

  • title – Display title (defaults to field_id)

  • required – Whether the field is required (mainly for CREATE mode)

  • original_value – Original date value from Jira (UPDATE mode only)

  • field_supports_update – Whether field can be updated (UPDATE mode only)

update_is_enabled

True

Indicates whether the work item allows editing/updating this field.

set_original_value(value: str | None) → None

Sets both the original_value and current value, resetting change tracking.

This should be called when loading a work item to initialize the widget with the current Jira value.

Parameters:

value – The date string from Jira (e.g., ‘2025-01-15’ or None)