@trycourier/react-designer 0.0.3 → 0.0.5

package/README.md

@@ -145,15 +145,23 @@ import { TemplateEditor, TemplateProvider, useTemplateActions } from '@trycourie
 function SaveButtonComponent() {
   const { publishTemplate } = useTemplateActions();
   
-  const handlePublishTemplate = () => {
+  const handlePublishTemplate = async () => {
 	  //... other publish logic
 	  await publishTemplate();
   }
 
-	return (
-		<TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+  return (
+    <div>
       <TemplateEditor hidePublish />
-			<button onClick={handlePublishTemplate}>Save Template</button>;
+      <button onClick={handlePublishTemplate}>Save Template</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <SaveButtonComponent />
     </TemplateProvider>
   );
 }
@@ -201,6 +209,8 @@ function App() {
 
 By default, the Courier Editor auto-saves content. To disable this feature, configure the provider as follows
 
+*Note:* `useTemplateActions` *must be used inside of the `<TemplateProvider />` context*
+
 ```tsx
 import "@trycourier/react-designer/styles.css";
 import { TemplateEditor, TemplateProvider, useTemplateActions } from '@trycourier/react-designer';
@@ -208,16 +218,24 @@ import { TemplateEditor, TemplateProvider, useTemplateActions } from '@trycourie
 function SaveButtonComponent() {
   const { saveTemplate, publishTemplate } = useTemplateActions();
   
-  const handleSaveTemplate = () => {
+  const handleSaveTemplate = async () => {
 	  //... other publish logic
 	  await saveTemplate(); // the template must be saved before publishing
 	  await publishTemplate();
   }
 
-	return (
-		<TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+  return (
+    <div>
       <TemplateEditor autoSave={false} hidePublish />
-			<button onClick={handleSaveTemplate}>Save Template</button>;
+      <button onClick={handleSaveTemplate}>Save Template</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <SaveButtonComponent />
     </TemplateProvider>
   );
 }
@@ -263,20 +281,20 @@ function App() {
     <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"
-				    }
-				  }
-				}}
-			/>
+          "user": {
+            "firstName": "John",
+            "lastName": "Doe",
+            "email": "john@example.com"
+          },
+          "company": {
+            "name": "Acme Inc",
+            "address": {
+              "street": "123 Main St",
+              "city": "San Francisco"
+            }
+          }
+        }}
+      />
     </TemplateProvider>
   );
 }
@@ -287,6 +305,172 @@ function App() {
 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).
 
+## Error Handling
+
+The Courier Editor includes a comprehensive error handling system that automatically provides user-friendly notifications for various error types including API errors, network failures, validation issues, and file upload problems.
+
+### Custom Error Handling
+
+You can programmatically trigger and handle errors using the `useTemplateActions` hook. This is useful for custom validation, user actions, or integration with external systems.
+
+*Note: `useTemplateActions` must be used inside of the `<TemplateProvider />` context*
+
+```tsx
+import { useTemplateActions, TemplateEditor, TemplateProvider } from '@trycourier/react-designer';
+
+function CustomComponent() {
+  const { setTemplateError } = useTemplateActions();
+  
+  const handleCustomAction = async () => {
+    try {
+      // Your custom logic here
+      await someApiCall();
+    } catch (error) {
+      // Simple string error (automatically converted)
+      setTemplateError("Something went wrong with your custom action");
+      
+      // Or create a structured error with custom toast configuration
+      setTemplateError({
+        message: "Custom error message",
+        toastProps: {
+          duration: 6000,
+          action: {
+            label: "Retry",
+            onClick: () => handleCustomAction(),
+          },
+          description: "Additional context about the error"
+        }
+      });
+    }
+  };
+
+  return (
+    <div>
+      <TemplateEditor />
+      <button onClick={handleCustomAction}>Custom Action</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <CustomComponent />
+    </TemplateProvider>
+  );
+}
+```
+
+### Error Object Structure
+
+All errors use a simple, consistent structure:
+
+```tsx
+// Error interface
+interface TemplateError {
+  message: string;                    // The error message to display
+  toastProps?: ExternalToast;         // Optional Sonner toast configuration
+}
+
+// Usage examples
+setTemplateError({
+  message: "Upload failed",
+  toastProps: {
+    duration: 5000,
+    description: "File size too large",
+    action: {
+      label: "Try Again",
+      onClick: () => retryUpload(),
+    }
+  }
+});
+
+// Different error scenarios
+setTemplateError({ message: "Authentication failed", toastProps: { duration: 6000 } });
+setTemplateError({ message: "Network error", toastProps: { description: "Check connection" } });
+setTemplateError({ message: "Validation error", toastProps: { duration: 5000 } });
+```
+
+### Error Boundary Protection
+
+The editor includes an error boundary component to catch and handle React rendering errors gracefully.
+
+*Note: `useTemplateActions` must be used inside of the `<TemplateProvider />` context*
+
+```tsx
+import { ErrorBoundary, useTemplateActions, TemplateEditor, TemplateProvider } from '@trycourier/react-designer';
+
+function TemplateEditorWithErrorHandling() {
+  const { setTemplateError } = useTemplateActions();
+
+  return (
+    <ErrorBoundary 
+      onError={(error, errorInfo) => {
+        // Custom error logging
+        console.error('Editor error:', error);
+        
+        // Optional: integrate with template error system
+        setTemplateError({
+          message: `Render error: ${error.message}`,
+          toastProps: {
+            duration: 6000,
+            action: {
+              label: "Reload",
+              onClick: () => window.location.reload(),
+            },
+          }
+        });
+      }}
+      fallback={<div>Something went wrong. Please refresh the page.</div>}
+    >
+      <TemplateEditor />
+    </ErrorBoundary>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <TemplateEditorWithErrorHandling />
+    </TemplateProvider>
+  );
+}
+```
+
+### Clearing Errors
+
+To programmatically clear the current error state:
+
+*Note: `useTemplateActions` must be used inside of the `<TemplateProvider />` context*
+
+```tsx
+import { useTemplateActions, TemplateEditor, TemplateProvider } from '@trycourier/react-designer';
+
+function ClearErrorComponent() {
+  const { setTemplateError } = useTemplateActions();
+
+  const handleClearError = () => {
+    // Clear the error
+    setTemplateError(null);
+  };
+
+  return (
+    <div>
+      <TemplateEditor />
+      <button onClick={handleClearError}>Clear Error</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <TemplateProvider templateId="template-123" tenantId="tenant-123" token="jwt">
+      <ClearErrorComponent />
+    </TemplateProvider>
+  );
+}
+```
+
 ## 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.