Technical Evaluation

Modularity: The bundle is a lightweight, focused enhancement for Sulu CMS, aligning with the principle of separation of concerns. It targets a specific UX pain point (block navigation in preview mode) without altering core Sulu functionality.
Event-Driven Design: Leverages cross-window messaging (postMessage) to decouple the preview iframe from the admin panel, ensuring minimal coupling with existing Sulu systems.
React Integration: Uses React fiber introspection (via ReactDOM.findDOMNode) to locate and manipulate blocks in the admin UI. This assumes Sulu’s admin panel is React-based (confirmed by Sulu 3.x docs), but may require adaptation if Sulu’s internals change.

Low Risk for Sulu 3.x: Explicitly designed for Sulu 3.0+, Symfony 7.0+, and PHP 8.2+, with no breaking changes to existing workflows.
Conditional Rendering: Uses sulu_user_loggedin_and_preview to isolate preview-specific behavior, preventing leaks to production.
Block ID Handling: Requires data-block-id on preview blocks, which must be backward-compatible with existing Sulu templates (minimal template changes needed).

Risk Area	Severity	Mitigation Strategy
React DOM Introspection	Medium	Test with Sulu’s latest React version; fallback to `querySelector` if fiber API changes.
Cross-Window Messaging	Low	Standard `postMessage` with origin validation.
Admin JS Build Process	Medium	Ensure `npm install` and `build` steps are automated in CI/CD.
Block ID Consistency	High	Validate `content._id` exists in all block types; add fallback logic.
Performance Impact	Low	Minimal overhead (event listeners only active in preview).

Sulu Version Lock: Will this bundle work with Sulu 3.1+ without modifications? (Check for React version changes.)
Block Type Support: Does it handle all Sulu block types (e.g., nested, dynamic)? Test edge cases like empty blocks.
Admin Customization: If Sulu’s admin UI is heavily customized, will ReactDOM.findDOMNode still locate blocks reliably?
Security: Is postMessage origin validation implemented? (Assume yes, but verify.)
Localization: Does the focus button text/localization need adaptation for non-English Sulu instances?
CI/CD Impact: How will this affect admin asset rebuilds in a CI pipeline? (May require post-install scripts.)

Integration Approach

Frontend: Compatible with Webpack Encore (for website JS) and Sulu’s admin JS stack (React + npm).
Backend: Zero server-side changes required; purely client-side and Twig template adjustments.
Database: No schema changes; relies on existing block metadata (content._id).

Pre-requisite Check:
- Verify Sulu version (>=3.0), PHP (8.2+), and Symfony (7.0+).
- Confirm admin panel uses React (Sulu 3.x does; no action needed).
Installation:
```
composer require alengo/sulu-preview-block-focus-bundle
```
Update config/bundles.php with the bundle class.
Admin JS Setup:
- Add dependency to assets/admin/package.json.
- Import in app.js and rebuild (npm run build).
Website JS Setup:
- Add Webpack Encore entry (webpack.config.js).
- Include script conditionally in Twig (using sulu_user_loggedin_and_preview).
Template Adjustment:
- Add data-block-id to all preview-rendered blocks (use Twig’s sulu_user_loggedin_and_preview guard).
Testing:
- Validate in preview mode: Hover blocks → focus button appears → click → admin scrolls/expands.
- Test nested blocks and edge cases (empty blocks, disabled blocks).

Sulu Plugins: No conflicts expected if plugins do not override block rendering or postMessage handling.
Custom Blocks: May require additional data-block-id logic if block types store IDs differently.
Legacy Browsers: Relies on modern JS features (e.g., postMessage, classList); test in target browsers.

Phase 1 (Low Risk):
- Install bundle + admin JS.
- Test focus button visibility in preview.
Phase 2 (Medium Risk):
- Add data-block-id to templates.
- Test scrolling/expansion in admin.
Phase 3 (High Risk):
- Test nested blocks, edge cases.
- Performance benchmark (e.g., large pages with many blocks).

Dependency Updates: Monitor Sulu 3.x and React version changes; bundle may need updates if Sulu’s admin DOM structure evolves.
Admin JS Maintenance: Any changes to sulu-preview-block-focus-bundle assets require rebuilding admin JS (npm run build).
Template Maintenance: data-block-id must be consistently applied across all preview-rendered blocks.

Debugging Tools:
- Browser DevTools: Inspect postMessage events and React DOM nodes.
- Logs: Add console logs in assets/admin/index.js for debugging.
Common Issues:
- Block Not Found: Verify data-block-id exists and matches admin-side IDs.
- Scrolling Fails: Check if admin panel has overflow constraints (e.g., fixed headers).
- Button Missing: Ensure Twig guard (sulu_user_loggedin_and_preview) is correct.

Performance:
- Event Listeners: Minimal overhead; only active in preview mode.
- Large Pages: Test with 100+ blocks to ensure scrolling/expansion remains responsive.
Concurrency: No server-side scaling concerns; purely client-side.

Failure Scenario	Impact	Mitigation
`postMessage` blocked	Focus button clicks fail	Verify iframe `srcdoc` or `sandbox` attributes.
Missing `data-block-id`	Block not found in admin	Add fallback: log error + highlight missing IDs.
React DOM structure changes	`findDOMNode` fails	Use `querySelector` as fallback.
Admin JS build fails	Feature disabled	Add `post-install` script to rebuild assets.
Nested block ID resolution	Parent/child mapping fails	Extend bundle to handle custom ID paths.

Developer Onboarding:
- 1 hour: Install and test basic functionality.
- 2 hours: Understand data-block-id requirements and template adjustments.
- 4 hours: Debug edge cases (nested blocks, custom admin UIs).
Documentation Gaps:
- Missing: Example of data-block-id for custom block types.
- Suggested: Add a Troubleshooting section to README (e.g., "Block not found? Check content._id").
Training:
- Template Authors: Train on conditional data-block-id usage.
- Admin Customizers: Warn about React DOM assumptions.