npm - polite-media - Versions diffs - 0.3.0 - Mend

polite-media 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/src/targets.ts ADDED Viewed

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * How both halves name the elements they act on, so `revealImages('.card img')`
+ * and `registerAll('[data-polite-media] video')` mean the same thing rather than
+ * being two similar-looking ideas.
+ */
+/**
+ * Anything that names one or more elements: a selector, a single element, or any
+ * collection of them.
+ *
+ * `ArrayLike` is listed alongside `Iterable` deliberately. `NodeListOf` and
+ * `HTMLCollectionOf` are iterable at runtime, but their `[Symbol.iterator]` lives
+ * in `lib.dom.iterable`, so a consumer whose `lib` omits it cannot pass
+ * `document.querySelectorAll('img')` to an `Iterable`-only parameter even though
+ * it works. `ArrayLike` is structural and needs no `lib` support.
+ */
+export type Target<T extends Element> = string | T | ArrayLike<T> | Iterable<T>;
+/** Resolves a {@link Target} to the elements it names. */
+export function resolveTargets<T extends Element>(target: Target<T>): T[] {
+  if (typeof target === 'string') return [...document.querySelectorAll<T>(target)];
+  // A single element is the obvious thing to pass when you already hold one, and
+  // it used to be rejected: `revealImages(myImg)` did not compile.
+  if (target instanceof Element) return [target as T];
+  return Array.from(target as ArrayLike<T>);
+}

package/src/video.css ADDED Viewed

@@ -0,0 +1,74 @@
+/*
+ * polite-media/video.css -- optional stylesheet.
+ *
+ * Timing only. This file sets no size, position or aspect ratio, because the
+ * library owns *when* media appears and the host owns *where*. That separation
+ * 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.
+ *
+ * Expected shape -- poster first, video second, sharing one box:
+ *
+ *   <div class="whatever-you-like" data-polite-media>
+ *     <img src="poster.avif" alt="">
+ *     <video muted loop playsinline preload="none">
+ *       <source src="hero.mp4" type="video/mp4">
+ *     </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
+ * And on <html>:
+ *   data-polite-paused  the user stopped playback via a [data-polite-pause-control] control
+ *
+ * --polite-fade defaults to 0s here, meaning a cut. A frame-0 poster does not
+ * make a fade free: playback starts at the reveal, so the poster stays frozen
+ * while the video advances and the crossfade blends a still against a frame that
+ * has moved on, which reads as a double exposure. Cutting is safe because the
+ * reveal waits for a presented frame, so there is always something to cut to.
+ *
+ * image.css reads the same property but defaults to 350ms, because a lone image
+ * has no second moving picture to ghost against and its fade covers the flicker
+ * of an async decode landing. Set the property to override both at once.
+ */
+[data-polite-media] > video {
+  opacity: 0;
+  transition: opacity var(--polite-fade, 0s) ease;
+}
+[data-polite-media][data-polite-ready] > video {
+  opacity: 1;
+}
+/*
+ * The poster is hidden only after the crossfade finishes. Removing it up front
+ * would expose whatever sits behind mid-dissolve; `visibility` rather than
+ * `display` so nothing reflows, and the delay must track --polite-fade.
+ */
+[data-polite-media][data-polite-ready] > :is(img, picture) {
+  visibility: hidden;
+  transition: visibility 0s linear var(--polite-fade, 0s);
+}
+/*
+ * A failed video is never revealed, so this is belt and braces -- but a
+ * half-decoded frame stuck at opacity 1 is exactly the state a viewer would
+ * report as broken.
+ */
+[data-polite-media][data-polite-failed] > video {
+  opacity: 0;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-polite-media] > video,
+  [data-polite-media] > :is(img, picture) {
+    transition: none;
+  }
+}

package/src/video.ts ADDED Viewed

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * Everything for background video. Imported on its own so an image-only page
+ * never pays for the IntersectionObserver, source selection or arbitration.
+ *
+ * The export list is deliberately small. Every name here is permanent once
+ * published, and adding one later is not a breaking change while removing one
+ * is -- so anything without a caller that can be named stays internal. The
+ * environment gates and the reveal primitive are used by this package and are
+ * not part of its interface.
+ */
+export {
+  configure,
+  pauseAll,
+  register,
+  registerAll,
+  resumeAll,
+  unregister,
+  unregisterAll,
+} from './coordinator.js';
+export type { AtOnce, ConfigureOptions, RegisterOptions, VideoTarget } from './coordinator.js';
+// Loaded for its `declare global` block as much as for the constants: the
+// ElementEventMap and DocumentEventMap augmentation only reaches a consumer if
+// this module is part of their program.
+export {
+  POLITE_VIDEO_PAUSECHANGE,
+  POLITE_VIDEO_FAILED,
+  POLITE_VIDEO_READY,
+  type PolitePauseEventDetail,
+  type PoliteVideoEventDetail,
+} from './events.js';

package/src/warm.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there. Imported on
+ * its own, so a page that only warms never pays for the video coordinator.
+ *
+ * A barrel for the same reason `video.ts` is one: this file is what the `./warm`
+ * subpath resolves to, so every name it exports is public and permanent once
+ * published. `resetWarmed` clears the dedup record for a test and has no caller
+ * outside the suite, so it stays in `warming.ts` where tests reach it directly.
+ */
+export { warm, warmOnIntent } from './warming.js';
+export type { WarmOptions, WarmSource } from './warming.js';

package/src/warming.ts ADDED Viewed

@@ -0,0 +1,162 @@
+/**
+ * @module
+ * Warming a destination page's image before the visitor gets there, so the click
+ * lands on a picture that is already in the cache.
+ *
+ * Every document prefetcher fetches the HTML and stops: Astro's `data-astro-prefetch`,
+ * Next's `<Link>`, quicklink. The image inside that HTML is discovered only after
+ * the new document parses, which is exactly when it is too late to matter.
+ *
+ * The platform has the pieces but not in one place. `imagesrcset` and `imagesizes`
+ * do responsive selection, but MDN scopes them to `rel="preload"` with `as="image"`
+ * only, and scopes preload itself to resources "your page will need very soon". A
+ * speculative navigation wants `prefetch` semantics, where those attributes do not
+ * apply. So you can have the right selection or the right timing, not both, and
+ * anyone who wants both ends up re-implementing the browser's own rules in JS:
+ * parsing `sizes`, comparing `w` descriptors, guessing format support.
+ *
+ * This module does none of that. It builds the candidates as a detached
+ * `<picture>` and lets the browser choose, which is measurably the same algorithm
+ * the destination page will run (e2e/warm.spec.ts, all three engines). Nothing
+ * here parses a media query, so nothing here can disagree with one.
+ *
+ * A detached `<img>` also *fetches* what it selects, so no `<link>` is injected at
+ * all. That sidesteps the two documented failures of the link approach: Safari
+ * does not support `<link rel="prefetch">`, and Firefox aborts it with
+ * NS_BINDING_ABORTED when the response carries no explicit cache header.
+ *
+ * Not an image pipeline. It generates no URLs and knows no widths; it warms the
+ * candidates you already build.
+ */
+import { connectionAllowsMedia } from './env.js';
+/** One `<picture>` candidate: a format, and the variants available in it. */
+export interface WarmSource {
+  /** A MIME type such as `image/avif`. Omitted means "always a candidate". */
+  type?: string;
+  srcset: string;
+}
+export interface WarmOptions {
+  /** Ordered, first supported wins, exactly as `<source>` children behave. */
+  sources?: WarmSource[];
+  srcset?: string;
+  /** A single URL, for an image with no variants. */
+  src?: string;
+  /** Handed to the browser verbatim. Nothing in this package parses it. */
+  sizes?: string;
+}
+const warmed = new Set<string>();
+/**
+ * Images with a fetch still in flight.
+ *
+ * A detached element is reachable from nothing once this function returns, and a
+ * collected image would be an aborted fetch. Precautionary rather than a fix for
+ * something observed: no engine was seen dropping one. It is cheap, and the bug
+ * it forecloses would be silent and load dependent, which is the kind no test
+ * here would catch.
+ */
+const inFlight = new Set<HTMLImageElement>();
+/**
+ * Deduped on what the caller asked for rather than on the URL the browser picks,
+ * because the URL is not known until selection has already happened, and the
+ * repeat this exists to stop is the same link hovered twice.
+ */
+function keyOf(options: WarmOptions): string {
+  const sources = (options.sources ?? []).map((source) => `${source.type ?? ''}|${source.srcset}`);
+  // Joined on NUL rather than a newline: a srcset spanning several lines is
+  // ordinary formatting, and would otherwise let two different candidate sets
+  // build the same key and silently drop the second warm.
+  return [...sources, options.srcset ?? '', options.src ?? '', options.sizes ?? ''].join('\0');
+}
+/** Warms one image: selects the variant this browser would request, and fetches it. */
+export function warm(options: WarmOptions): void {
+  // Speculative bytes are the first thing to drop on a metered connection. Astro
+  // downgrades to its `tap` strategy here rather than skipping; for an image
+  // nobody has asked for yet, not spending them at all is the better trade.
+  if (!connectionAllowsMedia()) return;
+  const sources = options.sources ?? [];
+  // Checked before anything is built, so an empty call allocates nothing, and
+  // before `warmed` is touched, so it cannot make a later correct call a no-op.
+  if (sources.length === 0 && !options.srcset && !options.src) {
+    console.warn(
+      'polite-media: warm() was given no src, srcset or sources, so nothing was warmed.'
+    );
+    return;
+  }
+  const key = keyOf(options);
+  if (warmed.has(key)) return;
+  const picture = document.createElement('picture');
+  for (const source of sources) {
+    const element = document.createElement('source');
+    if (source.type) element.type = source.type;
+    element.srcset = source.srcset;
+    picture.append(element);
+  }
+  const img = document.createElement('img');
+  picture.append(img);
+  // The visitor has not asked for this image and may never ask. It must not
+  // compete with the page they are actually looking at.
+  img.fetchPriority = 'low';
+  if (options.sizes) img.sizes = options.sizes;
+  if (options.srcset) img.srcset = options.srcset;
+  if (options.src) img.src = options.src;
+  warmed.add(key);
+  inFlight.add(img);
+  const settled = (): void => void inFlight.delete(img);
+  img.addEventListener('load', settled, { once: true });
+  img.addEventListener('error', settled, { once: true });
+}
+/**
+ * The events that mean "about to navigate". `pointerover` and `focusin` cover
+ * Astro's documented `hover` strategy, "when you hover over or focus on the
+ * link"; `touchstart` covers the touch case, where a hover never happens.
+ */
+const INTENT_EVENTS = ['pointerover', 'focusin', 'touchstart'] as const;
+/**
+ * Warms whatever `resolve` names when the visitor shows intent toward `selector`.
+ *
+ * Delegated on the document, so links added later are covered without rebinding
+ * and one listener serves a whole grid. `resolve` returns the candidates rather
+ * than the library inventing a `data-*` vocabulary for them: where an app keeps
+ * its srcsets is the app's business.
+ *
+ * Returns a teardown. Listeners on `document` survive a `<ClientRouter />` swap,
+ * so a caller that re-binds per navigation stacks duplicates without one.
+ */
+export function warmOnIntent(
+  selector: string,
+  resolve: (element: Element) => WarmOptions | null | undefined
+): () => void {
+  const onIntent = (event: Event): void => {
+    const element = (event.target as Element | null)?.closest?.(selector);
+    if (!element) return;
+    const options = resolve(element);
+    if (options) warm(options);
+  };
+  for (const type of INTENT_EVENTS) {
+    document.addEventListener(type, onIntent, { passive: true });
+  }
+  return () => {
+    for (const type of INTENT_EVENTS) document.removeEventListener(type, onIntent);
+  };
+}
+/** Drops the dedup record so a test can warm the same thing twice. Not public API. */
+export function resetWarmed(): void {
+  warmed.clear();
+  inFlight.clear();
+}