@xenterprises/nuxt-x-marketing 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -30,6 +30,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   section and its sample product data were dropped with them. Every other section of the
   demo page is unchanged.
 
+## [1.6.0] - 2026-10-12
+
+### Added
+
+- **`XMarkHero` `scrimWidth` prop** (opt-in, `overlay="scrim-left"` only). CSS length such as
+  `"40%"` or `"36rem"`. On md+ the scrim is 90% black up to `scrimWidth`, then fades out over a
+  further ~34% of the width so the photo on the right stays vivid. Below md it darkens a 90% band
+  from 18% to 82% of the hero height (35% at the top and bottom edges) instead of a flat 90%.
+  Without `scrimWidth`, `scrim-left` and every other default render byte-identical to 1.5.2.
+  Keep the whole text column inside the 90% zone: white title over 90% black on a pure-white
+  pixel is 17.8:1, white/80 subtitle 11.6:1; outside the zone contrast drops fast.
+
+## [1.5.2] - 2026-10-12
+
+### Fixed
+
+- **Scroll reveal uses one long-lived shared IntersectionObserver.** It is created once
+  and never disconnected or rebuilt; plugin hooks (`app:mounted`, `page:finish`) and
+  components only scan for new reveal elements and observe them. Removes the observer
+  churn that left elements unrevealed when IO callbacks did not fire in time. In-viewport
+  elements are still marked visible synchronously, and the fallback timer remains.
+  XMarkHero default look is unchanged from 1.5.1 (text visible by default, new props opt-in).
+
 ## [1.5.1] - 2026-10-12
 
 ### Fixed

package/app/components/X/Mark/Hero/index.vue

@@ -40,10 +40,16 @@
 
 			<!-- Overlay -->
 			<div
-				v-if="overlay !== 'none'"
+				v-if="overlay !== 'none' && !softScrim"
 				class="absolute inset-0"
 				:class="overlayClass"
 			/>
+			<!-- scrim-left + scrimWidth (opt-in, 1.6.0) -->
+			<div
+				v-else-if="softScrim"
+				class="absolute inset-0 x-hero-scrim-w"
+				:style="{ '--x-scrim-w': scrimWidth }"
+			/>
 		</div>
 
 		<!-- Content -->
@@ -196,6 +202,18 @@ const props = defineProps({
 		type: String,
 		default: "",
 	},
+	/**
+	 * scrim-left only, opt-in. CSS length for the 90% black zone, e.g. "40%" or "36rem".
+	 * When set: desktop (md+) keeps 90% up to this width, then a long soft fade so the
+	 * photo on the right stays vivid; mobile darkens a band behind the text instead of
+	 * a flat 90% over the whole hero. Keep the text column inside the 90% zone.
+	 * Unset (default): scrim-left renders exactly as in 1.5.x.
+	 */
+	scrimWidth: {
+		type: String,
+		default: "",
+		validator: (v) => v === "" || /^\d+(\.\d+)?(%|px|rem|em|vw)$/.test(v),
+	},
 	/** Add top padding for non-transparent nav */
 	includeNavPadding: {
 		type: Boolean,
@@ -221,6 +239,10 @@ const overlayClass = computed(() => {
 	return overlays[props.overlay] || "";
 });
 
+// scrim-left with scrimWidth renders a separate overlay element; without it the
+// 1.5.x overlay element renders unchanged (no extra class or style attribute).
+const softScrim = computed(() => props.overlay === "scrim-left" && !!props.scrimWidth);
+
 const heightClass = computed(() => {
 	const heights = {
 		full: "min-h-[calc(100svh-var(--ui-header-height))]",
@@ -260,3 +282,32 @@ const contentAlignmentClasses = computed(() => {
 	return aligns[props.align];
 });
 </script>
+
+<style>
+/* scrim-left + scrimWidth (1.6.0). Mobile: 90% band behind the text column,
+ * lighter at the top and bottom edges of the hero. */
+.x-hero-scrim-w {
+	background-image: linear-gradient(
+		to bottom,
+		rgb(0 0 0 / 0.35) 0%,
+		rgb(0 0 0 / 0.9) 18%,
+		rgb(0 0 0 / 0.9) 82%,
+		rgb(0 0 0 / 0.35) 100%
+	);
+}
+/* md+: 90% up to --x-scrim-w, then a long eased fade to clear. */
+@media (min-width: 768px) {
+	.x-hero-scrim-w {
+		background-image: linear-gradient(
+			to right,
+			rgb(0 0 0 / 0.9) 0,
+			rgb(0 0 0 / 0.9) var(--x-scrim-w),
+			rgb(0 0 0 / 0.72) calc(var(--x-scrim-w) + 4%),
+			rgb(0 0 0 / 0.45) calc(var(--x-scrim-w) + 10%),
+			rgb(0 0 0 / 0.2) calc(var(--x-scrim-w) + 18%),
+			rgb(0 0 0 / 0.06) calc(var(--x-scrim-w) + 26%),
+			rgb(0 0 0 / 0) calc(var(--x-scrim-w) + 34%)
+		);
+	}
+}
+</style>

package/app/composables/useScrollReveal.js

@@ -24,10 +24,12 @@ const animationSelectors = [
   '.xFadeUp-stagger',
 ].join(', ');
 
-// One active observer app-wide. Every init (plugin, app.vue workaround,
-// component) replaces the previous one, so callers never stack observers.
-let activeObserver = null;
+// One long-lived observer shared app-wide. It is created once and never
+// rebuilt: every init (plugin hooks, components, app.vue workarounds) only
+// scans for new elements and observes them, so there is no observer churn.
+let sharedObserver = null;
 let fallbackTimer = null;
+const observed = new WeakSet();
 
 const prefersReducedMotion = () =>
   typeof window !== 'undefined' &&
@@ -41,18 +43,40 @@ const inViewport = (el) => {
   return r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw;
 };
 
-export const useScrollReveal = (options = {}) => {
-  // Lifecycle hooks are only registered inside a component instance.
-  // Outside one (e.g. a plugin) the caller drives initScrollReveal/cleanup itself.
-  const instance = getCurrentInstance();
+const revealInViewport = () => {
+  document.querySelectorAll(animationSelectors).forEach((el) => {
+    if (!el.classList.contains('is-visible') && inViewport(el)) {
+      el.classList.add('is-visible');
+      sharedObserver?.unobserve(el);
+    }
+  });
+};
 
-  const defaultOptions = {
-    threshold: 0.15,
-    rootMargin: '0px 0px -80px 0px',
-    ...options,
-  };
+const getSharedObserver = () => {
+  if (!sharedObserver) {
+    sharedObserver = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add('is-visible');
+          sharedObserver?.unobserve(entry.target);
+        }
+      });
+    }, { threshold: 0.15, rootMargin: '0px 0px -80px 0px' });
+  }
+  return sharedObserver;
+};
 
-  const observer = ref(null);
+// Test-only: drop the shared observer and pending fallback.
+export const __resetScrollRevealForTests = () => {
+  sharedObserver = null;
+  if (fallbackTimer) clearTimeout(fallbackTimer);
+  fallbackTimer = null;
+};
+
+export const useScrollReveal = () => {
+  // Lifecycle hooks are only registered inside a component instance.
+  // Outside one (e.g. a plugin) the caller drives initScrollReveal itself.
+  const instance = getCurrentInstance();
 
   const initScrollReveal = () => {
     if (!import.meta.client || typeof document === 'undefined') return;
@@ -75,54 +99,31 @@ export const useScrollReveal = (options = {}) => {
     });
     root.classList.add(REVEAL_ARMED_CLASS);
 
-    if (activeObserver && activeObserver !== observer.value) activeObserver.disconnect();
-    if (observer.value) observer.value.disconnect();
-
-    observer.value = new IntersectionObserver((entries) => {
-      entries.forEach((entry) => {
-        if (entry.isIntersecting) {
-          entry.target.classList.add('is-visible');
-          if (options.once !== false) {
-            observer.value?.unobserve(entry.target);
-          }
-        } else if (options.once === false) {
-          entry.target.classList.remove('is-visible');
-        }
-      });
-    }, defaultOptions);
-    activeObserver = observer.value;
-
-    elements.forEach((el) => observer.value?.observe(el));
+    const io = getSharedObserver();
+    elements.forEach((el) => {
+      if (!el.classList.contains('is-visible') && !observed.has(el)) {
+        observed.add(el);
+        io.observe(el);
+      }
+    });
 
     // Fallback: if IO never fires, reveal anything on screen after a short wait.
     if (fallbackTimer) clearTimeout(fallbackTimer);
     fallbackTimer = setTimeout(() => {
       fallbackTimer = null;
-      document.querySelectorAll(animationSelectors).forEach((el) => {
-        if (!el.classList.contains('is-visible') && inViewport(el)) {
-          el.classList.add('is-visible');
-        }
-      });
+      revealInViewport();
     }, REVEAL_FALLBACK_MS);
   };
 
-  const cleanup = () => {
-    if (observer.value) {
-      observer.value.disconnect();
-      if (activeObserver === observer.value) activeObserver = null;
-      observer.value = null;
-    }
-  };
+  // The shared observer is long-lived; per-caller cleanup is a no-op.
+  // Detached elements are released by the WeakSet and by IO itself.
+  const cleanup = () => {};
 
   if (import.meta.client && instance) {
     onMounted(() => {
       // Small delay to ensure DOM is ready
       setTimeout(initScrollReveal, 100);
     });
-
-    onUnmounted(() => {
-      cleanup();
-    });
   }
 
   return {

package/app/plugins/marketing.client.ts

@@ -9,7 +9,8 @@ export default defineNuxtPlugin((nuxtApp) => {
   // instance, so drive it from app hooks: app:mounted covers initial
   // hydration (including prerendered pages, where page:finish can fire
   // before mount or not at all), page:finish covers client navigations.
-  // initScrollReveal is idempotent and keeps one observer app-wide.
+  // initScrollReveal only scans and observes new elements on one shared,
+  // long-lived observer; it never tears down or rebuilds it.
   const { initScrollReveal } = useScrollReveal();
   const run = () => nextTick(() => initScrollReveal());
   nuxtApp.hook('app:mounted', run);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@xenterprises/nuxt-x-marketing",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "main": "./nuxt.config.ts",
   "scripts": {
     "dev": "nuxi dev .playground",