@taprootio/espalier 4.20.1 → 5.0.0

package/dist/switch/esp-switch.js

@@ -1,4 +1,4 @@
-var s=function(a,e,i,l){var c=arguments.length,o=c<3?e:l===null?l=Object.getOwnPropertyDescriptor(e,i):l,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(a,e,i,l);else for(var h=a.length-1;h>=0;h--)(n=a[h])&&(o=(c<3?n(o):c>3?n(e,i,o):n(e,i))||o);return c>3&&o&&Object.defineProperty(e,i,o),o};import{css as m,html as d}from"lit";import{customElement as v,property as r}from"lit/decorators.js";import{classMap as p}from"lit/directives/class-map.js";import{EspalierElementBase as u}from"../shared/esp-element-base.js";import{FormFieldController as b}from"../shared/form-field-controller.js";import{FormFieldDescriptionController as g}from"../shared/form-field-description-controller.js";import{disabledControl as w,focusRing as f,srOnly as y}from"../shared/style-fragments.js";let t=class extends u{constructor(){super(...arguments),this.internals=this.attachInternals(),this.formCtrl=new b({host:this,internals:this.internals,getFormValue:()=>this.checked?this.value||"on":null,getValidity:()=>this.required&&!this.checked?{flags:{valueMissing:!0},message:this.requiredMessage||"Please toggle this switch to continue."}:null,onReset:()=>{this.checked=!1},onRestore:e=>{this.checked=e==="on"||e===this.value},onDisabled:e=>{this.disabled=e}}),this.formItemDescription=new g({host:this,getTarget:()=>this.shadowRoot?.querySelector(".switch-control")}),this.mode="switch",this.offLabel="",this.onLabel="",this.checked=!1,this.value="",this.name="",this.required=!1,this.requiredMessage="",this.disabled=!1}focus(e){this.focusShadowElementAfterUpdate(".switch-control",e)}setFormItemDescription(e){this.formItemDescription.setDescription(e)}validate(){this.formCtrl.validate()}checkValidity(){return this.formCtrl.checkValidity()}toggle(){this.disabled||(this.checked=!this.checked,this.formCtrl.syncValue(),this.emitValueChanged({checked:this.checked,value:this.value}))}handleKeyDown(e){(e.key===" "||e.key==="Enter")&&(e.preventDefault(),this.toggle())}handleLabelSlotChange(){this.requestUpdate()}getCurrentTextModeLabel(){return(this.checked?this.onLabel:this.offLabel).trim()}getTextModeAriaLabel(){const e=this.textContent?.replace(/\s+/g," ").trim()??"",i=this.getCurrentTextModeLabel();return e&&i?`${e}: ${i}`:e||i}formResetCallback(){this.formCtrl.handleFormReset()}formStateRestoreCallback(e){this.formCtrl.handleFormStateRestore(e)}formDisabledCallback(e){this.formCtrl.handleFormDisabled(e)}render(){return this.mode==="text"?d`
+var r=function(a,e,s,l){var c=arguments.length,o=c<3?e:l===null?l=Object.getOwnPropertyDescriptor(e,s):l,n;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")o=Reflect.decorate(a,e,s,l);else for(var h=a.length-1;h>=0;h--)(n=a[h])&&(o=(c<3?n(o):c>3?n(e,s,o):n(e,s))||o);return c>3&&o&&Object.defineProperty(e,s,o),o};import{css as f,html as d}from"lit";import{customElement as v,property as i}from"lit/decorators.js";import{classMap as p}from"lit/directives/class-map.js";import{EspalierElementBase as u}from"../shared/esp-element-base.js";import{FormFieldController as b}from"../shared/form-field-controller.js";import{FormFieldDescriptionController as g}from"../shared/form-field-description-controller.js";import{disabledControl as w,focusRing as m,srOnly as y}from"../shared/style-fragments.js";let t=class extends u{constructor(){super(...arguments),this.internals=this.attachInternals(),this.formCtrl=new b({host:this,internals:this.internals,getFormValue:()=>this.checked?this.value||"on":null,getValidity:()=>this.required&&!this.checked?{flags:{valueMissing:!0},message:this.requiredMessage||"Please toggle this switch to continue."}:null,onReset:()=>{this.checked=!1},onRestore:e=>{this.checked=e==="on"||e===this.value},onDisabled:e=>{this.disabled=e}}),this.formItemDescription=new g({host:this,getTarget:()=>this.shadowRoot?.querySelector(".switch-control")}),this.mode="switch",this.offLabel="",this.onLabel="",this.checked=!1,this.value="",this.name="",this.required=!1,this.requiredMessage="",this.disabled=!1}focus(e){this.focusShadowElementAfterUpdate(".switch-control",e)}setFormItemDescription(e){this.formItemDescription.setDescription(e)}setFormItemInvalid(e){this.formItemDescription.setInvalid(e)}validate(){this.formCtrl.validate()}checkValidity(){return this.formCtrl.checkValidity()}toggle(){this.disabled||(this.checked=!this.checked,this.formCtrl.syncValue(),this.emitValueChanged({checked:this.checked,value:this.value}))}handleKeyDown(e){(e.key===" "||e.key==="Enter")&&(e.preventDefault(),this.toggle())}handleLabelSlotChange(){this.requestUpdate()}getCurrentTextModeLabel(){return(this.checked?this.onLabel:this.offLabel).trim()}getTextModeAriaLabel(){const e=this.textContent?.replace(/\s+/g," ").trim()??"",s=this.getCurrentTextModeLabel();return e&&s?`${e}: ${s}`:e||s}formResetCallback(){this.formCtrl.handleFormReset()}formStateRestoreCallback(e){this.formCtrl.handleFormStateRestore(e)}formDisabledCallback(e){this.formCtrl.handleFormDisabled(e)}render(){return this.mode==="text"?d`
         <div
           class="switch-control text-control"
           role="switch"
@@ -34,7 +34,7 @@ var s=function(a,e,i,l){var c=arguments.length,o=c<3?e:l===null?l=Object.getOwnP
         </div>
         <span class="label"><slot></slot></span>
       </div>
-    `}};t.formAssociated=!0,t.styles=[...u.styles,y,f(".switch-control:focus-visible","--esp-switch-focus-shadow"),f(".text-control:focus-visible","--esp-switch-focus-shadow"),w(".switch-control"),m`
+    `}};t.clearsFormItemErrorOnChange=!0,t.formAssociated=!0,t.styles=[...u.styles,y,m(".switch-control:focus-visible","--esp-switch-focus-shadow"),m(".text-control:focus-visible","--esp-switch-focus-shadow"),w(".switch-control"),f`
       :host {
         display: block;
       }
@@ -153,4 +153,4 @@ var s=function(a,e,i,l){var c=arguments.length,o=c<3?e:l===null?l=Object.getOwnP
       .text-option.active {
         color: var(--esp-switch-text-active-color, var(--esp-color-action-text));
       }
-    `],s([r({type:String,reflect:!0})],t.prototype,"mode",void 0),s([r({attribute:"off-label"})],t.prototype,"offLabel",void 0),s([r({attribute:"on-label"})],t.prototype,"onLabel",void 0),s([r({type:Boolean,reflect:!0})],t.prototype,"checked",void 0),s([r({type:String})],t.prototype,"value",void 0),s([r({type:String,reflect:!0})],t.prototype,"name",void 0),s([r({type:Boolean,reflect:!0})],t.prototype,"required",void 0),s([r({attribute:"required-message"})],t.prototype,"requiredMessage",void 0),s([r({type:Boolean,reflect:!0})],t.prototype,"disabled",void 0),t=s([v("esp-switch")],t);export{t as EspalierSwitch};
+    `],r([i({type:String,reflect:!0})],t.prototype,"mode",void 0),r([i({attribute:"off-label"})],t.prototype,"offLabel",void 0),r([i({attribute:"on-label"})],t.prototype,"onLabel",void 0),r([i({type:Boolean,reflect:!0})],t.prototype,"checked",void 0),r([i({type:String})],t.prototype,"value",void 0),r([i({type:String,reflect:!0})],t.prototype,"name",void 0),r([i({type:Boolean,reflect:!0})],t.prototype,"required",void 0),r([i({attribute:"required-message"})],t.prototype,"requiredMessage",void 0),r([i({type:Boolean,reflect:!0})],t.prototype,"disabled",void 0),t=r([v("esp-switch")],t);export{t as EspalierSwitch};

package/dist/textarea/esp-textarea.js

@@ -1,4 +1,4 @@
-var r=function(n,e,i,l){var h=arguments.length,a=h<3?e:l===null?l=Object.getOwnPropertyDescriptor(e,i):l,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(n,e,i,l);else for(var u=n.length-1;u>=0;u--)(d=n[u])&&(a=(h<3?d(a):h>3?d(e,i,a):d(e,i))||a);return h>3&&a&&Object.defineProperty(e,i,a),a};import{css as m,html as p}from"lit";import{customElement as f,property as s}from"lit/decorators.js";import{ifDefined as o}from"lit/directives/if-defined.js";import{createRef as v,ref as g}from"lit/directives/ref.js";import{EspalierElementBase as c}from"../shared/esp-element-base.js";import{FormFieldController as y}from"../shared/form-field-controller.js";import{FormFieldDescriptionController as b}from"../shared/form-field-description-controller.js";let t=class extends c{constructor(){super(...arguments),this.internals=this.attachInternals(),this.theTextarea=v(),this.formCtrl=new y({host:this,internals:this.internals,getFormValue:()=>this.value||null,getValidity:()=>this._getValidity(),getValidationAnchor:()=>this.theTextarea.value??this,onReset:()=>{this.value="",this._hasVisibleError=!1},onRestore:e=>{this.value=e},onDisabled:e=>{this.disabled=e}}),this.formItemDescription=new b({host:this,getTarget:()=>this.theTextarea.value}),this._hasVisibleError=!1,this.fieldName="",this.value="",this.name="",this.required=!1,this.requiredMessage="",this.validationMessage="",this.disabled=!1,this._trackVisibleError=e=>{const i=e.detail;this._hasVisibleError=!i.valid}}handleInput(e){const i=e.target;this.value=i.value,this._syncInput()}_syncInput(){this._hasVisibleError?this.formCtrl.syncValue():this.formCtrl.syncValueSilently(),this.emitValueChanged(this.value)}_handleBlur(){this.formCtrl.syncValue()}_getValidity(){const e=this.theTextarea.value;if(e&&!e.validity.valid){const i=e.validity,l={valueMissing:i.valueMissing,tooLong:i.tooLong,tooShort:i.tooShort};return{flags:l,message:this._getFriendlyMessage(l)}}return this.required&&!this.value?{flags:{valueMissing:!0},message:this.requiredMessage||"Please fill out this field."}:null}_getFriendlyMessage(e){return e.valueMissing?this.requiredMessage||"Please fill out this field.":e.tooShort?this.validationMessage||`Must be at least ${this.minlength} characters.`:e.tooLong?this.validationMessage||`Must be no more than ${this.maxlength} characters.`:"Please enter a valid value."}focus(e){this.focusResolvedElementAfterUpdate(()=>this.theTextarea.value,e)}setFormItemDescription(e){this.formItemDescription.setDescription(e)}setFormItemLabel(e){this.formItemDescription.setLabel(e)}validate(){this.formCtrl.validate()}checkValidity(){return this.formCtrl.checkValidity()}formResetCallback(){this.formCtrl.handleFormReset()}formStateRestoreCallback(e){this.formCtrl.handleFormStateRestore(e)}formDisabledCallback(e){this.formCtrl.handleFormDisabled(e)}connectedCallback(){super.connectedCallback(),this.addEventListener("esp-validity-changed",this._trackVisibleError)}disconnectedCallback(){super.disconnectedCallback(),this.removeEventListener("esp-validity-changed",this._trackVisibleError)}render(){return p`
+var r=function(n,e,i,l){var h=arguments.length,a=h<3?e:l===null?l=Object.getOwnPropertyDescriptor(e,i):l,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")a=Reflect.decorate(n,e,i,l);else for(var u=n.length-1;u>=0;u--)(d=n[u])&&(a=(h<3?d(a):h>3?d(e,i,a):d(e,i))||a);return h>3&&a&&Object.defineProperty(e,i,a),a};import{css as c,html as p}from"lit";import{customElement as f,property as s}from"lit/decorators.js";import{ifDefined as o}from"lit/directives/if-defined.js";import{createRef as v,ref as g}from"lit/directives/ref.js";import{EspalierElementBase as m}from"../shared/esp-element-base.js";import{FormFieldController as y}from"../shared/form-field-controller.js";import{FormFieldDescriptionController as b}from"../shared/form-field-description-controller.js";let t=class extends m{constructor(){super(...arguments),this.internals=this.attachInternals(),this.theTextarea=v(),this.formCtrl=new y({host:this,internals:this.internals,getFormValue:()=>this.value||null,getValidity:()=>this._getValidity(),getValidationAnchor:()=>this.theTextarea.value??this,onReset:()=>{this.value="",this._hasVisibleError=!1},onRestore:e=>{this.value=e},onDisabled:e=>{this.disabled=e}}),this.formItemDescription=new b({host:this,getTarget:()=>this.theTextarea.value}),this._hasVisibleError=!1,this.fieldName="",this.value="",this.name="",this.required=!1,this.requiredMessage="",this.validationMessage="",this.disabled=!1,this._trackVisibleError=e=>{const i=e.detail;this._hasVisibleError=!i.valid}}handleInput(e){const i=e.target;this.value=i.value,this._syncInput()}_syncInput(){this._hasVisibleError?this.formCtrl.syncValue():this.formCtrl.syncValueSilently(),this.emitValueChanged(this.value)}_handleBlur(){this.formCtrl.syncValue()}_getValidity(){const e=this.theTextarea.value;if(e&&!e.validity.valid){const i=e.validity,l={valueMissing:i.valueMissing,tooLong:i.tooLong,tooShort:i.tooShort};return{flags:l,message:this._getFriendlyMessage(l)}}return this.required&&!this.value?{flags:{valueMissing:!0},message:this.requiredMessage||"Please fill out this field."}:null}_getFriendlyMessage(e){return e.valueMissing?this.requiredMessage||"Please fill out this field.":e.tooShort?this.validationMessage||`Must be at least ${this.minlength} characters.`:e.tooLong?this.validationMessage||`Must be no more than ${this.maxlength} characters.`:"Please enter a valid value."}focus(e){this.focusResolvedElementAfterUpdate(()=>this.theTextarea.value,e)}setFormItemDescription(e){this.formItemDescription.setDescription(e)}setFormItemInvalid(e){this.formItemDescription.setInvalid(e)}setFormItemLabel(e){this.formItemDescription.setLabel(e)}validate(){this.formCtrl.validate()}checkValidity(){return this.formCtrl.checkValidity()}formResetCallback(){this.formCtrl.handleFormReset()}formStateRestoreCallback(e){this.formCtrl.handleFormStateRestore(e)}formDisabledCallback(e){this.formCtrl.handleFormDisabled(e)}connectedCallback(){super.connectedCallback(),this.addEventListener("esp-validity-changed",this._trackVisibleError)}disconnectedCallback(){super.disconnectedCallback(),this.removeEventListener("esp-validity-changed",this._trackVisibleError)}render(){return p`
       <div class="esp-field">
         <textarea
           id=${this.fieldName}
@@ -15,7 +15,7 @@ var r=function(n,e,i,l){var h=arguments.length,a=h<3?e:l===null?l=Object.getOwnP
           ?disabled=${this.disabled}
         ></textarea>
       </div>
-    `}};t.formAssociated=!0,t.styles=[...c.styles,m`
+    `}};t.formAssociated=!0,t.styles=[...m.styles,c`
       .esp-field {
         margin: 1px;
 

package/dist/video/esp-video.d.ts

@@ -0,0 +1,266 @@
+import { type PropertyValues } from "lit";
+import { EspalierElementBase } from "../shared/esp-element-base.js";
+/** The HLS master-playlist media type, and the default `type`. */
+export declare const HLS_MEDIA_TYPE = "application/vnd.apple.mpegurl";
+/** The `aspect-ratio` used when the attribute is absent or invalid. */
+export declare const DEFAULT_VIDEO_ASPECT_RATIO = "16 / 9";
+export type VideoPreload = "none" | "metadata" | "auto";
+export type VideoControls = "native" | "none";
+export type VideoCrossOrigin = "" | "anonymous" | "use-credentials";
+/**
+ * Attaches a stream the browser cannot play natively to the element's
+ * `<video>`. Called with the video element and the `src` URL; returns, or
+ * resolves to, a teardown function the element calls when the source goes
+ * away. A rejection (or a synchronous throw) is a failed attach.
+ */
+export type VideoAdapter = (video: HTMLVideoElement, src: string) => Promise<() => void> | (() => void);
+/**
+ * How the playing source reached the video: `native` set `src` directly,
+ * `adapter` went through the host's adapter, and `fallback` is playing
+ * `fallback-src`.
+ */
+export type VideoSourceMode = "native" | "adapter" | "fallback";
+/**
+ * Why playback failed: `unsupported` when no `src` is set (and no fallback),
+ * or nothing could play `type` (no native support, no adapter, no fallback), `adapter` when the adapter rejected or
+ * threw, and `media` when the video element reported an error while loading
+ * or playing.
+ */
+export type VideoErrorReason = "unsupported" | "adapter" | "media";
+/**
+ * Detail of `esp-video-ready` on `esp-video`.
+ *
+ * @docUrl /api/video-ready-detail
+ * @menuGroup Event Details
+ * @menuLabel VideoReadyDetail
+ */
+export interface VideoReadyDetail {
+    /** The element's `src`. */
+    src: string;
+    /** How the source was attached. */
+    mode: VideoSourceMode;
+    /** The media duration in seconds; `Infinity` for a live stream. */
+    duration: number;
+}
+/**
+ * Detail of `esp-video-play` on `esp-video`.
+ *
+ * @docUrl /api/video-play-detail
+ * @menuGroup Event Details
+ * @menuLabel VideoPlayDetail
+ */
+export interface VideoPlayDetail {
+    /** The element's `src`. */
+    src: string;
+    /** How the source was attached. */
+    mode: VideoSourceMode;
+    /** The playback position, in seconds, at which playback started. */
+    currentTime: number;
+    /** Whether `autoplay` started this playback rather than the visitor. */
+    autoplay: boolean;
+}
+/**
+ * Detail of `esp-video-error` on `esp-video`.
+ *
+ * @docUrl /api/video-error-detail
+ * @menuGroup Event Details
+ * @menuLabel VideoErrorDetail
+ */
+export interface VideoErrorDetail {
+    /** The element's `src`. */
+    src: string;
+    /** The attachment that failed, or `null` when nothing was attached. */
+    mode: VideoSourceMode | null;
+    /** Why playback failed. */
+    reason: VideoErrorReason;
+    /** A short developer-facing description; not shown to visitors. */
+    message: string;
+    /** Whether the element is now trying `fallback-src`. */
+    fallback: boolean;
+}
+/**
+ * A native video player: a `<video>` element with a lazy poster, a fixed
+ * aspect ratio, captions, native controls, and visible loading and error
+ * states. It is never an iframe and never loads a third-party player.
+ *
+ * Nothing but the poster loads until the visitor presses play, so a page of
+ * videos costs one image request each. The play affordance over the poster is
+ * a real button named from `label` or `poster-alt`.
+ *
+ * ```html
+ * <esp-video
+ *   src="/assets/esp-video/espalier-sample.mp4"
+ *   type="video/mp4"
+ *   poster="/assets/esp-video/espalier-sample-poster.jpg"
+ *   poster-alt="Espalier's palette drifting across a trellis grid"
+ *   playsinline
+ * ></esp-video>
+ * ```
+ *
+ * ### Streaming
+ *
+ * `src` is an HLS master playlist by default. Where the browser plays HLS
+ * natively (Safari, iOS, current Chrome) the element sets `src` and plays.
+ * Where it does not, the element calls the host's `adapter` once, on first
+ * play intent, and the host attaches a streaming library such as hls.js.
+ * Espalier itself carries no player dependency. Without an adapter,
+ * `fallback-src` (an MP4) plays instead. The Video guide has a copy-ready
+ * hls.js adapter, with error handling, and the full lifecycle.
+ *
+ * ```js
+ * import { EspalierVideo } from "@taprootio/espalier/video";
+ * EspalierVideo.defaultAdapter = async (video, src) => {
+ *   const { default: Hls } = await import("hls.js");
+ *   const hls = new Hls();
+ *   hls.loadSource(src);
+ *   hls.attachMedia(video);
+ *   return () => hls.destroy();
+ * };
+ * ```
+ *
+ * ### Captions
+ *
+ * Give the element `<track>` children. A media element only reads its own
+ * child tracks, so the element mirrors them into its video when it attaches
+ * the source; `kind`, `srclang`, `label`, and `default` carry through. With
+ * the default `preload="none"`, no caption file loads before the visitor
+ * presses play.
+ *
+ * ```html
+ * <esp-video
+ *   src="/assets/esp-video/espalier-sample.mp4"
+ *   type="video/mp4"
+ *   poster="/assets/esp-video/espalier-sample-poster.jpg"
+ *   poster-alt="The trellis sample, with English captions"
+ *   aspect-ratio="21 / 9"
+ * >
+ *   <track kind="captions" src="/assets/esp-video/espalier-sample.en.vtt" srclang="en" label="English" default />
+ * </esp-video>
+ * ```
+ *
+ * ### Autoplay
+ *
+ * `autoplay` starts playback once the element is admitted (immediately, or
+ * near the viewport with `defer-offscreen`). It always plays muted: while
+ * `autoplay` is set the video stays muted whatever `muted` says, so a page
+ * never starts sound unprompted. It does not start for a visitor who prefers
+ * reduced motion, or where the browser blocks it; the poster and play button
+ * remain.
+ *
+ * @slot - `<track>` elements for captions, subtitles, descriptions, and chapters.
+ * @slot error - Replaces the error message shown over the poster.
+ * @csspart frame - The element's full box.
+ * @csspart video - The native `<video>` element.
+ * @csspart poster - The layer over the video holding the poster, play button, and messages.
+ * @csspart poster-image - The poster `<img>`.
+ * @csspart play - The play `<button>`, which covers the poster.
+ * @csspart play-icon - The visible play disc inside the button.
+ * @csspart message - The error message.
+ * @cssprop --esp-video-surface - Background behind the video and an absent poster. Defaults to a near-black derived from `--esp-color-text`.
+ * @cssprop --esp-video-border-radius - Corner radius. Defaults to `var(--esp-size-border-radius)`.
+ * @cssprop --esp-video-object-fit - How the video fills its box. Defaults to `contain`; the poster always covers.
+ * @cssprop --esp-video-accent - `accent-color` for the native controls, where the browser honors it. Defaults to `var(--esp-color-primary)`.
+ * @cssprop --esp-video-focus-outline - Focus-visible outline on the play button, the video, and the error message. Defaults to `3px solid var(--esp-color-link)`.
+ * @cssprop --esp-video-play-size - Diameter of the play disc. Defaults to `var(--esp-size-huge)`.
+ * @cssprop --esp-video-play-background - Fill of the play disc. Defaults to `var(--esp-color-background)` at 90% opacity.
+ * @cssprop --esp-video-play-color - Play glyph and loading-indicator color. Defaults to `var(--esp-color-text)`.
+ * @cssprop --esp-video-message-background - Error message background. Defaults to `var(--esp-color-background)`.
+ * @cssprop --esp-video-message-color - Error message text color. Defaults to `var(--esp-color-text)`.
+ * @event {CustomEvent<VideoReadyDetail>} esp-video-ready - Bubbles across shadow boundaries once the attached source has loaded its metadata; `detail` is `{ src, mode, duration }`. Fires once per attached source.
+ * @event {CustomEvent<VideoPlayDetail>} esp-video-play - Bubbles across shadow boundaries each time playback starts, or resumes after a pause, on the media's `playing`. Recovery from buffering or a seek is not reported, and a source that fails first reports no play; `detail` is `{ src, mode, currentTime, autoplay }`.
+ * @event {CustomEvent<VideoErrorDetail>} esp-video-error - Bubbles across shadow boundaries when a source fails; `detail` is `{ src, mode, reason, message, fallback }`. When `fallback` is true the element is already trying `fallback-src`.
+ * @docPageTitle Video
+ * @docUrl /components/video
+ * @menuGroup Media
+ * @menuLabel Video
+ * @menuIcon photo
+ */
+export declare class EspalierVideo extends EspalierElementBase {
+    /**
+     * The adapter used by every `esp-video` whose own `adapter` is unset.
+     * Register it once, before any video can receive a play intent — in the
+     * same module that imports Espalier is early enough, even for `autoplay`.
+     */
+    static defaultAdapter: VideoAdapter | null;
+    /** The media URL: an HLS master playlist by default, or a file matching `type`. */
+    src: string;
+    /**
+     * The media type of `src`, checked with `canPlayType` to choose between
+     * native playback and the adapter. `video/mp4` plays as a plain file.
+     */
+    type: string;
+    /** Poster image URL, shown until playback starts and behind error messages. */
+    poster: string;
+    /** Describes the poster; names the play button when `label` is unset. */
+    posterAlt: string;
+    /**
+     * The play button's accessible name. Defaults to `Play video: <poster-alt>`,
+     * or `Play video` with no poster text.
+     */
+    label: string;
+    /**
+     * The box's aspect ratio, as a positive number or `number / number`. Invalid
+     * values fall back to `16 / 9`.
+     */
+    aspectRatio: string;
+    /**
+     * How much media to load before play intent. `none` (the default) loads
+     * only the poster. `metadata` and `auto` apply where the browser plays
+     * `type` natively; an adapter stream, and the choice of the fallback over
+     * it, still wait for play intent. A natively preloaded source that fails
+     * switches to `fallback-src` at once.
+     */
+    preload: VideoPreload;
+    /** Start muted playback once admitted. Implies `muted`. */
+    autoplay: boolean;
+    /**
+     * Start muted. Always on while `autoplay` is set. Clearing it (or
+     * `autoplay`) unmutes only a paused video; a playing one stays muted until
+     * the visitor unmutes it.
+     */
+    muted: boolean;
+    /** Restart from the beginning when playback ends. */
+    loop: boolean;
+    /** Play inline on iOS rather than entering full screen. Needed for inline autoplay there. */
+    playsinline: boolean;
+    /**
+     * `native` (the default) shows the browser's controls once playback starts.
+     * `none` shows none; use it only for short decorative loops, since a visitor
+     * then has no way to pause.
+     */
+    controls: VideoControls;
+    /**
+     * Defer everything — the poster, `preload`, and `autoplay` — until the
+     * element is within 200px of the viewport. The poster is not rendered
+     * before then, so the browser's own lazy-loading distance cannot fetch it
+     * early.
+     */
+    deferOffscreen: boolean;
+    /**
+     * An MP4 played when `type` cannot play natively and no adapter is
+     * available, and tried once when the primary source fails.
+     */
+    fallbackSrc: string;
+    /**
+     * CORS mode for the video's requests, as on `<video crossorigin>`. Needed
+     * for caption tracks served from another origin.
+     */
+    crossOrigin: VideoCrossOrigin;
+    /**
+     * Attaches a stream the browser cannot play natively; see `VideoAdapter`.
+     * Called once per source, on first play intent, only when `canPlayType`
+     * reports `type` unplayable. Falls back to `EspalierVideo.defaultAdapter`.
+     */
+    adapter: VideoAdapter | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    protected render(): import("lit-html").TemplateResult<1>;
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "esp-video": EspalierVideo;
+    }
+}

package/dist/video/esp-video.js

@@ -0,0 +1,253 @@
+var o=function(n,t,e,s){var i=arguments.length,r=i<3?t:s===null?s=Object.getOwnPropertyDescriptor(t,e):s,c;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(n,t,e,s);else for(var d=n.length-1;d>=0;d--)(c=n[d])&&(r=(i<3?c(r):i>3?c(t,e,r):c(t,e))||r);return i>3&&r&&Object.defineProperty(t,e,r),r},u;import{css as A,html as h,nothing as p}from"lit";import{customElement as S,property as l,state as f}from"lit/decorators.js";import{keyed as O}from"lit/directives/keyed.js";import{EspalierElementBase as m}from"../shared/esp-element-base.js";import{ESP_EVENTS as y}from"../shared/events.js";import{srOnly as w}from"../shared/style-fragments.js";import{prefersReducedMotion as x}from"../shared/viewport.js";import{parseImageRatio as P}from"../image/image-ratio.js";import{enumConverter as v}from"../shared/enum-converter.js";const g="application/vnd.apple.mpegurl",C="16 / 9",b=new Set(["none","metadata","auto"]),k=new Set(["native","none"]),T=new Set(["","anonymous","use-credentials"]),$={fromAttribute(n){return n===null?"":n==="use-credentials"?"use-credentials":"anonymous"},toAttribute(n){return n||null}};function R(n){return n instanceof Error&&n.message?n.message:typeof n=="string"&&n?n:"The adapter failed to attach the stream."}function E(n){const t=n.error;return t?t.message||`MediaError code ${t.code}.`:"The video reported a playback error."}let a=u=class extends m{constructor(){super(...arguments),this.src="",this.type="application/vnd.apple.mpegurl",this.poster="",this.posterAlt="",this.label="",this.aspectRatio="16 / 9",this.preload="none",this.autoplay=!1,this.muted=!1,this.loop=!1,this.playsinline=!1,this.controls="native",this.deferOffscreen=!1,this.fallbackSrc="",this.crossOrigin="",this.adapter=null,this.phase="idle",this.started=!1,this.offscreenAdmitted=!1,this.attached=null,this.adapterAttaching=!1,this.adapterAttachErrored=!1,this.attaching=null,this.videoKey=0,this.mutedVideo=null,this.attachingEarly=!1,this.teardown=null,this.generation=0,this.triedFallback=!1,this.readyEmitted=!1,this.playIntent=!1,this.autoplayAttempted=!1,this.intentAutoplay=!1,this.autoplayPending=!1,this.playAttempt=0,this.pendingPlay=null,this.focusMessageOnError=!1,this.offscreenObserver=null,this.handleTrackSlotChange=()=>{const t=this.video;t&&this.attached&&this.mirrorTracks(t)},this.handlePlayClick=()=>{this.phase!=="loading"&&this.requestPlayback(!1)},this.handleLoadedMetadata=t=>{this.isCurrent(t)&&this.emitReady(t.currentTarget)},this.handlePlay=t=>{if(!this.isCurrent(t)||!this.attached)return;const e=this.autoplayPending;this.autoplayPending=!1,this.intentAutoplay=e,this.playIntent=!0,this.pendingPlay={autoplay:e}},this.handlePlaying=async t=>{const e=t.currentTarget;if(!this.isCurrent(t)||!this.attached)return;const s=this.pendingPlay;this.pendingPlay=null;const i=this.generation;if(s&&this.dispatchEvent(new CustomEvent(y.VIDEO_PLAY,{detail:{src:this.src,mode:this.attached.mode,currentTime:e.currentTime,autoplay:s.autoplay},bubbles:!0,composed:!0})),i!==this.generation)return;const r=this.shadowRoot?.activeElement?.classList.contains("play")??!1;this.started=!0,this.phase="playing",r&&(await this.updateComplete,e.focus())},this.handleVideoError=t=>{const e=t.currentTarget;if(!this.isCurrent(t))return;if(!this.attached){this.adapterAttaching&&(this.adapterAttachErrored=!0);return}const s=this.generation,i=this.playIntent&&(!this.started||!e.paused);this.failOver(e,"media",E(e))&&i&&this.startPlayback(e,s)}}get video(){return this.shadowRoot?.querySelector("video")??null}canPlayNatively(t){return t.canPlayType(this.type||g)!==""}resolvedAdapter(){return this.adapter??u.defaultAdapter}playLabel(){return this.label?this.label:this.posterAlt?`Play video: ${this.posterAlt}`:"Play video"}connectedCallback(){super.connectedCallback(),this.requestUpdate()}disconnectedCallback(){super.disconnectedCallback(),this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!1,this.resetSource()}syncOffscreenDeferral(){if(!this.deferOffscreen||typeof IntersectionObserver>"u"){this.offscreenObserver?.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted||(this.offscreenAdmitted=!0);return}if(this.offscreenAdmitted||this.offscreenObserver)return;const t=new IntersectionObserver(e=>{this.offscreenObserver===t&&e.some(s=>s.isIntersecting)&&(t.disconnect(),this.offscreenObserver=null,this.offscreenAdmitted=!0)},{rootMargin:"200px"});this.offscreenObserver=t,t.observe(this)}willUpdate(t){super.willUpdate(t),this.isConnected&&!this.offscreenAdmitted&&this.syncOffscreenDeferral(),this.src??="",this.type??=g,this.poster??="",this.posterAlt??="",this.label??="",this.fallbackSrc??="";const e=P(this.aspectRatio)??C;this.style.setProperty("--_esp-video-aspect-ratio",e),t.has("preload")&&!b.has(this.preload)&&(this.preload="none"),t.has("controls")&&!k.has(this.controls)&&(this.controls="native"),t.has("crossOrigin")&&!T.has(this.crossOrigin)&&(this.crossOrigin="anonymous"),this.hasUpdated&&["src","type","fallbackSrc"].some(s=>t.has(s)&&t.get(s)!==this[s])&&this.resetSource()}updated(t){if(super.updated(t),this.syncMuted(t),this.focusMessageOnError&&this.phase==="error"&&(this.focusMessageOnError=!1,this.shadowRoot?.querySelector('[part="message"]')?.focus()),!(!this.offscreenAdmitted||!this.isConnected)){if(this.autoplay&&!this.autoplayAttempted&&!this.playIntent&&(this.src||this.fallbackSrc)&&(this.autoplayAttempted=!0,!x())){this.requestPlayback(!0);return}if(this.preload!=="none"&&this.phase!=="error"&&!this.attached&&!this.attaching&&this.src){const e=this.video;e&&this.ensureSource(e,!0)}}}syncMuted(t){const e=this.video;if(!e)return;const s=e!==this.mutedVideo;this.mutedVideo=e,!(!s&&!t.has("muted")&&!t.has("autoplay"))&&(this.muted||this.autoplay?e.muted=!0:e.paused&&(e.muted=!1))}async requestPlayback(t){if(this.phase==="loading"&&this.playIntent)return;const e=this.generation;this.playIntent=!0,this.intentAutoplay=t,(!this.started||this.phase==="error")&&(this.phase="loading"),await this.updateComplete;const s=this.video;!s||e!==this.generation||!await this.ensureSource(s,!1)||e!==this.generation||(t&&(s.muted=!0),await this.startPlayback(s,e))}async startPlayback(t,e){if(e!==this.generation)return;const s=++this.playAttempt;this.autoplayPending=this.intentAutoplay;try{await t.play()}catch(i){if(e!==this.generation||s!==this.playAttempt)return;this.autoplayPending=!1,i?.name==="NotAllowedError"&&this.phase!=="error"&&(this.playIntent=!1,this.phase=this.started?"playing":"idle")}}ensureSource(t,e){if(this.attached)return Promise.resolve(!0);if(this.attaching&&(e||!this.attachingEarly))return this.attaching;const s=this.generation,i=this.attaching,r=i?i.then(c=>c||s!==this.generation?c:this.attachSource(t,e,s)):this.attachSource(t,e,s);return this.attaching=r,this.attachingEarly=e,r.finally(()=>{this.attaching===r&&(this.attaching=null)}),r}async attachSource(t,e,s){if(!this.src)return e?!1:this.fallbackSrc?(this.useSource(t,this.fallbackSrc,"fallback"),!0):(this.fail(null,"unsupported","No video source is set."),!1);if(this.canPlayNatively(t))return this.useSource(t,this.src,"native"),!0;if(e)return!1;const i=this.resolvedAdapter();if(i){this.mirrorTracks(t);let r;const c=t.error;this.adapterAttaching=!0,this.adapterAttachErrored=!1;try{r=await i(t,this.src)}catch(d){return s!==this.generation?!1:this.failOver(t,"adapter",R(d))}finally{s===this.generation&&(this.adapterAttaching=!1)}return s!==this.generation?(typeof r=="function"&&this.runTeardown(r),!1):(this.teardown=typeof r=="function"?r:null,this.attached={mode:"adapter"},this.readyEmitted=!1,this.adapterAttachErrored||t.error&&t.error!==c?this.failOver(t,"media",E(t)):(t.readyState>=1&&this.emitReady(t),!0))}return this.fallbackSrc?(this.useSource(t,this.fallbackSrc,"fallback"),!0):(this.fail(null,"unsupported",`This browser cannot play ${this.type} and no adapter is set.`),!1)}useSource(t,e,s){this.mirrorTracks(t),this.attached={mode:s},this.readyEmitted=!1,t.src=e}failOver(t,e,s){const i=this.attached?.mode??(e==="adapter"?"adapter":null),r=!!this.fallbackSrc&&!this.triedFallback&&i!=="fallback",c=this.generation;return this.emitError(i,e,s,r),c!==this.generation?!1:(this.runTeardown(),this.attached=null,this.pendingPlay=null,r?(this.triedFallback=!0,this.useSource(t,this.fallbackSrc,"fallback"),!0):(this.enterError(),!1))}emitError(t,e,s,i){this.dispatchEvent(new CustomEvent(y.VIDEO_ERROR,{detail:{src:this.src,mode:t,reason:e,message:s,fallback:i},bubbles:!0,composed:!0}))}fail(t,e,s){const i=this.generation;this.emitError(t,e,s,!1),i===this.generation&&this.enterError()}enterError(){const t=this.shadowRoot?.activeElement;this.focusMessageOnError=!!t?.classList.contains("play")||t!==null&&t===this.video,this.phase="error"}runTeardown(t=this.teardown){t===this.teardown&&(this.teardown=null);try{t?.()}catch{}}resetSource(){this.generation+=1,this.runTeardown();const t=this.attached!==null;this.attached=null,this.attaching&&(this.videoKey+=1,this.requestUpdate()),this.attaching=null,this.adapterAttaching=!1,this.adapterAttachErrored=!1,this.triedFallback=!1,this.readyEmitted=!1,this.playIntent=!1,this.autoplayAttempted=!1,this.intentAutoplay=!1,this.autoplayPending=!1,this.pendingPlay=null,this.focusMessageOnError=!1,this.started=!1,this.phase="idle";const e=this.video;e&&(t||e.hasAttribute("src"))&&(e.pause(),e.removeAttribute("src"),e.load())}mirrorTracks(t){for(const e of t.querySelectorAll("track"))e.remove();for(const e of this.children)e.localName==="track"&&t.append(e.cloneNode(!0))}isCurrent(t){return t.currentTarget===this.video}emitReady(t){!this.attached||this.readyEmitted||(this.readyEmitted=!0,this.dispatchEvent(new CustomEvent(y.VIDEO_READY,{detail:{src:this.src,mode:this.attached.mode,duration:t.duration},bubbles:!0,composed:!0})))}renderPosterContent(){if(this.phase==="error")return h`<div part="message" class="message" role="alert" tabindex="-1">
+        <slot name="error">This video can’t be played right now.</slot>
+      </div>`;const t=this.phase==="loading";return h`<button
+      part="play"
+      class="play"
+      type="button"
+      aria-label=${this.playLabel()}
+      aria-disabled=${t?"true":p}
+      @click=${this.handlePlayClick}
+    >
+      <span part="play-icon" class="play-icon" aria-hidden="true">
+        ${t?h`<span class="spinner"></span>`:h`<svg viewBox="0 0 24 24" focusable="false">
+              <path
+                d="M8 5.5v13a1 1 0 0 0 1.52.85l10.4-6.5a1 1 0 0 0 0-1.7L9.52 4.65A1 1 0 0 0 8 5.5Z"
+              />
+            </svg>`}
+      </span>
+    </button>`}render(){const t=!this.started||this.phase==="error",e=!this.deferOffscreen||this.offscreenAdmitted;return h`
+      <div part="frame" class="frame" data-phase=${this.phase}>
+        ${O(this.videoKey,h`<video
+            part="video"
+            class="video"
+            preload=${this.preload}
+            crossorigin=${this.crossOrigin||p}
+            tabindex=${this.controls==="none"||this.phase==="error"?"-1":p}
+            aria-label=${this.label||this.posterAlt||p}
+            ?controls=${this.controls==="native"&&this.started&&this.phase!=="error"}
+            ?loop=${this.loop}
+            ?playsinline=${this.playsinline}
+            @loadedmetadata=${this.handleLoadedMetadata}
+            @play=${this.handlePlay}
+            @playing=${this.handlePlaying}
+            @error=${this.handleVideoError}
+          ></video>`)}
+        <div part="poster" class="poster" ?data-dismissed=${!t}>
+          ${this.poster&&e?h`<img
+                part="poster-image"
+                class="poster-image"
+                loading=${this.deferOffscreen?"lazy":"eager"}
+                decoding="async"
+                alt=""
+                src=${this.poster}
+              />`:p}
+          ${this.renderPosterContent()}
+        </div>
+        <span class="sr-only" role="status"
+          >${this.phase==="loading"?"Loading video":""}</span
+        >
+        <slot class="tracks" @slotchange=${this.handleTrackSlotChange}></slot>
+      </div>
+    `}};a.defaultAdapter=null,a.styles=[...m.styles,w,A`
+      :host {
+        display: block;
+        position: relative;
+        box-sizing: border-box;
+        aspect-ratio: var(--_esp-video-aspect-ratio, 16 / 9);
+        overflow: hidden;
+        border-radius: var(--esp-video-border-radius, var(--esp-size-border-radius));
+        background: var(
+          --esp-video-surface,
+          oklch(from var(--esp-color-text, oklch(0.2 0 0)) 0.16 min(c, 0.02) h)
+        );
+      }
+
+      .frame,
+      .video {
+        display: block;
+        inline-size: 100%;
+        block-size: 100%;
+      }
+
+      .frame {
+        position: relative;
+      }
+
+      .video {
+        object-fit: var(--esp-video-object-fit, contain);
+        accent-color: var(--esp-video-accent, var(--esp-color-primary));
+      }
+
+      .video:focus {
+        outline: none;
+      }
+
+      .video:focus-visible {
+        outline: var(--esp-video-focus-outline, 3px solid var(--esp-color-link));
+        outline-offset: -3px;
+      }
+
+      .poster {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        transition:
+          opacity 200ms ease,
+          visibility 0s linear 0s;
+      }
+
+      .poster[data-dismissed] {
+        opacity: 0;
+        visibility: hidden;
+        pointer-events: none;
+        transition:
+          opacity 200ms ease,
+          visibility 0s linear 200ms;
+      }
+
+      .poster-image {
+        position: absolute;
+        inset: 0;
+        display: block;
+        inline-size: 100%;
+        block-size: 100%;
+        object-fit: cover;
+      }
+
+      .frame[data-phase="error"] .poster-image {
+        opacity: 0.45;
+      }
+
+      .play {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        margin: 0;
+        padding: 0;
+        border: 0;
+        background: transparent;
+        color: inherit;
+        font: inherit;
+        cursor: pointer;
+        -webkit-tap-highlight-color: transparent;
+      }
+
+      .play[aria-disabled="true"] {
+        cursor: progress;
+      }
+
+      .play:focus {
+        outline: none;
+      }
+
+      .play-icon {
+        display: grid;
+        place-items: center;
+        inline-size: var(--esp-video-play-size, var(--esp-size-huge, 4rem));
+        aspect-ratio: 1;
+        border-radius: 50%;
+        background: var(
+          --esp-video-play-background,
+          color-mix(in oklch, var(--esp-color-background, oklch(0.98 0 0)) 90%, transparent)
+        );
+        color: var(--esp-video-play-color, var(--esp-color-text, oklch(0.2 0 0)));
+        
+        box-shadow:
+          0 0 0 1px
+            color-mix(
+              in oklch,
+              var(--esp-video-play-color, var(--esp-color-text, oklch(0.2 0 0))) 28%,
+              transparent
+            ),
+          0 2px 12px oklch(0 0 0 / 0.28);
+        transition: transform 150ms ease;
+      }
+
+      .play:hover .play-icon {
+        transform: scale(1.06);
+      }
+
+      .play:focus-visible .play-icon {
+        outline: var(--esp-video-focus-outline, 3px solid var(--esp-color-link));
+        outline-offset: 3px;
+      }
+
+      .play-icon svg {
+        inline-size: 45%;
+        block-size: 45%;
+        
+        translate: 6% 0;
+        fill: currentColor;
+      }
+
+      .spinner {
+        inline-size: 40%;
+        aspect-ratio: 1;
+        border-radius: 50%;
+        border: 3px solid currentColor;
+        border-block-start-color: transparent;
+        animation: esp-video-spin 900ms linear infinite;
+      }
+
+      @keyframes esp-video-spin {
+        to {
+          rotate: 1turn;
+        }
+      }
+
+      .message {
+        position: relative;
+        max-inline-size: min(28rem, calc(100% - 2 * var(--esp-size-padding, 1rem)));
+        padding: var(--esp-size-small, 0.5rem) var(--esp-size-padding, 1rem);
+        border-radius: var(--esp-size-border-radius);
+        background: var(--esp-video-message-background, var(--esp-color-background));
+        color: var(--esp-video-message-color, var(--esp-color-text));
+        font-size: var(--esp-type-small, 0.875rem);
+        text-align: center;
+      }
+
+      .message:focus {
+        outline: none;
+      }
+
+      .message:focus-visible {
+        outline: var(--esp-video-focus-outline, 3px solid var(--esp-color-link));
+        outline-offset: 2px;
+      }
+
+      .tracks {
+        display: none;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .poster,
+        .poster[data-dismissed],
+        .play-icon {
+          transition: none;
+        }
+        .play:hover .play-icon {
+          transform: none;
+        }
+        .spinner {
+          animation: none;
+          border-block-start-color: currentColor;
+          opacity: 0.6;
+        }
+      }
+
+      @media (forced-colors: active) {
+        .play-icon {
+          border: 2px solid ButtonText;
+          background: ButtonFace;
+          color: ButtonText;
+        }
+        .play:focus-visible .play-icon {
+          outline-color: Highlight;
+        }
+        .message {
+          border: 1px solid CanvasText;
+        }
+      }
+    `],o([l({type:String})],a.prototype,"src",void 0),o([l({type:String})],a.prototype,"type",void 0),o([l({type:String})],a.prototype,"poster",void 0),o([l({attribute:"poster-alt",type:String})],a.prototype,"posterAlt",void 0),o([l({type:String})],a.prototype,"label",void 0),o([l({attribute:"aspect-ratio",type:String})],a.prototype,"aspectRatio",void 0),o([l({converter:v(b,"none"),reflect:!0})],a.prototype,"preload",void 0),o([l({type:Boolean})],a.prototype,"autoplay",void 0),o([l({type:Boolean})],a.prototype,"muted",void 0),o([l({type:Boolean})],a.prototype,"loop",void 0),o([l({type:Boolean})],a.prototype,"playsinline",void 0),o([l({converter:v(k,"native"),reflect:!0})],a.prototype,"controls",void 0),o([l({attribute:"defer-offscreen",type:Boolean})],a.prototype,"deferOffscreen",void 0),o([l({attribute:"fallback-src",type:String})],a.prototype,"fallbackSrc",void 0),o([l({attribute:"crossorigin",converter:$})],a.prototype,"crossOrigin",void 0),o([l({attribute:!1})],a.prototype,"adapter",void 0),o([f()],a.prototype,"phase",void 0),o([f()],a.prototype,"started",void 0),o([f()],a.prototype,"offscreenAdmitted",void 0),a=u=o([S("esp-video")],a);export{C as DEFAULT_VIDEO_ASPECT_RATIO,a as EspalierVideo,g as HLS_MEDIA_TYPE};