[Angular CDK] Better control over the outside click event

[pawel-twardziak]

Hi,

in that PR https://github.com/radix-ng/primitives/pull/200/files I introduced this;

interface MouseEvent {
    defaultPreventedCustom?: boolean;
}

interface KeyboardEvent {
    defaultPreventedCustom?: boolean;
}

It has been removed in one of my next PRs as I found it an anti-pattern a bit

I don't think this can be considered an anti-pattern if it is released as an official feature and is included in the documentation.

What is the reason for having such keys on the events?

1. Angular CDK being reasonable only provides browser native way to prevent the event if we wish: event.preventDefault(). If we need more, Angular leaves it to our own implementation using CDK.
2. event.preventDefault() aims all the default listeners which is e.g. <a href="..." /> click
3. We don't really want to prevent all the default actions every time we prevent a specific popover from reacting to any outside click
4. Preventing one popover from reacting to an outside click prevents all the rest popovers at the same time - which is not always desired. I reckon that quite often developers want to prevent one or some popovers while the rest should not get affected.

What feature could we implement to address the issues?

Steps:

1. Extend MouseEvent, KeyboardEvent and any event that we are gonne use from the CDK
2. Add a specific api interface to the event that gives a way to prevent a particular primitive instance on the page from being affected by the event, e.g.:

function callback(event: MouseEvent) {
  event.rdxPreventPrimitive('popover', id);
  // OR
  event.rdxPreventPrimitive(exactPopoverRootInstance);
  // OR
  event.rdxPreventPrimitive();
}
// where:

// first example
// first argument: 'popover' (optional) - type of primitive I want to prevent from bein affected by the event;
// second argument: id (optional) - exact instance id of the type of primitive I want to prevent from being affected by the event

// second example
// first argument: exactPopoverRootInstance (optional) - exact instance of primitive I want to prevent from being affected by the event

// third example
// no arguments: exactPopoverRootInstance (optional) - prevents all primitives on the page from being affected by the event

@radix-ng/core @radix-ng/maintainers

share your thoughts about it please :)

[artembelik]

@pawel-twardziak is there an example of similar logic implementation in other libraries?

[pawel-twardziak]

yeah, that's really interesting. I am cheking these:

• https://www.spartan.ng/
• https://angularprimitives.com/
• https://ng.ant.design/components/popover/en
• https://primeng.org/

any other suggestions?

[pawel-twardziak]

Spartan NG

They don't care. There is that code for opening dialog action:

	public open<DialogContext>(
		content: ComponentType<unknown> | TemplateRef<unknown>,
		vcr?: ViewContainerRef,
		context?: DialogContext,
		options?: Partial<BrnDialogOptions>,
	) {
                // ...
		if (options?.closeOnOutsidePointerEvents) {
			cdkDialogRef.outsidePointerEvents.pipe(takeUntil(destroyed$)).subscribe(() => {
				brnDialogRef.close(undefined, options?.closeDelay);
			});
		}

		if (options?.closeOnBackdropClick) {
			cdkDialogRef.backdropClick.pipe(takeUntil(destroyed$)).subscribe(() => {
				brnDialogRef.close(undefined, options?.closeDelay);
			});
		}
                // ...
	}

Developer cannot control it from outside cause the events are not exposed via outputs.

Our current implementation is more flexible and it could be even better with the approach I am proposing :)
We ought to give more value to developers to make them choose our library.

Let's see the other libs :)

[pawel-twardziak]

Angular Primitives

same as Spartan NG

[pawel-twardziak]

Ant Design of Angular

same

[pawel-twardziak]

Prime NG

they don't use the CDK Overlay.

[pawel-twardziak]

I don't see any other UI lib that counts taking care about what I am proposing.

So we could come up to the developers with a simple primitives registry and its internal API partially exposed via UIEvent or/and window object.

IMHO that would be a game changer for creative developers.

The more functional are out funabilities, the more fertile creativity of programmers 🚀

[pimenovoleg]

Sounds very interesting!
It seems that flexible control over the event model is something that doesn't get much attention.
This issue (and related ones) also discussed DOM events:
angular/components#9713

[pimenovoleg]

https://github.com/adobe/react-spectrum/blob/main/packages/@react-aria/interactions/src/useInteractOutside.ts#L34

The useInteractOutside hook allows tracking user interactions outside a specific element, which is useful for implementing features like closing popups when clicking outside their area. It provides the ability to handle such events and, if necessary, prevent their propagation.

Both of these hooks can be used to create components with controlled event behavior, similar to rdxPreventPrimitive.

@pawel-twardziak what do u think ?

[pawel-twardziak]

Sounds very interesting! It seems that flexible control over the event model is something that doesn't get much attention. This issue (and related ones) also discussed DOM events: angular/components#9713

Thanks @pimenovoleg!

[pawel-twardziak]

https://github.com/adobe/react-spectrum/blob/main/packages/@react-aria/interactions/src/useInteractOutside.ts#L34

The useInteractOutside hook allows tracking user interactions outside a specific element, which is useful for implementing features like closing popups when clicking outside their area. It provides the ability to handle such events and, if necessary, prevent their propagation.

Both of these hooks can be used to create components with controlled event behavior, similar to rdxPreventPrimitive.

@pawel-twardziak what do u think ?

I am not that good in React but yeah I will look at that :) Thanks! Nice you share my thoughts, maybe we create some great funability. Let's see ;)

The issue with the CDK outsideClick is that it is being listened on body element for capture phase and multicasted among all the overlays so we cannot really use preventDefault, stopPropagation or stopImmediatepropagation. Let's explore :)

[pawel-twardziak]

Sounds very interesting! It seems that flexible control over the event model is something that doesn't get much attention. This issue (and related ones) also discussed DOM events: angular/components#9713

Interesting, that issue isaacplmann/ngx-contextmenu#151 has been hanging for about 5 years :D

[pimenovoleg]

Off-topic, but about popovers :)
Built with Floating UI.
Documentation: ngx-popovers

[pawel-twardziak]

ngx-popovers is a bit outdated - I have checed it
Floating UI looks interesting, we might draw some inspiration from it :)

[pimenovoleg]

Recommended Approach

• Don’t modify the native event interfaces directly.
• Consider creating a separate abstraction: a custom event object or a global registry that keeps track of which primitives should ignore a given event.
• Document your chosen approach thoroughly, so it’s clear to all contributors how to manage event prevention logic.

interface RdxEvent<T extends Event> {
  originalEvent: T;
  preventedFor: { [primitiveType: string]: Set<string> };
  preventFor(primitiveType?: string, id?: string): void;
}

import { Directive, HostListener, EventEmitter, Output } from '@angular/core';

@Directive({
  selector: '[rdxEventWrapper]',
  host: {
    '(click)': 'onClick($event)'
  }
})
export class RdxEventWrapperDirective {
  @Output() rdxClick = new EventEmitter<RdxEvent<MouseEvent>>();

  onClick(event: MouseEvent) {
    const rdxEvent: RdxEvent<MouseEvent> = {
      originalEvent: event,
      preventedFor: {},
      preventFor: (primitiveType?: string, id?: string) => {
        const type = primitiveType || 'global';
        if (!rdxEvent.preventedFor[type]) {
          rdxEvent.preventedFor[type] = new Set<string>();
        }
        rdxEvent.preventedFor[type].add(id || '__ALL__');
      }
    };

    this.rdxClick.emit(rdxEvent);
  }
}

In @Component usage

shouldClose(event: RdxEvent<MouseEvent>): boolean {
    const prevented = event.preventedFor['popover'];
    if (prevented) {
      if (prevented.has('__ALL__') || prevented.has(this.popoverId)) {
        return false;
      }
    }
    return true;
  }

[pawel-twardziak]

This is exactly what I implemented initially there https://github.com/radix-ng/primitives/pull/200/files having that global extension to the events:

interface MouseEvent {
    defaultPreventedCustom?: boolean;
}

interface KeyboardEvent {
    defaultPreventedCustom?: boolean;
}

But as you said, this is something we want to avoid. Modifying events should be the last resort IMHO as this can appear an anti-pattern at any time.

Right now, on my local branch, I have implemented it back as an internal stuff with some modifications, skipping those global.d.ts files.

I just came back from a long walk and there is an idea in my head :) I mean there are more than one idea for that issue in my head but I am seeking the best one :D

How I see it for now:

global level abstraction:

1. RdxGlobalNgCdkEventsService is optionally provided in the app root. It provides an API for all of our primitives so that each of them can register themselves in the service.
2. CdkOverlay events functionality provied by the service - the service adds event listiners to the root of the DOM (which is <html /> tag) for each of the CDK global listiners (they are for capture phase of an event and that's why the listiners on the <html />)
3. The service can be injected anywhere so that developers can prevent events manually

primitive level abstraction:

1. Each primitive implements a specific directive (via hostDirectives prop) which first will register/deregister the primitive on the global service (if provided of course) and second will prevent the primitive from reacting to a specific CDK event when a particular input on the primitive is provided
2. The input:

• can be boolean, signal or Observable
• thanks to the flexible input type an event can get prevented: once, until, while, replay... any way you can use the input in unleashing the power of signal and observable
• takes not only the condition but also a type of an event,
• takes an array of prevention definiton so that one can prevent many events on the primitive

Of course an effective clean-up is gonne be implemented :)

That's it. I hope I haven't missed anything :) This will definitely work :)

@pimenovoleg how do you see it? :)

[pawel-twardziak]

@pimenovoleg #217 - this is the solution I am proposing :) For popover for now. But we can make it global, for all primitives :)

[pimenovoleg]

🚀 Very interesting, I'll take a closer look in the coming days.

We're also gradually shifting into the holiday mode :)

[pimenovoleg]

A quick, brief comment.
I think this is important in modern software development.

SSR compatibility: Direct usage of window requires additional checks or isolation to prevent crashes on the server.

fast fix it:

const getProvider: (throwWhenExists?: boolean) => Provider = (throwWhenExists = true) => ({
  provide: RdxCdkEventServiceToken,
  useFactory: () => {
    const platformId = inject(PLATFORM_ID);
    const isBrowser = isPlatformBrowser(platformId);

    if (!isBrowser) {
      isDevMode() && console.log('SSR mode detected: returning a stub instead of RdxCdkEventService');
      return null;
    }

    isDevMode() && console.log('providing RdxCdkEventService...');
    if ((window as any)[RdxCdkEventServiceWindowKey]) {
      if (throwWhenExists) {
        throw Error(existsErrorMessage);
      } else {
        isDevMode() && console.warn(existsErrorMessage);
      }
    }
    (window as any)[RdxCdkEventServiceWindowKey] ??= new RdxCdkEventService();
    return (window as any)[RdxCdkEventServiceWindowKey];
  }
});

[pawel-twardziak]

Hi @pimenovoleg I know what role SSR plays in the modern frontend development. Thank you for reminding that :)

I've mentioned if before, but that kind of issues are already delegated to there #202.
I don't want to do everything at once as that approach brings distraction. I am focusing on and carying about only one thing at time as following this way I can polish a particular scope.

I am used to do things step by step, scope by scope. Not all in one. I did all in one many years ago and that was not that efficient way and it was complication-prone approach :) It is enough we are aware about SSR and it is gonna be done soonish imho :)

Let me skip it and do all the SSR stuff withing that issue #202, ok? :)

There are more code parts that must get aligned to SSR requirements.