@meta-1/editor 0.0.28 → 1.0.0

package/src/components/tiptap-ui/image-align-button/use-image-align.ts

@@ -0,0 +1,295 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { useHotkeys } from "react-hotkeys-hook"
+import { type Editor } from "@tiptap/react"
+import { NodeSelection } from "@tiptap/pm/state"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor"
+import { useIsBreakpoint } from "../../../hooks/use-is-breakpoint"
+
+// --- Lib ---
+import { isExtensionAvailable } from "../../../lib/tiptap-utils"
+
+// --- Icons ---
+import { AlignCenterVerticalIcon } from "../../tiptap-icons/align-center-vertical-icon"
+import { AlignEndVerticalIcon } from "../../tiptap-icons/align-end-vertical-icon"
+import { AlignStartVerticalIcon } from "../../tiptap-icons/align-start-vertical-icon"
+
+export type ImageAlign = "left" | "center" | "right"
+
+/**
+ * Configuration for the image align functionality
+ */
+export interface UseImageAlignConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * The image alignment to apply.
+   */
+  align: ImageAlign
+  /**
+   * The name of the image extension to target.
+   * @default "image"
+   */
+  extensionName?: string
+  /**
+   * The attribute name used for alignment.
+   * @default "data-align"
+   */
+  attributeName?: string
+  /**
+   * Whether the button should hide when alignment is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful alignment change.
+   */
+  onAligned?: () => void
+}
+
+export const IMAGE_ALIGN_SHORTCUT_KEYS: Record<ImageAlign, string> = {
+  left: "alt+shift+l",
+  center: "alt+shift+e",
+  right: "alt+shift+r",
+}
+
+export const imageAlignIcons = {
+  left: AlignStartVerticalIcon,
+  center: AlignCenterVerticalIcon,
+  right: AlignEndVerticalIcon,
+}
+
+export const imageAlignLabels: Record<ImageAlign, string> = {
+  left: "Image align left",
+  center: "Image align center",
+  right: "Image align right",
+}
+
+/**
+ * Checks if image alignment can be performed in the current editor state
+ */
+export function canSetImageAlign(
+  editor: Editor | null,
+  align: ImageAlign,
+  extensionName: string = "image",
+  attributeName: string = "data-align"
+): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, [extensionName])) return false
+
+  return editor
+    .can()
+    .updateAttributes(extensionName, { [attributeName]: align })
+}
+
+/**
+ * Checks if the image alignment is currently active
+ */
+export function isImageAlignActive(
+  editor: Editor | null,
+  align: ImageAlign,
+  extensionName: string = "image",
+  attributeName: string = "data-align"
+): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, [extensionName])) return false
+
+  const attributes = editor.getAttributes(extensionName)
+  const currentAlign = attributes[attributeName] || "left"
+  return currentAlign === align
+}
+
+/**
+ * Sets image alignment in the editor
+ */
+export function setImageAlign(
+  editor: Editor | null,
+  align: ImageAlign,
+  extensionName: string = "image",
+  attributeName: string = "data-align"
+): boolean {
+  if (!editor?.isEditable) {
+    return false
+  }
+
+  if (!isExtensionAvailable(editor, [extensionName])) {
+    return false
+  }
+
+  if (!canSetImageAlign(editor, align, extensionName, attributeName)) {
+    return false
+  }
+
+  try {
+    const { selection } = editor.state
+    const isNodeSelection = selection instanceof NodeSelection
+    const selectionPosition = isNodeSelection
+      ? selection.from
+      : selection.$anchor.pos
+
+    const alignmentUpdated = editor
+      .chain()
+      .focus()
+      .updateAttributes(extensionName, { [attributeName]: align })
+      .run()
+
+    // Restore node selection if it was originally selected
+    // This is the temporary solution as image-node-extension.ts contain content: "inline*"
+    if (alignmentUpdated && isNodeSelection) {
+      editor.commands.setNodeSelection(selectionPosition)
+    }
+
+    return alignmentUpdated
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Determines if the image align button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+  align: ImageAlign
+  extensionName?: string
+  attributeName?: string
+}): boolean {
+  const {
+    editor,
+    hideWhenUnavailable,
+    align,
+    extensionName = "image",
+    attributeName = "data-align",
+  } = props
+
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, [extensionName])) return false
+
+  if (hideWhenUnavailable) {
+    return canSetImageAlign(editor, align, extensionName, attributeName)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides image align functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage with default "image" extension
+ * function MySimpleImageAlignButton() {
+ *   const { isVisible, handleImageAlign } = useImageAlign({ align: "center" })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleImageAlign}>Align Center</button>
+ * }
+ *
+ * // Advanced usage with custom extension name
+ * function MyAdvancedImageAlignButton() {
+ *   const { isVisible, handleImageAlign, label, isActive } = useImageAlign({
+ *     editor: myEditor,
+ *     align: "right",
+ *     extensionName: "myCustomImage", // Use your custom extension name
+ *     hideWhenUnavailable: true,
+ *     onAligned: () => console.log('Image aligned!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleImageAlign}
+ *       aria-pressed={isActive}
+ *       aria-label={label}
+ *     >
+ *       Align Right
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useImageAlign(config: UseImageAlignConfig) {
+  const {
+    editor: providedEditor,
+    align,
+    extensionName = "image",
+    attributeName = "data-align",
+    hideWhenUnavailable = false,
+    onAligned,
+  } = config
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const isMobile = useIsBreakpoint()
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canAlign = canSetImageAlign(editor, align, extensionName, attributeName)
+  const isActive = isImageAlignActive(
+    editor,
+    align,
+    extensionName,
+    attributeName
+  )
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(
+        shouldShowButton({
+          editor,
+          align,
+          hideWhenUnavailable,
+          extensionName,
+          attributeName,
+        })
+      )
+    }
+
+    handleSelectionUpdate()
+
+    editor.on("selectionUpdate", handleSelectionUpdate)
+    return () => {
+      editor.off("selectionUpdate", handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable, align, extensionName, attributeName])
+
+  const handleImageAlign = useCallback(() => {
+    if (!editor) return false
+
+    const success = setImageAlign(editor, align, extensionName, attributeName)
+    if (success) {
+      onAligned?.()
+    }
+    return success
+  }, [editor, align, extensionName, attributeName, onAligned])
+
+  useHotkeys(
+    IMAGE_ALIGN_SHORTCUT_KEYS[align],
+    (event) => {
+      event.preventDefault()
+      handleImageAlign()
+    },
+    {
+      enabled: isVisible && canAlign,
+      enableOnContentEditable: !isMobile,
+      enableOnFormTags: true,
+    }
+  )
+
+  return {
+    isVisible,
+    isActive,
+    handleImageAlign,
+    canAlign,
+    label: imageAlignLabels[align],
+    shortcutKeys: IMAGE_ALIGN_SHORTCUT_KEYS[align],
+    Icon: imageAlignIcons[align],
+  }
+}

package/src/components/tiptap-ui/image-caption-button/image-caption-button.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import * as React from "react";
+import { useTranslation } from "react-i18next";
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor";
+// --- UI Primitives ---
+import type { ButtonProps } from "../../tiptap-ui-primitive/button";
+import { Button } from "../../tiptap-ui-primitive/button";
+// --- Tiptap UI ---
+import type { UseImageCaptionConfig } from "./";
+import { useImageCaption } from "./";
+
+export interface ImageCaptionButtonProps extends Omit<ButtonProps, "type">, UseImageCaptionConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string;
+}
+
+/**
+ * Button component for toggling image captions in a Tiptap editor.
+ * Only appears when an image is selected in the editor.
+ *
+ * For custom button implementations, use the `useImageCaption` hook instead.
+ */
+export const ImageCaptionButton = React.forwardRef<HTMLButtonElement, ImageCaptionButtonProps>(
+  ({ editor: providedEditor, text, hideWhenUnavailable = false, onSet, onClick, children, ...buttonProps }, ref) => {
+    const { editor } = useTiptapEditor(providedEditor);
+    const { t } = useTranslation();
+    const { isVisible, isActive, canToggle, handleToggleCaption, label, Icon } = useImageCaption({
+      editor,
+      hideWhenUnavailable,
+      onSet,
+    });
+
+    const handleClick = React.useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        handleToggleCaption();
+      },
+      [handleToggleCaption, onClick],
+    );
+
+    if (!isVisible) {
+      return null;
+    }
+
+    return (
+      <Button
+        aria-label={label}
+        data-active-state={isActive ? "on" : "off"}
+        data-disabled={!canToggle}
+        data-style="ghost"
+        disabled={!canToggle}
+        onClick={handleClick}
+        role="button"
+        tabIndex={-1}
+        tooltip={t(label)}
+        type="button"
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+          </>
+        )}
+      </Button>
+    );
+  },
+);
+
+ImageCaptionButton.displayName = "ImageCaptionButton";

package/src/components/tiptap-ui/image-caption-button/index.tsx

@@ -0,0 +1,2 @@
+export * from "./image-caption-button"
+export * from "./use-image-caption"

package/src/components/tiptap-ui/image-caption-button/use-image-caption.ts

@@ -0,0 +1,212 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { type Editor } from "@tiptap/react"
+import { NodeSelection } from "@tiptap/pm/state"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor"
+
+// --- Lib ---
+import {
+  isExtensionAvailable,
+  isNodeTypeSelected,
+} from "../../../lib/tiptap-utils"
+
+// --- Icons ---
+import { ImageCaptionIcon } from "../../tiptap-icons/image-caption-icon"
+
+/**
+ * Configuration for the image caption functionality
+ */
+export interface UseImageCaptionConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Whether the button should hide when caption toggle is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful caption set.
+   */
+  onSet?: () => void
+}
+
+/**
+ * Checks if image caption can be toggled in the current editor state
+ */
+export function canToggleImageCaption(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, ["image"])) return false
+
+  return isNodeTypeSelected(editor, ["image"])
+}
+
+/**
+ * Checks if the currently selected image has caption enabled
+ */
+export function isImageCaptionActive(editor: Editor | null): boolean {
+  if (!editor) return false
+
+  try {
+    const { selection } = editor.state
+    const isImageSelected =
+      selection instanceof NodeSelection && selection.node.type.name === "image"
+
+    if (!isImageSelected) {
+      return false
+    }
+
+    const imageNode = (selection as NodeSelection).node
+    return imageNode.attrs.showCaption === true || imageNode.content.size > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Toggles the image caption in the editor
+ */
+export function setImageCaption(editor: Editor | null): boolean {
+  if (!editor?.isEditable || !canToggleImageCaption(editor)) {
+    return false
+  }
+
+  try {
+    const { selection } = editor.state
+    const isImageSelected =
+      selection instanceof NodeSelection && selection.node.type.name === "image"
+
+    if (!isImageSelected) {
+      return false
+    }
+
+    const captionEnabled = editor
+      .chain()
+      .focus()
+      .updateAttributes("image", { showCaption: true })
+      .run()
+
+    if (!captionEnabled) {
+      return false
+    }
+
+    const imagePosition = selection.from
+    editor
+      .chain()
+      .focus(imagePosition + 1)
+      .selectTextblockEnd()
+      .run()
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Determines if the image caption button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+}): boolean {
+  const { editor, hideWhenUnavailable } = props
+
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, ["image"])) return false
+
+  if (hideWhenUnavailable) {
+    return canToggleImageCaption(editor)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides image caption functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MyImageCaptionButton() {
+ *   const { isVisible, handleToggleCaption } = useImageCaption()
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleToggleCaption}>Toggle Caption</button>
+ * }
+ *
+ * // Advanced usage
+ * function MyAdvancedImageCaptionButton() {
+ *   const { isVisible, handleToggleCaption, label, canToggle } = useImageCaption({
+ *     editor: myEditor,
+ *     hideWhenUnavailable: true,
+ *     onSet: () => console.log('Caption set!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleToggleCaption}
+ *       disabled={!canToggle}
+ *       aria-label={label}
+ *     >
+ *       Toggle Caption
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useImageCaption(config?: UseImageCaptionConfig) {
+  const {
+    editor: providedEditor,
+    hideWhenUnavailable = false,
+    onSet,
+  } = config || {}
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const [isActive, setIsActive] = useState<boolean>(false)
+  const canToggle = canToggleImageCaption(editor)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, hideWhenUnavailable }))
+      setIsActive(isImageCaptionActive(editor))
+    }
+
+    handleSelectionUpdate()
+
+    editor.on("selectionUpdate", handleSelectionUpdate)
+
+    return () => {
+      editor.off("selectionUpdate", handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable])
+
+  const handleToggleCaption = useCallback(() => {
+    if (!editor) return false
+
+    const success = setImageCaption(editor)
+    if (success) {
+      onSet?.()
+    }
+    return success
+  }, [editor, onSet])
+
+  return {
+    isVisible,
+    isActive,
+    canToggle,
+    handleToggleCaption,
+    label: "Caption",
+    Icon: ImageCaptionIcon,
+  }
+}

package/src/components/tiptap-ui/image-download-button/image-download-button.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { forwardRef, useCallback } from "react";
+import { useTranslation } from "react-i18next";
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor";
+// --- Lib ---
+import { parseShortcutKeys } from "../../../lib/tiptap-utils";
+import { Badge } from "../../tiptap-ui-primitive/badge";
+// --- UI Primitives ---
+import type { ButtonProps } from "../../tiptap-ui-primitive/button";
+import { Button } from "../../tiptap-ui-primitive/button";
+// --- Tiptap UI ---
+import type { UseImageDownloadConfig } from "./";
+import { IMAGE_DOWNLOAD_SHORTCUT_KEY, useImageDownload } from "./";
+
+export interface ImageDownloadButtonProps extends Omit<ButtonProps, "type">, UseImageDownloadConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string;
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean;
+}
+
+export function ImageDownloadShortcutBadge({ shortcutKeys = IMAGE_DOWNLOAD_SHORTCUT_KEY }: { shortcutKeys?: string }) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>;
+}
+
+/**
+ * Button component for downloading images from a Tiptap editor.
+ * Only appears when an image is selected in the editor.
+ *
+ * For custom button implementations, use the `useImageDownload` hook instead.
+ */
+export const ImageDownloadButton = forwardRef<HTMLButtonElement, ImageDownloadButtonProps>(
+  (
+    {
+      editor: providedEditor,
+      text,
+      hideWhenUnavailable = false,
+      onDownloaded,
+      resolveFileUrl,
+      showShortcut = false,
+      onClick,
+      children,
+      ...buttonProps
+    },
+    ref,
+  ) => {
+    const { t } = useTranslation();
+    const { editor } = useTiptapEditor(providedEditor);
+    const { isVisible, canDownload, handleDownload, label, shortcutKeys, Icon } = useImageDownload({
+      editor,
+      hideWhenUnavailable,
+      onDownloaded,
+      resolveFileUrl,
+    });
+
+    const handleClick = useCallback(
+      async (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        await handleDownload();
+      },
+      [handleDownload, onClick],
+    );
+
+    if (!isVisible) {
+      return null;
+    }
+
+    return (
+      <Button
+        aria-label={label}
+        data-active-state="off"
+        data-disabled={!canDownload}
+        data-style="ghost"
+        disabled={!canDownload}
+        onClick={handleClick}
+        role="button"
+        tabIndex={-1}
+        tooltip={t(label)}
+        type="button"
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && <ImageDownloadShortcutBadge shortcutKeys={shortcutKeys} />}
+          </>
+        )}
+      </Button>
+    );
+  },
+);
+
+ImageDownloadButton.displayName = "ImageDownloadButton";

package/src/components/tiptap-ui/image-download-button/index.tsx

@@ -0,0 +1,2 @@
+export * from "./image-download-button"
+export * from "./use-image-download"