nuxt-hero 0.1.0

package/dist/runtime/composables/_gsap.d.ts

@@ -0,0 +1,60 @@
+import { type Ref, type WatchSource } from 'vue';
+import { type MaybeComputedElementRef } from '@vueuse/core';
+/** Any GSAP plugin accepted by gsap.registerPlugin(). */
+export type GSAPPlugin = object;
+export interface UseGSAPOptions {
+    /** Root element or ref to scope GSAP selectors to. */
+    scope?: MaybeComputedElementRef;
+    /** GSAP plugins to register before the callback runs. e.g. [ScrollTrigger, Draggable] */
+    plugins?: GSAPPlugin[];
+    /** Respect prefers-reduced-motion. When true, callback is skipped. @default true */
+    respectReducedMotion?: boolean;
+    /** Reactive sources that trigger re-initialization (reverts then re-runs callback after nextTick). */
+    watchSources?: WatchSource[];
+}
+export interface UseGSAPReturn {
+    /** The gsap instance with plugins registered. Use instead of importing gsap directly. */
+    gsap: typeof import('gsap').gsap;
+    /** The GSAP context, undefined before mount / on server. */
+    context: Readonly<Ref<gsap.Context | undefined>>;
+    /** Wrap a function so animations are tracked by this context. */
+    contextSafe: <T extends (...args: any[]) => any>(fn: T) => T;
+    /** Create a gsap.timeline() tracked by this context. */
+    timeline: (vars?: gsap.TimelineVars) => gsap.core.Timeline;
+    /** Revert and re-run the animation callback. */
+    refresh: () => void;
+    /** Manually kill the context. */
+    kill: () => void;
+    /** Whether the user prefers reduced motion (reactive). */
+    prefersReducedMotion: Readonly<Ref<boolean>>;
+}
+export interface UseGSAPCallbackContext {
+    gsap: typeof import('gsap').gsap;
+    context: gsap.Context;
+}
+/**
+ * Vue composable that wraps `gsap.context()` for safe, scoped GSAP animations.
+ *
+ * - Creates animations in `onMounted` (DOM is available).
+ * - Scopes selectors to a container element via `gsap.context()`.
+ * - Automatically reverts all animations and ScrollTriggers on unmount.
+ * - Supports `prefers-reduced-motion` — callback is skipped when preferred.
+ * - Provides `contextSafe()` for creating animations in event handlers.
+ * - Returns a `timeline()` helper that auto-tracks timelines in the context.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const container = ref<HTMLElement | null>(null)
+ *
+ * const { gsap, contextSafe, timeline } = useGSAP((self) => {
+ *   self.gsap.to('.box', { x: 100, duration: 0.6 })
+ * }, { scope: container })
+ *
+ * const onClick = contextSafe(() => {
+ *   gsap.to('.box', { rotation: 360 })
+ * })
+ * </script>
+ * ```
+ */
+export declare function useGSAP(callbackOrOptions?: ((self: UseGSAPCallbackContext) => void) | UseGSAPOptions, maybeOptions?: UseGSAPOptions): UseGSAPReturn;

package/dist/runtime/composables/_gsap.js

@@ -0,0 +1,135 @@
+import {
+  getCurrentInstance,
+  nextTick,
+  onMounted,
+  onUnmounted,
+  readonly,
+  ref,
+  shallowRef,
+  watch
+} from "vue";
+import { unrefElement, useMediaQuery } from "@vueuse/core";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+function createSSRNoOp() {
+  const noop = (() => {
+  });
+  return {
+    gsap: new Proxy({}, { get: () => noop }),
+    context: readonly(shallowRef(void 0)),
+    contextSafe: (fn) => fn,
+    timeline: () => ({}),
+    refresh: noop,
+    kill: noop,
+    prefersReducedMotion: readonly(ref(false))
+  };
+}
+let _coreReady = false;
+function ensureCorePlugins() {
+  if (_coreReady) return;
+  _coreReady = true;
+  gsap.registerPlugin(ScrollTrigger);
+}
+export function useGSAP(callbackOrOptions, maybeOptions) {
+  if (import.meta.env.SSR) {
+    return createSSRNoOp();
+  }
+  ensureCorePlugins();
+  let callback;
+  let options;
+  if (typeof callbackOrOptions === "function") {
+    callback = callbackOrOptions;
+    options = maybeOptions ?? {};
+  } else {
+    callback = void 0;
+    options = callbackOrOptions ?? {};
+  }
+  const {
+    scope,
+    plugins,
+    respectReducedMotion = true,
+    watchSources
+  } = options;
+  if (plugins && plugins.length > 0) {
+    gsap.registerPlugin(...plugins);
+  }
+  const context = shallowRef();
+  const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
+  let stopWatchSources;
+  function revert() {
+    context.value?.revert();
+    context.value = void 0;
+  }
+  function init() {
+    revert();
+    if (respectReducedMotion && prefersReducedMotion.value) {
+      return;
+    }
+    const el = scope ? unrefElement(scope) : void 0;
+    if (scope && !el) return;
+    context.value = gsap.context((ctx) => {
+      callback?.({ gsap, context: ctx });
+    }, el ?? void 0);
+  }
+  function refresh() {
+    init();
+  }
+  function kill() {
+    stopWatchSources?.();
+    revert();
+  }
+  function contextSafe(fn) {
+    return ((...args) => {
+      if (!context.value) {
+        return;
+      }
+      let result;
+      context.value.add(() => {
+        result = fn(...args);
+      });
+      return result;
+    });
+  }
+  function timeline(vars) {
+    if (context.value) {
+      let tl;
+      context.value.add(() => {
+        tl = gsap.timeline(vars);
+      });
+      return tl ?? gsap.timeline(vars);
+    }
+    return gsap.timeline(vars);
+  }
+  const instance = getCurrentInstance();
+  if (instance) {
+    onMounted(() => {
+      init();
+    });
+    onUnmounted(() => {
+      revert();
+    });
+  }
+  if (watchSources && watchSources.length > 0) {
+    stopWatchSources = watch(watchSources, () => {
+      nextTick(() => init());
+    });
+  }
+  if (respectReducedMotion) {
+    watch(prefersReducedMotion, (reduced) => {
+      if (reduced) {
+        revert();
+      } else {
+        init();
+      }
+    });
+  }
+  return {
+    gsap,
+    context: readonly(context),
+    contextSafe,
+    timeline,
+    refresh,
+    kill,
+    prefersReducedMotion: readonly(prefersReducedMotion)
+  };
+}

package/dist/runtime/composables/_hls.d.ts

@@ -0,0 +1,35 @@
+import { type Ref, type MaybeRef } from 'vue';
+export interface UseHlsOptions {
+    /**
+     * Start loading segments immediately or wait until play.
+     * @default true
+     */
+    autoLoad?: boolean;
+}
+export interface UseHlsReturn {
+    /** Whether hls.js is loading/attaching */
+    loading: Ref<boolean>;
+    /** Error message if HLS setup failed */
+    error: Ref<string | null>;
+    /** Available quality levels (heights) once manifest is parsed */
+    qualities: Ref<number[]>;
+    /** Set quality: 0 = auto, otherwise the height value */
+    setQuality: (height: number) => void;
+    /** Destroy the HLS instance manually */
+    destroy: () => void;
+}
+/**
+ * Composable for HLS video playback.
+ *
+ * Uses `hls.js` when available, falls back to native HLS (Safari).
+ * The `<video>` element is still controlled by VueUse's `useMediaControls`.
+ *
+ * `hls.js` is dynamically imported — only loaded when an `.m3u8` source is used.
+ *
+ * @example
+ * ```ts
+ * const videoRef = useTemplateRef<HTMLVideoElement>('videoRef')
+ * const { loading, error, qualities, setQuality } = useHls(videoRef, () => props.hlsSrc)
+ * ```
+ */
+export declare function useHls(videoEl: MaybeRef<HTMLVideoElement | null | undefined>, src: MaybeRef<string>, options?: UseHlsOptions): UseHlsReturn;

package/dist/runtime/composables/_hls.js

@@ -0,0 +1,88 @@
+import { ref, watch, toValue } from "vue";
+import { tryOnScopeDispose } from "@vueuse/core";
+export function useHls(videoEl, src, options = {}) {
+  const { autoLoad = true } = options;
+  const loading = ref(false);
+  const error = ref(null);
+  const qualities = ref([]);
+  let hls = null;
+  let HlsClass = null;
+  async function init() {
+    const el = toValue(videoEl);
+    const url = toValue(src);
+    cleanup();
+    if (!el || !url) return;
+    if (el.canPlayType("application/vnd.apple.mpegurl")) {
+      el.src = url;
+      return;
+    }
+    loading.value = true;
+    error.value = null;
+    try {
+      if (!HlsClass) {
+        const mod = await import("hls.js");
+        HlsClass = mod.default || mod;
+      }
+      if (!HlsClass.isSupported()) {
+        el.src = url;
+        loading.value = false;
+        return;
+      }
+      hls = new HlsClass({
+        autoStartLoad: autoLoad
+      });
+      hls.loadSource(url);
+      hls.attachMedia(el);
+      hls.on(HlsClass.Events.MANIFEST_PARSED, () => {
+        if (!hls) return;
+        qualities.value = hls.levels.map((l) => l.height);
+        loading.value = false;
+      });
+      hls.on(HlsClass.Events.ERROR, (_event, data) => {
+        if (data.fatal) {
+          error.value = `HLS error: ${data.type} \u2014 ${data.details}`;
+          loading.value = false;
+          if (data.type === HlsClass.ErrorTypes.NETWORK_ERROR) {
+            hls?.startLoad();
+          } else if (data.type === HlsClass.ErrorTypes.MEDIA_ERROR) {
+            hls?.recoverMediaError();
+          } else {
+            cleanup();
+          }
+        }
+      });
+      if (!autoLoad) {
+        const onPlay = () => {
+          el.removeEventListener("play", onPlay);
+          hls?.startLoad();
+        };
+        el.addEventListener("play", onPlay);
+      }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : "Failed to load hls.js";
+      loading.value = false;
+    }
+  }
+  function cleanup() {
+    if (hls) {
+      hls.destroy();
+      hls = null;
+    }
+    qualities.value = [];
+  }
+  function setQuality(height) {
+    if (!hls) return;
+    if (height === 0) {
+      hls.currentLevel = -1;
+    } else {
+      const idx = hls.levels.findIndex((l) => l.height === height);
+      if (idx !== -1) hls.currentLevel = idx;
+    }
+  }
+  function destroy() {
+    cleanup();
+  }
+  watch([() => toValue(videoEl), () => toValue(src)], () => init(), { immediate: true });
+  tryOnScopeDispose(cleanup);
+  return { loading, error, qualities, setQuality, destroy };
+}

package/dist/runtime/composables/_slides.d.ts

@@ -0,0 +1,26 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import type { HeroSlide, ResolvedSlideConfig } from '#hero/types';
+/**
+ * Creates reactive slide state — active slide, per-slide config resolution,
+ * video detection, and animation class computation.
+ *
+ * @param slides - Reactive array of slide definitions
+ * @param activeIndex - Currently active slide index
+ * @param previousIndex - Previously active slide index (for leave animations)
+ * @param displayDefaults - Default visibility flags for UI controls
+ * @param videoEnabled - Whether video backgrounds are enabled
+ * @param enterAnimation - Default enter animation class
+ * @param leaveAnimation - Default leave animation class
+ * @returns Computed slide state and animation helpers
+ */
+export declare function createSlideState(slides: MaybeRefOrGetter<HeroSlide[]>, activeIndex: Ref<number>, previousIndex: Ref<number>, displayDefaults: {
+    showPagination?: boolean;
+    showNavigation?: boolean;
+    showProgress?: boolean;
+    showVideoControls?: boolean;
+}, videoEnabled?: boolean, enterAnimation?: string, leaveAnimation?: string): {
+    activeSlide: import("vue").ComputedRef<HeroSlide>;
+    isActiveSlideVideo: import("vue").ComputedRef<boolean>;
+    activeSlideConfig: import("vue").ComputedRef<ResolvedSlideConfig>;
+    animationClass: (index: number) => string;
+};

package/dist/runtime/composables/_slides.js

@@ -0,0 +1,40 @@
+import { computed, toValue } from "vue";
+import { isVideoUrl } from "#hero/utils";
+export function createSlideState(slides, activeIndex, previousIndex, displayDefaults, videoEnabled = true, enterAnimation = "", leaveAnimation = "") {
+  const activeSlide = computed(() => toValue(slides)[activeIndex.value] ?? { bgSrc: "" });
+  const isActiveSlideVideo = computed(() => {
+    if (!videoEnabled) return false;
+    const slide = activeSlide.value;
+    return slide ? isVideoUrl(slide.bgSrc) : false;
+  });
+  const activeSlideConfig = computed(() => {
+    const cfg = activeSlide.value?.config ?? {};
+    return {
+      showPagination: cfg.showPagination ?? displayDefaults.showPagination ?? true,
+      showNavigation: cfg.showNavigation ?? displayDefaults.showNavigation ?? true,
+      showProgress: cfg.showProgress ?? displayDefaults.showProgress ?? true,
+      showVideoControls: cfg.showVideoControls ?? displayDefaults.showVideoControls ?? true,
+      videoLoop: cfg.videoLoop ?? false,
+      mediaControlsOptions: cfg.mediaControlsOptions
+    };
+  });
+  function resolveAnimation(index) {
+    const slide = toValue(slides)[index];
+    return {
+      enter: slide?.animation?.enter || enterAnimation || void 0,
+      leave: slide?.animation?.leave || leaveAnimation || void 0
+    };
+  }
+  function animationClass(index) {
+    const anim = resolveAnimation(index);
+    if (index === activeIndex.value && anim.enter) return anim.enter;
+    if (index === previousIndex.value && anim.leave) return anim.leave;
+    return "";
+  }
+  return {
+    activeSlide,
+    isActiveSlideVideo,
+    activeSlideConfig,
+    animationClass
+  };
+}

package/dist/runtime/composables/_swiper.d.ts

@@ -0,0 +1,23 @@
+import type { MaybeRefOrGetter } from 'vue';
+import type { Swiper } from 'swiper';
+import type { HeroSlide } from '#hero/types';
+/**
+ * Creates the Swiper instance state — tracks active/snap indices,
+ * provides navigation methods, and handles slide change events.
+ *
+ * @param slides - Reactive array of slide definitions (for total count)
+ * @returns Swiper state refs and navigation functions
+ */
+export declare function createSwiperState(slides: MaybeRefOrGetter<HeroSlide[]>): {
+    swiperInstance: import("vue").ShallowRef<Swiper | undefined, Swiper | undefined>;
+    activeIndex: import("vue").Ref<number, number>;
+    previousIndex: import("vue").Ref<number, number>;
+    snapIndex: import("vue").Ref<number, number>;
+    totalSnaps: import("vue").Ref<number, number>;
+    onSwiper: (swiper: Swiper) => void;
+    onSlideChange: () => void;
+    advanceSlide: () => void;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+};

package/dist/runtime/composables/_swiper.js

@@ -0,0 +1,52 @@
+import { ref, shallowRef, toValue } from "vue";
+export function createSwiperState(slides) {
+  const swiperInstance = shallowRef();
+  const activeIndex = ref(0);
+  const previousIndex = ref(-1);
+  const snapIndex = ref(0);
+  const totalSnaps = ref(1);
+  function updateSnapInfo(swiper) {
+    snapIndex.value = swiper.snapIndex ?? 0;
+    totalSnaps.value = swiper.snapGrid?.length ?? toValue(slides).length;
+  }
+  function onSwiper(swiper) {
+    swiperInstance.value = swiper;
+    updateSnapInfo(swiper);
+  }
+  function onSlideChange() {
+    if (!swiperInstance.value) return;
+    previousIndex.value = activeIndex.value;
+    activeIndex.value = swiperInstance.value.activeIndex;
+    updateSnapInfo(swiperInstance.value);
+  }
+  function advanceSlide() {
+    if (!swiperInstance.value) return;
+    if (snapIndex.value + 1 >= totalSnaps.value) swiperInstance.value.slideTo(0);
+    else swiperInstance.value.slideNext();
+  }
+  function next() {
+    advanceSlide();
+  }
+  function prev() {
+    if (!swiperInstance.value) return;
+    const total = toValue(slides).length;
+    if (snapIndex.value <= 0) swiperInstance.value.slideTo(total - 1);
+    else swiperInstance.value.slidePrev();
+  }
+  function goTo(index) {
+    swiperInstance.value?.slideTo(index);
+  }
+  return {
+    swiperInstance,
+    activeIndex,
+    previousIndex,
+    snapIndex,
+    totalSnaps,
+    onSwiper,
+    onSlideChange,
+    advanceSlide,
+    next,
+    prev,
+    goTo
+  };
+}

package/dist/runtime/composables/_video.d.ts

@@ -0,0 +1,30 @@
+import type { Ref } from 'vue';
+import type { VideoMediaControls } from '#hero/types';
+/**
+ * Creates reactive video state management for the slider.
+ * Maintains a registry of video controls keyed by slide index and
+ * proxies the active slide's controls as computed refs with safe defaults.
+ *
+ * @param activeIndex - Currently active slide index
+ * @param videoEnabled - Whether video features are enabled
+ * @returns Video state refs and control functions
+ */
+export declare function createVideoState(activeIndex: Ref<number>, videoEnabled: boolean): {
+    activeControls: import("vue").ComputedRef<VideoMediaControls | null>;
+    videoPlaying: import("vue").ComputedRef<boolean>;
+    videoCurrentTime: import("vue").ComputedRef<number>;
+    videoDuration: import("vue").ComputedRef<number>;
+    videoBuffered: import("vue").ComputedRef<number>;
+    videoVolume: import("vue").ComputedRef<number>;
+    videoMuted: import("vue").ComputedRef<boolean>;
+    videoWaiting: import("vue").ComputedRef<boolean>;
+    videoEnded: import("vue").ComputedRef<boolean>;
+    videoToggle: () => void;
+    videoSeek: (time: number) => void;
+    videoScrubStart: () => void;
+    videoScrubEnd: () => void;
+    videoSetVolume: (v: number) => void;
+    videoToggleMute: () => void;
+    registerSlideVideo: (index: number, controls: VideoMediaControls) => void;
+    unregisterSlideVideo: (index: number) => void;
+};

package/dist/runtime/composables/_video.js

@@ -0,0 +1,89 @@
+import { computed, ref } from "vue";
+export function createVideoState(activeIndex, videoEnabled) {
+  const controlsMap = videoEnabled ? /* @__PURE__ */ new Map() : null;
+  const controlsVersion = ref(0);
+  const activeControls = computed(() => {
+    if (!controlsMap) return null;
+    void controlsVersion.value;
+    return controlsMap.get(activeIndex.value) ?? null;
+  });
+  function registerSlideVideo(index, controls) {
+    if (!controlsMap) return;
+    controlsMap.set(index, controls);
+    controlsVersion.value++;
+  }
+  function unregisterSlideVideo(index) {
+    if (!controlsMap) return;
+    controlsMap.delete(index);
+    controlsVersion.value++;
+  }
+  const videoPlaying = computed(() => activeControls.value?.playing.value ?? false);
+  const videoCurrentTime = computed(() => activeControls.value?.currentTime.value ?? 0);
+  const videoDuration = computed(() => activeControls.value?.duration.value ?? 0);
+  const videoVolume = computed(() => activeControls.value?.volume.value ?? 0);
+  const videoMuted = computed(() => activeControls.value?.muted.value ?? false);
+  const videoWaiting = computed(() => activeControls.value?.waiting.value ?? false);
+  const videoEnded = computed(() => activeControls.value?.ended.value ?? false);
+  const videoBuffered = computed(() => {
+    const controls = activeControls.value;
+    if (!controls) return 0;
+    const buffered = controls.buffered.value;
+    if (!buffered.length) return 0;
+    return buffered[buffered.length - 1]?.[1] ?? 0;
+  });
+  const wasPlayingBeforeScrub = ref(false);
+  function videoScrubStart() {
+    const c = activeControls.value;
+    if (!c) return;
+    wasPlayingBeforeScrub.value = c.playing.value;
+    if (c.playing.value) {
+      c.playing.value = false;
+    }
+  }
+  function videoScrubEnd() {
+    const c = activeControls.value;
+    if (!c) return;
+    if (wasPlayingBeforeScrub.value) {
+      c.playing.value = true;
+    }
+  }
+  function videoToggle() {
+    const c = activeControls.value;
+    if (!c) return;
+    c.playing.value = !c.playing.value;
+  }
+  function videoSeek(time) {
+    const c = activeControls.value;
+    if (!c) return;
+    c.currentTime.value = time;
+  }
+  function videoSetVolume(v) {
+    const c = activeControls.value;
+    if (!c) return;
+    c.volume.value = v;
+  }
+  function videoToggleMute() {
+    const c = activeControls.value;
+    if (!c) return;
+    c.muted.value = !c.muted.value;
+  }
+  return {
+    activeControls,
+    videoPlaying,
+    videoCurrentTime,
+    videoDuration,
+    videoBuffered,
+    videoVolume,
+    videoMuted,
+    videoWaiting,
+    videoEnded,
+    videoToggle,
+    videoSeek,
+    videoScrubStart,
+    videoScrubEnd,
+    videoSetVolume,
+    videoToggleMute,
+    registerSlideVideo,
+    unregisterSlideVideo
+  };
+}

package/dist/runtime/composables/useHeroSlider.d.ts

@@ -0,0 +1,24 @@
+import type { MaybeRefOrGetter } from 'vue';
+import type { HeroSlide, UseHeroSliderOptions, UseHeroSliderReturn } from '#hero/types';
+/**
+ * Main composable for the hero slider. Composes navigation, slides, autoplay,
+ * and video state into a single flat API.
+ *
+ * @param containerRef - Root DOM element ref (or component instance ref) for hover detection and GSAP scoping
+ * @param slides - Reactive array of slide definitions
+ * @param options - Swiper config, animation classes, and display defaults
+ * @returns Flat object with all slider state and controls
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const container = ref<HTMLElement | null>(null)
+ * const slides = [{ bgSrc: '/hero.jpg', title: 'Welcome' }]
+ * const slider = useHeroSlider(container, slides, {
+ *   swiperOptions: { autoplay: { delay: 3000 } },
+ *   enterAnimation: 'hero-fadeIn hero-animated',
+ * })
+ * </script>
+ * ```
+ */
+export declare function useHeroSlider(containerRef: MaybeRefOrGetter<HTMLElement | null>, slides: MaybeRefOrGetter<HeroSlide[]>, options?: UseHeroSliderOptions): UseHeroSliderReturn;