reactive-route 0.0.1-alpha.26 → 0.0.1-alpha.28

package/vitepress/.vitepress/config.mts

@@ -0,0 +1,72 @@
+import { defineConfig } from 'vitepress';
+import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons';
+
+export default defineConfig({
+  title: 'Reactive Route',
+  description: 'Config-based routing for different frameworks',
+  base: '/reactive-route/',
+  head: [['link', { rel: 'icon', href: '/file.svg' }]],
+  markdown: {
+    config(md) {
+      md.use(groupIconMdPlugin);
+    },
+  },
+  vite: {
+    plugins: [groupIconVitePlugin()],
+  },
+  themeConfig: {
+    logo: '/file.svg',
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/', activeMatch: '/guide/' },
+      { text: 'Examples', link: '/examples/react', activeMatch: '/examples/' },
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: 'What is Reactive Route?', link: '/guide/' },
+            { text: 'Getting Started', link: '/guide/getting-started' },
+          ],
+        },
+        {
+          text: 'Core Concepts',
+          items: [
+            { text: 'Routes Configuration', link: '/guide/routes-configuration' },
+            { text: 'Router Configuration', link: '/guide/router-configuration' },
+            { text: 'Router Component', link: '/guide/router-component' },
+            { text: 'SSR', link: '/guide/ssr' },
+            { text: 'Advanced', link: '/guide/advanced' },
+          ],
+        },
+        {
+          text: 'Framework Integration',
+          items: [
+            { text: 'React', link: '/guide/react' },
+            { text: 'Preact', link: '/guide/preact' },
+            { text: 'Solid.js', link: '/guide/solid' },
+          ],
+        },
+      ],
+      '/examples/': [
+        {
+          text: 'Examples',
+          items: [
+            { text: 'React', link: '/examples/react' },
+            { text: 'Preact', link: '/examples/preact' },
+            { text: 'Solid.js', link: '/examples/solid' },
+          ],
+        },
+      ],
+    },
+    search: {
+      provider: 'local',
+    },
+    socialLinks: [{ icon: 'github', link: 'https://github.com/dkazakov8/reactive-route' }],
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2023-present Dmitry Kazakov',
+    },
+  },
+});

package/vitepress/.vitepress/theme/custom.css

@@ -0,0 +1,9 @@
+:root {
+  --vp-c-brand-1: #6231b6;
+  --vp-button-brand-bg: #6231b6;
+  --vp-button-brand-hover-bg: #542a9c;
+}
+
+:root.dark {
+  --vp-code-color: #bb9ee1;
+}

package/vitepress/.vitepress/theme/index.ts

@@ -0,0 +1,5 @@
+import Theme from 'vitepress/theme';
+import 'virtual:group-icons.css';
+import './custom.css';
+
+export default Theme;

package/vitepress/examples/preact.md

@@ -0,0 +1,22 @@
+# Preact Example
+
+To use it follow these steps:
+
+```shell
+git clone https://github.com/dkazakov8/reactive-route.git
+cd ./reactive-route/examples/preact
+pnpm install
+```
+
+This example is configured to use `pnpm` by default, but you may choose your own package manager
+by editing `packageManager` field in `package.json`.
+
+Next, choose the mode and reactivity system to start:
+
+- `pnpm run mobx` - CSR (Client rendering only) for MobX
+- `pnpm run observable` - CSR (Client rendering only) for Observable
+- `pnpm run ssr-mobx` - SSR for MobX
+- `pnpm run ssr-observable` - SSR for Observable
+
+Note, that wrapping of components in `observer` is made by the ESBuild bundler in this example.
+In your own projects, remember to follow the relevant [Framework Integration](/guide/preact).

package/vitepress/examples/react.md

@@ -0,0 +1,22 @@
+# React Example
+
+To use it follow these steps:
+
+```shell
+git clone https://github.com/dkazakov8/reactive-route.git
+cd ./reactive-route/examples/react
+pnpm install
+```
+
+This example is configured to use `pnpm` by default, but you may choose your own package manager
+by editing `packageManager` field in `package.json`.
+
+Next, choose the mode and reactivity system to start:
+
+- `pnpm run mobx` - CSR (Client rendering only) for MobX
+- `pnpm run observable` - CSR (Client rendering only) for Observable
+- `pnpm run ssr-mobx` - SSR for MobX
+- `pnpm run ssr-observable` - SSR for Observable
+
+Note, that wrapping of components in `observer` is made by the ESBuild bundler in this example.
+In your own projects, remember to follow the relevant [Framework Integration](/guide/react).

package/vitepress/examples/solid.md

@@ -0,0 +1,21 @@
+# Solid.js Example
+
+To use it follow these steps:
+
+```shell
+git clone https://github.com/dkazakov8/reactive-route.git
+cd ./reactive-route/examples/solid
+pnpm install
+```
+
+This example is configured to use `pnpm` by default, but you may choose your own package manager
+by editing `packageManager` field in `package.json`.
+
+Next, choose the mode and reactivity system to start:
+
+- `pnpm run solid` - CSR (Client rendering only) for Solid.js reactivity
+- `pnpm run mobx` - CSR (Client rendering only) for MobX
+- `pnpm run observable` - CSR (Client rendering only) for Observable
+- `pnpm run ssr-solid` - SSR for Solid.js reactivity
+- `pnpm run ssr-mobx` - SSR for MobX
+- `pnpm run ssr-observable` - SSR for Observable

package/vitepress/file.svg

@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="32"
+   height="32"
+   viewBox="0 0 32 32"
+   version="1.1"
+   id="svg1"
+   inkscape:version="1.4.2 (f4327f4, 2025-05-13)"
+   sodipodi:docname="ver-5.svg"
+   inkscape:export-filename="2.svg"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="px"
+     showgrid="true"
+     inkscape:zoom="4"
+     inkscape:cx="28.75"
+     inkscape:cy="45"
+     inkscape:window-width="1920"
+     inkscape:window-height="1009"
+     inkscape:window-x="-8"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1">
+    <inkscape:grid
+       id="grid1"
+       units="px"
+       originx="0"
+       originy="0"
+       spacingx="1"
+       spacingy="1"
+       empcolor="#0099e5"
+       empopacity="0.30196078"
+       color="#0099e5"
+       opacity="0.14901961"
+       empspacing="4"
+       enabled="true"
+       visible="true" />
+  </sodipodi:namedview>
+  <defs
+     id="defs1" />
+  <g
+     inkscape:label="Слой 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <path
+       id="rect1"
+       style="fill:#000000;fill-opacity:1;stroke-width:0;stroke-dasharray:none"
+       d="m 3,2 v 4 4 2 h 8 V 8 6 h 11 v 8 H 3 v 4 10 2 h 8 v -4 -8 h 16 v -4 -1 h 2 V 7 H 27 V 6 2 Z m 19,24 v 4 h 7 v -4 z" />
+    <rect
+       style="fill:#000000;fill-opacity:1;stroke-width:0;stroke-dasharray:none"
+       id="rect113"
+       width="8"
+       height="4"
+       x="19"
+       y="20" />
+    <rect
+       style="fill:#000000;fill-opacity:1;stroke-width:0;stroke-dasharray:none"
+       id="rect114"
+       width="1"
+       height="4"
+       x="21"
+       y="26" />
+  </g>
+</svg>

package/vitepress/guide/advanced.md

@@ -0,0 +1,131 @@
+# Advanced
+
+## Redirects chain
+
+This library fully supports unlimited redirects in SPA / SSR.
+
+```typescript [routes.ts]
+const routes = createRoutes({
+  one: {
+    path: '/1',
+    oader: () => import('./pages/one'),
+  },
+  two: {
+    path: '/2',
+    loader: () => import('./pages/two'),
+    async beforeEnter(config) {
+      return config.redirect({ route: 'one' });
+    },
+  },
+  three: {
+    path: '/3',
+    loader: () => import('./pages/three'),
+    async beforeEnter(config) {
+      return config.redirect({ route: 'two' });
+    },
+  },
+  four: {
+    path: '/4',
+    loader: () => import('./pages/four'),
+    async beforeEnter(config) {
+      return config.redirect({ route: 'three' });
+    },
+  },
+  
+  // Other routes
+});
+```
+
+In this case if user goes to `/4` he will be redirected to `/3` then `/2` then `/1`. 
+Browser's history and `router.routesHistory` will only have `['/1']`. 
+Also, chunks for pages four, three, two will not be loaded if you configured async chunks in your Bundler.
+
+## Watch and react to params / query changes
+
+`router.currentRoute` is an observable, so you can use it inside autorun / reaction / effect of your stack.
+
+```tsx
+import { TypeCurrentRoute } from 'reactive-route';
+import { routes } from 'routes';
+
+function MyComponent() {
+  const { router } = useContext(StoreContext);
+  
+  const currentRoute = router.currentRoute as TypeCurrentRoute<typeof routes.tabs>;
+
+  // React + MobX way
+  useEffect(() => {
+    const disposer = autorun(() => {
+      // Always check the name. Because after redirecting the currentRoute 
+      // will change, but this reaction is still alive, and the next route 
+      // may not have params and query at all!
+      if (currentRoute.name !== 'tabs') return;
+      
+      console.log(currentRoute.params.tab, currentRoute.query.foo);
+    })
+
+    return () => disposer();
+  }, []);
+  
+  if (router.currentRoute.name !== 'tabs') return null;
+
+  if (router.currentRoute.params.tab === 'dashboard') {
+    return <Dashboard />
+  }
+
+  if (router.currentRoute.params.tab === 'table') {
+    return <Table />
+  }
+
+  return <ModeNotFound />;
+}
+```
+
+## Prevent rerendering if pageId is the same
+
+To Do
+
+## Modular exports
+
+All the exports from your pages are written to the route config. You may read them in 
+`beforeSetPageComponent` prop of the `Router`. For example, when you use code-splitting and SSR 
+it's a good practice to extend some global RootStore or IoC container with page's stores:
+
+```tsx [pages/Home.tsx]
+export const homeStore = {
+  foo: 'bar'
+}
+
+export default function Home() {
+  const { modularStores } = useContext(StoreContext);
+
+  return `Home ${modularStores.homeStore.foo}`;
+}
+```
+
+```tsx [components/Router.tsx]
+export function Router() {
+  const { router, modularStores } = useContext(StoreContext);
+
+  return (
+    <RouterLib
+      routes={routes}
+      router={router}
+      beforeSetPageComponent={(route) => {
+        if (route.otherExports?.homeStore) {
+          modularStores.homeStore = route.otherExports.homeStore;
+        }
+      }}
+      beforeUpdatePageComponent={() => {
+        if (modularStores.homeStore) {
+          modularStores.homeStore.destroy();
+          modularStores.homeStore = null;
+        }
+      }}
+    />
+  );
+}
+```
+
+This way on hydration server can serialize `modularStores.homeStore` and the client can easily
+hydrate it on the first render. This mechanism can also be used in other useful scenarios.

package/vitepress/guide/getting-started.md

@@ -0,0 +1,139 @@
+# Getting Started
+
+This guide will help you set up Reactive Route in your application and create your first routes.
+
+### Installation
+
+The package includes the core router, React and Solid.js implementations, and adapters for different state management solutions.
+Note that every combination requires corresponding libraries to be installed in your project.
+
+::: code-group
+```sh [npm]
+npm i reactive-route
+```
+
+```sh [yarn]
+yarn add reactive-route
+```
+
+```sh [pnpm]
+pnpm add reactive-route
+```
+:::
+
+### Modules map
+
+```typescript
+import { createRoutes, createRouter } from 'reactive-route';
+import { Router } from 'reactive-route/react';
+import { Router } from 'reactive-route/solid';
+import { Router } from 'reactive-route/preact';
+import { adapters } from 'reactive-route/adapters/mobx-react';
+import { adapters } from 'reactive-route/adapters/mobx-preact';
+import { adapters } from 'reactive-route/adapters/mobx-solid';
+import { adapters } from 'reactive-route/adapters/solid';
+import { adapters } from 'reactive-route/adapters/kr-observable-react';
+import { adapters } from 'reactive-route/adapters/kr-observable-preact';
+import { adapters } from 'reactive-route/adapters/kr-observable-solid';
+```
+
+## Basic Setup
+
+### 1. Create a Router Store and Define Your Routes
+
+First, create a router store using the `createRouter` function and 
+your routes configuration using the `createRoutes` function:
+
+```typescript [router.ts]
+import { createRoutes, createRouter } from 'reactive-route';
+import { adapters } from 'reactive-route/adapters/{reactive-system}';
+
+const routes = createRoutes({
+  home: {
+    path: '/',
+    loader: () => import('./pages/home'),
+  },
+  user: {
+    path: '/user/:id',
+    params: {
+      id: (value) => /^\d+$/.test(value),
+    },
+    query: {
+      phone: (value) => value.length > 0 && value.length < 10,
+    },
+    loader: () => import('./pages/user'),
+  },
+  notFound: {
+    path: '/not-found',
+    props: { errorCode: 404 },
+    loader: () => import('./pages/error'),
+  },
+  internalError: {
+    path: '/internal-error',
+    props: { errorCode: 500 },
+    loader: () => import('./pages/error'),
+  },
+});
+
+//  If you prefer Context and SSR
+export function getRouter() {
+  return createRouter({ routes, adapters });
+}
+
+//  If you prefer singletons
+export const router = createRouter({ routes, adapters })
+```
+
+Pages `notFound` and `internalError` are required for error handling in the library.
+
+The recommended way is to use Context to pass it to UI components to avoid circular dependencies,
+multiple instances and add the possibility of SSR.
+
+```typescript [StoreContext.tsx]
+import { createContext } from '{ui-library}';
+
+import { getRouter } from './router';
+
+export const StoreContext = createContext(
+  undefined as unknown as { router: ReturnType<typeof getRouter> }
+);
+```
+
+### 2. Set Up the Router Component
+
+Create a custom Router component that uses the context to access the router store:
+
+```tsx [components/Router.tsx]
+import { useContext } from '{ui-library}';
+import { Router as RouterLib } from 'reactive-route/{ui-library}';
+
+import { StoreContext } from './StoreContext';
+
+export function Router() {
+  const { router } = useContext(StoreContext);
+
+  return <RouterLib router={router} />;
+}
+```
+
+### 3. Initialize the router and render
+
+```tsx [client.tsx]
+import { StoreContext } from './StoreContext';
+import { getRouterStore } from './router';
+import { Router } from './components/Router';
+
+const router = getRouterStore();
+
+await router.restoreFromURL({
+  pathname: location.pathname + location.search,
+});
+
+// the implementation is dependent on the UI library
+render(
+  element,
+  <StoreContext.Provider value={{ router }}>
+    <Router />
+  </StoreContext.Provider>
+);
+```

package/vitepress/guide/index.md

@@ -0,0 +1,44 @@
+# What is Reactive Route?
+
+![coverage](https://github.com/dkazakov8/reactive-route/blob/master/assets/coverage.svg)
+[![npm](https://img.shields.io/npm/v/reactive-route)](https://www.npmjs.com/package/reactive-route)
+![size-core](https://github.com/dkazakov8/reactive-route/blob/master/assets/core.svg)
+![size-react](https://github.com/dkazakov8/reactive-route/blob/master/assets/react.svg)
+![size-preact](https://github.com/dkazakov8/reactive-route/blob/master/assets/preact.svg)
+![size-solid](https://github.com/dkazakov8/reactive-route/blob/master/assets/solid.svg)
+
+Reactive Route is a lightweight, flexible, and reactive router for JavaScript applications.
+
+### Framework and State Management Agnostic
+
+The core routing logic is framework-agnostic, allowing it to be used with different UI frameworks and 
+state management solutions. Currently, Reactive Route provides official implementations for:
+
+- React + MobX
+- React + Observable
+- Preact (no compat) + MobX
+- Preact (no compat) + Observable
+- Solid.js + Solid.js reactivity
+- Solid.js + MobX
+- Solid.js + Observable
+- Vue + Vue reactivity (package in development)
+
+### Key Advantages
+
+Reactive Route offers several advantages that make it a powerful choice for routing in modern web applications:
+
+- **Lifecycle Hooks**: Built-in `beforeEnter` and `beforeLeave` hooks allow you to control navigation flow, perform authentication checks, load data, and handle unsaved changes.
+
+- **Dynamic Component Loading**: Supports dynamically loaded components through async imports (e.g., `() => import('./pages/Home')`), enabling code splitting and improving application performance.
+
+- **Modular Data Integration**: Supports dynamically loaded modular stores and other data for pages, making state management more organized and efficient.
+
+- **Server-Side Rendering**: Full SSR support for all the supported frameworks, ensuring optimal performance and SEO benefits.
+
+- **Parameter Validation**: Ensures that every dynamic parameter from the URL has a validator, preventing invalid routes and improving application robustness.
+
+- **TypeScript Integration**: Comprehensive TypeScript support for routes, dynamic parameters, and search queries, providing excellent developer experience and type safety.
+
+- **Separation of Concerns**: Functions as a centralized separate layer, eliminating the need for markup like `<Route path="..." />` inside components and keeping your component tree clean.
+
+In the following sections, we'll explore how to install and use Reactive Route in your applications.

package/vitepress/guide/preact.md

@@ -0,0 +1,33 @@
+# Preact Integration
+
+## Mobx
+
+The relevant imports are as follows
+
+```typescript
+import { Router } from 'reactive-route/preact';
+import { adapters } from 'reactive-route/adapters/mobx-preact';
+```
+
+You should ensure that packages `mobx`, `mobx-react-lite` are installed.
+
+If you use `mobx-react` instead of `mobx-react-lite` you may create an alias in your bundler or
+pass your own adapters with similar implementation but `observer` taken from `mobx-react`.
+
+Be sure to wrap your components which read observable router parameters into `observer` (if you use
+MobX this is presumably already done).
+
+## Observable
+
+The relevant imports are as follows
+
+```typescript
+import { Router } from 'reactive-route/preact';
+import { adapters } from 'reactive-route/adapters/kr-observable-preact';
+```
+
+You should ensure that package `kr-observable` is installed.
+
+Be sure to wrap your components which read observable router parameters into `observer` (if you use
+Observable this is presumably already done).
+

package/vitepress/guide/react.md

@@ -0,0 +1,33 @@
+# React Integration
+
+## Mobx
+
+The relevant imports are as follows
+
+```typescript
+import { Router } from 'reactive-route/react';
+import { adapters } from 'reactive-route/adapters/mobx-react';
+```
+
+You should ensure that packages `mobx`, `mobx-react-lite` are installed.
+
+If you use `mobx-react` instead of `mobx-react-lite` you may create an alias in your bundler or
+pass your own adapters with similar implementation but `observer` taken from `mobx-react`.
+
+Be sure to wrap your components which read observable router parameters into `observer` (if you use
+MobX this is presumably already done).
+
+## Observable
+
+The relevant imports are as follows
+
+```typescript
+import { Router } from 'reactive-route/react';
+import { adapters } from 'reactive-route/adapters/kr-observable-react';
+```
+
+You should ensure that package `kr-observable` is installed.
+
+Be sure to wrap your components which read observable router parameters into `observer` (if you use
+Observable this is presumably already done).
+

package/vitepress/guide/router-component.md

@@ -0,0 +1,67 @@
+# Router Component Configuration
+
+The router is the central piece that manages the state of the router and provides methods for navigation. It's created using the `createRouter` function.
+
+## Creating a Router Component
+
+```tsx [components/Router.tsx]
+import { useContext } from '{ui-library}';
+import { Router as RouterLib } from 'reactive-route/{ui-library}';
+
+import { StoreContext } from './StoreContext';
+
+export function Router() {
+  const { router } = useContext(StoreContext);
+
+  return <RouterLib router={router} />;
+}
+```
+
+The `Router` accepts these props:
+
+| Property                    | Type                                   | Description                                                                                                      |
+|-----------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| `router`                    | `ReturnType<typeof createRouter>`      | The router configuration                                                                                         |
+| `beforeMount`               | `() => void`                           | This function is called once on Router Component initiation, before any rendering (optional)                     |
+| `beforeUpdatePageComponent` | `() => void`                           | This function is called when page component is changed, before `beforeSetPageComponent` and rendering (optional) |
+| `beforeSetPageComponent`    | `(componentConfig: TypeRoute) => void` | This function is called when page component is loaded, before rendering (optional)                               |
+
+```tsx [components/Router.tsx]
+import { useContext } from '{ui-library}';
+import { Router as RouterLib } from 'reactive-route/{ui-library}';
+
+import { routes } from '../routes';
+import { StoreContext } from './StoreContext';
+
+export function Router() {
+  const { router } = useContext(StoreContext);
+
+  return (
+    <RouterLib
+      routes={routes}
+      router={router}
+      beforeMount={() => {
+        // Router just mounted
+      }}
+      beforeUpdatePageComponent={() => {
+        // some new page will be rendered soon (not called on first render!)
+        // You may stop async actions and clear modular stores here
+  
+        cancelExecutingApi();
+        cancelExecutingActions();
+        someStore.reset();
+      }}
+      beforeSetPageComponent={(route) => {
+        // some page will be rendered soon
+        // You may initiate modular stores here
+        
+        console.log(route); // shows which page will be loaded
+        
+        const myPageStore = route.otherExports?.myPageStore;
+      }}
+    />
+  );
+}
+```
+
+There are more examples of Router Component lifecycle in the [Advanced](/guide/advanced) section.