Refinements

Author: webJose

.gitignore

@@ -22,3 +22,6 @@ Thumbs.db
 # Vite
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Tarballs
+*.tgz

README.md

@@ -1,16 +1,21 @@
 # @wjfe/n-savant
 
-> Small router for Svelte v5 SPA's specialized for micro-frontends.
+> The client-side router for Svelte v5 SPA's that invented multi hash routing.
 
 ## Features
 
-This router's code is small, revolving the **900** lines of code, including typing.
+> [!NOTE]
+> #### Small and Unique!
+> 
+> + Less than **900** lines of code, including TypeScript typing.
+> + Always-on path and hash routing.  Simultaneous and independent routing modes.
+> + The router that invented multi hash routing.
 
 + **Reactivity-based**:  All data is reactive, reducing the need for events and imperative programming.
 + **Always-on path and hash routing**:  Add routers that use the URL's path name or the URL's hash value in the same 
 application.  Both routing modes are possible simultaneously.
-+ **Multi-hash routing**:  Unique to this router and not found in any other router library, you can create named paths 
-in the hash value of the URL and create router hierarchies that use a specific named path.
++ **Multi-hash routing**:  This is the first router in the world to do this:  You can create named paths in the hash 
+value of the URL and create router hierarchies that use a specific named path.
 
 ### `<Router>` Component
 
@@ -165,15 +170,17 @@ or matches most of the time, so navigation links are available the mayority/all
 
 Components (`Router`, `Route`, `Link`, `Fallback` and `RouterTrace`) with the same value of the `hash` property belong 
 to the same "universe".  Components with different hash values belong to different universes, and these universes are 
-parallel universes.  Components with hash value `false` use the URL's path name and will never interere with routers 
+parallel universes.  Components with hash value `false` use the URL's path name and will never interfere with routers 
 that use hash routing (hash value `true` or a path's name).  The main micro-frontend(s) may route using the URL's path 
 name, while specialty MFE's could route using the path in the hash part of the URL.
 
 ### Multi-Hash Routing
 
-Following up from the previous, 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.
+As of Februrary 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 
 routers.  A hash value of the form `#path1=/path/1;path2=/path/2;...` could power side-by-side MFE's on, say, 4K 
@@ -182,14 +189,14 @@ layouts.
 ### EXPERIMENTAL - Replacing the `single-spa` Router
 
 It is the author's intent to implement micro-frontends with only `single-spa` parcels and this router.  In other words, 
-abandon the use of `registerApplication()` and `start()` and just mount parcels.
+abandon the use of `registerApplication()` and `start()` and just mount parcels using this router.
 
 [single-spa](https://single-spa.js.org)
 
 ## Unintrusive Philosophy
 
 This mini router library imposes minimal restrictions.  Here are some features provided by other much larger codebases 
-(most notably `dvcol/svelte-simple-router`) that are not provided here because Svelte already has the capability.
+that are not provided here because Svelte already has the capability.
 
 ### Transitions
 
@@ -214,18 +221,19 @@ Nothing prevents you to add transitions to anything.
 Guard routes however you wish.  Maybe with an `{#if}` block, or maybe using the route's `and` property that allows you 
 to specify a predicate function.  There are probably many other ways.
 
-### Exact Property on Routes
+### `Exact` Property on Routes
 
 Not needed.  All matching is exact path matching, and if you want to opt out of the exact route matching, simply add 
-the rest parameter specifier:
+the `rest` parameter specifier (`/*`):
 
 ```svelte
 <Route key="admin" path="/admin/*">
     ...
 </Route>
 ```
 
-If you don't care about the value of the parameter, just ignore it.
+Now route matching for this route will behave as "starts with".  If you don't care about the value of the parameter, 
+just ignore it.
 
 ### Lazy-Loading
 
@@ -344,8 +352,10 @@ import { location } from "@wjfe/n-savant";
 
 // Path routing navigation:
 location.navigate('/new/path', { replace: true, state: { custom: 'Hi' }});
+
 // Hash routing navigation:
 location.navigate('#/new/path', { replace: true, state: { custom: 'Hi' }});
+
 // Multi-hash routing navigation:
 location.navigate('/new/path', 'path1', { replace: true, state: { custom: 'Hi' }});
 ```
@@ -360,8 +370,10 @@ Just in case you are wondering:  The navigation logic is already there in `<Link
 ```svelte
 <!-- Path Routing => https://example.com/new/path -->
 <Link hash="false" href="/new/path">Click Me!</Link>
+
 <!-- Hash Routing => https://example.com/#/new/path -->
 <Link hash="true" href="/new/path">Click Me!</Link>
+
 <!-- Multi Hash Routing => https://example.com/#path1=/new/path -->
 <!-- Will also preserve any other named paths -->
 <Link hash="path1" href="/new/path">Click Me!</Link>
@@ -382,6 +394,6 @@ on the router layouts, again, **at your own risk**.
 
 ---
 
-[Full Documentation @ Hashnode Pages](https://wjfe-n-savant.hashnode.pages)
+[Full Documentation @ Hashnode Space](https://wjfe-n-savant.hashnode.space)
 
 If you would like to report a bug or request a feature, head to the [Issues page](https://github.com/WJSoftware/wjfe-n-savant/issues).

package.json

@@ -3,9 +3,9 @@
 	"version": "0.1.0",
 	"scripts": {
 		"dev": "vite dev",
-		"build": "vite build && npm run prepack && pwsh ./update-svelte-files.ps1",
+		"build": "vite build && npm run prepack",
 		"preview": "vite preview",
-		"prepack": "svelte-kit sync && svelte-package && publint",
+		"prepack": "svelte-kit sync && svelte-package && publint && pwsh ./update-svelte-files.ps1",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"format": "prettier --write .",

src/lib/Fallback/README.md

@@ -0,0 +1,20 @@
+# Fallback
+
+The `Fallback` component can be thought about as a `Route` component that only render its children if there are no 
+other routes in the parent router engine that match.
+
+Internally, it checks the parent router engine's `noMatches` value, which is a reactive value calculated when all other 
+route status data is calculated.
+
+## Props
+
+| Property | Type | Default Value | Bindable | Description |
+|-|-|-|-|-|
+| `hash` | `boolean \| string` | `undefined` | | Sets the hash mode of the component. |
+| `children` | `Snippet` | `undefined` | | Renders the children of the component. |
+
+[Online Documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/components/fallback)
+
+## Examples
+
+See the examples for the `Router` component.

src/lib/Link/Link.svelte

@@ -2,6 +2,7 @@
 	import { location } from '$lib/core/Location.js';
 	import { joinPaths, resolveHashValue } from '$lib/core/RouterEngine.svelte.js';
 	import { getRouterContext } from '$lib/Router/Router.svelte';
+	import type { ActiveState } from '$lib/types.js';
 	import { type Snippet } from 'svelte';
 	import type { HTMLAnchorAttributes } from 'svelte/elements';
 
@@ -58,32 +59,7 @@
 		 * 
 		 * **IMPORTANT**:  This only works if the component is within a `Router` component.
 		 */
-		activeState?: {
-			/**
-			 * Sets the route key that the link will use to determine if it should render as active.
-			 */
-			key?: string;
-			/**
-			 * Sets the class that the link will use when rendering as active.
-			 * 
-			 * For example, set it to `"active"` for Bootstrap setups.
-			 */
-			class?: string;
-			/**
-			 * Sets the style that the link will use when rendering as active.
-			 * 
-			 * This can be a string of CSS styles or an object of key-value pairs.
-			 */
-			style?: HTMLAnchorAttributes['style'] | Record<string, string>;
-			/**
-			 * Sets the value of the `aria-current` attribute when the link is active.
-			 * 
-			 * The possible values are defined by the HTML specification.
-			 * 
-			 * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current#values)
-			 */
-			ariaCurrent?: HTMLAnchorAttributes['aria-current'];
-		};
+		activeState?: ActiveState;
 		/**
 		 * Configures the component to prepend the parent router's base path to the `href` property.
 		 * 

src/lib/Link/README.md

@@ -0,0 +1,57 @@
+# Link
+
+The `Link` component renders HTML anchor elements that behave in accordance to its `hash` property, allowing 
+SPA-friendly navigation (navigation without reloading).
+
+## Props
+
+| Property | Type | Default Value | Bindable | Description |
+|-|-|-|-|-|
+| `hash` | `boolean \| string` | `undefined` | | Sets the hash mode of the component. |
+| `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. |
+| `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. |
+| `children` | `Snippet` | `undefined` | | Renders the children of the component. |
+
+[Online Documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/components/link)
+
+## Examples
+
+### Basic Usage
+
+These don't require a parent router:
+
+```svelte
+<!-- Path Routing => https://example.com/new/path -->
+<Link hash="false" href="/new/path">Click Me!</Link>
+
+<!-- Hash Routing => https://example.com/#/new/path -->
+<Link hash="true" href="/new/path">Click Me!</Link>
+
+<!-- Multi Hash Routing => https://example.com/#path1=/new/path -->
+<!-- Will also preserve any other named paths -->
+<Link hash="path1" href="/new/path">Click Me!</Link>
+```
+
+### Usage Within a Parent Router
+
+In this example, the `Link` component will take advantage of the parent router to inherit its base path and to 
+automatically trigger its active appearance based on a specific route becoming active.
+
+```svelte
+<Router basePath="/some/base">
+    <Link
+        hash="path1"
+        href="/admin/users"
+        prependBasePath
+        activeState={{ key: 'adminUsers', class: 'active', }}
+    >
+        Click Me!
+    </Link>
+    <Route key="adminUsers" path="/admin/users">
+        ...
+    </Route>
+</Router>
+```