From 43c2f3dc318af130073ef71e90a03c4790880c8a Mon Sep 17 00:00:00 2001
From: Richard BAYET <richard.bayet@smile.fr>
Date: Thu, 16 Jan 2025 21:55:36 +0100
Subject: [PATCH] [Core] Reworked group and fields descriptions

---
 .../etc/adminhtml/system.xml                  | 25 +++++++++++--------
 src/module-elasticsuite-core/etc/config.xml   |  3 ++-
 .../adminhtml/web/css/source/_module.less     |  4 +++
 3 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/src/module-elasticsuite-core/etc/adminhtml/system.xml b/src/module-elasticsuite-core/etc/adminhtml/system.xml
index 4d879db9a..87377882b 100644
--- a/src/module-elasticsuite-core/etc/adminhtml/system.xml
+++ b/src/module-elasticsuite-core/etc/adminhtml/system.xml
@@ -183,43 +183,48 @@
 
             <group id="advanced" translate="label" type="text" sortOrder="99" showInDefault="1" showInWebsite="1" showInStore="1">
                 <label>Advanced Settings</label>
+                <field id="info" translate="label comment" type="label" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="0" >
+                    <label>Using popular search terms for autocomplete search of products and categories</label>
+                    <comment><![CDATA[Historically, both for leveraging user behavioral patterns and performance purposes, Elasticsuite relies on the Popular Search Terms Autocomplete results to complete and extend the search terms submitted by the user before searching for matching products or categories.<br />For instance, if a user types "comp" in the search box and the suggested popular search terms are "computer", "peach computer", "computer for kids", then categories and products matching either one of those three search terms will be shown and the original "comp" search term is discarded.<br />On the other hand, if no popular search term is found, then Elasticsuite will try finding products and categories matching only "comp", which might not provide any results unless some attributes have built-in autocompletion capability (by using the "standard_edge_ngram" as their search analyzer).<br />The settings below provide you with the ability to have more control over that "extension" mechanism: whether to disable it entirely, limit its extend, forcing the original search term to always be requested, etc.]]></comment>
+                    <frontend_model>Smile\ElasticsuiteCore\Block\Adminhtml\System\Config\Comment</frontend_model>
+                </field>
                 <field id="extension_enabled" translate="label comment" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1" canRestore="1">
                     <label>Use suggested search terms to fetch results</label>
                     <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
-                    <comment><![CDATA[Default: Yes. When enabled, autocompletion box results will be computed from the suggested search terms. This is intended to suggest results when the user is in the process of typing. Eg : When the user is typing "comp", the popular search term "computer" will be suggested, and therefore products or categories matching "computer" will be shown.]]></comment>
+                    <comment><![CDATA[Default: Yes (legacy behavior). When set to "Yes", products and categories autocomplete will use the search terms suggested in the popular term autocomplete. When set to "No", products and categories autocomplete results will be based solely on the original user raw search term, which might be a partial word (eg "comp" for "computer").]]></comment>
                 </field>
                 <field id="preserve_base_query" translate="label comment" type="select" sortOrder="15" showInDefault="1" showInWebsite="1" showInStore="1" canRestore="1">
-                    <label>Always use the user raw input for suggestions.</label>
+                    <label>Always use the user raw input for suggestions</label>
                     <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                     <depends>
                         <field id="extension_enabled">1</field>
                     </depends>
-                    <comment><![CDATA[Default: No. When set to "Yes", this setting will always proceed to fetch suggestions on the query typed by the user in addition to the extended terms. Eg : When the user is typing "comp", the popular search term "computer" will be suggested, but products or categories matching either "comp" or "computer" will be shown.]]></comment>
+                    <comment><![CDATA[Default: No (legacy behavior). When set to "No", the user raw search term, which might be a partial word, will only be used to fetch suggestions if no matching popular terms were found. When set to "Yes", it will always be used, whether matching popular terms were found or not. Eg if set to "Yes" : when the user is typing "comp" and the popular search term "computer" is suggested, then products or categories matching either "comp" or "computer" will be shown.]]></comment>
                 </field>
                 <field id="extension_limited" translate="label comment" type="select" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1" canRestore="1">
-                    <label>Limit the amount of suggested search terms used for autocomplete matching</label>
+                    <label>Limit the amount of suggested search terms used</label>
                     <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                     <depends>
                         <field id="extension_enabled">1</field>
                     </depends>
-                    <comment><![CDATA[Default: No. When set to "No", this setting will use the maximum number of suggested popular search terms configured in the dedicated section.]]></comment>
+                    <comment><![CDATA[Default: No (legacy behavior). When set to "No", all the suggested popular search terms will be used for the products and categories autocomplete. When set to "Yes", you will be able to define the maximum number of suggested search terms to use below.]]></comment>
                 </field>
                 <field id="extension_size" translate="label comment" type="text" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1" canRestore="1">
-                    <label>The number of suggested popular search terms to use for fetching results.</label>
-                    <validate>integer validate-greater-than-zero</validate>
+                    <label>Maximum number of popular search terms to use</label>
+                    <validate>required integer validate-greater-than-zero</validate>
                     <depends>
                         <field id="extension_enabled">1</field>
                         <field id="extension_limited">1</field>
                     </depends>
-                    <comment><![CDATA[The number of suggested search terms that will be used for fetching results in the autocompletion box.]]></comment>
+                    <comment><![CDATA[The maximum number of suggested search terms that will be used for fetching results in the products and categories autocomplete boxes. Having a value greater than the "Max Size" defined in the "Popular Term Autocomplete" section above has no effect.]]></comment>
                 </field>
                 <field id="stop_extension_on_match" translate="label comment" type="select" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1" canRestore="1">
-                    <label>Stop the extension mechanism when the current search term of the user is suggested.</label>
+                    <label>No extension for actual popular search terms</label>
                     <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                     <depends>
                         <field id="extension_enabled">1</field>
                     </depends>
-                    <comment><![CDATA[Default: No. When set to "Yes", this setting will discard the extension mechanism as soon as the exact search term entered by the user is part of the suggestions. Eg : When the user has finished to type "computer", if the list of suggested search terms is "computer", "apple computer", "computer for kids", only "computer" will be considered as it's exactly what the user has written.]]></comment>
+                    <comment><![CDATA[Default: No. When set to "Yes", the extension mechanism will be discarded when the search term entered by the user is amongst the popular terms suggestions. Eg : When the user has finished typing "computer", if the list of suggested search terms is ("computer", "apple computer", "computer for kids"), only "computer" will be taken into account for the products and categories autocomplete.]]></comment>
                 </field>
             </group>
         </section>
diff --git a/src/module-elasticsuite-core/etc/config.xml b/src/module-elasticsuite-core/etc/config.xml
index 7a50397f7..a26a31e15 100644
--- a/src/module-elasticsuite-core/etc/config.xml
+++ b/src/module-elasticsuite-core/etc/config.xml
@@ -55,9 +55,10 @@
             </term_autocomplete>
             <advanced>
                 <extension_enabled>1</extension_enabled>
+                <preserve_base_query>0</preserve_base_query>
                 <extension_limited>0</extension_limited>
+                <extension_size>5</extension_size>
                 <stop_extension_on_match>0</stop_extension_on_match>
-                <preserve_base_query>0</preserve_base_query>
             </advanced>
         </smile_elasticsuite_autocomplete_settings>
 
diff --git a/src/module-elasticsuite-core/view/adminhtml/web/css/source/_module.less b/src/module-elasticsuite-core/view/adminhtml/web/css/source/_module.less
index 620cca5bd..7d986c1b6 100644
--- a/src/module-elasticsuite-core/view/adminhtml/web/css/source/_module.less
+++ b/src/module-elasticsuite-core/view/adminhtml/web/css/source/_module.less
@@ -31,6 +31,10 @@ fieldset.radioset-tooltip {
         border-width: 1px 0;
         margin: @indent__l 0;
         padding: @indent__m;
+
+        #row_smile_elasticsuite_autocomplete_settings_advanced_info & {
+            margin-top: 0;
+        }
     }
 
     &.config-comment-title {