@docs.plus/extension-hyperlink 1.5.1 → 2.0.0

package/dist/styles.css

@@ -0,0 +1,403 @@
+/**
+ * @docs.plus/extension-hyperlink — default styles
+ *
+ * A minimal, framework-agnostic stylesheet for the prebuilt create/preview/edit
+ * popovers. Every visual token is exposed as a `--hl-*` CSS custom property so
+ * consumers can retheme without copy-pasting rules.
+ *
+ * Usage:
+ *   import '@docs.plus/extension-hyperlink/styles.css'
+ *
+ * Theming:
+ *   :root {
+ *     --hl-accent: #2563eb;
+ *     --hl-radius: 8px;
+ *   }
+ *
+ * Customizing a specific rule is fine — class names are part of the public API
+ * and are documented in the README.
+ */
+
+/*
+ * Theme tokens use `light-dark()` so the popover follows the nearest
+ * ancestor's `color-scheme` — that means a consumer who toggles
+ * `color-scheme: light | dark` on <html> (or an ancestor) flips the
+ * popover automatically, and it no longer gets stuck in dark mode just
+ * because the OS prefers dark. When `color-scheme` is `normal` (the
+ * default), `light-dark()` falls back to `prefers-color-scheme`, which
+ * preserves the previous OS-driven behavior for unopinionated hosts.
+ */
+:root {
+  --hl-bg: light-dark(#ffffff, #1f2937);
+  --hl-fg: light-dark(#111827, #f3f4f6);
+  --hl-muted: light-dark(#6b7280, #9ca3af);
+  --hl-border: light-dark(#e5e7eb, #374151);
+  --hl-hover: light-dark(#f3f4f6, #374151);
+  --hl-accent: light-dark(#2563eb, #60a5fa);
+  --hl-accent-fg: light-dark(#ffffff, #0b1220);
+  --hl-danger: light-dark(#dc2626, #f87171);
+  /* Elevation matches the docs.plus floating-surface language: 10px shells with a
+     two-layer overlay shadow (anchored panels), 8px inner controls. */
+  --hl-shadow:
+    0 20px 25px -5px light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.5)),
+    0 8px 10px -6px light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.4));
+  --hl-radius: 10px;
+  --hl-radius-sm: 8px;
+  --hl-font:
+    ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --hl-font-size: 14px;
+  /* Deceleration-only: popover hide removes the node, so this curve only ever plays entrances. */
+  --hl-transition: 120ms ease-out;
+}
+
+/* -------------------------------------------------------------------------
+   Floating popover shell (shared by all three popovers — preview / edit / create)
+   Positioning (fixed + top/left + z-index 9999) is inline from createPopover;
+   override stacking via `createPopover({ zIndex })`.
+   extension-hypermultimedia's media-toolbar.css carries a lockstep copy of
+   this shell — mirror edits there.
+   ------------------------------------------------------------------------- */
+.floating-popover {
+  opacity: 0;
+  transform: scale(0.96);
+  /* exit: 80ms ease-in fade (plays when .visible is removed; engine defers removal) */
+  transition:
+    opacity 80ms ease-in,
+    transform 80ms ease-in;
+  pointer-events: none;
+  -webkit-tap-highlight-color: transparent;
+  will-change: transform, opacity;
+}
+
+.floating-popover.visible {
+  opacity: 1;
+  transform: scale(1);
+  pointer-events: auto;
+  /* enter: 120ms ease-out scale from the anchored side (engine sets transform-origin) */
+  transition:
+    opacity 120ms ease-out,
+    transform 120ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .floating-popover,
+  .floating-popover.visible {
+    transition: none;
+  }
+}
+
+.floating-popover-arrow {
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  background: var(--hl-bg);
+  transform: rotate(45deg);
+  pointer-events: none;
+  z-index: 1;
+}
+
+.floating-popover-arrow-top {
+  border-right: 1px solid var(--hl-border);
+  border-bottom: 1px solid var(--hl-border);
+}
+
+.floating-popover-arrow-bottom {
+  border-top: 1px solid var(--hl-border);
+  border-left: 1px solid var(--hl-border);
+}
+
+.floating-popover-arrow-left {
+  border-top: 1px solid var(--hl-border);
+  border-right: 1px solid var(--hl-border);
+}
+
+.floating-popover-arrow-right {
+  border-bottom: 1px solid var(--hl-border);
+  border-left: 1px solid var(--hl-border);
+}
+
+.floating-popover-content {
+  position: relative;
+  z-index: 2;
+}
+
+/* -------------------------------------------------------------------------
+   Floating tooltip (icon buttons in the prebuilt popovers)
+   Behavior ships in the bundled @docs.plus/floating-tooltip; this skin is
+   the consumer's, lockstep with extension-hypermultimedia's media-toolbar.css.
+   Both extensions style this one global class, so the block uses identical
+   literals, never per-package tokens: with both bundles loaded, cascade
+   order would pick one package's tokens for every bubble.
+   ------------------------------------------------------------------------- */
+.floating-tooltip {
+  position: fixed;
+  z-index: 10000;
+  width: max-content;
+  padding: 3px 8px;
+  border-radius: 6px;
+  background: light-dark(#374151, #e5e7eb);
+  color: light-dark(#ffffff, #1f2937);
+  font-size: 11px;
+  box-shadow: 0 4px 12px light-dark(rgba(0, 0, 0, 0.15), rgba(0, 0, 0, 0.5));
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(2px);
+  transition:
+    opacity 100ms ease,
+    transform 100ms ease;
+}
+
+.floating-tooltip.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* -------------------------------------------------------------------------
+   Popover shell — shared shape for create / preview / edit
+   ------------------------------------------------------------------------- */
+.hyperlink-create-popover,
+.hyperlink-preview-popover,
+.hyperlink-edit-popover {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px;
+  background: var(--hl-bg);
+  color: var(--hl-fg);
+  border: 1px solid var(--hl-border);
+  border-radius: var(--hl-radius);
+  box-shadow: var(--hl-shadow);
+  font-family: var(--hl-font);
+  font-size: var(--hl-font-size);
+  line-height: 1.4;
+}
+
+.hyperlink-create-popover form,
+.hyperlink-edit-popover {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  width: 100%;
+}
+
+/* Input groups (create + edit) */
+.hyperlink-create-popover .inputs-wrapper,
+.hyperlink-edit-popover .text-wrapper,
+.hyperlink-edit-popover .href-wrapper {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  padding: 6px 8px;
+  background: var(--hl-bg);
+  border: 1px solid var(--hl-border);
+  border-radius: var(--hl-radius-sm);
+  transition:
+    border-color var(--hl-transition),
+    box-shadow var(--hl-transition);
+}
+
+.hyperlink-create-popover .inputs-wrapper:focus-within,
+.hyperlink-edit-popover .text-wrapper:focus-within,
+.hyperlink-edit-popover .href-wrapper:focus-within {
+  border-color: var(--hl-accent);
+  box-shadow: 0 0 0 1px var(--hl-accent);
+}
+
+.hyperlink-create-popover .inputs-wrapper.error,
+.hyperlink-edit-popover .text-wrapper.error,
+.hyperlink-edit-popover .href-wrapper.error {
+  border-color: var(--hl-danger);
+  box-shadow: 0 0 0 1px var(--hl-danger);
+}
+
+.hyperlink-create-popover .inputs-wrapper,
+.hyperlink-edit-popover .text-wrapper,
+.hyperlink-edit-popover .href-wrapper {
+  min-width: 0;
+  max-width: 100%;
+  box-sizing: border-box;
+}
+
+.hyperlink-create-popover input,
+.hyperlink-edit-popover input {
+  flex: 1;
+  min-width: 0;
+  padding: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+}
+
+.hyperlink-create-popover input::placeholder,
+.hyperlink-edit-popover input::placeholder {
+  color: var(--hl-muted);
+}
+
+.hyperlink-create-popover .search-icon,
+.hyperlink-edit-popover .search-icon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--hl-muted);
+}
+
+.hyperlink-create-popover .search-icon svg,
+.hyperlink-edit-popover .search-icon svg {
+  width: 18px;
+  height: 18px;
+}
+
+.hyperlink-create-popover .error-message,
+.hyperlink-edit-popover .error-message {
+  position: absolute;
+  top: -8px;
+  left: 8px;
+  display: none;
+  padding: 0 4px;
+  background: var(--hl-bg);
+  color: var(--hl-danger);
+  font-size: 11px;
+  font-weight: 600;
+  border-radius: var(--hl-radius-sm);
+}
+
+.hyperlink-create-popover .error-message.show,
+.hyperlink-edit-popover .error-message.show {
+  display: block;
+}
+
+.hyperlink-create-popover .inputs-wrapper {
+  width: auto;
+  flex: 1;
+  min-width: 0;
+}
+
+/* Action buttons (create submit + edit back/apply) */
+.hyperlink-create-popover .buttons-wrapper,
+.hyperlink-edit-popover .buttons-wrapper {
+  display: flex;
+  flex-shrink: 0;
+  gap: 4px;
+}
+
+.hyperlink-create-popover button[type='submit'],
+.hyperlink-edit-popover .back-button,
+.hyperlink-edit-popover .apply-button {
+  padding: 6px 12px;
+  background: transparent;
+  color: var(--hl-fg);
+  border: none;
+  border-radius: var(--hl-radius-sm);
+  font: inherit;
+  font-weight: 600;
+  white-space: nowrap;
+  cursor: pointer;
+  transition:
+    background-color var(--hl-transition),
+    color var(--hl-transition);
+}
+
+.hyperlink-create-popover button[type='submit']:hover:not(:disabled),
+.hyperlink-edit-popover .back-button:hover,
+.hyperlink-edit-popover .apply-button:hover {
+  background: var(--hl-accent);
+  color: var(--hl-accent-fg);
+}
+
+.hyperlink-create-popover button[type='submit']:disabled {
+  color: var(--hl-muted);
+  cursor: not-allowed;
+}
+
+/* Keyboard-focus ring for popover buttons (inputs get theirs via :focus-within). */
+.hyperlink-create-popover button:focus-visible,
+.hyperlink-preview-popover button:focus-visible,
+.hyperlink-edit-popover button:focus-visible {
+  outline: 2px solid var(--hl-accent);
+  outline-offset: 1px;
+}
+
+/* -------------------------------------------------------------------------
+   Preview popover (anchor + copy / edit / remove icon buttons)
+   ------------------------------------------------------------------------- */
+.hyperlink-preview-popover a {
+  display: inline-block;
+  max-width: 260px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 2px 6px;
+  color: var(--hl-accent);
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.hyperlink-preview-popover a:hover {
+  text-decoration: underline;
+}
+
+.hyperlink-preview-popover button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 5px;
+  background: transparent;
+  border: none;
+  border-radius: var(--hl-radius-sm);
+  color: var(--hl-fg);
+  cursor: pointer;
+  transition: background-color var(--hl-transition);
+}
+
+.hyperlink-preview-popover button:hover {
+  background: var(--hl-hover);
+}
+
+.hyperlink-preview-popover button svg {
+  width: 18px;
+  height: 18px;
+}
+
+.hyperlink-preview-popover .copy {
+  margin-left: auto;
+}
+
+.hyperlink-edit-popover {
+  align-items: stretch;
+}
+
+.hyperlink-edit-popover .inputs-wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+}
+
+.hyperlink-edit-popover .buttons-wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex-shrink: 0;
+}
+
+.hyperlink-edit-popover .back-button,
+.hyperlink-edit-popover .apply-button {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Matches extension-hypermultimedia's reduced-motion guard for the shared surfaces. */
+@media (prefers-reduced-motion: reduce) {
+  .floating-popover,
+  .floating-tooltip {
+    transition: none;
+  }
+}

package/package.json

@@ -1,50 +1,100 @@
 {
   "name": "@docs.plus/extension-hyperlink",
-  "description": "Hyperlink component for docs.plus",
-  "version": "1.5.1",
+  "version": "2.0.0",
+  "description": "Tiptap extension for hyperlinks with built-in popovers, auto-linking, and 50+ URL scheme support",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
   "author": "Hossein Marzban",
-  "homepage": "https://github.com/HMarzban/extension-hyperlink",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/docs-plus/docs.plus/tree/main/extensions/extension-hyperlink#readme",
+  "bugs": {
+    "url": "https://github.com/docs-plus/docs.plus/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/docs-plus/docs.plus",
-    "directory": "packages/extension-hyperlink"
+    "directory": "extensions/extension-hyperlink"
+  },
+  "scripts": {
+    "build": "NODE_ENV=production bunx tsup",
+    "dev": "bunx tsup --watch",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "playground": "bun --hot docs-playground --entry ./test/playground/main.ts --port 5173",
+    "test:unit": "bun test src",
+    "test:unit:watch": "bun test --watch src",
+    "pretest": "bun run build",
+    "test": "bun run test:unit && bunx start-server-and-test playground http://127.0.0.1:5173 cypress:run",
+    "test:e2e": "bunx start-server-and-test playground http://127.0.0.1:5173 cypress:run",
+    "test:e2e:watch": "bunx start-server-and-test playground http://127.0.0.1:5173 cypress:open",
+    "cypress:run": "bunx cypress run",
+    "cypress:open": "bunx cypress open",
+    "docs:screenshots": "bun run build && bunx start-server-and-test playground http://127.0.0.1:5173 'bunx cypress run --config specPattern=cypress/docs/**/*.cy.ts'",
+    "prepack": "bunx release-prepack",
+    "prepublishOnly": "bunx release-preflight"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "tiptap",
     "tiptap extension",
     "hyperlink",
     "link",
-    "docs.plus",
-    "prosemirror"
+    "autolink",
+    "rich-text-editor",
+    "floating-ui",
+    "url-validation",
+    "prosemirror",
+    "docs.plus"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "umd": "dist/index.umd.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "src",
-    "dist"
-  ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "npm run clean && rollup -c",
-    "ts": "tsc -p tsconfig.json"
-  },
-  "license": "MIT",
   "dependencies": {
-    "linkifyjs": "^4.1.1",
-    "tippy.js": "^6.3.7"
+    "@floating-ui/dom": "^1.7.6",
+    "linkifyjs": "^4.3.3"
   },
   "peerDependencies": {
-    "@tiptap/core": "^2.0.3",
-    "@tiptap/pm": "^2.0.3"
+    "@tiptap/core": "^3.22.3",
+    "@tiptap/pm": "^3.22.3"
+  },
+  "devDependencies": {
+    "@docs.plus/floating-popover": "0.0.0",
+    "@docs.plus/floating-tooltip": "0.0.0",
+    "@docs.plus/playground": "0.0.0",
+    "@docs.plus/release-tooling": "0.1.0",
+    "@tiptap/core": "^3.22.3",
+    "@tiptap/markdown": "^3.22.3",
+    "@tiptap/pm": "^3.22.3",
+    "@tiptap/starter-kit": "^3.22.3",
+    "@types/node": "^25.5.2",
+    "bun-types": "^1.3.13",
+    "cypress": "^15.13.1",
+    "cypress-real-events": "^1.15.0",
+    "eslint": "^9.39.4",
+    "start-server-and-test": "^2.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   }
 }

package/dist/helpers/autoHyperlink.d.ts

@@ -1,8 +0,0 @@
-import { MarkType } from "@tiptap/pm/model";
-import { Plugin } from "@tiptap/pm/state";
-type AutoHyperlinkOptions = {
-    type: MarkType;
-    validate?: (url: string) => boolean;
-};
-export default function autoHyperlink(options: AutoHyperlinkOptions): Plugin;
-export {};

package/dist/helpers/clickHandler.d.ts

@@ -1,11 +0,0 @@
-import { MarkType } from "@tiptap/pm/model";
-import { Plugin } from "@tiptap/pm/state";
-import { Editor } from "@tiptap/core";
-type ClickHandlerOptions = {
-    type: MarkType;
-    editor: Editor;
-    validate?: (url: string) => boolean;
-    modal?: ((options: any) => void | HTMLElement) | null;
-};
-export default function clickHandler(options: ClickHandlerOptions): Plugin;
-export {};

package/dist/helpers/editHyperlink.d.ts

@@ -1,9 +0,0 @@
-import { Editor } from "@tiptap/core";
-type EditHyperlinkOptions = {
-    editor: Editor;
-    validate?: (url: string) => boolean;
-    newURL?: string;
-    newText?: string;
-};
-export default function editHyperlink(options: EditHyperlinkOptions): boolean;
-export {};

package/dist/helpers/pasteHandler.d.ts

@@ -1,9 +0,0 @@
-import { Editor } from "@tiptap/core";
-import { MarkType } from "@tiptap/pm/model";
-import { Plugin } from "@tiptap/pm/state";
-type PasteHandlerOptions = {
-    editor: Editor;
-    type: MarkType;
-};
-export declare function pasteHandler(options: PasteHandlerOptions): Plugin;
-export {};

package/dist/helpers/tippyHelper.d.ts

@@ -1,29 +0,0 @@
-import { Instance, Props } from "tippy.js";
-import { Editor } from "@tiptap/core";
-import { EditorView } from "@tiptap/pm/view";
-export interface TippyInitOptions {
-    editor: Editor;
-    validate?: (url: string) => boolean;
-}
-declare class Tooltip {
-    private tippyInstance?;
-    private preventHide;
-    private tippyWrapper;
-    private editor;
-    private view;
-    constructor(options: TippyInitOptions);
-    init(): {
-        tippyModal: HTMLDivElement;
-        tippyInstance: Instance<Props> | undefined;
-    };
-    show(): boolean;
-    hide(): boolean;
-    private mousedownHandler;
-    private dragstartHandler;
-    private blurHandler;
-    private tippyBlurHandler;
-    private createTooltip;
-    update(view: EditorView, option?: any): {};
-    destroyTooltip(): void;
-}
-export default Tooltip;

package/dist/hyperlink.d.ts

@@ -1,77 +0,0 @@
-import { Mark } from "@tiptap/core";
-import { TSetHyperlinkModalOptions } from "./modals/setHyperlink";
-import { THyperlinkPreviewModalOptions } from "./modals/previewHyperlink";
-export interface LinkProtocolOptions {
-    scheme: string;
-    optionalSlashes?: boolean;
-}
-export interface HyperlinkOptions {
-    /**
-     * If enabled, it adds links as you type.
-     */
-    autoHyperlink: boolean;
-    /**
-     * An array of custom protocols to be registered with linkifyjs.
-     */
-    protocols: Array<LinkProtocolOptions | string>;
-    /**
-     * If enabled, links will be opened on click.
-     */
-    openOnClick: boolean;
-    /**
-     * Adds a link to the current selection if the pasted content only contains an url.
-     */
-    hyperlinkOnPaste: boolean;
-    /**
-     * A list of HTML attributes to be rendered.
-     */
-    HTMLAttributes: Record<string, any>;
-    /**
-     * A list of modals to be rendered.
-     * @default null
-     * @example
-     */
-    modals: {
-        previewHyperlink?: ((options: THyperlinkPreviewModalOptions) => void | HTMLElement) | null;
-        setHyperlink?: ((options: TSetHyperlinkModalOptions) => void | HTMLElement) | null;
-    };
-    /**
-     * A validation function that modifies link verification for the auto linker.
-     * @param url - The url to be validated.
-     * @returns - True if the url is valid, false otherwise.
-     */
-    validate?: (url: string) => boolean;
-}
-declare module "@tiptap/core" {
-    interface Commands<ReturnType> {
-        link: {
-            /**
-             * Edit the hyperlink's text
-             */
-            editHyperLinkText: (text: string) => ReturnType;
-            /**
-             * Edit the hyperlink's href value
-             */
-            editHyperLinkHref: (href: string) => ReturnType;
-            /**
-             * Edit the hyperlink's
-             */
-            editHyperlink: (attributes?: {
-                newText?: string;
-                newURL?: string;
-            }) => ReturnType;
-            /**
-             *  Set a hyperlink
-             */
-            setHyperlink: (attributes?: {
-                href: string;
-                target?: string | null;
-            }) => ReturnType;
-            /**
-             * Unset a link mark
-             */
-            unsetHyperlink: () => ReturnType;
-        };
-    }
-}
-export declare const Hyperlink: Mark<HyperlinkOptions, any>;