@ardium-ui/ui 5.0.0-alpha.89 → 5.0.0-alpha.90

package/fesm2022/ardium-ui-ui.mjs

@@ -16925,28 +16925,58 @@ class _ArdSnackbarRefInternal {
         this._onOpen.next();
         this._onOpen.complete();
     }
-    markAsStartingToClose() {
-        this._onCloseStart.next(true);
+    markAsStartingToClose(withAction = false) {
+        this._onCloseStart.next(withAction);
         this._onCloseStart.complete();
     }
 }
+/**
+ * Reference to an opened snackbar.
+ * Provides methods for closing the snackbar programmatically, and observables for subscribing to open, close, and action events.
+ */
 class ArdSnackbarRef {
     constructor(dismiss, _onOpen, _onCloseStart) {
         this.dismiss = dismiss;
         this._onOpen = _onOpen;
         this._onCloseStart = _onCloseStart;
         this._onClose = new Subject();
+        this._onAction = new Subject();
+        /**
+         * Observable that emits when the snackbar is opened. Completes after emitting the first value.
+         */
         this.onOpen = this._onOpen.asObservable();
+        /**
+         * Observable that emits when the snackbar is closed and all animations have finished. Emits a boolean value indicating whether the snackbar was closed as a result of the user clicking the action button (true) or not (false). Completes after emitting the first value.
+         */
         this.onClose = this._onClose.asObservable();
+        /**
+         * Observable that emits when the snackbar action is triggered, before the snackbar starts closing. Completes when the snackbar is closed, regardless of whether any value was emitted.
+         */
+        this.onAction = this._onAction.asObservable();
+        /**
+         * Observable that emits when the snackbar starts the closing process. Emits a boolean value indicating whether the closing was triggered by the user clicking the action button (true) or not (false). Completes after emitting the first value.
+         */
         this.onCloseStart = this._onCloseStart.asObservable();
         this._isClosed = false;
     }
+    /**
+     * Closes the snackbar, optionally indicating that the action was triggered.
+     * @param withAction A boolean value indicating whether the snackbar is being closed as a result of the user clicking the action button (true) or not (false).
+     */
     close(withAction = false) {
         if (this.isClosed)
             return;
         this.dismiss(withAction);
-        this.markAsClosed();
+        if (withAction) {
+            this._onAction.next();
+        }
+        this._onAction.complete();
     }
+    /**
+     * Marks the snackbar as closed after the closing animation has finished.
+     * @param withAction
+     * @returns
+     */
     markAsClosed(withAction = false) {
         if (this.isClosed)
             return;
@@ -16954,6 +16984,9 @@ class ArdSnackbarRef {
         this._onClose.complete();
         this._isClosed = true;
     }
+    /**
+     * Indicates whether the snackbar has been closed and the closing animation has finished.
+     */
     get isClosed() {
         return this._isClosed;
     }
@@ -17045,6 +17078,10 @@ const ARD_SNACKBAR_ANIMATION_LENGTH = new InjectionToken('ard-snackbar-animation
     factory: () => 150,
 });
 
+const TIMEOUT_LIMIT = 2_147_483_647; //maximum duration for setTimeout in browsers
+/**
+ * Service for opening snackbars. Provides methods for opening snackbars with either a simple message and action, or with a custom component. Manages a queue of snackbars to be displayed, and handles the display and dismissal of snackbars according to the specified options. Also provides methods for retrieving and clearing the snackbar queue.
+ */
 class ArdiumSnackbarService {
     constructor() {
         this._snackbarQueue = new Queue();
@@ -17054,6 +17091,14 @@ class ArdiumSnackbarService {
         this._injector = inject(Injector);
     }
     //! public methods for creating new snackbars
+    /**
+     * Opens a snackbar with the given message, action and options.
+     * @param message The message to display in the snackbar.
+     * @param action The label for the snackbar action. If provided, the snackbar will have an action button with this label.
+     *               When the action button is clicked, the snackbar will emit a close event with `withAction` set to `true`.
+     * @param options Additional options for configuring the snackbar.
+     * @returns A reference to the opened snackbar.
+     */
     open(message, action, options = {}) {
         options.data = {
             message,
@@ -17064,10 +17109,18 @@ class ArdiumSnackbarService {
             mergedOptions.data.message = message;
             mergedOptions.data.action = action;
         }
-        const internalRef = new _ArdSnackbarRefInternal(_ArdSimpleSnackbarComponent, mergedOptions, (withAction) => this.dismissCurrent(withAction));
+        const internalRef = new _ArdSnackbarRefInternal(_ArdSimpleSnackbarComponent, mergedOptions, (withAction) => {
+            this.dismissCurrent(withAction);
+        });
         this._handleQueue(mergedOptions.queueHandling, internalRef);
         return internalRef.publicRef;
     }
+    /**
+     * Opens a snackbar with a custom component, passing the given options.
+     * @param component The component to display inside the snackbar. This component will be instantiated and inserted into the snackbar overlay.
+     * @param options Additional options for configuring the snackbar, such as data to pass to the component, placement, styling, etc.
+     * @returns A reference to the opened snackbar, with the generic type of the component instance. You can use this reference to subscribe to open/close events, and to close the snackbar programmatically.
+     */
     openFromComponent(component, options) {
         const mergedOptions = this._mergeOptions(options);
         const internalRef = new _ArdSnackbarRefInternal(component, mergedOptions, (withAction) => this.dismissCurrent(withAction));
@@ -17138,8 +17191,8 @@ class ArdiumSnackbarService {
         sb.publicRef.instance = componentRef.instance;
         sb.markAsOpened();
         this._openedSnackbar = sb;
-        const duration = sb.options.duration === Infinity || sb.options.duration <= 0
-            ? 2_147_483_647 //maximum duration for setTimeout
+        const duration = sb.options.duration === Infinity || sb.options.duration <= 0 || sb.options.duration > TIMEOUT_LIMIT
+            ? TIMEOUT_LIMIT
             : sb.options.duration;
         sb.timeout = setTimeout(() => {
             this.dismissCurrent(false);
@@ -17202,6 +17255,10 @@ class ArdiumSnackbarService {
         return this._overlay.create(config);
     }
     //! public actions
+    /**
+     * Dismisses the currently opened snackbar, if any. If `withAction` is true, it indicates that the snackbar is being dismissed as a result of the user clicking the action button (if it has one). This will cause the snackbar to emit a close event with `withAction` set to true, allowing you to differentiate between automatic dismissal and user-initiated dismissal via the action button.
+     * @param withAction Optional boolean indicating whether the dismissal is due to the user clicking the action button. Defaults to false. If true, the snackbar's close event will emit with `withAction` set to true, allowing you to handle this case differently if needed.
+     */
     dismissCurrent(withAction) {
         const sb = this._openedSnackbar;
         if (!sb) {
@@ -17210,17 +17267,23 @@ class ArdiumSnackbarService {
         }
         sb.markAsStartingToClose();
         setTimeout(() => {
-            sb.overlay?.dispose();
             this._openedSnackbar = undefined;
             sb.publicRef.markAsClosed(withAction);
+            sb.overlay?.dispose();
             clearTimeout(sb.timeout);
             this._openNext();
         }, this._animationLength);
     }
     //! public queue methods
+    /**
+     * Returns an array of references to the snackbars currently in the queue, in the order they will be opened. Note that this does not include the currently opened snackbar, if any.
+     */
     getQueue() {
         return this._snackbarQueue.toArray().map(v => v.publicRef);
     }
+    /**
+     * Clears all pending snackbars from the queue. Does not affect the currently opened snackbar, if any. Use with caution, as this will remove all pending snackbars that have not yet been displayed, and they will not be shown at all.
+     */
     clearQueue() {
         this._snackbarQueue.clear();
     }