@lnear/router

This repository contains a TypeScript-based router library designed for single-page applications (SPAs). It is built with lit-html for template rendering and supports route management with plugins and dynamic path resolution.

Table of Contents

1. Features
2. Installation
3. Usage
   • Configuration
   • Adding Routes
   • Navigation
4. API Reference
   • resolveRouterPath
   • Config
   • Router
   • RouteDefinition
   • RouteEvent
5. Contributing
6. License

Features

• Dynamic Path Resolution: Resolve paths with the base URL specified at build time.
• Route Management: Define and manage routes with dynamic parameters and query strings.
• Plugin System: Enhance routing capabilities with plugins.
• Event Handling: Listen to route changes with custom events.
• Fallback Routes: Specify fallback routes for unmatched paths.

Installation

To install the router library, you need to have a package manager like npm or yarn:

npm install @lnear/router
# or
yarn add @lnear/router

Usage

Configuration

First, you need to create a configuration object for the router. This configuration includes your route definitions and any optional plugins or fallback routes.

import { Router, Config } from "@lnear/router";
import { html } from "lit-html";
const router = new Router({
  routes: [
    {
      path: "/",
      title: "Home",
      render: (context) => html`<h1>Home</h1>`,
    },
    {
      path: "/about",
      title: "About",
      render: (context) => html`<h1>About</h1>`,
    },
  ],
  fallback: "/404",
});

Adding Routes

You can dynamically add routes to the router after initialization.

router.addRoute({
  path: "/contact",
  title: "Contact",
  render: (context) => html`<h1>Contact</h1>`,
});

Navigation

To navigate programmatically, use the navigate method.

router.navigate("/about");

API Reference

resolveRouterPath

This function resolves a given path with the base URL specified at build time.

import { resolveRouterPath } from "@lnear/router";

const fullPath = resolveRouterPath("/my-path");

Config

The configuration object for the router.

export interface Config {
  fallback?: string;
  plugins?: RouterPluginInterface[];
  routes: RouteDefinition[];
}

Router

The main class for managing routes and navigation.

class Router extends EventTarget {
  constructor(config: Config);
  addRoute(route: RouteDefinition): void;
  navigate(
    url: URL | string,
    options?: { backNav?: boolean; replace?: boolean }
  ): Promise<void>;
  render(): TemplateResult<1>;
  uninstall(): void;
}

RouteDefinition

Defines a route in the router.

export interface RouteDefinition {
  path: string;
  title: string | ((context: Partial<Context>) => string);
  render(context: Context): TemplateResult<1>;
  plugins?: RouterPluginInterface[];
}

RouteEvent

An event that is dispatched when the route changes.

class RouteEvent extends Event {
  constructor(context: Context);
}

Contributing

We welcome contributions to improve the router library. To contribute, please fork the repository, create a new branch, and submit a pull request with your changes.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

This README provides an overview of the router library, its features, and usage instructions. For more detailed documentation and examples, please refer to the source code and comments within the codebase.