[labs/router] New Router API! 🌟

[thebug404]

Context

The @lit-labs/router package provides routing functionalities for Single Page Applications (SPAs), but currently, there are areas that could be enhanced:

• Programmatic navigation is not straightforward, requiring developers to come up with creative solutions to address this limitation.
• Route definition can be complex as the router is tightly coupled with components via ReactiveController. This can make it challenging to identify routes, especially when nesting them, as accessing each component is necessary.
• Implementing Lazy Loading on some pages may be confusing. Often, the enter callback is used to perform multiple tasks, such as loading components lazily, functioning as navigation guards, among others.

To address these improvement points, I've created this pull request proposing a more intuitive API and a more satisfying development experience. The proposed enhancements are based on concepts drawn from other popular routing APIs.

Solution

This pull request introduces significant enhancements to the @lit-labs/router library, aiming to revolutionize the way routes are managed in Lit applications. With Lit Router API, developers will have a more intuitive API for defining routes, adding pages through lazy loading, and a set of utilities to enhance the navigation experience.

• 🛣️ Defining Routes️: Instructions on how to define routes using Lit Router, with examples for both tag names and component classes.
• ⏳ Lazy Loading: Guide on how to implement lazy loading for improved performance.
• 🌳 Nested Routes: Explanation and example of defining nested routes.
• 🚀 Programmatic Navigation: API reference and examples for programmatic navigation.
• 🔄🔍 Query & Params: API reference and examples for accessing query parameters and route parameters.
• 🚧 Guards: Explanation and examples of using guards for route authentication.

Basic Usage

// Import package.
import '@lit-labs/router';

// Import your static pages.
import {HomePage} from './pages/home-page.js';
import './pages/about-page.js';

// Get a router.
const $router = document.querySelector('lit-router');

// Register your routes.
$router.setRoutes([
  {path: '/', component: HomePage},
  {path: '/about', component: 'about-page'}
]);

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3abc28e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📊 Tachometer Benchmark Results

Summary

A summary of the benchmark results will show here once they finish.

Results

The full results of your benchmarks will show here once they finish.

_{tachometer-reporter-action v2 for Benchmarks}

[justinfagnani]

While I appreciate the enthusiasm and contribute here, we ask in the contributing guide that PRs have have an associated issue or RFC so that we can have a discussion about the shape of the solution before diving into the code/review process.

This is a large PR with changes that might not fit the goals of the labs router. It would be good to come to agreement here before making such a large PR.

[thebug404]

I appreciate your feedback, my intention in submitting this PR was to address some of the points raised in the Proposal for a New API @lit-labs/router package. However, not receiving comments on the initial proposal, I decided to proceed with the implementation in a PR.

I understand the importance of having discussions about the shape of the solution before diving into the code review process. I am fully open to collaborate and discuss the goals of the Router Labs and how my changes can better align with those objectives.

Thank you again for your guidance, and I would be grateful to receive feedback on the Proposal for a New API @lit-labs/router package