@marimo-team/frontend 0.25.3-dev10 → 0.25.3-dev100

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/core/registerReactComponent.tsx

@@ -104,7 +104,7 @@ function PluginSlotInternal<T>(
   ref: React.Ref<PluginSlotHandle>,
 ): JSX.Element {
   const [childNodes, setChildNodes] = useState<ReactNode>(children);
-  const [value, setValue] = useState<T>(getInitialValue());
+  const [value, setValue] = useState<T>(getInitialValue);
   const { theme } = useTheme();
 
   const [parsedResult, setParsedResult] = useState(() => {

package/src/plugins/impl/CodeEditorPlugin.tsx

@@ -71,7 +71,7 @@ const CodeEditorComponent = (props: CodeEditorComponentProps) => {
   });
 
   const handleChange = useEvent((newValue: string) => {
-    setLocalValue((_) => newValue);
+    setLocalValue(newValue);
     if (typeof props.debounce === "number") {
       setValueDebounced(newValue);
     } else if (!props.debounce) {

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(
     () =>

package/src/plugins/impl/DropdownPlugin.tsx

@@ -97,13 +97,9 @@ const Dropdown = (props: DropdownProps): JSX.Element => {
         id={id}
         disabled={disabled}
       >
-        {allowSelectNone ? (
-          <option value={EMPTY_VALUE} selected={value.length === 0}>
-            --
-          </option>
-        ) : null}
+        {allowSelectNone ? <option value={EMPTY_VALUE}>--</option> : null}
         {options.map((option) => (
-          <option value={option} selected={value.includes(option)} key={option}>
+          <option value={option} key={option}>
             {option}
           </option>
         ))}

package/src/plugins/impl/FileBrowserPlugin.tsx

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { type LucideIcon, ChevronRightIcon, CornerLeftUp } from "lucide-react";
-import { type JSX, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { type JSX, useLayoutEffect, useRef, useState } from "react";
 import { z } from "zod";
 import {
   FILE_ICON as FILE_TYPE_ICONS,
@@ -16,6 +16,7 @@ import { Table, TableBody, TableCell, TableRow } from "@/components/ui/table";
 import { toast } from "@/components/ui/use-toast";
 import { RANDOM_ID_ATTR } from "@/core/dom/ui-element-constants";
 import { useAsyncData } from "@/hooks/useAsyncData";
+import { useDelayElapsed } from "@/hooks/useDelayElapsed";
 import { useInternalStateWithSync } from "@/hooks/useInternalStateWithSync";
 import { cn } from "@/utils/cn";
 import { type FilePath, PathBuilder, Paths } from "@/utils/paths";
@@ -200,7 +201,6 @@ export const FileBrowser = ({
 }: FileBrowserProps): JSX.Element | null => {
   const [path, setPath] = useInternalStateWithSync(initialPath);
   const [isUpdatingPath, setIsUpdatingPath] = useState(false);
-  const [showLoadingOverlay, setShowLoadingOverlay] = useState(false);
   const [activeIndex, setActiveIndex] = useState(0);
   const rowRefs = useRef<(HTMLTableRowElement | null)[]>([]);
   const gridRef = useRef<HTMLTableElement | null>(null);
@@ -219,20 +219,8 @@ export const FileBrowser = ({
     return list_directory({ path: path });
   }, [path, randomId, list_directory]);
 
-  useEffect(() => {
-    if (!isPending) {
-      setShowLoadingOverlay(false);
-      return;
-    }
-
-    const timeout = window.setTimeout(() => {
-      setShowLoadingOverlay(true);
-    }, 200);
-
-    return () => {
-      window.clearTimeout(timeout);
-    };
-  }, [isPending]);
+  const loadingDelayElapsed = useDelayElapsed(isPending ? 200 : 0);
+  const showLoadingOverlay = isPending && loadingDelayElapsed;
 
   // Reset the roving tabindex whenever the listing reloads (a new path or a
   // same-path refresh) so activeIndex never points past the current rows.

package/src/plugins/impl/FormPlugin.tsx

@@ -212,7 +212,7 @@ const Form = ({
   // wrapped plugin; this buffered value is in contrast to the actual
   // value of the plugin, which is the value of the wrapped plugin when
   // the submit button was last clicked/activated.
-  const [internalValue, setInternalValue] = useState<T>(
+  const [internalValue, setInternalValue] = useState<T>(() =>
     UI_ELEMENT_REGISTRY.lookupValue(elementId),
   );
 

package/src/plugins/impl/RangeSliderPlugin.tsx

@@ -74,7 +74,6 @@ const RangeSliderComponent = ({
   start,
   stop,
   step,
-  steps,
   debounce,
   orientation,
   showValue,

package/src/plugins/impl/RefreshPlugin.tsx

@@ -119,6 +119,7 @@ const RefreshComponent = ({ setValue, data }: IPluginProps<Value, Data>) => {
     <Labeled label={data.label}>
       <span className="inline-flex items-center text-secondary-foreground rounded shadow-sm-solid">
         <Button
+          aria-label="Refresh"
           data-testid="marimo-plugin-refresh-button"
           variant="secondary"
           size="icon"

package/src/plugins/impl/SliderPlugin.tsx

@@ -1,8 +1,9 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { type JSX, useEffect, useId, useMemo, useState } from "react";
+import { type JSX, useId, useMemo } from "react";
 import { useLocale } from "react-aria";
 import { z } from "zod";
 import { NumberField } from "@/components/ui/number-field";
+import { useInternalStateWithSync } from "@/hooks/useInternalStateWithSync";
 import { cn } from "@/utils/cn";
 import { clamp } from "@/utils/math";
 import {
@@ -156,13 +157,10 @@ const SliderComponent = ({
   const { locale } = useLocale();
 
   // Hold internal value
-  const [internalValue, setInternalValue] = useState(value);
-  // Update internal value on prop change
-  useEffect(() => {
-    // TODO: Replace this synchronization with a controlled-state primitive.
-    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the editable buffer when the controlled value changes.
-    setInternalValue(value);
-  }, [value]);
+  const [internalValue, setInternalValue] = useInternalStateWithSync(
+    value,
+    Object.is,
+  );
 
   const stepsConfig = useMemo(() => computeStepsConfig(steps), [steps]);
 

package/src/plugins/impl/__tests__/DataTablePlugin.test.tsx

@@ -12,11 +12,13 @@ import {
   waitFor,
 } from "@testing-library/react";
 import { Provider } from "jotai";
+import { useState } from "react";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { SetupMocks } from "@/__mocks__/common";
 import type { DownloadAsFunction } from "@/components/data-table/schemas";
 import type { FieldTypesWithExternalType } from "@/components/data-table/types";
 import { store } from "@/core/state/jotai";
+import { Deferred } from "@/utils/Deferred";
 import {
   type GetDataUrl,
   type GetRowIds,
@@ -463,7 +465,7 @@ describe("LoadingDataTableComponent", () => {
   });
 });
 
-describe("static notebook control suppression", () => {
+describe("table pagination and static notebook control suppression", () => {
   const fieldTypes: FieldTypesWithExternalType = [
     ["id", ["integer", "integer"]],
     ["name", ["string", "string"]],
@@ -538,6 +540,120 @@ describe("static notebook control suppression", () => {
     mockIsStatic.mockReturnValue(false);
   });
 
+  it("requests only the first page with the new configured page size", async () => {
+    const props = makeProps();
+    const view = (pageSize: number) => (
+      <Wrapper>
+        <LoadingDataTableComponent {...props} pageSize={pageSize} />
+      </Wrapper>
+    );
+    const { rerender } = render(view(PAGE_SIZE));
+    await waitFor(() =>
+      expect(screen.getByTestId("next-page-button")).toBeEnabled(),
+    );
+    fireEvent.click(screen.getByTestId("next-page-button"));
+    await waitFor(() =>
+      expect(props.search).toHaveBeenLastCalledWith(
+        expect.objectContaining({ page_number: 1, page_size: PAGE_SIZE }),
+      ),
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("next-page-button")).toBeEnabled(),
+    );
+    props.search.mockClear();
+
+    rerender(view(5));
+    await waitFor(() => expect(props.search).toHaveBeenCalled());
+    expect(
+      props.search.mock.calls.every(
+        ([request]) => request.page_number === 0 && request.page_size === 5,
+      ),
+    ).toBe(true);
+  });
+
+  it("preserves a new page size when a pending response changes the row count in the same batch", async () => {
+    const props = makeProps();
+    const Harness = () => {
+      const [pageSize, setPageSize] = useState(PAGE_SIZE);
+      return (
+        <Wrapper>
+          <button type="button" onClick={() => setPageSize(5)}>
+            Change configured page size
+          </button>
+          <LoadingDataTableComponent {...props} pageSize={pageSize} />
+        </Wrapper>
+      );
+    };
+    render(<Harness />);
+    await waitFor(() =>
+      expect(screen.getByTestId("next-page-button")).toBeEnabled(),
+    );
+    const response = {
+      data: firstPage,
+      total_rows: 25,
+      cell_styles: null,
+      cell_hover_texts: null,
+    };
+    const pendingPage = new Deferred<typeof response>();
+    props.search.mockReturnValueOnce(pendingPage.promise);
+    fireEvent.click(screen.getByTestId("next-page-button"));
+    await waitFor(() =>
+      expect(props.search).toHaveBeenLastCalledWith(
+        expect.objectContaining({ page_number: 1, page_size: PAGE_SIZE }),
+      ),
+    );
+    props.search.mockClear();
+
+    await act(async () => {
+      pendingPage.resolve(response);
+      // Settle the table-loading promises without committing the queued render.
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      fireEvent.click(
+        screen.getByRole("button", { name: "Change configured page size" }),
+      );
+    });
+
+    await waitFor(() => expect(props.search).toHaveBeenCalled());
+    expect(props.search).toHaveBeenLastCalledWith(
+      expect.objectContaining({ page_number: 0, page_size: 5 }),
+    );
+  });
+
+  it("returns to the first page when a refreshed result changes the row count", async () => {
+    const props = makeProps();
+    const view = () => (
+      <Wrapper>
+        <LoadingDataTableComponent {...props} />
+      </Wrapper>
+    );
+    const { rerender } = render(view());
+    await waitFor(() =>
+      expect(screen.getByTestId("next-page-button")).toBeEnabled(),
+    );
+    fireEvent.click(screen.getByTestId("next-page-button"));
+    await waitFor(() =>
+      expect(props.search).toHaveBeenLastCalledWith(
+        expect.objectContaining({ page_number: 1 }),
+      ),
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("next-page-button")).toBeEnabled(),
+    );
+    props.search = vi.fn().mockResolvedValue({
+      data: firstPage,
+      total_rows: 25,
+      cell_styles: null,
+      cell_hover_texts: null,
+    });
+
+    rerender(view());
+    await waitFor(() =>
+      expect(props.search).toHaveBeenLastCalledWith(
+        expect.objectContaining({ page_number: 0, page_size: PAGE_SIZE }),
+      ),
+    );
+  });
+
   it("renders kernel-dependent controls in normal mode", async () => {
     const props = makeProps();
     render(

package/src/plugins/impl/__tests__/FileBrowserPlugin.test.tsx

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import {
+  act,
   fireEvent,
   render,
   screen,
@@ -88,6 +89,50 @@ beforeAll(() => {
 });
 
 describe("FileBrowserPlugin session cache recovery", () => {
+  it("delays the initial loading overlay and hides it when listing completes", async () => {
+    vi.useFakeTimers();
+    try {
+      let resolveListing: (value: {
+        files: MockFile[];
+        total_count: number;
+        is_truncated: boolean;
+      }) => void = () => undefined;
+      const listDirectory = vi.fn(
+        () =>
+          new Promise((resolve) => {
+            resolveListing = resolve;
+          }),
+      );
+      const { unmount } = renderBrowser({ list_directory: listDirectory });
+
+      await act(async () => {
+        vi.advanceTimersByTime(199);
+      });
+      expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
+      await act(async () => {
+        vi.advanceTimersByTime(1);
+      });
+      expect(screen.getByText("Listing files...")).toBeInTheDocument();
+
+      await act(async () => {
+        resolveListing({
+          files: FILES,
+          total_count: FILES.length,
+          is_truncated: false,
+        });
+      });
+      expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
+      expect(screen.getByText("docs")).toBeInTheDocument();
+      await act(async () => {
+        vi.advanceTimersByTime(200);
+      });
+      expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
+      unmount();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("retries a failed cached listing when the plugin resets", async () => {
     const host = document.createElement("marimo-file-browser");
     const wrapper = document.createElement("marimo-ui-element");