@lotics/ui 5.5.0 → 5.6.1

package/AGENTS.md

@@ -222,10 +222,15 @@ never removes a file. Three reusable primitives back it (the logic is shared; th
 copy stay local):
 - **`useSelectionMode()`** (`@lotics/ui/use_selection_mode`) — `{ active, selected, enter, exit, toggle,
   toggleAll }`, an agnostic multi-select state machine (string ids; pairs with the grid's `selectedIds`).
-- **`shareOrDownloadFiles(files, { title })`** (`@lotics/ui/share_or_download`) — `navigator.share({ files })`
+- **`shareOrDownloadFiles(files, { title, credentials })`** (`@lotics/ui/share_or_download`) — `navigator.share({ files })`
   (mobile → Save to gallery / send to an app), else individual `downloadFileFromUrl` — **never a ZIP**.
-  It shares the BYTES (fetches each presigned URL → `File` at the tap), so URL expiry afterward is moot;
-  the share path needs the host iframe to grant `allow="web-share"` (else it falls back to download).
+  It shares the BYTES (fetches each URL → `File`), so URL expiry afterward is moot; the share path needs the
+  host iframe to grant `allow="web-share"` (else it falls back to download). Best for FAST urls (presigned
+  R2). **For SLOW urls (auth-gated proxy with a server round-trip), split it:** `prepareShareFiles(files,
+  {credentials})` fetches the `File[]` BEFORE the gesture (on menu-open), then `shareFiles(File[])` runs
+  `navigator.share` synchronously on the tap — **iOS Safari rejects `share()` if a slow fetch burns the
+  tap's transient activation**, which silently lands in the download fallback. `prepareShareFiles` throws on
+  a fetch failure (log it, don't swallow); `shareFiles` returns `"shared"|"cancelled"|"unsupported"`.
 - **`rotateImageToBlob(url, degrees)`** (`@lotics/ui/rotate_image`) — canvas-bake a 90° rotation into a
   NEW blob for re-upload (`useImageRotation` is view-only; this is how a rotation is persisted). Pair with
   `FileGalleryModal`'s `onPersistRotation`/`persisting` (the ✓ shown on a rotated image).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "5.5.0",
+  "version": "5.6.1",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/segmented_control.tsx

@@ -178,6 +178,9 @@ const styles = StyleSheet.create({
   track: {
     flexDirection: "row",
     alignSelf: "flex-start",
+    // Match the 40px system control height so it aligns with inputs/buttons in a
+    // toolbar band; segments stretch (alignItems defaults to "stretch") to fill it.
+    height: 40,
     gap: 2,
     padding: 3,
     borderRadius: 10,

package/src/share_or_download.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { shareOrDownloadFiles } from "./share_or_download";
+import { shareOrDownloadFiles, prepareShareFiles, shareFiles } from "./share_or_download";
 
 afterEach(() => {
   vi.restoreAllMocks();
@@ -48,3 +48,45 @@ describe("shareOrDownloadFiles", () => {
     expect(await shareOrDownloadFiles([{ url: "u", filename: "a.png" }])).toEqual({ delivered: "share", count: 0 });
   });
 });
+
+describe("prepareShareFiles + shareFiles (iOS: fetch ahead of the gesture, share synchronously)", () => {
+  it("prepareShareFiles fetches the bytes into File[] with the given credentials", async () => {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => new Response(new Blob(["img"], { type: "image/png" })));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubGlobal("navigator", { canShare: () => true, share: vi.fn() });
+
+    const files = await prepareShareFiles([{ url: "https://api/v1/files/k", filename: "a.png" }], { credentials: "include" });
+
+    expect(files).not.toBeNull();
+    expect(files?.[0]).toBeInstanceOf(File);
+    expect(files?.[0].name).toBe("a.png");
+    expect(fetchMock.mock.calls[0][1]).toMatchObject({ credentials: "include" });
+  });
+
+  it("prepareShareFiles returns null when Web Share (files) is unsupported", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(new Blob(["img"]))));
+    vi.stubGlobal("navigator", {}); // no canShare / share
+    expect(await prepareShareFiles([{ url: "u", filename: "a.png" }])).toBeNull();
+  });
+
+  it("prepareShareFiles THROWS on a fetch failure (caller logs it, not a silent download)", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(null, { status: 401 })));
+    vi.stubGlobal("navigator", { canShare: () => true, share: vi.fn() });
+    await expect(prepareShareFiles([{ url: "u", filename: "a.png" }])).rejects.toThrow(/401/);
+  });
+
+  it("shareFiles shares the SAME pre-fetched File (no re-fetch) and maps cancel/unsupported", async () => {
+    const share = vi.fn(async (_d: { files: File[] }) => undefined);
+    vi.stubGlobal("navigator", { canShare: () => true, share });
+    const file = new File(["x"], "a.png", { type: "image/png" });
+
+    expect(await shareFiles([file], { title: "T" })).toBe("shared");
+    expect(share.mock.calls[0][0].files[0]).toBe(file); // the exact pre-fetched File crosses the boundary
+
+    vi.stubGlobal("navigator", { share: vi.fn(async () => { throw new DOMException("x", "AbortError"); }) });
+    expect(await shareFiles([file])).toBe("cancelled");
+
+    vi.stubGlobal("navigator", {}); // no share
+    expect(await shareFiles([file])).toBe("unsupported");
+  });
+});

package/src/share_or_download.ts

@@ -5,8 +5,15 @@
 //
 // Web Share inside an iframe requires the host to grant `allow="web-share"` on
 // the iframe element; without it `navigator.canShare({ files })` is false and we
-// fall through to downloads. Must be invoked from a user gesture (a click) — the
-// blob fetches happen inside that gesture's task so the share keeps activation.
+// fall through to downloads.
+//
+// iOS Safari quirk: `navigator.share` MUST be called within the tap's *transient
+// activation*. Awaiting a SLOW blob fetch before it (e.g. an auth-gated proxy URL
+// with a server-side R2 round-trip) burns the activation → `share()` rejects →
+// the caller falls back to a download. So for slow URLs, fetch the File[] BEFORE
+// the gesture with `prepareShareFiles`, then call `shareFiles` synchronously on
+// the tap. `shareOrDownloadFiles` is the all-in-one convenience for FAST URLs
+// (presigned R2) where the fetch fits inside the activation window.
 //
 // Pure web, no React Native / @lotics/shared imports — consumable by both the
 // host frontend and sandboxed custom-code apps via the per-file export.
@@ -23,6 +30,10 @@ export type ShareOrDownloadResult =
   | { delivered: "share"; count: number }
   | { delivered: "download"; count: number };
 
+/** "shared" = the sheet completed · "cancelled" = the user dismissed it ·
+ *  "unsupported" = Web Share (files) unavailable. A genuine share failure THROWS. */
+export type ShareFilesResult = "shared" | "cancelled" | "unsupported";
+
 async function toFile(f: ShareableFile, credentials: RequestCredentials): Promise<File> {
   const res = await fetch(f.url, { cache: "no-store", credentials });
   if (!res.ok) throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
@@ -30,6 +41,49 @@ async function toFile(f: ShareableFile, credentials: RequestCredentials): Promis
   return new File([blob], f.filename, { type: f.mimeType || blob.type || "application/octet-stream" });
 }
 
+/**
+ * Fetch `files` into File objects ready for {@link shareFiles}, to be done BEFORE
+ * the share gesture so the share call itself stays synchronous (the iOS note
+ * above). Returns the File[] when Web Share (files) is supported and the set is
+ * shareable; returns `null` when Web Share is unavailable or the set isn't
+ * shareable (the caller should download instead). THROWS if a fetch fails, so the
+ * caller can log the real reason rather than silently downloading.
+ */
+export async function prepareShareFiles(
+  files: ShareableFile[],
+  opts?: { credentials?: RequestCredentials },
+): Promise<File[] | null> {
+  const valid = files.filter((f) => f.url);
+  if (valid.length === 0) return null;
+  const nav = typeof navigator !== "undefined" ? navigator : undefined;
+  if (!nav || typeof nav.canShare !== "function" || typeof nav.share !== "function") return null;
+  const fileObjs = await Promise.all(valid.map((f) => toFile(f, opts?.credentials ?? "same-origin")));
+  if (fileObjs.length === 0 || !nav.canShare({ files: fileObjs })) return null;
+  return fileObjs;
+}
+
+/**
+ * Share already-fetched File objects via the OS sheet. Call SYNCHRONOUSLY from a
+ * user gesture (no awaited fetch before it) so iOS keeps the transient activation.
+ * "cancelled" = user dismissed · "unsupported" = no Web Share; a real failure THROWS.
+ */
+export async function shareFiles(fileObjs: File[], opts?: { title?: string; text?: string }): Promise<ShareFilesResult> {
+  const nav = typeof navigator !== "undefined" ? navigator : undefined;
+  if (!nav || typeof nav.share !== "function" || fileObjs.length === 0) return "unsupported";
+  try {
+    await nav.share({ files: fileObjs, title: opts?.title, text: opts?.text });
+    return "shared";
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") return "cancelled";
+    throw err;
+  }
+}
+
+/**
+ * All-in-one: fetch + share, else download each file (never a ZIP). Best for FAST
+ * URLs (presigned R2) where the fetch fits inside the iOS activation window; for
+ * slow URLs, prepare ahead with {@link prepareShareFiles} + {@link shareFiles}.
+ */
 export async function shareOrDownloadFiles(
   files: ShareableFile[],
   opts?: { title?: string; text?: string; credentials?: RequestCredentials },