From 77cbf2dd6eee662118d601107b21935f299a188a Mon Sep 17 00:00:00 2001 From: Kristiyan Kostadinov Date: Wed, 2 Jun 2021 20:01:29 +0200 Subject: [PATCH] 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. --- src/cdk/accordion/BUILD.bazel | 2 +- src/cdk/accordion/accordion.md | 13 ++++++ src/components-examples/BUILD.bazel | 1 + .../cdk/accordion/BUILD.bazel | 25 +++++++++++ .../cdk-accordion-overview-example.css | 44 +++++++++++++++++++ .../cdk-accordion-overview-example.html | 29 ++++++++++++ .../cdk-accordion-overview-example.ts | 14 ++++++ .../cdk/accordion/index.ts | 24 ++++++++++ 8 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 src/cdk/accordion/accordion.md create mode 100644 src/components-examples/cdk/accordion/BUILD.bazel create mode 100644 src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.css create mode 100644 src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.html create mode 100644 src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.ts create mode 100644 src/components-examples/cdk/accordion/index.ts diff --git a/src/cdk/accordion/BUILD.bazel b/src/cdk/accordion/BUILD.bazel index 0fa36941b9ef..4ef3ba8c5aa3 100644 --- a/src/cdk/accordion/BUILD.bazel +++ b/src/cdk/accordion/BUILD.bazel @@ -42,7 +42,7 @@ ng_web_test_suite( markdown_to_html( name = "overview", - srcs = [], + srcs = [":accordion.md"], ) filegroup( diff --git a/src/cdk/accordion/accordion.md b/src/cdk/accordion/accordion.md new file mode 100644 index 000000000000..8eb2dcdd17a5 --- /dev/null +++ b/src/cdk/accordion/accordion.md @@ -0,0 +1,13 @@ +An accordion is a component with one or more expandable sections. CDK accordion provides a +foundation upon which you can build your own custom accordion component. CDK accordion provides +logic for the accordion interaction pattern without any styles. You can customize the accordion's +appearance based on your application's needs. + + + +### 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. diff --git a/src/components-examples/BUILD.bazel b/src/components-examples/BUILD.bazel index 9ad3bb8ad421..578c86a860ae 100644 --- a/src/components-examples/BUILD.bazel +++ b/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", diff --git a/src/components-examples/cdk/accordion/BUILD.bazel b/src/components-examples/cdk/accordion/BUILD.bazel new file mode 100644 index 000000000000..eb8390d70422 --- /dev/null +++ b/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", + ]), +) diff --git a/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.css b/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.css new file mode 100644 index 000000000000..b6d1add83573 --- /dev/null +++ b/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; +} diff --git a/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.html b/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.html new file mode 100644 index 000000000000..0a02078fd51a --- /dev/null +++ b/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.html @@ -0,0 +1,29 @@ + + +
+ {{ item }} + + Click to {{ accordionItem.expanded ? 'close' : 'open' }} + +
+
+ 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? +
+ + + diff --git a/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.ts b/src/components-examples/cdk/accordion/cdk-accordion-overview/cdk-accordion-overview-example.ts new file mode 100644 index 000000000000..c3d75fcbc160 --- /dev/null +++ b/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; +} diff --git a/src/components-examples/cdk/accordion/index.ts b/src/components-examples/cdk/accordion/index.ts new file mode 100644 index 000000000000..7b51bbf79215 --- /dev/null +++ b/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 { +}