1
0
Fork 0
mirror of https://github.com/jellyfin/jellyfin-web synced 2025-03-30 19:56:21 +00:00

Update documentation

This commit is contained in:
Dmitry Lyzo 2020-03-31 18:59:12 +03:00
parent 1646687773
commit a1cc977872
3 changed files with 125 additions and 81 deletions

View file

@ -21,7 +21,7 @@ import layoutManager from "layoutManager";
} }
/** /**
* Start AutoFocuser * Start AutoFocuser.
*/ */
export function enable() { export function enable() {
if (!isEnabled()) { if (!isEnabled()) {
@ -37,8 +37,8 @@ import layoutManager from "layoutManager";
/** /**
* Set focus on a suitable element, taking into account the previously selected. * Set focus on a suitable element, taking into account the previously selected.
* @param {HTMLElement} [container] - element to limit scope * @param {HTMLElement} [container] - Element to limit scope.
* @returns {HTMLElement} focused element * @returns {HTMLElement} Focused element.
*/ */
export function autoFocus(container) { export function autoFocus(container) {
if (!isEnabled()) { if (!isEnabled()) {

View file

@ -7,10 +7,10 @@
/** /**
* Returns parent of element with specified attribute value. * Returns parent of element with specified attribute value.
* @param {HTMLElement} elem - element whose parent need to find * @param {HTMLElement} elem - Element whose parent need to find.
* @param {string} name - attribute name * @param {string} name - Attribute name.
* @param {mixed} value - attribute value * @param {mixed} value - Attribute value.
* @returns {HTMLElement} Parent with specified attribute value * @returns {HTMLElement} Parent with specified attribute value.
*/ */
export function parentWithAttribute(elem, name, value) { export function parentWithAttribute(elem, name, value) {
while ((value ? elem.getAttribute(name) !== value : !elem.getAttribute(name))) { while ((value ? elem.getAttribute(name) !== value : !elem.getAttribute(name))) {
@ -26,9 +26,9 @@
/** /**
* Returns parent of element with one of specified tag names. * Returns parent of element with one of specified tag names.
* @param {HTMLElement} elem - element whose parent need to find * @param {HTMLElement} elem - Element whose parent need to find.
* @param {(string|Array)} tagNames - tag name or array of tag names * @param {(string|Array)} tagNames - Tag name or array of tag names.
* @returns {HTMLElement} Parent with one of specified tag names * @returns {HTMLElement} Parent with one of specified tag names.
*/ */
export function parentWithTag(elem, tagNames) { export function parentWithTag(elem, tagNames) {
// accept both string and array passed in // accept both string and array passed in
@ -49,9 +49,9 @@
/** /**
* Returns _true_ if class list contains one of specified names. * Returns _true_ if class list contains one of specified names.
* @param {DOMTokenList} classList - class list * @param {DOMTokenList} classList - Class list.
* @param {Array} classNames - array of class names * @param {Array} classNames - Array of class names.
* @returns {boolean} _true_ if class list contains one of specified names * @returns {boolean} _true_ if class list contains one of specified names.
*/ */
function containsAnyClass(classList, classNames) { function containsAnyClass(classList, classNames) {
for (let i = 0, length = classNames.length; i < length; i++) { for (let i = 0, length = classNames.length; i < length; i++) {
@ -64,9 +64,9 @@
/** /**
* Returns parent of element with one of specified class names. * Returns parent of element with one of specified class names.
* @param {HTMLElement} elem - element whose parent need to find * @param {HTMLElement} elem - Element whose parent need to find.
* @param {(string|Array)} classNames - class name or array of class names * @param {(string|Array)} classNames - Class name or array of class names.
* @returns {HTMLElement} Parent with one of specified class names * @returns {HTMLElement} Parent with one of specified class names.
*/ */
export function parentWithClass(elem, classNames) { export function parentWithClass(elem, classNames) {
// accept both string and array passed in // accept both string and array passed in
@ -100,10 +100,10 @@
/** /**
* Adds event listener to specified target. * Adds event listener to specified target.
* @param {EventTarget} target - event target * @param {EventTarget} target - Event target.
* @param {string} type - event type * @param {string} type - Event type.
* @param {function} handler - event handler * @param {function} handler - Event handler.
* @param {Object} [options] - listener options * @param {Object} [options] - Listener options.
*/ */
export function addEventListener(target, type, handler, options) { export function addEventListener(target, type, handler, options) {
let optionsOrCapture = options || {}; let optionsOrCapture = options || {};
@ -115,10 +115,10 @@
/** /**
* Removes event listener from specified target. * Removes event listener from specified target.
* @param {EventTarget} target - event target * @param {EventTarget} target - Event target.
* @param {string} type - event type * @param {string} type - Event type.
* @param {function} handler - event handler * @param {function} handler - Event handler.
* @param {Object} [options] - listener options * @param {Object} [options] - Listener options.
*/ */
export function removeEventListener(target, type, handler, options) { export function removeEventListener(target, type, handler, options) {
let optionsOrCapture = options || {}; let optionsOrCapture = options || {};
@ -147,7 +147,7 @@
/** /**
* Returns window size. * Returns window size.
* @returns {Object} Window size * @returns {Object} Window size.
*/ */
export function getWindowSize() { export function getWindowSize() {
if (!windowSize) { if (!windowSize) {
@ -173,7 +173,7 @@
/** /**
* Returns screen width. * Returns screen width.
* @returns {number} Screen width * @returns {number} Screen width.
*/ */
export function getScreenWidth() { export function getScreenWidth() {
let width = window.innerWidth; let width = window.innerWidth;
@ -197,7 +197,7 @@
/** /**
* Returns name of animation end event. * Returns name of animation end event.
* @returns {string} Name of animation end event * @returns {string} Name of animation end event.
*/ */
export function whichAnimationEvent() { export function whichAnimationEvent() {
if (_animationEvent) { if (_animationEvent) {
@ -224,7 +224,7 @@
/** /**
* Returns name of animation cancel event. * Returns name of animation cancel event.
* @returns {string} Name of animation cancel event * @returns {string} Name of animation cancel event.
*/ */
export function whichAnimationCancelEvent() { export function whichAnimationCancelEvent() {
return whichAnimationEvent().replace('animationend', 'animationcancel').replace('AnimationEnd', 'AnimationCancel'); return whichAnimationEvent().replace('animationend', 'animationcancel').replace('AnimationEnd', 'AnimationCancel');
@ -237,7 +237,7 @@
/** /**
* Returns name of transition end event. * Returns name of transition end event.
* @returns {string} Name of transition end event * @returns {string} Name of transition end event.
*/ */
export function whichTransitionEvent() { export function whichTransitionEvent() {
if (_transitionEvent) { if (_transitionEvent) {

View file

@ -24,7 +24,7 @@ import layoutManager from "layoutManager";
* Returns minimum vertical scroll. * Returns minimum vertical scroll.
* Scroll less than that value will be zeroed. * Scroll less than that value will be zeroed.
* *
* @return {number} minimum vertical scroll * @return {number} Minimum vertical scroll.
*/ */
function minimumScrollY() { function minimumScrollY() {
const topMenu = document.querySelector(".headerTop"); const topMenu = document.querySelector(".headerTop");
@ -55,10 +55,10 @@ import layoutManager from "layoutManager";
/** /**
* Returns value clamped by range [min, max]. * Returns value clamped by range [min, max].
* *
* @param {number} value - clamped value * @param {number} value - Clamped value.
* @param {number} min - begining of range * @param {number} min - Begining of range.
* @param {number} max - ending of range * @param {number} max - Ending of range.
* @return {number} clamped value * @return {number} Clamped value.
*/ */
function clamp(value, min, max) { function clamp(value, min, max) {
return value <= min ? min : value >= max ? max : value; return value <= min ? min : value >= max ? max : value;
@ -68,11 +68,11 @@ import layoutManager from "layoutManager";
* Returns the required delta to fit range 1 into range 2. * Returns the required delta to fit range 1 into range 2.
* In case of range 1 is bigger than range 2 returns delta to fit most out of range part. * In case of range 1 is bigger than range 2 returns delta to fit most out of range part.
* *
* @param {number} begin1 - begining of range 1 * @param {number} begin1 - Begining of range 1.
* @param {number} end1 - ending of range 1 * @param {number} end1 - Ending of range 1.
* @param {number} begin2 - begining of range 2 * @param {number} begin2 - Begining of range 2.
* @param {number} end2 - ending of range 2 * @param {number} end2 - Ending of range 2.
* @return {number} delta: <0 move range1 to the left, >0 - to the right * @return {number} Delta: <0 move range1 to the left, >0 - to the right.
*/ */
function fitRange(begin1, end1, begin2, end2) { function fitRange(begin1, end1, begin2, end2) {
const delta1 = begin1 - begin2; const delta1 = begin1 - begin2;
@ -88,13 +88,21 @@ import layoutManager from "layoutManager";
/** /**
* Ease value. * Ease value.
* *
* @param {number} t - value in range [0, 1] * @param {number} t - Value in range [0, 1].
* @return {number} eased value in range [0, 1] * @return {number} Eased value in range [0, 1].
*/ */
function ease(t) { function ease(t) {
return t*(2 - t); // easeOutQuad === ease-out return t*(2 - t); // easeOutQuad === ease-out
} }
/**
* @typedef {Object} Rect
* @property {number} left - X coordinate of top-left corner.
* @property {number} top - Y coordinate of top-left corner.
* @property {number} width - Width.
* @property {number} height - Height.
*/
/** /**
* Document scroll wrapper helps to unify scrolling and fix issues of some browsers. * Document scroll wrapper helps to unify scrolling and fix issues of some browsers.
* *
@ -109,6 +117,10 @@ import layoutManager from "layoutManager";
* Tizen 5 Browser/Native: scrolls documentElement (and window); has a document.scrollingElement * Tizen 5 Browser/Native: scrolls documentElement (and window); has a document.scrollingElement
*/ */
class DocumentScroller { class DocumentScroller {
/**
* Horizontal scroll position.
* @type {number}
*/
get scrollLeft() { get scrollLeft() {
return window.pageXOffset; return window.pageXOffset;
} }
@ -117,6 +129,10 @@ import layoutManager from "layoutManager";
window.scroll(val, window.pageYOffset); window.scroll(val, window.pageYOffset);
} }
/**
* Vertical scroll position.
* @type {number}
*/
get scrollTop() { get scrollTop() {
return window.pageYOffset; return window.pageYOffset;
} }
@ -125,22 +141,42 @@ import layoutManager from "layoutManager";
window.scroll(window.pageXOffset, val); window.scroll(window.pageXOffset, val);
} }
/**
* Horizontal scroll size (scroll width).
* @type {number}
*/
get scrollWidth() { get scrollWidth() {
return Math.max(document.documentElement.scrollWidth, document.body.scrollWidth); return Math.max(document.documentElement.scrollWidth, document.body.scrollWidth);
} }
/**
* Vertical scroll size (scroll height).
* @type {number}
*/
get scrollHeight() { get scrollHeight() {
return Math.max(document.documentElement.scrollHeight, document.body.scrollHeight); return Math.max(document.documentElement.scrollHeight, document.body.scrollHeight);
} }
/**
* Horizontal client size (client width).
* @type {number}
*/
get clientWidth() { get clientWidth() {
return Math.min(document.documentElement.clientWidth, document.body.clientWidth); return Math.min(document.documentElement.clientWidth, document.body.clientWidth);
} }
/**
* Vertical client size (client height).
* @type {number}
*/
get clientHeight() { get clientHeight() {
return Math.min(document.documentElement.clientHeight, document.body.clientHeight); return Math.min(document.documentElement.clientHeight, document.body.clientHeight);
} }
/**
* Returns bounding client rect.
* @return {Rect} Bounding client rect.
*/
getBoundingClientRect() { getBoundingClientRect() {
// Make valid viewport coordinates: documentElement.getBoundingClientRect returns rect of entire document relative to viewport // Make valid viewport coordinates: documentElement.getBoundingClientRect returns rect of entire document relative to viewport
return { return {
@ -151,6 +187,10 @@ import layoutManager from "layoutManager";
}; };
} }
/**
* Scrolls window.
* @param {...mixed} args See window.scrollTo.
*/
scrollTo() { scrollTo() {
window.scrollTo.apply(window, arguments); window.scrollTo.apply(window, arguments);
} }
@ -162,10 +202,11 @@ import layoutManager from "layoutManager";
const documentScroller = new DocumentScroller(); const documentScroller = new DocumentScroller();
/** /**
* Returns parent element that can be scrolled. If no such, returns documentElement. * Returns parent element that can be scrolled. If no such, returns document scroller.
* *
* @param {HTMLElement} element - element for which parent is being searched * @param {HTMLElement} element - Element for which parent is being searched.
* @param {boolean} vertical - search for vertical scrollable parent * @param {boolean} vertical - Search for vertical scrollable parent.
* @param {HTMLElement|DocumentScroller} Parent element that can be scrolled or document scroller.
*/ */
function getScrollableParent(element, vertical) { function getScrollableParent(element, vertical) {
if (element) { if (element) {
@ -197,17 +238,17 @@ import layoutManager from "layoutManager";
/** /**
* @typedef {Object} ScrollerData * @typedef {Object} ScrollerData
* @property {number} scrollPos - current scroll position * @property {number} scrollPos - Current scroll position.
* @property {number} scrollSize - scroll size * @property {number} scrollSize - Scroll size.
* @property {number} clientSize - client size * @property {number} clientSize - Client size.
*/ */
/** /**
* Returns scroll data for specified orientation. * Returns scroller data for specified orientation.
* *
* @param {HTMLElement} scroller - scroller * @param {HTMLElement} scroller - Scroller.
* @param {boolean} vertical - vertical scroll data * @param {boolean} vertical - Vertical scroller data.
* @return {ScrollerData} scroll data * @return {ScrollerData} Scroller data.
*/ */
function getScrollerData(scroller, vertical) { function getScrollerData(scroller, vertical) {
let data = {}; let data = {};
@ -228,10 +269,10 @@ import layoutManager from "layoutManager";
/** /**
* Returns position of child of scroller for specified orientation. * Returns position of child of scroller for specified orientation.
* *
* @param {HTMLElement} scroller - scroller * @param {HTMLElement} scroller - Scroller.
* @param {HTMLElement} element - child of scroller * @param {HTMLElement} element - Child of scroller.
* @param {boolean} vertical - vertical scroll * @param {boolean} vertical - Vertical scroll.
* @return {number} child position * @return {number} Child position.
*/ */
function getScrollerChildPos(scroller, element, vertical) { function getScrollerChildPos(scroller, element, vertical) {
const elementRect = element.getBoundingClientRect(); const elementRect = element.getBoundingClientRect();
@ -247,11 +288,11 @@ import layoutManager from "layoutManager";
/** /**
* Returns scroll position for element. * Returns scroll position for element.
* *
* @param {ScrollerData} scrollerData - scroller data * @param {ScrollerData} scrollerData - Scroller data.
* @param {number} elementPos - child element position * @param {number} elementPos - Child element position.
* @param {number} elementSize - child element size * @param {number} elementSize - Child element size.
* @param {boolean} centered - scroll to center * @param {boolean} centered - Scroll to center.
* @return {number} scroll position * @return {number} Scroll position.
*/ */
function calcScroll(scrollerData, elementPos, elementSize, centered) { function calcScroll(scrollerData, elementPos, elementSize, centered) {
const maxScroll = scrollerData.scrollSize - scrollerData.clientSize; const maxScroll = scrollerData.scrollSize - scrollerData.clientSize;
@ -271,8 +312,8 @@ import layoutManager from "layoutManager";
/** /**
* Calls scrollTo function in proper way. * Calls scrollTo function in proper way.
* *
* @param {HTMLElement} scroller - scroller * @param {HTMLElement} scroller - Scroller.
* @param {ScrollToOptions} options - scroll options * @param {ScrollToOptions} options - Scroll options.
*/ */
function scrollToHelper(scroller, options) { function scrollToHelper(scroller, options) {
if ("scrollTo" in scroller) { if ("scrollTo" in scroller) {
@ -296,11 +337,11 @@ import layoutManager from "layoutManager";
/** /**
* Performs built-in scroll. * Performs built-in scroll.
* *
* @param {HTMLElement} xScroller - horizontal scroller * @param {HTMLElement} xScroller - Horizontal scroller.
* @param {number} scrollX - horizontal coordinate * @param {number} scrollX - Horizontal coordinate.
* @param {HTMLElement} yScroller - vertical scroller * @param {HTMLElement} yScroller - Vertical scroller.
* @param {number} scrollY - vertical coordinate * @param {number} scrollY - Vertical coordinate.
* @param {boolean} smooth - smooth scrolling * @param {boolean} smooth - Smooth scrolling.
*/ */
function builtinScroll(xScroller, scrollX, yScroller, scrollY, smooth) { function builtinScroll(xScroller, scrollX, yScroller, scrollY, smooth) {
const scrollBehavior = smooth ? "smooth" : "instant"; const scrollBehavior = smooth ? "smooth" : "instant";
@ -313,6 +354,9 @@ import layoutManager from "layoutManager";
} }
} }
/**
* Requested frame for animated scroll.
*/
let scrollTimer; let scrollTimer;
/** /**
@ -326,10 +370,10 @@ import layoutManager from "layoutManager";
/** /**
* Performs animated scroll. * Performs animated scroll.
* *
* @param {HTMLElement} xScroller - horizontal scroller * @param {HTMLElement} xScroller - Horizontal scroller.
* @param {number} scrollX - horizontal coordinate * @param {number} scrollX - Horizontal coordinate.
* @param {HTMLElement} yScroller - vertical scroller * @param {HTMLElement} yScroller - Vertical scroller.
* @param {number} scrollY - vertical coordinate * @param {number} scrollY - Vertical coordinate.
*/ */
function animateScroll(xScroller, scrollX, yScroller, scrollY) { function animateScroll(xScroller, scrollX, yScroller, scrollY) {
@ -372,11 +416,11 @@ import layoutManager from "layoutManager";
/** /**
* Performs scroll. * Performs scroll.
* *
* @param {HTMLElement} xScroller - horizontal scroller * @param {HTMLElement} xScroller - Horizontal scroller.
* @param {number} scrollX - horizontal coordinate * @param {number} scrollX - Horizontal coordinate.
* @param {HTMLElement} yScroller - vertical scroller * @param {HTMLElement} yScroller - Vertical scroller.
* @param {number} scrollY - vertical coordinate * @param {number} scrollY - Vertical coordinate.
* @param {boolean} smooth - smooth scrolling * @param {boolean} smooth - Smooth scrolling.
*/ */
function doScroll(xScroller, scrollX, yScroller, scrollY, smooth) { function doScroll(xScroller, scrollX, yScroller, scrollY, smooth) {
@ -420,9 +464,9 @@ import layoutManager from "layoutManager";
/** /**
* Scrolls the document to a given position. * Scrolls the document to a given position.
* *
* @param {number} scrollX - horizontal coordinate * @param {number} scrollX - Horizontal coordinate.
* @param {number} scrollY - vertical coordinate * @param {number} scrollY - Vertical coordinate.
* @param {boolean} [smooth=false] - smooth scrolling * @param {boolean} [smooth=false] - Smooth scrolling.
*/ */
export function scrollTo(scrollX, scrollY, smooth) { export function scrollTo(scrollX, scrollY, smooth) {
@ -443,8 +487,8 @@ import layoutManager from "layoutManager";
/** /**
* Scrolls the document to a given element. * Scrolls the document to a given element.
* *
* @param {HTMLElement} element - target element of scroll task * @param {HTMLElement} element - Target element of scroll task.
* @param {boolean} [smooth=false] - smooth scrolling * @param {boolean} [smooth=false] - Smooth scrolling.
*/ */
export function scrollToElement(element, smooth) { export function scrollToElement(element, smooth) {