feat(editor): add fluent API for binding live updates to elements

- Introduced `LiveUpdatesBuilder` for chaining live update bindings in Blade (`text()`, `html()`, `outerHtml()`, `attr()`, `style()`).
- Enhanced JavaScript logic to support new `data-live-update-*` attributes with type and target parsing.
- Updated documentation with examples demonstrating fluent usage.

Author: eldomagan

docs/building-theme/adding-sections/integrating-editor.md

@@ -68,36 +68,87 @@ Bagisto Visual supports this via:
 
 ### Option 1: `liveUpdate()` Blade Directives
 
-Use `$section->liveUpdate()` or `$block->liveUpdate()` to wire an element to a setting.
+Use `$section->liveUpdate()` or `$block->liveUpdate()` to bind settings to elements.
 
-#### Text Content
+These helpers inject metadata to enable the editor to update the live preview without requiring a server-side re-render.
+
+#### `->text(string $settingId)`
+
+**Updates the element's `textContent`** whenever the specified setting changes.
+
+```blade
+<h1 {{ $section->liveUpdate()->text('heading') }}>
+  {{ $section->settings->heading }}
+</h1>
+```
+
+#### `->html(string $settingId)`
+
+**Updates the element's `innerHTML`** with the new setting value.
 
 ```blade
-<h2 {{ $section->liveUpdate('title') }}>
-  {{ $section->settings->title }}
-</h2>
+<div {{ $section->liveUpdate()->html('html_content') }}>
+  {!! $section->settings->html_content !!}
+</div>
 ```
 
-#### Element Attributes
+#### `->outerHtml(string $settingId)`
+
+**Replaces the entire element (`outerHTML`)** with the setting value.
 
 ```blade
-<img src="{{ $section->settings->image }}" {{ $section->liveUpdate('image', 'src') }}>
+<div {{ $section->liveUpdate()->outerHtml('html_block') }}>
+  {!! $section->settings->html_block !!}
+</div>
 ```
 
-#### Inside Blocks
+#### `->attr(string $settingId, string $attributeName)`
+
+**Updates the specified HTML attribute** (e.g. `src`, `href`, `alt`) with the setting value.
+
+```blade
+<img
+  src="{{ $section->settings->image }}"
+  {{ $section->liveUpdate()->attr('image', 'src') }}>
+```
+
+#### `->style(string $settingId, string $property)`
+
+**Updates a specific CSS style property** on the element using the setting value.
+
+```blade
+<div
+  style="width: {{ $section->settings->width }}"
+  {{ $section->liveUpdate()->style('width', 'width') }}>
+</div>
+```
+
+#### 🔹 Multiple Bindings on a Single Element
+
+You can bind multiple settings fluently to different parts of the same element:
+
+```blade
+<a
+  href="{{ $section->settings->link_url }}"
+  {{ $section->liveUpdate()
+      ->text('link_text')
+      ->attr('link_url', 'href') }}>
+  {{ $section->settings->link_text }}
+</a>
+```
+
+#### 🔹 Working Inside Blocks
+
+Works seamlessly inside dynamic or repeated blocks:
 
 ```blade
 @foreach ($section->blocks as $block)
   <p {{ $block->liveUpdate('text') }}>
-    {{ $block->settings['text'] }}
+    {{ $block->settings->text }}
   </p>
 @endforeach
 ```
 
-These helpers inject metadata to enable the editor to update content without requiring a server-side re-render.
-
----
-
 ### Option 2: JavaScript API (`Visual.handleLiveUpdate()`)
 
 For more complex cases (e.g. multiple targets, transform logic, or styling), use `Visual.handleLiveUpdate()`:

…isual/editor/assets/injected-NBYyEDlC.js …isual/editor/assets/injected-CVeaO1fW.jspublic/vendor/bagistoplus/visual/editor/assets/injected-NBYyEDlC.js renamed to public/vendor/bagistoplus/visual/editor/assets/injected-CVeaO1fW.js public/vendor/bagistoplus/visual/editor/assets/injected-NBYyEDlC.js renamed to public/vendor/bagistoplus/visual/editor/assets/injected-CVeaO1fW.js

@@ -48,7 +48,7 @@
     ]
   },
   "resources/assets/editor/injected.ts": {
-    "file": "assets/injected-NBYyEDlC.js",
+    "file": "assets/injected-CVeaO1fW.js",
     "name": "injected",
     "src": "resources/assets/editor/injected.ts",
     "isEntry": true

public/vendor/bagistoplus/visual/editor/manifest.json

@@ -424,18 +424,44 @@ class ThemeEditor {
     settingValue: any;
   }): boolean {
     const { section, block, settingId, settingValue } = data;
-    const key = [section?.id, block?.id, settingId].filter(Boolean).join(':');
-
-    const el = document.querySelector(`[data-live-update-key="${key}"]`) as HTMLElement;
+    const key = [section?.id, block?.id, settingId].filter(Boolean).join('.');
+    const attrName = `data-live-update-${key}`;
+    const selector = `[${CSS.escape(attrName)}]`;
 
+    const el = document.querySelector(selector) as HTMLElement;
     if (!el) {
       return false;
     }
 
-    if (el.dataset.liveUpdateAttr) {
-      el.setAttribute(el.dataset.liveUpdateAttr, settingValue);
-    } else {
-      el.textContent = settingValue;
+    const type = el.getAttribute(attrName);
+    const [updateType, updateKey] = type?.split(':') ?? ['text', undefined];
+
+    switch (updateType) {
+      case 'text':
+        el.textContent = settingValue;
+        break;
+      case 'html':
+        el.innerHTML = settingValue;
+        break;
+      case 'outerHTML':
+        el.outerHTML = settingValue;
+        break;
+      case 'attr':
+        if (!settingValue) {
+          el.removeAttribute(updateKey as string);
+        } else {
+          el.setAttribute(updateKey as string, settingValue);
+        }
+        break;
+      case 'style':
+        if (!settingValue) {
+          el.style.removeProperty(updateKey as string);
+        } else {
+          el.style.setProperty(updateKey as string, settingValue);
+        }
+        break;
+      default:
+        console.warn(`Unknown live update type: ${updateType}`);
     }
 
     return true;

resources/assets/editor/injected.ts

@@ -52,13 +52,18 @@ public function jsonSerialize(): mixed
         ];
     }
 
-    public function liveUpdate(string $settingId, ?string $attribute = null): LiveUpdateData
+    public function liveUpdate(?string $settingId = null, ?string $attr = null): LiveUpdatesBuilder
     {
-        return new LiveUpdateData(
-            settingId: $settingId,
-            attribute: $attribute,
-            sectionId: $this->sectionId,
-            blockId: $this->id,
-        );
+        $builder = new LiveUpdatesBuilder(sectionId: $this->sectionId, blockId: $this->id);
+
+        if ($settingId && $attr) {
+            return $builder->attr($settingId, $attr);
+        }
+
+        if ($settingId) {
+            return $builder->text($settingId);
+        }
+
+        return $builder;
     }
 }

src/Sections/Support/BlockData.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace BagistoPlus\Visual\Sections\Support;
+
+use BagistoPlus\Visual\Facades\ThemeEditor;
+use Illuminate\Contracts\Support\Htmlable;
+
+/**
+ * This class is used to build live updates metadata for a specific section or block in the theme editor.
+ * It allows adding various types of updates such as text, HTML, outer HTML, attributes, and styles.
+ */
+class LiveUpdatesBuilder implements Htmlable
+{
+    protected string $sectionId;
+
+    protected ?string $blockId;
+
+    protected array $updates = [];
+
+    public function __construct(string $sectionId, ?string $blockId = null)
+    {
+        $this->sectionId = $sectionId;
+        $this->blockId = $blockId;
+    }
+
+    protected function makeKey(string $settingId): string
+    {
+        return collect([
+            'section' => $this->sectionId,
+            'block' => $this->blockId,
+            'setting' => $settingId,
+        ])->filter()->implode('.');
+    }
+
+    protected function add(string $settingId, string $type): self
+    {
+        $this->updates[] = [
+            'key' => $this->makeKey($settingId),
+            'type' => $type,
+        ];
+
+        return $this;
+    }
+
+    public function text(string $settingId): self
+    {
+        return $this->add($settingId, 'text');
+    }
+
+    public function html(string $settingId): self
+    {
+        return $this->add($settingId, 'html');
+    }
+
+    public function outerHtml(string $settingId): self
+    {
+        return $this->add($settingId, 'outerHTML');
+    }
+
+    public function attr(string $settingId, string $attr): self
+    {
+        return $this->add($settingId, 'attr:'.$attr);
+    }
+
+    public function style(string $settingId, string $style): self
+    {
+        return $this->add($settingId, 'style:'.$style);
+    }
+
+    public function toHtml(): string
+    {
+        return $this->__toString();
+    }
+
+    public function __toString(): string
+    {
+        if (! ThemeEditor::inDesignMode()) {
+            return '';
+        }
+
+        return collect($this->updates)->map(function ($update) {
+            $attr = 'data-live-update-'.$update['key'];
+
+            return $attr.'="'.htmlspecialchars($update['type'], ENT_QUOTES, 'UTF-8').'"';
+        })->implode(' ');
+    }
+}

src/Sections/Support/LiveUpdateData.php

@@ -85,12 +85,18 @@ public function jsonSerialize(): mixed
         ];
     }
 
-    public function liveUpdate(string $settingId, ?string $attribute = null): LiveUpdateData
+    public function liveUpdate(?string $settingId = null, ?string $attr = null): LiveUpdatesBuilder
     {
-        return new LiveUpdateData(
-            settingId: $settingId,
-            attribute: $attribute,
-            sectionId: $this->id,
-        );
+        $builder = new LiveUpdatesBuilder(sectionId: $this->id, blockId: null);
+
+        if ($settingId && $attr) {
+            return $builder->attr($settingId, $attr);
+        }
+
+        if ($settingId) {
+            return $builder->text($settingId);
+        }
+
+        return $builder;
     }
 }