Portals #1032

eric-burel · 2024-09-30T07:57:17Z

eric-burel
Sep 30, 2024

Summary

In addition to slots that work on parent-children relationship, introduce a concept of portals that works from any-level of nesting.

Background & Motivation

The component hierarchy is directly tied to the DOM hierarchy which is not always the best structure for implementing a specific feature.

I am currently thinking of 2 use cases though some more might emerge during discussions:

triggering dialogs: floating elements tend to have a specific location very high in the DOM to avoid being parasited by intermediate elements positioning logic, that's typically how you implement absolutely positioned dialogs with a guarantee that the position is computed based on the viewport and not some random parent element that used a CSS filter.
feeding the section with metadata: for this use case, we might want to run further investigation to understand the impact of not having a meta tag into the <head> section. It's certainly not clean, but I suspect it does have an impact on SEO too.

For the first use case, at the moment you may use portals from your favorite client-side library, maybe this would just need some documentation to tell whether portals are supported or not.

However for proper SEO you may want the injection into the head tag to happen during server-side rendering only, it would be ideal to support this directly in Astro.

I've encountered the second use case while working on improving TutorialKit metadata.

Multiple changes were needed to make a proper connection between .mdx files and the Layout component that renders the meta tags:

supporting a new fields in the .mdx content frontmatter
crafting a YAML friendly representation of the metadata
updating all types accordingly
updating the layout component accordingly
converting back the YAML representation into HTML

And we still only support a few metadata : image, title, description. A similar work would be needed for more advanced tags like alternate links.

Goals

Bring a portal system

Example

# lesson.mdx
title: My lesson
---
<portal to="head">
  <link rel="alternate" href="/foobar.com">
<portal />

// pages/[slug].astro
// assuming you get the content from a collection
const MarkdownContent = await lesson.render()
---
<head>
  <portal name="head />
</head>
<body>
  <!-- This component will also inject an alternate URL into the head-->
  <MarkdownContent />
</body>

Related:
stackblitz/tutorialkit#342
withastro/astro#8703
https://react.dev/reference/react-dom/createPortal

Fryuni · 2024-10-01T02:37:11Z

Fryuni
Oct 1, 2024
Collaborator

This seems completely doable from userland as an integration.

Enabling it (regardless if by an integration or built into Astro) would disable streaming responses for any page containing a portal tho, since it's contents can only be known when every component renders.

4 replies

Fryuni Oct 1, 2024
Collaborator

Implemented an integration for it: Fryuni/inox-tools#167

Works with Astro components and with UI framework components (tho I still need to add the proper types for all of them, only React and Preact so far).

Once I add the types and tests I'll publish it

eric-burel Oct 1, 2024
Author

@Fryuni thanks for the reply, your code was super insightful!
My takeaways:

You are implementing the portals in user-land by working on the rendered HTML, as a post-processing step. I deplore the lack of a similar feature in Next.js, which I would call an "endware", because it unlocks so many user-land tweaks like this. It's also a possible approach for injecting polyfills depending on the user agent while keeping a page dynamic.
It works server-side as expected, Astro middlewares run at build-time only for static pages so it's also static-friendly.
A downside might be the cost, you need to parse the whole HTML content to find the portal. Ideally, this should be done against a kind of Astro AST representations earlier in the rendering process, eg when rendering a complete page.
I've learnt that portal is an existing, experimental but unused valid HTML element
You said "Astro compiler remove unknown head elements" => isn't that a strange behaviour? Or is it expected to have valid HTML?

Fryuni Oct 1, 2024
Collaborator

A downside might be the cost, you need to parse the whole HTML content to find the portal. Ideally, this should be done against a kind of Astro AST representations earlier in the rendering process

Astro doesn't have such a representation. Components render directly to HTML by turning the code into a template with interpolation. You can see it happening here. The template uses a $$render tag that returns an async iterator over each part of the template string and the interpolated values.

Another thing present in that example is that Astro adds ${$$renderHead($$result)} to the interpolation. That is where any component used can statically add elements to the head powered by the compiler. This is how <script> and <style> tags from all components in the page get added to the head. But since this happens before the components in the <body> are even called it only knows about what was discovered statically (this limitation is also why a component style will be present on the page even if you don't use it but import it, which has been reported multiple times).

It brings the performance of skipping any intermediate representation but, at the same time, limits what can be done in post-processing without parsing the HTML.

I've learnt that portal is an existing, experimental but unused valid HTML element

Yes, I also found that out. Technically, any tag without a - is reserved by the HTML spec for future use. That is why custom elements for web components must have a -.

This is not really a problem here. Astro already overrides the semantics of <slot>, <script> and <style>. You have to opt-out of the Astro semantics back into the HTML semantics by adding is:inline. The same could be done for <portal> if we wanted.

You said "Astro compiler remove unknown head elements" => isn't that a strange behaviour? Or is it expected to have valid HTML?

I think it is a bug. But it was 2 a.m., so I just figured out what was happening and not why it was happening.

It does other weird things things as well. If you have a tag that is not supposed to be on the <head> inline there it doesn't emit the <body> tag

eric-burel Oct 1, 2024
Author

Another thing present in that example is that Astro adds ${$$renderHead($$result)} to the interpolation.

Interesting, maybe we could figure a solution specific to the element, because that's a significant use case. Many framework choose to have a specific solution for metadata, eg Next.js metadata export, packages like Helmet etc.

Thanks again for your detailed technical insights

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Portals #1032

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment 4 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

Portals #1032

eric-burel Sep 30, 2024

Summary

Background & Motivation

Goals

Example

Replies: 1 comment · 4 replies

Fryuni Oct 1, 2024 Collaborator

Fryuni Oct 1, 2024 Collaborator

eric-burel Oct 1, 2024 Author

Fryuni Oct 1, 2024 Collaborator

eric-burel Oct 1, 2024 Author

eric-burel
Sep 30, 2024

Replies: 1 comment 4 replies

Fryuni
Oct 1, 2024
Collaborator

Fryuni Oct 1, 2024
Collaborator

eric-burel Oct 1, 2024
Author

Fryuni Oct 1, 2024
Collaborator

eric-burel Oct 1, 2024
Author