better_ui 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c59e86ef83ec560909908edbbbecd0c33a3663df87de94e99fff0475be5b23d
-  data.tar.gz: dc7a3b578f0b2cc70f3e25c843dbc918723bf4d0b7d9bdb4b511e2ad073cc5fd
+  metadata.gz: 7b6dbaeb8dede2be21e4bcff93ba5a7793a08f9e84521c2b46bd8e879be6d072
+  data.tar.gz: b9f58c90c95a748e694018c85aff6ceeb23ecee0f155b8cb45d9b64dc78da2e1
 SHA512:
-  metadata.gz: 66fdc7a9f14ff11b0d79caaff30d1b35ba4878dbbfcbddca7571684eb3628c62288a4fff4a33416b285c479ab96ca22ed271949184c472cb36f4131270a15552
-  data.tar.gz: abaf0df7af66450518ab1620ca0fe165e411c2b96a6accfc3a49acb91a93b82c64c7093bacbb7e5e272040275b96063dee0253608a08f406d2e1122ff78cb8c3
+  metadata.gz: 7bba346a1d310e3869a232212c8708bbff5ef18f048d9361acc895efa78709b6de1e78bfee44dc3b30db77daf3cf380093331d1443b90d0bb6c18a7ad5d9e2e3
+  data.tar.gz: be0e614d6d37d86946d7908e8f2ae0ff83a452dcfc7fc1dd29c42560f77a368bab654e556e767e2d06dcf26236281b9f39987221f0bbee451ff7a16d1125cf39

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright alessiobussolari
+Copyright Umberto Peserico
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,195 +1,301 @@
-# BetterUI 🎨
+# BetterUI
 
-[![Gem Version](https://badge.fury.io/rb/better_ui.svg)](https://badge.fury.io/rb/better_ui)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+Una libreria completa di componenti UI per applicazioni Rails costruita con ViewComponent e Tailwind CSS. Include 26 componenti con un sistema di design unificato e documentazione interattiva.
 
-> Componenti UI eleganti, coerenti e facilmente integrabili per le tue applicazioni Rails
+- 🎨 **Componenti Eleganti**: Componenti UI pre-costruiti con styling Tailwind CSS
+- 📖 **Documentazione Interattiva**: Preview Lookbook integrate per tutti i componenti
+- 🔧 **Altamente Personalizzabile**: Opzioni di configurazione flessibili per ogni componente
+- 🚀 **Production Ready**: Componenti testati che seguono le best practices
+- 📱 **Responsive**: Tutti i componenti sono mobile-first e responsive
+- ♿ **Accessibile**: Costruiti pensando all'accessibilità
 
-BetterUI è una gemma Rails che fornisce componenti UI riutilizzabili con documentazione integrata. Progettata per essere leggera, personalizzabile e facile da usare, ti aiuta a costruire interfacce belle e consistenti senza JavaScript.
+## Panoramica
 
-## ✨ Caratteristiche principali
+Better UI è una gem Rails che fornisce una collezione di componenti UI riutilizzabili costruiti con ViewComponent e Tailwind CSS. Include un sistema di design unificato con tematizzazione consistente e gestione completa dei form.
 
-- **Design puro** - Componenti UI eleganti e completamente CSS, senza JavaScript
-- **Facile integrazione** - Engine Rails montabile che si integra perfettamente con la tua app
-- **Documentazione integrata** - Visualizza esempi e documentazione direttamente nel browser
-- **Altamente personalizzabile** - Adatta facilmente lo stile al tuo brand
-- **Componenti modulari** - Usa solo ciò di cui hai bisogno
+### Caratteristiche Principali
 
-## 📦 Componenti disponibili
+- **Solo TailwindCSS**: Approccio puro Tailwind senza file CSS/SCSS personalizzati
+- **26 Componenti**: Libreria completa organizzata per scopo
+- **Sistema Input Unificato**: Componenti input supportano 14+ tipi (text, email, password, number, date, time, etc.)
+- **Documentazione Interattiva**: Integrazione Lookbook con preview live
+- **Sistema Helper**: Helper Rails-friendly con integrazione form builder
+- **Tematizzazione Consistente**: 9 temi standard (default, white, red, rose, orange, green, blue, yellow, violet)
+- **Dimensionamento Flessibile**: 3 dimensioni standard (small, medium, large) con 5 opzioni border radius
+- **Accessibilità**: Componenti progettati seguendo le best practices di accessibilità
 
-| Componente | Descrizione |
-|------------|-------------|
-| **Button** | Pulsanti stilizzati con varianti primary, secondary, success, danger |
-| **Alert** | Messaggi informativi, successi, avvisi ed errori |
-| **Card** | Contenitori flessibili con header, body e footer |
-| **Modal** | Finestre di dialogo modali |
-| **Tabs** | Navigazione a schede |
-| **Form Elements** | Campi di input stilizzati (in arrivo) |
-
-## 🚀 Installazione
+## Installazione
 
 Aggiungi questa riga al Gemfile della tua applicazione:
 
 ```ruby
-gem 'better_ui', '~> 0.1.0'
+gem "better_ui"
+```
+
+Per lo sviluppo con documentazione Lookbook:
+
+```ruby
+gem "better_ui"
+gem "lookbook", group: :development
 ```
 
-E poi esegui:
+Quindi esegui:
 
 ```bash
 $ bundle install
 ```
 
-## ⚙️ Configurazione
+## Setup
 
-### Monta l'engine
+### 1. Mount Engine (Opzionale)
 
-Aggiungi questo al tuo file `config/routes.rb`:
+Se vuoi accedere alle route interne di BetterUI, monta l'engine in `config/routes.rb`:
 
 ```ruby
 Rails.application.routes.draw do
-  mount BetterUi::Engine => '/better_ui'
-  
-  # ... altre tue route
+  mount BetterUi::Engine => "/better_ui"
+  # le tue altre route...
 end
 ```
 
-### Includi gli assets
+### 2. Setup Lookbook (Raccomandato per Development)
+
+Per accedere alla documentazione interattiva dei componenti durante lo sviluppo, monta Lookbook in `config/routes.rb`:
 
-In `app/assets/stylesheets/application.css`:
+```ruby
+Rails.application.routes.draw do
+  # Monta Lookbook solo in development
+  mount Lookbook::Engine => "/lookbook" if Rails.env.development?
 
-```css
-/*
- *= require better_ui/application
- */
+  # le tue altre route...
+end
 ```
 
-## 🎮 Utilizzo
+**Fatto!** I componenti BetterUI e le loro preview sono automaticamente disponibili in Lookbook.
+
+### 3. Includi Tailwind CSS
+
+Assicurati che la tua applicazione includa Tailwind CSS, dato che i componenti BetterUI si basano sulle classi Tailwind. Se non hai Tailwind CSS installato, segui la [guida ufficiale di installazione Tailwind CSS](https://tailwindcss.com/docs/guides/ruby-on-rails).
+
+## Utilizzo
 
-Una volta installato, puoi iniziare ad usare i componenti:
+I componenti Better UI possono essere utilizzati in due modi: istanziazione diretta o metodi helper.
+
+### Metodi Helper (Raccomandato)
 
 ```erb
-<%# Button %>
-<%= better_ui_button("Salva", type: "primary") %>
-
-<%# Alert %>
-<%= better_ui_alert("Operazione completata", type: "success") %>
-
-<%# Card %>
-<%= better_ui_card do %>
-  <%= better_ui_card_header("Titolo Card") %>
-  <%= better_ui_card_body do %>
-    <p>Contenuto della card...</p>
-  <% end %>
+<%# Input di testo con validazione %>
+<%= bui_input_text(
+  name: 'email',
+  value: @user.email,
+  type: :email,
+  theme: :blue,
+  size: :large,
+  required: true
+) %>
+
+<%# Button con theme e size %>
+<%= bui_button(
+  'Invia Form',
+  theme: :green,
+  size: :large,
+  type: :submit
+) %>
+
+<%# Card con blocco di contenuto %>
+<%= bui_card(title: 'Profilo Utente', theme: :white) do %>
+  <p>Contenuto informazioni utente qui</p>
+<% end %>
+
+<%# Integrazione con form %>
+<%= form_with model: @user do |form| %>
+  <%= bui_input_text(name: 'name', form: form, required: true) %>
+  <%= bui_input_text(name: 'email', type: :email, form: form) %>
+  <%= bui_button('Salva', type: :submit, theme: :blue) %>
 <% end %>
 ```
 
-Visita `/better_ui` nella tua applicazione per vedere la documentazione completa e gli esempi.
+### Istanziazione Diretta
+
+```erb
+<%# Rendering diretto del componente %>
+<%= render BetterUi::General::Input::Text::Component.new(
+  name: 'username',
+  type: :text,
+  theme: :default,
+  size: :medium
+) %>
+
+<%# Componente button %>
+<%= render BetterUi::General::Button::Component.new(
+  'Cliccami',
+  theme: :blue,
+  size: :large
+) %>
+```
 
-## 🎨 Personalizzazione
+### Sistema di Tematizzazione
 
-### Usa l'inizializzatore
+Tutti i componenti supportano tematizzazione consistente:
 
-Crea un file `config/initializers/better_ui.rb`:
+- **9 Temi Standard**: default, white, red, rose, orange, green, blue, yellow, violet
+- **3 Dimensioni Standard**: small, medium, large
+- **5 Opzioni Border Radius**: none, small, medium, large, full
+
+### Approccio Styling
+
+Better UI usa un approccio TailwindCSS puro con costanti per styling manutenibile:
 
 ```ruby
-BetterUi.configure do |config|
-  config.button_defaults = {
-    class: 'rounded-lg text-sm'
-  }
-  
-  config.alert_defaults = {
-    dismissible: true
-  }
-end
+# Le costanti del componente definiscono le opzioni di styling
+BUTTON_THEME_CLASSES = {
+  default: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
+  blue: 'bg-blue-600 text-white hover:bg-blue-700',
+  green: 'bg-green-600 text-white hover:bg-green-700'
+}.freeze
+
+BUTTON_SIZE_CLASSES = {
+  small: 'px-3 py-1.5 text-sm',
+  medium: 'px-4 py-2 text-base',
+  large: 'px-6 py-3 text-lg'
+}.freeze
 ```
 
-### Personalizza gli stili
+## Componenti Disponibili
 
-Sovrascrivi gli stili CSS nel tuo foglio di stile:
+Better UI include 26 componenti organizzati in tre categorie:
 
-```css
-.better-ui-button-primary {
-  background-color: #8b5cf6; /* Viola personalizzato */
-  border-color: #8b5cf6;
-}
-```
+### Componenti Application (4)
 
-## 🛠 Sviluppo
+Componenti di layout e navigazione per interfacce applicative:
 
-BetterUI utilizza una app dummy integrata per lo sviluppo e i test. Ecco come iniziare:
+- **Card**: Container di contenuto con supporto header e azioni
+- **Main**: Area contenuto principale dell'applicazione con layout responsive
+- **Navbar**: Barra di navigazione superiore con supporto contenuto flessibile
+- **Sidebar**: Navigazione laterale collassabile
 
-### Setup iniziale
+### Componenti General (22)
 
-```bash
-# Clona il repository
-git clone https://github.com/alessiobussolari/better_ui.git
-cd better_ui
+Elementi UI core per costruire interfacce:
 
-# Installa le dipendenze
-bin/setup
-```
+**Display & Feedback**
 
-### Avvia l'applicazione di test
+- **Alert**: Messaggi di notifica con temi multipli e opzioni dismissible
+- **Avatar**: Immagini profilo utente con supporto fallback
+- **Badge**: Indicatori di stato e etichette
+- **Progress**: Barre di progresso e indicatori di caricamento
+- **Spinner**: Animazioni di caricamento
+- **Tooltip**: Overlay di aiuto contestuale e informazioni
 
-Per vedere i componenti in azione e lavorare sulla documentazione:
+**Navigazione & Struttura**
 
-```bash
-# Avvia il server di test
-cd test/dummy
-bin/rails server
+- **Breadcrumb**: Indicatori di percorso di navigazione
+- **Divider**: Separatori di contenuto visivi
+- **Heading**: Intestazioni con tipografia consistente
+- **Icon**: Sistema icone SVG con libreria estesa
+- **Link**: Elementi anchor potenziati con supporto theme
+- **Panel**: Sezioni di contenuto organizzate
+- **Table**: Tabelle dati con sorting e funzionalità responsive
+- **Tag**: Elementi di categorizzazione ed etichettatura
 
-# Oppure dalla directory principale
-bin/rails server -b 0.0.0.0
-```
+**Form & Input**
+
+- **Button**: Button azione con varianti multiple e stati
+- **Field**: Wrapper campo form con supporto label e validazione
+- **Input**: Sistema input unificato che supporta 14+ tipi:
+  - **Text**: text, email, password, search, url, tel
+  - **Number**: number, range
+  - **Date/Time**: date, datetime-local, time, month, week
+  - **File**: upload file
+  - **Color**: color picker
+  - **Checkbox**: Opzioni multi-selezione
+  - **Radio**: Opzioni selezione singola
+  - **Select**: Selezioni dropdown
+  - **Textarea**: Input testo multi-riga
+
+### Componenti Form (0)
+
+Riservati per futuri componenti form specializzati e widget form complessi.
+
+## Personalizzazione e Styling
+
+I componenti BetterUI usano classi Tailwind CSS. Puoi:
 
-Visita `http://localhost:3000/better_ui` nel tuo browser per vedere la documentazione e testare i componenti.
+1. **Sovrascrivere classi**: Passa classi personalizzate tramite il parametro `classes`
+2. **Estendere componenti**: Crea i tuoi componenti che ereditano da BetterUI
+3. **Personalizzazione theme**: Modifica la configurazione Tailwind per tematizzazione consistente
 
-### Flusso di sviluppo
+```erb
+<!-- Aggiungi classi personalizzate -->
+<%= render BetterUi::General::Button::Component.new(
+  label: "Button Personalizzato",
+  classes: "my-custom-class hover:scale-105"
+) %>
+```
+
+Better UI è progettato per essere altamente personalizzabile mantenendo consistenza:
 
-1. **Crea un branch**: `git checkout -b feature/nuovo-componente`
-2. **Implementa il componente**: Aggiungi helper in `app/helpers/better_ui/application_helper.rb`
-3. **Aggiungi CSS**: Inserisci gli stili in `app/assets/stylesheets/better_ui/application.css`
-4. **Documenta**: Crea file Markdown in `docs/components/`
-5. **Testa**: Verifica nell'app dummy che tutto funzioni correttamente
-6. **Esegui i test**: `rake test`
+1. **Personalizzazione Theme**: Modifica le costanti dei componenti per cambiare lo styling di default
+2. **Configurazione Componenti**: Configura opzioni di default in `config/initializers/better_ui.rb`
+3. **Integrazione TailwindCSS**: Tutto lo styling usa classi TailwindCSS per massima flessibilità
+4. **Estensioni Componenti**: Estendi componenti esistenti o crea i tuoi seguendo i pattern stabiliti
 
-### Build e rilascio
+## Testing
 
-Per buildare la gemma localmente:
+I componenti Better UI sono testati completamente. Puoi eseguire la test suite con:
 
 ```bash
-bundle exec rake build
+bin/rails test
 ```
 
-Per installare la versione in sviluppo:
+## Supporto Browser
+
+I componenti BetterUI supportano tutti i browser moderni che supportano:
+
+- CSS Grid e Flexbox
+- Funzionalità JavaScript ES6+
+- Tailwind CSS
+
+## Contributing
+
+1. Forka il repository
+2. Crea il tuo branch feature (`git checkout -b feature/componente-fantastico`)
+3. Aggiungi il tuo componente con test e preview Lookbook
+4. Committa le tue modifiche (`git commit -am 'Aggiungi componente fantastico'`)
+5. Pusha al branch (`git push origin feature/componente-fantastico`)
+6. Crea una Pull Request
+
+### Setup Development
 
 ```bash
-bundle exec rake install
+git clone https://github.com/alessiobussolari/better_ui.git
+cd better_ui
+bundle install
+cd test/dummy
+bundle exec rails server
 ```
 
-## 🤝 Contribuire
+Visita `http://localhost:3000/lookbook` per vedere la documentazione dei componenti.
 
-I contributi sono benvenuti e apprezzati! Ecco come puoi aiutare:
+## Roadmap
 
-1. **Fork** il repository su GitHub
-2. **Clona** il tuo fork: `git clone https://github.com/TUO-USERNAME/better_ui.git`
-3. **Crea** un branch per la tua feature: `git checkout -b feature/incredibile-miglioramento`
-4. **Committa** i tuoi cambiamenti: `git commit -am 'Aggiunge una funzionalità incredibile'`
-5. **Pusha** al branch: `git push origin feature/incredibile-miglioramento`
-6. Invia una **Pull Request**
+- 🎯 Componenti form avanzati (input complessi, validazioni)
+- 📊 Componenti chart e visualizzazione dati
+- 🎭 Componenti animazione e transizione
+- 🌙 Supporto dark mode
+- 📱 Componenti specifici mobile
+- 🔧 Tool di configurazione e generatori
 
-### Linee guida
+## License
 
-- Segui lo stile di codice esistente
-- Scrivi test per le nuove funzionalità
-- Aggiorna la documentazione
-- Crea componenti che funzionano senza JavaScript
+La gem è disponibile come open source sotto i termini della [MIT License](https://opensource.org/licenses/MIT).
 
-## 📄 Licenza
+## Support
 
-BetterUI è disponibile come open source sotto i termini della [Licenza MIT](https://opensource.org/licenses/MIT).
+- 📖 [Documentazione](https://github.com/alessiobussolari/better_ui)
+- 🐛 [Issue Tracker](https://github.com/alessiobussolari/better_ui/issues)
+- 💬 [Discussioni](https://github.com/alessiobussolari/better_ui/discussions)
 
 ---
 
-Realizzato con ❤️ da [Alessio Bussolari](https://github.com/alessiobussolari)
+Costruito con ❤️ da [PanDev](https://github.com/alessiobussolari)