World Clock Strip

Reusable world-clock-strip web component extracted from the Dashboard web app. It presents a compact city/time display with optional city landmarks, a 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, Manila, Gold Coast
• City and local time only, with no weather, date, or temperature display
• Compact 55px desktop clock band
• 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
• Click or keyboard-activate the clock band to cycle plain and landmarks backgrounds
• Extensible exported background registry: clockBackgrounds
• 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" },
    { label: "London", timeZone: "Europe/London" }
  ],
  visualPreset: "cinematic",
  backgroundMode: "landmarks",
  persistKey: "executive-clock",
  enableUrlState: true,
});

document.body.append(clock);

Public API

Exports:

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

Types:

• ClockLocation
• ClockBackground
• ClockBackgroundOption
• CommonClockCity
• VisualPreset
• WorldClockConfig
• WorldClockStripOptions

Config Options

WorldClockStripOptions supports:

• locations
• landmarkAssetBaseUrl
• visualPreset
• backgroundMode
• readOnly
• persistKey
• enableUrlState
• shareQueryParam
• cityCatalog

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
• background

Read-Only Mode

Hide the config drawer entirely:

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

Or:

clock.readOnly = true;

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.
• Weather artwork is no longer rendered or included in the published package.
• npm run test:package validates the packed tarball in a clean temporary install.