@multiplatform.one/forms 7.34.4 → 7.36.0

package/src/MediaPicker/MediaPickerDemo.spec.tsx

@@ -0,0 +1,68 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import {
+  Preset,
+  boldPreset,
+  defaultPreset,
+  densePreset,
+  heroPreset,
+  registerPreset,
+  roomyPreset,
+} from "@multiplatform.one/theme";
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MediaPickerDemo } from "./MediaPicker.stories";
+import { pickMedia } from "./pickMedia";
+import { MediaPickerError } from "./types";
+
+vi.mock("./pickMedia", () => ({ pickMedia: vi.fn() }));
+beforeEach(() => vi.mocked(pickMedia).mockReset().mockResolvedValue(null));
+afterEach(cleanup);
+
+const presets = {
+  default: defaultPreset,
+  bold: boldPreset,
+  hero: heroPreset,
+  dense: densePreset,
+  roomy: roomyPreset,
+};
+for (const [name, preset] of Object.entries(presets)) registerPreset(name, preset);
+
+describe.each(Object.keys(presets))("%s media compositions", (preset) => {
+  it.each(["light", "dark"] as const)("keeps camera and library controls in %s", async (theme) => {
+    renderWithProviders(
+      <Preset preset={preset} theme={theme}>
+        <MediaPickerDemo capture />
+      </Preset>,
+    );
+    expect(document.querySelector('input[type="file"]')).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Take photo" }));
+    await waitFor(() =>
+      expect(pickMedia).toHaveBeenCalledWith(
+        { source: "camera", bytes: true },
+        expect.any(AbortSignal),
+      ),
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("button", { name: "Choose photo" })).not.toBeDisabled(),
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Choose photo" }));
+    await waitFor(() =>
+      expect(pickMedia).toHaveBeenLastCalledWith(
+        { source: "library", bytes: true },
+        expect.any(AbortSignal),
+      ),
+    );
+  });
+});
+
+it("shows a permission error at the invoking control and allows retry", async () => {
+  vi.mocked(pickMedia).mockRejectedValueOnce(
+    new MediaPickerError("permission-denied", "Photo access was denied.", "library"),
+  );
+  renderWithProviders(<MediaPickerDemo />);
+  fireEvent.click(screen.getByRole("button", { name: "Choose photo" }));
+  expect(await screen.findByRole("alert")).toHaveTextContent("Photo access was denied.");
+  expect(screen.getByRole("button", { name: "Choose photo" })).not.toBeDisabled();
+  fireEvent.click(screen.getByRole("button", { name: "Choose photo" }));
+  await waitFor(() => expect(screen.queryByRole("alert")).toBeNull());
+});

package/src/MediaPicker/README.md

@@ -0,0 +1,35 @@
+# MediaPicker
+
+`useMediaPicker` opens the system camera or image library without rendering controls.
+Compose it with MPO buttons so the invoking UI follows the active preset.
+
+`pick({ source: "camera" | "library", base64?, bytes? })` resolves to
+`{ uri, mimeType, width, height, base64?, bytes? }`, or `null` on cancellation.
+Bytes are the encoded image file, not decoded pixels. Base64 has no data-URL prefix.
+Only requested data properties are included. Native URIs point to the picker's
+temporary local file; persist the image before relying on it across app restarts.
+Web returns a data URI that remains usable after unmount. Browsers read the file
+to decode dimensions even when the extra data properties aren't requested.
+
+Call `pick` directly from the press handler. Awaiting work before it loses browser
+user activation. Web camera selection uses the file input's `capture` hint; a
+browser without camera capture opens its ordinary file chooser. Modern browsers
+emit `cancel`; older browsers use a window-focus fallback.
+
+Catch `MediaPickerError` and show its message at the invoking control. Its `code`
+is `permission-denied`, `unavailable`, `read-failed`, `invalid-image`, or `busy`.
+Permission errors include `canAskAgain` when the OS provides it. Cancellation
+preserves the caller's previous value. Only one picker may be active at a time.
+Unmounting removes the web input and settles its request. A native OS sheet
+cannot be programmatically dismissed; its eventual result is ignored after
+unmount and another native picker remains blocked until that sheet closes.
+
+Native hosts must install the optional `expo-image-picker` peer and include its
+config plugin in their binary. Declare the app's own `cameraPermission` and
+`photosPermission` purpose strings there; MPO never substitutes an app name or
+permission message. Image-only hosts can set `microphonePermission: false`.
+Changing these native settings requires a new binary, not an OTA update. A binary
+without the native module receives `unavailable` without importing the module.
+
+`FileUpload` remains the visible form-field primitive. Use this hook when an
+existing capture or profile surface owns its own controls.

package/src/MediaPicker/base64.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { base64ToBytes } from "./base64";
+
+describe("media image bytes", () => {
+  it.each([
+    ["", ""],
+    ["Zg==", "f"],
+    ["Zm8=", "fo"],
+    ["Zm9v", "foo"],
+    ["Zm9vYmFy", "foobar"],
+  ])("decodes RFC 4648 vector %s", (encoded, decoded) => {
+    expect(base64ToBytes(encoded)).toEqual(new TextEncoder().encode(decoded));
+  });
+  it("preserves binary bytes without relying on atob", () => {
+    expect(base64ToBytes("/9j/AA==")).toEqual(new Uint8Array([255, 216, 255, 0]));
+  });
+  it("handles large image payloads", () => {
+    const bytes = new Uint8Array(100_000).fill(241);
+    expect(base64ToBytes(Buffer.from(bytes).toString("base64"))).toEqual(bytes);
+  });
+  it("decodes a phone photo larger than the regexp stack", () => {
+    const bytes = base64ToBytes("A".repeat(16_777_216));
+    expect(bytes.length).toBe(12_582_912);
+    expect(bytes.every((byte) => byte === 0)).toBe(true);
+  });
+  it("rejects malformed data", () => {
+    expect(() => base64ToBytes("not base64!")).toThrow();
+  });
+});

package/src/MediaPicker/base64.ts

@@ -0,0 +1,23 @@
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const sextets = new Uint8Array(128);
+for (let index = 0; index < alphabet.length; index++) sextets[alphabet.charCodeAt(index)] = index;
+
+export function base64ToBytes(value: string): Uint8Array {
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  if (value.length % 4 !== 0 || /[^A-Za-z0-9+/]/.test(value.slice(0, value.length - padding))) {
+    throw new Error("Invalid base64 image data");
+  }
+  const bytes = new Uint8Array((value.length / 4) * 3 - padding);
+  let offset = 0;
+  for (let i = 0; i < value.length; i += 4) {
+    const word =
+      (sextets[value.charCodeAt(i)]! << 18) |
+      (sextets[value.charCodeAt(i + 1)]! << 12) |
+      (sextets[value.charCodeAt(i + 2)]! << 6) |
+      sextets[value.charCodeAt(i + 3)]!;
+    bytes[offset++] = (word >> 16) & 255;
+    if (offset < bytes.length) bytes[offset++] = (word >> 8) & 255;
+    if (offset < bytes.length) bytes[offset++] = word & 255;
+  }
+  return bytes;
+}

package/src/MediaPicker/payload.ts

@@ -0,0 +1,54 @@
+import { base64ToBytes } from "./base64";
+import { MediaPickerError, type MediaPickOptions, type PickedMedia } from "./types";
+
+const imageMimes: Record<string, string> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  heic: "image/heic",
+  heif: "image/heif",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  svg: "image/svg+xml",
+};
+
+export function imageMime(type: string | null | undefined, name: string): string {
+  return type || imageMimes[name.split(/[?#]/)[0]!.split(".").pop()!.toLowerCase()] || "";
+}
+
+export function imagePayload(
+  image: Omit<PickedMedia, "bytes" | "base64">,
+  base64: string | null | undefined,
+  options: MediaPickOptions,
+): PickedMedia {
+  if (
+    !image.mimeType.startsWith("image/") ||
+    !image.uri ||
+    !Number.isFinite(image.width) ||
+    !Number.isFinite(image.height) ||
+    image.width <= 0 ||
+    image.height <= 0
+  ) {
+    throw new MediaPickerError(
+      "invalid-image",
+      "The selected file is not a readable image.",
+      options.source,
+    );
+  }
+  const result: PickedMedia = { ...image };
+  if (options.base64 || options.bytes) {
+    if (!base64)
+      throw new MediaPickerError(
+        "read-failed",
+        "The image data could not be read.",
+        options.source,
+      );
+    if (options.base64) result.base64 = base64;
+    if (options.bytes) result.bytes = base64ToBytes(base64);
+  }
+  return result;
+}

package/src/MediaPicker/pickMedia.native.spec.ts

@@ -0,0 +1,160 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { loadImagePicker } from "../fields/FileUpload/nativePickerLoader";
+import { pickMedia } from "./pickMedia.native";
+import { MediaPickerError } from "./types";
+
+vi.mock("../fields/FileUpload/nativePickerLoader", () => ({ loadImagePicker: vi.fn() }));
+
+const cameraPermission = vi.fn();
+const libraryPermission = vi.fn();
+const launchCamera = vi.fn();
+const launchLibrary = vi.fn();
+const asset = {
+  uri: "file:///cache/photo.png",
+  mimeType: "image/png",
+  width: 32,
+  height: 24,
+  base64: "AQID",
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  cameraPermission.mockResolvedValue({ granted: true, canAskAgain: true });
+  libraryPermission.mockResolvedValue({ granted: true, canAskAgain: true });
+  launchCamera.mockResolvedValue({ canceled: false, assets: [asset] });
+  launchLibrary.mockResolvedValue({ canceled: false, assets: [asset] });
+  vi.mocked(loadImagePicker).mockReturnValue({
+    requestCameraPermissionsAsync: cameraPermission,
+    requestMediaLibraryPermissionsAsync: libraryPermission,
+    launchCameraAsync: launchCamera,
+    launchImageLibraryAsync: launchLibrary,
+  } as never);
+});
+
+describe("native media picker", () => {
+  it("preflights the camera and returns image metadata without eager data", async () => {
+    expect(await pickMedia({ source: "camera" })).toEqual({
+      uri: asset.uri,
+      mimeType: "image/png",
+      width: 32,
+      height: 24,
+    });
+    expect(cameraPermission).toHaveBeenCalledOnce();
+    expect(libraryPermission).not.toHaveBeenCalled();
+    expect(launchCamera).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mediaTypes: ["images"],
+        base64: false,
+      }),
+    );
+  });
+
+  it("returns requested base64 and matching bytes", async () => {
+    expect(await pickMedia({ source: "library", base64: true, bytes: true })).toEqual({
+      ...asset,
+      bytes: new Uint8Array([1, 2, 3]),
+    });
+    expect(launchLibrary).toHaveBeenCalledWith(expect.objectContaining({ base64: true }));
+  });
+
+  it("resolves null on cancel", async () => {
+    launchLibrary.mockResolvedValue({ canceled: true, assets: null });
+    expect(await pickMedia({ source: "library" })).toBeNull();
+  });
+
+  it("rejects denied permission before launching with a typed error", async () => {
+    cameraPermission.mockResolvedValue({ granted: false, canAskAgain: false });
+    await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({
+      code: "permission-denied",
+      source: "camera",
+      canAskAgain: false,
+    });
+    expect(launchCamera).not.toHaveBeenCalled();
+  });
+
+  it("reports a missing optional native module", async () => {
+    vi.mocked(loadImagePicker).mockReturnValue(null);
+    await expect(pickMedia({ source: "library" })).rejects.toBeInstanceOf(MediaPickerError);
+    await expect(pickMedia({ source: "library" })).rejects.toMatchObject({ code: "unavailable" });
+  });
+
+  it("does not silently omit requested data", async () => {
+    launchLibrary.mockResolvedValue({ canceled: false, assets: [{ ...asset, base64: null }] });
+    await expect(pickMedia({ source: "library", bytes: true })).rejects.toMatchObject({
+      code: "read-failed",
+    });
+  });
+
+  it("infers an omitted MIME type from the local URI", async () => {
+    launchLibrary.mockResolvedValue({
+      canceled: false,
+      assets: [{ ...asset, mimeType: undefined }],
+    });
+    expect(await pickMedia({ source: "library" })).toMatchObject({ mimeType: "image/png" });
+  });
+
+  it("denies library permission without opening a sheet", async () => {
+    libraryPermission.mockResolvedValue({ granted: false, canAskAgain: true });
+    await expect(pickMedia({ source: "library" })).rejects.toMatchObject({
+      code: "permission-denied",
+      canAskAgain: true,
+    });
+    expect(launchLibrary).not.toHaveBeenCalled();
+  });
+
+  it("ignores an aborted OS result and keeps the lock until the sheet closes", async () => {
+    let finish!: (result: unknown) => void;
+    launchLibrary.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+    );
+    const controller = new AbortController();
+    const first = pickMedia({ source: "library" }, controller.signal);
+    await vi.waitFor(() => expect(launchLibrary).toHaveBeenCalledOnce());
+    controller.abort();
+    await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({ code: "busy" });
+    finish({ canceled: false, assets: [asset] });
+    expect(await first).toBeNull();
+    expect(await pickMedia({ source: "camera" })).toMatchObject({ uri: asset.uri });
+  });
+
+  it("does not launch if unmounted during the permission request", async () => {
+    const controller = new AbortController();
+    cameraPermission.mockImplementationOnce(async () => {
+      controller.abort();
+      return { granted: true };
+    });
+    expect(await pickMedia({ source: "camera" }, controller.signal)).toBeNull();
+    expect(launchCamera).not.toHaveBeenCalled();
+  });
+
+  it("wraps OS failures and releases the picker lock", async () => {
+    const cause = new Error("No camera hardware");
+    launchCamera.mockRejectedValueOnce(cause);
+    await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({
+      code: "read-failed",
+      cause,
+    });
+    expect(await pickMedia({ source: "library" })).toMatchObject({ uri: asset.uri });
+  });
+
+  it.each(["ERR_CAMERA_UNAVAILABLE_ON_SIMULATOR", "ERR_MISSING_ACTIVITY_TO_HANDLE_INTENT"])(
+    "reports %s as unavailable",
+    async (code) => {
+      launchCamera.mockRejectedValueOnce({ code });
+      await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({ code: "unavailable" });
+    },
+  );
+
+  it.each(["ERR_MISSING_CAMERA_PERMISSION", "ERR_USER_REJECTED_PERMISSIONS"])(
+    "preserves a late OS permission denial: %s",
+    async (code) => {
+      launchCamera.mockRejectedValueOnce({ code });
+      await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({
+        code: "permission-denied",
+      });
+    },
+  );
+});

package/src/MediaPicker/pickMedia.native.ts

@@ -0,0 +1,95 @@
+import { loadImagePicker } from "../fields/FileUpload/nativePickerLoader";
+import { imageMime, imagePayload } from "./payload";
+import { MediaPickerError, type MediaPickOptions, type PickedMedia } from "./types";
+
+let active = false;
+
+export async function pickMedia(
+  options: MediaPickOptions,
+  signal?: AbortSignal,
+): Promise<PickedMedia | null> {
+  if (signal?.aborted) return null;
+  if (active)
+    throw new MediaPickerError("busy", "An image picker is already open.", options.source);
+  active = true;
+  try {
+    const picker = loadImagePicker();
+    if (!picker)
+      throw new MediaPickerError("unavailable", "This build has no image picker.", options.source);
+    const permission =
+      options.source === "camera"
+        ? await picker.requestCameraPermissionsAsync()
+        : await picker.requestMediaLibraryPermissionsAsync();
+    if (signal?.aborted) return null;
+    if (!permission.granted) {
+      throw new MediaPickerError(
+        "permission-denied",
+        "Image access was denied.",
+        options.source,
+        permission.canAskAgain,
+      );
+    }
+    const request = {
+      mediaTypes: ["images"] as "images"[],
+      quality: 1,
+      allowsMultipleSelection: false,
+      base64: !!(options.base64 || options.bytes),
+    };
+    const result =
+      options.source === "camera"
+        ? await picker.launchCameraAsync(request)
+        : await picker.launchImageLibraryAsync(request);
+    if (signal?.aborted || result.canceled) return null;
+    const asset = result.assets[0];
+    if (!asset)
+      throw new MediaPickerError("read-failed", "The picker returned no image.", options.source);
+    return imagePayload(
+      {
+        uri: asset.uri,
+        mimeType: imageMime(asset.mimeType, asset.uri),
+        width: asset.width,
+        height: asset.height,
+      },
+      asset.base64,
+      options,
+    );
+  } catch (error) {
+    if (signal?.aborted) return null;
+    if (error instanceof MediaPickerError) throw error;
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (
+      code === "ERR_CAMERA_UNAVAILABLE_ON_SIMULATOR" ||
+      code === "ERR_MISSING_ACTIVITY_TO_HANDLE_INTENT"
+    ) {
+      throw new MediaPickerError(
+        "unavailable",
+        "This device cannot open the image picker.",
+        options.source,
+        undefined,
+        { cause: error },
+      );
+    }
+    if (
+      code === "ERR_MISSING_CAMERA_PERMISSION" ||
+      code === "ERR_MISSING_PHOTO_LIBRARY_PERMISSION" ||
+      code === "ERR_USER_REJECTED_PERMISSIONS"
+    ) {
+      throw new MediaPickerError(
+        "permission-denied",
+        "Image access was denied.",
+        options.source,
+        undefined,
+        { cause: error },
+      );
+    }
+    throw new MediaPickerError(
+      "read-failed",
+      "The image could not be opened.",
+      options.source,
+      undefined,
+      { cause: error },
+    );
+  } finally {
+    active = false;
+  }
+}

package/src/MediaPicker/pickMedia.spec.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { pickMedia } from "./pickMedia";
+
+let opened: HTMLInputElement | undefined;
+
+beforeEach(() => {
+  opened = undefined;
+  vi.spyOn(HTMLInputElement.prototype, "click").mockImplementation(() => {
+    opened = document.querySelector<HTMLInputElement>('input[type="file"]') ?? undefined;
+  });
+  vi.stubGlobal(
+    "Image",
+    class {
+      naturalWidth = 32;
+      naturalHeight = 24;
+      onload?: () => void;
+      onerror?: () => void;
+      set src(_uri: string) {
+        queueMicrotask(() => this.onload?.());
+      }
+    },
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+function select(file: File) {
+  Object.defineProperty(opened, "files", { configurable: true, value: [file] });
+  opened!.dispatchEvent(new Event("change"));
+}
+
+describe("web media picker", () => {
+  it("opens synchronously in the user gesture and requests image capture", async () => {
+    const result = pickMedia({ source: "camera" });
+    expect(opened?.type).toBe("file");
+    expect(opened?.accept).toBe("image/*");
+    expect(opened?.getAttribute("capture")).toBe("environment");
+    expect(opened?.hidden).toBe(true);
+    opened!.dispatchEvent(new Event("cancel"));
+    expect(await result).toBeNull();
+    expect(document.querySelector('input[type="file"]')).toBeNull();
+  });
+
+  it("returns metadata and requested data for the same image", async () => {
+    const result = pickMedia({ source: "library", bytes: true, base64: true });
+    expect(opened?.hasAttribute("capture")).toBe(false);
+    select(new File([new Uint8Array([1, 2, 3])], "photo.png", { type: "image/png" }));
+    expect(await result).toEqual({
+      uri: "data:image/png;base64,AQID",
+      mimeType: "image/png",
+      width: 32,
+      height: 24,
+      base64: "AQID",
+      bytes: new Uint8Array([1, 2, 3]),
+    });
+    expect(document.querySelector('input[type="file"]')).toBeNull();
+  });
+
+  it("settles and cleans up on abort", async () => {
+    const controller = new AbortController();
+    const result = pickMedia({ source: "library" }, controller.signal);
+    controller.abort();
+    expect(await result).toBeNull();
+    expect(document.querySelector('input[type="file"]')).toBeNull();
+  });
+
+  it("uses focus cancellation even when oncancel exists for dialog support", async () => {
+    vi.useFakeTimers();
+    const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "oncancel");
+    Object.defineProperty(HTMLInputElement.prototype, "oncancel", {
+      configurable: true,
+      value: null,
+    });
+    const controller = new AbortController();
+    try {
+      const result = pickMedia({ source: "library" }, controller.signal);
+      window.dispatchEvent(new Event("focus"));
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(document.querySelector('input[type="file"]')).toBeNull();
+      expect(await result).toBeNull();
+    } finally {
+      controller.abort();
+      if (descriptor) Object.defineProperty(HTMLInputElement.prototype, "oncancel", descriptor);
+      else Reflect.deleteProperty(HTMLInputElement.prototype, "oncancel");
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not open when already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    expect(await pickMedia({ source: "library" }, controller.signal)).toBeNull();
+    expect(opened).toBeUndefined();
+  });
+
+  it("rejects nonimages and allows the next pick", async () => {
+    const result = pickMedia({ source: "library" });
+    const assertion = expect(result).rejects.toMatchObject({ code: "invalid-image" });
+    select(new File(["text"], "file.txt", { type: "text/plain" }));
+    await assertion;
+    const next = pickMedia({ source: "library" });
+    opened!.dispatchEvent(new Event("cancel"));
+    expect(await next).toBeNull();
+  });
+
+  it("rejects concurrent requests instead of losing a resolver", async () => {
+    const first = pickMedia({ source: "library" });
+    await expect(pickMedia({ source: "camera" })).rejects.toMatchObject({ code: "busy" });
+    opened!.dispatchEvent(new Event("cancel"));
+    await first;
+  });
+
+  it("returns a typed failure when the browser refuses to open", async () => {
+    vi.mocked(HTMLInputElement.prototype.click).mockImplementation(() => {
+      throw new DOMException("Blocked", "NotAllowedError");
+    });
+    await expect(pickMedia({ source: "library" })).rejects.toMatchObject({
+      code: "permission-denied",
+    });
+    expect(document.querySelector('input[type="file"]')).toBeNull();
+  });
+});