docs(cb-a11y): Content - Form controls

Author: AlmeroSteyn

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-form-controls.component.html

@@ -50,9 +50,11 @@ <h3>Hiding labels</h3>
             <hr>
         </header>
 
+        <!-- #docregion cb-a11y-form-controls-hidden-labels-usage -->
         <a11y-hidden-labels [label1]="'Search:'"
                             [label2]="'Filter:'">
         </a11y-hidden-labels>
+        <!--#enddocregion-->
 
     </section>
     <section class="row well">

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.css

@@ -1,3 +1,4 @@
+/* #docregion */
 label {
     border: 0;
     clip: rect(0 0 0 0);
@@ -8,7 +9,7 @@ label {
     position: absolute;
     width: 1px;
 }
-
+/* #enddocregion */
 input {
     margin-bottom: 1em;
 }

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.html

@@ -1,3 +1,4 @@
+<!-- #docregion -->
 <div class="form-group">
 
     <label [attr.for]="uniqueId">
@@ -11,4 +12,5 @@
            [attr.aria-label]="label2"
            class="form-control">
 
-</div>
+</div>
+<!-- #enddocregion -->

public/docs/_examples/cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.ts

@@ -1,6 +1,7 @@
 import {Component, OnInit, Input} from "angular2/core";
 import {A11yHelper} from "./../services/a11y-helper.service";
 
+// #docregion
 @Component({
     selector: 'a11y-hidden-labels',
     templateUrl: './app/form-controls/a11y-hidden-labels.component.html',
@@ -19,4 +20,5 @@ export class A11yHiddenLabels implements OnInit{
     ngOnInit(){
         this.uniqueId = this._a11yHelper.generateUniqueIdString();
     }
-}
+}
+// #enddocregion

public/docs/ts/latest/cookbook/a11y.jade

@@ -60,6 +60,8 @@ include ../_util-fns
 
     So without further ado, let us see how easy it is to get big accessibility gains in our applications!
 
+    **Feel free to follow along in this [live example](/resources/live-examples/cb-a11y/ts/plnkr.html)**.
+
 .l-main-section
 :marked
     ## Important note on styling in this chapter
@@ -352,6 +354,41 @@ code-example(language="html" escape="html" format="linenums").
         </div>
         </a11y-input-explicit>
 
+:marked
+    ### Hidden labels
+
+    Sometimes, the design of your page makes more send without a visible label. Think about `search` fields. Do you have
+    to provide a visual label for each one?
+
+    The answer is no. But does that mean we get away with not labelling the field at all?
+
+    Once again the answer is no.
+
+    So how do we solve it?
+
+    We can either use an `explicitly labelled` input and hide the label with style, or we can use the `aria-label`, which
+    is an `ARIA Property`.
+
+    **NOTE:**: We cannot hide the label using the `display` css property. Hidden fields are also hidden to assistive
+    technologies so we have to use some css magic to either position the label outside of the visible page or
+    shrinking it right down to be absolutely minute. We wont see it but screen readers will still find it and read it while
+    still linking it to the correct input via the `for / id' linkup.
+
+    So why don't we create a component showing off both, and use the internal component styles to hide the label.
+
++makeTabs('cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.html, cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.ts, cb-a11y/ts/app/form-controls/a11y-hidden-labels.component.css', null, 'a11y-hidden-labels.component.html,a11y-hidden-labels.component.ts,a11y-hidden-labels.component.css')
+
+:marked
+    Which can then be used as:
+
++makeExample('cb-a11y/ts/app/form-controls/a11y-form-controls.component.html','cb-a11y-form-controls-hidden-labels-usage')
+
+:marked
+    The way the label is rendered int he final `HTML` is no secret to us anymore, but when you inspect the second input,
+    you will see that an `aria-label` attribute has been added to the input. Simplified:
+
+code-example(language="html" escape="html" format="linenums").
+                <input aria-label="Filter:">
 
 .l-main-section
 <a id="keyboard-shortcuts"></a>