dap-design-system/dist/components/checkbox/checkbox.component.d.ts

Official design system for the DÁP (dap.gov.hu)

import { LabeledChoiceElement } from '../../internal/mixin/labeledChoiceElement';
import { default as DapDSFeedback } from '../feedback/feedback.component';
import { default as DapDSFormLabel } from '../form/form-label/form-label.component';
import { default as SystemCheckLine2 } from '../icons/system/system-check-line2/system-check-line2.component';
import { default as SystemSubtractLine } from '../icons/system/system-subtract-line/system-subtract-line.component';
import { default as DapDSTypography } from '../typography/typography.component';
/**
 * `dap-ds-checkbox`
 * @summary A checkbox is a form element that allows the user to select one or more options from a set.
 * @element dap-ds-checkbox
 * @title - Checkbox
 *
 * @event {{ checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean, type: 'checkbox' }} dds-change - Fired when the checkbox is checked or unchecked.
 * @event {{ void }} dds-blur - Emitted when the checkbox loses focus.
 * @event {{ void }} dds-focus - Emitted when the checkbox gains focus.
 * @event {{ checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean }} dds-input - Emitted when the checkbox receives input.
 *
 * @property {string} name - The name of the checkbox.
 * @property {string} value - The value of the checkbox.
 * @property {boolean} checked - Whether the checkbox is checked.
 * @property {string} label - The label of the checkbox.
 * @property {boolean} hideLabel - Visually hides the label while keeping it available to assistive technology. (default: false)
 * @property {string} description - The description of the checkbox.
 * @property {boolean} disabled - Whether the checkbox is disabled.
 * @property {boolean} readonly - Whether the checkbox is readonly (cannot be changed but value is submitted with form).
 * @property {boolean} required - Whether the checkbox is required.
 * @property {'xs' | 'sm' | 'lg'} size - The size of the checkbox. Default is 'sm'.
 * @property {string} sizeMap - Responsive size map (e.g. "md:lg").
 * @property {'left' | 'right'} labelPlacement - The placement of the label.
 * @property {'top' | 'bottom'} descriptionPlacement - The placement of the description.
 * @property {boolean} subtle - The weight of the label.
 * @property {string} feedback - The feedback of the checkbox.
 * @property {'negative' | 'positive' | 'warning'} feedbackType - The feedback type of the checkbox.
 * @property {boolean} invalid - The invalid state of the checkbox.
 * @property {boolean} optional - The optional state of the checkbox.
 * @property {string} optionalLabel - The optional label of the checkbox.
 * @property {string} requiredLabel - The required indicator of the checkbox. (default: '*')
 *
 * @csspart base - The main checkbox container.
 * @csspart label - The label of the checkbox.
 * @csspart input - The input of the checkbox.
 * @csspart control - The control of the checkbox.
 * @csspart icon - The icon of the checkbox.
 * @csspart icon-base - The base icon container.
 * @csspart label-container - The label container of the checkbox.
 * @csspart description - The description of the checkbox.
 * @csspart readonly - The readonly state of the checkbox.
 *
 * @cssproperty --dds-checkbox-size - The size of the checkbox. (default: var(--dds-spacing-500))
 * @cssproperty --dds-checkbox-border-width - The border width of the checkbox. (default: var(--dds-border-width-large))
 * @cssproperty --dds-checkbox-border-radius - The border radius of the checkbox. (default: var(--dds-radius-small))
 * @cssproperty --dds-checkbox-border-color - The border color of the checkbox. (default: var(--dds-border-neutral-base))
 * @cssproperty --dds-checkbox-background-color - The background color of the checkbox. (default: transparent)
 * @cssproperty --dds-checkbox-icon-color - The color of the checkbox icon. (default: var(--dds-button-primary-icon-enabled))
 * @cssproperty --dds-checkbox-hover-border-color - The border color when hovering over the checkbox. (default: var(--dds-border-neutral-medium))
 * @cssproperty --dds-checkbox-hover-background-color - The background color when hovering over the checkbox. (default: var(--dds-background-neutral-medium))
 * @cssproperty --dds-checkbox-active-border-color - The border color when the checkbox is active. (default: var(--dds-border-neutral-strong))
 * @cssproperty --dds-checkbox-active-background-color - The background color when the checkbox is active. (default: var(--dds-background-neutral-strong))
 * @cssproperty --dds-checkbox-checked-border-color - The border color when the checkbox is checked. (default: var(--dds-background-brand-base-inverted))
 * @cssproperty --dds-checkbox-checked-background-color - The background color when the checkbox is checked. (default: var(--dds-background-brand-base-inverted))
 * @cssproperty --dds-checkbox-checked-hover-border-color - The border color when hovering over a checked checkbox. (default: var(--dds-background-brand-medium-inverted))
 * @cssproperty --dds-checkbox-checked-hover-background-color - The background color when hovering over a checked checkbox. (default: var(--dds-background-brand-medium-inverted))
 * @cssproperty --dds-checkbox-checked-active-border-color - The border color when a checked checkbox is active. (default: var(--dds-background-brand-strong-inverted))
 * @cssproperty --dds-checkbox-checked-active-background-color - The background color when a checked checkbox is active. (default: var(--dds-background-brand-strong-inverted))
 * @cssproperty --dds-checkbox-invalid-border-color - The border color when the checkbox is invalid. (default: var(--dds-border-negative-base))
 * @cssproperty --dds-checkbox-invalid-background-color - The background color when the checkbox is invalid. (default: var(--dds-background-negative-base))
 * @cssproperty --dds-checkbox-invalid-hover-border-color - The border color when hovering over an invalid checkbox. (default: var(--dds-border-negative-medium))
 * @cssproperty --dds-checkbox-invalid-hover-background-color - The background color when hovering over an invalid checkbox. (default: var(--dds-background-negative-medium))
 * @cssproperty --dds-checkbox-invalid-active-border-color - The border color when an invalid checkbox is active. (default: var(--dds-border-negative-strong))
 * @cssproperty --dds-checkbox-invalid-active-background-color - The background color when an invalid checkbox is active. (default: var(--dds-background-negative-strong))
 * @cssproperty --dds-checkbox-disabled-border-color - The border color when the checkbox is disabled. (default: var(--dds-button-primary-background-disabled))
 * @cssproperty --dds-checkbox-disabled-background-color - The background color when the checkbox is disabled. (default: var(--dds-button-primary-background-disabled))
 * @cssproperty --dds-checkbox-disabled-icon-color - The color of the checkbox icon when disabled. (default: var(--dds-button-primary-icon-disabled))
 * @cssproperty --dds-checkbox-readonly-border-color - The border color when the checkbox is readonly. (default: var(--dds-border-neutral-subtle))
 * @cssproperty --dds-checkbox-readonly-background-color - The background color when the checkbox is readonly. (default: var(--dds-background-neutral-subtle))
 * @cssproperty --dds-checkbox-readonly-icon-color - The color of the checkbox icon when readonly. (default: var(--dds-text-neutral-base))
 */
export default class DapDSCheckbox extends LabeledChoiceElement {
    static tagName: string;
    static dependencies: {
        'dap-ds-icon-subtract-line': typeof SystemSubtractLine;
        'dap-ds-icon-check-line2': typeof SystemCheckLine2;
        'dap-ds-form-label': typeof DapDSFormLabel;
        'dap-ds-typography': typeof DapDSTypography;
        'dap-ds-feedback': typeof DapDSFeedback;
    };
    private static nextId;
    private readonly inputId;
    private readonly labelId;
    private readonly descriptionId;
    private readonly input;
    /** Whether the checkbox is indeterminate */
    indeterminate: boolean;
    /** Whether the checkbox should prevent the default action */
    preventDefault: boolean;
    /** This sets up border around the checkbox, when true. */
    border: boolean;
    /** Whether the checkbox is readonly */
    readonly: boolean;
    /** The type of the checkbox
     * @type {'normal' | 'background'}
     */
    type: 'normal' | 'background';
    static readonly styles: import('lit').CSSResult;
    constructor();
    /**
     * Validates property combinations and logs warnings for invalid states.
     * @private
     */
    private validateProperties;
    /**
     * Gets the aria-describedby attribute value by combining description and feedback IDs.
     * @returns {string | undefined} Space-separated IDs or undefined if none exist
     * @private
     */
    private getAriaDescribedBy;
    /**
     * Gets the aria-checked attribute value based on checkbox state.
     * @returns {'true' | 'false' | 'mixed'} The appropriate aria-checked value
     * @private
     */
    private getAriaChecked;
    /**
     * Handles click events on the checkbox.
     * Manages the checked/indeterminate state transitions and emits change events.
     * @private
     */
    private handleClick;
    /**
     * Handles input events on the checkbox.
     * Emits the dds-input event with current checkbox state.
     * @private
     */
    private handleInput;
    /**
     * Handles keyboard events on the checkbox.
     * Provides enhanced keyboard navigation and accessibility.
     * @param {KeyboardEvent} event - The keyboard event
     * @private
     */
    private handleKeyDown;
    get focusElement(): HTMLInputElement;
    /**
     * Programmatically focuses the checkbox input element.
     * @public
     */
    focus(): void;
    /**
     * Programmatically blurs the checkbox input element.
     * @public
     */
    blur(): void;
    /**
     * Renders the appropriate icon based on checkbox state.
     * @returns {TemplateResult | null} The icon template or null if unchecked
     * @private
     */
    renderIcon(): import('lit-html').TemplateResult | null;
    /**
     * Handles invalid events on the checkbox input.
     * Prevents the default browser validation UI from showing and manages invalid state.
     * @param {Event} event - The invalid event
     * @private
     */
    handleInvalid(event: Event): void;
    setValidity(): void;
    render(): import('lit-html').TemplateResult;
}