Update Mouse Region Widget

docs/resources/ui/widgets/built-in-widgets/mouse-region.md

@@ -1,38 +1,32 @@
 ---
-title: Mouse Region
+title: MouseRegion
 slug: mouse-region
 tags: [Base Elements]
+keywords: [MouseRegion, Hover, Mouse Enter, Mouse Exit, Cursor, Widget]
+description: Learn how to respond to pointer hover events with the MouseRegion widget in FlutterFlow.
 ---
 
 # MouseRegion
 
-The `MouseRegion` widget lets you know whenever the mouse pointer enters or exits from a widget. You could use it to build a user experience (UX), such as animating buttons when a user hovers over them and revealing or hiding menu items when a user hovers over the menu icon.
+The **MouseRegion** widget detects when a mouse pointer enters or leaves the area occupied by its child. You can use these events to start an animation, show additional content, or update another part of the interface while the pointer is hovering.
 
-On this page, you will learn how to [add the MouseRegion widget](#adding-mouseregion-widget), use it to [show/hide elements](#showhide-elements-using-mouseregion), and [customize](#customizing) it.
-
-## Adding MouseRegion widget
+:::info
+MouseRegion interactions are designed for web and desktop apps used with a mouse or a trackpad. Provide a tap-based alternative for touch devices, and do not make essential actions available only on hover.
+:::
 
-Here are the step-by-step instructions to build such an example:
+![A pointer enters a MouseRegion and triggers On Mouse Enter, then leaves and triggers On Mouse Exit.](imgs/mouse-region-events.svg)
 
-1. First, click on the **+ Add Widget** and drag the **MouseRegion** widget from the **Base 
-Elements** tab or add it directly from the widget tree.
-2. Add a [**Button**](../basic-widgets/button.md) (inside MouseRegion) 
-   with [**On Action Trigger**](../../../../ff-concepts/animations/widget_animations.md#animation-on-action-trigger) animation.
-3. Select the **MouseRegion** widget, select **Actions** from the Properties Panel (the right menu), and click **Open**. This will open an **Action flow Editor** in a new popup window.
-4. Select the **On Mouse Enter** tab. Actions added under this will be triggered whenever the mouse enters the MouseRegion widget.
-    1. Add the [Widget Animation](../../../../ff-concepts/animations/widget_animations.md) action to start the animation on a Button.
-5. Select the **On Mouse Exit** tab. Actions added under this will be triggered whenever the mouse leaves the MouseRegion widget.
-   1. Add the [Widget Animation](../../../../ff-concepts/animations/widget_animations.md) action to stop the animation on a Button.
+The following preview shows how a widget can respond when the pointer enters and leaves its MouseRegion:
 
 <div style={{
     position: 'relative',
-    paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
+    paddingBottom: 'calc(45.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
     height: 0,
     width: '100%'
 }}>
-    <iframe 
-        src="https://demo.arcade.software/fyWTrN674CtK5JKZi8jA?embed&show_copy_link=true"
-        title=""
+    <iframe
+        src="https://demo.arcade.software/HEF6ons42zeajxNapdr7?embed&show_copy_link=true"
+        title="Preview MouseRegion pointer events"
         style={{
             position: 'absolute',
             top: 0,
@@ -50,21 +44,24 @@ Elements** tab or add it directly from the widget tree.
     </iframe>
 </div>
 
-## Show/hide elements using MouseRegion
+## Adding a MouseRegion Widget
 
-Using the callbacks provided by the MouseRgion widget, you can show or hide a widget. The idea is to update the *App State* variable when the mouse pointer enters or exits the widget. And then use the same app state variable to add *Conditional Visibility* on a widget.
+1. Open the [Widget Palette](../../../../intro/ff-ui/widget-palette.md) and add the **MouseRegion** widget from **Base Elements**.
+2. Add the widget that should respond to hover as the child of **MouseRegion**.
+3. Set the child's size and position. The MouseRegion covers the area occupied by its child.
+4. Select **MouseRegion** and open the **Actions** tab to configure its [pointer events](#mouseregion-events).
 
-Let's see how to build the following example:
+The following walkthrough demonstrates how to add MouseRegion and configure its events:
 
 <div style={{
     position: 'relative',
     paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
     height: 0,
     width: '100%'
 }}>
-    <iframe 
-        src="https://demo.arcade.software/nFzYivGMxumu0IsrPn4b?embed&show_copy_link=true"
-        title=""
+    <iframe
+        src="https://demo.arcade.software/C01xFFlctqQNosODlOZK?embed&show_copy_link=true"
+        title="Add a MouseRegion widget and configure its pointer events"
         style={{
             position: 'absolute',
             top: 0,
@@ -82,92 +79,45 @@ Let's see how to build the following example:
     </iframe>
 </div>
 
-<p></p>
+## MouseRegion Events
 
-Here are the step-by-step instructions:
+The following events are available from the MouseRegion widget's **Actions** tab:
 
-1. First, add the Stack **>** **Container** **> MouseRegion >** **IconButton** to display the menu 
-icon.
-2. Add the **Container > MouseRegion >** **Column** (with some menu items/options) inside the same Stack widget.
+### On Mouse Enter
 
-:::info[Note] 
-Note that we wrapped the menu icon and its options inside the MouseRegion widget. In 
-the next step, we will add the same actions for both MouseRegion widgets so that the menu options stay visible as long as you hover over them.
-:::
+**On Mouse Enter** runs when the pointer moves into the MouseRegion. Use it to show content, start a [widget animation](../../../../ff-concepts/animations/widget_animations.md#animation-on-action-trigger), or update a state variable.
 
-![img_9.png](imgs/img_9.png)
+### On Mouse Exit
 
-3. Create a boolean [App State variable](../../../../resources/data-representation/app-state.md) 
-   and use it 
-to 
-[add conditional visibility](../../widgets/widget-commonalities.md#conditional) 
-   on menu options.
-4. On both MouseRegion widgets, add an [update app state variable](../../../../resources/data-representation/app-state.md#update-app-state-action) action to set **True** when the mouse enters and **False** when the mouse exit.
+**On Mouse Exit** runs when the pointer leaves the MouseRegion. Use it to hide content, stop or reverse an animation, or reset a state variable.
 
-<figure>
-    <div style={{
-    position: 'relative',
-    paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
-    height: 0,
-    width: '100%'
-}}>
-    <iframe 
-        src="https://demo.arcade.software/QsKNBHezCkCylYsY6lDB?embed&show_copy_link=true"
-        title=""
-        style={{
-            position: 'absolute',
-            top: 0,
-            left: 0,
-            width: '100%',
-            height: '100%',
-            colorScheme: 'light'
-        }}
-        frameborder="0"
-        loading="lazy"
-        webkitAllowFullScreen
-        mozAllowFullScreen
-        allowFullScreen
-        allow="clipboard-write">
-    </iframe>
-</div>
-  <figcaption class="centered-caption">Use app state variable and MouseRegion to show/hide a widget</figcaption>
-</figure>
+## Customizing
 
+Select the **MouseRegion** widget and open **MouseRegion Properties** in the [Properties Panel](../../../../intro/ff-ui/builder.md#properties-panel).
 
-## Customizing
+### Changing the Mouse Cursor
 
-You can customize the appearance and behavior of this widget using the various properties 
-available under the **Properties Panel**.
+Use **Mouse Cursor** to choose the cursor style shown while the pointer is inside the MouseRegion.
 
-### Customize mouse cursor
+When the child is clickable, choose a cursor that communicates that interaction. A suitable cursor helps users understand what they can do before they interact.
 
-When a mouse enters the widget, its cursor will change to the appropriate one by default. However, you can also set it to a custom one if you wish to.
+### Controlling Overlapping MouseRegions
 
-To customize the mouse cursor, select the **MouseRegion** widget, move to the properties panel, find the **Mouse Cursor** dropdown select the one you think fits best.
+Enable **Opaque** when this MouseRegion should prevent MouseRegion widgets behind it from responding to the pointer. This is useful when MouseRegions overlap, such as inside a Stack, and only the region in front should receive hover events.
 
-<div style={{
-    position: 'relative',
-    paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
-    height: 0,
-    width: '100%'
-}}>
-    <iframe 
-        src="https://demo.arcade.software/vTu0IFhJzyfqHryY0GHU?embed&show_copy_link=true"
-        title=""
-        style={{
-            position: 'absolute',
-            top: 0,
-            left: 0,
-            width: '100%',
-            height: '100%',
-            colorScheme: 'light'
-        }}
-        frameborder="0"
-        loading="lazy"
-        webkitAllowFullScreen
-        mozAllowFullScreen
-        allowFullScreen
-        allow="clipboard-write">
-    </iframe>
-</div>
+Disable **Opaque** when MouseRegion widgets behind it should remain responsive to the pointer.
+
+#### Example: Icon Over a Hoverable Card
+
+Suppose a Stack contains a product card that changes elevation on hover and a favorite icon positioned over the card. Both widgets have their own MouseRegion.
+
+- Enable **Opaque** on the favorite icon's MouseRegion when hovering over the icon should show its tooltip without also changing the card's elevation.
+- Disable **Opaque** when hovering over the favorite icon should trigger both the icon and card hover effects.
+
+## Best Practices
 
+- Treat hover as an enhancement and provide a tap-based alternative for touch devices.
+- Keep essential actions and information accessible without requiring hover.
+- Keep the MouseRegion's size stable while the pointer is inside it to prevent repeated enter and exit events.
+- Choose a cursor that accurately communicates the interaction.
+- Test the hover interaction with a mouse and a trackpad. Separately test the tap and keyboard alternatives provided for users who cannot use hover.