World Clock Strip

Reusable world-clock-strip web component extracted from the Dashboard web app. It ships with animated weather art, moving day-cycle background, editable locations, sharing tools, presets, and a bottom config drawer.

Features

• Shadow DOM custom element: world-clock-strip
• Default cities: Las Vegas, Israel, New Delhi, Macau, Sydney
• Built-in client-side weather via Open-Meteo
• Optional backend weather endpoint override
• Shareable URL state
• JSON import/export
• Saved presets in local storage
• Optional persistent local config
• Optional read-only mode
• Visual presets: default, minimal, cinematic, wallboard
• configchange event for host apps

Install

Install from npm:

npm install world-clock-strip

If you want to install directly from GitHub instead:

npm install git+ssh://[email protected]/steve777/World-Clock.git

For local development in this repo:

npm install

Run

npm run dev

Open http://127.0.0.1:4173.

Build

npm run build

npm run build:demo

npm run test

npm run test:package

Basic Usage

import { defineWorldClockStrip } from "world-clock-strip";

defineWorldClockStrip();

<world-clock-strip></world-clock-strip>

Imperative Usage

import { createWorldClockStrip } from "world-clock-strip";

const clock = createWorldClockStrip({
  locations: [
    { label: "Las Vegas", timeZone: "America/Los_Angeles", weatherQuery: "Las Vegas, Nevada" },
    { label: "London", timeZone: "Europe/London", weatherQuery: "London, United Kingdom" }
  ],
  weatherEnabled: true,
  visualPreset: "cinematic",
  persistKey: "executive-clock",
  enableUrlState: true,
});

document.body.append(clock);

Public API

Exports:

• defineWorldClockStrip()
• createWorldClockStrip()
• normalizeClockLocations()
• serializeWorldClockConfig()
• deserializeWorldClockConfig()
• defaultClockLocations

Types:

• ClockLocation
• ClockWeatherSnapshot
• CommonClockCity
• VisualPreset
• WorldClockConfig
• WorldClockStripOptions

Config Options

WorldClockStripOptions supports:

• locations
• weatherEnabled
• weatherEndpoint
• weatherAssetBaseUrl
• weatherOverrides
• visualPreset
• readOnly
• persistKey
• enableUrlState
• shareQueryParam
• cityCatalog

Temperature units are automatic:

• U.S. system time zones show F
• all other system time zones show C

Sharing

The drawer supports:

• Share: copies a URL with encoded clock config
• JSON: copy current config JSON or import one
• Saved presets: save, load, and delete local presets

You can also use the helpers directly:

import {
  serializeWorldClockConfig,
  deserializeWorldClockConfig,
} from "world-clock-strip";

Events

The component dispatches configchange:

clock.addEventListener("configchange", (event) => {
  const detail = (event as CustomEvent).detail;
  console.log(detail.config, detail.source);
});

detail.source is one of:

• api
• drawer
• url
• storage
• preset
• attribute

Read-Only Mode

Hide the config drawer entirely:

<world-clock-strip read-only></world-clock-strip>

Or:

clock.readOnly = true;

Weather Source

Most apps do not need a backend endpoint. If weatherEnabled is on and weatherEndpoint is blank, the component fetches weather itself.

If your app already has a backend route:

clock.weatherEndpoint = "/api/weather/clocks";

By default, the published package loads weather art from the package CDN so installed consumers render correctly without extra asset copying.

If you want to self-host the weather art instead:

clock.weatherAssetBaseUrl = "/vendor/world-clock/weather/";

Docker

docker build -t world-clock-strip .
docker run --rm -p 4173:4173 world-clock-strip

Notes

• The drawer stores presets in local storage.
• persistKey stores the current config in local storage.
• If both persisted state and shared URL state exist, the shared URL wins.
• The weather art bundle is much smaller than before, but the package still benefits from continued asset optimization.
• npm run test:package validates the packed tarball in a clean temporary install.