@multiplatform.one/forms 6.0.0

package/src/shared/useDragScroll.ts

@@ -0,0 +1,120 @@
+import {
+  type CSSProperties,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+  useCallback,
+  useRef,
+} from "react";
+
+export interface UseDragScrollOptions {
+  /** Direction of scroll - vertical or horizontal */
+  direction?: "vertical" | "horizontal";
+  /** Multiplier for drag distance (default: 1) */
+  sensitivity?: number;
+  /** Callback when drag starts */
+  onDragStart?: () => void;
+  /** Callback when drag ends */
+  onDragEnd?: () => void;
+}
+
+export interface UseDragScrollReturn {
+  /** Ref to attach to the scrollable container */
+  scrollRef: RefObject<HTMLElement | null>;
+  /** Props to spread on the scrollable container */
+  dragProps: {
+    onPointerDown: (e: ReactPointerEvent) => void;
+    style: CSSProperties;
+  };
+}
+
+/**
+ * Hook to enable drag-to-scroll behavior on a scrollable container.
+ * Allows users to click and drag to scroll the content.
+ */
+export function useDragScroll(options: UseDragScrollOptions = {}): UseDragScrollReturn {
+  const { direction = "vertical", sensitivity = 1, onDragStart, onDragEnd } = options;
+
+  const scrollRef = useRef<HTMLElement | null>(null);
+  const isDragging = useRef(false);
+  const startPos = useRef(0);
+  const startScroll = useRef(0);
+  const hasMoved = useRef(false);
+
+  const handlePointerMove = useCallback(
+    (e: PointerEvent) => {
+      if (!isDragging.current || !scrollRef.current) return;
+
+      const currentPos = direction === "vertical" ? e.clientY : e.clientX;
+      const delta = (startPos.current - currentPos) * sensitivity;
+
+      if (Math.abs(delta) > 3) {
+        hasMoved.current = true;
+      }
+
+      if (direction === "vertical") {
+        scrollRef.current.scrollTop = startScroll.current + delta;
+      } else {
+        scrollRef.current.scrollLeft = startScroll.current + delta;
+      }
+    },
+    [direction, sensitivity],
+  );
+
+  const handlePointerUp = useCallback(() => {
+    if (isDragging.current) {
+      isDragging.current = false;
+      document.removeEventListener("pointermove", handlePointerMove);
+      document.removeEventListener("pointerup", handlePointerUp);
+      document.body.style.userSelect = "";
+      document.body.style.cursor = "";
+
+      if (hasMoved.current) {
+        onDragEnd?.();
+      }
+    }
+  }, [handlePointerMove, onDragEnd]);
+
+  const handlePointerDown = useCallback(
+    (e: ReactPointerEvent) => {
+      // Only handle primary button (left click)
+      if (e.button !== 0) return;
+      // Don't interfere with interactive elements
+      const target = e.target as HTMLElement;
+      if (
+        target.closest("button") ||
+        target.closest("input") ||
+        target.closest("a") ||
+        target.closest('[role="option"]') ||
+        target.closest('[role="button"]')
+      ) {
+        return;
+      }
+
+      isDragging.current = true;
+      hasMoved.current = false;
+      startPos.current = direction === "vertical" ? e.clientY : e.clientX;
+      startScroll.current =
+        direction === "vertical"
+          ? (scrollRef.current?.scrollTop ?? 0)
+          : (scrollRef.current?.scrollLeft ?? 0);
+
+      document.addEventListener("pointermove", handlePointerMove);
+      document.addEventListener("pointerup", handlePointerUp);
+      document.body.style.userSelect = "none";
+
+      onDragStart?.();
+    },
+    [direction, handlePointerMove, handlePointerUp, onDragStart],
+  );
+
+  return {
+    scrollRef,
+    dragProps: {
+      onPointerDown: handlePointerDown,
+      style: {
+        cursor: "grab",
+        touchAction: direction === "vertical" ? "pan-x" : "pan-y",
+      },
+    },
+  };
+}

package/src/shared/useWheelIncrement.ts

@@ -0,0 +1,79 @@
+import { type RefObject, useCallback, useEffect, useRef } from "react";
+
+export interface UseWheelIncrementOptions {
+  /** Function to call when incrementing */
+  onIncrement: () => void;
+  /** Function to call when decrementing */
+  onDecrement: () => void;
+  /** Whether the input is disabled */
+  disabled?: boolean;
+  /** Whether the input is read-only */
+  readOnly?: boolean;
+  /** Minimum delta to trigger increment/decrement (helps with trackpad smoothness) */
+  threshold?: number;
+}
+
+export interface UseWheelIncrementReturn {
+  /** Props to spread onto the wrapper element (includes ref) */
+  wheelProps: { ref: RefObject<HTMLDivElement | null> };
+}
+
+/**
+ * Hook to enable mouse wheel increment/decrement on number inputs and similar controls.
+ * Scrolling up increments, scrolling down decrements.
+ *
+ * Uses native event listener with { passive: false } to allow preventDefault(),
+ * which is required because browsers treat wheel events as passive by default.
+ */
+export function useWheelIncrement(options: UseWheelIncrementOptions): UseWheelIncrementReturn {
+  const { onIncrement, onDecrement, disabled, readOnly, threshold = 1 } = options;
+  const ref = useRef<HTMLDivElement | null>(null);
+
+  // Accumulate delta for smooth trackpad scrolling
+  const accumulatedDelta = useRef(0);
+  const lastWheelTime = useRef(0);
+
+  const handleWheel = useCallback(
+    (e: WheelEvent) => {
+      if (disabled || readOnly) return;
+
+      // Prevent page scroll - this only works with { passive: false }
+      e.preventDefault();
+      e.stopPropagation();
+
+      const now = Date.now();
+      // Reset accumulated delta if there's been a pause
+      if (now - lastWheelTime.current > 150) {
+        accumulatedDelta.current = 0;
+      }
+      lastWheelTime.current = now;
+
+      // Accumulate the delta
+      accumulatedDelta.current += e.deltaY;
+
+      // Check if we've crossed the threshold
+      if (Math.abs(accumulatedDelta.current) >= threshold * 30) {
+        if (accumulatedDelta.current > 0) {
+          onDecrement();
+        } else {
+          onIncrement();
+        }
+        accumulatedDelta.current = 0;
+      }
+    },
+    [disabled, readOnly, onIncrement, onDecrement, threshold],
+  );
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    // Must use { passive: false } to allow preventDefault() on wheel events
+    element.addEventListener("wheel", handleWheel, { passive: false });
+    return () => {
+      element.removeEventListener("wheel", handleWheel);
+    };
+  }, [handleWheel]);
+
+  return { wheelProps: { ref } };
+}

package/src/shared/utils.spec.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  clampRadiusForControl,
+  clampRadiusForLargeComponent,
+  getOTPCellRadius,
+  stripRadiusFromStateProps,
+  clampRadiusInStateProps,
+  getFieldError,
+  mergeFieldHandler,
+} from "./utils";
+
+describe("clampRadiusForControl", () => {
+  it('returns "$4" fallback when undefined', () => {
+    expect(clampRadiusForControl(undefined)).toBe("$4");
+  });
+
+  it("returns 0 for $0", () => {
+    expect(clampRadiusForControl("$0")).toBe(0);
+  });
+
+  it("passes through tokens within the limit", () => {
+    expect(clampRadiusForControl("$2")).toBe("$2");
+    expect(clampRadiusForControl("$4")).toBe("$4");
+    expect(clampRadiusForControl("$6")).toBe("$6");
+  });
+
+  it("clamps tokens exceeding the max", () => {
+    expect(clampRadiusForControl("$12")).toBe("$6");
+    expect(clampRadiusForControl("$8")).toBe("$6");
+  });
+
+  it("uses custom max token number", () => {
+    expect(clampRadiusForControl("$5", 4)).toBe("$4");
+    expect(clampRadiusForControl("$3", 4)).toBe("$3");
+  });
+
+  it("passes through non-token strings", () => {
+    expect(clampRadiusForControl("10px")).toBe("10px");
+  });
+});
+
+describe("clampRadiusForLargeComponent", () => {
+  it('returns "$3" fallback when undefined', () => {
+    expect(clampRadiusForLargeComponent(undefined)).toBe("$3");
+  });
+
+  it("returns 0 for $0", () => {
+    expect(clampRadiusForLargeComponent("$0")).toBe(0);
+  });
+
+  it("clamps to $4 by default", () => {
+    expect(clampRadiusForLargeComponent("$12")).toBe("$4");
+    expect(clampRadiusForLargeComponent("$6")).toBe("$4");
+  });
+
+  it("passes through tokens within the limit", () => {
+    expect(clampRadiusForLargeComponent("$2")).toBe("$2");
+    expect(clampRadiusForLargeComponent("$4")).toBe("$4");
+  });
+});
+
+describe("getOTPCellRadius", () => {
+  it("returns 1000 for $12 (full/circular)", () => {
+    expect(getOTPCellRadius("$12")).toBe(1000);
+  });
+
+  it("clamps other tokens via clampRadiusForControl", () => {
+    expect(getOTPCellRadius("$4")).toBe("$4");
+    expect(getOTPCellRadius("$8")).toBe("$6");
+  });
+
+  it("returns $4 fallback for undefined", () => {
+    expect(getOTPCellRadius(undefined)).toBe("$4");
+  });
+});
+
+describe("stripRadiusFromStateProps", () => {
+  it("returns undefined/null props as-is", () => {
+    expect(stripRadiusFromStateProps(undefined)).toBeUndefined();
+  });
+
+  it("returns props unchanged when no borderRadius", () => {
+    const props = { color: "red", opacity: 1 };
+    expect(stripRadiusFromStateProps(props)).toBe(props);
+  });
+
+  it("removes borderRadius and keeps other props", () => {
+    const result = stripRadiusFromStateProps({ borderRadius: "$4", color: "blue" });
+    expect(result).toEqual({ color: "blue" });
+    expect(result).not.toHaveProperty("borderRadius");
+  });
+
+  it("returns undefined when borderRadius was the only prop", () => {
+    expect(stripRadiusFromStateProps({ borderRadius: "$4" })).toBeUndefined();
+  });
+});
+
+describe("clampRadiusInStateProps", () => {
+  it("returns undefined/null props as-is", () => {
+    expect(clampRadiusInStateProps(undefined)).toBeUndefined();
+  });
+
+  it("returns props unchanged when no borderRadius", () => {
+    const props = { color: "red" };
+    expect(clampRadiusInStateProps(props)).toBe(props);
+  });
+
+  it("clamps borderRadius in the props", () => {
+    const result = clampRadiusInStateProps({ borderRadius: "$12", color: "blue" });
+    expect(result).toEqual({ borderRadius: "$6", color: "blue" });
+  });
+
+  it("uses custom max token number", () => {
+    const result = clampRadiusInStateProps({ borderRadius: "$8", color: "blue" }, 4);
+    expect(result).toEqual({ borderRadius: "$4", color: "blue" });
+  });
+});
+
+describe("getFieldError", () => {
+  function makeField(errors: string[]) {
+    return { state: { meta: { errors } } } as any;
+  }
+
+  it("returns propError when provided", () => {
+    expect(getFieldError(makeField(["field error"]), "prop error")).toBe("prop error");
+  });
+
+  it("returns field error when no propError", () => {
+    expect(getFieldError(makeField(["validation failed"]))).toBe("validation failed");
+  });
+
+  it("returns undefined when no errors", () => {
+    expect(getFieldError(makeField([]))).toBeUndefined();
+  });
+
+  it("returns false propError over field error", () => {
+    expect(getFieldError(makeField(["field error"]), false)).toBe(false);
+  });
+});
+
+describe("mergeFieldHandler", () => {
+  it("calls both field handler and custom handler", () => {
+    const fieldBlur = vi.fn();
+    const customHandler = vi.fn();
+    const field = { handleBlur: fieldBlur } as any;
+
+    const merged = mergeFieldHandler(field, "handleBlur", customHandler);
+    merged("arg1", "arg2");
+
+    expect(fieldBlur).toHaveBeenCalledWith("arg1", "arg2");
+    expect(customHandler).toHaveBeenCalledWith("arg1", "arg2");
+  });
+
+  it("works without a custom handler", () => {
+    const fieldChange = vi.fn();
+    const field = { handleChange: fieldChange } as any;
+
+    const merged = mergeFieldHandler(field, "handleChange");
+    merged("value");
+
+    expect(fieldChange).toHaveBeenCalledWith("value");
+  });
+});

package/src/shared/utils.ts

@@ -0,0 +1,232 @@
+import { type ReactNode, useId, useMemo } from "react";
+import type {
+  ElevationStateProps,
+  KnobProps,
+  KnobRecipe,
+  ResolvedKnobs,
+} from "@multiplatform.one/theme";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { SizeTokens } from "tamagui";
+import { getVariableValue, isWeb } from "tamagui";
+import { getSize } from "@tamagui/get-token";
+import { useFormContext } from "../Form";
+import type { AnyFormApi, SimpleFieldApi } from "../types";
+
+/**
+ * Resolve a size token to its pixel value, optionally multiplied by a row count.
+ * e.g. getFieldHeight("$4") → 44, getFieldHeight("$4", 3) → 132
+ */
+export function getFieldHeight(sizeToken: SizeTokens, rows = 1): number {
+  return Math.round(getVariableValue(getSize(sizeToken)) * rows);
+}
+
+function clampRadius(
+  radiusToken: string | undefined,
+  maxTokenNum: number,
+  fallback: string,
+): string | 0 {
+  if (!radiusToken) return fallback;
+  if (radiusToken === "$0") return 0;
+  if (typeof radiusToken === "string" && radiusToken.startsWith("$")) {
+    const num = Number.parseInt(radiusToken.slice(1), 10);
+    return num > maxTokenNum ? `$${maxTokenNum}` : radiusToken;
+  }
+  return radiusToken;
+}
+
+/**
+ * Clamp border radius token so controls (buttons, inputs, checkbox) don't become
+ * fully circular/pill-shaped when knob is "full". Returns token string e.g. "$4".
+ */
+export function clampRadiusForControl(
+  radiusToken: string | undefined,
+  maxTokenNum = 6,
+): string | 0 {
+  return clampRadius(radiusToken, maxTokenNum, "$4");
+}
+
+/**
+ * Clamp border radius for large multi-line components (TextArea, RichTextEditor,
+ * CodeEditor, FileUpload dropzone, etc.). These components should never have
+ * pill-shaped corners as it wastes space and looks odd.
+ *
+ * Max default is $4 which provides subtle rounding without being excessive.
+ */
+export function clampRadiusForLargeComponent(
+  radiusToken: string | undefined,
+  maxTokenNum = 4,
+): string | 0 {
+  return clampRadius(radiusToken, maxTokenNum, "$3");
+}
+
+/**
+ * For OTP input cells: when knob radius is "full" ($12), use 1000 (circular).
+ * Otherwise clamp to max $6 like other inputs.
+ */
+export function getOTPCellRadius(radiusToken: string | undefined): number | string {
+  if (radiusToken === "$12") return 1000;
+  return clampRadiusForControl(radiusToken, 6) as string;
+}
+
+/**
+ * Build elevation props for a wrapper View around HOC-based components.
+ *
+ * Tamagui's create* HOC chains (createCheckbox, createSwitch, etc.) swallow
+ * the elevation variant. On web Tamagui's `elevation` prop doesn't reliably
+ * produce shadows on plain Views, so we emit raw `boxShadow` via `style`.
+ * On native we use standard RN shadow props.
+ */
+
+const webShadow: Record<string, string> = {
+  $1: "0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)",
+  $2: "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)",
+  $4: "0 10px 20px rgba(0,0,0,0.15), 0 3px 6px rgba(0,0,0,0.10)",
+};
+
+const nativeShadow: Record<string, Record<string, any>> = {
+  $1: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.12,
+    shadowRadius: 3,
+    elevation: 2,
+  },
+  $2: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 3 },
+    shadowOpacity: 0.15,
+    shadowRadius: 6,
+    elevation: 4,
+  },
+  $4: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 10 },
+    shadowOpacity: 0.15,
+    shadowRadius: 20,
+    elevation: 8,
+  },
+};
+
+function elevationToProps(token: string | undefined): Record<string, any> {
+  if (!token) return {};
+  if (isWeb) return { style: { boxShadow: webShadow[token] || webShadow["$2"] } };
+  return nativeShadow[token] || nativeShadow["$2"];
+}
+
+export function getElevationWrapperProps(
+  knobProps: KnobProps,
+  elevationRecipe: KnobRecipe<ElevationStateProps>,
+): Record<string, any> {
+  const elevation = knobProps.elevation;
+  if (
+    !elevation &&
+    !elevationRecipe.hoverKnobProps?.elevation &&
+    !elevationRecipe.pressKnobProps?.elevation &&
+    !elevationRecipe.focusVisibleKnobProps?.elevation
+  ) {
+    return {};
+  }
+  const props: Record<string, any> = {
+    elevation,
+    overflow: "visible" as const,
+    ...elevationToProps(elevation),
+  };
+  if (elevationRecipe.hoverKnobProps?.elevation) {
+    props.hoverStyle = elevationToProps(elevationRecipe.hoverKnobProps.elevation);
+  }
+  if (elevationRecipe.pressKnobProps?.elevation) {
+    props.pressStyle = elevationToProps(elevationRecipe.pressKnobProps.elevation);
+  }
+  if (elevationRecipe.focusVisibleKnobProps?.elevation) {
+    props.focusVisibleStyle = elevationToProps(elevationRecipe.focusVisibleKnobProps.elevation);
+  }
+  if (knobProps.transition) props.animation = knobProps.transition;
+  return props;
+}
+
+export function useFormField(props: { form?: AnyFormApi; id?: string; compact?: boolean }): {
+  resolvedForm: AnyFormApi | undefined;
+  id: string;
+} & ResolvedKnobs {
+  const formContext = useFormContext();
+  const resolvedForm = (props.form || formContext || undefined) as AnyFormApi | undefined;
+  const resolved = useResolvedKnobs({ compact: props.compact });
+  const generatedId = useId();
+  const id = props.id || generatedId;
+  return { resolvedForm, ...resolved, id };
+}
+
+export function getFieldError(
+  field: SimpleFieldApi<any>,
+  propError?: string | boolean,
+): string | boolean | undefined {
+  const fieldError = field.state.meta.errors.length
+    ? String(field.state.meta.errors[0])
+    : undefined;
+  return propError ?? fieldError;
+}
+
+const defaultIsEmpty = (v: unknown) => v == null || v === "";
+
+export function useResolvedValidators(
+  required: boolean | undefined,
+  validators: Record<string, unknown> | undefined,
+  label?: ReactNode,
+  name?: string,
+  isEmpty: (value: unknown) => boolean = defaultIsEmpty,
+): Record<string, unknown> | undefined {
+  return useMemo(() => {
+    if (!required) return validators;
+    const requiredValidator = ({ value }: { value: unknown }) =>
+      isEmpty(value)
+        ? `${typeof label === "string" ? label : name || "Field"} is required`
+        : undefined;
+    if (!validators) return { onSubmit: requiredValidator };
+    const existingOnSubmit = validators.onSubmit as ((...args: any[]) => any) | undefined;
+    const composedOnSubmit = existingOnSubmit
+      ? ({ value }: { value: unknown }) =>
+          existingOnSubmit({ value }) ?? requiredValidator({ value })
+      : requiredValidator;
+    return { ...validators, onSubmit: composedOnSubmit };
+  }, [required, validators, label, name, isEmpty]);
+}
+
+export function mergeFieldHandler(
+  field: SimpleFieldApi<any>,
+  name: "handleBlur" | "handleChange",
+  handler?: (...args: any[]) => void,
+): (...args: any[]) => void {
+  return (...args: any[]) => {
+    (field[name] as (...args: any[]) => void)(...args);
+    handler?.(...args);
+  };
+}
+
+/**
+ * State props type for control knob recipes.
+ */
+type ControlStateProps = Record<string, any> | undefined;
+
+/**
+ * Strip borderRadius from state props. Use for controls that must maintain
+ * a fixed shape (e.g., Radio buttons are always circular).
+ */
+export function stripRadiusFromStateProps(props: ControlStateProps): ControlStateProps {
+  if (!props || !("borderRadius" in props)) return props;
+  const { borderRadius: _, ...rest } = props;
+  return Object.keys(rest).length > 0 ? rest : undefined;
+}
+
+/**
+ * Clamp borderRadius in state props to a max token value.
+ * Use for controls like Checkbox that can have radius but shouldn't be fully circular.
+ */
+export function clampRadiusInStateProps(
+  props: ControlStateProps,
+  maxTokenNum = 6,
+): ControlStateProps {
+  if (!props || !("borderRadius" in props)) return props;
+  const { borderRadius, ...rest } = props;
+  const clamped = clampRadiusForControl(borderRadius, maxTokenNum);
+  return { ...rest, borderRadius: clamped };
+}

package/src/shared/zIndex.ts

@@ -0,0 +1,71 @@
+/**
+ * Centralized z-index scale for consistent layering across components.
+ *
+ * ## Z-Index Tiers
+ *
+ * | Tier              | Range       | Use Case                                    |
+ * |-------------------|-------------|---------------------------------------------|
+ * | Local             | 1-10        | Stacking within a component (badges, pins) |
+ * | Component         | 100         | Sticky headers, local overlays              |
+ * | Loading           | 1000        | Loading spinners, toasts                    |
+ * | Sheet             | 100000      | Mobile sheets, drawers                      |
+ * | Dropdown          | 200000      | Popovers, select dropdowns, modals          |
+ * | Extension         | 2147483647  | Browser extension injection (max int)       |
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { zIndex } from '../shared/zIndex';
+ *
+ * <View zIndex={zIndex.dropdown}>...</View>
+ * ```
+ */
+
+// Local stacking within a component (badges, pinned columns, scroll arrows)
+export const zLocalBase = 1;
+export const zLocalElevated = 2;
+export const zLocalTop = 10;
+
+// Component-level overlays (sticky table headers, local overlays)
+export const zComponent = 100;
+
+// Loading states, toasts, inline overlays
+export const zLoading = 1000;
+
+// Mobile sheets and drawer overlays
+export const zDrawerOverlay = 99999;
+export const zSheet = 100000;
+
+// Floating dropdowns, popovers, modals (must be above sheets)
+export const zDropdown = 200000;
+
+// Browser extension injection (max safe integer for DOM)
+export const zExtension = 2147483647;
+
+/**
+ * Named z-index constants for common use cases.
+ * Prefer these over raw numbers for consistency.
+ */
+export const zIndex = {
+  // Local stacking
+  localBase: zLocalBase,
+  localElevated: zLocalElevated,
+  localTop: zLocalTop,
+
+  // Component level
+  stickyHeader: zComponent,
+  scrollArrow: zLocalElevated,
+
+  // Loading/toast layer
+  loading: zLoading,
+
+  // Overlay layers
+  drawerOverlay: zDrawerOverlay,
+  sheet: zSheet,
+  dropdown: zDropdown,
+
+  // Special cases
+  extension: zExtension,
+} as const;
+
+export type ZIndexKey = keyof typeof zIndex;