Merge branch 'main' into patch-1

Author: sergeysova

docs/api/create-route.md

@@ -23,8 +23,9 @@ import { createRoute } from 'atomic-router';
 export const homeRoute = createRoute();
 export const postRoute = createRoute<{ postId: string }>();
 
-homeRoute.open();
-postRoute.open({ postId: '123' });
+// prefer `sample` over imperative events call
+homeRoute.open(); // Effect
+postRoute.open({ postId: '123' }); // Effect<{ postId: string }>
 
 postRoute.$params.watch(console.log);
 ```
@@ -36,21 +37,29 @@ postRoute.$params.watch(console.log);
 Open the route with specified params and query
 
 ```ts
-postRoute.navigate({
-  params: { postId: '123' },
-  query: { foo: 'bar' },
-});
+sample({
+  clock: someThingHappened,
+  fn: () => ({
+    params: { postId: '123' },
+    query: { foo: 'bar' },
+  }),
+  target: postRoute.navigate,
+})
 // /posts/:postId -> /posts/123?foo=bar
 ```
 
 You can also add `replace: true` option to do `history.replace` instead of `history.push`:
 
 ```ts
-postRoute.navigate({
-  params: { postId: '123' },
-  query: { foo: 'bar' },
-  replace: true,
-});
+sample({
+  clock: someThingHappened,
+  fn: () => ({
+    params: { postId: '123' },
+    query: { foo: 'bar' },
+    replace: true,
+  }),
+  target: postRoute.navigate,
+})
 ```
 
 **Signature:** `Effect<RouteParamsAndQuery<RouteParams> & { replace?: boolean }, RouteParamsAndQuery<RouteParams>>`
@@ -60,7 +69,11 @@ postRoute.navigate({
 The same as `.navigate` but with params only
 
 ```ts
-postRoute.open({ postId: '123' });
+sample({
+  clock: somethingHappened,
+  fn: () => ({ postId: '123' }),
+  target: postRoute.open,
+})
 // /posts/:postId -> /posts/123
 ```
 
@@ -121,7 +134,7 @@ sample({
 Detects whether the route is currently opened or not.
 
 ```ts
-postRoute.$isOpened.getState(); // true/false
+postRoute.$isOpened; // true/false
 ```
 
 **Signature:** `Store<boolean>`
@@ -133,7 +146,7 @@ Current route params. These params are used as tokens for URL set in **router**.
 If route is not opened, `$params` will be `{}`
 
 ```ts
-postRoute.$params.getState(); // { postId: 123 }
+postRoute.$params; // { postId: 123 }
 ```
 
 **Signature:** `Store<RouteParams>`
@@ -145,7 +158,7 @@ Current route query. These are used to build [**Query String**](https://en.wikip
 If route is not opened, `$query` will be `{}`
 
 ```ts
-postRoute.$query.getState(); // { foo: 'bar' }
+postRoute.$query; // { foo: 'bar' }
 ```
 
 **Signature:** `Store<RouteQuery>`

docs/api/create-router-controls.md

@@ -25,39 +25,37 @@ Create controls:
 // @/shared/routing
 import { createRouterControls } from 'atomic-router';
 
-export const controls = createRouterControls()
+export const controls = createRouterControls();
 
-controls.$query   // Store<RouteQuery> Store with current query params
-controls.back     // Event<void> Trigger it to call history.back
-controls.forward  // Event<void> Trigger it to call history.forward
+controls.$query;   // StoreWritable<RouteQuery> Store with current query params
+controls.back;     // EventCallable<void> Trigger it to call history.back
+controls.forward;  // EventCallable<void> Trigger it to call history.forward
 ```
 
 Pass it to `createHistoryRouter`:
 ```ts
 // @/app/router
-import { createHistoryRouter } from 'atomic-router'
+import { createHistoryRouter } from 'atomic-router';
+import { controls } from '@/shared/routing';
 
-import { controls } from '@/shared/routing'
-
-const routes = [/* ... */]
+const routesMap = [/* ... */];
 
 export const router = createHistoryRouter({
-  routes,
-  controls
-})
+  routes: routesMap,
+  controls,
+});
 ```
 
 Use it anywhere:
 ```ts
 // @/pages/register
 import { sample, createEvent } from 'effector'
-
 import { controls } from '@/shared/routing'
 
-const cancelButtonPressed = createEvent<MouseEvent>()
+export const cancelButtonPressed = createEvent();
 
 sample({
   clock: cancelButtonPressed,
-  target: controls.back
-})
+  target: controls.back,
+});
 ```

docs/api/create-router.md

@@ -9,30 +9,37 @@ import { createHistoryRouter } from 'atomic-router';
 ## Usage
 
 ```ts
+import { sample } from 'effector';
 import { createHistoryRouter } from 'atomic-router';
 import { createBrowserHistory, createMemoryHistory } from 'history';
 
 import { homeRoute } from '@/pages/home';
 import { postsRoute } from '@/pages/posts';
 import { postRoute } from '@/pages/post';
 
-// 1. Define routes
-const routes = [
+import { appStarted } from '@/shared/init';
+
+// 1. Define routes and URLs map
+const routesMap = [
   { path: '/', route: homeRoute },
   { path: '/posts', route: postsRoute },
   { path: '/posts/:postId', route: postRoute },
 ];
 
 // 2. Create router
 const router = createHistoryRouter({
-  routes: routes,
+  routes: routesMap,
 });
 
 // 3. Create history
-const history = isSsr ? createMemoryHistory() : createBrowserHistory();
+const history = isSSR ? createMemoryHistory() : createBrowserHistory();
 
 // 4. Attach it to router
-router.setHistory(history);
+sample({
+  clock: appStarted,
+  fn: () => history,
+  target: router.setHistory,
+})
 ```
 
 ## Handling 404 errors

docs/api/query-sync.md

@@ -15,17 +15,17 @@ import { querySync } from 'atomic-router';
 ### Basic example
 
 ```ts
-import { createStore } from 'effector'
-import { createRoute, querySync } from 'atomic-router'
+import { createStore } from 'effector';
+import { querySync } from 'atomic-router';
 
-import { controls } from '@/shared/routing'
+import { controls } from '@/shared/routing';
 
-const $utmSource = createStore("")
+const $utmSource = createStore("");
 
 querySync({
   source: { utm_source: $utmSource },
-  controls
-})
+  controls,
+});
 ```
 
 This will 
@@ -37,20 +37,20 @@ This will
 You can pass `route` param if you want this sync to work only for a specific route:
 
 ```ts
-import { createStore } from 'effector'
-import { createRoute, querySync } from 'atomic-router'
+import { createStore } from 'effector';
+import { createRoute, querySync } from 'atomic-router';
 
-import { controls } from '@/shared/routing'
+import { controls } from '@/shared/routing';
 
-const searchRoute = createRoute()
+const searchRoute = createRoute();
 
-const $q = createStore("")
+const $q = createStore("");
 
 querySync({
   source: { q: $q },
-  route: searchRoute, 
-  controls
-})
+  route: searchRoute,
+  controls,
+});
 ```
 
 ### With a `clock`
@@ -59,29 +59,29 @@ If we don't want to spam route updates, there's a `clock` parameter.
 If it's passed, `querySync` will update route only when `clock` it's triggered:
 
 ```ts
-import { createRoute, querySync } from 'atomic-router'
-import { createStore, createEvent } from 'effector'
+import { createRoute, querySync } from 'atomic-router';
+import { createStore, createEvent } from 'effector';
 
-import { controls } from '@/shared/routing'
+import { controls } from '@/shared/routing';
 
-const canvasEditorRoute = createRoute()
+const canvasEditorRoute = createRoute();
 
-const canvasDragged = createEvent()
-const canvasDragEnded = createEvent()
+const canvasDragged = createEvent();
+const canvasDragEnded = createEvent();
 
-const $x = createStore('0')
-const $y = createStore('0')
+const $x = createStore('0');
+const $y = createStore('0');
 
-$x.on(canvasDragged, (_, { x }) => x)
+$x.on(canvasDragged, (_, { x }) => x);
 
-$y.on(canvasDragged, (_, { y }) => y)
+$y.on(canvasDragged, (_, { y }) => y);
 
 querySync({
   source: { x: $x, y: $y },
   route: canvasEditorRoute,
   clock: canvasDragEnded, 
-  controls
-})
+  controls,
+});
 ```
 
 ## `cleanup` parameter
@@ -97,10 +97,10 @@ querySync({
     // Strip empty params ('', 0, false, null)
     empty: true,
     // Preserves params that should've been removed by irerelevant/empty params
-    preserve: ['utm_source']
+    preserve: ['utm_source'],
   }, 
-  controls
-})
+  controls,
+});
 ```
 
 - `cleanup` is optional. Default strategy is `{ irrelevant: true, empty: false, preserve: [] }`

docs/examples/protected-route.md

@@ -32,12 +32,12 @@ Then, we can create a simple wrapper:
 
 ```ts
 // @/shared/route
-import { chainRoute, RouteInstance, RouteParamsAndQuery } from 'atomic-router';
+import { chainRoute, RouteParams, RouteInstance, RouteParamsAndQuery } from 'atomic-router';
 import { createEvent } from 'effector';
 
 import { $isAuthorized, tokenReceived } from '@/shared/auth';
 
-export function chainAuthorized<Params>(route: RouteInstance<Params>) {
+export function chainAuthorized<Params extends RouteParams>(route: RouteInstance<Params>) {
   const sessionCheckStarted = createEvent<RouteParamsAndQuery<Params>>();
 
   const alreadyAuthorized = sample({

docs/react/api/create-routes-view.md

@@ -25,8 +25,8 @@ import { router } from '@/app/routing';
 
 const RoutesView = createRoutesView({
   routes: [
-    { route: Home.route, view: HomePage.view },
-    { route: Post.route, view: PostPage.view },
+    { route: HomePage.route, view: HomePage.view },
+    { route: HomePage.route, view: PostPage.view },
   ],
   otherwise() {
     return <div>Page not found!</div>;

docs/react/scope.md

@@ -8,6 +8,7 @@ Example:
 // No scope
 import { Route, createRoutesView } from 'atomic-router-react';
 
-// Scoped imports (correct for SSR)
+// Scoped imports (correct for effector < 23 and atomic-router-react < 0.9)
+// On newer versions you can safely use `atomic-router-react` without `/scope` in the SSR or SPA
 import { Route, createRoutesView } from 'atomic-router-react/scope';
 ```