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

Calendar

Figma link: tba

Overview

• The Dynamic Calendar component lets users view, select, and interact with dates or date ranges.
• It supports different visualization modes for navigating days, months, and years.
• It can display indicators on specific dates to reflect events or important information.
• It is useful for showing events, appointments, and important dates in applications.

Specs

Tokens

Structure

• The calendar determines which month or period is shown first when it loads, ensuring users start with a relevant view.
• It defines how users can interact with dates, whether by selecting a single day or a range of days.
• The component manages zoom levels, allowing navigation between detailed daily views, monthly overviews, or broader yearly perspectives.

(Configured in General Properties)

• displayName - Sets the display name of the component shown in the structure panel. For example, "Meeting Calendar" allows for easy identification of the calendar's purpose in the component structure.

(Configured in Visual Properties)

• selectionMode — Sets how users can interact with the calendar with options "date" (select a single date) or "timeframe" (select a range of dates). For instance, using "timeframe" mode allows users to select vacation periods or reporting periods spanning multiple days.

(Configured in Visibility)

• displayConditions — Defines conditions for displaying the component. Allows the calendar to be shown or hidden based on dynamic conditions like user role or application state.

Styling

(Configured in Visual Properties)

• viewDate — Determines which month is initially displayed when the calendar loads. Options include currentMonth, previousMonth, or nextMonth.
• minZoomMode — Sets the minimum zoom level (most detailed view) users can navigate to.
• maxZoomMode — Sets the maximum zoom level (least detailed view) users can navigate to.

Actions & Variants

Actions

(Configured in Events)

• events — Configures the events that the component can trigger and respond to.
• ON_CALENDAR_DATETIME_CHANGE — Triggered when a user selects a date or date range. Provides the selected date (in date mode) or from/to dates (in timeframe mode) in the event payload.
• ON_INIT — Triggered when the component is initialized. Can be used to perform setup operations.
• ON_DESTROY — Triggered when the component is removed from the DOM. Useful for cleanup operations.

Datasource

(Configured in Datasource)

• fetchEntityCollectionDataSourceId — Specifies the data source ID for retrieving calendar indicator data. Example: api/calendar-events connects to an endpoint that provides date indicators.
• getEntityCollectionHttpRequestParametersMap — Configures HTTP parameters for fetching calendar indicator data. Maps additional request parameters for dynamic filtering based on context.

Authorization

(Configured in Authorization)

• visibilityPolicySetId — Determines the visibility of the component based on specified policy sets. For example, setting to adminOnlyPolicy restricts the calendar to users with admin privileges.

Tests

(Configured in Testing Hooks)

• id — Unique identifier for programmatic access. Example: mainCalendar.
• dataTestId — Testing hook ID for automated tests. Example: date-selector-calendar.
• enableAsHotspot — Enables the calendar as a guided tour hotspot.
• guidedTourHotSpotTitle — Localized title for the hotspot.
• guidedTourHotSpotDescription — Localized description for the hotspot.

(Configured in Visual Properties)

• useMockData — Determines whether sample indicator data is used for demonstration. When enabled, predefined color indicators appear without a real data source (useful for demos and automated tests).

Guidelines

Usage

• Use when users need to pick one date or a contiguous date range. Choose the interaction via selectionMode: "date" (single) or "timeframe" (range).
• Start users in the relevant period with viewDate and constrain navigation with minZoomMode / maxZoomMode.
• Expose stable hooks for tests and analytics via id and dataTestId.

Interactions & Events

• React to user selection by handling ON_CALENDAR_DATETIME_CHANGE to update related UI or trigger logic.

Visibility & Authorization

• Show or hide the calendar based on runtime context using displayConditions.
• Gate access with visibilityPolicySetId when role-based visibility is needed.

Dos & Don’ts

Accessibility

Protocol of implemented accessibility measures

• Provide concise, localized helper text via guidedTourHotSpotTitle / guidedTourHotSpotDescription when enableAsHotspot is used.
• Reduce cognitive load by starting in-context with viewDate and keeping navigation bounded with minZoomMode / maxZoomMode.
• Ensure deterministic automation and auditability with dataTestId and id.
• Avoid color-only meaning by pairing indicator visuals with reactions to ON_CALENDAR_DATETIME_CHANGE (e.g., updating nearby text).
• Use displayConditions to prevent rendering when irrelevant, reducing tab stops and screen-reader noise.