@gitlab/ui 62.5.2 → 62.7.0

package/src/components/base/form/form_fields/form_fields.vue

@@ -0,0 +1,219 @@
+<script>
+import isFunction from 'lodash/isFunction';
+import mapValues from 'lodash/mapValues';
+import uniqueId from 'lodash/uniqueId';
+import GlFormGroup from '../form_group/form_group.vue';
+import GlFormInput from '../form_input/form_input.vue';
+import GlFormFieldValidator from './form_field_validator.vue';
+
+export default {
+  name: 'GlFormFields',
+  components: {
+    GlFormGroup,
+    GlFormInput,
+    GlFormFieldValidator,
+  },
+  model: {
+    prop: 'values',
+    event: 'input',
+  },
+  props: {
+    /**
+     * Object of keys to FieldDefinitions.
+     * The shape of the keys will be the same for `values` and what's emitted by the `input` event.
+     *
+     * @typedef {object} FieldDefinition
+     * @template TValue=string
+     * @property {string} label - Label text to show for this field.
+     * @property {undefined | Object} inputAttrs - Properties that are passed to the actual input for this field.
+     * @property {undefined | function(string): TValue} mapValue - Function that maps the inputted string value to the field's actual value (e.g. a Number).
+     * @property {undefined | Array<function(TValue): string | undefined>=} validators - Collection of validator functions.
+     *
+     * @type {{ [key: string]: FieldDefinition }}
+     */
+    fields: {
+      type: Object,
+      required: true,
+    },
+    /**
+     * The current value for each field, by key.
+     * Keys should match between `values` and `fields`.
+     */
+    values: {
+      type: Object,
+      required: true,
+    },
+    /**
+     * The id of the form element to handle "submit" listening.
+     */
+    formId: {
+      type: String,
+      required: true,
+    },
+  },
+  data() {
+    return {
+      fieldDirtyStatuses: {},
+      fieldValidations: {},
+    };
+  },
+  computed: {
+    formElement() {
+      return document.getElementById(this.formId);
+    },
+    fieldValidationProps() {
+      return mapValues(this.fields, (_, fieldName) => {
+        const invalidFeedback = this.fieldValidations[fieldName] || '';
+
+        return {
+          invalidFeedback,
+          state: invalidFeedback ? false : null,
+        };
+      });
+    },
+    fieldValues() {
+      return mapValues(this.fields, (_, fieldName) => {
+        if (fieldName in this.values) {
+          return this.values[fieldName];
+        }
+
+        return this.getMappedValue(fieldName, undefined);
+      });
+    },
+    fieldNames() {
+      return Object.keys(this.fields);
+    },
+    fieldsToRender() {
+      return mapValues(this.fields, (field, fieldName) => {
+        const id = uniqueId('gl-form-field-');
+
+        const scopedSlotName = `input(${fieldName})`;
+        const hasScopedSlot = this.$scopedSlots[scopedSlotName];
+        const scopedSlotAttrs = hasScopedSlot && {
+          value: this.fieldValues[fieldName],
+          input: (val) => this.onFieldInput(fieldName, val),
+          blur: () => this.onFieldBlur(fieldName),
+          validation: this.fieldValidationProps[fieldName],
+          id,
+        };
+
+        return {
+          ...field,
+          id,
+          label: field.label || fieldName,
+          scopedSlotName,
+          scopedSlotAttrs,
+        };
+      });
+    },
+  },
+  mounted() {
+    // why: We emit initial values as a convenience so that `v-model="values"` can be easily initialized.
+    this.$emit('input', this.fieldValues);
+
+    this.formElement?.addEventListener('submit', this.onFormSubmission);
+  },
+  destroyed() {
+    this.formElement?.removeEventListener('submit', this.onFormSubmission);
+  },
+  methods: {
+    setFieldDirty(fieldName) {
+      this.$set(this.fieldDirtyStatuses, fieldName, true);
+    },
+    setAllFieldsDirty() {
+      this.fieldNames.forEach((fieldName) => this.setFieldDirty(fieldName));
+    },
+    hasAllFieldsValid() {
+      // note: Only check "fieldNames" since "fields" could have changed since the life of "fieldValidations"
+      return this.fieldNames.every((fieldName) => !this.fieldValidations[fieldName]);
+    },
+    async checkBeforeSubmission() {
+      this.setAllFieldsDirty();
+
+      await this.$nextTick();
+
+      return this.hasAllFieldsValid();
+    },
+    getMappedValue(fieldName, val) {
+      const field = this.fields[fieldName];
+
+      if (isFunction(field?.mapValue)) {
+        return field.mapValue(val);
+      }
+
+      return val;
+    },
+    onFieldValidationUpdate(fieldName, invalidFeedback) {
+      this.$set(this.fieldValidations, fieldName, invalidFeedback);
+    },
+    onFieldBlur(fieldName) {
+      this.setFieldDirty(fieldName);
+    },
+    onFieldInput(fieldName, inputValue) {
+      const val = this.getMappedValue(fieldName, inputValue);
+
+      /**
+       * Emitted when any of the form values change. Used by `v-model`.
+       */
+      this.$emit('input', {
+        ...this.values,
+        [fieldName]: val,
+      });
+
+      /**
+       * Emitted when a form input emits the `input` event.
+       */
+      this.$emit('input-field', {
+        name: fieldName,
+        value: val,
+      });
+    },
+    async onFormSubmission(e) {
+      e.preventDefault();
+
+      const isValid = await this.checkBeforeSubmission();
+
+      if (isValid) {
+        /**
+         * Emitted when the form is submitted and all of the form fields are valid.
+         */
+        this.$emit('submit', e);
+      }
+    },
+  },
+};
+</script>
+
+<template>
+  <div>
+    <gl-form-group
+      v-for="(field, fieldName) in fieldsToRender"
+      :key="fieldName"
+      :label="field.label"
+      :label-for="field.id"
+      :invalid-feedback="fieldValidationProps[fieldName].invalidFeedback"
+      :state="fieldValidationProps[fieldName].state"
+    >
+      <gl-form-field-validator
+        :value="fieldValues[fieldName]"
+        :validators="field.validators"
+        :should-validate="fieldDirtyStatuses[fieldName]"
+        @update="onFieldValidationUpdate(fieldName, $event)"
+      />
+      <template v-if="field.scopedSlotAttrs">
+        <!-- @slot scoped slot that can be used for components other than `GlFormInput`. The name of the slot is `input(<fieldName>)`. -->
+        <slot :name="field.scopedSlotName" v-bind="field.scopedSlotAttrs"></slot>
+      </template>
+      <template v-else>
+        <gl-form-input
+          :id="field.id"
+          :value="fieldValues[fieldName]"
+          :state="fieldValidationProps[fieldName].state"
+          v-bind="field.inputAttrs"
+          @input="onFieldInput(fieldName, $event)"
+          @blur="onFieldBlur(fieldName)"
+        />
+      </template>
+    </gl-form-group>
+  </div>
+</template>

package/src/components/base/form/form_fields/mappers.js

@@ -0,0 +1,11 @@
+// This contains core mapping behavior (like mapping to native JavaScript types)
+// and**should not** contain domain-specific mappers.
+//
+// ```
+// // Good
+// export const mapToBoolean = ...
+//
+// // Bad
+// export const mapToApolloCacheWidget = ...
+// ```
+export const mapToNumber = (x) => Number(x || 0);

package/src/components/base/form/form_fields/mappers.spec.js

@@ -0,0 +1,17 @@
+import { mapToNumber } from './mappers';
+
+describe('components/base/form/form_fields/mappers', () => {
+  describe('mapToNumber', () => {
+    it.each`
+      input      | output
+      ${''}      | ${0}
+      ${false}   | ${0}
+      ${{}}      | ${Number.NaN}
+      ${'888'}   | ${888}
+      ${'-5e10'} | ${-50000000000}
+      ${'55.78'} | ${55.78}
+    `('with $input, returns $output', ({ input, output }) => {
+      expect(mapToNumber(input)).toBe(output);
+    });
+  });
+});

package/src/components/base/form/form_fields/validators.js

@@ -0,0 +1,16 @@
+// This contains core validating behavior and **should not** contain
+// domain-specific validations.
+//
+// Look to what's allowed in HTML attributes as a good basis for what belongs here
+//
+// ```
+// // Good
+// export const required = ...
+//
+// // Bad
+// export const projectPathIsUnique = ...
+// ```
+export const factory = (failMessage, isValid) => (val) => !isValid(val) ? failMessage : '';
+
+export const required = (failMessage) =>
+  factory(failMessage, (val) => val !== '' && val !== null && val !== undefined);

package/src/components/base/form/form_fields/validators.spec.js

@@ -0,0 +1,29 @@
+import { required } from './validators';
+
+const TEST_FAIL_MESSAGE = 'Yo test failed!';
+
+describe('components/base/form/form_fields/validators', () => {
+  // note: We used the `factory` to build required, so we implicitly test `factory` heere
+  describe('required', () => {
+    let validator;
+
+    beforeEach(() => {
+      validator = required(TEST_FAIL_MESSAGE);
+    });
+
+    it.each`
+      input        | output
+      ${''}        | ${TEST_FAIL_MESSAGE}
+      ${null}      | ${TEST_FAIL_MESSAGE}
+      ${undefined} | ${TEST_FAIL_MESSAGE}
+      ${'123'}     | ${''}
+      ${{}}        | ${''}
+      ${0}         | ${''}
+      ${1}         | ${''}
+      ${true}      | ${''}
+      ${false}     | ${''}
+    `('with $input, returns $output', ({ input, output }) => {
+      expect(validator(input)).toBe(output);
+    });
+  });
+});

package/src/index.js

@@ -44,6 +44,7 @@ export { default as GlFormRadioGroup } from './components/base/form/form_radio_g
 export { default as GlFormSelect } from './components/base/form/form_select/form_select.vue';
 export { default as GlFormTextarea } from './components/base/form/form_textarea/form_textarea.vue';
 export { default as GlFormGroup } from './components/base/form/form_group/form_group.vue';
+export { default as GlFormFields } from './components/base/form/form_fields/form_fields.vue';
 export { default as GlSearchBoxByType } from './components/base/search_box_by_type/search_box_by_type.vue';
 export { default as GlSearchBoxByClick } from './components/base/search_box_by_click/search_box_by_click.vue';
 export { default as GlDropdownItem } from './components/base/dropdown/dropdown_item.vue';

package/src/scss/utilities.scss

@@ -6745,6 +6745,12 @@
 .gl-column-gap-6\! {
   column-gap: $gl-spacing-scale-6 !important;
 }
+.gl-row-gap-6 {
+  row-gap: $gl-spacing-scale-6;
+}
+.gl-row-gap-6\! {
+  row-gap: $gl-spacing-scale-6 !important;
+}
 .gl-xs-mb-3 {
   @include gl-media-breakpoint-down(sm) {
   margin-bottom: $gl-spacing-scale-3;

package/src/scss/utility-mixins/spacing.scss

@@ -890,6 +890,18 @@
   column-gap: $gl-spacing-scale-6;
 }
 
+/**
+* Row gap utilities
+*
+* naming convention: gl-row-gap-{spacing-scale-index}
+* notes:
+* - Utilities should strictly follow $gl-spacing-scale
+*/
+
+@mixin gl-row-gap-6 {
+  row-gap: $gl-spacing-scale-6;
+}
+
 /**
 * Responsive margin utilities.
 *

package/src/utils.js

@@ -1 +1,4 @@
 export { GlBreakpointInstance, breakpoints } from './utils/breakpoints';
+
+export * as formValidators from './components/base/form/form_fields/validators';
+export * as formMappers from './components/base/form/form_fields/mappers';