@spark-ui/components 17.2.2 → 17.2.3-beta.1

package/dist/src/dropdown/types.d.ts

@@ -0,0 +1,8 @@
+import { UseMultipleSelectionReturnValue, UseSelectReturnValue } from 'downshift';
+export interface DropdownItem {
+    disabled: boolean;
+    value: string;
+    text: string;
+}
+export type ItemsMap = Map<string, DropdownItem>;
+export type DownshiftState = UseSelectReturnValue<DropdownItem> & UseMultipleSelectionReturnValue<DropdownItem>;

package/dist/src/dropdown/useDropdown.d.ts

@@ -0,0 +1,41 @@
+import { DropdownItem, ItemsMap } from './types';
+export interface DownshiftProps {
+    itemsMap: ItemsMap;
+    value: string | string[] | undefined;
+    defaultValue: string | string[] | undefined;
+    onValueChange: ((value: string) => void) | ((value: string[]) => void) | undefined;
+    open: boolean | undefined;
+    onOpenChange: ((isOpen: boolean) => void) | undefined;
+    defaultOpen: boolean | undefined;
+    multiple: boolean | undefined;
+    id: string;
+    labelId: string;
+}
+/**
+ * This hook abstract the complexity of using downshift with both single and multiple selection.
+ */
+export declare const useDropdown: ({ itemsMap, defaultValue, value, onValueChange, open, onOpenChange, defaultOpen, multiple, id, labelId, }: DownshiftProps) => {
+    /** There is a Downshift bug in React 19, it duplicates some selectedItems */
+    selectedItems: DropdownItem[];
+    activeIndex: number;
+    getDropdownProps: <Options>(options?: import('downshift').UseMultipleSelectionGetDropdownPropsOptions & Options, extraOptions?: import('downshift').GetPropsCommonOptions) => Omit<import('downshift').Overwrite<import('downshift').UseMultipleSelectionGetDropdownReturnValue, Options>, "preventKeyAction">;
+    getSelectedItemProps: <Options>(options: import('downshift').UseMultipleSelectionGetSelectedItemPropsOptions<DropdownItem> & Options) => Omit<import('downshift').Overwrite<import('downshift').UseMultipleSelectionGetSelectedItemReturnValue, Options>, "index" | "selectedItem">;
+    reset: () => void;
+    addSelectedItem: (item: DropdownItem) => void;
+    removeSelectedItem: (item: DropdownItem) => void;
+    setSelectedItems: (items: DropdownItem[]) => void;
+    setActiveIndex: (index: number) => void;
+    highlightedIndex: number;
+    selectedItem: DropdownItem | null;
+    isOpen: boolean;
+    inputValue: string;
+    getToggleButtonProps: <Options>(options?: import('downshift').UseSelectGetToggleButtonPropsOptions & Options, otherOptions?: import('downshift').GetPropsCommonOptions) => import('downshift').Overwrite<import('downshift').UseSelectGetToggleButtonReturnValue, Options>;
+    getLabelProps: <Options>(options?: import('downshift').UseSelectGetLabelPropsOptions & Options) => import('downshift').Overwrite<import('downshift').UseSelectGetLabelPropsReturnValue, Options>;
+    getMenuProps: <Options>(options?: import('downshift').UseSelectGetMenuPropsOptions & Options, otherOptions?: import('downshift').GetPropsCommonOptions) => import('downshift').Overwrite<import('downshift').UseSelectGetMenuReturnValue, Options>;
+    getItemProps: <Options>(options: import('downshift').UseSelectGetItemPropsOptions<DropdownItem> & Options) => Omit<import('downshift').Overwrite<import('downshift').UseSelectGetItemPropsReturnValue, Options>, "item" | "index">;
+    openMenu: () => void;
+    closeMenu: () => void;
+    toggleMenu: () => void;
+    selectItem: (item: DropdownItem | null) => void;
+    setHighlightedIndex: (index: number) => void;
+};

package/dist/src/dropdown/utils.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { DropdownItem, ItemsMap } from './types';
+export declare function getIndexByKey(map: ItemsMap, targetKey: string): number;
+export declare const getElementByIndex: (map: ItemsMap, index: number) => DropdownItem | undefined;
+export declare const getOrderedItems: (children: ReactNode, result?: DropdownItem[]) => DropdownItem[];
+/**
+ * If Dropdown.Item children:
+ * - is a string, then the string is used.
+ * - is JSX markup, then we look for Dropdown.ItemText to get its string value.
+ */
+export declare const getItemText: (children: ReactNode, itemText?: string) => string;
+export declare const getItemsFromChildren: (children: ReactNode) => ItemsMap;
+export declare const hasChildComponent: (children: ReactNode, displayName: string) => boolean;

package/dist/src/file-upload/FileUpload.d.ts

@@ -0,0 +1,130 @@
+import { ReactNode, Ref } from 'react';
+import { FileAcceptDetails, FileChangeDetails, FileRejectDetails, FileUploadFileError, RejectedFile } from './useFileUploadState';
+export type { FileAcceptDetails, FileChangeDetails, FileRejectDetails, FileUploadFileError, RejectedFile, };
+export interface FileUploadProps {
+    /**
+     * Change the default rendered element for the one passed as a child, merging their props and behavior.
+     */
+    asChild?: boolean;
+    ref?: Ref<HTMLDivElement>;
+    children: ReactNode;
+    className?: string;
+    /**
+     * Initial files to display when the component mounts (uncontrolled mode)
+     */
+    defaultValue?: File[];
+    /**
+     * Controlled files value (controlled mode)
+     * When provided, the component becomes controlled
+     */
+    value?: File[];
+    /**
+     * Callback when files are accepted
+     * @param details - Details about the accepted files
+     */
+    onFileAccept?: (details: FileAcceptDetails) => void;
+    /**
+     * Callback when files are rejected
+     * @param details - Details about the rejected files and their errors
+     */
+    onFileReject?: (details: FileRejectDetails) => void;
+    /**
+     * Callback when files change (both accepted and rejected)
+     * For controlled mode, use this to update the value prop by extracting details.acceptedFiles
+     * @param details - Details about both accepted and rejected files
+     */
+    onFileChange?: (details: FileChangeDetails) => void;
+    /**
+     * Whether multiple files can be selected
+     * @default true
+     */
+    multiple?: boolean;
+    /**
+     * Comma-separated list of accepted file types
+     * Supports MIME types (e.g., "image/*", "image/png", "application/pdf")
+     * and file extensions (e.g., ".pdf", ".doc", ".jpg")
+     * @example "image/*"
+     * @example ".pdf,.doc"
+     * @example "image/png,image/jpeg,.pdf"
+     */
+    accept?: string;
+    /**
+     * Maximum number of files that can be uploaded
+     * Files beyond this limit will be rejected
+     */
+    maxFiles?: number;
+    /**
+     * Maximum file size in bytes
+     * Files larger than this will be rejected
+     */
+    maxFileSize?: number;
+    /**
+     * Minimum file size in bytes
+     * Files smaller than this will be rejected
+     */
+    minFileSize?: number;
+    /**
+     * When `true`, prevents the user from interacting with the file upload
+     */
+    disabled?: boolean;
+    /**
+     * When `true`, sets the file upload to read-only mode
+     */
+    readOnly?: boolean;
+    /**
+     * The [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code for the locale.
+     * Used for formatting file sizes and error messages.
+     * @default Browser locale or 'en' if not available
+     */
+    locale?: string;
+}
+export declare const FileUploadContext: import('react').Context<{
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    files: File[];
+    rejectedFiles: RejectedFile[];
+    addFiles: (files: File[]) => void;
+    removeFile: (index: number) => void;
+    removeRejectedFile: (index: number) => void;
+    clearFiles: () => void;
+    clearRejectedFiles: () => void;
+    triggerRef: React.RefObject<HTMLElement | null>;
+    dropzoneRef: React.RefObject<HTMLElement | null>;
+    deleteButtonRefs: React.MutableRefObject<HTMLButtonElement[]>;
+    rejectedFileDeleteButtonRefs: React.MutableRefObject<HTMLButtonElement[]>;
+    multiple: boolean;
+    maxFiles?: number;
+    maxFilesReached: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    locale: string;
+    description?: string;
+    isInvalid?: boolean;
+    isRequired?: boolean;
+} | null>;
+export declare const FileUpload: {
+    ({ asChild: _asChild, children, defaultValue, value: controlledValue, onFileAccept, onFileReject, onFileChange, multiple, accept, maxFiles, maxFileSize, minFileSize, disabled: disabledProp, readOnly: readOnlyProp, locale, }: FileUploadProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export declare const useFileUploadContext: () => {
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    files: File[];
+    rejectedFiles: RejectedFile[];
+    addFiles: (files: File[]) => void;
+    removeFile: (index: number) => void;
+    removeRejectedFile: (index: number) => void;
+    clearFiles: () => void;
+    clearRejectedFiles: () => void;
+    triggerRef: React.RefObject<HTMLElement | null>;
+    dropzoneRef: React.RefObject<HTMLElement | null>;
+    deleteButtonRefs: React.MutableRefObject<HTMLButtonElement[]>;
+    rejectedFileDeleteButtonRefs: React.MutableRefObject<HTMLButtonElement[]>;
+    multiple: boolean;
+    maxFiles?: number;
+    maxFilesReached: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    locale: string;
+    description?: string;
+    isInvalid?: boolean;
+    isRequired?: boolean;
+};

package/dist/src/file-upload/FileUploadAcceptedFile.d.ts

@@ -0,0 +1,25 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+export interface FileUploadAcceptedFileProps extends ComponentPropsWithoutRef<'li'> {
+    ref?: Ref<HTMLLIElement>;
+    /**
+     * The file to display
+     */
+    file: File;
+    /**
+     * Upload progress value (0-100). When provided, displays a progress bar at the bottom of the file item.
+     */
+    uploadProgress?: number;
+    /**
+     * Accessible label for the delete button
+     */
+    deleteButtonAriaLabel: string;
+    /**
+     * Accessible label for the progress bar. Required when uploadProgress is provided.
+     */
+    progressAriaLabel?: string;
+    className?: string;
+}
+export declare const AcceptedFile: {
+    ({ className, file, uploadProgress, deleteButtonAriaLabel, progressAriaLabel, ...props }: FileUploadAcceptedFileProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadContext.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { RejectedFile } from './FileUpload';
+export interface FileUploadContextProps {
+    /**
+     * Render prop that receives acceptedFiles, rejectedFiles, formatFileSize, and locale
+     */
+    children: (props: {
+        acceptedFiles: File[];
+        rejectedFiles: RejectedFile[];
+        formatFileSize: (bytes: number, locale?: string) => string;
+        locale?: string;
+    }) => ReactNode;
+}
+export declare const Context: {
+    ({ children }: FileUploadContextProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadDropzone.d.ts

@@ -0,0 +1,10 @@
+export declare const DropzoneContext: import('react').Context<boolean>;
+export declare const useDropzoneContext: () => boolean;
+export declare function Dropzone({ children, className, unstyled, }: {
+    children?: React.ReactNode;
+    className?: string;
+    unstyled?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare namespace Dropzone {
+    var displayName: string;
+}

package/dist/src/file-upload/FileUploadItemDeleteTrigger.d.ts

@@ -0,0 +1,11 @@
+import { IconButton } from '../icon-button';
+export interface FileUploadItemDeleteTriggerProps extends React.ComponentProps<typeof IconButton> {
+    /**
+     * The file to delete
+     */
+    file: File;
+}
+export declare const ItemDeleteTrigger: {
+    ({ className, file, onClick, ...props }: FileUploadItemDeleteTriggerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadPreviewImage.d.ts

@@ -0,0 +1,17 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+export interface FileUploadPreviewImageProps extends ComponentPropsWithoutRef<'div'> {
+    ref?: Ref<HTMLDivElement>;
+    className?: string;
+    /**
+     * The file to preview
+     */
+    file: File;
+    /**
+     * Fallback content when file is not an image or preview fails
+     */
+    fallback?: React.ReactNode;
+}
+export declare const PreviewImage: {
+    ({ className, file, fallback, ...props }: FileUploadPreviewImageProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadRejectedFile.d.ts

@@ -0,0 +1,24 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+import { FileUploadFileError, RejectedFile as RejectedFileType } from './FileUpload';
+export interface FileUploadRejectedFileProps extends ComponentPropsWithoutRef<'li'> {
+    ref?: Ref<HTMLLIElement>;
+    /**
+     * The rejected file to display
+     */
+    rejectedFile: RejectedFileType;
+    /**
+     * Function to render the error message for each error code
+     * @param error - The error code
+     * @returns The error message to display
+     */
+    renderError: (error: FileUploadFileError) => string;
+    /**
+     * Accessible label for the delete button
+     */
+    deleteButtonAriaLabel: string;
+    className?: string;
+}
+export declare const RejectedFile: {
+    ({ className, rejectedFile, renderError, deleteButtonAriaLabel, ...props }: FileUploadRejectedFileProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadRejectedFileDeleteTrigger.d.ts

@@ -0,0 +1,12 @@
+import { IconButton } from '../icon-button';
+import { RejectedFile as RejectedFileType } from './FileUpload';
+export interface FileUploadRejectedFileDeleteTriggerProps extends React.ComponentProps<typeof IconButton> {
+    /**
+     * The rejected file to remove
+     */
+    rejectedFile: RejectedFileType;
+}
+export declare const RejectedFileDeleteTrigger: {
+    ({ className, rejectedFile, onClick, ...props }: FileUploadRejectedFileDeleteTriggerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/FileUploadTrigger.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode, Ref } from 'react';
+import { ButtonProps } from '../button';
+export interface FileUploadTriggerProps extends Omit<ButtonProps, 'children' | 'disabled'> {
+    ref?: Ref<HTMLButtonElement>;
+    className?: string;
+    children: ReactNode;
+    unstyled?: boolean;
+}
+export declare const Trigger: {
+    ({ className, children, asChild, unstyled, design, intent, size, shape, ref, ...props }: FileUploadTriggerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/file-upload/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File upload error codes
+ */
+export declare const FILE_UPLOAD_ERRORS: {
+    /**
+     * Exceeds the maxFiles limit
+     */
+    readonly TOO_MANY_FILES: "TOO_MANY_FILES";
+    /**
+     * File type not in the accept list
+     */
+    readonly FILE_INVALID_TYPE: "FILE_INVALID_TYPE";
+    /**
+     * File size exceeds maxFileSize
+     */
+    readonly FILE_TOO_LARGE: "FILE_TOO_LARGE";
+    /**
+     * File size below minFileSize
+     */
+    readonly FILE_TOO_SMALL: "FILE_TOO_SMALL";
+    /**
+     * Generic validation failure
+     */
+    readonly FILE_INVALID: "FILE_INVALID";
+    /**
+     * Duplicate file detected
+     */
+    readonly FILE_EXISTS: "FILE_EXISTS";
+};

package/dist/src/file-upload/index.d.mts

@@ -0,0 +1,22 @@
+import { FileAcceptDetails, FileChangeDetails, FileRejectDetails, FileUpload as Root, FileUploadFileError, RejectedFile } from './FileUpload';
+import { AcceptedFile } from './FileUploadAcceptedFile';
+import { Context } from './FileUploadContext';
+import { FILE_UPLOAD_ERRORS } from './constants';
+import { Dropzone } from './FileUploadDropzone';
+import { ItemDeleteTrigger } from './FileUploadItemDeleteTrigger';
+import { PreviewImage } from './FileUploadPreviewImage';
+import { RejectedFile as RejectedFileComponent } from './FileUploadRejectedFile';
+import { RejectedFileDeleteTrigger } from './FileUploadRejectedFileDeleteTrigger';
+import { Trigger } from './FileUploadTrigger';
+export type { FileAcceptDetails, FileChangeDetails, FileRejectDetails, RejectedFile, FileUploadFileError, };
+export { FILE_UPLOAD_ERRORS };
+export declare const FileUpload: typeof Root & {
+    Trigger: typeof Trigger;
+    Dropzone: typeof Dropzone;
+    Context: typeof Context;
+    ItemDeleteTrigger: typeof ItemDeleteTrigger;
+    PreviewImage: typeof PreviewImage;
+    AcceptedFile: typeof AcceptedFile;
+    RejectedFile: typeof RejectedFileComponent;
+    RejectedFileDeleteTrigger: typeof RejectedFileDeleteTrigger;
+};

package/dist/src/file-upload/index.d.ts

@@ -0,0 +1,22 @@
+import { FileAcceptDetails, FileChangeDetails, FileRejectDetails, FileUpload as Root, FileUploadFileError, RejectedFile } from './FileUpload';
+import { AcceptedFile } from './FileUploadAcceptedFile';
+import { Context } from './FileUploadContext';
+import { FILE_UPLOAD_ERRORS } from './constants';
+import { Dropzone } from './FileUploadDropzone';
+import { ItemDeleteTrigger } from './FileUploadItemDeleteTrigger';
+import { PreviewImage } from './FileUploadPreviewImage';
+import { RejectedFile as RejectedFileComponent } from './FileUploadRejectedFile';
+import { RejectedFileDeleteTrigger } from './FileUploadRejectedFileDeleteTrigger';
+import { Trigger } from './FileUploadTrigger';
+export type { FileAcceptDetails, FileChangeDetails, FileRejectDetails, RejectedFile, FileUploadFileError, };
+export { FILE_UPLOAD_ERRORS };
+export declare const FileUpload: typeof Root & {
+    Trigger: typeof Trigger;
+    Dropzone: typeof Dropzone;
+    Context: typeof Context;
+    ItemDeleteTrigger: typeof ItemDeleteTrigger;
+    PreviewImage: typeof PreviewImage;
+    AcceptedFile: typeof AcceptedFile;
+    RejectedFile: typeof RejectedFileComponent;
+    RejectedFileDeleteTrigger: typeof RejectedFileDeleteTrigger;
+};

package/dist/src/file-upload/test-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Helper function to simulate file upload in tests.
+ * Use this instead of userEvent.upload for file inputs, as userEvent.upload
+ * doesn't work correctly in this test environment.
+ *
+ * @param input - The file input element
+ * @param files - Single file or array of files to upload
+ */
+export declare const uploadFiles: (input: HTMLInputElement, files: File | File[]) => void;

package/dist/src/file-upload/useFileUploadState.d.ts

@@ -0,0 +1,88 @@
+import { FILE_UPLOAD_ERRORS } from './constants';
+export type FileUploadFileError = typeof FILE_UPLOAD_ERRORS.TOO_MANY_FILES | typeof FILE_UPLOAD_ERRORS.FILE_INVALID_TYPE | typeof FILE_UPLOAD_ERRORS.FILE_TOO_LARGE | typeof FILE_UPLOAD_ERRORS.FILE_TOO_SMALL | typeof FILE_UPLOAD_ERRORS.FILE_INVALID | typeof FILE_UPLOAD_ERRORS.FILE_EXISTS;
+export interface RejectedFile {
+    file: File;
+    errors: FileUploadFileError[];
+}
+export interface FileAcceptDetails {
+    files: File[];
+}
+export interface FileRejectDetails {
+    files: RejectedFile[];
+}
+export interface FileChangeDetails {
+    acceptedFiles: File[];
+    rejectedFiles: RejectedFile[];
+}
+export interface UseFileUploadStateProps {
+    /**
+     * Initial files to display when the component mounts (uncontrolled mode)
+     */
+    defaultValue?: File[];
+    /**
+     * Controlled files value (controlled mode)
+     * When provided, the component becomes controlled
+     */
+    value?: File[];
+    /**
+     * Callback when files are accepted
+     */
+    onFileAccept?: (details: FileAcceptDetails) => void;
+    /**
+     * Callback when files are rejected
+     */
+    onFileReject?: (details: FileRejectDetails) => void;
+    /**
+     * Callback when files change (both accepted and rejected)
+     * For controlled mode, use this to update the value prop by extracting details.acceptedFiles
+     */
+    onFileChange?: (details: FileChangeDetails) => void;
+    /**
+     * Whether multiple files can be selected
+     * @default true
+     */
+    multiple?: boolean;
+    /**
+     * Comma-separated list of accepted file types
+     */
+    accept?: string;
+    /**
+     * Maximum number of files that can be uploaded
+     */
+    maxFiles?: number;
+    /**
+     * Maximum file size in bytes
+     */
+    maxFileSize?: number;
+    /**
+     * Minimum file size in bytes
+     */
+    minFileSize?: number;
+    /**
+     * When `true`, prevents the user from interacting with the file upload
+     */
+    disabled?: boolean;
+    /**
+     * When `true`, sets the file upload to read-only mode
+     */
+    readOnly?: boolean;
+    /**
+     * The [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code for the locale.
+     * Used for formatting file sizes and error messages.
+     */
+    locale?: string;
+}
+export interface UseFileUploadStateReturn {
+    files: File[];
+    rejectedFiles: RejectedFile[];
+    addFiles: (files: File[]) => void;
+    removeFile: (index: number) => void;
+    removeRejectedFile: (index: number) => void;
+    clearFiles: () => void;
+    clearRejectedFiles: () => void;
+    maxFilesReached: boolean;
+}
+/**
+ * Hook that manages file upload state, validation, and file operations
+ */
+export declare function useFileUploadState({ defaultValue, value: controlledValue, onFileAccept, onFileReject, onFileChange, multiple, accept, maxFiles, maxFileSize, minFileSize, disabled, readOnly, locale, }: UseFileUploadStateProps): UseFileUploadStateReturn;

package/dist/src/file-upload/utils.d.ts

@@ -0,0 +1,40 @@
+import { ReactElement, RefObject } from 'react';
+/**
+ * Validates if a file matches the accept patterns
+ * Supports MIME types (e.g., "image/*", "image/png", "application/pdf")
+ * and file extensions (e.g., ".pdf", ".doc", ".jpg")
+ */
+export declare function validateFileAccept(file: File, accept: string): boolean;
+/**
+ * Validates if a file size is within the allowed range
+ * @param file - The file to validate
+ * @param minFileSize - Minimum file size in bytes
+ * @param maxFileSize - Maximum file size in bytes
+ * @param locale - Locale code for error messages. Defaults to browser locale or 'en'
+ * @returns Object with validation result and error message if invalid
+ */
+export declare function validateFileSize(file: File, minFileSize?: number, maxFileSize?: number, locale?: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Formats file size in bytes to human-readable format
+ * @param bytes - File size in bytes
+ * @param locale - Locale code (e.g., 'en', 'fr'). Defaults to browser locale or 'en'
+ * @returns Formatted file size string with appropriate unit
+ */
+export declare function formatFileSize(bytes: number, locale?: string): string;
+/**
+ * Returns the appropriate icon component based on the file type
+ * @param file - The file to get the icon for
+ * @returns React element representing the icon component
+ */
+export declare function getFileIcon(file: File): ReactElement;
+/**
+ * Finds the first focusable element from a list of candidates
+ * Falls back to inputRef if no other element is focusable
+ * @param candidates - Array of candidate elements to check
+ * @param inputRef - Input element to use as last resort
+ * @returns The first focusable element, or null if none found
+ */
+export declare function findFocusableElement(candidates: (HTMLElement | null)[], inputRef: RefObject<HTMLInputElement | null>): HTMLElement | null;

package/dist/src/form-field/FormField.d.ts

@@ -0,0 +1,21 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+import { FormFieldContextState } from './FormFieldContext';
+export interface FormFieldProps extends ComponentPropsWithoutRef<'div'>, Pick<FormFieldContextState, 'name' | 'state' | 'isRequired'> {
+    /**
+     * Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
+     */
+    asChild?: boolean;
+    /**
+     * When `true`, prevents the user from interacting.
+     */
+    disabled?: boolean;
+    /**
+     * Sets the component as interactive or not.
+     */
+    readOnly?: boolean;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare const FormField: {
+    ({ className, disabled, readOnly, name, state, isRequired, asChild, ref, ...others }: FormFieldProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/form-field/FormFieldAlertMessage.d.ts

@@ -0,0 +1,9 @@
+import { Ref } from 'react';
+import { FormFieldStateMessageProps } from './FormFieldStateMessage';
+export type FormFieldAlertMessageProps = Omit<FormFieldStateMessageProps, 'state'> & {
+    ref?: Ref<HTMLSpanElement>;
+};
+export declare const FormFieldAlertMessage: {
+    ({ ref, ...props }: FormFieldAlertMessageProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/form-field/FormFieldCharactersCount.d.ts

@@ -0,0 +1,26 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+export type FormFieldCharactersCountProps = ComponentPropsWithoutRef<'span'> & {
+    /**
+     * This description is for the screen reader, read when the input is focused.
+     */
+    description?: string;
+    /**
+     * The live announcement is for the screen read after a delay once the input value changes.
+     */
+    liveAnnouncement?: ({ remainingChars }: {
+        remainingChars: number;
+    }) => string;
+    /**
+     * Current value for the input this component belongs to.
+     */
+    value?: string;
+    /**
+     * Maximum numeric value to be displayed.
+     */
+    maxLength: number;
+    ref?: Ref<HTMLSpanElement>;
+};
+export declare const FormFieldCharactersCount: {
+    ({ className, value, maxLength, description, liveAnnouncement, ref, ...others }: FormFieldCharactersCountProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/src/form-field/FormFieldContext.d.ts

@@ -0,0 +1,49 @@
+export interface FormFieldContextState {
+    /**
+     * Generated id for the input component.
+     */
+    id: string;
+    /**
+     * Generated id for the label component.
+     */
+    labelId?: string;
+    /**
+     * The name of the input. Submitted with its owning form as part of a name/value pair.
+     */
+    name?: string;
+    /**
+     * A set of ids separated by a space used to describe the input component given by a set of messages.
+     */
+    description?: string;
+    /**
+     * Disables the field and its associated input
+     */
+    disabled?: boolean;
+    /**
+     * Marks the field and its associated input as read only
+     */
+    readOnly?: boolean;
+    /**
+     * The validation state of the input.
+     */
+    state?: 'error' | 'success' | 'alert';
+    /**
+     * If true, the form field will be invalid.
+     */
+    isInvalid?: boolean;
+    /**
+     * If true, the form field will be required.
+     */
+    isRequired?: boolean;
+    /**
+     * Callback used to store a descriptive message.
+     */
+    onMessageIdAdd: (id: string) => void;
+    /**
+     * Callback used to remove a descriptive message.
+     */
+    onMessageIdRemove: (id: string) => void;
+}
+export declare const FormFieldContext: import('react').Context<FormFieldContextState | null>;
+export declare const ID_PREFIX = ":form-field";
+export declare const useFormField: () => FormFieldContextState;