@arun-dev/headless 4.9.0 → 4.11.0

package/dist/combobox/index.cjs

@@ -32,12 +32,15 @@ __export(index_parts_exports, {
   ChipRemove: () => ComboboxChipRemove,
   Clear: () => ComboboxClear,
   Empty: () => ComboboxEmpty,
+  Group: () => ComboboxGroup,
+  GroupLabel: () => ComboboxGroupLabel,
   Input: () => ComboboxInput,
   InputGroup: () => ComboboxInputGroup,
   Item: () => ComboboxItem,
   List: () => ComboboxList,
   Popup: () => ComboboxPopup,
   Root: () => ComboboxRoot,
+  Separator: () => ComboboxSeparator,
   Status: () => ComboboxStatus,
   Trigger: () => ComboboxTrigger,
   Value: () => ComboboxValue
@@ -169,6 +172,11 @@ function useComboboxRootContext(part) {
 
 // src/combobox/ComboboxRoot.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
+function isGroupList(items) {
+  return items.length > 0 && items.every(
+    (entry) => entry !== null && typeof entry === "object" && Array.isArray(entry.items)
+  );
+}
 function defaultItemToString(item) {
   if (typeof item === "string") return item;
   if (item !== null && typeof item === "object" && "label" in item) return String(item.label);
@@ -193,6 +201,7 @@ function ComboboxRoot({
   onLoadMore,
   loading = false,
   disabled = false,
+  required = false,
   name,
   form,
   children
@@ -229,10 +238,17 @@ function ComboboxRoot({
   });
   const query = !multiple && inputValue === selectedLabel ? "" : inputValue;
   const deferredQuery = (0, import_react3.useDeferredValue)(query);
-  const filteredItems = (0, import_react3.useMemo)(() => {
-    if (filter === null) return items;
-    const run = filter ?? defaultFilter;
-    return run(items, deferredQuery, itemToString);
+  const { filteredItems, filteredGroups } = (0, import_react3.useMemo)(() => {
+    const run = filter === null ? (list) => list : (list) => (filter ?? defaultFilter)(
+      list,
+      deferredQuery,
+      itemToString
+    );
+    if (!isGroupList(items)) {
+      return { filteredItems: run(items), filteredGroups: null };
+    }
+    const groups = items.map((group) => ({ ...group, items: run(group.items) })).filter((group) => group.items.length > 0);
+    return { filteredItems: groups.flatMap((group) => group.items), filteredGroups: groups };
   }, [items, filter, deferredQuery, itemToString]);
   const indexByKey = (0, import_react3.useMemo)(
     () => new Map(filteredItems.map((item, index) => [itemToKey(item), index])),
@@ -326,7 +342,7 @@ function ComboboxRoot({
   (0, import_react3.useEffect)(() => {
     if (lastSelectedKeyRef.current === selectedKey) return;
     lastSelectedKeyRef.current = selectedKey;
-    setInputValueState(selectedLabel);
+    setInputValue(selectedLabel, "value-change");
   }, [selectedKey]);
   const [chips, setChips] = (0, import_react3.useState)([]);
   const registerChip = (0, import_react3.useCallback)((entry) => {
@@ -377,9 +393,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -413,9 +431,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -578,6 +598,7 @@ function ComboboxInput({ className, render, ...rest }) {
     open,
     multiple,
     disabled,
+    required,
     inputValue,
     filteredItems,
     itemToKey,
@@ -606,6 +627,20 @@ function ComboboxInput({ className, render, ...rest }) {
     () => highlight.get().index,
     () => -1
   );
+  const missing = required && selectedItems.length === 0;
+  const textOnly = missing && inputValue !== "";
+  const customValidityRef = (0, import_react5.useRef)(false);
+  (0, import_react5.useLayoutEffect)(() => {
+    const input = inputRef.current;
+    if (!input || typeof input.setCustomValidity !== "function") return;
+    if (textOnly) {
+      input.setCustomValidity(valueMissingMessage());
+      customValidityRef.current = true;
+    } else if (customValidityRef.current) {
+      input.setCustomValidity("");
+      customValidityRef.current = false;
+    }
+  }, [textOnly, inputRef]);
   function enabledIndices() {
     const indices = [];
     filteredItems.forEach((item, index) => {
@@ -643,6 +678,9 @@ function ComboboxInput({ className, render, ...rest }) {
       "aria-controls": listId,
       "aria-activedescendant": open && highlighted >= 0 ? optionId(highlighted) : void 0,
       disabled: disabled || void 0,
+      required: missing || void 0,
+      // Stays when a selection lifts `required`: the field is still required.
+      "aria-required": required || void 0,
       value: inputValue,
       ...comboboxDataAttributes({ open, multiple, disabled }),
       // The anchor, unless an InputGroup around it is.
@@ -712,6 +750,11 @@ function ComboboxInput({ className, render, ...rest }) {
     consumerProps: rest
   });
 }
+function valueMissingMessage() {
+  const probe = document.createElement("input");
+  probe.required = true;
+  return probe.validationMessage || "Please select an item in the list.";
+}
 
 // src/combobox/ComboboxInputGroup.tsx
 var import_react6 = require("react");
@@ -789,7 +832,8 @@ function ComboboxClear({ className, children, render, ...rest }) {
       type: "button",
       tabIndex: -1,
       disabled: disabled || void 0,
-      ...comboboxClearDataAttributes(selectedItems.length > 0),
+      // Nothing to clear while disabled: a disabled field hides it, as it has no effect.
+      ...comboboxClearDataAttributes(!disabled && selectedItems.length > 0),
       className,
       children,
       ref: elementRef,
@@ -872,8 +916,10 @@ function ComboboxList({
   render,
   ...rest
 }) {
-  const { multiple, loading, filteredItems, onLoadMore, listId } = useComboboxRootContext("List");
-  const content = typeof children === "function" ? filteredItems.map((item, index) => children(item, index)) : children;
+  const { multiple, loading, filteredItems, filteredGroups, onLoadMore, listId } = useComboboxRootContext("List");
+  const content = typeof children === "function" ? (filteredGroups ?? filteredItems).map(
+    (entry, index) => children(entry, index)
+  ) : children;
   return useRender({
     render,
     defaultTagName: "div",
@@ -909,10 +955,52 @@ function LoadMoreSentinel() {
 }
 
 // src/combobox/ComboboxItem.tsx
+var import_react12 = require("react");
+
+// src/combobox/ComboboxGroup.tsx
 var import_react11 = require("react");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var ComboboxGroupContext = (0, import_react11.createContext)(null);
+function useComboboxGroupContext() {
+  return (0, import_react11.useContext)(ComboboxGroupContext);
+}
+function ComboboxGroup({
+  disabled = false,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  useComboboxRootContext("Group");
+  const labelId = `${(0, import_react11.useId)()}-label`;
+  const [hasLabel, setHasLabel] = (0, import_react11.useState)(false);
+  const registerLabel = (0, import_react11.useCallback)(() => {
+    setHasLabel(true);
+    return () => setHasLabel(false);
+  }, []);
+  const context = (0, import_react11.useMemo)(
+    () => ({ disabled, labelId, registerLabel }),
+    [disabled, labelId, registerLabel]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: "group",
+      "aria-labelledby": hasLabel ? labelId : void 0,
+      "data-disabled": disabled ? "" : void 0,
+      className,
+      children
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ComboboxGroupContext.Provider, { value: context, children: element });
+}
+
+// src/combobox/ComboboxItem.tsx
 function ComboboxItem({
   value,
-  disabled = false,
+  disabled: disabledProp = false,
   className,
   children,
   render,
@@ -928,23 +1016,25 @@ function ComboboxItem({
     select,
     optionId
   } = useComboboxRootContext("Item");
+  const group = useComboboxGroupContext();
+  const disabled = disabledProp || (group?.disabled ?? false);
   const key = itemToKey(value);
   const index = indexByKey.get(key) ?? -1;
   const selected = selectedKeys.has(key);
-  const highlighted = (0, import_react11.useSyncExternalStore)(
+  const highlighted = (0, import_react12.useSyncExternalStore)(
     highlight.subscribe,
     () => index >= 0 && highlight.get().index === index,
     () => false
   );
-  const elementRef = (0, import_react11.useRef)(null);
-  (0, import_react11.useLayoutEffect)(() => {
+  const elementRef = (0, import_react12.useRef)(null);
+  (0, import_react12.useLayoutEffect)(() => {
     if (!disabled) return;
     disabledKeys.add(key);
     return () => {
       disabledKeys.delete(key);
     };
   }, [disabled, disabledKeys, key]);
-  (0, import_react11.useEffect)(() => {
+  (0, import_react12.useEffect)(() => {
     if (highlighted && highlight.get().reason === "keyboard") {
       elementRef.current?.scrollIntoView?.({ block: "nearest" });
     }
@@ -975,6 +1065,39 @@ function ComboboxItem({
   });
 }
 
+// src/combobox/ComboboxGroupLabel.tsx
+var import_react13 = require("react");
+function ComboboxGroupLabel({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const group = useComboboxGroupContext();
+  if (group === null) {
+    throw new Error("<Combobox.GroupLabel> must be rendered inside <Combobox.Group>.");
+  }
+  const { labelId, registerLabel } = group;
+  (0, import_react13.useLayoutEffect)(registerLabel, [registerLabel]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { id: labelId, className, children },
+    consumerProps: rest
+  });
+}
+
+// src/combobox/ComboboxSeparator.tsx
+function ComboboxSeparator({ className, render, ...rest }) {
+  useComboboxRootContext("Separator");
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { "aria-hidden": true, className },
+    consumerProps: rest
+  });
+}
+
 // src/combobox/ComboboxEmpty.tsx
 function ComboboxEmpty({ className, children, render, ...rest }) {
   const { filteredItems, loading } = useComboboxRootContext("Empty");
@@ -999,11 +1122,11 @@ function ComboboxStatus({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxChip.tsx
-var import_react12 = require("react");
-var import_jsx_runtime3 = require("react/jsx-runtime");
-var ComboboxChipContext = (0, import_react12.createContext)(null);
+var import_react14 = require("react");
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var ComboboxChipContext = (0, import_react14.createContext)(null);
 function useComboboxChipContext() {
-  const context = (0, import_react12.useContext)(ComboboxChipContext);
+  const context = (0, import_react14.useContext)(ComboboxChipContext);
   if (context === null) {
     throw new Error("<Combobox.ChipRemove> must be rendered inside <Combobox.Chip>.");
   }
@@ -1018,9 +1141,9 @@ function ComboboxChip({
 }) {
   const { disabled, itemToKey, remove, registerChip, chips, inputRef } = useComboboxRootContext("Chip");
   const key = itemToKey(value);
-  const elementRef = (0, import_react12.useRef)(null);
-  (0, import_react12.useLayoutEffect)(() => registerChip({ key, ref: elementRef }), [registerChip, key]);
-  const chipContext = (0, import_react12.useMemo)(() => ({ value }), [value]);
+  const elementRef = (0, import_react14.useRef)(null);
+  (0, import_react14.useLayoutEffect)(() => registerChip({ key, ref: elementRef }), [registerChip, key]);
+  const chipContext = (0, import_react14.useMemo)(() => ({ value }), [value]);
   function focusAt(index) {
     const chip = chips[index];
     if (chip) chip.ref.current?.focus();
@@ -1061,7 +1184,7 @@ function ComboboxChip({
     },
     consumerProps: rest
   });
-  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ComboboxChipContext.Provider, { value: chipContext, children: element });
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(ComboboxChipContext.Provider, { value: chipContext, children: element });
 }
 
 // src/combobox/ComboboxChipRemove.tsx
@@ -1096,11 +1219,11 @@ function ComboboxChipRemove({
 }
 
 // src/combobox/ComboboxValue.tsx
-var import_jsx_runtime4 = require("react/jsx-runtime");
+var import_jsx_runtime5 = require("react/jsx-runtime");
 function ComboboxValue({ children }) {
   const { multiple, selectedItems, itemToString } = useComboboxRootContext("Value");
   const value = multiple ? selectedItems : selectedItems[0] ?? null;
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_jsx_runtime4.Fragment, { children: children(value, { itemToString }) });
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: children(value, { itemToString }) });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/combobox/index.d.cts

@@ -3,7 +3,9 @@ import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
 import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.cjs';
 
 /** Why a value, the input's text or the open state changed — the second callback argument. */
-type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset';
+type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset'
+/** The input's text followed a change of `value` — the parent's, not the user's. */
+ | 'value-change';
 type ComboboxChangeDetails = {
     reason: ComboboxChangeReason;
 };
@@ -24,9 +26,20 @@ type ComboboxState = {
 type ComboboxValue$1<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
 /** Takes the whole list, so a filter can rank as well as narrow — a fuzzy search, say. */
 type ComboboxFilter<T> = (items: readonly T[], query: string, itemToString: (item: T) => string) => T[];
+/**
+ * Items under a label, as an `<optgroup>`: any object with an `items` array — the rest, a
+ * label or an id, is yours to render.
+ */
+type ComboboxGroup$1<T> = {
+    readonly items: readonly T[];
+};
 type ComboboxRootProps<T, Multiple extends boolean = false> = {
-    /** Every item the list can show. With server search, the current results. */
-    items: readonly T[];
+    /**
+     * Every item the list can show. With server search, the current results. Or groups of
+     * them: each an object with an `items` array, which the filter searches and `List` renders
+     * one by one, leaving out the groups with no match.
+     */
+    items: readonly T[] | readonly ComboboxGroup$1<T>[];
     /**
      * An item's label: what the input shows once it is picked, and what the default filter
      * matches. Defaults to the item itself for strings, else its `label` property.
@@ -78,6 +91,11 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
     loading?: boolean;
     /** Disables the input and every button. */
     disabled?: boolean;
+    /**
+     * Something must be selected before the form submits. The input is `required` while the
+     * selection is empty, so the browser's own validation reports it.
+     */
+    required?: boolean;
     /** Submits each selected item's key under this name, from hidden inputs. */
     name?: string;
     /** Associates the hidden inputs with a `<form>` by id, when rendered outside it. */
@@ -96,7 +114,7 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
  *
  * Focus stays in the input; the highlighted option is its `aria-activedescendant`.
  */
-declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
+declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, required, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
 
 type ComboboxInputOwnProps = {
     /** Element to render instead of the default `<input>`. Props and ref are merged onto it. */
@@ -114,6 +132,11 @@ type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'in
  * Enter picks the highlighted item; Esc closes. With `multiple`, Backspace in an empty input
  * removes the last selected item, and Left at the start of the text moves into the chips.
  *
+ * With the Root's `required`, the input is `required` while nothing is selected, so the
+ * browser's validation reports it, `:invalid` matches it, and `form.checkValidity()` fails.
+ * Text typed but not picked is still nothing selected: the input reports `valueMissing`'s
+ * message then, through `setCustomValidity`.
+ *
  * Leaving the input closes the list and puts the text back: the selected label, or empty
  * with `multiple`.
  */
@@ -161,7 +184,8 @@ type ComboboxClearProps = ComboboxClearOwnProps & Omit<ComponentPropsWithRef<'bu
  * Empties the input and the selection — every selected item, with `multiple`. Give it an
  * `aria-label`.
  *
- * `data-visible` is present while there is a selection to clear; style it hidden otherwise.
+ * `data-visible` is present while there is a selection to clear and the Root is not disabled;
+ * style it hidden otherwise.
  * Out of the tab order, and a press keeps focus in the input.
  */
 declare function ComboboxClear({ className, children, render, ...rest }: ComboboxClearProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
@@ -194,7 +218,8 @@ declare function ComboboxPopup({ side, align, className, children, render, ...re
 type ComboboxListOwnProps<T> = {
     /**
      * A function rendering one `Combobox.Item` per filtered item, or any nodes. With a
-     * virtualizer, render only the rows it asks for.
+     * virtualizer, render only the rows it asks for. With groups, it is called once per group
+     * the filter left an item in, with that group, and renders a `Combobox.Group`.
      */
     children?: ReactNode | ((item: T, index: number) => ReactNode);
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -204,7 +229,8 @@ type ComboboxListOwnProps<T> = {
 };
 type ComboboxListProps<T = unknown> = ComboboxListOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxListOwnProps<T>>;
 /**
- * The `role="listbox"`. Given a function, renders it once per item the filter left.
+ * The `role="listbox"`. Given a function, renders it once per item the filter left — or, when
+ * the Root's `items` are groups, once per group.
  *
  * With the Root's `onLoadMore`, an invisible sentinel follows the items; when it scrolls into
  * view and nothing is `loading`, `onLoadMore` is called. The list is `aria-busy` meanwhile.
@@ -214,7 +240,7 @@ declare function ComboboxList<T = unknown>({ className, children, render, ...res
 type ComboboxItemOwnProps<T> = {
     /** The item this option stands for — one of the Root's `items`. */
     value: T;
-    /** Cannot be picked, and the arrow keys skip it. */
+    /** Cannot be picked, and the arrow keys skip it. A disabled Group disables it too. */
     disabled?: boolean;
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
     render?: ReactElement;
@@ -229,7 +255,55 @@ type ComboboxItemProps<T = unknown> = ComboboxItemOwnProps<T> & Omit<ComponentPr
  * `data-selected` and `aria-selected` follow the Root's `value`; `data-highlighted` follows
  * the arrow keys and the pointer. Only the items whose highlight changes re-render.
  */
-declare function ComboboxItem<T = unknown>({ value, disabled, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function ComboboxItem<T = unknown>({ value, disabled: disabledProp, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxGroupOwnProps = {
+    /** Disables every Item inside, as `disabled` on an `<optgroup>` does. */
+    disabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxGroupProps = ComboboxGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxGroupOwnProps>;
+/**
+ * Items under a label, as an `<optgroup>`: `role="group"`, named by its GroupLabel. Render one
+ * from the List's function for each group of the Root's `items`, with an Item for each of the
+ * group's `items` — the filter has already narrowed them, and left out a group with none.
+ *
+ * The arrow keys run through every group's items as one list, past the labels.
+ */
+declare function ComboboxGroup({ disabled, className, children, render, ...rest }: ComboboxGroupProps): react.JSX.Element;
+
+type ComboboxGroupLabelOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxGroupLabelProps = ComboboxGroupLabelOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxGroupLabelOwnProps>;
+/**
+ * Names its Group, as an `<optgroup>`'s `label` does. Shown in the list, but not an option:
+ * it cannot be picked, and the arrow keys pass it.
+ */
+declare function ComboboxGroupLabel({ className, children, render, ...rest }: ComboboxGroupLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxSeparatorOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxSeparatorProps = ComboboxSeparatorOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxSeparatorOwnProps>;
+/**
+ * A line between items or groups in the List, as an `<hr>` in a `<select>`. The arrow keys pass
+ * it.
+ *
+ * Visual only: `aria-hidden`, with no `role="separator"`. A listbox may own only options and
+ * groups, so a separator role inside one fails `aria-required-children`; a Group, named by its
+ * label, is what tells a screen reader where one set ends.
+ */
+declare function ComboboxSeparator({ className, render, ...rest }: ComboboxSeparatorProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type ComboboxEmptyOwnProps = {
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -308,7 +382,7 @@ type ComboboxValueProps<T = unknown> = {
 declare function ComboboxValue<T = unknown>({ children }: ComboboxValueProps<T>): react.JSX.Element;
 
 declare namespace index_parts {
-  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
+  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxGroup as Group, ComboboxGroupLabel as GroupLabel, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxSeparator as Separator, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
 }
 
 /**
@@ -319,4 +393,4 @@ declare namespace index_parts {
  */
 declare function defaultFilter<T>(items: readonly T[], query: string, itemToString: (item: T) => string): T[];
 
-export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };
+export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxGroup$1 as ComboboxGroup, type ComboboxGroupLabelProps, type ComboboxGroupProps, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSeparatorProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };

package/dist/combobox/index.d.ts

@@ -3,7 +3,9 @@ import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
 import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.js';
 
 /** Why a value, the input's text or the open state changed — the second callback argument. */
-type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset';
+type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset'
+/** The input's text followed a change of `value` — the parent's, not the user's. */
+ | 'value-change';
 type ComboboxChangeDetails = {
     reason: ComboboxChangeReason;
 };
@@ -24,9 +26,20 @@ type ComboboxState = {
 type ComboboxValue$1<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
 /** Takes the whole list, so a filter can rank as well as narrow — a fuzzy search, say. */
 type ComboboxFilter<T> = (items: readonly T[], query: string, itemToString: (item: T) => string) => T[];
+/**
+ * Items under a label, as an `<optgroup>`: any object with an `items` array — the rest, a
+ * label or an id, is yours to render.
+ */
+type ComboboxGroup$1<T> = {
+    readonly items: readonly T[];
+};
 type ComboboxRootProps<T, Multiple extends boolean = false> = {
-    /** Every item the list can show. With server search, the current results. */
-    items: readonly T[];
+    /**
+     * Every item the list can show. With server search, the current results. Or groups of
+     * them: each an object with an `items` array, which the filter searches and `List` renders
+     * one by one, leaving out the groups with no match.
+     */
+    items: readonly T[] | readonly ComboboxGroup$1<T>[];
     /**
      * An item's label: what the input shows once it is picked, and what the default filter
      * matches. Defaults to the item itself for strings, else its `label` property.
@@ -78,6 +91,11 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
     loading?: boolean;
     /** Disables the input and every button. */
     disabled?: boolean;
+    /**
+     * Something must be selected before the form submits. The input is `required` while the
+     * selection is empty, so the browser's own validation reports it.
+     */
+    required?: boolean;
     /** Submits each selected item's key under this name, from hidden inputs. */
     name?: string;
     /** Associates the hidden inputs with a `<form>` by id, when rendered outside it. */
@@ -96,7 +114,7 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
  *
  * Focus stays in the input; the highlighted option is its `aria-activedescendant`.
  */
-declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
+declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, required, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
 
 type ComboboxInputOwnProps = {
     /** Element to render instead of the default `<input>`. Props and ref are merged onto it. */
@@ -114,6 +132,11 @@ type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'in
  * Enter picks the highlighted item; Esc closes. With `multiple`, Backspace in an empty input
  * removes the last selected item, and Left at the start of the text moves into the chips.
  *
+ * With the Root's `required`, the input is `required` while nothing is selected, so the
+ * browser's validation reports it, `:invalid` matches it, and `form.checkValidity()` fails.
+ * Text typed but not picked is still nothing selected: the input reports `valueMissing`'s
+ * message then, through `setCustomValidity`.
+ *
  * Leaving the input closes the list and puts the text back: the selected label, or empty
  * with `multiple`.
  */
@@ -161,7 +184,8 @@ type ComboboxClearProps = ComboboxClearOwnProps & Omit<ComponentPropsWithRef<'bu
  * Empties the input and the selection — every selected item, with `multiple`. Give it an
  * `aria-label`.
  *
- * `data-visible` is present while there is a selection to clear; style it hidden otherwise.
+ * `data-visible` is present while there is a selection to clear and the Root is not disabled;
+ * style it hidden otherwise.
  * Out of the tab order, and a press keeps focus in the input.
  */
 declare function ComboboxClear({ className, children, render, ...rest }: ComboboxClearProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
@@ -194,7 +218,8 @@ declare function ComboboxPopup({ side, align, className, children, render, ...re
 type ComboboxListOwnProps<T> = {
     /**
      * A function rendering one `Combobox.Item` per filtered item, or any nodes. With a
-     * virtualizer, render only the rows it asks for.
+     * virtualizer, render only the rows it asks for. With groups, it is called once per group
+     * the filter left an item in, with that group, and renders a `Combobox.Group`.
      */
     children?: ReactNode | ((item: T, index: number) => ReactNode);
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -204,7 +229,8 @@ type ComboboxListOwnProps<T> = {
 };
 type ComboboxListProps<T = unknown> = ComboboxListOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxListOwnProps<T>>;
 /**
- * The `role="listbox"`. Given a function, renders it once per item the filter left.
+ * The `role="listbox"`. Given a function, renders it once per item the filter left — or, when
+ * the Root's `items` are groups, once per group.
  *
  * With the Root's `onLoadMore`, an invisible sentinel follows the items; when it scrolls into
  * view and nothing is `loading`, `onLoadMore` is called. The list is `aria-busy` meanwhile.
@@ -214,7 +240,7 @@ declare function ComboboxList<T = unknown>({ className, children, render, ...res
 type ComboboxItemOwnProps<T> = {
     /** The item this option stands for — one of the Root's `items`. */
     value: T;
-    /** Cannot be picked, and the arrow keys skip it. */
+    /** Cannot be picked, and the arrow keys skip it. A disabled Group disables it too. */
     disabled?: boolean;
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
     render?: ReactElement;
@@ -229,7 +255,55 @@ type ComboboxItemProps<T = unknown> = ComboboxItemOwnProps<T> & Omit<ComponentPr
  * `data-selected` and `aria-selected` follow the Root's `value`; `data-highlighted` follows
  * the arrow keys and the pointer. Only the items whose highlight changes re-render.
  */
-declare function ComboboxItem<T = unknown>({ value, disabled, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function ComboboxItem<T = unknown>({ value, disabled: disabledProp, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxGroupOwnProps = {
+    /** Disables every Item inside, as `disabled` on an `<optgroup>` does. */
+    disabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxGroupProps = ComboboxGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxGroupOwnProps>;
+/**
+ * Items under a label, as an `<optgroup>`: `role="group"`, named by its GroupLabel. Render one
+ * from the List's function for each group of the Root's `items`, with an Item for each of the
+ * group's `items` — the filter has already narrowed them, and left out a group with none.
+ *
+ * The arrow keys run through every group's items as one list, past the labels.
+ */
+declare function ComboboxGroup({ disabled, className, children, render, ...rest }: ComboboxGroupProps): react.JSX.Element;
+
+type ComboboxGroupLabelOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxGroupLabelProps = ComboboxGroupLabelOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxGroupLabelOwnProps>;
+/**
+ * Names its Group, as an `<optgroup>`'s `label` does. Shown in the list, but not an option:
+ * it cannot be picked, and the arrow keys pass it.
+ */
+declare function ComboboxGroupLabel({ className, children, render, ...rest }: ComboboxGroupLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxSeparatorOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxSeparatorProps = ComboboxSeparatorOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxSeparatorOwnProps>;
+/**
+ * A line between items or groups in the List, as an `<hr>` in a `<select>`. The arrow keys pass
+ * it.
+ *
+ * Visual only: `aria-hidden`, with no `role="separator"`. A listbox may own only options and
+ * groups, so a separator role inside one fails `aria-required-children`; a Group, named by its
+ * label, is what tells a screen reader where one set ends.
+ */
+declare function ComboboxSeparator({ className, render, ...rest }: ComboboxSeparatorProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type ComboboxEmptyOwnProps = {
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -308,7 +382,7 @@ type ComboboxValueProps<T = unknown> = {
 declare function ComboboxValue<T = unknown>({ children }: ComboboxValueProps<T>): react.JSX.Element;
 
 declare namespace index_parts {
-  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
+  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxGroup as Group, ComboboxGroupLabel as GroupLabel, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxSeparator as Separator, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
 }
 
 /**
@@ -319,4 +393,4 @@ declare namespace index_parts {
  */
 declare function defaultFilter<T>(items: readonly T[], query: string, itemToString: (item: T) => string): T[];
 
-export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };
+export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxGroup$1 as ComboboxGroup, type ComboboxGroupLabelProps, type ComboboxGroupProps, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSeparatorProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };

package/dist/combobox/index.js

@@ -22,12 +22,15 @@ __export(index_parts_exports, {
   ChipRemove: () => ComboboxChipRemove,
   Clear: () => ComboboxClear,
   Empty: () => ComboboxEmpty,
+  Group: () => ComboboxGroup,
+  GroupLabel: () => ComboboxGroupLabel,
   Input: () => ComboboxInput,
   InputGroup: () => ComboboxInputGroup,
   Item: () => ComboboxItem,
   List: () => ComboboxList,
   Popup: () => ComboboxPopup,
   Root: () => ComboboxRoot,
+  Separator: () => ComboboxSeparator,
   Status: () => ComboboxStatus,
   Trigger: () => ComboboxTrigger,
   Value: () => ComboboxValue
@@ -75,6 +78,11 @@ function useComboboxRootContext(part) {
 
 // src/combobox/ComboboxRoot.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
+function isGroupList(items) {
+  return items.length > 0 && items.every(
+    (entry) => entry !== null && typeof entry === "object" && Array.isArray(entry.items)
+  );
+}
 function defaultItemToString(item) {
   if (typeof item === "string") return item;
   if (item !== null && typeof item === "object" && "label" in item) return String(item.label);
@@ -99,6 +107,7 @@ function ComboboxRoot({
   onLoadMore,
   loading = false,
   disabled = false,
+  required = false,
   name,
   form,
   children
@@ -135,10 +144,17 @@ function ComboboxRoot({
   });
   const query = !multiple && inputValue === selectedLabel ? "" : inputValue;
   const deferredQuery = useDeferredValue(query);
-  const filteredItems = useMemo(() => {
-    if (filter === null) return items;
-    const run = filter ?? defaultFilter;
-    return run(items, deferredQuery, itemToString);
+  const { filteredItems, filteredGroups } = useMemo(() => {
+    const run = filter === null ? (list) => list : (list) => (filter ?? defaultFilter)(
+      list,
+      deferredQuery,
+      itemToString
+    );
+    if (!isGroupList(items)) {
+      return { filteredItems: run(items), filteredGroups: null };
+    }
+    const groups = items.map((group) => ({ ...group, items: run(group.items) })).filter((group) => group.items.length > 0);
+    return { filteredItems: groups.flatMap((group) => group.items), filteredGroups: groups };
   }, [items, filter, deferredQuery, itemToString]);
   const indexByKey = useMemo(
     () => new Map(filteredItems.map((item, index) => [itemToKey(item), index])),
@@ -232,7 +248,7 @@ function ComboboxRoot({
   useEffect(() => {
     if (lastSelectedKeyRef.current === selectedKey) return;
     lastSelectedKeyRef.current = selectedKey;
-    setInputValueState(selectedLabel);
+    setInputValue(selectedLabel, "value-change");
   }, [selectedKey]);
   const [chips, setChips] = useState([]);
   const registerChip = useCallback((entry) => {
@@ -283,9 +299,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -319,9 +337,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -364,7 +384,7 @@ function ComboboxRoot({
 }
 
 // src/combobox/ComboboxInput.tsx
-import { useSyncExternalStore } from "react";
+import { useLayoutEffect, useRef as useRef2, useSyncExternalStore } from "react";
 
 // src/combobox/comboboxDataAttributes.ts
 function comboboxDataAttributes({ open, disabled }) {
@@ -395,6 +415,7 @@ function ComboboxInput({ className, render, ...rest }) {
     open,
     multiple,
     disabled,
+    required,
     inputValue,
     filteredItems,
     itemToKey,
@@ -423,6 +444,20 @@ function ComboboxInput({ className, render, ...rest }) {
     () => highlight.get().index,
     () => -1
   );
+  const missing = required && selectedItems.length === 0;
+  const textOnly = missing && inputValue !== "";
+  const customValidityRef = useRef2(false);
+  useLayoutEffect(() => {
+    const input = inputRef.current;
+    if (!input || typeof input.setCustomValidity !== "function") return;
+    if (textOnly) {
+      input.setCustomValidity(valueMissingMessage());
+      customValidityRef.current = true;
+    } else if (customValidityRef.current) {
+      input.setCustomValidity("");
+      customValidityRef.current = false;
+    }
+  }, [textOnly, inputRef]);
   function enabledIndices() {
     const indices = [];
     filteredItems.forEach((item, index) => {
@@ -460,6 +495,9 @@ function ComboboxInput({ className, render, ...rest }) {
       "aria-controls": listId,
       "aria-activedescendant": open && highlighted >= 0 ? optionId(highlighted) : void 0,
       disabled: disabled || void 0,
+      required: missing || void 0,
+      // Stays when a selection lifts `required`: the field is still required.
+      "aria-required": required || void 0,
       value: inputValue,
       ...comboboxDataAttributes({ open, multiple, disabled }),
       // The anchor, unless an InputGroup around it is.
@@ -529,9 +567,14 @@ function ComboboxInput({ className, render, ...rest }) {
     consumerProps: rest
   });
 }
+function valueMissingMessage() {
+  const probe = document.createElement("input");
+  probe.required = true;
+  return probe.validationMessage || "Please select an item in the list.";
+}
 
 // src/combobox/ComboboxInputGroup.tsx
-import { useLayoutEffect, useRef as useRef2 } from "react";
+import { useLayoutEffect as useLayoutEffect2, useRef as useRef3 } from "react";
 function ComboboxInputGroup({
   className,
   children,
@@ -539,9 +582,9 @@ function ComboboxInputGroup({
   ...rest
 }) {
   const { open, multiple, disabled, anchorName, registerGroup, registerInside, inputRef } = useComboboxRootContext("InputGroup");
-  const elementRef = useRef2(null);
-  useLayoutEffect(() => registerGroup(), [registerGroup]);
-  useLayoutEffect(() => registerInside(elementRef), [registerInside]);
+  const elementRef = useRef3(null);
+  useLayoutEffect2(() => registerGroup(), [registerGroup]);
+  useLayoutEffect2(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "div",
@@ -562,11 +605,11 @@ function ComboboxInputGroup({
 }
 
 // src/combobox/ComboboxTrigger.tsx
-import { useLayoutEffect as useLayoutEffect2, useRef as useRef3 } from "react";
+import { useLayoutEffect as useLayoutEffect3, useRef as useRef4 } from "react";
 function ComboboxTrigger({ className, children, render, ...rest }) {
   const { open, multiple, disabled, setOpen, close, listId, inputRef, registerInside } = useComboboxRootContext("Trigger");
-  const elementRef = useRef3(null);
-  useLayoutEffect2(() => registerInside(elementRef), [registerInside]);
+  const elementRef = useRef4(null);
+  useLayoutEffect3(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -594,11 +637,11 @@ function ComboboxTrigger({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxClear.tsx
-import { useLayoutEffect as useLayoutEffect3, useRef as useRef4 } from "react";
+import { useLayoutEffect as useLayoutEffect4, useRef as useRef5 } from "react";
 function ComboboxClear({ className, children, render, ...rest }) {
   const { disabled, selectedItems, clear, inputRef, registerInside } = useComboboxRootContext("Clear");
-  const elementRef = useRef4(null);
-  useLayoutEffect3(() => registerInside(elementRef), [registerInside]);
+  const elementRef = useRef5(null);
+  useLayoutEffect4(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -606,7 +649,8 @@ function ComboboxClear({ className, children, render, ...rest }) {
       type: "button",
       tabIndex: -1,
       disabled: disabled || void 0,
-      ...comboboxClearDataAttributes(selectedItems.length > 0),
+      // Nothing to clear while disabled: a disabled field hides it, as it has no effect.
+      ...comboboxClearDataAttributes(!disabled && selectedItems.length > 0),
       className,
       children,
       ref: elementRef,
@@ -681,7 +725,7 @@ function ComboboxPopup({
 }
 
 // src/combobox/ComboboxList.tsx
-import { useEffect as useEffect3, useRef as useRef5 } from "react";
+import { useEffect as useEffect3, useRef as useRef6 } from "react";
 import { Fragment, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function ComboboxList({
   className,
@@ -689,8 +733,10 @@ function ComboboxList({
   render,
   ...rest
 }) {
-  const { multiple, loading, filteredItems, onLoadMore, listId } = useComboboxRootContext("List");
-  const content = typeof children === "function" ? filteredItems.map((item, index) => children(item, index)) : children;
+  const { multiple, loading, filteredItems, filteredGroups, onLoadMore, listId } = useComboboxRootContext("List");
+  const content = typeof children === "function" ? (filteredGroups ?? filteredItems).map(
+    (entry, index) => children(entry, index)
+  ) : children;
   return useRender({
     render,
     defaultTagName: "div",
@@ -710,8 +756,8 @@ function ComboboxList({
 }
 function LoadMoreSentinel() {
   const { open, loading, filteredItems, onLoadMore } = useComboboxRootContext("List");
-  const ref = useRef5(null);
-  const onLoadMoreRef = useRef5(onLoadMore);
+  const ref = useRef6(null);
+  const onLoadMoreRef = useRef6(onLoadMore);
   onLoadMoreRef.current = onLoadMore;
   useEffect3(() => {
     const element = ref.current;
@@ -726,10 +772,52 @@ function LoadMoreSentinel() {
 }
 
 // src/combobox/ComboboxItem.tsx
-import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect4, useRef as useRef6, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect5, useRef as useRef7, useSyncExternalStore as useSyncExternalStore2 } from "react";
+
+// src/combobox/ComboboxGroup.tsx
+import { createContext as createContext2, useCallback as useCallback2, useContext as useContext2, useId as useId2, useMemo as useMemo2, useState as useState2 } from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var ComboboxGroupContext = createContext2(null);
+function useComboboxGroupContext() {
+  return useContext2(ComboboxGroupContext);
+}
+function ComboboxGroup({
+  disabled = false,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  useComboboxRootContext("Group");
+  const labelId = `${useId2()}-label`;
+  const [hasLabel, setHasLabel] = useState2(false);
+  const registerLabel = useCallback2(() => {
+    setHasLabel(true);
+    return () => setHasLabel(false);
+  }, []);
+  const context = useMemo2(
+    () => ({ disabled, labelId, registerLabel }),
+    [disabled, labelId, registerLabel]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: "group",
+      "aria-labelledby": hasLabel ? labelId : void 0,
+      "data-disabled": disabled ? "" : void 0,
+      className,
+      children
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsx3(ComboboxGroupContext.Provider, { value: context, children: element });
+}
+
+// src/combobox/ComboboxItem.tsx
 function ComboboxItem({
   value,
-  disabled = false,
+  disabled: disabledProp = false,
   className,
   children,
   render,
@@ -745,6 +833,8 @@ function ComboboxItem({
     select,
     optionId
   } = useComboboxRootContext("Item");
+  const group = useComboboxGroupContext();
+  const disabled = disabledProp || (group?.disabled ?? false);
   const key = itemToKey(value);
   const index = indexByKey.get(key) ?? -1;
   const selected = selectedKeys.has(key);
@@ -753,8 +843,8 @@ function ComboboxItem({
     () => index >= 0 && highlight.get().index === index,
     () => false
   );
-  const elementRef = useRef6(null);
-  useLayoutEffect4(() => {
+  const elementRef = useRef7(null);
+  useLayoutEffect5(() => {
     if (!disabled) return;
     disabledKeys.add(key);
     return () => {
@@ -792,6 +882,39 @@ function ComboboxItem({
   });
 }
 
+// src/combobox/ComboboxGroupLabel.tsx
+import { useLayoutEffect as useLayoutEffect6 } from "react";
+function ComboboxGroupLabel({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const group = useComboboxGroupContext();
+  if (group === null) {
+    throw new Error("<Combobox.GroupLabel> must be rendered inside <Combobox.Group>.");
+  }
+  const { labelId, registerLabel } = group;
+  useLayoutEffect6(registerLabel, [registerLabel]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { id: labelId, className, children },
+    consumerProps: rest
+  });
+}
+
+// src/combobox/ComboboxSeparator.tsx
+function ComboboxSeparator({ className, render, ...rest }) {
+  useComboboxRootContext("Separator");
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { "aria-hidden": true, className },
+    consumerProps: rest
+  });
+}
+
 // src/combobox/ComboboxEmpty.tsx
 function ComboboxEmpty({ className, children, render, ...rest }) {
   const { filteredItems, loading } = useComboboxRootContext("Empty");
@@ -816,11 +939,11 @@ function ComboboxStatus({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxChip.tsx
-import { createContext as createContext2, useContext as useContext2, useLayoutEffect as useLayoutEffect5, useMemo as useMemo2, useRef as useRef7 } from "react";
-import { jsx as jsx3 } from "react/jsx-runtime";
-var ComboboxChipContext = createContext2(null);
+import { createContext as createContext3, useContext as useContext3, useLayoutEffect as useLayoutEffect7, useMemo as useMemo3, useRef as useRef8 } from "react";
+import { jsx as jsx4 } from "react/jsx-runtime";
+var ComboboxChipContext = createContext3(null);
 function useComboboxChipContext() {
-  const context = useContext2(ComboboxChipContext);
+  const context = useContext3(ComboboxChipContext);
   if (context === null) {
     throw new Error("<Combobox.ChipRemove> must be rendered inside <Combobox.Chip>.");
   }
@@ -835,9 +958,9 @@ function ComboboxChip({
 }) {
   const { disabled, itemToKey, remove, registerChip, chips, inputRef } = useComboboxRootContext("Chip");
   const key = itemToKey(value);
-  const elementRef = useRef7(null);
-  useLayoutEffect5(() => registerChip({ key, ref: elementRef }), [registerChip, key]);
-  const chipContext = useMemo2(() => ({ value }), [value]);
+  const elementRef = useRef8(null);
+  useLayoutEffect7(() => registerChip({ key, ref: elementRef }), [registerChip, key]);
+  const chipContext = useMemo3(() => ({ value }), [value]);
   function focusAt(index) {
     const chip = chips[index];
     if (chip) chip.ref.current?.focus();
@@ -878,7 +1001,7 @@ function ComboboxChip({
     },
     consumerProps: rest
   });
-  return /* @__PURE__ */ jsx3(ComboboxChipContext.Provider, { value: chipContext, children: element });
+  return /* @__PURE__ */ jsx4(ComboboxChipContext.Provider, { value: chipContext, children: element });
 }
 
 // src/combobox/ComboboxChipRemove.tsx
@@ -913,11 +1036,11 @@ function ComboboxChipRemove({
 }
 
 // src/combobox/ComboboxValue.tsx
-import { Fragment as Fragment2, jsx as jsx4 } from "react/jsx-runtime";
+import { Fragment as Fragment2, jsx as jsx5 } from "react/jsx-runtime";
 function ComboboxValue({ children }) {
   const { multiple, selectedItems, itemToString } = useComboboxRootContext("Value");
   const value = multiple ? selectedItems : selectedItems[0] ?? null;
-  return /* @__PURE__ */ jsx4(Fragment2, { children: children(value, { itemToString }) });
+  return /* @__PURE__ */ jsx5(Fragment2, { children: children(value, { itemToString }) });
 }
 export {
   index_parts_exports as Combobox,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",