@horizon-framework/website-dev-docs 2.3.0

package/knowledge/CAPABILITIES.md

@@ -0,0 +1,190 @@
+# Capabilities — Features Transversais do Frontend
+
+> Sistema de funcionalidades reutilizaveis em apps/web/src/capabilities/
+
+---
+
+## Mapa das 11 Capabilities
+
+| Capability | Pasta | Funcao |
+|---|---|---|
+| Contacts | `contacts/` | Telefones e emails centralizados |
+| Social | `social/` | Redes sociais (13 plataformas) |
+| Code Snippets | `code-snippets/` | Scripts de marketing (GTM, GA, Facebook Pixel) |
+| MetaTags | `metatags/` | SEO global (title, favicon, OG) |
+| Navigations | `navigations/` | Menus dinamicos (ver NAVEGACAO_DINAMICA.md) |
+| Redirects | `redirects/` | URLs antigas → novas |
+| Sitemap | `sitemap/` | XML dinamico conectado com modulos |
+| Translation | `translation/` | Multilingue (PT, EN, ES) |
+| UTM Tracking | `utm-tracking/` | Captura parametros UTM |
+| Forms | `forms/` | Envio de leads + LGPD |
+| WhatsApp Float | `(em components/)` | Botao flutuante de atendimento |
+
+---
+
+## CONTACTS — Sistema de Contatos
+
+**Pasta:** `capabilities/contacts/`
+
+Centraliza TODOS os contatos do site (telefones, emails, WhatsApp).
+
+**Interface:**
+```typescript
+interface Contact {
+  type: "phone" | "email";
+  tags: ContactTag[];     // "whatsapp", "telegram", "mobile", "land"
+  value: string;          // numero ou email
+  label: string;          // "WhatsApp Principal"
+}
+```
+
+**Registry:** `CONTACT_TAG_CONFIG` mapeia tags para icones e URLs:
+- whatsapp → `https://wa.me/{numero}`
+- telegram → `https://t.me/{username}`
+- mobile → icone smartphone
+- land → icone phone
+
+**Dados:** `data/contacts.data.ts` — contatos base do cliente
+**Converters:** `toNavigationItems(contacts)` → NavigationItem[]
+
+**Ao criar site novo:** Editar `data/contacts.data.ts` com contatos do cliente.
+
+---
+
+## SOCIAL — Redes Sociais
+
+**Pasta:** `capabilities/social/`
+
+13 plataformas suportadas: Facebook, Instagram, LinkedIn, X, YouTube, TikTok, WhatsApp Business, Telegram, Pinterest, Discord, GitHub, Blog, Other.
+
+**Registry:** `SOCIAL_PLATFORMS` com icone, URL pattern, cor, descricao para cada plataforma.
+
+**Helpers:**
+- `createSocialFromUsername(platform, username)` → Social
+- `validateSocial(social)` → boolean
+- `toNavigationItems(socials)` → NavigationItem[]
+
+**Ao criar site novo:** Editar dados das redes sociais do cliente.
+
+---
+
+## CODE-SNIPPETS — Marketing Scripts
+
+**Pasta:** `capabilities/code-snippets/`
+
+Arquivo unico `scripts-marketing.tsx` com:
+- Google Tag Manager (GTM)
+- Google Analytics (GA4)
+- Facebook Pixel
+- Eventos de conversao (pagina /obrigado, cliques WhatsApp)
+
+**Ao criar site novo:** Trocar IDs de GTM, GA e Facebook Pixel do cliente.
+
+---
+
+## METATAGS — SEO Global
+
+**Pasta:** `capabilities/metatags/`
+
+Configuracao centralizada em `seo.ts`:
+- Title suffix (nome da imobiliaria)
+- Favicon path
+- OG Image (800x450)
+
+**Ao criar site novo:** Trocar nome, favicon e OG image.
+
+---
+
+## REDIRECTS — URLs Antigas
+
+**Pasta:** `capabilities/redirects/nextjs/`
+
+Gera redirects permanentes para o next.config:
+- Property: `/imovel/{slug}-ref-{id}` → `/imovel/{id}`
+- Genericos: `/venda` → `/imoveis/venda`
+- Search mappings: `/venda/apartamentos` → `/imoveis?filtros`
+
+**Exporta:** `generateNextConfigRedirects()` para integrar no next.config.js
+
+---
+
+## SITEMAP — XML Dinamico
+
+**Pasta:** `capabilities/sitemap/`
+
+Sistema modular: cada modulo implementa `SitemapProvider`.
+- `router.ts` roteia slug para provider correto via MODULES_REGISTRY
+- `config/static-pages.ts` lista paginas estaticas
+- `generators/` gera XML valido + sitemap index
+
+**Paginas estaticas incluidas:** /, /sobre, /contato, /localizacao, /termos-uso, /politica-privacidade
+
+**Ao criar site novo:** Verificar se paginas estaticas correspondem as existentes.
+
+---
+
+## TRANSLATION — Multilingue
+
+**Pasta:** `capabilities/translation/`
+
+3 idiomas: Portugues (pt), Ingles (en), Espanhol (es).
+Usa Google Translate com cookie `googtrans`.
+
+**Componentes:** LanguageProvider, LanguageSelector, LanguageSuggestionBanner
+**Hook:** `useForceTranslation`, `useLanguage`
+
+---
+
+## UTM TRACKING — Parametros de Marketing
+
+**Pasta:** `capabilities/utm-tracking/`
+
+Captura parametros UTM da URL e persiste em localStorage.
+- `extractUTMFromURL()` → UTMParams
+- `saveUTMToStorage()` / `loadUTMFromStorage()`
+- Hook: `useUTMTracking`, `useCurrentUTM`
+
+**Tipo:** `UTMParams { source, medium, campaign, term, content }`
+
+---
+
+## FORMS — Envio de Leads
+
+**Pasta:** `capabilities/forms/`
+
+Sistema centralizado para envio de leads:
+- `sendLead(data)` → envia para AUTOMATIONS
+- `consent.data.ts` → textos LGPD (completo e compacto)
+- Captura meta: page_id, utm_source, utm_campaign
+
+**Interface:** `LeadFormData` com campos tipados (text, email, phone, etc.)
+
+---
+
+## WHATSAPP FLUTUANTE
+
+**Pasta:** `components/whatsapp-float-button/`
+
+Botao circular fixo no canto inferior direito com:
+- Balao de mensagem animado (delay 7s)
+- Avatar do atendente customizavel
+- LocalStorage para lembrar fechamento
+- Link direto: `https://api.whatsapp.com/send/?phone={num}&text={msg}`
+
+**Config:** `WhatsAppConfig { phoneNumber, message, showBubble, bubbleMessage, attendantName, attendantAvatar }`
+
+**Ao criar site novo:** Configurar numero, mensagem e avatar no WhatsAppProvider.
+
+---
+
+## CHECKLIST — O que trocar ao criar site novo
+
+Ao usar template Horizon para novo cliente, trocar em capabilities:
+1. `contacts/data/contacts.data.ts` — telefones e emails
+2. `social/data/` — redes sociais
+3. `code-snippets/scripts-marketing.tsx` — IDs GTM, GA, Facebook
+4. `metatags/seo.ts` — nome, favicon, OG image
+5. `redirects/` — URLs especificas do cliente
+6. `sitemap/config/static-pages.ts` — paginas estaticas
+7. `WhatsAppProvider` — numero, mensagem, avatar
+8. `forms/` — verificar destino de leads

package/knowledge/COMPONENTES_GLOBAIS_UI.md

@@ -0,0 +1,407 @@
+# Sistema de Componentes Globais
+
+Sistema completo de componentes reutilizáveis e utilitários para a aplicação Nova Torres.
+
+## Componentes Implementados
+
+### **1. Sonner Toast** (Já Ativo)
+Sistema de notificações elegante já integrado no layout.
+
+**Uso:**
+```tsx
+import { toast } from "sonner";
+
+// Sucesso
+toast.success("Formulário enviado com sucesso!");
+
+// Erro
+toast.error("Erro ao processar dados");
+
+// Personalizado
+toast("Mensagem", {
+  description: "Descrição adicional",
+  duration: 5000
+});
+```
+
+### **2. Global Loading**
+Loading global centralizado com overlay.
+
+**Uso:**
+```tsx
+import { useGlobalLoading } from "@/components/providers/GlobalUIProvider";
+
+function MeuComponente() {
+  const { showLoading, hideLoading } = useGlobalLoading();
+
+  const handleSubmit = async () => {
+    showLoading();
+
+    try {
+      await minhaFuncaoAsincrona();
+    } finally {
+      hideLoading();
+    }
+  };
+}
+```
+
+### **3. Form Alert Modal** (Sua Ideia Genial!)
+Modal de feedback para formulários com timeout automático.
+
+**Uso:**
+```tsx
+import { useFormAlert } from "@/components/providers/GlobalUIProvider";
+
+function MeuFormulario() {
+  const { showAlert } = useFormAlert();
+
+  const handleSubmit = () => {
+    // Lógica do formulário...
+
+    showAlert({
+      type: "success", // "success" | "error" | "warning"
+      title: "Formulário Enviado!",
+      message: "Nossa equipe entrará em contato em breve.",
+      timeout: 5000 // auto-fechar em 5s
+    });
+  };
+}
+```
+
+### **4. Generic Modal**
+Sistema de modais reutilizáveis com diferentes tipos.
+
+**Uso:**
+```tsx
+import { useModal } from "@/components/providers/GlobalUIProvider";
+
+function MeuComponente() {
+  const { showModal } = useModal();
+
+  // Modal customizado
+  const openCustomModal = () => {
+    showModal({
+      type: "dialog",
+      title: "Editar Perfil",
+      content: <MeuFormulario />,
+      size: "lg"
+    });
+  };
+
+  // Alert simples
+  const openAlert = () => {
+    showModal({
+      type: "alert",
+      title: "Sucesso!",
+      description: "Operação realizada com sucesso."
+    });
+  };
+
+  // Confirmação
+  const openConfirm = () => {
+    showModal({
+      type: "confirm",
+      title: "Confirmar exclusão?",
+      description: "Esta ação não pode ser desfeita.",
+      variant: "destructive",
+      onConfirm: () => console.log("Confirmado"),
+      onCancel: () => console.log("Cancelado")
+    });
+  };
+}
+```
+
+### **5. Generic Sheet**
+Sidebars/drawers deslizantes para menus e painéis.
+
+**Uso:**
+```tsx
+import { useSheet } from "@/components/providers/GlobalUIProvider";
+
+function MeuComponente() {
+  const { showSheet } = useSheet();
+
+  const openMenu = () => {
+    showSheet({
+      title: "Menu de Navegação",
+      side: "left", // "left" | "right" | "top" | "bottom"
+      size: "sm",   // "sm" | "md" | "lg" | "xl" | "full"
+      content: <MenuNavegacao />
+    });
+  };
+
+  const openSettings = () => {
+    showSheet({
+      title: "Configurações",
+      side: "right",
+      size: "md",
+      content: <PainelConfiguracoes />
+    });
+  };
+}
+```
+
+### **6. Splash Screen**
+Tela inicial do app com animações elegantes.
+
+**Uso:**
+```tsx
+import { useSplashScreen } from "@/components/providers/GlobalUIProvider";
+
+function MeuComponente() {
+  const { showSplash, hideSplash } = useSplashScreen();
+
+  // Mostrar por 3 segundos
+  const showWelcome = () => {
+    showSplash(3000);
+  };
+
+  // Mostrar até esconder manualmente
+  const showPersistent = () => {
+    showSplash(0);
+    // Depois chamar hideSplash() quando quiser fechar
+  };
+}
+```
+
+### **7. Prose Typography**
+Componente para conteúdo rico em texto (markdown, artigos, docs).
+
+**Uso:**
+```tsx
+import { ProseTypography, ArticleProse, DocsProse } from "@/components/providers/GlobalUIProvider";
+
+// Básico
+<ProseTypography size="base" variant="default">
+  <div dangerouslySetInnerHTML={{ __html: meuConteudoHTML }} />
+</ProseTypography>
+
+// Para artigos
+<ArticleProse
+  title="Título do Artigo"
+  subtitle="Subtítulo opcional"
+  size="lg"
+>
+  {meuConteudo}
+</ArticleProse>
+
+// Para documentação
+<DocsProse>
+  {documentacaoTecnica}
+</DocsProse>
+```
+
+### **8. Video Player Modal**
+Modal para reprodução de vídeos do YouTube/Vimeo com suporte a navegação.
+
+**Localização:** `@/components/ui/horizon-ui/video-player-modal`
+
+**Uso Básico:**
+```tsx
+import { useState } from "react";
+import { VideoPlayerModal } from "@/components/ui/horizon-ui/video-player-modal";
+
+function MeuComponente() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Assistir Vídeo</button>
+
+      <VideoPlayerModal
+        open={isOpen}
+        onOpenChange={setIsOpen}
+        video={{
+          id: "video-1",
+          title: "Título do Vídeo",
+          url: "https://www.youtube.com/watch?v=VIDEO_ID",
+          subtitle: "Descrição opcional",
+        }}
+        externalLinkText="Assistir no YouTube"
+      />
+    </>
+  );
+}
+```
+
+**Com Navegação (lista de vídeos):**
+```tsx
+const [currentIndex, setCurrentIndex] = useState(0);
+const videos = [...]; // Lista de vídeos
+
+<VideoPlayerModal
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  video={videos[currentIndex]}
+  onPrevious={() => setCurrentIndex((i) => (i === 0 ? videos.length - 1 : i - 1))}
+  onNext={() => setCurrentIndex((i) => (i + 1) % videos.length)}
+  externalLinkText="Assistir no YouTube"
+  externalLinkIcon={<Youtube className="size-5" />}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Descrição |
+|------|------|-----------|
+| `open` | `boolean` | Controla abertura do modal |
+| `onOpenChange` | `(open: boolean) => void` | Callback de mudança de estado |
+| `video` | `{ id, title, url, subtitle? }` | Dados do vídeo atual |
+| `onPrevious?` | `() => void` | Callback para vídeo anterior |
+| `onNext?` | `() => void` | Callback para próximo vídeo |
+| `showNavigation?` | `boolean` | Mostrar botões prev/next (default: true) |
+| `showExternalLink?` | `boolean` | Mostrar link externo (default: true) |
+| `externalLinkText?` | `string` | Texto do link externo |
+| `externalLinkIcon?` | `ReactNode` | Ícone do link externo |
+
+**Suporte automático:**
+- YouTube: `youtube.com/watch?v=`, `youtu.be/`, `youtube.com/shorts/`
+- Vimeo: `vimeo.com/`
+- URLs de embed diretas
+
+## Como Está Configurado
+
+O sistema está **100% integrado** no seu `AppProviders.tsx`:
+
+```tsx
+<GlobalUIProvider
+  splashScreen={{
+    autoShow: false, // Não mostrar automaticamente
+    defaultDuration: 2000,
+  }}
+>
+  {/* Sua aplicação */}
+</GlobalUIProvider>
+```
+
+## Exemplo Prático: Página de Contato
+
+Sua página `/contato` **já está usando** o sistema:
+
+1. **Toast** para feedback (sucesso/erro)
+2. **Loading** no botão durante envio
+3. 🆕 **Pode adicionar Form Alert Modal** para feedback mais elegante
+
+**Exemplo de melhoria:**
+```tsx
+// Substitua o toast por Form Alert Modal
+import { useFormAlert } from "@/components/providers/GlobalUIProvider";
+
+const { showAlert } = useFormAlert();
+
+// Em vez de:
+toast.success("Mensagem enviada com sucesso!");
+
+// Use:
+showAlert({
+  type: "success",
+  title: "Mensagem Enviada!",
+  message: "Nossa equipe entrará em contato em breve.",
+  timeout: 5000
+});
+```
+
+## Stories no Storybook
+
+Todos os componentes têm stories completos disponíveis em:
+
+- `Global/GlobalLoading`
+- `Global/FormAlertModal`
+- `Global/useModal`
+- `Global/useSheet`
+- `Global/SplashScreen`
+- `Global/ProseTypography`
+- `Global/GlobalUIProvider`
+- `HorizonUI/VideoPlayerModal`
+
+Execute `pnpm storybook` e navegue para ver exemplos interativos.
+
+## Características Técnicas
+
+- **TypeScript completo** - Tipagem forte em todos os hooks
+- **Responsivo** - Funciona em mobile/desktop
+- **Tema adaptativo** - Dark/light mode automático
+- **Animações suaves** - Transições elegantes
+- **Acessibilidade** - Suporte a screen readers
+- **Performance** - Context otimizado, sem re-renders desnecessários
+- **Modular** - Use só o que precisa
+- **Consistente** - Visual uniforme em toda app
+
+## Próximos Passos
+
+1. **Testar** todos os hooks nas páginas existentes
+2. **Migrar** toasts existentes para Form Alert Modal onde fizer sentido
+3. **Implementar** splash screen se desejado (`autoShow: true`)
+4. **Usar** modais e sheets para menus e formulários
+5. **Aplicar** ProseTypography em conteúdo de blog/docs
+
+## Dicas de Uso
+
+### **Para Formulários:**
+```tsx
+// Loading + Form Alert = UX perfeito
+const { showLoading, hideLoading } = useGlobalLoading();
+const { showAlert } = useFormAlert();
+
+const handleSubmit = async () => {
+  showLoading();
+
+  try {
+    await submitForm();
+    hideLoading();
+
+    showAlert({
+      type: "success",
+      title: "Sucesso!",
+      message: "Formulário processado com sucesso."
+    });
+  } catch (error) {
+    hideLoading();
+
+    showAlert({
+      type: "error",
+      title: "Erro no Envio",
+      message: "Tente novamente em alguns minutos."
+    });
+  }
+};
+```
+
+### **Para Navegação:**
+```tsx
+// Sheet para menu mobile
+const { showSheet } = useSheet();
+
+<Button onClick={() => showSheet({
+  title: "Menu",
+  side: "left",
+  size: "sm",
+  content: <MobileMenu />
+})}>
+  Menu
+</Button>
+```
+
+### **Para Confirmações:**
+```tsx
+// Modal de confirmação elegante
+const { showModal } = useModal();
+
+const handleDelete = () => {
+  showModal({
+    type: "confirm",
+    title: "Excluir imóvel?",
+    description: "Esta ação não poderá ser desfeita.",
+    variant: "destructive",
+    confirmLabel: "Sim, excluir",
+    cancelLabel: "Cancelar",
+    onConfirm: () => {
+      // Lógica de exclusão
+    }
+  });
+};
+```
+
+---
+
+**Parabéns!** Seu app agora tem um sistema completo de componentes globais reutilizáveis, elegantes e performáticos. Tudo configurado e pronto para usar!