167 lines
4.2 KiB
Markdown
167 lines
4.2 KiB
Markdown
# GSAP Animation System (Punch animations)
|
|
|
|
This project uses GSAP for scroll-driven punch animations (zoom in/out effects) via shortcodes. The system is intentionally minimal.
|
|
|
|
## Architecture
|
|
|
|
### 1. Animations Library (`gsap-animations.js`)
|
|
Contains reusable zoom presets and `shouldAnimate()`.
|
|
|
|
### 2. Content Animations (`gsap-shortcode-init.js`)
|
|
Handles scroll-triggered animations in markdown/blog posts via shortcodes.
|
|
|
|
### 3. UI Component Animations (`mix-nav-animations.js`)
|
|
Handles interactive animations for navigation, buttons, and UI elements.
|
|
|
|
---
|
|
|
|
## For Content Authors (Markdown/Posts)
|
|
|
|
### Basic Usage
|
|
|
|
Punch into a focal point on scroll:
|
|
```markdown
|
|
{% gsapScrollAnim {
|
|
"animationType": "punchIn",
|
|
"focalX": 50,
|
|
"focalY": 50,
|
|
"startZoom": 1,
|
|
"endZoom": 2.5
|
|
} %}
|
|
[{ "src": "/path/to/high-res-image.jpg", "alt": "Image to punch into" }]
|
|
{% endgsapScrollAnim %}
|
|
```
|
|
|
|
### Available Animation Types
|
|
|
|
- `punchIn` - Punch into image focal point (zoom in)
|
|
- `punchOut` - Punch out from focal point (zoom out)
|
|
|
|
### Punch Animations with Focal Points
|
|
|
|
```markdown
|
|
{% gsapScrollAnim {
|
|
"animationType": "punchIn",
|
|
"focalX": 30,
|
|
"focalY": 40,
|
|
"startZoom": 1,
|
|
"endZoom": 2.5,
|
|
"scrub": true
|
|
} %}
|
|
[{
|
|
"src": "/path/to/high-res-image.jpg",
|
|
"alt": "Image to zoom"
|
|
}]
|
|
{% endgsapScrollAnim %}
|
|
```
|
|
|
|
- `focalX` / `focalY`: 0-100 (percentage of image dimensions)
|
|
- `startZoom` / `endZoom`: Scale values (1 = normal size)
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## Scroll Control Options
|
|
|
|
### `scrub` (default: `true`)
|
|
- `true` - Animation tied to scroll position (smooth)
|
|
- `false` - Animation plays once when triggered
|
|
|
|
### `scrollStart` (default: `"top 80%"`)
|
|
When animation begins:
|
|
- `"top 80%"` - When element's top hits 80% down viewport
|
|
- `"center center"` - When element center hits viewport center
|
|
- `"bottom 20%"` - When element bottom hits 20% down viewport
|
|
|
|
### `scrollEnd` (default: `"bottom 20%"`)
|
|
When animation completes (for scrubbed animations)
|
|
|
|
### `pin` (default: `false`)
|
|
Pin the element in place during animation:
|
|
```markdown
|
|
{% gsapScrollAnim {
|
|
"animationType": "zoomIn",
|
|
"pin": true,
|
|
"scrollEnd": "+=500"
|
|
} %}
|
|
```
|
|
|
|
### `spillingInto` (default: `false`)
|
|
Control layout overflow beyond prose margins:
|
|
- `false` - Default: constrained within prose margins
|
|
- `true` / `"prose"` - Override margins for responsive bleed
|
|
- `"bleed"` - Full-width edge-to-edge breakout
|
|
|
|
```markdown
|
|
{% gsapScrollAnim {
|
|
"animationType": "punchIn",
|
|
"spillingInto": "bleed"
|
|
} %}
|
|
[{ "src": "/path/to/image.jpg", "alt": "Full-width image" }]
|
|
{% endgsapScrollAnim %}
|
|
```
|
|
|
|
### `markers` (default: `false`)
|
|
Show debug markers (for development).
|
|
|
|
---
|
|
|
|
## Multiple Images
|
|
You can include multiple images; zoom applies to `.gsap-image` elements inside the container.
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
1. **Scrub for slow reveals** - Set `"scrub": true` for scroll-controlled drama
|
|
2. **No scrub for punchy moments** - Set `"scrub": false` for quick actions
|
|
3. **Pin for focus** - Use `"pin": true` to hold attention on an element
|
|
4. **Zoom needs high-res** - Zoom animations automatically request larger image sizes
|
|
|
|
---
|
|
|
|
## For Developers
|
|
|
|
### Library API
|
|
|
|
Zoom-only presets live in [`gsap-animations.js`](../src/assets/scripts/bundle/gsap-animations.js). Defaults are merged and can be overridden via shortcode config.
|
|
|
|
### UI Component Animations
|
|
|
|
Create component-specific files like [`mix-nav-animations.js`](../src/assets/scripts/bundle/mix-nav-animations.js):
|
|
|
|
```javascript
|
|
import gsap from 'gsap';
|
|
import { shouldAnimate } from './gsap-animations.js';
|
|
|
|
function initMyComponentAnimations() {
|
|
if (!shouldAnimate()) return;
|
|
|
|
document.querySelectorAll('.my-element').forEach(el => {
|
|
el.addEventListener('mouseenter', () => {
|
|
gsap.to(el, { scale: 1.1, duration: 0.2 });
|
|
});
|
|
});
|
|
}
|
|
|
|
// Turbo-compatible initialization
|
|
document.addEventListener('DOMContentLoaded', initMyComponentAnimations);
|
|
if (window.Turbo) {
|
|
document.addEventListener('turbo:load', initMyComponentAnimations);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Accessibility
|
|
|
|
All animations respect `prefers-reduced-motion`. Users with this preference will see static content without animations.
|
|
|
|
---
|
|
|
|
## Debugging
|
|
|
|
Enable markers to see scroll trigger points via the shortcode config.
|
|
|
|
Check browser console for warnings about missing animation types or configuration errors.
|