@gitlab/duo-ui 0.1.0

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

@@ -0,0 +1,258 @@
+<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 { setObjectProperty } from '../../../../utils/set_utils';
+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} groupAttrs - Properties that are passed to the group wrapping 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,
+    },
+    /**
+     * Validation errors from the server. Generally passed to the component after making an API call.
+     */
+    serverValidations: {
+      type: Object,
+      required: false,
+      default() {
+        return {};
+      },
+    },
+  },
+  data() {
+    return {
+      fieldDirtyStatuses: {},
+      fieldValidations: {},
+    };
+  },
+  computed: {
+    formElement() {
+      return document.getElementById(this.formId);
+    },
+    fieldValidationProps() {
+      return mapValues(this.fields, (_, fieldName) => {
+        const invalidFeedback =
+          this.serverValidations[fieldName] || 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 inputSlotName = `input(${fieldName})`;
+        const groupPassthroughSlotName = `group(${fieldName})-`;
+        const afterSlotName = `after(${fieldName})`;
+
+        const inputSlot = {
+          slotName: inputSlotName,
+          attrs: {
+            value: this.fieldValues[fieldName],
+            input: (val) => this.onFieldInput(fieldName, val),
+            blur: () => this.onFieldBlur(fieldName),
+            validation: this.fieldValidationProps[fieldName],
+            id,
+          },
+        };
+
+        const groupPassthroughSlots = Object.keys(this.$scopedSlots)
+          .filter((slotName) => slotName.startsWith(groupPassthroughSlotName))
+          .map((slotName) => {
+            const childSlotName = slotName.replace(groupPassthroughSlotName, '');
+
+            return {
+              slotName,
+              childSlotName,
+            };
+          });
+
+        return {
+          ...field,
+          id,
+          label: field.label || fieldName,
+          inputSlot,
+          groupPassthroughSlots,
+          afterSlotName,
+        };
+      });
+    },
+  },
+  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.fieldDirtyStatuses = setObjectProperty(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.fieldValidations = setObjectProperty(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>
+    <template v-for="(field, fieldName) in fieldsToRender">
+      <!-- eslint-disable-next-line vue/valid-v-for -->
+      <gl-form-group
+        v-bind="field.groupAttrs"
+        :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-for="{ slotName, childSlotName } in field.groupPassthroughSlots"
+          #[childSlotName]
+        >
+          <!-- @slot Can be used to pass slots to `GlFormGroup`. -->
+          <slot :name="slotName"></slot>
+        </template>
+        <!-- @slot Scoped slot that can be used for components other than `GlFormInput`. The name of the slot is `input(<fieldName>)`. -->
+        <slot :name="field.inputSlot.slotName" v-bind="field.inputSlot.attrs">
+          <gl-form-input
+            :id="field.id"
+            :value="fieldValues[fieldName]"
+            :state="fieldValidationProps[fieldName].state"
+            v-bind="field.inputAttrs"
+            @input="onFieldInput(fieldName, $event)"
+            @blur="onFieldBlur(fieldName)"
+          />
+        </slot>
+      </gl-form-group>
+      <!-- @slot Can be used to add content the form group of a field. The name of the slot is `after(<fieldName>)`.-->
+      <slot :name="field.afterSlotName"></slot>
+    </template>
+  </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/validators.js

@@ -0,0 +1,49 @@
+import emojiRegex from 'emoji-regex';
+
+const EMOJI_REGEX = emojiRegex();
+
+// 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 : '');
+
+/**
+ * Validator function to check if a string is present and non-empty.
+ *
+ * Returns an empty string if the input contains a valid string.
+ *
+ * Returns `failMessage` if the input string is empty, null, or undefined.
+ * @param {string} failMessage - The error message to be returned when validation fails.
+ * @returns {Function} A validation function that returns either `failMessage` or empty string.
+ */
+export const required = (failMessage) =>
+  factory(failMessage, (val) => val !== '' && val !== null && val !== undefined);
+
+/**
+ * Validator function to check if a string contains any emojis.
+ *
+ * Returns an empty string if the input is empty, null, or undefined, or if no emoji is present.
+ *
+ * Returns `failMessage` if the input string contains at least one emoji.
+ * @param {string} failMessage - The error message to be returned when validation fails.
+ * @returns {Function} A validation function that returns either `failMessage` or empty string.
+ */
+export const noEmojis = (failMessage) =>
+  factory(failMessage, (val) => {
+    if (!val || typeof val !== 'string') {
+      return true;
+    }
+
+    const resultsLength = val.match(EMOJI_REGEX)?.length ?? 0;
+
+    return resultsLength < 1;
+  });

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

@@ -0,0 +1 @@
+Form group adds structure to forms.

package/src/components/base/form/form_group/form_group.scss

@@ -0,0 +1,59 @@
+.gl-form-group {
+  @apply gl-mb-5;
+
+  .col-form-label {
+    @apply gl-text-base;
+    @apply gl-font-bold;
+    @apply gl-leading-normal;
+    @apply gl-pt-0;
+    @apply gl-pb-3;
+    color: var(--gl-text-color-strong);
+
+    > .label-description {
+      @apply gl-mt-3;
+      color: var(--gl-text-color-subtle);
+    }
+  }
+
+  .optional-label,
+  .label-description {
+    @apply gl-font-normal;
+  }
+
+  .invalid-feedback {
+    color: var(--gl-control-text-color-error);
+  }
+
+  .valid-feedback {
+    color: var(--gl-control-text-color-valid);
+  }
+
+  .invalid-feedback,
+  .valid-feedback,
+  .text-muted,
+  .gl-text-secondary {
+    @apply gl-text-base;
+    @apply gl-leading-normal;
+  }
+
+  .text-muted {
+    @apply gl-text-subtle #{!important};
+  }
+
+  .form-control {
+    + .invalid-feedback,
+    + .valid-feedback,
+    + .gl-text-secondary,
+    + .text-muted,
+    &.is-valid + .invalid-feedback + .text-muted,
+    &.is-valid + .invalid-feedback + .gl-text-secondary {
+      // See https://gitlab.com/gitlab-org/gitlab-ui/-/merge_requests/2806
+      // for the reasoning behind the "valid+invalid" selector above
+      @apply gl-mt-3;
+    }
+  }
+
+  legend {
+    border-bottom: 0;
+  }
+}

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

@@ -0,0 +1,76 @@
+<script>
+import isString from 'lodash/isString';
+import isPlainObject from 'lodash/isPlainObject';
+import { BFormGroup } from '../../../../vendor/bootstrap-vue/src/components/form-group/form-group';
+
+export default {
+  name: 'GlFormGroup',
+  components: {
+    BFormGroup,
+  },
+  inheritAttrs: false,
+  props: {
+    labelClass: {
+      type: [String, Array, Object],
+      required: false,
+      default: null,
+    },
+    labelDescription: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    optional: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    optionalText: {
+      type: String,
+      required: false,
+      default: '(optional)',
+    },
+  },
+  computed: {
+    actualLabelClass() {
+      const { labelClass } = this;
+      const defaultClass = 'col-form-label';
+
+      if (isString(labelClass)) {
+        return `${labelClass} ${defaultClass}`;
+      }
+      if (Array.isArray(labelClass)) {
+        return [...labelClass, defaultClass];
+      }
+      if (isPlainObject(labelClass)) {
+        return { ...labelClass, [defaultClass]: true };
+      }
+      return defaultClass;
+    },
+    hasLabelDescription() {
+      // eslint-disable-next-line @gitlab/vue-prefer-dollar-scopedslots
+      return Boolean(this.labelDescription || this.$slots['label-description']);
+    },
+  },
+};
+</script>
+<template>
+  <b-form-group v-bind="$attrs" class="gl-form-group" :label-class="actualLabelClass">
+    <template #label>
+      <slot name="label">
+        {{ $attrs.label }}
+        <span v-if="optional" class="optional-label" data-testid="optional-label">{{
+          optionalText
+        }}</span>
+      </slot>
+      <div v-if="hasLabelDescription" data-testid="label-description" class="label-description">
+        <slot name="label-description">{{ labelDescription }}</slot>
+      </div>
+    </template>
+
+    <!-- eslint-disable-next-line @gitlab/vue-prefer-dollar-scopedslots -->
+    <template v-for="slot in Object.keys($slots)" #[slot]>
+      <slot :name="slot"></slot>
+    </template>
+  </b-form-group>
+</template>

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

@@ -0,0 +1 @@
+General user input to be used in forms.

package/src/components/base/form/form_input/form_input.scss

@@ -0,0 +1,74 @@
+.gl-form-input,
+.gl-form-input.form-control {
+  @apply gl-font-regular;
+  @apply gl-text-base;
+  @apply gl-leading-normal;
+  @apply gl-py-3;
+  @apply gl-px-4;
+  @apply gl-h-auto;
+  @apply gl-border-none;
+  @include form-control-focus($ignore-warning: true);
+  appearance: none;
+  background: var(--gl-control-background-color-default);
+  color: var(--gl-text-color-default);
+  box-shadow: inset 0 0 0 $gl-border-size-1 var(--gl-control-border-color-default);
+
+  @media (forced-colors: active) {
+    border: 1px solid;
+  }
+
+  &:hover {
+    box-shadow: inset 0 0 0 $gl-border-size-1 var(--gl-control-border-color-hover);
+  }
+
+  &:read-only,
+  &:not(:disabled):not(.form-control-plaintext):not([type='color']):read-only {
+    background: var(--gl-control-background-color-readonly);
+    box-shadow: none;
+  }
+
+  &:disabled {
+    @apply gl-cursor-not-allowed;
+    background: var(--gl-control-background-color-disabled);
+    box-shadow: inset 0 0 0 $gl-border-size-1 var(--gl-control-border-color-disabled);
+    color: var(--gl-text-color-disabled);
+  }
+
+  &:not(.form-control-plaintext):focus {
+    @include gl-focus($color: var(--gl-control-border-color-focus));
+    background: var(--gl-control-background-color-default);
+    color: var(--gl-text-color-default);
+  }
+
+  &.is-invalid {
+    box-shadow: inset 0 0 0 $gl-border-size-1 var(--gl-control-border-color-error);
+
+    &:focus {
+      @include gl-focus($color: var(--gl-control-border-color-error));
+    }
+  }
+
+  &::placeholder {
+    color: var(--gl-control-placeholder-color);
+  }
+
+  &.form-control-plaintext {
+    @apply gl-shadow-none;
+  }
+}
+
+@each $name, $size in $gl-form-input-sizes {
+  .gl-form-input-#{$name} {
+    max-width: $size;
+  }
+
+  @each $breakpointName, $breakpointSize in $gl-form-input-sizes {
+    @if $breakpointName != xs {
+      .gl-#{$breakpointName}-form-input-#{$name} {
+        @include gl-media-breakpoint-up($breakpointName) {
+          max-width: $size;
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,98 @@
+<script>
+import isObject from 'lodash/isObject';
+import { BFormInput } from '../../../../vendor/bootstrap-vue/src/components/form-input/form-input';
+
+import { formInputWidths } from '../../../../utils/constants';
+
+const MODEL_PROP = 'value';
+const MODEL_EVENT = 'input';
+
+export default {
+  name: 'GlFormInput',
+  components: {
+    BFormInput,
+  },
+  inheritAttrs: false,
+  model: {
+    prop: MODEL_PROP,
+    event: MODEL_EVENT,
+  },
+  props: {
+    /**
+     * Maximum width of the input
+     */
+    width: {
+      type: [String, Object],
+      required: false,
+      default: null,
+      validator: (value) => {
+        const widths = isObject(value) ? Object.values(value) : [value];
+
+        return widths.every((width) => Object.values(formInputWidths).includes(width));
+      },
+    },
+  },
+  computed: {
+    cssClasses() {
+      if (this.width === null) {
+        return [];
+      }
+
+      if (isObject(this.width)) {
+        const { default: defaultWidth, ...nonDefaultWidths } = this.width;
+
+        return [
+          // eslint-disable-next-line @gitlab/tailwind -- Not a CSS utility
+          ...(defaultWidth ? [`gl-form-input-${defaultWidth}`] : []),
+          ...Object.entries(nonDefaultWidths).map(
+            // eslint-disable-next-line @gitlab/tailwind -- Not a CSS utility
+            ([breakpoint, width]) => `gl-${breakpoint}-form-input-${width}`
+          ),
+        ];
+      }
+
+      // eslint-disable-next-line @gitlab/tailwind -- Not a CSS utility
+      return [`gl-form-input-${this.width}`];
+    },
+    listeners() {
+      return {
+        ...this.$listeners,
+        // Swap purpose of input and update events from underlying BFormInput.
+        // See https://gitlab.com/gitlab-org/gitlab-ui/-/issues/631.
+        input: (...args) => {
+          /**
+           * Emitted to update the v-model
+           *
+           * @event update
+           * @property {string} value new value
+           */
+          this.$emit('update', ...args);
+        },
+        update: (...args) => {
+          /**
+           * Triggered by user interaction. Emitted after any formatting (not including 'trim' or 'number' props).
+           * Useful for getting the currently entered value when the 'debounce' or 'lazy' props are set.
+           *
+           * @event input
+           * @property {string} value new value
+           */
+          this.$emit(MODEL_EVENT, ...args);
+        },
+      };
+    },
+    noWheel() {
+      return this.$attrs.type === 'number';
+    },
+  },
+};
+</script>
+
+<template>
+  <b-form-input
+    class="gl-form-input"
+    :class="cssClasses"
+    :no-wheel="noWheel"
+    v-bind="$attrs"
+    v-on="listeners"
+  />
+</template>

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

@@ -0,0 +1,67 @@
+The `GlFormInputGroup` component allows one to build more advanced text
+input fields than generic `GlFormInput` when one needs that flexibility.
+Basic usage of the component:
+
+```html
+<div>
+  <gl-form-input-group>
+    <template #prepend>
+      <!-- Content to prepend your text input field -->
+    </template>
+    <template #append>
+      <!-- Content to append your text input field -->
+    </template>
+  </gl-form-input-group>
+</div>
+```
+
+One can use any other component (custom or `<gl-*>`) in both slots or
+not to use the slots at all. In the latter, the component will fallback
+to simple `GlFormInput`.
+
+## Predefined options
+
+Sometimes custom text input from the user isn't desired. Instead, the
+user should pick one of the predefined options that will automatically
+populate the input field. Typically, such cases will also include an
+actionable button (like **Copy**) put into the `append` slot.
+
+To achieve this effect, the `GlFormInputGroup` component accepts an
+array of options in the form of `predefinedOptions` param. For example:
+
+```javascript
+const optionValues = [
+  { name: 'Option #1', value: 'Option #1 is selected!' },
+  { name: 'Option #2', value: 'Option #2 is selected!' },
+];
+...
+<gl-form-input-group :predefined-options="optionValues" />
+```
+
+This will tell `GlFormInputGroup` to render a dropdown in the `prepend`
+slot with all of the supplied options' `name`s. When one of the options
+is selected, the input field is automatically populated with the
+option's `value`. Check the "Examples" section below for "With
+predefined options" example.
+
+### Pro tips
+
+Read some useful tips below about specific usage of the component.
+
+### Readonly input
+
+Often you want to make sure user doesn't mess up the predefined content
+pasted into the input field. In this case, you can set `readonly`
+param to `true`. You can play with `Readonly` knob on the right.
+
+### Preselect the text to copy
+
+If you set the `readonly` param on the `GlFormInputGroup` component,
+users will still be able to manually select the text and copy it.
+However, it's more user-friendly to preselect the text for the users if
+they click anywhere in the input field. This can be achieved by setting
+the `select-on-click` param to `true`. You can play with
+`Select text on click` knob on the right. Even better, try enabling
+`Readonly`, `Select text on click`, and `Switch to predefined input`
+altogether. And, probably, remove `Prepend text`. Or leave it. It's your
+call. :)