@etus/ui 0.1.0

package/src/components/data-display/Callout/Callout.variants.ts

@@ -0,0 +1,48 @@
+// Callout/Callout.variants.ts
+import { cva, type VariantProps } from "class-variance-authority"
+
+/**
+ * Callout style variants using CVA
+ *
+ * @see https://cva.style/docs
+ */
+export const calloutVariants = cva(
+  // Base styles (always applied)
+  "rounded-[var(--callout-root-radius)] border-l-[length:var(--callout-root-border-width)]",
+  {
+    variants: {
+      variant: {
+        default: "bg-muted/50 border-l-muted-foreground",
+        info: "bg-info-bg border-l-info",
+        warning: "bg-warning-bg border-l-warning",
+        error: "bg-error-bg border-l-error",
+        success: "bg-success-bg border-l-success",
+        tip: "bg-tip-bg border-l-tip",
+      },
+      size: {
+        sm: "p-[var(--callout-root-padding-sm)] text-[length:var(--callout-text-sm)]",
+        md: "p-[var(--callout-root-padding-md)] text-[length:var(--callout-text-md)]",
+        lg: "p-[var(--callout-root-padding-lg)] text-[length:var(--callout-text-lg)]",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "md",
+    },
+  }
+)
+
+/**
+ * Icon color mapping by variant
+ */
+export const iconColorVariants: Record<string, string> = {
+  default: "text-muted-foreground",
+  info: "text-info",
+  warning: "text-warning",
+  error: "text-error",
+  success: "text-success",
+  tip: "text-tip",
+}
+
+// Export variant prop types
+export type CalloutVariantProps = VariantProps<typeof calloutVariants>

package/src/components/data-display/Callout/README.md

@@ -0,0 +1,341 @@
+# Callout
+
+## Visão Geral
+
+O Callout e um componente de destaque inline usado para chamar atencao para informacoes importantes dentro do conteudo. Diferente de banners e alertas, callouts sao integrados ao fluxo do texto e nao requerem acao do usuario.
+
+### Classificacao Atomica
+- **Categoria**: Molecules
+- **Subcategoria**: Data Display / Feedback
+
+### Casos de Uso Comuns
+- Notas e dicas em documentacao
+- Avisos importantes em formularios
+- Informacoes complementares
+- Citacoes e highlights
+- Alertas contextuais
+- Mensagens de depreciacao
+
+### Relacao com Outros Componentes
+- **Alert**: Para alertas que requerem atencao
+- **Banner**: Para mensagens site-wide
+- **Card**: Container mais generico
+- **Tooltip**: Para informacoes on-demand
+
+## Design Specs
+
+### Variantes
+
+| Variante | Cor | Uso |
+|----------|-----|-----|
+| `default` | Gray | Notas gerais |
+| `info` | Blue | Dicas e informacoes |
+| `warning` | Yellow | Avisos |
+| `error` | Red | Erros e problemas |
+| `success` | Green | Boas praticas |
+| `tip` | Purple | Dicas especiais |
+
+### Tamanhos
+
+| Tamanho | Padding | Uso |
+|---------|---------|-----|
+| `sm` | `p-3` | Inline em texto |
+| `md` | `p-4` | Padrao |
+| `lg` | `p-6` | Destaque maior |
+
+### Estados
+
+- **Default**: Callout visivel
+- **Collapsible**: Pode ser minimizado
+- **Bordered**: Com borda lateral
+
+### Tokens de Design
+
+#### Cores (por variante)
+- Background: `bg-{variant}/10`
+- Border (left): `border-l-{variant}` (4px)
+- Icon: `text-{variant}`
+- Title: `text-foreground`
+- Text: `text-muted-foreground`
+
+#### Espacamento
+- Padding: `p-4`
+- Border Left: `border-l-4`
+- Icon-Title Gap: `gap-2`
+- Title-Content Gap: `gap-1`
+
+#### Tipografia
+- Title: `text-sm font-medium`
+- Content: `text-sm`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "info" \| "warning" \| "error" \| "success" \| "tip"` | `"default"` | Estilo visual |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho |
+| `title` | `string` | - | Titulo opcional |
+| `icon` | `ReactNode` | auto | Icone (auto por variante) |
+| `collapsible` | `boolean` | `false` | Pode ser minimizado |
+| `defaultOpen` | `boolean` | `true` | Estado inicial |
+| `className` | `string` | `""` | Classes adicionais |
+| `children` | `ReactNode` | - | Conteudo |
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Callout } from '@etus/ui'
+
+function BasicCallout() {
+  return (
+    <Callout variant="info" title="Nota">
+      Esta funcionalidade esta disponivel apenas para usuarios premium.
+    </Callout>
+  )
+}
+```
+
+### Variantes
+
+```tsx
+function CalloutVariants() {
+  return (
+    <div className="space-y-4">
+      <Callout variant="default" title="Nota">
+        Uma nota geral para o usuario.
+      </Callout>
+
+      <Callout variant="info" title="Informacao">
+        Dica util sobre como usar o recurso.
+      </Callout>
+
+      <Callout variant="warning" title="Atencao">
+        Cuidado ao realizar esta acao.
+      </Callout>
+
+      <Callout variant="error" title="Erro">
+        Esta operacao nao e permitida.
+      </Callout>
+
+      <Callout variant="success" title="Boa pratica">
+        Recomendamos usar esta abordagem.
+      </Callout>
+
+      <Callout variant="tip" title="Dica">
+        Atalho: use Ctrl+K para abrir a busca.
+      </Callout>
+    </div>
+  )
+}
+```
+
+### Em Documentacao
+
+```tsx
+function DocumentationExample() {
+  return (
+    <article className="prose">
+      <h2>Instalacao</h2>
+      <p>Para instalar o pacote, execute:</p>
+      <pre>npm install @etus/ui</pre>
+
+      <Callout variant="warning" title="Requisitos">
+        React 18 ou superior e obrigatorio para usar este pacote.
+      </Callout>
+
+      <h2>Configuracao</h2>
+      <p>Apos a instalacao, configure o tema...</p>
+
+      <Callout variant="tip" title="Dica Pro">
+        Use o CLI do Shadcn para adicionar componentes rapidamente:
+        <code>npx shadcn add button</code>
+      </Callout>
+    </article>
+  )
+}
+```
+
+### Collapsible
+
+```tsx
+function CollapsibleCallout() {
+  return (
+    <Callout
+      variant="info"
+      title="Detalhes tecnicos"
+      collapsible
+      defaultOpen={false}
+    >
+      <p>
+        A implementacao usa React Server Components quando disponivel,
+        com fallback para client-side rendering. O bundle e tree-shakeable
+        e suporta code splitting automatico.
+      </p>
+    </Callout>
+  )
+}
+```
+
+### Sem Titulo
+
+```tsx
+function SimplCallout() {
+  return (
+    <Callout variant="warning">
+      Esta versao sera descontinuada em janeiro de 2025.
+      Migre para a versao 2.0 o mais rapido possivel.
+    </Callout>
+  )
+}
+```
+
+### Implementacao
+
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority'
+import { Info, TriangleAlert, CircleX, CircleCheck, Lightbulb, FileText } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const calloutVariants = cva(
+  'rounded-lg border-l-4 p-4',
+  {
+    variants: {
+      variant: {
+        default: 'bg-muted/50 border-l-muted-foreground',
+        info: 'bg-blue-500/10 border-l-blue-500',
+        warning: 'bg-yellow-500/10 border-l-yellow-500',
+        error: 'bg-red-500/10 border-l-red-500',
+        success: 'bg-green-500/10 border-l-green-500',
+        tip: 'bg-purple-500/10 border-l-purple-500',
+      },
+      size: {
+        sm: 'p-3 text-xs',
+        md: 'p-4 text-sm',
+        lg: 'p-6 text-base',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'md',
+    },
+  }
+)
+
+const variantIcons = {
+  default: FileText,
+  info: Info,
+  warning: TriangleAlert,
+  error: CircleX,
+  success: CircleCheck,
+  tip: Lightbulb,
+}
+
+interface CalloutProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof calloutVariants> {
+  title?: string
+  icon?: React.ReactNode
+}
+
+function Callout({
+  className,
+  variant = 'default',
+  size,
+  title,
+  icon,
+  children,
+  ...props
+}: CalloutProps) {
+  const Icon = variantIcons[variant ?? 'default']
+
+  return (
+    <div
+      data-slot="callout"
+      className={cn(calloutVariants({ variant, size }), className)}
+      {...props}
+    >
+      <div className="flex gap-3">
+        <span className="shrink-0 mt-0.5">
+          {icon ?? <Icon className="size-4" />}
+        </span>
+        <div className="space-y-1">
+          {title && (
+            <h5 className="font-medium leading-none tracking-tight">
+              {title}
+            </h5>
+          )}
+          <div className="text-muted-foreground">{children}</div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export { Callout, calloutVariants }
+```
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="note"` para notas informativas
+- `role="alert"` para avisos importantes
+- Titulo com nivel de heading semantico se apropriado
+
+### Navegacao por Teclado
+- Conteudo focavel quando interativo
+- Links e botoes internos navegaveis
+
+### Contraste
+- Texto com contraste 4.5:1
+- Borda lateral visivel
+
+## Testes
+
+```typescript
+import { render, screen } from '@testing-library/react'
+import { Callout } from './Callout'
+
+describe('Callout', () => {
+  it('renders with title and content', () => {
+    render(
+      <Callout title="Test Title">
+        Test content
+      </Callout>
+    )
+
+    expect(screen.getByText('Test Title')).toBeInTheDocument()
+    expect(screen.getByText('Test content')).toBeInTheDocument()
+  })
+
+  it('renders without title', () => {
+    render(<Callout>Just content</Callout>)
+    expect(screen.getByText('Just content')).toBeInTheDocument()
+  })
+
+  it('applies variant styles', () => {
+    const { container } = render(
+      <Callout variant="warning">Warning</Callout>
+    )
+    expect(container.firstChild).toHaveClass('border-l-yellow-500')
+  })
+
+  it('renders custom icon', () => {
+    render(
+      <Callout icon={<span data-testid="custom-icon">!</span>}>
+        Content
+      </Callout>
+    )
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+  })
+})
+```
+
+## Referências
+
+- [MDN blockquote](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote)
+- [Docusaurus Admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
+- [Nextra Callout](https://nextra.site/docs/guide/built-ins/callout)

package/src/components/data-display/Callout/index.ts

@@ -0,0 +1,2 @@
+export type { CalloutProps, CalloutSize, CalloutVariant } from "./Callout.types"
+export { Callout, type CalloutProps as CalloutComponentProps, calloutVariants } from "./Callout"