@docs.plus/extension-hyperlink 1.5.2 → 2.1.0

package/dist/index.d.cts

@@ -0,0 +1,392 @@
+import { Editor, Mark } from '@tiptap/core';
+import { MarkType } from '@tiptap/pm/model';
+import { Placement } from '@floating-ui/dom';
+export { registerCustomProtocol } from 'linkifyjs';
+
+/**
+ * Canonicalize a user-supplied href so stored marks point somewhere
+ * absolute (bare `google.com` would otherwise resolve against
+ * `document.baseURI` at render time). See docs/url-handling.md for
+ * the full pipeline order.
+ */
+declare const normalizeHref: (raw: string, defaultProtocol?: string) => string;
+/**
+ * Shape `findLinks` produces (linkifyjs match + our synthetic
+ * special-scheme / phone entries). Loosened so linkifyjs types don't
+ * leak across the public boundary.
+ */
+type LinkifyMatchLike = {
+    type: string;
+    value: string;
+    href: string;
+};
+
+/**
+ * Blocked schemes: `javascript:`/`vbscript:` (script), `data:`, `file:`, `blob:`.
+ * Twin of hypermultimedia's copy — preflight diffs them byte-for-byte.
+ */
+declare const DANGEROUS_SCHEME_RE: RegExp;
+/**
+ * Single XSS gate used at every read/write boundary. Returns `false`
+ * for nullish/empty hrefs and any scheme matched by
+ * {@link DANGEROUS_SCHEME_RE}. See docs/security.md.
+ */
+declare const isSafeHref: (href: string | null | undefined) => href is string;
+type ValidateURLOptions = {
+    customValidator?: (url: string) => boolean;
+};
+/**
+ * Shape-validate a URL: web schemes with a plausible host, app schemes from
+ * the `getSpecialUrlInfo` catalog, and bare E.164 phones. Rejects schemes
+ * matched by {@link DANGEROUS_SCHEME_RE}. See docs/url-handling.md.
+ */
+declare const validateURL: (url: string, options?: ValidateURLOptions) => boolean;
+
+/** Discriminated input to {@link URLDecisions.forWrite}. */
+type WriteInput = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'href';
+    href: string;
+} | {
+    kind: 'match';
+    match: LinkifyMatchLike;
+};
+type WriteResult = {
+    /** Canonical, gated, write-safe href ready to set on the mark. */
+    href: string;
+    /** Source offset; `0` for `href`/`match` inputs. */
+    start: number;
+    end: number;
+};
+type ReadDecision = {
+    /** Passes the full gate (`isSafeHref` + `isAllowedUri`) — required before any `window.open`. */
+    navigable: boolean;
+};
+type WriteOptions = {
+    /** Per-call override of the controller's `validate`. */
+    validate?: (url: string) => boolean;
+};
+interface URLDecisions {
+    /** Resolve a write candidate to its canonical, gated href(s). Returns `[]` when nothing passes. */
+    forWrite(input: WriteInput, opts?: WriteOptions): WriteResult[];
+    /** Read-side gate for render + navigation. */
+    forRead(href: string | null | undefined): ReadDecision;
+    /**
+     * Pure shape check — skips the gate stack on purpose. That keeps a tightened
+     * `isAllowedUri` policy out of autolink's "is the existing link still
+     * link-shaped?" cleanup pass.
+     */
+    detect(text: string): boolean;
+}
+
+interface LinkContext {
+    type: MarkType;
+    editor: Editor;
+    /** One URL Decisions pipeline per editor (cached on `storage.context`). */
+    urls: URLDecisions;
+    options: HyperlinkOptions;
+    validate?: (url: string) => boolean;
+    /** Preview popover factory, or `null` when the host opted out. */
+    previewPopover: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
+}
+
+type SetHyperlinkAttributes = {
+    href: string;
+    target?: string | null;
+    title?: string | null;
+    image?: string | null;
+} & Record<string, unknown>;
+type EditHyperlinkAttributes = {
+    newText?: string;
+    newURL?: string;
+    title?: string;
+    image?: string;
+};
+interface HyperlinkPublicCommands<ReturnType> {
+    /** Write the hyperlink mark; returns `false` when `href` is missing or fails the gate. See docs/api.md → Commands. */
+    setHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
+    unsetHyperlink: () => ReturnType;
+    /** Toggle; same gates as `setHyperlink`. */
+    toggleHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
+    /** Open the create popover (configured `popovers.createHyperlink` or the prebuilt fallback); no-op only when the factory returns `null`. See docs/api.md → Commands. */
+    openCreateHyperlinkPopover: (attributes?: Partial<HyperlinkAttributes>) => ReturnType;
+    editHyperlinkText: (text: string) => ReturnType;
+    editHyperlinkHref: (href: string) => ReturnType;
+    editHyperlink: (attributes?: EditHyperlinkAttributes) => ReturnType;
+    /** Migration alias for `setHyperlink` (drop-in `@tiptap/extension-link` compat). */
+    setLink: (attributes: SetHyperlinkAttributes) => ReturnType;
+    /** Migration alias for `unsetHyperlink`. */
+    unsetLink: () => ReturnType;
+    /** Migration alias for `toggleHyperlink`. */
+    toggleLink: (attributes: SetHyperlinkAttributes) => ReturnType;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        hyperlink: HyperlinkPublicCommands<ReturnType>;
+    }
+}
+
+interface LinkProtocolOptions {
+    scheme: string;
+    optionalSlashes?: boolean;
+}
+/** Context for the user `isAllowedUri` hook; mirrors `@tiptap/extension-link`. */
+type IsAllowedUriContext = {
+    /** Built-in safety gate (`isSafeHref`). */
+    defaultValidate: (uri: string) => boolean;
+    /** Protocols registered via the `protocols` option. */
+    protocols: Array<LinkProtocolOptions | string>;
+    defaultProtocol: string;
+};
+/**
+ * `Extra` extends the built-ins with consumer-typed fields; it defaults to
+ * `Record<string, unknown>` to keep the v2 open index signature. Example: docs/api.md → TypeScript.
+ */
+type HyperlinkAttributes<Extra extends Record<string, unknown> = Record<string, unknown>> = {
+    href: string | null;
+    target: string | null;
+    rel: string | null;
+    class: string | null;
+    title: string | null;
+    image: string | null;
+} & Extra;
+type PreviewHyperlinkOptions = {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    nodePos: number;
+    attrs: HyperlinkAttributes;
+    validate?: (url: string) => boolean;
+    /** Composed XSS + `isAllowedUri` gate; BYO popovers must call this before any `window.open`. */
+    isAllowedUri?: (uri: string) => boolean;
+};
+type CreateHyperlinkOptions = {
+    editor: Editor;
+    extensionName: string;
+    attributes: Partial<HyperlinkAttributes>;
+    validate?: (url: string) => boolean;
+};
+type EditHyperlinkOptions = {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    /** Optional mark position; lets edit/back recover from ProseMirror replacing duplicate link DOM. */
+    nodePos?: number;
+    validate?: (url: string) => boolean;
+    /** Composed XSS + `isAllowedUri` gate to preserve preview policy across edit/back. */
+    isAllowedUri?: (uri: string) => boolean;
+    /** Override the default Back behaviour. Default re-opens the preview popover via `openPreviewHyperlink`. */
+    onBack?: () => void;
+    /** Mark name; defaults to `HYPERLINK_MARK_NAME`. */
+    markName?: string;
+};
+interface HyperlinkOptions {
+    autolink: boolean;
+    protocols: Array<LinkProtocolOptions | string>;
+    openOnClick: boolean;
+    linkOnPaste: boolean;
+    HTMLAttributes: Partial<HyperlinkAttributes>;
+    popovers: {
+        previewHyperlink?: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
+        editHyperlink?: ((options: EditHyperlinkOptions) => HTMLElement | null) | null;
+        createHyperlink?: ((options: CreateHyperlinkOptions) => HTMLElement | null) | null;
+    };
+    validate?: (url: string) => boolean;
+    /** Scheme used by `normalizeHref` to promote bare domains. Default `'https'`. See docs/api.md → Options. */
+    defaultProtocol: string;
+    /** URI policy hook — runs AFTER `isSafeHref`, BEFORE the mark is written. Mirrors `@tiptap/extension-link`. */
+    isAllowedUri?: (uri: string, ctx: IsAllowedUriContext) => boolean;
+    /** Per-link autolink veto. Return `false` to skip autolinking a specific URI (manual `setHyperlink` still works). */
+    shouldAutoLink?: (uri: string) => boolean;
+    /** Click inside a link selects the whole mark range (editable mode only). Mirrors `@tiptap/extension-link`. */
+    enableClickSelection: boolean;
+    /** ArrowRight at the right edge of a link drops a stored link mark. Mirrors `@tiptap/extension-link`. */
+    exitable: boolean;
+}
+/** Extension storage; one slot per editor instance. */
+interface HyperlinkStorage {
+    /**
+     * Cached `LinkContext`; populated on first access so all four `add*`
+     * hooks share one URL Decisions pipeline instead of allocating per hook.
+     */
+    context: LinkContext | null;
+}
+declare const Hyperlink: Mark<HyperlinkOptions, HyperlinkStorage>;
+
+type PopoverKind = 'preview' | 'edit' | 'create' | (string & {});
+type VirtualCoordinates = {
+    getBoundingClientRect: () => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    contextElement?: HTMLElement;
+};
+interface ManagedPopover {
+    hide: () => void;
+    destroy: () => void;
+    updateReference: (referenceElement?: HTMLElement, coordinates?: VirtualCoordinates) => void;
+}
+type AdoptMetadata = {
+    element: HTMLElement;
+    referenceElement: HTMLElement | null;
+};
+type ControllerState = {
+    kind: 'idle';
+} | ({
+    kind: 'mounted';
+    popoverKind: PopoverKind;
+} & AdoptMetadata);
+interface PopoverController {
+    adopt(popover: ManagedPopover, kind: PopoverKind, metadata: AdoptMetadata): () => void;
+    close(): void;
+    reposition(referenceElement?: HTMLElement, coordinates?: VirtualCoordinates): void;
+    getState(): ControllerState;
+    subscribe(listener: (state: ControllerState) => void): () => void;
+}
+declare function getDefaultController(): PopoverController;
+
+type PopoverAnchor = {
+    referenceElement: HTMLElement;
+    coordinates?: never;
+} | {
+    referenceElement?: never;
+    coordinates: VirtualCoordinates;
+};
+type PopoverShellOptions = {
+    content: HTMLElement;
+    placement?: Placement;
+    offset?: number;
+    showArrow?: boolean;
+    className?: string;
+    zIndex?: number;
+    /**
+     * ARIA has no popover role — the shell carries its content's role
+     * (`toolbar`, `dialog`, …) and stays role-less when omitted.
+     */
+    role?: string;
+    /** Same ARIA axis as `role` — shell-level so BYO content inherits the accessible name. */
+    ariaLabel?: string;
+    /**
+     * Nodes that must not light-dismiss (toggle triggers). When set, only these
+     * are ignored — not `referenceElement` — so a larger position surface (e.g.
+     * a toolbar bar) can still dismiss on sibling clicks. When omitted, the
+     * HTMLElement `referenceElement` is ignored instead.
+     */
+    ignoreOutsideClickOn?: HTMLElement | HTMLElement[];
+    /**
+     * When false, `shift` only moves on the main axis so end-aligned menus
+     * (e.g. toolbar overflow) stay pinned to the reference’s end edge.
+     * @default true
+     */
+    crossAxisShift?: boolean;
+    onShow?: () => void;
+    onHide?: () => void;
+};
+type PopoverOptions = PopoverAnchor & PopoverShellOptions;
+/**
+ * One-shot once opened: hiding releases the controller's ownership and nothing
+ * re-adopts, so `show()` will not reopen it. Build a new popover instead — a
+ * re-shown one would sit outside the single-popover invariant, invisible to
+ * `close()` and never evicted by the next `adopt()`.
+ */
+interface Popover {
+    element: HTMLElement;
+    /** No-op once the popover has been hidden or destroyed. */
+    show: () => void;
+    /** Terminal once shown. Before the first `show()` it no-ops and keeps ownership. */
+    hide: () => void;
+    destroy: () => void;
+    isVisible: () => boolean;
+    setContent: (content: HTMLElement) => void;
+    updateReference: (referenceElement?: HTMLElement, coordinates?: VirtualCoordinates) => void;
+}
+declare const DEFAULT_OFFSET = 8;
+declare function createPopover(options: PopoverOptions): Popover;
+
+interface BuildPreviewOptionsFromAnchorArgs {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    /** Prefer this ProseMirror position before falling back to DOM similarity. */
+    nodePos?: number;
+    validate?: (url: string) => boolean;
+    /** Preserve the host's composed navigation gate when rebuilding preview from edit/back. */
+    isAllowedUri?: (uri: string) => boolean;
+    /** Mark name to look up; defaults to `'hyperlink'`. Override only if the schema mark was renamed. */
+    markName?: string;
+}
+/**
+ * Exists so the edit popover's Back button and BYO `editHyperlink` factories
+ * share one `posAtDOM → mark.attrs` lookup. The DOM `link.href` property is
+ * never the raw-href fallback — it resolves relative hrefs against
+ * `document.baseURI`, leaking the host origin into a stored attribute.
+ */
+declare function buildPreviewOptionsFromAnchor({ editor, link, nodePos: preferredNodePos, validate, isAllowedUri, markName }: BuildPreviewOptionsFromAnchorArgs): PreviewHyperlinkOptions;
+
+/**
+ * Open the create-hyperlink popover anchored to the current selection.
+ * Returns `false` when the host opted out (factory returned `null`).
+ */
+declare function openCreateHyperlink(editor: Editor, attributes?: Partial<HyperlinkAttributes>): boolean;
+
+/**
+ * Open the edit popover anchored to a hyperlink. The prebuilt popover's
+ * Back button closes over `opts`, so no extra wiring is needed to
+ * return to the preview.
+ */
+declare function openEditHyperlink(opts: EditHyperlinkOptions): void;
+
+/**
+ * Returns `false` when the host opted out (factory returned `null`, e.g. a
+ * mobile bottom sheet). The click handler gates caret placement on it —
+ * `.focus()` on an opting-out host makes iOS Safari scroll the editor.
+ */
+declare function openPreviewHyperlink(opts: PreviewHyperlinkOptions): boolean;
+
+declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement;
+
+declare function editHyperlinkPopover(options: EditHyperlinkOptions): HTMLElement;
+
+declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
+
+declare function hideTooltip(): void;
+/** Returns a detach function for surfaces that re-render in place. */
+declare function attachTooltip(target: HTMLElement, label: string): () => void;
+
+/**
+ * Required `window.open` features. Without this arg the opened tab can
+ * read `window.opener` and the Referer leaks. Re-exported so popovers pin it.
+ */
+declare const SAFE_WINDOW_FEATURES: "noopener,noreferrer";
+
+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 Pencil: ({ size, fill }?: IconProps) => string;
+
+/** Catalog of app schemes and well-known domains. Source: https://github.com/bhagyas/app-urls */
+/**
+ * Type-only union for consumer icon maps (`Partial<Record<SpecialUrlType, …>>`).
+ * Zero runtime bytes. Naming convention is in this package's AGENTS.md.
+ */
+type SpecialUrlType = 'email' | 'phone' | 'sms' | 'facetime' | 'facetime-audio' | 'whatsapp' | 'telegram' | 'discord' | 'skype' | 'slack' | 'twitter' | 'facebook' | 'instagram' | 'linkedin' | 'snapchat' | 'reddit' | 'tiktok' | 'zoom' | 'teams' | 'webex' | 'meet' | 'calendar' | 'reminders' | 'contacts' | 'maps' | 'music' | 'apple-tv' | 'notes' | 'photos' | 'shortcuts' | 'app-store' | 'github' | 'gitlab' | 'vscode' | 'notion' | 'obsidian' | 'figma' | 'youtube' | 'spotify' | 'netflix' | 'twitch' | 'amazon' | 'uber' | 'lyft';
+type SpecialUrlInfo = {
+    type: SpecialUrlType;
+    title: string;
+    category: 'communication' | 'social' | 'productivity' | 'entertainment' | 'shopping' | 'development' | 'apple' | 'other';
+};
+/**
+ * Classify `url` against the catalog. `null` means a plain web URL (favicon).
+ * Icon mapping is the consumer's job; this package stays brand-neutral.
+ */
+declare const getSpecialUrlInfo: (url: string) => SpecialUrlInfo | null;
+
+export { type AdoptMetadata, type BuildPreviewOptionsFromAnchorArgs, type ControllerState, Copy, type CreateHyperlinkOptions, DANGEROUS_SCHEME_RE, DEFAULT_OFFSET, type EditHyperlinkAttributes, type EditHyperlinkOptions, Hyperlink, type HyperlinkAttributes, type HyperlinkOptions, type HyperlinkPublicCommands, type HyperlinkStorage, type IconProps, type IsAllowedUriContext, LinkOff, type LinkProtocolOptions, type LinkifyMatchLike, Pencil, type Popover, type PopoverController, type PopoverKind, type PopoverOptions, type PreviewHyperlinkOptions, SAFE_WINDOW_FEATURES, type SetHyperlinkAttributes, type SpecialUrlInfo, type SpecialUrlType, type ValidateURLOptions, type VirtualCoordinates, attachTooltip, buildPreviewOptionsFromAnchor, copyToClipboard, createHTMLElement, createHyperlinkPopover, createPopover, Hyperlink as default, editHyperlinkPopover, getDefaultController, getSpecialUrlInfo, hideTooltip, isSafeHref, normalizeHref, openCreateHyperlink, openEditHyperlink, openPreviewHyperlink, previewHyperlinkPopover, validateURL };