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