@multiplatform.one/forms 7.4.0 → 7.5.0

package/src/fields/FileUpload/nativeFilePicker.native.spec.ts

@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  acceptToMimeTypes,
+  isImageOnlyAccept,
+  isNativeFilePickerAvailable,
+  pickFilesNatively,
+} from "./nativeFilePicker.native";
+import { loadDocumentPicker, loadImagePicker } from "./nativePickerLoader";
+
+// The optional-peer loaders are the mock seam: on-device they try/catch-require
+// the pickers (Metro optional dependencies); here the modules are swapped
+// wholesale, the same way GeolocationMap.native.spec mocks `expoMapsLoader`.
+vi.mock("./nativePickerLoader", () => ({
+  loadDocumentPicker: vi.fn(() => null),
+  loadImagePicker: vi.fn(() => null),
+}));
+
+const loadDocumentPickerMock = vi.mocked(loadDocumentPicker);
+const loadImagePickerMock = vi.mocked(loadImagePicker);
+
+const getDocumentAsync = vi.fn();
+const launchImageLibraryAsync = vi.fn();
+const requestMediaLibraryPermissionsAsync = vi.fn();
+
+function withDocumentPicker() {
+  loadDocumentPickerMock.mockReturnValue({ getDocumentAsync } as never);
+}
+
+function withImagePicker() {
+  loadImagePickerMock.mockReturnValue({
+    launchImageLibraryAsync,
+    requestMediaLibraryPermissionsAsync,
+  } as never);
+}
+
+beforeEach(() => {
+  loadDocumentPickerMock.mockReset().mockReturnValue(null);
+  loadImagePickerMock.mockReset().mockReturnValue(null);
+  getDocumentAsync.mockReset();
+  launchImageLibraryAsync.mockReset();
+  requestMediaLibraryPermissionsAsync.mockReset().mockResolvedValue({ granted: true });
+});
+
+describe("acceptToMimeTypes", () => {
+  it("passes MIME entries through and drops extension entries", () => {
+    expect(acceptToMimeTypes("image/png, .pdf ,application/json")).toEqual([
+      "image/png",
+      "application/json",
+    ]);
+  });
+
+  it("returns undefined when accept is absent or extension-only", () => {
+    expect(acceptToMimeTypes()).toBeUndefined();
+    expect(acceptToMimeTypes(".pdf,.docx")).toBeUndefined();
+  });
+});
+
+describe("isImageOnlyAccept", () => {
+  it("is true only when every entry is an image", () => {
+    expect(isImageOnlyAccept("image/*")).toBe(true);
+    expect(isImageOnlyAccept("image/png,.jpg")).toBe(true);
+    expect(isImageOnlyAccept("image/png,application/pdf")).toBe(false);
+    expect(isImageOnlyAccept()).toBe(false);
+  });
+});
+
+describe("isNativeFilePickerAvailable", () => {
+  it("is false with neither peer and true with either", () => {
+    expect(isNativeFilePickerAvailable()).toBe(false);
+    withDocumentPicker();
+    expect(isNativeFilePickerAvailable()).toBe(true);
+  });
+});
+
+describe("pickFilesNatively", () => {
+  it("reports unavailable when no picker is linked into the build", async () => {
+    await expect(pickFilesNatively({})).resolves.toEqual({ files: [], unavailable: true });
+  });
+
+  it("maps document assets onto the FormData-ready shape", async () => {
+    withDocumentPicker();
+    getDocumentAsync.mockResolvedValue({
+      canceled: false,
+      assets: [
+        {
+          name: "report.pdf",
+          size: 2048,
+          uri: "file:///tmp/report.pdf",
+          mimeType: "application/pdf",
+          lastModified: 42,
+        },
+      ],
+    });
+
+    const outcome = await pickFilesNatively({ accept: "application/pdf,.pdf", multiple: true });
+
+    expect(getDocumentAsync).toHaveBeenCalledWith({
+      type: ["application/pdf"],
+      multiple: true,
+      copyToCacheDirectory: true,
+    });
+    expect(outcome.files).toEqual([
+      {
+        name: "report.pdf",
+        size: 2048,
+        type: "application/pdf",
+        uri: "file:///tmp/report.pdf",
+        lastModified: 42,
+      },
+    ]);
+  });
+
+  it("routes an image-only accept to the photo library", async () => {
+    withDocumentPicker();
+    withImagePicker();
+    launchImageLibraryAsync.mockResolvedValue({
+      canceled: false,
+      assets: [{ uri: "file:///tmp/IMG_0001.HEIC", fileSize: 900 }],
+    });
+
+    const outcome = await pickFilesNatively({ accept: "image/*" });
+
+    expect(getDocumentAsync).not.toHaveBeenCalled();
+    expect(launchImageLibraryAsync).toHaveBeenCalledWith({
+      mediaTypes: ["images"],
+      allowsMultipleSelection: false,
+      quality: 1,
+    });
+    // Android providers omit fileName and mimeType; both are derived from the
+    // URI so an accept="image/*" field does not reject its own pick.
+    expect(outcome.files).toEqual([
+      {
+        name: "IMG_0001.HEIC",
+        size: 900,
+        type: "image/heic",
+        uri: "file:///tmp/IMG_0001.HEIC",
+        lastModified: expect.any(Number),
+      },
+    ]);
+  });
+
+  it("reports a denied photo permission instead of falling back to documents", async () => {
+    withDocumentPicker();
+    withImagePicker();
+    requestMediaLibraryPermissionsAsync.mockResolvedValue({ granted: false });
+
+    const outcome = await pickFilesNatively({ accept: "image/*" });
+
+    expect(outcome).toEqual({ files: [], denied: true });
+    expect(getDocumentAsync).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the document browser when only that peer is installed", async () => {
+    withDocumentPicker();
+    getDocumentAsync.mockResolvedValue({ canceled: true });
+
+    const outcome = await pickFilesNatively({ accept: "image/*", mode: "image" });
+
+    expect(getDocumentAsync).toHaveBeenCalled();
+    expect(outcome).toEqual({ files: [], canceled: true });
+  });
+
+  it("treats a dismissed picker as a no-op", async () => {
+    withDocumentPicker();
+    getDocumentAsync.mockResolvedValue({ canceled: true });
+    await expect(pickFilesNatively({})).resolves.toEqual({ files: [], canceled: true });
+  });
+});

package/src/fields/FileUpload/nativeFilePicker.native.ts

@@ -0,0 +1,150 @@
+import type { NativePickedFile, NativePickOutcome, NativePickRequest } from "./filePickerTypes";
+import { loadDocumentPicker, loadImagePicker } from "./nativePickerLoader";
+
+/** Strips a display name out of a `file://`/`content://` URI. */
+function nameFromUri(uri: string, fallback: string): string {
+  const withoutQuery = uri.split("?")[0] ?? uri;
+  const last = withoutQuery.split("/").pop();
+  return last && last.length > 0 ? decodeURIComponent(last) : fallback;
+}
+
+const extensionMimes: Record<string, string> = {
+  gif: "image/gif",
+  heic: "image/heic",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  mov: "video/quicktime",
+  mp4: "video/mp4",
+  png: "image/png",
+  webp: "image/webp",
+};
+
+/**
+ * The image picker leaves `mimeType` undefined on some Android providers, and
+ * the field's `accept` check matches on `file.type`. Deriving it from the
+ * extension keeps an `accept="image/*"` field from rejecting its own pick.
+ */
+function mimeFromName(name: string): string {
+  const ext = name.split(".").pop()?.toLowerCase();
+  return (ext && extensionMimes[ext]) || "";
+}
+
+/**
+ * `accept` is a web media-query string ("image/*,.pdf"). The document picker
+ * takes MIME types only, so extension entries are dropped here and caught
+ * afterwards by the field's own `validateFile` — better a slightly wide picker
+ * than one that silently shows nothing.
+ */
+export function acceptToMimeTypes(accept?: string): string[] | undefined {
+  if (!accept) return undefined;
+  const mimes = accept
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0 && !entry.startsWith("."));
+  return mimes.length > 0 ? mimes : undefined;
+}
+
+/** True when every `accept` entry is an image type, so the photo library is the better surface. */
+export function isImageOnlyAccept(accept?: string): boolean {
+  if (!accept) return false;
+  const entries = accept
+    .split(",")
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0);
+  return (
+    entries.length > 0 &&
+    entries.every(
+      (entry) =>
+        entry.startsWith("image/") ||
+        entry === ".png" ||
+        entry === ".jpg" ||
+        entry === ".jpeg" ||
+        entry === ".gif" ||
+        entry === ".webp" ||
+        entry === ".heic",
+    )
+  );
+}
+
+export function isNativeFilePickerAvailable(): boolean {
+  return loadDocumentPicker() !== null || loadImagePicker() !== null;
+}
+
+async function pickFromPhotoLibrary(request: NativePickRequest): Promise<NativePickOutcome | null> {
+  const picker = loadImagePicker();
+  if (!picker) return null;
+  const permission = await picker.requestMediaLibraryPermissionsAsync();
+  if (!permission.granted) return { files: [], denied: true };
+  const result = await picker.launchImageLibraryAsync({
+    mediaTypes: ["images"],
+    allowsMultipleSelection: !!request.multiple,
+    quality: 1,
+  });
+  if (result.canceled) return { files: [], canceled: true };
+  const files: NativePickedFile[] = (result.assets ?? []).map((asset) => {
+    const name = asset.fileName || nameFromUri(asset.uri, "image");
+    return {
+      name,
+      // Android's photo provider omits fileSize; 0 keeps `maxSize` permissive
+      // rather than rejecting a file whose size the OS never reported.
+      size: asset.fileSize ?? 0,
+      type: asset.mimeType || mimeFromName(name),
+      uri: asset.uri,
+      lastModified: Date.now(),
+    };
+  });
+  return { files };
+}
+
+async function pickFromDocuments(request: NativePickRequest): Promise<NativePickOutcome | null> {
+  const picker = loadDocumentPicker();
+  if (!picker) return null;
+  const result = await picker.getDocumentAsync({
+    type: acceptToMimeTypes(request.accept) ?? "*/*",
+    multiple: !!request.multiple,
+    copyToCacheDirectory: true,
+  });
+  if (result.canceled) return { files: [], canceled: true };
+  const files: NativePickedFile[] = (result.assets ?? []).map((asset) => {
+    const name = asset.name || nameFromUri(asset.uri, "file");
+    return {
+      name,
+      size: asset.size ?? 0,
+      type: asset.mimeType || mimeFromName(name),
+      uri: asset.uri,
+      lastModified: asset.lastModified ?? Date.now(),
+    };
+  });
+  return { files };
+}
+
+/**
+ * Opens the system picker and returns the chosen files.
+ *
+ * `mode: "auto"` (the default) sends an image-only `accept` to the photo
+ * library — the surface a phone user expects for an avatar or a receipt — and
+ * everything else to the document browser. Either peer may be missing from a
+ * build; the other one is tried before reporting `unavailable`, so a consumer
+ * that installed only `expo-document-picker` still gets a working field.
+ */
+export async function pickFilesNatively(request: NativePickRequest): Promise<NativePickOutcome> {
+  const mode = request.mode ?? "auto";
+  const preferImages = mode === "image" || (mode === "auto" && isImageOnlyAccept(request.accept));
+  const order = preferImages
+    ? [pickFromPhotoLibrary, pickFromDocuments]
+    : [pickFromDocuments, pickFromPhotoLibrary];
+  for (const attempt of order) {
+    // `mode: "image"` must not silently fall back to the document browser for
+    // a DENIED permission — only for a picker that is absent from the build.
+    const outcome = await attempt(request);
+    if (outcome) return outcome;
+  }
+  return { files: [], unavailable: true };
+}
+
+export type {
+  NativePickedFile,
+  NativePickerMode,
+  NativePickOutcome,
+  NativePickRequest,
+} from "./filePickerTypes";

package/src/fields/FileUpload/nativeFilePicker.ts

@@ -0,0 +1,21 @@
+import type { NativePickOutcome, NativePickRequest } from "./filePickerTypes";
+
+/**
+ * Web twin of the native file picker (`nativeFilePicker.native.ts`). The web
+ * field opens a real `<input type="file">`, so this half exists only to keep
+ * `index.tsx` free of a platform branch at import time.
+ */
+export function isNativeFilePickerAvailable(): boolean {
+  return false;
+}
+
+export async function pickFilesNatively(_request: NativePickRequest): Promise<NativePickOutcome> {
+  return { files: [], unavailable: true };
+}
+
+export type {
+  NativePickedFile,
+  NativePickerMode,
+  NativePickOutcome,
+  NativePickRequest,
+} from "./filePickerTypes";

package/src/fields/FileUpload/nativePickerLoader.ts

@@ -0,0 +1,65 @@
+export type DocumentPickerModule = typeof import("expo-document-picker");
+export type ImagePickerModule = typeof import("expo-image-picker");
+
+let cachedDocumentPicker: DocumentPickerModule | null | undefined;
+let cachedImagePicker: ImagePickerModule | null | undefined;
+
+/**
+ * Probes an Expo native module without throwing. Both pickers ship a JS half
+ * that resolves fine in a build whose NATIVE half was never linked (Expo Go,
+ * a consumer that skipped the optional peer); touching the namespace then
+ * throws mid-render. `requireOptionalNativeModule` answers null instead, so
+ * the probe has to happen BEFORE the `require` — a throwing module factory is
+ * reported by Metro's guarded require as a FATAL LogBox in dev even when the
+ * caller catches it (the expo-maps lesson in `expoMapsLoader.ts`).
+ */
+function hasNativeModule(name: string): boolean {
+  try {
+    const core = require("expo-modules-core") as {
+      requireOptionalNativeModule?: (moduleName: string) => unknown;
+    };
+    if (!core.requireOptionalNativeModule) return true;
+    return core.requireOptionalNativeModule(name) != null;
+  } catch {
+    // expo-modules-core absent (non-Expo host) — let the guarded require decide.
+    return true;
+  }
+}
+
+/**
+ * Loads the optional `expo-document-picker` peer at runtime. The `require`
+ * sits inside a try/catch so Metro treats it as an optional dependency
+ * (`transformer.allowOptionalDependencies`, on by default in Expo): bundling
+ * succeeds without the package installed and the call returns null. Only the
+ * native picker twin imports this file — web bundles never reach it.
+ */
+export function loadDocumentPicker(): DocumentPickerModule | null {
+  if (cachedDocumentPicker !== undefined) return cachedDocumentPicker;
+  try {
+    cachedDocumentPicker = hasNativeModule("ExpoDocumentPicker")
+      ? (require("expo-document-picker") as DocumentPickerModule)
+      : null;
+  } catch {
+    cachedDocumentPicker = null;
+  }
+  return cachedDocumentPicker;
+}
+
+/** Same optional-peer contract as `loadDocumentPicker`, for `expo-image-picker`. */
+export function loadImagePicker(): ImagePickerModule | null {
+  if (cachedImagePicker !== undefined) return cachedImagePicker;
+  try {
+    cachedImagePicker = hasNativeModule("ExpoImagePicker")
+      ? (require("expo-image-picker") as ImagePickerModule)
+      : null;
+  } catch {
+    cachedImagePicker = null;
+  }
+  return cachedImagePicker;
+}
+
+/** Test seam: drops the memoized modules so a spec can swap them per case. */
+export function resetNativePickerCache(): void {
+  cachedDocumentPicker = undefined;
+  cachedImagePicker = undefined;
+}

package/src/fields/Geolocation/Geolocation.stories.tsx

@@ -1,4 +1,5 @@
 import { action } from "@multiplatform.one/storybook";
+import { DataTable, type DataTableColumn } from "@multiplatform.one/table";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { ArrowsOutIcon, NavigationArrowIcon } from "@phosphor-icons/react";
 import { useForm } from "@tanstack/react-form";
@@ -266,3 +267,31 @@ export const SkeletonState: Story = {
   render: (args) => <Geolocation {...args} locationIcon={<NavigationArrowIcon size={16} />} />,
   args: { label: "Location", skeleton: true },
 };
+
+type InTableRow = { id: string; label: string; value: { lat: number; lng: number } | "" };
+
+/** LC-06: Geolocation stays hosted in DataTable; the cell opens a modal. */
+export const InTable: Story = {
+  name: "In table",
+  render: () => {
+    const [data, setData] = useState<InTableRow[]>([
+      { id: "1", label: "Alpha", value: { lat: 30.2672, lng: -97.7431 } },
+      { id: "2", label: "Beta", value: { lat: 48.8566, lng: 2.3522 } },
+      { id: "3", label: "Gamma", value: "" },
+    ]);
+    const columns: DataTableColumn<InTableRow>[] = [
+      { accessorKey: "label", header: "Row" },
+      {
+        accessorKey: "value",
+        header: "Location",
+        field: "geolocation",
+        fieldProps: { locationIcon: <NavigationArrowIcon size={16} /> },
+      },
+    ];
+    return (
+      <YStack width="100%" height={320}>
+        <DataTable data={data} columns={columns} enablePagination={false} onDataChange={setData} />
+      </YStack>
+    );
+  },
+};

package/src/fields/Icon/Icon.spec.tsx

@@ -0,0 +1,67 @@
+import { act, fireEvent, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Icon } from "./index";
+
+describe("Icon", () => {
+  it("renders an icon control, not an unsupported-type string", () => {
+    const result = renderWithProviders(<Icon label="Workspace icon" value="mail" />);
+    const text = result.container.textContent ?? "";
+    expect(text).not.toMatch(/Unsupported field type/);
+    expect(result.container.querySelector('[data-testid="icon-field"]')).toBeTruthy();
+    const input = result.container.querySelector("input") as HTMLInputElement | null;
+    expect(input?.value).toBe("mail");
+  });
+
+  it("shows a dashed well when empty", () => {
+    const result = renderWithProviders(
+      <Icon label="Workspace icon" placeholder="Choose an icon" />,
+    );
+    expect(result.container.querySelector('[data-testid="icon-empty-well"]')).toBeTruthy();
+    const input = result.container.querySelector("input") as HTMLInputElement | null;
+    expect(input?.getAttribute("placeholder")).toBe("Choose an icon");
+  });
+
+  it("read-only renders the glyph well without a picker trigger", () => {
+    const result = renderWithProviders(<Icon label="Workspace icon" value="mail" readOnly />);
+    expect(result.container.querySelector('[data-testid="icon-field-readonly"]')).toBeTruthy();
+    expect(result.container.querySelector('[data-testid="icon-field"]')).toBeNull();
+    expect(result.container.textContent ?? "").not.toMatch(/Unsupported field type/);
+  });
+
+  it("opens a FloatingPanel grid and commits a drawn-set pick", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <Icon label="Workspace icon" value="" placeholder="Choose an icon" onChange={onChange} />,
+    );
+
+    const input = result.container.querySelector("input");
+    expect(input).toBeTruthy();
+    await act(async () => {
+      if (input) fireEvent.click(input);
+    });
+
+    await waitFor(() => {
+      expect(document.body.querySelector('[data-testid="icon-panel"]')).toBeTruthy();
+    });
+
+    const mail = document.body.querySelector('[data-testid="icon-option-mail"]');
+    expect(mail).toBeTruthy();
+    await act(async () => {
+      if (mail) fireEvent.click(mail);
+    });
+
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalledWith("mail");
+    });
+  });
+
+  it("does not paint typed icon glyphs in the trigger", () => {
+    const result = renderWithProviders(<Icon label="Workspace icon" value="mail" />);
+    const text = result.container.textContent ?? "";
+    for (const glyph of ["∨", "∧", "✓", "×", "▸", "☰"]) {
+      expect(text).not.toContain(glyph);
+    }
+    expect(result.container.querySelector("svg")).toBeTruthy();
+  });
+});

package/src/fields/Icon/Icon.stories.tsx

@@ -0,0 +1,59 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { YStack } from "tamagui";
+import { Icon } from "./index";
+
+const meta: Meta<typeof Icon> = {
+  title: "Forms/Icon",
+  component: Icon,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Icon picker over FloatingPanel. Options come from the DG-IDN-06 drawn set. Field-shaped panel matches the trigger width.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Icon>;
+
+export const Main: Story = {
+  name: "Main",
+  render: () => {
+    const Example = () => {
+      const [value, setValue] = useState("mail");
+      return (
+        <YStack gap="$4" width={320}>
+          <Icon
+            label="Workspace icon"
+            value={value}
+            onChange={(next) => {
+              setValue(next);
+              action("onChange")(next);
+            }}
+          />
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};
+
+export const Empty: Story = {
+  render: () => (
+    <YStack width={320}>
+      <Icon label="Workspace icon" placeholder="Choose an icon" />
+    </YStack>
+  ),
+};
+
+export const ReadOnly: Story = {
+  render: () => (
+    <YStack width={320}>
+      <Icon label="Workspace icon" value="upload" readOnly />
+    </YStack>
+  ),
+};

package/src/fields/Icon/drawnSet.spec.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import {
+  DRAWN_ICON_NAMES,
+  filterDrawnIcons,
+  isDrawnIconName,
+  parseIconOptions,
+  resolveIconCatalog,
+} from "./drawnSet";
+
+describe("drawn icon set (DG-IDN-06)", () => {
+  it("exposes the measured console-sheet names and no more", () => {
+    expect(DRAWN_ICON_NAMES).toEqual([
+      "chev-d",
+      "chev-r",
+      "chev-l",
+      "x",
+      "check",
+      "warn",
+      "arr-d",
+      "copy",
+      "disk",
+      "grip",
+      "chev-u",
+      "arr-u",
+      "arr-r",
+      "upload",
+      "mail",
+      "menu",
+    ]);
+  });
+
+  it("rejects names that are not in the drawn set", () => {
+    expect(isDrawnIconName("mail")).toBe(true);
+    expect(isDrawnIconName("scan")).toBe(false);
+    expect(isDrawnIconName("×")).toBe(false);
+  });
+
+  it("filters the catalog by name substring", () => {
+    expect(filterDrawnIcons(DRAWN_ICON_NAMES, "arr")).toEqual(["arr-d", "arr-u", "arr-r"]);
+    expect(filterDrawnIcons(DRAWN_ICON_NAMES, "zzz")).toEqual([]);
+  });
+
+  it("drops unknown df.options names instead of inventing glyphs", () => {
+    expect(parseIconOptions("mail\nscan\nupload")).toEqual(["mail", "upload"]);
+    expect(resolveIconCatalog(["mail", "nope"])).toEqual(["mail"]);
+  });
+});