@marimo-team/islands 0.23.10-dev26 → 0.23.10-dev28

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/plugins/impl/MultiselectPlugin.tsx

@@ -1,13 +1,10 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { type JSX, useId, useMemo, useState } from "react";
-import { Virtuoso } from "react-virtuoso";
+import { type JSX, useId, useMemo } from "react";
 import { z } from "zod";
-import { cn } from "@/utils/cn";
-import { Combobox, ComboboxItem } from "../../components/ui/combobox";
-import { CommandSeparator } from "../../components/ui/command";
+import type { Option } from "@/components/ui/select-core";
+import { SelectList } from "@/components/ui/select-core";
 import type { IPlugin, IPluginProps, Setter } from "../types";
 import { Labeled } from "./common/labeled";
-import { multiselectFilterFn } from "./multiselectFilterFn";
 
 interface Data {
   label: string | null;
@@ -55,9 +52,6 @@ interface MultiselectProps extends Data {
   setValue: Setter<T>;
 }
 
-const SELECT_ALL_KEY = "__select_all__";
-const DESELECT_ALL_KEY = "__deselect_all__";
-
 export const Multiselect = ({
   options,
   label,
@@ -68,144 +62,27 @@ export const Multiselect = ({
   disabled,
 }: MultiselectProps): JSX.Element => {
   const id = useId();
-  const [searchQuery, setSearchQuery] = useState<string>("");
-
-  const filteredOptions = useMemo(() => {
-    if (!searchQuery) {
-      return options;
-    }
-    return options.filter(
-      (option) => multiselectFilterFn(option, searchQuery) === 1,
-    );
-  }, [options, searchQuery]);
-
-  const handleValueChange = (newValues: string[] | null) => {
-    if (!newValues || newValues.length === 0) {
-      setValue([]);
-      return;
-    }
-
-    // Remove select all and deselect all from the new values
-    newValues = newValues.filter(
-      (value) => value !== SELECT_ALL_KEY && value !== DESELECT_ALL_KEY,
-    );
-
-    if (maxSelections === 1) {
-      // For single selection, just take the last selected value
-      setValue([newValues[newValues.length - 1]]);
-      return;
-    }
-
-    if (maxSelections != null && newValues.length > maxSelections) {
-      // When over max selections, remove oldest selections
-      newValues = newValues.slice(-maxSelections);
-    }
-    setValue(newValues);
-  };
-
-  const handleSelectAll = () => {
-    setValue(options);
-  };
-
-  const handleDeselectAll = () => {
-    setValue([]);
-  };
-
-  const extraOptions: React.ReactNode[] = [];
-  const selectAllEnabled = options.length > 0 && value.length < options.length;
-  const deselectAllEnabled = options.length > 0 && value.length > 0;
-
-  // Only show when more than 2 options
-  // Only show select all when maxSelections is not set
-  if (options.length > 2 && maxSelections == null) {
-    extraOptions.push(
-      <ComboboxItem
-        key={SELECT_ALL_KEY}
-        value={SELECT_ALL_KEY}
-        onSelect={handleSelectAll}
-        disabled={!selectAllEnabled}
-      >
-        Select all
-      </ComboboxItem>,
-    );
-  }
-
-  if (options.length > 2) {
-    extraOptions.push(
-      <ComboboxItem
-        key={DESELECT_ALL_KEY}
-        value={DESELECT_ALL_KEY}
-        onSelect={handleDeselectAll}
-        disabled={!deselectAllEnabled}
-      >
-        {maxSelections === 1 ? "Deselect" : "Deselect all"}
-      </ComboboxItem>,
-      <CommandSeparator key="_separator" />,
-    );
-  }
-
-  const renderList = () => {
-    // List virtualization
-    if (filteredOptions.length > 200) {
-      return (
-        <Virtuoso
-          style={{ height: "200px" }}
-          totalCount={filteredOptions.length}
-          overscan={50}
-          itemContent={(i: number) => {
-            const comboboxItem = (
-              <ComboboxItem key={filteredOptions[i]} value={filteredOptions[i]}>
-                {filteredOptions[i]}
-              </ComboboxItem>
-            );
-
-            if (i === 0) {
-              return (
-                <>
-                  {extraOptions}
-                  {comboboxItem}
-                </>
-              );
-            }
-
-            return comboboxItem;
-          }}
-        />
-      );
-    }
-
-    const list = filteredOptions.map((option) => (
-      <ComboboxItem key={option} value={option}>
-        {option}
-      </ComboboxItem>
-    ));
-
-    return (
-      <>
-        {extraOptions}
-        {list}
-      </>
-    );
-  };
+  const items = useMemo<Array<Option<string>>>(
+    () => options.map((option) => ({ value: option, label: option })),
+    [options],
+  );
 
   return (
     <Labeled label={label} id={id} fullWidth={fullWidth}>
-      <Combobox<string>
-        displayValue={(option) => option}
-        placeholder="Select..."
-        multiple={true}
-        className={cn({
-          "w-full": fullWidth,
-        })}
+      <SelectList<string>
+        id={id}
+        options={items}
         value={value}
-        onValueChange={handleValueChange}
-        shouldFilter={false}
-        search={searchQuery}
-        onSearchChange={setSearchQuery}
+        onChange={(next: string[] | string | null) =>
+          setValue((next as string[] | null) ?? [])
+        }
+        multiple={true}
+        maxSelections={maxSelections}
+        pinSelected={true}
+        compactChipTrigger={true}
+        fullWidth={fullWidth}
         disabled={disabled}
-      >
-        {renderList()}
-      </Combobox>
+      />
     </Labeled>
   );
 };