forlogic-core 3.0.10 → 4.0.0

package/docs/design-system/inputs.md

@@ -1,561 +0,0 @@
-<!-- ⚠️ 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. |
-| `showCharCount` | `boolean` | false | Exibe contador de caracteres abaixo do input (requer maxLength). |
-| `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.
-- 🎨 **Padrão v2**: Input usa 
--  (8px) e 
--  com 
--  para feedback visual no hover.
-- 🎨 **Padrão v2**: Bordas dos inputs têm contraste aumentado (luminosidade 82% light / 25% dark) para maior realce visual.
-
-> 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
-
-**Notas:**
-- 🎨 **Padrão v2**: Textarea usa 
--  (8px) e 
--  com 
--  para feedback visual no hover.
-
-> 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
-- 🎨 **Padrão v2**: Label usa 
--  (12px) e 
--  para hierarquia visual clara sem competir com o conteúdo do campo.
-
-> 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. O item selecionado é destacado por background (accent), fonte medium e borda esquerda na cor primary. A prop `showCheck` (opcional) adiciona um ícone de check à esquerda do item selecionado.
-
-**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. |
-| `showCheck` | `boolean` | false | Exibe o ícone de check à esquerda do item selecionado. Quando false, o item selecionado é destacado apenas pelo background, fonte medium e borda esquerda primary. |
-| `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 
-- ,
-        
-- rounded-lg
-- hover:border-primary
-- transition-colors
-- ,
-        
-- Combobox
-- showCheck
-
-> 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`
-
----