@multiplatform.one/forms 6.6.0 → 7.0.0

package/src/fields/ImageField/index.tsx

@@ -1,19 +1,25 @@
 /**
- * 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.
+ * ImageField — Frappe Attach Image: one preview frame that attaches, replaces,
+ * and drops; Remove is a sibling action. LC-71: keyboard ring on the frame
+ * (outer painted box) and a second ring on Remove — never on the hidden input.
  */
 
-import { ImageIcon, XIcon } from "@phosphor-icons/react";
-import type { MouseEvent, ReactNode } from "react";
+import { ImageSquareIcon, XIcon } from "@phosphor-icons/react";
+import {
+  ensureFocusVisibleRing,
+  wasKeyboardFocus,
+  type DisabledSurfaceProps,
+  type KnobProps,
+} from "@multiplatform.one/theme";
+import type { DragEvent, ReactNode } from "react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { LabelProps, SizeTokens } from "tamagui";
-import { Image, isWeb, Text, View, styled } from "tamagui";
-import { Field, FieldLayout } from "../../fieldLayout";
+import { Image, Text, View, YStack, isWeb, styled } from "tamagui";
+import { Button } from "../../Button";
+import { Field, FieldLayout, useFieldA11y, useFieldDescribedBy } from "../../fieldLayout";
 import { Skeleton } from "../../Skeleton";
 import { t } from "../../shared/t";
-import { formCardColors, formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { formCommonColors, formInputColors } from "../../shared/colorRamps";
 import {
   clampRadiusForControl,
   getFieldError,
@@ -23,6 +29,9 @@ import {
 } from "../../shared/utils";
 import type { AnyFormApi } from "../../types";
 
+const IMAGE_EXT = /\.(avif|bmp|gif|heic|heif|jpe?g|png|svg|webp)$/i;
+const CAPTION_MIN_EDGE = 56;
+
 export interface ImageFieldProps {
   name?: string;
   form?: AnyFormApi;
@@ -55,259 +64,330 @@ export interface ImageFieldProps {
   imageWidth?: number;
   /** Height of the image area (default: 48) */
   imageHeight?: number;
-  /** Whether to show a remove button when there's an image */
+  /** Whether to show a remove action when there's an image */
   showRemove?: boolean;
-  /** Placeholder text when no image */
+  /** Placeholder text when no image. Empty string hides the caption. */
   placeholder?: string;
+  /** How the preview fits the frame (Frappe Attach Image uses contain for logos). */
+  objectFit?: "cover" | "contain" | "fill" | "none";
   /** When true, renders a skeleton placeholder instead of the image field */
   skeleton?: boolean;
-  /** When true, uses compact sizing */
+  /** When true, applies compact density (tighter layout gaps; control size unchanged) */
   compact?: boolean;
 }
 
-const ImageContainer = styled(View, {
-  name: "ImageFieldContainer",
+const ImageFrame = styled(View, {
+  name: "ImageFieldFrame",
   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,
+  outlineWidth: 0,
+  focusStyle: { outlineWidth: 0 },
+  focusVisibleStyle: { outlineWidth: 0 },
 });
 
-const RemoveButton = styled(View, {
-  name: "ImageFieldRemove",
-  position: "absolute",
-  top: -6,
-  insetInlineEnd: -6,
-  width: 18,
-  height: 18,
-  borderRadius: 1000,
-  backgroundColor: formCommonColors.text,
-  alignItems: "center",
-  justifyContent: "center",
-  cursor: "pointer",
-  zIndex: 1,
-  hoverStyle: {
-    backgroundColor: formCommonColors.error,
-  },
-});
+type ImageControlProps = {
+  id: string;
+  label?: ReactNode;
+  currentValue: string | File | null | undefined;
+  errorProp?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  accept: string;
+  maxSize?: number;
+  imageWidth: number;
+  imageHeight: number;
+  showRemove: boolean;
+  placeholder?: string;
+  objectFit: NonNullable<ImageFieldProps["objectFit"]>;
+  cappedRadius: string | number;
+  borderWidth: number;
+  outlined: boolean;
+  elevation: KnobProps["elevation"];
+  transition: KnobProps["transition"];
+  body: KnobProps["body"];
+  gap?: KnobProps["gap"];
+  disabledSurface?: DisabledSurfaceProps;
+  onChange?: (val: string | File | null) => void;
+  onChangeProp?: (val: string | File | null) => void;
+  onValueChange?: (val: string | File | null) => void;
+  onInvalid?: (message: string | undefined) => void;
+  blurHandler?: (...args: any[]) => void;
+};
 
-export function ImageField({
-  name,
-  form: formProp,
-  validators,
+function isImageFile(file: File, accept: string): boolean {
+  if (file.type.startsWith("image/")) return true;
+  if (IMAGE_EXT.test(file.name)) return true;
+  if (!accept) return false;
+  const accepted = accept.split(",").map((type) => type.trim().toLowerCase());
+  const name = file.name.toLowerCase();
+  return accepted.some((type) => {
+    if (type.startsWith(".")) return name.endsWith(type);
+    if (type.endsWith("/*")) return file.type.startsWith(type.slice(0, -1));
+    return file.type === type || file.type.match(type.replace("*", ".*"));
+  });
+}
+
+function ImageControl({
+  id,
   label,
-  labelProps,
-  helperText,
-  error,
+  currentValue,
+  errorProp,
   required,
   disabled,
   readOnly,
-  size,
-  id: idProp,
-  value,
-  defaultValue,
-  onChange: onChangeProp,
-  onValueChange,
-  onBlur,
-  accept = "image/*",
+  accept,
   maxSize,
-  imageWidth = 48,
-  imageHeight = 48,
-  showRemove = true,
+  imageWidth,
+  imageHeight,
+  showRemove,
   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);
-
+  objectFit,
+  cappedRadius,
+  borderWidth,
+  outlined,
+  elevation,
+  transition,
+  body,
+  gap,
+  disabledSurface,
+  onChange,
+  onChangeProp,
+  onValueChange,
+  onInvalid,
+  blurHandler,
+}: ImageControlProps) {
+  const describedBy = useFieldDescribedBy();
+  const fieldA11y = useFieldA11y();
   const [previewUrl, setPreviewUrl] = useState<string | null>(null);
-  const [validationError, setValidationError] = useState<string | undefined>();
+  const [broken, setBroken] = useState(false);
+  const [kbFrameFocus, setKbFrameFocus] = useState(false);
+  const [isDragOver, setIsDragOver] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
-  const resolvedValue = value !== undefined ? value : defaultValue;
+  const dragDepthRef = useRef(0);
+  const canInteract = !disabled && !readOnly;
 
-  // Object URLs must be created in an effect — calling setState inside render
-  // (previous getDisplayUrl) infinite-looped whenever value was a File
-  // (SB-T2-07: DataTableCell image upload crash).
   useEffect(() => {
-    if (!(resolvedValue instanceof File) || !isWeb) {
+    setBroken(false);
+    if (!(currentValue instanceof File) || !isWeb) {
       setPreviewUrl(null);
       return;
     }
-    const url = URL.createObjectURL(resolvedValue);
+    const url = URL.createObjectURL(currentValue);
     setPreviewUrl(url);
     return () => URL.revokeObjectURL(url);
-  }, [resolvedValue]);
+  }, [currentValue]);
 
-  // Pure — never mutates state. File values resolve via previewUrl from the effect.
-  const getDisplayUrl = useCallback(
-    (val: string | File | null | undefined): string | null => {
-      if (!val) return null;
-      if (typeof val === "string") return val;
-      if (val instanceof File) return previewUrl;
-      return null;
+  const displayUrl =
+    typeof currentValue === "string" && currentValue
+      ? currentValue
+      : currentValue instanceof File
+        ? previewUrl
+        : null;
+  const hasValue =
+    currentValue instanceof File || (typeof currentValue === "string" && !!currentValue);
+  const hasPreview = !!displayUrl && !broken;
+  const minEdge = Math.min(imageWidth, imageHeight);
+  const caption = placeholder === undefined ? t("Add image") : placeholder;
+  const showCaption =
+    Boolean(caption) && !hasPreview && (placeholder !== undefined || minEdge >= CAPTION_MIN_EDGE);
+  const iconSize = Math.max(14, Math.min(32, Math.round(minEdge * 0.28)));
+
+  const emit = useCallback(
+    (next: string | File | null) => {
+      onInvalid?.(undefined);
+      onChange?.(next);
+      onChangeProp?.(next);
+      onValueChange?.(next);
+      blurHandler?.();
     },
-    [previewUrl],
+    [onChange, onChangeProp, onValueChange, onInvalid, blurHandler],
   );
 
   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`;
+        return t("Image must be less than {{size}}MB", { size: sizeMB });
       }
-      if (!file.type.startsWith("image/")) {
-        return "File must be an image";
+      if (!isImageFile(file, accept)) {
+        return t("File must be an image");
       }
       return null;
     },
-    [maxSize],
+    [maxSize, accept],
   );
 
-  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);
+  const applyFile = useCallback(
+    (file: File) => {
+      const invalid = validateFile(file);
+      if (invalid) {
+        setBroken(false);
+        onInvalid?.(invalid);
         return;
       }
+      setBroken(false);
+      emit(file);
+    },
+    [validateFile, emit, onInvalid],
+  );
 
-      setValidationError(undefined);
-      onChange?.(file);
-      // Canonical `onChange` and the alias `onValueChange` both fire once
-      // (same reconciliation as Switch).
-      onChangeProp?.(file);
-      onValueChange?.(file);
-      blurHandler?.();
+  const openFileDialog = useCallback(() => {
+    if (!canInteract) return;
+    fileInputRef.current?.click();
+  }, [canInteract]);
+
+  const isInteractiveChild = useCallback((e: { target: unknown; currentTarget: unknown }) => {
+    const target = e.target as HTMLElement | null;
+    const current = e.currentTarget as HTMLElement | null;
+    if (!target?.closest || !current) return false;
+    const interactive = target.closest('button, a, input, select, textarea, [role="button"]');
+    return !!interactive && interactive !== current;
+  }, []);
+
+  const handleFramePress = useCallback(
+    (e: { target: unknown; currentTarget: unknown }) => {
+      if (isInteractiveChild(e)) return;
+      openFileDialog();
     },
-    [validateFile, onChangeProp, onValueChange],
+    [isInteractiveChild, openFileDialog],
+  );
+
+  const handleFrameKeyDown = useCallback(
+    (e: { target: unknown; currentTarget: unknown; key?: string; preventDefault?: () => void }) => {
+      if (e.target !== e.currentTarget) return;
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault?.();
+        openFileDialog();
+      }
+    },
+    [openFileDialog],
   );
 
   const handleRemove = useCallback(
-    (
-      e: MouseEvent,
-      onChange?: (val: string | File | null) => void,
-      blurHandler?: (...args: any[]) => void,
-    ) => {
-      e.stopPropagation();
-      // Object-URL revoke happens in the preview effect cleanup when value clears.
-      onChange?.(null);
-      onChangeProp?.(null);
-      onValueChange?.(null);
-      blurHandler?.();
+    (e?: { stopPropagation?: () => void }) => {
+      e?.stopPropagation?.();
+      setBroken(false);
+      emit(null);
     },
-    [onChangeProp, onValueChange],
+    [emit],
   );
 
-  const openFileDialog = useCallback(() => {
-    if (disabled || readOnly) return;
-    fileInputRef.current?.click();
-  }, [disabled, readOnly]);
+  const handleDragEnter = useCallback(
+    (e: DragEvent) => {
+      e.preventDefault();
+      if (!canInteract) return;
+      dragDepthRef.current += 1;
+      setIsDragOver(true);
+    },
+    [canInteract],
+  );
 
-  // Render skeleton placeholder
-  if (skeleton) {
-    return (
-      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
-        <Skeleton variant="rounded" width={imageWidth} height={imageHeight} />
-      </FieldLayout>
-    );
-  }
+  const handleDragOver = useCallback((e: DragEvent) => {
+    e.preventDefault();
+  }, []);
 
-  const canInteract = !disabled && !readOnly;
+  const handleDragLeave = useCallback((e: DragEvent) => {
+    e.preventDefault();
+    dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+    if (dragDepthRef.current === 0) setIsDragOver(false);
+  }, []);
 
-  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;
+  const handleDrop = useCallback(
+    (e: DragEvent) => {
+      e.preventDefault();
+      dragDepthRef.current = 0;
+      setIsDragOver(false);
+      if (!canInteract) return;
+      const file = e.dataTransfer.files?.[0];
+      if (file) applyFile(file);
+    },
+    [canInteract, applyFile],
+  );
 
-    return (
-      <ImageContainer
+  const frameBorderWidth = isDragOver && canInteract ? Math.max(borderWidth, 2) : borderWidth;
+  const frameBorderColor =
+    errorProp || (isDragOver && canInteract)
+      ? errorProp
+        ? formCommonColors.error
+        : formCommonColors.text
+      : formInputColors.border.base;
+  const altText =
+    typeof label === "string" && label ? label : fieldA11y?.label || t("Selected image");
+  const emptyName =
+    typeof label === "string" && label ? t("{{label}}: add image", { label }) : t("Add image");
+
+  return (
+    <YStack alignItems="flex-start" {...(gap ?? { gap: "$2" })}>
+      <ImageFrame
+        id={id}
         width={imageWidth}
         height={imageHeight}
         borderRadius={cappedRadius}
-        interactive={canInteract}
-        hasImage={hasImage}
-        disabledState={!!disabled}
-        onPress={canInteract ? openFileDialog : undefined}
-        {...(errorProp ? { borderColor: formCommonColors.error } : undefined)}
+        borderStyle={hasPreview ? "solid" : "dashed"}
+        borderWidth={frameBorderWidth}
+        borderColor={frameBorderColor}
+        backgroundColor={outlined || hasPreview ? "transparent" : formInputColors.background.base}
+        elevation={elevation}
+        transition={transition}
+        {...(disabled ? disabledSurface : undefined)}
         aria-required={required || undefined}
         aria-invalid={!!errorProp || undefined}
         aria-readonly={readOnly || undefined}
+        aria-disabled={disabled || undefined}
+        aria-describedby={describedBy}
+        {...(!isWeb
+          ? {
+              accessibilityRole: canInteract ? "button" : undefined,
+              accessibilityLabel:
+                fieldA11y?.label ?? (typeof label === "string" ? label : emptyName),
+              accessibilityHint: fieldA11y?.description,
+              accessibilityState: { disabled: !!disabled },
+            }
+          : {})}
+        {...(kbFrameFocus ? ensureFocusVisibleRing({ outlineOffset: -2 }) : undefined)}
+        {...(canInteract
+          ? ({
+              role: "button",
+              tabIndex: 0,
+              cursor: "pointer",
+              onFocus: () => {
+                if (wasKeyboardFocus()) setKbFrameFocus(true);
+              },
+              onBlur: () => setKbFrameFocus(false),
+              ...(label && id ? null : { "aria-label": emptyName }),
+              onPress: handleFramePress,
+              onKeyDown: handleFrameKeyDown,
+              onDragEnter: handleDragEnter,
+              onDragOver: handleDragOver,
+              onDragLeave: handleDragLeave,
+              onDrop: handleDrop,
+            } as any)
+          : {})}
       >
-        {hasImage ? (
-          <>
-            <Image
-              // src (string), not source: the RN source object leaks onto the
-              // DOM <img> as source="[object Object]" on web
-              src={displayUrl}
-              alt={typeof label === "string" && label ? label : t("Selected image")}
-              width={imageWidth}
-              height={imageHeight}
-              objectFit="cover"
-            />
-            {showRemove && canInteract && (
-              <RemoveButton onPress={(e: any) => handleRemove(e, onChange, blurHandler)}>
-                <XIcon size={10} color="var(--color1)" />
-              </RemoveButton>
-            )}
-          </>
+        {hasPreview ? (
+          <Image
+            src={displayUrl as string}
+            alt={altText}
+            width={imageWidth}
+            height={imageHeight}
+            objectFit={objectFit}
+            onError={() => setBroken(true)}
+          />
         ) : (
-          <View alignItems="center" justifyContent="center" gap="$1">
-            <ImageIcon size={16} color="var(--color10)" />
-            {placeholder && (
-              <Text fontSize="$1" color={formCommonColors.muted} textAlign="center">
-                {placeholder}
+          <View alignItems="center" justifyContent="center" gap="$1" padding="$1">
+            <ImageSquareIcon size={iconSize} color="var(--color11)" />
+            {showCaption ? (
+              <Text {...body} color={formCommonColors.muted} textAlign="center" numberOfLines={2}>
+                {hasValue && broken ? t("Image failed to load") : caption}
               </Text>
-            )}
+            ) : hasValue && broken ? (
+              <Text color={formCommonColors.muted} textAlign="center" fontSize="$1">
+                {t("Image failed to load")}
+              </Text>
+            ) : null}
           </View>
         )}
 
@@ -316,16 +396,106 @@ export function ImageField({
             ref={fileInputRef}
             type="file"
             accept={accept}
-            onChange={(e) => handleFileSelect(e.target.files, onChange, blurHandler)}
+            tabIndex={-1}
+            aria-hidden={true}
+            onChange={(e) => {
+              const files = e.target.files;
+              e.target.value = "";
+              if (!files || files.length === 0) return;
+              applyFile(files[0]);
+            }}
             style={{ display: "none" }}
             disabled={!canInteract}
           />
         )}
-      </ImageContainer>
+      </ImageFrame>
+
+      {showRemove && hasValue && canInteract && (
+        <Button
+          chromeless
+          size="$2"
+          icon={XIcon}
+          aria-label={t("Remove image")}
+          onPress={() => handleRemove()}
+        >
+          {t("Remove")}
+        </Button>
+      )}
+    </YStack>
+  );
+}
+
+export function ImageField({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  size,
+  id: idProp,
+  value,
+  defaultValue,
+  onChange: onChangeProp,
+  onValueChange,
+  onBlur,
+  accept = "image/*",
+  maxSize,
+  imageWidth = 48,
+  imageHeight = 48,
+  showRemove = true,
+  placeholder,
+  objectFit = "cover",
+  skeleton,
+  compact,
+}: ImageFieldProps) {
+  const { resolvedForm, knobProps, disabledState, id } = useFormField({
+    form: formProp,
+    id: idProp,
+    compact,
+  });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const cappedRadius = clampRadiusForControl(knobProps.borderRadius.borderRadius, 6);
+  const [validationError, setValidationError] = useState<string | undefined>();
+
+  if (skeleton) {
+    return (
+      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
+        <Skeleton variant="rounded" width={imageWidth} height={imageHeight} />
+      </FieldLayout>
     );
+  }
+
+  const controlProps = {
+    id,
+    label,
+    required,
+    disabled,
+    readOnly,
+    accept,
+    maxSize,
+    imageWidth,
+    imageHeight,
+    showRemove,
+    placeholder,
+    objectFit,
+    cappedRadius,
+    borderWidth: (knobProps.borderRadius.borderWidth as number | undefined) ?? 1,
+    outlined: knobProps.outlined,
+    elevation: knobProps.elevation,
+    transition: knobProps.transition,
+    body: knobProps.body,
+    gap: knobProps.gap,
+    disabledSurface: disabled ? disabledState.surfaceKnobProps : undefined,
+    onChangeProp,
+    onValueChange,
+    onInvalid: setValidationError,
   };
 
-  // Standalone usage (no form)
   if (!resolvedForm || !name) {
     const standaloneError = error ?? validationError;
     return (
@@ -338,18 +508,17 @@ export function ImageField({
         required={required}
         size={size}
         knobProps={knobProps}
-        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
-        // the sibling label/helper readable) — it needs the disabled state.
         disabled={disabled}
       >
-        {/* User callbacks fire once inside handleFileSelect/handleRemove —
-            passing onValueChange as the internal handler double-fired it. */}
-        {renderImageField(value ?? defaultValue, standaloneError, undefined)}
+        <ImageControl
+          {...controlProps}
+          currentValue={value ?? defaultValue}
+          errorProp={standaloneError}
+        />
       </FieldLayout>
     );
   }
 
-  // Form-connected usage
   return (
     <Field
       form={resolvedForm}
@@ -372,17 +541,15 @@ export function ImageField({
             required={required}
             size={size}
             knobProps={knobProps}
-            // LC-40: see standalone branch — FieldLayout carries dimWhole.
             disabled={disabled}
           >
-            {renderImageField(
-              value !== undefined ? value : fieldValue,
-              resolvedError,
-              (val) => {
-                field.handleChange(val as any);
-              },
-              blurHandler,
-            )}
+            <ImageControl
+              {...controlProps}
+              currentValue={value !== undefined ? value : fieldValue}
+              errorProp={resolvedError}
+              onChange={(val) => field.handleChange(val as any)}
+              blurHandler={blurHandler}
+            />
           </FieldLayout>
         );
       }}