diff --git a/projects/igniteui-angular/src/lib/expansion-panel/README.md b/projects/igniteui-angular/src/lib/expansion-panel/README.md new file mode 100644 index 00000000000..706e9b92490 --- /dev/null +++ b/projects/igniteui-angular/src/lib/expansion-panel/README.md @@ -0,0 +1,101 @@ +# IgxExpansionPanel + + +**IgxExpansionPanel** is a light and highly templateable component that allows you to dynamically display content. + +A walkthrough of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/expansion_panel.html) + +# Usage + +```html + + + + Title + + + Description + + + +

Lengthier and more detailed description. Only visible when the panel is expanded

+ + +``` + +## igx-expansion-panel-header +The header of the `igx-expansion-panel` is **always** visible - this is the part of the component which handles user interaction. + +### igx-expansion-panel-title +The `title` part of the header is **always** visible and will always be placed in the beginning of the header (after the icon, depending on settings) +The title should be used to describe the content of the panel's body. + +### igx-expansion-panel-description +The `description` part of the header is **always** visible and will always be placed in the middle of the header (after the title). +The description can be used to provide a very short and concise explanation, further expanding upon the title, on the content of the panel's body. + +## igx-panel-body +The `igx-expansion-panel-body` contains all of the content in the `igx-expansion-panel` which should not be initially visible. The `body` is **sometimes** visible - only when the expansion panel is **not** `collapsed` + +# API Summary +The following tables summarize the **igx-expansion-panel**, **igx-expansion-panel-header** and **igx-expansion-panel-body** inputs, outputs and methods. + +## IgxExpansionPanelComponent + +### Inputs +The following inputs are available in the **igx-expansion-panel** component: + +| Name | Type | Description | +| :--- | :--- | :--- | +| `animationSettings` | `AnimationSettings` | Specifies the settings for the open and close animations of the panel | +| `id` | `string` | The id of the panel's host component | +| `collapsed` | `boolean` | Whether the component is collapsed (body is hidden) or not | + +### Outputs +The following outputs are available in the **igx-expansion-panel** component: + +| Name | Cancelable | Description | Parameters +| :--- | :--- | :--- | :--- | +| `onCollapsed` | `false` | Emitted when the panel is collapsed | `{ event: Event, panel: IgxExpansionPanelComponent }` | +| `onExpanded` | `false` | Emitted when the panel is expanded | `{ event: Event, panel: IgxExpansionPanelComponent }` | + + +### Methods +The following methods are available in the **igx-expansion-panel** component: + +| Name | Signature | Description | +| :--- | :--- | :--- | +| `collapse` | `(event?: Event ): void` | Collapses the panel | +| `expand` | `(event?: Event ): void` | Expands the panel | +| `toggle` | `(event?: Event ): void` | Toggles the panel (calls `collapse(event)` or `expand(event)` depending on `collapsed`) | + + +## IgxExpansionPanelHeaderComponent +### Inputs +The following inputs are available in the **igx-expansion-panel-header** component: + +| Name | Type | Description | +| :--- | :--- | :--- | +| `id` | `string` | The id of the panel header | +| `lv` | `string` | The `aria-level` attribute of the header | +| `role` | `string` | The `role` attribute of the header | +| `iconPosition` | `string` | The position of the expand/collapse icon of the header | +| `disabled` | `boolean` | Gets/sets whether the panel header is disabled (blocking user interaction) or not | + + +### Outputs +The following outputs are available in the **igx-expansion-panel-header** component: + +| Name | Cancelable | Description | Parameters +| :--- | :--- | :--- | :--- | +| `onInteraction` | `false` | Emitted when a user interacts with the header host | `{ event: Event, panel: IgxExpansionPanelComponent }` | + +## IgxExpansionPanelBodyComponent +### Inputs +The following inputs are available in the **igx-expansion-panel-body** component: + +| Name | Type | Description | +| :--- | :--- | :--- | +| `labelledBy` | `string` | The `aria-labelledby` attribute of the panel body | +| `label` | `string` | The `aria-label` attribute of the panel body | +| `role` | `string` | The `role` attribute of the panel body | diff --git a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-body.component.ts b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-body.component.ts index b9a56e6bfea..6bac6aafed9 100644 --- a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-body.component.ts +++ b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-body.component.ts @@ -13,28 +13,79 @@ export class IgxExpansionPanelBodyComponent implements OnInit { @Inject(IGX_EXPANSION_PANEL_COMPONENT) public panel: IgxExpansionPanelBase, public element: ElementRef, public cdr: ChangeDetectorRef) { } + /** + * @hidden + */ @HostBinding('class.igx-expansion-panel__body') public cssClass = `igx-expansion-panel__body`; - public _title = ''; + /** + * Gets the `aria-label` attribute of the panel body + * Defaults to the panel id with '-region' in the end; + * Get + * ```typescript + * const currentLabel = this.panel.body.label; + * ``` + */ @Input() @HostBinding('attr.aria-label') public get label(): string { return this._label || this.panel.id + '-region'; } + /** + * Sets the `aria-label` attribute of the panel body + * ```typescript + * this.panel.body.label = 'my-custom-label'; + * ``` + * ```html + * + * ``` + */ public set label(val: string) { this._label = val; } + /** + * Gets the `aria-labelledby` attribute of the panel body + * Defaults to the panel header id; + * Get + * ```typescript + * const currentLabel = this.panel.body.labelledBy; + * ``` + */ @Input() @HostBinding('attr.aria-labelledby') public get labelledBy(): string { return this._labelledBy; } + /** + * Sets the `aria-labelledby` attribute of the panel body + * ```typescript + * this.panel.body.labelledBy = 'my-custom-id'; + * ``` + * ```html + * + * ``` + */ public set labelledBy(val: string) { this._labelledBy = val; } + /** + * Gets/sets the `role` attribute of the panel body + * Default is 'region'; + * Get + * ```typescript + * const currentRole = this.panel.body.role; + * ``` + * Set + * ```typescript + * this.panel.body.role = 'content'; + * ``` + * ```html + * + * ``` + */ @Input() @HostBinding('attr.role') public role = 'region'; diff --git a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-header.component.ts b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-header.component.ts index b29dcc76c19..589fb791794 100644 --- a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-header.component.ts +++ b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel-header.component.ts @@ -31,44 +31,137 @@ export enum ICON_POSITION { export class IgxExpansionPanelHeaderComponent { // properties section private _iconTemplate = false; + /** + * Sets/gets the `id` of the expansion panel header. + * ```typescript + * let panelHeaderId = this.panel.header.id; + * ``` + * @memberof IgxExpansionPanelComponent + */ public id = ''; + /** + * @hidden + */ @ContentChild(IgxExpansionPanelIconDirective) public set iconTemplate(val: any) { this._iconTemplate = val; } + /** + * @hidden + */ public get iconTemplate(): any { return this._iconTemplate; } + /** + * Gets/sets the `aria-level` attribute of the header + * Get + * ```typescript + * const currentAriaLevel = this.panel.header.lv; + * ``` + * Set + * ```typescript + * this.panel.header.lv = '5'; + * ``` + * ```html + * + * ``` + */ @HostBinding('attr.aria-level') @Input() public lv = '3'; + /** + * Gets/sets the `role` attribute of the header + * Get + * ```typescript + * const currentRole = this.panel.header.role; + * ``` + * Set + * ```typescript + * this.panel.header.role = '5'; + * ``` + * ```html + * + * ``` + */ @HostBinding('attr.role') @Input() public role = 'heading'; + /** + * @hidden + */ public get controls (): string { return this.panel.id; } + /** + * Gets/sets the position of the expansion-panel-header expand/collapse icon + * Accepts `left`, `right` or `none` + * ```typescript + * const currentIconPosition = this.panel.header.iconPosition; + * ``` + * Set + * ```typescript + * this.panel.header.iconPosition = 'left'; + * ``` + * ```html + * + * ``` + */ @Input() public iconPosition: ICON_POSITION = ICON_POSITION.LEFT; + /** + * Emitted whenever a user interacts with the header host + * ```typescript + * handleInteraction(event: IExpansionPanelEventArgs) { + * ... + * } + * ``` + * ```html + * + * ... + * + * ``` + */ @Output() public onInteraction = new EventEmitter(); + /** + * @hidden + */ @HostBinding('class.igx-expansion-panel__header') public cssClass = 'igx-expansion-panel__header'; - + /** + * @hidden + */ @HostBinding('class.igx-expansion-panel__header--expanded') public get isExpanded () { return !this.panel.collapsed; } + /** + * Gets/sets the whether the header is disabled + * When disabled, the header will not handle user events and will stop their propagation + * + * ```typescript + * const isDisabled = this.panel.header.disabled; + * ``` + * Set + * ```typescript + * this.panel.header.disabled = true; + * ``` + * ```html + * + * ... + * + * ``` + */ @Input() @HostBinding('class.igx-expansion-panel--disabled') public disabled = false; @@ -78,6 +171,9 @@ export class IgxExpansionPanelHeaderComponent { this.id = `${this.panel.id}-header`; } + /** + * @hidden + */ @HostListener('keydown.Enter', ['$event']) @HostListener('keydown.Space', ['$event']) @HostListener('keydown.Spacebar', ['$event']) @@ -92,6 +188,9 @@ export class IgxExpansionPanelHeaderComponent { evt.preventDefault(); } + /** + * @hidden + */ public get iconPositionClass(): string { switch (this.iconPosition) { case (ICON_POSITION.LEFT): diff --git a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel.component.ts b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel.component.ts index e079336a25d..452a0b40a91 100644 --- a/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel.component.ts +++ b/projects/igniteui-angular/src/lib/expansion-panel/expansion-panel.component.ts @@ -9,11 +9,11 @@ import { ContentChild, forwardRef, } from '@angular/core'; -import { AnimationBuilder, AnimationReferenceMetadata, useAnimation } from '@angular/animations'; +import { AnimationBuilder, AnimationReferenceMetadata, useAnimation, AnimationAnimateRefMetadata } from '@angular/animations'; import { growVerOut, growVerIn } from '../animations/main'; import { IgxExpansionPanelBodyComponent } from './expansion-panel-body.component'; import { IgxExpansionPanelHeaderComponent } from './expansion-panel-header.component'; -import { IGX_EXPANSION_PANEL_COMPONENT, IgxExpansionPanelBase } from './expansion-panel.common'; +import { IGX_EXPANSION_PANEL_COMPONENT, IgxExpansionPanelBase, IExpansionPanelEventArgs } from './expansion-panel.common'; let NEXT_ID = 0; @@ -24,6 +24,37 @@ let NEXT_ID = 0; }) export class IgxExpansionPanelComponent implements IgxExpansionPanelBase { + /** + * Sets/gets the animation settings of the expansion panel component + * Open and Close animation should be passed + * + * Get + * ```typescript + * const currentAnimations = this.panel.animationSettings; + * ``` + * Set + * ```typescript + * import { slideInLeft, slideOutRight } from 'igniteui-angular'; + * ... + * this.panel.animationsSettings = { + * openAnimation: slideInLeft, + * closeAnimation: slideOutRight + * }; + * ``` + * or via template + * ```typescript + * import { slideInLeft, slideOutRight } from 'igniteui-angular'; + * ... + * myCustomAnimationObject = { + * openAnimation: slideInLeft, + * closeAnimation: slideOutRight + * }; + * ```html + * + * ... + * + * ``` + */ @Input() public animationSettings: { openAnimation: AnimationReferenceMetadata, closeAnimation: AnimationReferenceMetadata } = { openAnimation: growVerIn, @@ -45,26 +76,77 @@ export class IgxExpansionPanelComponent implements IgxExpansionPanelBase { @Input() public id = `igx-expansion-panel-${NEXT_ID++}`; + /** + * @hidden + */ @HostBinding('class.igx-expansion-panel') public cssClass = 'igx-expansion-panel'; + /** + * Gets/sets whether the component is collapsed (its content is hidden) + * Get + * ```typescript + * const myPanelState: boolean = this.panel.collapsed; + * ``` + * Set + * ```html + * this.panel.collapsed = true; + * ``` + */ @Input() public collapsed = true; + /** + * Emitted when the expansion panel finishes collapsing + * ```typescript + * handleCollapsed(event: { + * panel: IgxExpansionPanelComponent, + * event: Event + * }) + * ``` + * ```html + * + * ... + * + * ``` + */ @Output() - public onCollapsed = new EventEmitter(); + public onCollapsed = new EventEmitter(); + /** + * Emitted when the expansion panel finishes expanding + * ```typescript + * handleExpanded(event: { + * panel: IgxExpansionPanelComponent, + * event: Event + * }) + * ``` + * ```html + * + * ... + * + * ``` + */ @Output() - public onExpanded = new EventEmitter(); + public onExpanded = new EventEmitter(); + /** + * @hidden + */ public get headerId() { return this.header ? `${this.id}-header` : ''; } constructor(private cdr: ChangeDetectorRef, private builder: AnimationBuilder) { } + /** + * @hidden + */ @ContentChild(forwardRef(() => IgxExpansionPanelBodyComponent), { read: forwardRef(() => IgxExpansionPanelBodyComponent) }) public body: IgxExpansionPanelBodyComponent; + /** + * @hidden + */ @ContentChild(forwardRef(() => IgxExpansionPanelHeaderComponent), { read: forwardRef(() => IgxExpansionPanelHeaderComponent) }) public header: IgxExpansionPanelHeaderComponent; @@ -100,6 +182,16 @@ export class IgxExpansionPanelComponent implements IgxExpansionPanelBase { closeAnimationPlayer.play(); } + /** + * Collapses the panel + * + * ```html + * + * ... + * + * + * ``` + */ collapse(evt?: Event) { this.playCloseAnimation( () => { @@ -109,6 +201,16 @@ export class IgxExpansionPanelComponent implements IgxExpansionPanelBase { ); } + /** + * Expands the panel + * + * ```html + * + * ... + * + * + * ``` + */ expand(evt?: Event) { this.collapsed = false; this.cdr.detectChanges(); @@ -119,6 +221,16 @@ export class IgxExpansionPanelComponent implements IgxExpansionPanelBase { ); } + /** + * Toggles the panel + * + * ```html + * + * ... + * + * + * ``` + */ toggle(evt?: Event) { if (this.collapsed) { this.expand(evt);