From e2d7fcbfc2a6fe4686f7841b3b0f9fc8cca4a607 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Tue, 5 Oct 2021 23:18:29 +0100 Subject: [PATCH] Add lots of docs to RED.popover --- .../editor-client/src/js/ui/common/popover.js | 124 ++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/packages/node_modules/@node-red/editor-client/src/js/ui/common/popover.js b/packages/node_modules/@node-red/editor-client/src/js/ui/common/popover.js index 17969061c..27a454dc6 100644 --- a/packages/node_modules/@node-red/editor-client/src/js/ui/common/popover.js +++ b/packages/node_modules/@node-red/editor-client/src/js/ui/common/popover.js @@ -13,6 +13,128 @@ * See the License for the specific language governing permissions and * limitations under the License. **/ +/* + * RED.popover.create(options) - create a popover callout box + * RED.popover.tooltip(target,content, action) - add a tooltip to an element + * RED.popover.menu(options) - create a dropdown menu + * RED.popover.panel(content) - create a dropdown container element + */ + + +/* + * RED.popover.create(options) + * + * options + * - target : DOM element - the element to target with the popover + * - direction : string - position of the popover relative to target + * 'top', 'right'(default), 'bottom', 'left', 'inset-[top,right,bottom,left]' + * - trigger : string - what triggers the popover to be displayed + * 'hover' - display when hovering the target + * 'click' - display when target is clicked + * 'modal' - hmm not sure, need to find where we use that mode + * - content : string|function - contents of the popover. If a string, handled + * as raw HTML, so take care. + * If a function, can return a String to be added + * as text (not HTML), or a DOM element to append + * - delay : object - sets show/hide delays after mouseover/out events + * { show: 750, hide: 50 } + * - autoClose : number - delay before closing the popover in some cases + * if trigger is click - delay after mouseout + * else if trigger not hover/modal - delay after showing + * - width : number - width of popover, default 'auto' + * - maxWidth : number - max width of popover, default 'auto' + * - size : string - scale of popover. 'default', 'small' + * - offset : number - px offset from target + * - tooltip : boolean - if true, clicking on popover closes it + * - class : string - optional css class to apply to popover + * - interactive : if trigger is 'hover' and this is set to true, allow the mouse + * to move over the popover without hiding it. + * + * Returns the popover object with the following properties/functions: + * properties: + * - element : DOM element - the popover dom element + * functions: + * - setContent(content) - change the popover content. This only works if the + * popover is not currently displayed. It does not + * change the content of a visible popover. + * - open(instant) - show the popover. If 'instant' is true, don't fade in + * - close(instant) - hide the popover. If 'instant' is true, don't fade out + * - move(options) - move the popover. The options parameter can take many + * of the options detailed above including: + * target,direction,content,width,offset + * Other settings probably won't work because we haven't needed to change them + */ + +/* + * RED.popover.tooltip(target,content, action) + * + * - target : DOM element - the element to apply the tooltip to + * - content : string - the text of the tooltip + * - action : string - *optional* the name of an Action this tooltip is tied to + * For example, it 'target' is a button that triggers a particular action. + * The tooltip will include the keyboard shortcut for the action + * if one is defined + * + */ + +/* + * RED.popover.menu(options) + * + * options + * - options : array - list of menu options - see below for format + * - width : number - width of the menu. Default: 'auto' + * - class : string - class to apply to the menu container + * - maxHeight : number - maximum height of menu before scrolling items. Default: none + * - onselect : function(item) - called when a menu item is selected, if that item doesn't + * have its own onselect function + * - onclose : function(cancelled) - called when the menu is closed + * - disposeOnClose : boolean - by default, the menu is discarded when it closes + * and mustbe rebuilt to redisplay. Setting this to 'false' + * keeps the menu on the DOM so it can be shown again. + * + * Menu Options array: + * [ + * label : string|DOM element - the label of the item. Can be custom DOM element + * onselect : function - called when the item is selected + * ] + * + * Returns the menu object with the following functions: + * + * - options([menuItems]) - if menuItems is undefined, returns the current items. + * otherwise, sets the current menu items + * - show(opts) - shows the menu. `opts` is an object of options. See RED.popover.panel.show(opts) + * for the full list of options. In most scenarios, this just needs: + * - target : DOM element - the element to display the menu below + * - hide(cancelled) - hide the menu + */ + +/* + * RED.popover.panel(content) + * Create a UI panel that can be displayed relative to any target element. + * Handles auto-closing when mouse clicks outside the panel + * + * - 'content' - DOM element to display in the panel + * + * Returns the panel object with the following functions: + * + * properties: + * - container : DOM element - the panel element + * + * functions: + * - show(opts) - show the panel. + * opts: + * - onclose : function - called when the panel closes + * - closeButton : DOM element - if the panel is closeable by a click of a button, + * by providing a reference to it here, we can + * handle the events properly to hide the panel + * - target : DOM element - the element to display the panel relative to + * - align : string - should the panel align to the left or right edge of target + * default: 'right' + * - offset : Array - px offset to apply from the target. [width, height] + * - dispose : boolean - whether the panel should be removed from DOM when hidden + * default: true + * - hide(dispose) - hide the panel. + */ RED.popover = (function() { var deltaSizes = { @@ -123,6 +245,8 @@ RED.popover = (function() { div.width(width); if (options.maxWidth) { div.css("max-width",options.maxWidth) + } else { + div.css("max-width", 'auto'); } var targetPos = target[0].getBoundingClientRect();