@marimo-team/islands 0.19.7-dev23 → 0.19.7-dev25

package/src/utils/__tests__/objects.test.ts

@@ -0,0 +1,263 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import { Objects } from "../objects";
+
+describe("Objects", () => {
+  describe("EMPTY", () => {
+    it("should be an empty frozen object", () => {
+      expect(Objects.EMPTY).toEqual({});
+      expect(Object.isFrozen(Objects.EMPTY)).toBe(true);
+    });
+  });
+
+  describe("mapValues", () => {
+    it("should map values of an object", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = Objects.mapValues(obj, (v) => v * 2);
+      expect(result).toEqual({ a: 2, b: 4, c: 6 });
+    });
+
+    it("should pass key as second argument", () => {
+      const obj = { a: 1, b: 2 };
+      const result = Objects.mapValues(obj, (v, k) => `${k}:${v}`);
+      expect(result).toEqual({ a: "a:1", b: "b:2" });
+    });
+
+    it("should handle empty objects", () => {
+      const result = Objects.mapValues({}, (v) => v);
+      expect(result).toEqual({});
+    });
+
+    it("should return falsy input unchanged", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect(Objects.mapValues(null as any, (v) => v)).toBe(null);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect(Objects.mapValues(undefined as any, (v) => v)).toBe(undefined);
+    });
+  });
+
+  describe("fromEntries", () => {
+    it("should create object from entries", () => {
+      const entries: [string, number][] = [
+        ["a", 1],
+        ["b", 2],
+      ];
+      expect(Objects.fromEntries(entries)).toEqual({ a: 1, b: 2 });
+    });
+
+    it("should handle empty entries", () => {
+      expect(Objects.fromEntries([])).toEqual({});
+    });
+
+    it("should handle numeric keys", () => {
+      const entries: [number, string][] = [
+        [1, "a"],
+        [2, "b"],
+      ];
+      expect(Objects.fromEntries(entries)).toEqual({ 1: "a", 2: "b" });
+    });
+  });
+
+  describe("entries", () => {
+    it("should return entries of an object", () => {
+      const obj = { a: 1, b: 2 };
+      const entries = Objects.entries(obj);
+      expect(entries).toContainEqual(["a", 1]);
+      expect(entries).toContainEqual(["b", 2]);
+      expect(entries).toHaveLength(2);
+    });
+
+    it("should handle empty objects", () => {
+      expect(Objects.entries({})).toEqual([]);
+    });
+  });
+
+  describe("keys", () => {
+    it("should return keys of an object", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const keys = Objects.keys(obj);
+      expect(keys).toContain("a");
+      expect(keys).toContain("b");
+      expect(keys).toContain("c");
+      expect(keys).toHaveLength(3);
+    });
+
+    it("should handle empty objects", () => {
+      expect(Objects.keys({})).toEqual([]);
+    });
+  });
+
+  describe("size", () => {
+    it("should return the number of keys", () => {
+      expect(Objects.size({ a: 1, b: 2, c: 3 })).toBe(3);
+    });
+
+    it("should return 0 for empty objects", () => {
+      expect(Objects.size({})).toBe(0);
+    });
+  });
+
+  describe("keyBy", () => {
+    it("should key items by specified key function", () => {
+      const items = [
+        { id: "a", value: 1 },
+        { id: "b", value: 2 },
+      ];
+      const result = Objects.keyBy(items, (item) => item.id);
+      expect(result).toEqual({
+        a: { id: "a", value: 1 },
+        b: { id: "b", value: 2 },
+      });
+    });
+
+    it("should skip items with undefined keys", () => {
+      const items = [
+        { id: "a", value: 1 },
+        { id: undefined as unknown as string, value: 2 },
+        { id: "c", value: 3 },
+      ];
+      const result = Objects.keyBy(items, (item) => item.id);
+      expect(result).toEqual({
+        a: { id: "a", value: 1 },
+        c: { id: "c", value: 3 },
+      });
+    });
+
+    it("should handle empty arrays", () => {
+      expect(Objects.keyBy([], (item) => item)).toEqual({});
+    });
+
+    it("should use last item when keys collide", () => {
+      const items = [
+        { id: "a", value: 1 },
+        { id: "a", value: 2 },
+      ];
+      const result = Objects.keyBy(items, (item) => item.id);
+      expect(result).toEqual({ a: { id: "a", value: 2 } });
+    });
+  });
+
+  describe("collect", () => {
+    it("should collect and transform items", () => {
+      const items = [
+        { id: "a", value: 1 },
+        { id: "b", value: 2 },
+      ];
+      const result = Objects.collect(
+        items,
+        (item) => item.id,
+        (item) => item.value * 2,
+      );
+      expect(result).toEqual({ a: 2, b: 4 });
+    });
+
+    it("should handle empty arrays", () => {
+      const result = Objects.collect(
+        [],
+        (item) => item,
+        (item) => item,
+      );
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("groupBy", () => {
+    it("should group items by key", () => {
+      const items = [
+        { category: "a", value: 1 },
+        { category: "b", value: 2 },
+        { category: "a", value: 3 },
+      ];
+      const result = Objects.groupBy(
+        items,
+        (item) => item.category,
+        (item) => item.value,
+      );
+      expect(result).toEqual({
+        a: [1, 3],
+        b: [2],
+      });
+    });
+
+    it("should skip items with undefined keys", () => {
+      const items = [
+        { category: "a", value: 1 },
+        { category: undefined as unknown as string, value: 2 },
+        { category: "a", value: 3 },
+      ];
+      const result = Objects.groupBy(
+        items,
+        (item) => item.category,
+        (item) => item.value,
+      );
+      expect(result).toEqual({ a: [1, 3] });
+    });
+
+    it("should handle empty arrays", () => {
+      const result = Objects.groupBy(
+        [],
+        (item) => item,
+        (item) => item,
+      );
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("filter", () => {
+    it("should filter object entries by predicate", () => {
+      const obj = { a: 1, b: 2, c: 3, d: 4 };
+      const result = Objects.filter(obj, (v) => v % 2 === 0);
+      expect(result).toEqual({ b: 2, d: 4 });
+    });
+
+    it("should pass key as second argument", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = Objects.filter(obj, (_, k) => k !== "b");
+      expect(result).toEqual({ a: 1, c: 3 });
+    });
+
+    it("should handle empty objects", () => {
+      const result = Objects.filter({}, () => true);
+      expect(result).toEqual({});
+    });
+
+    it("should return empty object when nothing matches", () => {
+      const obj = { a: 1, b: 2 };
+      const result = Objects.filter(obj, () => false);
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("omit", () => {
+    it("should omit specified keys from object", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = Objects.omit(obj, ["b"]);
+      expect(result).toEqual({ a: 1, c: 3 });
+    });
+
+    it("should omit multiple keys", () => {
+      const obj = { a: 1, b: 2, c: 3, d: 4 };
+      const result = Objects.omit(obj, ["a", "c"]);
+      expect(result).toEqual({ b: 2, d: 4 });
+    });
+
+    it("should handle keys provided as Set", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = Objects.omit(obj, new Set(["a", "c"] as const));
+      expect(result).toEqual({ b: 2 });
+    });
+
+    it("should handle omitting non-existent keys", () => {
+      const obj = { a: 1, b: 2 };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const result = Objects.omit(obj, ["c" as any]);
+      expect(result).toEqual({ a: 1, b: 2 });
+    });
+
+    it("should return all properties when omitting empty array", () => {
+      const obj = { a: 1, b: 2 };
+      const result = Objects.omit(obj, []);
+      expect(result).toEqual({ a: 1, b: 2 });
+    });
+  });
+});

package/src/utils/__tests__/progress.test.ts

@@ -0,0 +1,156 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it, vi } from "vitest";
+import { ProgressState } from "../progress";
+
+describe("ProgressState", () => {
+  describe("constructor", () => {
+    it("should initialize with a numeric total", () => {
+      const progress = new ProgressState(100);
+      expect(progress.getProgress()).toBe(0);
+    });
+
+    it("should initialize with indeterminate total", () => {
+      const progress = new ProgressState("indeterminate");
+      expect(progress.getProgress()).toBe("indeterminate");
+    });
+  });
+
+  describe("static indeterminate", () => {
+    it("should create an indeterminate progress state", () => {
+      const progress = ProgressState.indeterminate();
+      expect(progress.getProgress()).toBe("indeterminate");
+    });
+  });
+
+  describe("addTotal", () => {
+    it("should add to the total when numeric", () => {
+      const progress = new ProgressState(100);
+      progress.addTotal(50);
+      // Progress is 0, total is now 150
+      expect(progress.getProgress()).toBe(0);
+      progress.increment(75);
+      expect(progress.getProgress()).toBe(50); // 75/150 * 100 = 50
+    });
+
+    it("should convert indeterminate to numeric when adding total", () => {
+      const progress = ProgressState.indeterminate();
+      expect(progress.getProgress()).toBe("indeterminate");
+      progress.addTotal(100);
+      expect(progress.getProgress()).toBe(0);
+    });
+  });
+
+  describe("increment", () => {
+    it("should increment the progress", () => {
+      const progress = new ProgressState(100);
+      progress.increment(25);
+      expect(progress.getProgress()).toBe(25);
+    });
+
+    it("should accumulate multiple increments", () => {
+      const progress = new ProgressState(100);
+      progress.increment(25);
+      progress.increment(25);
+      progress.increment(25);
+      expect(progress.getProgress()).toBe(75);
+    });
+
+    it("should allow progress beyond 100%", () => {
+      const progress = new ProgressState(100);
+      progress.increment(150);
+      expect(progress.getProgress()).toBe(150);
+    });
+  });
+
+  describe("getProgress", () => {
+    it("should return indeterminate for indeterminate state", () => {
+      const progress = ProgressState.indeterminate();
+      progress.increment(50); // increment has no visible effect
+      expect(progress.getProgress()).toBe("indeterminate");
+    });
+
+    it("should return correct percentage", () => {
+      const progress = new ProgressState(200);
+      progress.increment(50);
+      expect(progress.getProgress()).toBe(25); // 50/200 * 100 = 25
+    });
+
+    it("should return 0 when no progress made", () => {
+      const progress = new ProgressState(100);
+      expect(progress.getProgress()).toBe(0);
+    });
+
+    it("should return 100 when complete", () => {
+      const progress = new ProgressState(100);
+      progress.increment(100);
+      expect(progress.getProgress()).toBe(100);
+    });
+  });
+
+  describe("subscribe", () => {
+    it("should notify listeners on increment", () => {
+      const progress = new ProgressState(100);
+      const listener = vi.fn();
+      progress.subscribe(listener);
+
+      progress.increment(25);
+      expect(listener).toHaveBeenCalledWith(25);
+
+      progress.increment(25);
+      expect(listener).toHaveBeenCalledWith(50);
+      expect(listener).toHaveBeenCalledTimes(2);
+    });
+
+    it("should notify listeners on addTotal", () => {
+      const progress = new ProgressState(100);
+      const listener = vi.fn();
+      progress.subscribe(listener);
+
+      progress.addTotal(100);
+      expect(listener).toHaveBeenCalledWith(0); // 0/200 = 0%
+    });
+
+    it("should notify listeners when converting from indeterminate", () => {
+      const progress = ProgressState.indeterminate();
+      const listener = vi.fn();
+      progress.subscribe(listener);
+
+      progress.addTotal(100);
+      expect(listener).toHaveBeenCalledWith(0);
+    });
+
+    it("should return unsubscribe function", () => {
+      const progress = new ProgressState(100);
+      const listener = vi.fn();
+      const unsubscribe = progress.subscribe(listener);
+
+      progress.increment(25);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      progress.increment(25);
+      expect(listener).toHaveBeenCalledTimes(1); // no additional calls
+    });
+
+    it("should support multiple listeners", () => {
+      const progress = new ProgressState(100);
+      const listener1 = vi.fn();
+      const listener2 = vi.fn();
+      progress.subscribe(listener1);
+      progress.subscribe(listener2);
+
+      progress.increment(50);
+      expect(listener1).toHaveBeenCalledWith(50);
+      expect(listener2).toHaveBeenCalledWith(50);
+    });
+
+    it("should pass indeterminate to listeners", () => {
+      const progress = ProgressState.indeterminate();
+      const listener = vi.fn();
+      progress.subscribe(listener);
+
+      progress.increment(50);
+      expect(listener).toHaveBeenCalledWith("indeterminate");
+    });
+  });
+});

package/src/utils/download.ts

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import React from "react";
 import { toast } from "@/components/ui/use-toast";
 import { type CellId, CellOutputId } from "@/core/cells/ids";
 import { getRequestClient } from "@/core/network/requests";
@@ -9,6 +10,8 @@ import { prettyError } from "./errors";
 import { toPng } from "./html-to-image";
 import { captureIframeAsImage } from "./iframe";
 import { Logger } from "./Logger";
+import { ProgressState } from "./progress";
+import { ToastProgress } from "./toast-progress";
 
 /**
  * Show a loading toast while an async operation is in progress.
@@ -16,14 +19,16 @@ import { Logger } from "./Logger";
  */
 export async function withLoadingToast<T>(
   title: string,
-  fn: () => Promise<T>,
+  fn: (progress: ProgressState) => Promise<T>,
 ): Promise<T> {
+  const progress = ProgressState.indeterminate();
   const loadingToast = toast({
     title,
+    description: React.createElement(ToastProgress, { progress }),
     duration: Infinity,
   });
   try {
-    const result = await fn();
+    const result = await fn(progress);
     loadingToast.dismiss();
     return result;
   } catch (error) {

package/src/utils/objects.ts

@@ -32,6 +32,9 @@ export const Objects = {
   keys<K extends string | number>(obj: Record<K, unknown>): K[] {
     return Object.keys(obj) as K[];
   },
+  size<K extends string | number>(obj: Record<K, unknown>): number {
+    return Object.keys(obj).length;
+  },
   /**
    * Type-safe keyBy
    */

package/src/utils/progress.ts

@@ -0,0 +1,61 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+export type ProgressListener = (progress: number | "indeterminate") => void;
+
+export class ProgressState {
+  private progress = 0;
+  private total: number | "indeterminate";
+  private listeners = new Set<ProgressListener>();
+
+  constructor(total: number | "indeterminate") {
+    this.total = total;
+  }
+
+  static indeterminate(): ProgressState {
+    return new ProgressState("indeterminate");
+  }
+
+  addTotal(total: number) {
+    if (this.total === "indeterminate") {
+      this.total = total;
+    } else {
+      this.total += total;
+    }
+    this.notifyListeners();
+  }
+
+  /**
+   * Update the progress by the given increment.
+   */
+  increment(increment: number) {
+    this.progress += increment;
+    this.notifyListeners();
+  }
+
+  /**
+   * Get the progress as a percentage (0-100)
+   */
+  getProgress(): number | "indeterminate" {
+    if (this.total === "indeterminate") {
+      return "indeterminate";
+    }
+    return (this.progress / this.total) * 100;
+  }
+
+  /**
+   * Subscribe to progress updates.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: ProgressListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private notifyListeners() {
+    const progress = this.getProgress();
+    for (const listener of this.listeners) {
+      listener(progress);
+    }
+  }
+}

package/src/utils/toast-progress.tsx

@@ -0,0 +1,41 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { useSyncExternalStore } from "react";
+import { Progress } from "@/components/ui/progress";
+import type { ProgressState } from "./progress";
+
+interface ToastProgressProps {
+  progress: ProgressState;
+  showPercentage?: boolean;
+}
+
+/**
+ * A progress bar component that subscribes to a ProgressState and updates reactively.
+ * Designed to be used inside toasts.
+ */
+export const ToastProgress = ({
+  progress,
+  showPercentage = false,
+}: ToastProgressProps) => {
+  const value = useSyncExternalStore(
+    (callback) => progress.subscribe(callback),
+    () => progress.getProgress(),
+  );
+
+  // if we are at 100%, we want to show the indeterminate progress bar
+  const isIndeterminate = value === "indeterminate" || value === 100;
+
+  return (
+    <div className="mt-2 w-full min-w-[200px]">
+      <Progress
+        value={isIndeterminate ? undefined : value}
+        indeterminate={isIndeterminate}
+      />
+      {!isIndeterminate && showPercentage && (
+        <div className="mt-1 text-xs text-muted-foreground text-right">
+          {Math.round(value)}%
+        </div>
+      )}
+    </div>
+  );
+};