/**
 * @file Switch.tsx
 * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
 * @output Exports Switch component, SwitchProps, SwitchLabelPosition, SwitchLabelSpacing
 * @position Core implementation; consumed by index.ts, tested by Switch.test.tsx
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Switch/Switch.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/Switch/Switch.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Switch/index.ts (exports if types change)
 * - /apps/storybook/stories/Switch.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Switch/ (showcase blocks)
 */
import { type ChangeEvent, type FocusEvent, type ReactNode } from 'react';
import type { IconType } from '../Icon';
import type { InputStatus } from '../Field/types';
import type { BaseProps } from '../BaseProps';
import type { SizeValue } from '../utils/types';
export type SwitchLabelPosition = 'start' | 'end';
export type SwitchLabelSpacing = 'hug' | 'spread';
export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
    /** Ref forwarded to the root element */
    ref?: React.Ref<HTMLInputElement>;
    /**
     * Label text for the switch (always rendered for accessibility).
     */
    label: string;
    /**
     * Whether to visually hide the label (still accessible to screen readers).
     * @default false
     */
    isLabelHidden?: boolean;
    /**
     * Description text displayed below the label.
     */
    description?: string;
    /**
     * Callback fired when the switch state changes.
     */
    onChange?: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void;
    /**
     * Async action on change. Fires after onChange if not prevented.
     */
    changeAction?: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>;
    /**
     * Whether the switch is in a loading state.
     * @default false
     */
    isLoading?: boolean;
    /**
     * Whether the switch is on or off.
     */
    value: boolean;
    /**
     * Whether the switch is disabled.
     * @default false
     */
    isDisabled?: boolean;
    /**
     * The HTML name attribute for the underlying checkbox input.
     * Useful for form submissions.
     */
    htmlName?: string;
    /**
     * Explains why the switch is disabled. When set together with `isDisabled`,
     * the switch shows a tooltip with this text on hover and keyboard focus, and
     * the control stays focusable (via `aria-disabled`) so the reason is
     * discoverable by keyboard and assistive technology. Activation stays
     * blocked.
     *
     * Use this instead of wrapping a disabled switch in `Tooltip` — disabled
     * controls don't emit the pointer events an external tooltip needs.
     *
     * @example
     * ```
     * <Switch
     *   label="Enable notifications"
     *   value={enabled}
     *   isDisabled
     *   disabledMessage="Notifications are turned off org-wide"
     * />
     * ```
     */
    disabledMessage?: string;
    /**
     * Whether the field is optional. Mutually exclusive with isRequired.
     * @default false
     */
    isOptional?: boolean;
    /**
     * Whether the switch is required. Mutually exclusive with isOptional.
     * @default false
     */
    isRequired?: boolean;
    /**
     * Callback fired when the switch receives focus.
     */
    onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
    /**
     * Callback fired when the switch loses focus.
     */
    onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
    /**
     * Icon to display before the label text.
     */
    labelIcon?: ReactNode | IconType;
    /**
     * Width of the field. Numbers are treated as pixels, strings are used as-is
     * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
     * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
     */
    width?: SizeValue;
    /**
     * Tooltip text to display in an info icon at the end of the label.
     */
    labelTooltip?: string;
    /**
     * Which side of the switch the label appears on.
     * - 'start': Label appears before the switch
     * - 'end': Label appears after the switch
     * @default 'end'
     */
    labelPosition?: SwitchLabelPosition;
    /**
     * Spacing behavior between label and switch.
     * - 'hug': Label and switch are positioned next to each other
     * - 'spread': Label and switch are pushed to opposite ends
     * @default 'hug'
     */
    labelSpacing?: SwitchLabelSpacing;
    /**
     * Status indicator for the switch.
     * When set with a message, displays a colored message box below the switch.
     */
    status?: InputStatus;
    /**
     * Size variant controlling track and thumb dimensions.
     * - 'sm': 34x20px (matches sm checkbox/radio vertical rhythm)
     * - 'md': 40x24px (default, matches md checkbox/radio vertical rhythm)
     * @default 'md'
     */
    size?: 'sm' | 'md';
}
/**
 * A toggle switch component for boolean values.
 *
 * @example
 * ```
 * <Switch
 *   label="Enable notifications"
 *   value={enabled}
 *   onChange={setEnabled}
 * />
 * <Switch
 *   label="Dark mode"
 *   description="Switch to a darker color scheme"
 *   value={darkMode}
 *   onChange={setDarkMode}
 * />
 * ```
 */
export declare function Switch({ label, isLabelHidden, description, onChange, changeAction, isLoading, value, isDisabled, htmlName, disabledMessage, isOptional, isRequired, onFocus, onBlur, labelIcon, labelTooltip, labelPosition, labelSpacing, status, size, width, xstyle, className, style, ref, ...rest }: SwitchProps): import("react").JSX.Element;
export declare namespace Switch {
    var displayName: string;
}
//# sourceMappingURL=Switch.d.ts.map