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

package/README.md

@@ -111,18 +111,26 @@ entrada `/plugin` também fornece as declarações globais usadas pela IDE.
 
 ## TopNavBar
 
-Barra de navegação corporativa com breadcrumbs, menu hierárquico, busca e
-ações opcionais. A aplicação consumidora fornece os dados do menu, define a
-página ativa e decide o que acontece em cada evento.
+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 TopNavItem } from '@topjoao/top-design-system'
+import {
+  TopNavBar,
+  type TopNavAction,
+  type TopNavItem,
+  type TopNavSection,
+} from '@topjoao/top-design-system'
 
 const clienteAtual = ref('prefeitura-a')
+const favorito = ref(false)
 
-const secoes = [
+const secoes: TopNavSection[] = [
   {
     id: 'planejamento',
     label: 'Planejamento',
@@ -140,15 +148,12 @@ const secoes = [
 ]
 
 function navegar(item: TopNavItem) {
-  // Ex.: router.push(item.to)
+  if (item.to) router.push(item.to)
 }
 
-function buscarNoMenu(query: string) {
-  // Filtre ou consulte os itens permitidos para este usuário.
+function executarIntegracao(action: TopNavAction) {
+  // Abra a integração identificada por action.id.
 }
-
-function alternarAssistente() {}
-function abrirSuporte() {}
 </script>
 
 <template>
@@ -158,50 +163,173 @@ function abrirSuporte() {}
     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="buscarNoMenu"
-    @toggle-aia="alternarAssistente"
-    @open-support="abrirSuporte"
+    @search="consultarMenusPermitidos"
+    @toggle-aia="alternarAia"
+    @open-support="abrirCentralSuporte"
+    @toggle-favorite="favorito = !favorito"
+    @action="executarIntegracao"
+    @user-action="executarAcaoDaSessao"
   >
-    <template #brand>
+    <template #brand="{ compact }">
       <img src="/logo.svg" alt="Minha organização">
+      <span v-if="!compact">Sistema de Contratações</span>
     </template>
 
-    <template #context>
+    <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>
 ```
 
-`activeItemId` gera automaticamente o breadcrumb da página ativa, incluindo os
-ancestrais e dropdowns de cada nível. Por exemplo, um item `calendario` dentro
-de `Programação` em `Planejamento` resulta em `Início / Navegação /
-Planejamento / Programação / Calendário`.
+### 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. |
 
-Para personalizar a aparência, use nomes orientados ao que é exibido: `textColor`
-para textos e ícones principais, `mutedTextColor` para detalhes secundários,
-`menuTextColor` para o conteúdo dos dropdowns, além de `headerBackground`,
-`breadcrumbBackground`, `menuBackground`, `accentColor`, `borderColor`, `radius`
-e `height`.
+`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, logo ou nome do sistema. |
-| `context` | Contexto de operação: cliente, órgão, ambiente, exercício ou escopo. |
-| `actions` | Ações adicionais à direita da barra. |
-| `user-menu` | Conteúdo adicional ou substituto para a área de usuário. |
-| `search-results` | Apresentação personalizada dos resultados da busca. |
-| `breadcrumb-actions` | Ações junto à página atual, como favoritos. |
-| `mobile-footer` | Conteúdo adicional no menu mobile. |
-
-Eventos: `navigate`, `search`, `toggle-aia`, `open-support`,
-`toggle-favorite` e `user-action`. A barra não navega, persiste estado ou chama
-serviços por conta própria. Quando `searchable` está ativo, `Ctrl+K` (ou `⌘K`
-no macOS) move o foco para a pesquisa; `Escape` fecha o painel de busca.
+| `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