astro-scroll-transition 0.0.1

package/README.md

@@ -0,0 +1,66 @@
+# Astro Scroll Transition
+
+A scroll-driven image transition component for Astro. Import the `.astro` component, provide an ordered list of images, and add matching named slots for the content shown with each image.
+
+## Install
+
+```sh
+npm install astro-scroll-transition
+```
+
+Astro is a peer dependency and must be installed in the consuming project.
+
+## Use
+
+```astro
+---
+import Transition from "astro-scroll-transition/Transition.astro";
+import firstImage from "../assets/first.jpg";
+import secondImage from "../assets/second.jpg";
+import thirdImage from "../assets/third.jpg";
+---
+
+<Transition
+  images={[firstImage, secondImage, thirdImage]}
+  transitionDistance="75vh"
+  transitionHold="25vh"
+>
+  <section slot="content-0"><h2>First scene</h2></section>
+  <section slot="content-1"><h2>Second scene</h2></section>
+  <section slot="content-2"><h2>Third scene</h2></section>
+</Transition>
+```
+
+Slots are named `content-0`, `content-1`, and so on, matching the order of the `images` array. Images may be imported assets or image URLs supported by Astro's [image service](https://docs.astro.build/en/guides/images/).
+
+### Props
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `images` | `[]` | Ordered image sources for the transition. |
+| `transitionDistance` | `75vh` | Scroll distance used to fade between adjacent images. |
+| `transitionHold` | `25vh` | Scroll distance to hold each image before the next fade. |
+| `scrollStartHeight` | `0vh` | Scroll spacing before the first transition. |
+| `scrollEndHeight` | `0vh` | Scroll spacing after the last transition. |
+| `containerHeight` | calculated | Optional explicit height for the component wrapper. Otherwise derived from the viewport and transition props. |
+
+## Run the demo locally
+
+The repository root is also a standalone Astro demo site. It imports the component through the package export, so the demo exercises the same import path used by consumers.
+
+```sh
+npm install
+npm run demo
+```
+
+Astro starts the demo at `http://localhost:4321`. Build and preview the demo with `npm run build` and `npm run preview`.
+
+## Package and publish
+
+Before publishing, ensure the `name` in `package.json` is available on npm. Preview the exact contents of the package tarball with:
+
+```sh
+npm pack --dry-run
+```
+
+The published package contains the component and this README. `npm publish` runs the demo production build first through the `prepublishOnly` script.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "astro-scroll-transition",
+  "description": "Scroll-driven image transitions for Astro.",
+  "type": "module",
+  "version": "0.0.1",
+  "exports": {
+    "./Transition.astro": "./src/components/Transition.astro"
+  },
+  "files": [
+    "src/components/Transition.astro",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "demo": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "prepublishOnly": "npm run build",
+    "pack:dry-run": "npm pack --dry-run",
+    "astro": "astro"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  },
+  "devDependencies": {
+    "astro": "^7.3.2"
+  },
+  "allowScripts": {
+    "esbuild": true
+  }
+}

package/src/components/Transition.astro

@@ -0,0 +1,193 @@
+---
+import { Image } from "astro:assets";
+
+const {
+  // Scroll distance before the first image transition begins.
+  scrollStartHeight = "0vh",
+  // Scroll distance after the final image transition ends.
+  scrollEndHeight = "0vh",
+  // Optional explicit wrapper height; otherwise it is calculated from the other props.
+  containerHeight,
+  // Image paths shown in sequence during the scroll transition.
+  images = [],
+  // Scroll distance spent holding each image before the next fade begins.
+  transitionHold = "25vh",
+  // Scroll distance used to fade from one image to the next.
+  transitionDistance = "75vh",
+} = Astro.props;
+
+const transitionCount = Math.max(images.length - 1, 0);
+const dynamicContainerHeight =
+  containerHeight ??
+  `calc(100vh + ${scrollStartHeight} + ${transitionCount} * (${transitionDistance} + ${transitionHold}) + ${scrollEndHeight})`;
+
+const getImageName = (imagePath: string) => {
+  const pathWithoutQuery = imagePath.split(/[?#]/)[0];
+  const fileName = pathWithoutQuery.split("/").pop() ?? "image";
+
+  return fileName.replace(/\.[^/.]+$/, "");
+};
+---
+
+<div
+  class="transition-wrapper"
+  data-scroll-start-height={scrollStartHeight}
+  data-scroll-end-height={scrollEndHeight}
+  data-transition-hold={transitionHold}
+  data-transition-distance={transitionDistance}
+  style={`height: ${dynamicContainerHeight};`}
+>
+  {
+    images.map((imagePath: string, index: number) => (
+      <div
+        class="content"
+        id={`content-${getImageName(imagePath)}-${index}`}
+        style={`--content-index: ${index}; --scroll-start: ${scrollStartHeight}; --transition-distance: ${transitionDistance}; --transition-hold: ${transitionHold};`}
+      >
+        <slot name={`content-${index}`} />
+      </div>
+    ))
+  }
+
+  {
+    images.map((imagePath: string) => (
+      <Image
+        class="transition-image"
+        src={imagePath}
+        alt=""
+        width={600}
+        height={400}
+      />
+    ))
+  }
+</div>
+
+<script>
+  const transitionWrapper = document.querySelector<HTMLElement>(
+    ".transition-wrapper",
+  );
+  const transitionImages = Array.from(
+    document.querySelectorAll<HTMLElement>(".transition-image"),
+  );
+  const transitionContent = Array.from(
+    document.querySelectorAll<HTMLElement>(".content"),
+  );
+
+  const scrollStartHeight =
+    transitionWrapper?.dataset.scrollStartHeight || "100vh";
+  const scrollEndHeight = transitionWrapper?.dataset.scrollEndHeight || "100vh";
+
+  const getHeightInPixels = (height: string) => {
+    if (height.endsWith("vh")) {
+      return (Number.parseFloat(height) / 100) * window.innerHeight;
+    }
+
+    if (height.endsWith("vw")) {
+      return (Number.parseFloat(height) / 100) * window.innerWidth;
+    }
+
+    return Number.parseFloat(height);
+  };
+
+  const transitionHold = Math.max(
+    getHeightInPixels(transitionWrapper?.dataset.transitionHold || "0"),
+    0,
+  );
+  const transitionDistance = Math.max(
+    getHeightInPixels(transitionWrapper?.dataset.transitionDistance || "100vh"),
+    0,
+  );
+
+  const updateOpacity = () => {
+    if (!transitionWrapper || transitionImages.length === 0) return;
+
+    const section = transitionWrapper.getBoundingClientRect();
+    const scrollRange = transitionWrapper.offsetHeight - window.innerHeight;
+    const startOffset = getHeightInPixels(scrollStartHeight);
+    const endOffset = getHeightInPixels(scrollEndHeight);
+    const animationRange = Math.max(scrollRange - startOffset - endOffset, 0);
+    const animationProgress = animationRange
+      ? (-section.top - startOffset) / animationRange
+      : 0;
+    const scrollPercent = Math.min(Math.max(animationProgress, 0), 1);
+    const transitionCount = transitionImages.length - 1;
+    const fadeDistance = transitionCount ? transitionDistance : 0;
+    const segmentDistance = fadeDistance + transitionHold;
+    const scrollDistance = scrollPercent * animationRange;
+    const imageProgress = segmentDistance
+      ? scrollDistance / segmentDistance
+      : 0;
+    const transitionIndex = Math.min(
+      Math.floor(imageProgress),
+      transitionImages.length - 2,
+    );
+    const segmentProgress = segmentDistance
+      ? scrollDistance - transitionIndex * segmentDistance
+      : 0;
+    const imagePosition =
+      transitionImages.length === 1
+        ? 0
+        : segmentProgress < fadeDistance && fadeDistance
+          ? transitionIndex + segmentProgress / fadeDistance
+          : transitionIndex + 1;
+
+    const imageOpacities = transitionImages.map((_, index) =>
+      Math.max(1 - Math.abs(imagePosition - index), 0),
+    );
+
+    transitionImages.forEach((image, index) => {
+      image.style.opacity = `${imageOpacities[index]}`;
+    });
+
+    const activeContentIndex = Math.min(
+      Math.max(Math.round(imagePosition), 0),
+      transitionContent.length - 1,
+    );
+
+    transitionContent.forEach((content, index) => {
+      const isActive = index === activeContentIndex;
+      content.classList.toggle("active", isActive);
+      content.style.zIndex = isActive ? "2" : "1";
+      content.style.pointerEvents = isActive ? "auto" : "none";
+      content.inert = !isActive;
+      content.setAttribute("aria-hidden", `${!isActive}`);
+    });
+  };
+
+  window.addEventListener("scroll", updateOpacity, { passive: true });
+  updateOpacity();
+</script>
+
+<style>
+  .transition-wrapper {
+    position: relative;
+    display: grid;
+
+    .transition-image {
+      position: sticky;
+      top: 0;
+      width: 100%;
+      height: 100vh;
+      object-fit: cover;
+      grid-area: 1 / 1;
+      align-self: start;
+      z-index: 0;
+    }
+
+    .content {
+      grid-area: 1 / 1;
+      z-index: 1;
+      position: relative;
+      pointer-events: none;
+      padding-top: calc(
+        var(--scroll-start) + var(--content-index) *
+          (var(--transition-distance) + var(--transition-hold))
+      );
+
+      &.active {
+        z-index: 2;
+        pointer-events: auto;
+      }
+    }
+  }
+</style>