Merge pull request #3245 from IgniteUI/vslavov/expansion-panel-docs-6…

….2.x Docs - Expansion Panel - Add comments and README - 6.2.x
IgniteUI · Dec 4, 2018 · 5e7baf3 · 5e7baf3
2 parents 94df8b8 + 0ce3fd4
commit 5e7baf3
Show file tree

Hide file tree

Showing 4 changed files with 369 additions and 6 deletions.
diff --git a/projects/igniteui-angular/src/lib/expansion-panel/README.md 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
+<igx-expansion-panel>
+    <igx-expansion-panel-header>
+        <igx-expansion-panel-title>
+            Title
+        </igx-expansion-panel-title>
+        <igx-expansion-panel-description>
+            Description
+        </igx-expansion-panel-description>
+    </igx-expansion-panel-header>
+    <igx-expansion-panel-body>
+        <p>Lengthier and more detailed description. Only visible when the panel is expanded</p>
+    </igx-expansion-panel-body>
+</igx-expansion-panel>
+```
+
+## 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
@@ -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
+     *  <igx-expansion-panel-body [label]="'my-custom-label'"></igx-expansion-panel-body>
+     * ```
+     */
     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
+     *  <igx-expansion-panel-body [labelledBy]="'my-custom-id'"></igx-expansion-panel-body>
+     * ```
+     */
     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
+     *  <igx-expansion-panel-body [role]="'custom'"></igx-expansion-panel-body>
+     * ```
+     */
     @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
@@ -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 = <boolean>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
+     *  <igx-expansion-panel-header [lv]="myCustomLevel"></igx-expansion-panel-header>
+     * ```
+     */
     @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
+     *  <igx-expansion-panel-header [role]="'custom'"></igx-expansion-panel-header>
+     * ```
+     */
     @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
+     *  <igx-expansion-panel-header [iconPosition]="'right'"></igx-expansion-panel-header>
+     * ```
+     */
     @Input()
     public iconPosition: ICON_POSITION = ICON_POSITION.LEFT;
 
+    /**
+     * Emitted whenever a user interacts with the header host
+     * ```typescript
+     *  handleInteraction(event: IExpansionPanelEventArgs) {
+     *  ...
+     * }
+     * ```
+     * ```html
+     *  <igx-expansion-panel-header (onInteraction)="handleInteraction($event)">
+     *      ...
+     *  </igx-expansion-panel-header>
+     * ```
+     */
     @Output()
     public onInteraction = new EventEmitter<IExpansionPanelEventArgs>();
 
+    /**
+     * @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
+     *  <igx-expansion-panel-header [disabled]="true">
+     *     ...
+     *  </igx-expansion-panel-header>
+     * ```
+     */
     @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):