This commit adds the ability to return `RedirectCommand` from the error
handler provided by `withNavigationErrorHandler`. This will prevent the
error from being surfaced in the `events` observable of the Router and
instead convert the error to a redirect. This allows developers to
have more control over how the Router handles navigation errors. There
are some cases when the application _does not_ want the URL to be reset
when an error occurs.
resolves#42915
PR Close#55370
This commit ensures components in the route config predictably always
get their providers from the hierarchy available to routes rather than
sometimes being dependent on where they are inserted.
fixes#53369
BREAKING CHANGE: Providers available to the routed components always
come from the injector heirarchy of the routes and never inherit from
the `RouterOutlet`. This means that providers available only to the
component that defines the `RouterOutlet` will no longer be available to
route components in any circumstances. This was already the case
whenever routes defined providers, either through lazy loading an
`NgModule` or through explicit `providers` on the route config.
PR Close#54265
Returning a `RedirectCommand` from a resolver can be interpreted as
distinctly different from regular resolved data. When a resolver returns
`RedirectCommand` we can interperet this as an intention to redirect in
the same way as other guards.
resolves#29089
PR Close#54556
This commit updates the internal resolve value of the navigation promise
to use `false` instead of `null` when a navigation is skipped. The
navigation promise type requires `boolean` so the correct resolution to
match the truthy/falsiness of the currently resolved value, `null`, is
`false` instead.
PR Close#55068
This commit ensures components in the route config predictably always
get their providers from the hierarchy available to routes rather than
sometimes being dependent on where they are inserted.
fixes#53369
BREAKING CHANGE: Providers available to the routed components always
come from the injector heirarchy of the routes and never inherit from
the `RouterOutlet`. This means that providers available only to the
component that defines the `RouterOutlet` will no longer be available to
route components in any circumstances. This was already the case
whenever routes defined providers, either through lazy loading an
`NgModule` or through explicit `providers` on the route config.
PR Close#54265
This commit updates the logic around `Route.redirectTo` to enable using a
function to create the redirect. This function can return a string,
ands acts the same as previous string redirects, or a `UrlTree`, which
will act as an absolute redirect.
To be useful, the redirect function needs access to the params and data.
Today, developers can access these in their redirect strings, for
example `{path: ':id', redirectTo: '/user/:id'}`. Unfortunately,
developers only have access to params and data on the _current route_
today in the redirect strings. The params and data in the `RedirectFn`
give developers access to anything from the matched parent routes as
well. This is done as the same way as param and data aggregation later
on (https://github.com/angular/angular/blob/897f014785578d87bc655ea6ae9e113653960f50/packages/router/src/router_state.ts#L236-L278).
In order to accomplish this, we inherit params and data while
matching, after the `ActivatedRouteSnapshot` is created for the matched
route rather than waiting until the end.
The `RedirectFunction` does not return the full
`ActivatedRouteSnapshot` interface. Some things are not accurately known
at the route matching phase. For example, resolvers are not run until
later, so any resolved title would not be populated. The same goes for lazy
loaded components. The is also true for all the snapshots up to the
root, so properties that include parents (root, parent, pathFromRoot)
are also excluded. And naturally, the full route matching hasn't yet
happened so firstChild and children are not available either.
fixes#13373resolves#28661 (though not for the redirect string - you would return a
`UrlTree` from the function)
BREAKING CHANGE: This change allows `Route.redirectTo` to be a function
in addition to the previous string. Code which expects `redirectTo` to
only be a string on `Route` objects will need to be adjusted.
PR Close#52606
Returning `UrlTree` from a guard was a convenient new feature added to
the `Router`. However, it does not have feature-parity with the old
`router.navigate(...); return false;` pattern. The most common use-case
for this feature is to redirect to a new page _without_ updating the URL
from the initially attempted navigation. For example, rendering a 404
page when the user does not have access privelages to a route.
Fixes#17004Fixes#27148
BREAKING CHANGE: Guards can now return `RedirectCommand` for redirects
in addition to `UrlTree`. Code which expects only `boolean` or `UrlTree`
values in `Route` types will need to be adjusted.
PR Close#45023
This refactor makes it easier to update the return types of guards.
Rather than having to track what types guards can return, which may
change with new features over time, `MaybeAsync<GuardResult>` can be
used instead.
PR Close#54580
This is a follow up to https://github.com/angular/angular/commit/5c1d4410298e20cb03d7a1ddf7931538b6a181b4
which added the `info` property to navigation requests. `RouterLink` now
supports passing that transient navigation info to the navigation
request.
This info object can be anything and doesn't have to be serializable.
One use-case might be for passing the element that was clicked. This
might be useful for something like view transitions. In the "animating
with javascript" example from the blog (https://stackblitz.com/edit/stackblitz-starters-cklnkm)
those links could have done this instead of needing to create a separate
directive that tracks clicks.
PR Close#53784
This commit adds a property to the navigation options to allow
developers to provide transient navigation info that is available for
the duration of the navigation. This information can be retrieved at any
time with `Router.getCurrentNavigation()!.extras.info`. Previously,
developers were forced to either create a service to hold information
like this or put it on the `state` object, which gets persisted to the
session history.
This feature was partially motivated by the [Navigation API](https://github.com/WICG/navigation-api#example-using-info)
and would be something we would want/need to have feature parity if/when the
Router supports managing navigations with that instead of `History`.
PR Close#53303
With the deprecation of the configurable errorHandler in the Router, there is a missing
use-case to prevent the navigation promise from rejecting on an error. This rejection
results in unhandled promise rejections. This commit allows developers to instruct
the router to instead resolve the navigation promise with 'false', which matches
the behavior of other failed navigations.
Resolving the Promise would be the ideal default behavior. It is rare
that any code handles the navigation Promise at all and even more rare
that the Promise rejection is caught. Updating the default value for
this option should be considered for an upcoming major version.
fixes#48902
PR Close#48910
There are cases where the application's default behavior is 'reload' and
a certain navigation might want to override this to be `ignore` instead.
This commit allows `onSameUrlNavigation` in the `router.navigateByUrl`
to be `ignore` where it was previously restricted to only `reload`.
PR Close#52265
Angular recently gained a local compilation mode (see commit
345dd6d81a). This is intended to be used
with the TypeScript compiler option isolatedModules, which bans imports
of const enums.
This changes all const enums tagged with @publicApi to regular enums.
Fixes#46240
PR Close#51670
This commit adds the ability to provide a function that will get called
immediately after the view transition is created. This will allow
developers to do things like add/remove classes from the DOM when the
transition animation is finished, skip the transition based on
application conditions, etc. Having access to the transition unlocks
just about every example outlined in https://developer.chrome.com/docs/web-platform/view-transitions.
Note that the timing of the `updateCallback` execution is in the spec as
being called asyncronously (https://drafts.csswg.org/css-view-transitions-1/#callbackdef-updatecallback).
This means the `onViewTransitionCreated` callback is guaranteed to
execute before the update callback which in turn means it is guaranteed
to execute before the view transition `ready`/animation. As a result, it
is safe/effictive to add classes to the document in the
`onViewTransitionCreated` function in order to control animations of
that transition and then remove those classes in the transition's `finished`
`Promise`. The animation also doesn't start until the `Promise` returned
by `updateCallback` resolves, so this would also guarantee that the
animation starts asynchronously.
resolves#51827
PR Close#52002
The router currently restricts all further redirects after an absolute
redirect. Because there's no documented reason for _why_ this
restriction is in place, I'm now deeming this unnecessary. Developers
should not be restricted in this manner. Instead, configs that may
have caused infinite redirects in the past should be updated to not be
infinite. It is confusing to ignore configs with redirects after an
absolute redirect occurred because it creates different matching rules
depending on the whether an absolute redirect has happened or not.
For additional context on why I believe removing this restriction is
necessary, #13373 asks for allowing `redirectTo` to be a function. It
would make sense to allow this function to return a `UrlTree` like other
guards in the Router. When guards in the `Router` return `UrlTree`, they
cancel the current navigation and start a new one to re-do the route
matching. Since we're already in the router matching part, we don't need
to cancel the navigation. However, the restriction on absolute redirects
here then creates a weird situation where developers wouldn't see any
other redirects if they returned a `UrlTree` as an absolute redirect
from `redirectTo`.
resolves#39770
BREAKING CHANGE: Absolute redirects no longer prevent further redirects.
Route configurations may need to be adjusted to prevent infinite
redirects where additional redirects were previously ignored after an
absolute redirect occurred.
PR Close#51731
This commit adds an option to the view transition feature to skip the first transition.
This option is not available in RouterModule.forRoot.
resolves#51815
PR Close#51825
The `setupTestingRouter` function is a factory function for creating a
new instance of the `Router`. This function is effectively a no-op.
Developers should use `RouterModule.forRoot` or `provideRouter` in tests
instead.
BREAKING CHANGE: The `setupTestingRouter` function has been removed. Use
`RouterModule.forRoot` or `provideRouter` to setup the `Router` for
tests instead.
PR Close#51826
The `malformedUriErrorHandler` is used as a recovery mechanism for when the `UrlSerializer`
throws an error when parsing a URL string. If custom error handling is
desired for this, it should instead be done inside the
`UrlSerializer.parse` method itself. There's no reason to have an entire
feature option built around what can otherwise just be `try...catch`.
BREAKING CHANGE: `malformedUriErrorHandler` is no longer available in
the `RouterModule.forRoot` options. URL parsing errors should instead be
handled in the `UrlSerializer.parse` method.
PR Close#51745
The View Transitions API enables easy animations when transitioning between different DOM states. This commit adds an opt-in feature to the Router which runs the component activation and deactivation logic in the document.startViewTransition callback. If the browser does not support this API, route activation and deactivation will happen synchronously.
resolves#49401
PR Close#51314
This commit removes the `urlHandlingStrategy` from the public Router's API
BREAKING CHANGE:
`urlHandlingStrategy` has been removed from the Router public API.
This should instead be configured through the provideRouter or RouterModule.forRoot APIs.
PR Close#51631
This commit refactors the router internals to track state inside a separate
`StateManager`. This helps open the door to managing the state in
different, swappable providers. The current interface needed by the
Router is: `currentUrlTree`, `rawUrlTree`, `browserUrlTree`,
`routerState`, and `handleNavigationEvent` (other properties are because
some router properties are writeable when they shouldn't be). This is
a suprisingly small interface and can hopefully be made smaller in the
future (i.e. removing 1 or more of the 3 tracked of `UrlTree`s).
PR Close#48481
This commit removes deprecated properties on the Router. These are meant
to be configured through DI and not meant to be changed during runtime.
BREAKING CHANGE: The following Router properties have been removed from
the public API:
- canceledNavigationResolution
- paramsInheritanceStrategy
- titleStrategy
- urlUpdateStrategy
- malformedUriErrorHandler
These should instead be configured through the `provideRouter` or
`RouterModule.forRoot` APIs.
PR Close#51502
We enabled a lint rule internally to require that multi-provided
`InjectionToken`s have a `readonly` array type, the tokens in this
PR do not follow this rule and are causing lint violations.
Fixes#51124
PR Close#51125
If a library is compiling with Angular v16.1.0, the library will break
for users that are still on Angular v16.0.x. This happens because the
`DirectiveDeclaration` or `ComponentDeclaration` types are not expecting
an extra field for `signals` metadata. This field was only added to the
generic types in `16.1.0`- so compilations fail with errors like this:
```
Error: node_modules/@angular/material/icon/index.d.ts:204:18 -
error TS2707: Generic type 'ɵɵComponentDeclaration' requires between 7 and 9 type arguments.
```
To fix this, we quickly roll back the code for inserting this metadata
field. That way, libraries remain compatible with all v16.x framework
versions.
We continue to include the `signals` metadata if `signals: true` is set.
This is not public API anyway right now- so cannot happen- but imagine
we expose some signal APIs in e.g. 16.2.x, then we'd need this metadata
and can reasonably expect signal-component library users to use a more
recent framework core version.
PR Close#50714
The component exposed by the fixture is not important thus marked as `unknown`.
Exposing the fixture of the `RouterTestingHarness` allows to use the methods & properties of that fixture and makes it compatible with testing libraries relying on `ComponentFixture`
Fixes#48855
PR Close#50280
This commit adds the `signals: boolean` property to the internal
directive/component metadata. This does not add it to the public API
yet, as the feature has no internal support other than compiler
detection.
PR Close#49981
Adds ability for `RouterOutlet` to bind `Router` information to the routed
component's inputs. This commit also exposes some helpers for
implementers of custom outlets to do their own input binding if desired.
Resolves#18967
PR Close#49633
Adds support for marking a directive input as required. During template type checking, the compiler will verify that all required inputs have been specified and will raise a diagnostic if one or more are missing. Some specifics:
* Inputs are marked as required by passing an object literal with a `required: true` property to the `Input` decorator or into the `inputs` array.
* Required inputs imply that the directive can't work without them. This is why there's a new check that enforces that all required inputs of a host directive are exposed on the host.
* Required input diagnostics are reported through the `OutOfBandDiagnosticRecorder`, rather than generating a new structure in the TCB, because it allows us to provide a better error message.
* Currently required inputs are only supported during AOT compilation, because knowing which bindings are present during JIT can be tricky and may lead to increased bundle sizes.
Fixes#37706.
PR Close#49468
This reverts commit 13dd614cd1.
This breaks a g3 Typescript compilation tests where diagnostics are
expected for a missing input in the component.
PR Close#49467
Adds support for marking a directive input as required. During template type checking, the compiler will verify that all required inputs have been specified and will raise a diagnostic if one or more are missing. Some specifics:
* Inputs are marked as required by passing an object literal with a `required: true` property to the `Input` decorator or into the `inputs` array.
* Required inputs imply that the directive can't work without them. This is why there's a new check that enforces that all required inputs of a host directive are exposed on the host.
* Required input diagnostics are reported through the `OutOfBandDiagnosticRecorder`, rather than generating a new structure in the TCB, because it allows us to provide a better error message.
* Currently required inputs are only supported during AOT compilation, because knowing which bindings are present during JIT can be tricky and may lead to increased bundle sizes.
Fixes#37706.
PR Close#49453
This reverts commit 1a6ca68154.
This breaks tests in google3 which might be depending on private APIs. We
need to update these tests before we can land this PR.
PR Close#49449
Adds support for marking a directive input as required. During template type checking, the compiler will verify that all required inputs have been specified and will raise a diagnostic if one or more are missing. Some specifics:
* Inputs are marked as required by passing an object literal with a `required: true` property to the `Input` decorator or into the `inputs` array.
* Required inputs imply that the directive can't work without them. This is why there's a new check that enforces that all required inputs of a host directive are exposed on the host.
* Required input diagnostics are reported through the `OutOfBandDiagnosticRecorder`, rather than generating a new structure in the TCB, because it allows us to provide a better error message.
* Currently required inputs are only supported during AOT compilation, because knowing which bindings are present during JIT can be tricky and may lead to increased bundle sizes.
Fixes#37706.
PR Close#49304
BREAKING CHANGE:
`ComponentFactoryResolver` has been removed from Router APIs.
Component factories are not required to create an instance of a component
dynamically. Passing a factory resolver via resolver argument is no longer needed
and code can instead use `ViewContainerRef.createComponent` without the
factory resolver.
PR Close#49239
The `Router` already has the `getCurrentNavigation()` helper function to
expose information about the ongoing navigation.
`lastSuccessfulNavigation` is actually already exposed in the
`Navigation` object. This commit only _slightly_ extends the current API
surface by providing access to the `lastSuccessfulNavigation` object
outside of an ongoing navigation.
fixes#45685
PR Close#49235
This commit introduces helper functions to easily convert `Injectable`s with
functions compatible with `Route` guards to the corresponding guard functions.
These functions will serve to aid in migrating off of the now deprecated
class-based guards, but also provide an easy avenue to still defining
guards as `Injectable` classes if that is desired.
PR Close#48709
41e2a68e30 added a `type` property on all router events, and added all type of events to the `Event` union type, but forgot to remove `RouterEvent`.
This removes the benefit of the `type` field, because it is not possible to write:
```
this.router.events.pipe(filter((event: Event): event is NavigationEnd => event.type === EventType.NavigationEnd)).subscribe(/*...*/);
```
as `RouterEvent` does not have a `type` field (hence TS complains).
This commit fixes the issue by removing `RouterEvent` from the union type.
BREAKING CHANGE: The `RouterEvent` type is no longer present in the `Event` union type representing all router event types. If you have code using something like `filter((e: Event): e is RouterEvent => e instanceof RouterEvent)`, you'll need to update it to `filter((e: Event|RouterEvent): e is RouterEvent => e instanceof RouterEvent)`.
PR Close#46061
The Router scroller only listens for NavigationEnd events. However, the
default behavior of the Router is to ignore navigations to the same URL.
This breaks the anchor scrolling when clicking on an anchor whose
fragment is already in the URL.
fixes#29099
BREAKING CHANGE: The `Scroll` event's `routerEvent` property may also be
a `NavigationSkipped` event. Previously, it was only a `NavigationEnd`
event.
PR Close#48025
In order to test components and services which depend on router navigations, such as `ActivatedRoute` instances, tests currently need to provide a fair bit of boilerplate _or_ they can set up a stub for `ActivatedRoute` and list it in the `providers` to override it in `TestBed`. This approach of stubbing the `ActivatedRoute` creates a situation that can easily cause the test to break. The stub often only mocks out the dependencies that the component/service _currently_ needs. This dependencies might change over time and break the test in an unexpected way. In addition, it is difficult to get the structure of `ActivatedRoute` exactly correct.
This change will allow unit tests to quickly set up routes, trigger real navigations in the Router, and get instances of component's to test along with real instances of `ActivatedRoute`. This all comes without needing to know that the component depends on `ActivatedRoute` at all. This becomes more important when considering that a component may be refactored in the future to use `@Input` rather than access data on the `ActivatedRoute` instance (see #18967). Tests which mock out `ActivatedRoute` would all break, but those which use `navigateForTest` would continue to work without needing any updates.
resolves#15779resolves#48608
PR Close#48552
Class and `InjectionToken`-based guards and resolvers are not as configurable,
are less re-usable, require more boilerplate, cannot be defined inline with the route,
and require more in-depth knowledge of Angular features (`Injectable`/providers).
In short, they're less powerful and more cumbersome.
In addition, continued support increases the API surface which in turn increases
bundle size, code complexity, the learning curve and API surface to teach,
maintenance cost, and cognitive load (needing to grok several different types
of information in a single place).
Lastly, supporting only the `CanXFn` types for guards and `ResolveFn` type
for resolvers in the `Route` interface will enable better code
completion and integration with TypeScript. For example, when writing an
inline functional resolver today, the function is typed as `any` and
does not provide completions for the `ResolveFn` parameters. By
restricting the type to only `ResolveFn`, in the example below
TypeScript would be able to correctly identify the `route` parameter as
`ActivatedRouteSnapshot` and when authoring the inline route, the
language service would be able to autocomplete the function parameters.
```
const userRoute: Route = {
path: 'user/:id',
resolve: {
"user": (route) => inject(UserService).getUser(route.params['id']);
}
};
```
Importantly, this deprecation only affects the support for class and
`InjectionToken` guards at the `Route` definition. `Injectable` classes
and `InjectionToken` providers are _not_ being deprecated in the general
sense. Functional guards are robust enough to even support the existing
class-based guards through a transform:
```
function mapToCanMatch(providers: Array<Type<{canMatch: CanMatchFn}>>): CanMatchFn[] {
return providers.map(provider => (...params) => inject(provider).canMatch(...params));
}
const route = {
path: 'admin',
canMatch: mapToCanMatch([AdminGuard]),
};
```
With regards to tests, because of the ability to map `Injectable`
classes to guard functions as outlined above, nothing _needs_ to change
if projects prefer testing guards the way they do today. Functional
guards can also be written in a way that's either testable with
`runInContext` or by passing mock implementations of dependencies.
For example:
```
export function myGuardWithMockableDeps(
dep1 = inject(MyService),
dep2 = inject(MyService2),
dep3 = inject(MyService3),
) { }
const route = {
path: 'admin',
canActivate: [() => myGuardWithMockableDeps()]
}
// test file
const guardResultWithMockDeps = myGuardWithMockableDeps(mockService1, mockService2, mockService3);
const guardResultWithRealDeps = TestBed.inject(EnvironmentInjector).runInContext(myGuardWithMockableDeps);
```
DEPRECATED: Class and `InjectionToken` guards and resolvers are
deprecated. Instead, write guards as plain JavaScript functions and
inject dependencies with `inject` from `@angular/core`.
PR Close#47924
`errorHandler` and `malformedUriErrorHandler` were already deprecated in
the Router class public API. This change updates the deprecation to
extend to `RouterModule.forRoot` configuration options.
PR Close#48551
`withNavigationErrorHandler` is a close replacement for the
`RouterModule.forRoot.errorHandler` / `Router.errorHandler`.
It provides a quick, short way for users to define a function to handle
`NavigationError` events.
PR Close#48551
The argument against this feature:
Firstly, this isn't a navigation strategy that's very commonly desired.
Secondly, the hash strategy is a location configuration in `@angular/common`
and you can use it outside of the Router or with any custom router implementations.
So while the net effect of using the router is that it updates the URL which is
controlled by the strategy, this feature provider doesn't necessarily need to
exist in the Router. The location strategy is an application-wide configuration
and affects anything that imports `Location`. Of course, the Router does this
in a few places but plenty of other things might as well.
The argument for this feature:
* Discoverability. While `LocationStrategy` is technically in `@angular/common`, the most
common use-case _is_ when using it with the Router.
* Precedence in the `RouterModule.forRoot([], {useHash: true})`
* Precedence in other routing libraries (`createWebHashHistory` in VueJS
and `HashRouter` in React, for example)
* The implementation of `withHashLocation` is much more clear than
`useHash` was. You can look at the function and see that all it's
doing is adding the `HashLocationStrategy` to the providers list.
resolves#48295 / #47986
PR Close#48301
The Router constructor and `setupRouter` factory mainly exist as a
legacy configuration. Since the Router's creation, the style in Angular
has evolved quite a bit. This commit eliminates and cleans up some
unnecessary comlicated code paths related to the router
constructor/factory.
Note that there are edits to the `setupTestingRouter` that could be seen
as breaking. However, it is not for several reasons:
1. The function is documented as a factory function. If used as
documented, the parameters should match what's available in DI
2. The function is totally unused by the Router itself and is not used
in g3 either. I believe it was made publicApi by an error when
updating documentation annotations long ago.
PR Close#48215
This option has already been removed from availability externally. Internally, the last use has been removed
for the type on Route.loadChildren. More testing will be necessary to verify nothing relies on the other
code paths.
PR Close#48292
The events observable is part of the lifecycle of a navigation. This should
be contained in the NavigationTransitions class rather than the Router.
This Subject is re-exported by the router as an observable to maintain
the public API
PR Close#48202
Andrew Scott