@marimo-team/frontend 0.23.1-dev8 → 0.23.1

package/src/core/islands/components/__tests__/useIslandControls.test.ts

@@ -0,0 +1,208 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { useIslandControls } from "../useIslandControls";
+
+describe("useIslandControls", () => {
+  beforeEach(() => {
+    // Clean up any event listeners
+    document.body.innerHTML = "";
+  });
+
+  afterEach(() => {
+    // Clean up
+    document.body.innerHTML = "";
+  });
+
+  it("should return false initially when alwaysShowRun is false", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+    expect(result.current).toBe(false);
+  });
+
+  it("should return true initially when alwaysShowRun is true", () => {
+    const { result } = renderHook(() => useIslandControls(true));
+    expect(result.current).toBe(true);
+  });
+
+  it("should return true when Cmd key is pressed (macOS)", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    expect(result.current).toBe(false);
+
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it("should return true when Ctrl key is pressed (Windows/Linux)", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    expect(result.current).toBe(false);
+
+    act(() => {
+      const event = new KeyboardEvent("keydown", { ctrlKey: true });
+      document.dispatchEvent(event);
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it("should return false when Cmd key is released", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Cmd
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Release Cmd
+    act(() => {
+      const event = new KeyboardEvent("keyup", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should return false when Ctrl key is released", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Ctrl
+    act(() => {
+      const event = new KeyboardEvent("keydown", { ctrlKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Release Ctrl
+    act(() => {
+      const event = new KeyboardEvent("keyup", { ctrlKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should return false when Meta key name is released", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Cmd
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Release by key name
+    act(() => {
+      const event = new KeyboardEvent("keyup", { key: "Meta" });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should return false when Control key name is released", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Ctrl
+    act(() => {
+      const event = new KeyboardEvent("keydown", { ctrlKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Release by key name
+    act(() => {
+      const event = new KeyboardEvent("keyup", { key: "Control" });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should return false when window loses focus", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Cmd
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Blur window
+    act(() => {
+      const event = new Event("blur");
+      window.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should return false when mouse leaves window", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    // Press Cmd
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Mouse leave
+    act(() => {
+      const event = new Event("mouseleave");
+      window.dispatchEvent(event);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("should not register keyboard event listeners when alwaysShowRun is true", () => {
+    const { result } = renderHook(() => useIslandControls(true));
+
+    expect(result.current).toBe(true);
+
+    // Try to change state with keyboard events - should have no effect
+    act(() => {
+      const event = new KeyboardEvent("keydown", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    act(() => {
+      const event = new KeyboardEvent("keyup", { metaKey: true });
+      document.dispatchEvent(event);
+    });
+    expect(result.current).toBe(true);
+
+    // Blur and mouseleave are also no-ops when alwaysShowRun is true
+    act(() => {
+      window.dispatchEvent(new Event("blur"));
+    });
+    expect(result.current).toBe(true);
+  });
+
+  it("should handle rapid key presses correctly", () => {
+    const { result } = renderHook(() => useIslandControls(false));
+
+    expect(result.current).toBe(false);
+
+    // Multiple rapid presses
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { metaKey: true }));
+      document.dispatchEvent(new KeyboardEvent("keydown", { metaKey: true }));
+      document.dispatchEvent(new KeyboardEvent("keydown", { metaKey: true }));
+    });
+    expect(result.current).toBe(true);
+
+    // Multiple rapid releases
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keyup", { metaKey: true }));
+      document.dispatchEvent(new KeyboardEvent("keyup", { metaKey: true }));
+      document.dispatchEvent(new KeyboardEvent("keyup", { metaKey: true }));
+    });
+    expect(result.current).toBe(false);
+  });
+});

package/src/core/islands/components/output-wrapper.tsx

@@ -2,139 +2,120 @@
 
 import { useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
-import { CopyIcon, Loader2Icon, PlayIcon } from "lucide-react";
+import { Loader2Icon } from "lucide-react";
 import React, {
-  type JSX,
   type PropsWithChildren,
   useCallback,
-  useState,
+  useEffect,
+  useRef,
 } from "react";
 import { OutputRenderer } from "@/components/editor/Output";
-import { Button } from "@/components/ui/button";
-import { Tooltip } from "@/components/ui/tooltip";
 import { type NotebookState, notebookAtom } from "@/core/cells/cells";
 import type { CellId } from "@/core/cells/ids";
 import { isOutputEmpty } from "@/core/cells/outputs";
 import type { CellRuntimeState } from "@/core/cells/types";
-import { useRequestClient } from "@/core/network/requests";
-import { useEventListener } from "@/hooks/useEventListener";
-import { copyToClipboard } from "@/utils/copy";
-import { Logger } from "@/utils/Logger";
+import { ISLAND_TAG_NAMES } from "../constants";
+import { IslandControls } from "./IslandControls";
+import { useIslandControls } from "./useIslandControls";
 
-interface Props {
+/**
+ * Props for MarimoOutputWrapper component
+ */
+export interface MarimoOutputWrapperProps {
+  /**
+   * ID of the cell being rendered
+   */
   cellId: CellId;
+
+  /**
+   * Callback to get the current code for the cell
+   */
   codeCallback: () => string;
+
+  /**
+   * Whether to always show the run button (e.g., when editor is present)
+   */
   alwaysShowRun: boolean;
-  children: React.ReactNode;
-}
 
-interface IconButtonProps {
-  tooltip: string;
-  icon: JSX.Element;
-  action: () => void;
+  /**
+   * Initial/static HTML content to display
+   */
+  children: React.ReactNode;
 }
 
-const IconButton: React.FC<IconButtonProps> = ({ tooltip, icon, action }) => (
-  <Tooltip content={tooltip} delayDuration={200}>
-    <Button
-      size="icon"
-      variant="outline"
-      className="bg-background h-5 w-5 mb-0"
-      onClick={action}
-    >
-      {icon}
-    </Button>
-  </Tooltip>
-);
-
-export const MarimoOutputWrapper: React.FC<Props> = ({
+/**
+ * Wraps marimo cell output with interactive controls and status indicators.
+ *
+ * This component:
+ * - Renders cell output from the runtime state
+ * - Shows a loading spinner when the cell is running
+ * - Provides controls to copy code and re-run the cell
+ */
+export const MarimoOutputWrapper: React.FC<MarimoOutputWrapperProps> = ({
   cellId,
   codeCallback,
   alwaysShowRun,
   children,
 }) => {
-  const { sendRun } = useRequestClient();
-  const [pressed, setPressed] = useState<boolean>(alwaysShowRun);
+  const controlsVisible = useIslandControls(alwaysShowRun);
+  const wrapperRef = useRef<HTMLDivElement>(null);
   const selector = useCallback(
     (s: NotebookState) => s.cellRuntime[cellId],
     [cellId],
   );
   const runtime = useAtomValue(selectAtom(notebookAtom, selector));
 
-  // No need to register, if display is default.
-  // Lint still wants use to have the same event listeners per instance (which
-  // makes sense), so noop is used.
-  const maybeNoop = (fn: (e: KeyboardEvent) => void) =>
-    // oxlint-disable-next-line typescript/no-empty-function
-    alwaysShowRun ? () => {} : fn;
-
-  useEventListener(
-    document,
-    "keydown",
-    maybeNoop((e) => {
-      if (!alwaysShowRun && (e.metaKey || e.ctrlKey)) {
-        setPressed(true);
-      }
-    }),
-  );
-  useEventListener(
-    document,
-    "keyup",
-    maybeNoop((e) => {
-      if (
-        !alwaysShowRun &&
-        (e.metaKey || e.ctrlKey || e.key === "Meta" || e.key === "Control")
-      ) {
-        setPressed(false);
-      }
-    }),
-  );
-  // Set pressed to false if the window loses focus
-  useEventListener(window, "blur", () => setPressed(false));
-  useEventListener(window, "mouseleave", () => setPressed(false));
+  // Sync cell status to the host <marimo-island> element as a data attribute
+  // so downstream consumers can style based on status (e.g. [data-status="running"])
+  const status = runtime?.status ?? "idle";
+  useSyncStatusToIsland(wrapperRef, status);
 
+  // If no runtime yet, show static content
   if (!runtime?.output) {
-    return <div className="relative min-h-6 empty:hidden">{children}</div>;
+    return (
+      <div ref={wrapperRef} className="relative min-h-6 empty:hidden">
+        {children}
+      </div>
+    );
   }
 
   // No output to display
-  // Maybe in future, we can configure this to
-  // fallback to displaying the code.
   if (isOutputEmpty(runtime.output)) {
-    return null;
+    return <div ref={wrapperRef} />;
   }
 
   return (
-    <div className="relative min-h-6">
+    <div ref={wrapperRef} className="relative min-h-6">
       <OutputRenderer message={runtime.output} />
-      <Indicator state={runtime} />
-      <div
-        className="absolute top-0 right-0 z-50 flex items-center justify-center gap-1"
-        style={{ display: pressed ? "flex" : "none" }}
-      >
-        <IconButton
-          tooltip="Copy code"
-          icon={<CopyIcon className="size-3" />}
-          action={() => copyToClipboard(codeCallback())}
-        />
-        <IconButton
-          tooltip="Re-run cell"
-          icon={<PlayIcon className="size-3" />}
-          action={async () => {
-            await sendRun({
-              cellIds: [cellId],
-              codes: [codeCallback()],
-            }).catch((error) => {
-              Logger.error(error);
-            });
-          }}
-        />
-      </div>
+      <RunningIndicator state={runtime} />
+      <IslandControls
+        cellId={cellId}
+        codeCallback={codeCallback}
+        visible={controlsVisible}
+      />
     </div>
   );
 };
 
-const Indicator: React.FC<{ state: CellRuntimeState }> = ({ state }) => {
+/**
+ * Sets `data-status` on the closest `<marimo-island>` ancestor whenever the
+ * cell's runtime status changes. This lets page authors style islands with
+ * CSS like `marimo-island[data-status="running"] { opacity: 0.5; }`.
+ */
+function useSyncStatusToIsland(
+  ref: React.RefObject<HTMLDivElement | null>,
+  status: string,
+) {
+  useEffect(() => {
+    const island = ref.current?.closest(ISLAND_TAG_NAMES.ISLAND);
+    island?.setAttribute("data-status", status);
+  }, [ref, status]);
+}
+
+/**
+ * Shows a spinning indicator when the cell is running
+ */
+const RunningIndicator: React.FC<{ state: CellRuntimeState }> = ({ state }) => {
   if (state.status === "running") {
     return (
       <DelayRender>
@@ -148,7 +129,9 @@ const Indicator: React.FC<{ state: CellRuntimeState }> = ({ state }) => {
   return null;
 };
 
-// Render delay for children 200ms, using only css
+/**
+ * Delays rendering of children by 200ms using CSS animation
+ */
 const DelayRender: React.FC<PropsWithChildren> = ({ children }) => {
   return <div className="animate-delayed-show-200">{children}</div>;
 };

package/src/core/islands/components/useIslandControls.ts

@@ -0,0 +1,60 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { useState } from "react";
+import { useEventListener } from "@/hooks/useEventListener";
+
+/**
+ * Hook to manage the visibility of island controls based on keyboard state.
+ *
+ * Controls are shown when:
+ * - alwaysShowRun is true, OR
+ * - User holds Cmd/Ctrl key
+ *
+ * @param alwaysShowRun - If true, controls are always visible
+ * @returns Whether controls should be shown
+ */
+export function useIslandControls(alwaysShowRun: boolean): boolean {
+  const [pressed, setPressed] = useState<boolean>(alwaysShowRun);
+
+  // No need to register if display is always on
+  const maybeNoop = <T>(fn: (e: T) => void) =>
+    // oxlint-disable-next-line typescript/no-empty-function
+    alwaysShowRun ? () => {} : fn;
+
+  useEventListener(
+    document,
+    "keydown",
+    maybeNoop((e: KeyboardEvent) => {
+      if (!alwaysShowRun && (e.metaKey || e.ctrlKey)) {
+        setPressed(true);
+      }
+    }),
+  );
+
+  useEventListener(
+    document,
+    "keyup",
+    maybeNoop((e: KeyboardEvent) => {
+      if (
+        !alwaysShowRun &&
+        (e.metaKey || e.ctrlKey || e.key === "Meta" || e.key === "Control")
+      ) {
+        setPressed(false);
+      }
+    }),
+  );
+
+  // Set pressed to false if the window loses focus
+  useEventListener(
+    window,
+    "blur",
+    maybeNoop(() => setPressed(false)),
+  );
+  useEventListener(
+    window,
+    "mouseleave",
+    maybeNoop(() => setPressed(false)),
+  );
+
+  return pressed;
+}