better_ui 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c59e86ef83ec560909908edbbbecd0c33a3663df87de94e99fff0475be5b23d
-  data.tar.gz: dc7a3b578f0b2cc70f3e25c843dbc918723bf4d0b7d9bdb4b511e2ad073cc5fd
+  metadata.gz: 317837f4f80e12e6ab860a7a134e9f17e01f5db2d86f5b178a4c9a2bc9588f3a
+  data.tar.gz: 8815e3b40a461070b9cb178ee1a7e1e8abaccbf6cea7366ab5c079db174429f4
 SHA512:
-  metadata.gz: 66fdc7a9f14ff11b0d79caaff30d1b35ba4878dbbfcbddca7571684eb3628c62288a4fff4a33416b285c479ab96ca22ed271949184c472cb36f4131270a15552
-  data.tar.gz: abaf0df7af66450518ab1620ca0fe165e411c2b96a6accfc3a49acb91a93b82c64c7093bacbb7e5e272040275b96063dee0253608a08f406d2e1122ff78cb8c3
+  metadata.gz: 0fb96fb9537391b7448ffde247cd8d9ae4916dac0cfcd17c4efe912b061dfd05986368ebe6563549c58ce0909e9a509474ac885e136d133214f806437925726d
+  data.tar.gz: de95bf54dcd6fa022f5afa5c0867d65b7a78e8f24cab637aa7cf098f0bf01f5cabdac5e6c7b36ba1aba14833682b17174e1d229a4d428f5646d92ee876ad42f4

data/README.md

@@ -3,58 +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
+- **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 |
-| **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`:
 
@@ -64,33 +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 with breadcrumb %>
+<%= render BetterUi::Application::HeaderComponent.new(
+  title: "Dashboard",
+  subtitle: "Manage everything from here",
+  breadcrumbs: [
+    { text: "Home", url: "/" },
+    { text: "Dashboard" }
+  ],
+  actions: [
+    { content: button_html("New", "primary") }
+  ]
+) %>
+```
+
+Visit `/better_ui` in your application to see the complete documentation and examples.
+
+### The Header Component
+
+The Header component is designed to create complete page headers with numerous features:
+
+```erb
+<%= render BetterUi::Application::HeaderComponent.new(
+  title: {
+    text: "Settings",
+    icon: "settings"
+  },
+  subtitle: "Configure system preferences",
+  breadcrumbs: [
+    { text: "Home", url: "/" },
+    { text: "Admin", url: "/admin" },
+    { text: "Settings" }
+  ],
+  variant: :modern,
+  fixed: :top,
+  show_breadcrumbs: true,
+  actions: [
+    { content: button_html("Save", "primary") },
+    { content: button_html("Cancel", "secondary") }
+  ]
+) %>
 ```
 
-Visita `/better_ui` nella tua applicazione per vedere la documentazione completa e gli esempi.
+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
 
-## 🎨 Personalizzazione
+# 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 ✨
+
+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
+```
+
+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.
+ */
+
+.bui-button-primary {
+  // Override styles for .bui-button-primary here
+}
+
+.bui-button-secondary {
+  // Override styles for .bui-button-secondary here
+}
+
+// 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|
@@ -104,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/assets/javascripts/better_ui/controllers/navbar_controller.js

@@ -0,0 +1,138 @@
+// Navbar controller per gestire il comportamento del menu mobile e dei dropdown
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["menu", "dropdown", "submenu"]
+  
+  connect() {
+    // Verifica se siamo su mobile e aggiorna lo stato del menu
+    this.updateMenuState();
+    
+    // Aggiungi un event listener per il resize della finestra
+    window.addEventListener("resize", this.updateMenuState.bind(this));
+    
+    // Chiudi menu quando si clicca su un link (solo su mobile)
+    if (this.hasMenuTarget) {
+      const links = this.menuTarget.querySelectorAll("a");
+      links.forEach(link => {
+        link.addEventListener("click", () => {
+          // Se siamo su mobile, chiudi il menu
+          if (window.innerWidth < 768) {
+            this.closeMenu();
+          }
+        });
+      });
+    }
+
+    // Aggiungi listener per i click all'esterno del menu
+    document.addEventListener("click", this.handleClickOutside.bind(this))
+  }
+  
+  disconnect() {
+    // Rimuovi event listener per il resize della finestra
+    window.removeEventListener("resize", this.updateMenuState.bind(this));
+
+    // Rimuovi listener al disconnette
+    document.removeEventListener("click", this.handleClickOutside.bind(this))
+  }
+  
+  // Metodo per alternare l'apertura/chiusura del menu
+  toggleMenu(event) {
+    event.stopPropagation()
+    const isExpanded = this.menuTarget.classList.contains("hidden") === false
+    
+    if (isExpanded) {
+      this.closeMenu()
+    } else {
+      this.openMenu()
+    }
+  }
+  
+  // Metodo per chiudere il menu
+  closeMenu() {
+    this.menuTarget.classList.add("hidden")
+    
+    // Aggiorna l'attributo aria-expanded
+    const button = this.element.querySelector("[aria-controls='navbar-menu']")
+    if (button) {
+      button.setAttribute("aria-expanded", "false")
+    }
+  }
+  
+  // Metodo per aggiornare lo stato del menu in base alla dimensione della finestra
+  updateMenuState() {
+    if (this.hasMenuTarget) {
+      // Se siamo su desktop (md breakpoint - 768px)
+      if (window.innerWidth >= 768) {
+        // Assicurati che il menu sia visibile su desktop
+        this.menuTarget.classList.remove("hidden");
+        this.menuTarget.classList.add("md:block");
+      } else {
+        // Su mobile, nascondi il menu di default
+        this.menuTarget.classList.add("hidden");
+      }
+      
+      // Aggiorna l'attributo aria-expanded
+      const button = this.element.querySelector("[aria-controls='navbar-menu']");
+      if (button) {
+        const isExpanded = window.innerWidth >= 768 ? "true" : "false";
+        button.setAttribute("aria-expanded", isExpanded);
+      }
+    }
+  }
+
+  openMenu() {
+    this.menuTarget.classList.remove("hidden")
+    
+    // Chiudi tutti i dropdown nel menu mobile
+    if (this.hasSubmenuTarget) {
+      this.submenuTargets.forEach(submenu => {
+        submenu.classList.add("hidden")
+      })
+    }
+
+    // Aggiorna stato del pulsante
+    event.currentTarget.setAttribute("aria-expanded", "true")
+  }
+
+  toggleDropdown(event) {
+    event.stopPropagation()
+    const button = event.currentTarget
+    const dropdownId = button.getAttribute("aria-controls")
+    const dropdown = document.getElementById(dropdownId)
+    
+    if (dropdown) {
+      const isExpanded = button.getAttribute("aria-expanded") === "true"
+      
+      if (isExpanded) {
+        dropdown.classList.add("hidden")
+        button.setAttribute("aria-expanded", "false")
+      } else {
+        // Chiudi tutti gli altri dropdown prima di aprire quello corrente
+        if (this.hasSubmenuTarget) {
+          this.submenuTargets.forEach(submenu => {
+            if (submenu.id !== dropdownId) {
+              submenu.classList.add("hidden")
+              
+              // Trova e aggiorna il pulsante associato
+              const associatedButton = this.element.querySelector(`[aria-controls='${submenu.id}']`)
+              if (associatedButton) {
+                associatedButton.setAttribute("aria-expanded", "false")
+              }
+            }
+          })
+        }
+        
+        dropdown.classList.remove("hidden")
+        button.setAttribute("aria-expanded", "true")
+      }
+    }
+  }
+
+  handleClickOutside(event) {
+    // Chiudi il menu se si fa clic all'esterno
+    if (this.element.contains(event.target) === false) {
+      this.closeMenu()
+    }
+  }
+}