@sproutsocial/seeds-react-menu 1.12.1 → 1.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutsocial/seeds-react-menu",
-  "version": "1.12.1",
+  "version": "1.12.3",
   "description": "Seeds React Menu",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -37,17 +37,17 @@
   "dependencies": {
     "@radix-ui/react-popover": "^1.1.2",
     "@sproutsocial/seeds-react-box": "^1.1.16",
-    "@sproutsocial/seeds-react-button": "^2.0.4",
-    "@sproutsocial/seeds-react-checkbox": "^1.3.32",
-    "@sproutsocial/seeds-react-icon": "^2.3.6",
-    "@sproutsocial/seeds-react-input": "^1.5.15",
+    "@sproutsocial/seeds-react-button": "^2.0.5",
+    "@sproutsocial/seeds-react-checkbox": "^1.3.33",
+    "@sproutsocial/seeds-react-icon": "^2.3.7",
+    "@sproutsocial/seeds-react-input": "^1.5.16",
     "@sproutsocial/seeds-react-label": "^1.0.16",
-    "@sproutsocial/seeds-react-popout": "^2.4.37",
+    "@sproutsocial/seeds-react-popout": "^2.4.38",
     "@sproutsocial/seeds-react-radio": "^1.3.16",
-    "@sproutsocial/seeds-react-switch": "^1.2.31",
+    "@sproutsocial/seeds-react-switch": "^1.2.32",
     "@sproutsocial/seeds-react-system-props": "^3.0.2",
     "@sproutsocial/seeds-react-theme": "^3.6.2",
-    "@sproutsocial/seeds-react-token-input": "^1.4.37",
+    "@sproutsocial/seeds-react-token-input": "^1.4.38",
     "@sproutsocial/seeds-react-utilities": "^4.3.0",
     "@base-ui/react": "^1.3.0",
     "@tanstack/react-virtual": "^3.13.12",
@@ -57,7 +57,7 @@
     "styled-system": "^5.1.5"
   },
   "devDependencies": {
-    "@sproutsocial/seeds-react-tooltip": "^1.1.19",
+    "@sproutsocial/seeds-react-tooltip": "^1.1.20",
     "@sproutsocial/eslint-config-seeds": "*",
     "@sproutsocial/seeds-react-testing-library": "*",
     "@sproutsocial/seeds-testing": "*",

package/src/v3/Common/VirtualizedComboboxList.tsx

@@ -8,7 +8,11 @@ import {
   ComboboxSelectAllItem,
 } from "./ComboboxStyles";
 import type { DataWithId } from "./types";
-import { isPlaceholderSentinel } from "./sentinels";
+import {
+  isPlaceholderSentinel,
+  isCreatableSentinel,
+  type CreatableSentinel,
+} from "./sentinels";
 
 export const ITEM_HEIGHT = 32;
 
@@ -29,7 +33,11 @@ export function isSelectAllSentinel(v: unknown): v is SelectAllSentinel {
   return typeof v === "object" && v !== null && "__selectAll" in v;
 }
 
-export type FlatSentinelRow<T> = T | GroupHeaderSentinel | SelectAllSentinel;
+export type FlatSentinelRow<T> =
+  | T
+  | GroupHeaderSentinel
+  | SelectAllSentinel
+  | CreatableSentinel;
 
 interface VirtualizedComboboxListProps<T extends DataWithId> {
   open: boolean;
@@ -47,6 +55,12 @@ interface VirtualizedComboboxListProps<T extends DataWithId> {
   inputType: "icon" | "radio" | "checkbox" | "none";
   renderItem?: (item: T) => React.ReactNode;
   renderGroupHeading?: (label: string) => React.ReactNode;
+  renderCreatableItem?: (
+    sentinel: CreatableSentinel,
+    style: React.CSSProperties,
+    index: number,
+    measureRef: (el: Element | null) => void
+  ) => React.ReactNode;
 }
 
 export default function VirtualizedComboboxList<T extends DataWithId>({
@@ -59,6 +73,7 @@ export default function VirtualizedComboboxList<T extends DataWithId>({
   inputType,
   renderItem,
   renderGroupHeading,
+  renderCreatableItem,
 }: VirtualizedComboboxListProps<T>) {
   type Row = FlatSentinelRow<T>;
 
@@ -197,6 +212,18 @@ export default function VirtualizedComboboxList<T extends DataWithId>({
             );
           }
 
+          if (isCreatableSentinel(row)) {
+            if (renderCreatableItem) {
+              return renderCreatableItem(
+                row,
+                baseStyle,
+                virtualItem.index,
+                virtualizer.measureElement
+              );
+            }
+            return null;
+          }
+
           const item = row as T;
           return (
             <ComboboxItem

package/src/v3/Common/sentinels.ts

@@ -15,3 +15,16 @@ export function makePlaceholderSentinel(label: string): PlaceholderSentinel {
 export function isPlaceholderSentinel(v: unknown): v is PlaceholderSentinel {
   return typeof v === "object" && v !== null && "__placeholder" in v;
 }
+
+export interface CreatableSentinel {
+  __creatable: true;
+  label: string;
+}
+
+export function makeCreatableSentinel(label: string): CreatableSentinel {
+  return { __creatable: true, label };
+}
+
+export function isCreatableSentinel(v: unknown): v is CreatableSentinel {
+  return typeof v === "object" && v !== null && "__creatable" in v;
+}

package/src/v3/MultiCombobox.stories.tsx

@@ -8,6 +8,7 @@ import {
   largeBookSet,
   itemToString,
   renderItem,
+  type Book,
 } from "./storyData";
 
 const meta: Meta<typeof MultiCombobox> = {
@@ -421,3 +422,36 @@ export const CustomSearch: Story = {
     </div>
   ),
 };
+
+export const Creatable: Story = {
+  name: "Creatable",
+  render: () => {
+    const [bookList, setBookList] = React.useState<Book[]>(books);
+
+    return (
+      <div style={{ width: "300px" }}>
+        <FormField label="Pick or create books">
+          {({ id }) => (
+            <MultiCombobox
+              id={id}
+              data={bookList}
+              itemToString={itemToString}
+              placeholder="Search or create..."
+              isVirtualized
+              creatable
+              onCreate={(value) => {
+                const newBook: Book = {
+                  id: `book-custom-${value.toLowerCase().replace(/\s+/g, "-")}`,
+                  title: value,
+                  author: "Unknown",
+                };
+                setBookList((prev) => [...prev, newBook]);
+                return newBook;
+              }}
+            />
+          )}
+        </FormField>
+      </div>
+    );
+  },
+};

package/src/v3/MultiCombobox.tsx

@@ -6,6 +6,11 @@ import { useSeedsPortalContainer } from "./SeedsPortal";
 import ComboboxItem from "./Common/ComboboxItem";
 import type { DataWithId } from "./Common/types";
 import { groupItems } from "./Common/groupItems";
+import {
+  isCreatableSentinel,
+  makeCreatableSentinel,
+  type CreatableSentinel,
+} from "./Common/sentinels";
 import { Field } from "./Common/SelectStyles";
 import {
   ComboboxTokenInputGroup,
@@ -68,6 +73,7 @@ interface MultiComboboxBaseProps {
   filter?: ((item: unknown, query: string) => boolean) | null;
   inputValue?: string;
   onInputValueChange?: (value: string) => void;
+  "aria-describedby"?: string;
 }
 
 interface MultiComboboxDataProps<T extends DataWithId>
@@ -88,6 +94,8 @@ interface MultiComboboxDataProps<T extends DataWithId>
   isVirtualized?: boolean;
   removeSelectedItems?: boolean;
   maxTokens?: number;
+  creatable?: boolean;
+  onCreate?: (value: string) => T;
   children?: never;
 }
 
@@ -107,6 +115,8 @@ interface MultiComboboxChildrenProps extends MultiComboboxBaseProps {
   selectHeadings?: never;
   selectAll?: never;
   removeSelectedItems?: never;
+  creatable?: never;
+  onCreate?: never;
 }
 
 export type MultiComboboxProps<T extends DataWithId> =
@@ -132,6 +142,7 @@ export function MultiCombobox<T extends DataWithId>(
     inputValue,
     onInputValueChange,
   } = props;
+  const ariaDescribedBy = props["aria-describedby"];
 
   const isChildrenMode = "children" in props && props.children != null;
 
@@ -179,6 +190,12 @@ export function MultiCombobox<T extends DataWithId>(
   const isVirtualized = isChildrenMode
     ? false
     : (props as MultiComboboxDataProps<T>).isVirtualized ?? false;
+  const creatableProp = isChildrenMode
+    ? false
+    : (props as MultiComboboxDataProps<T>).creatable ?? false;
+  const onCreateProp = isChildrenMode
+    ? undefined
+    : (props as MultiComboboxDataProps<T>).onCreate;
   const children = isChildrenMode
     ? (props as MultiComboboxChildrenProps).children
     : undefined;
@@ -189,6 +206,8 @@ export function MultiCombobox<T extends DataWithId>(
 
   const { containerRef, portalContainer } = useSeedsPortalContainer();
   const [open, setOpen] = React.useState(false);
+  const [internalInputValue, setInternalInputValue] = React.useState("");
+  const skipNextInputChangeRef = React.useRef(false);
   const virtualizerRef = React.useRef<ReturnType<
     typeof useVirtualizer<HTMLDivElement, Element>
   > | null>(null);
@@ -226,11 +245,29 @@ export function MultiCombobox<T extends DataWithId>(
     [visibleData, groupBy]
   );
 
+  const currentInputValue = inputValue ?? internalInputValue;
+
+  const creatableSentinel = React.useMemo<CreatableSentinel | null>(() => {
+    if (!creatableProp) return null;
+    const trimmed = currentInputValue.trim();
+    if (!trimmed) return null;
+    const lowered = trimmed.toLocaleLowerCase();
+    const exactExists = data.some(
+      (d) => itemToString(d).trim().toLocaleLowerCase() === lowered
+    );
+    if (exactExists) return null;
+    return makeCreatableSentinel(trimmed);
+  }, [creatableProp, currentInputValue, data, itemToString]);
+
   // ─── Sentinel flat list ───────────────────────────────────────────────────
   // Used when selectHeadings or selectAll. selectAll implies selectHeadings —
   // group headers are always selectable when the list is flattened.
 
-  type FlatRow = T | GroupHeaderSentinel | SelectAllSentinel;
+  type FlatRow =
+    | T
+    | GroupHeaderSentinel
+    | SelectAllSentinel
+    | CreatableSentinel;
 
   const flatItems = React.useMemo<FlatRow[] | null>(() => {
     if (!selectHeadings && !selectAll) return null;
@@ -255,6 +292,22 @@ export function MultiCombobox<T extends DataWithId>(
   }
 
   function handleValueChange(next: FlatRow[]) {
+    const creatableClicked = next.find(isCreatableSentinel);
+    if (creatableClicked) {
+      const newItem = onCreateProp?.(creatableClicked.label);
+      const realItems = next.filter(
+        (v): v is T =>
+          !isGroupHeaderSentinel(v) &&
+          !isSelectAllSentinel(v) &&
+          !isCreatableSentinel(v)
+      );
+      setSelectedItems(newItem ? [...realItems, newItem] : realItems);
+      skipNextInputChangeRef.current = true;
+      setInternalInputValue("");
+      onInputValueChange?.("");
+      return;
+    }
+
     const selectAllClicked = next.filter(isSelectAllSentinel);
     const groupSentinels = next.filter(isGroupHeaderSentinel);
     const realItems = next.filter(
@@ -295,8 +348,18 @@ export function MultiCombobox<T extends DataWithId>(
     setSelectedItems(updated);
   }
 
-  function handleSimpleValueChange(newItems: T[]) {
-    setSelectedItems(newItems);
+  function handleSimpleValueChange(newItems: FlatRow[]) {
+    const creatableClicked = newItems.find(isCreatableSentinel);
+    if (creatableClicked) {
+      const newItem = onCreateProp?.(creatableClicked.label);
+      const realItems = newItems.filter((v): v is T => !isCreatableSentinel(v));
+      setSelectedItems(newItem ? [...realItems, newItem] : realItems);
+      skipNextInputChangeRef.current = true;
+      setInternalInputValue("");
+      onInputValueChange?.("");
+      return;
+    }
+    setSelectedItems(newItems as T[]);
   }
 
   function removeItem(item: T, e: React.MouseEvent) {
@@ -350,6 +413,10 @@ export function MultiCombobox<T extends DataWithId>(
       );
     }
 
+    if (isCreatableSentinel(row)) {
+      return renderCreatableItem(row);
+    }
+
     const item = row as T;
     return (
       <ComboboxItem
@@ -366,6 +433,33 @@ export function MultiCombobox<T extends DataWithId>(
     );
   }
 
+  function renderCreatableItem(
+    sentinel: CreatableSentinel,
+    style?: React.CSSProperties,
+    index?: number,
+    measureRef?: (el: Element | null) => void
+  ) {
+    return (
+      <ComboboxItem
+        key="__creatable"
+        value={sentinel}
+        itemId="__creatable"
+        label={`Create "${sentinel.label}"`}
+        inputType="none"
+        renderItem={() => (
+          <>
+            <Icon name="plus-outline" size="mini" />
+            {`Create "${sentinel.label}"`}
+          </>
+        )}
+        style={style}
+        index={index}
+        data-index={index}
+        ref={measureRef}
+      />
+    );
+  }
+
   // ─── Items passed to Combobox.Root ────────────────────────────────────────
   // When selectHeadings: flatItems (flat array of group header sentinels + items).
   // When selectAll only: prepend SELECT_ALL_SENTINEL to data so Base UI tracks
@@ -373,8 +467,12 @@ export function MultiCombobox<T extends DataWithId>(
   // The sentinel is never in flatItems — it is always rendered manually above
   // Combobox.List, so we must not prepend it when flatItems is used.
 
-  const rootItems =
+  const baseItems =
     flatItems ?? groups ?? (isChildrenMode ? undefined : visibleData);
+  const rootItems =
+    creatableSentinel && Array.isArray(baseItems)
+      ? ([...baseItems, creatableSentinel] as FlatRow[])
+      : baseItems;
 
   const hasSentinels = selectAll || selectHeadings;
 
@@ -395,9 +493,41 @@ export function MultiCombobox<T extends DataWithId>(
           if (!nextOpen && eventDetails.reason === "item-press") return;
           setOpen(nextOpen);
         }}
-        filter={filter}
-        inputValue={inputValue}
-        onInputValueChange={onInputValueChange}
+        filter={
+          creatableProp
+            ? (item: unknown, query: string) => {
+                if (isCreatableSentinel(item)) return true;
+                if (filter) return filter(item, query);
+                // Default Base UI filter: match against itemToStringLabel
+                if (isGroupHeaderSentinel(item) || isSelectAllSentinel(item))
+                  return true;
+                const label = itemToString(item as T);
+                return label.toLowerCase().includes(query.toLowerCase());
+              }
+            : filter
+        }
+        inputValue={
+          creatableProp ? currentInputValue : inputValue ?? internalInputValue
+        }
+        onInputValueChange={(v, eventDetails) => {
+          // Preserve search query when an item is selected. Base UI fires
+          // 'input-clear' on item-press; ignore it while the popup stays open.
+          if (eventDetails.reason === "input-clear" && open) return;
+
+          if (creatableProp) {
+            if (skipNextInputChangeRef.current) {
+              skipNextInputChangeRef.current = false;
+              return;
+            }
+            setInternalInputValue(v);
+            onInputValueChange?.(v);
+          } else {
+            if (inputValue === undefined) {
+              setInternalInputValue(v);
+            }
+            onInputValueChange?.(v);
+          }
+        }}
         onItemHighlighted={
           isVirtualized
             ? (item, { reason, index }) => {
@@ -423,20 +553,31 @@ export function MultiCombobox<T extends DataWithId>(
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           (hasSentinels ? handleValueChange : handleSimpleValueChange) as any
         }
-        itemToStringLabel={(item: FlatRow | null) => {
-          if (!item || isGroupHeaderSentinel(item) || isSelectAllSentinel(item))
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        itemToStringLabel={(item: any) => {
+          if (
+            !item ||
+            isGroupHeaderSentinel(item) ||
+            isSelectAllSentinel(item) ||
+            isCreatableSentinel(item)
+          )
             return "";
           return itemToString(item as T);
         }}
-        isItemEqualToValue={(a: FlatRow, b: FlatRow) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        isItemEqualToValue={(a: any, b: any) => {
+          if (isCreatableSentinel(a) && isCreatableSentinel(b))
+            return a.label === b.label;
           if (isGroupHeaderSentinel(a) && isGroupHeaderSentinel(b))
             return a.groupName === b.groupName;
           if (isSelectAllSentinel(a) && isSelectAllSentinel(b)) return true;
           if (
             !isGroupHeaderSentinel(a) &&
             !isSelectAllSentinel(a) &&
+            !isCreatableSentinel(a) &&
             !isGroupHeaderSentinel(b) &&
-            !isSelectAllSentinel(b)
+            !isSelectAllSentinel(b) &&
+            !isCreatableSentinel(b)
           )
             return (a as T).id === (b as T).id;
           return false;
@@ -475,6 +616,7 @@ export function MultiCombobox<T extends DataWithId>(
             <ComboboxTokenInput
               id={id}
               placeholder={value.length > 0 ? "" : placeholder}
+              aria-describedby={ariaDescribedBy}
             />
             <ComboboxActionButtons>
               <ComboboxClear aria-label="Clear all">
@@ -525,57 +667,83 @@ export function MultiCombobox<T extends DataWithId>(
                     inputType={inputType}
                     renderItem={renderItem}
                     renderGroupHeading={renderGroupHeading}
+                    renderCreatableItem={
+                      creatableProp
+                        ? (sentinel, style, index, measureRef) =>
+                            renderCreatableItem(
+                              sentinel,
+                              style,
+                              index,
+                              measureRef
+                            )
+                        : undefined
+                    }
                   />
                 ) : children ? (
                   children
                 ) : flatItems ? (
                   (row: FlatRow) => renderSentinelRow(row)
                 ) : groups ? (
-                  (group: { value: string; items: T[] }, index: number) => (
-                    <React.Fragment key={group.value}>
-                      <ComboboxGroup items={group.items}>
-                        <ComboboxGroupLabel>
-                          {renderGroupHeading
-                            ? renderGroupHeading(group.value)
-                            : group.value}
-                        </ComboboxGroupLabel>
-                        <Combobox.Collection>
-                          {(item: T) => (
-                            <ComboboxItem
-                              key={item.id}
-                              value={item}
-                              itemId={String(item.id)}
-                              label={itemToString(item)}
-                              disabled={item.disabled}
-                              inputType={inputType}
-                              renderItem={
-                                renderItem
-                                  ? () => renderItem(item)
-                                  : () => itemToString(item)
-                              }
-                            />
-                          )}
-                        </Combobox.Collection>
-                      </ComboboxGroup>
-                      {index < groups.length - 1 && <ComboboxSeparator />}
-                    </React.Fragment>
-                  )
+                  (
+                    group: { value: string; items: T[] } | CreatableSentinel,
+                    index: number
+                  ) => {
+                    if (isCreatableSentinel(group)) {
+                      return renderCreatableItem(group);
+                    }
+                    const g = group as { value: string; items: T[] };
+                    return (
+                      <React.Fragment key={g.value}>
+                        <ComboboxGroup items={g.items}>
+                          <ComboboxGroupLabel>
+                            {renderGroupHeading
+                              ? renderGroupHeading(g.value)
+                              : g.value}
+                          </ComboboxGroupLabel>
+                          <Combobox.Collection>
+                            {(item: T) => (
+                              <ComboboxItem
+                                key={item.id}
+                                value={item}
+                                itemId={String(item.id)}
+                                label={itemToString(item)}
+                                disabled={item.disabled}
+                                inputType={inputType}
+                                renderItem={
+                                  renderItem
+                                    ? () => renderItem(item)
+                                    : () => itemToString(item)
+                                }
+                              />
+                            )}
+                          </Combobox.Collection>
+                        </ComboboxGroup>
+                        {index < groups.length - 1 && <ComboboxSeparator />}
+                      </React.Fragment>
+                    );
+                  }
                 ) : (
-                  (item: T) => (
-                    <ComboboxItem
-                      key={item.id}
-                      value={item}
-                      itemId={String(item.id)}
-                      label={itemToString(item)}
-                      disabled={item.disabled}
-                      inputType={inputType}
-                      renderItem={
-                        renderItem
-                          ? () => renderItem(item)
-                          : () => itemToString(item)
-                      }
-                    />
-                  )
+                  (item: T | CreatableSentinel) => {
+                    if (isCreatableSentinel(item)) {
+                      return renderCreatableItem(item);
+                    }
+                    const dataItem = item as T;
+                    return (
+                      <ComboboxItem
+                        key={dataItem.id}
+                        value={dataItem}
+                        itemId={String(dataItem.id)}
+                        label={itemToString(dataItem)}
+                        disabled={dataItem.disabled}
+                        inputType={inputType}
+                        renderItem={
+                          renderItem
+                            ? () => renderItem(dataItem)
+                            : () => itemToString(dataItem)
+                        }
+                      />
+                    );
+                  }
                 )}
               </ComboboxList>
             </ComboboxPopup>