Work item widget patterns

Defining "widget"

A widget is a single component that can exist on a work item. This component can be used on one or many work item types and can be lightly customized at the point of implementation.

A widget contains both the frontend UI (if present) and the associated logic for presenting and managing any data used by the widget. There can be a one:many connection between the data model and widgets — there can be multiple widgets that utilize or manage the same data, and these could be present at the same time (e.g. a readonly summary widget and an editable detail widget, or two widgets showing two different filtered views of the same model).

Widgets should be differentiated by their purpose. When possible, this purpose should be abstracted to the highest reasonable level to maximize reusability — as an example, the widget for managing "tasks" was built as "child items", rather than managing one type of child it's abstracted up to managing any children.

See also: Work Item Type Widgets, Widgets FE Guide

Purpose

Widgets within work items need to utilize consistent conventions to display available functionality across different states (default, focus, active, readonly).

Creating a standard widget component will simplify ongoing widget development while providing a more consistent user experience.

Widgets currently break down to ~4 types:

  • Attributes: Widgets containing a label and value, where the value is typically but not always editable. Attributes are displayed together in the stack. Attributes can be set. Ex. assignee, weight, labels.
  • Actions: Widgets that modify the work item, typically in a binary fashion. Actions are displayed together in the menu. Actions can be applied. Ex. confidential, move, delete
  • Applications: Widgets that can contain a mix of data and actions, which have greater flexibility in how they're presented. Applications can be displayed anywhere in the work item. Applications can be utilized. Ex. design manager, child items.
  • Helper: User actions that have no system impact and are provided only as a shortcut for users. Helpers can be displayed wherever contextually relevant and are always(?) buttons. Helpers can be pressed. Ex. copy reference, copy email (helpers and actions could be combined, but they feel different enough)

Current widgets can be found here #368044 — these are roughly categorized as:

Widget Current Type Attribute Type
Title 🍱 App Short text
Description 🍱 App Long text
Close ⚡️ Action -
Assignees ➡️ Attribute Single or Multi-selection
Dates ➡️ Attribute Date
Labels ➡️ Attribute Multi-selection
Epic ➡️ Attribute Single selection
Milestone ➡️ Attribute Single selection
Iteration ➡️ Attribute Single selection
Weight ➡️ Attribute Number
Time Tracking 🍱 App -
Health Status ➡️ Attribute Single selection
Confidentiality ⚡️ Action -
Lock ⚡️ Action -
Notifications ⚡️ Action (User scope) -
Copy Reference 🖐 Helper -
Copy Email 🖐 Helper -
Move ⚡️ Action -
Linked Items 🍱 App -
Linked MRs 🍱 App -
Award Emoji 🍱 App -
Timeline 🍱 App -
Children Tree 🍱 App -
Clone ⚡️ Action -
Create MR/Branch ⚡️ Action -
Design Manager 🍱 App -
Discussion Threads 🍱 App -
System Notes 🍱 App -
Ancestors 🍱 App -
Summary 🍱 App -
Metrics 🍱 App -
Status (Incident) ➡️ Attribute Single selection
Escalation Policy ➡️ Attribute Single selection
Severity ➡️ Attribute Single selection
Todo 🍱 App -
Participants 🍱 App -

Attribute Widgets

Attribute widgets have the highest need for consistent presentation as they are always displayed side by side and should be expected to work in a predictable fashion.

Proposal (WIP):

  • Empty states display using a consistent pattern
    • Consideration: only show entered fields by default, add other fields as needed to minimize empty content
  • All editable values displayed using the same base styling (e.g. as an input, or button) in default and hover states
  • On clicking a value, show relevant controls (e.g. input, open dropdown, etc)
  • All non-editable values displayed as values with minimal/no interactivity related to editing

Considerations:

  • Handling embedded links (separate "open" button)
  • Equal support for light and dark mode
  • Mobile specific patterns for complex inputs like comboboxes
  • Possibility for active-state "wrapper" to further streamline inputs

Application Widgets

Application widgets can be more flexible in presentation but should in most cases feel like they're part of the same system. Application widgets can be interactive or just presentation, but should have more than a single data point or a more complex visualization of a data point — otherwise it should be treated as an attribute.

Edited by Nick Leonard