diff --git a/README.md b/README.md index 98aa138..ded8589 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ > **📝 Small and Unique!** > -> + Less than **1,400** lines of code, including TypeScript typing. +> + Less than **1,450** lines of code, including TypeScript typing. > + Always-on path and hash routing. Simultaneous and independent routing modes. > + The router that invented multi hash routing. -> + **NEW!** Supports extension packages (Sveltekit support coming soon) +> + **NEW!** Supports Sveltekit (via [@wjfe/n-savant-sk](https://github.com/WJSoftware/wjfe-n-savant-sk)) + **Electron support**: Works with Electron (all routing modes) + **Reactivity-based**: All data is reactive, reducing the need for events and imperative programming. @@ -133,27 +133,27 @@ For applications that also run in the browser, condition the navigation to Elect ```svelte - -
- -

Routing Demo

- - - - - - {#snippet children(params)} - - {/snippet} - - ... -
+ +
+ +

Routing Demo

+ + + + + + {#snippet children(params)} + + {/snippet} + + ... +
``` @@ -165,18 +165,20 @@ functionality. Still, this is not mandatory. ```svelte ``` @@ -189,7 +191,7 @@ strategies that are possible with this router. Routers always evaluate all defined routes, so it is possible for more than one route to match. This facilitates the layout of micro-frontends. For example, a navigation micro-frontend could be inside a route that either always matches -or matches most of the time, so navigation links are available the mayority/all of the time. +or matches most of the time, so navigation links are available the majority/all of the time. ### Simultaneous, Always-On Path and Hash Routing @@ -201,13 +203,13 @@ name, while specialty MFE's could route using the path in the hash part of the U ### Multi-Hash Routing -As of Februrary 2025, no other router in the world can do this. +As of February 2025, no other router in the world can do this. Imagine a scenario where your MFE application would like to show side-by-side two micro-frontends that are router-enabled (meaning they use or need to work with a path). With traditional routing, you could not have this setup because one MFE would take over the path, leaving the other MFE without one. -Mutli-hash routing creates named paths in the hash value, giving routers the ability to share the hash value with other +Multi-hash routing creates named paths in the hash value, giving routers the ability to share the hash value with other routers. A hash value of the form `#path1=/path/1;path2=/path/2;...` could power side-by-side MFE's on, say, 4K layouts. @@ -218,7 +220,7 @@ abandon the use of `registerApplication()` and `start()` and just mount parcels [single-spa](https://single-spa.js.org) -## Unintrusive Philosophy +## Unobtrusive Philosophy This mini router library imposes minimal restrictions. Here are some features provided by other much larger codebases that are not provided here because Svelte already has the capability. @@ -229,11 +231,11 @@ Nothing prevents you to add transitions to anything. ```svelte - {#snippet children(params)} -
- ... -
- {/snippet} + {#snippet children(params)} +
+ ... +
+ {/snippet}
``` @@ -252,7 +254,7 @@ the `rest` parameter specifier (`/*`): ```svelte - ... + ... ``` @@ -265,19 +267,19 @@ Lazy-loading components is very simple: ```svelte - {#await loadUsersComponent()} - Loading... - {:then Users} - - {:catch} -

Ooops!

- {/await} + {#await loadUsersComponent()} + Loading... + {:then Users} + + {:catch} +

Oops!

+ {/await}
``` @@ -291,13 +293,13 @@ import { location } from "@wjfe/n-savant"; // Or $derived, whichever you need. $effect(() => { - // Read location.url to re-run on URL changes (navigation). - location.url; - // Read location.state to re-run on state changes. - location.state; - // Read location.hashPaths to re-run on hash changes (hash navigation). - // The route named "single" is the one you want if doing hash routing. - location.hashPaths.single; + // Read location.url to re-run on URL changes (navigation). + location.url; + // Read location.state to re-run on state changes. + location.state; + // Read location.hashPaths to re-run on hash changes (hash navigation). + // The route named "single" is the one you want if doing hash routing. + location.hashPaths.single; }); ``` @@ -317,12 +319,12 @@ numeric parameter value uses the `and` property to type-check the value: ```svelte typeof rp.userId === 'number'}> - {#snippet children(rp)} - - {/snippet} + {#snippet children(rp)} + + {/snippet} - + ``` @@ -330,12 +332,12 @@ This is the version using a regular expression for the `path` property: ```svelte \d+)/i}> - {#snippet children(rp)} - - {/snippet} + {#snippet children(rp)} + + {/snippet} - + ``` @@ -346,23 +348,23 @@ property of router engines (which is reactive) by binding to a router's `router` ```svelte - ... + ... ``` @@ -384,29 +386,29 @@ import { location } from "@wjfe/n-savant"; // Path routing navigation: location.navigate('/new/path', { - replace: true, - state: { custom: 'Hi' }, - hash: false + replace: true, + state: { custom: 'Hi' }, + hash: false }); // Hash routing navigation: location.navigate('/new/path', { - replace: true, - state: { custom: 'Hi' }, - hash: true + replace: true, + state: { custom: 'Hi' }, + hash: true }); // Multi-hash routing navigation: location.navigate('/new/path', { - replace: true, - state: { custom: 'Hi' }, - hash: 'path1' + replace: true, + state: { custom: 'Hi' }, + hash: 'path1' }); // Preserve existing query parameters: location.navigate('/new/path', { - preserveQuery: true, - hash: false + preserveQuery: true, + hash: false }); ``` @@ -424,8 +426,8 @@ import { location } from "@wjfe/n-savant"; // Direct URL navigation: location.goTo('https://example.com/new/path', { - replace: true, - state: { path: undefined, hash: {} } // Must provide complete State object + replace: true, + state: { path: undefined, hash: {} } // Must provide complete State object }); // Shallow routing (navigate to current URL): @@ -433,7 +435,7 @@ location.goTo('', { replace: true }); // Preserve query parameters: location.goTo('/new/path', { - preserveQuery: ['param1', 'param2'] + preserveQuery: ['param1', 'param2'] }); ``` diff --git a/src/lib/Fallback/README.md b/src/lib/Fallback/README.md index a579995..1c6ef32 100644 --- a/src/lib/Fallback/README.md +++ b/src/lib/Fallback/README.md @@ -11,6 +11,7 @@ route status data is calculated. | Property | Type | Default Value | Bindable | Description | |-|-|-|-|-| | `hash` | `boolean \| string` | `undefined` | | Sets the hash mode of the component. | +| `when` | `WhenPredicate` | `undefined` | | Overrides the default activation conditions for the fallback content inside the component. | | `children` | `Snippet<[any, Record]>` | `undefined` | | Renders the children of the component. | [Online Documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/components/fallback) diff --git a/src/lib/Link/README.md b/src/lib/Link/README.md index 1fd362a..a1448c1 100644 --- a/src/lib/Link/README.md +++ b/src/lib/Link/README.md @@ -11,6 +11,7 @@ SPA-friendly navigation (navigation without reloading). | `href` | `string` | (none) | | Sets the URL to navigate to. | | `replace` | `boolean` | `false` | | Configures the link so it replaces the current URL as opposed to pushing the URL as a new entry in the browser's History API. | | `state` | `any` | `undefined` | | Sets the state object to pass to the browser's History API when pushing or replacing the URL. | +| `activeFor` | `string` | `undefined` | | Sets the route key that the link will use to determine if it should render as active. | | `activeState` | `ActiveState` | `undefined` | | Sets the various options that are used to automatically style the anchor tag whenever a particular route becomes active. | | `prependBasePath` | `boolean` | `false` | | Configures the component to prepend the parent router's base path to the `href` property. | | `preserveQuery` | `PreserveQuery` | `false` | | Configures the component to preserve the query string whenever it triggers navigation. | @@ -30,8 +31,8 @@ These don't require a parent router: Hash Routing => https://example.com/#/new/path - Multi Hash Routing => https://example.com/#path1=/new/path - Will also preserve any other named paths + Multi Hash Routing => https://example.com/#path1=/new/path + Will also preserve any other named paths ``` @@ -42,16 +43,17 @@ automatically trigger its active appearance based on a specific route becoming a ```svelte - - Click Me! - - - ... - + + Click Me! + + + ... + ``` diff --git a/src/lib/LinkContext/README.md b/src/lib/LinkContext/README.md index a4322aa..0184fbf 100644 --- a/src/lib/LinkContext/README.md +++ b/src/lib/LinkContext/README.md @@ -1,7 +1,6 @@ # LinkContext -The `LinkContext` component is used to create context for `Link` components. This context can be used to set, in -mass, the `replace`, `prependBasePath` and `preserveQuery` properties. +The `LinkContext` component is used to create context for `Link` components. This context can be used to set, in mass, the `replace`, `prependBasePath`, `preserveQuery` and `activeState` properties. Instead of writing this: @@ -16,9 +15,9 @@ You can do: ```svelte - ... - ... - ... + ... + ... + ... ``` @@ -33,13 +32,20 @@ lose the query string. The `Link` component will give priority to an explicitly-set value at its property level. If a property-level value is not found, then the context-provided property value is used. If there is no context, then the default value takes over. +### Priorities Between Contexts + +Link contexts inherit from parent link contexts. A context deeper in the document's hierarchy will give priority to the values explicitly set via its component properties. If a component property is `undefined`, the parent context, if any, will be used as source for the value. + +Unlike the `Link` component, the contextual properties of the `LinkContext` component provide no default value. + ## Props | Property | Type | Default Value | Bindable | Description | |-|-|-|-|-| -| `replace` | `boolean` | `false` | | Configures the link so it replaces the current URL as opposed to pushing the URL as a new entry in the browser's History API. | -| `prependBasePath` | `boolean` | `false` | | Configures the component to prepend the parent router's base path to the `href` property. | -| `preserveQuery` | `PreserveQuery` | `false` | | Configures the component to preserve the query string whenever it triggers navigation. | +| `replace` | `boolean` | `undefined` | | Configures the link so it replaces the current URL as opposed to pushing the URL as a new entry in the browser's History API. | +| `prependBasePath` | `boolean` | `undefined` | | Configures the component to prepend the parent router's base path to the `href` property. | +| `preserveQuery` | `PreserveQuery` | `undefined` | | Configures the component to preserve the query string whenever it triggers navigation. | +| `activeState` | `ActiveState` | `undefined` | | Sets the various options that are used to automatically style the anchor tag whenever a particular route becomes active. | | `children` | `Snippet` | `undefined` | | Renders the children of the component. | [Online Documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/components/linkcontext) diff --git a/src/lib/Router/README.md b/src/lib/Router/README.md index b8e86db..da452fb 100644 --- a/src/lib/Router/README.md +++ b/src/lib/Router/README.md @@ -23,19 +23,19 @@ Simplest form of use. ```svelte - -

Welcome to the home page!

-
- -

About Us

-
- -

Contact Us

-
+ +

Welcome to the home page!

+
+ +

About Us

+
+ +

Contact Us

+
``` @@ -46,11 +46,11 @@ the MFE is meant to respond to sub-path routes only. ```svelte - ... + ... ``` @@ -61,29 +61,29 @@ as needed. ```svelte - -

Welcome to the home page!

-

The Route component matched /root/home.

+ +

Welcome to the home page!

+

The Route component matched /root/home.

+
+ +

About Us

+
+ +

Contact Us

+
+ + +

Admin Dashboard

+

The Route component matched /root/admin/dashboard.

- -

About Us

+ +

Admin Users

- -

Contact Us

-
- - -

Admin Dashboard

-

The Route component matched /root/admin/dashboard.

-
- -

Admin Users

-
-
+
``` @@ -93,22 +93,22 @@ Use the `fallback()` snippet of the router to present content when no routes mat ```svelte - -

Welcome to the home page!

-
- -

About Us

-
- -

Contact Us

-
- {#snippet fallback()} -

404 Not Found

- {/snippet} + +

Welcome to the home page!

+
+ +

About Us

+
+ +

Contact Us

+
+ {#snippet fallback()} +

404 Not Found

+ {/snippet}
``` @@ -118,20 +118,20 @@ Parameters are expressed in the form `:[?]`. The optional `"?"` makes the ```svelte - - {#snippet children(params)} - - {#if params.detailed} - - {/if} - {/snippet} - + + {#snippet children(params)} + + {#if params.detailed} + + {/if} + {/snippet} + ``` @@ -142,12 +142,12 @@ never use this name as a name for one of your parameters. ```svelte - - ... - + + ... + ```