Create docs for Selection Helper and update Gallery

content/en/docs/marketplace/platform-supported-content/modules/data-widgets/_index.md

@@ -11,17 +11,18 @@ description: "Describes the configuration and usage of the Data Widgets module,
 
 This module contains the following widgets:
 
-* [Data Grid 2](/appstore/modules/data-grid-2/)
-* [Data Grid 2 Properties](/appstore/modules/data-grid-2-properties/)
-* [Drop-Down Sort](/appstore/modules/gallery/#dropdown)
-* [Filters](/appstore/modules/data-grid-2/#filters)
-* [Gallery](/appstore/modules/gallery/)
-* [Tree node](/appstore/modules/tree-node/)
+- [Data Grid 2](/appstore/modules/data-grid-2/)
+- [Data Grid 2 Properties](/appstore/modules/data-grid-2-properties/)
+- [Drop-Down Sort](/appstore/modules/gallery/#dropdown)
+- [Filters](/appstore/modules/data-grid-2/#filters)
+- [Gallery](/appstore/modules/gallery/)
+- [Selection helper](/appstore/modules/selection-helper/)
+- [Tree node](/appstore/modules/tree-node/)
 
 ## Migration
 
 If you were previously using the Data Grid 2 module, you must follow these steps before updating it to the new [Data Widgets](https://marketplace.mendix.com/link/component/116540) module:
 
-1. Rename the current **DataGrid** module (under **Marketplace** modules) to *DataWidgets* in Studio Pro.
+1. Rename the current **DataGrid** module (under **Marketplace** modules) to _DataWidgets_ in Studio Pro.
 1. Open the Marketplace and search for **Data Widgets**.
 1. Download and replace the current (renamed) DataWidgets module.

content/en/docs/marketplace/platform-supported-content/modules/data-widgets/gallery.md

@@ -17,12 +17,12 @@ Here is an example of a Gallery widget using filters:
 
 The gallery has an option to enable advanced options. When this option is toggled on, it enables numerous features to customize your gallery:
 
-* Pagination type
-* Pagination position
-* Empty list option
-* Dynamic item class
-* Filtering
-* Sorting
+- Pagination type
+- Pagination position
+- Empty list option
+- Dynamic item class
+- Filtering
+- Sorting
 
 ## Configuration
 
@@ -84,15 +84,15 @@ Triggers an action (such as a nanoflow, microflow, or Show page action) when the
 
 In order to enable filtering within the gallery items you need to select the desired attributes to be filtered in the **Filtering** tab. You can select attributes of the following types:
 
-* Autonumber
-* Boolean
-* Date & time
-* Decimal
-* Enumeration
-* Hashed string
-* Integer
-* Long
-* String
+- Autonumber
+- Boolean
+- Date & time
+- Decimal
+- Enumeration
+- Hashed string
+- Integer
+- Long
+- String
 
 The attributes selected here will be used for the matching filter placed inside the composable region. When using multiple attributes, the filters will automatically select the matching attributes and then compose the desired filter value in an `OR expression`. Make sure you just have one filter widget for each type, for example `Text Filter` and `Number Filter`.
 
@@ -108,7 +108,7 @@ An example of text filter being used in the composable region combined with a dr
 
 {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/gallery/filter-region.png" alt="Example of filtering composable region"   width="300"  class="no-border" >}}
 
-For more information about filters, see the [Filters](/appstore/modules/data-grid-2/#filters) section of *Data Grid 2*.
+For more information about filters, see the [Filters](/appstore/modules/data-grid-2/#filters) section of _Data Grid 2_.
 
 ## Sorting
 
@@ -128,8 +128,84 @@ The Drop-Down Sort widget is a widget you can use in combination with the Galler
 
 The Drop-Down Sort widget has two options you can set:
 
-* Empty option caption: value to be used when no value is selected
-* Screen reader caption: value to be announced by screen readers when using assistive technology
+- Empty option caption: value to be used when no value is selected
+- Screen reader caption: value to be announced by screen readers when using assistive technology
+
+## Selection
+
+Enabling selection allows users to select gallery items by clicking on them. Selection is disabled by default and can be activated by changing the **Selection** setting from **None** to either **Single** or **Multi**.
+
+The Gallery widget keeps selected items in memory and supports selection persistence across page navigation when the **Keep selection** option is enabled. This allows users to maintain their selections while browsing through paginated data or navigating between different pages in your application.
+
+### Selection Property
+
+The **Selection** property determines what type of selection is available to users:
+
+- **None**: Selection is disabled. Users cannot select gallery items.
+- **Single**: Users can select only one item at a time. Selecting a new item automatically deselects the previously selected item.
+- **Multi**: Users can select multiple items simultaneously using various interaction methods.
+
+When selection is enabled, the Gallery automatically provides visual feedback to indicate selected items and supports keyboard navigation for accessibility.
+
+### Selection and Click Actions Constraint
+
+{{% alert color="info" %}}
+It is not possible to use both selection and onClick actions simultaneously when the **On click trigger** is set to **Single click**. This constraint prevents ambiguous user interactions where a single click could both select an item and trigger an action.
+{{% /alert %}}
+
+#### Supported Combinations
+
+| Selection Mode | On Click Trigger | Selection Method | Click Action                                  | Supported |
+| -------------- | ---------------- | ---------------- | --------------------------------------------- | --------- |
+| None           | Single click     | N/A              | ✓ Click triggers action                       | ✓ Yes     |
+| None           | Double click     | N/A              | ✓ Double-click triggers action                | ✓ Yes     |
+| Single/Multi   | Single click     | Item click       | ✗ Ambiguous interaction                       | ✗ **No**  |
+| Single/Multi   | Double click     | Item click       | ✓ Click selects, double-click triggers action | ✓ Yes     |
+
+#### Error Prevention
+
+If you attempt to configure both selection (Single or Multi) and an onClick action with **Single click** trigger, the Gallery will display a design-time error:
+
+> "The item click action is ambiguous. Change 'On click trigger' to 'Double click' or set 'Selection' to 'None'."
+
+#### Recommended Approach
+
+For galleries that need both selection and click actions:
+
+1. Set **On click trigger** to **Double click**
+2. Configure your desired selection mode (Single or Multi)
+3. Users can then select items with single clicks and trigger actions with double clicks
+
+### Selection with Action Buttons in Header
+
+Gallery selection works seamlessly with action buttons and other widgets placed in the gallery header. This pattern enables powerful bulk operation workflows.
+
+#### Selection Helper Integration
+
+Place a **Selection Helper** widget in the gallery header to provide bulk selection controls:
+
+- **Select All**: Quickly select all visible items
+- **Clear Selection**: Remove all current selections
+- **Selection Status**: Visual indicator of current selection state (all, some, or none selected)
+
+#### Selection Count Display
+
+Enable the **Show selection count** property to display the number of selected items:
+
+- **Top**: Shows count above the gallery items
+- **Bottom**: Shows count below the gallery items
+- **Off**: Hides the selection count
+
+The selection count automatically updates as users select or deselect items and includes a "Clear selection" button for easy deselection.
+
+#### Event Handling
+
+Use the **On selection change** action to trigger custom logic when selection changes:
+
+- Update UI elements based on selection state
+- Enable/disable action buttons
+- Load additional data for selected items
+- Validate selection before allowing operations
 
 ## Keyboard Navigation and Selection
 
@@ -141,8 +217,8 @@ You can also see when an item is selected: an item with a light gray background
 
 For the keyboard navigation and keyboard selection to work, the user must open the **General** tab and then set the **Selection** property to one of the following:
 
-* **Single**: enables keyboard navigation with just single selection
-* **Multi**: to enable keyboard navigation with multi-selection
+- **Single**: enables keyboard navigation with just single selection
+- **Multi**: to enable keyboard navigation with multi-selection
 
 ### Keyboard Navigation
 
@@ -166,5 +242,5 @@ Employing keyboard navigation is an effective way of ensuring users who cannot u
 
 The new Gallery widget uses [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) as its base for styling. If you need to combine rows or columns you can achieve this using the following helper classes in the `Dynamic item class`:
 
-* `widget-gallery-column-span-1` until `widget-gallery-column-span-12`: these classes merge column spaces, pushing items to a new row when the selected amount is reached for each platform
-* `widget-gallery-row-span-1` until `widget-gallery-row-span-12`: these classes merge row spaces, pushing items into new columns or rows when needed
+- `widget-gallery-column-span-1` until `widget-gallery-column-span-12`: these classes merge column spaces, pushing items to a new row when the selected amount is reached for each platform
+- `widget-gallery-row-span-1` until `widget-gallery-row-span-12`: these classes merge row spaces, pushing items into new columns or rows when needed

content/en/docs/marketplace/platform-supported-content/modules/data-widgets/selection-helper.md

@@ -0,0 +1,114 @@
+---
+title: "Selection Helper"
+url: /appstore/modules/selection-helper/
+description: "Describes the configuration and usage of the Selection Helper widget, which is available in the Mendix Marketplace."
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+## Introduction
+
+The [Selection Helper](https://marketplace.mendix.com/link/component/116540) widget provides bulk selection controls for data widgets, enabling users to quickly select all or clear all items when multi-selection is enabled. While primarily often used for Gallery widgets, it also supports Data Grid 2 applications.
+
+Here is an example of a Selection Helper widget in a Gallery:
+
+{{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/example-selection-helper.png" alt="Example of Selection Helper in a Gallery widget" width="400" class="no-border" >}}
+
+Use the Selection Helper widget when you need to provide users with efficient bulk selection capabilities in your data widgets. This is particularly useful for:
+
+- **Gallery bulk operations**: Enable users to select multiple items in gallery layouts for batch processing like delete, update, or export operations
+- **Data Grid 2 bulk operations**: Provide similar functionality for tabular data presentations
+- **Data management workflows**: Streamline processes where users need to work with multiple records simultaneously
+- **Administrative interfaces**: Provide power users with quick selection tools for managing large datasets
+
+## Prerequisites
+
+Before using the Selection Helper widget, ensure:
+
+- **For Gallery**: Gallery widget is configured with Selection set to Multi
+- **For Data Grid 2**: Data Grid 2 is configured with Selection set to Multi
+
+The Selection Helper must be placed inside the data widget's header content area:
+
+### For Gallery
+
+1. Go to your Gallery widget
+2. In the Header section, add the Selection Helper widget to the header content area
+3. Configure the Selection Helper properties as needed
+
+### For Data Grid 2
+
+1. Go to your Data Grid 2 widget
+2. In the Header section, add the Selection Helper widget to the header content area
+3. Configure the Selection Helper properties as needed
+
+## Properties
+
+### Style
+
+Controls how the selection control appears to users:
+
+- **Check box** (default): Displays a standard checkbox that reflects the current selection state
+- **Custom**: Allows you to define custom widgets for different selection states
+
+#### Custom style
+
+Available when `Style = Custom` . Define custom widgets that display based on the current selection state:
+
+- **None Selected Widget**: Widget displayed when no items are currently selected. Usually contains "Select all" controls or empty state indicators.
+- **Some Selected Widget**: Widget displayed when some (but not all) items are selected. Often used to show "Select all" controls or partial selection indicators.
+- **All Selected Widget**: Widget displayed when all visible items in the grid are selected. Typically used to show "Clear selection" controls or indicators.
+
+Here is an example of a Selection Helper with custom style configured:
+
+{{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/style-custom-selection-helper.png" alt="Example of Selection Helper with custom style configured" width="400" class="no-border" >}}
+
+#### Selection States and Behavior
+
+The Selection Helper automatically manages three distinct selection states:
+
+| State | Checkbox Appearance  | Click Behavior            | Use Case                                  |
+| ----- | -------------------- | ------------------------- | ----------------------------------------- |
+| None  | Unchecked            | Selects all visible items | Starting state, no selections made        |
+| Some  | Indeterminate (dash) | Selects all visible items | Partial selection, complete the selection |
+| All   | Checked              | Clears all selections     | Full selection, allow deselection         |
+
+### Check Box Caption
+
+Available when Style = Check box
+
+Optional text label displayed next to the checkbox. Use this to provide context about the selection action, such as "Select all items" or "Toggle selection".
+
+### State Synchronization
+
+The Selection Helper maintains real-time synchronization with the parent data widget:
+
+- Changes made through the Selection Helper immediately reflect in individual row/item selections
+- Individual row/item selection changes update the Selection Helper state accordingly
+- Selection state persists across pagination when Keep selection is enabled in the data widget
+
+## Integration with Data Widgets
+
+### Compatible Selection Methods
+
+The Selection Helper works with both Gallery and Data Grid 2 selection methods:
+
+- **Gallery**: Users can select via item clicks and the Selection Helper
+- **Data Grid 2**: Users can select via both individual checkboxes/row clicks and the Selection Helper
+
+## Common Use Cases
+
+### Gallery Bulk Selection
+
+Place a Selection Helper with default checkbox style in the Gallery header for simple select-all functionality in grid or list layouts.
+
+### Data Grid 2 Bulk Selection
+
+Use the Selection Helper in Data Grid 2 headers for tabular data bulk operations.
+
+### Custom Bulk Operations Interface
+
+Use custom style to integrate with your app's design system across both Gallery and Data Grid 2.
+
+### Administrative Data Management
+
+Combine with action buttons that enable/disable based on selection state for both grid and list interfaces.