@telesign/boreal-web-components 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/collection/components/forms/bds-checkbox/bds-checkbox-group/bds-checkbox-group.js

@@ -0,0 +1,648 @@
+import { Host, Mixin, h, } from "@stencil/core";
+import { CHECKBOX_GROUP_TYPES } from "./types";
+import { formAssociatedMixin } from "../../../../mixins/index";
+import { ORIENTATIONS } from "../../../../types/index";
+import { createId, validatePropValue, KEYBOARD } from "../../../../utils/index";
+const LEAF_TAG = ['BDS-CHECKBOX', 'BDS-CHECKBOX-BUTTON', 'BDS-CHECKBOX-CARD'];
+/**
+ * Checkbox group component that orchestrates multi-selection across a set of `bds-checkbox`, `bds-checkbox-button`, `bds-checkbox-card` children.
+ *
+ * @slot - Default slot for `bds-checkbox`, `bds-checkbox-button`, `bds-checkbox-card` child elements.
+ */
+export class BdsCheckboxGroup extends Mixin(formAssociatedMixin) {
+    constructor() {
+        this._id = createId('bds-checkbox-group');
+        /** Internal mirror of the `disabled` prop, kept in sync via `@Watch` and `formDisabledCallback`. */
+        this.isDisabled = false;
+        /** Set to true when native form validation fires the `invalid` event; cleared on reset or when value becomes valid. */
+        this.isInvalid = false;
+        /** Disables all child checkboxes and prevents selection. Also mirrored to isDisabled @State for form-level disable support. */
+        this.disabled = false;
+        /** Shows error styling on the group helper text. Propagated to all child checkboxes. */
+        this.error = false;
+        /** Error message rendered below the checkbox options when error is true. Replaces helperText. */
+        this.errorMessage = '';
+        /** Helper text rendered below the checkbox options. Shown in default state; replaced by errorMessage in error state. */
+        this.helperText = '';
+        /** Tooltip text shown on the group label info icon. */
+        this.info = '';
+        /** Group label rendered above the checkbox options. */
+        this.label = '';
+        /** Layout direction of the checkbox options. */
+        this.orientation = 'horizontal';
+        /** Marks the group as required for form submission. Triggers validity error when no checkboxes are selected. */
+        this.required = false;
+        /** Identifies this group variant. 'checkbox' renders bds-checkbox children; 'checkboxbutton' renders bds-checkbox-button segmented control; 'checkboxcard' renders bds-checkbox-card element. */
+        this.type = 'checkbox';
+        /** Currently selected checkbox values. Synced to children on change. */
+        this.value = [];
+        /** Hides the divider between checkbox buttons when type is 'checkboxbutton'. */
+        this.joined = false;
+        this.handleKeyDown = (event) => {
+            const target = event.target;
+            if (!LEAF_TAG.includes(target.tagName))
+                return;
+            switch (event.key) {
+                case KEYBOARD.ArrowDown:
+                case KEYBOARD.ArrowRight:
+                    this.navigateTo(target, true);
+                    event.preventDefault();
+                    break;
+                case KEYBOARD.ArrowUp:
+                case KEYBOARD.ArrowLeft:
+                    this.navigateTo(target, false);
+                    event.preventDefault();
+                    break;
+            }
+        };
+        super();
+    }
+    onJoinedChange() {
+        this.insertDividers();
+    }
+    checkPropValues() {
+        validatePropValue(Object.values(ORIENTATIONS), ORIENTATIONS.VERTICAL, this.el, 'orientation');
+        validatePropValue(Object.values(CHECKBOX_GROUP_TYPES), CHECKBOX_GROUP_TYPES.CHECKBOX, this.el, 'type');
+        this.insertDividers();
+    }
+    onDisabledChange(next) {
+        this.isDisabled = next;
+        this.propagatePropertyToCheckboxes('disabled', next);
+    }
+    onErrorChange(val) {
+        this.propagatePropertyToCheckboxes('error', val);
+    }
+    onValuesChange(vals) {
+        this.syncCheckboxStates(vals);
+    }
+    componentWillLoad() {
+        this.checkPropValues();
+        this.isDisabled = this.disabled;
+        if (this.value.length !== 0)
+            return;
+        const selector = LEAF_TAG.map(tag => `${tag}[checked]`).join(',');
+        const el = this.el;
+        const checkedElements = Array.from(el.querySelectorAll(selector));
+        if (checkedElements.length > 0)
+            this.value = checkedElements.map((el) => el.getAttribute('value') ?? '').filter(v => v !== '');
+    }
+    componentDidLoad() {
+        this.onValuesChange(this.value);
+        this.onErrorChange(this.isError);
+        this.syncFormValue();
+        this.updateLayoutCount();
+    }
+    formAssociatedCallback() {
+        this.syncFormValue();
+    }
+    formResetCallback() {
+        this.value = [];
+        this.isInvalid = false;
+        this.checkboxElements.forEach((checkbox) => {
+            checkbox.checked = false;
+            checkbox.error = this.isError;
+        });
+        this.internals.setFormValue(null);
+        this.updateFormValidity();
+    }
+    formStateRestoreCallback(state, _mode) {
+        const vals = Array.isArray(state) ? state : [];
+        this.value = vals.filter(v => typeof v === 'string');
+        this.updateFormValue();
+    }
+    formDisabledCallback(disabled) {
+        this.isDisabled = disabled;
+        this.propagatePropertyToCheckboxes('disabled', disabled);
+    }
+    handleCheckboxChange(event) {
+        const target = event.target;
+        if (!LEAF_TAG.includes(target.tagName))
+            return;
+        event.stopPropagation();
+        const checkbox = target;
+        const value = checkbox.value;
+        this.updateCheckboxSelection(value, checkbox.checked);
+        this.syncFormValue();
+        this.bdsChange.emit({ value: this.value });
+        this.valueChange.emit(this.value);
+    }
+    handleInvalid(event) {
+        this.isInvalid = true;
+        if (this.errorMessage !== '')
+            event.preventDefault();
+    }
+    handleValueChange(event) {
+        const target = event.target;
+        if (!LEAF_TAG.includes(target.tagName))
+            return;
+        event.stopPropagation();
+    }
+    /** Returns whether the group's current value satisfies the browser's built-in constraint validation. */
+    async checkValidity() {
+        return this.internals.checkValidity();
+    }
+    /** Reports the group's validity state to the user, showing native validation UI if invalid. */
+    async reportValidity() {
+        return this.internals.reportValidity();
+    }
+    insertDividers() {
+        this.el.querySelectorAll('bds-divider[data-injected]').forEach(d => d.remove());
+        if (this.type !== CHECKBOX_GROUP_TYPES.CHECKBOX_BUTTON || this.joined)
+            return;
+        const dividerOrientation = this.orientation === ORIENTATIONS.HORIZONTAL ? ORIENTATIONS.VERTICAL : ORIENTATIONS.HORIZONTAL;
+        const buttons = this.checkboxElements.filter((el) => el.tagName === 'BDS-CHECKBOX-BUTTON');
+        buttons.forEach((btn, i) => {
+            if (i === 0)
+                return;
+            const divider = document.createElement('bds-divider');
+            divider.setAttribute('orientation', dividerOrientation);
+            divider.setAttribute('data-injected', '');
+            btn.parentNode?.insertBefore(divider, btn);
+        });
+    }
+    navigateTo(current, forward) {
+        const elements = this.checkboxElements.filter(el => !el.disabled);
+        if (elements.length === 0)
+            return;
+        const idx = elements.indexOf(current);
+        const newIndex = (elements.length + idx + (forward ? 1 : -1)) % elements.length;
+        const next = elements[newIndex];
+        next.focus();
+    }
+    updateCheckboxSelection(value, isChecked) {
+        if (!isChecked) {
+            this.value = this.value.filter(v => v !== value);
+            return;
+        }
+        if (!this.value.includes(value))
+            this.value = [...this.value, value];
+    }
+    syncCheckboxStates(vals) {
+        this.checkboxElements.forEach((el) => {
+            const isChecked = vals.includes(el.value);
+            el.checked = isChecked;
+        });
+    }
+    get checkboxElements() {
+        const selector = LEAF_TAG.map(tag => tag).join(',');
+        const el = this.el;
+        return Array.from(el.querySelectorAll(selector));
+    }
+    propagatePropertyToCheckboxes(property, value) {
+        this.checkboxElements.forEach(el => {
+            el[property] = value;
+        });
+    }
+    updateFormValue() {
+        if (this.value.length === 0)
+            this.internals.setFormValue(null);
+        else {
+            const formData = new FormData();
+            this.value.forEach(val => {
+                formData.append(this.name, val);
+            });
+            this.internals.setFormValue(formData);
+        }
+    }
+    syncFormValue() {
+        this.updateFormValue();
+        this.updateFormValidity();
+    }
+    updateFormValidity() {
+        if (this.required && this.value.length === 0) {
+            const anchor = this.checkboxElements.find(el => !el.disabled);
+            this.internals.setValidity({ valueMissing: true }, this.errorMessage !== '' ? this.errorMessage : 'Please select at least one option.', anchor);
+        }
+        else {
+            this.internals.setValidity({});
+            if (!this.isInvalid)
+                return;
+            this.isInvalid = false;
+            if (!this.error)
+                this.propagatePropertyToCheckboxes('error', false);
+        }
+    }
+    updateLayoutCount() {
+        const count = this.checkboxElements.length;
+        const el = this.el;
+        el.style.setProperty('--layout-count', `${count}`);
+    }
+    get isError() {
+        return this.error && !this.isDisabled;
+    }
+    get classMap() {
+        const showError = this.isError || this.isInvalid;
+        return {
+            'bds-checkbox-group': true,
+            'bds-checkbox-group--disabled': this.isDisabled,
+            'bds-checkbox-group--error': showError,
+            'bds-checkbox-group--required': this.required,
+        };
+    }
+    render() {
+        const labelId = `${this._id}-label`;
+        const helperId = `${this._id}-helper`;
+        const showError = this.isError || this.isInvalid;
+        const typographyState = this.isDisabled ? 'disabled' : showError ? 'error' : 'default';
+        const helperContent = showError && this.errorMessage !== '' ? this.errorMessage : this.helperText;
+        return (h(Host, { key: 'ae68b7136eae0493eb3191caa71bfd31c87bd5dd', class: this.classMap, role: "group", "aria-labelledby": this.label !== '' ? labelId : undefined, "aria-describedby": helperContent !== '' ? helperId : undefined, "aria-invalid": showError ? 'true' : undefined, "aria-required": this.required ? 'true' : undefined, onKeyDown: this.handleKeyDown }, this.label && (h("bds-typography", { key: '779561b620c5a18f7018fabaeaa8759de1c5a2e6', id: labelId, variant: "label", state: typographyState, required: this.required, tooltipText: this.info !== '' ? this.info : undefined }, this.label)), h("div", { key: '6a0edf16a86b9628dd52390da861c51089107b85', class: "bds-checkbox-group__options" }, h("slot", { key: 'd702a5bdfbf2b0984c6c799a2abadb5c7fb904d0', onSlotchange: () => this.updateLayoutCount() })), helperContent && (h("bds-typography", { key: '357a3fbf88e2b70696512806840a390e468b1c62', id: helperId, variant: "helper", state: typographyState }, helperContent))));
+    }
+    static get is() { return "bds-checkbox-group"; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["bds-checkbox-group.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["bds-checkbox-group.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "State",
+                            "text": "for form-level disable support."
+                        }],
+                    "text": "Disables all child checkboxes and prevents selection. Also mirrored to isDisabled"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "error": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shows error styling on the group helper text. Propagated to all child checkboxes."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "error",
+                "defaultValue": "false"
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Error message rendered below the checkbox options when error is true. Replaces helperText."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error-message",
+                "defaultValue": "''"
+            },
+            "helperText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Helper text rendered below the checkbox options. Shown in default state; replaced by errorMessage in error state."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "helper-text",
+                "defaultValue": "''"
+            },
+            "info": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Tooltip text shown on the group label info icon."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "info",
+                "defaultValue": "''"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Group label rendered above the checkbox options."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label",
+                "defaultValue": "''"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Name of the form control; submitted as the field key in FormData."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "name"
+            },
+            "orientation": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "Orientation",
+                    "resolved": "\"horizontal\" | \"vertical\"",
+                    "references": {
+                        "Orientation": {
+                            "location": "import",
+                            "path": "@/types",
+                            "id": "src/types/index.ts::Orientation",
+                            "referenceLocation": "Orientation"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Layout direction of the checkbox options."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "orientation",
+                "defaultValue": "'horizontal'"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Marks the group as required for form submission. Triggers validity error when no checkboxes are selected."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "type": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CheckboxGroupType",
+                    "resolved": "\"checkbox\" | \"checkboxbutton\" | \"checkboxcard\"",
+                    "references": {
+                        "CheckboxGroupType": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/forms/bds-checkbox/bds-checkbox-group/types/index.ts::CheckboxGroupType",
+                            "referenceLocation": "CheckboxGroupType"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Identifies this group variant. 'checkbox' renders bds-checkbox children; 'checkboxbutton' renders bds-checkbox-button segmented control; 'checkboxcard' renders bds-checkbox-card element."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "type",
+                "defaultValue": "'checkbox'"
+            },
+            "value": {
+                "type": "unknown",
+                "mutable": true,
+                "complexType": {
+                    "original": "string[]",
+                    "resolved": "string[]",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Currently selected checkbox values. Synced to children on change."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[]"
+            },
+            "joined": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "false",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Hides the divider between checkbox buttons when type is 'checkboxbutton'."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "joined",
+                "defaultValue": "false"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isDisabled": {},
+            "isInvalid": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "bdsChange",
+                "name": "bdsChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when any checkbox is toggled. Payload includes the complete updated values array."
+                },
+                "complexType": {
+                    "original": "CheckboxGroupChangeDetail",
+                    "resolved": "CheckboxGroupChangeDetail",
+                    "references": {
+                        "CheckboxGroupChangeDetail": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/forms/bds-checkbox/bds-checkbox-group/types/index.ts::CheckboxGroupChangeDetail",
+                            "referenceLocation": "CheckboxGroupChangeDetail"
+                        }
+                    }
+                }
+            }, {
+                "method": "valueChange",
+                "name": "valueChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when any checkbox is toggled. Used for v-model two-way binding in Vue."
+                },
+                "complexType": {
+                    "original": "string[]",
+                    "resolved": "string[]",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "checkValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Returns whether the group's current value satisfies the browser's built-in constraint validation.",
+                    "tags": []
+                }
+            },
+            "reportValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Reports the group's validity state to the user, showing native validation UI if invalid.",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "joined",
+                "methodName": "onJoinedChange"
+            }, {
+                "propName": "orientation",
+                "methodName": "checkPropValues"
+            }, {
+                "propName": "disabled",
+                "methodName": "onDisabledChange"
+            }, {
+                "propName": "error",
+                "methodName": "onErrorChange"
+            }, {
+                "propName": "isInvalid",
+                "methodName": "onErrorChange"
+            }, {
+                "propName": "value",
+                "methodName": "onValuesChange"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "bdsChange",
+                "method": "handleCheckboxChange",
+                "target": undefined,
+                "capture": true,
+                "passive": false
+            }, {
+                "name": "invalid",
+                "method": "handleInvalid",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "valueChange",
+                "method": "handleValueChange",
+                "target": undefined,
+                "capture": true,
+                "passive": false
+            }];
+    }
+    static get attachInternalsMemberName() { return "internals"; }
+}

package/dist/collection/components/forms/bds-checkbox/bds-checkbox-group/types/enum.js

@@ -0,0 +1,5 @@
+export const CHECKBOX_GROUP_TYPES = {
+    CHECKBOX: 'checkbox',
+    CHECKBOX_BUTTON: 'checkboxbutton',
+    CHECKBOX_CARD: 'checkboxcard',
+};

package/dist/collection/components/forms/bds-checkbox/bds-checkbox-group/types/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './enum';
+export * from './ICheckboxGroup';