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

package/README.md

@@ -1,17 +1,17 @@
-# `@minecraft/server-ui`
-
-The `@minecraft/server-ui` module contains types for expressing simple dialog-based user experiences.
-
-
-
-  * [*@minecraft/server-ui.ActionFormData*](../../../scriptapi/minecraft/server-ui/ActionFormData.md) contain a list of buttons with captions and images that can be used for presenting a set of options to a player.
-
-  * [*@minecraft/server-ui.MessageFormData*](../../../scriptapi/minecraft/server-ui/MessageFormData.md) are simple two-button message experiences that are functional for Yes/No or OK/Cancel questions.
-
-  * [*@minecraft/server-ui.ModalFormData*](../../../scriptapi/minecraft/server-ui/ModalFormData.md) allow for a more flexible "questionnaire-style" list of controls that can be used to take input.
-
-## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
-
-See full documentation for this module here:
-
+# `@minecraft/server-ui`
+
+The `@minecraft/server-ui` module contains types for expressing simple dialog-based user experiences.
+
+
+
+  * [*@minecraft/server-ui.ActionFormData*](../../../scriptapi/minecraft/server-ui/ActionFormData.md) contain a list of buttons with captions and images that can be used for presenting a set of options to a player.
+
+  * [*@minecraft/server-ui.MessageFormData*](../../../scriptapi/minecraft/server-ui/MessageFormData.md) are simple two-button message experiences that are functional for Yes/No or OK/Cancel questions.
+
+  * [*@minecraft/server-ui.ModalFormData*](../../../scriptapi/minecraft/server-ui/ModalFormData.md) allow for a more flexible "questionnaire-style" list of controls that can be used to take input.
+
+## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
+
+See full documentation for this module here:
+
 https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server-ui/minecraft-server-ui

package/index.d.ts

@@ -238,6 +238,146 @@ export class ActionFormResponse extends FormResponse {
     readonly selection?: number;
 }
 
+/**
+ * @beta
+ * A customizable form that lets you put buttons, labels,
+ * toggles, dropdowns, sliders, and more into a form! Built on
+ * top of Observable, the form will update when the
+ * Observables' value changes.
+ */
+export declare class CustomForm {
+    /**
+     * @remarks
+     * Inserts a button into the Custom form. onClick is called
+     * when the button is pressed.
+     *
+     */
+    button(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        onClick: () => void,
+        options?: ButtonOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Tell the client to close the form. Throws an error if the
+     * form is not open.
+     *
+     */
+    close(): void;
+    /**
+     * @remarks
+     * Adds a close "X" button to the form.
+     *
+     */
+    closeButton(): CustomForm;
+    /**
+     * @remarks
+     * Inserts a divider (i.e. a line) into the Custom form.
+     *
+     */
+    divider(options?: DividerOptions): CustomForm;
+    /**
+     * @remarks
+     * Inserts a dropdown into the Custom form with the provided
+     * items. The value is based on the items value that selected.
+     *
+     */
+    dropdown(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        value: Observable<number>,
+        items: DropdownItem[],
+        options?: DropdownOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Inserts a header (i.e. large sized text) into the Custom
+     * form.
+     *
+     */
+    header(
+        text: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        options?: TextOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Returns true if the form is currently being shown to the
+     * player.
+     *
+     */
+    isShowing(): boolean;
+    /**
+     * @remarks
+     * Inserts a label (i.e. medium sized text) into the Custom
+     * form.
+     *
+     */
+    label(
+        text: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        options?: TextOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Shows the form to the player. Will return false if the
+     * client was busy (i.e. in another menu or this one is open).
+     * Will throw if the user disconnects.
+     *
+     * @throws
+     *  *
+     */
+    show(): Promise<boolean>;
+    /**
+     * @remarks
+     * Creates a slider that lets players pick a number between
+     * minValue and maxValue. value must be client writable.
+     *
+     */
+    slider(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        value: Observable<number>,
+        minValue: Observable<number> | number,
+        maxValue: Observable<number> | number,
+        options?: SliderOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Inserts a space into the Custom form.
+     *
+     */
+    spacer(options?: SpacingOptions): CustomForm;
+    /**
+     * @remarks
+     * Inserts a text field into the Custom for that players can
+     * enter text into.
+     *
+     */
+    textField(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        text: Observable<string>,
+        options?: TextFieldOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Inserts an on/off toggle that players can interact with into
+     * the Custom form.
+     *
+     */
+    toggle(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        toggled: Observable<boolean>,
+        options?: ToggleOptions,
+    ): CustomForm;
+    /**
+     * @remarks
+     * Creates a Custom form to show to the player. Use this
+     * instead of a constructor.
+     *
+     */
+    static create(
+        player: minecraftserver.Player,
+        title: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+    ): CustomForm;
+}
+
 /**
  * Base type for a form response.
  */
@@ -258,6 +398,71 @@ export class FormResponse {
     readonly canceled: boolean;
 }
 
+/**
+ * @beta
+ * A simple message form UI, 2 buttons and a text body.
+ */
+export declare class MessageBox {
+    /**
+     * @remarks
+     * Sets the data for the text in the body of the message box.
+     * It is contained within a scroll view to allow for lots of
+     * text.
+     *
+     */
+    body(text: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage): MessageBox;
+    /**
+     * @remarks
+     * Sets the data for the top button in the message box.
+     *
+     */
+    button1(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        tooltip?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+    ): MessageBox;
+    /**
+     * @remarks
+     * Sets the data for the bottom button in the message box.
+     *
+     */
+    button2(
+        label: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+        tooltip?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+    ): MessageBox;
+    /**
+     * @remarks
+     * Tell the client to close the message box. Throws {@link
+     * FormCloseError} if the message box is not open.
+     *
+     */
+    close(): void;
+    /**
+     * @remarks
+     * Returns true if the message box is currently being shown to
+     * the player.
+     *
+     */
+    isShowing(): boolean;
+    /**
+     * @remarks
+     * Show this message box to the player. Will return a result
+     * even if the client was busy (i.e. in another menu). Will
+     * throw if the user disconnects.
+     *
+     */
+    show(): Promise<MessageBoxResult>;
+    /**
+     * @remarks
+     * Creates a message box for a certain player. Use this instead
+     * of a constructor.
+     *
+     */
+    static create(
+        player: minecraftserver.Player,
+        title: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage,
+    ): MessageBox;
+}
+
 /**
  * Builds a simple two-button modal dialog.
  * @example showBasicMessageForm.ts
@@ -653,6 +858,52 @@ export class ModalFormResponse extends FormResponse {
     readonly formValues?: (boolean | number | string | undefined)[];
 }
 
+/**
+ * @beta
+ * A class that represents data that can be Observed.
+ * Extensively used for UI.
+ */
+export declare class Observable<T extends string | number | boolean | UIRawMessage> {
+    /**
+     * @remarks
+     * Gets the data from the Observable.
+     *
+     */
+    getData(): T;
+    /**
+     * @remarks
+     * Sets the data on this Observable and notifies the
+     * subscribers.
+     *
+     */
+    setData(data: T): void;
+    /**
+     * @remarks
+     * Subscribes a callback to any changes that occur to the
+     * Observable. The return value can be passed into the
+     * `unsubscribe` function to stop listening to changes.
+     *
+     */
+    subscribe(listener: (newValue: T) => void): (newValue: T) => void;
+    /**
+     * @remarks
+     * Unsubscribe a callback from any changes that occur to the
+     * Observable. This takes the return value from the `subscribe`
+     * function.
+     *
+     */
+    unsubscribe(listener: (newValue: T) => void): void;
+    /**
+     * @remarks
+     * Creates an Observable, use this instead of a constructor.
+     *
+     */
+    static create<T extends string | number | boolean | UIRawMessage>(
+        data: T,
+        options?: ObservableOptions,
+    ): Observable<T>;
+}
+
 export class UIManager {
     private constructor();
     /**
@@ -664,6 +915,116 @@ export class UIManager {
     closeAllForms(player: minecraftserver.Player): void;
 }
 
+/**
+ * @beta
+ * The options for including a button in {@link CustomForm}.
+ */
+export interface ButtonOptions {
+    /**
+     * @remarks
+     * Whether or not this button is disabled.
+     *
+     */
+    disabled?: Observable<boolean> | boolean;
+    /**
+     * @remarks
+     * The tooltip for this button, shown when hovering the button.
+     *
+     */
+    tooltip?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage;
+    /**
+     * @remarks
+     * Whether or not this button is visible.
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The options for including a spacer in {@link CustomForm}.
+ */
+export interface DividerOptions {
+    /**
+     * @remarks
+     * Whether or not this divider is visible
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * Dropdown data for use in {@link CustomForm}.
+ */
+export interface DropdownItem {
+    /**
+     * @remarks
+     * The description of the dropdown item shown when it is
+     * selected.
+     *
+     */
+    description?: UIRawMessage | string;
+    /**
+     * @remarks
+     * The label of the dropdown item in the dropdown.
+     *
+     */
+    label: UIRawMessage | string;
+    /**
+     * @remarks
+     * The value the dropdown will be set to when this item is
+     * selected.
+     *
+     */
+    value: number;
+}
+
+/**
+ * @beta
+ * The options for including a dropdown in {@link CustomForm}.
+ */
+export interface DropdownOptions {
+    /**
+     * @remarks
+     * The description of the dropdown, shown in the UI.
+     *
+     */
+    description?: Observable<string> | string | UIRawMessage;
+    /**
+     * @remarks
+     * Whether or not this dropdown is disabled.
+     *
+     */
+    disabled?: Observable<boolean> | boolean;
+    /**
+     * @remarks
+     * Whether or not this dropdown is visible.
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The result when a {@link MessageBox} is closed.
+ */
+export interface MessageBoxResult {
+    /**
+     * @remarks
+     * The button that was selected, undefined if it was closed
+     * without pressing a button.
+     *
+     */
+    selection?: number;
+    /**
+     * @remarks
+     * Whether the message box was shown
+     *
+     */
+    wasShown: boolean;
+}
+
 /**
  * An interface that is passed into {@link
  * @minecraft/Server-ui.ModalFormData.dropdown} to provide
@@ -756,6 +1117,168 @@ export interface ModalFormDataToggleOptions {
     tooltip?: minecraftserver.RawMessage | string;
 }
 
+/**
+ * @beta
+ * An interface passed into `Observable.create`.
+ */
+export interface ObservableOptions {
+    /**
+     * @remarks
+     * If set to true, the client can update this value. This
+     * should be used for things like dropdown values, toggles,
+     * textfields, etc. If unset or false, the client cannot write
+     * to this observable.
+     *
+     */
+    clientWritable?: boolean;
+}
+
+/**
+ * @beta
+ * The options for including a slider in {@link CustomForm}.
+ */
+export interface SliderOptions {
+    /**
+     * @remarks
+     * The description of the slider, shown in the UI.
+     *
+     */
+    description?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage;
+    /**
+     * @remarks
+     * Whether or not this slider is disabled.
+     *
+     */
+    disabled?: Observable<boolean> | boolean;
+    /**
+     * @remarks
+     * The step size of the slider. For example, if this is 2 and
+     * the min is 0 and the max is 10, the only selectable values
+     * will be 0, 2, 4, 6, 8, 10.
+     *
+     */
+    step?: Observable<number> | number;
+    /**
+     * @remarks
+     * Whether or not this slider is visible.
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The options for including a spacer in {@link CustomForm}.
+ */
+export interface SpacingOptions {
+    /**
+     * @remarks
+     * Whether or not this spacer is visible
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The options for including a textfield in {@link CustomForm}.
+ */
+export interface TextFieldOptions {
+    /**
+     * @remarks
+     * The description for this text field, shown in the UI.
+     *
+     */
+    description?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage;
+    /**
+     * @remarks
+     * Whether or not this text field is disabled.
+     *
+     */
+    disabled?: Observable<boolean> | boolean;
+    /**
+     * @remarks
+     * Whether or not this text field is visible.
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The options for including a label or header in {@link
+ * CustomForm}.
+ */
+export interface TextOptions {
+    /**
+     * @remarks
+     * Whether or not this label is visible
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * The options for including a toggle in {@link CustomForm}.
+ */
+export interface ToggleOptions {
+    /**
+     * @remarks
+     * The description for this toggle, shown in the UI.
+     *
+     */
+    description?: Observable<string> | Observable<UIRawMessage> | string | UIRawMessage;
+    /**
+     * @remarks
+     * Whether or not this toggle is disabled.
+     *
+     */
+    disabled?: Observable<boolean> | boolean;
+    /**
+     * @remarks
+     * Whether or not this toggle is visible.
+     *
+     */
+    visible?: Observable<boolean> | boolean;
+}
+
+/**
+ * @beta
+ * A message that can be sent to the client. This is a subset
+ * of the RawMessage type, and is used for UI messages.
+ */
+export interface UIRawMessage {
+    /**
+     * @remarks
+     * Provides a raw-text equivalent of the current message.
+     *
+     */
+    rawtext?: UIRawMessage[];
+    /**
+     * @remarks
+     * Provides a string literal value to use.
+     *
+     */
+    text?: string;
+    /**
+     * @remarks
+     * Provides a translation token where, if the client has an
+     * available resource in the players' language which matches
+     * the token, will get translated on the client.
+     *
+     */
+    translate?: string;
+    /**
+     * @remarks
+     * Arguments for the translation token. Can be either an array
+     * of strings or UIRawMessage containing an array of raw text
+     * objects.
+     *
+     */
+    with?: string[] | UIRawMessage;
+}
+
 // @ts-ignore Class inheritance allowed for native defined classes
 export class FormRejectError extends Error {
     private constructor();
@@ -764,7 +1287,7 @@ export class FormRejectError extends Error {
      * This property can be read in early-execution mode.
      *
      */
-    reason: FormRejectReason;
+    readonly reason: FormRejectReason;
 }
 
 export const uiManager: UIManager;

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@minecraft/server-ui",
-  "version": "2.1.0-beta.1.26.2-stable",
-  "description": "",
-  "contributors": [
-    {
-      "name": "Jake Shirley",
-      "email": "jake@xbox.com"
-    },
-    {
-      "name": "Mike Ammerlaan",
-      "email": "mikeam@microsoft.com"
-    }
-  ],
-  "peerDependencies": {
-    "@minecraft/common": "^1.0.0",
-    "@minecraft/server": "^2.0.0 || ^2.6.0-beta.1.26.2-stable"
-  },
-  "license": "MIT"
+{
+  "name": "@minecraft/server-ui",
+  "version": "2.1.0-beta.1.26.20-preview.20",
+  "description": "",
+  "contributors": [
+    {
+      "name": "Jake Shirley",
+      "email": "jake@xbox.com"
+    },
+    {
+      "name": "Mike Ammerlaan",
+      "email": "mikeam@microsoft.com"
+    }
+  ],
+  "peerDependencies": {
+    "@minecraft/common": "^1.0.0",
+    "@minecraft/server": "^2.0.0 || ^2.8.0-beta.1.26.20-preview.20"
+  },
+  "license": "MIT"
 }