docs(cdk/accordion): add overview

Adds an overview doc for the `cdk/accordion` package, including a sample implementation of an accordion using the CDK.

Fixes #14298.

Author: crisbeto

src/cdk/accordion/BUILD.bazel

@@ -42,7 +42,7 @@ ng_web_test_suite(
 
 markdown_to_html(
     name = "overview",
-    srcs = [],
+    srcs = [":accordion.md"],
 )
 
 filegroup(

src/cdk/accordion/accordion.md

@@ -0,0 +1,14 @@
+CDK accordion provides a foundation upon which you can build your own custom accordion component.
+It comes with all of the necessary logic for an accordion, but it doesn't include any styles so that
+you can customize it based on your application's needs. An accordion is a component with one or more
+expandable sections where opening one section closes the previously-open section. You can also opt
+into having multiple sections open at the same time.
+
+<!-- example(cdk-accordion-overview) -->
+
+### Accessibility
+The CDK accordion doesn't come with any accessibility treatment, because it doesn't have control
+over its markup. We recommend to set the accordion trigger element as a `role="button"` while
+the body container as a `role="region"`. Furthermore, the trigger should have `aria-controls`
+pointing to the body and `aria-expanded` based on the expanded state, while the body should have
+an `aria-labelledby` that points to the header. See the example above for a sample implementation.

src/components-examples/BUILD.bazel

@@ -54,6 +54,7 @@ ALL_EXAMPLES = [
     "//src/components-examples/cdk/stepper",
     "//src/components-examples/cdk/scrolling",
     "//src/components-examples/cdk/portal",
+    "//src/components-examples/cdk/accordion",
     "//src/components-examples/cdk/platform",
     "//src/components-examples/cdk/drag-drop",
     "//src/components-examples/cdk/clipboard",

src/components-examples/cdk/accordion/BUILD.bazel

@@ -0,0 +1,25 @@
+load("//tools:defaults.bzl", "ng_module")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_module(
+    name = "accordion",
+    srcs = glob(["**/*.ts"]),
+    assets = glob([
+        "**/*.html",
+        "**/*.css",
+    ]),
+    module_name = "@angular/components-examples/cdk/accordion",
+    deps = [
+        "//src/cdk/accordion",
+    ],
+)
+
+filegroup(
+    name = "source-files",
+    srcs = glob([
+        "**/*.html",
+        "**/*.css",
+        "**/*.ts",
+    ]),
+)

src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.css

@@ -0,0 +1,44 @@
+.example-accordion {
+  display: block;
+  max-width: 500px;
+}
+
+.example-accordion-item {
+  display: block;
+  border: solid 1px #ccc;
+}
+
+.example-accordion-item + .example-accordion-item {
+  border-top: none;
+}
+
+.example-accordion-item-header {
+  display: flex;
+  align-content: center;
+  justify-content: space-between;
+}
+
+.example-accordion-item-description {
+  font-size: 0.85em;
+  color: #999;
+}
+
+.example-accordion-item-header,
+.example-accordion-item-body {
+  padding: 16px;
+}
+
+.example-accordion-item-header:hover {
+  cursor: pointer;
+  background-color: #eee;
+}
+
+.example-accordion-item:first-child {
+  border-top-left-radius: 4px;
+  border-top-right-radius: 4px;
+}
+
+.example-accordion-item:last-child {
+  border-bottom-left-radius: 4px;
+  border-bottom-right-radius: 4px;
+}

src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.html

@@ -0,0 +1,29 @@
+<cdk-accordion class="example-accordion">
+  <cdk-accordion-item
+    *ngFor="let item of items; let index = index;"
+    #accordionItem="cdkAccordionItem"
+    class="example-accordion-item"
+    role="button"
+    tabindex="0"
+    [attr.id]="'accordion-header-' + index"
+    [attr.aria-expanded]="accordionItem.expanded"
+    [attr.aria-controls]="'accordion-body-' + index">
+    <div class="example-accordion-item-header" (click)="accordionItem.toggle()">
+      {{ item }}
+      <span class="example-accordion-item-description">
+        Click to {{ accordionItem.expanded ? 'close' : 'open' }}
+      </span>
+    </div>
+    <div
+      class="example-accordion-item-body"
+      role="region"
+      [style.display]="accordionItem.expanded ? '' : 'none'"
+      [attr.id]="'accordion-body-' + index"
+      [attr.aria-labelledby]="'accordion-header-' + index">
+      Lorem ipsum dolor, sit amet consectetur adipisicing elit. Perferendis
+      excepturi incidunt ipsum deleniti labore, tempore non nam doloribus blanditiis
+      veritatis illo autem iure aliquid ullam rem tenetur deserunt velit culpa?
+    </div>
+  </cdk-accordion-item>
+</cdk-accordion>
+

src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.ts

@@ -0,0 +1,14 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Accordion overview
+ */
+@Component({
+  selector: 'cdk-accordion-overview-example',
+  templateUrl: 'cdk-accordion-overview-example.html',
+  styleUrls: ['cdk-accordion-overview-example.css'],
+})
+export class CdkAccordionOverviewExample {
+  items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];
+  expandedIndex = 0;
+}

src/components-examples/cdk/accordion/index.ts

@@ -0,0 +1,24 @@
+import {CommonModule} from '@angular/common';
+import {CdkAccordionModule} from '@angular/cdk/accordion';
+import {NgModule} from '@angular/core';
+import {
+  CdkAccordionOverviewExample,
+} from './cdk-accordion-overview/cdk-accordion-overview-example';
+
+export {CdkAccordionOverviewExample};
+
+const EXAMPLES = [
+  CdkAccordionOverviewExample,
+];
+
+@NgModule({
+  imports: [
+    CommonModule,
+    CdkAccordionModule
+  ],
+  declarations: EXAMPLES,
+  exports: EXAMPLES,
+  entryComponents: EXAMPLES,
+})
+export class CdkAccordionExamplesModule {
+}