tailmix 0.4.6 → 0.4.8

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

@@ -0,0 +1,130 @@
+import {Component} from './component';
+import {PluginManager} from './plugins';
+
+/**
+ * The Tailmix global object that manages the lifecycle of components and plugins.
+ * It provides methods for starting the application, hydration of components,
+ */
+const Tailmix = {
+    _namedInstances: {},
+    _components: new Map(),
+    _definitions: {},
+    _pluginManager: new PluginManager(),
+    _observer: null,
+
+    /**
+     * Starts the Tailmix application by loading component definitions and initializing components.
+     */
+    start() {
+        this.loadDefinitions();
+        this._namedInstances = {};
+        this._components.clear();
+
+        this.hydrate(document.body);
+        this.observeChanges();
+    },
+
+    /**
+     * Hydrate components within the specified root element.
+     * @param rootElement
+     */
+    hydrate(rootElement) {
+        const componentElements = rootElement.querySelectorAll('[data-tailmix-component]');
+        componentElements.forEach(element => {
+            if (this._components.has(element)) return;
+
+            const componentName = element.dataset.tailmixComponent;
+            const definition = this._definitions[componentName];
+            if (!definition) { /* ... */
+                return;
+            }
+
+            const component = new Component(element, definition, this._pluginManager);
+            this._components.set(element, component);
+
+            const componentId = element.dataset.tailmixId;
+            if (componentId) {
+                this._namedInstances[componentId] = component;
+            }
+        });
+
+        // External trigger binding
+        const triggerElements = rootElement.querySelectorAll('[data-tailmix-trigger-for]');
+        triggerElements.forEach(element => {
+            const targetId = element.dataset.tailmixTriggerFor;
+            const targetComponent = this._namedInstances[targetId];
+            if (targetComponent) {
+                targetComponent.dispatcher.bindAction(element);
+            }
+        });
+    },
+
+    /**
+     * Loads and parses the component definitions from a script tag with the attribute `data-tailmix-definitions`.
+     * If a valid JSON content is found, it assigns it to the `definitions` variable.
+     * Logs an error message to the console in case of parsing failure.
+     *
+     * @return {void} Does not return a value.
+     */
+    loadDefinitions() {
+        const definitionsTag = document.querySelector('script[data-tailmix-definitions]');
+        if (definitionsTag) {
+            try {
+                this._definitions = JSON.parse(definitionsTag.textContent);
+            } catch (e) {
+                console.error("Tailmix: Failed to parse component definitions.", e);
+            }
+        }
+    },
+
+    /**
+     * Retrieves a component associated with the nearest ancestor element
+     * that has the `data-tailmix-component` attribute.
+     *
+     * @param {Element} element - The DOM element from which the component search begins.
+     * @return {*} The component associated with the identified ancestor element, or `undefined` if no component is found.
+     */
+    getComponent(element) {
+        const root = element.closest('[data-tailmix-component]');
+        return root ? this._components.get(root) : undefined;
+    },
+
+    registerPlugin(plugin) {
+        this._pluginManager.register(plugin);
+    },
+
+    /**
+     * Observes changes in the DOM and rehydrates components when they are added or modified.
+     */
+    observeChanges() {
+        if (this._observer) this._observer.disconnect();
+
+        this._observer = new MutationObserver(mutations => {
+            for (const mutation of mutations) {
+                if (mutation.type === 'childList') {
+                    mutation.addedNodes.forEach(node => {
+                        if (node.nodeType === Node.ELEMENT_NODE) {
+                            // If the component itself was added
+                            if (node.matches('[data-tailmix-component]')) {
+                                this.hydrate(node);
+                            }
+                            // If a parent was added, which may contain components
+                            this.hydrate(node);
+                        }
+                    });
+                }
+            }
+        });
+
+        this._observer.observe(document.body, {childList: true, subtree: true});
+    }
+};
+
+// Initialize Tailmix on page load
+document.addEventListener("turbo:load", () => {
+    console.log("Tailmix starting...");
+    Tailmix.start();
+});
+
+
+export default Tailmix;

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

@@ -0,0 +1,35 @@
+class PluginManager {
+    constructor() {
+        this.plugins = [];
+    }
+
+    /**
+     * Registers a plugin with the plugin manager.
+     * @param plugin
+     */
+    register(plugin) {
+        if (!plugin.name) {
+            console.error("Tailmix Plugin Error: a plugin must have a name.", plugin);
+            return;
+        }
+        this.plugins.push(plugin);
+    }
+
+    /**
+     * Connects a component to all registered plugins.
+     * @param component
+     */
+    connect(component) {
+        this.plugins.forEach(plugin => {
+            if (typeof plugin.connect === 'function') {
+                const pluginConfig = component.definition.plugins?.[plugin.name];
+                if (pluginConfig) {
+                    plugin.connect(component.api, pluginConfig);
+                }
+            }
+        });
+    }
+}
+
+export {PluginManager};
+

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

@@ -0,0 +1,140 @@
+export class Updater {
+    constructor(component) {
+        this.component = component;
+        this.definition = component.definition;
+    }
+
+    run(newState, oldState) {
+        for (const elementName in this.definition.elements) {
+            const elementNode = this.component.elements[elementName];
+            const elementDef = this.definition.elements[elementName];
+
+            if (!elementNode || !elementDef) continue;
+
+            this.updateElement(elementNode, elementDef, newState, oldState);
+        }
+    }
+
+    updateElement(elementNode, elementDef, newState, oldState) {
+        this.updateClasses(elementNode, elementDef, newState);
+        this.updateAttributes(elementNode, elementDef, newState);
+        this.updateContent(elementNode, elementDef, newState);
+    }
+
+    updateClasses(elementNode, elementDef, newState) {
+        const targetClasses = this.calculateTargetClasses(elementDef, newState);
+        const currentClasses = new Set(elementNode.classList);
+
+        // We compare current classes with target classes and apply the difference.
+        targetClasses.forEach(cls => {
+            if (!currentClasses.has(cls)) {
+                elementNode.classList.add(cls);
+            }
+        });
+
+        currentClasses.forEach(cls => {
+            if (!targetClasses.has(cls)) {
+                // We avoid removing base classes that were originally in HTML.
+                // (This is a simple heuristic; it can be improved if base classes are in the definition)
+                const isBaseClass = !this.isVariantClass(elementDef, cls);
+                if (!targetClasses.has(cls) && !isBaseClass) {
+                    elementNode.classList.remove(cls);
+                }
+            }
+        });
+    }
+
+    updateAttributes(elementNode, elementDef, newState) {
+        if (elementDef.attribute_bindings) {
+            for (const attrName in elementDef.attribute_bindings) {
+                if (["text", "html"].includes(attrName)) continue;
+
+                const stateKey = elementDef.attribute_bindings[attrName];
+                const newValue = newState[stateKey];
+
+                // We update the attribute only if it has changed.
+                if (elementNode.getAttribute(attrName) !== newValue) {
+                    if (newValue === null || newValue === undefined) {
+                        elementNode.removeAttribute(attrName);
+                    } else {
+                        elementNode.setAttribute(attrName, newValue);
+                    }
+                }
+            }
+        }
+    }
+
+    updateContent(elementNode, elementDef, newState) {
+        const bindings = elementDef.attribute_bindings;
+        if (!bindings) return;
+
+        // Обработка `bind :text`
+        const textStateKey = bindings.text;
+        if (textStateKey !== undefined) {
+            const newText = newState[textStateKey] || '';
+            if (elementNode.textContent !== newText) {
+                elementNode.textContent = newText;
+            }
+        }
+
+        // Обработка `bind :html`
+        const htmlStateKey = bindings.html;
+        if (htmlStateKey !== undefined) {
+            const newHtml = newState[htmlStateKey] || '';
+            if (elementNode.innerHTML !== newHtml) {
+                elementNode.innerHTML = newHtml;
+            }
+        }
+    }
+
+    calculateTargetClasses(elementDef, state) {
+        const classes = new Set();
+
+        // 1. We add base classes (if any are in the definition).
+        // (We skip this for now, as they are already in the HTML)
+
+        // 2. We apply classes from active variants (dimensions).
+        if (elementDef.dimensions) {
+            for (const dimName in elementDef.dimensions) {
+                const dimDef = elementDef.dimensions[dimName];
+                const stateValue = state[dimName] !== undefined ? state[dimName] : dimDef.default;
+
+                const variantDef = dimDef.variants?.[stateValue];
+                if (variantDef?.classes) {
+                    variantDef.classes.forEach(cls => classes.add(cls));
+                }
+            }
+        }
+
+        // 3. We apply classes from active compound variants.
+        if (elementDef.compound_variants) {
+            elementDef.compound_variants.forEach(cv => {
+                const conditions = cv.on;
+                const modifications = cv.modifications;
+
+                const isMatch = Object.entries(conditions).every(([key, value]) => {
+                    return state[key] === value;
+                });
+
+                if (isMatch && modifications.classes) {
+                    modifications.classes.forEach(cls => classes.add(cls));
+                }
+            });
+        }
+
+        return classes;
+    }
+
+    isVariantClass(elementDef, className) {
+        if (elementDef.dimensions) {
+            for (const dimName in elementDef.dimensions) {
+                const dim = elementDef.dimensions[dimName];
+                for (const variantName in dim.variants) {
+                    if (dim.variants[variantName].classes?.includes(className)) return true;
+                }
+            }
+        }
+        // ... a check can also be added for compound_variants
+        return false;
+    }
+}

data/docs/01_getting_started.md

@@ -0,0 +1,39 @@
+# Getting Started with Tailmix
+
+Welcome to Tailmix! This guide will walk you through installing the gem, setting up your project, and creating your first component.
+
+## Philosophy
+
+Tailmix is built on the idea of **co-location**. Instead of defining component styles in separate CSS, SCSS, or CSS-in-JS files, you define them directly within the Ruby class that represents your component. This creates self-contained, highly reusable, and easily maintainable UI components.
+
+The core of Tailmix is a powerful and expressive **DSL (Domain-Specific Language)** that allows you to declaratively define how a component should look based on its properties or "variants".
+
+## Installation
+
+Getting started with Tailmix involves two simple steps: adding the gem and installing the JavaScript bridge.
+
+### 1. Add the Gem
+
+Add `tailmix` to your application's Gemfile:
+
+```bash
+bundle add tailmix
+```
+
+### 2. Install JavaScript Assets
+
+Run the installer to set up the necessary JavaScript files for the client-side bridge (used by actions).
+
+```bash
+bin/rails g tailmix:install
+```
+
+This command will add tailmix to your importmap.rb and ensure its JavaScript is available in your application.
+
+### Your First Component: A Badge
+Let's create a simple BadgeComponent to see Tailmix in action.
+
+#### 1. Define the Component Class
+
+
+

data/examples/_modal_component.arb

@@ -1,36 +1,28 @@
 # Arbre view:
 
-modal = SuperModalComponent.new(size: :lg, open: true)
+modal_component = ModalComponent.new(open: false, id: :user_profile_modal)
+ui = modal_component.ui
 
-# modal.lock!
-ui = modal.ui
+button "Open Modal Outer", tailmix_trigger_for(:user_profile_modal, :toggle_open)
 
-div ui.base do
-  div ui.overlay
-  div ui.open do
-    "open"
-  end
+div ui.container.component do
+  button "Open Modal", ui.open_button
 
-  div ui.panel do
-    button ui.close_button do
-      span "Close"
-    end
+  div ui.base do
+    div ui.overlay
 
-    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..."
+    div ui.panel do
+      div ui.title do
+        h3 "Modal Title"
+        button ui.close_button do
+          text_node "✖"
         end
       end
+
+      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
+

data/examples/button.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../lib/tailmix"
+require_relative "helpers"
+
+class Button
+  include Tailmix
+
+  tailmix do
+    element :button do
+      dimension :intent, default: :primary do
+        variant :primary, "bg-blue-500"
+        variant :danger, "bg-red-500"
+      end
+
+      dimension :size, default: :medium do
+        variant :medium, "p-4"
+        variant :small, "p-2"
+      end
+
+      compound_variant on: { intent: :danger, size: :small } do
+        classes "font-bold"
+        data special: "true"
+      end
+    end
+  end
+
+  attr_reader :ui
+  def initialize(intent: :primary, size: :medium)
+    @ui = tailmix(intent: intent, size: size)
+  end
+end
+
+
+puts "-" * 100
+puts Button.dev.docs
+
+# == Tailmix Docs for Button ==
+# Signature: `initialize(intent: :primary, size: :medium)`
+#
+# Dimensions:
+#   - intent (default: :primary)
+#     - :primary:
+#       - classes : "bg-blue-500"
+#     - :danger:
+#       - classes : "bg-red-500"
+#   - size (default: :medium)
+#     - :medium:
+#       - classes : "p-4"
+#     - :small:
+#       - classes : "p-2"
+#
+# Compound Variants:
+#   - on element `:button`:
+#     - on: { intent: :danger, size: :small }
+#       - classes : "font-bold"
+#       - data: {:special=>"true"}
+#
+# No actions defined.
+#
+# button
+#     classes :-> bg-red-500 p-4
+#     data :-> {}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:medium"}
+
+not_compound_component = Button.new(intent: :danger, size: :medium)
+print_component_ui(not_compound_component)
+# button
+#     classes :-> bg-red-500 p-4
+#     data :-> {}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:medium"}
+
+compound_component = Button.new(intent: :danger, size: :small)
+print_component_ui(compound_component)
+# button
+#     classes :-> bg-red-500 p-2 font-bold
+#     data :-> {"data-special"=>"true"}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:small"}

data/examples/helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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
+
+def print_component_ui(component_instance)
+  component_instance.class.dev.elements.each do |element_name|
+    element = component_instance.ui.send(element_name)
+    puts element_name
+    element.each_attribute do |attribute|
+      attribute.each do |key, value|
+        puts "    #{key} :-> #{value}"
+      end
+      puts ""
+    end
+  end
+end