better_ui 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 317837f4f80e12e6ab860a7a134e9f17e01f5db2d86f5b178a4c9a2bc9588f3a
-  data.tar.gz: 8815e3b40a461070b9cb178ee1a7e1e8abaccbf6cea7366ab5c079db174429f4
+  metadata.gz: ee8e6a1b636ddcd65276d5c410c5b0c9a239d236cdbf507d168bb68abe63c12d
+  data.tar.gz: 930f7752b6c813943b49d29bd635da5109355f036eea0bf1d5fc9aed45932173
 SHA512:
-  metadata.gz: 0fb96fb9537391b7448ffde247cd8d9ae4916dac0cfcd17c4efe912b061dfd05986368ebe6563549c58ce0909e9a509474ac885e136d133214f806437925726d
-  data.tar.gz: de95bf54dcd6fa022f5afa5c0867d65b7a78e8f24cab637aa7cf098f0bf01f5cabdac5e6c7b36ba1aba14833682b17174e1d229a4d428f5646d92ee876ad42f4
+  metadata.gz: f91edcfb87541fbdeb97e2bc3899c1b1d3a8508bd94a6e6a9955ea56940830cfcc98df3e23f82e9bcb975039b6d3122c36f7c0e75316822ec11f03d206105647
+  data.tar.gz: 9422f6159176dc75cd254009f55660831aca51c98e7a4d829a5ab6b4911d5fc569f44ae05c549a452d5fd403a844a1b589642244c1922f485f59874094618921

data/README.md

@@ -1,319 +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)
 
-> Elegant, consistent, and easily integrable UI components for your Rails applications
+A comprehensive UI component library for Rails applications built with ViewComponent and Tailwind CSS, following BEM methodology.
 
-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 Components](https://via.placeholder.com/800x400?text=Better+UI+Components)
 
-## ✨ Key Features
+## Table of Contents
 
-- **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
+- [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)
 
-## 📦 Available Components
+## Overview
 
-| 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) |
+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.
 
-## 🚀 Installation
+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
 
-Add this line to your application's Gemfile:
+For more detailed information, see the [components documentation](COMPONENTS.md).
 
-```ruby
-gem 'better_ui', '~> 0.1.0'
-```
-
-And then execute:
-
-```bash
-$ bundle install
-```
+## Installation
 
-## ⚙️ Configuration
+### Basic Installation
 
-### Mount the Engine
-
-Add this to your `config/routes.rb` file:
+1. Add the gem to your Gemfile:
 
 ```ruby
-Rails.application.routes.draw do
-  mount BetterUi::Engine => '/better_ui'
-  
-  # ... your other routes
-end
+gem 'better_ui'
 ```
 
-### Include the Assets
-
-In `app/assets/stylesheets/application.css`:
-
-```css
-/*
- *= require better_ui/application
- */
-```
-
-## 🎮 Usage
-
-Once installed, you can start using the components:
-
-```erb
-<%# 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 %>
+2. Run bundle install:
 
-<%# 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") }
-  ]
-) %>
+```bash
+bundle install
 ```
 
-Visit `/better_ui` in your application to see the complete documentation and examples.
-
-### The Header Component
+3. Run the installer:
 
-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") }
-  ]
-) %>
+```bash
+bin/rails generate better_ui:install
 ```
 
-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:
+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/`
 
-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
+### Advanced Installation Options
 
-Lookbook is only available in development and test environments.
+You can customize the installation process with the following options:
 
-## 🎨 Customization
-
-### Generate a Custom Stylesheet
+```bash
+# Skip mounting the engine in routes
+bin/rails generate better_ui:install --skip-routes
 
-BetterUI includes a generator to create a base stylesheet for customizing components:
+# Skip generating stylesheets
+bin/rails generate better_ui:install --skip-stylesheets
 
-```bash
-# Generate a stylesheet with the default "custom" prefix
-rails generate better_ui:stylesheet
+# Skip creating the configuration file
+bin/rails generate better_ui:install --skip-config
 
-# Generate a stylesheet with a custom prefix
-rails generate better_ui:stylesheet --prefix=my_theme
+# All options together
+bin/rails generate better_ui:install --skip-routes --skip-stylesheets --skip-config
 ```
 
-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
+### Tailwind CSS Configuration
 
-### Component Overrides System ✨
+Better UI requires Tailwind CSS to be properly configured in your application. If you haven't already set up Tailwind CSS, follow these steps:
 
-One of BetterUI's most powerful features is the automatic generation of override files:
+1. Install Tailwind CSS in your Rails application:
 
 ```bash
-# Generate override files for all components
-rails generate better_ui:stylesheet
+bin/rails tailwindcss:install
 ```
 
-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
+2. Configure Tailwind to include Better UI's components:
 
-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
-}
+In your `tailwind.config.js` file, add:
 
-// Nested class overrides
-.bui-button-with-icon {
-  .bui-icon {
-    // Override nested styles here
-  }
+```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...
 }
 ```
 
-### Use the Initializer
-
-Create a `config/initializers/better_ui.rb` file:
+For more detailed installation instructions, see [INSTALLATION.md](INSTALLATION.md).
 
-```ruby
-BetterUi.configure do |config|
-  config.button_defaults = {
-    class: 'rounded-lg text-sm'
-  }
-  
-  config.alert_defaults = {
-    dismissible: true
-  }
-end
-```
+## Documentation
 
-### Customize Styles
+After installation, you can access the interactive documentation at:
 
-Override CSS styles in your stylesheet:
-
-```css
-.better-ui-button-primary {
-  background-color: #8b5cf6; /* Custom purple */
-  border-color: #8b5cf6;
-}
+```
+http://localhost:3000/better_ui
 ```
 
-## 🛠 Development
+This provides:
+- Interactive component previews
+- Component API documentation
+- Usage examples and code snippets
+- Styling reference
 
-BetterUI uses an integrated dummy app for development and testing. Here's how to get started:
+## Usage
 
-### Initial Setup
+Using Better UI components in your views is straightforward:
 
-```bash
-# Clone the 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 }
+) %>
 
-# Install dependencies
-bin/setup
+<%# Panel component %>
+<%= render BetterUi::General::PanelComponent.new(title: 'User Details') do %>
+  <p>This is the panel content</p>
+<% end %>
 ```
 
-### Start the Test Application
+For more detailed usage instructions, see [USAGE.md](USAGE.md).
 
-To see components in action and work on documentation:
+## Customization
 
-```bash
-# Start the test server
-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
+
+Example of customizing a component style:
 
-# Or from the main directory
-bin/rails server -b 0.0.0.0
+```scss
+// app/assets/stylesheets/components/_button_overrides.scss
+@layer components {
+  .bui-button {
+    &--primary {
+      @apply bg-indigo-600 hover:bg-indigo-700;
+    }
+  }
+}
 ```
 
-Visit `http://localhost:3000/better_ui` in your browser to see the documentation and test the components.
+For more detailed customization instructions, see [CUSTOMIZATION.md](CUSTOMIZATION.md).
 
-### Development Flow
+## Components
 
-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`
+Better UI includes a wide range of components categorized into:
 
-### Build and Release
+- **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
 
-To build the gem locally:
+For a full list of available components and their documentation, see [COMPONENTS.md](COMPONENTS.md).
 
-```bash
-bundle exec rake build
-```
+## Testing
 
-To install the development version:
+Better UI components are thoroughly tested. You can run the test suite with:
 
 ```bash
-bundle exec rake install
+bin/rails test
 ```
 
-## 🤝 Contributing
-
-Contributions are welcome and appreciated! Here's how you can help:
-
-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**
+For more detailed testing instructions, see [TESTING.md](TESTING.md).
 
-### Guidelines
+## Contributing
 
-- Follow the existing code style
-- Write tests for new features
-- Update documentation
-- Create components that work without JavaScript
+Contributions are welcome! Please check out our [contribution guidelines](CONTRIBUTING.md).
 
-## 📄 License
+## License
 
-BetterUI is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Better UI is available as open source under the terms of the [MIT License](LICENSE).
 
----
+## Resources
 
-Made with ❤️ by [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 */