polite-media 0.4.2 → 0.5.0

package/src/image.ts

@@ -24,22 +24,16 @@ export type ImageTarget = Target<HTMLImageElement>;
 
 export interface RevealImagesOptions {
   /**
-   * Manage images that are not `loading="lazy"`.
-   *
-   * Off by default because LCP excludes elements at `opacity: 0`, and revealing
-   * one does not restore its candidacy -- so fading an eager, above-the-fold
-   * image can forfeit the metric it was meant to improve. A lazy image was never
-   * an LCP candidate, so the default is risk-free.
-   *
-   * Turning this on is legitimate and sometimes right: an eager grid that would
-   * otherwise cut from its backdrop to the photo on whatever frame the async
-   * decode lands looks worse without a fade. It just has to be a decision rather
-   * than an accident.
+   * @deprecated Ignored since 0.5, and warns. image.css no longer hides an eager
+   * image at all, so the opt-in has to be in the markup where the stylesheet can
+   * see it: `data-polite-reveal="eager"` on the image.
    */
   allowEager?: boolean;
 }
 
 const READY = 'data-polite-ready';
+/** Written while this module owns an image's reveal, so image.css can stand down. */
+const MANAGED = 'data-polite-managed';
 
 function markReady(image: HTMLImageElement): void {
   image.setAttribute(READY, '');
@@ -52,11 +46,12 @@ function markReady(image: HTMLImageElement): void {
 }
 
 /**
- * Every image this module has taken responsibility for.
- *
- * A WeakSet rather than an attribute: the stylesheet no longer needs to know
- * which images are managed, so writing it into the DOM would be state kept for
- * nobody. Weak so a released image is not pinned by the bookkeeping.
+ * Every image a `revealImages()` call has ever claimed, for the stray-image
+ * warning. Distinct from `data-polite-managed`, which marks an image only while
+ * this module still owns its reveal so the stylesheet's failsafe stands down: a
+ * teardown removes the attribute but the claim stays, since the warning is about
+ * selectors that never reached an image at all. Weak so a released image is not
+ * pinned by the bookkeeping.
  */
 const managed = new WeakSet<HTMLImageElement>();
 
@@ -90,6 +85,7 @@ function scheduleUnmanagedCheck(): void {
 }
 
 let warnedNoStylesheet = false;
+let warnedAllowEager = false;
 
 /**
  * image.css is the only thing that hides a marked image. Without it `data-polite-reveal` is inert:
@@ -114,6 +110,8 @@ function warnIfUnstyled(): void {
   // removed in this same task so nothing paints it and no scan above ever sees it.
   const probe = document.createElement('img');
   probe.setAttribute('data-polite-reveal', '');
+  // The stylesheet hides only lazy images, so an eager probe would read as unstyled everywhere.
+  probe.setAttribute('loading', 'lazy');
   document.body.appendChild(probe);
   const opacity = getComputedStyle(probe).opacity;
   probe.remove();
@@ -131,33 +129,52 @@ function warnIfUnstyled(): void {
 }
 
 /**
- * Reveals each matching image once it has decoded.
+ * Reveals each matching image once it has decoded. With no target it takes every
+ * marked image on the page.
  *
  * Returns a function that stops any reveals still pending, for a client-side
  * router tearing the page down before the images resolved.
  */
-export function revealImages(target: ImageTarget, options: RevealImagesOptions = {}): () => void {
+export function revealImages(
+  target: ImageTarget = 'img[data-polite-reveal]',
+  options: RevealImagesOptions = {}
+): () => void {
   const controller = new AbortController();
   const { signal } = controller;
 
+  if (options.allowEager && !warnedAllowEager) {
+    warnedAllowEager = true;
+    console.warn(
+      'polite-media: allowEager is ignored. To fade an eager image, put ' +
+        'data-polite-reveal="eager" on it, where the stylesheet can see the choice.'
+    );
+  }
+
   scheduleUnmanagedCheck();
 
+  const claimed: HTMLImageElement[] = [];
+
   for (const image of resolveTargets(target)) {
     managed.add(image);
-    // Eager images are revealed at once rather than skipped.
-    //
-    // Skipping looks like the cautious choice and is the opposite: image.css
-    // has already hidden anything carrying data-polite-reveal, so declining to
-    // manage it leaves it invisible permanently instead of merely unfaded.
-    // Revealing immediately keeps the LCP candidate visible from its first
-    // paint, which is the whole reason eager images are treated differently.
+    // Tells the stylesheet to leave this one alone. The failsafe there is for images nothing
+    // reveals, and firing it on one this module owns is worse than not firing it at all: opacity
+    // reaches 1 while the picture is still in flight, so when it arrives there is no fade left to
+    // run. Measured on a real page, eleven below-the-fold images were revealed that way five
+    // seconds in, none of them loaded.
+    image.setAttribute(MANAGED, '');
+    claimed.push(image);
+    // An eager image is never hidden by image.css, because LCP excludes elements at
+    // opacity 0 and a deferred module cannot reveal one before first paint. So it
+    // is marked ready at once, unless the markup opted it into the fade with the
+    // same value the stylesheet keys on.
     //
     // Tested against 'lazy' rather than for 'eager' deliberately. Engines
     // disagree on what an absent or invalid attribute reports: MDN documents
     // only 'eager' and 'lazy', while happy-dom returns 'auto'. Only "lazy" has
     // one agreed spelling, so asking whether it is lazy is answerable
     // everywhere, and everything else correctly falls into the eager branch.
-    if (!options.allowEager && image.loading !== 'lazy') {
+    const optedIn = image.getAttribute('data-polite-reveal') === 'eager';
+    if (!optedIn && image.loading !== 'lazy') {
       markReady(image);
       continue;
     }
@@ -193,7 +210,15 @@ export function revealImages(target: ImageTarget, options: RevealImagesOptions =
       });
   }
 
-  return () => controller.abort();
+  // Hands anything still unrevealed back to the stylesheet. A router tearing the page down before
+  // the images resolved would otherwise leave them owned by a module that has stopped listening,
+  // and with the failsafe suppressed that is hidden forever rather than merely unfaded.
+  return () => {
+    controller.abort();
+    for (const image of claimed) {
+      if (!image.hasAttribute(READY)) image.removeAttribute(MANAGED);
+    }
+  };
 }
 
 // Re-exported so `polite-media/image` carries the ElementEventMap and

package/src/layer.css

@@ -50,8 +50,9 @@
  * object-fit needs the image for its own reason: it "Applies to: replaced
  * elements", and a `<picture>` is a container rather than one.
  */
-[data-polite-media] > :is(img, video),
-[data-polite-media] > picture > img {
+[data-polite-media] > img,
+[data-polite-media] > picture > img,
+[data-polite-media] video {
   position: absolute;
   inset: 0;
   width: 100%;

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,