Make Quill instances detachable and reconfigurable

packages/quill/src/core/quill.ts

@@ -18,7 +18,7 @@ import type { DebugLevel } from './logger.js';
 import Module from './module.js';
 import Selection, { Range } from './selection.js';
 import type { Bounds } from './selection.js';
-import { createSubscriber, getSubscriber } from './subscriber.js';
+import { getSubscriber } from './subscriber.js';
 import Composition from './composition.js';
 import Theme from './theme.js';
 import type { ThemeConstructor } from './theme.js';
@@ -230,7 +230,6 @@ class Quill {
       instances.set(this.container, this);
       this.root = this.addContainer('ql-editor');
       this.root.classList.add('ql-blank');
-      createSubscriber(this.root);
       this.emitter = new Emitter();
     }
     const scrollBlotName = Parchment.ScrollBlot.blotName;

packages/quill/src/core/subscriber.ts

@@ -1,3 +1,7 @@
+import logger from './logger.js';
+
+const debug = logger('quill:subscriber');
+
 /**
  * Any object with a named constructor can request an event subscription.
  */
@@ -20,25 +24,16 @@ interface Subscription {
 
 const subscribers = new WeakMap<object, Subscriber>();
 
-/**
- * Creates a Subscriber instance, and binds it to an object.
- */
-export function createSubscriber(object: Source): Subscriber {
-  const subscriber = new Subscriber();
-  subscribers.set(object, subscriber);
-  return subscriber;
-}
-
 /**
  * Gets the Subscriber instance bound to the given object.
- * Throws an error if the binding does not exist.
+ * Creates a new one if the binding does not exist yet.
  */
 export function getSubscriber(object: Source): Subscriber {
-  const subscriber = subscribers.get(object);
+  let subscriber = subscribers.get(object);
   if (!subscriber) {
-    throw new Error(
-      `Subscriber not found for object ${object.constructor.name}`,
-    );
+    debug.info(`Creating new Subscriber for ${object.constructor.name}`);
+    subscriber = new Subscriber();
+    subscribers.set(object, subscriber);
   }
   return subscriber;
 }

packages/quill/test/unit/__helpers__/factory.ts

@@ -10,7 +10,6 @@ import ListItem, { ListContainer } from '../../../src/formats/list.js';
 import Inline from '../../../src/blots/inline.js';
 import Emitter from '../../../src/core/emitter.js';
 import { normalizeHTML } from './utils.js';
-import { createSubscriber } from '../../../src/core/subscriber.js';
 
 export const createRegistry = (formats: unknown[] = []) => {
   const registry = new Registry();
@@ -38,7 +37,6 @@ export const createScroll = (
   const emitter = new Emitter();
   const root = container.appendChild(document.createElement('div'));
   root.innerHTML = normalizeHTML(html);
-  createSubscriber(root);
   const scroll = new Scroll(registry, root, { emitter });
   return scroll;
 };

packages/quill/test/unit/blots/scroll.spec.ts

@@ -8,17 +8,13 @@ import { createRegistry } from '../__helpers__/factory.js';
 import { normalizeHTML, sleep } from '../__helpers__/utils.js';
 import Underline from '../../../src/formats/underline.js';
 import Strike from '../../../src/formats/strike.js';
-import {
-  createSubscriber,
-  getSubscriber,
-} from '../../../src/core/subscriber.js';
+import { getSubscriber } from '../../../src/core/subscriber.js';
 
 const createScroll = (html: string) => {
   const emitter = new Emitter();
   const registry = createRegistry([Underline, Strike]);
   const container = document.body.appendChild(document.createElement('div'));
   container.innerHTML = normalizeHTML(html);
-  createSubscriber(container);
   return new Scroll(registry, container, { emitter });
 };
 

packages/quill/test/unit/core/composition.spec.ts

@@ -4,14 +4,11 @@ import Scroll from '../../../src/blots/scroll.js';
 import { describe, expect, test, vitest } from 'vitest';
 import { createRegistry } from '../__helpers__/factory.js';
 import Quill from '../../../src/core.js';
-import { createSubscriber } from '../../../src/core/subscriber.js';
 
 describe('Composition', () => {
   test('triggers events on compositionstart', async () => {
     const emitter = new Emitter();
-    const container = document.createElement('div');
-    createSubscriber(container);
-    const scroll = new Scroll(createRegistry(), container, {
+    const scroll = new Scroll(createRegistry(), document.createElement('div'), {
       emitter,
     });
     new Composition(scroll, emitter);

packages/quill/test/unit/core/editor.spec.ts

@@ -27,7 +27,6 @@ import IndentClass from '../../../src/formats/indent.js';
 import { ColorClass } from '../../../src/formats/color.js';
 import Quill from '../../../src/core.js';
 import { normalizeHTML } from '../__helpers__/utils.js';
-import { createSubscriber } from '../../../src/core/subscriber.js';
 
 const createEditor = (html: string) => {
   const container = document.createElement('div');
@@ -881,10 +880,8 @@ describe('Editor', () => {
 
       const registry = new Registry();
       registry.register(MyBlot, Block, Break, Text);
-      const container = document.createElement('div');
-      createSubscriber(container);
       const editor = new Editor(
-        new Scroll(registry, container, {
+        new Scroll(registry, document.createElement('div'), {
           emitter: new Emitter(),
         }),
       );

packages/quill/test/unit/core/subscriber.spec.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, test, vitest } from 'vitest';
-import { createSubscriber, getSubscriber } from '../../../src/core/subscriber';
+import logger from '../../../src/core/logger.js';
+import { getSubscriber } from '../../../src/core/subscriber.js';
 
 describe('Subscriber', () => {
   class Test {}
@@ -9,23 +10,31 @@ describe('Subscriber', () => {
     object = new Test();
   });
 
-  describe('registration', () => {
+  describe('getSubscriber()', () => {
     test('maps a Subscriber to an object', () => {
-      const subscriber = createSubscriber(object);
-      expect(subscriber).toBeTruthy();
+      const subscriber = getSubscriber(object);
       expect(getSubscriber(object)).toBe(subscriber);
+      expect(getSubscriber(new Test())).not.toBe(subscriber);
     });
 
-    test('throws an error if no Subscriber is bound to an object', () => {
-      expect(() => getSubscriber(object)).toThrow(
-        'Subscriber not found for object Test',
+    test('logs the creation of a new Subscriber instance', () => {
+      logger.level('info');
+      vitest.spyOn(console, 'info');
+      getSubscriber(object);
+      expect(console.info).toHaveBeenCalledWith(
+        'quill:subscriber',
+        'Creating new Subscriber for Test',
       );
+      getSubscriber(object);
+      expect(console.info).toHaveBeenCalledTimes(1);
+      getSubscriber(new Test());
+      expect(console.info).toHaveBeenCalledTimes(2);
     });
   });
 
   describe('on()', () => {
     test('calls addEventListener on the target', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const source = new Test();
       const target = document.createElement('div');
       const event = 'keydown';
@@ -41,7 +50,7 @@ describe('Subscriber', () => {
     });
 
     test('keeps track of the subscription', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const source = new Test();
       const target = document.createElement('div');
       const event = 'keydown';
@@ -56,7 +65,7 @@ describe('Subscriber', () => {
 
   describe('off()', () => {
     test('calls removeEventListener on the target', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const target = document.createElement('div');
       const event = 'keydown';
       const handler = () => {};
@@ -71,7 +80,7 @@ describe('Subscriber', () => {
     });
 
     test('forgets the subscription', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const source = new Test();
       const target = document.createElement('div');
       const event = 'keydown';
@@ -85,7 +94,7 @@ describe('Subscriber', () => {
 
   describe('removeSourceListeners()', () => {
     test('removes all listeners related to a source', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const source1 = new Test();
       const source2 = new Test();
       const target1 = document.createElement('div');
@@ -110,7 +119,7 @@ describe('Subscriber', () => {
 
   describe('removeAllListeners()', () => {
     test('removes all listeners', () => {
-      const subscriber = createSubscriber(object);
+      const subscriber = getSubscriber(object);
       const source1 = new Test();
       const source2 = new Test();
       const target1 = document.createElement('div');

packages/quill/test/unit/ui/picker.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'vitest';
 import Picker from '../../../src/ui/picker.js';
-import { createSubscriber } from '../../../src/core/subscriber.js';
+import { getSubscriber } from '../../../src/core/subscriber.js';
 
 describe('Picker', () => {
   const setup = () => {
@@ -9,7 +9,7 @@ describe('Picker', () => {
       '<select><option selected>0</option><option value="1">1</option></select>';
     const pickerSelectorInstance = new Picker(
       container.firstChild as HTMLSelectElement,
-      createSubscriber(container),
+      getSubscriber(container),
     );
     const pickerSelector = container.querySelector('.ql-picker') as HTMLElement;
     return { container, pickerSelectorInstance, pickerSelector };

packages/website/content/docs/api.mdx

@@ -21,6 +21,28 @@ title: API
 
 ## Content
 
+### configure
+
+Applies a new [configuration](/docs/configuration/) to an existing instance of Quill.
+
+**Methods**
+
+```typescript
+configure(options: QuillOptions = {}): void
+```
+
+**Example 1**
+
+```typescript
+quill.configure();
+```
+
+**Example 2**
+
+```typescript
+quill.configure({ theme: 'bubble', readOnly: true });
+```
+
 ### deleteText
 
 Deletes text from the editor, returning a [Delta](/docs/delta/) representing the change. [Source](/docs/api/#events) may be `"user"`, `"api"`, or `"silent"`. Calls where the `source` is `"user"` when the editor is [disabled](#disable) are ignored.
@@ -59,6 +81,22 @@ document.querySelector('#deleteButton').addEventListener('click', () => {
   }}
 />
 
+### detach
+
+Deactivates a Quill instance by removing all event subscriptions. Useful to cleanup the environment and prevent memory leaks.
+
+**Methods**
+
+```typescript
+detach(): void
+```
+
+**Examples**
+
+```typescript
+quill.detach();
+```
+
 ### getContents
 
 Retrieves contents of the editor, with formatting data, represented by a [Delta](/docs/delta/) object.