@sproutsocial/seeds-react-menu 1.13.0 → 1.16.0

package/src/v3/MultiCombobox.stories.tsx

@@ -1,6 +1,12 @@
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { FormField } from "@sproutsocial/seeds-react-form-field";
+import { Button } from "@sproutsocial/seeds-react-button";
+import {
+  ModalV2,
+  ModalBody,
+  ModalFooter,
+} from "@sproutsocial/seeds-react-modal";
 import { MultiCombobox } from "./MultiCombobox";
 import {
   books,
@@ -190,6 +196,28 @@ export const SelectableHeadings: Story = {
   ),
 };
 
+export const DisabledGroupHeadings: Story = {
+  name: "Disabled group headings",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick books">
+        {({ id }) => (
+          <MultiCombobox
+            id={id}
+            data={books}
+            itemToString={itemToString}
+            renderItem={renderItem}
+            placeholder="Search books..."
+            groupBy={(book) => book.author}
+            selectHeadings
+            isGroupHeaderDisabled={(groupName) => groupName === "Harper Lee"}
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const SelectAll: Story = {
   name: "Select all",
   render: () => (
@@ -301,6 +329,28 @@ export const MaxTokens: Story = {
   ),
 };
 
+export const LargeBookSetWithMaxTokens: Story = {
+  name: "Large book set with max tokens",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick books">
+        {({ id }) => (
+          <MultiCombobox
+            id={id}
+            data={largeBookSet}
+            itemToString={itemToString}
+            renderItem={renderItem}
+            placeholder="Search books..."
+            isVirtualized
+            selectAll
+            maxTokens={5}
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const Loading: Story = {
   name: "Loading",
   render: () => (
@@ -472,3 +522,115 @@ export const Creatable: Story = {
     );
   },
 };
+
+// Story to help visualize what the combobox component looks like when it's invalid within a FormField component
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField
+        label="Pick books"
+        isInvalid
+        error="Please pick at least one book."
+      >
+        {({ id, isInvalid }) => (
+          <MultiCombobox
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Search books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
+// Story to help visualize what the combobox component looks like when it's required within a FormField component
+export const Required: Story = {
+  name: "Required",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick books" required>
+        {({ id, required }) => (
+          <MultiCombobox
+            id={id}
+            required={required}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Search books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
+export const LargeBookSetWithMaxTokensInModal: Story = {
+  name: "Large book set with max tokens (in modal)",
+  render: () => (
+    <ModalV2
+      title="Pick some books"
+      modalTrigger={<Button appearance="primary">Open Modal</Button>}
+      closeButtonAriaLabel="Close"
+    >
+      <ModalBody>
+        <div style={{ width: "300px" }}>
+          <FormField label="Pick books">
+            {({ id }) => (
+              <MultiCombobox
+                id={id}
+                data={largeBookSet}
+                itemToString={itemToString}
+                renderItem={renderItem}
+                placeholder="Search books..."
+                isVirtualized
+                selectAll
+                maxTokens={5}
+              />
+            )}
+          </FormField>
+        </div>
+      </ModalBody>
+      <ModalFooter cancelButton={<Button>Cancel</Button>} />
+    </ModalV2>
+  ),
+};
+
+// Verifies the a11y fix for Escape key containment. Open the modal, open the
+// combobox dropdown, then press Escape: the dropdown should close and focus
+// should return to the input — the modal should stay open. Pressing Escape
+// again (with the dropdown closed) should close the modal.
+export const EscapeKeyInModal: Story = {
+  name: "Escape Key in Modal (a11y)",
+  render: () => (
+    <ModalV2
+      title="Pick some books"
+      modalTrigger={<Button appearance="primary">Open Modal</Button>}
+      closeButtonAriaLabel="Close"
+    >
+      <ModalBody>
+        <div style={{ width: "300px", padding: "16px 0" }}>
+          <FormField label="Pick books">
+            {({ id }) => (
+              <MultiCombobox
+                id={id}
+                data={books}
+                itemToString={itemToString}
+                placeholder="Search books..."
+              />
+            )}
+          </FormField>
+          <p style={{ marginTop: 16, fontSize: 14 }}>
+            <strong>To verify:</strong> open the combobox, press{" "}
+            <kbd>Escape</kbd>. The dropdown should close and focus should return
+            to the input. The modal should remain open. Press <kbd>Escape</kbd>{" "}
+            again to close the modal.
+          </p>
+        </div>
+      </ModalBody>
+      <ModalFooter cancelButton={<Button>Cancel</Button>} />
+    </ModalV2>
+  ),
+};

package/src/v3/MultiCombobox.tsx

@@ -3,6 +3,7 @@ import { Combobox } from "@base-ui/react/combobox";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import VirtualizedComboboxList from "./Common/VirtualizedComboboxList";
 import { useSeedsPortalContainer } from "./SeedsPortal";
+import { useSuppressEscapeClear } from "./Common/useSuppressEscapeClear";
 import ComboboxItem from "./Common/ComboboxItem";
 import type { DataWithId } from "./Common/types";
 import { groupItems } from "./Common/groupItems";
@@ -74,6 +75,8 @@ interface MultiComboboxBaseProps {
   inputValue?: string;
   onInputValueChange?: (value: string) => void;
   "aria-describedby"?: string;
+  isInvalid?: boolean;
+  required?: boolean;
   fullWidth?: boolean;
 }
 
@@ -90,6 +93,7 @@ interface MultiComboboxDataProps<T extends DataWithId>
   onSelectedItemIdsChange?: (ids: Array<T["id"]>) => void;
   groupBy?: (item: T) => string;
   renderGroupHeading?: (label: string) => React.ReactNode;
+  isGroupHeaderDisabled?: (groupName: string) => boolean;
   selectHeadings?: boolean;
   selectAll?: boolean | string;
   isVirtualized?: boolean;
@@ -113,6 +117,7 @@ interface MultiComboboxChildrenProps extends MultiComboboxBaseProps {
   inputType?: never;
   groupBy?: never;
   renderGroupHeading?: never;
+  isGroupHeaderDisabled?: never;
   selectHeadings?: never;
   selectAll?: never;
   removeSelectedItems?: never;
@@ -145,6 +150,7 @@ export function MultiCombobox<T extends DataWithId>(
     fullWidth = true,
   } = props;
   const ariaDescribedBy = props["aria-describedby"];
+  const isInvalid = props.isInvalid;
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -180,6 +186,9 @@ export function MultiCombobox<T extends DataWithId>(
   const renderGroupHeading = isChildrenMode
     ? undefined
     : (props as MultiComboboxDataProps<T>).renderGroupHeading;
+  const isGroupHeaderDisabled = isChildrenMode
+    ? undefined
+    : (props as MultiComboboxDataProps<T>).isGroupHeaderDisabled;
   const selectHeadings = isChildrenMode
     ? false
     : (props as MultiComboboxDataProps<T>).selectHeadings ?? false;
@@ -213,6 +222,9 @@ export function MultiCombobox<T extends DataWithId>(
   const virtualizerRef = React.useRef<ReturnType<
     typeof useVirtualizer<HTMLDivElement, Element>
   > | null>(null);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const onInputKeyDownCapture = useSuppressEscapeClear(open);
 
   const isControlled = selectedItemIds !== undefined;
 
@@ -331,6 +343,7 @@ export function MultiCombobox<T extends DataWithId>(
 
     let updated = [...realItems];
     for (const sentinel of groupSentinels) {
+      if (isGroupHeaderDisabled?.(sentinel.groupName)) continue;
       const group = groups?.find((g) => g.value === sentinel.groupName);
       if (!group) continue;
       const allSelected = group.items.every((item) =>
@@ -368,6 +381,7 @@ export function MultiCombobox<T extends DataWithId>(
     e.preventDefault();
     e.stopPropagation();
     setSelectedItems(value.filter((v) => v.id !== item.id));
+    inputRef.current?.focus();
   }
 
   // ─── Render sentinel item ─────────────────────────────────────────────────
@@ -403,7 +417,11 @@ export function MultiCombobox<T extends DataWithId>(
           ? "all"
           : "partial";
       return (
-        <ComboboxGroupHeaderItem key={`__header-${row.groupName}`} value={row}>
+        <ComboboxGroupHeaderItem
+          key={`__header-${row.groupName}`}
+          value={row}
+          disabled={isGroupHeaderDisabled?.(row.groupName)}
+        >
           <ComboboxGroupHeaderCheckbox
             $state={state}
             id={`__header-${row.groupName}`}
@@ -492,7 +510,10 @@ export function MultiCombobox<T extends DataWithId>(
         open={open}
         disabled={props.disabled}
         onOpenChange={(nextOpen, eventDetails) => {
-          if (!nextOpen && eventDetails.reason === "item-press") return;
+          if (!nextOpen && eventDetails.reason === "item-press") {
+            eventDetails.cancel();
+            return;
+          }
           setOpen(nextOpen);
         }}
         filter={
@@ -537,13 +558,14 @@ export function MultiCombobox<T extends DataWithId>(
                 if (!item || !virt) return;
                 const isStart = index === 0;
                 const isEnd = index === virt.options.count - 1;
-                if (
-                  reason === "none" ||
-                  (reason === "keyboard" && (isStart || isEnd))
-                ) {
+                // Only handle keyboard wrap-around: when navigation loops from
+                // the last item to the first (or vice versa), the wrapped item
+                // is outside the virtualized window and standard scroll-into-
+                // view can't find it.
+                if (reason === "keyboard" && (isStart || isEnd)) {
                   queueMicrotask(() => {
                     virt.scrollToIndex(index, {
-                      align: isEnd ? "start" : "end",
+                      align: isStart ? "start" : "end",
                     });
                   });
                 }
@@ -586,7 +608,10 @@ export function MultiCombobox<T extends DataWithId>(
         }}
         items={rootItems}
       >
-        <ComboboxTokenInputGroup>
+        <ComboboxTokenInputGroup
+          $isInvalid={isInvalid}
+          onKeyDownCapture={onInputKeyDownCapture}
+        >
           <ComboboxToken>
             {renderSelection
               ? renderSelection(value)
@@ -616,9 +641,12 @@ export function MultiCombobox<T extends DataWithId>(
                   );
                 })()}
             <ComboboxTokenInput
+              ref={inputRef}
               id={id}
               placeholder={value.length > 0 ? "" : placeholder}
               aria-describedby={ariaDescribedBy}
+              aria-invalid={isInvalid || undefined}
+              aria-required={props.required || undefined}
             />
             <ComboboxActionButtons>
               <ComboboxClear aria-label="Clear all">
@@ -669,6 +697,7 @@ export function MultiCombobox<T extends DataWithId>(
                     inputType={inputType}
                     renderItem={renderItem}
                     renderGroupHeading={renderGroupHeading}
+                    isGroupHeaderDisabled={isGroupHeaderDisabled}
                     renderCreatableItem={
                       creatableProp
                         ? (sentinel, style, index, measureRef) =>

package/src/v3/MultiSearchableSelect.stories.tsx

@@ -37,6 +37,30 @@ export const Basic: Story = {
   ),
 };
 
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField
+        label="Pick books"
+        isInvalid
+        error="Please pick at least one book."
+      >
+        {({ id, isInvalid }) => (
+          <MultiSearchableSelect
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Select books"
+            searchPlaceholder="Search books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const CustomRenderItem: Story = {
   name: "Custom render item",
   render: () => (

package/src/v3/MultiSearchableSelect.tsx

@@ -80,6 +80,8 @@ interface MultiSearchableSelectBaseProps {
   disabled?: boolean;
   filter?: ((item: unknown, query: string) => boolean) | null;
   "aria-describedby"?: string;
+  isInvalid?: boolean;
+  required?: boolean;
   fullWidth?: boolean;
 }
 
@@ -149,6 +151,7 @@ export function MultiSearchableSelect<T extends DataWithId>(
     fullWidth = true,
   } = props;
   const ariaDescribedBy = props["aria-describedby"];
+  const isInvalid = props.isInvalid;
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -502,13 +505,10 @@ export function MultiSearchableSelect<T extends DataWithId>(
                 if (!item || !virt) return;
                 const isStart = index === 0;
                 const isEnd = index === virt.options.count - 1;
-                if (
-                  reason === "none" ||
-                  (reason === "keyboard" && (isStart || isEnd))
-                ) {
+                if (reason === "keyboard" && (isStart || isEnd)) {
                   queueMicrotask(() => {
                     virt.scrollToIndex(index, {
-                      align: isEnd ? "start" : "end",
+                      align: isStart ? "start" : "end",
                     });
                   });
                 }
@@ -554,6 +554,9 @@ export function MultiSearchableSelect<T extends DataWithId>(
         <SearchableSelectTokenTrigger
           id={id}
           aria-describedby={ariaDescribedBy}
+          aria-invalid={isInvalid || undefined}
+          aria-required={props.required || undefined}
+          $isInvalid={isInvalid}
         >
           {renderSelection ? (
             renderSelection(value)

package/src/v3/MultiSelect.stories.tsx

@@ -37,6 +37,29 @@ export const Basic: Story = {
   ),
 };
 
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField
+        label="Pick books"
+        isInvalid
+        error="Please pick at least one book."
+      >
+        {({ id, isInvalid }) => (
+          <MultiSelect
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Select books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const CustomRenderItem: Story = {
   name: "Custom render item",
   render: () => (

package/src/v3/MultiSelect.tsx

@@ -44,6 +44,8 @@ interface MultiSelectBaseProps {
   placeholder?: string;
   disabled?: boolean;
   "aria-describedby"?: string;
+  isInvalid?: boolean;
+  required?: boolean;
   fullWidth?: boolean;
 }
 
@@ -91,6 +93,7 @@ export type MultiSelectProps<T extends DataWithId> =
 export function MultiSelect<T extends DataWithId>(props: MultiSelectProps<T>) {
   const { id, placeholder = "Select...", fullWidth = true } = props;
   const ariaDescribedBy = props["aria-describedby"];
+  const isInvalid = props.isInvalid;
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -182,7 +185,12 @@ export function MultiSelect<T extends DataWithId>(props: MultiSelectProps<T>) {
         disabled={props.disabled}
         id={id}
       >
-        <SelectTrigger aria-describedby={ariaDescribedBy}>
+        <SelectTrigger
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={isInvalid || undefined}
+          aria-required={props.required || undefined}
+          $isInvalid={isInvalid}
+        >
           <SelectValue>
             {() => {
               if (renderSelection) return renderSelection(selectedItems);

package/src/v3/SingleCombobox.stories.tsx

@@ -36,6 +36,25 @@ export const Basic: Story = {
   ),
 };
 
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick a book" isInvalid error="Please pick a book.">
+        {({ id, isInvalid }) => (
+          <SingleCombobox
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Search books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const CustomRenderItem: Story = {
   name: "Custom render item",
   render: () => (

package/src/v3/SingleCombobox.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { Combobox } from "@base-ui/react/combobox";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { useSeedsPortalContainer } from "./SeedsPortal";
+import { useSuppressEscapeClear } from "./Common/useSuppressEscapeClear";
 import ComboboxItem from "./Common/ComboboxItem";
 import VirtualizedComboboxList from "./Common/VirtualizedComboboxList";
 import type { DataWithId } from "./Common/types";
@@ -32,6 +33,8 @@ interface SingleComboboxBaseProps {
   disabled?: boolean;
   filter?: ((item: unknown, query: string) => boolean) | null;
   "aria-describedby"?: string;
+  isInvalid?: boolean;
+  required?: boolean;
   fullWidth?: boolean;
 }
 
@@ -93,6 +96,7 @@ export function SingleCombobox<T extends DataWithId>(
     fullWidth = true,
   } = props;
   const ariaDescribedBy = props["aria-describedby"];
+  const isInvalid = props.isInvalid;
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -137,6 +141,8 @@ export function SingleCombobox<T extends DataWithId>(
     typeof useVirtualizer<HTMLDivElement, Element>
   > | null>(null);
 
+  const onInputKeyDownCapture = useSuppressEscapeClear(open);
+
   const isControlled = selectedItemId !== undefined;
 
   const idToItem = React.useCallback(
@@ -193,13 +199,10 @@ export function SingleCombobox<T extends DataWithId>(
                 if (!item || !virt) return;
                 const isStart = index === 0;
                 const isEnd = index === virt.options.count - 1;
-                if (
-                  reason === "none" ||
-                  (reason === "keyboard" && (isStart || isEnd))
-                ) {
+                if (reason === "keyboard" && (isStart || isEnd)) {
                   queueMicrotask(() => {
                     virt.scrollToIndex(index, {
-                      align: isEnd ? "start" : "end",
+                      align: isStart ? "start" : "end",
                     });
                   });
                 }
@@ -207,11 +210,16 @@ export function SingleCombobox<T extends DataWithId>(
             : undefined
         }
       >
-        <ComboboxInputGroup>
+        <ComboboxInputGroup
+          $isInvalid={isInvalid}
+          onKeyDownCapture={onInputKeyDownCapture}
+        >
           <ComboboxInput
             placeholder={placeholder}
             id={id}
             aria-describedby={ariaDescribedBy}
+            aria-invalid={isInvalid || undefined}
+            aria-required={props.required || undefined}
           />
           <ComboboxActionButtons>
             <ComboboxClear aria-label="Clear selection">

package/src/v3/SingleSearchableSelect.stories.tsx

@@ -37,6 +37,26 @@ export const Basic: Story = {
   ),
 };
 
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick a book" isInvalid error="Please pick a book.">
+        {({ id, isInvalid }) => (
+          <SingleSearchableSelect
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Select a book"
+            searchPlaceholder="Search books..."
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const CustomRenderItem: Story = {
   name: "Custom render item",
   render: () => (

package/src/v3/SingleSearchableSelect.tsx

@@ -42,6 +42,8 @@ interface SingleSearchableSelectBaseProps {
   disabled?: boolean;
   filter?: ((item: unknown, query: string) => boolean) | null;
   "aria-describedby"?: string;
+  isInvalid?: boolean;
+  required?: boolean;
   fullWidth?: boolean;
 }
 
@@ -110,6 +112,7 @@ export function SingleSearchableSelect<T extends DataWithId>(
     fullWidth = true,
   } = props;
   const ariaDescribedBy = props["aria-describedby"];
+  const isInvalid = props.isInvalid;
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -226,13 +229,10 @@ export function SingleSearchableSelect<T extends DataWithId>(
                 if (!item || !virt) return;
                 const isStart = index === 0;
                 const isEnd = index === virt.options.count - 1;
-                if (
-                  reason === "none" ||
-                  (reason === "keyboard" && (isStart || isEnd))
-                ) {
+                if (reason === "keyboard" && (isStart || isEnd)) {
                   queueMicrotask(() => {
                     virt.scrollToIndex(index, {
-                      align: isEnd ? "start" : "end",
+                      align: isStart ? "start" : "end",
                     });
                   });
                 }
@@ -240,7 +240,13 @@ export function SingleSearchableSelect<T extends DataWithId>(
             : undefined
         }
       >
-        <SearchableSelectTrigger id={id} aria-describedby={ariaDescribedBy}>
+        <SearchableSelectTrigger
+          id={id}
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={isInvalid || undefined}
+          aria-required={props.required || undefined}
+          $isInvalid={isInvalid}
+        >
           <SearchableSelectPlaceholder>
             <Combobox.Value placeholder={placeholder}>
               {value

package/src/v3/SingleSelect.stories.tsx

@@ -37,6 +37,25 @@ export const Basic: Story = {
   ),
 };
 
+export const Invalid: Story = {
+  name: "Invalid",
+  render: () => (
+    <div style={{ width: "300px" }}>
+      <FormField label="Pick a book" isInvalid error="Please pick a book.">
+        {({ id, isInvalid }) => (
+          <SingleSelect
+            id={id}
+            isInvalid={isInvalid}
+            data={books}
+            itemToString={itemToString}
+            placeholder="Select a book"
+          />
+        )}
+      </FormField>
+    </div>
+  ),
+};
+
 export const Empty: Story = {
   name: "Empty",
   render: () => (