forlogic-core 3.0.11 → 4.0.0

package/docs/design-system/dialogs.md

@@ -1,590 +0,0 @@
-<!-- ⚠️ 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 |
-| `container` | `HTMLElement | null` | document.body | TooltipContent: Nó-alvo do Portal. O conteúdo é portado por padrão para document.body, evitando clipping em containers com overflow. |
-
-**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
-- TooltipContent é renderizado via Portal (default: document.body), evitando clipping em sidebars, cards com scroll, dialogs e demais containers com overflow. Use a prop opcional container para portar para um nó específico.
-
-> 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`.*
-
----