@gitlab/ui 62.5.2 → 62.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [62.6.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v62.5.2...v62.6.0) (2023-05-02)
+
+
+### Features
+
+* Add gl-form-fields component ([a17bcb6](https://gitlab.com/gitlab-org/gitlab-ui/commit/a17bcb6c8db0444dcd7f5bd799fe681891dbdcc9))
+
 ## [62.5.2](https://gitlab.com/gitlab-org/gitlab-ui/compare/v62.5.1...v62.5.2) (2023-05-01)
 
 

package/dist/components/base/form/form_fields/form_field_validator.js

@@ -0,0 +1,93 @@
+import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
+
+/**
+ * FormFieldValidator
+ *
+ * This is an internal component which is used to watch on specific field/value
+ * pairs and emits changes to `invalidFeedback`.
+ *
+ * **why:** Without this separate component, *any* change to *any* value
+ * was causing *all* validators to run. A separate renderless component
+ * helps us isolate this logic *and* react only to what we need to.
+ */
+var script = {
+  name: 'GlFormFieldValidator',
+  props: {
+    value: {
+      required: true,
+      // ESLint requires "validator" or "type". Any kind of value is valid.
+      validator: () => true
+    },
+    validators: {
+      type: Array,
+      required: false,
+      default: () => []
+    },
+    shouldValidate: {
+      type: Boolean,
+      required: false,
+      default: false
+    }
+  },
+  computed: {
+    invalidFeedback() {
+      if (!this.shouldValidate) {
+        return '';
+      }
+      const result = this.validators.reduce((acc, validateFn) => {
+        // If we already have an invalid message, let's just use that one.
+        if (acc) {
+          return acc;
+        }
+        return validateFn(this.value);
+      }, '');
+
+      // Force falsey string for type consistency.
+      return result || '';
+    }
+  },
+  watch: {
+    invalidFeedback(newVal) {
+      this.$emit('update', newVal);
+    }
+  },
+  render() {
+    return null;
+  }
+};
+
+/* script */
+const __vue_script__ = script;
+
+/* template */
+
+  /* style */
+  const __vue_inject_styles__ = undefined;
+  /* scoped */
+  const __vue_scope_id__ = undefined;
+  /* module identifier */
+  const __vue_module_identifier__ = undefined;
+  /* functional template */
+  const __vue_is_functional_template__ = undefined;
+  /* style inject */
+  
+  /* style inject SSR */
+  
+  /* style inject shadow dom */
+  
+
+  
+  const __vue_component__ = __vue_normalize__(
+    {},
+    __vue_inject_styles__,
+    __vue_script__,
+    __vue_scope_id__,
+    __vue_is_functional_template__,
+    __vue_module_identifier__,
+    false,
+    undefined,
+    undefined,
+    undefined
+  );
+
+export default __vue_component__;

package/dist/components/base/form/form_fields/form_fields.js

@@ -0,0 +1,213 @@
+import isFunction from 'lodash/isFunction';
+import mapValues from 'lodash/mapValues';
+import uniqueId from 'lodash/uniqueId';
+import GlFormGroup from '../form_group/form_group';
+import GlFormInput from '../form_input/form_input';
+import GlFormFieldValidator from './form_field_validator';
+import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
+
+var script = {
+  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() {
+    var _this$formElement;
+    // why: We emit initial values as a convenience so that `v-model="values"` can be easily initialized.
+    this.$emit('input', this.fieldValues);
+    (_this$formElement = this.formElement) === null || _this$formElement === void 0 ? void 0 : _this$formElement.addEventListener('submit', this.onFormSubmission);
+  },
+  destroyed() {
+    var _this$formElement2;
+    (_this$formElement2 = this.formElement) === null || _this$formElement2 === void 0 ? void 0 : _this$formElement2.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 === null || field === void 0 ? void 0 : 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 */
+const __vue_script__ = script;
+
+/* template */
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('div',_vm._l((_vm.fieldsToRender),function(field,fieldName){return _c('gl-form-group',{key:fieldName,attrs:{"label":field.label,"label-for":field.id,"invalid-feedback":_vm.fieldValidationProps[fieldName].invalidFeedback,"state":_vm.fieldValidationProps[fieldName].state}},[_c('gl-form-field-validator',{attrs:{"value":_vm.fieldValues[fieldName],"validators":field.validators,"should-validate":_vm.fieldDirtyStatuses[fieldName]},on:{"update":function($event){return _vm.onFieldValidationUpdate(fieldName, $event)}}}),_vm._v(" "),(field.scopedSlotAttrs)?[_vm._t(field.scopedSlotName,null,null,field.scopedSlotAttrs)]:[_c('gl-form-input',_vm._b({attrs:{"id":field.id,"value":_vm.fieldValues[fieldName],"state":_vm.fieldValidationProps[fieldName].state},on:{"input":function($event){return _vm.onFieldInput(fieldName, $event)},"blur":function($event){return _vm.onFieldBlur(fieldName)}}},'gl-form-input',field.inputAttrs,false))]],2)}),1)};
+var __vue_staticRenderFns__ = [];
+
+  /* style */
+  const __vue_inject_styles__ = undefined;
+  /* scoped */
+  const __vue_scope_id__ = undefined;
+  /* module identifier */
+  const __vue_module_identifier__ = undefined;
+  /* functional template */
+  const __vue_is_functional_template__ = false;
+  /* style inject */
+  
+  /* style inject SSR */
+  
+  /* style inject shadow dom */
+  
+
+  
+  const __vue_component__ = __vue_normalize__(
+    { render: __vue_render__, staticRenderFns: __vue_staticRenderFns__ },
+    __vue_inject_styles__,
+    __vue_script__,
+    __vue_scope_id__,
+    __vue_is_functional_template__,
+    __vue_module_identifier__,
+    false,
+    undefined,
+    undefined,
+    undefined
+  );
+
+export default __vue_component__;

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

@@ -0,0 +1,13 @@
+// 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 = ...
+// ```
+const mapToNumber = x => Number(x || 0);
+
+export { mapToNumber };

package/dist/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 = ...
+// ```
+const factory = (failMessage, isValid) => val => !isValid(val) ? failMessage : '';
+const required = failMessage => factory(failMessage, val => val !== '' && val !== null && val !== undefined);
+
+export { factory, required };

package/dist/index.js

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

package/dist/utils.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "62.5.2",
+  "version": "62.6.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",
@@ -83,8 +83,8 @@
   },
   "devDependencies": {
     "@arkweid/lefthook": "0.7.7",
-    "@babel/core": "^7.21.4",
-    "@babel/preset-env": "^7.21.4",
+    "@babel/core": "^7.21.5",
+    "@babel/preset-env": "^7.21.5",
     "@babel/preset-react": "^7.18.6",
     "@gitlab/eslint-plugin": "19.0.0",
     "@gitlab/fonts": "^1.2.0",

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

@@ -0,0 +1,51 @@
+import { mount } from '@vue/test-utils';
+import GlFormFieldValidator from './form_field_validator.vue';
+import { required } from './validators';
+
+const TEST_VALUE = 'root';
+const TEST_MESSAGE = 'this is a required field';
+
+describe('GlFormFieldValidators', () => {
+  let wrapper;
+
+  const createWrapper = (props = {}) => {
+    wrapper = mount(GlFormFieldValidator, {
+      propsData: {
+        value: TEST_VALUE,
+        validators: [required(TEST_MESSAGE)],
+        shouldValidate: true,
+        ...props,
+      },
+    });
+  };
+  it('should call validators with value prop', () => {
+    const validators = [jest.fn(), jest.fn(), jest.fn()];
+
+    createWrapper({ validators });
+
+    validators.forEach((validator) => expect(validator).toHaveBeenCalledWith(TEST_VALUE));
+  });
+  it('should not call validators when told not to', () => {
+    const validators = [jest.fn(), jest.fn(), jest.fn()];
+
+    createWrapper({ validators, shouldValidate: false });
+
+    validators.forEach((validator) => expect(validator).not.toHaveBeenCalledWith(TEST_VALUE));
+  });
+
+  it('should not render anything ever forever', () => {
+    createWrapper();
+
+    expect(wrapper.html()).toBe('');
+  });
+
+  it('should emit update with result of validator', async () => {
+    createWrapper();
+
+    expect(wrapper.emitted('update')).toBeUndefined();
+
+    await wrapper.setProps({ value: '' });
+
+    expect(wrapper.emitted('update')).toEqual([[TEST_MESSAGE]]);
+  });
+});

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

@@ -0,0 +1,59 @@
+<script>
+/**
+ * FormFieldValidator
+ *
+ * This is an internal component which is used to watch on specific field/value
+ * pairs and emits changes to `invalidFeedback`.
+ *
+ * **why:** Without this separate component, *any* change to *any* value
+ * was causing *all* validators to run. A separate renderless component
+ * helps us isolate this logic *and* react only to what we need to.
+ */
+export default {
+  name: 'GlFormFieldValidator',
+  props: {
+    value: {
+      required: true,
+      // ESLint requires "validator" or "type". Any kind of value is valid.
+      validator: () => true,
+    },
+    validators: {
+      type: Array,
+      required: false,
+      default: () => [],
+    },
+    shouldValidate: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+  },
+  computed: {
+    invalidFeedback() {
+      if (!this.shouldValidate) {
+        return '';
+      }
+
+      const result = this.validators.reduce((acc, validateFn) => {
+        // If we already have an invalid message, let's just use that one.
+        if (acc) {
+          return acc;
+        }
+
+        return validateFn(this.value);
+      }, '');
+
+      // Force falsey string for type consistency.
+      return result || '';
+    },
+  },
+  watch: {
+    invalidFeedback(newVal) {
+      this.$emit('update', newVal);
+    },
+  },
+  render() {
+    return null;
+  },
+};
+</script>

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

@@ -0,0 +1,28 @@
+## Usage
+
+`GlFormFields` provides form builder functionality for ease of building simple
+forms out of other GitLab UI form components.
+
+For a code example, look at the story. It covers usage of `mapValue`, `validators`,
+custom form elements, and `inputAttrs`.
+
+## Fields type
+
+Each value of `fields` prop is expected to be a `FieldDefinition`. See below for the shape of this type:
+
+```ts
+interface FieldDefinition<TValue> {
+  // Label text to show for this field.
+  label: string;
+
+  // Collection of validator functions
+  validators?: Array<(value: TValue) => string | undefined>;
+
+  // Function that maps the inputted string value to the field's actual value
+  // (e.g. a Number).
+  mapValue?: (input: string) => TValue;
+
+  // Properties that are passed to the actual input for this field.
+  inputAttrs?: {};
+}
+```

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

@@ -0,0 +1,424 @@
+import cloneDeep from 'lodash/cloneDeep';
+import mapValues from 'lodash/mapValues';
+import { nextTick } from 'vue';
+import { shallowMount } from '@vue/test-utils';
+import GlFormGroup from '../form_group/form_group.vue';
+import GlInput from '../form_input/form_input.vue';
+import GlFormFields from './form_fields.vue';
+import GlFormFieldValidator from './form_field_validator.vue';
+import * as formMappers from './mappers';
+import * as formValidators from './validators';
+
+jest.mock('lodash/uniqueId', () => (val) => `${val}testunique`);
+
+const TEST_FIELDS = {
+  username: {
+    label: 'User name',
+    validators: [formValidators.required('User name is required')],
+  },
+  evenCount: {
+    label: 'Count',
+    mapValue: formMappers.mapToNumber,
+    validators: [
+      formValidators.factory('Count is required', Boolean),
+      (val) => (val % 2 === 1 ? 'Count must be even' : ''),
+    ],
+    inputAttrs: { size: 'xs', type: 'number' },
+  },
+  allCaps: {
+    label: 'All caps (optional)',
+    mapValue: (x) => x?.toUpperCase(),
+  },
+};
+const TEST_VALUES = {
+  username: 'root',
+  evenCount: 8,
+  allCaps: '',
+};
+
+const TEST_FORM_ID = 'test-form-id';
+
+describe('GlFormFields', () => {
+  let wrapper;
+
+  // region: factory --------------------------------------------------
+  const createComponent = (props = {}, options = {}) => {
+    // why: Clone the constant so Vue doesn't turn it reactive
+    const fields = cloneDeep(TEST_FIELDS);
+
+    wrapper = shallowMount(GlFormFields, {
+      propsData: {
+        fields,
+        values: {},
+        formId: TEST_FORM_ID,
+        ...props,
+      },
+      stubs: {
+        GlFormFieldValidator,
+      },
+      ...options,
+    });
+  };
+
+  // region: finders --------------------------------------------------
+  const mapFormGroupToData = (formGroup) => {
+    const input = formGroup.findComponent(GlInput);
+
+    return {
+      label: formGroup.attributes('label'),
+      state: formGroup.attributes('state'),
+      invalidFeedback: formGroup.attributes('invalid-feedback'),
+      input: {
+        // Ensure that "value" is present even if undefined
+        value: input.attributes('value'),
+        ...input.attributes(),
+      },
+    };
+  };
+  const findFormGroups = () => wrapper.findAllComponents(GlFormGroup).wrappers;
+  const findFormGroupsAsData = () => findFormGroups().map(mapFormGroupToData);
+  const findFormGroupFromLabel = (label) =>
+    wrapper.findAllComponents(GlFormGroup).wrappers.find((x) => x.attributes('label') === label);
+  const findInputFromLabel = (label) => findFormGroupFromLabel(label).findComponent(GlInput);
+  const findCustomInputFromLabel = (label) =>
+    findFormGroupFromLabel(label).find('[data-testid="test-custom-input"]');
+
+  // region: actions ---------------------------------------------------
+  const submitForm = async () => {
+    const form = document.getElementById(TEST_FORM_ID);
+
+    form.requestSubmit();
+
+    // Submit form waits for a tick
+    await nextTick();
+  };
+
+  // region: setup -----------------------------------------------------
+  beforeEach(() => {
+    document.body.innerHTML = `<form id="${TEST_FORM_ID}"></form>`;
+  });
+
+  // region: tests -----------------------------------------------------
+  describe('default', () => {
+    beforeEach(() => {
+      createComponent();
+    });
+
+    it('renders form groups for each field', () => {
+      expect(findFormGroupsAsData()).toStrictEqual([
+        {
+          label: TEST_FIELDS.username.label,
+          state: undefined,
+          invalidFeedback: '',
+          input: {
+            id: 'gl-form-field-testunique',
+            value: undefined,
+          },
+        },
+        {
+          label: TEST_FIELDS.evenCount.label,
+          state: undefined,
+          invalidFeedback: '',
+          input: {
+            id: 'gl-form-field-testunique',
+            value: '0',
+            ...TEST_FIELDS.evenCount.inputAttrs,
+          },
+        },
+        {
+          label: TEST_FIELDS.allCaps.label,
+          state: undefined,
+          invalidFeedback: '',
+          input: {
+            id: 'gl-form-field-testunique',
+            value: undefined,
+          },
+        },
+      ]);
+    });
+
+    it('emits initial values on mount', () => {
+      expect(wrapper.emitted('input')).toEqual([
+        [
+          {
+            username: undefined,
+            evenCount: 0,
+            allCaps: undefined,
+          },
+        ],
+      ]);
+    });
+
+    it('does not emit input-field', () => {
+      expect(wrapper.emitted('input-field')).toBeUndefined();
+    });
+
+    it('does not emit submit', () => {
+      expect(wrapper.emitted('submit')).toBeUndefined();
+    });
+
+    it('on field blur, it updates validation for field', async () => {
+      const input = findInputFromLabel(TEST_FIELDS.username.label);
+      input.vm.$emit('blur');
+
+      await nextTick();
+
+      expect(findFormGroupsAsData()).toMatchObject([
+        {
+          label: TEST_FIELDS.username.label,
+          invalidFeedback: 'User name is required',
+        },
+        // why: Include others fields to assert that the validation is not run for them
+        {
+          label: TEST_FIELDS.evenCount.label,
+          invalidFeedback: '',
+        },
+        {
+          label: TEST_FIELDS.allCaps.label,
+          invalidFeedback: '',
+        },
+      ]);
+    });
+
+    describe('on field input', () => {
+      beforeEach(() => {
+        const input = findInputFromLabel(TEST_FIELDS.username.label);
+        input.vm.$emit('input', 'New value');
+      });
+
+      it('emits input event', () => {
+        expect(wrapper.emitted('input')).toEqual([
+          // Initial value we already test here
+          expect.anything(),
+          // New emitted event
+          [
+            {
+              username: 'New value',
+            },
+          ],
+        ]);
+      });
+
+      it('emits input-field event', () => {
+        expect(wrapper.emitted('input-field')).toEqual([
+          [
+            {
+              name: 'username',
+              value: 'New value',
+            },
+          ],
+        ]);
+      });
+    });
+
+    describe('when form submits', () => {
+      beforeEach(async () => {
+        await submitForm();
+      });
+
+      it('runs validations', () => {
+        expect(findFormGroupsAsData()).toEqual([
+          {
+            label: TEST_FIELDS.username.label,
+            invalidFeedback: 'User name is required',
+            state: undefined,
+            input: {
+              value: undefined,
+              id: 'gl-form-field-testunique',
+            },
+          },
+          {
+            label: TEST_FIELDS.evenCount.label,
+            invalidFeedback: 'Count is required',
+            state: undefined,
+            input: expect.objectContaining({
+              value: '0',
+              id: 'gl-form-field-testunique',
+            }),
+          },
+          {
+            label: TEST_FIELDS.allCaps.label,
+            invalidFeedback: '',
+            state: undefined,
+            input: {
+              value: undefined,
+              id: 'gl-form-field-testunique',
+            },
+          },
+        ]);
+      });
+
+      it('does not emit submit', () => {
+        expect(wrapper.emitted('submit')).toBeUndefined();
+      });
+    });
+  });
+
+  // why: Let's test that multiple validators work as expected
+  describe('with non-empty but invalid "count"', () => {
+    beforeEach(() => {
+      createComponent({
+        values: {
+          evenCount: 7,
+        },
+      });
+    });
+
+    it('on blur, it runs remaining validators for "count" field', async () => {
+      const input = findInputFromLabel(TEST_FIELDS.evenCount.label);
+      input.vm.$emit('blur');
+
+      await nextTick();
+
+      expect(findFormGroupsAsData().find((x) => x.label === TEST_FIELDS.evenCount.label)).toEqual({
+        label: TEST_FIELDS.evenCount.label,
+        invalidFeedback: 'Count must be even',
+        state: undefined,
+        input: {
+          ...TEST_FIELDS.evenCount.inputAttrs,
+          id: 'gl-form-field-testunique',
+          value: '7',
+        },
+      });
+    });
+  });
+
+  describe('with valid values', () => {
+    beforeEach(() => {
+      const values = cloneDeep(TEST_VALUES);
+
+      createComponent({
+        values,
+      });
+    });
+
+    it('when form submits, emits submit', async () => {
+      await submitForm();
+
+      expect(wrapper.emitted('submit')).toEqual([[expect.any(Event)]]);
+    });
+
+    describe.each`
+      fieldName      | inputValue   | expectedValue
+      ${'allCaps'}   | ${'foo bar'} | ${'FOO BAR'}
+      ${'evenCount'} | ${'123'}     | ${123}
+    `(
+      'when input ("$fieldName") with mapValue changes',
+      ({ fieldName, inputValue, expectedValue }) => {
+        beforeEach(() => {
+          const input = findInputFromLabel(TEST_FIELDS[fieldName].label);
+          input.vm.$emit('input', inputValue);
+        });
+
+        it('emits input with mapped value', () => {
+          expect(wrapper.emitted('input')).toEqual([
+            // Ignore initial inputted value (already tested)
+            expect.anything(),
+            [
+              {
+                ...TEST_VALUES,
+                [fieldName]: expectedValue,
+              },
+            ],
+          ]);
+        });
+
+        it('emits input-field with mapped value', () => {
+          expect(wrapper.emitted('input-field')).toEqual([
+            [
+              {
+                name: fieldName,
+                value: expectedValue,
+              },
+            ],
+          ]);
+        });
+      }
+    );
+  });
+
+  describe('with scoped slot', () => {
+    beforeEach(() => {
+      createComponent(
+        {
+          values: {
+            evenCount: 5,
+          },
+        },
+        {
+          scopedSlots: {
+            'input(evenCount)':
+              '<button data-testid="test-custom-input" @click="props.input(props.value + 1)" @blur="props.blur">{{ props.value }}</button>',
+          },
+        }
+      );
+    });
+
+    it('renders scoped slot for field input', () => {
+      expect(findInputFromLabel(TEST_FIELDS.evenCount.label).exists()).toBe(false);
+      expect(findCustomInputFromLabel(TEST_FIELDS.evenCount.label).exists()).toBe(true);
+    });
+
+    it('passes down "blur" callback', async () => {
+      // what: We'll test this by emitting the "blur" we attached in the scopedSlot
+      //       and asserting that validation was ran.
+      expect(
+        findFormGroupFromLabel(TEST_FIELDS.evenCount.label).attributes('invalid-feedback')
+      ).toBe('');
+
+      findCustomInputFromLabel(TEST_FIELDS.evenCount.label).trigger('blur');
+      await nextTick();
+
+      expect(
+        findFormGroupFromLabel(TEST_FIELDS.evenCount.label).attributes('invalid-feedback')
+      ).toBe('Count must be even');
+    });
+
+    it('passes down "input" callback', () => {
+      // what: We'll test this by checking that the input-field event
+      //       is emitted when triggered by our scoped slot.
+      expect(wrapper.emitted('input-field')).toBeUndefined();
+
+      findCustomInputFromLabel(TEST_FIELDS.evenCount.label).trigger('click');
+
+      expect(wrapper.emitted('input-field')).toEqual([[{ name: 'evenCount', value: 6 }]]);
+    });
+
+    it('passes down "value"', () => {
+      expect(findCustomInputFromLabel(TEST_FIELDS.evenCount.label).text()).toEqual('5');
+    });
+  });
+
+  // why: We have to do some manual reactivity to optimize how often we call
+  //      field validators. Let's test that here.
+  describe('validation performance', () => {
+    let validationSpy;
+
+    beforeEach(async () => {
+      validationSpy = jest.fn().mockReturnValue('Not valid!');
+
+      createComponent({
+        fields: mapValues(TEST_FIELDS, (field) => ({
+          ...field,
+          validators: [validationSpy],
+        })),
+      });
+
+      // Trigger validation on all fields so that the fields are "dirty"
+      await submitForm();
+
+      // Clear validationSpy so we can assert on *new* validation calls
+      validationSpy.mockClear();
+    });
+
+    it('when input changes, only triggers validation for changed value', async () => {
+      expect(validationSpy).not.toHaveBeenCalled();
+
+      wrapper.setProps({ values: { username: 'root' } });
+      await nextTick();
+
+      expect(validationSpy).toHaveBeenCalledTimes(1);
+      expect(validationSpy).toHaveBeenCalledWith('root');
+    });
+  });
+});

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

@@ -0,0 +1,102 @@
+import uniqueId from 'lodash/uniqueId';
+import omit from 'lodash/omit';
+import GlModal from '../../modal/modal.vue';
+import GlButton from '../../button/button.vue';
+import GlListbox from '../../new_dropdowns/listbox/listbox.vue';
+import GlFormFields from './form_fields.vue';
+import readme from './form_fields.md';
+import { required } from './validators';
+import { mapToNumber } from './mappers';
+
+const Template = () => ({
+  ITEMS: ['Pizza', 'Keyboards', 'Guitars', 'Rocket ships'].map((text) => ({ text, value: text })),
+  components: { GlFormFields, GlButton, GlModal, GlListbox },
+  data() {
+    return {
+      // why: We declare fields here so that we can test what binding the
+      //      "confirmPassword" validator to "this.formValues" would act
+      //      like. In most cases, these can be constant and injected through
+      //      `$options`.
+      fields: {
+        USERNAME: {
+          label: 'NAME (ALL CAPS)',
+          mapValue: (x) => x?.toUpperCase(),
+          validators: [required('NAME IS REQUIRED!!!')],
+        },
+        password: {
+          label: 'Password',
+          inputAttrs: { type: 'password' },
+          validators: [required('Password is required')],
+        },
+        confirmPassword: {
+          label: 'Confirm Password',
+          inputAttrs: { type: 'password' },
+          validators: [
+            required('Confirmed password is required'),
+            (confirmValue) =>
+              confirmValue !== this.formValues.password ? 'Must match password' : '',
+          ],
+        },
+        custom: {
+          label: 'Custom input',
+          mapValue: mapToNumber,
+          validators: [(val) => (val < 1 ? 'Please click this at least once :)' : '')],
+        },
+        favoriteItem: {
+          label: 'Favorite Item (Optional)',
+        },
+      },
+      formValues: {},
+      testFormId: uniqueId('form_fields_story_'),
+    };
+  },
+  computed: {
+    values() {
+      return omit(this.formValues, ['confirmPassword']);
+    },
+    valuesJSON() {
+      // JSON doesn't allow undefined values
+      return JSON.stringify(this.values, (key, value) => (value === undefined ? null : value), 2);
+    },
+  },
+  methods: {
+    onSubmit() {
+      this.$refs.modal.show();
+    },
+  },
+  template: `
+    <div>
+      <h3>Fields</h3>
+      <form :id="testFormId" @submit.prevent>
+        <gl-form-fields :fields="fields" v-model="formValues" :form-id="testFormId" @submit="onSubmit">
+          <template #input(custom)="{ id, value, input, blur }">
+            <button :id="id" @click="input(value + 1)" @blur="blur" type="button">{{value}}</button>
+          </template>
+          <template #input(favoriteItem)="{ id, value, input, blur }">
+            <gl-listbox :id="id" :items="$options.ITEMS" :selected="value" @select="input" @hidden="blur" />
+          </template>
+        </gl-form-fields>
+        <gl-button type="submit" category="primary">Submit</gl-button>
+      </form>
+      <gl-modal ref="modal" modal-id="submission-modal" title="Form submission"><pre>{{ valuesJSON }}</pre></gl-modal>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export default {
+  title: 'base/form/form-fields',
+  component: GlFormFields,
+  parameters: {
+    knobs: {
+      disable: true,
+    },
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+  argTypes: {},
+};

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/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';