Add os.showAlert() function to display information dialogs

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ### :rocket: Features
 
+-   Added the `os.showAlert(options)` function to show an information/alert dialog with a single dismiss button. This is useful for communicating important information to the user that needs to be manually dismissed.
 -   Added the `os.eraseInst(recordKeyOrName, instName, options?)` function to delete insts programmatically.
 -   Added the `ai.listChatModels()` function to list the available chat models that the user can use based on their subscription.
 -   Changed webhooks to record logs to the same record that the webhook is stored in.

src/aux-common/bots/BotEvents.ts

@@ -131,6 +131,7 @@ export type AsyncActions =
     | IterableThrowAction
     | ShowInputAction
     | ShowConfirmAction
+    | ShowAlertAction
     | ShareAction
     | ImportAUXAction
     | RegisterBuiltinPortalAction
@@ -1490,6 +1491,44 @@ export interface ShowConfirmOptions {
     cancelText?: string;
 }
 
+/**
+ * Defines an event that is used to show an alert dialog to the user.
+ *
+ * @dochash types/os/input
+ * @docname ShowAlertAction
+ */
+export interface ShowAlertAction extends AsyncAction {
+    type: 'show_alert';
+
+    /**
+     * The options for the alert dialog.
+     */
+    options: ShowAlertOptions;
+}
+
+/**
+ * Defines an interface that represents the options that can be used for an alert dialog.
+ *
+ * @dochash types/os/input
+ * @docname ShowAlertOptions
+ */
+export interface ShowAlertOptions {
+    /**
+     * The title that should be shown on the dialog.
+     */
+    title: string;
+
+    /**
+     * The content of the dialog.
+     */
+    content: string;
+
+    /**
+     * The text that should be shown on the "Dismiss" button.
+     */
+    dismissText?: string;
+}
+
 /**
  * Defines an event that is used to set whether the connection is forced to be offline.
  * @docname SetForcedOfflineAction
@@ -4715,6 +4754,22 @@ export function showConfirm(
     };
 }
 
+/**
+ * Creates a new ShowAlertAction event.
+ * @param options The options for the alert dialog.
+ * @param taskId The ID of the async task.
+ */
+export function showAlert(
+    options: ShowAlertOptions,
+    taskId?: number | string
+): ShowAlertAction {
+    return {
+        type: 'show_alert',
+        options,
+        taskId,
+    };
+}
+
 /**
  * Creates a new SetForcedOfflineAction event.
  * @param offline Whether the connection should be offline.

src/aux-runtime/runtime/AuxLibrary.spec.ts

@@ -152,6 +152,7 @@ import {
     analyticsRecordEvent,
     KNOWN_TAGS,
     showConfirm,
+    showAlert,
     getCurrentInstUpdate,
     openPhotoCamera,
     enableCollaboration,
@@ -6120,6 +6121,32 @@ describe('AuxLibrary', () => {
             });
         });
 
+        describe('os.showAlert()', () => {
+            it('should emit a ShowAlertAction', () => {
+                const promise: any = library.api.os.showAlert({
+                    title: 'Alert',
+                    content: 'This is an important message.',
+                    dismissText: 'OK',
+                });
+                const expected = showAlert(
+                    {
+                        title: 'Alert',
+                        content: 'This is an important message.',
+                        dismissText: 'OK',
+                    },
+                    context.tasks.size
+                );
+                expect(promise[ORIGINAL_OBJECT]).toEqual(expected);
+                expect(context.actions).toEqual([expected]);
+            });
+
+            it('should throw an error if not given an options object', () => {
+                expect(() => {
+                    (library.api.os.showAlert as any)();
+                }).toThrowError();
+            });
+        });
+
         describe('os.goToDimension()', () => {
             it('should issue a GoToDimension event', () => {
                 const action = library.api.os.goToDimension('abc');

src/aux-runtime/runtime/AuxLibrary.ts

@@ -97,6 +97,7 @@ import type {
     WakeLockConfiguration,
     EnableXROptions,
     ShowConfirmOptions,
+    ShowAlertOptions,
     StoredAux,
     StoredAuxVersion2,
     StoredAuxVersion1,
@@ -154,6 +155,7 @@ import {
     showInputForTag as calcShowInputForTag,
     showInput as calcShowInput,
     showConfirm as calcShowConfirm,
+    showAlert as calcShowAlert,
     replaceDragBot as calcReplaceDragBot,
     goToDimension as calcGoToDimension,
     goToURL as calcGoToURL,
@@ -3702,6 +3704,7 @@ export function createDefaultLibrary(context: AuxGlobalContext) {
                 _showInput: showInput,
                 showInput: makeMockableFunction(showInput, 'os.showInput'),
                 showConfirm,
+                showAlert,
                 goToDimension,
                 goToURL,
                 openURL,
@@ -8487,6 +8490,43 @@ export function createDefaultLibrary(context: AuxGlobalContext) {
         return addAsyncAction(task, event);
     }
 
+    /**
+     * Shows an alert dialog using the given options. Alert dialogs are useful for communicating information to the user that needs to be manually dismissed.
+     *
+     * Returns a promise that resolves when the user dismisses the alert.
+     *
+     * @param options the options that should be used for the alert dialog.
+     *
+     * @example Show an alert dialog
+     * await os.showAlert({
+     *     title: 'Alert',
+     *     content: 'This is an important message.'
+     * });
+     *
+     * os.toast('Alert dismissed');
+     *
+     * @example Show an alert dialog with custom button text
+     * await os.showAlert({
+     *     title: 'Warning',
+     *     content: 'Please read this carefully.',
+     *     dismissText: 'Got it'
+     * });
+     *
+     * @dochash actions/os/portals
+     * @docname os.showAlert
+     * @docgroup 10-showInput
+     */
+    function showAlert(options: ShowAlertOptions): Promise<void> {
+        if (!options) {
+            throw new Error(
+                'You must provide an options object for os.showAlert()'
+            );
+        }
+        const task = context.createTask();
+        const event = calcShowAlert(options, task.taskId);
+        return addAsyncAction(task, event);
+    }
+
     /**
      * Loads the given dimension into the {@tag gridPortal} portal. Triggers the {@tag @onPortalChanged} shout for the gridPortal.
      * @param dimension the dimension that should be loaded.

src/aux-runtime/runtime/AuxLibraryDefinitions.def

@@ -1506,6 +1506,29 @@ declare interface ShowConfirmOptions {
     cancelText?: string;
 }
 
+/**
+ * Defines an interface that represents the options that can be used for an alert dialog.
+ *
+ * @dochash types/os/input
+ * @docname ShowAlertOptions
+ */
+export interface ShowAlertOptions {
+    /**
+     * The title that should be shown on the dialog.
+     */
+    title: string;
+
+    /**
+     * The content of the dialog.
+     */
+    content: string;
+
+    /**
+     * The text that should be shown on the "Dismiss" button.
+     */
+    dismissText?: string;
+}
+
 /**
  * Defines an event for actions.
  * Actions are basically user-defined events.
@@ -14430,6 +14453,12 @@ interface Os {
      */
     showConfirm(options: ShowConfirmOptions): Promise<boolean>;
 
+    /**
+     * Shows an alert dialog. Returns a promise that resolves when the user dismisses the alert.
+     * @param options The options that indicate how the alert dialog should be customized.
+     */
+    showAlert(options: ShowAlertOptions): Promise<void>;
+
     /**
      * Gets the dimension that the player is currently viewing.
      */

src/aux-server/aux-web/aux-player/PlayerApp/PlayerApp.ts

@@ -95,6 +95,7 @@ import { getRenderer } from '../../shared/scene/BotRenderer';
 import UploadFiles from '../../shared/vue-components/UploadFiles/UploadFiles';
 import ShowInputModal from '../../shared/vue-components/ShowInputModal/ShowInputModal';
 import ShowConfirmModal from '../../shared/vue-components/ShowConfirmModal/ShowConfirmModal';
+import ShowAlertModal from '../../shared/vue-components/ShowAlertModal/ShowAlertModal';
 import MeetPortal from '../../shared/vue-components/MeetPortal/MeetPortal';
 import TagPortal from '../../shared/vue-components/TagPortal/TagPortal';
 import CustomPortals from '../../shared/vue-components/CustomPortals/CustomPortals';
@@ -164,6 +165,7 @@ declare function sa_event(name: string, callback: () => void): void;
         'upload-files': UploadFiles,
         'show-input': ShowInputModal,
         'show-confirm': ShowConfirmModal,
+        'show-alert': ShowAlertModal,
         'meet-portal': MeetPortal,
         'tag-portal': TagPortal,
         'custom-portals': CustomPortals,

src/aux-server/aux-web/aux-player/PlayerApp/PlayerApp.vue

@@ -35,6 +35,7 @@
             <upload-files></upload-files>
             <show-input></show-input>
             <show-confirm></show-confirm>
+            <show-alert></show-alert>
 
             <md-dialog :md-active.sync="showQRCode" md-theme="default" class="qr-code-dialog">
                 <div class="qr-code-container">

src/aux-server/aux-web/shared/vue-components/ShowAlertModal/ShowAlertModal.css

@@ -0,0 +1,19 @@
+.alert-dialog-content {
+    padding-bottom: 0;
+}
+
+.alert-dialog .md-dialog-title {
+    margin-bottom: 0;
+}
+
+.alert-dialog {
+    transition-duration: 0.1s, 0.1s;
+}
+
+.alert-dialog .md-dialog-title {
+    display: inline-block;
+}
+
+.md-dialog.alert-dialog {
+    z-index: 20;
+}