bsky-richtext-react 1.0.2 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.0] — 2026-02-18
+
+### Breaking Changes
+
+- **Upgraded all `@tiptap/*` dependencies from v2 to v3** (`^3.20.0`). Consumers must update their installed `@tiptap/*` packages to v3.
+- **Replaced `tippy.js` with `@floating-ui/dom`** for mention suggestion popup positioning, aligning with the tiptap v3 ecosystem. The `tippy.js` peer dependency has been removed.
+- **Peer dependency requirements changed**: consumers must install `@tiptap/*@^3.20.0` and `@floating-ui/dom@^1.6.0`. The `tippy.js` peer dependency is no longer required.
+
+### Why
+
+- Fixes Turbopack build failures in Next.js 16+ when the consumer's dependency tree includes tiptap v3 packages (e.g., via `@tiptap/starter-kit@3.x`). Turbopack's strict static export analysis caught that `@tiptap/extension-list@3.x` imports symbols from `@tiptap/core` that don't exist in v2.
+- Aligns with the tiptap v3 ecosystem (`tippy.js` → `@floating-ui/dom`).
+
+### Migration
+
+```diff
+- "@tiptap/core": "^2.x.x",
++ "@tiptap/core": "^3.20.0",
+  // repeat for all @tiptap/* packages
+
+- "tippy.js": "^6.x.x",
++ "@floating-ui/dom": "^1.6.0",
+```
+
+---
+
+## [2.0.0] — 2026-02-18
+
+### Breaking Changes
+
+- **tiptap upgraded from v2 to v3** — all `@tiptap/*` peer dependencies must be updated to `^3.20.0`.
+- **`tippy.js` replaced with `@floating-ui/dom`** — the mention suggestion popup now uses `@floating-ui/dom` for positioning. Remove `tippy.js` from your dependencies and install `@floating-ui/dom` instead.
+
+### Migration
+
+```diff
+- bun add @tiptap/core@^2 @tiptap/react@^2 ... tippy.js
++ bun add @tiptap/core@^3.20.0 @tiptap/react@^3.20.0 ... @floating-ui/dom
+```
+
+Update all `@tiptap/*` peer dependencies to `^3.20.0` and replace `tippy.js` with `@floating-ui/dom`.
+
+---
+
+## [1.1.0] — 2026-02-17
+
+### Changed
+
+- **Default classNames now use Tailwind CSS utility classes** instead of the previous BEM-style class names (`bsky-editor`, `bsky-richtext`, etc.). All components have sensible out-of-the-box appearance as long as Tailwind is configured in the consumer's project — no extra setup needed.
+  - `defaultDisplayClassNames` — mentions, links, and tags are styled `text-blue-500 hover:underline`.
+  - `defaultEditorClassNames` — editor root is `block w-full relative`; mention chips and autolinks are `inline text-blue-500`.
+  - `defaultSuggestionClassNames` — dropdown has full visual defaults: `bg-white rounded-lg shadow-lg border`, hover states, avatar layout, truncated text columns.
+- **`styles.css` removed from the published package.** The `bsky-richtext-react/styles.css` sub-export and the `./dist/styles.css` artefact no longer exist. Remove any `import 'bsky-richtext-react/styles.css'` from your app.
+- **`sideEffects` set to `false`** — the package no longer has CSS side effects, enabling full tree-shaking.
+- **Tailwind added as a `devDependency`** — used exclusively in Storybook for development/testing. Not bundled in or required by consumers.
+- The `classNames` prop API and `generateClassNames()` are unchanged — all existing override patterns continue to work.
+
+### Migration
+
+```diff
+- import 'bsky-richtext-react/styles.css'
+  import { RichTextEditor } from 'bsky-richtext-react'
+```
+
+If you were targeting the old BEM class names in your own CSS, replace them with the `classNames` prop or `generateClassNames()` to apply your own classes directly.
+
+---
+
 ## [1.0.2] — 2026-02-17
 
 ### Fixed

package/README.md

@@ -14,7 +14,7 @@
 - **`<RichTextDisplay>`** — Render AT Protocol richtext records (`text` + `facets`) as interactive HTML. Handles @mentions, links, and #hashtags with fully customisable renderers and URL resolvers.
 - **`<RichTextEditor>`** — TipTap-based editor with real-time @mention autocomplete (powered by the **Bluesky public API** by default — no auth required), stateless URL decoration, undo/redo, and an imperative ref API.
 - **`generateClassNames()`** — Deep-merge utility for the `classNames` prop system. Pass an array of partial classNames objects and get one merged result, optionally using your own `cn()` / `clsx` / `tailwind-merge` utility.
-- **Headless by design** — Ships with layout-only CSS. Bring your own colours, fonts, and borders.
+- **Tailwind defaults, fully overridable** — Default classNames use Tailwind utility classes out of the box. Override any part via the `classNames` prop — no stylesheet import needed.
 - **Fully typed** — TypeScript-first with complete type definitions for all AT Protocol facet types.
 - **Tree-shakeable** — ESM + CJS dual build via `tsup`.
 
@@ -36,7 +36,16 @@ pnpm add bsky-richtext-react
 Peer dependencies (if not already installed):
 
 ```bash
-bun add react react-dom
+bun add react react-dom @floating-ui/dom \
+  @tiptap/core@^3.20.0 \
+  @tiptap/extension-document@^3.20.0 \
+  @tiptap/extension-hard-break@^3.20.0 \
+  @tiptap/extension-history@^3.20.0 \
+  @tiptap/extension-mention@^3.20.0 \
+  @tiptap/extension-paragraph@^3.20.0 \
+  @tiptap/extension-placeholder@^3.20.0 \
+  @tiptap/extension-text@^3.20.0 \
+  @tiptap/react@^3.20.0
 ```
 
 ---
@@ -47,7 +56,6 @@ bun add react react-dom
 
 ```tsx
 import { RichTextDisplay } from 'bsky-richtext-react'
-import 'bsky-richtext-react/styles.css'
 
 // Pass raw fields from an app.bsky.feed.post record
 export function Post({ post }) {
@@ -59,7 +67,6 @@ export function Post({ post }) {
 
 ```tsx
 import { RichTextEditor } from 'bsky-richtext-react'
-import 'bsky-richtext-react/styles.css'
 
 export function Composer() {
   return (
@@ -81,84 +88,13 @@ export function Composer() {
 
 ## Styling
 
-### 1. Import the structural CSS
+The library ships **no CSS file**. All default styles are Tailwind utility classes applied through the `classNames` prop system. As long as Tailwind is configured in your project, components look good with zero extra setup.
 
-```ts
-import 'bsky-richtext-react/styles.css'
-```
+### 1. Defaults — Tailwind utility classes
 
-This only sets `display`, `word-break`, `box-sizing`, and flex layout rules. **No colours, fonts, or borders are applied.** You control all visual styling.
-
-### 2. Target the default class names
-
-Every element rendered by the components carries a predictable CSS class that you can target directly:
-
-#### `<RichTextDisplay>`
-
-| Class | Element |
-|-------|---------|
-| `.bsky-richtext` | Root `<span>` |
-| `.bsky-mention` | @mention `<a>` |
-| `.bsky-link` | Link `<a>` |
-| `.bsky-tag` | #hashtag `<a>` |
-
-#### `<RichTextEditor>`
-
-| Class | Element |
-|-------|---------|
-| `.bsky-editor` | Root wrapper `<div>` |
-| `.bsky-editor-content` | ProseMirror wrapper |
-| `.bsky-editor-mention` | Mention chip inside editor |
-| `.autolink` | URL decoration span inside editor |
-
-#### `<MentionSuggestionList>` (dropdown)
-
-| Class | Element |
-|-------|---------|
-| `.bsky-suggestions` | Outer container |
-| `.bsky-suggestion-item` | Each suggestion row (`<button>`) |
-| `.bsky-suggestion-item-selected` | Currently highlighted row |
-| `.bsky-suggestion-avatar` | Avatar wrapper |
-| `.bsky-suggestion-avatar-img` | `<img>` element |
-| `.bsky-suggestion-avatar-placeholder` | Initial-letter fallback |
-| `.bsky-suggestion-text` | Text column (name + handle) |
-| `.bsky-suggestion-name` | Display name |
-| `.bsky-suggestion-handle` | `@handle` |
-| `.bsky-suggestion-empty` | "No results" message |
-
-```css
-/* Example: style the editor */
-.bsky-editor .ProseMirror {
-  padding: 12px 16px;
-  border: 1px solid #e1e4e8;
-  border-radius: 8px;
-  font-size: 16px;
-  line-height: 1.5;
-  min-height: 120px;
-}
+Every component has a set of default Tailwind classes applied out of the box (see `defaultEditorClassNames`, `defaultDisplayClassNames`, `defaultSuggestionClassNames`). No stylesheet import is required.
 
-/* Example: style mentions in a post */
-.bsky-mention {
-  color: #0085ff;
-  font-weight: 600;
-  text-decoration: none;
-}
-.bsky-mention:hover { text-decoration: underline; }
-
-/* Example: style the suggestion dropdown */
-.bsky-suggestions {
-  background: #fff;
-  border: 1px solid #e1e4e8;
-  border-radius: 8px;
-  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
-  min-width: 240px;
-  padding: 4px;
-}
-.bsky-suggestion-item { padding: 8px 10px; border-radius: 6px; }
-.bsky-suggestion-item-selected { background: #f0f4ff; }
-```
-
-### 3. Use `generateClassNames()` for targeted overrides
+### 2. Use `generateClassNames()` for targeted overrides
 
 The `classNames` prop on each component accepts a nested object. Use `generateClassNames()` to cleanly layer your classes on top of the defaults without rewriting them from scratch:
 
@@ -205,7 +141,9 @@ Pass a plain object to skip the defaults entirely:
 <RichTextDisplay classNames={{ root: 'my-text', mention: 'my-mention' }} />
 ```
 
-### 4. Tailwind integration
+### 3. Using `tailwind-merge` to deduplicate classes
+
+When layering your own Tailwind classes on top of the defaults, use `tailwind-merge` as the `cn` argument to avoid conflicting class duplication:
 
 ```tsx
 import { twMerge } from 'tailwind-merge'
@@ -295,7 +233,7 @@ import { RichTextEditor } from 'bsky-richtext-react'
 | `onMentionQuery` | `(query: string) => Promise<MentionSuggestion[]>` | **Bluesky public API** | Custom mention search. Overrides the built-in search. |
 | `mentionSearchDebounceMs` | `number` | `300` | Debounce delay (ms) for the built-in search. No effect when `onMentionQuery` is set. |
 | `disableDefaultMentionSearch` | `boolean` | `false` | Disable the built-in Bluesky API search entirely |
-| `renderMentionSuggestion` | `SuggestionOptions['render']` | tippy.js popup | Custom TipTap suggestion renderer factory |
+| `renderMentionSuggestion` | `SuggestionOptions['render']` | @floating-ui/dom popup | Custom TipTap suggestion renderer factory |
 | `mentionSuggestionOptions` | `DefaultSuggestionRendererOptions` | — | Options forwarded to the default renderer |
 | `editorRef` | `Ref<RichTextEditorRef>` | — | Imperative ref |
 | `editable` | `boolean` | `true` | Toggle read-only mode |
@@ -352,7 +290,7 @@ The editor searches Bluesky actors **by default** when the user types `@`:
 
 ### `<MentionSuggestionList>`
 
-The default suggestion dropdown rendered inside the tippy.js popup. Exported so you can reuse or reference it in your own popup implementation.
+The default suggestion dropdown rendered inside the @floating-ui/dom popup. Exported so you can reuse or reference it in your own popup implementation.
 
 ```tsx
 import { MentionSuggestionList } from 'bsky-richtext-react'
@@ -578,6 +516,24 @@ bun run format
 
 ---
 
+## Migration
+
+### v2.0.0 — tiptap v3 upgrade
+
+**v2.0.0 upgrades tiptap from v2 to v3.** If you are upgrading from v1.x, you must:
+
+1. Update all `@tiptap/*` peer dependencies to `^3.20.0`.
+2. Replace `tippy.js` with `@floating-ui/dom`.
+
+```diff
+- bun add @tiptap/core@^2 @tiptap/react@^2 tippy.js
++ bun add @tiptap/core@^3.20.0 @tiptap/react@^3.20.0 @floating-ui/dom
+```
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full list of changes.
+
+---
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md).

package/dist/index.cjs

@@ -11,15 +11,11 @@ var extensionHardBreak = require('@tiptap/extension-hard-break');
 var extensionPlaceholder = require('@tiptap/extension-placeholder');
 var api = require('@atproto/api');
 var extensionMention = require('@tiptap/extension-mention');
-var tippy = require('tippy.js');
+var dom = require('@floating-ui/dom');
 var core = require('@tiptap/core');
 var state = require('@tiptap/pm/state');
 var view = require('@tiptap/pm/view');
 
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-var tippy__default = /*#__PURE__*/_interopDefault(tippy);
-
 // src/components/RichTextDisplay/RichTextDisplay.tsx
 
 // src/types/facets.ts
@@ -35,29 +31,28 @@ function isTagFeature(feature) {
 
 // src/defaults/classNames.ts
 var defaultDisplayClassNames = {
-  root: "bsky-richtext",
-  mention: "bsky-mention",
-  link: "bsky-link",
-  tag: "bsky-tag"
+  root: "inline break-words",
+  mention: "inline text-blue-500 hover:underline cursor-pointer",
+  link: "inline text-blue-500 hover:underline",
+  tag: "inline text-blue-500 hover:underline cursor-pointer"
 };
 var defaultSuggestionClassNames = {
-  root: "bsky-suggestions",
-  item: "bsky-suggestion-item",
-  itemSelected: "bsky-suggestion-item-selected",
-  avatar: "bsky-suggestion-avatar",
-  avatarImg: "bsky-suggestion-avatar-img",
-  avatarPlaceholder: "bsky-suggestion-avatar-placeholder",
-  text: "bsky-suggestion-text",
-  name: "bsky-suggestion-name",
-  handle: "bsky-suggestion-handle",
-  empty: "bsky-suggestion-empty"
+  root: "flex flex-col max-h-80 overflow-y-auto bg-white rounded-lg shadow-lg border border-gray-200 min-w-60",
+  item: "flex items-center gap-3 w-full px-3 py-2 text-left cursor-pointer border-none bg-transparent hover:bg-gray-100 select-none",
+  itemSelected: "bg-gray-100",
+  avatar: "flex-shrink-0 w-10 h-10 rounded-full overflow-hidden bg-gray-200 flex items-center justify-center",
+  avatarImg: "block w-full h-full object-cover",
+  avatarPlaceholder: "flex items-center justify-center w-full h-full text-gray-500 font-medium text-sm",
+  text: "flex flex-col flex-1 min-w-0 overflow-hidden",
+  name: "block truncate font-medium text-gray-900 text-sm",
+  handle: "block truncate text-xs text-gray-500",
+  empty: "block px-3 py-2 text-sm text-gray-500"
 };
 var defaultEditorClassNames = {
-  root: "bsky-editor",
-  content: "bsky-editor-content",
-  placeholder: "bsky-editor-placeholder",
-  mention: "bsky-editor-mention",
-  link: "autolink",
+  root: "block w-full relative",
+  content: "block w-full",
+  mention: "inline text-blue-500",
+  link: "inline text-blue-500",
   suggestion: defaultSuggestionClassNames
 };
 
@@ -372,13 +367,7 @@ function createDebouncedSearch(delayMs = 300) {
     });
   };
 }
-var MentionSuggestionList = react.forwardRef(function MentionSuggestionListImpl({
-  items,
-  command,
-  showAvatars = true,
-  noResultsText = "No results",
-  classNames: classNamesProp
-}, ref) {
+var MentionSuggestionList = react.forwardRef(function MentionSuggestionListImpl({ items, command, showAvatars = true, noResultsText = "No results", classNames: classNamesProp }, ref) {
   const [selectedIndex, setSelectedIndex] = react.useState(0);
   const cn = react.useMemo(
     () => generateClassNames([defaultSuggestionClassNames, classNamesProp]),
@@ -462,12 +451,6 @@ function createDefaultSuggestionRenderer(options = {}) {
   return () => {
     let renderer;
     let popup;
-    const destroy = () => {
-      popup?.[0]?.destroy();
-      renderer?.destroy();
-      renderer = void 0;
-      popup = void 0;
-    };
     const buildProps = (props) => ({
       ...props,
       showAvatars: options.showAvatars ?? true,
@@ -482,33 +465,49 @@ function createDefaultSuggestionRenderer(options = {}) {
         });
         if (!props.clientRect) return;
         const clientRect = props.clientRect;
-        popup = tippy__default.default("body", {
-          getReferenceClientRect: () => clientRect?.() ?? new DOMRect(),
-          appendTo: () => document.body,
-          content: renderer.element,
-          showOnCreate: true,
-          interactive: true,
-          trigger: "manual",
-          placement: "bottom-start"
+        popup = document.createElement("div");
+        popup.style.position = "fixed";
+        popup.style.zIndex = "9999";
+        popup.appendChild(renderer.element);
+        document.body.appendChild(popup);
+        const virtualEl = { getBoundingClientRect: () => clientRect?.() ?? new DOMRect() };
+        void dom.computePosition(virtualEl, popup, {
+          placement: "bottom-start",
+          middleware: [dom.offset(8), dom.flip(), dom.shift({ padding: 8 })]
+        }).then(({ x, y }) => {
+          if (popup) {
+            popup.style.left = `${x}px`;
+            popup.style.top = `${y}px`;
+          }
         });
       },
       onUpdate(props) {
         renderer?.updateProps(buildProps(props));
-        if (!props.clientRect) return;
+        if (!props.clientRect || !popup) return;
         const clientRect = props.clientRect;
-        popup?.[0]?.setProps({
-          getReferenceClientRect: () => clientRect?.() ?? new DOMRect()
+        const virtualEl = { getBoundingClientRect: () => clientRect?.() ?? new DOMRect() };
+        void dom.computePosition(virtualEl, popup, {
+          placement: "bottom-start",
+          middleware: [dom.offset(8), dom.flip(), dom.shift({ padding: 8 })]
+        }).then(({ x, y }) => {
+          if (popup) {
+            popup.style.left = `${x}px`;
+            popup.style.top = `${y}px`;
+          }
         });
       },
       onKeyDown(props) {
         if (props.event.key === "Escape") {
-          popup?.[0]?.hide();
+          if (popup) popup.style.display = "none";
           return true;
         }
         return renderer?.ref?.onKeyDown(props) ?? false;
       },
       onExit() {
-        destroy();
+        popup?.remove();
+        renderer?.destroy();
+        popup = void 0;
+        renderer = void 0;
       }
     };
   };