@revenuecat/purchases-ui-js 4.1.0 → 4.2.0

package/dist/components/paywall/fixtures/sheet-video-stacking-paywall.d.ts

@@ -0,0 +1,6 @@
+import type { PaywallData } from "../../../types/paywall";
+/**
+ * Minimal variant of {@link SHEET_PAYWALL} with a sheet-level video background for
+ * Storybook z-order regression checks (`rc-sheet-video-bg`).
+ */
+export declare const SHEET_PAYWALL_VIDEO_STACKING: PaywallData;

package/dist/components/paywall/fixtures/sheet-video-stacking-paywall.js

@@ -0,0 +1,42 @@
+import { STORY_BACKGROUND_VIDEO_FILL } from "../../../stories/video-background-story-fixture";
+import { SHEET_PAYWALL } from "./sheet-paywall";
+/**
+ * Minimal variant of {@link SHEET_PAYWALL} with a sheet-level video background for
+ * Storybook z-order regression checks (`rc-sheet-video-bg`).
+ */
+export const SHEET_PAYWALL_VIDEO_STACKING = (() => {
+    const data = structuredClone(SHEET_PAYWALL);
+    data.id = "sheet_paywall_video_stacking";
+    data.components_localizations ??= {};
+    data.components_localizations.en_US ??= {};
+    Object.assign(data.components_localizations.en_US, {
+        "5GWqi3MXpt": "Content above tinted video",
+        E6CK5Xd1cE: "Open sheet · video backdrop",
+    });
+    const first = data.components_config.base.stack.components[0];
+    if (!first || first.type !== "button") {
+        return data;
+    }
+    const { action } = first;
+    if (!action ||
+        action.type !== "navigate_to" ||
+        action.destination !== "sheet") {
+        return data;
+    }
+    const { sheet } = action;
+    if (!sheet) {
+        return data;
+    }
+    sheet.background = STORY_BACKGROUND_VIDEO_FILL;
+    sheet.stack.background = null;
+    const headline = sheet.stack.components[0];
+    if (headline?.type === "text") {
+        headline.horizontal_alignment = "center";
+        headline.color = {
+            light: { type: "hex", value: "#ffffff" },
+        };
+        headline.font_size = "heading_m";
+        headline.font_weight = "semibold";
+    }
+    return data;
+})();

package/dist/components/stack/Stack.stories.svelte

@@ -6,6 +6,7 @@
   import { localizationDecorator } from "../../stories/localization-decorator";
   import type { StackProps } from "../../types/components/stack";
   import type { Component } from "../../types/component";
+  import { STORY_BACKGROUND_VIDEO_FILL } from "../../stories/video-background-story-fixture";
   import { DEFAULT_TEXT_COLOR } from "../../utils/constants";
   import { defineMeta } from "@storybook/addon-svelte-csf";
 
@@ -153,6 +154,79 @@
   }}
 />
 
+<Story
+  name="Surface — video background"
+  parameters={{
+    chromatic: { disableSnapshot: true },
+    docs: {
+      description: {
+        story:
+          "**Z-order:** `BackgroundVideoSurface` (`z-index: 1`), `::before` tint (`z-index: 2`), siblings (`z-index: 3`). Content and controls should remain sharp above the tint; motion is disabled in Chromatic.",
+      },
+    },
+  }}
+  args={{
+    size: {
+      width: { type: "fixed", value: 380 },
+      height: { type: "fixed", value: 260 },
+    },
+    shape: {
+      type: "rectangle",
+      corners: {
+        top_leading: 20,
+        top_trailing: 20,
+        bottom_leading: 20,
+        bottom_trailing: 20,
+      },
+    },
+    background: STORY_BACKGROUND_VIDEO_FILL,
+    components: [
+      {
+        type: "text",
+        size: {
+          width: { type: "fit" },
+          height: { type: "fit" },
+        },
+        horizontal_alignment: "center",
+        name: "Item 1",
+        id: "vbg-1",
+        text_lid: "id1",
+        color: {
+          light: { type: "hex", value: "#ffffff" },
+        },
+        font_name: null,
+        font_size: "heading_s",
+        font_weight: "bold",
+        background_color: {
+          dark: { type: "alias", value: "transparent" },
+          light: { type: "alias", value: "transparent" },
+        },
+      },
+      {
+        type: "text",
+        size: {
+          width: { type: "fill" },
+          height: { type: "fit" },
+        },
+        horizontal_alignment: "center",
+        name: "Item 2",
+        id: "vbg-2",
+        text_lid: "id2",
+        color: {
+          light: { type: "hex", value: "#e2e8f0" },
+        },
+        font_name: null,
+        font_size: "body_m",
+        font_weight: "regular",
+        background_color: {
+          dark: { type: "alias", value: "transparent" },
+          light: { type: "alias", value: "transparent" },
+        },
+      },
+    ] as unknown as TextNodeProps[],
+  }}
+/>
+
 <Story
   name="Z Layer"
   args={{

package/dist/components/stack/Stack.svelte

@@ -6,8 +6,16 @@
   import { getPaywallContext } from "../../stores/paywall";
   import { getSelectedStateContext } from "../../stores/selected";
   import { getOptionalVariablesContext } from "../../stores/variables";
+  import BackgroundVideoSurface from "../paywall/BackgroundVideoSurface.svelte";
   import type { StackProps } from "../../types/components/stack";
-  import { mapBackground } from "../../utils/background-utils";
+  import {
+    mapBackground,
+    resolveBackgroundVideoForSurface,
+  } from "../../utils/background-utils";
+  import {
+    rcVideoBackgroundHostClass,
+    videoBackgroundHostStyles,
+  } from "../../utils/video-background-host";
   import {
     css,
     mapBorder,
@@ -66,6 +74,15 @@
   const getColorMode = getColorModeContext();
   const colorMode = $derived(getColorMode());
 
+  const hasVideoBg = $derived(background?.type === "video");
+  const videoSurface = $derived.by(() => {
+    if (!hasVideoBg) return null;
+    const bg = background;
+    if (!bg || bg.type !== "video") return null;
+    return resolveBackgroundVideoForSurface(colorMode, bg);
+  });
+  const borderRadiusCss = $derived(mapBorderRadius(shape));
+
   const stackStyle = $derived(
     css({
       display: "flex",
@@ -78,8 +95,12 @@
       padding: mapSpacing(padding),
       ...mapBackground(colorMode, background_color, background),
       ...mapBorder(colorMode, border),
-      "border-radius": mapBorderRadius(shape),
+      "border-radius": borderRadiusCss,
       "box-shadow": mapShadow(colorMode, shadow),
+      ...videoBackgroundHostStyles({
+        hasVideoBg,
+        clipOverflow: borderRadiusCss !== "0",
+      }),
       // Read from props proxy so $derived re-evaluates when parent updates style
       ...props.style,
     }),
@@ -124,9 +145,28 @@
     role={onclick !== undefined ? "button" : undefined}
     {onclick}
     style={stackStyle}
-    class={["stack", "rc-gradient-border", classProp].filter(Boolean).join(" ")}
+    class={[
+      "stack",
+      "rc-gradient-border",
+      classProp,
+      hasVideoBg ? rcVideoBackgroundHostClass("stack") : "",
+    ]
+      .filter(Boolean)
+      .join(" ")}
     data-testid={testId}
   >
+    {#if videoSurface}
+      <BackgroundVideoSurface
+        url={videoSurface.url}
+        urlLowRes={videoSurface.url_low_res}
+        objectFit={videoSurface.fit}
+        objectPosition={videoSurface.position}
+        poster={videoSurface.posterWebp}
+        mute={videoSurface.mute}
+        loop={videoSurface.loop}
+      />
+    {/if}
+
     {#if badge}
       <div style={badgeStyle}>
         <Node nodeData={badge.stack} />
@@ -173,4 +213,19 @@
       background: var(--overlay);
     }
   }
+
+  .stack.rc-stack-video-bg::before {
+    z-index: 2;
+    pointer-events: none;
+  }
+
+  .stack.rc-stack-video-bg > :global(.rc-bg-video) {
+    z-index: 1;
+  }
+
+  /* Keep flex children interactive and above tinted overlay (::before z-index). */
+  .stack.rc-stack-video-bg > :global(:not(.rc-bg-video)) {
+    position: relative;
+    z-index: 3;
+  }
 </style>

package/dist/components/tabs/Tabs.stories.svelte

@@ -5,6 +5,7 @@
   import { variablesDecorator } from "../../stories/variables-decorator";
   import { defineMeta } from "@storybook/addon-svelte-csf";
   import { VARIABLES } from "../paywall/fixtures/variables";
+  import { TABS_VIDEO_STACKING_STORY_ARGS } from "./tabs-video-stacking-story-args";
 
   const defaultLocale = "en_US";
 
@@ -1428,3 +1429,29 @@
     type: "tabs",
   }}
 />
+
+<Story
+  name="Surface — video background (stacking / z-order)"
+  parameters={{
+    chromatic: { disableSnapshot: true },
+    docs: {
+      description: {
+        story:
+          "**Z-order:** video layer → tinted `::before` → tab content clip. Rounded corners should clip the backdrop; Chromatic skips motion snapshots.",
+      },
+    },
+  }}
+  decorators={[
+    componentDecorator(),
+    localizationDecorator({
+      defaultLocale,
+      localizations: {
+        [defaultLocale]: {
+          "t-a-body": "Tab A · content above video",
+          "t-b-body": "Tab B · content above video",
+        },
+      },
+    }),
+  ]}
+  args={TABS_VIDEO_STACKING_STORY_ARGS}
+/>

package/dist/components/tabs/Tabs.svelte

@@ -4,8 +4,16 @@
   import { getPaywallContext } from "../../stores/paywall";
   import { getSelectedStateContext } from "../../stores/selected";
   import { getOptionalVariablesContext } from "../../stores/variables";
+  import BackgroundVideoSurface from "../paywall/BackgroundVideoSurface.svelte";
   import type { TabsProps } from "../../types/components/tabs";
-  import { mapBackground } from "../../utils/background-utils";
+  import {
+    mapBackground,
+    resolveBackgroundVideoForSurface,
+  } from "../../utils/background-utils";
+  import {
+    rcVideoBackgroundHostClass,
+    videoBackgroundHostStyles,
+  } from "../../utils/video-background-host";
   import {
     css,
     mapBorder,
@@ -40,15 +48,30 @@
   const getColorMode = getColorModeContext();
   const colorMode = $derived(getColorMode());
 
+  const hasVideoBg = $derived(background?.type === "video");
+  const videoSurface = $derived.by(() => {
+    if (!hasVideoBg) return null;
+    const bg = background;
+    if (!bg || bg.type !== "video") return null;
+    return resolveBackgroundVideoForSurface(colorMode, bg);
+  });
+
+  const tabsBorderRadiusCss = $derived(mapBorderRadius(shape));
+
   const styles = $derived(
     css({
+      position: "relative",
       width: mapSize(size.width),
       height: mapSize(size.height),
       margin: mapSpacing(margin),
       padding: mapSpacing(padding),
+      ...videoBackgroundHostStyles({
+        hasVideoBg,
+        clipOverflow: tabsBorderRadiusCss !== "0",
+      }),
       ...mapBackground(colorMode, null, background),
       ...mapBorder(colorMode, border),
-      "border-radius": mapBorderRadius(shape),
+      "border-radius": tabsBorderRadiusCss,
       "box-shadow": mapShadow(colorMode, shadow),
     }),
   );
@@ -117,9 +140,51 @@
 </script>
 
 {#if isVisible}
-  <div class="rc-gradient-border" style={styles}>
+  <div
+    class={[
+      "rc-gradient-border",
+      hasVideoBg ? rcVideoBackgroundHostClass("tabs") : "",
+    ]
+      .filter(Boolean)
+      .join(" ")}
+    style={styles}
+  >
+    {#if videoSurface}
+      <BackgroundVideoSurface
+        url={videoSurface.url}
+        urlLowRes={videoSurface.url_low_res}
+        objectFit={videoSurface.fit}
+        objectPosition={videoSurface.position}
+        poster={videoSurface.posterWebp}
+        mute={videoSurface.mute}
+        loop={videoSurface.loop}
+      />
+    {/if}
     {#if $tab !== undefined}
-      <Stack {...$tab.stack} />
+      <Stack
+        {...$tab.stack}
+        class={hasVideoBg ? "rc-tabs-stack-front" : undefined}
+      />
     {/if}
   </div>
 {/if}
+
+<style>
+  .rc-tabs-video-bg::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: var(--overlay);
+    pointer-events: none;
+    z-index: 2;
+  }
+
+  .rc-tabs-video-bg > :global(.rc-bg-video) {
+    z-index: 1;
+  }
+
+  .rc-tabs-video-bg > :global(.rc-tabs-stack-front) {
+    position: relative;
+    z-index: 3;
+  }
+</style>

package/dist/components/tabs/tabs-video-stacking-story-args.d.ts

@@ -0,0 +1,3 @@
+import type { TabsProps } from "../../types/components/tabs";
+/** Minimal Tabs tree for Storybook layering checks (`rc-tabs-video-bg`). */
+export declare const TABS_VIDEO_STACKING_STORY_ARGS: TabsProps;

package/dist/components/tabs/tabs-video-stacking-story-args.js

@@ -0,0 +1,131 @@
+import { STORY_BACKGROUND_VIDEO_FILL } from "../../stories/video-background-story-fixture";
+const spacer = { bottom: 0, leading: 0, top: 0, trailing: 0 };
+const simpleTextStack = ({ tid, textLid, }) => ({
+    type: "stack",
+    id: `${tid}-inner`,
+    name: "",
+    background_color: null,
+    background: null,
+    badge: null,
+    border: null,
+    shadow: null,
+    spacing: 0,
+    dimension: {
+        alignment: "center",
+        distribution: "center",
+        type: "vertical",
+    },
+    shape: null,
+    margin: spacer,
+    padding: {
+        bottom: 24,
+        leading: 24,
+        top: 24,
+        trailing: 24,
+    },
+    size: {
+        width: { type: "fill" },
+        height: { type: "fit" },
+    },
+    components: [
+        {
+            type: "text",
+            id: `${tid}-t`,
+            name: "",
+            text_lid: textLid,
+            background_color: null,
+            color: {
+                light: { type: "hex", value: "#ffffff" },
+            },
+            font_name: null,
+            font_size: "heading_m",
+            font_weight: "semibold",
+            horizontal_alignment: "center",
+            margin: spacer,
+            padding: spacer,
+            size: {
+                width: { type: "fit" },
+                height: { type: "fit" },
+            },
+        },
+    ],
+});
+const tabToggle = {
+    type: "tab_control_toggle",
+    id: "vbg-toggle",
+    name: "",
+    default_value: false,
+    thumb_color_on: {
+        light: { type: "hex", value: "#ffffffff" },
+    },
+    thumb_color_off: {
+        light: { type: "hex", value: "#ccccccff" },
+    },
+    track_color_on: {
+        light: { type: "hex", value: "#4488ffff" },
+    },
+    track_color_off: {
+        light: { type: "hex", value: "#00000044" },
+    },
+};
+function tab(contentId, bodyLid) {
+    return {
+        type: "tab",
+        id: contentId,
+        name: "",
+        stack: simpleTextStack({ tid: contentId, textLid: bodyLid }),
+    };
+}
+/** Minimal Tabs tree for Storybook layering checks (`rc-tabs-video-bg`). */
+export const TABS_VIDEO_STACKING_STORY_ARGS = {
+    type: "tabs",
+    id: "tabs-video-z",
+    name: "Tabs · video layering",
+    size: {
+        width: { type: "fixed", value: 400 },
+        height: { type: "fixed", value: 300 },
+    },
+    padding: { bottom: 12, leading: 12, top: 12, trailing: 12 },
+    margin: spacer,
+    background: STORY_BACKGROUND_VIDEO_FILL,
+    shape: {
+        corners: {
+            bottom_leading: 20,
+            bottom_trailing: 20,
+            top_leading: 20,
+            top_trailing: 20,
+        },
+        type: "rectangle",
+    },
+    border: null,
+    shadow: null,
+    default_tab_id: "tab-a",
+    control: {
+        type: "toggle",
+        stack: {
+            type: "stack",
+            id: "vbg-toggle-stack",
+            name: "",
+            background_color: null,
+            background: null,
+            badge: null,
+            border: null,
+            shadow: null,
+            spacing: 16,
+            dimension: {
+                alignment: "center",
+                distribution: "center",
+                type: "horizontal",
+            },
+            shape: null,
+            margin: { bottom: 8, leading: 0, top: 0, trailing: 0 },
+            padding: spacer,
+            size: {
+                width: { type: "fill" },
+                height: { type: "fit" },
+            },
+            components: [tabToggle],
+        },
+    },
+    tabs: [tab("tab-a", "t-a-body"), tab("tab-b", "t-b-body")],
+};

package/dist/components/video/Video.svelte

@@ -20,6 +20,10 @@
     evaluateVisibilityConditions,
     getActiveStateProps,
   } from "../../utils/style-utils";
+  import {
+    applyInlineVideoPlaybackFlags,
+    subscribeDecorativeVideoAutoplayAttempts,
+  } from "../../utils/video-inline-playback";
   import ClipPath from "../image/ClipPath.svelte";
   import Overlay from "../image/Overlay.svelte";
 
@@ -208,11 +212,9 @@
   const shouldShowFallback = $derived(hasVideoError || !video);
 
   // Autoplay: native `autoplay` + programmatic `play()`. Unmuted autoplay is often blocked; we retry
-  // once with muted playback (`playbackMutedOverride`) then try to restore sound. Controls follow
-  // `show_controls` only. Bootstrap once per URL; `play()` when `readyState >= HAVE_CURRENT_DATA`.
-  // Microtask + rAF retries cover decode/policy ordering; refresh leaves `document` already
-  // `complete` (`load` won't fire)—extra microtask retries `tryPlay` for muted→unmuted paths.
-  // Pair with `translateZ(0)` + rc-workflows `screen-slide-fade`.
+  // once with muted playback (`playbackMutedOverride`) then try to restore sound (WebKit quirks).
+  // Bootstrap timing is shared via `subscribeDecorativeVideoAutoplayAttempts` (+ microtasks / `load`).
+  // Pair `translateZ(0)` on `<video>` with rc-workflows `screen-slide-fade` where needed.
   $effect(() => {
     if (!auto_play) {
       untrack(() => {
@@ -243,10 +245,12 @@
 
     let cancelled = false;
 
-    /** Keep `muted` / `playsInline` aligned with `mute_audio`, `playbackMutedOverride`, and the template. */
+    /** Keep muted / playsInline aligned with `mute_audio`, `playbackMutedOverride`, and the template. */
     const applyVideoPlaybackFlags = () => {
-      el.muted = mute_audio || playbackMutedOverride;
-      el.playsInline = true;
+      applyInlineVideoPlaybackFlags(el, {
+        preferMuted: mute_audio,
+        mutedPlaybackOverride: playbackMutedOverride,
+      });
     };
 
     let playingUnmuteListener: (() => void) | null = null;
@@ -271,16 +275,25 @@
       const playPromise = el.play();
       if (playPromise !== undefined) {
         playPromise.catch(() => {
+          if (cancelled || !el.isConnected) return;
           if (!mute_audio && !playbackMutedOverride) {
             untrack(() => {
               playbackMutedOverride = true;
             });
-            applyVideoPlaybackFlags();
+            applyInlineVideoPlaybackFlags(el, {
+              preferMuted: mute_audio,
+              mutedPlaybackOverride: true,
+            });
 
             /** Unmuted `play()` after a forced-muted start sometimes only works tied to playback (WebKit). */
             let unmuteAfterMutedStartHandled = false;
             const tryRestoreAudioAfterMutedAutoplay = () => {
-              if (unmuteAfterMutedStartHandled || mute_audio || cancelled)
+              if (
+                unmuteAfterMutedStartHandled ||
+                mute_audio ||
+                cancelled ||
+                !el.isConnected
+              )
                 return;
               unmuteAfterMutedStartHandled = true;
               queueMicrotask(() => {
@@ -293,6 +306,7 @@
                 const p3 = el.play();
                 if (p3 === undefined) return;
                 p3.catch(() => {
+                  if (cancelled || !el.isConnected) return;
                   untrack(() => {
                     playbackMutedOverride = true;
                   });
@@ -303,6 +317,7 @@
             };
 
             const onPlayingAfterMutedBootstrap = () => {
+              if (cancelled || !el.isConnected) return;
               playingUnmuteListener = null;
               tryRestoreAudioAfterMutedAutoplay();
             };
@@ -339,17 +354,6 @@
       }
     };
 
-    const onMediaReady = () => {
-      tryPlay();
-    };
-
-    if (el.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) {
-      el.addEventListener("loadeddata", onMediaReady);
-      el.addEventListener("canplay", onMediaReady);
-    } else {
-      tryPlay();
-    }
-
     /**
      * Once per `video.url`: muted `play()` nudge helps iOS decode before `HAVE_CURRENT_DATA`.
      * When `mute_audio` is false, `load()` reloads the media so poster/metadata can attach; unmuted
@@ -368,49 +372,21 @@
         }
       }
     };
+
     if (needsBootstrap && el.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) {
       nudgePlayback();
     }
 
-    /** Extra `tryPlay` ticks: next microtask vs next frame vs cold `load`; WebKit reordering varies. */
-    const deferTryPlayWithReadyGate = () => {
-      queueMicrotask(() => {
-        if (cancelled) return;
-        if (el.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
-          tryPlay();
-        }
-      });
-      requestAnimationFrame(() => {
-        if (cancelled) return;
-        if (el.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
-          tryPlay();
-        }
-      });
-    };
-
-    deferTryPlayWithReadyGate();
-
-    const onWindowLoad = () => {
-      tryPlay();
-    };
-    if (typeof document !== "undefined" && typeof window !== "undefined") {
-      if (document.readyState === "complete") {
-        queueMicrotask(() => {
-          if (!cancelled) tryPlay();
-        });
-      } else {
-        window.addEventListener("load", onWindowLoad);
-      }
-    }
+    const unsubAutoplay = subscribeDecorativeVideoAutoplayAttempts(
+      el,
+      tryPlay,
+      () => cancelled,
+    );
 
     return () => {
       cancelled = true;
       clearPlayingUnmuteListener();
-      el.removeEventListener("loadeddata", onMediaReady);
-      el.removeEventListener("canplay", onMediaReady);
-      if (typeof window !== "undefined") {
-        window.removeEventListener("load", onWindowLoad);
-      }
+      unsubAutoplay();
     };
   });
 

package/dist/stories/video-background-story-fixture.d.ts

@@ -0,0 +1,3 @@
+import type { BackgroundVideo } from "../types/background";
+/** Reusable Storybook payload for carousel/stack/tabs video-background demos. */
+export declare const STORY_BACKGROUND_VIDEO_FILL: BackgroundVideo;