tailmix 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6eba946c8714d0699a6d9476c1c7b31f323418fdbf6fbc449bb96fb5ffe85f2
-  data.tar.gz: 44460ef22c33497ff09002ef084691dafdedf19be942685faf8f578155f98351
+  metadata.gz: 25625758329e8524ce4fa37154be93d929b43ce85dfc5bb5669e8646b82ebd88
+  data.tar.gz: 1a98f9b38e7799819579309691e6692ec94ac5cf1358159c6c6431cc1d16c920
 SHA512:
-  metadata.gz: 587453b63976416198477d8b38c02ed24e7c3d48972464fa926d2ee0cad42737f324dede5e3dac92d78e584ba71cfb6552b1be7f4eb94485816a598e9d3fe5c3
-  data.tar.gz: 2d61fe96e8c2bf7ba9dc94876381bf0f5202dd0d22dd4aafe25ada2e977182b9693ae13d1f42c5d985980196ed1382587e9995fd5c614b925bab46f3159dec9f
+  metadata.gz: 3761c68a9b82be223d3c78f5e201347c9554165eceb42e3c00b2191c5cd7f6a128f5fd251ff5bd26328118d962f136d10ca552acfa5ee49a5819035910c27c9b
+  data.tar.gz: 21fc2e32708b3bb8c8ed8d14b83535d5f51d17d78abe6eec14138283e23b17059b3b2c76799cebd019e9f6578f0057cb8dfa4cd49aaa8aabddbdc859ea7af852

data/CHANGELOG.md

@@ -3,3 +3,11 @@
 ## [0.1.0] - 2025-08-12
 
 - Initial release
+
+## [0.4.8] - 2025-09-08
+
+- New DSL
+- State management
+- Reactions
+- Actions
+- Plugin system

data/README.md

@@ -1,214 +1,145 @@
 # 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.
+**Tailmix** is a powerful, declarative engine for managing HTML attributes in Ruby UI components. It allows you to co-locate all presentational logic—including CSS classes, data attributes, and ARIA roles—directly within your component's code, creating truly self-contained and maintainable components.
 
-[![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)
+[](https://badge.fury.io/rb/tailmix)
+[](https://github.com/alexander-s-f/tailmix/actions/workflows/main.yml)
 
 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
+## Key Features
+
+* **Declarative DSL:** Describe your component's styles with an elegant and intuitive API.
+* **Variants & Compound Variants:** Easily manage different component states (`size`, `color`, etc.) and their combinations.
+* **Component Inheritance:** Create base components and extend them to avoid code duplication.
+* **Zero Dependencies:** Pure Ruby, ready to work in any project.
 
-* **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 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 the gem to your Gemfile:
 
-```ruby
-gem 'tailmix'
-````
-
-Or install it from the command line:
-
 ```bash
 bundle add tailmix
 ```
 
-Next, run the installer to set up the JavaScript assets:
+Then, run the installer to set up the JavaScript assets (required for `action` and `Stimulus` integration):
 
 ```bash
 bin/rails g tailmix:install
 ```
 
-## Core Concepts
+-----
 
-You define your component's appearance using a simple `tailmix do ... end` DSL inside your class.
+## Usage
 
-- `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.
+The core idea of Tailmix is to describe all variants of your component within a Ruby class.
 
-## Usage Example
+### 1. Basic Example: The `Modal` Component
 
-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.
+**Component Definition:**
 
 ```ruby
+# app/components/modal_component.rb
 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: false do
-        variant true, "visible opacity-100"
+    plugin :auto_focus, on: :open_button, delay: 100
+    state :open, default: false, toggle: true
+
+    element :container do
+    end
+
+    element :open_button do
+      # We attach the `click` event to our auto-generated action.
+      on :click, :toggle_open
+    end
+
+    element :base do
+      dimension :open do
+        variant true, "fixed inset-0 z-50 flex items-center justify-center visible opacity-100 transition-opacity"
         variant false, "invisible opacity-0"
       end
-      stimulus.controller("modal")
     end
 
-    element :overlay, "fixed inset-0 bg-black/50 transition-opacity" do
-      stimulus.context("modal").action(click: :close)
+    element :overlay do
+      dimension :open do
+        variant true, "fixed inset-0 bg-black/50"
+        variant false, "hidden"
+      end
+      on :click, :toggle_open
     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"
+      dimension :open do
+        variant true, "block"
+        variant false, "hidden"
       end
     end
 
-    element :close_button, "absolute top-2 right-2 p-1 text-gray-400" do
-      stimulus.context("modal").action(click: :close)
+    element :close_button, "absolute top-2 right-2 p-1 text-gray-500 rounded-full cursor-pointer" do
+      on :click, :toggle_open
     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
+    element :title, "text-lg font-semibold text-gray-900 p-4 border-b"
+    element :body, "p-4 text-gray-900"
   end
 
-  def initialize(open: false, size: :md)
-    @ui = tailmix(open: open, size: size)
+  def initialize(open: false, id: nil)
+    @ui = tailmix(open: open, id: id)
   end
 end
 ```
 
-#### 2. Use in a View (Arbre, ERB, etc.)
-
-Thanks to Tailmix's design, you can pass `ui` objects directly to many rendering helpers.
-
-##### Arbre
-
-The API is seamless. The `ui` object behaves like an attributes hash automatically.
-
-Ruby
-
-```ruby
-# app/views/components/my_modal.arb
-# 1. Instantiate the component with the desired variants
-modal = ModalComponent.new(open: true, size: :sm)
+**Usage in ERB:**
+In ERB, use the `**` operator to pass the attributes.
 
-# 2. Render by passing the ui objects directly to Arbre's tag helpers
-div modal.ui.base do
-  div modal.ui.overlay
+```erb
+<% ui = ModalComponent.new(open: false, id: :user_profile_modal).ui %>
 
-  div modal.ui.panel do
-    # ... your content ...
-    button modal.ui.confirm_button, "Confirm"
-  end
-end
+<div <%= tag.attributes **ui.container.component %>>
+  ...
+</div>
 ```
 
-##### ERB / Rails Tag Helpers
-
-In ERB, the idiomatic way to pass a hash-like object as attributes is with the double splat (`**`) operator.
-
-Фрагмент кода
-
-```
-<%# app/views/pages/home.html.erb %>
-<% modal = ModalComponent.new(open: true, size: :sm) %>
-
-<%= tag.div **modal.ui.base do %>
-  <%= tag.div **modal.ui.overlay %>
-
-  <%= tag.div **modal.ui.panel do %>
-    <%# ... your content ... %>
-    <%= tag.button "Confirm", **modal.ui.confirm_button %>
-  <% end %>
-<% end %>
-```
-
-#### 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 }
-
-  showPendingState(event) {
-    event.preventDefault()
-    
-    // Instantly apply UI changes from the payload
-    Tailmix.run({
-      config: this.pendingDataValue,
-      controller: this
-    });
-
-    // ... then submit the form or send an AJAX request
-  }
-}
-```
-
-## Developer Tools
-
-Tailmix comes with built-in introspection tools to improve your development experience. Access them via the `.dev` namespace on your component class.
-
-#### Component Documentation
-
-Get a cheat sheet of all available `dimensions` and `actions` right in your console.
+**Usage in Arbre:**
+Arbre was the primary inspiration for Tailmix. Integration is seamless and does not require the `**` operator.
 
 ```ruby
-puts ModalComponent.dev.docs
-```
+# _example_modal_component.arb
+modal_component = ModalComponent.new(open: false, id: :user_profile_modal)
+ui = modal_component.ui
 
-#### Stimulus Controller Generator
+button "Open Modal Outer", tailmix_trigger_for(:user_profile_modal, :toggle_open)
 
-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")
-```
+div ui.container.component do
+  button "Open Modal", ui.open_button
 
-## Configuration
+  div ui.base do
+    div ui.overlay
 
-You can configure Tailmix by creating an initializer:
+    div ui.panel do
+      div ui.title do
+        h3 "Modal Title"
+        button ui.close_button do
+          text_node "✖"
+        end
+      end
 
-```ruby
-# config/initializers/tailmix.rb
-Tailmix.configure do |config|
-  # The attribute used by the universal JS selector.
-  config.element_selector_attribute = "data-tm-el"
+      div ui.body do
+        para "This is the main content of the modal. It's powered by the new Tailmix Runtime!"
+      end
+    end
+  end
 end
 ```
 
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/alexander-s-f/tailmix](https://github.com/alexander-s-f/tailmix).
+Bug reports and pull requests are welcome on GitHub.
 
 ## License
 

data/app/javascript/tailmix/runtime/action_dispatcher.js

@@ -0,0 +1,132 @@
+export class ActionDispatcher {
+
+    /**
+     * Creates an instance of ActionDispatcher.
+     * @param {Component} component - The component instance to which the dispatcher is attached.
+     */
+    constructor(component) {
+        this.component = component;
+        const internalActionElements = this.component.element.querySelectorAll('[data-tailmix-action]');
+        internalActionElements.forEach(element => this.bindAction(element));
+    }
+
+    /**
+     * Binds an action to a specific element based on its data-tailmix-action attribute.
+     * The attribute value should be in the format "eventName->actionName".
+     * @param {HTMLElement} element - The element to which the action is bound.
+     * @return {void}
+     */
+    bindAction(element) {
+        const actionString = element.dataset.tailmixAction;
+        const [eventName, actionName] = actionString.split('->');
+
+        if (!eventName || !actionName) {
+            console.warn(`Tailmix: Invalid action string "${actionString}"`);
+            return;
+        }
+
+        const actionDefinition = this.component.definition.actions[actionName];
+        if (!actionDefinition) {
+            console.warn(`Tailmix: Action "${actionName}" not found in definition.`);
+            return;
+        }
+
+        element.addEventListener(eventName, (event) => {
+            // Let's make sure the trigger is not part of another component.
+            if (element.dataset.tailmixTriggerFor && element.closest('[data-tailmix-component]') !== this.component.element) {
+                // Logic to prevent double triggering, if needed
+            }
+            this.dispatch(actionDefinition, event, element);
+        });
+    }
+
+    /**
+     * Dispatches an action based on the provided action definition and event input.
+     * Processes each transition within the action definition and performs state updates
+     * or other specified operations on the component.
+     * @param {Object} actionDefinition - The definition of the action containing transitions to be processed.
+     * @param {Object} event - The event triggering the dispatch, providing context for the action.
+     * @param {HTMLElement} triggerElement - The element that triggered the action.
+     * @return {void}
+     */
+    dispatch(actionDefinition, event, triggerElement) {
+        let runtimePayload = {};
+        const withMapAttr = triggerElement.dataset.tailmixActionWith;
+        if (withMapAttr) {
+            const withMap = JSON.parse(withMapAttr);
+            for (const key in withMap) {
+                runtimePayload[key] = this.component.state[withMap[key]];
+            }
+        }
+
+        actionDefinition.transitions.forEach(transition => {
+            this.executeTransition(transition, runtimePayload, event);
+        });
+    }
+
+    /**
+     * Executes a transition within an action definition.
+     * This method handles different transition types and applies updates to the component's state.'
+     * @param transition
+     * @param runtimePayload
+     * @param event
+     */
+    executeTransition(transition, runtimePayload, event) {
+        const {type, payload} = transition;
+        switch (type) {
+            case 'set':
+                const resolvedValue = this.resolveValue(payload.value, runtimePayload, event);
+                this.component.update({[payload.key]: resolvedValue});
+                break;
+            case 'toggle':
+                this.component.update({[payload.key]: !this.component.state[payload.key]});
+                break;
+            case 'refresh':
+                this.handleRefresh(payload, runtimePayload);
+                break;
+            case 'dispatch':
+                const detail = this.resolveValue(payload.detail, runtimePayload, event);
+                this.component.dispatch(payload.name, detail);
+                break;
+        }
+    }
+
+    /**
+     * Handles the refresh transition by fetching data from an endpoint based on the provided payload.
+     * @param {Object} payload - The payload containing the refresh configuration.
+     * @param {Object} runtimePayload - The runtime payload containing values to be used in the endpoint URL.
+     * @return {void}
+     */
+    handleRefresh(payload, runtimePayload) {
+        const stateDef = this.component.definition.states[payload.key];
+        if (!stateDef?.endpoint) {
+            console.warn(`Tailmix: No endpoint defined for state "${payload.key}"`);
+            return;
+        }
+
+        const params = new URLSearchParams();
+        if (payload.params) {
+            for (const key in payload.params) {
+                const stateKey = payload.params[key];
+                params.append(key, this.component.state[stateKey]);
+            }
+        }
+
+        const url = `${stateDef.endpoint.url}?${params.toString()}`;
+
+        // fetch(url, { headers: { 'Accept': 'text/vnd.turbo-stream.html' } })
+        //   .then(r => r.text())
+        //   .then(html => Turbo.renderStreamMessage(html));
+        console.log(`TODO: Fetch data for "${payload.key}" from ${url}`);
+    }
+
+    resolveValue(valueTemplate, runtimePayload, event) {
+        if (valueTemplate && valueTemplate.__type === 'payload_value') {
+            const keyPath = valueTemplate.key.split('.'); // e.g., "event.target.value"
+            let result = {event, ...runtimePayload};
+            keyPath.forEach(key => result = result?.[key]);
+            return result;
+        }
+        return valueTemplate;
+    }
+}

data/app/javascript/tailmix/runtime/component.js

@@ -0,0 +1,130 @@
+import {ActionDispatcher} from './action_dispatcher';
+import {Updater} from './updater';
+
+/**
+ * Represents a component instance that manages the state and behavior of a specific UI element.
+ * The Component class is responsible for loading and initializing the component's state,
+ * finding and managing its elements, and updating the UI based on the component's state.
+ */
+export class Component {
+    constructor(element, definition, pluginManager) {
+        this.element = element;
+        this.definition = definition;
+        this._state = this.loadInitialState();
+        this.elements = this.findElements();
+        this.updater = new Updater(this);
+        this.dispatcher = new ActionDispatcher(this);
+
+        // --- API ---
+        this.api = {
+            get state() {
+                return {...this._state};
+            },
+            setState: (newState) => this.update(newState),
+            element: (name) => this.elements[name],
+            runAction: (name, payload) => this.dispatcher.runActionByName(name, payload),
+            dispatch: (name, detail) => this.dispatch(name, detail),
+            on: (name, callback) => this.element.addEventListener(`tailmix:${name}`, callback),
+        };
+
+        this.initializeModels();
+        this.updater.run(this._state, {});
+        pluginManager.connect(this);
+
+        console.log(`Tailmix component "${this.definition.name || 'Unnamed'}" initialized.`, this);
+    }
+
+    /**
+     * Gets the current state of the component.
+     * @return {Object} The current state of the component.
+     */
+    get state() {
+        return this._state;
+    }
+
+    /**
+     * Updates the component's state with the provided new state and triggers the update mechanism.
+     * The previous state is logged for debugging purposes.
+     '
+     * @param newState
+     */
+    update(newState) {
+        const oldState = {...this._state};
+        Object.assign(this._state, newState);
+        this.element.dataset.tailmixState = JSON.stringify(this._state);
+        this.updater.run(this._state, oldState);
+    }
+
+    /**
+     * Dispatches a custom event with the specified name and detail.
+     * @param {string} name - The name of the event to be dispatched.
+     * @param {any} detail - The detail object to be attached to the event.
+     */
+    dispatch(name, detail) {
+        const event = new CustomEvent(`tailmix:${name}`, {bubbles: true, detail});
+        this.element.dispatchEvent(event);
+    }
+
+    /**
+     * Loads and parses the initial state from the data attribute.
+     * @return {Object} The parsed initial state.
+     */
+    loadInitialState() {
+        const initialState = JSON.parse(this.element.dataset.tailmixState || '{}');
+        const stateSchema = this.definition.states || {};
+
+        for (const key in stateSchema) {
+            if (initialState[key] === undefined && stateSchema[key].default !== undefined) {
+                initialState[key] = stateSchema[key].default;
+            }
+        }
+        return initialState;
+    }
+
+    /**
+     * Finds and retrieves all elements with a specific data attribute (`data-tailmix-element`)
+     * within the current root element, and maps their associated names to the DOM nodes.
+     * The root element itself is included if it also has the attribute with a defined name.
+     *
+     * @return {Object} An object where the keys are the names specified in the `data-tailmix-element`
+     *                  attribute, and the values are the corresponding DOM nodes.
+     */
+    findElements() {
+        const elements = {};
+        const elementNodes = this.element.querySelectorAll('[data-tailmix-element]');
+        elementNodes.forEach(node => {
+            const name = node.dataset.tailmixElement;
+            elements[name] = node;
+        });
+        // We also add the root element itself, if it has a name.
+        if (this.element.dataset.tailmixElement) {
+            elements[this.element.dataset.tailmixElement] = this.element;
+        }
+        return elements;
+    }
+
+    /**
+     * Initializes models by binding event listeners to elements and updating state accordingly.
+     * This method iterates through the component's elements and model bindings,
+     * and sets up event listeners for each attribute that needs to be updated.
+     *
+     * @return {void} This method does not return a value.
+     */
+    initializeModels() {
+        for (const elName in this.definition.elements) {
+            const element = this.elements[elName];
+            const modelBindings = this.definition.elements[elName].model_bindings;
+            if (!element || !modelBindings) continue;
+
+            for (const attrName in modelBindings) {
+                const binding = modelBindings[attrName];
+                element.addEventListener(binding.event, (event) => {
+                    this.update({[binding.state]: event.target[attrName]});
+                    if (binding.action) {
+                        // It is possible to add action execution after model update.
+                    }
+                });
+            }
+        }
+    }
+}