UX: Display setting description for objects typed theme setting (#26152)

Why this change?

Prior to this change, there is no description being displayed for
objects typed theme setting because we were rendering a button instead
of the components for the various setting types which will render the
setting's description.

What does this change do?

1. Introduce `SiteSettings::Description` compoment to centralise the HTML
being rendered across all settings component.

2. Renders the `SiteSettings::Description` component after the edit
   button in `site_setting.hbs`.

app/assets/javascripts/admin/addon/components/site-setting.hbs

@@ -32,6 +32,8 @@
       @label={{this.settingEditButton.label}}
       class="setting-value-edit-button"
     />
+
+    <SiteSettings::Description @description={{this.setting.description}} />
   {{else}}
     {{component
       this.componentName

app/assets/javascripts/admin/addon/components/site-settings/category-list.gjs

@@ -3,8 +3,8 @@ import { tracked } from "@glimmer/tracking";
 import { action } from "@ember/object";
 import didUpdate from "@ember/render-modifiers/modifiers/did-update";
 import Category from "discourse/models/category";
-import htmlSafe from "discourse-common/helpers/html-safe";
 import SettingValidationMessage from "admin/components/setting-validation-message";
+import SiteSettingsDescription from "admin/components/site-settings/description";
 import CategorySelector from "select-kit/components/category-selector";
 
 export default class CategoryList extends Component {
@@ -51,7 +51,7 @@ export default class CategoryList extends Component {
         @onChange={{this.onChangeSelectedCategories}}
       />
 
-      <div class="desc">{{htmlSafe this.setting.description}}</div>
+      <SiteSettingsDescription @description={{this.setting.description}} />
       <SettingValidationMessage @message={{this.validationMessage}} />
     </div>
   </template>

app/assets/javascripts/admin/addon/components/site-settings/category.hbs

@@ -4,4 +4,4 @@
   @options={{hash allowUncategorized=true none=(eq this.setting.default "")}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/color.hbs

@@ -6,4 +6,4 @@
   @onChangeColor={{this.onChangeColor}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/compact-list.hbs

@@ -8,4 +8,4 @@
 />
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/description.gjs

@@ -0,0 +1,5 @@
+import htmlSafe from "discourse-common/helpers/html-safe";
+
+<template>
+  <div class="desc">{{htmlSafe @description}}</div>
+</template>

app/assets/javascripts/admin/addon/components/site-settings/emoji-list.hbs

@@ -1,3 +1,3 @@
 <EmojiValueList @setting={{this.setting}} @values={{this.value}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />
 <SettingValidationMessage @message={{this.validationMessage}} />

app/assets/javascripts/admin/addon/components/site-settings/enum.hbs

@@ -10,7 +10,4 @@
 {{this.preview}}
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-
+<SiteSettings::Description @description={{this.setting.description}} />
-<div class="desc">
-  {{html-safe this.setting.description}}
-</div>

app/assets/javascripts/admin/addon/components/site-settings/file-size-restriction.gjs

@@ -2,9 +2,9 @@ import Component from "@glimmer/component";
 import { tracked } from "@glimmer/tracking";
 import { fn } from "@ember/helper";
 import { action } from "@ember/object";
-import { htmlSafe } from "@ember/template";
 import FileSizeInput from "admin/components/file-size-input";
 import SettingValidationMessage from "admin/components/setting-validation-message";
+import SiteSettingsDescription from "admin/components/site-settings/description";
 
 export default class FileSizeRestriction extends Component {
   @tracked _validationMessage = this.args.validationMessage;
@@ -29,6 +29,6 @@ export default class FileSizeRestriction extends Component {
     />
 
     <SettingValidationMessage @message={{this.validationMessage}} />
-    <div class="desc">{{htmlSafe @setting.description}}</div>
+    <SiteSettingsDescription @description={{this.setting.description}} />
   </template>
 }

app/assets/javascripts/admin/addon/components/site-settings/file-types-list.gjs

@@ -5,11 +5,11 @@ import { action } from "@ember/object";
 import { service } from "@ember/service";
 import { isEmpty } from "@ember/utils";
 import DButton from "discourse/components/d-button";
-import htmlSafe from "discourse-common/helpers/html-safe";
 import i18n from "discourse-common/helpers/i18n";
 import { makeArray } from "discourse-common/lib/helpers";
 import I18n from "discourse-i18n";
 import SettingValidationMessage from "admin/components/setting-validation-message";
+import SiteSettingsDescription from "admin/components/site-settings/description";
 import ListSetting from "select-kit/components/list-setting";
 
 const IMAGE_TYPES = [
@@ -147,6 +147,6 @@ export default class FileTypesList extends Component {
     />
 
     <SettingValidationMessage @message={{this.validationMessage}} />
-    <div class="desc">{{htmlSafe @setting.description}}</div>
+    <SiteSettingsDescription @description={{this.setting.description}} />
   </template>
 }

app/assets/javascripts/admin/addon/components/site-settings/group-list.hbs

@@ -7,4 +7,4 @@
   @onChange={{this.onChangeGroupListSetting}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/host-list.hbs

@@ -7,4 +7,4 @@
 />
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/integer.hbs

@@ -8,4 +8,4 @@
 />
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/list.hbs

@@ -4,4 +4,4 @@
   @choices={{this.setting.choices}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/named-list.hbs

@@ -9,4 +9,4 @@
 />
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/secret-list.hbs

@@ -4,4 +4,4 @@
   @isSecret={{this.isSecret}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/simple-list.hbs

@@ -6,4 +6,4 @@
   @allowAny={{this.setting.allow_any}}
 />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/string.hbs

@@ -7,4 +7,4 @@
 {{/if}}
 
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/tag-group-list.hbs

@@ -3,5 +3,5 @@
   @onChange={{this.onTagGroupChange}}
   @options={{hash filterPlaceholder="category.required_tag_group.placeholder"}}
 />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />
 <SettingValidationMessage @message={{this.validationMessage}} />

app/assets/javascripts/admin/addon/components/site-settings/tag-list.hbs

@@ -5,5 +5,5 @@
   @unlimitedTagCount={{true}}
   @options={{hash allowAny=false}}
 />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />
 <SettingValidationMessage @message={{this.validationMessage}} />

app/assets/javascripts/admin/addon/components/site-settings/upload.hbs

@@ -5,5 +5,5 @@
   @type="site_setting"
   @id={{concat "site-setting-image-uploader-" this.setting.setting}}
 />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />
 <SettingValidationMessage @message={{this.validationMessage}} />

app/assets/javascripts/admin/addon/components/site-settings/uploaded-image-list.hbs

@@ -5,5 +5,5 @@
     (hash value=this.value setting=this.setting)
   }}
 />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />
 <SettingValidationMessage @message={{this.validationMessage}} />

app/assets/javascripts/admin/addon/components/site-settings/url-list.hbs

@@ -1,3 +1,3 @@
 <ValueList @values={{this.value}} @addKey="admin.site_settings.add_url" />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

app/assets/javascripts/admin/addon/components/site-settings/value-list.hbs

@@ -1,3 +1,3 @@
 <ValueList @values={{this.value}} />
 <SettingValidationMessage @message={{this.validationMessage}} />
-<div class="desc">{{html-safe this.setting.description}}</div>
+<SiteSettings::Description @description={{this.setting.description}} />

spec/fixtures/theme_settings/objects_settings.yaml

@@ -1,4 +1,6 @@
 objects_setting:
+  description:
+    en: "This is a description for objects setting"
   type: objects
   default:
     - name: "section 1"

spec/system/admin_editing_objects_typed_theme_setting_spec.rb

@@ -33,6 +33,11 @@ RSpec.describe "Admin editing objects type theme setting", type: :system do
 
       expect(admin_customize_themes_page).to have_no_overriden_setting("objects_setting")
 
+      expect(admin_customize_themes_page).to have_setting_description(
+        "objects_setting",
+        "This is a description for objects setting",
+      )
+
       admin_objects_theme_setting_editor =
         admin_customize_themes_page.click_edit_objects_theme_setting_button("objects_setting")
 

spec/system/page_objects/pages/admin_customize_themes.rb

@@ -16,11 +16,15 @@ module PageObjects
       end
 
       def has_overridden_setting?(setting_name)
-        has_css?(overridden_setting_selector(setting_name))
+        has_css?(setting_selector(setting_name, overridden: true))
       end
 
       def has_no_overriden_setting?(setting_name)
-        has_no_css?(overridden_setting_selector(setting_name))
+        has_no_css?(setting_selector(setting_name, overridden: true))
+      end
+
+      def has_setting_description?(setting_name, description)
+        has_css?("#{setting_selector(setting_name)} .desc", exact_text: description)
       end
 
       def reset_overridden_setting(setting_name)
@@ -65,8 +69,8 @@ module PageObjects
 
       private
 
-      def overridden_setting_selector(setting_name)
+      def setting_selector(setting_name, overridden: false)
-        "section.theme.settings .setting.overridden[data-setting=\"#{setting_name}\"]"
+        "section.theme.settings .setting#{overridden ? ".overridden" : ""}[data-setting=\"#{setting_name}\"]"
       end
     end
   end