From 6ab2c8c7b6b28c0f6de411aba7d41bf74ed46515 Mon Sep 17 00:00:00 2001 From: crisbeto Date: Tue, 6 Feb 2018 20:23:48 +0100 Subject: [PATCH] docs: add overview docs for bottom sheet Adds the initial readme and overview example for the bottom sheet component. --- .../bottom-sheet/bottom-sheet-demo.ts | 1 - src/lib/bottom-sheet/bottom-sheet.md | 101 ++++++++++++++++++ .../bottom-sheet-overview-example-sheet.html | 21 ++++ .../bottom-sheet-overview-example.css | 1 + .../bottom-sheet-overview-example.html | 3 + .../bottom-sheet-overview-example.ts | 31 ++++++ 6 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 src/lib/bottom-sheet/bottom-sheet.md create mode 100644 src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example-sheet.html create mode 100644 src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.css create mode 100644 src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.html create mode 100644 src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.ts diff --git a/src/demo-app/bottom-sheet/bottom-sheet-demo.ts b/src/demo-app/bottom-sheet/bottom-sheet-demo.ts index c588c41522c9..e3bd8c80f4e3 100644 --- a/src/demo-app/bottom-sheet/bottom-sheet-demo.ts +++ b/src/demo-app/bottom-sheet/bottom-sheet-demo.ts @@ -49,7 +49,6 @@ export class BottomSheetDemo { template: ` - folder Action {{ link }} Description diff --git a/src/lib/bottom-sheet/bottom-sheet.md b/src/lib/bottom-sheet/bottom-sheet.md new file mode 100644 index 000000000000..87625c1255da --- /dev/null +++ b/src/lib/bottom-sheet/bottom-sheet.md @@ -0,0 +1,101 @@ +The `MatBottomSheet` service can be used to open Material Design panels to the bottom of the screen. +These panels are intended primarily as an interaction on mobile devices where they can be used as an +alternative to dialogs and menus. + + + +You can open a bottom sheet by calling the `open` method with a component to be loaded and an +optional config object. The `open` method will return an instance of `MatBottomSheetRef`: + +```ts +const bottomSheetRef = bottomSheet.open(SocialShareComponent, { + ariaLabel: 'Share on social media' +}); +``` + +The `MatBottomSheetRef` is a reference to the currently-opened bottom sheet and can be used to close +it or to subscribe to events. Note that only one bottom sheet can be open at a time. Any component +contained inside of a bottom sheet can inject the `MatBottomSheetRef` as well. + +```ts +bottomSheetRef.afterDismissed().subscribe(() => { + console.log('Bottom sheet has been dismissed.'); +}); + +bottomSheetRef.dismiss(); +``` + +### Sharing data with the bottom sheet component. +If you want to pass in some data to the bottom sheet, you can do so using the `data` property: + +```ts +const bottomSheetRef = bottomSheet.open(HobbitSheet, { + data: { names: ['Frodo', 'Bilbo'] }, +}); +``` + +Afterwards you can access the injected data using the `MAT_BOTTOM_SHEET_DATA` injection token: + +```ts +import {Component, Inject} from '@angular/core'; +import {MAT_BOTTOM_SHEET_DATA} from '@angular/material'; + +@Component({ + selector: 'hobbit-sheet', + template: 'passed in {{ data.names }}', +}) +export class HobbitSheet { + constructor(@Inject(MAT_BOTTOM_SHEET_DATA) public data: any) { } +} +``` + +### Configuring bottom sheet content via `entryComponents` + +Similarly to `MatDialog`, `MatBottomSheet` instantiates components at run-time. In order for it to +work, the Angular compiler needs extra information to create the necessary `ComponentFactory` for +your bottom sheet content component. + +Any components that are include inside of a bottom sheet have to be added to the `entryComponents` +inside your `NgModule`. + + +```ts +@NgModule({ + imports: [ + // ... + MatBottomSheetModule + ], + + declarations: [ + AppComponent, + ExampleBottomSheetComponent + ], + + entryComponents: [ + ExampleBottomSheetComponent + ], + + providers: [], + bootstrap: [AppComponent] +}) +export class AppModule {} +``` + +### Accessibility +By default, the bottom sheet has `role="dialog"` on the root element and can be labelled using the +`ariaLabel` property on the `MatBottomSheetConfig`. + +When a bottom sheet is opened, it will move focus to the first focusable element that it can find. +In order to prevent users from tabbing into elements in the background, the Material bottom sheet +uses a [focus trap](https://material.angular.io/cdk/a11y/overview#focustrap) to contain focus +within itself. Once a bottom sheet is closed, it will return focus to the element that was focused +before it was opened. + +#### Focus management +By default, the first tabbable element within the bottom sheet will receive focus upon open. +This can be configured by setting the `cdkFocusInitial` attribute on another focusable element. + +#### Keyboard interaction +By default pressing the escape key will close the bottom sheet. While this behavior can +be turned off via the `disableClose` option, users should generally avoid doing so +as it breaks the expected interaction pattern for screen-reader users. diff --git a/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example-sheet.html b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example-sheet.html new file mode 100644 index 000000000000..a4ecc8be6b8a --- /dev/null +++ b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example-sheet.html @@ -0,0 +1,21 @@ + + + Google Keep + Add to a note + + + + Google Docs + Embed in a document + + + + Google Plus + Share with your friends + + + + Google Hangouts + Show to your coworkers + + diff --git a/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.css b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.css new file mode 100644 index 000000000000..7432308753e6 --- /dev/null +++ b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.css @@ -0,0 +1 @@ +/** No CSS for this example */ diff --git a/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.html b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.html new file mode 100644 index 000000000000..f4e1ad632d9b --- /dev/null +++ b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.html @@ -0,0 +1,3 @@ +

You have receive a file called "cat-picture.jpeg".

+ + diff --git a/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.ts b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.ts new file mode 100644 index 000000000000..4336540e8ffa --- /dev/null +++ b/src/material-examples/bottom-sheet-overview/bottom-sheet-overview-example.ts @@ -0,0 +1,31 @@ +import {Component} from '@angular/core'; +import {MatBottomSheet, MatBottomSheetRef} from '@angular/material'; + +/** + * @title Bottom Sheet Overview + */ +@Component({ + selector: 'bottom-sheet-overview-example', + templateUrl: 'bottom-sheet-overview-example.html', + styleUrls: ['bottom-sheet-overview-example.css'], +}) +export class BottomSheetOverviewExample { + constructor(private bottomSheet: MatBottomSheet) {} + + openBottomSheet(): void { + this.bottomSheet.open(BottomSheetOverviewExampleSheet); + } +} + +@Component({ + selector: 'bottom-sheet-overview-example-sheet', + templateUrl: 'bottom-sheet-overview-example-sheet.html', +}) +export class BottomSheetOverviewExampleSheet { + constructor(private bottomSheetRef: MatBottomSheetRef) {} + + onNoClick(event: MouseEvent): void { + this.bottomSheetRef.dismiss(); + event.preventDefault(); + } +}