@cssints/reveal 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+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

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# @cssints/reveal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scroll-driven reveal animations for [cssints](../../README.md): an element runs one of
+[@cssints/motion](../motion/README.md)'s entrance presets as it scrolls into view, on `animation-timeline: view()` and
+`animation-range`, as one chain member of `cssints/plugin` `scope()`. In the spirit of
+[the supersonic plugin](https://github.com/the-illarionov/the-supersonic-plugin-for-scroll-based-animation) and
+[lax.js](https://github.com/alexfoxy/lax.js), with the browser doing the work. Where a target lacks scroll-driven
+animations, a 0.3 kB script plays the same keyframes once when the element enters.
+
+```ts
+import { cn, hover } from "cssints" with { type: "cssints" };
+import { reveal } from "@cssints/reveal" with { type: "cssints" };
+
+export const fade = reveal();
+export const card = reveal()
+  .preset("slide-in-up")
+  .range("entry 0% entry 100%")
+  .duration("500ms")
+  .easing("linear");
+export const tile = cn(reveal().preset("blur-in"), hover(reveal().duration("1s")));
+```
+
+```css
+@layer _.k {
+  @keyframes kf-7f473efd {
+    from {
+      opacity: var(--motion-o);
+      translate: var(--motion-x) var(--motion-y);
+      scale: var(--motion-s);
+      filter: blur(var(--motion-b));
+    }
+  }
+  @keyframes kf-4f766ef7 {
+    from {
+      opacity: var(--motion-o);
+    }
+  }
+  ._reveal-core {
+    animation: var(--reveal-k) var(--reveal-d) var(--reveal-e) both;
+    animation-range: var(--reveal-g);
+    --reveal-k: kf-7f473efd;
+    --reveal-rk: kf-4f766ef7;
+    --reveal-d: 300ms;
+    --reveal-e: ease-out;
+    --reveal-g: entry 0% cover 40%;
+    --motion-o: 0;
+    --motion-x: 0;
+    --motion-y: 0;
+    --motion-s: 1;
+    --motion-b: 0;
+    animation-timeline: view();
+  }
+  @media (prefers-reduced-motion: reduce) {
+    ._reveal-core {
+      animation-name: var(--reveal-rk);
+    }
+  }
+  /* only when a target lacks scroll-driven animations */
+  @supports not (animation-timeline: view()) {
+    [data-reveal] ._reveal-core:not([data-reveal-in]) {
+      animation-play-state: paused;
+    }
+  }
+}
+@layer _.a {
+  ._1a9p5a9 {
+    --motion-y: 25%;
+  }
+  ._yorqor {
+    --reveal-g: entry 0% entry 100%;
+  }
+  ._k4abtq {
+    --reveal-d: 500ms;
+  }
+  /* ... */
+}
+```
+
+## Rules
+
+- **Methods**, each once, in any order, all optional: `preset(name)` (`fade-in`), `range(<'animation-range'>)`
+  (`entry 0% cover 40%`), `duration(<time [0s,∞]>)` (300ms) and `easing(<easing-function>)` (`ease-out`). Each is one
+  class that sets a custom property, so a method works under a condition. Where the timeline is native, the range
+  decides when the animation runs and the scroll drives it (back and forth); the duration and the easing shape the
+  fallback's one play (the easing applies to the scrubbed progress too).
+- **Presets** are motion's entrance presets: `fade-in`, `slide-in-up`, `slide-in-down`, `slide-in-left`,
+  `slide-in-right`, `scale-in`, `blur-in`. The `-out` ones are not: the fallback can only play when an element enters.
+- **Reuse of motion.** The kernel names motion's `motionKeyframes.in` and `motionKeyframes.reducedIn`, which carries
+  their rules (shared with `motion()` on the same page: one rule each), and a preset sets the values those keyframes
+  read, from motion's `presets` table under motion's names (`motionVars`). Nothing is copied, not even a name.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce` the kernel runs the opacity-only keyframes (motion's rule):
+  a slide, scale or blur becomes a fade over the same range.
+- **One kernel, written as styles.** The `animation` shorthand resets `animation-timeline` and `animation-range`; a
+  kernel prints a shorthand before its longhands, so the timeline set beside it wins.
+- **Conflicts.** `reveal()` sets the animation: a `cn()` that holds it and an `animation*` property is a build error,
+  derived from the kernel: `cssints: reveal: kernel core sets animation, animation-timeline, animation-range, animation-name (this style also sets animation-duration)`.
+- **Errors** are the grammar's, in the types and at build time: `reveal.preset: unexpected "fade-out" in "fade-out",
+expected fade-in | ...`, `reveal.range: unexpected "sideways" in "entry 0% sideways"`.
+
+## Browsers
+
+- **Native**: Chrome 115, Safari 26 (scroll-driven animations, `css.properties.animation-timeline` and
+  `animation-range`). Firefox has them behind a flag only.
+- **The fallback.** When a browserslist target lacks them, the build adds the `@supports not` rule above to the sheet
+  (it stays out of the sheet for targets that all have them), and the kernel's `animation-timeline` and `animation-range` give no warning: the runtime polyfills both. The
+  script, `@cssints/reveal/runtime`, comes with it: the runtime entry names it (`script`), so the module that uses
+  `reveal()` imports it through `virtual:cssints/runtime/reveal.io`, which is empty when every target has the timeline.
+  Nothing to import by hand. In the browser it does nothing where `CSS.supports("animation-timeline:view()")`; elsewhere it
+  marks `<html data-reveal>` (the rule then holds each reveal at its first frame) and an `IntersectionObserver` gives an
+  element `data-reveal-in` when it enters the viewport, which plays the keyframes once, over `duration()`. A
+  `MutationObserver` picks up elements added later. 536 bytes minified, 319 gzip; no imports.
+- **Why not a polyfill.** [flackr's scroll-timeline polyfill](https://github.com/flackr/scroll-timeline) scrubs the
+  animation as the native timeline does, but it is about 61 kB minified (17 kB gzip), rewrites stylesheets and runs on
+  every scroll. A reveal is an entrance: playing it once on entry is what most sites want, costs 1/50 of the bytes and
+  nothing per scroll. The price is that the fallback is not scrubbed and ignores `range()`.
+- Without the script, a target that lacks the timeline plays the animation on load, as `motion()` would: nothing stays
+  hidden.
+- Tested in Chrome 154 and WebKit 26.6 (native, and the fallback forced) and Firefox 155 (the fallback):
+  `bun run test:browsers`.
+
+## Limits
+
+- With targets that mix both (the default browserslist), the script ships to every browser and only probes where the
+  timeline is native.
+- The fallback does not follow the range, the scroll direction or an element that leaves the viewport: it plays once. An
+  element that gets the class after it is in the document (not added with it) is not seen.
+- Until the script runs, a reveal below the fold may start playing; it is paused where it is and resumes on entry. The
+  script runs with the first module that uses `reveal()`.
+- Entrance presets only, one per element; for an exit on scroll write the animation with `animationTimeline("view()")`
+  and `animationRange("exit ...")` yourself.
+
+```bash
+cd packages/reveal && bun run test            # fixtures through the engine (output by targets, runtime module, conflicts, errors)
+cd packages/reveal && bun run test:browsers   # Chrome, Firefox and WebKit through playwright-core
+```
+
+## Credits
+
+In the spirit of [the supersonic plugin](https://github.com/the-illarionov/the-supersonic-plugin-for-scroll-based-animation)
+(MIT, Alex Illarionov) and [lax.js](https://github.com/alexfoxy/lax.js) (MIT, Alex Fox). The presets are
+[@cssints/motion](../motion/README.md)'s. No code is copied.

package/dist/index.d.mts

@@ -0,0 +1,58 @@
+//#region src/index.d.ts
+/** The scope of `reveal()`, for a scope that embeds it (its kernel `core`). */
+export declare const revealScope: import("cssints/plugin").Scope<"reveal", {
+  readonly "#core": {
+    readonly css: (css: import("cssints/plugin").Css) => import("cssints").Style[];
+  };
+  readonly "#io": {
+    readonly polyfills: ["css.properties.animation-timeline", "css.properties.animation-range"];
+    readonly script: "@cssints/reveal/runtime";
+    readonly css: "@supports not (animation-timeline:view()){[data-reveal] &:not([data-reveal-in]){animation-play-state:paused}}";
+  };
+  readonly reveal: {
+    readonly uses: readonly ["core", "io"];
+    readonly chain: {
+      readonly preset: {
+        readonly args: "fade-in | slide-in-up | slide-in-down | slide-in-left | slide-in-right | scale-in | blur-in";
+        readonly emit: (name: string) => (readonly ["--motion-o" | "--motion-x" | "--motion-y" | "--motion-s" | "--motion-b", string])[];
+      };
+      readonly range: {
+        readonly args: "<'animation-range'>";
+        readonly emit: (v: string) => [string, string][];
+      };
+      readonly duration: {
+        readonly args: "<time [0s,∞]>";
+        readonly emit: (v: string) => [string, string][];
+      };
+      readonly easing: {
+        readonly args: "<easing-function>";
+        readonly emit: (v: string) => [string, string][];
+      };
+    };
+  };
+}>;
+/**
+ * `reveal().preset("slide-in-up").range("entry 0% entry 100%").duration("500ms").easing("linear")`: motion's entrance
+ * preset driven by the element's scroll into view, each method once and optional (`fade-in`, `entry 0% cover 40%`,
+ * 300ms and `ease-out` for the fallback, which plays once on entry). Under `prefers-reduced-motion: reduce` only the
+ * opacity moves. It sets the animation, so an `animation*` property in the same `cn()` is a build error.
+ */
+export declare const reveal: () => import("cssints/plugin").Chain<"reveal", {
+  readonly preset: {
+    readonly args: "fade-in | slide-in-up | slide-in-down | slide-in-left | slide-in-right | scale-in | blur-in";
+    readonly emit: (name: string) => (readonly ["--motion-o" | "--motion-x" | "--motion-y" | "--motion-s" | "--motion-b", string])[];
+  };
+  readonly range: {
+    readonly args: "<'animation-range'>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly duration: {
+    readonly args: "<time [0s,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly easing: {
+    readonly args: "<easing-function>";
+    readonly emit: (v: string) => [string, string][];
+  };
+}, {}>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,68 @@
+import { motionKeyframes, motionVars, presets } from "@cssints/motion";
+import { scope } from "cssints/plugin";
+//#region src/index.ts
+const names = "fade-in | slide-in-up | slide-in-down | slide-in-left | slide-in-right | scale-in | blur-in";
+const fields = Object.keys(motionVars);
+const emitPreset = (name) => {
+	const p = presets[name];
+	return fields.flatMap((f) => {
+		const v = p[f];
+		return v === void 0 ? [] : [[motionVars[f], v]];
+	});
+};
+/** The scope of `reveal()`, for a scope that embeds it (its kernel `core`). */
+const revealScope = scope("reveal", {
+	"#core": { css: (css) => [
+		css.vars({
+			"--_k": motionKeyframes.in,
+			"--_rk": motionKeyframes.reducedIn,
+			"--_d": "300ms",
+			"--_e": "ease-out",
+			"--_g": "entry 0% cover 40%",
+			[motionVars.opacity]: 0,
+			[motionVars.x]: 0,
+			[motionVars.y]: 0,
+			[motionVars.scale]: 1,
+			[motionVars.blur]: 0
+		}),
+		css.animation("var(--_k) var(--_d) var(--_e) both"),
+		css.animationTimeline("view()"),
+		css.animationRange("var(--_g)"),
+		css.media("(prefers-reduced-motion: reduce)")(css.animationName("var(--_rk)"))
+	] },
+	"#io": {
+		polyfills: ["css.properties.animation-timeline", "css.properties.animation-range"],
+		script: "@cssints/reveal/runtime",
+		css: `@supports not (animation-timeline:view()){[data-reveal] &:not([data-reveal-in]){animation-play-state:paused}}`
+	},
+	reveal: {
+		uses: ["core", "io"],
+		chain: {
+			preset: {
+				args: names,
+				emit: emitPreset
+			},
+			range: {
+				args: "<'animation-range'>",
+				emit: (v) => [["--_g", v]]
+			},
+			duration: {
+				args: "<time [0s,∞]>",
+				emit: (v) => [["--_d", v]]
+			},
+			easing: {
+				args: "<easing-function>",
+				emit: (v) => [["--_e", v]]
+			}
+		}
+	}
+});
+/**
+* `reveal().preset("slide-in-up").range("entry 0% entry 100%").duration("500ms").easing("linear")`: motion's entrance
+* preset driven by the element's scroll into view, each method once and optional (`fade-in`, `entry 0% cover 40%`,
+* 300ms and `ease-out` for the fallback, which plays once on entry). Under `prefers-reduced-motion: reduce` only the
+* opacity moves. It sets the animation, so an `animation*` property in the same `cn()` is a build error.
+*/
+const { reveal } = revealScope.export();
+//#endregion
+export { reveal, revealScope };

package/dist/runtime.d.mts

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

package/dist/runtime.mjs

@@ -0,0 +1 @@
+if(typeof CSS<`u`&&!CSS.supports(`animation-timeline:view()`)){let e=document.documentElement,t=`._reveal-core`,n=new IntersectionObserver(e=>{for(let t of e)t.isIntersecting&&(t.target.setAttribute(`data-reveal-in`,``),n.unobserve(t.target))}),r=e=>{e.matches(t)&&n.observe(e);for(let r of e.querySelectorAll(t))n.observe(r)};e.setAttribute(`data-reveal`,``),r(e),new MutationObserver(e=>{for(let t of e)for(let e of t.addedNodes)e instanceof Element&&r(e)}).observe(e,{childList:!0,subtree:!0})}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@cssints/reveal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Scroll-driven reveal animations for cssints: motion's presets on animation-timeline: view(), with a tiny IntersectionObserver fallback",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/reveal"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/runtime.ts",
+    "./dist/runtime.mjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "default": "./dist/runtime.mjs"
+    }
+  },
+  "dependencies": {
+    "@cssints/motion": "^0.2.0"
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}