feat(editor): link plugin no longer invoke window but instead expose onClick handler

cdskill · cdskill · commit a55bef93cee2 · 2026-06-16T23:26:36.000+02:00
diff --git a/apps/docs/src/app/playground/link.spec.ts b/apps/docs/src/app/playground/link.spec.ts
@@ -0,0 +1,116 @@
+import {
+  LINK_PLUGIN_DEFAULT_OPTIONS,
+  LinkPlugin,
+  createQalmaEditor,
+} from '@qalma/editor';
+import type {
+  LinkClickEvent,
+  QalmaEditorController,
+  QalmaPlugin,
+} from '@qalma/editor';
+import { describe, expect, it } from 'vitest';
+
+const LINK_CONTENT =
+  '<p><a href="https://angular.dev" target="_blank" rel="noopener noreferrer">Angular</a></p>';
+
+describe('LinkPlugin', () => {
+  it('exposes configurable link click defaults and validation', () => {
+    const onClick = (): void => undefined;
+    const configured = LinkPlugin.configure({ onClick });
+
+    expect(LINK_PLUGIN_DEFAULT_OPTIONS).toEqual({
+      allowedProtocols: ['http', 'https', 'mailto', 'tel'],
+      allowRelativeLinks: true,
+      defaultTarget: '_blank',
+      defaultRel: 'noopener noreferrer',
+      onClick: null,
+    });
+    expect(LinkPlugin.options).toEqual(LINK_PLUGIN_DEFAULT_OPTIONS);
+    expect(configured.options.onClick).toBe(onClick);
+    expect(() =>
+      LinkPlugin.configure({
+        onClick: 'open' as never,
+      }),
+    ).toThrow('LinkPlugin onClick must be a function or null.');
+  });
+
+  it('leaves link click navigation to consumer-owned behavior', () => {
+    const defaultMounted = mountLinkEditor([LinkPlugin]);
+    const defaultEvent = new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+    });
+
+    try {
+      expect(defaultMounted.link.dispatchEvent(defaultEvent)).toBe(true);
+      expect(defaultEvent.defaultPrevented).toBe(false);
+    } finally {
+      defaultMounted.editor.unmount(defaultMounted.host);
+      defaultMounted.host.remove();
+    }
+
+    const captured: LinkClickEvent[] = [];
+    const configuredMounted = mountLinkEditor([
+      LinkPlugin.configure({
+        onClick: (event) => {
+          captured.push(event);
+        },
+      }),
+    ]);
+    const configuredEvent = new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+    });
+
+    try {
+      expect(configuredMounted.link.dispatchEvent(configuredEvent)).toBe(false);
+      expect(configuredEvent.defaultPrevented).toBe(true);
+
+      const [linkClick] = captured;
+
+      if (!linkClick) {
+        throw new Error('Expected link click event.');
+      }
+
+      expect(linkClick.event).toBe(configuredEvent);
+      expect(linkClick.element).toBe(configuredMounted.link);
+      expect(linkClick.href).toBe('https://angular.dev');
+      expect(linkClick.target).toBe('_blank');
+      expect(linkClick.rel).toBe('noopener noreferrer');
+      expect(linkClick.text).toBe('Angular');
+    } finally {
+      configuredMounted.editor.unmount(configuredMounted.host);
+      configuredMounted.host.remove();
+    }
+  });
+});
+
+function mountLinkEditor(plugins: readonly QalmaPlugin[]): {
+  editor: QalmaEditorController;
+  host: HTMLElement;
+  link: HTMLAnchorElement;
+} {
+  const editor = createQalmaEditor({
+    content: LINK_CONTENT,
+    plugins,
+  });
+  const host = document.createElement('div');
+
+  document.body.append(host);
+  editor.mount(host);
+
+  const link = host.querySelector<HTMLAnchorElement>('a[href]');
+
+  if (!link) {
+    editor.unmount(host);
+    host.remove();
+
+    throw new Error('Expected editor link.');
+  }
+
+  return {
+    editor,
+    host,
+    link,
+  };
+}
diff --git a/apps/docs/src/content/docs/link.md b/apps/docs/src/content/docs/link.md
@@ -19,12 +19,12 @@ const editor = createQalmaEditor({
 
 ## Commands and query
 
-| Contract | Description |
-| -------- | ----------- |
-| `setLink` | Applies a link to the selection or stores it for future typed text. |
-| `selectLink` | Selects an existing link by current state, document range, or anchor element. |
-| `unsetLink` | Removes the active link mark. |
-| `query&lt;LinkState&gt;('link')` | Returns link range, attributes, and text for the active or selected link. |
+| Contract                         | Description                                                                   |
+| -------------------------------- | ----------------------------------------------------------------------------- |
+| `setLink`                        | Applies a link to the selection or stores it for future typed text.           |
+| `selectLink`                     | Selects an existing link by current state, document range, or anchor element. |
+| `unsetLink`                      | Removes the active link mark.                                                 |
+| `query&lt;LinkState&gt;('link')` | Returns link range, attributes, and text for the active or selected link.     |
 
 `setLink` accepts a string or an object.
 
@@ -64,17 +64,19 @@ const editor = createQalmaEditor({
       allowRelativeLinks: true,
       defaultTarget: '_blank',
       defaultRel: 'noopener noreferrer',
+      onClick: null,
     }),
   ],
 });
 ```
 
-| Option | Default | Description |
-| ------ | ------- | ----------- |
-| `allowedProtocols` | `['http', 'https', 'mailto', 'tel']` | Protocol allow-list. Entries are names without `:`. |
-| `allowRelativeLinks` | `true` | Allows links without a protocol. |
-| `defaultTarget` | `'_blank'` | Applied when command values or pasted DOM do not provide a target. Only `'_blank'` is preserved. |
-| `defaultRel` | `'noopener noreferrer'` | Applied when command values or pasted DOM do not provide `rel`. Empty strings become `null`. |
+| Option               | Default                              | Description                                                                                                                           |
+| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowedProtocols`   | `['http', 'https', 'mailto', 'tel']` | Protocol allow-list. Entries are names without `:`.                                                                                   |
+| `allowRelativeLinks` | `true`                               | Allows links without a protocol.                                                                                                      |
+| `defaultTarget`      | `'_blank'`                           | Applied when command values or pasted DOM do not provide a target. Only `'_blank'` is preserved.                                      |
+| `defaultRel`         | `'noopener noreferrer'`              | Applied when command values or pasted DOM do not provide `rel`. Empty strings become `null`.                                          |
+| `onClick`            | `null`                               | Optional callback for editor link clicks. When configured, Qalma prevents the native click and passes the link event to the host app. |
 
 Invalid or empty hrefs make `setLink` return `false`.
 
@@ -118,10 +120,36 @@ editor.execute('selectLink', { from: link.from, to: link.to });
 
 ## Click behavior
 
-The plugin handles clicks on editor links. It prevents the editor click,
-normalizes the href with the same options, and opens `_blank` links with
-`window.open(href, '_blank', 'noopener,noreferrer')`. Other links assign
-`window.location.href`.
+The plugin does not navigate on editor link clicks by default. Navigation,
+routing, analytics, previews, and confirmation flows stay in your app.
 
-If your product needs a different link-click policy, wrap the editor or build a
-custom plugin that handles those DOM events first.
+Configure `onClick` when you want Qalma to turn editor link clicks into a
+consumer-owned event. Qalma normalizes the href with the same options, prevents
+the native click, and passes the DOM event, anchor element, href, target, rel,
+and text to your callback.
+
+```typescript
+import { LinkClickHandler, LinkPlugin } from '@qalma/editor';
+
+const handleLinkClick: LinkClickHandler = ({ href, target }) => {
+  if (target === '_blank') {
+    window.open(href, '_blank', 'noopener,noreferrer');
+
+    return;
+  }
+
+  window.location.assign(href);
+};
+
+const editor = createQalmaEditor({
+  plugins: [
+    LinkPlugin.configure({
+      onClick: handleLinkClick,
+    }),
+  ],
+});
+```
+
+That example intentionally keeps navigation in application code. A routed
+Angular app can call its router, open a product-specific preview, or ignore the
+click entirely.
diff --git a/apps/sandbox/src/app/app.spec.ts b/apps/sandbox/src/app/app.spec.ts
@@ -1142,13 +1142,15 @@ describe('App', () => {
       allowRelativeLinks: true,
       defaultTarget: '_blank',
       defaultRel: 'noopener noreferrer',
+      onClick: null,
     });
     expect(LinkPlugin.options).toEqual(LINK_PLUGIN_DEFAULT_OPTIONS);
     expect(configured.options).toEqual({
       allowedProtocols: ['http', 'https', 'mailto', 'tel'],
       allowRelativeLinks: false,
       defaultTarget: '_blank',
       defaultRel: 'noopener noreferrer',
+      onClick: null,
     });
     expect(() =>
       LinkPlugin.configure({
@@ -1157,6 +1159,11 @@ describe('App', () => {
     ).toThrowError(
       'LinkPlugin allowedProtocols must include at least one protocol.',
     );
+    expect(() =>
+      LinkPlugin.configure({
+        onClick: 'open' as never,
+      }),
+    ).toThrowError('LinkPlugin onClick must be a function or null.');
   });
 
   it('should expose configurable image defaults and validation', () => {
diff --git a/libs/editor/README.md b/libs/editor/README.md
@@ -112,7 +112,7 @@ plugin instance with merged options, e.g.
 | `ListsPlugin`                                                                         | `toggleBulletList`, `toggleOrderedList`, `splitListItem`, `liftListItem`, `sinkListItem`                         |
 | `TaskListPlugin`                                                                      | `toggleTaskList`, `toggleTaskItemChecked`, `setTaskItemChecked`, `splitTaskItem`, `liftTaskItem`, `sinkTaskItem` |
 | `CodeBlockPlugin`                                                                     | `toggleCodeBlock`, `setCodeBlockLanguage`                                                                        |
-| `LinkPlugin`                                                                          | `setLink`, `unsetLink`                                                                                           |
+| `LinkPlugin`                                                                          | `setLink`, `selectLink`, `unsetLink`                                                                             |
 | `ImagePlugin`                                                                         | `insertImage`, `updateImage`                                                                                     |
 | `MentionPlugin`                                                                       | `insertMention`                                                                                                  |
 | `SlashCommandPlugin`                                                                  | `deleteSlashCommand`, `dismissSlashCommand`                                                                      |
@@ -130,7 +130,7 @@ Read each plugin's source under `src/lib/plugins` for configuration options
 (e.g. `HeadingsPlugin.configure({ levels: [1, 2, 3] })`,
 `MentionPlugin.configure({ trigger: '@' })`,
 `SlashCommandPlugin.configure({ trigger: '/' })`,
-`LinkPlugin.configure({ allowedProtocols: [...] })`).
+`LinkPlugin.configure({ allowedProtocols: [...], onClick })`).
 
 ## Learn more
 
diff --git a/libs/editor/src/lib/plugins/link.ts b/libs/editor/src/lib/plugins/link.ts
