@material/web 1.0.0-pre.8 → 1.0.0

package/menu/internal/controllers/shared.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LitElement } from 'lit';
+import { MenuItem } from './menuItemController.js';
+import type { Corner, SurfacePositionTarget } from './surfacePositionController.js';
+/**
+ * The interface needed for a Menu to work with other md-menu elements.
+ */
+export interface MenuSelf {
+    /**
+     * Whether or not the menu is currently opened.
+     */
+    open: boolean;
+    /**
+     * Skips the opening and closing animations.
+     */
+    quick: boolean;
+    /**
+     * Displays overflow content like a submenu.
+     *
+     * __NOTE__: This may cause adverse effects if you set
+     * `md-menu {max-height:...}`
+     * and have items overflowing items in the "y" direction.
+     */
+    hasOverflow: boolean;
+    /**
+     * Communicates to the menu that it is a submenu and should not handle the
+     * ArrowLeft button in LTR and ArrowRight button in RTL.
+     */
+    isSubmenu: boolean;
+    /**
+     * After closing, does not restore focus to the last focused element before
+     * the menu was opened.
+     */
+    skipRestoreFocus: boolean;
+    /**
+     * The corner of the anchor in which the menu should anchor to.
+     */
+    anchorCorner: Corner;
+    /**
+     * The corner of the menu in which the menu should anchor from.
+     */
+    menuCorner: Corner;
+    /**
+     * The element the menu should anchor to.
+     */
+    anchorElement: (HTMLElement & Partial<SurfacePositionTarget>) | null;
+    /**
+     * What the menu should focus by default when opened.
+     */
+    defaultFocus: FocusState;
+    /**
+     * An array of items managed by the list.
+     */
+    items: MenuItem[];
+    /**
+     * Opens the menu.
+     */
+    show: () => void;
+    /**
+     * Closes the menu.
+     */
+    close: () => void;
+}
+/**
+ * The interface needed for a Menu to work with other md-menu elements. Useful
+ * for keeping your types safe when wrapping `md-menu`.
+ */
+export type Menu = MenuSelf & LitElement;
+/**
+ * The reason the `close-menu` event was dispatched.
+ */
+export interface Reason {
+    kind: string;
+}
+/**
+ * The click selection reason for the `close-menu` event. The menu was closed
+ * because an item was selected via user click.
+ */
+export interface ClickReason extends Reason {
+    kind: typeof CloseReason.CLICK_SELECTION;
+}
+/**
+ * The keydown reason for the `close-menu` event. The menu was closed
+ * because a specific key was pressed. The default closing keys for
+ * `md-menu-item` are, Space, Enter or Escape.
+ */
+export interface KeydownReason extends Reason {
+    kind: typeof CloseReason.KEYDOWN;
+    key: string;
+}
+/**
+ * The default menu closing reasons for the material md-menu package.
+ */
+export type DefaultReasons = ClickReason | KeydownReason;
+/**
+ * Creates an event that closes any parent menus.
+ */
+export declare function createCloseMenuEvent<T extends Reason = DefaultReasons>(initiator: MenuItem, reason: T): CustomEvent<{
+    initiator: MenuItem;
+    itemPath: MenuItem[];
+    reason: T;
+}>;
+/**
+ * Creates an event that signals to the menu that it should stay open on the
+ * focusout event.
+ */
+export declare function createStayOpenOnFocusoutEvent(): Event;
+/**
+ * Creates an event that signals to the menu that it should close open on the
+ * focusout event.
+ */
+export declare function createCloseOnFocusoutEvent(): Event;
+/**
+ * Creates a default close menu event used by md-menu.
+ */
+export declare const createDefaultCloseMenuEvent: (initiator: MenuItem, reason: DefaultReasons) => CustomEvent<{
+    initiator: MenuItem;
+    itemPath: MenuItem[];
+    reason: DefaultReasons;
+}>;
+/**
+ * The type of the default close menu event used by md-menu.
+ */
+export type CloseMenuEvent<T extends Reason = DefaultReasons> = ReturnType<typeof createCloseMenuEvent<T>>;
+/**
+ * Creates an event that requests the given item be selected.
+ */
+export declare function createDeactivateTypeaheadEvent(): Event;
+/**
+ * The type of the event that requests the typeahead functionality of containing
+ * menu be deactivated.
+ */
+export type DeactivateTypeaheadEvent = ReturnType<typeof createDeactivateTypeaheadEvent>;
+/**
+ * Creates an event that requests the typeahead functionality of containing menu
+ * be activated.
+ */
+export declare function createActivateTypeaheadEvent(): Event;
+/**
+ * The type of the event that requests the typeahead functionality of containing
+ * menu be activated.
+ */
+export type ActivateTypeaheadEvent = ReturnType<typeof createActivateTypeaheadEvent>;
+/**
+ * Keys that are used to navigate menus.
+ */
+export declare const NavigableKey: {
+    readonly UP: "ArrowUp";
+    readonly DOWN: "ArrowDown";
+    readonly RIGHT: "ArrowRight";
+    readonly LEFT: "ArrowLeft";
+};
+/**
+ * Keys that are used for selection in menus.
+ */
+export declare const SelectionKey: {
+    readonly SPACE: "Space";
+    readonly ENTER: "Enter";
+};
+/**
+ * Default close `Reason` kind values.
+ */
+export declare const CloseReason: {
+    readonly CLICK_SELECTION: "click-selection";
+    readonly KEYDOWN: "keydown";
+};
+/**
+ * Keys that can close menus.
+ */
+export declare const KeydownCloseKey: {
+    readonly ESCAPE: "Escape";
+    readonly SPACE: "Space";
+    readonly ENTER: "Enter";
+};
+type Values<T> = T[keyof T];
+/**
+ * Determines whether the given key code is a key code that should close the
+ * menu.
+ *
+ * @param code The KeyboardEvent code to check.
+ * @return Whether or not the key code is in the predetermined list to close the
+ * menu.
+ */
+export declare function isClosableKey(code: string): code is Values<typeof KeydownCloseKey>;
+/**
+ * Determines whether the given key code is a key code that should select a menu
+ * item.
+ *
+ * @param code They KeyboardEvent code to check.
+ * @return Whether or not the key code is in the predetermined list to select a
+ * menu item.
+ */
+export declare function isSelectableKey(code: string): code is Values<typeof SelectionKey>;
+/**
+ * Determines whether a target element is contained inside another element's
+ * composed tree.
+ *
+ * @param target The potential contained element.
+ * @param container The potential containing element of the target.
+ * @returns Whether the target element is contained inside the container's
+ * composed subtree
+ */
+export declare function isElementInSubtree(target: EventTarget, container: EventTarget): boolean;
+/**
+ * Element to focus on when menu is first opened.
+ */
+export declare const FocusState: {
+    readonly NONE: "none";
+    readonly LIST_ROOT: "list-root";
+    readonly FIRST_ITEM: "first-item";
+    readonly LAST_ITEM: "last-item";
+};
+/**
+ * Element to focus on when menu is first opened.
+ */
+export type FocusState = typeof FocusState[keyof typeof FocusState];
+export {};

package/menu/internal/controllers/shared.js

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Creates an event that closes any parent menus.
+ */
+export function createCloseMenuEvent(initiator, reason) {
+    return new CustomEvent('close-menu', {
+        bubbles: true,
+        composed: true,
+        detail: { initiator, reason, itemPath: [initiator] }
+    });
+}
+/**
+ * Creates an event that signals to the menu that it should stay open on the
+ * focusout event.
+ */
+export function createStayOpenOnFocusoutEvent() {
+    return new Event('stay-open-on-focusout', { bubbles: true, composed: true });
+}
+/**
+ * Creates an event that signals to the menu that it should close open on the
+ * focusout event.
+ */
+export function createCloseOnFocusoutEvent() {
+    return new Event('close-on-focusout', { bubbles: true, composed: true });
+}
+/**
+ * Creates a default close menu event used by md-menu.
+ */
+export const createDefaultCloseMenuEvent = (createCloseMenuEvent);
+/**
+ * Creates an event that requests the given item be selected.
+ */
+export function createDeactivateTypeaheadEvent() {
+    return new Event('deactivate-typeahead', { bubbles: true, composed: true });
+}
+/**
+ * Creates an event that requests the typeahead functionality of containing menu
+ * be activated.
+ */
+export function createActivateTypeaheadEvent() {
+    return new Event('activate-typeahead', { bubbles: true, composed: true });
+}
+/**
+ * Keys that are used to navigate menus.
+ */
+// tslint:disable-next-line:enforce-name-casing We are mimicking enum style
+export const NavigableKey = {
+    UP: 'ArrowUp',
+    DOWN: 'ArrowDown',
+    RIGHT: 'ArrowRight',
+    LEFT: 'ArrowLeft',
+};
+/**
+ * Keys that are used for selection in menus.
+ */
+// tslint:disable-next-line:enforce-name-casing We are mimicking enum style
+export const SelectionKey = {
+    SPACE: 'Space',
+    ENTER: 'Enter',
+};
+/**
+ * Default close `Reason` kind values.
+ */
+// tslint:disable-next-line:enforce-name-casing We are mimicking enum style
+export const CloseReason = {
+    CLICK_SELECTION: 'click-selection',
+    KEYDOWN: 'keydown',
+};
+/**
+ * Keys that can close menus.
+ */
+// tslint:disable-next-line:enforce-name-casing We are mimicking enum style
+export const KeydownCloseKey = {
+    ESCAPE: 'Escape',
+    SPACE: SelectionKey.SPACE,
+    ENTER: SelectionKey.ENTER,
+};
+/**
+ * Determines whether the given key code is a key code that should close the
+ * menu.
+ *
+ * @param code The KeyboardEvent code to check.
+ * @return Whether or not the key code is in the predetermined list to close the
+ * menu.
+ */
+export function isClosableKey(code) {
+    return Object.values(KeydownCloseKey).some(value => (value === code));
+}
+/**
+ * Determines whether the given key code is a key code that should select a menu
+ * item.
+ *
+ * @param code They KeyboardEvent code to check.
+ * @return Whether or not the key code is in the predetermined list to select a
+ * menu item.
+ */
+export function isSelectableKey(code) {
+    return Object.values(SelectionKey).some(value => (value === code));
+}
+/**
+ * Determines whether a target element is contained inside another element's
+ * composed tree.
+ *
+ * @param target The potential contained element.
+ * @param container The potential containing element of the target.
+ * @returns Whether the target element is contained inside the container's
+ * composed subtree
+ */
+export function isElementInSubtree(target, container) {
+    // Dispatch a composed, bubbling event to check its path to see if the
+    // newly-focused element is contained in container's subtree
+    const focusEv = new Event('md-contains', { bubbles: true, composed: true });
+    let composedPath = [];
+    const listener = (ev) => {
+        composedPath = ev.composedPath();
+    };
+    container.addEventListener('md-contains', listener);
+    target.dispatchEvent(focusEv);
+    container.removeEventListener('md-contains', listener);
+    const isContained = composedPath.length > 0;
+    return isContained;
+}
+/**
+ * Element to focus on when menu is first opened.
+ */
+// tslint:disable-next-line:enforce-name-casing We are mimicking enum style
+export const FocusState = {
+    NONE: 'none',
+    LIST_ROOT: 'list-root',
+    FIRST_ITEM: 'first-item',
+    LAST_ITEM: 'last-item'
+};
+//# sourceMappingURL=shared.js.map

package/menu/internal/controllers/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["shared.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 {LitElement} from 'lit';\n\nimport {MenuItem} from './menuItemController.js';\nimport type {Corner, SurfacePositionTarget} from './surfacePositionController.js';\n\n/**\n * The interface needed for a Menu to work with other md-menu elements.\n */\nexport interface MenuSelf {\n  /**\n   * Whether or not the menu is currently opened.\n   */\n  open: boolean;\n  /**\n   * Skips the opening and closing animations.\n   */\n  quick: boolean;\n  /**\n   * Displays overflow content like a submenu.\n   *\n   * __NOTE__: This may cause adverse effects if you set\n   * `md-menu {max-height:...}`\n   * and have items overflowing items in the \"y\" direction.\n   */\n  hasOverflow: boolean;\n  /**\n   * Communicates to the menu that it is a submenu and should not handle the\n   * ArrowLeft button in LTR and ArrowRight button in RTL.\n   */\n  isSubmenu: boolean;\n  /**\n   * After closing, does not restore focus to the last focused element before\n   * the menu was opened.\n   */\n  skipRestoreFocus: boolean;\n  /**\n   * The corner of the anchor in which the menu should anchor to.\n   */\n  anchorCorner: Corner;\n  /**\n   * The corner of the menu in which the menu should anchor from.\n   */\n  menuCorner: Corner;\n  /**\n   * The element the menu should anchor to.\n   */\n  anchorElement: (HTMLElement&Partial<SurfacePositionTarget>)|null;\n  /**\n   * What the menu should focus by default when opened.\n   */\n  defaultFocus: FocusState;\n  /**\n   * An array of items managed by the list.\n   */\n  items: MenuItem[];\n  /**\n   * Opens the menu.\n   */\n  show: () => void;\n  /**\n   * Closes the menu.\n   */\n  close: () => void;\n}\n\n/**\n * The interface needed for a Menu to work with other md-menu elements. Useful\n * for keeping your types safe when wrapping `md-menu`.\n */\nexport type Menu = MenuSelf&LitElement;\n\n/**\n * The reason the `close-menu` event was dispatched.\n */\nexport interface Reason {\n  kind: string;\n}\n\n/**\n * The click selection reason for the `close-menu` event. The menu was closed\n * because an item was selected via user click.\n */\nexport interface ClickReason extends Reason {\n  kind: typeof CloseReason.CLICK_SELECTION;\n}\n\n/**\n * The keydown reason for the `close-menu` event. The menu was closed\n * because a specific key was pressed. The default closing keys for\n * `md-menu-item` are, Space, Enter or Escape.\n */\nexport interface KeydownReason extends Reason {\n  kind: typeof CloseReason.KEYDOWN;\n  key: string;\n}\n\n/**\n * The default menu closing reasons for the material md-menu package.\n */\nexport type DefaultReasons = ClickReason|KeydownReason;\n\n/**\n * Creates an event that closes any parent menus.\n */\nexport function createCloseMenuEvent<T extends Reason = DefaultReasons>(\n    initiator: MenuItem, reason: T) {\n  return new CustomEvent<\n      {initiator: MenuItem, itemPath: MenuItem[], reason: T}>('close-menu', {\n    bubbles: true,\n    composed: true,\n    detail: {initiator, reason, itemPath: [initiator]}\n  });\n}\n\n/**\n * Creates an event that signals to the menu that it should stay open on the\n * focusout event.\n */\nexport function createStayOpenOnFocusoutEvent() {\n  return new Event('stay-open-on-focusout', {bubbles: true, composed: true});\n}\n\n/**\n * Creates an event that signals to the menu that it should close open on the\n * focusout event.\n */\nexport function createCloseOnFocusoutEvent() {\n  return new Event('close-on-focusout', {bubbles: true, composed: true});\n}\n\n/**\n * Creates a default close menu event used by md-menu.\n */\nexport const createDefaultCloseMenuEvent = createCloseMenuEvent<DefaultReasons>;\n\n/**\n * The type of the default close menu event used by md-menu.\n */\n// tslint:disable-next-line\nexport type CloseMenuEvent<T extends Reason = DefaultReasons> =\n    ReturnType<typeof createCloseMenuEvent<T>>;\n\n/**\n * Creates an event that requests the given item be selected.\n */\nexport function createDeactivateTypeaheadEvent() {\n  return new Event('deactivate-typeahead', {bubbles: true, composed: true});\n}\n\n/**\n * The type of the event that requests the typeahead functionality of containing\n * menu be deactivated.\n */\nexport type DeactivateTypeaheadEvent =\n    ReturnType<typeof createDeactivateTypeaheadEvent>;\n\n/**\n * Creates an event that requests the typeahead functionality of containing menu\n * be activated.\n */\nexport function createActivateTypeaheadEvent() {\n  return new Event('activate-typeahead', {bubbles: true, composed: true});\n}\n\n/**\n * The type of the event that requests the typeahead functionality of containing\n * menu be activated.\n */\nexport type ActivateTypeaheadEvent =\n    ReturnType<typeof createActivateTypeaheadEvent>;\n\n/**\n * Keys that are used to navigate menus.\n */\n// tslint:disable-next-line:enforce-name-casing We are mimicking enum style\nexport const NavigableKey = {\n  UP: 'ArrowUp',\n  DOWN: 'ArrowDown',\n  RIGHT: 'ArrowRight',\n  LEFT: 'ArrowLeft',\n} as const;\n\n/**\n * Keys that are used for selection in menus.\n */\n// tslint:disable-next-line:enforce-name-casing We are mimicking enum style\nexport const SelectionKey = {\n  SPACE: 'Space',\n  ENTER: 'Enter',\n} as const;\n\n/**\n * Default close `Reason` kind values.\n */\n// tslint:disable-next-line:enforce-name-casing We are mimicking enum style\nexport const CloseReason = {\n  CLICK_SELECTION: 'click-selection',\n  KEYDOWN: 'keydown',\n} as const;\n\n/**\n * Keys that can close menus.\n */\n// tslint:disable-next-line:enforce-name-casing We are mimicking enum style\nexport const KeydownCloseKey = {\n  ESCAPE: 'Escape',\n  SPACE: SelectionKey.SPACE,\n  ENTER: SelectionKey.ENTER,\n} as const;\n\ntype Values<T> = T[keyof T];\n\n/**\n * Determines whether the given key code is a key code that should close the\n * menu.\n *\n * @param code The KeyboardEvent code to check.\n * @return Whether or not the key code is in the predetermined list to close the\n * menu.\n */\nexport function isClosableKey(code: string):\n    code is Values<typeof KeydownCloseKey> {\n  return Object.values(KeydownCloseKey).some(value => (value === code));\n}\n\n/**\n * Determines whether the given key code is a key code that should select a menu\n * item.\n *\n * @param code They KeyboardEvent code to check.\n * @return Whether or not the key code is in the predetermined list to select a\n * menu item.\n */\nexport function isSelectableKey(code: string):\n    code is Values<typeof SelectionKey> {\n  return Object.values(SelectionKey).some(value => (value === code));\n}\n\n/**\n * Determines whether a target element is contained inside another element's\n * composed tree.\n *\n * @param target The potential contained element.\n * @param container The potential containing element of the target.\n * @returns Whether the target element is contained inside the container's\n * composed subtree\n */\nexport function isElementInSubtree(\n    target: EventTarget, container: EventTarget) {\n  // Dispatch a composed, bubbling event to check its path to see if the\n  // newly-focused element is contained in container's subtree\n  const focusEv = new Event('md-contains', {bubbles: true, composed: true});\n  let composedPath: EventTarget[] = [];\n  const listener = (ev: Event) => {\n    composedPath = ev.composedPath();\n  };\n\n  container.addEventListener('md-contains', listener);\n  target.dispatchEvent(focusEv);\n  container.removeEventListener('md-contains', listener);\n\n  const isContained = composedPath.length > 0;\n  return isContained;\n}\n\n/**\n * Element to focus on when menu is first opened.\n */\n// tslint:disable-next-line:enforce-name-casing We are mimicking enum style\nexport const FocusState = {\n  NONE: 'none',\n  LIST_ROOT: 'list-root',\n  FIRST_ITEM: 'first-item',\n  LAST_ITEM: 'last-item'\n} as const;\n\n/**\n * Element to focus on when menu is first opened.\n */\nexport type FocusState = typeof FocusState[keyof typeof FocusState];"]}

package/menu/internal/controllers/surfacePositionController.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import { StyleInfo } from 'lit/directives/style-map.js';
+/**
+ * An enum of supported Menu corners
+ */
+export declare const Corner: {
+    readonly END_START: "end-start";
+    readonly END_END: "end-end";
+    readonly START_START: "start-start";
+    readonly START_END: "start-end";
+};
+/**
+ * A corner of a box in the standard logical property style of <block>_<inline>
+ */
+export type Corner = typeof Corner[keyof typeof Corner];
+/**
+ * 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 the positioning algorithim should calculate relative to the parent
+     * of the anchor element (absolute) or relative to the window (fixed).
+     *
+     * Examples for `position = 'fixed'`:
+     *
+     * - 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
+     */
+    positioning: 'absolute' | 'fixed';
+    /**
+     * 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;
+    /**
+     * The strategy to follow when repositioning the menu to stay inside the
+     * viewport. "move" will simply move the surface to stay in the viewport.
+     * "resize" will attempt to resize the surface.
+     *
+     * Both strategies will still attempt to flip the anchor and surface corners.
+     */
+    repositionStrategy: 'move' | 'resize';
+    /**
+     * 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>;
+    /**
+     * Calculates the css property, the inset, and the out of bounds correction
+     * for the surface in the block direction.
+     */
+    private calculateBlock;
+    /**
+     * Calculates the css property, the inset, and the out of bounds correction
+     * for the surface in the inline direction.
+     */
+    private calculateInline;
+    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;
+}