bsky-richtext-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,761 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, AnchorHTMLAttributes, Ref } from 'react';
+import { SuggestionOptions, SuggestionProps, SuggestionKeyDownProps } from '@tiptap/suggestion';
+
+/**
+ * TypeScript types mirroring the `app.bsky.richtext.facet` lexicon.
+ *
+ * Spec: /lexicons/app/richtext/facet.json
+ * Reference: https://atproto.com/lexicons/app-bsky-richtext
+ */
+/**
+ * Specifies the sub-string range a facet feature applies to.
+ * Indices are ZERO-indexed byte offsets of the UTF-8 encoded text.
+ * - byteStart: inclusive
+ * - byteEnd:   exclusive
+ *
+ * ⚠️  JavaScript strings are UTF-16. Always convert to a UTF-8 byte array
+ *     before computing byte offsets.
+ */
+interface ByteSlice {
+    byteStart: number;
+    byteEnd: number;
+}
+/** Mention of another AT Protocol account. The DID is the canonical identifier. */
+interface MentionFeature {
+    $type: 'app.bsky.richtext.facet#mention';
+    /** DID of the mentioned account */
+    did: string;
+}
+/** A hyperlink facet. The URI is the full, unshortened URL. */
+interface LinkFeature {
+    $type: 'app.bsky.richtext.facet#link';
+    /** The full URL */
+    uri: string;
+}
+/** A hashtag facet. The tag value does NOT include the leading '#'. */
+interface TagFeature {
+    $type: 'app.bsky.richtext.facet#tag';
+    /** The tag text without the '#' prefix (max 64 graphemes / 640 bytes) */
+    tag: string;
+}
+/** Union of all possible facet feature types. */
+type FacetFeature = MentionFeature | LinkFeature | TagFeature;
+/**
+ * A single richtext annotation — maps a byte-range within the post text
+ * to one or more semantic features (mention, link, tag).
+ */
+interface Facet {
+    index: ByteSlice;
+    features: FacetFeature[];
+}
+/**
+ * Represents the `text` + `facets` fields as they appear in an AT Protocol
+ * record (e.g. `app.bsky.feed.post`).
+ */
+interface RichTextRecord {
+    text: string;
+    facets?: Facet[];
+}
+/**
+ * A parsed segment of richtext — a slice of text with its associated feature
+ * (if any). Produced by the richtext parser.
+ */
+interface RichTextSegment {
+    /** The raw text of this segment */
+    text: string;
+    /** The facet feature associated with this segment, if any */
+    feature?: FacetFeature;
+}
+declare function isMentionFeature(feature: FacetFeature): feature is MentionFeature;
+declare function isLinkFeature(feature: FacetFeature): feature is LinkFeature;
+declare function isTagFeature(feature: FacetFeature): feature is TagFeature;
+
+/**
+ * ClassNames type definitions for bsky-richtext-react components.
+ *
+ * Each interface describes the styleable parts of a component as an optional
+ * nested object of CSS class strings. Use `generateClassNames()` to deep-merge
+ * multiple classNames objects together (e.g. defaults + your overrides).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   generateClassNames,
+ *   defaultEditorClassNames,
+ * } from 'bsky-richtext-react'
+ *
+ * <RichTextEditor
+ *   classNames={generateClassNames([
+ *     defaultEditorClassNames,
+ *     { root: 'border rounded-lg p-2', mention: 'text-blue-500' },
+ *   ], cn)}
+ * />
+ * ```
+ */
+/**
+ * Styleable parts of the `RichTextDisplay` component.
+ */
+interface DisplayClassNames {
+    /** Root `<span>` wrapper around all richtext content */
+    root?: string;
+    /** Anchor element wrapping each @mention */
+    mention?: string;
+    /** Anchor element wrapping each link */
+    link?: string;
+    /** Anchor element wrapping each #hashtag */
+    tag?: string;
+}
+/**
+ * Styleable parts of the `MentionSuggestionList` dropdown component.
+ * Also nested as `suggestion` inside `EditorClassNames`.
+ */
+interface SuggestionClassNames {
+    /** Outermost container div */
+    root?: string;
+    /** Each suggestion row (`<button>`) */
+    item?: string;
+    /**
+     * Class added to the currently highlighted suggestion row.
+     * Applied in addition to `item` — not instead of it.
+     */
+    itemSelected?: string;
+    /** Avatar wrapper `<span>` */
+    avatar?: string;
+    /** Avatar `<img>` element */
+    avatarImg?: string;
+    /** Initial-letter fallback shown when no avatar URL is available */
+    avatarPlaceholder?: string;
+    /** Text column container (holds display name + handle) */
+    text?: string;
+    /** Display name `<span>` */
+    name?: string;
+    /** `@handle` `<span>` */
+    handle?: string;
+    /** "No results" empty-state message */
+    empty?: string;
+}
+/**
+ * Styleable parts of the `RichTextEditor` component.
+ */
+interface EditorClassNames {
+    /** Root wrapper `<div>` around the editor */
+    root?: string;
+    /** Inner ProseMirror editable `<div>` (via `.ProseMirror`) */
+    content?: string;
+    /** Placeholder text element */
+    placeholder?: string;
+    /** Mention chips rendered inside the editor */
+    mention?: string;
+    /** Autolink decoration spans rendered inside the editor */
+    link?: string;
+    /** Class names forwarded to the nested `MentionSuggestionList` */
+    suggestion?: SuggestionClassNames;
+}
+
+interface MentionProps {
+    /** The raw segment text (e.g. "@alice.bsky.social") */
+    text: string;
+    /** The resolved DID of the mentioned account */
+    did: string;
+    /** The mention facet feature */
+    feature: MentionFeature;
+}
+interface LinkProps {
+    /** The display text for the link (may be shortened) */
+    text: string;
+    /** The full URL */
+    uri: string;
+    /** The link facet feature */
+    feature: LinkFeature;
+}
+interface TagProps {
+    /** The display text including '#' (e.g. "#atproto") */
+    text: string;
+    /** The tag value without '#' prefix (e.g. "atproto") */
+    tag: string;
+    /** The tag facet feature */
+    feature: TagFeature;
+}
+interface RichTextDisplayProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /**
+     * The richtext record to render.
+     * Accepts `{ text, facets? }` — i.e. the raw AT Protocol record fields.
+     */
+    value: RichTextRecord | string;
+    /**
+     * Custom renderer for @mention segments.
+     * If not provided, renders a plain `<a>` linking to the profile.
+     */
+    renderMention?: (props: MentionProps) => ReactNode;
+    /**
+     * Custom renderer for link segments.
+     * If not provided, renders a plain `<a>` with the shortened URL as text.
+     */
+    renderLink?: (props: LinkProps) => ReactNode;
+    /**
+     * Custom renderer for #hashtag segments.
+     * If not provided, renders a plain `<a>` linking to the hashtag search.
+     */
+    renderTag?: (props: TagProps) => ReactNode;
+    /**
+     * When true, all interactive facets (mentions, links, tags) are rendered
+     * as plain text with no anchor elements.
+     * @default false
+     */
+    disableLinks?: boolean;
+    /**
+     * Props forwarded to every `<a>` element rendered by the default renderers.
+     * Ignored when custom `renderMention` / `renderLink` / `renderTag` are used.
+     */
+    linkProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
+    /**
+     * CSS class names for each styleable part of the component.
+     *
+     * Use `generateClassNames()` to cleanly merge with the built-in defaults:
+     * @example
+     * ```tsx
+     * import { generateClassNames, defaultDisplayClassNames } from 'bsky-richtext-react'
+     *
+     * <RichTextDisplay
+     *   classNames={generateClassNames([
+     *     defaultDisplayClassNames,
+     *     { mention: 'text-blue-500 hover:underline' },
+     *   ], cn)}
+     * />
+     * ```
+     *
+     * Or pass a completely custom object to opt out of the defaults entirely:
+     * ```tsx
+     * <RichTextDisplay classNames={{ root: 'my-richtext', mention: 'my-mention' }} />
+     * ```
+     */
+    classNames?: Partial<DisplayClassNames>;
+    /**
+     * Generate the `href` for @mention anchors.
+     * Called with the mention's DID.
+     * @default (did) => `https://bsky.app/profile/${did}`
+     *
+     * @example Route mentions to your own profile pages
+     * ```tsx
+     * mentionUrl={(did) => `/profile/${did}`}
+     * ```
+     */
+    mentionUrl?: (did: string) => string;
+    /**
+     * Generate the `href` for #hashtag anchors.
+     * Called with the tag value (without the '#' prefix).
+     * @default (tag) => `https://bsky.app/hashtag/${encodeURIComponent(tag)}`
+     *
+     * @example Route hashtags to your own search page
+     * ```tsx
+     * tagUrl={(tag) => `/search?tag=${encodeURIComponent(tag)}`}
+     * ```
+     */
+    tagUrl?: (tag: string) => string;
+    /**
+     * Transform a link URI before it is used as the anchor's `href`.
+     * Useful for proxying external links or adding UTM parameters.
+     * @default (uri) => uri  (identity — no transformation)
+     *
+     * @example Add a referral parameter
+     * ```tsx
+     * linkUrl={(uri) => `${uri}?ref=myapp`}
+     * ```
+     */
+    linkUrl?: (uri: string) => string;
+}
+/**
+ * `RichTextDisplay` renders AT Protocol richtext content — a string with
+ * optional `facets` that annotate byte ranges as mentions, links, or hashtags.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <RichTextDisplay value={{ text: post.text, facets: post.facets }} />
+ * ```
+ *
+ * @example With custom mention renderer
+ * ```tsx
+ * <RichTextDisplay
+ *   value={post}
+ *   renderMention={({ text, did }) => (
+ *     <Link to={`/profile/${did}`}>{text}</Link>
+ *   )}
+ * />
+ * ```
+ *
+ * @example With URL resolvers pointing to your own routes
+ * ```tsx
+ * <RichTextDisplay
+ *   value={post}
+ *   mentionUrl={(did) => `/profile/${did}`}
+ *   tagUrl={(tag) => `/search?tag=${tag}`}
+ * />
+ * ```
+ *
+ * @example With classNames (using generateClassNames for clean merging)
+ * ```tsx
+ * import { generateClassNames, defaultDisplayClassNames } from 'bsky-richtext-react'
+ *
+ * <RichTextDisplay
+ *   value={post}
+ *   classNames={generateClassNames([
+ *     defaultDisplayClassNames,
+ *     { mention: 'text-blue-500 font-semibold' },
+ *   ], cn)}
+ * />
+ * ```
+ */
+declare function RichTextDisplay({ value, renderMention, renderLink, renderTag, disableLinks, linkProps, classNames: classNamesProp, mentionUrl, tagUrl, linkUrl, ...spanProps }: RichTextDisplayProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * createSuggestionRenderer
+ *
+ * Factory that returns a TipTap `SuggestionOptions['render']` function.
+ * It uses `tippy.js` for cursor-anchored positioning and `ReactRenderer`
+ * to mount the `MentionSuggestionList` React component into the popup.
+ *
+ * Heavily inspired by Bluesky's social-app Autocomplete.tsx and the
+ * official TipTap mention example:
+ * https://tiptap.dev/docs/editor/extensions/nodes/mention#usage
+ *
+ * This is the default renderer used when the consumer does NOT supply
+ * a custom `renderMentionSuggestion` prop to `<RichTextEditor>`.
+ */
+
+interface DefaultSuggestionRendererOptions {
+    /**
+     * Whether to show avatars in the suggestion list.
+     * Forwarded to `MentionSuggestionList`.
+     * @default true
+     */
+    showAvatars?: boolean;
+    /**
+     * Text shown when the query returns no results.
+     * @default "No results"
+     */
+    noResultsText?: string;
+    /**
+     * CSS class names for each styleable part of the suggestion dropdown.
+     * Forwarded directly to `MentionSuggestionList`.
+     */
+    classNames?: Partial<SuggestionClassNames>;
+}
+/**
+ * Create the default TipTap `suggestion.render` factory.
+ *
+ * The returned function is called once per "suggestion session"
+ * (i.e. each time the user types "@" and a popup should open/update/close).
+ *
+ * It follows the same lifecycle pattern as the Bluesky reference:
+ *  - `onStart`  → Mount ReactRenderer, create tippy popup
+ *  - `onUpdate` → Update props, reposition popup
+ *  - `onKeyDown`→ Delegate to the MentionSuggestionList imperative ref
+ *  - `onExit`   → Destroy popup and React renderer
+ */
+declare function createDefaultSuggestionRenderer(options?: DefaultSuggestionRendererOptions): SuggestionOptions<MentionSuggestion>['render'];
+
+/**
+ * A single suggestion item for the @mention autocomplete popup.
+ */
+interface MentionSuggestion {
+    /** DID of the suggested account — used as the facet's `did` value */
+    did: string;
+    /** Display handle (e.g. "alice.bsky.social") */
+    handle: string;
+    /** Optional display name */
+    displayName?: string;
+    /** Optional avatar URL */
+    avatarUrl?: string;
+}
+/**
+ * Imperative ref API for `RichTextEditor`.
+ */
+interface RichTextEditorRef {
+    /** Focus the editor */
+    focus: () => void;
+    /** Blur the editor */
+    blur: () => void;
+    /** Clear the editor content */
+    clear: () => void;
+    /** Get the current plain-text content */
+    getText: () => string;
+}
+interface RichTextEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /**
+     * Initial richtext value. The editor is pre-populated with this content on mount.
+     * This is an uncontrolled initial state — use `onChange` to track updates.
+     */
+    initialValue?: RichTextRecord | string;
+    /**
+     * Called on every content change with the latest `RichTextRecord`.
+     *
+     * The `facets` array is populated via `detectFacetsWithoutResolution()` —
+     * facets will contain handles (not DIDs) for mentions until you resolve them
+     * server-side using the AT Protocol agent.
+     */
+    onChange?: (record: RichTextRecord) => void;
+    /**
+     * Placeholder text shown when the editor is empty.
+     */
+    placeholder?: string;
+    /**
+     * Called when the editor gains focus.
+     */
+    onFocus?: () => void;
+    /**
+     * Called when the editor loses focus.
+     */
+    onBlur?: () => void;
+    /**
+     * Async function to fetch @mention suggestions.
+     * Called with the query string (text after "@") as the user types.
+     * Return an empty array to show no suggestions / "No results".
+     *
+     * When not provided, the built-in Bluesky public API search is used
+     * (debounced by `mentionSearchDebounceMs`). Set `disableDefaultMentionSearch`
+     * to true to disable this default behaviour entirely.
+     *
+     * @example
+     * ```tsx
+     * onMentionQuery={async (q) => {
+     *   const res = await agent.searchActors({ term: q, limit: 8 })
+     *   return res.data.actors.map(a => ({
+     *     did: a.did,
+     *     handle: a.handle,
+     *     displayName: a.displayName,
+     *     avatarUrl: a.avatar,
+     *   }))
+     * }}
+     * ```
+     */
+    onMentionQuery?: (query: string) => Promise<MentionSuggestion[]>;
+    /**
+     * Debounce delay (in milliseconds) applied to the built-in Bluesky mention
+     * search. Has no effect when `onMentionQuery` is provided.
+     * @default 300
+     */
+    mentionSearchDebounceMs?: number;
+    /**
+     * When true, disables the default Bluesky public API mention search.
+     * No suggestions will appear unless you provide `onMentionQuery`.
+     * @default false
+     */
+    disableDefaultMentionSearch?: boolean;
+    /**
+     * Custom TipTap `suggestion.render` factory.
+     * When provided, replaces the default tippy.js + MentionSuggestionList renderer.
+     * The factory must return `{ onStart, onUpdate, onKeyDown, onExit }`.
+     *
+     * See: https://tiptap.dev/docs/editor/extensions/nodes/mention#usage
+     */
+    renderMentionSuggestion?: SuggestionOptions['render'];
+    /**
+     * Options forwarded to the default suggestion renderer.
+     * Only used when `renderMentionSuggestion` is NOT provided.
+     */
+    mentionSuggestionOptions?: DefaultSuggestionRendererOptions;
+    /**
+     * CSS class names for each styleable part of the editor.
+     *
+     * Use `generateClassNames()` to cleanly merge with the built-in defaults:
+     * @example
+     * ```tsx
+     * import { generateClassNames, defaultEditorClassNames } from 'bsky-richtext-react'
+     *
+     * <RichTextEditor
+     *   classNames={generateClassNames([
+     *     defaultEditorClassNames,
+     *     { root: 'border rounded-lg p-3', mention: 'text-blue-500' },
+     *   ], cn)}
+     * />
+     * ```
+     *
+     * Or pass a completely custom object to opt out of the defaults:
+     * ```tsx
+     * <RichTextEditor classNames={{ root: 'my-editor', mention: 'my-mention' }} />
+     * ```
+     */
+    classNames?: Partial<EditorClassNames>;
+    /**
+     * Imperative ref for programmatic control.
+     */
+    editorRef?: Ref<RichTextEditorRef>;
+    /**
+     * Whether the editor content is editable.
+     * @default true
+     */
+    editable?: boolean;
+}
+/**
+ * `RichTextEditor` is a TipTap-based editor for composing AT Protocol richtext.
+ *
+ * Features:
+ * - Real-time @mention autocomplete — defaults to the Bluesky public API,
+ *   override with `onMentionQuery`
+ * - Automatic URL decoration (link facets detected on change)
+ * - Hard-break (Shift+Enter) for newlines inside a paragraph
+ * - Undo/redo history
+ * - `onChange` emits a `RichTextRecord` with `text` + `facets` populated via
+ *   `detectFacetsWithoutResolution()`
+ * - Headless — bring your own CSS, or use the structural defaults in styles.css
+ *
+ * @example Basic usage (built-in Bluesky mention search)
+ * ```tsx
+ * <RichTextEditor
+ *   placeholder="What's on your mind?"
+ *   onChange={(record) => setPost(record)}
+ * />
+ * ```
+ *
+ * @example Custom mention search
+ * ```tsx
+ * <RichTextEditor
+ *   placeholder="What's on your mind?"
+ *   onMentionQuery={async (q) => searchProfiles(q)}
+ *   onChange={(record) => setPost(record)}
+ * />
+ * ```
+ *
+ * @example With classNames
+ * ```tsx
+ * import { generateClassNames, defaultEditorClassNames } from 'bsky-richtext-react'
+ *
+ * <RichTextEditor
+ *   classNames={generateClassNames([
+ *     defaultEditorClassNames,
+ *     { root: 'border rounded-lg p-3' },
+ *   ], cn)}
+ * />
+ * ```
+ */
+declare function RichTextEditor({ initialValue, onChange, placeholder, onFocus, onBlur, onMentionQuery, mentionSearchDebounceMs, disableDefaultMentionSearch, renderMentionSuggestion, mentionSuggestionOptions, classNames: classNamesProp, editorRef, editable, ...divProps }: RichTextEditorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Ref handle that TipTap calls into for keyboard events while the popup is open.
+ * Mirrors the `MentionListRef` interface from the Bluesky reference implementation.
+ */
+interface MentionSuggestionListRef {
+    onKeyDown: (props: SuggestionKeyDownProps) => boolean;
+}
+interface MentionSuggestionListProps extends SuggestionProps<MentionSuggestion> {
+    /**
+     * Whether to render avatars when `avatarUrl` is present on a suggestion.
+     * When false, avatar placeholder is hidden entirely.
+     * @default true
+     */
+    showAvatars?: boolean;
+    /**
+     * Text to show when the items array is empty.
+     * @default "No results"
+     */
+    noResultsText?: string;
+    /**
+     * CSS class names for each styleable part of the suggestion dropdown.
+     *
+     * Use `generateClassNames()` to merge with the built-in defaults:
+     * @example
+     * ```tsx
+     * import { generateClassNames, defaultSuggestionClassNames } from 'bsky-richtext-react'
+     *
+     * classNames={generateClassNames([
+     *   defaultSuggestionClassNames,
+     *   { item: 'px-3 py-2', itemSelected: 'bg-blue-50' },
+     * ], cn)}
+     * ```
+     */
+    classNames?: Partial<SuggestionClassNames>;
+}
+/**
+ * Default mention suggestion dropdown rendered by `RichTextEditor`.
+ *
+ * Consumers can pass `classNames` to style specific parts, or pass a completely
+ * custom `renderMentionSuggestion` factory to the editor to replace this
+ * component entirely.
+ */
+declare const MentionSuggestionList: react.ForwardRefExoticComponent<MentionSuggestionListProps & react.RefAttributes<MentionSuggestionListRef>>;
+
+/**
+ * Parse a `RichTextRecord` into an array of `RichTextSegment` objects.
+ *
+ * The result is memoized — re-computation only occurs when `text` or the
+ * serialized facets change.
+ *
+ * @example
+ * ```tsx
+ * const segments = useRichText({ text: post.text, facets: post.facets })
+ * // [{ text: 'Hello ' }, { text: '@alice', feature: { $type: '...mention', did: '...' } }]
+ * ```
+ */
+declare function useRichText(record: RichTextRecord): RichTextSegment[];
+
+/**
+ * Richtext parser — converts `{ text, facets }` into an ordered array of
+ * `RichTextSegment` objects, each with their text slice and optional feature.
+ *
+ * Algorithm:
+ *  1. Sort facets by byteStart (ascending).
+ *  2. Walk through the text byte-by-byte, emitting plain segments between
+ *     facets and annotated segments for each facet's byte range.
+ *  3. Overlapping facets are handled gracefully (skipped).
+ */
+
+/**
+ * Parse a `RichTextRecord` into an ordered array of segments, each
+ * carrying its text and an optional facet feature.
+ *
+ * The segments are contiguous — joining all `segment.text` values
+ * reconstructs the original `record.text` exactly.
+ */
+declare function parseRichText(record: RichTextRecord): RichTextSegment[];
+
+/**
+ * URL display utilities for richtext rendering.
+ */
+/**
+ * Shorten a URL for display purposes — strips the protocol and truncates
+ * the path if it's very long (mirrors Bluesky's `toShortUrl` behaviour).
+ *
+ * @example
+ * toShortUrl('https://example.com/some/very/long/path?q=foo')
+ * // => 'example.com/some/very/long/path?q=foo'
+ */
+declare function toShortUrl(url: string, maxLength?: number): string;
+/**
+ * Validate that a string is a well-formed URL.
+ */
+declare function isValidUrl(url: string): boolean;
+
+/**
+ * generateClassNames — deep-merge utility for component classNames objects.
+ *
+ * Accepts an array of partial classNames objects and merges them left-to-right,
+ * so later entries override earlier ones. String values at the same key are
+ * combined using the optional `cn` function (e.g. `clsx`, `tailwind-merge`).
+ * Nested objects (e.g. `suggestion` inside `EditorClassNames`) are recursively
+ * merged using the same rules.
+ *
+ * Falsy values in the array (`undefined`, `null`, `false`) are silently
+ * ignored, which makes conditional spreading ergonomic:
+ *
+ * @example Basic override
+ * ```ts
+ * import { generateClassNames, defaultEditorClassNames } from 'bsky-richtext-react'
+ *
+ * classNames={generateClassNames([
+ *   defaultEditorClassNames,
+ *   { root: 'border rounded-lg', mention: 'text-blue-500' },
+ * ])}
+ * ```
+ *
+ * @example With a Tailwind-merge / clsx utility
+ * ```ts
+ * import { cn } from '@/lib/utils'
+ *
+ * classNames={generateClassNames([
+ *   defaultEditorClassNames,
+ *   { root: 'rounded-none' },
+ * ], cn)}
+ * ```
+ *
+ * @example Conditional overrides
+ * ```ts
+ * classNames={generateClassNames([
+ *   defaultEditorClassNames,
+ *   isCompact && { root: 'text-sm' },
+ *   isDark   && darkThemeClassNames,
+ * ], cn)}
+ * ```
+ *
+ * @example Deep nested override (suggestion dropdown)
+ * ```ts
+ * classNames={generateClassNames([
+ *   defaultEditorClassNames,
+ *   { suggestion: { item: 'hover:bg-gray-100', itemSelected: 'bg-blue-50' } },
+ * ])}
+ * ```
+ */
+/**
+ * A function that accepts any number of class strings (plus falsy values) and
+ * returns a single merged class string. Compatible with `clsx`, `classnames`,
+ * and `tailwind-merge`'s `twMerge` / `cn` utilities.
+ */
+type ClassNameFn = (...inputs: Array<string | undefined | null | false>) => string;
+/**
+ * Deep-merge an array of classNames objects into a single classNames object.
+ *
+ * @param classNamesArray - Objects to merge, left-to-right. Falsy entries are skipped.
+ * @param cn - Optional class utility function. When omitted, strings are
+ *   joined with a single space (filtering empty strings).
+ */
+declare function generateClassNames<T extends object>(classNamesArray: Array<Partial<T> | undefined | null | false>, cn?: ClassNameFn): T;
+
+/**
+ * Bluesky public API helpers for mention search.
+ *
+ * `searchBskyActors` calls the unauthenticated public Bluesky API to look up
+ * actor suggestions. It is used as the default `onMentionQuery` implementation
+ * in `RichTextEditor` — no API key or authentication required.
+ *
+ * `createDebouncedSearch` wraps `searchBskyActors` with a debounce so rapid
+ * keystrokes don't fire unnecessary network requests. Only the latest in-flight
+ * query resolves; stale promises from earlier keystrokes are silently discarded.
+ */
+
+/**
+ * Search for Bluesky actors using the public, unauthenticated API.
+ *
+ * Returns up to `limit` matching `MentionSuggestion` objects, or an empty
+ * array if the query is blank, the network request fails, or the response is
+ * malformed.
+ *
+ * @param query - Text the user typed after "@"
+ * @param limit - Max results to return (default: 8)
+ */
+declare function searchBskyActors(query: string, limit?: number): Promise<MentionSuggestion[]>;
+/**
+ * Create a debounced version of `searchBskyActors`.
+ *
+ * Rapid calls within `delayMs` are coalesced — only the *latest* invocation
+ * fires a network request. Earlier pending promises resolve with the same
+ * result as the latest call (they are not rejected or left dangling).
+ *
+ * @param delayMs - Debounce window in milliseconds (default: 300)
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = createDebouncedSearch(400)
+ * // Pass to onMentionQuery or use as the internal default
+ * ```
+ */
+declare function createDebouncedSearch(delayMs?: number): (query: string) => Promise<MentionSuggestion[]>;
+
+/**
+ * Default classNames for bsky-richtext-react components.
+ *
+ * These are the CSS class names used when no override is provided.
+ * The companion `styles.css` targets exactly these class names for structural
+ * layout rules. Consumers can extend or override them using `generateClassNames()`.
+ *
+ * @example Keep defaults, override one class
+ * ```tsx
+ * import { generateClassNames, defaultEditorClassNames } from 'bsky-richtext-react'
+ *
+ * classNames={generateClassNames([
+ *   defaultEditorClassNames,
+ *   { root: 'border rounded-lg p-2' },
+ * ])}
+ * ```
+ *
+ * @example Completely replace defaults (opt out of all built-in class names)
+ * ```tsx
+ * classNames={{ root: 'my-editor', mention: 'my-mention' }}
+ * ```
+ */
+
+declare const defaultDisplayClassNames: DisplayClassNames;
+declare const defaultSuggestionClassNames: SuggestionClassNames;
+declare const defaultEditorClassNames: EditorClassNames;
+
+export { type ByteSlice, type ClassNameFn, type DefaultSuggestionRendererOptions, type DisplayClassNames, type EditorClassNames, type Facet, type FacetFeature, type LinkFeature, type LinkProps, type MentionFeature, type MentionProps, type MentionSuggestion, MentionSuggestionList, type MentionSuggestionListProps, type MentionSuggestionListRef, RichTextDisplay, type RichTextDisplayProps, RichTextEditor, type RichTextEditorProps, type RichTextEditorRef, type RichTextRecord, type RichTextSegment, type SuggestionClassNames, type TagFeature, type TagProps, createDebouncedSearch, createDefaultSuggestionRenderer, defaultDisplayClassNames, defaultEditorClassNames, defaultSuggestionClassNames, generateClassNames, isLinkFeature, isMentionFeature, isTagFeature, isValidUrl, parseRichText, searchBskyActors, toShortUrl, useRichText };