bm-core-ui 2.8.2 → 2.9.0

package/build/@types/index.d.ts

@@ -2828,7 +2828,7 @@ export class BMLayoutConstraintKind {
  * A constraint is a linear equation that takes the form of 
  * ```js
  * view2.attribute2 + constant
- * ``
+ * `` 
  * where the equals sign can be replaced with an inequality sign as needed.
  * Note that despite looking like an assignment statement, the constraint expression is a mathematical equation and the layout
  * system may choose to modify either side (or even both) of the equation to fulfill the constraint's requirements.
@@ -5046,7 +5046,7 @@ export class BMScrollView extends BMView {
 
 
 	/**
-	 * Invoked whenever the iScroll instance managing this scroll view's scrolling scrolls.
+	 * Invoked whenever the iScroll instance managing this scroll view's scrolling.
 	 *     
 	 */
 	private _iScrollDidScroll(): void;
@@ -7947,12 +7947,37 @@ export class BMMenuItem {
 	 */
 	readonly action?: (($0: BMMenuItem) => void) | null | undefined;
 
+	/**
+	 * An optional submenu that opens from this menu item.
+	 *     
+	 */
+	readonly submenu?: BMMenu | null | undefined;
+
+	/**
+	 * Whether this menu item is a separator.
+	 *     
+	 */
+	readonly isSeparator: boolean;
+
 	/**
 	 * Additional, arbitrary information associated with this menu item.
 	 *     
 	 */
 	userInfo?: any | null | undefined;
 
+	/**
+	 * Additional CSS classes to apply to this item's node.
+	 *     
+	 */
+	CSSClass?: string | null | undefined;
+
+	/**
+	 * The node that represents this menu item, available while its menu
+	 * is open.
+	 *     
+	 */
+	private _node?: DOMNode | null | undefined;
+
 	/**
 	 * Constructs and returns a menu item with the given name.
 	 * Optionally, the menu item may have an icon associated with it as well as an
@@ -7963,11 +7988,12 @@ export class BMMenuItem {
 	 * 
 	 * @param action    If specified, this is a function that will be invoked when this menu item is selected.
 	 *                                                  This function will receive the selected menu item as a parameter.
+	 * @param submenu                Optional. If specified, this represents a menu that opens from this menu item.
 	 * @param userInfo            Optional. If specified, this represents additional arbitrary data attached to this menu item.
 	 * @return                              This menu item.
 	 *     
 	 */
-	initWithName(name: string, {icon: icon, action: action, userInfo: userInfo}?: {icon?: string | null | undefined, action?: (($0: BMMenuItem) => void) | null | undefined, userInfo?: any | null | undefined}): BMMenuItem;
+	initWithName(name: string, {icon: icon, action: action, submenu: submenu, userInfo: userInfo}?: {icon?: string | null | undefined, action?: (($0: BMMenuItem) => void) | null | undefined, submenu?: BMMenu | null | undefined, userInfo?: any | null | undefined}): BMMenuItem;
 
 
 	/**
@@ -7980,10 +8006,12 @@ export class BMMenuItem {
 	 * 
 	 * @param action    If specified, this is a function that will be invoked when this menu item is selected.
 	 *                                                  This function will receive the selected menu item as a parameter.
+	 * @param submenu                Optional. If specified, this represents a menu that opens from this menu item.
+	 * @param userInfo            Optional. If specified, this represents additional arbitrary data attached to this menu item.
 	 * @return                              A menu item.
 	 * 
 	 */
-	static menuItemWithName (name: string, {icon: icon, action: action}?: {icon?: string | null | undefined, action?: (($0: BMMenuItem) => void) | null | undefined}): BMMenuItem;
+	static menuItemWithName (name: string, {icon: icon, action: action, submenu: submenu, userInfo: userInfo}?: {icon?: string | null | undefined, action?: (($0: BMMenuItem) => void) | null | undefined, submenu?: BMMenu | null | undefined, userInfo?: any | null | undefined}): BMMenuItem;
 
 
 	/**
@@ -8022,7 +8050,6 @@ export class BMMenu {
 
 	/**
 	 * A custom list of CSS classes to add to the menu DOM node.
-	 * This only has effect when set before the menu is opened.
 	 *     
 	 */
 	CSSClass: string;
@@ -8064,16 +8091,54 @@ export class BMMenu {
 	private _sourceNodeDisplacement?: number | null | undefined;
 
 	/**
-	 * The index of the currently highlighted menu item.
+	 * The source node horizontal displacement, used while the menu is visible.
 	 *     
 	 */
-	private _highlightedIndex: number;
+	private _sourceNodeHorizontalDisplacement?: number | null | undefined;
 
 	/**
 	 * The DOM node that was focused when this alert was opened.
 	 *     
 	 */
-	private readonly _previouslyActiveNode: any;
+	private _previouslyActiveNode: DOMNode;
+
+	/**
+	 * The submenu currently displayed, if any.
+	 *     
+	 */
+	private _submenu?: BMMenu | null | undefined;
+
+	/**
+	 * The menu that opened this menu, if any.
+	 *     
+	 */
+	private _supermenu?: BMMenu | null | undefined;
+
+	/**
+	 * The menu's frame, relative to the viewport, available while this menu is visible.
+	 *     
+	 */
+	readonly frame?: BMRect | null | undefined;
+
+	/**
+	 * The index of the currently highlighted menu item.
+	 *     
+	 */
+	highlightedIndex: number;
+
+	/**
+	 * Set to `YES` while delaying events due to a submenu having
+	 * been recently activated.
+	 *     
+	 */
+	private _delaysEvents: boolean;
+
+	/**
+	 * Controls whether the closing animation should be delayed to allow time
+	 * for the selection animation to play on the selected menu item.
+	 *     
+	 */
+	_delaysClosing: boolean;
 
 	/**
 	 * Initializes this menu with the specified items.
@@ -8094,6 +8159,16 @@ export class BMMenu {
 	private _renderMenu(): void;
 
 
+	/**
+	 * Invoked by CoreUI to build the menu node, in the specified container.
+	 * @param container      The container node in which to render the menu.
+	 *                                          If not specified, a new container will be created
+	 *                                          for this menu.
+	 *     
+	 */
+	private _renderMenuWithContainer(container?: DOMNode | null | undefined): void;
+
+
 	/**
 	 * Invoked by CoreUI to build the menu item nodes displayed by this menu.
 	 *     
@@ -8135,13 +8210,53 @@ export class BMMenu {
 
 
 	/**
-	 * Animatable. Dismisses this menu, if it is visible.
-	 * @param animated       Defaults to `NO`. If set to `YES`, this change will be animated.
+	 * Shows this menu at an appropriate position around the given rect. The coordinates of this rect
+	 * are relative to the viewport.
+	 * @param rect                      The rect around which to show this menu.
+	 * @param animated      Defaults to `NO`. If set to `YES`, this change will be animated.
 	 *                                          If this method is invoked from within an animation context, the value of this parameter is ignored
 	 *                                          and the values of the current animation context are used.
+	 * 
+	 * @param kind       Defaults to `Menu`. The kind of menu.
+	 *     
+	 */
+	private _openAroundRect(rect: BMRect, {animated: animated, kind: kind}?: {animated?: boolean | null | undefined, kind?: BMMenuKind | null | undefined}): void;
+
+
+	/**
+	 * Opens the submenu for the given menu item.
+	 * @param item                      The item whose submenu should be opened.
+	 * @param animated          Defaults to `YES`. If set to `YES` this change will be animated.
+	 * @param delaysEvents      Defaults to `NO`. If set to `YES`, mouse events on the current menu will be
+	 *                                              temporarily suspended, allowing the pointer to move over other menu items
+	 *                                              without closing the submenu.
+	 * @param acquireFocus      Defaults to `NO`. If set to `YES`, the submenu will acquire keyboard focus upon
+	 *                                              opening. Otherwise, this menu will retain keyboard focus.
 	 *     
 	 */
-	closeAnimated(animated?: boolean | null | undefined): void;
+	private _openSubmenuForMenuItem(item: BMMenuItem, {animated: animated, delaysEvents: delaysEvents, acquireFocus: acquireFocus}?: {animated?: boolean | null | undefined, delaysEvents?: boolean | null | undefined, acquireFocus?: boolean | null | undefined}): void;
+
+
+	/**
+	 * Temporarily prevents menu items from being highlighted, while the mouse
+	 * pointer moves towards the specified submenu.
+	 * @param submenu           The submenu for which to delay events.
+	 * @param item         The item from which the submenu opened.
+	 *     
+	 */
+	private _delayEventsForSubmenu(submenu: BMMenu, {item: item}: {item: BMMenuItem}): void;
+
+
+	/**
+	 * Dismisses this menu, if it is visible.
+	 * @param animated           Defaults to `YES`. If set to `YES`, this change will be animated.
+	 *                                              If this method is invoked from within an animation context, the value of this parameter is ignored
+	 *                                              and the values of the current animation context are used.
+	 * @param withSupermenu     Defaults to `NO`. If set to `YES` and this menu is displayed as a submenu, its supermenus
+	 *                                              will also close.
+	 *     
+	 */
+	closeAnimated(animated?: boolean | null | undefined, {withSupermenu: withSupermenu}?: {withSupermenu?: boolean | null | undefined}): void;
 
 
 	/**
@@ -8160,6 +8275,30 @@ export class BMMenu {
 	arrowDownPressedWithEvent(event: KeyboardEvent): void;
 
 
+	/**
+	 * Invoked when the right arrow is pressed.
+	 * @param event      The event that triggered this action.
+	 *     
+	 */
+	arrowRightPressedWithEvent(event: KeyboardEvent): void;
+
+
+	/**
+	 * Invoked when the left arrow is pressed.
+	 * @param event      The event that triggered this action.
+	 *     
+	 */
+	arrowLeftPressedWithEvent(event: KeyboardEvent): void;
+
+
+	/**
+	 * Invoked when the return or spacebar key is pressed.
+	 * @param event      The event that triggered this action.
+	 *     
+	 */
+	returnPressedWithEvent(event: KeyboardEvent): void;
+
+
 	/**
 	 * Invoked when the tab key is pressed.
 	 * @param event      The event that triggered this action.
@@ -8191,7 +8330,69 @@ export class BMMenu {
 
 
 /**
- * The specification for a `BMTextField` object, which can optionally be used in conjunction with `BMTextField` objects and will receive various
+ * The specification for a `BMMenuDelegate` object, which can optionally be used in conjunction with `BMTextField` objects and will receive various
+ * callbacks related to the text field's lifecycle.
+ * 
+ */
+export interface BMMenuDelegate {
+
+	/**
+	 * Invoked by menus when they are about to be opened. This method is invoked before
+	 * any associated animation runs and before the actual content is rendered.
+	 * @param menu      The calling menu.
+	 *     
+	 */
+	menuWillOpen?(menu: BMMenu): void;
+
+
+	/**
+	 * Invoked by menus when they are about to be closed. This method is invoked before
+	 * any associated animation runs.
+	 * @param menu      The calling menu.
+	 *     
+	 */
+	menuWillClose?(menu: BMMenu): void;
+
+
+	/**
+	 * Invoked by menus after they are closed. This method is invoked after
+	 * any associated animation runs and after their contents are removed from the document.
+	 * @param menu      The calling menu.
+	 *     
+	 */
+	menuDidClose?(menu: BMMenu): void;
+
+
+	/**
+	 * Invoked by menus whenever a menu item is about to be selected.
+	 * Delegates can implement this method to control whether the manu item may be selected or not.
+	 * 
+	 * Returning `YES` from this method will cause the item to be selected and the menu to close.
+	 * Returning `NO` from this method will prevent the menu item from being selected and the menu will not close.
+	 * 
+	 * If this method is not implemented, all menu items may be selected.
+	 * 
+	 * @param menu          The menu on which the item is about to be selected.
+	 * @param item      The menu item that is about to be selected.
+	 * @return            `YES` if the menu item should be selected, `NO` otherwise.
+	 *     
+	 */
+	menuShouldSelectItem?(menu: BMMenu, item: BMMenuItem): boolean;
+
+
+	/**
+	 * Invoked by menus whenever a menu item has been selected.
+	 * @param menu          The menu on which the item was selected.
+	 * @param item      The menu item that was selected.
+	 *     
+	 */
+	menuDidSelectItem?(menu: BMMenu, item: BMMenuItem): void;
+
+}
+
+
+/**
+ * The specification for a `BMTextFieldDelegate` object, which can optionally be used in conjunction with `BMTextField` objects and will receive various
  * callbacks related to the text field's lifecycle.
  * 
  */
@@ -8204,7 +8405,7 @@ export interface BMTextFieldDelegate {
 	 * 
 	 * If this method is not implemented, suggestions and autocomplete will not be available.
 	 * @param textField 		The calling text field.
-	 * @param text                  
+	 * @param text                  The text for which to obtain suggestions.
 	 * @return                    An array of string suggestions.
 	 *  
 	 */
@@ -8240,7 +8441,7 @@ export interface BMTextFieldDelegate {
 	/**
 	 * Invoked whenever the contents in this text field change for any reason. This can be because of an input event,
 	 * the user pasting text or a suggestion being selected.
-	 * Note that this method will not be invoked when manually setting the input node's `value`.
+	 * Note that this method will not be invoked when programatically setting the input node's `value`.
 	 * 
 	 * Delegate objects can implement this method in place of standard event listeners to handle changes to this text field.
 	 * The contents of the text field can be retrieved via the standard `value` property on the text field's node.
@@ -8253,9 +8454,9 @@ export interface BMTextFieldDelegate {
 	/**
 	 * Invoked whenever the user presses the return key while the text field has keyboard focus.
 	 * 
-	 * Delegate objects can implement this method to customize the behaviour when the user presses the return key and also control whether the default action will take place.
-	 * The default action for pressing the return key is to cause the text field to resign keyboard focus. If suggestions are used, the return key will also fill in the currently
-	 * highlighted suggestion.
+	 * Delegate objects can implement this method to customize the behaviour when the user presses the return key and also control 
+	 * whether the default action will take place. The default action for pressing the return key is to cause the text field to 
+	 * resign keyboard focus. If suggestions are used, the return key will also fill in the currently highlighted suggestion.
 	 * @param textField        The calling text field.
 	 * @return           Defaults to `YES`. If set to `YES`, the standard behaviour will be invoked.
 	 *     
@@ -9431,10 +9632,11 @@ export class BMCollectionViewLayout {
 	 * Layout objects should return YES from this method if the new bounds require a new layout.
 	 * The default implementation returns NO in all cases.
 	 * @param bounds        The new bounds.
+	 * @param fromBounds 	The previous bounds.
 	 * @return             True if the new frame requires a new layout, false otherwise.
 	 *     
 	 */
-	shouldInvalidateLayoutForBoundsChange(bounds: BMRect): boolean;
+	shouldInvalidateLayoutForBoundsChange(bounds: BMRect, {fromBounds: fromBounds}: {fromBounds: BMRect}): boolean;
 
 
 	/**
@@ -10171,10 +10373,14 @@ export class BMCollectionViewFlowLayout extends BMCollectionViewLayout {
 	 * When using automatic cell sizes, the generator will yield execution and only calculate portions of the layout on demand.
 	 * With the exeption of the first invocation, it is required to pass an index path to the iterator's `next` method. The layout process
 	 * will continue until it fully lays out the cell for that index path, at which point it will yield again.
-	 * @param useOffset 			When set to `YES` the layout will take the scrollbar size into account.
+	 * @param useOffset 							When set to `YES` the layout will take the scrollbar size into account.
+	 * @param targetRect 				When computing a layout using automatic cell sizes, this is an optional rect up to which
+	 * 														to measure cells. This is reserved for when this is invoked as a delegate.
+	 * @param targetIndexPath 		When computing a layout using automatic cell sizes, this is an optional index path up to which
+	 * 														to measure cells. This is reserved for when this is invoked as a delegate.
 	 *  
 	 */
-	*_prepareLayoutWithScrollbarOffsetGenerator(useOffset: boolean): void;
+	*_prepareLayoutWithScrollbarOffsetGenerator(useOffset: boolean, {targetRect: targetRect, targetIndexPath: targetIndexPath}?: {targetRect?: BMRect | null | undefined, targetIndexPath?: BMIndexPath | null | undefined}): void;
 
 
 	/**
@@ -12434,9 +12640,10 @@ export interface BMCollectionViewDelegate {
 	 * Invoked by the collection view whenever the bounds change.
 	 * @param collectionView 		The calling collection view.
 	 * @param newBounds 					The new bounds.
+	 * @param fromBounds 					The previous bounds.
 	 *  
 	 */
-	collectionViewBoundsDidChange?(collectionView: BMCollectionView, newBounds: BMRect): void;
+	collectionViewBoundsDidChange?(collectionView: BMCollectionView, newBounds: BMRect, {fromBounds: fromBounds}: {fromBounds: BMRect}): void;
 
 
 	/**
@@ -13363,6 +13570,14 @@ export class BMWindow extends BMView {
 	dismissAnimated(animated?: boolean | null | undefined, {toRect: toRect, toNode: toNode, completionHandler: completionHandler}?: {toRect?: BMRect | null | undefined, toNode?: DOMNode | null | undefined, completionHandler?: (() => void) | null | undefined}): void;
 
 
+	/**
+	 * Invoked after this window closes. Subclasses overriding this method must invoked
+	 * the superclass method at some point in their implementation.
+	 *  
+	 */
+	windowDidClose(): void;
+
+
 	/**
 	 * Minimizes this window. This method will raise an error if this window is modal.
 	 * If this window is already minimized, this method will have no effect.
@@ -13740,6 +13955,38 @@ export interface BMCodeEditorDelegate {
 }
 
 
+/**
+ * Constants describing the position where the indicator appears on its popover.
+ * 
+ */
+export class BMPopoverIndicatorDirection {
+	/**
+	 * Causes the popover indicator to appear on the top edge of the popover.
+	 *  
+	 */
+	static Top: BMPopoverIndicatorDirection;
+
+	/**
+	 * Causes the popover indicator to appear on the bottom edge of the popover.
+	 *  
+	 */
+	static Bottom: BMPopoverIndicatorDirection;
+
+	/**
+	 * Causes the popover indicator to appear on the left edge of the popover.
+	 *  
+	 */
+	static Left: BMPopoverIndicatorDirection;
+
+	/**
+	 * Causes the popover indicator to appear on the right edge of the popover.
+	 *  
+	 */
+	static Right: BMPopoverIndicatorDirection;
+
+	private constructor(); 
+}
+
 /**
  * The popover is a kind of window that is visually linked to a source element.
  * Unlike windows, popovers are always modal.
@@ -13870,12 +14117,31 @@ export class BMPopover extends BMWindow {
 	 */
 	private _contentViewBottomConstraint: BMLayoutConstraint;
 
+	/**
+	 * The content view's left edge constraint.
+	 *     
+	 */
+	private _contentViewLeftConstraint: BMLayoutConstraint;
+
+	/**
+	 * The content view's right edge constraint.
+	 *     
+	 */
+	private _contentViewRightConstraint: BMLayoutConstraint;
+
 	/**
 	 * The computed height of the indicator.
 	 *     
 	 */
 	readonly _indicatorHeight: number;
 
+	/**
+	 * An array that specifies the permitted indicator directions that this popover
+	 * may use and the priority in which they will be evaluated.
+	 *     
+	 */
+	permittedDirections: BMPopoverIndicatorDirection[];
+
 	/**
 	 * Designated initializer. Initializes this popover with the given size.
 	 * 
@@ -13895,21 +14161,45 @@ export class BMPopover extends BMWindow {
 	private _updatePosition(): void;
 
 
+	/**
+	 * Determines the direction that the popover should appear in order to fit best around the given point.
+	 * The popover will verify directions in the order specified by the `permittedDirections` property.
+	 * If none of the permitted indicator directions would fit the popover in the viewport, the first
+	 * specified direction is returned.
+	 * @param point                    The anchor point to check against.
+	 * @return     The direction that best fits.
+	 *     
+	 */
+	private _directionAroundPoint(point: BMPoint): BMPopoverIndicatorDirection;
+
+
+	/**
+	 * Determines the direction that the popover should appear in order to fit best around the given rect.
+	 * The popover will verify directions in the order specified by the `permittedDirections` property.
+	 * If none of the permitted indicator directions would fit the popover in the viewport, the first
+	 * specified direction is returned.
+	 * @param rect                      The anchor rect to check against.
+	 * @return     The direction that best fits.
+	 *     
+	 */
+	private _directionAroundRect(rect: BMRect): BMPopoverIndicatorDirection;
+
+
 	/**
 	 * Builds the SVG path definition for a popover with the given frame. Note that the indicator will be positioned inside the frame, which will push the usable
 	 * area of the frame downwards.
-	 * @param frame                             The popover's frame.
-	 * @param widthIndicatorSize     Defaults to `8`. The size of the popover's indicator.
-	 * @param radius                 Defaults to `4`. Controls how rounded the corners are.
-	 * @param inset                  Defaults to `0`. An optional inset to apply to the path.
-	 * @param knobPosition           Defaults to half of the frame's width. The position along the top frame on which to place the knob.
-	 *                                                  This coordinate is relative to the popover's frame and represents the center position of the knob.
-	 *                                                  This position should not overlap the specified corner radius.
-	 * @param gravity                Defaults to `"Top"`. If set to `"Bottom"`, the popover knob will be placed at the bottom of the popover.
+	 * @param frame                                         The popover's frame.
+	 * @param indicatorSize                      Defaults to `8`. The size of the popover's indicator.
+	 * @param radius                             Defaults to `4`. Controls how rounded the corners are.
+	 * @param inset                              Defaults to `0`. An optional inset to apply to the path.
+	 * @param position                           Defaults to half of the frame's width. The position along the edge of the frame on which to place the indicator.
+	 *                                                              This coordinate is relative to the popover's frame and represents the center position of the indicator.
+	 *                                                              This position should not overlap the specified corner radius.
+	 * @param direction     Defaults to `.Top`. Controls where the indicator will be placed relative to the popover.
 	 * @return                                  The SVG path.
 	 *     
 	 */
-	private _pathForPopoverWithFrame(frame: BMRect, {widthIndicatorSize: widthIndicatorSize, radius: radius, inset: inset, knobPosition: knobPosition, gravity: gravity}?: {widthIndicatorSize?: number | null | undefined, radius?: number | null | undefined, inset?: number | null | undefined, knobPosition?: number | null | undefined, gravity?: string | null | undefined}): string;
+	private _pathForPopoverWithFrame(frame: BMRect, {indicatorSize: indicatorSize, radius: radius, inset: inset, position: position, direction: direction}?: {indicatorSize?: number | null | undefined, radius?: number | null | undefined, inset?: number | null | undefined, position?: number | null | undefined, direction?: BMPopoverIndicatorDirection | null | undefined}): string;
 
 
 	/**
@@ -14013,7 +14303,13 @@ export class BMAlertPopup extends BMWindow {
 	 * The DOM node that was focused when this alert was opened.
 	 *     
 	 */
-	private readonly _previouslyActiveNode: any;
+	private _previouslyActiveNode: DOMNode;
+
+	/**
+	 * A handler that is invoked when the window resizes, used to reposition this window.
+	 *     
+	 */
+	private _centerHandler: (() => void);
 
 	/**
 	 * Designated initializer. Initializes this alert popup with the given labels.