@vertigis/viewer-spec/messaging/registry/ui.d.ts

VertiGIS Viewer Specification

import type { UIDensity } from "../../app-config/common/BrandingModelProperties.js";
import type { TranslatableText, TranslateOptions } from "../../app-config/common/TranslatableText.js";
import type { Command } from "../Command.js";
import { CommandRegistry } from "../CommandRegistry.js";
import type { Event } from "../Event.js";
import { EventRegistry } from "../EventRegistry.js";
import type { Operation } from "../Operation.js";
import { OperationRegistry } from "../OperationRegistry.js";
import type { ComponentId, Model } from "../common.js";
export type { ComponentId };
/**
 * A category for a notification that affects the color and icon used.
 */
export declare enum NotificationCategory {
    ERROR = "error",
    INFO = "info",
    SUCCESS = "success",
    WARNING = "warning"
}
/**
 * The base args for a command/operation showing a message box.
 */
export interface MessageBoxArgs {
    /**
     * The title of the dialog.
     */
    title?: string;
    /**
     * The message to be displayed in the dialog.
     */
    message?: string;
    /**
     * Whether the dialog is draggable or not. Defaults to true. Web only.
     */
    isDraggable?: boolean;
    /**
     * Where the dialog appears in the app when it is created. Defaults to
     * center position. Web only.
     */
    initialPosition?: MessageBoxPosition;
}
/**
 * Arguments for the 'ui.alert' command.
 */
export interface AlertCommandArgs extends MessageBoxArgs {
    /**
     * The text to display on the dismiss button.
     */
    buttonText?: string;
}
/**
 * Arguments for the 'ui.confirm' operation.
 */
export interface ConfirmOperationArgs extends MessageBoxArgs {
    /**
     * The text to display on the ok button.
     */
    okButtonText?: string;
    /**
     * The text to display on the cancel button.
     */
    cancelButtonText?: string;
}
/**
 * Arguments for the 'ui.prompt' operation.
 */
export interface PromptOperationArgs extends MessageBoxArgs {
    /**
     * The default value to display in the input box.
     */
    defaultInputValue?: string;
    /**
     * The text to display on the ok button.
     */
    okButtonText?: string;
    /**
     * The text to display on the cancel button.
     */
    cancelButtonText?: string;
}
/**
 * The arguments for the `ui.display-notification` command.
 */
export interface DisplayNotificationArgs {
    /**
     * Optional identifier that can be used to hide a particular notification
     * (see `ui.hide-notification`) Web only.
     */
    id?: string;
    /**
     * The category of notification, i.e. "error" (default is "info").
     */
    category?: NotificationCategory;
    /**
     * The message to be displayed in the notification. Mobile only supports a
     * string for this property.
     */
    message: TranslatableText;
    /**
     * The position of the notification on the screen. Web only.
     */
    position?: Position;
    /**
     * Disable notification timeouts. Timeouts only apply to "info" and
     * "success" categories. Web only.
     */
    disableTimeouts?: boolean;
    /**
     * Notifications in the same notification group are mutually exclusive, and
     * will supersede one another. Mobile only.
     */
    notificationGroup?: string;
    /**
     * The notification title - only shown for system notifications. Mobile
     * only.
     */
    title?: string;
    /**
     * The type of notification - 'app', 'system', or 'auto'. Defaults to
     * 'auto'. Mobile only.
     */
    type?: NotificationType;
    /**
     * Indicates if the notification should auto-close after a time duration.
     * Defaults to true. Mobile only.
     */
    autoClose?: boolean;
    /**
     * Invoked when the notification is closed, either explicitly or due to
     * timeout. Web only.
     */
    onClose?: () => void;
}
/**
 * The arguments for the `ui.hide-notification` command.
 */
export interface HideNotificationArgs {
    /**
     * Optional identifier that can be used to hide a particular notification.
     * Web only.
     */
    id?: string;
}
/**
 * The type of notification - 'app', 'system', or 'auto'. Defaults to 'auto'.
 * Mobile only.
 */
export declare enum NotificationType {
    /**
     * Automatically choose whether to display an app notification or system
     * notification. If the app is in the background, a system notification will
     * be shown. If the app is in the foreground, an in-app notification will be
     * shown. If notifications are unauthorized at the OS level, an in-app
     * notification will always be shown.
     */
    AUTO = "auto",
    /**
     * Display the notification in-app.
     */
    APP = "app",
    /**
     * Display the notification as a system notification using the device's
     * operating system. If system notifications are turned off/disabled in the
     * OS settings, then it will fall back to using an in-app notification.
     */
    SYSTEM = "system"
}
/**
 * Arguments for the "ui.set-visual-state" command.
 */
export interface SetVisualStateArgs {
    /**
     * The component ID.
     */
    id: ComponentId;
    /**
     * The visual state of the component. The set of visual states is specific
     * to the type of component.
     */
    visualState: VisualState;
}
/**
 * Arguments for the "ui.display-busy-state" args.
 */
export interface DisplayBusyStateArgs {
    /**
     * The ID used to link a busy state to its caller. Web only.
     */
    id?: string;
    /**
     * The title to display. Mobile only.
     */
    title?: string;
    /**
     * The message to display.
     */
    message?: string;
    /**
     * The number of milliseconds to wait before displaying the message. Default
     * is 3000. Web only.
     */
    messageDelayMs?: number;
    /**
     * The minimum duration, in milliseconds, that the busy state will be
     * displayed. Defaults to 500. Mobile only.
     */
    minimumDisplayDurationMs?: number;
    /**
     * The maximum number of milliseconds the busy state will be displayed. Web
     * only.
     */
    maximumDisplayDurationMs?: number;
}
/**
 * Arguments for the "ui.focus" command.
 */
export interface FocusArgs {
    /**
     * The component to focus. If the selector property is not defined, the
     * first focusable element within the component will receive focus. If this
     * property is not defined, only the selector will be used.
     */
    component?: ComponentId | Model;
    /**
     * The CSS selector used to find an HTML Element in the DOM. If a component
     * is also provided, the selector will only look within the component's
     * element tree in the DOM.
     */
    selector?: string;
    /**
     * The maximum number of milliseconds the command will spend attempting to
     * focus the element. This may be useful in cases where the target
     * component/element requires time to load or render. Defaults to 0.
     */
    timeout?: number;
}
/**
 * Payload for a VisualStateChangeEvent.
 */
export interface VisualStateChangeEvent {
    /**
     * The ID of the component whose visual state has changed.
     */
    component: ComponentId;
    /**
     * The visual state of the component before the change.
     */
    previous: VisualState;
    /**
     * The new visual state of the component.
     */
    current: VisualState;
}
/**
 * A component's visual state. The values will vary based on the component type.
 */
export type VisualState = string;
/**
 * Represents the state of a layout node.
 */
export declare enum State {
    UNLOADED = 0,
    SUSPENDED = 1,
    ACTIVATED = 2,
    DEACTIVATED = 3,
    FAILED = 4
}
/**
 * A position for a display notification.
 */
export declare enum Position {
    BOTTOM = "bottom",
    LEFT = "left",
    RIGHT = "right",
    TOP = "top"
}
/**
 * A position for the MessageBox dialog.
 */
export type MessageBoxPosition = "bottom" | "start" | "end" | "top" | "bottom-start" | "bottom-end" | "top-start" | "top-end" | "center";
/**
 * Arguments for the ui.narrate command.
 */
export type NarrateArgs = string | NarrateOptions;
/**
 * Translate options for the ui.narrate command.
 */
export interface NarrateOptions extends TranslateOptions {
    /**
     * A timeout before the narration is executed. This can be used to avoid
     * focus changes that can interrupt the screen reader. Defaults to 50ms.
     */
    timeout?: number;
}
/**
 * Arguments for the "ui.activate" and "ui.deactivate" commands.
 *
 * @webOnly
 */
export interface ActivationArgs {
    /**
     * The component to activate or deactivate. Can be identified by its ID or
     * model.
     */
    component: ComponentId | Model;
    /**
     * Whether to validate the component's state before activation or
     * deactivation. Defaults to `false` if not provided.
     */
    validateState?: boolean;
}
/**
 * Arguments that can be passed to the "ui.activate" command. Supports a
 * component's ID, its model, or detailed activation arguments.
 */
export type ActivateArgs = ActivationArgs | ComponentId | Model;
/**
 * Arguments that can be passed to the "ui.deactivate" command. Supports a
 * component's ID, its model, or detailed deactivation arguments.
 */
export type DeactivateArgs = ActivationArgs | ComponentId | Model;
export declare class UICommands extends CommandRegistry {
    protected readonly _prefix = "ui";
    /**
     * Activates a component with the given ID or model, causing it to become
     * visible. For VertiGIS Studio Mobile, only ID is supported.
     */
    get activate(): Command<ActivateArgs>;
    /**
     * Toggles the active state on a component with the given ID. Mobile only.
     *
     * @mobileOnly
     */
    get activeToggle(): Command<ComponentId>;
    /**
     * Shows an alert to the user.
     */
    get alert(): Command<AlertCommandArgs>;
    /**
     * Waits (does nothing) for the specified period. The UI will remain active
     * during this period. This is primarily intended to be used for testing and
     * troubleshooting. Mobile only.
     *
     * @mobileOnly
     */
    get await(): Command<number>;
    /**
     * Deactivates a component with the given ID, causing it to disappear. For
     * VertiGIS Studio Mobile, only ID is supported.
     */
    get deactivate(): Command<DeactivateArgs>;
    /**
     * Displays a loading indicator and custom message to the user to indicate
     * that the UI is busy.
     */
    get displayBusyState(): Command<DisplayBusyStateArgs>;
    /**
     * Shows a notification to the user.
     */
    get displayNotification(): Command<DisplayNotificationArgs>;
    /**
     * Pauses display of notifications until resumed. Mobile only.
     *
     * @mobileOnly
     */
    get pauseNotifications(): Command;
    /**
     * If notifications are currently paused, resumes displaying notifications.
     * Mobile only.
     *
     * @mobileOnly
     */
    get resumeNotifications(): Command;
    /**
     * Focuses on a component or DOM element. Web only.
     *
     * @webOnly
     */
    get focus(): Command<FocusArgs>;
    /**
     * Hides the busy state if currently shown. In Web, requires the ID of the
     * caller that was used to show the busy state.
     */
    get hideBusyState(): Command<string | void>;
    /**
     * Hides a notification previously shown to the user.
     */
    get hideNotification(): Command<HideNotificationArgs | void>;
    /**
     * Marks a component as being available. The interpretation of what effect
     * this has is up to the component. Currently the only component that will
     * react to this is the task-bar, which will have the effect of showing the
     * tab/button for that component. The argument can be an id of the
     * component, or the model for the component. Mobile only.
     *
     * @mobileOnly
     */
    get makeAvailable(): Command<ComponentId | Model>;
    /**
     * Marks a component as being unavailable. The interpretation of what effect
     * this has is up to the component. Currently the only component that will
     * react to this is the task-bar, which will have the effect of hiding the
     * tab/button for that component, and deactivating the component. The
     * argument can be an id of the component, or the model for the component.
     * Mobile only.
     *
     * @mobileOnly
     */
    get makeUnavailable(): Command<ComponentId | Model>;
    /**
     * Forces assistive technology (screen readers) to narrate a translatable
     * message to the end user. Web only.
     *
     * @webOnly
     */
    get narrate(): Command<NarrateArgs>;
    /**
     * Sets the density level for the UI. Web only.
     *
     * @webOnly
     */
    get setDensity(): Command<UIDensity>;
    /**
     * Sets the locale for the application and loads any locale-specific
     * resources. Accepts a valid locale code (example: "en", "fr" or "de-AT").
     * Web only.
     *
     * @webOnly
     */
    get setLocale(): Command<string>;
    /**
     * Sets the color theme of the viewer. The required argument is the new
     * theme's ID.
     */
    get setTheme(): Command<string>;
    /**
     * Sets the visual state of a component. Web only.
     *
     * @webOnly
     */
    get setVisualState(): Command<SetVisualStateArgs>;
}
export declare class UIOperations extends OperationRegistry {
    protected readonly _prefix = "ui";
    /**
     * Gets user confirmation by way of a popup box.
     */
    get confirm(): Operation<ConfirmOperationArgs, boolean>;
    /**
     * Get the IDs of components in the current layout that are backed by the
     * given model. Most models are used by a single component, but in some
     * cases multiple components can share a model. Web only.
     *
     * @webOnly
     */
    get getComponentIds(): Operation<ComponentId | Model, string[]>;
    /**
     * Gets the current locale code for the application. (example: "en", "fr" or
     * "de-AT"). Web only.
     *
     * @webOnly
     */
    get getLocale(): Operation<void, string>;
    /**
     * Gets the active color theme of the viewer. Returns the theme's ID. Web
     * only.
     *
     * @webOnly
     */
    get getTheme(): Operation<void, string>;
    /**
     * Gets all color themes available to the viewer. Returns the theme IDs. Web
     * only.
     *
     * @webOnly
     */
    get getThemes(): Operation<void, string[]>;
    /**
     * Gets the visual state of a component. Web only.
     *
     * @webOnly
     */
    get getVisualState(): Operation<ComponentId | Model, VisualState | undefined>;
    /**
     * Gets the state of a component. Web only.
     *
     * @webOnly
     */
    get getComponentState(): Operation<ComponentId | Model, State | undefined>;
    /**
     * Prompts the user to enter a value in a popup box. Web only.
     *
     * @webOnly
     */
    get prompt(): Operation<PromptOperationArgs, string>;
}
export declare class UIEvents extends EventRegistry {
    protected readonly _prefix = "ui";
    /**
     * Raised when a component is activated. The argument is the component ID.
     */
    get activated(): Event<ComponentId>;
    /**
     * Raised when a component is added to the layout. Web only.
     *
     * @webOnly
     */
    get added(): Event<ComponentId>;
    /**
     * Raised when a component's ancestor becomes activated. The argument is the
     * descendant component's ID. Web only.
     *
     * @webOnly
     */
    get ancestorActivated(): Event<ComponentId>;
    /**
     * Raised when a component's ancestor becomes deactivated. The argument is
     * the descendant component's ID. Web only.
     *
     * @webOnly
     */
    get ancestorDeactivated(): Event<ComponentId>;
    /**
     * Raised when a component is deactivated. The argument is the component ID.
     */
    get deactivated(): Event<ComponentId>;
    /**
     * Raised when the UI density setting is changed. Web only.
     *
     * @webOnly
     */
    get densityChanged(): Event<UIDensity>;
    /**
     * Raised when the locale is changed by the user. The argument is the locale
     * code. Web only.
     *
     * @webOnly
     */
    get localeChanged(): Event<string>;
    /**
     * Raised when a component begins initialization. The argument is the
     * component ID. Web only.
     *
     * @webOnly
     */
    get initializing(): Event<ComponentId>;
    /**
     * Raised when a component and its descendants have been initially
     * activated. The argument is the component ID. Web only.
     *
     * @webOnly
     */
    get initialized(): Event<ComponentId>;
    /**
     * Raised when a component is removed from the layout. Web only.
     *
     * @webOnly
     */
    get removed(): Event<ComponentId>;
    /**
     * Raised when a component is reordered in the layout relative to its
     * siblings. Web only.
     *
     * @webOnly
     */
    get reordered(): Event<ComponentId>;
    /**
     * Raised when the app's theme is changed. The argument is the theme id.
     */
    get themeChanged(): Event<string>;
    /**
     * Raised when a component's visual state is changed. Web only.
     *
     * @webOnly
     */
    get visualStateChanged(): Event<VisualStateChangeEvent>;
}