# Image Extension

## Example

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

	let editor = $state<Readable<SvelteTiptap.Editor>>();
	let errorMessage = $state('');

	async function fakeUpload(
		file: File,
		onProgress: (p: number) => void,
		signal: AbortSignal
	): Promise<string> {
		// Read the actual file as a data URL so the same image is shown after "upload"
		const dataUrl = await new Promise<string>((resolve, reject) => {
			const reader = new FileReader();
			reader.onload = () => resolve(reader.result as string);
			reader.onerror = () => reject(new Error('Failed to read file'));
			reader.readAsDataURL(file);
		});

		// Simulate upload progress
		return new Promise((resolve, reject) => {
			let progress = 0;
			const interval = setInterval(() => {
				progress += 0.1;
				onProgress(Math.min(progress, 1));
				if (progress >= 1) {
					clearInterval(interval);
					resolve(dataUrl);
				}
			}, 200);
			signal.addEventListener('abort', () => {
				clearInterval(interval);
				reject(new Error('Upload cancelled'));
			});
		});
	}
</script>

<Box class="not-prose">
	<CoreRichTextEditor
		bind:editor
		placeholder="Paste or drop an image..."
		extraExtensions={[
			ImageExtension.configure({
				upload: fakeUpload,
				imageComponent: EditableImage,
				onError: (err) => {
					errorMessage = err.message;
				}
			})
		]}
		class="min-h-24"
	/>

	<div class="mt-2 flex items-center gap-2">
		<Button
			onclick={() => {
				if ($editor) {
					pickAndInsertImage($editor);
				}
			}}
		>
			Add Image
		</Button>

		{#if errorMessage}
			<span class="text-sm text-red-500">{errorMessage}</span>
		{/if}
	</div>
</Box>
```

## Documentation

## Usage

Add `ImageExtension` via `extraExtensions` with an `upload` function. Images can then be pasted, dropped, or inserted programmatically.

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

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

	async function upload(file: File, onProgress: (p: number) => void, signal: AbortSignal) {
		const res = await fetch('/api/upload', { method: 'POST', body: file, signal });
		return (await res.json()).url;
	}
</script>

<CoreRichTextEditor
	bind:editor
	extraExtensions={[ImageExtension.configure({ upload })]}
/>
```

That's it — paste or drag-drop an image and it will upload automatically.

## Programmatic insertion

Use `pickAndInsertImage` to open a file picker, or `insertImage` to insert a file directly. Great for toolbar buttons or slash menu items.

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

<!-- File picker button -->
<button onclick={() => pickAndInsertImage($editor)}>Add Image</button>

<!-- Insert a file you already have -->
<button onclick={() => insertImage($editor, myFile)}>Insert</button>
```

## Slash menu integration

Add an image item to `SlashMenu` for a `/image` command.

```svelte
<SlashMenu
	editor={$editor}
	items={[
		{
			id: 'image',
			label: 'Image',
			command: ({ editor, range }) => {
				editor.chain().focus().deleteRange(range).run();
				pickAndInsertImage(editor);
			}
		}
	]}
/>
```

## Editable alt text

Use the built-in `EditableImage` component to let users edit alt text. It shows a pencil button on hover that opens a modal with a textarea.

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

<CoreRichTextEditor
	extraExtensions={[
		ImageExtension.configure({
			upload: myUpload,
			imageComponent: EditableImage
		})
	]}
/>
```

## Custom image component

Pass `imageComponent` to replace the default `<img>` rendering with your own Svelte component. Your component receives tiptap's `NodeViewProps` — use `props.node.attrs.src` for the image URL and `props.updateAttributes()` to update node data.

```svelte
<!-- CustomImage.svelte -->
<script lang="ts">
	import type { NodeViewProps } from '@tiptap/core';
	import { NodeViewWrapper } from 'svelte-tiptap';

	let props: NodeViewProps = $props();
</script>

<NodeViewWrapper>
	<figure class="my-4">
		<img
			src={props.node.attrs.src}
			alt={props.node.attrs.alt}
			class="rounded-lg shadow-md"
		/>
		{#if props.node.attrs.alt}
			<figcaption class="mt-1 text-sm text-gray-500">{props.node.attrs.alt}</figcaption>
		{/if}
	</figure>
</NodeViewWrapper>
```

```svelte
<script lang="ts">
	import { ImageExtension } from '@foxui/text';
	import CustomImage from './CustomImage.svelte';
</script>

<CoreRichTextEditor
	extraExtensions={[
		ImageExtension.configure({
			upload: myUpload,
			imageComponent: CustomImage
		})
	]}
/>
```

## How it works

`ImageExtension` is a single tiptap Extension that bundles everything:

- **`@tiptap/extension-image`** for rendering final `<img>` elements
- **Upload placeholder node** with a Svelte NodeView showing a preview and progress bar
- **ProseMirror plugins** for `handlePaste` and `handleDrop` — no external DOM handlers needed
- **Extension storage** with a runtime `Map` so `File` objects reach the upload function (node attributes stay serializable)

When an image is inserted, a blob preview is shown immediately. The `upload` function runs in the background. Once it resolves, the placeholder is replaced with a final image using the **returned URL**.

## Works with any editor

`ImageExtension` works with `CoreRichTextEditor`, `RichTextEditor`, or any tiptap editor that supports `extraExtensions`.

## Sources

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

## API Reference

### ImageExtension
A tiptap Extension that bundles image display, upload placeholders, and paste/drop handling. Add via extraExtensions.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| upload | `(file: File, onProgress: (p: number) => void, signal: AbortSignal) => Promise<string>` | `-` | Upload function. Receives the file, a progress callback (0–1), and an AbortSignal. Must return the final image URL. (required) |
| accept | `string` | `'image/*'` | Accepted file types for the file picker and validation. |
| maxFileSize | `number` | `0` | Maximum file size in bytes. 0 means unlimited. |
| onError | `(error: Error) => void` | `-` | Called when an upload fails or a file is rejected. |
| HTMLAttributes | `Record<string, string>` | `{}` | HTML attributes applied to final <img> elements. |
| imageComponent | `Component` | `-` | Custom Svelte component for rendering final images. Receives NodeViewProps from tiptap (node.attrs.src, node.attrs.alt, etc.). |

### EditableImage
A pre-built image component with alt text editing. Shows a pencil button on hover that opens a modal with a textarea. Use as imageComponent option.

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

### pickAndInsertImage
Helper function that opens a native file picker and inserts the selected image into the editor.

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

### insertImage
Helper function that inserts a file directly as an uploading image into the editor.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Editor` | `-` | The tiptap editor instance. (required) |
| file | `File` | `-` | The image file to upload. (required) |

### ImageUploadFn
Type signature for the upload function.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| file | `File` | `-` | The image file to upload. (required) |
| onProgress | `(progress: number) => void` | `-` | Progress callback. Values range from 0 to 1. (required) |
| abortSignal | `AbortSignal` | `-` | Signal to abort the upload when the placeholder is deleted. (required) |