videojs-mobile-ui 1.1.4 → 1.2.0

package/scripts/readme-options.js

@@ -0,0 +1,370 @@
+/* eslint-disable no-console */
+
+const fs = require('fs');
+
+const PATHS = {
+  plugin: './src/plugin.js',
+  readme: './README.md'
+};
+
+const COLOURS = {
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  reset: '\x1b[0m'
+};
+
+/**
+ * Main execution entry point. Reads files, validates data, and updates README.
+ */
+function main() {
+  try {
+    const pluginContent = fs.readFileSync(PATHS.plugin, 'utf8');
+    const readmeContent = fs.readFileSync(PATHS.readme, 'utf8');
+
+    console.log(`Reading source from ${PATHS.plugin}...`);
+
+    const properties = parseJSDoc(pluginContent);
+
+    if (!properties || properties.length === 0) {
+      console.error('Could not find "MobileUiOptions" JSDoc in plugin.js');
+      return;
+    }
+
+    const defaultsObj = extractAndParseDefaults(pluginContent);
+    const defaultsCodeBlock = extractDefaultsCodeBlock(pluginContent);
+
+    if (defaultsObj) {
+      const structureValid = validateStructure(properties, defaultsObj);
+      const valuesValid = validateValues(properties, defaultsObj);
+
+      if (!structureValid || !valuesValid) {
+        console.error(`${COLOURS.red}Validation failed. Please fix the inconsistencies above.${COLOURS.reset}`);
+        process.exit(1);
+      }
+    } else {
+      console.warn('Could not parse "defaults" object from code. Skipping validation.');
+    }
+
+    const publicProperties = properties.filter(p => !p.isInternal);
+    const newDocsMarkdown = generateMarkdown(publicProperties);
+
+    console.log(`Generated documentation for ${publicProperties.length} public properties.`);
+    console.log(`Updating ${PATHS.readme}...`);
+
+    const updatedReadme = updateReadmeContent(readmeContent, newDocsMarkdown, defaultsCodeBlock);
+
+    fs.writeFileSync(PATHS.readme, updatedReadme);
+    console.log('README.md updated successfully!');
+
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * -------------------------------------------------------
+ * PARSING
+ * -------------------------------------------------------
+ */
+
+/**
+ * Parses the JSDoc @typedef block for MobileUiOptions into an array of property objects.
+ *
+ * @param {string} content - The file content to parse.
+ * @return {Array} List of property objects.
+ */
+function parseJSDoc(content) {
+  const blockRegex = /\/\*\*[\s\S]*?@typedef \{Object\} MobileUiOptions[\s\S]*?\*\//;
+  const match = content.match(blockRegex);
+
+  if (!match) {
+    return [];
+  }
+
+  const lines = match[0].split('\n');
+  const properties = [];
+  let currentProp = null;
+  let nextIsInternal = false;
+
+  const propertyRegex = /@property\s+\{(.+?)\}\s+(?:\[(.+?)\]|(\S+))/;
+
+  lines.forEach(line => {
+    const cleanLine = line.trim().replace(/^\*\s?/, '').trim();
+
+    if (cleanLine.includes('@internal')) {
+      nextIsInternal = true;
+      return;
+    }
+
+    const propMatch = cleanLine.match(propertyRegex);
+
+    if (propMatch) {
+      if (currentProp) {
+        properties.push(currentProp);
+      }
+
+      currentProp = {
+        name: propMatch[2] || propMatch[3],
+        type: propMatch[1],
+        description: [],
+        isInternal: nextIsInternal
+      };
+
+      nextIsInternal = false;
+
+    } else if (currentProp && !cleanLine.startsWith('@') && cleanLine !== '/') {
+      if (cleanLine.length > 0) {
+        currentProp.description.push(cleanLine);
+      }
+    }
+  });
+
+  if (currentProp) {
+    properties.push(currentProp);
+  }
+
+  return properties;
+}
+
+/**
+ * Extracts and evaluates the 'defaults' object literal from the source code.
+ *
+ * @param {string} content - The file content.
+ * @return {Object|null} The evaluated JavaScript object or null.
+ */
+function extractAndParseDefaults(content) {
+  const regex = /const defaults = (\{[\s\S]*?^\};)/m;
+  const match = content.match(regex);
+
+  if (!match) {
+    return null;
+  }
+
+  try {
+    /* eslint-disable-next-line no-new-func */
+    const func = new Function('return ' + match[1]);
+
+    return func();
+  } catch (e) {
+    console.error('Failed to parse defaults object:', e.message);
+    return null;
+  }
+}
+
+/**
+ * Extracts the raw string representation of the 'defaults' object for display.
+ *
+ * @param {string} content - The file content.
+ * @return {string|null} The raw code block string.
+ */
+function extractDefaultsCodeBlock(content) {
+  const regex = /const defaults = (\{[\s\S]*?^\};)/m;
+  const match = content.match(regex);
+
+  return match ? match[1] : null;
+}
+
+/**
+ * -------------------------------------------------------
+ * VALIDATION
+ * -------------------------------------------------------
+ */
+
+/**
+ * Validates that all JSDoc properties exist in defaults and vice-versa.
+ *
+ * @param {Array} properties - Parsed JSDoc properties.
+ * @param {Object} defaults - The actual code defaults object.
+ * @return {boolean} True if valid.
+ */
+function validateStructure(properties, defaults) {
+  let isValid = true;
+  const errors = [];
+  const defaultsKeys = flattenKeys(defaults);
+
+  // 1. Check JSDoc -> Code
+  properties.filter(p => !p.isInternal).forEach(prop => {
+    // Check if prop is a leaf node or a container object in defaults
+    const isPresent = defaultsKeys.includes(prop.name) ||
+                      defaultsKeys.some(k => k.startsWith(prop.name + '.'));
+
+    if (!isPresent) {
+      errors.push(`MISSING IN DEFAULTS: JSDoc property "${prop.name}" is missing from the defaults object.`);
+      isValid = false;
+    }
+  });
+
+  // 2. Check Code -> JSDoc
+  defaultsKeys.forEach(defKey => {
+    const isDocumented = properties.some(p => p.name === defKey);
+
+    if (!isDocumented) {
+      errors.push(`UNDOCUMENTED PROPERTY: Defaults contains "${defKey}" which is not in the JSDoc.`);
+      isValid = false;
+    }
+  });
+
+  if (!isValid) {
+    console.error(`--- ${COLOURS.blue}DEFAULTS MISMATCH${COLOURS.reset} --------`);
+    errors.forEach(e => console.error(e));
+    console.error('-------------------------------');
+  }
+
+  return isValid;
+}
+
+/**
+ * Verifies that JSDoc 'Default' descriptions match actual code values.
+ *
+ * @param {Array} properties - Parsed JSDoc properties.
+ * @param {Object} defaults - The actual code defaults object.
+ * @return {boolean} True if valid.
+ */
+function validateValues(properties, defaults) {
+  let isValid = true;
+  const errors = [];
+
+  properties.forEach(prop => {
+    const defaultLine = prop.description.find(line => line.startsWith('Default '));
+
+    if (defaultLine) {
+      let rawValue = defaultLine.substring('Default '.length).trim();
+
+      rawValue = rawValue.replace(/\.$/, '').replace(/^`|`$/g, '');
+
+      const expectedValue = castValueToType(rawValue, prop.type);
+      const actualValue = getNestedValue(defaults, prop.name);
+
+      if (actualValue !== undefined && actualValue !== expectedValue) {
+        errors.push(`VALUE MISMATCH for "${prop.name}":\n` +
+          `   - JSDoc expects: ${JSON.stringify(expectedValue)}\n` +
+          `   - Code has:      ${JSON.stringify(actualValue)}`);
+        isValid = false;
+      }
+    }
+  });
+
+  if (!isValid) {
+    console.error(`--- ${COLOURS.blue}VALUE VALIDATION ERRORS${COLOURS.reset} ---`);
+    errors.forEach(e => console.error(e));
+    console.error('-------------------------------');
+  }
+
+  return isValid;
+}
+
+/**
+ * Recursively flattens an object into an array of dot-notation keys.
+ *
+ * @param {Object} obj - The object to flatten.
+ * @param {string} prefix - The current key path prefix.
+ * @return {Array<string>} Array of keys.
+ */
+function flattenKeys(obj, prefix = '') {
+  let keys = [];
+
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+
+      if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
+        keys = keys.concat(flattenKeys(obj[key], fullKey));
+      } else {
+        keys.push(fullKey);
+      }
+    }
+  }
+  return keys;
+}
+
+/**
+ * Casts a string value to a JavaScript type based on the JSDoc type definition.
+ *
+ * @param {string} str - The raw string value.
+ * @param {string} type - The JSDoc type (e.g., 'boolean', 'number').
+ * @return {*} The casted value.
+ */
+function castValueToType(str, type) {
+  const lowerType = type.toLowerCase();
+
+  if (lowerType === 'boolean') {
+    return str === 'true';
+  }
+  if (lowerType === 'number') {
+    return Number(str);
+  }
+  if (lowerType === 'string') {
+    return str.replace(/^['"]|['"]$/g, '');
+  }
+  try {
+    return JSON.parse(str);
+  } catch (e) {
+    return str;
+  }
+}
+
+/**
+ * Retrieves a value from a nested object using a dot-notation path string.
+ *
+ * @param {Object} obj - The source object.
+ * @param {string} path - The dot-notation path (e.g., 'fullscreen.enterOnRotate').
+ * @return {*} The found value or undefined.
+ */
+function getNestedValue(obj, path) {
+  return path.split('.').reduce((prev, curr) => {
+    return prev ? prev[curr] : undefined;
+  }, obj);
+}
+
+/**
+ * -------------------------------------------------------
+ * OUTPUT GENERATION
+ * -------------------------------------------------------
+ */
+
+/**
+ * Formats property objects into a specific Markdown list style.
+ *
+ * @param {Array} properties - List of property objects.
+ * @return {string} Formatted Markdown string.
+ */
+function generateMarkdown(properties) {
+  return properties.map(prop => {
+    const descString = prop.description.join('  \n  ');
+
+    return `- **\`${prop.name}\`** {${prop.type}}  \n  ${descString}`;
+  }).join('\n');
+}
+
+/**
+ * Replaces specific sections in the README content with new documentation.
+ *
+ * @param {string} readmeContent - The original README text.
+ * @param {string} newDocs - The new options list Markdown.
+ * @param {string} defaultsCodeBlock - The new defaults code block.
+ * @return {string} The updated README text.
+ */
+function updateReadmeContent(readmeContent, newDocs, defaultsCodeBlock) {
+  let content = readmeContent;
+
+  if (defaultsCodeBlock) {
+    const defaultsRegex = /(### Default options)([\s\S]*?)(### Options)/;
+
+    if (defaultsRegex.test(content)) {
+      const codeBlock = `\`\`\`js\n${defaultsCodeBlock}\n\`\`\``;
+
+      content = content.replace(defaultsRegex, `$1\n\n${codeBlock}\n\n$3`);
+    }
+  }
+
+  const optionsRegex = /(### Options)([\s\S]*?)(## Installation)/;
+
+  if (!optionsRegex.test(content)) {
+    throw new Error('Could not find "### Options" section followed by "## Installation" in README.md');
+  }
+
+  return content.replace(optionsRegex, `$1\n\n${newDocs}\n\n$3`);
+}
+
+main();

package/src/plugin.css

@@ -95,4 +95,10 @@
     display: none;
   }
 
+  &:not(:fullscreen).using-fs-swipe-up,
+  &:fullscreen.using-fs-swipe-down {
+    touch-action: none;
+    overflow: hidden;
+  }
+
 }

package/src/plugin.js

@@ -1,15 +1,64 @@
 import videojs from 'video.js';
 import {version as VERSION} from '../package.json';
 import './touchOverlay.js';
+import initSwipe from './swipeFullscreen.js';
 import window from 'global/window';
 
-// Default options for the plugin.
+/**
+ * @typedef {Object} MobileUiOptions
+ * @property {Object} [fullscreen]
+ *  Options for fullscreen behaviours.
+ * @property {boolean} [fullscreen.enterOnRotate]
+ *  If the device is rotated, enter fullscreen.
+ *  Default `true`.
+ * @property {boolean} [fullscreen.exitOnRotate]
+ *  If the device is rotated, exit fullscreen, unless `lockOnRotate` is used.
+ *  Default `true`.
+ * @property {boolean} [fullscreen.lockOnRotate]
+ *  When going fullscreen in response to rotation (`enterOnRotate`), also lock the orientation (not supported by iOS).
+ *  Default `true`.
+ * @property {boolean} [fullscreen.lockToLandscapeOnEnter]
+ *  When fullscreen is entered by any means, lock the orientation (not supported by iOS).
+ *  Default `false`.
+ * @property {boolean} [fullscreen.swipeToFullscreen]
+ *  Swipe up to enter fullscreen.
+ *  Default `false`.
+ * @property {boolean} [fullscreen.swipeFromFullscreen]
+ *  Swipe down to exit fullscreen.
+ *  Won't do anything on iOS native fullscreen, which has its own swipe down exit gesture.
+ *  Default `false`.
+ * @property {boolean} [fullscreen.disabled]
+ *  All fullscreen functionality provided by this plugin disabled.
+ *  Default `false`.
+ * @property {Object} [touchControls]
+ *  Options for tap overlay.
+ * @property {number} [touchControls.seekSeconds]
+ *  Increment to seek in seconds.
+ *  Default `10`.
+ * @property {number} [touchControls.tapTimeout]
+ *  Timeout to consider multiple taps as double rather than two single.
+ *  Default `300`.
+ * @property {boolean} [touchControls.disableOnEnd]
+ *  Disable the touch overlay when the video ends.
+ *  Useful if an end screen overlay is used to avoid conflict.
+ *  Default `false`.
+ * @property {boolean} [touchControls.disabled]
+ *  All tap overlay functionality provided by this plugin disabled.
+ *  Default `false`.
+ * @internal
+ * @property {boolean} [forceForTesting]
+ *  Used in unit tests
+ */
+
+/** @type {MobileUiOptions} */
 const defaults = {
   fullscreen: {
     enterOnRotate: true,
     exitOnRotate: true,
     lockOnRotate: true,
     lockToLandscapeOnEnter: false,
+    swipeToFullscreen: false,
+    swipeFromFullscreen: false,
     disabled: false
   },
   touchControls: {
@@ -55,7 +104,7 @@ const getOrientation = () => {
  * @param    {Player} player
  *           A Video.js player object.
  *
- * @param    {Object} [options={}]
+ * @param    {MobileUiOptions} [options={}]
  *           A plain object containing options for the plugin.
  */
 const onPlayerReady = (player, options) => {
@@ -77,20 +126,26 @@ const onPlayerReady = (player, options) => {
     return;
   }
 
+  if (options.fullscreen.swipeToFullscreen || options.fullscreen.swipeFromFullscreen) {
+    initSwipe(player, options);
+  }
+
   let locked = false;
 
   const rotationHandler = () => {
     const currentOrientation = getOrientation();
 
     if (currentOrientation === 'landscape' && options.fullscreen.enterOnRotate) {
-      if (player.paused() === false) {
-        player.requestFullscreen();
+      if (!player.paused() && !player.isFullscreen()) {
+        player.requestFullscreen().catch((err) => {
+          player.log.warn('Browser refused fullscreen request:', err);
+        });
         if ((options.fullscreen.lockOnRotate || options.fullscreen.lockToLandscapeOnEnter) &&
             screen.orientation && screen.orientation.lock) {
           screen.orientation.lock('landscape').then(() => {
             locked = true;
-          }).catch((e) => {
-            videojs.log('Browser refused orientation lock:', e);
+          }).catch((err) => {
+            videojs.log.warn('Browser refused orientation lock:', err);
           });
         }
       }
@@ -119,6 +174,7 @@ const onPlayerReady = (player, options) => {
   }
 
   player.on('fullscreenchange', _ => {
+    player.log('fullscreenchange', player.isFullscreen(), options.fullscreen.lockToLandscapeOnEnter, getOrientation());
     if (player.isFullscreen() && options.fullscreen.lockToLandscapeOnEnter && getOrientation() === 'portrait') {
       screen.orientation.lock('landscape').then(()=>{
         locked = true;
@@ -140,40 +196,10 @@ const onPlayerReady = (player, options) => {
 };
 
 /**
- * A video.js plugin.
- *
- * Adds a monile UI for player control, and fullscreen orientation control
+ * Adds a mobile UI for player control, and fullscreen orientation control
  *
  * @function mobileUi
- * @param    {Object} [options={}]
- *           Plugin options.
- * @param    {boolean} [options.forceForTesting=false]
- *           Enables the display regardless of user agent, for testing purposes
- * @param    {Object} [options.fullscreen={}]
- *           Fullscreen options.
- * @param    {boolean} [options.fullscreen.disabled=false]
- *           If true no fullscreen handling except the *deprecated* iOS fullwindow hack
- * @param    {boolean} [options.fullscreen.enterOnRotate=true]
- *           Whether to go fullscreen when rotating to landscape
- * @param    {boolean} [options.fullscreen.exitOnRotate=true]
- *           Whether to leave fullscreen when rotating to portrait (if not locked)
- * @param    {boolean} [options.fullscreen.lockOnRotate=true]
- *           Whether to lock orientation when rotating to landscape
- *           Unlocked when exiting fullscreen or on 'ended
- * @param    {boolean} [options.fullscreen.lockToLandscapeOnEnter=false]
- *           Whether to always lock orientation to landscape on fullscreen mode
- *           Unlocked when exiting fullscreen or on 'ended'
- * @param    {Object} [options.touchControls={}]
- *           Touch UI options.
- * @param    {boolean} [options.touchControls.disabled=false]
- *           If true no touch controls are added.
- * @param    {int} [options.touchControls.seekSeconds=10]
- *           Number of seconds to seek on double-tap
- * @param    {int} [options.touchControls.tapTimeout=300]
- *           Interval in ms to be considered a doubletap
- * @param    {boolean} [options.touchControls.disableOnEnd=false]
- *           Whether to disable when the video ends (e.g., if there is an endscreen)
- *           Never shows if the endscreen plugin is present
+ * @param    {MobileUiOptions} [options={}] Plugin options
  */
 const mobileUi = function(options = {}) {
   if (options.forceForTesting || videojs.browser.IS_ANDROID || videojs.browser.IS_IOS) {

package/src/swipeFullscreen.js

@@ -0,0 +1,122 @@
+/** @import Player from 'video.js/dist/types/player' */
+/** @import Plugin from 'video.js/dist/types/plugin' */
+/** @import {MobileUiOptions} from './plugin' */
+
+/**
+ * Sets up swiping to enter and exit fullscreen.
+ *
+ * @this {Plugin}
+ * @param {Player} player
+ *  The player to initialise on.
+ * @param {MobileUiOptions} pluginOptions
+ *  The options used by the mobile ui plugin.
+ */
+const initSwipe = (player, pluginOptions) => {
+  const {swipeToFullscreen, swipeFromFullscreen} = pluginOptions.fullscreen;
+
+  if (swipeToFullscreen) {
+    player.addClass('using-fs-swipe-up');
+  }
+  if (swipeFromFullscreen) {
+    player.addClass('using-fs-swipe-down');
+  }
+
+  let touchStartY = 0;
+  let couldBeSwiping = false;
+  const swipeThreshold = 30;
+
+  /**
+   * Monitor the possible start of a swipe
+   *
+   * @param {TouchEvent} e Triggering touch event
+   */
+  const onStart = (e) => {
+    const isFullscreen = player.isFullscreen();
+
+    if (
+      (!isFullscreen && !swipeToFullscreen) ||
+      (isFullscreen && !swipeFromFullscreen)
+    ) {
+      couldBeSwiping = false;
+      return;
+    }
+
+    touchStartY = e.changedTouches[0].clientY;
+    couldBeSwiping = true;
+    player.tech_.el().style.transition = '';
+  };
+
+  /**
+   * Monitor the movement of a swipe
+   *
+   * @param {TouchEvent} e Triggering touch event
+   */
+  const onMove = (e) => {
+    if (!couldBeSwiping) {
+      return;
+    }
+
+    const currentY = e.touches[0].clientY;
+    const deltaY = touchStartY - currentY;
+    const isFullscreen = player.isFullscreen();
+
+    let scale = 1;
+
+    if (!isFullscreen && deltaY > 0) {
+      // Swiping up to enter fullscreen: Zoom in (Max 1.1)
+      scale = 1 + Math.min(0.1, deltaY / 500);
+      player.tech_.el().style.transform = `scale(${scale})`;
+    } else if (isFullscreen && deltaY < 0) {
+      // Swiping down to exit fullscreen: Zoom out (Min 0.9)
+      scale = 1 - Math.min(0.1, Math.abs(deltaY) / 500);
+      player.tech_.el().style.transform = `scale(${scale})`;
+    }
+  };
+
+  /**
+   * Monitor the touch end to determine a valid swipe
+   *
+   * @param {TouchEvent} e Triggering touch event
+   */
+  const onEnd = (e) => {
+    if (!couldBeSwiping) {
+      return;
+    }
+    couldBeSwiping = false;
+
+    player.tech_.el().style.transition = 'transform 0.3s ease-out';
+    player.tech_.el().style.transform = 'scale(1)';
+
+    if (e.type === 'touchcancel') {
+      return;
+    }
+
+    const touchEndY = e.changedTouches[0].clientY;
+    const deltaY = touchStartY - touchEndY;
+
+    if (deltaY > swipeThreshold && !player.isFullscreen()) {
+      player.requestFullscreen().catch((err) => {
+        player.log.warn('Browser refused fullscreen', err);
+      });
+    } else if (deltaY < -swipeThreshold && player.isFullscreen()) {
+      player.exitFullscreen();
+    }
+  };
+
+  player.el().addEventListener('touchstart', onStart, { passive: true });
+  player.el().addEventListener('touchmove', onMove, { passive: true });
+  player.el().addEventListener('touchend', onEnd, { passive: true });
+  player.el().addEventListener('touchcancel', onEnd, { passive: true });
+
+  player.on('dispose', () => {
+    player.el().removeEventListener('touchstart', onStart, { passive: true });
+    player.el().removeEventListener('touchmove', onMove, { passive: true });
+    player.el().removeEventListener('touchend', onEnd, { passive: true });
+    player.el().removeEventListener('touchcancel', onEnd, { passive: true });
+    player.tech_.el().style.transform = '';
+    player.tech_.el().style.transition = '';
+  });
+
+};
+
+export default initSwipe;

package/src/touchOverlay.js

@@ -6,6 +6,8 @@
 import videojs from 'video.js';
 import window from 'global/window';
 
+/** @import Player from 'video.js/dist/types/player' */
+
 const Component = videojs.getComponent('Component');
 const dom = videojs.dom || videojs;
 
@@ -22,7 +24,7 @@ class TouchOverlay extends Component {
   * @param  {Player} player
   *         The `Player` that this class should be attached to.
   *
-  * @param  {Object} [options]
+  * @param  {options} [options]
   *         The key/value store of player options.
   */
   constructor(player, options) {
@@ -117,7 +119,9 @@ class TouchOverlay extends Component {
       return;
     }
 
-    event.preventDefault();
+    if (event.cancelable) {
+      event.preventDefault();
+    }
 
     this.taps += 1;
     if (this.taps === 1) {