Swheel

Declarative component-based svelte 3 router.

Install

npm i --save swheel

API

<Router />
<MemoryRouter />
getHistory()
- history methods
- history stores
navLink
<Route />
<Layout />
<HashRoute />
<Fallback />
<Redirect />
<BeforeLeave />
<Protected />

<Router />

Should be placed on the top of your application. Applies special listener for every <a> element and initializes routing state for application's tree.

Uses browser history API.

<MemoryRouter />

The same as <Router> but uses in-memory history API.

getHistory: `Function`

Function that returns object of helper functions to work with history.

This function should be called in the component's initialization step bacause Router and MemoryRouter uses svelte's context API as a core approach

Methods:

Name	Arguments	Description
`push`	`path: String`	Push path to the history
`replace`	`path: String`	Replace path in the current state of the history
`back`	-	Move back in the history
`forward`	-	Move forward in the history

Stores:

Name	Subject	Description
`currentPath`	`currentPath: String`	Current path in history
`stack` (`<MemoryRouter>` only)	`{ stack, hasNext, hasPrev }`	Set of fields with memory histories' metadata

navLink: `Function`

Svelte action. Allows to control active class (show/hide it) in case of matching href attribute with current path of history. Active class name should be defined explicitly to be compiled with svelte.

Ex. <a use:navLink={{ exact: true, activeClass: 'active' }} class="active" href="/path" />

Parameters:

Name	Type	Default / required	Description
exact	`Boolean`	`false`	If pathes should have exactly matches
activeClass	`String`	`'active'`	Class name that will be assigned in case of pathes matches

<Route />

Specifies your route configuration.

It is possible to define nested to routes.
In this case all pathes will calculate relatively the parent path.
Ex. If parent route defined as <Route path="/parent" /> and child as <Route path="/child" /> - in this case nested route will be resolved by path /parent/child.

Prop	Type	Default / required	Description
`path`	`String`	required	Path to access the route. Could be defined as template with required and optional parameters (ex. `/pokemon/:id`). If `path` matched than parameters passing inside components from `lazy` or `component` as property (ex. `export let id`) or could be accessed from `let:params` and passed to the slot.
`let:params`	`Object`	`null`	Parameters resolved from `path`
`exact`	`Boolean`	`false`	Detects if path should have exactly matches
`when`	`Boolean`	`true`	Detects if route is using in current flow
`component`	`SvelteComponent`	`null`	Renders in case if `path` matched
`lazy`	`() => Promise<SvelteComponent>`	`null`	Function that returns promise that resolving the Svelte component Loading starts only on the first route matching and after that component will cache
`throttle`	`Number`	`0`	Uses in a couple with `lazy`. Determines minimal time (in ms) which component will not be displayed. Necessary for preventing flash effect when switching pending state to component.
`<slot />`	`SvelteSlot`	`-`	Renders in the case if `lazy` or `component` props was't defined
`<slot name="pending" />`	`SvelteSlot`	`-`	Renders when component from `lazy` field is loading
`<slot name="catch" />`	`SvelteSlot`	`-`	Renders when component from `lazy` field is failed to load

<Layout />

Provides the possibility to declaratively define layouts around the group of routes and will be rendered only in the case if any path of these routes matches.

Prop	Type	Default / required	Description
`component`	`SvelteComponent`	required	Layout component that wraps the group of routes. `<slot/>` content of `<Layout>` will be passed to it. Renders only in case if any path of inner routes matches.
`when`	`Boolean`	`true`	Detects if layout and it routes' group is using in current flow
`<slot />`	`SvelteSlot`	`-`	Will be passed to the `component`.

<HashRoute />

Extends <Route> without path property and expands with own ones.

Route that displays content, when history hash (#) matches.

Prop	Type	Default / required	Description
`hash`	`String`	required	Should start with `#`
`let:removeHash`	`Function`	-	Passes to `component` or `lazy` as property. Function that allows to remove hash from history. Usefull in a couple with modals etc.

<Fallback />

Extends <Route> without path property.

Renders component from lazy, component or <slot /> if any defined route wasn't rendered.
Usefull for 404 (NotFound) pages.

<Redirect />

Determines overriding of current location.
Nested redirect will define from path relatively to the parent route's path.

Prop	Type	Default / required	Description
`to`	`String`	required	Defines path to which redirect in case of `from` matched
`from`	`String`	`'*'`	Determines the path that should be overrided. If `*` specified than redirect will be triggered from path that doesn't matched for any route.
`exact`	`Boolean`	`false`	Detects if path of `from` property should have exactly matches

<BeforeLeave />

Provides possibility to prevent leaving from the page.

Usefull if there is a form on the page and in the case of it's filled to prevent leaving.

Prop	Type	Default / required	Description
`shouldDetectLeave`	`Boolean`	`true`	Detects if leaving should be detected
`let:isLeaving`	`Boolean`	`true`	Detects if user trying to leave the page
`let:cancelLeave`	`Function`	-	Cancel transition from the page
`let:acceptLeave`	`Function`	-	Accept transition from the page. User will be moved to the page where he tried to go before.
`<slot />`	`SvelteSlot`	-	Child content of the component

<Protected />

Protects displaying of nested routes. If routes was wrapped with some content before - it (content) will be displayed in any case. Uses as an abstraction for <Layout /> but could be usefull in some special cases.

Prop	Type	Default / required	Description
`when`	`Boolean`	`true`	Detects if routes should be displayed in the subtree

TODO

Recipe for SSR
Unit tests
Typings

qutran/swheel