better_ui 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2242792aeee217a121cb73ec14ccc317d8f9c7af9e3dcdcf52629d05eca55731
-  data.tar.gz: 86015104cb387605208eaa8f9ffbdeb3764542fd089e09cf2dd011cecc37640b
+  metadata.gz: ee8e6a1b636ddcd65276d5c410c5b0c9a239d236cdbf507d168bb68abe63c12d
+  data.tar.gz: 930f7752b6c813943b49d29bd635da5109355f036eea0bf1d5fc9aed45932173
 SHA512:
-  metadata.gz: df1b73b3f9c3782a562ef7b585fd9bbac50c45fc8cc9661fe6ff8aa335c53f988c65ce4ab430c7c6dc82d74419b9dd80e026ad50c4533742b7940153fba2e653
-  data.tar.gz: 1010406d6a425b0ca48e1acf0af262634a7f5babf54edd34dfd6c7b6943dbdb1a18c250d800f68b9e41ec7bc94d095a8ed9d3e3ca7efb540bbb3ddbe4d310105
+  metadata.gz: f91edcfb87541fbdeb97e2bc3899c1b1d3a8508bd94a6e6a9955ea56940830cfcc98df3e23f82e9bcb975039b6d3122c36f7c0e75316822ec11f03d206105647
+  data.tar.gz: 9422f6159176dc75cd254009f55660831aca51c98e7a4d829a5ab6b4911d5fc569f44ae05c549a452d5fd403a844a1b589642244c1922f485f59874094618921

data/README.md

@@ -1,259 +1,211 @@
-# BetterUI 🎨
+# Better UI
 
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Componenti UI eleganti, coerenti e facilmente integrabili per le tue applicazioni Rails
+A comprehensive UI component library for Rails applications built with ViewComponent and Tailwind CSS, following BEM methodology.
 
-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.
+![Better UI Components](https://via.placeholder.com/800x400?text=Better+UI+Components)
 
-## ✨ Caratteristiche principali
+## Table of Contents
 
-- **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
-- **Preview dei componenti** - Visualizza e interagisci con i componenti usando Lookbook
+- [Overview](#overview)
+- [Installation](#installation)
+  - [Basic Installation](#basic-installation)
+  - [Advanced Installation Options](#advanced-installation-options)
+  - [Tailwind CSS Configuration](#tailwind-css-configuration)
+- [Documentation](#documentation)
+- [Usage](#usage)
+- [Customization](#customization)
+- [Components](#components)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Resources](#resources)
 
-## 📦 Componenti disponibili
+## Overview
 
-| 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 |
-| **Navbar** | Barra di navigazione responsive con supporto per menu dropdown |
-| **Sidebar** | Menu laterale con supporto per navigazione gerarchica |
-| **Toast** | Notifiche temporanee con timer e animazioni |
-| **Header** | Intestazioni di pagina con titolo, sottotitolo, breadcrumb e azioni |
-| **Form Elements** | Campi di input stilizzati (in arrivo) |
+Better UI is a Rails gem that provides a collection of reusable UI components built with ViewComponent and Tailwind CSS. It follows the BEM (Block Element Modifier) methodology to ensure consistent naming and styling conventions.
 
-## 🚀 Installazione
+Key features:
+- **Modern Sass Architecture**: Uses `@use` and `@forward` instead of deprecated `@import`
+- **Modular Components**: Each component is isolated and can be used independently
+- **Customizable**: Override components styles with your own customizations
+- **Interactive Documentation**: Built-in documentation viewer with Lookbook
+- **Responsive Design**: All components are responsive by default
+- **Accessibility**: Components are designed with accessibility in mind
 
-Aggiungi questa riga al Gemfile della tua applicazione:
+For more detailed information, see the [components documentation](COMPONENTS.md).
+
+## Installation
+
+### Basic Installation
+
+1. Add the gem to your Gemfile:
 
 ```ruby
-gem 'better_ui', '~> 0.1.0'
+gem 'better_ui'
 ```
 
-E poi esegui:
+2. Run bundle install:
 
 ```bash
-$ bundle install
+bundle install
 ```
 
-## ⚙️ Configurazione
+3. Run the installer:
 
-### Monta l'engine
-
-Aggiungi questo al tuo file `config/routes.rb`:
-
-```ruby
-Rails.application.routes.draw do
-  mount BetterUi::Engine => '/better_ui'
-  
-  # ... altre tue route
-end
+```bash
+bin/rails generate better_ui:install
 ```
 
-### Includi gli assets
+The installer will:
+- Mount the Better UI engine at `/better_ui`
+- Add the necessary assets to your application
+- Create a configuration file at `config/initializers/better_ui.rb`
+- Generate customizable stylesheets in `app/assets/stylesheets/components/`
 
-In `app/assets/stylesheets/application.css`:
+### Advanced Installation Options
 
-```css
-/*
- *= require better_ui/application
- */
-```
+You can customize the installation process with the following options:
 
-## 🎮 Utilizzo
+```bash
+# Skip mounting the engine in routes
+bin/rails generate better_ui:install --skip-routes
 
-Una volta installato, puoi iniziare ad usare i componenti:
+# Skip generating stylesheets
+bin/rails generate better_ui:install --skip-stylesheets
 
-```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 %>
-<% end %>
+# Skip creating the configuration file
+bin/rails generate better_ui:install --skip-config
 
-<%# Header con breadcrumb %>
-<%= render BetterUi::Application::HeaderComponent.new(
-  title: "Dashboard",
-  subtitle: "Gestisci tutto da qui",
-  breadcrumbs: [
-    { text: "Home", url: "/" },
-    { text: "Dashboard" }
-  ],
-  actions: [
-    { content: button_html("Nuovo", "primary") }
-  ]
-) %>
+# All options together
+bin/rails generate better_ui:install --skip-routes --skip-stylesheets --skip-config
 ```
 
-Visita `/better_ui` nella tua applicazione per vedere la documentazione completa e gli esempi.
+### Tailwind CSS Configuration
 
-### Il componente Header
+Better UI requires Tailwind CSS to be properly configured in your application. If you haven't already set up Tailwind CSS, follow these steps:
 
-Il componente Header è progettato per creare intestazioni di pagina complete con numerose funzionalità:
+1. Install Tailwind CSS in your Rails application:
 
-```erb
-<%= render BetterUi::Application::HeaderComponent.new(
-  title: {
-    text: "Impostazioni",
-    icon: "settings"
-  },
-  subtitle: "Configura le preferenze del sistema",
-  breadcrumbs: [
-    { text: "Home", url: "/" },
-    { text: "Admin", url: "/admin" },
-    { text: "Impostazioni" }
-  ],
-  variant: :modern,
-  fixed: :top,
-  show_breadcrumbs: true,
-  actions: [
-    { content: button_html("Salva", "primary") },
-    { content: button_html("Annulla", "secondary") }
-  ]
-) %>
+```bash
+bin/rails tailwindcss:install
 ```
 
-Il componente supporta:
-- Titolo con opzionale icona integrata
-- Sottotitolo descrittivo
-- Breadcrumbs completi con link di navigazione
-- Azioni contestuali (pulsanti, menu, ecc.)
-- Varianti di stile: modern, light, dark, primary, transparent
-- Posizionamento fisso (in alto o in basso)
-- Controllo della visibilità dei breadcrumb
-
-### Preview dei componenti con Lookbook
-
-BetterUI integra [Lookbook](https://github.com/allmarkedup/lookbook) per visualizzare in anteprima i componenti UI:
+2. Configure Tailwind to include Better UI's components:
 
-1. Accedi a `/better_ui/lookbook` nella tua applicazione per visualizzare il catalogo componenti
-2. Esplora le varianti e le configurazioni disponibili per ogni componente
-3. Visualizza il codice sorgente e il markup generato
-4. Interagisci con i componenti in tempo reale
+In your `tailwind.config.js` file, add:
 
-Lookbook è disponibile solo negli ambienti di sviluppo e test.
+```javascript
+module.exports = {
+  content: [
+    './app/views/**/*.{html,html.erb,erb}',
+    './app/helpers/**/*.rb',
+    './app/javascript/**/*.js',
+    './app/components/**/*.{rb,html,html.erb,erb}',
+    // Add this line for Better UI components
+    './app/components/better_ui/**/*.{rb,html,html.erb,erb}'
+  ],
+  // other configurations...
+}
+```
 
-## 🎮 Personalizzazione
+For more detailed installation instructions, see [INSTALLATION.md](INSTALLATION.md).
 
-### Usa l'inizializzatore
+## Documentation
 
-Crea un file `config/initializers/better_ui.rb`:
+After installation, you can access the interactive documentation at:
 
-```ruby
-BetterUi.configure do |config|
-  config.button_defaults = {
-    class: 'rounded-lg text-sm'
-  }
-  
-  config.alert_defaults = {
-    dismissible: true
-  }
-end
 ```
-
-### Personalizza gli stili
-
-Sovrascrivi gli stili CSS nel tuo foglio di stile:
-
-```css
-.better-ui-button-primary {
-  background-color: #8b5cf6; /* Viola personalizzato */
-  border-color: #8b5cf6;
-}
+http://localhost:3000/better_ui
 ```
 
-## 🛠 Sviluppo
+This provides:
+- Interactive component previews
+- Component API documentation
+- Usage examples and code snippets
+- Styling reference
 
-BetterUI utilizza una app dummy integrata per lo sviluppo e i test. Ecco come iniziare:
+## Usage
 
-### Setup iniziale
+Using Better UI components in your views is straightforward:
 
-```bash
-# Clona il repository
-git clone https://github.com/alessiobussolari/better_ui.git
-cd better_ui
+```erb
+<%# Basic button %>
+<%= render BetterUi::General::ButtonComponent.new(label: 'Click me') %>
+
+<%# Button with more options %>
+<%= render BetterUi::General::ButtonComponent.new(
+  label: 'Submit',
+  variant: 'primary',
+  size: 'large',
+  icon_left: 'check',
+  data: { turbo: false }
+) %>
 
-# Installa le dipendenze
-bin/setup
+<%# Panel component %>
+<%= render BetterUi::General::PanelComponent.new(title: 'User Details') do %>
+  <p>This is the panel content</p>
+<% end %>
 ```
 
-### Avvia l'applicazione di test
+For more detailed usage instructions, see [USAGE.md](USAGE.md).
 
-Per vedere i componenti in azione e lavorare sulla documentazione:
+## Customization
 
-```bash
-# Avvia il server di test
-cd test/dummy
-bin/rails server
+Better UI is designed to be highly customizable:
+
+1. **Style Customization**: Edit the generated override files in `app/assets/stylesheets/components/`
+2. **Component Configuration**: Configure default options in `config/initializers/better_ui.rb`
+3. **Component Extensions**: Extend existing components or create your own
 
-# Oppure dalla directory principale
-bin/rails server -b 0.0.0.0
+Example of customizing a component style:
+
+```scss
+// app/assets/stylesheets/components/_button_overrides.scss
+@layer components {
+  .bui-button {
+    &--primary {
+      @apply bg-indigo-600 hover:bg-indigo-700;
+    }
+  }
+}
 ```
 
-Visita `http://localhost:3000/better_ui` nel tuo browser per vedere la documentazione e testare i componenti.
+For more detailed customization instructions, see [CUSTOMIZATION.md](CUSTOMIZATION.md).
 
-### Flusso di sviluppo
+## Components
 
-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`
+Better UI includes a wide range of components categorized into:
 
-### Build e rilascio
+- **General Components**: Basic UI elements like buttons, badges, icons
+- **Application Components**: Complex UI elements like cards, alerts, sidebars
+- **Website Components**: Components specifically designed for websites
 
-Per buildare la gemma localmente:
+For a full list of available components and their documentation, see [COMPONENTS.md](COMPONENTS.md).
 
-```bash
-bundle exec rake build
-```
+## Testing
 
-Per installare la versione in sviluppo:
+Better UI components are thoroughly tested. You can run the test suite with:
 
 ```bash
-bundle exec rake install
+bin/rails test
 ```
 
-## 🤝 Contribuire
-
-I contributi sono benvenuti e apprezzati! Ecco come puoi aiutare:
-
-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**
+For more detailed testing instructions, see [TESTING.md](TESTING.md).
 
-### Linee guida
+## Contributing
 
-- Segui lo stile di codice esistente
-- Scrivi test per le nuove funzionalità
-- Aggiorna la documentazione
-- Crea componenti che funzionano senza JavaScript
+Contributions are welcome! Please check out our [contribution guidelines](CONTRIBUTING.md).
 
-## 📄 Licenza
+## License
 
-BetterUI è disponibile come open source sotto i termini della [Licenza MIT](https://opensource.org/licenses/MIT).
+Better UI is available as open source under the terms of the [MIT License](LICENSE).
 
----
+## Resources
 
-Realizzato con ❤️ da [Alessio Bussolari](https://github.com/alessiobussolari)
+- [Troubleshooting Guide](TROUBLESHOOTING.md)
+- [FAQs](FAQ.md)
+- [Changelog](CHANGELOG.md)
+- [Roadmap](ROADMAP.md)

data/app/assets/stylesheets/better_ui/_base.scss

@@ -0,0 +1,9 @@
+// Base che importa Tailwind
+@use "tailwindcss/base";
+@use "tailwindcss/components";
+@use "tailwindcss/utilities";
+
+// Stili comuni dell'applicazione
+html, body {
+  @apply font-sans text-gray-900 leading-normal;
+} 

data/app/assets/stylesheets/better_ui/_components.scss

@@ -0,0 +1,2 @@
+// Re-espone tutti i componenti con un singolo import
+@forward "components/index"; 

data/app/assets/stylesheets/better_ui/_utilities.scss

@@ -0,0 +1,14 @@
+@layer utilities {
+  // Utility classes aggiuntive che estendono Tailwind
+  .spacing-responsive {
+    @apply px-4 py-6 md:px-6 md:py-8 lg:px-8 lg:py-10;
+  }
+  
+  .text-shadow {
+    @apply shadow-sm;
+  }
+  
+  .card-shadow {
+    @apply shadow-md hover:shadow-lg transition-shadow duration-200;
+  }
+} 

data/app/assets/stylesheets/better_ui/application.css

@@ -13,10 +13,12 @@
  *= require_tree .
  *= require_self
  *= require font-awesome
+ *= require better_ui
  */
 
 /* 
- * BetterUI - Utilizziamo Tailwind CSS per tutti gli stili
+ * BetterUI - Utilizziamo Tailwind CSS per tutti gli stili 
+ * Ora organizzati con la moderna sintassi di Sass (@use/@forward)
  */
 
 /* Stili per il syntax highlighting di CodeRay */

data/app/assets/stylesheets/better_ui/components/_avatar.scss

@@ -0,0 +1,200 @@
+@layer components {
+  // Classe base per l'avatar (Block)
+  .bui-avatar {
+    @apply inline-flex items-center justify-center relative;
+    
+    // Elements
+    &__image {
+      @apply object-cover;
+    }
+    
+    &__placeholder {
+      @apply flex items-center justify-center font-medium text-white uppercase;
+    }
+    
+    &__status {
+      @apply absolute bottom-0 right-0 block rounded-full ring-2 ring-white;
+      
+      &--online {
+        @apply bg-green-400;
+      }
+      
+      &--offline {
+        @apply bg-gray-400;
+      }
+      
+      &--busy {
+        @apply bg-red-400;
+      }
+      
+      &--away {
+        @apply bg-yellow-400;
+      }
+    }
+    
+    &__presence {
+      @apply absolute block rounded-full ring-2 ring-white;
+    }
+    
+    &__badge {
+      @apply absolute -top-1 -right-1 flex items-center justify-center;
+    }
+    
+    // Modifiers (dimensioni)
+    &--xs {
+      @apply h-6 w-6;
+      
+      .bui-avatar__placeholder {
+        @apply text-xs;
+      }
+      
+      .bui-avatar__status {
+        @apply h-1.5 w-1.5;
+      }
+      
+      .bui-avatar__badge {
+        @apply h-4 w-4 text-[0.6rem];
+      }
+    }
+    
+    &--sm {
+      @apply h-8 w-8;
+      
+      .bui-avatar__placeholder {
+        @apply text-xs;
+      }
+      
+      .bui-avatar__status {
+        @apply h-2 w-2;
+      }
+      
+      .bui-avatar__badge {
+        @apply h-5 w-5 text-xs;
+      }
+    }
+    
+    &--md {
+      @apply h-10 w-10;
+      
+      .bui-avatar__placeholder {
+        @apply text-sm;
+      }
+      
+      .bui-avatar__status {
+        @apply h-2.5 w-2.5;
+      }
+      
+      .bui-avatar__badge {
+        @apply h-6 w-6 text-xs;
+      }
+    }
+    
+    &--lg {
+      @apply h-12 w-12;
+      
+      .bui-avatar__placeholder {
+        @apply text-base;
+      }
+      
+      .bui-avatar__status {
+        @apply h-3 w-3;
+      }
+      
+      .bui-avatar__badge {
+        @apply h-7 w-7 text-sm;
+      }
+    }
+    
+    &--xl {
+      @apply h-16 w-16;
+      
+      .bui-avatar__placeholder {
+        @apply text-lg;
+      }
+      
+      .bui-avatar__status {
+        @apply h-4 w-4;
+      }
+      
+      .bui-avatar__badge {
+        @apply h-8 w-8 text-sm;
+      }
+    }
+    
+    // Modifiers (colori placeholders)
+    &--gray {
+      .bui-avatar__placeholder {
+        @apply bg-gray-500;
+      }
+    }
+    
+    &--red {
+      .bui-avatar__placeholder {
+        @apply bg-red-500;
+      }
+    }
+    
+    &--blue {
+      .bui-avatar__placeholder {
+        @apply bg-blue-500;
+      }
+    }
+    
+    &--green {
+      .bui-avatar__placeholder {
+        @apply bg-green-500;
+      }
+    }
+    
+    &--violet {
+      .bui-avatar__placeholder {
+        @apply bg-violet-500;
+      }
+    }
+    
+    &--orange {
+      .bui-avatar__placeholder {
+        @apply bg-orange-500;
+      }
+    }
+    
+    &--yellow {
+      .bui-avatar__placeholder {
+        @apply bg-yellow-500 text-yellow-900;
+      }
+    }
+    
+    // Modifiers (forma)
+    &--circle {
+      @apply rounded-full;
+      
+      .bui-avatar__image,
+      .bui-avatar__placeholder {
+        @apply rounded-full;
+      }
+    }
+    
+    &--square {
+      @apply rounded-md;
+      
+      .bui-avatar__image,
+      .bui-avatar__placeholder {
+        @apply rounded-md;
+      }
+    }
+    
+    // Modifiers (gruppo)
+    &--group {
+      @apply -ml-2 first:ml-0;
+    }
+  }
+  
+  // Avatar group container
+  .bui-avatar-group {
+    @apply flex;
+    
+    .bui-avatar {
+      @apply border-2 border-white;
+    }
+  }
+}