# Embed Extension

## Example

```svelte
<script lang="ts">
	import {
		CoreRichTextEditor,
		EmbedExtension,
		EmbedModal,
		youtubeEmbed,
		Box,
		Button,
		openEmbedModal,
		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
		placeholder="Paste a YouTube URL to see it embed..."
		extraExtensions={[
			EmbedExtension.configure({
				embeds: [youtubeEmbed]
			})
		]}
		class="min-h-24"
	>
		{#if $editor}
			<EmbedModal editor={$editor} />
		{/if}
	</CoreRichTextEditor>
	<div class="mt-2">
		<Button
			onclick={() => {
				if ($editor) openEmbedModal($editor);
			}}
		>
			Add Embed
		</Button>
	</div>
</Box>
```

## Documentation

## Usage

Add `EmbedExtension` via `extraExtensions` with an array of embed definitions. URLs pasted or typed on their own line will automatically convert to rich embeds.

```svelte
<script lang="ts">
	import { CoreRichTextEditor, EmbedExtension, youtubeEmbed } from '@foxui/text';
</script>

<CoreRichTextEditor
	extraExtensions={[
		EmbedExtension.configure({
			embeds: [youtubeEmbed]
		})
	]}
/>
```

That's it — paste a YouTube URL and it becomes an embedded player.

## How detection works

1. **Paste** — When a URL is pasted as plain text, it's checked against all embed matchers. If one matches, an embed node is inserted immediately.
2. **Typed URLs** — When the user types a URL and moves to the next line (e.g. presses Enter), the link-only paragraph is detected and converted.

## Built-in YouTube embed

The `youtubeEmbed` definition matches common YouTube URL formats:

- `https://www.youtube.com/watch?v=VIDEO_ID`
- `https://youtu.be/VIDEO_ID`
- `https://www.youtube.com/embed/VIDEO_ID`
- `https://www.youtube.com/shorts/VIDEO_ID`

## Embed modal

Add `EmbedModal` as a child of the editor to let users manually insert embeds via a URL input dialog. It validates the URL against all registered embeds and shows an error if none match.

```svelte
<script lang="ts">
	import { CoreRichTextEditor, EmbedExtension, EmbedModal, youtubeEmbed, openEmbedModal } from '@foxui/text';
</script>

<CoreRichTextEditor bind:editor extraExtensions={[EmbedExtension.configure({ embeds: [youtubeEmbed] })]}>
	{#if $editor}
		<EmbedModal editor={$editor} />
	{/if}
</CoreRichTextEditor>

<!-- Trigger from a button -->
<button onclick={() => openEmbedModal($editor)}>Add Embed</button>
```

The modal is also available from the slash menu — type `/embed` to open it.

You can also control the modal directly with a bindable `open` prop:

```svelte
<EmbedModal editor={$editor} bind:open={embedModalOpen} />
<button onclick={() => embedModalOpen = true}>Add Embed</button>
```

## Programmatic insertion

Use `insertEmbed` to insert an embed from a URL without the modal. Returns `null` on success or an error string.

```typescript
import { insertEmbed } from '@foxui/text';

const error = insertEmbed($editor, 'https://www.youtube.com/watch?v=dQw4w9WgXcQ');
if (error) console.error(error);
```

## Custom embeds

Create your own embed by defining a `name`, a `match` function, and a Svelte `component`:

```typescript
import type { EmbedDefinition } from '@foxui/text';
import SpotifyPlayer from './SpotifyPlayer.svelte';

const spotifyEmbed: EmbedDefinition = {
	name: 'spotify',
	match: (url) => {
		const m = url.match(/open\.spotify\.com\/track\/(\w+)/);
		return m ? { trackId: m[1] } : false;
	},
	component: SpotifyPlayer
};
```

Your component receives three props:

```svelte
<!-- SpotifyPlayer.svelte -->
<script lang="ts">
	let { url, data, selected }: { url: string; data: Record<string, any>; selected: boolean } =
		$props();
</script>

<iframe
	src="https://open.spotify.com/embed/track/{data.trackId}"
	class="h-20 w-full rounded-lg {selected ? 'ring-2 ring-accent-500' : ''}"
	allow="encrypted-media"
></iframe>
```

Then add it alongside the built-in embeds:

```svelte
<CoreRichTextEditor
	extraExtensions={[
		EmbedExtension.configure({
			embeds: [youtubeEmbed, spotifyEmbed]
		})
	]}
/>
```

## Multiple embed providers

Pass as many embed definitions as you like. The first match wins — order matters.

```typescript
EmbedExtension.configure({
	embeds: [youtubeEmbed, spotifyEmbed, vimeoEmbed, twitterEmbed]
})
```

## Sources

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

## API Reference

### EmbedExtension
A tiptap Extension that auto-detects URLs in paragraphs and replaces them with rich embeds. Add via extraExtensions.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| embeds | `EmbedDefinition[]` | `[]` | Array of embed definitions. Each definition has a name, match function, and component. |

### EmbedDefinition
Defines an embed provider with URL matching and a rendering component.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| name | `string` | `-` | Unique name for this embed type (e.g. "youtube", "spotify"). (required) |
| match | `(url: string) => Record<string, any> | false | null` | `-` | URL matcher. Return an object with embed-specific data if the URL matches, or false/null to skip. (required) |
| component | `Component` | `-` | Svelte component to render the embed. Receives props: url (string), data (object from match), selected (boolean). (required) |

### EmbedModal
Modal dialog for manually inserting an embed by URL. Add as a child of the editor. Automatically registers with the slash menu.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Editor` | `-` | The tiptap editor instance. (required) |
| open | `boolean` | `false` | Bindable. Controls modal visibility. |

### insertEmbed
Programmatically insert an embed for a URL. Returns null on success or an error string.

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

### openEmbedModal
Opens the EmbedModal if one is mounted. Used by the slash menu and can be called from custom buttons.

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

### youtubeEmbed
Built-in YouTube embed definition. Matches youtube.com/watch, youtu.be, youtube.com/embed, and youtube.com/shorts URLs.

| Prop | Type | Default | Description |
|------|------|---------|-------------|