@leelaing/live-clock

Reusable timezone-aware live date and time utilities with a React hook and an unstyled React clock component.

The package owns date/time behavior, not visual design. It does not ship CSS or depend on Tailwind, DaisyUI, Bootstrap, Material UI, Electron, Tauri, or application-specific styling.

Install

npm install @leelaing/live-clock

React consumers must provide React 18 or newer.

Core Utilities

import { formatDate, formatDateTime, formatTime } from '@leelaing/live-clock';

const now = new Date();

formatDate(now, {
  locale: 'en-US',
  timeZone: 'America/New_York',
  dateFormat: 'long',
  weekday: true
});

formatTime(now, {
  locale: 'en-US',
  timeZone: 'Europe/London',
  timeFormat: '24h',
  seconds: true,
  timeZoneName: 'short'
});

formatDateTime(now, {
  timeZone: 'Australia/Perth',
  separator: '@'
});

React Hook

import { useLiveClock } from '@leelaing/live-clock';

function HeaderClock() {
  const clock = useLiveClock({
    timeZone: 'America/Los_Angeles',
    timeFormat: 'auto'
  });

  return <time dateTime={clock.iso}>{clock.dateTime}</time>;
}

The hook returns structured data:

{
  now,
  timestamp,
  iso,
  date,
  time,
  dateTime,
  timeZone,
  timeZoneName
}

Unstyled Component

import { LiveClock } from '@leelaing/live-clock';

<LiveClock
  layout="inline"
  timeZone="America/New_York"
  timeFormat="12h"
  timeZoneName="short"
/>

Supported layouts:

• inline
• date-top
• time-top
• date-only
• time-only

Stable selectors and attributes are exposed for consuming applications:

• lee-live-clock
• lee-live-clock__date
• lee-live-clock__time
• lee-live-clock__separator
• lee-live-clock__timezone
• data-live-clock
• data-layout
• data-time-format
• data-time-zone

No styles are attached to those selectors.

Development

npm install
npm start

Quality Checks

npm run check

npm run check runs:

1. TypeScript type checking
2. ESLint
3. Tests
4. Production build

Standard Commands

| Command | Purpose | | --- | --- | | npm start | Build/watch during development | | npm run dev | Alias for npm start | | npm run build | Production build | | npm test | Run tests once | | npm run test:watch | Run tests in watch mode | | npm run lint | Lint source | | npm run typecheck | TypeScript validation | | npm run format | Format files | | npm run check | Run all validation | | npm run clean | Remove generated output |

License

MIT