@marimo-team/islands 0.23.12-dev1 → 0.23.12-dev10

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

@@ -0,0 +1,314 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { SetupMocks } from "@/__mocks__/common";
+import { initialModeAtom } from "@/core/mode";
+import { store } from "@/core/state/jotai";
+import type { IPluginProps } from "../../types";
+import { FileBrowserPlugin } from "../FileBrowserPlugin";
+
+interface MockFile {
+  id: string;
+  path: string;
+  name: string;
+  is_directory: boolean;
+}
+
+const FILES: MockFile[] = [
+  { id: "1", path: "/home/user/docs", name: "docs", is_directory: true },
+  { id: "2", path: "/home/user/a.txt", name: "a.txt", is_directory: false },
+  { id: "3", path: "/home/user/b.txt", name: "b.txt", is_directory: false },
+];
+
+type Value = MockFile[];
+
+function mockListDirectory(files: MockFile[]) {
+  return vi.fn().mockResolvedValue({
+    files,
+    total_count: files.length,
+    is_truncated: false,
+  });
+}
+
+function makeProps(
+  overrides: {
+    selectionMode?: string;
+    multiple?: boolean;
+    value?: Value;
+    setValue?: (v: Value) => void;
+    files?: MockFile[];
+    list_directory?: ReturnType<typeof vi.fn>;
+    host?: HTMLElement;
+  } = {},
+): IPluginProps<Value, Record<string, unknown>> {
+  const files = overrides.files ?? FILES;
+  const list_directory = overrides.list_directory ?? mockListDirectory(files);
+  return {
+    data: {
+      initialPath: "/home/user",
+      filetypes: [],
+      selectionMode: overrides.selectionMode ?? "all",
+      multiple: overrides.multiple ?? true,
+      label: null,
+      restrictNavigation: false,
+    },
+    value: overrides.value ?? [],
+    setValue: overrides.setValue ?? vi.fn(),
+    host: overrides.host ?? document.createElement("div"),
+    functions: {
+      list_directory,
+    },
+  } as unknown as IPluginProps<Value, Record<string, unknown>>;
+}
+
+function renderBrowser(overrides: Parameters<typeof makeProps>[0] = {}) {
+  const listDirectory =
+    overrides.list_directory ?? mockListDirectory(overrides.files ?? FILES);
+  const result = render(
+    FileBrowserPlugin.render(
+      makeProps({ ...overrides, list_directory: listDirectory }) as Parameters<
+        typeof FileBrowserPlugin.render
+      >[0],
+    ),
+  );
+  return { ...result, listDirectory };
+}
+
+beforeAll(() => {
+  SetupMocks.resizeObserver();
+  store.set(initialModeAtom, "edit");
+});
+
+describe("FileBrowserPlugin keyboard accessibility", () => {
+  it("renders a row per file plus the parent row", async () => {
+    renderBrowser();
+    expect(await screen.findByText("docs")).toBeInTheDocument();
+    // parent "..", docs, a.txt, b.txt
+    expect(screen.getAllByRole("row")).toHaveLength(4);
+  });
+
+  it("marks the list as a multiselectable grid", async () => {
+    renderBrowser({ multiple: true });
+    await screen.findByText("docs");
+    const grid = screen.getByRole("grid");
+    expect(grid).toHaveAttribute("aria-multiselectable", "true");
+  });
+
+  it("does not select a non-selectable file on click (mode=directory)", async () => {
+    const setValue = vi.fn();
+    renderBrowser({ selectionMode: "directory", setValue });
+    const fileCell = await screen.findByText("a.txt");
+    fireEvent.click(fileCell.closest('[role="row"]')!);
+    expect(setValue).not.toHaveBeenCalled();
+  });
+
+  it("labels each selectable checkbox with the file name", async () => {
+    renderBrowser({ selectionMode: "all" });
+    await screen.findByText("docs");
+    expect(
+      screen.getByRole("checkbox", { name: "Select a.txt" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("checkbox", { name: "Select docs" }),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps checkboxes out of the tab order", async () => {
+    renderBrowser({ selectionMode: "all" });
+    await screen.findByText("docs");
+    expect(
+      screen.getByRole("checkbox", { name: "Select a.txt" }),
+    ).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("places exactly one row in the tab order", async () => {
+    renderBrowser();
+    await screen.findByText("docs");
+    const rows = screen.getAllByRole("row");
+    const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
+    expect(tabbable).toHaveLength(1);
+    // the parent row is first and starts active
+    expect(rows[0]).toHaveAttribute("tabindex", "0");
+  });
+
+  it("resets the active row to the parent row after navigating", async () => {
+    renderBrowser({ selectionMode: "all" });
+    const docs = await screen.findByText("docs");
+    const docsRow = docs.closest('[role="row"]')!;
+    fireEvent.keyDown(docsRow, { key: "ArrowDown" }); // move active off the parent
+    fireEvent.click(docs); // navigate into "docs"
+    await screen.findByText("docs"); // listing reloads (mock returns same files)
+    const rows = screen.getAllByRole("row");
+    expect(rows[0]).toHaveAttribute("tabindex", "0");
+    // the focused row must match the only tabbable row
+    expect(rows[0]).toHaveFocus();
+  });
+
+  it("resets the active row when the listing refreshes in place", async () => {
+    // The cell's random-id changes when the cell re-renders, refetching the
+    // same path. A shrinking listing must not leave activeIndex out of bounds.
+    const parent = document.createElement("div");
+    parent.setAttribute("random-id", "a");
+    const host = document.createElement("div");
+    parent.append(host);
+    document.body.append(parent);
+
+    const list_directory = vi
+      .fn()
+      .mockResolvedValueOnce({
+        files: FILES,
+        total_count: FILES.length,
+        is_truncated: false,
+      })
+      .mockResolvedValue({
+        files: [FILES[0]],
+        total_count: 1,
+        is_truncated: false,
+      });
+
+    const props = () =>
+      FileBrowserPlugin.render(
+        makeProps({ host, list_directory }) as Parameters<
+          typeof FileBrowserPlugin.render
+        >[0],
+      );
+    const { rerender } = render(props());
+    await screen.findByText("a.txt");
+
+    // Move the active row to the last row, then trigger a same-path refresh.
+    fireEvent.keyDown(screen.getAllByRole("row")[0], { key: "End" });
+    expect(screen.getAllByRole("row").at(-1)).toHaveAttribute("tabindex", "0");
+
+    parent.setAttribute("random-id", "b");
+    rerender(props());
+
+    await waitFor(() =>
+      // parent ".." plus the single remaining file
+      expect(screen.getAllByRole("row")).toHaveLength(2),
+    );
+    const rows = screen.getAllByRole("row");
+    const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
+    expect(tabbable).toHaveLength(1);
+    expect(rows[0]).toHaveAttribute("tabindex", "0");
+  });
+
+  it("syncs the tabbable row to whichever row gains focus", async () => {
+    renderBrowser();
+    await screen.findByText("docs");
+    const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+    expect(rows[0]).toHaveAttribute("tabindex", "0");
+
+    fireEvent.focus(rows[2]); // e.g. focus from a mouse click, not arrow keys
+    expect(rows[2]).toHaveAttribute("tabindex", "0");
+    expect(rows[0]).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("moves focus to the parent row after navigating from within the grid", async () => {
+    // Navigating into a directory unmounts the focused row; focus must follow
+    // to the parent row instead of falling back to the document body.
+    const list_directory = vi
+      .fn()
+      .mockResolvedValueOnce({
+        files: FILES,
+        total_count: FILES.length,
+        is_truncated: false,
+      })
+      .mockResolvedValue({
+        files: [
+          {
+            id: "99",
+            path: "/home/user/docs/inner.txt",
+            name: "inner.txt",
+            is_directory: false,
+          },
+        ],
+        total_count: 1,
+        is_truncated: false,
+      });
+    renderBrowser({ selectionMode: "all", list_directory });
+    await screen.findByText("docs");
+
+    const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+    fireEvent.keyDown(rows[0], { key: "ArrowDown" }); // focus the docs row
+    expect(rows[1]).toHaveFocus();
+    fireEvent.keyDown(rows[1], { key: "Enter" }); // navigate into docs
+
+    await screen.findByText("inner.txt");
+    expect(screen.getAllByRole("row")[0]).toHaveFocus();
+  });
+
+  it("moves focus with arrows and clamps at the ends", async () => {
+    renderBrowser();
+    await screen.findByText("docs");
+    const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+
+    fireEvent.keyDown(rows[0], { key: "ArrowDown" });
+    expect(rows[1]).toHaveFocus();
+    expect(rows[1]).toHaveAttribute("tabindex", "0");
+
+    fireEvent.keyDown(rows[1], { key: "ArrowUp" });
+    expect(rows[0]).toHaveFocus();
+
+    fireEvent.keyDown(rows[0], { key: "ArrowUp" }); // clamp at top
+    expect(rows[0]).toHaveFocus();
+
+    fireEvent.keyDown(rows[0], { key: "End" });
+    expect(rows[3]).toHaveFocus();
+
+    fireEvent.keyDown(rows[3], { key: "ArrowDown" }); // clamp at bottom
+    expect(rows[3]).toHaveFocus();
+
+    fireEvent.keyDown(rows[3], { key: "Home" });
+    expect(rows[0]).toHaveFocus();
+  });
+
+  it("Enter navigates into a directory", async () => {
+    const setValue = vi.fn();
+    const { listDirectory } = renderBrowser({
+      selectionMode: "all",
+      setValue,
+    });
+    await screen.findByText("docs");
+    fireEvent.keyDown(rowFor("docs"), { key: "Enter" });
+    await waitFor(() =>
+      expect(listDirectory).toHaveBeenCalledWith({ path: "/home/user/docs" }),
+    );
+    // navigation does not mutate value
+    expect(setValue).not.toHaveBeenCalled();
+  });
+
+  it("Enter toggles selection on a selectable file", async () => {
+    const setValue = vi.fn();
+    renderBrowser({ selectionMode: "all", multiple: true, setValue });
+    await screen.findByText("a.txt");
+    fireEvent.keyDown(rowFor("a.txt"), { key: "Enter" });
+    expect(setValue).toHaveBeenCalledWith([
+      expect.objectContaining({ path: "/home/user/a.txt" }),
+    ]);
+  });
+
+  it("Space toggles selection and never navigates", async () => {
+    const setValue = vi.fn();
+    renderBrowser({ selectionMode: "all", multiple: true, setValue });
+    await screen.findByText("docs");
+    // Space on a selectable directory selects it (does not navigate)
+    fireEvent.keyDown(rowFor("docs"), { key: " " });
+    expect(setValue).toHaveBeenCalledWith([
+      expect.objectContaining({ path: "/home/user/docs" }),
+    ]);
+  });
+
+  it("Space on the parent row is a no-op", async () => {
+    const setValue = vi.fn();
+    renderBrowser({ selectionMode: "all", setValue });
+    await screen.findByText("docs");
+    const parentRow = screen.getAllByRole("row")[0];
+    fireEvent.keyDown(parentRow, { key: " " });
+    expect(setValue).not.toHaveBeenCalled();
+  });
+});
+
+function rowFor(name: string): HTMLElement {
+  return screen.getByText(name).closest('[role="row"]') as HTMLElement;
+}

package/src/plugins/impl/matplotlib/matplotlib-renderer.ts

@@ -292,7 +292,7 @@ export class MatplotlibRenderer {
     // Configure container
     container.tabIndex = -1;
     container.role = "application";
-    container.className = "relative inline-block select-none outline-none";
+    container.className = "relative inline-block select-none outline-hidden";
 
     // Create canvas
     const canvas = document.createElement("canvas");

package/src/plugins/impl/mpl-interactive/MplInteractivePlugin.tsx

@@ -174,99 +174,99 @@ const MplInteractiveSlot = (props: IPluginProps<ModelIdRef, Data>) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const figureRef = useRef<MplFigure | null>(null);
   const wsRef = useRef<MplCommWebSocket | null>(null);
+  // Sends to the currently bound backend model. Re-pointed on every (re)bind
+  // so the persistent socket and toolbar downloads always reach the live comm.
+  const sendRef = useRef<(msg: unknown) => void>(Functions.NOOP);
+  // Detaches the model bound by the most recent bindModel call. Shared between
+  // the mount and rebind effects so a rerun disposes the prior model's
+  // listener before attaching the next one (never stacking listeners).
+  const boundModelCleanupRef = useRef<(() => void) | undefined>(undefined);
+  // Latest model id, read by the mount effect without being a dependency:
+  // the figure is built once, and switching to a new model is the rebind
+  // effect's job, not a reason to tear the canvas down.
+  const modelIdRef = useRef(modelId);
+  modelIdRef.current = modelId;
+  // The data attributes are re-parsed into fresh objects on every rerun, so
+  // `toolbarImages` changes identity even when its contents do not. Read it
+  // from a ref so it can't retrigger the mount effect and rebuild the canvas.
+  const toolbarImagesRef = useRef(toolbarImages);
+  toolbarImagesRef.current = toolbarImages;
+
+  // Bind the already-rendered figure/socket to a backend model, leaving the
+  // DOM, figure, and socket in place so they survive across reruns. Disposes
+  // the previously bound model first and records the new cleanup in
+  // boundModelCleanupRef, so exactly one model listener is ever attached.
+  const bindModel = useCallback(async (id: WidgetModelId): Promise<void> => {
+    const fakeWs = wsRef.current;
+    if (!fakeWs) {
+      return;
+    }
 
-  const setupFigure = useCallback(
-    async (container: HTMLElement) => {
-      // Load mpl.js globally (only once, via <script src>)
-      await ensureMplJs(mplJsUrl);
+    let model: Model<ModelState>;
+    try {
+      model = await MODEL_MANAGER.get(id);
+    } catch {
+      Logger.error("Failed to get model for mpl interactive", id);
+      return;
+    }
 
-      if (!window.mpl) {
-        Logger.error("mpl.js failed to load");
-        return;
-      }
+    // The figure may have been torn down (unmount, or a structural rebuild)
+    // while we awaited the model; don't wire a listener that would outlive it.
+    if (wsRef.current !== fakeWs) {
+      return;
+    }
 
-      // Get the model from MODEL_MANAGER
-      let model: Model<ModelState>;
-      try {
-        model = await MODEL_MANAGER.get(modelId);
-      } catch {
-        Logger.error("Failed to get model for mpl interactive", modelId);
+    // Detach the previously bound model before wiring the new one.
+    boundModelCleanupRef.current?.();
+
+    // Re-point outbound traffic at this model without recreating the socket,
+    // so mpl.js's onopen/onmessage wiring stays intact.
+    const send = (msg: unknown) => model.send(msg);
+    fakeWs.setSendHandler(send);
+    sendRef.current = send;
+
+    // Listen for backend → frontend messages via model custom events
+    const handleCustomMessage = (
+      content: { type: string; data?: unknown; format?: string },
+      buffers?: readonly DataView[],
+    ) => {
+      if (!content) {
         return;
       }
 
-      // Create the fake WebSocket
-      const fakeWs = new MplCommWebSocket((msg: unknown) => {
-        // Send from frontend → backend via model custom message
-        model.send(msg);
-      });
-      wsRef.current = fakeWs;
-
-      // Listen for backend → frontend messages via model custom events
-      const handleCustomMessage = (
-        content: { type: string; data?: unknown; format?: string },
-        buffers?: readonly DataView[],
-      ) => {
-        if (!content) {
-          return;
-        }
-
-        if (content.type === "json") {
-          fakeWs.receiveJson(content.data);
-        } else if (content.type === "binary" && buffers && buffers.length > 0) {
-          fakeWs.receiveBinary(buffers[0]);
-        } else if (
-          content.type === "download" &&
-          buffers &&
-          buffers.length > 0
-        ) {
-          const fmt = content.format || "png";
-          const dv = buffers[0];
-          const ab = dv.buffer.slice(
-            dv.byteOffset,
-            dv.byteOffset + dv.byteLength,
-          ) as ArrayBuffer;
-          downloadBlob(
-            new Blob([ab], { type: `image/${fmt}` }),
-            `figure.${fmt}`,
-          );
-        }
-      };
+      if (content.type === "json") {
+        fakeWs.receiveJson(content.data);
+      } else if (content.type === "binary" && buffers && buffers.length > 0) {
+        fakeWs.receiveBinary(buffers[0]);
+      } else if (content.type === "download" && buffers && buffers.length > 0) {
+        const fmt = content.format || "png";
+        const dv = buffers[0];
+        const ab = dv.buffer.slice(
+          dv.byteOffset,
+          dv.byteOffset + dv.byteLength,
+        ) as ArrayBuffer;
+        downloadBlob(new Blob([ab], { type: `image/${fmt}` }), `figure.${fmt}`);
+      }
+    };
 
-      model.on("msg:custom", handleCustomMessage as any);
+    model.on("msg:custom", handleCustomMessage as any);
 
-      // Create the mpl figure
-      const figId = modelId;
-      const ondownload = (_figure: MplFigure, format: string) => {
-        // Send download request to backend
-        model.send({ type: "download", format });
-      };
+    // Replay the mpl.js handshake against the new comm so the backend
+    // re-establishes image mode and pushes a frame. The figure DOM and the
+    // backend manager's toolbar state are left untouched.
+    fakeWs.onopen?.();
 
-      const fig = new window.mpl.figure(figId, fakeWs, ondownload, container);
-      figureRef.current = fig;
-
-      // Set the canvas_div to the backend's figure size so the
-      // ResizeObserver doesn't trigger an immediate resize cycle.
-      // mpl.js creates: fig.root > [titlebar, canvas_div, toolbar]
-      const canvasDiv = fig.root.querySelector<HTMLElement>("div[tabindex]");
-      if (canvasDiv) {
-        canvasDiv.style.width = `${width}px`;
-        canvasDiv.style.height = `${height}px`;
+    boundModelCleanupRef.current = () => {
+      model.off("msg:custom", handleCustomMessage as any);
+      if (sendRef.current === send) {
+        sendRef.current = Functions.NOOP;
       }
+    };
+  }, []);
 
-      // Trigger the onopen callback to start communication
-      // mpl.js sends initial messages in onopen
-      setTimeout(() => {
-        fakeWs.onopen?.();
-      }, 0);
-
-      return () => {
-        model.off("msg:custom", handleCustomMessage as any);
-        fakeWs.close();
-      };
-    },
-    [modelId, mplJsUrl, width, height],
-  );
-
+  // Mount: build the DOM, mpl figure, and socket once. modelId is read from a
+  // ref and intentionally omitted from the deps — rebinding to a new model is
+  // handled by the effect below, not by rebuilding the canvas.
   useEffect(() => {
     const container = containerRef.current;
     if (!container) {
@@ -280,34 +280,90 @@ const MplInteractiveSlot = (props: IPluginProps<ModelIdRef, Data>) => {
     const removeCss = injectCss(container, cssUrl);
 
     // Patch toolbar images
-    const removeImageObserver = patchToolbarImages(container, toolbarImages);
+    const removeImageObserver = patchToolbarImages(
+      container,
+      toolbarImagesRef.current,
+    );
 
-    let cleanup: (() => void) | undefined;
     let cancelled = false;
 
-    setupFigure(container)
-      .then((cleanupFn) => {
-        if (cancelled) {
-          cleanupFn?.();
-          return;
-        }
-        cleanup = cleanupFn;
-      })
-      .catch((error) => {
-        if (!cancelled) {
-          Logger.error("Failed to set up MPL interactive figure", error);
-        }
+    const setup = async () => {
+      // Load mpl.js globally (only once, via <script src>)
+      await ensureMplJs(mplJsUrl);
+
+      if (!window.mpl) {
+        Logger.error("mpl.js failed to load");
+        return;
+      }
+
+      // The send handler is swapped per bind; route through sendRef so the
+      // socket outlives any single model.
+      const fakeWs = new MplCommWebSocket((msg: unknown) => {
+        sendRef.current(msg);
       });
+      wsRef.current = fakeWs;
+
+      const ondownload = (_figure: MplFigure, format: string) => {
+        sendRef.current({ type: "download", format });
+      };
+
+      const fig = new window.mpl.figure(
+        modelIdRef.current,
+        fakeWs,
+        ondownload,
+        container,
+      );
+      figureRef.current = fig;
+
+      // Set the canvas_div to the backend's figure size so the
+      // ResizeObserver doesn't trigger an immediate resize cycle.
+      // mpl.js creates: fig.root > [titlebar, canvas_div, toolbar]
+      const canvasDiv = fig.root.querySelector<HTMLElement>("div[tabindex]");
+      if (canvasDiv) {
+        canvasDiv.style.width = `${width}px`;
+        canvasDiv.style.height = `${height}px`;
+      }
+
+      await bindModel(modelIdRef.current);
+    };
+
+    setup().catch((error) => {
+      if (!cancelled) {
+        Logger.error("Failed to set up MPL interactive figure", error);
+      }
+    });
 
     return () => {
       cancelled = true;
+      boundModelCleanupRef.current?.();
+      boundModelCleanupRef.current = undefined;
       removeCss();
       removeImageObserver();
-      cleanup?.();
+      wsRef.current?.close();
+      wsRef.current = null;
+      figureRef.current = null;
       // Clear DOM on unmount so stale content doesn't linger
       container.innerHTML = "";
     };
-  }, [modelId, cssUrl, toolbarImages, setupFigure]);
+  }, [mplJsUrl, cssUrl, width, height, bindModel]);
+
+  // Rebind to a new model when the cell re-runs, keeping the rendered figure
+  // and toolbar in place. The initial bind is owned by the mount effect, so
+  // skip the first run here.
+  const isInitialBindRef = useRef(true);
+  useEffect(() => {
+    if (isInitialBindRef.current) {
+      isInitialBindRef.current = false;
+      return;
+    }
+
+    // bindModel disposes the previously bound model and guards against a
+    // teardown that races the awaited model lookup, so no per-run cleanup is
+    // needed here; the mount effect's cleanup detaches the final bind.
+    bindModel(modelId).catch((error) => {
+      Logger.error("Failed to rebind MPL interactive figure", error);
+    });
+  }, [modelId, bindModel]);
 
   // Re-request figure when tab becomes visible
   useEventListener(document, "visibilitychange", () => {
@@ -324,6 +380,7 @@ const MplInteractiveSlot = (props: IPluginProps<ModelIdRef, Data>) => {
 export const visibleForTesting = {
   ensureMplJs,
   injectCss,
+  MplInteractiveSlot,
   resetMplJsLoading: () => {
     mplJsLoading = null;
   },