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

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

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