tailmix 0.2.0 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b60ee0099a1c65d9cab150deed3820c382c472029fc35f0f7b4f3d2c8f7c7a45
-  data.tar.gz: c3744db3320269d2a04b332bb039ee3e9d7a3b0bfac334bfe79cc25fafdf2145
+  metadata.gz: f6eba946c8714d0699a6d9476c1c7b31f323418fdbf6fbc449bb96fb5ffe85f2
+  data.tar.gz: 44460ef22c33497ff09002ef084691dafdedf19be942685faf8f578155f98351
 SHA512:
-  metadata.gz: 4baebd46d43f04837c23e390e8b33633eb95542e36015090c2c23663cba343a7be759b4c01a4a81268517419c531321bfe7e3ff4dbd6350268c45bbc6d476365
-  data.tar.gz: 6a0544fe9a7bd949f466b6d5bca583e4ec7c9a6d8a2e342609c12accb0708a4ffd8d868512d80b9a679b807042025c24e287da26e8f8370893e13a3038aaac3d
+  metadata.gz: 587453b63976416198477d8b38c02ed24e7c3d48972464fa926d2ee0cad42737f324dede5e3dac92d78e584ba71cfb6552b1be7f4eb94485816a598e9d3fe5c3
+  data.tar.gz: 2d61fe96e8c2bf7ba9dc94876381bf0f5202dd0d22dd4aafe25ada2e977182b9693ae13d1f42c5d985980196ed1382587e9995fd5c614b925bab46f3159dec9f

data/.rubocop.yml

@@ -1,3 +1,6 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
 AllCops:
   TargetRubyVersion: 3.1
 

data/README.md

@@ -1,148 +1,210 @@
-# tailmix
+# Tailmix
+
+**Tailmix** is a powerful, declarative, and interactive CSS class manager for building maintainable UI components in Ruby. It's designed to work seamlessly with utility-first CSS frameworks like **Tailwind CSS**, allowing you to co-locate your style logic with your component's code—in a clean, structured, and highly reusable way.
 
 [![Gem Version](https://badge.fury.io/rb/tailmix.svg)](https://badge.fury.io/rb/tailmix)
 [![Build Status](https://github.com/alexander-s-f/tailmix/actions/workflows/main.yml/badge.svg)](https://github.com/alexander-s-f/tailmix/actions/workflows/main.yml)
 
-**Tailmix** is a powerful, declarative, and interactive class manager for building maintainable UI components in Ruby. It's designed to work seamlessly with utility-first CSS frameworks like **Tailwind CSS**, allowing you to co-locate your style logic with your component's code in a clean, structured, and highly reusable way.
-
-Inspired by modern frontend tools like CVA (Class Variance Authority), `tailmix` brings a robust styling engine to your server-side components (like those built with Arbre, ViewComponent, or Phlex).
+Inspired by modern frontend tools like CVA (Class Variance Authority), Tailmix brings a robust styling engine to your server-side components (built with Arbre, ViewComponent, Phlex, etc.).
 
 ## Philosophy
 
 * **Co-location & Isolation:** Define all style variants for a component directly within its class. No more hunting for styles in separate files. Each component is fully self-contained.
-* **Declarative First:** A beautiful DSL to *declare* your component's visual appearance based on variants like `state`, `size`, etc.
-* **Imperative Power:** A rich runtime API to dynamically and imperatively `add`, `remove`, or `toggle` classes, perfect for server-side updates via Hotwire/Turbo.
+* **Declarative First:** A beautiful DSL to declaratively describe your component's appearance based on variants like state, size, etc.
+* **Imperative Power:** A rich runtime API to dynamically add, remove, or toggle classes, perfect for server-side updates via Hotwire/Turbo.
 * **Framework-Agnostic:** Written in pure Ruby with zero dependencies, ready to be used in any project.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your Gemfile:
 
 ```ruby
 gem 'tailmix'
+````
+
+Or install it from the command line:
+
+```bash
+bundle add tailmix
 ```
 
-And then execute: `$ bundle install`
+Next, run the installer to set up the JavaScript assets:
+
+```bash
+bin/rails g tailmix:install
+```
 
-Or install it yourself as: `$ gem install tailmix`
+## Core Concepts
 
-## The DSL: A Detailed Breakdown
+You define your component's appearance using a simple `tailmix do ... end` DSL inside your class.
 
-You define a component's style "schema" using the `tailmix` DSL within your class.
+- `element :name, "base classes"`: Defines a logical part of your component (e.g., `:wrapper`, `:panel`, `:icon`).
+- `dimension :name, default: :value`: Defines a variant or "dimension" (e.g., `size` or `color`).
+- `variant :value, "classes"`: Defines the classes for a specific variant.
+- `action :name, method: :add | :toggle | :remove`: Defines a named set of UI mutations that can be applied on the server (`.apply!`) or passed to the client (`action_payload`).
+- `stimulus`: A powerful nested DSL for declaratively describing Stimulus `data-*` attributes.
 
-* `element :name, "base classes" do ... end`: Defines a "part" of your component. Every component has at least one element.
-* `dimension_name do ... end` (e.g., `state do`, `size do`): Defines a variant "dimension". The name can be anything you choose.
-* `option :name, "classes", default: true`: Defines a specific option within a dimension and its corresponding CSS classes. One option per dimension can be marked as the default.
+## Usage Example
 
-### Full Example of the DSL
+Let's build a complex `ModalComponent` from scratch.
+#### 1. Define the Component (`app/components/modal_component.rb`)
+
+This is a plain Ruby class that contains all the style and behavior logic.
 
 ```ruby
-class MyButtonComponent
+class ModalComponent
   include Tailmix
+  attr_reader :ui
 
   tailmix do
-    # Define the main element and its base classes
-    element :button, "inline-flex items-center font-medium rounded-md" do
-      # Define the 'size' dimension
-      size do
-        option :sm, "px-2.5 py-1.5 text-xs", default: true
-        option :md, "px-3 py-2 text-sm"
-        option :lg, "px-4 py-2 text-base"
+    element :base, "fixed inset-0 z-50 flex items-center justify-center" do
+      dimension :open, default: false do
+        variant true, "visible opacity-100"
+        variant false, "invisible opacity-0"
       end
+      stimulus.controller("modal")
+    end
 
-      # Define the 'intent' dimension
-      intent do
-        option :primary, "bg-blue-600 text-white hover:bg-blue-700", default: true
-        option :secondary, "bg-gray-200 text-gray-800 hover:bg-gray-300"
-        option :danger, "bg-red-600 text-white hover:bg-red-700"
+    element :overlay, "fixed inset-0 bg-black/50 transition-opacity" do
+      stimulus.context("modal").action(click: :close)
+    end
+
+    element :panel, "relative bg-white rounded-lg shadow-xl" do
+      dimension :size, default: :md do
+        variant :sm, "w-full max-w-sm p-4"
+        variant :md, "w-full max-w-md p-6"
       end
     end
 
-    # Define another element, like an icon
-    element :icon, "inline-block" do
-      size do
-        option :sm, "h-4 w-4"
-        option :md, "h-5 w-5", default: true
-        option :lg, "h-6 w-6"
+    element :close_button, "absolute top-2 right-2 p-1 text-gray-400" do
+      stimulus.context("modal").action(click: :close)
+    end
+
+    element :confirm_button, "px-4 py-2 bg-blue-600 text-white rounded-md" do
+      stimulus.controller("form-submission")
+              .action(:click, :show_pending_state)
+              .action_payload(:show_pending_state, as: :pending_data)
+    end
+    
+    action :show_pending_state, method: :add do
+      element :confirm_button do
+        classes "is-loading"
+        data pending: true
       end
     end
   end
-  # ...
+
+  def initialize(open: false, size: :md)
+    @ui = tailmix(open: open, size: size)
+  end
 end
 ```
 
-## Usage
+#### 2. Use in a View (Arbre, ERB, etc.)
+
+Thanks to Tailmix's design, you can pass `ui` objects directly to many rendering helpers.
 
-### 1. Initialization
+##### Arbre
 
-Inside your component, call the `tailmix` helper to create an interactive style manager. You can pass initial variants to it.
+The API is seamless. The `ui` object behaves like an attributes hash automatically.
+
+Ruby
 
 ```ruby
-class MyButtonComponent
-  # ... (tailmix DSL from above)
+# app/views/components/my_modal.arb
+# 1. Instantiate the component with the desired variants
+modal = ModalComponent.new(open: true, size: :sm)
 
-  attr_reader :classes
+# 2. Render by passing the ui objects directly to Arbre's tag helpers
+div modal.ui.base do
+  div modal.ui.overlay
 
-  def initialize(intent: :primary, size: :md)
-    # The `tailmix` helper creates and returns the manager object
-    @classes = tailmix(intent: intent, size: size)
-  end
-  
-  def render
-    # The manager's methods map to your elements.
-    # Ruby's `to_s` is called implicitly when rendering.
-    "<button class='#{@classes.button}'>
-       <span class='#{@classes.icon}'></span>
-       Click me
-     </button>"
+  div modal.ui.panel do
+    # ... your content ...
+    button modal.ui.confirm_button, "Confirm"
   end
 end
+```
+
+##### ERB / Rails Tag Helpers
+
+In ERB, the idiomatic way to pass a hash-like object as attributes is with the double splat (`**`) operator.
 
-# Renders a medium primary button by default
-button = MyButtonComponent.new
-button.render
+Фрагмент кода
 
-# Renders a small danger button
-button = MyButtonComponent.new(intent: :danger, size: :sm)
-button.render
 ```
+<%# app/views/pages/home.html.erb %>
+<% modal = ModalComponent.new(open: true, size: :sm) %>
 
-### 2. Dynamic & Imperative Usage
+<%= tag.div **modal.ui.base do %>
+  <%= tag.div **modal.ui.overlay %>
 
-This is where `tailmix` truly shines. The `@classes` object is a live manager that you can modify. This is perfect for server-side re-rendering with Hotwire/Turbo.
+  <%= tag.div **modal.ui.panel do %>
+    <%# ... your content ... %>
+    <%= tag.button "Confirm", **modal.ui.confirm_button %>
+  <% end %>
+<% end %>
+```
 
-```ruby
-class MyButtonComponent
-  # ...
+#### 3. Bring it to Life with Stimulus
+
+The `action_payload` helper makes it easy to connect server-side definitions with client-side behavior.
+
+JavaScript
+
+```js
+// app/javascript/controllers/form_submission_controller.js
+import { Controller } from "@hotwired/stimulus"
+import Tailmix from "tailmix"
+
+export default class extends Controller {
+  static values = { pendingData: Object }
 
-  # A method that might be called during a Turbo Stream update
-  def set_loading_state!
-    # The `combine` method updates the declarative state
-    @classes.combine(intent: :secondary)
+  showPendingState(event) {
+    event.preventDefault()
     
-    # The imperative API allows for fine-grained control
-    @classes.button.add("cursor-wait opacity-75")
-    @classes.icon.add("animate-spin")
-  end
+    // Instantly apply UI changes from the payload
+    Tailmix.run({
+      config: this.pendingDataValue,
+      controller: this
+    });
+
+    // ... then submit the form or send an AJAX request
+  }
+}
+```
 
-  def remove_loading_state!
-    @classes.combine(intent: :primary) # Revert to original intent
-    @classes.button.remove("cursor-wait opacity-75")
-    @classes.icon.remove("animate-spin")
-  end
-end
+## Developer Tools
+
+Tailmix comes with built-in introspection tools to improve your development experience. Access them via the `.dev` namespace on your component class.
 
-button = MyButtonComponent.new(intent: :primary)
-button.set_loading_state!
-button.render # Renders the button in a loading state
+#### Component Documentation
 
-button.remove_loading_state!
-button.render # Renders the button back in its primary state
+Get a cheat sheet of all available `dimensions` and `actions` right in your console.
+
+```ruby
+puts ModalComponent.dev.docs
 ```
 
-### 3. The Bridge to JavaScript (Stimulus)
+#### Stimulus Controller Generator
+
+Tailmix can analyze your component and scaffold a perfect boilerplate Stimulus controller with all targets, values, and action methods.
+
+```ruby
+puts ModalComponent.dev.stimulus.scaffold("modal")
+```
 
-While `tailmix` is a server-side library, it enables clean integration with JavaScript controllers like Stimulus by providing the "source of truth" for classes. You can create a helper to export variants to `data-` attributes, keeping your JS free of hardcoded style strings.
+## Configuration
+
+You can configure Tailmix by creating an initializer:
+
+```ruby
+# config/initializers/tailmix.rb
+Tailmix.configure do |config|
+  # The attribute used by the universal JS selector.
+  config.element_selector_attribute = "data-tm-el"
+end
+```
 
 ## Contributing
 

data/app/javascript/tailmix/finder.js

@@ -0,0 +1,15 @@
+/**
+ * Finds an element by the new Tailmix selector convention.
+ * e.g., [data-tailmix-panel]
+ * @param {HTMLElement} rootElement
+ * @param {string} name - The logical name of the element (e.g., "panel").
+ * @returns {HTMLElement|null}
+ */
+export function findElement(rootElement, name) {
+    const selector = `[data-tailmix-${name}]`;
+
+    if (rootElement.matches(selector)) {
+        return rootElement;
+    }
+    return rootElement.querySelector(selector);
+}

data/app/javascript/tailmix/index.js

@@ -0,0 +1,7 @@
+import { runFromStimulus } from './stimulus_adapter';
+
+const Tailmix = {
+    run: runFromStimulus
+};
+
+export default Tailmix;

data/app/javascript/tailmix/mutator.js

@@ -0,0 +1,28 @@
+/**
+ * @param {HTMLElement} element
+ * @param {object} command - { field: "classes", method: "toggle", payload: "hidden" }.
+ */
+export function applyCommand(element, command) {
+    const { field, method, payload } = command;
+
+    if (field === 'classes') {
+        payload.split(' ').forEach(klass => {
+            if (klass) element.classList[method](klass);
+        });
+    } else if (field === 'data') {
+        for (const key in payload) {
+            const attributeName = `data-${key.replace(/_/g, '-')}`;
+            const value = payload[key];
+
+            if (method === 'remove') {
+                element.removeAttribute(attributeName);
+            } else if (method === 'toggle') {
+                element.hasAttribute(attributeName)
+                    ? element.removeAttribute(attributeName)
+                    : element.setAttribute(attributeName, value);
+            } else { // 'add'
+                element.setAttribute(attributeName, value);
+            }
+        }
+    }
+}

data/app/javascript/tailmix/runner.js

@@ -0,0 +1,7 @@
+/**
+ * TailmixRunner
+ *
+ */
+export default class TailmixRunner {
+
+}

data/app/javascript/tailmix/stimulus_adapter.js

@@ -0,0 +1,37 @@
+import { findElement as findElementByAttribute } from './finder';
+import { applyCommand } from './mutator';
+
+/**
+ * @param {object} params
+ * @param {object} params.config
+ * @param {StimulusController} params.controller
+ */
+export function runFromStimulus({ config, controller }) {
+    if (!config?.mutations) {
+        console.error("Invalid Tailmix config:", config);
+        return;
+    }
+
+    for (const elementName in config.mutations) {
+        const targetElement = findElement(elementName, controller);
+
+        if (!targetElement) {
+            console.warn(`Tailmix: Element "${elementName}" not found.`);
+            continue;
+        }
+
+        const commands = config.mutations[elementName];
+
+        for (const command of commands) {
+            applyCommand(targetElement, command);
+        }
+    }
+}
+
+function findElement(name, controller) {
+    const targetName = `${name}Target`;
+    if (controller[targetName]) {
+        return controller[targetName];
+    }
+    return findElementByAttribute(controller.element, name);
+}

data/examples/_modal_component.arb

@@ -0,0 +1,36 @@
+# Arbre view:
+
+modal = SuperModalComponent.new(size: :lg, open: true)
+
+# modal.lock!
+ui = modal.ui
+
+div ui.base do
+  div ui.overlay
+  div ui.open do
+    "open"
+  end
+
+  div ui.panel do
+    button ui.close_button do
+      span "Close"
+    end
+
+    h3 ui.title do
+      "Payment Successful"
+    end
+
+    div ui.body do
+      "Your payment has been successfully submitted. We’ve sent you an email with all of the details of your order."
+    end
+
+    div ui.footer do
+      button ui.confirm_button do
+        span "Confirm Purchase"
+        div ui.spinner do
+          span "Loading..."
+        end
+      end
+    end
+  end
+end

data/examples/modal_component.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../lib/tailmix"
+
+class ModalComponent
+  include Tailmix
+  attr_reader :ui
+
+  tailmix do
+    element :base, "fixed inset-0 z-50 flex items-center justify-center" do
+      dimension :open, default: true do
+        variant true, "visible opacity-100"
+        variant false, "invisible opacity-0"
+      end
+      stimulus.controller("modal").action_payload(:toggle, as: :toggle_data)
+    end
+
+    element :overlay, "fixed inset-0 bg-black/50 transition-opacity" do
+      stimulus.context("modal").action(:click, :close)
+    end
+
+    element :panel, "relative bg-white rounded-lg shadow-xl transition-transform transform" do
+      dimension :size, default: :md do
+        variant :sm, "w-full max-w-sm p-4" do
+          classes "dark:text-slate-400", group: :dark_mode
+          classes "one two"
+        end
+        variant :md, "w-full max-w-md p-6"
+        variant :lg, "w-full max-w-lg p-8"
+      end
+      stimulus.context("modal").target("panel")
+    end
+
+    element :title, "text-lg font-semibold text-gray-900"
+    element :body, "mt-2 text-sm text-gray-600"
+    element :close_button, "absolute top-2 right-2 p-1 text-gray-400 rounded-full hover:bg-gray-100 hover:text-gray-600" do
+      stimulus.context("modal").action(:click, :close)
+    end
+
+    element :footer, "mt-4 pt-4 border-t flex justify-end"
+    element :confirm_button, "relative inline-flex items-center px-4 py-2 bg-blue-600 text-white font-semibold rounded-md hover:bg-blue-700" do
+      stimulus.controller("form-submission")
+              .action(:click, :submit)
+              .action_payload(:enter_pending_state, as: :pending_data)
+    end
+
+    element :spinner, "absolute inset-0 flex items-center justify-center hidden"
+
+    action :toggle, method: :toggle do
+      element :overlay do
+        classes "hidden"
+      end
+      element :panel do
+        classes "hidden"
+      end
+    end
+
+    action :lock, method: :add do
+      element :close_button do
+        classes "hidden"
+      end
+      element :panel do
+        data locked: true, reason: "processing"
+      end
+    end
+
+    action :enter_pending_state, method: :add do
+      element :confirm_button do
+        classes "opacity-75 cursor-not-allowed"
+      end
+      element :spinner do
+        classes "flex"
+      end
+    end
+  end
+
+  def initialize(size: :md, open: false)
+    @ui = tailmix(size: size, open: open)
+  end
+
+  def lock!
+    @ui.action(:lock).apply!
+  end
+end
+
+puts "-" * 100
+# puts ModalComponent.dev.docs
+# puts ""
+# puts "Scaffolds:"
+# puts ""
+# puts ModalComponent.dev.stimulus.scaffold
+# puts ""
+
+# >>>
+#
+# == Tailmix Docs for ModalComponent ==
+# Signature: `initialize(open: true, size: :md)`
+#
+# Dimensions:
+#   - open (default: true)
+#     - true:
+#       - classes : "visible opacity-100"
+#     - false:
+#       - classes : "invisible opacity-0"
+#   - size (default: :md)
+#     - :sm:
+#       - classes : "w-full max-w-sm p-4"
+#       - classes (group: :dark_mode): "dark:text-slate-400"
+#       - classes : "one two"
+#     - :md:
+#       - classes : "w-full max-w-md p-6"
+#     - :lg:
+#       - classes : "w-full max-w-lg p-8"
+#
+# Actions:
+#   - :toggle
+#   - :lock
+#   - :enter_pending_state
+#
+# Stimulus:
+#   - on `modal` controller:
+#     - Targets: panel
+#     - Actions: close
+#
+# Stimulus:
+#   - on `form-submission` controller:
+#     - Actions: submit
+#
+# Scaffolds:
+#
+# // Generated by Tailmix for the "modal" controller
+# // Path: app/javascript/controllers/modal_controller.js
+# import { Controller } from "@hotwired/stimulus"
+# import Tailmix from "tailmix"
+#
+# export default class extends Controller {
+#   static targets = ['panel']
+#   static values = { toggleData: Object }
+#
+#   connect() {
+#     console.log("modal controller connected to", this.element);
+#   }
+#   toggle(event) {
+#      if (event) event.preventDefault();
+#      Tailmix.run({ config: this.toggleDataValue, controller: this });
+#   }
+#
+#   close() {
+#     console.log('modal#close fired');
+#   }
+# }
+# ------------------------------------------------------------
+#
+# // Generated by Tailmix for the "form-submission" controller
+# // Path: app/javascript/controllers/form-submission_controller.js
+# import { Controller } from "@hotwired/stimulus"
+# import Tailmix from "tailmix"
+#
+# export default class extends Controller {
+#   static targets = []
+#   static values = { pendingData: Object }
+#
+#   connect() {
+#     console.log("form-submission controller connected to", this.element);
+#   }
+#   enterPendingState(event) {
+#      if (event) event.preventDefault();
+#      Tailmix.run({ config: this.pendingDataValue, controller: this });
+#   }
+#
+#   submit() {
+#     console.log('form-submission#submit fired');
+#   }
+# }
+# ------------------------------------------------------------
+
+
+
+
+modal = ModalComponent.new(size: :lg, open: true)
+# modal.lock!
+ui = modal.ui
+
+
+def stringify_keys(obj)
+  case obj
+  when Hash
+    obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+  when Array
+    obj.map { |v| stringify_keys(v) }
+  else
+    obj
+  end
+end
+
+# puts "Definition:"
+# puts JSON.pretty_generate(stringify_keys(ModalComponent.tailmix_definition.to_h))
+# ui.action(:lock).apply!
+
+ModalComponent.dev.elements.each do |element_name|
+  element = ui.send(element_name)
+  puts element_name
+  element.each_attribute do |attribute|
+    attribute.each do |key, value|
+      puts "    #{key} :-> #{value}"
+    end
+    puts ""
+  end
+end