Skip to content

README.md

Latest commit

 

History

History
136 lines (89 loc) · 3.88 KB

README.md

File metadata and controls

136 lines (89 loc) · 3.88 KB
Raw

simple-watch

A lightweight, zero-dependency analog clock widget built with TypeScript and CSS. Supports two themes (light and dark), optional digit display, smooth second-hand animation, and a simple API for attaching, resizing, pausing, and resuming.

Dark watch Light watch

Installation

pnpm add simple-watch
# or
npm install simple-watch
# or
yarn add simple-watch

Usage

1. Include the stylesheet

<link rel="stylesheet" href="node_modules/simple-watch/css/watch.css" />

Or, with a bundler that supports CSS imports:

import 'simple-watch/css';

2. Add a container element

<div class="watch"></div>

3. Instantiate and attach

import { Watch } from 'simple-watch';

const watchEl = document.querySelector('.watch') as HTMLElement;

const watch = new Watch({
  size: 300,
  theme: 'dark',
  showDigits: true,
  smooth: true,
});

watch.attach(watchEl);

Browser (IIFE / UMD)

After running pnpm build, reference the bundled output directly:

<link rel="stylesheet" href="css/watch.css" />
<script src="dist/index.global.js"></script>
<script>
  const watch = new SimpleWatch.Watch({ theme: 'dark', size: 300 });
  watch.attach(document.querySelector('.watch'));
</script>

See the example/ folder for a working demo.

API

new Watch(config?)

Creates a new Watch instance. All configuration options are optional.

Option Type Default Description
smooth boolean false Enables smooth second hand via millisecond interpolation
size number 300 Size of the watch face in pixels
theme 'light' | 'dark' 'light' Visual color theme
showDigits boolean false Show numeric hour labels (1–12) on the watch face

watch.attach(el?)

Renders the watch DOM into el and starts the animation loop. If no element is provided, a new <div> is created and appended to document.body.

watch.setSize(size)

Dynamically resizes the watch face to size pixels. Digit font sizes are updated automatically.

watch.suspend()

Pauses the animation loop. The watch face stays visible but frozen at the last rendered time.

watch.resume()

Resumes the animation loop after suspend() has been called.

Development

pnpm install
pnpm build         # compile TypeScript → dist/
pnpm lint          # run ESLint
pnpm lint:fix      # auto-fix ESLint issues
pnpm format        # format with Prettier
pnpm format:check  # check formatting without writing
pnpm release       # run semantic-release locally (CI does this on main)

Open example/index.html in a browser after running pnpm build.

Automated Releases

This project uses Semantic Release and GitHub Actions to publish GitHub Releases automatically.

  • Trigger: every push to main (including merged PRs)
  • Output: a new Git tag + GitHub Release with autogenerated notes
  • Changelog: CHANGELOG.md is updated and committed by the release workflow

Commit message guidance

Semantic Release determines version bumps from commit messages. Conventional-style commits are recommended (feat:, fix:, etc.).

For this repository, release rules are configured so non-breaking commits also produce at least a patch release on main.

Author

👤 Hajanirina Ridjvan Randrianandraina

Show your support

Give a ⭐️ if this project helped you!

License

MIT