[Complete] RFC: DOM Interaction in Angular #56498

jelbourn · 2024-06-18T18:45:53Z

jelbourn
Jun 18, 2024
Maintainer

Background

When server-side rendering an application today, Angular uses a library called Domino to provide implementations of a subset of browser APIs such as Document and HTMLOListElement. With these emulated APIs, components that access DOCUMENT or ElementRef#nativeElement can run on the server via the same code paths as the browser. This means that Angular developers can write code that interacts directly with the DOM and, in many cases, that code successfully runs on the server. However, the approach comes with some downsides:

Limited support: As DOM emulation only implements a subset of the DOM, it works great in some cases, but falls apart in others. Standard browser features, like Shadow DOM, aren't supported, leading to issues that can be tricky to diagnose. This problem grows over time as browsers introduce new features.
Inefficient, error-prone: While manual DOM manipulation can be useful (for example, to avoid change detection errors), it prevents Angular from having full knowledge of the state of the DOM. This has two considerable consequences:
1. It prevents Angular from reliably matching up server rendered templates with elements in the DOM. This process, called hydration, is important for performance and user experience.
2. It prevents Angular from implementing other highly-requested features such as partial hydration and streaming HTML responses, as Angular is unable to know when it is safe to consider some part of the DOM complete.

Separately from the technical challenges with DOM emulation, the framework's existing API for interacting with the DOM (ElementRef) is more verbose than it needs to be. In considering how Angular developers interact with the DOM, we think there's an opportunity to make this API more ergonomic while also providing additional guard rails for building high performance apps.

We would eventually like to move Angular toward a world where DOM emulation is an optional feature that developers explicitly choose to enable, as opposed to an integral part of its design. This opt-in approach will lead to components that are compatible with more advanced SSR features (e.g. partial hydration) by default. It will additionally help make Angular less complicated and easier to reason about.. To that end, we see a lot of potential in changing how we think about and expose the DOM to Angular components.

What kind of feedback are we looking for?

While we're excited to hear any and all comments on the changes proposed below, we have a few specific discussion points that we are especially keen to hear about. In particular:

Discussion Question 1: We’re proposing moving away from DOM emulation as a well-lit path. Do you have any use-cases that strictly depend on Angular's server-side DOM emulation today?
Discussion Question 2: To help create components that always work great on the server and browser, we’re proposing limits to when and how native DOM elements can be accessed. Are these limits (and their rationale) easy to understand?
Discussion Question 3: For a more ergonomic API, we’re proposing replacing the ElementRef API with a new API named DomRef. From a developer ergonomics perspective, does DomRef seem easier to use than ElementRef? Are there any use-cases for ElementRef that are made worse by using DomRef?

When you leave a comment, be sure to note the question(s) to which you're responding. As always, keep our code of conduct in mind. We know that a proposal of this scope significantly impacts Angular and the way you use it in your projects. We appreciate your commitment and investment in this project and ask to keep comments respectful.

`DomRef` API

A DomRef is a wrapper around a DOM element. There are a few differences compared to ElementRef. First, DomRef has a more streamlined API: the value can be unwrapped simply by calling it:

const myInputRef: DomRef<HTMLInputElement> = /* ... */;
/* ... */
const myInput: HTMLInputElement = myInputRef();

Second, DomRef is contextual. To help prevent accidentally creating components that cannot be server-side rendered, a DomRef will throw if you attempt to unwrap it before the next afterRender or afterNextRender:

@Component({ /* ... */ })
export class SimpleComponent {
  myInputRef = inject(DomRef<HTMLInputElement>);
  injector = inject(Injector);

  constructor() {
    const myInput = this.myInputRef(); // ❌ This always throws!

    afterNextRender(() => {
      const myInput = this.myInputRef(); // ✅ This is always safe!
    });
  }

  onClick() {
    // If the event originates from a real user action, this is safe ✅
    // If the event was triggered programmatically during page load, this might throw ⚠️
    const myInput = this.myInputRef();

    afterNextRender(() => {
      const myInput = this.myInputRef(); // ✅ This is always safe!
    }, { injector: this.injector });
  }
}

In general, we believe that the only time you should need to unwrap and access a native DOM element is on the browser, after the page has been rendered, typically in response to a user interacting with the page. The DomRef API encourages this by making it an error to unwrap it elsewhere, while still allowing the reference to be safely passed around. In other situations, you should use features like host bindings to declaratively specify the DOM state.

At the same time, ElementRef will be marked as deprecated.

`DOCUMENT_REF` Token

Today, Angular provides a DOCUMENT token that can be used to access the application Document safely, without branching, during server-side rendering or on the browser.

In a world where DOM emulation is optional, this value will need to be null, undefined, or simply not provided during server-side rendering. To bridge this gap, we want to expose DOCUMENT_REF: DomRef<Document> as a safer alternative. At the same time, DOCUMENT will be marked as deprecated.

Changes to view and content queries

Today, signal-based queries (e.g. viewChild) and detector-based queries (e.g. @ViewChild) return an ElementRef by default when no read option is configured. As ElementRef will be deprecated in favor of DomRef, a future major version will change this default to DomRef instead. A schematic will provide an automatic migration as part of ng update to avoid breaking existing code.

(this RFC is posted by @jelbourn on behalf of its author, @devknoll)

yjaaidi · 2024-06-18T21:03:36Z

yjaaidi
Jun 18, 2024

I love this! I think that this is my favorite part 😊:

a DomRef will throw if you attempt to unwrap it before the next afterRender or afterNextRender

Good job!

0 replies

yjaaidi · 2024-06-18T21:11:48Z

yjaaidi
Jun 18, 2024

About Question 1: A common use case is vanilla JS 3rd party libraries that might alter the DOM. (e.g. some code highlighters)

2 replies

rainerhahnekamp Jun 18, 2024

Aren't non-Angular libs not failing by default? They are not aware of the emulated DOM and accessed document, window, etc. directly. In the past, I always had to disable them on the server.

yjaaidi Jun 18, 2024

It depends on how intrusive they are and the APIs they rely on.
Generally speaking, it is challenging and fragile but I've seen SSRed apps that relied on 3rd party libs interacting with the DOM.

The two examples that I've seen and I have in mind are:

code syntax highlighting libraries where you provide a DOM element and it highlights the <code> in it accordingly.
a library that highlighted the text matching searched keywords (fragile and not ideal again. I recommended avoiding this but I am pretty sure that there are some similar behaviors out there in the wild 😊)

rainerhahnekamp · 2024-06-18T21:12:51Z

rainerhahnekamp
Jun 18, 2024

Ad Question 3: Aren't there alternatives to deprecating ElementRef? Like zone.js & zoneless or Standalone & NgModules? There should be a clear recommendation towards DomRef but maybe not deprecate ElementRef.

I guess the migration script will not be able migrate it to 100%?

6 replies

iteriani Jun 18, 2024
Collaborator

I wonder if offering a carrot such as enabling faster SSR would be better in the short term vs deprecation. For example, disabling domino and allowing streaming (as opposed to waiting until an application is stable) would depend on all usages of ElementRef being migrated to DomRef.

jelbourn Jun 18, 2024
Maintainer Author

As a general rule of thumb, we'll deprecate + migrate something when we're confident we can write a tool that will automatically handle the vast majority of use-cases. This would be the case with e.g. NgFor to @for (and other control flow). We do this because it makes the framework harder to learn/use/maintain if there are multiple supported ways of accomplishing the same thing. In this instance, ElementRef and DomRef would do the exact same thing, but with DomRef having more safeguards to prevent unintended failures.

For changes that aren't straightforward 1:1 migrations (e.g. NgModule to standalone), we'll take the approach of both continuing to be supported (but maybe not forever, depending on the specific scenario).

rainerhahnekamp Jun 18, 2024

I see. When the migration is as smooth as the one for the control flow, it is not really a big deal. If I don't have any work to do, feel free 👍😃

jdegand Jun 19, 2024

Does DomRef trigger change detection? ElementRef does not trigger change detection.

Is DomRef sanitized?

waterplea Jun 20, 2024

@jelbourn migration here wouldn't help libs. Libs could keep using modules, they could not adopt new control flow and still be usable in Angular 18, even if they are distributed with Angular 14 + Ivy. In my environment, which I'm sure I'm not the only person experiencing, enterprise has tons of apps. Some of them are supported by limited teams, who do not have resources to keep up with latest framework and latest recommended approach. But they use internal and external libs and depend on bugfixes and features, so libs tend to lag behind for backwards compatibility. This seems like a HUGE change. Alternatively, if DOM emulation becomes optional and the old way is maintained — this is going to split user base, because libs have a choice to either adopt new way and cut off old users, which in real business environment is typically not an option for them, or they will have to enforce DOM emulation on the apps using them. This, in turn, would limit new approach adoption or have users turn away from the lib for that reason. I honestly don't see how this whole idea would be beneficial to Angular ecosystem. Admittedly, I'm not familiar with hydration/resumability which might be what you are trying to solve here, but I'm well enough experienced with SSR and building tons of low level stuff that was compatible with both client side and server side rendering with no problems, Angular and DI already have everything we as devs need in that regard.

Harpush · 2024-06-18T21:21:03Z

Harpush
Jun 18, 2024

How does it relate to renderer api? Will it get deprecated too?

2 replies

devknoll Jun 19, 2024

There currently aren't any changes planned to Renderer2 for this RFC.

While the Renderer2 APIs can potentially break hydration and streaming today, the new guard rails introduced by DomRef and DOCUMENT_REF should sufficiently eliminate this risk without requiring further API changes.

Harpush Jun 24, 2024

There currently aren't any changes planned to Renderer2 for this RFC.

While the Renderer2 APIs can potentially break hydration and streaming today, the new guard rails introduced by DomRef and DOCUMENT_REF should sufficiently eliminate this risk without requiring further API changes.

So does that mean DOM interactions through the new api are preferred? So essentially deprecating renderer2? Or are there still use cases for it?

e-oz · 2024-06-18T21:42:53Z

e-oz
Jun 18, 2024

DomRef will throw if you attempt to unwrap it before the next afterRender or afterNextRender

How migrations are going to handle this? There is no way to automatically replace ElementRef with DomRef if a code logic change is required.

8 replies

JeanMeche Jun 19, 2024
Collaborator

I would expect this to work as long as the referenced element exists.

e-oz Jun 19, 2024

There are 2 references and both of them work when an input setter is called. afterNextRender() happens after inputs are set, but I'm not sure if it happens in the same tick, synchronously.

e-oz Jun 19, 2024

ElementRef in the constructor would already return empty

I'm sure some directives use ElementRef in the constructor to get the host element. I've updated my example to show the use case.

devknoll Jun 19, 2024

For the given StackBlitz example, it's really preferred that you use bindings here (host or otherwise) rather than direct DOM manipulation using either DomRef or ElementRef.

Using afterNextRender here just to prevent throwing wouldn't be great, as your styles will change after hydration, which could be jarring for users.

e-oz Jun 19, 2024

@devknoll it doesn't matter what would be better in that example. The reason why that example exists is not to show how I usually write my code but to ask what things from that example will stop working and what things will be covered by migration. The only thing I care about in this RFC is the scale of breaking changes. The new code will adapt to (almost) anything, that’s not an issue.

lacolaco · 2024-06-18T23:00:24Z

lacolaco
Jun 18, 2024

The cause that Angular cannot create the dom ref is not only by SSR, but also the element doesn't exist. For example, the referred element may be dismissed by if block.

So my question is: Why it throws rather than returns null?

2 replies

Yogu Jun 19, 2024

Currently, viewChild('does-not-exist') results in a Signal with the value undefined, so there would be no ElementRef at all. I'd assume that this part would not change. A DomRef would only be created if the view child actually exists. This part can already be determined on the server-side.

-> I'd assume viewChild('does-not-exist')() (the () to unwrap the signal, not the DomRef) on the server side would just return null instead of throwing, correct?

devknoll Jun 19, 2024

The RFC prefers throwing rather than returning null because it considers reading the value too early to be a program bug that really ought to be addressed.

In the case of conditional elements, as @Yogu mentioned, these are handled by the respective query APIs, where you should get undefined or an empty array. It's possible that you will still have references to a DomRef even if the element is removed, but this is also the case with ElementRef.

DmitryEfimenko · 2024-06-19T03:49:56Z

DmitryEfimenko
Jun 19, 2024

Not sure if the goal, namely partial hydration and streaming are worth such a huge breaking change. Now, if the change was enabling resumability, I'd have zero doubts.

0 replies

MillerSvt · 2024-06-19T04:52:30Z

MillerSvt
Jun 19, 2024

What will the viewChild API that returns DomRef look like?

class MyComp {
    element = viewChild('element');

    method() {
        this.element()(); // First call returns DomRef, second call returns HTMLElement ?
    }
}

4 replies

Yogu Jun 19, 2024

~~I'd think viewChild would already return a DomRef, so you would only need to call it once~~

oops of course viewChild() currently returns a Signal, that's why you would need to call it twice

samuelfernandez Jun 19, 2024

Calling it twice doesn't look that nice 😅

MillerSvt Jun 19, 2024

I believe this would be possible if DomRef extended the signal.

waterplea Jun 21, 2024

That's actually a reasonable proposition. I would much more prefer it to be a signal that doesn't throw but return null instead, while it is not safe to query and then be reactively updated with actual value when it becomes available. This way we would still be able to build declarative structures that do not rely on the order of execution instead of branching our code, FYI @jelbourn @atscott

waterplea · 2024-06-19T06:04:24Z

waterplea
Jun 19, 2024

This sounds terrible for low level devs like me, who are focused on Web APIs and UI components libraries as it potentially introduces a lot of imperative boilerplate, dependent on the order of execution.

8 replies

JeanMeche Jun 19, 2024
Collaborator

I'm not talking about the host element, but any other reference elements like with myInputRef in the example.

waterplea Jun 19, 2024

If you are talking about view queries — I haven't yet used the signal form so I cannot comment on that. In case of traditional view queries they were always typed with ? and I worked around it as I would do with any other optional type, by early returns or fallback values when appropriate. I would much more prefer that than being unsure if it will throw on me. And what about host element? How relevant this API is for it?

Code example in the original post looks like cumbersome react-like hook shenanigans. I didn't like afterNextRender API when it first popped up, when we already had isPlatformBrowser, now it looks as if we will be forced to use it if we want to support SSR, which we already had no problems doing. I don't know much about hydration and internal troubles Angular team has with server side, but this all seems very foreign to me, Angular and DI had everything we need to support server side, from a standpoint of library developer.

Angular already discourages direct DOM manipulations, people who do it usually know what they are doing, we don't need it to become harder.

devknoll Jun 20, 2024

Would you be able to share more specifics about your use cases and concerns?

I understand and appreciate your concern about potentially making direct DOM manipulation harder. The challenge is: how do we make DOM emulation optional while minimizing the impact to other areas? If you can always reach into DOCUMENT or an ElementRef at any time, such as in a constructor, then Angular must always emulate the DOM, since the code is running during server rendering too.

At the same time, it's not clear to me personally that simply returning null instead would be compelling by itself. For example, if the RFC supported myInputRef.maybeGet()?.style.setProperty(...): in which situations would this code be executed? Is it really OK to just silently not set this property only during server rendering? Or is the component going to get rendered with one style, and then immediately flash to another style (possibly causing a layout shift) upon hydration, causing a poor user experience?

waterplea Jun 21, 2024

I'll try to dig for examples, but I'm having hard time wrapping my head around the proposition. We can access ElementRef in two ways, for the most part.

Injecting host element
Using content/view queries

Are you proposing that we will no longer be able to inject host element in constructor? That is super bad.
Queries are already empty/undefined until they are resolved. New queries are signals, which is even better because they declaratively notify subscribers that they become available.

How does the proposed change intend to improve our lives as developers? I read it as it tries to sell it to us under the guise of type safety, claiming the current approach is error-prone and destined for issues that are hard to diagnose. What seems to be lurking underneath is attempt to make internals of Angular easier for the team, which is not bad in and of itself, but at the cost for us as Angular users.

waterplea Jun 21, 2024

I have listed my cases of concern in a separate reply: #56498 (comment)

kedevked · 2024-06-19T08:37:47Z

kedevked
Jun 19, 2024

Question 3: That's a great step forward for Angular. I have always found the ElementRef API not developer friendly. I like that the new api throw error when it is called. It will force developer to write code that follows the best practices. Returning DomRef | null as suggested by some comments, will imply checking against null when using DomRef. I am in favor of causing the api to throw

Question 2: The limits are easy to understand. Angular has always discouraged DOM manipulation. This is the time to restrict it by throwing errors

0 replies

e-oz · 2024-06-19T10:17:46Z

e-oz
Jun 19, 2024

q2: no. Will be there any changes in comparison to ElementRef? ElementRef was not always accessible either.

q3:

From a developer ergonomics perspective, does DomRef seem easier to use than ElementRef?

No, I see no difference. ElementRef will throw an exception if undefined, and DomRef will throw an exception if not ready. What's the difference? A framework should have breaking changes to move forward, but what is the difference here? What for these breaking changes? elementRef?.nativeElement or domRef() - both of them will throw if not ready, ok, what are the benefits?

Almost every library in the ecosystem will be affected - some apps will stuck with an upgrade not because they can't run a migration, but because a library they use didn't migrate. Maybe you could just improve the existing ElementRef somehow?

3 replies

eneajaho Jun 19, 2024

Libraries that migrate to latest version will probably accept PRs that convert ElementRef to DomRef, but as you said, this is an issue for older libs which don't migrate to latest Angular (they already are an issue that we as community need to fix somehow)

danielglejzner Jun 19, 2024

Libraries that migrate to latest version will probably accept PRs that convert ElementRef to DomRef, but as you said, this is an issue for older libs which don't migrate to latest Angular (they already are an issue that we as community need to fix somehow)

This is not a solution. Dragging entire ecosystem with us all the time wont work. 15 -> 16 is a hard enough push for libs.

waterplea Jun 20, 2024

As a library maintainer I confirm this is going to be abysmal. Backwards compatibility is very important for libraries because not every app is ready to upgrade to the latest Angular. In Enterprise ecosystem a lot of apps lag behind but need features and bugfixes from libs. And making "emulation optional" will just split user base along this axis. Libraries that rely on "the old way" would require apps to use emulation, therefore limiting either library user base or new DOM approach adoption. I'm seriously confused how this whole idea is considered rational.

Yogu · 2024-06-19T12:33:31Z

Yogu
Jun 19, 2024

Discussion Question 2: To help create components that always work great on the server and browser, we’re proposing limits to when and how native DOM elements can be accessed. Are these limits (and their rationale) easy to understand?

I think yes. Basically: Only access the DOM in the browser.

Discussion Question 3: For a more ergonomic API, we’re proposing replacing the ElementRef API with a new API named DomRef. From a developer ergonomics perspective, does DomRef seem easier to use than ElementRef? Are there any use-cases for ElementRef that are made worse by using DomRef?

I do not agree with the first proposed benefit (that DomRef has a more streamlined API because the value can be unwrapped simply by calling it) on its own. I do not think that .nativeElement is unnecessarily verbose. It is a regular property access, so you understand what is happening. Calling a value (as opposed to a named function) has no clear meaning.

Especially the case of a Signal<DomRef> as mentioned above can be confusing and might be considered worse than a Signal<ElementRef>, purely from the aspect of understanding the code:

domRef = viewChild('something');
const a = domRef(); // () here means "access the signal value"
const b = a(); // ()  here means "access the native element"
const c = nodeRef()(); // the repated () could be interpreted as bug on first glance

However, I think it is good that unwrapping a DomRef throws if you access it before if it is not available. The code that tries to accesses it should not run on the server in the first place. Throwing instead of returning null or undefined allows Angular to throw an error with a message that explains what exactly is happening.

Property getters should never throw in my opinion - that would be unexpected.

There is one third alternative API besides a getter and a function: just a method. I think it could be easier to understand, especially when combined with getters:

const nodeRef = viewChild('something');
const a = nodeRef(); // () here still means "access the signal value"
const b = a.getNativeElement(); // ()  here means "access the native element"
const c = nodeRef().getNativeElement();

The name getNativeElement() would not really work with DomRef<Document> though.

1 reply

I533118 Jul 2, 2024

I agree. nodeRef()() looks awkward
+1 for nodeRef().getNativeElement();, or just nativeElement property defined as getter in the API.

robertIsaac · 2024-06-19T18:22:27Z

robertIsaac
Jun 19, 2024

answering Question 1

case 1. multiple language support

in projects that support multiple languages especially if it's mixed between RTL and LTR languages (e.g. Arabic and English), we need to change the dir and language attributes of the html elements, and to add the proper css style files (e.g. bootstrap.min.css or bootstrap.rtl.min.css) on the server depending on the route the user is using (e.g. start with /ar or /en

without rendering this in the SSR, it will mean only one language will be properly indexed, e.g. both Arabic and English pages will be indexed as English, and that the page will show initially as LTR then later on to switch to RTL

here is an example of how this work
https://github.com/robertIsaac/angular-internationalization/blob/master/src/app/core/utils/initialize-direction.factory.ts

case 2. SEO tags

add SEO tags to the dom, e.g. canonical, keywords, description as they are dynamically generated from the URL or comes from the API side
without them being in the SSR

3 replies

Jefftopia Jul 12, 2024

Do your SEO tags and other meta/head elements depend on downstream services?
Angular SSR applications already have the ability to specific a document object in lieu of file. My SSR app, for example, reads the doc but interpolates some fields in the express app outside of Angular.

I wonder if the comment about header and meta tags is really a request to pull the entire DOM tree into an Angular app so as to benefit from Angular interpolation. In the meantime, just know that you don't need Angular for any of that.

PowerKiKi Jul 12, 2024

Not OP, but in my case SEO tags are indeed coming from Angular services. So I need Angular features in order to properly set SEO tags. I don't think it would be reasonable to do that "only" via express in that case.

mumenthalers Jul 18, 2024

Same here: SEO tags are set through angular services. Initially set in SSR but as the user navigates in the client, the SEO tags get updated

danielglejzner · 2024-06-19T18:54:21Z

danielglejzner
Jun 19, 2024

I would like to see alternatives to deprecating ElementRef

0 replies

SkyZeroZx · 2024-06-20T02:55:46Z

SkyZeroZx
Jun 20, 2024

Discussion Question 1: We’re proposing moving away from DOM emulation as a well-lit path. Do you have any use-cases that strictly depend on Angular's server-side DOM emulation today?

Currently to use a Canonical Links how example

` createCanonicalLink(url: string) {
const link: HTMLLinkElement = this.document.createElement('link');

	link.setAttribute('rel', 'canonical');
	link.setAttribute('href', url);
	this.document.head.appendChild(link);
}

`

Other hand it's render or append a custom overlay in server with usa document and send to client a modal or toast previous render

`attachRoot(componentType: Type) {
const factory = this.componentFactory.resolveComponentFactory(componentType);
const componentRef = factory.create(this.injector);

	this.applicationRef.attachView(componentRef.hostView);

	const domElem = (componentRef.hostView as EmbeddedViewRef<Type<T>>).rootNodes[0] as HTMLElement;

	this.document.body.appendChild(domElem);

	componentRef.changeDetectorRef.markForCheck();

	return componentRef;
}`

Question 3
For a more ergonomic API, we’re proposing replacing the ElementRef API with a new API named DomRef. From a developer ergonomics perspective, does DomRef seem easier to use than ElementRef? Are there any use-cases for ElementRef that are made worse by using DomRef?

Possible breaking change a libs or wrapper or elements if not migration applied to ElementRef , i prefer deprecated or coexist by certain of time
Example of Swiper Web Element to Angular
``
constructor(
private element: ElementRef,
@Inject(PLATFORM_ID) private plataformId: object
) {
this._swiperElement = element.nativeElement;
}

ngAfterViewInit(): void {
	Object.assign(this.element.nativeElement, this.config());
		this.element?.nativeElement?.initialize();
}

0 replies

waterplea · 2024-06-21T07:31:00Z

waterplea
Jun 21, 2024

Use cases for ElementRef that I feel are going to become a lot harder

I have voiced my concern regarding this RFC and in numerous places were asked for examples that I'm worried about, so here's a list of them in a separate branch of discussion.

Create complex RxJS streams through piping various fromEvent Observables.
Testing if element is focused/contains focused element.
Using native imperative APIs, such as .focus(), .scrollIntoView(), .scrollTo(), .contains(), .matches() and many more.
Manually dispatching events, custom events.
Manual DOM manipulations, such as creating ripple effect with manually created and attached elements etc.
Querying elements for their properties, such as size, id, data attributes etc.
Using Web APIs, such as IntersectionObserver, MutationObserver etc.
Working with low level DOM stuff, such as selection, input masking, DOM traversals — we are still in the web and these things are needed in UI kits, even though they are rarely visible to business logic devs.
Manually overriding styles, such as temporary resetting scrollBehavior to scroll without animation, moving something offscreen in some sync processing, fighting numerous iOS bugs with hacks.
Unit testing will get more detached from real situation when you will try to programmatically dispatch event in jest and it will be treated differently.

If any of those are not self evident — feel free to ask about particular bullet and I will try to bring up a real life scenario.

I understand that there might be criticism of most of these cases that they don't really make sense for SSR part of app lifecycle, however to this I would respond — it is MUCH easier to organize your app in a way that works both for client side and server side by just using early returns or properly reacting to, say, nullish size of elements on the server, than to branch it out explicitly into client side and server side pieces of executed code. I though DI was EXACTLY the answer to doing it this way by providing different dependencies in different environments to allow us to write code if we have everything we need all the time. Otherwise what was the point of DOCUMENT token at all? Why don't we just test if (typeof window !== 'undefined') everywhere? I don't see how this new approach is much better than just querying global objects like window or navigator as is — they will also just through whenever they are not there.

44 replies

e-oz Jul 12, 2024

unsafe() variants should throw, that would justify the "unsafe" part. Not vice versa.

waterplea Jul 13, 2024

unsafe() variants should throw, that would justify the "unsafe" part. Not vice versa.

I don't think we will get there, given the intent of the team to enforce the practice of DOM access in a designated environment only 🙂 but that sure does sound correct, a safer approach is to be told upfront something might not be there. Especially when we can access DOM in event callbacks and not just in hooks, and that's just a straight up «might throw, might not throw, we don't know» 🙂

I'm sure glad we are getting somewhere that satisfies all needs, though, whatever we call it in the end.

mauriziocescon Jul 13, 2024

Well, it depends on the POV and what you want to achieve. Try to interpret the ng-team wish:

Safe = try to trust us! In order to deliver great ssr features (as an ecosystem), libs should be ssr ready (with what’s coming next as well). And without clear exceptions (=> refactoring), it's gonna be hard to achieve the goal. Therefore, we’d like to enforce the rules at https://developer.chrome.com/blog/angular-dom-safety-ssr. This is the safe way of doing DOM manipulation now and in the future (so safe as a way of expressing “future proof, no side effects”). In exchange of your trust, we promise you to deliver great migration tools (pretty sure not perfect).

Technically speaking, this is not different than:

do NOT use inject outside of an injection context (exception),
do NOT access input-objects in the comp-constructor (potential exception),
…

Unsafe = we understand you might be skeptical... and, as pointed out, we don’t want wild runtime exceptions if you’re not ready or you know what you’re doing. In such cases, just manage null… but considering the average ng-dev quickly reading the doc, we want to make sure the message is clear: this is not following the guidelines (goal: great ssr features for the ecosystem), so it can have side effects. Therefore unsafe (as a way of saying “warning”).

Strictly personal: I understand all your concerns… I work for a big corporation and changing things is always difficult / time consuming (I see myself in all the roles in this discussion).

But on the other hand, I truly believe it’s mostly a matter of trust. And trust is not for free… you gotta earn it, bit by bit, day by day. After what the ng-team has done in the last years, they won mine (and I guess many others)!

And considering the never ending story with React, it’s simply insane thinking there’s no careful thoughts behind any proposed change (adaptation after feedback is part of the oss DNA).

My last 2 cents!

e-oz Jul 13, 2024

safe = will definitely not blow up your code in runtime, will check everything before execution.

unsafe = there might be undefined behavior, exceptions, and panics.

It is not related to trust at all (I don’t see how the term “trust” can be applied here). Code either throws or not. JS can not have an undefined behavior or panics, so the only code that might be called unsafe is code that might throw exceptions.

There is absolutely nothing personal.

pfeileon Aug 13, 2024

I'd like to know why it's an exception in the first place: If you know when and where it happens, how is it an exception?
If you want to provide more information, return a result object.

tomastrajan · 2024-06-21T08:04:47Z

tomastrajan
Jun 21, 2024

In general, we believe that the only time you should need to unwrap and access a native DOM element is on the browser, after the page has been rendered, typically in response to a user interacting with the page.

It depends, for webapps maybe, but if we use Angular to build websites, the inability to access DOM in SSR context would lead to a different HTML being produced on server vs in browser after bootstrapping of Angular / hydration, I would image this would potentially lead to content layout shifts (and hence rise in the CLS lighthouse metric) which is penalized.

Angular, especially with SSR / SSG / hydration is an attractive option for websites as well as webapps and custom component libraries can provide unified style for all organization touchpoints which is very valuable and efficient.

It seems that impact of this change would have negative consequences on this use case.

1 reply

mauriziocescon Jun 21, 2024

Just reporting it...

https://developer.chrome.com/blog/angular-dom-safety-ssr

JeanMeche · 2024-06-21T15:39:47Z

JeanMeche
Jun 21, 2024
Collaborator

Care to give any details what myInputRef = inject(DomRef<HTMLInputElement>); exactly does ?
It's unclear to me. Is it the equivelent of inject the ElementRef ?

2 replies

mauriziocescon Jun 21, 2024

#56544

JeanMeche Jun 21, 2024
Collaborator

Perfect, that's it. The DomRef can be read safely once the component is init when in a browser context.
I feel reasonable to me that init with DOM changes shouldn't happen in the constructor.

j-perezr · 2024-06-22T15:10:49Z

j-perezr
Jun 22, 2024

We have an application written in Angular and we have a set of web components for the common componentw (header, footer, menu, the shell component with the layout, notification center, etc). These components use shadow dom, both, open and close and expose not only props and events but also methods. We had a requirement to implement SSR but found, as mentioned, several problems. Would be possible with the new API using web components?

0 replies

PowerKiKi · 2024-06-26T12:22:52Z

PowerKiKi
Jun 26, 2024

SEO tags

We have a requirement to be able to set a few elements in <head> for SEO purposes. This includes <meta> and <link> elements. Otherwise SSR pages as seen by crawlers would not include SEO information, ruining the entire reason for SEO to exist.

One of the thing we rely on is the Meta service to to generate <meta> elements in SSR. And we have a custom service Link which is very heavily inspired by Meta but for <link> elements.

Today the implementation of Meta relies on DOCUMENT. That means it will break and will need to be refactored/re-implemented differently by the Angular team.

Will the new Meta still be able to generate <meta> elements in SSR ?
Will it be possible for user-side code to mimic the new Meta implementation in order to provide similar features for <link> elements ? Or will it be impossible because the new Meta will use internal APIs not accessible by user-side code ?

4 replies

devknoll Jul 10, 2024

The Meta service will continue to operate as-is for now. Any future breaking changes related to it will be announced in advance and follow the Breaking change policy as normal.

PowerKiKi Jul 11, 2024

So you plan to keep using the deprecated DOCUMENT internally to implement Meta ? What will happen when DOCUMENT will finally be dropped and it will be impossible to manage <meta> (and <link>) during SSR ?

Your answer does not mention any possible way out of this. That seems a bit short sighted. I am worried that we will end up in a dead end if we implement this RFC as-is. And when the time to solve this issue comes, we will just give up and won't ever be able to manage <meta> and <link> during SSR.

I don't expected a fully-fledged solution, but at least some hints on what could be possible, and most importantly the guarantee that we will still be able to handle all SEO tags during SSR.

Can you guarantee that ?

devknoll Jul 11, 2024

My apologies: I'm not sure that I would consider an outcome that is incapable of managing <head> tags to actually be SSR 🙂

The question is: how do you manage those tags then? Via a DOM-like interface like Meta? Or perhaps a more declarative method? In the simplest case, an alternative API could look exactly like the existing Meta service today, except that it uses DomRef<HTMLMetaElement> everywhere it currently uses HTMLMetaElement. But would that be the best alternative...?

I can't provide an answer about what this will look like, because that hasn't been decided yet. I can say, however, that SEO support is extremely important for SSR. I can imagine a world where the API might become more limited (i.e. being unable to directly access HTMLMetaElements, due to DOM emulation) or more declarative (i.e. perhaps as part of route configuration, similar to <title>, or included directly as part of a component template), but I can't imagine a world where you're not able to have significant control over the content of <head> in some manner: that just doesn't seem very useful.

PowerKiKi Jul 12, 2024

I can't imagine a world where you're not able to have significant control over the content of <head> in some manner

That's all I wanted to hear, thank you.

samuelfernandez · 2024-07-01T15:51:55Z

samuelfernandez
Jul 1, 2024

Discussion Question 1: As mentioned, there are use cases where the checking the HTML structure is needed. For example, a directive that sets the for attribute in a label to bind it to an input. Again, it is possible to find a solution, but it involves work...

Discussion Question 2: Yes, reasoning is clear and solution looks nice. However, there are private apps that will never need SSR or SEO. Forcing them to do a major refactor that can't be automated because of the deprecation of ElementRef without providing benefits would be painful.

Discussion Question 3: Current API with ElementRef is already simple.

I understand that the new one provides more benefits such as runtime checks. With the new input based on signals, I really like how it can be declared, and the framework has protections against accessing its value before being set. By using inputs just inside computed, effect or the template makes it safe and as devs we forget about that limitation.

Something similar will happen with DomRef, which is nice. As long as it is used inside afterNextRender should be safe, that is more the breaking change to me. But don't know if it is a great benefit weighting the impactful breaking change of deprecating ElementRef. I'd be nice that it could be supported across various major versions at least.

Thoughts on the API

I wonder why the generic type for ElementRef<T> or the new DomRef<T> does not have a default type like HTMLElement. It would be a nice default, even a type constraint, without needing to declare it in every use case.

4 replies

zygarios Jul 2, 2024

@samuelfernandez great idea with default type HTMLElement

PowerKiKi Jul 3, 2024

Default type HTMLElement sounds like an improvement, or maybe no default at all to force people to specify what they expect. At the very least it shouldn't default on any as it is now. Because it is way too permissive.

devknoll Jul 10, 2024

Would Element be an acceptable default type instead of HTMLElement? This would make it safer (e.g. when using SVG or MathML).

Yogu Jul 10, 2024

You probably wouldn't specify the type as often as you currently specify ElementRef<...> because with the new function-based queries like viewChild(), the type can be inferred. So a default type is probably less important (but I agree that it definitely should not be any). Also note that the RFC intents to make use of DomRef<Document>, but a Document is not an Element, only a Node.

Jefftopia · 2024-07-12T01:28:44Z

Jefftopia
Jul 12, 2024

Discussion Question 1: We’re proposing moving away from DOM emulation as a well-lit path. Do you have any use-cases that strictly depend on Angular's server-side DOM emulation today?

I'm concerned about limiting the ability of my organization, which chose the difficult path of supporting many frameworks, to use SSR alongside an ecosystem of design system components written in lit. I'm comfortable with "two" paths but uncomfortable with the risk of dwindling support for a domino-based app. My suggestion is to allow both, but keep domino-based the default for some time.

Discussion Question 2: To help create components that always work great on the server and browser, we’re proposing limits to when and how native DOM elements can be accessed. Are these limits (and their rationale) easy to understand?

Yes but I agree with sentiment expressed elsewhere which amounts to: I'd like to see an Angular way to dynamically create or update, during SSR, more parts of the Head -- inserting links, styles, tags, scripts, etc. Today I do this outside of Angular and provide the "processed" HTML to the commonEngine's render method. I'd rather do it in Angular.

0 replies

JoolsHattey · 2024-07-15T18:10:16Z

JoolsHattey
Jul 15, 2024

Discussion Question 1: We’re proposing moving away from DOM emulation as a well-lit path. Do you have any use-cases that strictly depend on Angular's server-side DOM emulation today?

My use case is that i need to be able to set a class on the document.body on the server, before it's sent to the client. This is used to allow the theme/colours to be set based on the config of the client using the app.
Others in this thread have mentioned having a non DOM emulated way of updating stuff in the head, such as allowing inserting scripts, links, updating body class, etc, would definitley solve this use case without needing direct access to the DOM.

0 replies

devknoll · 2024-08-21T16:02:25Z

devknoll
Aug 21, 2024

Hello everyone 👋

To start, thank you to everyone who participated in this RFC! Your feedback has been incredibly valuable. Additionally, we would like to thank you for your continued patience over the last few weeks.

Many of you have raised valid concerns with this particular proposal, such as:

The awkwardness of the proposed DomRef API changes when coupled with signal queries (e.g. this.el()())
The proposed DomRef API being time-dependent but non-reactive
Lack of information about what is going to happen to related DOM APIs, such as Meta

This is great feedback and demonstrates exactly why we have RFCs in the first place ✨. We strongly believe in the original motivations for this RFC: making DOM emulation optional while providing powerful but safer alternatives. However, this was always intended to be a longer term goal that we expected to gradually move toward over several major releases, while helping the ecosystem adjust along the way.

Put simply: there’s no rush. That is why we’ve decided to put this idea back into the oven for the time being, so that we can spend more time considering your concerns and how best to address them. We’ll share more information in the future when we’re able to.

Thank you again for your valuable feedback and insights 🙏

0 replies

[Complete] RFC: DOM Interaction in Angular #56498

Uh oh!

jelbourn Jun 18, 2024 Maintainer

Background

DomRef API

DOCUMENT_REF Token

Changes to view and content queries

Replies: 24 comments · 94 replies

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iteriani Jun 18, 2024 Collaborator

Uh oh!

jelbourn Jun 18, 2024 Maintainer Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeanMeche Jun 19, 2024 Collaborator

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeanMeche Jun 19, 2024 Collaborator

Uh oh!

Uh oh!

jelbourn
Jun 18, 2024
Maintainer

`DomRef` API

`DOCUMENT_REF` Token

Replies: 24 comments 94 replies

iteriani Jun 18, 2024
Collaborator

jelbourn Jun 18, 2024
Maintainer Author

JeanMeche Jun 19, 2024
Collaborator

JeanMeche Jun 19, 2024
Collaborator