Skip to content

README.md

Latest commit

 

History

History
430 lines (311 loc) · 11.4 KB

README.md

File metadata and controls

430 lines (311 loc) · 11.4 KB

TypeCraft Frontend - MVP

Plataforma de transformação de manuscritos em livros profissionalmente formatados usando IA

📋 Table of Contents

🎯 Overview

TypeCraft Frontend é a interface do usuário para uma plataforma SaaS que automatiza a formatação de manuscritos em livros profissionais. Com inteligência artificial, o sistema aplica formatação ABNT, APA ou IEEE em minutos.

Público-Alvo

  • Autores independentes: Publicar romances na Amazon KDP
  • Acadêmicos: Formatar TCCs, dissertações e teses
  • Editoras: Processar múltiplos livros em lote

Proposta de Valor

  • ⚡ Formatação automática em 10 minutos (vs. dias manualmente)
  • 💰 Economia de R$ 2.500+ em designers profissionais
  • ✅ 100% de conformidade com normas ABNT/APA/IEEE
  • 🎨 Customização completa de design

✨ Features

MVP Implementado

  • ✅ Landing Page: Hero, features, pricing, testimonials
  • ✅ Autenticação: NextAuth com Supabase
  • ✅ Gerenciamento de Projetos: CRUD completo
  • ✅ Upload de Manuscritos: Drag-and-drop com validação
  • ✅ Processamento AI: Integração com backend Python
  • ✅ Design Customizer: Fontes, cores, templates
  • ✅ Download de Arquivos: PDF, EPUB, MOBI
  • ✅ Internacionalização: pt-BR e en
  • ✅ Testes: Unit (40), Integration (26), E2E (34)
  • ✅ Performance: Code splitting, lazy loading, caching
  • ✅ Acessibilidade: WCAG 2.1 Level AA compliant
  • ✅ Build Status: Zero TypeScript errors

Roadmap

  • Editor de manuscritos inline
  • Colaboração em tempo real
  • Preview 3D de livro físico
  • Marketplace de templates premium
  • API pública para integração

🛠 Tech Stack

Core

  • Next.js 16: React framework com App Router
  • TypeScript: Type safety
  • Tailwind CSS: Utility-first CSS
  • React Query (TanStack Query): Server state management

Libraries

  • next-auth: Autenticação
  • next-intl: Internacionalização
  • react-hook-form: Formulários
  • zod: Validação de schemas
  • axios: HTTP client
  • react-dropzone: File upload
  • react-colorful: Color picker
  • sonner: Toast notifications
  • lucide-react: Icons

Testing

  • Jest: Unit testing
  • Testing Library: Component testing
  • Playwright: E2E testing

Dev Tools

  • ESLint: Linting com jsx-a11y para acessibilidade
  • Prettier: Code formatting
  • Husky: Git hooks (opcional)
  • Lighthouse CI: Performance budgets e monitoring

🚀 Getting Started

Prerequisites

  • Node.js 18+ e npm
  • Backend Python rodando em http://localhost:8000
  • Conta Supabase (para auth)

Installation

# Clone o repositório
git clone https://github.com/seu-usuario/typecraft.git
cd typecraft/web

# Instale dependências
npm install

# Configure variáveis de ambiente
cp .env.example .env.local
# Edite .env.local com suas credenciais

# Execute em desenvolvimento
npm run dev

Abra http://localhost:3000 no navegador.

Environment Variables

Crie .env.local:

# API Backend
NEXT_PUBLIC_API_URL=http://localhost:8000

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

📁 Project Structure

web/
├── public/               # Static assets
├── src/
│   ├── app/             # Next.js App Router pages
│   │   ├── [locale]/    # Internationalized routes
│   │   └── api/         # API routes
│   ├── components/      # React components
│   │   ├── ui/          # Reusable UI components
│   │   ├── landing/     # Landing page sections
│   │   └── lazy/        # Lazy-loaded components
│   ├── lib/             # Utilities and configurations
│   │   ├── api/         # API client
│   │   ├── hooks/       # Custom React hooks
│   │   ├── providers/   # Context providers
│   │   └── validations/ # Zod schemas
│   ├── i18n/            # Internationalization
│   └── types/           # TypeScript types
├── e2e/                 # Playwright E2E tests
├── docs/                # Documentation
└── scripts/             # Build and utility scripts

💻 Development

Available Scripts

# Development
npm run dev               # Start dev server with Turbopack
npm run build            # Build for production
npm run start            # Start production server
npm run lint             # Run ESLint

# Testing
npm test                 # Run unit tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Generate coverage report
npm run test:e2e         # Run E2E tests
npm run test:e2e:ui      # Run E2E tests with UI
npm run test:e2e:report  # Show E2E test report

# Analysis
npm run analyze          # Analyze bundle size

Code Style

  • TypeScript: Strict mode enabled
  • ESLint: Configured for Next.js + React
  • Formatting: 2 spaces, single quotes
  • Components: PascalCase, one per file
  • Hooks: Prefix with use

Git Workflow

# Create feature branch
git checkout -b feature/your-feature

# Make changes and commit
git add .
git commit -m "feat: your feature description"

# Push and create PR
git push origin feature/your-feature

🧪 Testing

Unit Tests (Jest + Testing Library)

# Run all unit tests
npm test

# Run specific test file
npm test useProjects

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage

Test Coverage:

  • 40 unit tests (hooks)
  • 26 integration tests (components)
  • Target: >80% coverage

E2E Tests (Playwright)

# Run all E2E tests
npm run test:e2e

# Run with UI mode (interactive)
npm run test:e2e:ui

# View HTML report
npm run test:e2e:report

E2E Scenarios:

  • Complete user journey
  • Manuscript upload flow
  • Design customization
  • Responsive design
  • Accessibility

⚡ Performance

Metrics Targets

  • FCP (First Contentful Paint): < 1.8s
  • LCP (Largest Contentful Paint): < 2.5s
  • TTI (Time to Interactive): < 3.8s
  • CLS (Cumulative Layout Shift): < 0.1

Optimizations Implemented

  • ✅ Code Splitting: Dynamic imports para componentes pesados
  • ✅ Lazy Loading: Componentes carregados on-demand
  • ✅ Image Optimization: Next.js Image com AVIF/WebP
  • ✅ Caching: React Query com estratégias inteligentes
  • ✅ Bundle Size: Otimização de imports e tree-shaking
  • ✅ Prefetching: Rotas críticas prefetchadas

📚 Ver PERFORMANCE.md para detalhes completos.

♿ Acessibilidade

WCAG 2.1 Level AA

TypeCraft Web foi desenvolvido com acessibilidade como prioridade:

  • ✅ SC 1.1.1 - Textos alternativos em todos os elementos não-textuais
  • ✅ SC 2.1.1 - Navegação completa por teclado
  • ✅ SC 2.1.2 - Sem armadilhas de teclado
  • ✅ SC 2.3.3 - Animações respeitam prefers-reduced-motion
  • ✅ SC 2.4.1 - Skip-to-content link implementado
  • ✅ SC 4.1.2 - ARIA roles, labels e live regions completos

Funcionalidades

  • ARIA Live Regions: Anúncios de progresso e erros
  • Keyboard Navigation: Tab order lógico em todos os componentes
  • Screen Readers: Labels descritivos e ícones decorativos marcados
  • Reduced Motion: Detecção automática de preferências de movimento
  • Color Contrast: Mínimo 4.5:1 em todo o site

📚 Ver ACCESSIBILITY.md para documentação completa.

🚢 Deployment

Vercel (Recomendado)

# Install Vercel CLI
npm i -g vercel

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Docker

# Build image
docker build -t typecraft-web .

# Run container
docker run -p 3000:3000 typecraft-web

Environment Variables (Production)

Configure no dashboard da Vercel/hosting:

  • NEXT_PUBLIC_API_URL: URL do backend em produção
  • NEXTAUTH_URL: URL do frontend em produção
  • NEXTAUTH_SECRET: Secret forte (use openssl rand -base64 32)
  • Credenciais do Supabase

🤝 Contributing

Como Contribuir

  1. Fork o projeto
  2. Crie uma feature branch
  3. Commit suas mudanças
  4. Push para a branch
  5. Abra um Pull Request

Guidelines

  • Escreva testes para novas features
  • Mantenha cobertura de testes > 80%
  • Siga o estilo de código existente
  • Documente mudanças significativas

📋 Changelog

v1.0.0 - 2025-11-01

🎯 Qualidade de Código: Limpo, Semântico, Zero Warnings

Correções Críticas (P0)

  • ✅ Stripe API Version: Atualizado para 2025-10-29.clover (compatível com stripe@19.2.0)
  • ✅ Build Production: Zero TypeScript errors, compilação bem-sucedida em 3.6s

TypeScript & Linting (P1)

  • ✅ Type Safety: Removido unsafe casting as never, substituído por type-safe readonly arrays
  • ✅ ESLint Configuration: Adicionado jsx-a11y/recommended para validação automática de acessibilidade
  • ✅ Strict Mode: Mantido TypeScript strict mode com zero erros

Acessibilidade WCAG 2.1 Level AA (P1-P2)

  • ✅ ManuscriptUpload Component:

    • ARIA roles: region, progressbar, alert, status
    • ARIA labels descritivos em todos os elementos interativos
    • ARIA live regions: polite (progresso) e assertive (erros)
    • Ícones decorativos marcados com aria-hidden="true"

  • ✅ HeroSection Component:

    • Suporte a prefers-reduced-motion com MediaQuery API
    • Animações desabilitadas automaticamente quando preferido
    • Ícones decorativos com aria-hidden="true"

  • ✅ Layout Global:

    • Skip-to-content link implementado (WCAG SC 2.4.1)
    • Navegação por teclado otimizada
    • Landmark <main> com ID para skip link

Performance (P2)

  • ✅ Font Loading:

    • Redução de 10+ famílias para 4 essenciais
    • Carregamento assíncrono com técnica media="print" + onLoad
    • ~60% de redução no tempo de carregamento de fontes
    • Preconnect para fonts.googleapis.com e fonts.gstatic.com

  • ✅ Lighthouse CI:

    • Performance budgets configurados (FCP < 2s, LCP < 2.5s)
    • Scores mínimos: Performance 90%, Accessibility 100%

  • ✅ Build Metrics:

    • Compilação: 3.6s
    • 14 páginas estáticas geradas
    • Zero warnings de produção

Documentação

  • ✅ ACCESSIBILITY.md: Documentação completa de recursos de acessibilidade
  • ✅ PERFORMANCE.md: Guia de otimizações e métricas
  • ✅ lighthouserc.json: Configuration para CI/CD com performance budgets
  • ✅ README.md: Atualizado com novas funcionalidades

Próximos Passos Sugeridos

  • Deploy to Vercel (frontend production ready)
  • Integrar Lighthouse CI no pipeline de deploy
  • Adicionar error tracking (Sentry)
  • Testes de contraste de cores automatizados

📝 License

Este projeto está sob a licença MIT. Ver LICENSE para detalhes.

👥 Team

  • Juan Carlos: Founder & Lead Developer

📞 Support

Feito com ❤️ usando Next.js 16 e TypeScript