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

package/ripple/lib/ripple.d.ts

@@ -3,60 +3,72 @@
  * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { LitElement, PropertyValues, TemplateResult } from 'lit';
-import { ClassInfo } from 'lit/directives/class-map.js';
-/** @soyCompatible */
-export declare class Ripple extends LitElement {
-    mdRoot: HTMLElement;
-    unbounded: boolean;
+import { LitElement, PropertyValues } from 'lit';
+import { Attachable } from '../../internal/controller/attachable-controller.js';
+/**
+ * A ripple component.
+ */
+export declare class Ripple extends LitElement implements Attachable {
+    /**
+     * Disables the ripple.
+     */
     disabled: boolean;
-    protected hovered: boolean;
-    protected focused: boolean;
-    protected pressed: boolean;
-    protected rippleSize: string;
-    protected rippleScale: string;
-    protected initialSize: number;
-    protected pressAnimationSignal: import("../../motion/animation.js").AnimationSignal;
-    protected growAnimation: Animation | null;
-    protected delayedEndPressHandle: number | null;
-    /** @soyTemplate */
-    protected render(): TemplateResult;
-    /** @soyTemplate */
-    protected getRenderRippleClasses(): ClassInfo;
+    get htmlFor(): string | null;
+    set htmlFor(htmlFor: string | null);
+    get control(): HTMLElement;
+    private hovered;
+    private pressed;
+    private readonly mdRoot;
+    private rippleSize;
+    private rippleScale;
+    private initialSize;
+    private growAnimation?;
+    private state;
+    private rippleStartEvent?;
+    private checkBoundsAfterContextMenu;
+    private readonly attachableController;
+    attach(control: HTMLElement): void;
+    detach(): void;
+    protected render(): import("lit-html").TemplateResult<1>;
     protected update(changedProps: PropertyValues<this>): void;
-    protected getDimensions(): DOMRect;
-    protected determineRippleSize(): void;
-    protected getNormalizedPointerEventCoords(pointerEvent: PointerEvent): {
-        x: number;
-        y: number;
-    };
-    protected getTranslationCoordinates(positionEvent?: Event | null): {
-        startPoint: {
-            x: number;
-            y: number;
-        };
-        endPoint: {
-            x: number;
-            y: number;
-        };
-    };
-    protected startPressAnimation(positionEvent?: Event | null): void;
     /**
-     * @deprecated Use beginHover
+     * TODO(b/269799771): make private
+     * @private only public for slider
+     */
+    handlePointerenter(event: PointerEvent): void;
+    /**
+     * TODO(b/269799771): make private
+     * @private only public for slider
      */
-    startHover(hoverEvent?: Event): void;
-    beginHover(hoverEvent?: Event): void;
-    endHover(): void;
+    handlePointerleave(event: PointerEvent): void;
+    private handlePointerup;
+    private handlePointerdown;
+    private handleClick;
+    private handlePointercancel;
+    private handleContextmenu;
+    private determineRippleSize;
+    private getNormalizedPointerEventCoords;
+    private getTranslationCoordinates;
+    private startPressAnimation;
+    private endPressAnimation;
     /**
-     * @deprecated Use beginFocus
+     * Returns `true` if
+     *  - the ripple element is enabled
+     *  - the pointer is primary for the input type
+     *  - the pointer is the pointer that started the interaction, or will start
+     * the interaction
+     *  - the pointer is a touch, or the pointer state has the primary button
+     * held, or the pointer is hovering
      */
-    startFocus(): void;
-    beginFocus(): void;
-    endFocus(): void;
+    private shouldReactToEvent;
     /**
-     * @deprecated Use beginPress
+     * Check if the event is within the bounds of the element.
+     *
+     * This is only needed for the "stuck" contextmenu longpress on Chrome.
      */
-    startPress(positionEvent?: Event | null): void;
-    beginPress(positionEvent?: Event | null): void;
-    endPress(): void;
+    private inBounds;
+    private isTouch;
+    /** @private */
+    handleEvent(event: Event): Promise<void>;
+    private onControlChange;
 }

package/ripple/lib/ripple.js

@@ -3,11 +3,12 @@
  * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { __decorate, __metadata } from "tslib";
+import { __decorate } from "tslib";
 import { html, LitElement } from 'lit';
 import { property, query, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
-import { createAnimationSignal, Easing } from '../../motion/animation.js';
+import { AttachableController } from '../../internal/controller/attachable-controller.js';
+import { EASING } from '../../internal/motion/animation.js';
 const PRESS_GROW_MS = 450;
 const MINIMUM_PRESS_MS = 225;
 const INITIAL_ORIGIN_SCALE = 0.2;
@@ -16,75 +17,227 @@ const SOFT_EDGE_MINIMUM_SIZE = 75;
 const SOFT_EDGE_CONTAINER_RATIO = 0.35;
 const PRESS_PSEUDO = '::after';
 const ANIMATION_FILL = 'forwards';
-/** @soyCompatible */
+/**
+ * Interaction states for the ripple.
+ *
+ * On Touch:
+ *  - `INACTIVE -> TOUCH_DELAY -> WAITING_FOR_CLICK -> INACTIVE`
+ *  - `INACTIVE -> TOUCH_DELAY -> HOLDING -> WAITING_FOR_CLICK -> INACTIVE`
+ *
+ * On Mouse or Pen:
+ *   - `INACTIVE -> WAITING_FOR_CLICK -> INACTIVE`
+ */
+var State;
+(function (State) {
+    /**
+     * Initial state of the control, no touch in progress.
+     *
+     * Transitions:
+     *   - on touch down: transition to `TOUCH_DELAY`.
+     *   - on mouse down: transition to `WAITING_FOR_CLICK`.
+     */
+    State[State["INACTIVE"] = 0] = "INACTIVE";
+    /**
+     * Touch down has been received, waiting to determine if it's a swipe or
+     * scroll.
+     *
+     * Transitions:
+     *   - on touch up: begin press; transition to `WAITING_FOR_CLICK`.
+     *   - on cancel: transition to `INACTIVE`.
+     *   - after `TOUCH_DELAY_MS`: begin press; transition to `HOLDING`.
+     */
+    State[State["TOUCH_DELAY"] = 1] = "TOUCH_DELAY";
+    /**
+     * A touch has been deemed to be a press
+     *
+     * Transitions:
+     *  - on up: transition to `WAITING_FOR_CLICK`.
+     */
+    State[State["HOLDING"] = 2] = "HOLDING";
+    /**
+     * The user touch has finished, transition into rest state.
+     *
+     * Transitions:
+     *   - on click end press; transition to `INACTIVE`.
+     */
+    State[State["WAITING_FOR_CLICK"] = 3] = "WAITING_FOR_CLICK";
+})(State || (State = {}));
+/**
+ * Events that the ripple listens to.
+ */
+const EVENTS = [
+    'click', 'contextmenu', 'pointercancel', 'pointerdown', 'pointerenter',
+    'pointerleave', 'pointerup'
+];
+/**
+ * Delay reacting to touch so that we do not show the ripple for a swipe or
+ * scroll interaction.
+ */
+const TOUCH_DELAY_MS = 150;
+/**
+ * A ripple component.
+ */
 export class Ripple extends LitElement {
     constructor() {
         super(...arguments);
-        // TODO(https://bugs.webkit.org/show_bug.cgi?id=247546)
-        // Remove Safari workaround that requires reflecting `unbounded` so
-        // it can be styled against.
-        this.unbounded = false;
+        /**
+         * Disables the ripple.
+         */
         this.disabled = false;
         this.hovered = false;
-        this.focused = false;
         this.pressed = false;
         this.rippleSize = '';
         this.rippleScale = '';
         this.initialSize = 0;
-        this.pressAnimationSignal = createAnimationSignal();
-        this.growAnimation = null;
-        this.delayedEndPressHandle = null;
+        this.state = State.INACTIVE;
+        this.checkBoundsAfterContextMenu = false;
+        this.attachableController = new AttachableController(this, this.onControlChange.bind(this));
+    }
+    get htmlFor() {
+        return this.attachableController.htmlFor;
+    }
+    set htmlFor(htmlFor) {
+        this.attachableController.htmlFor = htmlFor;
+    }
+    get control() {
+        return this.attachableController.control;
+    }
+    attach(control) {
+        this.attachableController.attach(control);
+    }
+    detach() {
+        this.attachableController.detach();
     }
-    /** @soyTemplate */
     render() {
-        return html `<div class="md3-ripple-surface ${classMap(this.getRenderRippleClasses())}"></div>`;
-    }
-    /** @soyTemplate */
-    getRenderRippleClasses() {
-        return {
-            'md3-ripple--hovered': this.hovered,
-            'md3-ripple--focused': this.focused,
-            'md3-ripple--pressed': this.pressed,
-            'md3-ripple--unbounded': this.unbounded,
+        const classes = {
+            'hovered': this.hovered,
+            'pressed': this.pressed,
         };
+        return html `<div class="surface ${classMap(classes)}"></div>`;
     }
     update(changedProps) {
         if (changedProps.has('disabled') && this.disabled) {
-            this.endHover();
-            this.endFocus();
-            this.endPress();
+            this.hovered = false;
+            this.pressed = false;
         }
         super.update(changedProps);
     }
-    getDimensions() {
-        return (this.parentElement ?? this).getBoundingClientRect();
+    /**
+     * TODO(b/269799771): make private
+     * @private only public for slider
+     */
+    handlePointerenter(event) {
+        if (!this.shouldReactToEvent(event)) {
+            return;
+        }
+        this.hovered = true;
+    }
+    /**
+     * TODO(b/269799771): make private
+     * @private only public for slider
+     */
+    handlePointerleave(event) {
+        if (!this.shouldReactToEvent(event)) {
+            return;
+        }
+        this.hovered = false;
+        // release a held mouse or pen press that moves outside the element
+        if (this.state !== State.INACTIVE) {
+            this.endPressAnimation();
+        }
+    }
+    handlePointerup(event) {
+        if (!this.shouldReactToEvent(event)) {
+            return;
+        }
+        if (this.state === State.HOLDING) {
+            this.state = State.WAITING_FOR_CLICK;
+            return;
+        }
+        if (this.state === State.TOUCH_DELAY) {
+            this.state = State.WAITING_FOR_CLICK;
+            this.startPressAnimation(this.rippleStartEvent);
+            return;
+        }
+    }
+    async handlePointerdown(event) {
+        if (!this.shouldReactToEvent(event)) {
+            return;
+        }
+        this.rippleStartEvent = event;
+        if (!this.isTouch(event)) {
+            this.state = State.WAITING_FOR_CLICK;
+            this.startPressAnimation(event);
+            return;
+        }
+        // after a longpress contextmenu event, an extra `pointerdown` can be
+        // dispatched to the pressed element. Check that the down is within
+        // bounds of the element in this case.
+        if (this.checkBoundsAfterContextMenu && !this.inBounds(event)) {
+            return;
+        }
+        this.checkBoundsAfterContextMenu = false;
+        // Wait for a hold after touch delay
+        this.state = State.TOUCH_DELAY;
+        await new Promise(resolve => {
+            setTimeout(resolve, TOUCH_DELAY_MS);
+        });
+        if (this.state !== State.TOUCH_DELAY) {
+            return;
+        }
+        this.state = State.HOLDING;
+        this.startPressAnimation(event);
+    }
+    handleClick() {
+        // Click is a MouseEvent in Firefox and Safari, so we cannot use
+        // `shouldReactToEvent`
+        if (this.disabled) {
+            return;
+        }
+        if (this.state === State.WAITING_FOR_CLICK) {
+            this.endPressAnimation();
+            return;
+        }
+        if (this.state === State.INACTIVE) {
+            // keyboard synthesized click event
+            this.startPressAnimation();
+            this.endPressAnimation();
+        }
+    }
+    handlePointercancel(event) {
+        if (!this.shouldReactToEvent(event)) {
+            return;
+        }
+        this.endPressAnimation();
+    }
+    handleContextmenu() {
+        if (this.disabled) {
+            return;
+        }
+        this.checkBoundsAfterContextMenu = true;
+        this.endPressAnimation();
     }
     determineRippleSize() {
-        const { height, width } = this.getDimensions();
+        const { height, width } = this.getBoundingClientRect();
         const maxDim = Math.max(height, width);
         const softEdgeSize = Math.max(SOFT_EDGE_CONTAINER_RATIO * maxDim, SOFT_EDGE_MINIMUM_SIZE);
-        let maxRadius = maxDim;
-        let initialSize = Math.floor(maxDim * INITIAL_ORIGIN_SCALE);
+        const initialSize = Math.floor(maxDim * INITIAL_ORIGIN_SCALE);
         const hypotenuse = Math.sqrt(width ** 2 + height ** 2);
-        maxRadius = hypotenuse + PADDING;
-        // ensure `initialSize` is even for unbounded
-        if (this.unbounded) {
-            initialSize = initialSize - (initialSize % 2);
-        }
+        const maxRadius = hypotenuse + PADDING;
         this.initialSize = initialSize;
         this.rippleScale = `${(maxRadius + softEdgeSize) / initialSize}`;
-        this.rippleSize = `${this.initialSize}px`;
+        this.rippleSize = `${initialSize}px`;
     }
     getNormalizedPointerEventCoords(pointerEvent) {
         const { scrollX, scrollY } = window;
-        const { left, top } = this.getDimensions();
+        const { left, top } = this.getBoundingClientRect();
         const documentX = scrollX + left;
         const documentY = scrollY + top;
         const { pageX, pageY } = pointerEvent;
         return { x: pageX - documentX, y: pageY - documentY };
     }
     getTranslationCoordinates(positionEvent) {
-        const { height, width } = this.getDimensions();
+        const { height, width } = this.getBoundingClientRect();
         // end in the center
         const endPoint = {
             x: (width - this.initialSize) / 2,
@@ -108,12 +261,16 @@ export class Ripple extends LitElement {
         return { startPoint, endPoint };
     }
     startPressAnimation(positionEvent) {
+        if (!this.mdRoot) {
+            return;
+        }
+        this.pressed = true;
+        this.growAnimation?.cancel();
         this.determineRippleSize();
         const { startPoint, endPoint } = this.getTranslationCoordinates(positionEvent);
         const translateStart = `${startPoint.x}px, ${startPoint.y}px`;
         const translateEnd = `${endPoint.x}px, ${endPoint.y}px`;
-        const signal = this.pressAnimationSignal.start();
-        const growAnimation = this.mdRoot.animate({
+        this.growAnimation = this.mdRoot.animate({
             top: [0, 0],
             left: [0, 0],
             height: [this.rippleSize, this.rippleSize],
@@ -125,94 +282,108 @@ export class Ripple extends LitElement {
         }, {
             pseudoElement: PRESS_PSEUDO,
             duration: PRESS_GROW_MS,
-            easing: Easing.STANDARD,
+            easing: EASING.STANDARD,
             fill: ANIMATION_FILL
         });
-        growAnimation.addEventListener('finish', () => {
-            this.pressAnimationSignal.finish();
-            this.growAnimation = null;
-        });
-        signal.addEventListener('abort', () => {
-            growAnimation.cancel();
-            this.growAnimation = null;
+    }
+    async endPressAnimation() {
+        this.state = State.INACTIVE;
+        const animation = this.growAnimation;
+        const pressAnimationPlayState = animation?.currentTime ?? Infinity;
+        if (pressAnimationPlayState >= MINIMUM_PRESS_MS) {
+            this.pressed = false;
+            return;
+        }
+        await new Promise(resolve => {
+            setTimeout(resolve, MINIMUM_PRESS_MS - pressAnimationPlayState);
         });
-        this.growAnimation = growAnimation;
+        if (this.growAnimation !== animation) {
+            // A new press animation was started. The old animation was canceled and
+            // should not finish the pressed state.
+            return;
+        }
+        this.pressed = false;
     }
     /**
-     * @deprecated Use beginHover
+     * Returns `true` if
+     *  - the ripple element is enabled
+     *  - the pointer is primary for the input type
+     *  - the pointer is the pointer that started the interaction, or will start
+     * the interaction
+     *  - the pointer is a touch, or the pointer state has the primary button
+     * held, or the pointer is hovering
      */
-    startHover(hoverEvent) {
-        this.beginHover(hoverEvent);
-    }
-    beginHover(hoverEvent) {
-        if (hoverEvent?.pointerType !== 'touch') {
-            this.hovered = true;
+    shouldReactToEvent(event) {
+        if (this.disabled || !event.isPrimary) {
+            return false;
         }
-    }
-    endHover() {
-        this.hovered = false;
+        if (this.rippleStartEvent &&
+            this.rippleStartEvent.pointerId !== event.pointerId) {
+            return false;
+        }
+        if (event.type === 'pointerenter' || event.type === 'pointerleave') {
+            return !this.isTouch(event);
+        }
+        const isPrimaryButton = event.buttons === 1;
+        return this.isTouch(event) || isPrimaryButton;
     }
     /**
-     * @deprecated Use beginFocus
+     * Check if the event is within the bounds of the element.
+     *
+     * This is only needed for the "stuck" contextmenu longpress on Chrome.
      */
-    startFocus() {
-        this.beginFocus();
-    }
-    beginFocus() {
-        this.focused = true;
+    inBounds({ x, y }) {
+        const { top, left, bottom, right } = this.getBoundingClientRect();
+        return x >= left && x <= right && y >= top && y <= bottom;
     }
-    endFocus() {
-        this.focused = false;
+    isTouch({ pointerType }) {
+        return pointerType === 'touch';
     }
-    /**
-     * @deprecated Use beginPress
-     */
-    startPress(positionEvent) {
-        this.beginPress(positionEvent);
-    }
-    beginPress(positionEvent) {
-        this.pressed = true;
-        if (this.delayedEndPressHandle !== null) {
-            clearTimeout(this.delayedEndPressHandle);
-            this.delayedEndPressHandle = null;
+    /** @private */
+    async handleEvent(event) {
+        switch (event.type) {
+            case 'click':
+                this.handleClick();
+                break;
+            case 'contextmenu':
+                this.handleContextmenu();
+                break;
+            case 'pointercancel':
+                this.handlePointercancel(event);
+                break;
+            case 'pointerdown':
+                await this.handlePointerdown(event);
+                break;
+            case 'pointerenter':
+                this.handlePointerenter(event);
+                break;
+            case 'pointerleave':
+                this.handlePointerleave(event);
+                break;
+            case 'pointerup':
+                this.handlePointerup(event);
+                break;
+            default:
+                break;
         }
-        this.startPressAnimation(positionEvent);
     }
-    endPress() {
-        const pressAnimationPlayState = this.growAnimation?.currentTime ?? Infinity;
-        if (pressAnimationPlayState >= MINIMUM_PRESS_MS) {
-            this.pressed = false;
-        }
-        else {
-            this.delayedEndPressHandle = setTimeout(() => {
-                this.pressed = false;
-                this.delayedEndPressHandle = null;
-            }, MINIMUM_PRESS_MS - pressAnimationPlayState);
+    onControlChange(prev, next) {
+        for (const event of EVENTS) {
+            prev?.removeEventListener(event, this);
+            next?.addEventListener(event, this);
         }
     }
 }
 __decorate([
-    query('.md3-ripple-surface'),
-    __metadata("design:type", HTMLElement)
-], Ripple.prototype, "mdRoot", void 0);
-__decorate([
-    property({ type: Boolean, reflect: true }),
-    __metadata("design:type", Object)
-], Ripple.prototype, "unbounded", void 0);
-__decorate([
-    property({ type: Boolean, reflect: true }),
-    __metadata("design:type", Object)
+    property({ type: Boolean, reflect: true })
 ], Ripple.prototype, "disabled", void 0);
 __decorate([
-    state(),
-    __metadata("design:type", Object)
+    state()
 ], Ripple.prototype, "hovered", void 0);
 __decorate([
-    state(),
-    __metadata("design:type", Object)
-], Ripple.prototype, "focused", void 0);
-__decorate([
-    state(),
-    __metadata("design:type", Object)
+    state()
 ], Ripple.prototype, "pressed", void 0);
+__decorate([
+    query('.surface')
+], Ripple.prototype, "mdRoot", void 0);
 //# sourceMappingURL=ripple.js.map