From a87e20b5c7ff6d0d66aba1a19703c51f20d3d2aa Mon Sep 17 00:00:00 2001
From: Jeremy Thomas <bbxdesign@gmail.com>
Date: Sun, 13 Oct 2019 20:06:56 +0100
Subject: [PATCH] Improve form documentation

---
 docs/documentation/form/file.html     |  32 +++----
 docs/documentation/form/general.html  |  81 ++++++++++++++----
 docs/documentation/form/input.html    |  18 ++--
 docs/documentation/form/select.html   | 118 +++++++++++++++++---------
 docs/documentation/form/textarea.html |  46 +++++++++-
 5 files changed, 213 insertions(+), 82 deletions(-)

diff --git a/docs/documentation/form/file.html b/docs/documentation/form/file.html
index b7dafc79..9c484b97 100644
--- a/docs/documentation/form/file.html
+++ b/docs/documentation/form/file.html
@@ -568,31 +568,31 @@ meta:
 
 <div class="content">
   <p>
-    The <code>.file</code> element is a simple <strong>interactive label</strong> that wraps an <code>&lt;input type="file"&gt;</code>. It comprises several sub-elements:
+    The <code>file</code> element is a simple <strong>interactive label</strong> that wraps an <code>&lt;input type="file"&gt;</code>. It comprises several sub-elements:
   </p>
   <ul>
     <li>
-      <code>.file</code> the main <strong>container</strong>
+      <code>file</code> the main <strong>container</strong>
       <ul>
         <li>
-          <code>.file-label</code> the actual <strong>interactive</strong> and clickable part of the element
+          <code>file-label</code> the actual <strong>interactive</strong> and clickable part of the element
           <ul>
             <li>
-              <code>.file-input</code> the <strong>native</strong> file input, hidden for styling purposes
+              <code>file-input</code> the <strong>native</strong> file input, hidden for styling purposes
             </li>
             <li>
-              <code>.file-cta</code> the upload <strong>call-to-action</strong>
+              <code>file-cta</code> the upload <strong>call-to-action</strong>
               <ul>
                 <li>
-                  <code>.file-icon</code> an optional <strong>upload</strong> icon
+                  <code>file-icon</code> an optional <strong>upload</strong> icon
                 </li>
                 <li>
-                  <code>.file-label</code> the "Choose a file…" text
+                  <code>file-label</code> the "Choose a file…" text
                 </li>
               </ul>
             </li>
             <li>
-              <code>.file-name</code> a container for the <strong>chosen file</strong> name
+              <code>file-name</code> a container for the <strong>chosen file</strong> name
             </li>
           </ul>
         </li>
@@ -609,7 +609,7 @@ meta:
   <div class="column">
     <div class="content">
       <p>
-        With the <code>.has-name</code> modifier combined with the <code>.file-name</code> element, you can add a <strong>placeholder</strong> for the selected file name.
+        With the <code>has-name</code> modifier combined with the <code>file-name</code> element, you can add a <strong>placeholder</strong> for the selected file name.
       </p>
     </div>
     <div class="bd-example">
@@ -625,7 +625,7 @@ meta:
   <div class="column">
     <div class="content">
       <p>
-        You can move the CTA to the <strong>right side</strong> with the <code>.is-right</code> modifier.
+        You can move the CTA to the <strong>right side</strong> with the <code>is-right</code> modifier.
       </p>
     </div>
     <div class="bd-example">
@@ -641,7 +641,7 @@ meta:
   <div class="column">
     <div class="content">
       <p>
-        You can also <strong>expand</strong> the name to fill up the space with the <code>.is-fullwidth</code> modifier.
+        You can also <strong>expand</strong> the name to fill up the space with the <code>is-fullwidth</code> modifier.
       </p>
     </div>
     <div class="bd-example">
@@ -657,7 +657,7 @@ meta:
   <div class="column">
     <div class="content">
       <p>
-        You can have a <strong>boxed block</strong> with the <code>.is-boxed</code> modifier.
+        You can have a <strong>boxed block</strong> with the <code>is-boxed</code> modifier.
       </p>
     </div>
     <div class="bd-example">
@@ -673,7 +673,7 @@ meta:
   <div class="column">
     <div class="content">
       <p>
-        You can <strong>combine</strong> <code>.has-name</code> and <code>.is-boxed</code>.
+        You can <strong>combine</strong> <code>has-name</code> and <code>is-boxed</code>.
       </p>
     </div>
     <div class="bd-example">
@@ -710,13 +710,13 @@ meta:
   </p>
   <ul>
     <li>
-      <code>.is-small</code>
+      <code>is-small</code>
     </li>
     <li>
-      <code>.is-medium</code>
+      <code>is-medium</code>
     </li>
     <li>
-      <code>.is-large</code>
+      <code>is-large</code>
     </li>
   </ul>
 </div>
diff --git a/docs/documentation/form/general.html b/docs/documentation/form/general.html
index 77630862..be0b8791 100644
--- a/docs/documentation/form/general.html
+++ b/docs/documentation/form/general.html
@@ -106,6 +106,12 @@ variables_keys:
 </div>
 {% endcapture %}
 
+{% capture control_example %}
+<div class="control">
+  <input class="input" type="text" placeholder="Text input">
+</div>
+{% endcapture %}
+
 {% capture field_example %}
 <div class="field">
   <label class="label">Label</label>
@@ -807,23 +813,66 @@ variables_keys:
 {% endcapture %}
 
 <div class="content">
-  <p>The following form controls <strong>classes</strong> are supported:</p>
+  <p>
+    Bulma supports the following native <strong>HTML form elements</strong>: <code>&lt;form&gt;</code> <code>&lt;button&gt;</code> <code>&lt;input&gt;</code> <code>&lt;textarea&gt;</code> and <code>&lt;label&gt;</code>.
+  </p>
+  <p>
+    The following CSS <strong>classes</strong> are supported:
+  </p>
   <ul>
-    <li><code>.label</code></li>
-    <li><code>.input</code></li>
-    <li><code>.textarea</code></li>
-    <li><code>.select</code></li>
-    <li><code>.checkbox</code></li>
-    <li><code>.radio</code></li>
-    <li><code>.button</code></li>
-    <li><code>.help</code></li>
+    <li><code>label</code></li>
+    <li><code>input</code></li>
+    <li><code>textarea</code></li>
+    <li><code>select</code></li>
+    <li><code>checkbox</code></li>
+    <li><code>radio</code></li>
+    <li><code>button</code></li>
+    <li><code>help</code></li>
   </ul>
-  <p>Each of them should be wrapped in a <code>.control</code> container.<br>
-  When combining several controls in a <strong>form</strong>, use the <code>.field</code> class as a <strong>container</strong>, to keep the spacing consistent.</p>
 </div>
 
+<div class="content">
+  <p>
+    To maintain the design evenly balanced, Bulma provides a very useful <code>control</code> container with which you can <strong>wrap</strong> the form controls.
+    <br>
+    When combining several controls in a <strong>form</strong>, use the <code>field</code> class as a <strong>container</strong>, to keep the spacing consistent.
+  </p>
+</div>
+
+{% include elements/anchor.html name="Complete form example" %}
+
 {% include elements/snippet.html content=example more=true %}
 
+{% include elements/anchor.html name="Form control" %}
+
+<div class="content">
+  <p>
+    The <code>control</code> element is a wrapper for form controls. It gives the possibility to:
+  </p>
+  <ul>
+    <li>
+      resize form controls
+    </li>
+    <li>
+      combine form controls into a group
+    </li>
+    <li>
+      combine form controls into a list
+    </li>
+    <li>
+      append and prepend icons to a form control
+    </li>
+  </ul>
+</div>
+
+{% include elements/snippet.html content=control_example %}
+
+<div class="content">
+  <p>
+    For the best results using Bulma, it's recommended to use the <code>control</code> element as often as possible.
+  </p>
+</div>
+
 {% include elements/anchor.html name="Form field" %}
 
 <div class="content">
@@ -1015,20 +1064,20 @@ variables_keys:
 
 <div class="content">
   <p>
-    To preserve the <strong>vertical alignment</strong> of labels with each type and size of control, the <code>.field-label</code> comes with <strong>4 size modifiers</strong>:
+    To preserve the <strong>vertical alignment</strong> of labels with each type and size of control, the <code>field-label</code> comes with <strong>4 size modifiers</strong>:
   </p>
   <ul>
     <li>
-      <code>.is-small</code>
+      <code>is-small</code>
     </li>
     <li>
-      <code>.is-normal</code> for any <code>.input</code> or <code>.button</code>
+      <code>is-normal</code> for any <code>input</code> or <code>button</code>
     </li>
     <li>
-      <code>.is-medium</code>
+      <code>is-medium</code>
     </li>
     <li>
-      <code>.is-large</code>
+      <code>is-large</code>
     </li>
   </ul>
 </div>
diff --git a/docs/documentation/form/input.html b/docs/documentation/form/input.html
index 18d362da..0243a07d 100644
--- a/docs/documentation/form/input.html
+++ b/docs/documentation/form/input.html
@@ -249,19 +249,23 @@ meta:
 {% endcapture %}
 
 <div class="content">
-  <p>The following <strong>modifiers</strong> are supported:</p>
-  <ul>
-    <li>the <strong><a href="#colors">color</a></strong></li>
-    <li>the <strong><a href="#sizes">size</a></strong></li>
-    <li>the <strong><a href="#states">state</a></strong></li>
-  </ul>
-  <p>The following <a href="http://htmlreference.io/element/input/" target="_blank">type attributes</a> are supported:</p>
+  <p>
+    The Bulma <code>input</code> CSS class is meant for <code>&lt;input"&gt;</code> HTML elements. The following <a href="http://htmlreference.io/element/input/" target="_blank">type attributes</a> are supported:
+  </p>
   <ul>
     <li><code>type="text"</code></li>
     <li><code>type="password"</code></li>
     <li><code>type="email"</code></li>
     <li><code>type="tel"</code></li>
   </ul>
+  <p>
+   Several <strong>modifiers</strong> are supported which affect:
+  </p>
+  <ul>
+    <li>the <strong><a href="#colors">color</a></strong></li>
+    <li>the <strong><a href="#sizes">size</a></strong></li>
+    <li>the <strong><a href="#states">state</a></strong></li>
+  </ul>
 </div>
 
 <div class="columns">
diff --git a/docs/documentation/form/select.html b/docs/documentation/form/select.html
index dea0d061..f90fc8ea 100644
--- a/docs/documentation/form/select.html
+++ b/docs/documentation/form/select.html
@@ -280,7 +280,22 @@ meta:
 {% endcapture %}
 
 <div class="content">
-  <p>The following <strong>modifiers</strong> are supported:</p>
+  <p>
+    The <code>select</code> class is a simple wrapper around the <code>&lt;select"&gt;</code> HTML element, which gives the styling more flexibility and support for icons.
+  </p>
+</div>
+
+<div class="columns">
+  <div class="column is-half">
+    {{ select_example }}
+  </div>
+  <div class="column is-half highlight-full">
+    {% highlight html %}{{ select_example }}{% endhighlight %}
+  </div>
+</div>
+
+<div class="content">
+  <p>Several <strong>modifiers</strong> are supported which affect:</p>
   <ul>
     <li>the <strong><a href="#select-color">color</a></strong></li>
     <li>the <strong><a href="#select-size">size</a></strong></li>
@@ -288,18 +303,7 @@ meta:
   </ul>
 </div>
 
-<div class="columns">
-  <div class="column is-half">
-    {{select_example}}
-  </div>
-  <div class="column is-half highlight-full">
-    {% highlight html %}{{select_example}}{% endhighlight %}
-  </div>
-</div>
-
-<hr>
-
-<h3 class="title">Multiple select</h3>
+{% include elements/anchor.html name="Multiple select" %}
 
 <div class="columns">
   <div class="column is-half">
@@ -308,10 +312,10 @@ meta:
         You can style a <strong>multiple select</strong> dropdown, by using the <code>is-multiple</code> modifier, and by using the <code>multiple</code> HTML attribute.
       </p>
     </div>
-    {{select_multiple_example}}
+    {{ select_multiple_example }}
   </div>
   <div class="column is-half highlight-full">
-    {% highlight html %}{{select_multiple_example}}{% endhighlight %}
+    {% highlight html %}{{ select_multiple_example }}{% endhighlight %}
   </div>
 </div>
 
@@ -319,10 +323,10 @@ meta:
 
 <div class="columns">
   <div class="column is-half">
-    {{colors_example}}
+    {{ colors_example }}
   </div>
   <div class="column is-half highlight-full">
-    {% highlight html %}{{colors_example}}{% endhighlight %}
+    {% highlight html %}{{ colors_example }}{% endhighlight %}
   </div>
 </div>
 
@@ -330,6 +334,12 @@ meta:
 
 {% include elements/new-tag.html version="0.6.2" %}
 
+<div class="content">
+  <p>
+    You can create a <strong>rounded dropdown</strong> by appending the <code>is-rounded</code> modifier:
+  </p>
+</div>
+
 <div class="columns">
   <div class="column is-half">
     {{ rounded_example }}
@@ -341,62 +351,86 @@ meta:
 
 {% include elements/anchor.html name="Sizes" %}
 
+<div class="content">
+  <p>
+    The <code>select</code> element comes in <strong>4</strong> different sizes:
+  </p>
+</div>
+
 <div class="columns">
   <div class="column is-half">
-    {{sizes_example}}
+    {{ sizes_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{sizes_example}}{% endhighlight %}
+    {% highlight html %}{{ sizes_example }}{% endhighlight %}
   </div>
 </div>
 
-<hr>
+{% include elements/anchor.html name="States" %}
+
+<div class="content">
+  <p>
+    Bulma styles the different <strong>states</strong> of the <code>select</code> elment. Each state is available as a pseudo-class and a CSS class:
+  </p>
+  <ul>
+    <li>
+      <code>:hover</code> and <code>is-hovered</code>
+    </li>
+    <li>
+      <code>:focus</code> and <code>is-focused</code>
+    </li>
+    <li>
+      <code>:active</code> and <code>is-active</code>
+    </li>
+  </ul>
+  <p>
+    This allows you to obtain the style of a certain state without having to trigger it.
+  </p>
+</div>
 
-<h3 id="select-state" class="title">States</h3>
 <h4 class="subtitle">Normal</h4>
+
 <div class="columns">
   <div class="column is-half">
-    {{normal_example}}
+    {{ normal_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{normal_example}}{% endhighlight %}
+    {% highlight html %}{{ normal_example }}{% endhighlight %}
   </div>
 </div>
 
 <h4 class="subtitle">Hover</h4>
 <div class="columns">
   <div class="column is-half">
-    {{hover_example}}
+    {{ hover_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{hover_example}}{% endhighlight %}
+    {% highlight html %}{{ hover_example }}{% endhighlight %}
   </div>
 </div>
 
 <h4 class="subtitle">Focus</h4>
 <div class="columns">
   <div class="column is-half">
-    {{focus_example}}
+    {{ focus_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{focus_example}}{% endhighlight %}
+    {% highlight html %}{{ focus_example }}{% endhighlight %}
   </div>
 </div>
 
 <h4 class="subtitle">Loading</h4>
 <div class="columns">
   <div class="column is-half">
-    {{loading_example}}
+    {{ loading_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{loading_example}}{% endhighlight %}
+    {% highlight html %}{{ loading_example }}{% endhighlight %}
   </div>
 </div>
 
-<!-- Font Awesome Icons -->
-<hr>
+{% include elements/anchor.html name="With icons" %}
 
-<h3 id="input-with-icons" class="title">With icons</h3>
 <div class="content">
   <p>You can append the <strong>modifier</strong> on a control:</p>
   <ul>
@@ -414,10 +448,10 @@ meta:
 </div>
 <div class="columns">
   <div class="column is-half">
-    {{icons_example}}
+    {{ icons_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{icons_example}}{% endhighlight %}
+    {% highlight html %}{{ icons_example }}{% endhighlight %}
   </div>
 </div>
 
@@ -428,36 +462,36 @@ meta:
         If the control contains an icon, Bulma will make sure the icon remains <strong>centered</strong>, no matter the size of the input <em>or</em> of the icon.
       </p>
     </div>
-    {{has_icons_small_example}}
+    {{ has_icons_small_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{has_icons_small_example}}{% endhighlight %}
+    {% highlight html %}{{ has_icons_small_example }}{% endhighlight %}
   </div>
 </div>
 
 <div class="columns">
   <div class="column is-half">
-    {{has_icons_normal_example}}
+    {{ has_icons_normal_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{has_icons_normal_example}}{% endhighlight %}
+    {% highlight html %}{{ has_icons_normal_example }}{% endhighlight %}
   </div>
 </div>
 
 <div class="columns">
   <div class="column is-half">
-    {{has_icons_medium_example}}
+    {{ has_icons_medium_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{has_icons_medium_example}}{% endhighlight %}
+    {% highlight html %}{{ has_icons_medium_example }}{% endhighlight %}
   </div>
 </div>
 
 <div class="columns">
   <div class="column is-half">
-    {{has_icons_large_example}}
+    {{ has_icons_large_example }}
   </div>
   <div class="column is-half">
-    {% highlight html %}{{has_icons_large_example}}{% endhighlight %}
+    {% highlight html %}{{ has_icons_large_example }}{% endhighlight %}
   </div>
 </div>
diff --git a/docs/documentation/form/textarea.html b/docs/documentation/form/textarea.html
index e7e071f2..b1f28478 100644
--- a/docs/documentation/form/textarea.html
+++ b/docs/documentation/form/textarea.html
@@ -132,6 +132,12 @@ meta:
 </div>
 {% endcapture %}
 
+<div class="content">
+  <p>
+    The Bulma <code>textarea</code> CSS class is the multiline version of the <a href="{{ site.data.links.by_id.form-input.path }}"><code>input</code> element</a>:
+  </p>
+</div>
+
 {% include elements/snippet.html content=textarea_example %}
 
 {% capture fixedsize_example %}
@@ -142,7 +148,7 @@ meta:
 
 <div class="content">
   <p>
-    You can set the height of the textarea using the `rows` HTML attribute.
+    You can set the height of the textarea using the <code>rows</code> HTML attribute.
   </p>
 </div>
 
@@ -150,14 +156,46 @@ meta:
 
 {% include elements/anchor.html name="Colors" %}
 
+<div class="content">
+  <p>
+    The <code>textarea</code> element is available in several colors:
+  </p>
+</div>
+
 {% include elements/snippet.html content=colors_example %}
 
 {% include elements/anchor.html name="Sizes" %}
 
+<div class="content">
+  <p>
+    The <code>textarea</code> element comes in <strong>4 different sizes:</strong>
+  </p>
+</div>
+
 {% include elements/snippet.html content=sizes_example %}
 
 {% include elements/anchor.html name="States" %}
 
+<div class="content">
+  <p>
+    Bulma styles the different <strong>states</strong> of the <code>textarea</code> elment. Each state is available as a pseudo-class and a CSS class:
+  </p>
+  <ul>
+    <li>
+      <code>:hover</code> and <code>is-hovered</code>
+    </li>
+    <li>
+      <code>:focus</code> and <code>is-focused</code>
+    </li>
+    <li>
+      <code>:active</code> and <code>is-active</code>
+    </li>
+  </ul>
+  <p>
+    This allows you to obtain the style of a certain state without having to trigger it.
+  </p>
+</div>
+
 <h4 class="subtitle">Normal</h4>
 
 {% include elements/snippet.html content=normal_example %}
@@ -209,4 +247,10 @@ meta:
 
 <h4 class="subtitle">Fixed Size</h4>
 
+<div class="content">
+  <p>
+    You can disable a <code>textarea</code> resizing by appending the <code>has-fixed-size</code> modifier:
+  </p>
+</div>
+
 {% include elements/snippet.html content=fixedsize_example %}