@marimo-team/islands 0.23.10-dev3 → 0.23.10-dev31

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

@@ -0,0 +1,294 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { BulkAction, Option } from "../types";
+import { useSelectList } from "../use-select-list";
+
+const opts: Array<Option<string>> = [
+  { value: "a", label: "apple" },
+  { value: "b", label: "banana" },
+  { value: "c", label: "cherry" },
+];
+
+describe("useSelectList - search", () => {
+  it("filters visibleOptions by label using the strict word match", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: [],
+        onChange: vi.fn(),
+        multiple: true,
+      }),
+    );
+    act(() => result.current.setSearchQuery("ban"));
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual(["b"]);
+  });
+
+  it("returns all options when the query is empty", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: [],
+        onChange: vi.fn(),
+        multiple: true,
+      }),
+    );
+    expect(result.current.visibleOptions).toHaveLength(3);
+  });
+
+  it("keeps options for any positive filter score, not just 1", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: [],
+        onChange: vi.fn(),
+        multiple: true,
+        filterFn: (label) => (label === "apple" ? 0.5 : 0),
+      }),
+    );
+    act(() => result.current.setSearchQuery("anything"));
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual(["a"]);
+  });
+});
+
+describe("useSelectList - multi toggle", () => {
+  it("adds an unselected value", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({ options: opts, value: ["a"], onChange, multiple: true }),
+    );
+    act(() => result.current.toggle("b"));
+    expect(onChange).toHaveBeenCalledWith(["a", "b"]);
+  });
+
+  it("removes a selected value", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["a", "b"],
+        onChange,
+        multiple: true,
+      }),
+    );
+    act(() => result.current.toggle("a"));
+    expect(onChange).toHaveBeenCalledWith(["b"]);
+  });
+
+  it("drops the oldest selection when maxSelections is exceeded", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["a", "b"],
+        onChange,
+        multiple: true,
+        maxSelections: 2,
+      }),
+    );
+    act(() => result.current.toggle("c"));
+    expect(onChange).toHaveBeenCalledWith(["b", "c"]);
+  });
+
+  it("isChecked reflects membership", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["a"],
+        onChange: vi.fn(),
+        multiple: true,
+      }),
+    );
+    expect(result.current.isChecked("a")).toBe(true);
+    expect(result.current.isChecked("b")).toBe(false);
+  });
+});
+
+describe("useSelectList - single toggle", () => {
+  it("replaces the value", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({ options: opts, value: "a", onChange, multiple: false }),
+    );
+    act(() => result.current.toggle("b"));
+    expect(onChange).toHaveBeenCalledWith("b");
+  });
+
+  it("clears to null when allowSelectNone and the value is re-toggled", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: "a",
+        onChange,
+        multiple: false,
+        allowSelectNone: true,
+      }),
+    );
+    act(() => result.current.toggle("a"));
+    expect(onChange).toHaveBeenCalledWith(null);
+  });
+});
+
+describe("useSelectList - pinning + freeze", () => {
+  it("pins selected to the top of visibleOptions when open and idle", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["c"],
+        onChange: vi.fn(),
+        multiple: true,
+        pinSelected: true,
+      }),
+    );
+    act(() => result.current.setOpen(true));
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual([
+      "c",
+      "a",
+      "b",
+    ]);
+    expect(result.current.pinnedCount).toBe(1);
+  });
+
+  it("freezes pinned order while open: a newly toggled item does not re-pin", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useSelectList({
+          options: opts,
+          value,
+          onChange,
+          multiple: true,
+          pinSelected: true,
+        }),
+      { initialProps: { value: ["c"] as string[] } },
+    );
+    act(() => result.current.setOpen(true));
+    rerender({ value: ["c", "a"] });
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual([
+      "c",
+      "a",
+      "b",
+    ]);
+    expect(result.current.isChecked("a")).toBe(true);
+  });
+
+  it("re-pins when the search clears", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useSelectList({
+          options: opts,
+          value,
+          onChange: vi.fn(),
+          multiple: true,
+          pinSelected: true,
+        }),
+      { initialProps: { value: ["b"] as string[] } },
+    );
+    act(() => result.current.setOpen(true));
+    act(() => result.current.setSearchQuery("a"));
+    rerender({ value: ["b", "a"] });
+    act(() => result.current.setSearchQuery(""));
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual([
+      "b",
+      "a",
+      "c",
+    ]);
+  });
+
+  it("does not pin when pinSelected is false", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["c"],
+        onChange: vi.fn(),
+        multiple: true,
+      }),
+    );
+    act(() => result.current.setOpen(true));
+    expect(result.current.visibleOptions.map((o) => o.value)).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+    expect(result.current.pinnedCount).toBe(0);
+  });
+});
+
+describe("useSelectList - bulk", () => {
+  const findAction = <K extends BulkAction<string>["kind"]>(
+    actions: ReadonlyArray<BulkAction<string>>,
+    kind: K,
+  ): Extract<BulkAction<string>, { kind: K }> | undefined =>
+    actions.find(
+      (a): a is Extract<BulkAction<string>, { kind: K }> => a.kind === kind,
+    );
+
+  it("idle: select-all picks every option; deselect-all clears", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({ options: opts, value: ["a"], onChange, multiple: true }),
+    );
+    act(() => findAction(result.current.bulkActions, "select-all")?.run());
+    expect(onChange).toHaveBeenCalledWith(["a", "b", "c"]);
+    onChange.mockClear();
+    act(() => findAction(result.current.bulkActions, "deselect-all")?.run());
+    expect(onChange).toHaveBeenCalledWith([]);
+  });
+
+  it("idle: select-all skips disabled options and keeps the existing selection", () => {
+    const onChange = vi.fn();
+    const withDisabled: Array<Option<string>> = [
+      { value: "a", label: "apple" },
+      { value: "b", label: "banana", disabled: true },
+      { value: "c", label: "cherry" },
+    ];
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: withDisabled,
+        value: ["c"],
+        onChange,
+        multiple: true,
+      }),
+    );
+    act(() => findAction(result.current.bulkActions, "select-all")?.run());
+    expect(onChange).toHaveBeenCalledWith(["c", "a"]);
+  });
+
+  it("searching: select-matching acts only on the matches (additive)", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() =>
+      useSelectList({ options: opts, value: ["a"], onChange, multiple: true }),
+    );
+    act(() => result.current.setSearchQuery("b"));
+    act(() => findAction(result.current.bulkActions, "select-matching")?.run());
+    expect(onChange).toHaveBeenCalledWith(["a", "b"]);
+  });
+
+  it("exposes idle bulkActions in select-then-deselect order", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: ["a"],
+        onChange: vi.fn(),
+        multiple: true,
+      }),
+    );
+    const kinds = result.current.bulkActions.map((a) => a.kind);
+    expect(kinds).toEqual(["select-all", "deselect-all"]);
+    const selectAll = findAction(result.current.bulkActions, "select-all");
+    expect(selectAll && "enabled" in selectAll && selectAll.enabled).toBe(true);
+  });
+
+  it("bulkActions is empty for single-select", () => {
+    const { result } = renderHook(() =>
+      useSelectList({
+        options: opts,
+        value: "a",
+        onChange: vi.fn(),
+        multiple: false,
+      }),
+    );
+    expect(result.current.bulkActions).toEqual([]);
+  });
+});

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

@@ -0,0 +1,222 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import type { Option } from "../types";
+import {
+  deselectMatching,
+  getBulkActions,
+  getVisibleOptions,
+  multiselectFilterFn,
+  selectMatching,
+} from "../utils";
+
+describe("multiselectFilterFn", () => {
+  it("matches when all query words appear in the option (any order)", () => {
+    expect(multiselectFilterFn("foo bar", "bar foo")).toBe(1);
+  });
+
+  it("does not match a partial word", () => {
+    expect(multiselectFilterFn("foo bar", "foob")).toBe(0);
+  });
+});
+
+describe("selectMatching", () => {
+  it("adds only unselected matches, existing first then additions", () => {
+    expect(selectMatching(["a"], ["a", "b", "c"])).toEqual(["a", "b", "c"]);
+  });
+
+  it("keeps selections outside the filter untouched", () => {
+    expect(selectMatching(["x", "y"], ["a", "b"])).toEqual([
+      "x",
+      "y",
+      "a",
+      "b",
+    ]);
+  });
+
+  it("is generic over the value type", () => {
+    expect(selectMatching<number>([1], [1, 2])).toEqual([1, 2]);
+  });
+});
+
+describe("deselectMatching", () => {
+  it("removes only the matching items", () => {
+    expect(deselectMatching(["a", "b", "c"], ["a", "c"])).toEqual(["b"]);
+  });
+
+  it("leaves out-of-filter selections intact", () => {
+    expect(deselectMatching(["x", "a"], ["a", "b"])).toEqual(["x"]);
+  });
+});
+
+const opt = (value: string): Option<string> => ({ value, label: value });
+
+describe("getVisibleOptions", () => {
+  it("pins selected options first, both groups in option order", () => {
+    const options = ["a", "b", "c", "d"].map(opt);
+    const { visibleOptions, pinnedCount } = getVisibleOptions(
+      options,
+      new Set(["b", "d"]),
+    );
+    expect(visibleOptions.map((o) => o.value)).toEqual(["b", "d", "a", "c"]);
+    expect(pinnedCount).toBe(2);
+  });
+
+  it("returns options unchanged when nothing is pinned", () => {
+    const options = ["a", "b", "c"].map(opt);
+    const { visibleOptions, pinnedCount } = getVisibleOptions(
+      options,
+      new Set(),
+    );
+    expect(visibleOptions.map((o) => o.value)).toEqual(["a", "b", "c"]);
+    expect(pinnedCount).toBe(0);
+  });
+
+  it("ignores pinned values that are not in options", () => {
+    const options = ["a", "b"].map(opt);
+    const { visibleOptions, pinnedCount } = getVisibleOptions(
+      options,
+      new Set(["b", "ghost"]),
+    );
+    expect(visibleOptions.map((o) => o.value)).toEqual(["b", "a"]);
+    expect(pinnedCount).toBe(1);
+  });
+});
+
+const bulkBase = {
+  options: ["a", "b", "c", "d"].map(opt),
+  value: [] as string[],
+  searchQuery: "",
+  maxSelections: undefined as number | undefined,
+};
+
+describe("getBulkActions", () => {
+  it("returns no specs for 2 or fewer options", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        options: ["a", "b"].map(opt),
+        filteredOptions: ["a", "b"].map(opt),
+      }),
+    ).toEqual([]);
+  });
+
+  it("returns no specs when maxSelections is 1", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        filteredOptions: bulkBase.options,
+        maxSelections: 1,
+      }),
+    ).toEqual([]);
+  });
+
+  it("idle: select-all then deselect-all, both enabled", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a"],
+        filteredOptions: bulkBase.options,
+      }),
+    ).toEqual([
+      { kind: "select-all", enabled: true },
+      { kind: "deselect-all", enabled: true },
+    ]);
+  });
+
+  it("idle: select-all disabled when everything is selected", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a", "b", "c", "d"],
+        filteredOptions: bulkBase.options,
+      }),
+    ).toEqual([
+      { kind: "select-all", enabled: false },
+      { kind: "deselect-all", enabled: true },
+    ]);
+  });
+
+  it("searching: items reflect unselected vs selected matches", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a"],
+        searchQuery: "x",
+        filteredOptions: ["a", "b", "c"].map(opt),
+      }),
+    ).toEqual([
+      { kind: "select-matching", items: ["b", "c"].map(opt) },
+      { kind: "deselect-matching", items: ["a"].map(opt) },
+    ]);
+  });
+
+  it("searching with no matches: no specs", () => {
+    expect(
+      getBulkActions({ ...bulkBase, searchQuery: "zzz", filteredOptions: [] }),
+    ).toEqual([]);
+  });
+
+  it("searching: omits select-matching when all matches are already selected", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a", "b"],
+        searchQuery: "x",
+        filteredOptions: ["a", "b"].map(opt),
+      }),
+    ).toEqual([{ kind: "deselect-matching", items: ["a", "b"].map(opt) }]);
+  });
+
+  it("maxSelections > 1: deselect-side only, idle and searching", () => {
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a"],
+        filteredOptions: bulkBase.options,
+        maxSelections: 3,
+      }),
+    ).toEqual([{ kind: "deselect-all", enabled: true }]);
+
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        value: ["a"],
+        searchQuery: "x",
+        filteredOptions: ["a", "b"].map(opt),
+        maxSelections: 3,
+      }),
+    ).toEqual([{ kind: "deselect-matching", items: ["a"].map(opt) }]);
+  });
+
+  it("idle: select-all is disabled when only disabled options remain unselected", () => {
+    const options = [opt("a"), { value: "b", label: "b", disabled: true }];
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        options: [...options, opt("c")],
+        value: ["a", "c"],
+        filteredOptions: [...options, opt("c")],
+      }),
+    ).toEqual([
+      { kind: "select-all", enabled: false },
+      { kind: "deselect-all", enabled: true },
+    ]);
+  });
+
+  it("searching: select-matching omits disabled matches", () => {
+    const filteredOptions = [
+      opt("a"),
+      { value: "b", label: "b", disabled: true },
+      opt("c"),
+    ];
+    expect(
+      getBulkActions({
+        ...bulkBase,
+        options: filteredOptions,
+        value: [],
+        searchQuery: "x",
+        filteredOptions,
+      }),
+    ).toEqual([{ kind: "select-matching", items: ["a", "c"].map(opt) }]);
+  });
+});

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

@@ -0,0 +1,16 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+export {
+  SelectList,
+  VIRTUALIZE_THRESHOLD,
+  VIRTUALIZED_LIST_HEIGHT,
+} from "./select-list";
+export { useSelectList } from "./use-select-list";
+export { renderSlot, type Slot } from "./render-slot";
+export type { BulkAction, BulkActionSpec, Option, OptionState } from "./types";
+export {
+  deselectMatching,
+  getBulkActions,
+  getVisibleOptions,
+  multiselectFilterFn,
+  selectMatching,
+} from "./utils";

package/src/components/ui/select-core/option-row.tsx

@@ -0,0 +1,33 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import * as React from "react";
+import { ComboboxItem } from "../combobox";
+import type { Option, OptionState } from "./types";
+
+interface OptionRowProps<V> {
+  option: Option<V>;
+  checked: boolean;
+  renderOption?: (option: Option<V>, state: OptionState) => React.ReactNode;
+}
+
+function OptionRowImpl<V>({
+  option,
+  checked,
+  renderOption,
+}: OptionRowProps<V>): React.JSX.Element {
+  return (
+    <ComboboxItem
+      data-slot="select-option"
+      data-checked={checked || undefined}
+      // Selection identity, not the display string: the Combobox tracks
+      // `isSelected`/`onSelect` by this value and echoes it back through
+      // `onValueChange`. The cast bridges the unconstrained option type to
+      // ComboboxItem's stringifiable-value bound.
+      value={option.value as string | number}
+      disabled={option.disabled}
+    >
+      {renderOption ? renderOption(option, { checked }) : option.label}
+    </ComboboxItem>
+  );
+}
+
+export const OptionRow = React.memo(OptionRowImpl) as typeof OptionRowImpl;

package/src/components/ui/select-core/render-slot.ts

@@ -0,0 +1,20 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type React from "react";
+
+/**
+ * A customizable piece of UI: either fixed content, or a function that builds it
+ * from `A`. The thunk form lets callers defer work (or read render-time args)
+ * until the slot is actually shown.
+ */
+export type Slot<A extends unknown[] = []> =
+  | React.ReactNode
+  | ((...args: A) => React.ReactNode);
+
+/** Resolve a {@link Slot} to its node, calling the thunk form with `args`. */
+export function renderSlot<A extends unknown[]>(
+  slot: Slot<A>,
+  ...args: A
+): React.ReactNode {
+  return typeof slot === "function" ? slot(...args) : slot;
+}