# 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):

```html
<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.

```bash
# 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
- `mosaique-effects@1.0` — latest patch within 1.0.x
- `mosaique-effects@1` — latest minor within 1.x.x

## Local Development

```bash
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