@central-ui/react 0.1.2 → 0.2.0

package/dist/components/combobox/index.d.ts

@@ -1,6 +1,8 @@
-import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
 import type { SVGIconProps } from '../../types/Icon.ts';
+import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
+import type { ValidationProps } from '../../types/Validation.ts';
 import type { ComponentProps, ComponentPropsWithRef, ReactElement, ReactNode } from 'react';
+import type { ValidationMessageChildren } from '../../utils/Validation.ts';
 type StyleProps = {
     /**
      * Disables preset styling for this element.
@@ -34,7 +36,7 @@ export type GroupType<T extends readonly GroupShape[]> = T[number];
 export type ItemType<T extends readonly GroupShape[]> = GroupType<T>['items'][number];
 /** Manually type a ChipsList callback argument with ChipsType<typeof rootItems>, using the exact items variable passed to Root. Also useful for multiple-selection state. */
 export type ChipsType<T extends readonly GroupShape[]> = ItemType<T>[];
-export type RootProps<T extends readonly GroupShape[], Multiple extends boolean | undefined = false> = Omit<BaseCombobox.Root.Props<ItemType<T>, Multiple>, 'items' | 'filteredItems' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'id'> & {
+export type RootProps<T extends readonly GroupShape[], Multiple extends boolean | undefined = false> = Omit<BaseCombobox.Root.Props<ItemType<T>, Multiple>, 'items' | 'filteredItems' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'id'> & ValidationProps & {
     /** Input id, also used automatically by Label. Omit to generate a stable id. */
     id?: BaseCombobox.Root.Props<ItemType<T>, Multiple>['id'];
     /**
@@ -50,8 +52,6 @@ export type RootProps<T extends readonly GroupShape[], Multiple extends boolean
      * performs filtering itself, such as filtering results on a server.
      */
     filteredItems?: readonly GroupType<T>[];
-    /** Visual validation tone only; does not validate or change selection. @default 'neutral' */
-    tone?: 'neutral' | 'valid' | 'invalid';
 };
 /**
  * Searchable selection using Base UI's built-in filtering and keyboard handling.
@@ -206,7 +206,7 @@ export type RootProps<T extends readonly GroupShape[], Multiple extends boolean
  *   <Combobox.AddonOpenButtonIcon />
  * </Combobox.AddonOpenButton>
  */
-export declare function Root<T extends readonly GroupShape[], Multiple extends boolean | undefined = false>({ children, id, tone, open, defaultOpen, onOpenChange, onItemHighlighted, ...props }: RootProps<T, Multiple>): import("react").JSX.Element;
+export declare function Root<T extends readonly GroupShape[], Multiple extends boolean | undefined = false>({ children, id, validation, defaultOpen, onOpenChange, ...props }: RootProps<T, Multiple>): import("react").JSX.Element;
 /** Use for the standard stacked layout, or omit when supplying your own layout. */
 export declare const Container: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 /** Labels the input automatically using Root's id. Supply the visible label as children; no htmlFor needed. */
@@ -271,7 +271,7 @@ export type GroupsListProps<Group extends GroupShape = GroupShape> = Omit<Compon
     children: ReactNode | ((group: Group, index: number) => ReactNode);
 } & StyleProps;
 /** Required groups container inside ScrollArea. A children callback receives each automatically filtered group; do not filter or map the original groups again. Manually annotate group with Combobox.GroupType<typeof rootItems>, using the exact items variable passed to Root. */
-export declare function GroupsList<Group extends GroupShape = GroupShape>({ disableStyle, children, className, style, ...props }: GroupsListProps<Group>): import("react").JSX.Element;
+export declare function GroupsList<Group extends GroupShape = GroupShape>({ disableStyle, children, className, ...props }: GroupsListProps<Group>): import("react").JSX.Element;
 export type ItemsListProps<Item extends ItemShape = ItemShape> = Omit<ComponentPropsWithRef<'div'>, 'children' | 'className'> & {
     className?: string;
     /**
@@ -283,21 +283,21 @@ export type ItemsListProps<Item extends ItemShape = ItemShape> = Omit<ComponentP
     children?: ReactNode | ((item: Item, index: number) => ReactNode);
 } & StyleProps;
 /** Required items container inside Group. A children callback receives the filtered items belonging to that Group; do not repeat filtering yourself. Manually annotate item with Combobox.ItemType<typeof rootItems>, using the exact items variable passed to Root. */
-export declare function ItemsList<Item extends ItemShape = ItemShape>({ disableStyle, children, className, style, ...props }: ItemsListProps<Item>): import("react").JSX.Element;
+export declare function ItemsList<Item extends ItemShape = ItemShape>({ disableStyle, children, className, ...props }: ItemsListProps<Item>): import("react").JSX.Element;
 export type GroupProps<Item extends ItemShape = ItemShape> = Omit<ComponentPropsWithRef<typeof BaseCombobox.Group>, 'items' | 'className'> & {
     className?: string;
     /** Items for this group; pass group.items from GroupsList. Required even for a flat list. */
     items: readonly Item[];
 } & StyleProps;
 /** Required wrapper around ItemsList, even for a visually flat list. Pass group.items. A GroupLabel is optional; omit it when the group has an empty label. */
-export declare function Group<Item extends ItemShape = ItemShape>({ disableStyle, className, style, ...props }: GroupProps<Item>): import("react").JSX.Element;
+export declare function Group<Item extends ItemShape = ItemShape>({ disableStyle, className, ...props }: GroupProps<Item>): import("react").JSX.Element;
 export type ItemProps<Item extends ItemShape = ItemShape> = Omit<ComponentPropsWithRef<typeof BaseCombobox.Item>, 'value' | 'className'> & {
     className?: string;
     /** Pass the item supplied by ItemsList so selection can match it by item.value. */
     value: Item;
 } & StyleProps;
 /** Required selectable row inside ItemsList. Pass the complete item object as value, with ItemText and ItemIndicator inside. Selection, highlighting, and keyboard behavior are built in. */
-export declare function Item<Item extends ItemShape = ItemShape>({ disableStyle, className, style, ...props }: ItemProps<Item>): import("react").JSX.Element;
+export declare function Item<Item extends ItemShape = ItemShape>({ disableStyle, className, ...props }: ItemProps<Item>): import("react").JSX.Element;
 export type PopupProps = Omit<ComponentPropsWithRef<typeof BaseCombobox.Popup>, 'className'> & {
     className?: string;
 } & Pick<BaseCombobox.Portal.Props, 'container' | 'keepMounted'> & Pick<BaseCombobox.Positioner.Props, 'anchor' | 'positionMethod' | 'alignOffset' | 'collisionBoundary' | 'collisionPadding' | 'sticky' | 'arrowPadding' | 'disableAnchorTracking' | 'collisionAvoidance'> & {
@@ -312,20 +312,6 @@ export type PopupProps = Omit<ComponentPropsWithRef<typeof BaseCombobox.Popup>,
 export declare function Popup({ disableStyle, container, keepMounted, anchor, positionMethod, side, sideOffset, align, alignOffset, collisionBoundary, collisionPadding, sticky, arrowPadding, disableAnchorTracking, collisionAvoidance, className, style, ...props }: PopupProps): import("react").JSX.Element;
 /** Optional decorative popup arrow. Place inside Popup; the SVG and direction handling are supplied. No children needed. */
 export declare const Arrow: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").SVGProps<SVGSVGElement>, "children" | "dangerouslySetInnerHTML"> & StyleProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
-/** Behavior only: turns its single child element into the popup trigger. Adds no preset styling and has no disableStyle prop. Use an accessible button child; pass className to the child for its appearance. */
-export declare const PopupOpenHandler: import("react").ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react").ComboboxTriggerProps, "children" | "className" | "render"> & {
-    /** Additional classes forwarded to the trigger element. This handler has no preset styles. */
-    className?: string;
-    /** Single element to receive the behavior. Use a button with an accessible name. */
-    children: ReactElement;
-}, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
-/** Behavior only: turns its single child element into a removal control for the surrounding Chip. Adds no preset styling and has no disableStyle prop. Use an accessible button child. */
-export declare const ChipRemoveHandler: import("react").ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react").ComboboxChipRemoveProps, "children" | "className" | "render"> & {
-    /** Additional classes forwarded to the removal element. This handler has no preset styles. */
-    className?: string;
-    /** Single element to receive the behavior. Use a button with an accessible name. */
-    children: ReactElement;
-}, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
 /** Optional input adornment container inside InputGroup. Wraps icons, text, or buttons without adding trigger behavior. */
 export declare const Addon: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & {
     /** Preset adornment appearance. Does not add button behavior. @default 'normal' */
@@ -346,7 +332,7 @@ export declare const AddonButton: import("react").ForwardRefExoticComponent<Omit
     /** Disables this button. Root disabled or readOnly also disables it automatically. */
     disabled?: ComponentProps<"button">["disabled"];
 } & StyleProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
-/** Input control wrapper. Place Input (or ChipsList containing Input) and optional Addon controls inside. Root tone controls its preset validation border. */
+/** Input control wrapper. Place Input (or ChipsList containing Input) and optional Addon controls inside. Root validation controls its preset validation border. */
 export declare const InputGroup: import("react").ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react").ComboboxInputGroupProps, "className"> & {
     className?: string;
 } & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
@@ -384,12 +370,15 @@ export declare const ItemText: import("react").ForwardRefExoticComponent<Omit<im
 export declare const AddonText: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLSpanElement> & import("react").HTMLAttributes<HTMLSpanElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLSpanElement>>;
 /** Text content inside Empty. Supply your empty-result message; Empty handles its visibility automatically. */
 export declare const EmptyText: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
-/** Optional supporting text. Supply its content; it does not connect itself to the input with aria-describedby. Use matching id and Input aria-describedby when needed. */
+/** Optional supporting text. Supply its content; it describes the input to screen readers automatically. */
 export declare const Description: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
-/** Optional alert message. You control when it is rendered and its contents; tone does not validate or show this message automatically. */
-export declare const Error: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
-/** Optional success status. You control when it is rendered and its contents; tone does not show this message automatically. */
-export declare const Success: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & StyleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+type MessageProps = Omit<ComponentProps<'div'>, 'children'> & StyleProps & {
+    children?: ValidationMessageChildren;
+};
+/** Shows itself only while Root's validation is `'error'`: with no children it shows the message from `['error', message]`, a function children formats that message, and other children replace it. */
+export declare const Error: import("react").ForwardRefExoticComponent<Omit<MessageProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/** Shows itself only while Root's validation is `'success'`: with no children it shows the message from `['success', message]`, a function children formats that message, and other children replace it. */
+export declare const Success: import("react").ForwardRefExoticComponent<Omit<MessageProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 /** Built-in decorative open-button icon. Place inside AddonOpenButton; no children needed. Defaults to strokeWidth 1.5. */
 export declare const AddonOpenButtonIcon: import("react").ForwardRefExoticComponent<Omit<Omit<SVGIconProps, "strokeWidth"> & {
     /** @default 1.5 */
@@ -424,4 +413,3 @@ export declare const LoadingText: import("react").ForwardRefExoticComponent<Omit
 /** Built-in decorative spinner for Loading. No children needed; you control when it is rendered. */
 export declare const LoadingIcon: import("react").ForwardRefExoticComponent<Omit<SVGIconProps & StyleProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/components/combobox/index.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
-import { Check, ChevronsUpDown, LoaderCircle, X } from 'lucide-react';
-import { cloneElement, createContext, forwardRef, useContext, useId, useState, } from 'react';
+import { Check, ChevronsUpDown, LoaderCircle, X } from "../../utils/icons.js";
+import { cloneElement, createContext, forwardRef, useContext, useEffect, useId, useState } from 'react';
 import { twMerge } from 'tailwind-merge';
-import { ToneProvider, useToneContext } from "../../utils/Tone.js";
+import { readValidation, validationAttributes, validationMessageContent } from "../../utils/Validation.js";
 /**
  * Searchable selection using Base UI's built-in filtering and keyboard handling.
  * Does not render an element. Keep all parts inside Root.
@@ -157,21 +157,28 @@ import { ToneProvider, useToneContext } from "../../utils/Tone.js";
  *   <Combobox.AddonOpenButtonIcon />
  * </Combobox.AddonOpenButton>
  */
-export function Root({ children, id, tone = 'neutral', open, defaultOpen = false, onOpenChange, onItemHighlighted, ...props }) {
+export function Root({ children, id, validation, defaultOpen = false, onOpenChange, ...props }) {
+    //1. Tracking the open state even when uncontrolled, so parts can carry data-open
+    const [openInternalState, setOpenInternalState] = useState(defaultOpen);
+    //2. Holding the ids of Description, Error and Success, so Input announces them to screen readers through aria-describedby
+    const [describedByIds, setDescribedByIds] = useState([]);
+    //3. Sharing everything with the parts
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    const [openInternalState, setOpenInternalState] = useState(defaultOpen);
-    return (_jsx(BaseCombobox.Root, { ...props, id: inputId, open: open, defaultOpen: defaultOpen, onItemHighlighted: onItemHighlighted, isItemEqualToValue: (item, selected) => item.value === selected.value, onOpenChange: (nextOpen, details) => {
+    return (_jsx(BaseCombobox.Root, { ...props, id: inputId, defaultOpen: defaultOpen, isItemEqualToValue: (item, selected) => item.value === selected.value, onOpenChange: (nextOpen, details) => {
             onOpenChange?.(nextOpen, details);
             if (!details.isCanceled)
                 setOpenInternalState(nextOpen);
         }, children: _jsx(ComboboxContext.Provider, { value: {
                 inputId,
-                open: open ?? openInternalState,
+                open: props.open ?? openInternalState,
                 disabled: props.disabled ?? false,
                 readOnly: props.readOnly ?? false,
                 required: props.required ?? false,
-            }, children: _jsx(ToneProvider, { value: tone, children: children }) }) }));
+                validation: readValidation(validation),
+                describedByIds,
+                setDescribedByIds,
+            }, children: children }) }));
 }
 /** Use for the standard stacked layout, or omit when supplying your own layout. */
 export const Container = /* @__PURE__ */ forwardRef(function Container({ disableStyle, className, ...props }, ref) {
@@ -179,15 +186,15 @@ export const Container = /* @__PURE__ */ forwardRef(function Container({ disable
 });
 /** Labels the input automatically using Root's id. Supply the visible label as children; no htmlFor needed. */
 export const Label = /* @__PURE__ */ forwardRef(function Label({ disableStyle, className, ...props }, ref) {
-    const { inputId } = useComboboxContext();
+    const context = useComboboxContext();
     const attributes = usePartAttributes();
-    return (_jsx("label", { ...attributes, ...props, ref: ref, htmlFor: inputId, "data-component": "combobox-label", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+    return (_jsx("label", { ...attributes, ...props, ref: ref, htmlFor: context.inputId, "data-component": "combobox-label", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
 /** Search input with built-in filtering and selected-label display. Its id is managed by Root. Inside ChipsList, the preset automatically uses the compact chip-input sizing. */
-export const Input = /* @__PURE__ */ forwardRef(function Input({ disableStyle, className, ...props }, ref) {
-    const { inputId } = useComboboxContext();
+export const Input = /* @__PURE__ */ forwardRef(function Input({ disableStyle, className, 'aria-describedby': describedBy, ...props }, ref) {
+    const context = useComboboxContext();
     const inChips = useContext(ChipsContext);
-    return (_jsx(BaseCombobox.Input, { ...props, ref: ref, id: inputId, "data-component": "combobox-input", "data-style-disabled": disableStyle ? '' : undefined, "data-in-chips": inChips ? '' : undefined, className: className }));
+    return (_jsx(BaseCombobox.Input, { "aria-invalid": context.validation.state === 'error' || undefined, "aria-describedby": [describedBy, ...context.describedByIds].filter(Boolean).join(' ') || undefined, ...props, ref: ref, id: context.inputId, "data-component": "combobox-input", "data-style-disabled": disableStyle ? '' : undefined, "data-in-chips": inChips ? '' : undefined, className: className }));
 });
 function ChipsListInner({ disableStyle, children, className, ...props }, ref) {
     return (_jsx(BaseCombobox.Value, { children: (selected) => (_jsx(ChipsContext.Provider, { value: true, children: _jsx(BaseCombobox.Chips, { ...props, ref: ref, "data-slot": "chips-list", "data-component": "combobox-chipslist", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: typeof children === 'function' ? children(selected) : children }) })) }));
@@ -222,24 +229,24 @@ export const ChipsList = /* @__PURE__ */ forwardRef(ChipsListInner);
 /** Reads Base UI selection without rendering its own element. Use its children callback only when you need a custom selection display; Input already displays the selected label automatically. */
 export const Value = BaseCombobox.Value;
 /** Required listbox and scroll viewport inside Popup. Place GroupsList inside it. Owns keyboard/listbox semantics; do not nest another listbox primitive. */
-export const ScrollArea = /* @__PURE__ */ forwardRef(function ScrollArea({ disableStyle, className, style, ...props }, ref) {
-    return (_jsx(BaseCombobox.List, { ...props, ref: ref, style: style, "data-component": "combobox-scrollarea", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export const ScrollArea = /* @__PURE__ */ forwardRef(function ScrollArea({ disableStyle, className, ...props }, ref) {
+    return (_jsx(BaseCombobox.List, { ...props, ref: ref, "data-component": "combobox-scrollarea", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
 /** Required groups container inside ScrollArea. A children callback receives each automatically filtered group; do not filter or map the original groups again. Manually annotate group with Combobox.GroupType<typeof rootItems>, using the exact items variable passed to Root. */
-export function GroupsList({ disableStyle, children, className, style, ...props }) {
-    return (_jsx("div", { ...props, style: style, "data-component": "combobox-groupslist", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: typeof children === 'function' ? (_jsx(BaseCombobox.Collection, { children: children })) : (children) }));
+export function GroupsList({ disableStyle, children, className, ...props }) {
+    return (_jsx("div", { ...props, "data-component": "combobox-groupslist", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: typeof children === 'function' ? (_jsx(BaseCombobox.Collection, { children: children })) : (children) }));
 }
 /** Required items container inside Group. A children callback receives the filtered items belonging to that Group; do not repeat filtering yourself. Manually annotate item with Combobox.ItemType<typeof rootItems>, using the exact items variable passed to Root. */
-export function ItemsList({ disableStyle, children, className, style, ...props }) {
-    return (_jsx("div", { ...props, style: style, "data-component": "combobox-itemslist", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: typeof children === 'function' ? (_jsx(BaseCombobox.Collection, { children: children })) : (children) }));
+export function ItemsList({ disableStyle, children, className, ...props }) {
+    return (_jsx("div", { ...props, "data-component": "combobox-itemslist", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: typeof children === 'function' ? (_jsx(BaseCombobox.Collection, { children: children })) : (children) }));
 }
 /** Required wrapper around ItemsList, even for a visually flat list. Pass group.items. A GroupLabel is optional; omit it when the group has an empty label. */
-export function Group({ disableStyle, className, style, ...props }) {
-    return (_jsx(BaseCombobox.Group, { ...props, style: style, "data-component": "combobox-group", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export function Group({ disableStyle, className, ...props }) {
+    return (_jsx(BaseCombobox.Group, { ...props, "data-component": "combobox-group", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 }
 /** Required selectable row inside ItemsList. Pass the complete item object as value, with ItemText and ItemIndicator inside. Selection, highlighting, and keyboard behavior are built in. */
-export function Item({ disableStyle, className, style, ...props }) {
-    return (_jsx(BaseCombobox.Item, { ...props, style: style, "data-component": "combobox-item", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export function Item({ disableStyle, className, ...props }) {
+    return (_jsx(BaseCombobox.Item, { ...props, "data-component": "combobox-item", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 }
 /** Popup containing Empty, an optional Loading message, and ScrollArea, in that order. Already includes the portal and positioner: do not add either yourself. Defaults to bottom/start with a 5px gap. Core available-space and anchor-width inline styles stay active when preset styling is disabled. */
 export function Popup({ disableStyle, container, keepMounted, anchor, positionMethod, side = 'bottom', sideOffset = 5, align = 'start', alignOffset, collisionBoundary, collisionPadding, sticky, arrowPadding, disableAnchorTracking, collisionAvoidance, className, style, ...props }) {
@@ -255,14 +262,6 @@ export function Popup({ disableStyle, container, keepMounted, anchor, positionMe
 export const Arrow = /* @__PURE__ */ forwardRef(function Arrow({ disableStyle, className, style, ...props }, ref) {
     return (_jsxs(BaseCombobox.Arrow, { style: style, render: _jsx("svg", { ...props, ref: ref, "aria-hidden": true, width: "20", height: "10", viewBox: "0 0 20 10" }), "data-component": "combobox-arrow", "data-style-disabled": disableStyle ? '' : undefined, className: className, children: [_jsx("path", { d: "M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z", "data-component": "combobox-arrow-1" }), _jsx("path", { d: "M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z", "data-component": "combobox-arrow-2" }), _jsx("path", { d: "M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z", "data-component": "combobox-arrow-3" })] }));
 });
-/** Behavior only: turns its single child element into the popup trigger. Adds no preset styling and has no disableStyle prop. Use an accessible button child; pass className to the child for its appearance. */
-export const PopupOpenHandler = /* @__PURE__ */ forwardRef(function PopupOpenHandler({ children, ...props }, ref) {
-    return _jsx(BaseCombobox.Trigger, { ...props, ref: ref, render: children });
-});
-/** Behavior only: turns its single child element into a removal control for the surrounding Chip. Adds no preset styling and has no disableStyle prop. Use an accessible button child. */
-export const ChipRemoveHandler = /* @__PURE__ */ forwardRef(function ChipRemoveHandler({ children, ...props }, ref) {
-    return _jsx(BaseCombobox.ChipRemove, { ...props, ref: ref, render: children });
-});
 /** Optional input adornment container inside InputGroup. Wraps icons, text, or buttons without adding trigger behavior. */
 export const Addon = /* @__PURE__ */ forwardRef(function Addon({ disableStyle, variant = 'normal', className, ...props }, ref) {
     return (_jsx("div", { ...props, ref: ref, "data-variant": variant, "data-component": "combobox-addon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
@@ -287,10 +286,10 @@ export const AddonButton = /* @__PURE__ */ forwardRef(function AddonButton({ dis
     const attributes = usePartAttributes();
     return (_jsx("button", { ...attributes, ...props, ref: ref, type: type, disabled: disabled || context.disabled || context.readOnly, "data-component": "combobox-addonbutton", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
-/** Input control wrapper. Place Input (or ChipsList containing Input) and optional Addon controls inside. Root tone controls its preset validation border. */
+/** Input control wrapper. Place Input (or ChipsList containing Input) and optional Addon controls inside. Root validation controls its preset validation border. */
 export const InputGroup = /* @__PURE__ */ forwardRef(function InputGroup({ disableStyle, className, ...props }, ref) {
-    const tone = useToneContext();
-    return (_jsx(BaseCombobox.InputGroup, { "data-tone": tone, ...props, ref: ref, "data-component": "combobox-inputgroup", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+    const attributes = usePartAttributes();
+    return (_jsx(BaseCombobox.InputGroup, { "data-validation": attributes['data-validation'], ...props, ref: ref, "data-component": "combobox-inputgroup", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
 /** Displays one selected item inside ChipsList. Keep chips in selected-item order so Base UI can remove the matching item. Supply the item label and an optional removal control. */
 export const Chip = /* @__PURE__ */ forwardRef(function Chip({ disableStyle, className, ...props }, ref) {
@@ -335,40 +334,54 @@ export const EmptyText = /* @__PURE__ */ forwardRef(function EmptyText({ disable
     const attributes = usePartAttributes();
     return (_jsx("div", { ...attributes, ...props, ref: ref, "data-component": "combobox-emptytext", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
-/** Optional supporting text. Supply its content; it does not connect itself to the input with aria-describedby. Use matching id and Input aria-describedby when needed. */
-export const Description = /* @__PURE__ */ forwardRef(function Description({ disableStyle, className, ...props }, ref) {
+/** Optional supporting text. Supply its content; it describes the input to screen readers automatically. */
+export const Description = /* @__PURE__ */ forwardRef(function Description({ disableStyle, className, id, ...props }, ref) {
+    const describedById = useDescribedById(id);
     const attributes = usePartAttributes();
-    return (_jsx("div", { ...attributes, ...props, ref: ref, "data-component": "combobox-description", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+    return (_jsx("div", { ...attributes, ...props, id: describedById, ref: ref, "data-component": "combobox-description", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
-/** Optional alert message. You control when it is rendered and its contents; tone does not validate or show this message automatically. */
-export const Error = /* @__PURE__ */ forwardRef(function Error({ disableStyle, className, ...props }, ref) {
-    const attributes = usePartAttributes();
-    return (_jsx("div", { role: "alert", "aria-atomic": "true", ...attributes, ...props, ref: ref, "data-component": "combobox-error", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+/** Shows itself only while Root's validation is `'error'`: with no children it shows the message from `['error', message]`, a function children formats that message, and other children replace it. */
+export const Error = /* @__PURE__ */ forwardRef(function Error({ children, ...props }, ref) {
+    const context = useComboboxContext();
+    const content = validationMessageContent(context.validation, 'error', children);
+    if (content === undefined)
+        return null;
+    return _jsx(Message, { ...props, ref: ref, role: "alert", component: "combobox-error", children: content });
 });
-/** Optional success status. You control when it is rendered and its contents; tone does not show this message automatically. */
-export const Success = /* @__PURE__ */ forwardRef(function Success({ disableStyle, className, ...props }, ref) {
+/** Shows itself only while Root's validation is `'success'`: with no children it shows the message from `['success', message]`, a function children formats that message, and other children replace it. */
+export const Success = /* @__PURE__ */ forwardRef(function Success({ children, ...props }, ref) {
+    const context = useComboboxContext();
+    const content = validationMessageContent(context.validation, 'success', children);
+    if (content === undefined)
+        return null;
+    return _jsx(Message, { ...props, ref: ref, role: "status", component: "combobox-success", children: content });
+});
+// The shared body of Error and Success, mounted only while they show, so only visible messages describe the input
+const Message = /* @__PURE__ */ forwardRef(function Message({ disableStyle, className, id, component, ...props }, ref) {
+    const describedById = useDescribedById(id);
     const attributes = usePartAttributes();
-    return (_jsx("div", { role: "status", "aria-atomic": "true", ...attributes, ...props, ref: ref, "data-component": "combobox-success", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+    return _jsx("div", { "aria-atomic": "true", ...attributes, ...props, id: describedById, ref: ref, "data-component": component, "data-style-disabled": disableStyle ? '' : undefined, className: className });
 });
 /** Built-in decorative open-button icon. Place inside AddonOpenButton; no children needed. Defaults to strokeWidth 1.5. */
-export const AddonOpenButtonIcon = /* @__PURE__ */ forwardRef(function AddonOpenButtonIcon({ disableStyle, className, strokeWidth = 1.5, ...props }, ref) {
-    const attributes = usePartAttributes();
-    return (_jsx(ChevronsUpDown, { ...attributes, "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": "combobox-addonopenbuttonicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export const AddonOpenButtonIcon = /* @__PURE__ */ forwardRef(function AddonOpenButtonIcon(props, ref) {
+    return _jsx(BuiltInIcon, { ...props, ref: ref, icon: ChevronsUpDown, component: "combobox-addonopenbuttonicon" });
 });
 /** Built-in decorative clear icon. Place inside AddonClearButton; no children needed. Defaults to strokeWidth 1.5. */
-export const AddonClearButtonIcon = /* @__PURE__ */ forwardRef(function AddonClearButtonIcon({ disableStyle, className, strokeWidth = 1.5, ...props }, ref) {
-    const attributes = usePartAttributes();
-    return (_jsx(X, { ...attributes, "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": "combobox-addonclearbuttonicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export const AddonClearButtonIcon = /* @__PURE__ */ forwardRef(function AddonClearButtonIcon(props, ref) {
+    return _jsx(BuiltInIcon, { ...props, ref: ref, icon: X, component: "combobox-addonclearbuttonicon" });
 });
 /** Built-in decorative removal icon. Place inside ChipRemoveButton; no children needed. Defaults to strokeWidth 1.5. */
-export const ChipRemoveButtonIcon = /* @__PURE__ */ forwardRef(function ChipRemoveButtonIcon({ disableStyle, className, strokeWidth = 1.5, ...props }, ref) {
-    const attributes = usePartAttributes();
-    return (_jsx(X, { ...attributes, "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": "combobox-chipremovebuttonicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export const ChipRemoveButtonIcon = /* @__PURE__ */ forwardRef(function ChipRemoveButtonIcon(props, ref) {
+    return _jsx(BuiltInIcon, { ...props, ref: ref, icon: X, component: "combobox-chipremovebuttonicon" });
 });
 /** Optional spinner inside Addon. Does not detect requests: you decide when to render it. Defaults to strokeWidth 1.5. */
-export const AddonLoadingIcon = /* @__PURE__ */ forwardRef(function AddonLoadingIcon({ disableStyle, className, strokeWidth = 1.5, ...props }, ref) {
+export const AddonLoadingIcon = /* @__PURE__ */ forwardRef(function AddonLoadingIcon(props, ref) {
+    return _jsx(BuiltInIcon, { ...props, ref: ref, icon: LoaderCircle, component: "combobox-addonloadingicon" });
+});
+// The shared body of the built-in decorative icons above, which only differ by their icon and component name
+const BuiltInIcon = /* @__PURE__ */ forwardRef(function BuiltInIcon({ disableStyle, className, strokeWidth = 1.5, icon: Icon, component, ...props }, ref) {
     const attributes = usePartAttributes();
-    return (_jsx(LoaderCircle, { ...attributes, "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": "combobox-addonloadingicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+    return _jsx(Icon, { ...attributes, "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": component, "data-style-disabled": disableStyle ? '' : undefined, className: className });
 });
 /** Required selection indicator inside Item. Visibility is automatic and a checkmark is supplied: no children or selection condition needed. Pass children only to replace the built-in checkmark. */
 export const ItemIndicator = /* @__PURE__ */ forwardRef(function ItemIndicator({ disableStyle, children, keepMounted, ...props }, ref) {
@@ -391,11 +404,11 @@ export const LoadingText = /* @__PURE__ */ forwardRef(function LoadingText({ dis
     return (_jsx("div", { ...props, ref: ref, "data-component": "combobox-loadingtext", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
 /** Built-in decorative spinner for Loading. No children needed; you control when it is rendered. */
-export const LoadingIcon = /* @__PURE__ */ forwardRef(function LoadingIcon({ disableStyle, className, ...props }, ref) {
-    return (_jsx(LoaderCircle, { "aria-hidden": true, strokeWidth: undefined, ...props, ref: ref, "data-component": "combobox-loadingicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
+export const LoadingIcon = /* @__PURE__ */ forwardRef(function LoadingIcon({ disableStyle, className, strokeWidth = 2, ...props }, ref) {
+    return (_jsx(LoaderCircle, { "aria-hidden": true, ...props, ref: ref, strokeWidth: strokeWidth, "data-component": "combobox-loadingicon", "data-style-disabled": disableStyle ? '' : undefined, className: className }));
 });
-const ComboboxContext = 
-/* @__PURE__ */ createContext(null);
+const ComboboxContext = /* @__PURE__ */ createContext(null);
+// Telling Input it sits inside ChipsList, so the preset uses the compact chip-input sizing
 const ChipsContext = /* @__PURE__ */ createContext(false);
 function useComboboxContext() {
     const context = useContext(ComboboxContext);
@@ -403,15 +416,25 @@ function useComboboxContext() {
         throw new globalThis.Error('Combobox parts must be inside Combobox.Root');
     return context;
 }
+// The state attributes every part carries, so presets can style any part from Root's state
 function usePartAttributes() {
-    const { open, disabled, readOnly, required } = useComboboxContext();
-    const tone = useToneContext();
+    const context = useComboboxContext();
     return {
-        'data-open': open ? '' : undefined,
-        'data-disabled': disabled ? '' : undefined,
-        'data-readonly': readOnly ? '' : undefined,
-        'data-required': required ? '' : undefined,
-        'data-tone': tone,
+        'data-open': context.open ? '' : undefined,
+        'data-disabled': context.disabled ? '' : undefined,
+        'data-readonly': context.readOnly ? '' : undefined,
+        'data-required': context.required ? '' : undefined,
+        ...validationAttributes(context.validation),
     };
 }
-//# sourceMappingURL=index.js.map
+// Registering a part's id in Input's aria-describedby while the part is mounted
+function useDescribedById(id) {
+    const context = useComboboxContext();
+    const generatedId = useId();
+    const describedById = id ?? generatedId;
+    useEffect(() => {
+        context.setDescribedByIds((current) => [...current, describedById]);
+        return () => context.setDescribedByIds((current) => current.filter((currentId) => currentId !== describedById));
+    }, [describedById, context.setDescribedByIds]);
+    return describedById;
+}

package/dist/components/datepicker/index.d.ts

@@ -1,4 +1,5 @@
 import type { StyleProps } from '../../types/Style.ts';
+import type { AsChildProps } from '../../utils/asChild.ts';
 import type { DatePickerProps } from 'react-aria-components/DatePicker';
 import type { DateRangePickerProps } from 'react-aria-components/DateRangePicker';
 import { Label as AriaLabel } from 'react-aria-components/Label';
@@ -16,6 +17,8 @@ import { FieldError } from 'react-aria-components/FieldError';
 import type { CalendarDate } from '@internationalized/date';
 import type { ComponentProps, ReactElement, ReactNode } from 'react';
 import type { SVGIconProps } from '../../types/Icon.ts';
+import type { Validation } from '../../types/Validation.ts';
+import type { ValidationMessageChildren } from '../../utils/Validation.ts';
 type DateRange = {
     start: string;
     end: string;
@@ -35,8 +38,6 @@ type SharedRootProps = {
     readOnly?: DatePickerProps<CalendarDate>['isReadOnly'];
     /** Require a date when validating a surrounding form. */
     required?: DatePickerProps<CalendarDate>['isRequired'];
-    /** Mark the picker invalid for accessibility and validation; use tone for a separate visual tone. */
-    invalid?: DatePickerProps<CalendarDate>['isInvalid'];
     /** Control the popup from application state. Omit to let trigger interactions manage it. */
     open?: DatePickerProps<CalendarDate>['isOpen'];
     /** Prevent selection before this ISO calendar date (YYYY-MM-DD). Omit for no lower limit. */
@@ -47,8 +48,11 @@ type SharedRootProps = {
     placeholderValue?: string | null;
     /** Choose date formatting and language. Omit to use the inherited application locale. */
     locale?: string;
-    /** Choose the visual tone. This does not validate data or show/hide feedback messages. */
-    tone?: 'neutral' | 'valid' | 'invalid';
+    /**
+     * The picker's validation state, with an optional message: `'error'` marks it invalid, `['error', 'Pick a later date']` also shows that message in Error. Same for `'success'` and Success.
+     * Omit it to keep only the picker's own validation, like a required or out-of-range date.
+     */
+    validation?: Validation;
 };
 type SingleRootProps = Pick<DatePickerProps<CalendarDate>, CoreKeys | 'name' | 'autoComplete'> & SharedRootProps & {
     /** Use range for a start/end selection; single is the default. Choose the corresponding field composition. */
@@ -200,17 +204,8 @@ export declare function AddonOpenButtonIcon({ disableStyle, children, className,
     /** Omit for the supplied default icon; pass a child only to replace it. */
     children?: ReactElement<SVGIconProps>;
 }) & StyleProps): ReactElement<SVGIconProps, string | import("react").JSXElementConstructor<any>>;
-/** Behavior only: give your child control this action. Style the child itself; this wrapper has no preset appearance or disableStyle prop. */
-export declare function AddonOpenHandler({ children, isDisabled, ...props }: Omit<StyledButtonProps, 'children' | 'render'> & {
-    /** Supply your own accessible control. It receives the behavior; its own className owns the appearance. */
-    children: ReactElement<ComponentProps<'button'>>;
-}): import("react").JSX.Element;
-export declare function OpenButton({ disableStyle, className, isDisabled, ...props }: StyledButtonProps & StyleProps): import("react").JSX.Element;
-/** Behavior only: give your child control this action. Style the child itself; this wrapper has no preset appearance or disableStyle prop. */
-export declare function OpenHandler({ children, isDisabled, ...props }: Omit<StyledButtonProps, 'children' | 'render'> & {
-    /** Supply your own accessible control. It receives the behavior; its own className owns the appearance. */
-    children: ReactElement<ComponentProps<'button'>>;
-}): import("react").JSX.Element;
+/** Opens the calendar popup. Pass asChild to give this behavior to your own button, like a "Choose appointment" Button; it keeps the state data attributes but none of this part's styling. */
+export declare function OpenButton({ asChild, disableStyle, isDisabled, children, ...props }: StyledButtonProps & AsChildProps & StyleProps): import("react").JSX.Element;
 /** Formats the selected date or range automatically. Omit children for the usual display; supply children only to replace it. Placeholder appears before selection. */
 export declare function OpenButtonValue({ disableStyle, children, placeholder, className, ...props }: (ComponentProps<'span'> & {
     /** Shown before a date is selected. Omit children to keep the automatic formatted date display. */
@@ -226,7 +221,7 @@ export type PopupProps = Omit<PopoverProps, 'className' | 'style' | 'render' | '
     style?: ComponentProps<'div'>['style'];
 } & StyleProps;
 /** Use the same calendar composition for both trigger choices. Opening and focus management are handled by the picker; do not add your own popup visibility condition. */
-export declare const Popup: import("react").ForwardRefExoticComponent<Omit<PopoverProps, "slot" | "style" | "className" | "render" | "onOpenChange" | "defaultOpen" | "isOpen" | "trigger"> & {
+export declare const Popup: import("react").ForwardRefExoticComponent<Omit<PopoverProps, "className" | "slot" | "style" | "render" | "onOpenChange" | "defaultOpen" | "isOpen" | "trigger"> & {
     className?: string;
     style?: ComponentProps<"div">["style"];
 } & StyleProps & import("react").RefAttributes<HTMLElement>>;
@@ -268,16 +263,6 @@ export declare function Actions({ disableStyle, className, ...props }: Component
 export declare function ViewDateValue({ disableStyle, className, level, ...props }: (Omit<ComponentProps<'h2'>, 'children'> & Pick<ComponentProps<typeof Heading>, 'level'>) & StyleProps): import("react").JSX.Element;
 export declare function PreviousButton({ disableStyle, className, isDisabled, ...props }: StyledButtonProps & StyleProps): import("react").JSX.Element;
 export declare function NextButton({ disableStyle, className, isDisabled, ...props }: StyledButtonProps & StyleProps): import("react").JSX.Element;
-/** Behavior only: give your child control this action. Style the child itself; this wrapper has no preset appearance or disableStyle prop. */
-export declare function PreviousHandler({ children, isDisabled, ...props }: Omit<StyledButtonProps, 'children' | 'render'> & {
-    /** Supply your own accessible control. It receives the behavior; its own className owns the appearance. */
-    children: ReactElement<ComponentProps<'button'>>;
-}): import("react").JSX.Element;
-/** Behavior only: give your child control this action. Style the child itself; this wrapper has no preset appearance or disableStyle prop. */
-export declare function NextHandler({ children, isDisabled, ...props }: Omit<StyledButtonProps, 'children' | 'render'> & {
-    /** Supply your own accessible control. It receives the behavior; its own className owns the appearance. */
-    children: ReactElement<ComponentProps<'button'>>;
-}): import("react").JSX.Element;
 /** A default icon is supplied. Omit children for the usual case; pass an icon only to replace that visual. */
 export declare function PreviousButtonIcon({ disableStyle, children, className, ...props }: (Omit<SVGIconProps, 'children'> & {
     /** Omit for the supplied default icon; pass a child only to replace it. */
@@ -299,11 +284,13 @@ export declare function Table({ disableStyle, index, className, ...props }: (Omi
     index?: number;
 }) & StyleProps): import("react").JSX.Element;
 export declare function Description({ disableStyle, className, ...props }: Omit<ComponentProps<typeof Text>, 'slot' | 'render'> & StyleProps): import("react").JSX.Element;
-/** Keep mounted to let the picker render its validation error automatically. Omit children for the native error text; override only for a custom message. */
-export declare function Error({ disableStyle, className, ...props }: (Omit<ComponentProps<typeof FieldError>, 'className' | 'render'> & {
+/** Keep mounted: it shows while the picker is invalid. With no children it shows Root's message from `['error', message]`, or else the picker's own validation text, like a required or out-of-range date. A function children formats Root's message, and other children replace it. */
+export declare function Error({ disableStyle, className, children, ...props }: (Omit<ComponentProps<typeof FieldError>, 'className' | 'render' | 'children'> & {
     className?: string;
+    children?: ValidationMessageChildren;
 }) & StyleProps): import("react").JSX.Element;
-/** You decide when to show this feedback. Changing tone does not validate data or render the message for you. */
-export declare function Success({ disableStyle, className, ...props }: Omit<ComponentProps<typeof Text>, 'slot' | 'render'> & StyleProps): import("react").JSX.Element;
+/** Shows itself only while Root's validation is `'success'`: with no children it shows the message from `['success', message]`, a function children formats that message, and other children replace it. */
+export declare function Success({ disableStyle, className, children, ...props }: Omit<ComponentProps<typeof Text>, 'slot' | 'render' | 'children'> & {
+    children?: ValidationMessageChildren;
+} & StyleProps): import("react").JSX.Element | null;
 export {};
-//# sourceMappingURL=index.d.ts.map