npm - @topjoao/top-design-system - Versions diffs - 0.1.0-beta.2 → 0.1.0-beta.20 - Mend

@topjoao/top-design-system 0.1.0-beta.2 → 0.1.0-beta.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/README.md +743 -135
package/dist/TopToast-CJpXTbO3.cjs +2 -0
package/dist/TopToast-CJpXTbO3.cjs.map +1 -0
package/dist/TopToast-SOmpzVY5.js +2414 -0
package/dist/TopToast-SOmpzVY5.js.map +1 -0
package/dist/components/TopButton.vue.d.ts +4 -1
package/dist/components/TopConfirmDialog.vue.d.ts +47 -0
package/dist/components/TopDatePicker.vue.d.ts +81 -0
package/dist/components/TopFileUpload.vue.d.ts +88 -0
package/dist/components/TopInputText.vue.d.ts +24 -0
package/dist/components/TopNavBar.vue.d.ts +269 -0
package/dist/components/TopSelect.vue.d.ts +100 -0
package/dist/components/TopTabs.vue.d.ts +34 -0
package/dist/components/TopToast.vue.d.ts +37 -0
package/dist/components/internal/TopNavMobileTree.vue.d.ts +20 -0
package/dist/index.cjs +1 -1
package/dist/index.cjs.map +1 -1
package/dist/index.d.ts +15 -0
package/dist/index.js +12 -70
package/dist/index.js.map +1 -1
package/dist/nuxt.cjs +1 -1
package/dist/nuxt.cjs.map +1 -1
package/dist/nuxt.js +28 -0
package/dist/nuxt.js.map +1 -1
package/dist/plugin.cjs +1 -1
package/dist/plugin.cjs.map +1 -1
package/dist/plugin.d.ts +16 -0
package/dist/plugin.js +4 -4
package/dist/plugin.js.map +1 -1
package/dist/style.css +1 -1
package/dist/theme/topSolutions.d.ts +7 -0
package/package.json +91 -84
package/dist/TopButton-9IIdtUbJ.js +0 -81
package/dist/TopButton-9IIdtUbJ.js.map +0 -1
package/dist/TopButton-CDKgguLF.cjs +0 -2
package/dist/TopButton-CDKgguLF.cjs.map +0 -1

package/README.md CHANGED Viewed

@@ -1,135 +1,743 @@
-# TopSolutions Design System
-Biblioteca de componentes Vue 3, estilos e tokens visuais compartilhados pela
-TopSolutions.
-## Instalação
-```bash
-npm install @topjoao/top-design-system@beta
-```
-A aplicação consumidora deve possuir Vue 3, PrimeVue, PrimeIcons e
-`@primeuix/themes` em versões compatíveis com as `peerDependencies` do pacote.
-## Uso com Nuxt
-Adicione o módulo uma única vez ao `nuxt.config.ts`:
-```ts
-export default defineNuxtConfig({
-  modules: [
-    // outros módulos...
-    '@topjoao/top-design-system/nuxt',
-  ],
-})
-```
-Depois de alterar a configuração, reinicie o servidor de desenvolvimento ou
-regenere os arquivos do Nuxt:
-```bash
-npm run postinstall
-```
-O módulo registra os componentes, gera suas tipagens e inclui o CSS da
-biblioteca. Não é necessário importar o componente manualmente:
-```vue
-<template>
-  <TopButton label="Salvar" icon="pi pi-save" />
-</template>
-```
-## Uso com Vue 3
-### Importação por componente
-```vue
-<script setup lang="ts">
-import { TopButton } from '@topjoao/top-design-system'
-import '@topjoao/top-design-system/style.css'
-</script>
-<template>
-  <TopButton label="Salvar" icon="pi pi-save" />
-</template>
-```
-### Registro global
-Na inicialização da aplicação:
-```ts
-import { createApp } from 'vue'
-import { TopSolutionsDesignSystem } from '@topjoao/top-design-system/plugin'
-import '@topjoao/top-design-system/style.css'
-import App from './App.vue'
-createApp(App).use(TopSolutionsDesignSystem).mount('#app')
-```
-Após o registro, os componentes podem ser utilizados sem importação manual. A
-entrada `/plugin` também fornece as declarações globais usadas pela IDE.
-## TopButton
-Exemplo
-```vue
-<template>
-  <TopButton label="Salvar" icon="pi pi-save" @click="salvar" />
-  <TopButton label="Cancelar" secondary />
-  <TopButton label="Consultar" outlined>
-    <template #icon>
-      <i class="pi pi-search" />
-    </template>
-  </TopButton>
-</template>
-```
-| Prop | Tipo | Padrão |
-|---|---|---|
-| `tooltip` | `string` | `''` |
-| `tooltipClass` | `string` | `'text-xs'` |
-| `label` | `string` | `''` |
-| `icon` | `string` | `''` |
-| `loading` | `boolean` | `false` |
-| `class` | `string` | `''` |
-| `outlined` | `boolean` | `false` |
-| `secondary` | `boolean` | `false` |
-| `disabled` | `boolean` | `false` |
-| `unstyled` | `boolean` | `false` |
-| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` |
-O componente emite `click` sem payload e oferece o slot nomeado `icon`.
-## Desenvolvimento da biblioteca
-```bash
-npm install
-npm run check
-```
-O comando `check` executa verificação de tipos, testes e build.
-Para inspecionar o conteúdo que seria publicado:
-```bash
-npm pack --dry-run
-```
-Para gerar um pacote local instalável:
-```bash
-npm pack
-```
-Para publicar uma nova versão beta, primeiro altere a versão; versões já
-publicadas no npm não podem ser sobrescritas.
-```bash
-npm version prerelease --preid=beta --no-git-tag-version
-npm publish --access public --tag beta
-```
+# TopSolutions Design System
+Biblioteca de componentes Vue 3, estilos e tokens visuais compartilhados pela
+TopSolutions.
+## Instalação
+```bash
+npm install @topjoao/top-design-system@beta
+```
+A aplicação consumidora deve possuir Vue 3, PrimeVue, PrimeIcons e
+`@primeuix/themes` em versões compatíveis com as `peerDependencies` do pacote.
+## Tema TopSolutions
+A biblioteca exporta `TopSolutionsPreset`, o preset PrimeVue baseado na paleta
+oficial da TopSolutions. Configure-o uma vez na aplicação consumidora:
+```ts
+import PrimeVue from 'primevue/config'
+import { TopSolutionsPreset } from '@topjoao/top-design-system'
+app.use(PrimeVue, {
+  theme: {
+    preset: TopSolutionsPreset,
+    options: { darkModeSelector: '.dark' },
+  },
+})
+```
+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
+borda fornecidos por `style.css`; não é necessário passar classes `dark:` em cada
+uso. A aplicação pode substituir esses tokens após importar o CSS da biblioteca.
+Os tokens públicos de campos são `--top-field-background`,
+`--top-field-background-readonly`, `--top-field-background-disabled`,
+`--top-field-text`, `--top-field-label`, `--top-field-placeholder`,
+`--top-field-border`, `--top-field-border-hover` e `--top-field-icon`.
+O preset é independente dos ajustes de layout próprios do TopLicita; ele
+contém apenas tokens semânticos compartilháveis, como cores primárias, neutras,
+sucesso, alerta e erro.
+`style.css` contém somente os estilos dos componentes públicos do Design System.
+Regras que
+alcançam o PrimeVue são encapsuladas pelas classes-raiz desses componentes;
+componentes PrimeVue usados diretamente pela aplicação consumidora não são
+sobrescritos pela biblioteca.
+## Uso com Nuxt
+Adicione o módulo uma única vez ao `nuxt.config.ts`:
+```ts
+export default defineNuxtConfig({
+  modules: [
+    // outros módulos...
+    '@topjoao/top-design-system/nuxt',
+  ],
+})
+```
+Depois de alterar a configuração, reinicie o servidor de desenvolvimento ou
+regenere os arquivos do Nuxt:
+```bash
+npm run postinstall
+```
+O módulo registra os componentes, gera suas tipagens e inclui o CSS da
+biblioteca. Não é necessário importar o componente manualmente:
+```vue
+<template>
+  <TopButton label="Salvar" icon="pi pi-save" />
+</template>
+```
+## Uso com Vue 3
+### Importação por componente
+```vue
+<script setup lang="ts">
+import { TopButton } from '@topjoao/top-design-system'
+import '@topjoao/top-design-system/style.css'
+</script>
+<template>
+  <TopButton label="Salvar" icon="pi pi-save" />
+</template>
+```
+### Registro global
+Na inicialização da aplicação:
+```ts
+import { createApp } from 'vue'
+import { TopSolutionsDesignSystem } from '@topjoao/top-design-system/plugin'
+import '@topjoao/top-design-system/style.css'
+import App from './App.vue'
+createApp(App).use(TopSolutionsDesignSystem).mount('#app')
+```
+Após o registro, os componentes podem ser utilizados sem importação manual. A
+entrada `/plugin` também fornece as declarações globais usadas pela IDE.
+## TopNavBar
+Barra de navegação responsiva inspirada no AppSidebar do TopLicita. O
+componente fornece apenas layout e interação: a aplicação consumidora continua
+responsável por rotas, permissões, sessão, cliente/órgão, busca remota,
+favoritos, Aia, suporte e integrações. Nenhuma dessas ações é executada pela
+biblioteca; todas são comunicadas por eventos.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  TopNavBar,
+  type TopNavAction,
+  type TopNavItem,
+  type TopNavSection,
+} from '@topjoao/top-design-system'
+const clienteAtual = ref('prefeitura-a')
+const favorito = ref(false)
+const secoes: TopNavSection[] = [
+  {
+    id: 'planejamento',
+    label: 'Planejamento',
+    icon: 'pi pi-book',
+    children: [
+      {
+        id: 'programacao',
+        label: 'Programação',
+        children: [
+          { id: 'calendario', label: 'Calendário', to: '/programacao/calendario' },
+        ],
+      },
+    ],
+  },
+]
+function navegar(item: TopNavItem) {
+  if (item.to) router.push(item.to)
+}
+function executarIntegracao(action: TopNavAction) {
+  // Abra a integração identificada por action.id.
+}
+</script>
+<template>
+  <TopNavBar
+    :sections="secoes"
+    active-item-id="calendario"
+    searchable
+    show-aia
+    show-support
+    show-favorite-toggle
+    :favorite-active="favorito"
+    :actions="[
+      { id: 'integracoes', label: 'Integrações', icon: 'pi pi-th-large' },
+    ]"
+    :user="{ name: 'João Silva', subtitle: 'Administrador', initials: 'JS' }"
+    :user-menu-items="[
+      { id: 'perfil', label: 'Meu perfil', icon: 'pi pi-user' },
+      { id: 'sair', label: 'Sair', icon: 'pi pi-sign-out' },
+    ]"
+    @navigate="navegar"
+    @search="consultarMenusPermitidos"
+    @toggle-aia="alternarAia"
+    @open-support="abrirCentralSuporte"
+    @toggle-favorite="favorito = !favorito"
+    @action="executarIntegracao"
+    @user-action="executarAcaoDaSessao"
+  >
+    <template #brand="{ compact }">
+      <img src="/logo.svg" alt="Minha organização">
+      <span v-if="!compact">Sistema de Contratações</span>
+    </template>
+    <template #context="{ compact }">
+      <select v-model="clienteAtual" aria-label="Cliente atual">
+        <option value="prefeitura-a">Prefeitura A</option>
+        <option value="prefeitura-b">Prefeitura B</option>
+      </select>
+      <span v-if="!compact">Poder Executivo</span>
+    </template>
+  </TopNavBar>
+</template>
+```
+### Menu e breadcrumbs
+`sections` aceita uma árvore de profundidade arbitrária. Cada nó usa
+`TopNavItem` (`id`, `label`, `to?`, `icon?`, `disabled?`, `children?`, `data?`).
+Seções sem filhos são removidas e um `children: []` nunca cria um painel vazio.
+No desktop, a primeira coluna do painel mestre–detalhe tem `16rem`; os itens de
+cada nível são repartidos em colunas de `18rem`, no máximo dez por coluna.
+Subníveis aparecem sempre à direita do nível de origem.
+Breadcrumbs estão habilitados por padrão e começam por `Início / Navegação`.
+Há duas formas de fornecer a trilha:
+- informe `breadcrumbs` com itens `TopNavBreadcrumb`; `sectionId` liga o item a
+  uma seção e `menuId` liga a qualquer nó com filhos;
+- omita `breadcrumbs` e informe `activeItemId`; a trilha é derivada da árvore.
+Por exemplo, `calendario` dentro de `Programação` em `Planejamento` gera
+`Início / Navegação / Planejamento / Programação / Calendário`. A rota ativa
+não recebe fundo permanente nos menus desktop; somente hover e o ramo que está
+sendo explorado recebem destaque.
+### Props
+| Prop | Tipo / padrão | Finalidade |
+|---|---|---|
+| `sections` | `TopNavSection[]` / `[]` | Árvore de navegação já filtrada pela aplicação. |
+| `breadcrumbs` | `TopNavBreadcrumb[]` / `[]` | Trilha explícita; vazia permite derivação por `activeItemId`. |
+| `homeItem` | `TopNavItem` / `Início` | Item inicial emitido ao clicar em Início. |
+| `navigationLabel` | `string` / `Navegação` | Rótulo do menu mestre. |
+| `activeItemId` | `string` | Nó atual, usado no breadcrumb e no Drawer. |
+| `searchable` | `boolean` / `false` | Habilita busca desktop e busca própria do Drawer. |
+| `searchValue` | `string` | Valor opcionalmente controlado com `v-model:search-value`. |
+| `searchResults` | `TopNavItem[]` | Resultados controlados; sem a prop, a árvore é filtrada localmente. |
+| `searchPlaceholder` | `string` | Placeholder das duas buscas. |
+| `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`. |
+| `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. |
+### Eventos
+| Evento | Payload | Quando ocorre |
+|---|---|---|
+| `navigate` | `TopNavItem` | Início, menu, resultado ou favorito é selecionado. |
+| `search` | `string` | A consulta muda no desktop ou no Drawer. |
+| `update:searchValue` | `string` | Atualização de `v-model:search-value`. |
+| `update:mobileOpen` | `boolean` | Atualização de `v-model:mobile-open`. |
+| `toggle-aia` | — | A ação Aia é acionada. |
+| `open-support` | — | A ação de suporte é acionada. |
+| `toggle-favorite` | — | A estrela da página atual é acionada. |
+| `action` | `TopNavAction` | Uma ação genérica/integração é acionada. |
+| `user-action` | `TopNavUserMenuItem` | Uma opção de usuário é selecionada. |
+| `user-click` | `TopNavUser \| undefined` | A área de usuário sem menu é acionada. |
+`Ctrl+K` e `Cmd+K` abrem/focam a busca. Em telas menores que `1024px`, o
+atalho abre primeiro o Drawer e foca a busca móvel. `Escape` fecha os painéis.
+### Slots
+| Slot | Uso |
+|---|---|
+| `brand` | Marca; recebe `{ compact }`. |
+| `context`, `scope` ou `client` | Contexto operacional; aliases com prioridade nessa ordem e `{ compact }`. |
+| `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. |
+| `user` | Conteúdo do gatilho de usuário; recebe `{ user, compact }`. |
+| `user-menu` | Painel de usuário; recebe `{ items, select }`. |
+| `search-results` | Resultados customizados; recebe `{ items, select }`. |
+| `breadcrumb-actions` | Ações adicionais no fim da segunda faixa. |
+| `drawer-header` | Cabeçalho inteiro; recebe `{ close }`. |
+| `drawer-brand` | Marca do Drawer; por padrão reutiliza `brand`. |
+| `drawer-search` | Busca inteira; recebe `{ query, update, clear }`. |
+| `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, open, toggle }`. |
+| `drawer-footer` | Conteúdo final adicional; recebe `{ close }`. |
+### Aparência e responsividade
+`appearance` aceita `headerBackground`, `breadcrumbBackground`,
+`drawerBackground`, `drawerFooterBackground`, `textColor`, `mutedTextColor`,
+`accentColor`, `menuBackground`, `menuTextColor`, `menuHoverBackground`,
+`menuExploredBackground`, `borderColor`, `menuBorderColor` (a borda externa de
+6px), `menuOutlineColor`, `radius`, `drawerRadius`, `headerHeight` (`height` é
+mantido como alias), `drawerWidth`, `shadow`, `fontFamily`, `fontSize`,
+`secondaryFontSize`, `captionFontSize`, `lineHeight`, `fontWeight`,
+`strongFontWeight`, `actionSize`, `headerPadding`, `mobileHeaderPadding`,
+`breadcrumbPadding`, `mobileBreadcrumbPadding`, `menuItemPadding`,
+`itemLineHeight`, `sectionWidth`, `columnWidth` e `contextCompactWidth`.
+No Drawer, `mobileActiveBackground`, `mobileActiveTextColor`,
+e `mobileDividerColor` controlam respectivamente o módulo ativo e os
+separadores horizontais.
+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`
+só cria variáveis inline para propriedades que foram realmente informadas; os
+valores fiéis ao AppSidebar existem apenas como *fallbacks* no CSS. Assim, um
+tema global pode controlar o componente sem precisar usar `!important`:
+```css
+:root {
+  --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-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%);
+}
+```
+As variáveis globais também alcançam o Drawer teleportado. 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
+vira ícone abaixo de `1320px`, nome do usuário some abaixo de `1180px` e, se o
+conteúdo ainda transbordar, o contexto recebe `compact: true`. O último estágio
+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. 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.
+## TopButton
+Exemplo
+```vue
+<template>
+  <TopButton label="Salvar" icon="pi pi-save" @click="salvar" />
+  <TopButton label="Cancelar" secondary />
+  <TopButton label="Excluir" severity="danger" />
+  <TopButton label="Consultar" outlined>
+    <template #icon>
+      <i class="pi pi-search" />
+    </template>
+  </TopButton>
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `tooltip` | `string` | `''` |
+| `tooltipClass` | `string` | `'text-xs'` |
+| `label` | `string` | `''` |
+| `icon` | `string` | `''` |
+| `loading` | `boolean` | `false` |
+| `class` | `string` | `''` |
+| `outlined` | `boolean` | `false` |
+| `severity` | `'primary' \| 'secondary' \| 'success' \| 'warn' \| 'danger'` | `'primary'` |
+| `secondary` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `unstyled` | `boolean` | `false` |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` |
+O componente emite `click` sem payload e oferece o slot nomeado `icon`.
+`secondary` permanece como atalho compatível para `severity="secondary"`.
+## 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
+decide o que executar e quando encerrar após a confirmação.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopConfirmDialog } from '@topjoao/top-design-system'
+const showConfirm = ref(false)
+function excluirRegistro() {
+  // Execute a ação e feche o diálogo quando apropriado.
+  showConfirm.value = false
+}
+</script>
+<template>
+  <TopConfirmDialog
+    v-model="showConfirm"
+    title="Confirmar exclusão"
+    message="Deseja realmente excluir este registro?"
+    confirm-text="Excluir"
+    cancel-text="Cancelar"
+    @confirm="excluirRegistro"
+  />
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `boolean` | `false` |
+| `title` | `string` | `'Confirmar'` |
+| `message` | `string` | `''` |
+| `confirmText` / `cancelText` | `string` | `'Confirmar'` / `'Cancelar'` |
+| `loading` | `boolean` | `false` |
+| `loadingText` | `string` | `'Processando...'` |
+| `severity` | `'primary' \| 'danger'` | `'danger'` |
+| `icon` | `string` | `'pi pi-exclamation-triangle'` |
+Eventos: `update:modelValue`, `confirm`, `cancel` e `close`. O evento `confirm`
+não fecha automaticamente o diálogo, permitindo que a aplicação aguarde uma
+operação assíncrona. Os slots `message` e default permitem substituir a mensagem
+textual.
+## TopDatePicker
+Seletor de datas baseado no `DatePicker` do PrimeVue. O valor permanece como
+`Date` (ou arrays de `Date` nos modos `multiple` e `range`); `dateFormat` altera
+somente a apresentação no campo e não converte o `v-model` para texto.
+No modo padrão (`single` com `dd/mm/yy`), a digitação recebe automaticamente a
+máscara brasileira `dd/mm/aaaa`.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopDatePicker } from '@topjoao/top-design-system'
+const dataNascimento = ref<Date | null>(null)
+</script>
+<template>
+  <TopDatePicker
+    v-model="dataNascimento"
+    label="Data de nascimento"
+    placeholder="Selecione a data"
+    :max-date="new Date()"
+    required
+    error="Informe uma data válida."
+    @date-select="validarData"
+  />
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `Date \| Date[] \| (Date \| null)[] \| null` | `null` |
+| `label` | `string` | `''` |
+| `placeholder` | `string` | `'dd/mm/aaaa'` |
+| `required` | `boolean` | `false` |
+| `error` | `string` | `''` |
+| `invalid` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `readonly` | `boolean` | `false` |
+| `selectionMode` | `'single' \| 'multiple' \| 'range'` | `'single'` |
+| `dateFormat` | `string` | `'dd/mm/yy'` |
+| `minDate` / `maxDate` | `Date` | `undefined` |
+| `showIcon` | `boolean` | `true` |
+| `iconDisplay` | `'button' \| 'input'` | `'input'` |
+| `manualInput` | `boolean` | `true` |
+| `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`.
+`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
+mensagem ao input com atributos ARIA e a exibe abaixo do campo. `readonly`
+impede edição e seleção sem desabilitar o controle, enquanto `disabled` remove a
+interação. No modo escuro, o campo usa os tokens públicos `--top-field-*`.
+## TopFileUpload
+Seletor de arquivos baseado no `FileUpload` do PrimeVue. O componente valida e
+apresenta os arquivos, mas não os envia: a aplicação consumidora controla o
+upload por `v-model` e pelos eventos.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopFileUpload } from '@topjoao/top-design-system'
+const anexos = ref<File[]>([])
+function enviarArquivos(files: File[]) {
+  // Envie os arquivos usando o serviço da aplicação.
+}
+</script>
+<template>
+  <TopFileUpload
+    v-model="anexos"
+    label="Anexos"
+    accept=".pdf,image/*"
+    multiple
+    :max-file-size="5 * 1024 * 1024"
+    :max-files="5"
+    required
+    @select="enviarArquivos"
+  />
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `File \| File[] \| null` | `null` |
+| `label` | `string` | `''` |
+| `placeholder` | `string` | `'Arraste e solte o arquivo aqui'` |
+| `required` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `accept` | `string` | `''` |
+| `multiple` | `boolean` | `false` |
+| `maxFileSize` | `number \| null` (bytes) | `null` |
+| `maxFiles` | `number \| null` | `null` |
+| `error` | `string` | `''` |
+| `selectLabel` | `string` | `'Selecionar arquivo'` |
+| `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.
+## TopInputText
+Campo textual baseado no `InputText` do PrimeVue. O `v-model` é sempre
+`string`, inclusive para códigos, documentos e identificadores compostos
+somente por dígitos; por exemplo, `"001234"` preserva os zeros à esquerda.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopInputText } from '@topjoao/top-design-system'
+const codigo = ref('001234')
+</script>
+<template>
+  <TopInputText
+    id="codigo"
+    v-model="codigo"
+    label="Código"
+    placeholder="Digite o código"
+    required
+    maxlength="10"
+    autocomplete="off"
+  />
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `string` | `''` |
+| `label` | `string` | `''` |
+| `placeholder` | `string` | `''` |
+| `required` | `boolean` | `false` |
+| `error` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+| `readonly` | `boolean` | `false` |
+Atributos e eventos nativos adicionais, como `name`, `maxlength`,
+`autocomplete`, `inputmode`, `pattern`, `aria-*`, `data-*`, `focus` e `blur`,
+são repassados ao elemento `input` interno.
+## TopSelect
+Seletor pesquisável baseado no `AutoComplete` do PrimeVue. Ele é genérico: a
+aplicação fornece os itens, executa a busca e decide qualquer apresentação de
+domínio por slots.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopSelect } from '@topjoao/top-design-system'
+const selectedCustomer = ref(null)
+const customers = ref([])
+function searchCustomers({ query }: { query: string }) {
+  // Atualize customers com o resultado da sua fonte de dados.
+}
+</script>
+<template>
+  <TopSelect
+    v-model="selectedCustomer"
+    :options="customers"
+    option-label="name"
+    option-key="id"
+    option-prefix="code"
+    show-option-prefix
+    :loading="false"
+    @search="searchCustomers"
+  >
+    <template #icon="{ loading }">
+      <i :class="loading ? 'pi pi-spin pi-spinner' : 'pi pi-users'" />
+    </template>
+    <template #footer>
+      <button type="button">Criar cliente</button>
+    </template>
+  </TopSelect>
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `options` | `array` | `[]` |
+| `optionLabel` | `string \| function` | `'label'` |
+| `optionKey` | `string` | `'id'` |
+| `optionPrefix` | `string` | `''` |
+| `showOptionPrefix` | `boolean` | `false` |
+| `showSelectedPrefix` | `boolean` | `false` |
+| `loading` / `disabled` / `invalid` | `boolean` | `false` |
+| `placeholder` | `string` | `'Search...'` |
+| `minQueryLength` | `number` | `1` |
+| `multiple` / `forceSelection` | `boolean` | `false` / `true` |
+| `panelWidth` / `scrollHeight` | `string` | `null` / `'250px'` |
+| `emptyMessage` / `loadingMessage` | `string` | mensagens padrão em inglês |
+| `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.
+## TopTabs
+Navegação em abas baseada em `Tabs`, `TabList`, `Tab`, `TabPanels` e `TabPanel`
+do PrimeVue, com estrutura simplificada e estilos dos temas claro e escuro do
+Design System.
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  TopTabs,
+  type TopTabItem,
+  type TopTabValue,
+} from '@topjoao/top-design-system'
+const activeTab = ref<TopTabValue>('dados')
+const tabs: TopTabItem[] = [
+  { value: 'dados', label: 'Dados' },
+  { value: 'documentos', label: 'Documentos' },
+  { value: 'auditoria', label: 'Auditoria', disabled: true },
+]
+</script>
+<template>
+  <TopTabs v-model="activeTab" :tabs="tabs">
+    <template #dados>
+      Dados gerais do processo
+    </template>
+    <template #documentos>
+      Documentos anexados
+    </template>
+    <template #auditoria>
+      Histórico de auditoria
+    </template>
+  </TopTabs>
+</template>
+```
+| Prop | Tipo | Padrão |
+|---|---|---|
+| `modelValue` | `string \| number` | obrigatório |
+| `tabs` | `TopTabItem[]` | obrigatório |
+| `lazy` | `boolean` | `false` |
+| `scrollable` | `boolean` | `true` |
+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`.
+## Desenvolvimento da biblioteca
+```bash
+npm install
+npm run check
+```
+O comando `check` executa verificação de tipos, testes e build.
+Para inspecionar o conteúdo que seria publicado:
+```bash
+npm pack --dry-run
+```
+## Playground visual
+O Storybook permite testar os componentes isoladamente e consultar seus
+exemplos. Ele é uma dependência de desenvolvimento e não é incluído no pacote
+publicado.
+```bash
+npm run storybook
+```
+Abra `http://localhost:6006` para acessar as histórias de `TopButton`,
+`TopConfirmDialog`, `TopDatePicker`, `TopInputText`, `TopSelect` e `TopTabs`. Use o botão de
+contraste na barra superior para alternar o preview entre tema claro e escuro.
+Para gerar a versão estática da documentação, execute:
+```bash
+npm run build-storybook
+```
+Para gerar um pacote local instalável:
+```bash
+npm pack
+```
+Para publicar uma nova versão beta, primeiro altere a versão; versões já
+publicadas no npm não podem ser sobrescritas.
+```bash
+npm version prerelease --preid=beta --no-git-tag-version
+npm publish --access public --tag beta
+```