fernandes-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02fd9e64f88c0ae8270f7891857c1d3de61489da4a90894347d215395c22f09a
+  data.tar.gz: a7888a8e95b7e44e4d4ec0da67fedce961c8b84b3b4fea343a35e4dc3864592d
+SHA512:
+  metadata.gz: 343cc0a615f1e5454d4f2f1f989ca5f3e3348288f46954ebc26958f74e2ca2a24ac44fbdd553e3cc511ce5e1d5adb92efc5b22bf1066b7aa9fbd5b4af5b56afb
+  data.tar.gz: adfddca0b82cb569fef6e98b080a12879aa768700f37410f63b96fae8390745c9a24c3aad9ee5af63bc2cff6eeba6291733b40c2299276b6cbe1d720c2579b9f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Celso Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,392 @@
+# UI Engine
+
+![UI Logo](./logo.png)
+
+A Rails engine providing a component library with Tailwind CSS 4 support. Designed to work seamlessly with multiple Rails versions (6, 7, and 8) and different asset pipelines (Propshaft, Sprockets, and Node/Bun).
+
+## Features
+
+- ✅ **Tailwind CSS 4** - CSS-first configuration using `@import`, `@source`, and `@theme`
+- ✅ **Multi-Pipeline Support** - Works with Propshaft (Rails 8), Sprockets (Rails 6/7), and Node/Bun bundlers
+- ✅ **Importmap Ready** - JavaScript modules via importmaps or bundlers
+- ✅ **Flexible Installation** - Automatic detection of your app's asset pipeline
+- ✅ **Rails 6-8 Compatible** - Supports Rails 6.0+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ui"
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate ui:install
+```
+
+The installer will automatically detect your asset pipeline and configure the engine appropriately.
+
+## Usage
+
+The UI Engine provides CSS variables, Stimulus controllers, and components. You configure Tailwind CSS in your application, and the installer does this automatically.
+
+### JavaScript Integration
+
+The engine supports two approaches for JavaScript integration:
+
+#### **Option 1: Importmaps (Rails 8 Default, Zero-Build)**
+
+The engine automatically configures importmap pins. Just import and use:
+
+```javascript
+// app/javascript/application.js
+import { Application } from "@hotwired/stimulus"
+import * as UI from "ui"
+
+const application = Application.start()
+
+// Register all UI controllers
+UI.registerControllers(application)
+
+console.log("UI Engine version:", UI.version)
+```
+
+#### **Option 2: JavaScript Bundlers (Bun, esbuild, Webpack)**
+
+Install the engine as an npm package:
+
+```bash
+bun add @ui/engine
+# or
+npm install @ui/engine
+```
+
+Then import in your bundled JavaScript:
+
+```javascript
+// app/javascript/application.js
+import { Application } from "@hotwired/stimulus"
+import * as UI from "@ui/engine"
+
+const application = Application.start()
+
+// Register all UI controllers
+UI.registerControllers(application)
+```
+
+### Selective Controller Import
+
+You can import only the controllers you need for better performance and tree-shaking:
+
+#### **Import Individual Controllers from Main Module**
+
+```javascript
+import { Application } from "@hotwired/stimulus"
+import { HelloController, DropdownController } from "ui"
+
+const application = Application.start()
+application.register("ui--hello", HelloController)
+application.register("ui--dropdown", DropdownController)
+```
+
+#### **Import Directly from Controller Files (Importmap)**
+
+```javascript
+import { Application } from "@hotwired/stimulus"
+import HelloController from "ui/controllers/hello_controller"
+
+const application = Application.start()
+application.register("ui--hello", HelloController)
+```
+
+#### **Selective Registration with Helper**
+
+```javascript
+import { Application } from "@hotwired/stimulus"
+import { HelloController, registerControllersInto } from "ui"
+
+const application = Application.start()
+
+// Register only specific controllers
+registerControllersInto(application, {
+  "ui--hello": HelloController
+  // Don't register DropdownController
+})
+```
+
+### Benefits of Selective Import
+
+✅ **Tree-shaking** - Bundlers eliminate unused code
+✅ **Flexibility** - Choose exactly what to import
+✅ **Performance** - Load only what you need
+✅ **Compatibility** - Works with both importmaps and bundlers
+
+## Available Components
+
+The engine currently provides the following Stimulus controllers and components:
+
+### **Accordion** (`ui--accordion`)
+Collapsible content sections with smooth CSS transitions. Supports single mode (only one item open) and multiple mode (multiple items can be open simultaneously).
+
+**Usage:**
+```erb
+<%= render "ui/accordion/accordion", type: "single" do %>
+  <%= render "ui/accordion/item", value: "item-1", initial_open: true do %>
+    <%= render "ui/accordion/trigger" do %>
+      Getting Started
+    <% end %>
+    <%= render "ui/accordion/content" do %>
+      <p>Follow the installation instructions to get started.</p>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+### **Dropdown** (`ui--dropdown`)
+Dropdown menu component with toggle functionality.
+
+### **Hello** (`ui--hello`)
+Example component demonstrating Stimulus controller basics.
+
+### CSS Variables
+
+Import engine CSS variables in your Tailwind config:
+
+```css
+@import "ui/application.css";
+```
+
+This provides variables like `--ui-primary`, `--ui-spacing-*`, etc.
+
+### Tailwind Configuration
+
+Your `app/assets/stylesheets/application.tailwind.css` should include:
+
+```css
+@import "tailwindcss";
+@import "ui/application.css";  /* Engine CSS variables */
+
+/* Scan engine files for Tailwind classes */
+@source "../../javascript/**/*.js";
+@source "../../views/**/*.erb";
+
+/* If using gems, also scan the gem paths */
+@source "../../../.bundle/ruby/*/gems/ui-*/app/views/**/*.erb";
+@source "../../../.bundle/ruby/*/gems/ui-*/app/javascript/**/*.js";
+
+@theme {
+  /* Your customizations */
+}
+```
+
+### Building CSS
+
+```bash
+# One-time build
+bun run build:css
+
+# Watch for changes (development)
+bun run build:css:watch
+
+# Production build (minified)
+bun run build:css:prod
+```
+
+### Development Workflow
+
+```bash
+# Start Rails server + Tailwind watch
+bin/dev
+```
+
+This runs both the Rails server and Tailwind CSS watcher simultaneously.
+
+## Development
+
+### Running the Dummy App
+
+The engine includes a dummy Rails application for testing:
+
+```bash
+cd test/dummy
+bin/dev
+```
+
+This will start both the Rails server and Tailwind CSS watch process.
+
+### Building CSS
+
+```bash
+# One-time build
+bun run build:css
+
+# Watch for changes
+bun run build:css:watch
+
+# Production build (minified)
+bun run build:css:prod
+```
+
+### Project Structure
+
+```
+app/
+├── assets/
+│   └── stylesheets/ui/
+│       └── application.css     # CSS variables (shipped with gem)
+├── behaviors/ui/               # Shared behavior modules (always loaded)
+│   ├── button_behavior.rb
+│   └── ...
+├── components/ui/              # Phlex components (loaded if phlex-rails available)
+│   ├── button.rb
+│   └── ...
+├── view_components/ui/         # ViewComponents (loaded if view_component available)
+│   ├── button_component.rb
+│   └── ...
+├── javascript/ui/
+│   └── index.js                # JavaScript entry point
+├── views/ui/                   # ERB partials (always available)
+│   ├── _button.html.erb
+│   └── ...
+└── controllers/ui/             # Engine controllers
+
+config/
+└── importmap.rb                # Importmap pins for JS modules
+
+lib/
+├── generators/ui/install/
+│   ├── install_generator.rb   # Installation generator
+│   └── templates/             # Templates for host app setup
+└── ui/
+    ├── configuration.rb       # UI.configure settings
+    └── engine.rb              # Engine configuration
+
+test/dummy/                     # Test application
+├── app/assets/stylesheets/
+│   └── application.tailwind.css  # Tailwind config (NOT in engine!)
+└── package.json               # Tailwind CLI (NOT in engine!)
+```
+
+## Component Formats
+
+The engine supports three component formats:
+
+| Format | Directory | Required Gem | Description |
+|--------|-----------|--------------|-------------|
+| **ERB Partials** | `app/views/ui/` | None | Always available, uses Behaviors |
+| **Phlex** | `app/components/ui/` | `phlex-rails` >= 2.0 | Ruby-first components |
+| **ViewComponent** | `app/view_components/ui/` | `view_component` >= 3.0 | GitHub's ViewComponent |
+
+### Automatic Loading
+
+By default, the engine automatically detects which gems are available and loads the appropriate components:
+
+- **Behaviors** (`app/behaviors/ui/`) - Always loaded (required for ERB)
+- **Phlex** - Loaded if `phlex-rails` gem is present and version >= 2.0.0
+- **ViewComponent** - Loaded if `view_component` gem is present and version >= 3.0.0
+
+### Manual Configuration
+
+You can override automatic detection by configuring before Rails loads. Add to `config/application.rb` **before** `Bundler.require`:
+
+```ruby
+# config/application.rb
+require_relative "boot"
+
+# Configure UI before Bundler.require loads the engine
+require "ui/configuration"
+UI.configure do |c|
+  c.enable_phlex = true           # Force enable (skip version check)
+  c.enable_view_component = false # Force disable (don't load even if gem exists)
+end
+
+require "rails/all"
+Bundler.require(*Rails.groups)
+# ...
+```
+
+#### Configuration Options
+
+| Value | Behavior |
+|-------|----------|
+| `nil` (default) | Auto-detect: loads if gem available AND version meets minimum |
+| `true` | Force enable: loads if gem available (ignores version check) |
+| `false` | Force disable: never loads, even if gem is available |
+
+#### Use Cases
+
+**Force Enable** - Testing with unsupported gem versions:
+```ruby
+UI.configure do |c|
+  c.enable_phlex = true  # Use Phlex even if version < 2.0
+end
+```
+
+**Force Disable** - Legacy gems in app that shouldn't be used:
+```ruby
+UI.configure do |c|
+  c.enable_view_component = false  # Don't load even though gem exists
+end
+```
+
+**ERB Only** - Minimal setup without optional dependencies:
+```ruby
+UI.configure do |c|
+  c.enable_phlex = false
+  c.enable_view_component = false
+end
+```
+
+## Architecture: Why Tailwind Config Lives in Host App
+
+**Key Principle:** The engine provides **styled components**, not Tailwind configuration.
+
+- **Engine provides:** CSS variables, JavaScript, views with Tailwind classes
+- **Host app provides:** Tailwind compilation, `@source` configuration, theme customization
+
+This approach:
+- ✅ Allows each app to customize Tailwind output
+- ✅ Enables apps to scan their own files + engine files
+- ✅ Avoids conflicts with existing Tailwind setups
+- ✅ Keeps engine gem size small (no compiled CSS)
+- ✅ Supports different Rails versions and asset pipelines
+
+## Tailwind CSS 4 Configuration
+
+Your application (not the engine) configures Tailwind. The generator creates `app/assets/stylesheets/application.tailwind.css`:
+
+```css
+@import "tailwindcss";
+@import "ui/application.css";  /* Import engine CSS variables */
+
+/* Scan YOUR app files */
+@source "../../javascript/**/*.js";
+@source "../../views/**/*.erb";
+
+/* Scan ENGINE files for Tailwind classes */
+@source "../../../../../app/javascript/**/*.js";  /* If local gem */
+@source "../../../../../app/views/**/*.erb";      /* If local gem */
+
+/* Or scan bundled gem (adjust path as needed) */
+@source "../../../.bundle/ruby/*/gems/ui-*/app/**/*.{erb,rb,js}";
+
+@theme {
+  /* Customize using engine variables */
+  --color-primary: var(--ui-primary);
+}
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"