dwv-ui 0.1.0

package/guidelines/overview-components.md

@@ -0,0 +1,305 @@
+# Padrões de Componentes
+
+Este documento define como componentes React devem ser criados para o projeto DWV.
+
+---
+
+## Estrutura de Arquivos
+
+### Componente Simples (sem variação estrutural)
+
+```
+ComponentName/
+├── index.tsx           # Type Props + Componente + Export
+├── styles/
+│   └── variants.ts     # CVA variants (se houver)
+└── primitives/         # Componentes auxiliares (se houver)
+    └── ComponentIcon.tsx
+```
+
+### Componente com Variação Estrutural
+
+Quando existem variações que mudam drasticamente a estrutura (ex: Select vs SearchableSelect):
+
+```
+ComponentName/
+├── index.ts            # Public API (apenas exports)
+├── mod/                # Variações estruturais
+│   ├── ComponentName.tsx
+│   └── SearchableComponentName.tsx
+├── styles/
+│   └── variants.ts     # CVA variants compartilhados
+└── primitives/         # Partes reutilizáveis
+    ├── Trigger.tsx
+    └── Content.tsx
+```
+
+---
+
+## Declaração de Componente
+
+### Padrão Obrigatório
+
+```typescript
+// Arrow function, sem React.FC
+const Button = ({ children, variant, className, ...props }: Props) => (
+  <button className={cn(buttonVariants({ variant }), className)} {...props}>
+    {children}
+  </button>
+);
+
+export { Button };
+```
+
+### Proibido
+
+```typescript
+// React.FC - NÃO USAR
+const Button: React.FC<Props> = ({ children }) => ...
+
+// function declaration - NÃO USAR
+function Button({ children }: Props) { ... }
+
+// export default - NÃO USAR
+export default Button
+```
+
+---
+
+## Tipagem de Props
+
+### Props no index.tsx (nome simples)
+
+```typescript
+type Props = ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: ReactNode;
+  variant?: "primary" | "outline";
+  icon?: IconProps;
+};
+```
+
+### Props em types.ts (nome completo)
+
+Quando separar em arquivo próprio:
+
+```typescript
+// types.ts
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: ReactNode;
+  variant?: "primary" | "outline";
+};
+
+export type { ButtonProps };
+```
+
+### Intersecção com HTML Attributes
+
+Herdar de HTML quando faz sentido:
+
+```typescript
+// Input herda de InputHTMLAttributes
+type Props = InputHTMLAttributes<HTMLInputElement> & {
+  label?: string;
+  error?: string;
+};
+
+// Div container herda de HTMLAttributes
+type Props = HTMLAttributes<HTMLDivElement> & {
+  title: string;
+};
+```
+
+### Acesso Externo Granular
+
+Quando componente tem partes que precisam de customização:
+
+```typescript
+type Props = InputHTMLAttributes<HTMLInputElement> & {
+  label?: string;
+  error?: string;
+  wrapperAttr?: HTMLAttributes<HTMLDivElement>;
+  errorAttr?: HTMLAttributes<HTMLParagraphElement>;
+};
+```
+
+---
+
+## Ref em Componentes
+
+Componentes de ação (Button, Input, etc) devem aceitar ref.
+
+### React 19+ (ref como prop)
+
+```typescript
+type Props = ButtonHTMLAttributes<HTMLButtonElement> & {
+  ref?: React.Ref<HTMLButtonElement>;
+  children: ReactNode;
+};
+
+const Button = ({ children, ref, ...props }: Props) => (
+  <button ref={ref} {...props}>
+    {children}
+  </button>
+);
+```
+
+### React 18 (forwardRef)
+
+```typescript
+const SelectTrigger = React.forwardRef<
+  React.ComponentRef<typeof SelectPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Trigger ref={ref} className={cn(...)} {...props} />
+))
+SelectTrigger.displayName = 'SelectTrigger'
+```
+
+---
+
+## Ordem dos Elementos
+
+Dentro de um arquivo de componente:
+
+```typescript
+// 1. Imports (externos primeiro, depois aliases internos, depois relativos)
+import { useState, type ReactNode } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@shared/lib";
+import { buttonVariants } from "./styles/variants";
+import { ButtonIcon } from "./primitives/ButtonIcon";
+
+// 2. Types
+type Props = VariantProps<typeof buttonVariants> & {
+  children: ReactNode;
+  icon?: IconType;
+  className?: string;
+};
+
+// 3. Componente principal
+const Button = ({
+  children,
+  variant,
+  size,
+  icon,
+  className,
+  ...props
+}: Props) => (
+  <button
+    className={cn(buttonVariants({ variant, size }), className)}
+    {...props}
+  >
+    {icon && <ButtonIcon type={icon} position="left" />}
+    {children}
+  </button>
+);
+
+// 4. Export nomeado
+export { Button };
+export type { Props as ButtonProps };
+```
+
+---
+
+## Componentes Auxiliares (Primitives)
+
+Quando um componente tem partes reutilizáveis:
+
+```typescript
+// primitives/ButtonIcon.tsx
+const buttonIcons = {
+  download: FiDownload,
+  add: FiPlus,
+  edit: FiEdit,
+};
+
+type Props = {
+  type: keyof typeof buttonIcons | React.ComponentType;
+  position: "left" | "right";
+};
+
+const ButtonIcon = ({ type, ...props }: Props) => {
+  const Icon = typeof type === "string" ? buttonIcons[type] : type;
+  return <Icon {...props} />;
+};
+
+export { ButtonIcon };
+```
+
+---
+
+## Barrel Files (index.ts)
+
+### Componente simples (tudo no index.tsx)
+
+O próprio `index.tsx` já exporta o componente.
+
+### Componente com variações (index.ts separado)
+
+```typescript
+// index.ts
+export { Select } from "./mod/Select";
+export { SearchableSelect } from "./mod/SearchableSelect";
+export type { SelectProps, SelectOption } from "./types";
+```
+
+---
+
+## Exemplos Completos
+
+### Badge
+
+```typescript
+// Badge/index.tsx
+import { cn } from "@shared/lib";
+import { badgeVariants } from "./styles/variants.ts";
+
+type Props = VariantProps<typeof badgeVariants> & {
+  children: ReactNode;
+  className?: string;
+};
+
+const Badge = ({ children, variant, className }: Props) => (
+  <span className={cn(badgeVariants({ variant }), className)}>{children}</span>
+);
+
+export { Badge };
+```
+
+### Button
+
+```typescript
+// Button/index.tsx
+import { ButtonHTMLAttributes, ReactNode } from "react";
+import { IconType } from "react-icons";
+import { buttonVariants } from "./styles/variants.ts";
+import { ButtonIcon, buttonIcons } from "./primitives";
+
+type IconProps = {
+  type: keyof typeof buttonIcons | IconType;
+  position: "left" | "right";
+  size?: number;
+  color?: string;
+  className?: string;
+};
+
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> &
+  VariantProps<typeof buttonVariants> & {
+    children: ReactNode;
+    icon?: IconProps;
+  };
+
+const Button = ({
+  children,
+  variant,
+  className,
+  icon,
+  ...props
+}: ButtonProps) => (
+  <button className={buttonVariants({ variant, className })} {...props}>
+    {!!icon && icon.position === "left" && <ButtonIcon {...icon} />}
+    {children}
+    {!!icon && icon.position === "right" && <ButtonIcon {...icon} />}
+  </button>
+);
+```

package/guidelines/overview-styling.md

@@ -0,0 +1,154 @@
+# Sistema de Estilização
+
+Este documento define como componentes devem ser estilizados no projeto DWV.
+
+---
+
+## Stack de Estilização
+
+| Ferramenta                         | Propósito                           |
+| ---------------------------------- | ----------------------------------- |
+| **Tailwind CSS**                   | Utility-first CSS framework         |
+| **CVA** (class-variance-authority) | Gerenciar variantes de componentes  |
+| **tailwind-merge**                 | Resolver conflitos de classes       |
+| **cn()**                           | Função helper para merge de classes |
+
+---
+
+## Função cn()
+
+Sempre usar `cn()` para combinar classes Tailwind. Ela faz merge inteligente e resolve conflitos.
+
+### Implementação
+
+```typescript
+import { cx } from "class-variance-authority";
+import { twMerge } from "tailwind-merge";
+
+type ClassValue = string | number | boolean | undefined | null | ClassValue[];
+
+export const cn = (...classes: ClassValue[]) => twMerge(cx(classes));
+```
+
+### Uso
+
+```typescript
+// Sempre usar cn() para classes
+<div className={cn('flex gap-4', isActive && 'bg-brand-100', className)} />
+
+// Nunca concatenar strings diretamente
+<div className={`flex gap-4 ${isActive ? 'bg-brand-100' : ''}`} /> // ERRADO
+```
+
+---
+
+## CVA (Class Variance Authority)
+
+Usar CVA para componentes com variantes (variant, size, etc).
+
+### Estrutura Básica
+
+```typescript
+import { cva, type VariantProps } from "class-variance-authority";
+
+const buttonVariants = cva(
+  // Classes base (sempre aplicadas)
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors",
+  {
+    variants: {
+      // Cada variante é uma prop do componente
+      variant: {
+        primary: "bg-brand-600 text-white hover:bg-brand-700",
+        outline: "border border-neutral-300 bg-transparent hover:bg-neutral-50",
+        link: "text-brand-600 underline-offset-4 hover:underline",
+      },
+      size: {
+        sm: "h-8 px-3 text-sm",
+        md: "h-10 px-4 text-sm",
+        lg: "h-12 px-6 text-base",
+      },
+    },
+    // Valores padrão
+    defaultVariants: {
+      variant: "primary",
+      size: "md",
+    },
+  }
+);
+```
+
+### Organização e uso
+
+```
+Button/
+├── index.tsx
+└── styles/
+    └── variants.ts
+```
+
+```typescript
+// styles/variants.ts
+import { cva } from 'class-variance-authority'
+const buttonVariants = cva(...)
+export { buttonVariants }
+```
+
+```typescript
+// index.tsx
+import { buttonVariants } from "./styles/variants.ts";
+
+type Props = VariantProps<typeof buttonVariants> & {
+  children: ReactNode;
+  className?: string;
+};
+
+const Button = ({ children, variant, size, className, ...props }: Props) => (
+  <button
+    className={cn(buttonVariants({ variant, size }), className)}
+    {...props}
+  >
+    {children}
+  </button>
+);
+```
+
+## Estilos condicionais
+
+**NUNCA usar condicionais diretas no className:**
+
+```typescript
+// ❌ Proibido
+<div className={isActive ? 'text-white' : 'text-brand'} />
+<div className={isHidden && 'hidden'} />
+<div className={`${isOpen ? 'opacity-100' : 'opacity-0'}`} />
+```
+
+**SEMPRE usar `data-` attributes:**
+
+```typescript
+// ✅ Correto
+<Button
+  data-hidden={!!isButtonHidden}
+  className={cn(
+    'flex flex-1 text-white bg-brand',
+    'data-[hidden=true]:hidden'
+  )}
+/>
+
+<div
+  data-active={!!isActive}
+  className={cn(
+    'px-4 py-2 rounded',
+    'data-[active=true]:bg-brand data-[active=true]:text-white',
+    'data-[active=false]:bg-neutral-100 data-[active=false]:text-neutral-600'
+  )}
+/>
+```
+
+**Regras:**
+
+| Regra        | Descrição                                                            |
+| ------------ | -------------------------------------------------------------------- |
+| Prefixo `!!` | Sempre usar para garantir valor booleano                             |
+| Separação    | Estilos condicionais separados dos base via `cn()`                   |
+| Nomenclatura | `data-[nome]` descritivo: `hidden`, `active`, `selected`, `disabled` |

package/guidelines/overview-theme.md

@@ -0,0 +1,204 @@
+# Tema do Projeto
+
+Este documento define os tokens de design do projeto DWV, na maioria dos casos o próprio design dos componentes no Figma informa qual token correto usar, mas em outros casos será necessário mapear o token pela cor hexadecimal.
+
+---
+
+## Cores
+
+### Brand (Cor Primária - Vermelho)
+
+| Token       | Hex     | Uso                    |
+| ----------- | ------- | ---------------------- |
+| `brand-100` | #ffdddd | Backgrounds sutis      |
+| `brand-200` | #ffc0c0 | Backgrounds hover      |
+| `brand-300` | #ff9494 | Borders                |
+| `brand-400` | #ff5757 | Estados intermediários |
+| `brand-500` | #ff2323 | Cor principal          |
+| `brand-600` | #d70000 | **Botões primários**   |
+| `brand-700` | #b10303 | Hover de botões        |
+| `brand-800` | #920A0A | Estados ativos         |
+| `brand-900` | #500000 | Textos de ênfase       |
+
+### Neutral (Cinzas)
+
+| Token          | Hex     | Uso                |
+| -------------- | ------- | ------------------ |
+| `neutral-0`    | #ffffff | Background branco  |
+| `neutral-50`   | #F9F9FA | Background sutil   |
+| `neutral-100`  | #F5F5F6 | Background cards   |
+| `neutral-200`  | #E6E6E7 | Borders leves      |
+| `neutral-300`  | #CFCFD2 | Borders            |
+| `neutral-400`  | #AEADB3 | Placeholders       |
+| `neutral-500`  | #85848C | Textos secundários |
+| `neutral-600`  | #6A6971 | Textos             |
+| `neutral-700`  | #5B5A60 | Textos importantes |
+| `neutral-800`  | #4D4C51 | Títulos            |
+| `neutral-900`  | #444347 | Títulos fortes     |
+| `neutral-1000` | #363538 | Textos escuros     |
+
+### Dark (Modo Escuro)
+
+| Token      | Hex     | Uso                    |
+| ---------- | ------- | ---------------------- |
+| `dark-100` | #2C2C2E | Cards dark mode        |
+| `dark-200` | #202021 | Background dark        |
+| `dark-300` | #161618 | Background mais escuro |
+
+### Green (Sucesso)
+
+| Token       | Hex     | Uso               |
+| ----------- | ------- | ----------------- |
+| `green-100` | #DFF9E2 | Background sutil  |
+| `green-200` | #C1F1C7 | Background        |
+| `green-300` | #91E49B | Borders           |
+| `green-400` | #5ACE69 | Estados           |
+| `green-500` | #33B444 | **Cor principal** |
+| `green-600` | #28A138 | Hover             |
+| `green-700` | #20752C | Textos            |
+| `green-800` | #1B4C22 | -                 |
+| `green-900` | #092A0F | -                 |
+
+### Yellow (Aviso)
+
+| Token        | Hex     | Uso               |
+| ------------ | ------- | ----------------- |
+| `yellow-100` | #FFFDC5 | Background sutil  |
+| `yellow-200` | #FFFA87 | Background        |
+| `yellow-300` | #FFF148 | Borders           |
+| `yellow-400` | #FFE31E | Estados           |
+| `yellow-500` | #FCC404 | **Cor principal** |
+| `yellow-600` | #E69D00 | Hover             |
+| `yellow-700` | #b96d04 | Textos            |
+
+### Orange (Alerta e erros)
+
+| Token        | Hex     | Uso               |
+| ------------ | ------- | ----------------- |
+| `orange-100` | #FFEDD3 | Background sutil  |
+| `orange-200` | #FFD8A5 | Background        |
+| `orange-300` | #FFBB6D | Borders           |
+| `orange-400` | #FF9232 | Estados           |
+| `orange-500` | #FF720A | **Cor principal** |
+| `orange-600` | #F05906 | Hover             |
+| `orange-700` | #C74207 | Textos            |
+
+### Blue (Informação)
+
+| Token      | Hex     | Uso               |
+| ---------- | ------- | ----------------- |
+| `blue-100` | #E0EFFE | Background sutil  |
+| `blue-200` | #BADFFD | Background        |
+| `blue-300` | #7CC6FD | Borders           |
+| `blue-400` | #37AAF9 | Estados           |
+| `blue-500` | #0D8FEA | **Cor principal** |
+| `blue-600` | #0172CB | Hover             |
+| `blue-700` | #0259A2 | Textos            |
+| `blue-800` | #0B406F | -                 |
+| `blue-900` | #082849 | -                 |
+
+### Pink
+
+| Token      | Hex     |
+| ---------- | ------- |
+| `pink-100` | #FDE4F8 |
+| `pink-500` | #F479D8 |
+| `pink-700` | #D025B7 |
+
+### Overlay
+
+```typescript
+"bg-overlay-100"; // #0A0A0CD9 - overlay escuro com transparência
+```
+
+---
+
+## Espaçamentos
+
+Base de 4px. Escala completa:
+
+| Token | Valor   | Pixels |
+| ----- | ------- | ------ |
+| `0`   | 0       | 0px    |
+| `px`  | 1px     | 1px    |
+| `1`   | 0.25rem | 4px    |
+| `2`   | 0.5rem  | 8px    |
+| `3`   | 0.75rem | 12px   |
+| `4`   | 1rem    | 16px   |
+| `5`   | 1.25rem | 20px   |
+| `6`   | 1.5rem  | 24px   |
+| `7`   | 1.75rem | 28px   |
+| `8`   | 2rem    | 32px   |
+| `9`   | 2.25rem | 36px   |
+| `10`  | 2.5rem  | 40px   |
+| `11`  | 2.75rem | 44px   |
+| `12`  | 3rem    | 48px   |
+| `14`  | 3.5rem  | 56px   |
+| `16`  | 4rem    | 64px   |
+| `20`  | 5rem    | 80px   |
+| `24`  | 6rem    | 96px   |
+
+---
+
+## Border Radius
+
+| Token          | Valor     | Pixels  |
+| -------------- | --------- | ------- |
+| `rounded-none` | 0         | 0px     |
+| `rounded-sm`   | 0.3125rem | 5px     |
+| `rounded-md`   | 0.625rem  | 10px    |
+| `rounded-lg`   | 0.9375rem | 15px    |
+| `rounded-full` | 50%       | Círculo |
+
+---
+
+## Tipografia
+
+### Font Family
+
+```typescript
+"font-roboto"; // Roboto, sans-serif (fonte principal)
+```
+
+### Line Height
+
+| Token            | Valor |
+| ---------------- | ----- |
+| `leading-none`   | 1     |
+| `leading-tight`  | 1.2   |
+| `leading-normal` | 1.5   |
+
+---
+
+## Breakpoints
+
+| Token | Valor | Pixels |
+| ----- | ----- | ------ |
+| `sm`  | 30em  | 480px  |
+| `md`  | 48em  | 768px  |
+| `lg`  | 62em  | 992px  |
+| `xl`  | 80em  | 1280px |
+| `2xl` | 96em  | 1536px |
+| `3xl` | 120em | 1920px |
+
+---
+
+## Animações
+
+### Keyframes disponíveis
+
+| Nome                    | Descrição                  |
+| ----------------------- | -------------------------- |
+| `fade-in`               | Aparece com fade           |
+| `fade-out`              | Desaparece com fade        |
+| `scale-in`              | Aparece com zoom           |
+| `scale-out`             | Desaparece com zoom        |
+| `slide-in-from-bottom`  | Entra de baixo             |
+| `slide-out-from-bottom` | Sai para baixo             |
+| `slide-in-from-top`     | Entra de cima              |
+| `slide-out-from-top`    | Sai para cima              |
+| `slide-in-from-left`    | Entra da esquerda          |
+| `slide-out-from-left`   | Sai para esquerda          |
+| `slide-in-from-right`   | Entra da direita           |
+| `slide-out-from-right`  | Sai para direita           |
+| `infinite-scroll`       | Scroll infinito horizontal |