@videojs/html 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/reference/feature-fullscreen.md

@@ -0,0 +1,116 @@
+# Fullscreen
+
+Fullscreen state and actions for the player store
+
+Controls fullscreen mode. Tries the container element first, falls back to the media element.
+
+## Import
+
+ts
+
+```
+import { fullscreenFeature } from '@videojs/html';
+```
+
+The `liveVideoFeatures` and `videoFeatures` [feature bundles](../concepts/presets.md) include this feature.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`fullscreen`
+
+`boolean`
+
+▸
+
+Description
+
+Whether fullscreen mode is currently active.
+
+`fullscreenAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether fullscreen can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter fullscreen mode. Tries container first, falls back to media element.
+
+`exitFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit fullscreen mode.
+
+`toggleFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle fullscreen mode.
+
+### Selector
+
+Pass `selectFullscreen` to [`PlayerController`](./player-controller.md) to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.
+
+fullscreen-button.ts
+
+```
+import { createPlayer, UIElement, selectFullscreen } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({ features: videoFeatures });
+
+class FullscreenButton extends UIElement {
+  readonly #fullscreen = new PlayerController(this, selectFullscreen);
+}
+```
+
+### Screen orientation
+
+Add [`features.orientationLock`](./feature-orientation-lock.md) to lock screen orientation while fullscreen is active. Unsupported browsers and rejected lock requests are ignored, so iOS Safari continues to use its normal fullscreen behavior.
+
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type.
+
+html
+
+```
+<my-player orientation-lock-type="portrait">
+  <video src="/video.mp4"></video>
+</my-player>
+```
+
+See [Orientation lock](./feature-orientation-lock.md) for the player setup.

package/docs/reference/feature-live.md

@@ -0,0 +1,101 @@
+# Live
+
+Live edge state for the player store
+
+Tracks when playback is at the live edge and what kind of live window the stream provides.
+
+*   `liveEdgeStart` is the playback time where the live edge begins. Playback counts as live when `currentTime` reaches this value.
+*   `targetLiveWindow` describes the kind of live window. Despite its name, it does not report a number of seconds: `0` means a sliding live window, `Infinity` means a live event with playback history, and `NaN` means on-demand or not known yet.
+
+Both values are `NaN` when the media does not provide live-edge information.
+
+Use the [buffer feature](./feature-buffer.md) to find the times a viewer can seek to. Its `seekable` value contains `[start, end]` pairs. On a sliding live stream, the oldest and newest available times both move forward.
+
+The live presets do not include the [stream type feature](./feature-stream-type.md), so `selectStreamType` returns `undefined` unless you add it to a custom player.
+
+The [time feature](./feature-time.md) reports the end of the available live video as `duration`, even when the browser reports `Infinity`. To check for live playback, use `!Number.isNaN(targetLiveWindow)` instead of checking `duration`.
+
+## Import
+
+ts
+
+```
+import { liveFeature } from '@videojs/html';
+```
+
+The `liveAudioFeatures` and `liveVideoFeatures` [feature bundles](../concepts/presets.md) include this feature.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`liveEdgeStart`
+
+`number`
+
+▸
+
+Description
+
+Playback time where the live edge begins.
+
+Playback is live when `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown.
+
+`targetLiveWindow`
+
+`number`
+
+▸
+
+Description
+
+Describes the kind of live window available. This value is not a duration.
+
+`0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown.
+
+### Selector
+
+Pass `selectLive` to [`PlayerController`](./player-controller.md) to subscribe to live state. Returns `undefined` if the live feature is not configured.
+
+live-edge-button.ts
+
+```
+import { createPlayer, UIElement, selectLive } from '@videojs/html';
+import { liveVideoFeatures } from '@videojs/html/live-video';
+
+const { PlayerController } = createPlayer({ features: liveVideoFeatures });
+
+class LiveEdgeButton extends UIElement {
+  readonly #live = new PlayerController(this, selectLive);
+}
+```
+
+## Jump to the live edge
+
+Use the packaged live button for the usual jump-to-live behavior. It combines the live, time, and buffer features, then seeks to the end of the last `seekable` range. It also manages its accessible label and disabled state.
+
+index.html
+
+```
+<script type="module">
+  import '@videojs/html/ui/live-button';
+</script>
+
+<media-live-button class="station-live-button">On air</media-live-button>
+```
+
+Put the button in your custom controls and style it there. Do not calculate the destination from `duration` or set `currentTime` to `Infinity`.
+
+If you need different behavior, you can combine the same public features yourself:
+
+*   Read `targetLiveWindow` from `selectLive` to check that the source is live.
+*   Read the newest available time from the last range returned by `selectBuffer`.
+*   Call the `seek()` action returned by `selectTime` with that time.
+
+Read the same three selectors with [`PlayerController`](./player-controller.md). Call `selectTime`’s `seek()` action with the last end time from `selectBuffer` when `selectLive` reports a live source.

package/docs/reference/feature-metadata.md

@@ -0,0 +1,153 @@
+# Metadata
+
+Resolved title and poster values for the player store
+
+Resolves what is playing into two values your UI can render: `title` and `poster`.
+
+`title` and `poster` each resolve independently through the same two tiers: the value you set, then the value the media reports. The first tier that holds a value wins; when neither does, the resolved value is an empty string. Because the tiers stay separate, clearing the value you set reveals the media’s, and a source that reports a poster but no title contributes to one while leaving the other empty.
+
+An empty string counts as a value and stops the chain: set `title` to `''` and the resolved title is `''`. Pass `null` to clear your value.
+
+The metadata feature is included by the `videoFeatures`, `audioFeatures`, `liveVideoFeatures`, and `liveAudioFeatures` [presets](../concepts/presets.md); apps that build a custom preset can compose it in directly.
+
+## Import
+
+ts
+
+```
+import { metadataFeature } from '@videojs/html';
+```
+
+The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](../concepts/presets.md) include this feature.
+
+## API Reference
+
+### Configuration
+
+Attributes and matching properties the player element accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`contentTitle`
+
+`MediaContentValue`
+
+`—`
+
+▸
+
+Attribute
+
+`content-title`
+
+Description
+
+The title to display. Takes precedence over the title the media carries.
+
+`poster`
+
+`MediaContentValue`
+
+`—`
+
+▸
+
+Attribute
+
+`poster`
+
+Description
+
+The poster to display. Takes precedence over the poster the media carries.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`title`
+
+`string`
+
+▸
+
+Description
+
+The resolved content title. Set it through the player, not through the store.
+
+`poster`
+
+`string`
+
+▸
+
+Description
+
+The resolved poster URL, independent of the media element's own `poster`. Set it through the player, not through the store.
+
+### Selector
+
+To just show the name of what is playing, drop in the [Title component](./title.md) — it reads this feature for you. Reach for the selector when building your own UI.
+
+Pass `selectMetadata` to [`PlayerController`](./player-controller.md) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.
+
+content-title.ts
+
+```
+import { createPlayer, UIElement, selectMetadata } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({ features: videoFeatures });
+
+class ContentTitle extends UIElement {
+  readonly #metadata = new PlayerController(this, selectMetadata);
+}
+```
+
+### Player inputs
+
+The store publishes the resolved values and takes no writes. A player input is the only way to set one.
+
+Every input is an attribute on [`<video-player>`](./player.md), each with a matching property. A player built without the metadata feature observes none of them.
+
+`title` already means the tooltip on an HTML element, so the title input goes by `content-title` in markup, and by `contentTitle` as a property. The other inputs use their own names.
+
+html
+
+```
+<video-player content-title="The Pilot" poster="/episode-art.jpg">
+  <media-container>
+    <video src="episode.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+Removing an attribute clears your value, so it falls through to what the media reports.
+
+title-controls.ts
+
+```
+const player = document.querySelector('video-player');
+
+player?.setAttribute('content-title', 'The Pilot');
+player?.removeAttribute('content-title'); // falls back to the media
+```
+
+The flow between an attribute and its property runs one way: an attribute change writes the property, but setting the property leaves the attribute alone. Read the property for the current value.
+
+### Media-reported values
+
+The media tier comes from media that reports content data and announces changes to it, and it covers `title` and `poster`. A media reports only the keys it can vouch for, so either may be absent while the other arrives. A key that never arrives means that tier never contributes, and the resolved value is whatever you set. Detaching the media clears its values; the values you set survive and apply to the next source.
+
+`poster` is the feature’s own resolved value, not the media element’s `poster` attribute. Setting one does not set the other.
+
+A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](./poster.md) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it. [Add a poster and loading placeholder](../how-to/add-a-poster-and-loading-placeholder.md) walks through that technique for each framework.

package/docs/reference/feature-orientation-lock.md

@@ -0,0 +1,135 @@
+# Orientation lock
+
+Screen orientation locking while fullscreen is active
+
+Locks screen orientation while fullscreen is active.
+
+## Import
+
+ts
+
+```
+import { orientationLockFeature } from '@videojs/html';
+```
+
+No packaged [feature bundle](../concepts/presets.md) includes this feature — add it to your [`createPlayer`](./html-create-player.md) features yourself.
+
+## API Reference
+
+### Configuration
+
+Attributes and matching properties the player element accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`orientationLockType`
+
+`undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+`'landscape'`
+
+▸
+
+Attribute
+
+`orientation-lock-type`
+
+Description
+
+Screen orientation type to lock while fullscreen is active.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`orientationLockType`
+
+`'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+▸
+
+Description
+
+Screen orientation type locked while fullscreen is active.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`setOrientationLockType`
+
+`(value: 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | null | undefined) => void`
+
+▸
+
+Description
+
+Sets the locked orientation type. Absent input — nullish, or the empty string a valueless HTML attribute produces — restores the default.
+
+### Usage
+
+Selecting the feature adds it to the player.
+
+player.ts
+
+```
+import { createPlayer, features } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement: MyPlayer } = createPlayer({
+  features: [...videoFeatures, features.orientationLock],
+});
+
+customElements.define('my-player', MyPlayer);
+```
+
+### Orientation type
+
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type. The value can change while the player is running; if the screen is already locked, it re-locks to the new type.
+
+html
+
+```
+<my-player orientation-lock-type="portrait">
+  <video src="/video.mp4"></video>
+</my-player>
+```
+
+The attribute only exists on a player that selected the feature. Setting it on an element built from `videoFeatures` alone does nothing.
+
+Clearing the value restores `landscape`.
+
+### Selector
+
+Pass `selectOrientationLock` to [`PlayerController`](./player-controller.md) to subscribe to the lock state. Returns `undefined` if the orientation lock feature is not configured.
+
+orientation-toggle.ts
+
+```
+import { createPlayer, features, UIElement, selectOrientationLock } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({
+  features: [...videoFeatures, features.orientationLock],
+});
+
+class OrientationToggle extends UIElement {
+  readonly #lock = new PlayerController(this, selectOrientationLock);
+}
+```
+
+Unsupported browsers and rejected lock requests are ignored.

package/docs/reference/feature-pip.md

@@ -0,0 +1,100 @@
+# Picture-in-picture
+
+Picture-in-picture state and actions for the player store
+
+Controls picture-in-picture mode.
+
+## Import
+
+ts
+
+```
+import { pipFeature } from '@videojs/html';
+```
+
+The `liveVideoFeatures` and `videoFeatures` [feature bundles](../concepts/presets.md) include this feature.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`pip`
+
+`boolean`
+
+▸
+
+Description
+
+Whether picture-in-picture mode is currently active.
+
+`pipAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether picture-in-picture can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter picture-in-picture mode.
+
+`exitPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit picture-in-picture mode.
+
+`togglePictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle picture-in-picture mode.
+
+### Selector
+
+Pass `selectPiP` to [`PlayerController`](./player-controller.md) to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.
+
+pip-button.ts
+
+```
+import { createPlayer, UIElement, selectPiP } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({ features: videoFeatures });
+
+class PiPButton extends UIElement {
+  readonly #pip = new PlayerController(this, selectPiP);
+}
+```

package/docs/reference/feature-playback-rate.md

@@ -0,0 +1,80 @@
+# Playback rate
+
+Playback speed state and actions for the player store
+
+Controls speed of playback.
+
+## Import
+
+ts
+
+```
+import { playbackRateFeature } from '@videojs/html';
+```
+
+The `audioFeatures` and `videoFeatures` [feature bundles](../concepts/presets.md) include this feature.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`playbackRates`
+
+`readonly number[]`
+
+▸
+
+Description
+
+Available playback rates.
+
+`playbackRate`
+
+`number`
+
+▸
+
+Description
+
+Current playback rate.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`setPlaybackRate`
+
+`(rate: number) => void`
+
+▸
+
+Description
+
+Set the playback rate.
+
+### Selector
+
+Pass `selectPlaybackRate` to [`PlayerController`](./player-controller.md) to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
+
+rate-display.ts
+
+```
+import { createPlayer, UIElement, selectPlaybackRate } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({ features: videoFeatures });
+
+class RateDisplay extends UIElement {
+  readonly #rate = new PlayerController(this, selectPlaybackRate);
+}
+```