Checkbox Group: API Table
class: LionCheckbox, lion-checkbox
Fields
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
choiceValue | public | string|any | The value that will be registered to the modelValue of the parent ChoiceGroup. Recommended to be a string | ChoiceInputMixin | |
modelValue | public | {value:string|any,checked:boolean} | { value: '', checked: false } | Whereas 'normal' `.modelValue`s usually store a complex/typed version of a view value, choice inputs have a slightly different approach. In order to remain their Single Source of Truth characteristic, choice inputs store both the value and 'checkedness', in the format { value: 'x', checked: true } Different from the platform, this also allows to serialize the 'non checkedness', allowing to restore form state easily and inform the server about unchecked options. | FormControlMixin |
disabled | public | boolean | false | Boolean indicating whether or not this element is disabled. | DisabledMixin |
checked | public | boolean | ChoiceInputMixin | ||
value | public | The view value. Will be delegated to `._inputNode.value` | FormatMixin | ||
formatOn | protected | string | 'change' | Event that will trigger formatting (more precise, visual update of the view, so the user sees the formatted value) Default: 'change' | FormatMixin |
formatOptions | public | ({}) | Configuration object that will be available inside the formatter function | FormatMixin | |
formattedValue | public | string|undefined | undefined | The view value is the result of the formatter function (when available). The result will be stored in the native _inputNode (usually an input[type=text]). Examples: - For a date input, this would be '20/01/1999' (dependent on locale). - For a number input, this could be '1,234.56' (a String representation of modelValue 1234.56) | FormatMixin |
serializedValue | public | string|undefined | undefined | The serialized version of the model value. This value exists for maximal compatibility with the platform API. The serialized value can be an interface in context where data binding is not supported and a serialized string needs to be set. Examples: - For a date input, this would be the iso format of a date, e.g. '1999-01-20'. - For a number input this would be the String representation of a float ('1234.56' instead of 1234.56) When no parser is available, the value is usually the same as the formattedValue (being _inputNode.value) | FormatMixin |
_isPasting | protected | boolean | false | Whether the user is pasting content. Allows Subclassers to do this in their subclass: | FormatMixin |
_isHandlingUserInput | protected | boolean | false | Flag that will be set when user interaction takes place (for instance after an 'input' event). Will be added as meta info to the `model-value-changed` event. Depending on whether a user is interacting, formatting logic will be handled differently. | FormatMixin |
_inputNode | protected | HTMLInputElement | HTMLTextAreaElement | The interactive (form) element. Can be a native element like input/textarea/select or an element with tabindex > -1 | FormControlMixin | |
selectionStart | public | number | NativeTextFieldMixin | ||
selectionEnd | public | number | NativeTextFieldMixin | ||
_focusableNode | protected | HTMLElement | The focusable element: could be an input, textarea, select, button or any other element with tabindex > -1 | LionField | |
autocomplete | public | string | undefined | undefined | Delegates this property to input/textarea/select. | NativeTextFieldMixin |
focused | public | boolean | false | Whether the focusable element within (`._focusableNode`) is focused. Reflects to attribute '[focused]' as a styling hook | FocusMixin |
focusedVisible | public | boolean | false | Whether the focusable element within (`._focusableNode`) matches ':focus-visible' Reflects to attribute '[focused-visible]' as a styling hook See: https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible | FocusMixin |
autofocus | public | boolean | false | FocusMixin | |
label | public | string | '' | The label text for the input node. When no value is defined, textContent of [slot=label] will be used | FormControlMixin |
helpText | public | string | '' | The helpt text for the input node. When no value is defined, textContent of [slot=help-text] will be used | FormControlMixin |
fieldName | public | string | Will be used in validation messages to refer to the current field | FormControlMixin | |
_labelNode | protected | Element where label will be rendered to | FormControlMixin | ||
_helpTextNode | protected | Element where help text will be rendered to | FormControlMixin | ||
_feedbackNode | protected | Element where validation feedback will be rendered to | FormControlMixin | ||
readOnly | public | boolean | false | A Boolean attribute which, if present, indicates that the user should not be able to edit the value of the input. The difference between disabled and readonly is that read-only controls can still function, whereas disabled controls generally do not function as controls until they are enabled. (From: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly) | FormControlMixin |
labelSrOnly | public | boolean | false | The label will only be visible for srceen readers when true | FormControlMixin |
_inputId | protected | string | Unique id that can be used in all light dom | FormControlMixin | |
_ariaLabelledNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-labelledby of `._inputNode` | FormControlMixin |
_ariaDescribedNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-describedby of `._inputNode` | FormControlMixin |
_repropagationRole | public | 'child'|'choice-group'|'fieldset' | 'child' | Based on the role, details of handling model-value-changed repropagation differ. | FormControlMixin |
_isRepropagationEndpoint | public | boolean | false | By default, a field with _repropagationRole 'choice-group' will act as an 'endpoint'. This means it will be considered as an individual field: for a select, individual options will not be part of the formPath. They will. Similarly, components that (a11y wise) need to be fieldsets, but 'interaction wise' (from Application Developer perspective) need to be more like fields (think of an amount-input with a currency select box next to it), can set this to true to hide private internals in the formPath. | FormControlMixin |
type | public | string | 'text' | LionInput | |
placeholder | public | string | '' | LionInput | |
name | public | string | '' | The name the element will be registered with to the .formElements collection of the parent. Also, it serves as the key of key/value pairs in modelValue/serializedValue objects | FormRegisteringMixin |
_parentFormGroup | protected | FormRegistrarHost | undefined | undefined | The registrar this FormControl registers to, Usually a descendant of FormGroup or ChoiceGroup | FormRegisteringMixin |
allowCrossRootRegistration | public | boolean | false | To encourage accessibility best practices, `form-element-register` events do not pierce through shadow roots. This forces the developer to create form groups and fieldsets that automatically allow the creation of accessible relationships in the same dom tree. Use this option if you know what you're doing. It will then be possible to nest FormControls inside shadow dom. See https://lion-web.netlify.app/fundamentals/rationales/accessibility/#shadow-roots-and-accessibility | FormRegisteringMixin |
_requestedToBeDisabled | protected | boolean | false | DisabledMixin | |
_feedbackConditionMeta | protected | Allows Subclassers to add meta info for feedbackCondition | LionField | ||
touched | public | boolean | false | True when user has focused and left(blurred) the field. | InteractionStateMixin |
dirty | public | boolean | false | True when user has changed the value of the field. | InteractionStateMixin |
prefilled | public | boolean | false | True when user has left non-empty field or input is prefilled. The name must be seen from the point of view of the input field: once the user enters the input field, the value is non-empty. | InteractionStateMixin |
filled | public | boolean | false | True when the modelValue is non-empty (see _isEmpty in FormControlMixin) | InteractionStateMixin |
_leaveEvent | protected | string | 'blur' | The event that triggers the touched state | InteractionStateMixin |
_valueChangedEvent | protected | string | 'model-value-changed' | The event that triggers the dirty state | InteractionStateMixin |
submitted | public | InteractionStateMixin | |||
operationMode | public | OperationMode | Types of input interaction of the FormControl (for instance 'enter'|'select'|'upload') | ValidateMixin | |
_allValidators | protected | Validator[] | Combination of validators provided by Application Developer and the default validators | ValidateMixin | |
hasFeedbackFor | public | ValidationType[] | [] | As soon as validation happens (after modelValue/validators/validator param change), this array is updated with the active ValidationTypes ('error'|'warning'|'success'|'info' etc.). Notice the difference with `.showsFeedbackFor`, which filters `.hasFeedbackFor` based on `.feedbackCondition()`. For styling purposes, will be reflected to [has-feedback-for="error warning"]. This can be useful for subtle visual feedback on keyup, like a red/green border around an input. | ValidateMixin |
showsFeedbackFor | public | ValidationType[] | [] | Based on outcome of feedbackCondition, this array decides what ValidationTypes should be shown in validationFeedback, based on meta data like interaction states. For styling purposes, it reflects it `[shows-feedback-for="error warning"]` | ValidateMixin |
validationStates | public | ValidationStates | {} | The outcome of a validation 'round'. Keyed by ValidationType and Validator name | ValidateMixin |
isPending | public | boolean | false | Flag indicating whether async validation is pending. Creates attribute [is-pending] as a styling hook | ValidateMixin |
validators | public | Validator[] | [] | Used by Application Developers to add Validators to a FormControl. | ValidateMixin |
defaultValidators | public | Validator[] | [] | Used by Subclassers to add default Validators to a particular FormControl. A date input for instance, always needs the isDate validator. | ValidateMixin |
_visibleMessagesAmount | protected | number | 1 | The amount of feedback messages that will visible in LionValidationFeedback | ValidateMixin |
Methods
| Name | Privacy | Description | Parameters | Return | Inherited From |
|---|---|---|---|---|---|
_choiceGraphicTemplate | protected | ChoiceInputMixin | |||
_afterTemplate | protected | ChoiceInputMixin | |||
_preventDuplicateLabelClick | protected | The native platform fires an event for both the click on the label, and also the redispatched click on the native input element. This results in two click events arriving at the host, but we only want one. This method prevents the duplicate click and ensures the correct isTrusted event with the correct event.target arrives at the host. | ev: Event | ChoiceInputMixin | |
_toggleChecked | protected | ev: Event | ChoiceInputMixin | ||
_syncNameToParentFormGroup | protected | Override this in case of extending ChoiceInputMixin and requiring to sync differently with parent form group name Right now it checks tag name match where the parent form group tagname should include the child field tagname ('checkbox' is included in 'checkbox-group') | ChoiceInputMixin | ||
_proxyInputEvent | protected | This can be called whenever the view value should be updated. Dependent on component type ("input" for <input> or "change" for <select>(mainly for IE)) a different event should be used as source for the "user-input-changed" event (which can be seen as an abstraction layer on top of other events (input, change, whatever)) | FormatMixin | ||
_onModelValueChanged | protected | Responds to modelValue changes in the synchronous cycle (most subclassers should listen to the asynchronous cycle ('modelValue' in the .updated lifecycle)) | { modelValue }, old: { modelValue:unknown }, newV: { modelValue:unknown } | FormatMixin | |
parser | public | Converts viewValue to modelValue For instance, a localized date to a Date Object | v: string, opts: FormatOptions | * | FormatMixin |
formatter | public | Converts modelValue to formattedValue (formattedValue will be synced with `._inputNode.value`) For instance, a Date object to a localized date. | modelValue: ChoiceInputModelValue | string | FormatMixin |
clear | public | Clears modelValue. Interaction states are not cleared (use resetInteractionState for this) | LionField | ||
_isEmpty | protected | Used for required validator. | modelValue: any | boolean | FormControlMixin |
_syncValueUpwards | protected | Synchronization from `._inputNode.value` to `LionField` (flow [2]) Downwards syncing should only happen for `LionField`.value changes from 'above'. This triggers _onModelValueChanged and connects user input to the parsing/formatting/serializing loop. | FormatMixin | ||
preprocessor | public | Preprocessors could be considered 'live formatters'. Their result is shown to the user on keyup instead of after blurring the field. The biggest difference between preprocessors and formatters is their moment of execution: preprocessors are run before modelValue is computed (and work based on view value), whereas formatters are run after the parser (and are based on modelValue) Automatically formats code while typing. It depends on a preprocessro that smartly updates the viewValue and caret position for best UX. | v: string, opts: FormatOptions & { prevViewValue: string; currentCaretIndex: number } | { viewValue:string; caretIndex:number; }|string|undefined | FormatMixin |
serializer | public | Converts `.modelValue` to `.serializedValue` For instance, a Date object to an iso formatted date string | v: ? | string | FormatMixin |
deserializer | public | Converts `.serializedValue` to `.modelValue` For instance, an iso formatted date string to a Date object | v: ? | ? | FormatMixin |
_calculateValues | protected | Responsible for storing all representations(modelValue, serializedValue, formattedValue and value) of the input value. Prevents infinite loops, so all value observers can be treated like they will only be called once, without indirectly calling other observers. (in fact, some are called twice, but the __preventRecursiveTrigger lock prevents the second call from having effect). | { source }, config: {source:'model'|'serialized'|'formatted'|null} | FormatMixin | |
_dispatchModelValueChangedEvent | protected | This is wrapped in a distinct method, so that parents can control when the changed event is fired. For objects, a deep comparison might be needed. | args: { modelValue: unknown; }[] | FormatMixin | |
_reflectBackFormattedValueToUser | protected | Synchronization from `LionField.value` to `._inputNode.value` - flow [1] will always be reflected back - flow [2] will not be reflected back when this flow was triggered via `@user-input-changed` (this will happen later, when `formatOn` condition is met) | FormatMixin | ||
_reflectBackOn | protected | Every time .formattedValue is attempted to sync to the view value (on change/blur and on modelValue change), this condition is checked. When enhancing it, it's recommended to call via `return this._myExtraCondition && super._reflectBackOn()` | boolean | FormatMixin | |
_onUserInputChanged | protected | FormatMixin | |||
__onCompositionEvent | protected | { type }, event: Event | FormatMixin | ||
_setValueAndPreserveCaret | protected | Restores the cursor to its original position after updating the value. | newValue: string | NativeTextFieldMixin | |
focus | public | Calls `focus()` on focusable element within | FocusMixin | ||
blur | public | Calls `blur()` on focusable element within | FocusMixin | ||
_triggerInitialModelValueChangedEvent | protected | FormControlMixin | |||
_enhanceLightDomClasses | protected | FormControlMixin | |||
_enhanceLightDomA11y | protected | FormControlMixin | |||
_enhanceLightDomA11yForAdditionalSlots | protected | Enhances additional slots(prefix, suffix, before, after) defined by developer. When boolean attribute data-label or data-description is found, the slot element will be connected to the input via aria-labelledby or aria-describedby | additionalSlots: string[] | FormControlMixin | |
__reflectAriaAttr | protected | Will handle help text, validation feedback and character counter, prefix/suffix/before/after (if they contain data-description flag attr). Also, contents of id references that will be put in the <lion-field>._ariaDescribedby property from an external context, will be read by a screen reader. | attrName: string, nodes: Element[], reorder: boolean|undefined | FormControlMixin | |
_groupOneTemplate | protected | TemplateResult | FormControlMixin | ||
_groupTwoTemplate | protected | TemplateResult | FormControlMixin | ||
_labelTemplate | protected | TemplateResult | FormControlMixin | ||
_helpTextTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupBeforeTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupPrefixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupInputTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupSuffixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupAfterTemplate | protected | TemplateResult | FormControlMixin | ||
_feedbackTemplate | protected | TemplateResult | FormControlMixin | ||
_getAriaDescriptionElements | protected | This function exposes descripion elements that a FormGroup should expose to its children. See FormGroupMixin.__getAllDescriptionElementsInParentChain() | Array.<HTMLElement> | FormControlMixin | |
addToAriaLabelledBy | public | Allows to add extra element references to aria-labelledby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaLabelledBy | public | Allows to remove element references from aria-labelledby attribute. | element: HTMLElement | FormControlMixin | |
addToAriaDescribedBy | public | Allows to add element references to aria-describedby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaDescribedBy | public | Allows to remove element references from aria-describedby attribute. | element: HTMLElement | FormControlMixin | |
__getDirectSlotChild | protected | slotName: string | HTMLElement | undefined | FormControlMixin | |
_dispatchInitialModelValueChangedEvent | protected | FormControlMixin | |||
_onBeforeRepropagateChildrenValues | protected | Hook for Subclassers to add logic before repropagation | ev: CustomEvent | FormControlMixin | |
__repropagateChildrenValues | protected | ev: CustomEvent | FormControlMixin | ||
_repropagationCondition | protected | Based on provided target, this condition determines whether received model-value-changed event should be repropagated | target: FormControlHost | FormControlMixin | |
_onLabelClick | protected | FormControlMixin | |||
makeRequestToBeDisabled | public | DisabledMixin | |||
retractRequestToBeDisabled | public | DisabledMixin | |||
initInteractionState | public | Evaluations performed on connectedCallback. This method is public, so it can be called at a later moment (when we need to wait for registering children for instance) as well. Since this method will be called twice in last mentioned scenario, it must stay idempotent. | InteractionStateMixin | ||
_iStateOnLeave | protected | Sets touched value to true and reevaluates prefilled state. When false, on next interaction, user will start with a clean state. | InteractionStateMixin | ||
_iStateOnValueChange | protected | Sets dirty value and validates when already touched or invalid | InteractionStateMixin | ||
resetInteractionState | public | Resets touched and dirty, and recomputes prefilled | LionField | ||
_onTouchedChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
_onDirtyChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
_showFeedbackConditionFor | protected | Default feedbackCondition condition, used by Subclassers, that will be used when `feedbackCondition()` is not overridden by Application Developer. Show the validity feedback when returning true, don't show when false | type: string, meta: InteractionStates | ValidateMixin | |
validate | public | Triggered by: - modelValue change - change in the 'validators' array - change in the config of an individual Validator Three situations are handled: - a1) the FormControl is empty: further execution is halted. When the Required Validator (being mutually exclusive to the other Validators) is applied, it will end up in the validation result (as the only Validator, since further execution was halted). - a2) there are synchronous Validators: this is the most common flow. When modelValue hasn't changed since last async results were generated, 'sync results' are merged with the 'async results'. - a3) there are asynchronous Validators: for instance when server side evaluation is needed. Executions are scheduled and awaited and the 'async results' are merged with the 'sync results'. - b) there are MetaValidators. After steps a1, a2, or a3 are finished, the holistic MetaValidators (evaluating the total result of the 'regular' (a1, a2 and a3) validators) will be run... Situations a2 and a3 are not mutually exclusive and can be triggered within one `validate()` call. Situation b will occur after every call. | { clearCurrentResult = false }, opts: { clearCurrentResult?: boolean } | ValidateMixin | |
__executeValidators | protected | ValidateMixin | |||
_onValidatorUpdated | protected | e: Event|CustomEvent | ValidateMixin | ||
_updateFeedbackComponent | protected | Responsible for retrieving messages from Validators and (delegation of) rendering them. For `._feedbackNode` (extension of LionValidationFeedback): - retrieve messages from highest prio Validators - provide the result to custom feedback node and let the custom node decide on their renderings In both cases: - we compute the 'show' flag (like 'hasErrorVisible') for all types - we set the customValidity message of the highest prio Validator - we set aria-invalid="true" in case hasErrorVisible is true | ValidateMixin | ||
feedbackCondition | public | Allows the Application Developer to specify when a feedback message should be shown | type: string, meta: object, currentCondition: ((type: string, meta: object) => boolean) | boolean | ValidateMixin |
_hasFeedbackVisibleFor | protected | Used to translate `.hasFeedbackFor` and `.shouldShowFeedbackFor` to `.showsFeedbackFor` | type: string | ValidateMixin | |
_updateShouldShowFeedbackFor | protected | ValidateMixin | |||
_prioritizeAndFilterFeedback | protected | Orders all active validators in this.__validationResult. Can also filter out occurrences (based on interaction states) | { validationResult }, opts: { validationResult: Validator[] } | Validator[] | ValidateMixin |
reset | public | Resets modelValue to initial value. Interaction states are cleared | LionField | ||
_onChange | protected | Dispatches custom bubble event | ev: Event= | LionField |
Events
| Name | Type | Description | Inherited From |
|---|---|---|---|
model-value-changed | CustomEvent | FormControlMixin | |
user-input-changed | Event | LionField | |
focus | Event | FocusMixin | |
blur | Event | FocusMixin | |
focusin | Event | FocusMixin | |
focusout | Event | FocusMixin | |
form-element-name-changed | CustomEvent | FormControlMixin | |
form-element-register | CustomEvent | FormRegisteringMixin | |
touched-changed | Event | InteractionStateMixin | |
dirty-changed | Event | InteractionStateMixin | |
showsFeedbackForChanged | Event | ValidateMixin | |
Event | ValidateMixin | ||
shouldShowFeedbackForChanged | Event | ValidateMixin | |
validate-performed | Event | private event that should be listened to by LionFieldSet | ValidateMixin |
Attributes
| Name | Field | Inherited From |
|---|---|---|
checked | checked | ChoiceInputMixin |
disabled | disabled | DisabledMixin |
modelValue | modelValue | ChoiceInputMixin |
choiceValue | choiceValue | ChoiceInputMixin |
autocomplete | autocomplete | NativeTextFieldMixin |
focused | focused | FocusMixin |
focused-visible | focusedVisible | FocusMixin |
autofocus | autofocus | FocusMixin |
readonly | readOnly | FormControlMixin |
label | label | FormControlMixin |
label-sr-only | labelSrOnly | FormControlMixin |
help-text | helpText | FormControlMixin |
type | type | LionInput |
placeholder | placeholder | LionInput |
name | name | FormRegisteringMixin |
allow-cross-root-registration | allowCrossRootRegistration | FormRegisteringMixin |
touched | touched | InteractionStateMixin |
dirty | dirty | InteractionStateMixin |
filled | filled | InteractionStateMixin |
shows-feedback-for | showsFeedbackFor | ValidateMixin |
is-pending | isPending | ValidateMixin |
class: LionCheckboxGroup, lion-checkbox-group
Fields
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
multipleChoice | public | boolean | true | When false (default), modelValue and serializedValue will reflect the currently selected choice (usually a string). When true, modelValue will and serializedValue will be an array of strings. | ChoiceGroupMixin |
modelValue | public | Object keyed by formElements names, containing formElements' modelValues | FormControlMixin | ||
serializedValue | public | Object keyed by formElements names, containing formElements' serializedValues | FormGroupMixin | ||
formattedValue | public | Object keyed by formElements names, containing formElements' formattedValues | FormGroupMixin | ||
operationMode | public | OperationMode | Types of input interaction of the FormControl (for instance 'enter'|'select'|'upload') | ValidateMixin | |
_repropagationRole | public | 'child'|'choice-group'|'fieldset' | 'choice-group' | Based on the role, details of handling model-value-changed repropagation differ. | FormControlMixin |
formElements | public | FormControlsCollection | new FormControlsCollection() | Closely mimics the natively supported HTMLFormControlsCollection. It can be accessed both like an array and an object (based on control/element names). | FormRegistrarMixin |
_isFormOrFieldset | protected | boolean | false | Flag that determines how ".formElements" should behave. For a regular fieldset (see LionFieldset) we expect ".formElements" to be accessible as an object. In case of a radio-group, a checkbox-group or a select/listbox, it should act like an array (see ChoiceGroupMixin). Usually, when false, we deal with a choice-group (radio-group, checkbox-group, (multi)select) | FormRegistrarMixin |
initComplete | public | Promise<any> | new Promise((resolve, reject) => { this.__resolveInitComplete = resolve; this.__rejectInitComplete = reject; }) | initComplete resolves after all pending initialization logic (for instance `<form-group .serializedValue=$>`) is executed | FormRegistrarMixin |
registrationComplete | public | Promise<any> & {done?:boolean} | new Promise((resolve, reject) => { this.__resolveRegistrationComplete = resolve; this.__rejectRegistrationComplete = reject; }) | registrationComplete waits for all children formElements to have registered | FormRegistrarMixin |
done | public | boolean | false | FormRegistrarMixin | |
_allValidators | protected | Validator[] | Combination of validators provided by Application Developer and the default validators | ValidateMixin | |
_feedbackConditionMeta | protected | Allows Subclassers to add meta info for feedbackCondition | ValidateMixin | ||
hasFeedbackFor | public | ValidationType[] | [] | As soon as validation happens (after modelValue/validators/validator param change), this array is updated with the active ValidationTypes ('error'|'warning'|'success'|'info' etc.). Notice the difference with `.showsFeedbackFor`, which filters `.hasFeedbackFor` based on `.feedbackCondition()`. For styling purposes, will be reflected to [has-feedback-for="error warning"]. This can be useful for subtle visual feedback on keyup, like a red/green border around an input. | ValidateMixin |
showsFeedbackFor | public | ValidationType[] | [] | Based on outcome of feedbackCondition, this array decides what ValidationTypes should be shown in validationFeedback, based on meta data like interaction states. For styling purposes, it reflects it `[shows-feedback-for="error warning"]` | ValidateMixin |
validationStates | public | ValidationStates | {} | The outcome of a validation 'round'. Keyed by ValidationType and Validator name | ValidateMixin |
isPending | public | boolean | false | Flag indicating whether async validation is pending. Creates attribute [is-pending] as a styling hook | ValidateMixin |
validators | public | Validator[] | [] | Used by Application Developers to add Validators to a FormControl. | ValidateMixin |
defaultValidators | public | Validator[] | [] | Used by Subclassers to add default Validators to a particular FormControl. A date input for instance, always needs the isDate validator. | ValidateMixin |
_visibleMessagesAmount | protected | number | 1 | The amount of feedback messages that will visible in LionValidationFeedback | ValidateMixin |
touched | public | boolean | false | True when user has focused and left(blurred) the field. | FormGroupMixin |
dirty | public | boolean | false | True when user has changed the value of the field. | FormGroupMixin |
prefilled | public | boolean | false | True when user has left non-empty field or input is prefilled. The name must be seen from the point of view of the input field: once the user enters the input field, the value is non-empty. | FormGroupMixin |
filled | public | boolean | false | True when the modelValue is non-empty (see _isEmpty in FormControlMixin) | InteractionStateMixin |
_leaveEvent | protected | string | 'blur' | The event that triggers the touched state | InteractionStateMixin |
_valueChangedEvent | protected | string | 'model-value-changed' | The event that triggers the dirty state | InteractionStateMixin |
submitted | public | boolean | false | True when parent form is submitted | FormGroupMixin |
_inputNode | protected | The host element with role group (or radio-group or form) containing necessary aria attributes | FormControlMixin | ||
_initialModelValue | protected | Gathers initial model values of all children. Used when resetGroup() is called. | FormGroupMixin | ||
value | public | string | '' | FormGroupMixin | |
disabled | public | boolean | false | Disables all formElements in group | DisabledMixin |
focused | public | boolean | false | True when any of the children is focused. | FormGroupMixin |
__descriptionElementsInParentChain | protected | new Set() | FormGroupMixin | ||
__pendingValues | protected | {modelValue?:{[key:string]: any}, serializedValue?:{[key:string]: any}} | { modelValue: {}, serializedValue: {} } | FormGroupMixin | |
label | public | string | '' | The label text for the input node. When no value is defined, textContent of [slot=label] will be used | FormControlMixin |
helpText | public | string | '' | The helpt text for the input node. When no value is defined, textContent of [slot=help-text] will be used | FormControlMixin |
fieldName | public | string | Will be used in validation messages to refer to the current field | FormControlMixin | |
_labelNode | protected | Element where label will be rendered to | FormControlMixin | ||
_helpTextNode | protected | Element where help text will be rendered to | FormControlMixin | ||
_feedbackNode | protected | Element where validation feedback will be rendered to | FormControlMixin | ||
readOnly | public | boolean | false | A Boolean attribute which, if present, indicates that the user should not be able to edit the value of the input. The difference between disabled and readonly is that read-only controls can still function, whereas disabled controls generally do not function as controls until they are enabled. (From: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly) | FormControlMixin |
labelSrOnly | public | boolean | false | The label will only be visible for srceen readers when true | FormControlMixin |
_inputId | protected | string | Unique id that can be used in all light dom | FormControlMixin | |
_ariaLabelledNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-labelledby of `._inputNode` | FormControlMixin |
_ariaDescribedNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-describedby of `._inputNode` | FormControlMixin |
_isRepropagationEndpoint | public | boolean | false | By default, a field with _repropagationRole 'choice-group' will act as an 'endpoint'. This means it will be considered as an individual field: for a select, individual options will not be part of the formPath. They will. Similarly, components that (a11y wise) need to be fieldsets, but 'interaction wise' (from Application Developer perspective) need to be more like fields (think of an amount-input with a currency select box next to it), can set this to true to hide private internals in the formPath. | FormControlMixin |
_requestedToBeDisabled | protected | boolean | false | DisabledMixin |
Methods
| Name | Privacy | Description | Parameters | Return | Inherited From |
|---|---|---|---|---|---|
_completeRegistration | protected | Resolves the registrationComplete promise. Subclassers can delay if needed | FormRegistrarMixin | ||
addFormElement | public | child: FormControl, indexToInsertAt: number | FormRegistrarMixin | ||
clear | public | ChoiceGroupMixin | |||
_triggerInitialModelValueChangedEvent | protected | FormControlMixin | |||
_getFromAllFormElementsFilter | protected | A filter function which will exclude a form field when returning false By default, exclude form fields which are disabled The type is be passed as well for more fine grained control, e.g. distinguish the filter when fetching modelValue versus serializedValue | el: FormControl, type: string | boolean | FormGroupMixin |
_getFromAllFormElements | protected | Implicit :( | property: string, filterFn: (el: FormControl, property?: string) => boolean | {[name:string]: any} | FormGroupMixin |
_throwWhenInvalidChildModelValue | protected | child: FormControl | ChoiceGroupMixin | ||
_isEmpty | protected | Used for Required validation and computation of interaction states | modelValue: any | boolean | FormControlMixin |
_checkSingleChoiceElements | protected | ev: CustomEvent & {target:FormControl} | ChoiceGroupMixin | ||
_getCheckedElements | protected | ChoiceGroupMixin | |||
_setCheckedElements | protected | value: string | any[], check: Function | ChoiceGroupMixin | ||
_onBeforeRepropagateChildrenValues | protected | Hook for Subclassers to add logic before repropagation | ev: CustomEvent | FormControlMixin | |
_repropagationCondition | protected | Based on provided target, this condition determines whether received model-value-changed event should be repropagated | target: FormControlHost & ChoiceInputHost | FormControlMixin | |
isRegisteredFormElement | public | el: ElementWithParentFormGroup | FormRegistrarMixin | ||
removeFormElement | public | child: FormControlHost | FormRegistrarMixin | ||
_onRequestToAddFormElement | protected | Hook for Subclassers to perform logic before an element is added | ev: CustomEvent | FormRegistrarMixin | |
_onRequestToChangeFormElementName | protected | ev: CustomEvent | FormRegistrarMixin | ||
_onRequestToRemoveFormElement | protected | ev: CustomEvent | FormRegistrarMixin | ||
updateSync | public | name: string, oldValue: ? | ValidateMixin | ||
validate | public | Triggered by: - modelValue change - change in the 'validators' array - change in the config of an individual Validator Three situations are handled: - a1) the FormControl is empty: further execution is halted. When the Required Validator (being mutually exclusive to the other Validators) is applied, it will end up in the validation result (as the only Validator, since further execution was halted). - a2) there are synchronous Validators: this is the most common flow. When modelValue hasn't changed since last async results were generated, 'sync results' are merged with the 'async results'. - a3) there are asynchronous Validators: for instance when server side evaluation is needed. Executions are scheduled and awaited and the 'async results' are merged with the 'sync results'. - b) there are MetaValidators. After steps a1, a2, or a3 are finished, the holistic MetaValidators (evaluating the total result of the 'regular' (a1, a2 and a3) validators) will be run... Situations a2 and a3 are not mutually exclusive and can be triggered within one `validate()` call. Situation b will occur after every call. | { clearCurrentResult = false }, opts: { clearCurrentResult?: boolean } | ValidateMixin | |
__executeValidators | protected | ValidateMixin | |||
_onValidatorUpdated | protected | e: Event|CustomEvent | ValidateMixin | ||
_updateFeedbackComponent | protected | Responsible for retrieving messages from Validators and (delegation of) rendering them. For `._feedbackNode` (extension of LionValidationFeedback): - retrieve messages from highest prio Validators - provide the result to custom feedback node and let the custom node decide on their renderings In both cases: - we compute the 'show' flag (like 'hasErrorVisible') for all types - we set the customValidity message of the highest prio Validator - we set aria-invalid="true" in case hasErrorVisible is true | ValidateMixin | ||
_showFeedbackConditionFor | protected | Default feedbackCondition condition, used by Subclassers, that will be used when `feedbackCondition()` is not overridden by Application Developer. Show the validity feedback when returning true, don't show when false | type: string, meta: object | ValidateMixin | |
feedbackCondition | public | Allows the Application Developer to specify when a feedback message should be shown | type: string, meta: object, currentCondition: ((type: string, meta: object) => boolean) | boolean | ValidateMixin |
_hasFeedbackVisibleFor | protected | Used to translate `.hasFeedbackFor` and `.shouldShowFeedbackFor` to `.showsFeedbackFor` | type: string | ValidateMixin | |
_updateShouldShowFeedbackFor | protected | ValidateMixin | |||
_prioritizeAndFilterFeedback | protected | Orders all active validators in this.__validationResult. Can also filter out occurrences (based on interaction states) | { validationResult }, opts: { validationResult: Validator[] } | Validator[] | ValidateMixin |
initInteractionState | public | Evaluations performed on connectedCallback. This method is public, so it can be called at a later moment (when we need to wait for registering children for instance) as well. Since this method will be called twice in last mentioned scenario, it must stay idempotent. | InteractionStateMixin | ||
_iStateOnLeave | protected | Sets touched value to true and reevaluates prefilled state. When false, on next interaction, user will start with a clean state. | InteractionStateMixin | ||
_iStateOnValueChange | protected | Sets dirty value and validates when already touched or invalid | InteractionStateMixin | ||
resetInteractionState | public | Resets touched and dirty, and recomputes prefilled | FormGroupMixin | ||
_onTouchedChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
_onDirtyChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
__initInteractionStates | protected | FormGroupMixin | |||
__setupOutsideClickHandling | protected | FormGroupMixin | |||
_checkForOutsideClick | protected | event: Event | FormGroupMixin | ||
__requestChildrenToBeDisabled | protected | FormGroupMixin | |||
__retractRequestChildrenToBeDisabled | protected | FormGroupMixin | |||
_inputGroupTemplate | protected | TemplateResult | FormControlMixin | ||
submitGroup | public | Handles interaction state 'submitted'. This allows children to enable visibility of validation feedback | FormGroupMixin | ||
resetGroup | public | Resets to initial/prefilled values and interaction states of all FormControls in group, | FormGroupMixin | ||
clearGroup | public | Clears all values and resets all interaction states of all FormControls in group, | FormGroupMixin | ||
_setValueForAllFormElements | protected | Sets the same value for requested property in all formElements | property: string | number, value: any | FormGroupMixin | |
_setValueMapForAllFormElements | protected | Allows to set formElements values via a keyed object structure | property: string, values: { [x: string]: any; } | FormGroupMixin | |
_anyFormElementHas | protected | Returns true when one of the formElements has requested | property: string | FormGroupMixin | |
_anyFormElementHasFeedbackFor | protected | state: string | FormGroupMixin | ||
_everyFormElementHas | protected | Returns true when all of the formElements have requested property | property: string | FormGroupMixin | |
__onChildValidatePerformed | protected | Gets triggered by event 'validate-performed' which enabled us to handle 2 different situations - react on modelValue change, which says something about the validity as a whole (at least two checkboxes for instance) and nothing about the children's values - children validity states have changed, so fieldset needs to update itself based on that | ev: Event | FormGroupMixin | |
_syncFocused | protected | FormGroupMixin | |||
_onFocusOut | protected | ev: Event | FormGroupMixin | ||
_syncDirty | protected | FormGroupMixin | |||
__storeAllDescriptionElementsInParentChain | protected | Traverses the _parentFormGroup tree, and gathers all aria description elements (feedback) that should be provided to children. In the example below, when the input for 'street' has focus, a screenreader user would hear the #group-error. In case one of the inputs was in error state as well, the SR user would first hear the local error, followed by #group-error | FormGroupMixin | ||
__linkParentMessages | protected | child: FormControl | FormGroupMixin | ||
__unlinkParentMessages | protected | child: FormControl | FormGroupMixin | ||
_enhanceLightDomClasses | protected | FormControlMixin | |||
_enhanceLightDomA11y | protected | FormControlMixin | |||
_enhanceLightDomA11yForAdditionalSlots | protected | Enhances additional slots(prefix, suffix, before, after) defined by developer. When boolean attribute data-label or data-description is found, the slot element will be connected to the input via aria-labelledby or aria-describedby | additionalSlots: string[] | FormControlMixin | |
__reflectAriaAttr | protected | Will handle help text, validation feedback and character counter, prefix/suffix/before/after (if they contain data-description flag attr). Also, contents of id references that will be put in the <lion-field>._ariaDescribedby property from an external context, will be read by a screen reader. | attrName: string, nodes: Element[], reorder: boolean|undefined | FormControlMixin | |
_groupOneTemplate | protected | TemplateResult | FormControlMixin | ||
_groupTwoTemplate | protected | TemplateResult | FormControlMixin | ||
_labelTemplate | protected | TemplateResult | FormControlMixin | ||
_helpTextTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupBeforeTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupPrefixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupInputTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupSuffixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupAfterTemplate | protected | TemplateResult | FormControlMixin | ||
_feedbackTemplate | protected | TemplateResult | FormControlMixin | ||
_getAriaDescriptionElements | protected | This function exposes descripion elements that a FormGroup should expose to its children. See FormGroupMixin.__getAllDescriptionElementsInParentChain() | Array.<HTMLElement> | FormControlMixin | |
addToAriaLabelledBy | public | Allows to add extra element references to aria-labelledby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaLabelledBy | public | Allows to remove element references from aria-labelledby attribute. | element: HTMLElement | FormControlMixin | |
addToAriaDescribedBy | public | Allows to add element references to aria-describedby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaDescribedBy | public | Allows to remove element references from aria-describedby attribute. | element: HTMLElement | FormControlMixin | |
__getDirectSlotChild | protected | slotName: string | HTMLElement | undefined | FormControlMixin | |
_dispatchInitialModelValueChangedEvent | protected | FormControlMixin | |||
__repropagateChildrenValues | protected | ev: CustomEvent | FormControlMixin | ||
_onLabelClick | protected | FormControlMixin | |||
makeRequestToBeDisabled | public | DisabledMixin | |||
retractRequestToBeDisabled | public | DisabledMixin |
Events
| Name | Type | Description | Inherited From |
|---|---|---|---|
showsFeedbackForChanged | Event | ValidateMixin | |
Event | ValidateMixin | ||
shouldShowFeedbackForChanged | Event | ValidateMixin | |
validate-performed | Event | private event that should be listened to by LionFieldSet | ValidateMixin |
touched-changed | Event | InteractionStateMixin | |
dirty-changed | Event | InteractionStateMixin | |
form-element-name-changed | CustomEvent | FormControlMixin | |
model-value-changed | CustomEvent | FormControlMixin |
Attributes
| Name | Field | Inherited From |
|---|---|---|
multiple-choice | multipleChoice | ChoiceGroupMixin |
_isFormOrFieldset | _isFormOrFieldset | FormRegistrarMixin |
shows-feedback-for | showsFeedbackFor | ValidateMixin |
is-pending | isPending | ValidateMixin |
touched | touched | FormGroupMixin |
dirty | dirty | FormGroupMixin |
filled | filled | InteractionStateMixin |
submitted | submitted | FormGroupMixin |
focused | focused | FormGroupMixin |
prefilled | prefilled | FormGroupMixin |
readonly | readOnly | FormControlMixin |
label | label | FormControlMixin |
label-sr-only | labelSrOnly | FormControlMixin |
help-text | helpText | FormControlMixin |
disabled | disabled | DisabledMixin |
class: LionCheckboxIndeterminate, lion-checkbox-indeterminate
Fields
| Name | Privacy | Type | Default | Description | Inherited From |
|---|---|---|---|---|---|
_checkboxGroupNode | protected | ||||
_subCheckboxes | protected | ||||
indeterminate | public | boolean | false | Indeterminate state of the checkbox | |
_indeterminateSubStates | protected | boolean[] | [] | ||
mixedState | public | boolean | false | ||
choiceValue | public | string|any | The value that will be registered to the modelValue of the parent ChoiceGroup. Recommended to be a string | ChoiceInputMixin | |
modelValue | public | {value:string|any,checked:boolean} | { value: '', checked: false } | Whereas 'normal' `.modelValue`s usually store a complex/typed version of a view value, choice inputs have a slightly different approach. In order to remain their Single Source of Truth characteristic, choice inputs store both the value and 'checkedness', in the format { value: 'x', checked: true } Different from the platform, this also allows to serialize the 'non checkedness', allowing to restore form state easily and inform the server about unchecked options. | FormControlMixin |
disabled | public | boolean | false | Boolean indicating whether or not this element is disabled. | DisabledMixin |
checked | public | boolean | ChoiceInputMixin | ||
value | public | The view value. Will be delegated to `._inputNode.value` | FormatMixin | ||
formatOn | protected | string | 'change' | Event that will trigger formatting (more precise, visual update of the view, so the user sees the formatted value) Default: 'change' | FormatMixin |
formatOptions | public | ({}) | Configuration object that will be available inside the formatter function | FormatMixin | |
formattedValue | public | string|undefined | undefined | The view value is the result of the formatter function (when available). The result will be stored in the native _inputNode (usually an input[type=text]). Examples: - For a date input, this would be '20/01/1999' (dependent on locale). - For a number input, this could be '1,234.56' (a String representation of modelValue 1234.56) | FormatMixin |
serializedValue | public | string|undefined | undefined | The serialized version of the model value. This value exists for maximal compatibility with the platform API. The serialized value can be an interface in context where data binding is not supported and a serialized string needs to be set. Examples: - For a date input, this would be the iso format of a date, e.g. '1999-01-20'. - For a number input this would be the String representation of a float ('1234.56' instead of 1234.56) When no parser is available, the value is usually the same as the formattedValue (being _inputNode.value) | FormatMixin |
_isPasting | protected | boolean | false | Whether the user is pasting content. Allows Subclassers to do this in their subclass: | FormatMixin |
_isHandlingUserInput | protected | boolean | false | Flag that will be set when user interaction takes place (for instance after an 'input' event). Will be added as meta info to the `model-value-changed` event. Depending on whether a user is interacting, formatting logic will be handled differently. | FormatMixin |
_inputNode | protected | HTMLInputElement | HTMLTextAreaElement | The interactive (form) element. Can be a native element like input/textarea/select or an element with tabindex > -1 | FormControlMixin | |
selectionStart | public | number | NativeTextFieldMixin | ||
selectionEnd | public | number | NativeTextFieldMixin | ||
_focusableNode | protected | HTMLElement | The focusable element: could be an input, textarea, select, button or any other element with tabindex > -1 | LionField | |
autocomplete | public | string | undefined | undefined | Delegates this property to input/textarea/select. | NativeTextFieldMixin |
focused | public | boolean | false | Whether the focusable element within (`._focusableNode`) is focused. Reflects to attribute '[focused]' as a styling hook | FocusMixin |
focusedVisible | public | boolean | false | Whether the focusable element within (`._focusableNode`) matches ':focus-visible' Reflects to attribute '[focused-visible]' as a styling hook See: https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible | FocusMixin |
autofocus | public | boolean | false | FocusMixin | |
label | public | string | '' | The label text for the input node. When no value is defined, textContent of [slot=label] will be used | FormControlMixin |
helpText | public | string | '' | The helpt text for the input node. When no value is defined, textContent of [slot=help-text] will be used | FormControlMixin |
fieldName | public | string | Will be used in validation messages to refer to the current field | FormControlMixin | |
_labelNode | protected | Element where label will be rendered to | FormControlMixin | ||
_helpTextNode | protected | Element where help text will be rendered to | FormControlMixin | ||
_feedbackNode | protected | Element where validation feedback will be rendered to | FormControlMixin | ||
readOnly | public | boolean | false | A Boolean attribute which, if present, indicates that the user should not be able to edit the value of the input. The difference between disabled and readonly is that read-only controls can still function, whereas disabled controls generally do not function as controls until they are enabled. (From: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly) | FormControlMixin |
labelSrOnly | public | boolean | false | The label will only be visible for srceen readers when true | FormControlMixin |
_inputId | protected | string | Unique id that can be used in all light dom | FormControlMixin | |
_ariaLabelledNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-labelledby of `._inputNode` | FormControlMixin |
_ariaDescribedNodes | public | HTMLElement[] | [] | Contains all elements that should end up in aria-describedby of `._inputNode` | FormControlMixin |
_repropagationRole | public | 'child'|'choice-group'|'fieldset' | 'child' | Based on the role, details of handling model-value-changed repropagation differ. | FormControlMixin |
_isRepropagationEndpoint | public | boolean | false | By default, a field with _repropagationRole 'choice-group' will act as an 'endpoint'. This means it will be considered as an individual field: for a select, individual options will not be part of the formPath. They will. Similarly, components that (a11y wise) need to be fieldsets, but 'interaction wise' (from Application Developer perspective) need to be more like fields (think of an amount-input with a currency select box next to it), can set this to true to hide private internals in the formPath. | FormControlMixin |
type | public | string | 'text' | LionInput | |
placeholder | public | string | '' | LionInput | |
name | public | string | '' | The name the element will be registered with to the .formElements collection of the parent. Also, it serves as the key of key/value pairs in modelValue/serializedValue objects | FormRegisteringMixin |
_parentFormGroup | protected | FormRegistrarHost | undefined | undefined | The registrar this FormControl registers to, Usually a descendant of FormGroup or ChoiceGroup | FormRegisteringMixin |
allowCrossRootRegistration | public | boolean | false | To encourage accessibility best practices, `form-element-register` events do not pierce through shadow roots. This forces the developer to create form groups and fieldsets that automatically allow the creation of accessible relationships in the same dom tree. Use this option if you know what you're doing. It will then be possible to nest FormControls inside shadow dom. See https://lion-web.netlify.app/fundamentals/rationales/accessibility/#shadow-roots-and-accessibility | FormRegisteringMixin |
_requestedToBeDisabled | protected | boolean | false | DisabledMixin | |
_feedbackConditionMeta | protected | Allows Subclassers to add meta info for feedbackCondition | LionField | ||
touched | public | boolean | false | True when user has focused and left(blurred) the field. | InteractionStateMixin |
dirty | public | boolean | false | True when user has changed the value of the field. | InteractionStateMixin |
prefilled | public | boolean | false | True when user has left non-empty field or input is prefilled. The name must be seen from the point of view of the input field: once the user enters the input field, the value is non-empty. | InteractionStateMixin |
filled | public | boolean | false | True when the modelValue is non-empty (see _isEmpty in FormControlMixin) | InteractionStateMixin |
_leaveEvent | protected | string | 'blur' | The event that triggers the touched state | InteractionStateMixin |
_valueChangedEvent | protected | string | 'model-value-changed' | The event that triggers the dirty state | InteractionStateMixin |
submitted | public | InteractionStateMixin | |||
operationMode | public | OperationMode | Types of input interaction of the FormControl (for instance 'enter'|'select'|'upload') | ValidateMixin | |
_allValidators | protected | Validator[] | Combination of validators provided by Application Developer and the default validators | ValidateMixin | |
hasFeedbackFor | public | ValidationType[] | [] | As soon as validation happens (after modelValue/validators/validator param change), this array is updated with the active ValidationTypes ('error'|'warning'|'success'|'info' etc.). Notice the difference with `.showsFeedbackFor`, which filters `.hasFeedbackFor` based on `.feedbackCondition()`. For styling purposes, will be reflected to [has-feedback-for="error warning"]. This can be useful for subtle visual feedback on keyup, like a red/green border around an input. | ValidateMixin |
showsFeedbackFor | public | ValidationType[] | [] | Based on outcome of feedbackCondition, this array decides what ValidationTypes should be shown in validationFeedback, based on meta data like interaction states. For styling purposes, it reflects it `[shows-feedback-for="error warning"]` | ValidateMixin |
validationStates | public | ValidationStates | {} | The outcome of a validation 'round'. Keyed by ValidationType and Validator name | ValidateMixin |
isPending | public | boolean | false | Flag indicating whether async validation is pending. Creates attribute [is-pending] as a styling hook | ValidateMixin |
validators | public | Validator[] | [] | Used by Application Developers to add Validators to a FormControl. | ValidateMixin |
defaultValidators | public | Validator[] | [] | Used by Subclassers to add default Validators to a particular FormControl. A date input for instance, always needs the isDate validator. | ValidateMixin |
_visibleMessagesAmount | protected | number | 1 | The amount of feedback messages that will visible in LionValidationFeedback | ValidateMixin |
Methods
| Name | Privacy | Description | Parameters | Return | Inherited From |
|---|---|---|---|---|---|
_storeIndeterminateState | protected | ||||
_setOldState | protected | ||||
_setOwnCheckedState | protected | ||||
_setBasedOnMixedState | protected | ||||
_afterTemplate | protected | ChoiceInputMixin | |||
_onRequestToAddFormElement | protected | ev: Event | |||
_onRequestToRemoveFormElement | protected | ev: Event | |||
_choiceGraphicTemplate | protected | ChoiceInputMixin | |||
_preventDuplicateLabelClick | protected | The native platform fires an event for both the click on the label, and also the redispatched click on the native input element. This results in two click events arriving at the host, but we only want one. This method prevents the duplicate click and ensures the correct isTrusted event with the correct event.target arrives at the host. | ev: Event | ChoiceInputMixin | |
_toggleChecked | protected | ev: Event | ChoiceInputMixin | ||
_syncNameToParentFormGroup | protected | Override this in case of extending ChoiceInputMixin and requiring to sync differently with parent form group name Right now it checks tag name match where the parent form group tagname should include the child field tagname ('checkbox' is included in 'checkbox-group') | ChoiceInputMixin | ||
_proxyInputEvent | protected | This can be called whenever the view value should be updated. Dependent on component type ("input" for <input> or "change" for <select>(mainly for IE)) a different event should be used as source for the "user-input-changed" event (which can be seen as an abstraction layer on top of other events (input, change, whatever)) | FormatMixin | ||
_onModelValueChanged | protected | Responds to modelValue changes in the synchronous cycle (most subclassers should listen to the asynchronous cycle ('modelValue' in the .updated lifecycle)) | { modelValue }, old: { modelValue:unknown }, newV: { modelValue:unknown } | FormatMixin | |
parser | public | Converts viewValue to modelValue For instance, a localized date to a Date Object | v: string, opts: FormatOptions | * | FormatMixin |
formatter | public | Converts modelValue to formattedValue (formattedValue will be synced with `._inputNode.value`) For instance, a Date object to a localized date. | modelValue: ChoiceInputModelValue | string | FormatMixin |
clear | public | Clears modelValue. Interaction states are not cleared (use resetInteractionState for this) | LionField | ||
_isEmpty | protected | Used for required validator. | modelValue: any | boolean | FormControlMixin |
_syncValueUpwards | protected | Synchronization from `._inputNode.value` to `LionField` (flow [2]) Downwards syncing should only happen for `LionField`.value changes from 'above'. This triggers _onModelValueChanged and connects user input to the parsing/formatting/serializing loop. | FormatMixin | ||
preprocessor | public | Preprocessors could be considered 'live formatters'. Their result is shown to the user on keyup instead of after blurring the field. The biggest difference between preprocessors and formatters is their moment of execution: preprocessors are run before modelValue is computed (and work based on view value), whereas formatters are run after the parser (and are based on modelValue) Automatically formats code while typing. It depends on a preprocessro that smartly updates the viewValue and caret position for best UX. | v: string, opts: FormatOptions & { prevViewValue: string; currentCaretIndex: number } | { viewValue:string; caretIndex:number; }|string|undefined | FormatMixin |
serializer | public | Converts `.modelValue` to `.serializedValue` For instance, a Date object to an iso formatted date string | v: ? | string | FormatMixin |
deserializer | public | Converts `.serializedValue` to `.modelValue` For instance, an iso formatted date string to a Date object | v: ? | ? | FormatMixin |
_calculateValues | protected | Responsible for storing all representations(modelValue, serializedValue, formattedValue and value) of the input value. Prevents infinite loops, so all value observers can be treated like they will only be called once, without indirectly calling other observers. (in fact, some are called twice, but the __preventRecursiveTrigger lock prevents the second call from having effect). | { source }, config: {source:'model'|'serialized'|'formatted'|null} | FormatMixin | |
_dispatchModelValueChangedEvent | protected | This is wrapped in a distinct method, so that parents can control when the changed event is fired. For objects, a deep comparison might be needed. | args: { modelValue: unknown; }[] | FormatMixin | |
_reflectBackFormattedValueToUser | protected | Synchronization from `LionField.value` to `._inputNode.value` - flow [1] will always be reflected back - flow [2] will not be reflected back when this flow was triggered via `@user-input-changed` (this will happen later, when `formatOn` condition is met) | FormatMixin | ||
_reflectBackOn | protected | Every time .formattedValue is attempted to sync to the view value (on change/blur and on modelValue change), this condition is checked. When enhancing it, it's recommended to call via `return this._myExtraCondition && super._reflectBackOn()` | boolean | FormatMixin | |
_onUserInputChanged | protected | FormatMixin | |||
__onCompositionEvent | protected | { type }, event: Event | FormatMixin | ||
_setValueAndPreserveCaret | protected | Restores the cursor to its original position after updating the value. | newValue: string | NativeTextFieldMixin | |
focus | public | Calls `focus()` on focusable element within | FocusMixin | ||
blur | public | Calls `blur()` on focusable element within | FocusMixin | ||
_triggerInitialModelValueChangedEvent | protected | FormControlMixin | |||
_enhanceLightDomClasses | protected | FormControlMixin | |||
_enhanceLightDomA11y | protected | FormControlMixin | |||
_enhanceLightDomA11yForAdditionalSlots | protected | Enhances additional slots(prefix, suffix, before, after) defined by developer. When boolean attribute data-label or data-description is found, the slot element will be connected to the input via aria-labelledby or aria-describedby | additionalSlots: string[] | FormControlMixin | |
__reflectAriaAttr | protected | Will handle help text, validation feedback and character counter, prefix/suffix/before/after (if they contain data-description flag attr). Also, contents of id references that will be put in the <lion-field>._ariaDescribedby property from an external context, will be read by a screen reader. | attrName: string, nodes: Element[], reorder: boolean|undefined | FormControlMixin | |
_groupOneTemplate | protected | TemplateResult | FormControlMixin | ||
_groupTwoTemplate | protected | TemplateResult | FormControlMixin | ||
_labelTemplate | protected | TemplateResult | FormControlMixin | ||
_helpTextTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupBeforeTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupPrefixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupInputTemplate | protected | TemplateResult | FormControlMixin | ||
_inputGroupSuffixTemplate | protected | TemplateResult | nothing | FormControlMixin | ||
_inputGroupAfterTemplate | protected | TemplateResult | FormControlMixin | ||
_feedbackTemplate | protected | TemplateResult | FormControlMixin | ||
_getAriaDescriptionElements | protected | This function exposes descripion elements that a FormGroup should expose to its children. See FormGroupMixin.__getAllDescriptionElementsInParentChain() | Array.<HTMLElement> | FormControlMixin | |
addToAriaLabelledBy | public | Allows to add extra element references to aria-labelledby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaLabelledBy | public | Allows to remove element references from aria-labelledby attribute. | element: HTMLElement | FormControlMixin | |
addToAriaDescribedBy | public | Allows to add element references to aria-describedby attribute. | element: HTMLElement, { idPrefix = '', reorder = true }, customConfig: {idPrefix?:string; reorder?: boolean} | FormControlMixin | |
removeFromAriaDescribedBy | public | Allows to remove element references from aria-describedby attribute. | element: HTMLElement | FormControlMixin | |
__getDirectSlotChild | protected | slotName: string | HTMLElement | undefined | FormControlMixin | |
_dispatchInitialModelValueChangedEvent | protected | FormControlMixin | |||
_onBeforeRepropagateChildrenValues | protected | Hook for Subclassers to add logic before repropagation | ev: CustomEvent | FormControlMixin | |
__repropagateChildrenValues | protected | ev: CustomEvent | FormControlMixin | ||
_repropagationCondition | protected | Based on provided target, this condition determines whether received model-value-changed event should be repropagated | target: FormControlHost | FormControlMixin | |
_onLabelClick | protected | FormControlMixin | |||
makeRequestToBeDisabled | public | DisabledMixin | |||
retractRequestToBeDisabled | public | DisabledMixin | |||
initInteractionState | public | Evaluations performed on connectedCallback. This method is public, so it can be called at a later moment (when we need to wait for registering children for instance) as well. Since this method will be called twice in last mentioned scenario, it must stay idempotent. | InteractionStateMixin | ||
_iStateOnLeave | protected | Sets touched value to true and reevaluates prefilled state. When false, on next interaction, user will start with a clean state. | InteractionStateMixin | ||
_iStateOnValueChange | protected | Sets dirty value and validates when already touched or invalid | InteractionStateMixin | ||
resetInteractionState | public | Resets touched and dirty, and recomputes prefilled | LionField | ||
_onTouchedChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
_onDirtyChanged | protected | Dispatches event on touched state change | InteractionStateMixin | ||
_showFeedbackConditionFor | protected | Default feedbackCondition condition, used by Subclassers, that will be used when `feedbackCondition()` is not overridden by Application Developer. Show the validity feedback when returning true, don't show when false | type: string, meta: InteractionStates | ValidateMixin | |
validate | public | Triggered by: - modelValue change - change in the 'validators' array - change in the config of an individual Validator Three situations are handled: - a1) the FormControl is empty: further execution is halted. When the Required Validator (being mutually exclusive to the other Validators) is applied, it will end up in the validation result (as the only Validator, since further execution was halted). - a2) there are synchronous Validators: this is the most common flow. When modelValue hasn't changed since last async results were generated, 'sync results' are merged with the 'async results'. - a3) there are asynchronous Validators: for instance when server side evaluation is needed. Executions are scheduled and awaited and the 'async results' are merged with the 'sync results'. - b) there are MetaValidators. After steps a1, a2, or a3 are finished, the holistic MetaValidators (evaluating the total result of the 'regular' (a1, a2 and a3) validators) will be run... Situations a2 and a3 are not mutually exclusive and can be triggered within one `validate()` call. Situation b will occur after every call. | { clearCurrentResult = false }, opts: { clearCurrentResult?: boolean } | ValidateMixin | |
__executeValidators | protected | ValidateMixin | |||
_onValidatorUpdated | protected | e: Event|CustomEvent | ValidateMixin | ||
_updateFeedbackComponent | protected | Responsible for retrieving messages from Validators and (delegation of) rendering them. For `._feedbackNode` (extension of LionValidationFeedback): - retrieve messages from highest prio Validators - provide the result to custom feedback node and let the custom node decide on their renderings In both cases: - we compute the 'show' flag (like 'hasErrorVisible') for all types - we set the customValidity message of the highest prio Validator - we set aria-invalid="true" in case hasErrorVisible is true | ValidateMixin | ||
feedbackCondition | public | Allows the Application Developer to specify when a feedback message should be shown | type: string, meta: object, currentCondition: ((type: string, meta: object) => boolean) | boolean | ValidateMixin |
_hasFeedbackVisibleFor | protected | Used to translate `.hasFeedbackFor` and `.shouldShowFeedbackFor` to `.showsFeedbackFor` | type: string | ValidateMixin | |
_updateShouldShowFeedbackFor | protected | ValidateMixin | |||
_prioritizeAndFilterFeedback | protected | Orders all active validators in this.__validationResult. Can also filter out occurrences (based on interaction states) | { validationResult }, opts: { validationResult: Validator[] } | Validator[] | ValidateMixin |
reset | public | Resets modelValue to initial value. Interaction states are cleared | LionField | ||
_onChange | protected | Dispatches custom bubble event | ev: Event= | LionField |
Events
| Name | Type | Description | Inherited From |
|---|---|---|---|
model-value-changed | CustomEvent | FormControlMixin | |
user-input-changed | Event | LionField | |
focus | Event | FocusMixin | |
blur | Event | FocusMixin | |
focusin | Event | FocusMixin | |
focusout | Event | FocusMixin | |
form-element-name-changed | CustomEvent | FormControlMixin | |
form-element-register | CustomEvent | FormRegisteringMixin | |
touched-changed | Event | InteractionStateMixin | |
dirty-changed | Event | InteractionStateMixin | |
showsFeedbackForChanged | Event | ValidateMixin | |
Event | ValidateMixin | ||
shouldShowFeedbackForChanged | Event | ValidateMixin | |
validate-performed | Event | private event that should be listened to by LionFieldSet | ValidateMixin |
Attributes
| Name | Field | Inherited From |
|---|---|---|
indeterminate | indeterminate | |
mixed-state | mixedState | |
checked | checked | ChoiceInputMixin |
disabled | disabled | DisabledMixin |
modelValue | modelValue | ChoiceInputMixin |
choiceValue | choiceValue | ChoiceInputMixin |
autocomplete | autocomplete | NativeTextFieldMixin |
focused | focused | FocusMixin |
focused-visible | focusedVisible | FocusMixin |
autofocus | autofocus | FocusMixin |
readonly | readOnly | FormControlMixin |
label | label | FormControlMixin |
label-sr-only | labelSrOnly | FormControlMixin |
help-text | helpText | FormControlMixin |
type | type | LionInput |
placeholder | placeholder | LionInput |
name | name | FormRegisteringMixin |
allow-cross-root-registration | allowCrossRootRegistration | FormRegisteringMixin |
touched | touched | InteractionStateMixin |
dirty | dirty | InteractionStateMixin |
filled | filled | InteractionStateMixin |
shows-feedback-for | showsFeedbackFor | ValidateMixin |
is-pending | isPending | ValidateMixin |