Add Calendar view for Dag #54252

RoyLee1224 · 2025-08-08T00:00:05Z

Related issues, discussions and PRs

closes: #54138
related issue: #52008
discussions: #50907
backend: #52748

Changes

New "Calendar" Tab is added to the Dag page
Dual Granularity View: Daily & Hourly View
Tooltips: Hovering over a cell displays a tooltip with the specific date/time and the runs info.
Success Rate Spectrum: A color-coded legend explains the success rate.
Adjusted success.400 and success.500 in the theme for better readability. I've confirmed this change won't affect other parts of the UI. The lime green we see in the current UI is using running.600.

Discussions and suggestions on the UI design are highly welcome.

To-Do

Enhance Cell Coloring by State: Update the getColor logic to reflect the final run states (e.g., success -> green, failed -> red, mixed -> yellow, planned -> brown).
Improve Tooltip Performance: Implement debounce for the tooltip similar to GridTI.tsx to prevent performance issues.
Make legend responsive and vertical in hourly view.
Abbreviate weekday names to a single letter(Mo -> M) for smaller cell sizes (< 18px).
Replace all hardcoded colors with theme tokens to enable dark mode support.

Screenshots

calendar_v2.mp4

Hourly View

Daily View

^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named {pr_number}.significant.rst or {issue_number}.significant.rst, in airflow-core/newsfragments.

feat(ui): Add Github style grid for Calendar tab fix(ui): Fix time format for importing dag runs to calendar

Lee-W

Translation-wise, it looks good to me. would appreciate on a second pair of eyes

jscheffl

Looks good to me in general. Thanks for the work!
I was also fearing a bit that the view is too large but find it very cool that you added a control to adjust cell size. This is then cool to adjust to individual screen size!

Some small layout nit, can you fix this up before merge?

(1) In some zoom levels the days are wrapped on the hourly view:

(2) Colors need some adjustment for dark mode... the colors especially on days w/o execution look a bit strange. Also the legend font colors are probably too dark gray for readability.

airflow-core/src/airflow/ui/public/i18n/locales/zh-TW/dag.json

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/Calendar.tsx

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/constants.ts

…itioning

…play

…B colors

RoyLee1224 · 2025-08-11T00:48:02Z

Update

calendar_v3.mp4

Hi all, I've pushed the following updates based on the review:

Layout:

Made legend responsive and vertical in hourly view.
Abbreviated weekday names to a single letter(Mo -> M) for smaller cell sizes (< 18px).

Theming:

Replaced all hardcoded colors with theme tokens to enable dark mode support.
Adjusted success.400 and success.500 in the theme for better readability. I've confirmed this change won't affect other parts of the UI. The lime green we see in the current UI is using running.600.

The theme change:

Before	After

RoyLee1224 · 2025-08-16T05:22:02Z

Here's a demo video of filter & show total

filter_showtotal.mp4

jscheffl · 2025-08-16T10:08:23Z

Here's a demo video of filter & show total

Very cool!

ashb · 2025-08-17T16:59:39Z

@RoyLee1224 You've missed one crucial use case: Seeing when the Dag will run. Not so useful with a daily or hourly scheduler, but crucial for more complex scheduling patterns, and was the original reason Calendar view was added to Airflow 2's UI

ashb · 2025-08-17T17:00:53Z

Here's a demo video of filter & show total
filter_showtotal.mp4

Nice.

What do the "Daily" and "Hourly" buttons do? How does a dag behave if it runs once a day? What about when it's 4 times a day?

bbovenzi

I appreciate the filters you added but I think those are not the ones we need. I feel like we're trying to make this calendar heatmap do too much at once

I would still like to remove:

showing the count in the cell
changing the cell size

What we do need:

Let's just have a toggle between total count and failure count with a tooltip that always gives you the full breakdown. Both should be sequential colors just like the github commit history heatmap is only shades of green. Plus "planned" as a distinctly different color to be colorblind friendly.
We can then simplify the legend and have it take up less screen space
(Future PR) Clicking on a cell should link to a list of dagruns filtered to that date range and with state=failed if we were only showing the failed count. Or link directly to the dagrun if the count for that period is 1

airflow-core/src/airflow/ui/src/router.tsx

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/Calendar.tsx

bbovenzi · 2025-08-19T22:47:35Z

(Future PR) We probably want to add better bar charts to the overview page too so that this calendar view is not trying to do too much.

…h theme settings

RoyLee1224 · 2025-08-22T17:06:19Z

@bbovenzi Sure, sounds good! Those filters were just my experiment on a different branch, and I agree that simplifying is the right way to go.

I've updated the PR with the changes you suggested:

remove cellsize changing function
GitHub-style heatmap with buttons toggle between total count and failure count
default to hourly

The current static thresholds for TOTAL_COLOR_INTENSITIES and FAILURE_COLOR_INTENSITIES might not scale well.
Maybe we should:

Use different intensity scales for the daily vs. hourly views.
Longer-term, the scale could be dynamic based on the Dag's own run history.

Please let me know what you think!

calendar_v4.mp4

jscheffl

For me this is looking very good (still) - LGTM so that we get this in 3.1!

(mini nit: The yearly view is a bit large, needs almost FHD screen to see the panel w/o scrolling. Might it make sense to make cell sizing a nit smaller? Non blocking though!)

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/CalendarLegend.tsx

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/Calendar.tsx

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/DailyCalendarView.tsx

…els to single letters

RoyLee1224 · 2025-08-22T22:00:44Z

With 14px cell size, the 10px font (2xs) is a bit tight. Here are the options:

Reduce the font size to 9px.
Use single-letter abbreviations for the days (M, T, W) while keeping the 10px font.

For now, I've implemented Option B in the latest commit, but I'm happy to change it depending on your preference. Let me know what you think!

Option	Preview
Before
Option A: Reduce Font Size
Option B: Single-Letter Days

jscheffl · 2025-08-22T22:02:32Z

With 14px cell size, the 10px font (2xs) is a bit tight. Here are the options:

For me both is OK

RoyLee1224 · 2025-08-22T22:19:40Z

Third, I think we can always get away with less white space between each cell too which should help with the size of the calendars

Here’s a quick comparison between the original gap=1 and smallergap=0.5:

gap 1	gap 0.5

For now, I'm using gap=0.5.

bbovenzi

LGTM

Great work and thanks for being so patient with so many comments. I think people will really enjoy this!

bbovenzi · 2025-08-25T15:53:35Z

Oh and #protm

jason810496 · 2025-08-25T17:59:56Z

Great work! #protm as well

* feat(ui): WIP - Add initial scaffold for DAG Calendar view feat(ui): Add Github style grid for Calendar tab fix(ui): Fix time format for importing dag runs to calendar * feat(ui): enhance Dag Calendar with hourly/daily view * feat(ui): Implement state and Success Rate Spectrum for calendar view * feat(ui): implement debounced tooltip for calendar grid * feat(ui): enhance calendar view UX with improved loading and button * feat(ui): modify Success Rate Spectrum layout in hourly calender view * perf(ui): optimize calendar data processing * feat(ui): refactor calendar legend layout and improve hourly view positioning * feat(ui): improve calendar cellSize controls and hourly view text display * feat(ui): enhance calendar dark mode support and replace hardcoded RGB colors * refactor(ui): optimize calendar date state management * refactor(ui): Extract calendar tooltip logic into useDelayedTooltip hook * refactor(ui): reduce duplication in CalendarLegend * style(ui): improve calendar UI consistency and accessibility * fix(i18n): modify translations * fix(ui): remove cellsize changing function * feat(ui): GitHub-style heatmap, default to hourly. * fix(ui): Rename calendar colorMode to viewMode to avoid confusion with theme settings * style(calendar): reduce cell size to 14x14px and simplify weekday labels to single letters * refactor(ui): consolidate calendar cells * style(ui): modify calendar cell gap and legend size

RoyLee1224 added 2 commits August 8, 2025 07:52

feat(ui): WIP - Add initial scaffold for DAG Calendar view

fcec159

feat(ui): Add Github style grid for Calendar tab fix(ui): Fix time format for importing dag runs to calendar

feat(ui): enhance Dag Calendar with hourly/daily view

c7e47fe

RoyLee1224 requested review from bbovenzi, jscheffl, pierrejeambrun, ryanahamilton and shubhamraj-git as code owners August 8, 2025 00:00

boring-cyborg bot added area:translations area:UI Related to UI/UX. For Frontend Developers. translation:default labels Aug 8, 2025

RoyLee1224 marked this pull request as draft August 8, 2025 00:00

RoyLee1224 and others added 5 commits August 9, 2025 00:52

feat(ui): Implement state and Success Rate Spectrum for calendar view

11e7a96

feat(ui): implement debounced tooltip for calendar grid

00f89f2

feat(ui): enhance calendar view UX with improved loading and button

ae98bd6

feat(ui): modify Success Rate Spectrum layout in hourly calender view

839555d

Merge branch 'main' into calendar

85de630

RoyLee1224 marked this pull request as ready for review August 8, 2025 22:45

RoyLee1224 requested review from Lee-W and jason810496 as code owners August 8, 2025 22:45

RoyLee1224 changed the title ~~[WIP] Add Calendar view for Dag~~ Add Calendar view for Dag Aug 9, 2025

Lee-W reviewed Aug 9, 2025

View reviewed changes

perf(ui): optimize calendar data processing

da3ad99

jscheffl reviewed Aug 9, 2025

View reviewed changes

RoyLee1224 added 6 commits August 11, 2025 04:56

feat(ui): refactor calendar legend layout and improve hourly view pos…

504fd7f

…itioning

feat(ui): improve calendar cellSize controls and hourly view text dis…

2026034

…play

feat(ui): enhance calendar dark mode support and replace hardcoded RG…

9be6f57

…B colors

refactor(ui): optimize calendar date state management

5037b3c

refactor(ui): Extract calendar tooltip logic into useDelayedTooltip hook

f731aee

refactor(ui): reduce duplication in CalendarLegend

5a3a187

fix(i18n): modify translations

9a59262

bbovenzi reviewed Aug 19, 2025

View reviewed changes

airflow-core/src/airflow/ui/src/router.tsx Show resolved Hide resolved

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/Calendar.tsx Outdated Show resolved Hide resolved

RoyLee1224 added 3 commits August 22, 2025 11:30

fix(ui): remove cellsize changing function

cea2950

feat(ui): GitHub-style heatmap, default to hourly.

a509f43

fix(ui): Rename calendar colorMode to viewMode to avoid confusion wit…

66f64b2

…h theme settings

jscheffl approved these changes Aug 22, 2025

View reviewed changes

bbovenzi reviewed Aug 22, 2025

View reviewed changes

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/CalendarLegend.tsx Show resolved Hide resolved

bbovenzi reviewed Aug 22, 2025

View reviewed changes

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/Calendar.tsx Outdated Show resolved Hide resolved

bbovenzi reviewed Aug 22, 2025

View reviewed changes

airflow-core/src/airflow/ui/src/pages/Dag/Calendar/DailyCalendarView.tsx Outdated Show resolved Hide resolved

RoyLee1224 added 2 commits August 22, 2025 17:08

style(calendar): reduce cell size to 14x14px and simplify weekday lab…

7effbf1

…els to single letters

refactor(ui): consolidate calendar cells

f65a75b

style(ui): modify calendar cell gap and legend size

d2b1718

bbovenzi approved these changes Aug 25, 2025

View reviewed changes

bbovenzi added this to the Airflow 3.1.0 milestone Aug 25, 2025

bbovenzi merged commit 9a30311 into apache:main Aug 25, 2025
56 checks passed

bbovenzi mentioned this pull request Aug 26, 2025

Calendar view: remove hardcoded data range #54951

Closed

2 tasks

RoyLee1224 deleted the calendar branch September 10, 2025 14:46

Add Calendar view for Dag #54252

Add Calendar view for Dag #54252

Uh oh!

Conversation

RoyLee1224 commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues, discussions and PRs

Changes

To-Do

Screenshots

Hourly View

Daily View

Uh oh!

Lee-W left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jscheffl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RoyLee1224 commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Update

Layout:

Theming:

Uh oh!

RoyLee1224 commented Aug 16, 2025

Uh oh!

jscheffl commented Aug 16, 2025

Uh oh!

ashb commented Aug 17, 2025

Uh oh!

ashb commented Aug 17, 2025

Uh oh!

bbovenzi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bbovenzi commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RoyLee1224 commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jscheffl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RoyLee1224 commented Aug 22, 2025

Uh oh!

jscheffl commented Aug 22, 2025

Uh oh!

RoyLee1224 commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bbovenzi left a comment

Choose a reason for hiding this comment

Uh oh!

bbovenzi commented Aug 25, 2025

Uh oh!

Uh oh!

jason810496 commented Aug 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

RoyLee1224 commented Aug 8, 2025 •

edited

Loading

Lee-W left a comment •

edited

Loading

RoyLee1224 commented Aug 11, 2025 •

edited

Loading

bbovenzi commented Aug 19, 2025 •

edited

Loading

RoyLee1224 commented Aug 22, 2025 •

edited

Loading

RoyLee1224 commented Aug 22, 2025 •

edited

Loading