cetec-design-system 2.2.2-next.0 → 2.3.7

package/dist/types/index.d.ts

@@ -7,14 +7,14 @@ import { ElementType } from 'react';
 import { HTMLProps } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { JSX as JSX_2 } from 'react';
-import { JSXElementConstructor } from 'react';
+import { KeyboardEventHandler } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { Placement } from '@floating-ui/react';
 import { Preset } from '@pandacss/dev';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RefObject } from 'react';
-import { SVGAttributes } from 'react';
 
 declare type AdvancedPseudos =
 | ":-moz-any()"
@@ -42,6 +42,12 @@ declare type AdvancedPseudos =
 | ":nth-of-type"
 | ":where";
 
+/**
+ * Numeric design-token sizes supported by the icon recipe. Non-numeric sizes
+ * do not have corresponding recipe variants.
+ */
+export declare type AllowedIconSizes = keyof typeof numericSizes;
+
 declare type AnimationToken = "spin" | "ping" | "pulse" | "bounce" | "skeletonWave"
 
 declare type AnySelector = `${string}&` | `&${string}` | `@${AtRuleType}${string}`
@@ -65,6 +71,8 @@ declare type AriaAttributes =
 declare type AspectRatioToken = "square" | "landscape" | "portrait" | "wide" | "ultrawide" | "golden"
 
 declare type AsProp<T extends ElementType> = {
+    /** Element or component rendered by the polymorphic component. */
+    /** @default "div" */
     as?: T;
 };
 
@@ -84,38 +92,199 @@ declare type AtRuleType = 'media' | 'layer' | 'container' | 'supports' | 'page'
 declare type AttributeSelector = `&${Pseudos | DataAttributes | AriaAttributes}`
 
 /**
- * Avatar component for displaying user or entity images with optional
- * presence and status indicators.
+ * Filters and selects one or more metadata-only `Option` values.
+ *
+ * Use controlled `value` and `onValueChange`, or initialize uncontrolled state
+ * with `defaultValue`. The input uses combobox semantics; arrow keys navigate,
+ * Enter selects, and Escape closes the listbox. Supply `aria-label` or
+ * `aria-labelledby` when no external label is associated with the input.
+ *
+ * @example
+ * ```tsx
+ * <Autocomplete defaultValue="active" aria-label="Status">
+ *   <Option value="active" label="Active" />
+ *   <Option value="archived" label="Archived" />
+ * </Autocomplete>
+ * ```
+ */
+export declare const Autocomplete: (props: AutocompleteProps) => JSX.Element;
+
+declare type AutocompleteBaseProps = Omit<BoxProps, keyof AutocompleteVariantProps | 'children' | 'defaultValue' | 'onChange' | 'value'> & AutocompleteVariantProps & {
+    /** Controlled text displayed in the input. */
+    inputValue?: string;
+    /** Initial input text when `inputValue` is not provided. */
+    defaultInputValue?: string;
+    /** Runs when typing, selection, or clearing changes the input text. */
+    onInputValueChange?: (value: string, reason: AutocompleteInputChangeReason) => void;
+    /**
+     * Runs when the input text changes.
+     *
+     * @deprecated Use `onInputValueChange`.
+     */
+    onInputChange?: (value: string, reason: AutocompleteInputChangeReason) => void;
+    /** Controlled listbox visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial listbox visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the listbox open or close. */
+    onOpenChange?: (open: boolean, reason: AutocompleteOpenChangeReason) => void;
+    /**
+     * Offers the current input as a selectable option when it has no exact
+     * match.
+     *
+     * @default false
+     */
+    allowCustomValue?: boolean;
+    /** Creates the visible label for a custom-value option. */
+    getCreateOptionLabel?: (inputValue: string) => string;
+    /**
+     * Maximum selected tokens shown while an unfocused multiple Autocomplete
+     * is collapsed. Negative values and `undefined` show every token.
+     */
+    limitTags?: number;
+    /**
+     * Input hint shown while no value is selected.
+     *
+     * @default 'Select...'
+     */
+    placeholder?: string;
+    /**
+     * Floating UI placement of the listbox relative to the control.
+     *
+     * @default 'bottom-start'
+     */
+    placement?: Placement;
+    /**
+     * Gap between the control and listbox, in pixels.
+     *
+     * @default 4
+     */
+    offset?: number;
+    /** Metadata-only `Option` children used to populate the listbox. */
+    children?: ReactNode;
+    /** Identifier for the combobox input. A generated identifier is used when omitted. */
+    id?: string;
+    /** Form field name used by hidden inputs for selected values. */
+    name?: string;
+    /** Prevents focus and interaction. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Allows focus and text selection while preventing value changes. */
+    readOnly?: boolean;
+    /** Applies error styling and `aria-invalid`. Overrides field context when provided. */
+    error?: boolean;
+    /** Applies valid styling to the control. */
+    valid?: boolean;
+    /** Applies invalid styling and `aria-invalid`. Overrides field context when provided. */
+    invalid?: boolean;
+    /** Spacing density used by listbox options. */
+    density?: MenuDensity;
+    /**
+     * Shows a loading indicator and replaces an empty list with `loadingText`.
+     *
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Shows `loadingText` after the current options during incremental loading.
+     *
+     * @default false
+     */
+    loadingMore?: boolean;
+    /** Indicates that scrolling can request another page of options. */
+    hasMore?: boolean;
+    /** Runs near the end of the list when more options are available. */
+    onLoadMore?: () => void;
+    /**
+     * Status content shown while options are loading.
+     *
+     * @default 'Loading options…'
+     */
+    loadingText?: ReactNode;
+    /**
+     * Status content shown when filtering produces no options.
+     *
+     * @default 'No options'
+     */
+    noOptionsText?: ReactNode;
+};
+
+/** User actions that can change the selected Autocomplete value. */
+export declare type AutocompleteChangeReason = 'select-option' | 'remove-option' | 'clear' | 'create-option';
+
+/** Actions that can change the text displayed in the Autocomplete input. */
+export declare type AutocompleteInputChangeReason = 'input' | 'selection' | 'clear';
+
+/** Interactions that can request an Autocomplete listbox visibility change. */
+export declare type AutocompleteOpenChangeReason = 'input' | 'focus' | 'keyboard' | 'selection' | 'escape' | 'outside-press';
+
+/** Props accepted by {@link Autocomplete}, discriminated by `multiple`. */
+export declare type AutocompleteProps<Multiple extends boolean = boolean> = Multiple extends true ? MultipleAutocompleteProps : Multiple extends false ? SingleAutocompleteProps : SingleAutocompleteProps | MultipleAutocompleteProps;
+
+/** Selected value shape for single- or multiple-selection `Autocomplete`. */
+export declare type AutocompleteValue<Multiple extends boolean = false> = Multiple extends true ? string[] : Multiple extends false ? string | null : string | string[] | null;
+
+declare interface AutocompleteVariant {
+    /**
+     * @default "md"
+     */
+    size: "sm" | "md" | "lg" | "xl"
+}
+
+declare type AutocompleteVariantProps = {
+    [key in keyof AutocompleteVariant]?: ConditionalValue<AutocompleteVariant[key]> | undefined
+}
+
+/**
+ * Represents a person or entity with an image and deterministic fallback.
+ *
+ * Presence and status indicators are visual only. Supply equivalent text when
+ * either state is meaningful to assistive technology.
+ *
+ * @example
+ * ```tsx
+ * <Avatar src="/people/ada.jpg" alt="Ada Lovelace" name="Ada Lovelace" />
+ * ```
  */
 export declare const Avatar: (props: AvatarProps) => JSX.Element;
 
+/** Presence states displayed at the bottom-right of an avatar. */
 declare type AvatarPresence = 'online' | 'busy' | 'offline' | 'focus';
 
-declare type AvatarProps = Omit<BoxProps, keyof AvatarVariantProps> & Omit<AvatarVariantProps, 'size' | 'shape'> & {
-    /** Image source URL */
+/** Props accepted by {@link Avatar}. */
+export declare type AvatarProps = Omit<BoxProps, keyof AvatarVariantProps> & Omit<AvatarVariantProps, 'size' | 'shape'> & {
+    /** Image URL. A failed or missing image falls back to custom content, initials, or a user icon. */
     src?: string;
-    /** Alt text for image */
+    /** Alternative text for the image. Use an empty string when nearby text already identifies the entity. */
+    /** @default "" */
     alt?: string;
-    /** Name for generating initials fallback */
+    /** Name used to generate first-and-last initials when no image is available. */
     name?: string;
-    /** Size of the avatar */
+    /** Visual size. An explicit value takes precedence over slot context. */
     size?: AvatarSize;
-    /** Shape of the avatar */
+    /** Outline shape of the avatar. */
+    /** @default "circle" */
     shape?: AvatarShape;
-    /** Presence indicator (bottom-right) */
+    /** Decorative presence indicator shown at the bottom-right. Provide equivalent text elsewhere when the state matters. */
     presence?: AvatarPresence;
-    /** Status indicator (top-right) */
+    /** Decorative status indicator shown at the top-right. Provide equivalent text elsewhere when the state matters. */
     status?: AvatarStatus;
-    /** Custom fallback content (overrides initials) */
+    /** Fallback content that takes precedence over generated initials and the default user icon. */
     fallback?: ReactNode;
-    /** Border color for the avatar */
+    /** CSS border color applied to the avatar root. */
     borderColor?: string;
 };
 
+/** Supported outline shapes for {@link Avatar}. */
 declare type AvatarShape = AvatarVariantProps['shape'];
 
+/** Supported visual sizes for {@link Avatar}. */
 declare type AvatarSize = NonNullable<AvatarVariantProps['size']>;
 
+/** Status states displayed at the top-right of an avatar. */
 declare type AvatarStatus = 'approved' | 'declined' | 'locked';
 
 declare interface AvatarVariant {
@@ -134,26 +303,36 @@ declare type AvatarVariantProps = {
 }
 
 /**
- * Badge component for displaying notification counts or status indicators.
+ * Displays a notification count or compact status indicator.
+ *
+ * Without `children`, the badge is standalone. With children, it positions the
+ * indicator at the anchor's top-right. Omitting `count` renders a dot. The
+ * badge does not announce updates by itself; add an accessible label or live
+ * region when the value conveys essential information.
  *
- * - Without children: renders as standalone badge
- * - With children: wraps content and positions badge at top-right
- * - Without count prop: shows as dot
- * - With count prop: shows the number (or "99+" if exceeds overflowCount)
+ * @example
+ * ```tsx
+ * <Badge count={3}><Icon name="bell" aria-label="Notifications" /></Badge>
+ * ```
  */
 export declare const Badge: (props: BadgeProps) => JSX.Element | null;
 
-declare type BadgeProps = Omit<BoxProps, keyof BadgeVariantProps> & Omit<BadgeVariantProps, 'standalone' | 'dot'> & {
-    /** Number to show in badge. If provided, switches to count mode. */
+/** Props accepted by {@link Badge}. */
+export declare type BadgeProps = Omit<BoxProps, keyof BadgeVariantProps> & Omit<BadgeVariantProps, 'standalone' | 'dot'> & {
+    /** Numeric content. Providing a value switches the badge from dot mode to count mode. */
     count?: number;
-    /** Show badge when count is zero. Default: false */
+    /** Keeps the indicator visible when `count` is zero. */
+    /** @default false */
     showZero?: boolean;
-    /** Max count to show. Displays "99+" when exceeded. Default: 99 */
+    /** Largest count shown directly; larger values render as `{overflowCount}+`. */
+    /** @default 99 */
     overflowCount?: number;
-    /** Color scheme of the badge. Default: 'danger' */
+    /** Semantic color treatment of the indicator. */
+    /** @default "danger" */
     variant?: BadgeVariantProps['variant'];
-    /** Content to wrap with the badge */
+    /** Content used as the positioning anchor. Without children, the badge is standalone. */
     children?: ReactNode;
+    /** Visual indicator size. An explicit value takes precedence over slot context. */
     size?: BadgeVariantProps['size'];
 };
 
@@ -199,13 +378,25 @@ declare type BorderToken = "default" | "bold" | "inverse" | "disabled" | "input"
 declare type BorderWidthToken = "0" | "1" | "2" | "4" | "8" | "16"
 
 /**
- * Our base polymorphic component, which provides the correct default props based on the rendered element type.
- * Note: in React 19+, ref is passed through as a prop, and onClick is inherited based on the element type.
+ * Renders a token-aware polymorphic foundation for design-system components.
+ *
+ * `Box` renders a `div` by default. Set `as` to use another semantic element or
+ * component; compatible native props and the React 19 `ref` prop follow that
+ * selection. Prefer a semantic component when one already expresses the
+ * intended behavior.
+ *
+ * @example
+ * ```tsx
+ * <Box as="section" p="16" aria-labelledby="summary-heading">
+ *   Summary content
+ * </Box>
+ * ```
  */
-export declare const Box: <T extends ElementType = "div">(props: BoxProps<T>) => ReactElement<any, string | JSXElementConstructor<any>>;
+export declare const Box: <T extends ElementType = "div">(props: BoxProps<T>) => JSX.Element;
 
 declare type BoxOwnProps = SystemStyleObject_2 & BoxVariantProps;
 
+/** Props accepted by {@link Box}, including Panda style and native element props. */
 export declare type BoxProps<T extends ElementType = ElementType> = PolymorphicComponentProps<T, BoxOwnProps>;
 
 declare interface BoxVariant {
@@ -216,9 +407,32 @@ declare type BoxVariantProps = {
     [key in keyof BoxVariant]?: ConditionalValue<BoxVariant[key]> | undefined
 }
 
+/**
+ * Displays the current navigation path as a semantic unordered list.
+ *
+ * Linked segments use {@link Link}; segments without `href` are rendered as
+ * plain text. Use page navigation instead when the hierarchy is not a path to
+ * the current location.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumbs
+ *   items={[
+ *     { id: 'home', label: 'Home', href: '/' },
+ *     { id: 'invoices', label: 'Invoices' },
+ *   ]}
+ * />
+ * ```
+ */
 export declare const Breadcrumbs: (props: BreadcrumbsProps) => JSX.Element;
 
-declare type BreadcrumbsProps = Omit<BoxProps, keyof BreadcrumbsVariantProps> & BreadcrumbsVariantProps & {
+/** Props for {@link Breadcrumbs}. */
+export declare type BreadcrumbsProps = Omit<BoxProps, keyof BreadcrumbsVariantProps> & BreadcrumbsVariantProps & {
+    /**
+     * Ordered path segments. A segment with `href` renders as a link; a segment
+     * without it renders as plain text, which is normally the current page.
+     * Keep the final segment non-linked when it represents the current page.
+     */
     items: {
         id: string;
         label: string;
@@ -234,9 +448,23 @@ declare type BreadcrumbsVariantProps = {
     [key in keyof BreadcrumbsVariant]?: ConditionalValue<BreadcrumbsVariant[key]> | undefined
 }
 
+/**
+ * Displays the largest currently matching design-system breakpoint.
+ *
+ * This is a development aid, not user-facing application content. It renders a
+ * colored `Tag` from `@media/base` through `@media/2xl` based on media-query
+ * hooks.
+ *
+ * @example
+ * ```tsx
+ * <BreakpointIndicator />
+ * ```
+ */
 export declare const BreakpointIndicator: (props: BreakpointIndicatorProps) => JSX.Element;
 
-declare type BreakpointIndicatorProps = Omit<BoxProps, keyof BreakpointIndicatorVariantProps> & BreakpointIndicatorVariantProps & {
+/** Props for {@link BreakpointIndicator}, a development breakpoint readout. */
+export declare type BreakpointIndicatorProps = Omit<BoxProps, keyof BreakpointIndicatorVariantProps> & BreakpointIndicatorVariantProps & {
+    /** Recipe variant for the indicator's visual treatment. */
     variant?: BreakpointIndicatorVariantProps['variant'];
 };
 
@@ -251,6 +479,7 @@ declare type BreakpointIndicatorVariantProps = {
     [key in keyof BreakpointIndicatorVariant]?: ConditionalValue<BreakpointIndicatorVariant[key]> | undefined
 }
 
+/** Key of a Cetec viewport breakpoint token. */
 declare type BreakpointKey = keyof typeof breakpoints;
 
 declare const breakpoints: {
@@ -264,20 +493,78 @@ declare const breakpoints: {
 
 declare type BreakpointToken = "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
 
+/**
+ * Performs an action or navigates to a location.
+ *
+ * Renders a native `button` by default, or an anchor when `href` is supplied.
+ * Use {@link IconButton} for actions represented only by an icon. In a
+ * `FormField` or slot context, explicitly supplied `size`, `error`, `invalid`,
+ * and `disabled` values take precedence over slot context, which takes
+ * precedence over field context. Its recipe defaults to the `standard` variant
+ * and `md` size.
+ *
+ * @example
+ * ```tsx
+ * <Button onClick={saveInvoice}>Save invoice</Button>
+ * ```
+ */
 export declare const Button: (props: ButtonProps) => JSX.Element;
 
-declare type ButtonProps = Omit<BoxProps, keyof ButtonVariantProps> & Omit<ButtonVariantProps, 'before' | 'after' | 'iconBefore' | 'iconAfter'> & {
+/**
+ * Props for {@link Button}. Extends {@link BoxProps} for layout and native
+ * element attributes while reserving the button recipe's visual variants.
+ */
+export declare type ButtonProps = Omit<BoxProps, keyof ButtonVariantProps | 'fontSize' | 'fontVariant'> & Omit<ButtonVariantProps, 'before' | 'after' | 'iconBefore' | 'iconAfter'> & {
+    /** Content rendered before the button label. Takes precedence over `iconBefore`. */
     before?: ReactNode;
+    /** Content rendered after the button label. Takes precedence over `iconAfter`. */
     after?: ReactNode;
+    /**
+     * Legacy icon name rendered before the label when `before` is not provided.
+     *
+     * @deprecated Use `before={<Icon name="..." aria-hidden />}`. This alias
+     * will be removed in a future major release.
+     */
     iconBefore?: IconNamesList;
+    /**
+     * Legacy icon name rendered after the label when `after` is not provided.
+     *
+     * @deprecated Use `after={<Icon name="..." aria-hidden />}`. This alias
+     * will be removed in a future major release.
+     */
     iconAfter?: IconNamesList;
+    /** When provided, renders an anchor instead of a native button. */
     href?: string;
+    /**
+     * Shows a centered spinner, hides the visible content, and sets
+     * `aria-busy`. Loading does not disable the control; set `disabled` when
+     * the action must not be available.
+     *
+     * @default false
+     */
     loading?: boolean;
+    /** Visible label and optional inline content for the action. */
     children: string | ReactNode;
+    /** Marks the control as having an error for styling and descendant slots. */
     error?: boolean;
+    /** Sets `aria-invalid` and marks the control invalid for styling and slots. */
     invalid?: boolean;
+    /**
+     * Disables a native button. For links, marks the anchor `aria-disabled` and
+     * prevents its default click navigation.
+     */
     disabled?: boolean;
+    /**
+     * Native button type; ignored when `href` causes the component to render an
+     * anchor.
+     *
+     * @default 'button'
+     */
     type?: 'submit' | 'reset' | 'button';
+    /** Font size forwarded to the button's text treatment. */
+    fontSize?: BoxProps['fontSize'];
+    /** Font variant forwarded to the button's text treatment. */
+    fontVariant?: BoxProps['fontVariant'];
 };
 
 declare interface ButtonVariant {
@@ -297,13 +584,91 @@ declare type ButtonVariantProps = {
     [key in keyof ButtonVariant]?: ConditionalValue<ButtonVariant[key]> | undefined
 }
 
+/**
+ * Displays an accessible day, month, and year selection grid.
+ *
+ * Use `value` and `onChange` for date selection. `viewDate` separately controls
+ * the visible month; omit it to let Calendar manage navigation internally.
+ * Dates outside `minDate` and `maxDate` remain visible but unavailable.
+ *
+ * @example
+ * ```tsx
+ * <Calendar value={date} onChange={setDate} label="Choose invoice date" />
+ * ```
+ */
+export declare const Calendar: (props: CalendarProps) => JSX.Element;
+
+/** Props for {@link Calendar}, including selection, bounds, and visible-month state. */
+export declare type CalendarProps = Omit<BoxProps, keyof CalendarVariantProps | 'children'> & Omit<CalendarVariantProps, 'type'> & {
+    /** Controlled selected date. */
+    value?: DateValue | null;
+    /** Runs when a selectable day is chosen. Calendar never clears its own value. */
+    onChange?: (value: DateValue) => void;
+    /**
+     * Range-selection endpoints, for DateRangeMenu. Independent of `value` —
+     * a Calendar can show a range highlight (start/end fill + in-between
+     * tint) regardless of which month it's currently displaying, since a
+     * range's two endpoints may fall in months neither calendar is showing.
+     */
+    rangeStart?: DateValue | null;
+    /** End of the optional visual range highlight. */
+    rangeEnd?: DateValue | null;
+    /** Earliest selectable date. */
+    minDate?: DateValue;
+    /** Latest selectable date. */
+    maxDate?: DateValue;
+    /** Controlled visible month and year. */
+    viewDate?: ViewDate;
+    /** Initial visible month and year when `viewDate` is not provided. Defaults to `value`, then today. */
+    defaultViewDate?: ViewDate;
+    /** Runs when month or year navigation requests a new visible month. */
+    onViewDateChange?: (viewDate: ViewDate) => void;
+    /** Prevents navigation and date selection. */
+    disabled?: boolean;
+    /** Accessible label prefix for the calendar grid. */
+    label?: string;
+};
+
+declare interface CalendarVariant {
+    /**
+     * @default "days"
+     */
+    type: "days" | "months" | "years"
+}
+
+declare type CalendarVariantProps = {
+    [key in keyof CalendarVariant]?: ConditionalValue<CalendarVariant[key]> | undefined
+}
+
+/**
+ * Groups related content in a visual container that can optionally navigate or
+ * act as a control.
+ *
+ * A card with `href` renders an anchor. A card that is otherwise interactive
+ * renders a button; a non-interactive card renders a `div`. Avoid nesting other
+ * interactive elements inside an interactive card.
+ *
+ * @example
+ * ```tsx
+ * <Card href="/orders/123">Order 123</Card>
+ * ```
+ */
 export declare const Card: (props: CardProps) => JSX.Element;
 
-declare type CardProps = Omit<BoxProps, keyof CardVariantProps> & CardVariantProps & {
+/** Props accepted by {@link Card}. */
+export declare type CardProps = Omit<BoxProps, keyof CardVariantProps> & CardVariantProps & {
+    /** Destination that makes the entire card render as a link. */
     href?: string;
+    /** Card content. */
     children?: string | ReactNode;
+    /** Marks the card as currently grabbed by a drag interaction. */
+    /** @default false */
     grabbed?: boolean;
+    /** Disables the rendered button or prevents link navigation. */
+    /** @default false */
     disabled?: boolean;
+    /** Forces button semantics and interactive styling without an `href`. */
+    /** @default false */
     interactive?: boolean;
 };
 
@@ -319,46 +684,89 @@ declare type CardVariantProps = {
     [key in keyof CardVariant]?: ConditionalValue<CardVariant[key]> | undefined
 }
 
+/**
+ * Panda CSS preset containing Cetec tokens, semantic tokens, recipes,
+ * utilities, patterns, global CSS, and conditions.
+ *
+ * Add this preset to a Panda configuration to generate styles that match the
+ * design system. It extends Panda's base preset while replacing its
+ * `dropShadow` utility and omitting the base `box` and `divider` patterns.
+ *
+ * @example
+ * ```ts
+ * import { cetecPreset } from 'cetec-design-system';
+ *
+ * export default defineConfig({ presets: [cetecPreset] });
+ * ```
+ */
 export declare const cetecPreset: Preset;
 
 /**
- * Checkbox supports both controlled and uncontrolled usage.
+ * A native checkbox control without a visible label.
+ *
+ * Use {@link CheckboxInput} when the checkbox needs a text label. Supply
+ * `checked` with `onChange` for controlled state, or `defaultChecked` for
+ * uncontrolled state. The primitive renders an `<input type="checkbox">`, so
+ * its `name` participates in native form submission. Associate it with a
+ * visible label using `id`; `indeterminate` is a visual mixed state only.
  *
  * @example
- * <Checkbox defaultChecked />
+ * ```tsx
+ * <Checkbox name="notifications" defaultChecked />
+ * ```
  *
  * @example
+ * ```tsx
  * const [checked, setChecked] = useState(false);
- * <Checkbox checked={checked} onChange={(e) => setChecked(e.target.checked)} />
+ * <Checkbox name="notifications" checked={checked} onChange={(event) => setChecked(event.target.checked)} />
+ * ```
  */
 export declare const Checkbox: (props: CheckboxProps) => JSX.Element;
 
 /**
- * Helper type for checkbox change events
+ * Native change event emitted by {@link Checkbox}.
  * @example
  * const handleChange: CheckboxChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type CheckboxChangeEvent = ChangeEvent<HTMLInputElement>;
+export declare type CheckboxChangeEvent = ChangeEvent<HTMLInputElement>;
 
 /**
- * Helper type for checkbox change handler functions
+ * Handler for a {@link Checkbox} native change event.
  * @example
  * const handleChange: CheckboxChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type CheckboxChangeHandler = (e: CheckboxChangeEvent) => void;
+export declare type CheckboxChangeHandler = (e: CheckboxChangeEvent) => void;
 
+/**
+ * A checkbox paired with a clickable label.
+ *
+ * Use this instead of {@link Checkbox} for ordinary labelled form controls.
+ * It generates an input ID when needed and connects it to the rendered label.
+ * Its checked-state and field-context behavior match `Checkbox`; explicit
+ * `disabled`, `error`, and `invalid` props override field context.
+ *
+ * @example
+ * ```tsx
+ * <CheckboxInput name="terms" defaultChecked>
+ *   I agree to the terms
+ * </CheckboxInput>
+ * ```
+ */
 export declare const CheckboxInput: (props: CheckboxInputProps) => JSX.Element;
 
-declare type CheckboxInputProps = Omit<BoxProps, keyof CheckboxInputVariantProps> & CheckboxInputVariantProps & {
-    name: string;
-    checked?: boolean;
+/** Props for {@link CheckboxInput}, a labelled {@link Checkbox}. */
+export declare type CheckboxInputProps = Omit<BoxProps, keyof CheckboxInputVariantProps> & CheckboxInputVariantProps & {
+    /** Form field name submitted when checked. */ name: string;
+    /** Controlled checked state. Pair with `onChange`; do not combine with `defaultChecked`. */ checked?: boolean;
+    /** Initial uncontrolled checked state; updates after mount are ignored. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: CheckboxChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    children?: string | ReactNode;
-    disabled?: boolean;
+    /** Runs when the contained native checkbox changes. */ onChange?: CheckboxChangeHandler;
+    /** Input ID. When omitted, a stable React ID is generated for the label association. */ id?: string;
+    /** Applies error styling to the checkbox and overrides field context. */ error?: boolean;
+    /** Marks the checkbox invalid and overrides field context. */ invalid?: boolean;
+    /** Visible label content. Provide text or an accessible label element; this wrapper supplies `htmlFor`. */ children?: string | ReactNode;
+    /** Disables the label and checkbox, overriding field context. */ disabled?: boolean;
 };
 
 declare interface CheckboxInputVariant {
@@ -369,16 +777,19 @@ declare type CheckboxInputVariantProps = {
     [key in keyof CheckboxInputVariant]?: ConditionalValue<CheckboxInputVariant[key]> | undefined
 }
 
-declare type CheckboxProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof CheckboxVariantProps> & CheckboxVariantProps & {
-    name: string;
-    checked?: boolean;
+/** Props for {@link Checkbox}, the unlabelled native checkbox primitive. */
+export declare type CheckboxProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof CheckboxVariantProps> & CheckboxVariantProps & {
+    /** Form field name submitted when the checkbox is checked. */ name: string;
+    /** Controlled checked state. Pair with `onChange`; do not combine with `defaultChecked`. */ checked?: boolean;
+    /** Initial uncontrolled checked state; later updates are ignored. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: CheckboxChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    disabled?: boolean;
-    indeterminate?: boolean;
+    /** Runs for the native input change event; read the next state from `event.target.checked`. */ onChange?: CheckboxChangeHandler;
+    /** Native input ID. Use it to associate an external `<label>` with the checkbox. */ id?: string;
+    /** Applies error styling, taking precedence over field context. */ error?: boolean;
+    /** Marks the native input invalid with `aria-invalid` and takes precedence over field context. */ invalid?: boolean;
+    /** Disables interaction and takes precedence over field context. */ disabled?: boolean;
+    /** Displays the mixed state and sets the native `indeterminate` property. This does not change `checked`. */ indeterminate?: boolean;
 };
 
 declare interface CheckboxVariant {
@@ -389,51 +800,135 @@ declare type CheckboxVariantProps = {
     [key in keyof CheckboxVariant]?: ConditionalValue<CheckboxVariant[key]> | undefined
 }
 
+/**
+ * Renders a compact label, optionally with an action or dismissal control.
+ *
+ * A chip is static unless it has `onClick` or both a `value` and a parent
+ * `ChipGroup`. Grouped single-select chips use radio behavior and arrow-key
+ * roving focus; grouped multi-select chips use checkbox behavior. `before` and
+ * `after` slots inherit state through slot context.
+ *
+ * @example
+ * ```tsx
+ * <Chip dismissable onDismiss={() => remove('design')}>Design</Chip>
+ * ```
+ */
 export declare const Chip: (props: ChipProps) => JSX.Element;
 
+/**
+ * Coordinates the selection and keyboard behavior of child {@link Chip} values.
+ *
+ * Use `value` with `onChange` for controlled selection, or `defaultValue` for
+ * initialization only. In a single-select group, arrow keys move focus and
+ * select the newly focused chip. Label the group with `label` when it needs an
+ * accessible name.
+ *
+ * @example
+ * ```tsx
+ * <ChipGroup type="single" defaultValue="all" label="Status">
+ *   <Chip value="all">All</Chip>
+ *   <Chip value="open">Open</Chip>
+ * </ChipGroup>
+ * ```
+ */
 export declare const ChipGroup: (props: ChipGroupProps) => JSX.Element;
 
+/** Shared selection and keyboard-navigation state for a {@link ChipGroup}. */
 declare type ChipGroupContextValue = {
+    /** The group's single- or multi-select behavior. */
     type: ChipGroupType;
+    /** Optional size inherited by child chips. */
     size?: ChipGroupSize;
+    /** Current selected value or values. */
     value: string | string[];
+    /** Updates the group's selected value or values. */
     onChange: (value: string | string[]) => void;
+    /** Optional shared form metadata supplied by the group. */
     name?: string;
+    /** Registers a selectable child chip for keyboard navigation. */
     registerChip: (value: string, ref: RefObject<HTMLButtonElement | null>) => void;
+    /** Removes a child chip from keyboard navigation. */
     unregisterChip: (value: string) => void;
+    /** Moves focus to the next or previous registered chip. */
     focusChip: (direction: 'next' | 'prev', currentValue: string) => void;
+    /** Registered selectable chip values in DOM registration order. */
     chipValues: string[];
 };
 
-declare type ChipGroupProps = Omit<WrapProps, 'role'> & Omit<BoxProps, keyof WrapProps> & {
+declare type ChipGroupOwnProps = {
+    /** Required selection model. `'single'` uses radio semantics; `'multi'` uses checkbox semantics. */
     type: ChipGroupType;
+    /** Controlled selected value. Use a string for `'single'` or a string array for `'multi'`, with `onChange` to accept updates. */
     value?: string | string[];
+    /**
+     * Initial selected value for an uncontrolled group. It is used only on first render.
+     * @default '' for `'single'`; [] for `'multi'`
+     */
     defaultValue?: string | string[];
+    /** Called with the next selection when a child chip is activated. */
     onChange?: (value: string | string[]) => void;
+    /** `Chip` children. Chips require a unique `value` to participate in selection. */
     children: ReactNode;
+    /** Size inherited by child chips unless a child supplies its own size. */
     size?: ChipGroupSize;
+    /** Accessible name applied to the group container. */
     label?: string;
+    /** Container identifier. When supplied, the container references `${id}-label`, which consumers must render themselves. */
     id?: string;
+    /** Shared form metadata exposed to child-chip context; it does not create native form inputs. */
     name?: string;
 };
 
+/** Props for {@link ChipGroup}, which coordinates selectable child chips. */
+export declare type ChipGroupProps = Omit<BoxProps, keyof ChipGroupWrapProps | keyof ChipGroupOwnProps | 'role'> & ChipGroupWrapProps & ChipGroupOwnProps;
+
+/** Chip recipe size inherited by `Chip` descendants of a group. */
 declare type ChipGroupSize = ChipVariantProps['size'];
 
+/** Selection model used by {@link ChipGroup}. */
 declare type ChipGroupType = 'single' | 'multi';
 
-declare type ChipProps = Omit<BoxProps, keyof ChipVariantProps> & Omit<ChipVariantProps, 'before' | 'after' | 'dismissable'> & {
+declare type ChipGroupWrapProps = Pick<WrapProps, 'align' | 'columnGap' | 'gap' | 'justify' | 'rowGap'>;
+
+/** Props for {@link Chip}, a compact label that can be static, actionable, selectable, or dismissible. */
+export declare type ChipProps = Omit<BoxProps, keyof ChipVariantProps> & Omit<ChipVariantProps, 'before' | 'after' | 'dismissable'> & {
+    /** Visible chip label, also used in the default dismissal label. */
     children: string;
+    /** Content displayed before the chip label. */
     before?: ReactNode;
+    /** Content displayed after the chip label and before the dismiss control. */
     after?: ReactNode;
+    /** Disables the primary action and dismiss button. The local value takes precedence over slot and field context. */
     disabled?: boolean;
+    /** Shows a spinner and disables chip interaction. */
     loading?: boolean;
+    /** Applies deleted styling without removing the chip from the DOM. */
     deleted?: boolean;
+    /** Adds a dismiss button after the chip content. */
     dismissable?: boolean;
+    /**
+     * Accessible name for the dismiss button.
+     * @default `Remove ${children}`
+     */
     dismissLabel?: string;
+    /** Ref forwarded to the dismiss button. */
+    dismissButtonRef?: Ref<HTMLButtonElement>;
+    /** Tab order override for the dismiss button. */
+    dismissButtonTabIndex?: number;
+    /** Applies error styling. The local value takes precedence over slot and field context. */
     error?: boolean;
+    /** Marks the chip invalid with `aria-invalid`. The local value takes precedence over slot and field context. */
     invalid?: boolean;
+    /** Called when the dismiss button is activated. The button is disabled when this callback is absent. */
     onDismiss?: () => void;
+    /** Keyboard handler composed onto the dismiss button. */
+    onDismissKeyDown?: KeyboardEventHandler<HTMLButtonElement>;
+    /**
+     * Native type for the chip's primary button when it is selectable or has `onClick`.
+     * @default 'button'
+     */
     type?: 'button' | 'submit' | 'reset';
+    /** Value used by a parent `ChipGroup` to identify and select this chip. */
     value?: string;
 };
 
@@ -451,10 +946,24 @@ declare type ChipVariantProps = {
     [key in keyof ChipVariant]?: ConditionalValue<ChipVariant[key]> | undefined
 }
 
+/**
+ * Renders code content in a native `code` element.
+ *
+ * Use `Pre` for a preformatted code block. `lang` supplies element language
+ * metadata; it does not perform syntax highlighting.
+ *
+ * @example
+ * ```tsx
+ * <Code>npm run build</Code>
+ * ```
+ */
 export declare const Code: (props: CodeProps) => JSX.Element;
 
-declare type CodeProps = Omit<BoxProps, keyof CodeVariantProps | keyof TextProps> & CodeVariantProps & TextProps & {
+/** Props accepted by {@link Code}. */
+export declare type CodeProps = Omit<BoxProps, keyof CodeVariantProps | keyof TextProps> & CodeVariantProps & TextProps & {
+    /** Source code or inline content to render. */
     children?: string | ReactNode;
+    /** Language metadata forwarded to the native `code` element. */
     lang?: string;
 };
 
@@ -808,6 +1317,7 @@ declare interface Conditions {
     	"base": string
 }
 
+/** Key of a Cetec container-size token. */
 declare type ContainerSizeKey = keyof typeof containerSizes;
 
 declare const containerSizes: {
@@ -1236,90 +1746,512 @@ declare namespace DataType {
     type VisualBox = "border-box" | "content-box" | "padding-box";
 }
 
-export declare const DatePicker: (props: DatePickerProps) => JSX.Element;
+/** Segment order and separator convention used to display a date. */
+export declare type DateFormat = 'MM/DD/YYYY' | 'YYYY-MM-DD';
+
+/**
+ * Renders a segmented date field with optional leading and trailing content.
+ *
+ * The field accepts keyboard entry and stepping through year, month, and day
+ * segments. Use `DatePicker` when a calendar menu is also needed.
+ *
+ * @example
+ * ```tsx
+ * <DateInput label="Invoice date" defaultValue={{ year: 2026, month: 8, day: 3 }} />
+ * ```
+ */
+export declare const DateInput: (props: DateInputProps) => JSX.Element;
 
-declare type DatePickerProps = Omit<BoxProps, keyof DatePickerVariantProps | 'children'> & DatePickerVariantProps & {
-    /** Controlled value */
+/** Props for {@link DateInput}, including segmented date state and field slots. */
+export declare type DateInputProps = Omit<BoxProps, keyof SegmentedFieldsVariantProps | 'children'> & Omit<SegmentedFieldsVariantProps, 'field' | 'range' | 'before' | 'after'> & {
+    /** Identifier forwarded to the segmented date group. */
+    id?: string;
+    /** Controlled date. Pair with `onChange`. */
     value?: DateValue | null;
-    /** Initial uncontrolled value */
+    /** Initial date when `value` is not provided. */
     defaultValue?: DateValue | null;
-    /** Called when the date changes */
+    /** Runs when the segmented date becomes complete or is cleared. */
     onChange?: (value: DateValue | null) => void;
-    /** Earliest selectable date */
-    minDate?: DateValue;
-    /** Latest selectable date */
-    maxDate?: DateValue;
-    /** Accessible label for the input group */
+    /** Segment order and separator convention. */
+    dateFormat?: DateFormat;
+    /** Accessible name for the segmented date group. */
     label?: string;
-    disabled?: boolean;
+    /** Content before the date field. Takes precedence over `iconBefore`. */
+    before?: ReactNode;
+    /** Content after the date field. Takes precedence over `iconAfter`. */
+    after?: ReactNode;
+    /** Legacy icon rendered before the field when `before` is absent. */
+    iconBefore?: IconNamesList;
+    /** Legacy icon rendered after the field when `after` is absent. */
+    iconAfter?: IconNamesList;
+    /** Applies error styling. Overrides field context when provided. */
     error?: boolean;
+    /** Prevents editing. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Applies invalid styling. Overrides field context when provided. */
     invalid?: boolean;
-    id?: string;
-    name?: string;
-    /** Controlled popover open state */
+    /** Reflected through to the segmented field — lets a wrapping Menu/Picker show "active anchor" styling */
     open?: boolean;
-    /** Initial uncontrolled popover state */
-    defaultOpen?: boolean;
-    onOpenChange?: (open: boolean) => void;
-    size?: DatePickerVariantProps['size'];
+    /** Forwarded to the segmented field — see SegmentedDate's onFocusWithin */
+    onFocusWithin?: () => void;
+    /** Forwarded to the segmented field — see SegmentedDate's onBlurWithin */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
 };
 
-declare interface DatePickerVariant {
-    /**
-     * @default "md"
-     */
-    size: "sm" | "md" | "lg" | "xl"
-}
-
-declare type DatePickerVariantProps = {
-    [key in keyof DatePickerVariant]?: ConditionalValue<DatePickerVariant[key]> | undefined
-}
-
-export declare const DateRangePicker: (props: DateRangePickerProps) => JSX.Element;
+/**
+ * Presents a calendar in a Menu and commits a selected day immediately.
+ *
+ * Supply a `trigger`, or set inherited `inline` to render the calendar in
+ * normal flow. Selecting an enabled date calls `onChange` and closes a
+ * triggered menu.
+ *
+ * @example
+ * ```tsx
+ * <DateMenu trigger={<Button>Choose date</Button>} onChange={setDate} />
+ * ```
+ */
+export declare const DateMenu: (props: DateMenuProps) => any;
 
-declare type DateRangePickerProps = {
-    /** Start date value */
-    startValue?: DateValue | null;
-    /** End date value */
-    endValue?: DateValue | null;
-    /** Called when start date changes */
-    onStartChange?: (value: DateValue | null) => void;
-    /** Called when end date changes */
-    onEndChange?: (value: DateValue | null) => void;
-    /** Earliest selectable date (applies to both pickers) */
+/** Props for {@link DateMenu}, a Calendar presented through Menu behavior. */
+export declare type DateMenuProps = Omit<MenuProps, 'children' | 'onChange' | 'value'> & {
+    /** Selected date shown by the calendar. */
+    value?: DateValue | null;
+    /** Commits immediately on day selection, then closes the menu. */
+    onChange?: (value: DateValue | null) => void;
+    /** Earliest selectable date. */
     minDate?: DateValue;
-    /** Latest selectable date (applies to both pickers) */
+    /** Latest selectable date. */
     maxDate?: DateValue;
+    /** Controlled visible calendar month. */
+    viewDate?: ViewDate_2;
+    /** Initial visible month when `viewDate` is not provided. */
+    defaultViewDate?: ViewDate_2;
+    /** Runs when calendar navigation requests a new visible month. */
+    onViewDateChange?: (viewDate: ViewDate_2) => void;
+    /** Prevents opening or selection and returns only the trigger. */
     disabled?: boolean;
-    error?: boolean;
-    /** Size passed to both DatePickers */
-    size?: DatePickerVariantProps['size'];
-    /** Accessible label prefix — used to build "Start date" and "End date" labels */
+    /** Accessible label passed to the calendar grid. */
     label?: string;
 };
 
-declare interface DateValue {
-    year: number;
-    month: number;
-    day: number;
-}
+/**
+ * Combines keyboard date entry with a calendar selection menu.
+ *
+ * Focusing the segmented input opens the menu. Typed dates and calendar
+ * selections update the same controlled or uncontrolled value.
+ *
+ * @example
+ * ```tsx
+ * <DatePicker label="Due date" value={date} onChange={setDate} />
+ * ```
+ */
+export declare const DatePicker: (props: DatePickerProps) => JSX.Element;
 
-export declare const deriveItemTextValue: ({ textValue, label, description, getItemText, }: {
-    textValue?: string;
-    label?: string;
-    description?: string;
-    getItemText: (item: {
-        label?: string;
-        description?: string;
-    }) => string;
-}) => string;
+/** Props for {@link DatePicker}, combining a segmented input and calendar menu. */
+export declare type DatePickerProps = Pick<DateInputProps, 'id' | 'label' | 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'dateFormat' | 'size'> & {
+    /** Controlled selected date. Pair with `onChange`. */
+    value?: DateValue | null;
+    /** Initial selected date when `value` is not provided. */
+    defaultValue?: DateValue | null;
+    /** Runs when typing or calendar selection commits a date. */
+    onChange?: (value: DateValue | null) => void;
+    /** Earliest selectable calendar date. */
+    minDate?: DateValue;
+    /** Latest selectable calendar date. */
+    maxDate?: DateValue;
+    /** Controlled visible calendar month. */
+    viewDate?: ViewDate_4;
+    /** Initial visible month when `viewDate` is not provided. */
+    defaultViewDate?: ViewDate_4;
+    /** Runs when calendar navigation requests a new visible month. */
+    onViewDateChange?: (viewDate: ViewDate_4) => void;
+    /** Floating UI placement of the calendar menu. */
+    placement?: Placement;
+    /** Controlled menu visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial menu visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the menu open or close. */
+    onOpenChange?: (open: boolean) => void;
+};
+
+/**
+ * Renders start and end dates as two coordinated segmented fields.
+ *
+ * Each endpoint commits independently while the component preserves the other
+ * endpoint. Use `DateRangePicker` when a calendar menu and Apply/Cancel flow
+ * are also needed.
+ *
+ * @example
+ * ```tsx
+ * <DateRangeInput startLabel="Arrival" endLabel="Departure" />
+ * ```
+ */
+export declare const DateRangeInput: (props: DateRangeInputProps) => JSX.Element;
+
+/** Props for {@link DateRangeInput}, including range state and field slots. */
+export declare type DateRangeInputProps = Omit<BoxProps, keyof SegmentedFieldsVariantProps | 'children'> & Omit<SegmentedFieldsVariantProps, 'field' | 'range' | 'before' | 'after'> & {
+    /** Identifier applied to the range container. */
+    id?: string;
+    /** Controlled start and end dates. Pair with `onChange`. */
+    value?: DateRangeValue | null;
+    /** Initial range when `value` is not provided. */
+    defaultValue?: DateRangeValue | null;
+    /** Runs whenever either endpoint becomes complete or is cleared. */
+    onChange?: (value: DateRangeValue | null) => void;
+    /** Segment order and separator convention shared by both endpoints. */
+    dateFormat?: DateFormat;
+    /** Accessible name for the start-date segments. */
+    startLabel?: string;
+    /** Accessible name for the end-date segments. */
+    endLabel?: string;
+    /** Content before the range. Takes precedence over `iconBefore`. */
+    before?: ReactNode;
+    /** Content after the range. Takes precedence over `iconAfter`. */
+    after?: ReactNode;
+    /** Legacy icon rendered before the range when `before` is absent. */
+    iconBefore?: IconNamesList;
+    /** Legacy icon rendered after the range when `after` is absent. */
+    iconAfter?: IconNamesList;
+    /** Applies error styling. Overrides field context when provided. */
+    error?: boolean;
+    /** Prevents editing both endpoints. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Applies invalid styling. Overrides field context when provided. */
+    invalid?: boolean;
+    /** Reflected through to the segmented fields — lets a wrapping Menu/Picker show "active anchor" styling */
+    open?: boolean;
+    /** Forwarded to both segmented fields — see SegmentedDate's onFocusWithin */
+    onFocusWithin?: () => void;
+    /** Forwarded to both segmented fields — see SegmentedDate's onBlurWithin */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+/**
+ * Selects a date range from two independently navigable calendars.
+ *
+ * Selection is held as a draft until Apply is pressed. Cancel restores the
+ * committed `value`. Apply is unavailable until both endpoints are selected.
+ *
+ * @example
+ * ```tsx
+ * <DateRangeMenu
+ *   trigger={<Button>Choose dates</Button>}
+ *   value={range}
+ *   onChange={setRange}
+ * />
+ * ```
+ */
+export declare const DateRangeMenu: (props: DateRangeMenuProps) => any;
+
+/** Props for {@link DateRangeMenu}, including committed range and bounds. */
+export declare type DateRangeMenuProps = Omit<MenuProps, 'children' | 'onChange' | 'value'> & {
+    /** Committed start and end dates used to initialize the menu draft. */
+    value?: DateRangeValue | null;
+    /** Commits the complete draft when Apply is pressed; Cancel discards it. */
+    onChange?: (value: DateRangeValue | null) => void;
+    /** Earliest selectable date for both calendars. */
+    minDate?: DateValue;
+    /** Latest selectable date for both calendars. */
+    maxDate?: DateValue;
+    /** Prevents opening or selection and returns only the trigger. */
+    disabled?: boolean;
+    /** Accessible label for the first calendar. */
+    startLabel?: string;
+    /** Accessible label for the second calendar. */
+    endLabel?: string;
+};
+
+/**
+ * Combines segmented range entry with a two-calendar selection menu.
+ *
+ * Typed endpoints commit immediately. Calendar choices remain a draft until
+ * Apply is pressed; Cancel restores the currently committed range.
+ *
+ * @example
+ * ```tsx
+ * <DateRangePicker startLabel="Arrival" endLabel="Departure" />
+ * ```
+ */
+export declare const DateRangePicker: (props: DateRangePickerProps) => JSX.Element;
+
+/** Props for {@link DateRangePicker}, combining range input and calendar menu. */
+export declare type DateRangePickerProps = Pick<DateRangeInputProps, 'id' | 'startLabel' | 'endLabel' | 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'dateFormat' | 'size'> & {
+    /** Controlled start and end dates. Pair with `onChange`. */
+    value?: DateRangeValue | null;
+    /** Initial range when `value` is not provided. */
+    defaultValue?: DateRangeValue | null;
+    /** Runs for typed endpoint changes and applied calendar drafts. */
+    onChange?: (value: DateRangeValue | null) => void;
+    /** Earliest selectable date for both calendars. */
+    minDate?: DateValue;
+    /** Latest selectable date for both calendars. */
+    maxDate?: DateValue;
+    /** Floating UI placement of the calendar menu. */
+    placement?: Placement;
+    /** Controlled menu visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial menu visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the menu open or close. */
+    onOpenChange?: (open: boolean) => void;
+};
+
+/** A committed date range — either endpoint may be null while only partially filled in. */
+export declare interface DateRangeValue {
+    start: DateValue | null;
+    end: DateValue | null;
+}
+
+/**
+ * Renders coordinated segmented date and time fields in one control.
+ *
+ * Each complete portion is preserved while the other changes. Use
+ * `DateTimePicker` when calendar and time-selection menus are also needed.
+ *
+ * @example
+ * ```tsx
+ * <DateTimeInput dateLabel="Due date" timeLabel="Due time" />
+ * ```
+ */
+export declare const DateTimeInput: (props: DateTimeInputProps) => JSX.Element;
+
+/** Props for {@link DateTimeInput}, including combined state and field slots. */
+export declare type DateTimeInputProps = Omit<BoxProps, keyof SegmentedFieldsVariantProps | 'children'> & Omit<SegmentedFieldsVariantProps, 'field' | 'range' | 'before' | 'after'> & {
+    /** Identifier applied to the combined field container. */
+    id?: string;
+    /** Controlled date and time. Pair with `onChange`. */
+    value?: DateTimeValue | null;
+    /** Initial date and time when `value` is not provided. */
+    defaultValue?: DateTimeValue | null;
+    /** Runs whenever the date or time portion changes. */
+    onChange?: (value: DateTimeValue | null) => void;
+    /** Segment order and separator convention for the date portion. */
+    dateFormat?: DateFormat;
+    /** Display cycle for the time portion. */
+    timeFormat?: TimeFormat;
+    /** Minute increment used by keyboard stepping. */
+    minuteStep?: number;
+    /** Accessible name for the date segments. */
+    dateLabel?: string;
+    /** Accessible name for the time segments. */
+    timeLabel?: string;
+    /** Content before the combined field. Takes precedence over `iconBefore`. */
+    before?: ReactNode;
+    /** Content after the combined field. Takes precedence over `iconAfter`. */
+    after?: ReactNode;
+    /** Legacy icon rendered before the field when `before` is absent. */
+    iconBefore?: IconNamesList;
+    /** Legacy icon rendered after the field when `after` is absent. */
+    iconAfter?: IconNamesList;
+    /** Applies error styling. Overrides field context when provided. */
+    error?: boolean;
+    /** Prevents editing both portions. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Applies invalid styling. Overrides field context when provided. */
+    invalid?: boolean;
+    /** Reflected through to the segmented fields — lets a wrapping Menu/Picker show "active anchor" styling */
+    open?: boolean;
+    /** Forwarded to both segmented fields — see SegmentedDate/SegmentedTime's onFocusWithin */
+    onFocusWithin?: () => void;
+    /** Forwarded to both segmented fields — see SegmentedDate/SegmentedTime's onBlurWithin */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+/**
+ * Selects a date and time from a calendar and aligned time columns.
+ *
+ * Changes remain a draft until Apply is pressed. Cancel restores `value`, and
+ * Apply is unavailable until both the date and time portions are complete.
+ *
+ * @example
+ * ```tsx
+ * <DateTimeMenu
+ *   trigger={<Button>Schedule</Button>}
+ *   value={scheduledAt}
+ *   onChange={setScheduledAt}
+ * />
+ * ```
+ */
+export declare const DateTimeMenu: (props: DateTimeMenuProps) => any;
+
+/** Props for {@link DateTimeMenu}, including committed value and constraints. */
+export declare type DateTimeMenuProps = Omit<MenuProps, 'children' | 'onChange' | 'value'> & {
+    /** Committed date and time used to initialize the menu draft. */
+    value?: DateTimeValue | null;
+    /** Commits the complete draft when Apply is pressed; Cancel discards it. */
+    onChange?: (value: DateTimeValue | null) => void;
+    /** Earliest selectable calendar date. */
+    minDate?: DateValue;
+    /** Latest selectable calendar date. */
+    maxDate?: DateValue;
+    /** Controlled visible calendar month. */
+    viewDate?: ViewDate_3;
+    /** Initial visible calendar month when `viewDate` is not provided. */
+    defaultViewDate?: ViewDate_3;
+    /** Runs when calendar navigation requests a new visible month. */
+    onViewDateChange?: (viewDate: ViewDate_3) => void;
+    /** Display cycle for the time columns. */
+    timeFormat?: TimeFormat;
+    /** Interval used to generate minute choices. */
+    minuteStep?: number;
+    /** Prevents opening or selection and returns only the trigger. */
+    disabled?: boolean;
+    /** Accessible label passed to the calendar grid. */
+    dateLabel?: string;
+};
+
+/**
+ * Combines segmented date-time entry with a calendar and time menu.
+ *
+ * Typed portions commit immediately. Menu choices remain a draft until Apply
+ * is pressed; Cancel restores the currently committed value.
+ *
+ * @example
+ * ```tsx
+ * <DateTimePicker dateLabel="Due date" timeLabel="Due time" />
+ * ```
+ */
+export declare const DateTimePicker: (props: DateTimePickerProps) => JSX.Element;
+
+/** Props for {@link DateTimePicker}, combining segmented entry and menu. */
+export declare type DateTimePickerProps = Pick<DateTimeInputProps, 'id' | 'dateLabel' | 'timeLabel' | 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'dateFormat' | 'timeFormat' | 'size'> & {
+    /** Controlled combined date and time. Pair with `onChange`. */
+    value?: DateTimeValue | null;
+    /** Initial combined value when `value` is not provided. */
+    defaultValue?: DateTimeValue | null;
+    /** Runs for typed changes and applied menu drafts. */
+    onChange?: (value: DateTimeValue | null) => void;
+    /** Minute interval used by segmented stepping and menu choices. */
+    minuteStep?: number;
+    /** Earliest selectable calendar date. */
+    minDate?: DateValue;
+    /** Latest selectable calendar date. */
+    maxDate?: DateValue;
+    /** Controlled visible calendar month. */
+    viewDate?: ViewDate_5;
+    /** Initial visible month when `viewDate` is not provided. */
+    defaultViewDate?: ViewDate_5;
+    /** Runs when calendar navigation requests a new visible month. */
+    onViewDateChange?: (viewDate: ViewDate_5) => void;
+    /** Floating UI placement of the date-time menu. */
+    placement?: Placement;
+    /** Controlled menu visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial menu visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the menu open or close. */
+    onOpenChange?: (open: boolean) => void;
+};
+
+/**
+ * Coordinates independent start and end `DateTimePicker` controls.
+ *
+ * The controls render side by side when space allows and stack at narrow
+ * widths. Each endpoint has its own menu and commits independently.
+ *
+ * @example
+ * ```tsx
+ * <DateTimeRangePicker
+ *   startDateLabel="Starts on"
+ *   startTimeLabel="Starts at"
+ *   endDateLabel="Ends on"
+ *   endTimeLabel="Ends at"
+ * />
+ * ```
+ */
+export declare const DateTimeRangePicker: (props: DateTimeRangePickerProps) => JSX.Element;
+
+/** Props for {@link DateTimeRangePicker}, which coordinates two pickers. */
+export declare type DateTimeRangePickerProps = Pick<DateTimeInputProps, 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'dateFormat' | 'timeFormat' | 'size'> & {
+    /** Controlled start and end date-times. Pair with `onChange`. */
+    value?: DateTimeRangeValue | null;
+    /** Initial range when `value` is not provided. */
+    defaultValue?: DateTimeRangeValue | null;
+    /** Runs whenever either endpoint commits a new value. */
+    onChange?: (value: DateTimeRangeValue | null) => void;
+    /** Minute interval shared by both endpoint pickers. */
+    minuteStep?: number;
+    /** Earliest selectable date for both endpoints. */
+    minDate?: DateValue;
+    /** Latest selectable date for both endpoints. */
+    maxDate?: DateValue;
+    /** Accessible date label for the start picker. */
+    startDateLabel?: string;
+    /** Accessible time label for the start picker. */
+    startTimeLabel?: string;
+    /** Accessible date label for the end picker. */
+    endDateLabel?: string;
+    /** Accessible time label for the end picker. */
+    endTimeLabel?: string;
+    /** Floating UI placement shared by both endpoint menus. */
+    placement?: Placement;
+};
+
+/** A committed date+time range — either endpoint may be null while only partially filled in. */
+export declare interface DateTimeRangeValue {
+    start: DateTimeValue | null;
+    end: DateTimeValue | null;
+}
+
+/** A combined date+time value — either half may be null while only partially filled in. */
+export declare interface DateTimeValue {
+    date: DateValue | null;
+    time: TimeValue | null;
+}
+
+/** A calendar date. Month is 1-indexed (1 = January) to match human-readable input. */
+export declare interface DateValue {
+    year: number;
+    month: number;
+    day: number;
+}
+
+/** Returns explicit `textValue` when present, otherwise derives searchable text from item metadata. */
+export declare const deriveItemTextValue: ({ textValue, label, description, getItemText, }: {
+    textValue?: string;
+    label?: string;
+    description?: string;
+    getItemText: (item: {
+        label?: string;
+        description?: string;
+    }) => string;
+}) => string;
 
 declare type DistributiveOmit<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never
 
+/**
+ * Draws a visual separator between adjacent regions.
+ *
+ * `Divider` is decorative and renders a `div`; use semantic sectioning and
+ * headings when the separation must also be conveyed to assistive technology.
+ *
+ * @example
+ * ```tsx
+ * <Divider />
+ * ```
+ */
 export declare const Divider: (props: DividerProps) => JSX.Element;
 
-declare type DividerProps = Omit<BoxProps, keyof DividerVariantProps> & DividerVariantProps & {
+/** Props accepted by {@link Divider}. */
+export declare type DividerProps = Omit<BoxProps, keyof DividerVariantProps> & DividerVariantProps & {
+    /** Axis along which the visual divider extends. */
+    /** @default "horizontal" */
     direction?: DividerVariantProps['direction'];
+    /** Visual thickness of the divider. */
+    /** @default "thin" */
     weight?: DividerVariantProps['weight'];
 };
 
@@ -1338,6 +2270,43 @@ declare type DividerVariantProps = {
     [key in keyof DividerVariant]?: ConditionalValue<DividerVariant[key]> | undefined
 }
 
+/**
+ * Adds a test id to the interaction chain shared with a subtree.
+ *
+ * Design-system components pick this up automatically: `Box` opens a scope
+ * whenever it receives a `data-testid`, so anything rendered through the
+ * library already contributes. Reach for `DsChainScope` only around raw DOM
+ * that does not render through `Box` and still needs to appear in the chain,
+ * such as an application-owned wrapper element.
+ *
+ * The chain exists so portaled content can be attributed back to the subtree
+ * that opened it. A menu, modal, or tooltip renders into `document.body` and
+ * has no DOM ancestry to its opener, but React context follows the React tree
+ * through a portal, so the chain resolves correctly on either side.
+ *
+ * Renders no DOM of its own. The chain keeps the five nearest ids.
+ *
+ * @example
+ * ```tsx
+ * <DsChainScope testId="order-row">
+ *   <tr data-testid="order-row">{cells}</tr>
+ * </DsChainScope>
+ * ```
+ */
+export declare const DsChainScope: ({ testId, children }: DsChainScopeProps) => JSX.Element;
+
+/** Props accepted by {@link DsChainScope}. */
+export declare type DsChainScopeProps = {
+    /**
+     * `data-testid` value appended to the chain inherited by `children`. Match it
+     * to the `data-testid` written on the element this scope describes so the
+     * chain and the DOM agree.
+     */
+    testId: string;
+    /** Subtree that resolves the extended chain. */
+    children?: ReactNode;
+};
+
 declare type DurationToken = "fastest" | "faster" | "fast" | "normal" | "slow" | "slower" | "slowest"
 
 declare type EasingToken = "default" | "linear" | "in" | "out" | "in-out"
@@ -1350,24 +2319,81 @@ declare type FontToken = "heading" | "body" | "mono"
 
 declare type FontWeightToken = "light" | "normal" | "medium" | "bold" | "black"
 
+/**
+ * Groups a label, control, help text, and validation message into one field.
+ *
+ * `labelFor` must match the `id` of the nested input. The component provides
+ * `size`, `error`, `invalid`, and `disabled` through field context to
+ * compatible descendants, but it does not add native input attributes for
+ * them. If `success` and an error state are both true, success messaging wins.
+ *
+ * @example
+ * ```tsx
+ * <FormField label="Email" labelFor="email" required>
+ *   <TextInput id="email" type="email" required />
+ * </FormField>
+ * ```
+ */
 export declare const FormField: (props: FormFieldProps) => JSX.Element;
 
-declare type FormFieldProps = Omit<BoxProps, keyof FormFieldVariantProps | 'gap'> & FormFieldVariantProps & {
+/**
+ * Props for {@link FormField}. It supplies field state to compatible
+ * descendants through `FieldContext`.
+ */
+export declare type FormFieldProps = Omit<BoxProps, keyof FormFieldVariantProps | 'gap'> & FormFieldVariantProps & {
+    /** Visible label text for the field. */
     label: string;
+    /**
+     * The `id` of the labeled input. The child input must use this exact `id`
+     * for the rendered label's `htmlFor` relationship to work.
+     */
     labelFor: string;
+    /** Input or control content associated with this field. */
     children: ReactNode;
+    /** Supporting guidance displayed near the input. */
     helpText?: string;
+    /**
+     * Displays a visual required indicator. Also set `required` on the native
+     * input when browser validation or required semantics are needed.
+     */
     required?: boolean;
+    /** Marks the field and compatible descendants as having an error. */
     error?: boolean;
+    /** Marks the field invalid and supplies invalid state to compatible descendants. */
     invalid?: boolean;
+    /** Marks the field successful. Success text takes precedence over error text. */
     success?: boolean;
+    /** Message displayed when `error` or `invalid` is true and `success` is false. */
     errorText?: string;
+    /** Message displayed when `success` is true, including when error state is also set. */
     successText?: string;
+    /**
+     * Marks the field `aria-disabled`, applies disabled styling, and supplies
+     * disabled state to compatible descendants. Native child controls must
+     * still receive `disabled` themselves.
+     */
     disabled?: boolean;
+    /** Optional title shown by the label-help tooltip when `tooltipText` is provided. */
     tooltipTitle?: string;
+    /**
+     * Help text that enables the informational tooltip beside the label. The
+     * tooltip is not rendered without this value.
+     */
     tooltipText?: string;
+    /**
+     * Field size passed to compatible descendants and used by the field recipe.
+     *
+     * @default 'md'
+     */
     size?: FormFieldVariantProps['size'];
+    /**
+     * Uses a stacked field by default; `inline` places label and control in a
+     * two-column layout.
+     *
+     * @default 'default'
+     */
     layout?: FormFieldVariantProps['layout'];
+    /** Spacing token applied between controls in the field's input container. */
     gap?: SpacingToken;
 };
 
@@ -1386,8 +2412,10 @@ declare type FormFieldVariantProps = {
     [key in keyof FormFieldVariant]?: ConditionalValue<FormFieldVariant[key]> | undefined
 }
 
+/** Returns the internal menu compound-component marker for a React element, or `null` for other values. */
 export declare const getComponentType: (node: unknown) => string | null;
 
+/** Splits text into case-insensitive query-match parts for highlight rendering. */
 export declare const getHighlightedTextParts: (value: string, query: string) => {
     text: string;
     match: boolean;
@@ -1397,12 +2425,27 @@ declare type Globals = "-moz-initial" | "inherit" | "initial" | "revert" | "reve
 
 export declare type GlobalStyleObject = Record<string, unknown>;
 
+/** Returns whether a child tree contains any visible menu item, subgroup, or submenu for a filter. */
 export declare const hasMatchingItems: (children: ReactNode, filterContext: MenuFilterContextValue) => boolean;
 
+/**
+ * Renders a semantic document heading with the matching typography.
+ *
+ * Choose `level` from the page outline rather than for visual size alone.
+ *
+ * @example
+ * ```tsx
+ * <Heading level="h2">Shipping details</Heading>
+ * ```
+ */
 export declare const Heading: (props: HeadingProps) => JSX.Element;
 
-declare type HeadingProps = Omit<TextProps, keyof HeadingVariantProps> & HeadingVariantProps & {
+/** Props accepted by {@link Heading}. */
+export declare type HeadingProps = Omit<TextProps, keyof HeadingVariantProps> & HeadingVariantProps & {
+    /** Heading content. */
     children?: string | ReactNode;
+    /** Semantic heading level and matching visual treatment. */
+    /** @default "h2" */
     level?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 };
 
@@ -1418,11 +2461,33 @@ declare type HeadingVariantProps = {
     [key in keyof HeadingVariant]?: ConditionalValue<HeadingVariant[key]> | undefined
 }
 
+/**
+ * Renders case-insensitive literal matches in text using semantic `mark`
+ * elements.
+ *
+ * Empty or whitespace-only queries, and `enabled={false}`, render the original
+ * string without wrapper markup. Use it directly for custom content; default
+ * {@link ListItem} content uses it automatically when highlighting is enabled.
+ *
+ * @example
+ * ```tsx
+ * <HighlightText value="Account settings" query="account" />
+ * ```
+ */
 export declare const HighlightText: (props: HighlightTextProps) => JSX.Element;
 
-declare type HighlightTextProps = Omit<BoxProps, keyof HighlightTextVariantProps> & HighlightTextVariantProps & {
+/** Props for {@link HighlightText}. */
+export declare type HighlightTextProps = Omit<BoxProps, keyof HighlightTextVariantProps> & HighlightTextVariantProps & {
+    /** Text to render and search within. */
     value: string;
+    /** Case-insensitive literal text to mark within `value`. */
     query: string;
+    /**
+     * When false, returns `value` without creating highlight markup or applying
+     * styling props.
+     *
+     * @default true
+     */
     enabled?: boolean;
 };
 
@@ -1434,22 +2499,74 @@ declare type HighlightTextVariantProps = {
     [key in keyof HighlightTextVariant]?: ConditionalValue<HighlightTextVariant[key]> | undefined
 }
 
-declare type HourCycle = '12' | '24';
-
 declare type HTMLStyledProps<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps & AsProps, JsxStyleProps>
 
+/**
+ * Renders an SVG symbol from the configured icon sprite.
+ *
+ * Icons are visual content, not automatically hidden or named. Pass
+ * `aria-hidden` for decorative icons; give meaningful standalone icons an
+ * accessible name such as `aria-label`. Wrap meaningful actions in
+ * {@link IconButton} rather than using a bare clickable SVG.
+ *
+ * @example
+ * ```tsx
+ * <Icon name="info" aria-label="More information" />
+ * ```
+ */
 export declare const Icon: (props: IconProps) => JSX.Element;
 
+/**
+ * Performs an icon-only action or navigation with a required accessible label.
+ *
+ * Renders a native `button` by default, or an anchor when `href` is supplied.
+ * Its explicit `size`, `error`, `invalid`, and `disabled` values take
+ * precedence over slot context, which takes precedence over field context.
+ * Its recipe defaults to the `standard` variant and `md` size.
+ *
+ * @example
+ * ```tsx
+ * <IconButton iconName="edit" altText="Edit invoice" onClick={editInvoice} />
+ * ```
+ */
 export declare const IconButton: (props: IconButtonProps) => JSX.Element;
 
-declare type IconButtonProps = Omit<BoxProps, keyof IconButtonVariantProps> & IconButtonVariantProps & {
+/**
+ * Props for {@link IconButton}. Extends {@link BoxProps} for layout and native
+ * element attributes while reserving its visual recipe variants.
+ */
+export declare type IconButtonProps = Omit<BoxProps, keyof IconButtonVariantProps> & IconButtonVariantProps & {
+    /** Icon symbol rendered for the action. */
     iconName: IconNamesList;
+    /**
+     * Required accessible label for the button and text used by its tooltip.
+     * Describe the action, not the icon's shape.
+     */
     altText: string;
+    /** When provided, renders an anchor instead of a native button. */
     href?: string;
+    /**
+     * Shows a centered spinner, hides the icon, and sets `aria-busy`. Loading
+     * does not disable the control; set `disabled` when the action is unavailable.
+     *
+     * @default false
+     */
     loading?: boolean;
+    /** Marks the control as having an error for styling. */
     error?: boolean;
+    /** Sets `aria-invalid` and marks the control invalid for styling. */
     invalid?: boolean;
+    /**
+     * Disables a native button. For links, marks the anchor `aria-disabled` and
+     * prevents its default click navigation.
+     */
     disabled?: boolean;
+    /**
+     * Native button type; ignored when `href` causes the component to render an
+     * anchor.
+     *
+     * @default 'button'
+     */
     type?: 'submit' | 'reset' | 'button';
 };
 
@@ -1468,10 +2585,12 @@ declare type IconButtonVariantProps = {
     [key in keyof IconButtonVariant]?: ConditionalValue<IconButtonVariant[key]> | undefined
 }
 
+/** Resolved SVG sprite configuration shared by {@link IconProvider}. */
 declare type IconConfigContextValue = {
     spritePath: string;
 };
 
+/** Runtime catalog of icon names accepted by `Icon`. */
 export declare const IconNames: {
     readonly 'aa-placeholder': "aa-placeholder";
     readonly alarm: "alarm";
@@ -2099,16 +3218,57 @@ declare type IconNamesList =
 | 'zoom-in'
 | 'zoom-out';
 
-declare type IconProps = Omit<BoxProps, IconNamesList | 'size'> & SVGAttributes<SVGElement> & IconVariantProps & {
+declare type IconOwnProps = {
+    /** Symbol identifier from the configured SVG sprite. */
     name: IconNamesList;
+    /**
+     * Icon size recipe variant. Responsive/conditional recipe values are
+     * supported. An explicit value takes precedence over slot context.
+     *
+     * @default 24px when no size is supplied by the icon or its slot context
+     */
     size?: IconVariantProps['size'];
+    /**
+     * Design-token fill color. An explicit value takes precedence over slot
+     * context; otherwise the recipe uses the decorative icon color.
+     *
+     * @default 'icon.decorative'
+     */
     fill?: ColorToken;
 };
 
+/**
+ * Props for {@link Icon}. Extends SVG and Box props for presentation and
+ * accessibility attributes.
+ */
+export declare type IconProps = Omit<BoxProps, keyof IconVariantProps | keyof IconOwnProps> & Omit<IconVariantProps, keyof IconOwnProps> & IconOwnProps;
+
+/**
+ * Configures the SVG sprite used by descendant {@link Icon} components.
+ *
+ * Use it at an application or embedded-library boundary when the default
+ * `/sprite.svg` location is not available. Nested providers override the
+ * sprite path for their own descendants.
+ *
+ * @example
+ * ```tsx
+ * <IconProvider spritePath="/assets/icons.svg">
+ *   <App />
+ * </IconProvider>
+ * ```
+ */
 export declare const IconProvider: ({ children, spritePath }: IconProviderProps) => JSX.Element;
 
+/** Props for {@link IconProvider}. */
 export declare type IconProviderProps = {
+    /** Components that should resolve sprite symbols from this provider. */
     children: ReactNode;
+    /**
+     * URL or path to the SVG sprite file. This provider value applies to all
+     * descendant `Icon` components.
+     *
+     * @default '/sprite.svg'
+     */
     spritePath?: string;
 };
 
@@ -2125,6 +3285,7 @@ declare type Important = ImportantMark | WhitespaceImportant
 
 declare type ImportantMark = "!" | "!important"
 
+/** Returns whether text is visible for the supplied filtering mode and query. */
 export declare const isItemMatch: ({ textValue, query, filterMode, }: {
     textValue: string;
     query: string;
@@ -2139,23 +3300,46 @@ P
 declare type JsxStyleProps = SystemStyleObject_2 & WithCss
 
 /**
- * Used to display keyboard shortcuts.
- * Supported special symbols: ⌘ command, ⌥ option, ⌃ control, ⇪ shift,
- * ⎋ escape, ⌫ delete, ↩ return, ⇥ tab, ← left, → right, ↑ up, ↓ down.
- * Example: <Kbd keys={['⌘', 'K']} />
+ * Displays a keyboard shortcut as a group of native `kbd` elements.
+ *
+ * Known symbols receive readable tooltip labels: ⌘ command, ⌥ option,
+ * ⌃ control, ⇪ shift, ⎋ escape, ⌫ delete, ↩ return, ⇥ tab, and the four arrow
+ * symbols. `Kbd` describes a shortcut; it is not an interactive control.
+ *
+ * @example
+ * ```tsx
+ * <Kbd keys={['⌘', 'K']} />
+ * ```
  */
 export declare const Kbd: (props: KbdProps) => JSX.Element;
 
+/** Props accepted by {@link Kbd}. */
 export declare type KbdProps = Omit<BoxProps, 'children'> & {
+    /** Ordered key labels that make up the shortcut. */
     keys: KbdValue[];
 };
 
+/** A visible key label accepted by `Kbd`. */
 declare type KbdValue = string;
 
+/**
+ * Renders a native label for a form control.
+ *
+ * `htmlFor` must match the target control's `id`. Use `FormField` when the
+ * control also needs help text, validation messaging, or shared field state.
+ *
+ * @example
+ * ```tsx
+ * <Label htmlFor="email">Email address</Label>
+ * ```
+ */
 export declare const Label: (props: LabelProps) => JSX.Element;
 
-declare type LabelProps = Omit<BoxProps, keyof LabelVariantProps> & LabelVariantProps & {
+/** Props accepted by {@link Label}. */
+export declare type LabelProps = Omit<BoxProps, keyof LabelVariantProps> & LabelVariantProps & {
+    /** ID of the form control labeled by this element. */
     htmlFor: string;
+    /** Visible label content. */
     children?: string | ReactNode;
 };
 
@@ -2182,18 +3366,45 @@ declare type LetterSpacingToken = "tighter" | "tight" | "normal" | "wide" | "wid
 
 declare type LineHeightToken = "none" | "tight" | "default" | "loose"
 
+/**
+ * Navigates to another location using a native anchor.
+ *
+ * Set `external` for destinations that should open in a new tab. Use `Button`
+ * for actions that do not navigate.
+ *
+ * @example
+ * ```tsx
+ * <Link href="/orders">View orders</Link>
+ * ```
+ */
 export declare const Link: (props: LinkProps) => JSX.Element;
 
-declare type LinkProps = Omit<BoxProps, keyof LinkVariantProps> & LinkVariantProps & {
+/** Props accepted by {@link Link}. */
+export declare type LinkProps = Omit<BoxProps, keyof LinkVariantProps> & LinkVariantProps & {
+    /** Destination URL for the native anchor. */
     href: string;
+    /** Opens the destination in a new tab and displays an external-link icon. */
+    /** @default false */
     external?: boolean;
+    /** Prevents navigation and removes the link from sequential keyboard focus. */
+    /** @default false */
     disabled?: boolean;
+    /** Visual text size. */
     size?: LinkVariantProps['size'];
+    /** Font family token used for the link text. */
+    /** @default "body" */
     family?: FontToken;
+    /** Applies italic styling to the link text. */
+    /** @default false */
     italic?: boolean;
+    /** Applies the recipe's bold link treatment. */
+    /** @default false */
     bold?: boolean;
+    /** Explicit font-weight token. */
     weight?: FontWeightToken;
+    /** Additional class name merged with the link recipe class. */
     className?: string;
+    /** Link label and inline content. */
     children?: ReactNode;
 };
 
@@ -2216,27 +3427,88 @@ declare type LinkVariantProps = {
     [key in keyof LinkVariant]?: ConditionalValue<LinkVariant[key]> | undefined
 }
 
+/**
+ * Lays out related {@link ListItem} controls and shares density and search
+ * highlighting settings with its descendants.
+ *
+ * The component renders a `div` and does not assign an ARIA role. When its
+ * children are interactive options, provide the appropriate role and label
+ * (for example, `role="listbox"` and `aria-label`).
+ *
+ * @example
+ * ```tsx
+ * <List role="listbox" aria-label="Account settings">
+ *   <ListItem label="Profile" />
+ * </List>
+ * ```
+ */
 export declare const List: (props: ListProps) => JSX.Element;
 
+/** Values inherited by descendants of a {@link ListProvider}. */
 declare type ListContextValue = {
+    /** Resolved list spacing density. */
     density: ListDensity;
+    /** Search text for default list-item content. */
     query: string;
+    /** Whether default list-item text should mark query matches. */
     highlightMatches: boolean;
+    /** Reserved list-item variant metadata for custom list composition. */
     variant?: ListItemVariantProps['variant'];
+    /** Reserved leading icon metadata for custom list composition. */
     iconBefore?: IconNamesList;
+    /** Reserved trailing icon metadata for custom list composition. */
     iconAfter?: IconNamesList;
 };
 
+/** Responsive density value shared by List primitives. */
 declare type ListDensity = ListItemVariantProps['density'];
 
+/**
+ * Renders an interactive option, link, selection control, or visual divider.
+ *
+ * Except for the `divider` variant, it renders a native `button` with
+ * `type="button"` by default, or an anchor when `href` is provided, and sets
+ * `role="option"`. Place interactive items in a suitably labeled parent such
+ * as `<List role="listbox">`. Pass custom `children` for fully custom item
+ * content; doing so replaces the label, description, controls, icons, and
+ * match highlighting.
+ *
+ * @example
+ * ```tsx
+ * <ListItem label="Profile" description="Manage your account" />
+ * ```
+ */
 export declare const ListItem: (props: ListItemProps) => JSX.Element;
 
+/**
+ * Groups related list items under an optional label and can add a trailing
+ * separator.
+ *
+ * The group inherits search settings from its parent list and provides its
+ * resolved density to descendants. Use {@link List} as the parent when items
+ * should share list semantics and configuration.
+ *
+ * @example
+ * ```tsx
+ * <ListItemGroup label="Account">
+ *   <ListItem label="Profile" />
+ * </ListItemGroup>
+ * ```
+ */
 export declare const ListItemGroup: (props: ListItemGroupProps) => JSX.Element;
 
-declare type ListItemGroupProps = Omit<BoxProps, keyof ListItemGroupVariantProps | 'children'> & ListItemGroupVariantProps & {
+/** Props for {@link ListItemGroup}. */
+export declare type ListItemGroupProps = Omit<BoxProps, keyof ListItemGroupVariantProps | 'children'> & ListItemGroupVariantProps & {
+    /** Optional heading displayed above the group's children. */
     label?: string;
+    /** Items or other content belonging to this group. */
     children: BoxProps['children'];
+    /** Displays a separator after the group. */
     divider?: boolean;
+    /**
+     * Density inherited by descendant list items unless they provide their own
+     * value. Responsive recipe values are supported.
+     */
     density?: ListDensity;
 };
 
@@ -2251,20 +3523,64 @@ declare type ListItemGroupVariantProps = {
     [key in keyof ListItemGroupVariant]?: ConditionalValue<ListItemGroupVariant[key]> | undefined
 }
 
-declare type ListItemProps = Omit<BoxProps<'button'>, keyof ListItemVariantProps | 'as' | 'type' | 'href'> & Omit<ListItemVariantProps, 'selected' | 'iconBefore' | 'iconAfter'> & {
+/**
+ * Props for {@link ListItem}. It extends button-like Box props, except its
+ * semantic element and button type are controlled by the component.
+ */
+export declare type ListItemProps = Omit<BoxProps, keyof ListItemVariantProps | 'as' | 'type' | 'href'> & Omit<ListItemVariantProps, 'selected' | 'iconBefore' | 'iconAfter'> & {
+    /** When provided, renders an anchor instead of the default native button. */
     href?: string;
+    /** Content rendered before the default label and description. */
+    before?: ReactNode;
+    /** Primary text rendered when custom `children` are not supplied. */
     label?: string;
+    /** Secondary text rendered below `label` when custom `children` are not supplied. */
     description?: string;
+    /** Search text used to highlight this item's default `label` and `description`. */
     query?: string;
+    /**
+     * Enables highlighting for this item's default text. When omitted, inherits
+     * the nearest {@link List} setting.
+     */
     highlightMatches?: boolean;
+    /**
+     * Native `name` passed to the checkbox or toggle created by the matching
+     * `variant`.
+     *
+     * @default 'list-item'
+     */
     controlName?: string;
+    /**
+     * Runs for the native change event from a checkbox or toggle variant. It
+     * does not update `selected`; update that prop from the owning state.
+     */
     onControlChange?: ChangeEventHandler<HTMLInputElement>;
+    /**
+     * Sets `aria-selected` and selected styling. This is controlled state and
+     * does not change when the item is clicked.
+     *
+     * @default false
+     */
     selected?: boolean;
+    /**
+     * Chooses default content, a checkbox, a toggle, or a noninteractive
+     * divider. The `divider` variant ignores item content and other Box props.
+     *
+     * @default 'default'
+     */
     variant?: ListItemVariantProps['variant'];
+    /**
+     * Overrides the nearest {@link List} or {@link ListItemGroup} density.
+     * Responsive recipe values are supported.
+     */
     density?: ListDensity;
+    /** Icon symbol rendered before the default text content. */
     iconBefore?: IconNamesList;
+    /** Icon symbol rendered after the default text content. */
     iconAfter?: IconNamesList;
+    /** Fill token for `iconBefore`. */
     iconBeforeFill?: IconProps['fill'];
+    /** Fill token for `iconAfter`. */
     iconAfterFill?: IconProps['fill'];
 };
 
@@ -2286,10 +3602,33 @@ declare type ListItemVariantProps = {
     [key in keyof ListItemVariant]?: ConditionalValue<ListItemVariant[key]> | undefined
 }
 
-declare type ListProps = Omit<BoxProps, keyof ListVariantProps | 'children'> & ListVariantProps & {
+/**
+ * Props for {@link List}. Its values are provided to nested list primitives
+ * through list context.
+ */
+export declare type ListProps = Omit<BoxProps, keyof ListVariantProps | 'children'> & ListVariantProps & {
+    /** List items and optional {@link ListItemGroup} sections. */
     children: ReactNode;
+    /**
+     * Shared spacing density for descendants that do not set their own density.
+     * Responsive recipe values are supported.
+     *
+     * @default 'compact'
+     */
     density?: ListDensity;
+    /**
+     * Search text inherited by descendants that do not provide their own
+     * `query`. It is used only when highlighting is enabled.
+     *
+     * @default ''
+     */
     query?: string;
+    /**
+     * Enables highlighting of inherited `query` matches in default
+     * `ListItem` labels and descriptions. Child items can override it.
+     *
+     * @default false
+     */
     highlightMatches?: boolean;
 };
 
@@ -2304,10 +3643,27 @@ declare type ListVariantProps = {
     [key in keyof ListVariant]?: ConditionalValue<ListVariant[key]> | undefined
 }
 
+/**
+ * Displays a keyboard-navigable action list from a trigger or inline in a layout.
+ *
+ * Use `MenuItem`, `MenuGroup`, and `SubMenu` as children. A triggered menu
+ * restores the trigger relationship through Floating UI and dismisses on Escape
+ * or outside press. Use an inline menu when the list should always be visible.
+ *
+ * @example
+ * ```tsx
+ * <Menu trigger={<Button>Actions</Button>}>
+ *   <MenuItem label="Edit" onClick={edit} />
+ *   <MenuItem label="Archive" onClick={archive} />
+ * </Menu>
+ * ```
+ */
 export declare const Menu: (props: MenuProps) => JSX.Element;
 
+/** Spacing density shared by a menu panel and its rows. */
 export declare type MenuDensity = ListDensity;
 
+/** Filtering state consumed by menu compound components. */
 declare type MenuFilterContextValue = {
     query: string;
     filterMode: MenuFilterMode;
@@ -2318,37 +3674,89 @@ declare type MenuFilterContextValue = {
     }) => string;
 };
 
+/** Determines whether `query` hides non-matching menu items. */
 declare type MenuFilterMode = 'none' | 'contains';
 
+/**
+ * Groups related menu rows under an optional label.
+ *
+ * A group is hidden when none of its supported menu children match the parent
+ * menu's active filter.
+ *
+ * @example
+ * ```tsx
+ * <MenuGroup label="File">
+ *   <MenuItem label="Download" />
+ * </MenuGroup>
+ * ```
+ */
 export declare const MenuGroup: (props: MenuGroupProps) => JSX.Element | null;
 
-export declare type MenuGroupProps = BoxProps & {
+declare type MenuGroupOwnProps = {
+    /** Optional group heading. */
     label?: string;
+    /** Menu children shown only when at least one child matches the current filter. */
     children: ReactNode;
+    /** Adds a divider before the group. */
     divider?: boolean;
 };
 
+/** Props for {@link MenuGroup}, a labeled group of related menu children. */
+export declare type MenuGroupProps = Omit<BoxProps, keyof MenuGroupOwnProps> & MenuGroupOwnProps;
+
+/**
+ * Renders an actionable row within a {@link Menu}.
+ *
+ * It renders a button by default, or an anchor when `href` is supplied. Arrow
+ * keys and typeahead participate in the parent menu's roving focus behavior.
+ * Use `variant="checkbox"` or `"toggle"` when `selected` is meaningful.
+ *
+ * @example
+ * ```tsx
+ * <MenuItem label="Duplicate" iconBefore="copy" onClick={duplicate} />
+ * ```
+ */
 export declare const MenuItem: (props: MenuItemProps) => JSX.Element | null;
 
-export declare type MenuItemProps = Omit<BoxProps<'button'>, 'as' | 'ref' | 'onClick' | 'type'> & Omit<MenuVariantProps, 'iconBefore' | 'iconAfter'> & {
+/** Props for {@link MenuItem}, a selectable row inside a {@link Menu}. */
+export declare type MenuItemProps = Omit<BoxProps, 'as' | 'ref' | 'onClick' | 'type'> & Omit<MenuVariantProps, 'iconBefore' | 'iconAfter'> & {
+    /** Primary visible text, also used for typeahead and filtering unless `textValue` is supplied. */
     label?: string;
+    /** Secondary visible text included in filtering by default. */
     description?: string;
+    /**
+     * Chooses a regular item, checkable item, toggle item, or divider.
+     * @default 'default'
+     */
     variant?: MenuItemVariant;
+    /** Prevents activation and marks the row unavailable to assistive technology. */
     disabled?: boolean;
+    /** Sets selected styling and `aria-checked` for checkbox and toggle variants. */
     selected?: boolean;
+    /** Icon displayed before the item text. */
     iconBefore?: IconNamesList;
+    /** Icon displayed after the item text. */
     iconAfter?: IconNamesList;
+    /** Renders the item as an anchor instead of a button. */
     href?: string;
+    /** Browsing context for an anchor item. */
     target?: string;
+    /** Relationship attribute for an anchor item, such as `noopener` for a new tab. */
     rel?: string;
+    /** Overrides the parent menu's `closeOnSelect` behavior for this item. */
     closeOnSelect?: boolean;
+    /** Overrides the parent menu's row density for this item. */
     density?: MenuDensity;
+    /** Explicit text used for typeahead and filtering instead of label and description. */
     textValue?: string;
+    /** Called for pointer selection before the menu closes. Call `event.preventDefault()` to prevent the automatic close and tree click event. */
     onClick?: (event: MouseEvent_2<HTMLElement>) => void;
 };
 
+/** Visual and ARIA role variants supported by {@link MenuItem}. */
 export declare type MenuItemVariant = 'default' | 'checkbox' | 'toggle' | 'divider';
 
+/** Roving-focus state for one menu level. */
 declare type MenuListContextValue = {
     activeIndex: number | null;
     getItemProps: (userProps?: HTMLProps<HTMLElement>) => HTMLProps<HTMLElement>;
@@ -2360,30 +3768,96 @@ declare type MenuListContextValue = {
     closeParentSubMenuFlyout?: () => void;
 };
 
-export declare type MenuProps = {
+declare type MenuOwnProps = {
+    /** Trigger element cloned with the menu's event handlers and ARIA attributes. Omit it, or use `inline`, to render the menu in place. */
     trigger?: ReactElement;
+    /** `MenuItem`, `MenuGroup`, and `SubMenu` children that make up the menu. */
     children: ReactNode;
+    /** Controlled popup state. Pair with `onOpenChange`; omit it to use `defaultOpen`. */
     open?: boolean;
+    /**
+     * Initial popup state for an uncontrolled triggered menu. It is used only on first render.
+     * @default false
+     */
     defaultOpen?: boolean;
+    /** Called when interaction requests that a triggered menu open or close. */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Floating UI placement of a triggered menu relative to its trigger.
+     * @default 'bottom-start'
+     */
     placement?: Placement;
+    /**
+     * Positioning strategy for a triggered menu.
+     * @default 'absolute'
+     */
     strategy?: 'absolute' | 'fixed';
+    /**
+     * Closes the root menu after a `MenuItem` is selected unless that item overrides it.
+     * @default true
+     */
     closeOnSelect?: boolean;
+    /**
+     * Renders the panel in normal document flow without requiring a trigger.
+     * @default false
+     */
     inline?: boolean;
+    /**
+     * Pointer interactions that open the trigger.
+     * @default 'click'
+     */
     triggerInteraction?: MenuTriggerInteraction;
+    /**
+     * Delay before hover interaction opens the menu, in milliseconds.
+     * @default 75
+     */
     triggerOpenDelay?: number;
+    /**
+     * Delay before hover interaction closes the menu, in milliseconds.
+     * @default 100
+     */
     triggerCloseDelay?: number;
+    /**
+     * Default presentation for descendant `SubMenu` components.
+     * @default 'hover'
+     */
     subMenuInteraction?: SubMenuInteraction;
+    /**
+     * Spacing density for menu rows.
+     * @default 'compact'
+     */
     density?: MenuDensity;
+    /**
+     * Text used to filter `MenuItem` and `SubMenu` labels when `filterMode` is `'contains'`.
+     * @default ''
+     */
     query?: string;
+    /** Reserved for external filtering controls; this component does not call it. */
     onQueryChange?: (query: string) => void;
+    /**
+     * Enables case-insensitive substring filtering when set to `'contains'`.
+     * @default 'none'
+     */
     filterMode?: MenuFilterMode;
+    /**
+     * Content rendered when filtering leaves no visible menu children.
+     * @default 'No results found'
+     */
     renderNoResults?: ReactNode;
+    /**
+     * Highlights case-insensitive query matches in visible labels and descriptions.
+     * @default Boolean(query)
+     */
     highlightMatches?: boolean;
+    /**
+     * Derives searchable text when an item does not provide `textValue`. It receives the item's label and description.
+     * @default joins label and description with a space
+     */
     getItemText?: (item: {
         label?: string;
         description?: string;
     }) => string;
+    /** Applies the recipe's panel visual treatment. */
     panel?: MenuVariantProps['panel'];
     /**
      * When this `Menu` is used as one section of a horizontal menubar, pass a
@@ -2396,16 +3870,37 @@ export declare type MenuProps = {
      * row and horizontal menubar keys would not run on the trigger).
      */
     onMenubarEdgeNavigate?: (direction: 1 | -1) => void;
-} & BoxProps;
+};
 
+/** Props for {@link Menu}, including popup state, filtering, and nested-menu behavior. */
+export declare type MenuProps = Omit<BoxProps, keyof MenuOwnProps> & MenuOwnProps;
+
+/**
+ * Provides menu root and filter context for custom compound-menu composition.
+ *
+ * Normal menus provide this context automatically. Use this provider only when
+ * composing `MenuItem`, `MenuGroup`, or `SubMenu` outside a `Menu`.
+ *
+ * @example
+ * ```tsx
+ * <MenuProvider>
+ *   <MenuItem label="Refresh" />
+ * </MenuProvider>
+ * ```
+ */
 export declare const MenuProvider: ({ children, root, filter }: MenuProviderProps) => JSX.Element;
 
+/** Props for {@link MenuProvider}, an escape hatch for custom menu composition. */
 export declare type MenuProviderProps = {
+    /** Descendants that consume the supplied menu contexts. */
     children: ReactNode;
+    /** Partial root behavior merged with the normal menu defaults. */
     root?: Partial<MenuRootContextValue>;
+    /** Partial filtering behavior merged with the normal menu defaults. */
     filter?: Partial<MenuFilterContextValue>;
 };
 
+/** Shared root behavior consumed by menu compound components. */
 declare type MenuRootContextValue = {
     density: MenuDensity;
     panel?: MenuVariantProps['panel'];
@@ -2420,7 +3915,8 @@ declare type MenuRootContextValue = {
     onMenubarEdgeNavigate?: (direction: 1 | -1) => void;
 };
 
-declare type MenuTriggerInteraction = 'click' | 'hover' | 'click-and-hover';
+/** Pointer or focus interactions that can open a menu trigger. */
+declare type MenuTriggerInteraction = 'click' | 'hover' | 'focus' | 'click-and-hover';
 
 declare interface MenuVariant {
     /**
@@ -2434,54 +3930,119 @@ declare type MenuVariantProps = {
     [key in keyof MenuVariant]?: ConditionalValue<MenuVariant[key]> | undefined
 }
 
+/**
+ * Renders a controlled modal dialog in a portal with focus management and a
+ * scroll-locking overlay.
+ *
+ * Escape always calls `onOpenChange(false)`. By default, pressing the overlay
+ * does too. The dialog remains mounted for a 150 ms closing animation. Supply
+ * an accessible name through `aria-label` or `aria-labelledby`; a visible
+ * `ModalHeader` title alone is not linked automatically.
+ *
+ * @example
+ * ```tsx
+ * <Modal open={open} onOpenChange={setOpen} aria-label="Delete project">
+ *   <ModalHeader title="Delete project" />
+ *   <ModalBody>This cannot be undone.</ModalBody>
+ *   <ModalFooter><Button onClick={remove}>Delete</Button></ModalFooter>
+ * </Modal>
+ * ```
+ */
 export declare const Modal: (props: ModalProps) => JSX.Element | null;
 
+/**
+ * Renders the main content region of a {@link Modal}.
+ *
+ * @example
+ * ```tsx
+ * <ModalBody>Changes are saved automatically.</ModalBody>
+ * ```
+ */
 export declare const ModalBody: (props: ModalBodyProps) => JSX.Element;
 
-declare type ModalBodyProps = Omit<BoxProps, 'children'> & {
-    /** Body content */
+/** Props for {@link ModalBody}, the main content region of a modal. */
+export declare type ModalBodyProps = Omit<BoxProps, 'children'> & {
+    /** Content displayed in the modal's body region. */
     children: ReactNode;
 };
 
+/** State and close behavior shared with descendants of {@link Modal}. */
 declare interface ModalContextValue {
-    /** Whether the modal is open */
+    /** Whether the modal is currently in its open phase. */
     open: boolean;
-    /** Callback to close the modal */
+    /** Requests closing through the parent modal's `onOpenChange(false)`. */
     onClose: () => void;
-    /** Whether overlay clicks should close the modal */
+    /** Whether the parent modal blocks overlay-triggered closing. */
     preventOverlayClose?: boolean;
 }
 
+/**
+ * Renders the action region of a {@link Modal}.
+ *
+ * @example
+ * ```tsx
+ * <ModalFooter><Button>Save</Button></ModalFooter>
+ * ```
+ */
 export declare const ModalFooter: (props: ModalFooterProps) => JSX.Element;
 
-declare type ModalFooterProps = Omit<BoxProps, 'children'> & {
-    /** Footer content (typically action buttons) */
+/** Props for {@link ModalFooter}, the action region of a modal. */
+export declare type ModalFooterProps = Omit<BoxProps, 'children'> & {
+    /** Content displayed in the footer, typically dialog action buttons. */
     children: ReactNode;
 };
 
+/**
+ * Renders the optional header region of a parent {@link Modal}.
+ *
+ * Use `title` for the standard heading or provide `children` for custom header
+ * content. It must be rendered inside `Modal` because it uses modal context to
+ * close the dialog.
+ *
+ * @example
+ * ```tsx
+ * <ModalHeader title="Edit profile" />
+ * ```
+ */
 export declare const ModalHeader: (props: ModalHeaderProps) => JSX.Element;
 
-declare type ModalHeaderProps = Omit<BoxProps, 'children'> & {
-    /** Title text */
+/** Props for {@link ModalHeader}, the optional heading and close-control region. */
+export declare type ModalHeaderProps = Omit<BoxProps, 'children'> & {
+    /** Text rendered as the default level-three heading when `children` is omitted. */
     title?: string;
-    /** Whether to show the close button */
+    /**
+     * Shows the built-in button that calls the parent modal's `onOpenChange(false)`.
+     * @default true
+     */
     showCloseButton?: boolean;
-    /** Children (custom header content) */
+    /** Custom header content. When supplied, it replaces both `title` and the built-in close button. */
     children?: ReactNode;
 };
 
-declare type ModalProps = Omit<BoxProps, keyof ModalVariantProps> & ModalVariantProps & {
-    /** Controlled open state (REQUIRED) */
+/** Props for {@link Modal}, a controlled, portalled dialog. */
+export declare type ModalProps = Omit<BoxProps, keyof ModalVariantProps> & ModalVariantProps & {
+    /** Controlled dialog state. Render state changes by updating this value after `onOpenChange`. */
     open: boolean;
-    /** Callback when open state should change (REQUIRED) */
+    /** Called when Escape, overlay interaction, or a descendant close control requests closing. */
     onOpenChange: (open: boolean) => void;
-    /** Whether clicking the overlay should close the modal */
+    /**
+     * Prevents overlay clicks from requesting close. Escape still requests close.
+     * @default false
+     */
     preventOverlayClose?: boolean;
-    /** Children (ModalHeader, ModalBody, ModalFooter) */
+    /** Dialog content, typically composed from `ModalHeader`, `ModalBody`, and `ModalFooter`. */
     children: ReactNode;
-    /** Optional ID for ARIA attributes */
+    /** Identifier applied to the dialog element. Provide accessible naming with `aria-label` or `aria-labelledby`. */
     id?: string;
+    /**
+     * Recipe size for the dialog panel.
+     * @default 'md'
+     */
     size?: ModalVariantProps['size'];
+    /**
+     * Recipe position for the dialog panel.
+     * @default 'centered'
+     */
     position?: ModalVariantProps['position'];
 };
 
@@ -2592,6 +4153,24 @@ declare interface ModernCssProperties {
     WebkitTextSecurity?: Globals | 'none' | 'circle' | 'disc' | 'square'
 }
 
+/** Props for a multiple-selection {@link Autocomplete}. */
+declare type MultipleAutocompleteProps = AutocompleteBaseProps & {
+    /** Enables multiple selection and renders selected values as tokens. */
+    multiple: true;
+    /** Controlled selected values. Pair with `onValueChange`. */
+    value?: AutocompleteValue<true>;
+    /** Initial selected values when `value` is not provided. */
+    defaultValue?: AutocompleteValue<true>;
+    /** Runs when selection, removal, clearing, or creation requests new values. */
+    onValueChange?: (value: AutocompleteValue<true>, reason: AutocompleteChangeReason) => void;
+    /**
+     * Runs when the selected values change.
+     *
+     * @deprecated Use `onValueChange`.
+     */
+    onChange?: (value: AutocompleteValue<true>, reason: AutocompleteChangeReason) => void;
+};
+
 declare type Nested<P> = P & {
     [K in Selectors]?: Nested<P>
 } & {
@@ -2602,6 +4181,162 @@ declare type Nested<P> = P & {
 
 declare type Number_2 = number & {}
 
+declare const numericSizes: {
+    '0': {
+        value: string;
+    };
+    '1': {
+        value: string;
+    };
+    '2': {
+        value: string;
+    };
+    '3': {
+        value: string;
+    };
+    '4': {
+        value: string;
+    };
+    '5': {
+        value: string;
+    };
+    '6': {
+        value: string;
+    };
+    '7': {
+        value: string;
+    };
+    '8': {
+        value: string;
+    };
+    '9': {
+        value: string;
+    };
+    '10': {
+        value: string;
+    };
+    '12': {
+        value: string;
+    };
+    '14': {
+        value: string;
+    };
+    '16': {
+        value: string;
+    };
+    '18': {
+        value: string;
+    };
+    '20': {
+        value: string;
+    };
+    '22': {
+        value: string;
+    };
+    '24': {
+        value: string;
+    };
+    '28': {
+        value: string;
+    };
+    '32': {
+        value: string;
+    };
+    '40': {
+        value: string;
+    };
+    '48': {
+        value: string;
+    };
+    '56': {
+        value: string;
+    };
+    '64': {
+        value: string;
+    };
+    '72': {
+        value: string;
+    };
+    '80': {
+        value: string;
+    };
+    '88': {
+        value: string;
+    };
+    '96': {
+        value: string;
+    };
+    '104': {
+        value: string;
+    };
+    '112': {
+        value: string;
+    };
+    '120': {
+        value: string;
+    };
+    '128': {
+        value: string;
+    };
+    '136': {
+        value: string;
+    };
+    '144': {
+        value: string;
+    };
+    '152': {
+        value: string;
+    };
+    '160': {
+        value: string;
+    };
+    '168': {
+        value: string;
+    };
+    '176': {
+        value: string;
+    };
+    '184': {
+        value: string;
+    };
+    '192': {
+        value: string;
+    };
+    '200': {
+        value: string;
+    };
+    '208': {
+        value: string;
+    };
+    '216': {
+        value: string;
+    };
+    '224': {
+        value: string;
+    };
+    '232': {
+        value: string;
+    };
+    '240': {
+        value: string;
+    };
+    '248': {
+        value: string;
+    };
+    '256': {
+        value: string;
+    };
+    '264': {
+        value: string;
+    };
+    '272': {
+        value: string;
+    };
+    '280': {
+        value: string;
+    };
+};
+
 declare type NumericSizeToken = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "12" | "14" | "16" | "18" | "20" | "22" | "24" | "28" | "32" | "40" | "48" | "56" | "64" | "72" | "80" | "88" | "96" | "104" | "112" | "120" | "128" | "136" | "144" | "152" | "160" | "168" | "176" | "184" | "192" | "200" | "208" | "216" | "224" | "232" | "240" | "248" | "256" | "264" | "272" | "280"
 
 declare interface ObsoleteProperties<TLength = (string & {}) | 0, TTime = string & {}> {
@@ -3663,6 +5398,38 @@ declare type ObsoletePropertiesFallback<TLength = (string & {}) | 0, TTime = str
 
 declare type OmittedHTMLProps = 'color' | 'translate' | 'transition' | 'width' | 'height' | 'content'
 
+/**
+ * Declares selectable metadata for a parent `Autocomplete`.
+ *
+ * `Option` renders no DOM by itself. Place it directly inside `Autocomplete`;
+ * the parent builds the visible listbox and selection behavior.
+ *
+ * @example
+ * ```tsx
+ * <Autocomplete aria-label="Assignee">
+ *   <Option value="ada" label="Ada Lovelace" />
+ * </Autocomplete>
+ * ```
+ */
+declare const Option_2: (_props: OptionProps) => null;
+export { Option_2 as Option }
+
+/** Metadata accepted by an {@link Option} inside `Autocomplete`. */
+export declare type OptionProps = {
+    /** Stable value reported when this option is selected. */
+    value: string;
+    /** Visible option text and selected-value label. */
+    label: string;
+    /** Prevents the option from receiving navigation or selection. */
+    disabled?: boolean;
+    /** Secondary text included when filtering options. */
+    description?: string;
+    /** Icon rendered before the option label. */
+    iconLeft?: IconNamesList;
+    /** Icon rendered after the option label. */
+    iconRight?: IconNamesList;
+};
+
 export declare namespace Panda {
     export type RecipeConfig<V extends RecipeVariantRecord = RecipeVariantRecord> = BaseRecipeConfig<V>;
     export type SlotRecipeConfig<S extends string = string, V extends SlotRecipeVariantRecord<S> = SlotRecipeVariantRecord<S>> = BaseSlotRecipeConfig<S, V>;
@@ -3688,6 +5455,10 @@ export declare type PatternConfig<T extends PatternProperties = PatternPropertie
 
 export declare type PatternProperties = Record<string, unknown>;
 
+/**
+ * Combines custom props with the compatible native props and ref for the
+ * element selected by `as`.
+ */
 declare type PolymorphicComponentProps<T extends ElementType, Props extends object = object> = Props & AsProp<T> & Omit<ComponentPropsWithRef<T>, PropsToOmit<T, Props>>;
 
 declare type PositionAreaAxis =
@@ -3754,14 +5525,31 @@ declare type PositionTry =
 | 'inline-end'
 | DashedIdent
 
+/**
+ * Renders a preformatted code block using native `pre` and `code` semantics.
+ *
+ * Whitespace in string content is preserved. The component does not perform
+ * syntax highlighting.
+ *
+ * @example
+ * ```tsx
+ * <Pre lang="typescript">{'const ready = true;'}</Pre>
+ * ```
+ */
 export declare const Pre: (props: PreProps) => JSX.Element;
 
-declare type PreProps = BoxProps & {
+declare type PreOwnProps = {
+    /** Preformatted code content. */
     children: string | ReactNode;
+    /** Language metadata forwarded to the nested `Code` element. */
     lang?: string;
+    /** Element override for the rendered `pre` container. */
     as?: string;
 };
 
+/** Props accepted by {@link Pre}. */
+export declare type PreProps = Omit<BoxProps, keyof PreOwnProps> & PreOwnProps;
+
 declare interface PropertiesFallback<TLength = (string & {}) | 0, TTime = string & {}>
 extends StandardPropertiesFallback<TLength, TTime>,
 VendorPropertiesFallback<TLength, TTime>,
@@ -5512,68 +7300,117 @@ declare namespace Property {
     type VectorEffect = Globals | "non-scaling-stroke" | "none";
 }
 
+/** Record of native attributes and Panda CSS properties accepted by `splitProps`. */
 declare type PropsRecord = Record<string, unknown>;
 
 declare type PropsToOmit<T extends ElementType, P extends object> = keyof (AsProp<T> & P);
 
 declare type Pseudos = AdvancedPseudos | SimplePseudos;
 
+/** Direction used when comparing a viewport or container size token. */
 declare type QueryDirection = 'min' | 'max';
 
+/** Direction used when comparing a viewport or container size token. */
 declare type QueryDirection_2 = 'min' | 'max';
 
 /**
- * Radio supports both controlled and uncontrolled usage.
+ * A native radio control without a visible label.
+ *
+ * Prefer {@link RadioInput} inside {@link RadioGroup} for a labelled,
+ * keyboard-navigable choice group. For standalone use, group radios by `name`
+ * and associate each with a label using `id`. Use `checked` with `onChange` for
+ * controlled state, or `defaultChecked` only for uncontrolled state.
  *
  * @example
- * <Radio defaultChecked />
+ * ```tsx
+ * <Radio name="shipping" defaultChecked />
+ * ```
  *
  * @example
+ * ```tsx
  * const [checked, setChecked] = useState(false);
- * <Radio checked={checked} onChange={(e) => setChecked(e.target.checked)} />
+ * <Radio name="shipping" checked={checked} onChange={(event) => setChecked(event.target.checked)} />
+ * ```
  */
 export declare const Radio: (props: RadioProps) => JSX.Element;
 
 /**
- * Helper type for radio change events
+ * Native change event emitted by {@link Radio}.
  * @example
  * const handleChange: RadioChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type RadioChangeEvent = ChangeEvent<HTMLInputElement>;
+export declare type RadioChangeEvent = ChangeEvent<HTMLInputElement>;
 
 /**
- * Helper type for radio change handler functions
+ * Handler for a {@link Radio} native change event.
  * @example
  * const handleChange: RadioChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type RadioChangeHandler = (e: RadioChangeEvent) => void;
+export declare type RadioChangeHandler = (e: RadioChangeEvent) => void;
 
+/**
+ * Coordinates a mutually exclusive set of {@link RadioInput} controls.
+ *
+ * It renders a `radiogroup` and shares its name, selected value, and disabled
+ * state through context. Each grouped `RadioInput` needs a `value`; its native
+ * radio behavior provides arrow-key navigation. Use `value` with `onChange` for
+ * controlled state or `defaultValue` for uncontrolled state, never both.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup name="size" defaultValue="medium" label="Size">
+ *   <RadioInput value="small">Small</RadioInput>
+ *   <RadioInput value="medium">Medium</RadioInput>
+ * </RadioGroup>
+ * ```
+ */
 export declare const RadioGroup: (props: RadioGroupProps) => JSX.Element;
 
-declare type RadioGroupProps = Omit<BoxProps, 'children' | 'role'> & {
-    name: string;
-    value?: string | null;
+/** Props for {@link RadioGroup}, which coordinates descendant {@link RadioInput} controls. */
+export declare type RadioGroupProps = Omit<BoxProps, 'children' | 'role'> & {
+    /** Shared native name for descendant grouped radios. */ name: string;
+    /** Controlled selected value. Pair with `onChange`; use `null` for no selection. */ value?: string | null;
+    /** Initial uncontrolled selected value; later updates are ignored. */
+    /** @default null */
     defaultValue?: string | null;
-    onChange?: (value: string) => void;
-    children: ReactNode;
-    label?: string;
-    id?: string;
-    disabled?: boolean;
+    /** Runs with the selected child `value` after a grouped radio changes. */ onChange?: (value: string) => void;
+    /** Grouped `RadioInput` children. */ children: ReactNode;
+    /** Accessible name applied as `aria-label`. Use when no separate visible group label is available. */ label?: string;
+    /** Group ID. When supplied, descendants should provide an element with `${id}-label` as the visible group label. */ id?: string;
+    /** Disables descendant grouped radios unless a child explicitly supplies `disabled`. */ disabled?: boolean;
 };
 
+/**
+ * A labelled radio option.
+ *
+ * Place it in {@link RadioGroup} with a unique `value` to receive shared
+ * selection state, its name, and group-disabled state. Outside a group it acts
+ * like a labelled {@link Radio}; supply `name` to form a native radio group.
+ * Explicit `disabled` wins over group and field context.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup name="plan" defaultValue="standard" label="Plan">
+ *   <RadioInput value="standard">Standard</RadioInput>
+ * </RadioGroup>
+ * ```
+ */
 export declare const RadioInput: (props: RadioInputProps) => JSX.Element;
 
-declare type RadioInputProps = Omit<BoxProps, keyof RadioInputVariantProps> & RadioInputVariantProps & {
-    name?: string;
-    value?: string;
-    checked?: boolean;
+/** Props for {@link RadioInput}, a labelled radio that can join a {@link RadioGroup}. */
+export declare type RadioInputProps = Omit<BoxProps, keyof RadioInputVariantProps> & RadioInputVariantProps & {
+    /** Native group name when the input is not inside a `RadioGroup`; group context takes precedence. */ name?: string;
+    /** Value reported to the nearest `RadioGroup`; required for the input to participate in that group. */ value?: string;
+    /** Controlled state for standalone use. Group context takes precedence when `value` is supplied. */ checked?: boolean;
+    /** Initial standalone selected state; ignored for grouped radios and after mount. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: RadioChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    children?: string | ReactNode;
-    disabled?: boolean;
+    /** Runs after group selection is requested and for standalone native changes. The group `onChange` receives the selected value. */ onChange?: RadioChangeHandler;
+    /** Input ID. A stable ID is generated when omitted and associated with the wrapper label. */ id?: string;
+    /** Applies error styling, overriding field context. */ error?: boolean;
+    /** Marks the radio invalid, overriding field context. */ invalid?: boolean;
+    /** Visible label content. */ children?: string | ReactNode;
+    /** Disables the radio, overriding group and field context. */ disabled?: boolean;
 };
 
 declare interface RadioInputVariant {
@@ -5584,15 +7421,18 @@ declare type RadioInputVariantProps = {
     [key in keyof RadioInputVariant]?: ConditionalValue<RadioInputVariant[key]> | undefined
 }
 
-declare type RadioProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof RadioVariantProps> & RadioVariantProps & {
-    name?: string;
-    checked?: boolean;
+/** Props for {@link Radio}, the unlabelled native radio primitive. */
+export declare type RadioProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof RadioVariantProps> & RadioVariantProps & {
+    /** Native radio group name. Radios with the same name are mutually exclusive. */ name?: string;
+    /** Controlled selected state. Pair with `onChange`; do not combine with `defaultChecked`. */ checked?: boolean;
+    /** Initial selected state for uncontrolled use; later updates are ignored. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: RadioChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    disabled?: boolean;
+    /** Runs for the native input change event when this radio becomes selected. */ onChange?: RadioChangeHandler;
+    /** Native input ID used by an external label. */ id?: string;
+    /** Applies error styling, overriding field context. */ error?: boolean;
+    /** Marks the native input invalid with `aria-invalid`, overriding field context. */ invalid?: boolean;
+    /** Disables interaction, overriding field context. */ disabled?: boolean;
 };
 
 declare interface RadioVariant {
@@ -5609,38 +7449,333 @@ export declare type RecipeConfig<V extends RecipeVariantRecord = RecipeVariantRe
 
 export declare type RecipeVariantRecord = Record<string, Record<string, unknown> | string | number | boolean | null | undefined>;
 
+/**
+ * Edits a date as separate year, month, and day spinbutton segments.
+ *
+ * The component clamps days to the selected month and emits only complete
+ * dates or a fully cleared `null` value. Use `DateInput` when leading or
+ * trailing slots and field validation styling are needed.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedDate defaultValue={{ year: 2026, month: 8, day: 3 }} />
+ * ```
+ */
+export declare const SegmentedDate: (props: SegmentedDateProps) => JSX.Element;
+
+declare type SegmentedDateFormat = DateFormat;
+
+/** Props for {@link SegmentedDate}, a keyboard-editable date field. */
+export declare type SegmentedDateProps = Omit<BoxProps, keyof SegmentedInputsVariantProps | 'children' | 'onChange' | 'value'> & SegmentedInputVariantProps & {
+    /** Ref attached to the segmented group container. */
+    ref?: Ref<HTMLDivElement>;
+    /** Controlled date. Pair with `onChange`; `null` clears every segment. */
+    value?: DateValue | null;
+    /** Initial date when `value` is not provided. */
+    defaultValue?: DateValue | null;
+    /** Runs after all date segments form a date, or after every segment is cleared. */
+    onChange?: (value: DateValue | null) => void;
+    /**
+     * Segment order and default separator.
+     *
+     * @default 'YYYY-MM-DD'
+     */
+    format?: SegmentedDateFormat;
+    /** Overrides separator content or spacing between date segments. */
+    separators?: SeparatorConfig;
+    /**
+     * Accessible name for the segmented group.
+     *
+     * @default 'Date'
+     */
+    label?: string;
+    /** Prevents editing and keyboard interaction. */
+    disabled?: boolean;
+    /** Runs when focus enters any date segment. */
+    onFocusWithin?: () => void;
+    /** Runs when focus leaves a date segment and provides the next focused node. */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+declare interface SegmentedFieldsVariant {
+    /**
+     * @default "md"
+     */
+    size: "sm" | "md" | "lg" | "xl"
+    field: "date" | "time" | "dateTime"
+    range: "date" | "time"
+    before: boolean
+    after: boolean
+}
+
+declare type SegmentedFieldsVariantProps = {
+    [key in keyof SegmentedFieldsVariant]?: ConditionalValue<SegmentedFieldsVariant[key]> | undefined
+}
+
+/**
+ * Renders a keyboard-editable group of numeric and choice segments.
+ *
+ * This is the low-level primitive used by `SegmentedDate` and
+ * `SegmentedTime`. Each segment uses spinbutton semantics; arrow keys step
+ * values, number or choice keys enter values, and focus advances between
+ * completed numeric segments.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedInput
+ *   label="Quantity"
+ *   items={[{
+ *     type: 'segment', kind: 'numeric', id: 'quantity',
+ *     label: 'Quantity', placeholder: '0', value: null,
+ *     min: 0, max: 99, digits: 2,
+ *   }]}
+ * />
+ * ```
+ */
+export declare const SegmentedInput: (props: SegmentedInputProps) => JSX.Element;
+
+/** Change payload containing the complete value map and changed segment. */
+declare type SegmentedInputChange = {
+    values: SegmentedInputValueMap;
+    changedSegmentId: string;
+};
+
+/** Editable segment or visual separator accepted by `SegmentedInput`. */
+export declare type SegmentedInputItem = SegmentItem | SeparatorItem;
+
+/** Props for the low-level {@link SegmentedInput} composition primitive. */
+export declare type SegmentedInputProps = Omit<BoxProps, keyof SegmentedInputsVariantProps | 'children' | 'onChange' | 'value'> & SegmentedInputVariantProps_2 & {
+    /** Ref attached to the segment group container. */
+    ref?: Ref<HTMLDivElement>;
+    /** Ordered editable segments and visual separators. */
+    items: readonly SegmentedInputItem[];
+    /** Accessible name announced for the complete group. */
+    label: string;
+    /** Prevents editing and keyboard interaction. Overrides field context. */
+    disabled?: boolean;
+    /** Controlled values keyed by segment identifier. */
+    value?: SegmentedInputValueMap;
+    /** Runs after a segment changes with the complete next value map. */
+    onChange?: (change: SegmentedInputChange) => void;
+    /** Runs when focus enters any editable segment. */
+    onFocusWithin?: () => void;
+    /** Runs when focus leaves a segment and provides the next focused node. */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+declare interface SegmentedInputsVariant {
+    /**
+     * @default "md"
+     */
+    size: "sm" | "md" | "lg" | "xl"
+}
+
+declare type SegmentedInputsVariantProps = {
+    [key in keyof SegmentedInputsVariant]?: ConditionalValue<SegmentedInputsVariant[key]> | undefined
+}
+
+/** Current segment values keyed by each segment's stable identifier. */
+export declare type SegmentedInputValueMap = Record<string, SegmentValue>;
+
+declare type SegmentedInputVariantProps = Omit<SegmentedInputsVariantProps, 'bare'>;
+
+declare type SegmentedInputVariantProps_2 = Omit<SegmentedInputsVariantProps, 'bare'>;
+
+declare type SegmentedInputVariantProps_3 = Omit<SegmentedInputsVariantProps, 'bare'>;
+
+/**
+ * Edits a time as separate hour, minute, and optional meridiem segments.
+ *
+ * Display may use 12- or 24-hour time, but values always store hours from 0
+ * through 23. Use `TimeInput` when leading or trailing slots and field
+ * validation styling are needed.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedTime defaultValue={{ hour: 13, minute: 30 }} timeFormat="12" />
+ * ```
+ */
+export declare const SegmentedTime: (props: SegmentedTimeProps) => JSX.Element;
+
+/** Props for {@link SegmentedTime}, a keyboard-editable time field. */
+export declare type SegmentedTimeProps = Omit<BoxProps, keyof SegmentedInputsVariantProps | 'children' | 'onChange' | 'value'> & SegmentedInputVariantProps_3 & {
+    /** Ref attached to the segmented group container. */
+    ref?: Ref<HTMLDivElement>;
+    /** Controlled 24-hour time value. Pair with `onChange`. */
+    value?: TimeValue | null;
+    /** Initial time when `value` is not provided. */
+    defaultValue?: TimeValue | null;
+    /** Runs when the hour and minute segments form a complete time. */
+    onChange?: (value: TimeValue | null) => void;
+    /**
+     * Display cycle; emitted values always use 24-hour hours.
+     *
+     * @default '12'
+     */
+    timeFormat?: TimeFormat;
+    /**
+     * Minute increment used by keyboard stepping. Unsupported values are normalized.
+     *
+     * @default 1
+     */
+    minuteStep?: number;
+    /** Overrides content or spacing around time and meridiem separators. */
+    separators?: {
+        time?: SeparatorConfig;
+        meridiem?: SeparatorConfig;
+    };
+    /**
+     * Accessible name for the segmented group.
+     *
+     * @default 'Time'
+     */
+    label?: string;
+    /** Prevents editing and keyboard interaction. */
+    disabled?: boolean;
+    /** Runs when focus enters any time segment. */
+    onFocusWithin?: () => void;
+    /** Runs when focus leaves a time segment and provides the next focused node. */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+/** Metadata for an editable numeric or choice segment. */
+declare type SegmentItem = {
+    type: 'segment';
+    id: string;
+    label: string;
+    placeholder: string;
+    value: SegmentValue;
+    disabled?: boolean;
+} & ({
+    kind: 'numeric';
+    min: number;
+    max: number;
+    digits: number;
+    step?: number;
+    format?: (value: number) => string;
+    clampValue?: (value: number, values: SegmentedInputValueMap) => number;
+} | {
+    kind: 'choice';
+    choices: readonly string[];
+    inputKeys?: Record<string, string>;
+});
+
+/** Value stored by one editable segment. */
+declare type SegmentValue = number | string | null;
+
+/**
+ * Chooses one or more values from metadata-only {@link SelectOption} children.
+ *
+ * The trigger uses combobox/listbox semantics. Arrow keys, Enter, and Space open
+ * it; typeahead and arrow keys navigate options; Escape or outside press closes
+ * it. Focus stays on the trigger when the non-modal popup opens.
+ *
+ * @example
+ * ```tsx
+ * <Select defaultValue="draft" name="status">
+ *   <SelectOption value="draft" label="Draft" />
+ *   <SelectOption value="published" label="Published" />
+ * </Select>
+ * ```
+ */
 export declare const Select: (props: SelectProps) => JSX.Element;
 
+/**
+ * Declares an option for a parent {@link Select}.
+ *
+ * This component returns `null`; place it directly inside `Select` so the
+ * parent can interpret its metadata.
+ *
+ * @example
+ * ```tsx
+ * <SelectOption value="medium" label="Medium" />
+ * ```
+ */
 export declare const SelectOption: (_props: SelectOptionProps) => null;
 
+/** Metadata consumed by {@link Select}; `SelectOption` does not render an element itself. */
 export declare type SelectOptionProps = Omit<BoxProps, 'children'> & {
+    /** Stable value emitted by the parent `Select`. */
     value: string;
+    /** Visible option text and the value used for keyboard typeahead. */
     label: string;
+    /** Excludes the option from pointer and keyboard selection. */
     disabled?: boolean;
+    /** Supporting text displayed below the label in the popup. */
     description?: string;
+    /** Icon displayed before the option label. */
     iconLeft?: IconNamesList;
+    /** Icon displayed after the option label. */
     iconRight?: IconNamesList;
 };
 
 declare type Selectors = AttributeSelector | ParentSelector
 
-export declare type SelectProps = Omit<BoxProps<'button'>, keyof SelectVariantProps | 'children' | 'onChange' | 'type' | 'value'> & SelectVariantProps & {
+/** Props for {@link Select}, an ARIA listbox-based single or multiple select. */
+export declare type SelectProps = Omit<BoxProps, keyof SelectVariantProps | 'children' | 'onChange' | 'type' | 'value'> & SelectVariantProps & {
+    /** Controlled selected value. Use a string for single selection or a string array for multiple selection, with `onChange` to accept changes. */
     value?: SelectValue;
+    /**
+     * Initial selected value for an uncontrolled select. It is used only on first render.
+     * @default null
+     */
     defaultValue?: SelectValue;
+    /** Called when the user selects, deselects, or clears an option. In controlled mode, update `value` with the supplied value. */
     onChange?: (value: SelectValue) => void;
+    /**
+     * Allows several options to be selected and renders selected options as removable chips.
+     * @default false
+     */
     multiple?: boolean;
+    /**
+     * Text shown while no option is selected.
+     * @default 'Select...'
+     */
     placeholder?: string;
+    /** Controlled popup state. Pair with `onOpenChange`; omit it to use `defaultOpen`. */
     open?: boolean;
+    /**
+     * Initial popup state for an uncontrolled select. It is used only on first render.
+     * @default false
+     */
     defaultOpen?: boolean;
+    /** Called when user interaction requests that the popup open or close. */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Floating UI placement for the listbox relative to the trigger.
+     * @default 'bottom-start'
+     */
     placement?: Placement;
+    /**
+     * Gap between the trigger and listbox, in pixels.
+     * @default 4
+     */
     offset?: number;
+    /** Metadata-only `SelectOption` children used to build the listbox. Other children are ignored. */
     children?: ReactNode;
+    /** Identifier for the combobox trigger. A generated identifier is used when omitted. */
     id?: string;
+    /** Form field name. Each selected value is submitted through a hidden input. */
     name?: string;
+    /**
+     * Prevents opening, selection, and hidden-input submission.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Marks the combobox as invalid with `aria-invalid` and error styling.
+     * @default false
+     */
     error?: boolean;
+    /**
+     * Density applied to the popup options.
+     * @default 'compact'
+     */
     density?: MenuDensity;
+    /**
+     * Shrinks the trigger to its content instead of using the standard select width.
+     * @default false
+     */
     autoSize?: boolean;
 };
 
@@ -5659,6 +7794,25 @@ declare type SelectVariantProps = {
     [key in keyof SelectVariant]?: ConditionalValue<SelectVariant[key]> | undefined
 }
 
+/** Content and spacing used for a separator between editable segments. */
+export declare type SeparatorConfig = {
+    /** Visual separator content. */
+    content?: ReactNode;
+    /** Space placed around the separator. */
+    gap?: SeparatorGap;
+};
+
+/** Spacing applied around a visual separator between editable segments. */
+export declare type SeparatorGap = 'none' | 'tight' | 'normal' | 'loose';
+
+/** Metadata for non-editable content between segments. */
+declare type SeparatorItem = {
+    type: 'separator';
+    id: string;
+    content: ReactNode;
+    gap?: SeparatorGap;
+};
+
 declare type ShadowToken = "zeroBase" | "raisedBase" | "elevatedBase" | "overlayBase" | "overflowBase" | "zero" | "raised" | "elevated" | "overlay" | "overflow"
 
 declare type SimplePseudos =
@@ -5773,21 +7927,62 @@ declare type SimplePseudos =
 | ":valid"
 | ":visited";
 
+/** Props for a single-selection {@link Autocomplete}. */
+declare type SingleAutocompleteProps = AutocompleteBaseProps & {
+    /** Selects at most one value. */
+    multiple?: false;
+    /** Controlled selected value. Pair with `onValueChange`. */
+    value?: AutocompleteValue<false>;
+    /** Initial selected value when `value` is not provided. */
+    defaultValue?: AutocompleteValue<false>;
+    /** Runs when selection, removal, clearing, or creation requests a new value. */
+    onValueChange?: (value: AutocompleteValue<false>, reason: AutocompleteChangeReason) => void;
+    /**
+     * Runs when the selected value changes.
+     *
+     * @deprecated Use `onValueChange`.
+     */
+    onChange?: (value: AutocompleteValue<false>, reason: AutocompleteChangeReason) => void;
+};
+
 declare type SizeToken = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "12" | "14" | "16" | "18" | "20" | "22" | "24" | "28" | "32" | "40" | "48" | "56" | "64" | "72" | "80" | "88" | "96" | "104" | "112" | "120" | "128" | "136" | "144" | "152" | "160" | "168" | "176" | "184" | "192" | "200" | "208" | "216" | "224" | "232" | "240" | "248" | "256" | "264" | "272" | "280" | "full" | "half" | "min" | "max" | "fit" | "prose" | "auto" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl" | "8xl" | "breakpoint-xs" | "breakpoint-sm" | "breakpoint-md" | "breakpoint-lg" | "breakpoint-xl" | "breakpoint-2xl"
 
+/**
+ * Reserves the shape of content while that content is loading.
+ *
+ * `Skeleton` is visual only and does not announce loading. Put it in a region
+ * with an appropriate accessible loading state when users need that feedback.
+ *
+ * @example
+ * ```tsx
+ * <Skeleton width="full" height="40" aria-hidden />
+ * ```
+ */
 export declare const Skeleton: (props: SkeletonProps) => JSX.Element;
 
+/** Supported animation modes for {@link Skeleton}. */
 declare type SkeletonAnimation = 'pulse' | 'wave' | false;
 
-declare type SkeletonProps = Omit<BoxProps, 'as' | 'children' | 'width' | 'height'> & {
+/** Props accepted by {@link Skeleton}. */
+export declare type SkeletonProps = Omit<BoxProps, 'as' | 'children' | 'width' | 'height'> & {
+    /** Loading animation, or `false` for a static placeholder. */
+    /** @default "pulse" */
     animation?: SkeletonAnimation;
+    /** Placeholder shape. */
+    /** @default "text" */
     variant?: SkeletonVariant;
+    /** Element or component rendered as the placeholder root. */
+    /** @default "span" */
     component?: ElementType;
+    /** Explicit placeholder width; content determines width when omitted. */
     width?: string | number;
+    /** Explicit placeholder height; content determines height when omitted. */
     height?: string | number;
+    /** Content whose dimensions the skeleton should match. */
     children?: ReactNode;
 };
 
+/** Supported placeholder shapes for {@link Skeleton}. */
 declare type SkeletonVariant = 'text' | 'circular' | 'rounded' | 'rectangular';
 
 export declare type SlotRecipeConfig<S extends string = string, V extends SlotRecipeVariantRecord<S> = SlotRecipeVariantRecord<S>> = BaseSlotRecipeConfig<S, V>;
@@ -5796,11 +7991,28 @@ export declare type SlotRecipeVariantRecord<S extends string = string> = Record<
 
 declare type SpacingToken = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "12" | "14" | "16" | "18" | "20" | "22" | "24" | "28" | "32" | "40" | "48" | "56" | "64" | "72" | "80" | "88" | "96" | "104" | "112" | "120" | "128" | "136" | "144" | "152" | "160" | "168" | "176" | "184" | "192" | "200" | "208" | "216" | "224" | "232" | "240" | "248" | "256" | "264" | "272" | "280" | "full" | "half" | "min" | "max" | "fit" | "prose" | "auto" | "-0" | "-1" | "-2" | "-3" | "-4" | "-5" | "-6" | "-7" | "-8" | "-9" | "-10" | "-12" | "-14" | "-16" | "-18" | "-20" | "-22" | "-24" | "-28" | "-32" | "-40" | "-48" | "-56" | "-64" | "-72" | "-80" | "-88" | "-96" | "-104" | "-112" | "-120" | "-128" | "-136" | "-144" | "-152" | "-160" | "-168" | "-176" | "-184" | "-192" | "-200" | "-208" | "-216" | "-224" | "-232" | "-240" | "-248" | "-256" | "-264" | "-272" | "-280" | "-full" | "-half" | "-min" | "-max" | "-fit" | "-prose" | "-auto"
 
+/**
+ * Displays an indeterminate visual loading indicator.
+ *
+ * `Spinner` does not create a live region or loading label. Apply `aria-busy`
+ * and visible or screen-reader text to the region whose state is changing.
+ *
+ * @example
+ * ```tsx
+ * <Box aria-busy="true" aria-label="Loading orders"><Spinner /></Box>
+ * ```
+ */
 export declare const Spinner: (props: SpinnerProps) => JSX.Element;
 
-declare type SpinnerProps = Omit<BoxProps, keyof SpinnerVariantProps> & SpinnerVariantProps & {
+/** Props accepted by {@link Spinner}. */
+export declare type SpinnerProps = Omit<BoxProps, keyof SpinnerVariantProps> & SpinnerVariantProps & {
+    /** Uses the inverse-color treatment for dark or bold surfaces. */
+    /** @default false */
     inverse?: boolean;
+    /** Absolutely centers the spinner within its positioned container. */
+    /** @default false */
     centered?: boolean;
+    /** Visual size. An explicit value takes precedence over slot context. */
     size?: SpinnerVariantProps['size'];
 };
 
@@ -5817,6 +8029,20 @@ declare type SpinnerVariantProps = {
     [key in keyof SpinnerVariant]?: ConditionalValue<SpinnerVariant[key]> | undefined
 }
 
+/**
+ * Separates Panda CSS props from remaining element props and returns a merged
+ * class name for the generated styles.
+ *
+ * The first tuple value combines an existing string `className` with styles
+ * generated from Panda CSS props, including the `css` prop. The second value
+ * excludes those styling props and `className`, so it can be spread onto an
+ * element without leaking them to the DOM.
+ *
+ * @example
+ * ```tsx
+ * const [className, elementProps] = splitProps({ p: '4', id: 'profile' });
+ * ```
+ */
 export declare const splitProps: (props: PropsRecord) => [string, PropsRecord];
 
 declare interface StandardLonghandProperties<TLength = (string & {}) | 0, TTime = string & {}> {
@@ -11931,19 +14157,47 @@ declare type String_2 = string & {}
 
 declare type StringToMultiple<T extends string> = T | `${T}, ${T}`
 
+/**
+ * Opens nested menu content from a row in a parent {@link Menu}.
+ *
+ * Hover submenus open as positioned flyouts; `interaction="digin"` replaces
+ * the parent level in the same panel. Arrow Right opens a flyout and Arrow Left
+ * returns focus to its trigger. Filtering also searches nested children.
+ *
+ * @example
+ * ```tsx
+ * <SubMenu label="More actions">
+ *   <MenuItem label="Duplicate" />
+ * </SubMenu>
+ * ```
+ */
 export declare const SubMenu: (props: SubMenuProps) => JSX.Element | null;
 
+/** Opens a submenu as a positioned flyout or as an in-panel drill-in level. */
 declare type SubMenuInteraction = 'hover' | 'digin';
 
+/** Props for {@link SubMenu}, a nested menu trigger and its child menu. */
 export declare type SubMenuProps = Omit<BoxProps, 'as'> & Omit<MenuVariantProps, 'iconBefore' | 'iconAfter'> & {
+    /** Visible submenu trigger text. */
     label: string;
+    /** Secondary visible text included in filtering by default. */
     description?: string;
+    /** Prevents opening the nested menu. */
     disabled?: boolean;
+    /** Applies selected styling to the nested-menu trigger. */
     selected?: boolean;
+    /** Icon displayed before the trigger text. */
     iconBefore?: IconNamesList;
+    /** Overrides the parent menu's submenu interaction mode. */
     interaction?: SubMenuInteraction;
+    /**
+     * Floating placement for a hover submenu.
+     * @default 'right-start'
+     */
     placement?: Placement;
+    /** `MenuItem`, `MenuGroup`, or nested `SubMenu` children. */
     children: ReactNode;
+    /** Explicit text used for typeahead and filtering instead of label and description. */
     textValue?: string;
 };
 
@@ -19495,13 +21749,32 @@ export declare type SystemStyleObject = Record<string, unknown>;
 
 declare type SystemStyleObject_2 = Omit<Nested<SystemProperties & CssVarProperties>, 'base'>
 
+/**
+ * Displays a compact, non-interactive category or status label.
+ *
+ * Use `Chip` when the item can be selected or dismissed. Icons are decorative,
+ * so the text must communicate the tag's meaning.
+ *
+ * @example
+ * ```tsx
+ * <Tag hue="green">Approved</Tag>
+ * ```
+ */
 export declare const Tag: (props: TagProps) => JSX.Element;
 
-declare type TagProps = Omit<BoxProps, keyof TagVariantProps> & Omit<TagVariantProps, 'iconBefore' | 'iconAfter'> & {
+/** Props accepted by {@link Tag}. */
+export declare type TagProps = Omit<BoxProps, keyof TagVariantProps> & Omit<TagVariantProps, 'iconBefore' | 'iconAfter'> & {
+    /** Visible tag label. */
     children: string;
+    /** Decorative icon shown before the label. */
     iconBefore?: IconNamesList;
+    /** Decorative icon shown after the label. */
     iconAfter?: IconNamesList;
+    /** Visual emphasis treatment. */
+    /** @default "default" */
     variant?: TagVariantProps['variant'];
+    /** Color family used by the tag treatment. */
+    /** @default "slate" */
     hue?: TagVariantProps['hue'];
 };
 
@@ -19523,17 +21796,50 @@ declare type TagVariantProps = {
     [key in keyof TagVariant]?: TagVariant[key] | undefined
 }
 
+/**
+ * Renders design-system typography without imposing document semantics.
+ *
+ * The component renders a `span` by default. Choose `as` based on the content's
+ * semantic role; use `Heading` for document headings and `Label` for form
+ * labels.
+ *
+ * @example
+ * ```tsx
+ * <Text as="p" size="md">Account details</Text>
+ * ```
+ */
 declare const Text_2: (props: TextProps) => JSX.Element;
 export { Text_2 as Text }
 
+/**
+ * Renders a multi-line native textarea.
+ *
+ * Use a `Label` or `FormField` to provide its accessible name. Local `size`,
+ * error, invalid, and disabled values override matching field-context values.
+ *
+ * @example
+ * ```tsx
+ * <Textarea id="notes" name="notes" rows={4} />
+ * ```
+ */
 export declare const Textarea: (props: TextareaProps) => JSX.Element;
 
-declare type TextareaProps = Omit<BoxProps, keyof TextareaVariantProps> & TextareaVariantProps & {
+/** Props for {@link Textarea}, a multi-line native text input. */
+export declare type TextareaProps = Omit<BoxProps, keyof TextareaVariantProps> & TextareaVariantProps & {
+    /** Form field name submitted with the textarea value. */
     name: string;
+    /**
+     * Applies the recipe's content-sized visual treatment; it does not measure or resize the native element.
+     * @default false
+     */
     autoSize?: boolean;
+    /** Applies error styling. The local value takes precedence over field context. */
     error?: boolean;
+    /** Marks the native textarea invalid with `aria-invalid` and applies invalid styling. */
     invalid?: boolean;
+    /** Disables the native textarea. The local value takes precedence over field context. */
     disabled?: boolean;
+    /** Identifier used to associate a visible `Label` with this textarea. */
     id?: string;
 };
 
@@ -19549,19 +21855,51 @@ declare type TextareaVariantProps = {
     [key in keyof TextareaVariant]?: ConditionalValue<TextareaVariant[key]> | undefined
 }
 
+/**
+ * Renders a single-line native input with optional leading and trailing slots.
+ *
+ * Use a `Label` or `FormField` to provide an accessible name. `before` and
+ * `after` can contain controls; they inherit size and state through slot
+ * context. Explicit slots take precedence over `iconBefore` and `iconAfter`.
+ *
+ * @example
+ * ```tsx
+ * <TextInput id="email" name="email" type="email" iconBefore="mail" />
+ * ```
+ */
 export declare const TextInput: (props: TextInputProps) => JSX.Element;
 
-declare type TextInputProps = Omit<BoxProps, keyof TextInputVariantProps> & Omit<TextInputVariantProps, 'before' | 'after' | 'iconBefore' | 'iconAfter'> & {
+/** Props for {@link TextInput}, a single-line native input with optional slots. */
+export declare type TextInputProps = Omit<BoxProps, keyof TextInputVariantProps> & Omit<TextInputVariantProps, 'before' | 'after' | 'iconBefore' | 'iconAfter'> & {
+    /** Form field name submitted with the input value. */
     name: string;
+    /** Identifier used to associate a visible `Label` with this input. */
     id?: string;
+    /** Content rendered before the native input. Takes precedence over `iconBefore`. */
     before?: ReactNode;
+    /** Content rendered after the native input. Takes precedence over `iconAfter`. */
     after?: ReactNode;
+    /** Decorative icon rendered before the input when `before` is omitted. */
     iconBefore?: IconNamesList;
+    /** Decorative icon rendered after the input when `after` is omitted. */
     iconAfter?: IconNamesList;
+    /** Applies error styling. The local value takes precedence over field context. */
     error?: boolean;
+    /** Disables the native input. The local value takes precedence over slot and field context. */
     disabled?: boolean;
+    /** Applies valid styling without changing native constraint validation. */
     valid?: boolean;
+    /** Marks the native input invalid with `aria-invalid` and applies invalid styling. */
     invalid?: boolean;
+    /**
+     * Native autocomplete hint for the input. This component disables browser autocomplete by default.
+     * @default 'off'
+     */
+    autoComplete?: string;
+    /**
+     * Native input type.
+     * @default 'text'
+     */
     type?: 'text' | 'number' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'date' | 'time' | 'datetime-local' | 'month' | 'week';
 };
 
@@ -19579,10 +21917,16 @@ declare type TextInputVariantProps = {
     [key in keyof TextInputVariant]?: ConditionalValue<TextInputVariant[key]> | undefined
 }
 
-declare type TextProps = Omit<BoxProps, keyof TextVariantProps> & TextVariantProps & {
+/** Props accepted by {@link Text}. */
+export declare type TextProps = Omit<BoxProps, keyof TextVariantProps> & TextVariantProps & {
+    /** Text or inline content to render. */
     children: string | ReactNode;
+    /** Semantic element or component used for the text. */
+    /** @default "span" */
     as?: ElementType;
+    /** Explicit ARIA role when the rendered element does not provide it. */
     role?: string;
+    /** Adds the text to sequential keyboard focus when a composite widget requires it. */
     tabIndex?: number;
 };
 
@@ -19601,122 +21945,382 @@ declare type TextVariantProps = {
     [key in keyof TextVariant]?: ConditionalValue<TextVariant[key]> | undefined
 }
 
+/** Supported document color modes. */
 declare type Theme = 'light' | 'dark';
 
+/** Value returned by {@link useTheme} and provided by {@link ThemeProvider}. */
 declare interface ThemeContextType {
+    /** Currently active color mode. */
     theme: Theme;
+    /**
+     * Sets the active color mode and persists it as the user's browser
+     * preference.
+     */
     setTheme: (theme: Theme) => void;
 }
 
+/**
+ * Provides the active color mode and persists explicit user choices in browser
+ * storage.
+ *
+ * Without a saved preference, the initial mode follows
+ * `prefers-color-scheme`; subsequent system changes are followed only until a
+ * preference is saved through {@link useTheme}. This provider updates the
+ * document's `data-color-mode` attribute and requires a browser environment.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
 export declare function ThemeProvider({ children }: {
     children: ReactNode;
 }): JSX.Element;
 
+/**
+ * Renders an icon-only control that toggles the nearest theme provider between
+ * light and dark themes.
+ *
+ * It obtains state from `useTheme`, so it must be rendered below the design
+ * system's theme provider. The accessible label always describes the theme that
+ * will be selected next.
+ *
+ * @example
+ * ```tsx
+ * <ThemeSwitcher />
+ * ```
+ */
 export declare const ThemeSwitcher: () => JSX.Element;
 
-export declare const TimePicker: (props: TimePickerProps) => JSX.Element;
+/** Display cycle used for time input while values remain normalized to 24-hour time. */
+export declare type TimeFormat = '12' | '24';
 
-declare type TimePickerProps = Omit<BoxProps, keyof TimePickerVariantProps | 'children'> & TimePickerVariantProps & {
-    /** Controlled value — hour is always 24h (0–23) internally */
+/**
+ * Renders a segmented time field with optional leading and trailing content.
+ *
+ * Display can use 12- or 24-hour time while values remain normalized to
+ * 24-hour hours. Use `TimePicker` when a time-selection menu is also needed.
+ *
+ * @example
+ * ```tsx
+ * <TimeInput label="Start time" defaultValue={{ hour: 9, minute: 30 }} />
+ * ```
+ */
+export declare const TimeInput: (props: TimeInputProps) => JSX.Element;
+
+/** Props for {@link TimeInput}, including segmented time state and field slots. */
+export declare type TimeInputProps = Omit<BoxProps, keyof SegmentedFieldsVariantProps | 'children'> & Omit<SegmentedFieldsVariantProps, 'field' | 'range' | 'before' | 'after'> & {
+    /** Identifier forwarded to the segmented time group. */
+    id?: string;
+    /** Controlled 24-hour time value. Pair with `onChange`. */
     value?: TimeValue | null;
-    /** Initial uncontrolled value — hour is always 24h (0–23) internally */
+    /** Initial time when `value` is not provided. */
     defaultValue?: TimeValue | null;
-    /** Called when the time changes */
+    /** Runs when the time segments form a complete value. */
     onChange?: (value: TimeValue | null) => void;
-    /** 12-hour or 24-hour display */
-    hourCycle?: HourCycle;
-    /** Minute snap interval (default 1 = any minute) */
+    /** Display cycle; emitted values always use 24-hour hours. */
+    timeFormat?: TimeFormat;
+    /** Minute increment used by keyboard stepping. */
     minuteStep?: number;
-    /** Accessible label for the input group */
+    /** Accessible name for the segmented time group. */
     label?: string;
-    disabled?: boolean;
+    /** Content before the time field. Takes precedence over `iconBefore`. */
+    before?: ReactNode;
+    /** Content after the time field. Takes precedence over `iconAfter`. */
+    after?: ReactNode;
+    /** Legacy icon rendered before the field when `before` is absent. */
+    iconBefore?: IconNamesList;
+    /** Legacy icon rendered after the field when `after` is absent. */
+    iconAfter?: IconNamesList;
+    /** Applies error styling. Overrides field context when provided. */
     error?: boolean;
+    /** Prevents editing. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Applies invalid styling. Overrides field context when provided. */
     invalid?: boolean;
-    id?: string;
-    name?: string;
-    /** Controlled popover open state */
+    /** Reflected through to the segmented field — lets a wrapping Menu/Picker show "active anchor" styling */
     open?: boolean;
-    /** Initial uncontrolled popover state */
-    defaultOpen?: boolean;
-    onOpenChange?: (open: boolean) => void;
-    size?: TimePickerVariantProps['size'];
+    /** Forwarded to the segmented field — see SegmentedTime's onFocusWithin */
+    onFocusWithin?: () => void;
+    /** Forwarded to the segmented field — see SegmentedTime's onBlurWithin */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
 };
 
-declare interface TimePickerVariant {
+/**
+ * Presents hour, minute, and optional meridiem selection columns in a Menu.
+ *
+ * Each selection commits immediately while the menu remains open. Supply a
+ * `trigger`, or set inherited `inline` to render the columns in normal flow.
+ *
+ * @example
+ * ```tsx
+ * <TimeMenu trigger={<Button>Choose time</Button>} onChange={setTime} />
+ * ```
+ */
+export declare const TimeMenu: (props: TimeMenuProps) => any;
+
+/** Props for {@link TimeMenu}, including selected time and display cycle. */
+export declare type TimeMenuProps = Omit<MenuProps, 'children' | 'onChange' | 'value'> & {
+    /** Selected 24-hour time reflected in the menu columns. */
+    value?: TimeValue | null;
+    /** Runs immediately when an hour, minute, or meridiem choice is selected. */
+    onChange?: (value: TimeValue | null) => void;
     /**
-     * @default "md"
+     * Display cycle; emitted values always use 24-hour hours.
+     *
+     * @default '12'
      */
-    size: "sm" | "md" | "lg" | "xl"
-}
+    timeFormat?: TimeFormat;
+    /**
+     * Interval used to generate minute choices.
+     *
+     * @default 1
+     */
+    minuteStep?: number;
+    /** Prevents opening or selection and returns only the trigger. */
+    disabled?: boolean;
+};
 
-declare type TimePickerVariantProps = {
-    [key in keyof TimePickerVariant]?: ConditionalValue<TimePickerVariant[key]> | undefined
-}
+/**
+ * Combines keyboard time entry with hour and minute selection columns.
+ *
+ * Focusing the segmented input opens the menu. Input and menu interactions
+ * update the same value, normalized to 24-hour hours.
+ *
+ * @example
+ * ```tsx
+ * <TimePicker label="Start time" value={time} onChange={setTime} />
+ * ```
+ */
+export declare const TimePicker: (props: TimePickerProps) => JSX.Element;
 
-export declare const TimeRangePicker: ({ startValue, endValue, onStartChange, onEndChange, hourCycle, minuteStep, disabled, error, size, label, }: TimeRangePickerProps) => JSX.Element;
-
-declare type TimeRangePickerProps = {
-    /** Start time value (hour in 24h format, 0–23) */
-    startValue?: TimeValue | null;
-    /** End time value (hour in 24h format, 0–23) */
-    endValue?: TimeValue | null;
-    /** Called when start time changes */
-    onStartChange?: (value: TimeValue | null) => void;
-    /** Called when end time changes */
-    onEndChange?: (value: TimeValue | null) => void;
-    hourCycle?: HourCycle;
+/** Props for {@link TimePicker}, combining segmented entry and a time menu. */
+export declare type TimePickerProps = Pick<TimeInputProps, 'id' | 'label' | 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'timeFormat' | 'size'> & {
+    /** Controlled 24-hour time value. Pair with `onChange`. */
+    value?: TimeValue | null;
+    /** Initial time when `value` is not provided. */
+    defaultValue?: TimeValue | null;
+    /** Runs when typing or menu selection commits a time. */
+    onChange?: (value: TimeValue | null) => void;
+    /** Minute interval used by segmented stepping and menu choices. */
     minuteStep?: number;
-    disabled?: boolean;
+    /** Floating UI placement of the time menu. */
+    placement?: Placement;
+    /** Controlled menu visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial menu visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the menu open or close. */
+    onOpenChange?: (open: boolean) => void;
+};
+
+/**
+ * Renders start and end times as two coordinated segmented fields.
+ *
+ * Values remain normalized to 24-hour time regardless of display cycle. Use
+ * `TimeRangePicker` when a menu and Apply/Cancel flow are also needed.
+ *
+ * @example
+ * ```tsx
+ * <TimeRangeInput startLabel="Opens" endLabel="Closes" />
+ * ```
+ */
+export declare const TimeRangeInput: (props: TimeRangeInputProps) => JSX.Element;
+
+/** Props for {@link TimeRangeInput}, including range state and field slots. */
+export declare type TimeRangeInputProps = Omit<BoxProps, keyof SegmentedFieldsVariantProps | 'children'> & Omit<SegmentedFieldsVariantProps, 'field' | 'range' | 'before' | 'after'> & {
+    /** Identifier applied to the range container. */
+    id?: string;
+    /** Controlled start and end times. Pair with `onChange`. */
+    value?: TimeRangeValue | null;
+    /** Initial time range when `value` is not provided. */
+    defaultValue?: TimeRangeValue | null;
+    /** Runs whenever either endpoint becomes complete or is cleared. */
+    onChange?: (value: TimeRangeValue | null) => void;
+    /** Display cycle shared by both endpoints. */
+    timeFormat?: TimeFormat;
+    /** Minute increment used by keyboard stepping. */
+    minuteStep?: number;
+    /** Accessible name for the start-time segments. */
+    startLabel?: string;
+    /** Accessible name for the end-time segments. */
+    endLabel?: string;
+    /** Content before the range. Takes precedence over `iconBefore`. */
+    before?: ReactNode;
+    /** Content after the range. Takes precedence over `iconAfter`. */
+    after?: ReactNode;
+    /** Legacy icon rendered before the range when `before` is absent. */
+    iconBefore?: IconNamesList;
+    /** Legacy icon rendered after the range when `after` is absent. */
+    iconAfter?: IconNamesList;
+    /** Applies error styling. Overrides field context when provided. */
     error?: boolean;
-    /** Size passed to both TimePickers */
-    size?: TimePickerVariantProps['size'];
-    /** Accessible label prefix — used to build "Start time" and "End time" labels */
-    label?: string;
+    /** Prevents editing both endpoints. Overrides field context when provided. */
+    disabled?: boolean;
+    /** Applies invalid styling. Overrides field context when provided. */
+    invalid?: boolean;
+    /** Reflected through to the segmented fields — lets a wrapping Menu/Picker show "active anchor" styling */
+    open?: boolean;
+    /** Forwarded to both segmented fields — see SegmentedTime's onFocusWithin */
+    onFocusWithin?: () => void;
+    /** Forwarded to both segmented fields — see SegmentedTime's onBlurWithin */
+    onBlurWithin?: (relatedTarget: Node | null) => void;
+};
+
+/**
+ * Selects a start and end time from parallel selection columns.
+ *
+ * Changes remain a draft until Apply is pressed. Cancel restores the
+ * committed `value`; Apply is unavailable until both endpoints are complete.
+ *
+ * @example
+ * ```tsx
+ * <TimeRangeMenu
+ *   trigger={<Button>Choose hours</Button>}
+ *   value={range}
+ *   onChange={setRange}
+ * />
+ * ```
+ */
+export declare const TimeRangeMenu: (props: TimeRangeMenuProps) => any;
+
+/** Props for {@link TimeRangeMenu}, including committed range and display. */
+export declare type TimeRangeMenuProps = Omit<MenuProps, 'children' | 'onChange' | 'value'> & {
+    /** Committed start and end times used to initialize the menu draft. */
+    value?: TimeRangeValue | null;
+    /** Commits the complete draft when Apply is pressed; Cancel discards it. */
+    onChange?: (value: TimeRangeValue | null) => void;
+    /** Display cycle shared by both endpoints. */
+    timeFormat?: TimeFormat;
+    /** Interval used to generate minute choices. */
+    minuteStep?: number;
+    /** Prevents opening or selection and returns only the trigger. */
+    disabled?: boolean;
+    /** Accessible prefix for the start-time columns. */
+    startLabel?: string;
+    /** Accessible prefix for the end-time columns. */
+    endLabel?: string;
+};
+
+/**
+ * Combines segmented range entry with start and end time-selection columns.
+ *
+ * Typed endpoints commit immediately. Menu choices remain a draft until Apply
+ * is pressed; Cancel restores the currently committed range.
+ *
+ * @example
+ * ```tsx
+ * <TimeRangePicker startLabel="Opens" endLabel="Closes" />
+ * ```
+ */
+export declare const TimeRangePicker: (props: TimeRangePickerProps) => JSX.Element;
+
+/** Props for {@link TimeRangePicker}, combining range input and time menu. */
+export declare type TimeRangePickerProps = Pick<TimeRangeInputProps, 'id' | 'startLabel' | 'endLabel' | 'before' | 'after' | 'iconBefore' | 'iconAfter' | 'error' | 'disabled' | 'invalid' | 'timeFormat' | 'size'> & {
+    /** Controlled start and end times. Pair with `onChange`. */
+    value?: TimeRangeValue | null;
+    /** Initial time range when `value` is not provided. */
+    defaultValue?: TimeRangeValue | null;
+    /** Runs for typed endpoint changes and applied menu drafts. */
+    onChange?: (value: TimeRangeValue | null) => void;
+    /** Minute interval used by segmented stepping and menu choices. */
+    minuteStep?: number;
+    /** Floating UI placement of the time menu. */
+    placement?: Placement;
+    /** Controlled menu visibility. Pair with `onOpenChange`. */
+    open?: boolean;
+    /**
+     * Initial menu visibility when `open` is not provided.
+     *
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Runs when interaction requests that the menu open or close. */
+    onOpenChange?: (open: boolean) => void;
 };
 
-declare interface TimeValue {
+/** A committed time range — either endpoint may be null while only partially filled in. */
+export declare interface TimeRangeValue {
+    start: TimeValue | null;
+    end: TimeValue | null;
+}
+
+/** A time of day. Hour is always 24-hour (0-23) internally, regardless of display cycle. */
+export declare interface TimeValue {
     hour: number;
     minute: number;
 }
 
 /**
- * Toggle supports both controlled and uncontrolled usage.
+ * A native checkbox styled as an on/off toggle, without a visible label.
+ *
+ * Use {@link ToggleInput} when a visible label is needed. `Toggle` renders an
+ * `<input type="checkbox">`, not an ARIA `switch`; use `checked` with
+ * `onChange` for controlled state or `defaultChecked` for uncontrolled state.
+ * Provide `id` and an associated label so the control has an accessible name.
  *
  * @example
- * <Toggle defaultChecked />
+ * ```tsx
+ * <Toggle name="marketing" defaultChecked />
+ * ```
  *
  * @example
+ * ```tsx
  * const [checked, setChecked] = useState(false);
- * <Toggle checked={checked} onChange={(e) => setChecked(e.target.checked)} />
+ * <Toggle name="marketing" checked={checked} onChange={(event) => setChecked(event.target.checked)} />
+ * ```
  */
 export declare const Toggle: (props: ToggleProps) => JSX.Element;
 
 /**
- * Helper type for toggle change events
+ * Native change event emitted by {@link Toggle}.
  * @example
  * const handleChange: ToggleChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type ToggleChangeEvent = ChangeEvent<HTMLInputElement>;
+export declare type ToggleChangeEvent = ChangeEvent<HTMLInputElement>;
 
 /**
- * Helper type for toggle change handler functions
+ * Handler for a {@link Toggle} native change event.
  * @example
  * const handleChange: ToggleChangeHandler = (e) => setChecked(e.target.checked);
  */
-declare type ToggleChangeHandler = (e: ToggleChangeEvent) => void;
+export declare type ToggleChangeHandler = (e: ToggleChangeEvent) => void;
 
+/**
+ * A toggle paired with a clickable label.
+ *
+ * Use it for binary settings with a visible text label. It generates an ID when
+ * needed and associates that ID with the label. Its state and field-context
+ * precedence match {@link Toggle}.
+ *
+ * @example
+ * ```tsx
+ * <ToggleInput name="emailUpdates" defaultChecked>
+ *   Email updates
+ * </ToggleInput>
+ * ```
+ */
 export declare const ToggleInput: (props: ToggleInputProps) => JSX.Element;
 
-declare type ToggleInputProps = Omit<BoxProps, keyof ToggleInputVariantProps> & ToggleInputVariantProps & {
-    name: string;
-    checked?: boolean;
+/** Props for {@link ToggleInput}, a labelled {@link Toggle}. */
+export declare type ToggleInputProps = Omit<BoxProps, keyof ToggleInputVariantProps> & ToggleInputVariantProps & {
+    /** Form field name submitted when the toggle is on. */ name: string;
+    /** Controlled on/off state. Pair with `onChange`; do not combine with `defaultChecked`. */ checked?: boolean;
+    /** Initial uncontrolled on/off state; later updates are ignored. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: ToggleChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    disabled?: boolean;
-    children?: string | ReactNode;
+    /** Runs when the contained native checkbox changes. */ onChange?: ToggleChangeHandler;
+    /** Input ID. A stable ID is generated when omitted and associated with the label. */ id?: string;
+    /** Applies error styling, overriding field context. */ error?: boolean;
+    /** Marks the toggle invalid, overriding field context. */ invalid?: boolean;
+    /** Disables the label and toggle, overriding field context. */ disabled?: boolean;
+    /** Visible label content. */ children?: string | ReactNode;
 };
 
 declare interface ToggleInputVariant {
@@ -19727,15 +22331,18 @@ declare type ToggleInputVariantProps = {
     [key in keyof ToggleInputVariant]?: ConditionalValue<ToggleInputVariant[key]> | undefined
 }
 
-declare type ToggleProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof ToggleVariantProps> & ToggleVariantProps & {
-    name: string;
-    checked?: boolean;
+/** Props for {@link Toggle}, the unlabelled native checkbox styled as a switch. */
+export declare type ToggleProps = Omit<BoxProps, 'checked' | 'defaultChecked' | 'onChange' | keyof ToggleVariantProps> & ToggleVariantProps & {
+    /** Form field name submitted when the toggle is on. */ name: string;
+    /** Controlled on/off state. Pair with `onChange`; do not combine with `defaultChecked`. */ checked?: boolean;
+    /** Initial uncontrolled on/off state; later updates are ignored. */
+    /** @default false */
     defaultChecked?: boolean;
-    onChange?: ToggleChangeHandler;
-    id?: string;
-    error?: boolean;
-    invalid?: boolean;
-    disabled?: boolean;
+    /** Runs for the native checkbox change event; read the next state from `event.target.checked`. */ onChange?: ToggleChangeHandler;
+    /** Native input ID used by an external label. */ id?: string;
+    /** Applies error styling, overriding field context. */ error?: boolean;
+    /** Marks the native checkbox invalid with `aria-invalid`, overriding field context. */ invalid?: boolean;
+    /** Disables interaction, overriding field context. */ disabled?: boolean;
 };
 
 declare interface ToggleVariant {
@@ -19773,26 +22380,52 @@ declare type Tokens = {
     		breakpoints: BreakpointToken
 } & { [token: string]: never }
 
+/**
+ * Shows nonessential contextual text for a trigger on hover and keyboard focus.
+ *
+ * The trigger is wrapped in a span and linked with `aria-describedby`; Escape
+ * dismisses the portalled tooltip. Do not use a tooltip as the only accessible
+ * name or instruction for an interactive control.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip text="Copies the link"><IconButton iconName="copy" altText="Copy link" /></Tooltip>
+ * ```
+ */
 export declare const Tooltip: (props: TooltipProps) => JSX.Element;
 
-declare type TooltipProps = Omit<BoxProps, keyof TooltipVariantProps | 'children'> & TooltipVariantProps & {
-    /** Tooltip body text (required) */
+/** Props for {@link Tooltip}, nonessential contextual text shown on hover or focus. */
+export declare type TooltipProps = Omit<BoxProps, keyof TooltipVariantProps | 'children'> & TooltipVariantProps & {
+    /** Text displayed in the tooltip body. Use an accessible label instead when this is essential control information. */
     text: string;
-    /** Optional bold title rendered above the text */
+    /** Optional title displayed above the tooltip body. */
     title?: string;
-    /** Show/hide the arrow caret. Default: true */
+    /**
+     * Shows the arrow pointing at the trigger.
+     * @default true
+     */
     caret?: boolean;
-    /** Floating UI placement. Automatically flips if it doesn't fit. Default: 'bottom' */
+    /**
+     * Preferred placement relative to the trigger. The overlay can flip when it does not fit.
+     * @default 'bottom'
+     */
     placement?: Placement;
-    /** Distance in px between trigger and tooltip. Default: 8 */
+    /**
+     * Gap between trigger and tooltip, in pixels.
+     * @default 8
+     */
     offset?: number;
-    /** Hover open/close delay in ms, or { open, close } for separate delays */
+    /** Hover open/close delay in milliseconds, or separate `open` and `close` delays. */
     delay?: number | {
         open: number;
         close: number;
     };
-    /** Trigger element. Wrapped in a <span> to attach the floating ref. */
+    /** Trigger content, wrapped in an inline-flex span to receive floating interaction props. */
     children?: ReactNode;
+    /**
+     * Tooltip recipe size.
+     * @default 'md'
+     */
     size?: TooltipVariantProps['size'];
 };
 
@@ -19818,24 +22451,94 @@ declare interface UnstyledProps {
     unstyled?: boolean | undefined
 }
 
+/** Returns the nearest `ChipGroup` context, or `null` when a chip is not grouped. */
 export declare const useChipGroup: () => ChipGroupContextValue | null;
 
+/**
+ * Reports whether a referenced element meets a Cetec container-size threshold.
+ *
+ * The ref must point to a mounted `HTMLElement`. Returns `false` during server
+ * rendering or until the element is available. It uses a container-query API
+ * when the element supplies one, otherwise observes size changes with
+ * `ResizeObserver`; sizes are compared in `rem` using the root font size.
+ *
+ * @param containerRef - Ref for the element whose width is measured.
+ * @param size - Cetec container-size token such as `lg`.
+ * @param direction - Whether the width must meet or remain below the threshold.
+ * @default direction 'min'
+ * @example
+ * ```tsx
+ * const panelRef = useRef<HTMLDivElement>(null);
+ * const isWide = useContainerQuery(panelRef, 'lg');
+ * ```
+ */
 export declare function useContainerQuery(containerRef: RefObject<HTMLElement>, size: ContainerSizeKey, direction?: QueryDirection_2): boolean;
 
+/**
+ * Returns the sprite path supplied by the nearest {@link IconProvider}.
+ * Falls back to `/sprite.svg` when no provider is present.
+ */
 export declare const useIconConfig: () => IconConfigContextValue;
 
+/**
+ * Returns configuration from the nearest {@link ListProvider}, or compact,
+ * empty-query, no-highlighting defaults when no provider is present.
+ */
 export declare const useListContext: () => ListContextValue;
 
+/**
+ * Reports whether the viewport matches a Cetec breakpoint media query.
+ *
+ * Returns `false` during server rendering. The hook subscribes to browser
+ * media-query changes after mounting. Use `min` for the breakpoint and wider,
+ * or `max` for the generated maximum-width query.
+ *
+ * @param breakpoint - Cetec breakpoint token such as `md`.
+ * @param direction - Whether to create a minimum- or maximum-width query.
+ * @default direction 'min'
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery('lg');
+ * ```
+ */
 export declare function useMediaQuery(breakpoint: BreakpointKey, direction?: QueryDirection): boolean;
 
+/** Returns the active menu filtering configuration, or the default configuration outside a `Menu`. */
 export declare const useMenuFilterContext: () => MenuFilterContextValue;
 
+/** Returns roving-focus state for the current menu level, or `null` when none is provided. */
 export declare const useMenuListContext: () => MenuListContextValue | null;
 
+/**
+ * Returns the enclosing menu's shared behavior.
+ *
+ * Must be called below `Menu` or `MenuProvider`; otherwise it throws.
+ */
 export declare const useMenuRootContext: () => MenuRootContextValue;
 
+/**
+ * Returns state and close behavior from the closest parent {@link Modal}.
+ *
+ * Call only in a modal descendant; it throws when no modal context is present.
+ *
+ * @example
+ * ```tsx
+ * const { onClose } = useModalContext();
+ * ```
+ */
 export declare const useModalContext: () => ModalContextValue;
 
+/**
+ * Returns the active color mode and a function to persist a new preference.
+ *
+ * Must be called beneath {@link ThemeProvider}; throws when no provider is
+ * available.
+ *
+ * @example
+ * ```tsx
+ * const { theme, setTheme } = useTheme();
+ * ```
+ */
 export declare function useTheme(): ThemeContextType;
 
 declare type UtilitySizeToken = "full" | "half" | "min" | "max" | "fit" | "prose" | "auto"
@@ -21973,6 +24676,31 @@ declare interface VendorShorthandProperties<TLength = (string & {}) | 0, TTime =
 
 declare type VendorShorthandPropertiesFallback<TLength = (string & {}) | 0, TTime = string & {}> = Fallback<VendorShorthandProperties<TLength, TTime>>;
 
+declare type ViewDate = {
+    year: number;
+    month: number;
+};
+
+declare type ViewDate_2 = {
+    year: number;
+    month: number;
+};
+
+declare type ViewDate_3 = {
+    year: number;
+    month: number;
+};
+
+declare type ViewDate_4 = {
+    year: number;
+    month: number;
+};
+
+declare type ViewDate_5 = {
+    year: number;
+    month: number;
+};
+
 declare type WhitespaceImportant = ` ${ImportantMark}`
 
 declare type WithColorOpacityModifier<T> = [T] extends [string] ? `${T}/${string}` & { __colorOpacityModifier?: true } : never