Merge pull request #248 from gfscott/youtube-lite-0.3.2-options

Add lite-mode options for thumbnail format and YouTube Player API access

.changeset/old-dragons-float.md

@@ -0,0 +1,5 @@
+---
+"eleventy-plugin-youtube-embed": minor
+---
+
+Add lite-mode options for thumbnail format and YouTube JS API access

packages/youtube/README.md

@@ -250,12 +250,24 @@ eleventyConfig.addPlugin(embedYouTube, {
       <td><code>https://cdn.jsdelivr.net/gh/paulirish/lite-youtube-embed@0.3.0/src/lite-yt-embed.min.js</code></td>
       <td>Pass a custom URL to load the necessary JavaScript from the source of your choice.</td>
     </tr>
+    <tr>
+      <td><code>lite.jsApi</code><br>✨ <b>New in v1.11.0!</b></td>
+      <td>Boolean</td>
+      <td><code>false</code></td>
+      <td>If you change this to true, then the plugin adds a `js-api` parameter to the custom element that enables access to YouTube's IFrame Player API. See <a href="https://github.com/paulirish/lite-youtube-embed?tab=readme-ov-file#access-the-youtube-iframe-player-api">usage example</a> and <a href="https://paulirish.github.io/lite-youtube-embed/variants/js-api.html">demo</a>.</td>
+    </tr>
     <tr>
       <td><code>lite.responsive</code><br>✨ <b>New in v1.10.0!</b></td>
       <td>Boolean</td>
       <td><code>false</code></td>
       <td>If you change this to <code>true</code>, then the plugin adds a CSS rule to override the default max-width of <code>&lt;lite-youtube&gt;</code> elements, which are <a href="https://github.com/paulirish/lite-youtube-embed/blob/f9fc3a2475ade166d0cf7bb3e3caa3ec236ee74e/src/lite-yt-embed.css#L9">hard coded</a> to a maximum of 720 pixels.</td>
     </tr>
+    <tr>
+      <td><code>lite.thumbnailFormat</code><br>✨ <b>New in v1.11.0!</b></td>
+      <td>String</td>
+      <td><code>jpg</code></td>
+      <td>If you change this to <code>webp</code>, then the plugin will load the YouTube thumbnail image in WebP format instead of JPEG.</td>
+    </tr>
     <tr>
       <td><code>lite.thumbnailQuality</code></td>
       <td>String</td>

packages/youtube/lib/defaults.js

@@ -35,10 +35,14 @@ const defaults = {
  * @typedef {Object} Thumbnails
  * @property {string[]} validSizes - An array of valid sizes.
  * @property {string} defaultSize - The default size.
+ * @property {string[]} validFormats - An array of valid formats.
+ * @property {string} defaultFormat - The default format.
  */
 const thumbnails = {
   validSizes: ["default", "hqdefault", "mqdefault", "sddefault", "maxresdefault"],
-  defaultSize: "hqdefault"
+  defaultSize: "hqdefault",
+  validFormats: ["jpg", "webp"],
+  defaultFormat: "jpg",
 }
 
 /**
@@ -51,22 +55,25 @@ const thumbnails = {
  * @property {boolean} [js.enabled] - Whether JS is enabled.
  * @property {boolean} [js.inline] - Whether JS is inline.
  * @property {string} [js.path] - The path to the JS file.
+ * 
  * @property {boolean} [responsive] - Whether the layout is responsive.
  * @property {string} [thumbnailQuality] - The quality of the thumbnail.
  */
 const liteDefaults = {
   css: {
     enabled: true,
     inline: false,
-    path: 'https://cdn.jsdelivr.net/gh/paulirish/lite-youtube-embed@0.3.0/src/lite-yt-embed.min.css'
+    path: 'https://cdn.jsdelivr.net/gh/paulirish/lite-youtube-embed@0.3.2/src/lite-yt-embed.min.css'
   },
   js: {
     enabled: true,
     inline: false,
-    path: 'https://cdn.jsdelivr.net/gh/paulirish/lite-youtube-embed@0.3.0/src/lite-yt-embed.min.js'
+    path: 'https://cdn.jsdelivr.net/gh/paulirish/lite-youtube-embed@0.3.2/src/lite-yt-embed.min.js'
   },
+  jsApi: false,
   responsive: false,
   thumbnailQuality: thumbnails.defaultSize,
+  thumbnailFormat: thumbnails.defaultFormat,
 };
 
 module.exports.thumbnails = thumbnails;

packages/youtube/lib/embed.js

@@ -73,8 +73,15 @@ function liteEmbed({id, url}, options, index) {
   options = merge(options, getInputUrlParams(url))
   const liteOpt = liteConfig(options);
         liteOpt.thumbnailQuality = validateThumbnailSize(liteOpt.thumbnailQuality);
+        liteOpt.thumbnailFormat = validateThumbnailFormat(liteOpt.thumbnailFormat);
   const params = stringifyUrlParams(options);
 
+  const thumbnailUrl = () => {
+    const fileTypePath = liteOpt.thumbnailFormat === 'webp' ? 'vi_webp' : 'vi';
+    const fileName = `${liteOpt.thumbnailQuality}.${liteOpt.thumbnailFormat}`;
+    return `https://i.ytimg.com/${fileTypePath}/${id}/${fileName}`;
+  }
+
   // Access the file system to read the lite embed CSS and JS
   const fs = require('fs');
   const path = require('path');
@@ -96,7 +103,7 @@ function liteEmbed({id, url}, options, index) {
   out += index === 0 && liteOpt.responsive ? `<style>.${options.embedClass} lite-youtube {max-width:100%}</style>\n` : '';
 
   out += `<div id="${id}" class="${options.embedClass}">`;
-  out += `<lite-youtube videoid="${id}" style="background-image: url('https://i.ytimg.com/vi/${id}/${liteOpt.thumbnailQuality}.jpg');"${params ? ` params="${params}"` : ''}>`;
+  out += `<lite-youtube videoid="${id}" style="background-image: url('${thumbnailUrl()}');"${params ? ` params="${params}"` : ''}${liteOpt.jsApi ? ' js-api' : ''}>`;
   out += '<div class="lty-playbtn"></div></lite-youtube></div>';
   return out;
 }
@@ -198,5 +205,20 @@ async function getYouTubeTitleViaOembed(id, options) {
   }
 }
 
+/**
+ * Validates the thumbnail format and returns the format if it is valid, otherwise returns the default format.
+ *
+ * @param {string} format - The thumbnail format to validate.
+ * @param {object} options - The options object containing the valid thumbnail formats.
+ * @returns {string} - The validated thumbnail format.
+ */
+function validateThumbnailFormat(format) {
+  if ( !thumbnails.validFormats.includes(format) ) {
+    return thumbnails.defaultFormat
+  }
+  return format;
+}
+
 module.exports.validateThumbnailSize = validateThumbnailSize;
+module.exports.validateThumbnailFormat = validateThumbnailFormat;
 module.exports.getYouTubeTitleViaOembed = getYouTubeTitleViaOembed;