@trycourier/react-designer 0.5.1 → 0.7.0

package/README.md

@@ -291,7 +291,9 @@ Type `{{variableName}}` directly in the editor. The variable will be automatical
 
 ### Variable Autocomplete
 
-When you provide a `variables` prop, the editor shows an autocomplete dropdown when users type `{{`. This guides users to select from available variables and helps prevent typos.
+When you provide a `variables` prop, the editor enables variable functionality: typing `{{` creates variable chips, the variable toolbar button is shown, and an autocomplete dropdown guides users to select from available variables.
+
+> **Note:** If the `variables` prop is not provided (or is `undefined`), all variable functionality is disabled — the variable toolbar button is hidden and typing `{{` will not create variable chips. To enable variables without autocomplete suggestions, pass an empty object: `variables={{}}`.
 
 ```tsx
 import "@trycourier/react-designer/styles.css";
@@ -789,7 +791,7 @@ The Editor component is the core element that provides the template editing inte
 | theme            | ThemeObj \| cssClass                   |         | Controls the visual appearance of the editor. Can be a Theme object with styling properties or a CSS class name.                                                                                                                                                       |
 | value            | ElementalContent                       |         | Initial content for the editor in ElementalContent format. Used as the starting template when the editor loads.                                                                                                                                                        |
 | variableValidation | VariableValidationConfig             |         | Configuration for custom variable validation. Allows restricting which variable names are allowed and defining behavior on validation failure. See [Variable Validation](#variable-validation) section for details.                                                    |
-| variables        | Record<string, any>                    |         | Variables available for autocomplete suggestions. When provided, typing `{{` shows a dropdown with matching variables. See [Variable Autocomplete](#variable-autocomplete) section for details.                                                                        |
+| variables        | Record<string, any>                    |         | Variables available for autocomplete suggestions. When provided, typing `{{` shows a dropdown with matching variables. When not provided (`undefined`), all variable functionality is disabled (toolbar button hidden, `{{` typing does not create chips). Pass `{}` to enable variables without suggestions. See [Variable Autocomplete](#variable-autocomplete) section for details. |
 | disableVariablesAutocomplete | boolean                      | false   | When `true`, disables variable autocomplete and allows users to type any variable name directly. When `false` (default), shows autocomplete dropdown with variables from the `variables` prop.                                                                          |
 
 ### Multi-Channel Routing
@@ -847,7 +849,7 @@ The Brand Editor component accepts properties that allow you to customize its be
 | theme            | ThemeObj \| cssClass           |         | Controls the visual appearance of the editor. Can be a Theme object with styling properties or a CSS class name.               |
 | value            | BrandSettings                  |         | Initial brand settings values to populate the editor with, including colors, logo, social links, and header style preferences. |
 | variableValidation | VariableValidationConfig     |         | Configuration for custom variable validation. See [Variable Validation](#variable-validation) section for details.             |
-| variables        | Record<string, any>            |         | Variables available for autocomplete suggestions. When provided, typing `{{` shows a dropdown with matching variables.           |
+| variables        | Record<string, any>            |         | Variables available for autocomplete suggestions. When not provided, all variable functionality is disabled. Pass `{}` to enable without suggestions. |
 | disableVariablesAutocomplete | boolean              | false   | When `true`, disables variable autocomplete and allows users to type any variable name directly.                                  |
 
 ### Brand Provider
@@ -859,6 +861,76 @@ The Brand Provider component is responsible for managing brand-related state and
 | tenantId | string | Yes      | The unique identifier for the tenant whose brand settings are being edited.           |
 | token    | string | Yes      | Authentication token (JWT or ClientKey) used to authorize brand-related API requests. |
 
+## Shadow DOM Usage
+
+If you render the Courier Editor inside a [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) (e.g., for style isolation), drag-and-drop functionality will not work out of the box. This is a known incompatibility with the underlying [pragmatic-drag-and-drop](https://github.com/atlassian/pragmatic-drag-and-drop) library, which relies on `event.target` to identify dragged elements. Shadow DOM re-targets events to the shadow host, breaking this detection.
+
+We provide a utility function `applyShadowDomDndFix` that patches event handling to restore drag-and-drop support inside a Shadow DOM.
+
+### Setup
+
+Call `applyShadowDomDndFix(shadowRoot)` **after** creating the shadow root but **before** rendering the editor. Store the returned cleanup function and call it when unmounting.
+
+```tsx
+import { useEffect, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import {
+  TemplateEditor,
+  TemplateProvider,
+  applyShadowDomDndFix,
+} from "@trycourier/react-designer";
+import "@trycourier/react-designer/styles.css";
+
+function EditorInShadowDom() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    // 1. Create Shadow DOM
+    const shadowRoot = container.attachShadow({ mode: "open" });
+
+    // 2. Apply DnD fix BEFORE rendering the editor
+    const cleanupDndFix = applyShadowDomDndFix(shadowRoot);
+
+    // 3. Inject styles into shadow root
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = "/path/to/react-designer/styles.css";
+    shadowRoot.appendChild(link);
+
+    // 4. Render the editor
+    const mountPoint = document.createElement("div");
+    shadowRoot.appendChild(mountPoint);
+
+    const root = createRoot(mountPoint);
+    root.render(
+      <TemplateProvider
+        templateId="my-template"
+        tenantId="my-tenant"
+        token="my-token"
+      >
+        <TemplateEditor />
+      </TemplateProvider>
+    );
+
+    // 5. Cleanup on unmount
+    return () => {
+      cleanupDndFix();
+      root.unmount();
+    };
+  }, []);
+
+  return <div ref={containerRef} />;
+}
+```
+
+### Known Limitations
+
+- **Drag handles are disabled in Shadow DOM.** In a normal DOM context, blocks can only be dragged by the grip icon on the left. Inside a Shadow DOM, blocks become draggable from anywhere on the element. This is because pragmatic-drag-and-drop's internal handle validation is not compatible with Shadow DOM event re-targeting.
+- **Global patch.** The fix monkey-patches `Event.prototype.target` while active. Always call the cleanup function when unmounting to restore normal behavior.
+
 # Limitations
 
 **React Only**