useblocks 1.1.85-dev.10 → 1.1.85-dev.11

package/README.md

@@ -49,7 +49,7 @@ How the merged **`ExportedApi`** interfaces, **`AppEvent`** and payload types fi
 | --- | --- |
 | **`init`** | **`content` is mandatory**. **`init(options) → Promise<Instance>`**. |
 | Module vs **instance** | The **`useblocks`** bundle exports **`init`** (plus optional named ESM APIs). **`setConfig`**, **`show`**, **`save`**, **`destroy`** belong to the **`init`** return value—not the namespace object. |
-| Same DOM repeat | Calling **`init`** again on an existing mount triggers **`reset`**. Avoid parallel **`init`** on one container. |
+| Same DOM repeat | Calling **`init`** again on the same element returns **the same object** and applies options like **`setConfig`**. A call made while the previous one is still starting supersedes it: the previous promise rejects with **`AbortError`**. **`destroy()`** through any reference destroys the editor. One object per call — **`ownership: 'counted'`**. |
 | Events | **`instance.handle*(…)`** usually returns **unsubscribe**. **`handleSubjectChanged`** / **`handlePreheaderChanged`** use bespoke signatures — see typings. |
 | Async | Handlers plus **`getAuthToken`** may be **`async`**; funnel errors via **`handleError`** or your own telemetry. |
 | Build | Without Webpack/Vite helpers you must wire **`__useblocks__`** / **`publicPath`**. Expect a heavy UI bundle (React, Monaco, etc.). |
@@ -152,11 +152,11 @@ You can take **`EMAIL_CODE`** from <a href="https://cdn.useblocks.io/plugin/new-
 
 For debugging, the dev build may support a front-end token flow — configure an auth proxy in your app if you use that path.
 
-### Editor handle: `create()`
+### The editor object right away: `create()`
 
 `init()` resolves only once the editor is ready and the email from `content` is shown. Handlers fire
 earlier — inside `init()` — so they cannot refer to the editor: your variable is not assigned yet.
-`create()` returns a **handle** right away, synchronously, with readiness as a separate promise:
+`create()` returns the **editor object** right away, synchronously, with readiness as a separate promise:
 
 ```javascript
 const editor = emailmaker.create({
@@ -164,7 +164,7 @@ const editor = emailmaker.create({
   element: '#editor',
   content: { email },
   handleEmailInit: async () => {
-    // The handle already exists — it is assigned by the time the event fires.
+    // The object already exists — it is assigned by the time the event fires.
     const compiled = await editor.compileEmail(undefined, { amp: true });
     await saveOnYourSide(compiled);
   },
@@ -172,9 +172,11 @@ const editor = emailmaker.create({
 await editor.ready;
 ```
 
-You can store the handle, subscribe to events or call `destroy()` right away.
+It is a plain object, just like the result of `init()`: every method is an own property, visible to
+`Object.keys`, spread and `Object.assign`, and any method can be replaced with your own. You can store
+the object, subscribe to events or call `destroy()` right away.
 
-The handle is bound to the editor as soon as the editor is assembled — before the email from `content`
+The object is bound to the editor as soon as the editor is assembled — before the email from `content`
 is shown — so calls made from handlers (like `compileEmail()` above) reach the editor. Once bound,
 every call goes straight to the editor. Before binding:
 
@@ -185,28 +187,17 @@ every call goes straight to the editor. Before binding:
 | `setEmailMeta`, `setBlockMeta`, `notify` | applied once ready, in order |
 | `getElement()` | the element from options if it was passed as an element; `undefined` for a selector |
 | `getCodeErrors()` | an empty list |
-| `getConfig()`, `use()`, `container`, `undoRedoService` | throw — await `ready` or use `useAsync()` |
+| `getConfig()`, `use()` | throw a clear error — await `ready` or use `useAsync()` |
+| `container`, `undoRedoService` fields | `undefined`; reading them never throws |
 | `destroy()` | cancels initialisation; `ready` rejects with `AbortError` |
 
-After `destroy()` the handle is detached: its subscriptions are removed and its methods reject like a
-destroyed editor's. If another owner has already reused the element, destroying the previous handle
-leaves the editor alone and only takes its own subscriptions with it.
-
 Between binding and `ready` the email may not be shown yet. If you need the shown document — a
 `getEmailSnapshot()`, for example — await `ready` first.
 
-Another `create()` or `init()` into the same element reuses its editor with the new options (waiting for
-a start still in progress): both calls succeed and the editor belongs to the latest
-one. From then on the earlier handle is not the owner: it stops receiving events, and its `destroy()` only
-detaches it and leaves the editor alone. `destroy()` of the latest handle destroys the editor, even before
-its `ready`.
-
-If the new call passes the same data as the earlier one — the same email, configuration, user and the same
-set of handlers, even as new functions, as on every component re-render — the editor does not re-apply the
-options: the email is not shown again, `handleSetOptions` and `handleOptionsChanged` do not fire, and
-events go to the new call's handlers.
+A repeated `create()` or `init()` into the same element is described below, in
+[“Repeated init() into the same element”](#repeated-init-into-the-same-element).
 
-An initialisation error arrives as a `ready` rejection. If you create a handle and never await
+An initialisation error arrives as a `ready` rejection. If you create an object and never await
 `ready`, such an error surfaces in the console as unhandled — on purpose, otherwise there is no way to
 learn the editor did not start. The exception is `destroy()` before `ready`: that rejection is
 expected and stays quiet.
@@ -254,7 +245,7 @@ When you need full control over the lifecycle, mount the editor by hand with **`
 
 Configuration is a nested object: editor chrome, initial email payload, and callback hooks.
 
-Calling **`init`** again on the **same DOM host** reuses the editor (**`reset`**) with the new options; a start still in progress is awaited. Both calls succeed, the latest call owns the editor.
+Calling **`init`** again on the **same DOM host** returns the same object and applies the new options — see [“Repeated init() into the same element”](#repeated-init-into-the-same-element).
 
 ### Element
 
@@ -291,31 +282,70 @@ is our job, not yours.
 | metadata and document state | yes |
 | the email markup | replaced by whatever you pass in `content` |
 
-### Tear-down with more than one owner
+### Repeated init() into the same element
 
-One container outlives several owners: a page starts the editor, the next page enters the same
-container and gets the same instance. This happens without you arranging it — React unmounts the
-previous page **after** mounting the new one, and StrictMode invokes the effect twice.
+How a repeated `init()` or `create()` into the same container behaves is set by the `ownership` option.
 
-So `destroy()` tears the editor down only for the latest owner. An earlier owner's tear-down means
-"I no longer hold it" and leaves the running instance alone:
+**By default (`ownership: 'single'`) — as in 1.1.89.** The container has one editor object:
 
 ```javascript
 const first = await emailmaker.init({ element: '#editor', content });
-const second = await emailmaker.init({ element: '#editor', content });  // the same editor
+const second = await emailmaker.init({ element: '#editor', content, config });
+first === second; // true
 
-first.destroy();   // destroys nothing: second owns it now
-second.destroy();  // destroys it
+second.destroy(); // destroys the editor — through any reference
 ```
 
-Keep what the **latest** `init()` returned. Previously a late tear-down killed the editor under the
-new page, and the next show failed with `DestroyedInstanceError`.
+- A repeated call applies its options like `setConfig`. Handlers from options are swapped at once:
+  later events go to the new call's handlers. Subscriptions made through the object
+  (`editor.handleSaveEmail(cb)`) stay — it is the same object.
+- The email is shown again only if it differs from the one you set last yourself — via `init`, `show`
+  or `reset`. `init(A)` → `show(B)` → `init(A)` brings email A back. `init(A)` → `init(A)` does not
+  redraw it, so the user's edits stay.
+- If the call passes the same data as the previous one — the same email, configuration, user and the
+  same set of handlers, even as new functions, as on every component re-render — the options are not
+  re-applied: `handleSetOptions` and `handleOptionsChanged` do not fire and the token is not requested
+  again.
+- A call made while the previous one is still starting supersedes it: the previous promise rejects with
+  an `AbortError` (`emailmaker.isSupersededInitError(error)`), and only the new one succeeds.
+- `destroy()` through any reference destroys the editor, and `handleDestroy` subscribed through the
+  object fires.
+
+**`ownership: 'counted'` — an object per call.** Use it when several parts of your app share the
+editor in one container: a page starts it, the next page enters the same container, and the previous
+page's tear-down comes later — React unmounts the previous page **after** mounting the new one, and
+StrictMode invokes the effect twice.
+
+```javascript
+const first = emailmaker.create({ element: '#editor', content, ownership: 'counted' });
+const second = emailmaker.create({ element: '#editor', content, ownership: 'counted' });
+await Promise.all([first.ready, second.ready]); // both succeed, one editor
+
+first.destroy();  // releases only first's share and its subscriptions
+second.destroy(); // the last share: the editor is destroyed shortly after
+```
+
+- Every call gets its own object with all methods of the shared editor and holds a share in it. The
+  object's subscriptions live until its `destroy()`.
+- `destroy()` releases the object's share. The editor is destroyed once no shares are left — after a
+  short delay, so a tear-down immediately followed by a new call (StrictMode) does not recreate it.
+- The options and handlers of the latest call apply. When its share is released, the handlers from
+  options move to the latest remaining owner; the email and settings stay as they are.
+- `emailmaker.getInstance(element)` returns the latest call's object.
+
+**Modes can be mixed.** A call without the flag holds the editor until its object's `destroy()` and
+gets the container's shared object. Counted shares live on top of it. `destroy()` of the object without
+the flag destroys the editor with all shares — their objects then behave as after `destroy()`. In
+development mode mixing is flagged with a console warning.
+
+**If a repeated call fails to start** (the token or `app_init` failed, or it was cancelled via
+`signal`), only that call is rejected: the editor keeps its previous options and its email, restored
+from a snapshot (text and header; undo history is cleared). If the hand-back fails too, the editor is
+destroyed, and the earlier objects' methods throw `EditorStartFailedError` with the reason in `cause` —
+start the editor again with a new `init()`. Aborting the earlier call's `signal` after a new call came
+in leaves the editor alone.
 
-If the new `init()` fails to start (it failed or was cancelled via `signal`), the editor is handed back
-to the earlier owner: with its own options and its email restored from a snapshot (text and header;
-undo history is cleared). If the hand-back fails too, the editor is destroyed, and the earlier
-instance's methods throw `EditorStartFailedError` with the reason in `cause` — start the editor again
-with a new `init()`.
+`init()` into a **different** container starts a new editor.
 
 ### Content
 
@@ -629,7 +659,7 @@ See typings (**`ExportedApi.DataMixin.Events`**) — includes for example **`han
 | handleDestroy             | Destroy lifecycle                    |
 | handleLoad                | Instance ready hook                  |
 | handleLoadImage           | Image upload helpers & proxies       |
-| handleNotify              | Generic notification. Among errors: `TEMPLATE_READ_ERROR` (`data: { templateId }`) — the template named by `templateId` could not be read and the email opened without it. Sent once per template for the editor's lifetime; the event has no title and the editor shows no toast for it — show your own if the user should know. |
+| handleNotify              | Generic notification. Among warnings (`type: 'warning'`): `TEMPLATE_READ_ERROR` (`data: { templateId }`) — the template named by `templateId` could not be read and the email opened without it. Sent once per template for the editor's lifetime and never to `handleError`; the event has no title and the editor shows no toast for it — show your own if the user should know. |
 | handleError               | Error toast hook                     |
 | handleSuccess             | Success toast hook                   |
 | handleTestEmailSend       | Send test mail                       |