Versions Compared

Old Version 3

changes.mady.by.user GE-DevDoc-Bot

Saved on

compared with

New Version Current

changes.mady.by.user GE-DevDoc-Bot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Progress Bar

(in development)

...

[!WARNING] This component might still be in development. Please use with caution.

Overview

  • The Dynamic Progress Bar component shows progress toward completing a task or process.
  • It displays a horizontal bar that fills from left to right as progress increases.
  • It supports customizable colors, thresholds, and state indicators.
  • This component is useful for showing task completion, loading states, or any measurable percentage.

...

  • id – Specifies a unique identifier for the component used for programmatic access. For example, "fileUploadProgressBar" enables targeted manipulation of this specific progress bar.
  • dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "file-upload-progress" allows test scripts to reliably locate this component.
  • enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, this progress bar can be highlighted during guided tours of the application.
  • guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Progress Indicator", "de-DE": "Fortschrittsanzeige"} provides localized titles for the hotspot.
  • guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "This bar shows your current progress", "de-DE": "Dieser Balken zeigt Ihren aktuellen Fortschritt"} provides localized descriptions.
  • Figma: tba
  • Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/other-components/progress-bar

Guidelines

Technical Documentation for Backend Developers

...

  • adjust only the outer spacing with paddingClass; no component height/width tokens are exposed.
  • set displayName to help authors identify the instance in the structure panel.

States & Feedback

  • normal: set the current percentage with updateProgress(n).
  • error: call setInvalid(errorMessage) to show a failure message; recover with setValid() and then resume updateProgress(...).

Data-Driven / Conditional Behavior

  • clamp values so updateProgress(n) only receives numbers between 0 and 100.
  • when upstream logic signals a failure, trigger setInvalid(errorMessage); on recovery, call setValid() and continue with updateProgress.

Visibility & Authorization

  • hide the component for ineligible users with visibilityPolicySetId.

Content & Localization

  • localize user-facing copy with titleTranslations for the header and errorMessage for failures.
  • if used in guided tours, localize guidedTourHotSpotTitle and guidedTourHotSpotDescription; enable with enableAsHotspot.

Dos & Don’ts

initialize to a known value on mount using ON_INIT then updateProgress(0 or cached.events.ON_INIT, updateProgress
DoDon’tArticle setting(s)
)
leave the bar at an arbitrary default that doesn’t match real progress.
update with values strictly within 0–100.pass values outside the allowed range or non-numbers.updateProgress
show an actionable failure message when progress cannot continue.indicate failure only by color or by stopping updates with no explanation.setInvalid, errorMessage
clear the error state when resolved, then resume updates.keep the bar in error after the issue is fixed.setValid, updateProgress
add outer spacing to suit context.force spacing with external CSS overrides.paddingClass
localize all user-facing copy (title, error, hotspot text).ship English-only text.titleTranslations, errorMessage, guidedTourHotSpotTitle, guidedTourHotSpotDescription
hide for ineligible users.show sensitive progress to users who shouldn’t see it.visibilityPolicySetIdprovide stable hooks for automation and monitoring.target the bar by brittle selectors.id, dataTestId
annotate the component for tours when teaching the UI.rely on ad-hoc callouts elsewhere to explain it.enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription
clean up listeners/timers on teardown.leave background work running after navigation.events.ON_DESTROY

Accessibility

  • provide localized context for what the bar represents using titleTranslations. Keep it concise and specific so announcements are understandable.
  • convey failures with text via setInvalid(errorMessage); clear with setValid().
    • write errorMessage text that states the issue and, if relevant, the next action.
  • expose stable hooks for testing and audits using dataTestId and id.
  • prevent disclosure of restricted information by gating visibility with visibilityPolicySetId.
  • localize guided-tour copy when hotspots are enabled using guidedTourHotSpotTitle and guidedTourHotSpotDescription.
  • moderate announcement frequency by batching calls to updateProgress to avoid rapid changes that can overwhelm users and assistive tech.