@trycourier/react-designer 0.2.0 → 0.4.0

package/README.md

@@ -283,40 +283,176 @@ const { requestId } = await courier.send({
 
 Variables are placeholders in your template that get replaced with actual data when the email is sent. For example, instead of writing "**Hello customer,**" you can write "**Hello `{{user.firstName}}`,**" which will display the recipient's actual name.
 
-The Courier Editor supports nested variable structures:
+The Courier Editor supports any valid variable name, including nested structures like `{{user.firstName}}` or `{{company.address.city}}`.
+
+**How to Insert Variables**
+
+Type `{{variableName}}` directly in the editor. The variable will be automatically converted to a variable node when you finish typing. Variable names must follow valid JSON property naming conventions (e.g., `user.firstName`, `company.name`).
+
+### 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.
 
 ```tsx
 import "@trycourier/react-designer/styles.css";
 import { TemplateEditor, TemplateProvider } from "@trycourier/react-designer";
 
 function App() {
+  // Define available variables (can be nested objects)
+  const variables = {
+    user: {
+      firstName: "",
+      lastName: "",
+      email: "",
+    },
+    order: {
+      id: "",
+      total: "",
+      date: "",
+    },
+    company: {
+      name: "",
+    },
+  };
+
   return (
     <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
-      <TemplateEditor
-        variables={{
-          user: {
-            firstName: "John",
-            lastName: "Doe",
-            email: "john@example.com",
-          },
-          company: {
-            name: "Acme Inc",
-            address: {
-              street: "123 Main St",
-              city: "San Francisco",
-            },
-          },
-        }}
-      />
+      <TemplateEditor variables={variables} />
     </TemplateProvider>
   );
 }
 ```
 
-**How to Insert Variables**
+When users type `{{` in the editor, they'll see a dropdown with:
+- `user.firstName`
+- `user.lastName`
+- `user.email`
+- `order.id`
+- `order.total`
+- `order.date`
+- `company.name`
+
+The dropdown filters as the user types, making it easy to find the right variable.
+
+**Disabling Autocomplete:**
+
+If you want to allow users to type any variable name without suggestions, use the `disableVariablesAutocomplete` prop:
+
+```tsx
+<TemplateEditor disableVariablesAutocomplete />
+```
+
+This is useful when you don't have a predefined list of variables and want to allow any variable name.
+
+### Variable Validation
+
+The editor supports custom variable validation, allowing you to restrict which variable names users can enter. This is useful when you have a specific set of allowed replacement variables and want to prevent users from entering arbitrary names that could cause errors downstream.
+
+```tsx
+import "@trycourier/react-designer/styles.css";
+import { TemplateEditor, TemplateProvider } from "@trycourier/react-designer";
+import type { VariableValidationConfig } from "@trycourier/react-designer";
+
+const ALLOWED_VARIABLES = [
+  "user.firstName",
+  "user.lastName",
+  "user.email",
+  "order.id",
+  "order.total",
+];
+
+function App() {
+  const variableValidation: VariableValidationConfig = {
+    // Custom validator - return true if variable is allowed
+    validate: (name) => ALLOWED_VARIABLES.includes(name),
+    
+    // Behavior when validation fails: "mark" (default) or "remove"
+    onInvalid: "mark",
+    
+    // Toast message shown on invalid variable
+    invalidMessage: (name) => 
+      `Variable "${name}" is not allowed. Available: ${ALLOWED_VARIABLES.join(", ")}`,
+  };
+
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <TemplateEditor variableValidation={variableValidation} />
+    </TemplateProvider>
+  );
+}
+```
+
+**VariableValidationConfig Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `validate` | `(name: string) => boolean` | - | Custom validator function. Returns `true` if the variable is allowed. Runs after built-in format validation. |
+| `onInvalid` | `"mark" \| "remove"` | `"mark"` | Behavior when validation fails. `"mark"` keeps the chip with invalid styling (red). `"remove"` deletes the chip. |
+| `invalidMessage` | `string \| ((name: string) => string)` | - | Message to show as a toast when validation fails. Can be a static string or a function for dynamic messages. |
+| `overrideFormatValidation` | `boolean` | `false` | If `true`, bypasses built-in format validation entirely. Only the custom `validate` function is used. Use with caution. |
+
+**Validation Flow:**
+
+1. **Built-in format validation** runs first (unless `overrideFormatValidation` is `true`), ensuring the variable name follows valid JSON property conventions.
+2. **Custom validation** runs second (if `validate` is provided), checking against your allowed list or custom rules.
+3. If validation fails, the `onInvalid` behavior is applied and a toast is shown if `invalidMessage` is configured.
+
+### Block Library Customization
 
-1. When editing text, type `{{` to open the variable suggestions dropdown. Select the variable you want to insert from the list.
-2. Via curly braces `{}` icon in top toolbar (if the variables are available for selected element).
+The `useBlockConfig` hook allows you to customize the blocks available in the sidebar, set default attributes, and create pre-configured block presets.
+
+_Note: `useBlockConfig` must be used inside of the `<TemplateProvider />` context_
+
+```tsx
+import { useBlockConfig, TemplateEditor, TemplateProvider } from "@trycourier/react-designer";
+
+function CustomBlocksEditor() {
+  const { setVisibleBlocks, setDefaults, registerPreset } = useBlockConfig();
+
+  useEffect(() => {
+    // Register a preset (pre-configured block variant)
+    registerPreset({
+      type: "button",
+      key: "console",
+      label: "Go to Console",
+      icon: <ExternalLinkIcon />, // Optional custom icon
+      attributes: { link: "https://console.example.com", backgroundColor: "#007bff" },
+    });
+
+    // Set default attributes for all new buttons (borderRadius is a number in pixels)
+    setDefaults("button", { borderRadius: 4 });
+
+    // Control which blocks appear in sidebar (and their order)
+    setVisibleBlocks([
+      "heading",
+      "text",
+      { type: "button", preset: "console" }, // Preset between built-in blocks
+      "image",
+      "button",
+    ]);
+  }, []);
+
+  return <TemplateEditor />;
+}
+```
+
+**API Reference:**
+
+| Function | Description |
+|----------|-------------|
+| `visibleBlocks` | Current visible blocks array |
+| `setVisibleBlocks(blocks)` | Set which blocks appear in sidebar |
+| `resetVisibleBlocks()` | Reset to default blocks |
+| `setDefaults(type, attrs)` | Set default attributes for a block type |
+| `getDefaults(type)` | Get defaults for a block type |
+| `clearDefaults(type)` | Clear defaults for a block type |
+| `registerPreset(preset)` | Register a pre-configured block variant |
+| `unregisterPreset(type, key)` | Remove a preset |
+| `presets` | All registered presets |
+| `getPresetsForType(type)` | Get presets for a specific block type |
+| `insertBlock(type, presetKey?)` | Programmatically insert a block |
+
+**Block Types:** `heading`, `text`, `image`, `button`, `divider`, `spacer`, `customCode`, `column`, `blockquote`
 
 ## Error Handling
 
@@ -489,6 +625,79 @@ function App() {
 }
 ```
 
+## Template Duplication
+
+The `useTemplateActions` hook provides a `duplicateTemplate` function that allows you to create a copy of the current template with a new ID. This is useful for creating variations of existing templates or providing users with a "Save As" functionality.
+
+_Note: `useTemplateActions` must be used inside of the `<TemplateProvider />` context_
+
+```tsx
+import { useTemplateActions, TemplateEditor, TemplateProvider } from "@trycourier/react-designer";
+import { useState } from "react";
+
+function DuplicateTemplateExample() {
+  const { duplicateTemplate } = useTemplateActions();
+
+  // Simple duplicate with auto-generated name (adds "-copy" suffix)
+  const handleQuickDuplicate = async () => {
+    const result = await duplicateTemplate();
+    if (result?.success) {
+      console.log(`Template duplicated to: ${result.templateId}`);
+    }
+  };
+
+  // Duplicate with custom ID
+  const handleCustomDuplicate = async () => {
+    const result = await duplicateTemplate({
+      targetTemplateId: "my-custom-template-id",
+      // Optionally provide a custom display name:
+      // name: "My Duplicated Template",
+    });
+    if (result?.success) {
+      console.log(`Template duplicated! New ID: ${result.templateId}, Version: ${result.version}`);
+    }
+  };
+
+  return (
+    <div>
+      <TemplateEditor />
+      <button onClick={handleQuickDuplicate}>Quick Duplicate</button>
+      <button onClick={handleCustomDuplicate}>Duplicate with Custom ID</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="original-template" tenantId="tenant-123" token="jwt">
+      <DuplicateTemplateExample />
+    </TemplateProvider>
+  );
+}
+```
+
+### Duplicate Template Options
+
+All options are optional. If called with no arguments, the function will create a duplicate with ID `{currentTemplateId}-copy`.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `targetTemplateId` | `string` | No | The ID for the new duplicated template. Defaults to `{currentTemplateId}-copy` |
+| `content` | `ElementalContent` | No | Override the content to duplicate (defaults to current editor content) |
+| `name` | `string` | No | Custom display name for the new template (defaults to targetTemplateId) |
+
+### Duplicate Template Result
+
+The `duplicateTemplate` function returns a promise that resolves to:
+
+```tsx
+interface DuplicateTemplateResult {
+  success: boolean;    // Whether the duplication succeeded
+  templateId: string;  // The ID of the new template
+  version?: string;    // The version of the newly created template
+}
+```
+
 ## Brand Editor
 
 The Brand Editor component allows you to customize and manage a tenant's brand settings directly within your application. This specialized editor provides an interface for modifying brand colors, logos, and other visual elements that will be applied to your templates.
@@ -568,18 +777,20 @@ The Properties section details the configuration options available for both the
 
 The Editor component is the core element that provides the template editing interface. If you are using the Template Editor with the Template provider, required properties will be provided.
 
-| Property         | Type                                   | Default  | Description                                                                                                                                                                                                                                                            |
-| ---------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| autoSave         | boolean                                | true     | Enables automatic saving of changes to the template. When true, changes are automatically persisted.                                                                                                                                                                   |
-| autoSaveDebounce | number                                 | 200ms    | Time in milliseconds to wait after changes before triggering an auto-save operation. Controls save frequency.                                                                                                                                                          |
-| brandEditor      | boolean                                | false    | When enabled, shows the brand editor interface alongside the template editor. Allows editing brand settings.                                                                                                                                                           |
-| brandProps       | BrandEditorProps                       |          | Configuration options for the brand editor when enabled. Passed directly to the BrandEditor component.                                                                                                                                                                 |
-| hidePublish      | boolean                                | false    | When true, hides the "Publish Changes" button in the editor interface.                                                                                                                                                                                                 |
-| onChange         | (value: ElementalContent) => void      |          | Callback function that fires whenever the editor content changes, providing the updated ElementalContent structure.                                                                                                                                                    |
-| routing          | { method: string; channels: string[] } |          | Configures multi-channel routing and delivery behavior. The `method` property determines delivery strategy: "single" (deliver via first available channel) or "all" (deliver via all configured channels). The `channels` array defines which delivery channels are available in the editor. |
-| 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.                                                                                                                                                        |
-| variables        | Record<string, any                     |          | Custom variables available for template personalization. These can be referenced within the template content.                                                                                                                                                          |
+| Property         | Type                                   | Default | Description                                                                                                                                                                                                                                                            |
+| ---------------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| autoSave         | boolean                                | true    | Enables automatic saving of changes to the template. When true, changes are automatically persisted.                                                                                                                                                                   |
+| autoSaveDebounce | number                                 | 2000ms  | Time in milliseconds to wait after changes before triggering an auto-save operation. Controls save frequency.                                                                                                                                                          |
+| brandEditor      | boolean                                | false   | When enabled, shows the brand editor interface alongside the template editor. Allows editing brand settings.                                                                                                                                                           |
+| brandProps       | BrandEditorProps                       |         | Configuration options for the brand editor when enabled. Passed directly to the BrandEditor component.                                                                                                                                                                 |
+| hidePublish      | boolean                                | false   | When true, hides the "Publish Changes" button in the editor interface.                                                                                                                                                                                                 |
+| onChange         | (value: ElementalContent) => void      |         | Callback function that fires whenever the editor content changes, providing the updated ElementalContent structure.                                                                                                                                                    |
+| routing          | { method: string; channels: string[] } |         | Configures multi-channel routing and delivery behavior. The `method` property determines delivery strategy: "single" (deliver via first available channel) or "all" (deliver via all configured channels). The `channels` array defines which delivery channels are available in the editor. |
+| 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.                                                                        |
+| 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
 
@@ -627,15 +838,17 @@ The TemplateProvider component wraps the Editor component and manages the templa
 
 The Brand Editor component accepts properties that allow you to customize its behavior and appearance. These properties provide control over the editing interface and functionality specific to brand management.
 
-| Property         | Type                           | Default  | Description                                                                                                                    |
-| ---------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| autoSave         | boolean                        | true     | Enables automatic saving of changes to the template. When true, changes are automatically persisted.                           |
-| autoSaveDebounce | number                         | 200ms    | Time in milliseconds to wait after changes before triggering an auto-save operation. Controls save frequency.                  |
-| hidePublish      | boolean                        | false    | When true, hides the "Publish Changes" button in the editor interface.                                                         |
-| onChange         | (value: BrandSettings) => void |          | Callback function that fires whenever brand settings are modified, providing the updated brand configuration values.           |
-| 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. |
-| variables        | Record<string, any             |          | Custom variables available for brand personalization. These can be referenced within the brand footer content.                 |
+| Property         | Type                           | Default | Description                                                                                                                    |
+| ---------------- | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| autoSave         | boolean                        | true    | Enables automatic saving of changes to the template. When true, changes are automatically persisted.                           |
+| autoSaveDebounce | number                         | 2000ms  | Time in milliseconds to wait after changes before triggering an auto-save operation. Controls save frequency.                  |
+| hidePublish      | boolean                        | false   | When true, hides the "Publish Changes" button in the editor interface.                                                         |
+| onChange         | (value: BrandSettings) => void |         | Callback function that fires whenever brand settings are modified, providing the updated brand configuration values.           |
+| 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.           |
+| disableVariablesAutocomplete | boolean              | false   | When `true`, disables variable autocomplete and allows users to type any variable name directly.                                  |
 
 ### Brand Provider