npm package: @outbook/webcomponents-player-timeline
Description: Web component player-timeline
Author: Antonio Rodríguez
Latest version: 1.0.3

# @outbook/webcomponents-player-timeline

This package provides a web component for a customizable player timeline, displaying playback progress and chapter markers.

## Installation

```bash
npm install @outbook/webcomponents-player-timeline
```

## Usage

### As a Lit Element

```javascript
import {html} from 'lit';
import {PlayerTimeline} from '@outbook/webcomponents-player-timeline';

function render() {
  const duration = 120; // Example duration in seconds
  const currentTime = 30; // Example current time in seconds
  const currentItem = {
    metadata: {
      chapters: [
        {start: 0, end: 30000, tags: {title: 'Introduction'}},
        {start: 30000, end: 60000, tags: {title: 'Chapter 1'}},
      ],
    },
  };

  return html`
    ${PlayerTimeline({
      duration: duration,
      props: {
        currentTime: currentTime,
        currentItem: currentItem,
      },
    })}
  `;
}
```

### Direct HTML Usage

You can also use the custom element directly in your HTML. Remember to import the component's JavaScript for the custom element to be defined. The `duration` attribute represents the total duration of the media in seconds. The component's internal state (like `currentTime` and `currentItem`) is passed via the `.props` property when used directly, which is less common for simple HTML usage but possible for framework integration.

```javascript
import '@outbook/webcomponents-player-timeline';

// Example of setting props if needed, typically handled by a framework
const playerTimeline = document.querySelector('outbook-player-timeline');
playerTimeline.duration = 120; // Total duration in seconds
playerTimeline.props = {
  currentTime: 30, // Current playback time in seconds
  currentItem: {
    metadata: {
      chapters: [
        {start: 0, end: 30000, tags: {title: 'Introduction'}},
        {start: 30000, end: 60000, tags: {title: 'Chapter 1'}},
      ],
    },
  },
};
```

```html
<outbook-player-timeline duration="120"></outbook-player-timeline>
```

## Component Usage

The component is best used via its wrapper function `PlayerTimeline`, which simplifies passing complex properties like `props`.

### Properties

| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
| `duration` | `duration` | `Number` | `undefined` | The total duration of the media in seconds. (Required) |
| `lang` | `lang` | `String` | `'en'` | The language to use for internationalization. |
| `extraClasses` | `extraClasses` | `String` | `undefined` | Classes to add to the host element. |
| `props` | `props` | `Object` | `{}` | An object containing dynamic properties like `currentTime` (current playback time in seconds) and `currentItem` (an object that can contain `metadata.chapters` for chapter markers). |

## Styling

This component uses Shadow DOM, and its styles are self-contained. The component's styles are automatically applied and encapsulated, so there is no need to import any additional stylesheets.

### Custom Properties

Can be used with css `light-dark` function.

| Custom Property                                       | Description                                       |
|-------------------------------------------------------|---------------------------------------------------|
| `--outbook-player-timeline--background`               | The background color of the timeline track.       |
| `--outbook-player-timeline--background-completed`     | The background color of the completed part of the timeline track. |
| `--outbook-player-timeline--chapter-mark-color`       | The color of chapter markers.                     |
| `--outbook-player-timeline--chapter-played-mark-color`| The color of chapter markers for played chapters. |

## License

This component is licensed under the Apache-2.0 License.