forlogic-core 2.0.3 → 2.0.5

package/docs/design-system/dialogs.md

@@ -0,0 +1,588 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Dialogs
+
+Categoria: **Dialogs** | 11 componentes
+
+### ModulesDialog
+
+Dialog para navegação entre módulos do sistema.
+
+**Uso:**
+```tsx
+import { useState } from 'react';
+import { Button, ModulesDialog } from 'forlogic-core';
+import { LayoutGrid } from 'lucide-react';
+
+function App() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>
+        <LayoutGrid className="h-4 w-4 mr-2" />
+        Módulos
+      </Button>
+
+      <ModulesDialog
+        open={open}
+        onOpenChange={setOpen}
+        onModuleClick={(module) => console.log(module)}
+      />
+    </>
+  );
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `open` | `boolean` | - | Controla se o dialog está aberto |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando o estado muda |
+| `onModuleClick` | `(module: Module) => void` | - | Callback ao clicar em um módulo. Default: navega via URL do módulo |
+| `educaUrl` | `string` | https://educa.forlogic.net/ | URL do link do Forlogic Educa |
+| `saberGestaoUrl` | `string` | https://sabergestao.com.br/ | URL do link do Saber Gestão |
+
+**Acessibilidade:**
+- Dialog acessível com role=
+-  e aria-modal=
+- ,
+          
+- ,
+          
+- ,
+          
+
+**Notas:**
+- Para separação entre módulos contratados e disponíveis (contractedModules, onModuleInterest), consulte a documentação de Module Access.
+- Internamente usa o componente ModulesContent, compartilhado com o AccessDeniedDialog.
+- 2 Abas de Grupos: Qualiex e Clássicos
+- Grid Responsivo: 4 colunas em XL, 3 em MD, 2 em base
+- Cards no Rodapé: Forlogic Educa, Saber Gestão e Wiki
+
+> Fonte: `src\design-system\docs\components\ModulesDialogDoc.tsx`
+
+---
+
+### Alert
+
+Exibe uma mensagem de destaque para chamar a atenção do usuário. O componente inclui ícone automático baseado na variante.
+
+**Uso:**
+```tsx
+import { Alert, AlertDescription, AlertTitle } from "forlogic-core"
+
+<Alert variant="info">
+  <AlertTitle>Informação</AlertTitle>
+  <AlertDescription>
+    Esta é uma mensagem informativa para o usuário.
+  </AlertDescription>
+</Alert>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `showIcon` | `boolean` | true | Se deve exibir o ícone padrão da variante. |
+| `className` | `string` | - | Classes CSS adicionais. |
+
+**Exemplos:**
+```tsx
+<Alert variant=
+```
+```tsx
+<Alert variant=
+```
+```tsx
+<Alert variant=
+```
+```tsx
+<Alert variant=
+```
+```tsx
+<Alert variant=
+```
+
+**Acessibilidade:**
+- Usa role=
+-  para anunciar automaticamente aos leitores de tela
+- A cor não é o único meio de transmitir informações - ícones fornecem contexto adicional
+- Estrutura HTML semântica com título e descrição claramente definidos
+- Contraste de cores adequado para acessibilidade visual
+
+> Fonte: `src\design-system\docs\components\AlertDoc.tsx`
+
+---
+
+### Card
+
+Exibe um card com cabeçalho, conteúdo e rodapé.
+
+**Uso:**
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "forlogic-core"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card Content</p>
+  </CardContent>
+  <CardFooter>
+    <p>Card Footer</p>
+  </CardFooter>
+</Card>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais para o card. |
+
+**Acessibilidade:**
+- Estrutura semântica com elementos apropriados
+- Hierarquia de cabeçalhos adequada
+- Contraste de cores acessível
+- Funciona com leitores de tela
+
+> Fonte: `src\design-system\docs\components\CardDoc.tsx`
+
+---
+
+### Popover
+
+Exibe conteúdo rico em um portal, acionado por um botão.
+
+**Uso:**
+```tsx
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Button,
+  Input,
+  Label
+} from 'forlogic-core';
+
+function DimensionsPopover() {
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Abrir popover</Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-80">
+        <div className="grid gap-4">
+          <div className="space-y-2">
+            <h4 className="font-medium leading-none">Dimensões</h4>
+            <p className="text-sm text-muted-foreground">
+              Defina as dimensões para a camada.
+            </p>
+          </div>
+          <div className="grid gap-2">
+            <div className="grid grid-cols-3 items-center gap-4">
+              <Label htmlFor="width">Largura</Label>
+              <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
+            </div>
+            <div className="grid grid-cols-3 items-center gap-4">
+              <Label htmlFor="maxWidth">Máx. largura</Label>
+              <Input id="maxWidth" defaultValue="300px" className="col-span-2 h-8" />
+            </div>
+            <div className="grid grid-cols-3 items-center gap-4">
+              <Label htmlFor="height">Altura</Label>
+              <Input id="height" defaultValue="25px" className="col-span-2 h-8" />
+            </div>
+            <div className="grid grid-cols-3 items-center gap-4">
+              <Label htmlFor="maxHeight">Máx. altura</Label>
+              <Input id="maxHeight" defaultValue="none" className="col-span-2 h-8" />
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `defaultOpen` | `boolean` | false | Estado aberto inicial (não controlado). |
+| `open` | `boolean` | - | Estado aberto controlado. |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando o estado muda. |
+| `modal` | `boolean` | false | Define comportamento modal (bloqueia interação externa). |
+| `asChild (Trigger)` | `boolean` | false | Mescla props com o elemento filho. |
+| `sideOffset` | `number` | 4 | Distância em pixels do trigger. |
+| `alignOffset` | `number` | 0 | Deslocamento do alinhamento em pixels. |
+| `avoidCollisions` | `boolean` | true | Evita colisões com bordas da viewport. |
+| `collisionPadding` | `number | Padding` | 0 | Espaçamento da borda de colisão. |
+| `hideWhenDetached` | `boolean` | false | Oculta quando desconectado do trigger. |
+| `container` | `HTMLElement | null` | document.body | Container do portal. |
+
+**Acessibilidade:**
+- Segue o padrão WAI-ARIA Dialog (non-modal).
+- Enter/Space: Abre/fecha o popover quando o trigger está focado.
+- Escape: Fecha o popover e retorna o foco ao trigger.
+- Tab: Navega entre elementos focáveis dentro do popover.
+- Foco é automaticamente movido para o conteúdo ao abrir.
+- Foco retorna ao trigger ao fechar.
+- Atributos ARIA: aria-expanded, aria-haspopup.
+- Data attributes: [data-state], [data-side], [data-align].
+
+**Notas:**
+- Use Popover para exibir conteúdo rico como formulários, detalhes ou ações secundárias.
+- Prefira Dialog para conteúdo que requer atenção total do usuário.
+- O prop asChild permite usar qualquer elemento como trigger.
+- Combine com formulários para edição inline de campos.
+
+> Fonte: `src\design-system\docs\components\PopoverDoc.tsx`
+
+---
+
+### Tooltip
+
+Um popup que exibe informações relacionadas a um elemento quando o elemento recebe foco do teclado ou o mouse passa sobre ele.
+
+**Uso:**
+```tsx
+import { 
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from 'forlogic-core';
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="outline">Hover</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Adicionar à biblioteca</p>
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `delayDuration` | `number` | 300 | TooltipProvider: Atraso em ms antes de exibir o tooltip |
+| `skipDelayDuration` | `number` | 300 | TooltipProvider: Tempo para pular o delay ao mover entre tooltips |
+| `disableHoverableContent` | `boolean` | false | TooltipProvider: Impede que o conteúdo permaneça aberto ao passar o mouse |
+| `open` | `boolean` | - | Tooltip: Estado controlado de abertura |
+| `defaultOpen` | `boolean` | false | Tooltip: Estado inicial (não controlado) |
+| `onOpenChange` | `(open: boolean) => void` | - | Tooltip: Callback quando o estado muda |
+| `sideOffset` | `number` | 4 | TooltipContent: Distância em pixels do trigger |
+| `alignOffset` | `number` | 0 | TooltipContent: Offset do alinhamento em pixels |
+
+**Exemplos:**
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Info className=
+```
+```tsx
+<TooltipContent side=
+```
+```tsx
+// Sem delay
+<TooltipProvider delayDuration={0}>
+  <Tooltip>...</Tooltip>
+</TooltipProvider>
+
+// Delay de 1 segundo
+<TooltipProvider delayDuration={1000}>
+  <Tooltip>...</Tooltip>
+</TooltipProvider>
+```
+```tsx
+// Provider compartilhado - mover entre tooltips é instantâneo
+<TooltipProvider delayDuration={100} skipDelayDuration={0}>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant=
+```
+```tsx
+<TooltipContent className=
+```
+
+**Acessibilidade:**
+- Exibido ao focar no elemento trigger via teclado
+- Fechado automaticamente ao pressionar Escape
+- role=
+-  aplicado automaticamente
+- Associação via aria-describedby
+- Não depende apenas de hover (acessível via focus)
+
+**Notas:**
+- Use TooltipProvider como wrapper para compartilhar delays entre tooltips
+- Prefira Tooltip para dicas curtas, use Popover para conteúdo interativo
+- Evite tooltips em elementos que requerem ação rápida (botões principais)
+- Combine com ícones de informação para ajuda contextual
+- Use delayDuration={0} para exibição instantânea quando necessário
+
+> Fonte: `src\design-system\docs\components\TooltipDoc.tsx`
+
+---
+
+### Media
+
+Módulo completo para upload, edição e renderização de imagens e vídeos. Inclui editores interativos, renderizadores otimizados e hook genérico de upload.
+
+**Uso:**
+```tsx
+// Exemplo básico de upload de imagem
+const { upload, uploading, progress } = useMediaUpload({
+  uploadFunction: async (file, options) => {
+    // Implementação do upload para seu storage
+    const url = await uploadToStorage(file, options);
+    return { url, path: file.name };
+  }
+});
+
+// Renderizar uma imagem
+<ImageRenderer
+  content={{
+    imageUrl: 'https://example.com/image.jpg',
+    caption: 'Legenda da imagem',
+    alignment: 'center'
+  }}
+/>
+
+// Renderizar um vídeo
+<VideoRenderer
+  content={{
+    videoUrl: 'https://youtube.com/watch?v=...',
+    controls: true
+  }}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `uploadFunction` | `UploadFunction` | - | Função de upload customizada (obrigatória para uploads) |
+| `deleteFunction` | `DeleteFunction` | - | Função de delete customizada |
+| `defaultOptions` | `UploadOptions` | - | Opções padrão: bucket, maxSize, allowedTypes |
+| `onSuccess` | `(result: UploadResult) => void` | - | Callback executado após upload bem-sucedido |
+| `onError` | `(error: Error) => void` | - | Callback executado em caso de erro |
+| `value` | `ImageBlockContent | VideoBlockContent` | - | Valor atual do conteúdo |
+| `onChange` | `(value) => void` | - | Callback para mudanças no conteúdo |
+| `onSubmit` | `(value) => void` | - | Callback ao salvar o conteúdo |
+| `onCancel` | `() => void` | - | Callback ao cancelar edição |
+| `uploadOptions` | `UploadOptions` | - | Opções de upload específicas para o editor |
+| `content` | `ImageBlockContent | VideoBlockContent` | - | Conteúdo a ser renderizado |
+| `className` | `string` | - | Classes CSS adicionais |
+| `style` | `CSSProperties` | - | Estilos inline adicionais |
+
+**Exemplos:**
+```tsx
+import { useMediaUpload, getSupabaseClient } from
+```
+
+**Acessibilidade:**
+- ImageRenderer inclui atributo alt obrigatório para acessibilidade
+- VideoRenderer usa atributo title no iframe para identificação
+- Controles de vídeo habilitados por padrão para navegação por teclado
+- Autoplay sempre acompanhado de muted para conformidade com navegadores
+- Links de download possuem texto descritivo
+- Todos os inputs dos editores possuem labels associados
+
+**Notas:**
+- O hook useMediaUpload requer que o projeto forneça as funções de upload/delete
+- A função uploadFunction deve retornar { url: string, path?: string }
+- VideoRenderer detecta automaticamente YouTube e Vimeo pela URL
+- Para vídeos locais, use o player HTML5 nativo com controles
+- Dimensões são opcionais; imagens usam max-width: 100% por padrão
+- O módulo não inclui implementação de storage - use Supabase, S3, etc.
+- Helpers de imagem usam Canvas API para compressão e resize
+
+> Fonte: `src\design-system\docs\components\MediaDoc.tsx`
+
+---
+
+### ModulesDialog
+
+Dialog para navegação entre módulos do sistema.
+
+**Uso:**
+```tsx
+import { useState } from 'react';
+import { Button, ModulesDialog } from 'forlogic-core';
+import { LayoutGrid } from 'lucide-react';
+
+function App() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>
+        <LayoutGrid className="h-4 w-4 mr-2" />
+        Módulos
+      </Button>
+
+      <ModulesDialog
+        open={open}
+        onOpenChange={setOpen}
+        onModuleClick={(module) => console.log(module)}
+      />
+    </>
+  );
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `open` | `boolean` | - | Controla se o dialog está aberto |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando o estado muda |
+| `onModuleClick` | `(module: Module) => void` | - | Callback ao clicar em um módulo. Default: navega via URL do módulo |
+| `educaUrl` | `string` | https://educa.forlogic.net/ | URL do link do Forlogic Educa |
+| `saberGestaoUrl` | `string` | https://sabergestao.com.br/ | URL do link do Saber Gestão |
+
+**Acessibilidade:**
+- Dialog acessível com role=
+-  e aria-modal=
+- ,
+          
+- ,
+          
+- ,
+          
+
+**Notas:**
+- Para separação entre módulos contratados e disponíveis (contractedModules, onModuleInterest), consulte a documentação de Module Access.
+- Internamente usa o componente ModulesContent, compartilhado com o AccessDeniedDialog.
+- 2 Abas de Grupos: Qualiex e Clássicos
+- Grid Responsivo: 4 colunas em XL, 3 em MD, 2 em base
+- Cards no Rodapé: Forlogic Educa, Saber Gestão e Wiki
+
+> Fonte: `src\design-system\docs\components\ModulesDialogDoc.tsx`
+
+---
+
+### Onboarding Dialog
+
+Componente para fluxos de onboarding em múltiplos passos. Suporta imagens estáticas, GIFs, navegação entre steps e indicador de progresso com dropdown.
+
+**Uso:**
+```tsx
+import { useState } from "react";
+import { OnboardingDialog, OnboardingStep, Button } from "forlogic-core";
+
+function App() {
+  const [open, setOpen] = useState(false);
+
+  const steps: OnboardingStep[] = [
+    {
+      id: "welcome",
+      title: "Bem-vindo ao Sistema",
+      description: "Neste espaço, você irá adicionar o texto que explica o processo de onboarding.",
+    },
+    {
+      id: "features",
+      title: "Conheça as Funcionalidades",
+      description: "Descubra todas as ferramentas disponíveis para você.",
+    },
+    {
+      id: "start",
+      title: "Comece Agora",
+      description: "Você está pronto para começar a usar o sistema!",
+    },
+  ];
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Iniciar Onboarding</Button>
+      <OnboardingDialog
+        open={open}
+        onOpenChange={setOpen}
+        steps={steps}
+        onComplete={() => console.log("Onboarding concluído!")}
+      />
+    </>
+  );
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `open` | `boolean` | - | Controla se o dialog está aberto. (obrigatório) |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback quando o estado de aberto muda. (obrigatório) |
+
+**Acessibilidade:**
+- O dialog usa os padrões de acessibilidade do Radix UI Dialog.
+- O botão de fechar possui sr-only label.
+- Navegação por teclado suportada (Tab, Escape).
+- Focus trap ativo quando o dialog está aberto.
+
+**Notas:**
+- O componente suporta tanto imagens estáticas quanto GIFs animados.
+- Use o modo controlado (currentStepIndex + onCurrentStepChange) quando precisar sincronizar o estado com outros componentes.
+- Os textos dos botões são customizáveis para suporte a i18n.
+- Para anúncios de features, use com um único step e showProgressIndicator={false}.
+- O botão 
+-  só aparece a partir do segundo step.
+
+> Fonte: `src\design-system\docs\components\OnboardingDialogDoc.tsx`
+
+---
+
+### Online Editor Dialog
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Terms of Use
+
+Componentes para exibir e gerenciar termos de uso. Inclui TermsOfUseDialog (notificação de termos atualizados) e TermsOfUseViewer (visualização full-screen do documento com opção de assinatura).
+
+**Uso:**
+```tsx
+import { TermsOfUseDialog, TermsOfUseViewer } from 'forlogic-core';
+
+// Dialog de notificação
+<TermsOfUseDialog
+  term={term}
+  open={open}
+  onClose={() => setOpen(false)}
+  onAgree={(termId) => handleAgree(termId)}
+/>
+
+// Viewer full-screen
+<TermsOfUseViewer
+  term={term}
+  open={open}
+  onClose={() => setOpen(false)}
+  onSign={(termId) => handleSign(termId)}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `term` | `TermOfUse` | - | Termo a exibir (id, description, file, type, hasUserSignature) |
+| `open` | `boolean` | - | Controla visibilidade |
+| `onClose` | `() => void` | - | Callback ao fechar |
+| `onAgree` | `(termId) => void` | - | Callback ao concordar (TermsOfUseDialog) |
+| `onSign` | `(termId) => void` | - | Callback ao assinar (TermsOfUseViewer) |
+| `viewOnly` | `boolean` | false | Oculta botão de assinatura (TermsOfUseViewer) |
+
+**Notas:**
+- TermsOfUseViewer oculta botão automaticamente quando hasUserSignature=true
+
+> Fonte: `src\design-system\docs\components\TermsOfUseDoc.tsx`
+
+---
+
+### Viewer Dialog
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---