bedrock-ddui-forms 1.0.0 → 1.1.0

package/README.es.md

@@ -24,6 +24,7 @@ En lugar de encadenar llamadas sobre `CustomForm`, describes la vista como datos
 - **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`.
+- **Router**: registra vistas por nombre, pásales parámetros y vuelve atrás con `"back"`.
 - **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.
 
@@ -151,6 +152,105 @@ Un botón puede abrir otra vista con `to`. Se ejecuta **después** de `onClick`,
 - 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.
 
+Para muchas vistas, parámetros y un botón de volver automático, mira el [Router](#router-vistas-con-nombre-y-atrás).
+
+## Router: vistas con nombre y "atrás"
+
+Cuando tus menús crecen, conectar cada botón con el siguiente `openX(player)` se vuelve repetitivo. `createRouter` registra tus vistas por nombre, permite que los botones apunten a ellas y guarda un **historial por jugador** para que un botón pueda volver atrás.
+
+```js
+import { ObservableBoolean } from "@minecraft/server-ui";
+import { createRouter } from "bedrock-ddui-forms/index";   // o desde tu carpeta libs/
+
+const router = createRouter({
+    menu: (player) => ({
+        title: "Menú",
+        content: [
+            { type: "button", label: "Mi perfil", to: { view: "profile", params: { name: player.name } } },
+            { type: "button", label: "Ajustes", to: "settings" },
+            { type: "close-button" }
+        ]
+    }),
+
+    profile: (player, params) => ({
+        title: `Perfil: ${params.name}`,
+        content: [
+            { type: "label", text: "Todavía no hay nada aquí." },
+            { type: "button", label: "Volver", to: "back" }
+        ]
+    }),
+
+    settings: (player) => ({
+        title: "Ajustes",
+        content: [
+            { type: "toggle", label: "Notificaciones", toggled: new ObservableBoolean(true, { clientWritable: true }) },
+            { type: "button", label: "Volver", to: "back" }
+        ]
+    })
+});
+
+// Iniciar un flujo
+router.open(player, "menu");
+```
+
+Cada vista es una función `(player, params) => formData`. Devuelve el mismo objeto que le darías a `customFormRender`, incluido `onExit`.
+
+### Valores que acepta `to`
+
+| `to` | Resultado |
+| --- | --- |
+| `"settings"` | Abre la vista registrada con ese nombre. |
+| `{ view: "profile", params: { ... } }` | Lo mismo, pasándole `params` a la vista. |
+| `"back"` | Vuelve a la vista anterior del historial del jugador. Si no hay ninguna, el formulario simplemente se cierra. |
+| una función | Funciona como el `to` normal (ver [Navegación](#navegación)), pero queda **fuera** del router: el historial del jugador se descarta. |
+
+Si usas el nombre de una vista que no registraste, el router lanza `Unknown View: "nombre"`.
+
+### Parámetros
+
+`params` es el segundo argumento de la función de la vista. Puedes pasarlos desde un botón (`to: { view, params }`) o al iniciar el flujo (`router.open(player, "profile", { name: "Alex" })`).
+
+Qué pasas es decisión tuya. El router guarda los `params` de cada paso en el historial y los vuelve a usar al volver atrás, de modo que la vista se reconstruye con los mismos `params`. Por eso los datos simples (nombres, ids, números) son la opción más segura: una entidad o un objeto de jugador guardado ahí puede dejar de ser válido cuando el jugador regrese a esa vista.
+
+Volver atrás **reconstruye** la vista llamando otra vez a su función, así que los valores que el jugador escribió (tus `Observable`) no se conservan: vuelven a sus valores iniciales.
+
+### Opciones del router
+
+```js
+const router = createRouter(views, { onInvalid: "skip" });
+```
+
+El segundo argumento acepta las mismas opciones que el tercer argumento de `customFormRender` (ver [Validación y mensajes de error](#validación-y-mensajes-de-error)) y se aplica a todas las vistas.
+
+### Qué devuelve `open`
+
+`router.open(...)` devuelve una promesa que se resuelve con el motivo de cierre de **la vista que abrió**, no de todo el flujo. Cuando un botón navega, el servidor cierra esa vista, así que se resuelve con `ServerClosed`. El `onExit` de cada vista sigue la misma regla descrita en [Cerrar una vista](#cerrar-una-vista-onexit).
+
+### Vida del historial y limpieza
+
+El router guarda en memoria el historial de cada jugador. Se borra cuando:
+
+- el jugador cierra el formulario,
+- un formulario se cierra desde código sin navegar (por ejemplo `this.close()` dentro de `onClick`),
+- vuelves a llamar a `router.open(...)`: un flujo nuevo siempre empieza limpio,
+- llamas a `router.clear(playerId)`.
+
+Si un jugador sale del servidor a mitad de un flujo, su historial queda en memoria hasta que ocurra una de esas cosas. Es una entrada pequeña por jugador, pero puedes liberarla cuando se vaya:
+
+```js
+import { world } from "@minecraft/server";
+
+world.afterEvents.playerLeave.subscribe(({ playerId }) => router.clear(playerId));
+```
+
+La librería no se suscribe a este evento por ti, a propósito:
+
+- así la librería depende solo de `@minecraft/server-ui`,
+- crear un router no engancha ningún evento global,
+- tú decides cómo y cuándo limpiar según tu addon.
+
+Suscríbete **una sola vez** (como arriba), no una vez por vista: una suscripción por vista se iría acumulando mientras los jugadores sigan conectados.
+
 ## Leer valores
 
 Los valores son los `Observable` que tú creas, así que guarda una referencia y léelos cuando los necesites:
@@ -247,6 +347,7 @@ 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
+  createRouter.js         vistas con nombre y historial de "atrás" por jugador
 models/properties/
   *.js                    typedefs de JSDoc de cada elemento
 ```

package/README.md

@@ -24,6 +24,7 @@ Instead of chaining calls on `CustomForm`, you describe a view as data and let a
 - **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`.
+- **Router**: register views by name, pass parameters between them and go back with `"back"`.
 - **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.
 
@@ -44,7 +45,7 @@ BP/
   manifest.json
   scripts/
     main.js
-    lib/bedrock-ddui-forms/
+    libs/bedrock-ddui-forms/
       index.js
       core/
       models/
@@ -151,6 +152,105 @@ A button can open another view with `to`. It runs **after** `onClick`, once the
 - 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.
 
+For many views, parameters and an automatic back button, see [Router](#router-named-views-and-back).
+
+## Router: named views and "back"
+
+When your menus grow, wiring every button to the next `openX(player)` gets repetitive. `createRouter` registers your views by name, lets buttons point to them, and keeps a **history per player** so a button can go back.
+
+```js
+import { ObservableBoolean } from "@minecraft/server-ui";
+import { createRouter } from "bedrock-ddui-forms/index";   // or from your libs/ folder
+
+const router = createRouter({
+    menu: (player) => ({
+        title: "Menu",
+        content: [
+            { type: "button", label: "My profile", to: { view: "profile", params: { name: player.name } } },
+            { type: "button", label: "Settings", to: "settings" },
+            { type: "close-button" }
+        ]
+    }),
+
+    profile: (player, params) => ({
+        title: `Profile: ${params.name}`,
+        content: [
+            { type: "label", text: "Nothing here yet." },
+            { type: "button", label: "Back", to: "back" }
+        ]
+    }),
+
+    settings: (player) => ({
+        title: "Settings",
+        content: [
+            { type: "toggle", label: "Notifications", toggled: new ObservableBoolean(true, { clientWritable: true }) },
+            { type: "button", label: "Back", to: "back" }
+        ]
+    })
+});
+
+// Start a flow
+router.open(player, "menu");
+```
+
+Each view is a function `(player, params) => formData`. It returns the same object you would give to `customFormRender`, including `onExit`.
+
+### Values accepted by `to`
+
+| `to` | Result |
+| --- | --- |
+| `"settings"` | Opens the view registered with that name. |
+| `{ view: "profile", params: { ... } }` | Same, passing `params` to the view. |
+| `"back"` | Returns to the previous view in the player's history. If there is none, the form just closes. |
+| a function | Works like the normal `to` (see [Navigation](#navigation)), but it is **outside** the router: the player's history is discarded. |
+
+If you use a view name that was not registered, the router throws `Unknown View: "name"`.
+
+### Parameters
+
+`params` is the second argument of the view function. You can pass it from a button (`to: { view, params }`) or when you start the flow (`router.open(player, "profile", { name: "Alex" })`).
+
+What you pass is up to you. The router stores the `params` of every step in the history and uses them again when going back, so the view is rebuilt with the same `params`. Because of that, plain data (names, ids, numbers) is the safest choice: an entity or a player object stored there may no longer be valid when the player returns to that view.
+
+Going back **rebuilds** the view by calling its function again, so the values the player typed (your `Observable`s) are not kept: they return to their initial values.
+
+### Router options
+
+```js
+const router = createRouter(views, { onInvalid: "skip" });
+```
+
+The second argument takes the same options as the third argument of `customFormRender` (see [Validation and error messages](#validation-and-error-messages)) and applies to every view.
+
+### What `open` returns
+
+`router.open(...)` returns a promise that resolves with the closing reason of **the view it opened**, not of the whole flow. When a button navigates, that view is closed by the server, so it resolves with `ServerClosed`. The `onExit` of each view follows the same rule described in [Closing a view](#closing-a-view-onexit).
+
+### History lifetime and cleanup
+
+The router keeps each player's history in memory. It is cleared when:
+
+- the player closes the form,
+- a form is closed from code without navigating (for example `this.close()` inside `onClick`),
+- you call `router.open(...)` again: a new flow always starts clean,
+- you call `router.clear(playerId)`.
+
+If a player leaves the server in the middle of a flow, their history stays in memory until one of those things happens. It is a small entry per player, but you can release it when they leave:
+
+```js
+import { world } from "@minecraft/server";
+
+world.afterEvents.playerLeave.subscribe(({ playerId }) => router.clear(playerId));
+```
+
+The library does not subscribe to this event for you, on purpose:
+
+- it keeps the library dependent only on `@minecraft/server-ui`,
+- creating a router does not hook any global event,
+- you decide how and when to clean up for your own addon.
+
+Subscribe **once** (as above), not once per view: a subscription per view would pile up while players stay online.
+
 ## Reading values
 
 The values are the `Observable` objects you create, so keep a reference and read them when you need them:
@@ -245,6 +345,7 @@ 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
+  createRouter.js         named views with a per-player "back" history
 models/properties/
   *.js                    JSDoc typedefs for each element
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bedrock-ddui-forms",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "A declarative layer for creating DDUI forms (CustomForm) from @minecraft/server-ui based on objects.",
     "type": "module",
     "main": "./src/index.js",

package/src/core/createRouter.js

@@ -0,0 +1,74 @@
+import { DataDrivenScreenClosedReason } from "@minecraft/server-ui";
+import { customFormRender } from "./customFormRender";
+
+/**
+ * @param {Record<string, (player: import("@minecraft/server").Player, params?: Record<string, any>) => import("./customFormRender").FormData>} views
+ * @param {import("./customFormRender").RenderOptions} [renderOptions]
+ */
+export const createRouter = (views, renderOptions) => {
+    const stacks = new Map();
+
+    const open = async (player, name, params = {}, push = true) => {
+        const build = views[name];
+        if (!build) throw new Error(`Unknown View: "${name}"`);
+
+        const form = build(player, params);
+
+        const stack = stacks.get(player.id) ?? [];
+        const entry = { name, params };
+        if (push) stack.push(entry);
+        stacks.set(player.id, stack);
+
+        let navigated = false; // ¿este formulario se cerró porque el router navegó?
+
+        const content = form.content.map((prop) => {
+            if (prop.type !== "button" || prop.to === undefined || typeof prop.to === "function") return prop;
+
+            if (prop.to === "back") {
+                return {
+                    ...prop,
+                    to: () => {
+                        navigated = true;
+                        stack.pop();
+                        const prev = stack[stack.length - 1];
+                        if (prev) open(player, prev.name, prev.params, false);
+                        else stacks.delete(player.id); // no hay a dónde volver
+                    }
+                };
+            }
+
+            const target = typeof prop.to === "string" ? { view: prop.to, params: {} } : prop.to;
+            return {
+                ...prop,
+                to: () => {
+                    navigated = true;
+                    open(player, target.view, target.params);
+                }
+            };
+        });
+
+        return Promise.resolve(customFormRender(player, { ...form, content }, renderOptions)).then((reason) => {
+            // Si otra apertura ya reemplazó la pila, no tocar nada
+            if (stacks.get(player.id) !== stack) return reason;
+
+            if (
+                reason === DataDrivenScreenClosedReason.ClientClosed ||
+                (reason === DataDrivenScreenClosedReason.ServerClosed && !navigated)
+            ) {
+                stacks.delete(player.id); // cerró el jugador, o se cerró por código
+            } else if (push && (reason === undefined || reason === DataDrivenScreenClosedReason.UserBusy)) {
+                const i = stack.lastIndexOf(entry);
+                if (i !== -1) stack.splice(i, 1); // nunca se mostró
+            }
+            return reason;
+        });
+    };
+
+    return {
+        open: (player, name, params) => {
+            stacks.delete(player.id); // una apertura raíz siempre empieza limpia
+            return open(player, name, params);
+        },
+        clear: (playerId) => stacks.delete(playerId), // opcional, para quien lo quiera
+    };
+};

package/src/index.js

@@ -1,2 +1,3 @@
 export { customFormRender } from "./core/customFormRender";
+export { createRouter } from "./core/createRouter";
 export { validateForm, FormValidationError } from "./core/validation";