npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bitovi/router-4-web-component

v0.1.0-alpha12

Published

A router for Web Components.

Downloads

31

Readme

@bitovi/router-4-web-component

A router for web components.

Install

As part of an ES module

Use "esm.sh" and import this module into a source file where you need to use the router.

import from "https://esm.sh/@bitovi/router-4-web-component";

As part of a bundle

If you are bundling your source code you may need to use a dynamic import to load the library like so:

async function main() {
  await import("https://esm.sh/@bitovi/router-4-web-component");
}

Using a script element

The script can also be loaded in an HTML file, typically as part of the <head> element.

<head>
  <script
    src="https://esm.sh/@bitovi/router-4-web-component"
    type="module"
  ></script>
</head>

Then you can use the router in your HTML.

<r4w-router>
  <r4w-route path="/foo" src="/foo.js">
    <my-web-component />
  </r4w-route>
</r4w-router>

API

Elements

<r4w-link>

Must be a descendant of the <rw4-router> element. When the link is clicked browser history is updated, a matching route that is a child of the same <rw4-router> ancestor element will be activated.

Attributes

All attributes that can be applied to an <a> element - except href - as well as:

  • to - The path that will be pushed to browser history.
Descendants

Same descendants as an <a> tag.


<r4w-redirect />

Must be an immediate child of <r4w-switch>. Will be used to update browser history if none of the immediate child <r4w-route> elements match the current URL.

Attributes
  • to - The path that will be pushed to browser history.
Descendants

None


<r4w-route>

Child elements will be added to the DOM when its path matches the browser location and the route becomes active; child elements will be removed when it is deactivated.

If the route has a src attribute the source file will be dynamically imported (and cached) when the route is activated then the children will be added to the DOM; otherwise children are immediately attached to the DOM. A common use case is a web component as the route's child and the src is the URL of a JavaScript file that creates the web component's class and defines the web component in customElements.

Attributes
  • path - The path pushed to browser history.
  • src - Optional URL to a resource, commonly another ES module. Will be imported dynamically (and cached) the first time the route is activated.
Descendants

Any element


<r4w-router>

All r4w elements must be nested under a single r4w-router. This is the most basic component and should probably be placed close to the <body element of the document.

Attributes

None

Descendants

Any element


<r4w-switch>

Activates a single child <r4w-route> element (that is an immediate child of the switch) when a path matches the browser location or an <rw4-redirect> takes effect.

Attributes

None

Descendants

Any element. The <r4w-redirect> element must be a direct child of this element.


Mixins

ParamsListenerMixin

This mixin is used as a base for web components that want to get params information from a route's path. Must be a descendant of an <r4w-route> element.

Can be used in a mixin definition of a web component.

Create a web component.

import { ParamsListenerMixin } from "https://esm.sh/@bitovi/router-4-web-component";

export class MyWebComponent extends ParamsListenerMixin(HTMLElement) {
  override _onParamsChange(params: Record<string, string>): void {
    // The params information in the `params` object depends on the tokens
    // included in the value of an `<r4w-route>` `path` attrbute.
    console.log("_onParamsChange: params=", params);
  }
}

if (!customElements.get("my-web-component")) {
  customElements.define("my-web-component", MyWebComponent);
}

Use the web component.

<r4w-router>
  <r4w-link to="/items/42">The meaning of...</r4w-link>
  <r4w-route path="/items/:item">
    <my-web-component />
  </r4w-route>
</r4w-router>

When this code is executed the text "_onParamsChange: params= { item: 42 }" will be logged.


TemplateMixin

Fetch an HTML file and make its body available as a string to clients. The string can be set as the innerHTML of an element, typically a <template>.

Can be used in a mixin definition of a web component.

Create a web component and apply the mixin to it.

import { TemplateMixin } from "https://esm.sh/@bitovi/router-4-web-component";

export class MyWebComponent extends TemplateMixin(HTMLElement) {
  constructor() {
    super();
    // Setting the `templateSrc` property starts the download.
    this.templateSrc = "//example.com/template.html";
  }

  override _onTemplateReady(html: string) {
    // The download has completed and the contents of the file are passes as the `html` arg.
    const template = document.createElement("template");
    template.innerHTML = html;
  }
}

if (!customElements.get("my-web-component")) {
  customElements.define("my-web-component", MyWebComponent);
}

Functions

receive

Various messages are used to communicate status changes in the router system. The receive function is the method used to listen for those messages. Provide a handler that will be invoked when the named message arrives.

parameters
  • name {keyof R4WDetailMap} The name of the message to listen for.
  • callback {ReceiveCallback} This will be invoked when a message arrives.
  • target {EventTarget} An optional parameter that indicates the element that message refers to, when provided this is the object that will receive messages; defaults to window.
returns

{DisconnectCallback} Invoke when the you no longer need to receive messages.