@scalepad/ui 0.1.0

package/src/components/RichText/richTextHelpers.ts

@@ -0,0 +1,65 @@
+import type { JSONContent } from '@tiptap/react';
+
+/**
+ * Shared helpers for ProseMirror / Tiptap document manipulation used
+ * across `RichTextEditor`, `RichTextView`, and `EditableRichText`.
+ */
+
+export function normalizeValue(value: JSONContent | null): JSONContent {
+  if (value != null) {
+    return value;
+  }
+
+  return {
+    type: 'doc',
+    content: [{ type: 'paragraph' }],
+  };
+}
+
+export function docsEqual(a: JSONContent, b: JSONContent): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function plainTextFromDoc(
+  value: JSONContent | null | undefined,
+): string {
+  if (!value) {
+    return '';
+  }
+
+  if (typeof value.text === 'string') {
+    return value.text;
+  }
+
+  if (!Array.isArray(value.content)) {
+    return '';
+  }
+
+  return value.content
+    .map(item => plainTextFromDoc(item))
+    .join('\n')
+    .trim();
+}
+
+export function richTextDocFromPlainText(text: string): JSONContent {
+  return {
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: text
+          ? [
+              {
+                type: 'text',
+                text,
+              },
+            ]
+          : [],
+      },
+    ],
+  };
+}
+
+export function isDocEmpty(value: JSONContent | null | undefined): boolean {
+  return plainTextFromDoc(value).length === 0;
+}

package/src/components/RichText/richTextImage.ts

@@ -0,0 +1,253 @@
+/**
+ * Configurable image upload + lazy load support for `@scalepad/ui` rich-text
+ * editors.
+ *
+ * The design system intentionally doesn't know how to talk to a backend, so
+ * consumers wire two callbacks:
+ *
+ * - `uploadImage(blob, file)` — persist the uploaded blob and return a
+ *   stable `fileId` the doc can carry. The editor stores only the id; the
+ *   `src` attribute stays empty until the loader resolves it.
+ * - `loadImage(fileId)` — resolve a stored `fileId` back into a renderable
+ *   `src` (data URL, signed CDN URL — whatever the caller prefers). Returns
+ *   `null`/`undefined` to leave the image in the loading state.
+ *
+ * Both are optional. The hook surface enforces opt-in behaviour so the
+ * legacy "load 200 sections at once" rate-limit problem doesn't bite — see
+ * `autoLoad` on {@link useRichTextImageLoader}.
+ */
+import { useCallback, useEffect, useRef } from 'react';
+
+import type { Editor } from '@tiptap/react';
+
+import {
+  RICH_TEXT_FILE_ID_ATTRIBUTE,
+  RICH_TEXT_IMAGE_CLASS,
+} from './richTextExtensions';
+
+/**
+ * Bytes after WebP conversion. Matches the legacy editor's limit so users
+ * with existing instincts about "what fits" don't have to relearn it.
+ */
+export const DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES = 3 * 1024 * 1024;
+
+export interface RichTextImageUploadResult {
+  /** Stable identifier the consumer can use to fetch / replace the image. */
+  fileId: string;
+}
+
+export interface RichTextImageUploadError {
+  /** User-facing error message; the editor inserts it as a paragraph. */
+  error: string;
+}
+
+export type RichTextImageUploadResponse =
+  | RichTextImageUploadResult
+  | RichTextImageUploadError;
+
+export interface RichTextImageUploadConfig {
+  /**
+   * Persist the uploaded blob (already converted to WebP) and return the
+   * stable file id. Throw or return `{ error }` to surface an inline error
+   * to the user.
+   */
+  uploadImage: (
+    blob: Blob,
+    originalFile: File,
+  ) => Promise<RichTextImageUploadResponse>;
+  /**
+   * Override the post-WebP-conversion size limit. Defaults to
+   * {@link DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES} (3 MB) so behaviour matches
+   * the legacy editor.
+   */
+  maxBytes?: number;
+  /**
+   * WebP quality (0..1). Defaults to 0.8, matching the legacy editor.
+   */
+  quality?: number;
+}
+
+/**
+ * Build a callback that converts a `File` to WebP, validates its size, and
+ * defers to the consumer's `uploadImage` to persist it. Returns the file
+ * id on success, `{ error }` on validation failure / upload rejection.
+ */
+export function useRichTextImageUploader({
+  uploadImage,
+  maxBytes = DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES,
+  quality = 0.8,
+}: RichTextImageUploadConfig) {
+  return useCallback(
+    async (file: File): Promise<RichTextImageUploadResponse> => {
+      const blob = await convertToWebp(file, quality).catch(err => {
+        return {
+          error:
+            err instanceof Error ? err.message : 'Failed to process image.',
+        } as const;
+      });
+
+      if ('error' in (blob as object)) {
+        return blob as RichTextImageUploadError;
+      }
+
+      const webpBlob = blob as Blob;
+      if (webpBlob.size > maxBytes) {
+        const limitMb = Math.round(maxBytes / (1024 * 1024));
+        return {
+          error: `Image must be less than ${limitMb}MB, please try again.`,
+        };
+      }
+
+      try {
+        return await uploadImage(webpBlob, file);
+      } catch (err) {
+        return {
+          error: err instanceof Error ? err.message : 'Failed to upload image.',
+        };
+      }
+    },
+    [uploadImage, maxBytes, quality],
+  );
+}
+
+/**
+ * Convert an image File into a WebP blob via an offscreen canvas. The
+ * implementation matches the legacy `useTiptapImageUploader` precisely so
+ * file ids minted in either editor stay interchangeable.
+ *
+ * Exported so the non-React paste/drop pipeline in
+ * `richTextImageHandlers` can share the same conversion path.
+ */
+export function convertToWebp(file: File, quality: number): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+      reject(new Error('Browser does not support canvas conversion.'));
+      return;
+    }
+    const img = new window.Image();
+    const objectUrl = URL.createObjectURL(file);
+
+    img.onload = () => {
+      canvas.width = img.width;
+      canvas.height = img.height;
+      ctx.drawImage(img, 0, 0);
+      URL.revokeObjectURL(objectUrl);
+      canvas.toBlob(
+        result => {
+          if (!result) {
+            reject(new Error('Failed to convert image to WebP.'));
+            return;
+          }
+          resolve(result);
+        },
+        'image/webp',
+        quality,
+      );
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(objectUrl);
+      reject(new Error('Failed to load image.'));
+    };
+    img.src = objectUrl;
+  });
+}
+
+export interface RichTextImageLoaderConfig {
+  /**
+   * Resolve a stored file id into a renderable `src`. Returning `null` or
+   * `undefined` leaves the image in the loading state — useful when the
+   * caller wants to skip loading entirely for a specific id (e.g. behind a
+   * feature flag) without erroring.
+   */
+  loadImage: (fileId: string) => Promise<string | null | undefined>;
+  /**
+   * When `false` (the default), images stay in the loading state until the
+   * consumer calls the returned `loadImages` function manually. Surfaces
+   * that render many editors at once (Assessments renders ~200 sections
+   * simultaneously) MUST keep this off so they don't fan out 200 parallel
+   * blob fetches and trip the server's rate limiter.
+   *
+   * When `true`, the loader runs on every editor doc change.
+   */
+  autoLoad?: boolean;
+}
+
+export interface RichTextImageLoaderHandle {
+  /** Force-load every image with an unresolved `data-rich-text-file-id`. */
+  loadImages: () => Promise<void>;
+}
+
+/**
+ * Walk the editor DOM for image nodes that carry a `data-rich-text-file-id`
+ * but no usable `src`, and resolve each via the consumer-provided callback.
+ *
+ * The DOM is the source of truth here rather than the Tiptap doc JSON
+ * because the editor renders each node into a real `<img>` whose `src` we
+ * can mutate without recomputing the doc — which keeps the doc payload
+ * compact (just the file id) and avoids unnecessary onUpdate fires.
+ */
+export function useRichTextImageLoader(
+  editor: Editor | null,
+  config: RichTextImageLoaderConfig | null | undefined,
+): RichTextImageLoaderHandle {
+  // Cache the latest loader callback so the imperative `loadImages` always
+  // hits the freshest implementation without re-running the auto-load
+  // effect on every render.
+  const loadImageRef = useRef<RichTextImageLoaderConfig['loadImage'] | null>(
+    config?.loadImage ?? null,
+  );
+  loadImageRef.current = config?.loadImage ?? null;
+
+  const loadImages = useCallback(async () => {
+    const load = loadImageRef.current;
+    if (!editor || !load) return;
+    const root = editor.view.dom as HTMLElement;
+    const images = root.querySelectorAll<HTMLImageElement>(
+      `img.${RICH_TEXT_IMAGE_CLASS}[${RICH_TEXT_FILE_ID_ATTRIBUTE}]`,
+    );
+    if (images.length === 0) return;
+    await Promise.all(
+      Array.from(images).map(async img => {
+        const fileId = img.getAttribute(RICH_TEXT_FILE_ID_ATTRIBUTE);
+        if (!fileId) return;
+        if (img.dataset.richTextImageState === 'loaded') return;
+        // `data:` srcs are placeholder thumbnails or already-resolved
+        // payloads; skip them so we don't re-fetch.
+        if (img.src && img.src.startsWith('data:')) return;
+        img.dataset.richTextImageState = 'loading';
+        try {
+          const src = await load(fileId);
+          if (src) {
+            img.src = src;
+            img.dataset.richTextImageState = 'loaded';
+          } else {
+            img.dataset.richTextImageState = 'idle';
+          }
+        } catch {
+          img.dataset.richTextImageState = 'error';
+        }
+      }),
+    );
+  }, [editor]);
+
+  // Optional auto-loader. The default is OFF — surfaces that render many
+  // sections at once opt out so they don't fan a request per section.
+  useEffect(() => {
+    if (!editor || !config?.autoLoad || !config.loadImage) return;
+    const handle = window.setTimeout(() => {
+      void loadImages();
+    }, 100);
+    const onUpdate = () => {
+      void loadImages();
+    };
+    editor.on('update', onUpdate);
+    return () => {
+      window.clearTimeout(handle);
+      editor.off('update', onUpdate);
+    };
+  }, [editor, config?.autoLoad, config?.loadImage, loadImages]);
+
+  return { loadImages };
+}

package/src/components/RichText/richTextImageHandlers.ts

@@ -0,0 +1,244 @@
+/**
+ * Helpers that bridge the design-system-agnostic image hooks
+ * ({@link useRichTextImageUploader}, {@link useRichTextImageLoader}) into
+ * the editor components' `editorProps`. Centralised here so every editor
+ * surface (`RichTextEditor`, `EditableRichText`, `SlashRichTextEditor`)
+ * speaks the same upload/insert/error contract.
+ */
+import type { EditorView } from '@tiptap/pm/view';
+import type { Editor } from '@tiptap/react';
+
+import { RICH_TEXT_FILE_ID_ATTRIBUTE } from './richTextExtensions';
+import {
+  convertToWebp,
+  DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES,
+  useRichTextImageLoader as useImageLoader,
+  type RichTextImageLoaderConfig,
+  type RichTextImageLoaderHandle,
+  type RichTextImageUploadConfig,
+  type RichTextImageUploadResponse,
+} from './richTextImage';
+
+const DEFAULT_UPLOAD_ERROR = 'Failed to upload image. Please try again.';
+
+/**
+ * Combined image-handling config consumed by every editor in `@scalepad/ui`.
+ *
+ * The shape is opt-in at four layers:
+ *
+ * 1. If the consumer doesn't pass an `image` prop at all, the editor
+ *    schema omits the Image extension entirely — so the user can't even
+ *    paste an image into the document.
+ * 2. If `image.uploadImage` is omitted, paste / drop image data is
+ *    ignored. (Useful for read-only-ish surfaces that should still render
+ *    existing image nodes faithfully but never accept a new upload.)
+ * 3. If `image.loadImage` is omitted, images stay in their initial
+ *    `data:` / blank state forever. (Useful when the consumer wants the
+ *    editor to roundtrip the doc but the surface itself isn't responsible
+ *    for fetching binary content.)
+ * 4. If `image.autoLoad` is omitted (or `false`), images stay in the
+ *    loading state until the consumer calls `handle.loadImages()` from
+ *    the returned handle.
+ *
+ * Surfaces that render many editors at once (e.g. Assessments — ~200
+ * sections simultaneously) MUST keep `autoLoad: false` and trigger
+ * `loadImages()` from a viewport observer to avoid rate-limiting the
+ * backend.
+ */
+export interface RichTextImageEditorConfig
+  extends
+    Partial<RichTextImageUploadConfig>,
+    Partial<RichTextImageLoaderConfig> {
+  /**
+   * Called when a paste/drop upload fails. When provided, the error is
+   * surfaced through this callback (e.g. so the consumer can show a
+   * toast) instead of being inserted into the document as an editable
+   * paragraph the user has to delete.
+   *
+   * Omit to fall back to the legacy behaviour of inserting the error
+   * message as a paragraph at the drop location.
+   */
+  onError?: (message: string) => void;
+}
+
+const noopHandlers = {} as const;
+
+/**
+ * Build the `editorProps.handlePaste` / `handleDrop` pair that uploads
+ * pasted / dropped image files via the consumer-provided callback and
+ * inserts an empty `image` node carrying the resulting
+ * `data-rich-text-file-id`.
+ *
+ * Returns an empty object when `image` is undefined or doesn't contain an
+ * `uploadImage` callback — that's the signal that the surface doesn't
+ * accept image input.
+ */
+export function installRichTextImageHandlers(
+  image: RichTextImageEditorConfig | undefined,
+) {
+  if (!image?.uploadImage) return noopHandlers;
+
+  return {
+    handlePaste: (view: EditorView, event: ClipboardEvent) => {
+      const items = event.clipboardData?.items;
+      if (!items) return false;
+      for (const item of items) {
+        if (item.type.startsWith('image/')) {
+          const file = item.getAsFile();
+          if (file) {
+            event.preventDefault();
+            void uploadAndInsertImage(
+              view,
+              file,
+              view.state.selection.from,
+              image,
+            );
+            return true;
+          }
+        }
+      }
+      return false;
+    },
+    handleDrop: (view: EditorView, event: DragEvent) => {
+      const files = event.dataTransfer?.files;
+      if (!files || files.length === 0) return false;
+      const file = files[0];
+      if (!file || !file.type.startsWith('image/')) return false;
+      event.preventDefault();
+      const coords = view.posAtCoords({
+        left: event.clientX,
+        top: event.clientY,
+      });
+      void uploadAndInsertImage(
+        view,
+        file,
+        coords?.pos ?? view.state.selection.from,
+        image,
+      );
+      return true;
+    },
+  };
+}
+
+async function uploadAndInsertImage(
+  view: EditorView,
+  file: File,
+  insertPos: number,
+  image: RichTextImageEditorConfig,
+) {
+  if (!image.uploadImage) return;
+
+  const response = await runUploadPipeline(file, image);
+
+  // The upload is async and the user may have unmounted the editor (closed
+  // the modal, navigated away, etc.) while it was in flight. Bail out
+  // before touching `view.state` or dispatching, both of which throw on a
+  // destroyed view.
+  if (view.isDestroyed) return;
+
+  const safePos = clampInsertPos(view, insertPos);
+  if ('error' in response) {
+    const message = response.error || DEFAULT_UPLOAD_ERROR;
+    if (image.onError) {
+      image.onError(message);
+    } else {
+      insertErrorParagraph(view, safePos, message);
+    }
+    return;
+  }
+
+  const imageNode = view.state.schema.nodes.image;
+  if (!imageNode) return;
+  const tr = view.state.tr.insert(
+    safePos,
+    imageNode.create({
+      src: '',
+      [RICH_TEXT_FILE_ID_ATTRIBUTE]: response.fileId,
+    }),
+  );
+  view.dispatch(tr);
+}
+
+const DEFAULT_PROCESS_ERROR = 'Failed to process image. Please try again.';
+
+/**
+ * Mirror of {@link useRichTextImageUploader} that runs outside React (so
+ * paste / drop handlers fire). Performs WebP conversion + size validation
+ * via the shared {@link convertToWebp} helper before delegating to the
+ * consumer's `uploadImage`.
+ *
+ * Unexpected exceptions from the conversion or the consumer's uploader
+ * are intentionally NOT echoed back to the caller — the raw `err.message`
+ * may contain stack traces, internal URLs, or library-internal text that
+ * shouldn't surface in the document or in a toast. We log the original
+ * for debugging and return a generic, user-facing string instead.
+ *
+ * Errors the consumer surfaces by *returning* `{ error }` from
+ * `uploadImage` are passed through as-is — those are the consumer's
+ * intentional user-facing messages.
+ */
+async function runUploadPipeline(
+  file: File,
+  image: RichTextImageEditorConfig,
+): Promise<RichTextImageUploadResponse> {
+  let blob: Blob;
+  try {
+    blob = await convertToWebp(file, image.quality ?? 0.8);
+  } catch (err) {
+    console.warn('[richTextImageHandlers] Image conversion failed:', err);
+    return { error: DEFAULT_PROCESS_ERROR };
+  }
+
+  const maxBytes = image.maxBytes ?? DEFAULT_RICH_TEXT_IMAGE_MAX_BYTES;
+  if (blob.size > maxBytes) {
+    const limitMb = Math.round(maxBytes / (1024 * 1024));
+    return {
+      error: `Image must be less than ${limitMb}MB, please try again.`,
+    };
+  }
+
+  try {
+    return await image.uploadImage!(blob, file);
+  } catch (err) {
+    console.warn('[richTextImageHandlers] Image upload failed:', err);
+    return { error: DEFAULT_UPLOAD_ERROR };
+  }
+}
+
+function clampInsertPos(view: EditorView, pos: number) {
+  return Math.max(0, Math.min(pos, view.state.doc.content.size));
+}
+
+function insertErrorParagraph(view: EditorView, pos: number, message: string) {
+  const { schema } = view.state;
+  const paragraph = schema.nodes.paragraph;
+  if (!paragraph) return;
+  const tr = view.state.tr.insert(
+    pos,
+    paragraph.create(null, [schema.text(message)]),
+  );
+  view.dispatch(tr);
+}
+
+/**
+ * Editor-side wrapper around the design-system-agnostic
+ * {@link useRichTextImageLoader}. Returns the loader handle so callers can
+ * trigger lazy loads (e.g. from a viewport intersection observer) without
+ * touching the editor.
+ */
+export function useRichTextImageLoader(
+  editor: Editor | null,
+  image: RichTextImageEditorConfig | undefined,
+): RichTextImageLoaderHandle {
+  // Always call the hook so the rules-of-hooks check stays consistent
+  // even when the consumer doesn't pass an `image` config.
+  return useImageLoader(
+    editor,
+    image?.loadImage
+      ? {
+          loadImage: image.loadImage,
+          autoLoad: image.autoLoad,
+        }
+      : null,
+  );
+}