Common Users Widgets

User input and autocomplete widgets for Jira user selection.

This module provides specialized Textual widgets for selecting Jira users within the TUI application. It combines an input field with autocomplete functionality to allow users to search and select from available Jira users.

Classes:

  • JiraUserInput: An input field widget that stores the selected Jira user’s account ID alongside the display value. Supports reactive state management for enabled/disabled states and integrates with the autocomplete provider.

  • UsersAutoComplete: An autocomplete provider that dynamically searches for Jira users via the API as the user types. Implements caching to improve performance and supports custom user search functions for advanced filtering.

Typical Usage:

The JiraUserInput and UsersAutoComplete widgets are typically used together to create a user selection field with live search capabilities:

1from textual.widgets import Input
2from jiratui.widgets.commons.users import JiraUserInput, UsersAutoComplete
3
4user_input = JiraUserInput(id='user_selector')
5UsersAutoComplete(
6    target=user_input, api_controller=api_controller, user_search_function=custom_search_fn
7)

The selected user’s account ID can be retrieved via the account_id property of the JiraUserInput instance.

Dependencies:

  • textual: TUI framework

  • textual-autocomplete: Autocomplete widget extension

  • jiratui.controllers.api: API controller for Jira queries

JiraUserInput

class JiraUserInput(*args, **kwargs)

Bases: textual.widgets.Input

An input field for selecting a single Jira user.

This widget is specifically designed for statically composed widgets; i.e. widgets that are defined in the compose() method of other widgets.

If you need to support single/multi-user selection for dynamically created widgets then use SingleUserPickerWidget and MultiUserPickerWidget.

This widget holds the Jira user’s account id that is used to identify the user. The widget MUST implement a property called account_id to retrieve and set the account id of the selected user.

This widget can be used with the UsersAutoComplete widget to support autocomplete search functionality.

Examples

users_selector = JiraUserInput(
    id='search-filters-input-assignee',
    border_subtitle='(a)',
    border_title='Assignee',
)
await mount(
    UsersAutoComplete(
        users_selector,
        api,
        id='filter-assignee-autocomplete',
        user_search_function=custom_search_function,
    )
)

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

None

The id used by Jira to identify this field in the edit-metadata or to update its value in a work item.

property account_id: str | None

This is required to support autocomplete behavior.

clear()

UsersAutoComplete

class UsersAutoComplete(target: textual.widgets.Input, api_controller: jiratui.api_controller.controller.APIController, user_search_function: Callable | None = None, id: str | None = None)

Bases: textual_autocomplete.AutoComplete

AutoComplete for Jira users that searches users using the Jira API.

This widget fetches users dynamically as the user types. It requires an Input widget as the target; the target widget MUST provide a property to set the user’s account id, account_id.

This is useful for filtering users by name or email addresses, e.g. when searching for possible reporters.

Initialization

Initializes a UsersAutoComplete widget.

Parameters:

  • target – the Input widget to attach autocomplete to

  • api_controller – APIController instance for fetching suggestions.

  • user_search_function – an async callable that searches and filters users based on a query term.

  • id – the id for this widget.

MIN_QUERY_TERM_LENGTH

3

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

should_show_dropdown(search_string: str) → bool
apply_completion(value: str, state: textual_autocomplete.TargetState) → None