@nexdom/uimed-vue 2.0.0-beta.9 → 2.0.0

package/skills/uimed-vue/references/guide/components/main.md

@@ -0,0 +1,435 @@
+# Componente base
+
+O componente destinado a raiz do projeto se chama `Main`.
+
+É responsável por carregar o menu superior, o menu de navegação lateral, o rodapé, os componentes utilizados pelos composables de [Toasts](../composables/use-toast.md), [Diálogos](../composables/use-dialog.md), [Confirmações](../composables/use-confirm.md) e [Alterações não salvas](../composables/use-unsaved-changes.md) e os estilos necessários para os demais componentes.
+
+## Propriedades
+
+### Logo
+
+A `logo` nos permite provisionar a URL que será utilizada pelo `Main` para orquestrar a apresentação de uma imagem de logo na aplicação.
+
+A logo é decorativa e não é anunciada por leitores de tela, que identificam a aplicação pelo título do menu superior (`title` da prop `app-bar`); por isso, informe o título junto com a `logo`.
+
+```vue
+<template>
+  <u-main :appBar :logo>
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { reactive, ref, watch } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const logo = "/uimed-vue/favicon.svg";
+
+const appBar = reactive<NonNullable<MainProps["appBar"]>>({
+  title: "Menu superior",
+});
+</script>
+```
+
+### Menu superior
+
+A prop `app-bar` define as configurações para apresentação do menu superior.
+
+Para ocultar o menu superior, basta omitir essa prop.
+
+As ações do menu superior têm nomes fixos para leitores de tela: "Menu de navegação" (exibido apenas em telas pequenas, que também informa se o menu de navegação está aberto ou fechado), "Ajuda", "Notificações" e "Menu do usuário". Quando há notificações não lidas, o botão de notificações inclui a quantidade no nome, por exemplo "Notificações (2 não lidas)" ou "Notificações (1 não lida)".
+
+No menu do usuário aberto, o avatar aparece maior e centralizado, com o nome (`title`) e o `subtitle` do usuário abaixo dele.
+
+```vue
+<template>
+  <u-main :appBar @update:notifications-open="toggleNotifications">
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { reactive, ref, watch } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const appBar = reactive<NonNullable<MainProps["appBar"]>>({
+  title: "Menu superior",
+  help: "https://www.google.com",
+  notifications: [
+    {
+      title: "v1.1",
+      subtitle: "Nova versão disponível para instalação.",
+      when: "10:30",
+      read: false,
+    },
+    {
+      title: "v1",
+      subtitle: "Nova versão disponível para testes.",
+      when: "Ontem",
+      read: false,
+    },
+    {
+      title: "vBeta",
+      subtitle: "Nova versão disponível para testes.",
+      when: "29/09/2026",
+      read: true,
+    },
+    {
+      title: "vAlpha",
+      subtitle: "Nova versão disponível para testes.",
+      when: "28/09/2026",
+      read: true,
+    },
+  ],
+  user: {
+    title: "Rafael Perini",
+    subtitle: "UIMed-Vue Co-Creator",
+    img: "/uimed-vue/avatar.jpg",
+    options: [
+      {
+        description: "Bibliotecas",
+        items: [
+          {
+            description: "Pkg-template",
+            route: "https://nexdom-healthtech.github.io/pkg-template/",
+          },
+          {
+            description: "Shared",
+            route: "https://nexdom-healthtech.github.io/shared/",
+          },
+          {
+            description: "UIMed-Vue",
+            route: "https://nexdom-healthtech.github.io/uimed-vue/",
+          },
+        ],
+      },
+      {
+        description: "GitHub NEXDOM",
+        route: "https://github.com/nexdom-healthtech",
+      },
+      { description: "Sair", action: () => window.alert("Saindo...") },
+    ],
+  },
+});
+
+function toggleNotifications(open: boolean) {
+  if (!open) {
+    appBar.notifications = appBar.notifications?.map((notification) => ({
+      ...notification,
+      read: true,
+    }));
+  }
+}
+</script>
+```
+
+#### Usuário sem imagem
+
+O avatar do usuário mostra a imagem informada em `img`. Sem `img`, ele mostra as iniciais do `title`: a primeira letra do primeiro e do último nome, como "RP" para "Rafael Perini". Sem `img` nem `title`, ele mostra um ícone genérico. A regra vale tanto para o botão do menu superior quanto para o menu do usuário aberto.
+
+O avatar é decorativo: leitores de tela não leem as iniciais e continuam anunciando o botão como "Menu do usuário".
+
+```vue
+<template>
+  <u-main :appBar>
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+  user: {
+    title: "Rafael Perini",
+    subtitle: "UIMed-Vue Co-Creator",
+    options: [{ description: "Sair", action: () => window.alert("Saindo...") }],
+  },
+};
+</script>
+```
+
+#### Detalhes do usuário
+
+Para mostrar mais informações do usuário no menu, como a empresa e o perfil de acesso, use o slot `user-section-details`. O conteúdo aparece abaixo do nome e do subtítulo e acima das opções, com o texto centralizado como eles. O slot aceita qualquer conteúdo, inclusive ações, como um botão para gerenciar o perfil.
+
+O slot só é exibido quando há um menu do usuário, ou seja, quando `appBar.user` é informado.
+
+```vue
+<template>
+  <u-main :appBar>
+    <template #user-section-details>
+      <u-row>
+        <u-column cols="12">
+          <strong>Unimed do Estado de Santa Catarina</strong>
+          <div>Perfil Administrador</div>
+        </u-column>
+      </u-row>
+      <u-row>
+        <u-column cols="12">
+          <u-button variant="secondary" full-width @click="manageProfile">
+            Gerenciar perfil
+          </u-button>
+        </u-column>
+      </u-row>
+    </template>
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UColumn, UMain, URow } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+  user: {
+    title: "Julyana Costa",
+    subtitle: "julyana.costa@example.com",
+    options: [{ description: "Sair", action: () => window.alert("Saindo...") }],
+  },
+};
+
+function manageProfile() {
+  window.alert("Abrindo o perfil...");
+}
+</script>
+```
+
+### Menu de navegação
+
+A prop `navigation-menu` define as configurações para apresentação do menu lateral de navegação.
+
+Para ocultar o menu de navegação, basta omitir essa prop.
+
+Em telas largas (a partir de 1145px), o menu fica sempre visível à esquerda do conteúdo, recolhido, mostrando apenas os ícones dos itens e grupos do primeiro nível e um item "Buscar". Ele se expande sobre o conteúdo, sem deslocá-lo, enquanto o mouse está sobre ele, enquanto o foco do teclado está nele ou pelo atalho de busca, e volta a se recolher quando o mouse e o foco saem dele. Recolhido, ele destaca o grupo que contém a página atual; expandido, abre esse grupo e destaca apenas o item da página. Ao se recolher, ele fecha os grupos e limpa o texto da busca.
+
+Em telas pequenas, o menu fica oculto e é aberto sobre o conteúdo pelo botão "Menu de navegação" do menu superior.
+
+Os itens e grupos do primeiro nível do menu exibem um ícone antes da sua descrição, informado pelo nome na propriedade obrigatória `icon`. Os nomes disponíveis estão em [Ícones](../icons.md). Os itens dentro de um grupo não aceitam ícones, para que o menu siga o mesmo padrão visual em todas as aplicações.
+
+O menu também conta com um campo de busca que filtra itens e grupos em tempo real, no formato _case-insensitive_.
+
+O atalho `Ctrl + K` (`⌘ + K` no macOS), indicado no próprio campo de busca, expande o menu (ou o abre, em telas pequenas) e coloca o foco na busca, com o texto já digitado selecionado. Com o menu expandido ou aberto, o atalho apenas leva o foco de volta à busca. Levar o foco ao item "Buscar" do menu recolhido tem o mesmo efeito. Ele funciona mesmo com o foco em um campo de formulário, mas é ignorado com o foco dentro de diálogos, confirmações, menus suspensos e editores de texto rico, ou no botão de um menu suspenso aberto.
+
+A tecla `Esc` recolhe (ou fecha) o menu enquanto o foco está nele ou, se ele foi expandido pelo atalho, mesmo com o foco fora dele (como durante o carregamento, em que a busca desabilitada não recebe o foco). Se o menu foi expandido pelo atalho ou pelo item "Buscar", o foco volta ao elemento que o tinha antes. Recolhido pelo `Esc`, o menu só volta a se expandir quando o mouse entra nele, quando o foco sai e volta a ele, ou pelo atalho.
+
+Quando a página tem mais de um `UMain` com menu de navegação, apenas o primeiro responde ao atalho. Por isso, nesta página, `Ctrl + K` abre o menu da demonstração abaixo em vez da busca da documentação, que continua disponível pela tecla `/`.
+
+```vue
+<template>
+  <u-main :appBar :navigationMenu>
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { ref, reactive } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+};
+
+const navigationMenu: NonNullable<MainProps["navigationMenu"]> = {
+  items: [
+    {
+      description: "Início",
+      route: "/",
+      icon: "home",
+    },
+    {
+      description: "Documentação",
+      icon: "folder",
+      items: [
+        {
+          description: "Componentes",
+          route: "/components",
+        },
+        {
+          description: "Composables",
+          route: "/composables",
+        },
+      ],
+    },
+    {
+      description: "Configurações",
+      icon: "cog",
+      action: () => window.alert("Abrindo configurações..."),
+    },
+  ],
+};
+</script>
+```
+
+### Carregamento
+
+A prop `loading` exibe skeletons no lugar das ações do menu superior (ajuda, notificações e usuário) e dos itens do menu de navegação, enquanto os dados do usuário e as opções de menu são carregados.
+
+A logo e o título continuam visíveis, assim como o botão do menu de navegação, em telas pequenas. O menu de navegação continua se expandindo (ou abrindo, em telas pequenas) normalmente, com a busca e o item "Buscar" desabilitados, e ao final do carregamento os itens aparecem já filtrados pelo texto buscado. Se o menu de notificações estiver aberto quando o carregamento começar, ele é fechado.
+
+O conteúdo da página não é afetado: nele, utilize a prop `loading` dos próprios componentes, como o [Section](./section.md).
+
+```vue
+<template>
+  <u-main :appBar :navigationMenu :loading>
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+// Altere para `false` quando os dados do usuário e do menu forem carregados
+const loading = ref(true);
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+  help: "https://www.google.com",
+  notifications: [],
+  user: {
+    title: "Rafael Perini",
+    subtitle: "UIMed-Vue Co-Creator",
+  },
+};
+
+const navigationMenu: NonNullable<MainProps["navigationMenu"]> = {
+  items: [
+    {
+      description: "Início",
+      route: "/",
+      icon: "home",
+    },
+    {
+      description: "Configurações",
+      icon: "cog",
+      action: () => window.alert("Abrindo configurações..."),
+    },
+  ],
+};
+</script>
+```
+
+### Rodapé
+
+A prop `footer` exibe um texto fixo na parte inferior da tela, como a versão da aplicação, para que o usuário consiga informá-la ao suporte ao relatar um problema. O texto fica centralizado e o conteúdo da página termina acima do rodapé, sem ficar coberto por ele.
+
+Para ocultar o rodapé, basta omitir essa prop ou deixar o seu `description` vazio, por exemplo enquanto o usuário não estiver autenticado. O carregamento (prop `loading`) não afeta o rodapé.
+
+```vue
+<template>
+  <u-main :appBar :footer="isAuthenticated ? footer : undefined">
+    <h2>O conteúdo da página vai aqui...</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const isAuthenticated = ref(true);
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+};
+
+const footer: NonNullable<MainProps["footer"]> = {
+  description: "Versão 1.4.2",
+};
+</script>
+```
+
+### Cor de fundo
+
+A prop `background` aplica uma cor ao fundo de toda a aplicação, como em landing pages, com as mesmas opções de cor do [Botão](./button.md): `primary`, `secondary`, `positive`, `informative`, `caution` e `danger`. Quando omitida, a aplicação usa o fundo padrão do tema.
+
+O texto colocado diretamente sobre o fundo passa a usar a cor associada a ele (branco ou preto). O menu superior, o rodapé, as [Sections](./section.md) e os diálogos mantêm os próprios fundos.
+
+Cuide do contraste ao escolher a cor:
+
+- `secondary` é a mesma cor do fundo das [Sections](./section.md) e do menu superior, que perdem a separação do restante da página.
+- Evite combinações em que o componente some no fundo, como um botão `primary` ou links sobre o fundo `primary`, ou links e campos de formulário sobre o fundo `danger`.
+
+```vue
+<template>
+  <u-main background="primary" :appBar>
+    <h2>Boas-vindas ao portal</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+};
+</script>
+```
+
+## Eventos
+
+### Notificações
+
+O evento `update:notificationsOpen` é emitido sempre que o menu de notificações é aberto ou fechado.
+
+```vue
+<template>
+  <u-main :app-bar="appBar" @update:notifications-open="onNotificationsOpen">
+    <h2>{{ notificationsOpenCount }} interação(ões)</h2>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const notificationsOpenCount = ref(0);
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+  notifications: [],
+};
+
+function onNotificationsOpen() {
+  notificationsOpenCount.value++;
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UMain](../../api/components/main.md) para a lista completa de props, slots e eventos.
+
+O conteúdo da página ocupa toda a altura visível abaixo do menu superior (e acima do rodapé, quando exibido): para centralizar o formulário de uma tela de login nela, por exemplo, veja [Altura total](./layout.md#altura-total) nos componentes de layout.

package/skills/uimed-vue/references/guide/components/mask-field.md

@@ -0,0 +1,256 @@
+# Campos com máscara
+
+O componente para campos com máscara se chama `MaskField`.
+
+Ele funciona como um [campo de texto](./text-field.md), mas formata o valor enquanto o usuário digita, inserindo automaticamente os separadores da máscara (`.`, `-`, `/`, `(`, `)`, espaço). O `v-model` recebe **somente os caracteres digitados**, sem os separadores e com as letras em maiúsculas (por exemplo, `12345678909` para o CPF `123.456.789-09` e `12ABC34501DE35` para o CNPJ `12.ABC.345/01DE-35`), que é o formato normalmente enviado ao backend.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<input>` nativo e do `UTextField` sempre que o valor tiver uma máscara.
+
+## Propriedades
+
+### Máscaras predefinidas
+
+A prop `mask` é obrigatória e define a máscara aplicada ao campo. A biblioteca oferece as seguintes máscaras predefinidas:
+
+| `mask`  | Máscara              | Exemplo exibido                              | `v-model`                            |
+| ------- | -------------------- | -------------------------------------------- | ------------------------------------ |
+| `cpf`   | `###.###.###-##`     | `123.456.789-09`                             | `12345678909`                        |
+| `cnpj`  | `##.###.###/####-##` | `12.345.678/0001-95`<br>`12.ABC.345/01DE-35` | `12345678000195`<br>`12ABC34501DE35` |
+| `cep`   | `#####-###`          | `01310-100`                                  | `01310100`                           |
+| `phone` | `(##) #####-####`    | `(11) 91234-5678`                            | `11912345678`                        |
+| `date`  | `##/##/####`         | `31/12/2026`                                 | `31122026`                           |
+
+A máscara `cnpj` aceita tanto o CNPJ numérico quanto o alfanumérico (IN RFB nº 2.229/2024): as 12 primeiras posições aceitam letras de A a Z, sem acento, ou dígitos, e as 2 últimas (os dígitos verificadores), somente dígitos. As letras podem ser digitadas ou coladas em minúsculas: o campo as exibe e as envia ao `v-model` em maiúsculas. O CNPJ alfanumérico só é aceito com `mask="cnpj"`: a máscara `##.###.###/####-##`, informada como máscara personalizada, aceita somente dígitos.
+
+```vue
+<template>
+  <u-mask-field v-model="cpf" label="CPF" mask="cpf" />
+  <u-mask-field v-model="cnpj" label="CNPJ" mask="cnpj" />
+  <u-mask-field v-model="cep" label="CEP" mask="cep" />
+  <u-mask-field v-model="phone" label="Celular" mask="phone" />
+  <u-mask-field v-model="date" label="Data" mask="date" />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UMaskField } from "@nexdom/uimed-vue/components";
+
+const cpf = ref("");
+const cnpj = ref("");
+const cep = ref("");
+const phone = ref("");
+const date = ref("");
+</script>
+```
+
+> [!Tip]
+> A máscara `phone` tem 11 dígitos (DDD e celular). Um telefone fixo, com 10 dígitos, é considerado incompleto e exibe a mensagem "Valor incompleto".
+
+> [!Warning]
+> O campo não valida os dígitos verificadores do CPF e do CNPJ nem a existência do documento: ele só confere o formato. Valide o documento no backend da aplicação.
+
+> [!Tip]
+> A máscara `date` apenas formata o valor: ela não valida se a data existe (`31/02/2026` é aceito) e o `v-model` fica no formato `DDMMAAAA` (por exemplo, `31122026`). Para datas, prefira os [campos de data e hora](./date-time-field.md), que oferecem seletor, limites e o formato padrão `YYYY-MM-DD`.
+
+### Máscaras personalizadas
+
+A prop `mask` também aceita a própria máscara, em que `#` representa um dígito (0–9) e qualquer outro caractere é um separador fixo, inserido automaticamente e fora do `v-model`. Os separadores podem ser símbolos, espaços ou letras: em `####-##/####`, o valor `1234561234` é exibido como `1234-56/1234`, e em `Nº ####`, o valor `1234` é exibido como `Nº 1234`. Uma máscara personalizada precisa ter pelo menos um `#`: o tipo da prop `mask` rejeita uma máscara sem ele, assim como o nome de uma máscara predefinida escrito errado (como `cpff`).
+
+```vue
+<template>
+  <u-mask-field v-model="protocol" label="Protocolo" mask="####-##/####" />
+  <u-mask-field v-model="number" label="Número" mask="Nº ####" />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UMaskField } from "@nexdom/uimed-vue/components";
+
+const protocol = ref("");
+const number = ref("");
+</script>
+```
+
+> [!Warning]
+> Evite separadores fixos que o usuário também poderia digitar, como os dígitos de `0800 ###-####` ou o `55` de `+55 (##) #####-####`: quando o campo espera um desses separadores, o caractere igual a ele é lido como o separador, e não como valor. Por exemplo, digitar `0` no campo vazio de `0800 ###-####` não tem efeito, e o `v-model` `0800123` é exibido como `0800 123-`. Nesses casos, deixe o trecho fixo fora da máscara (por exemplo, no `label` ou no `hint`).
+
+### Comportamento ao digitar
+
+- Somente dígitos são aceitos, exceto nas 12 primeiras posições da máscara `cnpj`, que também aceitam letras de A a Z, sem acento, convertidas para maiúsculas. Os demais caracteres (símbolos, letras acentuadas, `ç` e letras nos dígitos verificadores do CNPJ) são descartados, sem atualizar o `v-model`. O número de caracteres é limitado pela quantidade de posições da máscara (por exemplo, 14 no CNPJ).
+- Um separador aparece assim que a posição anterior a ele é preenchida (`123` vira `123.`). Se o usuário digitar o próprio separador na posição dele, ele não é duplicado.
+- Com a máscara completa, um caractere digitado no final é ignorado. Digitado no meio, ele é inserido, e o último caractere do valor é descartado.
+- Inserir ou apagar um caractere no meio do valor desloca os caracteres seguintes, e um caractere que não cabe na nova posição é descartado. Por exemplo, no CNPJ `12.345.678/90AB-12`, digitar `9` no início desloca a letra `B` para os dígitos verificadores, onde ela é descartada, e o valor passa a ser `91.234.567/890A-12`.
+- `Backspace` logo após um separador apenas move o cursor para antes dele, e o próximo `Backspace` apaga o caractere anterior. Da mesma forma, `Delete` logo antes de um separador move o cursor para depois dele. Ao apagar uma seleção, somente os caracteres selecionados são removidos (uma seleção só com separadores não apaga nada), e o valor é formatado novamente.
+- Ao colar um valor, com ou sem formatação, em maiúsculas ou minúsculas, o resultado é o mesmo: os caracteres que a máscara não aceita são descartados e o excesso é cortado no final.
+- O cursor permanece após o mesmo caractere ao digitar, apagar ou colar no meio do valor, inclusive com teclados com composição de texto (IME).
+- Em dispositivos móveis, o teclado numérico é exibido nas máscaras que aceitam somente dígitos. Na máscara `cnpj`, que aceita letras, é exibido o teclado de texto, já em maiúsculas.
+
+> [!Warning]
+> Como o valor é reescrito a cada alteração, o histórico de desfazer do navegador (`Ctrl+Z`) não fica disponível no campo.
+
+### Valor inicial
+
+Quando o `v-model` chega fora do formato (com a máscara, por exemplo), o campo exibe o valor normalizado, sem alterar o `v-model`. Um `v-model` com letras minúsculas na máscara `cnpj` (como `12abc34501de35`) é exibido em maiúsculas e é válido, e só é enviado em maiúsculas quando o usuário altera o valor. Quando ele não cabe na máscara, por ter mais caracteres do que ela comporta ou caracteres fora do formato dela (como letras no CPF ou nos dígitos verificadores do CNPJ), o campo exibe somente a parte que cabe, e a validação falha com a mensagem "Valor inválido", exibida assim que o campo é validado (ao sair dele ou ao enviar o [formulário](./form.md)). Em todos os casos, o `v-model` só é alterado quando o usuário altera o valor exibido: colar o mesmo valor que já está exibido não o altera.
+
+```vue
+<template>
+  <u-mask-field v-model="maskedCpf" label="CPF com máscara" mask="cpf" />
+  <u-mask-field v-model="longCpf" label="CPF com dígitos a mais" mask="cpf" />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UMaskField } from "@nexdom/uimed-vue/components";
+
+const maskedCpf = ref("123.456.789-09");
+const longCpf = ref("123456789099");
+</script>
+```
+
+> [!Important]
+> Trocar a prop `mask` com o campo preenchido (por exemplo, de `cnpj` para `cpf`) não altera o `v-model`: um valor que não cabe na nova máscara é exibido cortado e falha na validação com a mensagem "Valor inválido". Ao trocar a máscara, ajuste ou limpe o valor na aplicação.
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao campo. O padrão é `primary`.
+
+```vue
+<template>
+  <u-mask-field label="Primary" mask="cpf" variant="primary" />
+  <u-mask-field label="Secondary" mask="cpf" variant="secondary" />
+</template>
+
+<script lang="ts" setup>
+import { UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Labels, placeholders e mensagens
+
+As props `label`, `placeholder` e `hint` funcionam da mesma forma que nos [campos de texto](./text-field.md).
+
+Sem a prop `placeholder`, o campo exibe a própria máscara como placeholder, com `0` no lugar de cada `#` e os separadores fixos como na máscara: `000.000.000-00` para `cpf`, `00.000.000/0000-00` para `cnpj`, `00000-000` para `cep` e `Nº 0000` para `Nº ####`. Um `placeholder` informado substitui o padrão, e `placeholder=""` remove o placeholder. Como nos campos de texto, com um `label`, o placeholder só aparece quando o campo está em foco.
+
+```vue
+<template>
+  <u-mask-field label="CEP" mask="cep" hint="Somente os dígitos são salvos" />
+  <u-mask-field label="CPF" mask="cpf" placeholder="Somente números" />
+</template>
+
+<script lang="ts" setup>
+import { UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Validação
+
+Enquanto houver um valor sem que a máscara esteja completa (por exemplo, um CNPJ com menos de 14 caracteres), o campo exibe a mensagem "Valor incompleto", e um valor que não cabe na máscara (veja [Valor inicial](#valor-inicial)) exibe a mensagem "Valor inválido". A validação confere somente o formato, e não se o documento é válido. Com a prop `required`, o campo também impede o envio do [formulário](./form.md) enquanto estiver vazio, exibindo a mensagem "Campo obrigatório".
+
+```vue
+<template>
+  <u-form>
+    <u-mask-field label="CPF" mask="cpf" required />
+    <u-button type="submit">Enviar</u-button>
+  </u-form>
+</template>
+
+<script lang="ts" setup>
+import { UButton, UForm, UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Estados
+
+#### Desabilitado
+
+Utilize a prop `disabled` para indicar ao usuário que não há possibilidade de interação com o campo.
+
+```vue
+<template>
+  <u-mask-field model-value="12345678909" label="Desabilitado" mask="cpf" disabled />
+</template>
+
+<script lang="ts" setup>
+import { UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Somente leitura
+
+Utilize a prop `readonly` para evitar que o valor presente em um campo seja alterado.
+
+```vue
+<template>
+  <u-mask-field model-value="12345678909" label="Somente leitura" mask="cpf" readonly />
+</template>
+
+<script lang="ts" setup>
+import { UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Carregamento
+
+A prop `loading` exibe um indicador de carregamento no campo enquanto ativa. Nesse estado, o campo mantém o rótulo como nome acessível e fica marcado como ocupado, e leitores de tela ignoram o indicador.
+
+```vue
+<template>
+  <u-mask-field label="Carregando" mask="cpf" loading />
+</template>
+
+<script lang="ts" setup>
+import { UMaskField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Limpável
+
+A prop `clearable` exibe um recurso para limpar o campo, que altera o `v-model` para uma `string` vazia.
+
+```vue
+<template>
+  <u-mask-field v-model="cep" label="Limpável" mask="cep" clearable />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UMaskField } from "@nexdom/uimed-vue/components";
+
+const cep = ref("01310100");
+</script>
+```
+
+## Eventos
+
+### Atualização
+
+O evento `update:modelValue` será emitido toda vez que o valor do campo for alterado pelo usuário, repassando somente os caracteres do valor, sem os separadores e com as letras em maiúsculas, como uma `string`. Caracteres descartados e separadores digitados não emitem o evento.
+
+```vue
+<template>
+  <u-mask-field label="Celular" mask="phone" :model-value @update:model-value="onUpdateValue" />
+  <p>{{ changes }} alteração(ões): "{{ modelValue }}"</p>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UMaskField } from "@nexdom/uimed-vue/components";
+
+const modelValue = ref("1191234567");
+const changes = ref(0);
+
+function onUpdateValue(newValue: string) {
+  modelValue.value = newValue;
+  changes.value++;
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UMaskField](../../api/components/mask-field.md) para a lista completa de props e eventos.