tailmix 0.4.7 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 972f0dcd1667c6db95fbce07209fdf7ab3568b335fd0dab933977a641114dc6a
-  data.tar.gz: 3063e23f5422ec1fe5f20683263a6b7cfce4f9c054d393e520f962a0727d4992
+  metadata.gz: 25625758329e8524ce4fa37154be93d929b43ce85dfc5bb5669e8646b82ebd88
+  data.tar.gz: 1a98f9b38e7799819579309691e6692ec94ac5cf1358159c6c6431cc1d16c920
 SHA512:
-  metadata.gz: fb3cfcfef0f342f12dc680a18e7a7d20b278b08699f28b09b473f8843747d147cd9a1ae56db112a86ce4c52881b609ecd6a9fe863fcdd43c9b63ff0ccc3f50cc
-  data.tar.gz: 75366e305721e6091324578ff4138f10b1d0ed70135d0094f901bb52f58580465f528731b498e23f2f61e26369dd4ad5d34425d28da81e26996c138c1d2872b9
+  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

@@ -11,22 +11,9 @@ Inspired by modern frontend tools like CVA (Class Variance Authority), Tailmix b
 
 * **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.
-* **Stimulus Bridge:** Seamlessly integrate with StimulusJS to create interactive components.
-* **"Hot" UI Updates:** Enable optimistic UI updates with `action` and `action_payload` in tandem with Hotwire/Turbo.
 * **Component Inheritance:** Create base components and extend them to avoid code duplication.
-* **Developer Tools:** Get built-in documentation and code generators right in your console.
 * **Zero Dependencies:** Pure Ruby, ready to work in any project.
 
------
-
-## Quick Links
-
-* **[Full Documentation →](/docs)**
-* **[DSL Reference](/docs/02_dsl_reference.md)**
-* **[Cookbook (Recipes)](/docs/05_cookbook.md)**
-
-
------
 
 ## Installation
 
@@ -48,120 +35,10 @@ bin/rails g tailmix:install
 
 The core idea of Tailmix is to describe all variants of your component within a Ruby class.
 
-### 1. Basic Example: The `Badge` Component
-
-Let's create a simple, flexible `Badge` that can have different colors.
-
-**Component Definition:**
-
-```ruby
-# app/components/badge_component.rb
-class BadgeComponent
-  include Tailmix
-  attr_reader :ui, :text
-
-  def initialize(text, color: :gray)
-    @ui = tailmix(color: color)
-    @text = text
-  end
-
-  tailmix do
-    element :badge, "inline-flex items-center px-2.5 py-0.5 text-xs font-medium rounded-full" do
-      dimension :color, default: :gray do
-        variant :gray,    "bg-gray-100 text-gray-800"
-        variant :success, "bg-green-100 text-green-800"
-        variant :danger,  "bg-red-100 text-red-800"
-      end
-    end
-  end
-end
-```
-
-**Usage in ERB:**
-In ERB, use the `**` operator to pass the attributes.
-
-```erb
-<% badge = BadgeComponent.new("Active", color: :success) %>
-
-<span <%= tag.attributes **badge.ui.badge %>>
-  <%= badge.text %>
-</span>
-```
-
-**Usage in Arbre:**
-Arbre was the primary inspiration for Tailmix. Integration is seamless and does not require the `**` operator.
-
-```ruby
-# my_view.arb
-badge = BadgeComponent.new("Active", color: :success)
-ui = badge.ui
-
-span ui.badge do
-  text_node badge.text
-end
-```
-
-### 2\. Adding Interactivity with Stimulus
-
-Tailmix allows you to declaratively define Stimulus controllers. Let's build a component to copy text to the clipboard.
+### 1. Basic Example: The `Modal` Component
 
 **Component Definition:**
 
-```ruby
-# app/components/clipboard_component.rb
-class ClipboardComponent
-  include Tailmix
-  attr_reader :ui, :text_to_copy
-
-  def initialize(text_to_copy)
-    @ui = tailmix
-    @text_to_copy = text_to_copy
-  end
-
-  tailmix do
-    element :wrapper, "flex items-center space-x-2" do
-      stimulus.controller("clipboard") # data-controller="clipboard"
-    end
-
-    element :source, "p-2 border rounded-md bg-gray-50" do
-      stimulus.context("clipboard").target("source") # data-clipboard-target="source"
-    end
-
-    element :button, "px-3 py-2 text-sm font-medium text-white bg-blue-600 rounded-md" do
-      stimulus.context("clipboard").action(:click, :copy) # data-action="click->clipboard#copy"
-    end
-  end
-end
-```
-
-**Stimulus Controller:**
-Generate a template with `puts ClipboardComponent.dev.stimulus.scaffold` and fill in the logic.
-
-```javascript
-// app/javascript/controllers/clipboard_controller.js
-import { Controller } from "@hotwired/stimulus"
-
-export default class extends Controller {
-  static targets = ["source"]
-
-  copy() {
-    navigator.clipboard.writeText(this.sourceTarget.textContent)
-    // Optionally: show a success notification
-  }
-}
-```
-
-Your component is now fully interactive, with its entire structure defined in a single Ruby file.
-
------
-
-## 3. Advanced Example: An Interactive Modal
-
-Now let's see the full power of Tailmix by building a common UI pattern: a fully interactive modal component. This example combines multiple elements, shared variants, Stimulus integration, and a client-side action for optimistic updates.
-
-Component Definition:
-The `ModalComponent` definition is self-contained. It describes the structure, all possible states, and the interactive behavior of the modal.
-
 ```ruby
 # app/components/modal_component.rb
 class ModalComponent
@@ -169,132 +46,96 @@ class ModalComponent
   attr_reader :ui
 
   tailmix do
-    # A container to hold the controller and its data
+    plugin :auto_focus, on: :open_button, delay: 100
+    state :open, default: false, toggle: true
+
     element :container do
-      stimulus.controller("modal")
-              .action_payload(:toggle, as: :toggle_data)
-              # dynamic values:
-              .value(:user_id, method: :get_current_user_id)
-              .value(:generated_at, call: -> { Time.now.iso8601 })
     end
 
-    # The button that will trigger the modal
-    element :open_button, "inline-flex text-white bg-blue-600 rounded-lg px-5 py-2.5 cursor-pointer" do
-      stimulus.context("modal").action(:click, :toggle)
+    element :open_button do
+      # We attach the `click` event to our auto-generated action.
+      on :click, :toggle_open
     end
 
-    # The modal's backdrop and wrapper, controlled by the :open dimension
-    element :base, "flex items-center justify-center" do
-      dimension :open, default: false do
-        variant true, "fixed inset-0 z-50 visible opacity-100 transition-opacity"
+    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
     end
 
-    element :overlay, "fixed inset-0 bg-black/50" do
-      stimulus.context("modal").action(:click, :toggle)
+    element :overlay do
+      dimension :open do
+        variant true, "fixed inset-0 bg-black/50"
+        variant false, "hidden"
+      end
+      on :click, :toggle_open
     end
 
-    # The main modal panel, with variants for both :open and :size
-    element :panel, "w-full relative bg-white rounded-lg shadow-xl" do
-      dimension :open, default: false do
+    element :panel, "relative bg-white rounded-lg shadow-xl" do
+      dimension :open do
         variant true, "block"
         variant false, "hidden"
       end
-      dimension :size, default: :md do
-        variant :sm, "max-w-sm p-4"
-        variant :md, "max-w-md p-6"
-      end
-      stimulus.context("modal").target("panel")
     end
 
     element :close_button, "absolute top-2 right-2 p-1 text-gray-500 rounded-full cursor-pointer" do
-      stimulus.context("modal").action(:click, :toggle)
+      on :click, :toggle_open
     end
 
-    # The action that will be executed on the client-side
-    action :toggle, method: :toggle do
-      element :base do
-        classes "visible opacity-100"
-        classes "invisible opacity-0"
-      end
-      element :overlay do
-        classes "fixed inset-0 bg-black/50"
-      end
-      element :panel do
-        classes "block"
-        classes "hidden"
-      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(size: :md, open: false)
-    @ui = tailmix(size: size, open: open)
-  end
-
-  def get_current_user_id
-    123
+  def initialize(open: false, id: nil)
+    @ui = tailmix(open: open, id: id)
   end
 end
 ```
 
-**Stimulus Controller:**
-This controller will handle the modal's open/close logic and use the `action_payload` to trigger the closing animation defined in Ruby.
-
-```javascript
-// app/javascript/controllers/modal_controller.js
-import { Controller } from "@hotwired/stimulus"
-import Tailmix from "tailmix"
-
-export default class extends Controller {
-    static values = { toggleData: Object }
+**Usage in ERB:**
+In ERB, use the `**` operator to pass the attributes.
 
-    toggle(event) {
-        // Prevent default browser behavior, like form submissions
-        if (event) event.preventDefault();
+```erb
+<% ui = ModalComponent.new(open: false, id: :user_profile_modal).ui %>
 
-        // Run the UI mutations defined in our Ruby :toggle action
-        Tailmix.run({
-            config: this.toggleDataValue,
-            controller: this
-        });
-    }
-}
+<div <%= tag.attributes **ui.container.component %>>
+  ...
+</div>
 ```
 
-**View Usage (Arbre):**
-The view code is clean and readable. We instantiate the component and render its elements. The action_payload is serialized to the container element, making it available to the Stimulus controller.
+**Usage in Arbre:**
+Arbre was the primary inspiration for Tailmix. Integration is seamless and does not require the `**` operator.
 
 ```ruby
-# my_view.arb
-modal = ModalComponent.new(size: :sm)
-ui = modal.ui
+# _example_modal_component.arb
+modal_component = ModalComponent.new(open: false, id: :user_profile_modal)
+ui = modal_component.ui
+
+button "Open Modal Outer", tailmix_trigger_for(:user_profile_modal, :toggle_open)
 
-div ui.container do
+div ui.container.component do
   button "Open Modal", ui.open_button
 
   div ui.base do
     div ui.overlay
+
     div ui.panel do
-      button "Close", ui.close_button
-      h3 "Payment Successful", ui.title
+      div ui.title do
+        h3 "Modal Title"
+        button ui.close_button do
+          text_node "✖"
+        end
+      end
 
       div ui.body do
-        "Your payment has been successfully submitted..."
+        para "This is the main content of the modal. It's powered by the new Tailmix Runtime!"
       end
     end
   end
 end
 ```
 
------
-
-## Developer Tools
-
-Use the `.dev` namespace to introspect your components right from the console.
-
-* **`YourComponent.dev.docs`**: Displays full documentation for all variants and actions.
-* **`YourComponent.dev.stimulus.scaffold`**: Generates a Stimulus controller template.
 
 ## Contributing
 

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.
+                    }
+                });
+            }
+        }
+    }
+}