From 91fc74e40b64f0d563368a411543670b1938af66 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:46:02 +0000 Subject: [PATCH 1/4] Initial plan From 5c4bc124629856bb534785823193e3f0ba67b222 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:48:29 +0000 Subject: [PATCH 2/4] Initial analysis of Playwright test improvements Co-authored-by: fellyph <330792+fellyph@users.noreply.github.com> --- package-lock.json | 43 +++---------------------------------------- 1 file changed, 3 insertions(+), 40 deletions(-) diff --git a/package-lock.json b/package-lock.json index bbb7ade..946ebe1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -67,7 +67,6 @@ "integrity": "sha512-yJ474Zv3cwiSOO9nXJuqzvwEeM+chDuQ8GJirw+pZ91sCGCyOZ3dJkVE09fTV0VEVzXyLWhh3G/AolYTPX7Mow==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@ampproject/remapping": "^2.2.0", "@babel/code-frame": "^7.25.7", @@ -2010,7 +2009,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" }, @@ -2034,7 +2032,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" } @@ -3469,7 +3466,6 @@ "integrity": "sha512-/g2d4sW9nUDJOMz3mabVQvOGhVa4e/BN/Um7yca9Bb2XTzPPnfTWHWQg+IsEYO7M3Vx+EXvaM/I2pJWIMun1bg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@octokit/auth-token": "^4.0.0", "@octokit/graphql": "^7.1.0", @@ -3845,7 +3841,6 @@ "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", "dev": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=8.0.0" } @@ -3869,7 +3864,6 @@ "integrity": "sha512-s5vvxXPVdjqS3kTLKMeBMvop9hbWkwzBpu+mUO2M7sZtlkyDJGwFe33wRKnbaYDo8ExRVBIIdwIGrqpxHuKttA==", "dev": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=14" }, @@ -3883,7 +3877,6 @@ "integrity": "sha512-OOCM2C/QIURhJMuKaekP3TRBxBKxG/TWWA0TL2J6nXUtDnuCtccy49LUJF8xPFXMX+0LMcxFpCo8M9cGY1W6rQ==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/semantic-conventions": "1.28.0" }, @@ -4366,7 +4359,6 @@ "integrity": "sha512-5UxZqiAgLYGFjS4s9qm5mBVo433u+dSPUFWVWXmLAD4wB65oMCoXaJP1KJa9DIYYMeHu3z4BZcStG3LC593cWA==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/core": "1.30.1", "@opentelemetry/semantic-conventions": "1.28.0" @@ -4394,7 +4386,6 @@ "integrity": "sha512-jVPgBbH1gCy2Lb7X0AVQ8XAfgg0pJ4nvl8/IiQA6nxOsPvS+0zMJaFSs2ltXe0J6C8dqjcnpyqINDJmU30+uOg==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/core": "1.30.1", "@opentelemetry/resources": "1.30.1", @@ -4423,7 +4414,6 @@ "integrity": "sha512-TtxJSRD8Ohxp6bKkhrm27JRHAxPczQA7idtcTOMYI+wQRRrfgqxHv1cFbCApcSnNjtXkmzFozn6jQtFrOmbjPQ==", "dev": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=14" } @@ -5153,7 +5143,6 @@ "integrity": "sha512-Tzh95Twig7hUwwNe381/K3PggZBZblKUe2wv25oIpzWLr6Z0m4KgV1ZVIjnR6GM9ANEqjZD7XsZEa6JL/7YEgg==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "playwright": "1.56.0" }, @@ -5646,7 +5635,6 @@ "integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@babel/core": "^7.21.3", "@svgr/babel-preset": "8.1.0", @@ -5883,7 +5871,6 @@ "integrity": "sha512-FXx2pKgId/WyYo2jXw63kk7/+TY7u7AziEJxJAnSFzHlqTAS3Ync6SvgYAN/k4/PQpnnVuzoMuVnByKK2qp0ag==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/estree": "*", "@types/json-schema": "*" @@ -6284,7 +6271,6 @@ "integrity": "sha512-u6kMFSBM9HcoTpUXnL6mt2HSzftqb3JgYV6oxIgL2dl6sX6aCa5k6SOkzv5DuZjBTPUE/dJltKtwwuqrkZHpfw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/node": "*", "@types/tapable": "^1", @@ -6409,7 +6395,6 @@ "integrity": "sha512-tbsV1jPne5CkFQCgPBcDOt30ItF7aJoZL997JSF7MhGQqOeT3svWRYxiqlfA5RUdlHN6Fi+EI9bxqbdyAUZjYQ==", "dev": true, "license": "BSD-2-Clause", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "6.21.0", "@typescript-eslint/types": "6.21.0", @@ -7832,7 +7817,6 @@ "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "dev": true, "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -7940,7 +7924,6 @@ "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -8947,7 +8930,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "caniuse-lite": "^1.0.30001726", "electron-to-chromium": "^1.5.173", @@ -10654,8 +10636,7 @@ "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1478340.tgz", "integrity": "sha512-EqhRVWo+j3O1a5LEvZi5fFlBRhvciqYoCHpsEfPcIpA/Abh0W1LF+V3AIvQD9Z4Apj0+p3U07vb7uXfn2hm3HQ==", "dev": true, - "license": "BSD-3-Clause", - "peer": true + "license": "BSD-3-Clause" }, "node_modules/diff-sequences": { "version": "29.6.3", @@ -11302,7 +11283,6 @@ "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", "@eslint-community/regexpp": "^4.6.1", @@ -11359,7 +11339,6 @@ "integrity": "sha512-/IGJ6+Dka158JnP5n5YFMOszjDWrXggGz1LaK/guZq9vZTmniaKlHcsscvkAhn9y4U+BU3JuUdYvtAMcv30y4A==", "dev": true, "license": "MIT", - "peer": true, "bin": { "eslint-config-prettier": "bin/cli.js" }, @@ -14736,7 +14715,6 @@ "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@jest/core": "^29.7.0", "@jest/types": "^29.6.3", @@ -15899,8 +15877,7 @@ "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1475386.tgz", "integrity": "sha512-RQ809ykTfJ+dgj9bftdeL2vRVxASAuGU+I9LEx9Ij5TXU5HrgAQVmzi72VA+mkzscE12uzlRv5/tWWv9R9J1SA==", "dev": true, - "license": "BSD-3-Clause", - "peer": true + "license": "BSD-3-Clause" }, "node_modules/lighthouse/node_modules/puppeteer-core/node_modules/ws": { "version": "8.18.3", @@ -17006,7 +16983,6 @@ "integrity": "sha512-cuXAJJB1Rdqz0UO6w524matlBqDBjcNt7Ru+RDIu4y6RI1gVqiWBnylrK8sPRk81gGBA0X8hJbDXolVOoTc+sA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "ajv": "^6.12.6", "ajv-errors": "^1.0.1", @@ -18038,7 +18014,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -18763,7 +18738,6 @@ "resolved": "https://registry.npmjs.org/preact/-/preact-10.27.0.tgz", "integrity": "sha512-/DTYoB6mwwgPytiqQTh/7SFRL98ZdiD8Sk8zIUVOxtwq4oWcwrcd1uno9fE/zZmUaUrFNYzbH14CPebOz9tZQw==", "license": "MIT", - "peer": true, "funding": { "type": "opencollective", "url": "https://opencollective.com/preact" @@ -18785,7 +18759,6 @@ "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==", "dev": true, "license": "MIT", - "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -19178,7 +19151,6 @@ "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "loose-envify": "^1.1.0" }, @@ -19214,7 +19186,6 @@ "integrity": "sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -19834,7 +19805,6 @@ "integrity": "sha512-9GUyuksjw70uNpb1MTYWsH9MQHOHY6kwfnkafC24+7aOMZn9+rVMBxRbLvw756mrBFbIsFg6Xw9IkR2Fnn3k+Q==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "chokidar": "^4.0.0", "immutable": "^5.0.2", @@ -19917,6 +19887,7 @@ "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "loose-envify": "^1.1.0" } @@ -19947,7 +19918,6 @@ "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -21151,7 +21121,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "@csstools/css-parser-algorithms": "^3.0.5", "@csstools/css-tokenizer": "^3.0.4", @@ -21487,7 +21456,6 @@ "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -22217,7 +22185,6 @@ "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", "dev": true, "license": "(MIT OR CC0-1.0)", - "peer": true, "engines": { "node": ">=10" }, @@ -22330,7 +22297,6 @@ "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==", "dev": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -22765,7 +22731,6 @@ "integrity": "sha512-B4t+nJqytPeuZlHuIKTbalhljIFXeNRqrUGAQgTGlfOl2lXXKXw+yZu6bicycP+PUlM44CxBjCFD6aciKFT3LQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/eslint-scope": "^3.7.7", "@types/estree": "^1.0.8", @@ -22874,7 +22839,6 @@ "integrity": "sha512-pIDJHIEI9LR0yxHXQ+Qh95k2EvXpWzZ5l+d+jIo+RdSm9MiHfzazIxwwni/p7+x4eJZuvG1AJwgC4TNQ7NRgsg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@discoveryjs/json-ext": "^0.5.0", "@webpack-cli/configtest": "^2.1.1", @@ -22955,7 +22919,6 @@ "integrity": "sha512-0XavAZbNJ5sDrCbkpWL8mia0o5WPOd2YGtxrEiZkBK9FjLppIUK2TgxK6qGD2P3hUXTJNNPVibrerKcx5WkR1g==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/bonjour": "^3.5.9", "@types/connect-history-api-fallback": "^1.3.5", From 3c3c7222b4a2aaa97d5949df2f063d46f0793a6d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:53:52 +0000 Subject: [PATCH 3/4] Improve Playwright test reliability and robustness - Add helper functions to reduce code duplication - Replace brittle selectors with role-based selectors - Enhance wait strategies with proper waitFor conditions - Add comprehensive assertions for UI state and behavior - Increase test coverage with new tests for timing and parallax - Update Playwright config with better timeouts and debugging - Document improvements in tests/README.md Co-authored-by: fellyph <330792+fellyph@users.noreply.github.com> --- .github/agents/gutenberg-fixer.agent.md | 7 +- .github/workflows/build-plugin.yml | 7 +- .github/workflows/gemini-dispatch.yml | 2 +- .github/workflows/playwright.yml | 4 +- AGENTS.md | 23 +- README.md | 17 +- instructions/PROGRESS-BAR-SUMMARY.md | 83 ++- instructions/READING-PROGRESS-BAR.md | 68 +- instructions/RESUMO-IMPLEMENTACAO.md | 42 +- instructions/intructions.md | 71 +- playwright.config.js | 90 +-- 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 | 265 +++++++- tests/global-setup.ts | 84 +-- tests/global-teardown.ts | 16 +- tests/scroll-block.spec.ts | 867 +++++++++++++++--------- tsconfig.json | 11 +- 22 files changed, 1980 insertions(+), 1450 deletions(-) diff --git a/.github/agents/gutenberg-fixer.agent.md b/.github/agents/gutenberg-fixer.agent.md index 36da40d..22c8430 100644 --- a/.github/agents/gutenberg-fixer.agent.md +++ b/.github/agents/gutenberg-fixer.agent.md @@ -6,7 +6,7 @@ name: gutenberg-fixer description: "Fixes issues in a WordPress Gutenberg block project, following the project's coding standards." -tools: ["read", "edit", "search", "shell"] +tools: ['read', 'edit', 'search', 'shell'] --- # My Agent @@ -25,12 +25,14 @@ Before making any changes, carefully analyze the existing code, project structur ## Coding Standards ### CSS + - Use BEM-inspired naming: `package-directory__element--modifier`. - Prefix class names with the package name to avoid collisions. - Separate styles: `style.scss` (frontend + editor), `editor.scss` (editor-only). - Use `is-` prefix for state modifiers (e.g., `is-active`). ### JavaScript + - Use functional components with hooks. - Organize imports: External dependencies, then WordPress dependencies, then internal dependencies. - Prefer stable APIs over experimental ones. @@ -38,6 +40,7 @@ Before making any changes, carefully analyze the existing code, project structur - Use single quotes for strings. ### PHP + - Follow WordPress VIP coding standards. - Use proper namespacing and PSR-4 autoloading. - Include comprehensive docblocks. @@ -50,7 +53,7 @@ Before making any changes, carefully analyze the existing code, project structur - `npm run format`: To format the code. - `npm run lint:css`: To lint CSS/SCSS files. - `npm run lint:php`: To lint PHP files. -4. **Run the code on Playground**: After fixing and verifying the code, check if the application is running: +4. **Run the code on Playground**: After fixing and verifying the code, check if the application is running: - `npm run playground:start` Please always make sure your changes do not introduce any new issues and fully resolve the original problem. 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/gemini-dispatch.yml b/.github/workflows/gemini-dispatch.yml index 22d0b27..728715f 100644 --- a/.github/workflows/gemini-dispatch.yml +++ b/.github/workflows/gemini-dispatch.yml @@ -25,7 +25,7 @@ defaults: jobs: debugger: if: |- - ${{ fromJSON(vars.DEBUG || vars.ACTIONS_STEP_DEBUG || false) }} + ${{ fromJSON(vars.DEBUG || vars.ACTIONS_STEP_DEBUG || false) }} runs-on: 'ubuntu-latest' permissions: contents: 'read' 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/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/instructions/PROGRESS-BAR-SUMMARY.md b/instructions/PROGRESS-BAR-SUMMARY.md index 8f6b0cb..c730758 100644 --- a/instructions/PROGRESS-BAR-SUMMARY.md +++ b/instructions/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/instructions/READING-PROGRESS-BAR.md b/instructions/READING-PROGRESS-BAR.md index 577b1f6..2bc1819 100644 --- a/instructions/READING-PROGRESS-BAR.md +++ b/instructions/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/instructions/RESUMO-IMPLEMENTACAO.md b/instructions/RESUMO-IMPLEMENTACAO.md index 7e39b94..e020fce 100644 --- a/instructions/RESUMO-IMPLEMENTACAO.md +++ b/instructions/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/instructions/intructions.md b/instructions/intructions.md index 7937ffe..0c013a9 100644 --- a/instructions/intructions.md +++ b/instructions/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: '