sinapse-ai 9.3.0 → 9.4.0

package/squads/squad-animations/knowledge-base/web-animations-api-view-transitions.md

@@ -1,478 +0,0 @@
-# Web Animations API + View Transitions API — Native Browser Animations
-
-> APIs nativas do browser para animacoes sem dependencias externas.
-> Complementam GSAP/Framer Motion com acesso de baixo nivel e zero bundle cost.
-
----
-
-## 1. Web Animations API (WAAPI)
-
-API nativa que expoe o mesmo motor de animacao que CSS usa internamente.
-Zero dependencias, excelente para animacoes programaticas e performance-critical.
-
-### Suporte
-- Chrome 36+, Firefox 48+, Safari 13.1+
-- Suporte completo (incluindo `KeyframeEffect`) em todos os browsers modernos
-
-### Animacao basica
-
-```javascript
-// Equivalente a CSS animation: fadeIn 0.3s ease-out forwards;
-const element = document.querySelector('.card');
-
-const animation = element.animate(
-  [
-    { opacity: 0, transform: 'translateY(20px)' },  // keyframe 0%
-    { opacity: 1, transform: 'translateY(0)' }       // keyframe 100%
-  ],
-  {
-    duration: 300,
-    easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-    fill: 'forwards',     // Manter estado final
-    delay: 0,
-    iterations: 1,
-  }
-);
-
-// Promises para sequenciamento
-await animation.finished;
-// Proximo passo aqui
-```
-
-### Controle imperativo (vantagem sobre CSS)
-
-```javascript
-const animation = element.animate(keyframes, options);
-
-animation.pause();           // Pausar
-animation.play();            // Reproduzir
-animation.reverse();         // Inverter direcao
-animation.cancel();          // Cancelar (volta ao estado original)
-animation.finish();          // Pular para o fim
-
-// Controlar tempo diretamente
-animation.currentTime = 150; // Ir para 150ms
-animation.playbackRate = 2;  // Velocidade 2x
-
-// Estado
-animation.playState;   // "running" | "paused" | "finished" | "idle"
-animation.ready;       // Promise que resolve quando comeca
-animation.finished;    // Promise que resolve quando termina
-```
-
-### Keyframe Effects — Composicao
-
-```javascript
-// KeyframeEffect permite reutilizar keyframes
-const fadeInKeyframes = new KeyframeEffect(
-  null,  // Elemento adicionado depois
-  [{ opacity: 0 }, { opacity: 1 }],
-  { duration: 300, fill: 'forwards' }
-);
-
-// Reutilizar para multiplos elementos
-document.querySelectorAll('.card').forEach((card, index) => {
-  const effect = new KeyframeEffect(
-    card,
-    fadeInKeyframes.getKeyframes(),
-    {
-      ...fadeInKeyframes.getTiming(),
-      delay: index * 50,  // Stagger
-    }
-  );
-  new Animation(effect, document.timeline).play();
-});
-```
-
-### GroupEffect + SequenceEffect (Animation Worklet)
-
-```javascript
-// Sequencia de animacoes (experimental — Chrome only)
-const group = new GroupEffect([
-  new KeyframeEffect(title, [{ opacity: 0 }, { opacity: 1 }], 500),
-  new KeyframeEffect(subtitle, [{ opacity: 0 }, { opacity: 1 }], { duration: 500, delay: 200 }),
-]);
-new Animation(group).play();
-```
-
-### getAnimations() — Inspecao e Controle
-
-```javascript
-// Pausar TODAS as animacoes de um elemento
-element.getAnimations().forEach(anim => anim.pause());
-
-// Pausar animacoes da pagina inteira (menu "pause animations")
-document.getAnimations().forEach(anim => anim.pause());
-
-// Listar animacoes CSS em andamento
-const cssAnimations = element.getAnimations().filter(a => a instanceof CSSAnimation);
-const cssTransitions = element.getAnimations().filter(a => a instanceof CSSTransition);
-```
-
-### Scroll Timeline (CSS nativa + WAAPI)
-
-```javascript
-// Criar scroll timeline programaticamente
-const scrollTimeline = new ScrollTimeline({
-  source: document.scrollingElement,
-  axis: 'block',  // "block" (vertical) | "inline" (horizontal)
-});
-
-// Animar com scroll como timeline
-element.animate(
-  [
-    { opacity: 0, transform: 'translateY(50px)' },
-    { opacity: 1, transform: 'translateY(0)' }
-  ],
-  {
-    duration: 1000,
-    timeline: scrollTimeline,
-    rangeStart: 'entry 0%',   // Quando elemento entra no viewport
-    rangeEnd: 'entry 100%',   // Quando elemento terminou de entrar
-    fill: 'both',
-  }
-);
-
-// View timeline — para animacoes baseadas em visibilidade de elemento
-const viewTimeline = new ViewTimeline({ subject: element });
-
-otherElement.animate(
-  [{ opacity: 0 }, { opacity: 1 }],
-  {
-    duration: 1000,
-    timeline: viewTimeline,
-    rangeStart: 'entry 20%',
-    rangeEnd: 'entry 80%',
-    fill: 'both',
-  }
-);
-```
-
----
-
-## 2. CSS Scroll-Driven Animations (Native)
-
-CSS puro para animacoes baseadas em scroll. Chrome 115+. Zero JavaScript.
-
-### animation-timeline: scroll()
-
-```css
-/* Barra de progresso de leitura */
-@keyframes progress {
-  from { width: 0%; }
-  to { width: 100%; }
-}
-
-.reading-progress {
-  position: fixed;
-  top: 0; left: 0;
-  height: 4px;
-  background: #0066ff;
-  animation: progress linear;
-  animation-timeline: scroll(root block); /* scroll(elemento eixo) */
-  animation-fill-mode: both;
-}
-```
-
-### animation-timeline: view()
-
-```css
-/* Reveal ao entrar no viewport — zero JS */
-@keyframes reveal {
-  from {
-    opacity: 0;
-    transform: translateY(50px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.scroll-reveal {
-  animation: reveal linear;
-  animation-timeline: view();
-  /* Quando o elemento aparece ate quando termina de aparecer */
-  animation-range: entry 0% entry 100%;
-  animation-fill-mode: both;
-}
-```
-
-### animation-range — Controle Fino
-
-```css
-/* Diferentes ranges para diferentes efeitos */
-
-/* Animar enquanto entra no viewport */
-.fade-in {
-  animation-range: entry 0% entry 50%;
-}
-
-/* Animar enquanto sai do viewport */
-.fade-out {
-  animation-range: exit 0% exit 100%;
-}
-
-/* Conteiner coberto — animar quando conteudo cobre o elemento */
-.parallax-bg {
-  animation-range: cover 0% cover 100%;
-}
-
-/* Intervalo explicito em pixels/% */
-.timed-reveal {
-  animation-range: entry 20% cover 60%;
-}
-```
-
-### Named scroll timelines
-
-```css
-/* Definir timeline em ancestral */
-.scroll-container {
-  overflow: scroll;
-  scroll-timeline: --my-scroll block; /* nome e eixo */
-}
-
-/* Usar timeline nomeada em descendente */
-.animated-child {
-  animation: reveal linear;
-  animation-timeline: --my-scroll;
-  animation-range: entry 0% entry 100%;
-}
-```
-
-### Parallax CSS puro
-
-```css
-.parallax-element {
-  animation: parallax-move linear;
-  animation-timeline: scroll();
-  animation-fill-mode: both;
-}
-
-@keyframes parallax-move {
-  from { transform: translateY(0); }
-  to { transform: translateY(-200px); }
-}
-```
-
-### Suporte e Fallback
-
-```css
-/* Verificar suporte */
-@supports (animation-timeline: scroll()) {
-  .scroll-reveal {
-    animation: reveal linear;
-    animation-timeline: view();
-    animation-range: entry 0% entry 100%;
-  }
-}
-
-/* Fallback para browsers sem suporte */
-.scroll-reveal {
-  /* Estado visivel como default (sem animacao) */
-  opacity: 1;
-  transform: none;
-}
-```
-
----
-
-## 3. View Transitions API
-
-API nativa para transicoes entre paginas e estados UI. Chrome 111+.
-Safari 18+ (cross-document). Firefox em desenvolvimento.
-
-### Same-document View Transitions
-
-```javascript
-// Transicao de estado simples
-function updateContent(newContent) {
-  // Sem suporte — atualiza instantaneamente
-  if (!document.startViewTransition) {
-    updateDOM(newContent);
-    return;
-  }
-
-  // Com suporte — anima a transicao
-  document.startViewTransition(() => {
-    updateDOM(newContent);
-  });
-}
-
-// Com callback apos animacao
-const transition = document.startViewTransition(updateDOM);
-await transition.ready;  // DOM atualizado, animacao iniciada
-await transition.finished; // Animacao completa
-```
-
-### CSS para View Transitions
-
-```css
-/* Pseudo-elements criados automaticamente */
-::view-transition-old(root) {
-  /* O "before" screenshot animando para fora */
-  animation: fade-out 0.25s ease-out;
-}
-
-::view-transition-new(root) {
-  /* O "after" screenshot animando para dentro */
-  animation: fade-in 0.25s ease-in;
-}
-
-@keyframes fade-out {
-  from { opacity: 1; }
-  to   { opacity: 0; }
-}
-
-@keyframes fade-in {
-  from { opacity: 0; }
-  to   { opacity: 1; }
-}
-```
-
-### Elementos nomeados (Shared Element Transitions)
-
-```css
-/* Dar nome a elemento especifico */
-.hero-image {
-  view-transition-name: hero-image;
-}
-
-.product-title {
-  view-transition-name: product-title;
-}
-
-/* Controlar animacao do elemento especifico */
-::view-transition-old(hero-image) {
-  animation: scale-down 0.3s ease-out;
-}
-
-::view-transition-new(hero-image) {
-  animation: scale-up 0.3s ease-out;
-}
-
-@keyframes scale-down {
-  from { transform: scale(1); }
-  to   { transform: scale(0.8); opacity: 0; }
-}
-
-@keyframes scale-up {
-  from { transform: scale(0.8); opacity: 0; }
-  to   { transform: scale(1); }
-}
-```
-
-### Next.js com View Transitions
-
-```tsx
-'use client';
-import { useRouter } from 'next/navigation';
-
-export function ViewTransitionLink({ href, children }) {
-  const router = useRouter();
-
-  const handleClick = (e: React.MouseEvent) => {
-    e.preventDefault();
-
-    if (!document.startViewTransition) {
-      router.push(href);
-      return;
-    }
-
-    document.startViewTransition(() => {
-      router.push(href);
-    });
-  };
-
-  return <a href={href} onClick={handleClick}>{children}</a>;
-}
-```
-
-### Cross-document View Transitions (MPA)
-
-```html
-<!-- Ativar em cada pagina (Chrome 126+) -->
-<meta name="view-transition" content="same-origin" />
-```
-
-```css
-/* CSS e aplicado em ambas as paginas para cross-document */
-.hero {
-  view-transition-name: page-hero;
-}
-
-/* Na pagina de destino, o mesmo elemento com mesmo nome anima */
-```
-
-### Tipos de View Transitions
-
-```javascript
-// Transicoes com tipos diferentes para direcoes
-function navigateForward(href) {
-  document.startViewTransition({
-    update: () => router.push(href),
-    types: ['slide-forward'],       // CSS pode usar @keyframes com tipo
-  });
-}
-
-function navigateBack(href) {
-  document.startViewTransition({
-    update: () => router.push(href),
-    types: ['slide-back'],
-  });
-}
-```
-
-```css
-/* Keyframes seletivos por tipo */
-@keyframes slide-out-left {
-  to { transform: translateX(-100%); }
-}
-
-@keyframes slide-in-right {
-  from { transform: translateX(100%); }
-}
-
-/* Aplicar apenas quando tipo = slide-forward */
-:root:active-view-transition-type(slide-forward) {
-  &::view-transition-old(root) {
-    animation: slide-out-left 0.3s ease-out;
-  }
-  &::view-transition-new(root) {
-    animation: slide-in-right 0.3s ease-out;
-  }
-}
-```
-
----
-
-## 4. Quando Usar Cada API
-
-| Cenario | API Recomendada |
-|---------|----------------|
-| Animacao simples sem dependencias | WAAPI |
-| Scroll reveal CSS-only | CSS Scroll-Driven |
-| Barra de progresso de leitura | CSS Scroll-Driven |
-| Parallax suave sem JS | CSS Scroll-Driven |
-| Page transitions SPA | View Transitions API |
-| Shared element transitions | View Transitions API |
-| Animacoes complexas, timeline | GSAP |
-| Componentes React, micro-interactions | Framer Motion |
-| Controlar/inspecionar CSS animations | WAAPI (getAnimations) |
-| Pausar animacoes (acessibilidade) | WAAPI (document.getAnimations) |
-
----
-
-## 5. Suporte a Browsers (2025-2026)
-
-| API | Chrome | Firefox | Safari | Edge |
-|-----|--------|---------|--------|------|
-| WAAPI basica | 75+ | 63+ | 13.1+ | 79+ |
-| ScrollTimeline/ViewTimeline | 115+ | Em dev | Nao | 115+ |
-| CSS scroll-driven | 115+ | Em dev | Nao | 115+ |
-| View Transitions (same-doc) | 111+ | Em dev | 18+ | 111+ |
-| View Transitions (cross-doc) | 126+ | Em dev | 18+ | 126+ |
-| View Transition types | 125+ | Nao | Nao | 125+ |
-
-**Estrategia de progressive enhancement:** Sempre verificar suporte antes de usar, fornecer fallback funcional.