@meta-1/editor 0.0.28 → 1.0.0

package/src/hooks/use-menu-navigation.ts

@@ -0,0 +1,182 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { Editor } from "@tiptap/react";
+
+type Orientation = "horizontal" | "vertical" | "both";
+
+interface MenuNavigationOptions<T> {
+  /**
+   * The Tiptap editor instance, if using with a Tiptap editor.
+   */
+  editor?: Editor | null;
+  /**
+   * Reference to the container element for handling keyboard events.
+   */
+  containerRef?: React.RefObject<HTMLElement | null>;
+  /**
+   * Search query that affects the selected item.
+   */
+  query?: string;
+  /**
+   * Array of items to navigate through.
+   */
+  items: T[];
+  /**
+   * Callback fired when an item is selected.
+   */
+  onSelect?: (item: T) => void;
+  /**
+   * Callback fired when the menu should close.
+   */
+  onClose?: () => void;
+  /**
+   * The navigation orientation of the menu.
+   * @default "vertical"
+   */
+  orientation?: Orientation;
+  /**
+   * Whether to automatically select the first item when the menu opens.
+   * @default true
+   */
+  autoSelectFirstItem?: boolean;
+}
+
+/**
+ * Hook that implements keyboard navigation for dropdown menus and command palettes.
+ *
+ * Handles arrow keys, tab, home/end, enter for selection, and escape to close.
+ * Works with both Tiptap editors and regular DOM elements.
+ *
+ * @param options - Configuration options for the menu navigation
+ * @returns Object containing the selected index and a setter function
+ */
+export function useMenuNavigation<T>({
+  editor,
+  containerRef,
+  query,
+  items,
+  onSelect,
+  onClose,
+  orientation = "vertical",
+  autoSelectFirstItem = true,
+}: MenuNavigationOptions<T>) {
+  const [selectedIndex, setSelectedIndex] = useState<number>(autoSelectFirstItem ? 0 : -1);
+
+  useEffect(() => {
+    const handleKeyboardNavigation = (event: KeyboardEvent) => {
+      if (!items.length) return false;
+
+      const moveNext = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return 0;
+          return (currentIndex + 1) % items.length;
+        });
+
+      const movePrev = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return items.length - 1;
+          return (currentIndex - 1 + items.length) % items.length;
+        });
+
+      switch (event.key) {
+        case "ArrowUp": {
+          if (orientation === "horizontal") return false;
+          event.preventDefault();
+          movePrev();
+          return true;
+        }
+
+        case "ArrowDown": {
+          if (orientation === "horizontal") return false;
+          event.preventDefault();
+          moveNext();
+          return true;
+        }
+
+        case "ArrowLeft": {
+          if (orientation === "vertical") return false;
+          event.preventDefault();
+          movePrev();
+          return true;
+        }
+
+        case "ArrowRight": {
+          if (orientation === "vertical") return false;
+          event.preventDefault();
+          moveNext();
+          return true;
+        }
+
+        case "Tab": {
+          event.preventDefault();
+          if (event.shiftKey) {
+            movePrev();
+          } else {
+            moveNext();
+          }
+          return true;
+        }
+
+        case "Home": {
+          event.preventDefault();
+          setSelectedIndex(0);
+          return true;
+        }
+
+        case "End": {
+          event.preventDefault();
+          setSelectedIndex(items.length - 1);
+          return true;
+        }
+
+        case "Enter": {
+          if (event.isComposing) return false;
+          event.preventDefault();
+          if (selectedIndex !== -1 && items[selectedIndex]) {
+            onSelect?.(items[selectedIndex]);
+          }
+          return true;
+        }
+
+        case "Escape": {
+          event.preventDefault();
+          onClose?.();
+          return true;
+        }
+
+        default:
+          return false;
+      }
+    };
+
+    let targetElement: HTMLElement | null = null;
+
+    if (editor) {
+      targetElement = editor.view.dom;
+    } else if (containerRef?.current) {
+      targetElement = containerRef.current;
+    }
+
+    if (targetElement) {
+      targetElement.addEventListener("keydown", handleKeyboardNavigation, true);
+
+      return () => {
+        targetElement?.removeEventListener("keydown", handleKeyboardNavigation, true);
+      };
+    }
+
+    return undefined;
+  }, [editor, containerRef, items, selectedIndex, onSelect, onClose, orientation]);
+
+  useEffect(() => {
+    if (query) {
+      setSelectedIndex(autoSelectFirstItem ? 0 : -1);
+    }
+  }, [query, autoSelectFirstItem]);
+
+  return {
+    selectedIndex: items.length ? selectedIndex : undefined,
+    setSelectedIndex,
+  };
+}

package/src/hooks/use-on-click-outside.ts

@@ -0,0 +1,135 @@
+"use client";
+
+import type { RefObject } from "react";
+import { useEffect, useRef } from "react";
+
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";
+
+// MediaQueryList Event based useEventListener interface
+function useEventListener<K extends keyof MediaQueryListEventMap>(
+  eventName: K,
+  handler: (event: MediaQueryListEventMap[K]) => void,
+  element: RefObject<MediaQueryList>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// Window Event based useEventListener interface
+function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  element?: undefined,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// Element Event based useEventListener interface
+function useEventListener<
+  K extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  T extends Element = K extends keyof HTMLElementEventMap ? HTMLDivElement : SVGElement,
+>(
+  eventName: K,
+  handler: ((event: HTMLElementEventMap[K]) => void) | ((event: SVGElementEventMap[K]) => void),
+  element: RefObject<T>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+// Document Event based useEventListener interface
+function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  element: RefObject<Document>,
+  options?: boolean | AddEventListenerOptions,
+): void;
+
+/**
+ * Custom hook that attaches event listeners to DOM elements, the window, or media query lists.
+ * @template KW - The type of event for window events.
+ * @template KH - The type of event for HTML or SVG element events.
+ * @template KM - The type of event for media query list events.
+ * @template T - The type of the DOM element (default is `HTMLElement`).
+ * @param {KW | KH | KM} eventName - The name of the event to listen for.
+ * @param {(event: WindowEventMap[KW] | HTMLElementEventMap[KH] | SVGElementEventMap[KH] | MediaQueryListEventMap[KM] | Event) => void} handler - The event handler function.
+ * @param {RefObject<T>} [element] - The DOM element or media query list to attach the event listener to (optional).
+ * @param {boolean | AddEventListenerOptions} [options] - An options object that specifies characteristics about the event listener (optional).
+ */
+function useEventListener<
+  KW extends keyof WindowEventMap,
+  KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  KM extends keyof MediaQueryListEventMap,
+  T extends HTMLElement | SVGAElement | MediaQueryList = HTMLElement,
+>(
+  eventName: KW | KH | KM,
+  handler: (
+    event: WindowEventMap[KW] | HTMLElementEventMap[KH] | SVGElementEventMap[KH] | MediaQueryListEventMap[KM] | Event,
+  ) => void,
+  element?: RefObject<T>,
+  options?: boolean | AddEventListenerOptions,
+) {
+  // Create a ref that stores handler
+  const savedHandler = useRef(handler);
+
+  useIsomorphicLayoutEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    // Define the listening target
+    const targetElement: T | Window = element?.current ?? window;
+
+    if (!(targetElement && targetElement.addEventListener)) return;
+
+    // Create event listener that calls handler function stored in ref
+    const listener: typeof handler = (event) => {
+      savedHandler.current(event);
+    };
+
+    targetElement.addEventListener(eventName, listener, options);
+
+    // Remove event listener on cleanup
+    return () => {
+      targetElement.removeEventListener(eventName, listener, options);
+    };
+  }, [eventName, element, options]);
+}
+
+export { useEventListener };
+
+/** Supported event types. */
+type EventType = "mousedown" | "mouseup" | "touchstart" | "touchend" | "focusin" | "focusout";
+
+/**
+ * Custom hook that handles clicks outside a specified element.
+ * @template T - The type of the element's reference.
+ * @param {RefObject<T> | RefObject<T>[]} ref - The React ref object(s) representing the element(s) to watch for outside clicks.
+ * @param {(event: MouseEvent | TouchEvent | FocusEvent) => void} handler - The callback function to be executed when a click outside the element occurs.
+ * @param {EventType} [eventType] - The mouse event type to listen for (optional, default is 'mousedown').
+ * @param {?AddEventListenerOptions} [eventListenerOptions] - The options object to be passed to the `addEventListener` method (optional).
+ * @returns {void}
+ */
+export function useOnClickOutside<T extends HTMLElement | null = HTMLElement>(
+  ref: RefObject<T> | RefObject<T>[],
+  handler: (event: MouseEvent | TouchEvent | FocusEvent) => void,
+  eventType: EventType = "mousedown",
+  eventListenerOptions: AddEventListenerOptions = {},
+): void {
+  useEventListener(
+    eventType,
+    (event) => {
+      const target = event.target as Node;
+
+      // Do nothing if the target is not connected element with document
+      if (!target || !target.isConnected) {
+        return;
+      }
+
+      const isOutside = Array.isArray(ref)
+        ? ref.filter((r) => Boolean(r.current)).every((r) => r.current && !r.current.contains(target))
+        : ref.current && !ref.current.contains(target);
+
+      if (isOutside) {
+        handler(event);
+      }
+    },
+    undefined,
+    eventListenerOptions,
+  );
+}

package/src/hooks/use-scrolling.ts

@@ -0,0 +1,75 @@
+import type { RefObject } from "react"
+import { useEffect, useState } from "react"
+
+type ScrollTarget = RefObject<HTMLElement> | Window | null | undefined
+type EventTargetWithScroll = Window | HTMLElement | Document
+
+interface UseScrollingOptions {
+  debounce?: number
+  fallbackToDocument?: boolean
+}
+
+export function useScrolling(
+  target?: ScrollTarget,
+  options: UseScrollingOptions = {}
+): boolean {
+  const { debounce = 150, fallbackToDocument = true } = options
+  const [isScrolling, setIsScrolling] = useState(false)
+
+  useEffect(() => {
+    // Resolve element or window
+    const element: EventTargetWithScroll =
+      target && typeof Window !== "undefined" && target instanceof Window
+        ? target
+        : ((target as RefObject<HTMLElement>)?.current ?? window)
+
+    // Mobile: fallback to document when using window
+    const eventTarget: EventTargetWithScroll =
+      fallbackToDocument &&
+      element === window &&
+      typeof document !== "undefined"
+        ? document
+        : element
+
+    const on = (
+      el: EventTargetWithScroll,
+      event: string,
+      handler: EventListener
+    ) => el.addEventListener(event, handler, true)
+
+    const off = (
+      el: EventTargetWithScroll,
+      event: string,
+      handler: EventListener
+    ) => el.removeEventListener(event, handler)
+
+    let timeout: ReturnType<typeof setTimeout>
+    const supportsScrollEnd = element === window && "onscrollend" in window
+
+    const handleScroll: EventListener = () => {
+      if (!isScrolling) setIsScrolling(true)
+
+      if (!supportsScrollEnd) {
+        clearTimeout(timeout)
+        timeout = setTimeout(() => setIsScrolling(false), debounce)
+      }
+    }
+
+    const handleScrollEnd: EventListener = () => setIsScrolling(false)
+
+    on(eventTarget, "scroll", handleScroll)
+    if (supportsScrollEnd) {
+      on(eventTarget, "scrollend", handleScrollEnd)
+    }
+
+    return () => {
+      off(eventTarget, "scroll", handleScroll)
+      if (supportsScrollEnd) {
+        off(eventTarget, "scrollend", handleScrollEnd)
+      }
+      clearTimeout(timeout)
+    }
+  }, [target, debounce, fallbackToDocument, isScrolling])
+
+  return isScrolling
+}

package/src/hooks/use-throttled-callback.ts

@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import throttle from "lodash.throttle";
+
+import { useUnmount } from "./use-unmount";
+
+interface ThrottleSettings {
+  leading?: boolean | undefined;
+  trailing?: boolean | undefined;
+}
+
+const defaultOptions: ThrottleSettings = {
+  leading: false,
+  trailing: true,
+};
+
+/**
+ * A hook that returns a throttled callback function.
+ *
+ * @param fn The function to throttle
+ * @param wait The time in ms to wait before calling the function
+ * @param dependencies The dependencies to watch for changes
+ * @param options The throttle options
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useThrottledCallback<T extends (...args: any[]) => any>(
+  fn: T,
+  wait = 250,
+  dependencies: React.DependencyList = [],
+  options: ThrottleSettings = defaultOptions,
+): {
+  (this: ThisParameterType<T>, ...args: Parameters<T>): ReturnType<T>;
+  cancel: () => void;
+  flush: () => void;
+} {
+  const handler = useMemo(
+    () => throttle<T>(fn, wait, options),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    dependencies,
+  );
+
+  useUnmount(() => {
+    handler.cancel();
+  });
+
+  return handler;
+}
+
+export default useThrottledCallback;

package/src/hooks/use-tiptap-editor.ts

@@ -0,0 +1,49 @@
+"use client"
+
+import type { Editor } from "@tiptap/react"
+import { useCurrentEditor, useEditorState } from "@tiptap/react"
+import { useMemo } from "react"
+
+/**
+ * Hook that provides access to a Tiptap editor instance.
+ *
+ * Accepts an optional editor instance directly, or falls back to retrieving
+ * the editor from the Tiptap context if available. This allows components
+ * to work both when given an editor directly and when used within a Tiptap
+ * editor context.
+ *
+ * @param providedEditor - Optional editor instance to use instead of the context editor
+ * @returns The provided editor or the editor from context, whichever is available
+ */
+export function useTiptapEditor(providedEditor?: Editor | null): {
+  editor: Editor | null
+  editorState?: Editor["state"]
+  canCommand?: Editor["can"]
+} {
+  const { editor: coreEditor } = useCurrentEditor()
+  const mainEditor = useMemo(
+    () => providedEditor || coreEditor,
+    [providedEditor, coreEditor]
+  )
+
+  const editorState = useEditorState({
+    editor: mainEditor,
+    selector(context) {
+      if (!context.editor) {
+        return {
+          editor: null,
+          editorState: undefined,
+          canCommand: undefined,
+        }
+      }
+
+      return {
+        editor: context.editor,
+        editorState: context.editor.state,
+        canCommand: context.editor.can,
+      }
+    },
+  })
+
+  return editorState || { editor: null }
+}

package/src/hooks/use-ui-editor-state.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import type { Editor } from "@tiptap/react";
+import { useEditorState } from "@tiptap/react";
+
+import { defaultUiState, type UiState } from "../components/tiptap-extension/ui-state-extension";
+
+export function useUiEditorState(editor: Editor | null): UiState {
+  return (
+    useEditorState({
+      editor,
+      selector: ({ editor }) => {
+        if (!editor) return defaultUiState;
+
+        const state = editor.storage.uiState;
+        if (!state) {
+          console.warn(
+            "Editor storage uiState is not initialized. Ensure you have the uiState extension added to your editor.",
+          );
+          return defaultUiState;
+        }
+
+        return { ...defaultUiState, ...state };
+      },
+    }) ?? defaultUiState
+  );
+}
+
+export default useUiEditorState;

package/src/hooks/use-unmount.ts

@@ -0,0 +1,21 @@
+import { useRef, useEffect } from "react"
+
+/**
+ * Hook that executes a callback when the component unmounts.
+ *
+ * @param callback Function to be called on component unmount
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const useUnmount = (callback: (...args: Array<any>) => any) => {
+  const ref = useRef(callback)
+  ref.current = callback
+
+  useEffect(
+    () => () => {
+      ref.current()
+    },
+    []
+  )
+}
+
+export default useUnmount

package/src/hooks/use-window-size.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { useThrottledCallback } from "./use-throttled-callback";
+
+export interface WindowSizeState {
+  /**
+   * The width of the window's visual viewport in pixels.
+   */
+  width: number;
+  /**
+   * The height of the window's visual viewport in pixels.
+   */
+  height: number;
+  /**
+   * The distance from the top of the visual viewport to the top of the layout viewport.
+   * Particularly useful for handling mobile keyboard appearance.
+   */
+  offsetTop: number;
+  /**
+   * The distance from the left of the visual viewport to the left of the layout viewport.
+   */
+  offsetLeft: number;
+  /**
+   * The scale factor of the visual viewport.
+   * This is useful for scaling elements based on the current zoom level.
+   */
+  scale: number;
+}
+
+/**
+ * Hook that tracks the window's visual viewport dimensions, position, and provides
+ * a CSS transform for positioning elements.
+ *
+ * Uses the Visual Viewport API to get accurate measurements, especially important
+ * for mobile devices where virtual keyboards can change the visible area.
+ * Only updates state when values actually change to optimize performance.
+ *
+ * @returns An object containing viewport properties and a CSS transform string
+ */
+export function useWindowSize(): WindowSizeState {
+  const [windowSize, setWindowSize] = useState<WindowSizeState>({
+    width: 0,
+    height: 0,
+    offsetTop: 0,
+    offsetLeft: 0,
+    scale: 0,
+  });
+
+  const handleViewportChange = useThrottledCallback(() => {
+    if (typeof window === "undefined") return;
+
+    const vp = window.visualViewport;
+    if (!vp) return;
+
+    const { width = 0, height = 0, offsetTop = 0, offsetLeft = 0, scale = 0 } = vp;
+
+    setWindowSize((prevState) => {
+      if (
+        width === prevState.width &&
+        height === prevState.height &&
+        offsetTop === prevState.offsetTop &&
+        offsetLeft === prevState.offsetLeft &&
+        scale === prevState.scale
+      ) {
+        return prevState;
+      }
+
+      return { width, height, offsetTop, offsetLeft, scale };
+    });
+  }, 200);
+
+  useEffect(() => {
+    const visualViewport = window.visualViewport;
+    if (!visualViewport) return;
+
+    visualViewport.addEventListener("resize", handleViewportChange);
+
+    handleViewportChange();
+
+    return () => {
+      visualViewport.removeEventListener("resize", handleViewportChange);
+    };
+  }, [handleViewportChange]);
+
+  return windowSize;
+}

package/src/index.ts

@@ -1,7 +1,4 @@
-export type { EditorEvents } from "@tiptap/core";
-
-export type { EditorProps, EditorRef } from "./editor";
-export { Editor } from "./editor";
-export * from "./editor/hooks";
-export type { ContentViewerProps } from "./editor/viewer";
-export { ContentViewer } from "./editor/viewer";
+export * from "./content";
+export * from "./editor";
+export * from "./editor/collaboration";
+export * from "./hooks/use-editor";