@ssa-ui-kit/core 2.33.0 → 3.1.0

package/dist/components/DateRangePicker/hooks/useDateRangePicker.d.ts

@@ -1,4 +1,6 @@
+import React from 'react';
 import { DateTime } from 'luxon';
+import { useMergeRefs } from '@floating-ui/react';
 import { CalendarType, DateRangePickerProps, DateTimeTuple } from '../types';
 export declare const useDateRangePicker: ({ dateMin, dateMax, name: _name, format: propFormat, maskOptions, isOpenState, defaultValue, rangePickerType, onOpen, onClose, onError, onChange, ...rest }: DateRangePickerProps & {
     isOpenState?: boolean;
@@ -10,32 +12,35 @@ export declare const useDateRangePicker: ({ dateMin, dateMax, name: _name, forma
     };
     dateMinParts: number[];
     dateMaxParts: number[];
-    dateMinDT: DateTime<true> | DateTime<false>;
-    dateMaxDT: DateTime<true> | DateTime<false>;
+    dateMinDT: DateTime;
+    dateMaxDT: DateTime;
     dateTime: DateTimeTuple;
-    inputValueFrom: any;
-    inputValueTo: any;
-    calendarViewDateTime: [DateTime<boolean> | undefined, DateTime<boolean> | undefined];
+    inputValueFrom?: string;
+    inputValueTo?: string;
+    calendarViewDateTime: DateTimeTuple;
     calendarType: CalendarType;
-    lastChangedDate: [Date | undefined, Date | undefined];
+    lastChangedDate?: [Date | undefined | null, Date | undefined | null];
     luxonFormat: string;
     lastFocusedElement: "from" | "to";
     nameFrom: string;
     nameTo: string;
     currentIndex: number;
-    currentCalendarViewDT: DateTime<boolean>;
+    currentCalendarViewDT: DateTime;
     isOpen: boolean;
-    status: "error" | "success" | "basic" | undefined;
-    inputFromRef: ((instance: HTMLInputElement | null) => void | import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | null;
-    inputToRef: ((instance: HTMLInputElement | null) => void | import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | null;
-    setIsOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
-    setLastFocusedElement: import("react").Dispatch<import("react").SetStateAction<"from" | "to">>;
+    status?: "error" | "success" | "basic";
+    inputFromRef: ReturnType<typeof useMergeRefs<HTMLInputElement | null>>;
+    inputToRef: ReturnType<typeof useMergeRefs<HTMLInputElement | null>>;
+    setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    setLastFocusedElement: React.Dispatch<React.SetStateAction<"from" | "to">>;
     safeOnChange: (newDateTime?: DateTime) => void;
-    setCalendarType: import("react").Dispatch<import("react").SetStateAction<CalendarType>>;
-    setCalendarViewDateTime: import("react").Dispatch<import("react").SetStateAction<[DateTime<boolean> | undefined, DateTime<boolean> | undefined]>>;
-    setDateTime: import("react").Dispatch<import("react").SetStateAction<DateTimeTuple>>;
-    handleBlur: import("react").FocusEventHandler<HTMLInputElement>;
+    setCalendarType: React.Dispatch<React.SetStateAction<CalendarType>>;
+    setCalendarViewDateTime: React.Dispatch<React.SetStateAction<DateTimeTuple>>;
+    setDateTime: React.Dispatch<React.SetStateAction<DateTimeTuple>>;
+    handleBlur: React.FocusEventHandler<HTMLInputElement>;
     rangeSelectionStep: "start" | "end" | null;
-    setRangeSelectionStep: import("react").Dispatch<import("react").SetStateAction<"start" | "end" | null>>;
+    setRangeSelectionStep: React.Dispatch<React.SetStateAction<"start" | "end" | null>>;
     clearInputValue: (field: "from" | "to") => void;
+    isEndDatePresent: boolean;
+    setIsEndDatePresent: React.Dispatch<React.SetStateAction<boolean>>;
+    setLastChangedDate: React.Dispatch<React.SetStateAction<[Date | undefined | null, Date | undefined | null]>>;
 };

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

@@ -1 +1,4 @@
 export * from './DateRangePicker';
+export { DateRangePickerFormBridge, PRESENT_VALUE, type DateRangePickerFormBridgeProps, type DateRangePickerFormBridgeValue, } from './DateRangePickerFormBridge';
+export { DEFAULT_MASK_FORMAT, DEFAULT_EUROPEAN_MASK_FORMAT, DEFAULT_MONTH_MASK_FORMAT, DEFAULT_YEAR_MASK_FORMAT, } from './constants';
+export type { LastFocusedElement, RangePickerType, Format, DateRangePickerProps, DateRangePickerOnChangeDates, DateTimeTuple, DateRangePickerContextProps, } from './types';

package/dist/components/DateRangePicker/styles.d.ts

@@ -2,8 +2,9 @@ export declare const DaysViewCell: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 } & {
-    direction?: string;
-    alignItems?: string;
+    direction?: import("../Wrapper").WrapperDirection;
+    alignItems?: import("../Wrapper").WrapperAlignItems;
+    justifyContent?: import("../Wrapper").WrapperJustifyContent;
     fade?: boolean;
     fadeDelay?: number;
     isVisible?: boolean;
@@ -37,8 +38,9 @@ export declare const TriggerWrapper: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 } & {
-    direction?: string;
-    alignItems?: string;
+    direction?: import("../Wrapper").WrapperDirection;
+    alignItems?: import("../Wrapper").WrapperAlignItems;
+    justifyContent?: import("../Wrapper").WrapperJustifyContent;
     fade?: boolean;
     fadeDelay?: number;
     isVisible?: boolean;

package/dist/components/DateRangePicker/types.d.ts

@@ -3,16 +3,28 @@ import { DateTime } from 'luxon';
 import { useMask } from '@react-input/mask';
 import { FieldContextValue } from '../Field/FieldProvider';
 import { InputProps } from '../Input/types';
+import type { PickerCalendarType, DateFormat } from '../JsonSchemaForm/utils/dateFormats';
 export type LastFocusedElement = 'from' | 'to';
-export type RangePickerType = 'days' | 'months' | 'years';
-export type Format = 'mm/dd/yyyy' | 'dd/mm/yyyy' | 'mm/yyyy' | 'yyyy';
+export type RangePickerType = PickerCalendarType;
+export type Format = DateFormat;
+/**
+ * Type for the dates tuple passed to DateRangePicker's onChange callback.
+ *
+ * - Date: A valid date was selected
+ * - null: "Present" option was selected (end date only)
+ * - undefined: Date field is empty/unset
+ */
+export type DateRangePickerOnChangeDates = [
+    Date | null | undefined,
+    Date | null | undefined
+];
 export type DateRangePickerProps = {
     name: string;
     label?: string;
     format?: Format;
     isOpenState?: boolean;
-    value?: [string | undefined, string | undefined];
-    defaultValue?: [string, string];
+    value?: [string | undefined | null, string | undefined | null];
+    defaultValue?: [string, string | null] | [string, string];
     maskOptions?: Parameters<typeof useMask>[0];
     inputProps?: Partial<InputProps>;
     status?: FieldContextValue['status'];
@@ -39,7 +51,7 @@ export type DateRangePickerProps = {
         calendar?: string;
         label?: string;
     };
-    onChange?: (dates?: [Date | null, Date | null]) => void;
+    onChange?: (dates?: DateRangePickerOnChangeDates) => void;
     onOpen?: () => void;
     onClose?: () => void;
     onError?: (date: unknown, error?: string | null) => void;
@@ -47,6 +59,7 @@ export type DateRangePickerProps = {
     onYearChange?: (date: Date) => void;
     onBlur?: FocusEventHandler<HTMLInputElement>;
     allowReverseSelection?: boolean;
+    showPresentOption?: boolean;
 };
 export type DateTimeTuple = [DateTime | undefined, DateTime | undefined];
 export type DateRangePickerContextProps = Omit<DateRangePickerProps, 'dateMin' | 'dateMax'> & {
@@ -72,9 +85,10 @@ export type DateRangePickerContextProps = Omit<DateRangePickerProps, 'dateMin' |
         year: number;
     };
     lastFocusedElement: LastFocusedElement;
-    lastChangedDate?: [Date | undefined, Date | undefined];
+    lastChangedDate?: [Date | undefined | null, Date | undefined | null];
     safeOnChange?: (date?: DateTime) => void;
     setLastFocusedElement: Dispatch<SetStateAction<LastFocusedElement>>;
+    setLastChangedDate: Dispatch<SetStateAction<[Date | undefined | null, Date | undefined | null]>>;
     handleToggleOpen: MouseEventHandler<HTMLButtonElement | HTMLInputElement>;
     setCalendarViewDateTime: Dispatch<SetStateAction<DateTimeTuple>>;
     setDateTime: Dispatch<SetStateAction<DateTimeTuple>>;
@@ -83,5 +97,8 @@ export type DateRangePickerContextProps = Omit<DateRangePickerProps, 'dateMin' |
     rangeSelectionStep: 'start' | 'end' | null;
     setRangeSelectionStep: Dispatch<SetStateAction<'start' | 'end' | null>>;
     clearInputValue: (field: 'from' | 'to') => void;
+    showPresentOption?: boolean;
+    isEndDatePresent: boolean;
+    setIsEndDatePresent: Dispatch<SetStateAction<boolean>>;
 };
-export type CalendarType = 'days' | 'months' | 'years';
+export type CalendarType = PickerCalendarType;

package/dist/components/DateRangePicker/utils/dates.d.ts

@@ -5,7 +5,7 @@ export declare const getYearsList: (props?: {
     yearsCount?: number;
 }) => number[];
 export declare const processDate: (dateParts: {
-    month: string;
-    day: string;
+    month?: string;
+    day?: string;
     year: string;
 }, yearMin: number, yearMax: number) => boolean;

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

@@ -1,2 +1,3 @@
 export * as Drawer from './index.parts';
-export { useDrawer, UseDrawerOptions } from './useDrawer';
+export { useDrawer } from './useDrawer';
+export type { UseDrawerOptions } from './useDrawer';

package/dist/components/Dropdown/Dropdown.d.ts

@@ -1,4 +1,92 @@
 import { DropdownOptionProps } from '../DropdownOptions/types';
 import { DropdownProps } from './types';
+/**
+ * Dropdown - Select-like dropdown component for single selection
+ *
+ * A flexible dropdown component that allows users to select one option from
+ * a list of choices. Uses a compound component pattern with DropdownOption
+ * children. Provides keyboard navigation, accessibility features, and click-outside
+ * to close functionality.
+ *
+ * Component structure:
+ * - Dropdown (root container with context)
+ *   - DropdownToggle (button that opens/closes dropdown)
+ *   - DropdownOptions (menu container that appears when open)
+ *     - DropdownOption (individual selectable items)
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * const items = [
+ *   { id: 1, value: 'Apple' },
+ *   { id: 2, value: 'Banana' },
+ *   { id: 3, value: 'Cherry' },
+ * ];
+ *
+ * <Dropdown
+ *   selectedItem={items[0]}
+ *   onChange={(item) => handleSelection(item)}
+ *   placeholder="Select a fruit"
+ * >
+ *   {items.map(item => (
+ *     <DropdownOption key={item.id} value={item.id}>
+ *       {item.value}
+ *     </DropdownOption>
+ *   ))}
+ * </Dropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled open state
+ * const [isOpen, setIsOpen] = useState(false);
+ * <Dropdown
+ *   isOpen={isOpen}
+ *   onChange={handleChange}
+ *   selectedItem={selected}
+ * >
+ *   {options.map(opt => (
+ *     <DropdownOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </DropdownOption>
+ *   ))}
+ * </Dropdown>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom props for sub-components
+ * <Dropdown
+ *   selectedItem={selected}
+ *   onChange={handleChange}
+ *   dropdownProps={{
+ *     base: { id: 'my-dropdown' },
+ *     toggleButton: { 'data-testid': 'dropdown-toggle' },
+ *     toggleButtonArrow: { className: 'custom-arrow' }
+ *   }}
+ * >
+ *   {options.map(opt => (
+ *     <DropdownOption key={opt.id} value={opt.id}>
+ *       {opt.label}
+ *     </DropdownOption>
+ *   ))}
+ * </Dropdown>
+ * ```
+ *
+ * @see {@link DropdownOption} - Child component for individual options
+ * @see {@link DropdownToggle} - Toggle button component
+ * @see {@link DropdownOptions} - Options menu container
+ *
+ * @accessibility
+ * - ARIA attributes set according to WAI-ARIA combobox pattern
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - Click outside to close
+ * - Screen reader friendly
+ * - Focus management
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
+ */
 declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Dropdown;

package/dist/components/Dropdown/types.d.ts

@@ -1,23 +1,124 @@
 import React from 'react';
+import { Interpolation, Theme } from '@emotion/react';
 import { DropdownOptionProps } from '../DropdownOptions';
 import { CommonProps } from '../../types/emotion';
 import { IconProps } from '../Icon/types';
+/**
+ * Props that are controlled by Dropdown component
+ * These props cannot be passed via dropdownProps.toggleButton
+ */
 export type ControlledButtonProps = 'onClick' | 'onFocus' | 'disabled' | 'type' | 'role' | 'aria-expanded' | 'aria-haspopup' | 'aria-labelledby' | 'aria-controls' | 'children';
+/**
+ * Props for the Dropdown component
+ *
+ * A select-like dropdown component that allows users to choose one option from
+ * a list. Uses compound component pattern with DropdownOption children.
+ * Provides keyboard navigation, accessibility, and customizable styling.
+ *
+ * @example
+ * ```tsx
+ * const items = [
+ *   { id: 1, value: 'Option 1' },
+ *   { id: 2, value: 'Option 2' },
+ * ];
+ *
+ * <Dropdown
+ *   selectedItem={items[0]}
+ *   onChange={(item) => console.log(item)}
+ *   placeholder="Select an option"
+ * >
+ *   {items.map(item => (
+ *     <DropdownOption key={item.id} value={item.id}>
+ *       {item.value}
+ *     </DropdownOption>
+ *   ))}
+ * </Dropdown>
+ * ```
+ */
 export interface DropdownProps<P extends DropdownOptionProps> extends CommonProps {
+    /**
+     * Currently selected item
+     * When provided, this item will be displayed in the toggle button
+     */
     selectedItem?: P;
+    /**
+     * Callback function called when an option is selected
+     * Receives the selected DropdownOptionProps object
+     */
     onChange?: (item: P) => void;
+    /**
+     * Whether the dropdown is disabled
+     * Disabled dropdowns cannot be opened or interacted with
+     * @default false
+     */
     isDisabled?: boolean;
+    /**
+     * Placeholder text displayed when no item is selected
+     * @default 'Select something'
+     */
     placeholder?: string;
+    /**
+     * DropdownOption components as children
+     * Each child must be a DropdownOption component
+     */
     children?: React.ReactNode;
+    /**
+     * Custom CSS class name for the toggle button
+     */
     className?: string;
+    /**
+     * Controlled open state
+     * When provided, controls dropdown open/closed state externally
+     */
     isOpen?: boolean;
+    /**
+     * Props object for sub-components
+     * Allows fine-grained control over component parts
+     */
     dropdownProps?: {
+        /** Props for the wrapper div element */
         base?: React.HTMLAttributes<HTMLDivElement>;
-        toggleButton?: Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, ControlledButtonProps>;
+        /** Props for the toggle button element (excluding controlled props) */
+        toggleButton?: Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, ControlledButtonProps> & {
+            /**
+             * Emotion css prop for custom styles on the toggle button.
+             * Merged on top of the component's built-in styles, so any rule here
+             * overrides the default appearance.
+             *
+             * @example
+             * ```tsx
+             * import { css } from '@emotion/react';
+             *
+             * <Dropdown
+             *   dropdownProps={{
+             *     toggleButton: {
+             *       css: css`background: hotpink; border: none;`,
+             *     },
+             *   }}
+             * >
+             *   ...
+             * </Dropdown>
+             * ```
+             */
+            css?: Interpolation<Theme>;
+        };
+        /** Props for the arrow icon SVG element */
         toggleButtonArrow?: Omit<IconProps, 'name' | 'size'>;
     };
 }
+/**
+ * Dropdown context value
+ * Provides selection state and change handler to child DropdownOption components
+ */
 export interface DropdownContextType {
+    /**
+     * Function to handle option selection
+     * Called when a DropdownOption is clicked
+     */
     onChange: (item?: string) => void;
+    /**
+     * Currently active/selected item
+     * Used to highlight the selected option
+     */
     activeItem?: DropdownOptionProps | null;
 }

package/dist/components/DropdownOption/DropdownOption.d.ts

@@ -10,6 +10,8 @@ interface DropdownItemProps extends CommonProps {
     value?: string | number | boolean;
     label?: string | number;
     children?: React.ReactNode;
+    /** Avatar or icon to display before the option content (e.g. <Avatar size={20} image={url} />) */
+    avatar?: React.ReactNode;
 }
 declare const DropdownOption: import("@emotion/styled").StyledComponent<{
     theme?: Theme;

package/dist/components/DropdownOptions/DropdownOptions.d.ts

@@ -1,3 +1,34 @@
 import { DropdownItemsListProps } from './types';
+/**
+ * DropdownOptions - Options menu container for Dropdown component
+ *
+ * Renders the scrollable list of options that appears when the dropdown is open.
+ * Provides proper ARIA attributes for accessibility and keyboard navigation.
+ *
+ * @category Form Controls
+ * @subcategory Selection
+ *
+ * @example
+ * ```tsx
+ * // Used within Dropdown component
+ * <Dropdown selectedItem={selected} onChange={handleChange}>
+ *   <DropdownOptions>
+ *     {items.map(item => (
+ *       <DropdownOption key={item.id} value={item.id}>
+ *         {item.label}
+ *       </DropdownOption>
+ *     ))}
+ *   </DropdownOptions>
+ * </Dropdown>
+ * ```
+ *
+ * @see {@link Dropdown} - Parent component
+ * @see {@link DropdownOption} - Individual option components
+ *
+ * @accessibility
+ * - Uses role="listbox" for proper ARIA semantics
+ * - Supports keyboard navigation (Arrow keys, Enter, Escape)
+ * - Screen reader friendly
+ */
 declare const DropdownOptions: ({ ariaLabelledby, id, children, }: DropdownItemsListProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default DropdownOptions;

package/dist/components/DropdownOptions/types.d.ts

@@ -1,7 +1,29 @@
 import { CommonProps } from '../../types/emotion';
+/**
+ * Props for DropdownOption component
+ *
+ * Record type that allows any string or number properties.
+ * Common properties include: value, label, children, etc.
+ */
 export type DropdownOptionProps = Record<string, string | number>;
+/**
+ * Props for DropdownOptions component
+ *
+ * Container component for dropdown option items. Renders as a scrollable
+ * list with proper ARIA attributes.
+ */
 export interface DropdownItemsListProps extends CommonProps {
+    /**
+     * ARIA label reference
+     * Associates the listbox with its label
+     */
     ariaLabelledby?: string;
+    /**
+     * Unique identifier for the options container
+     */
     id?: string;
+    /**
+     * DropdownOption components as children
+     */
     children?: React.ReactNode;
 }

package/dist/components/DropdownToggle/DropdownToggle.d.ts

@@ -1,7 +1,8 @@
+import { Theme } from '@emotion/react';
 import { DropdownToggleProps } from './types';
 export declare const DropdownToggleBase: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme;
+    theme?: Theme;
     as?: React.ElementType;
-} & Pick<DropdownToggleProps, "colors" | "disabled" | "isMultiple" | "isOpen" | "selectedCount">, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+} & Pick<DropdownToggleProps, "colors" | "disabled" | "isOpen" | "isMultiple" | "selectedCount">, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
 declare const DropdownToggle: ({ onClick, onFocus, isOpen, isMultiple, selectedCount, disabled, children, ariaLabelledby, ariaControls, colors, className, ...restProps }: DropdownToggleProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default DropdownToggle;

package/dist/components/DropdownToggle/types.d.ts

@@ -1,10 +1,12 @@
 import React from 'react';
-import { Theme } from '@emotion/react';
+import { Interpolation, Theme } from '@emotion/react';
 import { CommonProps } from '../../types/emotion';
 import { ControlledButtonProps } from '../Dropdown/types';
 export interface DropdownToggleProps extends CommonProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, ControlledButtonProps> {
+    /** Emotion css prop forwarded to the underlying styled button */
+    css?: Interpolation<Theme>;
     onClick: (e: React.MouseEvent<HTMLElement>) => void;
-    onFocus: (e: React.FocusEvent<HTMLButtonElement, Element>) => void;
+    onFocus?: (e: React.FocusEvent<HTMLButtonElement, Element>) => void;
     isOpen: boolean;
     isMultiple?: boolean;
     disabled?: boolean;
@@ -17,5 +19,5 @@ export interface DropdownToggleProps extends CommonProps, Omit<React.ButtonHTMLA
 }
 export interface MultipleStylesProps {
     theme: Theme;
-    selectedCount?: number;
+    isOpen?: boolean;
 }

package/dist/components/Field/FieldControl.d.ts

@@ -1,7 +1,68 @@
 import React, { HTMLAttributes } from 'react';
 import { FieldContextValue } from './FieldProvider';
+/**
+ * Props for Field.Control component
+ *
+ * Wrapper component for form controls (inputs, textarea elements, selects, etc.).
+ * Provides consistent styling, validation state borders, and optional focus forwarding.
+ * Can accept children as React nodes or a render function that receives field context.
+ */
 export interface FieldControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
-    controlRef?: React.RefObject<HTMLElement>;
+    /**
+     * Optional ref to a specific element to focus when control is clicked
+     * If not provided, will attempt to focus the first child input element
+     */
+    controlRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Form control element(s) to wrap
+     * Can be a React node or a function that receives FieldContextValue and returns a node
+     */
     children: React.ReactNode | ((props: FieldContextValue) => React.ReactNode);
 }
+/**
+ * Field.Control - Wrapper component for form controls
+ *
+ * Provides a styled container for form inputs with automatic focus forwarding,
+ * validation state styling (error/success borders), and consistent layout.
+ * Clicking anywhere in the control area will focus the contained input when
+ * forwardFocus is enabled in Field.Root.
+ *
+ * @category Form Controls
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Field.Root>
+ *   <Field.Label htmlFor="username">Username</Field.Label>
+ *   <Field.Control>
+ *     <Input id="username" name="username" />
+ *   </Field.Control>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With render function
+ * <Field.Control>
+ *   {(context) => (
+ *     <Input
+ *       name="email"
+ *       disabled={context.disabled}
+ *       css={{ borderColor: context.status === 'error' ? 'red' : 'blue' }}
+ *     />
+ *   )}
+ * </Field.Control>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom control ref
+ * const inputRef = useRef<HTMLInputElement>(null);
+ * <Field.Control controlRef={inputRef}>
+ *   <CustomInput ref={inputRef} />
+ * </Field.Control>
+ * ```
+ *
+ * @see {@link Field.Root} - Parent component that provides context
+ */
 export declare const FieldControl: React.ForwardRefExoticComponent<FieldControlProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Field/FieldDescription.d.ts

@@ -1,4 +1,37 @@
+/**
+ * Props for Field.Description component
+ *
+ * Helper text component that only displays when field status is 'basic'.
+ * Automatically hidden when field is in 'error' or 'success' state to avoid
+ * conflicting with Field.Error or Field.Success messages.
+ */
 export interface FieldDescriptionProps {
+    /**
+     * Helper text content to display
+     */
     children: React.ReactNode;
 }
+/**
+ * Field.Description - Helper text for form fields
+ *
+ * Displays descriptive helper text below form controls. Only visible when
+ * the field status is 'basic' (hidden when status is 'error' or 'success'
+ * to avoid conflicts with validation messages).
+ *
+ * @category Form Controls
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Field.Root>
+ *   <Field.Label htmlFor="password">Password</Field.Label>
+ *   <Field.Control>
+ *     <Input id="password" name="password" type="password" />
+ *   </Field.Control>
+ *   <Field.Description>
+ *     Must be at least 8 characters with one number
+ *   </Field.Description>
+ * </Field.Root>
+ * ```
+ */
 export declare const FieldDescription: ({ children }: FieldDescriptionProps) => import("@emotion/react/jsx-runtime").JSX.Element | null;

package/dist/components/Field/FieldError.d.ts

@@ -1,4 +1,40 @@
+/**
+ * Props for Field.Error component
+ *
+ * Error message component that only displays when field status is 'error'.
+ * Automatically hidden when field is in 'basic' or 'success' state.
+ */
 export interface FieldErrorProps {
+    /**
+     * Error message text to display
+     */
     children: React.ReactNode;
 }
+/**
+ * Field.Error - Error message for form fields
+ *
+ * Displays error messages below form controls. Only visible when the field
+ * status is 'error'. Automatically styled with error colors and hidden when
+ * status is 'basic' or 'success'.
+ *
+ * @category Form Controls
+ * @subcategory Layout
+ *
+ * @example
+ * ```tsx
+ * <Field.Root status={errors.email ? 'error' : 'basic'}>
+ *   <Field.Label htmlFor="email">Email</Field.Label>
+ *   <Field.Control>
+ *     <Input id="email" name="email" />
+ *   </Field.Control>
+ *   <Field.Error>
+ *     {errors.email?.message || 'Email is required'}
+ *   </Field.Error>
+ * </Field.Root>
+ * ```
+ *
+ * @accessibility
+ * - Uses role="status" for screen reader announcements
+ * - Visible only when status is 'error'
+ */
 export declare const FieldError: ({ children }: FieldErrorProps) => import("@emotion/react/jsx-runtime").JSX.Element | null;