Skip to content

Commit

Permalink
Update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@willybrauner
willybrauner committed Oct 18, 2023
1 parent f1ded44 commit 4f3763e
Showing 1 changed file with 64 additions and 54 deletions.
118 changes: 64 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,6 @@ A fresh high-level react router designed for flexible route transitions

<br>

cher-ami router API is inspired by [wouter](https://github.com/molefrog/wouter),
[solidify router](https://github.com/solid-js/solidify/blob/master/navigation/Router.ts)
and
[vue router](https://router.vuejs.org/) API.

## Why another react router?

Because managing route transitions with React is always complicated, this router
Expand All @@ -25,18 +20,25 @@ This router loads [history](https://github.com/ReactTraining/history)
, [path-to-regexp](https://github.com/pillarjs/path-to-regexp)
and [@wbe/debug](https://github.com/willybrauner/debug) as dependencies.

## Playground

- [example client](https://codesandbox.io/s/github/cher-ami/router/tree/main/examples/example-client)
- [example ssr](https://codesandbox.io/s/github/cher-ami/router/tree/main/examples/example-ssr)
-

## Summary

- [Installation](#Installation)
- [Simple usage](#SimpleUsage)
- [Dynamic routes](#DynamicRoutes)
- [Sub Routers](#SubRouters)
- [Manage Transitions](#ManageTransitions)
- [Default sequential transitions](#DefaultSequentialTransitions)
- [Custom transitions](#CustomTransitions)
- [SSR support](#SSRSupport)
- [Debug](#Debug)
- [Example](#Example)
- [Simple usage](#Simple-Usage)
- [Dynamic routes](#Dynamic-Routes)
- [Sub Router](#Sub-Router)
- [Manage Transitions](#Manage-Transitions)
- [Default sequential transitions](#Default-Sequential-Transitions)
- [Custom transitions](#Custom-Transitions)
- [SSR support](#SSR-Support)
- [Workflow](#Workflow)
- [thanks](#Thanks)
- [credits](#Credits)

**API**

Expand Down Expand Up @@ -66,13 +68,13 @@ Global:
- [`Helpers`](#Helpers) Global Routers helpers
- [`Routers object`](#Routers) Global Routers object contains all routers properties (history, instances...)

## <a name="Installation"></a>Installation
## Installation

```shell
$ npm i @cher-ami/router -s
```

## <a name="SimpleUsage"></a>Simple usage
## Simple usage

```jsx
import React from "react";
Expand Down Expand Up @@ -139,9 +141,7 @@ const FooPage = forwardRef((props, handleRef) => {
});
```

**[Demo codesandbox: simple usage](https://codesandbox.io/s/simple-usage-cpufs)**

## <a name="DynamicRoutes"></a>Dynamic routes
## Dynamic routes

cher-ami router use [path-to-regexp](https://github.com/pillarjs/path-to-regexp) which
accept path parameters. (check
Expand Down Expand Up @@ -178,8 +178,6 @@ const ArticlePage = forwardRef((props, handleRef) => {
});
```

**[Demo codesandbox: simple usage](https://codesandbox.io/s/simple-usage-cpufs)**

Also, it is possible to match a specific route by a simple dynamic route
parameter for the "not found route" case. In this case, the routes object order
declaration is important. `/:rest` path route need to be the last of
Expand All @@ -203,9 +201,7 @@ const routesList = [
];
```

**[Demo codesandbox: not found route](https://codesandbox.io/s/not-found-route-eu4bi)**

## <a name="SubRouters"></a>Sub-router
## Sub-router

cher-ami router supports nested routes from sub routers instance 🙏🏽.
It is possible to nest as many routers as you want.
Expand Down Expand Up @@ -272,12 +268,12 @@ const FooPage = forwardRef((props, handleRef) => {
});
```

## <a name="ManageTransitions"></a>Manage transitions
## Manage transitions

`ManageTransitions` function allows to define, "when" and "in what conditions",
routes transitions will be exectued.

### <a name="DefaultSequentialTransitions"></a>Default sequential transitions
### Default sequential transitions

By default, a "sequential" transitions senario is used by Stack component: the
previous page play out performs, then the new page play in.
Expand Down Expand Up @@ -310,7 +306,7 @@ const sequencialTransition = ({ previousPage, currentPage, unmountPreviousPage }
};
```
### <a name="CustomTransitions"></a>Custom transitions
### Custom transitions
It's however possible to create a custom transitions senario function and pass
it to the Stack `manageTransitions` props. In this example, we would like to
Expand All @@ -336,9 +332,7 @@ const App = (props, handleRef) => {
};
```
**[Demo codesandbox: custom manage transitions](https://codesandbox.io/s/inspiring-thompson-tw4qn)**
## <a name="SSRSupport"></a>SSR Support
## SSR Support
This router is compatible with SSR due to using `staticLocation` props instead of `history` props on Router instance.
In this case, the router will match only with `staticLocation` props value and render the appropiate route without invoking the browser history. (Because `window` is not available on the server).
Expand Down Expand Up @@ -383,25 +377,34 @@ function HomePage({ api }) {
For larger example, check the [example-ssr folder](./examples/example-ssr/).
## <a name="Example"></a>Example
## Workflow
A use case example is available on this repos.
```shell
# Install dependencies
pnpm i

Install dependencies
## build watch
pnpm run build:watch

```shell
$ npm i
```
## start tests
pnpm run test:watch

Start dev server
## start all examples
pnpm run dev

```shell
$ npm run dev
## Before publishing
pnpm run pre-publish

## Increment version
npm version {patch|minor|major}

## Publish
npm publish
```
## <a name="Api"></a>API
## API
### <a name="Router"></a>Router
### Router
Router component creates a new router instance.
Expand All @@ -428,7 +431,7 @@ Router component creates a new router instance.
- **middlewares** `[]` _(optional)_ add routes middleware function to patch each routes)
- **id** `?number | string` _(optional)_ id of the router instance - default : `1`
### <a name="Link"></a>Link
### Link
Trig new route.
Expand All @@ -444,7 +447,7 @@ Trig new route.
- **onClick** `()=> void` _(optional)_ execute callback on the click event
- **className** `string` _(optional)_ Class name added to component root DOM element
### <a name="Stack"></a>Stack
### Stack
Render previous and current page component.
Expand Down Expand Up @@ -477,7 +480,7 @@ interface IRouteStack {
}
```
### <a name="useRouter"></a>useRouter
### useRouter
Get current router informations:
Expand Down Expand Up @@ -518,7 +521,7 @@ type TRoute = Partial<{
}>;
```
### <a name="useLocation"></a>useLocation
### useLocation
Allow the router to change location.
Expand Down Expand Up @@ -546,7 +549,7 @@ type TOpenRouteParams = {
};
```
### <a name="useStack"></a>useStack
### useStack
useStack allows to the parent Stack to handle page transitions and refs.
Expand Down Expand Up @@ -643,7 +646,7 @@ const customManageTransitions = ({ previousPage, currentPage, unmountPreviousPag
nothing
### <a name="useRouteCounter"></a>useRouteCounter
### useRouteCounter
Returns route counter
Expand All @@ -663,7 +666,7 @@ An object with these properties:
- **isFirstRoute** `boolean` Check if it's first route - default: `true`
- **resetCounter** `() => void` Reset routerCounter & isFirstRoute states
### <a name="useHistory"></a>useHistory
### useHistory
Allow to get the global router history and execute a callback each time history
change.
Expand All @@ -683,7 +686,7 @@ const history = useHistory((e) => {
- **history** `History` : global history object. (`Routers.history`)
### <a name="useLang"></a>useLang
### useLang
Get and update langService current language object.
Expand All @@ -707,7 +710,7 @@ Array of :
- **lang** `TLanguage` : current lang object
- **setLang** `(lang: TLanguage | string, force: boolean) => void` : set new lang object (same API than `langService.setLang`)
### <a name="LangService"></a>LangService
### LangService
Manage `:lang` params from anywhere inside Router scope.
Expand Down Expand Up @@ -848,13 +851,13 @@ langService.redirectToDefaultLang();
#### redirectToBrowserLang(forcePageReload = true) `void`
Same than `redirectToDefaultLang` method but redirect to the user `navigator.language`.
If the browser language doesn't exist in Languages array, we redirect to the default lang.
If the browser language doesn't exist in Languages array, we redirect to the default lang.
```js
langService.redirectToBrowserLang();
```
### <a name="TranslatePath"></a>Translate Path
### Translate Path
Paths can be translated by lang in route path property. This option works only if LangService instance is created and passed to the Router component.
Expand All @@ -865,7 +868,7 @@ Paths can be translated by lang in route path property. This option works only i
}
```
## <a name="Helpers"></a>Helpers
## Helpers
#### createUrl()
Expand All @@ -879,7 +882,7 @@ Create a formated URL by string, or `TOpenRouteParams`
Push new route in current history. Stack(s) component(s) will return the appriopriate route.
## <a name="Routers"></a>Routers
## Routers
Routers is a global object who contains all routers informations. Because @cher-ami/router is possibly multi-stack, we need a global object to store shared informations between router instances.
Expand Down Expand Up @@ -913,6 +916,13 @@ How many route are resolved from the start of the session. This property is also
Is it the first route of the session. This property is also available from `useRouteCounter`.
## Thanks
cher-ami router API is inspired by [wouter](https://github.com/molefrog/wouter),
[solidify router](https://github.com/solid-js/solidify/blob/master/navigation/Router.ts)
and
[vue router](https://router.vuejs.org/) API.
## Credits
[Willy Brauner](https://github.com/willybrauner)
Expand Down

0 comments on commit 4f3763e

Please sign in to comment.