@marimo-team/islands 0.23.10-dev25 → 0.23.10-dev27

package/src/components/ui/combobox.tsx

@@ -2,7 +2,7 @@
 
 import { useControllableState } from "@radix-ui/react-use-controllable-state";
 import { Check, ChevronDownIcon, XCircle } from "lucide-react";
-import React, { createContext } from "react";
+import React, { createContext, useCallback, useMemo } from "react";
 import { cn } from "../../utils/cn";
 import { Functions } from "../../utils/functions";
 import { Badge } from "./badge";
@@ -40,6 +40,8 @@ interface ComboboxCommonProps<TValue> {
   id?: string;
   keepPopoverOpenOnSelect?: boolean;
   disabled?: boolean;
+  /** Override the trigger contents with a node (e.g. a compact chip summary). */
+  renderValue?: (value: TValue[] | TValue | null) => React.ReactNode;
 }
 
 type ComboboxFilterProps =
@@ -97,6 +99,7 @@ export const Combobox = <TValue,>({
   keepPopoverOpenOnSelect,
   id,
   disabled = false,
+  renderValue,
   ...rest
 }: ComboboxProps<TValue>) => {
   const [open = false, setOpen] = useControllableState({
@@ -112,39 +115,45 @@ export const Combobox = <TValue,>({
     },
   });
 
-  const isSelected = (selectedValue: unknown) => {
-    if (Array.isArray(value)) {
-      return value.includes(selectedValue as TValue);
-    }
-    return value === selectedValue;
-  };
+  const isSelected = useCallback(
+    (selectedValue: unknown) => {
+      if (Array.isArray(value)) {
+        return value.includes(selectedValue as TValue);
+      }
+      return value === selectedValue;
+    },
+    [value],
+  );
 
-  const handleSelect = (selectedValue: unknown) => {
-    let newValue: TValue | TValue[] | null = selectedValue as TValue;
+  const handleSelect = useCallback(
+    (selectedValue: unknown) => {
+      let newValue: TValue | TValue[] | null = selectedValue as TValue;
 
-    if (multiple) {
-      if (Array.isArray(value)) {
-        if (value.includes(newValue)) {
-          const newArr = value.filter((val) => val !== selectedValue);
-          newValue = newArr.length > 0 ? newArr : [];
+      if (multiple) {
+        if (Array.isArray(value)) {
+          if (value.includes(newValue)) {
+            const newArr = value.filter((val) => val !== selectedValue);
+            newValue = newArr.length > 0 ? newArr : [];
+          } else {
+            newValue = [...value, newValue];
+          }
         } else {
-          newValue = [...value, newValue];
+          newValue = [newValue];
         }
-      } else {
-        newValue = [newValue];
+      } else if (value === selectedValue) {
+        newValue = null;
       }
-    } else if (value === selectedValue) {
-      newValue = null;
-    }
 
-    setValue(newValue);
-    const keepOpen = keepPopoverOpenOnSelect ?? multiple;
-    if (!keepOpen) {
-      setOpen(false);
-    }
-  };
+      setValue(newValue);
+      const keepOpen = keepPopoverOpenOnSelect ?? multiple;
+      if (!keepOpen) {
+        setOpen(false);
+      }
+    },
+    [keepPopoverOpenOnSelect, multiple, value, setValue, setOpen],
+  );
 
-  const renderValue = (): string => {
+  const renderValueLabel = (): string => {
     // If we show chips, we don't want to change the placeholder
     if (multiple && chips && placeholder) {
       return placeholder;
@@ -168,6 +177,14 @@ export const Combobox = <TValue,>({
     return placeholder ?? "--";
   };
 
+  const comboboxContextValue: ComboboxContextValue = useMemo(
+    () => ({
+      isSelected,
+      onSelect: handleSelect,
+    }),
+    [isSelected, handleSelect],
+  );
+
   return (
     <div className={cn("relative")} {...rest}>
       <Popover
@@ -191,7 +208,9 @@ export const Combobox = <TValue,>({
             aria-expanded={open}
             aria-disabled={disabled}
           >
-            <span className="truncate flex-1 min-w-0">{renderValue()}</span>
+            <span className="truncate flex-1 min-w-0">
+              {renderValue ? renderValue(value ?? null) : renderValueLabel()}
+            </span>
             <ChevronDownIcon className="ml-3 w-4 h-4 opacity-50 shrink-0" />
           </button>
         </PopoverTrigger>
@@ -209,7 +228,7 @@ export const Combobox = <TValue,>({
             />
             <CommandList className="max-h-60 py-.5">
               <CommandEmpty>{emptyState}</CommandEmpty>
-              <ComboboxContext value={{ isSelected, onSelect: handleSelect }}>
+              <ComboboxContext value={comboboxContextValue}>
                 {children}
               </ComboboxContext>
             </CommandList>
@@ -277,12 +296,14 @@ export const ComboboxItem = React.forwardRef(
         ? value.value
         : String(value);
     const context = React.use(ComboboxContext);
+    const isOptionSelected = context.isSelected(value);
 
     return (
       <CommandItem
         ref={ref}
         className={cn("pl-6 m-1 py-1", className)}
         role="option"
+        aria-selected={isOptionSelected}
         value={valueAsString}
         disabled={disabled}
         onSelect={() => {
@@ -290,9 +311,7 @@ export const ComboboxItem = React.forwardRef(
           onSelect?.(value);
         }}
       >
-        {context.isSelected(value) && (
-          <Check className="absolute left-1 h-4 w-4" />
-        )}
+        {isOptionSelected && <Check className="absolute left-1 h-4 w-4" />}
         {children}
       </CommandItem>
     );

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";