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

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

package/src/components/ui/select-core/select-list.tsx

@@ -0,0 +1,248 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type * as React from "react";
+import { Virtuoso } from "react-virtuoso";
+import { CompactChipRow } from "@/components/ui/value-chips";
+import { cn } from "@/utils/cn";
+import { Combobox } from "../combobox";
+import { CommandItem, CommandSeparator } from "../command";
+import { OptionRow } from "./option-row";
+import { renderSlot, type Slot } from "./render-slot";
+import type { BulkAction, Option, OptionState } from "./types";
+import { useSelectList } from "./use-select-list";
+
+/** Above this many options the list virtualizes. */
+export const VIRTUALIZE_THRESHOLD = 200;
+
+/** Fixed pixel height of the virtualized viewport (Virtuoso requires one). */
+export const VIRTUALIZED_LIST_HEIGHT = 200;
+
+function bulkActionLabel<V>(action: BulkAction<V>): string {
+  switch (action.kind) {
+    case "select-all":
+      return "Select all";
+    case "deselect-all":
+      return "Deselect all";
+    case "select-matching":
+      return `Select ${action.items.length} matching`;
+    case "deselect-matching":
+      return `Deselect ${action.items.length} matching`;
+  }
+}
+
+interface SelectListProps<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;
+  /** Float the (frozen) selection to the top of the idle menu, with a separator. */
+  pinSelected?: boolean;
+  /** Summarize the selection in the trigger as a compact chip row instead of "N selected". */
+  compactChipTrigger?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  fullWidth?: boolean;
+  className?: string;
+  id?: string;
+  "data-testid"?: string;
+  /** Renders the row content; the core owns the interactive container. */
+  renderOption?: (option: Option<V>, state: OptionState) => React.ReactNode;
+  /** Shown when no option matches the current query. */
+  renderEmpty?: Slot;
+  /**
+   * Virtualize once the visible option count exceeds this. Lower it when
+   * `renderOption` produces expensive rows so they virtualize sooner.
+   */
+  virtualizeThreshold?: number;
+  /** Fixed pixel height of the virtualized viewport. */
+  virtualizedHeight?: number;
+}
+
+export function SelectList<V>(props: SelectListProps<V>): React.JSX.Element {
+  const {
+    options,
+    value,
+    onChange,
+    multiple,
+    maxSelections,
+    allowSelectNone,
+    pinSelected = false,
+    compactChipTrigger = false,
+    placeholder = "Select...",
+    disabled = false,
+    fullWidth = false,
+    className,
+    id,
+    renderOption,
+    renderEmpty = "Nothing found.",
+    virtualizeThreshold = VIRTUALIZE_THRESHOLD,
+    virtualizedHeight = VIRTUALIZED_LIST_HEIGHT,
+  } = props;
+
+  const list = useSelectList<V>({
+    options,
+    value,
+    onChange,
+    multiple,
+    maxSelections,
+    allowSelectNone,
+    pinSelected,
+  });
+
+  const handleComboChange = (next: V[] | V | null): void => {
+    if (!multiple) {
+      if (next == null && !allowSelectNone) {
+        return;
+      }
+      onChange(next);
+      return;
+    }
+    let arr = Array.isArray(next) ? next : [];
+    if (maxSelections != null && arr.length > maxSelections) {
+      arr = arr.slice(-maxSelections);
+    }
+    onChange(arr);
+  };
+
+  // Bulk rows render as raw CommandItem (not ComboboxItem) so Combobox's per-item
+  // toggle doesn't intercept them — only the action's own `run` fires on select.
+  const bulkRows: React.ReactNode[] = list.bulkActions.map((action) => {
+    const disabled =
+      "enabled" in action ? !action.enabled : action.items.length === 0;
+    return (
+      <CommandItem
+        key={action.kind}
+        data-slot="select-bulk"
+        className="pl-6 m-1 py-1"
+        value={`__bulk_${action.kind}`}
+        disabled={disabled}
+        onSelect={() => {
+          if (!disabled) {
+            action.run();
+          }
+        }}
+      >
+        {bulkActionLabel(action)}
+      </CommandItem>
+    );
+  });
+  if (bulkRows.length > 0) {
+    bulkRows.push(
+      <CommandSeparator key="_bulk_separator" data-slot="select-separator" />,
+    );
+  }
+
+  // Rendered at the start of the first unpinned row, not after the last pinned row,
+  // so the menu-separator's `last:hidden` Tailwind variant doesn't hide it inside
+  // Virtuoso's per-item wrapper.
+  const pinnedSeparator = (index: number): React.ReactNode =>
+    list.pinnedCount > 0 &&
+    index === list.pinnedCount &&
+    list.pinnedCount < list.visibleOptions.length ? (
+      <CommandSeparator key="_pinned_separator" data-slot="select-separator" />
+    ) : null;
+
+  const renderItems = () => {
+    if (list.visibleOptions.length > virtualizeThreshold) {
+      return (
+        <Virtuoso
+          data-slot="select-list"
+          style={{ height: virtualizedHeight }}
+          totalCount={list.visibleOptions.length}
+          overscan={50}
+          itemContent={(i: number) => {
+            const option = list.visibleOptions[i];
+            return (
+              <>
+                {i === 0 && bulkRows}
+                {pinnedSeparator(i)}
+                <OptionRow
+                  option={option}
+                  checked={list.isChecked(option.value)}
+                  renderOption={renderOption}
+                />
+              </>
+            );
+          }}
+        />
+      );
+    }
+
+    const rows = list.visibleOptions.flatMap((option, i) => {
+      const separator = pinnedSeparator(i);
+      const row = (
+        <OptionRow
+          key={String(option.value)}
+          option={option}
+          checked={list.isChecked(option.value)}
+          renderOption={renderOption}
+        />
+      );
+      return separator ? [separator, row] : [row];
+    });
+
+    return (
+      <>
+        {bulkRows}
+        {rows}
+      </>
+    );
+  };
+
+  const renderTriggerValue = (current: V[] | V | null): React.ReactNode => {
+    const items = Array.isArray(current)
+      ? current
+      : current != null
+        ? [current]
+        : [];
+    if (items.length === 0) {
+      return <span className="text-muted-foreground">{placeholder}</span>;
+    }
+    return <CompactChipRow items={items.map(list.labelOf)} max={3} />;
+  };
+
+  // Props shared by both branches. `multiple`/`value`/`onValueChange` are the
+  // Combobox's discriminant trio, so they're set per-branch below with the
+  // literal `multiple` that matches each value/handler shape.
+  const comboboxProps = {
+    "data-slot": "select-root",
+    "data-testid": props["data-testid"],
+    displayValue: (option: V) => list.labelOf(option),
+    renderValue: compactChipTrigger ? renderTriggerValue : undefined,
+    placeholder,
+    className: cn({ "w-full": fullWidth }, className),
+    shouldFilter: false as const,
+    search: list.searchQuery,
+    onSearchChange: list.setSearchQuery,
+    open: list.open,
+    onOpenChange: list.setOpen,
+    emptyState: renderSlot(renderEmpty),
+    disabled,
+    id,
+  };
+
+  return multiple ? (
+    <Combobox<V>
+      {...comboboxProps}
+      multiple={true}
+      value={value as V[] | null}
+      onValueChange={handleComboChange}
+    >
+      {renderItems()}
+    </Combobox>
+  ) : (
+    <Combobox<V>
+      {...comboboxProps}
+      multiple={false}
+      value={value as V | null}
+      onValueChange={handleComboChange}
+    >
+      {renderItems()}
+    </Combobox>
+  );
+}

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

@@ -0,0 +1,44 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** A single selectable item. */
+export interface Option<V = string> {
+  /** Selection identity; what the adapter serializes. */
+  value: V;
+  /** Human-readable string used for display, filtering, and chip text. */
+  label: string;
+  /** Whether the option can be selected. */
+  disabled?: boolean;
+  /** Arbitrary per-row payload (e.g. `{ count }`) read by render slots. */
+  data?: unknown;
+}
+
+/**
+ * Live state of an option, passed to `renderOption` so custom rows can reflect
+ * selection. Keyboard highlight is exposed on the row element as
+ * `aria-selected` / `data-selected`, so custom rows style it via CSS.
+ */
+export interface OptionState {
+  /** Whether the option is currently selected. */
+  checked: boolean;
+}
+
+/**
+ * Pure-data description of one bulk row to render above the option list. The
+ * hook decides which specs exist for the current search/cap state; the facade
+ * decides labels and markup.
+ *
+ * - `select-all` / `deselect-all` act on the whole option list — the facade
+ *   already has it as a prop, so the spec just carries `enabled` for the
+ *   disabled-but-visible state (e.g. everything already picked).
+ * - `select-matching` / `deselect-matching` act on the search-filtered subset,
+ *   which the facade can't see; `items` carries that subset so the facade can
+ *   label the row ("Select N matching") and the slot is omitted when empty.
+ */
+export type BulkActionSpec<V> =
+  | { kind: "select-all"; enabled: boolean }
+  | { kind: "deselect-all"; enabled: boolean }
+  | { kind: "select-matching"; items: Array<Option<V>> }
+  | { kind: "deselect-matching"; items: Array<Option<V>> };
+
+/** A renderable bulk action: spec + the closure that applies it on click. */
+export type BulkAction<V> = BulkActionSpec<V> & { run: () => void };

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