### ES Module Installation and Usage of simplycountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Demonstrates how to install and use simplycountdown.js via npm within an ES Module environment. It covers basic import, CSS inclusion, initializing the countdown after the DOM is loaded, and provides specific examples for Vue 3 and React component integration. Includes instructions for installing the package.

```javascript
// Install via npm
// npm install simplycountdown.js

// Basic import and usage
import simplyCountdown from "simplycountdown.js";
import "simplycountdown.js/dist/themes/default.css";

// Initialize after DOM load
document.addEventListener("DOMContentLoaded", () => {
    simplyCountdown(".countdown", {
        year: 2025,
        month: 12,
        day: 25
    });
});

// Vue 3 component usage
import { onMounted, ref } from "vue";
import simplyCountdown from "simplycountdown.js";

export default {
    setup() {
        const countdownRef = ref(null);

        onMounted(() => {
            const controller = simplyCountdown(countdownRef.value, {
                year: 2025,
                month: 6,
                day: 1,
                onEnd: () => {
                    console.log("Countdown finished");
                }
            });
        });

        return { countdownRef };
    }
};

// React component usage
import React, { useEffect, useRef } from "react";
import simplyCountdown from "simplycountdown.js";

function CountdownTimer() {
    const countdownRef = useRef(null);

    useEffect(() => {
        const controller = simplyCountdown(countdownRef.current, {
            year: 2025,
            month: 12,
            day: 31,
            zeroPad: true
        });

        return () => {
            controller.stopCountdown();
        };
    }, []);

    return <div ref={countdownRef} className="simply-countdown-circle"></div>;
}
```

--------------------------------

### Build Documentation Site

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This command generates the documentation website for the simplycountdown.js project, providing guides, examples, and API references.

```bash
npm run build:docs
```

--------------------------------

### Install Development Dependencies with Bun

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/CONTRIBUTING.md

Installs the necessary project dependencies using the Bun package manager. Bun is recommended for its performance and seamless dependency management.

```bash
bun install
```

--------------------------------

### Install SimplyCountdown.js using Package Managers

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Instructions for installing the simplycountdown.js package using npm, yarn, or bun. These commands are used to add the library to your project's dependencies.

```bash
npm install simplycountdown.js
# or
yarn add simplycountdown.js
# or
bun install simplycountdown.js
```

--------------------------------

### Start Development Server

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/CONTRIBUTING.md

Runs a development server with Vite, which automatically updates sources from `src/core` and allows testing new features in the `docs/src` directory. Changes in the documentation files will refresh the development page.

```bash
bun run dev
```

--------------------------------

### Prepare HTML for SimplyCountdown.js

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Example HTML structure required to initialize SimplyCountdown.js. A target div with a specific class is needed to host the countdown timer.

```html
<!-- ...YOUR HTML CODE -->
<div class="my-super-countdown simply-countdown-circle"></div>
<!-- YOUR HTML CODE... -->
```

--------------------------------

### Install simplyCountdown.js with npm, yarn, pnpm, or bun

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

This snippet demonstrates how to install the simplyCountdown.js library using various popular JavaScript package managers. It shows the specific commands for npm, yarn, pnpm, and bun.

```bash
npm install simplycountdown.js
```

```bash
yarn add simplycountdown.js
```

```bash
pnpm install simplycountdown.js
```

```bash
bun install simplycountdown.js
```

--------------------------------

### SimplyCountdown.js Configuration Options

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Detailed example of how to configure SimplyCountdown.js with various options. This includes setting the target date, customizing words, display options, styling classes, formatting, and event handlers.

```javascript
// .my-super-countdown is an example
// you can target any HTML element with any CSS selector
simplyCountdown(".my-super-countdown", {
    // Target date (Required)
    year: 2025, // Target year [YYYY]
    month: 12, // Target month [1-12]
    day: 25, // Target day [1-31]
    hours: 0, // Target hours [0-23]
    minutes: 0, // Target minutes [0-59]
    seconds: 0, // Target seconds [0-59]

    // Words customization
    words: {
        days: {
            // Function to handle pluralization
            lambda: (root, count) => (count > 1 ? root + "s" : root),
            root: "day", // Base word for days
        },
        hours: {
            lambda: (root, count) => (count > 1 ? root + "s" : root),
            root: "hour",
        },
        minutes: {
            lambda: (root, count) => (count > 1 ? root + "s" : root),
            root: "minute",
        },
        seconds: {
            lambda: (root, count) => (count > 1 ? root + "s" : root),
            root: "second",
        },
    },

    // Display options
    plural: true, // Enable/disable pluralization
    inline: false, // Display inline (true) or in blocks (false)
    inlineSeparator: ", ", // Separator for inline display
    enableUtc: false, // Use UTC time instead of local time

    // Styling classes
    inlineClass: "simply-countdown-inline", // Class for inline display
    sectionClass: "simply-section", // Class for each time unit section
    amountClass: "simply-amount", // Class for number display
    wordClass: "simply-word", // Class for word display

    // Formatting options
    zeroPad: false, // Add leading zeros to numbers (e.g., 05 instead of 5)
    countUp: false, // Count up from target date instead of down to it
    removeZeroUnits: false, // Hide time units when they reach zero
    refresh: 1000, // Update interval in milliseconds (1 second = 1000)

    // Event handlers
    onEnd: () => {
        // Callback function when countdown ends
        console.log("Countdown finished!");
    },
    onStop: () => {}, // Callback when countdown is stopped
    onResume: () => {}, // Callback when countdown is resumed
    onUpdate: (params) => {}, // Callback when countdown is updated
});
```

--------------------------------

### Initialize SimplyCountdown.js using CommonJS

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Example of initializing SimplyCountdown.js using CommonJS module syntax. This is typically used in Node.js environments or older JavaScript projects.

```javascript
const simplyCountdown = require("simplycountdown");

simplyCountdown(".my-super-countdown", {
    year: 2025,
    month: 12,
    day: 25,
});
```

--------------------------------

### Initialize SimplyCountdown.js using ES Module

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Basic usage example demonstrating how to initialize SimplyCountdown.js using ES Module syntax. It requires importing the library and calling the simplyCountdown function with a target selector and configuration options.

```javascript
import simplyCountdown from "simplycountdown.js";

simplyCountdown(".my-super-countdown", {
    year: 2025,
    month: 12,
    day: 25,
});
```

--------------------------------

### ES Module Usage (JavaScript)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/dist/index.html

Demonstrates initializing a countdown timer using ES module syntax. This example covers various configuration options, including target date, custom labels, inline formatting, UTC enablement, refresh intervals, and callback functions for different events.

```javascript
import simplyCountdown from 'simplycountdown.js';

// This is an example with default parameters
simplyCountdown('[CSS-SELECTOR]', {
    year: 2015, // Target year (required)
    month: 6, // Target month [1-12] (required)
    day: 28, // Target day [1-31] (required)
    hours: 0, // Target hour [0-23], default: 0
    minutes: 0, // Target minute [0-59], default: 0
    seconds: 0, // Target second [0-59], default: 0
    words: { // Custom labels, with lambda for plurals
        days: { root: 'day', lambda: (root, n) => n > 1 ? root + 's' : root },
        hours: { root: 'hour', lambda: (root, n) => n > 1 ? root + 's' : root },
        minutes: { root: 'minute', lambda: (root, n) => n > 1 ? root + 's' : root },
        seconds: { root: 'second', lambda: (root, n) => n > 1 ? root + 's' : root }
    },
    plural: true, // Use plurals for labels
    inline: false, // Inline format: e.g., "24 days, 4 hours, 2 minutes"
    inlineSeparator: ', ', // Separator for inline format, default: ", "
    inlineClass: 'simply-countdown-inline', // CSS class for inline countdown
    enableUtc: false, // Use UTC time if true
    refresh: 1000, // Refresh interval in ms, default: 1000
    sectionClass: 'simply-section', // CSS class for each countdown section
    amountClass: 'simply-amount', // CSS class for numeric values
    wordClass: 'simply-word', // CSS class for unit labels
    zeroPad: false, // Pad numbers with leading zero
    removeZeroUnits: false, // Remove units with zero value
    countUp: false, // Count up after reaching zero
    onEnd: () => {}, // Callback when countdown ends
    onStop: () => {}, // Callback when countdown is stopped
    onResume: () => {}, // Callback when countdown is resumed
    onUpdate: (params) => {} // Callback when countdown is updated
});

// Also, you can init with already existing Javascript Object.
let myElement = document.querySelector('.my-countdown');
simplyCountdown(myElement, { /* options */ });

let multipleElements = document.querySelectorAll('.my-countdown');
simplyCountdown(multipleElements, { /* options */ });

```

--------------------------------

### CommonJS Usage (JavaScript)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/dist/index.html

Illustrates how to import and initialize the simplyCountdown library using the CommonJS module system, typically found in Node.js environments or older build setups. It shows a basic initialization with required options.

```javascript
const simplyCountdown = require("simplycountdown.js");

simplyCountdown("#mycountdown", {
    year: 2025,
    month: 12,
    day: 25,
});

```

--------------------------------

### JavaScript - ES Module Usage with Default Parameters

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Shows how to initialize simplyCountdown.js using ES modules. This example uses default parameters for the countdown and demonstrates importing the library. It also includes comments explaining the purpose of various configuration options.

```javascript
import simplyCountdown from 'simplycountdown.js';

// This is an example with default parameters
simplyCountdown('[CSS-SELECTOR]', {
    year: 2015, // Target year (required)
    month: 6, // Target month [1-12] (required)
    day: 28, // Target day [1-31] (required)
    hours: 0, // Target hour [0-23], default: 0
    minutes: 0, // Target minute [0-59], default: 0
    seconds: 0, // Target second [0-59], default: 0
    words: { // Custom labels, with lambda for plurals
        days: { root: 'day', lambda: (root, n) => n > 1 ? root + 's' : root },
        hours: { root: 'hour', lambda: (root, n) => n > 1 ? root + 's' : root },
        minutes: { root: 'minute', lambda: (root, n) => n > 1 ? root + 's' : root },
        seconds: { root: 'second', lambda: (root, n) => n > 1 ? root + 's' : root }
    },
    plural: true, // Use plurals for labels
    inline: false, // Inline format: e.g., "24 days, 4 hours, 2 minutes"
    inlineSeparator: ', ', // Separator for inline format, default: ", "
    inlineClass: 'simply-countdown-inline', // CSS class for inline countdown
    enableUtc: false, // Use UTC time if true
    refresh: 1000, // Refresh interval in ms, default: 1000
    sectionClass: 'simply-section', // CSS class for each countdown section
    amountClass: 'simply-amount', // CSS class for numeric values
    wordClass: 'simply-word', // CSS class for unit labels
    zeroPad: false, // Pad numbers with leading zero
    removeZeroUnits: false, // Remove units with zero value
    countUp: false, // Count up after reaching zero
    onEnd: () => {}, // Callback when countdown ends
    onStop: () => {}, // Callback when countdown is stopped
    onResume: () => {}, // Callback when countdown is resumed
    onUpdate: (params) => {} // Callback when countdown is updated
});

// Also, you can init with already existing Javascript Object.
let myElement = document.querySelector('.my-countdown');
simplyCountdown(myElement, { /* options */ });

let multipleElements = document.querySelectorAll('.my-countdown');
simplyCountdown(multipleElements, { /* options */ });
```

--------------------------------

### Clone SimplyCountdown.js Repository

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/CONTRIBUTING.md

Clones the SimplyCountdown.js repository to your local machine. This is the first step after forking the project to start making contributions.

```bash
git clone git@github.com:your-username/simplyCountdown.js.git
cd simplyCountdown.js
```

--------------------------------

### CSS for Customizing Themes

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Provides example CSS selectors for customizing the appearance of SimplyCountdown.js. This allows for creating unique themes by overriding default styles for various countdown components.

```css
.custom-countdown-theme {
    /* Main countdown container */
}

.custom-countdown-theme > .simply-section {
    /* Individual time unit blocks */
}

.custom-countdown-theme > .simply-section > div {
    /* Inner container for amount and word */
}

.custom-countdown-theme > .simply-section .simply-amount,
.custom-countdown-theme > .simply-section .simply-word {
    /* Common styles for numbers and labels */
}

.custom-countdown-theme > .simply-section .simply-amount {
    /* Number display */
}

.custom-countdown-theme > .simply-section .simply-word {
    /* Label text */
}
```

--------------------------------

### Countdown with Controls (JavaScript)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/dist/index.html

This example demonstrates how to initialize a countdown timer with control functionalities like stop, resume, and how to handle updates and state changes. It uses callbacks to update an external state box with the current countdown state.

```javascript
// Example 8: With controls
const controlDemo = simplyCountdown('.simply-countdown-control', {
    year: nextYear,
    month: nextMonth,
    day: 27,
    zeroPad: false,
    enableUtc: true,
    onUpdate: () => {
        updateStateBox(controlDemo.getState());
    },
    onResume: () => {
        updateStateBox(controlDemo.getState());
    },
    onStop: () => {
        updateStateBox(controlDemo.getState());
    }
});

const updateStateBox = (state) => {
    let stateBox = document.querySelector('.state-box');
    stateBox.innerHTML = JSON.stringify(state, null, 2);
}

updateStateBox(controlDemo.getState());
// Not a conventional declaration, but it's useful for the demo
window.controlDemo = controlDemo;

```

--------------------------------

### JavaScript - Control Example with Stop/Resume

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Demonstrates how to use controls (stop, resume) with simplyCountdown.js. It initializes a countdown, updates a state box with the current state on various callbacks (update, resume, stop), and exposes the countdown instance globally for manual control.

```javascript
const controlDemo = simplyCountdown('.simply-countdown-control', {
    year: nextYear,
    month: nextMonth,
    day: 27,
    zeroPad: false,
    enableUtc: true,
    onUpdate: () => {
        updateStateBox(controlDemo.getState());
    },
    onResume: () => {
        updateStateBox(controlDemo.getState());
    },
    onStop: () => {
        updateStateBox(controlDemo.getState());
    }
});

const updateStateBox = (state) => {
    let stateBox = document.querySelector('.state-box');
    stateBox.innerHTML = JSON.stringify(state, null, 2);
}

updateStateBox(controlDemo.getState());
// Not a conventional declaration, but it's useful for the demo
window.controlDemo = controlDemo;
```

--------------------------------

### Import SimplyCountdown.js Source Files (TypeScript)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Example of how to import the TypeScript source files directly if you need to compile them within your project. This approach allows for deeper integration and customization of the library's source code.

```typescript
import simplyCountdown from "simplycountdown.js/src/core/simplyCountdown";
```

--------------------------------

### Managing Multiple Countdown Instances

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Illustrates how to manage multiple countdown instances simultaneously using simplycountdown.js. This includes creating and controlling individual timers for different events and a utility to pause or resume all timers. It also shows an example of auto-initializing countdowns based on data attributes.

```javascript
import simplyCountdown from "simplycountdown.js";

// Create multiple countdowns
const controllers = {
    christmas: simplyCountdown("#christmas-timer", {
        year: 2025,
        month: 12,
        day: 25,
        onEnd: () => console.log("Merry Christmas!")
    }),

    newyear: simplyCountdown("#newyear-timer", {
        year: 2026,
        month: 1,
        day: 1,
        onEnd: () => console.log("Happy New Year!")
    }),

    birthday: simplyCountdown("#birthday-timer", {
        year: 2025,
        month: 6,
        day: 15,
        countUp: true
    })
};

// Control all countdowns
function pauseAll() {
    Object.values(controllers).forEach(c => c.stopCountdown());
}

function resumeAll() {
    Object.values(controllers).forEach(c => c.resumeCountdown());
}

// Auto-initialize all countdown elements
document.querySelectorAll("[data-countdown]").forEach(element => {
    const target = element.dataset.countdown;
    const [year, month, day] = target.split("-").map(Number);

    simplyCountdown(element, {
        year,
        month,
        day,
        zeroPad: true
    });
});
```

--------------------------------

### Custom Russian Pluralization for simplyCountdown.js

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

This example shows how to configure simplyCountdown.js to use custom Russian pluralization rules for days, hours, minutes, and seconds. It includes a helper function `pluralizeRus` to handle the complex Russian pluralization logic.

```javascript
// Example 7: with custom Russian pluralization
    simplyCountdown('#custom-plural', {
        // some parameters...
        words: {
            days: {
                lambda: (root, n) => pluralizeRus(n, 'день', 'дня', 'дней'),
                root: 'день'
            },
            hours: {
                lambda: (root, n) => pluralizeRus(n, 'час', 'часа', 'часов'),
                root: 'час'
            },
            minutes: {
                lambda: (root, n) => pluralizeRus(n, 'минута', 'минуты', 'минут'),
                root: 'минута'
            },
            seconds: {
                lambda: (root, n) => pluralizeRus(n, 'секунда', 'секунды', 'секунд'),
                root: 'секунда'
            }
        }
    });

    function pluralizeRus(number, singular, genitiveSingular, genitivePlural) {
        const lastDigit = number % 10;
        const lastTwoDigits = number % 100;

        if (lastTwoDigits >= 11 && lastTwoDigits <= 14) {
            return `${genitivePlural}`;
        }

        if (lastDigit === 1 && lastTwoDigits !== 11) {
            return `${singular}`;
        }

        if (lastDigit >= 2 && lastDigit <= 4 && !(lastTwoDigits >= 12 && lastTwoDigits <= 14)) {
            return `${genitiveSingular}`;
        }

        return `${genitivePlural}`;
    }
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Starts the test runner in watch mode, which automatically re-runs tests whenever code changes are detected, facilitating rapid development and debugging.

```bash
npm run test:watch
```

--------------------------------

### Count-Up Timer with simplyCountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Illustrates how to configure simplyCountdown.js to count up from a past date using the `countUp: true` option. This is ideal for displaying elapsed time. Examples include tracking project age and event durations, with options for zero-padding and custom unit formatting.

```javascript
import simplyCountdown from "simplycountdown.js";

// Count up from project start date
simplyCountdown("#project-age", {
    year: 2023,
    month: 1,
    day: 15,
    countUp: true,
    zeroPad: true,
    removeZeroUnits: false
});

// Event timer with milestones
const eventTimer = simplyCountdown("#event-timer", {
    year: 2024,
    month: 6,
    day: 1,
    hours: 9,
    minutes: 0,
    countUp: true,
    onEnd: () => {
        // In count-up mode, onEnd is not called
    }
});

// Track time since account creation
simplyCountdown("#member-since", {
    year: 2022,
    month: 3,
    day: 20,
    countUp: true,
    inline: true,
    inlineSeparator: " : ",
    words: {
        days: { lambda: (r, n) => "d", root: "" },
        hours: { lambda: (r, n) => "h", root: "" },
        minutes: { lambda: (r, n) => "m", root: "" },
        seconds: { lambda: (r, n) => "s", root: "" }
    }
});
// Output: "1095 d : 12 h : 45 m : 30 s"
```

--------------------------------

### SimplyCountdown.js Generated HTML Structure (Block Display)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Example of the HTML structure generated by SimplyCountdown.js in its default block display mode. This shows how the countdown is broken down into sections for days, hours, minutes, and seconds.

```html
<div class="simply-countdown">
    <div class="simply-section">
        <div>
            <span class="simply-amount">24</span>
            <span class="simply-word">days</span>
        </div>
    </div>
    <!-- Similar sections for hours, minutes, seconds -->
</div>
```

--------------------------------

### JavaScript Custom Words Countdown

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Configures a countdown timer with custom labels for days, hours, minutes, and seconds. This example demonstrates dynamic word generation using lambda functions for singular and plural forms and sets up inline display with a custom separator.

```javascript
simplyCountdown("#inline", {
    year: 2025,
    month: 12,
    day: 25,
    inline: true,
    inlineSeparator: " | ",
    words: {
        days: {
            lambda: (root, count) => (count === 1 ? "day" : "days"),
            root: "day",
        },
        hours: {
            lambda: (root, count) => (count === 1 ? "hour" : "hours"),
            root: "hour",
        },
        minutes: {
            lambda: (root, count) => (count === 1 ? "minute" : "minutes"),
            root: "minute",
        },
        seconds: {
            lambda: (root, count) => (count === 1 ? "second" : "seconds"),
            root: "second",
        },
    },
});
```

--------------------------------

### CommonJS Node.js Usage for Server-Side Countdown

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Demonstrates how to use simplycountdown.js in a CommonJS Node.js environment for server-side countdown calculations and integration with an Express.js API endpoint. It includes functions for calculating remaining time and an example API route to serve countdown data.

```javascript
// CommonJS require
const simplyCountdown = require("simplycountdown.js");

// Server-side countdown calculation
function getCountdownData(targetDate) {
    const now = new Date();
    const target = new Date(targetDate);
    const diff = target.getTime() - now.getTime();

    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
    const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
    const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
    const seconds = Math.floor((diff % (1000 * 60)) / 1000);

    return { days, hours, minutes, seconds };
}

// Express.js API endpoint
app.get("/api/countdown/:eventId", (req, res) => {
    const event = getEventById(req.params.eventId); // Assuming getEventById is defined elsewhere
    const countdownData = getCountdownData(event.date);

    res.json({
        event: event.name,
        countdown: countdownData,
        hasEnded: countdownData.days < 0
    });
});
```

--------------------------------

### UTC Timezone Countdown with simplyCountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Explains how to use the `enableUtc: true` option to perform countdown calculations based on Coordinated Universal Time (UTC). This ensures the countdown is consistent across different timezones, suitable for global events or product launches. Includes examples with `onEnd` callbacks for actions upon completion.

```javascript
import simplyCountdown from "simplycountdown.js";

// Global product launch countdown
simplyCountdown("#launch-countdown", {
    year: 2025,
    month: 6,
    day: 1,
    hours: 0,
    minutes: 0,
    seconds: 0,
    enableUtc: true,
    zeroPad: true,
    onEnd: () => {
        window.location.href = "/launch";
    }
});

// Synchronized event across timezones
simplyCountdown("#global-event", {
    year: 2025,
    month: 12,
    day: 31,
    hours: 23,
    minutes: 59,
    seconds: 59,
    enableUtc: true,
    inline: false,
    onEnd: () => {
        console.log("Happy New Year!");
        fetch("/api/event/triggered", { method: "POST" });
    }
});
```

--------------------------------

### Get Countdown State with simplyCountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Demonstrates how to retrieve the current state of a countdown, including pause status, interval reference, and target date. This is useful for debugging, saving, and restoring countdown states. It uses `setInterval` to periodically log state information and `localStorage` to persist it.

```javascript
import simplyCountdown from "simplycountdown.js";

const countdown = simplyCountdown("#timer", {
    year: 2025,
    month: 12,
    day: 25
});

// Check state periodically
setInterval(() => {
    const state = countdown.getState();
    console.log("Is Paused:", state.isPaused);
    console.log("Target Date:", state.targetDate);
    console.log("Has Active Interval:", state.interval !== null);

    // Store state in localStorage
    localStorage.setItem("countdownState", JSON.stringify({
        isPaused: state.isPaused,
        targetDate: state.targetDate.toISOString()
    }));
}, 5000);

// Toggle based on state
document.getElementById("toggleBtn").addEventListener("click", () => {
    const state = countdown.getState();
    if (state.isPaused) {
        countdown.resumeCountdown();
    } else {
        countdown.stopCountdown();
    }
});
```

--------------------------------

### Generate and Serve Test Files Locally

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Generates test files for different module formats and then serves them locally using a development server, allowing for easy testing of module compatibility in a browser environment.

```bash
npm run dist:test:serve
```

--------------------------------

### Apply Ready-to-use Themes - HTML & JavaScript

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/dist/index.html

Implement pre-built themes for SimplyCountdown.js by linking the appropriate CSS files and applying corresponding classes to your countdown elements. This allows for quick visual customization.

```html
<link rel="stylesheet" href="dist/themes/default.css">
<link rel="stylesheet" href="dist/themes/dark.css">
<link rel="stylesheet" href="dist/themes/cyber.css">
<link rel="stylesheet" href="dist/themes/losange.css">
<link rel="stylesheet" href="dist/themes/circle.css">

<div class="my-countdown simply-countdown"></div>
<div class="my-countdown simply-countdown-dark"></div>
<div class="my-countdown simply-countdown-cyber"></div>
<div class="my-countdown simply-countdown-losange"></div>
<div class="my-countdown simply-countdown-circle"></div>

<script>
simplyCountdown('.my-countdown', {
    year: 2024,
    month: 12,
    day: 25
});
</script>
```

--------------------------------

### Build and Test SimplyCountdown.js Distribution

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/CONTRIBUTING.md

Builds the project and then serves the generated distribution files for testing. This command generates HTML files in `dist_test` and runs a temporary server to verify that various countdown implementations work correctly.

```bash
bun run build
bun run dist:test:serve
```

--------------------------------

### Initialize SimplyCountdown.js via Browser (UMD)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Instructions for using SimplyCountdown.js in a browser environment by including the UMD script. The library is then accessed globally via the simplyCountdown variable.

```html
<script src="path/to/simplyCountdown.umd.js"></script>
<script>
    simplyCountdown(".my-super-countdown", {
        year: 2025,
        month: 12,
        day: 25,
    });
</script>
```

--------------------------------

### Run Tests

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Executes the test suite for the simplycountdown.js project to ensure the library functions correctly across different scenarios.

```bash
npm run test
```

--------------------------------

### Including a Theme CSS File

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Demonstrates how to link a theme's CSS file into your HTML document to apply a specific visual style to the countdown timer. Ensure the path to the CSS file is correct.

```html
<link rel="stylesheet" href="path/to/themes/default.css" />
```

--------------------------------

### Generate Test Files for Module Formats

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This command generates test files for various module formats (ES, UMD, CommonJS), preparing the project for comprehensive module compatibility testing.

```bash
npm run dist:test
```

--------------------------------

### Build CSS Themes

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This command compiles and builds the CSS theme files for the simplycountdown.js library, allowing for customization of the countdown's appearance.

```bash
npm run build:themes
```

--------------------------------

### Build Library (ES and UMD formats)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This command builds the simplycountdown.js library in both ES (ECMAScript Modules) and UMD (Universal Module Definition) formats, ensuring compatibility with various JavaScript environments.

```bash
npm run build:lib
```

--------------------------------

### TypeScript Integration for Countdown Initialization

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Shows how to integrate simplycountdown.js with TypeScript, leveraging its type definitions for enhanced code safety and developer experience. It covers configuration, controller usage, state inspection, and creating a class-based wrapper for managing countdown instances.

```typescript
import simplyCountdown from "simplycountdown.js";
import type { CountdownParameters, CountdownController } from "simplycountdown.js/src/types";

// Fully typed configuration
const config: Partial<CountdownParameters> = {
    year: 2025,
    month: 12,
    day: 25,
    zeroPad: true,
    enableUtc: true,
    onEnd: () => {
        console.log("Countdown complete");
    },
    onUpdate: (params) => {
        console.log("Updated with:", params);
    }
};

// Typed controller
const controller: CountdownController = simplyCountdown("#timer", config);

// Type-safe state inspection
const state = controller.getState();
console.log(`Paused: ${state.isPaused}`);
console.log(`Target: ${state.targetDate.toISOString()}`);

// Class-based wrapper
class CountdownManager {
    private controller: CountdownController;

    constructor(selector: string, params: Partial<CountdownParameters>) {
        this.controller = simplyCountdown(selector, params);
    }

    pause(): void {
        this.controller.stopCountdown();
    }

    resume(): void {
        this.controller.resumeCountdown();
    }

    setNewTarget(year: number, month: number, day: number): void {
        this.controller.updateCountdown({ year, month, day });
    }

    isPaused(): boolean {
        return this.controller.getState().isPaused;
    }
}

const manager = new CountdownManager("#event-timer", {
    year: 2025,
    month: 6,
    day: 15
});
```

--------------------------------

### Vanilla JavaScript Syntax for simplyCountdown

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This is the new vanilla JavaScript syntax for initializing simplyCountdown, replacing the old jQuery-compatible syntax. It targets elements using CSS selectors and accepts an options object.

```javascript
simplyCountdown('.some-countdowns', options)
```

--------------------------------

### JavaScript - CommonJS Usage

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Demonstrates how to import and use simplyCountdown.js in an environment that supports CommonJS modules, such as Node.js or older build systems. It shows a basic initialization with required options.

```javascript
const simplyCountdown = require("simplycountdown.js");

simplyCountdown("#mycountdown", {
    year: 2025,
    month: 12,
    day: 25,
});
```

--------------------------------

### Available Themes

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

simplyCountdown offers multiple visually appealing themes to enhance your countdown timer's appearance. Each theme is carefully designed to suit different website styles and aesthetics.

```APIDOC
## Available Themes

**simplyCountdown** offers multiple visually appealing themes to enhance your countdown timer's appearance. Each theme is carefully designed to suit different website styles and aesthetics, from minimal to modern designs.

The theme collection includes a clean default style, a sleek dark mode, a futuristic cyberpunk variation, an elegant losange theme, and a modern circle design. These themes are implemented through separate CSS files for optimal performance and easy customization.

### Implementing Themes

To implement any theme, simply include the corresponding CSS file in your HTML document's head section. Each theme maintains the countdown's functionality while providing unique visual presentations.

#### Theme CSS Classes

- Default theme: `simply-countdown`
- Dark theme: `simply-countdown-dark`
- Cyberpunk theme: `simply-countdown-cyber`
- Losange theme: `simply-countdown-losange`
- Circle theme: `simply-countdown-circle`

### Example Usage

```html
<!-- Include theme CSS files -->
<link rel="stylesheet" href="dist/themes/default.css">
<link rel="stylesheet" href="dist/themes/dark.css">
<link rel="stylesheet" href="dist/themes/cyber.css">
<link rel="stylesheet" href="dist/themes/losange.css">
<link rel="stylesheet" href="dist/themes/circle.css">

<!-- Apply themes using corresponding classes -->
<div class="my-countdown simply-countdown"></div>
<div class="my-countdown simply-countdown-dark"></div>
<div class="my-countdown simply-countdown-cyber"></div>
<div class="my-countdown simply-countdown-losange"></div>
<div class="my-countdown simply-countdown-circle"></div>

<script>
// Initialize countdowns with desired options
simplyCountdown('.my-countdown', {
    year: 2024,
    month: 12,
    day: 25
});
</script>
```
```

--------------------------------

### Apply Ready-to-use Themes for simplyCountdown (HTML)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Enhance the visual appearance of your countdown timers by including pre-designed themes provided by simplyCountdown.js. This involves linking the appropriate CSS file in your HTML's head section and applying a corresponding class to the countdown container. Themes include Default, Dark, Cyberpunk, Losange, and Circle.

```html
<!-- Choose one or more themes: -->
<link rel="stylesheet" href="dist/themes/default.css">
<link rel="stylesheet" href="dist/themes/dark.css">
<link rel="stylesheet" href="dist/themes/cyber.css">
<link rel="stylesheet" href="dist/themes/losange.css">
<link rel="stylesheet" href="dist/themes/circle.css">

<div class="my-countdown simply-countdown"></div>
<div class="my-countdown simply-countdown-dark"></div>
<div class="my-countdown simply-countdown-cyber"></div>
<div class="my-countdown simply-countdown-losange"></div>
<div class="my-countdown simply-countdown-circle"></div>

<script>
// This will init all countdowns with the same options, but different themes
simplyCountdown('.my-countdown', {
    year: 2024,
    month: 12,
    day: 25
});
</script>
```

--------------------------------

### JavaScript Selector Support

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Illustrates how SimplyCountdown.js can be initialized using different types of DOM selectors: a CSS selector string, a single DOM element, or a collection of DOM elements.

```javascript
// CSS selector string
simplyCountdown("#countdown", parameters);

// Single DOM element
simplyCountdown(document.getElementById("countdown"), parameters);

// Multiple elements
simplyCountdown(document.querySelectorAll(".countdown"), parameters);
```

--------------------------------

### Initialize Countdown Timer with SimplyCountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Initializes a countdown timer on specified HTML elements using a CSS selector, HTMLElement, or NodeList. Accepts configuration options for target date and time, and includes callbacks like onEnd. Returns a controller object for managing the timer.

```javascript
import simplyCountdown from "simplycountdown.js";

// Basic countdown to Christmas 2025
const countdown = simplyCountdown(".my-countdown", {
    year: 2025,
    month: 12,
    day: 25,
    hours: 0,
    minutes: 0,
    seconds: 0,
    onEnd: () => {
        console.log("Merry Christmas!");
        alert("The countdown has ended!");
    }
});

// Multiple countdowns with same configuration
simplyCountdown(".multiple-timers", {
    year: 2025,
    month: 6,
    day: 15,
    zeroPad: true
});

// Using DOM element reference
const element = document.getElementById("timer");
const controller = simplyCountdown(element, {
    year: 2025,
    month: 3,
    day: 1
});
```

--------------------------------

### HTML Structure for Inline Display

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

This HTML snippet shows the basic structure for displaying a countdown timer inline using the 'simply-countdown-inline' class.

```html
<div class="simply-countdown simply-countdown-inline">24 days, 3 hours, 45 minutes, 12 seconds</div>
```

--------------------------------

### Accessing TypeScript Source (JavaScript)

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/dist/index.html

This snippet shows how to import the core functionality of simplyCountdown directly from its source files, which can be useful when working with TypeScript projects or when needing to import specific modules.

```javascript
import simplyCountdown from "simplycountdown.js/src/core/simplyCountdown";

```

--------------------------------

### JavaScript Countdown Control Features

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/README.md

Shows how to obtain a controller object after initializing a countdown, allowing for programmatic control such as pausing, resuming, and updating the countdown's parameters. Chaining multiple control methods is also demonstrated.

```javascript
// Initialize countdown
const countdown = simplyCountdown("#mycountdown", parameters);

// Stop the countdown
countdown.pause();

// Resume countdown
countdown.resume();

// Update countdown parameters
countdown.update({
    year: 2026,
    month: 1,
    day: 1,
});

// Chain control methods
countdown.pause();
countdown.resume();
countdown.update({ year: 2026, hours: 12, minutes: 51 });
```

--------------------------------

### Control Methods API

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Control your countdown timers with precision using the returned controller object. This API lets you stop, resume, and update countdowns dynamically.

```APIDOC
## Control Methods API

Control your countdown timers with precision using the returned controller object. **simplyCountdown's** API lets you stop, resume, and update countdowns dynamically.

### Initialization with Control Callbacks

```javascript
const countdown = simplyCountdown('#mycountdown', {
    year: 2025,
    month: 12,
    day: 25,
    onStop: () => console.log('Countdown stopped'),
    onResume: () => console.log('Countdown resumed'),
    onUpdate: (newParams) => console.log('Updated with:', newParams)
});
```

### Countdown Control Methods

- **stopCountdown()**: Pauses the countdown.
- **resumeCountdown()**: Resumes the paused countdown.
- **updateCountdown(newParams)**: Updates the countdown with new parameters. `newParams` is an object containing updated date/time properties.

```javascript
// Control the countdown
countdown.stopCountdown();    // Pause
countdown.resumeCountdown();  // Resume
countdown.updateCountdown({   // Update parameters
    year: 2026,
    month: 1
});
```

### Get Countdown State

- **getState()**: Returns an object with the current state of the countdown.

```javascript
// Get current state
const state = countdown.getState();
console.log('Is paused:', state.isPaused);
console.log('Target date:', state.targetDate);
```

### Handling Multiple Countdowns

When initializing with a class selector, the methods apply to all matched countdowns.

```javascript
const countdowns = simplyCountdown('.countdown-class', options);
countdowns.stopCountdown();  // Stops all countdowns
countdowns.updateCountdown({ year: 2026 }); // Updates all
```
```

--------------------------------

### HTML/JavaScript - Browser (UMD) Usage

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Shows how to include and use simplyCountdown.js in a web browser using the UMD (Universal Module Definition) build. This method involves including a script tag and then calling the library's function directly.

```html
<script src="path/to/simplyCountdown.umd.js"></script>
<script>
    simplyCountdown("#mycountdown", {
        year: 2025,
        month: 12,
        day: 25,
    });
</script>
```

--------------------------------

### Customization

Source: https://github.com/vincentloy/simplycountdown.js/blob/develop/docs/src/index.html

Customize your countdown timers with CSS to match your website's design perfectly. simplyCountdown.js provides a flexible HTML structure that's easy to style.

```APIDOC
## Customize

Customize your countdown timers with CSS to match your website's design perfectly.

**simplyCountdown.js** provides a flexible HTML structure that's easy to style. Whether you want minimal designs or elaborate displays, the library's modular structure lets you modify individual elements like numbers, labels, and containers.

### Base CSS Structure for Customization

Below is the base CSS structure you can customize. Apply your custom theme by adding a unique class to your countdown container and targeting its elements.

```css
.custom-countdown-theme {
    /* Main countdown container styles */
}

.custom-countdown-theme > .simply-section {
    /* Styles for individual time unit blocks (days, hours, minutes, seconds) */
}

.custom-countdown-theme > .simply-section > div {
    /* Inner container for amount and word */
}

.custom-countdown-theme > .simply-section .simply-amount,
.custom-countdown-theme > .simply-section .simply-word {
    /* Common styles for numbers and labels */
}

.custom-countdown-theme > .simply-section .simply-amount {
    /* Styles specific to the number display */
}

.custom-countdown-theme > .simply-section .simply-word {
    /* Styles specific to the label text (e.g., 'days', 'hours') */
}
```

### Example Customization

To use custom CSS, add your own class to the countdown element and target it:

```html
<div class="my-custom-countdown simply-countdown"></div>

<style>
.my-custom-countdown {
    font-family: 'Arial', sans-serif;
    color: #333;
}

.my-custom-countdown .simply-amount {
    font-size: 3em;
    font-weight: bold;
    color: #007bff;
}

.my-custom-countdown .simply-word {
    font-size: 1.2em;
    text-transform: uppercase;
    color: #666;
}
</style>

<script>
simplyCountdown('.my-custom-countdown', {
    year: 2024,
    month: 12,
    day: 25
});
</script>
```
```

--------------------------------

### Inline Countdown Display with simplyCountdown.js

Source: https://context7.com/vincentloy/simplycountdown.js/llms.txt

Shows how to render a countdown as a single line of text using the `inline: true` option. This mode is suitable for compact layouts and embedding within sentences. Customizable separators and classes can be applied, along with options to remove zero units and define custom words for units.

```javascript
import simplyCountdown from "simplycountdown.js";

// Basic inline countdown
simplyCountdown("#inline-timer", {
    year: 2025,
    month: 12,
    day: 31,
    inline: true,
    inlineSeparator: " | ",
    inlineClass: "my-inline-countdown"
});

// Inline with custom formatting
simplyCountdown("#sentence-timer", {
    year: 2025,
    month: 6,
    day: 15,
    inline: true,
    inlineSeparator: ", ",
    removeZeroUnits: true,
    words: {
        days: { lambda: (root, n) => n === 1 ? "day" : "days", root: "day" },
        hours: { lambda: (root, n) => n === 1 ? "hour" : "hours", root: "hour" },
        minutes: { lambda: (root, n) => n === 1 ? "minute" : "minutes", root: "minute" },
        seconds: { lambda: (root, n) => n === 1 ? "second" : "seconds", root: "second" }
    }
});

// Output: "24 days, 5 hours, 30 minutes, 12 seconds"
```