CELEBRATION.JS
==============

A dependency-free JavaScript effects library from Zyel Lab.

Live demo and catalog:
https://zyel.io/lab/

Download:
https://zyel.io/lab/celebration.js

Source:
https://github.com/chasonarthur/zyel.io/tree/main/lab

FEATURES
--------

- 140 success animations
- 70 synthesized success sounds in five selectable categories
- 20 full-screen error effects
- 20 synthesized error sounds
- SVG confetti, true fireworks, potion vapor, spark points, glass shards,
  smoke clouds, bubbles, maple/oak/birch leaves, streamers, and glitches
- Element anchoring and behind-element masking
- Source outlines and automatic palette extraction
- Attraction, repulsion, edge collisions, directional cones, and particle scale
- Subtle, normal, huge, and absurd intensity levels
- Automatic mobile and desktop performance tiers
- Screen shake, flash, blur, chromatic distortion, and optional haptics
- Seeded, reproducible random selection and particle layouts
- Pointer-following effects and named multi-stage combos
- Timed multi-stage queues
- Numbered, named, random, and round-robin selection
- Optional alert dialogs
- Full-motion Lab playback by default, with explicit System and Reduced previews
- Reduced-motion support in the reusable library through motion: "respect" or "reduce"
- Firework shells launch vertically from the lower edge, arrive at their exact burst centers, and explode only after the rocket reaches its apex
- Compact alternating-gradient preview tiles use a locally hosted Font Awesome play icon to make every preset clearly pressable
- No third-party dependencies

QUICK START
-----------

1. Add the script:

   <script src="/js/celebration.js"></script>

2. Fire an effect:

   Celebration.fire({
     animation: 57,
     sound: "round-robin",
     alert: false
   });

ANCHOR TO A BUTTON
------------------

Celebration.fireFrom("#saveButton", {
  animation: "random",
  sound: "random",
  anchorPoint: "center",
  behind: true,
  alert: false
});

Every success preset supports fireFrom(). The source may be a CSS selector,
DOM element, event/currentTarget, or { element, point, offset } object. The
animation is masked over the source element so it appears to burst from behind
the original control.

The equivalent long form is:

Celebration.fire({
  animation: "random",
  sound: "random",
  anchor: "#saveButton",
  behind: true,
  alert: false
});

SELECTION MODES
---------------

Visuals and sounds are selected independently:

Celebration.fire({
  animation: "random",      // One non-repeating random pick from all 140
  sound: "round-robin",     // Cycles through all 70 before repeating
  alert: false
});

Celebration.fire({
  animation: 57,            // Specific animation number or exact name
  sound: 12,                // Specific sound number or exact name
  alert: false
});

Set independent defaults for repeated calls:

const celebrations = new Celebration({
  animationStrategy: "random",
  soundStrategy: "round-robin"
});

celebrations.fireFrom("#saveButton", { alert: false });

NEW SPECTACLE FAMILIES
----------------------

Presets 81-140 use dedicated motion renderers rather than recolored confetti:

- 81-84: chrysanthemum, willow, crackling, and peony fireworks
- 85-88: potion vapor, magical sparks, elixir bubbles, and toxic lime clouds
- 89-91: star points, firefly dots, and constellation ignition
- 92-94: clear, stained, and frosted glass shatters
- 95-96: silver and violet smoke systems
- 97-100: center, bottom, fountain, and tidal bubble systems
- 101-105: maple, oak, birch, mixed forest, and seasonal leaf systems
- 106-115: acorns, chestnuts, hazelnuts, grain, wheat, barley, oats,
  seed pods, corn kernels, and a mixed harvest cascade
- 116-140: ball lightning, plasma arcs, supernovas, black holes, meteors,
  solar flares, magma, cryo crystals, phoenix fire, dragon breath,
  spectral flame, portals, lasers, holograms, diamond dust, auroras,
  ink blooms, water impacts, sonic booms, comic impacts, magnetic fields,
  chain reactions, circuit traces, rockets, and burning-fuse finales

All of these work with fireFrom(), random, round-robin, queues, palettes, and
the same independently selected success sounds.

QUEUE A FINALE
--------------

Celebration.queue([
  { delay: 0, animation: 77, sound: 1, origin: "bottom" },
  { delay: 500, animation: 61, sound: false, origin: "top" },
  { delay: 500, animation: 80, sound: 12, origin: "corners" }
]);

ADVANCED PHYSICS AND TREATMENTS
-------------------------------

Celebration.fireFrom("#saveButton", {
  animation: 127,
  sound: "electronic",
  intensity: "huge",
  performance: "auto",
  particleScale: 1.15,
  direction: "up",
  attraction: 0.4,
  repulsion: 0.8,
  collisions: true,
  palette: "auto",
  anchorOutline: true,
  flash: true,
  chromatic: true,
  haptics: true,
  seed: "release-42",
  alert: false
});

intensity accepts "subtle", "normal", "huge", "absurd", or a numeric scale.
performance accepts "auto", "low", "medium", "high", or "ultra".
direction accepts up/down/left/right, diagonal directions, inward, or outward.
target (or toward) accepts a selector, element, or event target and aims
directional effects from the source origin toward that element.
palette: "auto" extracts usable colors from the anchored source element.

SOUND CATEGORIES
----------------

Success sounds can be selected by number, exact name, rotation strategy, or:

- "magical"
- "explosive"
- "electronic"
- "crystalline"
- "arcade"

Celebration.fire({
  animation: 118,
  sound: "explosive",
  alert: false
});

NAMED COMBOS
------------

Celebration.combo("supernovaFinale", { intensity: "huge" });

const celebrations = Celebration.getShared();
celebrations.playCombo("everythingDetonates", {
  anchor: "#saveButton",
  palette: "auto",
  haptics: true
});

Available combo keys:
supernovaFinale, elementalClash, portalBreach, rocketVictory,
quantumOverdrive, everythingDetonates.

POINTER FOLLOWING
-----------------

const celebrations = Celebration.getShared();

celebrations.followPointer({
  animation: "random",
  sound: false,
  interval: 120,
  intensity: "subtle"
});

celebrations.stopPointerFollowing();

ERROR EFFECT
------------

Celebration.fire({
  type: "error",
  animation: "round-robin",
  sound: "round-robin",
  errorIcon: "!",
  errorTitle: "Save failed",
  errorMessage: "The server could not save your changes.",
  alert: false
});

CORE METHODS
------------

Celebration.fire(options)
Celebration.fireFrom(source, options)
Celebration.queue(steps, options)
Celebration.combo(name, options)
Celebration.getShared(options)

instance.fireFrom(source, options)
instance.playAnimation(reference, options)
instance.playSound(reference, options)
instance.enqueue(steps, options)
instance.playCombo(name, options)
instance.getCombos()
instance.followPointer(options)
instance.stopPointerFollowing()
instance.showAlert(options)
instance.clear()
instance.count(type, catalog)
instance.getCatalog(type, catalog)
instance.getSoundCategories()
instance.setSoundEnabled(enabled)

REFERENCES
----------

An animation or sound reference may be:

- A 1-based number
- An exact preset name
- "random"
- "round-robin"

"random" draws from the full catalog and avoids immediately repeating the
previous pick. "round-robin" traverses the full catalog in order, then starts
again. Use type: "error" to select from the separate error catalogs.

LICENSE
-------

MIT License. See https://zyel.io/lab/LICENSE.txt

Zyel builds web products, AI systems, automation, and digital platforms.
https://zyel.io/