npm package: @ibrahimjs/timer-component
Description: Timer component
Latest version: 1.0.3

# TimerComponent Documentation

## Overview

TimerComponent is a customizable web component package that provides a countdown timer with play, pause, and reset functionalities. This package includes four main web components: TimerComponent, TimerPlayerComponent, TimerPartComponent.

## Installation

Install the package via NPM:

`  npm install @ibrahimjs/timer-component`

## Usage

### Importing Components

To use the components in your project, import them as follows as create customElements with them:

```js
    import { TimerComponent } from "@ibrahimjs/timer-component";
    import { TimerPlayerComponent } from "@ibrahimjs/timer-component";
    import { TimerPartComponent } from "@ibrahimjs/timer-component";

    window.customElements.define("timer-component", TimerComponent);
    window.customElements.define("timer-player-component", TimerPlayerComponent);
    window.customElements.define("timer-part-component", TimerPartComponent);
```

### TimerComponent

TimerComponent is the core component that handles the countdown timer functionality.

#### Properties

- **start** (Number): Initial countdown value in seconds. Default is 0.
- **limit** (Number): Countdown limit value in seconds. Required when reverse is false.
- **reverse** (Boolean): If true, the timer counts down. Default is false.
- **autostart** (Boolean): If true, the timer starts automatically. Default is false.
- **autoreset** (Boolean): If true, the timer resets automatically when finished. Default is false.

#### Example

```html
<timer-component
  start="0"
  limit="10"
  reverse
  autostart
  autoreset
></timer-component>
```

### TimerPlayerComponent

TimerPlayerComponent provides controls to play, pause, and reset the TimerComponent.

#### Properties

- **playBtn** (Boolean): Displays the play button. Default is false.
- **pauseBtn** (Boolean): Displays the pause button. Default is false.
- **resetBtn** (Boolean): Displays the reset button. Default is false.
- **isFinishedMessage** (String): Message displayed when the timer finishes. Default is "¡Finish!".

#### Example

```html
<timer-player-component
  play-btn
  pause-btn
  reset-btn
  finish-message="Ready!"
>
  <timer-component></timer-component>
</timer-player-component>
```

### TimerPartComponent

TimerPartComponent displays individual parts of the timer (days, hours, minutes, seconds).

#### Properties

- **value** (Number): The numeric value of the time part.
- **format** (String): The format of the time part (DD, HH, MM, SS).

#### Example

```html
<timer-part-component value="12" format="HH"></timer-part-component>
```

### SetTimerComponent

SetTimerComponent provides an input for updating the TimerComponent dynamically.

#### Properties

- **inputValue** (Number): The input value in seconds. Default is 0.

#### Events

- **submit-timer**: Dispatched when the timer value is submitted. Includes the new timer value in the detail.

## Styling

Each component can be customized using CSS variables for better integration with your design system.

### TimerComponent Styles

- **\--timer-component-part-color**: Color of the timer parts.
- **\--timer-component-join-padding**: Padding between the timer parts.

### TimerPlayerComponent Styles

- **\--timer-player-component-action-margin**: Margin for action buttons.
- **\--timer-player-component-status-margin**: Margin for the status display.
- **\--timer-player-component-status-color**: Color for the status display.
- **\--timer-player-component-status-font-size**: Font size for the status display.
- **\--timer-player-component-button-padding**: Padding for action buttons.
- **\--timer-player-component-button-margin**: Margin for action buttons.
- **\--timer-player-component-button-border-radius**: Border radius for action buttons.
- **\--timer-player-component-button-border**: Border style for action buttons.
- **\--timer-player-component-color**: Text color for action buttons.
- **\--timer-player-component-part-color**: Background color for action buttons.
- **\--timer-player-component-play-color**: Text color for the play button.
- **\--timer-player-component-play-background-color**: Background color for the play button.

### TimerPartComponent Styles

- **\--timer-component-part-color**: Text color for timer parts.
- **\--timer-component-part-padding**: Padding for timer parts.
- **\--timer-component-part-box-shadow**: Box shadow for timer parts.
- **\--timer-component-part-border-radius**: Border radius for timer parts.

## Events

- **isFinished**: Dispatched by TimerComponent when the timer finishes.


## License

This project is licensed under the MIT License. See the LICENSE file for details.