bdd-use-countdown/README.md

React hook encapsulating countdown functionality

# 🕒 useCountdown

A lightweight React hook to run a live countdown between two [DateX](https://www.npmjs.com/package/bdd-date-ext) instances.

Built with TypeScript and designed to integrate seamlessly into React apps using `bdd-date-ext`.

---

## 📦 Installation

```bash
npm install use-countdown-hook
```

This package depends on `bdd-date-ext`, which will be installed automatically.

## 🔧 Usage

```tsx
import { useCountdown } from 'use-countdown-hook';
import { DateX } from 'bdd-date-ext';

const CountdownComponent = () => {
  const countdownEnd = new DateX().shift(5, "minute"); // 5 minutes from NOW
  
  const values = useCountdown({
    end: countdownEnd,
    onEnd: () => console.log("Time's up!"),
    timedActions: [
      {
        timestamp: countdownEnd.shift(-1, "minute"),
        action: () => console.log("Only 1 minute left!"),
      },
    ],
  });

  return (
    <div>
      <p>{values.days}d {values.hours}h {values.minutes}m {values.seconds}s</p>
    </div>
  );
};
```

## 🧠 Hook Signature

```tsx
useCountdown(args: {
  start?: DateX; // default = new DateX()
  end: DateX;
  onStart?: (start: DateX) => void;
  onEnd?: (end: DateX) => void;
  timedActions?: { timestamp: DateX, action: (timestamp: DateX) => void }[];
}): {
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  milliseconds: number;
}
```

## ✅ Features

- ⏱ Starts automatically from start (or now)
- 📌 onStart and onEnd lifecycle callbacks
- 🔔 Supports timed actions (e.g., alert 1 min before end)
- 🧪 Fully typed (TypeScript ready)
- 💡 Based on bdd-date-ext for improved date manipulation

## 📄 License
MIT