@topjoao/top-design-system 0.1.9 → 0.2.11

package/README.md

@@ -1,37 +1,37 @@
 # TopSolutions Design System
 
 Biblioteca de componentes Vue 3, estilos e tokens visuais compartilhados pela
-TopSolutions.
-
-## Índice
-
-- [Instalação e configuração](#instalação)
-- [Tema e tokens](#tema-topsolutions)
-- [Integração com Nuxt e Vue 3](#uso-com-nuxt)
-- [Componentes](#componentes-publicos)
-- [Tipos e exports públicos](#tipos-e-exports-públicos)
-- [Desenvolvimento da biblioteca](#desenvolvimento-da-biblioteca)
-
-## Componentes públicos
-
-| Componente | Finalidade | `v-model` |
-|---|---|---|
-| `TopButton` | Botão com estilos e estados da marca. | — |
-| `TopConfirmDialog` | Confirmação modal controlada pela aplicação. | `boolean` |
-| `TopDatePicker` | Campo de data, múltiplas datas ou intervalo. | `Date`/array de `Date` |
-| `TopFileUpload` | Escolha, validação e prévia de arquivos; não faz upload. | `File`/`File[]`/`null` |
-| `TopInputText` | Campo textual com label, erro e acessibilidade. | `string` |
+TopSolutions.
+
+## Índice
+
+- [Instalação e configuração](#instalação)
+- [Tema e tokens](#tema-topsolutions)
+- [Integração com Nuxt e Vue 3](#uso-com-nuxt)
+- [Componentes](#componentes-publicos)
+- [Tipos e exports públicos](#tipos-e-exports-públicos)
+- [Desenvolvimento da biblioteca](#desenvolvimento-da-biblioteca)
+
+## Componentes públicos
+
+| Componente | Finalidade | `v-model` |
+|---|---|---|
+| `TopButton` | Botão com estilos e estados da marca. | — |
+| `TopConfirmDialog` | Confirmação modal controlada pela aplicação. | `boolean` |
+| `TopDatePicker` | Campo de data, múltiplas datas ou intervalo. | `Date`/array de `Date` |
+| `TopFileUpload` | Escolha, validação e prévia de arquivos; não faz upload. | `File`/`File[]`/`null` |
+| `TopInputText` | Campo textual com label, erro e acessibilidade. | `string` |
 | `TopTextArea` | Campo de texto multilinha com label, erro e altura configurável. | `string` |
-| `TopInputNumber` | Campo numérico localizado, com moeda, limites e incrementos. | `number \| null` |
-| `TopNavBar` | Navegação responsiva, breadcrumbs, favoritos e Drawer. | `searchValue` e `mobileOpen` opcionais |
-| `TopSelect` | Autocomplete pesquisável com paginação virtual. | opção/opções |
-| `TopTabs` | Abas com painéis nomeados. | `string \| number` |
-| `TopToast` | Renderizador de notificações do serviço Toast do PrimeVue. | — |
+| `TopInputNumber` | Campo numérico localizado, com moeda, limites e incrementos. | `number \| null` |
+| `TopNavBar` | Navegação responsiva, breadcrumbs, favoritos e Drawer. | `searchValue` e `mobileOpen` opcionais |
+| `TopSelect` | Autocomplete pesquisável com paginação virtual. | opção/opções |
+| `TopTabs` | Abas com painéis nomeados. | `string \| number` |
+| `TopToast` | Renderizador de notificações do serviço Toast do PrimeVue. | — |
 
 ## Instalação
 
 ```bash
-npm install @topjoao/top-design-system
+npm install @topjoao/top-design-system
 ```
 
 A aplicação consumidora deve possuir Vue 3, PrimeVue, PrimeIcons e
@@ -46,24 +46,24 @@ oficial da TopSolutions. Configure-o uma vez na aplicação consumidora:
 import PrimeVue from 'primevue/config'
 import { TopSolutionsPreset } from '@topjoao/top-design-system'
 
-app.use(PrimeVue, {
-  theme: {
-    preset: TopSolutionsPreset,
-    options: {
-      darkModeSelector: '.dark',
-      cssLayer: {
-        name: 'primevue',
-        order: 'primevue',
-      },
-    },
-  },
-})
-```
-
-A camada `primevue` mantém os estilos estruturais do tema abaixo dos padrões do
-Design System e das classes utilitárias da aplicação. Com isso, propriedades
-como `headerClass` e `contentClass` conseguem sobrescrever os valores padrão sem
-`!important`.
+app.use(PrimeVue, {
+  theme: {
+    preset: TopSolutionsPreset,
+    options: {
+      darkModeSelector: '.dark',
+      cssLayer: {
+        name: 'primevue',
+        order: 'primevue',
+      },
+    },
+  },
+})
+```
+
+A camada `primevue` mantém os estilos estruturais do tema abaixo dos padrões do
+Design System e das classes utilitárias da aplicação. Com isso, propriedades
+como `headerClass` e `contentClass` conseguem sobrescrever os valores padrão sem
+`!important`.
 
 Para ativar o modo escuro, adicione ou remova `.dark` uma única vez no elemento
 `<html>` da aplicação. Os componentes usam tokens semânticos de superfície, texto e
@@ -270,16 +270,16 @@ sendo explorado recebem destaque.
 | `showAia`, `showSupport` | `boolean` / `false` | Exibem as ações opcionais. |
 | `aiaActive` | `boolean` / `false` | Estado visual do botão Aia. |
 | `aiaLabel`, `supportLabel` | `string` | Textos acessíveis e rótulos do Drawer. |
-| `actions` | `TopNavAction[]` / `[]` | Ações genéricas, como integrações, emitidas por `action`. |
-| `client` | `TopNavClient` | Organização, cliente ou escopo ativo exibido no cabeçalho e como contexto do usuário no rodapé do Drawer; não cria ação nem seletor. |
-| `user` | `TopNavUser` | Dados exclusivamente visuais do usuário. |
+| `actions` | `TopNavAction[]` / `[]` | Ações genéricas, como integrações, emitidas por `action`. |
+| `client` | `TopNavClient` | Organização, cliente ou escopo ativo exibido no cabeçalho e como contexto do usuário no rodapé do Drawer; não cria ação nem seletor. |
+| `user` | `TopNavUser` | Dados exclusivamente visuais do usuário. |
 | `userMenuItems` | `TopNavUserMenuItem[]` | Opções emitidas por `user-action`; suporta separadores. |
 | `favoriteItems` | `TopNavItem[]` / `[]` | Favoritos fornecidos pelo pai para dropdown e Drawer. |
 | `showFavoriteToggle` | `boolean` / `false` | Exibe a estrela da página atual. |
 | `favoriteActive` | `boolean` / `false` | Estado visual da estrela atual. |
-| `mobileOpen` | `boolean` | Controle opcional com `v-model:mobile-open`. |
-| `appearance` | `TopNavBarAppearance` | Tokens visuais locais descritos abaixo. |
-| `spacing` | `TopNavBarSpacing` | Espaçamento do conteúdo no cabeçalho e breadcrumbs; preserva os padrões atuais quando omitido. |
+| `mobileOpen` | `boolean` | Controle opcional com `v-model:mobile-open`. |
+| `appearance` | `TopNavBarAppearance` | Tokens visuais locais descritos abaixo. |
+| `spacing` | `TopNavBarSpacing` | Espaçamento do conteúdo no cabeçalho e breadcrumbs; preserva os padrões atuais quando omitido. |
 
 ### Eventos
 
@@ -304,7 +304,7 @@ atalho abre primeiro o Drawer e foca a busca móvel. `Escape` fecha os painéis.
 | Slot | Uso |
 |---|---|
 | `brand` | Marca; recebe `{ compact }`. |
-| `context`, `scope` ou `client` | Contexto operacional; aliases com prioridade nessa ordem, recebem `{ client, compact }`. O slot `client` substitui a apresentação padrão da prop `client`. |
+| `context`, `scope` ou `client` | Contexto operacional; aliases com prioridade nessa ordem, recebem `{ client, compact }`. O slot `client` substitui a apresentação padrão da prop `client`. |
 | `context-compact` | Variante explícita usada no último estágio de overflow. |
 | `actions` | Conteúdo adicional do cabeçalho; recebe `{ compact, close }`. |
 | `aia-icon`, `support-icon` | Ícones customizados das ações quadradas. |
@@ -318,53 +318,53 @@ atalho abre primeiro o Drawer e foca a busca móvel. `Escape` fecha os painéis.
 | `drawer-actions` | Ações; recebe `{ actions, select, close }`. |
 | `drawer-before-menu`, `drawer-after-menu` | Conteúdo antes/depois do trilho rolável. |
 | `drawer-menu` | Substitui a árvore; recebe `{ sections, select, close }`. |
-| `drawer-user` | Rodapé de usuário; recebe `{ user, client, open, toggle }`. |
-| `drawer-footer` | Conteúdo final adicional; recebe `{ close }`. |
-
-### Faixa de favoritos
-
-No desktop, `favoriteItems` aparece primeiro em uma faixa horizontal abaixo dos
-breadcrumbs. A biblioteca mede uma cópia invisível da faixa com
-`ResizeObserver`: se a largura real não couber, ela é substituída pelo dropdown
-`Favoritos`. O mesmo dropdown é usado depois que a página passa de `120px` de
-scroll e a faixa retorna apenas ao chegar a `24px` ou menos. Os valores evitam
-oscilações perto do topo e reproduzem o comportamento do AppSidebar.
-
-### Aparência e responsividade
-
-Use `spacing` para criar uma zona segura horizontal sem limitar o fundo das
-duas faixas. Os valores são aplicados no elemento raiz como
-`--top-nav-header-padding` e `--top-nav-breadcrumb-padding`; o cabeçalho e o
-breadcrumb continuam ocupando toda a largura da viewport.
-Em telas móveis, esses valores também são usados, salvo se a aplicação já
-definir as variáveis específicas `--top-nav-header-padding-mobile` ou
-`--top-nav-breadcrumb-padding-mobile`.
-
-```vue
-<TopNavBar
-  :spacing="{
-    headerPadding: '0.625rem max(2rem, calc((100vw - 80rem) / 2 + 2rem))',
-    breadcrumbPadding: '0.25rem max(2rem, calc((100vw - 80rem) / 2 + 2rem))',
-  }"
-/>
-```
-
-`appearance` é propositalmente pequeno e semântico. Use `colors` para
-`navigation`, `text`, `mutedText`, `accent`, `border`, `menuText`,
-`mobileActiveText` e `favoritesText`; `surfaces` para `breadcrumb`, `drawer`,
-`drawerFooter`, `menu`, `menuHover`, `menuExplored`, `mobileActive`,
-`favorites` e `currentPage`; `borders` para `menu` (a borda externa de 6px),
-`menuOutline`, `mobileDivider`, `favorites` e `currentPage`; `shape` para
-`radius`, `drawerRadius`, `shadow` e `favoritesShadow`; e `focus` para
-`onDark` e `onLight`.
-
-```ts
-const appearance = {
-  colors: { navigation: '#09090b', text: '#f4f4f5', border: 'rgb(255 255 255 / 14%)' },
-  surfaces: { drawer: '#09090b', menu: '#18181b', menuHover: '#27272a' },
-  shape: { radius: '8px', shadow: '0 12px 30px rgb(0 0 0 / 25%)' },
-}
-```
+| `drawer-user` | Rodapé de usuário; recebe `{ user, client, open, toggle }`. |
+| `drawer-footer` | Conteúdo final adicional; recebe `{ close }`. |
+
+### Faixa de favoritos
+
+No desktop, `favoriteItems` aparece primeiro em uma faixa horizontal abaixo dos
+breadcrumbs. A biblioteca mede uma cópia invisível da faixa com
+`ResizeObserver`: se a largura real não couber, ela é substituída pelo dropdown
+`Favoritos`. O mesmo dropdown é usado depois que a página passa de `120px` de
+scroll e a faixa retorna apenas ao chegar a `24px` ou menos. Os valores evitam
+oscilações perto do topo e reproduzem o comportamento do AppSidebar.
+
+### Aparência e responsividade
+
+Use `spacing` para criar uma zona segura horizontal sem limitar o fundo das
+duas faixas. Os valores são aplicados no elemento raiz como
+`--top-nav-header-padding` e `--top-nav-breadcrumb-padding`; o cabeçalho e o
+breadcrumb continuam ocupando toda a largura da viewport.
+Em telas móveis, esses valores também são usados, salvo se a aplicação já
+definir as variáveis específicas `--top-nav-header-padding-mobile` ou
+`--top-nav-breadcrumb-padding-mobile`.
+
+```vue
+<TopNavBar
+  :spacing="{
+    headerPadding: '0.625rem max(2rem, calc((100vw - 80rem) / 2 + 2rem))',
+    breadcrumbPadding: '0.25rem max(2rem, calc((100vw - 80rem) / 2 + 2rem))',
+  }"
+/>
+```
+
+`appearance` é propositalmente pequeno e semântico. Use `colors` para
+`navigation`, `text`, `mutedText`, `accent`, `border`, `menuText`,
+`mobileActiveText` e `favoritesText`; `surfaces` para `breadcrumb`, `drawer`,
+`drawerFooter`, `menu`, `menuHover`, `menuExplored`, `mobileActive`,
+`favorites` e `currentPage`; `borders` para `menu` (a borda externa de 6px),
+`menuOutline`, `mobileDivider`, `favorites` e `currentPage`; `shape` para
+`radius`, `drawerRadius`, `shadow` e `favoritesShadow`; e `focus` para
+`onDark` e `onLight`.
+
+```ts
+const appearance = {
+  colors: { navigation: '#09090b', text: '#f4f4f5', border: 'rgb(255 255 255 / 14%)' },
+  surfaces: { drawer: '#09090b', menu: '#18181b', menuHover: '#27272a' },
+  shape: { radius: '8px', shadow: '0 12px 30px rgb(0 0 0 / 25%)' },
+}
+```
 
 A biblioteca não fixa tipografia inline. Por padrão, família, tamanho, peso e
 altura de linha são herdados da aplicação consumidora. Além disso, `appearance`
@@ -377,33 +377,33 @@ tema global pode controlar o componente sem precisar usar `!important`:
   --top-nav-font-family: var(--app-font-family);
   --top-nav-font-size: var(--app-font-size);
   --top-nav-strong-font-weight: 600;
-  --top-nav-action-size: 2.5rem;
-  --top-nav-header-padding: 0.625rem 1.5rem;
-  --top-nav-breadcrumb-padding: 0.25rem 1.5rem;
-  --top-nav-menu-item-padding: 0.5rem 0.75rem;
+  --top-nav-action-size: 2.5rem;
+  --top-nav-header-padding: 0.625rem 1.5rem;
+  --top-nav-breadcrumb-padding: 0.25rem 1.5rem;
+  --top-nav-menu-item-padding: 0.5rem 0.75rem;
   --top-nav-section-width: 16rem;
   --top-nav-column-width: 18rem;
   --top-nav-mobile-active-bg: #fff;
-  --top-nav-mobile-active-fg: #025a84;
-  --top-nav-mobile-divider: rgb(255 255 255 / 20%);
-  --top-nav-mobile-item-gap: 0.25rem;
-  --top-nav-mobile-submenu-padding: 0.5rem 0 0.375rem 0.35rem;
-  --top-nav-favorites-bg: #f8fafc;
-  --top-nav-favorites-fg: #0f172a;
-  --top-nav-favorites-border: #e2e8f0;
-  --top-nav-favorites-shadow: 0 1px 2px rgb(15 23 42 / 6%);
-  --top-nav-focus-ring: #dbeafe;
-  --top-nav-focus-ring-light: #1d4ed8;
-  --top-nav-current-bg: rgb(255 255 255 / 10%);
-  --top-nav-current-border: rgb(255 255 255 / 15%);
-  --top-nav-menu-scrollbar-thumb: #94a3b8;
-}
+  --top-nav-mobile-active-fg: #025a84;
+  --top-nav-mobile-divider: rgb(255 255 255 / 20%);
+  --top-nav-mobile-item-gap: 0.25rem;
+  --top-nav-mobile-submenu-padding: 0.5rem 0 0.375rem 0.35rem;
+  --top-nav-favorites-bg: #f8fafc;
+  --top-nav-favorites-fg: #0f172a;
+  --top-nav-favorites-border: #e2e8f0;
+  --top-nav-favorites-shadow: 0 1px 2px rgb(15 23 42 / 6%);
+  --top-nav-focus-ring: #dbeafe;
+  --top-nav-focus-ring-light: #1d4ed8;
+  --top-nav-current-bg: rgb(255 255 255 / 10%);
+  --top-nav-current-border: rgb(255 255 255 / 15%);
+  --top-nav-menu-scrollbar-thumb: #94a3b8;
+}
 ```
 
-As variáveis globais também alcançam o Drawer teleportado. Use-as para ajustes
-estruturais — tipografia, larguras, alturas, padding e espaçamentos do menu —
-em vez de props no componente. Um valor passado por `appearance` tem precedência
-local e não altera os demais tokens do tema.
+As variáveis globais também alcançam o Drawer teleportado. Use-as para ajustes
+estruturais — tipografia, larguras, alturas, padding e espaçamentos do menu —
+em vez de props no componente. Um valor passado por `appearance` tem precedência
+local e não altera os demais tokens do tema.
 
 O breakpoint móvel é `1024px`. No desktop, um `ResizeObserver` reaplica a mesma
 sequência progressiva do AppSidebar: ações colapsam abaixo de `1440px`, busca
@@ -412,15 +412,15 @@ conteúdo ainda transbordar, o contexto recebe `compact: true`. O último estág
 também limita o contêiner do contexto a `3.25rem`; use `context-compact` quando
 quiser controlar exatamente o que permanece visível.
 
-Abaixo de `1024px`, a navegação desktop desaparece e o Drawer do PrimeVue assume.
-Ele mantém cabeçalho, busca, ações, trilho translúcido rolável, árvore recursiva,
-favoritos e usuário. No rodapé, a foto e o nome do usuário formam a primeira
-linha; o cliente atual aparece abaixo e o subtítulo do cliente recebe uma
-etiqueta quando houver. A transição `menu-expand` existe somente dentro do Drawer;
-os dropdowns desktop abrem sem animação e suas áreas de hover incluem o espaço
-entre gatilho e painel. Nessa largura, os breadcrumbs deixam de rolar
-horizontalmente: eles quebram em linhas e o bloco da página atual ocupa sua
-própria linha para permanecer legível.
+Abaixo de `1024px`, a navegação desktop desaparece e o Drawer do PrimeVue assume.
+Ele mantém cabeçalho, busca, ações, trilho translúcido rolável, árvore recursiva,
+favoritos e usuário. No rodapé, a foto e o nome do usuário formam a primeira
+linha; o cliente atual aparece abaixo e o subtítulo do cliente recebe uma
+etiqueta quando houver. A transição `menu-expand` existe somente dentro do Drawer;
+os dropdowns desktop abrem sem animação e suas áreas de hover incluem o espaço
+entre gatilho e painel. Nessa largura, os breadcrumbs deixam de rolar
+horizontalmente: eles quebram em linhas e o bloco da página atual ocupa sua
+própria linha para permanecer legível.
 
 ## TopButton
 
@@ -442,8 +442,8 @@ Exemplo
 
 | Prop | Tipo | Padrão |
 |---|---|---|
-| `tooltip` | `string` | `''` |
-| `tooltipClass` | `string` | `'text-xs'` |
+| `tooltip` | `string` | `''` |
+| `tooltipClass` | `string` | `'text-xs'` |
 | `label` | `string` | `''` |
 | `icon` | `string` | `''` |
 | `loading` | `boolean` | `false` |
@@ -455,43 +455,43 @@ Exemplo
 | `unstyled` | `boolean` | `false` |
 | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` |
 
-O componente emite `click` sem payload. O slot nomeado `icon` não recebe
-parâmetros e substitui a prop `icon` — útil para SVGs, `HugeiconsIcon` ou um
-ícone com estado próprio. `secondary` permanece como atalho compatível para
-`severity="secondary"` e tem precedência sobre `severity`.
-
-O botão clicável interno expõe a classe estável `top-button__control`, que pode
-ser usada para customizar globalmente qualquer característica dos `TopButton`,
-como tipografia, cores, espaçamento, dimensões e bordas. Defina a regra no CSS
-global da aplicação, carregado depois do CSS do Design System:
-
-```css
-.top-button__control {
-  font-size: 0.875rem;
-  font-weight: 600;
-  min-height: 44px;
-  padding: 0.75rem 1rem;
-  border-radius: 0.5rem;
-}
-```
-
-Em um projeto com Tailwind, a mesma regra pode usar `@apply`:
-
-```css
-@layer components {
-  .top-button__control {
-    @apply min-h-11 rounded-lg px-4 py-3 text-sm font-semibold;
-  }
-}
-```
-
-A classe `top-button__control` atua no botão clicável, enquanto `top-button`
-atua no elemento externo que o envolve. A prop `class` continua disponível para
-customizar somente uma ocorrência. Algumas regras internas que usam
-`!important` podem exigir maior especificidade ou `!important` para serem
-sobrescritas.
-
-## TopConfirmDialog
+O componente emite `click` sem payload. O slot nomeado `icon` não recebe
+parâmetros e substitui a prop `icon` — útil para SVGs, `HugeiconsIcon` ou um
+ícone com estado próprio. `secondary` permanece como atalho compatível para
+`severity="secondary"` e tem precedência sobre `severity`.
+
+O botão clicável interno expõe a classe estável `top-button__control`, que pode
+ser usada para customizar globalmente qualquer característica dos `TopButton`,
+como tipografia, cores, espaçamento, dimensões e bordas. Defina a regra no CSS
+global da aplicação, carregado depois do CSS do Design System:
+
+```css
+.top-button__control {
+  font-size: 0.875rem;
+  font-weight: 600;
+  min-height: 44px;
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+}
+```
+
+Em um projeto com Tailwind, a mesma regra pode usar `@apply`:
+
+```css
+@layer components {
+  .top-button__control {
+    @apply min-h-11 rounded-lg px-4 py-3 text-sm font-semibold;
+  }
+}
+```
+
+A classe `top-button__control` atua no botão clicável, enquanto `top-button`
+atua no elemento externo que o envolve. A prop `class` continua disponível para
+customizar somente uma ocorrência. Algumas regras internas que usam
+`!important` podem exigir maior especificidade ou `!important` para serem
+sobrescritas.
+
+## TopConfirmDialog
 
 Diálogo de confirmação baseado no `Dialog` do PrimeVue e nos botões do Design
 System. A visibilidade é controlada por `v-model`; a aplicação consumidora
@@ -589,16 +589,16 @@ const dataNascimento = ref<Date | null>(null)
 | `showButtonBar` | `boolean` | `false` |
 | `appendTo` | `'body' \| 'self' \| HTMLElement` | `'body'` |
 
-Eventos: `update:modelValue`, `input`, `change`, `date-select`, `show`, `hide`,
-`today-click`, `clear-click`, `month-change`, `year-change`, `focus`, `blur` e
-`keydown`. Os slots do `DatePicker` do PrimeVue são repassados pelo wrapper,
-incluindo `date`, `header`, `footer`, `buttonbar`, `inputicon`, `dropdownicon`,
-`previcon` e `nexticon`.
-
-O slot `date` recebe as props de dia disponibilizadas pelo `DatePicker`; os
-slots de ícone recebem as props correspondentes do PrimeVue. Os slots `header`,
-`footer` e `buttonbar` permitem substituir essas regiões. Todos são apenas
-repassados: o wrapper preserva as props e o comportamento do componente-base.
+Eventos: `update:modelValue`, `input`, `change`, `date-select`, `show`, `hide`,
+`today-click`, `clear-click`, `month-change`, `year-change`, `focus`, `blur` e
+`keydown`. Os slots do `DatePicker` do PrimeVue são repassados pelo wrapper,
+incluindo `date`, `header`, `footer`, `buttonbar`, `inputicon`, `dropdownicon`,
+`previcon` e `nexticon`.
+
+O slot `date` recebe as props de dia disponibilizadas pelo `DatePicker`; os
+slots de ícone recebem as props correspondentes do PrimeVue. Os slots `header`,
+`footer` e `buttonbar` permitem substituir essas regiões. Todos são apenas
+repassados: o wrapper preserva as props e o comportamento do componente-base.
 
 `required` adiciona o atributo nativo e o asterisco visual; a validação continua
 sob responsabilidade da aplicação. `error` ativa o estado inválido, associa a
@@ -654,123 +654,123 @@ function enviarArquivos(files: File[]) {
 | `removeLabel` | `string` | `'Remover'` |
 | `loading` | `boolean` | `false` |
 
-Eventos: `update:modelValue`, `select`, `change`, `remove`, `clear` e `error`.
-Erros de tipo, tamanho e quantidade possuem `code`, `message` e o `file`
-relacionado. Os slots `empty` e `preview` permitem customizar a área vazia e a
-pré-visualização. Os métodos `choose()` e `clear()` ficam disponíveis pela ref
-do componente.
-
-| Slot | Parâmetros recebidos | Uso |
-|---|---|---|
-| `empty` | `{ choose, disabled }` | Substitui a área vazia. Chame `choose()` para abrir o seletor nativo. |
-| `preview` | `{ file, index, url }` | Substitui a miniatura. `url` é uma object URL apenas para imagens; nos demais casos, é `''`. |
-
-```vue
-<TopFileUpload ref="upload" v-model="anexos" multiple>
-  <template #empty="{ choose, disabled }">
-    <button type="button" :disabled="disabled" @click="choose()">Anexar documentos</button>
-  </template>
-  <template #preview="{ file, url }">
-    <img v-if="url" :src="url" :alt="file.name">
-    <span v-else>{{ file.name }}</span>
-  </template>
-</TopFileUpload>
-```
-
-`accept` aceita extensões (`.pdf`), MIME types (`application/pdf`) e curingas
-MIME (`image/*`), separados por vírgula. `maxFileSize` é contado em bytes. Em
-modo simples, a última seleção válida substitui a anterior; com `multiple`,
-arquivos válidos são acumulados sem duplicar nome, tipo e tamanho.
-
-## TopInputNumber
-
-Campo numérico baseado no `InputNumber` do PrimeVue, com a mesma estrutura de
-label, erro e acessibilidade dos demais campos. Por padrão usa `pt-BR`. No modo
-`decimal`, o usuário informa explicitamente o separador decimal; no modo
-`currency`, a máscara de centavos vem habilitada e transforma `12345` em
-`R$ 123,45`. O `v-model` permanece sempre numérico (`number`) ou `null` quando
-vazio.
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { TopInputNumber } from '@topjoao/top-design-system'
-
-const quantidade = ref<number | null>(null)
-const valorUnitario = ref<number | null>(null)
-</script>
-
-<template>
-  <TopInputNumber
-    v-model="quantidade"
-    label="Quantidade"
-    :min="1"
-    :min-fraction-digits="2"
-    :max-fraction-digits="4"
-    required
-  />
-
-  <TopInputNumber
-    v-model="valorUnitario"
-    label="Valor unitário"
-    mode="currency"
-    currency="BRL"
-    :min-fraction-digits="2"
-    :max-fraction-digits="2"
-  />
-</template>
-```
-
-| Prop | Tipo | Padrão | Finalidade |
-|---|---|---|---|
-| `modelValue` | `number \| null` | `null` | Valor numérico controlado. |
-| `label` / `placeholder` | `string` | `''` / `''` | Rótulo e texto auxiliar do campo. |
-| `required` | `boolean` | `false` | Asterisco visual e atributo nativo obrigatório. |
-| `error` | `string` | `''` | Mensagem e estado inválido. |
-| `invalid` | `boolean` | `false` | Força estado inválido sem mostrar mensagem. |
-| `disabled` / `readonly` | `boolean` | `false` / `false` | Remove interação / preserva leitura sem desabilitar. |
-| `locale` | `string` | `'pt-BR'` | Locale para separadores e moeda. |
-| `mode` | `'decimal' \| 'currency'` | `'decimal'` | Formatação decimal ou monetária. |
-| `currency` / `currencyDisplay` | `string` / `'symbol' \| 'code' \| 'name'` | `undefined` / `'symbol'` | Código ISO 4217 e modo de exibição da moeda. |
-| `currencyInputMode` | `'decimal' \| 'cents'` | `'cents'` | Controla a entrada monetária; `decimal` desliga a máscara mesmo quando `cents` é `true`. Não afeta `mode="decimal"`. |
-| `cents` | `boolean` | `true` | Habilita a máscara automática somente em `mode="currency"`; `false` usa o `InputNumber` padrão. |
-| `centsFractionDigits` | `number` | `undefined` (efetivo: `2`) | Primeira opção para definir as casas da máscara monetária. |
-| `currencyFractionDigits` | `number` | `undefined` | Fallback de casas da máscara, usado depois de `centsFractionDigits`. |
-| `useGrouping` / `format` | `boolean` | `true` / `true` | Separadores de milhar e formatação do valor. |
-| `minFractionDigits` / `maxFractionDigits` | `number` | `undefined` | Precisão do PrimeVue. Sem `maxFractionDigits`, o modo decimal aceita até 20 casas; a máscara monetária usa esse valor como último fallback antes de `2`. |
-| `min` / `max` / `step` | `number` | `undefined` / `undefined` / `1` | Limites e passo dos botões/teclado. |
-| `showButtons` / `buttonLayout` | `boolean` / `'stacked' \| 'horizontal' \| 'vertical'` | `false` / `'stacked'` | Exibe e organiza os controles de incremento. |
-| `allowEmpty` / `showClear` / `highlightOnFocus` | `boolean` | `true` / `false` / `false` | Permite limpar, mostra ícone de limpeza e seleciona valor ao focar. |
-
-Eventos: `update:modelValue` (`number | null`), `input`, `focus` e `blur`. No
-fluxo padrão do `InputNumber`, o componente também repassa `value-change`.
-Atributos adicionais, como `name`, `autocomplete`, `aria-*` e `data-*`, são
-repassados ao controle interno.
-
-Quando a máscara de centavos não está ativa, os slots do `InputNumber` também
-são repassados: `incrementbutton` e
-`decrementbutton` recebem `{ listeners }`; `incrementicon` e `decrementicon`
-substituem os ícones; `clearicon` recebe `{ clearCallback }`.
-
-Para reproduzir a digitação monetária do TopLicita, a máscara de centavos já
-vem ativa em `mode="currency"`. O usuário digita somente dígitos: `12345`
-resulta em `R$ 123,45` e o `v-model` recebe `123.45`. Para exigir a vírgula
-decimal digitada pelo usuário, passe `:cents="false"` ou
-`currency-input-mode="decimal"`.
-Como a máscara controla o texto enquanto o usuário digita, nesse modo os
-botões incrementais, o ícone de limpeza e seus slots do `InputNumber` não são
-renderizados.
-
-```vue
-<TopInputNumber
-  v-model="valorUnitario"
-  label="Valor unitário"
-  mode="currency"
-  currency="BRL"
-/>
-```
-
-## TopInputText
+Eventos: `update:modelValue`, `select`, `change`, `remove`, `clear` e `error`.
+Erros de tipo, tamanho e quantidade possuem `code`, `message` e o `file`
+relacionado. Os slots `empty` e `preview` permitem customizar a área vazia e a
+pré-visualização. Os métodos `choose()` e `clear()` ficam disponíveis pela ref
+do componente.
+
+| Slot | Parâmetros recebidos | Uso |
+|---|---|---|
+| `empty` | `{ choose, disabled }` | Substitui a área vazia. Chame `choose()` para abrir o seletor nativo. |
+| `preview` | `{ file, index, url }` | Substitui a miniatura. `url` é uma object URL apenas para imagens; nos demais casos, é `''`. |
+
+```vue
+<TopFileUpload ref="upload" v-model="anexos" multiple>
+  <template #empty="{ choose, disabled }">
+    <button type="button" :disabled="disabled" @click="choose()">Anexar documentos</button>
+  </template>
+  <template #preview="{ file, url }">
+    <img v-if="url" :src="url" :alt="file.name">
+    <span v-else>{{ file.name }}</span>
+  </template>
+</TopFileUpload>
+```
+
+`accept` aceita extensões (`.pdf`), MIME types (`application/pdf`) e curingas
+MIME (`image/*`), separados por vírgula. `maxFileSize` é contado em bytes. Em
+modo simples, a última seleção válida substitui a anterior; com `multiple`,
+arquivos válidos são acumulados sem duplicar nome, tipo e tamanho.
+
+## TopInputNumber
+
+Campo numérico baseado no `InputNumber` do PrimeVue, com a mesma estrutura de
+label, erro e acessibilidade dos demais campos. Por padrão usa `pt-BR`. No modo
+`decimal`, o usuário informa explicitamente o separador decimal; no modo
+`currency`, a máscara de centavos vem habilitada e transforma `12345` em
+`R$ 123,45`. O `v-model` permanece sempre numérico (`number`) ou `null` quando
+vazio.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopInputNumber } from '@topjoao/top-design-system'
+
+const quantidade = ref<number | null>(null)
+const valorUnitario = ref<number | null>(null)
+</script>
+
+<template>
+  <TopInputNumber
+    v-model="quantidade"
+    label="Quantidade"
+    :min="1"
+    :min-fraction-digits="2"
+    :max-fraction-digits="4"
+    required
+  />
+
+  <TopInputNumber
+    v-model="valorUnitario"
+    label="Valor unitário"
+    mode="currency"
+    currency="BRL"
+    :min-fraction-digits="2"
+    :max-fraction-digits="2"
+  />
+</template>
+```
+
+| Prop | Tipo | Padrão | Finalidade |
+|---|---|---|---|
+| `modelValue` | `number \| null` | `null` | Valor numérico controlado. |
+| `label` / `placeholder` | `string` | `''` / `''` | Rótulo e texto auxiliar do campo. |
+| `required` | `boolean` | `false` | Asterisco visual e atributo nativo obrigatório. |
+| `error` | `string` | `''` | Mensagem e estado inválido. |
+| `invalid` | `boolean` | `false` | Força estado inválido sem mostrar mensagem. |
+| `disabled` / `readonly` | `boolean` | `false` / `false` | Remove interação / preserva leitura sem desabilitar. |
+| `locale` | `string` | `'pt-BR'` | Locale para separadores e moeda. |
+| `mode` | `'decimal' \| 'currency'` | `'decimal'` | Formatação decimal ou monetária. |
+| `currency` / `currencyDisplay` | `string` / `'symbol' \| 'code' \| 'name'` | `undefined` / `'symbol'` | Código ISO 4217 e modo de exibição da moeda. |
+| `currencyInputMode` | `'decimal' \| 'cents'` | `'cents'` | Controla a entrada monetária; `decimal` desliga a máscara mesmo quando `cents` é `true`. Não afeta `mode="decimal"`. |
+| `cents` | `boolean` | `true` | Habilita a máscara automática somente em `mode="currency"`; `false` usa o `InputNumber` padrão. |
+| `centsFractionDigits` | `number` | `undefined` (efetivo: `2`) | Primeira opção para definir as casas da máscara monetária. |
+| `currencyFractionDigits` | `number` | `undefined` | Fallback de casas da máscara, usado depois de `centsFractionDigits`. |
+| `useGrouping` / `format` | `boolean` | `true` / `true` | Separadores de milhar e formatação do valor. |
+| `minFractionDigits` / `maxFractionDigits` | `number` | `undefined` | Precisão do PrimeVue. Sem `maxFractionDigits`, o modo decimal aceita até 20 casas; a máscara monetária usa esse valor como último fallback antes de `2`. |
+| `min` / `max` / `step` | `number` | `undefined` / `undefined` / `1` | Limites e passo dos botões/teclado. |
+| `showButtons` / `buttonLayout` | `boolean` / `'stacked' \| 'horizontal' \| 'vertical'` | `false` / `'stacked'` | Exibe e organiza os controles de incremento. |
+| `allowEmpty` / `showClear` / `highlightOnFocus` | `boolean` | `true` / `false` / `false` | Permite limpar, mostra ícone de limpeza e seleciona valor ao focar. |
+
+Eventos: `update:modelValue` (`number | null`), `input`, `focus` e `blur`. No
+fluxo padrão do `InputNumber`, o componente também repassa `value-change`.
+Atributos adicionais, como `name`, `autocomplete`, `aria-*` e `data-*`, são
+repassados ao controle interno.
+
+Quando a máscara de centavos não está ativa, os slots do `InputNumber` também
+são repassados: `incrementbutton` e
+`decrementbutton` recebem `{ listeners }`; `incrementicon` e `decrementicon`
+substituem os ícones; `clearicon` recebe `{ clearCallback }`.
+
+Para reproduzir a digitação monetária do TopLicita, a máscara de centavos já
+vem ativa em `mode="currency"`. O usuário digita somente dígitos: `12345`
+resulta em `R$ 123,45` e o `v-model` recebe `123.45`. Para exigir a vírgula
+decimal digitada pelo usuário, passe `:cents="false"` ou
+`currency-input-mode="decimal"`.
+Como a máscara controla o texto enquanto o usuário digita, nesse modo os
+botões incrementais, o ícone de limpeza e seus slots do `InputNumber` não são
+renderizados.
+
+```vue
+<TopInputNumber
+  v-model="valorUnitario"
+  label="Valor unitário"
+  mode="currency"
+  currency="BRL"
+/>
+```
+
+## TopInputText
 
 Campo textual baseado no `InputText` do PrimeVue. O `v-model` é sempre
 `string`, inclusive para códigos, documentos e identificadores compostos
@@ -800,6 +800,7 @@ const codigo = ref('001234')
 | Prop | Tipo | Padrão |
 |---|---|---|
 | `modelValue` | `string` | `''` |
+| `type` | `string` | `'text'` |
 | `label` | `string` | `''` |
 | `placeholder` | `string` | `''` |
 | `required` | `boolean` | `false` |
@@ -810,6 +811,7 @@ const codigo = ref('001234')
 Atributos e eventos nativos adicionais, como `name`, `maxlength`,
 `autocomplete`, `inputmode`, `pattern`, `aria-*`, `data-*`, `focus` e `blur`,
 são repassados ao elemento `input` interno.
+Use `type="email"` ou `type="password"` para os respectivos campos.
 
 ## TopTextArea
 
@@ -834,7 +836,8 @@ const descricao = ref('')
     label="Descrição"
     placeholder="Descreva o item"
     :rows="5"
-    maxlength="500"
+    :max-length="500"
+    show-counter
     required
   />
 </template>
@@ -851,6 +854,14 @@ const descricao = ref('')
 | `readonly` | `boolean` | `false` |
 | `rows` | `number` | `4` |
 | `autoResize` | `boolean` | `false` |
+| `maxLength` | `number` | `undefined` (sem limite) |
+| `showCounter` | `boolean` | `false` |
+
+`maxLength` define o limite nativo de caracteres para digitação e colagem.
+`showCounter` exibe a contagem abaixo do campo, alinhada à direita, no formato
+`12 / 500 caracteres`. Sem limite configurado, mostra apenas `12 caracteres`.
+O contador acompanha o `v-model`; ocultá-lo não remove o limite. Valores atribuídos
+diretamente ao `v-model` não são truncados pelo limite nativo do navegador.
 
 Atributos e eventos nativos adicionais, como `name`, `maxlength`, `aria-*`,
 `data-*`, `focus` e `blur`, são repassados ao elemento `textarea` interno.
@@ -896,43 +907,43 @@ function searchCustomers({ query }: { query: string }) {
 </template>
 ```
 
-| Prop | Tipo | Padrão |
-|---|---|---|
-| `modelValue` | `SelectOption \| SelectOption[] \| null` | `null` |
-| `options` | `array` | `[]` |
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `SelectOption \| SelectOption[] \| null` | `null` |
+| `options` | `array` | `[]` |
 | `optionLabel` | `string \| function` | `'label'` |
 | `optionKey` | `string` | `'id'` |
 | `optionPrefix` | `string` | `''` |
 | `showOptionPrefix` | `boolean` | `false` |
 | `showSelectedPrefix` | `boolean` | `false` |
 | `loading` / `disabled` / `invalid` | `boolean` | `false` |
-| `placeholder` | `string` | `'Pesquisar...'` |
+| `placeholder` | `string` | `'Pesquisar...'` |
 | `minQueryLength` | `number` | `1` |
 | `multiple` / `forceSelection` | `boolean` | `false` / `true` |
 | `panelWidth` / `scrollHeight` | `string` | `null` / `'250px'` |
-| `emptyMessage` / `loadingMessage` | `string` | `'Nenhum resultado encontrado.'` / `'Carregando...'` |
+| `emptyMessage` / `loadingMessage` | `string` | `'Nenhum resultado encontrado.'` / `'Carregando...'` |
 | `closeOnSelect` | `boolean` | `false` |
 
 Eventos: `update:modelValue`, `search`, `loadMore`, `clear`, `select` e
 `change`.
 
-Slots: `icon`, `option`, `selected-item`, `chip`, `empty`, `option-group` e
-`footer`. O slot `icon` recebe `loading`; sem ele, o componente mostra uma lupa
-ou um indicador de carregamento. Quando um slot não é informado, o componente usa sua apresentação padrão.
-O texto das opções é limitado visualmente pela largura disponível do painel,
-sem corte por quantidade fixa de caracteres; o tooltip padrão exibe o valor
-completo quando `showTooltip` está ativo.
-
-| Slot | Parâmetros recebidos | Uso |
-|---|---|---|
-| `icon` | `{ loading }` | Ícone à esquerda do campo. |
-| `option` | Props nativas, mais `{ option, label, prefix, query }` | Linha de uma opção. |
-| `selected-item` | Props nativas, incluindo `item` | Valor único escolhido. |
-| `chip` | Props nativas, incluindo `value` e `removeCallback` | Tag no modo múltiplo. |
-| `empty` | — | Conteúdo quando não há opções; também substitui o loading padrão. |
-| `option-group` | Props nativas, incluindo `option` | Cabeçalho de um grupo. |
-| `footer` | Props nativas do AutoComplete | Rodapé do painel. |
-
+Slots: `icon`, `option`, `selected-item`, `chip`, `empty`, `option-group` e
+`footer`. O slot `icon` recebe `loading`; sem ele, o componente mostra uma lupa
+ou um indicador de carregamento. Quando um slot não é informado, o componente usa sua apresentação padrão.
+O texto das opções é limitado visualmente pela largura disponível do painel,
+sem corte por quantidade fixa de caracteres; o tooltip padrão exibe o valor
+completo quando `showTooltip` está ativo.
+
+| Slot | Parâmetros recebidos | Uso |
+|---|---|---|
+| `icon` | `{ loading }` | Ícone à esquerda do campo. |
+| `option` | Props nativas, mais `{ option, label, prefix, query }` | Linha de uma opção. |
+| `selected-item` | Props nativas, incluindo `item` | Valor único escolhido. |
+| `chip` | Props nativas, incluindo `value` e `removeCallback` | Tag no modo múltiplo. |
+| `empty` | — | Conteúdo quando não há opções; também substitui o loading padrão. |
+| `option-group` | Props nativas, incluindo `option` | Cabeçalho de um grupo. |
+| `footer` | Props nativas do AutoComplete | Rodapé do painel. |
+
 `search` recebe `{ originalEvent, query }` nas consultas digitadas e quando o
 botão abre o dropdown sem opções carregadas; se já houver opções, a abertura
 pelo botão reutiliza essa lista. Atualize `options` com os resultados.
@@ -989,111 +1000,111 @@ const tabs: TopTabItem[] = [
 Cada `TopTabItem` possui `value`, `label` e `disabled?`. O `value` deve ser
 único e identifica tanto a seleção quanto o slot do painel; por exemplo,
 `value: 'documentos'` utiliza `#documentos`. Cada slot recebe `tab` e `active`.
-O componente emite somente `update:modelValue`. Atributos adicionais, incluindo
-as opções de passthrough do PrimeVue, são repassados ao componente `Tabs`.
-
-## TopToast
-
-`TopToast` personaliza o renderizador do serviço `Toast` do PrimeVue. Registre
-`ToastService` uma vez, renderize um único `TopToast` perto da raiz e dispare
-mensagens com `useToast`. Ele não recebe uma lista de mensagens por prop.
-
-```ts
-// main.ts
-import PrimeVue from 'primevue/config'
-import ToastService from 'primevue/toastservice'
-import { createApp } from 'vue'
-import App from './App.vue'
-
-createApp(App).use(PrimeVue).use(ToastService).mount('#app')
-```
-
-```vue
-<script setup lang="ts">
-import { useToast } from 'primevue/usetoast'
-import { TopButton, TopToast } from '@topjoao/top-design-system'
-
-const toast = useToast()
-const abrirCadastro = () => { /* navegue para o cadastro */ }
-
-function salvar() {
-  toast.add({
-    severity: 'success', summary: 'Cadastro concluído', detail: 'As alterações foram salvas.', life: 5000,
-    data: {
-      footer: 'Protocolo: CAD-2026-0042',
-      action: { label: 'Ver cadastro', icon: 'pi pi-arrow-right', onClick: () => abrirCadastro() },
-    },
-  })
-}
-</script>
-
-<template>
-  <TopToast :base-z-index="30000" />
-  <TopButton label="Salvar" @click="salvar" />
-</template>
-```
-
-| Prop | Tipo | Padrão | Finalidade |
-|---|---|---|---|
-| `baseZIndex` | `number` | `30000` | Camada base das notificações. |
-
-Além das opções usuais de `ToastMessageOptions` do PrimeVue (`severity`,
-`summary`, `detail`, `life`, `closable` etc.), `data` aceita `TopToastData`:
-
-| Campo | Tipo | Efeito |
-|---|---|---|
-| `data.footer` | `string \| number` | Texto discreto abaixo da mensagem. |
-| `data.action.label` | `string` | Rótulo da ação. |
-| `data.action.icon` | `string` opcional | Classe de ícone PrimeIcons. |
-| `data.action.onClick` | `() => void` opcional | Função chamada ao clicar na ação. |
-
-| Slot | Parâmetros recebidos | Uso |
-|---|---|---|
-| `action` | `{ action, message, run }` | Substitui o botão; execute `run()` para chamar `action.onClick`. |
-| `footer` | `{ message, footer }` | Substitui o rodapé. |
-
-## Tipos e exports públicos
-
-O pacote raiz exporta todos os componentes, `TopSolutionsPreset`, `colors` e
-os tipos abaixo. Use `import type` para não acrescentar código ao bundle.
-
-```ts
-import {
-  colors,
-  TopSolutionsPreset,
-  type TopButtonSeverity,
-  type TopDatePickerSelectionMode,
-  type TopDatePickerValue,
-  type TopFileUploadError,
-  type TopFileUploadValue,
-  type TopInputNumberValue,
-  type TopInputNumberMode,
-  type TopInputNumberButtonLayout,
-  type TopInputNumberCurrencyInputMode,
-  type TopNavItem,
-  type TopNavSection,
-  type TopTabItem,
-  type TopToastData,
-} from '@topjoao/top-design-system'
-```
-
-`TopNavItem` descreve um nó (`id`, `label`, `to?`, `icon?`, `disabled?`,
-`children?`, `data?`); `TopNavSection` é o mesmo contrato com `children`
-obrigatório. `TopNavAction`, `TopNavUser`, `TopNavClient` e
-`TopNavUserMenuItem` correspondem às props de mesmo nome. A aparência da barra
-é definida por `TopNavBarAppearance` e seus subtipos exportados:
-`TopNavBarColors`, `TopNavBarSurfaces`, `TopNavBarBorders`, `TopNavBarShape` e
-`TopNavBarFocus`. `TopNavBarSpacing` tipa as propriedades opcionais
-`headerPadding` e `breadcrumbPadding` da prop `spacing`.
-
-`TopInputNumberValue`, `TopInputNumberMode`, `TopInputNumberButtonLayout` e
-`TopInputNumberCurrencyInputMode`
-tipam, respectivamente, o valor, o modo de formatação, o layout dos botões e o
-modo de entrada monetária do campo numérico. `colors` expõe as escalas
-imutáveis `primary`, `secondary`, `success`, `warn` e
-`danger`, cada uma com tons de `50` a `950`.
-
-## Desenvolvimento da biblioteca
+O componente emite somente `update:modelValue`. Atributos adicionais, incluindo
+as opções de passthrough do PrimeVue, são repassados ao componente `Tabs`.
+
+## TopToast
+
+`TopToast` personaliza o renderizador do serviço `Toast` do PrimeVue. Registre
+`ToastService` uma vez, renderize um único `TopToast` perto da raiz e dispare
+mensagens com `useToast`. Ele não recebe uma lista de mensagens por prop.
+
+```ts
+// main.ts
+import PrimeVue from 'primevue/config'
+import ToastService from 'primevue/toastservice'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).use(PrimeVue).use(ToastService).mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import { useToast } from 'primevue/usetoast'
+import { TopButton, TopToast } from '@topjoao/top-design-system'
+
+const toast = useToast()
+const abrirCadastro = () => { /* navegue para o cadastro */ }
+
+function salvar() {
+  toast.add({
+    severity: 'success', summary: 'Cadastro concluído', detail: 'As alterações foram salvas.', life: 5000,
+    data: {
+      footer: 'Protocolo: CAD-2026-0042',
+      action: { label: 'Ver cadastro', icon: 'pi pi-arrow-right', onClick: () => abrirCadastro() },
+    },
+  })
+}
+</script>
+
+<template>
+  <TopToast :base-z-index="30000" />
+  <TopButton label="Salvar" @click="salvar" />
+</template>
+```
+
+| Prop | Tipo | Padrão | Finalidade |
+|---|---|---|---|
+| `baseZIndex` | `number` | `30000` | Camada base das notificações. |
+
+Além das opções usuais de `ToastMessageOptions` do PrimeVue (`severity`,
+`summary`, `detail`, `life`, `closable` etc.), `data` aceita `TopToastData`:
+
+| Campo | Tipo | Efeito |
+|---|---|---|
+| `data.footer` | `string \| number` | Texto discreto abaixo da mensagem. |
+| `data.action.label` | `string` | Rótulo da ação. |
+| `data.action.icon` | `string` opcional | Classe de ícone PrimeIcons. |
+| `data.action.onClick` | `() => void` opcional | Função chamada ao clicar na ação. |
+
+| Slot | Parâmetros recebidos | Uso |
+|---|---|---|
+| `action` | `{ action, message, run }` | Substitui o botão; execute `run()` para chamar `action.onClick`. |
+| `footer` | `{ message, footer }` | Substitui o rodapé. |
+
+## Tipos e exports públicos
+
+O pacote raiz exporta todos os componentes, `TopSolutionsPreset`, `colors` e
+os tipos abaixo. Use `import type` para não acrescentar código ao bundle.
+
+```ts
+import {
+  colors,
+  TopSolutionsPreset,
+  type TopButtonSeverity,
+  type TopDatePickerSelectionMode,
+  type TopDatePickerValue,
+  type TopFileUploadError,
+  type TopFileUploadValue,
+  type TopInputNumberValue,
+  type TopInputNumberMode,
+  type TopInputNumberButtonLayout,
+  type TopInputNumberCurrencyInputMode,
+  type TopNavItem,
+  type TopNavSection,
+  type TopTabItem,
+  type TopToastData,
+} from '@topjoao/top-design-system'
+```
+
+`TopNavItem` descreve um nó (`id`, `label`, `to?`, `icon?`, `disabled?`,
+`children?`, `data?`); `TopNavSection` é o mesmo contrato com `children`
+obrigatório. `TopNavAction`, `TopNavUser`, `TopNavClient` e
+`TopNavUserMenuItem` correspondem às props de mesmo nome. A aparência da barra
+é definida por `TopNavBarAppearance` e seus subtipos exportados:
+`TopNavBarColors`, `TopNavBarSurfaces`, `TopNavBarBorders`, `TopNavBarShape` e
+`TopNavBarFocus`. `TopNavBarSpacing` tipa as propriedades opcionais
+`headerPadding` e `breadcrumbPadding` da prop `spacing`.
+
+`TopInputNumberValue`, `TopInputNumberMode`, `TopInputNumberButtonLayout` e
+`TopInputNumberCurrencyInputMode`
+tipam, respectivamente, o valor, o modo de formatação, o layout dos botões e o
+modo de entrada monetária do campo numérico. `colors` expõe as escalas
+imutáveis `primary`, `secondary`, `success`, `warn` e
+`danger`, cada uma com tons de `50` a `950`.
+
+## Desenvolvimento da biblioteca
 
 ```bash
 npm install
@@ -1133,14 +1144,14 @@ Para gerar um pacote local instalável:
 npm pack
 ```
 
-Para publicar uma nova versão estável, primeiro incremente a versão seguindo o
-versionamento semântico; versões já publicadas no npm não podem ser
-sobrescritas. Use `patch`, `minor` ou `major` conforme o impacto da mudança.
-
-```bash
-npm version patch --no-git-tag-version
-npm publish --access public --tag latest
-```
-
-A tag `latest` é a padrão do npm. Assim, consumidores instalam a versão estável
-simplesmente com `npm install @topjoao/top-design-system`.
+Para publicar uma nova versão estável, primeiro incremente a versão seguindo o
+versionamento semântico; versões já publicadas no npm não podem ser
+sobrescritas. Use `patch`, `minor` ou `major` conforme o impacto da mudança.
+
+```bash
+npm version patch --no-git-tag-version
+npm publish --access public --tag latest
+```
+
+A tag `latest` é a padrão do npm. Assim, consumidores instalam a versão estável
+simplesmente com `npm install @topjoao/top-design-system`.