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

package/README.md

@@ -106,10 +106,232 @@ 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
+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
 
 Exemplo