From ab20ffd9964ffadc5adec875380568414ba444b4 Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Fri, 8 Sep 2017 14:28:11 -0700 Subject: [PATCH] docs(list): add example and missing JsDoc for selection-list (#6899) --- src/lib/list/list.md | 9 ++++++++ src/lib/list/list.ts | 3 +++ src/lib/list/selection-list.ts | 21 ++++++++++++------- src/material-examples/example-module.ts | 8 +++++++ .../list-selection/list-selection-example.css | 1 + .../list-selection-example.html | 9 ++++++++ .../list-selection/list-selection-example.ts | 13 ++++++++++++ 7 files changed, 56 insertions(+), 8 deletions(-) create mode 100644 src/material-examples/list-selection/list-selection-example.css create mode 100644 src/material-examples/list-selection/list-selection-example.html create mode 100644 src/material-examples/list-selection/list-selection-example.ts diff --git a/src/lib/list/list.md b/src/lib/list/list.md index a46f75f071d..f9ad2ae169d 100644 --- a/src/lib/list/list.md +++ b/src/lib/list/list.md @@ -42,6 +42,15 @@ element in an ``. ``` +### Selection lists +A selection list provides an interface for selecting values, where each list item is an option. + + + +The options within a selection-list should not contain further interactive controls, such +as buttons and anchors. + + ### Multi-line lists For lists that require multiple lines per item, annotate each line with an `mdLine` attribute. Whichever heading tag is appropriate for your DOM hierarchy should be used (not necessarily `

` diff --git a/src/lib/list/list.ts b/src/lib/list/list.ts index 7762facbc6a..3b9205e7421 100644 --- a/src/lib/list/list.ts +++ b/src/lib/list/list.ts @@ -33,6 +33,7 @@ export class MdListItemBase {} export const _MdListItemMixinBase = mixinDisableRipple(MdListItemBase); +/** Divider between items within a list. */ @Directive({ selector: 'md-divider, mat-divider', host: { @@ -42,6 +43,7 @@ export const _MdListItemMixinBase = mixinDisableRipple(MdListItemBase); }) export class MdListDivider {} +/** A Material Design list component. */ @Component({ moduleId: module.id, selector: 'md-list, mat-list, md-nav-list, mat-nav-list', @@ -114,6 +116,7 @@ export class MdListIconCssMatStyler {} }) export class MdListSubheaderCssMatStyler {} +/** An item within a Material Design list. */ @Component({ moduleId: module.id, selector: 'md-list-item, mat-list-item, a[md-list-item], a[mat-list-item]', diff --git a/src/lib/list/selection-list.ts b/src/lib/list/selection-list.ts index 753a6acbf37..a239b0e81d9 100644 --- a/src/lib/list/selection-list.ts +++ b/src/lib/list/selection-list.ts @@ -36,13 +36,15 @@ import {CanDisableRipple, mixinDisableRipple} from '../core/common-behaviors/dis import {MATERIAL_COMPATIBILITY_MODE} from '../core/compatibility/compatibility'; +/** @docs-private */ export class MdSelectionListBase {} export const _MdSelectionListMixinBase = mixinDisableRipple(mixinDisabled(MdSelectionListBase)); +/** @docs-private */ export class MdListOptionBase {} export const _MdListOptionMixinBase = mixinDisableRipple(MdListOptionBase); - +/** Event emitted by a selection-list whenever the state of an option is changed. */ export interface MdSelectionListOptionEvent { option: MdListOption; } @@ -95,10 +97,12 @@ export class MdListOption extends _MdListOptionMixinBase get disabled() { return (this.selectionList && this.selectionList.disabled) || this._disabled; } set disabled(value: any) { this._disabled = coerceBooleanProperty(value); } + /** Value of the option */ @Input() get value() { return this._value; } set value( val: any) { this._value = coerceBooleanProperty(val); } + /** Whether the option is selected. */ @Input() get selected() { return this._selected; } set selected( val: boolean) { this._selected = coerceBooleanProperty(val); } @@ -135,6 +139,7 @@ export class MdListOption extends _MdListOptionMixinBase this.destroyed.emit({option: this}); } + /** Toggles the selection state of the option. */ toggle(): void { this.selected = !this.selected; this.selectionList.selectedOptions.toggle(this); @@ -174,6 +179,9 @@ export class MdListOption extends _MdListOptionMixinBase } +/** + * Material Design list component where each item is a selectable option. Behaves as a listbox. + */ @Component({ moduleId: module.id, selector: 'md-selection-list, mat-selection-list', @@ -208,7 +216,7 @@ export class MdSelectionList extends _MdSelectionListMixinBase /** The option components contained within this selection-list. */ @ContentChildren(MdListOption) options: QueryList; - /** options which are selected. */ + /** The currently selected options. */ selectedOptions: SelectionModel = new SelectionModel(true); constructor(private _element: ElementRef) { @@ -231,13 +239,12 @@ export class MdSelectionList extends _MdSelectionListMixinBase this._optionFocusSubscription.unsubscribe(); } + /** Focus the selection-list. */ focus() { this._element.nativeElement.focus(); } - /** - * Map all the options' destroy event subscriptions and merge them into one stream. - */ + /** Map all the options' destroy event subscriptions and merge them into one stream. */ private _onDestroySubscription(): Subscription { return RxChain.from(this.options.changes) .call(startWith, this.options) @@ -257,9 +264,7 @@ export class MdSelectionList extends _MdSelectionListMixinBase }); } - /** - * Map all the options' onFocus event subscriptions and merge them into one stream. - */ + /** Map all the options' onFocus event subscriptions and merge them into one stream. */ private _onFocusSubscription(): Subscription { return RxChain.from(this.options.changes) .call(startWith, this.options) diff --git a/src/material-examples/example-module.ts b/src/material-examples/example-module.ts index 1a67aed7c9f..4b3396e8c99 100644 --- a/src/material-examples/example-module.ts +++ b/src/material-examples/example-module.ts @@ -52,6 +52,7 @@ import {InputOverviewExample} from './input-overview/input-overview-example'; import {InputPrefixSuffixExample} from './input-prefix-suffix/input-prefix-suffix-example'; import {ListOverviewExample} from './list-overview/list-overview-example'; import {ListSectionsExample} from './list-sections/list-sections-example'; +import {ListSelectionExample} from './list-selection/list-selection-example'; import {MenuIconsExample} from './menu-icons/menu-icons-example'; import {MenuOverviewExample} from './menu-overview/menu-overview-example'; import {PaginatorConfigurableExample} from './paginator-configurable/paginator-configurable-example'; @@ -323,6 +324,12 @@ export const EXAMPLE_COMPONENTS = { additionalFiles: null, selectorName: null }, + 'list-selection': { + title: 'List with selection', + component: ListSelectionExample, + additionalFiles: null, + selectorName: null + }, 'menu-icons': { title: 'Menu with icons', component: MenuIconsExample, @@ -580,6 +587,7 @@ export const EXAMPLE_LIST = [ InputPrefixSuffixExample, ListOverviewExample, ListSectionsExample, + ListSelectionExample, MenuIconsExample, MenuOverviewExample, PaginatorConfigurableExample, diff --git a/src/material-examples/list-selection/list-selection-example.css b/src/material-examples/list-selection/list-selection-example.css new file mode 100644 index 00000000000..7949471cec9 --- /dev/null +++ b/src/material-examples/list-selection/list-selection-example.css @@ -0,0 +1 @@ +/** No styles for this example. */ diff --git a/src/material-examples/list-selection/list-selection-example.html b/src/material-examples/list-selection/list-selection-example.html new file mode 100644 index 00000000000..cd1d9f07353 --- /dev/null +++ b/src/material-examples/list-selection/list-selection-example.html @@ -0,0 +1,9 @@ + + + {{shoe}} + + + +

+ Options selected: {{shoes.selectedOptions.selected.length}} +

diff --git a/src/material-examples/list-selection/list-selection-example.ts b/src/material-examples/list-selection/list-selection-example.ts new file mode 100644 index 00000000000..644d3d8a570 --- /dev/null +++ b/src/material-examples/list-selection/list-selection-example.ts @@ -0,0 +1,13 @@ +import {Component} from '@angular/core'; + +/** + * @title List with selection + */ +@Component({ + selector: 'list-selection-example', + styleUrls: ['list-selection-example.css'], + templateUrl: 'list-selection-example.html', +}) +export class ListSelectionExample { + typesOfShoes = ['Boots', 'Clogs', 'Loafers', 'Moccasins', 'Sneakers']; +}