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

# @outbook/webcomponents-player-artwork

This package provides a web component for displaying player artwork. It supports responsive images via `srcset`, multiple sources for `<picture>` elements, and a customizable fallback icon when no image is provided.

## Installation

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

## Usage

### As a Lit Element (using wrapper function)

The `PlayerArtwork` wrapper function simplifies usage within Lit templates.

```javascript
import { html } from 'lit';
import { PlayerArtwork } from '@outbook/webcomponents-player-artwork';
import { music_note } from '@outbook/icons';

function render() {
  return html`
    ${PlayerArtwork({
      src1x: 'path/to/image.jpg',
      src2x: 'path/to/image@2x.jpg',
      icon: music_note
    })}
  `;
}
```

### Direct HTML Usage (using component tag)

You can use the custom element directly in your HTML. Note that complex properties like `icon` must be set via JavaScript, while `sources` can be passed as a JSON string.

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

```html
<!-- Simple usage -->
<outbook-player-artwork
  src1x="path/to/image.jpg"
  src2x="path/to/image@2x.jpg"
></outbook-player-artwork>

<!-- With sources for <picture> element -->
<outbook-player-artwork
  sources='[{"media": "(min-width: 600px)", "src1x": "large.jpg"}]'
></outbook-player-artwork>

<!-- With fallback icon (default is music_note) -->
<outbook-player-artwork></outbook-player-artwork>
```

## Component Usage

The component is best used via its wrapper function `PlayerArtwork`.

### Properties

The properties listed below are used by the `PlayerArtwork` wrapper function.

| Attribute       | Property       | Type      | Default      | Description                                                                                                        |
|-----------------|----------------|-----------|--------------|--------------------------------------------------------------------------------------------------------------------|
| `class`         | `extraClasses` | `String`  | `undefined`  | CSS classes to apply to the host element.                                                                          |
| `natural-ratio` | `naturalRatio` | `Boolean` | `false`      | Natural ratio preseves original image ratio.                                                                       |
| `src1x`         | `src1x`        | `String`  | `undefined`  | The source URL for the 1x resolution image.                                                                        |
| `src2x`         | `src2x`        | `String`  | `undefined`  | The source URL for the 2x resolution image.                                                                        |
| `sources`       | `sources`      | `Array`   | `[]`         | An array of source objects for `<picture>` usage. Each object should have `media`, `src1x`, and optionally `src2x`. |
| -               | `icon`         | `Object`  | `music_note` | The SVG icon object to display as a fallback. Must be passed as a property.                                        |

### Sources Object Structure

The `sources` array expects objects with the following structure:

```javascript
{
  media: '(min-width: 600px)',
  src1x: 'path/to/large-image.jpg',
  src2x: 'path/to/large-image@2x.jpg'
}
```

## Styling

This component uses Shadow DOM, and its styles are self-contained. The component's styles are automatically applied and encapsulated.

### Custom Properties

You can customize the appearance using the following CSS custom properties:

| Custom Property | Description |
|---|---|
| `--outbook-player-artwork--background-color` | Background color of the artwork container. |
| `--outbook-player-artwork--text-color` | Color of the fallback icon. |
| `--outbook-player-artwork--crystal-background` | Background styling for the crystal effect (fallback mode). |
| `--outbook-player-artwork--crystal-border` | Border styling for the crystal effect (fallback mode). |

## License

This component is licensed under the Apache-2.0 License.