(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Progress States

Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-45017&t=ftfrOGkPzlG2GaTo-1

Overview

• The Dynamic Progress States component displays a sequence of states to show progression through a process, workflow, or journey.
• It can visualize status information from a data source or from static configurations.
• The layout can be horizontal or vertical depending on the process type.
• Each state supports customizable appearance, including titles, subtitles, and additional information.
• The component is useful for tracking current progress and context within multi-step workflows.

Specs

Tokens

Structure

(Configured in General Properties)

• displayName - Sets the display name of the component shown in the structure panel. For example, "Order Processing States" allows for easy identification of the component's purpose in the component structure. Example: "OrderProcessingStates".

(Configured in Datasource)

• enableStaticData - Determines whether the component uses statically defined states or fetches state data from a data source. When set to true, the component will use the states defined in the "states" property. Example: false.
• getElementsDataSourceId - Specifies the data source ID for retrieving progress states data. This connects the component to an API endpoint that returns the state data. Example: "api/order/process-states".
• getEntityCollectionHttpRequestParametersMap - Configures HTTP request parameters for fetching data from the API. This allows customizing query parameters, path parameters, or request body. Example:

{
  "PATH": {
    "orderId": "context.selectedOrder.id"
  },
  "QUERY": {
    "includeHistory": "true"
  }
}

State

(Configured in Data Configuration)

• states - Defines static state configurations when not using a data source. Each state has its own title, subtitle, status, and optional action configuration. Example:

[
  {
    "id": 0,
    "titleTranslations": {"en-US": "Submitted"},
    "subtitleTranslations": {"en-US": "Order received"},
    "status": 1,
    "information": [{"iconName": "calendar", "text": "April 15, 2025"}]
  },
  {
    "id": 1,
    "titleTranslations": {"en-US": "Processing"},
    "subtitleTranslations": {"en-US": "Order in preparation"},
    "status": 3,
    "information": []
  }
]

• stateIdField - Defines which field in the data source serves as the unique identifier for each state. This is crucial for correctly identifying and tracking states. Example: "stateId".
• currentStateField - Specifies the field name that indicates whether a state is the current active state. This field should contain a boolean value (true/false) in the data. Example: "isCurrentState".
• sortOrderField - Determines which field in the data source is used to sort the states in their display order. States will be arranged based on the values in this field, from lowest to highest. Example: "sequence".
• statusRules - Defines rules for dynamically determining the visual status of each state (valid, invalid, pending, disabled) based on data conditions. Rules can compare field values with static values or with values from the current state. Example:

[
  {
    "field": "completionPercent",
    "operator": "greaterEqual",
    "valueType": "customValue",
    "value": "100",
    "status": "1",
    "priority": "1"
  }
]

• informationConfigs - Configures additional information items displayed for each state, such as details or metrics with optional icons. This allows showing supplementary data below each state. Example:

[
  {
    "iconName": "info",
    "text": {
      "en-US": "Updated {{lastUpdatedDate}}",
      "de-DE": "Aktualisiert {{lastUpdatedDate}}"
    }
  }
]

Styling

(Configured in Visual Properties)

• direction - Determines the layout direction of the progress states. Options include "horizontal" (states arranged side by side) or "vertical" (states stacked vertically). Horizontal layout works well for process flows that move from left to right, while vertical is suitable for top-down workflows. Example: "horizontal".
• titleField - Specifies the field name in the data source that contains the title for each state. For example, setting it to "stateName" will display the value of the "stateName" field as the title for each state. Example: "stateName".
• subtitleField - Specifies the field name in the data source that contains the subtitle text for each state. This provides additional context or detail below the main title for each state. Example: "stateDescription".
• paddingClass - Configures the padding space around the component using CSS classes. For example, "p-3" adds medium padding on all sides of the component. Example: "p-3".

Actions & Variants

(Configured in Visual Properties)

• readonly - Controls whether the progress states are interactive or display-only. When set to true, users cannot trigger actions associated with the states. Example: true.

(Configured in Events)

• events - Configures the events that the component can trigger and respond to.
• ON_INIT (Events) - Triggered when the component is initialized. Can be used to load default data or perform setup operations.
• ON_DESTROY (Events) - Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

Tests

(Configured in Testing Hooks)

• id - Specifies the unique identifier for the component, used for programmatic access. Example: "orderProcessingStates".
• dataTestId - Sets the testing hook ID for automated testing. Example: "order-process-states-component".
• enableAsHotspot - Enables the component as a guided tour hotspot. When set to true, the component can be highlighted during guided tours. Example: true.
• guidedTourHotSpotTitle - Sets the title for the guided tour hotspot, supporting translations. Example: {"en-US": "Order Process", "fr-FR": "Processus de commande"}.
• guidedTourHotSpotDescription - Sets the description for the guided tour hotspot, supporting translations. Example: {"en-US": "Track the progress of your order through these states", "fr-FR": "Suivez la progression de votre commande à travers ces états"}.

Guidelines

Usage

• visualize progression through discrete steps using either dynamic or static sources. configure with enableStaticData, states, or getElementsDataSourceId and getEntityCollectionHttpRequestParametersMap.
• indicate the active step by mapping the data field that marks it as current via currentStateField.
• present key labels by mapping titles and subtitles from your data (titleField, subtitleField) or, in static mode, via states[].titleTranslations and states[].subtitleTranslations.
• add compact, per-state context (dates, metrics) using informationConfigs (supports iconName and localized text).

Sizing & Layout

• switch between left-to-right and top-down presentations using direction.
• tune outer spacing with paddingClass to keep content readable.
• keep text succinct by sourcing only short labels via titleField/subtitleField (or concise states[].*Translations) so step headers remain scannable.

States & Feedback

• drive visual status per step using statusRules and resolve conflicts with rule priority.
• avoid color-only meaning by pairing status with short, noncritical text via informationConfigs.

Interactions & Events

• enforce view-only timelines by setting readonly: true when no actions are expected.

Visibility & Authorization

• hide or show the component based on app state via displayConditions.
• restrict visibility for roles/entitlements via visibilityPolicySetId.

Content & Localization

• localize all user-visible copy: states[].titleTranslations, states[].subtitleTranslations, informationConfigs[].text, guidedTourHotSpotTitle, guidedTourHotSpotDescription.

Dos & Don’ts

Accessibility

• deterministically identify the active step for assistive technologies using currentStateField.
• ensure status is not color-only by pairing visual status with short text lines configured in informationConfigs (driven by statusRules).
• where onboarding is necessary, use localized hotspot copy to guide users (enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription).
• keep titles and subtitles short and descriptive for clear announcements (titleField, states[].titleTranslations, states[].subtitleTranslations).
• avoid rapid status changes by using unambiguous predicates and explicit priority in statusRules.
• localize supplemental information for clarity across locales (informationConfigs[].text).