@bktl/zen-countdown

A mountable countdown timer widget with pluggable number-base display (decimal, binary, octal, hex, base64) and an optional recurring "next brief" schedule mode. Zero dependencies, plain ESM, styles are injected automatically.

Install

npm install @bktl/zen-countdown

Usage

import { mountCountdown } from "@bktl/zen-countdown";

const countdown = mountCountdown(document.getElementById("app"), {
  duration: 60, // seconds
});

countdown.start();

Call countdown.destroy() to remove the widget and its listeners.

Options

| Option | Default | Description | | ----------------- | ------------------------------------ | -------------------------------------------------------------------| | duration | 60 | Countdown length in seconds ("countdown" mode only). | | mode | "countdown" | "countdown" or "next-brief". | | briefHours | [8, 17] | Local hours (0–23), Mon–Fri, the schedule fires at ("next-brief").| | title | derived | Heading text. | | format | "decimal" | Initial number format. | | formats | all of FORMATS | Which format toggle buttons to show. | | muteStorageKey | "zen.alarmMuted" | localStorage key used to persist the mute toggle. | | onFinish | — | Called each time the countdown/brief hits zero. |

Controller

mountCountdown() returns:

• start() / reset() — control the countdown (no-op in "next-brief" mode).
• setFormat(key) — switch number format programmatically.
• destroy() — unmount and clean up.
• el — the root element, if you need to reposition or style around it.

FORMATS

The raw format table ({ [key]: { label, render(n) } }) is also exported if you want to render numbers yourself without mounting the widget.

Development

index.html in this repo is a live demo — open it directly or serve it with any static file server. Append ?next to the URL to see the "next brief" mode.