@marimo-team/islands 0.23.10-dev9 → 0.23.10

package/src/components/ui/select-core/use-select-list.ts

@@ -0,0 +1,347 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useMemo, useState } from "react";
+import { assertNever } from "@/utils/assertNever";
+import type { BulkAction, Option } from "./types";
+import {
+  deselectMatching,
+  getBulkActions,
+  getVisibleOptions,
+  multiselectFilterFn,
+  selectMatching,
+} from "./utils";
+
+/** cmdk-style relevance score for `(label, query)`; any positive score matches. */
+type FilterFn = (label: string, query: string) => number;
+
+interface UseSelectListParams<V> {
+  options: Array<Option<V>>;
+  /** Current selection: an array when `multiple`, otherwise a single value or null. */
+  value: V[] | V | null;
+  onChange: (next: V[] | V | null) => void;
+  /** Multi-select when true; single-select (replace-on-pick) when false. */
+  multiple: boolean;
+  /** Cap on multi-select size. At the cap, picking another drops the oldest. */
+  maxSelections?: number;
+  /** Single-select only: re-picking the current value clears it to null. */
+  allowSelectNone?: boolean;
+  /** Match predicate over `(label, query)`; defaults to the strict word match. */
+  filterFn?: FilterFn;
+  /** Float the (frozen) selection to the top of the idle menu. */
+  pinSelected?: boolean;
+}
+
+interface UseSelectListResult<V> {
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** Filtered, and (when `pinSelected` and idle) selected-first ordered. */
+  visibleOptions: Array<Option<V>>;
+  /** Count of pinned options at the head of `visibleOptions` (0 unless pinned + idle). */
+  pinnedCount: number;
+  isChecked: (value: V) => boolean;
+  toggle: (value: V) => void;
+  /**
+   * Renderable bulk rows for the current search/cap state, in display order.
+   * Empty for single-select. Each entry carries its data (`enabled` or `items`)
+   * and a `run` closure that applies it.
+   */
+  bulkActions: Array<BulkAction<V>>;
+  /** Map a value back to its option label; falls back to `String(value)`. */
+  labelOf: (value: V) => string;
+}
+
+function asArray<V>(value: V[] | V | null): V[] {
+  if (value == null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+interface SearchParams<V> {
+  options: Array<Option<V>>;
+  filterFn: FilterFn;
+}
+
+/** Search query and the options that currently match it. */
+function useSearch<V>({ options, filterFn }: SearchParams<V>): {
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+  filteredOptions: Array<Option<V>>;
+} {
+  const [searchQuery, setSearchQuery] = useState("");
+  const filteredOptions = useMemo(() => {
+    if (!searchQuery) {
+      return options;
+    }
+    return options.filter((o) => filterFn(o.label, searchQuery) > 0);
+  }, [options, searchQuery, filterFn]);
+  return { searchQuery, setSearchQuery, filteredOptions };
+}
+
+interface PinningParams<V> {
+  value: V[] | V | null;
+  pinSelected: boolean;
+  options: Array<Option<V>>;
+  searchQuery: string;
+  filteredOptions: Array<Option<V>>;
+}
+
+/**
+ * Open state plus the frozen selection snapshot that orders the idle menu. The
+ * snapshot is retaken (`repin`) when the menu opens or the search clears, so a row
+ * toggled mid-session keeps its place instead of jumping to the top under the cursor.
+ */
+function usePinning<V>({
+  value,
+  pinSelected,
+  options,
+  searchQuery,
+  filteredOptions,
+}: PinningParams<V>): {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  repin: () => void;
+  visibleOptions: Array<Option<V>>;
+  pinnedCount: number;
+} {
+  const [open, setOpenState] = useState(false);
+  const [pinnedSelection, setPinnedSelection] = useState<Set<V>>(
+    () => new Set(asArray(value)),
+  );
+
+  const repin = (): void => setPinnedSelection(new Set(asArray(value)));
+
+  const setOpen = (nextOpen: boolean): void => {
+    setOpenState(nextOpen);
+    if (nextOpen) {
+      repin();
+    }
+  };
+
+  const { visibleOptions, pinnedCount } = useMemo(() => {
+    if (searchQuery || !pinSelected) {
+      return { visibleOptions: filteredOptions, pinnedCount: 0 };
+    }
+    return getVisibleOptions(options, pinnedSelection);
+  }, [searchQuery, pinSelected, filteredOptions, options, pinnedSelection]);
+
+  return { open, setOpen, repin, visibleOptions, pinnedCount };
+}
+
+interface ToggleParams<V> {
+  value: V[] | V | null;
+  onChange: (next: V[] | V | null) => void;
+  multiple: boolean;
+  maxSelections: number | undefined;
+  allowSelectNone: boolean | undefined;
+  selected: ReadonlySet<V>;
+}
+
+/** Membership test and the cap/cardinality-aware single-item toggle. */
+function useToggle<V>({
+  value,
+  onChange,
+  multiple,
+  maxSelections,
+  allowSelectNone,
+  selected,
+}: ToggleParams<V>): {
+  isChecked: (value: V) => boolean;
+  toggle: (value: V) => void;
+} {
+  const isChecked = (candidate: V): boolean => selected.has(candidate);
+
+  const toggle = (candidate: V): void => {
+    if (!multiple) {
+      if (allowSelectNone && value === candidate) {
+        onChange(null);
+        return;
+      }
+      onChange(candidate);
+      return;
+    }
+
+    const current = asArray(value);
+    if (selected.has(candidate)) {
+      onChange(current.filter((v) => v !== candidate));
+      return;
+    }
+
+    let next = [...current, candidate];
+    if (maxSelections != null && next.length > maxSelections) {
+      next = next.slice(-maxSelections);
+    }
+    onChange(next);
+  };
+
+  return { isChecked, toggle };
+}
+
+interface BulkParams<V> {
+  value: V[] | V | null;
+  onChange: (next: V[] | V | null) => void;
+  multiple: boolean;
+  options: Array<Option<V>>;
+  filteredOptions: Array<Option<V>>;
+  searchQuery: string;
+  maxSelections: number | undefined;
+}
+
+/** Bulk-row specs paired with run closures; inert for single-select. */
+function useBulk<V>({
+  value,
+  onChange,
+  multiple,
+  options,
+  filteredOptions,
+  searchQuery,
+  maxSelections,
+}: BulkParams<V>): { bulkActions: Array<BulkAction<V>> } {
+  const bulkActions = useMemo<Array<BulkAction<V>>>(() => {
+    if (!multiple) {
+      return [];
+    }
+    const specs = getBulkActions({
+      options,
+      filteredOptions,
+      value: asArray(value),
+      searchQuery,
+      maxSelections,
+    });
+    return specs.map((spec): BulkAction<V> => {
+      switch (spec.kind) {
+        case "select-all":
+          return {
+            ...spec,
+            run: () =>
+              onChange(
+                selectMatching(
+                  asArray(value),
+                  options.filter((o) => !o.disabled).map((o) => o.value),
+                ),
+              ),
+          };
+        case "deselect-all":
+          return { ...spec, run: () => onChange([]) };
+        case "select-matching":
+          return {
+            ...spec,
+            run: () =>
+              onChange(
+                selectMatching(
+                  asArray(value),
+                  spec.items.map((o) => o.value),
+                ),
+              ),
+          };
+        case "deselect-matching":
+          return {
+            ...spec,
+            run: () =>
+              onChange(
+                deselectMatching(
+                  asArray(value),
+                  spec.items.map((o) => o.value),
+                ),
+              ),
+          };
+        default:
+          return assertNever(spec);
+      }
+    });
+  }, [
+    multiple,
+    options,
+    filteredOptions,
+    value,
+    searchQuery,
+    maxSelections,
+    onChange,
+  ]);
+
+  return { bulkActions };
+}
+
+/**
+ * Headless state for a searchable select list, shared across the multiselect,
+ * dropdown, and top-K filter facades. Composes four focused concerns — search,
+ * pinning/freeze, membership/toggle, and bulk actions — behind one entry point.
+ * Pinning and bulk rows are opt-in so the single-select and top-K facades share
+ * only what they need.
+ */
+export function useSelectList<V>({
+  options,
+  value,
+  onChange,
+  multiple,
+  maxSelections,
+  allowSelectNone,
+  filterFn = multiselectFilterFn,
+  pinSelected = false,
+}: UseSelectListParams<V>): UseSelectListResult<V> {
+  const selected = useMemo(() => new Set(asArray(value)), [value]);
+
+  const labelByValue = useMemo(() => {
+    const map = new Map<V, string>();
+    for (const option of options) {
+      map.set(option.value, option.label);
+    }
+    return map;
+  }, [options]);
+  const labelOf = (candidate: V): string =>
+    labelByValue.get(candidate) ?? String(candidate);
+
+  const {
+    searchQuery,
+    setSearchQuery: setSearchQueryState,
+    filteredOptions,
+  } = useSearch({ options, filterFn });
+
+  const { open, setOpen, repin, visibleOptions, pinnedCount } = usePinning({
+    value,
+    pinSelected,
+    options,
+    searchQuery,
+    filteredOptions,
+  });
+
+  const { isChecked, toggle } = useToggle({
+    value,
+    onChange,
+    multiple,
+    maxSelections,
+    allowSelectNone,
+    selected,
+  });
+
+  const { bulkActions } = useBulk({
+    value,
+    onChange,
+    multiple,
+    options,
+    filteredOptions,
+    searchQuery,
+    maxSelections,
+  });
+
+  const setSearchQuery = (query: string): void => {
+    setSearchQueryState(query);
+    if (query === "") {
+      repin();
+    }
+  };
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    open,
+    setOpen,
+    visibleOptions,
+    pinnedCount,
+    isChecked,
+    toggle,
+    bulkActions,
+    labelOf,
+  };
+}

package/src/components/ui/select-core/utils.ts

@@ -0,0 +1,121 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { BulkActionSpec, Option } from "./types";
+
+/**
+ * Override cmdk's relevance-sorting filter with a stricter membership test: an
+ * option matches only when every whitespace-separated query word appears in it
+ * (case-insensitive), in any order. More lenient than exact match, stricter than
+ * fuzzy.
+ *
+ * Examples:
+ * - "foo bar" matches "foo bar"
+ * - "bar foo" matches "foo bar"
+ * - "foob" does not match "foo bar"
+ */
+export function multiselectFilterFn(option: string, value: string): number {
+  const words = value.split(/\s+/);
+  const match = words.every((word) =>
+    option.toLowerCase().includes(word.toLowerCase()),
+  );
+  return match ? 1 : 0;
+}
+
+/** Union: append the not-yet-selected members of `toAdd`, preserving order. */
+export function selectMatching<V>(selected: V[], toAdd: V[]): V[] {
+  const set = new Set(selected);
+  return [...set, ...toAdd.filter((v) => !set.has(v))];
+}
+
+/** Difference: drop every member of `toRemove` from `selected`. */
+export function deselectMatching<V>(selected: V[], toRemove: V[]): V[] {
+  const set = new Set(toRemove);
+  return selected.filter((v) => !set.has(v));
+}
+
+/**
+ * Order options for the idle (no active search) menu: pinned selections first in
+ * pin insertion order (so a freshly added selection appears after earlier ones),
+ * then everything else in option order. `pinnedSelection` is a frozen snapshot
+ * taken when the menu opens, so toggling an item does not reorder the list under
+ * the cursor. Returns the count of pinned options alongside the list so callers
+ * don't have to re-scan to find where the pinned block ends.
+ */
+export function getVisibleOptions<V>(
+  options: Array<Option<V>>,
+  pinnedSelection: ReadonlySet<V>,
+): { visibleOptions: Array<Option<V>>; pinnedCount: number } {
+  const byValue = new Map(options.map((o) => [o.value, o] as const));
+  const pinned: Array<Option<V>> = [];
+  for (const value of pinnedSelection) {
+    const option = byValue.get(value);
+    if (option) {
+      pinned.push(option);
+    }
+  }
+  const rest = options.filter((o) => !pinnedSelection.has(o.value));
+  return { visibleOptions: [...pinned, ...rest], pinnedCount: pinned.length };
+}
+
+/**
+ * Decide which bulk rows the menu shows for the current search/cap state.
+ *
+ * When searching, the select-side spec carries the unselected matches and the
+ * deselect-side spec carries the selected matches (each omitted when empty).
+ * When idle, the spec is just `select-all` / `deselect-all` with an `enabled`
+ * flag for the disabled-but-visible state. `maxSelections` hides the select-
+ * side everywhere (a bulk select could exceed the cap); `maxSelections === 1`
+ * suppresses bulk rows entirely. Returns `[]` when bulk rows shouldn't show.
+ *
+ * Specs come in select-then-deselect order so the facade can render them as-is.
+ */
+export function getBulkActions<V>(params: {
+  options: Array<Option<V>>;
+  filteredOptions: Array<Option<V>>;
+  value: V[];
+  searchQuery: string;
+  maxSelections: number | undefined;
+}): Array<BulkActionSpec<V>> {
+  const { options, filteredOptions, value, searchQuery, maxSelections } =
+    params;
+
+  if (options.length <= 2 || maxSelections === 1) {
+    return [];
+  }
+
+  const capped = maxSelections != null;
+  const specs: Array<BulkActionSpec<V>> = [];
+
+  if (searchQuery !== "") {
+    if (filteredOptions.length === 0) {
+      return [];
+    }
+    const selected = new Set(value);
+    const selectedMatches: Array<Option<V>> = [];
+    const unselectedMatches: Array<Option<V>> = [];
+    for (const option of filteredOptions) {
+      if (selected.has(option.value)) {
+        selectedMatches.push(option);
+      } else if (!option.disabled) {
+        // Disabled rows can't be picked individually, so bulk select skips them too.
+        unselectedMatches.push(option);
+      }
+    }
+    if (!capped && unselectedMatches.length > 0) {
+      specs.push({ kind: "select-matching", items: unselectedMatches });
+    }
+    if (selectedMatches.length > 0) {
+      specs.push({ kind: "deselect-matching", items: selectedMatches });
+    }
+    return specs;
+  }
+
+  if (!capped) {
+    const selected = new Set(value);
+    specs.push({
+      kind: "select-all",
+      enabled: options.some((o) => !o.disabled && !selected.has(o.value)),
+    });
+  }
+  specs.push({ kind: "deselect-all", enabled: value.length > 0 });
+  return specs;
+}

package/src/components/ui/toast.tsx

@@ -17,6 +17,7 @@ const ToastViewport = React.forwardRef<
     ref={ref}
     className={cn(
       "fixed top-0 z-100 flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:w-fit md:max-w-[420px]",
+      "print:hidden",
       className,
     )}
     {...props}

package/src/core/cells/__tests__/document-changes.test.ts

@@ -430,7 +430,7 @@ describe("toDocumentChanges", () => {
       const [a] = state.cellIds.inOrderIds;
 
       // Position cursor at end of "line1" (position 5)
-      const view = state.cellHandles[a].current!.editorView;
+      const view = state.cellHandles[a].current!.editorView!;
       view.dispatch({ selection: { anchor: 5 } });
 
       const { changes } = resolve(state, {
@@ -466,7 +466,7 @@ describe("toDocumentChanges", () => {
       const [a] = state.cellIds.inOrderIds;
 
       // Split the cell first
-      const view = state.cellHandles[a].current!.editorView;
+      const view = state.cellHandles[a].current!.editorView!;
       view.dispatch({ selection: { anchor: 5 } });
       const snapshot = view.state.doc.toString();
       state = dispatch(state, {

package/src/core/cells/__tests__/focus.test.ts

@@ -1,11 +1,17 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import type { EditorView } from "@codemirror/view";
+import { createStore } from "jotai";
 import { beforeEach, describe, expect, it } from "vitest";
+import { MockNotebook } from "@/__mocks__/notebook";
 import { cellId } from "@/__tests__/branded";
+import type { CellHandle } from "@/components/editor/notebook-cell";
+import { notebookAtom } from "../cells";
 import type { CellFocusState } from "../focus";
-import { exportedForTesting } from "../focus";
+import { exportedForTesting, lastFocusedCellAtom } from "../focus";
 
-const { initialState, reducer, createActions } = exportedForTesting;
+const { initialState, reducer, createActions, cellFocusAtom } =
+  exportedForTesting;
 
 const CellIds = {
   a: cellId("a"),
@@ -270,3 +276,40 @@ describe("cell focus reducer", () => {
     });
   });
 });
+
+describe("lastFocusedCellAtom", () => {
+  it("returns null getEditorView when CodeMirror is not mounted", () => {
+    const store = createStore();
+    const markdownCellId = cellId("markdown");
+
+    const unmountedEditorHandle: CellHandle = {
+      get editorView(): EditorView {
+        throw new ReferenceError("Attempting to dereference null object.");
+      },
+      editorViewOrNull: null,
+    };
+
+    const notebook = MockNotebook.notebookState({
+      cellData: {
+        [markdownCellId]: {
+          config: { hide_code: true },
+        },
+      },
+    });
+    notebook.cellHandles[markdownCellId] = {
+      current: unmountedEditorHandle,
+    };
+
+    store.set(notebookAtom, notebook);
+    store.set(cellFocusAtom, {
+      focusedCellId: markdownCellId,
+      lastFocusedCellId: markdownCellId,
+    });
+
+    const lastFocusedCell = store.get(lastFocusedCellAtom);
+
+    expect(lastFocusedCell).not.toBeNull();
+    expect(lastFocusedCell?.cellId).toBe(markdownCellId);
+    expect(lastFocusedCell?.getEditorView()).toBeNull();
+  });
+});

package/src/core/cells/focus.ts

@@ -106,7 +106,7 @@ function cellFocusDetails(cellId: CellId, notebookState: NotebookState) {
   if (!data || !handle) {
     return null;
   }
-  const getEditorView = () => handle.editorView;
+  const getEditorView = () => handle.editorViewOrNull;
 
   return {
     cellId,

package/src/core/cells/scrollCellIntoView.ts

@@ -7,6 +7,7 @@ import {
 import type { CellHandle } from "@/components/editor/notebook-cell";
 import { retryWithTimeout } from "@/utils/timeout";
 import { Logger } from "../../utils/Logger";
+import { editorMountScheduler } from "../codemirror/editor-mount-scheduler";
 import { scrollActiveLineIntoView } from "../codemirror/extensions";
 import { goToVariableDefinition } from "../codemirror/go-to-definition/commands";
 import { getCellEditorView } from "./cells";
@@ -48,6 +49,9 @@ export function focusAndScrollCellIntoView({
     // https://github.com/marimo-team/marimo/issues/2940
     tryFocus(element);
   } else {
+    // Build this cell's editor now if it is still queued, so focus can land in
+    // it instead of the placeholder.
+    editorMountScheduler.promote(cellId);
     const editor = cell.current?.editorView;
     if (!editor) {
       Logger.warn("scrollCellIntoView: editor not found", cellId);

package/src/core/cells/utils.ts

@@ -29,7 +29,7 @@ export function notebookCells(state: NotebookState) {
 export function notebookCellEditorViews({ cellHandles }: NotebookState) {
   const views: Record<CellId, EditorView> = {};
   for (const [cell, ref] of Objects.entries(cellHandles)) {
-    if (!ref.current) {
+    if (!ref.current?.editorView) {
       continue;
     }
     views[cell] = ref.current.editorView;