svelte-rtf-editor 1.3.0 → 1.4.0

package/README.md

@@ -13,6 +13,7 @@ RTF viewer and rich-text editor components for **Svelte 5**.
 - **`InkEditor`** — Full rich-text editor that reads and writes RTF, built on `contenteditable`
   - Formatting toolbar: bold, italic, underline, strikethrough, font colour
   - Block-level controls: headings (H1–H3), paragraph, blockquote, code block
+  - Images: upload, paste or drag-and-drop, with a description below each picture, drag-to-resize and left/centre/right placement — embedded in the RTF, not linked
   - Import an RTF file from disk; export as RTF, HTML, or Markdown
   - Optional auto-save to `localStorage`
   - Word count and character count status bar
@@ -124,12 +125,15 @@ Pass an HTML string as `content`. If the content is already RTF, convert it firs
 | `showStatusBar` | `boolean`  | `true`                       | Show the word/character count bar                         |
 | `minHeight`     | `string`   | `'40vh'`                     | CSS `min-height` of the editing area                      |
 | `readonly`      | `boolean`  | `false`                      | Disable editing                                           |
+| `maxImageEdge`  | `number`   | `1600`                       | Longest edge (px) an inserted image is scaled down to; `0` keeps full size |
+| `maxImageBytes` | `number`   | `524288`                     | Encoded byte ceiling per image; oversized pictures are re-encoded until they fit. `0` disables |
+| `maxImageDisplayWidth` | `number` | `624`                 | Width (px) a newly inserted image is displayed at, unless the column is narrower — 6.5in of page. `0` fills the column |
 
 #### Callback props
 
 | Prop       | Payload                                      | Description                                 |
 |------------|----------------------------------------------|---------------------------------------------|
-| `onchange` | `{ html, text, wordCount, charCount }`       | Fired on every content change               |
+| `onchange` | `{ html, text, wordCount, charCount, estimatedRtfBytes }` | Fired on every content change |
 | `onsave`   | `{ html }`                                   | Fired on auto-save or `Ctrl+S`              |
 | `onimport` | `{ html }`                                   | Fired after a successful RTF file import    |
 
@@ -141,6 +145,7 @@ editor.getText()          // → string  — plain text (no tags)
 editor.setHTML(html)      // → void    — replace content programmatically
 editor.getMarkdown()      // → string  — Markdown conversion of content
 editor.getRTF()           // → string  — RTF conversion of content
+editor.getRtfSize()       // → number  — exact byte size of that RTF
 editor.clear()            // → void    — clear the editor
 editor.focus()            // → void    — focus the editor
 editor.exportFile(format) // → void    — download as 'html' | 'md' | 'rtf'
@@ -152,13 +157,16 @@ editor.importRtf()        // → void    — open the file picker to import .rtf
 ## Utility functions
 
 ```ts
-import { rtfToHtml, htmlToRtf, readRtfFile, htmlToMarkdown, downloadFile } from 'svelte-rtf-editor';
+import {
+  rtfToHtml, htmlToRtf, estimateRtfBytes, readRtfFile, htmlToMarkdown, downloadFile
+} from 'svelte-rtf-editor';
 ```
 
 | Function                              | Description                                        |
 |---------------------------------------|----------------------------------------------------|
 | `rtfToHtml(rtf: string): string`      | Parse an RTF string and return an HTML string      |
 | `htmlToRtf(html: string): string`     | Convert an HTML string to RTF                      |
+| `estimateRtfBytes(el: HTMLElement): number` | Approximate RTF size of a DOM element without converting it |
 | `readRtfFile(file: File): Promise<string>` | Read a `.rtf` File object and return HTML     |
 | `htmlToMarkdown(el: HTMLElement): string` | Convert a DOM element's content to Markdown   |
 | `downloadFile(name, content, mime): void` | Trigger a file download in the browser        |
@@ -192,7 +200,72 @@ The components use CSS custom properties with sensible fallbacks, so they work o
 | `Ctrl+B`   | Bold              |
 | `Ctrl+I`   | Italic            |
 | `Ctrl+U`   | Underline         |
+| `Ctrl+K`   | Insert link       |
 | `Ctrl+S`   | Save (fires `onsave`) |
+| `Backspace` / `Delete` | Remove the selected image |
+
+---
+
+## Working with images
+
+Three ways to add a picture:
+
+- **Toolbar** — the image button opens a dialog where you can pick one or several files from disk, or paste an image address
+- **Paste** — paste an image straight from the clipboard (a screenshot, for example)
+- **Drag and drop** — drop image files anywhere in the editing area; they are inserted where you dropped them
+
+Each picture is inserted as a `<figure>` with a `<figcaption>` under it. Click the caption line and type to describe the image — the description travels with the picture through every export. Insert as many images as a document needs.
+
+Click an image to select it. A frame appears with corner handles you can drag to resize (the aspect ratio is kept and the width is capped at the editor's text width), buttons for 25% / 50% / 100% width, left / centre / right placement, a shortcut to its description, and a remove button.
+
+### How images are stored
+
+Images are held inline as base64 data URLs, so a document is self-contained — it auto-saves, exports and re-imports with the pictures intact, and needs no image server.
+
+- **RTF export** writes each picture as a real `\pict` group (`\pngblip` / `\jpegblip`) sized with `\picwgoal` / `\pichgoal`, so it opens with the images in Word, TextEdit and other RTF readers. The description follows as an italic line, tagged with an ignorable `{\*\inkcap}` destination that this library uses to re-attach it to the figure on import; other readers simply skip the tag.
+- **RTF import** decodes `\pict` PNG and JPEG data (including pictures wrapped in `{\*\shppict}`) back into images at their stored size. Picture formats a browser cannot display — metafiles and device-dependent bitmaps — are skipped.
+- **Formats**: PNG and JPEG are embedded as-is. Anything else (GIF, WebP, SVG, …) is re-encoded to PNG when inserted, since RTF carries no other bitmap types. Animated images keep their first frame.
+- **Images added by address** are fetched and inlined so they survive export. When the fetch is blocked (CORS or offline) the address is kept and the picture still displays, but it exports as an `[Image: …]` placeholder instead of picture data — the editor says so at insert time rather than letting it go unnoticed until the document is read downstream.
+- **Size**: RTF stores picture data as hexadecimal — two characters per byte — so an embedded image costs twice its file size in the document. Resizing an image in the editor changes its display size only; two caps applied at insert time are what bound the payload:
+  - `maxImageEdge` (1600 px) scales the picture down so neither edge exceeds it.
+  - `maxImageBytes` (512 KB, so roughly 1 MB of document per image) is the ceiling that actually matters. A picture over it is re-encoded until it fits: a PNG is tried as PNG first so screenshots and diagrams stay sharp, falls back to JPEG only when it is too heavy *and* has no transparency to lose, then steps down through 80%, 64% and 50% of the target size. Whichever candidate fits first is kept.
+
+  Set either to `0` to disable it. Both caps are applied by re-encoding through a `<canvas>`, so they only take effect in a browser — in a runtime without one (SSR, jsdom/happy-dom tests) the original bytes are passed through untouched. Do not rely on them to bound a payload assembled server-side.
+- **Page fit**: a newly inserted picture is displayed at `maxImageDisplayWidth` (624 px) rather than filling the editor. RTF records the display size in twips — 624 px × 15 = 9360 twips = 6.5 in, the text width of a Letter page with 1 in margins — so pictures arrive sized to the page they will be printed or filed on, not to the width of the browser window. Resize handles still go up to the full column width when a picture deserves it.
+
+### Sending RTF over a transport
+
+`htmlToRtf` output is written to survive being carried inside another format — an HL7 `OBX-5` field, a JSON string, a CSV cell:
+
+- **One line.** The document contains no CR or LF anywhere — not in picture data, and not in text either: a newline inside text content is collapsed to the space a browser would have rendered (RTF readers ignore raw CR/LF, so `Hello\nworld` used to render as "Helloworld"). `<pre>` blocks keep their line structure as `\line`.
+- **Uppercase hex.** Picture bytes are written as uppercase hex, so a PNG begins with the `89504E470D0A1A0A` signature that receivers commonly match on.
+- **Format read from the bytes.** `\pngblip` vs `\jpegblip` is decided by sniffing the image's leading bytes, never by its declared MIME type — an operating system assigns `File.type` from the file extension, so a WebP saved as `.png` claims to be PNG. Bytes that are neither PNG nor JPEG are re-encoded on insert, or exported as a text placeholder rather than as a blip whose declared type contradicts its content.
+- **Sized for the pipe.** `maxImageBytes` bounds each picture, and the payload is roughly twice that in hex. Lower it to fit a field-length limit.
+
+Some receivers require the whole field on one unbroken line when it carries an image — that is why the writer emits no line breaks at all, rather than wrapping picture data the way many RTF writers do.
+
+### Knowing how big a document is
+
+The transport cares about the size of the finished RTF, and pictures make that unpredictable. Two ways to read it:
+
+```svelte
+<script>
+  let editor;
+  let size = 0;
+</script>
+
+<!-- an estimate on every change, cheap enough for a live indicator -->
+<InkEditor bind:this={editor} onchange={({ estimatedRtfBytes }) => (size = estimatedRtfBytes)} />
+
+<!-- the exact figure, when it is time to send -->
+<button onclick={() => console.log(editor.getRtfSize())}>Check size</button>
+```
+
+`getRtfSize()` does the full conversion — call it when a decision depends on it, not on every keystroke. `estimatedRtfBytes` counts picture data exactly (two characters per byte, which is what dominates) and approximates the rest, leaving an error of a few hundred bytes at most. The output is ASCII, so bytes and characters are the same number.
+
+The library reports the size and stops there; whether an oversized document may be sent is the host application's decision.
+
+Escaping for the carrying format is the integration layer's job, not the editor's. For HL7 v2 that means escaping the whole string's delimiters — `\` → `\E\`, `|` → `\F\`, `^` → `\S\`, `&` → `\T\`, `~` → `\R\` — because ordinary typed text ("Smith & Jones") reaches the RTF unescaped.
 
 ---
 

package/dist/RtfViewer.svelte

@@ -92,4 +92,22 @@
     .rtf-viewer :global(p:last-child) {
         margin-bottom: 0;
     }
+
+    /* Pictures decoded from \pict groups keep their stored width but never
+       overflow the viewer. */
+    .rtf-viewer :global(img) {
+        max-width: 100%;
+        height: auto;
+    }
+
+    .rtf-viewer :global(figure) {
+        margin: 1em 0;
+    }
+
+    .rtf-viewer :global(figcaption) {
+        margin-top: 0.4em;
+        font-size: 0.85em;
+        font-style: italic;
+        color: var(--text-muted, #8a7e72);
+    }
 </style>

package/dist/components/ImageOverlay.svelte

@@ -0,0 +1,302 @@
+<script lang="ts">
+	/**
+	 * ImageOverlay — selection frame for an image inside the editor.
+	 *
+	 * Renders outside the contenteditable area (so it never ends up in the
+	 * exported HTML) and is absolutely positioned over the target image by
+	 * `bounds`, which must be a positioned ancestor of the editing surface.
+	 *
+	 * Provides drag-to-resize corner handles plus a small toolbar for
+	 * placement (left / centre / right), width presets, caption editing and
+	 * deletion.
+	 */
+
+	interface Props {
+		/** Image currently selected in the editor, or null when nothing is selected. */
+		target?: HTMLImageElement | null;
+		/** Positioned element the overlay coordinates are relative to. */
+		bounds?: HTMLElement | null;
+		/** Widest the image may become — the editor's content box width in px. */
+		maxWidth?: () => number;
+		onchange?: () => void;
+		onremove?: () => void;
+		oncaption?: (img: HTMLImageElement) => void;
+	}
+
+	let { target = null, bounds = null, maxWidth, onchange, onremove, oncaption }: Props = $props();
+
+	const MIN_WIDTH = 40;
+	const CORNERS = ['nw', 'ne', 'sw', 'se'] as const;
+
+	let frame = $state({ left: 0, top: 0, width: 0, height: 0 });
+	let visible = $state(false);
+	let dragging = $state(false);
+	let sizeLabel = $state('');
+
+	/** Recompute the frame position — call after anything that reflows content. */
+	export function reposition(): void {
+		if (!target || !bounds || !target.isConnected) {
+			visible = false;
+			return;
+		}
+		const t = target.getBoundingClientRect();
+		const b = bounds.getBoundingClientRect();
+		frame = { left: t.left - b.left, top: t.top - b.top, width: t.width, height: t.height };
+		visible = t.width > 0 && t.height > 0;
+	}
+
+	$effect(() => {
+		// Re-read `target` so the effect re-runs whenever the selection changes.
+		void target;
+		reposition();
+	});
+
+	function limit(): number {
+		const max = maxWidth?.() ?? 0;
+		return max > MIN_WIDTH ? max : Number.POSITIVE_INFINITY;
+	}
+
+	function applyWidth(px: number): void {
+		if (!target) return;
+		const width = Math.round(Math.min(Math.max(px, MIN_WIDTH), limit()));
+		// The width attribute would fight the style rule — the style is the
+		// single source of truth that both the RTF writer and CSS read.
+		target.removeAttribute('width');
+		target.removeAttribute('height');
+		target.style.width = `${width}px`;
+		target.style.height = 'auto';
+		reposition();
+	}
+
+	function startResize(e: PointerEvent, corner: string): void {
+		if (!target) return;
+		e.preventDefault();
+		e.stopPropagation();
+
+		const rect = target.getBoundingClientRect();
+		const startX = e.clientX;
+		const startWidth = rect.width;
+		const ratio = rect.width > 0 ? rect.height / rect.width : 1;
+		const handle = e.currentTarget as HTMLElement;
+
+		dragging = true;
+		sizeLabel = `${Math.round(startWidth)} × ${Math.round(rect.height)}`;
+		handle.setPointerCapture?.(e.pointerId);
+
+		const onMove = (ev: PointerEvent) => {
+			// West-side handles grow the image as the pointer moves left.
+			const dx = corner.includes('w') ? startX - ev.clientX : ev.clientX - startX;
+			applyWidth(startWidth + dx);
+			const w = target ? target.getBoundingClientRect().width : 0;
+			sizeLabel = `${Math.round(w)} × ${Math.round(w * ratio)}`;
+		};
+
+		const onUp = (ev: PointerEvent) => {
+			handle.releasePointerCapture?.(ev.pointerId);
+			handle.removeEventListener('pointermove', onMove);
+			handle.removeEventListener('pointerup', onUp);
+			handle.removeEventListener('pointercancel', onUp);
+			dragging = false;
+			onchange?.();
+		};
+
+		handle.addEventListener('pointermove', onMove);
+		handle.addEventListener('pointerup', onUp);
+		handle.addEventListener('pointercancel', onUp);
+	}
+
+	function align(value: 'left' | 'center' | 'right'): void {
+		if (!target) return;
+		const block = target.closest('figure') ?? target.parentElement;
+		if (!block) return;
+		if (value === 'left') block.removeAttribute('style');
+		else (block as HTMLElement).style.textAlign = value;
+		reposition();
+		onchange?.();
+	}
+
+	function currentAlign(): string {
+		const block = target?.closest('figure') ?? target?.parentElement;
+		return (block as HTMLElement | null)?.style?.textAlign || 'left';
+	}
+
+	function scaleTo(percent: number): void {
+		const max = maxWidth?.() ?? 0;
+		if (!max) return;
+		applyWidth((max * percent) / 100);
+		onchange?.();
+	}
+</script>
+
+<svelte:window onresize={reposition} onscroll={reposition} />
+
+{#if visible && target}
+	<div
+		class="ink-img-frame"
+		class:dragging
+		style="left:{frame.left}px;top:{frame.top}px;width:{frame.width}px;height:{frame.height}px"
+	>
+		<div class="ink-img-tools">
+			<button
+				type="button"
+				title="Align left"
+				class:active={currentAlign() === 'left'}
+				onclick={() => align('left')}
+			>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="15" y2="12"/><line x1="3" y1="18" x2="18" y2="18"/></svg>
+			</button>
+			<button
+				type="button"
+				title="Align center"
+				class:active={currentAlign() === 'center'}
+				onclick={() => align('center')}
+			>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="6" y1="12" x2="18" y2="12"/><line x1="4" y1="18" x2="20" y2="18"/></svg>
+			</button>
+			<button
+				type="button"
+				title="Align right"
+				class:active={currentAlign() === 'right'}
+				onclick={() => align('right')}
+			>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="9" y1="12" x2="21" y2="12"/><line x1="6" y1="18" x2="21" y2="18"/></svg>
+			</button>
+
+			<span class="ink-img-sep"></span>
+
+			<button type="button" title="Quarter width" onclick={() => scaleTo(25)}>25%</button>
+			<button type="button" title="Half width" onclick={() => scaleTo(50)}>50%</button>
+			<button type="button" title="Full width" onclick={() => scaleTo(100)}>100%</button>
+
+			<span class="ink-img-sep"></span>
+
+			<button type="button" title="Edit description" onclick={() => target && oncaption?.(target)}>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7V5h16v2"/><line x1="9" y1="19" x2="15" y2="19"/><line x1="12" y1="5" x2="12" y2="19"/></svg>
+			</button>
+			<button type="button" class="danger" title="Remove image" onclick={() => onremove?.()}>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/></svg>
+			</button>
+		</div>
+
+		{#each CORNERS as corner}
+			<!-- svelte-ignore a11y_no_static_element_interactions -->
+			<span
+				class="ink-img-handle {corner}"
+				onpointerdown={(e) => startResize(e, corner)}
+			></span>
+		{/each}
+
+		{#if dragging}
+			<span class="ink-img-size">{sizeLabel}</span>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	.ink-img-frame {
+		position: absolute;
+		box-sizing: border-box;
+		border: 1.5px solid var(--accent, #d4622b);
+		border-radius: 2px;
+		/* Clicks fall through to the image/text underneath; only the handles
+		   and the toolbar are interactive. */
+		pointer-events: none;
+		z-index: 20;
+	}
+
+	.ink-img-handle {
+		position: absolute;
+		width: 11px;
+		height: 11px;
+		background: white;
+		border: 1.5px solid var(--accent, #d4622b);
+		border-radius: 2px;
+		pointer-events: auto;
+		touch-action: none;
+	}
+
+	.ink-img-handle.nw { top: -6px; left: -6px; cursor: nwse-resize; }
+	.ink-img-handle.ne { top: -6px; right: -6px; cursor: nesw-resize; }
+	.ink-img-handle.sw { bottom: -6px; left: -6px; cursor: nesw-resize; }
+	.ink-img-handle.se { bottom: -6px; right: -6px; cursor: nwse-resize; }
+
+	.ink-img-tools {
+		position: absolute;
+		bottom: calc(100% + 8px);
+		left: 50%;
+		transform: translateX(-50%);
+		display: flex;
+		align-items: center;
+		gap: 2px;
+		padding: 4px;
+		background: white;
+		border: 1px solid var(--border, #e5e2dc);
+		border-radius: var(--radius-sm, 5px);
+		box-shadow: var(--shadow-md, 0 4px 12px rgba(44, 37, 32, 0.12));
+		pointer-events: auto;
+		white-space: nowrap;
+	}
+
+	.dragging .ink-img-tools {
+		opacity: 0;
+	}
+
+	.ink-img-tools button {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 26px;
+		height: 26px;
+		padding: 0 5px;
+		border: none;
+		background: none;
+		border-radius: 4px;
+		color: var(--text-muted, #8a7e72);
+		font-family: 'DM Sans', sans-serif;
+		font-size: 11px;
+		font-weight: 500;
+		cursor: pointer;
+		transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+
+	.ink-img-tools button:hover {
+		background: var(--surface, #f2f0ec);
+		color: var(--text, #2c2520);
+	}
+
+	.ink-img-tools button.active {
+		background: var(--accent-soft, #fdf0e9);
+		color: var(--accent, #d4622b);
+	}
+
+	.ink-img-tools button.danger:hover {
+		background: #fdecea;
+		color: #d32f2f;
+	}
+
+	.ink-img-tools svg {
+		width: 14px;
+		height: 14px;
+	}
+
+	.ink-img-sep {
+		width: 1px;
+		height: 16px;
+		margin: 0 4px;
+		background: var(--border, #e5e2dc);
+	}
+
+	.ink-img-size {
+		position: absolute;
+		bottom: 6px;
+		right: 6px;
+		padding: 2px 7px;
+		border-radius: 3px;
+		background: rgba(26, 23, 20, 0.78);
+		color: white;
+		font-family: 'DM Sans', sans-serif;
+		font-size: 11px;
+		font-variant-numeric: tabular-nums;
+		pointer-events: none;
+	}
+</style>

package/dist/components/ImageOverlay.svelte.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ImageOverlay — selection frame for an image inside the editor.
+ *
+ * Renders outside the contenteditable area (so it never ends up in the
+ * exported HTML) and is absolutely positioned over the target image by
+ * `bounds`, which must be a positioned ancestor of the editing surface.
+ *
+ * Provides drag-to-resize corner handles plus a small toolbar for
+ * placement (left / centre / right), width presets, caption editing and
+ * deletion.
+ */
+interface Props {
+    /** Image currently selected in the editor, or null when nothing is selected. */
+    target?: HTMLImageElement | null;
+    /** Positioned element the overlay coordinates are relative to. */
+    bounds?: HTMLElement | null;
+    /** Widest the image may become — the editor's content box width in px. */
+    maxWidth?: () => number;
+    onchange?: () => void;
+    onremove?: () => void;
+    oncaption?: (img: HTMLImageElement) => void;
+}
+declare const ImageOverlay: import("svelte").Component<Props, {
+    reposition: () => void;
+}, "">;
+type ImageOverlay = ReturnType<typeof ImageOverlay>;
+export default ImageOverlay;