@arun-dev/headless 4.8.0 → 4.10.0

package/dist/combobox/index.cjs

@@ -32,13 +32,17 @@ __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,
   Status: () => ComboboxStatus,
-  Trigger: () => ComboboxTrigger
+  Trigger: () => ComboboxTrigger,
+  Value: () => ComboboxValue
 });
 
 // src/combobox/ComboboxRoot.tsx
@@ -167,6 +171,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);
@@ -191,6 +200,7 @@ function ComboboxRoot({
   onLoadMore,
   loading = false,
   disabled = false,
+  required = false,
   name,
   form,
   children
@@ -227,10 +237,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])),
@@ -342,6 +359,11 @@ function ComboboxRoot({
     },
     [insideRefs]
   );
+  const [hasGroup, setHasGroup] = (0, import_react3.useState)(false);
+  const registerGroup = (0, import_react3.useCallback)(() => {
+    setHasGroup(true);
+    return () => setHasGroup(false);
+  }, []);
   const inputRef = (0, import_react3.useRef)(null);
   const popupRef = (0, import_react3.useRef)(null);
   const { current: initial } = (0, import_react3.useRef)({ value, inputValue });
@@ -370,9 +392,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -392,6 +416,8 @@ function ComboboxRoot({
       chips,
       registerInside,
       isInside,
+      hasGroup,
+      registerGroup,
       onLoadMore,
       inputId: `${id}-input`,
       listId: `${id}-list`,
@@ -404,9 +430,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -426,6 +454,8 @@ function ComboboxRoot({
       chips,
       registerInside,
       isInside,
+      hasGroup,
+      registerGroup,
       onLoadMore,
       id
     ]
@@ -567,6 +597,7 @@ function ComboboxInput({ className, render, ...rest }) {
     open,
     multiple,
     disabled,
+    required,
     inputValue,
     filteredItems,
     itemToKey,
@@ -586,6 +617,7 @@ function ComboboxInput({ className, render, ...rest }) {
     listId,
     optionId,
     anchorName,
+    hasGroup,
     inputRef,
     popupRef
   } = useComboboxRootContext("Input");
@@ -594,6 +626,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) => {
@@ -631,9 +677,13 @@ 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 }),
-      style: { anchorName },
+      // The anchor, unless an InputGroup around it is.
+      style: hasGroup ? void 0 : { anchorName },
       className,
       ref: inputRef,
       onChange(event) {
@@ -699,13 +749,49 @@ 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/ComboboxTrigger.tsx
+// src/combobox/ComboboxInputGroup.tsx
 var import_react6 = require("react");
-function ComboboxTrigger({ className, children, render, ...rest }) {
-  const { open, multiple, disabled, setOpen, close, listId, inputRef, registerInside } = useComboboxRootContext("Trigger");
+function ComboboxInputGroup({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const { open, multiple, disabled, anchorName, registerGroup, registerInside, inputRef } = useComboboxRootContext("InputGroup");
   const elementRef = (0, import_react6.useRef)(null);
+  (0, import_react6.useLayoutEffect)(() => registerGroup(), [registerGroup]);
   (0, import_react6.useLayoutEffect)(() => registerInside(elementRef), [registerInside]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      ...comboboxDataAttributes({ open, multiple, disabled }),
+      style: { anchorName },
+      className,
+      children,
+      ref: elementRef,
+      onMouseDown(event) {
+        if (event.target !== event.currentTarget || disabled) return;
+        event.preventDefault();
+        inputRef.current?.focus();
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/combobox/ComboboxTrigger.tsx
+var import_react7 = require("react");
+function ComboboxTrigger({ className, children, render, ...rest }) {
+  const { open, multiple, disabled, setOpen, close, listId, inputRef, registerInside } = useComboboxRootContext("Trigger");
+  const elementRef = (0, import_react7.useRef)(null);
+  (0, import_react7.useLayoutEffect)(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -733,11 +819,11 @@ function ComboboxTrigger({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxClear.tsx
-var import_react7 = require("react");
+var import_react8 = require("react");
 function ComboboxClear({ className, children, render, ...rest }) {
   const { disabled, selectedItems, clear, inputRef, registerInside } = useComboboxRootContext("Clear");
-  const elementRef = (0, import_react7.useRef)(null);
-  (0, import_react7.useLayoutEffect)(() => registerInside(elementRef), [registerInside]);
+  const elementRef = (0, import_react8.useRef)(null);
+  (0, import_react8.useLayoutEffect)(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -763,7 +849,7 @@ function ComboboxClear({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxPopup.tsx
-var import_react8 = require("react");
+var import_react9 = require("react");
 function ComboboxPopup({
   side = "bottom",
   align = "start",
@@ -773,7 +859,7 @@ function ComboboxPopup({
   ...rest
 }) {
   const { open, multiple, disabled, setOpen, close, isInside, anchorName, inputRef, popupRef } = useComboboxRootContext("Popup");
-  (0, import_react8.useEffect)(() => {
+  (0, import_react9.useEffect)(() => {
     if (!open) return;
     function onPointerDown(event) {
       if (event.target instanceof Node && isInside(event.target)) return;
@@ -782,8 +868,8 @@ function ComboboxPopup({
     document.addEventListener("pointerdown", onPointerDown, true);
     return () => document.removeEventListener("pointerdown", onPointerDown, true);
   }, [open, isInside, close]);
-  const [, resync] = (0, import_react8.useReducer)((n) => n + 1, 0);
-  (0, import_react8.useEffect)(() => {
+  const [, resync] = (0, import_react9.useReducer)((n) => n + 1, 0);
+  (0, import_react9.useEffect)(() => {
     const popup = popupRef.current;
     if (!popup || typeof popup.showPopover !== "function") return;
     const shown = popup.matches(":popover-open");
@@ -820,7 +906,7 @@ function ComboboxPopup({
 }
 
 // src/combobox/ComboboxList.tsx
-var import_react9 = require("react");
+var import_react10 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
 function ComboboxList({
   className,
@@ -828,8 +914,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",
@@ -849,10 +937,10 @@ function ComboboxList({
 }
 function LoadMoreSentinel() {
   const { open, loading, filteredItems, onLoadMore } = useComboboxRootContext("List");
-  const ref = (0, import_react9.useRef)(null);
-  const onLoadMoreRef = (0, import_react9.useRef)(onLoadMore);
+  const ref = (0, import_react10.useRef)(null);
+  const onLoadMoreRef = (0, import_react10.useRef)(onLoadMore);
   onLoadMoreRef.current = onLoadMore;
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     const element = ref.current;
     if (!element || !open || loading || typeof IntersectionObserver === "undefined") return;
     const observer = new IntersectionObserver((entries) => {
@@ -865,10 +953,52 @@ function LoadMoreSentinel() {
 }
 
 // src/combobox/ComboboxItem.tsx
-var import_react10 = require("react");
+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,
@@ -884,23 +1014,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_react10.useSyncExternalStore)(
+  const highlighted = (0, import_react12.useSyncExternalStore)(
     highlight.subscribe,
     () => index >= 0 && highlight.get().index === index,
     () => false
   );
-  const elementRef = (0, import_react10.useRef)(null);
-  (0, import_react10.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_react10.useEffect)(() => {
+  (0, import_react12.useEffect)(() => {
     if (highlighted && highlight.get().reason === "keyboard") {
       elementRef.current?.scrollIntoView?.({ block: "nearest" });
     }
@@ -931,6 +1063,28 @@ 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/ComboboxEmpty.tsx
 function ComboboxEmpty({ className, children, render, ...rest }) {
   const { filteredItems, loading } = useComboboxRootContext("Empty");
@@ -955,11 +1109,11 @@ function ComboboxStatus({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxChip.tsx
-var import_react11 = require("react");
-var import_jsx_runtime3 = require("react/jsx-runtime");
-var ComboboxChipContext = (0, import_react11.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_react11.useContext)(ComboboxChipContext);
+  const context = (0, import_react14.useContext)(ComboboxChipContext);
   if (context === null) {
     throw new Error("<Combobox.ChipRemove> must be rendered inside <Combobox.Chip>.");
   }
@@ -974,9 +1128,9 @@ function ComboboxChip({
 }) {
   const { disabled, itemToKey, remove, registerChip, chips, inputRef } = useComboboxRootContext("Chip");
   const key = itemToKey(value);
-  const elementRef = (0, import_react11.useRef)(null);
-  (0, import_react11.useLayoutEffect)(() => registerChip({ key, ref: elementRef }), [registerChip, key]);
-  const chipContext = (0, import_react11.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();
@@ -1017,7 +1171,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
@@ -1050,6 +1204,14 @@ function ComboboxChipRemove({
     consumerProps: rest
   });
 }
+
+// src/combobox/ComboboxValue.tsx
+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_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: children(value, { itemToString }) });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Combobox,

package/dist/combobox/index.d.cts

@@ -21,12 +21,23 @@ type ComboboxState = {
 };
 
 /** The selection: one item or `null`, or an array with `multiple`. */
-type ComboboxValue<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
+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.
@@ -51,10 +62,10 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
      * Never `undefined` once mounted: the mode is latched at mount. Use `null` — or `[]` with
      * `multiple` — for nothing selected.
      */
-    value?: ComboboxValue<T, Multiple>;
+    value?: ComboboxValue$1<T, Multiple>;
     /** Initial selection when uncontrolled. Read once, at mount. */
-    defaultValue?: ComboboxValue<T, Multiple>;
-    onValueChange?: (value: ComboboxValue<T, Multiple>, details: ComboboxChangeDetails) => void;
+    defaultValue?: ComboboxValue$1<T, Multiple>;
+    onValueChange?: (value: ComboboxValue$1<T, Multiple>, details: ComboboxChangeDetails) => void;
     /** Controlled text of the input. Provide `onInputValueChange` alongside it. */
     inputValue?: string;
     /** Initial text when uncontrolled. Defaults to the selected item's label, without `multiple`. */
@@ -78,6 +89,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 +112,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. */
@@ -107,18 +123,39 @@ type ComboboxInputOwnProps = {
 type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof ComboboxInputOwnProps | 'value' | 'defaultValue'>;
 /**
  * The text input: `role="combobox"`, and the element focus stays on. Its text is the Root's
- * `inputValue`. It is what the popup is anchored to.
+ * `inputValue`. It is what the popup is anchored to, unless an InputGroup wraps it.
  *
  * Typing opens the list and filters it. Up and Down open it, or move the highlight, wrapping;
  * Home and End jump to the ends while it is open; Alt+Down opens it without highlighting.
  * 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`.
  */
 declare function ComboboxInput({ className, render, ...rest }: ComboboxInputProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
+type ComboboxInputGroupOwnProps = {
+    /** 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 ComboboxInputGroupProps = ComboboxInputGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxInputGroupOwnProps>;
+/**
+ * The field around the Input — chips, Clear and Trigger with it — when they are drawn as one
+ * box. It takes over as the popup's anchor, so the list lines up with the whole field rather
+ * than the text alone, and a press on it is not a press outside.
+ *
+ * A press on the box itself, between its children, focuses the input.
+ */
+declare function ComboboxInputGroup({ className, children, render, ...rest }: ComboboxInputGroupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
 type ComboboxTriggerOwnProps = {
     /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
     render?: ReactElement;
@@ -178,7 +215,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. */
@@ -188,7 +226,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.
@@ -198,7 +237,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;
@@ -213,7 +252,38 @@ 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 ComboboxEmptyOwnProps = {
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -273,8 +343,26 @@ type ComboboxChipRemoveProps = ComboboxChipRemoveOwnProps & Omit<ComponentPropsW
  */
 declare function ComboboxChipRemove({ className, children, render, ...rest }: ComboboxChipRemoveProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
+type ComboboxValueProps<T = unknown> = {
+    /**
+     * Renders the selection: `T | null`, or `T[]` with `multiple`. The Root's `itemToString` is
+     * passed along for labels — a chip's text, say.
+     */
+    children: (value: T, details: {
+        itemToString: (item: unknown) => string;
+    }) => ReactNode;
+};
+/**
+ * The current selection, for whatever shows it outside the input — chips, most often. Renders
+ * no element of its own.
+ *
+ * It exists so that a separate styling package can show the selection without owning a copy
+ * of it (decision 9): the value stays the Root's.
+ */
+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, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger };
+  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, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
 }
 
 /**
@@ -285,4 +373,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 ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue, 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 ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };

package/dist/combobox/index.d.ts

@@ -21,12 +21,23 @@ type ComboboxState = {
 };
 
 /** The selection: one item or `null`, or an array with `multiple`. */
-type ComboboxValue<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
+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.
@@ -51,10 +62,10 @@ type ComboboxRootProps<T, Multiple extends boolean = false> = {
      * Never `undefined` once mounted: the mode is latched at mount. Use `null` — or `[]` with
      * `multiple` — for nothing selected.
      */
-    value?: ComboboxValue<T, Multiple>;
+    value?: ComboboxValue$1<T, Multiple>;
     /** Initial selection when uncontrolled. Read once, at mount. */
-    defaultValue?: ComboboxValue<T, Multiple>;
-    onValueChange?: (value: ComboboxValue<T, Multiple>, details: ComboboxChangeDetails) => void;
+    defaultValue?: ComboboxValue$1<T, Multiple>;
+    onValueChange?: (value: ComboboxValue$1<T, Multiple>, details: ComboboxChangeDetails) => void;
     /** Controlled text of the input. Provide `onInputValueChange` alongside it. */
     inputValue?: string;
     /** Initial text when uncontrolled. Defaults to the selected item's label, without `multiple`. */
@@ -78,6 +89,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 +112,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. */
@@ -107,18 +123,39 @@ type ComboboxInputOwnProps = {
 type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof ComboboxInputOwnProps | 'value' | 'defaultValue'>;
 /**
  * The text input: `role="combobox"`, and the element focus stays on. Its text is the Root's
- * `inputValue`. It is what the popup is anchored to.
+ * `inputValue`. It is what the popup is anchored to, unless an InputGroup wraps it.
  *
  * Typing opens the list and filters it. Up and Down open it, or move the highlight, wrapping;
  * Home and End jump to the ends while it is open; Alt+Down opens it without highlighting.
  * 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`.
  */
 declare function ComboboxInput({ className, render, ...rest }: ComboboxInputProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
+type ComboboxInputGroupOwnProps = {
+    /** 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 ComboboxInputGroupProps = ComboboxInputGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxInputGroupOwnProps>;
+/**
+ * The field around the Input — chips, Clear and Trigger with it — when they are drawn as one
+ * box. It takes over as the popup's anchor, so the list lines up with the whole field rather
+ * than the text alone, and a press on it is not a press outside.
+ *
+ * A press on the box itself, between its children, focuses the input.
+ */
+declare function ComboboxInputGroup({ className, children, render, ...rest }: ComboboxInputGroupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
 type ComboboxTriggerOwnProps = {
     /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
     render?: ReactElement;
@@ -178,7 +215,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. */
@@ -188,7 +226,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.
@@ -198,7 +237,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;
@@ -213,7 +252,38 @@ 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 ComboboxEmptyOwnProps = {
     /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
@@ -273,8 +343,26 @@ type ComboboxChipRemoveProps = ComboboxChipRemoveOwnProps & Omit<ComponentPropsW
  */
 declare function ComboboxChipRemove({ className, children, render, ...rest }: ComboboxChipRemoveProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
+type ComboboxValueProps<T = unknown> = {
+    /**
+     * Renders the selection: `T | null`, or `T[]` with `multiple`. The Root's `itemToString` is
+     * passed along for labels — a chip's text, say.
+     */
+    children: (value: T, details: {
+        itemToString: (item: unknown) => string;
+    }) => ReactNode;
+};
+/**
+ * The current selection, for whatever shows it outside the input — chips, most often. Renders
+ * no element of its own.
+ *
+ * It exists so that a separate styling package can show the selection without owning a copy
+ * of it (decision 9): the value stays the Root's.
+ */
+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, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger };
+  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, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
 }
 
 /**
@@ -285,4 +373,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 ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue, 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 ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };

package/dist/combobox/index.js

@@ -22,13 +22,17 @@ __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,
   Status: () => ComboboxStatus,
-  Trigger: () => ComboboxTrigger
+  Trigger: () => ComboboxTrigger,
+  Value: () => ComboboxValue
 });
 
 // src/combobox/ComboboxRoot.tsx
@@ -73,6 +77,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);
@@ -97,6 +106,7 @@ function ComboboxRoot({
   onLoadMore,
   loading = false,
   disabled = false,
+  required = false,
   name,
   form,
   children
@@ -133,10 +143,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])),
@@ -248,6 +265,11 @@ function ComboboxRoot({
     },
     [insideRefs]
   );
+  const [hasGroup, setHasGroup] = useState(false);
+  const registerGroup = useCallback(() => {
+    setHasGroup(true);
+    return () => setHasGroup(false);
+  }, []);
   const inputRef = useRef(null);
   const popupRef = useRef(null);
   const { current: initial } = useRef({ value, inputValue });
@@ -276,9 +298,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -298,6 +322,8 @@ function ComboboxRoot({
       chips,
       registerInside,
       isInside,
+      hasGroup,
+      registerGroup,
       onLoadMore,
       inputId: `${id}-input`,
       listId: `${id}-list`,
@@ -310,9 +336,11 @@ function ComboboxRoot({
       open,
       multiple,
       disabled,
+      required,
       inputValue,
       loading,
       filteredItems,
+      filteredGroups,
       itemToString,
       itemToKey,
       indexByKey,
@@ -332,6 +360,8 @@ function ComboboxRoot({
       chips,
       registerInside,
       isInside,
+      hasGroup,
+      registerGroup,
       onLoadMore,
       id
     ]
@@ -353,7 +383,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 }) {
@@ -384,6 +414,7 @@ function ComboboxInput({ className, render, ...rest }) {
     open,
     multiple,
     disabled,
+    required,
     inputValue,
     filteredItems,
     itemToKey,
@@ -403,6 +434,7 @@ function ComboboxInput({ className, render, ...rest }) {
     listId,
     optionId,
     anchorName,
+    hasGroup,
     inputRef,
     popupRef
   } = useComboboxRootContext("Input");
@@ -411,6 +443,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) => {
@@ -448,9 +494,13 @@ 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 }),
-      style: { anchorName },
+      // The anchor, unless an InputGroup around it is.
+      style: hasGroup ? void 0 : { anchorName },
       className,
       ref: inputRef,
       onChange(event) {
@@ -516,13 +566,49 @@ 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 as useLayoutEffect2, useRef as useRef3 } from "react";
+function ComboboxInputGroup({
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const { open, multiple, disabled, anchorName, registerGroup, registerInside, inputRef } = useComboboxRootContext("InputGroup");
+  const elementRef = useRef3(null);
+  useLayoutEffect2(() => registerGroup(), [registerGroup]);
+  useLayoutEffect2(() => registerInside(elementRef), [registerInside]);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      ...comboboxDataAttributes({ open, multiple, disabled }),
+      style: { anchorName },
+      className,
+      children,
+      ref: elementRef,
+      onMouseDown(event) {
+        if (event.target !== event.currentTarget || disabled) return;
+        event.preventDefault();
+        inputRef.current?.focus();
+      }
+    },
+    consumerProps: rest
+  });
+}
 
 // src/combobox/ComboboxTrigger.tsx
-import { useLayoutEffect, useRef as useRef2 } 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 = useRef2(null);
-  useLayoutEffect(() => registerInside(elementRef), [registerInside]);
+  const elementRef = useRef4(null);
+  useLayoutEffect3(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -550,11 +636,11 @@ function ComboboxTrigger({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxClear.tsx
-import { useLayoutEffect as useLayoutEffect2, useRef as useRef3 } 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 = useRef3(null);
-  useLayoutEffect2(() => registerInside(elementRef), [registerInside]);
+  const elementRef = useRef5(null);
+  useLayoutEffect4(() => registerInside(elementRef), [registerInside]);
   return useRender({
     render,
     defaultTagName: "button",
@@ -637,7 +723,7 @@ function ComboboxPopup({
 }
 
 // src/combobox/ComboboxList.tsx
-import { useEffect as useEffect3, useRef as useRef4 } 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,
@@ -645,8 +731,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",
@@ -666,8 +754,8 @@ function ComboboxList({
 }
 function LoadMoreSentinel() {
   const { open, loading, filteredItems, onLoadMore } = useComboboxRootContext("List");
-  const ref = useRef4(null);
-  const onLoadMoreRef = useRef4(onLoadMore);
+  const ref = useRef6(null);
+  const onLoadMoreRef = useRef6(onLoadMore);
   onLoadMoreRef.current = onLoadMore;
   useEffect3(() => {
     const element = ref.current;
@@ -682,10 +770,52 @@ function LoadMoreSentinel() {
 }
 
 // src/combobox/ComboboxItem.tsx
-import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect3, useRef as useRef5, 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,
@@ -701,6 +831,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);
@@ -709,8 +841,8 @@ function ComboboxItem({
     () => index >= 0 && highlight.get().index === index,
     () => false
   );
-  const elementRef = useRef5(null);
-  useLayoutEffect3(() => {
+  const elementRef = useRef7(null);
+  useLayoutEffect5(() => {
     if (!disabled) return;
     disabledKeys.add(key);
     return () => {
@@ -748,6 +880,28 @@ 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/ComboboxEmpty.tsx
 function ComboboxEmpty({ className, children, render, ...rest }) {
   const { filteredItems, loading } = useComboboxRootContext("Empty");
@@ -772,11 +926,11 @@ function ComboboxStatus({ className, children, render, ...rest }) {
 }
 
 // src/combobox/ComboboxChip.tsx
-import { createContext as createContext2, useContext as useContext2, useLayoutEffect as useLayoutEffect4, useMemo as useMemo2, useRef as useRef6 } 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>.");
   }
@@ -791,9 +945,9 @@ function ComboboxChip({
 }) {
   const { disabled, itemToKey, remove, registerChip, chips, inputRef } = useComboboxRootContext("Chip");
   const key = itemToKey(value);
-  const elementRef = useRef6(null);
-  useLayoutEffect4(() => 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();
@@ -834,7 +988,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
@@ -867,6 +1021,14 @@ function ComboboxChipRemove({
     consumerProps: rest
   });
 }
+
+// src/combobox/ComboboxValue.tsx
+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__ */ jsx5(Fragment2, { children: children(value, { itemToString }) });
+}
 export {
   index_parts_exports as Combobox,
   defaultFilter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.8.0",
+  "version": "4.10.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",