@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/epic-design/references/directional-reveals.md

@@ -0,0 +1,455 @@
+# Directional Reveals Reference
+
+Elements and sections don't always enter from the bottom. Premium sites use **directional births** — sections that drop from the top, iris open from center, peel away like wallpaper, or unfold diagonally. This file covers all 8 directional reveal patterns.
+
+## Table of Contents
+1. [Top-Down Clip Birth](#top-down)
+2. [Window Pane Iris Open](#iris-open)
+3. [Curtain Panel Roll-Up](#curtain-rollup)
+4. [SVG Morph Border](#svg-morph)
+5. [Diagonal Wipe Birth](#diagonal-wipe)
+6. [Circle Iris Expand](#circle-iris)
+7. [Multi-Directional Stagger Grid](#multi-direction)
+8. [Loading Screen Curtain Lift](#loading-screen)
+
+---
+
+## Pattern 1: Top-Down Clip Birth {#top-down}
+
+The section is born from the top edge and grows **downward**. Instead of rising from below, it drops and unfolds from above. This is the opposite of the conventional bottom-up reveal and creates a striking "curtain drop" feeling.
+
+```css
+/* Starting state — section is fully clipped (invisible) */
+.top-drop-section {
+  /* Section exists in DOM but is invisible */
+  clip-path: inset(0 0 100% 0);
+  /* 
+    inset(top right bottom left):
+    - top: 0 → clip starts at top edge
+    - bottom: 100% → clips 100% from bottom = nothing visible
+  */
+}
+
+/* Revealed state */
+.top-drop-section.revealed {
+  clip-path: inset(0 0 0% 0);
+  transition: clip-path 1.2s cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+```javascript
+// GSAP scroll-driven version with scrub
+function initTopDownBirth(sectionEl) {
+  gsap.fromTo(sectionEl,
+    { clipPath: 'inset(0 0 100% 0)' },
+    {
+      clipPath: 'inset(0 0 0% 0)',
+      ease: 'power2.out',
+      scrollTrigger: {
+        trigger: sectionEl.previousElementSibling, // previous section is the trigger
+        start: 'bottom 80%',
+        end: 'bottom 20%',
+        scrub: 1.5,
+      }
+    }
+  );
+}
+
+// Exit: section retracts back upward (born from top, dies back up)
+function addTopRetractExit(sectionEl) {
+  gsap.to(sectionEl, {
+    clipPath: 'inset(100% 0 0% 0)', // now clips from TOP — retracts upward
+    ease: 'power2.in',
+    scrollTrigger: {
+      trigger: sectionEl,
+      start: 'bottom 20%',
+      end: 'bottom top',
+      scrub: 1,
+    }
+  });
+}
+```
+
+**Key insight:** Enter = `inset(0 0 100% 0)` → `inset(0 0 0% 0)` (bottom clips away downward).
+Exit = `inset(0)` → `inset(100% 0 0 0)` (top clips away upward = retracts back where it came from).
+
+---
+
+## Pattern 2: Window Pane Iris Open {#iris-open}
+
+An entire section starts as a tiny centered rectangle — like a keyhole or portal — and expands outward to fill the viewport. Creates a cinematic "opening shot" feeling.
+
+```javascript
+function initWindowPaneIris(sectionEl) {
+  // The section starts as a small centered window
+  gsap.fromTo(sectionEl,
+    {
+      clipPath: 'inset(42% 35% 42% 35% round 12px)',
+      // 42% from top AND bottom = only 16% of height visible
+      // 35% from left AND right = only 30% of width visible
+      // Centered rectangle peek
+    },
+    {
+      clipPath: 'inset(0% 0% 0% 0% round 0px)',
+      ease: 'none',
+      scrollTrigger: {
+        trigger: sectionEl,
+        start: 'top 90%',
+        end: 'top 10%',
+        scrub: 1.2,
+      }
+    }
+  );
+
+  // Also scale/zoom the content inside for parallax depth
+  gsap.fromTo(sectionEl.querySelector('.iris-content'),
+    { scale: 1.4 },
+    {
+      scale: 1,
+      ease: 'none',
+      scrollTrigger: {
+        trigger: sectionEl,
+        start: 'top 90%',
+        end: 'top 10%',
+        scrub: 1.2,
+      }
+    }
+  );
+}
+```
+
+**Variation — horizontal bar open (blinds effect):**
+```javascript
+// Two bars that slide apart (one from top, one from bottom)
+function initBlindsOpen(topBar, bottomBar, revealEl) {
+  const tl = gsap.timeline({
+    scrollTrigger: {
+      trigger: revealEl,
+      start: 'top 70%',
+      toggleActions: 'play none none reverse',
+    }
+  });
+
+  tl.to(topBar, { yPercent: -100, duration: 1.0, ease: 'power3.inOut' })
+    .to(bottomBar, { yPercent: 100, duration: 1.0, ease: 'power3.inOut' }, 0);
+}
+```
+
+---
+
+## Pattern 3: Curtain Panel Roll-Up {#curtain-rollup}
+
+Multiple layered panels. Each one "rolls up" from top, exposing the panel beneath. Like peeling back wallpaper layers to reveal what's underneath. Uses z-index stacking.
+
+```css
+.curtain-stack {
+  position: relative;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.curtain-panel {
+  position: absolute;
+  inset: 0;
+  /* Stack panels — panel 1 on top, panel N on bottom */
+}
+.curtain-panel:nth-child(1) { z-index: 5; background: #0f0f0f; }
+.curtain-panel:nth-child(2) { z-index: 4; background: #1a0a2e; }
+.curtain-panel:nth-child(3) { z-index: 3; background: #2d0b4e; }
+.curtain-panel:nth-child(4) { z-index: 2; background: #1e3a8a; }
+/* Final revealed content at z-index 1 */
+```
+
+```javascript
+function initCurtainRollUp(containerEl) {
+  const panels = gsap.utils.toArray('.curtain-panel', containerEl);
+
+  const tl = gsap.timeline({
+    scrollTrigger: {
+      trigger: containerEl,
+      start: 'top top',
+      end: `+=${panels.length * 120}%`,
+      pin: true,
+      scrub: 1,
+    }
+  });
+
+  panels.forEach((panel, i) => {
+    const segmentDuration = 1 / panels.length;
+    const segmentStart = i * segmentDuration;
+
+    // Each panel rolls up — clip from bottom rises to top
+    tl.to(panel, {
+      clipPath: 'inset(100% 0 0% 0)', // rolls up: bottom clips first, rising to 100%
+      duration: segmentDuration,
+      ease: 'power2.inOut',
+    }, segmentStart);
+
+    // Heading for this panel fades in
+    const heading = panel.querySelector('.panel-heading');
+    if (heading) {
+      tl.from(heading, {
+        opacity: 0,
+        y: 30,
+        duration: segmentDuration * 0.4,
+      }, segmentStart + segmentDuration * 0.1);
+    }
+  });
+
+  return tl;
+}
+```
+
+---
+
+## Pattern 4: SVG Morph Border {#svg-morph}
+
+The section's edge is not a hard straight line — it morphs between shapes (rectangle → wave → diagonal → organic curve) as the user scrolls. Makes sections feel alive and fluid.
+
+```html
+<!-- SVG clipPath element -->
+<svg width="0" height="0" style="position:absolute">
+  <defs>
+    <clipPath id="morphClip" clipPathUnits="objectBoundingBox">
+      <path id="morphPath" d="M0,0 L1,0 L1,0.95 Q0.5,1.05 0,0.95 Z"/>
+    </clipPath>
+  </defs>
+</svg>
+
+<section class="morphed-section" style="clip-path: url(#morphClip)">
+  <!-- section content -->
+</section>
+```
+
+```javascript
+function initSVGMorphBorder() {
+  const morphPath = document.getElementById('morphPath');
+
+  const paths = {
+    straight: 'M0,0 L1,0 L1,1 L0,1 Z',
+    wave:     'M0,0 L1,0 L1,0.95 Q0.75,1.05 0.5,0.95 Q0.25,0.85 0,0.95 Z',
+    diagonal: 'M0,0 L1,0 L1,0.88 L0,1.0 Z',
+    organic:  'M0,0 L1,0 L1,0.92 C0.8,1.04 0.6,0.88 0.4,1.0 C0.2,1.12 0.1,0.90 0,0.96 Z',
+  };
+
+  ScrollTrigger.create({
+    trigger: '.morphed-section',
+    start: 'top 80%',
+    end: 'bottom 20%',
+    scrub: 2,
+    onUpdate: (self) => {
+      const p = self.progress;
+      // Morph between straight → wave → diagonal as scroll progresses
+      if (p < 0.5) {
+        // Interpolate straight → wave
+        morphPath.setAttribute('d', p < 0.25 ? paths.straight : paths.wave);
+      } else {
+        morphPath.setAttribute('d', p < 0.75 ? paths.wave : paths.diagonal);
+      }
+    }
+  });
+}
+```
+
+---
+
+## Pattern 5: Diagonal Wipe Birth {#diagonal-wipe}
+
+Content is revealed by a diagonal sweep across the screen — from top-left corner to bottom-right (or any corner combination). Feels cinematic and directional.
+
+```javascript
+function initDiagonalWipe(el, direction = 'top-left') {
+  const clipPaths = {
+    'top-left': {
+      from: 'polygon(0 0, 0 0, 0 0)',
+      to:   'polygon(0 0, 120% 0, 0 120%)',
+    },
+    'top-right': {
+      from: 'polygon(100% 0, 100% 0, 100% 0)',
+      to:   'polygon(-20% 0, 100% 0, 100% 120%)',
+    },
+    'center-out': {
+      from: 'polygon(50% 50%, 50% 50%, 50% 50%, 50% 50%)',
+      to:   'polygon(-10% -10%, 110% -10%, 110% 110%, -10% 110%)',
+    },
+  };
+
+  const { from, to } = clipPaths[direction];
+
+  gsap.fromTo(el,
+    { clipPath: from },
+    {
+      clipPath: to,
+      duration: 1.4,
+      ease: 'power3.inOut',
+      scrollTrigger: {
+        trigger: el,
+        start: 'top 70%',
+      }
+    }
+  );
+}
+```
+
+---
+
+## Pattern 6: Circle Iris Expand {#circle-iris}
+
+The most dramatic reveal: a perfect circle expands from the center of the section outward, like an aperture opening or a spotlight switching on.
+
+```javascript
+function initCircleIris(el, originX = '50%', originY = '50%') {
+  gsap.fromTo(el,
+    { clipPath: `circle(0% at ${originX} ${originY})` },
+    {
+      clipPath: `circle(80% at ${originX} ${originY})`,
+      ease: 'none',
+      scrollTrigger: {
+        trigger: el,
+        start: 'top 75%',
+        end: 'top 25%',
+        scrub: 1,
+      }
+    }
+  );
+}
+
+// Variant: iris opens from cursor position on hover
+function initHoverIris(el) {
+  el.addEventListener('mouseenter', (e) => {
+    const rect = el.getBoundingClientRect();
+    const x = ((e.clientX - rect.left) / rect.width * 100).toFixed(1) + '%';
+    const y = ((e.clientY - rect.top) / rect.height * 100).toFixed(1) + '%';
+
+    gsap.fromTo(el,
+      { clipPath: `circle(0% at ${x} ${y})` },
+      { clipPath: `circle(100% at ${x} ${y})`, duration: 0.6, ease: 'power2.out' }
+    );
+  });
+}
+```
+
+---
+
+## Pattern 7: Multi-Directional Stagger Grid {#multi-direction}
+
+When a grid or set of cards appears, each item enters from a different edge/direction — creating a dynamic assembly effect instead of uniform fade-ups.
+
+```javascript
+function initMultiDirectionalGrid(gridEl) {
+  const items = gsap.utils.toArray('.grid-item', gridEl);
+
+  const directions = [
+    { x: -80, y: 0 },   // from left
+    { x: 0, y: -80 },   // from top
+    { x: 80, y: 0 },    // from right
+    { x: 0, y: 80 },    // from bottom
+    { x: -60, y: -60 }, // from top-left
+    { x: 60, y: -60 },  // from top-right
+    { x: -60, y: 60 },  // from bottom-left
+    { x: 60, y: 60 },   // from bottom-right
+  ];
+
+  items.forEach((item, i) => {
+    const dir = directions[i % directions.length];
+
+    gsap.from(item, {
+      x: dir.x,
+      y: dir.y,
+      opacity: 0,
+      duration: 0.8,
+      ease: 'power3.out',
+      scrollTrigger: {
+        trigger: gridEl,
+        start: 'top 75%',
+      },
+      delay: i * 0.08, // stagger
+    });
+  });
+}
+```
+
+---
+
+## Pattern 8: Loading Screen Curtain Lift {#loading-screen}
+
+A full-viewport branded intro screen that physically lifts off the page on load, revealing the site beneath. Sets cinematic expectations before any scroll animation begins.
+
+```css
+.loading-curtain {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  background: #0a0a0a; /* or brand color */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Split into two halves for dramatic split-open effect */
+}
+
+.curtain-top {
+  position: absolute;
+  top: 0; left: 0; right: 0;
+  height: 50%;
+  background: inherit;
+  transform-origin: top center;
+}
+
+.curtain-bottom {
+  position: absolute;
+  bottom: 0; left: 0; right: 0;
+  height: 50%;
+  background: inherit;
+  transform-origin: bottom center;
+}
+```
+
+```javascript
+function initLoadingCurtain() {
+  const curtainTop = document.querySelector('.curtain-top');
+  const curtainBottom = document.querySelector('.curtain-bottom');
+  const curtainLogo = document.querySelector('.curtain-logo');
+  const loadingScreen = document.querySelector('.loading-curtain');
+
+  // Prevent scroll during loading
+  document.body.style.overflow = 'hidden';
+
+  const tl = gsap.timeline({
+    delay: 0.5,
+    onComplete: () => {
+      document.body.style.overflow = '';
+      loadingScreen.style.display = 'none';
+      // Init all scroll animations AFTER curtain lifts
+      initAllAnimations();
+    }
+  });
+
+  // Logo appears first
+  tl.from(curtainLogo, { opacity: 0, scale: 0.8, duration: 0.6, ease: 'power2.out' })
+    // Brief hold
+    .to({}, { duration: 0.4 })
+    // Logo fades out
+    .to(curtainLogo, { opacity: 0, scale: 1.1, duration: 0.4, ease: 'power2.in' })
+    // Curtain splits: top goes up, bottom goes down
+    .to(curtainTop, { yPercent: -100, duration: 0.9, ease: 'power4.inOut' }, '-=0.1')
+    .to(curtainBottom, { yPercent: 100, duration: 0.9, ease: 'power4.inOut' }, '<');
+}
+
+window.addEventListener('load', initLoadingCurtain);
+```
+
+---
+
+## Combining Directional Reveals
+
+For maximum cinematic impact, chain directional reveals between sections:
+
+```
+Section 1 → Section 2: Window pane iris (section 2 peeks through a keyhole)
+Section 2 → Section 3: Top-down clip birth (section 3 drops from top)
+Section 3 → Section 4: Diagonal wipe (section 4 sweeps in from corner)
+Section 4 → Section 5: Circle iris (section 5 opens from center)
+Section 5 → Section 6: Curtain panel roll-up (exposes multiple layers)
+```
+
+Each transition feels distinct, keeping the user engaged across the full scroll experience.