import { CheckboxGroupLayout, CheckboxGroupOption, CheckboxMode } from '@mezzanine-ui/core/checkbox';
import { ChangeEvent, ChangeEventHandler, ComponentProps, ReactNode } from 'react';
import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
import Checkbox from './Checkbox';
export interface CheckboxGroupChangeEventTarget extends HTMLInputElement {
    values: string[];
}
export type CheckboxGroupChangeEvent = ChangeEvent<HTMLInputElement> & {
    target: CheckboxGroupChangeEventTarget;
};
export declare function assignCheckboxGroupValuesToEvent(event: ChangeEvent<HTMLInputElement>, values: string[], name: string): CheckboxGroupChangeEvent;
type CheckboxGroupOptionInput = CheckboxGroupOption & Omit<ComponentProps<typeof Checkbox>, 'checked' | 'mode' | 'children' | 'defaultChecked' | 'indeterminate' | 'inputProps' | 'inputRef' | 'name' | 'onChange' | 'ref' | 'value'> & {
    /**
     * The id of input element.
     * If not provided, will be auto-generated as `{name}-{value}`.
     */
    id?: string;
    /**
     * The react ref passed to input element.
     */
    inputRef?: ComponentProps<typeof Checkbox>['inputRef'];
    /**
     * Additional props for the input element.
     */
    inputProps?: ComponentProps<typeof Checkbox>['inputProps'];
};
export interface CheckboxGroupLevelConfig {
    /**
     * Whether the level control is active.
     */
    active: boolean;
    /**
     * Whether the level control checkbox is disabled.
     * @default false
     */
    disabled?: boolean;
    /**
     * The label displayed for the level control checkbox.
     * @default 'Select all'
     */
    label?: string;
    /**
     * The mode of level control checkbox.
     * @default 'main'
     */
    mode?: CheckboxMode;
    /**
     * Custom onChange handler for the level control.
     * If not provided, the default behavior (select/deselect all) will be used.
     */
    onChange?: ChangeEventHandler<HTMLInputElement>;
}
interface CheckboxGroupBaseProps extends NativeElementPropsWithoutKeyAndRef<'div'> {
    /**
     * The default value of checkbox group.
     */
    defaultValue?: string[];
    /**
     * Whether the checkbox group is disabled.
     * Control the disabled of checkboxes in group if disabled not passed to checkbox.
     */
    disabled?: boolean;
    /**
     * The level control configuration.
     * When provided, a "select all" checkbox will be rendered above the group.
     */
    level?: CheckboxGroupLevelConfig;
    /**
     * The layout of checkbox group.
     * @default 'horizontal'
     */
    layout?: CheckboxGroupLayout;
    /**
     * The mode of checkboxes in the group.
     * Control the mode of checkboxes in group if mode not passed to checkbox.
     */
    mode?: CheckboxMode;
    /**
     * The name of checkbox group.
     * Control the name of checkboxes in group if name not passed to checkbox.
     *
     * @important When integrating with react-hook-form, this prop is highly recommended.
     * All checkboxes in the group will share the same `name` attribute, which is required
     * for react-hook-form to correctly collect the selected values as an array.
     *
     * @example Using with react-hook-form's Controller:
     * ```tsx
     * const { control } = useForm();
     * <Controller
     *   name="interests"
     *   control={control}
     *   render={({ field }) => (
     *     <CheckboxGroup
     *       name="interests"
     *       value={field.value || []}
     *       onChange={(e) => field.onChange(e.target.values)}
     *     >
     *       <Checkbox value="reading" label="Reading" />
     *       <Checkbox value="coding" label="Coding" />
     *     </CheckboxGroup>
     *   )}
     * />
     * ```
     */
    name?: string;
    /**
     * The onChange of checkbox group.
     * Provides the latest `values` array via `event.target.values`.
     */
    onChange?: (event: CheckboxGroupChangeEvent) => void;
    /**
     * The value of checkbox group.
     */
    value?: string[];
}
interface CheckboxGroupOptionsInputProps extends CheckboxGroupBaseProps {
    children?: never;
    options: CheckboxGroupOptionInput[];
}
interface CheckboxGroupChildrenInputProps extends CheckboxGroupBaseProps {
    children: ReactNode;
    options?: never;
}
export type CheckboxGroupProps = CheckboxGroupOptionsInputProps | CheckboxGroupChildrenInputProps;
/**
 * 核取方塊群組元件，用於管理一組具有相同 `name` 的核取方塊。
 *
 * 支援透過 `options` 陣列或 `children` 傳入子元件兩種方式渲染選項，並可透過
 * `layout` 控制水平或垂直排列。啟用 `level` 設定可顯示「全選」控制核取方塊，
 * 勾選狀態會自動計算 indeterminate 中間態；`onChange` 回呼透過 `event.target.values`
 * 提供最新已選取的值陣列。
 *
 * @example
 * ```tsx
 * import CheckboxGroup from '@mezzanine-ui/react/CheckboxGroup';
 * import Checkbox from '@mezzanine-ui/react/Checkbox';
 *
 * // 使用 options 陣列
 * <CheckboxGroup
 *   name="fruits"
 *   defaultValue={['apple']}
 *   options={[
 *     { label: '蘋果', value: 'apple' },
 *     { label: '香蕉', value: 'banana' },
 *     { label: '橘子', value: 'orange' },
 *   ]}
 *   onChange={(e) => console.log(e.target.values)}
 * />
 *
 * // 使用 children 方式，垂直排列
 * <CheckboxGroup name="options" layout="vertical">
 *   <Checkbox label="選項一" value="a" />
 *   <Checkbox label="選項二" value="b" />
 * </CheckboxGroup>
 *
 * // 啟用全選控制
 * <CheckboxGroup
 *   name="items"
 *   options={[{ label: '項目 A', value: 'a' }, { label: '項目 B', value: 'b' }]}
 *   level={{ active: true, label: '全選' }}
 * />
 * ```
 *
 * @see {@link Checkbox} 單一核取方塊元件
 */
declare const CheckboxGroup: import("react").ForwardRefExoticComponent<CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
export default CheckboxGroup;