Guía
Formularios
Una ruta recibe sus formularios con actions. HTML que funciona sin JavaScript, validado en el servidor, con redirect, fail y validate.
Un formulario de Ascua es un <form method="post"> de HTML. El navegador ya
sabe enviarlo, seguir la redirección y volver atrás, así que funciona sin una
línea de JavaScript. Lo recibe la misma ruta que lo pinta, en actions.
Las acciones necesitan servidor: ascua({ site: { mode: "server" } }). Un
sitio estático con acciones no se construye, para que un formulario no se
pierda en silencio.
Una acción
// src/routes/orders/new.ts
import { fail, field, fields, redirect, validate, type ActionContext, type FormResult } from "vite-plugin-ascua/site";
const Order = fields({
product: field.text({ max: 80 }),
quantity: field.number({ min: 1, integer: true }),
urgent: field.checkbox(),
});
export const actions = {
async default({ formData }: ActionContext) {
const result = await validate(Order, formData);
if (!result.ok) return fail(400, result);
const id = await saveOrder(result.data);
throw redirect(`/orders/${id}`);
},
};
export default function NewOrder({ form }: { form?: FormResult<typeof Order> }) {
const errors = form?.ok === false ? form.errors : {};
const values = form?.ok === false ? form.values : {};
return view`
<form method="post">
<label>Producto <input name="product" value=${String(values.product ?? "")}></label>
<p class="error">${errors.product ?? ""}</p>
<label>Cantidad <input name="quantity" inputmode="numeric" value=${String(values.quantity ?? "")}></label>
<p class="error">${errors.quantity ?? ""}</p>
<label><input type="checkbox" name="urgent"> Urgente</label>
<button>Pedir</button>
</form>`;
}Lo que pasa al enviarlo:
- El navegador manda el
POSTa la misma URL y corre la accióndefault. - Si no vale,
fail(400, result)vuelve a pintar la página con un 400 y el resultado en la propform: los errores y lo que se había escrito. - Si vale,
redirectresponde con un 303. El navegador pide la página nueva con GET, y recargarla no reenvía el pedido.
Varias acciones
default atiende <form method="post">. Las demás se eligen con
?/nombre en el action del formulario:
export const actions = {
async default(context: ActionContext) { /* save */ },
async delete({ params }: ActionContext<{ id: string }>) {
await deleteOrder(params.id);
throw redirect("/orders");
},
};<form method="post" action="?/delete"><button>Borrar</button></form>Una acción recibe { params, url, request, cookies, formData }. Lo que
devuelva sin fail llega también en form, con un 200. Después de la acción
corre load(), así que la página ya ve lo que se guardó. notFound() dentro
de una acción responde con la página 404.
Validar
validate(esquema, formData) acepta cualquier
Standard Schema: los de fields, Zod, Valibot,
ArkType. Devuelve { ok: true, data } o { ok: false, errors, values }:
errors: el primer mensaje de cada campo, por su nombre.values: lo que se escribió, para volver a llenar el formulario. Sin archivos ni nada que se llame como una contraseña.
Lo que llega de un formulario siempre es texto. Los esquemas de field lo
convierten:
| Da | ||
|---|---|---|
field.text({ min, max, pattern, trim }) |
string |
Sin espacios en los extremos; obligatorio salvo min: 0 |
field.email() |
string |
Obligatorio |
field.number({ min, max, integer }) |
number |
Acepta coma decimal |
field.checkbox() |
boolean |
Marcada si llegó |
field.choice(["a", "b"]) |
"a" | "b" |
Uno de los dados |
field.optional(esquema) |
T | undefined |
Vacío es undefined |
Todos aceptan message para cambiar el mensaje. Los de serie salen en el
idioma del sitio: español, o inglés con ascua({ site: { lang: "en" } }). fields({ … }) los junta
en un objeto y, a diferencia de un esquema de objeto corriente, reúne los
errores de todos los campos a la vez: un formulario los muestra juntos.
p sigue siendo para los props de las islas, que llegan como
JSON y no como texto.
Sin recargar la página: enhance
El formulario de arriba recarga la página en cada envío. Si está dentro de
una isla, enhance() lo envía con fetch y deja el resultado
en signals: los errores aparecen sin recargar, lo escrito no se pierde y el
botón se puede desactivar mientras se envía. Sin JavaScript, el mismo
<form method="post"> sigue funcionando como siempre.
// src/islands/order-form.ts
import { defineIsland } from "ascua";
import { enhance, formResult } from "vite-plugin-ascua/form";
import type { FormResult } from "vite-plugin-ascua/site";
import type { Order } from "../routes/orders/new.js";
type Result = FormResult<typeof Order>;
function OrderForm(props: { form?: Result }) {
const order = enhance<Result>({ initial: props.form });
const errors = () => {
const result = order.result();
return result?.ok === false ? result.errors : {};
};
return view`
<form method="post" onsubmit=${order.submit}>
<label>Producto <input name="product"></label>
<p class="error">${() => errors().product ?? ""}</p>
<label>Cantidad <input name="quantity" inputmode="numeric"></label>
<p class="error">${() => errors().quantity ?? ""}</p>
<button disabled=${() => order.pending()}>Pedir</button>
<p class="error">${() => order.error() ?? ""}</p>
</form>`;
}
export const OrderFormIsland = defineIsland("order-form", { form: formResult<Result>() }, OrderForm);La página pinta la isla y le pasa su prop form: así, si el formulario se
envió sin JavaScript, la isla muestra los errores igual.
// src/routes/orders/new.ts — las mismas actions de antes
export default function NewOrder({ form }: { form?: FormResult<typeof Order> }) {
return view`<OrderFormIsland form=${form}/>`;
}enhance() devuelve:
submit |
Va en onsubmit. Un formulario GET lo deja pasar: la URL queda compartible. |
pending() |
Hay un envío en curso. Un segundo envío, mientras tanto, se ignora. |
result() |
Lo que devolvió la acción, o el data de su fail. |
error() |
Si no se pudo enviar, o el servidor lo rechazó: otro origen, una acción que no existe. |
status() |
El código: 200, el de fail, 403… |
Las acciones no cambian. Cuando el envío llega de enhance, el servidor
responde con el resultado en JSON en vez de con la página, y no corre
load(). El botón que envió el formulario cuenta igual que sin JavaScript:
su name y su value van en los datos, y su formaction elige la acción.
Si la acción redirige, enhance navega a la página nueva. Si sale bien,
vacía el formulario (reset: false lo evita) y llama a onSuccess.
Cookies
load() y las acciones reciben cookies. Se escriben seguras por defecto, y
las firmadas no se pueden cambiar sin el secreto:
export const actions = {
async default({ formData, cookies }: ActionContext) {
const user = await checkLogin(formData);
if (!user) return fail(401, { error: "No coincide" });
await cookies.setSigned("session", user.id, { maxAge: 60 * 60 * 24 * 7 });
throw redirect("/dashboard");
},
};
export async function load(_: object, { cookies }: LoadContext) {
const id = await cookies.getSigned("session"); // undefined si no hay, o si la tocaron
if (!id) throw redirect("/login");
return findUser(id);
}El detalle está en Seguridad.