astro-reveal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Picoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# astro-reveal
+
+Scroll reveal animations for [Astro](https://astro.build) — smooth slide-ins, fades, scales — that work with **any** UI framework or no framework at all.
+
+- **Zero runtime JS by default.** Uses native CSS [scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline). In purist mode your page ships a single stylesheet and nothing else.
+- **Opt-in JS engine** (`mode: "observer"`) when you want the classic "reveal once and stay" behaviour and universal browser support — about **0.6 KB** gzipped.
+- **UI-agnostic.** Astro outputs HTML in the end, so the same `data-reveal` attribute animates content whether it came from a React, Vue, Svelte island, or plain HTML.
+- **FOUC-proof and accessible by design.** No flash of hidden content, and `prefers-reduced-motion` is respected out of the box.
+- **Plays nice with View Transitions** and late-hydrating islands.
+
+It's the [AOS](https://github.com/michalsnik/aos) idea, rebuilt for the Astro era.
+
+## Install
+
+```sh
+npx astro add astro-reveal
+```
+
+Or manually:
+
+```sh
+npm install astro-reveal
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import reveal from "astro-reveal";
+
+export default defineConfig({
+  integrations: [reveal()],
+});
+```
+
+That's it. The integration injects the stylesheet for you — no manual CSS import needed.
+
+## Usage
+
+Use the component:
+
+```astro
+---
+import Reveal from "astro-reveal/Reveal.astro";
+---
+<Reveal animation="up">
+  <h1>I rise into place as you scroll.</h1>
+</Reveal>
+
+<Reveal animation="scale" distance="3rem" as="section">
+  <p>Render as any tag with `as`.</p>
+</Reveal>
+```
+
+Or the raw attribute (works on anything, including markup from other frameworks):
+
+```html
+<div data-reveal="fade">Hello</div>
+<img data-reveal="left" src="/photo.jpg" alt="" />
+```
+
+### Animations
+
+| Value   | Effect                                  |
+| ------- | --------------------------------------- |
+| `up`    | rises into place (starts below)         |
+| `down`  | drops into place (starts above)         |
+| `left`  | slides left (starts to the right)       |
+| `right` | slides right (starts to the left)       |
+| `fade`  | opacity only                            |
+| `scale` | scales up from slightly smaller         |
+| `blur`  | un-blurs into focus                     |
+
+## The two engines
+
+You pick the engine; the API stays identical.
+
+| `mode`               | Runtime JS | Behaviour                          | Browser support                             |
+| -------------------- | ---------- | ---------------------------------- | ------------------------------------------- |
+| `"scroll"` (default) | **none**   | scrubbed — reverses on scroll up   | animates where supported, static elsewhere  |
+| `"observer"`         | ~0.6 KB    | plays **once** and stays           | everywhere                                  |
+| `"auto"`             | ~0.6 KB    | native where supported, JS fallback | identical everywhere                        |
+
+```js
+reveal({ mode: "observer" }); // the "on steroids" mode
+```
+
+Why this matters: in `"scroll"` mode the hidden ("from") state only exists inside an `@supports (animation-timeline: view())` block. A browser that can't animate it **never hides the content** — so there is no flash and nothing can get stuck invisible. The trade-off is that scroll-driven animations are *scrubbed*: scroll back up and they play in reverse. If you want "appear once and stay put", switch to `"observer"`.
+
+## Options
+
+```ts
+reveal({
+  mode: "scroll",                  // "scroll" | "observer" | "auto"
+  once: true,                      // observer/auto: reveal once and keep it
+  threshold: 0.15,                 // observer/auto: IntersectionObserver threshold
+  rootMargin: "0px 0px -10% 0px",  // observer/auto: fire slightly before the fold
+});
+```
+
+## Customisation
+
+Tune per element with CSS custom properties (via the component or inline style):
+
+```html
+<div data-reveal="up" style="--reveal-distance: 4rem; --reveal-duration: 1s;"></div>
+```
+
+| Variable             | Default                        | Applies to        |
+| -------------------- | ------------------------------ | ----------------- |
+| `--reveal-distance`  | `1.5rem`                       | up/down/left/right |
+| `--reveal-scale`     | `0.94`                         | scale             |
+| `--reveal-blur`      | `8px`                          | blur              |
+| `--reveal-duration`  | `700ms`                        | observer mode     |
+| `--reveal-easing`    | `cubic-bezier(.16,1,.3,1)`     | observer mode     |
+| `--reveal-index`     | `0`                            | stagger position  |
+| `--reveal-stagger`   | `90ms`                         | observer mode     |
+
+Set them globally by targeting `[data-reveal]` in your own CSS. Everything ships inside `@layer astro-reveal`, so your styles always win without specificity battles.
+
+### Stagger
+
+```astro
+{items.map((item, i) => <Reveal animation="up" index={i}>{item}</Reveal>)}
+```
+
+In `observer` mode each item gets `transition-delay: index * --reveal-stagger` for a crisp cascade. In `scroll` mode stagger is approximated by nudging each item's scroll range (grouped staggers are crisper in `observer` mode).
+
+## Accessibility
+
+Users with `prefers-reduced-motion: reduce` see content in its final state immediately, in every mode. This is built into the CSS, not bolted on — there's no configuration to forget.
+
+## Browser support
+
+Native scroll-driven animations (`animation-timeline: view()`) ship in Chromium-based browsers. Firefox and Safari support has been moving — **check [caniuse.com/css-scroll-timeline](https://caniuse.com/?search=animation-timeline) for the current state** before relying on purist mode for a specific audience.
+
+- If you target only modern Chromium → `"scroll"` (zero JS).
+- If you need identical behaviour everywhere → `"auto"` (native where it can, JS where it can't).
+- If you specifically want "reveal once and stay" → `"observer"`.
+
+## How it works
+
+A tiny head-inline script (only injected in `observer`/`auto` modes) decides which engine runs by toggling a single `reveal-js` class on `<html>` before paint. The two CSS rule sets — one scoped to `html:not(.reveal-js)` (native), one to `html.reveal-js` (JS) — are therefore mutually exclusive by construction. No double-animating, no race conditions.
+
+## License
+
+MIT © Nicolás Picotto

package/Reveal.astro

@@ -0,0 +1,54 @@
+---
+/*
+ * <Reveal> — ergonomic wrapper over the `data-reveal` attribute.
+ * Works the same under both engines because it only sets the attribute and a
+ * few CSS custom properties; the integration's CSS/JS does the rest.
+ *
+ *   <Reveal animation="up">…</Reveal>
+ *   <Reveal animation="scale" distance="3rem" index={2} as="section">…</Reveal>
+ *
+ * For raw HTML (no component), just use the attribute directly:
+ *   <div data-reveal="fade">…</div>
+ */
+export type RevealAnimation = "up" | "down" | "left" | "right" | "fade" | "scale" | "blur";
+
+interface Props {
+  /** Direction the element travels as it appears. @default "up" */
+  animation?: RevealAnimation;
+  /** Element/tag to render. @default "div" */
+  as?: string;
+  /** Travel distance (up/down/left/right) e.g. "2rem". */
+  distance?: string;
+  /** Stagger position within a group (0,1,2,…). */
+  index?: number;
+  /** Transition duration in observer mode, e.g. "500ms". */
+  duration?: string;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const {
+  animation = "up",
+  as: Tag = "div",
+  distance,
+  index,
+  duration,
+  class: className,
+  style: userStyle,
+  ...rest
+} = Astro.props;
+
+const vars = [
+  distance ? `--reveal-distance:${distance}` : "",
+  index != null ? `--reveal-index:${index}` : "",
+  duration ? `--reveal-duration:${duration}` : "",
+]
+  .filter(Boolean)
+  .join(";");
+
+const style = [vars, userStyle].filter(Boolean).join(";") || undefined;
+---
+
+<Tag data-reveal={animation} class={className} style={style} {...rest}>
+  <slot />
+</Tag>

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { AstroIntegration } from "astro";
+export type RevealMode = "scroll" | "observer" | "auto";
+export interface RevealOptions {
+    /**
+     * Which engine to use.
+     *  - "scroll"   (default) Native CSS scroll-driven animations. Zero runtime
+     *               JS. Scrubbed: reverses as you scroll back up. Browsers
+     *               without support show content normally (no animation, no FOUC).
+     *  - "observer" IntersectionObserver. ~1KB JS. Plays once and stays. Works
+     *               everywhere. This is the "on steroids" mode.
+     *  - "auto"     Native where supported, falls back to observer where not, so
+     *               it looks identical across browsers (always ships the ~1KB).
+     * @default "scroll"
+     */
+    mode?: RevealMode;
+    /**
+     * Observer/auto only. Reveal once and keep it revealed (true), or re-hide
+     * when the element leaves the viewport (false).
+     * @default true
+     */
+    once?: boolean;
+    /**
+     * Observer/auto only. IntersectionObserver threshold.
+     * @default 0.15
+     */
+    threshold?: number;
+    /**
+     * Observer/auto only. IntersectionObserver rootMargin. The default trims the
+     * bottom so reveals fire slightly before the element hits the fold.
+     * @default "0px 0px -10% 0px"
+     */
+    rootMargin?: string;
+}
+export default function astroReveal(options?: RevealOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+// Read our own package name so injected imports keep resolving even if the
+// package is renamed/forked. (dist/index.js -> ../package.json = package root.)
+const PKG = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+const DEFAULTS = {
+    mode: "scroll",
+    once: true,
+    threshold: 0.15,
+    rootMargin: "0px 0px -10% 0px",
+};
+function headInline(opts) {
+    const runtime = {
+        mode: opts.mode,
+        once: opts.once,
+        threshold: opts.threshold,
+        rootMargin: opts.rootMargin,
+    };
+    // Runs in <head> before paint. Decides the engine by toggling the marker
+    // class, so the CSS rule sets stay mutually exclusive. No marker => purist.
+    return `(function(){var o=${JSON.stringify(runtime)};window.__ASTRO_REVEAL__=o;try{var s=window.CSS&&CSS.supports&&CSS.supports("animation-timeline: view()");if(o.mode==="observer"||(o.mode==="auto"&&!s)){document.documentElement.classList.add("reveal-js");}}catch(e){document.documentElement.classList.add("reveal-js");}})();`;
+}
+export default function astroReveal(options = {}) {
+    const config = { ...DEFAULTS, ...options };
+    return {
+        name: PKG.name,
+        hooks: {
+            "astro:config:setup": ({ injectScript, logger }) => {
+                // The stylesheet is always needed. Injecting it at the `page-ssr`
+                // stage associates it with each page's server render, so Astro emits
+                // the <link>/inline <style> reliably — and ships ZERO client JS.
+                injectScript("page-ssr", `import ${JSON.stringify(`${PKG.name}/styles.css`)};`);
+                if (config.mode !== "scroll") {
+                    injectScript("head-inline", headInline(config));
+                    injectScript("page", `import ${JSON.stringify(`${PKG.name}/observer`)};`);
+                }
+                logger.info(`enabled in "${config.mode}" mode` +
+                    (config.mode === "scroll" ? " (zero runtime JS)" : ` (once: ${config.once})`));
+            },
+        },
+    };
+}

package/dist/runtime/observer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/observer.js

@@ -0,0 +1,99 @@
+/*
+ * astro-reveal — observer runtime ("on steroids" mode)
+ * Injected only when mode is "observer" or "auto". Loaded deferred.
+ *
+ * Reads config from window.__ASTRO_REVEAL__ (set by the head-inline script,
+ * which also decides whether the `.reveal-js` marker belongs on <html>).
+ *
+ * Responsibilities — the four things AOS gets wrong:
+ *   1. Never touch anything unless this browser is actually using the JS
+ *      engine (the `.reveal-js` marker is present). In "auto" mode a browser
+ *      with native scroll-timeline support has no marker, so we no-op.
+ *   2. Re-scan after Astro View Transitions (`astro:page-load`).
+ *   3. Watch for late-hydrated islands via MutationObserver.
+ *   4. Bail entirely under prefers-reduced-motion (CSS already shows content).
+ */
+const REVEALED = "is-revealed";
+function getConfig() {
+    const w = window;
+    return (w.__ASTRO_REVEAL__ ?? {
+        mode: "observer",
+        once: true,
+        threshold: 0.15,
+        rootMargin: "0px 0px -10% 0px",
+    });
+}
+function shouldRun() {
+    // Only the JS engine touches the DOM. If the marker isn't there
+    // (purist / auto-on-supporting-browser), the CSS engine owns this page.
+    if (!document.documentElement.classList.contains("reveal-js"))
+        return false;
+    // Respect the user. The hidden state is gated by no-preference in CSS,
+    // so content is already visible — nothing for us to do.
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
+        return false;
+    return true;
+}
+let observer = null;
+let mutationObserver = null;
+const tracked = new WeakSet();
+function reveal(el) {
+    el.classList.add(REVEALED);
+}
+function observe(el, config) {
+    if (tracked.has(el) || el.classList.contains(REVEALED))
+        return;
+    tracked.add(el);
+    observer.observe(el);
+}
+function collect(root = document) {
+    return Array.from(root.querySelectorAll("[data-reveal]"));
+}
+function setup() {
+    if (!shouldRun())
+        return;
+    const config = getConfig();
+    observer?.disconnect();
+    observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (!entry.isIntersecting) {
+                if (!config.once)
+                    entry.target.classList.remove(REVEALED);
+                continue;
+            }
+            reveal(entry.target);
+            if (config.once)
+                observer.unobserve(entry.target);
+        }
+    }, { threshold: config.threshold, rootMargin: config.rootMargin });
+    for (const el of collect())
+        observe(el, config);
+    // Watch for elements added after first paint (hydrated islands, CMS
+    // fragments swapped in, client:visible components, etc.)
+    mutationObserver?.disconnect();
+    mutationObserver = new MutationObserver((mutations) => {
+        for (const m of mutations) {
+            for (const node of Array.from(m.addedNodes)) {
+                if (!(node instanceof Element))
+                    continue;
+                if (node.matches?.("[data-reveal]"))
+                    observe(node, config);
+                for (const child of collect(node))
+                    observe(child, config);
+            }
+        }
+    });
+    mutationObserver.observe(document.body, { childList: true, subtree: true });
+}
+function init() {
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", setup, { once: true });
+    }
+    else {
+        setup();
+    }
+}
+init();
+// Astro View Transitions: the DOM is swapped, observers are stale. Re-arm.
+document.addEventListener("astro:page-load", setup);
+export {};

package/dist/styles/reveal.css

@@ -0,0 +1,129 @@
+/*
+ * astro-reveal — scroll reveal animations for Astro
+ * --------------------------------------------------
+ * Two engines, one API, never both at once:
+ *
+ *   PURIST  (default) : native CSS scroll-driven animations.
+ *                       0 bytes of runtime JS. Scrubbed (reverses on scroll up).
+ *                       Active on  html:not(.reveal-js)  +  @supports view().
+ *
+ *   OBSERVER (steroids): IntersectionObserver toggles `.is-revealed`.
+ *                        ~1KB JS. Plays once and stays. Works everywhere.
+ *                        Active when  html.reveal-js  is present.
+ *
+ * The `.reveal-js` marker is added (or not) by a tiny head-inline script
+ * that the integration injects only when the chosen mode needs it. That
+ * single class is what flips a browser from one engine to the other, so the
+ * two rule sets below are mutually exclusive by construction.
+ *
+ * Everything lives in `@layer astro-reveal` so your own styles always win
+ * without specificity fights.
+ */
+
+@layer astro-reveal {
+
+  /* Tunable knobs. Override per-element via inline style or globally here. */
+  [data-reveal] {
+    --reveal-distance: 1.5rem;
+    --reveal-blur: 8px;
+    --reveal-scale: 0.94;
+    --reveal-duration: 700ms;
+    --reveal-easing: cubic-bezier(0.16, 1, 0.3, 1); /* easeOutExpo-ish */
+    --reveal-index: 0;        /* stagger position within a group */
+    --reveal-stagger: 90ms;   /* per-index delay (observer mode) */
+  }
+
+  /* ============================================================
+   * PURIST ENGINE — native scroll-driven animations
+   * Only on browsers that support it AND when JS engine is off.
+   * If unsupported, NOTHING here applies, so content shows normally.
+   * => FOUC / hidden-forever content is structurally impossible.
+   * ============================================================ */
+  @media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: view()) {
+      :where(html:not(.reveal-js)) [data-reveal] {
+        animation: linear both;
+        animation-timeline: view();
+        /* Best-effort stagger: nudge the scroll window per index.
+           Grouped stagger is crisper in observer mode. */
+        animation-range:
+          entry calc(0% + var(--reveal-index) * 4%)
+          cover calc(30% + var(--reveal-index) * 4%);
+      }
+
+      :where(html:not(.reveal-js)) [data-reveal="up"]    { animation-name: reveal-up; }
+      :where(html:not(.reveal-js)) [data-reveal="down"]  { animation-name: reveal-down; }
+      :where(html:not(.reveal-js)) [data-reveal="left"]  { animation-name: reveal-left; }
+      :where(html:not(.reveal-js)) [data-reveal="right"] { animation-name: reveal-right; }
+      :where(html:not(.reveal-js)) [data-reveal="fade"]  { animation-name: reveal-fade; }
+      :where(html:not(.reveal-js)) [data-reveal="scale"] { animation-name: reveal-scale; }
+      :where(html:not(.reveal-js)) [data-reveal="blur"]  { animation-name: reveal-blur; }
+    }
+  }
+
+  /* ============================================================
+   * OBSERVER ENGINE — IntersectionObserver + class toggle
+   * Hidden state is scoped under `.reveal-js`, which is only ever
+   * added by JS. So if JS is disabled, the class never appears and
+   * content stays visible. Reduced-motion users never get hidden.
+   * ============================================================ */
+  @media (prefers-reduced-motion: no-preference) {
+    html.reveal-js [data-reveal] {
+      opacity: 0;
+      transition-property: opacity, transform, filter;
+      transition-duration: var(--reveal-duration);
+      transition-timing-function: var(--reveal-easing);
+      transition-delay: calc(var(--reveal-index) * var(--reveal-stagger));
+      will-change: opacity, transform;
+    }
+
+    html.reveal-js [data-reveal="up"]    { transform: translateY(var(--reveal-distance)); }
+    html.reveal-js [data-reveal="down"]  { transform: translateY(calc(-1 * var(--reveal-distance))); }
+    html.reveal-js [data-reveal="left"]  { transform: translateX(var(--reveal-distance)); }
+    html.reveal-js [data-reveal="right"] { transform: translateX(calc(-1 * var(--reveal-distance))); }
+    html.reveal-js [data-reveal="scale"] { transform: scale(var(--reveal-scale)); }
+    html.reveal-js [data-reveal="blur"]  { filter: blur(var(--reveal-blur)); }
+    /* "fade" needs no transform, opacity:0 above is enough */
+
+    /* The revealed state: everything snaps back to neutral. */
+    html.reveal-js [data-reveal].is-revealed {
+      opacity: 1;
+      transform: none;
+      filter: none;
+    }
+  }
+
+  /* ============================================================
+   * KEYFRAMES (shared by the purist engine)
+   * Naming follows AOS: the value is the direction the element
+   * TRAVELS as it appears. `up` rises into place (starts below).
+   * ============================================================ */
+  @keyframes reveal-up {
+    from { opacity: 0; transform: translateY(var(--reveal-distance)); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+  @keyframes reveal-down {
+    from { opacity: 0; transform: translateY(calc(-1 * var(--reveal-distance))); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+  @keyframes reveal-left {
+    from { opacity: 0; transform: translateX(var(--reveal-distance)); }
+    to   { opacity: 1; transform: translateX(0); }
+  }
+  @keyframes reveal-right {
+    from { opacity: 0; transform: translateX(calc(-1 * var(--reveal-distance))); }
+    to   { opacity: 1; transform: translateX(0); }
+  }
+  @keyframes reveal-fade {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+  @keyframes reveal-scale {
+    from { opacity: 0; transform: scale(var(--reveal-scale)); }
+    to   { opacity: 1; transform: scale(1); }
+  }
+  @keyframes reveal-blur {
+    from { opacity: 0; filter: blur(var(--reveal-blur)); }
+    to   { opacity: 1; filter: blur(0); }
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+   "name": "astro-reveal",
+   "version": "0.1.0",
+   "description": "Scroll reveal animations for Astro. Zero-JS by default via native CSS scroll-driven animations, with an opt-in IntersectionObserver engine. UI-framework agnostic.",
+   "type": "module",
+   "author": "Nicolás Picoto",
+   "license": "MIT",
+   "keywords": [
+      "astro",
+      "astro-integration",
+      "astro-component",
+      "withastro",
+      "animation",
+      "scroll",
+      "reveal",
+      "scroll-driven-animations",
+      "aos",
+      "intersection-observer"
+   ],
+   "exports": {
+      ".": {
+         "types": "./dist/index.d.ts",
+         "default": "./dist/index.js"
+      },
+      "./Reveal.astro": "./Reveal.astro",
+      "./observer": "./dist/runtime/observer.js",
+      "./styles.css": "./dist/styles/reveal.css"
+   },
+   "main": "./dist/index.js",
+   "types": "./dist/index.d.ts",
+   "files": [
+      "dist",
+      "Reveal.astro",
+      "README.md",
+      "LICENSE"
+   ],
+   "scripts": {
+      "build": "tsc && node scripts/copy-assets.mjs",
+      "dev": "tsc --watch",
+      "typecheck": "tsc --noEmit",
+      "changeset": "changeset",
+      "version": "changeset version",
+      "release": "npm run build && changeset publish",
+      "prepublishOnly": "npm run build"
+   },
+   "publishConfig": {
+      "access": "public"
+   },
+   "peerDependencies": {
+      "astro": ">=4.0.0"
+   },
+   "devDependencies": {
+      "@changesets/cli": "^2.31.0",
+      "@types/node": "^20.11.0",
+      "astro": "^4.16.0",
+      "typescript": "^5.4.0"
+   },
+   "repository": {
+      "type": "git",
+      "url": "https://github.com/nicopicoto/astro-reveal.git"
+   }
+}