@trycourier/react-designer 0.2.0 → 0.3.0

package/README.md

@@ -283,40 +283,68 @@ 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}}`.
 
-```tsx
-import "@trycourier/react-designer/styles.css";
-import { TemplateEditor, TemplateProvider } from "@trycourier/react-designer";
+**How to Insert Variables**
 
-function App() {
-  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",
-            },
-          },
-        }}
-      />
-    </TemplateProvider>
-  );
+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`).
+
+### Block Library Customization
+
+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 />;
 }
 ```
 
-**How to Insert Variables**
+**API Reference:**
 
-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).
+| 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 +517,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 +669,18 @@ 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.                                                                                                                                                        |
+| variables        | Record<string, any>                    |         | **Deprecated.** Previously used for autocomplete suggestions. Users can now type any variable directly. This prop has no effect.                                                                                                                                       |
 
 ### Multi-Channel Routing
 
@@ -627,15 +728,15 @@ 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. |
+| variables        | Record<string, any>            |         | **Deprecated.** Previously used for autocomplete suggestions. Users can now type any variable directly. This prop has no effect. |
 
 ### Brand Provider