Mosaique Effects

Shared JS effects library for LumApps client sites. Loaded via <script> tag — each site enables features through a simple config object.

Quick Start

Add this to the site's header (Settings > Header):

<script>window.MosaiqueConfig = {
  reactions: true,
  scrollReveal: true,
  headings: true,
  cardLift: true,
  imageZoom: true,
  readingProgress: true,
  scrollTop: true,
  buttonEffects: true,
  navHover: true,
  headingAnchors: true
};</script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/mosaique-effects@1/dist/mosaique-effects.min.js"></script>

Set any module to false or remove it to disable that effect.

Modules

| Key | Effect | |-----|--------| | reactions | Animated reaction buttons (scale, wiggle, particle burst) | | scrollReveal | Staggered fade-in for content elements on page load and scroll | | headings | Subtle letter-spacing tighten + fade on h1/h2 | | cardLift | Scale + shadow elevation on content list cards on hover | | imageZoom | Gentle zoom on linked images on hover | | readingProgress | Thin accent bar at top of viewport tracking scroll position | | scrollTop | Floating back-to-top button (bottom-left) | | buttonEffects | Click ripple + press bounce on buttons | | navHover | Directional animated underline on main nav links | | headingAnchors | Hover-reveal anchor links on headings, copies URL to clipboard |

Publishing to npm

The library is hosted on npm and served via jsDelivr CDN.

# First time setup
npm login

# Build
npm run build

# Bump version and publish
npm version patch    # 1.0.0 -> 1.0.1
npm publish

jsDelivr picks up new versions automatically. Sites reference a specific version in their script tag, so updating the npm version doesn't break existing sites until you update their header.

Version pinning:

• mosaique-effects@1 — exact version, never changes
• [email protected] — latest patch within 1.0.x
• mosaique-effects@1 — latest minor within 1.x.x

Local Development

npm install
npm run build          # Build dist/mosaique-effects.min.js
npm run serve          # Serve on http://localhost:8081

For testing, point the site header to http://localhost:8081/mosaique-effects.min.js instead of the CDN URL.

Architecture

• src/index.js — entry point, reads config, boots enabled modules
• src/core/observer.js — shared MutationObserver for React SPA re-renders
• src/core/utils.js — WeakSet tracker, queryAll, CSS injection
• src/modules/*.js — individual effect modules
• src/modules/*.css — module CSS (embedded in JS at build time)

Each module:

• Exports an init() function called by the entry point
• Registers DOM selectors with the shared observer
• Uses WeakSet tracking to avoid double-initialising elements
• Injects its own CSS via <style> tag at runtime

GSAP is a peer dependency loaded separately via CDN (not bundled).

CSS Variables

Some modules use LumApps CSS variables for theming:

• --lumx-color-secondary-N — accent colour for reading progress bar and scroll-to-top button

Safety

• All effects are scoped to .front-office so they don't run in the LumApps editor
• Scroll reveal has a CSS animation fallback — if GSAP fails, content auto-reveals after 1.5s
• Headings have a similar safety fallback after 3s
• The library checks for GSAP and degrades gracefully if not loaded