@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/MentionInput/MentionInput.spec.tsx

@@ -1,7 +1,25 @@
-import { describe, expect, it } from "vitest";
+import { fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { MentionInput } from "./index";
 
+const userMentions = {
+  trigger: "@",
+  data: [
+    {
+      id: "u1",
+      display: "Alice",
+      avatar: "https://example.com/a.png",
+      description: "Engineer",
+    },
+    {
+      id: "u2",
+      display: "Bob",
+      description: "Designer",
+    },
+  ],
+};
+
 describe("MentionInput", () => {
   it("should render with label and placeholder", () => {
     const result = renderWithProviders(
@@ -22,4 +40,100 @@ describe("MentionInput", () => {
     const textArea = result.container.querySelector("textarea");
     expect(textArea?.getAttribute("placeholder")).toBe("Type @ to mention");
   });
+
+  it("fires canonical onChange and the deprecated onTextChange alias once per change", () => {
+    const onChange = vi.fn();
+    const onTextChange = vi.fn();
+    const result = renderWithProviders(
+      <MentionInput
+        label="Comment"
+        name="comment"
+        mentions={[
+          {
+            trigger: "@",
+            data: [{ id: "u1", display: "Alice" }],
+          },
+        ]}
+        onChange={onChange}
+        onTextChange={onTextChange}
+      />,
+    );
+
+    const textArea = result.container.querySelector("textarea");
+    expect(textArea).toBeTruthy();
+    if (textArea) fireEvent.change(textArea, { target: { value: "hello" } });
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("hello");
+    expect(onTextChange).toHaveBeenCalledTimes(1);
+    expect(onTextChange).toHaveBeenCalledWith("hello");
+  });
+
+  it("opens a flush listbox with media-slot rows when typing @", () => {
+    const result = renderWithProviders(
+      <MentionInput label="Comment" name="comment" mentions={[userMentions]} />,
+    );
+
+    const textArea = result.container.querySelector("textarea");
+    expect(textArea).toBeTruthy();
+    if (!textArea) return;
+
+    fireEvent.change(textArea, { target: { value: "@", selectionStart: 1, selectionEnd: 1 } });
+    // Web caret tracking also listens to select — keep both in sync like the browser.
+    Object.defineProperty(textArea, "selectionStart", { value: 1, configurable: true });
+    Object.defineProperty(textArea, "selectionEnd", { value: 1, configurable: true });
+    fireEvent.select(textArea);
+
+    const listbox = result.container.ownerDocument.querySelector('[role="listbox"]');
+    expect(listbox).toBeTruthy();
+    if (!listbox) return;
+
+    const style = getComputedStyle(listbox);
+    expect(style.paddingTop).toBe("0px");
+    expect(style.paddingRight).toBe("0px");
+    expect(style.paddingBottom).toBe("0px");
+    expect(style.paddingLeft).toBe("0px");
+
+    const options = listbox.querySelectorAll('[role="option"]');
+    expect(options.length).toBe(2);
+    // Both rows reserve a media slot when any item has an avatar (Bob has none).
+    expect(result.findTextElement("Alice")).toBeDefined();
+    expect(result.findTextElement("Bob")).toBeDefined();
+    expect(result.findTextElement("Engineer")).toBeDefined();
+    expect(result.findTextElement("Designer")).toBeDefined();
+    expect(result.findTextElement("B")).toBeDefined(); // Bob initials fallback
+  });
+
+  it("does not reserve a media slot for all-text triggers (hashtags)", () => {
+    const result = renderWithProviders(
+      <MentionInput
+        label="Post"
+        name="post"
+        mentions={[
+          {
+            trigger: "#",
+            data: [
+              { id: "react", display: "react" },
+              { id: "ts", display: "typescript" },
+            ],
+          },
+        ]}
+      />,
+    );
+
+    const textArea = result.container.querySelector("textarea");
+    expect(textArea).toBeTruthy();
+    if (!textArea) return;
+
+    fireEvent.change(textArea, { target: { value: "#", selectionStart: 1, selectionEnd: 1 } });
+    Object.defineProperty(textArea, "selectionStart", { value: 1, configurable: true });
+    Object.defineProperty(textArea, "selectionEnd", { value: 1, configurable: true });
+    fireEvent.select(textArea);
+
+    const listbox = result.container.ownerDocument.querySelector('[role="listbox"]');
+    expect(listbox).toBeTruthy();
+    expect(result.findTextElement("react")).toBeDefined();
+    // No avatar / initials glyphs for an all-text list.
+    expect(result.container.ownerDocument.querySelector("img")).toBeNull();
+  });
 });

package/src/fields/MentionInput/MentionInput.stories.tsx

@@ -26,6 +26,8 @@ const meta: Meta<typeof MentionInput> = {
     error: { control: "text", description: "Error message" },
     required: { control: "boolean", description: "Mark field as required" },
     disabled: { control: "boolean", description: "Disable the input" },
+    readOnly: { control: "boolean", description: "Read-only display" },
+    compact: { control: "boolean", description: "Use compact sizing" },
     size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
     minHeight: { control: "number", description: "Minimum height of input" },
     maxHeight: { control: "number", description: "Maximum height of input" },
@@ -205,8 +207,7 @@ export const Interactive: Story = {
         <YStack gap="$4" maxWidth={400}>
           <MentionInput
             label="Comment"
-            value={value}
-            // @ts-expect-error controlled mode not supported
+            defaultValue={value}
             onChange={(val: string) => {
               setValue(val);
               action("onChange")(val);
@@ -263,3 +264,8 @@ export const MultipleTriggersStory: Story = {
     disabled: false,
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the field's anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: () => <MentionInput label="Comment" mentions={[userMentions]} skeleton />,
+};

package/src/fields/MentionInput/index.tsx

@@ -3,10 +3,11 @@ 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 { Avatar, Text, XStack, YStack, isWeb, styled } from "tamagui";
 import { useDismiss, useInteractions } from "@floating-ui/react";
+import { menuRowFrame } from "@multiplatform.one/theme";
 
-import { formInputColors } from "../../shared/colorRamps";
+import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import { ScrollArrow } from "../../shared/floatingList";
 import { Skeleton } from "../../Skeleton";
 import { zIndex } from "../../shared/zIndex";
@@ -20,6 +21,7 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 import type { FormFieldProps } from "../../fieldLayout";
+import { t } from "../../shared/t";
 import type { FieldComponentProps } from "../../types";
 import { Input as InputParts } from "../../InputParts";
 import { TextArea } from "../TextArea";
@@ -62,7 +64,9 @@ export type MentionInputProps<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = Omit<
   FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-  "children" | "field"
+  // "onChange": FormFieldProps carries the DOM ChangeEventHandler from
+  // YStackProps; this field exposes a canonical value callback instead.
+  "children" | "field" | "onChange"
 > &
   Partial<
     Omit<
@@ -77,6 +81,12 @@ export type MentionInputProps<
     maxHeight?: number;
     autoResize?: boolean;
     onMentionSelect?: (mention: MentionItem, trigger: string) => void;
+    /**
+     * Canonical change handler, consistent with the rest of the field family.
+     * Fires with the raw text on every keystroke. Prefer this over `onTextChange`.
+     */
+    onChange?: (text: string) => void;
+    /** @deprecated Use `onChange` instead. */
     onTextChange?: (text: string) => void;
     textAreaProps?: Record<string, any>;
     /** When true, renders a skeleton placeholder instead of the mention input */
@@ -85,23 +95,38 @@ export type MentionInputProps<
     compact?: boolean;
   };
 
-const estimatedItemHeight = 48;
 const blurCloseDelayMs = 150;
 const zeroWidthSpace = "\u200b";
 
+// One fontSize step below the field size token \u2014 the T-HELPER register for the
+// secondary (role/description) line, matching the shared suggestion-row recipe.
+const helperFontSizeMap: Record<string, string> = { $3: "$2", $4: "$3", $5: "$4" };
+
+// LC-01 SP-EDGE-MENU: the row spans the full menu width and owns ALL padding
+// (the overlay container owns only its border), so the active/hover highlight
+// runs edge-to-edge. LC-16 ONE-IMPLEMENTATION: geometry IS the shared
+// `menuRowFrame` recipe from theme (same frame as SelectRow and the
+// DropdownMenu item row). Suggestion-list concerns stay local: cursor,
+// gap, vertical padding, and the form-input color ramp.
 const MentionSuggestionItem = styled(XStack, {
-  padding: "$3",
-  alignItems: "center",
+  name: "MentionSuggestionItem",
+  ...menuRowFrame,
+  paddingVertical: "$2",
+  gap: "$2",
   cursor: "pointer",
   hoverStyle: { backgroundColor: formInputColors.background.focus },
   variants: {
     selected: {
-      true: { backgroundColor: formInputColors.background.base },
+      true: { backgroundColor: formInputColors.background.focus },
       false: { backgroundColor: "transparent" },
     },
   } as const,
 });
 
+// LC-08: fixed leading slot so avatar / initials / missing-media rows share
+// one text-column left edge (Avatar size="$2" ≈ 28px).
+const MEDIA_SLOT = 28;
+
 export function MentionInput<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -113,11 +138,12 @@ export function MentionInput<
     defaultValue,
     form,
     mentions = [],
-    placeholder = "Type @ to mention someone",
+    placeholder = t("Type @ to mention someone"),
     minHeight: minHeightProp,
     maxHeight: maxHeightProp,
     autoResize = false,
     onMentionSelect,
+    onChange,
     onTextChange,
     textAreaProps,
     mode,
@@ -209,6 +235,12 @@ export function MentionInput<
     [showSuggestions, currentTrigger, searchQuery, getFilteredSuggestions],
   );
   const hasSuggestions = suggestions.length > 0;
+  // LC-08: uniform slot decision is per-list — if any visible row has media,
+  // all rows reserve the slot; an all-text list (e.g. hashtags) has none.
+  const suggestionsHaveMedia = useMemo(
+    () => suggestions.some((item) => Boolean(item.avatar)),
+    [suggestions],
+  );
 
   const panel = useFloatingPanel({
     open: hasSuggestions,
@@ -258,11 +290,43 @@ export function MentionInput<
     [checkForTrigger],
   );
 
+  // ── 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;
+  }, []);
+
   const handleTextChange = useCallback(
     (newText: string) => {
       const oldText = text;
-      const editPosition = prevCursorRef.current;
       const lengthDiff = newText.length - oldText.length;
+      // On web the RN onSelectionChange callback never fires, so read the
+      // caret straight off the DOM textarea (already updated by input time)
+      const webElement = getWebTextAreaElement();
+      const domCaret =
+        webElement && typeof webElement.selectionStart === "number"
+          ? webElement.selectionStart
+          : null;
+      const editPosition =
+        domCaret !== null ? Math.max(0, domCaret - Math.max(0, lengthDiff)) : prevCursorRef.current;
 
       if (lengthDiff !== 0) {
         setMentionList((prev) =>
@@ -286,15 +350,18 @@ export function MentionInput<
       }
 
       setText(newText);
-      const estimatedCursor = Math.max(
-        0,
-        Math.min(editPosition + Math.max(0, lengthDiff), newText.length),
-      );
+      const estimatedCursor =
+        domCaret !== null
+          ? domCaret
+          : Math.max(0, Math.min(editPosition + Math.max(0, lengthDiff), newText.length));
+      prevCursorRef.current = estimatedCursor;
       setCursorPosition(estimatedCursor);
       updateTriggerState(newText, estimatedCursor);
+      // Canonical `onChange` and the alias `onTextChange` both fire (single emit).
+      onChange?.(newText);
       onTextChange?.(newText);
     },
-    [text, updateTriggerState, onTextChange],
+    [text, updateTriggerState, onChange, onTextChange, getWebTextAreaElement],
   );
 
   const handleSelectionChange = useCallback(
@@ -309,6 +376,17 @@ export function MentionInput<
     [text, updateTriggerState],
   );
 
+  // Web caret tracking: the DOM `select` event fires on every caret move
+  // (clicks, arrow keys, typing), unlike RN's onSelectionChange
+  const handleWebSelect = useCallback(() => {
+    const el = getWebTextAreaElement();
+    if (!el || typeof el.selectionStart !== "number") return;
+    const position = el.selectionStart;
+    prevCursorRef.current = position;
+    setCursorPosition(position);
+    updateTriggerState(el.value, position);
+  }, [getWebTextAreaElement, updateTriggerState]);
+
   const insertMention = useCallback(
     (item: MentionItem) => {
       if (!currentTrigger) return;
@@ -347,7 +425,15 @@ export function MentionInput<
       setCurrentTrigger(null);
       prevQueryRef.current = "";
       onMentionSelect?.(item, currentTrigger);
-      setTimeout(() => textAreaRef.current?.focus(), 0);
+      setTimeout(() => {
+        const el = getWebTextAreaElement();
+        if (el) {
+          el.focus();
+          el.setSelectionRange(newCursorPos, newCursorPos);
+        } else {
+          textAreaRef.current?.focus();
+        }
+      }, 0);
     },
     [
       text,
@@ -357,6 +443,7 @@ export function MentionInput<
       triggerMap,
       mentionList,
       onMentionSelect,
+      getWebTextAreaElement,
     ],
   );
 
@@ -389,12 +476,21 @@ export function MentionInput<
     [showSuggestions, currentTrigger, suggestions, selectedIndex, insertMention],
   );
 
+  const itemRefs = useRef<Array<HTMLElement | null>>([]);
+
+  // Keep the keyboard-active row in view by measuring the real row, same as
+  // Select's controlled-scrolling adjustment (no estimated item height).
   useEffect(() => {
-    if (hasSuggestions && panel.refs.floating.current) {
-      panel.refs.floating.current.scrollTo?.({
-        top: Math.max(0, (selectedIndex - 2) * estimatedItemHeight),
-        behavior: "smooth",
-      });
+    if (!hasSuggestions) return;
+    const floating = panel.refs.floating.current;
+    const item = itemRefs.current[selectedIndex];
+    if (!floating || !item?.getBoundingClientRect) return;
+    const containerRect = floating.getBoundingClientRect();
+    const itemRect = item.getBoundingClientRect();
+    if (itemRect.bottom > containerRect.bottom) {
+      floating.scrollTop += itemRect.bottom - containerRect.bottom;
+    } else if (itemRect.top < containerRect.top) {
+      floating.scrollTop -= containerRect.top - itemRect.top;
     }
   }, [selectedIndex, hasSuggestions, panel.refs.floating]);
 
@@ -423,30 +519,6 @@ export function MentionInput<
     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 => {
@@ -551,12 +623,13 @@ export function MentionInput<
       borderRadius={panel.dropdownRadius}
       borderWidth={panel.hasBorder ? panel.knobProps.borderRadius.borderWidth : 0}
       borderColor={panel.hasBorder ? formInputColors.border.focus : "transparent"}
-      paddingVertical={0}
+      // LC-01: container owns only its border — zero padding on all four sides.
+      padding={0}
       maxHeight={suggestionsMaxHeight}
       minWidth={suggestionsMinWidth}
       role={"listbox" as "list"}
       id={suggestionListId}
-      aria-label="Suggestions"
+      aria-label={t("Suggestions")}
     >
       <ScrollArrow
         direction="up"
@@ -564,41 +637,65 @@ export function MentionInput<
         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 && (
+      {/* LC-01: rows are direct children of the scroll container — no padded
+          wrapper, the container owns only its border. */}
+      {suggestions.map((item, index) => {
+        const optionId = `${id}-option-${item.id}`;
+        return (
+          <MentionSuggestionItem
+            key={item.id}
+            ref={(node: any) => {
+              itemRefs.current[index] = node;
+            }}
+            selected={index === selectedIndex}
+            onPress={() => handleSuggestionPress(item)}
+            onMouseEnter={() => setSelectedIndex(index)}
+            role="option"
+            id={optionId}
+            aria-selected={index === selectedIndex}
+          >
+            {/* LC-08 MEDIA-SLOT-ROW: when any row in the list has media, every
+                row reserves the same fixed slot (initials fallback, centered)
+                so the text columns share one left edge. */}
+            {suggestionsHaveMedia && (
+              <YStack
+                width={MEDIA_SLOT}
+                height={MEDIA_SLOT}
+                alignItems="center"
+                justifyContent="center"
+                flexShrink={0}
+              >
                 <Avatar size="$2" circular>
-                  <Avatar.Image src={item.avatar} />
-                  <Avatar.Fallback backgroundColor={formInputColors.background.focus}>
-                    <Text>{item.display[0]}</Text>
+                  {item.avatar ? <Avatar.Image src={item.avatar} /> : null}
+                  <Avatar.Fallback
+                    backgroundColor={formInputColors.background.focus}
+                    justifyContent="center"
+                    alignItems="center"
+                  >
+                    <Text fontSize={helperFontSizeMap[knobProps.sizeToken as string] ?? "$2"}>
+                      {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>
+            )}
+            <YStack flex={1} minWidth={0}>
+              <Text fontSize={knobProps.sizeToken} {...knobProps.body} fontWeight="600">
+                {item.display}
+              </Text>
+              {item.description && (
+                <Text
+                  fontSize={helperFontSizeMap[knobProps.sizeToken as string] ?? "$2"}
+                  color={formCommonColors.muted}
+                  {...knobProps.body}
+                >
+                  {item.description}
+                </Text>
+              )}
+            </YStack>
+          </MentionSuggestionItem>
+        );
+      })}
       <ScrollArrow
         direction="down"
         scrollRef={panel.refs.floating}
@@ -640,6 +737,7 @@ export function MentionInput<
       textAreaRef={textAreaRef}
       textAreaProps={{
         onSelectionChange: handleSelectionChange,
+        ...(isWeb ? { onSelect: handleWebSelect } : {}),
         onKeyDown: handleKeyDown as any,
         "aria-haspopup": "listbox",
         "aria-expanded": hasSuggestions,

package/src/fields/OTPInput/OtpInput.stories.tsx

@@ -157,7 +157,6 @@ export const Interactive: Story = {
       const [value, setValue] = useState("");
       return (
         <YStack gap="$4" maxWidth={400}>
-          {/* @ts-expect-error controlled mode typing mismatch */}
           <OTPInput label="Enter Code" length={6} value={value} onChange={setValue} />
           <Text>Current value: {value || "Empty"}</Text>
         </YStack>
@@ -209,3 +208,8 @@ export const AutoSubmit: Story = {
     return <AutoSubmitDemo />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the cell row anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Verification Code", skeleton: true },
+};