From 49e03b2d1f141c41eeb10d0fb4087a14cace1c56 Mon Sep 17 00:00:00 2001 From: Bitaru Date: Wed, 20 Mar 2024 22:57:31 +0100 Subject: [PATCH] chore: add property descriptions --- .../video-button/Video-button.component.ts | 11 ++++++++ .../Video-condition.component.ts | 21 +++++++++++++++ .../Video-container.component.ts | 5 ++++ .../Video-controls.component.ts | 13 +++++++++ .../video-cues/Video-cues.component.ts | 15 +++++++++++ .../Video-errors-manager.component.ts | 4 +++ .../Video-live-sign.component.ts | 3 +++ .../video-menu/Video-menu.component.ts | 12 +++++++++ .../video-player/Video-player.component.ts | 24 +++++++++++++++++ .../Video-progress.component.ts | 7 +++++ .../video-slider/Video-slider.component.ts | 27 +++++++++++++++++++ .../Video-timeline.component.ts | 9 +++++++ .../video-timer/Video-timer.component.ts | 6 +++++ 13 files changed, 157 insertions(+) diff --git a/src/components/video-button/Video-button.component.ts b/src/components/video-button/Video-button.component.ts index 868d61b..54daff3 100644 --- a/src/components/video-button/Video-button.component.ts +++ b/src/components/video-button/Video-button.component.ts @@ -18,12 +18,23 @@ export class VideoButton extends LitElement { static styles = unsafeCSS(styles); public command = createCommand(this); + /** + * Specifies the offset distance of the tooltip from the button. + */ @property({ type: Number, attribute: "tooltip-offset" }) tooltipOffset = 40; + /** + * Determines whether the button should display a tooltip. + * If set to `true`, the tooltip will not be displayed. + * Defaults to `false`, meaning the tooltip will be shown by default. + */ @property({ type: Boolean, attribute: "without-tooltip" }) withoutTooltip = false; + /** + * Specifies the preferred position of the tooltip relative to the button. + */ @property({ attribute: "tooltip-position" }) tooltipPosition: Placement = "top"; diff --git a/src/components/video-condition/Video-condition.component.ts b/src/components/video-condition/Video-condition.component.ts index b88a7e7..89411e0 100644 --- a/src/components/video-condition/Video-condition.component.ts +++ b/src/components/video-condition/Video-condition.component.ts @@ -37,9 +37,30 @@ const createCompare = @customElement("video-condition") export class VideoCondition extends LitElement { + /** + * A query string specifying conditions to be evaluated against the application state. + * The query string consists of one or more comparison expressions separated by logical operators (&& or ||). + * Each comparison expression follows the pattern: "key comparator value", where: + * - key: The key of a property in the application state to be compared. + * - comparator: The comparison operator (>, >=, <, <=, ==, or !=). + * - value: The value to compare against the property in the application state. + * Examples of valid comparison expressions: + * - "isActive == true" + * - "volume >= 50" + * - "currentTime < 100" + * - "isMuted != false" + * Multiple comparison expressions can be combined using logical operators: + * - "isActive == true && volume >= 50" + * - "currentTime < 100 || isMuted != false" + */ @property() query?: string; + /** + * Indicates whether the conditions specified by the query are currently matching the state of the application. + * This property reflects the result of evaluating the query against the application state. + * If the conditions specified in the query match the state, this property is set to true; otherwise, it is false. + */ @property({ type: Boolean, reflect: true, attribute: "matching" }) isMatching: boolean; diff --git a/src/components/video-container/Video-container.component.ts b/src/components/video-container/Video-container.component.ts index 5bc4427..d3c7f3c 100644 --- a/src/components/video-container/Video-container.component.ts +++ b/src/components/video-container/Video-container.component.ts @@ -67,6 +67,11 @@ export class VideoContainer extends LitElement { @connect("live") live: boolean; + /** + * A unique identifier used for storing and retrieving user preferences related to video playback. + * These preferences include volume level, selected quality level, active text track, playback rate, and mute status. + * When provided, these preferences are stored in the browser's local storage to maintain user settings across sessions. + */ @property({ type: String, attribute: "storage-key" }) storageKey: string; diff --git a/src/components/video-controls/Video-controls.component.ts b/src/components/video-controls/Video-controls.component.ts index 31db20c..eb5f0df 100644 --- a/src/components/video-controls/Video-controls.component.ts +++ b/src/components/video-controls/Video-controls.component.ts @@ -11,18 +11,31 @@ import styles from "./Video-controls.styles.css?inline"; export class VideoControls extends DependentPropsMixin(LitElement) { static styles = unsafeCSS(styles); + /** + * Indicates whether the video player is in idle mode. + */ @connect("idle") @property({ type: Boolean, reflect: true }) idle: boolean; + /** + * Indicates whether the video is currently playing. + */ @connect("isPlaying") @property({ type: Boolean, reflect: true }) playing: boolean; + /** + * Indicates whether the video player is in fullscreen mode. + */ @connect("isFullscreen") @property({ type: Boolean, reflect: true }) fullscreen: boolean; + /** + * Indicates whether the video controls are customized. + * If true, the controls are custom; if false, they are default. + */ @property({ type: Boolean, reflect: true }) custom = false; diff --git a/src/components/video-cues/Video-cues.component.ts b/src/components/video-cues/Video-cues.component.ts index 7463baa..19c674d 100644 --- a/src/components/video-cues/Video-cues.component.ts +++ b/src/components/video-cues/Video-cues.component.ts @@ -8,20 +8,35 @@ import { connect } from "../../state"; export class VideoCues extends LitElement { static styles = unsafeCSS(styles); + /** + * Indicates whether the video player is in idle mode. + */ @connect("idle") @property({ type: Boolean, reflect: true }) idle: boolean; + /** + * The currently active text track (e.g., subtitles or captions). + */ @connect("activeTextTrack") activeTextTrack: string; + /** + * An array of cues or subtitles to be displayed during video playback. + */ @connect("cues") cues: string[]; + /** + * Indicates whether the device is an iOS device. + */ @connect("isIos") @property({ type: Boolean, reflect: true, attribute: "is-ios" }) isIos: true; + /** + * Indicates whether the video player is in fullscreen mode. + */ @connect("isFullscreen") isFullscreen: false; diff --git a/src/components/video-errors-manager/Video-errors-manager.component.ts b/src/components/video-errors-manager/Video-errors-manager.component.ts index 7e571c3..acecb52 100644 --- a/src/components/video-errors-manager/Video-errors-manager.component.ts +++ b/src/components/video-errors-manager/Video-errors-manager.component.ts @@ -9,6 +9,10 @@ export class VideoErrorsManager extends LitElement { timer = 0; + /** + * The timeout duration (in milliseconds) for displaying error messages before clearing. + * If set to 0, error messages will persist until manually cleared. + */ @property({ type: Number }) timeout = 10000; diff --git a/src/components/video-live-sign/Video-live-sign.component.ts b/src/components/video-live-sign/Video-live-sign.component.ts index a80b062..ba737a6 100644 --- a/src/components/video-live-sign/Video-live-sign.component.ts +++ b/src/components/video-live-sign/Video-live-sign.component.ts @@ -8,6 +8,9 @@ import { createCommand, connect } from "../../state"; export class VideoLiveSign extends LitElement { static styles = unsafeCSS(styles); + /** + * Indicates whether the video stream is live. + */ @connect("live") live: boolean; diff --git a/src/components/video-menu/Video-menu.component.ts b/src/components/video-menu/Video-menu.component.ts index 0566b7c..600207c 100644 --- a/src/components/video-menu/Video-menu.component.ts +++ b/src/components/video-menu/Video-menu.component.ts @@ -5,11 +5,17 @@ import styles from "./Video-menu.styles.css?inline"; import { eventCode, emit } from "../../helpers/event"; type MenuItem = { + // The value associated with the menu item value: string | number; + // The text label of the menu item label: string; + // Indicates whether the menu item is currently active isActive?: boolean; + // Icon to display before the label iconBefore?: any; + // Icon to display after the label iconAfter?: any; + // Keyboard shortcut for the menu item key?: string; }; @@ -17,9 +23,15 @@ type MenuItem = { export class VideoMenu extends LitElement { static styles = unsafeCSS(styles); + /** + * An array of menu items to display. + */ @property({ type: Array }) items: MenuItem[] = []; + /** + * The title of the menu. + */ @property() title: string; diff --git a/src/components/video-player/Video-player.component.ts b/src/components/video-player/Video-player.component.ts index 2644aa9..86a80d4 100644 --- a/src/components/video-player/Video-player.component.ts +++ b/src/components/video-player/Video-player.component.ts @@ -31,27 +31,51 @@ export class VideoPlayer extends LitElement { public state = createState(this); public fullscreen = new FullscreenController(this); + /** + * The ID of the element to be used as the fullscreen container. + */ @property({ type: String, attribute: "fullscreen-element" }) fullscreenContainer: string; + /** + * Indicates whether the player is in idle mode. + */ @property({ type: Boolean, reflect: true }) idle = false; + /** + * Parameters to be passed to Mux for analytics. + */ @property({ type: Object, attribute: "mux-data" }) muxData: MuxParams; + /** + * Indicates whether the player should automatically focus on load. + */ @property({ type: Boolean }) autofocus = false; + /** + * The duration of inactivity before the player enters idle mode (in milliseconds). + */ @property({ type: Number, attribute: "idle-timeout" }) idleTimeout = 9000; + /** + * The tabindex of the player for keyboard navigation. + */ @property({ type: Number, attribute: true, reflect: true }) tabindex = 0; + /** + * The key used for storing player state in local storage. + */ @property({ type: String, attribute: "storage-key" }) storageKey: string; + /** + * The time offset (in seconds) to seek the video to. + */ @property({ type: Number }) offset: number; diff --git a/src/components/video-progress/Video-progress.component.ts b/src/components/video-progress/Video-progress.component.ts index 43f4942..ff5b0b7 100644 --- a/src/components/video-progress/Video-progress.component.ts +++ b/src/components/video-progress/Video-progress.component.ts @@ -7,9 +7,16 @@ import { ifDefined } from "lit/directives/if-defined.js"; export class VideoProgress extends LitElement { static styles = unsafeCSS(styles); + /** + * The current value of the progress bar. + * Should be a number between 0 and 100. + */ @property({ type: Number }) value = 0; + /** + * Indicates whether the progress bar is in a loading state. + */ @property({ type: Boolean }) loading = false; diff --git a/src/components/video-slider/Video-slider.component.ts b/src/components/video-slider/Video-slider.component.ts index 02ace78..c53ae8f 100644 --- a/src/components/video-slider/Video-slider.component.ts +++ b/src/components/video-slider/Video-slider.component.ts @@ -21,30 +21,57 @@ const generateGetBoundingClientRect = export class VideoSlider extends LitElement { static styles = unsafeCSS(styles); + /** + * The current value of the slider + */ @property({ type: Number }) value = 0; + /** + * The maximum value allowed on the slider + */ @property({ type: Number }) max = 1; + /** + * Indicates whether the slider is disabled. + */ @property({ type: Boolean, reflect: true }) disabled = false; + /** + * Indicates whether the slider should take up full width. + */ @property({ type: Boolean, reflect: true }) full = false; + /** + * Indicates whether the slider is in a loading state. + */ @property({ type: Boolean, reflect: true }) loading = false; + /** + * Text to display as the value of the slider. + */ @property({ attribute: "value-text" }) valueText = ""; + /** + * Text to display in the tooltip. + */ @property({ attribute: "tooltip-text" }) tooltipText = ""; + /** + * Determines whether the slider should have a tooltip. + */ @property({ type: Boolean, attribute: "with-tooltip" }) withTooltip = false; + /** + * Offset for positioning the tooltip relative to the slider. + */ @property({ type: Number, attribute: "tooltip-offset" }) tooltipOffset = -11; diff --git a/src/components/video-timeline/Video-timeline.component.ts b/src/components/video-timeline/Video-timeline.component.ts index df210cb..613960b 100644 --- a/src/components/video-timeline/Video-timeline.component.ts +++ b/src/components/video-timeline/Video-timeline.component.ts @@ -30,9 +30,18 @@ export class VideoTimeline extends DependentPropsMixin(LitElement) { static styles = unsafeCSS(styles); public command = createCommand(this); + /** + * Indicates whether the video timeline is disabled or not. + */ @property({ type: Boolean }) disabled = false; + /** + * The segments property provides a flexible + * mechanism for dividing the video timeline into distinct segments, + * enabling enhanced visualization and navigation of the video content + * based on different temporal divisions or events. + */ @property({ type: Array, converter: segmentConverter }) segments: number[] = [0]; diff --git a/src/components/video-timer/Video-timer.component.ts b/src/components/video-timer/Video-timer.component.ts index b4d2e48..f58119a 100644 --- a/src/components/video-timer/Video-timer.component.ts +++ b/src/components/video-timer/Video-timer.component.ts @@ -8,6 +8,12 @@ import { timeAsString } from "../../helpers/time"; export class VideoTimer extends LitElement { static styles = unsafeCSS(styles); + /** + * Specifies the format in which the time information should be displayed by the video timer component. + * `left`: Displays the time remaining until the end of the video. + * `past`: Displays the time elapsed since the beginning of the video. + * `total`: Displays the total duration of the video. + */ @property() format: "left" | "past" | "total" = "left";