@railway/inkwell 1.1.0 → 1.2.0

package/README.md

@@ -51,26 +51,18 @@ pnpm dev
 
 ## Releases
 
-Versioning and `CHANGELOG.md` are managed by [Changesets](https://github.com/changesets/changesets). Publishing to npm runs via GitHub Actions on a `v*` tag push.
+Releases are automated. Every PR carries exactly one label that determines the next version bump:
 
-When you open a PR that should show up in the changelog:
+| Label | Effect |
+|---|---|
+| `release/patch` | Bumps the patch version (e.g. `1.1.0` → `1.1.1`) |
+| `release/minor` | Bumps the minor version (e.g. `1.1.0` → `1.2.0`) |
+| `release/major` | Bumps the major version (e.g. `1.1.0` → `2.0.0`) |
+| `release/skip`  | No version bump (use for docs-only or chore PRs) |
 
-```bash
-pnpm changeset   # pick bump type, write a user-facing summary
-```
-
-Commit the generated `.changeset/*.md` file alongside your code.
-
-To cut a release from `main`:
-
-```bash
-pnpm changeset version   # bumps packages/inkwell/package.json + writes CHANGELOG.md
-git commit -am "🚀 release: v$(node -p "require('./packages/inkwell/package.json').version")"
-git tag "v$(node -p "require('./packages/inkwell/package.json').version")"
-git push --follow-tags
-```
+When a labeled PR merges to `main`, the `auto-release` workflow batches with any other recently-merged PRs, picks the highest bump across them, tags `vX.Y.Z`, and pushes. The tag push triggers the `publish` workflow, which generates release notes from PR titles since the previous tag, drafts a GitHub Release, publishes to npm, and un-drafts.
 
-Pushing the `v*` tag triggers the publish workflow.
+Release notes live on the [GitHub Releases page](https://github.com/railwayapp/inkwell/releases). There is no in-repo `CHANGELOG.md`.
 
 ## License
 

package/dist/index.cjs

@@ -1377,6 +1377,7 @@ var InkwellEditorClient = react.forwardRef(
     );
     const overLimit = characterLimit !== void 0 && characterCount > characterLimit;
     const hasCharacterLimit = characterLimit !== void 0;
+    const showCharacterCount = characterLimit !== void 0 && characterCount >= characterLimit * 0.8;
     const getEditorState = react.useCallback(() => {
       const content2 = serializeContent();
       return {
@@ -1436,7 +1437,8 @@ var InkwellEditorClient = react.forwardRef(
     activePluginRef.current = activePlugin;
     const pluginPositionRef = react.useRef({
       top: 0,
-      left: 0
+      left: 0,
+      cursorRect: { top: 0, bottom: 0, left: 0 }
     });
     const forwardedKeyListenersRef = react.useRef(/* @__PURE__ */ new Map());
     const wrapperRef = react.useRef(null);
@@ -1547,10 +1549,14 @@ var InkwellEditorClient = react.forwardRef(
       ]
     );
     const getCursorPosition = react.useCallback(() => {
+      const empty = {
+        top: 0,
+        left: 0,
+        cursorRect: { top: 0, bottom: 0, left: 0 }
+      };
       try {
         const domSelection = window.getSelection();
-        if (!domSelection || domSelection.rangeCount === 0)
-          return { top: 0, left: 0 };
+        if (!domSelection || domSelection.rangeCount === 0) return empty;
         const range = domSelection.getRangeAt(0);
         let rect = range.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0 && domSelection.anchorNode) {
@@ -1558,14 +1564,22 @@ var InkwellEditorClient = react.forwardRef(
           if (node) rect = node.getBoundingClientRect();
         }
         const wrapperEl = wrapperRef.current;
-        if (!wrapperEl) return { top: 0, left: 0 };
+        if (!wrapperEl) return empty;
         const wrapperRect = wrapperEl.getBoundingClientRect();
+        const cursorTop = rect.top - wrapperRect.top;
+        const cursorBottom = rect.bottom - wrapperRect.top;
+        const cursorLeft = rect.left - wrapperRect.left;
         return {
-          top: rect.bottom - wrapperRect.top + 4,
-          left: rect.left - wrapperRect.left
+          top: cursorBottom + 4,
+          left: cursorLeft,
+          cursorRect: {
+            top: cursorTop,
+            bottom: cursorBottom,
+            left: cursorLeft
+          }
         };
       } catch {
-        return { top: 0, left: 0 };
+        return empty;
       }
     }, []);
     const wrapSelection = react.useCallback(
@@ -1833,7 +1847,11 @@ var InkwellEditorClient = react.forwardRef(
       query: activePlugin === plugin ? activePluginQuery : "",
       onSelect: handlePluginSelect,
       onDismiss: dismissPlugin,
-      position: pluginPositionRef.current,
+      position: {
+        top: pluginPositionRef.current.top,
+        left: pluginPositionRef.current.left
+      },
+      cursorRect: pluginPositionRef.current.cursorRect,
       editorRef: editorElRef,
       editor: pluginEditor,
       wrapSelection,
@@ -2009,7 +2027,7 @@ var InkwellEditorClient = react.forwardRef(
         className: `inkwell-editor-wrapper${hasCharacterLimit ? " inkwell-editor-has-character-limit" : ""}${overLimit ? " inkwell-editor-over-limit" : ""}${className ? ` ${className}` : ""}${classNames?.root ? ` ${classNames.root}` : ""}`,
         style: styles?.root,
         children: [
-          hasCharacterLimit && /* @__PURE__ */ jsxRuntime.jsx(
+          showCharacterCount && /* @__PURE__ */ jsxRuntime.jsx(
             CharacterCount,
             {
               count: characterCount,
@@ -2168,16 +2186,41 @@ var insertUploadedAttachment = (file, options) => {
     options.onError?.(err, file);
   });
 };
-function createAttachmentsPlugin(options) {
+function routeFiles(editor, files, options) {
   const { accept } = options;
+  const matching = accept ? files.filter((f) => mimeMatches(f.type, accept)) : files;
+  const handled = matching.filter(
+    (f) => isImageFile(f) || options.onAttachmentAdd !== void 0
+  );
+  for (const file of handled) {
+    if (isImageFile(file)) {
+      insertUploadedImage(editor, file, options);
+    } else {
+      insertUploadedAttachment(file, options);
+    }
+  }
+  const skipped = files.filter((f) => !handled.includes(f));
+  return { handled, skipped };
+}
+function createAttachmentsPlugin(options) {
   return {
     name: "attachments",
+    setup(editor) {
+      if (!options.ref) return;
+      const writableRef = options.ref;
+      writableRef.current = {
+        upload: (files) => {
+          if (files.length === 0) return;
+          routeFiles(editor, files, options);
+        }
+      };
+      return () => {
+        writableRef.current = null;
+      };
+    },
     onInsertData(data, { editor, insertData }) {
       const files = extractFiles(data);
-      const matching = accept ? files.filter((f) => mimeMatches(f.type, accept)) : files;
-      const handled = matching.filter(
-        (f) => isImageFile(f) || options.onAttachmentAdd !== void 0
-      );
+      const { handled, skipped } = routeFiles(editor, files, options);
       if (handled.length === 0) {
         const htmlImages = extractHtmlImages(data);
         if (htmlImages.length === 0) return false;
@@ -2186,16 +2229,8 @@ function createAttachmentsPlugin(options) {
         }
         return true;
       }
-      const unhandled = files.filter((f) => !handled.includes(f));
-      if (unhandled.length > 0) {
-        insertData(filesOnlyDataTransfer(unhandled));
-      }
-      for (const file of handled) {
-        if (isImageFile(file)) {
-          insertUploadedImage(editor, file, options);
-        } else {
-          insertUploadedAttachment(file, options);
-        }
+      if (skipped.length > 0) {
+        insertData(filesOnlyDataTransfer(skipped));
       }
       return true;
     }
@@ -2273,8 +2308,10 @@ function createCompletionsPlugin({
 var BASE = "inkwell-plugin-picker";
 var pluginPickerClass = {
   popup: `${BASE}-popup`,
+  popupFlipped: `${BASE}-popup-flipped`,
   picker: `${BASE}`,
   search: `${BASE}-search`,
+  list: `${BASE}-list`,
   item: `${BASE}-item`,
   itemActive: `${BASE}-item-active`,
   empty: `${BASE}-empty`,
@@ -2282,6 +2319,74 @@ var pluginPickerClass = {
   subtitle: `${BASE}-subtitle`,
   preview: `${BASE}-preview`
 };
+var POPUP_GAP = 4;
+var VIEWPORT_MARGIN = 8;
+var CURSOR_HEIGHT_FALLBACK = 20;
+function usePickerPlacement(position, cursorRect) {
+  const [popupEl, setPopupEl] = react.useState(null);
+  const [placement, setPlacement] = react.useState({ flippedAbove: false, leftOverride: null });
+  const cursorTopWrapper = cursorRect?.top ?? Math.max(0, position.top - POPUP_GAP - CURSOR_HEIGHT_FALLBACK);
+  const cursorBottomWrapper = cursorRect?.bottom ?? Math.max(0, position.top - POPUP_GAP);
+  const cursorLeftWrapper = cursorRect?.left ?? position.left;
+  react.useLayoutEffect(() => {
+    if (!popupEl) return;
+    const measure = () => {
+      const offsetParent = popupEl.offsetParent;
+      if (!(offsetParent instanceof HTMLElement)) return;
+      const wrapperRect = offsetParent.getBoundingClientRect();
+      const popupRect = popupEl.getBoundingClientRect();
+      const popupHeight = popupRect.height;
+      const popupWidth = popupRect.width;
+      const cursorTopViewport = wrapperRect.top + cursorTopWrapper;
+      const cursorBottomViewport = wrapperRect.top + cursorBottomWrapper;
+      const cursorLeftViewport = wrapperRect.left + cursorLeftWrapper;
+      const spaceBelowViewport = window.innerHeight - cursorBottomViewport - VIEWPORT_MARGIN;
+      const spaceBelowWrapper = wrapperRect.bottom - cursorBottomViewport;
+      const spaceBelow = Math.min(spaceBelowViewport, spaceBelowWrapper);
+      const spaceAbove = cursorTopViewport - VIEWPORT_MARGIN;
+      const needsFlip = popupHeight + POPUP_GAP > spaceBelow;
+      const fitsAbove = popupHeight + POPUP_GAP <= spaceAbove;
+      const flippedAbove = needsFlip && fitsAbove;
+      const maxRightViewport = window.innerWidth - VIEWPORT_MARGIN;
+      const popupRightIfDefault = cursorLeftViewport + popupWidth;
+      const leftOverride = popupRightIfDefault > maxRightViewport ? Math.max(
+        VIEWPORT_MARGIN - wrapperRect.left,
+        maxRightViewport - popupWidth - wrapperRect.left
+      ) : null;
+      setPlacement(
+        (prev) => prev.flippedAbove === flippedAbove && prev.leftOverride === leftOverride ? prev : { flippedAbove, leftOverride }
+      );
+    };
+    measure();
+    const ResizeObserverCtor = typeof window !== "undefined" ? window.ResizeObserver : void 0;
+    const resizeObserver = ResizeObserverCtor ? new ResizeObserverCtor(() => measure()) : null;
+    resizeObserver?.observe(popupEl);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [popupEl, cursorTopWrapper, cursorBottomWrapper, cursorLeftWrapper]);
+  const style = {
+    position: "absolute",
+    top: placement.flippedAbove ? cursorTopWrapper - POPUP_GAP : position.top,
+    left: placement.leftOverride ?? position.left,
+    transform: placement.flippedAbove ? "translateY(-100%)" : void 0,
+    zIndex: 1001
+  };
+  const className = placement.flippedAbove ? `${pluginPickerClass.popup} ${pluginPickerClass.popupFlipped}` : pluginPickerClass.popup;
+  return {
+    setPopupEl,
+    style,
+    className,
+    flippedAbove: placement.flippedAbove
+  };
+}
+function usePluginPopupPlacement(position, cursorRect) {
+  return usePickerPlacement(position, cursorRect);
+}
 function PluginMenuPrimitive({
   items,
   search,
@@ -2293,6 +2398,7 @@ function PluginMenuPrimitive({
   onSelect,
   onDismiss,
   position,
+  cursorRect,
   subscribeForwardedKey
 }) {
   const [selectedIndex, setSelectedIndex] = react.useState(0);
@@ -2437,16 +2543,13 @@ function PluginMenuPrimitive({
       updateSelectedIndex
     ]
   );
+  const placement = usePickerPlacement(position, cursorRect);
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       onMouseDown: (event) => event.preventDefault(),
       children: /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
@@ -2460,7 +2563,7 @@ function PluginMenuPrimitive({
           "aria-activedescendant": results.length > 0 ? activeOptionId : void 0,
           children: [
             /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.search, "aria-label": placeholder, children: query || placeholder }),
-            results.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx("div", { id: listboxId, role: "listbox", children: renderedResults })
+            results.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx("div", { id: listboxId, role: "listbox", className: pluginPickerClass.list, children: renderedResults })
           ]
         }
       )
@@ -2622,6 +2725,7 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
   onExecute,
   onDismiss,
   position,
+  cursorRect,
   getEditor
 }, ref) {
   const [mode, setMode] = react.useState("commands");
@@ -2785,17 +2889,14 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
       selectedIndex
     ]
   );
+  const placement = usePluginPopupPlacement(position, cursorRect);
   if (mode === "ready" && selectedCommand) {
     return /* @__PURE__ */ jsxRuntime.jsx(
       "div",
       {
-        className: pluginPickerClass.popup,
-        style: {
-          position: "absolute",
-          top: position.top,
-          left: position.left,
-          zIndex: 1001
-        },
+        ref: placement.setPopupEl,
+        className: placement.className,
+        style: placement.style,
         children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.picker, children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "inkwell-plugin-slash-commands-execute", children: "Enter to execute \xB7 Esc to cancel" }) })
       }
     );
@@ -2803,13 +2904,9 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: pluginPickerClass.picker, children: [
         /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.search, children: mode === "commands" ? `/${query}` : `${selectedCommand ? `/${selectedCommand.name} ` : ""}${query}` }),
         loadingArgs && items.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, children: "Loading..." }) : items.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: pluginPickerClass.empty, children: emptyMessage }) : /* @__PURE__ */ jsxRuntime.jsx(
@@ -2818,6 +2915,7 @@ var SlashCommandMenuInner = react.forwardRef(function SlashCommandMenuInner2({
             id: listboxId,
             role: "listbox",
             "aria-activedescendant": activeOptionId,
+            className: pluginPickerClass.list,
             children: items.map((item, index) => {
               const active = index === selectedIndex;
               return /* @__PURE__ */ jsxRuntime.jsxs(

package/dist/index.d.cts

@@ -180,11 +180,20 @@ interface PluginRenderProps {
     onSelect: (content: string) => void;
     /** Deactivate this plugin. */
     onDismiss: () => void;
-    /** Cursor position when the trigger fired. */
+    /** Cursor position when the trigger fired. Wrapper-relative; sits just
+     *  below the caret so a popup with `top: position.top` renders below it. */
     position: {
         top: number;
         left: number;
     };
+    /** Wrapper-relative caret bounding rect when the trigger fired. Lets pickers
+     *  flip above the caret when there isn't room below. Optional for backwards
+     *  compatibility with consumers that pass synthesized props. */
+    cursorRect?: {
+        top: number;
+        bottom: number;
+        left: number;
+    };
     /** Ref to the editable DOM element. */
     editorRef: RefObject<HTMLDivElement | null>;
     /** Narrow editor controller for plugin actions. */
@@ -271,6 +280,9 @@ interface Attachment {
      */
     [key: string]: unknown;
 }
+interface AttachmentsHandle {
+    upload: (files: File[]) => void;
+}
 interface AttachmentsPluginOptions {
     /**
      * Upload a single file and resolve to the public URL, or an object
@@ -283,6 +295,8 @@ interface AttachmentsPluginOptions {
      * (`image/*`). Files that don't match pass through untouched.
      */
     accept?: string;
+    /** Populated on editor mount, nulled on unmount. */
+    ref?: RefObject<AttachmentsHandle | null>;
     /**
      * Placeholder alt text shown on the inserted image element while an
      * image upload is in flight. Defaults to `"Uploading…"`.
@@ -475,4 +489,4 @@ declare function InkwellRenderer({ content, className, components, rehypePlugins
  */
 declare function parseMarkdown(content: string, options?: ParseMarkdownOptions): ReactNode;
 
-export { type Attachment, type AttachmentUploadResult, type AttachmentsPluginOptions, type BubbleMenuItem, type BubbleMenuItemProps, type BubbleMenuOptions, type CompletionsPluginOptions, type EmojiItem, type EmojiPluginOptions, type InkwellComponents, InkwellEditor, type InkwellEditorClassNames, type InkwellEditorFocusOptions, type InkwellEditorHandle, type InkwellEditorProps, type InkwellEditorState, type InkwellEditorStyles, type InkwellFeatures, type InkwellPlugin, type InkwellPluginActivation, type InkwellPluginEditor, type InkwellPluginPlaceholder, InkwellRenderer, type InkwellRendererProps, type MentionItem, type MentionRenderer, type MentionsPluginOptions, type ParseMarkdownOptions, type PluginInsertDataContext, type PluginKeyDownContext, type PluginRenderProps, type RehypePluginConfig, type SlashCommandArg, type SlashCommandChoice, type SlashCommandExecution, type SlashCommandItem, type SlashCommandsPluginOptions, type Snippet, type SnippetsPluginOptions, type SubscribeForwardedKey, createAttachmentsPlugin, createBubbleMenuPlugin, createCompletionsPlugin, createEmojiPlugin, createMentionsPlugin, createSlashCommandsPlugin, createSnippetsPlugin, defaultBubbleMenuItems, defaultEmojis, htmlToMarkdown, parseMarkdown };
+export { type Attachment, type AttachmentUploadResult, type AttachmentsHandle, type AttachmentsPluginOptions, type BubbleMenuItem, type BubbleMenuItemProps, type BubbleMenuOptions, type CompletionsPluginOptions, type EmojiItem, type EmojiPluginOptions, type InkwellComponents, InkwellEditor, type InkwellEditorClassNames, type InkwellEditorFocusOptions, type InkwellEditorHandle, type InkwellEditorProps, type InkwellEditorState, type InkwellEditorStyles, type InkwellFeatures, type InkwellPlugin, type InkwellPluginActivation, type InkwellPluginEditor, type InkwellPluginPlaceholder, InkwellRenderer, type InkwellRendererProps, type MentionItem, type MentionRenderer, type MentionsPluginOptions, type ParseMarkdownOptions, type PluginInsertDataContext, type PluginKeyDownContext, type PluginRenderProps, type RehypePluginConfig, type SlashCommandArg, type SlashCommandChoice, type SlashCommandExecution, type SlashCommandItem, type SlashCommandsPluginOptions, type Snippet, type SnippetsPluginOptions, type SubscribeForwardedKey, createAttachmentsPlugin, createBubbleMenuPlugin, createCompletionsPlugin, createEmojiPlugin, createMentionsPlugin, createSlashCommandsPlugin, createSnippetsPlugin, defaultBubbleMenuItems, defaultEmojis, htmlToMarkdown, parseMarkdown };

package/dist/index.d.ts

@@ -180,11 +180,20 @@ interface PluginRenderProps {
     onSelect: (content: string) => void;
     /** Deactivate this plugin. */
     onDismiss: () => void;
-    /** Cursor position when the trigger fired. */
+    /** Cursor position when the trigger fired. Wrapper-relative; sits just
+     *  below the caret so a popup with `top: position.top` renders below it. */
     position: {
         top: number;
         left: number;
     };
+    /** Wrapper-relative caret bounding rect when the trigger fired. Lets pickers
+     *  flip above the caret when there isn't room below. Optional for backwards
+     *  compatibility with consumers that pass synthesized props. */
+    cursorRect?: {
+        top: number;
+        bottom: number;
+        left: number;
+    };
     /** Ref to the editable DOM element. */
     editorRef: RefObject<HTMLDivElement | null>;
     /** Narrow editor controller for plugin actions. */
@@ -271,6 +280,9 @@ interface Attachment {
      */
     [key: string]: unknown;
 }
+interface AttachmentsHandle {
+    upload: (files: File[]) => void;
+}
 interface AttachmentsPluginOptions {
     /**
      * Upload a single file and resolve to the public URL, or an object
@@ -283,6 +295,8 @@ interface AttachmentsPluginOptions {
      * (`image/*`). Files that don't match pass through untouched.
      */
     accept?: string;
+    /** Populated on editor mount, nulled on unmount. */
+    ref?: RefObject<AttachmentsHandle | null>;
     /**
      * Placeholder alt text shown on the inserted image element while an
      * image upload is in flight. Defaults to `"Uploading…"`.
@@ -475,4 +489,4 @@ declare function InkwellRenderer({ content, className, components, rehypePlugins
  */
 declare function parseMarkdown(content: string, options?: ParseMarkdownOptions): ReactNode;
 
-export { type Attachment, type AttachmentUploadResult, type AttachmentsPluginOptions, type BubbleMenuItem, type BubbleMenuItemProps, type BubbleMenuOptions, type CompletionsPluginOptions, type EmojiItem, type EmojiPluginOptions, type InkwellComponents, InkwellEditor, type InkwellEditorClassNames, type InkwellEditorFocusOptions, type InkwellEditorHandle, type InkwellEditorProps, type InkwellEditorState, type InkwellEditorStyles, type InkwellFeatures, type InkwellPlugin, type InkwellPluginActivation, type InkwellPluginEditor, type InkwellPluginPlaceholder, InkwellRenderer, type InkwellRendererProps, type MentionItem, type MentionRenderer, type MentionsPluginOptions, type ParseMarkdownOptions, type PluginInsertDataContext, type PluginKeyDownContext, type PluginRenderProps, type RehypePluginConfig, type SlashCommandArg, type SlashCommandChoice, type SlashCommandExecution, type SlashCommandItem, type SlashCommandsPluginOptions, type Snippet, type SnippetsPluginOptions, type SubscribeForwardedKey, createAttachmentsPlugin, createBubbleMenuPlugin, createCompletionsPlugin, createEmojiPlugin, createMentionsPlugin, createSlashCommandsPlugin, createSnippetsPlugin, defaultBubbleMenuItems, defaultEmojis, htmlToMarkdown, parseMarkdown };
+export { type Attachment, type AttachmentUploadResult, type AttachmentsHandle, type AttachmentsPluginOptions, type BubbleMenuItem, type BubbleMenuItemProps, type BubbleMenuOptions, type CompletionsPluginOptions, type EmojiItem, type EmojiPluginOptions, type InkwellComponents, InkwellEditor, type InkwellEditorClassNames, type InkwellEditorFocusOptions, type InkwellEditorHandle, type InkwellEditorProps, type InkwellEditorState, type InkwellEditorStyles, type InkwellFeatures, type InkwellPlugin, type InkwellPluginActivation, type InkwellPluginEditor, type InkwellPluginPlaceholder, InkwellRenderer, type InkwellRendererProps, type MentionItem, type MentionRenderer, type MentionsPluginOptions, type ParseMarkdownOptions, type PluginInsertDataContext, type PluginKeyDownContext, type PluginRenderProps, type RehypePluginConfig, type SlashCommandArg, type SlashCommandChoice, type SlashCommandExecution, type SlashCommandItem, type SlashCommandsPluginOptions, type Snippet, type SnippetsPluginOptions, type SubscribeForwardedKey, createAttachmentsPlugin, createBubbleMenuPlugin, createCompletionsPlugin, createEmojiPlugin, createMentionsPlugin, createSlashCommandsPlugin, createSnippetsPlugin, defaultBubbleMenuItems, defaultEmojis, htmlToMarkdown, parseMarkdown };

package/dist/index.js

@@ -1362,6 +1362,7 @@ var InkwellEditorClient = forwardRef(
     );
     const overLimit = characterLimit !== void 0 && characterCount > characterLimit;
     const hasCharacterLimit = characterLimit !== void 0;
+    const showCharacterCount = characterLimit !== void 0 && characterCount >= characterLimit * 0.8;
     const getEditorState = useCallback(() => {
       const content2 = serializeContent();
       return {
@@ -1421,7 +1422,8 @@ var InkwellEditorClient = forwardRef(
     activePluginRef.current = activePlugin;
     const pluginPositionRef = useRef({
       top: 0,
-      left: 0
+      left: 0,
+      cursorRect: { top: 0, bottom: 0, left: 0 }
     });
     const forwardedKeyListenersRef = useRef(/* @__PURE__ */ new Map());
     const wrapperRef = useRef(null);
@@ -1532,10 +1534,14 @@ var InkwellEditorClient = forwardRef(
       ]
     );
     const getCursorPosition = useCallback(() => {
+      const empty = {
+        top: 0,
+        left: 0,
+        cursorRect: { top: 0, bottom: 0, left: 0 }
+      };
       try {
         const domSelection = window.getSelection();
-        if (!domSelection || domSelection.rangeCount === 0)
-          return { top: 0, left: 0 };
+        if (!domSelection || domSelection.rangeCount === 0) return empty;
         const range = domSelection.getRangeAt(0);
         let rect = range.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0 && domSelection.anchorNode) {
@@ -1543,14 +1549,22 @@ var InkwellEditorClient = forwardRef(
           if (node) rect = node.getBoundingClientRect();
         }
         const wrapperEl = wrapperRef.current;
-        if (!wrapperEl) return { top: 0, left: 0 };
+        if (!wrapperEl) return empty;
         const wrapperRect = wrapperEl.getBoundingClientRect();
+        const cursorTop = rect.top - wrapperRect.top;
+        const cursorBottom = rect.bottom - wrapperRect.top;
+        const cursorLeft = rect.left - wrapperRect.left;
         return {
-          top: rect.bottom - wrapperRect.top + 4,
-          left: rect.left - wrapperRect.left
+          top: cursorBottom + 4,
+          left: cursorLeft,
+          cursorRect: {
+            top: cursorTop,
+            bottom: cursorBottom,
+            left: cursorLeft
+          }
         };
       } catch {
-        return { top: 0, left: 0 };
+        return empty;
       }
     }, []);
     const wrapSelection = useCallback(
@@ -1818,7 +1832,11 @@ var InkwellEditorClient = forwardRef(
       query: activePlugin === plugin ? activePluginQuery : "",
       onSelect: handlePluginSelect,
       onDismiss: dismissPlugin,
-      position: pluginPositionRef.current,
+      position: {
+        top: pluginPositionRef.current.top,
+        left: pluginPositionRef.current.left
+      },
+      cursorRect: pluginPositionRef.current.cursorRect,
       editorRef: editorElRef,
       editor: pluginEditor,
       wrapSelection,
@@ -1994,7 +2012,7 @@ var InkwellEditorClient = forwardRef(
         className: `inkwell-editor-wrapper${hasCharacterLimit ? " inkwell-editor-has-character-limit" : ""}${overLimit ? " inkwell-editor-over-limit" : ""}${className ? ` ${className}` : ""}${classNames?.root ? ` ${classNames.root}` : ""}`,
         style: styles?.root,
         children: [
-          hasCharacterLimit && /* @__PURE__ */ jsx(
+          showCharacterCount && /* @__PURE__ */ jsx(
             CharacterCount,
             {
               count: characterCount,
@@ -2153,16 +2171,41 @@ var insertUploadedAttachment = (file, options) => {
     options.onError?.(err, file);
   });
 };
-function createAttachmentsPlugin(options) {
+function routeFiles(editor, files, options) {
   const { accept } = options;
+  const matching = accept ? files.filter((f) => mimeMatches(f.type, accept)) : files;
+  const handled = matching.filter(
+    (f) => isImageFile(f) || options.onAttachmentAdd !== void 0
+  );
+  for (const file of handled) {
+    if (isImageFile(file)) {
+      insertUploadedImage(editor, file, options);
+    } else {
+      insertUploadedAttachment(file, options);
+    }
+  }
+  const skipped = files.filter((f) => !handled.includes(f));
+  return { handled, skipped };
+}
+function createAttachmentsPlugin(options) {
   return {
     name: "attachments",
+    setup(editor) {
+      if (!options.ref) return;
+      const writableRef = options.ref;
+      writableRef.current = {
+        upload: (files) => {
+          if (files.length === 0) return;
+          routeFiles(editor, files, options);
+        }
+      };
+      return () => {
+        writableRef.current = null;
+      };
+    },
     onInsertData(data, { editor, insertData }) {
       const files = extractFiles(data);
-      const matching = accept ? files.filter((f) => mimeMatches(f.type, accept)) : files;
-      const handled = matching.filter(
-        (f) => isImageFile(f) || options.onAttachmentAdd !== void 0
-      );
+      const { handled, skipped } = routeFiles(editor, files, options);
       if (handled.length === 0) {
         const htmlImages = extractHtmlImages(data);
         if (htmlImages.length === 0) return false;
@@ -2171,16 +2214,8 @@ function createAttachmentsPlugin(options) {
         }
         return true;
       }
-      const unhandled = files.filter((f) => !handled.includes(f));
-      if (unhandled.length > 0) {
-        insertData(filesOnlyDataTransfer(unhandled));
-      }
-      for (const file of handled) {
-        if (isImageFile(file)) {
-          insertUploadedImage(editor, file, options);
-        } else {
-          insertUploadedAttachment(file, options);
-        }
+      if (skipped.length > 0) {
+        insertData(filesOnlyDataTransfer(skipped));
       }
       return true;
     }
@@ -2258,8 +2293,10 @@ function createCompletionsPlugin({
 var BASE = "inkwell-plugin-picker";
 var pluginPickerClass = {
   popup: `${BASE}-popup`,
+  popupFlipped: `${BASE}-popup-flipped`,
   picker: `${BASE}`,
   search: `${BASE}-search`,
+  list: `${BASE}-list`,
   item: `${BASE}-item`,
   itemActive: `${BASE}-item-active`,
   empty: `${BASE}-empty`,
@@ -2267,6 +2304,74 @@ var pluginPickerClass = {
   subtitle: `${BASE}-subtitle`,
   preview: `${BASE}-preview`
 };
+var POPUP_GAP = 4;
+var VIEWPORT_MARGIN = 8;
+var CURSOR_HEIGHT_FALLBACK = 20;
+function usePickerPlacement(position, cursorRect) {
+  const [popupEl, setPopupEl] = useState(null);
+  const [placement, setPlacement] = useState({ flippedAbove: false, leftOverride: null });
+  const cursorTopWrapper = cursorRect?.top ?? Math.max(0, position.top - POPUP_GAP - CURSOR_HEIGHT_FALLBACK);
+  const cursorBottomWrapper = cursorRect?.bottom ?? Math.max(0, position.top - POPUP_GAP);
+  const cursorLeftWrapper = cursorRect?.left ?? position.left;
+  useLayoutEffect(() => {
+    if (!popupEl) return;
+    const measure = () => {
+      const offsetParent = popupEl.offsetParent;
+      if (!(offsetParent instanceof HTMLElement)) return;
+      const wrapperRect = offsetParent.getBoundingClientRect();
+      const popupRect = popupEl.getBoundingClientRect();
+      const popupHeight = popupRect.height;
+      const popupWidth = popupRect.width;
+      const cursorTopViewport = wrapperRect.top + cursorTopWrapper;
+      const cursorBottomViewport = wrapperRect.top + cursorBottomWrapper;
+      const cursorLeftViewport = wrapperRect.left + cursorLeftWrapper;
+      const spaceBelowViewport = window.innerHeight - cursorBottomViewport - VIEWPORT_MARGIN;
+      const spaceBelowWrapper = wrapperRect.bottom - cursorBottomViewport;
+      const spaceBelow = Math.min(spaceBelowViewport, spaceBelowWrapper);
+      const spaceAbove = cursorTopViewport - VIEWPORT_MARGIN;
+      const needsFlip = popupHeight + POPUP_GAP > spaceBelow;
+      const fitsAbove = popupHeight + POPUP_GAP <= spaceAbove;
+      const flippedAbove = needsFlip && fitsAbove;
+      const maxRightViewport = window.innerWidth - VIEWPORT_MARGIN;
+      const popupRightIfDefault = cursorLeftViewport + popupWidth;
+      const leftOverride = popupRightIfDefault > maxRightViewport ? Math.max(
+        VIEWPORT_MARGIN - wrapperRect.left,
+        maxRightViewport - popupWidth - wrapperRect.left
+      ) : null;
+      setPlacement(
+        (prev) => prev.flippedAbove === flippedAbove && prev.leftOverride === leftOverride ? prev : { flippedAbove, leftOverride }
+      );
+    };
+    measure();
+    const ResizeObserverCtor = typeof window !== "undefined" ? window.ResizeObserver : void 0;
+    const resizeObserver = ResizeObserverCtor ? new ResizeObserverCtor(() => measure()) : null;
+    resizeObserver?.observe(popupEl);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [popupEl, cursorTopWrapper, cursorBottomWrapper, cursorLeftWrapper]);
+  const style = {
+    position: "absolute",
+    top: placement.flippedAbove ? cursorTopWrapper - POPUP_GAP : position.top,
+    left: placement.leftOverride ?? position.left,
+    transform: placement.flippedAbove ? "translateY(-100%)" : void 0,
+    zIndex: 1001
+  };
+  const className = placement.flippedAbove ? `${pluginPickerClass.popup} ${pluginPickerClass.popupFlipped}` : pluginPickerClass.popup;
+  return {
+    setPopupEl,
+    style,
+    className,
+    flippedAbove: placement.flippedAbove
+  };
+}
+function usePluginPopupPlacement(position, cursorRect) {
+  return usePickerPlacement(position, cursorRect);
+}
 function PluginMenuPrimitive({
   items,
   search,
@@ -2278,6 +2383,7 @@ function PluginMenuPrimitive({
   onSelect,
   onDismiss,
   position,
+  cursorRect,
   subscribeForwardedKey
 }) {
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -2422,16 +2528,13 @@ function PluginMenuPrimitive({
       updateSelectedIndex
     ]
   );
+  const placement = usePickerPlacement(position, cursorRect);
   return /* @__PURE__ */ jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       onMouseDown: (event) => event.preventDefault(),
       children: /* @__PURE__ */ jsxs(
         "div",
@@ -2445,7 +2548,7 @@ function PluginMenuPrimitive({
           "aria-activedescendant": results.length > 0 ? activeOptionId : void 0,
           children: [
             /* @__PURE__ */ jsx("div", { className: pluginPickerClass.search, "aria-label": placeholder, children: query || placeholder }),
-            results.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsx("div", { id: listboxId, role: "listbox", children: renderedResults })
+            results.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, role: "status", children: emptyMessage }) : /* @__PURE__ */ jsx("div", { id: listboxId, role: "listbox", className: pluginPickerClass.list, children: renderedResults })
           ]
         }
       )
@@ -2607,6 +2710,7 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
   onExecute,
   onDismiss,
   position,
+  cursorRect,
   getEditor
 }, ref) {
   const [mode, setMode] = useState("commands");
@@ -2770,17 +2874,14 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
       selectedIndex
     ]
   );
+  const placement = usePluginPopupPlacement(position, cursorRect);
   if (mode === "ready" && selectedCommand) {
     return /* @__PURE__ */ jsx(
       "div",
       {
-        className: pluginPickerClass.popup,
-        style: {
-          position: "absolute",
-          top: position.top,
-          left: position.left,
-          zIndex: 1001
-        },
+        ref: placement.setPopupEl,
+        className: placement.className,
+        style: placement.style,
         children: /* @__PURE__ */ jsx("div", { className: pluginPickerClass.picker, children: /* @__PURE__ */ jsx("div", { className: "inkwell-plugin-slash-commands-execute", children: "Enter to execute \xB7 Esc to cancel" }) })
       }
     );
@@ -2788,13 +2889,9 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
   return /* @__PURE__ */ jsx(
     "div",
     {
-      className: pluginPickerClass.popup,
-      style: {
-        position: "absolute",
-        top: position.top,
-        left: position.left,
-        zIndex: 1001
-      },
+      ref: placement.setPopupEl,
+      className: placement.className,
+      style: placement.style,
       children: /* @__PURE__ */ jsxs("div", { className: pluginPickerClass.picker, children: [
         /* @__PURE__ */ jsx("div", { className: pluginPickerClass.search, children: mode === "commands" ? `/${query}` : `${selectedCommand ? `/${selectedCommand.name} ` : ""}${query}` }),
         loadingArgs && items.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, children: "Loading..." }) : items.length === 0 ? /* @__PURE__ */ jsx("div", { className: pluginPickerClass.empty, children: emptyMessage }) : /* @__PURE__ */ jsx(
@@ -2803,6 +2900,7 @@ var SlashCommandMenuInner = forwardRef(function SlashCommandMenuInner2({
             id: listboxId,
             role: "listbox",
             "aria-activedescendant": activeOptionId,
+            className: pluginPickerClass.list,
             children: items.map((item, index) => {
               const active = index === selectedIndex;
               return /* @__PURE__ */ jsxs(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@railway/inkwell",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Inkwell is a Markdown editor and renderer for React with an extensible plugin system.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -63,6 +63,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/mdast": "^4.0.4",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",

package/src/styles.css

@@ -31,6 +31,7 @@
   --inkwell-accent: hsl(217, 91%, 50%);
   --inkwell-accent-soft: hsla(217, 91%, 50%, 0.12);
   --inkwell-danger: hsl(0, 72%, 51%);
+  --inkwell-danger-soft: hsla(0, 72%, 51%, 0.14);
 
   /* Inline code */
   --inkwell-code-bg: hsl(220, 14%, 94%);
@@ -61,6 +62,8 @@
 
     --inkwell-accent: hsl(217, 91%, 65%);
     --inkwell-accent-soft: hsla(217, 91%, 65%, 0.16);
+    --inkwell-danger: hsl(0, 70%, 65%);
+    --inkwell-danger-soft: hsla(0, 70%, 65%, 0.18);
 
     --inkwell-code-bg: hsl(220, 13%, 18%);
     --inkwell-code-fg: hsl(340, 70%, 75%);
@@ -72,21 +75,34 @@
 .inkwell-editor-wrapper {
   position: relative;
 }
-.inkwell-editor {
-  min-height: 200px;
+
+/* Visual-chrome defaults (padding, border, background, type) are wrapped in
+   `:where()` so they carry 0,0,0 specificity. Any single-class consumer rule
+   on `.inkwell-editor` (Tailwind utilities, `classNames.editor`, etc.) wins
+   automatically — no `!important` or selector gymnastics needed.
+
+   Container size (min-height, max-height, height) is deliberately NOT
+   defaulted here. Inkwell sits inside the consumer's layout and the right
+   size is a consumer decision: a full-page editor wants `min-height: 60vh`,
+   a chat composer wants `min-height: 0`, a panel just wants to fill its
+   container. Set it on the editor via `styles.editor`, `classNames.editor`,
+   or your own CSS. */
+:where(.inkwell-editor) {
   padding: 1rem 1.25rem;
-  outline: none;
   border: 1px solid var(--inkwell-border);
   border-radius: var(--inkwell-radius);
   background: var(--inkwell-bg);
-  color: var(--inkwell-text);
   line-height: 1.6;
   font-size: 0.95rem;
   transition: border-color 0.15s ease;
 }
-.inkwell-editor:focus-within {
+:where(.inkwell-editor:focus-within) {
   border-color: var(--inkwell-border-strong);
 }
+.inkwell-editor {
+  outline: none;
+  color: var(--inkwell-text);
+}
 
 .inkwell-editor p {
   margin: 0;
@@ -162,34 +178,35 @@
   height: auto;
 }
 
-/* Built-in character count. Anchored to the bottom-right of the editor
-   wrapper. `characterLimit` is a soft hint — typing past the limit is
-   allowed; the count turns red and the wrapper picks up
-   `.inkwell-editor-over-limit`, which paints a red ring on the editor
-   surface so it's visually obvious the document is over budget. */
+/* Built-in character count. Overlays the top-right corner of the editor
+   wrapper so it never shifts content, and sits on a solid surface tint
+   so it visually layers above any text that wraps underneath. Only
+   rendered once typing reaches 80% of `characterLimit`, since the
+   limit is a soft hint — typing past it is allowed; the count then
+   turns red and the wrapper picks up `.inkwell-editor-over-limit`,
+   which paints a soft red halo on the editor surface so it's visually
+   obvious the document is over budget. */
 .inkwell-editor-character-count {
   position: absolute;
-  right: 0.7rem;
-  bottom: 0.7rem;
+  top: 0.5rem;
+  right: 0.5rem;
   z-index: 10;
-  padding: 0.15rem 0.45rem;
+  padding: 0.1rem 0.4rem;
   font-size: 0.72rem;
   font-variant-numeric: tabular-nums;
   color: var(--inkwell-text-dim);
+  background: var(--inkwell-bg);
+  border-radius: calc(var(--inkwell-radius) - 2px);
   pointer-events: none;
   user-select: none;
 }
 .inkwell-editor-character-count-over {
-  color: hsl(0, 75%, 55%);
+  color: var(--inkwell-danger);
   font-weight: 500;
 }
-.inkwell-editor-wrapper.inkwell-editor-has-character-limit .inkwell-editor {
-  padding-right: 5.25rem;
-  padding-bottom: 2.25rem;
-}
 .inkwell-editor-wrapper.inkwell-editor-over-limit .inkwell-editor {
-  border-color: hsl(0, 75%, 55%);
-  box-shadow: 0 0 0 1px hsl(0, 75%, 55%);
+  border-color: var(--inkwell-danger-soft);
+  box-shadow: 0 0 0 3px var(--inkwell-danger-soft);
 }
 
 .inkwell-editor-backtick,
@@ -303,6 +320,28 @@
 .inkwell-plugin-picker-search::placeholder {
   color: var(--inkwell-text-dim);
 }
+.inkwell-plugin-picker-list {
+  max-height: 240px;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: var(--inkwell-border-strong) transparent;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar {
+  width: 8px;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-track {
+  background: transparent;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-thumb {
+  background-color: var(--inkwell-border-strong);
+  border-radius: 4px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+.inkwell-plugin-picker-list::-webkit-scrollbar-thumb:hover {
+  background-color: var(--inkwell-text-dim);
+}
 .inkwell-plugin-picker-item {
   padding: 7px 10px;
   cursor: pointer;
@@ -348,9 +387,13 @@
 
 /* ── Renderer ────────────────────────────────────────────────────── */
 
-.inkwell-renderer {
+/* Layout defaults on the renderer follow the same low-specificity pattern
+   as the editor — a single-class consumer rule wins automatically. */
+:where(.inkwell-renderer) {
   line-height: 1.65;
   font-size: 0.95rem;
+}
+.inkwell-renderer {
   color: var(--inkwell-text);
 }
 .inkwell-renderer :first-child {