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

ts
// 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:

  1. El navegador manda el POST a la misma URL y corre la acción default.
  2. Si no vale, fail(400, result) vuelve a pintar la página con un 400 y el resultado en la prop form: los errores y lo que se había escrito.
  3. Si vale, redirect responde 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:

ts
export const actions = {
  async default(context: ActionContext) { /* save */ },
  async delete({ params }: ActionContext<{ id: string }>) {
    await deleteOrder(params.id);
    throw redirect("/orders");
  },
};
html
<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.

ts
// 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.

ts
// 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:

ts
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.