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

package/menu/lib/surfacePositionController.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import { StyleInfo } from 'lit/directives/style-map.js';
+/**
+ * A corner of a box in the standard logical property style of <block>_<inline>
+ */
+export type Corner = 'END_START' | 'END_END' | 'START_START' | 'START_END';
+/**
+ * An interface that provides a method to customize the rect from which to
+ * calculate the anchor positioning. Useful for when you want a surface to
+ * anchor to an element in your shadow DOM rather than the host element.
+ */
+export interface SurfacePositionTarget extends HTMLElement {
+    getSurfacePositionClientRect?: () => DOMRect;
+}
+/**
+ * The configurable options for the surface position controller.
+ */
+export interface SurfacePositionControllerProperties {
+    /**
+     * The corner of the anchor to align the surface's position.
+     */
+    anchorCorner: Corner;
+    /**
+     * The corner of the surface to align to the given anchor corner.
+     */
+    surfaceCorner: Corner;
+    /**
+     * The HTMLElement reference of the surface to be positioned.
+     */
+    surfaceEl: SurfacePositionTarget | null;
+    /**
+     * The HTMLElement reference of the anchor to align to.
+     */
+    anchorEl: SurfacePositionTarget | null;
+    /**
+     * Whether or not the calculation should be relative to the top layer rather
+     * than relative to the parent of the anchor.
+     *
+     * Examples for `isTopLayer:true`:
+     *
+     * - If there is no `position:relative` in the given parent tree and the
+     *   surface is `position:absolute`
+     * - If the surface is `position:fixed`
+     * - If the surface is in the "top layer"
+     * - The anchor and the surface do not share a common `position:relative`
+     *   ancestor
+     */
+    isTopLayer: boolean;
+    /**
+     * Whether or not the surface should be "open" and visible
+     */
+    isOpen: boolean;
+    /**
+     * The number of pixels in which to offset from the inline axis relative to
+     * logical property.
+     *
+     * Positive is right in LTR and left in RTL.
+     */
+    xOffset: number;
+    /**
+     * The number of pixes in which to offset the block axis.
+     *
+     * Positive is down and negative is up.
+     */
+    yOffset: number;
+    /**
+     * A function to call after the surface has been positioned.
+     */
+    onOpen: () => void;
+    /**
+     * A function to call before the surface should be closed. (A good time to
+     * perform animations while the surface is still visible)
+     */
+    beforeClose: () => Promise<void>;
+    /**
+     * A function to call after the surface has been closed.
+     */
+    onClose: () => void;
+}
+/**
+ * Given a surface, an anchor, corners, and some options, this surface will
+ * calculate the position of a surface to align the two given corners and keep
+ * the surface inside the window viewport. It also provides a StyleInfo map that
+ * can be applied to the surface to handle visiblility and position.
+ */
+export declare class SurfacePositionController implements ReactiveController {
+    private readonly host;
+    private readonly getProperties;
+    private surfaceStylesInternal;
+    private lastValues;
+    /**
+     * @param host The host to connect the controller to.
+     * @param getProperties A function that returns the properties for the
+     * controller.
+     */
+    constructor(host: ReactiveControllerHost, getProperties: () => SurfacePositionControllerProperties);
+    /**
+     * The StyleInfo map to apply to the surface via Lit's stylemap
+     */
+    get surfaceStyles(): StyleInfo;
+    /**
+     * Calculates the surface's new position required so that the surface's
+     * `surfaceCorner` aligns to the anchor's `anchorCorner` while keeping the
+     * surface inside the window viewport. This positioning also respects RTL by
+     * checking `getComputedStyle()` on the surface element.
+     */
+    position(): Promise<void>;
+    hostUpdate(): void;
+    hostUpdated(): void;
+    /**
+     * Checks whether the properties passed into the controller have changed since
+     * the last positioning. If so, it will reposition if the surface is open or
+     * close it if the surface should close.
+     */
+    private onUpdate;
+    /**
+     * Hides the surface.
+     */
+    private close;
+}

package/menu/lib/surfacePositionController.js

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Given a surface, an anchor, corners, and some options, this surface will
+ * calculate the position of a surface to align the two given corners and keep
+ * the surface inside the window viewport. It also provides a StyleInfo map that
+ * can be applied to the surface to handle visiblility and position.
+ */
+export class SurfacePositionController {
+    /**
+     * @param host The host to connect the controller to.
+     * @param getProperties A function that returns the properties for the
+     * controller.
+     */
+    constructor(host, getProperties) {
+        this.host = host;
+        this.getProperties = getProperties;
+        // The current styles to apply to the surface.
+        this.surfaceStylesInternal = {
+            'display': 'none',
+        };
+        // Previous values stored for change detection. Open change detection is
+        // calculated separately so initialize it here.
+        this.lastValues = { isOpen: false };
+        this.host.addController(this);
+    }
+    /**
+     * The StyleInfo map to apply to the surface via Lit's stylemap
+     */
+    get surfaceStyles() {
+        return this.surfaceStylesInternal;
+    }
+    /**
+     * Calculates the surface's new position required so that the surface's
+     * `surfaceCorner` aligns to the anchor's `anchorCorner` while keeping the
+     * surface inside the window viewport. This positioning also respects RTL by
+     * checking `getComputedStyle()` on the surface element.
+     */
+    async position() {
+        const { surfaceEl, anchorEl, anchorCorner: anchorCornerRaw, surfaceCorner: surfaceCornerRaw, isTopLayer: topLayerRaw, xOffset, yOffset, } = this.getProperties();
+        const anchorCorner = anchorCornerRaw.toUpperCase().trim();
+        const surfaceCorner = surfaceCornerRaw.toUpperCase().trim();
+        if (!surfaceEl || !anchorEl) {
+            return;
+        }
+        // Paint the surface transparently so that we can get the position and the
+        // rect info of the surface.
+        this.surfaceStylesInternal = {
+            'display': 'block',
+            'opacity': '0',
+        };
+        // Wait for it to be visible.
+        this.host.requestUpdate();
+        await this.host.updateComplete;
+        const surfaceRect = surfaceEl.getSurfacePositionClientRect ?
+            surfaceEl.getSurfacePositionClientRect() :
+            surfaceEl.getBoundingClientRect();
+        const anchorRect = anchorEl.getSurfacePositionClientRect ?
+            anchorEl.getSurfacePositionClientRect() :
+            anchorEl.getBoundingClientRect();
+        const [surfaceBlock, surfaceInline] = surfaceCorner.split('_');
+        const [anchorBlock, anchorInline] = anchorCorner.split('_');
+        // We use number booleans to multiply values rather than `if` / ternary
+        // statements because it _heavily_ cuts down on nesting and readability
+        const isTopLayer = topLayerRaw ? 1 : 0;
+        // LTR depends on the direction of the SURFACE not the anchor.
+        const isLTR = getComputedStyle(surfaceEl).direction === 'ltr' ? 1 : 0;
+        const isRTL = isLTR ? 0 : 1;
+        const isSurfaceInlineStart = surfaceInline === 'START' ? 1 : 0;
+        const isSurfaceInlineEnd = surfaceInline === 'END' ? 1 : 0;
+        const isSurfaceBlockStart = surfaceBlock === 'START' ? 1 : 0;
+        const isSurfaceBlockEnd = surfaceBlock === 'END' ? 1 : 0;
+        const isOneInlineEnd = anchorInline !== surfaceInline ? 1 : 0;
+        const isOneBlockEnd = anchorBlock !== surfaceBlock ? 1 : 0;
+        /*
+         * A diagram that helps describe some of the variables used in the following
+         * calculations.
+         *
+         * ┌───── inline/blockTopLayerOffset
+         * │       │
+         * │     ┌─▼───┐                  Window
+         * │    ┌┼─────┴────────────────────────┐
+         * │    ││                              │
+         * └──► ││  ┌──inline/blockAnchorOffset │
+         *      ││  │     │                     │
+         *      └┤  │  ┌──▼───┐                 │
+         *       │  │ ┌┼──────┤                 │
+         *       │  └─►│Anchor│                 │
+         *       │    └┴──────┘                 │
+         *       │                              │
+         *       │     ┌────────────────────────┼────┐
+         *       │     │ Surface                │    │
+         *       │     │                        │    │
+         *       │     │                        │    │
+         *       │     │                        │    │
+         *       │     │                        │    │
+         *       │     │                        │    │
+         *       └─────┼────────────────────────┘    ├┐
+         *             │ inline/blockOOBCorrection   ││
+         *             │                         │   ││
+         *             │                         ├──►││
+         *             │                         │   ││
+         *             └────────────────────────┐▼───┼┘
+         *                                      └────┘
+         */
+        // Whether or not to apply the width of the anchor
+        const inlineAnchorOffset = isOneInlineEnd * anchorRect.width + xOffset;
+        // The inline position of the anchor relative to window in LTR
+        const inlineTopLayerOffsetLTR = isSurfaceInlineStart * anchorRect.left +
+            isSurfaceInlineEnd * (window.innerWidth - anchorRect.right);
+        // The inline position of the anchor relative to window in RTL
+        const inlineTopLayerOffsetRTL = isSurfaceInlineStart * (window.innerWidth - anchorRect.right) +
+            isSurfaceInlineEnd * anchorRect.left;
+        // The inline position of the anchor relative to window
+        const inlineTopLayerOffset = isLTR * inlineTopLayerOffsetLTR + isRTL * inlineTopLayerOffsetRTL;
+        // If the surface's inline would be out of bounds of the window, move it
+        // back in
+        const inlineOutOfBoundsCorrection = Math.min(0, window.innerWidth - inlineTopLayerOffset - inlineAnchorOffset -
+            surfaceRect.width);
+        // The inline logical value of the surface
+        const inline = isTopLayer * inlineTopLayerOffset + inlineAnchorOffset +
+            inlineOutOfBoundsCorrection;
+        // Whether or not to apply the height of the anchor
+        const blockAnchorOffset = isOneBlockEnd * anchorRect.height + yOffset;
+        // The absolute block position of the anchor relative to window
+        const blockTopLayerOffset = isSurfaceBlockStart * anchorRect.top +
+            isSurfaceBlockEnd * (window.innerHeight - anchorRect.bottom);
+        // If the surface's block would be out of bounds of the window, move it back
+        // in
+        const blockOutOfBoundsCorrection = Math.min(0, window.innerHeight - blockTopLayerOffset - blockAnchorOffset -
+            surfaceRect.height);
+        // The block logical value of the surface
+        const block = isTopLayer * blockTopLayerOffset + blockAnchorOffset +
+            blockOutOfBoundsCorrection;
+        const surfaceBlockProperty = surfaceBlock === 'START' ? 'inset-block-start' : 'inset-block-end';
+        const surfaceInlineProperty = surfaceInline === 'START' ? 'inset-inline-start' : 'inset-inline-end';
+        this.surfaceStylesInternal = {
+            'display': 'block',
+            'opacity': '1',
+            [surfaceBlockProperty]: `${block}px`,
+            [surfaceInlineProperty]: `${inline}px`,
+        };
+        this.host.requestUpdate();
+    }
+    hostUpdate() {
+        this.onUpdate();
+    }
+    hostUpdated() {
+        this.onUpdate();
+    }
+    /**
+     * Checks whether the properties passed into the controller have changed since
+     * the last positioning. If so, it will reposition if the surface is open or
+     * close it if the surface should close.
+     */
+    async onUpdate() {
+        const props = this.getProperties();
+        let hasChanged = false;
+        for (const [key, value] of Object.entries(props)) {
+            // tslint:disable-next-line
+            hasChanged = hasChanged || (value !== this.lastValues[key]);
+            if (hasChanged)
+                break;
+        }
+        const openChanged = this.lastValues.isOpen !== props.isOpen;
+        const hasAnchor = !!props.anchorEl;
+        const hasSurface = !!props.surfaceEl;
+        if (hasChanged && hasAnchor && hasSurface) {
+            // Only update isOpen, because if it's closed, we do not want to waste
+            // time on a useless reposition calculation. So save the other "dirty"
+            // values until next time it opens.
+            this.lastValues.isOpen = props.isOpen;
+            if (props.isOpen) {
+                // We are going to do a reposition, so save the prop values for future
+                // dirty checking.
+                this.lastValues = props;
+                await this.position();
+                props.onOpen();
+            }
+            else if (openChanged) {
+                await props.beforeClose();
+                this.close();
+                props.onClose();
+            }
+        }
+    }
+    /**
+     * Hides the surface.
+     */
+    close() {
+        this.surfaceStylesInternal = {
+            'display': 'none',
+        };
+        this.host.requestUpdate();
+    }
+}
+//# sourceMappingURL=surfacePositionController.js.map

package/menu/lib/surfacePositionController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfacePositionController.js","sourceRoot":"","sources":["surfacePositionController.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2023 Google LLC\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport {ReactiveController, ReactiveControllerHost} from 'lit';\nimport {StyleInfo} from 'lit/directives/style-map.js';\n\n/**\n * A corner of a box in the standard logical property style of <block>_<inline>\n */\nexport type Corner = 'END_START'|'END_END'|'START_START'|'START_END';\n\n/**\n * An interface that provides a method to customize the rect from which to\n * calculate the anchor positioning. Useful for when you want a surface to\n * anchor to an element in your shadow DOM rather than the host element.\n */\nexport interface SurfacePositionTarget extends HTMLElement {\n  getSurfacePositionClientRect?: () => DOMRect;\n}\n\n/**\n * The configurable options for the surface position controller.\n */\nexport interface SurfacePositionControllerProperties {\n  /**\n   * The corner of the anchor to align the surface's position.\n   */\n  anchorCorner: Corner;\n  /**\n   * The corner of the surface to align to the given anchor corner.\n   */\n  surfaceCorner: Corner;\n  /**\n   * The HTMLElement reference of the surface to be positioned.\n   */\n  surfaceEl: SurfacePositionTarget|null;\n  /**\n   * The HTMLElement reference of the anchor to align to.\n   */\n  anchorEl: SurfacePositionTarget|null;\n  /**\n   * Whether or not the calculation should be relative to the top layer rather\n   * than relative to the parent of the anchor.\n   *\n   * Examples for `isTopLayer:true`:\n   *\n   * - If there is no `position:relative` in the given parent tree and the\n   *   surface is `position:absolute`\n   * - If the surface is `position:fixed`\n   * - If the surface is in the \"top layer\"\n   * - The anchor and the surface do not share a common `position:relative`\n   *   ancestor\n   */\n  isTopLayer: boolean;\n  /**\n   * Whether or not the surface should be \"open\" and visible\n   */\n  isOpen: boolean;\n  /**\n   * The number of pixels in which to offset from the inline axis relative to\n   * logical property.\n   *\n   * Positive is right in LTR and left in RTL.\n   */\n  xOffset: number;\n  /**\n   * The number of pixes in which to offset the block axis.\n   *\n   * Positive is down and negative is up.\n   */\n  yOffset: number;\n  /**\n   * A function to call after the surface has been positioned.\n   */\n  onOpen: () => void;\n  /**\n   * A function to call before the surface should be closed. (A good time to\n   * perform animations while the surface is still visible)\n   */\n  beforeClose: () => Promise<void>;\n  /**\n   * A function to call after the surface has been closed.\n   */\n  onClose: () => void;\n}\n\n/**\n * Given a surface, an anchor, corners, and some options, this surface will\n * calculate the position of a surface to align the two given corners and keep\n * the surface inside the window viewport. It also provides a StyleInfo map that\n * can be applied to the surface to handle visiblility and position.\n */\nexport class SurfacePositionController implements ReactiveController {\n  // The current styles to apply to the surface.\n  private surfaceStylesInternal: StyleInfo = {\n    'display': 'none',\n  };\n  // Previous values stored for change detection. Open change detection is\n  // calculated separately so initialize it here.\n  private lastValues: SurfacePositionControllerProperties = {isOpen: false} as\n      SurfacePositionControllerProperties;\n\n  /**\n   * @param host The host to connect the controller to.\n   * @param getProperties A function that returns the properties for the\n   * controller.\n   */\n  constructor(\n      private readonly host: ReactiveControllerHost,\n      private readonly getProperties: () => SurfacePositionControllerProperties,\n  ) {\n    this.host.addController(this);\n  }\n\n  /**\n   * The StyleInfo map to apply to the surface via Lit's stylemap\n   */\n  get surfaceStyles() {\n    return this.surfaceStylesInternal;\n  }\n\n  /**\n   * Calculates the surface's new position required so that the surface's\n   * `surfaceCorner` aligns to the anchor's `anchorCorner` while keeping the\n   * surface inside the window viewport. This positioning also respects RTL by\n   * checking `getComputedStyle()` on the surface element.\n   */\n  async position() {\n    const {\n      surfaceEl,\n      anchorEl,\n      anchorCorner: anchorCornerRaw,\n      surfaceCorner: surfaceCornerRaw,\n      isTopLayer: topLayerRaw,\n      xOffset,\n      yOffset,\n    } = this.getProperties();\n    const anchorCorner = anchorCornerRaw.toUpperCase().trim();\n    const surfaceCorner = surfaceCornerRaw.toUpperCase().trim();\n\n    if (!surfaceEl || !anchorEl) {\n      return;\n    }\n\n    // Paint the surface transparently so that we can get the position and the\n    // rect info of the surface.\n    this.surfaceStylesInternal = {\n      'display': 'block',\n      'opacity': '0',\n    };\n\n    // Wait for it to be visible.\n    this.host.requestUpdate();\n    await this.host.updateComplete;\n\n    const surfaceRect = surfaceEl.getSurfacePositionClientRect ?\n        surfaceEl.getSurfacePositionClientRect() :\n        surfaceEl.getBoundingClientRect();\n    const anchorRect = anchorEl.getSurfacePositionClientRect ?\n        anchorEl.getSurfacePositionClientRect() :\n        anchorEl.getBoundingClientRect();\n    const [surfaceBlock, surfaceInline] =\n        surfaceCorner.split('_') as Array<'START'|'END'>;\n    const [anchorBlock, anchorInline] =\n        anchorCorner.split('_') as Array<'START'|'END'>;\n\n\n    // We use number booleans to multiply values rather than `if` / ternary\n    // statements because it _heavily_ cuts down on nesting and readability\n    const isTopLayer = topLayerRaw ? 1 : 0;\n    // LTR depends on the direction of the SURFACE not the anchor.\n    const isLTR =\n        getComputedStyle(surfaceEl as HTMLElement).direction === 'ltr' ? 1 : 0;\n    const isRTL = isLTR ? 0 : 1;\n    const isSurfaceInlineStart = surfaceInline === 'START' ? 1 : 0;\n    const isSurfaceInlineEnd = surfaceInline === 'END' ? 1 : 0;\n    const isSurfaceBlockStart = surfaceBlock === 'START' ? 1 : 0;\n    const isSurfaceBlockEnd = surfaceBlock === 'END' ? 1 : 0;\n    const isOneInlineEnd = anchorInline !== surfaceInline ? 1 : 0;\n    const isOneBlockEnd = anchorBlock !== surfaceBlock ? 1 : 0;\n\n    /*\n     * A diagram that helps describe some of the variables used in the following\n     * calculations.\n     *\n     * ┌───── inline/blockTopLayerOffset\n     * │       │\n     * │     ┌─▼───┐                  Window\n     * │    ┌┼─────┴────────────────────────┐\n     * │    ││                              │\n     * └──► ││  ┌──inline/blockAnchorOffset │\n     *      ││  │     │                     │\n     *      └┤  │  ┌──▼───┐                 │\n     *       │  │ ┌┼──────┤                 │\n     *       │  └─►│Anchor│                 │\n     *       │    └┴──────┘                 │\n     *       │                              │\n     *       │     ┌────────────────────────┼────┐\n     *       │     │ Surface                │    │\n     *       │     │                        │    │\n     *       │     │                        │    │\n     *       │     │                        │    │\n     *       │     │                        │    │\n     *       │     │                        │    │\n     *       └─────┼────────────────────────┘    ├┐\n     *             │ inline/blockOOBCorrection   ││\n     *             │                         │   ││\n     *             │                         ├──►││\n     *             │                         │   ││\n     *             └────────────────────────┐▼───┼┘\n     *                                      └────┘\n     */\n\n    // Whether or not to apply the width of the anchor\n    const inlineAnchorOffset = isOneInlineEnd * anchorRect.width + xOffset;\n    // The inline position of the anchor relative to window in LTR\n    const inlineTopLayerOffsetLTR = isSurfaceInlineStart * anchorRect.left +\n        isSurfaceInlineEnd * (window.innerWidth - anchorRect.right);\n    // The inline position of the anchor relative to window in RTL\n    const inlineTopLayerOffsetRTL =\n        isSurfaceInlineStart * (window.innerWidth - anchorRect.right) +\n        isSurfaceInlineEnd * anchorRect.left;\n    // The inline position of the anchor relative to window\n    const inlineTopLayerOffset =\n        isLTR * inlineTopLayerOffsetLTR + isRTL * inlineTopLayerOffsetRTL;\n    // If the surface's inline would be out of bounds of the window, move it\n    // back in\n    const inlineOutOfBoundsCorrection = Math.min(\n        0,\n        window.innerWidth - inlineTopLayerOffset - inlineAnchorOffset -\n            surfaceRect.width);\n\n    // The inline logical value of the surface\n    const inline = isTopLayer * inlineTopLayerOffset + inlineAnchorOffset +\n        inlineOutOfBoundsCorrection;\n\n    // Whether or not to apply the height of the anchor\n    const blockAnchorOffset = isOneBlockEnd * anchorRect.height + yOffset;\n    // The absolute block position of the anchor relative to window\n    const blockTopLayerOffset = isSurfaceBlockStart * anchorRect.top +\n        isSurfaceBlockEnd * (window.innerHeight - anchorRect.bottom);\n    // If the surface's block would be out of bounds of the window, move it back\n    // in\n    const blockOutOfBoundsCorrection = Math.min(\n        0,\n        window.innerHeight - blockTopLayerOffset - blockAnchorOffset -\n            surfaceRect.height);\n\n    // The block logical value of the surface\n    const block = isTopLayer * blockTopLayerOffset + blockAnchorOffset +\n        blockOutOfBoundsCorrection;\n\n    const surfaceBlockProperty =\n        surfaceBlock === 'START' ? 'inset-block-start' : 'inset-block-end';\n    const surfaceInlineProperty =\n        surfaceInline === 'START' ? 'inset-inline-start' : 'inset-inline-end';\n\n    this.surfaceStylesInternal = {\n      'display': 'block',\n      'opacity': '1',\n      [surfaceBlockProperty]: `${block}px`,\n      [surfaceInlineProperty]: `${inline}px`,\n    };\n\n    this.host.requestUpdate();\n  }\n\n  hostUpdate() {\n    this.onUpdate();\n  }\n\n  hostUpdated() {\n    this.onUpdate();\n  }\n\n  /**\n   * Checks whether the properties passed into the controller have changed since\n   * the last positioning. If so, it will reposition if the surface is open or\n   * close it if the surface should close.\n   */\n  private async onUpdate() {\n    const props = this.getProperties();\n    let hasChanged = false;\n    for (const [key, value] of Object.entries(props)) {\n      // tslint:disable-next-line\n      hasChanged = hasChanged || (value !== (this.lastValues as any)[key]);\n      if (hasChanged) break;\n    }\n\n    const openChanged = this.lastValues.isOpen !== props.isOpen;\n    const hasAnchor = !!props.anchorEl;\n    const hasSurface = !!props.surfaceEl;\n\n    if (hasChanged && hasAnchor && hasSurface) {\n      // Only update isOpen, because if it's closed, we do not want to waste\n      // time on a useless reposition calculation. So save the other \"dirty\"\n      // values until next time it opens.\n      this.lastValues.isOpen = props.isOpen;\n\n      if (props.isOpen) {\n        // We are going to do a reposition, so save the prop values for future\n        // dirty checking.\n        this.lastValues = props;\n\n        await this.position();\n        props.onOpen();\n      } else if (openChanged) {\n        await props.beforeClose();\n        this.close();\n        props.onClose();\n      }\n    }\n  }\n\n  /**\n   * Hides the surface.\n   */\n  private close() {\n    this.surfaceStylesInternal = {\n      'display': 'none',\n    };\n    this.host.requestUpdate();\n  }\n}\n"]}

package/menu/lib/typeaheadController.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MenuItem } from './shared.js';
+/**
+ * The options that are passed to the typeahead controller.
+ */
+export interface TypeaheadControllerProperties {
+    /**
+     * A function that returns an array of menu items to be searched.
+     * @return An array of menu items to be searched by typing.
+     */
+    getItems: () => MenuItem[];
+    /**
+     * The maximum time between each keystroke to keep the current type buffer
+     * alive.
+     */
+    typeaheadBufferTime: number;
+    /**
+     * Whether or not the typeahead should listen for keystrokes or not.
+     */
+    active: boolean;
+}
+/**
+ * Data structure tuple that helps with indexing.
+ *
+ * [index, item, normalized header text]
+ */
+type TypeaheadRecord = [number, MenuItem, string];
+/**
+ * Indicies to access the TypeaheadRecord tuple type.
+ */
+export declare const TYPEAHEAD_RECORD: {
+    readonly INDEX: 0;
+    readonly ITEM: 1;
+    readonly TEXT: 2;
+};
+/**
+ * This controller listens to `keydown` events and searches the header text of
+ * an array of `MenuItem`s with the corresponding entered keys within the buffer
+ * time and activates the item.
+ *
+ * @example
+ * ```ts
+ * const typeaheadController = new TypeaheadController(() => ({
+ *   typeaheadBufferTime: 50,
+ *   getItems: () => Array.from(document.querySelectorAll('md-menu-item'))
+ * }));
+ * html`
+ *   <div
+ *       @keydown=${typeaheadController.onKeydown}
+ *       tabindex="0"
+ *       class="activeItemText">
+ *     <!-- focusable element that will receive keydown events -->
+ *     Apple
+ *   </div>
+ *   <div>
+ *     <md-menu-item active header="Apple"></md-menu-item>
+ *     <md-menu-item header="Apricot"></md-menu-item>
+ *     <md-menu-item header="Banana"></md-menu-item>
+ *     <md-menu-item header="Olive"></md-menu-item>
+ *     <md-menu-item header="Orange"></md-menu-item>
+ *   </div>
+ * `;
+ * ```
+ */
+export declare class TypeaheadController {
+    private readonly getProperties;
+    /**
+     * Array of tuples that helps with indexing.
+     */
+    private typeaheadRecords;
+    /**
+     * Currently-typed text since last buffer timeout
+     */
+    private typaheadBuffer;
+    /**
+     * The timeout id from the current buffer's setTimeout
+     */
+    private cancelTypeaheadTimeout;
+    /**
+     * If we are currently "typing"
+     */
+    isTypingAhead: boolean;
+    /**
+     * The record of the last active item.
+     */
+    lastActiveRecord: TypeaheadRecord | null;
+    /**
+     * @param getProperties A function that returns the options of the typeahead
+     * controller:
+     *
+     * {
+     *   getItems: A function that returns an array of menu items to be searched.
+     *   typeaheadBufferTime: The maximum time between each keystroke to keep the
+     *       current type buffer alive.
+     * }
+     */
+    constructor(getProperties: () => TypeaheadControllerProperties);
+    private get items();
+    private get active();
+    /**
+     * Apply this listener to the element that will receive `keydown` events that
+     * should trigger this controller.
+     *
+     * @param e The native browser `KeyboardEvent` from the `keydown` event.
+     */
+    readonly onKeydown: (e: KeyboardEvent) => void;
+    /**
+     * Sets up typingahead
+     */
+    private beginTypeahead;
+    /**
+     * Performs the typeahead. Based on the normalized items and the current text
+     * buffer, finds the _next_ item with matching text and activates it.
+     *
+     * @example
+     *
+     * items: Apple, Banana, Olive, Orange, Cucumber
+     * buffer: ''
+     * user types: o
+     *
+     * activates Olive
+     *
+     * @example
+     *
+     * items: Apple, Banana, Olive (active), Orange, Cucumber
+     * buffer: 'o'
+     * user types: l
+     *
+     * activates Olive
+     *
+     * @example
+     *
+     * items: Apple, Banana, Olive (active), Orange, Cucumber
+     * buffer: ''
+     * user types: o
+     *
+     * activates Orange
+     *
+     * @example
+     *
+     * items: Apple, Banana, Olive, Orange (active), Cucumber
+     * buffer: ''
+     * user types: o
+     *
+     * activates Olive
+     */
+    private typeahead;
+    /**
+     * Ends the current typeahead and clears the buffer.
+     */
+    private readonly endTypeahead;
+}
+export {};