Feat: More Guided Tours

[kaeizen]

Summary by CodeRabbit

• New Features

  • Added guided tours for Block Backgrounds, Responsive Controls, Hover States, Advanced Hover States, and Global Color Schemes to help users learn new features.
  • Enhanced Getting Started page with improved quick-start options for guided feature discovery.
  • Improved tour system with better positioning and iframe support for complex editor layouts.

• Bug Fixes

  • Fixed tour modal styling alignment for consistent tooltip positioning.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai[bot]]

Walkthrough

This PR extends the guided modal tour system by adding five new tour condition keys and corresponding tour modules (block-backgrounds, responsive-controls, hover-states, advanced-hover-states, global-color-schemes). It refactors getting-started to use data-driven configuration, enhances tour positioning with iframe support, and introduces utility functions for DOM synchronization.

Changes

Cohort / File(s)	Summary
Tour Condition & Infrastructure src/components/guided-modal-tour/tour-conditions.js, src/components/guided-modal-tour/index.js, src/lazy-components/modal-tour/tours/index.js	Added 5 new tour condition keys (block-backgrounds, responsive-controls, hover-states, advanced-hover-states, global-color-schemes); each checks URL for tour parameter. Updated modal tour to apply WordPress filter to conditions. Refactored tour loading to dynamically import tour modules and apply filter for extensibility.
New Tour Modules src/lazy-components/modal-tour/tours/block-backgrounds.js, src/lazy-components/modal-tour/tours/responsive-controls.js, src/lazy-components/modal-tour/tours/hover-states.js, src/lazy-components/modal-tour/tours/advanced-hover-states.js, src/lazy-components/modal-tour/tours/global-color-schemes.js	Added 5 new tour modules, each exporting initialize() and steps array. Tours demonstrate block backgrounds, responsive controls, hover states, advanced hover styling, and global color schemes with localized content and editor interactions.
Getting Started Refactor src/welcome/getting-started.js	Refactored to data-driven QUICK_BUTTONS constant with 16 entries (id, icon, title, description, link, cta, display, premium fields). Added video section. Replaced inline quick-start blocks with mapped card rendering; added pro gating and pulsating indicator for premium features.
Getting Started Styling src/welcome/getting-started.scss	Reduced gap to 24px, repositioned video grid placement. Replaced column layout with row layout for cards; added color assignments for card groups (5n+3, 5n+4, 5n, 5n+6). Added custom-icon-wrapper utility and disabled-state button styling.
Modal Tour Enhancements src/lazy-components/modal-tour/index.js	Added iframe support via modalDelay, anchorInIframe, glowTargetInIframe config. Refactored position calculation with offsetCoord helper to handle both document and iframe contexts. Updated glow target and element positioning for iframe-aware rendering. Invokes preStep on initialization.
Component Data Attributes src/components/base-control2/index.js, src/components/color-palette-control/index.js, src/components/sortable-picker/index.js, src/components/block-styles-control/index.js, src/components/guided-modal-tour/editor.scss	Added data-attribute hookup to BaseControl2 and AdvancedControl. Added data-item-key attribute to SortablePicker button. Added data-slug and data-name to block-style options; improved block-styles popover with is-opened class and onEscape handling. Extended tooltip styling for right-top positioning.
Tour Utilities src/lazy-components/modal-tour/utils.js	Introduced waitForElement(selector, timeout) utility that polls via requestAnimationFrame and resolves with DOM element or rejects on timeout.
Editor Block Tour Dynamic Routing src/plugins/guided-modal-tour/editor-block-tour.js	Updated EditorBlockTour to use dynamic tourId state, reading URL parameter "tour" via effect; renders GuidedModalTour with computed tourId instead of fixed "blocks" value.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant GettingStarted as Getting Started Component
    participant GuidedModalTour as Guided Modal Tour
    participant TourConditions as Tour Conditions
    participant TourFilter as WordPress Filter
    participant TourModule as Tour Module

    User->>GettingStarted: Click quick-start button (e.g., "Block Backgrounds")
    GettingStarted->>GuidedModalTour: Render with tourId from QUICK_BUTTONS
    GuidedModalTour->>TourConditions: Check TOUR_CONDITIONS[tourId]
    TourConditions->>TourConditions: Check URL for tour parameter
    GuidedModalTour->>TourFilter: applyFilters('stackable.guided-tour.conditions', TOUR_CONDITIONS)
    TourFilter->>GuidedModalTour: Return filtered conditions
    GuidedModalTour->>TourModule: Load tour module (e.g., blockBackgrounds)
    TourModule->>TourModule: initialize() - insert blocks, setup editor state
    TourModule->>TourModule: steps[0] - preStep hook
    TourModule->>User: Display first tour step with anchor, glow, modal
    User->>GuidedModalTour: Click Next
    GuidedModalTour->>TourModule: Execute postStep hook for current step
    TourModule->>TourModule: Update editor state (select blocks, open panels)
    GuidedModalTour->>TourModule: Execute preStep hook for next step
    TourModule->>User: Display next step

sequenceDiagram
    participant Modal as Modal Tour Component
    participant Step as Step Config
    participant IFrame as Editor Canvas iframe
    participant MainDoc as Main Document
    participant CalcPos as Position Calculator

    Modal->>Step: Load step with anchorInIframe=true
    Step->>Modal: Provide anchor selector & iframe flag
    Modal->>IFrame: querySelector(anchorSelector) in iframe.contentDocument
    IFrame->>CalcPos: Return element from iframe
    CalcPos->>CalcPos: offsetCoord(element, isInIframe=true)
    CalcPos->>CalcPos: Add iframe.getBoundingClientRect() offset
    CalcPos->>MainDoc: Compute position in viewport coordinates
    MainDoc->>Modal: Return adjusted modal position
    Modal->>Modal: Render glow element with iframe-adjusted coordinates
    Modal->>User: Display modal at correct position overlaying iframe content

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Areas requiring extra attention:

• Tour Module Logic (block-backgrounds.js, responsive-controls.js, hover-states.js, advanced-hover-states.js, global-color-schemes.js): Each module has similar structure but distinct editor interactions, block selections, and attribute updates. Review for consistency in preStep/postStep patterns, correct block hierarchy, and localization coverage.
• iframe Support in Modal Tour (src/lazy-components/modal-tour/index.js): The offset calculation logic for positioning modals and glow elements within iframes is intricate. Verify offsetCoord helper correctly adjusts coordinates across all position variants (12+ cases) and handles edge cases like iframe boundaries.
• Dynamic Tour Loading (src/lazy-components/modal-tour/tours/index.js): The dynamic import mechanism with filter application changes how tours are assembled. Confirm the filter hook integrates cleanly and does not break existing tour resolution.
• Getting Started Refactor (src/welcome/getting-started.js): Verify QUICK_BUTTONS constant covers all intended tours, icon assignments are correct, and premium gating logic properly gates non-pro users. Check that display filtering and contextual header rendering work as expected.
• Data Attribute Propagation (base-control2, color-palette-control, sortable-picker, block-styles-control): Confirm data attributes are consistently passed through component props and render without breaking existing functionality or styling.

Possibly related PRs

• PR #3571: Modifies the same guided-modal-tour/tours and getting-started code, establishing the initial tour infrastructure that this PR extends with five new tour modules and refactored data-driven configuration.

Poem

🐰 Five tours bloom where guidance did not dwell,
iframe walls broken, positions calculated well,
Data attributes dance on every control,
From blocks to colors, the tour system's now whole,
Quick buttons mapped, the welcome page knows,
How to show users what Stackable bestows! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Feat: More Guided Tours' accurately describes the main changeset, which adds five new guided tour modules (block-backgrounds, responsive-controls, hover-states, advanced-hover-states, global-color-schemes) plus supporting infrastructure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch feat/more-guided-tours

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions[bot]]

🤖 Pull request artifacts

file	commit
pr3639-stackable-3639-merge.zip	bab77d9672caed77ecc4686d3513cec005f7f0e4

[github-actions[bot]]

Try this Pull Request in the WordPress playground: https://playground.wordpress.net/?mode=seamless#{"landingPage":"/wp-admin/post-new.php?post_type=page","preferredVersions":{"php":"latest","wp":"latest"},"steps":[{"step":"login","username":"admin","password":"password"},{"step":"installPlugin","pluginZipFile":{"resource":"url","url":"https://raw.githubusercontent.com/gambitph/Stackable/artifacts/pr3639-stackable-3639-merge.zip"}}]}