Máscaras

Da formato mientras se escribe, comprueba el dígito verificador de documentos y oculta datos sensibles. No sustituye el campo por otro control: es comportamiento sobre tu <input>, que sigue con su name y con el estilo que el proyecto ya aplica.

Ejemplos

Todo es el mismo data-tuc-mask con otro formato. El texto de espera sale del patrón — nadie escribe 000.000.000-00 a mano. Los formatos con nombre siguen documentos y convenciones de Brasil; el patrón libre sirve para cualquier otra cosa.

Cómo usar

Marca el <input> con el formato, y se inicializa solo al cargar y en cada htmx:afterSwap. El componente pone la clase .tuc-input en el campo y un inputmode numérico cuando el patrón no acepta letras, para que el móvil abra el teclado de números.

<input name="cpf"      data-tuc-mask="cpf" data-validate="true">
<input name="document" data-tuc-mask="cpf-cnpj">
<input name="phone"    data-tuc-mask="phone">
<input name="amount"   data-tuc-mask="brl">
<input name="expiry"   data-tuc-mask="##/##">

En el formulario de Django

class CustomerForm(forms.ModelForm):
    class Meta:
        model = Customer
        fields = ["document", "phone", "credit_limit"]
        widgets = {
            "document": forms.TextInput(attrs={"data-tuc-mask": "cpf-cnpj", "data-validate": "true"}),
            "phone": forms.TextInput(attrs={"data-tuc-mask": "phone"}),
            "credit_limit": forms.TextInput(attrs={"data-tuc-mask": "brl"}),
        }

El campo envía el texto tal como está en pantalla: 111.444.777-35, R$ 1.234,50. Límpialo en el clean_ — la validación del navegador protege la pantalla, no el servidor.

def clean_document(self):
    return re.sub(r"[^0-9A-Z]", "", self.cleaned_data["document"].upper())

def clean_credit_limit(self):
    text = re.sub(r"[^\d,]", "", self.cleaned_data["credit_limit"])
    return Decimal(text.replace(",", ".")) if text else None

En JavaScript

const m = new Tucano.Mask('#amount', { format: 'brl' });
m.getRaw();          // '123450' — sin puntuación
m.getNumber();       // 1234.5 — solo en los formatos de moneda; en los demás, null
m.setValue('99');    // da formato y dispara tucano:change
m.isValid();         // comprueba el dígito verificador, en los formatos que lo tienen
m.destroy();

document.querySelector('#amount').addEventListener('tucano:change', (e) => {
  e.detail.value;    // 'R$ 1.234,50'
  e.detail.raw;      // '123450'
  e.detail.number;   // 1234.5
});

Las utilidades detrás de la máscara también vienen listas, para validar o dar formato fuera de un campo:

Tucano.mask.validateCPF('111.444.777-35')              // true
Tucano.mask.validateCNPJ('11.222.333/0001-81')         // true
Tucano.mask.validateCpfCnpj('123.456.789-01')          // false
Tucano.mask.format('12345678901', 'cpf')               // '123.456.789-01'
Tucano.mask.applyCurrency('12345', { currency: 'BRL' }) // 'R$ 123,45'
Tucano.mask.maskEmail('contato@empresa.com.br')        // 'c••••••@empresa.com.br'

Validación

Con data-validate, el dígito verificador se comprueba al salir del campo. Si falla, el campo recibe aria-invalid="true" y setCustomValidity, y el propio navegador bloquea el envío — sin una línea en el proyecto.

Y el acierto se ve al momento: en cuanto el valor está completo y correcto, el campo se pone verde, sin esperar a salir de él. El error espera — mientras se escribe, un CPF a medias nunca se pone rojo; solo se señala al salir del campo, y vuelve a desaparecer cuando la persona lo corrige. El verde es el atributo data-tuc-valid, pintado con --tuc-success.

Valen cpf, cnpj, cnpj-numeric y cpf-cnpj; los demás formatos no tienen dígito que comprobar. Un campo vacío pasa: la obligatoriedad es cosa de required. Mientras se escribe el error desaparece, y al volver al campo también — incluida la marca que vino del servidor, porque la persona está corrigiendo.

<input name="cpf" data-tuc-mask="cpf" data-validate="true" data-error-text="Revisa el CPF">

Campo sensible

data-tuc-reveal pone un ojo para mostrar y ocultar. Un campo que ya llega relleno nace oculto, con solo el final visible; un campo vacío nace visible, porque quien escribe necesita ver. La contraseña es la excepción: nace siempre oculta.

<input name="cpf" value="111.444.777-35" data-tuc-mask="cpf" data-tuc-reveal>
<input name="card" data-tuc-mask="card" data-tuc-reveal data-reveal-visible="4">
<input name="api_key" data-tuc-reveal="all">
<input type="email" name="email" data-tuc-reveal>
<input type="password" name="password" data-tuc-reveal>

Lo que el formulario envía no cambia por estar oculto. Fuera de type="password", el name pasa a un <input type="hidden"> con el valor real, y el campo visible muestra los puntos. Mientras está oculto, el campo es de solo lectura: escribir sobre los puntos sobrescribiría el valor sin que la persona se diera cuenta. Los separadores siguen en su sitio, para que la forma siga siendo reconocible: •••.•••.•••-35.

Texto suelto en la pantalla

No todo dato sensible está en un campo: el CPF en la pantalla de un cliente, la tarjeta en una celda de tabla, la clave de API en un párrafo. data-tuc-reveal vale en cualquier elemento, en los mismos modos, y junto con data-tuc-format. El texto nace oculto, con el ojo al lado.

<td><span data-tuc-format="cpf" data-tuc-reveal>{{ customer.cpf }}</span></td>
<td><span data-tuc-reveal data-reveal-visible="4">{{ card.number }}</span></td>
<p>Clave de API: <span data-tuc-reveal="all">{{ api_key }}</span></p>

Solo para mostrar

Para lo que ya viene de la base de datos y no se edita, no hace falta un campo: data-tuc-format da formato al texto del propio elemento.

<span data-tuc-format="cpf">{{ customer.cpf }}</span>
<span data-tuc-format="brl">{{ order.total }}</span>
<span data-tuc-format="phone" data-value="{{ customer.phone }}"></span>

Acepta cpf, cnpj, cpf-cnpj, phone, mobile, cep, card, real, currency y patrón libre, con data-decimals y data-currency en la moneda. El valor sale del texto del elemento o de data-value. La moneda lee el punto decimal de la base de datos (1234.5) y también la coma. Un contenido que no completa el patrón vuelve tal como vino, en lugar de salir a medias y parecer corrupto. Para HTML insertado por otro camino que no sea HTMX, Tucano.autoFormat(element).

Teclado y accesibilidad

La máscara usa el teclado del navegador, sin atajos propios. De lo que se ocupa es de que el cursor no se pierda.

El ojo anuncia "Mostrar" u "Ocultar" y el estado con aria-pressed. Al mostrar, el foco va al campo. Si falla la validación, el campo queda con aria-invalid="true", que el lector de pantalla lee como no válido.

API

Generada a partir del código en cada build — si algo no está aquí, no existe.

Opciones

Las notas de esta tabla salen de los comentarios del código fuente, que están escritos en portugués.