forlogic-core 2.0.2 → 2.0.4

package/docs/design-system/inputs.md

@@ -0,0 +1,536 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Inputs
+
+Categoria: **Inputs** | 10 componentes
+
+### Input
+
+Campo de entrada de texto com suporte a todos os tipos HTML. Inclui Label para rótulos acessíveis e InputGroup para agrupar inputs com addons de prefixo, sufixo, ícones e botões.
+
+**Uso:**
+```tsx
+import { Input, Label } from "forlogic-core"
+
+// Input básico
+<Input placeholder="Digite algo..." />
+
+// Com Label
+<div className="grid w-full items-center gap-1.5">
+  <Label htmlFor="email">Email</Label>
+  <Input type="email" id="email" placeholder="email@exemplo.com" />
+</div>
+
+// InputGroup com prefixo e sufixo
+import { InputGroup, InputGroupInput, InputGroupAddon, InputGroupButton } from "forlogic-core"
+
+<InputGroup>
+  <InputGroupAddon align="inline-start">https://</InputGroupAddon>
+  <InputGroupInput placeholder="exemplo.com" />
+  <InputGroupAddon align="inline-end">.com.br</InputGroupAddon>
+</InputGroup>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `placeholder` | `string` | - | Texto de placeholder exibido quando o campo está vazio. |
+| `value` | `string | number` | - | Valor controlado do input. |
+| `defaultValue` | `string | number` | - | Valor inicial para input não controlado. |
+| `disabled` | `boolean` | false | Se o input está desabilitado (não editável e não envia no form). |
+| `readOnly` | `boolean` | false | Se o input é somente leitura (não editável mas envia no form). |
+| `required` | `boolean` | false | Se o campo é obrigatório para submissão do formulário. |
+| `maxLength` | `number` | - | Número máximo de caracteres permitidos. |
+| `minLength` | `number` | - | Número mínimo de caracteres necessários. |
+| `pattern` | `string` | - | Regex para validação do valor (HTML5). |
+| `autoComplete` | `string` | - | Dica de autocompletar:  |
+| `autoFocus` | `boolean` | false | Se o input deve receber foco automaticamente ao montar. |
+| `className` | `string` | - | Classes CSS adicionais para customização. |
+| `onChange` | `(e: ChangeEvent) => void` | - | Callback chamado quando o valor muda. |
+| `onBlur` | `(e: FocusEvent) => void` | - | Callback chamado quando o input perde foco. |
+| `onFocus` | `(e: FocusEvent) => void` | - | Callback chamado quando o input recebe foco. |
+
+**Exemplos:**
+```tsx
+<Input type=
+```
+```tsx
+<div className=
+```
+```tsx
+// Normal
+<Input placeholder=
+```
+```tsx
+// Ícone à esquerda
+<div className=
+```
+```tsx
+// Prefixo
+<InputGroup>
+  <InputGroupAddon align=
+```
+```tsx
+// Ícone de usuário
+<InputGroup>
+  <InputGroupAddon align=
+```
+
+**Acessibilidade:**
+- Sempre associe Label ao Input usando htmlFor/id para melhor navegação com leitores de tela
+- Use placeholder como dica adicional, nunca como substituto do Label
+- O estado disabled é comunicado automaticamente para tecnologias assistivas
+- O estado required é comunicado e valida automaticamente no submit
+- InputGroup mantém foco visual unificado (ring) quando qualquer elemento interno está focado
+- Indicadores de foco visíveis atendem WCAG 2.4.7 (Focus Visible)
+- Inputs são totalmente navegáveis via teclado (Tab, Shift+Tab)
+- Para campos de senha, forneça toggle de visibilidade com ícone descritivo
+- Mensagens de erro devem ser associadas ao input via aria-describedby para leitores de tela
+
+**Notas:**
+- **Label**: Componente de rótulo acessível. Use 
+-  para associar ao 
+-  do input.
+- **InputGroup**: Container que agrupa input com addons. Adiciona borda unificada e foco visual compartilhado.
+- **InputGroupInput**: Input estilizado para uso dentro do InputGroup (remove bordas próprias).
+- **InputGroupTextarea**: Textarea estilizado para uso com addons 
+-  ou 
+- .
+- **InputGroupAddon**: Elemento decorativo (texto, ícone). Props: 
+- : 
+-  (prefixo), 
+-  (sufixo), 
+-  (topo), 
+-  (base).
+- **InputGroupButton**: Botão integrado ao InputGroup. Props: 
+- : 
+- , 
+- , 
+- , 
+- . Aceita todas as 
+-  do Button.
+- Para validação de formulários, use react-hook-form com FormField, FormControl e FormMessage.
+- Para estados de erro, adicione as classes 
+-  ao Input.
+
+> Fonte: `src\design-system\docs\components\InputDoc.tsx`
+
+---
+
+### Textarea
+
+Exibe um textarea de formulário ou um componente que se parece com um textarea.
+
+**Uso:**
+```tsx
+import { Textarea } from "forlogic-core"
+
+<Textarea placeholder="Digite sua mensagem aqui." />
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `placeholder` | `string` | - | Texto do placeholder. |
+| `disabled` | `boolean` | false | Se o textarea está desabilitado. |
+| `rows` | `number` | - | Número de linhas de texto visíveis. |
+
+**Exemplos:**
+```tsx
+<Textarea placeholder=
+```
+
+**Acessibilidade:**
+- Elemento HTML textarea padrão
+- Funciona com labels e controles de formulário
+- Acessível por teclado
+- Amigável para leitores de tela
+
+> Fonte: `src\design-system\docs\components\TextareaDoc.tsx`
+
+---
+
+### Checkbox
+
+Um controle que permite ao usuário alternar entre marcado e desmarcado.
+
+**Uso:**
+```tsx
+import { Checkbox } from "forlogic-core"
+
+<div className="flex items-center space-x-2">
+  <Checkbox id="terms" />
+  <label htmlFor="terms">Accept terms and conditions</label>
+</div>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `checked` | `boolean` | false | O estado marcado controlado. |
+| `defaultChecked` | `boolean` | false | O estado marcado padrão. |
+| `disabled` | `boolean` | false | Se o checkbox está desabilitado. |
+| `onCheckedChange` | `(checked: boolean) => void` | - | Manipulador de evento chamado quando o estado marcado muda. |
+
+**Exemplos:**
+```tsx
+<Checkbox id=
+```
+```tsx
+<div className=
+```
+
+**Acessibilidade:**
+- Suporte completo de teclado
+- Segue o padrão de design WAI-ARIA
+- Gerenciamento adequado de foco
+- Funciona com labels de formulário
+
+> Fonte: `src\design-system\docs\components\CheckboxDoc.tsx`
+
+---
+
+### Radio Group
+
+Um conjunto de botões marcáveis—conhecidos como botões de rádio—onde apenas um pode ser marcado por vez.
+
+**Uso:**
+```tsx
+import { RadioGroup, RadioGroupItem } from "forlogic-core"
+
+<RadioGroup defaultValue="option-one">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-one" id="r1" />
+    <Label htmlFor="r1">Option One</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-two" id="r2" />
+    <Label htmlFor="r2">Option Two</Label>
+  </div>
+</RadioGroup>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `defaultValue` | `string` | - | O valor selecionado padrão. |
+| `value` | `string` | - | O valor selecionado controlado. |
+| `onValueChange` | `(value: string) => void` | - | Manipulador de evento quando o valor muda. |
+| `disabled` | `boolean` | false | Se o grupo de rádio está desabilitado. |
+
+**Exemplos:**
+```tsx
+<RadioGroup defaultValue=
+```
+```tsx
+<RadioGroup defaultValue=
+```
+```tsx
+<RadioGroup defaultValue=
+```
+```tsx
+<RadioGroup defaultValue=
+```
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Teclas de seta para selecionar opções
+- Segue o padrão de grupo de rádio WAI-ARIA
+- Gerenciamento adequado de foco
+
+> Fonte: `src\design-system\docs\components\RadioGroupDoc.tsx`
+
+---
+
+### Label
+
+Renderiza uma label acessível associada a controles de formulário.
+
+**Uso:**
+```tsx
+import { Label } from "forlogic-core"
+
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `htmlFor` | `string` | - | O id do controle de formulário para associar. |
+| `className` | `string` | - | Classes CSS para estilização. |
+| `children` | `ReactNode` | - | Conteúdo da label. |
+
+**Exemplos:**
+```tsx
+<div className=
+```
+```tsx
+<Label htmlFor=
+```
+```tsx
+<div className=
+```
+```tsx
+<Label htmlFor=
+```
+```tsx
+<Label htmlFor=
+```
+```tsx
+<div className=
+```
+```tsx
+<div className=
+```
+
+**Acessibilidade:**
+- Associa adequadamente com controles de formulário via htmlFor
+- Clicar na label foca automaticamente o input associado
+- Suporte completo para leitores de tela
+- Compatível com WCAG - melhora a área de clique
+- Use com Checkbox/Radio para melhor UX
+
+**Notas:**
+- Sempre associe Labels a seus campos via htmlFor/id
+- Use o componente Label (não <label>) para formulários acessíveis
+- Indique campos obrigatórios com asterisco ou texto descritivo
+- Labels aumentam a área de clique para inputs (especialmente útil em mobile)
+- Adicione cursor-pointer quando associada a checkboxes/radios
+- Combine com texto de ajuda abaixo do input para instruções adicionais
+
+> Fonte: `src\design-system\docs\components\LabelDoc.tsx`
+
+---
+
+### Slider
+
+Um input onde o usuário seleciona um valor dentro de um intervalo determinado.
+
+**Uso:**
+```tsx
+import { Slider } from "forlogic-core"
+
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+**Acessibilidade:**
+- Suporte completo de teclado (teclas de seta para ajustar)
+- Segue o padrão WAI-ARIA de slider
+- Labels e valores ARIA adequados
+- Indicadores de foco visíveis
+
+> Fonte: `src\design-system\docs\components\SliderDoc.tsx`
+
+---
+
+### File Upload
+
+Componente de upload de arquivo único com drag & drop, validação de tipo/tamanho e ações (download, visualizar, substituir, remover). Portado do flc-single-file-uploader Angular.
+
+**Uso:**
+```tsx
+import { SingleFileUpload } from 'forlogic-core';
+
+<SingleFileUpload
+  storedFile={{ id: '1', name: 'doc.pdf', extension: 'pdf', size: 1024 }}
+  allowedExtensions={['pdf', 'docx']}
+  maxSizeInBytes={10 * 1024 * 1024}
+  onFileSelect={(file) => console.log(file)}
+  onFileRemove={() => console.log('removed')}
+  onDownload={async (f) => downloadFile(f.id)}
+  onView={(f) => openViewer(f.id)}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `storedFile` | `StoredFile | null` | - | Arquivo já armazenado no servidor (id, name, extension, size). |
+| `disabled` | `boolean` | false | Desabilita interação com o componente. |
+| `required` | `boolean` | false | Marca o campo como obrigatório. |
+| `touched` | `boolean` | false | Marca o campo como tocado (exibe erro de required). |
+| `error` | `string` | - | Mensagem de erro externa a ser exibida. |
+
+**Exemplos:**
+```tsx
+<SingleFileUpload
+  onFileSelect={(f) => handleSelect(f)}
+  onFileRemove={() => handleRemove()}
+/>
+```
+```tsx
+<SingleFileUpload
+  storedFile={{ id:
+```
+```tsx
+<SingleFileUpload
+  allowedExtensions={[
+```
+
+**Notas:**
+- Portado do flc-single-file-uploader Angular. Valida tipos proibidos (FORBIDDEN_FILE_TYPES: exe, bat, cmd, etc) automaticamente.
+- Utilitários exportados: formatBytes(bytes) e getFileExtension(filename).
+- O componente gerencia estados internos de arquivo local vs servidor (StoredFile).
+- Tipos proibidos são bloqueados automaticamente independente da prop allowedExtensions.
+
+> Fonte: `src\design-system\docs\components\FileUploadDoc.tsx`
+
+---
+
+### Select
+
+Exibe uma lista de opções para o usuário escolher—acionada por um botão.
+
+**Uso:**
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "forlogic-core"
+
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `defaultValue` | `string` | - | O valor selecionado padrão. |
+| `value` | `string` | - | O valor selecionado controlado. |
+| `onValueChange` | `(value: string) => void` | - | Manipulador de evento quando o valor muda. |
+| `disabled` | `boolean` | false | Se o select está desabilitado. |
+| `container (SelectContent)` | `HTMLElement` | - | Container HTML para portal (útil dentro de Dialog). |
+| `collisionBoundary (SelectContent)` | `HTMLElement` | - | Elemento para detecção de colisão de posicionamento. |
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Busca por digitação antecipada
+- Segue o padrão de listbox WAI-ARIA
+- Anúncios para leitores de tela
+
+**Notas:**
+- 💡 Use 
+-  e 
+-  quando o Select estiver dentro de um Dialog para evitar problemas de scroll
+- 💡 Para seleção com busca, considere usar 
+-  ao invés de 
+
+> Fonte: `src\design-system\docs\components\SelectDoc.tsx`
+
+---
+
+### Rich Text Editor
+
+Editor de texto rico construído com Tiptap, suportando formatação visual, edição de código HTML e preview. Ideal para formulários que precisam de conteúdo formatado.
+
+**Uso:**
+```tsx
+import { RichTextEditor } from "forlogic-core"
+
+const [content, setContent] = useState('')
+
+<RichTextEditor
+  value={content}
+  onChange={setContent}
+  placeholder="Escreva algo aqui..."
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | - | Conteúdo HTML atual do editor. |
+| `onChange` | `(value: string) => void` | - | Callback chamado quando o conteúdo muda. |
+| `disabled` | `boolean` | false | Desabilita a edição. |
+| `showModeToggle` | `boolean` | true | Mostra botões de alternância Visual/Código/Preview. |
+| `showVariableHint` | `boolean` | true | Mostra dica sobre uso de variáveis {{variavel}}. |
+| `className` | `string` | - | Classes CSS adicionais para o container. |
+
+**Exemplos:**
+```tsx
+<RichTextEditor
+  value={content}
+  onChange={setContent}
+  showVariableHint={false}
+  placeholder=
+```
+```tsx
+<RichTextEditor
+  value={content}
+  onChange={setContent}
+  showModeToggle={false}
+  showVariableHint={false}
+  minHeight=
+```
+```tsx
+<RichTextEditor
+  value={content}
+  onChange={setContent}
+  disabled
+/>
+```
+
+**Acessibilidade:**
+- Toolbar com botões acessíveis via teclado
+- Títulos com atributos title para tooltips
+- Suporte a atalhos de teclado (Ctrl+B, Ctrl+I, etc.)
+- Contraste adequado nos estados ativo/inativo
+- Focus visível em todos os elementos interativos
+
+> Fonte: `src\design-system\docs\components\RichTextEditorDoc.tsx`
+
+---
+
+### Custom Form Fields
+
+Componente container que renderiza campos de formulário dinâmicos baseados em configuração. Suporta 9 tipos de campo: Texto Somente Leitura, Texto, Data, Hora, URL, Numérico, Seleção Única, Seleção Múltipla e Questões. Portado de FlcCustomFormFieldsComponent (flc-custom-form-fields).
+
+**Uso:**
+```tsx
+import { CustomFormFields, ECustomFormFieldType, validateFields } from "forlogic-core"
+import type { FieldAssociation } from "forlogic-core"
+
+const fields: FieldAssociation[] = [
+  {
+    id: 'f1',
+    type: ECustomFormFieldType.text,
+    name: 'Nome',
+    required: true,
+    config: { multiline: false },
+    isActive: true,
+  },
+  // ...mais campos
+];
+
+const [formFields, setFormFields] = useState(fields);
+
+<CustomFormFields
+  fields={formFields}
+  onChange={setFormFields}
+  onFieldChange={(field) => console.log('Changed:', field)}
+/>
+```
+
+**Notas:**
+- Portado de FlcCustomFormFieldsComponent (flc-custom-form-fields) Angular.
+- Tipos de campo: readOnlyText (1), text (2), date (3), time (4), url (5), number (6), singleSelection (7), multiSelection (8), questions (9).
+- Use validateFields() para validar campos obrigatórios e restrições numéricas.
+- Use getFormFieldValues() para extrair valores no formato de envio ao backend.
+- Use setFormFieldValues() para aplicar valores salvos a uma lista de campos.
+- Campos de seleção suportam dataSource custom (dados estáticos) e users (lista de usuários do sistema).
+
+> Fonte: `src\design-system\docs\components\CustomFormFieldsDoc.tsx`
+
+---