@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, Capability, Qualifier, ParamDefinition } from '@scion/microfrontend-platform';
import { Observable } from 'rxjs';
import { Dictionary } from '@scion/toolkit/util';
import { PreDestroy } from '@scion/toolkit/bean-manager';

/**
 * Represents an object that can be disposed of to free up resources.
 */
interface Disposable {
    /**
     * Disposes of the object, releasing any allocated resources.
     */
    dispose(): void;
}

/**
 * Built-in workbench capabilities.
 */
declare enum WorkbenchCapabilities {
    /**
     * Contributes a workbench part.
     *
     * A part is a visual element of the workbench layout. Parts can be docked to the side or
     * positioned relative to each other. A part can display content or stack views.
     */
    Part = "part",
    /**
     * Contributes a workbench view.
     *
     * A view is a visual element of the workbench layout for displaying content stacked or side-by-side.
     */
    View = "view",
    /**
     * Contributes a workbench perspective.
     *
     * A perspective defines an arrangement of parts and views. Users can switch between perspectives. Perspectives share the same main area, if any.
     */
    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",
    /**
     * Provides texts to the SCION Workbench and micro apps.
     */
    TextProvider = "text-provider"
}

/**
 * Signature of a function to provide texts to the SCION Workbench and micro apps.
 *
 * Texts starting with the percent symbol (`%`) are passed to the text provider for translation, with the percent symbol omitted.
 *
 * A text provider can be registered via {@link WorkbenchClient.registerTextProvider} in the Activator.
 *
 * @param key - Translation key of the text.
 * @param params - Parameters used for text interpolation.
 * @return Text associated with the key, or `undefined` if not found.
 *         Localized applications should return an Observable with the text in the current language, and emit the translated text each time when the language changes.
 *
 * @category Localization
 */
type WorkbenchTextProviderFn = (key: string, params: {
    [name: string]: string;
}) => Observable<string | undefined> | string | undefined;
/**
 * Represents either a text or a key for translation.
 *
 * A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
 *
 * Key and parameters are passed to the registered text provider for translation. Applications can register a text provider
 * using {@link WorkbenchClient.registerTextProvider}.
 *
 * Semicolons in interpolation parameters must be escaped with two backslashes (`\\;`).
 *
 * Examples:
 * - `%key`: translation key
 * - `%key;param=value`: translation key with a single interpolation parameter
 * - `%key;param1=value1;param2=value2`: translation key with multiple interpolation parameters
 * - `text`: no translation key, text is returned as is
 *
 * @category Localization
 */
type Translatable = string | `%${string}`;

/**
 * **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 WorkbenchPart} for the microfrontend to interact with the part.
 * - {@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>;
    /**
     * Provides texts to the SCION Workbench and micro apps.
     *
     * A text provider is a function that returns the text for a translation key.
     *
     * Texts starting with the percent symbol (`%`) are passed to the text provider for translation, with the percent symbol omitted.
     *
     * This function must be called in an Activator. Refer to {@link @scion/microfrontend-platform!ActivatorCapability} for details on activators.
     *
     * Applications can use {@link WorkbenchTextService} to get texts from other micro applications.
     *
     * @param textProvider - Function to provide the text for a translation key.
     * @return Object to unregister the text provider.
     */
    static registerTextProvider(textProvider: WorkbenchTextProviderFn): Disposable;
}

/**
 * A part is a visual element of the workbench layout. Parts can be docked to the side or positioned relative to each other.
 * A part can display content or stack views.
 *
 * The arrangement of parts is defined in a {@link WorkbenchPerspectiveCapability}. Each part defined in the perspective references
 * a part capability to contribute content, either a microfrontend, a stack of views, or both. If both, the microfrontend is displayed
 * only if the view stack is empty. Views in a docked part cannot be dragged into or out of docked parts.
 *
 * The part microfrontend can inject the {@link WorkbenchPart} handle to interact with the part.
 *
 * @category Part
 * @see WorkbenchPart
 */
interface WorkbenchPartCapability extends Capability {
    /**
     * @inheritDoc
     */
    type: WorkbenchCapabilities.Part;
    /**
     * Qualifies this part. The qualifier is required for a part.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * Specifies parameters required by this part.
     *
     * Parameters can be read in the microfrontend by injecting the {@link WorkbenchPart} handle, or referenced in path, title, label, tooltip and resolvers using the colon syntax.
     *
     * @inheritDoc
     */
    params?: ParamDefinition[];
    /**
     * @inheritDoc
     */
    properties?: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL given in the application manifest, or to the origin of the manifest file if no base URL is specified.
         *
         * Path segments can reference capability parameters using the colon syntax.
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "read", "required": false}
         *   ],
         *   "properties": {
         *     "path": "tasks?read=:read", // `:read` references a capability parameter
         *   }
         * }
         * ```
         *
         * If the part contains views, the microfrontend is displayed only if the view stack is empty.
         */
        path?: string;
        /**
         * Specifies views to stack in the part.
         *
         * Microfrontends provided as view capability can be referenced. Views are stacked in declaration order.
         *
         * Declaring an intention allows for referencing public view capabilities of other applications. If a view capability cannot be resolved, the view
         * is omitted, allowing conditional display, for example, based on user permissions.
         *
         * If a docked part, views cannot be dragged in or out.
         */
        views?: WorkbenchViewRef[];
        /**
         * Specifies the title displayed in the part bar.
         *
         * Defaults to {@link extras.label} if a docked part. Set to `false` to not display a title.
         *
         * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
         *
         * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
         */
        title?: Translatable | false;
        /**
         * Controls the appearance of a docked part and its toggle button.
         *
         * A docked part is a part that is docked to the left, right, or bottom side of the workbench.
         *
         * This property only applies to docked parts. The perspective determines whether a part is docked or positioned relative to another part.
         */
        extras?: DockedPartExtras;
        /**
         * Defines resolvers for use in the title, label and tooltip.
         *
         * A resolver defines a topic where a request is sent to resolve text or a translation key, typically based on capability parameters. Topic segments can reference capability parameters using the colon syntax.
         *
         * The application can respond to resolve requests by installing a message listener in the activator. Refer to {@link ActivatorCapability} for registering an activator.
         *
         * @example - Message listener replying to resolve requests
         *
         * ```ts
         * import {Beans} from '@scion/toolkit/bean-manager';
         * import {MessageClient} from '@scion/microfrontend-platform';
         *
         * Beans.get(MessageClient).onMessage('tasks/count', message => {
         *   return ...;
         * });
         * ```
         */
        resolve?: {
            [name: string]: string;
        };
        /**
         * Instructs the workbench to show a splash, such as a skeleton or loading indicator, until the microfrontend signals readiness.
         *
         * By default, the workbench shows a loading indicator. A custom splash can be configured in the workbench host application.
         *
         * This property only applies to the microfrontend loaded into the part, not views stacked in the part.
         *
         * @see WorkbenchPart.signalReady
         */
        showSplash?: boolean;
        /**
         * Specifies CSS class(es) to add to the part, e.g., to locate the part in tests.
         */
        cssClass?: string | string[];
        /**
         * Arbitrary metadata associated with the capability.
         */
        [key: string]: unknown;
    };
}
/**
 * Controls the appearance of a docked part and its toggle button.
 *
 * A docked part is a part that is docked to the left, right, or bottom side of the workbench.
 */
interface DockedPartExtras {
    /**
     * Specifies the icon (key) displayed in the toggle button.
     *
     * Refer to the documentation of the workbench host application for available icons.
     */
    icon: string;
    /**
     * Specifies the label displayed in the toggle button.
     *
     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
     *
     * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
     */
    label: Translatable;
    /**
     * Specifies the tooltip displayed when hovering over the toggle button.
     *
     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
     *
     * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
     */
    tooltip?: Translatable;
}
/**
 * Describes a view referenced in a part.
 */
interface WorkbenchViewRef {
    /**
     * Specifies the {@link WorkbenchViewCapability} that provides the view microfrontend.
     *
     * Declaring an intention allows for referencing public view capabilities of other applications.
     *
     * If the view capability cannot be resolved, the view is omitted, allowing conditional display, for example, based on user permissions.
     */
    qualifier: Qualifier;
    /**
     * Defines data to pass 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?: {
        [name: string]: unknown;
    };
    /**
     * Controls whether to activate the view. If not specified, activates the first view of the stack.
     */
    active?: boolean;
    /**
     * Specifies CSS class(es) to add to the view, e.g., to locate the view in tests.
     */
    cssClass?: string | string[];
}

/**
 * A part is a visual element of the workbench layout. Parts can be docked to the side or
 * positioned relative to each other. A part can display content or stack views.
 *
 * The part microfrontend can inject this handle to interact with the part.
 *
 * @category Part
 * @see WorkbenchPartCapability
 */
declare abstract class WorkbenchPart {
    /**
     * Unique identity of this part.
     */
    abstract readonly id: PartId;
    /**
     * Signals readiness, notifying the workbench that this part has completed initialization.
     *
     * If `showSplash` is set to `true` on the part capability, the workbench displays a splash until the part microfrontend signals readiness.
     *
     * @see WorkbenchPartCapability.properties.showSplash
     */
    abstract signalReady(): void;
    /**
     * Capability of the microfrontend loaded into the part.
     */
    abstract readonly capability: WorkbenchPartCapability;
    /**
     * Parameters of the microfrontend loaded into the part.
     */
    abstract readonly params: Map<string, unknown>;
    /**
     * Indicates whether this part is active.
     *
     * Upon subscription, emits the active state of this part, and then emits continuously when it changes.
     * The Observable never completes.
     */
    abstract readonly active$: Observable<boolean>;
    /**
     * Indicates whether this part has the focus.
     *
     * Upon subscription, emits the focused state of this part, and then emits continuously when it changes.
     * The Observable never completes.
     */
    abstract readonly focused$: Observable<boolean>;
}

/**
 * A view is a visual element of the workbench layout for displaying content stacked or side-by-side.
 *
 * A view capability can be opened via {@link WorkbenchRouter} or added to a perspective in a {@link WorkbenchPartCapability}.
 *
 * The microfrontend can inject the {@link WorkbenchView} handle to interact with the view.
 *
 * @category View
 * @see WorkbenchView
 */
interface WorkbenchViewCapability extends Capability {
    /**
     * @inheritDoc
     */
    type: WorkbenchCapabilities.View;
    /**
     * Qualifies this view. The qualifier is required for a view.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * Specifies parameters required by the view.
     *
     * Parameters can be read in the microfrontend by injecting the {@link WorkbenchView} handle, or referenced in path, title and resolvers using the colon syntax.
     *
     * @inheritDoc
     */
    params?: ViewParamDefinition[];
    /**
     * @inheritDoc
     */
    properties: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL given in the application manifest, or to the origin of the manifest file if no base URL is specified.
         *
         * Path segments can reference capability parameters using the colon syntax.
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "path": "products/:id", // `:id` references a capability parameter
         *   }
         * }
         * ```
         */
        path: string;
        /**
         * Controls if to load the microfrontend only when activating the view tab.
         *
         * Requires configuration of {@link title} and {@link heading} in the manifest.
         *
         * Defaults to `true`.
         */
        lazy?: boolean;
        /**
         * Specifies the title of the view tab.
         *
         * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
         *
         * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
         *
         * @example - Title referencing a resolver
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "title": ":productName", // `:productName` references a resolver
         *     "resolve": {
         *       "productName": "products/:id/name" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         *
         * @example - Translatable title referencing a resolver in its interpolation parameters
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "title": "%product.title;name=:productName", // `:productName` references a resolver
         *     "resolve": {
         *       "productName": "products/:id/name" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         */
        title?: Translatable;
        /**
         * Specifies the subtitle of the view tab.
         *
         * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
         *
         * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
         *
         * @example - Heading referencing a resolver
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "heading": ":productCategory", // `:productCategory` references a resolver
         *     "resolve": {
         *      "productCategory": "products/:id/category" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         *
         * @example - Translatable heading referencing a resolver in its interpolation parameters
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "heading": "%product_category.title;category=:productCategory", // `:productCategory` references a resolver
         *     "resolve": {
         *       "productCategory": "products/:id/category" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         */
        heading?: Translatable;
        /**
         * Defines resolvers for use in the view title and heading.
         *
         * A resolver defines a topic where a request is sent to resolve text or a translation key, typically based on capability parameters. Topic segments can reference capability parameters using the colon syntax.
         *
         * The application can respond to resolve requests by installing a message listener in the activator. Refer to {@link ActivatorCapability} for registering an activator.
         *
         * @example - Message listener replying to resolve requests
         *
         * ```ts
         * import {Beans} from '@scion/toolkit/bean-manager';
         * import {MessageClient} from '@scion/microfrontend-platform';
         *
         * Beans.get(MessageClient).onMessage('products/:id/name', message => {
         *   const id = message.params.get('id');
         *   return `Product ${id}`;
         * });
         * ```
         */
        resolve?: {
            [name: string]: string;
        };
        /**
         * Controls 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
 */
declare abstract class WorkbenchView {
    /**
     * Unique 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;
    /**
     * 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>;
    /**
     * 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>;
    /**
     * Indicates whether this view has the focus.
     *
     * Upon subscription, emits the focused 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 focused$: Observable<boolean>;
    /**
     * Gets 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<PartId>;
    /**
     * Sets the title to be displayed in the view tab.
     *
     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
     */
    abstract setTitle(title: Translatable): void;
    /**
     * Sets the title to be displayed in the view tab.
     *
     * @deprecated since version 1.0.0-beta.31. To migrate, pass a translatable and provide the text using a text provider registered in `WorkbenchClient.registerTextProvider`.
     */
    abstract setTitle(title: Observable<Translatable>): void;
    /**
     * Sets the subtitle to be displayed in the view tab.
     *
     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
     */
    abstract setHeading(heading: Translatable): void;
    /**
     * Sets the subtitle to be displayed in the view tab.
     *
     * @deprecated since version 1.0.0-beta.31. To migrate, pass a translatable and provide the text using a text provider registered in `WorkbenchClient.registerTextProvider`.
     */
    abstract setHeading(heading: Observable<Translatable>): 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 {
    /**
     * Capability of the microfrontend loaded into the view.
     */
    capability: WorkbenchViewCapability;
    /**
     * Parameters of the microfrontend loaded into the view.
     */
    params: ReadonlyMap<string, any>;
    /**
     * The identity of the part that contains the view.
     */
    partId: PartId;
    /**
     * Indicates whether this view is active.
     */
    active: boolean;
    /**
     * Indicates whether this view has the focus.
     */
    focused: boolean;
}

/**
 * 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 and resize a dialog.
 *
 * Displayed on top of other content, a modal dialog blocks interaction with other parts of the application. A dialog can be context-modal
 * or application-modal. Dialogs are stacked per modality, with only the topmost dialog in each stack being interactive.
 *
 * The microfrontend can inject the {@link WorkbenchDialog} handle to interact with the dialog, such as setting the title, reading
 * parameters, or closing it.
 *
 * Dialogs provided by the workbench host application have a footer and resize to fit content. See the documentation of `WorkbenchDialogService`
 * in `@scion/workbench` for more information on adding actions to the footer.
 *
 * Dialogs provided by other applications must specify an explicit size in {@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 a dialog.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * Specifies parameters required by the dialog.
     *
     * Parameters can be read in the microfrontend by injecting the {@link WorkbenchDialog} handle, or referenced in path, title and resolvers using the colon syntax.
     *
     * @inheritDoc
     */
    params?: ParamDefinition[];
    /**
     * @inheritDoc
     */
    properties: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL given in the application manifest, or to the origin of the manifest file if no base URL is specified.
         *
         * Path segments can reference capability parameters using the colon syntax.
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "path": "products/:id", // `:id` references a capability parameter
         *   }
         * }
         * ```
         */
        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.
         *
         * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
         *
         * Text and interpolation parameters can reference capability parameters and resolvers using the colon syntax. See {@link resolve} for defining resolvers.
         *
         * @example - Title referencing a resolver
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "title": ":productName", // `:productName` references a resolver
         *     "resolve": {
         *       "productName": "products/:id/name" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         *
         * @example - Translatable title referencing a resolver in its interpolation parameters
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "title": "%product.title;name=:productName", // `:productName` references a resolver
         *     "resolve": {
         *       "productName": "products/:id/name" // `:id` references a capability parameter
         *     }
         *   }
         * }
         * ```
         */
        title?: Translatable;
        /**
         * Defines resolvers for use in the dialog title.
         *
         * A resolver defines a topic where a request is sent to resolve text or a translation key, typically based on capability parameters. Topic segments can reference capability parameters using the colon syntax.
         *
         * The application can respond to resolve requests by installing a message listener in the activator. Refer to {@link ActivatorCapability} for registering an activator.
         *
         * @example - Message listener replying to resolve requests
         *
         * ```ts
         * import {Beans} from '@scion/toolkit/bean-manager';
         * import {MessageClient} from '@scion/microfrontend-platform';
         *
         * Beans.get(MessageClient).onMessage('products/:id/name', message => {
         *   const id = message.params.get('id');
         *   return `Product ${id}`;
         * });
         * ```
         */
        resolve?: {
            [name: string]: 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> {
    /**
     * Represents the identity of this dialog.
     */
    abstract readonly id: DialogId;
    /**
     * 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.
     *
     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
     */
    abstract setTitle(title: Translatable): void;
    /**
     * Sets the title of the dialog.
     *
     * @deprecated since version 1.0.0-beta.31. To migrate, pass a translatable and provide the text using a text provider registered in `WorkbenchClient.registerTextProvider`.
     */
    abstract setTitle(title: Observable<Translatable>): void;
    /**
     * Indicates whether this dialog has the focus.
     */
    abstract readonly focused$: Observable<boolean>;
    /**
     * 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;
}

/**
 * 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 {
    /**
     * @inheritDoc
     */
    type: WorkbenchCapabilities.Popup;
    /**
     * Qualifies this popup. The qualifier is required for a popup.
     *
     * @inheritDoc
     */
    qualifier: Qualifier;
    /**
     * @inheritDoc
     */
    properties: {
        /**
         * Specifies the path to the microfrontend.
         *
         * The path is relative to the base URL given in the application manifest, or to the origin of the manifest file if no base URL is specified.
         *
         * Path segments can reference capability parameters using the colon syntax.
         *
         * ```json
         * {
         *   "params": [
         *     {"name": "id", "required": true}
         *   ],
         *   "properties": {
         *     "path": "products/:id", // `:id` references a capability parameter
         *   }
         * }
         * ```
         */
        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.
 *
 * @deprecated since version 1.0.0-beta.34. Marked for removal. No replacement. Instead, add a parameter to the popup capability for the popup opener to pass required referrer information.
 *
 * @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;
}

/**
 * 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> {
    /**
     * Represents the identity of this popup.
     */
    abstract readonly id: PopupId;
    /**
     * Capability that represents the microfrontend loaded into this workbench popup.
     */
    abstract readonly capability: WorkbenchPopupCapability;
    /**
     * Indicates whether this popup has the focus.
     */
    abstract readonly focused$: Observable<boolean>;
    /**
     * 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