@marimo-team/islands 0.25.3-dev24 → 0.25.3-dev244

package/src/css/globals.css

@@ -55,26 +55,37 @@
     --background: light-dark(hsl(0deg 0% 100%), hsl(150deg 7.7% 10.2%));
     --foreground: light-dark(hsl(222.2deg 47.4% 11.2%), hsl(155deg 7% 93%));
     --muted: light-dark(hsl(210deg 40% 96.1%), hsl(180deg 14% 1%));
-    --muted-foreground: light-dark(hsl(215.4deg 16.3% 46.9%),
-        hsl(155deg 5% 68.3%));
+    --muted-foreground: light-dark(
+      hsl(215.4deg 16.3% 46.9%),
+      hsl(155deg 5% 68.3%)
+    );
     --popover: light-dark(hsl(0deg 0% 100%), hsl(151deg 5.5% 15.2%));
-    --popover-foreground: light-dark(hsl(222.2deg 47.4% 11.2%),
-        hsl(155deg 5% 68.3%));
+    --popover-foreground: light-dark(
+      hsl(222.2deg 47.4% 11.2%),
+      hsl(155deg 5% 68.3%)
+    );
     --card: light-dark(hsl(0deg 0% 100%), hsl(151deg 5.5% 15.2%));
-    --card-foreground: light-dark(hsl(222.2deg 47.4% 11.2%),
-        hsl(155deg 5% 76.3%));
+    --card-foreground: light-dark(
+      hsl(222.2deg 47.4% 11.2%),
+      hsl(155deg 5% 76.3%)
+    );
     --border: light-dark(hsl(214.3deg 31.8% 91.4%), hsl(153deg 3.7% 24.2%));
     --input: light-dark(hsl(0deg 0% 64%), hsl(154deg 3.3% 28.7%));
     --primary: light-dark(hsl(208deg 93.5% 47.4%), hsl(192deg 59.8% 39%));
     --primary-foreground: light-dark(hsl(210deg 40% 98%), hsl(190deg 80% 84%));
     --secondary: light-dark(hsl(210deg 40% 96.1%), hsl(155deg 7% 93%));
-    --secondary-foreground: light-dark(hsl(222.2deg 47.4% 11.2%),
-        hsl(151deg 5.5% 15.2%));
+    --secondary-foreground: light-dark(
+      hsl(222.2deg 47.4% 11.2%),
+      hsl(151deg 5.5% 15.2%)
+    );
     --accent: light-dark(hsl(209deg 100% 96.5%), hsl(192deg 56.6% 26.5%));
     --accent-foreground: light-dark(hsl(211deg 90% 42%), hsl(190deg 80% 84%));
     --ring: hsl(215deg 20.2% 65.1%);
 
     /* Semantic colors. */
+    --brand: light-dark(#365f43, #a8c9ae);
+    --brand-hover: light-dark(#2b5037, #bdd8c2);
+    --brand-foreground: light-dark(#fff, #172b1c);
     --destructive: var(--red-9, #e5484d);
     --destructive-hover: var(--red-10, #dc3e42);
     --destructive-border: var(--red-11, #ce2c31);
@@ -89,6 +100,7 @@
     --action-hover: var(--yellow-10, #ffdc00);
     --action-border: var(--yellow-11, #9e6c00);
     --action-foreground: var(--yellow-12, #473b1f);
+    --search-highlight: var(--yellow-4, #fff394);
     --link: light-dark(hsl(211deg 90% 42%), hsl(211deg 90% 62%));
     --link-visited: light-dark(hsl(272deg 51% 54%), hsl(272deg 51% 74%));
     --stale: hsl(42deg 56% 44% / 25%);
@@ -97,8 +109,10 @@
 
     /* Base shadows. */
     --base-shadow: light-dark(hsl(0deg 0% 85% / 40%), hsla(0deg 0% 36% / 60%));
-    --base-shadow-darker: light-dark(hsl(0deg 0% 50% / 40%),
-        hsl(0deg 0% 50% / 60%));
+    --base-shadow-darker: light-dark(
+      hsl(0deg 0% 50% / 40%),
+      hsl(0deg 0% 50% / 60%)
+    );
     --base-shadow-opacity: 5%;
 
     /* Codemirror editor */
@@ -137,6 +151,7 @@
     --action-hover: var(--yellow-7, #665417);
     --action-border: var(--yellow-11, #f5e147);
     --action-foreground: var(--yellow-12, #f6eeb4);
+    --search-highlight: var(--yellow-6, #524202);
     --stale: hsl(54deg 100% 86.7% / 25%);
   }
 }
@@ -201,6 +216,11 @@
   [role="button"]:not(:disabled) {
     cursor: pointer;
   }
+
+  audio {
+    max-width: 100%;
+    transform: translateZ(0);
+  }
 }
 
 @theme {
@@ -209,40 +229,64 @@
   --shadow-xxs: 0px 0px 2px 0px var(--base-shadow-darker);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-xs: 1px 1px 2px 0px var(--base-shadow), 0px 0px 2px 0px hsl(0deg 0% 25% / var(--base-shadow-opacity));
+  --shadow-xs:
+    1px 1px 2px 0px var(--base-shadow),
+    0px 0px 2px 0px hsl(0deg 0% 25% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-sm: 2px 2px 2px 0px var(--base-shadow), 0px 0px 2px 0px hsl(0deg 0% 25% / var(--base-shadow-opacity));
+  --shadow-sm:
+    2px 2px 2px 0px var(--base-shadow),
+    0px 0px 2px 0px hsl(0deg 0% 25% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-md: 4px 4px 4px 0px var(--base-shadow), 0 0px 4px 0px hsl(0deg 0% 60% / var(--base-shadow-opacity));
+  --shadow-md:
+    4px 4px 4px 0px var(--base-shadow),
+    0 0px 4px 0px hsl(0deg 0% 60% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-lg: 5px 6px 4px 0px var(--base-shadow), 0 0px 4px 0px hsl(0deg 0% 75% / var(--base-shadow-opacity));
+  --shadow-lg:
+    5px 6px 4px 0px var(--base-shadow),
+    0 0px 4px 0px hsl(0deg 0% 75% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-xl: 8px 9px 4px 0px var(--base-shadow), 0 0px 6px 0px hsl(0deg 0% 85% / var(--base-shadow-opacity));
+  --shadow-xl:
+    8px 9px 4px 0px var(--base-shadow),
+    0 0px 6px 0px hsl(0deg 0% 85% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-2xl: 10px 12px 10px 0px var(--base-shadow), 0 0px 8px 0px hsl(0deg 0% 90% / var(--base-shadow-opacity));
+  --shadow-2xl:
+    10px 12px 10px 0px var(--base-shadow),
+    0 0px 8px 0px hsl(0deg 0% 90% / var(--base-shadow-opacity));
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-xs-solid: 1px 1px 0px 0px var(--base-shadow-darker), 0px 0px 2px 0px hsl(0deg 0% 50% / 20%);
+  --shadow-xs-solid:
+    1px 1px 0px 0px var(--base-shadow-darker),
+    0px 0px 2px 0px hsl(0deg 0% 50% / 20%);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-sm-solid: 2px 2px 0px 0px var(--base-shadow-darker), 0px 0px 2px 0px hsl(0deg 0% 50% / 20%);
+  --shadow-sm-solid:
+    2px 2px 0px 0px var(--base-shadow-darker),
+    0px 0px 2px 0px hsl(0deg 0% 50% / 20%);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-md-solid: 4px 4px 0px 0px var(--base-shadow-darker), 0 0px 2px 0px hsl(0deg 0% 60% / 50%);
+  --shadow-md-solid:
+    4px 4px 0px 0px var(--base-shadow-darker),
+    0 0px 2px 0px hsl(0deg 0% 60% / 50%);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-lg-solid: 5px 6px 0px 0px var(--base-shadow-darker), 0 0px 4px 0px hsl(0deg 0% 75% / 50%);
+  --shadow-lg-solid:
+    5px 6px 0px 0px var(--base-shadow-darker),
+    0 0px 4px 0px hsl(0deg 0% 75% / 50%);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-xl-solid: 7px 8px 0px 0px var(--base-shadow-darker), 0 0px 4px 0px hsl(0deg 0% 85% / 50%);
+  --shadow-xl-solid:
+    7px 8px 0px 0px var(--base-shadow-darker),
+    0 0px 4px 0px hsl(0deg 0% 85% / 50%);
 
   /* oxfmt-ignore: definition needs to be oneline or breaks variants */
-  --shadow-2xl-solid: 10px 12px 0px 0px var(--base-shadow-darker), 0 0px 8px 0px hsl(0deg 0% 90% / 50%);
+  --shadow-2xl-solid:
+    10px 12px 0px 0px var(--base-shadow-darker),
+    0 0px 8px 0px hsl(0deg 0% 90% / 50%);
 
   /* Solid shadows with lighter shade color */
 

package/src/hooks/__tests__/useAsyncData.test.tsx

@@ -0,0 +1,148 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, render, renderHook, waitFor } from "@testing-library/react";
+import { Activity } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import { useAsyncData } from "../useAsyncData";
+
+function AsyncDataStatus({ fetch }: { fetch: () => Promise<string> }) {
+  const result = useAsyncData(fetch, []);
+  return (
+    <output
+      data-status={result.status}
+      data-fetching={result.isFetching}
+      data-error={result.error?.message ?? ""}
+    >
+      {result.data}
+    </output>
+  );
+}
+
+describe("useAsyncData", () => {
+  it.each(["success", "error"] as const)(
+    "restarts fetching when Activity reopens after %s",
+    async (initialStatus) => {
+      const initial = new Deferred<string>();
+      const restarted = new Deferred<string>();
+      const fetch = vi
+        .fn(() => restarted.promise)
+        .mockImplementationOnce(() => initial.promise);
+      const view = render(
+        <Activity mode="visible">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+      await act(async () => {
+        if (initialStatus === "success") {
+          initial.resolve("first");
+        } else {
+          initial.reject(new Error("offline"));
+        }
+      });
+      expect(view.getByRole("status").dataset.status).toBe(initialStatus);
+
+      view.rerender(
+        <Activity mode="hidden">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+      view.rerender(
+        <Activity mode="visible">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+
+      expect(fetch).toHaveBeenCalledTimes(2);
+      expect(view.getByRole("status").dataset).toMatchObject({
+        status: initialStatus === "success" ? "loading" : "pending",
+        error: "",
+        fetching: "true",
+      });
+      expect(view.getByRole("status").textContent).toBe(
+        initialStatus === "success" ? "first" : "",
+      );
+      await act(async () => restarted.resolve("latest"));
+      expect(view.getByRole("status").dataset).toMatchObject({
+        status: "success",
+        fetching: "false",
+      });
+      expect(view.getByRole("status").textContent).toBe("latest");
+    },
+  );
+
+  it("ignores a request canceled when Activity hides", async () => {
+    const canceled = new Deferred<string>();
+    const restarted = new Deferred<string>();
+    const fetch = vi
+      .fn(() => restarted.promise)
+      .mockImplementationOnce(() => canceled.promise);
+    const view = render(
+      <Activity mode="visible">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    view.rerender(
+      <Activity mode="hidden">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    view.rerender(
+      <Activity mode="visible">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    expect(fetch).toHaveBeenCalledTimes(2);
+    await act(async () => canceled.resolve("obsolete"));
+    expect(view.getByRole("status").dataset.status).toBe("pending");
+    expect(view.getByRole("status").textContent).toBe("");
+    await act(async () => restarted.resolve("latest"));
+    expect(view.getByRole("status").dataset.status).toBe("success");
+    expect(view.getByRole("status").textContent).toBe("latest");
+  });
+
+  it("preserves data while refetching and ignores obsolete requests", async () => {
+    const requests = [
+      new Deferred<string>(),
+      new Deferred<string>(),
+      new Deferred<string>(),
+    ];
+    const fetch = vi
+      .fn(() => requests[0].promise)
+      .mockImplementationOnce(() => requests[0].promise)
+      .mockImplementationOnce(() => requests[1].promise)
+      .mockImplementationOnce(() => requests[2].promise);
+    const { result, rerender } = renderHook(
+      ({ key }) => useAsyncData(fetch, [key]),
+      { initialProps: { key: 0 } },
+    );
+    expect(result.current.status).toBe("pending");
+    await act(async () => requests[0].resolve("first"));
+    expect(result.current.data).toBe("first");
+    rerender({ key: 1 });
+    expect(result.current).toMatchObject({ status: "loading", data: "first" });
+    rerender({ key: 2 });
+    await act(async () => requests[1].resolve("obsolete"));
+    expect(result.current).toMatchObject({ status: "loading", data: "first" });
+    await act(async () => requests[2].resolve("latest"));
+    expect(result.current).toMatchObject({ status: "success", data: "latest" });
+  });
+
+  it("retries after errors and allows manual updates during a request", async () => {
+    const request = new Deferred<string>();
+    const fetch = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockImplementation(() => request.promise);
+    const { result } = renderHook(() => useAsyncData(fetch, []));
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    act(() => result.current.refetch());
+    expect(result.current.status).toBe("pending");
+    act(() => result.current.setData("manual"));
+    expect(result.current).toMatchObject({ status: "success", data: "manual" });
+    await act(async () => request.resolve("response"));
+    expect(result.current).toMatchObject({
+      status: "success",
+      data: "response",
+    });
+  });
+});

package/src/hooks/__tests__/useDebounce.test.tsx

@@ -121,6 +121,57 @@ describe("useDebounceControlledState", () => {
 
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it("replaces an uncommitted draft when the external value changes", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({
+          initialValue: value,
+          onChange,
+          delay: 1000,
+        }),
+      { initialProps: { value: "initial" } },
+    );
+
+    act(() => result.current.onChange("draft"));
+    rerender({ value: "external" });
+    expect(result.current.value).toBe("external");
+    act(() => vi.runAllTimers());
+    expect(result.current.debouncedValue).toBe("external");
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("handles NaN external values without repeatedly resetting the draft", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({ initialValue: value, onChange }),
+      { initialProps: { value: Number.NaN } },
+    );
+
+    expect(result.current.value).toBeNaN();
+    act(() => result.current.onChange(1));
+    rerender({ value: Number.NaN });
+    expect(result.current.value).toBe(1);
+    rerender({ value: 2 });
+    expect(result.current.value).toBe(2);
+    rerender({ value: Number.NaN });
+    expect(result.current.value).toBeNaN();
+  });
+
+  it("resets the draft when the external value changes from zero to negative zero", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({ initialValue: value, onChange }),
+      { initialProps: { value: 0 } },
+    );
+
+    act(() => result.current.onChange(1));
+    rerender({ value: -0 });
+    expect(result.current.value).toBe(-0);
+  });
 });
 
 describe("useDebouncedCallback", () => {

package/src/hooks/__tests__/useDeepCompareMemoize.test.tsx

@@ -0,0 +1,39 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useDeepCompareMemoize } from "../useDeepCompareMemoize";
+
+describe("useDeepCompareMemoize", () => {
+  it("keeps equal values stable and updates changed values immediately", () => {
+    const initial = { nested: [1, 2] };
+    const { result, rerender } = renderHook(
+      ({ value }) => useDeepCompareMemoize(value),
+      {
+        initialProps: { value: initial },
+      },
+    );
+    rerender({ value: { nested: [1, 2] } });
+    expect(result.current).toBe(initial);
+    const changed = { nested: [1, 3] };
+    rerender({ value: changed });
+    expect(result.current).toBe(changed);
+    rerender({ value: { nested: [1, 3] } });
+    expect(result.current).toBe(changed);
+  });
+
+  it("handles inline callbacks without causing additional renders", () => {
+    let renders = 0;
+    const { result, rerender } = renderHook(
+      ({ value }) => {
+        renders++;
+        return useDeepCompareMemoize({ callback: () => value });
+      },
+      { initialProps: { value: "initial" } },
+    );
+
+    const initialRenders = renders;
+    rerender({ value: "changed" });
+    expect(result.current.callback()).toBe("changed");
+    expect(renders).toBe(initialRenders + 1);
+  });
+});

package/src/hooks/__tests__/useDelayElapsed.test.tsx

@@ -52,4 +52,32 @@ describe("useDelayElapsed", () => {
     // The pending timeout must be cleared, not left dangling.
     expect(vi.getTimerCount()).toBe(0);
   });
+
+  it("handles a NaN delay without resetting on every render", () => {
+    const { result, rerender } = renderHook(() => useDelayElapsed(Number.NaN));
+    expect(result.current).toBe(false);
+
+    act(() => vi.runAllTimers());
+    expect(result.current).toBe(true);
+    rerender();
+    expect(result.current).toBe(true);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("restarts a completed delay after the gate is temporarily disabled", () => {
+    const { result, rerender } = renderHook(
+      ({ delay }) => useDelayElapsed(delay),
+      { initialProps: { delay: 1000 } },
+    );
+    act(() => vi.advanceTimersByTime(1000));
+    expect(result.current).toBe(true);
+    rerender({ delay: 0 });
+    expect(result.current).toBe(true);
+    rerender({ delay: 1000 });
+    expect(result.current).toBe(false);
+    act(() => vi.advanceTimersByTime(999));
+    expect(result.current).toBe(false);
+    act(() => vi.advanceTimersByTime(1));
+    expect(result.current).toBe(true);
+  });
 });

package/src/hooks/__tests__/useInternalStateWithSync.test.tsx

@@ -32,6 +32,26 @@ describe("useInternalStateWithSync", () => {
     expect(result.current[0]).toBe("new value");
   });
 
+  it("preserves function values without calling them and resets when they change", () => {
+    const initial = vi.fn(() => "initial");
+    const draft = vi.fn(() => "draft");
+    const changed = vi.fn(() => "changed");
+    const { result, rerender } = renderHook(
+      ({ value }) => useInternalStateWithSync(value),
+      { initialProps: { value: initial } },
+    );
+
+    expect(result.current[0]).toBe(initial);
+    act(() => result.current[1](() => draft));
+    rerender({ value: initial });
+    expect(result.current[0]).toBe(draft);
+    rerender({ value: changed });
+    expect(result.current[0]).toBe(changed);
+    expect(initial).not.toHaveBeenCalled();
+    expect(draft).not.toHaveBeenCalled();
+    expect(changed).not.toHaveBeenCalled();
+  });
+
   it("should not update internal state if initial value remains the same", () => {
     const { result, rerender } = renderHook(
       ({ value }) => useInternalStateWithSync(value),

package/src/hooks/__tests__/useScript.test.tsx

@@ -0,0 +1,77 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useScript } from "../useScript";
+
+afterEach(() => {
+  document.querySelectorAll("script").forEach((script) => script.remove());
+});
+
+describe("useScript", () => {
+  it("observes loading and completion of a new script", async () => {
+    const { result } = renderHook(() => useScript("/first.js"));
+    expect(result.current).toBe("loading");
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(result.current).toBe("ready");
+  });
+
+  it("uses the new source's status when the source changes", async () => {
+    const { result, rerender } = renderHook(({ src }) => useScript(src), {
+      initialProps: { src: "/first.js" },
+    });
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(result.current).toBe("ready");
+    rerender({ src: "/second.js" });
+    expect(result.current).toBe("loading");
+    await act(async () => {
+      document
+        .querySelector('script[src="/second.js"]')
+        ?.dispatchEvent(new Event("error"));
+    });
+    expect(result.current).toBe("error");
+  });
+
+  it("shares an existing script and only removes scripts it owns", async () => {
+    const owner = renderHook(() =>
+      useScript("/first.js", { removeOnUnmount: true }),
+    );
+    const subscriber = renderHook(() =>
+      useScript("/first.js", { removeOnUnmount: true }),
+    );
+    expect(document.querySelectorAll("script")).toHaveLength(1);
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(subscriber.result.current).toBe("ready");
+    subscriber.unmount();
+    expect(document.querySelectorAll("script")).toHaveLength(1);
+    owner.unmount();
+    expect(document.querySelectorAll("script")).toHaveLength(0);
+  });
+
+  it("settles for remaining subscribers when the first unmounts mid-load", async () => {
+    const first = renderHook(() => useScript("/shared.js"));
+    const second = renderHook(() => useScript("/shared.js"));
+    first.unmount();
+    expect(second.result.current).toBe("loading");
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(second.result.current).toBe("ready");
+    // A later subscriber sees the settled status
+    expect(renderHook(() => useScript("/shared.js")).result.current).toBe(
+      "ready",
+    );
+  });
+
+  it("handles sources that are not valid inside a CSS selector", () => {
+    const src = '/odd"name].js';
+    const { result } = renderHook(() => useScript(src));
+    expect(result.current).toBe("loading");
+    expect(document.querySelector("script")?.getAttribute("src")).toBe(src);
+  });
+});