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

spotlight.js-proto

v0.0.11

Published

small library to highlight website content

Downloads

15

Readme

Spotlight.js

Spotlight.js is a Javascript library that let developers highlight content on websites; it allows to create a tour, containing several elements the user can browse through.

With Spotlight.js, you could:

  • showcase your web app features;
  • guide users wanting to accomplish a given task;
  • attract users' attention on a given element.
  • do much more stuff!

Architecture

The library works the same way as a theatre set!

To perform a theatre play, you need actors, right? Well, same idea here! Each component you want to highlight can be declared as follows:

// actors need an asynchronous function that will return targeted HTMLElements.
const titleActor = new Actor(async () => document.getElementById('header-title'));
const menuActor = new Actor(async () => document.getElementById('right-menu'));

Of course, you need a spotlight to showcase them!

const spotlight = new Spotlight();

Then, add your actors as targets for your spotlight:

spotlight.addActors( titleActor, menuActor );

Options

You can set options:

  • for your Spotlight instance;
  • for your Actors, if you want to set settings for specific actors; these will override options set up in your Spotlight instance.
const spotlight = new Spotlight({ options });       // see available options below
spotlight.addActors(
    new Actor(async () => document.getElementById('paragraph-1'), { options }),
    new Actor(async () => document.getElementById('paragraph-2'))
); 

Spotlight options

| name | description | default | |---|---|---| | allowHiddenFocus | allows Spotlight.js to focus elements even when the spot is not activated | false | | autoScroll | when an actor is not in the viewport (and spot is on), scrolls the document until the actor is visible | true | | centerActorOnFocus | when an actor is focused, scrolls the view to center it, even if it is completely in the viewport | true | | loops | at the end of the tour, focuses on the first actor | false | | onBackgroundClick | if preventContentClicking is true, set a callback to call when the user clicks the page during the tour | (spotlight) => spotlight.toggleSpot() | | onEnd | callback triggered when calling next() while last actor is focused | () => console.log("tour ended") | | onLightsOff | triggered when the spot goes off | () => {} | | preventContentClicking | prevents users from clicking page content when a presentation is in progress | true | | preventFocusSpam | blocks focus transition when another is running | true | | resetOnLightsOff | focuses the first actor when turning the spot off | false | | resetOnEnd | spot fades off when next() is called while last actor is focused | true |

Spotlight + Actor options

| name | description | default | |---|---|---| | delay | transition time, in milliseconds, for the spot to switch from an actor to another | 1000 | | matchRadius | reproduces the border-radius of the targeted actor | true | | onFocus | callback triggered when the spot starts targeting a new actor | (newActor: Actor, oldActor: Actor) => { console.log('switching focus from ${oldActor} to ${newActor}'); } | | onFocused | callback triggered when the spot targets a new actor | (actor: Actor) => { console.log('now focusing ${actor}'); } | | shadowColor | color of the shadow (you might want to put some alpha value here) | #ff0000dd | | showSign | should display the sign | true | | showControls | should display controls on the sign | true | | signHTML | overrides sign body with custom HTML code | '' | | signPosition | defines position of the sign regarded the focused actor (can be TOP, RIGHT, BOTTOM, LEFT) | SignPosition.RIGHT | | signText | text of the sign | "Hello there!" | | signTitle | title of the sign | "Title" | | validScrollContainer | check the "Limit parent scrolling" section below | () => true |

Tips

Actors with no target

If you want to center the sign on the screen with no particular target (eg for beginning a tour), provide () => null as builder to the Actor instance :

new Actor (
    async () => null, 
    {
        signTitle: 'Welcome to Spotlight.js', 
        signText: 'Since no actor has been provided, the sign centers itself on the page by default.'
    }
)

Limit parent scrolling

Under the hood, spotlight.js uses the scrollIntoView library to scroll to an element that is offscreen. When focusing an actor, it will attempt to scroll all elements containing the targeted element, which can lead to undesired behaviors, such as scrolling your app's main wrapper:

| Parent overscrolling example | |:--:| | app wrapper is scrolled, revealing a white blank on the page bottom |

To prevent this, you can control which elements scrollIntoView can scroll by providing the validScrollContainer option as such:

this.spotlight = new Spotlight ({
    // not scrolling the window nor #app container
    validScrollContainer: (target, parentsScrolled) => {
        return target !== window && !target.matches('#app');
    }
});

| No parent overscrolling with the validScrollContainer function set | |:--:| | app wrapper is not a valid scrolling target anymore! |

Check scrollIntoView's github for more details.