@domternal/extension-emoji 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,211 @@
+import { CommandSpec, Node } from '@domternal/core';
+import { Plugin, PluginKey } from '@domternal/pm/state';
+import { NodeType } from '@domternal/pm/model';
+
+/**
+ * Built-in emoji datasets for @domternal/extension-emoji.
+ *
+ * Two exports:
+ * - `emojis` — ~200 most popular emoji (~8KB gzipped)
+ * - `allEmojis` — Full ~1,800 emoji Unicode 15.1 set (~40KB gzipped)
+ *
+ * Users can import either or provide their own custom data.
+ */
+/**
+ * A single emoji entry in the dataset.
+ */
+interface EmojiItem {
+    /** Native Unicode emoji character (e.g., "😄") */
+    emoji: string;
+    /** Unique name used as node attribute (e.g., "smile") */
+    name: string;
+    /** Shortcodes without colons (e.g., ["smile", "grinning"]) */
+    shortcodes: string[];
+    /** Search tags (e.g., ["happy", "face"]) */
+    tags: string[];
+    /** Category group (e.g., "Smileys & Emotion") */
+    group: string;
+    /** Optional fallback image URL for unsupported emoji */
+    fallbackImage?: string;
+}
+/** Curated set of ~200 most commonly used emoji. */
+declare const emojis: EmojiItem[];
+/**
+ * Full Unicode 15.1 emoji dataset.
+ * Includes the popular set plus all remaining Unicode emoji.
+ * Use `emojis` for a lighter bundle, or `allEmojis` for full coverage.
+ */
+declare const allEmojis: EmojiItem[];
+
+/**
+ * Suggestion Plugin for Emoji Autocomplete
+ *
+ * Headless ProseMirror plugin that watches for a trigger character (default: ':'),
+ * tracks the query, and calls render callbacks so framework wrappers can display
+ * a dropdown picker.
+ *
+ * This is a zero-dependency implementation — no external suggestion library needed.
+ */
+
+/** Plugin key for external access to suggestion state. */
+declare const emojiSuggestionPluginKey: PluginKey<SuggestionState>;
+interface SuggestionProps {
+    /** Current query string (text after trigger char). */
+    query: string;
+    /** Document range of the trigger + query (for replacement). */
+    range: {
+        from: number;
+        to: number;
+    };
+    /** Filtered emoji items matching the query. */
+    items: EmojiItem[];
+    /** Call to insert an emoji and close the suggestion. */
+    command: (item: EmojiItem) => void;
+    /** Returns the client rect of the cursor for positioning the popup. */
+    clientRect: (() => DOMRect | null) | null;
+    /** The ProseMirror editor DOM element (for appending popups inside the editor tree). */
+    element: HTMLElement;
+}
+interface SuggestionRenderer {
+    /** Called when suggestion is first activated. */
+    onStart: (props: SuggestionProps) => void;
+    /** Called when query or items change. */
+    onUpdate: (props: SuggestionProps) => void;
+    /** Called when suggestion is deactivated. */
+    onExit: () => void;
+    /** Called on keydown — return true to prevent default editor handling. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+interface SuggestionOptions {
+    /** Trigger character. Default: ':' */
+    char?: string;
+    /** Minimum query length before showing suggestions. Default: 0 */
+    minQueryLength?: number;
+    /** Filter/sort items for a given query. */
+    items?: (props: {
+        query: string;
+    }) => EmojiItem[];
+    /** Render callbacks for the suggestion popup. */
+    render?: () => SuggestionRenderer;
+    /** Allow spaces in query. Default: false */
+    allowSpaces?: boolean;
+}
+interface SuggestionPluginOptions extends SuggestionOptions {
+    editor: unknown;
+    nodeType: NodeType | null;
+    storage: EmojiStorage;
+    plainText: boolean;
+}
+interface SuggestionState {
+    active: boolean;
+    query: string;
+    range: {
+        from: number;
+        to: number;
+    } | null;
+}
+/**
+ * Creates a ProseMirror plugin for emoji suggestion/autocomplete.
+ */
+declare function createSuggestionPlugin(options: SuggestionPluginOptions): Plugin;
+
+/**
+ * Emoji Node Extension
+ *
+ * Inline atom node for emoji with shortcode input rules, emoticon support,
+ * and a headless suggestion plugin for autocomplete pickers.
+ *
+ * @example
+ * ```ts
+ * import { Emoji, emojis } from '@domternal/extension-emoji';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Emoji.configure({
+ *       emojis,
+ *       enableEmoticons: true,
+ *     }),
+ *   ],
+ * });
+ *
+ * // Insert emoji by name
+ * editor.commands.insertEmoji('smile');
+ *
+ * // Programmatically open suggestion picker
+ * editor.commands.suggestEmoji();
+ * ```
+ */
+
+declare module '@domternal/core' {
+    interface RawCommands {
+        insertEmoji: CommandSpec<[name: string]>;
+        suggestEmoji: CommandSpec;
+    }
+}
+interface EmojiOptions {
+    /** Emoji dataset. Default: built-in ~200 popular emoji. */
+    emojis: EmojiItem[];
+    /** Enable emoticon shortcuts like :) and <3. Default: false. */
+    enableEmoticons: boolean;
+    /** Render emoji as plain text instead of atom nodes. Default: false. */
+    plainText: boolean;
+    /** HTML attributes for the emoji span element. */
+    HTMLAttributes: Record<string, unknown>;
+    /** Suggestion plugin config for autocomplete picker. Default: null (disabled). */
+    suggestion: SuggestionOptions | null;
+}
+interface EmojiStorage {
+    /** Get frequently used emoji names, sorted by usage count descending. */
+    getFrequentlyUsed: () => string[];
+    /** Record a usage of an emoji name. */
+    addFrequentlyUsed: (name: string) => void;
+    /** Find an emoji item by name. */
+    findEmoji: (name: string) => EmojiItem | undefined;
+    /** Search emoji by query (matches name, shortcodes, and tags). */
+    searchEmoji: (query: string) => EmojiItem[];
+    /** @internal Name → EmojiItem lookup map (set in onCreate). */
+    _nameMap?: Map<string, EmojiItem>;
+    /** @internal Shortcode → EmojiItem lookup map (set in onCreate). */
+    _shortcodeMap?: Map<string, EmojiItem>;
+}
+declare const Emoji: Node<EmojiOptions, EmojiStorage>;
+
+/**
+ * Emoticon to emoji name mappings.
+ * Used when `enableEmoticons: true` to convert text shortcuts to emoji.
+ *
+ * Each key is the emoticon text, value is the emoji `name` from the dataset.
+ * The emoticon is matched at the end of input (after a space or at line start).
+ */
+declare const emoticons: Record<string, string>;
+
+/**
+ * Default emoji suggestion renderer — vanilla DOM dropdown.
+ *
+ * Framework-agnostic: creates a positioned dropdown near the cursor
+ * that displays matching emoji items with keyboard navigation.
+ *
+ * @example
+ * ```ts
+ * import { Emoji, emojis, createEmojiSuggestionRenderer } from '@domternal/extension-emoji';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Emoji.configure({
+ *       emojis,
+ *       suggestion: {
+ *         render: createEmojiSuggestionRenderer(),
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Creates a render factory for the emoji suggestion plugin.
+ * Returns a function that produces a `SuggestionRenderer` instance.
+ */
+declare function createEmojiSuggestionRenderer(): () => SuggestionRenderer;
+
+export { Emoji, type EmojiItem, type EmojiOptions, type EmojiStorage, type SuggestionOptions, type SuggestionProps, type SuggestionRenderer, allEmojis, createEmojiSuggestionRenderer, createSuggestionPlugin, Emoji as default, emojiSuggestionPluginKey, emojis, emoticons };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { CommandSpec, Node } from '@domternal/core';
+import { Plugin, PluginKey } from '@domternal/pm/state';
+import { NodeType } from '@domternal/pm/model';
+
+/**
+ * Built-in emoji datasets for @domternal/extension-emoji.
+ *
+ * Two exports:
+ * - `emojis` — ~200 most popular emoji (~8KB gzipped)
+ * - `allEmojis` — Full ~1,800 emoji Unicode 15.1 set (~40KB gzipped)
+ *
+ * Users can import either or provide their own custom data.
+ */
+/**
+ * A single emoji entry in the dataset.
+ */
+interface EmojiItem {
+    /** Native Unicode emoji character (e.g., "😄") */
+    emoji: string;
+    /** Unique name used as node attribute (e.g., "smile") */
+    name: string;
+    /** Shortcodes without colons (e.g., ["smile", "grinning"]) */
+    shortcodes: string[];
+    /** Search tags (e.g., ["happy", "face"]) */
+    tags: string[];
+    /** Category group (e.g., "Smileys & Emotion") */
+    group: string;
+    /** Optional fallback image URL for unsupported emoji */
+    fallbackImage?: string;
+}
+/** Curated set of ~200 most commonly used emoji. */
+declare const emojis: EmojiItem[];
+/**
+ * Full Unicode 15.1 emoji dataset.
+ * Includes the popular set plus all remaining Unicode emoji.
+ * Use `emojis` for a lighter bundle, or `allEmojis` for full coverage.
+ */
+declare const allEmojis: EmojiItem[];
+
+/**
+ * Suggestion Plugin for Emoji Autocomplete
+ *
+ * Headless ProseMirror plugin that watches for a trigger character (default: ':'),
+ * tracks the query, and calls render callbacks so framework wrappers can display
+ * a dropdown picker.
+ *
+ * This is a zero-dependency implementation — no external suggestion library needed.
+ */
+
+/** Plugin key for external access to suggestion state. */
+declare const emojiSuggestionPluginKey: PluginKey<SuggestionState>;
+interface SuggestionProps {
+    /** Current query string (text after trigger char). */
+    query: string;
+    /** Document range of the trigger + query (for replacement). */
+    range: {
+        from: number;
+        to: number;
+    };
+    /** Filtered emoji items matching the query. */
+    items: EmojiItem[];
+    /** Call to insert an emoji and close the suggestion. */
+    command: (item: EmojiItem) => void;
+    /** Returns the client rect of the cursor for positioning the popup. */
+    clientRect: (() => DOMRect | null) | null;
+    /** The ProseMirror editor DOM element (for appending popups inside the editor tree). */
+    element: HTMLElement;
+}
+interface SuggestionRenderer {
+    /** Called when suggestion is first activated. */
+    onStart: (props: SuggestionProps) => void;
+    /** Called when query or items change. */
+    onUpdate: (props: SuggestionProps) => void;
+    /** Called when suggestion is deactivated. */
+    onExit: () => void;
+    /** Called on keydown — return true to prevent default editor handling. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+interface SuggestionOptions {
+    /** Trigger character. Default: ':' */
+    char?: string;
+    /** Minimum query length before showing suggestions. Default: 0 */
+    minQueryLength?: number;
+    /** Filter/sort items for a given query. */
+    items?: (props: {
+        query: string;
+    }) => EmojiItem[];
+    /** Render callbacks for the suggestion popup. */
+    render?: () => SuggestionRenderer;
+    /** Allow spaces in query. Default: false */
+    allowSpaces?: boolean;
+}
+interface SuggestionPluginOptions extends SuggestionOptions {
+    editor: unknown;
+    nodeType: NodeType | null;
+    storage: EmojiStorage;
+    plainText: boolean;
+}
+interface SuggestionState {
+    active: boolean;
+    query: string;
+    range: {
+        from: number;
+        to: number;
+    } | null;
+}
+/**
+ * Creates a ProseMirror plugin for emoji suggestion/autocomplete.
+ */
+declare function createSuggestionPlugin(options: SuggestionPluginOptions): Plugin;
+
+/**
+ * Emoji Node Extension
+ *
+ * Inline atom node for emoji with shortcode input rules, emoticon support,
+ * and a headless suggestion plugin for autocomplete pickers.
+ *
+ * @example
+ * ```ts
+ * import { Emoji, emojis } from '@domternal/extension-emoji';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Emoji.configure({
+ *       emojis,
+ *       enableEmoticons: true,
+ *     }),
+ *   ],
+ * });
+ *
+ * // Insert emoji by name
+ * editor.commands.insertEmoji('smile');
+ *
+ * // Programmatically open suggestion picker
+ * editor.commands.suggestEmoji();
+ * ```
+ */
+
+declare module '@domternal/core' {
+    interface RawCommands {
+        insertEmoji: CommandSpec<[name: string]>;
+        suggestEmoji: CommandSpec;
+    }
+}
+interface EmojiOptions {
+    /** Emoji dataset. Default: built-in ~200 popular emoji. */
+    emojis: EmojiItem[];
+    /** Enable emoticon shortcuts like :) and <3. Default: false. */
+    enableEmoticons: boolean;
+    /** Render emoji as plain text instead of atom nodes. Default: false. */
+    plainText: boolean;
+    /** HTML attributes for the emoji span element. */
+    HTMLAttributes: Record<string, unknown>;
+    /** Suggestion plugin config for autocomplete picker. Default: null (disabled). */
+    suggestion: SuggestionOptions | null;
+}
+interface EmojiStorage {
+    /** Get frequently used emoji names, sorted by usage count descending. */
+    getFrequentlyUsed: () => string[];
+    /** Record a usage of an emoji name. */
+    addFrequentlyUsed: (name: string) => void;
+    /** Find an emoji item by name. */
+    findEmoji: (name: string) => EmojiItem | undefined;
+    /** Search emoji by query (matches name, shortcodes, and tags). */
+    searchEmoji: (query: string) => EmojiItem[];
+    /** @internal Name → EmojiItem lookup map (set in onCreate). */
+    _nameMap?: Map<string, EmojiItem>;
+    /** @internal Shortcode → EmojiItem lookup map (set in onCreate). */
+    _shortcodeMap?: Map<string, EmojiItem>;
+}
+declare const Emoji: Node<EmojiOptions, EmojiStorage>;
+
+/**
+ * Emoticon to emoji name mappings.
+ * Used when `enableEmoticons: true` to convert text shortcuts to emoji.
+ *
+ * Each key is the emoticon text, value is the emoji `name` from the dataset.
+ * The emoticon is matched at the end of input (after a space or at line start).
+ */
+declare const emoticons: Record<string, string>;
+
+/**
+ * Default emoji suggestion renderer — vanilla DOM dropdown.
+ *
+ * Framework-agnostic: creates a positioned dropdown near the cursor
+ * that displays matching emoji items with keyboard navigation.
+ *
+ * @example
+ * ```ts
+ * import { Emoji, emojis, createEmojiSuggestionRenderer } from '@domternal/extension-emoji';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Emoji.configure({
+ *       emojis,
+ *       suggestion: {
+ *         render: createEmojiSuggestionRenderer(),
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Creates a render factory for the emoji suggestion plugin.
+ * Returns a function that produces a `SuggestionRenderer` instance.
+ */
+declare function createEmojiSuggestionRenderer(): () => SuggestionRenderer;
+
+export { Emoji, type EmojiItem, type EmojiOptions, type EmojiStorage, type SuggestionOptions, type SuggestionProps, type SuggestionRenderer, allEmojis, createEmojiSuggestionRenderer, createSuggestionPlugin, Emoji as default, emojiSuggestionPluginKey, emojis, emoticons };