VT event lifecycle docs

[matthewp]

Description (required)

Documents the new lifecycle events from: withastro/astro#9090

Related issues & labels (optional)

For Astro version: 3.6. See astro PR #9090.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Nov 22, 2023 2:21pm

[matthewp]

I could see the following changes made:

• Make the sections which explain the events purely about what the event does, when it occurs, etc. and not about use-cases.
• Move use-cases to a separate headings. I like this idea because it's easier to find how to achieve something vs. finding which event lists the use-case.

[martrapp]

"occurs immediately before the view transition ends" could be misleading: Surely it is near the end of the navigation, but "astro:after-swap" takes place immediately before the start of the animation (for the simulation immediately before the start of the "new" part). In any case, the loading indicator is already recorded on the screenshot and will not disappear so quickly, depending on the animation. A better place to remove it would be astro:after-preparation because the photo has not yet been taken :)

[sarah11918]

I'm hearing two different comments here:

1. "immediately before the view transition ends" isn't exactly right. What's a better, concise, way to describe it?
2. Spinner has come back to haunt us. This now is the only real example (that's not, it's still safe to do this) example for this section. Can you suggest (code sample even better, but just in words like above is fine) what a good thing to happen here is? So that this section can have a proper example of its own that makes sense and is a realistic use case? Note: it's also OK to say that "there's very little that might target this event specifically, but it does provide you..."

[sarah11918]

@matthewp @martrapp I took a pass at this, and added a bit more intro content to the section. It was really well done! I would be happy with this releasing with the new features, and as we have time adding more of Martin's use-cases listed in PR 9090... either in time for launch or otherwise.

I will call out:

• astro:after-swap was already written for docs, and was previously the only point at which state was passed, so I tried to update more like to indicate that this is the "last responsible moment" for passing along state, and instead focus on the end of the view transition. I would ask you in particular to look at this and see whether you'd describe this differently now.
• I'm not entirely sure I've nailed the difference between after-preparation and before-swap. Only one of them talked about being inside/outside of the view transition, so I made it clearer that one is before and one is inside. And I'm inferring that the difference is that before you have access to the old page only, not the new one, and inside the view transition you have access to BOTH DOMs so you can swap. I just want to make sure that that is correct and that you think that comes across. We haven't really said what "being inside the view transition" means explicitly, but I think that's the connection.

Otherwise, please read for both accuracy but also nuance! We have lots of time to get this exactly right, not just sort of right.

[matthewp]

@sarah11918 Yeah, that different makes sense. Another thing that @martrapp and I were talking about, is that the before- events are points in which you can modify what is about to happen, whereas the after- events are notifications of what just happened. I'm not sure if that's something we should mention or not.

Doing another pass myself now.

[martrapp]

As for the question of relevant examples for each event, you might want to check out the new examples at https://events-3bg.pages.dev/.

For the document we could do this:

• before-preparation + loader() replacement: (simplified) image prefetch example from the demo page
• after-preparation: existing example (loading indicator)
• before-swap: existing example (darkMode)
• before-swap + swap() replacement: existing example (diff)
• after-swap: scroll to top example from the demo page
• page-load: existing example

What do you think? @matthewp, @sarah11918

[sarah11918]

@martrapp Did you make that page?? That's lovely! I would suggest we link to it, rather than reproduce it. Many of our docs pages link to "community resources" and then it's less for our translators to translate, less of a maintenance burden on docs if things update. it also encourages community members to produce content which scales more than us doing everything ourselves. 😄

What would you think about that?

[martrapp]

What would you think about that?

That would be great! (Once the events are published and people can download and run the examples with a current Astro version)

But we can definitely borrow for the missing after-swap example :-)

[sarah11918]

@martrapp I would love it if you could add the after-swap event example here, and then I think this would be good to go!

[sarah11918]

OK! I'm happy with the content/structure of this page!

@matthewp @martrapp - happy for you to do any final review here. Otherwise, Team Docs will just handle any last minute polishing as we notice in the morning! Thank you both for your contribution for this one! An exciting feature we're happy to get into docs! 🙌

[martrapp]

Layout error due to wrong quotation marks, but otherwise I'm very happy with this section!