@page-speed/forms 0.2.3 → 0.3.0

package/dist/inputs.d.ts

@@ -580,6 +580,21 @@ interface FileValidationError {
     error: "type" | "size" | "count";
     message: string;
 }
+/**
+ * Upload progress tracking per file
+ */
+interface FileUploadProgress {
+    [fileName: string]: number;
+}
+/**
+ * Crop area coordinates
+ */
+interface CropArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 /**
  * FileInput component props
  */
@@ -618,6 +633,31 @@ interface FileInputProps extends Omit<InputProps<File[]>, "value" | "onChange">
      * @default true
      */
     showPreview?: boolean;
+    /**
+     * Show upload progress indicators
+     * @default true
+     */
+    showProgress?: boolean;
+    /**
+     * Upload progress per file (0-100)
+     * Consumer should update this during upload
+     */
+    uploadProgress?: FileUploadProgress;
+    /**
+     * Enable image cropping for image files
+     * @default false
+     */
+    enableCropping?: boolean;
+    /**
+     * Crop aspect ratio (width / height)
+     * @default Free form (no constraint)
+     * @example 16/9, 1, 4/3
+     */
+    cropAspectRatio?: number;
+    /**
+     * Crop complete handler - receives cropped blob and original file
+     */
+    onCropComplete?: (croppedBlob: Blob, originalFile: File) => void;
     /**
      * Validation error handler
      */
@@ -628,7 +668,15 @@ interface FileInputProps extends Omit<InputProps<File[]>, "value" | "onChange">
     onFileRemove?: (file: File, index: number) => void;
 }
 /**
- * FileInput component for file selection with validation
+ * FileInput component for file selection with validation, progress tracking, and image cropping
+ *
+ * Features:
+ * - Drag-and-drop file upload
+ * - File type and size validation
+ * - Image preview thumbnails
+ * - Upload progress indicators
+ * - Image cropping with aspect ratio control
+ * - Multiple file support
  *
  * @example
  * ```tsx
@@ -641,11 +689,480 @@ interface FileInputProps extends Omit<InputProps<File[]>, "value" | "onChange">
  *   error={hasError}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // With upload progress
+ * <FileInput
+ *   name="photos"
+ *   accept="image/*"
+ *   multiple
+ *   value={files}
+ *   onChange={setFiles}
+ *   showProgress
+ *   uploadProgress={progress}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With image cropping
+ * <FileInput
+ *   name="avatar"
+ *   accept="image/*"
+ *   value={files}
+ *   onChange={setFiles}
+ *   enableCropping
+ *   cropAspectRatio={1}
+ *   onCropComplete={(blob, file) => {
+ *     // Handle cropped image
+ *   }}
+ * />
+ * ```
  */
 declare function FileInput({ name, value, onChange, onBlur, placeholder, disabled, required, error, className, accept, maxSize, // 5MB default
-maxFiles, multiple, showPreview, onValidationError, onFileRemove, ...props }: FileInputProps): React.JSX.Element;
+maxFiles, multiple, showPreview, showProgress, uploadProgress, enableCropping, cropAspectRatio, onCropComplete, onValidationError, onFileRemove, ...props }: FileInputProps): React.JSX.Element;
 declare namespace FileInput {
     var displayName: string;
 }
 
-export { Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, FileInput, type FileInputProps, type FileValidationError, Radio, type RadioOption, type RadioProps, Select, type SelectOption, type SelectOptionGroup, type SelectProps, TextArea, type TextAreaProps, TextInput };
+/**
+ * DatePicker props interface
+ */
+interface DatePickerProps extends Omit<InputProps<Date | null>, "onChange"> {
+    /**
+     * Change handler - receives selected date or null
+     */
+    onChange: (date: Date | null) => void;
+    /**
+     * Placeholder text when no date is selected
+     * @default "Select date..."
+     */
+    placeholder?: string;
+    /**
+     * Date format for display
+     * @default "MM/dd/yyyy"
+     */
+    format?: string;
+    /**
+     * Minimum selectable date
+     */
+    minDate?: Date;
+    /**
+     * Maximum selectable date
+     */
+    maxDate?: Date;
+    /**
+     * Dates that should be disabled
+     */
+    disabledDates?: Date[];
+    /**
+     * Function to determine if a date should be disabled
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /**
+     * Show clear button
+     * @default true
+     */
+    clearable?: boolean;
+    /**
+     * Show calendar icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Additional native input attributes
+     */
+    [key: string]: any;
+}
+/**
+ * DatePicker - Accessible date selection component with calendar UI
+ *
+ * A lightweight date picker with calendar popup, keyboard navigation,
+ * and error state support. Designed to work seamlessly with useForm and Field components.
+ *
+ * Features:
+ * - Calendar popup with month/year navigation
+ * - Full accessibility support (ARIA attributes, keyboard navigation)
+ * - Error state styling
+ * - Controlled input behavior
+ * - Date range constraints (min/max dates)
+ * - Disabled dates support
+ * - Clearable selection
+ * - Custom date format display
+ * - Icon display toggle
+ * - Click outside to close
+ * - Native date input fallback for mobile
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ initialValues: { birthdate: null } });
+ *
+ * <DatePicker
+ *   {...form.getFieldProps('birthdate')}
+ *   placeholder="Select your birthdate"
+ *   format="MM/dd/yyyy"
+ *   maxDate={new Date()}
+ *   clearable
+ *   showIcon
+ *   error={!!form.errors.birthdate}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With date range constraints
+ * <DatePicker
+ *   name="appointment"
+ *   value={appointmentDate}
+ *   onChange={setAppointmentDate}
+ *   minDate={new Date()}
+ *   maxDate={addDays(new Date(), 90)}
+ *   isDateDisabled={(date) => date.getDay() === 0 || date.getDay() === 6}
+ * />
+ * ```
+ *
+ * Note: This component requires react-day-picker as a peer dependency.
+ * Install with: npm install react-day-picker date-fns
+ *
+ * @see https://opensite.ai/developers/page-speed/forms/date-picker
+ */
+declare function DatePicker({ name, value, onChange, onBlur, disabled, required, error, className, placeholder, format, minDate, maxDate, disabledDates, isDateDisabled, clearable, showIcon, ...props }: DatePickerProps): React.JSX.Element;
+declare namespace DatePicker {
+    var displayName: string;
+}
+
+/**
+ * Time value format
+ */
+interface TimeValue {
+    hour: number;
+    minute: number;
+    period: "AM" | "PM";
+}
+/**
+ * TimePicker props interface
+ */
+interface TimePickerProps extends Omit<InputProps<string>, "onChange"> {
+    /**
+     * Change handler - receives time string in format "HH:mm AM/PM"
+     */
+    onChange: (time: string) => void;
+    /**
+     * Placeholder text when no time is selected
+     * @default "Select time..."
+     */
+    placeholder?: string;
+    /**
+     * Use 24-hour format instead of 12-hour with AM/PM
+     * @default false
+     */
+    use24Hour?: boolean;
+    /**
+     * Minute step interval (e.g., 15 for 15-minute increments)
+     * @default 1
+     */
+    minuteStep?: number;
+    /**
+     * Show clear button
+     * @default true
+     */
+    clearable?: boolean;
+    /**
+     * Show clock icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Additional native input attributes
+     */
+    [key: string]: any;
+}
+/**
+ * TimePicker - Accessible time selection component with AM/PM support
+ *
+ * A lightweight time picker with dropdown selection for hours, minutes, and AM/PM period.
+ * Designed to work seamlessly with useForm and Field components.
+ *
+ * Features:
+ * - Dropdown selection with hour/minute spinners
+ * - 12-hour or 24-hour format support
+ * - AM/PM period selector
+ * - Configurable minute step intervals
+ * - Full accessibility support (ARIA attributes, keyboard navigation)
+ * - Error state styling
+ * - Controlled input behavior
+ * - Clearable selection
+ * - Icon display toggle
+ * - Click outside to close
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ initialValues: { appointment: '' } });
+ *
+ * <TimePicker
+ *   {...form.getFieldProps('appointment')}
+ *   placeholder="Select time"
+ *   minuteStep={15}
+ *   clearable
+ *   showIcon
+ *   error={!!form.errors.appointment}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With 24-hour format
+ * <TimePicker
+ *   name="startTime"
+ *   value={startTime}
+ *   onChange={setStartTime}
+ *   use24Hour
+ *   minuteStep={30}
+ * />
+ * ```
+ *
+ * @see https://opensite.ai/developers/page-speed/forms/time-picker
+ */
+declare function TimePicker({ name, value, onChange, onBlur, disabled, required, error, className, placeholder, use24Hour, minuteStep, clearable, showIcon, ...props }: TimePickerProps): React.JSX.Element;
+declare namespace TimePicker {
+    var displayName: string;
+}
+
+/**
+ * Date range value
+ */
+interface DateRange {
+    start: Date | null;
+    end: Date | null;
+}
+/**
+ * DateRangePicker props interface
+ */
+interface DateRangePickerProps extends Omit<InputProps<DateRange>, "onChange"> {
+    /**
+     * Change handler - receives date range object
+     */
+    onChange: (range: DateRange) => void;
+    /**
+     * Placeholder text when no dates are selected
+     * @default "Select date range..."
+     */
+    placeholder?: string;
+    /**
+     * Date format for display
+     * @default "MM/dd/yyyy"
+     */
+    format?: string;
+    /**
+     * Minimum selectable date
+     */
+    minDate?: Date;
+    /**
+     * Maximum selectable date
+     */
+    maxDate?: Date;
+    /**
+     * Dates that should be disabled
+     */
+    disabledDates?: Date[];
+    /**
+     * Function to determine if a date should be disabled
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /**
+     * Show clear button
+     * @default true
+     */
+    clearable?: boolean;
+    /**
+     * Show calendar icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Separator between start and end dates
+     * @default " - "
+     */
+    separator?: string;
+    /**
+     * Additional native input attributes
+     */
+    [key: string]: any;
+}
+/**
+ * DateRangePicker - Accessible date range selection component
+ *
+ * A lightweight date range picker with calendar popup for selecting start and end dates.
+ * Designed to work seamlessly with useForm and Field components.
+ *
+ * Features:
+ * - Dual calendar view for range selection
+ * - Full accessibility support (ARIA attributes, keyboard navigation)
+ * - Error state styling
+ * - Controlled input behavior
+ * - Date range constraints (min/max dates)
+ * - Disabled dates support
+ * - Clearable selection
+ * - Custom date format display
+ * - Visual range highlighting
+ * - Icon display toggle
+ * - Click outside to close
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ initialValues: { dateRange: { start: null, end: null } } });
+ *
+ * <DateRangePicker
+ *   {...form.getFieldProps('dateRange')}
+ *   placeholder="Select date range"
+ *   format="MM/dd/yyyy"
+ *   clearable
+ *   showIcon
+ *   error={!!form.errors.dateRange}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With date constraints
+ * <DateRangePicker
+ *   name="vacation"
+ *   value={vacationRange}
+ *   onChange={setVacationRange}
+ *   minDate={new Date()}
+ *   maxDate={addDays(new Date(), 365)}
+ *   separator=" to "
+ * />
+ * ```
+ *
+ * @see https://opensite.ai/developers/page-speed/forms/date-range-picker
+ */
+declare function DateRangePicker({ name, value, onChange, onBlur, disabled, required, error, className, placeholder, format, minDate, maxDate, disabledDates, isDateDisabled, clearable, showIcon, separator, ...props }: DateRangePickerProps): React.JSX.Element;
+declare namespace DateRangePicker {
+    var displayName: string;
+}
+
+/**
+ * Editor mode type
+ */
+type EditorMode = "wysiwyg" | "markdown";
+/**
+ * Toolbar button configuration
+ */
+interface ToolbarButton {
+    command: string;
+    icon: string;
+    title: string;
+    action: (editor: HTMLElement) => void;
+}
+/**
+ * RichTextEditor props interface
+ */
+interface RichTextEditorProps extends Omit<InputProps<string>, "onChange"> {
+    /**
+     * Change handler - receives HTML or Markdown content
+     */
+    onChange: (content: string) => void;
+    /**
+     * Editor mode - WYSIWYG or Markdown
+     * @default "wysiwyg"
+     */
+    mode?: EditorMode;
+    /**
+     * Allow mode switching
+     * @default false
+     */
+    allowModeSwitch?: boolean;
+    /**
+     * Placeholder text when editor is empty
+     * @default "Start typing..."
+     */
+    placeholder?: string;
+    /**
+     * Minimum height of editor
+     * @default "200px"
+     */
+    minHeight?: string;
+    /**
+     * Maximum height of editor (enables scrolling)
+     */
+    maxHeight?: string;
+    /**
+     * Show toolbar
+     * @default true
+     */
+    showToolbar?: boolean;
+    /**
+     * Toolbar buttons to display
+     * @default ["bold", "italic", "underline", "heading", "bulletList", "orderedList", "link"]
+     */
+    toolbarButtons?: string[];
+    /**
+     * Additional native input attributes
+     */
+    [key: string]: any;
+}
+/**
+ * RichTextEditor - Basic rich text editing component with WYSIWYG and Markdown support
+ *
+ * A lightweight rich text editor with basic formatting capabilities and optional Markdown mode.
+ * Designed to work seamlessly with useForm and Field components.
+ *
+ * Features:
+ * - WYSIWYG editor with contentEditable
+ * - Markdown editor mode
+ * - Configurable toolbar with common formatting options
+ * - Full accessibility support
+ * - Error state styling
+ * - Controlled input behavior
+ * - Custom toolbar configuration
+ * - Mode switching support
+ * - Placeholder text support
+ * - Adjustable height constraints
+ *
+ * Toolbar buttons:
+ * - bold: Bold text (**text**)
+ * - italic: Italic text (*text*)
+ * - underline: Underlined text
+ * - heading: Heading levels (H1-H3)
+ * - bulletList: Unordered list
+ * - orderedList: Ordered list
+ * - link: Insert hyperlink
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ initialValues: { content: '' } });
+ *
+ * <RichTextEditor
+ *   {...form.getFieldProps('content')}
+ *   placeholder="Write your content..."
+ *   mode="wysiwyg"
+ *   allowModeSwitch
+ *   showToolbar
+ *   minHeight="200px"
+ *   maxHeight="500px"
+ *   error={!!form.errors.content}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Markdown mode
+ * <RichTextEditor
+ *   name="description"
+ *   value={description}
+ *   onChange={setDescription}
+ *   mode="markdown"
+ *   toolbarButtons={["bold", "italic", "heading", "link"]}
+ * />
+ * ```
+ *
+ * @see https://opensite.ai/developers/page-speed/forms/rich-text-editor
+ */
+declare function RichTextEditor({ name, value, onChange, onBlur, disabled, required, error, className, mode, allowModeSwitch, placeholder, minHeight, maxHeight, showToolbar, toolbarButtons, ...props }: RichTextEditorProps): React.JSX.Element;
+declare namespace RichTextEditor {
+    var displayName: string;
+}
+
+export { Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, type CropArea, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, type EditorMode, FileInput, type FileInputProps, type FileUploadProgress, type FileValidationError, Radio, type RadioOption, type RadioProps, RichTextEditor, type RichTextEditorProps, Select, type SelectOption, type SelectOptionGroup, type SelectProps, TextArea, type TextAreaProps, TextInput, TimePicker, type TimePickerProps, type TimeValue, type ToolbarButton };