Skip to content

README.md

Latest commit

 

History

History
315 lines (232 loc) · 10.1 KB

README.md

File metadata and controls

315 lines (232 loc) · 10.1 KB
AppDimens - Design Responsivo em Todos os Dispositivos

📐 AppDimens

Dimensões Responsivas Inteligentes para Qualquer Tela

Versão Licença Plataforma Estratégias

📚 Documentação | ⚡ Referência Rápida | 🔬 Detalhes Técnicos

Idiomas: English | Português (BR) | Español

🆕 Novidades na Versão 2.0

🎯 13 Estratégias de Escalonamento (eram apenas 2!)

  • BALANCED ⭐ Nova estratégia primária recomendada - híbrida linear-logarítmica
  • DEFAULT (antiga Fixed) - logarítmica com compensação de AR (recomendação secundária)
  • PERCENTAGE (antiga Dynamic) - escalonamento proporcional
  • LOGARITHMIC - psicofísica pura de Weber-Fechner
  • POWER - Lei de Potência de Stevens (configurável)
  • FLUID - Similar ao CSS clamp com breakpoints
  • Mais 7: INTERPOLATED, DIAGONAL, PERIMETER, FIT, FILL, AUTOSIZE 🆕, NONE

🧠 Sistema de Inferência Inteligente

  • Seleção automática de estratégia baseada no tipo de elemento
  • 18 tipos de elemento (BUTTON, TEXT, ICON, CONTAINER, etc.)
  • 8 categorias de dispositivo (PHONE_SMALL até TV)
  • Sistema de decisão baseado em pesos

⚡ Melhoria de Performance de 5x

  • Cache unificado lock-free (0.001µs)
  • Tabela de lookup para ln() (10-20x mais rápido)
  • Constantes pré-calculadas
  • Algoritmos de busca binária (O(log n))

♻️ Compatibilidade entre artefatos

  • Pacotes antigos podem ainda expor .fxdp/.dydp — confira o changelog da dependência que você usa
  • Para Android Compose novo, siga o appdimens-dynamic 3.x (sdp, asdp, …); veja PLATFORM_API_MAP.md (inglês)

⚡ Visão Geral Rápida

AppDimens faz seus elementos de UI escalonarem perfeitamente em todos os dispositivos - de telefones a tablets, TVs, relógios e navegadores web.

Em vez de tamanhos fixos que parecem minúsculos em tablets ou enormes em relógios, AppDimens usa escalonamento perceptual baseado em pesquisa psicofísica (Weber-Fechner, Stevens) que adapta inteligentemente ao tamanho da tela, proporção e tipo de dispositivo.

Por que AppDimens 2.0?

❌ Sem AppDimens:
   Telefone (360dp): Botão = 48dp (13% da tela) ✅ Bom
   Tablet (720dp): Botão = 48dp (7% da tela)  ❌ Muito pequeno!

❌ Com Escalonamento Linear (SDP):
   Telefone (360dp): Botão = 58dp (16% da tela) ✅ OK
   Tablet (720dp): Botão = 115dp (16% da tela) ❌ Muito grande!

✅ Com AppDimens BALANCED ⭐:
   Telefone (360dp): Botão = 58dp (16% da tela) ✅ Perfeito
   Tablet (720dp): Botão = 70dp (10% da tela) ✅ Perfeito!

Benefícios Principais

  • ✅ Proporções perfeitas em qualquer tamanho de tela
  • ✅ Funciona em todo lugar: Android, iOS, Flutter, React Native, Web
  • ✅ API por plataforma: tokens sdp/asdp no Android Compose; balanced() no iOS/Web/RN; AppDimens.fixed/dynamic no Flutter
  • ✅ Cientificamente comprovado: Baseado em pesquisa psicofísica (Weber-Fechner, Stevens)
  • ✅ Melhor performance: 5x mais rápido com cache lock-free e otimizações
  • ✅ 13 estratégias: Do simples ao avançado, cobrindo todos os casos de uso
  • ✅ Inferência Inteligente: Seleção automática de estratégia para 18 tipos de elemento
  • ✅ Unidades físicas: Medidas do mundo real (mm, cm, polegadas) em todas as plataformas
  • ✅ Desenvolvimento de jogos: Módulos especializados para Android (C++/NDK) e iOS (Metal)
  • ✅ AutoSize 🆕: Auto-dimensionamento com consciência de container como TextView autoSizeText

🚀 Instalação

Android

dependencies {
    implementation("io.github.bodenberg:appdimens-dynamic:2.0.1")
    implementation("io.github.bodenberg:appdimens-sdps:2.0.1")
    implementation("io.github.bodenberg:appdimens-ssps:2.0.1")
    implementation("io.github.bodenberg:appdimens-all:2.0.1")
    implementation("io.github.bodenberg:appdimens-games:2.0.1")
}

iOS

pod 'AppDimens', '~> 2.0.0'

Flutter

dependencies:
  appdimens: ^2.0.0

React Native

npm install appdimens-react-native@2.0.0

Web

npm install webdimens@2.0.0

📖 Guia Completo de Instalação

💡 Uso Básico

Android (Jetpack Compose)

@Composable
fun MeuCard() {
    Card(
        modifier = Modifier
            .width(300.wdp)      // ✨ BALANCED (RECOMENDADO) ⭐
            .padding(16.sdp)
    ) {
        Text(
            text = "Olá Mundo",
            fontSize = 18.ssp
        )
    }
}

iOS (SwiftUI)

struct MeuCard: View {
    var body: some View {
        VStack {
            Text("Olá Mundo")
                .font(.system(size: AppDimens.shared.balanced(18).toPoints()))
        }
        .padding(AppDimens.shared.balanced(16).toPoints())
        .frame(width: AppDimens.shared.balanced(300).toPoints())
    }
}

Flutter

Widget build(BuildContext context) {
  return Container(
    width: AppDimens.fixed(300).calculate(context),
    padding: EdgeInsets.all(AppDimens.fixed(16).calculate(context)),
    child: Text(
      'Olá Mundo',
      style: TextStyle(fontSize: AppDimens.fixed(18).calculate(context)),
    ),
  );
}

React Native

{% raw %}

function MeuCard() {
  const { balanced } = useAppDimens();
  
  return (
    <View style={{ width: balanced(300), padding: balanced(16) }}>
      <Text style={{ fontSize: balanced(18) }}>
        Olá Mundo
      </Text>
    </View>
  );
}

{% endraw %}

Web (React)

{% raw %}

import { useWebDimens } from 'webdimens/react';

function MeuCard() {
  const { balanced } = useWebDimens();
  
  return (
    <div style={{ width: balanced(300), padding: balanced(16) }}>
      <h2 style={{ fontSize: balanced(18) }}>Olá Mundo</h2>
    </div>
  );
}

{% endraw %}

🎯 Estratégias de Escalonamento

Estratégia Quando Usar Exemplo Disponibilidade
BALANCED ⭐ RECOMENDADO 95% dos casos - apps multi-dispositivo (telefones, tablets, TVs) 48.sdp Todas as plataformas
DEFAULT (Secundário) Apps focados em telefones, ícones, compatibilidade 48.sdp Todas as plataformas
PERCENTAGE Containers grandes, grids de largura total, elementos proporcionais Android Compose: 300.wdp (eixo de largura); iOS/Web/RN: percentage(...) nos builders Todas as plataformas
LOGARITHMIC Apps de TV, controle máximo em telas grandes 48.logarithmic() Todas as plataformas
POWER Uso geral, configurável com expoente 48.power(0.75) Todas as plataformas
FLUID 🌊 Tipografia, espaçamento com transições suaves min/max fluid(16, 24) Todas as plataformas

📖 Entendendo as Estratégias de Escalonamento

🏆 Por que AppDimens é #1

AppDimens foi cientificamente comparado contra 7 outras abordagens de escalonamento:

🥇 #1 AppDimens BALANCED: 93/100 ⭐⭐⭐⭐⭐ (Recomendação primária)
🥈 #2 AppDimens LOGARITHMIC: 88/100 ⭐⭐⭐⭐⭐ (TV/Tablets grandes)
🥉 #3 AppDimens POWER: 86/100 ⭐⭐⭐⭐
   #4 AppDimens DEFAULT: 82/100 ⭐⭐⭐⭐ (Focado em telefones)
   #5 SDP/SSP: 65/100
   #6 CSS vw/vh: 58/100

O Que Torna Melhor?

  • ✅ Estratégia BALANCED: Híbrida linear-logarítmica (40% de redução de oversizing)
  • ✅ Modelos perceptuais: Baseado em psicofísica (Weber-Fechner, Stevens)
  • ✅ 13 estratégias: Biblioteca mais abrangente
  • ✅ Inferência Inteligente: Seleção automática de estratégia
  • ✅ 5x mais rápido: Cache lock-free e otimizações
  • ✅ Compensação de aspect ratio: Única biblioteca com ajuste de AR (estratégia DEFAULT)

📊 Ver Comparação Completa

📚 Documentação

Primeiros Passos

  1. Referência Rápida ⚡ Encontre qualquer coisa em segundos
  2. Guia Simplificado 📖 Entenda em 15 minutos
  3. Exemplos 💻 Código pronto para usar

Documentação Técnica

  1. Guia Técnico Completo 🔬 Tudo em um lugar (2h de leitura)
  2. Comparação de Fórmulas 📊 Análise científica & rankings
  3. Teoria Matemática 📐 Fundação matemática formal

Guias por Plataforma

📚 Índice Completo da Documentação

🤝 Contribuindo

Contribuições são bem-vindas!

📖 Guia de Contribuição

📄 Licença

Apache License 2.0 - veja o arquivo LICENSE

👨‍💻 Autor

Jean Bodenberg

Feito com ❤️ para desenvolvedores no mundo todo

Documentação • Exemplos • Guia Técnico