@docs.plus/extension-hyperlink 1.5.2 → 4.3.0

package/dist/index.d.cts

@@ -0,0 +1,255 @@
+import { Editor, Mark } from '@tiptap/core';
+import { EditorView } from '@tiptap/pm/view';
+import { Placement } from '@floating-ui/dom';
+export { registerCustomProtocol } from 'linkifyjs';
+
+interface LinkProtocolOptions {
+    scheme: string;
+    optionalSlashes?: boolean;
+}
+type HyperlinkAttributes = {
+    href: string | null;
+    target: string | null;
+    rel: string | null;
+    class: string | null;
+    title: string | null;
+    image: string | null;
+    [key: string]: unknown;
+};
+type PreviewHyperlinkOptions = {
+    editor: Editor;
+    view: EditorView;
+    link: HTMLAnchorElement;
+    nodePos: number;
+    attrs: HyperlinkAttributes;
+    linkCoords: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    validate?: (url: string) => boolean;
+};
+type CreateHyperlinkOptions = {
+    editor: Editor;
+    extensionName: string;
+    attributes: Partial<HyperlinkAttributes>;
+    validate?: (url: string) => boolean;
+};
+interface HyperlinkOptions {
+    autolink: boolean;
+    protocols: Array<LinkProtocolOptions | string>;
+    openOnClick: boolean;
+    linkOnPaste: boolean;
+    HTMLAttributes: Partial<HyperlinkAttributes>;
+    popovers: {
+        previewHyperlink?: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
+        createHyperlink?: ((options: CreateHyperlinkOptions) => HTMLElement | null) | null;
+    };
+    validate?: (url: string) => boolean;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        hyperlink: {
+            editHyperlinkText: (text: string) => ReturnType;
+            editHyperlinkHref: (href: string) => ReturnType;
+            editHyperlink: (attributes?: {
+                newText?: string;
+                newURL?: string;
+                title?: string;
+                image?: string;
+            }) => ReturnType;
+            setHyperlink: (attributes?: {
+                href: string;
+                target?: string | null;
+            }) => ReturnType;
+            unsetHyperlink: () => ReturnType;
+        };
+    }
+}
+declare const Hyperlink: Mark<HyperlinkOptions, any>;
+
+interface FloatingToolbarOptions {
+    referenceElement?: HTMLElement;
+    coordinates?: {
+        x: number;
+        y: number;
+        width?: number;
+        height?: number;
+        contextElement?: HTMLElement;
+    };
+    content: HTMLElement;
+    placement?: Placement;
+    offset?: number;
+    showArrow?: boolean;
+    className?: string;
+    zIndex?: number;
+    onShow?: () => void;
+    onHide?: () => void;
+}
+interface FloatingToolbarInstance {
+    element: HTMLElement;
+    show: () => void;
+    hide: () => void;
+    destroy: () => void;
+    isVisible: () => boolean;
+    setContent: (content: HTMLElement) => void;
+    updateReference: (referenceElement?: HTMLElement, coordinates?: FloatingToolbarOptions['coordinates']) => void;
+}
+declare const DEFAULT_OFFSET = 8;
+declare function createFloatingToolbar(options: FloatingToolbarOptions): FloatingToolbarInstance;
+declare const getCurrentToolbar: () => FloatingToolbarInstance | null;
+declare const isToolbarVisible: () => boolean;
+declare const hideCurrentToolbar: () => void;
+declare const destroyCurrentToolbar: () => void;
+declare const updateCurrentToolbarPosition: (referenceElement?: HTMLElement, coordinates?: FloatingToolbarOptions["coordinates"]) => void;
+
+declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement | null;
+
+type EditHyperlinkModalOptions = {
+    editor: Editor;
+    validate?: (url: string) => boolean;
+    view: EditorView;
+    link: HTMLAnchorElement;
+    linkCoords: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    onBack?: () => void;
+    markName?: string;
+};
+declare function editHyperlinkPopover(options: EditHyperlinkModalOptions): void;
+
+declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
+
+declare const copyToClipboard: (text: string, callback?: (success: boolean) => void) => Promise<boolean>;
+
+declare const createHTMLElement: <K extends keyof HTMLElementTagNameMap>(type: K, props?: Partial<HTMLElementTagNameMap[K]>) => HTMLElementTagNameMap[K];
+
+interface IconProps {
+    size?: number;
+    fill?: string;
+}
+declare const Copy: ({ size, fill }?: IconProps) => string;
+declare const LinkOff: ({ size, fill }?: IconProps) => string;
+declare const Link: ({ size, fill }?: IconProps) => string;
+declare const Pencil: ({ size, fill }?: IconProps) => string;
+declare const Title: ({ size, fill }?: IconProps) => string;
+
+declare const normalizeHref: (raw: string) => string;
+/**
+ * Shape we depend on from a linkifyjs match (plus autolink's
+ * manually-constructed special-scheme entries, which also set `type`).
+ * Loosened to avoid importing linkifyjs types across the public boundary.
+ */
+type LinkifyMatchLike = {
+    type: string;
+    value: string;
+    href: string;
+};
+/**
+ * Canonicalize a linkifyjs match for storage.
+ *
+ * linkifyjs defaults URL matches to `http://…`; we prefer `https://` to
+ * stay consistent with the create popover and markdown input rule, so
+ * URL matches run through `normalizeHref(value)`. Non-URL matches
+ * (emails → `mailto:`, etc.) already carry a meaningful scheme in `href`
+ * and are returned unchanged.
+ */
+declare const normalizeLinkifyHref: (link: LinkifyMatchLike) => string;
+
+/**
+ * Special URL schemes and their corresponding SVG icons
+ * Based on: https://github.com/bhagyas/app-urls
+ */
+type SpecialUrlInfo = {
+    type: string;
+    title: string;
+    /**
+     * Icon identifier hint for consumers (e.g. `'HiMail'`, `'FaWhatsapp'`).
+     * Not rendered by the extension — consumers map this to their own icon
+     * components (React icons, SVG sprites, etc.).
+     */
+    icon: string;
+    category: 'communication' | 'social' | 'productivity' | 'entertainment' | 'shopping' | 'development' | 'apple' | 'other';
+};
+/**
+ * Detect special URL and return corresponding info
+ */
+declare const getSpecialUrlInfo: (url: string) => SpecialUrlInfo | null;
+/**
+ * Get all available categories
+ */
+declare const getCategories: () => string[];
+/**
+ * Get URLs by category
+ */
+declare const getUrlsByCategory: (category: string) => Record<string, SpecialUrlInfo>;
+
+/** Schemes that must never be used as link hrefs (XSS vectors). */
+declare const DANGEROUS_SCHEME_RE: RegExp;
+type ValidateURLOptions = {
+    customValidator?: (url: string) => boolean;
+};
+/**
+ * Validates URLs including both standard web URLs and special app/protocol schemes
+ *
+ * Supports:
+ * - Standard web URLs (http, https, ftp)
+ * - Email addresses (mailto:)
+ * - Phone numbers (tel:, sms:)
+ * - App deep links (whatsapp:, discord:, etc.)
+ * - Apple app schemes (maps:, music:, etc.)
+ * - Development tools (github:, vscode:, etc.)
+ * - Domain-based detection (wa.me, t.me, etc.)
+ *
+ * For http(s)/ftp(s) URLs, the host must also look real — a TLD dot,
+ * `localhost`, or an IP literal. This rejects scheme-prefixed typos like
+ * `https://googlecom` that linkifyjs alone would accept.
+ *
+ * @param url - The URL string to validate
+ * @param options - Optional configuration
+ * @param options.customValidator - Custom validation function to apply additional checks
+ * @returns true if the URL is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateURL('https://example.com') // true
+ * validateURL('mailto:user@example.com') // true
+ * validateURL('tel:+1234567890') // true
+ * validateURL('whatsapp://send?text=hello') // true
+ * validateURL('wa.me/1234567890') // true
+ * validateURL('https://googlecom') // false (no TLD, no localhost, no IP)
+ * validateURL('invalid-url') // false
+ * ```
+ */
+declare const validateURL: (url: string, options?: ValidateURLOptions) => boolean;
+/**
+ * Get the scheme/protocol from a URL
+ * @param url - The URL to extract scheme from
+ * @returns The scheme (e.g., 'https', 'mailto', 'tel') or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getUrlScheme('https://example.com') // 'https'
+ * getUrlScheme('mailto:user@example.com') // 'mailto'
+ * getUrlScheme('invalid') // null
+ * ```
+ */
+declare const getUrlScheme: (url: string) => string | null;
+/**
+ * Check if a URL is a special app/protocol scheme (not http/https)
+ * @param url - The URL to check
+ * @returns true if it's a special scheme, false for standard web URLs
+ *
+ * @example
+ * ```typescript
+ * isSpecialSchemeUrl('mailto:user@example.com') // true
+ * isSpecialSchemeUrl('https://example.com') // false
+ * ```
+ */
+declare const isSpecialSchemeUrl: (url: string) => boolean;
+
+export { Copy, type CreateHyperlinkOptions, DANGEROUS_SCHEME_RE, DEFAULT_OFFSET, type FloatingToolbarInstance, type FloatingToolbarOptions, Hyperlink, type HyperlinkAttributes, type HyperlinkOptions, Link, LinkOff, type LinkProtocolOptions, type LinkifyMatchLike, Pencil, type PreviewHyperlinkOptions, type SpecialUrlInfo, Title, copyToClipboard, createFloatingToolbar, createHTMLElement, createHyperlinkPopover, Hyperlink as default, destroyCurrentToolbar, editHyperlinkPopover, getCategories, getCurrentToolbar, getSpecialUrlInfo, getUrlScheme, getUrlsByCategory, hideCurrentToolbar, isSpecialSchemeUrl, isToolbarVisible, normalizeHref, normalizeLinkifyHref, previewHyperlinkPopover, updateCurrentToolbarPosition, validateURL };

package/dist/index.d.ts

@@ -1,9 +1,255 @@
-export * from "./hyperlink";
-export * from "./helpers/tippyHelper";
-export * from "./modals/previewHyperlink";
-export * from "./modals/setHyperlink";
-import { previewHyperlinkModal } from "./modals/previewHyperlink";
-import { setHyperlinkModal } from "./modals/setHyperlink";
-import Tooltip from "./helpers/tippyHelper";
-import { Hyperlink } from "./hyperlink";
-export { Hyperlink, Tooltip, previewHyperlinkModal, setHyperlinkModal };
+import { Editor, Mark } from '@tiptap/core';
+import { EditorView } from '@tiptap/pm/view';
+import { Placement } from '@floating-ui/dom';
+export { registerCustomProtocol } from 'linkifyjs';
+
+interface LinkProtocolOptions {
+    scheme: string;
+    optionalSlashes?: boolean;
+}
+type HyperlinkAttributes = {
+    href: string | null;
+    target: string | null;
+    rel: string | null;
+    class: string | null;
+    title: string | null;
+    image: string | null;
+    [key: string]: unknown;
+};
+type PreviewHyperlinkOptions = {
+    editor: Editor;
+    view: EditorView;
+    link: HTMLAnchorElement;
+    nodePos: number;
+    attrs: HyperlinkAttributes;
+    linkCoords: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    validate?: (url: string) => boolean;
+};
+type CreateHyperlinkOptions = {
+    editor: Editor;
+    extensionName: string;
+    attributes: Partial<HyperlinkAttributes>;
+    validate?: (url: string) => boolean;
+};
+interface HyperlinkOptions {
+    autolink: boolean;
+    protocols: Array<LinkProtocolOptions | string>;
+    openOnClick: boolean;
+    linkOnPaste: boolean;
+    HTMLAttributes: Partial<HyperlinkAttributes>;
+    popovers: {
+        previewHyperlink?: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
+        createHyperlink?: ((options: CreateHyperlinkOptions) => HTMLElement | null) | null;
+    };
+    validate?: (url: string) => boolean;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        hyperlink: {
+            editHyperlinkText: (text: string) => ReturnType;
+            editHyperlinkHref: (href: string) => ReturnType;
+            editHyperlink: (attributes?: {
+                newText?: string;
+                newURL?: string;
+                title?: string;
+                image?: string;
+            }) => ReturnType;
+            setHyperlink: (attributes?: {
+                href: string;
+                target?: string | null;
+            }) => ReturnType;
+            unsetHyperlink: () => ReturnType;
+        };
+    }
+}
+declare const Hyperlink: Mark<HyperlinkOptions, any>;
+
+interface FloatingToolbarOptions {
+    referenceElement?: HTMLElement;
+    coordinates?: {
+        x: number;
+        y: number;
+        width?: number;
+        height?: number;
+        contextElement?: HTMLElement;
+    };
+    content: HTMLElement;
+    placement?: Placement;
+    offset?: number;
+    showArrow?: boolean;
+    className?: string;
+    zIndex?: number;
+    onShow?: () => void;
+    onHide?: () => void;
+}
+interface FloatingToolbarInstance {
+    element: HTMLElement;
+    show: () => void;
+    hide: () => void;
+    destroy: () => void;
+    isVisible: () => boolean;
+    setContent: (content: HTMLElement) => void;
+    updateReference: (referenceElement?: HTMLElement, coordinates?: FloatingToolbarOptions['coordinates']) => void;
+}
+declare const DEFAULT_OFFSET = 8;
+declare function createFloatingToolbar(options: FloatingToolbarOptions): FloatingToolbarInstance;
+declare const getCurrentToolbar: () => FloatingToolbarInstance | null;
+declare const isToolbarVisible: () => boolean;
+declare const hideCurrentToolbar: () => void;
+declare const destroyCurrentToolbar: () => void;
+declare const updateCurrentToolbarPosition: (referenceElement?: HTMLElement, coordinates?: FloatingToolbarOptions["coordinates"]) => void;
+
+declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement | null;
+
+type EditHyperlinkModalOptions = {
+    editor: Editor;
+    validate?: (url: string) => boolean;
+    view: EditorView;
+    link: HTMLAnchorElement;
+    linkCoords: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    onBack?: () => void;
+    markName?: string;
+};
+declare function editHyperlinkPopover(options: EditHyperlinkModalOptions): void;
+
+declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
+
+declare const copyToClipboard: (text: string, callback?: (success: boolean) => void) => Promise<boolean>;
+
+declare const createHTMLElement: <K extends keyof HTMLElementTagNameMap>(type: K, props?: Partial<HTMLElementTagNameMap[K]>) => HTMLElementTagNameMap[K];
+
+interface IconProps {
+    size?: number;
+    fill?: string;
+}
+declare const Copy: ({ size, fill }?: IconProps) => string;
+declare const LinkOff: ({ size, fill }?: IconProps) => string;
+declare const Link: ({ size, fill }?: IconProps) => string;
+declare const Pencil: ({ size, fill }?: IconProps) => string;
+declare const Title: ({ size, fill }?: IconProps) => string;
+
+declare const normalizeHref: (raw: string) => string;
+/**
+ * Shape we depend on from a linkifyjs match (plus autolink's
+ * manually-constructed special-scheme entries, which also set `type`).
+ * Loosened to avoid importing linkifyjs types across the public boundary.
+ */
+type LinkifyMatchLike = {
+    type: string;
+    value: string;
+    href: string;
+};
+/**
+ * Canonicalize a linkifyjs match for storage.
+ *
+ * linkifyjs defaults URL matches to `http://…`; we prefer `https://` to
+ * stay consistent with the create popover and markdown input rule, so
+ * URL matches run through `normalizeHref(value)`. Non-URL matches
+ * (emails → `mailto:`, etc.) already carry a meaningful scheme in `href`
+ * and are returned unchanged.
+ */
+declare const normalizeLinkifyHref: (link: LinkifyMatchLike) => string;
+
+/**
+ * Special URL schemes and their corresponding SVG icons
+ * Based on: https://github.com/bhagyas/app-urls
+ */
+type SpecialUrlInfo = {
+    type: string;
+    title: string;
+    /**
+     * Icon identifier hint for consumers (e.g. `'HiMail'`, `'FaWhatsapp'`).
+     * Not rendered by the extension — consumers map this to their own icon
+     * components (React icons, SVG sprites, etc.).
+     */
+    icon: string;
+    category: 'communication' | 'social' | 'productivity' | 'entertainment' | 'shopping' | 'development' | 'apple' | 'other';
+};
+/**
+ * Detect special URL and return corresponding info
+ */
+declare const getSpecialUrlInfo: (url: string) => SpecialUrlInfo | null;
+/**
+ * Get all available categories
+ */
+declare const getCategories: () => string[];
+/**
+ * Get URLs by category
+ */
+declare const getUrlsByCategory: (category: string) => Record<string, SpecialUrlInfo>;
+
+/** Schemes that must never be used as link hrefs (XSS vectors). */
+declare const DANGEROUS_SCHEME_RE: RegExp;
+type ValidateURLOptions = {
+    customValidator?: (url: string) => boolean;
+};
+/**
+ * Validates URLs including both standard web URLs and special app/protocol schemes
+ *
+ * Supports:
+ * - Standard web URLs (http, https, ftp)
+ * - Email addresses (mailto:)
+ * - Phone numbers (tel:, sms:)
+ * - App deep links (whatsapp:, discord:, etc.)
+ * - Apple app schemes (maps:, music:, etc.)
+ * - Development tools (github:, vscode:, etc.)
+ * - Domain-based detection (wa.me, t.me, etc.)
+ *
+ * For http(s)/ftp(s) URLs, the host must also look real — a TLD dot,
+ * `localhost`, or an IP literal. This rejects scheme-prefixed typos like
+ * `https://googlecom` that linkifyjs alone would accept.
+ *
+ * @param url - The URL string to validate
+ * @param options - Optional configuration
+ * @param options.customValidator - Custom validation function to apply additional checks
+ * @returns true if the URL is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateURL('https://example.com') // true
+ * validateURL('mailto:user@example.com') // true
+ * validateURL('tel:+1234567890') // true
+ * validateURL('whatsapp://send?text=hello') // true
+ * validateURL('wa.me/1234567890') // true
+ * validateURL('https://googlecom') // false (no TLD, no localhost, no IP)
+ * validateURL('invalid-url') // false
+ * ```
+ */
+declare const validateURL: (url: string, options?: ValidateURLOptions) => boolean;
+/**
+ * Get the scheme/protocol from a URL
+ * @param url - The URL to extract scheme from
+ * @returns The scheme (e.g., 'https', 'mailto', 'tel') or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getUrlScheme('https://example.com') // 'https'
+ * getUrlScheme('mailto:user@example.com') // 'mailto'
+ * getUrlScheme('invalid') // null
+ * ```
+ */
+declare const getUrlScheme: (url: string) => string | null;
+/**
+ * Check if a URL is a special app/protocol scheme (not http/https)
+ * @param url - The URL to check
+ * @returns true if it's a special scheme, false for standard web URLs
+ *
+ * @example
+ * ```typescript
+ * isSpecialSchemeUrl('mailto:user@example.com') // true
+ * isSpecialSchemeUrl('https://example.com') // false
+ * ```
+ */
+declare const isSpecialSchemeUrl: (url: string) => boolean;
+
+export { Copy, type CreateHyperlinkOptions, DANGEROUS_SCHEME_RE, DEFAULT_OFFSET, type FloatingToolbarInstance, type FloatingToolbarOptions, Hyperlink, type HyperlinkAttributes, type HyperlinkOptions, Link, LinkOff, type LinkProtocolOptions, type LinkifyMatchLike, Pencil, type PreviewHyperlinkOptions, type SpecialUrlInfo, Title, copyToClipboard, createFloatingToolbar, createHTMLElement, createHyperlinkPopover, Hyperlink as default, destroyCurrentToolbar, editHyperlinkPopover, getCategories, getCurrentToolbar, getSpecialUrlInfo, getUrlScheme, getUrlsByCategory, hideCurrentToolbar, isSpecialSchemeUrl, isToolbarVisible, normalizeHref, normalizeLinkifyHref, previewHyperlinkPopover, updateCurrentToolbarPosition, validateURL };