@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/video-player-frame.js

@@ -0,0 +1,51 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { useCallback } from "react";
+/** What the frame is called when the author gave the video no title. */ const FALLBACK_TITLE = 'Video player';
+/** The shape assumed for a film nobody measured. */ const DEFAULT_ASPECT_RATIO = '16 / 9';
+export function VideoPlayerFrame(props) {
+    const { src, title, aspectRatio, height, radius, focusOnMount, style } = props;
+    const takeFocus = useCallback((node)=>{
+        node == null ? void 0 : node.focus();
+    }, []);
+    return /*#__PURE__*/ _jsx("iframe", {
+        ref: focusOnMount ? takeFocus : undefined,
+        src: src,
+        title: title || FALLBACK_TITLE,
+        // `autoplay` is delegated because the press happened in this document
+        // and the film plays in another one: without the grant a browser may
+        // refuse to start the film the visitor just asked for.
+        allow: "autoplay; fullscreen; picture-in-picture",
+        allowFullScreen: true,
+        // The Video embed block's sandbox: the player runs its own scripts on
+        // its own origin and may open a link in a new tab, and it may not
+        // navigate this page or submit a form from it.
+        sandbox: "allow-scripts allow-same-origin allow-presentation allow-popups",
+        style: _extends({
+            display: 'block',
+            width: '100%',
+            height: height || undefined,
+            aspectRatio: height ? undefined : aspectRatio || DEFAULT_ASPECT_RATIO,
+            border: 0,
+            borderRadius: radius != null ? `${radius}px` : undefined
+        }, style)
+    });
+}
+VideoPlayerFrame.displayName = 'VideoPlayerFrame';
+
+//# sourceMappingURL=video-player-frame.js.map

package/src/lib/components/video-player-frame.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/components/video-player-frame.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { type CSSProperties, useCallback } from 'react'\n\n/**\n * The frame a hosted player plays in (AGL-2826).\n *\n * Shared by the Video element, which puts it where the poster was, and by the\n * lightbox, which opens it in a dialog, so the two cannot disagree about what\n * the frame may do. Nothing renders this before a press, except the player an\n * element loads with the page (AGL-2962), and that only for a visitor whose\n * analytics consent is on record. Otherwise the element's poster is a button\n * until the press, which is what keeps the player's origin off the wire for a\n * visitor who only looks at the page.\n */\nexport interface VideoPlayerFrameProps {\n  /** The player's address, rebuilt by the caller from a parsed media id. */\n  src: string\n  /** Names the frame for assistive technology. */\n  title?: string\n  /** `width / height`; 16:9 when nothing measured the film. */\n  aspectRatio?: string\n  /** A CSS height the author pinned, which replaces the ratio. */\n  height?: string\n  /** Corner radius in px, matching the poster it replaced. */\n  radius?: number\n  /**\n   * Move focus into the player as it mounts. For the in-place player only,\n   * where the button that was pressed has just left the page and focus would\n   * otherwise fall back to the body.\n   *\n   * ⛔ Never inside the lightbox. A cross-origin frame keeps every key pressed\n   * while it has focus, so `Escape` never reaches the dialog. Measured on\n   * 2026-09-10: with focus moved into the Wistia frame, `Escape` left the\n   * dialog open and the film playing. Left on the dialog, `Escape` closes it,\n   * and `Tab` still reaches the player.\n   */\n  focusOnMount?: boolean\n  /** Layout the placement adds, such as the lightbox's flex, applied last. */\n  style?: CSSProperties\n}\n\n/** What the frame is called when the author gave the video no title. */\nconst FALLBACK_TITLE = 'Video player'\n\n/** The shape assumed for a film nobody measured. */\nconst DEFAULT_ASPECT_RATIO = '16 / 9'\n\nexport function VideoPlayerFrame(props: VideoPlayerFrameProps) {\n  const { src, title, aspectRatio, height, radius, focusOnMount, style } = props\n  const takeFocus = useCallback((node: HTMLIFrameElement | null) => {\n    node?.focus()\n  }, [])\n  return (\n    <iframe\n      ref={focusOnMount ? takeFocus : undefined}\n      src={src}\n      title={title || FALLBACK_TITLE}\n      // `autoplay` is delegated because the press happened in this document\n      // and the film plays in another one: without the grant a browser may\n      // refuse to start the film the visitor just asked for.\n      allow=\"autoplay; fullscreen; picture-in-picture\"\n      allowFullScreen\n      // The Video embed block's sandbox: the player runs its own scripts on\n      // its own origin and may open a link in a new tab, and it may not\n      // navigate this page or submit a form from it.\n      sandbox=\"allow-scripts allow-same-origin allow-presentation allow-popups\"\n      style={{\n        display: 'block',\n        width: '100%',\n        height: height || undefined,\n        aspectRatio: height ? undefined : aspectRatio || DEFAULT_ASPECT_RATIO,\n        border: 0,\n        borderRadius: radius != null ? `${radius}px` : undefined,\n        ...style,\n      }}\n    />\n  )\n}\nVideoPlayerFrame.displayName = 'VideoPlayerFrame'\n"],"names":["useCallback","FALLBACK_TITLE","DEFAULT_ASPECT_RATIO","VideoPlayerFrame","props","src","title","aspectRatio","height","radius","focusOnMount","style","takeFocus","node","focus","iframe","ref","undefined","allow","allowFullScreen","sandbox","display","width","border","borderRadius","displayName"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAA6BA,WAAW,QAAQ,QAAO;AAwCvD,sEAAsE,GACtE,MAAMC,iBAAiB;AAEvB,kDAAkD,GAClD,MAAMC,uBAAuB;AAE7B,OAAO,SAASC,iBAAiBC,KAA4B;IAC3D,MAAM,EAAEC,GAAG,EAAEC,KAAK,EAAEC,WAAW,EAAEC,MAAM,EAAEC,MAAM,EAAEC,YAAY,EAAEC,KAAK,EAAE,GAAGP;IACzE,MAAMQ,YAAYZ,YAAY,CAACa;QAC7BA,wBAAAA,KAAMC,KAAK;IACb,GAAG,EAAE;IACL,qBACE,KAACC;QACCC,KAAKN,eAAeE,YAAYK;QAChCZ,KAAKA;QACLC,OAAOA,SAASL;QAChB,sEAAsE;QACtE,qEAAqE;QACrE,uDAAuD;QACvDiB,OAAM;QACNC,eAAe;QACf,sEAAsE;QACtE,kEAAkE;QAClE,+CAA+C;QAC/CC,SAAQ;QACRT,OAAO;YACLU,SAAS;YACTC,OAAO;YACPd,QAAQA,UAAUS;YAClBV,aAAaC,SAASS,YAAYV,eAAeL;YACjDqB,QAAQ;YACRC,cAAcf,UAAU,OAAO,GAAGA,OAAO,EAAE,CAAC,GAAGQ;WAC5CN;;AAIX;AACAR,iBAAiBsB,WAAW,GAAG"}

package/src/lib/components/video.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as Aglyn from '@aglyn/aglyn';
+import type { SxProps } from '@mui/material/styles';
+import { type ReactNode } from 'react';
+export declare const ID: Aglyn.ComponentId;
+/** How much of a video the browser may fetch before anyone asks for it. */
+export type VideoPreload = 'none' | 'metadata' | 'auto';
+/**
+ * What `preload` an unset field resolves to, given the rest of the node.
+ *
+ * Exported for the spec, because the whole point of this element is what it
+ * does NOT download and a rule that is only asserted through rendered markup
+ * is a rule three refactors from being an accident.
+ *
+ * * **Autoplay wins first.** A video that starts on its own needs its bytes
+ *   by definition; `none` there is a hint every browser overrides anyway, and
+ *   stating it would only mislead the next reader.
+ * * **A poster buys `none`.** This is the saving the element exists for — the
+ *   poster carries the first paint at image cost, and not one byte of video
+ *   is fetched until a visitor presses play.
+ * * **No poster keeps `metadata`.** With neither a poster nor metadata a
+ *   `<video>` paints a black rectangle, so deferring an unpostered video
+ *   trades a real transfer for a real regression. `metadata` is also what
+ *   every document authored before this rendered, which is what makes the
+ *   change safe for sites already published.
+ */
+export declare function resolveVideoPreload(options: {
+    preload?: unknown;
+    poster?: unknown;
+    autoPlay?: unknown;
+}): VideoPreload;
+export interface VideoProps {
+    /**
+     * Where the video comes from. Either a **media reference** —
+     * `media:{scope}/{mediaId}`, what "Browse media" stores (AGL-1215) — or any
+     * URL. `resolveMediaSrc` decides, exactly as it does for an image.
+     *
+     * A Wistia link is read differently (AGL-2826): the element keeps only the
+     * media id and plays Wistia's own player, which loads when a visitor
+     * presses play and never before, unless {@link loadPlayer} loads it with the
+     * page. See `wistia-embed.ts`.
+     */
+    src?: string;
+    /**
+     * The still shown before playback, and the element's entire first paint
+     * once `preload` is `none`. A media reference or a URL, like `src`.
+     *
+     * Optional even for a poster-first placement: when the DAM captured a frame
+     * at upload, {@link posterFromSource} says so and the element derives the
+     * poster from the video's own reference.
+     */
+    poster?: string;
+    /**
+     * The chosen asset has a poster the DAM generated (AGL-2749), served at
+     * `?poster=1` on the video's own reference.
+     *
+     * Written by the pick, never by an author, and it is a flag rather than a
+     * url on purpose: the url can be derived from `src` by anybody, but only
+     * the media document knows whether it resolves to anything. A video
+     * uploaded before AGL-2742 answers 404, and this is what keeps that 404 out
+     * of an `<img>` and out of the page's `thumbnailUrl`.
+     */
+    posterFromSource?: boolean;
+    /**
+     * The video's title (AGL-2741). Serves three jobs at once and is deliberate
+     * about it: the `<video>`'s tooltip, the accessible name a screen reader
+     * announces for the player, and `VideoObject.name` in the page's structured
+     * data. One sentence an author writes once.
+     */
+    title?: string;
+    /**
+     * What the video is about — `VideoObject.description`, which Google
+     * recommends for a video rich result but does not require, so a blank one
+     * drops only this field from the structured data. Never rendered as
+     * visible text; the element is a player, not a caption.
+     */
+    description?: string;
+    /**
+     * When the video was first published, as `YYYY-MM-DD`. Google requires it
+     * beside the title and the poster, and it is the one nothing else on the
+     * page can supply: a screen's own publish date is when the PAGE went up,
+     * which for a film embedded months later is simply a different fact.
+     *
+     * The day is what an author types; the page's `VideoObject` publishes it as
+     * that day at noon UTC, because Google reads `uploadDate` as a date-time
+     * with a zone (`uploadDateTime` in the VideoObject builder).
+     */
+    uploadDate?: string;
+    /**
+     * Running time in seconds. Copied off the media document when the DAM's
+     * video pipeline publishes one (`Aglyn.videoMediaProps`) and read from the
+     * asset again when the page is composed, so a replace reaches it
+     * (AGL-2807); typed by the author otherwise, and omitted from the schema
+     * when neither happened.
+     */
+    durationSeconds?: number;
+    /**
+     * Show the poster as a play button and open the film in a dialog
+     * (AGL-2744).
+     *
+     * Default OFF, so every document published before this keeps rendering the
+     * inline player it was authored against. Requires a poster — there is
+     * nothing to click without one — and falls back to inline playback when
+     * there is none, rather than rendering a button with no face.
+     *
+     * A Wistia poster waits for a press whether this is on or off; the switch
+     * decides only where its player opens, in the dialog or in place of the
+     * poster. A Wistia player that {@link loadPlayer} put in the page stays in
+     * the page either way.
+     */
+    lightbox?: boolean;
+    /**
+     * Load a Wistia video's player with the page (AGL-2962), in place of the
+     * poster and without autoplay, for a visitor whose stored consent grants
+     * analytics.
+     *
+     * For a page built to show this one film. A search engine lists a video
+     * only from a page whose main content it is, and it can only find a player
+     * that is in the page once the page has loaded; a poster that must be
+     * pressed first is the case Search Console reports as "Cannot determine
+     * video position and size".
+     *
+     * Default OFF, so every document published before this renders the poster
+     * it was authored against. No effect on any other source: a library film or
+     * a video URL already renders its `<video>` into the page's HTML. The
+     * page-load state below says who gets the player and when.
+     */
+    loadPlayer?: boolean;
+    /** Captions file — a WebVTT (`.vtt`) URL or media reference. */
+    captionsSrc?: string;
+    /** What the captions track is called in the player's menu. */
+    captionsLabel?: string;
+    /** BCP-47 language tag for the captions, e.g. `en`. */
+    captionsLang?: string;
+    autoPlay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    /**
+     * Play inline on a phone rather than taking over the screen. Defaults ON,
+     * which is what this element has always rendered — it is a control now
+     * because a full-screen takeover is a legitimate choice for a film and
+     * there was no way to ask for it.
+     */
+    playsInline?: boolean;
+    /** See {@link resolveVideoPreload}; unset is decided from the node. */
+    preload?: VideoPreload;
+    /** CSS width (e.g. "100%", "640px"); defaults to 100%. */
+    width?: string;
+    /** CSS height (e.g. "360px"); defaults to auto. */
+    height?: string;
+    /**
+     * The asset's own pixel dimensions, copied off the media document when the
+     * video was picked (AGL-2741) — the same pair, by the same route and for
+     * the same reason, as `image.tsx` — and read from the asset again when the
+     * page is composed, so a replace with a different shape resizes the player
+     * (AGL-2807).
+     *
+     * NOT author controls, which is why neither appears in the schema below.
+     * They describe the file; the CSS `width`/`height` above describe the
+     * placement. Here they become a CSS `aspect-ratio` rather than the HTML
+     * attribute pair an `<img>` gets, because a `<video>`'s `width`/`height`
+     * content attributes are used dimensions, not a ratio — writing them would
+     * pin the element to the file's pixel size instead of reserving its shape.
+     *
+     * The stake is higher than it is for an image. An `<img>` with no ratio is
+     * zero-height until its bytes decode; a `<video preload="none">` with no
+     * ratio is zero-height until somebody presses play, which on most pages is
+     * never.
+     */
+    intrinsicWidth?: number;
+    /** See `intrinsicWidth` — the two are only ever used as a pair. */
+    intrinsicHeight?: number;
+    /** Border radius in px. */
+    radius?: number;
+    /**
+     * Authored node styles, handed over by the renderer rather than typed
+     * into an attribute — recomposed below so the Styles panel's values are
+     * merged rather than replaced (AGL-1284).
+     */
+    sx?: SxProps;
+    /**
+     * Accepted and dropped. The element is `selfClosing`, so the besigner never
+     * gives it children; the `<track>` below is the renderer's own child and
+     * anything arriving through the tree would land beside it.
+     */
+    children?: ReactNode;
+}
+/**
+ * Video element (AGL-162, AGL-2741): plays a media-library upload, any URL or
+ * a Wistia video (AGL-2826), poster first.
+ *
+ * The default is now to download NOTHING until a visitor asks. A poster is an
+ * image — a few tens of kilobytes through the DAM's WebP variants, edge-cached
+ * — while the video behind it is not edge-cacheable at all and is measured in
+ * megabytes. `preload` decides which of those a page pays for on first paint,
+ * and {@link resolveVideoPreload} explains what an unset field resolves to.
+ *
+ * An empty src shows a labeled placeholder so the element stays selectable in
+ * the editor.
+ */
+declare const Video: import("react").ForwardRefExoticComponent<VideoProps & import("react").RefAttributes<HTMLElement>>;
+export declare const schema: Aglyn.ComponentSchema<VideoProps>;
+export declare const presets: Aglyn.PresetSchema[];
+export default Video;