@xjur-ui/react 3.1.2 → 4.0.0

package/CHANGELOG.md

@@ -1,16 +1,1485 @@
 # @xjur-ui/react
 
-## 3.1.2
+## 4.0.0
 
-### Patch Changes
+### Major Changes
+
+- 07e5bf1: # Migração de OTPInput para PinInput + Novo Componente Message
+
+  Esta release inclui duas mudanças importantes:
+  1. **BREAKING CHANGE**: Migração do componente OTPInput para PinInput com arquitetura composicional
+  2. **NEW FEATURE**: Adição do componente Message para feedback e notificações
+
+  ***
+
+  ## 1. Migração de OTPInput para PinInput com arquitetura composicional
+
+  ## Breaking Changes
+
+  **BREAKING CHANGE**: O componente `OTPInput` foi completamente substituído pelo novo componente `PinInput` com arquitetura composicional moderna.
+
+  ### Migração Necessária
+
+  #### Antes (OTPInput - Depreciado)
+
+  ```tsx
+  import {
+    OTPInputRoot,
+    OTPInputTrigger,
+    OTPInputInput,
+    OTPInputCaption,
+    OTPInputHiddenInput
+  } from '@xjur-ui/react/otp-input'
+
+  ;<OTPInputRoot state="normal" length={4} initial="1234">
+    <OTPInputTrigger>
+      <OTPInputInput index={0} />
+      <OTPInputInput index={1} />
+      <OTPInputInput index={2} />
+      <OTPInputInput index={3} />
+    </OTPInputTrigger>
+    <OTPInputCaption>Digite o código</OTPInputCaption>
+    <OTPInputHiddenInput name="code" />
+  </OTPInputRoot>
+  ```
+
+  #### Depois (PinInput - Novo)
+
+  ```tsx
+  import {
+    PinInput,
+    PinInputControl,
+    PinInputTrigger,
+    PinInputCaption
+  } from '@xjur-ui/react/pin-input'
+
+  ;<PinInput state="normal" length={4} defaultValue="1234" name="code">
+    <PinInputTrigger>
+      <PinInputControl index={0} />
+      <PinInputControl index={1} />
+      <PinInputControl index={2} />
+      <PinInputControl index={3} />
+    </PinInputTrigger>
+    <PinInputCaption>Digite o código</PinInputCaption>
+  </PinInput>
+  ```
+
+  ### Principais Mudanças na API
+
+  | OTPInput (Antigo)     | PinInput (Novo)                          | Notas                                      |
+  | --------------------- | ---------------------------------------- | ------------------------------------------ |
+  | `OTPInputRoot`        | `PinInput`                               | Renomeado para seguir padrão composicional |
+  | `OTPInputInput`       | `PinInputControl`                        | Nome mais descritivo                       |
+  | `initial` prop        | `defaultValue` prop                      | API mais consistente com React             |
+  | `OTPInputHiddenInput` | Campo automático via prop `name`         | Simplificado                               |
+  | Sem callbacks         | `onChangeValue`, `onComplete`, `onError` | Maior controle                             |
+  | Sem auto-submit       | `autoSubmit` prop                        | Nova funcionalidade                        |
+  | Sem placeholder       | `placeholder` prop                       | Melhoria UX                                |
+
+  ## Novas Funcionalidades
+
+  ### 1. Auto-Submit de Formulários
+
+  ```tsx
+  <PinInput autoSubmit={true} name="code" onError={handleError}>
+    {/* Submete automaticamente quando completo */}
+  </PinInput>
+  ```
+
+  ### 2. Placeholder Posicional
+
+  ```tsx
+  <PinInput placeholder="0000">{/* Mostra "0" em cada campo vazio */}</PinInput>
+  ```
+
+  ### 3. Callbacks Detalhados
+
+  ```tsx
+  <PinInput
+    onChangeValue={(value) => console.log('Valor:', value)}
+    onComplete={(value) => console.log('Completo:', value)}
+    onError={(error) => console.error('Erro:', error)}
+  >
+  ```
+
+  ### 4. Hidden Input Automático
+
+  ```tsx
+  <PinInput name="verification_code">
+    {/* Cria automaticamente <input type="hidden" name="verification_code" /> */}
+  </PinInput>
+  ```
+
+  ### 5. Colagem Inteligente de Código
+  - Detecta quando usuário cola código completo
+  - Distribui automaticamente pelos campos
+  - Valida todos os caracteres contra padrão regex
+
+  ### 6. Validação Customizada por Campo
+
+  ```tsx
+  <PinInputControl pattern="[A-Z0-9]" inputMode="text" />
+  ```
+
+  ## Melhorias de Performance
+  - **Context memoizado**: Reduz re-renders desnecessários
+  - **Callbacks estáveis**: `useCallback` para `setCodeAt` e `registerInput`
+  - **Refs otimizadas**: Mantém referências sem causar re-renders
+  - **Validação lazy**: Regex compilado apenas quando necessário
+
+  ## Melhorias de Acessibilidade
+  - `autoComplete="one-time-code"`: Melhor experiência em dispositivos móveis
+  - `inputMode="numeric"`: Exibe teclado numérico automaticamente
+  - Navegação por teclado completa (setas, backspace, tab)
+  - Estados visuais claros (normal, error, disabled)
+  - Suporte completo a leitores de tela
+
+  ## Melhorias de DX (Developer Experience)
+  - **TypeScript completo**: Tipos exportados e documentados
+  - **Hook de contexto**: `usePinInputContext()` para componentes customizados
+  - **Documentação**: README.md detalhado com exemplos práticos
+  - **Stories**: 9 exemplos no Storybook cobrindo todos os casos de uso
+  - **Tratamento de erros**: Callback `onError` para debugging
+
+  ## Arquivos Criados
+  - `packages/react/src/components/controls/pin-input/pin-input-root.tsx`
+  - `packages/react/src/components/controls/pin-input/pin-input-control.tsx`
+  - `packages/react/src/components/controls/pin-input/pin-input-trigger.tsx`
+  - `packages/react/src/components/controls/pin-input/pin-input-caption.tsx`
+  - `packages/react/src/components/controls/pin-input/index.ts`
+  - `packages/react/src/components/controls/pin-input/README.md`
+
+  ## Arquivos Removidos
+  - `packages/react/src/components/controls/otp-input.tsx`
+  - `apps/docs/src/components/otp-input.stories.tsx`
+
+  ## Arquivos Criados/Atualizados (Documentação)
+  - `apps/docs/src/components/pin-input.stories.tsx` - 9 stories interativas:
+    - **Playground**: Exemplo básico com controles interativos
+    - **SixDigits**: OTP de 6 dígitos
+    - **Error**: Estado de erro com validação
+    - **Disabled**: Estado desabilitado
+    - **AutoSubmit**: Submissão automática de formulário
+    - **WithDefaultValue**: Valor inicial pré-preenchido
+    - **Alphanumeric**: Validação customizada alfanumérica
+    - **WithMonitoring**: Monitoramento em tempo real
+    - **TwoFactorAuth**: Fluxo completo de autenticação 2FA
+
+  ## Casos de Uso Suportados
+  1. ✅ Verificação de Email/SMS (OTP de 6 dígitos)
+  2. ✅ Autenticação de Dois Fatores (2FA)
+  3. ✅ PIN de Segurança (4 dígitos)
+  4. ✅ Código de Ativação (alfanumérico)
+  5. ✅ Verificação de Pagamento
+  6. ✅ Reset de Senha
+  7. ✅ Confirmação de Transação
+
+  ## Guia de Migração Detalhado
+
+  ### Passo 1: Atualizar Imports
+
+  ```diff
+  - import { OTPInputRoot, OTPInputTrigger, OTPInputInput, OTPInputCaption } from '@xjur-ui/react/otp-input'
+  + import { PinInput, PinInputTrigger, PinInputControl, PinInputCaption } from '@xjur-ui/react/pin-input'
+  ```
+
+  ### Passo 2: Renomear Componentes
+
+  ```diff
+  - <OTPInputRoot state="normal" length={4} initial="1234">
+  + <PinInput state="normal" length={4} defaultValue="1234" name="code">
+      <OTPInputTrigger>
+  -     <OTPInputInput index={0} />
+  +     <PinInputControl index={0} />
+      </OTPInputTrigger>
+  -   <OTPInputHiddenInput name="code" />
+    </PinInput>
+  ```
+
+  ### Passo 3: Adicionar Callbacks (Opcional)
+
+  ```tsx
+  <PinInput
+    onComplete={(code) => {
+      // Código completo digitado
+      verifyCode(code)
+    }}
+    onChangeValue={(value) => {
+      // Cada alteração
+      console.log('Valor:', value)
+    }}
+  >
+  ```
+
+  ### Passo 4: Habilitar Auto-Submit (Opcional)
+
+  ```tsx
+  <form onSubmit={handleSubmit}>
+    <PinInput autoSubmit={true} name="code">
+      {/* Submete automaticamente ao completar */}
+    </PinInput>
+  </form>
+  ```
+
+  ## Compatibilidade
+  - ✅ React 19.1.1+
+  - ✅ TypeScript 5.x
+  - ✅ Tailwind CSS 4.x
+  - ✅ Navegadores modernos (Chrome, Firefox, Safari, Edge)
+  - ✅ Dispositivos móveis (iOS Safari, Chrome Mobile)
+
+  ## Próximos Passos
+
+  Após esta atualização, recomendamos:
+  1. **Testar fluxos de autenticação**: Verifique todos os fluxos que usavam OTPInput
+  2. **Revisar validações**: Configure validações customizadas se necessário
+  3. **Implementar auto-submit**: Aproveite a nova funcionalidade para melhor UX
+  4. **Adicionar tratamento de erros**: Use o callback `onError` para debugging
+
+  ## Suporte
+
+  Para dúvidas ou problemas com a migração, consulte:
+  - 📖 README.md completo em `packages/react/src/components/controls/pin-input/README.md`
+  - 📚 9 exemplos interativos no Storybook
+  - 🔍 TypeScript types para autocomplete e documentação inline
+
+  ***
+
+  ## 2. Novo Componente Message
+
+  ### Visão Geral
+
+  O **Message** é um novo componente composicional para exibir mensagens e notificações contextuais aos usuários. Perfeito para feedbacks de ações, alertas, avisos e mensagens de sucesso.
+
+  ### Características Principais
+
+  #### Arquitetura Composicional
+  - **MessageRoot**: Container principal com controle de variante e modo de exibição
+  - **MessageIcon**: Ícone automático baseado na variante (success, neutral, warning, error)
+  - **MessageText**: Componente de texto com truncate automático
+  - **MessageClose**: Botão de fechamento que remove o elemento do DOM
+
+  #### Variantes Visuais
+
+  | Variante | Ícone   | Cor      | Uso                                 |
+  | -------- | ------- | -------- | ----------------------------------- |
+  | success  | check   | Verde    | Confirmações de ações bem-sucedidas |
+  | neutral  | info    | Cinza    | Informações gerais                  |
+  | warning  | warning | Amarelo  | Avisos que requerem atenção         |
+  | error    | error   | Vermelho | Erros e problemas críticos          |
+
+  #### Modos de Apresentação
+
+  **Full-Width (Padrão)**
+  - Largura total do container
+  - Ícone visível à esquerda
+  - Borda colorida de 4px à esquerda
+  - Padding generoso
+  - Ideal para mensagens de sistema
+
+  **Inline (Compacto)**
+  - Largura ajustada ao conteúdo (w-fit)
+  - Sem ícone
+  - Sem borda lateral
+  - Padding compacto
+  - Ideal para mensagens próximas a campos
+
+  ### API do Componente
+
+  #### MessageRoot Props
+
+  ```tsx
+  interface MessageRootProps {
+    variant?: 'success' | 'neutral' | 'warning' | 'error' // Padrão: 'neutral'
+    inline?: boolean // Padrão: false
+    children: React.ReactNode
+    // + todas as props de HTMLDivElement
+  }
+  ```
+
+  #### MessageIcon
+  - Renderiza automaticamente o ícone apropriado
+  - Não é exibido quando `inline={true}`
+  - Sem props customizáveis
+
+  #### MessageText
+  - Wrapper do Typography com truncate automático
+  - Aceita todas as props do Typography
+  - Herda cor do contexto da mensagem
+
+  #### MessageClose
+  - Botão que remove a mensagem do DOM
+  - Renderiza ícone "close" por padrão
+  - Aceita children customizados
+  - Aceita todas as props de `<button>`
+
+  ### Exemplos de Uso
+
+  #### Mensagem de Sucesso
+
+  ```tsx
+  import {
+    MessageRoot,
+    MessageIcon,
+    MessageText,
+    MessageClose
+  } from '@xjur-ui/react/message'
+
+  ;<MessageRoot variant="success">
+    <MessageIcon />
+    <MessageText>Documento salvo com sucesso!</MessageText>
+    <MessageClose />
+  </MessageRoot>
+  ```
+
+  #### Mensagem de Erro em Formulário
+
+  ```tsx
+  <MessageRoot variant="error">
+    <MessageIcon />
+    <MessageText>Por favor, preencha todos os campos obrigatórios.</MessageText>
+  </MessageRoot>
+  ```
+
+  #### Aviso Importante
+
+  ```tsx
+  <MessageRoot variant="warning">
+    <MessageIcon />
+    <MessageText>Esta ação não pode ser desfeita.</MessageText>
+  </MessageRoot>
+  ```
+
+  #### Mensagem Inline
+
+  ```tsx
+  <MessageRoot variant="neutral" inline>
+    <MessageText>Informação adicional</MessageText>
+  </MessageRoot>
+  ```
+
+  ### Funcionalidades
+
+  #### 1. Animação de Entrada
+  - Fade-in suave (250ms) para não assustar usuários
+  - Classes: `animate-in fade-in-0 duration-250`
+
+  #### 2. Fechamento Inteligente
+  - Remove o elemento do DOM ao clicar no botão de fechar
+  - Utiliza `ref.current?.remove()` para limpeza completa
+  - Callback `onClose` disponível via contexto
+
+  #### 3. Context API
+
+  ```tsx
+  interface MessageRootContextValue {
+    variant: MessageRootVariant
+    inline: boolean
+    onClose?: () => void
+  }
+
+  // Hook para componentes customizados
+  const { variant, inline, onClose } = useMessageRootContext()
+  ```
+
+  #### 4. Mapeamento Automático de Ícones
+
+  ```tsx
+  const iconMap = new Map<MessageRootVariant, React.ReactNode>([
+    ['success', <Icon name="check" className="text-success-idle" />],
+    ['neutral', <Icon name="info" className="text-icon-neutral-3" />],
+    ['warning', <Icon name="warning" className="text-warning-idle" />],
+    ['error', <Icon name="error" className="text-danger-idle" />]
+  ])
+  ```
+
+  ### Acessibilidade
+  - ✅ Botão de fechamento com `type="button"` para evitar submissão acidental
+  - ✅ Estados visuais claros com cores contrastantes
+  - ✅ Animação suave de entrada
+  - ✅ Remoção do DOM ao fechar para limpar árvore de acessibilidade
+  - ✅ Texto com truncate para evitar quebras visuais
+  - ✅ Suporte completo a leitores de tela
+
+  ### Performance
+  - **Context memoizado**: Reduz re-renders desnecessários
+  - **Callback estável**: `handleClose` com `useCallback`
+  - **Ícones pré-compilados**: Map de ícones criado uma única vez
+  - **Composição modular**: Componentes pequenos e focados
+
+  ### Documentação no Storybook
+
+  10 stories interativas demonstrando todos os casos de uso:
+  1. **Playground**: Exemplo interativo com controles
+  2. **Success**: Mensagem de sucesso
+  3. **Neutral**: Mensagem neutra/informativa
+  4. **Warning**: Mensagem de aviso
+  5. **Error**: Mensagem de erro
+  6. **InlineSuccess**: Versão compacta de sucesso
+  7. **InlineError**: Versão compacta de erro
+  8. **WithoutClose**: Mensagem persistente sem botão fechar
+  9. **LongText**: Demonstração com texto longo
+  10. **MultipleMessages**: Showcase de todas as variantes
+
+  ### Casos de Uso Suportados
+  1. ✅ Feedback de ações (salvar, deletar, enviar)
+  2. ✅ Validação de formulários
+  3. ✅ Avisos importantes
+  4. ✅ Mensagens de erro
+  5. ✅ Notificações de sistema
+  6. ✅ Confirmações de operações
+  7. ✅ Informações contextuais inline
+  8. ✅ Alertas temporários
+  9. ✅ Status de operações assíncronas
+  10. ✅ Mensagens de onboarding
+
+  ### Arquivos Criados
+  - `packages/react/src/components/message/index.ts`
+  - `packages/react/src/components/message/message-root.tsx`
+  - `packages/react/src/components/message/message-icon.tsx`
+  - `packages/react/src/components/message/message-text.tsx`
+  - `packages/react/src/components/message/message-close.tsx`
+  - `apps/docs/src/components/message.stories.tsx`
+
+  ### Integração com Design System
+
+  O componente Message utiliza:
+  - **Design tokens** do @xjur-ui/styles para cores e espaçamentos
+  - **Sistema de ícones** via componente Icon
+  - **Typography** para texto consistente
+  - **TailwindCSS 4.x** para estilização
+  - **Tailwind Variants** (tv) para variantes CSS
+
+  ### TypeScript
+
+  Tipagem completa exportada:
+
+  ```tsx
+  export type MessageRootVariant = 'success' | 'neutral' | 'warning' | 'error'
+
+  export interface MessageRootProps extends ComponentProps<'div'> {
+    variant?: MessageRootVariant
+    inline?: boolean
+    children: React.ReactNode
+  }
+
+  export function useMessageRootContext(): MessageRootContextValue
+  ```
+
+  ### Compatibilidade
+  - ✅ React 19.1.1+
+  - ✅ TypeScript 5.x
+  - ✅ Tailwind CSS 4.x
+  - ✅ Navegadores modernos (Chrome, Firefox, Safari, Edge)
+  - ✅ Dispositivos móveis (iOS Safari, Chrome Mobile)
+
+  ### Roadmap Futuro
+
+  Possíveis melhorias para próximas versões:
+  - Auto-dismiss com timeout configurável
+  - Posicionamento fixo (toast-style)
+  - Animações de saída customizáveis
+  - Suporte a ações customizadas (além de close)
+  - Progress bar para mensagens temporárias
+  - Queue de mensagens
+  - Suporte a rich content (links, imagens)
+
+  ***
+
+  ## 3. Novo Componente Toast (toast-v2)
+
+  ### Visão Geral
+
+  O **Toast** é um sistema completo de notificações temporárias não intrusivas, construído sobre a biblioteca Sonner e o componente Message. Oferece uma API imperativa simples e poderosa para exibir notificações toast com posicionamento, ações e callbacks.
+
+  ### Características Principais
+
+  #### Baseado em Sonner
+  - **Library moderna e performática**: Sonner é a biblioteca toast mais popular e otimizada do ecossistema React
+  - **Empilhamento inteligente**: Gerenciamento automático de múltiplos toasts
+  - **Animações suaves**: CSS transforms otimizadas
+  - **Mobile-friendly**: Suporte a swipe gestures
+  - **Acessibilidade integrada**: ARIA live regions automáticas
+
+  #### Integração com Message
+  - Reutiliza componente Message para consistência visual
+  - Usa MessageIcon, MessageText, MessageAction e MessageClose
+  - Design tokens compartilhados
+  - Mesmos padrões de acessibilidade
+
+  #### Arquitetura
+  - **ToastWrapper**: Provider global baseado no Toaster do Sonner
+  - **toast()**: Função imperativa para disparar toasts
+  - **ToastComponent**: Componente interno que renderiza usando Message
 
-- 338d246: feat: ajuste no componente de otp input para receber borda de erro
+  ### API do Componente
+
+  O objeto `toast` expõe 3 métodos principais:
+
+  #### 1. toast.dispatch(message, options)
+
+  Dispara um novo toast e retorna o ID do toast criado.
+
+  ```tsx
+  function toast.dispatch(message: string, options?: {
+    variant?: 'primary' | 'destructive'
+    dismissible?: boolean
+    action?: { label: string; onClick: () => void }
+    position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+    inline?: boolean
+    duration?: number  // ms, default: 3000
+    toasterId?: string
+    onAutoClose?: (toast) => void
+    onDismiss?: (toast) => void
+  }): string  // Retorna o ID do toast
+  ```
+
+  #### 2. toast.dismiss(toastId)
+
+  Fecha um toast específico pelo ID.
+
+  ```tsx
+  function toast.dismiss(toastId: string): void
+  ```
+
+  **Exemplo**:
+
+  ```tsx
+  const toastId = toast.dispatch('Processando...')
+  // Mais tarde...
+  toast.dismiss(toastId)
+  ```
+
+  #### 3. toast.clear()
+
+  Fecha todos os toasts ativos.
+
+  ```tsx
+  function toast.clear(): void
+  ```
+
+  **Exemplo**:
+
+  ```tsx
+  // Fechar todos os toasts ao navegar para outra página
+  toast.clear()
+  ```
+
+  #### Opções Disponíveis
+
+  | Opção       | Tipo                                     | Padrão         | Descrição                                     |
+  | ----------- | ---------------------------------------- | -------------- | --------------------------------------------- | ----------------------------------------- | --------------- |
+  | variant     | `'primary'                               | 'destructive'` | `'primary'`                                   | Estilo visual (mapeia para success/error) |
+  | dismissible | `boolean`                                | `true`         | Se pode ser fechado manualmente               |
+  | action      | `{ label: string; onClick: () => void }` | `undefined`    | Botão de ação adicional                       |
+  | position    | `'top-right'                             | 'top-left'     | ...`                                          | `undefined`                               | Posição na tela |
+  | inline      | `boolean`                                | `false`        | Modo compacto                                 |
+  | duration    | `number`                                 | `3000`         | Duração em ms (Infinity se dismissible=false) |
+  | toasterId   | `string`                                 | `undefined`    | ID do toaster específico                      |
+  | onAutoClose | `(toast) => void`                        | `undefined`    | Callback ao fechar automaticamente            |
+  | onDismiss   | `(toast) => void`                        | `undefined`    | Callback ao fechar                            |
+
+  ### Variantes
+
+  | Variante    | Mapeia para Message | Visual                   | Uso                              |
+  | ----------- | ------------------- | ------------------------ | -------------------------------- |
+  | primary     | success             | Verde com ícone check    | Confirmações e sucessos (padrão) |
+  | destructive | error               | Vermelho com ícone error | Erros e ações destrutivas        |
+
+  **Nota**: Para variantes `neutral` e `warning`, use o componente Message diretamente com posicionamento fixo.
+
+  ### Posições Disponíveis
+  - **top-right**: Canto superior direito
+  - **top-left**: Canto superior esquerdo
+  - **bottom-right**: Canto inferior direito (padrão Sonner)
+  - **bottom-left**: Canto inferior esquerdo
+
+  ### Exemplos de Uso
+
+  #### Setup Inicial
+
+  ```tsx
+  import { ToastWrapper } from '@xjur-ui/react/toast-v2'
+
+  function App() {
+    return (
+      <>
+        <ToastWrapper />
+        {/* Resto da aplicação */}
+      </>
+    )
+  }
+  ```
+
+  #### Toast Simples
+
+  ```tsx
+  import { toast } from '@xjur-ui/react/toast'
+
+  // Sucesso
+  toast.dispatch('Documento salvo com sucesso!')
+
+  // Erro
+  toast.dispatch('Erro ao processar solicitação', {
+    variant: 'destructive'
+  })
+  ```
+
+  #### Toast com Ação
+
+  ```tsx
+  toast.dispatch('Email enviado com sucesso', {
+    action: {
+      label: 'Desfazer',
+      onClick: () => undoSendEmail()
+    }
+  })
+  ```
+
+  #### Toast Persistente com Dismiss
+
+  ```tsx
+  const toastId = toast.dispatch('Processando... Por favor aguarde', {
+    dismissible: false,
+    duration: Infinity
+  })
+
+  // Depois de completar a tarefa
+  setTimeout(() => {
+    toast.dismiss(toastId)
+    toast.dispatch('Concluído!', { variant: 'primary' })
+  }, 3000)
+  ```
+
+  #### Fechar Todos os Toasts
+
+  ```tsx
+  // Disparar múltiplos toasts
+  toast.dispatch('Primeira notificação')
+  toast.dispatch('Segunda notificação')
+  toast.dispatch('Terceira notificação')
+
+  // Fechar todos de uma vez
+  toast.clear()
+  ```
+
+  #### Toast com Posição e Duração
+
+  ```tsx
+  toast.dispatch('Notificação importante', {
+    position: 'top-right',
+    duration: 5000 // 5 segundos
+  })
+  ```
+
+  #### Toast com Callbacks
+
+  ```tsx
+  toast.dispatch('Upload iniciado', {
+    onAutoClose: t => {
+      console.log('Toast auto-fechado:', t)
+      logAnalytics('toast_auto_close')
+    },
+    onDismiss: t => {
+      console.log('Toast fechado:', t)
+    }
+  })
+  ```
+
+  ### Funcionalidades
+
+  #### 1. Empilhamento Automático
+  - Sonner gerencia automaticamente a queue de toasts
+  - Toasts são empilhados verticalmente
+  - Animações coordenadas ao adicionar/remover
+
+  #### 2. Swipe to Dismiss (Mobile)
+  - Gestos de swipe para fechar em mobile
+  - Feedback visual durante o swipe
+  - Configuração automática pelo Sonner
+
+  #### 3. Auto-dismiss Inteligente
+  - Duração padrão de 3 segundos
+  - Ajuste automático para Infinity se `dismissible=false`
+  - Pause no hover (comportamento Sonner)
+
+  #### 4. Callbacks de Lifecycle
+  - `onAutoClose`: Chamado quando fecha automaticamente
+  - `onDismiss`: Chamado em qualquer tipo de fechamento
+  - Recebe objeto toast com ID e metadata
+
+  #### 5. Múltiplos Toasters
+  - Suporte a múltiplos toasters com IDs diferentes
+  - Útil para diferentes áreas da aplicação
+  - Configuração via `toasterId`
+
+  #### 6. Gerenciamento de Ciclo de Vida
+  - **Disparar**: `toast.dispatch()` retorna o ID do toast
+  - **Fechar específico**: `toast.dismiss(id)` fecha um toast pelo ID
+  - **Fechar todos**: `toast.clear()` limpa todos os toasts ativos
+  - Permite padrões avançados:
+    - Substituir toast de loading por sucesso
+    - Limpar notificações ao mudar de página
+    - Gerenciar toasts relacionados
+
+  ### Integração com Message
+
+  O Toast reutiliza completamente o componente Message:
+
+  ```tsx
+  // toast-component.tsx
+  export function ToastComponent({
+    variant = 'primary',
+    inline = false,
+    dismissible = true,
+    message,
+    action,
+    onDismiss
+  }: ToastComponentProps) {
+    return (
+      <MessageRoot inline={inline} variant={variant}>
+        <MessageIcon />
+        <MessageText>{message}</MessageText>
+
+        {action && (
+          <MessageAction variant={variant} onClick={action.onClick}>
+            {action.label}
+          </MessageAction>
+        )}
+
+        {dismissible && <MessageClose onClick={onDismiss} />}
+      </MessageRoot>
+    )
+  }
+  ```
+
+  Isso garante:
+  - ✅ Consistência visual total
+  - ✅ Mesmos design tokens
+  - ✅ Manutenção centralizada
+  - ✅ Reutilização de código
+
+  ### Acessibilidade
+  - ✅ **ARIA live regions**: Sonner cria automaticamente
+  - ✅ **Screen readers**: Anúncios automáticos de toasts
+  - ✅ **Navegação por teclado**: Tab, Enter, Escape
+  - ✅ **Focus management**: Foco adequado em ações
+  - ✅ **Swipe gestures**: Mobile acessível
+  - ✅ **Prefers-reduced-motion**: Respeita preferências do usuário
+  - ✅ **Labels apropriadas**: Botões com texto claro
+
+  ### Performance
+  - ✅ **Renderização otimizada**: Sonner usa virtualização
+  - ✅ **Animações com transforms**: GPU-accelerated
+  - ✅ **Limpeza automática**: Remove toasts do DOM após fechar
+  - ✅ **Memoização**: Context e callbacks memoizados
+  - ✅ **Bundle size pequeno**: ~10KB (Sonner) + componentes existentes
+
+  ### Documentação no Storybook
+
+  13 stories interativas cobrindo todos os casos:
+  1. **Playground**: Exemplo básico interativo
+  2. **Primary**: Toast de sucesso
+  3. **Destructive**: Toast de erro
+  4. **WithAction**: Toast com botão de ação
+  5. **NotDismissible**: Toast persistente
+  6. **CustomDuration**: Durações customizadas (1s, 10s)
+  7. **Positions**: Todas as 4 posições
+  8. **InlineMode**: Modo compacto
+  9. **WithCallbacks**: Demonstração de callbacks
+  10. **MultipleToasts**: Empilhamento de 3 toasts
+  11. **DismissSpecific**: Fechar toast específico por ID
+  12. **ClearAll**: Fechar todos os toasts ativos
+  13. **RealWorldExample**: Exemplos CRUD práticos
+
+  ### Casos de Uso Suportados
+  1. ✅ Confirmações de ações (salvar, deletar, enviar)
+  2. ✅ Notificações de erro
+  3. ✅ Ações com desfazer (undo)
+  4. ✅ Status de upload/download
+  5. ✅ Notificações de sistema
+  6. ✅ Feedback de formulários
+  7. ✅ Operações assíncronas
+  8. ✅ Alertas temporários
+  9. ✅ Confirmações destrutivas
+  10. ✅ Múltiplas notificações simultâneas
+
+  ### Arquivos Criados/Substituídos
+
+  **Toast (substituição completa)**:
+  - `packages/react/src/components/toast/index.ts`
+  - `packages/react/src/components/toast/toast.tsx`
+  - `packages/react/src/components/toast/toast-component.tsx`
+  - `packages/react/src/components/toast/toast.types.ts`
+
+  **Message**:
+  - `packages/react/src/components/message/message-action.tsx` (novo)
+
+  **Documentação**:
+  - `apps/docs/src/components/toast.stories.tsx` (reescrito completamente)
+
+  **Observação**: O componente Toast foi completamente reescrito. O código antigo baseado em Radix foi substituído por uma nova implementação baseada em Sonner.
+
+  ### Dependências
+
+  Nova dependência adicionada:
+
+  ```json
+  {
+    "dependencies": {
+      "sonner": "^1.x"
+    }
+  }
+  ```
+
+  **Sonner**: Library toast moderna, leve e performática
+  - Bundle: ~10KB gzipped
+  - Zero dependencies além de React
+  - Amplamente adotada pela comunidade
+  - Manutenção ativa
+
+  ### Comparação: Toast vs Message
+
+  | Aspecto          | Toast (toast-v2)          | Message                   |
+  | ---------------- | ------------------------- | ------------------------- |
+  | **Posição**      | Fixo na tela (flutuante)  | Inline no layout          |
+  | **Duração**      | Temporário (auto-dismiss) | Persistente               |
+  | **API**          | Imperativa (`toast()`)    | Declarativa (JSX)         |
+  | **Uso**          | Notificações globais      | Feedback contextual       |
+  | **Empilhamento** | Automático (Sonner queue) | Manual                    |
+  | **Biblioteca**   | Sonner + Message          | Nativo                    |
+  | **Callbacks**    | onAutoClose, onDismiss    | onClose via ref           |
+  | **Posições**     | 4 cantos da tela          | Onde for renderizado      |
+  | **Ações**        | Suporte via MessageAction | Suporte via MessageAction |
+
+  ### Boas Práticas
+  1. **Use Toast para feedback não crítico**: Confirmações rápidas, updates de status
+  2. **Use Message para feedback crítico inline**: Erros de formulário, avisos importantes
+  3. **Limite a duração**: 3-5s para leitura confortável
+  4. **Evite spam de toasts**: Não dispare múltiplos toasts em sequência rápida
+  5. **Forneça ações quando relevante**: "Desfazer", "Ver detalhes"
+  6. **Posicione adequadamente**: top-right para notificações, bottom-right para status
+  7. **Teste em mobile**: Verifique swipe gestures
+  8. **Use callbacks para analytics**: Track abertura e fechamento
+  9. **Gerencie o ciclo de vida**: Use `dismiss()` para substituir loading por sucesso
+  10. **Limpe ao navegar**: Use `clear()` ao mudar de página/contexto
+  11. **Armazene IDs quando necessário**: Salve o retorno de `dispatch()` para controle posterior
+
+  ### Migração do Toast Antigo (Radix)
+
+  O toast antigo baseado em Radix UI será removido. Migração:
+
+  #### Antes (Toast Radix - Depreciado)
+
+  ```tsx
+  import {
+    ToastProvider,
+    ToastComponent,
+    ToastViewport
+  } from '@xjur-ui/react/toast'
+
+  ;<ToastProvider>
+    <ToastComponent variant="success" description="Salvo!" />
+    <ToastViewport />
+  </ToastProvider>
+  ```
+
+  #### Depois (Toast Sonner - Novo)
+
+  ```tsx
+  import { ToastWrapper, toast } from '@xjur-ui/react/toast'
+
+  // No root da app
+  ;<ToastWrapper />
+
+  // Onde precisar
+  toast.dispatch('Salvo!', { variant: 'primary' })
+
+  // Com controle de ciclo de vida
+  const toastId = toast.dispatch('Processando...')
+  toast.dismiss(toastId) // Fechar específico
+  toast.clear() // Fechar todos
+  ```
+
+  ### Compatibilidade
+  - ✅ React 19.1.1+
+  - ✅ TypeScript 5.x
+  - ✅ Tailwind CSS 4.x
+  - ✅ Navegadores modernos (Chrome, Firefox, Safari, Edge)
+  - ✅ iOS Safari 12+
+  - ✅ Chrome Mobile
+  - ✅ Suporte SSR/SSG
+
+  ### Roadmap Futuro
+
+  Melhorias planejadas:
+  - Mais variantes (neutral, warning) mapeando para Message
+  - Suporte a rich content (imagens, progress bars)
+  - Posições customizadas (não apenas cantos)
+  - Temas customizados
+  - Agrupamento de toasts relacionados
+  - Priorização de toasts
+  - Rate limiting automático
+
+  ***
+
+  ## 4. Novo Componente SelectionBar (selection-bar-v2)
+
+  ### Visão Geral
+
+  O **SelectionBar** é um componente composicional que exibe uma barra de ações flutuante na parte inferior da tela quando itens são selecionados. Renderizado via Portal React, é ideal para operações em lote em listas, tabelas e grids, oferecendo uma experiência moderna e intuitiva.
+
+  ### Características Principais
+
+  #### Arquitetura Composicional Moderna
+  - **SelectionBarRoot**: Container principal com gerenciamento de estado e portal
+  - **SelectionBarTitleRoot**: Container para título e botão de fechar
+  - **SelectionBarTitle**: Texto do título (wrapper do Typography)
+  - **SelectionBarClose**: Botão para fechar a barra
+  - **SelectionBarActionGroup**: Container de ações com suporte a overflow
+  - **SelectionBarAction**: Botão de ação (wrapper do Button)
+
+  #### Portal e Posicionamento Fixo
+  - Renderizado via `createPortal` React
+  - Alvo: elemento `#selection-bar-root` ou `document.body`
+  - Posição: `fixed bottom-[60px]` (acima de barras de navegação)
+  - Centralizado horizontalmente: `left-1/2 -translate-x-1/2`
+  - Z-index: 1000 (acima de outros elementos)
+
+  #### Animações e Transições
+  - **Entrada**: `slide-in-from-top` (200ms)
+  - **Saída**: `slide-out-to-bottom` (200ms)
+  - Auto-remoção do DOM após fechamento
+  - Estados visuais: `data-state="open|closed"`
+
+  ### API do Componente
+
+  #### SelectionBarRoot
+
+  ```tsx
+  interface SelectionBarRootProps {
+    open?: boolean // Padrão: true
+    onOpenChange?: (open: boolean) => void
+    className?: string
+    children: React.ReactNode
+    // + todas as props de HTMLDivElement
+  }
+  ```
+
+  **Context API**:
+
+  ```tsx
+  interface SelectionBarContextValue {
+    open: boolean
+    onClose: () => void
+  }
+
+  // Hook
+  const { open, onClose } = useSelectionBarContext()
+  ```
+
+  #### Outros Componentes
+
+  | Componente              | Base       | Props Especiais               |
+  | ----------------------- | ---------- | ----------------------------- |
+  | SelectionBarTitleRoot   | div        | Container flexbox             |
+  | SelectionBarTitle       | Typography | weight="medium", cor neutra   |
+  | SelectionBarClose       | Button     | size="icon_md", ícone close   |
+  | SelectionBarActionGroup | div        | Flexbox com overflow-x-hidden |
+  | SelectionBarAction      | Button     | className="shrink-0"          |
+
+  ### Exemplos de Uso
+
+  #### Seleção Básica em Tabela
+
+  ```tsx
+  import {
+    SelectionBarRoot,
+    SelectionBarTitleRoot,
+    SelectionBarTitle,
+    SelectionBarClose,
+    SelectionBarActionGroup,
+    SelectionBarAction
+  } from '@xjur-ui/react/selection-bar'
+  import { Icon } from '@xjur-ui/react/icon'
+
+  const [selectedIds, setSelectedIds] = useState<string[]>([])
+
+  {
+    selectedIds.length > 0 && (
+      <SelectionBarRoot>
+        <SelectionBarTitleRoot>
+          <SelectionBarClose />
+          <SelectionBarTitle>
+            {selectedIds.length} selecionados
+          </SelectionBarTitle>
+        </SelectionBarTitleRoot>
+
+        <SelectionBarActionGroup>
+          <SelectionBarAction onClick={handleExport}>
+            <Icon name="download" />
+            Exportar
+          </SelectionBarAction>
+          <SelectionBarAction onClick={handleArchive}>
+            Arquivar
+          </SelectionBarAction>
+          <SelectionBarAction variant="destructive" onClick={handleDelete}>
+            <Icon name="delete" />
+            Excluir
+          </SelectionBarAction>
+        </SelectionBarActionGroup>
+      </SelectionBarRoot>
+    )
+  }
+  ```
+
+  #### Com Controle de Estado
+
+  ```tsx
+  const [open, setOpen] = useState(false)
+  const [selectedItems, setSelectedItems] = useState([])
+
+  <SelectionBarRoot
+    open={open}
+    onOpenChange={(newOpen) => {
+      setOpen(newOpen)
+      if (!newOpen) {
+        // Limpar seleções ao fechar
+        setSelectedItems([])
+      }
+    }}
+  >
+    <SelectionBarTitleRoot>
+      <SelectionBarClose />
+      <SelectionBarTitle>
+        {selectedItems.length} selecionados
+      </SelectionBarTitle>
+    </SelectionBarTitleRoot>
+
+    <SelectionBarActionGroup>
+      <SelectionBarAction>Exportar PDF</SelectionBarAction>
+      <SelectionBarAction>Compartilhar</SelectionBarAction>
+      <SelectionBarAction variant="destructive">
+        <Icon name="delete" />
+      </SelectionBarAction>
+    </SelectionBarActionGroup>
+  </SelectionBarRoot>
+  ```
+
+  #### Operações em Lote
+
+  ```tsx
+  <SelectionBarRoot>
+    <SelectionBarTitleRoot>
+      <SelectionBarClose />
+      <SelectionBarTitle>5 documentos selecionados</SelectionBarTitle>
+    </SelectionBarTitleRoot>
+
+    <SelectionBarActionGroup>
+      <SelectionBarAction>Exportar PDF</SelectionBarAction>
+      <SelectionBarAction>Exportar Excel</SelectionBarAction>
+      <SelectionBarAction>Compartilhar</SelectionBarAction>
+      <SelectionBarAction>Mover para</SelectionBarAction>
+      <SelectionBarAction>Arquivar</SelectionBarAction>
+
+      <SelectionBarAction size="icon_md" variant="destructive">
+        <Icon name="delete" />
+      </SelectionBarAction>
+    </SelectionBarActionGroup>
+  </SelectionBarRoot>
+  ```
+
+  ### Funcionalidades
+
+  #### 1. Portal Rendering
+  - Renderiza fora da hierarquia DOM do componente pai
+  - Evita problemas de z-index e overflow
+  - Permite posicionamento fixo global
+  - Fallback automático para `document.body`
+
+  #### 2. Gerenciamento de Estado
+  - Estado controlado via props `open` e `onOpenChange`
+  - Estado interno quando não controlado
+  - Callback ao fechar para sincronizar com estado externo
+  - Auto-remoção do DOM após animação de saída
+
+  #### 3. Overflow Horizontal
+  - Container de ações com `overflow-x-hidden`
+  - Scroll horizontal automático em mobile
+  - Ações com `shrink-0` para não comprimir
+  - Suporta muitas ações sem quebrar layout
+
+  #### 4. Context API
+  - Hook `useSelectionBarContext()` para componentes customizados
+  - Acesso a `open` e `onClose` em qualquer nível
+  - Permite criar componentes especializados
+
+  #### 5. Integração com Componentes Base
+  - Usa Button para ações (todas as variantes disponíveis)
+  - Usa Typography para título (todas as props disponíveis)
+  - Usa Icon para ícones
+  - Mantém consistência visual com design system
+
+  ### Acessibilidade
+  - ✅ **Navegação por teclado**: Todos os botões são focáveis
+  - ✅ **Ícones descritivos**: Ações com ícones e/ou texto claro
+  - ✅ **Botão de fechar**: Sempre visível e acessível
+  - ✅ **Contraste adequado**: Fundo primário com texto legível
+  - ✅ **Animações**: Respeitam `prefers-reduced-motion`
+  - ✅ **Focus management**: Foco adequado em botões
+
+  ### Performance
+  - ✅ **Portal rendering**: Otimizado pelo React
+  - ✅ **Animações CSS**: GPU-accelerated com transforms
+  - ✅ **Auto-remoção**: Limpa DOM após fechamento
+  - ✅ **Context memoizado**: Evita re-renders desnecessários
+  - ✅ **Callbacks estáveis**: `useCallback` para `handleClose`
+  - ✅ **Composição modular**: Componentes pequenos e focados
+
+  ### Documentação no Storybook
+
+  8 stories interativas cobrindo todos os casos:
+  1. **Playground**: Exemplo básico com 3 itens selecionados
+  2. **WithManyActions**: Múltiplas ações com overflow
+  3. **WithIconsOnly**: Apenas ícones (compacto)
+  4. **WithMixedActions**: Mistura de ícones e texto
+  5. **ControlledState**: Controle total do estado
+  6. **TableIntegration**: Integração completa com tabela
+  7. **MinimalActions**: Uma única ação
+  8. **WithVariants**: Diferentes variantes de botão
+
+  ### Casos de Uso Suportados
+  1. ✅ Seleção em tabelas
+  2. ✅ Operações em lote em listas
+  3. ✅ Seleção múltipla em grids
+  4. ✅ Ações de arquivamento em massa
+  5. ✅ Exportação de múltiplos itens
+  6. ✅ Compartilhamento em lote
+  7. ✅ Exclusão de múltiplos registros
+  8. ✅ Movimentação de arquivos
+  9. ✅ Marcação de leitura/não lido
+  10. ✅ Aprovação/rejeição em lote
+
+  ### Arquivos Criados/Substituídos
+
+  **SelectionBar (substituição completa)**:
+  - `packages/react/src/components/selection-bar/index.ts`
+  - `packages/react/src/components/selection-bar/selection-bar-root.tsx`
+  - `packages/react/src/components/selection-bar/selection-bar-title.tsx`
+  - `packages/react/src/components/selection-bar/selection-bar-close.tsx`
+  - `packages/react/src/components/selection-bar/selection-bar-action.tsx`
+  - `packages/react/src/components/selection-bar/selection-bar-action-group.tsx`
+
+  **Documentação**:
+  - `apps/docs/src/components/selection-bar.stories.tsx` (reescrito completamente)
+
+  **Observação**: O componente SelectionBar foi completamente reescrito. O código antigo foi substituído por uma nova implementação composicional com portal, estado gerenciado e animações.
+
+  ### Comparação: Versão Antiga vs Nova
+
+  | Aspecto          | Antiga                  | Nova (v2)                    |
+  | ---------------- | ----------------------- | ---------------------------- |
+  | **Arquitetura**  | Monolítica              | Composicional                |
+  | **Renderização** | Normal no DOM           | Portal (flutuante)           |
+  | **Estado**       | Não gerenciado          | Controlado/não-controlado    |
+  | **Animações**    | Básicas ou inexistentes | Slide-in/out suaves          |
+  | **Overflow**     | Sem tratamento          | Scroll horizontal automático |
+  | **Fechamento**   | Manual                  | Auto-remoção do DOM          |
+  | **Context**      | Sem context             | Context API completa         |
+  | **Callbacks**    | Limitados               | `onOpenChange` completo      |
+  | **Composição**   | 1-2 componentes         | 6 componentes especializados |
+
+  ### Boas Práticas
+  1. **Use para operações em lote**: Perfeito para ações em múltiplos itens
+  2. **Limite o número de ações**: 3-5 ações principais
+  3. **Priorize ações importantes**: Mais usadas primeiro
+  4. **Indique quantidade selecionada**: Sempre mostre o número
+  5. **Forneça feedback visual**: Ícones e cores apropriadas
+  6. **Feche ao limpar seleção**: Use `onOpenChange` para sincronizar
+  7. **Teste em mobile**: Verifique overflow horizontal
+  8. **Confirme ações destrutivas**: Use diálogos para deletar
+  9. **Crie portal root**: Adicione `<div id="selection-bar-root" />` no app
+  10. **Sincronize estado**: Mantenha seleções e barra em sync
+
+  ### Migração da Versão Antiga
+
+  #### Antes (SelectionBar Antigo - Depreciado)
+
+  ```tsx
+  import { SelectionBar } from '@xjur-ui/react/selection-bar'
+
+  ;<SelectionBar
+    title="3 selecionados"
+    actions={[
+      { label: 'Exportar', onClick: handleExport },
+      { label: 'Excluir', onClick: handleDelete }
+    ]}
+  />
+  ```
+
+  #### Depois (SelectionBar Novo - Composicional)
+
+  ```tsx
+  import {
+    SelectionBarRoot,
+    SelectionBarTitleRoot,
+    SelectionBarTitle,
+    SelectionBarClose,
+    SelectionBarActionGroup,
+    SelectionBarAction
+  } from '@xjur-ui/react/selection-bar'
+
+  ;<SelectionBarRoot>
+    <SelectionBarTitleRoot>
+      <SelectionBarClose />
+      <SelectionBarTitle>3 selecionados</SelectionBarTitle>
+    </SelectionBarTitleRoot>
+
+    <SelectionBarActionGroup>
+      <SelectionBarAction onClick={handleExport}>Exportar</SelectionBarAction>
+      <SelectionBarAction variant="destructive" onClick={handleDelete}>
+        Excluir
+      </SelectionBarAction>
+    </SelectionBarActionGroup>
+  </SelectionBarRoot>
+  ```
+
+  ### Compatibilidade
+  - ✅ React 19.1.1+
+  - ✅ TypeScript 5.x
+  - ✅ Tailwind CSS 4.x
+  - ✅ Navegadores modernos (Chrome, Firefox, Safari, Edge)
+  - ✅ iOS Safari 12+
+  - ✅ Chrome Mobile
+  - ✅ Suporte SSR/SSG (com hydration de portals)
+
+  ### Roadmap Futuro
+
+  Melhorias planejadas:
+  - Indicador visual de scroll (mais ações disponíveis)
+  - Posicionamento customizável (top/bottom)
+  - Temas customizados
+  - Suporte a ações agrupadas (dropdowns)
+  - Contador animado ao mudar seleção
+  - Undo/Redo de ações
+  - Modo compacto para mobile
+
+  ***
+
+  ## Resumo da Release
+
+  ### Breaking Changes
+  - ❌ **OTPInput** removido e substituído por **PinInput**
+  - ❌ **Toast (Radix)** removido e substituído por **Toast (Sonner)**
+  - ❌ **SelectionBar** reescrito completamente com arquitetura composicional
+
+  ### Novas Funcionalidades
+  - ✅ **PinInput**: Componente moderno com auto-submit, callbacks e validação
+  - ✅ **Message**: Sistema de mensagens contextuais com 4 variantes
+  - ✅ **Toast**: Sistema de notificações baseado em Sonner com controle de ciclo de vida
+  - ✅ **SelectionBar**: Barra de ações flutuante com portal e estado gerenciado
+  - ✅ **MessageAction**: Componente de ação para Message e Toast
+
+  ### Melhorias
+  - 📖 Documentação completa no Storybook (40 stories no total)
+  - 🎨 Design consistente com tokens do sistema
+  - ♿ Acessibilidade aprimorada em todos os componentes
+  - ⚡ Performance otimizada com memoização e portals
+  - 📦 TypeScript completo com tipos exportados
+  - 🔄 Reutilização de componentes (Toast usa Message internamente)
+  - 📱 Mobile-friendly (swipe no Toast, overflow no SelectionBar)
+  - 🎯 Controle total de ciclo de vida (toasts e selection bar)
+  - 🎭 Animações suaves em todos os componentes
+
+  ### Arquivos Modificados/Criados
+  - 5 arquivos do componente PinInput
+  - 6 arquivos do componente Message (incluindo MessageAction)
+  - 4 arquivos do componente Toast
+  - 6 arquivos do componente SelectionBar
+  - 3 arquivos de stories no Storybook
+  - 1 README do PinInput
+
+  ### Arquivos Removidos
+  - 1 arquivo do OTPInput antigo
+  - 1 arquivo do Toast antigo (Radix)
+  - 1 arquivo do SelectionBar antigo
+  - 1 arquivo de stories do OTPInput
+
+  ### Dependências Adicionadas
+  - **sonner**: ^2.0.7 (~10KB) - Library moderna para toasts
+
+  ### Estatísticas da Release
+  - **Componentes novos/reescritos**: 4 (PinInput, Message, Toast, SelectionBar)
+  - **Componentes removidos**: 3 (OTPInput, Toast Radix, SelectionBar antigo)
+  - **Stories no Storybook**: 40 (9 PinInput + 10 Message + 13 Toast + 8 SelectionBar)
+  - **Breaking changes**: 3 (OTPInput → PinInput, Toast Radix → Toast Sonner, SelectionBar reescrito)
+  - **Linhas de código**: ~1800 novas linhas
+  - **Cobertura de casos de uso**: 37+ casos diferentes
+  - **Funcionalidades do Toast**: 3 métodos (dispatch, dismiss, clear)
+  - **Componentes no SelectionBar**: 6 componentes especializados
+
+  ### Próximos Passos Recomendados
+  1. **Migrar de OTPInput para PinInput**
+     - Atualizar imports: `@xjur-ui/react/pin-input`
+     - Renomear componentes: `OTPInputRoot` → `PinInput`, etc.
+     - Ajustar props: `initial` → `defaultValue`
+     - Adicionar callbacks opcionais: `onComplete`, `onChangeValue`
+     - Aproveitar auto-submit para melhor UX
+  2. **Migrar de Toast Radix para Toast Sonner**
+     - Atualizar imports: `@xjur-ui/react/toast`
+     - Substituir `<ToastProvider>` por `<ToastWrapper />`
+     - Converter de API declarativa para imperativa
+     - Usar `toast.dispatch()` ao invés de componentes JSX
+     - Aproveitar `toast.dismiss()` e `toast.clear()` para controle avançado
+     - Armazenar IDs retornados por `dispatch()` quando necessário
+     - Remover lógica de gerenciamento manual de toasts
+  3. **Integrar Message no sistema**
+     - Substituir alerts antigos por Message
+     - Padronizar feedback de ações em formulários
+     - Implementar em fluxos críticos
+     - Usar MessageAction para ações contextuais
+  4. **Migrar SelectionBar**
+     - Atualizar imports para componentes composicionais
+     - Converter props de array para JSX composicional
+     - Adicionar `<div id="selection-bar-root" />` no root da aplicação (opcional)
+     - Usar `onOpenChange` para sincronizar estado com seleções
+     - Aproveitar overflow horizontal para muitas ações
+  5. **Integrar Toast para notificações**
+     - Adicionar `<ToastWrapper />` no root da aplicação
+     - Substituir notificações antigas por `toast.dispatch()`
+     - Usar `toast.dismiss()` para substituir loading por sucesso
+     - Usar `toast.clear()` ao mudar de página/contexto
+     - Implementar callbacks para analytics
+     - Configurar posicionamento adequado
+     - Armazenar IDs para controle de toasts relacionados
+  6. **Integrar SelectionBar em tabelas e listas**
+     - Adicionar ao componente de seleção múltipla
+     - Sincronizar estado de seleções com `onOpenChange`
+     - Implementar ações em lote (exportar, deletar, arquivar)
+     - Configurar portal root para melhor controle
+     - Testar overflow em mobile
+  7. **Testar em produção**
+     - Validar acessibilidade com leitores de tela
+     - Verificar performance em dispositivos low-end
+     - Testar gestures em mobile (swipe to dismiss, overflow horizontal)
+     - Validar portals em SSR/SSG
+     - Coletar feedback de usuários
+     - Monitorar métricas de uso
+
+  ### Impacto Estimado
+
+  **Positivo:**
+  - ✅ Melhor DX com API simplificada
+  - ✅ Componentes mais modernos e performáticos
+  - ✅ Documentação muito mais completa
+  - ✅ Consistência visual total entre Message e Toast
+  - ✅ Redução de bundle size (Sonner vs Radix Toast)
+  - ✅ Mais casos de uso suportados
+
+  **Atenção Necessária:**
+  - ⚠️ Migração necessária em todos os usos de OTPInput
+  - ⚠️ Migração necessária em todos os usos de Toast
+  - ⚠️ Migração necessária em todos os usos de SelectionBar
+  - ⚠️ Testes extensivos recomendados (especialmente portals em SSR)
+  - ⚠️ Atualização de documentação interna da equipe
+  - ⚠️ Validação de z-index em diferentes contextos
+
+  ### Guias de Migração Rápida
+
+  #### OTPInput → PinInput (1 minuto)
+
+  ```diff
+  - import { OTPInputRoot, OTPInputInput, ... } from '@xjur-ui/react/otp-input'
+  + import { PinInput, PinInputControl, ... } from '@xjur-ui/react/pin-input'
+
+  - <OTPInputRoot initial="1234" length={4}>
+  + <PinInput defaultValue="1234" length={4} name="code">
+      <PinInputTrigger>
+  -     <OTPInputInput index={0} />
+  +     <PinInputControl index={0} />
+      </PinInputTrigger>
+  -   <OTPInputHiddenInput name="code" />
+    </PinInput>
+  ```
+
+  #### Toast Radix → Toast Sonner (30 segundos)
+
+  ```diff
+  - import { ToastProvider, ToastComponent } from '@xjur-ui/react/toast'
+  + import { ToastWrapper, toast } from '@xjur-ui/react/toast'
+
+    // No root
+  - <ToastProvider>
+  -   <App />
+  - </ToastProvider>
+  + <ToastWrapper />
+  + <App />
+
+    // Ao disparar
+  - <ToastComponent variant="success" description="Salvo!" />
+  + toast.dispatch('Salvo!', { variant: 'primary' })
+
+    // Controle avançado
+  + const id = toast.dispatch('Processando...')
+  + toast.dismiss(id)  // Fechar específico
+  + toast.clear()      // Fechar todos
+  ```
+
+  #### SelectionBar Antigo → SelectionBar Composicional (2 minutos)
+
+  ```diff
+  - import { SelectionBar } from '@xjur-ui/react/selection-bar'
+  + import {
+  +   SelectionBarRoot,
+  +   SelectionBarTitleRoot,
+  +   SelectionBarTitle,
+  +   SelectionBarClose,
+  +   SelectionBarActionGroup,
+  +   SelectionBarAction
+  + } from '@xjur-ui/react/selection-bar'
+
+  - <SelectionBar
+  -   title="3 selecionados"
+  -   actions={[
+  -     { label: 'Exportar', onClick: handleExport },
+  -     { label: 'Excluir', onClick: handleDelete }
+  -   ]}
+  - />
+  + <SelectionBarRoot>
+  +   <SelectionBarTitleRoot>
+  +     <SelectionBarClose />
+  +     <SelectionBarTitle>3 selecionados</SelectionBarTitle>
+  +   </SelectionBarTitleRoot>
+  +
+  +   <SelectionBarActionGroup>
+  +     <SelectionBarAction onClick={handleExport}>
+  +       Exportar
+  +     </SelectionBarAction>
+  +     <SelectionBarAction
+  +       variant="destructive"
+  +       onClick={handleDelete}
+  +     >
+  +       Excluir
+  +     </SelectionBarAction>
+  +   </SelectionBarActionGroup>
+  + </SelectionBarRoot>
+
+    // Com controle de estado
+  + <SelectionBarRoot
+  +   open={open}
+  +   onOpenChange={(newOpen) => {
+  +     setOpen(newOpen)
+  +     if (!newOpen) setSelectedItems([])
+  +   }}
+  + >
+  ```
 
 ## 3.1.1
 
 ### Patch Changes
 
 - 6ff314b: fix progress text view
+- ffe201e: Add error state and disabled state in otp input
 
 ## 3.1.0