Skip to content
Snippets Groups Projects
Verified Commit bbfef197 authored by Volker Schukai's avatar Volker Schukai :alien:
Browse files

doc: update docs

parent 70964340
No related branches found
No related tags found
No related merge requests found
...@@ -35,19 +35,20 @@ export { MessageStateButton }; ...@@ -35,19 +35,20 @@ export { MessageStateButton };
const buttonElementSymbol = Symbol("buttonElement"); const buttonElementSymbol = Symbol("buttonElement");
/** /**
* A select control that can be used to select one or more options from a list. * A specialized button component that combines state management with message display capabilities.
* It extends the Popper component to show messages in a popup overlay and can be used for form submissions
* or manual actions.
* *
* @fragments /fragments/components/form/message-state-button/ * @fragments /fragments/components/form/message-state-button/
*
* @example /examples/components/form/message-state-button-simple * @example /examples/components/form/message-state-button-simple
* *
* @since 2.11.0 * @since 2.11.0
* @copyright schukai GmbH * @copyright schukai GmbH
* @summary A beautiful select control that can make your life easier and also looks good. * @summary Button component with integrated message display and state management
* @fires monster-options-set * @fires monster-state-changed - Fired when button state changes
* @fires monster-selected * @fires monster-message-shown - Fired when message is displayed
* @fires monster-change * @fires monster-message-hidden - Fired when message is hidden
* @fires monster-changed * @fires monster-click - Fired when button is clicked
*/ */
class MessageStateButton extends Popper { class MessageStateButton extends Popper {
/** /**
...@@ -61,12 +62,12 @@ class MessageStateButton extends Popper { ...@@ -61,12 +62,12 @@ class MessageStateButton extends Popper {
} }
/** /**
* Sets the state of the button which affects its visual appearance
* *
* @param {string} state * @param {string} state - The state to set (e.g. 'success', 'error', 'loading')
* @param {number} timeout * @param {number} timeout - Optional timeout in milliseconds after which state is removed
* @return {MessageStateButton} * @return {MessageStateButton} Returns the button instance for chaining
* @throws {TypeError} value is not a string * @throws {TypeError} When state is not a string or timeout is not a number
* @throws {TypeError} value is not an instance
*/ */
setState(state, timeout) { setState(state, timeout) {
return this[buttonElementSymbol].setState(state, timeout); return this[buttonElementSymbol].setState(state, timeout);
...@@ -164,12 +165,13 @@ class MessageStateButton extends Popper { ...@@ -164,12 +165,13 @@ class MessageStateButton extends Popper {
} }
/** /**
* Sets the message * Sets the message content to be displayed in the popup overlay
* *
* @param {string|HTMLElement}message * @param {string|HTMLElement} message - The message content as string or HTML element
* @param {string} title * @param {string} title - Optional title to show above the message
* @param {string} icon * @param {string} icon - Optional icon HTML to display next to the title
* @return {MessageStateButton} * @return {MessageStateButton} Returns the button instance for chaining
* @throws {TypeError} When message is empty or invalid type
*/ */
setMessage(message, title, icon) { setMessage(message, title, icon) {
if (isString(message)) { if (isString(message)) {
...@@ -230,10 +232,10 @@ class MessageStateButton extends Popper { ...@@ -230,10 +232,10 @@ class MessageStateButton extends Popper {
} }
/** /**
* With this method you can show the popper with timeout feature. * Shows the message popup overlay with optional auto-hide timeout
* *
* @param {number} timeout * @param {number} timeout - Optional time in milliseconds after which the message will auto-hide
* @return {MessageStateButton} * @return {MessageStateButton} Returns the button instance for chaining
*/ */
showMessage(timeout) { showMessage(timeout) {
this.showDialog.call(this); this.showDialog.call(this);
...@@ -248,7 +250,7 @@ class MessageStateButton extends Popper { ...@@ -248,7 +250,7 @@ class MessageStateButton extends Popper {
} }
/** /**
* With this method you can show the popper. * With this method, you can show the popper.
* *
* @return {MessageStateButton} * @return {MessageStateButton}
*/ */
...@@ -306,10 +308,12 @@ class MessageStateButton extends Popper { ...@@ -306,10 +308,12 @@ class MessageStateButton extends Popper {
} }
/** /**
* The Button.click() method simulates a click on the internal button element. * Programmatically triggers a click event on the button
* Will not trigger if button is disabled
* *
* @since 3.27.0 * @since 3.27.0
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click} * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click}
* @fires monster-click
*/ */
click() { click() {
if (this.getOption("disabled") === true) { if (this.getOption("disabled") === true) {
......
...@@ -34,53 +34,60 @@ import { isArray } from "../../types/is.mjs"; ...@@ -34,53 +34,60 @@ import { isArray } from "../../types/is.mjs";
export {Popper}; export {Popper};
/** /**
* Symbol for timer callback reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const timerCallbackSymbol = Symbol("timerCallback"); const timerCallbackSymbol = Symbol("timerCallback");
/** /**
* local symbol * Symbol for resize observer reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const resizeObserverSymbol = Symbol("resizeObserver"); const resizeObserverSymbol = Symbol("resizeObserver");
/** /**
* local symbol * Symbol for close event handler reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const closeEventHandler = Symbol("closeEventHandler"); const closeEventHandler = Symbol("closeEventHandler");
/** /**
* Symbol for control element reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const controlElementSymbol = Symbol("controlElement"); const controlElementSymbol = Symbol("controlElement");
/** /**
* Symbol for button element reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const buttonElementSymbol = Symbol("buttonElement"); const buttonElementSymbol = Symbol("buttonElement");
/** /**
* local symbol * Symbol for popper element reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const popperElementSymbol = Symbol("popperElement"); const popperElementSymbol = Symbol("popperElement");
/** /**
* local symbol * Symbol for arrow element reference
* @private * @private
* @type {symbol} * @type {symbol}
*/ */
const arrowElementSymbol = Symbol("arrowElement"); const arrowElementSymbol = Symbol("arrowElement");
/** /**
* A Popper is a floating UI element that can be shown or hidden. * Popper component for displaying floating UI elements
*
* The Popper class creates a floating overlay element that can be shown/hidden
* and positioned relative to a trigger element. It supports different interaction
* modes like click, hover, focus etc.
* *
* @fragments /fragments/components/layout/popper/ * @fragments /fragments/components/layout/popper/
* *
...@@ -89,36 +96,34 @@ const arrowElementSymbol = Symbol("arrowElement"); ...@@ -89,36 +96,34 @@ const arrowElementSymbol = Symbol("arrowElement");
* *
* @since 1.65.0 * @since 1.65.0
* @copyright schukai GmbH * @copyright schukai GmbH
* @summary A beautiful popper that can make your life easier and also looks good. * @summary Floating overlay component with flexible positioning and interaction modes
* @fires monster-popper-hide fired when the popper is hide. * @fires monster-popper-hide - Fired when popper starts hiding
* @fires monster-popper-hidden fired when the popper is hidden. * @fires monster-popper-hidden - Fired when popper is fully hidden
* @fires monster-popper-open fired when the popper is open. * @fires monster-popper-open - Fired when popper starts opening
* @fires monster-popper-opened fired when the popper is opened. * @fires monster-popper-opened - Fired when popper is fully opened
*/ */
class Popper extends CustomElement { class Popper extends CustomElement {
/** /**
* This method is called by the `instanceof` operator. * Gets the instance symbol for type checking
* @return {symbol} * @return {symbol} The instance type symbol
*/ */
static get [instanceSymbol]() { static get [instanceSymbol]() {
return Symbol.for("@schukai/monster/components/layout/popper@@instance"); return Symbol.for("@schukai/monster/components/layout/popper@@instance");
} }
/** /**
* To set the options via the HTML tag, the attribute `data-monster-options` must be used. * Default configuration options for the popper
* @see {@link https://monsterjs.org/en/doc/#configurate-a-monster-control}
*
* The individual configuration values can be found in the table.
* *
* @property {Object} templates The templates for the control. * @property {Object} templates - Template configuration
* @property {string} templates.main The main template. * @property {string} templates.main - Main template HTML
* @property {string} mode The mode of the popper. Possible values are `click`, `enter`, `manual`, `focus`, "auto" or a combination of them. * @property {string} mode - Interaction mode(s): click|enter|manual|focus|auto
* @property {string} content The content of the popper. * @property {string} content - Content template
* @property {object} popper The popper options. * @property {Object} popper - Positioning options
* @property {string} popper.placement The placement of the popper. Possible values are `top`, `bottom`, `left` and `right`. * @property {string} popper.placement - Placement: top|bottom|left|right
* @property {function[]} popper.middleware The middleware functions of the popper. * @property {Array} popper.middleware - Positioning middleware functions
* @property {Object} features The features of the popper. * @property {Object} features - Feature flags
* @property {boolean} features.preventOpenEventSent Prevents the open event from being sent. * @property {boolean} features.preventOpenEventSent - Prevent open event
* @returns {Object} Default options merged with parent defaults
*/ */
get defaults() { get defaults() {
return Object.assign({}, super.defaults, { return Object.assign({}, super.defaults, {
...@@ -138,9 +143,9 @@ class Popper extends CustomElement { ...@@ -138,9 +143,9 @@ class Popper extends CustomElement {
} }
/** /**
* This method is called by the `connectedCallback` method on the first call. * Initialize the component
* * Called on first connection to DOM
* @return {void} * @private
*/ */
[assembleMethodSymbol]() { [assembleMethodSymbol]() {
super[assembleMethodSymbol](); super[assembleMethodSymbol]();
...@@ -149,27 +154,24 @@ class Popper extends CustomElement { ...@@ -149,27 +154,24 @@ class Popper extends CustomElement {
} }
/** /**
* This method returns the tag name of the element. * Gets the custom element tag name
* * @return {string} The tag name
* @return {string}
*/ */
static getTag() { static getTag() {
return "monster-popper"; return "monster-popper";
} }
/** /**
* This method returns the css styles of the element. * Gets component stylesheets
* * @return {CSSStyleSheet[]} Array of stylesheets
* @return {CSSStyleSheet[]}
*/ */
static getCSSStyleSheet() { static getCSSStyleSheet() {
return [PopperStyleSheet]; return [PopperStyleSheet];
} }
/** /**
* This method is called when the element is connected to the dom. * Lifecycle callback when element connects to DOM
* * Sets up event listeners and initializes popper
* @return {void}
*/ */
connectedCallback() { connectedCallback() {
super.connectedCallback(); super.connectedCallback();
...@@ -177,7 +179,6 @@ class Popper extends CustomElement { ...@@ -177,7 +179,6 @@ class Popper extends CustomElement {
const document = getDocument(); const document = getDocument();
for (const [, type] of Object.entries(["click", "touch"])) { for (const [, type] of Object.entries(["click", "touch"])) {
// close on outside ui-events
document.addEventListener(type, this[closeEventHandler]); document.addEventListener(type, this[closeEventHandler]);
} }
...@@ -186,14 +187,12 @@ class Popper extends CustomElement { ...@@ -186,14 +187,12 @@ class Popper extends CustomElement {
} }
/** /**
* This method is called when the element is disconnected from the dom. * Lifecycle callback when element disconnects from DOM
* * Cleans up event listeners and observers
* @return {void}
*/ */
disconnectedCallback() { disconnectedCallback() {
super.disconnectedCallback(); super.disconnectedCallback();
// close on outside ui-events
for (const [, type] of Object.entries(["click", "touch"])) { for (const [, type] of Object.entries(["click", "touch"])) {
document.removeEventListener(type, this[closeEventHandler]); document.removeEventListener(type, this[closeEventHandler]);
} }
...@@ -202,9 +201,8 @@ class Popper extends CustomElement { ...@@ -202,9 +201,8 @@ class Popper extends CustomElement {
} }
/** /**
* With this method, you can show the popper. * Shows the popper element
* * @return {Popper} The popper instance
* @return {Popper}
*/ */
showDialog() { showDialog() {
show.call(this); show.call(this);
...@@ -212,9 +210,8 @@ class Popper extends CustomElement { ...@@ -212,9 +210,8 @@ class Popper extends CustomElement {
} }
/** /**
* With this method you can hide the popper. * Hides the popper element
* * @return {Popper} The popper instance
* @return {Popper}
*/ */
hideDialog() { hideDialog() {
hide.call(this); hide.call(this);
...@@ -222,9 +219,8 @@ class Popper extends CustomElement { ...@@ -222,9 +219,8 @@ class Popper extends CustomElement {
} }
/** /**
* With this method you can toggle the popper. * Toggles popper visibility
* * @return {Popper} The popper instance
* @return {Popper}
*/ */
toggleDialog() { toggleDialog() {
if (this[popperElementSymbol].style.display === STYLE_DISPLAY_MODE_BLOCK) { if (this[popperElementSymbol].style.display === STYLE_DISPLAY_MODE_BLOCK) {
...@@ -237,8 +233,9 @@ class Popper extends CustomElement { ...@@ -237,8 +233,9 @@ class Popper extends CustomElement {
} }
/** /**
* Initializes event handlers for popper interactivity
* @private * @private
* @return {Popper} * @return {Popper} The popper instance
*/ */
function initEventHandler() { function initEventHandler() {
this[closeEventHandler] = (event) => { this[closeEventHandler] = (event) => {
...@@ -276,10 +273,11 @@ function initEventHandler() { ...@@ -276,10 +273,11 @@ function initEventHandler() {
} }
/** /**
* Sets up event handlers for specific interaction mode
* @private * @private
* @param mode * @param {string} mode - Interaction mode to initialize
* @return {Popper} * @return {Popper} The popper instance
* @throws Error * @throws {Error} For unknown modes
*/ */
function initEventHandlerByMode(mode) { function initEventHandlerByMode(mode) {
switch (mode) { switch (mode) {
...@@ -338,10 +336,10 @@ function initEventHandlerByMode(mode) { ...@@ -338,10 +336,10 @@ function initEventHandlerByMode(mode) {
} }
/** /**
* Sets up resize observer for popper repositioning
* @private * @private
*/ */
function attachResizeObserver() { function attachResizeObserver() {
// against flickering
this[resizeObserverSymbol] = new ResizeObserver((entries) => { this[resizeObserverSymbol] = new ResizeObserver((entries) => {
if (this[timerCallbackSymbol] instanceof DeadMansSwitch) { if (this[timerCallbackSymbol] instanceof DeadMansSwitch) {
try { try {
...@@ -369,6 +367,10 @@ function attachResizeObserver() { ...@@ -369,6 +367,10 @@ function attachResizeObserver() {
}); });
} }
/**
* Disconnects resize observer
* @private
*/
function disconnectResizeObserver() { function disconnectResizeObserver() {
if (this[resizeObserverSymbol] instanceof ResizeObserver) { if (this[resizeObserverSymbol] instanceof ResizeObserver) {
this[resizeObserverSymbol].disconnect(); this[resizeObserverSymbol].disconnect();
...@@ -376,6 +378,7 @@ function disconnectResizeObserver() { ...@@ -376,6 +378,7 @@ function disconnectResizeObserver() {
} }
/** /**
* Hides the popper element
* @private * @private
*/ */
function hide() { function hide() {
...@@ -396,6 +399,7 @@ function hide() { ...@@ -396,6 +399,7 @@ function hide() {
} }
/** /**
* Shows the popper element
* @private * @private
*/ */
function show() { function show() {
...@@ -427,6 +431,7 @@ function show() { ...@@ -427,6 +431,7 @@ function show() {
} }
/** /**
* Updates popper positioning
* @private * @private
*/ */
function updatePopper() { function updatePopper() {
...@@ -447,8 +452,9 @@ function updatePopper() { ...@@ -447,8 +452,9 @@ function updatePopper() {
} }
/** /**
* Initializes references to DOM elements
* @private * @private
* @return {Popper} * @return {Popper} The popper instance
*/ */
function initControlReferences() { function initControlReferences() {
this[controlElementSymbol] = this.shadowRoot.querySelector( this[controlElementSymbol] = this.shadowRoot.querySelector(
...@@ -467,8 +473,9 @@ function initControlReferences() { ...@@ -467,8 +473,9 @@ function initControlReferences() {
} }
/** /**
* Gets the main template HTML
* @private * @private
* @return {string} * @return {string} Template HTML
*/ */
function getTemplate() { function getTemplate() {
// language=HTML // language=HTML
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment