@multiplatform.one/forms 6.0.0

package/src/fields/ImageField/ImageField.stories.tsx

@@ -0,0 +1,214 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { useState } from "react";
+import { YStack, XStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { ImageField } from "./index";
+
+const meta: Meta<typeof ImageField> = {
+  title: "Forms/ImageField",
+  component: ImageField,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "An image upload field that shows a preview when an image exists, or a dashed upload area when empty. Both states have the same dimensions for consistent layout.",
+      },
+    },
+  },
+  argTypes: {
+    label: { control: "text", description: "Field label" },
+    helperText: { control: "text", description: "Helper text below the field" },
+    error: { control: "text", description: "Error message" },
+    required: { control: "boolean", description: "Mark field as required" },
+    disabled: { control: "boolean", description: "Disable image upload" },
+    readOnly: { control: "boolean", description: "Read-only mode" },
+    size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
+    imageWidth: { control: "number", description: "Width of the image area" },
+    imageHeight: { control: "number", description: "Height of the image area" },
+    showRemove: { control: "boolean", description: "Show remove button on image" },
+    placeholder: { control: "text", description: "Placeholder text when no image" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ImageField>;
+
+export const Main: Story = {
+  name: "Main",
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: {
+          avatar: null,
+          logo: null,
+        },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+
+      return (
+        <Form form={form}>
+          <YStack gap="$4">
+            <ImageField
+              {...({
+                label: "Profile Avatar",
+                name: "avatar",
+                helperText: "Upload your profile picture",
+                imageWidth: 64,
+                imageHeight: 64,
+              } as any)}
+            />
+            <ImageField
+              {...({
+                label: "Company Logo",
+                name: "logo",
+                helperText: "Upload your company logo",
+                imageWidth: 120,
+                imageHeight: 60,
+              } as any)}
+            />
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};
+
+export const Standalone: Story = {
+  args: {
+    label: "Upload Image",
+    helperText: "Click to upload an image",
+    imageWidth: 64,
+    imageHeight: 64,
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const WithPlaceholder: Story = {
+  args: {
+    label: "Profile Picture",
+    placeholder: "Upload",
+    imageWidth: 80,
+    imageHeight: 80,
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const WithExistingImage: Story = {
+  args: {
+    label: "Current Avatar",
+    value: "https://picsum.photos/200",
+    imageWidth: 80,
+    imageHeight: 80,
+    helperText: "Click to change image",
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Image",
+    disabled: true,
+    imageWidth: 64,
+    imageHeight: 64,
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: "Read Only",
+    readOnly: true,
+    value: "https://picsum.photos/200",
+    imageWidth: 64,
+    imageHeight: 64,
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const WithError: Story = {
+  args: {
+    label: "Required Image",
+    error: "Please upload an image",
+    required: true,
+    imageWidth: 64,
+    imageHeight: 64,
+  },
+  render: (args) => <ImageField {...args} />,
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <YStack gap="$4">
+      <XStack gap="$4" alignItems="flex-end">
+        <ImageField label="Small (32x32)" imageWidth={32} imageHeight={32} />
+        <ImageField label="Medium (48x48)" imageWidth={48} imageHeight={48} />
+        <ImageField label="Large (64x64)" imageWidth={64} imageHeight={64} />
+        <ImageField label="XL (96x96)" imageWidth={96} imageHeight={96} />
+      </XStack>
+    </YStack>
+  ),
+};
+
+export const RectangularSizes: Story = {
+  render: () => (
+    <YStack gap="$4">
+      <ImageField label="Banner (200x80)" imageWidth={200} imageHeight={80} placeholder="Banner" />
+      <ImageField label="Logo (160x40)" imageWidth={160} imageHeight={40} placeholder="Logo" />
+      <ImageField
+        label="Thumbnail (120x90)"
+        imageWidth={120}
+        imageHeight={90}
+        placeholder="Thumb"
+      />
+    </YStack>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const InteractiveExample = () => {
+      const [image, setImage] = useState<string | File | null>(null);
+      return (
+        <YStack gap="$4">
+          <ImageField
+            label="Upload Image"
+            value={image}
+            onValueChange={(val) => {
+              setImage(val);
+              action("onValueChange")(val);
+            }}
+            imageWidth={80}
+            imageHeight={80}
+            helperText={
+              image
+                ? typeof image === "string"
+                  ? "URL loaded"
+                  : `File: ${image.name}`
+                : "No image selected"
+            }
+          />
+        </YStack>
+      );
+    };
+    return <InteractiveExample />;
+  },
+};
+
+export const NoRemoveButton: Story = {
+  args: {
+    label: "No Remove Button",
+    value: "https://picsum.photos/200",
+    showRemove: false,
+    imageWidth: 64,
+    imageHeight: 64,
+    helperText: "Click image to change",
+  },
+  render: (args) => <ImageField {...args} />,
+};

package/src/fields/ImageField/index.tsx

@@ -0,0 +1,364 @@
+/**
+ * ImageField - Image upload field with preview.
+ *
+ * Shows an image when one exists, otherwise shows a dashed upload area.
+ * Both states have the same dimensions. Clicking triggers file selection.
+ */
+
+import { ImageIcon, XIcon } from "@phosphor-icons/react";
+import type { MouseEvent, ReactNode } from "react";
+import { useCallback, useRef, useState } from "react";
+import type { LabelProps, SizeTokens } from "tamagui";
+import { Image, isWeb, Text, View, styled } from "tamagui";
+import { Field, FieldLayout } from "../../fieldLayout";
+import { Skeleton } from "../../Skeleton";
+import { formCardColors, formCommonColors, formInputColors } from "../../shared/colorRamps";
+import {
+  clampRadiusForControl,
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import type { AnyFormApi } from "../../types";
+
+export interface ImageFieldProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  /** Current value - can be a URL string or File object */
+  value?: string | File | null;
+  defaultValue?: string | File | null;
+  /** Callback when image changes */
+  onValueChange?: (value: string | File | null) => void;
+  onBlur?: (...args: any[]) => void;
+  /** Accepted image types (default: "image/*") */
+  accept?: string;
+  /** Max file size in bytes */
+  maxSize?: number;
+  /** Width of the image area (default: 48) */
+  imageWidth?: number;
+  /** Height of the image area (default: 48) */
+  imageHeight?: number;
+  /** Whether to show a remove button when there's an image */
+  showRemove?: boolean;
+  /** Placeholder text when no image */
+  placeholder?: string;
+  /** When true, renders a skeleton placeholder instead of the image field */
+  skeleton?: boolean;
+  /** When true, uses compact sizing */
+  compact?: boolean;
+}
+
+const ImageContainer = styled(View, {
+  name: "ImageFieldContainer",
+  position: "relative",
+  alignItems: "center",
+  justifyContent: "center",
+  overflow: "hidden",
+
+  variants: {
+    interactive: {
+      true: {
+        cursor: "pointer",
+        hoverStyle: {
+          opacity: 0.9,
+        },
+        pressStyle: {
+          opacity: 0.8,
+        },
+      },
+      false: {
+        cursor: "default",
+      },
+    },
+    hasImage: {
+      true: {
+        borderStyle: "solid",
+        borderWidth: 1,
+        borderColor: formCardColors.border.base,
+      },
+      false: {
+        borderStyle: "dashed",
+        borderWidth: 1,
+        borderColor: formInputColors.border.base,
+        backgroundColor: formInputColors.background.base,
+      },
+    },
+    disabledState: {
+      true: { opacity: 0.5 },
+      false: { opacity: 1 },
+    },
+  } as const,
+});
+
+const RemoveButton = styled(View, {
+  name: "ImageFieldRemove",
+  position: "absolute",
+  top: -6,
+  right: -6,
+  width: 18,
+  height: 18,
+  borderRadius: 1000,
+  backgroundColor: formCommonColors.text,
+  alignItems: "center",
+  justifyContent: "center",
+  cursor: "pointer",
+  zIndex: 1,
+  hoverStyle: {
+    backgroundColor: formCommonColors.error,
+  },
+});
+
+export function ImageField({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  size,
+  id: idProp,
+  value,
+  defaultValue,
+  onValueChange,
+  onBlur,
+  accept = "image/*",
+  maxSize,
+  imageWidth = 48,
+  imageHeight = 48,
+  showRemove = true,
+  placeholder,
+  skeleton,
+  compact,
+}: ImageFieldProps) {
+  const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  // Intentional: extract raw radius token to pass to clampRadiusForControl utility function.
+  // The utility needs the token string (e.g. "$4") to clamp it, not a fragment.
+  const cappedRadius = clampRadiusForControl(knobProps.borderRadius.borderRadius, 6);
+
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+  const [validationError, setValidationError] = useState<string | undefined>();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  // Get display URL from value
+  const getDisplayUrl = useCallback((val: string | File | null | undefined): string | null => {
+    if (!val) return null;
+    if (typeof val === "string") return val;
+    if (val instanceof File && isWeb) {
+      // Create object URL for File preview
+      const url = URL.createObjectURL(val);
+      setPreviewUrl((prev) => {
+        if (prev) URL.revokeObjectURL(prev);
+        return url;
+      });
+      return url;
+    }
+    return null;
+  }, []);
+
+  const validateFile = useCallback(
+    (file: File): string | null => {
+      if (maxSize && file.size > maxSize) {
+        const sizeMB = (maxSize / 1024 / 1024).toFixed(1);
+        return `Image must be less than ${sizeMB}MB`;
+      }
+      if (!file.type.startsWith("image/")) {
+        return "File must be an image";
+      }
+      return null;
+    },
+    [maxSize],
+  );
+
+  const handleFileSelect = useCallback(
+    (
+      files: FileList | null,
+      onChange?: (val: string | File | null) => void,
+      blurHandler?: (...args: any[]) => void,
+    ) => {
+      if (!files || files.length === 0) return;
+
+      const file = files[0];
+      const validationError = validateFile(file);
+
+      if (validationError) {
+        setValidationError(validationError);
+        return;
+      }
+
+      setValidationError(undefined);
+      onChange?.(file);
+      onValueChange?.(file);
+      blurHandler?.();
+    },
+    [validateFile, onValueChange],
+  );
+
+  const handleRemove = useCallback(
+    (
+      e: MouseEvent,
+      onChange?: (val: string | File | null) => void,
+      blurHandler?: (...args: any[]) => void,
+    ) => {
+      e.stopPropagation();
+      if (previewUrl) {
+        URL.revokeObjectURL(previewUrl);
+        setPreviewUrl(null);
+      }
+      onChange?.(null);
+      onValueChange?.(null);
+      blurHandler?.();
+    },
+    [previewUrl, onValueChange],
+  );
+
+  const openFileDialog = useCallback(() => {
+    if (disabled || readOnly) return;
+    fileInputRef.current?.click();
+  }, [disabled, readOnly]);
+
+  // Render skeleton placeholder
+  if (skeleton) {
+    return (
+      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
+        <Skeleton variant="rounded" width={imageWidth} height={imageHeight} />
+      </FieldLayout>
+    );
+  }
+
+  const canInteract = !disabled && !readOnly;
+
+  const renderImageField = (
+    currentValue: string | File | null | undefined,
+    errorProp?: string | boolean,
+    onChange?: (val: string | File | null) => void,
+    blurHandler?: (...args: any[]) => void,
+  ) => {
+    const displayUrl = getDisplayUrl(currentValue);
+    const hasImage = !!displayUrl;
+
+    return (
+      <ImageContainer
+        width={imageWidth}
+        height={imageHeight}
+        borderRadius={cappedRadius}
+        interactive={canInteract}
+        hasImage={hasImage}
+        disabledState={!!disabled}
+        onPress={canInteract ? openFileDialog : undefined}
+        {...(errorProp ? { borderColor: formCommonColors.error } : undefined)}
+        aria-required={required || undefined}
+        aria-invalid={!!errorProp || undefined}
+        aria-readonly={readOnly || undefined}
+      >
+        {hasImage ? (
+          <>
+            <Image
+              source={{ uri: displayUrl }}
+              width={imageWidth}
+              height={imageHeight}
+              objectFit="cover"
+            />
+            {showRemove && canInteract && (
+              <RemoveButton onPress={(e: any) => handleRemove(e, onChange, blurHandler)}>
+                <XIcon size={10} color="var(--color1)" />
+              </RemoveButton>
+            )}
+          </>
+        ) : (
+          <View alignItems="center" justifyContent="center" gap="$1">
+            <ImageIcon size={16} color="var(--color10)" />
+            {placeholder && (
+              <Text fontSize="$1" color={formCommonColors.muted} textAlign="center">
+                {placeholder}
+              </Text>
+            )}
+          </View>
+        )}
+
+        {isWeb && (
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept={accept}
+            onChange={(e) => handleFileSelect(e.target.files, onChange, blurHandler)}
+            style={{ display: "none" }}
+            disabled={!canInteract}
+          />
+        )}
+      </ImageContainer>
+    );
+  };
+
+  // Standalone usage (no form)
+  if (!resolvedForm || !name) {
+    const standaloneError = error ?? validationError;
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={standaloneError}
+        helperText={helperText}
+        required={required}
+        size={size}
+        knobProps={knobProps}
+      >
+        {renderImageField(value ?? defaultValue, standaloneError, onValueChange)}
+      </FieldLayout>
+    );
+  }
+
+  // Form-connected usage
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue as any}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error) ?? validationError;
+        const fieldValue = field.state.value as string | File | null;
+        const blurHandler = mergeFieldHandler(field, "handleBlur", onBlur);
+
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            helperText={helperText}
+            required={required}
+            size={size}
+            knobProps={knobProps}
+          >
+            {renderImageField(
+              value !== undefined ? value : fieldValue,
+              resolvedError,
+              (val) => {
+                field.handleChange(val as any);
+              },
+              blurHandler,
+            )}
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}

package/src/fields/Input/Input.spec.tsx

@@ -0,0 +1,75 @@
+import { fireEvent, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Form } from "../../Form";
+import { Input } from "./index";
+
+describe("Input", () => {
+  describe("without form context", () => {
+    it("renders with label and placeholder", () => {
+      const result = renderWithProviders(
+        <Input label="Name" placeholder="Enter name" name="name" />,
+      );
+      expect(result.findTextElement("Name")).toBeDefined();
+      const input = result.container.querySelector("input");
+      expect(input?.getAttribute("placeholder")).toBe("Enter name");
+    });
+
+    it("renders required label with asterisk", () => {
+      const result = renderWithProviders(<Input label="Required" name="req" required />);
+      const label = result.container.querySelector("label");
+      expect(label?.textContent).toContain("Required");
+      expect(label?.textContent).toContain("*");
+    });
+
+    it("renders with helper text and error", () => {
+      const result = renderWithProviders(
+        <Input label="Email" helperText="Enter your email" error="Invalid email" name="email" />,
+      );
+      // Helper text is hidden when error is present; error takes precedence
+      expect(result.findTextElement("Enter your email")).toBeUndefined();
+      expect(result.findTextElement("Invalid email")).toBeDefined();
+    });
+
+    it("renders disabled state", () => {
+      const result = renderWithProviders(<Input label="Disabled" name="d" disabled />);
+      const input = result.container.querySelector("input");
+      expect(input?.getAttribute("aria-disabled")).toBe("true");
+    });
+
+    it("renders readOnly state", () => {
+      const result = renderWithProviders(
+        <Input label="ReadOnly" name="r" readOnly value="hello" />,
+      );
+      const input = result.container.querySelector("input");
+      expect(input?.getAttribute("aria-readonly")).toBe("true");
+    });
+
+    it("renders skeleton placeholder", () => {
+      const result = renderWithProviders(<Input label="Loading" name="l" skeleton />);
+      expect(result.container.querySelector("input")).toBeNull();
+    });
+
+    it("calls onChangeText when value changes", async () => {
+      const onChangeText = vi.fn();
+      const result = renderWithProviders(
+        <Input label="Text" name="text" onChangeText={onChangeText} />,
+      );
+      const input = result.container.querySelector("input");
+      if (input) fireEvent.change(input, { target: { value: "hello" } });
+      await waitFor(() => expect(onChangeText).toHaveBeenCalledWith("hello"));
+    });
+  });
+
+  describe("with form context", () => {
+    it("renders and validates with tanstack form", async () => {
+      const onSubmit = vi.fn();
+      const result = renderWithProviders(
+        <Form formOptions={{ defaultValues: { name: "" } }} onSubmit={onSubmit} submitText="Submit">
+          <Input name="name" label="Name" required />
+        </Form>,
+      );
+      expect(result.findTextElement("Name")).toBeDefined();
+    });
+  });
+});