templates-patterns-collection
Last commit date
assets
2 weeks ago
beaver
1 year ago
e2e-tests
1 week ago
editor
1 year ago
elementor
1 year ago
includes
1 week ago
languages
1 week ago
migration
5 years ago
onboarding
1 week ago
shared
2 years ago
vendor
1 week ago
.browserslistrc
1 year ago
.eslintrc
1 year ago
AGENTS.md
1 week ago
CHANGELOG.md
1 week ago
CONTRIBUTING.md
2 years ago
README.md
1 week ago
phpstan.neon
2 weeks ago
readme.txt
1 week ago
templates-patterns-collection.php
1 week ago
yarn.lock
1 year ago
AGENTS.md
149 lines
| 1 | # Agent Workflow |
| 2 | |
| 3 | ## Project Overview |
| 4 | |
| 5 | Templates Patterns Collection is a WordPress plugin that powers ThemeIsle's starter sites, page templates, block patterns, and onboarding flows for Neve. It combines PHP import/orchestration code with multiple React-based admin/editor integrations for Gutenberg, Elementor, Beaver Builder, and onboarding. |
| 6 | |
| 7 | ## Build & Development Commands |
| 8 | |
| 9 | ### Setup |
| 10 | |
| 11 | ```bash |
| 12 | composer install |
| 13 | yarn install --frozen-lockfile |
| 14 | ``` |
| 15 | |
| 16 | ### Production Build |
| 17 | |
| 18 | ```bash |
| 19 | # Full build: JS/CSS bundles + RTL files + POT generation |
| 20 | yarn run build |
| 21 | ``` |
| 22 | |
| 23 | `yarn run build` includes `build:makepot`, which requires Docker/WordPress CLI. If Docker is unavailable, build the assets only: |
| 24 | |
| 25 | ```bash |
| 26 | yarn run build:js |
| 27 | yarn run build:onboarding |
| 28 | yarn run build:editor |
| 29 | yarn run build:elementor |
| 30 | yarn run build:beaver |
| 31 | yarn run rtlcss:app |
| 32 | yarn run rtlcss:onboarding |
| 33 | yarn run rtlcss:editor |
| 34 | yarn run rtlcss:elementor |
| 35 | yarn run rtlcss:beaver |
| 36 | ``` |
| 37 | |
| 38 | ### Development |
| 39 | |
| 40 | ```bash |
| 41 | yarn run dev |
| 42 | |
| 43 | # Individual watch targets |
| 44 | yarn run watch:js |
| 45 | yarn run watch:onboarding |
| 46 | yarn run watch:editor |
| 47 | yarn run watch:elementor |
| 48 | yarn run watch:beaver |
| 49 | ``` |
| 50 | |
| 51 | ## Linting & Formatting |
| 52 | |
| 53 | ```bash |
| 54 | # JavaScript |
| 55 | yarn run lint |
| 56 | yarn run lint:onboarding |
| 57 | yarn run format |
| 58 | |
| 59 | # PHP |
| 60 | composer run lint |
| 61 | composer run format |
| 62 | composer run phpstan |
| 63 | ``` |
| 64 | |
| 65 | ## Testing |
| 66 | |
| 67 | ```bash |
| 68 | # PHP. Prerequisites: MySQL, the WordPress test suite, and the PHPUnit Polyfills. |
| 69 | # Neither PHPUnit nor the Polyfills are composer deps here: GitHub-hosted runners |
| 70 | # ship PHPUnit preinstalled globally, and setup-php adds the Polyfills |
| 71 | # (tools: phpunit-polyfills); copilot-setup-steps.yml installs both. Tests target the |
| 72 | # CI PHP version (7.4); newer local PHP (8.x) can abort mid-run. Install the suite once: |
| 73 | bash bin/install-wp-tests.sh wordpress_test root root 127.0.0.1 |
| 74 | phpunit # phpunit is NOT a composer dep here; use the global one (CI/copilot-setup provide it) |
| 75 | |
| 76 | # E2E |
| 77 | yarn run ci:e2e |
| 78 | ``` |
| 79 | |
| 80 | `yarn run ci:e2e` reinstalls `e2e-tests` dependencies, starts the wp-env test environment, installs Playwright Chromium, and runs the browser suite. |
| 81 | |
| 82 | ## Architecture |
| 83 | |
| 84 | ### Bootstrap & Runtime |
| 85 | |
| 86 | - `templates-patterns-collection.php`: plugin bootstrap, constants, Composer autoload, activation/onboarding hooks. |
| 87 | - `includes/Main.php`: main runtime coordinator and singleton entry point. |
| 88 | - `includes/Rest_Server.php`: plugin REST API routes. |
| 89 | - `includes/Admin.php`: wp-admin screens, onboarding triggers, AJAX endpoints, notices, logs. |
| 90 | |
| 91 | The plugin uses the `TIOB\*` namespace from `includes/`. |
| 92 | |
| 93 | ### Import / Template Domain |
| 94 | |
| 95 | - `includes/Importers/`: core import pipeline for content, plugins, widgets, theme mods, cleanup, and WordPress WXR parsing. |
| 96 | - `includes/Importers/WP/`: customized WordPress importer internals and builder-specific meta handlers. |
| 97 | - `includes/Importers/Helpers/`: import support utilities and mapping logic. |
| 98 | - `migration/`: migration code for legacy site/template data. |
| 99 | |
| 100 | ### Editor & Builder Integrations |
| 101 | |
| 102 | - `includes/Editor.php`: Gutenberg/editor registration and editor-side bootstrapping. |
| 103 | - `includes/Elementor.php`: Elementor editor integration. |
| 104 | - `includes/TI_Beaver.php`: Beaver Builder integration and AJAX handlers. |
| 105 | - `editor/`: Gutenberg/site editor React app. |
| 106 | - `elementor/`: Elementor React app/assets. |
| 107 | - `beaver/`: Beaver Builder React app/assets. |
| 108 | |
| 109 | ### UI Apps |
| 110 | |
| 111 | - `assets/`: main templates library/admin app. |
| 112 | - `onboarding/`: first-run onboarding React app. |
| 113 | - `shared/`: shared JS helpers consumed across apps. |
| 114 | |
| 115 | Each app follows a `src/` -> `build/` pipeline powered by `@wordpress/scripts`, with separate RTL generation. |
| 116 | |
| 117 | ## Folder/Subfolder Search Map |
| 118 | |
| 119 | | Path | What lives here | Start here when... | |
| 120 | |---|---|---| |
| 121 | | `templates-patterns-collection.php` | Bootstrap, constants, plugin startup, activation hooks | You need to trace plugin boot order | |
| 122 | | `includes/Main.php` | Main singleton wiring for runtime services | You are following how features are registered | |
| 123 | | `includes/Admin.php` | Admin UI wiring, notices, AJAX handlers, onboarding gates | A wp-admin flow or notice is broken | |
| 124 | | `includes/Rest_Server.php` | REST routes used by imports and UI apps | A React flow fails on API calls | |
| 125 | | `includes/Editor.php` | Gutenberg/block editor integration | Site editor or block editor behavior needs changes | |
| 126 | | `includes/Elementor.php` | Elementor integration hooks | The issue only appears in Elementor | |
| 127 | | `includes/TI_Beaver.php` | Beaver Builder integration and AJAX actions | The issue only appears in Beaver Builder | |
| 128 | | `includes/Importers/` | Import pipeline for templates, content, plugins, widgets, cleanup | Imported content or starter-site setup is wrong | |
| 129 | | `includes/Importers/WP/` | WXR importer internals and builder-specific content parsing | You are debugging low-level import parsing | |
| 130 | | `assets/src/` | Main templates library React app source | The primary template browser/import UI needs changes | |
| 131 | | `assets/build/` | Compiled main app assets | You are verifying generated output | |
| 132 | | `onboarding/src/` | Onboarding UI source | First-run user journey needs changes | |
| 133 | | `editor/src/` | Gutenberg/site editor app source | Editor insertion/import UX needs changes | |
| 134 | | `elementor/src/` | Elementor app source | Elementor-side template UI needs changes | |
| 135 | | `beaver/src/` | Beaver Builder app source | Beaver-side template UI needs changes | |
| 136 | | `shared/` | Shared utilities/modules used by multiple apps | Logic is duplicated across apps or shared state is involved | |
| 137 | | `migration/` | Legacy migration scripts | You are handling upgrades or data carry-forward | |
| 138 | | `languages/` | Translation assets and generated POT file | Work touches strings or i18n packaging | |
| 139 | | `tests/` | PHPUnit tests, fixtures, PHP test support | You are adding or updating automated coverage | |
| 140 | | `e2e-tests/` | Browser tests and wp-env config | You need end-to-end verification | |
| 141 | | `bin/` | Distribution/build helpers | You are adjusting packaging/release behavior | |
| 142 | |
| 143 | ## Notes & Gotchas |
| 144 | |
| 145 | - `yarn run build` is not purely a frontend build; it also tries to generate translations through Docker. |
| 146 | - Asset builds generate paired RTL files explicitly through `rtlcss:*` scripts. |
| 147 | - REST and AJAX are both used in this plugin, so editor/import bugs may cross PHP and React boundaries. |
| 148 | - Builder-specific behavior is split between PHP integration classes in `includes/` and separate app folders (`editor/`, `elementor/`, `beaver/`, `onboarding/`, `assets/`). |
| 149 |