@scion/workbench-client/index.d.ts

SCION Workbench Client provides core API for a web app to interact with SCION Workbench and other microfrontends. It is a pure TypeScript library based on the framework-agnostic `@scion/microfrontend-platform` library and can be used with any web stack.

import { ConnectOptions, Qualifier, Capability, ParamDefinition } from '@scion/microfrontend-platform';
import { Dictionary } from '@scion/toolkit/util';
import { Observable } from 'rxjs';
import { PreDestroy } from '@scion/toolkit/bean-manager';

/**
 * **SCION Workbench Client provides core API for a web app to interact with SCION Workbench and other microfrontends.**
 *
 * It is a pure TypeScript library based on the framework-agnostic `@scion/microfrontend-platform` library and can be used with any web stack.
 *
 * You can use the `Beans` object to get references to services to interact with the SCION Workbench and the SCION Microfrontend Platform.
 *
 * #### Core services include:
 *
 * - {@link WorkbenchRouter} for navigating to a microfrontend in a workbench view.
 * - {@link WorkbenchView} for the microfrontend to interact with the view.
 * - {@link WorkbenchDialogService} for displaying a microfrontend in a dialog.
 * - {@link WorkbenchDialog} for the microfrontend to interact with the dialog.
 * - {@link WorkbenchPopupService} for displaying a microfrontend in a popup.
 * - {@link WorkbenchPopup} for the microfrontend to interact with the popup.
 * - {@link WorkbenchMessageBoxService} for displaying a message.
 * - {@link WorkbenchMessageBox} for the microfrontend to interact with the message box.
 * - {@link WorkbenchNotificationService} for displaying a notification.
 * - `MessageClient` for sending or receiving messages between micro applications.
 * - `IntentClient` for issuing or receiving intents between micro applications.
 * - `ManifestService` for reading and registering capabilities at runtime.
 * - `SciRouterOutletElement` for embedding microfrontends.
 * - `OutletRouter` for navigating to a site in a router outlet element.
 * - `ContextService` for looking up contextual data set on a router outlet.
 * - `PreferredSizeService` for a microfrontend to report its preferred size.
 * - `FocusMonitor` for observing if the microfrontend has received focus or contains embedded web content that has received focus.
 *
 * For example, you can obtain the workbench router as follows:
 *
 * ```ts
 * const router = Beans.get(WorkbenchRouter)
 * ```
 *
 * Below is a summary of the core concepts of the SCION Microfrontend Platform.
 *
 * #### Host Application and Micro Applications
 * The host application, sometimes also called the container application, provides the top-level integration container for microfrontends. Typically, it is the web app
 * which the user loads into his browser and provides the main application shell, defining areas to embed microfrontends. The host application has SCION Workbench installed,
 * registers micro apps and starts the SCION Microfrontend Platform in host mode.
 *
 * A micro application deals with well-defined business functionality. It is a regular web application that provides one or more microfrontends. SCION Microfrontend Platform
 * uses iframes to embed microfrontends; thus, any web page can be integrated as a microfrontend. A micro application can communicate with other micro applications safely
 * using the platform's cross-origin messaging API. A micro application has to provide an application manifest which to register in the host application.
 *
 * For more information, see the chapter [Core Concepts](https://microfrontend-platform-developer-guide.scion.vercel.app/#_core_concepts)
 * of the SCION Microfrontend Platform Developer's Guide.
 *
 * #### Embedding of Microfrontends
 * You can embed microfrontends using the `<sci-router-outlet>` web component. Web content displayed in the web component is controlled via the `OutletRouter`.
 *
 * For more information, see the chapter [Embedding Microfrontends](https://microfrontend-platform-developer-guide.scion.vercel.app/#chapter:embedding-microfrontends)
 * of the SCION Microfrontend Platform Developer's Guide.
 *
 * #### Cross-Application Communication
 * You can interact with other micro applications via messaging or through so-called intents. Intents are a mechanism known from Android development,
 * enabling controlled collaboration across application boundaries.
 *
 * For more information, see the chapters [Cross-Application Communication](https://microfrontend-platform-developer-guide.scion.vercel.app/#chapter:cross-application-communication)
 * and [Intention API](https://microfrontend-platform-developer-guide.scion.vercel.app/#chapter:intention-api) of the SCION Microfrontend Platform Developer's Guide.
 *
 * #### Activation
 * You can provide an activator to connect to the platform when the user loads the host app into his browser, allowing to initialize and install message listeners for interacting
 * with other micro applications. Starting an activator may take some time. In order not to miss any messages, you can instruct the platform host to wait until you signal
 * readiness.
 *
 * For more information, see the chapter [Activator](https://microfrontend-platform-developer-guide.scion.vercel.app/#chapter:activator) of the SCION Microfrontend
 * Platform Developer's Guide.
 *
 * See our [Developer's Guide](https://microfrontend-platform-developer-guide.scion.vercel.app) for the full documentation about the
 * [SCION Microfrontend Platform](https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform).
 */
declare class WorkbenchClient {
    private constructor();
    /**
     * Connects the micro application to the SCION Workbench and SCION Microfrontend Platform.
     *
     * After connected, the micro application can interact with the workbench and other micro applications. Typically, the
     * micro application connects to the workbench during the bootstrapping. In Angular, for example, this can be done in
     * an app initializer.
     *
     * See {@link @scion/microfrontend-platform!MicrofrontendPlatformClient.connect} for more information about connecting to the platform host.
     *
     * @param  symbolicName - Specifies the symbolic name of the micro application. The micro application needs to be registered
     *         in the workbench under that identity.
     * @param  connectOptions - Controls how to connect to the workbench.
     * @return A Promise that resolves once connected to the workbench, or that rejects otherwise.
     */
    static connect(symbolicName: string, connectOptions?: ConnectOptions): Promise<void>;
}

/**
 * Excludes all keys from T, resulting in an empty object `{}`.
 */
type Empty<T> = {
    [Key in keyof T]: never;
};

/**
 * Enables navigation of workbench views.
 *
 * A view is a visual workbench element for displaying content side-by-side or stacked.
 *
 * A microfrontend provided as a view capability can be opened in a view. The qualifier differentiates between different
 * view capabilities. An application can open the public view capabilities of other applications if it manifests a respective
 * intention.
 *
 * @category Router
 * @category View
 */
declare class WorkbenchRouter {
    /**
     * Navigates to a microfrontend of a view capability based on the given qualifier and extras.
     *
     * By default, the router opens a new view if no view is found that matches the specified qualifier and required params. Optional parameters do not affect view resolution.
     * If one or more views match the qualifier and required params, they will be navigated instead of opening the microfrontend in a new view tab.
     * This behavior can be changed by setting an explicit navigation target in navigation extras.
     *
     * @param  qualifier - Identifies the view capability that provides the microfrontend to display in a view.
     *                     Passing an empty qualifier (`{}`) allows the microfrontend to update its parameters, restoring updated parameters when the page reloads.
     *                     Parameter handling can be controlled using the {@link WorkbenchNavigationExtras#paramsHandling} option.
     * @param  extras - Options to control navigation.
     * @return Promise that resolves to `true` on successful navigation, or `false` otherwise.
     */
    navigate(qualifier: Qualifier | Empty<Qualifier>, extras?: WorkbenchNavigationExtras): Promise<boolean>;
    private issueViewIntent;
    private updateViewParams;
    private isSelfNavigation;
}
/**
 * Options to control the navigation.
 *
 * @category Router
 * @category View
 */
interface WorkbenchNavigationExtras {
    /**
     * Passes data to the view.
     *
     * The view can declare mandatory and optional parameters. No additional parameters are allowed. Refer to the documentation of the capability for more information.
     */
    params?: Map<string, any> | Dictionary;
    /**
     * Instructs the workbench router how to handle params in self-navigation.
     *
     * Self-navigation allows the microfrontend to update its parameters, restoring updated parameters when the page reloads.
     * Setting a `paramsHandling` strategy has no effect on navigations other than self-navigation. A self-navigation is
     * initiated by passing an empty qualifier.
     *
     * One of:
     * * `replace`: Replaces current parameters (default).
     * * `merge`:   Merges new parameters with current parameters, with new parameters of equal name overwriting existing parameters.
     *              A parameter can be removed by passing `undefined` as its value.
     */
    paramsHandling?: 'merge' | 'replace';
    /**
     * Controls where to open the view. Defaults to `auto`.
     *
     * One of:
     * - 'auto':   Navigates existing views that match the qualifier and required params, or opens a new view otherwise. Optional parameters do not affect view resolution.
     * - 'blank':  Opens a new view and navigates it.
     * - <viewId>: Navigates the specified view. If already opened, replaces it, or opens a new view otherwise.
     */
    target?: string | 'blank' | 'auto';
    /**
     * Controls which part to navigate views in.
     *
     * If target is `blank`, opens the view in the specified part.
     * If target is `auto`, navigates matching views in the specified part, or opens a new view in that part otherwise.
     *
     * If the specified part is not in the layout, opens the view in the active part, with the active part of the main area taking precedence.
     */
    partId?: string;
    /**
     * Instructs the router to activate the view. Defaults to `true`.
     */
    activate?: boolean;
    /**
     * Closes views that match the specified qualifier and required parameters. Optional parameters do not affect view resolution.
     *
     * The parameters support the asterisk wildcard value (`*`) to match views with any value for a parameter.
     *
     * Only views for which the application has an intention can be closed.
     */
    close?: boolean;
    /**
     * Specifies where to insert the view into the tab bar. Has no effect if navigating an existing view. Defaults to after the active view.
     */
    position?: number | 'start' | 'end' | 'before-active-view' | 'after-active-view';
    /**
     * Specifies CSS class(es) to add to the view, e.g., to locate the view in tests.
     */
    cssClass?: string | string[];
}
/**
 * Command object for instructing the Workbench Router to update view params in self-navigation.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 */
interface ɵViewParamsUpdateCommand {
    /**
     * @see WorkbenchNavigationExtras#params
     */
    params: Dictionary;
    /**
     * @see WorkbenchNavigationExtras#paramsHandling
     */
    paramsHandling?: 'merge' | 'replace';
}
/**
 * Named parameters used in microfrontend routes.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 */
declare enum ɵMicrofrontendRouteParams {
    /**
     * Named path segment in the microfrontend route representing the view capability for which to embed its microfrontend.
     */
    ɵVIEW_CAPABILITY_ID = "\u0275ViewCapabilityId"
}

/**
 * Built-in workbench capabilities.
 */
declare enum WorkbenchCapabilities {
    /**
     * Contributes a microfrontend for display in workbench view.
     *
     * A view is a visual workbench element for displaying content stacked or side-by-side.
     */
    View = "view",
    /**
     * Contributes a perspective to the workbench.
     *
     * A perspective is a named arrangement of views. Different perspectives provide a different perspective on the application.
     */
    Perspective = "perspective",
    /**
     * Contributes a microfrontend for display in workbench popup.
     *
     * A popup is a visual workbench component for displaying content above other content.
     */
    Popup = "popup",
    /**
     * Contributes a microfrontend for display in workbench dialog.
     *
     * A dialog is a visual element for focused interaction with the user, such as prompting the user for input or confirming actions.
     */
    Dialog = "dialog",
    /**
     * Contributes a message box in the host app.
     *
     * A message box is a standardized dialog for presenting a message to the user, such as an info, warning or alert,
     * or for prompting the user for confirmation.
     */
    MessageBox = "messagebox",
    /**
     * Contributes a notification in the host app.
     *
     * A notification appears in the upper-right corner and disappears automatically after a few seconds.
     * It informs the user of a system event, e.g., that a task has been completed or an error has occurred.
     */
    Notification = "notification"
}

/**
 * Represents a microfrontend for display in a workbench view.
 *
 * A view is a visual workbench element for displaying content stacked or side-by-side.
 *
 * The microfrontend can inject the {@link WorkbenchView} handle to interact with the view, such as setting the title, reading
 * parameters, or closing it.
 *
 * @category View
 * @see WorkbenchView
 * @see WorkbenchRouter
 */
interface WorkbenchViewCapability extends Capability {
    /**
     * @inheritDoc
     */
    type: WorkbenchCapabilities.View;
    /**
     * Qualifies this view. The qualifier is required for views.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * Specifies parameters required by the view.
     *
     * Parameters are available in the path and title for placeholder substitution, or can be read in the microfrontend by injecting the {@link WorkbenchView} handle.
     *
     * @inheritDoc
     */
    params?: ViewParamDefinition[];
    /**
     * @inheritDoc
     */
    properties: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL specified in the application manifest. If the
         * application does not declare a base URL, it is relative to the origin of the manifest file.
         *
         * The path supports placeholders that will be replaced with parameter values. A placeholder
         * starts with a colon (`:`) followed by the parameter name.
         *
         * Usage:
         * ```json
         * {
         *   "type": "view",
         *   "qualifier": {"entity": "product"},
         *   "params": [
         *     {"name": "id", "required":  true, "description": "Identifies the product."}
         *   ],
         *   "properties": {
         *     "path": "product/:id",
         *     ...
         *   }
         * }
         * ```
         */
        path: string;
        /**
         * Specifies the title of this view.
         *
         * The title supports placeholders that will be replaced with parameter values. A placeholder starts with a colon (`:`) followed by the parameter name.
         * The title can also be set in the microfrontend via {@link WorkbenchView} handle.
         */
        title?: string;
        /**
         * Specifies the subtitle of this view.
         *
         * The heading supports placeholders that will be replaced with parameter values. A placeholder starts with a colon (`:`) followed by the parameter name.
         * The heading can also be set in the microfrontend via {@link WorkbenchView} handle.
         */
        heading?: string;
        /**
         * Specifies if to display a close button in the view tab. Defaults to `true`.
         */
        closable?: boolean;
        /**
         * Instructs the workbench to show a splash, such as a skeleton or loading indicator, until the view microfrontend signals readiness.
         *
         * By default, the workbench shows a loading indicator. A custom splash can be configured in the workbench host application.
         *
         * @see WorkbenchView.signalReady
         */
        showSplash?: boolean;
        /**
         * Specifies CSS class(es) to add to the view, e.g., to locate the view in tests.
         */
        cssClass?: string | string[];
        /**
         * Arbitrary metadata associated with the capability.
         */
        [key: string]: unknown;
    };
}
/**
 * Describes a parameter to be passed along with a view intent.
 *
 * @category View
 * @inheritDoc
 */
interface ViewParamDefinition extends ParamDefinition {
    /**
     * Controls how the workbench router should pass this parameter to the workbench view.
     *
     * By default, parameters are passed via the workbench URL as matrix parameters.
     * Marking a parameter as "transient" instructs the router to pass it via navigational state, useful for large objects.
     *
     * Transient parameters are not persistent, they are only added to the browser's session history to support back/forward browser navigation.
     * Microfrontends must be able to restore state without relying on transient parameters.
     */
    transient?: boolean;
    /**
     * @inheritDoc
     */
    [property: string]: any;
}

/**
 * A view is a visual workbench element for displaying content stacked or side-by-side in the workbench layout.
 *
 * Users can drag views from one part to another, even across windows, or place them side-by-side, horizontally and vertically.
 *
 * The view microfrontend can inject this handle to interact with the view.
 *
 * @category View
 * @see WorkbenchViewCapability
 * @see WorkbenchRouter
 */
declare abstract class WorkbenchView {
    /**
     * Represents the identity of this view.
     */
    abstract readonly id: ViewId;
    /**
     * Signals readiness, notifying the workbench that this view has completed initialization.
     *
     * If `showSplash` is set to `true` on the view capability, the workbench displays a splash until the view microfrontend signals readiness.
     *
     * @see WorkbenchViewCapability.properties.showSplash
     */
    abstract signalReady(): void;
    /**
     * Provides the capability of the microfrontend loaded into the view.
     *
     * Upon subscription, emits the microfrontend's capability, and then emits continuously when navigating to a different microfrontend
     * of the same application. It completes when navigating to a microfrontend of another application.
     */
    abstract readonly capability$: Observable<WorkbenchViewCapability>;
    /**
     * Provides the parameters of the microfrontend loaded into the view.
     *
     * Upon subscription, emits the microfrontend's parameters, and then emits continuously when the parameters change.
     * The Observable completes when navigating to a microfrontend of another application, but not when navigating to a different microfrontend
     * of the same application.
     */
    abstract readonly params$: Observable<ReadonlyMap<string, any>>;
    /**
     * The current snapshot of this view.
     */
    abstract readonly snapshot: ViewSnapshot;
    /**
     * Indicates whether this view is active.
     *
     * Upon subscription, emits the active state of this view, and then emits continuously when it changes.
     * The Observable completes when navigating to a microfrontend of another application, but not when navigating to a different microfrontend
     * of the same application.
     */
    abstract readonly active$: Observable<boolean>;
    /**
     * Provides the identity of the part that contains this view.
     *
     * Upon subscription, emits the identity of this view's part, and then emits continuously when it changes.
     * The Observable completes when navigating to a microfrontend of another application, but not when navigating to a different microfrontend
     * of the same application.
     */
    abstract readonly partId$: Observable<string>;
    /**
     * Sets the title to be displayed in the view tab.
     */
    abstract setTitle(title: string | Observable<string>): void;
    /**
     * Sets the subtitle to be displayed in the view tab.
     */
    abstract setHeading(heading: string | Observable<string>): void;
    /**
     * Sets whether this view is dirty or pristine. When navigating to another microfrontend, the view's dirty state is set to pristine.
     *
     * You can provide the dirty/pristine state either as a boolean or as Observable. If you pass an Observable, it will be unsubscribed when
     * navigating to another microfrontend, whether from the same app or a different one.
     *
     * If not passing an argument, the view is marked as dirty. To mark it as pristine, you need to pass `false`.
     */
    abstract markDirty(dirty?: boolean | Observable<boolean>): void;
    /**
     * Controls whether the user should be allowed to close this workbench view.
     *
     * You can provide either a boolean or Observable. If you pass an Observable, it will be unsubscribed when navigating to another microfrontend,
     * whether from the same app or a different one.
     */
    abstract setClosable(closable: boolean | Observable<boolean>): void;
    /**
     * Initiates the closing of this workbench view.
     */
    abstract close(): void;
    /**
     * Registers a guard to confirm closing the view, replacing any previous guard.
     *
     * Example:
     * ```ts
     * Beans.get(WorkbenchView).canClose(async () => {
     *   const action = await Beans.get(WorkbenchMessageBoxService).open('Do you want to save changes?', {
     *     actions: {
     *       yes: 'Yes',
     *       no: 'No',
     *       cancel: 'Cancel'
     *     }
     *   });
     *
     *   switch (action) {
     *     case 'yes':
     *       // Store changes ...
     *       return true;
     *     case 'no':
     *       return true;
     *     default:
     *       return false;
     *   }
     * });
     * ```
     *
     * @param canClose - Callback to confirm closing the view.
     * @returns Reference to the `CanClose` guard, which can be used to unregister the guard.
     */
    abstract canClose(canClose: CanCloseFn): CanCloseRef;
}
/**
 * The signature of a function to confirm closing a view., e.g., if dirty.
 */
type CanCloseFn = () => Observable<boolean> | Promise<boolean> | boolean;
/**
 * Reference to the `CanClose` guard registered on a view.
 */
interface CanCloseRef {
    /**
     * Removes the `CanClose` guard from the view.
     *
     * Has no effect if another guard was registered in the meantime.
     */
    dispose(): void;
}
/**
 * Provides information about a view displayed at a particular moment in time.
 *
 * @category View
 */
interface ViewSnapshot {
    /**
     * Parameters of the microfrontend loaded into the view.
     */
    params: ReadonlyMap<string, any>;
    /**
     * The identity of the part that contains the view.
     */
    partId: string;
}
/**
 * Format of a view identifier.
 *
 * Each view is assigned a unique identifier (e.g., `view.1`, `view.2`, etc.).
 *
 * @category View
 */
type ViewId = `view.${number}`;

declare class ɵWorkbenchView implements WorkbenchView, PreDestroy {
    id: ViewId;
    private _propertyChange$;
    private _destroy$;
    /**
     * Observable that emits when the application loaded into the current view receives an unloading event,
     * i.e., is just about to be replaced by a microfrontend of another application.
     */
    private _beforeUnload$;
    /**
     * Observable that emits before navigating to a different microfrontend of the same app.
     */
    private _beforeInAppNavigation$;
    private _canCloseFn;
    private _canCloseSubscription;
    active$: Observable<boolean>;
    partId$: Observable<string>;
    params$: Observable<ReadonlyMap<string, any>>;
    capability$: Observable<WorkbenchViewCapability>;
    whenProperties: Promise<void>;
    snapshot: ViewSnapshot;
    constructor(id: ViewId);
    /** @inheritDoc */
    signalReady(): void;
    /** @inheritDoc */
    setTitle(title: string | Observable<string>): void;
    /** @inheritDoc */
    setHeading(heading: string | Observable<string>): void;
    /** @inheritDoc */
    markDirty(dirty: undefined | boolean | Observable<boolean>): void;
    /** @inheritDoc */
    setClosable(closable: boolean | Observable<boolean>): void;
    /** @inheritDoc */
    close(): void;
    /** @inheritDoc */
    canClose(canClose: CanCloseFn): CanCloseRef;
    preDestroy(): void;
}
/**
 * Context key to retrieve the view ID for microfrontends embedded in the context of a workbench view.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 * @see {@link ContextService}
 */
declare const ɵVIEW_ID_CONTEXT_KEY = "\u0275workbench.view.id";

/**
 * Defines command endpoints for the communication between SCION Workbench and SCION Workbench Client.
 *
 * @docs-private Not public API, intended for internal use only.
 */
declare const ɵWorkbenchCommands: {
    /**
     * Computes the topic via which the title of a workbench view tab can be set.
     */
    readonly viewTitleTopic: (viewId: ViewId | ":viewId") => string;
    /**
     * Computes the topic via which the heading of a workbench view tab can be set.
     */
    readonly viewHeadingTopic: (viewId: ViewId | ":viewId") => string;
    /**
     * Computes the topic via which a view tab can be marked dirty or pristine.
     */
    readonly viewDirtyTopic: (viewId: ViewId | ":viewId") => string;
    /**
     * Computes the topic via which a view tab can be made closable.
     */
    readonly viewClosableTopic: (viewId: ViewId | ":viewId") => string;
    /**
     * Computes the topic via which a view can be closed.
     */
    readonly viewCloseTopic: (viewId: ViewId | ":viewId") => string;
    /**
     * Computes the topic to notify the active state of a view.
     *
     * The active state is published as a retained message.
     */
    readonly viewActiveTopic: (viewId: ViewId) => string;
    /**
     * Computes the topic to notify the part of a view.
     *
     * The part identity is published as a retained message.
     */
    readonly viewPartIdTopic: (viewId: ViewId) => string;
    /**
     * Computes the topic to request closing confirmation of a view.
     *
     * When closing a view and if the microfrontend has subscribed to this topic, the workbench requests closing confirmation
     * via this topic. By sending a `true` reply, the workbench continues with closing the view, by sending a `false` reply,
     * closing is prevented.
     */
    readonly canCloseTopic: (viewId: ViewId) => string;
    /**
     * Computes the topic for signaling that a microfrontend is about to be replaced by a microfrontend of another app.
     */
    readonly viewUnloadingTopic: (viewId: ViewId) => string;
    /**
     * Computes the topic for updating params of a microfrontend view.
     */
    readonly viewParamsUpdateTopic: (viewId: ViewId, viewCapabilityId: string) => string;
    /**
     * Computes the topic for providing params to a view microfrontend.
     *
     * Params include the {@link ɵMicrofrontendRouteParams#ɵVIEW_CAPABILITY_ID capability id}, params as passed in {@link WorkbenchNavigationExtras.params},
     * and the view qualifier.
     *
     * Params are published as a retained message.
     */
    readonly viewParamsTopic: (viewId: ViewId) => string;
    /**
     * Computes the topic for observing the popup origin.
     */
    readonly popupOriginTopic: (popupId: string) => string;
    /**
     * Computes the topic via which a popup can be closed.
     */
    readonly popupCloseTopic: (popupId: string) => string;
    /**
     * Computes the topic via which to set a result
     */
    readonly popupResultTopic: (popupId: string) => string;
    /**
     * Computes the topic via which the title of a dialog can be set.
     */
    readonly dialogTitleTopic: (dialogId: string) => string;
    /**
     * Computes the topic via which a dialog can be closed.
     */
    readonly dialogCloseTopic: (dialogId: string) => string;
};

/**
 * Represents a point on the page or view, optionally with a dimension, where a workbench popup should be attached.
 *
 * @category Popup
 */
type PopupOrigin = (Point | TopLeftPoint | TopRightPoint | BottomLeftPoint | BottomRightPoint) & {
    width?: number;
    height?: number;
};
/**
 * Coordinate relative to the "x/y" corner of the view or page viewport.
 *
 * @category Popup
 */
interface Point {
    x: number;
    y: number;
}
/**
 * Coordinate relative to the "top/left" corner of the view or page viewport.
 *
 * This is equivalent to passing a "x/y" coordinate as {@link Point}.
 *
 * @category Popup
 */
interface TopLeftPoint {
    top: number;
    left: number;
}
/**
 * Coordinate relative to the "top/right" corner of the view or page viewport.
 *
 * @category Popup
 */
interface TopRightPoint {
    top: number;
    right: number;
}
/**
 * Coordinate relative to the "bottom/left" corner of the view or page viewport.
 *
 * @category Popup
 */
interface BottomLeftPoint {
    bottom: number;
    left: number;
}
/**
 * Coordinate relative to the "bottom/right" corner of the view or page viewport.
 *
 * @category Popup
 */
interface BottomRightPoint {
    bottom: number;
    right: number;
}

/**
 * Configures the popup to display a microfrontend in a workbench popup using {@link WorkbenchPopupService}.
 *
 * @category Popup
 */
interface WorkbenchPopupConfig {
    /**
     * Controls where to open the popup.
     *
     * Can be an HTML element or coordinates:
     * - Using an element: The popup opens and sticks to the element.
     * - Using coordinates: The popup opens and sticks relative to the view or page bounds.
     *
     * Supported coordinate pairs:
     * - x/y: Relative to the top/left corner of the view or page.
     * - top/left: Same as x/y.
     * - top/right: Relative to the top/right corner.
     * - bottom/left: Relative to the bottom/left corner.
     * - bottom/right: Relative to the bottom/right corner.
     *
     * Coordinates can be updated using an Observable. The popup displays when the Observable emits the first coordinate.
     */
    anchor: Element | PopupOrigin | Observable<PopupOrigin>;
    /**
     * Passes data to the popup.
     *
     * The popup can declare mandatory and optional parameters. No additional parameters are allowed. Refer to the documentation of the capability for more information.
     */
    params?: Map<string, any> | Dictionary;
    /**
     * Hint where to align the popup relative to the popup anchor, unless there is not enough space available in that area. By default,
     * if not specified, the popup opens north of the anchor.
     */
    align?: 'east' | 'west' | 'north' | 'south';
    /**
     * Controls when to close the popup.
     */
    closeStrategy?: CloseStrategy;
    /**
     * Specifies CSS class(es) to add to the popup, e.g., to locate the popup in tests.
     */
    cssClass?: string | string[];
    /**
     * Specifies the context in which to open the popup.
     */
    context?: {
        /**
         * Specifies the view the popup belongs to.
         *
         * Binds the popup to the lifecycle of a view so that it displays only if the view is active and closes when the view is closed.
         *
         * By default, if opening the popup in the context of a view, that view is used as the popup's contextual view.
         * If you set the view id to `null`, the popup will open without referring to the contextual view.
         */
        viewId?: ViewId | null;
    };
}
/**
 * Specifies when to close the popup.
 *
 * @category Popup
 */
interface CloseStrategy {
    /**
     * Controls if to close the popup on focus loss, returning the result set via {@link Popup#setResult} to the popup opener.
     * Defaults to `true`.
     */
    onFocusLost?: boolean;
    /**
     * Controls if to close the popup when pressing escape. Defaults to `true`.
     * No return value will be passed to the popup opener.
     */
    onEscape?: boolean;
}

/**
 * Command object for instructing the Workbench to open the microfrontend of given popup capability in a popup.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 */
interface ɵWorkbenchPopupCommand {
    popupId: string;
    align?: 'east' | 'west' | 'north' | 'south';
    closeStrategy?: CloseStrategy;
    cssClass?: string | string[];
    context?: {
        viewId?: ViewId | null;
    };
}

/**
 * Displays a microfrontend in a popup.
 *
 * A popup is a visual workbench component for displaying content above other content. It is positioned relative to an anchor and
 * moves when the anchor moves. Unlike a dialog, the popup closes on focus loss.
 *
 * A microfrontend provided as a `popup` capability can be opened in a popup. The qualifier differentiates between different
 * popup capabilities. An application can open the public popup capabilities of other applications if it manifests a respective
 * intention.
 *
 * @category Popup
 * @see WorkbenchPopupCapability
 */
declare class WorkbenchPopupService {
    /**
     * Displays a microfrontend in a workbench popup based on the given qualifier.
     *
     * The qualifier identifies the microfrontend to display in the popup.
     *
     * The anchor is used to position the popup based on its preferred alignment:
     * - Using an element: The popup opens and sticks to the element.
     * - Using coordinates: The popup opens and sticks relative to the view or page bounds.
     *
     * If the popup is opened within a view, it only displays if the view is active and closes when the view is closed.
     *
     * By default, the popup closes on focus loss or when pressing the escape key.
     *
     * Pass data to the popup using parameters. Only declared parameters are allowed. Refer to the capability documentation for details.
     *
     * @param  qualifier - Identifies the popup capability that provides the microfrontend for display as popup.
     * @param  config - Controls popup behavior.
     * @returns Promise that resolves to the popup result, if any, or that rejects if the popup was closed with an error or couldn't be opened,
     *          e.g., because of missing the intention or because no `popup` capability matching the qualifier and visible to the application
     *          was found.
     */
    open<T>(qualifier: Qualifier, config: WorkbenchPopupConfig): Promise<T | undefined>;
    /**
     * Observes the position of the popup anchor.
     *
     * The Observable emits the anchor's initial position, and each time its position changes.
     * The Observable never completes.
     */
    private observePopupOrigin$;
}

/**
 * Represents a microfrontend for display in a workbench popup.
 *
 * A popup is a visual workbench component for displaying content above other content.
 *
 * Unlike views, popups are not part of the persistent workbench navigation, meaning that popups do not survive a page reload.
 *
 * @category Popup
 */
interface WorkbenchPopupCapability extends Capability {
    type: WorkbenchCapabilities.Popup;
    /**
     * Qualifies this popup. The qualifier is required for popups.
     */
    qualifier: Qualifier;
    properties: {
        /**
         * Specifies the path of the microfrontend to be opened when navigating to this popup capability.
         *
         * The path is relative to the base URL, as specified in the application manifest. If the
         * application does not declare a base URL, it is relative to the origin of the manifest file.
         *
         * In the path, you can reference qualifier and parameter values in the form of named parameters.
         * Named parameters begin with a colon (`:`) followed by the parameter or qualifier name, and are allowed in path segments, query parameters, matrix parameters
         * and the fragment part. The popup router will substitute named parameters in the URL accordingly.
         *
         * In addition to using qualifier and parameter values as named parameters in the URL, params are available in the microfrontend via {@link WorkbenchPopup.params} object.
         *
         * #### Usage of named parameters in the path:
         * ```json
         * {
         *   "type": "popup",
         *   "qualifier": {"entity": "product"},
         *   "params": [
         *     {"name": "id", "required":  true, "description": "Identifies the product."}
         *   ],
         *   "properties": {
         *     "path": "product/:id",
         *     ...
         *   }
         * }
         * ```
         *
         * #### Path parameter example:
         * segment/:param1/segment/:param2
         *
         * #### Matrix parameter example:
         * segment/segment;matrixParam1=:param1;matrixParam2=:param2
         *
         * #### Query parameter example:
         * segment/segment?queryParam1=:param1&queryParam2=:param2
         */
        path: string;
        /**
         * Specifies the preferred popup size.
         *
         * If not set, the popup will adjust its size to the content size reported by the embedded content using {@link @scion/microfrontend-platform!PreferredSizeService}.
         * Note that the microfrontend may take some time to load, causing the popup to flicker when opened. Therefore, for fixed-sized popups,
         * consider declaring the popup size in the popup capability.
         */
        size?: PopupSize;
        /**
         * Instructs the workbench to show a splash, such as a skeleton or loading indicator, until the popup microfrontend signals readiness.
         *
         * By default, the workbench shows a loading indicator. A custom splash can be configured in the workbench host application.
         *
         * @see WorkbenchPopup.signalReady
         */
        showSplash?: boolean;
        /**
         * Specifies CSS class(es) to add to the popup, e.g., to locate the popup in tests.
         */
        cssClass?: string | string[];
        /**
         * Arbitrary metadata associated with the capability.
         */
        [key: string]: unknown;
    };
}
/**
 * Represents the preferred popup size.
 */
interface PopupSize {
    /**
     * Specifies the min-height of the popup.
     */
    minHeight?: string;
    /**
     * Specifies the height of the popup.
     */
    height?: string;
    /**
     * Specifies the max-height of the popup.
     */
    maxHeight?: string;
    /**
     * Specifies the min-width of the popup.
     */
    minWidth?: string;
    /**
     * Specifies the width of the popup.
     */
    width?: string;
    /**
     * Specifies the max-width of the popup.
     */
    maxWidth?: string;
}

/**
 * Information about the context in which a popup was opened.
 *
 * @category Popup
 */
interface WorkbenchPopupReferrer {
    /**
     * Identity of the view if opened in the context of a view.
     */
    viewId?: ViewId;
    /**
     * Identity of the view capability if opened in the context of a view microfrontend.
     */
    viewCapabilityId?: string;
}

/**
 * Context when displaying a microfrontend in a popup.
 *
 * This object can be obtained from the {@link ContextService} using the name {@link ɵPOPUP_CONTEXT}.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 */
interface ɵPopupContext {
    popupId: string;
    params: Map<string, any>;
    capability: WorkbenchPopupCapability;
    closeOnFocusLost: boolean;
    referrer: WorkbenchPopupReferrer;
}
/**
 * Key for obtaining the current popup context using {@link ContextService}.
 *
 * The popup context is only available to microfrontends loaded in a workbench popup.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 * @see {@link ContextService}
 * @see {@link ɵPopupContext}
 */
declare const ɵPOPUP_CONTEXT = "\u0275workbench.popup";

/**
 * A popup is a visual workbench component for displaying content above other content.
 *
 * If a microfrontend lives in the context of a workbench popup, regardless of its embedding level, it can inject an instance
 * of this class to interact with the workbench popup, such as reading passed parameters or closing the popup.
 *
 * #### Preferred Size
 * You can report preferred popup size using {@link @scion/microfrontend-platform!PreferredSizeService}. Typically, you would
 * subscribe to size changes of the microfrontend's primary content and report it. As a convenience, {@link @scion/microfrontend-platform!PreferredSizeService}
 * provides API to pass an element for automatic dimension monitoring. If your content can grow and shrink, e.g., if using expandable
 * panels, consider positioning primary content out of the document flow, that is, setting its position to `absolute`. This way,
 * you give it infinite space so that it can always be rendered at its preferred size.
 *
 * ```typescript
 * Beans.get(PreferredSizeService).fromDimension(<HTMLElement>);
 * ```
 *
 * Note that the microfrontend may take some time to load, causing the popup to flicker when opened. Therefore, for fixed-sized
 * popups, consider declaring the popup size in the popup capability.
 *
 * @category Popup
 */
declare abstract class WorkbenchPopup<R = unknown> {
    /**
     * Capability that represents the microfrontend loaded into this workbench popup.
     */
    abstract readonly capability: WorkbenchPopupCapability;
    /**
     * Signals readiness, notifying the workbench that this popup has completed initialization.
     *
     * If `showSplash` is set to `true` on the popup capability, the workbench displays a splash until the popup microfrontend signals readiness.
     *
     * @see WorkbenchPopupCapability.properties.showSplash
     */
    abstract signalReady(): void;
    /**
     * Provides information about the context in which this popup was opened.
     */
    abstract readonly referrer: WorkbenchPopupReferrer;
    /**
     * Parameters including qualifier entries as passed for navigation by the popup opener.
     */
    abstract readonly params: Map<string, any>;
    /**
     * Sets a result that will be passed to the popup opener when the popup is closed on focus loss {@link CloseStrategy#onFocusLost}.
     */
    abstract setResult(result?: R): void;
    /**
     * Closes the popup. Optionally, pass a result or an error to the popup opener.
     */
    abstract close(result?: R | Error): void;
}
/**
 * Message headers to interact with the workbench popup.
 *
 * @docs-private Not public API, intended for internal use only.
 * @ignore
 */
declare enum ɵWorkbenchPopupMessageHeaders {
    CLOSE_WITH_ERROR = "\u0275WORKBENCH-POPUP:CLOSE_WITH_ERROR"
}

/**
 * Represents a microfrontend for display in a workbench dialog.
 *
 * A dialog is a visual element for focused interaction with the user, such as prompting the user for input or confirming actions.
 * The user can move or resize a dialog.
 *
 * Displayed on top of other content, a dialog blocks interaction with other parts of the application. Multiple dialogs are stacked,
 * and only the topmost dialog in each modality stack can be interacted with.
 *
 * The microfrontend can inject the {@link WorkbenchDialog} handle to interact with the dialog, such as setting the title, reading
 * parameters, or closing it.
 *
 * If provided by the workbench host application, the dialog has a footer and resizes to fit its content. See the documentation of
 * `WorkbenchDialogService` in `@scion/workbench` for more information on adding actions to the footer.
 *
 * Dialogs from other applications must specify their size using {@link WorkbenchDialogCapability.properties.size} and add
 * the footer in the microfrontend.
 *
 * @category Dialog
 * @see WorkbenchDialog
 * @see WorkbenchDialogService
 */
interface WorkbenchDialogCapability extends Capability {
    /**
     * @inheritDoc
     */
    type: WorkbenchCapabilities.Dialog;
    /**
     * Qualifies this dialog. The qualifier is required for dialogs.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * Specifies parameters required by the dialog.
     *
     * Parameters are available in the path and title for placeholder substitution, or can be read in the microfrontend by injecting the {@link WorkbenchDialog} handle.
     *
     * @inheritDoc
     */
    params?: ParamDefinition[];
    /**
     * @inheritDoc
     */
    properties: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL specified in the application manifest. If the
         * application does not declare a base URL, it is relative to the origin of the manifest file.
         *
         * The path supports placeholders that will be replaced with parameter values. A placeholder
         * starts with a colon (`:`) followed by the parameter name.
         *
         * Usage:
         * ```json
         * {
         *   "type": "dialog",
         *   "qualifier": {"entity": "product"},
         *   "params": [
         *     {"name": "id", "required":  true, "description": "Identifies the product."}
         *   ],
         *   "properties": {
         *     "path": "product/:id",
         *     ...
         *   }
         * }
         * ```
         */
        path: string;
        /**
         * Specifies the size of this dialog, required if this dialog is provided by an application other than the workbench host application.
         */
        size?: WorkbenchDialogSize;
        /**
         * Specifies the title of this dialog.
         *
         * The title supports placeholders that will be replaced with parameter values. A placeholder starts with a colon (`:`) followed by the parameter name.
         * The title can also be set in the microfrontend via {@link WorkbenchDialog} handle.
         */
        title?: string;
        /**
         * Specifies if to display a close button in the dialog header. Defaults to `true`.
         */
        closable?: boolean;
        /**
         * Specifies if the user can resize the dialog. Defaults to `true`.
         */
        resizable?: boolean;
        /**
         * Controls if to apply a padding to the content of the dialog.
         *
         * By default, dialogs provided by the workbench host application have a padding, others do not.
         */
        padding?: boolean;
        /**
         * Instructs the workbench to show a splash, such as a skeleton or loading indicator, until the dialog microfrontend signals readiness.
         *
         * By default, the workbench shows a loading indicator. A custom splash can be configured in the workbench host application.
         *
         * @see WorkbenchDialog.signalReady
         */
        showSplash?: boolean;
        /**
         * Specifies CSS class(es) to add to the dialog, e.g., to locate the dialog in tests.
         */
        cssClass?: string | string[];
        /**
         * Arbitrary metadata associated with the capability.
         */
        [key: string]: unknown;
    };
}
/**
 * Specifies the dialog size.
 */
interface WorkbenchDialogSize {
    /**
     * Specifies the height of the dialog, required if this dialog is provided by an application other than the workbench host application.
     */
    height?: string;
    /**
     * Specifies the width of the dialog, required if this dialog is provided by an application other than the workbench host application.
     */
    width?: string;
    /**
     * Specifies the minimum height of the dialog.
     */
    minHeight?: string;
    /**
     * Specifies the maximum height of the dialog.
     */
    maxHeight?: string;
    /**
     * Specifies the minimum width of the dialog.
     */
    minWidth?: string;
    /**
     * Specifies the maximum width of the dialog.
     */
    maxWidth?: string;
}

/**
 * Handle to interact with a dialog opened via {@link WorkbenchDialogService}.
 *
 * The dialog microfrontend can inject this handle to interact with the dialog, such as setting the title,
 * reading parameters, or closing it.
 *
 * @category Dialog
 * @see WorkbenchDialogCapability
 * @see WorkbenchDialogService
 */
declare abstract class WorkbenchDialog<R = unknown> {
    /**
     * Capability of the microfrontend loaded into this dialog.
     */
    abstract readonly capability: WorkbenchDialogCapability;
    /**
     * Parameters as passed by the dialog opener.
     */
    abstract readonly params: Map<string, unknown>;
    /**
     * Sets the title of the dialog.
     */
    abstract setTitle(title: string | Observable<string>): void;
    /**
     * Signals readiness, notifying the workbench that this dialog has completed initialization.
     *
     * If `showSplash` is set to `true` on the dialog capability, the workbench displays a splash until the dialog microfrontend signals readiness.
     *
     * @see WorkbenchDialogCapability.properties.showSplash
     */
    abstract signalReady(): void;
    /**
     * Closes the dialog. Optionally, pass a result or an error to the dialog opener.
     */
    abstract close(result?: R | Error): void;
}

/**
 * Configures the dialog to display a microfrontend in a workbench dialog using {@link WorkbenchDialogService}.
 *
 * @category Dialog
 */
interface WorkbenchDialogOptions {
    /**
     * Passes data to the dialog.
     *
     * The dialog can declare mandatory and optional parameters. No additional paramet