@minecraft/server-ui 2.1.0-beta.1.26.20-preview.20 → 2.1.0-beta.1.26.20-preview.23

package/index.d.ts

@@ -33,6 +33,36 @@
  */
 import * as minecraftcommon from '@minecraft/common';
 import * as minecraftserver from '@minecraft/server';
+/**
+ * @beta
+ * The reason why a data driven screen (i.e. MessageBox or
+ * CustomForm) was closed.
+ */
+export declare enum DataDrivenScreenClosedReason {
+    /**
+     * @remarks
+     * Closed because it was programmatically told by the server to
+     * close using `form.close()`.
+     *
+     */
+    ServerClose = 'ServerClose',
+    /**
+     * @remarks
+     * Closed because the user was busy (i.e. other UI was open).
+     *
+     */
+    UserBusy = 'UserBusy',
+    /**
+     * @remarks
+     * Closed because the client closed the form. This can be with
+     * a close button on the form (i.e. the X in the corner of a
+     * message box, the 'Close' button on a custom form, or either
+     * button in the message box)
+     *
+     */
+    UserClose = 'UserClose',
+}
+
 export enum FormCancelationReason {
     UserBusy = 'UserBusy',
     UserClosed = 'UserClosed',
@@ -44,33 +74,66 @@ export enum FormRejectReason {
     ServerShutdown = 'ServerShutdown',
 }
 
+/**
+ * @beta
+ * An enum representing the errors that can occur during text
+ * filtering. This is used to provide more context about the
+ * filtering process.
+ */
+export declare enum TextFilteringError {
+    /**
+     * @remarks
+     * The text was not filtered because the player disabled text
+     * filtering in their settings.
+     *
+     */
+    DisabledByPlayer = 'DisabledByPlayer',
+    /**
+     * @remarks
+     * The text was not filtered because the service is
+     * unreachable. This can occur if there are network issues or
+     * if the service is down for maintenance.
+     *
+     */
+    TextProcessorServiceUnreachable = 'TextProcessorServiceUnreachable',
+    /**
+     * @remarks
+     * An unknown error occurred during text filtering. This can
+     * occur if there is an unexpected issue with the text
+     * filtering service or if the service returns an error that is
+     * not categorized under the other error types.
+     *
+     */
+    Unknown = 'Unknown',
+}
+
 /**
  * Builds a simple player form with buttons that let the player
  * take action.
  * @example showActionForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ActionFormData, ActionFormResponse } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ActionFormData, ActionFormResponse } from '@minecraft/server-ui';
  *
  * function showActionForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const playerList = world.getPlayers();
  *
  *   if (playerList.length >= 1) {
  *     const form = new ActionFormData()
- *       .title("Test Title")
- *       .body("Body text here!")
- *       .button("btn 1")
- *       .button("btn 2")
- *       .button("btn 3")
- *       .button("btn 4")
- *       .button("btn 5");
+ *       .title('Test Title')
+ *       .body('Body text here!')
+ *       .button('btn 1')
+ *       .button('btn 2')
+ *       .button('btn 3')
+ *       .button('btn 4')
+ *       .button('btn 5');
  *
  *     form.show(playerList[0]).then((result: ActionFormResponse) => {
  *       if (result.canceled) {
- *         log("Player exited out of the dialog. Note that if the chat window is up, dialogs are automatically canceled.");
+ *         log('Player exited out of the dialog. Note that if the chat window is up, dialogs are automatically canceled.');
  *         return -1;
  *       } else {
- *         log("Your result was: " + result.selection);
+ *         log('Your result was: ' + result.selection);
  *       }
  *     });
  *   }
@@ -78,25 +141,25 @@ export enum FormRejectReason {
  * ```
  * @example showFavoriteMonth.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ActionFormData, ActionFormResponse } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ActionFormData, ActionFormResponse } from '@minecraft/server-ui';
  *
  * function showFavoriteMonth(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   if (players.length >= 1) {
  *     const form = new ActionFormData()
- *       .title("Months")
- *       .body("Choose your favorite month!")
- *       .button("January")
- *       .button("February")
- *       .button("March")
- *       .button("April")
- *       .button("May");
+ *       .title('Months')
+ *       .body('Choose your favorite month!')
+ *       .button('January')
+ *       .button('February')
+ *       .button('March')
+ *       .button('April')
+ *       .button('May');
  *
  *     form.show(players[0]).then((response: ActionFormResponse) => {
  *       if (response.selection === 3) {
- *         log("I like April too!");
+ *         log('I like April too!');
  *         return -1;
  *       }
  *     });
@@ -172,28 +235,28 @@ export class ActionFormData {
  * form.
  * @example showActionForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ActionFormData, ActionFormResponse } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ActionFormData, ActionFormResponse } from '@minecraft/server-ui';
  *
  * function showActionForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const playerList = world.getPlayers();
  *
  *   if (playerList.length >= 1) {
  *     const form = new ActionFormData()
- *       .title("Test Title")
- *       .body("Body text here!")
- *       .button("btn 1")
- *       .button("btn 2")
- *       .button("btn 3")
- *       .button("btn 4")
- *       .button("btn 5");
+ *       .title('Test Title')
+ *       .body('Body text here!')
+ *       .button('btn 1')
+ *       .button('btn 2')
+ *       .button('btn 3')
+ *       .button('btn 4')
+ *       .button('btn 5');
  *
  *     form.show(playerList[0]).then((result: ActionFormResponse) => {
  *       if (result.canceled) {
- *         log("Player exited out of the dialog. Note that if the chat window is up, dialogs are automatically canceled.");
+ *         log('Player exited out of the dialog. Note that if the chat window is up, dialogs are automatically canceled.');
  *         return -1;
  *       } else {
- *         log("Your result was: " + result.selection);
+ *         log('Your result was: ' + result.selection);
  *       }
  *     });
  *   }
@@ -201,25 +264,25 @@ export class ActionFormData {
  * ```
  * @example showFavoriteMonth.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ActionFormData, ActionFormResponse } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ActionFormData, ActionFormResponse } from '@minecraft/server-ui';
  *
  * function showFavoriteMonth(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   if (players.length >= 1) {
  *     const form = new ActionFormData()
- *       .title("Months")
- *       .body("Choose your favorite month!")
- *       .button("January")
- *       .button("February")
- *       .button("March")
- *       .button("April")
- *       .button("May");
+ *       .title('Months')
+ *       .body('Choose your favorite month!')
+ *       .button('January')
+ *       .button('February')
+ *       .button('March')
+ *       .button('April')
+ *       .button('May');
  *
  *     form.show(players[0]).then((response: ActionFormResponse) => {
  *       if (response.selection === 3) {
- *         log("I like April too!");
+ *         log('I like April too!');
  *         return -1;
  *       }
  *     });
@@ -324,7 +387,7 @@ export declare class CustomForm {
      * @throws
      *  *
      */
-    show(): Promise<boolean>;
+    show(): Promise<DataDrivenScreenClosedReason>;
     /**
      * @remarks
      * Creates a slider that lets players pick a number between
@@ -378,6 +441,13 @@ export declare class CustomForm {
     ): CustomForm;
 }
 
+/**
+ * @beta
+ * Thrown when attempting to close a DDUI form that isn't open.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export declare class FormCloseError extends Error {}
+
 /**
  * Base type for a form response.
  */
@@ -467,20 +537,17 @@ export declare class MessageBox {
  * Builds a simple two-button modal dialog.
  * @example showBasicMessageForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { MessageFormResponse, MessageFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { MessageFormResponse, MessageFormData } from '@minecraft/server-ui';
  *
- * function showBasicMessageForm(
- *   log: (message: string, status?: number) => void,
- *   targetLocation: DimensionLocation
- * ) {
+ * function showBasicMessageForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   const messageForm = new MessageFormData()
- *     .title("Message Form Example")
- *     .body("This shows a simple example using §o§7MessageFormData§r.")
- *     .button1("Button 1")
- *     .button2("Button 2");
+ *     .title('Message Form Example')
+ *     .body('This shows a simple example using §o§7MessageFormData§r.')
+ *     .button1('Button 1')
+ *     .button2('Button 2');
  *
  *   messageForm
  *     .show(players[0])
@@ -490,30 +557,27 @@ export declare class MessageBox {
  *         return;
  *       }
  *
- *       log(`You selected ${formData.selection === 0 ? "Button 1" : "Button 2"}`);
+ *       log(`You selected ${formData.selection === 0 ? 'Button 1' : 'Button 2'}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
  * ```
  * @example showTranslatedMessageForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { MessageFormResponse, MessageFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { MessageFormResponse, MessageFormData } from '@minecraft/server-ui';
  *
- * function showTranslatedMessageForm(
- *   log: (message: string, status?: number) => void,
- *   targetLocation: DimensionLocation
- * ) {
+ * function showTranslatedMessageForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   const messageForm = new MessageFormData()
- *     .title({ translate: "permissions.removeplayer" })
- *     .body({ translate: "accessibility.list.or.two", with: ["Player 1", "Player 2"] })
- *     .button1("Player 1")
- *     .button2("Player 2");
+ *     .title({ translate: 'permissions.removeplayer' })
+ *     .body({ translate: 'accessibility.list.or.two', with: ['Player 1', 'Player 2'] })
+ *     .button1('Player 1')
+ *     .button2('Player 2');
  *
  *   messageForm
  *     .show(players[0])
@@ -523,10 +587,10 @@ export declare class MessageBox {
  *         return;
  *       }
  *
- *       log(`You selected ${formData.selection === 0 ? "Player 1" : "Player 2"}`);
+ *       log(`You selected ${formData.selection === 0 ? 'Player 1' : 'Player 2'}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
@@ -585,20 +649,17 @@ export class MessageFormData {
  * form.
  * @example showBasicMessageForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { MessageFormResponse, MessageFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { MessageFormResponse, MessageFormData } from '@minecraft/server-ui';
  *
- * function showBasicMessageForm(
- *   log: (message: string, status?: number) => void,
- *   targetLocation: DimensionLocation
- * ) {
+ * function showBasicMessageForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   const messageForm = new MessageFormData()
- *     .title("Message Form Example")
- *     .body("This shows a simple example using §o§7MessageFormData§r.")
- *     .button1("Button 1")
- *     .button2("Button 2");
+ *     .title('Message Form Example')
+ *     .body('This shows a simple example using §o§7MessageFormData§r.')
+ *     .button1('Button 1')
+ *     .button2('Button 2');
  *
  *   messageForm
  *     .show(players[0])
@@ -608,30 +669,27 @@ export class MessageFormData {
  *         return;
  *       }
  *
- *       log(`You selected ${formData.selection === 0 ? "Button 1" : "Button 2"}`);
+ *       log(`You selected ${formData.selection === 0 ? 'Button 1' : 'Button 2'}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
  * ```
  * @example showTranslatedMessageForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { MessageFormResponse, MessageFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { MessageFormResponse, MessageFormData } from '@minecraft/server-ui';
  *
- * function showTranslatedMessageForm(
- *   log: (message: string, status?: number) => void,
- *   targetLocation: DimensionLocation
- * ) {
+ * function showTranslatedMessageForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
  *   const messageForm = new MessageFormData()
- *     .title({ translate: "permissions.removeplayer" })
- *     .body({ translate: "accessibility.list.or.two", with: ["Player 1", "Player 2"] })
- *     .button1("Player 1")
- *     .button2("Player 2");
+ *     .title({ translate: 'permissions.removeplayer' })
+ *     .body({ translate: 'accessibility.list.or.two', with: ['Player 1', 'Player 2'] })
+ *     .button1('Player 1')
+ *     .button2('Player 2');
  *
  *   messageForm
  *     .show(players[0])
@@ -641,10 +699,10 @@ export class MessageFormData {
  *         return;
  *       }
  *
- *       log(`You selected ${formData.selection === 0 ? "Player 1" : "Player 2"}`);
+ *       log(`You selected ${formData.selection === 0 ? 'Player 1' : 'Player 2'}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
@@ -666,33 +724,33 @@ export class MessageFormResponse extends FormResponse {
  * player.
  * @example showBasicModalForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ModalFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ModalFormData } from '@minecraft/server-ui';
  *
  * function showBasicModalForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
- *   const modalForm = new ModalFormData().title("Example Modal Controls for §o§7ModalFormData§r");
+ *   const modalForm = new ModalFormData().title('Example Modal Controls for §o§7ModalFormData§r');
  *
- *   modalForm.toggle("Toggle w/o default");
- *   modalForm.toggle("Toggle w/ default", true);
+ *   modalForm.toggle('Toggle w/o default');
+ *   modalForm.toggle('Toggle w/ default', true);
  *
- *   modalForm.slider("Slider w/o default", 0, 50, 5);
- *   modalForm.slider("Slider w/ default", 0, 50, 5, 30);
+ *   modalForm.slider('Slider w/o default', 0, 50, 5);
+ *   modalForm.slider('Slider w/ default', 0, 50, 5, 30);
  *
- *   modalForm.dropdown("Dropdown w/o default", ["option 1", "option 2", "option 3"]);
- *   modalForm.dropdown("Dropdown w/ default", ["option 1", "option 2", "option 3"], 2);
+ *   modalForm.dropdown('Dropdown w/o default', ['option 1', 'option 2', 'option 3']);
+ *   modalForm.dropdown('Dropdown w/ default', ['option 1', 'option 2', 'option 3'], 2);
  *
- *   modalForm.textField("Input w/o default", "type text here");
- *   modalForm.textField("Input w/ default", "type text here", "this is default");
+ *   modalForm.textField('Input w/o default', 'type text here');
+ *   modalForm.textField('Input w/ default', 'type text here', 'this is default');
  *
  *   modalForm
  *     .show(players[0])
- *     .then((formData) => {
+ *     .then(formData => {
  *       players[0].sendMessage(`Modal form results: ${JSON.stringify(formData.formValues, undefined, 2)}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
@@ -814,33 +872,33 @@ export class ModalFormData {
  * Returns data about player responses to a modal form.
  * @example showBasicModalForm.ts
  * ```typescript
- * import { world, DimensionLocation } from "@minecraft/server";
- * import { ModalFormData } from "@minecraft/server-ui";
+ * import { world, DimensionLocation } from '@minecraft/server';
+ * import { ModalFormData } from '@minecraft/server-ui';
  *
  * function showBasicModalForm(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  *   const players = world.getPlayers();
  *
- *   const modalForm = new ModalFormData().title("Example Modal Controls for §o§7ModalFormData§r");
+ *   const modalForm = new ModalFormData().title('Example Modal Controls for §o§7ModalFormData§r');
  *
- *   modalForm.toggle("Toggle w/o default");
- *   modalForm.toggle("Toggle w/ default", true);
+ *   modalForm.toggle('Toggle w/o default');
+ *   modalForm.toggle('Toggle w/ default', true);
  *
- *   modalForm.slider("Slider w/o default", 0, 50, 5);
- *   modalForm.slider("Slider w/ default", 0, 50, 5, 30);
+ *   modalForm.slider('Slider w/o default', 0, 50, 5);
+ *   modalForm.slider('Slider w/ default', 0, 50, 5, 30);
  *
- *   modalForm.dropdown("Dropdown w/o default", ["option 1", "option 2", "option 3"]);
- *   modalForm.dropdown("Dropdown w/ default", ["option 1", "option 2", "option 3"], 2);
+ *   modalForm.dropdown('Dropdown w/o default', ['option 1', 'option 2', 'option 3']);
+ *   modalForm.dropdown('Dropdown w/ default', ['option 1', 'option 2', 'option 3'], 2);
  *
- *   modalForm.textField("Input w/o default", "type text here");
- *   modalForm.textField("Input w/ default", "type text here", "this is default");
+ *   modalForm.textField('Input w/o default', 'type text here');
+ *   modalForm.textField('Input w/ default', 'type text here', 'this is default');
  *
  *   modalForm
  *     .show(players[0])
- *     .then((formData) => {
+ *     .then(formData => {
  *       players[0].sendMessage(`Modal form results: ${JSON.stringify(formData.formValues, undefined, 2)}`);
  *     })
  *     .catch((error: Error) => {
- *       log("Failed to show form: " + error);
+ *       log('Failed to show form: ' + error);
  *       return -1;
  *     });
  * }
@@ -870,6 +928,21 @@ export declare class Observable<T extends string | number | boolean | UIRawMessa
      *
      */
     getData(): T;
+    /**
+     * @remarks
+     * Gets filtered data from the Observable (only available for
+     * strings). In case of failure, it will return an array of
+     * TextFilteringError that can provide more context about the
+     * filtering process. For testing purposes, the options are
+     * available under "Creator -> Text Filtering" settings menu.
+     * This delay is only applied to the getFilteredText function
+     * and can be used to simulate network latency when testing.
+     *
+     */
+    getFilteredText(
+        this: Observable<T & string>,
+        player: minecraftserver.Player,
+    ): Promise<string | TextFilteringError[]>;
     /**
      * @remarks
      * Sets the data on this Observable and notifies the
@@ -885,6 +958,7 @@ export declare class Observable<T extends string | number | boolean | UIRawMessa
      *
      */
     subscribe(listener: (newValue: T) => void): (newValue: T) => void;
+    toJSON(): unknown;
     /**
      * @remarks
      * Unsubscribe a callback from any changes that occur to the
@@ -904,6 +978,22 @@ export declare class Observable<T extends string | number | boolean | UIRawMessa
     ): Observable<T>;
 }
 
+/**
+ * @beta
+ * Thrown when a DDUI screen is rejected because the player
+ * left before responding.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export declare class PlayerLeftError extends Error {}
+
+/**
+ * @beta
+ * Thrown when a DDUI screen is rejected because the server is
+ * shutting down.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export declare class ServerShutdownError extends Error {}
+
 export class UIManager {
     private constructor();
     /**
@@ -1012,17 +1102,17 @@ export interface DropdownOptions {
 export interface MessageBoxResult {
     /**
      * @remarks
-     * The button that was selected, undefined if it was closed
-     * without pressing a button.
+     * The reason the message box was closed.
      *
      */
-    selection?: number;
+    closeReason: DataDrivenScreenClosedReason;
     /**
      * @remarks
-     * Whether the message box was shown
+     * The button that was selected, undefined if it was closed
+     * without pressing a button.
      *
      */
-    wasShown: boolean;
+    selection?: number;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server-ui",
-  "version": "2.1.0-beta.1.26.20-preview.20",
+  "version": "2.1.0-beta.1.26.20-preview.23",
   "description": "",
   "contributors": [
     {
@@ -14,7 +14,7 @@
   ],
   "peerDependencies": {
     "@minecraft/common": "^1.0.0",
-    "@minecraft/server": "^2.0.0 || ^2.8.0-beta.1.26.20-preview.20"
+    "@minecraft/server": "^2.0.0 || ^2.8.0-beta.1.26.20-preview.23"
   },
   "license": "MIT"
 }