@marimo-team/islands 0.19.12-dev1 → 0.20.0

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>
+  );
+};

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

@@ -0,0 +1,415 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { IPluginProps } from "../../types";
+import { MatrixPlugin } from "../MatrixPlugin";
+
+type PluginData = ReturnType<MatrixPlugin["validator"]["parse"]>;
+
+function makeProps(
+  overrides: Partial<IPluginProps<number[][], PluginData>> = {},
+): IPluginProps<number[][], PluginData> {
+  return {
+    host: document.createElement("div"),
+    value: [
+      [1, 2],
+      [3, 4],
+    ],
+    setValue: vi.fn(),
+    data: {
+      initialValue: [
+        [1, 2],
+        [3, 4],
+      ],
+      label: null,
+      minValue: null,
+      maxValue: null,
+      step: [
+        [1, 1],
+        [1, 1],
+      ],
+      precision: 1,
+      rowLabels: null,
+      columnLabels: null,
+      symmetric: false,
+      debounce: false,
+      scientific: false,
+      disabled: [
+        [false, false],
+        [false, false],
+      ],
+    },
+    functions: {},
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  // jsdom doesn't implement pointer capture
+  Element.prototype.setPointerCapture = vi.fn();
+  Element.prototype.releasePointerCapture = vi.fn();
+
+  // jsdom's PointerEvent doesn't properly inherit MouseEvent properties
+  // like clientX. Polyfill it so fireEvent.pointerDown/Move/Up work.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any).PointerEvent = class PointerEvent extends MouseEvent {
+    readonly pointerId: number;
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 0;
+    }
+  };
+});
+
+describe("MatrixPlugin", () => {
+  it("renders correct number of cells", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps();
+    const { getAllByTestId } = render(plugin.render(props));
+
+    const cells = getAllByTestId(/^matrix-cell-/);
+    expect(cells).toHaveLength(4);
+  });
+
+  it("displays values with correct precision", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      value: [
+        [1.5, 2.123],
+        [3, 4.9],
+      ],
+      data: {
+        ...makeProps().data,
+        precision: 2,
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+
+    expect(getByTestId("matrix-cell-0-0").textContent).toBe("1.50");
+    expect(getByTestId("matrix-cell-0-1").textContent).toBe("2.12");
+    expect(getByTestId("matrix-cell-1-0").textContent).toBe("3.00");
+    expect(getByTestId("matrix-cell-1-1").textContent).toBe("4.90");
+  });
+
+  it("renders disabled cells with aria-disabled", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      data: {
+        ...makeProps().data,
+        disabled: [
+          [true, false],
+          [false, true],
+        ],
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+
+    expect(getByTestId("matrix-cell-0-0").getAttribute("aria-disabled")).toBe(
+      "true",
+    );
+    expect(getByTestId("matrix-cell-0-1").hasAttribute("aria-disabled")).toBe(
+      false,
+    );
+    expect(getByTestId("matrix-cell-1-0").hasAttribute("aria-disabled")).toBe(
+      false,
+    );
+    expect(getByTestId("matrix-cell-1-1").getAttribute("aria-disabled")).toBe(
+      "true",
+    );
+  });
+
+  it("renders row labels", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      data: {
+        ...makeProps().data,
+        rowLabels: ["Row A", "Row B"],
+      },
+    });
+    const { getByText } = render(plugin.render(props));
+
+    expect(getByText("Row A")).toBeDefined();
+    expect(getByText("Row B")).toBeDefined();
+  });
+
+  it("renders column labels", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      data: {
+        ...makeProps().data,
+        columnLabels: ["Col X", "Col Y"],
+      },
+    });
+    const { getByText } = render(plugin.render(props));
+
+    expect(getByText("Col X")).toBeDefined();
+    expect(getByText("Col Y")).toBeDefined();
+  });
+
+  it("renders a 3x3 matrix", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      value: [
+        [1, 0, 0],
+        [0, 1, 0],
+        [0, 0, 1],
+      ],
+      data: {
+        ...makeProps().data,
+        step: [
+          [1, 1, 1],
+          [1, 1, 1],
+          [1, 1, 1],
+        ],
+        disabled: [
+          [false, false, false],
+          [false, false, false],
+          [false, false, false],
+        ],
+      },
+    });
+    const { getAllByTestId } = render(plugin.render(props));
+
+    const cells = getAllByTestId(/^matrix-cell-/);
+    expect(cells).toHaveLength(9);
+  });
+
+  it("validates with zod schema", () => {
+    const plugin = new MatrixPlugin();
+    const result = plugin.validator.safeParse({
+      initialValue: [
+        [1, 2],
+        [3, 4],
+      ],
+      label: "test",
+      minValue: null,
+      maxValue: null,
+      step: [
+        [1, 1],
+        [1, 1],
+      ],
+      precision: 1,
+      rowLabels: null,
+      columnLabels: null,
+      symmetric: false,
+      scientific: false,
+      disabled: [
+        [false, false],
+        [false, false],
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("displays values in scientific notation", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      value: [
+        [0.00153, 1234567],
+        [0, -0.042],
+      ],
+      data: {
+        ...makeProps().data,
+        scientific: true,
+        precision: 2,
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+
+    expect(getByTestId("matrix-cell-0-0").textContent).toBe("1.53e-3");
+    expect(getByTestId("matrix-cell-0-1").textContent).toBe("1.23e+6");
+    expect(getByTestId("matrix-cell-1-0").textContent).toBe("0.00e+0");
+    expect(getByTestId("matrix-cell-1-1").textContent).toBe("-4.20e-2");
+  });
+
+  it("drag adjusts cell value", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [0, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+    });
+    const { getByTestId } = render(plugin.render(props));
+    const cell = getByTestId("matrix-cell-0-0");
+    const container = getByTestId("marimo-plugin-matrix");
+
+    // Pointer down on cell (0,0), then move 30px right = 3 steps
+    fireEvent.pointerDown(cell, { clientX: 100, pointerId: 1 });
+    fireEvent.pointerMove(container, { clientX: 130 });
+    fireEvent.pointerUp(container);
+
+    expect(setValueMock).toHaveBeenCalledWith([
+      [3, 0],
+      [0, 0],
+    ]);
+  });
+
+  it("symmetric mode mirrors value to transpose cell", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [0, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+      data: {
+        ...makeProps().data,
+        symmetric: true,
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+    const cell = getByTestId("matrix-cell-0-1");
+    const container = getByTestId("marimo-plugin-matrix");
+
+    fireEvent.pointerDown(cell, { clientX: 100, pointerId: 1 });
+    fireEvent.pointerMove(container, { clientX: 120 }); // 2 steps
+    fireEvent.pointerUp(container);
+
+    // Cell (0,1) and (1,0) should both be 2
+    expect(setValueMock).toHaveBeenCalledWith([
+      [0, 2],
+      [2, 0],
+    ]);
+  });
+
+  it("ArrowUp increments cell value", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [5, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+    });
+    const { getByTestId } = render(plugin.render(props));
+
+    fireEvent.keyDown(getByTestId("matrix-cell-0-0"), { key: "ArrowUp" });
+
+    expect(setValueMock).toHaveBeenCalledWith([
+      [6, 0],
+      [0, 0],
+    ]);
+  });
+
+  it("ArrowDown decrements cell value", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [5, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+    });
+    const { getByTestId } = render(plugin.render(props));
+
+    fireEvent.keyDown(getByTestId("matrix-cell-0-0"), { key: "ArrowDown" });
+
+    expect(setValueMock).toHaveBeenCalledWith([
+      [4, 0],
+      [0, 0],
+    ]);
+  });
+
+  it("disabled cells ignore pointer and keyboard input", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [5, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+      data: {
+        ...makeProps().data,
+        disabled: [
+          [true, false],
+          [false, false],
+        ],
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+    const cell = getByTestId("matrix-cell-0-0");
+    const container = getByTestId("marimo-plugin-matrix");
+
+    // Keyboard
+    fireEvent.keyDown(cell, { key: "ArrowUp" });
+    expect(setValueMock).not.toHaveBeenCalled();
+
+    // Drag
+    fireEvent.pointerDown(cell, { clientX: 100, pointerId: 1 });
+    fireEvent.pointerMove(container, { clientX: 130 });
+    fireEvent.pointerUp(container);
+    expect(setValueMock).not.toHaveBeenCalled();
+  });
+
+  it("clamps values to min/max bounds", () => {
+    const plugin = new MatrixPlugin();
+    const setValueMock = vi.fn();
+    const props = makeProps({
+      value: [
+        [5, 0],
+        [0, 0],
+      ],
+      setValue: setValueMock,
+      data: {
+        ...makeProps().data,
+        minValue: [
+          [0, 0],
+          [0, 0],
+        ],
+        maxValue: [
+          [6, 10],
+          [10, 10],
+        ],
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+    const cell = getByTestId("matrix-cell-0-0");
+    const container = getByTestId("marimo-plugin-matrix");
+
+    // Try to drag far right (would be +10 without clamping)
+    fireEvent.pointerDown(cell, { clientX: 100, pointerId: 1 });
+    fireEvent.pointerMove(container, { clientX: 200 });
+    fireEvent.pointerUp(container);
+
+    // Should be clamped to max of 6
+    expect(setValueMock).toHaveBeenCalledWith([
+      [6, 0],
+      [0, 0],
+    ]);
+  });
+
+  it("sets aria attributes on cells", () => {
+    const plugin = new MatrixPlugin();
+    const props = makeProps({
+      data: {
+        ...makeProps().data,
+        rowLabels: ["x", "y"],
+        columnLabels: ["a", "b"],
+        minValue: [
+          [0, 0],
+          [0, 0],
+        ],
+        maxValue: [
+          [10, 10],
+          [10, 10],
+        ],
+      },
+    });
+    const { getByTestId } = render(plugin.render(props));
+    const cell = getByTestId("matrix-cell-0-1");
+
+    expect(cell.getAttribute("aria-label")).toBe("x, b");
+    expect(cell.getAttribute("aria-valuenow")).toBe("2");
+    expect(cell.getAttribute("aria-valuemin")).toBe("0");
+    expect(cell.getAttribute("aria-valuemax")).toBe("10");
+    expect(cell.getAttribute("tabindex")).toBe("0");
+  });
+});

package/src/plugins/impl/anywidget/model.ts

@@ -397,11 +397,10 @@ export async function handleWidgetMessage(
       return;
     }
 
-    case "close": {
+    case "close":
       BINDING_MANAGER.destroy(modelId);
       modelManager.delete(modelId); // aborts the model's signal, clearing listeners
       return;
-    }
 
     case "update": {
       const { state, buffer_paths = [] } = msg;