@marimo-team/frontend 0.19.12-dev1 → 0.20.1

package/src/core/codemirror/extensions.ts

@@ -29,14 +29,9 @@ export function formatKeymapExtension(hotkeys: HotkeyProvider) {
       preventDefault: true,
       run: (ev) => {
         const currentLanguage = getCurrentLanguageAdapter(ev);
-        // Early return if not a supported language
-        if (currentLanguage !== "markdown" && currentLanguage !== "python") {
-          return false;
-        }
-
-        // Toggle between markdown and python
         const destinationLanguage =
-          currentLanguage === "python" ? "markdown" : "python";
+          currentLanguage === "markdown" ? "python" : "markdown";
+
         const response = toggleToLanguage(ev, destinationLanguage, {
           force: true,
         });

package/src/core/documentation/DocHoverTarget.tsx

@@ -0,0 +1,23 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { ReactNode } from "react";
+import { useDebouncedCallback } from "@/hooks/useDebounce";
+import { requestOutputDocumentation } from "./doc-lookup";
+
+export const DocHoverTarget: React.FC<{
+  qualifiedName: string;
+  children: ReactNode;
+}> = ({ qualifiedName, children }) => {
+  const handleMouseEnter = useDebouncedCallback(() => {
+    requestOutputDocumentation(qualifiedName);
+  }, 100);
+
+  return (
+    <span
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={() => handleMouseEnter.cancel()}
+    >
+      {children}
+    </span>
+  );
+};

package/src/core/documentation/doc-lookup.ts

@@ -0,0 +1,50 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { getCells } from "@/core/cells/cells";
+import { AUTOCOMPLETER } from "@/core/codemirror/completion/Autocompleter";
+import { store } from "@/core/state/jotai";
+import { Logger } from "@/utils/Logger";
+import { documentationAtom } from "./state";
+
+/**
+ * Request documentation for a qualified Python name (e.g. "torch.nn.Linear")
+ * by piggybacking on the existing code-completion system.
+ *
+ * We send the qualified name as the "document" to the autocomplete endpoint.
+ * Jedi resolves it and returns the docstring in the completion info.
+ */
+export async function requestOutputDocumentation(
+  qualifiedName: string,
+): Promise<void> {
+  // We need any valid cell_id for the completion request.
+  const cellId = getCells().inOrderIds.at(0);
+  if (!cellId) {
+    return;
+  }
+
+  try {
+    const message = await AUTOCOMPLETER.request({
+      document: qualifiedName,
+      cellId,
+    });
+
+    if (!message || message.options.length === 0) {
+      return;
+    }
+
+    // Find the option matching the last segment of the qualified name
+    const shortName = qualifiedName.split(".").pop() ?? qualifiedName;
+
+    const defaultOption = message.options[0];
+    const match =
+      message.options.find((o) => o.name === shortName) ?? defaultOption;
+
+    if (match?.completion_info) {
+      store.set(documentationAtom, {
+        documentation: match.completion_info,
+      });
+    }
+  } catch (error) {
+    Logger.debug(`Doc lookup failed for "${qualifiedName}"`, error);
+  }
+}

package/src/core/islands/main.ts

@@ -126,6 +126,7 @@ export async function initialize() {
       case "datasets":
       case "data-source-connections":
       case "validate-sql-result":
+      case "storage-namespaces":
       case "secret-keys-result":
       case "startup-logs":
         // Unsupported

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -284,6 +284,9 @@ export function useMarimoKernelConnection(opts: {
           })),
         });
         return;
+      case "storage-namespaces":
+        // TODO: Handle storage namespaces
+        return;
 
       case "reconnected":
         return;

package/src/css/app/Cell.css

@@ -314,6 +314,11 @@
 
   &.published {
     border: none;
+
+    &:hover {
+      border: none;
+      box-shadow: none;
+    }
   }
 }
 

package/src/mount.tsx

@@ -59,9 +59,9 @@ import { reportVitals } from "./utils/vitals";
 let hasMounted = false;
 
 /**
- * Main entry point for the mairmo app.
+ * Main entry point for the marimo app.
  *
- * Sets up the mairmo app with a theme provider.
+ * Sets up the marimo app with a theme provider.
  */
 export function mount(options: unknown, el: Element): Error | undefined {
   if (hasMounted) {

package/src/plugins/core/RenderHTML.tsx

@@ -14,6 +14,7 @@ import React, {
 } from "react";
 import { CopyClipboardIcon } from "@/components/icons/copy-icon";
 import { QueryParamPreservingLink } from "@/components/ui/query-param-preserving-link";
+import { DocHoverTarget } from "@/core/documentation/DocHoverTarget";
 import { sanitizeHtml, useSanitizeHtml } from "./sanitize";
 
 type ReplacementFn = NonNullable<HTMLReactParserOptions["replace"]>;
@@ -146,6 +147,19 @@ const addCopyButtonToCodehilite: TransformFn = (
   }
 };
 
+// Wrap elements with data-marimo-doc attribute in a DocHoverTarget
+const wrapDocHoverTargets: TransformFn = (
+  reactNode: ReactNode,
+  domNode: DOMNode,
+): JSX.Element | undefined => {
+  if (domNode instanceof Element && domNode.attribs?.["data-marimo-doc"]) {
+    const qualifiedName = domNode.attribs["data-marimo-doc"];
+    return (
+      <DocHoverTarget qualifiedName={qualifiedName}>{reactNode}</DocHoverTarget>
+    );
+  }
+};
+
 const CopyableCode = ({ children }: { children: ReactNode }) => {
   const ref = useRef<HTMLDivElement>(null);
   return (
@@ -224,6 +238,7 @@ function parseHtml({
   const transformFunctions: TransformFn[] = [
     addCopyButtonToCodehilite,
     preserveQueryParamsInAnchorLinks,
+    wrapDocHoverTargets,
     removeWrappingBodyTags,
     removeWrappingHtmlTags,
   ];

package/src/plugins/core/__test__/registerReactComponent.test.ts

@@ -0,0 +1,204 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import ReactDOM from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { z } from "zod";
+import {
+  isCustomMarimoElement,
+  registerReactComponent,
+} from "../registerReactComponent";
+
+// Each custom element name can only be registered once per jsdom window,
+// so we use a counter to generate unique tag names across tests.
+let tagCounter = 0;
+function uniqueTag(base: string) {
+  return `marimo-test-${base}-${++tagCounter}`;
+}
+
+function makePlugin(tagName: string) {
+  return {
+    tagName,
+    validator: z.any(),
+    render: () => null as never,
+  };
+}
+
+describe("isCustomMarimoElement", () => {
+  test("returns false for null", () => {
+    expect(isCustomMarimoElement(null)).toBe(false);
+  });
+
+  test("returns false for a regular HTMLElement", () => {
+    const div = document.createElement("div");
+    expect(isCustomMarimoElement(div)).toBe(false);
+  });
+
+  test("returns false for a non-HTMLElement", () => {
+    const svg = document.createElementNS(
+      "http://www.w3.org/2000/svg",
+      "circle",
+    );
+    expect(isCustomMarimoElement(svg as Element)).toBe(false);
+  });
+
+  test("returns true for a registered marimo custom element", () => {
+    const tag = uniqueTag("is-custom");
+    registerReactComponent(makePlugin(tag));
+    const el = document.createElement(tag);
+    expect(isCustomMarimoElement(el)).toBe(true);
+  });
+
+  test("returns false for an element with wrong __type__ value", () => {
+    const div = document.createElement("div") as unknown as HTMLElement & {
+      __type__: string;
+    };
+    div.__type__ = "something_else";
+    expect(isCustomMarimoElement(div)).toBe(false);
+  });
+});
+
+describe("connectedCallback - light DOM nesting detection", () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let createRootSpy: any;
+  const mockRoot = {
+    render: vi.fn(),
+    unmount: vi.fn(),
+  };
+
+  beforeEach(() => {
+    createRootSpy = vi
+      .spyOn(ReactDOM, "createRoot")
+      .mockReturnValue(mockRoot as unknown as ReactDOM.Root);
+  });
+
+  afterEach(() => {
+    createRootSpy.mockRestore();
+    mockRoot.render.mockClear();
+    mockRoot.unmount.mockClear();
+  });
+
+  test("skips mounting when element is a light DOM child of another marimo element", () => {
+    const parentTag = uniqueTag("parent");
+    const childTag = uniqueTag("child");
+    registerReactComponent(makePlugin(parentTag));
+    registerReactComponent(makePlugin(childTag));
+
+    const parent = document.createElement(parentTag);
+    const child = document.createElement(childTag);
+    parent.append(child);
+
+    createRootSpy.mockClear();
+    document.body.append(parent);
+
+    // Only the parent should mount; the child is skipped because it
+    // detects a marimo ancestor in the light DOM.
+    expect(createRootSpy).toHaveBeenCalledTimes(1);
+    expect(createRootSpy).toHaveBeenCalledWith(parent.shadowRoot);
+
+    parent.remove();
+  });
+
+  test("mounts when element is not nested inside a marimo element", () => {
+    const tag = uniqueTag("standalone");
+    registerReactComponent(makePlugin(tag));
+
+    const el = document.createElement(tag);
+    createRootSpy.mockClear();
+
+    document.body.append(el);
+
+    expect(createRootSpy).toHaveBeenCalledTimes(1);
+    expect(createRootSpy).toHaveBeenCalledWith(el.shadowRoot);
+
+    el.remove();
+  });
+
+  test("mounts when nested inside a regular (non-marimo) element", () => {
+    const tag = uniqueTag("in-div");
+    registerReactComponent(makePlugin(tag));
+
+    const wrapper = document.createElement("div");
+    const el = document.createElement(tag);
+    wrapper.append(el);
+
+    createRootSpy.mockClear();
+    document.body.append(wrapper);
+
+    expect(createRootSpy).toHaveBeenCalledTimes(1);
+    expect(createRootSpy).toHaveBeenCalledWith(el.shadowRoot);
+
+    wrapper.remove();
+  });
+
+  test("skips mounting for deeply nested marimo element through non-marimo wrappers", () => {
+    const outerTag = uniqueTag("outer");
+    const innerTag = uniqueTag("inner");
+    registerReactComponent(makePlugin(outerTag));
+    registerReactComponent(makePlugin(innerTag));
+
+    const outer = document.createElement(outerTag);
+    const div = document.createElement("div");
+    const inner = document.createElement(innerTag);
+
+    // Structure: outer > div > inner
+    outer.append(div);
+    div.append(inner);
+
+    createRootSpy.mockClear();
+    document.body.append(outer);
+
+    // Only outer mounts; inner is skipped because a marimo ancestor
+    // is found when traversing through the intermediate div.
+    expect(createRootSpy).toHaveBeenCalledTimes(1);
+    expect(createRootSpy).toHaveBeenCalledWith(outer.shadowRoot);
+
+    outer.remove();
+  });
+
+  test("mounts both sibling marimo elements (neither is a child of the other)", () => {
+    const tagA = uniqueTag("sibling-a");
+    const tagB = uniqueTag("sibling-b");
+    registerReactComponent(makePlugin(tagA));
+    registerReactComponent(makePlugin(tagB));
+
+    const wrapper = document.createElement("div");
+    const a = document.createElement(tagA);
+    const b = document.createElement(tagB);
+    wrapper.append(a);
+    wrapper.append(b);
+
+    createRootSpy.mockClear();
+    document.body.append(wrapper);
+
+    // Both siblings should mount since neither is a child of the other.
+    expect(createRootSpy).toHaveBeenCalledTimes(2);
+
+    wrapper.remove();
+  });
+
+  test("mounts when element is inside the shadow DOM of another marimo element", () => {
+    const outerTag = uniqueTag("shadow-outer");
+    const innerTag = uniqueTag("shadow-inner");
+    registerReactComponent(makePlugin(outerTag));
+    registerReactComponent(makePlugin(innerTag));
+
+    const outer = document.createElement(outerTag);
+    const inner = document.createElement(innerTag);
+
+    // Place the inner element inside the outer element's shadow root,
+    // simulating how getChildren() -> renderHTML() re-creates children
+    // in the shadow DOM. parentElement traversal stays within the
+    // shadow root boundary, so inner should NOT detect outer as an
+    // ancestor and should mount normally.
+    outer.shadowRoot?.append(inner);
+
+    createRootSpy.mockClear();
+    document.body.append(outer);
+
+    // Both elements should mount: outer in the document, inner in the
+    // shadow root (parentElement traversal doesn't cross shadow boundary).
+    expect(createRootSpy).toHaveBeenCalledTimes(2);
+
+    outer.remove();
+  });
+});

package/src/plugins/core/registerReactComponent.tsx

@@ -316,6 +316,15 @@ export function registerReactComponent<T>(plugin: IPlugin<T, unknown>): void {
     }
 
     connectedCallback() {
+      // Skip mounting if this element is in the light DOM of another
+      // marimo custom element. The parent element's shadow DOM will
+      // re-create this element via getChildren() -> renderHTML(), so
+      // this light DOM copy should remain inert to avoid duplicate
+      // side-effects (e.g., mo.lazy firing load() twice).
+      if (this.isLightDOMChildOfMarimoElement()) {
+        return;
+      }
+
       if (!this.mounted) {
         // Create a React root on the shadow root
         invariant(this.shadowRoot, "Shadow root should exist");
@@ -348,6 +357,30 @@ export function registerReactComponent<T>(plugin: IPlugin<T, unknown>): void {
       }
     }
 
+    /**
+     * Check if this element is in the light DOM of another marimo
+     * custom element. When a marimo element (e.g. marimo-tabs) has
+     * children that are also marimo elements (e.g. marimo-lazy), the
+     * browser upgrades both the light DOM originals AND the shadow DOM
+     * copies created by renderHTML(). The light DOM copies should not
+     * mount since they are not rendered (no <slot>) and would cause
+     * duplicate side-effects.
+     *
+     * parentElement traversal stays within the same DOM tree boundary
+     * (shadow root or document), so shadow DOM copies never find a
+     * marimo ancestor and correctly return false.
+     */
+    private isLightDOMChildOfMarimoElement(): boolean {
+      let parent = this.parentElement;
+      while (parent) {
+        if (isCustomMarimoElement(parent)) {
+          return true;
+        }
+        parent = parent.parentElement;
+      }
+      return false;
+    }
+
     /**
      * Reset the plugin initial value and data.
      * And then re-render the plugin.

package/src/plugins/impl/MatrixPlugin.tsx

@@ -0,0 +1,275 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { type JSX, useCallback, useRef, useState } from "react";
+import { z } from "zod";
+import { cn } from "@/utils/cn";
+import type { IPlugin, IPluginProps, Setter } from "../types";
+import { Labeled } from "./common/labeled";
+import matrixCss from "./matrix.css?inline";
+
+type T = number[][];
+
+interface Data {
+  label: string | null;
+  minValue?: number[][] | null;
+  maxValue?: number[][] | null;
+  step: number[][];
+  precision: number;
+  rowLabels?: string[] | null;
+  columnLabels?: string[] | null;
+  symmetric: boolean;
+  debounce: boolean;
+  scientific: boolean;
+  disabled: boolean[][];
+}
+
+export class MatrixPlugin implements IPlugin<T, Data> {
+  tagName = "marimo-matrix";
+
+  cssStyles = [matrixCss];
+
+  validator = z.object({
+    initialValue: z.array(z.array(z.number())),
+    label: z.string().nullable(),
+    minValue: z.array(z.array(z.number())).nullish(),
+    maxValue: z.array(z.array(z.number())).nullish(),
+    step: z.array(z.array(z.number())),
+    precision: z.number(),
+    rowLabels: z.array(z.string()).nullish(),
+    columnLabels: z.array(z.string()).nullish(),
+    symmetric: z.boolean(),
+    debounce: z.boolean().default(false),
+    scientific: z.boolean(),
+    disabled: z.array(z.array(z.boolean())),
+  });
+
+  render(props: IPluginProps<T, Data>): JSX.Element {
+    return (
+      <MatrixComponent
+        {...props.data}
+        value={props.value}
+        setValue={props.setValue}
+      />
+    );
+  }
+}
+
+const PIXELS_PER_STEP = 10;
+
+interface MatrixComponentProps extends Data {
+  value: T;
+  setValue: Setter<T>;
+}
+
+const MatrixComponent = ({
+  value,
+  setValue,
+  label,
+  minValue,
+  maxValue,
+  step,
+  precision,
+  rowLabels,
+  columnLabels,
+  symmetric,
+  debounce,
+  scientific,
+  disabled,
+}: MatrixComponentProps): JSX.Element => {
+  const dragState = useRef<{
+    row: number;
+    col: number;
+    startX: number;
+    startValue: number;
+  } | null>(null);
+  const [activeCell, setActiveCell] = useState<{
+    row: number;
+    col: number;
+  } | null>(null);
+
+  // Draft holds local edits during an active drag/interaction.
+  // Outside of a drag we always read from the prop `value` directly,
+  // which avoids stale-state bugs when the matrix shape changes.
+  const [draft, setDraft] = useState(value);
+  const displayValue = activeCell != null ? draft : value;
+
+  const formatValue = (val: number) =>
+    scientific ? val.toExponential(precision) : val.toFixed(precision);
+
+  const clampValue = useCallback(
+    (val: number, row: number, col: number): number => {
+      let clamped = val;
+      if (minValue != null) {
+        clamped = Math.max(clamped, minValue[row][col]);
+      }
+      if (maxValue != null) {
+        clamped = Math.min(clamped, maxValue[row][col]);
+      }
+      return clamped;
+    },
+    [minValue, maxValue],
+  );
+
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent, row: number, col: number) => {
+      if (disabled[row][col] || !(e.target instanceof Element)) {
+        return;
+      }
+      e.preventDefault();
+      e.target.setPointerCapture(e.pointerId);
+      dragState.current = {
+        row,
+        col,
+        startX: e.clientX,
+        startValue: displayValue[row][col],
+      };
+      setActiveCell({ row, col });
+    },
+    [disabled, displayValue],
+  );
+
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      const state = dragState.current;
+      if (!state) {
+        return;
+      }
+      const { row, col, startX, startValue } = state;
+      const dx = e.clientX - startX;
+      const cellStep = step[row][col];
+      const steps = Math.round(dx / PIXELS_PER_STEP);
+      const rawValue = startValue + steps * cellStep;
+      const newValue = clampValue(rawValue, row, col);
+
+      if (newValue !== displayValue[row][col]) {
+        const copy = displayValue.map((r) => [...r]);
+        copy[row][col] = newValue;
+        if (symmetric && row !== col) {
+          copy[col][row] = newValue;
+        }
+        setDraft(copy);
+        if (!debounce) {
+          setValue(copy);
+        }
+      }
+    },
+    [step, clampValue, displayValue, symmetric, debounce, setValue],
+  );
+
+  const handlePointerUp = useCallback(() => {
+    if (debounce && dragState.current) {
+      setValue(displayValue);
+    }
+    dragState.current = null;
+    setActiveCell(null);
+  }, [debounce, displayValue, setValue]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent, row: number, col: number) => {
+      if (e.key === "ArrowUp" || e.key === "ArrowDown") {
+        if (disabled[row][col]) {
+          return;
+        }
+        e.preventDefault();
+        const cellStep = step[row][col];
+        const delta = e.key === "ArrowUp" ? cellStep : -cellStep;
+        const newValue = clampValue(displayValue[row][col] + delta, row, col);
+
+        if (newValue !== displayValue[row][col]) {
+          const copy = displayValue.map((r) => [...r]);
+          copy[row][col] = newValue;
+          if (symmetric && row !== col) {
+            copy[col][row] = newValue;
+          }
+          setDraft(copy);
+          setValue(copy);
+        }
+      }
+    },
+    [disabled, step, displayValue, clampValue, symmetric, setValue],
+  );
+
+  const hasRowLabels = rowLabels != null && rowLabels.length > 0;
+  const hasColumnLabels = columnLabels != null && columnLabels.length > 0;
+
+  const numRows = displayValue.length;
+  const numCols = displayValue[0]?.length ?? 0;
+
+  return (
+    <Labeled label={label} align="top" className="items-center">
+      <div
+        className="relative inline-block"
+        data-testid="marimo-plugin-matrix"
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerUp}
+      >
+        <table
+          className="font-mono text-sm tabular-nums select-none border-separate border-spacing-0"
+          role="group"
+          aria-label={label || "Matrix"}
+        >
+          {hasColumnLabels && (
+            <thead>
+              <tr>
+                {hasRowLabels && <th />}
+                {columnLabels.map((lbl, j) => (
+                  <th
+                    key={j}
+                    className="text-center text-sm font-medium text-foreground px-2 pb-1"
+                  >
+                    {lbl}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+          )}
+          <tbody>
+            {displayValue.map((row, i) => (
+              <tr key={i}>
+                {hasRowLabels && (
+                  <th className="text-right text-sm font-medium text-foreground pr-3 h-8">
+                    {rowLabels[i]}
+                  </th>
+                )}
+                {row.map((cellValue, j) => {
+                  const isDisabled = disabled[i][j];
+                  const isActive =
+                    activeCell?.row === i && activeCell?.col === j;
+                  const rowLabel = rowLabels?.[i] ?? `Row ${i + 1}`;
+                  const colLabel = columnLabels?.[j] ?? `Column ${j + 1}`;
+                  return (
+                    <td
+                      key={j}
+                      className={cn(
+                        "relative text-center min-w-14 h-8 px-2 transition-colors touch-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+                        isDisabled
+                          ? "cursor-default text-muted-foreground"
+                          : "cursor-ew-resize text-[var(--link)] hover:bg-accent",
+                        isActive && "bg-accent",
+                        j === 0 && "bracket-l",
+                        j === numCols - 1 && "bracket-r",
+                        i === 0 && "bracket-t",
+                        i === numRows - 1 && "bracket-b",
+                      )}
+                      tabIndex={isDisabled ? -1 : 0}
+                      aria-label={`${rowLabel}, ${colLabel}`}
+                      aria-valuenow={cellValue}
+                      aria-valuemin={minValue?.[i]?.[j]}
+                      aria-valuemax={maxValue?.[i]?.[j]}
+                      aria-disabled={isDisabled || undefined}
+                      onPointerDown={(e) => handlePointerDown(e, i, j)}
+                      onKeyDown={(e) => handleKeyDown(e, i, j)}
+                      data-testid={`matrix-cell-${i}-${j}`}
+                    >
+                      {formatValue(cellValue)}
+                    </td>
+                  );
+                })}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </Labeled>
+  );
+};