@momentum-design/components 0.129.41 → 0.129.43

package/dist/components/coachmark/coachmark.component.d.ts

@@ -1,8 +1,22 @@
 import Popover from '../popover/popover.component';
 import type { PopoverTrigger } from '../popover/popover.types';
 /**
+ * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
+ * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
+ *
  * Coachmark component based on top of the popover component,
  * with the default value of certain properties changed.
+ * Coachmark component will always have an arrow attached to it.
+ * The color of the coachmark is contrast.
+ *
+ * ## When to use
+ * - Introducing a new or complex feature to users.
+ * - Drawing attention to a UI element that might otherwise be missed.
+ * - Providing step-by-step guidance in an onboarding or walkthrough flow.
+ *
+ * ## Accessibility
+ * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
+ * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
  *
  * @dependency mdc-popover
  *
@@ -24,7 +38,6 @@ import type { PopoverTrigger } from '../popover/popover.types';
  * @cssproperty --mdc-popover-elevation-3 - elevation of the popover
  *
  * @slot - Default slot for modal container
- *
  */
 declare class Coachmark extends Popover {
     /**

package/dist/components/coachmark/coachmark.component.js

@@ -11,8 +11,22 @@ import { property } from 'lit/decorators.js';
 import Popover from '../popover/popover.component';
 import { DEFAULTS } from './coachmark.constants';
 /**
+ * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
+ * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
+ *
  * Coachmark component based on top of the popover component,
  * with the default value of certain properties changed.
+ * Coachmark component will always have an arrow attached to it.
+ * The color of the coachmark is contrast.
+ *
+ * ## When to use
+ * - Introducing a new or complex feature to users.
+ * - Drawing attention to a UI element that might otherwise be missed.
+ * - Providing step-by-step guidance in an onboarding or walkthrough flow.
+ *
+ * ## Accessibility
+ * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
+ * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
  *
  * @dependency mdc-popover
  *
@@ -34,7 +48,6 @@ import { DEFAULTS } from './coachmark.constants';
  * @cssproperty --mdc-popover-elevation-3 - elevation of the popover
  *
  * @slot - Default slot for modal container
- *
  */
 class Coachmark extends Popover {
     constructor() {

package/dist/components/coachmark/index.d.ts

@@ -1,5 +1,4 @@
 import Coachmark from './coachmark.component';
-import '../button';
 declare global {
     interface HTMLElementTagNameMap {
         ['mdc-coachmark']: Coachmark;

package/dist/components/coachmark/index.js

@@ -1,5 +1,4 @@
 import Coachmark from './coachmark.component';
 import { TAG_NAME } from './coachmark.constants';
-import '../button';
 Coachmark.register(TAG_NAME);
 export default Coachmark;

package/dist/components/popover/popover.component.d.ts

@@ -1,6 +1,6 @@
 import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
-import type { PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger } from './popover.types';
+import type { PopoverBoundaryRoot, PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger } from './popover.types';
 declare const Popover_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/BackdropMixin").BackdropMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/PreventScrollMixin").PreventScrollMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/FocusTrapMixin").FocusTrapClassInterface> & typeof Component;
 /**
  * Popover is generic overlay which can be triggered by any actionable element.
@@ -156,7 +156,7 @@ declare class Popover extends Popover_base {
      *
      * @see [Floating UI - rootBoundary](https://floating-ui.com/docs/detectOverflow#rootboundary)
      */
-    boundaryRoot: 'viewport' | 'document';
+    boundaryRoot: PopoverBoundaryRoot;
     /**
      * Virtual padding around the boundary to check for overflow.
      * So the popover will not be placed on top of the edge of the boundary.
@@ -374,12 +374,12 @@ declare class Popover extends Popover_base {
     /**
      * Get trigger element on-demand
      * It is necessary because trigger might appear later in the DOM, or it could be replaced completely.
-     *
-     * @internal
      */
     get triggerElement(): HTMLElement | null;
+    /** @internal */
     private timers;
     constructor();
+    /** @internal */
     private parseTrigger;
     protected firstUpdated(changedProperties: PropertyValues): Promise<void>;
     connectedCallback(): void;
@@ -390,14 +390,17 @@ declare class Popover extends Popover_base {
      *
      * We are using capture phase for to make sure we capture trigger events even when they are not propagated during the
      * bubble phase (e.g.: buttons in list item)
+     * @internal
      */
     private setupTriggerListeners;
     /**
      * Removes the trigger related event listeners.
+     * @internal
      */
     private removeTriggerListeners;
     /**
      * Removes all event listeners related to the popover.
+     * @internal
      */
     private removeAllListeners;
     protected updated(changedProperties: PropertyValues): Promise<void>;
@@ -405,6 +408,7 @@ declare class Popover extends Popover_base {
      * Handles the outside click event to close the popover.
      *
      * @param event - The mouse event.
+     * @internal
      */
     protected onOutsidePopoverClick: (event: MouseEvent) => void;
     /**
@@ -413,12 +417,14 @@ declare class Popover extends Popover_base {
      * This method is attached to the document.
      *
      * @param event - The keyboard event.
+     * @internal
      */
     private onEscapeKeydown;
     /**
      * Handles the popover focus out event.
      *
      * @param event - The focus event.
+     * @internal
      */
     private onPopoverFocusOut;
     /**
@@ -430,38 +436,43 @@ declare class Popover extends Popover_base {
      */
     protected isOpenUpdated(oldValue: boolean, newValue: boolean): Promise<void>;
     /**
-     *  Handles mouse enter event on the trigger element.
-     *  This method sets the `isHovered` flag to true and shows the popover
+     * Handles mouse enter event on the trigger element.
+     * This method sets the `isHovered` flag to true and shows the popover
+     * @internal
      */
     private handleMouseEnter;
     /**
-     *  Handles mouse leave event on the trigger element.
-     *  This method sets the `isHovered` flag to false and starts the close delay
-     *  timer to hide the popover.
+     * Handles mouse leave event on the trigger element.
+     * This method sets the `isHovered` flag to false and starts the close delay
+     * timer to hide the popover.
+     * @internal
      */
     private handleMouseLeave;
     /**
-     *  Handles focus out event on the trigger element.
-     *  This method checks if the popover is not hovered and hides the popover.
-     *  If the popover is hovered, it will not hide the popover.
+     * Closes based on hideOnBlur property or hover state.
+     * @internal
      */
     private handleFocusOut;
     /**
-     *  Handles focus in event on the trigger element.
-     *  This method checks if the trigger element has visible focus or is being hovered.
+     * Handles focus in event on the trigger element.
+     * This method checks if the trigger element has visible focus or is being hovered.
+     * @internal
      */
     private handleFocusIn;
     /**
      * Cancels the open delay timer.
+     * @internal
      */
     private cancelOpenDelay;
     /**
      * Starts the close delay timer.
      * If the popover is not interactive, it will close the popover after the delay.
+     * @internal
      */
     private startCloseDelay;
     /**
      * Cancels the close delay timer.
+     * @internal
      */
     private cancelCloseDelay;
     /**
@@ -480,6 +491,7 @@ declare class Popover extends Popover_base {
      * Positions the popover based on the trigger element.
      * It also handles the flip, size and arrow placement.
      * It uses the floating-ui/dom library to calculate the position.
+     * @internal
      */
     private positionPopover;
     protected isEventFromTrigger(event: Event): boolean;

package/dist/components/popover/popover.component.js

@@ -129,8 +129,6 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
     /**
      * Get trigger element on-demand
      * It is necessary because trigger might appear later in the DOM, or it could be replaced completely.
-     *
-     * @internal
      */
     get triggerElement() {
         return this.getRootNode().querySelector(`[id="${this.triggerID}"]`);
@@ -384,7 +382,9 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          * @internal
          */
         this.popoverDepth = 0;
+        /** @internal */
         this.timers = new Timers(this);
+        /** @internal */
         this.parseTrigger = () => {
             var _a;
             const triggers = ((_a = this.trigger) === null || _a === void 0 ? void 0 : _a.split(' ')) || [];
@@ -411,10 +411,14 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          *
          * We are using capture phase for to make sure we capture trigger events even when they are not propagated during the
          * bubble phase (e.g.: buttons in list item)
+         * @internal
          */
         this.setupTriggerListeners = () => {
             if (this.trigger.includes('click')) {
                 document.addEventListener('click', this.togglePopoverVisible, { capture: true });
+                if (this.hideOnBlur) {
+                    document.addEventListener('focusout', this.handleFocusOut, { capture: true });
+                }
             }
             if (this.trigger.includes('mouseenter')) {
                 const hoverBridge = this.renderRoot.querySelector('div[part="popover-hover-bridge"]');
@@ -433,6 +437,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         };
         /**
          * Removes the trigger related event listeners.
+         * @internal
          */
         this.removeTriggerListeners = () => {
             // click trigger
@@ -450,6 +455,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         };
         /**
          * Removes all event listeners related to the popover.
+         * @internal
          */
         this.removeAllListeners = () => {
             this.removeTriggerListeners();
@@ -468,6 +474,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          * Handles the outside click event to close the popover.
          *
          * @param event - The mouse event.
+         * @internal
          */
         this.onOutsidePopoverClick = (event) => {
             if (popoverStack.peek() !== this)
@@ -486,6 +493,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          * This method is attached to the document.
          *
          * @param event - The keyboard event.
+         * @internal
          */
         this.onEscapeKeydown = (event) => {
             if (!this.visible || event.code !== 'Escape') {
@@ -503,6 +511,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          * Handles the popover focus out event.
          *
          * @param event - The focus event.
+         * @internal
          */
         this.onPopoverFocusOut = (event) => {
             if (!this.contains(event.relatedTarget)) {
@@ -510,8 +519,9 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
             }
         };
         /**
-         *  Handles mouse enter event on the trigger element.
-         *  This method sets the `isHovered` flag to true and shows the popover
+         * Handles mouse enter event on the trigger element.
+         * This method sets the `isHovered` flag to true and shows the popover
+         * @internal
          */
         this.handleMouseEnter = (event) => {
             if (!this.isEventFromTrigger(event))
@@ -520,9 +530,10 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
             this.show();
         };
         /**
-         *  Handles mouse leave event on the trigger element.
-         *  This method sets the `isHovered` flag to false and starts the close delay
-         *  timer to hide the popover.
+         * Handles mouse leave event on the trigger element.
+         * This method sets the `isHovered` flag to false and starts the close delay
+         * timer to hide the popover.
+         * @internal
          */
         this.handleMouseLeave = (event) => {
             if (!this.isEventFromTrigger(event))
@@ -531,20 +542,28 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
             this.startCloseDelay();
         };
         /**
-         *  Handles focus out event on the trigger element.
-         *  This method checks if the popover is not hovered and hides the popover.
-         *  If the popover is hovered, it will not hide the popover.
+         * Closes based on hideOnBlur property or hover state.
+         * @internal
          */
         this.handleFocusOut = (event) => {
             if (!this.isEventFromTrigger(event))
                 return;
+            if (this.hideOnBlur) {
+                const { relatedTarget } = event;
+                // Don't hide if focus moves within the component
+                if (!this.contains(relatedTarget)) {
+                    this.hide();
+                }
+                return;
+            }
             if (!this.isHovered) {
                 this.hide();
             }
         };
         /**
-         *  Handles focus in event on the trigger element.
-         *  This method checks if the trigger element has visible focus or is being hovered.
+         * Handles focus in event on the trigger element.
+         * This method checks if the trigger element has visible focus or is being hovered.
+         * @internal
          */
         this.handleFocusIn = (event) => {
             var _a, _b, _c, _d;
@@ -558,6 +577,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         };
         /**
          * Cancels the open delay timer.
+         * @internal
          */
         this.cancelOpenDelay = () => {
             this.timers.clearTimeout(TIMEOUTS.OPEN);
@@ -565,6 +585,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         /**
          * Starts the close delay timer.
          * If the popover is not interactive, it will close the popover after the delay.
+         * @internal
          */
         this.startCloseDelay = () => {
             this.cancelOpenDelay();
@@ -586,6 +607,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
         };
         /**
          * Cancels the close delay timer.
+         * @internal
          */
         this.cancelCloseDelay = () => {
             this.timers.clearTimeout(TIMEOUTS.HOVER);
@@ -646,6 +668,7 @@ class Popover extends BackdropMixin(PreventScrollMixin(FocusTrapMixin(Component)
          * Positions the popover based on the trigger element.
          * It also handles the flip, size and arrow placement.
          * It uses the floating-ui/dom library to calculate the position.
+         * @internal
          */
         this.positionPopover = () => {
             const { triggerElement } = this;

package/dist/components/popover/popover.constants.d.ts

@@ -27,6 +27,10 @@ declare const STRATEGY: {
     readonly ABSOLUTE: "absolute";
     readonly FIXED: "fixed";
 };
+declare const BOUNDARY_ROOT: {
+    readonly VIEWPORT: "viewport";
+    readonly DOCUMENT: "document";
+};
 declare const DEFAULTS: {
     readonly PLACEMENT: "bottom";
     readonly TRIGGER: "click";
@@ -63,4 +67,4 @@ declare const TIMEOUTS: {
     readonly HOVER: "hover";
     readonly CLOSE: "close";
 };
-export { TAG_NAME, POPOVER_PLACEMENT, COLOR, STRATEGY, TRIGGER, DEFAULTS, TIMEOUTS };
+export { TAG_NAME, POPOVER_PLACEMENT, COLOR, STRATEGY, TRIGGER, BOUNDARY_ROOT, DEFAULTS, TIMEOUTS };

package/dist/components/popover/popover.constants.js

@@ -29,6 +29,10 @@ const STRATEGY = {
     ABSOLUTE: 'absolute',
     FIXED: 'fixed',
 };
+const BOUNDARY_ROOT = {
+    VIEWPORT: 'viewport',
+    DOCUMENT: 'document',
+};
 const DEFAULTS = {
     PLACEMENT: POPOVER_PLACEMENT.BOTTOM,
     TRIGGER: TRIGGER.CLICK,
@@ -36,7 +40,7 @@ const DEFAULTS = {
     STRATEGY: STRATEGY.ABSOLUTE,
     OFFSET: 4,
     BOUNDARY: 'clippingAncestors',
-    BOUNDARY_ROOT: 'viewport',
+    BOUNDARY_ROOT: BOUNDARY_ROOT.VIEWPORT,
     BOUNDARY_PADDING: 0,
     VISIBLE: false,
     ARROW: false,
@@ -65,4 +69,4 @@ const TIMEOUTS = {
     HOVER: 'hover',
     CLOSE: 'close',
 };
-export { TAG_NAME, POPOVER_PLACEMENT, COLOR, STRATEGY, TRIGGER, DEFAULTS, TIMEOUTS };
+export { TAG_NAME, POPOVER_PLACEMENT, COLOR, STRATEGY, TRIGGER, BOUNDARY_ROOT, DEFAULTS, TIMEOUTS };

package/dist/components/popover/popover.types.d.ts

@@ -1,9 +1,10 @@
 import type { ValueOf, TypedCustomEvent } from '../../utils/types';
 import type Popover from './popover.component';
-import { POPOVER_PLACEMENT, TRIGGER, COLOR, STRATEGY } from './popover.constants';
+import { POPOVER_PLACEMENT, TRIGGER, COLOR, STRATEGY, BOUNDARY_ROOT } from './popover.constants';
 type PopoverPlacement = ValueOf<typeof POPOVER_PLACEMENT>;
 type PopoverColor = ValueOf<typeof COLOR>;
 type PopoverStrategy = ValueOf<typeof STRATEGY>;
+type PopoverBoundaryRoot = ValueOf<typeof BOUNDARY_ROOT>;
 type PopoverTrigger = ValueOf<typeof TRIGGER> | `${ValueOf<typeof TRIGGER>} ${ValueOf<typeof TRIGGER>}`;
 type PopoverShownEvent = TypedCustomEvent<Popover, {
     show: boolean;
@@ -23,4 +24,4 @@ interface Events {
     onCreatedEvent: PopoverCreatedEvent;
     onDestroyedEvent: PopoverDestroyedEvent;
 }
-export type { PopoverPlacement, PopoverColor, PopoverStrategy, PopoverTrigger, Events, PopoverShownEvent, PopoverHiddenEvent, };
+export type { PopoverPlacement, PopoverColor, PopoverStrategy, PopoverBoundaryRoot, PopoverTrigger, Events, PopoverShownEvent, PopoverHiddenEvent, };