Form Select: Rails documentation update

docs/app/helpers/components_helper.rb

@@ -380,9 +380,9 @@ def sage_components
       },
       {
         title: "form_select",
-        description: "The form select presents a selectable menu of options. The options within the menu are represented by <option> elements.",
+        description: "The Select component is a user-friendly form control designed to let users pick an option or multiple options from a set. Upon selection, it presents a dialog showcasing all choices in an easily navigable list, with features like added context messages, error indications, and a disabled mode.",
         scss: "done",
-        docs: "todo",
+        docs: "done",
         rails: "done",
         react: "todo",
         responsive: "todo",

docs/app/views/examples/components/form_select/_preview.html.erb

@@ -1,178 +1,100 @@
-<h3 class="<%= SageClassnames::TYPE::HEADING_6 %>">Default</h3>
+<h2>Variants</h2>
+
+<h3>Default</h3>
+<p>The Default variation of the Select component is a simple HTML form element.</p>
 <%= sage_component SageFormSelect, {
-  name: "Characters",
-  id: "characters",
+  name: "Language",
+  id: "language",
   select_options: [
     {
-      text: "-- Please Select a Character --",
-      value: "",
-    },
-    {
-      text: "(None Specified)",
-      value: "",
+      text: "de - German",
+      value: "de",
     },
     {
-      text: "Mario",
-      value: "mario",
+      text: "en - English",
+      value: "en",
     },
     {
-      text: "Luigi",
-      value: "luigi",
+      text: "es - Spanish",
+      value: "es",
     },
     {
-      text: "Princess Peach",
-      value: "princess-peach",
+      text: "fi - Finnish",
+      value: "fi",
     },
     {
-      text: "Daisy",
-      value: "daisy",
-    },
-    {
-      text: "Toad",
-      value: "toad",
+      text: "fr - French",
+      value: "fr",
     },
   ],
-  message: "This is a message"
 } %>
 
-<h3 class="<%= SageClassnames::TYPE::HEADING_6 %>">Error state with message and disabled option</h3>
+<%= sage_component SageDivider, {} %>
+
+<h3>Select with Message</h3>
+<p>The Select component can be used with a message to provide additional context.</p>
+
 <%= sage_component SageFormSelect, {
-  name: "Pets",
-  has_error: true,
+  name: "Default Currency",
   select_options: [
     {
-      text: "-- Please Select a Pet --",
-      value: "",
-    },
-    {
-      text: "(None Specified)",
-      value: "",
-      selected: true
-    },
-    {
-      text: "Dog",
-      value: "dog",
-    },
-    {
-      text: "Cat",
-      value: "cat",
+      text: "USD - United States Dollar",
+      value: "USD",
     },
     {
-      text: "Hamster",
-      value: "hamster",
+      text: "AED - United Arab Emirates Dirham",
+      value: "AED",
     },
     {
-      text: "Parrot",
-      value: "parrot",
+      text: "AFN - Afghan Afghani",
+      value: "AFN",
     },
     {
-      text: "Spider",
-      value: "spider",
-      disabled: true
-    },
-    {
-      text: "Goldfish",
-      value: "goldfish",
+      text: "ALL - Albanian Lek",
+      value: "ALL",
     },
   ],
-  message: "This is a message"
+  message: "The default currency will be used for formatting and calculation purposes."
 } %>
 
-<h3 class="<%= SageClassnames::TYPE::HEADING_6 %>">Disabled (with pre-selected option)</h3>
-<%= sage_component SageFormSelect, {
-  name: "Sports",
-  disabled: true,
-  select_options: [
-    {
-      text: "Basketball",
-      value: "basketball"
-    },
-    {
-      text: "Football",
-      value: "football"
-    },
-    {
-      text: "Lacrosse",
-      value: "lacrosse"
-    },
-    {
-      text: "Baseball",
-      value: "baseball",
-      selected: true
-    },
-    {
-      text: "Blitzball",
-      value: "blitzball"
-    },
-  ]
-} %>
+<%= sage_component SageDivider, {} %>
+
+<h3>Error State</h3>
+<p>The Select component can indicate an error state.</p>
 
-<h3 class="<%= SageClassnames::TYPE::HEADING_6 %>">Optgroup use</h3>
 <%= sage_component SageFormSelect, {
-  name: "Sports!",
+  name: "Text direction",
+  has_error: true,
   select_options: [
     {
-      text: "Bowling",
-      value: "bowling",
-    },
-    {
-      group_label: "Hand Sports",
-      group_options: [
-        {
-          text: "Football",
-          value: "football",
-        },
-        {
-          text: "Basketball",
-          value: "basketball",
-        },
-      ],
-    },
-    {
-      text: "Nascar",
-      value: "nascar",
-      selected: true,
+      text: "Left to right (ltr)",
+      value: "ltr",
     },
     {
-      group_label: "Foot Sports",
-      group_options: [
-        {
-          text: "Soccer",
-          value: "soccer",
-        },
-      ],
+      text: "Right to left (rtl)",
+      value: "rtl",
     },
-  ]
+  ],
+  message: "This field is required."
 } %>
 
-<script>
-  const handleOnChange = (consoles) => {
-    var selectedText = consoles.options[consoles.selectedIndex].innerHTML;
-    var selectedVal = consoles.value;
-    alert("Selected Text: " + selectedText + " Value: " + selectedVal);
-  }
-</script>
-<h3 class="<%= SageClassnames::TYPE::HEADING_6 %>">Example on how to pass additional attributes to the component</h3>
+<%= sage_component SageDivider, {} %>
+
+<h3>Disabled</h3>
+<p>The Select component can be marked as disabled. Selects labeled as Disabled will not be submitted in forms.</p>
+
 <%= sage_component SageFormSelect, {
-  name: "Consoles",
-  component_attributes: {
-    onChange: "handleOnChange(this)",
-    "my-attribute": "hello"
-  },
+  name: "Text direction",
+  disabled: true,
   select_options: [
     {
-      text: "X-Box",
-      value: "x-box"
-    },
-    {
-      text: "PlayStation",
-      value: "playstation"
+      text: "Left to right (ltr)",
+      value: "ltr",
     },
     {
-      text: "Nintendo Switch",
-      value: "switch"
+      text: "Right to left (rtl)",
+      value: "rtl",
     },
-  ]
+  ],
+  message: "This field is not available until you select a language."
 } %>
-
-<p><strong>Note:</strong> For a fully styled dropdown selector, see the Dropdown component.</p>

docs/app/views/examples/components/form_select/_props.html.erb

@@ -1,18 +1,18 @@
 <tr>
   <td><%= md('`disabled`') %></td>
-  <td><%= md('Enabling this property adds the `disabled` attribute to the component. <br>⚠️ `disabled` inputs are not submitted in forms.') %></td>
+  <td><%= md('Enabling this property adds the `disabled` attribute to the component. `disabled` inputs are not submitted in forms.') %></td>
   <td><%= md('Boolean') %></td>
   <td><%= md('`false`') %></td>
 </tr>
 <tr>
   <td><%= md('`has_error`') %></td>
-  <td><%= md('Enabling this property adds the `.sage-form-field--error` class to the component.') %></td>
+  <td><%= md('Enabling this property styles the select in the default danger color theme.') %></td>
   <td><%= md('Boolean') %></td>
   <td><%= md('`false`') %></td>
 </tr>
 <tr>
   <td><%= md('`message`') %></td>
-  <td><%= md('Sets the message text for the component.') %></td>
+  <td><%= md('Displays the message text for the component.') %></td>
   <td><%= md('String') %></td>
   <td><%= md('`nil`') %></td>
 </tr>