more documentation

Author: nielslyngsoe

packages/uui-base/lib/mixins/FormControlMixin.ts

@@ -168,10 +168,22 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
       });
     }
 
+    /**
+     * Determn wether this FormControl has a value.
+     * @method hasValue
+     * @returns {boolean}
+     */
     public hasValue(): boolean {
       return this.value !== '';
     }
 
+    /**
+     * Get internal form element.
+     * This has to be implemented to provide a FormControl Element of choice for the given context. The element is used as anchor for validation-messages.
+     * @abstract
+     * @method getFormElement
+     * @returns {HTMLElement | undefined}
+     */
     protected abstract getFormElement(): HTMLElement | undefined;
 
     disconnectedCallback(): void {
@@ -184,6 +196,21 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
       }
     }
 
+    /**
+     * Add validator, to validate this Form Control.
+     * See https://developer.mozilla.org/en-US/docs/Web/API/ValidityState for available Validator FlagTypes.
+     *
+     * @example
+     * this.addValidator(
+     *  'tooLong',
+     *  () => 'This input contains too many characters',
+     *  () => this._value.length > 10
+     * );
+     * @method hasValue
+     * @param {FlagTypes} flagKey the type of validation.
+     * @param {method} getMessage method to retrieve relevant message. Is executed every time the validator is re-executed.
+     * @param {method} checkMethod method to determine if this validator should invalidate this form control. Return true if this should prevent submission.
+     */
     protected addValidator(
       flagKey: FlagTypes,
       getMessageMethod: () => String,
@@ -225,13 +252,6 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
     updated(changedProperties: Map<string | number | symbol, unknown>) {
       super.updated(changedProperties);
       this._runValidators();
-      /*
-      if(changedProperties.has('pristine')) {
-        if(changedProperties.get('pristine') === false) {
-          this._internals.reportValidity();
-        }
-      }
-      */
     }
 
     private _onFormSubmit = () => {

packages/uui-form-validation-message/lib/uui-form-validation-message.element.ts

@@ -7,9 +7,11 @@ import { repeat } from 'lit/directives/repeat.js';
 
 /**
  * @element uui-form-validation-message
- * @description - Component for displaying one or more validation messages from Form Control within the given scope. Notice: Only supports components that build on the FormControlMixing.
+ * @description - Component for displaying one or more validation messages from UUI Form Control within the given scope.
+ * Notice: Only supports components that is build on the FormControlMixing.
  * @slot - for button contents
  * @slot message - for extras in the messages container
+ * @see FormControlMixin
  */
 
 @defineElement('uui-form-validation-message')
@@ -77,8 +79,8 @@ export class UUIFormValidationMessageElement extends LitElement {
 
   private _onControlInvalid = (e: UUIFormControlEvent) => {
     const ctrl = e.target;
-    if (ctrl.pristine !== true) {
-      // This enables any component who does have the pristine property to hide a message. (as well we only want to show messages from fields that are NOT pristine aka. that are dirty or in a from that has been submitted)
+    if (ctrl.pristine === false) {
+      // Currently we only show message from components who does have the pristine property. (we only want to show messages from fields that are NOT pristine aka. that are dirty or in a from that has been submitted)
       this._messages.set(ctrl, ctrl.validationMessage);
     } else {
       this._messages.delete(ctrl);

packages/uui-form-validation-message/lib/uui-form-validation-message.story.ts

@@ -33,7 +33,7 @@ AAAOverview.storyName = 'Overview';
 export const ForAnotherElement: Story = () =>
   html` <p>
       The Form Validation Message element can also display validation messages
-      from another element than it self. This is done by setting the 'for'
+      from another scope than it self. This is done by setting the 'for'
       attribute.
     </p>
     <div id="myCustomScope">

packages/uui-form/lib/uui-form.element.ts

@@ -18,6 +18,7 @@ export class UUIFormElement extends HTMLFormElement {
     const isValid = this.checkValidity();
 
     if (!isValid) {
+      // submit-invalid attribute is used by descendant form controls to check wether submit has been requested without succeeding.
       this.setAttribute('submit-invalid', '');
       return;
     }