tailmix 0.4.5 → 0.4.7

data/docs/02_dsl_reference.md

@@ -0,0 +1,266 @@
+
+# DSL Reference
+
+The Tailmix DSL is designed to be declarative, expressive, and intuitive. All definitions are placed within a `tailmix do ... end` block inside your component class.
+
+## `element`
+
+The `element` method is the top-level keyword used to define a logical part or section of your component.
+
+### Syntax
+
+```ruby
+element :name, "optional base classes" do
+  # ... further definitions for this element
+end
+```
+
+* **`:name` (Symbol)**: A unique name for the element, like `:wrapper`, `:title`, or `:close_button`. This name is used to access the element's attributes from the `ui` object (e.g., `ui.wrapper`).
+* **`"base classes"` (String, optional)**: A space-separated string of CSS classes that will always be applied to this element, regardless of any variants.
+* **`do ... end` block**: This is where you define the element's variants using `dimension`.
+
+### Example
+
+```ruby
+tailmix do
+  # An element with no base classes
+  element :wrapper do
+    # ...
+  end
+
+  # An element with base classes
+  element :title, "text-lg font-bold text-gray-900"
+end
+```
+
+-----
+
+## `dimension`
+
+A `dimension` defines an axis of variation for an element. It represents a property of the component that can change and affect its styling, such as `size`, `color`, or `state`. It must be defined inside an `element` block.
+
+### Syntax
+
+```ruby
+dimension :name, default: :value do
+  # ... variant definitions
+end
+```
+
+* **`:name` (Symbol)**: The name of the dimension, like `:size` or `:intent`.
+* **`default: :value` (optional)**: The default value for this dimension if none is provided when the component is initialized.
+
+### Example
+
+```ruby
+element :button, "rounded-lg" do
+  dimension :size, default: :md do
+    # ... variants for :sm, :md, :lg
+  end
+
+  dimension :intent, default: :primary do
+    # ... variants for :primary, :secondary, :danger
+  end
+end
+```
+
+-----
+
+## `variant`
+
+The `variant` method defines the specific styles that should be applied when a `dimension` has a certain value. It must be defined inside a `dimension` block.
+
+### Syntax
+
+There are two forms for defining a variant:
+
+**1. Simple (inline classes)**
+
+```ruby
+variant :name, "classes to apply"
+```
+
+**2. Advanced (with a block)**
+
+```ruby
+variant :name, "optional base classes for this variant" do
+  classes "...", group: :optional_label
+  data key: "value"
+  aria key: "value"
+end
+```
+
+* **`:name` (Symbol|Boolean|String)**: The value of the dimension this variant corresponds to (e.g., `:md`, `true`).
+* **`"classes"` (String)**: A space-separated string of CSS classes.
+* **`do ... end` block**: For more complex definitions:
+    * **`classes`**: Can be called multiple times to logically group classes. The optional `group:` option is for documentation purposes.
+    * **`data`**: A hash to define `data-*` attributes.
+    * **`aria`**: A hash to define `aria-*` attributes for accessibility.
+
+### Example
+
+```ruby
+dimension :size, default: :md do
+  # Simple variant
+  variant :sm, "px-2 py-1 text-sm"
+
+  # Advanced variant with a block
+  variant :md, "px-4 py-2" do
+    classes "text-base font-semibold", group: :typography
+    data size: "medium"
+    aria pressed: "false"
+  end
+end
+```
+
+-----
+
+## `compound_variant`
+
+A `compound_variant` allows you to define styles that apply only when a specific **combination** of dimensions is active. This is crucial for handling interdependencies in a design system. It must be defined inside an `element` block.
+
+### Syntax
+
+```ruby
+compound_variant on: { dimension1: :value, dimension2: :value } do
+  # ... modifications (classes, data, aria)
+end
+```
+
+* **`on: { ... }` (Hash)**: A hash specifying the exact conditions under which this rule should be applied.
+* **`do ... end` block**: The modifications to apply. It uses the same `classes`, `data`, and `aria` methods as the `variant` block.
+
+### Example
+
+This example makes an "outline" button's text and border color match its intent.
+
+```ruby
+element :button do
+  dimension :intent, default: :primary do
+    variant :primary, "bg-blue-500 text-white border-blue-500"
+    variant :danger, "bg-red-500 text-white border-red-500"
+  end
+
+  dimension :look, default: :fill do
+    variant :outline, "bg-transparent"
+  end
+
+  # Apply these classes ONLY when look is :outline AND intent is :primary
+  compound_variant on: { look: :outline, intent: :primary } do
+    classes "text-blue-500"
+  end
+
+  # Apply these classes ONLY when look is :outline AND intent is :danger
+  compound_variant on: { look: :outline, intent: :danger } do
+    classes "text-red-500"
+  end
+end
+```
+
+-----
+
+## `action`
+
+The `action` method defines a named set of imperative UI mutations that can be triggered at runtime. This is the core of the client-side bridge for optimistic updates with Hotwire/Turbo. It is defined at the top level of the `tailmix` block.
+
+### Syntax
+
+```ruby
+action :name, method: :add | :remove | :toggle do
+  element :element_to_modify do
+    classes "..."
+    data key: "value"
+  end
+end
+```
+
+* **`:name` (Symbol)**: A unique name for the action, like `:show_spinner` or `:disable_form`.
+* **`method:`**: The default operation for all modifications within the block (`:add`, `:remove`, or `:toggle`).
+* **`element :name do ... end`**: Specifies which element the following modifications apply to.
+
+### Example
+
+```ruby
+action :show_pending_state, method: :add do
+  element :submit_button do
+    classes "opacity-50 cursor-not-allowed"
+    data pending: true
+  end
+
+  element :spinner do
+    # You can override the default method for a specific modification
+    classes "hidden", method: :remove
+  end
+end
+```
+
+-----
+
+## `stimulus`
+
+The `stimulus` DSL provides helpers for declaratively adding Stimulus `data-*` attributes. It is available inside any `element` block. The DSL is chainable and context-aware.
+
+### Setting the Context
+
+Most helpers require a controller context to be set first. You can do this in two ways:
+
+* **`.controller("name")`**: This is the primary method. It both adds a `data-controller="name"` attribute and sets the context for subsequent chained calls.
+* **`.context("name")`**: This method only sets the context for subsequent calls without adding a new `data-controller` attribute. This is useful when you want to add targets or actions to an element that is inside the scope of a controller defined on a parent element.
+
+### Helpers (Context-Aware)
+
+These methods must be called after `.controller()` or `.context()`.
+
+#### **`.target("name")`**
+
+Adds a target for the current controller context.
+
+* **Syntax**: `.target("myTarget")`
+* **Result**: `data-[controller-name]-target="myTarget"`
+
+#### **`.action(event, method)` or `.action("specifier")`**
+
+Adds an action for the current controller context. It has multiple forms for flexibility.
+
+* **Syntax 1 (Tuple)**: `.action(:click, :open)` -\> `data-action="click->[controller-name]#open"`
+* **Syntax 2 (Hash)**: `.action(click: :open, mouseenter: :highlight)` -\> `data-action="click->[controller-name]#open mouseenter->[controller-name]#highlight"`
+* **Syntax 3 (Raw String)**: `.action("click->other-controller#doSomething")`
+
+#### **`.value(:name, ...)`**
+
+Adds a value for the current controller context. It can be a literal value, or it can be resolved dynamically from a method or a proc.
+
+* **Syntax**:
+    * `.value(:my_value, value: "some-string")`
+    * `.value(:user_id, method: :current_user_id)`
+    * `.value(:timestamp, call: -> { Time.now.to_i })`
+* **Result**: `data-[controller-name]-my-value-value="..."`
+
+#### **`.action_payload(:action, as: :value_name)`**
+
+A powerful helper that serializes a Tailmix `action` definition into a Stimulus value, making it available on the client-side.
+
+* **Syntax**: `.action_payload(:disable_form, as: :disable_data)`
+* **Result**: `data-[controller-name]-disable-data-value="{...json...}"`
+
+### Example
+
+```ruby
+element :confirm_button, "px-4 py-2" do
+  stimulus
+    .controller("modal")                                # -> data-controller="modal"
+    .action(:click, :open)                               # -> data-action="click->modal#open"
+    .target("panel")                                     # -> data-modal-target="panel"
+    .value(:url, value: "/items/1")                      # -> data-modal-url-value="/items/1"
+    .action_payload(:toggle, as: :toggle_data)           # -> data-modal-toggle-data-value="{...}"
+end
+
+element :overlay do
+  # Assume `modal` controller is on a parent element
+  stimulus
+    .context("modal")
+    .action(:click, :close)                              # -> data-action="click->modal#close"
+end
+```
+
+-----

data/docs/03_advanced_usage.md

@@ -0,0 +1,88 @@
+# Advanced Usage
+
+This guide covers more advanced features of Tailmix, including component inheritance and using the developer tools.
+
+## Component Inheritance
+
+One of the most powerful features of Tailmix is the ability to inherit and extend component definitions. This allows you to create a base set of components for your design system and then specialize them for specific use cases.
+
+When a component class inherits from another, their `tailmix` definitions are intelligently merged:
+
+* **Base Classes**: Are combined, with duplicates removed.
+* **Dimensions & Variants**: Are merged. If a child defines a variant with the same name as a parent (e.g., `:sm`), the child's definition will completely **override** the parent's for that specific variant. New variants are added.
+* **Compound Variants**: Are combined. Both parent and child compound variants will be applied.
+* **Actions**: Are merged. If a child defines an action with the same name as a parent, the child's definition **overrides** the parent's.
+
+### Example: BaseButton and DangerButton
+
+Let's define a `BaseButtonComponent` and then a more specific `DangerButtonComponent` that inherits from it.
+
+**1. The Base Component**
+
+```ruby
+# app/components/base_button_component.rb
+class BaseButtonComponent
+  include Tailmix
+  attr_reader :ui
+
+  def initialize(size: :md)
+    @ui = tailmix(size: size)
+  end
+
+  tailmix do
+    element :button, "font-semibold border rounded" do
+      dimension :size, default: :md do
+        variant :sm, "px-2.5 py-1.5 text-xs"
+        variant :md, "px-3 py-2 text-sm"
+      end
+    end
+  end
+end
+```
+
+**2. The Inherited Component**
+
+The DangerButtonComponent inherits from BaseButtonComponent and only specifies what's different.
+
+```ruby
+# app/components/danger_button_component.rb
+class DangerButtonComponent < BaseButtonComponent
+  tailmix do
+    # This adds to the parent's base classes
+    element :button, "bg-red-500 text-white border-transparent hover:bg-red-600" do
+      # This adds a new variant to the :size dimension
+      dimension :size do
+        variant :lg, "px-4 py-2 text-base"
+      end
+    end
+  end
+end
+```
+
+**Resulting Definition for `DangerButtonComponent`:**
+
+The `:button` element will have the combined base classes: `"font-semibold border rounded bg-red-500 ..."`.
+
+The `:size` dimension will now have three variants available: `:sm`, `:md` (from the parent), and `:lg` (from the child).
+
+### Developer Tools
+
+Tailmix includes a set of developer tools available via the `.dev` class method on your component.
+
+`.dev.docs`
+
+Prints a comprehensive summary of the component's definition, including its signature, dimensions, variants, compound variants, and actions. This is invaluable for understanding a component's API at a glance.
+
+```ruby
+puts DangerButtonComponent.dev.docs
+```
+
+`.dev.stimulus.scaffold`
+
+
+Analyzes the component's `stimulus` definitions and generates a boilerplate Stimulus controller in your console, complete with all targets, values, and action methods.
+
+```ruby
+puts MyModalComponent.dev.stimulus.scaffold
+```
+

data/docs/04_client_side_bridge.md

@@ -0,0 +1,119 @@
+# The Client-Side Bridge
+
+Tailmix is primarily a server-side tool, but it includes a powerful "bridge" to your client-side JavaScript, enabling dynamic and optimistic UI updates. This bridge operates on several levels.
+
+## Level 1: The State Bridge
+
+Every element defined in Tailmix automatically receives a `data-tailmix-*` attribute.
+
+```html
+<button data-tailmix-button="size:md,intent:primary">
+  Click Me
+</button>
+```
+
+This attribute serves two purposes:
+
+1. A Stable Selector: You can reliably select this element in your JavaScript with `document.querySelector('[data-tailmix-button]')`. This is used internally by Tailmix actions.
+
+2. A State Indicator: The value of the attribute reflects the currently applied variants. Your JavaScript can read this to understand the element's state without needing extra data attributes.
+
+**Example: Reading State in Stimulus**
+
+```js
+// button_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+    connect() {
+        // e.g., "size:md,intent:primary"
+        const variants = this.element.dataset.tailmixButton;
+        console.log("Current button variants:", variants);
+
+        if (variants.includes("size:md")) {
+            // do something specific for medium buttons
+        }
+    }
+}
+```
+
+## Level 2: The Action Bridge
+
+This is the most powerful part of the bridge, allowing you to execute UI mutations defined in Ruby directly on the client.
+
+1. Define an `actio`n in Ruby
+   
+First, define an `action` in your component. This action describes a set of changes to apply to different elements.
+
+```ruby
+# app/components/form_component.rb
+class FormComponent
+  include Tailmix
+  tailmix do
+    element :submit_button
+    element :spinner, "hidden"
+
+    action :show_pending_state, method: :add do
+      element :submit_button do
+        classes "opacity-50 cursor-not-allowed"
+      end
+      element :spinner do
+        classes "hidden", method: :remove # override default method
+      end
+    end
+  end
+end
+```
+
+2. Expose it with action_payload
+   
+Use the `action_payload` helper in your `stimulus` block to serialize the action's definition into a Stimulus value.
+
+```ruby
+# ...inside the :submit_button element
+stimulus
+  .controller("form")
+  .action(:click, :submit)
+  .action_payload(:show_pending_state, as: :pending_data)
+```
+
+This will generate `data-form-pending-data-value="{...}"` containing the JSON definition of your `:show_pending_state` action.
+
+3. Run it from Stimulus
+
+In your Stimulus controller, import `Tailmix` and call `Tailmix.run()` with the action's config.
+
+```js
+// form_controller.js
+import { Controller } from "@hotwired/stimulus"
+import Tailmix from "tailmix"
+
+export default class extends Controller {
+    static values = { pendingData: Object }
+
+    submit(event) {
+        event.preventDefault();
+
+        // Instantly apply the UI changes defined in Ruby
+        Tailmix.run({
+            config: this.pendingDataValue,
+            controller: this
+        });
+
+        // ... now submit the form via fetch/AJAX ...
+    }
+}
+```
+
+When `submit` is called, the button's classes will be changed and the spinner will be shown instantly, creating a fast, optimistic UI update.
+
+## Level 3: The Definition Bridge (Future Vision)
+
+The ultimate goal is to allow the client to have access to the full `variant` and `compound_variant` definitions. This would enable the client to dynamically switch between any variant combination without a server roundtrip, providing a SPA-like experience.
+
+This is a complex feature planned for a future release and will likely involve passing the definitions via an inline `<script type="application/json">` tag to keep the component's HTML clean.
+
+
+
+
+