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

Clock

Overview

  • The Dynamic Clock Component is a countdown timer that provides visual feedback as time progresses.
  • Users can start, stop, and monitor countdown periods.
  • The timer shows visual warnings when approaching time limits.
  • It is useful for time-sensitive operations, timing processes, or activity monitoring.

Clock Overview

Specs

Tokens

Token Description
displayName Display name of the component shown in the structure panel
countDownBarInSeconds Total duration of the countdown timer in seconds
warningRangeInPercent Percentage of elapsed time at which a visual warning is shown
events Configures the events that the component can trigger and respond to
ON_CLOCK_COUNTDOWN_START (Events) Event triggered when the countdown timer is started
ON_CLOCK_COUNTDOWN_STOP (Events) Event triggered when the countdown is manually stopped
ON_CLOCK_COUNTDOWN_WARNING_REACHED (Events) Event triggered when the timer reaches the warning threshold
ON_CLOCK_COUNTDOWN_EXCEEDED (Events) Event triggered when the countdown timer reaches zero
ON_GLOBAL_PARAMETERS_CHANGE (Events) Event triggered when global parameters affecting the component change
ON_INIT (Events) Event triggered when the component is initialized
ON_DESTROY (Events) Event triggered when the component is removed from the DOM
enableAsHotspot Enables the clock as a guided tour hotspot
guidedTourHotSpotTitle Title text for the guided tour hotspot with multilingual support
guidedTourHotSpotDescription Description text for the guided tour hotspot with multilingual support

Structure

  • The Clock component displays a countdown timer with a visual progress indicator.
  • The timer tracks elapsed time until reaching zero.
  • A warning state appears when the configured threshold is reached.

Structure of clock visually explained

(Configured in General Properties)

  • displayName: Sets the display name of the component shown in the structure panel. For example, "Operation Timer" allows easy identification of the clock’s purpose.

Styling

(Configured in Visual Properties)

  • countDownBarInSeconds: Defines the total countdown duration in seconds. For example, 300 creates a five-minute timer with visual progress.
  • warningRangeInPercent: Sets the percentage threshold at which the timer shows a warning. For example, 80 means the timer warns when 80% of the time has elapsed.

Visual Properties tab for countdown settings

Actions & Variants

(Configured in Events)

  • events: Configures the events that the component can trigger and respond to.
  • ON_CLOCK_COUNTDOWN_START: Triggered when the countdown timer is started. Can be used to synchronize other components or log the start of a process.
  • ON_CLOCK_COUNTDOWN_STOP: Triggered when the countdown is manually stopped. Useful for capturing interrupted processes or user interventions.
  • ON_CLOCK_COUNTDOWN_WARNING_REACHED: Triggered when the timer reaches the warning threshold defined by warningRangeInPercent. Can be used to display alerts or trigger preparatory actions.
  • ON_CLOCK_COUNTDOWN_EXCEEDED: Triggered when the countdown timer reaches zero. Can be used to execute follow-up actions or notify users that time has expired.
  • ON_GLOBAL_PARAMETERS_CHANGE: Triggered when global parameters affecting the component change. Allows the component to respond to system-wide settings changes.
  • ON_INIT: Triggered when the component is initialized. Can be used for setup operations.
  • ON_DESTROY: Triggered when the component is removed from the DOM. Useful for cleanup operations.

Tests

(Configured in Testing Hooks)

  • enableAsHotspot: Enables the clock component as a guided tour hotspot. When enabled, the clock can be highlighted during guided tours to draw user attention to timing features.
  • guidedTourHotSpotTitle: Sets the title for the guided tour hotspot with multilingual support. For example, {"en-US": "Monitor Operation Time", "de-DE": "Betriebszeit überwachen"}.
  • guidedTourHotSpotDescription: Sets the description for the guided tour hotspot with multilingual support. For example, {"en-US": "Click the play button to start timing your operation. The timer will warn you when time is running out.", "de-DE": "Klicken Sie auf die Wiedergabetaste, um die Zeitmessung Ihres Vorgangs zu starten. Der Timer warnt Sie, wenn die Zeit knapp wird."}.
  • Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-77301&t=iosNC2AkSTGs5lMh-1
  • Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id7/3-clock

Guidelines

Usage

  • Use the Clock to time a bounded activity by setting the total duration via countDownBarInSeconds.
  • Provide an early warning window so users can prepare before time expires by configuring warningRangeInPercent.

Interactions & Events

  • React to environment or preference changes using ON_GLOBAL_PARAMETERS_CHANGE.
  • Clean up timers, listeners, or analytics hooks when the Clock is removed via ON_DESTROY.

Dos & Don’ts

Do Don’t Article setting(s)
Start and stop the timer through explicit event wiring. Assume the timer starts automatically without control. ON_CLOCK_COUNTDOWN_START, ON_CLOCK_COUNTDOWN_STOP
Handle the zero-time boundary to close the loop on the flow. Ignore expiry and leave the state unresolved. ON_CLOCK_COUNTDOWN_EXCEEDED
Apply global changes deterministically (recalculate, then restart). Mutate duration/threshold mid-countdown without rules. ON_GLOBAL_PARAMETERS_CHANGE, countDownBarInSeconds, ON_CLOCK_COUNTDOWN_START
Provide localized hotspot text when using guided help. Enable the hotspot with placeholder or untranslated strings. enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription
Remove timers/listeners when the Clock is removed. Leave background processes running after teardown. ON_DESTROY

Accessibility

  • Do not rely on color alone to communicate the warning state; pair the visual change with ON_CLOCK_COUNTDOWN_WARNING_REACHED so downstream cues (e.g., announcements) can run for users with color-vision deficiencies.
  • Provide adequate time to perceive changes: set warningRangeInPercent early enough to give users a meaningful buffer before expiry, acknowledging low-vision scenarios where perceivability can be reduced.
  • Keep hotspot text concise microcontent and never the sole place for critical instructions; it should supplement, not replace, primary UI affordances.
  • No labels