better_ui 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f8b92fdba76f5e84f09fb6a3bf9879b209e0e7dfd8f864186784db24b808c59
-  data.tar.gz: 4d21e971baeecb10c7a3c5952041ac7e6911342e0efe4d0015efb92f9f214652
+  metadata.gz: 317837f4f80e12e6ab860a7a134e9f17e01f5db2d86f5b178a4c9a2bc9588f3a
+  data.tar.gz: 8815e3b40a461070b9cb178ee1a7e1e8abaccbf6cea7366ab5c079db174429f4
 SHA512:
-  metadata.gz: 778ee8d067130b37947a227ccf1322e8cf5b82d19c9b3f7a0371cc16b62071daaeb5eb6a191898ef2b06419486fe656bc22bea4314fbf98884fdf16259ac8409
-  data.tar.gz: 1df545b428bdb281fb6f78b7be2e58e455bd6bd67f0202684f51b9e756c9ccc3e928a283f97d98a924185e1bb859b63f8cf2a91857ef49478cf6bfc3f254629d
+  metadata.gz: 0fb96fb9537391b7448ffde247cd8d9ae4916dac0cfcd17c4efe912b061dfd05986368ebe6563549c58ce0909e9a509474ac885e136d133214f806437925726d
+  data.tar.gz: de95bf54dcd6fa022f5afa5c0867d65b7a78e8f24cab637aa7cf098f0bf01f5cabdac5e6c7b36ba1aba14833682b17174e1d229a4d428f5646d92ee876ad42f4

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright Umberto Peserico
+Copyright alessiobussolari
 
 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,301 +1,319 @@
-# BetterUI
+# BetterUI 🎨
 
-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.
+[![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 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à
+> Elegant, consistent, and easily integrable UI components for your Rails applications
 
-## Panoramica
+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.
 
-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.
+## ✨ Key Features
 
-### Caratteristiche Principali
+- **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
 
-- **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à
+## 📦 Available Components
 
-## Installazione
+| Component | Description |
+|------------|-------------|
+| **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) |
 
-Aggiungi questa riga al Gemfile della tua applicazione:
+## 🚀 Installation
 
-```ruby
-gem "better_ui"
-```
-
-Per lo sviluppo con documentazione Lookbook:
+Add this line to your application's Gemfile:
 
 ```ruby
-gem "better_ui"
-gem "lookbook", group: :development
+gem 'better_ui', '~> 0.1.0'
 ```
 
-Quindi esegui:
+And then execute:
 
 ```bash
 $ bundle install
 ```
 
-## Setup
+## ⚙️ Configuration
 
-### 1. Mount Engine (Opzionale)
+### Mount the Engine
 
-Se vuoi accedere alle route interne di BetterUI, monta l'engine in `config/routes.rb`:
+Add this to your `config/routes.rb` file:
 
 ```ruby
 Rails.application.routes.draw do
-  mount BetterUi::Engine => "/better_ui"
-  # le tue altre route...
+  mount BetterUi::Engine => '/better_ui'
+  
+  # ... your other routes
 end
 ```
 
-### 2. Setup Lookbook (Raccomandato per Development)
+### Include the Assets
 
-Per accedere alla documentazione interattiva dei componenti durante lo sviluppo, monta Lookbook in `config/routes.rb`:
-
-```ruby
-Rails.application.routes.draw do
-  # Monta Lookbook solo in development
-  mount Lookbook::Engine => "/lookbook" if Rails.env.development?
+In `app/assets/stylesheets/application.css`:
 
-  # le tue altre route...
-end
+```css
+/*
+ *= require better_ui/application
+ */
 ```
 
-**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).
+## 🎮 Usage
 
-## Utilizzo
-
-I componenti Better UI possono essere utilizzati in due modi: istanziazione diretta o metodi helper.
-
-### Metodi Helper (Raccomandato)
+Once installed, you can start using the components:
 
 ```erb
-<%# Input di testo con validazione %>
-<%= bui_input_text(
-  name: 'email',
-  value: @user.email,
-  type: :email,
-  theme: :blue,
-  size: :large,
-  required: true
-) %>
+<%# Button %>
+<%= better_ui_button("Save", type: "primary") %>
+
+<%# Alert %>
+<%= better_ui_alert("Operation completed", type: "success") %>
+
+<%# Card %>
+<%= better_ui_card do %>
+  <%= better_ui_card_header("Card Title") %>
+  <%= better_ui_card_body do %>
+    <p>Card content...</p>
+  <% end %>
+<% end %>
 
-<%# Button con theme e size %>
-<%= bui_button(
-  'Invia Form',
-  theme: :green,
-  size: :large,
-  type: :submit
+<%# 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") }
+  ]
 ) %>
+```
 
-<%# Card con blocco di contenuto %>
-<%= bui_card(title: 'Profilo Utente', theme: :white) do %>
-  <p>Contenuto informazioni utente qui</p>
-<% end %>
+Visit `/better_ui` in your application to see the complete documentation and examples.
 
-<%# 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 %>
-```
+### The Header Component
 
-### Istanziazione Diretta
+The Header component is designed to create complete page headers with numerous features:
 
 ```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
+<%= 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") }
+  ]
 ) %>
 ```
 
-### Sistema di Tematizzazione
+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
 
-Tutti i componenti supportano tematizzazione consistente:
+### Component Previews with Lookbook
 
-- **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
+BetterUI integrates [Lookbook](https://github.com/allmarkedup/lookbook) to preview UI components:
 
-### Approccio Styling
+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
 
-Better UI usa un approccio TailwindCSS puro con costanti per styling manutenibile:
+Lookbook is only available in development and test environments.
 
-```ruby
-# 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
-```
+## 🎨 Customization
 
-## Componenti Disponibili
+### Generate a Custom Stylesheet
 
-Better UI include 26 componenti organizzati in tre categorie:
+BetterUI includes a generator to create a base stylesheet for customizing components:
 
-### Componenti Application (4)
-
-Componenti di layout e navigazione per interfacce applicative:
+```bash
+# Generate a stylesheet with the default "custom" prefix
+rails generate better_ui:stylesheet
 
-- **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
+# Generate a stylesheet with a custom prefix
+rails generate better_ui:stylesheet --prefix=my_theme
+```
 
-### Componenti General (22)
+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
 
-Elementi UI core per costruire interfacce:
+### Component Overrides System ✨
 
-**Display & Feedback**
+One of BetterUI's most powerful features is the automatic generation of override files:
 
-- **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
+```bash
+# Generate override files for all components
+rails generate better_ui:stylesheet
+```
 
-**Navigazione & Struttura**
+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
+  }
+}
+```
 
-- **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
+### Use the Initializer
 
-**Form & Input**
+Create a `config/initializers/better_ui.rb` file:
 
-- **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
+```ruby
+BetterUi.configure do |config|
+  config.button_defaults = {
+    class: 'rounded-lg text-sm'
+  }
+  
+  config.alert_defaults = {
+    dismissible: true
+  }
+end
+```
 
-### Componenti Form (0)
+### Customize Styles
 
-Riservati per futuri componenti form specializzati e widget form complessi.
+Override CSS styles in your stylesheet:
 
-## Personalizzazione e Styling
+```css
+.better-ui-button-primary {
+  background-color: #8b5cf6; /* Custom purple */
+  border-color: #8b5cf6;
+}
+```
 
-I componenti BetterUI usano classi Tailwind CSS. Puoi:
+## 🛠 Development
 
-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
+BetterUI uses an integrated dummy app for development and testing. Here's how to get started:
 
-```erb
-<!-- Aggiungi classi personalizzate -->
-<%= render BetterUi::General::Button::Component.new(
-  label: "Button Personalizzato",
-  classes: "my-custom-class hover:scale-105"
-) %>
-```
+### Initial Setup
 
-Better UI è progettato per essere altamente personalizzabile mantenendo consistenza:
+```bash
+# Clone the repository
+git clone https://github.com/alessiobussolari/better_ui.git
+cd better_ui
 
-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
+# Install dependencies
+bin/setup
+```
 
-## Testing
+### Start the Test Application
 
-I componenti Better UI sono testati completamente. Puoi eseguire la test suite con:
+To see components in action and work on documentation:
 
 ```bash
-bin/rails test
+# Start the test server
+cd test/dummy
+bin/rails server
+
+# Or from the main directory
+bin/rails server -b 0.0.0.0
 ```
 
-## Supporto Browser
+Visit `http://localhost:3000/better_ui` in your browser to see the documentation and test the components.
 
-I componenti BetterUI supportano tutti i browser moderni che supportano:
+### Development Flow
 
-- CSS Grid e Flexbox
-- Funzionalità JavaScript ES6+
-- Tailwind CSS
+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`
 
-## Contributing
+### Build and Release
 
-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
+To build the gem locally:
 
-### Setup Development
+```bash
+bundle exec rake build
+```
+
+To install the development version:
 
 ```bash
-git clone https://github.com/alessiobussolari/better_ui.git
-cd better_ui
-bundle install
-cd test/dummy
-bundle exec rails server
+bundle exec rake install
 ```
 
-Visita `http://localhost:3000/lookbook` per vedere la documentazione dei componenti.
+## 🤝 Contributing
 
-## Roadmap
+Contributions are welcome and appreciated! Here's how you can help:
 
-- 🎯 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
+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**
 
-## License
+### Guidelines
 
-La gem è disponibile come open source sotto i termini della [MIT License](https://opensource.org/licenses/MIT).
+- Follow the existing code style
+- Write tests for new features
+- Update documentation
+- Create components that work without JavaScript
 
-## Support
+## 📄 License
 
-- 📖 [Documentazione](https://github.com/alessiobussolari/better_ui)
-- 🐛 [Issue Tracker](https://github.com/alessiobussolari/better_ui/issues)
-- 💬 [Discussioni](https://github.com/alessiobussolari/better_ui/discussions)
+BetterUI is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ---
 
-Costruito con ❤️ da [PanDev](https://github.com/alessiobussolari)
+Made with ❤️ by [Alessio Bussolari](https://github.com/alessiobussolari)