world-clock-strip 0.2.0

package/README.md

@@ -0,0 +1,204 @@
+# 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
+
+If the repo is private, install from GitHub with access:
+
+```bash
+npm install git+ssh://git@github.com/steve777/World-Clock.git
+```
+
+For local development in this repo:
+
+```bash
+npm install
+```
+
+## Run
+
+```bash
+npm run dev
+```
+
+Open [http://127.0.0.1:4173](http://127.0.0.1:4173).
+
+## Build
+
+```bash
+npm run build
+```
+
+```bash
+npm run build:demo
+```
+
+```bash
+npm run test
+```
+
+```bash
+npm run test:package
+```
+
+## Basic Usage
+
+```ts
+import { defineWorldClockStrip } from "world-clock-strip";
+
+defineWorldClockStrip();
+```
+
+```html
+<world-clock-strip></world-clock-strip>
+```
+
+## Imperative Usage
+
+```ts
+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`
+- `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:
+
+```ts
+import {
+  serializeWorldClockConfig,
+  deserializeWorldClockConfig,
+} from "world-clock-strip";
+```
+
+## Events
+
+The component dispatches `configchange`:
+
+```ts
+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:
+
+```html
+<world-clock-strip read-only></world-clock-strip>
+```
+
+Or:
+
+```ts
+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:
+
+```ts
+clock.weatherEndpoint = "/api/weather/clocks";
+```
+
+## Docker
+
+```bash
+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.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { WORLD_CLOCK_TAG_NAME, WorldClockStripElement, createWorldClockStrip, deserializeWorldClockConfig, defaultClockLocations, defineWorldClockStrip, getFallbackWeatherCondition, isDaytimeWeather, mapWeatherCode, normalizeClockLocations, serializeWorldClockConfig, } from "./world-clock";
+export type { ClockLocation, ClockWeatherSnapshot, CommonClockCity, VisualPreset, WorldClockConfig, WorldClockStripOptions, } from "./world-clock";