feat: add navLayout prop

[gpbl]

This PR introduces the new navLayout prop, which fixes #2629 and provides a new layout option for navigation:

• around: Navigation buttons are displayed on either side of the caption.
• after: Navigation buttons are displayed after the caption

This change also accounts for cases where the number of months displayed is greater than one.

Known Issues

• During transitions, the navigation buttons appear duplicated. This issue can likely be resolved by modifying the useAnimation hook.

Screen.Recording.2025-05-04.at.8.14.09.AM.mov

Notes on Reusing the Nav Component

I considered adding skipNextButton or skipPrevButton props to the Nav component to reuse it. However, I am not sure if as having multiple <nav> elements with the same label is correct. Reusing Nav would potentially result in a breaking change.

[gpbl]

@rodgobbi still refining the change, wanted to share with you this proof-of-concept - what do you think?

[rodgobbi]

@gpbl

Lemme fix the animation issues, I'll push changes to your branch.

[rodgobbi]

@gpbl

The approach looks good indeed.
I understand better now, using explicit values for the prop fixes #2629.

And I imagine we could make the after value the default one in the upcoming breaking change.

My only suggestion is to try to move the new nav layout elements out of the months.map, as they don't repeat per month in the calendar, therefore conceptually they should be out of the months.map logic.
And I expect that doing so would simplify the CSS styles and perhaps fix the issue happening with the animation.

[rodgobbi]

I think we could move this out of the months.map scope, as it is absolute positioned, I expect we could mount one button before the map and another one after.
If you tried this already, lemme know if there are any issues.

This comment also applies to the after navLayout, which is mounted within the map scope.

Perhaps doing that fixes the issue that happens during the animation.

[gpbl]

Thank you, @rodgobbi, for your quick review and suggestions! Apologies for not being clear about how to test this (I use the playground in the website).

And I imagine we could make the after value the default one in the upcoming breaking change.

Yes, exactly! That is the plan.

I think we could move this out of the months.map scope, as it is absolutely positioned. I expect we could mount one button before the map and another one after.
If you tried this already, let me know if there are any issues.

The reason I placed the navigation buttons inside the loop is to align them with the caption when displaying multiple months across multiple rows. I can't make assumptions about how large is that container...

Moving the buttons outside the months container makes it challenging to position them correctly without altering the element tree.

I believe the animation glitch is because these elements are not being hidden while duplicating the container during the transition (the test failure seems to confirm that). If you have some time to look at it I'd be happy to let you fix it!

[rodgobbi]

@gpbl

I see, I think I was testing the branch too soon, even before you pushed some changes required for the nav buttons to be aligned with the caption.
It makes sense to mount with the month element to align it properly.

For the after layout, I see different issues, one of which is a bug is that multiple buttons are being mounted, one for each month; we should mount only one.
The glitch also happens because of the styles manually set to the month container during the animation, which causes the relative container for the nav buttons to change from the root element to the month in the calendar.

What do you think of rendering only the after nav buttons outside the months.map? After the calendar months.
I think this would fix the glitch and the current issue of multiple buttons rendered, and it also makes more sense to be outside the map logic.

I can test this and push the changes if it works.

[gpbl]

Thanks @rodgobbi I got what you mean.

For the around layout - I could fix the animation glitch by changing useAnimation (I I'd like to give a review to these query selectors soon or later).

For the after layout, I see different issues, one of which is a bug is that multiple buttons are being mounted, one for each month; we should mount only one.

Fixed,

The glitch also happens because of the styles manually set to the month container during the animation, which causes the relative container for the nav buttons to change from the root element to the month in the calendar.

I'm not sure if I can replicate this again - I'll double check.

What do you think of rendering only the after nav buttons outside the months.map?

Also in this case, we want it right after the caption to preserve the tab behavior.

[gpbl]

I confirm the glitch with multiple months is still there:

Untitled.mov

I will give a look to it tomorrow with a fresh mind!

[rodgobbi]

@gpbl thanks for checking, lemme try to fix it later and I'll message you again with the results 👍

[rodgobbi]

@gpbl
The line that is causing the issue in the animation is this one.

I need to think more about how to work around that. It's very tricky to support the current after nav layout UX with the current animation logic.

On the flip side, the glitch happens when there are multiple months wrapping to the next line, and in the same scenario the tabbing flow is also problematic:

Screen.Recording.2025-05-06.at.18.59.50.mov

I wasn't able to reproduce the glitch happening to the first displayed month like in #2755 (comment).

What do you think of always anchoring the after nav buttons to the last displayed month?

Like the last nav button for the around layout.
This would keep the tabbing flow consistent following the visual order, and this glitch would not happen because the nav buttons' position during animation would be the same as the non-animating state.