import { ChangeEventHandler, Ref } from 'react';
import { CheckboxSize } from '@mezzanine-ui/core/checkbox';
import { BaseInputProps } from '../Input';
import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
import { CheckboxPropsBase } from './typings';
type CheckboxInputElementProps = Omit<NativeElementPropsWithoutKeyAndRef<'input'>, 'checked' | 'defaultChecked' | 'disabled' | 'onChange' | 'placeholder' | 'type' | 'value' | `aria-${'disabled' | 'checked'}`> & {
    /**
     * The id attribute can be provided via inputProps, but it's recommended to use the `id` prop directly.
     * If both are provided, the `id` prop takes precedence.
     */
    id?: string;
    /**
     * The name attribute can be provided via inputProps, but it's recommended to use the `name` prop directly.
     * If both are provided, the `name` prop takes precedence.
     */
    name?: string;
};
export interface CheckboxProps extends Omit<NativeElementPropsWithoutKeyAndRef<'label'>, 'onChange'>, CheckboxPropsBase {
    /**
     * Whether to show an editable input when checkbox is checked.
     * When `true`, an Input component will be displayed after the checkbox when checked.
     * If `editableInput` is not provided, default values will be used (name, id, placeholder).
     *
     * @example Simple usage
     * ```tsx
     * <Checkbox
     *   label="其他"
     *   withEditInput
     *   value={otherValue}
     *   onChange={(e) => setOtherValue(e.target.value)}
     * />
     * ```
     *
     * @example With custom editableInput
     * ```tsx
     * <Checkbox
     *   label="其他"
     *   withEditInput
     *   editableInput={{
     *     placeholder: "請輸入其他選項",
     *     name: "otherOption",
     *     value: otherValue,
     *     onChange: (e) => setOtherValue(e.target.value),
     *   }}
     * />
     * ```
     *
     * @example With react-hook-form
     * ```tsx
     * const { register, watch } = useForm();
     * const isOtherChecked = watch('options.other');
     *
     * <Checkbox
     *   label="其他"
     *   {...register('options.other')}
     *   withEditInput
     *   editableInput={{
     *     ...register('otherOption', { required: isOtherChecked }),
     *     placeholder: "請輸入其他選項",
     *   }}
     * />
     * ```
     */
    withEditInput?: boolean;
    /**
     * Configuration for editable input that appears when checkbox is checked.
     * When `withEditInput` is `true` and this prop is not provided, default values will be used.
     *
     * Default values when not provided:
     * - `name`: `{checkboxName}_input` or `{checkboxId}_input`
     * - `id`: `{checkboxId}_input`
     * - `placeholder`: "Please enter..."
     */
    editableInput?: Omit<BaseInputProps, 'variant'>;
    /**
     * The id of input element.
     */
    id?: string;
    /**
     * Since at Mezzanine we use a host element to wrap our input, most derived props will be passed to the host element.
     * If you need direct control to the input element, use this prop to provide to it.
     */
    inputProps?: CheckboxInputElementProps;
    /**
     * The react ref passed to input element.
     *
     * @important When using with react-hook-form's `register`, pass the ref through this prop:
     * ```tsx
     * const { register } = useForm();
     * <Checkbox inputRef={register('fieldName').ref} name="fieldName" />
     * ```
     *
     * For CheckboxGroup, use `Controller` instead of `register` for better array value handling.
     */
    inputRef?: Ref<HTMLInputElement>;
    /**
     * The name attribute of the input element.
     *
     * @important When using with react-hook-form or inside a CheckboxGroup, this prop is recommended.
     * For CheckboxGroup, all checkboxes should share the same `name` attribute.
     *
     * When using with react-hook-form's `register`, ensure this matches the field name:
     * ```tsx
     * const { register } = useForm();
     * <Checkbox {...register('fieldName')} inputRef={register('fieldName').ref} />
     * ```
     */
    name?: string;
    /**
     * Invoked by input change event.
     */
    onChange?: ChangeEventHandler<HTMLInputElement>;
    /**
     * The value of checkbox. Used when checkbox is inside a CheckboxGroup.
     *
     * @important This prop is required when checkbox is inside a CheckboxGroup.
     * It is also recommended when integrating with react-hook-form.
     */
    value?: string;
    /**
     * The size of checkbox.
     * When mode is 'chip', size can be 'main' | 'sub' | 'minor'.
     * When mode is 'default', size can be 'main' | 'sub'.
     * @default 'main'
     */
    size?: CheckboxSize<NonNullable<CheckboxPropsBase['mode']>>;
}
/**
 * 核取方塊元件，支援預設（default）與晶片（chip）兩種模式。
 *
 * 提供受控與非受控兩種使用方式，可透過 `checked`／`defaultChecked` 切換狀態。
 * 在 `CheckboxGroup` 內使用時，必須提供 `value` 屬性；支援 `indeterminate` 中間狀態
 * 及 `withEditInput` 勾選後顯示附加輸入框的功能。
 *
 * @example
 * ```tsx
 * import Checkbox from '@mezzanine-ui/react/Checkbox';
 *
 * // 基本用法（非受控）
 * <Checkbox label="同意條款" defaultChecked />
 *
 * // 受控用法
 * const [checked, setChecked] = useState(false);
 * <Checkbox
 *   checked={checked}
 *   label="訂閱電子報"
 *   onChange={(e) => setChecked(e.target.checked)}
 * />
 *
 * // Chip 模式
 * <Checkbox label="熱門" mode="chip" size="sub" />
 *
 * // 含附加輸入框
 * <Checkbox label="其他" withEditInput editableInput={{ placeholder: '請輸入其他選項' }} />
 * ```
 *
 * @see {@link CheckboxGroup} 管理多個核取方塊的群組元件
 * @see {@link useCheckboxControlValue} 核取方塊受控值的自訂 Hook
 */
declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLLabelElement>>;
export default Checkbox;