feat(signals): provide support for scoped events

[markostanimirovic]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/ngrx/platform/blob/main/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:

What is the current behavior?

Closes #4776

What is the new behavior?

// === providing scoped dispatcher: ===
{ providers: [provideDispatcher()] }

// === dispatching events to the parent/global scope: ===
// scope values: 'self' | 'parent' | 'global' ('self' by default)

const event1 = event('event1');
const event2 = event('event2');

// using Dispatcher:
const dispatcher = inject(Dispatcher);
dispatcher.dispatch(event1(), { scope: 'parent' });

// using injectDispatch:
const dispatch = injectDispatch({ event1 });
dispatch({ scope: 'global' }).event1();

// using toScope:
withEffects((_, events = inject(Events)) => ({
  $: events.on(event1).pipe(
    map(() => [event2(), toScope({ 'parent' })]),
  ),
}))

// using mapToScope:
withEffects((_, events = inject(Events)) => ({
  $: events.on(event1).pipe(
    map(() => event2()),
    mapToScope('global'),
  ),
}))

Does this PR introduce a breaking change?

[ ] Yes
[x] No

[netlify]

✅ Deploy Preview for ngrx-io canceled.

Name	Link
🔨 Latest commit	f0e87a2
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-io/deploys/6921d5bc452e640008f7a4a0

[netlify]

✅ Deploy Preview for ngrx-site-v19 ready!

Name	Link
🔨 Latest commit	f0e87a2
🔍 Latest deploy log	https://app.netlify.com/projects/ngrx-site-v19/deploys/6921d5bc952bad00086cbc42
😎 Deploy Preview	https://deploy-preview-4997--ngrx-site-v19.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rainerhahnekamp]

Will you provide the updated documentation in a separate PR?

[markostanimirovic]

@rainerhahnekamp Yes, I'll add a new section 'Scoped Events' without changing existing content from the Events page because the previous behavior remained the same.

[rainerhahnekamp]

That is important for the event tracker in the toolkit. 👍

[rainerhahnekamp]

LGTM 👍

[timdeschryver]

Lovely! 🤩

[timdeschryver]

Is there a reason to escape these?
In VSCode this gives the following result:

Suggested change

	* \@Component({
	* \/* ... *\/
	* providers: [provideDispatcher()],
	* })
	* @Component({
	* /* ... */
	* providers: [provideDispatcher()],
	* })

[markostanimirovic]

I removed unnecessary second backslashes in: \/* ... \/. The first one is required. Otherwise, it's not displayed properly:

Regarding a backslash before the @Component decorator, it's needed to avoid treating @Component as a JSDoc annotation.

[timdeschryver]

An open question about the naming of this function, sorry I should've mentioned this in the RFC.
What about renaming it to withScope, I think this makes the intent easier to read.

[loadSuccess(), withScope('global')]
// or
[loadSuccess(), scopedTo('global')]

I'm also fine with toScope though.

[markostanimirovic]

I'd keep the toScope name for consistency with mapToScope, but also to distinguish it from SignalStore features that have the with prefix.

In general, this helper is not required (we can directly return [loadedSuccess(), { scope: 'global' }]), but I added it for a bit better DX - to avoid typos and enable autocompletion in IDEs for the scope name. Anyway, mapToScope will be the common way to change the default event scope in the effect, while toScope can be used if we want to have more granular control and have different scopes for success and error events, which would be a rare case.