@material/web 1.0.0-pre.1 → 1.0.0-pre.3

package/list/lib/listitem/list-item.d.ts

@@ -5,69 +5,125 @@
  */
 import '../../../ripple/ripple.js';
 import '../../../focus/focus-ring.js';
-import { ActionElement, BeginPressConfig, EndPressConfig } from '../../../actionelement/action-element.js';
+import { LitElement, nothing, PropertyValues, TemplateResult } from 'lit';
+import { ClassInfo } from 'lit/directives/class-map.js';
 import { MdRipple } from '../../../ripple/ripple.js';
 import { ARIARole } from '../../../types/aria.js';
-import { TemplateResult } from 'lit';
-import { ClassInfo } from 'lit/directives/class-map.js';
-/** @soyCompatible */
-export declare class ListItem extends ActionElement {
+interface ListItemSelf {
+    active: boolean;
+    disabled: boolean;
+}
+/**
+ * The interface of an item that is compatible with md-list. An item that is
+ * selectable and disablable.
+ */
+export type ListItem = ListItemSelf & HTMLElement;
+export declare class ListItemEl extends LitElement implements ListItem {
     role: ARIARole;
     ariaSelected: 'true' | 'false';
     ariaChecked: 'true' | 'false';
-    itemId: string;
+    /**
+     * The primary, headline text of the list item.
+     */
+    headline: string;
+    /**
+     * The one-line supporting text below the headline.
+     */
     supportingText: string;
+    /**
+     * The multi-line supporting text below the headline. __NOTE:__ if set to a
+     * truthy value, overrides the visibility and behavior of `supportingText`.
+     */
     multiLineSupportingText: string;
+    /**
+     * The supporting text placed at the end of the item. Overriden by elements
+     * slotted into the `end` slot.
+     */
     trailingSupportingText: string;
+    /**
+     * Disables the item and makes it non-selectable and non-interactive.
+     */
     disabled: boolean;
+    /**
+     * The tabindex of the underlying item.
+     *
+     * __NOTE:__ this is overriden by the keyboard behavior of `md-list` and by
+     * setting `selected`.
+     */
     itemTabIndex: number;
-    headline: string;
-    ripple: MdRipple;
-    listItemRoot: HTMLElement;
-    showFocusRing: boolean;
-    /** @soyTemplate */
+    /**
+     * Whether or not the element is in the selected visual state. When active,
+     * tabindex is set to 0, and in some list item variants (like md-list-item),
+     * focuses the underlying item.
+     */
+    active: boolean;
+    /**
+     * READONLY. Sets the `md-list-item` attribute on the element.
+     */
+    isListItem: boolean;
+    protected ripple: Promise<MdRipple | null>;
+    protected listItemRoot: HTMLElement;
+    protected showFocusRing: boolean;
+    protected showRipple: boolean;
+    /**
+     * Only meant to be overriden by subclassing and not by the user. This is
+     * so that we have control over focus on specific variants such as disabling
+     * focus on <md-autocomplete-item> but enabling it for <md-menu-item>.
+     */
+    protected focusOnSelection: boolean;
+    protected getRipple: () => Promise<MdRipple>;
+    private isFirstUpdate;
+    willUpdate(changed: PropertyValues<this>): void;
     render(): TemplateResult;
-    /** @soyTemplate */
-    protected renderRipple(): TemplateResult;
-    /** @soyTemplate */
+    /**
+     * Renders the root list item.
+     *
+     * @param content {unkown} the child content of the list item.
+     */
+    protected renderListItem(content: unknown): TemplateResult<1>;
+    /**
+     * Handles rendering of the ripple element.
+     */
+    protected renderRipple(): TemplateResult | typeof nothing;
+    /**
+     * Handles rendering of the focus ring.
+     */
     protected renderFocusRing(): TemplateResult;
-    /** @soyTemplate */
-    protected getAriaRole(): ARIARole;
-    /** @soyTemplate */
+    /**
+     * Classes applied to the list item root.
+     */
     protected getRenderClasses(): ClassInfo;
-    /** @soyTemplate */
+    /**
+     * The content rendered at the start of the list item.
+     */
     protected renderStart(): TemplateResult;
-    /** @soyTemplate */
+    /**
+     * Handles rendering the headline and supporting text.
+     */
     protected renderBody(): TemplateResult;
-    /** @soyTemplate */
+    /**
+     * Renders the one-line supporting text.
+     */
     protected renderSupportingText(): TemplateResult;
-    /** @soyTemplate */
-    protected renderMultiLineSupportingText(): TemplateResult;
-    /** @soyTemplate */
-    protected renderEnd(): TemplateResult;
-    /** @soyTemplate */
-    protected renderTrailingSupportingText(): TemplateResult;
-    protected handleSlotChange(): void;
-    beginPress({ positionEvent }: BeginPressConfig): void;
-    endPress({ cancelled }: EndPressConfig): void;
-    protected handleFocus(): void;
-    protected handleBlur(): void;
-    handlePointerDown(e: PointerEvent): void;
-    protected handlePointerEnter(e: PointerEvent): void;
-    handlePointerLeave(e: PointerEvent): void;
-    /** @bubbleWizEvent */
-    protected handleKeyDown(e: KeyboardEvent): void;
-    protected handleKeyUp(e: KeyboardEvent): void;
     /**
-     * Focuses list item and makes list item focusable via keyboard.
+     * Renders the multi-line supporting text
      */
-    activate(): void;
+    protected renderMultiLineSupportingText(): TemplateResult;
     /**
-     * Returns true if list item is currently focused and is focusable.
+     * The content rendered at the end of the list item.
      */
-    isActive(): boolean;
+    protected renderEnd(): TemplateResult;
     /**
-     * Removes list item from sequential keyboard navigation.
+     * Renders the supporting text at the end of the list item.
      */
-    deactivate(): void;
+    protected renderTrailingSupportingText(): TemplateResult;
+    protected onPointerdown(): void;
+    protected onFocus(): void;
+    protected onBlur(): void;
+    protected onClick(e: Event): void;
+    protected onKeydown(e: KeyboardEvent): void;
+    protected onPointerenter(e: Event): void;
+    protected onPointerleave(e: Event): void;
+    updated(changed: PropertyValues<this>): void;
 }
+export {};

package/list/lib/listitem/list-item.js

@@ -4,257 +4,288 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { __decorate, __metadata } from "tslib";
+// Required for @ariaProperty
+// tslint:disable:no-new-decorators
 import '../../../ripple/ripple.js';
 import '../../../focus/focus-ring.js';
-import { ActionElement } from '../../../actionelement/action-element.js';
+import { html, LitElement, nothing } from 'lit';
+import { property, query, queryAsync, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
 import { ariaProperty } from '../../../decorators/aria-property.js';
 import { pointerPress, shouldShowStrongFocus } from '../../../focus/strong-focus.js';
-import { MdRipple } from '../../../ripple/ripple.js';
-import { html } from 'lit';
-import { property, query } from 'lit/decorators.js';
-import { classMap } from 'lit/directives/class-map.js';
-import { ifDefined } from 'lit/directives/if-defined.js';
-/** @soyCompatible */
-export class ListItem extends ActionElement {
+import { ripple } from '../../../ripple/directive.js';
+// tslint:disable-next-line:enforce-comments-on-exported-symbols
+export class ListItemEl extends LitElement {
     constructor() {
         super(...arguments);
         // @ts-ignore(b/264292293): Use `override` with TS 4.9+
         this.role = 'listitem';
+        /**
+         * The primary, headline text of the list item.
+         */
+        this.headline = '';
+        /**
+         * The one-line supporting text below the headline.
+         */
         this.supportingText = '';
+        /**
+         * The multi-line supporting text below the headline. __NOTE:__ if set to a
+         * truthy value, overrides the visibility and behavior of `supportingText`.
+         */
         this.multiLineSupportingText = '';
+        /**
+         * The supporting text placed at the end of the item. Overriden by elements
+         * slotted into the `end` slot.
+         */
         this.trailingSupportingText = '';
+        /**
+         * Disables the item and makes it non-selectable and non-interactive.
+         */
         this.disabled = false;
+        /**
+         * The tabindex of the underlying item.
+         *
+         * __NOTE:__ this is overriden by the keyboard behavior of `md-list` and by
+         * setting `selected`.
+         */
         this.itemTabIndex = -1;
-        this.headline = '';
+        /**
+         * Whether or not the element is in the selected visual state. When active,
+         * tabindex is set to 0, and in some list item variants (like md-list-item),
+         * focuses the underlying item.
+         */
+        this.active = false;
+        /**
+         * READONLY. Sets the `md-list-item` attribute on the element.
+         */
+        this.isListItem = true;
         this.showFocusRing = false;
+        this.showRipple = false;
+        /**
+         * Only meant to be overriden by subclassing and not by the user. This is
+         * so that we have control over focus on specific variants such as disabling
+         * focus on <md-autocomplete-item> but enabling it for <md-menu-item>.
+         */
+        this.focusOnSelection = true;
+        this.getRipple = () => {
+            this.showRipple = true;
+            return this.ripple;
+        };
+        this.isFirstUpdate = true;
+    }
+    willUpdate(changed) {
+        if (changed.has('active') && !this.disabled) {
+            if (this.active) {
+                this.itemTabIndex = 0;
+                if (this.focusOnSelection) {
+                    this.showFocusRing = shouldShowStrongFocus();
+                }
+                // Do not reset anything if it's the first render because user could
+                // have set `itemTabIndex` manually.
+            }
+            else if (!this.isFirstUpdate) {
+                this.itemTabIndex = -1;
+            }
+        }
     }
-    /** @soyTemplate */
     render() {
+        return this.renderListItem(html `
+      ${this.renderStart()}
+      ${this.renderBody()}
+      ${this.renderEnd()}
+      <div class="ripple">
+        ${this.renderRipple()}
+      </div>
+      <div class="focus-ring">
+        ${this.renderFocusRing()}
+      </div>`);
+    }
+    /**
+     * Renders the root list item.
+     *
+     * @param content {unkown} the child content of the list item.
+     */
+    renderListItem(content) {
         return html `
       <li
-          tabindex=${this.itemTabIndex}
+          tabindex=${this.disabled ? -1 : this.itemTabIndex}
           role=${this.role}
-          aria-selected=${ifDefined(this.ariaSelected || undefined)}
-          aria-checked=${ifDefined(this.ariaChecked || undefined)}
-          id=${ifDefined(this.itemId || undefined)}
-          data-query-md3-list-item
-          class="md3-list-item ${classMap(this.getRenderClasses())}"
-          @pointerdown=${this.handlePointerDown}
-          @pointerenter=${this.handlePointerEnter}
-          @pointerup=${this.handlePointerUp}
-          @pointercancel=${this.handlePointerCancel}
-          @pointerleave=${this.handlePointerLeave}
-          @keydown=${this.handleKeyDown}
-          @keyup=${this.handleKeyUp}
-          @click=${this.handleClick}
-          @contextmenu=${this.handleContextMenu}
-          @focus=${this.handleFocus}
-          @blur=${this.handleBlur}
-          >
-        ${this.renderStart()}
-        ${this.renderBody()}
-        ${this.renderEnd()}
-        <div class="md3-list-item__ripple">
-          ${this.renderRipple()}
-        </div>
-        <div class="md3-list-item__focus-ring">
-          ${this.renderFocusRing()}
-        </div>
-      </li>`;
+          aria-selected=${this.ariaSelected || nothing}
+          aria-checked=${this.ariaChecked || nothing}
+          class="list-item ${classMap(this.getRenderClasses())}"
+          @pointerdown=${this.onPointerdown}
+          @focus=${this.onFocus}
+          @blur=${this.onBlur}
+          @click=${this.onClick}
+          @pointerenter=${this.onPointerenter}
+          @pointerleave=${this.onPointerleave}
+          @keydown=${this.onKeydown}
+          ${ripple(this.getRipple)}>${content}</li>`;
     }
-    /** @soyTemplate */
+    /**
+     * Handles rendering of the ripple element.
+     */
     renderRipple() {
-        return html `<md-ripple ?disabled="${this.disabled}"></md-ripple>`;
+        return this.showRipple ?
+            html `<md-ripple ?disabled="${this.disabled}"></md-ripple>` :
+            nothing;
     }
-    /** @soyTemplate */
+    /**
+     * Handles rendering of the focus ring.
+     */
     renderFocusRing() {
         return html `<md-focus-ring .visible="${this.showFocusRing}"></md-focus-ring>`;
     }
-    /** @soyTemplate */
-    getAriaRole() {
-        return 'listitem';
-    }
-    /** @soyTemplate */
+    /**
+     * Classes applied to the list item root.
+     */
     getRenderClasses() {
         return {
-            'md3-list-item--with-one-line': this.supportingText === '' && this.multiLineSupportingText === '',
-            'md3-list-item--with-two-line': this.supportingText !== '' && this.multiLineSupportingText === '',
-            'md3-list-item--with-three-line': this.multiLineSupportingText !== '',
-            'md3-list-item--disabled': this.disabled,
-            'md3-list-item--enabled': !this.disabled,
+            'with-one-line': this.supportingText === '' && this.multiLineSupportingText === '',
+            'with-two-line': this.supportingText !== '' && this.multiLineSupportingText === '',
+            'with-three-line': this.multiLineSupportingText !== '',
+            'disabled': this.disabled,
+            'enabled': !this.disabled,
         };
     }
-    /** @soyTemplate */
+    /**
+     * The content rendered at the start of the list item.
+     */
     renderStart() {
-        return html `<div class="md3-list-item__start"><!--
-      --><slot name="start" @slotchange=${this.handleSlotChange}></slot><!--
-    --></div>`;
+        return html `<div class="start"><slot name="start"></slot></div>`;
     }
-    /** @soyTemplate */
+    /**
+     * Handles rendering the headline and supporting text.
+     */
     renderBody() {
-        return html `<div class="md3-list-item__body"><!--
-       --><span class="md3-list-item__label-text"><!--
-          -->${this.headline}<!--
-       --></span><!--
-        -->${this.multiLineSupportingText !== '' ?
+        const supportingText = this.multiLineSupportingText !== '' ?
             this.renderMultiLineSupportingText() :
             this.supportingText !== '' ? this.renderSupportingText() :
-                ''}<!--
-    --></div>`;
+                '';
+        return html `<div class="body"
+      ><span class="label-text">${this.headline}</span>${supportingText}</div>`;
     }
-    /** @soyTemplate */
+    /**
+     * Renders the one-line supporting text.
+     */
     renderSupportingText() {
-        return html `<span class="md3-list-item__supporting-text"><!--
-          -->${this.supportingText}<!--
-       --></span>`;
+        return html `<span class="supporting-text">${this.supportingText}</span>`;
     }
-    /** @soyTemplate */
+    /**
+     * Renders the multi-line supporting text
+     */
     renderMultiLineSupportingText() {
-        return html `<span class="md3-list-item__supporting-text md3-list-item__supporting-text--multi-line"><!--
-          -->${this.multiLineSupportingText}<!--
-       --></span>`;
+        return html `<span class="supporting-text supporting-text--multi-line"
+      >${this.multiLineSupportingText}</span>`;
     }
-    /** @soyTemplate */
+    /**
+     * The content rendered at the end of the list item.
+     */
     renderEnd() {
-        return html `<div class="md3-list-item__end"><!--
-      --><slot name="end" @slotchange=${this.handleSlotChange}><!--
-        -->${this.trailingSupportingText !== '' ?
+        const supportingText = this.trailingSupportingText !== '' ?
             this.renderTrailingSupportingText() :
-            ''}<!--
-      --></slot><!--
-    --></div>`;
+            '';
+        return html `<div class="end"
+      ><slot name="end">${supportingText}</slot></div>`;
     }
-    /** @soyTemplate */
+    /**
+     * Renders the supporting text at the end of the list item.
+     */
     renderTrailingSupportingText() {
-        return html `<span class="md3-list-item__trailing-supporting-text"><!--
-          -->${this.trailingSupportingText}<!--
-       --></span>`;
-    }
-    handleSlotChange() {
-        this.requestUpdate();
+        return html `<span class="trailing-supporting-text"
+      >${this.trailingSupportingText}</span>`;
     }
-    beginPress({ positionEvent }) {
-        this.ripple.beginPress(positionEvent);
-    }
-    endPress({ cancelled }) {
-        this.ripple.endPress();
-        if (cancelled)
-            return;
-        super.endPress({ cancelled, actionData: { item: this } });
-    }
-    handleFocus() {
-        this.showFocusRing = shouldShowStrongFocus();
-    }
-    handleBlur() {
-        this.showFocusRing = false;
-    }
-    handlePointerDown(e) {
-        super.handlePointerDown(e);
+    onPointerdown() {
         pointerPress();
         this.showFocusRing = shouldShowStrongFocus();
     }
-    handlePointerEnter(e) {
-        this.ripple.beginHover(e);
-    }
-    handlePointerLeave(e) {
-        super.handlePointerLeave(e);
-        this.ripple.endHover();
-    }
-    /** @bubbleWizEvent */
-    handleKeyDown(e) {
-        if (e.key !== ' ' && e.key !== 'Enter')
-            return;
-        e.preventDefault();
-        // TODO(b/240124486): Replace with beginPress provided by action
-        // element.
-        this.ripple.beginPress(e);
-    }
-    handleKeyUp(e) {
-        if (e.key !== ' ' && e.key !== 'Enter')
-            return;
-        e.preventDefault();
-        // TODO(b/240124486): Replace with beginPress provided by action element.
-        super.endPress({ cancelled: false, actionData: { item: this } });
-        this.ripple.endPress();
-    }
-    /**
-     * Focuses list item and makes list item focusable via keyboard.
-     */
-    activate() {
-        this.itemTabIndex = 0;
-        this.listItemRoot.focus();
-        this.showFocusRing = true;
+    onFocus() {
+        this.showFocusRing = shouldShowStrongFocus();
     }
-    /**
-     * Returns true if list item is currently focused and is focusable.
-     */
-    isActive() {
-        return this.itemTabIndex === 0 && this.showFocusRing;
+    onBlur() {
+        this.showFocusRing = false;
     }
-    /**
-     * Removes list item from sequential keyboard navigation.
-     */
-    deactivate() {
-        this.itemTabIndex = -1;
+    // For easier overriding in menu-item
+    onClick(e) { }
+    onKeydown(e) { }
+    onPointerenter(e) { }
+    onPointerleave(e) { }
+    updated(changed) {
+        super.updated(changed);
+        // will focus the list item root if it is selected but not on the first
+        // update or else it may cause the page to jump on first load.
+        if (changed.has('active') && !this.isFirstUpdate && this.active &&
+            this.focusOnSelection) {
+            this.listItemRoot.focus();
+        }
+        this.isFirstUpdate = false;
     }
 }
 __decorate([
-    ariaProperty // tslint:disable-line:no-new-decorators
-    // tslint:disable-next-line:decorator-placement
+    ariaProperty
+    // tslint:disable-next-line
+    ,
+    property({ type: String, attribute: 'data-role', noAccessor: true })
+    // @ts-ignore(b/264292293): Use `override` with TS 4.9+
     ,
-    property({ type: String, attribute: 'data-role', noAccessor: true }),
     __metadata("design:type", String)
-], ListItem.prototype, "role", void 0);
+], ListItemEl.prototype, "role", void 0);
 __decorate([
-    ariaProperty // tslint:disable-line:no-new-decorators
-    ,
+    ariaProperty,
     property({ type: String, attribute: 'data-aria-selected', noAccessor: true }),
     __metadata("design:type", String)
-], ListItem.prototype, "ariaSelected", void 0);
+], ListItemEl.prototype, "ariaSelected", void 0);
 __decorate([
-    ariaProperty // tslint:disable-line:no-new-decorators
-    ,
+    ariaProperty,
     property({ type: String, attribute: 'data-aria-checked', noAccessor: true }),
     __metadata("design:type", String)
-], ListItem.prototype, "ariaChecked", void 0);
+], ListItemEl.prototype, "ariaChecked", void 0);
 __decorate([
-    property({ type: String }),
-    __metadata("design:type", String)
-], ListItem.prototype, "itemId", void 0);
+    property(),
+    __metadata("design:type", Object)
+], ListItemEl.prototype, "headline", void 0);
 __decorate([
-    property({ type: String }),
+    property(),
     __metadata("design:type", Object)
-], ListItem.prototype, "supportingText", void 0);
+], ListItemEl.prototype, "supportingText", void 0);
 __decorate([
-    property({ type: String }),
+    property(),
     __metadata("design:type", Object)
-], ListItem.prototype, "multiLineSupportingText", void 0);
+], ListItemEl.prototype, "multiLineSupportingText", void 0);
 __decorate([
-    property({ type: String }),
+    property(),
     __metadata("design:type", Object)
-], ListItem.prototype, "trailingSupportingText", void 0);
+], ListItemEl.prototype, "trailingSupportingText", void 0);
 __decorate([
     property({ type: Boolean }),
     __metadata("design:type", Object)
-], ListItem.prototype, "disabled", void 0);
+], ListItemEl.prototype, "disabled", void 0);
 __decorate([
     property({ type: Number }),
     __metadata("design:type", Object)
-], ListItem.prototype, "itemTabIndex", void 0);
+], ListItemEl.prototype, "itemTabIndex", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true }),
+    __metadata("design:type", Object)
+], ListItemEl.prototype, "active", void 0);
 __decorate([
-    property({ type: String }),
+    property({ type: Boolean, attribute: 'md-list-item', reflect: true }),
     __metadata("design:type", Object)
-], ListItem.prototype, "headline", void 0);
+], ListItemEl.prototype, "isListItem", void 0);
 __decorate([
-    query('md-ripple'),
-    __metadata("design:type", MdRipple)
-], ListItem.prototype, "ripple", void 0);
+    queryAsync('md-ripple'),
+    __metadata("design:type", Promise)
+], ListItemEl.prototype, "ripple", void 0);
 __decorate([
-    query('[data-query-md3-list-item]'),
+    query('.list-item'),
     __metadata("design:type", HTMLElement)
-], ListItem.prototype, "listItemRoot", void 0);
+], ListItemEl.prototype, "listItemRoot", void 0);
 __decorate([
-    property({ type: Boolean }),
+    state(),
+    __metadata("design:type", Object)
+], ListItemEl.prototype, "showFocusRing", void 0);
+__decorate([
+    state(),
     __metadata("design:type", Object)
-], ListItem.prototype, "showFocusRing", void 0);
+], ListItemEl.prototype, "showRipple", void 0);
 //# sourceMappingURL=list-item.js.map