nuxt-hero 0.1.0

package/dist/runtime/composables/useHeroSlider.js

@@ -0,0 +1,131 @@
+import { computed, toValue, watch } from "vue";
+import { useElementHover } from "@vueuse/core";
+import { createSwiperState } from "./_swiper.js";
+import { createSlideState } from "./_slides.js";
+import { createAutoplayState } from "./_autoplay.js";
+import { createVideoState } from "./_video.js";
+function resolveElement(source) {
+  const raw = toValue(source);
+  if (!raw) return null;
+  if (raw.$el) return raw.$el;
+  if (raw instanceof HTMLElement) return raw;
+  return null;
+}
+export function useHeroSlider(containerRef, slides, options = {}) {
+  const {
+    swiperOptions = {},
+    enterAnimation = "",
+    leaveAnimation = "",
+    showPagination,
+    showNavigation,
+    showProgress,
+    showVideoControls
+  } = options;
+  const mergedSwiperOptions = computed(() => {
+    const { autoplay: autoplay2, ...userOpts } = swiperOptions;
+    return {
+      slidesPerView: 1,
+      spaceBetween: 0,
+      grabCursor: true,
+      ...userOpts,
+      autoplay: false
+    };
+  });
+  const isMultiSlide = computed(() => {
+    const spv = mergedSwiperOptions.value.slidesPerView;
+    return spv === "auto" || typeof spv === "number" && spv > 1;
+  });
+  const videoEnabled = true;
+  const swiper = createSwiperState(slides);
+  const slideState = createSlideState(
+    slides,
+    swiper.activeIndex,
+    swiper.previousIndex,
+    { showPagination, showNavigation, showProgress, showVideoControls },
+    videoEnabled,
+    enterAnimation,
+    leaveAnimation
+  );
+  const resolvedContainer = computed(() => resolveElement(containerRef));
+  const isHovered = useElementHover(resolvedContainer);
+  const autoplay = createAutoplayState(
+    swiper.advanceSlide,
+    slideState.isActiveSlideVideo,
+    isHovered,
+    options
+  );
+  const video = createVideoState(swiper.activeIndex, videoEnabled);
+  const autoplayProgress = computed(() => {
+    const controls = video.activeControls.value;
+    if (controls && controls.duration.value > 0) {
+      return Math.min(controls.currentTime.value / controls.duration.value, 1);
+    }
+    return autoplay.autoplayProgress.value;
+  });
+  if (videoEnabled) {
+    watch(
+      () => video.videoEnded.value,
+      (ended) => {
+        if (!ended) return;
+        if (!autoplay.autoplayEnabled) return;
+        if (slideState.activeSlideConfig.value.videoLoop) return;
+        if (!isHovered.value) {
+          swiper.advanceSlide();
+        }
+      }
+    );
+  }
+  function onSlideChange() {
+    swiper.onSlideChange();
+    autoplay.onSlideChange();
+  }
+  return {
+    // Navigation
+    next: swiper.next,
+    prev: swiper.prev,
+    goTo: swiper.goTo,
+    // Slide state
+    activeIndex: swiper.activeIndex,
+    snapIndex: swiper.snapIndex,
+    totalSnaps: swiper.totalSnaps,
+    activeSlide: slideState.activeSlide,
+    activeSlideConfig: slideState.activeSlideConfig,
+    isActiveSlideVideo: slideState.isActiveSlideVideo,
+    isMultiSlide,
+    animationClass: (index) => isMultiSlide.value ? "" : slideState.animationClass(index),
+    // Autoplay
+    autoplayEnabled: autoplay.autoplayEnabled,
+    autoplayProgress,
+    autoplayRemaining: autoplay.autoplayRemaining,
+    autoplayDelay: autoplay.autoplayDelay,
+    autoplayPaused: autoplay.autoplayPaused,
+    autoplayPause: autoplay.autoplayPause,
+    autoplayResume: autoplay.autoplayResume,
+    autoplayReset: autoplay.autoplayReset,
+    autoplaySetDelay: autoplay.autoplaySetDelay,
+    // Video
+    videoPlaying: video.videoPlaying,
+    videoCurrentTime: video.videoCurrentTime,
+    videoDuration: video.videoDuration,
+    videoBuffered: video.videoBuffered,
+    videoVolume: video.videoVolume,
+    videoMuted: video.videoMuted,
+    videoWaiting: video.videoWaiting,
+    videoEnded: video.videoEnded,
+    videoToggle: video.videoToggle,
+    videoSeek: video.videoSeek,
+    videoScrubStart: video.videoScrubStart,
+    videoScrubEnd: video.videoScrubEnd,
+    videoSetVolume: video.videoSetVolume,
+    videoToggleMute: video.videoToggleMute,
+    // Hover
+    isHovered,
+    // Swiper options (merged)
+    mergedSwiperOptions,
+    // Internal bindings
+    onSwiper: swiper.onSwiper,
+    onSlideChange,
+    registerSlideVideo: video.registerSlideVideo,
+    unregisterSlideVideo: video.unregisterSlideVideo
+  };
+}

package/dist/runtime/hero-swiper-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '#hero/swiper-modules' {
+  import type { SwiperModule } from 'swiper/types'
+  export const swiperModules: SwiperModule[]
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,221 @@
+import type { SwiperOptions } from 'swiper/types';
+import type { useMediaControls } from '@vueuse/core';
+import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+/** Extracted from VueUse's useMediaControls second parameter */
+export type MediaControlsOptions = NonNullable<Parameters<typeof useMediaControls>[1]>;
+export type SwiperEffect = 'fade' | 'cube' | 'coverflow' | 'creative' | 'cards' | 'flip';
+export interface HeroFeatures {
+    navigation?: boolean;
+    pagination?: boolean;
+    mousewheel?: boolean;
+    keyboard?: boolean;
+    a11y?: boolean;
+    freeMode?: boolean;
+    thumbs?: boolean;
+    grid?: boolean;
+    zoom?: boolean;
+    scrollbar?: boolean;
+    controller?: boolean;
+    virtual?: boolean;
+    hashNavigation?: boolean;
+    history?: boolean;
+    effects?: SwiperEffect[];
+    /** GSAP scroll-based parallax (ScrollTrigger) */
+    parallax?: boolean;
+    /** Swiper slide-transition parallax module */
+    swiperParallax?: boolean;
+    /** Video backgrounds + useMediaControls */
+    video?: boolean;
+    /** HLS streaming (lazy hls.js import). Requires video: true */
+    hls?: boolean;
+}
+export interface SlideAnimation {
+    /** animate.css class for content entering. e.g. 'animate__fadeInUp' */
+    enter?: string;
+    /** animate.css class for content leaving. e.g. 'animate__fadeOutDown' */
+    leave?: string;
+}
+export interface SlideConfig {
+    /** Show pagination dots when this slide is active. Default: inherited from HeroSliderProps */
+    showPagination?: boolean;
+    /** Show navigation arrows when this slide is active. Default: inherited from HeroSliderProps */
+    showNavigation?: boolean;
+    /** Show progress bar / video scrubber when this slide is active. Default: inherited from HeroSliderProps */
+    showProgress?: boolean;
+    /** Show video controls when this slide is active (video slides only). Default: inherited from HeroSliderProps */
+    showVideoControls?: boolean;
+    /** Loop video playback. When false, auto-advances to next slide on video end. Default: false */
+    videoLoop?: boolean;
+    /** VueUse useMediaControls options passed through to the video element. @see https://vueuse.org/core/useMediaControls/ */
+    mediaControlsOptions?: MediaControlsOptions;
+}
+/** Resolved slide config with boolean defaults applied */
+export interface ResolvedSlideConfig {
+    showPagination: boolean;
+    showNavigation: boolean;
+    showProgress: boolean;
+    showVideoControls: boolean;
+    videoLoop: boolean;
+    mediaControlsOptions?: MediaControlsOptions;
+}
+export interface HeroSlide {
+    /** Background image or video URL (auto-detected from extension) */
+    bgSrc: string;
+    /** Dark-mode alternative (falls back to bgSrc) */
+    bgDarkSrc?: string;
+    /** Thumbnail for pagination tooltip / navigation preview */
+    thumbSrc?: string;
+    /** Slide title (used in nav-slit preview) */
+    title?: string;
+    /** Poster frame for video backgrounds */
+    poster?: string;
+    /** Per-slide animation config (overrides global enterAnimation/leaveAnimation) */
+    animation?: SlideAnimation;
+    /** Per-slide display & media config (overrides global HeroSliderProps defaults) */
+    config?: SlideConfig;
+    /** Any extra data the consumer needs in the slot */
+    [key: string]: unknown;
+}
+export type OverlayPatternType = 'lines' | 'dots' | 'gradient' | 'custom';
+export interface OverlayPattern {
+    /** Pattern type */
+    type: OverlayPatternType;
+    /** Pattern opacity (0-1). Default: 0.15 */
+    opacity?: number;
+    /** Pattern color. Default: 'black' */
+    color?: string;
+    /** Custom CSS background-image value (only for type: 'custom') */
+    css?: string;
+}
+export interface ParallaxConfig {
+    /** Enable parallax on background image/video. Default: true */
+    bg?: boolean;
+    /** Enable parallax on content container. Default: true */
+    content?: boolean;
+    /** Parallax speed multiplier. Default: 0.125 */
+    speed?: number;
+    /** Minimum opacity percentage (0-1). Default: 0.7 */
+    minOpacity?: number;
+}
+export interface HeroSliderUI {
+    /** Root wrapper element */
+    root?: string;
+    /** Swiper container */
+    swiper?: string;
+    /** Each SwiperSlide */
+    slide?: string;
+    /** Slide inner container (.hero-slide) */
+    container?: string;
+    /** Slide background layer (.hero-slide-bg) */
+    bg?: string;
+    /** UI controls overlay layer (pagination, navigation, progress) */
+    controls?: string;
+    /** Autoplay progress bar track */
+    progress?: string;
+}
+export interface HeroSliderProps {
+    /** Array of slides */
+    slides: HeroSlide[];
+    /** Composable return value — makes HeroSlider a controlled component */
+    slider: UseHeroSliderReturn;
+    /** Default animation class for content entering */
+    enterAnimation?: string;
+    /** Default animation class for content leaving */
+    leaveAnimation?: string;
+    /** Stacked overlay patterns on top of each slide background */
+    overlayPatterns?: OverlayPattern[];
+    /** Parallax config - pass false to disable, true for defaults, object for fine control */
+    parallax?: MaybeRefOrGetter<boolean | ParallaxConfig>;
+    /** @nuxt/image preset name for slide backgrounds */
+    imagePreset?: string;
+    /** Wrapper element tag. Default: 'div' */
+    as?: string;
+    /** Class overrides for internal elements (Nuxt UI-style) */
+    ui?: HeroSliderUI;
+}
+export interface UseHeroSliderOptions {
+    /**
+     * Swiper configuration passed through to the `<Swiper>` component.
+     *
+     * Every standard Swiper option is accepted — `slidesPerView`, `spaceBetween`,
+     * `centeredSlides`, `loop`, `effect`, `speed`, `breakpoints`, etc.
+     *
+     * **Autoplay:** The `autoplay.delay` value configures the built-in progress
+     * timer (default 5000ms). Swiper's native autoplay is always disabled;
+     * the composable manages slide advancement and progress tracking internally.
+     *
+     * **Mousewheel:** Set `mousewheel: true` (or an options object) and the
+     * Mousewheel Swiper module is auto-registered — no manual import needed.
+     *
+     * **Vertical direction:** Set `direction: 'vertical'` and the UI adapts:
+     * - Pagination moves to the side (right in LTR, left in RTL)
+     * - Navigation: prev on top, next on bottom
+     * - Progress bar renders vertically on the side
+     */
+    swiperOptions?: SwiperOptions;
+    enterAnimation?: string;
+    leaveAnimation?: string;
+    /** Show pagination dots. Default: true. Can be overridden per-slide via slide.config */
+    showPagination?: boolean;
+    /** Show navigation arrows. Default: true. Can be overridden per-slide via slide.config */
+    showNavigation?: boolean;
+    /** Show progress bar / video scrubber. Default: true. Can be overridden per-slide via slide.config */
+    showProgress?: boolean;
+    /** Show video controls overlay. Default: true. Can be overridden per-slide via slide.config */
+    showVideoControls?: boolean;
+}
+export interface UseHeroSliderReturn {
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    activeIndex: Ref<number>;
+    snapIndex: Ref<number>;
+    totalSnaps: Ref<number>;
+    activeSlide: ComputedRef<HeroSlide>;
+    activeSlideConfig: ComputedRef<ResolvedSlideConfig>;
+    isActiveSlideVideo: ComputedRef<boolean>;
+    /** True when slidesPerView > 1 (or 'auto') — disables content animations */
+    isMultiSlide: ComputedRef<boolean>;
+    animationClass: (index: number) => string;
+    autoplayEnabled: boolean;
+    autoplayProgress: ComputedRef<number>;
+    autoplayRemaining: ComputedRef<number>;
+    autoplayDelay: Ref<number>;
+    autoplayPaused: Ref<boolean>;
+    autoplayPause: () => void;
+    autoplayResume: () => void;
+    autoplayReset: () => void;
+    autoplaySetDelay: (ms: number) => void;
+    videoPlaying: ComputedRef<boolean>;
+    videoCurrentTime: ComputedRef<number>;
+    videoDuration: ComputedRef<number>;
+    videoBuffered: ComputedRef<number>;
+    videoVolume: ComputedRef<number>;
+    videoMuted: ComputedRef<boolean>;
+    videoWaiting: ComputedRef<boolean>;
+    videoEnded: ComputedRef<boolean>;
+    videoToggle: () => void;
+    videoSeek: (time: number) => void;
+    /** Call when scrubber drag starts — pauses video, remembers play state */
+    videoScrubStart: () => void;
+    /** Call when scrubber drag ends — resumes if was playing before scrub */
+    videoScrubEnd: () => void;
+    videoSetVolume: (v: number) => void;
+    videoToggleMute: () => void;
+    isHovered: Ref<boolean>;
+    mergedSwiperOptions: ComputedRef<Record<string, unknown>>;
+    onSwiper: (swiper: any) => void;
+    onSlideChange: () => void;
+    registerSlideVideo: (index: number, controls: VideoMediaControls) => void;
+    unregisterSlideVideo: (index: number) => void;
+}
+export interface VideoMediaControls {
+    playing: Ref<boolean>;
+    currentTime: Ref<number>;
+    duration: Ref<number>;
+    buffered: Ref<[number, number][]>;
+    volume: Ref<number>;
+    muted: Ref<boolean>;
+    waiting: Ref<boolean>;
+    ended: Ref<boolean>;
+}

package/dist/runtime/utils.d.ts

@@ -0,0 +1,22 @@
+import type { OverlayPattern, ParallaxConfig } from './types.js';
+/** Check if a URL points to a video file based on extension (.mp4, .webm, .mov, .ogg, .m3u8) */
+export declare function isVideoUrl(url: string): boolean;
+/** Check if a URL points to an HLS stream (.m3u8) */
+export declare function isHlsUrl(url: string): boolean;
+/** Generate CSS background-image for a pattern */
+export declare function patternCSS(pattern: OverlayPattern): string;
+/** Get the CSS background-size value appropriate for a pattern type */
+export declare function patternSize(pattern: OverlayPattern): string;
+/** Default parallax config */
+export declare const DEFAULT_PARALLAX: Required<ParallaxConfig>;
+/**
+ * Resolve a parallax prop value to a full config object.
+ * `false` disables all parallax, `true` uses defaults, objects are merged with defaults.
+ */
+export declare function resolveParallaxConfig(value: boolean | ParallaxConfig): Required<ParallaxConfig>;
+/** Format seconds as MM:SS */
+export declare function formatTime(seconds: number): string;
+/** Safely extract hero config from Nuxt runtime config */
+export declare function getHeroConfig(runtimeConfig: {
+    public: Record<string, unknown>;
+}): Record<string, any>;

package/dist/runtime/utils.js

@@ -0,0 +1,50 @@
+const VIDEO_EXTENSIONS = /\.(mp4|webm|mov|ogg|m3u8)(\?|$)/i;
+const HLS_EXTENSIONS = /\.(m3u8)(\?|$)/i;
+export function isVideoUrl(url) {
+  return VIDEO_EXTENSIONS.test(url);
+}
+export function isHlsUrl(url) {
+  return HLS_EXTENSIONS.test(url);
+}
+export function patternCSS(pattern) {
+  const color = pattern.color ?? "black";
+  switch (pattern.type) {
+    case "lines":
+      return `repeating-linear-gradient(45deg, ${color} 25%, transparent 25%, transparent 75%, ${color} 75%, ${color}), repeating-linear-gradient(45deg, ${color} 25%, transparent 25%, transparent 75%, ${color} 75%, ${color})`;
+    case "dots":
+      return `radial-gradient(circle, ${color} 1px, transparent 1px)`;
+    case "gradient":
+      return `radial-gradient(circle at 55% 60%, #00aaff, #002aff, rgba(144,143,255,1))`;
+    case "custom":
+      return pattern.css ?? "";
+  }
+}
+export function patternSize(pattern) {
+  switch (pattern.type) {
+    case "lines":
+      return "2px 2px";
+    case "dots":
+      return "20px 20px";
+    default:
+      return "cover";
+  }
+}
+export const DEFAULT_PARALLAX = {
+  bg: true,
+  content: true,
+  speed: 0.125,
+  minOpacity: 0.7
+};
+export function resolveParallaxConfig(value) {
+  if (value === false) return { bg: false, content: false, speed: 0, minOpacity: 1 };
+  if (value === true) return { ...DEFAULT_PARALLAX };
+  return { ...DEFAULT_PARALLAX, ...value };
+}
+export function formatTime(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = Math.floor(seconds % 60);
+  return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
+}
+export function getHeroConfig(runtimeConfig) {
+  return runtimeConfig.public.hero ?? {};
+}

package/dist/types.d.mts

@@ -0,0 +1,9 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'
+
+export { type HeroModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "nuxt-hero",
+  "version": "0.1.0",
+  "description": "A full-featured hero slider Nuxt module with parallax, video backgrounds, overlay patterns, and customizable animations.",
+  "license": "MIT",
+  "author": "weskhaled",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weskhaled/nuxt-hero.git"
+  },
+  "homepage": "https://github.com/weskhaled/nuxt-hero#readme",
+  "bugs": {
+    "url": "https://github.com/weskhaled/nuxt-hero/issues"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "hero",
+    "slider",
+    "parallax",
+    "video",
+    "swiper",
+    "gsap",
+    "tailwindcss"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "build": "nuxt-module-build build",
+    "prepare": "nuxt-module-build build --stub",
+    "prepack": "nuxt-module-build build",
+    "typecheck": "nuxi typecheck playground",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "lint:all": "oxlint . && pnpm typecheck"
+  },
+  "dependencies": {
+    "@nuxt/icon": "^2.2.1",
+    "@nuxt/kit": "^4.4.2",
+    "gsap": "^3.14.2"
+  },
+  "peerDependencies": {
+    "@nuxt/image": ">=2.0.0",
+    "@nuxtjs/color-mode": "^4.0.0",
+    "@tailwindcss/vite": "^4.2.2",
+    "@vueuse/core": "^14.2.1",
+    "@vueuse/nuxt": ">=14.2.1",
+    "animate.css": "^4.1.1",
+    "hls.js": "^1.5.0",
+    "swiper": "^11.0.0 || ^12.0.0",
+    "tailwindcss": "^4.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@nuxt/image": {
+      "optional": true
+    },
+    "animate.css": {
+      "optional": true
+    },
+    "hls.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@iconify-json/lucide": "^1.2.101",
+    "@nuxt/image": "^2.0.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/test-utils": "^3.17.0",
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/node": "^25.6.0",
+    "animate.css": "^4.1.1",
+    "hls.js": "^1.6.2",
+    "nuxt": "^4.4.2",
+    "oxlint": "^1.59.0",
+    "swiper": "^12.1.0",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4",
+    "vue-tsc": "^3.2.6"
+  }
+}