@tiptap/extension-twitch 3.0.0

package/src/twitch.ts

@@ -0,0 +1,257 @@
+import { createAtomBlockMarkdownSpec, mergeAttributes, Node, nodePasteRule } from '@tiptap/core'
+
+import { getEmbedUrlFromTwitchUrl, isValidTwitchUrl, TWITCH_REGEX_GLOBAL } from './utils.js'
+
+export interface TwitchOptions {
+  /**
+   * Controls if the paste handler for Twitch videos should be added.
+   * @default true
+   * @example false
+   */
+  addPasteHandler: boolean
+
+  /**
+   * Controls if the Twitch video should be allowed to go fullscreen.
+   * @default true
+   * @example false
+   */
+  allowFullscreen: boolean
+
+  /**
+   * Controls if the Twitch video should autoplay.
+   * @default false
+   * @example true
+   */
+  autoplay: boolean
+
+  /**
+   * Controls if the Twitch video should start muted.
+   * @default false
+   * @example true
+   */
+  muted: boolean
+
+  /**
+   * The time in the video where playback starts (format: 1h2m3s).
+   * Only works for video embeds, not for clips or channels.
+   * @default undefined
+   * @example '1h2m3s'
+   */
+  time?: string
+
+  /**
+   * The parent domain for the Twitch embed. Required for embed functionality.
+   * @default 'localhost'
+   * @example 'example.com'
+   */
+  parent: string
+
+  /**
+   * The height of the Twitch video.
+   * @default 480
+   * @example 720
+   */
+  height: number
+
+  /**
+   * The width of the Twitch video.
+   * @default 640
+   * @example 1280
+   */
+  width: number
+
+  /**
+   * The HTML attributes for a Twitch video node.
+   * @default {}
+   * @example { class: 'foo' }
+   */
+  HTMLAttributes: Record<string, any>
+
+  /**
+   * Controls if the Twitch node should be inline or not.
+   * @default false
+   * @example true
+   */
+  inline: boolean
+}
+
+/**
+ * The options for setting a Twitch video.
+ */
+type SetTwitchVideoOptions = {
+  src: string
+  width?: number
+  height?: number
+  autoplay?: boolean
+  muted?: boolean
+  time?: string
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    twitch: {
+      /**
+       * Insert a Twitch video
+       * @param options The Twitch video attributes
+       * @example editor.commands.setTwitchVideo({ src: 'https://www.twitch.tv/videos/1234567890' })
+       */
+      setTwitchVideo: (options: SetTwitchVideoOptions) => ReturnType
+    }
+  }
+}
+
+/**
+ * This extension adds support for Twitch videos.
+ * @see https://www.tiptap.dev/api/nodes/twitch
+ *
+ * @example
+ * ```ts
+ * import { useEditor, EditorContent } from '@tiptap/react'
+ * import { StarterKit } from '@tiptap/starter-kit'
+ * import { Twitch } from '@tiptap/extension-twitch'
+ *
+ * const editor = useEditor({
+ *   extensions: [
+ *     StarterKit,
+ *     Twitch.configure({
+ *       parent: 'example.com',
+ *       allowFullscreen: true,
+ *     }),
+ *   ],
+ *   content: '<p>Hello World!</p>',
+ * })
+ * ```
+ */
+export const Twitch = Node.create<TwitchOptions>({
+  name: 'twitch',
+
+  addOptions() {
+    return {
+      addPasteHandler: true,
+      allowFullscreen: true,
+      autoplay: false,
+      muted: false,
+      time: undefined,
+      parent: 'localhost',
+      height: 480,
+      width: 640,
+      HTMLAttributes: {},
+      inline: false,
+    }
+  },
+
+  inline() {
+    return this.options.inline
+  },
+
+  group() {
+    return this.options.inline ? 'inline' : 'block'
+  },
+
+  draggable: true,
+
+  addAttributes() {
+    return {
+      src: {
+        default: null,
+      },
+      width: {
+        default: this.options.width,
+      },
+      height: {
+        default: this.options.height,
+      },
+      autoplay: {
+        default: this.options.autoplay,
+      },
+      muted: {
+        default: this.options.muted,
+      },
+      time: {
+        default: this.options.time,
+      },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-twitch-video] iframe',
+      },
+    ]
+  },
+
+  addCommands() {
+    return {
+      setTwitchVideo:
+        (options: SetTwitchVideoOptions) =>
+        ({ commands }) => {
+          if (!isValidTwitchUrl(options.src)) {
+            return false
+          }
+
+          return commands.insertContent({
+            type: this.name,
+            attrs: options,
+          })
+        },
+    }
+  },
+
+  addPasteRules() {
+    if (!this.options.addPasteHandler) {
+      return []
+    }
+
+    return [
+      nodePasteRule({
+        find: TWITCH_REGEX_GLOBAL,
+        type: this.type,
+        getAttributes: match => {
+          return { src: match.input }
+        },
+      }),
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    const embedUrl = getEmbedUrlFromTwitchUrl({
+      url: HTMLAttributes.src,
+      allowFullscreen: this.options.allowFullscreen,
+      autoplay: HTMLAttributes.autoplay ?? this.options.autoplay,
+      muted: HTMLAttributes.muted ?? this.options.muted,
+      time: HTMLAttributes.time ?? this.options.time,
+      parent: this.options.parent,
+    })
+
+    if (!embedUrl) {
+      return ['div', 'Invalid Twitch URL']
+    }
+
+    HTMLAttributes.src = embedUrl
+
+    return [
+      'div',
+      { 'data-twitch-video': '' },
+      [
+        'iframe',
+        mergeAttributes(
+          this.options.HTMLAttributes,
+          {
+            width: this.options.width,
+            height: this.options.height,
+            allowfullscreen: this.options.allowFullscreen,
+            scrolling: 'no',
+            frameborder: '0',
+          },
+          HTMLAttributes,
+        ),
+      ],
+    ]
+  },
+
+  ...createAtomBlockMarkdownSpec({
+    nodeName: 'twitch',
+    allowedAttributes: ['src', 'width', 'height', 'autoplay', 'muted', 'time'],
+  }),
+})

package/src/utils.ts

@@ -0,0 +1,213 @@
+/**
+ * Regex patterns for matching Twitch URLs
+ * Matches:
+ * - https://twitch.tv/videos/1234567890
+ * - https://www.twitch.tv/videos/1234567890
+ * - https://twitch.tv/examplechannel/clip/ClipName-123
+ * - https://www.twitch.tv/examplechannel/clip/ClipName-123
+ * - https://clips.twitch.tv/ClipName
+ * - https://www.clips.twitch.tv/ClipName
+ * - https://twitch.tv/examplechannel (channel)
+ * - https://www.twitch.tv/examplechannel
+ */
+export const TWITCH_REGEX =
+  /^(https?:\/\/)?(www\.)?(twitch\.tv|clips\.twitch\.tv)\/(?:videos\/(\d+)|(\w+)\/clip\/([\w-]+)|([\w-]+)(?:\/)?)?(\?.*)?$/
+
+export const TWITCH_REGEX_GLOBAL =
+  /^(https?:\/\/)?(www\.)?(twitch\.tv|clips\.twitch\.tv)\/(?:videos\/(\d+)|(\w+)\/clip\/([\w-]+)|([\w-]+)(?:\/)?)?(\?.*)?$/g
+
+/**
+ * Validates if a URL is a valid Twitch video, clip or channel URL
+ *
+ * @param url - The URL to validate
+ * @returns true if the URL is a valid Twitch URL
+ *
+ * @example
+ * ```ts
+ * isValidTwitchUrl('https://www.twitch.tv/videos/1234567890') // true
+ * isValidTwitchUrl('https://www.twitch.tv/examplechannel/clip/ExampleClipName') // true
+ * isValidTwitchUrl('https://www.twitch.tv/examplechannel') // true
+ * isValidTwitchUrl('https://clips.twitch.tv/ExampleClipName') // true
+ * isValidTwitchUrl('invalid') // false
+ * ```
+ */
+export const isValidTwitchUrl = (url: string) => {
+  return url.match(TWITCH_REGEX)
+}
+
+export interface GetEmbedUrlOptions {
+  url: string
+  allowFullscreen?: boolean
+  autoplay?: boolean
+  muted?: boolean
+  time?: string
+  parent?: string
+}
+
+/**
+ * Extracts the video, clip or channel identifier from a Twitch URL
+ *
+ * @param url - The Twitch URL
+ * @returns Object containing type ('video', 'clip' or 'channel') and ID, or null if invalid
+ *
+ * @example
+ * ```ts
+ * getTwitchIdentifier('https://www.twitch.tv/videos/1234567890')
+ * // { type: 'video', id: '1234567890' }
+ *
+ * getTwitchIdentifier('https://www.twitch.tv/examplechannel/clip/ExampleClipName-ABC123')
+ * // { type: 'clip', id: 'ExampleClipName-ABC123' }
+ *
+ * getTwitchIdentifier('https://www.twitch.tv/examplechannel')
+ * // { type: 'channel', id: 'examplechannel' }
+ * ```
+ */
+export const getTwitchIdentifier = (url: string): { type: 'video' | 'clip' | 'channel'; id: string } | null => {
+  if (!isValidTwitchUrl(url)) {
+    return null
+  }
+
+  // Remove query parameters
+  const cleanUrl = url.split('?')[0]
+
+  // Handle clip URLs from clips.twitch.tv
+  if (cleanUrl.includes('clips.twitch.tv/')) {
+    const clipRegex = /clips\.twitch\.tv\/([\w-]+)/
+    const match = cleanUrl.match(clipRegex)
+    return match ? { type: 'clip', id: match[1] } : null
+  }
+
+  // Handle twitch.tv URLs
+  if (cleanUrl.includes('twitch.tv/')) {
+    // Check if it's a video URL (videos/ID)
+    const videoRegex = /twitch\.tv\/videos\/(\d+)/
+    const videoMatch = cleanUrl.match(videoRegex)
+    if (videoMatch) {
+      return { type: 'video', id: videoMatch[1] }
+    }
+
+    // Check if it's a clip URL (channel/clip/clipname)
+    const channelClipRegex = /twitch\.tv\/([\w-]+)\/clip\/([\w-]+)/
+    const clipMatch = cleanUrl.match(channelClipRegex)
+    if (clipMatch) {
+      return { type: 'clip', id: clipMatch[2] }
+    }
+
+    // Otherwise it's a channel URL
+    const channelRegex = /twitch\.tv\/([\w-]+)(?:\/)?$/
+    const channelMatch = cleanUrl.match(channelRegex)
+    if (channelMatch) {
+      return { type: 'channel', id: channelMatch[1] }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Generates an embed URL from a Twitch video, clip or channel URL with optional parameters
+ *
+ * @param options - The embed URL options
+ * @returns The embed URL or null if invalid
+ *
+ * @example
+ * ```ts
+ * getEmbedUrlFromTwitchUrl({
+ *   url: 'https://www.twitch.tv/videos/1234567890',
+ *   parent: 'example.com',
+ *   muted: true,
+ *   time: '1h2m3s'
+ * })
+ * // Returns: https://player.twitch.tv/?video=1234567890&parent=example.com&muted=true&time=1h2m3s
+ *
+ * getEmbedUrlFromTwitchUrl({
+ *   url: 'https://www.twitch.tv/examplechannel/clip/ExampleClipName-ABC123',
+ *   parent: 'example.com',
+ *   autoplay: true,
+ *   muted: true
+ * })
+ * // Returns: https://clips.twitch.tv/embed?clip=ExampleClipName-ABC123&parent=example.com&autoplay=true&muted=true
+ *
+ * getEmbedUrlFromTwitchUrl({
+ *   url: 'https://www.twitch.tv/examplechannel',
+ *   parent: 'example.com'
+ * })
+ * // Returns: https://player.twitch.tv/?channel=examplechannel&parent=example.com
+ * ```
+ */
+export const getEmbedUrlFromTwitchUrl = (options: GetEmbedUrlOptions): string | null => {
+  const { url, allowFullscreen = true, autoplay = false, muted = false, time, parent } = options
+
+  const identifier = getTwitchIdentifier(url)
+
+  if (!identifier) {
+    return null
+  }
+
+  const parentDomain = parent || 'localhost'
+
+  // Handle clip URLs
+  if (identifier.type === 'clip') {
+    const clipUrl = new URL('https://clips.twitch.tv/embed')
+    clipUrl.searchParams.set('clip', identifier.id)
+    clipUrl.searchParams.set('parent', parentDomain)
+
+    if (autoplay) {
+      clipUrl.searchParams.set('autoplay', 'true')
+    }
+
+    if (muted) {
+      clipUrl.searchParams.set('muted', 'true')
+    }
+
+    return clipUrl.toString()
+  }
+
+  // Handle video URLs
+  if (identifier.type === 'video') {
+    const videoUrl = new URL('https://player.twitch.tv/')
+    videoUrl.searchParams.set('video', identifier.id)
+    videoUrl.searchParams.set('parent', parentDomain)
+
+    if (allowFullscreen) {
+      videoUrl.searchParams.set('allowfullscreen', 'true')
+    }
+
+    if (autoplay) {
+      videoUrl.searchParams.set('autoplay', 'true')
+    }
+
+    if (muted) {
+      videoUrl.searchParams.set('muted', 'true')
+    }
+
+    if (time) {
+      videoUrl.searchParams.set('time', time)
+    }
+
+    return videoUrl.toString()
+  }
+
+  // Handle channel URLs
+  if (identifier.type === 'channel') {
+    const channelUrl = new URL('https://player.twitch.tv/')
+    channelUrl.searchParams.set('channel', identifier.id)
+    channelUrl.searchParams.set('parent', parentDomain)
+
+    if (allowFullscreen) {
+      channelUrl.searchParams.set('allowfullscreen', 'true')
+    }
+
+    if (autoplay) {
+      channelUrl.searchParams.set('autoplay', 'true')
+    }
+
+    if (muted) {
+      channelUrl.searchParams.set('muted', 'true')
+    }
+
+    return channelUrl.toString()
+  }
+
+  return null
+}