@decaf-ts/ui-decorators 0.17.1 → 0.17.4

package/lib/types/ui/interfaces/IDecafModal.d.mts

@@ -0,0 +1,186 @@
+/**
+ * @description Interface for modal presentation and lifecycle control in Decaf UI.
+ * @summary Describes the public contract for modal configuration, presentation,
+ * dismissal, and event handling used by the modal component layer.
+ *
+ * @module ui/interfaces/IDecafModal
+ * @memberOf module:ui-decorators
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import { DecafComponent } from "../DecafComponent.d.mts";
+export interface IDecafModal extends DecafComponent<Model> {
+    /**
+     * @description Reference to the modal instance controller.
+     * @summary Exposes the dismiss capability used to close the modal programmatically.
+     */
+    modal?: any;
+    /**
+     * @description Title displayed in the modal header.
+     * @summary Optional header text rendered above the modal content.
+     */
+    title?: string;
+    /**
+     * @description Controls whether the modal is open.
+     * @summary Signals the current presentation state of the modal.
+     */
+    isOpen: boolean;
+    /**
+     * @description Optional tag used to identify the modal instance.
+     * @summary Provides a stable identifier that can be used by rendering and lookup logic.
+     */
+    tag?: string;
+    /**
+     * @description Additional modal configuration options.
+     * @summary Stores custom configuration passed into modal creation and presentation.
+     */
+    options?: Record<string, unknown>;
+    /**
+     * @description Global configuration values available to the modal.
+     * @summary Holds shared runtime data that can be consumed by modal content and handlers.
+     */
+    globals?: Record<string, unknown>;
+    /**
+     * @description Inline content rendered inside the modal body.
+     * @summary Accepts HTML text or DOM content to be sanitized and displayed.
+     */
+    inlineContent?: string | any;
+    /**
+     * @description Position of the inline content within the modal.
+     * @summary Determines whether inline content appears before or after the main body.
+     */
+    inlineContentPosition: "top" | "bottom";
+    /**
+     * @description Enables fullscreen presentation for the modal.
+     * @summary Controls whether the modal occupies the entire viewport.
+     */
+    fullscreen: boolean;
+    /**
+     * @description Enables expandable presentation for the modal.
+     * @summary Signals whether the modal can be expanded by the user.
+     */
+    expandable: boolean;
+    /**
+     * @description Controls border rendering for the modal content.
+     * @summary Enables or disables visual borders according to the component styling rules.
+     */
+    borders: boolean;
+    /**
+     * @description Enables lightbox presentation for the modal.
+     * @summary Controls whether the modal is displayed with a lightbox-style overlay.
+     */
+    lightBox: boolean;
+    /**
+     * @description Controls the transparency of the modal header.
+     * @summary Indicates whether the modal header should be rendered with a transparent background.
+     */
+    headerTransparent: boolean;
+    /**
+     * @description Sets the background color of the modal header.
+     * @summary Stores the header color token used to style the modal header region.
+     */
+    headerBackground: string;
+    /**
+     * @description Controls the visibility of the modal header.
+     * @summary Indicates whether the header section should be rendered.
+     */
+    showHeader: boolean;
+    /**
+     * @description Controls the visibility of the modal close button.
+     * @summary Indicates whether the close action should be shown in the header.
+     */
+    showCloseButton: boolean;
+    /**
+     * @description Emits modal dismiss details.
+     * @summary Notifies consumers when the modal is about to be dismissed.
+     */
+    willDismissEvent: {
+        emit(value: unknown): void;
+    };
+    /**
+     * @description Indicates whether the modal content is expanded.
+     * @summary Tracks the current expanded or collapsed state of the modal body.
+     */
+    expanded: boolean;
+    /**
+     * @description Defines the icon color used by the modal.
+     * @summary Stores the color token used for modal icons and actions.
+     */
+    iconColor: string;
+    /**
+     * @description Initializes the modal component state.
+     * @summary Prepares the modal before presentation and applies inline content sanitization.
+     *
+     * @return {Promise<void>} Resolves when initialization completes.
+     */
+    ngOnInit(): Promise<void>;
+    /**
+     * @description Prepares the modal with the provided options.
+     * @summary Merges defaults, applies global runtime settings, and registers custom handlers.
+     *
+     * @param {Record<string, unknown>} [options={}] Additional modal initialization options.
+     * @return {Promise<void>} Resolves when preparation completes.
+     */
+    prepare(options?: Record<string, unknown>): Promise<void>;
+    /**
+     * @description Sanitizes and normalizes inline content.
+     * @summary Converts DOM content to HTML text when needed and prepares it for safe rendering.
+     *
+     * @return {void} Does not return a value.
+     */
+    parseInlineContent(): void;
+    /**
+     * @description Creates and presents the modal.
+     * @summary Prepares the modal, presents it, and returns the active modal instance contract.
+     *
+     * @param {Record<string, unknown>} [props={}] Modal properties used during creation.
+     * @return {Promise<any>} Resolves with the modal instance contract.
+     */
+    create(props?: Record<string, unknown>): Promise<any>;
+    /**
+     * @description Presents the modal.
+     * @summary Sets the modal as visible and triggers any presentation-time updates.
+     *
+     * @return {Promise<void>} Resolves when the modal is visible.
+     */
+    present(): Promise<void>;
+    /**
+     * @description Handles a custom event triggered by the modal.
+     * @summary Stops event propagation when needed and routes the event to confirm or cancel actions.
+     *
+     * @param {any} event Event payload emitted by the modal.
+     * @return {Promise<void>} Resolves when event handling completes.
+     */
+    handleEvent(event: any): Promise<void>;
+    /**
+     * @description Handles the modal dismiss event.
+     * @summary Emits the dismiss payload and returns the overlay detail object to callers.
+     *
+     * @param {any} event Dismiss event emitted by the modal.
+     * @return {Promise<{ data?: unknown }>} Resolves with the dismiss event details.
+     */
+    handleWillDismiss(event: any): Promise<{
+        data?: unknown;
+    }>;
+    /**
+     * @description Toggles the expanded state of the modal.
+     * @summary Switches between expanded and collapsed presentation modes.
+     *
+     * @return {void} Does not return a value.
+     */
+    handleExpandToggle(): void;
+    /**
+     * @description Cancels the modal.
+     * @summary Dismisses the modal using the cancel role.
+     *
+     * @return {Promise<void>} Resolves when the modal has been dismissed.
+     */
+    cancel(): Promise<void>;
+    /**
+     * @description Confirms the modal.
+     * @summary Dismisses the modal using the confirm role and optional event data.
+     *
+     * @param {any} [event] Optional event payload forwarded to the dismiss action.
+     * @return {Promise<void>} Resolves when the modal has been dismissed.
+     */
+    confirm(event?: any): Promise<void>;
+}

package/lib/types/ui/interfaces/IDecafRouter.d.cts

@@ -0,0 +1,108 @@
+/**
+ * @description Contract for router helpers used by Decaf UI components.
+ * @summary Defines navigation and query-parameter utilities that abstract the
+ * underlying routing implementation for UI components and services.
+ *
+ * @interface IDecafRouter
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafRouter {
+    /**
+     * @description Parses query parameters from the current route.
+     * @summary Extracts specified query parameters from the current route and returns them
+     * as an array of key-value pairs. When no params are provided, all query parameters
+     * are extracted.
+     *
+     * @param {string | string[]} [params] - The parameter name(s) to extract from the route
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    parseAllQueryParams(params?: string | string[]): Record<string, any>[];
+    /**
+     * @description Checks if a query parameter exists in the current route.
+     * @summary Determines whether a specific query parameter is present in the current
+     * route's query parameters.
+     *
+     * @param {string} param - The name of the query parameter to check
+     * @return {boolean} True if the parameter exists, false otherwise
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    hasQueryParam(param: string): boolean;
+    /**
+     * @description Retrieves a specific query parameter from the current route.
+     * @summary Extracts a single query parameter from the current route and returns it
+     * as a key-value pair, or undefined if not found.
+     *
+     * @param {string} param - The name of the query parameter to retrieve
+     * @return {Record<string, any> | undefined} A key-value object representing the parameter, or undefined if not found
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getQueryParam(param: string): Record<string, any> | undefined;
+    /**
+     * @description Retrieves the value of a specific query parameter.
+     * @summary Extracts only the string value of a single query parameter from the current
+     * route, or undefined if not found.
+     *
+     * @param {string} param - The name of the query parameter to retrieve
+     * @return {string | undefined} The value of the parameter, or undefined if not found
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getQueryParamValue(param: string): string | undefined;
+    /**
+     * @description Retrieves the last segment of the current URL.
+     * @summary Extracts the final path segment from the current URL. Falls back to the
+     * browser's window location when the Angular Router URL is unavailable.
+     *
+     * @return {string} The last segment of the current URL path
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getLastUrlSegment(): string;
+    /**
+     * @description Retrieves the current URL of the application.
+     * @summary Returns the current URL path, stripping the leading forward slash.
+     * Falls back to the browser's pathname when the Angular Router returns only '/'.
+     *
+     * @return {string} The current URL without the leading slash
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getCurrentUrl(): string;
+    /**
+     * @description Retrieves the URL of the previous page.
+     * @summary Extracts the URL of the previous page from the router's navigation history,
+     * useful for back navigation and tracking the user's navigation path.
+     *
+     * @return {string} The URL of the previous page
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getPreviousUrl(): string;
+    /**
+     * @description Navigates back to the previous page.
+     * @summary Dispatches a {@link ComponentEventNames.BackButtonClickEvent} custom event
+     * and then triggers browser back navigation via Angular's Location service.
+     *
+     * @return {void}
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    backToLastPage(): void;
+    /**
+     * @description Navigates to a specified page.
+     * @summary Triggers navigation to the given page using the Ionic NavController,
+     * supporting ROOT, FORWARD, and BACK directions.
+     *
+     * @param {string} page - The target page path
+     * @param {"forward" | "back" | "root"} [direction] - The direction of navigation (default: FORWARD)
+     * @param {Record<string, any>} [options] - Additional navigation options
+     * @return {Promise<boolean>} Resolves to true if navigation succeeds, false otherwise
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    navigate(page: string, direction?: "forward" | "back" | "root", options?: Record<string, any>): Promise<boolean>;
+}

package/lib/types/ui/interfaces/IDecafRouter.d.mts

@@ -0,0 +1,108 @@
+/**
+ * @description Contract for router helpers used by Decaf UI components.
+ * @summary Defines navigation and query-parameter utilities that abstract the
+ * underlying routing implementation for UI components and services.
+ *
+ * @interface IDecafRouter
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafRouter {
+    /**
+     * @description Parses query parameters from the current route.
+     * @summary Extracts specified query parameters from the current route and returns them
+     * as an array of key-value pairs. When no params are provided, all query parameters
+     * are extracted.
+     *
+     * @param {string | string[]} [params] - The parameter name(s) to extract from the route
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    parseAllQueryParams(params?: string | string[]): Record<string, any>[];
+    /**
+     * @description Checks if a query parameter exists in the current route.
+     * @summary Determines whether a specific query parameter is present in the current
+     * route's query parameters.
+     *
+     * @param {string} param - The name of the query parameter to check
+     * @return {boolean} True if the parameter exists, false otherwise
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    hasQueryParam(param: string): boolean;
+    /**
+     * @description Retrieves a specific query parameter from the current route.
+     * @summary Extracts a single query parameter from the current route and returns it
+     * as a key-value pair, or undefined if not found.
+     *
+     * @param {string} param - The name of the query parameter to retrieve
+     * @return {Record<string, any> | undefined} A key-value object representing the parameter, or undefined if not found
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getQueryParam(param: string): Record<string, any> | undefined;
+    /**
+     * @description Retrieves the value of a specific query parameter.
+     * @summary Extracts only the string value of a single query parameter from the current
+     * route, or undefined if not found.
+     *
+     * @param {string} param - The name of the query parameter to retrieve
+     * @return {string | undefined} The value of the parameter, or undefined if not found
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getQueryParamValue(param: string): string | undefined;
+    /**
+     * @description Retrieves the last segment of the current URL.
+     * @summary Extracts the final path segment from the current URL. Falls back to the
+     * browser's window location when the Angular Router URL is unavailable.
+     *
+     * @return {string} The last segment of the current URL path
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getLastUrlSegment(): string;
+    /**
+     * @description Retrieves the current URL of the application.
+     * @summary Returns the current URL path, stripping the leading forward slash.
+     * Falls back to the browser's pathname when the Angular Router returns only '/'.
+     *
+     * @return {string} The current URL without the leading slash
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getCurrentUrl(): string;
+    /**
+     * @description Retrieves the URL of the previous page.
+     * @summary Extracts the URL of the previous page from the router's navigation history,
+     * useful for back navigation and tracking the user's navigation path.
+     *
+     * @return {string} The URL of the previous page
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getPreviousUrl(): string;
+    /**
+     * @description Navigates back to the previous page.
+     * @summary Dispatches a {@link ComponentEventNames.BackButtonClickEvent} custom event
+     * and then triggers browser back navigation via Angular's Location service.
+     *
+     * @return {void}
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    backToLastPage(): void;
+    /**
+     * @description Navigates to a specified page.
+     * @summary Triggers navigation to the given page using the Ionic NavController,
+     * supporting ROOT, FORWARD, and BACK directions.
+     *
+     * @param {string} page - The target page path
+     * @param {"forward" | "back" | "root"} [direction] - The direction of navigation (default: FORWARD)
+     * @param {Record<string, any>} [options] - Additional navigation options
+     * @return {Promise<boolean>} Resolves to true if navigation succeeds, false otherwise
+     *
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    navigate(page: string, direction?: "forward" | "back" | "root", options?: Record<string, any>): Promise<boolean>;
+}

package/lib/types/ui/interfaces/IDecafSpinner.d.cts

@@ -0,0 +1,69 @@
+/**
+ * @description Contract for loading overlay management in Decaf applications.
+ * @summary Defines the public API for displaying, updating, and dismissing loading overlays
+ * with optional progress tracking and message updates.
+ *
+ * @interface IDecafSpinner
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafSpinner {
+    /**
+     * @description Checks if a loading overlay is currently visible.
+     * @summary Returns true when a loading overlay is active and displayed to the user.
+     *
+     * @returns {boolean} True if a loading overlay is visible, false otherwise
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    isVisible(): boolean;
+    /**
+     * @description Displays a loading overlay with the specified message and options.
+     * @summary Creates and presents a loading overlay. If one is already visible,
+     * updates the existing overlay instead of creating a new one.
+     *
+     * @param {string | Record<string, any>} message - The message to display, or a full options object
+     * @param {Record<string, any>} [options] - Optional configuration for the loading overlay
+     * @returns {Promise<void>} Resolves when the loading overlay is displayed
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    show(message: string | Record<string, any>, options?: Record<string, any>): Promise<void>;
+    /**
+     * @description Updates the loading overlay message and optionally tracks progress.
+     * @summary Modifies the current overlay message. When {@link isProgressUpdate} is a number,
+     * displays progress as a percentage. When no overlay exists, creates one with a default duration.
+     *
+     * @param {string} message - The new message to display
+     * @param {boolean | number} [isProgressUpdate=false] - Progress percentage (number) or flag (boolean)
+     * @returns {Promise<void>} Resolves when the update is applied
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    update(message: string, isProgressUpdate?: boolean | number): Promise<void>;
+    /**
+     * @description Removes the loading overlay from display.
+     * @summary Dismisses the active loading overlay and resets internal progress state.
+     * Safe to call even when no overlay is active.
+     *
+     * @returns {Promise<void>} Resolves when the overlay is dismissed
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    remove(): Promise<void>;
+    /**
+     * @description Merges custom options with the default loading configuration.
+     * @summary Combines defaults with user-provided options. The {@link message} parameter
+     * takes precedence over any message set in {@link options}.
+     *
+     * @param {Record<string, any>} [options={}] - Custom loading options to merge
+     * @param {string} [message] - Optional message override
+     * @returns {Promise<Record<string, any>>} The merged configuration object
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getOptions(options?: Record<string, any>, message?: string): Promise<Record<string, any>>;
+    /**
+     * @description Retrieves the current loading message.
+     * @summary Returns the message currently being displayed in the active loading overlay.
+     *
+     * @returns {Promise<string>} Resolves to the current loading message
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getMessage(): Promise<string>;
+}

package/lib/types/ui/interfaces/IDecafSpinner.d.mts

@@ -0,0 +1,69 @@
+/**
+ * @description Contract for loading overlay management in Decaf applications.
+ * @summary Defines the public API for displaying, updating, and dismissing loading overlays
+ * with optional progress tracking and message updates.
+ *
+ * @interface IDecafSpinner
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafSpinner {
+    /**
+     * @description Checks if a loading overlay is currently visible.
+     * @summary Returns true when a loading overlay is active and displayed to the user.
+     *
+     * @returns {boolean} True if a loading overlay is visible, false otherwise
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    isVisible(): boolean;
+    /**
+     * @description Displays a loading overlay with the specified message and options.
+     * @summary Creates and presents a loading overlay. If one is already visible,
+     * updates the existing overlay instead of creating a new one.
+     *
+     * @param {string | Record<string, any>} message - The message to display, or a full options object
+     * @param {Record<string, any>} [options] - Optional configuration for the loading overlay
+     * @returns {Promise<void>} Resolves when the loading overlay is displayed
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    show(message: string | Record<string, any>, options?: Record<string, any>): Promise<void>;
+    /**
+     * @description Updates the loading overlay message and optionally tracks progress.
+     * @summary Modifies the current overlay message. When {@link isProgressUpdate} is a number,
+     * displays progress as a percentage. When no overlay exists, creates one with a default duration.
+     *
+     * @param {string} message - The new message to display
+     * @param {boolean | number} [isProgressUpdate=false] - Progress percentage (number) or flag (boolean)
+     * @returns {Promise<void>} Resolves when the update is applied
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    update(message: string, isProgressUpdate?: boolean | number): Promise<void>;
+    /**
+     * @description Removes the loading overlay from display.
+     * @summary Dismisses the active loading overlay and resets internal progress state.
+     * Safe to call even when no overlay is active.
+     *
+     * @returns {Promise<void>} Resolves when the overlay is dismissed
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    remove(): Promise<void>;
+    /**
+     * @description Merges custom options with the default loading configuration.
+     * @summary Combines defaults with user-provided options. The {@link message} parameter
+     * takes precedence over any message set in {@link options}.
+     *
+     * @param {Record<string, any>} [options={}] - Custom loading options to merge
+     * @param {string} [message] - Optional message override
+     * @returns {Promise<Record<string, any>>} The merged configuration object
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getOptions(options?: Record<string, any>, message?: string): Promise<Record<string, any>>;
+    /**
+     * @description Retrieves the current loading message.
+     * @summary Returns the message currently being displayed in the active loading overlay.
+     *
+     * @returns {Promise<string>} Resolves to the current loading message
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    getMessage(): Promise<string>;
+}

package/lib/types/ui/interfaces/IDecafToast.d.cts

@@ -0,0 +1,63 @@
+import { DecafToastOptions, DecafToastRole } from "../types.d.cts";
+/**
+ * @description Contract for toast notification management in Decaf applications.
+ * @summary Defines the public API for displaying toast messages with semantic types
+ * (error, success, warning, info), custom options, and dismissal role tracking.
+ *
+ * @interface IDecafToast
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafToast {
+    options: DecafToastOptions;
+    /**
+     * @description Displays an error toast with danger styling.
+     * @summary Presents a toast with the danger color and waits for dismissal,
+     * returning the role that caused it.
+     *
+     * @param {string} message - The error message to display
+     * @returns {Promise<DecafToastRole>} Resolves with the dismissal role
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    error(message: string): Promise<DecafToastRole>;
+    /**
+     * @description Creates and presents a toast from a full options object.
+     * @summary Convenience wrapper around {@link show} for callers that already
+     * have a complete {@link DecafToastOptions} object.
+     *
+     * @param {DecafToastOptions} options - Full toast configuration options
+     * @returns {Promise<object>} Resolves with the created toast element
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    create(options: DecafToastOptions): Promise<object>;
+    /**
+     * @description Displays an informational toast with default styling.
+     * @summary Presents a toast without a semantic color, suitable for neutral messages.
+     * Additional options can override the defaults.
+     *
+     * @param {string} message - The informational message to display
+     * @param {DecafToastOptions} [options={}] - Optional overrides for toast configuration
+     * @returns {Promise<void>} Resolves when the toast is presented
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    show(message: string, options?: DecafToastOptions): Promise<void>;
+    /**
+     * @description Displays a success toast with success styling.
+     * @summary Presents a toast with the success color for positive feedback messages.
+     *
+     * @param {string} message - The success message to display
+     * @returns {Promise<void>} Resolves when the toast is presented
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    success(message: string): Promise<void>;
+    /**
+     * @description Displays a warning toast with warning styling.
+     * @summary Presents a toast with the warning color and waits for dismissal,
+     * returning the role that caused it.
+     *
+     * @param {string} message - The warning message to display
+     * @returns {Promise<DecafToastRole>} Resolves with the dismissal role
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    warn(message: string): Promise<DecafToastRole>;
+}

package/lib/types/ui/interfaces/IDecafToast.d.mts

@@ -0,0 +1,63 @@
+import { DecafToastOptions, DecafToastRole } from "../types.d.mts";
+/**
+ * @description Contract for toast notification management in Decaf applications.
+ * @summary Defines the public API for displaying toast messages with semantic types
+ * (error, success, warning, info), custom options, and dismissal role tracking.
+ *
+ * @interface IDecafToast
+ * @since 2026-06-19
+ * @memberOf module:ui-decorators/ui/interfaces
+ */
+export interface IDecafToast {
+    options: DecafToastOptions;
+    /**
+     * @description Displays an error toast with danger styling.
+     * @summary Presents a toast with the danger color and waits for dismissal,
+     * returning the role that caused it.
+     *
+     * @param {string} message - The error message to display
+     * @returns {Promise<DecafToastRole>} Resolves with the dismissal role
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    error(message: string): Promise<DecafToastRole>;
+    /**
+     * @description Creates and presents a toast from a full options object.
+     * @summary Convenience wrapper around {@link show} for callers that already
+     * have a complete {@link DecafToastOptions} object.
+     *
+     * @param {DecafToastOptions} options - Full toast configuration options
+     * @returns {Promise<object>} Resolves with the created toast element
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    create(options: DecafToastOptions): Promise<object>;
+    /**
+     * @description Displays an informational toast with default styling.
+     * @summary Presents a toast without a semantic color, suitable for neutral messages.
+     * Additional options can override the defaults.
+     *
+     * @param {string} message - The informational message to display
+     * @param {DecafToastOptions} [options={}] - Optional overrides for toast configuration
+     * @returns {Promise<void>} Resolves when the toast is presented
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    show(message: string, options?: DecafToastOptions): Promise<void>;
+    /**
+     * @description Displays a success toast with success styling.
+     * @summary Presents a toast with the success color for positive feedback messages.
+     *
+     * @param {string} message - The success message to display
+     * @returns {Promise<void>} Resolves when the toast is presented
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    success(message: string): Promise<void>;
+    /**
+     * @description Displays a warning toast with warning styling.
+     * @summary Presents a toast with the warning color and waits for dismissal,
+     * returning the role that caused it.
+     *
+     * @param {string} message - The warning message to display
+     * @returns {Promise<DecafToastRole>} Resolves with the dismissal role
+     * @memberOf module:ui-decorators/ui/interfaces
+     */
+    warn(message: string): Promise<DecafToastRole>;
+}

package/lib/types/ui/interfaces/index.d.cts

@@ -0,0 +1,4 @@
+export * from "./IDecafModal.d.cts";
+export * from "./IDecafToast.d.cts";
+export * from "./IDecafSpinner.d.cts";
+export * from "./IDecafRouter.d.cts";