fix(astro:transitions): add missing docs for available public APIs

[ArmandPhilippot]

Description (required)

• Updates astro:transitions reference to:

  • Fix <Since /> in <ClientRouter /> (added in v5, Rename the ViewTransitions component to ClientRouter astro#11980)
  • Fix the transitionEnabledOnThisPage type
  • Fix types in "Lifecycle events attributes":
    • info is typed as any and this matches what we describe ("arbitrary data").
    • direction is typed as string (because string is wider than Direction) and using Direction was a bit confusing given the description ("anything else").
  • Add Type:/<Since /> for "Lifecycle events"
  • Add fallback as available prop for <ClientRouter /> (hidden in the ToC)
  • Add default return value for getFallback()
  • Add missing docs for public APIs added in New events for Astro's view transition API astro#9090:
    • createAnimationScope,
    • isTransitionBeforePreparationEvent,
    • isTransitionBeforeSwapEvent,
    • TRANSITION_BEFORE_PREPARATION,
    • TRANSITION_AFTER_PREPARATION,
    • TRANSITION_BEFORE_SWAP,
    • TRANSITION_AFTER_SWAP,
    • TRANSITION_PAGE_LOAD,
    • type NavigationTypeString,
    • type TransitionBeforePreparationEvent,
    • type TransitionBeforeSwapEvent
  • Add docs for type Direction and type Fallback added in API for clientside router astro#8571
  • Add some <ReadMore /> around existing content
  • Specify when the lifecycle event attributes are available (for users not coming from the event itself, this can be confusing without that)
  • Slightly reword some existing content

• Updates "View Transitions" guide to:

  • Add some links to the reference
  • Replace navigate() options with a link (we already document them, the same way, in the reference)
  • Replace the history options link

Not documented

• ClientRouterModule, TransitionModule from astro:transitions: although importable those are internal types
• EventModule, TransitionRouterModule, TransitionSwapFunctionModule from astro:transitions/client: although importable those are internal types
• type Options: I think it makes more sense to details the properties under navigate() so I wasn't sure how to document the type. I left it in the available imports from astro:transitions/client though.
• The TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types (currently partially displayed in the guide) because they are exported from astro, not astro:transitions.

Related issues & labels (optional)

• Suggested label: add new content, improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	adb4db1
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/691dc9380ea1400008f4d3da
😎 Deploy Preview	https://deploy-preview-12734--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/view-transitions.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-transitions.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

This whole section and the code snippet might need a review from someone used to view transitions (and Astro's implementation). This is my understanding but maybe I'm wrong here. 😅
Also, the code snippet is a bit heavy, but if I understand correctly, we need all of this to have a working example?

[ArmandPhilippot]

This is probably for Sarah: I struggled a bit to describe the constants (this one and the followings). I'm not sure this is the best description, but I think those are useful to document.

[ArmandPhilippot]

Is it true ("some other listener might have set")? I'm not familiar enough with view transitions but from my understanding, this can only be defined inside an astro:before-preparation event so the current description might be confusing?

I reused the wording we had, and added a sentence below to clarify that, although common to both, this attribute does not have the same purpose depending on the event.

[ArmandPhilippot]

I wasn't sure if this should be plain text or part of the API block, but I think this is helpful to add this information for someone getting there from a direct link, an AI, etc.

[ArmandPhilippot]

Anyone is welcome to review this PR, but I'll ping @matthewp and @martrapp because they know better the view transitions API. If one of you two has the time to check the accuracy of the new sections this would be helpful! No rush!

Context: Some imports weren't documented, at least in the reference page. I added docs for them and fixed some types/since while I was there. The details is available in the first post. You're free to check the whole PR, but your help is especially useful for createAnimationScope() and the direction attribute (see my review comment for why I need you here).

Also, is there a reason for the TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types to be exported from astro instead of astro:transitions?
Not a real issue, I ask the question because it would have been convenient to have them in the same place so that they could be documented on the reference page, and avoid displaying them as a code snippet in the guide.

[martrapp]

Hi @ArmandPhilippot 👋🏼 thank you for taking care and fixing!

I'm afraid, some of these are long forgotten youthful mistakes and which we should mark them as deprecated:

• TRANSITION_AFTER_PREPARATION, TRANSITION_AFTER_SWAP, TRANSITION_BEFORE_PREPARATION, TRANSITION_BEFORE_SWAP, TRANSITION_PAGE_LOAD.
  When I introduced them, Matthew told me that Astro does typically not provide constants like this, but I missed the chance to take them out again.
• isTransitionBeforePreparationEvent, isTransitionBeforeSwapEvent: I found those narrowing function useful for Typescript. That was before I learned from Erika, how this is done right (types/public/view-transitions.ts)

[ArmandPhilippot]

Thanks for the feedback, Martin! Well, even if we end up not documenting them because we prefer to deprecate them, this allows us to identify what we should clean up in a future version! The same thing happened with astro:actions: withastro/astro#14608 😄

[martrapp]

Also, is there a reason for the TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types to be exported from astro instead of astro:transitions?

Good question, that never really stood out to me. @matthewp?

Direction:

Yes, you are right, this can only be changed in a listener for astro:before-preparation.

Details: For links and form submission, direction is automatically set to forward. History traversals set this to forward or back. The value is available in the TransitionBeforePreparationEvent and can be changed using a listener to astro:before-preparation. The value is used to control the animation direction right before astro:before-swap is dispatched. Listeners to astro:before-swap can still read the value, but in that event, it is write protected.

While normal navigation is forward and back, this limits you to two types of animation on navigation. So, yes, an idea was to support more than those two and hence allowing direction to have arbitrary values. We never pushed that much and integration with Astro scopes and the generated styles is very low-level.

Your createAnimationScope example looks good, but I'll need more time to review ;-)

[florian-lefebvre]

Armand feel free to create a new issue on the main repo and assign it to the v6 milestone once you know what we should deprecated/remove!