@arun-dev/headless 4.10.0 → 4.12.0

package/dist/combobox/index.cjs

@@ -40,6 +40,7 @@ __export(index_parts_exports, {
   List: () => ComboboxList,
   Popup: () => ComboboxPopup,
   Root: () => ComboboxRoot,
+  Separator: () => ComboboxSeparator,
   Status: () => ComboboxStatus,
   Trigger: () => ComboboxTrigger,
   Value: () => ComboboxValue
@@ -341,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) => {
@@ -831,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,
@@ -1085,6 +1087,17 @@ function ComboboxGroupLabel({
   });
 }
 
+// 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");

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;
 };
@@ -182,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>>;
@@ -285,6 +288,23 @@ type ComboboxGroupLabelProps = ComboboxGroupLabelOwnProps & Omit<ComponentPropsW
  */
 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. */
     render?: ReactElement;
@@ -362,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, 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 };
+  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 };
 }
 
 /**
@@ -373,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 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 };
+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;
 };
@@ -182,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>>;
@@ -285,6 +288,23 @@ type ComboboxGroupLabelProps = ComboboxGroupLabelOwnProps & Omit<ComponentPropsW
  */
 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. */
     render?: ReactElement;
@@ -362,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, 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 };
+  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 };
 }
 
 /**
@@ -373,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 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 };
+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

@@ -30,6 +30,7 @@ __export(index_parts_exports, {
   List: () => ComboboxList,
   Popup: () => ComboboxPopup,
   Root: () => ComboboxRoot,
+  Separator: () => ComboboxSeparator,
   Status: () => ComboboxStatus,
   Trigger: () => ComboboxTrigger,
   Value: () => ComboboxValue
@@ -247,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) => {
@@ -648,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,
@@ -902,6 +904,17 @@ function ComboboxGroupLabel({
   });
 }
 
+// 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");

package/dist/field/index.cjs

@@ -0,0 +1,287 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/field/index.ts
+var field_exports = {};
+__export(field_exports, {
+  Field: () => index_parts_exports
+});
+module.exports = __toCommonJS(field_exports);
+
+// src/field/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Control: () => FieldControl,
+  Description: () => FieldDescription,
+  Error: () => FieldError,
+  Label: () => FieldLabel,
+  Root: () => FieldRoot
+});
+
+// src/field/FieldRoot.tsx
+var import_react3 = require("react");
+
+// src/core/useRender.ts
+var import_react = require("react");
+
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
+function chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? chainHandlers(earlier, value) : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  consumerProps
+}) {
+  const merged = mergeProps(props, consumerProps);
+  if ((0, import_react.isValidElement)(render)) {
+    return (0, import_react.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react.createElement)(defaultTagName, merged);
+}
+
+// src/field/FieldRootContext.ts
+var import_react2 = require("react");
+var FieldRootContext = (0, import_react2.createContext)(null);
+function useFieldRootContext(part) {
+  const context = (0, import_react2.useContext)(FieldRootContext);
+  if (context === null) {
+    throw new Error(`<Field.${part}> must be rendered inside <Field.Root>.`);
+  }
+  return context;
+}
+function fieldDataAttributes({ invalid, disabled, required }) {
+  return {
+    "data-invalid": invalid ? "" : void 0,
+    "data-disabled": disabled ? "" : void 0,
+    "data-required": required ? "" : void 0
+  };
+}
+
+// src/field/FieldRoot.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function usePresence() {
+  const [count, setCount] = (0, import_react3.useState)(0);
+  const register = (0, import_react3.useCallback)(() => {
+    setCount((n) => n + 1);
+    return () => setCount((n) => n - 1);
+  }, []);
+  return [count > 0, register];
+}
+function FieldRoot({
+  invalid = false,
+  disabled = false,
+  required = false,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const id = (0, import_react3.useId)();
+  const [hasDescription, registerDescription] = usePresence();
+  const [hasError, registerError] = usePresence();
+  const context = (0, import_react3.useMemo)(
+    () => ({
+      invalid,
+      disabled,
+      required,
+      controlId: `${id}-control`,
+      descriptionId: `${id}-description`,
+      errorId: `${id}-error`,
+      hasDescription,
+      hasError,
+      registerDescription,
+      registerError
+    }),
+    [invalid, disabled, required, id, hasDescription, hasError, registerDescription, registerError]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: { ...fieldDataAttributes({ invalid, disabled, required }), className, children },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FieldRootContext.Provider, { value: context, children: element });
+}
+
+// src/field/FieldLabel.tsx
+function FieldLabel({ className, children, render, ...rest }) {
+  const { controlId, ...state } = useFieldRootContext("Label");
+  return useRender({
+    render,
+    defaultTagName: "label",
+    props: { htmlFor: controlId, ...fieldDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldControl.tsx
+function FieldControl({
+  render,
+  "aria-describedby": describedBy,
+  ...rest
+}) {
+  const { controlId, descriptionId, errorId, hasDescription, hasError, ...state } = useFieldRootContext("Control");
+  const describedByIds = [
+    hasDescription ? descriptionId : void 0,
+    hasError ? errorId : void 0,
+    describedBy
+  ].filter(Boolean).join(" ");
+  return useRender({
+    render,
+    defaultTagName: "input",
+    props: {
+      id: controlId,
+      "aria-describedby": describedByIds || void 0,
+      "aria-invalid": state.invalid || void 0,
+      disabled: state.disabled || void 0,
+      required: state.required || void 0,
+      ...fieldDataAttributes(state)
+    },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldDescription.tsx
+var import_react4 = require("react");
+function FieldDescription({ className, children, render, ...rest }) {
+  const context = useFieldRootContext("Description");
+  const { descriptionId, registerDescription, invalid, disabled, required } = context;
+  (0, import_react4.useLayoutEffect)(registerDescription, [registerDescription]);
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: {
+      id: descriptionId,
+      ...fieldDataAttributes({ invalid, disabled, required }),
+      className,
+      children
+    },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldError.tsx
+var import_react5 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function FieldError({ className, children, render, ...rest }) {
+  const context = useFieldRootContext("Error");
+  const { invalid, disabled, required } = context;
+  if (!invalid) return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    ShownError,
+    {
+      className,
+      render,
+      state: { invalid, disabled, required },
+      ...rest,
+      children
+    }
+  );
+}
+function ShownError({
+  className,
+  children,
+  render,
+  state,
+  ...rest
+}) {
+  const { errorId, registerError } = useFieldRootContext("Error");
+  (0, import_react5.useLayoutEffect)(registerError, [registerError]);
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: { id: errorId, ...fieldDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Field
+});

package/dist/field/index.d.cts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+type FieldRootOwnProps = {
+    /** Shows the Error and marks the control `aria-invalid`. Yours to set — Field validates nothing. */
+    invalid?: boolean;
+    /** Disables the control and marks every part `data-disabled`. */
+    disabled?: boolean;
+    /** Marks the control `required`, so the browser's own validation reports it. */
+    required?: 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 FieldRootProps = FieldRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof FieldRootOwnProps>;
+/**
+ * One control with its label, description and error (decision 15). Generates their ids and
+ * holds `invalid`, `disabled` and `required`; `Control` puts them on the control.
+ *
+ * Validity is yours: set `invalid` from react-hook-form's `fieldState`, or from what the
+ * browser reported. A group of controls under one label is a native `<fieldset>`.
+ */
+declare function FieldRoot({ invalid, disabled, required, className, children, render, ...rest }: FieldRootProps): react.JSX.Element;
+
+type FieldLabelOwnProps = {
+    /** Element to render instead of the default `<label>`. 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 FieldLabelProps = FieldLabelOwnProps & Omit<ComponentPropsWithRef<'label'>, keyof FieldLabelOwnProps>;
+/** Names the control: a `<label>` whose `htmlFor` is the control's id, so a press focuses it. */
+declare function FieldLabel({ className, children, render, ...rest }: FieldLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldControlOwnProps = {
+    /**
+     * The control: `<Input />`, `<Select />`, `<Checkbox.Root />`, `<Combobox.Input />` or your
+     * own. Defaults to an `<input>`. The Field's `id`, `aria-describedby`, `aria-invalid`,
+     * `disabled` and `required` are merged onto it.
+     */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type FieldControlProps = FieldControlOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof FieldControlOwnProps>;
+/**
+ * Puts the Field on its control. `render` is the seam: Field does not reach into each control,
+ * it hands the control the attributes that tie it to the label, description and error.
+ *
+ * `aria-describedby` names the Description, then the Error — only those rendered — followed by
+ * any of your own. The id is the Field's: an `id` of your own breaks the Label's `htmlFor`.
+ */
+declare function FieldControl({ render, 'aria-describedby': describedBy, ...rest }: FieldControlProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldDescriptionOwnProps = {
+    /** Element to render instead of the default `<p>`. 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 FieldDescriptionProps = FieldDescriptionOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof FieldDescriptionOwnProps>;
+/**
+ * Help text under the control, read out with it through `aria-describedby`.
+ */
+declare function FieldDescription({ className, children, render, ...rest }: FieldDescriptionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldErrorOwnProps = {
+    /** Element to render instead of the default `<p>`. 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 FieldErrorProps = FieldErrorOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof FieldErrorOwnProps>;
+/**
+ * What is wrong, read out with the control through `aria-describedby`. Rendered only while the
+ * Root is `invalid`, so it is named only while it is shown.
+ */
+declare function FieldError({ className, children, render, ...rest }: FieldErrorProps): react.JSX.Element | null;
+
+declare namespace index_parts {
+  export { FieldControl as Control, FieldDescription as Description, FieldError as Error, FieldLabel as Label, FieldRoot as Root };
+}
+
+/** The state Field.Root shares with its parts, and projects as `data-*` attributes. */
+type FieldState = {
+    invalid: boolean;
+    disabled: boolean;
+    required: boolean;
+};
+
+export { index_parts as Field, type FieldControlProps, type FieldDescriptionProps, type FieldErrorProps, type FieldLabelProps, type FieldRootProps, type FieldState };

package/dist/field/index.d.ts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+type FieldRootOwnProps = {
+    /** Shows the Error and marks the control `aria-invalid`. Yours to set — Field validates nothing. */
+    invalid?: boolean;
+    /** Disables the control and marks every part `data-disabled`. */
+    disabled?: boolean;
+    /** Marks the control `required`, so the browser's own validation reports it. */
+    required?: 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 FieldRootProps = FieldRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof FieldRootOwnProps>;
+/**
+ * One control with its label, description and error (decision 15). Generates their ids and
+ * holds `invalid`, `disabled` and `required`; `Control` puts them on the control.
+ *
+ * Validity is yours: set `invalid` from react-hook-form's `fieldState`, or from what the
+ * browser reported. A group of controls under one label is a native `<fieldset>`.
+ */
+declare function FieldRoot({ invalid, disabled, required, className, children, render, ...rest }: FieldRootProps): react.JSX.Element;
+
+type FieldLabelOwnProps = {
+    /** Element to render instead of the default `<label>`. 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 FieldLabelProps = FieldLabelOwnProps & Omit<ComponentPropsWithRef<'label'>, keyof FieldLabelOwnProps>;
+/** Names the control: a `<label>` whose `htmlFor` is the control's id, so a press focuses it. */
+declare function FieldLabel({ className, children, render, ...rest }: FieldLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldControlOwnProps = {
+    /**
+     * The control: `<Input />`, `<Select />`, `<Checkbox.Root />`, `<Combobox.Input />` or your
+     * own. Defaults to an `<input>`. The Field's `id`, `aria-describedby`, `aria-invalid`,
+     * `disabled` and `required` are merged onto it.
+     */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type FieldControlProps = FieldControlOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof FieldControlOwnProps>;
+/**
+ * Puts the Field on its control. `render` is the seam: Field does not reach into each control,
+ * it hands the control the attributes that tie it to the label, description and error.
+ *
+ * `aria-describedby` names the Description, then the Error — only those rendered — followed by
+ * any of your own. The id is the Field's: an `id` of your own breaks the Label's `htmlFor`.
+ */
+declare function FieldControl({ render, 'aria-describedby': describedBy, ...rest }: FieldControlProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldDescriptionOwnProps = {
+    /** Element to render instead of the default `<p>`. 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 FieldDescriptionProps = FieldDescriptionOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof FieldDescriptionOwnProps>;
+/**
+ * Help text under the control, read out with it through `aria-describedby`.
+ */
+declare function FieldDescription({ className, children, render, ...rest }: FieldDescriptionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type FieldErrorOwnProps = {
+    /** Element to render instead of the default `<p>`. 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 FieldErrorProps = FieldErrorOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof FieldErrorOwnProps>;
+/**
+ * What is wrong, read out with the control through `aria-describedby`. Rendered only while the
+ * Root is `invalid`, so it is named only while it is shown.
+ */
+declare function FieldError({ className, children, render, ...rest }: FieldErrorProps): react.JSX.Element | null;
+
+declare namespace index_parts {
+  export { FieldControl as Control, FieldDescription as Description, FieldError as Error, FieldLabel as Label, FieldRoot as Root };
+}
+
+/** The state Field.Root shares with its parts, and projects as `data-*` attributes. */
+type FieldState = {
+    invalid: boolean;
+    disabled: boolean;
+    required: boolean;
+};
+
+export { index_parts as Field, type FieldControlProps, type FieldDescriptionProps, type FieldErrorProps, type FieldLabelProps, type FieldRootProps, type FieldState };

package/dist/field/index.js

@@ -0,0 +1,176 @@
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/field/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Control: () => FieldControl,
+  Description: () => FieldDescription,
+  Error: () => FieldError,
+  Label: () => FieldLabel,
+  Root: () => FieldRoot
+});
+
+// src/field/FieldRoot.tsx
+import { useCallback, useId, useMemo, useState } from "react";
+
+// src/field/FieldRootContext.ts
+import { createContext, useContext } from "react";
+var FieldRootContext = createContext(null);
+function useFieldRootContext(part) {
+  const context = useContext(FieldRootContext);
+  if (context === null) {
+    throw new Error(`<Field.${part}> must be rendered inside <Field.Root>.`);
+  }
+  return context;
+}
+function fieldDataAttributes({ invalid, disabled, required }) {
+  return {
+    "data-invalid": invalid ? "" : void 0,
+    "data-disabled": disabled ? "" : void 0,
+    "data-required": required ? "" : void 0
+  };
+}
+
+// src/field/FieldRoot.tsx
+import { jsx } from "react/jsx-runtime";
+function usePresence() {
+  const [count, setCount] = useState(0);
+  const register = useCallback(() => {
+    setCount((n) => n + 1);
+    return () => setCount((n) => n - 1);
+  }, []);
+  return [count > 0, register];
+}
+function FieldRoot({
+  invalid = false,
+  disabled = false,
+  required = false,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const id = useId();
+  const [hasDescription, registerDescription] = usePresence();
+  const [hasError, registerError] = usePresence();
+  const context = useMemo(
+    () => ({
+      invalid,
+      disabled,
+      required,
+      controlId: `${id}-control`,
+      descriptionId: `${id}-description`,
+      errorId: `${id}-error`,
+      hasDescription,
+      hasError,
+      registerDescription,
+      registerError
+    }),
+    [invalid, disabled, required, id, hasDescription, hasError, registerDescription, registerError]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: { ...fieldDataAttributes({ invalid, disabled, required }), className, children },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsx(FieldRootContext.Provider, { value: context, children: element });
+}
+
+// src/field/FieldLabel.tsx
+function FieldLabel({ className, children, render, ...rest }) {
+  const { controlId, ...state } = useFieldRootContext("Label");
+  return useRender({
+    render,
+    defaultTagName: "label",
+    props: { htmlFor: controlId, ...fieldDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldControl.tsx
+function FieldControl({
+  render,
+  "aria-describedby": describedBy,
+  ...rest
+}) {
+  const { controlId, descriptionId, errorId, hasDescription, hasError, ...state } = useFieldRootContext("Control");
+  const describedByIds = [
+    hasDescription ? descriptionId : void 0,
+    hasError ? errorId : void 0,
+    describedBy
+  ].filter(Boolean).join(" ");
+  return useRender({
+    render,
+    defaultTagName: "input",
+    props: {
+      id: controlId,
+      "aria-describedby": describedByIds || void 0,
+      "aria-invalid": state.invalid || void 0,
+      disabled: state.disabled || void 0,
+      required: state.required || void 0,
+      ...fieldDataAttributes(state)
+    },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldDescription.tsx
+import { useLayoutEffect } from "react";
+function FieldDescription({ className, children, render, ...rest }) {
+  const context = useFieldRootContext("Description");
+  const { descriptionId, registerDescription, invalid, disabled, required } = context;
+  useLayoutEffect(registerDescription, [registerDescription]);
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: {
+      id: descriptionId,
+      ...fieldDataAttributes({ invalid, disabled, required }),
+      className,
+      children
+    },
+    consumerProps: rest
+  });
+}
+
+// src/field/FieldError.tsx
+import { useLayoutEffect as useLayoutEffect2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function FieldError({ className, children, render, ...rest }) {
+  const context = useFieldRootContext("Error");
+  const { invalid, disabled, required } = context;
+  if (!invalid) return null;
+  return /* @__PURE__ */ jsx2(
+    ShownError,
+    {
+      className,
+      render,
+      state: { invalid, disabled, required },
+      ...rest,
+      children
+    }
+  );
+}
+function ShownError({
+  className,
+  children,
+  render,
+  state,
+  ...rest
+}) {
+  const { errorId, registerError } = useFieldRootContext("Error");
+  useLayoutEffect2(registerError, [registerError]);
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: { id: errorId, ...fieldDataAttributes(state), className, children },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Field
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.10.0",
+  "version": "4.12.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",
@@ -104,6 +104,16 @@
         "default": "./dist/radio-group/index.cjs"
       }
     },
+    "./field": {
+      "import": {
+        "types": "./dist/field/index.d.ts",
+        "default": "./dist/field/index.js"
+      },
+      "require": {
+        "types": "./dist/field/index.d.cts",
+        "default": "./dist/field/index.cjs"
+      }
+    },
     "./switch": {
       "import": {
         "types": "./dist/switch/index.d.ts",