@tramvai/module-router 2.59.4 → 2.61.2

package/README.md

@@ -2,6 +2,8 @@
 
 Module for routing in the application. Exports two sub-modules: with client SPA transitions, and no-SPA.
 
+Link to complete Router documentation - https://tramvai.dev/docs/features/routing/overview/
+
 ## Installation
 
 You need to install `@tramvai/module-router`:
@@ -27,423 +29,6 @@ createApp({
 
 The module is based on the library [@tinkoff/router](references/libs/router.md)
 
-### Default Settings
-
-Next [settings](references/libs/router.md#constructor-options) are used
-
-- `trailingSlashes = true`
-- `mergeSlashes = true`
-
-### Navigation flow on the server
-
-![Diagram](/img/router/navigate-flow-server.drawio.svg)
-
-### Flow of the first navigation on the client
-
-![Diagram](/img/router/rehydrate-client.drawio.svg)
-
-### Flow of navigation on the client without SPA transitions
-
-![Diagram](/img/router/navigate-flow-client-no-spa.drawio.svg)
-
-### Flow of navigation on the client with SPA transitions
-
-![Diagram](/img/router/navigate-flow-client-spa.drawio.svg)
-
-## API
-
-### Static routes in the application
-
-Route description format:
-
-```ts
-const routes = [
-  {
-    // the name of the route is required
-    name: 'route1',
-    // the path of the route is required
-    path: '/route/a/',
-    // additional configs for the route
-    config: {
-      // layout component name
-      layoutComponent: 'layout',
-      // page component name
-      pageComponent: 'page',
-    },
-  },
-];
-```
-
-You can explicitly transfer a list of routes to routing when adding a router module:
-
-```ts
-import { createApp } from '@tramvai/core';
-import { SpaRouterModule } from '@tramvai/module-router';
-
-const routes = [
-  // ...
-];
-
-createApp({
-  modules: [
-    // ...,
-    SpaRouterModule.forRoot(routes),
-  ],
-});
-```
-
-Or separately with the `ROUTES_TOKEN` token (you can set it several times):
-
-```ts
-import { ROUTES_TOKEN } from '@tramvai/module-router';
-import { provide } from '@tramvai/core';
-
-const routesCommon = [
-  // ...
-];
-const routesSpecific = [
-  // ...
-];
-
-const providers = [
-  // ...,
-  provide({
-    provide: ROUTES_TOKEN,
-    multi: true,
-    useValue: routesCommon,
-  }),
-  provide({
-    provide: ROUTES_TOKEN,
-    multi: true,
-    useValue: routesSpecific,
-  }),
-];
-```
-
-### PAGE_SERVICE_TOKEN
-
-Service wrapper for working with routing. Serves to hide routing work and is the preferred way of routing work.
-
-Methods:
-
-- `getCurrentRoute()` - get the current route
-- `getCurrentUrl()` - object-result of parsing the current url
-- `getConfig()` - get the config of the current page
-- `getContent()` - get content for the current page
-- `getMeta()` - get the meta for the current page
-- `navigate(options)` - navigation to a new page [more](references/libs/router.md)
-- `updateCurrentRoute(options)` - update the current route with new parameters [more](references/libs/router.md)
-- `back()` - go back through history
-- `forward()` - go forward through history
-- `go(to)` - go to the specified delta by history
-- `addComponent(name, component)` - add new component to current page into ComponentRegistry
-- `getComponent(name)` - get component from current page components from ComponentRegistry
-
-### RouterStore
-
-Store that stores information about the current and previous routes.
-
-Properties:
-
-- `currentRoute` - current route
-- `currentUrl` - current url
-- `previousRoute` - previous route
-- `previousUrl` - previous url
-
-### ROUTER_GUARD_TOKEN
-
-Allows you to block or redirect the transition to the page under certain conditions. See [@tinkoff/router](/references/libs/router.md)
-
-### Redirects
-
-Redirects can be done via [guards](#ROUTER_GUARD_TOKEN) or explicitly via the `redirect` property in the route.
-
-```ts
-const routes = [
-  // ...,
-  {
-    name: 'redirect',
-    path: '/from/',
-    redirect: '/to/',
-  },
-];
-```
-
-### Not Found route
-
-The route used if no matches were found for the current page, can be specified in a special way in the list of routes.
-
-```ts
-const route = [
-  // ...other routes,
-  {
-    name: 'not-found',
-    path: '*',
-    config: {
-      pageComponent: 'notfoundComponentName',
-    },
-  },
-];
-```
-
-### ROUTE_RESOLVE_TOKEN
-
-Allows you to define an asynchronous function that returns a route object that will be called if no suitable static route was found in the application.
-
-### ROUTE_TRANSFORM_TOKEN
-
-Transformer function for application routes (set statically and those that will be loaded via ROUTE_RESOLVE_TOKEN)
-
-### Method of setting when actions should be performed during SPA transitions
-
-By default, SPA transitions execute actions after defining the next route, but before the actual transition, which allows the page to be displayed immediately with new data, but can cause a noticeable visual lag if the actions are taken long enough.
-
-It is possible to change the behavior and make the execution of actions after the transition itself. Then, when developing components, you will need to take into account that data will be loaded as it becomes available.
-
-Configurable explicitly when using the routing module:
-
-```ts
-import { createApp } from '@tramvai/core';
-import { SpaRouterModule } from '@tramvai/module-router';
-
-createApp({
-  modules: [
-    // ...,
-    SpaRouterModule.forRoot([], {
-      spaActionsMode: 'after', // default is 'before'
-    }),
-  ],
-});
-```
-
-or through token `ROUTER_SPA_ACTIONS_RUN_MODE_TOKEN`:
-
-```ts
-import { ROUTER_SPA_ACTIONS_RUN_MODE_TOKEN } from '@tramvai/module-router';
-import { provide } from '@tramvai/core';
-
-const providers = [
-  // ...,
-  provide({
-    provide: ROUTER_SPA_ACTIONS_RUN_MODE_TOKEN,
-    useValue: 'after',
-  }),
-];
-```
-
-## How to
-
-### Working with navigation in providers and actions
-
-In this case, it is best to use the [PAGE_SERVICE_TOKEN](#page_service_token)
-
-```ts
-import { provide, declareAction } from '@tramvai/core';
-import { PAGE_SERVICE_TOKEN } from '@tramvai/module-router';
-
-const provider = provide({
-  provide: 'token',
-  useFactory: ({ pageService }) => {
-    if (pageService().getCurrentUrl().pathname === '/test/') {
-      return pageService.navigate({ url: '/redirect/', replace: true });
-    }
-  },
-  deps: {
-    pageService: PAGE_SERVICE_TOKEN,
-  },
-});
-
-const action = declareAction({
-  name: 'action',
-  fn() {
-    if (this.deps.pageService.getConfig().pageComponent === 'pageComponent') {
-      return this.deps.pageService.updateCurrentRoute({ query: { test: 'true' } });
-    }
-  },
-  deps: {
-    pageService: PAGE_SERVICE_TOKEN,
-  },
-});
-```
-
-### Working with navigation in React components
-
-You can work with routing inside React components using hooks and components - `useNavigate` and `useRoute` from the [@tinkoff/router](references/libs/router.md#интеграция-с-react)
-
-<p>
-<details>
-<summary>An example of working with navigation in the application</summary>
-
-@inline ../../../examples/how-to/router-navigate/index.tsx
-
-</details>
-</p>
-
-#### Link
-
-A wrapper for a react component that makes it clickable
-
-> If the react component is passed to the Link as children, then this passed component will be rendered and the `href`, `onClick` props will be passed as props to that component and they should be used to make the navigation. Otherwise, the `<a>` tag will be rendered with children as a child.
-> Your passed component need to be wrapped in the `forwardRef` for routes assets prefetching.
-
-```ts
-import { Link } from '@tramvai/module-router';
-import CustomLink from '@custom-scope/link';
-
-export const Component = () => {
-  return (
-    <Link url="/test/">
-      <CustomLink />
-    </Link>
-  );
-};
-
-export const WrapLink = () => {
-  return <Link url="/test/">Click me</Link>;
-};
-```
-
-##### Page resources prefetch
-
-`Link` component will try to prefetch resources for passed `url`, if this `url` is handled by the application router.
-
-It will help to make subsequent page-loads faster because target page assets already be saved in browser cache.
-
-How it works:
-
-- Component determines when it is in the viewport (using `Intersection Observer`)
-- waits until the browser is idle (using `requestIdleCallback`)
-- checks if the user isn't on a slow connection (using `navigator.connection.effectiveType`) or has data-saver enabled (using `navigator.connection.saveData`)
-- triggers page resources (js, css) prefetching
-
-Main reference for this feature - [quicklink](https://github.com/GoogleChromeLabs/quicklink) library.
-
-If you want to disable this behaviour, pass `prefetch={false}` property.
-
-```tsx
-export const WrapLink = () => {
-  return <Link url="/test/" prefetch={false}>Click me</Link>;
-};
-```
-
-### How to set static routes
-
-[RouterModule](references/modules/router/base.md) allows you to add new routes when configuring your application. The second way is to pass static routes to DI via the `ROUTES_TOKEN` token.
-
-<p>
-<details>
-<summary>An example of adding static routes to an application</summary>
-
-@inline ../../../examples/how-to/router-static-routes/index.tsx
-
-</details>
-</p>
-
-### How to set Route Guard
-
-`ROUTER_GUARD_TOKEN` is set as an asynchronous function, which allows you to perform various actions and influence the routing behavior.
-
-<p>
-<details>
-<summary>Example router guards job in application</summary>
-
-@inline ../../../examples/how-to/router-guards/index.tsx
-
-</details>
-</p>
-
-### How to add transition hooks
-
-[Transition hooks](references/libs/router.md#transition-hooks) allows to subscribe on different steps of the transition
-
-1. Get router instance with `ROUTER_TOKEN` token
-2. Use methods `registerHook`, `registerSyncHook` to add new hooks to the router
-3. Registration should happen as soon as possible so appropriate line is `customerStart` as it executes before navigation happens.
-
-### How to set the Not found route
-
-The Not found route is used if the corresponding route is not found for the url.
-
-Such a route is specified in the list of routes with the special `*` character in the `path` property.
-
-<p>
-<details>
-<summary>An example of setting a Not Found route in an application</summary>
-
-@inline ../../../examples/how-to/router-not-found/index.tsx
-
-</details>
-</p>
-
-### How to change Not found route response status
-
-By default, responses for the Not found route return a status of 200. You can change status in custom Route Guard, by using `RESPONSE_MANAGER_TOKEN`.
-
-<p>
-<details>
-<summary>An example of changing a Not Found route response status</summary>
-
-@inline ../../../examples/how-to/router-not-found-custom-status/index.tsx
-
-</details>
-</p>
-
-### How to change response status in actions
-
-For example, you make a important request in action, and if this request will fail, application need to return 500 or 404 status.
-
-Page actions running after router navigation flow, when route is completely resolved. You can change status by using `RESPONSE_MANAGER_TOKEN`. If you want to prevent page component rendering, you can throw `NotFoundError` from `@tinkoff/errors` library.
-
-<p>
-<details>
-<summary>An example of changing response status in actions</summary>
-
-@inline ../../../examples/how-to/router-action-error/index.tsx
-
-</details>
-</p>
-
-### Testing
-
-#### Testing ROUTER_GUARD_TOKEN extensions
-
-If you have a module or providers that define `ROUTER_GUARD_TOKEN`, then it will be convenient to use special utilities to test them separately
-
-```ts
-import { ROUTER_GUARD_TOKEN } from '@tramvai/tokens-router';
-import { testGuard } from '@tramvai/module-router/tests';
-import { CustomModule } from './module';
-import { providers } from './providers';
-
-describe('router guards', () => {
-  it('should redirect from guard', async () => {
-    const { router } = testGuard({
-      providers,
-    });
-
-    await router.navigate('/test/');
-
-    expect(router.getCurrentUrl()).toMatchObject({
-      path: '/redirect/',
-    });
-  });
-
-  it('should block navigation', async () => {
-    const { router } = testGuard({
-      modules: [CustomModule],
-    });
-
-    expect(router.getCurrentUrl()).toMatchObject({ path: '/' });
-
-    await router.navigate('/test/').catch(() => null);
-
-    expect(router.getCurrentUrl()).toMatchObject({
-      path: '/',
-    });
-  });
-});
-```
-
 ## Exported tokens
 
 [link](references/tokens/router.md)

package/lib/index.browser.js

@@ -83,7 +83,8 @@ const loadBundle = ({ bundleManager, logger, actionRegistry, responseManager, di
                 bundle,
                 pageComponent,
             });
-            // если бандл не найдён, то всё ок мы должны вернуть 404 на сервере, а на клиенте просто загрузить новую страницу
+            // если бандл не найден, то всё ок и мы должны вернуть 404 на сервере,
+            // а на клиенте просто загрузить новую страницу
             responseManager.setStatus(404);
             return false;
         }

package/lib/index.es.js

@@ -84,7 +84,8 @@ const loadBundle = ({ bundleManager, logger, actionRegistry, responseManager, di
                 bundle,
                 pageComponent,
             });
-            // если бандл не найдён, то всё ок мы должны вернуть 404 на сервере, а на клиенте просто загрузить новую страницу
+            // если бандл не найден, то всё ок и мы должны вернуть 404 на сервере,
+            // а на клиенте просто загрузить новую страницу
             responseManager.setStatus(404);
             return false;
         }

package/lib/index.js

@@ -96,7 +96,8 @@ const loadBundle = ({ bundleManager, logger, actionRegistry, responseManager, di
                 bundle,
                 pageComponent,
             });
-            // если бандл не найдён, то всё ок мы должны вернуть 404 на сервере, а на клиенте просто загрузить новую страницу
+            // если бандл не найден, то всё ок и мы должны вернуть 404 на сервере,
+            // а на клиенте просто загрузить новую страницу
             responseManager.setStatus(404);
             return false;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tramvai/module-router",
-  "version": "2.59.4",
+  "version": "2.61.2",
   "description": "",
   "main": "lib/index.js",
   "browser": {
@@ -27,26 +27,26 @@
   },
   "dependencies": {
     "@tinkoff/errors": "0.3.5",
-    "@tinkoff/router": "0.2.6",
+    "@tinkoff/router": "0.2.7",
     "@tinkoff/url": "0.8.4",
-    "@tramvai/react": "2.59.4",
-    "@tramvai/tokens-child-app": "2.59.4",
-    "@tramvai/tokens-render": "2.59.4",
-    "@tramvai/tokens-router": "2.59.4",
-    "@tramvai/tokens-server": "2.59.4",
-    "@tramvai/experiments": "2.59.4"
+    "@tramvai/react": "2.61.2",
+    "@tramvai/tokens-child-app": "2.61.2",
+    "@tramvai/tokens-render": "2.61.2",
+    "@tramvai/tokens-router": "2.61.2",
+    "@tramvai/tokens-server": "2.61.2",
+    "@tramvai/experiments": "2.61.2"
   },
   "peerDependencies": {
     "@tinkoff/utils": "^2.1.2",
-    "@tramvai/cli": "2.59.4",
-    "@tramvai/core": "2.59.4",
-    "@tramvai/module-log": "2.59.4",
-    "@tramvai/module-server": "2.59.4",
-    "@tramvai/papi": "2.59.4",
-    "@tramvai/state": "2.59.4",
-    "@tramvai/test-helpers": "2.59.4",
-    "@tramvai/test-mocks": "2.59.4",
-    "@tramvai/tokens-common": "2.59.4",
+    "@tramvai/cli": "2.61.2",
+    "@tramvai/core": "2.61.2",
+    "@tramvai/module-log": "2.61.2",
+    "@tramvai/module-server": "2.61.2",
+    "@tramvai/papi": "2.61.2",
+    "@tramvai/state": "2.61.2",
+    "@tramvai/test-helpers": "2.61.2",
+    "@tramvai/test-mocks": "2.61.2",
+    "@tramvai/tokens-common": "2.61.2",
     "@tinkoff/dippy": "0.8.11",
     "react": "*",
     "tslib": "^2.4.0"