@outbook/webcomponents-player-artwork 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @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. |
+| `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outbook/webcomponents-player-artwork",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "player-artwork.js",
   "type": "module",
   "private": false,

package/player-artwork.js

@@ -16,31 +16,56 @@ function renderCoverFallback({ icon = music_note }) {
   `;
 }
 
+function buildSrcSet(src1x, src2x) {
+  return src2x ? `${src1x} 1x, ${src2x} 2x` : `${src1x} 1x`;
+}
+
 class ComponentPlayerArtwork extends LitElement {
   static properties = {
     src1x: { type: String },
     src2x: { type: String },
+    sources: {
+      converter: {
+        fromAttribute: value => (value ? JSON.parse(value) : []),
+        toAttribute: value => (value?.length ? JSON.stringify(value) : null)
+      }
+    },
     icon: { type: Object }
   };
 
   constructor() {
     super();
     this.icon = music_note;
+    this.sources = [];
   }
 
   static styles = styleComponent;
 
+  get resolvedSources() {
+    if (this.sources?.length) return this.sources;
+    if (this.src1x) return [{ src1x: this.src1x, src2x: this.src2x }];
+    return [];
+  }
+
   render() {
-    if (this.src1x) {
-      const srcSet = this.src2x
-        ? `${this.src1x} 1x, ${this.src2x} 2x`
-        : `${this.src1x} 1x`;
+    const [fallback] = this.resolvedSources;
 
+    if (fallback) {
       return html`
         <picture class="player-artwork player-artwork--image">
+          ${this.resolvedSources.length > 1
+            ? this.resolvedSources.map(
+                ({ media, src1x, src2x }) => html`
+                  <source
+                    media="${ifDefined(media)}"
+                    srcset="${buildSrcSet(src1x, src2x)}"
+                  />
+                `
+              )
+            : ''}
           <img
-            srcset="${srcSet}"
-            src="${this.src1x}"
+            srcset="${buildSrcSet(fallback.src1x, fallback.src2x)}"
+            src="${fallback.src1x}"
             alt=""
             aria-hidden="true"
             loading="lazy"
@@ -57,14 +82,13 @@ if (!customElements.get('outbook-player-artwork')) {
   customElements.define('outbook-player-artwork', ComponentPlayerArtwork);
 }
 
-export function PlayerArtwork(props) {
-  const { extraClasses, src1x, src2x, icon } = props;
-
+export function PlayerArtwork({ extraClasses, src1x, src2x, sources, icon }) {
   return html`
     <outbook-player-artwork
       class="${ifDefined(extraClasses)}"
       src1x="${ifDefined(src1x)}"
       src2x="${ifDefined(src2x)}"
+      .sources="${sources ?? []}"
       .icon="${icon}"
     ></outbook-player-artwork>
   `;