property in anchor element forces a reload of the target

[martrapp]

Changes

In an anchor element, the data-astro-reload property (with no value or with a value other than 'false') forces a reload of the target document (instead of a view transition).

Closes #7947

Testing

manually tested on the example given in #7947, outcome documented there.
[update 2023-08-22]: added e2e test

Docs

The documentation of the (still experimental) View Transitions needs to be updated.

Not sure if the data property will be the final interface for users or if there will be syntactic sugar (e.g. transition:reload).
I plan to add one or more properties in the next few days to address other issues, in particular a property to control cross-page scrolling behavior (as opposed to on-page scrolling behavior)

/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: 52606a3

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[matthewp]

Want to bikeshed on the name a little bit. astro-reload sounds a little off to me because we're not reloading the page; the page has never been loaded in the first place. But if this is a common name other similar implementations use then I think it's ok.

Just did a check:

• swup - data-no-swup: https://swup.js.org/api/markup/#ignore-links
• Turbo - data-turbo="false": https://turbo.hotwired.dev/reference/attributes#data-attributes
• Phoenix - Opt-in via link component: https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#link/1

Could not find other examples.

[martrapp]

force-load?
mpa-load?
…

[ematipico]

Maybe astro-load or astro-server-load? Or astro-force-load like suggested. "mpa" uses an acronym that is not well known.

[matthewp]

cc @delucis and @bluwy our naming experts.

[delucis]

Given our current directives related to this are all transition:*, I’d imagine something like transition:none would make most sense here?

Although… would clicking a link with this property override any transition:persist and blow away that DOM? If so, that makes the transition:* namespace a much less good fit.

Do we have a description of use cases somewhere? Those might help with naming.

[matthewp]

@delucis This just means you want to opt-out of client-side routing for a particular link. One use-case is that the link goes to a file rather than another page, for ex. <a href="/chart.pdf">Chart</a>.

Note that directives are used for server-side processing in some way; transition:animate creates a stylesheet. There's no server-side stuff happening in this one. The attribute will remain in the output HTML. Doesn't mean we can't use a directive like name, but something to consider.

[bluwy]

SvelteKit uses data-sveltekit-reload so there's an initial pattern. Though I'd say it's confusing at times too, it's not really a reload, but letting the browser do its thing instead. Maybe data-astro-no-load, data-astro-skip-route, data-astro-skip-navigate, data-astro-skip, data-astro-ignore? I'm not really sure what's the best name here 😄

Could also think ahead how this plays if we want to make prefetch first-class in the future

[delucis]

Yeah, if we’re reasonably happy with how astrojs/prefetch works currently, that could maybe help us pick a name that works well with those? Although that’s opt-in at the moment via rel="prefetch" and rel="prefetch-intent", so perhaps doesn’t help.

[matthewp]

What about data-astro-no-transition? Keep it specific to what happens otherwise?

[matthewp]

I think I'm coming around to just using data-astro-reload to keep it consistent with svelte. I don't love it, but don't love the alternatives.

[martrapp]

There are only two hard things in Computer Science: cache invalidation and naming things.

My 2ct

I won’t use “transition” because technically it is not mainly about visual transition but whether or not the document is updated with new content (swap) or replaced by a new document. There could also be swap without transition.

link would sound good to me but none of the defined values (https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel) seem to fit our purpose

another try:
data-astro-fresh-document
data-astro-browser-default-navigation
data-astro-browser-default
data-astro-browser-navigation
sata-astro-default-navigation

These would also express that we leave it to to browser to choose viewers based on content-type

[matthewp]

is there a reason why someone would use a false value here? If not I think we can just check for its existence to save a few bytes.

[martrapp]

For me it looks odd if someone writes: reload="false" and gets a reload.
But at the end it is a matter of documentation: "Any value assigned to this attribute is ignored."
10 Bytes saved :-) !

[matthewp]

I think given the lack of great options we should just stick with data-astro-reload and think about it more later.

[matthewp]

I'm changing the base of this to next as we are not going to do another minor release of 2.x, so this will go out with 3.0.

I'm going to document this as part of withastro/docs#4320

[matthewp]

@martrapp would you mind resolving this conflict? I would do it but it's part of the code that you most recently updated. Once that's done this is ready to be merged. Thanks!