better_ui 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2242792aeee217a121cb73ec14ccc317d8f9c7af9e3dcdcf52629d05eca55731
-  data.tar.gz: 86015104cb387605208eaa8f9ffbdeb3764542fd089e09cf2dd011cecc37640b
+  metadata.gz: 317837f4f80e12e6ab860a7a134e9f17e01f5db2d86f5b178a4c9a2bc9588f3a
+  data.tar.gz: 8815e3b40a461070b9cb178ee1a7e1e8abaccbf6cea7366ab5c079db174429f4
 SHA512:
-  metadata.gz: df1b73b3f9c3782a562ef7b585fd9bbac50c45fc8cc9661fe6ff8aa335c53f988c65ce4ab430c7c6dc82d74419b9dd80e026ad50c4533742b7940153fba2e653
-  data.tar.gz: 1010406d6a425b0ca48e1acf0af262634a7f5babf54edd34dfd6c7b6943dbdb1a18c250d800f68b9e41ec7bc94d095a8ed9d3e3ca7efb540bbb3ddbe4d310105
+  metadata.gz: 0fb96fb9537391b7448ffde247cd8d9ae4916dac0cfcd17c4efe912b061dfd05986368ebe6563549c58ce0909e9a509474ac885e136d133214f806437925726d
+  data.tar.gz: de95bf54dcd6fa022f5afa5c0867d65b7a78e8f24cab637aa7cf098f0bf01f5cabdac5e6c7b36ba1aba14833682b17174e1d229a4d428f5646d92ee876ad42f4

data/README.md

@@ -3,63 +3,66 @@
 [![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)
 
-> Componenti UI eleganti, coerenti e facilmente integrabili per le tue applicazioni Rails
+> Elegant, consistent, and easily integrable UI components for your Rails applications
 
-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.
+BetterUI is a Rails gem that provides reusable UI components with built-in documentation. Designed to be lightweight, customizable, and easy to use, it helps you build beautiful and consistent interfaces without JavaScript.
 
-## ✨ Caratteristiche principali
+## ✨ Key Features
 
-- **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
+- **Pure Design** - Elegant, fully CSS UI components, no JavaScript
+- **Easy Integration** - Mountable Rails engine that integrates seamlessly with your app
+- **Built-in Documentation** - View examples and documentation directly in your browser
+- **Highly Customizable** - Easily adapt the style to your brand
+- **Modular Components** - Use only what you need
+- **Component Previews** - View and interact with components using Lookbook
 
-## 📦 Componenti disponibili
+## 📦 Available Components
 
-| Componente | Descrizione |
+| Component | Description |
 |------------|-------------|
-| **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) |
-
-## 🚀 Installazione
-
-Aggiungi questa riga al Gemfile della tua applicazione:
+| **Button** | Styled buttons with primary, secondary, success, danger variants |
+| **Alert** | Informational, success, warning, and error messages |
+| **Card** | Flexible containers with header, body, and footer |
+| **Modal** | Modal dialog windows |
+| **Tabs** | Tab navigation |
+| **Navbar** | Responsive navigation bar with dropdown menu support |
+| **Sidebar** | Side menu with hierarchical navigation support |
+| **Toast** | Temporary notifications with timer and animations |
+| **Header** | Page headers with title, subtitle, breadcrumb, and actions |
+| **Badge** | Labels with support for icons, colors, and outline variants |
+| **Spinner** | Loading indicators with various themes and sizes |
+| **Avatar** | User avatars with support for images, initials, and online status |
+| **Form Elements** | Styled input fields (coming soon) |
+
+## 🚀 Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
 gem 'better_ui', '~> 0.1.0'
 ```
 
-E poi esegui:
+And then execute:
 
 ```bash
 $ bundle install
 ```
 
-## ⚙️ Configurazione
+## ⚙️ Configuration
 
-### Monta l'engine
+### Mount the Engine
 
-Aggiungi questo al tuo file `config/routes.rb`:
+Add this to your `config/routes.rb` file:
 
 ```ruby
 Rails.application.routes.draw do
   mount BetterUi::Engine => '/better_ui'
   
-  # ... altre tue route
+  # ... your other routes
 end
 ```
 
-### Includi gli assets
+### Include the Assets
 
 In `app/assets/stylesheets/application.css`:
 
@@ -69,92 +72,149 @@ In `app/assets/stylesheets/application.css`:
  */
 ```
 
-## 🎮 Utilizzo
+## 🎮 Usage
 
-Una volta installato, puoi iniziare ad usare i componenti:
+Once installed, you can start using the components:
 
 ```erb
 <%# Button %>
-<%= better_ui_button("Salva", type: "primary") %>
+<%= better_ui_button("Save", type: "primary") %>
 
 <%# Alert %>
-<%= better_ui_alert("Operazione completata", type: "success") %>
+<%= better_ui_alert("Operation completed", type: "success") %>
 
 <%# Card %>
 <%= better_ui_card do %>
-  <%= better_ui_card_header("Titolo Card") %>
+  <%= better_ui_card_header("Card Title") %>
   <%= better_ui_card_body do %>
-    <p>Contenuto della card...</p>
+    <p>Card content...</p>
   <% end %>
 <% end %>
 
-<%# Header con breadcrumb %>
+<%# Header with breadcrumb %>
 <%= render BetterUi::Application::HeaderComponent.new(
   title: "Dashboard",
-  subtitle: "Gestisci tutto da qui",
+  subtitle: "Manage everything from here",
   breadcrumbs: [
     { text: "Home", url: "/" },
     { text: "Dashboard" }
   ],
   actions: [
-    { content: button_html("Nuovo", "primary") }
+    { content: button_html("New", "primary") }
   ]
 ) %>
 ```
 
-Visita `/better_ui` nella tua applicazione per vedere la documentazione completa e gli esempi.
+Visit `/better_ui` in your application to see the complete documentation and examples.
 
-### Il componente Header
+### The Header Component
 
-Il componente Header è progettato per creare intestazioni di pagina complete con numerose funzionalità:
+The Header component is designed to create complete page headers with numerous features:
 
 ```erb
 <%= render BetterUi::Application::HeaderComponent.new(
   title: {
-    text: "Impostazioni",
+    text: "Settings",
     icon: "settings"
   },
-  subtitle: "Configura le preferenze del sistema",
+  subtitle: "Configure system preferences",
   breadcrumbs: [
     { text: "Home", url: "/" },
     { text: "Admin", url: "/admin" },
-    { text: "Impostazioni" }
+    { text: "Settings" }
   ],
   variant: :modern,
   fixed: :top,
   show_breadcrumbs: true,
   actions: [
-    { content: button_html("Salva", "primary") },
-    { content: button_html("Annulla", "secondary") }
+    { content: button_html("Save", "primary") },
+    { content: button_html("Cancel", "secondary") }
   ]
 ) %>
 ```
 
-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
+The component supports:
+- Title with optional integrated icon
+- Descriptive subtitle
+- Complete breadcrumbs with navigation links
+- Contextual actions (buttons, menus, etc.)
+- Style variants: modern, light, dark, primary, transparent
+- Fixed positioning (top or bottom)
+- Breadcrumb visibility control
+
+### Component Previews with Lookbook
+
+BetterUI integrates [Lookbook](https://github.com/allmarkedup/lookbook) to preview UI components:
+
+1. Access `/better_ui/lookbook` in your application to view the component catalog
+2. Explore available variants and configurations for each component
+3. View source code and generated markup
+4. Interact with components in real-time
+
+Lookbook is only available in development and test environments.
+
+## 🎨 Customization
+
+### Generate a Custom Stylesheet
+
+BetterUI includes a generator to create a base stylesheet for customizing components:
+
+```bash
+# Generate a stylesheet with the default "custom" prefix
+rails generate better_ui:stylesheet
+
+# Generate a stylesheet with a custom prefix
+rails generate better_ui:stylesheet --prefix=my_theme
+```
+
+This will create:
+1. A main SCSS file with imports for all components
+2. Individual SCSS files for each component in the `app/assets/stylesheets/components/` directory
+3. Special `*_overrides.scss` files for each component that allow you to override styles without modifying the original files
+
+### Component Overrides System ✨
 
-### Preview dei componenti con Lookbook
+One of BetterUI's most powerful features is the automatic generation of override files:
+
+```bash
+# Generate override files for all components
+rails generate better_ui:stylesheet
+```
 
-BetterUI integra [Lookbook](https://github.com/allmarkedup/lookbook) per visualizzare in anteprima i componenti UI:
+This creates special `*_overrides.scss` files that:
+- Contain empty classes matching the original component files
+- Allow for clean customization without modifying the original styles
+- Support both standard and nested SCSS class structures
+- Include helpful comments for easier modification
+
+Example override file structure:
+```scss
+/* ==============================
+ * Button Component Overrides
+ * ==============================
+ * This file contains empty classes to override default styles.
+ * Add your customizations here.
+ */
 
-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
+.bui-button-primary {
+  // Override styles for .bui-button-primary here
+}
 
-Lookbook è disponibile solo negli ambienti di sviluppo e test.
+.bui-button-secondary {
+  // Override styles for .bui-button-secondary here
+}
 
-## 🎮 Personalizzazione
+// Nested class overrides
+.bui-button-with-icon {
+  .bui-icon {
+    // Override nested styles here
+  }
+}
+```
 
-### Usa l'inizializzatore
+### Use the Initializer
 
-Crea un file `config/initializers/better_ui.rb`:
+Create a `config/initializers/better_ui.rb` file:
 
 ```ruby
 BetterUi.configure do |config|
@@ -168,92 +228,92 @@ BetterUi.configure do |config|
 end
 ```
 
-### Personalizza gli stili
+### Customize Styles
 
-Sovrascrivi gli stili CSS nel tuo foglio di stile:
+Override CSS styles in your stylesheet:
 
 ```css
 .better-ui-button-primary {
-  background-color: #8b5cf6; /* Viola personalizzato */
+  background-color: #8b5cf6; /* Custom purple */
   border-color: #8b5cf6;
 }
 ```
 
-## 🛠 Sviluppo
+## 🛠 Development
 
-BetterUI utilizza una app dummy integrata per lo sviluppo e i test. Ecco come iniziare:
+BetterUI uses an integrated dummy app for development and testing. Here's how to get started:
 
-### Setup iniziale
+### Initial Setup
 
 ```bash
-# Clona il repository
+# Clone the repository
 git clone https://github.com/alessiobussolari/better_ui.git
 cd better_ui
 
-# Installa le dipendenze
+# Install dependencies
 bin/setup
 ```
 
-### Avvia l'applicazione di test
+### Start the Test Application
 
-Per vedere i componenti in azione e lavorare sulla documentazione:
+To see components in action and work on documentation:
 
 ```bash
-# Avvia il server di test
+# Start the test server
 cd test/dummy
 bin/rails server
 
-# Oppure dalla directory principale
+# Or from the main directory
 bin/rails server -b 0.0.0.0
 ```
 
-Visita `http://localhost:3000/better_ui` nel tuo browser per vedere la documentazione e testare i componenti.
+Visit `http://localhost:3000/better_ui` in your browser to see the documentation and test the components.
 
-### Flusso di sviluppo
+### Development Flow
 
-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. **Create a branch**: `git checkout -b feature/new-component`
+2. **Implement the component**: Add helpers in `app/helpers/better_ui/application_helper.rb`
+3. **Add CSS**: Insert styles in `app/assets/stylesheets/better_ui/application.css`
+4. **Document**: Create Markdown files in `docs/components/`
+5. **Test**: Verify in the dummy app that everything works correctly
+6. **Run tests**: `rake test`
 
-### Build e rilascio
+### Build and Release
 
-Per buildare la gemma localmente:
+To build the gem locally:
 
 ```bash
 bundle exec rake build
 ```
 
-Per installare la versione in sviluppo:
+To install the development version:
 
 ```bash
 bundle exec rake install
 ```
 
-## 🤝 Contribuire
+## 🤝 Contributing
 
-I contributi sono benvenuti e apprezzati! Ecco come puoi aiutare:
+Contributions are welcome and appreciated! Here's how you can help:
 
-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**
+1. **Fork** the repository on GitHub
+2. **Clone** your fork: `git clone https://github.com/YOUR-USERNAME/better_ui.git`
+3. **Create** a branch for your feature: `git checkout -b feature/amazing-improvement`
+4. **Commit** your changes: `git commit -am 'Add an amazing feature'`
+5. **Push** to the branch: `git push origin feature/amazing-improvement`
+6. Submit a **Pull Request**
 
-### Linee guida
+### Guidelines
 
-- Segui lo stile di codice esistente
-- Scrivi test per le nuove funzionalità
-- Aggiorna la documentazione
-- Crea componenti che funzionano senza JavaScript
+- Follow the existing code style
+- Write tests for new features
+- Update documentation
+- Create components that work without JavaScript
 
-## 📄 Licenza
+## 📄 License
 
-BetterUI è disponibile come open source sotto i termini della [Licenza MIT](https://opensource.org/licenses/MIT).
+BetterUI is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ---
 
-Realizzato con ❤️ da [Alessio Bussolari](https://github.com/alessiobussolari)
+Made with ❤️ by [Alessio Bussolari](https://github.com/alessiobussolari)

data/app/components/better_ui/application/alert_component.html.erb

@@ -24,4 +24,4 @@
       <%= render BetterUi::General::IconComponent.new(name: "xmark") %>
     </button>
   <% end %>
-</div> 
+</div>