docs(getting-started): add accessibility description section to Getti…

…ng started page (#3944)

* docs(getting-started): add accessibility decscription section to Getting started page

* add accessibility description sections

demo/src/app/common/getting-started/getting-started.component.html

@@ -56,6 +56,7 @@ <h2>Table of contents</h2>
         <li><a routerLink="." fragment="api">API</a></li>
         <li><a routerLink="." fragment="troubleshooting">Troubleshooting</a></li>
         <li><a routerLink="." fragment="contribution">Contributing</a></li>
+        <li><a routerLink="." fragment="accessibility">Accessibility</a></li>
         <!--<li><a routerLink="." fragment="license">License</a></li>-->
       </ol>
 
@@ -127,6 +128,37 @@ <h3>Credits</h3>
         <a href="https://www.browserstack.com">Browser Stack</a>
         <a href="https://www.browserstack.com"><img src="https://camo.githubusercontent.com/a7b268f2785656ab3ca7b1cbb1633ee5affceb8f/68747470733a2f2f64677a6f7139623561736a67312e636c6f756466726f6e742e6e65742f70726f64756374696f6e2f696d616765732f6c61796f75742f6c6f676f2d6865616465722e706e67" alt="Browser Stack" height="31px"></a>
       </p>
+
+      <h2 id="accessibility">Accessibility</h2>
+
+      <h3>Overview and Limitations</h3>
+
+      <p>The overall accessibility of any project built with ngx-bootstrap depends in large part on the author’s markup, additional styling, and scripting they’ve included.
+        However, provided that these have been implemented correctly, it should be perfectly possible to create websites and applications
+        that fulfill <a href="https://www.w3.org/TR/WCAG20/"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.0</a> (A/AA/AAA),
+        <a href="https://www.section508.gov/">Section 508</a> and similar accessibility standards and requirements.</p>
+
+      <h3>Interactive components</h3>
+
+      <p>Interactive components—such as modal dialogs, dropdown menus and custom tooltips—are designed to work for touch, mouse and keyboard users.
+        Through the use of relevant <a href="https://www.w3.org/WAI/intro/aria"><abbr title="Web Accessibility Initiative">WAI</abbr>-<abbr title="Accessible Rich Internet Applications">ARIA</abbr></a>
+        roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers).</p>
+      <p>Authors need to include ARIA roles and attributes to more accurately convey the precise nature of their component. </p>
+
+      <h3>Color contrast</h3>
+
+      <p>Most colors that currently make up Bootstrap’s default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—lead to <em>insufficient</em> color contrast (below the recommended <a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html">WCAG 2.0 color contrast ratio of 4.5:1</a>) when used against a light background. Authors will need to manually modify/extend these default colors to ensure adequate color contrast ratios.</p>
+
+      <h3>Additional resources</h3>
+
+      <ul>
+        <li><a href="https://www.w3.org/TR/WCAG20/">Web Content Accessibility Guidelines (WCAG) 2.0</a></li>
+        <li><a href="http://a11yproject.com/">The A11Y Project</a></li>
+        <li><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility">MDN accessibility documentation</a></li>
+        <li><a href="https://tenon.io/">Tenon.io Accessibility Checker</a></li>
+        <li><a href="https://developer.paciellogroup.com/resources/contrastanalyser/">Colour Contrast Analyser (CCA)</a></li>
+        <li><a href="https://github.com/squizlabs/HTML_CodeSniffer">“HTML Codesniffer” bookmarklet for identifying accessibility issues</a></li>
+      </ul>
     </div>
   </div>
 </demo-section>

demo/src/app/components/+carousel/carousel-section.list.ts

@@ -8,6 +8,7 @@ import { DemoCarouselIntervalComponent } from './demos/interval/interval';
 import { DemoCarouselDisableIndicatorComponent } from './demos/disable-indicator/disable-indicator';
 import { DemoCarouselDisableLoopingComponent } from './demos/disable-looping/disable-looping';
 import { DemoCarouselSlideChangedEventComponent } from './demos/slide-changed-event/slide-changed-event';
+import { DemoAccessibilityComponent } from './demos/accessibility/accessibility';
 
 import { ContentSection } from '../../docs/models/content-section.model';
 import { DemoTopSectionComponent } from '../../docs/demo-section-components/demo-top-section/index';
@@ -103,6 +104,11 @@ export const demoComponentContent: ContentSection[] = [
         component: require('!!raw-loader?lang=typescript!./demos/slide-changed-event/slide-changed-event.ts'),
         html: require('!!raw-loader?lang=markup!./demos/slide-changed-event/slide-changed-event.html'),
         outlet: DemoCarouselSlideChangedEventComponent
+      },
+      {
+        title: 'Accessibility',
+        anchor: 'accessibility',
+        outlet: DemoAccessibilityComponent
       }
     ]
   },

demo/src/app/components/+carousel/demos/accessibility/accessibility.html

@@ -0,0 +1 @@
+<p>The <code>alt</code> attribute is meant to help users not miss any content, so make sure your text is helpful to anyone not seeing the image. </p>

demo/src/app/components/+carousel/demos/accessibility/accessibility.ts

@@ -0,0 +1,7 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-accessibility',
+  templateUrl: './accessibility.html'
+})
+export class DemoAccessibilityComponent {}

demo/src/app/components/+carousel/demos/index.ts

@@ -8,6 +8,7 @@ import { DemoCarouselIntervalComponent } from './interval/interval';
 import { DemoCarouselDisableIndicatorComponent } from './disable-indicator/disable-indicator';
 import { DemoCarouselDisableLoopingComponent } from './disable-looping/disable-looping';
 import { DemoCarouselSlideChangedEventComponent } from './slide-changed-event/slide-changed-event';
+import { DemoAccessibilityComponent } from './accessibility/accessibility';
 
 export const DEMO_COMPONENTS = [
   DemoCarouselDynamicComponent,
@@ -20,5 +21,6 @@ export const DEMO_COMPONENTS = [
   DemoCarouselIntervalComponent,
   DemoCarouselDisableIndicatorComponent,
   DemoCarouselDisableLoopingComponent,
-  DemoCarouselSlideChangedEventComponent
+  DemoCarouselSlideChangedEventComponent,
+  DemoAccessibilityComponent
 ];

demo/src/app/components/+collapse/collapse-section.list.ts

@@ -5,6 +5,7 @@ import { ContentSection } from '../../docs/models/content-section.model';
 import { DemoTopSectionComponent } from '../../docs/demo-section-components/demo-top-section/index';
 import { ExamplesComponent } from '../../docs/demo-section-components/demo-examples-section/index';
 import { ApiSectionsComponent } from '../../docs/demo-section-components/demo-api-section/index';
+import { DemoAccessibilityComponent } from './demos/accessibility/accessibility';
 
 import { NgApiDocComponent } from '../../docs/api-docs';
 
@@ -35,6 +36,11 @@ export const demoComponentContent: ContentSection[] = [
         component: require('!!raw-loader?lang=typescript!./demos/toggle-manual/toggle-manual'),
         html: require('!!raw-loader?lang=markup!./demos/toggle-manual/toggle-manual.html'),
         outlet: ToggleManualDemoComponent
+      },
+      {
+        title: 'Accessibility',
+        anchor: 'accessibility',
+        outlet: DemoAccessibilityComponent
       }
     ]
   },

demo/src/app/components/+collapse/demos/accessibility/accessibility.html

@@ -0,0 +1,3 @@
+<p>Be sure to add <code class="highlighter-rouge">aria-expanded</code> to the control element. This attribute explicitly conveys the current state of the collapsible element tied to the control to screen readers and similar assistive technologies. If the collapsible element is closed by default, the attribute on the control element should have a value of <code class="highlighter-rouge">aria-expanded="false"</code>. If you’ve set the collapsible element to be open by default using the <code class="highlighter-rouge">show</code> class, set <code class="highlighter-rouge">aria-expanded="true"</code> on the control instead. The plugin will automatically toggle this attribute on the control based on whether or not the collapsible element has been opened or closed. If the control element’s HTML element is not a button (e.g., an <code class="highlighter-rouge">&lt;a&gt;</code> or <code class="highlighter-rouge">&lt;div&gt;</code>), the attribute <code class="highlighter-rouge">role="button"</code> should be added to the element.</p>
+<p>If your control element is targeting a single collapsible element – i.e. the <code class="highlighter-rouge">data-target</code> attribute is pointing to an <code class="highlighter-rouge">id</code> selector – you should add the <code class="highlighter-rouge">aria-controls</code> attribute to the control element, containing the <code class="highlighter-rouge">id</code> of the collapsible element. Modern screen readers and similar assistive technologies make use of this attribute to provide users with additional shortcuts to navigate directly to the collapsible element itself.</p>
+

demo/src/app/components/+collapse/demos/accessibility/accessibility.ts

@@ -0,0 +1,7 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-accessibility',
+  templateUrl: './accessibility.html'
+})
+export class DemoAccessibilityComponent {}

demo/src/app/components/+collapse/demos/index.ts

@@ -1,7 +1,9 @@
 import { CollapseDemoComponent } from './basic/basic';
 import { ToggleManualDemoComponent } from './toggle-manual/toggle-manual';
+import { DemoAccessibilityComponent } from './accessibility/accessibility';
 
 export const DEMO_COMPONENTS = [
   CollapseDemoComponent,
-  ToggleManualDemoComponent
+  ToggleManualDemoComponent,
+  DemoAccessibilityComponent
 ];

demo/src/app/components/+dropdown/demos/accessibility/accessibility.html

@@ -0,0 +1,2 @@
+<p>The <a href="https://www.w3.org/TR/wai-aria/"><abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr></a> standard defines an actual <a href="https://www.w3.org/TR/wai-aria-1.1/#menu"><code class="highlighter-rouge">role="menu"</code> widget</a>, but this is specific to application-like menus which trigger actions or functions. <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus.</p>
+<p>Dropdowns, on the other hand, are designed to be generic and applicable to a variety of situations and markup structures. For instance, it is possible to create dropdowns that contain additional inputs and form controls, such as search fields or login forms. For this reason, ngx-bootstrap does not expect (nor automatically add) any of the <code class="highlighter-rouge">role</code> and <code class="highlighter-rouge">aria-</code> attributes required for true <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus. Authors will have to include these more specific attributes themselves.</p>

demo/src/app/components/+dropdown/demos/accessibility/accessibility.ts

@@ -0,0 +1,7 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-accessibility',
+  templateUrl: './accessibility.html'
+})
+export class DemoAccessibilityComponent {}

demo/src/app/components/+dropdown/demos/index.ts

@@ -15,6 +15,7 @@ import { DemoDropdownDisabledItemComponent } from './disabled-item/disabled-item
 import { DemoDropdownStateChangeEventComponent } from './state-change-event/state-change-event';
 import { DemoDropdownAutoCloseComponent } from './autoclose/autoclose';
 import { DemoDropdownCustomHtmlComponent } from './custom-html/custom-html';
+import { DemoAccessibilityComponent } from './accessibility/accessibility';
 
 export const DEMO_COMPONENTS = [
   DemoDropdownBasicComponent,
@@ -33,5 +34,6 @@ export const DEMO_COMPONENTS = [
   DemoDropdownVisibilityEventsComponent,
   DemoDropdownStateChangeEventComponent,
   DemoDropdownAutoCloseComponent,
-  DemoDropdownCustomHtmlComponent
+  DemoDropdownCustomHtmlComponent,
+  DemoAccessibilityComponent
 ];

demo/src/app/components/+dropdown/dropdown-section.list.ts

@@ -15,6 +15,7 @@ import { DemoDropdownVisibilityEventsComponent } from './demos/visibility-events
 import { DemoDropdownStateChangeEventComponent } from './demos/state-change-event/state-change-event';
 import { DemoDropdownAutoCloseComponent } from './demos/autoclose/autoclose';
 import { DemoDropdownCustomHtmlComponent } from './demos/custom-html/custom-html';
+import { DemoAccessibilityComponent } from './demos/accessibility/accessibility';
 
 import { ContentSection } from '../../docs/models/content-section.model';
 import { DemoTopSectionComponent } from '../../docs/demo-section-components/demo-top-section/index';
@@ -26,6 +27,7 @@ import {
   NgApiDocConfigComponent
 } from '../../docs/api-docs';
 
+
 export const demoComponentContent: ContentSection[] = [
   {
     name: 'Usage',
@@ -186,6 +188,11 @@ export const demoComponentContent: ContentSection[] = [
         html: require('!!raw-loader?lang=markup!./demos/autoclose/autoclose.html'),
         description: `<p>Use <code>autoClose</code> property to change dropdown's default behavior</p>`,
         outlet: DemoDropdownAutoCloseComponent
+      },
+      {
+        title: 'Accessibility',
+        anchor: 'accessibility',
+        outlet: DemoAccessibilityComponent
       }
     ]
   },

demo/src/app/components/+modal/demos/accessibility/accessibility.html

@@ -0,0 +1 @@
+<p>Be sure to add <code class="highlighter-rouge">role="dialog"</code> and <code class="highlighter-rouge">aria-labelledby="..."</code>, referencing the modal title, to <code class="highlighter-rouge">.modal</code>, and <code class="highlighter-rouge">role="document"</code> to the <code class="highlighter-rouge">.modal-dialog</code> itself. Additionally, you may give a description of your modal dialog with <code class="highlighter-rouge">aria-describedby</code> on <code class="highlighter-rouge">.modal</code>.</p>

demo/src/app/components/+modal/demos/accessibility/accessibility.ts

@@ -0,0 +1,7 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-accessibility',
+  templateUrl: './accessibility.html'
+})
+export class DemoAccessibilityComponent {}

demo/src/app/components/+modal/demos/index.ts

@@ -15,6 +15,7 @@ import { DemoModalServiceDisableBackdropComponent } from './service-options/disa
 import { DemoModalServiceEventsComponent } from './service-events/service-events';
 import { DemoModalServiceConfirmWindowComponent } from './service-confirm-window/service-confirm-window';
 import { DemoModalScrollingLongContentComponent } from './scrolling-long-content/scrolling-long-content';
+import { DemoAccessibilityComponent } from './accessibility/accessibility';
 
 export const DEMO_COMPONENTS = [
   DemoModalSizesComponent,
@@ -32,5 +33,6 @@ export const DEMO_COMPONENTS = [
   DemoModalEventsComponent,
   DemoModalServiceEventsComponent,
   DemoModalServiceConfirmWindowComponent,
-  DemoModalScrollingLongContentComponent
+  DemoModalScrollingLongContentComponent,
+  DemoAccessibilityComponent
 ];

demo/src/app/components/+modal/modal-section.list.ts

@@ -14,6 +14,7 @@ import { DemoModalChildComponent } from './demos/child/child';
 import { DemoModalNestedComponent } from './demos/nested/nested';
 import { DemoModalEventsComponent } from './demos/events/events';
 import { DemoAutoShownModalComponent } from './demos/auto-shown/auto-shown';
+import { DemoAccessibilityComponent } from './demos/accessibility/accessibility';
 
 import { ContentSection } from '../../docs/models/content-section.model';
 import { DemoTopSectionComponent } from '../../docs/demo-section-components/demo-top-section/index';
@@ -198,6 +199,11 @@ export const demoComponentContent: ContentSection[] = [
           want to defer that until user actually sees modal content. I.e. for a "Select e-mail recipient" modal
           you might want to defer recipient list loading until the modal is shown.</p>`,
         outlet: DemoAutoShownModalComponent
+      },
+      {
+        title: 'Accessibility',
+        anchor: 'accessibility',
+        outlet: DemoAccessibilityComponent
       }
     ]
   },

demo/src/app/components/+tabs/demos/accessibility/accessibility.html

@@ -0,0 +1 @@
+<p>Note that tabs can be given <code class="highlighter-rouge">role="tablist"</code>, <code class="highlighter-rouge">role="tab"</code> and <code class="highlighter-rouge">role="tabpanel"</code> attributes. These are appropriate for tabbed interfaces, as described in the <a href="https://www.w3.org/TR/wai-aria-practices/#tabpanel"><abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr> Authoring Practices</a>.</p>

demo/src/app/components/+tabs/demos/accessibility/accessibility.ts

@@ -0,0 +1,7 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-accessibility',
+  templateUrl: './accessibility.html'
+})
+export class DemoAccessibilityComponent {}

demo/src/app/components/+tabs/demos/index.ts

@@ -9,17 +9,20 @@ import { DemoTabsManualComponent } from './manual/manual';
 import { DemoTabsDisableComponent } from './disable/disable';
 import { DemoTabsCustomComponent } from './custom-template/custom-template';
 import { DemoTabsSelectEventComponent } from './select-event/select-event';
+import { DemoAccessibilityComponent } from './accessibility/accessibility';
 
 export const DEMO_COMPONENTS = [
   DemoTabsBasicComponent,
   DemoTabsManualComponent,
   DemoTabsDisableComponent,
+  DemoTabsDisableComponent,
   DemoTabsDynamicComponent,
   DemoTabsStylingComponent,
   DemoTabsPillsComponent,
   DemoTabsVerticalPillsComponent,
   DemoTabsJustifiedComponent,
   DemoTabsConfigComponent,
   DemoTabsCustomComponent,
-  DemoTabsSelectEventComponent
+  DemoTabsSelectEventComponent,
+  DemoAccessibilityComponent
 ];

demo/src/app/components/+tabs/tabs-section.list.ts

@@ -9,6 +9,7 @@ import { DemoTabsConfigComponent } from './demos/config/config';
 import { DemoTabsDisableComponent } from './demos/disable/disable';
 import { DemoTabsCustomComponent } from './demos/custom-template/custom-template';
 import { DemoTabsSelectEventComponent } from './demos/select-event/select-event';
+import { DemoAccessibilityComponent } from './demos/accessibility/accessibility';
 
 import { ContentSection } from '../../docs/models/content-section.model';
 import { DemoTopSectionComponent } from '../../docs/demo-section-components/demo-top-section/index';
@@ -112,6 +113,11 @@ export const demoComponentContent: ContentSection[] = [
         component: require('!!raw-loader?lang=typescript!./demos/custom-template/custom-template'),
         html: require('!!raw-loader?lang=markup!./demos/custom-template/custom-template.html'),
         outlet: DemoTabsCustomComponent
+      },
+      {
+        title: 'Accessibility',
+        anchor: 'accessibility',
+        outlet: DemoAccessibilityComponent
       }
     ]
   },