@meta-1/editor 0.0.28 → 1.0.0

package/src/hooks/use-editor.ts

@@ -0,0 +1,237 @@
+import { useCallback, useEffect, useRef } from "react";
+import { Highlight } from "@tiptap/extension-highlight";
+import { TaskItem, TaskList } from "@tiptap/extension-list";
+import { Mathematics } from "@tiptap/extension-mathematics";
+import { Mention } from "@tiptap/extension-mention";
+import { Subscript } from "@tiptap/extension-subscript";
+import { Superscript } from "@tiptap/extension-superscript";
+import { TextAlign } from "@tiptap/extension-text-align";
+import { Color, TextStyle } from "@tiptap/extension-text-style";
+import { Typography } from "@tiptap/extension-typography";
+import { UniqueID } from "@tiptap/extension-unique-id";
+import { Placeholder, Selection } from "@tiptap/extensions";
+import { Markdown } from "@tiptap/markdown";
+import { Editor, Extensions, useEditor } from "@tiptap/react";
+import { StarterKit } from "@tiptap/starter-kit";
+
+import { ListNormalizationExtension } from "../components/tiptap-extension/list-normalization-extension";
+import { NodeAlignment } from "../components/tiptap-extension/node-alignment-extension";
+import { NodeBackground } from "../components/tiptap-extension/node-background-extension";
+import { UiState } from "../components/tiptap-extension/ui-state-extension";
+import { HorizontalRule } from "../components/tiptap-node/horizontal-rule-node/horizontal-rule-node-extension";
+import { Image } from "../components/tiptap-node/image-node/image-node-extension";
+import type { UploadFunction } from "../components/tiptap-node/image-upload-node/image-upload-node-extension";
+import { ImageUploadNode } from "../components/tiptap-node/image-upload-node/image-upload-node-extension";
+import { TableHandleExtension } from "../components/tiptap-node/table-node/extensions/table-handle";
+import { TableKit } from "../components/tiptap-node/table-node/extensions/table-node-extension";
+import { handleImageUpload, MAX_FILE_SIZE } from "../lib/tiptap-utils";
+
+export type Meta1EditorValue = string | Record<string, unknown>;
+
+export interface ImageUploadOptions {
+  upload?: UploadFunction;
+  accept?: string;
+  maxSize?: number;
+  limit?: number;
+  onError?: (error: Error) => void;
+  onSuccess?: (url: string) => void;
+}
+
+export type ContentType = "html" | "json" | "markdown";
+
+export type Meta1EditorOptions = {
+  extensions?: Extensions;
+  className?: string;
+  placeholder?: string;
+  contentType?: ContentType;
+  editable?: boolean;
+  imageUpload?: ImageUploadOptions;
+};
+
+/**
+ * Editor instance that can be passed to Meta1Editor component
+ */
+export interface Meta1EditorInstance {
+  /** Internal: set the actual editor reference */
+  _setEditor?: (editor: Editor | null) => void;
+  /** Internal: set contentType for value conversion */
+  _contentType?: ContentType;
+  /** Get the underlying tiptap Editor instance */
+  getEditor: () => Editor | null;
+  /** Get current content as JSON */
+  getJSON: () => Record<string, unknown> | null;
+  /** Get current content as HTML */
+  getHTML: () => string | null;
+  /** Get current content as Markdown */
+  getMarkdown: () => string | null;
+  /** Focus the editor */
+  focus: () => void;
+  /** Check if editor is empty */
+  isEmpty: () => boolean;
+}
+
+const getValueFromEditor = (editor: Editor, contentType: ContentType): Meta1EditorValue => {
+  switch (contentType) {
+    case "json":
+      return editor.getJSON();
+    case "html":
+      return editor.getHTML();
+    case "markdown":
+      return editor.getMarkdown();
+    default:
+      return JSON.stringify(editor.getJSON());
+  }
+};
+
+/**
+ * Hook to create a Meta1Editor instance reference.
+ * Similar to Form.useForm(), this creates a stable reference that can be passed to Meta1Editor.
+ *
+ * @example
+ * const editor = Meta1Editor.useEditor();
+ *
+ * // Access editor methods
+ * const json = editor.getJSON();
+ * editor.focus();
+ *
+ * return <Meta1Editor editor={editor} />;
+ */
+export const useEditorInstance = (): Meta1EditorInstance => {
+  const editorRef = useRef<Editor | null>(null);
+  const instanceRef = useRef<Meta1EditorInstance | null>(null);
+
+  const _setEditor = useCallback((editor: Editor | null) => {
+    editorRef.current = editor;
+  }, []);
+
+  if (!instanceRef.current) {
+    instanceRef.current = {
+      _setEditor,
+      _contentType: "json",
+      getEditor: () => editorRef.current,
+      getJSON: () => editorRef.current?.getJSON() ?? null,
+      getHTML: () => editorRef.current?.getHTML() ?? null,
+      getMarkdown: () => editorRef.current?.getMarkdown() ?? null,
+      focus: () => editorRef.current?.commands.focus(),
+      isEmpty: () => editorRef.current?.isEmpty ?? true,
+    };
+  }
+
+  return instanceRef.current;
+};
+
+export type UseMeta1EditorProps = Meta1EditorOptions & {
+  value?: Meta1EditorValue;
+  onChange?: (content: Meta1EditorValue) => void;
+};
+
+/**
+ * Internal hook that creates the actual tiptap editor.
+ * Used internally by Meta1Editor component.
+ */
+export const useMeta1Editor = (props: UseMeta1EditorProps) => {
+  const {
+    extensions,
+    className,
+    placeholder,
+    value,
+    onChange,
+    contentType = "json",
+    editable = true,
+    imageUpload,
+  } = props;
+  const isUpdatingFromPropsRef = useRef(false);
+
+  const editor = useEditor({
+    content: value,
+    contentType: contentType,
+    editable,
+    onUpdate: ({ editor }) => {
+      if (!isUpdatingFromPropsRef.current) {
+        onChange?.(getValueFromEditor(editor, contentType));
+      }
+    },
+    editorProps: {
+      attributes: {
+        class: `gap-xl flex flex-col ${className || ""}`,
+      },
+    },
+    extensions: [
+      StarterKit.configure({
+        horizontalRule: false,
+        dropcursor: {
+          width: 2,
+        },
+        link: { openOnClick: false },
+      }),
+      Markdown,
+      HorizontalRule,
+      TextAlign.configure({ types: ["heading", "paragraph"] }),
+      Placeholder.configure({
+        placeholder,
+        emptyNodeClass: "is-empty with-slash",
+      }),
+      Mention,
+      TableKit.configure({
+        table: {
+          resizable: true,
+          cellMinWidth: 120,
+        },
+      }),
+      NodeBackground,
+      NodeAlignment,
+      TextStyle,
+      Mathematics,
+      Superscript,
+      Subscript,
+      Color,
+      TaskList,
+      TaskItem.configure({ nested: true }),
+      Highlight.configure({ multicolor: true }),
+      Selection,
+      Image,
+      TableHandleExtension,
+      ListNormalizationExtension,
+      ImageUploadNode.configure({
+        accept: imageUpload?.accept ?? "image/*",
+        maxSize: imageUpload?.maxSize ?? MAX_FILE_SIZE,
+        limit: imageUpload?.limit ?? 3,
+        upload: imageUpload?.upload ?? handleImageUpload,
+        onError: imageUpload?.onError ?? ((error) => console.error("Upload failed:", error)),
+        onSuccess: imageUpload?.onSuccess,
+      }),
+      UniqueID.configure({
+        types: ["table", "paragraph", "bulletList", "orderedList", "taskList", "heading", "blockquote", "codeBlock"],
+      }),
+      Typography,
+      UiState,
+      ...(extensions || []),
+    ],
+    immediatelyRender: false,
+  });
+
+  // Sync value from props to editor
+  useEffect(() => {
+    if (!editor || value === undefined) {
+      return;
+    }
+
+    const currentContent = getValueFromEditor(editor, contentType);
+    const isContentEqual =
+      typeof value === "string" && typeof currentContent === "string"
+        ? value === currentContent
+        : JSON.stringify(value) === JSON.stringify(currentContent);
+
+    if (!isContentEqual) {
+      queueMicrotask(() => {
+        isUpdatingFromPropsRef.current = true;
+        editor.commands.setContent(value);
+        requestAnimationFrame(() => {
+          isUpdatingFromPropsRef.current = false;
+        });
+      });
+    }
+  }, [editor, value, contentType]);
+
+  return editor;
+};

package/src/hooks/use-element-rect.ts

@@ -0,0 +1,165 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+import { useThrottledCallback } from "./use-throttled-callback";
+
+export type RectState = Omit<DOMRect, "toJSON">;
+
+export interface ElementRectOptions {
+  /**
+   * The element to track. Can be an Element, ref, or selector string.
+   * Defaults to document.body if not provided.
+   */
+  element?: Element | React.RefObject<Element> | string | null;
+  /**
+   * Whether to enable rect tracking
+   */
+  enabled?: boolean;
+  /**
+   * Throttle delay in milliseconds for rect updates
+   */
+  throttleMs?: number;
+  /**
+   * Whether to use ResizeObserver for more accurate tracking
+   */
+  useResizeObserver?: boolean;
+}
+
+const initialRect: RectState = {
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+};
+
+const isSSR = typeof window === "undefined";
+const hasResizeObserver = !isSSR && typeof ResizeObserver !== "undefined";
+
+/**
+ * Helper function to check if code is running on client side
+ */
+const isClientSide = (): boolean => !isSSR;
+
+/**
+ * Custom hook that tracks an element's bounding rectangle and updates on resize, scroll, etc.
+ *
+ * @param options Configuration options for element rect tracking
+ * @returns The current bounding rectangle of the element
+ */
+export function useElementRect({
+  element,
+  enabled = true,
+  throttleMs = 100,
+  useResizeObserver = true,
+}: ElementRectOptions = {}): RectState {
+  const [rect, setRect] = useState<RectState>(initialRect);
+
+  const getTargetElement = useCallback((): Element | null => {
+    if (!enabled || !isClientSide()) return null;
+
+    if (!element) {
+      return document.body;
+    }
+
+    if (typeof element === "string") {
+      return document.querySelector(element);
+    }
+
+    if ("current" in element) {
+      return element.current;
+    }
+
+    return element;
+  }, [element, enabled]);
+
+  const updateRect = useThrottledCallback(
+    () => {
+      if (!enabled || !isClientSide()) return;
+
+      const targetElement = getTargetElement();
+      if (!targetElement) {
+        setRect(initialRect);
+        return;
+      }
+
+      const newRect = targetElement.getBoundingClientRect();
+      setRect({
+        x: newRect.x,
+        y: newRect.y,
+        width: newRect.width,
+        height: newRect.height,
+        top: newRect.top,
+        right: newRect.right,
+        bottom: newRect.bottom,
+        left: newRect.left,
+      });
+    },
+    throttleMs,
+    [enabled, getTargetElement],
+    { leading: true, trailing: true },
+  );
+
+  useEffect(() => {
+    if (!enabled || !isClientSide()) {
+      setRect(initialRect);
+      return;
+    }
+
+    const targetElement = getTargetElement();
+    if (!targetElement) return;
+
+    updateRect();
+
+    const cleanup: (() => void)[] = [];
+
+    if (useResizeObserver && hasResizeObserver) {
+      const resizeObserver = new ResizeObserver(() => {
+        window.requestAnimationFrame(updateRect);
+      });
+      resizeObserver.observe(targetElement);
+      cleanup.push(() => resizeObserver.disconnect());
+    }
+
+    const handleUpdate = () => updateRect();
+
+    window.addEventListener("scroll", handleUpdate, true);
+    window.addEventListener("resize", handleUpdate, true);
+
+    cleanup.push(() => {
+      window.removeEventListener("scroll", handleUpdate);
+      window.removeEventListener("resize", handleUpdate);
+    });
+
+    return () => {
+      cleanup.forEach((fn) => fn());
+      setRect(initialRect);
+    };
+  }, [enabled, getTargetElement, updateRect, useResizeObserver]);
+
+  return rect;
+}
+
+/**
+ * Convenience hook for tracking document.body rect
+ */
+export function useBodyRect(options: Omit<ElementRectOptions, "element"> = {}): RectState {
+  return useElementRect({
+    ...options,
+    element: isClientSide() ? document.body : null,
+  });
+}
+
+/**
+ * Convenience hook for tracking a ref element's rect
+ */
+export function useRefRect<T extends Element>(
+  ref: React.RefObject<T>,
+  options: Omit<ElementRectOptions, "element"> = {},
+): RectState {
+  return useElementRect({ ...options, element: ref });
+}

package/src/hooks/use-floating-element.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useEffect, useMemo } from "react";
+import type { AutoUpdateOptions, UseDismissProps, UseFloatingOptions } from "@floating-ui/react";
+import { autoUpdate, useDismiss, useFloating, useInteractions, useTransitionStyles } from "@floating-ui/react";
+
+interface FloatingElementReturn {
+  /**
+   * Whether the floating element is currently mounted in the DOM.
+   */
+  isMounted: boolean;
+  /**
+   * Ref function to attach to the floating element DOM node.
+   */
+  ref: (node: HTMLElement | null) => void;
+  /**
+   * Combined styles for positioning, transitions, and z-index.
+   */
+  style: React.CSSProperties;
+  /**
+   * Returns props that should be spread onto the floating element.
+   */
+  getFloatingProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
+  /**
+   * Returns props that should be spread onto the reference element.
+   */
+  getReferenceProps: (userProps?: React.HTMLProps<Element>) => Record<string, unknown>;
+}
+
+/**
+ * Custom hook for creating and managing floating elements relative to a reference position
+ *
+ * @param show - Boolean controlling visibility of the floating element
+ * @param referencePos - DOMRect, function returning DOMRect, or null representing the position to anchor the floating element to
+ * @param zIndex - Z-index value for the floating element
+ * @param options - Additional options to pass to the underlying useFloating hook
+ * @returns Object containing properties and methods to control the floating element
+ */
+export function useFloatingElement(
+  show: boolean,
+  reference: HTMLElement | DOMRect | (() => DOMRect | null) | null,
+  zIndex: number,
+  options?: Partial<UseFloatingOptions & { dismissOptions?: UseDismissProps }>,
+  autoUpdateOptions?: AutoUpdateOptions,
+): FloatingElementReturn {
+  const { dismissOptions, ...floatingOptions } = options || {};
+
+  const { refs, context, floatingStyles } = useFloating({
+    open: show,
+    whileElementsMounted(referenceEl, floatingEl, update) {
+      const cleanup = autoUpdate(referenceEl, floatingEl, update, autoUpdateOptions);
+      return cleanup;
+    },
+    ...floatingOptions,
+  });
+
+  const { isMounted, styles } = useTransitionStyles(context);
+
+  const dismiss = useDismiss(context, dismissOptions);
+
+  const { getReferenceProps, getFloatingProps } = useInteractions([dismiss]);
+
+  useEffect(() => {
+    if (reference === null) {
+      refs.setReference(null);
+      return;
+    }
+
+    // If reference is an actual DOM element, use it directly
+    // autoUpdate will automatically observe it for scroll/resize
+    if (reference instanceof HTMLElement) {
+      refs.setReference(reference);
+
+      return;
+    }
+
+    const getBoundingClientRect = () => {
+      const rect = typeof reference === "function" ? reference() : reference;
+      return rect || new DOMRect();
+    };
+
+    refs.setReference({
+      getBoundingClientRect,
+    });
+  }, [reference, refs]);
+
+  return useMemo(
+    () => ({
+      isMounted,
+      ref: refs.setFloating,
+      style: {
+        ...styles,
+        ...floatingStyles,
+        zIndex,
+      },
+      getFloatingProps,
+      getReferenceProps,
+    }),
+    [floatingStyles, isMounted, refs.setFloating, styles, zIndex, getFloatingProps, getReferenceProps],
+  );
+}

package/src/hooks/use-floating-toolbar-visibility.ts

@@ -0,0 +1,123 @@
+import { isNodeSelection, type Editor } from "@tiptap/react"
+import { NodeSelection, type Transaction } from "@tiptap/pm/state"
+import { useEffect, useRef, useState } from "react"
+
+export const HIDE_FLOATING_META = "hideFloatingToolbar"
+
+/**
+ * Centralizes all logic about when the floating toolbar should be hidden/shown.
+ *
+ * - Listens for transactions that carry HIDE_FLOATING_META
+ * - Clears the hide flag on common “user intent” events
+ * - Handles the “re-click on the same selected node” case
+ * - Exposes `shouldShow` so UI can just render based on it
+ * - Exposes helpers to set selections with the meta flag
+ */
+export function useFloatingToolbarVisibility(params: {
+  editor: Editor | null
+  isSelectionValid: (
+    editor: Editor,
+    selection: Editor["state"]["selection"]
+  ) => boolean
+  extraHideWhen?: boolean // e.g. aiGenerationActive || commentInputVisible
+}) {
+  const { editor, isSelectionValid, extraHideWhen = false } = params
+  const [shouldShow, setShouldShow] = useState(false)
+  const hideRef = useRef(false)
+
+  // --- TX listener: turn on hide when our meta is present, clear it on new Selection without the flag
+  useEffect(() => {
+    if (!editor) return
+
+    const onTx = ({ transaction }: { transaction: Transaction }) => {
+      if (transaction.getMeta(HIDE_FLOATING_META)) {
+        hideRef.current = true
+      } else if (
+        // Clear hide flag when a new Selection is made without the meta
+        // This ensures first-click on a new selection shows the floating toolbar again
+        transaction.selectionSet
+      ) {
+        hideRef.current = false
+      }
+    }
+
+    editor.on("transaction", onTx)
+
+    return () => {
+      editor.off("transaction", onTx)
+    }
+  }, [editor])
+
+  // --- Re-click same selected node should immediately allow floating
+  useEffect(() => {
+    if (!editor) return
+    const dom = editor.view.dom
+
+    const onPointerDown = (e: PointerEvent) => {
+      const sel = editor.state.selection
+      if (!(sel instanceof NodeSelection)) return
+      const nodeDom = editor.view.nodeDOM(sel.from) as HTMLElement | null
+      if (!nodeDom) return
+      if (nodeDom.contains(e.target as Node)) {
+        hideRef.current = false
+        // selection won't change, recompute now
+        const valid = isSelectionValid(editor, sel)
+        setShouldShow(valid && !extraHideWhen)
+      }
+    }
+
+    dom.addEventListener("pointerdown", onPointerDown, { capture: true })
+    return () =>
+      dom.removeEventListener("pointerdown", onPointerDown, {
+        capture: true,
+      })
+  }, [editor, extraHideWhen, isSelectionValid])
+
+  // --- Selection-driven visibility
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      const { selection } = editor.state
+      const valid = isSelectionValid(editor, selection)
+
+      if (extraHideWhen || (isNodeSelection(selection) && hideRef.current)) {
+        setShouldShow(false)
+        return
+      }
+      setShouldShow(valid)
+    }
+
+    handleSelectionUpdate()
+    editor.on("selectionUpdate", handleSelectionUpdate)
+    return () => {
+      editor.off("selectionUpdate", handleSelectionUpdate)
+    }
+  }, [editor, extraHideWhen, isSelectionValid])
+
+  return { shouldShow }
+}
+
+/**
+ * Programmatically select a node and hide floating for that selection
+ * @param editor
+ * @param pos
+ */
+export const selectNodeAndHideFloating = (editor: Editor, pos: number) => {
+  if (!editor) return
+  const { state, view } = editor
+  view.dispatch(
+    state.tr
+      .setSelection(NodeSelection.create(state.doc, pos))
+      .setMeta(HIDE_FLOATING_META, true)
+  )
+}
+
+/**
+ * Mark “hide floating” on the next relevant transaction (no selection change needed)
+ * @param editor
+ */
+export const markHideFloatingOnNext = (editor: Editor) => {
+  if (!editor) return
+  editor.view.dispatch(editor.state.tr.setMeta(HIDE_FLOATING_META, true))
+}

package/src/hooks/use-is-breakpoint.ts

@@ -0,0 +1,37 @@
+"use client"
+
+import { useEffect, useState } from "react"
+
+type BreakpointMode = "min" | "max"
+
+/**
+ * Hook to detect whether the current viewport matches a given breakpoint rule.
+ * Example:
+ *   useIsBreakpoint("max", 768)   // true when width < 768
+ *   useIsBreakpoint("min", 1024)  // true when width >= 1024
+ */
+export function useIsBreakpoint(
+  mode: BreakpointMode = "max",
+  breakpoint = 768
+) {
+  const [matches, setMatches] = useState<boolean | undefined>(undefined)
+
+  useEffect(() => {
+    const query =
+      mode === "min"
+        ? `(min-width: ${breakpoint}px)`
+        : `(max-width: ${breakpoint - 1}px)`
+
+    const mql = window.matchMedia(query)
+    const onChange = (e: MediaQueryListEvent) => setMatches(e.matches)
+
+    // Set initial value
+    setMatches(mql.matches)
+
+    // Add listener
+    mql.addEventListener("change", onChange)
+    return () => mql.removeEventListener("change", onChange)
+  }, [mode, breakpoint])
+
+  return !!matches
+}

package/src/hooks/use-isomorphic-layout-effect.ts

@@ -0,0 +1,11 @@
+"use client"
+
+import { useEffect, useLayoutEffect } from "react"
+
+/**
+ * Custom hook that uses either `useLayoutEffect` or `useEffect` based on the environment (client-side or server-side).
+ * @param {Function} effect - The effect function to be executed.
+ * @param {Array<any>} [dependencies] - An array of dependencies for the effect (optional).
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect