Ticket Widget: List Type

The List type shows a set of items. Use it to list related things, such as linked tickets, assets or knowledge base articles. Each item can be plain text, a link to another page, or an action that loads new content into the widget.

In short: you return a list of items. Each item has a title and an optional description. Its type and url decide what happens on click. An item can also have a "…" menu with more choices.

How it renders

The widget is laid out in this order: header, description, value, actions. For a List widget the value is the list of items.

• If value is empty, the value part is not displayed. The rest of the widget still shows.
• Only the first 25 items are displayed. Show the most relevant 25, or use an action to load another set.
• The title is required and shown in bold. If it is too wide for the screen, it is truncated.
• The description is optional and shown in a subtle style. It wraps onto more lines.
• A "…" icon appears on an item that has entries.

The layout is the same on small screens. Titles are truncated and descriptions wrap.

Items are not selectable. Selection is only available in the Form type.

Item types

The item's type decides what a click does.

Unlike the widget-level actions, list items have a type, so one list can mix plain, action and link items.

If the data is incomplete

• A url with no type, or with default, is treated as a action.
• A type of action or link with no url is treated as a plain item.

Set both type and url yourself, so the result doesn't depend on these rules.

The "…" menu

entries adds a "…" menu to an item. It is an extra, so it works with every item type, including plain items with no url.

Each entry has a label, a url and a type of action or link, with the same behaviour as items: an action entry fetches its url, and a link entry links to it.

• Up to 5 entries per item. More are dropped.
• Entries cannot have their own menus.

Use it for secondary choices, such as "Unlink" or "Open in portal".

Example

{
  "type": "list",
  "title": "Related items",
  "value": [
    { "title": "Printer is out of toner" },
    {
      "title": "Laptop LT-0042",
      "description": "Assigned to Jane Smith",
      "type": "action",
      "url": "/widgets/assets/LT-0042"
    },
    {
      "title": "How to reset a password",
      "description": "Knowledge base",
      "type": "link",
      "url": "https://kb.example.com/reset-password",
      "entries": [
        { "label": "Copy to reply", "type": "action", "url": "/widgets/kb/copy?id=17" },
        { "label": "Open in portal", "type": "link", "url": "https://portal.example.com/kb/17" }
      ]
    }
  ]
}

Type reference

export interface ListTicketWidgetContent extends TicketWidgetContentBase<
  ReadonlyArray<TicketWidgetListItem>
> {
  readonly type: 'list';
}

export interface TicketWidgetListItem {
  /**
   * Maximum 250 characters. Hard-truncated (client-side) beyond this length.
   */
  readonly title: string;
  /**
   * Maximum 500 characters. Hard-truncated (client-side) beyond this length.
   */
  readonly description?: string;

  /**
   * - 'default': item is not interactive.
   * - 'action': `url` is fetched and the response replaces this list item's content.
   * - 'link': `url` is opened as navigation (new tab).
   *
   * Fallback rules (defensive against malformed provider data):
   * - `url` present but `type` omitted or 'default' → treated as 'link'.
   * - `type` is 'action' or 'link' but `url` is missing → treated as 'default'.
   */
  readonly type?: TicketWidgetItemType;

  readonly url?: string;

  /**
   * When present, UI displays a "…" icon that opens these entries in a dropdown.
   * Maximum 5 items. Items beyond this are dropped.
   */
  readonly entries?: ReadonlyArray<TicketWidgetItemEntry>;
}

export type TicketWidgetItemType = 'default' | 'action' | 'link';

export type TicketWidgetItemEntryType = 'action' | 'link';

export interface TicketWidgetItemEntry {
  readonly icon?: CustomSvgContent;
  /**
   * Maximum 80 characters. Hard-truncated (client-side) beyond this length.
   */
  readonly label: string;
  readonly url: string;
  readonly type: TicketWidgetItemEntryType;
}

export interface TicketWidgetContentBase<T> {
  readonly type: TicketWidgetContentType;

  readonly refreshMode?: TicketWidgetRefreshMode;
  readonly refreshIntervalSec?: number;

  readonly icon?: CustomSvgContent;

  /**
   * Maximum 256 characters. Hard-truncated (client-side) beyond this length.
   */
  readonly title: string;
  readonly titleColour?: ContentColor;

  /**
   * Markdown content, does not support HTML embed.
   * Maximum 10,000 characters. Hard-truncated (client-side) beyond this length.
   */
  readonly description?: string;

  readonly borderColour?: ContentColor;

  readonly value: T;

  /**
   * Action rendered on the far left, isolated from the secondary/primary
   * action group (e.g. "back" in a multi-step form).
   *
   * Never gated by form validation: always enabled, even when the form is
   * incomplete. When `form` is present, the current (possibly partial)
   * answers are sent with the request so the provider can restore them
   * (e.g. when the user steps back). This is NOT a submission; the provider
   * must not validate, persist or act on the answers.
   */
  readonly leadingAction?: TicketWidgetAction;

  /**
   * Secondary action rendered on the right, before the primary action.
   * Typically a lower-emphasis action (e.g. "cancel", "skip").
   *
   * Never gated by form validation: always enabled, even when the form is
   * incomplete. When `form` is present, the current (possibly partial)
   * answers are sent with the request so the provider can remember them.
   * This is NOT a submission; the provider must not validate, persist or
   * act on the answers.
   */
  readonly secondaryAction?: TicketWidgetAction;

  /**
   * Primary action rendered on the far right, the main call-to-action
   * for this widget (e.g. "next", "submit").
   *
   * When `form` is present, disabled until the form is complete (all
   * required fields answered). This is the only action that submits the
   * form: the answers are sent as a submission, and the provider should
   * validate and act on them.
   */
  readonly primaryAction?: TicketWidgetAction;

  /**
   * Answers submitted by the user, keyed by field identifier, and sent back
   * to the provider on the next request.
   *
   * Limits:
   * - Maximum 20 entries. Entries beyond this are dropped.
   * - Key: maximum 100 characters. Hard-truncated (client-side) beyond this length.
   * - A null result is replaced with an empty result.
   * - Invalid results are dropped, not converted.
   * - Each choice identifier is hard-truncated (client-side) to 100 characters.
   * - Maximum 10 choices per result. Choices beyond this are dropped.
   */
  readonly form?: Record<string, TicketWidgetFieldResult>;

  /**
   * Arbitrary provider-defined data carried across requests. The client
   * persists whatever the provider returns here and sends it back verbatim
   * on the next request. Providers do not need to store session state
   * themselves; the round trip through the client is the only state store.
   *
   * Limits (anything exceeding them is dropped, not truncated):
   * - Maximum 20 entries.
   * - Key: maximum 100 characters.
   * - Value: maximum 1,000 characters.
   * - Non-string values are dropped, not converted.
   */
  readonly state?: Record<string, string>;
}