@ibanzajoe/uploader 1.5.0 → 1.6.0

package/dist/index.d.cts

@@ -144,9 +144,14 @@ type PickerOptions = {
      */
     fromSources?: Array<'local_file_system' | 'camera'>;
     /**
-     * Preferred camera when the 'camera' source is used.
-     *   'user'        — front / selfie camera (mirrored). Default.
+     * Which camera opens first when the 'camera' source is used.
+     *   'user'        — front / selfie camera (mirrored).
      *   'environment' — rear camera.
+     *
+     * Omitted (recommended) → chosen per device: **rear on phones and tablets**,
+     * front on desktops. The user can flip between them in the camera view
+     * whenever the device exposes more than one camera, so this only sets the
+     * starting side.
      */
     cameraFacingMode?: 'user' | 'environment';
 };
@@ -302,6 +307,12 @@ declare function DropPane({ apikey, apiUrl, security, deliveryProtection, allowe
  * unmount, on capture (to release the camera indicator while reviewing), and on
  * cancel.
  *
+ * Which camera opens first is device-dependent: phones and tablets default to
+ * the REAR camera (people photograph the world, not themselves, from an upload
+ * form), desktops to the only camera they have. A flip control appears whenever
+ * the device actually exposes more than one camera, so the default is a starting
+ * point rather than a constraint. `facingMode` overrides the default outright.
+ *
  * All colors resolve from --uploader-* CSS variables — no hard-coded brand
  * colors. Used by PickerOverlay and DropPane.
  *
@@ -310,6 +321,24 @@ declare function DropPane({ apikey, apiUrl, security, deliveryProtection, allowe
 
 /** True when the current environment can open a camera stream. */
 declare function isCameraSupported(): boolean;
+/** Which physical camera to open. Mirrors the getUserMedia `facingMode` values. */
+type CameraFacingMode = 'user' | 'environment';
+/**
+ * Best-effort "is this a phone or tablet?" check, used only to pick which camera
+ * opens first — never to gate a feature, so a wrong answer costs one tap on the
+ * flip control.
+ *
+ * `userAgentData.mobile` is the reliable signal where it exists (Chromium). The
+ * UA regex covers everything else, and the `maxTouchPoints` clause catches
+ * iPadOS 13+, which reports a desktop Macintosh UA and would otherwise open the
+ * front camera on a tablet.
+ */
+declare function isMobileDevice(): boolean;
+/**
+ * The camera to open when the caller expresses no preference: rear on mobile,
+ * front on everything else.
+ */
+declare function defaultCameraFacingMode(): CameraFacingMode;
 /**
  * Decide whether the picker should offer the camera source, given the picker
  * options and the current environment. The camera is offered when:
@@ -323,8 +352,12 @@ type CameraCaptureProps = {
     onCapture: (file: File) => void;
     /** Called when the user backs out without capturing. */
     onCancel: () => void;
-    /** Which camera to prefer. 'user' = front (mirrored), 'environment' = rear. */
-    facingMode?: 'user' | 'environment';
+    /**
+     * Which camera to open first. 'user' = front (mirrored), 'environment' = rear.
+     * Omitted → `defaultCameraFacingMode()`: rear on mobile, front elsewhere. The
+     * user can still flip when the device has more than one camera.
+     */
+    facingMode?: CameraFacingMode;
     /** Output MIME type for the still. Default 'image/jpeg'. */
     outputType?: string;
     /** Quality 0–1 for lossy output. Default 0.92. */
@@ -401,4 +434,4 @@ type EditImageOptions = {
 };
 declare function editImage(file: File, opts?: EditImageOptions): Promise<File>;
 
-export { CameraCapture, type CameraCaptureProps, type CropArea, DeliveryProtection, DropPane, type DropPaneProps, type EditImageOptions, FileResult, type Flip, ImageEditor, type ImageEditorProps, type PickerFile, type PickerFileState, type PickerOptions, PickerOverlay, type PickerOverlayProps, PickerResponse, type SharedPickerProps, UploaderClientOptions, type UploaderTheme, type UsePickerOptions, type UsePickerResult, editImage, isCameraSupported, shouldOfferCamera, themeToVars, usePicker };
+export { CameraCapture, type CameraCaptureProps, type CameraFacingMode, type CropArea, DeliveryProtection, DropPane, type DropPaneProps, type EditImageOptions, FileResult, type Flip, ImageEditor, type ImageEditorProps, type PickerFile, type PickerFileState, type PickerOptions, PickerOverlay, type PickerOverlayProps, PickerResponse, type SharedPickerProps, UploaderClientOptions, type UploaderTheme, type UsePickerOptions, type UsePickerResult, defaultCameraFacingMode, editImage, isCameraSupported, isMobileDevice, shouldOfferCamera, themeToVars, usePicker };

package/dist/index.d.ts

@@ -144,9 +144,14 @@ type PickerOptions = {
      */
     fromSources?: Array<'local_file_system' | 'camera'>;
     /**
-     * Preferred camera when the 'camera' source is used.
-     *   'user'        — front / selfie camera (mirrored). Default.
+     * Which camera opens first when the 'camera' source is used.
+     *   'user'        — front / selfie camera (mirrored).
      *   'environment' — rear camera.
+     *
+     * Omitted (recommended) → chosen per device: **rear on phones and tablets**,
+     * front on desktops. The user can flip between them in the camera view
+     * whenever the device exposes more than one camera, so this only sets the
+     * starting side.
      */
     cameraFacingMode?: 'user' | 'environment';
 };
@@ -302,6 +307,12 @@ declare function DropPane({ apikey, apiUrl, security, deliveryProtection, allowe
  * unmount, on capture (to release the camera indicator while reviewing), and on
  * cancel.
  *
+ * Which camera opens first is device-dependent: phones and tablets default to
+ * the REAR camera (people photograph the world, not themselves, from an upload
+ * form), desktops to the only camera they have. A flip control appears whenever
+ * the device actually exposes more than one camera, so the default is a starting
+ * point rather than a constraint. `facingMode` overrides the default outright.
+ *
  * All colors resolve from --uploader-* CSS variables — no hard-coded brand
  * colors. Used by PickerOverlay and DropPane.
  *
@@ -310,6 +321,24 @@ declare function DropPane({ apikey, apiUrl, security, deliveryProtection, allowe
 
 /** True when the current environment can open a camera stream. */
 declare function isCameraSupported(): boolean;
+/** Which physical camera to open. Mirrors the getUserMedia `facingMode` values. */
+type CameraFacingMode = 'user' | 'environment';
+/**
+ * Best-effort "is this a phone or tablet?" check, used only to pick which camera
+ * opens first — never to gate a feature, so a wrong answer costs one tap on the
+ * flip control.
+ *
+ * `userAgentData.mobile` is the reliable signal where it exists (Chromium). The
+ * UA regex covers everything else, and the `maxTouchPoints` clause catches
+ * iPadOS 13+, which reports a desktop Macintosh UA and would otherwise open the
+ * front camera on a tablet.
+ */
+declare function isMobileDevice(): boolean;
+/**
+ * The camera to open when the caller expresses no preference: rear on mobile,
+ * front on everything else.
+ */
+declare function defaultCameraFacingMode(): CameraFacingMode;
 /**
  * Decide whether the picker should offer the camera source, given the picker
  * options and the current environment. The camera is offered when:
@@ -323,8 +352,12 @@ type CameraCaptureProps = {
     onCapture: (file: File) => void;
     /** Called when the user backs out without capturing. */
     onCancel: () => void;
-    /** Which camera to prefer. 'user' = front (mirrored), 'environment' = rear. */
-    facingMode?: 'user' | 'environment';
+    /**
+     * Which camera to open first. 'user' = front (mirrored), 'environment' = rear.
+     * Omitted → `defaultCameraFacingMode()`: rear on mobile, front elsewhere. The
+     * user can still flip when the device has more than one camera.
+     */
+    facingMode?: CameraFacingMode;
     /** Output MIME type for the still. Default 'image/jpeg'. */
     outputType?: string;
     /** Quality 0–1 for lossy output. Default 0.92. */
@@ -401,4 +434,4 @@ type EditImageOptions = {
 };
 declare function editImage(file: File, opts?: EditImageOptions): Promise<File>;
 
-export { CameraCapture, type CameraCaptureProps, type CropArea, DeliveryProtection, DropPane, type DropPaneProps, type EditImageOptions, FileResult, type Flip, ImageEditor, type ImageEditorProps, type PickerFile, type PickerFileState, type PickerOptions, PickerOverlay, type PickerOverlayProps, PickerResponse, type SharedPickerProps, UploaderClientOptions, type UploaderTheme, type UsePickerOptions, type UsePickerResult, editImage, isCameraSupported, shouldOfferCamera, themeToVars, usePicker };
+export { CameraCapture, type CameraCaptureProps, type CameraFacingMode, type CropArea, DeliveryProtection, DropPane, type DropPaneProps, type EditImageOptions, FileResult, type Flip, ImageEditor, type ImageEditorProps, type PickerFile, type PickerFileState, type PickerOptions, PickerOverlay, type PickerOverlayProps, PickerResponse, type SharedPickerProps, UploaderClientOptions, type UploaderTheme, type UsePickerOptions, type UsePickerResult, defaultCameraFacingMode, editImage, isCameraSupported, isMobileDevice, shouldOfferCamera, themeToVars, usePicker };

package/dist/index.js

@@ -782,6 +782,19 @@ import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 function isCameraSupported() {
   return typeof navigator !== "undefined" && !!navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === "function" && typeof document !== "undefined" && typeof HTMLCanvasElement !== "undefined";
 }
+function isMobileDevice() {
+  if (typeof navigator === "undefined") return false;
+  const uaData = navigator.userAgentData;
+  if (typeof uaData?.mobile === "boolean") return uaData.mobile;
+  const ua = navigator.userAgent ?? "";
+  if (/Android|iPhone|iPad|iPod|Windows Phone|webOS|BlackBerry|Opera Mini|Mobile/i.test(ua)) {
+    return true;
+  }
+  return /Macintosh/.test(ua) && (navigator.maxTouchPoints ?? 0) > 1;
+}
+function defaultCameraFacingMode() {
+  return isMobileDevice() ? "environment" : "user";
+}
 var IMAGE_EXT = /\.(png|jpe?g|gif|webp|bmp|svg|avif|heic|heif)$/i;
 function acceptsImages(accept) {
   if (!accept || accept.length === 0) return true;
@@ -822,7 +835,7 @@ function describeCameraError(err) {
 function CameraCapture({
   onCapture,
   onCancel,
-  facingMode = "user",
+  facingMode,
   outputType = "image/jpeg",
   quality: quality2 = 0.92,
   fileNamePrefix = "camera-photo",
@@ -835,12 +848,32 @@ function CameraCapture({
   const [status, setStatus] = useState3("initializing");
   const [error, setError] = useState3(null);
   const [stillUrl, setStillUrl] = useState3("");
-  const mirror = facingMode === "user";
+  const [facing, setFacing] = useState3(
+    () => facingMode ?? defaultCameraFacingMode()
+  );
+  const [canFlip, setCanFlip] = useState3(false);
+  const mirror = facing === "user";
+  useEffect2(() => {
+    if (facingMode) setFacing(facingMode);
+  }, [facingMode]);
   const stopStream = useCallback4(() => {
     streamRef.current?.getTracks().forEach((t) => t.stop());
     streamRef.current = null;
     if (videoRef.current) videoRef.current.srcObject = null;
   }, []);
+  const probeCameraCount = useCallback4(async () => {
+    const media = typeof navigator !== "undefined" ? navigator.mediaDevices : void 0;
+    if (!media || typeof media.enumerateDevices !== "function") {
+      setCanFlip(isMobileDevice());
+      return;
+    }
+    try {
+      const devices = await media.enumerateDevices();
+      setCanFlip(devices.filter((d) => d.kind === "videoinput").length > 1);
+    } catch {
+      setCanFlip(isMobileDevice());
+    }
+  }, []);
   const startStream = useCallback4(async () => {
     setError(null);
     setStatus("initializing");
@@ -849,9 +882,12 @@ function CameraCapture({
       setStatus("error");
       return;
     }
+    stopStream();
     try {
       const stream = await navigator.mediaDevices.getUserMedia({
-        video: { facingMode },
+        // Non-exact: a device with no camera on the requested side falls back to
+        // the one it has rather than throwing OverconstrainedError.
+        video: { facingMode: facing },
         audio: false
       });
       if (videoRef.current == null) {
@@ -861,11 +897,12 @@ function CameraCapture({
       streamRef.current = stream;
       videoRef.current.srcObject = stream;
       setStatus("live");
+      void probeCameraCount();
     } catch (err) {
       setError(describeCameraError(err));
       setStatus("error");
     }
-  }, [facingMode]);
+  }, [facing, probeCameraCount, stopStream]);
   useEffect2(() => {
     void startStream();
     return () => {
@@ -913,6 +950,9 @@ function CameraCapture({
       quality2
     );
   }, [mirror, outputType, quality2, stopStream]);
+  const flipCamera = useCallback4(() => {
+    setFacing((current) => current === "user" ? "environment" : "user");
+  }, []);
   const retake = useCallback4(() => {
     blobRef.current = null;
     setStillUrl("");
@@ -931,6 +971,7 @@ function CameraCapture({
       className: ["uploader-camera", className ?? ""].filter(Boolean).join(" "),
       style,
       "data-testid": "camera-capture",
+      "data-facing": facing,
       children: [
         /* @__PURE__ */ jsxs3("div", { className: "uploader-camera-stage", children: [
           status === "error" ? /* @__PURE__ */ jsx3("div", { className: "uploader-camera-error", role: "alert", children: error }) : status === "captured" ? (
@@ -947,7 +988,50 @@ function CameraCapture({
               "data-mirror": mirror ? "true" : void 0
             }
           ),
-          status === "initializing" && /* @__PURE__ */ jsx3("div", { className: "uploader-camera-status", "aria-live": "polite", children: "Starting camera\u2026" })
+          status === "initializing" && /* @__PURE__ */ jsx3("div", { className: "uploader-camera-status", "aria-live": "polite", children: "Starting camera\u2026" }),
+          canFlip && (status === "live" || status === "initializing") && /* @__PURE__ */ jsx3(
+            "button",
+            {
+              type: "button",
+              className: "uploader-camera-flip",
+              "aria-label": facing === "user" ? "Switch to rear camera" : "Switch to front camera",
+              disabled: status !== "live",
+              onClick: flipCamera,
+              children: /* @__PURE__ */ jsxs3("svg", { viewBox: "0 0 24 24", width: "20", height: "20", "aria-hidden": "true", focusable: "false", children: [
+                /* @__PURE__ */ jsx3(
+                  "path",
+                  {
+                    d: "M4 8.5A2.5 2.5 0 0 1 6.5 6h1.2l1-1.7a1 1 0 0 1 .87-.5h4.86a1 1 0 0 1 .86.5l1 1.7h1.21A2.5 2.5 0 0 1 20 8.5v8A2.5 2.5 0 0 1 17.5 19h-11A2.5 2.5 0 0 1 4 16.5v-8Z",
+                    fill: "none",
+                    stroke: "currentColor",
+                    strokeWidth: "1.6",
+                    strokeLinejoin: "round"
+                  }
+                ),
+                /* @__PURE__ */ jsx3(
+                  "path",
+                  {
+                    d: "M9.4 12.6a2.6 2.6 0 0 0 4.45 1.6M14.6 11.4a2.6 2.6 0 0 0-4.45-1.6",
+                    fill: "none",
+                    stroke: "currentColor",
+                    strokeWidth: "1.6",
+                    strokeLinecap: "round"
+                  }
+                ),
+                /* @__PURE__ */ jsx3(
+                  "path",
+                  {
+                    d: "m9.4 10.2-.1 2.1 2.1-.6M14.6 13.8l.1-2.1-2.1.6",
+                    fill: "none",
+                    stroke: "currentColor",
+                    strokeWidth: "1.6",
+                    strokeLinecap: "round",
+                    strokeLinejoin: "round"
+                  }
+                )
+              ] })
+            }
+          )
         ] }),
         status === "live" && /* @__PURE__ */ jsx3("p", { className: "uploader-camera-hint", children: "Frame your shot, then tap the shutter to capture." }),
         /* @__PURE__ */ jsx3("div", { className: "uploader-camera-actions", children: status === "captured" ? /* @__PURE__ */ jsxs3(Fragment, { children: [
@@ -1638,10 +1722,12 @@ export {
   PickerOverlay,
   UploaderClient,
   crop,
+  defaultCameraFacingMode,
   editImage,
   flip,
   flop,
   isCameraSupported,
+  isMobileDevice,
   output,
   quality,
   resize,