@bendyline/squisq-editor-react 1.2.1 → 1.3.0

package/src/EditorShell.tsx

@@ -7,7 +7,13 @@
  */
 
 import { useEffect, useState, useCallback } from 'react';
-import { EditorProvider, useEditorContext, type EditorView } from './EditorContext';
+import {
+  EditorProvider,
+  useEditorContext,
+  type EditorView,
+  type ImageDisplayMode,
+  type MentionProvider,
+} from './EditorContext';
 import { Toolbar } from './Toolbar';
 import { StatusBar } from './StatusBar';
 import { RawEditor } from './RawEditor';
@@ -16,6 +22,7 @@ import { PreviewPanel } from './PreviewPanel';
 import { PreviewSettingsProvider, PreviewToolbarControls } from './PreviewControls';
 import { MediaBin } from './MediaBin';
 import { DropZoneOverlay } from './DropZoneOverlay';
+import { TooltipLayer } from './Tooltip';
 import { useFileDrop, type DropTarget } from './hooks/useFileDrop';
 import {
   partitionFiles,
@@ -25,7 +32,7 @@ import {
 } from './utils/dropUtils';
 import type { MediaProvider } from '@bendyline/squisq/schemas';
 import type { ContentContainer } from '@bendyline/squisq/storage';
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
 export type { EditorTheme } from './EditorContext';
 
@@ -59,6 +66,105 @@ export interface EditorShellProps {
   toolbarSlotAfterActions?: ReactNode;
   /** Content rendered at the rightmost end of the toolbar, after all other elements. */
   toolbarSlotRight?: ReactNode;
+  /**
+   * Whether to show the "Play" (preview) tab in the toolbar. When false, the
+   * tab and its preview panel are hidden, and ⌘3 becomes a no-op. Use this
+   * when embedding the editor somewhere the slideshow preview doesn't make
+   * sense (e.g. editing free-form prompt documents). Defaults to true.
+   */
+  showPlayTab?: boolean;
+  /**
+   * Optional "submit on Enter" callback. When provided, a plain Enter
+   * keypress fires this callback instead of inserting a newline, and
+   * Cmd/Ctrl+Enter inserts a newline instead. Matches chat-composer UX
+   * (Slack, Discord). When omitted, the editor behaves normally.
+   */
+  submitOnEnter?: () => void;
+  /**
+   * Let the WYSIWYG editing surface fill its container instead of rendering
+   * as a centered 800px "page" column. Useful when embedding in chat
+   * composers, side panels, or any layout where the page metaphor doesn't
+   * fit. Defaults to false (page mode).
+   */
+  fullWidth?: boolean;
+  /**
+   * Font-family stack applied to the editor **chrome** — toolbar buttons,
+   * tabs, status bar, and control surfaces. The actual editing areas
+   * (Tiptap / Monaco) keep their own fonts so document editing isn't
+   * affected. Use this when the editor is embedded in a larger product
+   * that has its own UX type system and you want the controls to blend in.
+   *
+   * @example
+   * ```tsx
+   * <EditorShell uxFont="'Hanken Grotesk', system-ui, sans-serif" ... />
+   * ```
+   */
+  uxFont?: string;
+  /**
+   * Drop the editor's generous page-style padding in favor of a tight
+   * layout that hugs its container. The default WYSIWYG surface uses
+   * 16×24px padding suitable for editing long-form documents; chat
+   * composers want much less. Applies to the editing area only — the
+   * toolbar, tabs, and status bar keep their normal sizing.
+   */
+  thinMargins?: boolean;
+  /**
+   * Render the bottom status bar (word / character / line / block counts
+   * and parse-state indicator). Defaults to `true`. Set to `false` in
+   * embedded surfaces — chat composers and other short-form inputs —
+   * where the stats are noise.
+   */
+  showStatusBar?: boolean;
+  /**
+   * How images should be displayed in the WYSIWYG view. `'inline'`
+   * (default) flows them at natural size up to the container width;
+   * `'thumbnail'` constrains each image to a 100×100 box with
+   * aspect-preserving containment — useful for chat composers and other
+   * dense surfaces where a full-resolution paste would dominate the
+   * layout. Storage bytes are unchanged either way.
+   */
+  imageDisplayMode?: ImageDisplayMode;
+  /**
+   * File name (e.g. `foo.ts`) or bare extension that the content
+   * represents. When set to a non-markdown/text extension, the shell
+   * enters **code mode**: Monaco picks the right language based on the
+   * extension, the WYSIWYG and Preview tabs disappear, and the toolbar
+   * drops its markdown-specific formatting buttons. Markdown-ish
+   * extensions (`.md`, `.markdown`, `.mdown`, `.txt`) keep the full
+   * experience. Omit to get today's markdown behavior unchanged.
+   */
+  fileName?: string;
+  /**
+   * Explicit Monaco language ID override (e.g. `'typescript'`,
+   * `'python'`, `'json'`). Wins over the language derived from
+   * `fileName`. Anything other than `'markdown'` or `'plaintext'`
+   * switches the shell into code mode.
+   */
+  language?: string;
+  /**
+   * Optional async provider for `@`-mention suggestions. When supplied,
+   * typing `@` inside the editor opens a popover of candidates; selecting
+   * one inserts a `@[Label](scheme:id)` mention token. Used by chat
+   * composers and any other surface that wants to address named entities
+   * inline. Omit to disable mentions entirely.
+   */
+  mentionProvider?: MentionProvider | null;
+  /**
+   * Placeholder text shown in the WYSIWYG editor while the document is
+   * empty. When omitted, the editor rotates through its own generic
+   * "start typing…" prompts; pass a value here to override with copy
+   * that fits the embedding surface (e.g. a chat composer knows who
+   * the message is going to and can say so).
+   */
+  placeholder?: string;
+  /**
+   * When true, both editing surfaces become non-editable: Monaco runs in
+   * `readOnly` mode and Tiptap is set to `editable: false`. The toolbar
+   * still renders — hide it from the host side if you want a pure preview.
+   * Useful for reference panels that show file content without inviting
+   * accidental edits.
+   */
+  readOnly?: boolean;
 }
 
 /**
@@ -80,29 +186,58 @@ export function EditorShell({
   toolbarSlotLeft,
   toolbarSlotAfterActions,
   toolbarSlotRight,
+  showPlayTab = true,
+  submitOnEnter,
+  fullWidth = false,
+  uxFont,
+  thinMargins = false,
+  showStatusBar = true,
+  imageDisplayMode = 'inline',
+  fileName,
+  language,
+  mentionProvider,
+  placeholder,
+  readOnly = false,
 }: EditorShellProps) {
   // Show the toggle when explicitly opted in, or when mediaProvider prop was passed at all
   const filesToggleEnabled = showFilesToggle ?? mediaProvider !== undefined;
 
+  // If the host hides the Play tab but asked for it as the initial view,
+  // fall back to wysiwyg so we don't boot into a tab the user can't leave.
+  const effectiveInitialView: EditorView =
+    !showPlayTab && initialView === 'preview' ? 'wysiwyg' : initialView;
+
   return (
     <EditorProvider
       initialMarkdown={initialMarkdown}
-      initialView={initialView}
+      initialView={effectiveInitialView}
       articleId={articleId}
       theme={theme}
       mediaProvider={mediaProvider}
+      imageDisplayMode={imageDisplayMode}
+      mentionProvider={mentionProvider}
+      fileName={fileName}
+      language={language}
     >
       <EditorShellInner
         basePath={basePath}
         onChange={onChange}
         className={className}
         height={height}
+        placeholder={placeholder}
         mediaProvider={mediaProvider ?? null}
         container={container}
         filesToggleEnabled={filesToggleEnabled}
         toolbarSlotLeft={toolbarSlotLeft}
         toolbarSlotAfterActions={toolbarSlotAfterActions}
         toolbarSlotRight={toolbarSlotRight}
+        showPlayTab={showPlayTab}
+        submitOnEnter={submitOnEnter}
+        fullWidth={fullWidth}
+        uxFont={uxFont}
+        thinMargins={thinMargins}
+        showStatusBar={showStatusBar}
+        readOnly={readOnly}
       />
     </EditorProvider>
   );
@@ -113,12 +248,20 @@ interface EditorShellInnerProps {
   onChange?: (source: string) => void;
   className?: string;
   height: string;
+  placeholder?: string;
   mediaProvider: MediaProvider | null;
   container?: ContentContainer | null;
   filesToggleEnabled: boolean;
   toolbarSlotLeft?: ReactNode;
   toolbarSlotAfterActions?: ReactNode;
   toolbarSlotRight?: ReactNode;
+  showPlayTab: boolean;
+  submitOnEnter?: () => void;
+  fullWidth: boolean;
+  uxFont?: string;
+  thinMargins: boolean;
+  showStatusBar: boolean;
+  readOnly: boolean;
 }
 
 function EditorShellInner({
@@ -126,15 +269,25 @@ function EditorShellInner({
   onChange,
   className,
   height,
+  placeholder,
   mediaProvider,
   container,
   filesToggleEnabled,
   toolbarSlotLeft,
   toolbarSlotAfterActions,
   toolbarSlotRight,
+  showPlayTab,
+  submitOnEnter,
+  fullWidth,
+  uxFont,
+  thinMargins,
+  showStatusBar,
+  readOnly,
 }: EditorShellInnerProps) {
-  const { activeView, markdownSource, doc, theme, insertAtCursor, replaceAll } = useEditorContext();
+  const { activeView, markdownSource, doc, theme, editorMode, insertAtCursor, replaceAll } =
+    useEditorContext();
   const isPreview = activeView === 'preview';
+  const isCodeMode = editorMode === 'code';
   const [showFiles, setShowFiles] = useState(false);
   const [mediaRefreshKey, setMediaRefreshKey] = useState(0);
   const isDark = theme === 'dark';
@@ -200,6 +353,7 @@ function EditorShellInner({
             document.querySelector<HTMLButtonElement>('[data-view="raw"]')?.click();
             break;
           case '3':
+            if (!showPlayTab) return;
             e.preventDefault();
             document.querySelector<HTMLButtonElement>('[data-view="preview"]')?.click();
             break;
@@ -208,17 +362,24 @@ function EditorShellInner({
     };
     window.addEventListener('keydown', handler);
     return () => window.removeEventListener('keydown', handler);
-  }, []);
+  }, [showPlayTab]);
 
   return (
     <div
       className={`squisq-editor-shell ${className || ''}`}
       data-theme={theme}
+      data-full-width={fullWidth ? 'true' : undefined}
+      data-thin-margins={thinMargins ? 'true' : undefined}
       style={{
         display: 'flex',
         flexDirection: 'column',
         height,
         overflow: 'hidden',
+        // When a consumer supplies a UX font stack, expose it to the
+        // editor CSS via this custom property. Chrome elements (toolbar,
+        // tabs, status bar) consume `--squisq-ux-font` as their
+        // `font-family`, falling back to the system stack when unset.
+        ...(uxFont ? ({ '--squisq-ux-font': uxFont } as CSSProperties) : {}),
       }}
       {...containerProps}
     >
@@ -227,15 +388,16 @@ function EditorShellInner({
         <div className="squisq-editor-header">
           <Toolbar
             showFiles={showFiles}
-            onToggleFiles={filesToggleEnabled ? handleToggleFiles : undefined}
+            onToggleFiles={!isCodeMode && filesToggleEnabled ? handleToggleFiles : undefined}
             slotLeft={toolbarSlotLeft}
             slotAfterActions={
               <>
                 {toolbarSlotAfterActions}
-                {isPreview && <PreviewToolbarControls />}
+                {!isCodeMode && isPreview && <PreviewToolbarControls />}
               </>
             }
             slotRight={toolbarSlotRight}
+            showPlayTab={showPlayTab}
           />
         </div>
 
@@ -245,17 +407,32 @@ function EditorShellInner({
           style={{ flex: 1, overflow: 'hidden', position: 'relative', display: 'flex' }}
         >
           <div style={{ flex: 1, overflow: 'hidden', position: 'relative' }}>
-            {activeView === 'raw' && <RawEditor theme={theme === 'dark' ? 'vs-dark' : 'vs'} />}
-            {activeView === 'wysiwyg' && <WysiwygEditor />}
-            {isPreview && <PreviewPanel basePath={basePath} container={container} />}
+            {activeView === 'raw' && (
+              <RawEditor
+                theme={theme === 'dark' ? 'vs-dark' : 'vs'}
+                submitOnEnter={submitOnEnter}
+                readOnly={readOnly}
+              />
+            )}
+            {/* WYSIWYG + Preview are markdown-only surfaces — skip them
+                entirely in code mode so Tiptap never initializes and the
+                preview pipeline stays idle. */}
+            {!isCodeMode && activeView === 'wysiwyg' && (
+              <WysiwygEditor
+                submitOnEnter={submitOnEnter}
+                placeholder={placeholder}
+                readOnly={readOnly}
+              />
+            )}
+            {!isCodeMode && isPreview && <PreviewPanel basePath={basePath} container={container} />}
           </div>
 
-          {showFiles && (
+          {!isCodeMode && showFiles && (
             <MediaBin mediaProvider={mediaProvider} isDark={isDark} refreshKey={mediaRefreshKey} />
           )}
 
-          {/* Drop zone overlay */}
-          {isDragging && (
+          {/* Drop zone overlay — image / text drop UX is markdown-specific. */}
+          {!isCodeMode && isDragging && (
             <DropZoneOverlay
               dragContentType={dragContentType}
               zoneProps={zoneProps}
@@ -264,9 +441,12 @@ function EditorShellInner({
           )}
         </div>
 
-        {/* Status bar */}
-        <StatusBar />
+        {/* Status bar — word / char / line / block counts. Host can
+            suppress via `showStatusBar={false}` for embedded chat-style
+            composers where the stats are noise. */}
+        {showStatusBar && <StatusBar />}
       </PreviewSettingsProvider>
+      <TooltipLayer />
     </div>
   );
 }

package/src/ImageNodeView.tsx

@@ -16,8 +16,9 @@ import { useEditorContext } from './EditorContext';
 
 function ImageComponent({ node }: NodeViewProps) {
   const { src, alt, title } = node.attrs as { src: string; alt: string; title: string };
-  const { mediaProvider } = useEditorContext();
+  const { mediaProvider, imageDisplayMode } = useEditorContext();
   const [resolvedSrc, setResolvedSrc] = useState(src);
+  const isThumbnail = imageDisplayMode === 'thumbnail';
 
   const isRelative =
     src &&
@@ -53,7 +54,19 @@ function ImageComponent({ node }: NodeViewProps) {
         src={resolvedSrc}
         alt={alt || ''}
         title={title || undefined}
-        style={{ maxWidth: '100%', height: 'auto', display: 'block' }}
+        className={isThumbnail ? 'squisq-image squisq-image--thumbnail' : 'squisq-image'}
+        style={
+          isThumbnail
+            ? {
+                maxWidth: '100px',
+                maxHeight: '100px',
+                width: 'auto',
+                height: 'auto',
+                objectFit: 'contain',
+                display: 'block',
+              }
+            : { maxWidth: '100%', height: 'auto', display: 'block' }
+        }
       />
     </NodeViewWrapper>
   );

package/src/MediaBin.tsx

@@ -8,6 +8,7 @@
 
 import { useState, useEffect, useRef, useCallback } from 'react';
 import type { MediaProvider, MediaEntry } from '@bendyline/squisq/schemas';
+import { SQUISQ_MEDIA_MIME } from './mediaDragMime';
 
 // ============================================
 // Types
@@ -186,16 +187,37 @@ export function MediaBin({ mediaProvider, isDark, refreshKey }: MediaBinProps) {
         {entries.map((entry) => {
           const thumb = thumbUrls[entry.name];
           const basename = entry.name.includes('/') ? entry.name.split('/').pop()! : entry.name;
+          const isImage = isImageMime(entry.mimeType);
+          const altText = basename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+
+          const handleDragStart = (e: React.DragEvent<HTMLDivElement>) => {
+            if (!isImage) return;
+            const payload = JSON.stringify({
+              name: entry.name,
+              mimeType: entry.mimeType,
+              alt: altText,
+            });
+            e.dataTransfer.setData(SQUISQ_MEDIA_MIME, payload);
+            e.dataTransfer.setData('text/plain', `![${altText}](${entry.name})`);
+            e.dataTransfer.effectAllowed = 'copy';
+          };
 
           return (
             <div
               key={entry.name}
               className="squisq-media-bin-item"
               title={`${entry.name}\n${entry.mimeType}\n${formatSize(entry.size)}`}
+              draggable={isImage}
+              onDragStart={handleDragStart}
             >
               {/* Thumbnail or icon */}
               {thumb ? (
-                <img src={thumb} alt={basename} className="squisq-media-bin-thumb" />
+                <img
+                  src={thumb}
+                  alt={basename}
+                  className="squisq-media-bin-thumb"
+                  draggable={false}
+                />
               ) : (
                 <span className="squisq-media-bin-icon">{iconForMime(entry.mimeType)}</span>
               )}

package/src/MentionExtension.tsx

@@ -0,0 +1,258 @@
+/**
+ * MentionExtension
+ *
+ * Tiptap mention configuration paired with a small absolutely-positioned
+ * suggestion popover. Shares a caller-supplied async provider (see
+ * `MentionProvider` in EditorContext) with the Monaco `@` completion
+ * provider in `RawEditor`, so both editing modes surface the same roster.
+ *
+ * The mention chip renders as `<span data-mention data-kind data-id
+ * data-label class="mention">@Label</span>`, matching the wire format that
+ * `tiptapBridge` emits when converting markdown → Tiptap HTML. On serialize
+ * back to markdown, the bridge emits `@[Label](kind:id)`.
+ */
+
+import Mention from '@tiptap/extension-mention';
+import { PluginKey } from '@tiptap/pm/state';
+import type { Editor, Range } from '@tiptap/core';
+import type { MentionCandidate, MentionProvider } from './EditorContext';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SuggestionProps = any;
+
+/**
+ * Fallback namespace for defensive code paths — used when a mention node
+ * somehow lacks a `kind` attribute (e.g. legacy HTML parsed without one).
+ * Inserts from the suggestion popover always carry the candidate's own
+ * `scheme`, so this only surfaces for malformed/legacy content.
+ */
+const FALLBACK_KIND = 'mention';
+
+type SuggestionState = {
+  items: MentionCandidate[];
+  selected: number;
+};
+
+/**
+ * Build the Tiptap mention extension for an editor. The returned extension
+ * captures a reference to `getProvider` at configure-time and calls it on
+ * every keystroke — keep the reference stable so we don't recreate the
+ * editor just to change who answers the `@` query.
+ */
+export function buildMentionExtension(getProvider: () => MentionProvider | null) {
+  return Mention.configure({
+    HTMLAttributes: {
+      class: 'mention',
+      'data-mention': 'true',
+    },
+    renderHTML({ options, node }) {
+      const label =
+        (node.attrs.label as string | undefined) ?? (node.attrs.id as string | undefined) ?? '';
+      const id = (node.attrs.id as string | undefined) ?? '';
+      const kind = (node.attrs.kind as string | undefined) ?? FALLBACK_KIND;
+      return [
+        'span',
+        {
+          ...options.HTMLAttributes,
+          'data-kind': kind,
+          'data-id': id,
+          'data-label': label,
+        },
+        `@${label}`,
+      ];
+    },
+    renderText({ node }) {
+      const label =
+        (node.attrs.label as string | undefined) ?? (node.attrs.id as string | undefined) ?? '';
+      const id = (node.attrs.id as string | undefined) ?? '';
+      const kind = (node.attrs.kind as string | undefined) ?? FALLBACK_KIND;
+      return `@[${label}](${kind}:${id})`;
+    },
+  }).extend({
+    addAttributes() {
+      return {
+        id: {
+          default: null,
+          parseHTML: (el) => el.getAttribute('data-id'),
+          renderHTML: (attrs) => (attrs.id ? { 'data-id': attrs.id } : {}),
+        },
+        label: {
+          default: null,
+          parseHTML: (el) => el.getAttribute('data-label'),
+          renderHTML: (attrs) => (attrs.label ? { 'data-label': attrs.label } : {}),
+        },
+        kind: {
+          default: FALLBACK_KIND,
+          parseHTML: (el) => el.getAttribute('data-kind') ?? FALLBACK_KIND,
+          renderHTML: (attrs) => ({ 'data-kind': attrs.kind ?? FALLBACK_KIND }),
+        },
+      };
+    },
+    addOptions() {
+      return {
+        ...(this.parent?.() ?? {}),
+        suggestion: {
+          char: '@',
+          // Custom plugin key so the mention suggestion doesn't collide
+          // with any future `:` or `/` popovers.
+          pluginKey: new PluginKey('mentionSuggestion'),
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          command: ({ editor, range, props }: { editor: Editor; range: Range; props: any }) => {
+            const id = (props?.id as string | null) ?? '';
+            const label = (props?.label as string | null) ?? id;
+            const kind = (props?.kind as string | undefined) ?? FALLBACK_KIND;
+            editor
+              .chain()
+              .focus()
+              .insertContentAt(range, [
+                {
+                  type: 'mention',
+                  attrs: { id, label, kind },
+                },
+                { type: 'text', text: ' ' },
+              ])
+              .run();
+          },
+          items: async ({ query }: { query: string }) => {
+            const provider = getProvider();
+            if (!provider) return [];
+            try {
+              return await provider(query);
+            } catch {
+              return [];
+            }
+          },
+          render: renderSuggestionFactory(),
+        },
+      };
+    },
+  });
+}
+
+/**
+ * Lightweight suggestion popover. Uses a plain absolutely-positioned div
+ * anchored to the caret rect — no tippy.js needed. Keyboard nav handled via
+ * the `onKeyDown` hook Tiptap wires up.
+ */
+function renderSuggestionFactory() {
+  return () => {
+    let container: HTMLDivElement | null = null;
+    let state: SuggestionState = { items: [], selected: 0 };
+    let currentProps: SuggestionProps | null = null;
+
+    const update = () => {
+      if (!container || !currentProps) return;
+      container.innerHTML = '';
+      if (state.items.length === 0) {
+        container.style.display = 'none';
+        return;
+      }
+      container.style.display = 'block';
+
+      for (let i = 0; i < state.items.length; i++) {
+        const item = state.items[i];
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'squisq-mention-item' + (i === state.selected ? ' is-selected' : '');
+        btn.dataset.index = String(i);
+        btn.innerHTML = '';
+        const label = document.createElement('span');
+        label.className = 'squisq-mention-label';
+        label.textContent = item.label;
+        btn.appendChild(label);
+        if (item.description) {
+          const desc = document.createElement('span');
+          desc.className = 'squisq-mention-desc';
+          desc.textContent = item.description;
+          btn.appendChild(desc);
+        }
+        btn.addEventListener('mousedown', (ev) => {
+          ev.preventDefault();
+          selectAt(i);
+        });
+        container.appendChild(btn);
+      }
+
+      positionTo(container, currentProps.clientRect);
+    };
+
+    const selectAt = (index: number) => {
+      const item = state.items[index];
+      if (!item || !currentProps) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const command = (currentProps as any).command;
+      if (typeof command === 'function') {
+        command({ id: item.id, label: item.label, kind: item.scheme });
+      }
+    };
+
+    return {
+      onStart: (props: SuggestionProps) => {
+        currentProps = props;
+        state = { items: props.items ?? [], selected: 0 };
+        if (!container) {
+          container = document.createElement('div');
+          container.className = 'squisq-mention-popover';
+          container.style.position = 'absolute';
+          container.style.zIndex = '10000';
+          document.body.appendChild(container);
+        }
+        update();
+      },
+      onUpdate: (props: SuggestionProps) => {
+        currentProps = props;
+        if (Array.isArray(props.items)) {
+          state = { items: props.items, selected: 0 };
+        }
+        update();
+      },
+      onKeyDown: ({ event }: { event: KeyboardEvent }) => {
+        if (!state.items.length) return false;
+        if (event.key === 'ArrowDown') {
+          state.selected = (state.selected + 1) % state.items.length;
+          update();
+          return true;
+        }
+        if (event.key === 'ArrowUp') {
+          state.selected = (state.selected - 1 + state.items.length) % state.items.length;
+          update();
+          return true;
+        }
+        if (event.key === 'Enter' || event.key === 'Tab') {
+          selectAt(state.selected);
+          return true;
+        }
+        if (event.key === 'Escape') {
+          state = { items: [], selected: 0 };
+          update();
+          return true;
+        }
+        return false;
+      },
+      onExit: () => {
+        if (container?.parentNode) container.parentNode.removeChild(container);
+        container = null;
+        currentProps = null;
+      },
+    };
+  };
+}
+
+function positionTo(
+  el: HTMLDivElement,
+  clientRect: (() => DOMRect | null) | null | undefined,
+): void {
+  const rect = clientRect?.();
+  if (!rect) return;
+  // Anchor just below the caret; fall back to above when there's no room.
+  const viewportH = window.innerHeight;
+  const below = rect.bottom + 4;
+  const estH = Math.min(240, el.offsetHeight || 200);
+  const fitsBelow = below + estH < viewportH;
+  el.style.left = `${rect.left + window.scrollX}px`;
+  if (fitsBelow) {
+    el.style.top = `${below + window.scrollY}px`;
+  } else {
+    el.style.top = `${rect.top + window.scrollY - estH - 4}px`;
+  }
+}