From a304cf2017b902b033541f05901765b73bc72f7d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 21 Nov 2025 19:57:07 +0000 Subject: [PATCH 1/2] Initial plan From 0b93298ff0ea544950367b4e11ac6e0213ee890d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:05:17 +0000 Subject: [PATCH 2/2] Add webpack config and fix parallax support in PHP Code review fixes: - Added webpack.config.js to properly build src/index.js - Updated my-scroll-block.php to support parallax attributes in render_block filter - Applied Prettier formatting to all files - Verified build, lint, and typecheck all pass Co-authored-by: fellyph <330792+fellyph@users.noreply.github.com> --- .github/workflows/build-plugin.yml | 7 +- .github/workflows/playwright.yml | 4 +- AGENTS.md | 23 +- NOVAS-FUNCIONALIDADES.md | 36 +- PROGRESS-BAR-SUMMARY.md | 83 ++-- READING-PROGRESS-BAR.md | 68 ++- README.md | 17 +- RESUMO-IMPLEMENTACAO.md | 42 +- intructions.md | 71 +-- my-scroll-block.php | 91 ++-- package-lock.json | 43 +- playwright.config.js | 76 +-- src/editor.css | 48 +- src/index.js | 770 ++++++++++++++--------------- src/progress-block/block.json | 81 ++- src/progress-block/editor.css | 39 +- src/progress-block/style.css | 220 ++++----- src/style.css | 615 ++++++++++++----------- tests/README.md | 23 +- tests/global-setup.ts | 84 ++-- tests/global-teardown.ts | 16 +- tests/scroll-block.spec.ts | 622 ++++++++++++----------- tsconfig.json | 34 -- webpack.config.js | 23 + 24 files changed, 1597 insertions(+), 1539 deletions(-) create mode 100644 webpack.config.js diff --git a/.github/workflows/build-plugin.yml b/.github/workflows/build-plugin.yml index 0eca7cb..bcd7de1 100644 --- a/.github/workflows/build-plugin.yml +++ b/.github/workflows/build-plugin.yml @@ -12,7 +12,7 @@ on: jobs: build: runs-on: ubuntu-latest - + steps: - name: Checkout repository uses: actions/checkout@v4 @@ -20,8 +20,8 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: "lts/*" - cache: "npm" + node-version: 'lts/*' + cache: 'npm' - name: Install dependencies run: npm ci @@ -59,4 +59,3 @@ jobs: files: my-scroll-block*.zip env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml index cb43612..af113a9 100644 --- a/.github/workflows/playwright.yml +++ b/.github/workflows/playwright.yml @@ -18,8 +18,8 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: "lts/*" - cache: "npm" + node-version: 'lts/*' + cache: 'npm' - name: Install dependencies run: npm ci diff --git a/AGENTS.md b/AGENTS.md index 14643d3..057ffe4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,10 +83,12 @@ The plugin uses **WordPress block filters** to extend core blocks without creati ### CSS Classes & Frontend **Editor classes:** + - `.scroll-anim-block` - Main animation class - `.scroll-anim-{type}` - Specific animation type class **Frontend rendering:** + - Classes are added by PHP filters in `my-scroll-block.php` (handles dynamic blocks) - JavaScript filters in `src/index.js` handle saved block markup in post editor - CSS scroll timeline rules in `src/style.css` trigger animations @@ -103,20 +105,21 @@ Tests use **Playwright + TypeScript + WordPress Playground**: - **Blueprint** (`blueprint.json`): Contains the initial data to initiate a WordPress Playground instance for testing To run tests individually: + ```bash npx playwright test scroll-block.spec.ts -g "test-name-pattern" ``` ## Key Files & Their Roles -| File | Purpose | -|------|---------| -| [my-scroll-block.php](my-scroll-block.php) | Plugin entry point; enqueues assets; applies render_block filter for frontend class/attr injection | -| [src/index.js](src/index.js) | Block filters for editor integration; attribute registration, UI controls, markup manipulation | -| [src/style.css](src/style.css) | CSS scroll timeline rules for all animation types | -| [src/editor.css](src/editor.css) | Editor UI styles (animation indicator, editor preview) | -| [tests/scroll-block.spec.ts](tests/scroll-block.spec.ts) | End-to-end tests for editor and frontend rendering | -| [tests/global-setup.ts](tests/global-setup.ts) | WordPress Playground startup with plugin mounting | +| File | Purpose | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| [my-scroll-block.php](my-scroll-block.php) | Plugin entry point; enqueues assets; applies render_block filter for frontend class/attr injection | +| [src/index.js](src/index.js) | Block filters for editor integration; attribute registration, UI controls, markup manipulation | +| [src/style.css](src/style.css) | CSS scroll timeline rules for all animation types | +| [src/editor.css](src/editor.css) | Editor UI styles (animation indicator, editor preview) | +| [tests/scroll-block.spec.ts](tests/scroll-block.spec.ts) | End-to-end tests for editor and frontend rendering | +| [tests/global-setup.ts](tests/global-setup.ts) | WordPress Playground startup with plugin mounting | ## When Making Changes @@ -130,6 +133,7 @@ npx playwright test scroll-block.spec.ts -g "test-name-pattern" ### Modifying Block Support Supported blocks are defined in: + - `SUPPORTED_BLOCKS` constant in [src/index.js](src/index.js) - `$supported_blocks` array in [my-scroll-block.php](my-scroll-block.php) (must match) @@ -142,6 +146,7 @@ The animation selector is rendered via `PanelBody` + `SelectControl` components ### Testing New Features Tests run against a real WordPress instance via WordPress Playground. When adding tests: + 1. Use TypeScript for type safety (`npm run typecheck` validates) 2. Ensure WordPress Playground can reach the feature (auto-login, plugin pre-activated) 3. Use page selectors that work with WordPress's block editor DOM @@ -210,4 +215,4 @@ This will install and activate the plugin with the changes from this branch. - The `installPlugin` step automatically installs and activates the plugin - Users can test the changes without needing to set up a local WordPress environment - This mirrors the functionality of the GitHub action in `.github/workflows/pr-playground-comment.yml` but uses branches instead of PR refs -- Important: Use `"refType":"branch"` when referencing branch names, not `"refType":"refname"` (which is used for full refs like `refs/pull/123/head`) \ No newline at end of file +- Important: Use `"refType":"branch"` when referencing branch names, not `"refType":"refname"` (which is used for full refs like `refs/pull/123/head`) diff --git a/NOVAS-FUNCIONALIDADES.md b/NOVAS-FUNCIONALIDADES.md index 3fe3d1e..a2339ca 100644 --- a/NOVAS-FUNCIONALIDADES.md +++ b/NOVAS-FUNCIONALIDADES.md @@ -67,13 +67,13 @@ Uma nova animação de entrada que usa o efeito de desfoque (blur) para criar tr ```css @keyframes scrollBlurIn { - from { - opacity: 0; - filter: blur(10px); + from { + opacity: 0; + filter: blur(10px); } - to { - opacity: 1; - filter: blur(0); + to { + opacity: 1; + filter: blur(0); } } ``` @@ -136,13 +136,15 @@ Novos atributos adicionados aos blocos: Os elementos renderizados incluem: ```html -

+

Conteúdo

``` @@ -156,8 +158,8 @@ Todas as animações usam `animation-timeline: view()` conforme a especificaçã .scroll-anim-fade-in-out { animation-timeline: view(); } - - [data-anim-range="quick"].scroll-anim-fade-in { + + [data-anim-range='quick'].scroll-anim-fade-in { animation-range: entry 0% cover 50%; } } @@ -198,12 +200,15 @@ O plugin respeita as preferências de movimento reduzido: ## 🎓 Exemplos da Documentação Implementados ### ✅ Contact List (In-and-Out) + Implementado com as animações "In & Out" - elementos que animam ao entrar E sair. ### ✅ Animation Range Control + Implementado com os presets de timing e controles custom. ### ✅ Multiple Timeline Ranges + Implementado com as animações In-and-Out que usam ranges diferentes para entry e exit. ## 🚀 Próximos Passos Possíveis @@ -219,4 +224,3 @@ Baseado na documentação, futuras funcionalidades poderiam incluir: --- **Desenvolvido com base na documentação oficial do Chrome e seguindo as melhores práticas de Web Animations API.** - diff --git a/PROGRESS-BAR-SUMMARY.md b/PROGRESS-BAR-SUMMARY.md index 8f6b0cb..c730758 100644 --- a/PROGRESS-BAR-SUMMARY.md +++ b/PROGRESS-BAR-SUMMARY.md @@ -7,6 +7,7 @@ A new **Reading Progress Bar** block has been successfully implemented using CSS ## 📁 Files Created ### Block Files + ``` src/progress-block/ ├── block.json ✅ Block metadata & attributes @@ -16,6 +17,7 @@ src/progress-block/ ``` ### Build Output + ``` build/progress-block/ ├── block.json ✅ Copied block metadata @@ -26,6 +28,7 @@ build/progress-block/ ``` ### Documentation + ``` READING-PROGRESS-BAR.md ✅ Complete user guide PROGRESS-BAR-SUMMARY.md ✅ This file @@ -34,21 +37,24 @@ PROGRESS-BAR-SUMMARY.md ✅ This file ## 🎯 Key Features ### 1. **Scroll Progress Timeline** + - Uses `animation-timeline: scroll(root block)` - Tracks document scroll position - 100% CSS, no JavaScript needed - Runs off main thread for 60fps performance ### 2. **Customization Options** -| Option | Type | Default | Range/Options | -|--------|------|---------|---------------| -| Position | Select | top | top, bottom | -| Bar Height | Range | 4px | 2-20px | -| Bar Color | Color | #3858e9 | Any color + alpha | -| Background Color | Color | #e0e0e0 | Any color + alpha | -| Show Percentage | Toggle | false | true/false | + +| Option | Type | Default | Range/Options | +| ---------------- | ------ | ------- | ----------------- | +| Position | Select | top | top, bottom | +| Bar Height | Range | 4px | 2-20px | +| Bar Color | Color | #3858e9 | Any color + alpha | +| Background Color | Color | #e0e0e0 | Any color + alpha | +| Show Percentage | Toggle | false | true/false | ### 3. **Responsive & Accessible** + - Mobile optimized - Respects `prefers-reduced-motion` - Non-blocking (pointer-events: none) @@ -68,16 +74,19 @@ PROGRESS-BAR-SUMMARY.md ✅ This file } @keyframes progress-bar { - from { transform: scaleX(0); } - to { transform: scaleX(1); } + from { + transform: scaleX(0); + } + to { + transform: scaleX(1); + } } ``` ### HTML Structure ```html -
+
@@ -116,6 +125,7 @@ PROGRESS-BAR-SUMMARY.md ✅ This file ## 🎨 Usage Examples ### Basic Setup + 1. Add "Reading Progress Bar" block to post 2. Configure in sidebar (color, height, position) 3. Publish @@ -124,6 +134,7 @@ PROGRESS-BAR-SUMMARY.md ✅ This file ### Recommended Configurations **Blog Post:** + ``` Position: Top Height: 4px @@ -133,6 +144,7 @@ Percentage: Off ``` **Documentation:** + ``` Position: Top Height: 5px @@ -142,6 +154,7 @@ Percentage: On ``` **Minimal:** + ``` Position: Bottom Height: 2px @@ -152,28 +165,29 @@ Percentage: Off ## 🌐 Browser Support -| Browser | Version | Status | -|---------|---------|--------| -| Chrome | 115+ | ✅ Full Support | -| Edge | 115+ | ✅ Full Support | -| Opera | 101+ | ✅ Full Support | -| Firefox | Experimental | ⏳ Behind Flag | -| Safari | In Development | ⏳ Coming Soon | +| Browser | Version | Status | +| ------- | -------------- | --------------- | +| Chrome | 115+ | ✅ Full Support | +| Edge | 115+ | ✅ Full Support | +| Opera | 101+ | ✅ Full Support | +| Firefox | Experimental | ⏳ Behind Flag | +| Safari | In Development | ⏳ Coming Soon | ### Fallback + - Displays warning message in unsupported browsers - Gracefully degrades (bar hidden but site functional) - No errors or broken layouts ## 📊 Performance Metrics -| Metric | Value | -|--------|-------| -| JS Bundle | 4.3KB (minified) | -| CSS Bundle | 2.3KB (minified) | -| Runtime CPU | <1% additional | -| FPS | Consistent 60fps | -| Render | Off main thread | +| Metric | Value | +| ----------- | ---------------- | +| JS Bundle | 4.3KB (minified) | +| CSS Bundle | 2.3KB (minified) | +| Runtime CPU | <1% additional | +| FPS | Consistent 60fps | +| Render | Off main thread | ## 🎓 Based On @@ -190,14 +204,14 @@ This implementation follows the official Chrome documentation: ## 🔄 Difference from View Timeline -| Feature | Scroll Timeline (Progress Bar) | View Timeline (In-Out Animations) | -|---------|-------------------------------|-----------------------------------| -| **Tracks** | Document scroll position | Element visibility in viewport | -| **Use Case** | Progress indicators, parallax | Entry/exit animations | -| **Syntax** | `scroll(root block)` | `view()` | -| **Range** | 0% (top) to 100% (bottom) | entry/cover/exit ranges | -| **Fixed Position** | Usually yes | Usually no | -| **Multiple Instances** | Typically one per page | Multiple per page | +| Feature | Scroll Timeline (Progress Bar) | View Timeline (In-Out Animations) | +| ---------------------- | ------------------------------ | --------------------------------- | +| **Tracks** | Document scroll position | Element visibility in viewport | +| **Use Case** | Progress indicators, parallax | Entry/exit animations | +| **Syntax** | `scroll(root block)` | `view()` | +| **Range** | 0% (top) to 100% (bottom) | entry/cover/exit ranges | +| **Fixed Position** | Usually yes | Usually no | +| **Multiple Instances** | Typically one per page | Multiple per page | ## 🚀 Next Steps (Optional Enhancements) @@ -213,10 +227,12 @@ Based on Chrome docs, future features could include: ## 📝 Files Modified ### Existing Files Updated + - `/src/index.js` - Added import for progress block - `/my-scroll-block.php` - Added block registration function ### New Files Created + - `/src/progress-block/block.json` - `/src/progress-block/index.js` - `/src/progress-block/editor.css` @@ -261,4 +277,3 @@ npm run playground:start **Implementation Date:** November 10, 2025 **Based On:** [Chrome Developers - Scroll-Driven Animations](https://developer.chrome.com/docs/css-ui/scroll-driven-animations) **Status:** ✅ Complete & Ready for Production - diff --git a/READING-PROGRESS-BAR.md b/READING-PROGRESS-BAR.md index 577b1f6..2bc1819 100644 --- a/READING-PROGRESS-BAR.md +++ b/READING-PROGRESS-BAR.md @@ -29,11 +29,13 @@ A Reading Progress Bar é uma barra fixa que acompanha automaticamente o progres ## ✨ Funcionalidades ### 1. **Rastreamento Automático de Scroll** + - Usa `animation-timeline: scroll(root block)` - Sincronizado perfeitamente com o scroll nativo do navegador - Performance otimizada (roda off main thread) ### 2. **Personalização Completa** + - **Cor da Barra** - Escolha qualquer cor (com suporte a alpha/transparência) - **Cor de Fundo** - Cor da trilha de fundo - **Altura** - De 2px a 20px @@ -41,6 +43,7 @@ A Reading Progress Bar é uma barra fixa que acompanha automaticamente o progres - **Mostrar Porcentagem** - Opcional: exibe % de progresso ### 3. **Sem JavaScript no Frontend** + - 100% CSS puro - Melhor performance - Funciona mesmo com JavaScript desabilitado @@ -58,25 +61,30 @@ A Reading Progress Bar é uma barra fixa que acompanha automaticamente o progres No painel lateral, você verá as seguintes opções: #### **Position** (Posição) + - `Top` - Barra no topo da página (padrão) - `Bottom` - Barra no rodapé da página #### **Bar Height** (Altura da Barra) + - Slider de 2px a 20px - Padrão: 4px - Recomendado: 3-6px para mobile, 4-8px para desktop #### **Progress Bar Color** (Cor da Barra) + - Color picker completo - Suporte a alpha (transparência) - Padrão: `#3858e9` (azul) #### **Background Color** (Cor de Fundo) + - Color picker para a trilha de fundo - Padrão: `#e0e0e0` (cinza claro) - Dica: Use transparência para efeito sutil #### **Show Percentage** (Mostrar Porcentagem) + - Toggle on/off - Exibe número de % no canto direito - Aparece ao passar o mouse @@ -91,6 +99,7 @@ No painel lateral, você verá as seguintes opções: ## 💻 Exemplos de Uso ### Exemplo 1: Blog Post Simples + ``` Configuração: - Position: Top @@ -103,6 +112,7 @@ Resultado: Barra discreta no topo que acompanha a leitura ``` ### Exemplo 2: Artigo Longo com Porcentagem + ``` Configuração: - Position: Top @@ -115,6 +125,7 @@ Resultado: Barra mais visível com indicador de % ao hover ``` ### Exemplo 3: Design Minimalista + ``` Configuração: - Position: Bottom @@ -127,6 +138,7 @@ Resultado: Linha fina e discreta na parte inferior ``` ### Exemplo 4: High Contrast + ``` Configuração: - Position: Top @@ -143,10 +155,12 @@ Resultado: Barra chamativa para dashboards ou apps ### HTML Renderizado ```html -
+ --progress-bg-color: #e0e0e0;" +>
@@ -188,16 +202,17 @@ Resultado: Barra chamativa para dashboards ou apps ### Diferença: scroll() vs view() -| Feature | `scroll()` | `view()` | -|---------|-----------|----------| -| **Base** | Posição do scroll do container | Visibilidade do elemento no viewport | -| **Uso** | Progress bars, parallax global | Animações de entrada/saída | -| **Sintaxe** | `scroll(root block)` | `view()` | -| **Exemplo** | Barra de progresso | Fade in ao aparecer | +| Feature | `scroll()` | `view()` | +| ----------- | ------------------------------ | ------------------------------------ | +| **Base** | Posição do scroll do container | Visibilidade do elemento no viewport | +| **Uso** | Progress bars, parallax global | Animações de entrada/saída | +| **Sintaxe** | `scroll(root block)` | `view()` | +| **Exemplo** | Barra de progresso | Fade in ao aparecer | ## 📱 Responsividade ### Mobile + ```css @media (max-width: 768px) { .reading-progress-percentage { @@ -210,15 +225,16 @@ Resultado: Barra chamativa para dashboards ou apps ### Recomendações por Dispositivo -| Dispositivo | Altura Recomendada | Posição | Percentage | -|-------------|-------------------|----------|------------| -| Mobile | 3-4px | Top | Off | -| Tablet | 4-6px | Top | Optional | -| Desktop | 4-8px | Top ou Bottom | On | +| Dispositivo | Altura Recomendada | Posição | Percentage | +| ----------- | ------------------ | ------------- | ---------- | +| Mobile | 3-4px | Top | Off | +| Tablet | 4-6px | Top | Optional | +| Desktop | 4-8px | Top ou Bottom | On | ## ♿ Acessibilidade ### Reduced Motion + ```css @media (prefers-reduced-motion: reduce) { .reading-progress-bar { @@ -228,6 +244,7 @@ Resultado: Barra chamativa para dashboards ou apps ``` ### Boas Práticas + - ✅ Não interfere com navegação por teclado - ✅ `pointer-events: none` - não bloqueia cliques - ✅ Alto contraste disponível @@ -237,11 +254,13 @@ Resultado: Barra chamativa para dashboards ou apps ## 🌐 Compatibilidade de Navegadores ### Suportado ✅ + - **Chrome 115+** - Suporte completo - **Edge 115+** - Suporte completo - **Opera 101+** - Suporte completo ### Em Desenvolvimento ⏳ + - **Firefox** - Experimental (behind flag) - **Safari** - Em desenvolvimento @@ -261,21 +280,25 @@ Para navegadores sem suporte, o CSS inclui uma mensagem informativa: ## 🎓 Casos de Uso ### 1. **Blog Posts & Articles** + - Ajuda leitores a saberem quanto falta - Melhora engajamento - Reduz bounce rate ### 2. **Documentation** + - Orientação em docs longos - Navegação visual - Indicador de progresso em tutoriais ### 3. **Landing Pages** + - Storytelling com scroll - Indicador de seções - Visual feedback ### 4. **E-learning** + - Progresso de leitura de cursos - Indicador de conclusão - Gamification @@ -283,24 +306,32 @@ Para navegadores sem suporte, o CSS inclui uma mensagem informativa: ## 🔍 Troubleshooting ### Problema: Barra não aparece + **Solução:** + 1. Verifique se está usando Chrome 115+ 2. Publique a página (não funciona no preview) 3. Certifique-se que há conteúdo suficiente para scroll ### Problema: Barra fica sempre cheia + **Solução:** + - A página precisa ter scroll vertical - Adicione mais conteúdo para ultrapassar a altura da viewport ### Problema: Barra não sincroniza suavemente + **Solução:** + 1. Desabilite extensões do navegador que afetam scroll 2. Verifique se não há `scroll-behavior: smooth` conflitante 3. Teste em modo anônimo ### Problema: Percentage não aparece + **Solução:** + 1. Ative "Show Percentage" nas settings 2. Passe o mouse sobre a barra 3. Verifique z-index de outros elementos @@ -308,6 +339,7 @@ Para navegadores sem suporte, o CSS inclui uma mensagem informativa: ## 📊 Performance ### Métricas + - **FPS:** 60fps consistentes (roda off main thread) - **CPU:** < 1% de uso adicional - **Memory:** ~2KB adicional @@ -342,7 +374,9 @@ Possíveis melhorias baseadas na documentação: ## 💡 Tips & Tricks ### Tip 1: Posicionamento com Header Fixo + Se você tem um header fixo, ajuste o z-index: + ```css .reading-progress-container { z-index: 999999; /* Acima do header */ @@ -350,13 +384,17 @@ Se você tem um header fixo, ajuste o z-index: ``` ### Tip 2: Combinar com View Animations + Use junto com as animações in-out para efeito completo: + ``` Progress Bar no topo + Paragraphs com Fade In & Out = ✨ Amazing! ``` ### Tip 3: Cores Temáticas + Combine com a identidade visual do site: + ``` Blog Tech: #3858e9 (azul tech) Blog Natureza: #00b894 (verde) @@ -364,6 +402,7 @@ Blog Minimalista: #2d3436 (preto) ``` ### Tip 4: Altura por Contexto + ``` Mobile: 3px (discreto) Desktop: 5px (mais visível) @@ -379,4 +418,3 @@ O Reading Progress Bar é uma implementação moderna e performática de indicad **Criado com base em:** [Chrome Developers - Scroll-Driven Animations](https://developer.chrome.com/docs/css-ui/scroll-driven-animations) **Data:** 10/11/2025 **Versão:** 1.0.0 - diff --git a/README.md b/README.md index e58cde4..02c36c2 100644 --- a/README.md +++ b/README.md @@ -32,22 +32,26 @@ A WordPress plugin that adds scroll-driven animation capabilities to core blocks ### For Development 1. Clone the repository: + ```bash git clone cd my-scroll-block ``` 2. Install dependencies: + ```bash npm install ``` 3. Build the plugin: + ```bash npm run build ``` 4. Start development mode (with live reload): + ```bash npm start ``` @@ -55,11 +59,13 @@ npm start ### For Production 1. Build the plugin: + ```bash npm run build ``` 2. Create a zip file: + ```bash npm run plugin-zip ``` @@ -90,16 +96,19 @@ This project uses Playwright with TypeScript for end-to-end testing with WordPre ### Setup Tests 1. Install Playwright browsers: + ```bash npx playwright install --with-deps chromium ``` 2. Run tests: + ```bash npm test ``` 3. Check TypeScript types: + ```bash npm run typecheck ``` @@ -109,6 +118,7 @@ For more details, see [tests/README.md](tests/README.md) ### TypeScript Support Tests are written in TypeScript for: + - ✅ Type safety and error prevention - ✅ Better IDE autocomplete - ✅ Self-documenting code @@ -129,6 +139,7 @@ See [TYPESCRIPT_MIGRATION.md](../TYPESCRIPT_MIGRATION.md) for migration details. ### On the Frontend When a block has a scroll animation: + - The plugin adds CSS classes: `scroll-anim-block` and `scroll-anim-{type}` - A data attribute `data-scroll-anim="1"` is added - CSS scroll timeline rules trigger the animation as you scroll @@ -156,6 +167,7 @@ my-scroll-block/ ## Browser Support This plugin uses modern CSS features including: + - CSS Scroll Timelines - View Timeline - Animation Timeline @@ -176,6 +188,7 @@ Contributions are welcome! Please: ## Continuous Integration The project uses GitHub Actions for CI: + - Runs on every push and pull request - Tests with Chromium only - Uploads test reports on failure @@ -187,6 +200,7 @@ GPL-2.0-or-later ## Credits Built with: + - [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts) - [Playwright](https://playwright.dev/) - [WordPress Playground](https://github.com/WordPress/wordpress-playground) @@ -194,6 +208,7 @@ Built with: ## Support For issues and questions: + - Check the [tests/README.md](tests/README.md) for testing documentation - Review existing GitHub issues - Create a new issue with detailed information @@ -201,9 +216,9 @@ For issues and questions: ## Changelog ### 0.1.0 + - Initial release - Support for 8 animation types - Block editor integration - CSS scroll timeline animations - Playwright test coverage - diff --git a/RESUMO-IMPLEMENTACAO.md b/RESUMO-IMPLEMENTACAO.md index 7e39b94..e020fce 100644 --- a/RESUMO-IMPLEMENTACAO.md +++ b/RESUMO-IMPLEMENTACAO.md @@ -28,6 +28,7 @@ Animações que funcionam tanto na entrada quanto na saída do viewport: ### 4. 🎛️ Controles Custom Avançados Quando "Custom" é selecionado: + - Entry Start (%) - Controla início da animação de entrada - Entry End (%) - Controla fim da animação de entrada - Exit Start (%) - Controla início da animação de saída (apenas in-out) @@ -36,7 +37,9 @@ Quando "Custom" é selecionado: ## 📁 Arquivos Modificados ### `/src/index.js` + **Mudanças:** + - Adicionados novos imports: `RangeControl`, `ToggleControl` - Expandido `ANIMATION_OPTIONS` com 5 novas opções - Criado `RANGE_OPTIONS` com 5 presets @@ -53,7 +56,9 @@ Quando "Custom" é selecionado: - Atualizados filtros `getSaveContent.extraProps` e `BlockListBlock` para incluir data attributes de range ### `/src/style.css` + **Mudanças:** + - Adicionado suporte para `.scroll-anim-blur-in` - Adicionadas 4 novas classes in-out: - `.scroll-anim-fade-in-out` @@ -72,7 +77,9 @@ Quando "Custom" é selecionado: - `@keyframes scrollRotateInOut` ### `/my-scroll-block.php` + **Mudanças:** + - Atualizado filtro `render_block` para: - Capturar `animationRange` attribute - Adicionar `data-anim-range` ao HTML @@ -110,13 +117,15 @@ Browser executa animações usando scroll-timeline ### Exemplo de HTML Renderizado ```html -

+

Conteúdo do parágrafo

``` @@ -155,43 +164,54 @@ Browser executa animações usando scroll-timeline ## ✅ Testes Realizados ### Build + ```bash npm run build ``` + **Resultado:** ✅ Compilado com sucesso sem erros ### Linter + ```bash # Verificado automaticamente ``` + **Resultado:** ✅ Sem erros de lint ### Verificação de Assets Compilados **JavaScript:** + ```bash grep "Fade In & Out|Blur In" build/index.js ``` + **Resultado:** ✅ Novas opções presentes no código compilado **CSS:** + ```bash grep "fade-in-out|blur-in" build/style-index.css ``` + **Resultado:** ✅ Novas classes e keyframes presentes ## 🚀 Como Testar (Manual) ### Passo 1: Iniciar WordPress Playground + ```bash cd my-scroll-block npm run playground:start ``` ### Passo 2: Acessar Editor + Navegue para: http://127.0.0.1:9400/wp-admin/post-new.php ### Passo 3: Testar Animações Simples + 1. Adicione um bloco Paragraph 2. No painel lateral "Scroll Animation": - Selecione "Blur In" @@ -200,6 +220,7 @@ Navegue para: http://127.0.0.1:9400/wp-admin/post-new.php 4. Publique e visualize ### Passo 4: Testar Animações In-Out + 1. Adicione novo bloco Paragraph 2. Selecione "🔄 Fade In & Out" 3. Note o emoji 🔄 indicando animação bidirecional @@ -207,6 +228,7 @@ Navegue para: http://127.0.0.1:9400/wp-admin/post-new.php 5. Publique e role para ver entrada E saída ### Passo 5: Testar Custom Timing + 1. Adicione novo bloco 2. Selecione "🔄 Scale In & Out" 3. Em "Animation Timing", selecione "Custom" @@ -232,20 +254,24 @@ Navegue para: http://127.0.0.1:9400/wp-admin/post-new.php ## 🎓 Referências da Documentação Implementadas ### ✅ Implementado: Contact List Pattern + - **Fonte:** [Chrome Docs - Contact List Demo](https://developer.chrome.com/docs/css-ui/scroll-driven-animations#demo_contact_list) - **Implementação:** Animações In-and-Out com sintaxe `entry`/`exit` ### ✅ Implementado: Animation Range Control + - **Fonte:** [Chrome Docs - View Timeline Range](https://developer.chrome.com/docs/css-ui/scroll-driven-animations#view-timelines) - **Implementação:** 5 presets + custom sliders ### ✅ Implementado: Multiple Timeline Ranges + - **Fonte:** [Chrome Docs - Attaching to Multiple Ranges](https://developer.chrome.com/docs/css-ui/scroll-driven-animations#attaching_to_multiple_view_timeline_ranges) - **Implementação:** Keyframes com ranges separados para entry e exit ## 🔄 Compatibilidade ### Browsers Suportados + - ✅ Chrome 115+ - ✅ Edge 115+ - ✅ Opera 101+ @@ -253,6 +279,7 @@ Navegue para: http://127.0.0.1:9400/wp-admin/post-new.php - ⏳ Safari (em desenvolvimento) ### Graceful Degradation + - CSS usa `@supports (animation-timeline: view())` - Browsers não suportados: elementos aparecem sem animação - Acessibilidade: `@media (prefers-reduced-motion)` respeitado @@ -275,4 +302,3 @@ A implementação foi concluída com sucesso, adicionando funcionalidades avanç **Data da implementação:** 10/11/2025 **Baseado em:** [Chrome Developers - Scroll-driven Animations](https://developer.chrome.com/docs/css-ui/scroll-driven-animations) - diff --git a/intructions.md b/intructions.md index 7937ffe..0c013a9 100644 --- a/intructions.md +++ b/intructions.md @@ -1,38 +1,43 @@ -# Product Requirements Document (PRD) +# Product Requirements Document (PRD) + **Feature:** Scroll-Driven Animation Effects for Gutenberg Blocks **Author:** [Fellyph Cintra] **Date:** [Aug 08th, 2025] -**Version:** 1.0 +**Version:** 1.0 --- -## 1. Overview -The goal is to enable WordPress Gutenberg users to easily apply **scroll-driven animations** to selected block types (Images, Paragraphs, Columns, and Groups) directly from the block’s **Settings Panel**. Animations will trigger as the element scrolls into view, with user-configurable transition type, delay, and duration. +## 1. Overview + +The goal is to enable WordPress Gutenberg users to easily apply **scroll-driven animations** to selected block types (Images, Paragraphs, Columns, and Groups) directly from the block’s **Settings Panel**. Animations will trigger as the element scrolls into view, with user-configurable transition type, delay, and duration. This will allow content creators to add modern, engaging visual effects without requiring custom CSS or JavaScript knowledge. --- -## 2. Objectives -- Provide an **intuitive UI** for selecting and configuring animation properties. -- Support a set of **predefined animation types** inspired by CSS Scroll-Driven Animations (e.g., fade, slide, scale, rotate). +## 2. Objectives + +- Provide an **intuitive UI** for selecting and configuring animation properties. +- Support a set of **predefined animation types** inspired by CSS Scroll-Driven Animations (e.g., fade, slide, scale, rotate). - Allow customization of: - **Transition Type** - **Delay** (in ms) -- Ensure **accessibility and performance** best practices. -- Maintain compatibility with **core Gutenberg block styles**. +- Ensure **accessibility and performance** best practices. +- Maintain compatibility with **core Gutenberg block styles**. --- -## 3. Scope +## 3. Scope ### 3.1 Supported Blocks + - Core Image Block - Core Paragraph Block - Core Columns Block - Core Group Block ### 3.2 Supported Animation Types (examples) + - Fade In - Slide In (left, right, up, down) - Scale Up / Scale Down @@ -41,23 +46,25 @@ This will allow content creators to add modern, engaging visual effects without --- -## 4. User Stories +## 4. User Stories -1. **As a content creator**, I want to select an animation type for the core blocks, image, paragraph, column and group. So that it animates when it scrolls into view. -2. **As a designer**, I want to configure the delay of the animation to match my site’s visual style. -3. **As a site owner**, I want to enable animations without affecting performance or accessibility. +1. **As a content creator**, I want to select an animation type for the core blocks, image, paragraph, column and group. So that it animates when it scrolls into view. +2. **As a designer**, I want to configure the delay of the animation to match my site’s visual style. +3. **As a site owner**, I want to enable animations without affecting performance or accessibility. --- -## 5. Functional Requirements +## 5. Functional Requirements ### 5.1 UI Requirements + - Add a **“Scroll Animation”** panel to the Gutenberg core block settings sidebar when a supported blocks, image, paragraph, column and group are selected. - The panel contains: - **Animation Type** (Dropdown: “None”, “Fade In”, “Slide In Left”, “Slide In Right”, “Slide In Up”, “Slide In Down”, “Scale Up”, “Rotate In”, etc.) - **Delay** (Number input in milliseconds) ### 5.2 Technical Requirements + - Use CSS `@scroll-timeline` and `animation-timeline` if browser supports it, with JavaScript fallback for compatibility. - Apply animation styles **only** when the block is in the viewport. - Store animation settings in the block’s attributes. @@ -67,13 +74,15 @@ This will allow content creators to add modern, engaging visual effects without --- ## 6. Non-Functional Requirements + - **Performance:** Minimize JavaScript payload; only load when animation is enabled for a block. - **Accessibility:** Ensure animations respect `prefers-reduced-motion` media query. - **Browser Support:** Modern browsers (Chrome, Edge, Firefox, Safari). Graceful degradation for unsupported browsers. --- -## 7. Example Attribute Schema +## 7. Example Attribute Schema + ```json { "animationType": { @@ -90,19 +99,19 @@ This will allow content creators to add modern, engaging visual effects without ## 8. Example CSS/JS Implementation Outline ### 8.1 CSS Example -```css - @property --anim-displacement { - syntax: ''; - inherits: false; - initial-value: 20px; - } +```css +@property --anim-displacement { + syntax: ''; + inherits: false; + initial-value: 20px; +} - @property --anim-delay { - syntax: '