@topjoao/top-design-system 0.1.0-beta.18 → 0.1.0-beta.19

package/README.md

@@ -106,240 +106,18 @@ 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`.
-
-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;
-}
-```
-
-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
+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="Excluir" severity="danger" />
+  <TopButton label="Salvar" icon="pi pi-save" @click="salvar" />
+  <TopButton label="Cancelar" secondary />
+  <TopButton label="Excluir" severity="danger" />
 
   <TopButton label="Consultar" outlined>
     <template #icon>
@@ -357,15 +135,15 @@ Exemplo
 | `icon` | `string` | `''` |
 | `loading` | `boolean` | `false` |
 | `class` | `string` | `''` |
-| `outlined` | `boolean` | `false` |
-| `severity` | `'primary' \| 'secondary' \| 'success' \| 'warn' \| 'danger'` | `'primary'` |
-| `secondary` | `boolean` | `false` |
+| `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"`.
+O componente emite `click` sem payload e oferece o slot nomeado `icon`.
+`secondary` permanece como atalho compatível para `severity="secondary"`.
 
 ## TopConfirmDialog
 
@@ -414,76 +192,76 @@ 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'
+## 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[]>([])
 
@@ -500,15 +278,15 @@ function enviarArquivos(files: File[]) {
     multiple
     :max-file-size="5 * 1024 * 1024"
     :max-files="5"
-    required
-    @select="enviarArquivos"
-  />
+    required
+    @select="enviarArquivos"
+  />
 </template>
 ```
 
 | Prop | Tipo | Padrão |
 |---|---|---|
-| `modelValue` | `File \| File[] \| null` | `null` |
+| `modelValue` | `File \| File[] \| null` | `null` |
 | `label` | `string` | `''` |
 | `placeholder` | `string` | `'Arraste e solte o arquivo aqui'` |
 | `required` | `boolean` | `false` |
@@ -525,8 +303,8 @@ function enviarArquivos(files: File[]) {
 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.
+pré-visualização. Os métodos `choose()` e `clear()` ficam disponíveis pela ref
+do componente.
 
 ## TopInputText
 
@@ -635,6 +413,59 @@ 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
@@ -661,7 +492,7 @@ npm run storybook
 ```
 
 Abra `http://localhost:6006` para acessar as histórias de `TopButton`,
-`TopConfirmDialog`, `TopDatePicker`, `TopInputText` e `TopSelect`. Use o botão de
+`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: