@marimo-team/islands 0.25.3-dev51 → 0.25.3-dev55

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

@@ -0,0 +1,257 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
+import {
+  Profiler,
+  startTransition,
+  StrictMode,
+  Suspense,
+  useLayoutEffect,
+  useState,
+} from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import { useStateForKey } from "../useStateForKey";
+
+describe("useStateForKey", () => {
+  it("preserves edits for the same key and creates fresh state on key changes", () => {
+    const initialize = vi.fn(() => new Set<string>());
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, initialize),
+      { initialProps: { key: "first" } },
+    );
+    const initial = result.current[0];
+    act(() => result.current[1](new Set(["expanded"])));
+    rerender({ key: "first" });
+    expect(result.current[0]).toEqual(new Set(["expanded"]));
+    expect(initialize).toHaveBeenCalledOnce();
+
+    rerender({ key: "second" });
+    expect(result.current[0]).toEqual(new Set());
+    expect(result.current[0]).not.toBe(initial);
+    expect(initialize).toHaveBeenCalledTimes(2);
+
+    rerender({ key: "first" });
+    expect(result.current[0]).toEqual(new Set());
+    expect(initialize).toHaveBeenCalledTimes(3);
+  });
+
+  it("preserves queued functional updates and ignores setters from another key", () => {
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, () => 0),
+      { initialProps: { key: "first" } },
+    );
+    const oldSetter = result.current[1];
+    act(() => {
+      result.current[1]((value) => value + 1);
+      result.current[1]((value) => value + 1);
+    });
+    expect(result.current[0]).toBe(2);
+
+    rerender({ key: "second" });
+    const staleUpdate = vi.fn(() => 99);
+    act(() => oldSetter(staleUpdate));
+    act(() => oldSetter(99));
+    expect(result.current[0]).toBe(0);
+    expect(staleUpdate).not.toHaveBeenCalled();
+  });
+
+  it("uses Object.is for NaN and signed zero keys", () => {
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, () => "initial"),
+      { initialProps: { key: Number.NaN } },
+    );
+    act(() => result.current[1]("draft"));
+    rerender({ key: Number.NaN });
+    expect(result.current[0]).toBe("draft");
+
+    rerender({ key: 0 });
+    expect(result.current[0]).toBe("initial");
+    act(() => result.current[1]("draft"));
+    rerender({ key: -0 });
+    expect(result.current[0]).toBe("initial");
+  });
+
+  it("stores function values without invoking them", () => {
+    const initial = vi.fn();
+    const changed = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ key, value }) => useStateForKey(key, () => value),
+      { initialProps: { key: "first", value: initial } },
+    );
+    expect(result.current[0]).toBe(initial);
+    act(() => result.current[1](() => changed));
+    expect(result.current[0]).toBe(changed);
+    rerender({ key: "second", value: initial });
+    expect(result.current[0]).toBe(initial);
+    expect(initial).not.toHaveBeenCalled();
+    expect(changed).not.toHaveBeenCalled();
+  });
+
+  it("uses a changed initializer only after the key changes", () => {
+    const first = vi.fn(() => "first default");
+    const second = vi.fn(() => "second default");
+    const { result, rerender } = renderHook(
+      ({ key, initialize }) => useStateForKey(key, initialize),
+      { initialProps: { key: "A", initialize: first } },
+    );
+    act(() => result.current[1]("draft"));
+    rerender({ key: "A", initialize: second });
+    expect(result.current[0]).toBe("draft");
+    expect(second).not.toHaveBeenCalled();
+    rerender({ key: "B", initialize: second });
+    expect(result.current[0]).toBe("second default");
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it("compares object keys by reference rather than their contents", () => {
+    const key = { id: "A" };
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, () => 0),
+      { initialProps: { key } },
+    );
+    act(() => result.current[1](1));
+    rerender({ key });
+    expect(result.current[0]).toBe(1);
+    rerender({ key: { id: "A" } });
+    expect(result.current[0]).toBe(0);
+  });
+
+  it("keeps setters stable for the same key and accepts old setters when that key returns", () => {
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, () => 0),
+      { initialProps: { key: "A" } },
+    );
+    const setA = result.current[1];
+    act(() => setA(1));
+    rerender({ key: "A" });
+    expect(result.current[1]).toBe(setA);
+    rerender({ key: "B" });
+    expect(result.current[1]).not.toBe(setA);
+    act(() => setA(2));
+    expect(result.current[0]).toBe(0);
+    rerender({ key: "A" });
+    act(() => setA(3));
+    expect(result.current[0]).toBe(3);
+  });
+
+  it("retries the owner without rendering or committing stale state to children", () => {
+    const onOwnerRender = vi.fn();
+    const onChildRender = vi.fn();
+    const onCommit = vi.fn();
+    const onLayout = vi.fn();
+    function Child({ owner, value }: { owner: string; value: string }) {
+      onChildRender(owner, value);
+      useLayoutEffect(() => onLayout(owner, value), [owner, value]);
+      return <span>{value}</span>;
+    }
+    function Owner({ owner }: { owner: string }) {
+      onOwnerRender();
+      const [value, setValue] = useStateForKey(owner, () => `${owner} default`);
+      return (
+        <>
+          <button onClick={() => setValue("draft")}>Edit</button>
+          <Child owner={owner} value={value} />
+        </>
+      );
+    }
+    const content = (owner: string) => (
+      <Profiler id="owner" onRender={onCommit}>
+        <Owner owner={owner} />
+      </Profiler>
+    );
+    const { rerender } = render(content("A"));
+    const button = screen.getByRole("button", { name: "Edit" });
+    fireEvent.click(button);
+    expect(screen.getByText("draft")).toBeInTheDocument();
+    onOwnerRender.mockClear();
+    onChildRender.mockClear();
+    onCommit.mockClear();
+    onLayout.mockClear();
+
+    rerender(content("B"));
+    expect(onOwnerRender.mock.calls.length).toBeGreaterThan(1);
+    expect(onChildRender.mock.calls).toEqual([["B", "B default"]]);
+    expect(onLayout.mock.calls).toEqual([["B", "B default"]]);
+    expect(onCommit).toHaveBeenCalledOnce();
+    expect(screen.getByRole("button", { name: "Edit" })).toBe(button);
+  });
+
+  it("keeps state correct when Strict Mode repeats initialization and updates", () => {
+    const initialize = vi.fn(() => new Set<string>());
+    const { result, rerender } = renderHook(
+      ({ key }) => useStateForKey(key, initialize),
+      { initialProps: { key: "A" }, wrapper: StrictMode },
+    );
+    expect(initialize.mock.calls.length).toBeGreaterThan(1);
+    act(() => result.current[1]((previous) => new Set([...previous, "draft"])));
+    expect(result.current[0]).toEqual(new Set(["draft"]));
+    rerender({ key: "B" });
+    expect(result.current[0]).toEqual(new Set());
+  });
+
+  it.each(["completes", "is canceled"])(
+    "preserves visible edits when a suspended transition %s",
+    async (outcome) => {
+      const pending = new Deferred<void>();
+      let blocked = true;
+      const suspended = vi.fn();
+      function Pending({ owner }: { owner: string }) {
+        if (owner === "B" && blocked) {
+          suspended();
+          throw pending.promise;
+        }
+        return null;
+      }
+      function Owner({ owner }: { owner: string }) {
+        const [value, setValue] = useStateForKey(owner, () => 0);
+        return (
+          <>
+            <button onClick={() => setValue((previous) => previous + 1)}>
+              {owner}:{value}
+            </button>
+            <Pending owner={owner} />
+          </>
+        );
+      }
+      function Harness() {
+        const [owner, setOwner] = useState("A");
+        return (
+          <>
+            <button onClick={() => startTransition(() => setOwner("B"))}>
+              Switch owner
+            </button>
+            <button onClick={() => setOwner("A")}>Keep owner</button>
+            <Suspense fallback="Loading">
+              <Owner owner={owner} />
+            </Suspense>
+          </>
+        );
+      }
+      render(<Harness />);
+      fireEvent.click(screen.getByRole("button", { name: "A:0" }));
+      fireEvent.click(screen.getByRole("button", { name: "Switch owner" }));
+      expect(suspended).toHaveBeenCalled();
+      fireEvent.click(screen.getByRole("button", { name: "A:1" }));
+      expect(screen.getByRole("button", { name: "A:2" })).toBeInTheDocument();
+      if (outcome === "is canceled") {
+        fireEvent.click(screen.getByRole("button", { name: "Keep owner" }));
+      }
+      await act(async () => {
+        blocked = false;
+        pending.resolve();
+        await pending.promise;
+      });
+      expect(
+        screen.getByRole("button", {
+          name: outcome === "completes" ? "B:0" : "A:2",
+        }),
+      ).toBeInTheDocument();
+    },
+  );
+});

package/src/hooks/useDebounce.ts

@@ -2,6 +2,7 @@
 import { debounce } from "lodash-es";
 import { useEffect, useMemo, useState } from "react";
 import useEvent from "react-use-event-hook";
+import { useInternalStateWithSync } from "./useInternalStateWithSync";
 
 export function useDebounce<T>(value: T, delay: number): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);
@@ -41,18 +42,14 @@ export function useDebounceControlledState<T>(opts: {
   disabled?: boolean;
 }) {
   const { initialValue, onChange, delay, disabled } = opts;
-  const [internalValue, setInternalValue] = useState<T>(initialValue);
+  const [internalValue, setInternalValue] = useInternalStateWithSync(
+    initialValue,
+    Object.is,
+  );
   const debouncedValue = useDebounce(internalValue, delay || 200);
 
   const onUpdate = useEvent(onChange);
 
-  // Handle external changes:
-  useEffect(() => {
-    // TODO: Replace this synchronization with a controlled-state primitive.
-    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the debounced draft when the controlled value changes.
-    setInternalValue(initialValue);
-  }, [initialValue]);
-
   // Handle debounced updates for user input
   useEffect(() => {
     if (disabled) {

package/src/hooks/useDeepCompareMemoize.ts

@@ -12,7 +12,7 @@ import React from "react";
  * Useful when the re-render if more expensive than the deep compare.
  */
 export function useDeepCompareMemoize<T>(value: T) {
-  const ref = React.useRef<T>(value);
+  const ref = React.useRef(value);
 
   if (!dequal(value, ref.current)) {
     ref.current = value;

package/src/hooks/useDelayElapsed.ts

@@ -1,6 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { useLayoutEffect, useState } from "react";
+import { useEffect, useState } from "react";
 
 /**
  * Returns `false` until `delayMs` has elapsed since mount (or since `delayMs`
@@ -8,20 +8,24 @@ import { useLayoutEffect, useState } from "react";
  * `delayMs <= 0`. Useful for suppressing spinner/fallback flashes.
  */
 export function useDelayElapsed(delayMs: number): boolean {
-  const [elapsed, setElapsed] = useState(delayMs <= 0);
+  const [timer, setTimer] = useState({ delayMs, elapsed: delayMs <= 0 });
 
-  // Layout effect (not a plain effect) so that when `delayMs` flips from `<= 0`
-  // to `> 0` — e.g. a gate re-closing — we reset `elapsed` to `false` before
-  // the browser paints, rather than briefly flashing the fallback for a frame.
-  useLayoutEffect(() => {
+  // Reset during render so a changed delay never commits a stale `elapsed`
+  // (e.g. a gate re-closing shows no fallback flash before paint)
+  if (!Object.is(timer.delayMs, delayMs)) {
+    setTimer({ delayMs, elapsed: delayMs <= 0 });
+  }
+
+  useEffect(() => {
     if (delayMs <= 0) {
-      setElapsed(true);
       return;
     }
-    setElapsed(false);
-    const timeout = setTimeout(() => setElapsed(true), delayMs);
+    const timeout = setTimeout(
+      () => setTimer({ delayMs, elapsed: true }),
+      delayMs,
+    );
     return () => clearTimeout(timeout);
   }, [delayMs]);
 
-  return elapsed;
+  return timer.elapsed;
 }

package/src/hooks/useInternalStateWithSync.ts

@@ -1,5 +1,5 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { useRef, useState } from "react";
+import { useState } from "react";
 
 type EqualityFn<T> = (a: T, b: T) => boolean;
 
@@ -13,13 +13,13 @@ export function useInternalStateWithSync<T>(
   initial: T,
   equalityFn: EqualityFn<T> = defaultEqualityFn,
 ) {
-  const [state, setState] = useState(initial);
-  const ref = useRef(initial);
+  const [state, setState] = useState(() => initial);
+  const [previousInitial, setPreviousInitial] = useState(() => initial);
 
   // Whenever the outside state changes, update the internal state
-  if (!equalityFn(ref.current, initial)) {
-    setState(initial); // react is ok to setState during render
-    ref.current = initial;
+  if (!equalityFn(previousInitial, initial)) {
+    setState(() => initial);
+    setPreviousInitial(() => initial);
   }
 
   return [state, setState] as const;

package/src/hooks/useScript.ts

@@ -1,90 +1,87 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import React from "react";
+import { useCallback, useSyncExternalStore } from "react";
 
 type ScriptStatus = "loading" | "ready" | "error" | "unknown";
 interface ScriptOptions {
   removeOnUnmount?: boolean;
 }
 
+interface ScriptEntry {
+  element: HTMLScriptElement;
+  listeners: Set<() => void>;
+  /** Whether useScript created the element, and so may remove it. */
+  owned: boolean;
+}
+
 const defaultOptions = { removeOnUnmount: false };
 
+// One entry per src, so reading the status on render is a map lookup
+const scripts = new Map<string, ScriptEntry>();
+
+function findScript(src: string): HTMLScriptElement | undefined {
+  // Compare attributes rather than building a selector, which `src` could break
+  return [...document.scripts].find(
+    (script) => script.getAttribute("src") === src,
+  );
+}
+
+function acquireScript(src: string): ScriptEntry {
+  const cached = scripts.get(src);
+  if (cached?.element.isConnected) {
+    return cached;
+  }
+  const existing = findScript(src);
+  const element = existing ?? document.createElement("script");
+  const entry: ScriptEntry = {
+    element,
+    listeners: new Set(),
+    owned: !existing,
+  };
+  const setStatus = (status: ScriptStatus) => {
+    element.dataset.status = status;
+    entry.listeners.forEach((listener) => listener());
+  };
+  // Listen for the script's lifetime rather than per subscriber, so the
+  // status still settles if the first subscriber unmounts mid-load.
+  element.addEventListener("load", () => setStatus("ready"), { once: true });
+  element.addEventListener("error", () => setStatus("error"), { once: true });
+  if (!existing) {
+    element.src = src;
+    element.async = true;
+    element.dataset.status = "loading";
+    document.body.append(element);
+  }
+  scripts.set(src, entry);
+  return entry;
+}
+
 export function useScript(
   src: string,
   options: ScriptOptions = defaultOptions,
 ) {
-  const [status, setStatus] = React.useState<ScriptStatus>(() => {
-    const existingScript = document.querySelector<HTMLScriptElement>(
-      `script[src="${src}"]`,
-    );
-    return (existingScript?.dataset.status as ScriptStatus) || "unknown";
-  });
-
-  React.useEffect(() => {
-    let script = document.querySelector<HTMLScriptElement>(
-      `script[src="${src}"]`,
-    );
-
-    const updateStatus = (newStatus: ScriptStatus) => {
-      if (script) {
-        script.dataset.status = newStatus;
-        setStatus(newStatus);
-      }
-    };
-
-    const handleScriptLoad = () => updateStatus("ready");
-    const handleScriptError = () => updateStatus("error");
-
-    // observes DOM changes and updates the status
-    const observeScript = (script: HTMLScriptElement) => {
-      const observer = new MutationObserver(() => {
-        const newStatus = script.dataset.status;
-        if (newStatus) {
-          setStatus(newStatus as ScriptStatus);
-        }
-      });
-      observer.observe(script, {
-        attributes: true,
-        attributeFilter: ["data-status"],
-      });
-      return observer;
-    };
-
-    if (!script) {
-      script = document.createElement("script");
-      script.src = src;
-      script.async = true;
-      updateStatus("loading");
-      document.body.append(script);
-
-      script.addEventListener("load", handleScriptLoad);
-      script.addEventListener("error", handleScriptError);
-
-      const observer = observeScript(script);
+  const { removeOnUnmount } = options;
+  const getSnapshot = useCallback((): ScriptStatus => {
+    const cached = scripts.get(src)?.element;
+    const element = cached?.isConnected ? cached : findScript(src);
+    return (element?.dataset.status as ScriptStatus) || "unknown";
+  }, [src]);
 
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const entry = acquireScript(src);
+      entry.listeners.add(onChange);
       return () => {
-        observer.disconnect();
-        if (script) {
-          script.removeEventListener("load", handleScriptLoad);
-          script.removeEventListener("error", handleScriptError);
-
-          if (options.removeOnUnmount) {
-            script.remove();
+        entry.listeners.delete(onChange);
+        if (removeOnUnmount && entry.owned && entry.listeners.size === 0) {
+          entry.element.remove();
+          if (scripts.get(src) === entry) {
+            scripts.delete(src);
           }
         }
       };
-    }
-
-    const domStatus = script.dataset.status;
-    if (domStatus) {
-      if (domStatus === "ready" || domStatus === "error") {
-        return;
-      }
-      const observer = observeScript(script);
-      return () => observer.disconnect();
-    }
-
-    setStatus("unknown");
-  }, [src, options.removeOnUnmount]);
+    },
+    [src, removeOnUnmount],
+  );
 
-  return status;
+  return useSyncExternalStore(subscribe, getSnapshot);
 }

package/src/hooks/useStateForKey.ts

@@ -0,0 +1,93 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { type SetStateAction, useCallback, useReducer } from "react";
+
+interface KeyedState<T> {
+  key: unknown;
+  value: T;
+}
+
+type KeyedAction<T> =
+  | { type: "reset"; state: KeyedState<T> }
+  | { type: "update"; key: unknown; update: SetStateAction<T> };
+
+function reduceKeyedState<T>(
+  previous: KeyedState<T>,
+  action: KeyedAction<T>,
+): KeyedState<T> {
+  if (action.type === "reset") {
+    return action.state;
+  }
+  if (!Object.is(previous.key, action.key)) {
+    return previous;
+  }
+  const value =
+    typeof action.update === "function"
+      ? (action.update as (previous: T) => T)(previous.value)
+      : action.update;
+  return Object.is(previous.value, value)
+    ? previous
+    : { key: action.key, value };
+}
+
+/**
+ * Local state that resets when its owner key changes.
+ *
+ * The key uses Object.is. NaN matches NaN, 0 differs from -0, and objects match
+ * by reference. Keep the key stable between resets. An inline object such as
+ * `{ id }` creates a new key on each render and causes a render loop.
+ *
+ * On a key change, this hook calls initialize() and schedules a state update
+ * during render. React retries the calling component before rendering its
+ * children. Children and effects receive the reset value without an intervening
+ * commit of the old value. This resets only this hook's state. The component
+ * stays mounted, and its other hooks keep their state.
+ *
+ * initialize must be pure. React can call it more than once in Strict Mode or
+ * when retrying an interrupted render. A new initializer alone does not reset
+ * state. The next key change uses the initializer from that render. After
+ * committed key changes A -> B -> A, A starts fresh instead of restoring its
+ * earlier value. If React abandons a pending render for B, the visible state
+ * for A remains intact, including edits made while B was pending.
+ *
+ * The setter accepts values or pure updater functions, like useState. To store
+ * a function, use setValue(() => callback). Its identity is stable for the same
+ * key and changes with the key. Updates from a different key are ignored,
+ * including their updater functions. After A -> B -> A, an old setter for A
+ * can update A again. This hook does not cancel requests. For request results,
+ * use a distinct key for each lifetime so late results stay invalid.
+ *
+ * React can still call the component for ignored or same-value updates.
+ * Render counts do not indicate how many changes React commits to the screen.
+ *
+ * Use useInternalStateWithSync when the external value itself supplies the
+ * reset value. Use this hook when a separate key controls the reset.
+ *
+ * @example
+ * const [expanded, setExpanded] = useStateForKey(tree, () => new Set<string>());
+ *
+ * @see https://react.dev/reference/react/useState#storing-information-from-previous-renders
+ */
+export function useStateForKey<T>(key: unknown, initialize: () => T) {
+  // useState can eagerly evaluate an updater against a suspended render's
+  // state. A reducer checks the key when React processes each render's queue,
+  // so the still-visible owner can accept edits during a transition.
+  const [stored, dispatch] = useReducer(reduceKeyedState<T>, key, (key) => ({
+    key,
+    value: initialize(),
+  }));
+  const current = Object.is(stored.key, key)
+    ? stored
+    : { key, value: initialize() };
+  if (current !== stored) {
+    dispatch({ type: "reset", state: current });
+  }
+
+  const setValue = useCallback(
+    (update: SetStateAction<T>) => {
+      dispatch({ type: "update", key, update });
+    },
+    [key],
+  );
+
+  return [current.value, setValue] as const;
+}

package/src/plugins/impl/DataTablePlugin.tsx

@@ -546,10 +546,12 @@ export const LoadingDataTableComponent = memo(
       }
     }, [setValue, filters, searchQuery, sorting, props.hasStableRowId]);
 
-    // If pageSize changes, reset pagination state
-    useEffect(() => {
+    const [previousPageSize, setPreviousPageSize] = useState(props.pageSize);
+    // Reconcile before requesting data for the updated table configuration.
+    if (previousPageSize !== props.pageSize) {
+      setPreviousPageSize(props.pageSize);
       setPaginationState({ pageIndex: 0, pageSize: props.pageSize });
-    }, [props.pageSize]);
+    }
 
     // Data loading
     const { data, error, isPending, isFetching } = useAsyncData<{
@@ -697,12 +699,13 @@ export const LoadingDataTableComponent = memo(
       [search, sorting, filters, searchQuery],
     );
 
-    // If total rows change, reset pageIndex
-    useEffect(() => {
+    const [previousTotalRows, setPreviousTotalRows] = useState(data?.totalRows);
+    if (previousTotalRows !== data?.totalRows) {
+      setPreviousTotalRows(data?.totalRows);
       setPaginationState((state) =>
         state.pageIndex === 0 ? state : { ...state, pageIndex: 0 },
       );
-    }, [data?.totalRows]);
+    }
 
     // Column summaries
     const { data: columnSummaries, error: columnSummariesError } = useAsyncData<
@@ -835,7 +838,7 @@ const DataTableComponent = ({
   sizeBytesIsLoading,
   maxColumns,
   pagination,
-  selection,
+  selection: requestedSelection,
   value,
   showFilters,
   showDownload,
@@ -843,7 +846,7 @@ const DataTableComponent = ({
   showColumnExplorer,
   showRowExplorer,
   showChartBuilder,
-  showDataTypes,
+  showDataTypes: requestedShowDataTypes,
   rowHeaders,
   fieldTypes,
   paginationState,
@@ -975,15 +978,11 @@ const DataTableComponent = ({
   const fractionDigitsByColumn = useDeepCompareMemoize(computedFractionDigits);
   const shownColumns = memoizedClampedFieldTypes.length;
 
-  // If the field types are not set, we don't show them
-  if (!fieldTypes) {
-    showDataTypes = false;
-  }
+  // Only show data types when they are explicitly supplied.
+  const showDataTypes = Boolean(fieldTypes && requestedShowDataTypes);
 
   // Row/cell selection writes back to the kernel, absent in static exports.
-  if (isStatic) {
-    selection = null;
-  }
+  const selection = isStatic ? null : requestedSelection;
 
   const columns = useMemo(
     () =>