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 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tulipnpm/appointments-widget

v1.0.0

Published

Loader for the Tulip appointments booking widget.

Readme

@tulipnpm/appointments-widget

Loads the Tulip appointments booking widget on your site. The loader exchanges your publishable key for a short session, keeps it fresh and frames the widget. The widget itself is served from your Tulip host, so booking screens, styling and copy update without a new loader release.

Before you start

Your Tulip contact gives you two values and sets one thing up for you.

  • The host, for example https://tenant.example.com.
  • A publishable key, wdg_pk_ followed by 32 hex characters. It is safe in page source, because it only starts a session from an allowed origin.
  • The allowed origins. Tulip lists every origin that loads the widget, for example https://www.example.com and https://staging.example.com. A page on any other origin gets a setup error.

If your site sends a Content Security Policy, allow these sources.

| Directive | Source | | ------------- | --------------------------------------------------- | | script-src | https://cdn.jsdelivr.net, for the script tag only | | connect-src | your Tulip host, for the session exchange | | frame-src | your Tulip host, for the widget iframe | | img-src | the logo URL, when your launcher shows a logo |

Modes

The widget runs in one of two modes.

  • page draws the widget inline in an element you provide. The frame grows and shrinks with its content.
  • sidePanel adds a launcher button to a bottom corner of the page. The button opens the widget in a 560 px panel, full screen on viewports narrower than 744 px. The launcher appears once the widget has loaded.

Tulip stores a default mode for your site. The mode option overrides it. Set mode in page mode, so the frame can show the setup error when the session exchange fails. Without it, the loader does not know the mode and draws nothing.

Install

Script tag, page mode

<div id="book-appointment"></div>
<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/appointments-widget@1/dist/loader.min.js"></script>
<script>
    const widget = TulipAppointments.init({
        host: 'https://tenant.example.com',
        publishableKey: 'wdg_pk_0123456789abcdef0123456789abcdef',
        mode: 'page',
        container: '#book-appointment',
        locale: document.documentElement.lang,
    });
    widget.on('booked', (booking) => {
        window.dataLayer?.push({ event: 'appointment_booked', bookingUuid: booking.bookingUuid });
    });
</script>

The script sets the global window.TulipAppointments, with init as its only member.

@1 follows every 1.x release after jsDelivr refreshes its cache, which takes up to a day. To use Subresource Integrity, load an exact version such as @1.0.0 with an integrity attribute. You then get fixes only when you change the version.

Bundler, side panel mode

npm install @tulipnpm/appointments-widget
import { init } from '@tulipnpm/appointments-widget';

init({
    host: 'https://tenant.example.com',
    publishableKey: 'wdg_pk_0123456789abcdef0123456789abcdef',
    mode: 'sidePanel',
});

The package is ESM only and ships its own TypeScript types.

React, side panel mode with the store preselected

import { AppointmentsWidget } from '@tulipnpm/appointments-widget/react';

export function StorePage({ storeUuid }: { storeUuid: string }) {
    return (
        <AppointmentsWidget
            host="https://tenant.example.com"
            publishableKey="wdg_pk_0123456789abcdef0123456789abcdef"
            mode="sidePanel"
            context={{ storeUuid }}
            onBooked={(booking) => console.info('booked', booking.bookingUuid)}
        />
    );
}

The component needs React 18 or later. The script tag and the init import need no React.

The component takes the options below except container. In page mode it renders a div, styled through className. In side panel mode it renders nothing and attaches the launcher to document.body. A change to host, publishableKey, mode, locale or colorScheme restarts the widget. A change to context only calls setContext. The onReady, onOpen, onClose, onStepChanged, onBooked and onError props receive the events below. A ref gets the handle.

import { useRef } from 'react';
import type { AppointmentsWidgetHandle } from '@tulipnpm/appointments-widget';
import { AppointmentsWidget } from '@tulipnpm/appointments-widget/react';

export function BookButton() {
    const widgetRef = useRef<AppointmentsWidgetHandle>(null);

    return (
        <>
            <AppointmentsWidget
                ref={widgetRef}
                host="https://tenant.example.com"
                publishableKey="wdg_pk_0123456789abcdef0123456789abcdef"
                mode="sidePanel"
            />
            <button onClick={() => widgetRef.current?.open()}>Book an appointment</button>
        </>
    );
}

Preview releases

Prereleases such as 1.1.0-rc.0 ship under the next dist-tag. A range like @1 does not match a prerelease. Load @next or an exact prerelease instead.

<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/appointments-widget@next/dist/loader.min.js"></script>
npm install @tulipnpm/appointments-widget@next

Options

| Option | Required | Description | | ---------------- | ------------ | --------------------------------------------------------------------------------- | | host | yes | Your Tulip host. Must use https. | | publishableKey | yes | The wdg_pk_ key from Tulip. | | mode | no | page or sidePanel. Overrides the mode stored in Tulip. | | container | in page mode | The element, or a CSS selector for it, that holds the widget. | | locale | no | A BCP 47 tag such as fr-CA. Defaults to the browser language. | | colorScheme | no | light or dark. Defaults to light. dark uses your brand's dark colors. | | context | no | { storeUuid, appointmentTypeUuid, associateUuid }. See Preselect. |

The widget shows the first supported language from locale, then your site's default language, then English.

Preselect

context and setContext preselect parts of the booking. Each field is optional.

  • storeUuid skips the store step when the store takes widget bookings.
  • appointmentTypeUuid skips the type step when the type is offered at the chosen store.
  • associateUuid preselects the associate on the associate step.

When a value matches nothing bookable, the shopper picks as usual. setContext replaces the whole context, so pass every field you want to keep. You can call it before or after ready.

Handle

init returns a handle at once. Events fire later, so handlers you attach right after init see every event.

| Member | Description | | --------------------- | ----------------------------------------------------------------------- | | mode | page, sidePanel, or null until the mode is known. | | open(), close() | Open or close the side panel. No effect in page mode or before ready. | | setContext(context) | Replace the preselected store, type and associate. | | on(event, handler) | Subscribe to an event. Returns a function that unsubscribes. | | destroy() | Remove the widget, the launcher, the session timer and every listener. |

One widget runs per page. A second init destroys the first widget.

Events

| Event | Payload | | --------------- | ------------------------------------------------------------------------------------------------ | | ready | { protocol }, once the widget has loaded. | | open, close | {}, when the side panel opens or closes. | | stepChanged | { step, index, total }. index is zero-based over the steps the shopper sees. | | booked | { bookingUuid, start, end, timeZone, storeUuid, appointmentTypeUuid }. Holds no customer data. | | error | { code, message, fatal }. See below. |

step is one of selectAppointmentMethod, selectStore, selectAppointmentType, selectAssociate, selectDateTime, bookingForm, reviewBooking or bookingConfirmation. start and end are ISO 8601 with an offset, and timeZone is the store's IANA zone.

Errors

| code | fatal | Meaning | | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | setup | yes | The widget cannot start. The page origin is not allowed, the key is wrong, the host is not https or page mode has no container. | | session | yes | The session expired and the loader could not renew it. The widget shows an error. Reload the page. | | configurationUnavailable | no | The widget could not load your site's configuration and runs with the default look. | | translationsUnavailable | no | The widget could not load your copy overrides and runs with the built-in copy. |

On a setup error from the session exchange, the browser console names the page origin and the key prefix. Side panel mode then shows no launcher, and page mode shows a translated error in the frame.

Migrate from @tulipnpm/timekit_project_selector

The two packages can run on the same page and the same tenant, so you can move one site at a time.

  1. Tulip support writes your brand, widget configuration and copy overrides.
  2. Tulip support creates your publishable key and allows your site origins.
  3. Replace the legacy script tags, the booking.js tags and the TimekitProjectSelector init call with one snippet above. The Timekit app_key leaves your page.
  4. Tulip support sets which appointment types the widget offers.

| Legacy | This package | | ------------------------------------------------- | -------------------------------------------------------------------- | | app_key in the page source | publishableKey, which only starts a session from an allowed origin | | addFilter | setContext({ storeUuid, appointmentTypeUuid, associateUuid }) | | popup and embed modes | mode: 'sidePanel' and mode: 'page' | | host CSS that targets widget classes | brand and widget configuration in Tulip, no CSS | | custom UI mode (getStrategy, getStepsFactory) | not offered |