Document swapFunctions of astro:transitions/client

[martrapp]

Description (required)

In 4.8.0 10908 we introduced building blocks for custom swap() functions. Up to now we didn't properly document and export them. We first wanted to see if they worked. They did.

This PR is intended to discuss and close this technical debt.

For Astro version: 4.15.0. See astro PR 11708.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	1420df9
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/66ccfbec781c900008b9e8c0
😎 Deploy Preview	https://deploy-preview-9084--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 site 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

Locale	File	Note
en	guides/view-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.

[sarah11918]

I'm wondering whether we should have a nice API entry for swapFunctions here: https://docs.astro.build/en/reference/api-reference/#viewtransitions- ?

Since it's something we import from astro:transitions, it feels like there should be a reference item for it?

[martrapp]

I'm wondering whether we should have ...

Yes, definitively. It could be part of #7961! But i would not add it to the API section before the events. You use the custom swap functions to redefine the swap function of the event object.

[sarah11918]

OK, so I am now really feeling the lack of a section in API reference for astro:transitions 😄 But for now, for this addition, I think we can do this, then separately let's get a new section in the API reference page and we'll come back here and link to a proper full reference of all these things!

[martrapp]

Thank you very much for your help Sarah! There is a reason why Astro Docs have such a good reputation 💜

[sarah11918]

Thanks for the helpful polish on this, @martrapp ! Approving for docs! (Wait, this is docs...)

[sarah11918]

Suggested change

	ev.swap = () => mySwap(ev.newDocument);
	event.swap = () => mySwap(event.newDocument);

Last tiny tiny thing: assuming that ev stands for event, we generally prefer to write these words out in full as they can help people who aren't used to standard abbreviations. This would be my preference, if correct!

[martrapp]

Good one! I had used ev for consistency with the rest of the page. Now everything is consistent again ;-)

[yanthomasdev]

LGTM @martrapp, good work! 💜