@operato/popup 2.0.0-alpha.2 → 2.0.0-alpha.28

package/src/ox-popup-list.ts

@@ -23,6 +23,9 @@ function guaranteeFocus(element: HTMLElement) {
   closest?.focus()
 }
 
+/**
+ * A custom element representing a list-like popup menu.
+ */
 @customElement('ox-popup-list')
 export class OxPopupList extends OxPopup {
   static styles = [
@@ -129,9 +132,30 @@ export class OxPopupList extends OxPopup {
     `
   ]
 
+  /**
+   * A boolean property that, when set to true, allows multiple options to be selected in the popup list.
+   * @type {boolean}
+   */
   @property({ type: Boolean }) multiple: boolean = false
+
+  /**
+   * An optional attribute that specifies the name of the attribute used to mark selected options in the list.
+   * @type {string|undefined}
+   */
   @property({ type: String, attribute: 'attr-selected' }) attrSelected?: string
+
+  /**
+   * A boolean property that, when set to true, enables the search functionality in the popup list.
+   * Users can search/filter options by typing in a search bar.
+   * @type {boolean|undefined}
+   */
   @property({ type: Boolean, attribute: 'with-search' }) withSearch?: boolean
+
+  /**
+   * The value(s) of the selected option(s) in the popup list.
+   * This property can be a string or an array of strings, depending on whether multiple selections are allowed.
+   * @type {string|string[]|undefined}
+   */
   @property({ type: String }) value?: string | string[]
 
   @state() activeIndex?: number
@@ -284,6 +308,11 @@ export class OxPopupList extends OxPopup {
     }
   }
 
+  /**
+   * Retrieves the labels of the selected options in the popup list.
+   * If multiple selections are allowed, an array of labels is returned. Otherwise, a single label is returned.
+   * @returns {string|string[]} The label(s) of the selected option(s).
+   */
   public getSelectedLabels(): string | string[] {
     const options = Array.from(this.querySelectorAll(':scope > [option]'))
 
@@ -294,6 +323,11 @@ export class OxPopupList extends OxPopup {
     return this.multiple ? selected : selected[0]
   }
 
+  /**
+   * Handles the selection of options in the popup list and dispatches a 'select' event with the selected value(s).
+   * If multiple selections are allowed, an array of selected values is dispatched; otherwise, a single value is dispatched.
+   * Also, it checks whether the selected option should remain alive and whether the popup should be closed.
+   */
   async select() {
     await this.updateComplete
 
@@ -317,6 +351,13 @@ export class OxPopupList extends OxPopup {
     }
   }
 
+  /**
+   * Sets the active option within the popup list based on the given index or Element.
+   * If 'withSelect' is true, it also manages the selection state of the option.
+   *
+   * @param {number | Element | null} active - The index or Element of the option to set as active.
+   * @param {boolean | undefined} withSelect - Indicates whether to manage the selection state of the option.
+   */
   setActive(active: number | Element | null, withSelect?: boolean) {
     var options = Array.from(this.querySelectorAll('[option]:not([hidden])'))
     if (this.withSearch) {
@@ -351,6 +392,12 @@ export class OxPopupList extends OxPopup {
     })
   }
 
+  /**
+   * Overrides the 'open' method of the base class 'OxPopup' to set the initial active index
+   * when the popup list is opened. It ensures that an option is initially selected for user interaction.
+   *
+   * @param {object} params - The parameters for opening the popup, including position and size.
+   */
   override open(params: {
     left?: number
     top?: number
@@ -369,6 +416,11 @@ export class OxPopupList extends OxPopup {
     }
   }
 
+  /**
+   * Overrides the 'close' method of the base class 'OxPopup' to dispatch a custom event
+   * indicating that the popup list is being closed. This event can be used for further interactions
+   * or logic in the application.
+   */
   override close() {
     if (this.hasAttribute('active')) {
       this.dispatchEvent(

package/src/ox-popup-menu.ts

@@ -15,6 +15,9 @@ function focusClosest(element: HTMLElement) {
   return closest
 }
 
+/**
+ * Custom element representing a popup menu. It extends OxPopup.
+ */
 @customElement('ox-popup-menu')
 export class OxPopupMenu extends OxPopup {
   static styles = [
@@ -77,6 +80,9 @@ export class OxPopupMenu extends OxPopup {
     `
   ]
 
+  /**
+   * Property to track the index of the active menu item.
+   */
   @property({ type: Number }) activeIndex: number = 0
 
   render() {
@@ -151,6 +157,10 @@ export class OxPopupMenu extends OxPopup {
     }
   }
 
+  /**
+   * Selects a menu item by dispatching a 'select' event.
+   * Closes the menu if the item doesn't have 'alive-on-select' attribute.
+   */
   select(menu: Element) {
     menu.dispatchEvent(new CustomEvent('select'))
     if (!menu.hasAttribute('alive-on-select')) {
@@ -158,6 +168,9 @@ export class OxPopupMenu extends OxPopup {
     }
   }
 
+  /**
+   * Sets the active menu item based on the index or the menu element itself.
+   */
   setActive(active: number | Element | null) {
     const menus = Array.from(this.querySelectorAll(':scope > ox-popup-menuitem, :scope > [menu]'))
 
@@ -183,7 +196,8 @@ export class OxPopupMenu extends OxPopup {
   }
 
   /**
-   * Open Popup
+   * Static method to open a popup menu with the provided template and position options.
+   * Creates and returns an instance of OxPopupMenu.
    *
    * @param {PopupOpenOptions}
    */

package/src/ox-popup-menuitem.ts

@@ -3,6 +3,10 @@ import { customElement, property, state } from 'lit/decorators.js'
 
 import { OxPopupMenu } from './ox-popup-menu'
 
+/**
+ * Custom element representing a menu item within an OxPopup menu.
+ * It can contain a label and an optional submenu.
+ */
 @customElement('ox-popup-menuitem')
 export class OxPopupMenuItem extends LitElement {
   static styles = [
@@ -49,7 +53,15 @@ export class OxPopupMenuItem extends LitElement {
     `
   ]
 
+  /**
+   * Property indicating whether the menu item is active or not.
+   * When active, it may show a submenu.
+   */
   @property({ type: Boolean }) active: boolean = false
+
+  /**
+   * The label to display for the menu item.
+   */
   @property({ type: String }) label!: string
 
   @state() _submenu?: OxPopupMenu
@@ -133,6 +145,12 @@ export class OxPopupMenuItem extends LitElement {
     }
   }
 
+  /**
+   * Expands the submenu, if it exists.
+   * The submenu is displayed below and to the right of the menu item.
+   *
+   * @param {boolean} silent - If true, the submenu is opened silently without user interaction.
+   */
   expand(silent: boolean) {
     if (!this._submenu) {
       return
@@ -143,14 +161,25 @@ export class OxPopupMenuItem extends LitElement {
     this._submenu.open({ top, left, silent })
   }
 
+  /**
+   * Collapses the submenu, if it exists.
+   */
   collapse() {
     this._submenu?.close()
   }
 
+  /**
+   * Dispatches a custom 'ox-collapse' event indicating that the menu item should collapse itself.
+   * This event can be used to trigger further interactions or logic in the application.
+   */
   collapseSelf() {
     this.dispatchEvent(new CustomEvent('ox-collapse', { bubbles: true, composed: true, detail: this }))
   }
 
+  /**
+   * Dispatches a custom 'ox-close' event indicating that the menu item should close itself.
+   * This event can be used to trigger further interactions or logic in the application.
+   */
   close() {
     this.dispatchEvent(new CustomEvent('ox-close', { bubbles: true, composed: true, detail: this }))
   }

package/src/ox-popup.ts

@@ -4,6 +4,15 @@ import { customElement, state } from 'lit/decorators.js'
 
 import { ScrollbarStyles } from '@operato/styles'
 
+/**
+ * Custom element class representing the 'ox-popup' component.
+ *
+ * This component provides the functionality to display a popup with various configuration options.
+ * It can be used to show additional information, notifications, or user interactions within a web application.
+ *
+ * @fires ox-close - Dispatched when the popup is closed.
+ * @fires ox-collapse - Dispatched when the popup is collapsed.
+ */
 @customElement('ox-popup')
 export class OxPopup extends LitElement {
   static styles = [
@@ -32,12 +41,12 @@ export class OxPopup extends LitElement {
     `
   ]
 
-  @state() _parent?: Element
+  @state() _parent: Element | null = null
 
   private lastActive: HTMLElement = document.activeElement as HTMLElement
 
   render() {
-    return html` <slot> </slot> `
+    return html`<slot />`
   }
 
   protected _onfocusout: (e: FocusEvent) => void = function (this: OxPopup, e: FocusEvent) {
@@ -122,12 +131,6 @@ export class OxPopup extends LitElement {
    * @property {Number} left The position-left where the pop-up will be displayed
    * @property {HTMLElement} parent Popup's parent element
    */
-
-  /**
-   * Open Popup
-   *
-   * @param {PopupOpenOptions}
-   */
   static open({
     template,
     top,
@@ -136,7 +139,8 @@ export class OxPopup extends LitElement {
     bottom,
     width,
     height,
-    parent
+    parent,
+    style
   }: {
     template: unknown
     top?: number
@@ -146,9 +150,13 @@ export class OxPopup extends LitElement {
     width?: string
     height?: string
     parent?: Element | null
+    style?: string
   }): OxPopup {
     const owner = parent || document.body
     const target = document.createElement('ox-popup') as OxPopup
+    if (style) {
+      target.style.cssText = style
+    }
 
     render(template, target)
 
@@ -160,6 +168,18 @@ export class OxPopup extends LitElement {
     return target
   }
 
+  /**
+   * Opens the 'ox-popup' with the specified position and dimensions.
+   *
+   * @param {PopupOpenOptions} options - An object specifying the position and dimensions of the popup.
+   * @param {number} options.left - The left position (in pixels) where the popup should be displayed. If not provided, it will be centered horizontally.
+   * @param {number} options.top - The top position (in pixels) where the popup should be displayed. If not provided, it will be centered vertically.
+   * @param {number} options.right - The right position (in pixels) where the popup should be displayed. If provided, it will override the 'left' value.
+   * @param {number} options.bottom - The bottom position (in pixels) where the popup should be displayed. If provided, it will override the 'top' value.
+   * @param {string} options.width - The maximum width of the popup (CSS string). For example, '300px'.
+   * @param {string} options.height - The maximum height of the popup (CSS string). For example, '200px'.
+   * @param {boolean} [options.silent=false] - A flag indicating whether the popup should auto-focus or not. If set to true, the popup won't attempt to focus on any element.
+   */
   open({
     left,
     top,
@@ -188,9 +208,9 @@ export class OxPopup extends LitElement {
     }
 
     if (left === undefined && top === undefined && right === undefined && bottom === undefined) {
+      this.style.transform = 'translateX(-50%) translateY(-50%)'
       this.style.left = '50%'
       this.style.top = '50%'
-      this.style.transform = 'translateX(-50%) translateY(-50%)'
     } else {
       if (left !== undefined) this.style.left = `${left}px`
       if (top !== undefined) this.style.top = `${top}px`
@@ -229,7 +249,7 @@ export class OxPopup extends LitElement {
       const computedStyle = getComputedStyle(this)
 
       if (t < 0) {
-        this.style.top = `calc(${computedStyle.top} + ${t}px)` // 현재의 top 값에 t를 추가한다.
+        this.style.top = '0'
         this.style.bottom = ''
       } else if (vh < t + h) {
         this.style.top = `calc(${computedStyle.top} - ${t + h - vh}px)` // 현재의 top 값에 차감한다.
@@ -237,7 +257,7 @@ export class OxPopup extends LitElement {
       }
 
       if (l < 0) {
-        this.style.left = `calc(${computedStyle.left} + ${l}px)` // 현재의 left 값에 l를 추가한다.
+        this.style.left = '0'
         this.style.right = ''
       } else if (vw < l + w) {
         this.style.left = `calc(${computedStyle.left} - ${l + w - vw}px)` // 현재의 left 값에 차감한다.
@@ -264,6 +284,9 @@ export class OxPopup extends LitElement {
     }
   }
 
+  /**
+   * Closes the 'ox-popup'.
+   */
   close() {
     this.removeAttribute('active')
 
@@ -282,7 +305,7 @@ export class OxPopup extends LitElement {
       this.removeEventListener('contextmenu', this._oncontextmenu)
 
       this._parent.removeChild(this)
-      delete this._parent
+      this._parent = null
 
       if (this.lastActive) {
         this.lastActive.focus && this.lastActive.focus()

package/src/ox-prompt.ts

@@ -12,6 +12,9 @@ const TYPES_ICON = {
   question: 'question_mark'
 }
 
+/**
+ * The `ox-prompt` custom element represents a modal popup that provides information or options for the user, such as confirmation or cancellation.
+ */
 @customElement('ox-prompt')
 export class OxPrompt extends LitElement {
   static styles = [
@@ -66,14 +69,49 @@ export class OxPrompt extends LitElement {
     `
   ]
 
+  /**
+   * Specifies the type of the popup. Possible values are 'success', 'error', 'warning', 'info', 'question'.
+   */
   @property({ type: String }) type?: 'success' | 'error' | 'warning' | 'info' | 'question'
+
+  /**
+   * Specifies the icon of the popup.
+   */
   @property({ type: String }) icon?: string
+
+  /**
+   * Specifies the title of the popup.
+   */
   @property({ type: String }) titler?: string = ''
+
+  /**
+   * Specifies the text content of the popup.
+   */
   @property({ type: String }) text?: string
+
+  /**
+   * Specifies the footer (additional information at the bottom) of the popup.
+   */
   @property({ type: String }) footer?: string
+
+  /**
+   * Determines whether the popup is displayed as a toast.
+   */
   @property({ type: Boolean }) toast?: boolean
+
+  /**
+   * Specifies settings for the confirmation button.
+   */
   @property({ type: Object }) confirmButton?: { text: string; color?: string }
+
+  /**
+   * Specifies settings for the cancel button.
+   */
   @property({ type: Object }) cancelButton?: { text: string; color?: string }
+
+  /**
+   * A callback function called when the popup is closed, providing the result of the user's interaction.
+   */
   @property({ type: Object }) callback?: (result: { value: boolean }) => void
 
   @state() _parent?: Element
@@ -102,11 +140,17 @@ export class OxPrompt extends LitElement {
     `
   }
 
+  /**
+   * Function called when the confirm button is clicked.
+   */
   onConfirm() {
     this.resolveFn && this.resolveFn(true)
     this.close()
   }
 
+  /**
+   * Function called when the cancel button is clicked.
+   */
   onCancel() {
     this.resolveFn && this.resolveFn(false)
     this.close()
@@ -184,6 +228,31 @@ export class OxPrompt extends LitElement {
     this.guaranteeFocus()
   }
 
+  /**
+   * Static method to open the `ox-prompt` popup.
+   * @param {object} options - An object containing popup options.
+   * @param {unknown} [options.template] - An optional content template to render inside the popup.
+   * @param {'success' | 'error' | 'warning' | 'info' | 'question'} [options.type] - The type of the popup, which can be one of: 'success', 'error', 'warning', 'info', 'question'.
+   * @param {string} [options.icon] - The icon to be displayed in the popup header.
+   * @param {string} [options.title] - The title to be displayed in the popup header.
+   * @param {string} [options.text] - The main text content of the popup.
+   * @param {string} [options.footer] - Additional information to be displayed at the bottom of the popup.
+   * @param {object} [options.confirmButton] - Configuration for the confirmation button in the popup.
+   * @param {string} options.confirmButton.text - The text to be displayed on the confirmation button.
+   * @param {string} [options.confirmButton.color] - The color of the confirmation button (CSS color).
+   * @param {object} [options.cancelButton] - Configuration for the cancel button in the popup.
+   * @param {string} options.cancelButton.text - The text to be displayed on the cancel button.
+   * @param {string} [options.cancelButton.color] - The color of the cancel button (CSS color).
+   * @param {number} [options.top] - The top position of the popup (in pixels).
+   * @param {number} [options.left] - The left position of the popup (in pixels).
+   * @param {number} [options.right] - The right position of the popup (in pixels).
+   * @param {number} [options.bottom] - The bottom position of the popup (in pixels).
+   * @param {string} [options.width] - The maximum width of the popup (CSS string).
+   * @param {string} [options.height] - The maximum height of the popup (CSS string).
+   * @param {Element | null} [options.parent] - The parent element to which the popup should be attached. If not provided, it will be attached to the document body.
+   * @param {(result: { value: boolean }) => void} [options.callback] - A callback function that will be invoked when the user interacts with the popup, providing the result of the interaction.
+   * @returns {Promise<boolean>} A Promise that resolves based on user interaction with the popup.
+   */
   public static async open({
     template,
     type,
@@ -244,6 +313,18 @@ export class OxPrompt extends LitElement {
     return result
   }
 
+  /**
+   * Opens the popup with specified position and dimensions.
+   * @param {object} options - An object specifying the position and dimensions of the popup.
+   * @param {number} [options.left] - The left position of the popup (in pixels). If not provided, the popup will be horizontally centered.
+   * @param {number} [options.top] - The top position of the popup (in pixels). If not provided, the popup will be vertically centered.
+   * @param {number} [options.right] - The right position of the popup (in pixels). Overrides 'left' if both 'left' and 'right' are provided.
+   * @param {number} [options.bottom] - The bottom position of the popup (in pixels). Overrides 'top' if both 'top' and 'bottom' are provided.
+   * @param {string} [options.width] - The maximum width of the popup (CSS string). If not provided, no width restriction is applied.
+   * @param {string} [options.height] - The maximum height of the popup (CSS string). If not provided, no height restriction is applied.
+   * @param {boolean} [options.silent=false] - Determines whether to focus the popup automatically (true) or not (false).
+   * @returns {Promise<boolean>} A Promise that resolves based on user interaction with the popup.
+   */
   open({
     left,
     top,
@@ -352,6 +433,9 @@ export class OxPrompt extends LitElement {
     }
   }
 
+  /**
+   * Closes the popup.
+   */
   close() {
     this.removeAttribute('active')