@etus/ui 0.1.0

package/src/components/feedback/Message/README.md

@@ -0,0 +1,522 @@
+# Message
+
+## Visão Geral
+
+O componente **Message** exibe feedback contextual inline, tipicamente usado em formularios para mostrar erros de validacao, avisos ou mensagens de sucesso associadas a campos especificos. Diferente de Toast e Alert, o Message e posicionado junto ao elemento relacionado.
+
+### Classificacao Atomica
+- **Categoria**: Atoms / Molecules
+- **Subcategoria**: Feedback / Forms
+
+### Casos de Uso Comuns
+- Mensagens de erro de validacao de campo
+- Feedback de sucesso apos acao em campo
+- Avisos sobre formato ou requisitos
+- Dicas contextuais durante preenchimento
+- Status de validacao em tempo real
+
+### Relacao com Outros Componentes
+- **ErrorMessage**: Especializado para erros de formulario
+- **HelpText**: Para texto de ajuda estatico
+- **SuccessMessage**: Especializado para feedback positivo
+- **Alert**: Para mensagens mais proeminentes
+- **Label**: Frequentemente usado junto para formar o campo
+
+## Design Specs
+
+### Variantes
+- **error**: Mensagem de erro (vermelho)
+- **warning**: Aviso importante (amarelo/laranja)
+- **success**: Confirmacao positiva (verde)
+- **info**: Informacao neutra (azul)
+
+### Tamanhos
+- **sm**: `text-xs` - Para mensagens compactas
+- **md**: `text-sm` - Tamanho padrao
+
+### Estados
+- **Default**: Mensagem visivel
+- **Hidden**: Mensagem oculta (condicional)
+- **Animated**: Entrada/saida com animacao
+
+### Tokens de Design
+
+#### Cores
+- Error: `text-destructive` / `text-red-500`
+- Warning: `text-amber-600` / `text-orange-500`
+- Success: `text-green-600` / `text-emerald-500`
+- Info: `text-blue-600` / `text-sky-500`
+- Muted: `text-muted-foreground`
+
+#### Espacamento
+- Margin Top: `mt-1` / `mt-1.5` / `mt-2`
+- Gap com icone: `gap-1` / `gap-1.5`
+
+#### Tipografia
+- Font Size: `text-xs` / `text-sm`
+- Font Weight: `font-normal` / `font-medium`
+
+#### Icones
+- Tamanho: `size-3` / `size-4`
+- Posicao: Inline com texto
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|---------|-----------|
+| `variant` | `'error' \| 'warning' \| 'success' \| 'info'` | `'error'` | Estilo visual |
+| `size` | `'sm' \| 'md'` | `'sm'` | Tamanho do texto |
+| `children` | `ReactNode` | - | Conteudo da mensagem |
+| `icon` | `ReactNode` | Auto por variant | Icone customizado |
+| `showIcon` | `boolean` | `true` | Exibir icone |
+| `id` | `string` | - | ID para associar com aria-describedby |
+| `className` | `string` | `''` | Classes CSS adicionais |
+| `animate` | `boolean` | `false` | Animar entrada/saida |
+| `role` | `string` | `'alert'` para error | Role ARIA |
+
+### Interfaces TypeScript
+
+```typescript
+import { cva, type VariantProps } from 'class-variance-authority'
+
+const messageVariants = cva(
+  'flex items-start gap-1.5 text-sm',
+  {
+    variants: {
+      variant: {
+        error: 'text-destructive',
+        warning: 'text-amber-600 dark:text-amber-500',
+        success: 'text-green-600 dark:text-green-500',
+        info: 'text-blue-600 dark:text-blue-500',
+      },
+      size: {
+        sm: 'text-xs',
+        md: 'text-sm',
+      },
+    },
+    defaultVariants: {
+      variant: 'error',
+      size: 'sm',
+    },
+  }
+)
+
+interface MessageProps
+  extends React.ComponentProps<'p'>,
+    VariantProps<typeof messageVariants> {
+  icon?: React.ReactNode
+  showIcon?: boolean
+  animate?: boolean
+}
+```
+
+### Comparacao com Referencias
+
+| Design System | Variantes | Icones | Animacao |
+|---------------|-----------|--------|----------|
+| **ETUS** | 4 | Opcional | Opcional |
+| Chakra UI | FormErrorMessage | Built-in | Sim |
+| MUI | FormHelperText | Manual | Manual |
+| Ant Design | Form.Item | Built-in | Sim |
+| Mantine | Input.Error | Opcional | Sim |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="alert"`: Para mensagens de erro (anuncio imediato)
+- `aria-live="polite"`: Para outras mensagens
+- `id`: Para associacao via `aria-describedby`
+
+### Uso com Campos
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" aria-describedby="email-error" aria-invalid={!!error} />
+<Message id="email-error" variant="error">{error}</Message>
+```
+
+### Tecnologias Assistivas
+- Screen readers anunciam erros imediatamente
+- Mensagens de sucesso anunciadas de forma polida
+- Associacao com campo via aria-describedby
+
+### Conformidade WCAG
+- 1.3.1 Info and Relationships
+- 3.3.1 Error Identification
+- 4.1.3 Status Messages
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Message } from '@etus/ui'
+
+function BasicMessage() {
+  return (
+    <Message variant="error">
+      Este campo e obrigatorio
+    </Message>
+  )
+}
+```
+
+### Todas as Variantes
+
+```tsx
+import { Message } from '@etus/ui'
+
+function AllVariants() {
+  return (
+    <div className="space-y-2">
+      <Message variant="error">
+        Erro: Formato de email invalido
+      </Message>
+
+      <Message variant="warning">
+        Aviso: Senha fraca
+      </Message>
+
+      <Message variant="success">
+        Sucesso: Username disponivel
+      </Message>
+
+      <Message variant="info">
+        Info: Minimo de 8 caracteres
+      </Message>
+    </div>
+  )
+}
+```
+
+### Com Campo de Formulario
+
+```tsx
+import { Label, Input, Message } from '@etus/ui'
+import { useState } from 'react'
+
+function FieldWithMessage() {
+  const [email, setEmail] = useState('')
+  const [error, setError] = useState('')
+
+  const validate = (value: string) => {
+    if (!value) {
+      setError('Email e obrigatorio')
+    } else if (!value.includes('@')) {
+      setError('Email invalido')
+    } else {
+      setError('')
+    }
+  }
+
+  return (
+    <div className="space-y-1.5">
+      <Label htmlFor="email">Email</Label>
+      <Input
+        id="email"
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        onBlur={() => validate(email)}
+        aria-describedby={error ? 'email-error' : undefined}
+        aria-invalid={!!error}
+        className={error ? 'border-destructive' : ''}
+      />
+      {error && (
+        <Message id="email-error" variant="error">
+          {error}
+        </Message>
+      )}
+    </div>
+  )
+}
+```
+
+### Com Icone Customizado
+
+```tsx
+import { Message } from '@etus/ui'
+import { CircleAlert, CircleCheck } from 'lucide-react'
+
+function CustomIconMessage() {
+  return (
+    <div className="space-y-2">
+      <Message
+        variant="error"
+        icon={<CircleAlert className="size-4" />}
+      >
+        Conexao perdida
+      </Message>
+
+      <Message
+        variant="success"
+        icon={<CircleCheck className="size-4" />}
+      >
+        Dados salvos com sucesso
+      </Message>
+    </div>
+  )
+}
+```
+
+### Sem Icone
+
+```tsx
+import { Message } from '@etus/ui'
+
+function MessageWithoutIcon() {
+  return (
+    <Message variant="info" showIcon={false}>
+      Dica: Use letras e numeros para uma senha forte
+    </Message>
+  )
+}
+```
+
+### Multiplas Mensagens
+
+```tsx
+import { Message } from '@etus/ui'
+
+function MultipleMessages() {
+  const errors = [
+    'Minimo de 8 caracteres',
+    'Pelo menos uma letra maiuscula',
+    'Pelo menos um numero',
+  ]
+
+  return (
+    <div className="space-y-1">
+      {errors.map((error, i) => (
+        <Message key={i} variant="error">
+          {error}
+        </Message>
+      ))}
+    </div>
+  )
+}
+```
+
+### Com Animacao
+
+```tsx
+import { Message } from '@etus/ui'
+import { useState, useEffect } from 'react'
+
+function AnimatedMessage() {
+  const [showSuccess, setShowSuccess] = useState(false)
+
+  const handleSave = async () => {
+    await saveData()
+    setShowSuccess(true)
+    setTimeout(() => setShowSuccess(false), 3000)
+  }
+
+  return (
+    <div>
+      <button onClick={handleSave}>Salvar</button>
+
+      {showSuccess && (
+        <Message
+          variant="success"
+          animate
+          className="animate-in fade-in slide-in-from-top-1"
+        >
+          Salvo com sucesso!
+        </Message>
+      )}
+    </div>
+  )
+}
+```
+
+### Validacao em Tempo Real
+
+```tsx
+import { Label, Input, Message } from '@etus/ui'
+import { useState, useMemo } from 'react'
+
+function RealTimeValidation() {
+  const [password, setPassword] = useState('')
+
+  const validation = useMemo(() => {
+    const rules = [
+      { test: password.length >= 8, message: 'Minimo 8 caracteres' },
+      { test: /[A-Z]/.test(password), message: 'Uma letra maiuscula' },
+      { test: /[0-9]/.test(password), message: 'Um numero' },
+    ]
+    return rules
+  }, [password])
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="password">Senha</Label>
+      <Input
+        id="password"
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+      />
+      <div className="space-y-1">
+        {validation.map((rule, i) => (
+          <Message
+            key={i}
+            variant={rule.test ? 'success' : 'info'}
+            size="sm"
+          >
+            {rule.message}
+          </Message>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+### Integracao com React Hook Form
+
+```tsx
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { Label, Input, Message, Button } from '@etus/ui'
+
+const schema = z.object({
+  email: z.string().email('Email invalido'),
+  name: z.string().min(2, 'Nome muito curto'),
+})
+
+function FormWithMessages() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <div className="space-y-4">
+        <div className="space-y-1.5">
+          <Label htmlFor="name">Nome</Label>
+          <Input
+            id="name"
+            {...register('name')}
+            aria-invalid={!!errors.name}
+          />
+          {errors.name && (
+            <Message variant="error">
+              {errors.name.message}
+            </Message>
+          )}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="email">Email</Label>
+          <Input
+            id="email"
+            {...register('email')}
+            aria-invalid={!!errors.email}
+          />
+          {errors.email && (
+            <Message variant="error">
+              {errors.email.message}
+            </Message>
+          )}
+        </div>
+
+        <Button type="submit">Enviar</Button>
+      </div>
+    </form>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao com diferentes variantes
+- Aplicacao de classes corretas
+- Renderizacao de icone
+- Atributos ARIA corretos
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Message } from './Message'
+
+describe('Message', () => {
+  it('renders children', () => {
+    render(<Message>Error message</Message>)
+    expect(screen.getByText('Error message')).toBeInTheDocument()
+  })
+
+  it('applies error variant by default', () => {
+    render(<Message>Error</Message>)
+    expect(screen.getByText('Error')).toHaveClass('text-destructive')
+  })
+
+  it('applies variant classes correctly', () => {
+    const { rerender } = render(<Message variant="success">Message</Message>)
+    expect(screen.getByText('Message')).toHaveClass('text-green-600')
+
+    rerender(<Message variant="warning">Message</Message>)
+    expect(screen.getByText('Message')).toHaveClass('text-amber-600')
+  })
+
+  it('renders with role alert for error variant', () => {
+    render(<Message variant="error">Error</Message>)
+    expect(screen.getByRole('alert')).toBeInTheDocument()
+  })
+
+  it('hides icon when showIcon is false', () => {
+    render(<Message showIcon={false}>Message</Message>)
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+  })
+
+  it('renders custom icon', () => {
+    render(
+      <Message icon={<span data-testid="custom-icon" />}>
+        Message
+      </Message>
+    )
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+  })
+
+  it('applies size classes', () => {
+    const { rerender } = render(<Message size="sm">Small</Message>)
+    expect(screen.getByText('Small')).toHaveClass('text-xs')
+
+    rerender(<Message size="md">Medium</Message>)
+    expect(screen.getByText('Medium')).toHaveClass('text-sm')
+  })
+
+  it('accepts id for aria-describedby association', () => {
+    render(<Message id="field-error">Error</Message>)
+    expect(screen.getByText('Error')).toHaveAttribute('id', 'field-error')
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Componente simples e leve
+- Variantes via CVA para type-safety
+- Icones contextuais por variant
+- Role ARIA automatico por tipo
+- Compativel com react-hook-form e outros form libs
+
+## Referências
+
+- [WAI-ARIA Forms](https://www.w3.org/WAI/tutorials/forms/)
+- [WCAG Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html)
+- [Chakra UI FormErrorMessage](https://chakra-ui.com/docs/components/form-control)
+- [React Hook Form](https://react-hook-form.com/)

package/src/components/feedback/Message/index.ts

@@ -0,0 +1,2 @@
+export type { MessageProps, MessageSize, MessageVariant } from "./Message.types"
+export { Message, messageVariants } from "./Message"