@multiplatform.one/forms 6.0.0

package/src/fields/MentionInput/index.tsx

@@ -0,0 +1,691 @@
+import type { Validator } from "../../types";
+
+import type { DeepKeys, DeepValue } from "@tanstack/form-core";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useProps, type SizeTokens } from "tamagui";
+import { Avatar, Text, View, XStack, YStack, styled } from "tamagui";
+import { useDismiss, useInteractions } from "@floating-ui/react";
+
+import { formInputColors } from "../../shared/colorRamps";
+import { ScrollArrow } from "../../shared/floatingList";
+import { Skeleton } from "../../Skeleton";
+import { zIndex } from "../../shared/zIndex";
+import { useFloatingPanel, panelTransition } from "../../FloatingPanel";
+import { Field } from "../../fieldLayout";
+import {
+  getFieldError,
+  getFieldHeight,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import type { FormFieldProps } from "../../fieldLayout";
+import type { FieldComponentProps } from "../../types";
+import { Input as InputParts } from "../../InputParts";
+import { TextArea } from "../TextArea";
+
+export interface MentionItem {
+  id: string;
+  display: string;
+  avatar?: string;
+  description?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface MentionConfig {
+  trigger: string;
+  data: MentionItem[];
+  allowSpace?: boolean;
+  insertSpace?: boolean;
+  menuHeight?: number;
+  menuWidth?: number;
+}
+
+export interface MentionData {
+  type: string;
+  id: string;
+  display: string;
+  position: number;
+  length: number;
+}
+
+export interface MentionValue {
+  text: string;
+  mentions: MentionData[];
+}
+
+export type MentionInputProps<
+  TParentData = any,
+  TName extends DeepKeys<TParentData> = any,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = Omit<
+  FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+  "children" | "field"
+> &
+  Partial<
+    Omit<
+      FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+      "children"
+    >
+  > & {
+    readOnly?: boolean;
+    mentions: MentionConfig[];
+    placeholder?: string;
+    minHeight?: number;
+    maxHeight?: number;
+    autoResize?: boolean;
+    onMentionSelect?: (mention: MentionItem, trigger: string) => void;
+    onTextChange?: (text: string) => void;
+    textAreaProps?: Record<string, any>;
+    /** When true, renders a skeleton placeholder instead of the mention input */
+    skeleton?: boolean;
+    /** When true, uses compact sizing */
+    compact?: boolean;
+  };
+
+const estimatedItemHeight = 48;
+const blurCloseDelayMs = 150;
+const zeroWidthSpace = "\u200b";
+
+const MentionSuggestionItem = styled(XStack, {
+  padding: "$3",
+  alignItems: "center",
+  cursor: "pointer",
+  hoverStyle: { backgroundColor: formInputColors.background.focus },
+  variants: {
+    selected: {
+      true: { backgroundColor: formInputColors.background.base },
+      false: { backgroundColor: "transparent" },
+    },
+  } as const,
+});
+
+export function MentionInput<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+>(props: MentionInputProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const {
+    defaultValue,
+    form,
+    mentions = [],
+    placeholder = "Type @ to mention someone",
+    minHeight: minHeightProp,
+    maxHeight: maxHeightProp,
+    autoResize = false,
+    onMentionSelect,
+    onTextChange,
+    textAreaProps,
+    mode,
+    name,
+    preserveValue,
+    validators,
+    disabled,
+    readOnly,
+    label,
+    labelProps,
+    error: errorProp,
+    helperText,
+    required,
+    size,
+    onBlur,
+    skeleton,
+    compact,
+    id: idProp,
+  } = useProps(props);
+
+  const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const resolvedSizeToken = (size || knobProps.sizeToken) as SizeTokens;
+  const minHeight = minHeightProp ?? getFieldHeight(resolvedSizeToken, 3);
+  const maxHeight = maxHeightProp ?? getFieldHeight(resolvedSizeToken, 8);
+  const minRows = Math.max(1, Math.round(minHeight / 20));
+  const maxRows = Math.max(minRows, Math.round(maxHeight / 20));
+
+  const [text, setText] = useState("");
+  const [mentionList, setMentionList] = useState<MentionData[]>([]);
+  const [showSuggestions, setShowSuggestions] = useState(false);
+  const [currentTrigger, setCurrentTrigger] = useState<string | null>(null);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [cursorPosition, setCursorPosition] = useState(0);
+
+  const textAreaRef = useRef<any>(null);
+  const prevCursorRef = useRef(0);
+  const prevQueryRef = useRef("");
+  const blurTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const fieldRef = useRef<{ handleChange: (value: any) => void } | null>(null);
+
+  const triggerMap = useMemo(() => {
+    const map = new Map<string, MentionConfig>();
+    for (const config of mentions) {
+      map.set(config.trigger, config);
+    }
+    return map;
+  }, [mentions]);
+
+  const checkForTrigger = useCallback(
+    (currentText: string, position: number) => {
+      for (const [trigger, config] of triggerMap) {
+        const allowSpace = config.allowSpace ?? false;
+        let wordStart = position;
+        while (wordStart > 0) {
+          const char = currentText[wordStart - 1];
+          if (char === "\n") break;
+          if (char === " " && !allowSpace) break;
+          wordStart--;
+        }
+        const currentWord = currentText.slice(wordStart, position);
+        if (currentWord.startsWith(trigger)) {
+          const query = currentWord.slice(trigger.length);
+          return { trigger, query, wordStart };
+        }
+      }
+      return null;
+    },
+    [triggerMap],
+  );
+
+  const getFilteredSuggestions = useCallback(
+    (trigger: string, query: string) => {
+      const config = triggerMap.get(trigger);
+      if (!config) return [];
+      return config.data.filter(
+        (item) =>
+          item.display.toLowerCase().includes(query.toLowerCase()) ||
+          item.id.toLowerCase().includes(query.toLowerCase()),
+      );
+    },
+    [triggerMap],
+  );
+
+  const suggestions = useMemo(
+    () =>
+      showSuggestions && currentTrigger ? getFilteredSuggestions(currentTrigger, searchQuery) : [],
+    [showSuggestions, currentTrigger, searchQuery, getFilteredSuggestions],
+  );
+  const hasSuggestions = suggestions.length > 0;
+
+  const panel = useFloatingPanel({
+    open: hasSuggestions,
+    onOpenChange: (nextOpen) => {
+      if (!nextOpen) {
+        setShowSuggestions(false);
+        setCurrentTrigger(null);
+        prevQueryRef.current = "";
+      }
+    },
+    fitContent: true,
+  });
+
+  const dismiss = useDismiss(panel.context, {
+    outsidePressEvent: "click",
+    ancestorScroll: false,
+  });
+  const { getFloatingProps } = useInteractions([dismiss]);
+
+  useEffect(() => {
+    fieldRef.current?.handleChange({ text, mentions: mentionList } as any);
+  }, [text, mentionList]);
+
+  useEffect(() => {
+    return () => {
+      if (blurTimeoutRef.current) clearTimeout(blurTimeoutRef.current);
+    };
+  }, []);
+
+  const updateTriggerState = useCallback(
+    (currentText: string, position: number) => {
+      const triggerInfo = checkForTrigger(currentText, position);
+      if (triggerInfo) {
+        setCurrentTrigger(triggerInfo.trigger);
+        setSearchQuery(triggerInfo.query);
+        setShowSuggestions(true);
+        if (triggerInfo.query !== prevQueryRef.current) {
+          setSelectedIndex(0);
+        }
+        prevQueryRef.current = triggerInfo.query;
+      } else {
+        setShowSuggestions(false);
+        setCurrentTrigger(null);
+        prevQueryRef.current = "";
+      }
+    },
+    [checkForTrigger],
+  );
+
+  const handleTextChange = useCallback(
+    (newText: string) => {
+      const oldText = text;
+      const editPosition = prevCursorRef.current;
+      const lengthDiff = newText.length - oldText.length;
+
+      if (lengthDiff !== 0) {
+        setMentionList((prev) =>
+          prev
+            .map((m) => ({ ...m }))
+            .filter((mention) => {
+              const mentionEnd = mention.position + mention.length;
+              if (editPosition >= mentionEnd) return true;
+              if (editPosition <= mention.position) {
+                mention.position += lengthDiff;
+                const expectedText = `${mention.type}${mention.display}`;
+                const actualText = newText.slice(
+                  mention.position,
+                  mention.position + mention.length,
+                );
+                return actualText === expectedText;
+              }
+              return false;
+            }),
+        );
+      }
+
+      setText(newText);
+      const estimatedCursor = Math.max(
+        0,
+        Math.min(editPosition + Math.max(0, lengthDiff), newText.length),
+      );
+      setCursorPosition(estimatedCursor);
+      updateTriggerState(newText, estimatedCursor);
+      onTextChange?.(newText);
+    },
+    [text, updateTriggerState, onTextChange],
+  );
+
+  const handleSelectionChange = useCallback(
+    (event: any) => {
+      const selection = event?.nativeEvent?.selection;
+      if (selection) {
+        prevCursorRef.current = selection.start;
+        setCursorPosition(selection.start);
+        updateTriggerState(text, selection.start);
+      }
+    },
+    [text, updateTriggerState],
+  );
+
+  const insertMention = useCallback(
+    (item: MentionItem) => {
+      if (!currentTrigger) return;
+      const triggerInfo = checkForTrigger(text, cursorPosition);
+      if (!triggerInfo) return;
+
+      const { wordStart } = triggerInfo;
+      const beforeMention = text.slice(0, wordStart);
+      const afterMention = text.slice(cursorPosition);
+      const mentionText = `${currentTrigger}${item.display}`;
+      const config = triggerMap.get(currentTrigger);
+      const insertSpace = config?.insertSpace !== false;
+      const newText = beforeMention + mentionText + (insertSpace ? " " : "") + afterMention;
+      const insertedLength = mentionText.length + (insertSpace ? 1 : 0);
+      const oldLength = cursorPosition - wordStart;
+      const positionDiff = insertedLength - oldLength;
+
+      const adjustedMentions = mentionList.map((m) =>
+        m.position > wordStart ? { ...m, position: m.position + positionDiff } : m,
+      );
+
+      const newMention: MentionData = {
+        type: currentTrigger,
+        id: item.id,
+        display: item.display,
+        position: wordStart,
+        length: mentionText.length,
+      };
+
+      const newCursorPos = wordStart + mentionText.length + (insertSpace ? 1 : 0);
+      setText(newText);
+      setMentionList([...adjustedMentions, newMention]);
+      setCursorPosition(newCursorPos);
+      prevCursorRef.current = newCursorPos;
+      setShowSuggestions(false);
+      setCurrentTrigger(null);
+      prevQueryRef.current = "";
+      onMentionSelect?.(item, currentTrigger);
+      setTimeout(() => textAreaRef.current?.focus(), 0);
+    },
+    [
+      text,
+      cursorPosition,
+      currentTrigger,
+      checkForTrigger,
+      triggerMap,
+      mentionList,
+      onMentionSelect,
+    ],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: any) => {
+      if (!showSuggestions || !currentTrigger || suggestions.length === 0) return;
+      const key = event.key || event.nativeEvent?.key;
+
+      switch (key) {
+        case "ArrowDown":
+          event.preventDefault?.();
+          setSelectedIndex((prev) => (prev < suggestions.length - 1 ? prev + 1 : 0));
+          break;
+        case "ArrowUp":
+          event.preventDefault?.();
+          setSelectedIndex((prev) => (prev > 0 ? prev - 1 : suggestions.length - 1));
+          break;
+        case "Enter":
+          event.preventDefault?.();
+          if (suggestions[selectedIndex]) {
+            insertMention(suggestions[selectedIndex]);
+          }
+          break;
+        case "Escape":
+          event.preventDefault?.();
+          setShowSuggestions(false);
+          break;
+      }
+    },
+    [showSuggestions, currentTrigger, suggestions, selectedIndex, insertMention],
+  );
+
+  useEffect(() => {
+    if (hasSuggestions && panel.refs.floating.current) {
+      panel.refs.floating.current.scrollTo?.({
+        top: Math.max(0, (selectedIndex - 2) * estimatedItemHeight),
+        behavior: "smooth",
+      });
+    }
+  }, [selectedIndex, hasSuggestions, panel.refs.floating]);
+
+  const handleBlurInternal = useCallback((..._args: any[]) => {
+    blurTimeoutRef.current = setTimeout(() => {
+      setShowSuggestions(false);
+    }, blurCloseDelayMs);
+  }, []);
+
+  const handleSuggestionPress = useCallback(
+    (item: MentionItem) => {
+      if (blurTimeoutRef.current) {
+        clearTimeout(blurTimeoutRef.current);
+        blurTimeoutRef.current = null;
+      }
+      insertMention(item);
+    },
+    [insertMention],
+  );
+
+  const activeConfig = currentTrigger ? triggerMap.get(currentTrigger) : null;
+  const suggestionsMaxHeight =
+    activeConfig?.menuHeight ??
+    (knobProps.sizeToken === "$3" ? 160 : knobProps.sizeToken === "$5" ? 240 : 200);
+  const suggestionsMinWidth =
+    activeConfig?.menuWidth ??
+    (knobProps.sizeToken === "$3" ? 180 : knobProps.sizeToken === "$5" ? 240 : 200);
+
+  // ── Textarea element access ────────────────────────────────
+
+  const getWebTextAreaElement = useCallback((): HTMLTextAreaElement | null => {
+    if (typeof document === "undefined") return null;
+    const current = textAreaRef.current as
+      | HTMLTextAreaElement
+      | { textarea?: HTMLTextAreaElement; _textarea?: HTMLTextAreaElement }
+      | HTMLElement
+      | null;
+    if (!current) return null;
+    if (current instanceof HTMLTextAreaElement) return current;
+    if ("textarea" in current && current.textarea instanceof HTMLTextAreaElement) {
+      return current.textarea;
+    }
+    if ("_textarea" in current && current._textarea instanceof HTMLTextAreaElement) {
+      return current._textarea;
+    }
+    if (current instanceof HTMLElement) {
+      const nested = current.querySelector("textarea");
+      return nested instanceof HTMLTextAreaElement ? nested : null;
+    }
+    return null;
+  }, []);
+
+  // ── Virtual reference at caret position ────────────────────
+
+  const getCaretClientRect = useCallback((): DOMRect => {
+    const fallback = DOMRect.fromRect({ x: 0, y: 0, width: 1, height: 16 });
+    if (typeof window === "undefined" || typeof document === "undefined") return fallback;
+    const textAreaElement = getWebTextAreaElement();
+    if (!textAreaElement) return fallback;
+
+    const style = window.getComputedStyle(textAreaElement);
+    const textAreaRect = textAreaElement.getBoundingClientRect();
+    const mirror = document.createElement("div");
+    mirror.style.position = "absolute";
+    mirror.style.visibility = "hidden";
+    mirror.style.pointerEvents = "none";
+    mirror.style.whiteSpace = "pre-wrap";
+    mirror.style.wordWrap = "break-word";
+    mirror.style.overflowWrap = "anywhere";
+    mirror.style.left = "-9999px";
+    mirror.style.top = "0";
+    mirror.style.width = `${textAreaElement.clientWidth}px`;
+    mirror.style.fontFamily = style.fontFamily;
+    mirror.style.fontSize = style.fontSize;
+    mirror.style.fontWeight = style.fontWeight;
+    mirror.style.fontStyle = style.fontStyle;
+    mirror.style.letterSpacing = style.letterSpacing;
+    mirror.style.lineHeight = style.lineHeight;
+    mirror.style.textTransform = style.textTransform;
+    mirror.style.textIndent = style.textIndent;
+    mirror.style.tabSize = style.tabSize;
+    mirror.style.padding = style.padding;
+    mirror.style.border = style.border;
+    mirror.style.boxSizing = style.boxSizing;
+    mirror.textContent = text.slice(0, cursorPosition);
+
+    const marker = document.createElement("span");
+    marker.textContent = text[cursorPosition] || zeroWidthSpace;
+    mirror.appendChild(marker);
+    document.body.appendChild(mirror);
+
+    try {
+      const markerRect = marker.getBoundingClientRect();
+      const mirrorRect = mirror.getBoundingClientRect();
+      const parsedLineHeight = Number.parseFloat(style.lineHeight);
+      const parsedFontSize = Number.parseFloat(style.fontSize);
+      const lineHeight = Number.isFinite(parsedLineHeight)
+        ? parsedLineHeight
+        : Number.isFinite(parsedFontSize)
+          ? parsedFontSize * 1.2
+          : 18;
+      const relLeft = markerRect.left - mirrorRect.left - textAreaElement.scrollLeft;
+      const relTop = markerRect.top - mirrorRect.top - textAreaElement.scrollTop;
+      const left = textAreaRect.left + relLeft;
+      const top = textAreaRect.top + relTop;
+      return DOMRect.fromRect({ x: left, y: top, width: 1, height: lineHeight });
+    } finally {
+      document.body.removeChild(mirror);
+    }
+  }, [getWebTextAreaElement, text, cursorPosition]);
+
+  useEffect(() => {
+    const el = getWebTextAreaElement();
+    if (el) panel.triggerRef.current = el;
+  });
+
+  useLayoutEffect(() => {
+    if (!hasSuggestions) return;
+    const rect = getCaretClientRect();
+    panel.refs.setReference({ getBoundingClientRect: () => rect });
+    panel.update();
+  }, [hasSuggestions, cursorPosition, text]);
+
+  const suggestionListId = `${id}-suggestions`;
+  const selectedOptionId =
+    hasSuggestions && suggestions[selectedIndex]
+      ? `${id}-option-${suggestions[selectedIndex].id}`
+      : undefined;
+
+  // ── Floating dropdown ──────────────────────────────────────
+
+  const floatingDropdown = panel.mounted ? (
+    <YStack
+      {...getFloatingProps({
+        ref: panel.refs.setFloating,
+        style: {
+          position: panel.strategy,
+          top: panel.y ?? 0,
+          left: panel.x ?? 0,
+          scrollbarWidth: "none" as any,
+          zIndex: zIndex.dropdown,
+          overflow: "auto",
+          boxShadow: "0px 8px 28px rgba(0,0,0,0.12), 0px 2px 6px rgba(0,0,0,0.04)",
+          opacity: panel.visible ? 1 : 0,
+          transform: panel.visible ? "scale(1)" : "scale(0.96)",
+          transition: panelTransition,
+          transformOrigin: panel.placement.startsWith("top") ? "bottom left" : "top left",
+        },
+        onScroll: (e: any) => panel.updateArrows(e.target as HTMLElement),
+      })}
+      outlineWidth={0}
+      pointerEvents={panel.visible ? "auto" : "none"}
+      backgroundColor="$background"
+      borderRadius={panel.dropdownRadius}
+      borderWidth={panel.hasBorder ? panel.knobProps.borderRadius.borderWidth : 0}
+      borderColor={panel.hasBorder ? formInputColors.border.focus : "transparent"}
+      paddingVertical={0}
+      maxHeight={suggestionsMaxHeight}
+      minWidth={suggestionsMinWidth}
+      role={"listbox" as "list"}
+      id={suggestionListId}
+      aria-label="Suggestions"
+    >
+      <ScrollArrow
+        direction="up"
+        scrollRef={panel.refs.floating}
+        visible={panel.arrowUp}
+        arrowScrollDirRef={panel.arrowScrollDirRef}
+      />
+      <View {...panel.knobProps.panelPadding}>
+        {suggestions.map((item, index) => {
+          const optionId = `${id}-option-${item.id}`;
+          return (
+            <MentionSuggestionItem
+              key={item.id}
+              {...knobProps.gap}
+              selected={index === selectedIndex}
+              onPress={() => handleSuggestionPress(item)}
+              role="option"
+              id={optionId}
+              aria-selected={index === selectedIndex}
+            >
+              {item.avatar && (
+                <Avatar size="$2" circular>
+                  <Avatar.Image src={item.avatar} />
+                  <Avatar.Fallback backgroundColor={formInputColors.background.focus}>
+                    <Text>{item.display[0]}</Text>
+                  </Avatar.Fallback>
+                </Avatar>
+              )}
+              <YStack flex={1}>
+                <Text fontSize={knobProps.sizeToken} {...knobProps.body}>
+                  {item.display}
+                </Text>
+                {item.description && (
+                  <Text fontSize={knobProps.sizeToken} color="$colorHover" {...knobProps.body}>
+                    {item.description}
+                  </Text>
+                )}
+              </YStack>
+            </MentionSuggestionItem>
+          );
+        })}
+      </View>
+      <ScrollArrow
+        direction="down"
+        scrollRef={panel.refs.floating}
+        visible={panel.arrowDown}
+        arrowScrollDirRef={panel.arrowScrollDirRef}
+      />
+    </YStack>
+  ) : null;
+
+  // ── TextArea ───────────────────────────────────────────────
+
+  const mentionTextArea = (
+    resolvedError?: string | boolean,
+    fieldBlurHandler?: (...args: any[]) => void,
+  ) => (
+    <TextArea
+      disabled={disabled}
+      readOnly={readOnly}
+      label={label}
+      labelProps={labelProps}
+      error={resolvedError ?? errorProp}
+      helperText={helperText}
+      required={required}
+      size={size}
+      onBlur={(...args: any[]) => {
+        handleBlurInternal(...args);
+        if (fieldBlurHandler) {
+          fieldBlurHandler(...args);
+        } else {
+          onBlur?.(...args);
+        }
+      }}
+      value={text}
+      onChangeText={handleTextChange}
+      placeholder={placeholder}
+      autoResize={autoResize}
+      minRows={minRows}
+      maxRows={maxRows}
+      textAreaRef={textAreaRef}
+      textAreaProps={{
+        onSelectionChange: handleSelectionChange,
+        onKeyDown: handleKeyDown as any,
+        "aria-haspopup": "listbox",
+        "aria-expanded": hasSuggestions,
+        "aria-controls": hasSuggestions ? suggestionListId : undefined,
+        "aria-activedescendant": selectedOptionId,
+        ...textAreaProps,
+      }}
+    />
+  );
+
+  // Render skeleton placeholder (after all hooks)
+  if (skeleton) {
+    return (
+      <InputParts size={size || knobProps.sizeToken}>
+        {label && <Skeleton variant="text" width="30%" height={14} />}
+        <Skeleton variant="rounded" width="100%" height={minHeight} />
+      </InputParts>
+    );
+  }
+
+  if (!resolvedForm || !name) {
+    return (
+      <>
+        {mentionTextArea()}
+        {floatingDropdown}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <Field
+        defaultValue={defaultValue}
+        form={resolvedForm}
+        mode={mode}
+        name={name}
+        preserveValue={preserveValue}
+        validators={resolvedValidators}
+      >
+        {(field) => {
+          fieldRef.current = { handleChange: field.handleChange };
+          const resolvedError = getFieldError(field, errorProp);
+          return mentionTextArea(resolvedError, mergeFieldHandler(field, "handleBlur", onBlur));
+        }}
+      </Field>
+      {floatingDropdown}
+    </>
+  );
+}