# Link Extension

## Example

```svelte
<script lang="ts">
	import { CoreRichTextEditor, FormattingBubbleMenu, Box, type SvelteTiptap } from '@foxui/all';
	import type { Readable } from 'svelte/store';

	let editor = $state<Readable<SvelteTiptap.Editor>>();
</script>

<Box class="not-prose">
	<CoreRichTextEditor bind:editor class="min-h-24">
		{#if $editor}
			<FormattingBubbleMenu {editor} />
		{/if}
	</CoreRichTextEditor>
</Box>
```

## Documentation

## Usage

`CoreRichTextEditor` includes `LinkExtension` by default. Pasted and typed URLs are automatically converted to links, and Markdown syntax `[text](url)` is supported out of the box.

```svelte
<CoreRichTextEditor />
```

`FormattingBubbleMenu` automatically includes a `LinkPopover` when the link extension is detected — no extra setup needed.

```svelte
<CoreRichTextEditor bind:editor>
	<FormattingBubbleMenu {editor} />
</CoreRichTextEditor>
```

## Standalone link popover

`LinkPopover` is a toggle button with a popover for editing URLs. It follows the same pattern as `BoldToggle` / `ItalicToggle` — drop it into any toolbar.

```svelte
<LinkPopover {editor} />
```

## Reacting to new links

Use the `onlinkadded` callback to run logic whenever a link is added — whether by typing, pasting, autolink, or the link popover.

Via `CoreRichTextEditor` (uses default extensions):

```svelte
<CoreRichTextEditor
	onlinkadded={({ href, text }) => {
		console.log(`Link added: ${text} → ${href}`);
	}}
/>
```

Or configure it directly on the extension:

```svelte
<CoreRichTextEditor
	extensions={[
		StarterKit.configure({ link: false }),
		LinkExtension.configure({
			onlinkadded: ({ href, text, editor }) => {
				// fetch preview, validate, transform, etc.
			}
		})
	]}
/>
```

## Programmatic usage

```ts
import { setLink, removeLink } from '@foxui/text';

// Set a link on the current selection
setLink(editor, 'https://example.com');

// Remove link from the current selection
removeLink(editor);
```

## How it works

`LinkExtension` wraps `@tiptap/extension-link` with:

- **Autolink** — URLs typed or pasted are automatically detected and linked
- **Markdown syntax** — `[text](url "title")` input and paste rules, with `title` attribute support
- **Configurable** — toggle autolink, markdown, open-on-click behavior, default protocol

`LinkPopover` tracks the current selection via editor transactions. When the selection is inside a link, the toggle is pressed and clicking it opens the popover pre-filled with the current URL.

## Sources

Based on "TipTap" (https://tiptap.dev/docs/editor/extensions/marks/link)

## API Reference

### LinkExtension
A tiptap Extension that bundles link detection, autolink, and optional Markdown syntax. Add via extraExtensions.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| openOnClick | `boolean | 'whenNotEditable'` | `'whenNotEditable'` | Whether clicking a link opens it. |
| autolink | `boolean` | `true` | Automatically detect and linkify URLs as you type. |
| defaultProtocol | `string` | `'https'` | Protocol added to URLs without one. |
| markdown | `boolean` | `true` | Enable Markdown link syntax [text](url "title"). |
| HTMLAttributes | `Record<string, string>` | `{}` | HTML attributes applied to link elements. |
| onlinkadded | `(event: LinkAddedEvent) => void` | `-` | Called whenever a link is added to the editor (via typing, pasting, autolink, or UI). Receives { href, text, editor }. |

### LinkPopover
A toggle button with a popover for setting, editing, or removing links on the current selection. Works standalone, in a bubble menu, or in any toolbar.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Readable<Editor>` | `-` | The editor store. (required) |
| class | `string` | `-` | CSS classes for the popover content. |

### setLink
Helper function to set a link on the current selection. Unsets the link if URL is empty.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Editor` | `-` | The tiptap editor instance. (required) |
| url | `string` | `-` | The URL to set. (required) |

### removeLink
Helper function to remove the link from the current selection.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Editor` | `-` | The tiptap editor instance. (required) |