polite-media 0.4.3 → 0.5.0

package/src/video.css

@@ -6,13 +6,13 @@
  * is why it works at any video size, and it would be undone by a single width
  * declaration here.
  *
- * `data-polite-media` goes on the container in your markup, not from script.
- * It has to be authored: a <video preload="none"> paints an empty box, and if
- * the base "hidden" state only arrived once JS ran, a page whose bundle failed
- * would show that empty box stacked over the poster. Authored, the safe state is
- * the default and the library only ever has to reveal.
+ * `data-polite-media` goes on the box in your markup, not from script. It has
+ * to be authored: a <video preload="none"> paints an empty box, and if the base
+ * "hidden" state only arrived once JS ran, a page whose bundle failed would
+ * show that empty box stacked over the poster. Authored, the safe state is the
+ * default and the library only ever has to reveal.
  *
- * Expected shape -- poster first, video second, sharing one box:
+ * Expected shape -- poster a direct child, video anywhere inside, one box:
  *
  *   <div class="whatever-you-like" data-polite-media>
  *     <img src="poster.avif" alt="">
@@ -21,9 +21,15 @@
  *     </video>
  *   </div>
  *
- * Attributes the library sets on that container:
- *   data-polite-ready   a frame has actually painted
- *   data-polite-failed  no source could be decoded; the poster is now permanent
+ * The video rules use a descendant combinator so a wrapper between box and
+ * video is fine; the poster rule stays a direct child so a logo deeper in the
+ * box is left alone. One box holds one video, and boxes must not nest: the
+ * ready state reveals every video inside the box.
+ *
+ * Attributes the library sets on that box:
+ *   data-polite-ready    a frame has actually painted
+ *   data-polite-failed   no source could be decoded; the poster is now permanent
+ *   data-polite-blocked  play() refused until a gesture; the library is retrying
  * And on <html>:
  *   data-polite-paused  the user stopped playback via a [data-polite-pause-control] control
  *
@@ -38,12 +44,12 @@
  * of an async decode landing. Set the property to override both at once.
  */
 
-[data-polite-media] > video {
+[data-polite-media] video {
   opacity: 0;
   transition: opacity var(--polite-fade, 0s) ease;
 }
 
-[data-polite-media][data-polite-ready] > video {
+[data-polite-media][data-polite-ready] video {
   opacity: 1;
 }
 
@@ -62,12 +68,12 @@
  * half-decoded frame stuck at opacity 1 is exactly the state a viewer would
  * report as broken.
  */
-[data-polite-media][data-polite-failed] > video {
+[data-polite-media][data-polite-failed] video {
   opacity: 0;
 }
 
 @media (prefers-reduced-motion: reduce) {
-  [data-polite-media] > video,
+  [data-polite-media] video,
   [data-polite-media] > :is(img, picture) {
     transition: none;
   }

package/src/video.ts

@@ -24,6 +24,7 @@ export type { AtOnce, ConfigureOptions, RegisterOptions, VideoTarget } from './c
 // ElementEventMap and DocumentEventMap augmentation only reaches a consumer if
 // this module is part of their program.
 export {
+  POLITE_VIDEO_BLOCKED,
   POLITE_VIDEO_PAUSECHANGE,
   POLITE_VIDEO_FAILED,
   POLITE_VIDEO_READY,