@docs.plus/extension-hyperlink 1.5.1 → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,414 @@
+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 README → Normalization 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;
+};
+
+/**
+ * Schemes blocked at every write boundary: `javascript:` / `vbscript:`
+ * (script execution), `data:` (arbitrary HTML), `file:` (local FS),
+ * `blob:` (in-page memory; never legitimate in stored content).
+ *
+ * Twin of `extension-hypermultimedia`'s copy. Adding a scheme to one and not
+ * the other opens a hole in the twin, so 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 README → Security.
+ */
+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 README → Validation.
+ */
+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;
+}
+
+/** Deps every interaction (input rule, paste rule, autolink, paste handler, click handler) reads. */
+interface LinkContext {
+    type: MarkType;
+    editor: Editor;
+    /** URL Decisions pipeline; one per `createLinkContext` call (the extension allocates one per editor, cached on `storage.context`). */
+    urls: URLDecisions;
+    options: HyperlinkOptions;
+    /** Convenience accessor for `options.validate`. */
+    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 README → Commands. */
+    setHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
+    /** Remove the hyperlink mark from the current selection. */
+    unsetHyperlink: () => ReturnType;
+    /** Toggle the hyperlink mark; 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 README → 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: README → 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 README → 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 exits the 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>;
+
+interface BuildPreviewOptionsFromAnchorArgs {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    /** Prefer this ProseMirror position before falling back to DOM similarity. */
+    nodePos?: number;
+    /** Forwarded onto the returned options; usually the configured `validate` option. */
+    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;
+
+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 = {
+    /** The popover's root element — what subscribers attach focus rings, scroll-freezes, or DOM observers to. */
+    element: HTMLElement;
+    /** The anchor the popover is glued to — `null` for virtual-coords popovers (e.g. selection-anchored create). */
+    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;
+
+/** Hide the shared tooltip bubble and cancel any pending show. */
+declare function hideTooltip(): void;
+/** Show `label` above `target` after a short hover/focus delay. Returns a detach function for surfaces that re-render in place. */
+declare function attachTooltip(target: HTMLElement, label: string): () => void;
+
+declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement;
+
+declare function editHyperlinkPopover(options: EditHyperlinkOptions): HTMLElement;
+
+declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
+
+/**
+ * `window.open` features string for safe navigation — every
+ * `window.open(href, '_blank', …)` call needs this explicit arg or the
+ * opened tab can read `window.opener` and the Referer leaks. Re-exported
+ * so downstream popovers pin the same value.
+ */
+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;
+
+/**
+ * Special URL schemes and well-known domains the extension classifies
+ * for the preview popover.
+ *
+ * Catalog source: https://github.com/bhagyas/app-urls
+ */
+/**
+ * String-literal union so consumers can declare a
+ * `Partial<Record<SpecialUrlType, …>>` icon map with exhaustive
+ * autocomplete — type-only, zero runtime bytes. Naming convention lives
+ * 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 (scheme prefix or host suffix).
+ * Returns `null` for plain web URLs — the consumer should fall back to
+ * a generic favicon. Mapping `type`/`category` to an icon is the
+ * consumer's job; the extension stays brand-neutral on purpose.
+ */
+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 };