bedrock-ddui-forms 0.0.0-stage → 1.0.0

package/README.es.md

@@ -0,0 +1,262 @@
+# bedrock-ddui-forms
+
+> [🇬🇧 English](./README.md) · 🇪🇸 Español
+
+Una capa declarativa para crear formularios **DDUI** (`CustomForm`) de `@minecraft/server-ui` a partir de objetos.
+
+En lugar de encadenar llamadas sobre `CustomForm`, describes la vista como datos y un renderizador la traduce:
+
+```js
+{
+    title: "Ajustes",
+    content: [
+        { type: "header", text: "General" },
+        { type: "toggle", label: "Activar función", toggled: new ObservableBoolean(true, { clientWritable: true }) },
+        { type: "close-button" }
+    ]
+}
+```
+
+> No afiliado a Mojang ni a Microsoft. "Minecraft" y "Bedrock" se usan solo para describir la plataforma a la que apunta esta librería.
+
+## Características
+
+- **Vistas declarativas**: un formulario es un objeto con `title` y un arreglo `content`.
+- **Tipado con la API oficial**: los modelos son typedefs de JSDoc que reutilizan los tipos de `@minecraft/server-ui` (`ButtonOptions`, `SliderOptions`, …), así que se mantienen sincronizados con el módulo.
+- **Navegación sencilla**: un botón puede abrir otra vista con `to`, combinable con `onClick`.
+- **Fácil de extender**: añadir un tipo de elemento nuevo es una entrada en una tabla y una función.
+- **Fallback seguro**: un `type` no soportado muestra un label visible y registra una advertencia, en vez de romper todo el formulario.
+
+## Requisitos
+
+- `@minecraft/server-ui` **2.2.0** (estable)
+
+## Instalación
+
+El motor de scripts de Minecraft **no** resuelve paquetes de npm (dentro del juego no existe `node_modules`). Solo los módulos `@minecraft/*` declarados en el `manifest.json` los aporta el juego, así que la librería tiene que terminar como archivos dentro de la carpeta `scripts/` de tu addon. Hay dos formas de hacerlo.
+
+### Opción 1: copiar los archivos
+
+Copia la librería dentro de tu behavior pack e impórtala con rutas relativas:
+
+```
+BP/
+  manifest.json
+  scripts/
+    main.js
+    libs/bedrock-ddui-forms/
+      index.js
+      core/
+      models/
+    views/
+```
+
+```js
+import { customFormRender } from "../libs/bedrock-ddui-forms/index";
+```
+
+No necesita herramientas, pero para actualizar tienes que copiar los archivos de nuevo.
+
+### Opción 2: usar un bundler (recomendada si instalas desde npm)
+
+```bash
+npm install bedrock-ddui-forms
+```
+
+Después empaqueta tu código y la librería en un solo archivo dentro de `scripts/`. Por ejemplo, con [esbuild](https://esbuild.github.io/):
+
+```bash
+npx esbuild src/index.js --bundle --format=esm --outfile=scripts/libs/bedrock-ddui-forms/index.js --external:@minecraft/server --external:@minecraft/server-ui
+```
+
+Los `--external` son importantes: los módulos `@minecraft/*` los aporta el juego y no deben incluirse en el bundle. Con este flujo, `npm update` basta para actualizar la librería.
+
+### Siempre necesario
+
+- Declara `@minecraft/server-ui` en tu `manifest.json` (esta librería apunta a la versión `2.2.0`). Nunca se copia ni se empaqueta:
+
+  ```json
+  {
+    "module_name": "@minecraft/server-ui",
+    "version": "2.2.0"
+  }
+  ```
+
+- La propia librería no debe usar módulos de Node.js (`node:fs`, etc.), porque no existen en el juego.
+- Los imports internos de la librería están escritos sin extensión (`./propertiesFactory`), y los bundlers los resuelven. Si copias los archivos y tu entorno exige extensiones explícitas, añade `.js` a los imports relativos.
+
+## Inicio rápido
+
+```js
+import { ObservableBoolean, ObservableString } from "@minecraft/server-ui";
+import { customFormRender } from "../libs/bedrock-ddui-forms/index";
+
+const createSettingsPage = (player) => ({
+    title: "Ajustes",
+    content: [
+        { type: "header", text: "General" },
+        { type: "spacer" },
+        {
+            type: "text-field",
+            label: "Nombre",
+            text: new ObservableString("Steve", { clientWritable: true })
+        },
+        {
+            type: "toggle",
+            label: "Activar función",
+            toggled: new ObservableBoolean(true, { clientWritable: true })
+        },
+        { type: "divider" },
+        { type: "close-button" }
+    ]
+});
+
+export const openSettings = (player) => customFormRender(player, createSettingsPage(player));
+```
+
+> **Consejo:** define cada vista como una función (`createXPage(player)`) para que los `Observable` se creen de nuevo cada vez que se abre la vista y no se arrastre estado anterior.
+
+## Elementos soportados
+
+| `type` | Propiedades principales | Método de `CustomForm` |
+| --- | --- | --- |
+| `button` | `label`, `onClick?`, `to?`, `options?` | `button()` |
+| `close-button` | – | `closeButton()` |
+| `divider` | `options?` | `divider()` |
+| `dropdown` | `label`, `value` (`ObservableNumber`), `items`, `options?` | `dropdown()` |
+| `header` | `text`, `options?` | `header()` |
+| `image` | `src`, `pack`, `options?` (`onClick`, `tooltip`, `visible`, `width`) | `image()` |
+| `label` | `text`, `options?` | `label()` |
+| `slider` | `label`, `value` (`ObservableNumber`), `min`, `max`, `options?` (`step`, …) | `slider()` |
+| `spacer` | `options?` | `spacer()` |
+| `text-field` | `label`, `text` (`ObservableString`), `options?` | `textField()` |
+| `toggle` | `label`, `toggled` (`ObservableBoolean`), `options?` | `toggle()` |
+
+`options` siempre coincide con el tipo de opciones correspondiente de `@minecraft/server-ui` (por ejemplo `SliderOptions`). `image.options.width` es una fracción del ancho del formulario (`0.5` es la mitad).
+
+## Navegación
+
+Un botón puede abrir otra vista con `to`. Se ejecuta **después** de `onClick`, cuando el formulario actual ya está cerrado, así que se pueden combinar:
+
+```js
+{
+    type: "button",
+    label: "Guardar y volver",
+    onClick: function () { save(player); },   // se ejecuta primero
+    to: () => openMainMenu(player)            // luego cierra este formulario y abre el siguiente
+}
+```
+
+- Si el botón solo navega, usa `to`.
+- Si hace algo más, usa `onClick`, y añade `to` si además debe navegar.
+- Dentro de `onClick` y de `image.options.onClick`, `this` es el `CustomForm`, así que `this.close()` funciona si necesitas cerrar sin abrir nada.
+
+## Leer valores
+
+Los valores son los `Observable` que tú creas, así que guarda una referencia y léelos cuando los necesites:
+
+```js
+const createPage = (player) => {
+    const name = new ObservableString("", { clientWritable: true });
+
+    return {
+        title: "Renombrar",
+        content: [
+            { type: "text-field", label: "Nuevo nombre", text: name },
+            {
+                type: "button",
+                label: "Guardar",
+                onClick: function () { rename(player, name.getData()); },
+                to: () => openMainMenu(player)
+            }
+        ]
+    };
+};
+```
+
+## Cerrar una vista: `onExit`
+
+`formData.onExit` se ejecuta cuando el formulario se cierra, por cualquier motivo excepto `UserBusy` (cuando el formulario no pudo mostrarse). `this` es el `CustomForm` y el primer argumento es el `DataDrivenScreenClosedReason`:
+
+```js
+{
+    title: "Ajustes",
+    content: [ /* ... */ ],
+    onExit(reason) {
+        // reason: ClientClosed | ServerClosed
+    }
+}
+```
+
+Cuando un botón navega con `to`, el servidor cierra el formulario actual, así que su `onExit` también se ejecuta, con `ServerClosed`, **después** de que `to` ya abrió la siguiente vista. Revisa `reason` si solo quieres reaccionar cuando el jugador cierra el formulario (`ClientClosed`).
+
+## Validación y mensajes de error
+
+Antes de abrir una vista, `customFormRender` revisa cada elemento y reporta **todos** los problemas que encuentra en un solo mensaje en la consola, con el lugar exacto de cada uno:
+
+```
+[bedrock-ddui-forms] View "Stored Inventory": 3 errors, 2 warnings
+  ERROR   content[0] slider "Protection duration" > label: is required. Expected string | ObservableString | ObservableUIRawMessage | UIRawMessage.
+  WARNING content[0] slider "Protection duration" > text: unknown property "text". Valid properties: label, value, min, max, options.
+  WARNING content[0] slider "Protection duration" > options.steps: unknown option "steps". Did you mean "step"?
+  ERROR   content[1] textfield "Owner" > type: unknown type "textfield". Did you mean "text-field"?
+  ERROR   content[2] toggle "Keep armor" > toggled: expected ObservableBoolean, received boolean true. Create it with new ObservableBoolean(<initial value>, { clientWritable: true }).
+```
+
+Los mensajes están en inglés, igual que el resto de la salida de la librería.
+
+- Los **errores** dejan el elemento inutilizable. Las **advertencias** señalan equivocaciones probables (propiedades u opciones desconocidas, un valor de dropdown que ningún item tiene, `min` mayor que `max`, un botón sin acción...) y no detienen nada.
+- Los errores de escritura reciben una sugerencia ("Did you mean ...?"), y si pasas un valor simple donde se necesita un `Observable`, el mensaje explica cómo crearlo.
+- También se detecta un error muy común: `to: openMenu(player)` llama a la función en vez de pasarla (`to: () => openMenu(player)`).
+- Los errores lanzados dentro de `onClick`, `to`, `image.options.onClick` y `onExit` se registran con el elemento al que pertenecen, en vez de fallar en silencio.
+
+Qué pasa con un elemento con errores lo decides tú, con el tercer argumento de `customFormRender`:
+
+```js
+customFormRender(player, formData, { onInvalid: "label" });  // por defecto
+```
+
+| `onInvalid` | Comportamiento |
+| --- | --- |
+| `"label"` | Muestra un marcador visible en su lugar (útil mientras desarrollas). |
+| `"skip"` | Deja el elemento fuera (mejor en producción o con contenido que viene de fuera). |
+| `"throw"` | No abre el formulario y lanza un `FormValidationError` (su propiedad `issues` lista todos los problemas). |
+
+Si el problema está en la vista misma (falta `title`, `content` no es un arreglo, no hay `player`), el formulario no se puede construir: se registra el reporte y `customFormRender` devuelve `undefined`.
+
+También puedes validar sin renderizar, por ejemplo en una prueba o con vistas que vienen de un servidor:
+
+```js
+import { validateForm } from "bedrock-ddui-forms";
+
+const report = validateForm(formData, player);
+report.errors;    // problemas que rompen un elemento
+report.warnings;  // equivocaciones probables
+report.message;   // el texto mostrado arriba
+```
+
+## Valor de retorno
+
+`customFormRender(player, formData)` devuelve una promesa que se resuelve con el `DataDrivenScreenClosedReason` (`ClientClosed`, `ServerClosed` o `UserBusy`), o `undefined` si la vista no se pudo construir o hubo un error al mostrarla. Un resultado `UserBusy` además registra una advertencia.
+
+## Estructura del proyecto
+
+```
+index.js                  punto de entrada público
+core/
+  customFormRender.js     renderiza una vista y la muestra al jugador
+  propertiesFactory.js    asocia cada `type` con su llamada a CustomForm
+  validation.js           revisa las vistas y construye los mensajes de error
+models/properties/
+  *.js                    typedefs de JSDoc de cada elemento
+```
+
+## Añadir un tipo de elemento nuevo
+
+1. Crea su typedef en `models/properties/` y añádelo a la unión `Property`.
+2. Escribe su función en `propertiesFactory.js`.
+3. Regístrala en la tabla `properties`.
+
+## Aviso legal
+
+Este proyecto no está afiliado, respaldado ni patrocinado por Mojang Studios ni Microsoft.

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# bedrock-ddui-forms
+
+> 🇬🇧 English · [🇪🇸 Español](./README.es.md)
+
+A declarative layer for building `@minecraft/server-ui` **DDUI** forms (`CustomForm`) from plain objects.
+
+Instead of chaining calls on `CustomForm`, you describe a view as data and let a renderer translate it:
+
+```js
+{
+    title: "Settings",
+    content: [
+        { type: "header", text: "General" },
+        { type: "toggle", label: "Enable feature", toggled: new ObservableBoolean(true, { clientWritable: true }) },
+        { type: "close-button" }
+    ]
+}
+```
+
+> Not affiliated with Mojang or Microsoft. "Minecraft" and "Bedrock" are used only to describe the platform this library targets.
+
+## Features
+
+- **Declarative views**: a form is an object with a `title` and a `content` array.
+- **Typed with the official API**: models are JSDoc typedefs that reuse the types of `@minecraft/server-ui` (`ButtonOptions`, `SliderOptions`, …), so they stay in sync with the module.
+- **Simple navigation**: a button can open another view with `to`, composed with `onClick`.
+- **Easy to extend**: adding a new element type is one entry in a lookup table and one function.
+- **Safe fallback**: an unsupported `type` renders a visible label and logs a warning instead of breaking the whole form.
+
+## Requirements
+
+- `@minecraft/server-ui` **2.2.0** (stable)
+
+## Installation
+
+Minecraft's script engine does **not** resolve npm packages (there is no `node_modules` inside the game). Only the `@minecraft/*` modules declared in the `manifest.json` are provided by the game, so the library has to end up as files inside your addon's `scripts/` folder. There are two ways to do it.
+
+### Option 1: copy the files
+
+Copy the library into your behavior pack and import it with relative paths:
+
+```
+BP/
+  manifest.json
+  scripts/
+    main.js
+    lib/bedrock-ddui-forms/
+      index.js
+      core/
+      models/
+    views/
+```
+
+```js
+import { customFormRender } from "../libs/bedrock-ddui-forms/index";
+```
+
+No tooling needed, but you have to copy the files again to update.
+
+### Option 2: use a bundler (recommended if you install from npm)
+
+```bash
+npm install bedrock-ddui-forms
+```
+
+Then bundle your code and the library into a single file inside `scripts/`. For example, with [esbuild](https://esbuild.github.io/):
+
+```bash
+npx esbuild src/index.js --bundle --format=esm --outfile=scripts/libs/bedrock-ddui-forms/index.js --external:@minecraft/server --external:@minecraft/server-ui
+```
+
+The `--external` flags are important: the `@minecraft/*` modules are provided by the game and must not be bundled. With this flow, `npm update` is enough to update the library.
+
+### Always required
+
+- Declare `@minecraft/server-ui` in your `manifest.json` (this library targets version `2.2.0`). It is never copied or bundled:
+
+  ```json
+  {
+    "module_name": "@minecraft/server-ui",
+    "version": "2.2.0"
+  }
+  ```
+
+- The library itself must not use Node.js modules (`node:fs`, etc.), because they don't exist in the game.
+- The library's internal imports are written without file extensions (`./propertiesFactory`), which bundlers resolve. If you copy the files and your setup requires explicit extensions, add `.js` to the relative imports.
+
+## Quick start
+
+```js
+import { ObservableBoolean, ObservableString } from "@minecraft/server-ui";
+import { customFormRender } from "../libs/bedrock-ddui-forms/index";
+
+const createSettingsPage = (player) => ({
+    title: "Settings",
+    content: [
+        { type: "header", text: "General" },
+        { type: "spacer" },
+        {
+            type: "text-field",
+            label: "Name",
+            text: new ObservableString("Steve", { clientWritable: true })
+        },
+        {
+            type: "toggle",
+            label: "Enable feature",
+            toggled: new ObservableBoolean(true, { clientWritable: true })
+        },
+        { type: "divider" },
+        { type: "close-button" }
+    ]
+});
+
+export const openSettings = (player) => customFormRender(player, createSettingsPage(player));
+```
+
+> **Tip:** define each view as a function (`createXPage(player)`) so the `Observable` values are created again every time the view is opened and no old state is carried over.
+
+## Supported elements
+
+| `type` | Main properties | `CustomForm` method |
+| --- | --- | --- |
+| `button` | `label`, `onClick?`, `to?`, `options?` | `button()` |
+| `close-button` | – | `closeButton()` |
+| `divider` | `options?` | `divider()` |
+| `dropdown` | `label`, `value` (`ObservableNumber`), `items`, `options?` | `dropdown()` |
+| `header` | `text`, `options?` | `header()` |
+| `image` | `src`, `pack`, `options?` (`onClick`, `tooltip`, `visible`, `width`) | `image()` |
+| `label` | `text`, `options?` | `label()` |
+| `slider` | `label`, `value` (`ObservableNumber`), `min`, `max`, `options?` (`step`, …) | `slider()` |
+| `spacer` | `options?` | `spacer()` |
+| `text-field` | `label`, `text` (`ObservableString`), `options?` | `textField()` |
+| `toggle` | `label`, `toggled` (`ObservableBoolean`), `options?` | `toggle()` |
+
+`options` always matches the corresponding options type of `@minecraft/server-ui` (for example `SliderOptions`). `image.options.width` is a fraction of the form width (`0.5` is half).
+
+## Navigation
+
+A button can open another view with `to`. It runs **after** `onClick`, once the current form is closed, so both can be combined:
+
+```js
+{
+    type: "button",
+    label: "Save and go back",
+    onClick: function () { save(player); },   // runs first
+    to: () => openMainMenu(player)            // then closes this form and opens the next one
+}
+```
+
+- If you only navigate, use `to`.
+- If the button does something else, use `onClick`, and add `to` if it should also navigate.
+- Inside `onClick` and `image.options.onClick`, `this` is the `CustomForm`, so `this.close()` works if you need to close without opening anything.
+
+## Reading values
+
+The values are the `Observable` objects you create, so keep a reference and read them when you need them:
+
+```js
+const createPage = (player) => {
+    const name = new ObservableString("", { clientWritable: true });
+
+    return {
+        title: "Rename",
+        content: [
+            { type: "text-field", label: "New name", text: name },
+            {
+                type: "button",
+                label: "Save",
+                onClick: function () { rename(player, name.getData()); },
+                to: () => openMainMenu(player)
+            }
+        ]
+    };
+};
+```
+
+## Closing a view: `onExit`
+
+`formData.onExit` runs after the form closes, for any reason except `UserBusy` (when the form could not be shown at all). `this` is the `CustomForm` and the first argument is the `DataDrivenScreenClosedReason`:
+
+```js
+{
+    title: "Settings",
+    content: [ /* ... */ ],
+    onExit(reason) {
+        // reason: ClientClosed | ServerClosed
+    }
+}
+```
+
+When a button navigates with `to`, the current form is closed by the server, so its `onExit` also runs, with `ServerClosed`, **after** `to` has already opened the next view. Check `reason` if you only want to react when the player closes the form (`ClientClosed`).
+
+## Validation and error messages
+
+Before opening a view, `customFormRender` checks every element and reports **all** the problems it finds in one message in the console, with the exact place of each one:
+
+```
+[bedrock-ddui-forms] View "Stored Inventory": 3 errors, 2 warnings
+  ERROR   content[0] slider "Protection duration" > label: is required. Expected string | ObservableString | ObservableUIRawMessage | UIRawMessage.
+  WARNING content[0] slider "Protection duration" > text: unknown property "text". Valid properties: label, value, min, max, options.
+  WARNING content[0] slider "Protection duration" > options.steps: unknown option "steps". Did you mean "step"?
+  ERROR   content[1] textfield "Owner" > type: unknown type "textfield". Did you mean "text-field"?
+  ERROR   content[2] toggle "Keep armor" > toggled: expected ObservableBoolean, received boolean true. Create it with new ObservableBoolean(<initial value>, { clientWritable: true }).
+```
+
+- **Errors** make the element unusable. **Warnings** point at likely mistakes (unknown properties or options, a dropdown value that no item has, `min` greater than `max`, a button with no action...) and do not stop anything.
+- Typos get a "Did you mean ...?" suggestion, and passing a plain value where an `Observable` is needed explains how to create it.
+- A common mistake is also caught: `to: openMenu(player)` calls the function instead of passing it (`to: () => openMenu(player)`).
+- Errors thrown inside `onClick`, `to`, `image.options.onClick` and `onExit` are logged with the element they belong to instead of failing silently.
+
+What happens to an element with errors is up to you, with the third argument of `customFormRender`:
+
+```js
+customFormRender(player, formData, { onInvalid: "label" });  // default
+```
+
+| `onInvalid` | Behaviour |
+| --- | --- |
+| `"label"` | Shows a visible placeholder in its place (handy while developing). |
+| `"skip"` | Leaves the element out (better for production or for content you load from outside). |
+| `"throw"` | Does not open the form and throws a `FormValidationError` (its `issues` property lists every problem). |
+
+If the problem is in the view itself (`title` missing, `content` not an array, no `player`), the form cannot be built: the report is logged and `customFormRender` returns `undefined`.
+
+You can also validate without rendering, for example in a test or for views that come from a server:
+
+```js
+import { validateForm } from "bedrock-ddui-forms";
+
+const report = validateForm(formData, player);
+report.errors;    // problems that break an element
+report.warnings;  // likely mistakes
+report.message;   // the text shown above
+```
+
+## Return value
+
+`customFormRender(player, formData)` returns a promise that resolves with the `DataDrivenScreenClosedReason` (`ClientClosed`, `ServerClosed` or `UserBusy`), or `undefined` if the view could not be built or an error occurred while showing it. A `UserBusy` result also logs a warning.
+
+## Project layout
+
+```
+index.js                  public entry point
+core/
+  customFormRender.js     renders a view and shows it to the player
+  propertiesFactory.js    maps each `type` to its CustomForm call
+  validation.js           checks views and builds the error messages
+models/properties/
+  *.js                    JSDoc typedefs for each element
+```
+
+## Adding a new element type
+
+1. Create its typedef in `models/properties/` and add it to the `Property` union.
+2. Write its function in `propertiesFactory.js`.
+3. Register it in the `properties` table.
+
+## Disclaimer
+
+This project is not affiliated with, endorsed by, or sponsored by Mojang Studios or Microsoft.

package/package.json

@@ -1,6 +1,35 @@
-{
-  "name": "bedrock-ddui-forms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+    "name": "bedrock-ddui-forms",
+    "version": "1.0.0",
+    "description": "A declarative layer for creating DDUI forms (CustomForm) from @minecraft/server-ui based on objects.",
+    "type": "module",
+    "main": "./src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "README.es.md"
+    ],
+    "scripts": {
+        "test": "node --import ./test/register-stubs.mjs --test \"test/*.test.js\""
+    },
+    "author": "victorsigma",
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/victorsigma/Bedrock-DDUI-Forms.git"
+    },
+    "keywords": [
+        "minecraft",
+        "bedrock",
+        "ddui",
+        "server-ui",
+        "forms",
+        "script-api"
+    ],
+    "peerDependencies": {
+        "@minecraft/server-ui": "2.2.0"
+    }
 }

package/src/core/customFormRender.js

@@ -0,0 +1,88 @@
+import { CustomForm, DataDrivenScreenClosedReason, ObservableString, ObservableUIRawMessage } from "@minecraft/server-ui";
+import { propertiesFactory } from "./propertiesFactory";
+import { FormValidationError, logCallbackError, validateForm } from "./validation";
+
+/**
+ * @typedef {Object} FormData
+ * @property {ObservableString | ObservableUIRawMessage | string} title
+ * @property {import("../models/properties/Property").Property[]} content
+ * @property {(this: CustomForm, reason: DataDrivenScreenClosedReason) => void} [onExit] - Runs after the form closes, for any reason except `UserBusy`.
+ */
+
+/**
+ * @typedef {Object} RenderOptions
+ * @property {"label" | "skip" | "throw"} [onInvalid] - What to do with elements that have errors.
+ *  - `"label"` (default): show a visible placeholder in their place.
+ *  - `"skip"`: leave them out of the form.
+ *  - `"throw"`: do not open the form and throw a `FormValidationError`.
+ */
+
+/**
+ * @param {import("@minecraft/server").Player} player
+ * @param {FormData} formData
+ * @param {RenderOptions} [options]
+ * @returns {Promise<DataDrivenScreenClosedReason | undefined>} Motivo de cierre, o undefined si la vista no pudo mostrarse.
+ */
+export const customFormRender = async (player, formData, options = {}) => {
+    const { onInvalid = "label" } = options;
+
+    const report = validateForm(formData, player);
+
+    if (report.errors.length) {
+        console.error(report.message);
+    } else if (report.warnings.length) {
+        console.warn(report.message);
+    }
+
+    if (report.errors.length && onInvalid === "throw") {
+        throw new FormValidationError(report);
+    }
+    if (report.fatal) return undefined;
+
+    let view = new CustomForm(player, formData.title);
+
+    formData.content.forEach((property, index) => {
+        const path = `content[${index}] ${property?.type ?? "element"}`;
+
+        if (report.invalid.has(index)) {
+            if (onInvalid !== "skip") view = placeholder(view, path);
+            return;
+        }
+
+        try {
+            view = propertiesFactory(view, property);
+        } catch (e) {
+            console.error(`[bedrock-ddui-forms] ${path}: the API rejected this element: ${e?.message ?? e}`);
+            if (onInvalid === "skip") return;
+            view = placeholder(view, path);
+        }
+    });
+
+    try {
+        const reason = await view.show();
+
+        if (reason === DataDrivenScreenClosedReason.UserBusy) {
+            console.warn("[bedrock-ddui-forms]: The player is busy with another UI.");
+        } else {
+            runOnExit(view, formData.onExit, reason);
+        }
+
+        return reason;
+    } catch (e) {
+        console.warn(`[bedrock-ddui-forms]: ${e}`);
+    }
+}
+
+/** Runs `onExit` on its own, so an error inside it is reported as such and does not look like a failure of show(). */
+const runOnExit = (view, onExit, reason) => {
+    if (typeof onExit !== "function") return;
+
+    try {
+        onExit.call(view, reason);
+    } catch (e) {
+        logCallbackError("onExit", e);
+    }
+};
+
+/** Visible stand-in for an element that could not be built. */
+const placeholder = (view, path) => view.label(`[invalid element] ${path} (see the console)`);