96 lines
2.9 KiB
Markdown
96 lines
2.9 KiB
Markdown
# Routing: `Router()` & Utilities
|
|
|
|
SigPro includes a built-in, lightweight **Hash Router** to create Single Page Applications (SPA). It manages the URL state, matches components to paths, and handles the lifecycle of your pages automatically.
|
|
|
|
## Router Signature
|
|
|
|
```typescript
|
|
Router(routes: Route[]): HTMLElement
|
|
```
|
|
|
|
### Route Object
|
|
| Property | Type | Description |
|
|
| :--- | :--- | :--- |
|
|
| **`path`** | `string` | The URL fragment (e.g., `"/"`, `"/user/:id"`, or `"*"`). |
|
|
| **`component`** | `Function` | A function that returns a Node, a String, or a reactive View. |
|
|
|
|
---
|
|
|
|
## Usage Patterns
|
|
|
|
### 1. Defining Routes
|
|
The `Router` returns a `div` element with the class `.router-outlet`. When the hash changes, the router destroys the previous view and mounts the new one inside this container.
|
|
|
|
```javascript
|
|
const App = () => Div({ class: "app-layout" }, [
|
|
Navbar(),
|
|
// The router outlet is placed here
|
|
Router([
|
|
{ path: "/", component: Home },
|
|
{ path: "/profile/:id", component: (params) => UserProfile(params.id) },
|
|
{ path: "*", component: () => H1("404 Not Found") }
|
|
])
|
|
]);
|
|
```
|
|
|
|
### 2. Dynamic Segments (`:id`)
|
|
The router automatically parses URL parameters (like `:id`) and passes them as an object to the component function. You can also access them globally via `Router.params()`.
|
|
|
|
```javascript
|
|
// If the URL is #/profile/42
|
|
const UserProfile = (params) => {
|
|
return H1(`User ID is: ${params.id}`); // Displays "User ID is: 42"
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Navigation Utilities
|
|
|
|
SigPro provides a set of programmatic methods to control the history and read the state.
|
|
|
|
### `Router.to(path)`
|
|
Navigates to a specific path. It automatically formats the hash (e.g., `/home` becomes `#/home`).
|
|
```javascript
|
|
Button({ onclick: () => Router.to("/dashboard") }, "Go to Dashboard")
|
|
```
|
|
|
|
### `Router.back()`
|
|
Goes back to the previous page in the browser history.
|
|
```javascript
|
|
Button({ onclick: () => Router.back() }, "Back")
|
|
```
|
|
|
|
### `Router.path()`
|
|
Returns the current path (without the `#`).
|
|
```javascript
|
|
Watch(() => {
|
|
console.log("Current path is:", Router.path());
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Technical Behavior
|
|
|
|
* **Automatic Cleanup**: Every time you navigate, the router calls `.destroy()` on the previous view. This ensures that all **signals, effects, and event listeners** from the old page are purged from memory.
|
|
* **Reactive Params**: `Router.params` is a signal (`$`). You can react to parameter changes without re-mounting the entire router outlet.
|
|
* **Hash-Based**: By using `window.location.hash`, SigPro works out-of-the-box on any static hosting (like GitHub Pages or Vercel) without needing server-side redirects.
|
|
|
|
---
|
|
|
|
## Styling the Outlet
|
|
The router returns a standard `div` with the `.router-outlet` class. You can easily style it or add transitions:
|
|
|
|
```css
|
|
.router-outlet {
|
|
display: block;
|
|
min-height: 100vh;
|
|
animation: fadeIn 0.3s ease;
|
|
}
|
|
|
|
@keyframes fadeIn {
|
|
from { opacity: 0; transform: translateY(10px); }
|
|
to { opacity: 1; transform: translateY(0); }
|
|
}
|
|
``` |