README

Scroll-triggered viewport animations for Neo components: reveal on enter, item stagger, parallax, and optional exit animations. Built on the existing neo/animate catalog (an animate.css fork namespaced as .neo-animate--*) plus a small IntersectionObserver driver — no external animation library.

How it works

Authors write marker classes (they carry no animation CSS themselves); the driver (src/js/neo-animate.ts) applies the real catalog classes at the right moments. Only the driver ever writes neo-animate--animated and raw catalog names. Elements queued for a reveal are pre-hidden (opacity only) behind an html.neo-animate-ready gate added by an inline head script — no-JS visitors and prefers-reduced-motion users always see content.

Class API

Playground (/admin/config/neo/animate)

A frontend-developer tool under Configuration → Neo → Animate:

• Playground — pick animation / speed / delay / repeat, preview live with a Replay button, and copy the result in three forms (marker classes, the neo_animate Twig filter, the Alchemist prop values).
• Gallery — every catalog animation grouped by family, click a tile to replay.
• Stagger and Parallax live demos.
• Simulate reduced motion toggle to preview the accessible fallback.

Gated by the access neo_animate demo permission (uid 1 bypasses; grant it to any role that should see the tool).

Twig authoring (ordinary templates)

For non-Alchemist templates (node/views/block/field twigs) two filters apply the same animations without hand-writing marker classes — no library attach needed (the driver is global):

{# animate an attributes object #}
<div{{ attributes|neo_animate('fade-up', {delay: 200, speed: 'slow'}) }}>…</div>

{# stagger a render array's children: +200ms every 2nd item #}
{{ content.field_images|neo_animate_children('zoom-in', 2, 200) }}

Friendly names (fade, fade-up/down/left/right, zoom-in/out, slide-*, flip-*, bounce) map to catalog effects; any other value passes through as a raw catalog name, so the full catalog (tada, jello, fadeInUpSmall, …) is reachable. Options: speed (bucket), delay (ms number or bucket string), once (false → replays via repeat), exit (a catalog name). Precise delay values ride on a data-neo-animate-delay attribute the driver applies on reveal.

Alchemist props

Any component opts in with:

animate:
  type: animate
animate_speed:
  type: animate_speed
animate_delay:
  type: animate_delay
animate_stagger:
  type: animate_stagger

Stagger additionally needs the component's repeating element to carry the neo-animate-item class in its twig. Editors picking Stagger on a component without item markers is a harmless no-op; Animation "None" never hides anything.

Behavior matrix

Pitfalls

• Catalog speed/delay modifiers are compound selectors — inert without neo-animate--animated. That's by design; don't "fix" them.
• A custom style list for the animate prop must keep a none: { value: '' } option (empty styles maps are rejected).
• All classes here are plain CSS (catalog + this module) — no Tailwind rebuild is needed when using them; drush cr after editing prop defs or component yml.