From 58ef983848b34673fc335bbacf1b013f66abdde9 Mon Sep 17 00:00:00 2001
From: Makito <i@maki.to>
Date: Thu, 14 Mar 2024 15:09:10 +0800
Subject: [PATCH] feat(entities-plugins): support field grouping (#1224)

---
 .../forms/src/generator/FormGenerator.vue     |  98 ++++++++++++--
 .../entities-plugins/docs/plugin-form.md      |   6 +
 .../sandbox/pages/PluginFormPage.vue          |   2 +
 .../src/components/PluginEntityForm.vue       |  27 ++--
 .../src/components/PluginForm.cy.ts           |  76 +++++++++++
 .../src/components/PluginForm.vue             |   3 +-
 .../src/composables/useSchemas.ts             | 125 +++++++++++++++---
 .../entities-plugins/src/locales/en.json      |   5 +
 .../entities-plugins/src/types/plugin-form.ts |   2 +
 9 files changed, 303 insertions(+), 41 deletions(-)

diff --git a/packages/core/forms/src/generator/FormGenerator.vue b/packages/core/forms/src/generator/FormGenerator.vue
index 9d434ec381..3fcc3996ad 100644
--- a/packages/core/forms/src/generator/FormGenerator.vue
+++ b/packages/core/forms/src/generator/FormGenerator.vue
@@ -1,14 +1,89 @@
-<template lang="pug">
-div.vue-form-generator(v-if='schema != null')
-  fieldset(v-if="schema.fields", :is='tag')
-    template(v-for='field in fields')
-      form-group(v-if='fieldVisible(field)', ref="children", :vfg="vfg", :field="field", :errors="errors", :model="model", :options="options", @validated="onFieldValidated", @model-updated="onModelUpdated")
-
-  template(v-for='group in groups')
-    fieldset(:is='tag', :class='getFieldRowClasses(group)')
-      legend(v-if='group.legend') {{ group.legend }}
-      template(v-for='field in group.fields')
-        form-group(v-if='fieldVisible(field)', ref="children", :vfg="vfg", :field="field", :errors="errors", :model="model", :options="options", @validated="onFieldValidated", @model-updated="onModelUpdated")
+<template>
+  <div
+    v-if="schema != null"
+    class="vue-form-generator"
+  >
+    <component
+      :is="tag"
+      v-if="schema.fields"
+    >
+      <template
+        v-for="field in fields"
+        :key="field.model"
+      >
+        <form-group
+          v-if="fieldVisible(field)"
+          ref="children"
+          :errors="errors"
+          :field="field"
+          :model="model"
+          :options="options"
+          :vfg="vfg"
+          @model-updated="onModelUpdated"
+          @validated="onFieldValidated"
+        />
+      </template>
+    </component>
+
+    <template
+      v-for="(group, i) in groups"
+      :key="`group-${i}`"
+    >
+      <KCollapse
+        v-if="group.collapsible"
+        :model-value="group.collapsedByDefault === undefined ? false : group.collapsedByDefault"
+        :title="group.legend"
+      >
+        <component
+          :is="tag"
+          :class="getFieldRowClasses(group)"
+        >
+          <template
+            v-for="field in group.fields"
+            :key="field.model"
+          >
+            <form-group
+              v-if="fieldVisible(field)"
+              ref="children"
+              :errors="errors"
+              :field="field"
+              :model="model"
+              :options="options"
+              :vfg="vfg"
+              @model-updated="onModelUpdated"
+              @validated="onFieldValidated"
+            />
+          </template>
+        </component>
+      </KCollapse>
+
+      <component
+        :is="tag"
+        v-else
+        :class="getFieldRowClasses(group)"
+      >
+        <legend v-if="group.legend">
+          {{ group.legend }}
+        </legend>
+        <template
+          v-for="field in group.fields"
+          :key="field.model"
+        >
+          <form-group
+            v-if="fieldVisible(field)"
+            ref="children"
+            :errors="errors"
+            :field="field"
+            :model="model"
+            :options="options"
+            :vfg="vfg"
+            @model-updated="onModelUpdated"
+            @validated="onFieldValidated"
+          />
+        </template>
+      </component>
+    </template>
+  </div>
 </template>
 
 <script>
@@ -16,6 +91,7 @@ import { get as objGet, forEach, isFunction, isNil, isArray } from 'lodash'
 import formMixin from './FormMixin.vue'
 import formGroup from './FormGroup.vue'
 import { ref } from 'vue'
+
 export default {
   name: 'FormGenerator',
   components: { formGroup },
diff --git a/packages/entities/entities-plugins/docs/plugin-form.md b/packages/entities/entities-plugins/docs/plugin-form.md
index 8f37f52eea..64599c4d26 100644
--- a/packages/entities/entities-plugins/docs/plugin-form.md
+++ b/packages/entities/entities-plugins/docs/plugin-form.md
@@ -91,6 +91,12 @@ A form component for Plugins.
     - default: `false`
     - *Specific to Kong Manager*. Whether or not to hide the consumer group scope field.
 
+  - `groupFields`:
+    - type: `boolean`
+    - required: `false`
+    - default: `false`
+    - Whether to enable grouping for required and advanced (optional) fields.
+
 The base konnect or kongManger config.
 
 #### `pluginType`
diff --git a/packages/entities/entities-plugins/sandbox/pages/PluginFormPage.vue b/packages/entities/entities-plugins/sandbox/pages/PluginFormPage.vue
index a4272e2451..8b4845608f 100644
--- a/packages/entities/entities-plugins/sandbox/pages/PluginFormPage.vue
+++ b/packages/entities/entities-plugins/sandbox/pages/PluginFormPage.vue
@@ -51,6 +51,7 @@ const konnectConfig = ref<KonnectPluginFormConfig>({
   backRoute: { name: 'select-plugin' },
   cancelRoute: { name: 'home' },
   jsonYamlFormsEnabled: true,
+  groupFields: true,
 })
 
 const kongManagerConfig = ref<KongManagerPluginFormConfig>({
@@ -62,6 +63,7 @@ const kongManagerConfig = ref<KongManagerPluginFormConfig>({
   // entityId: '123-abc-i-lover-cats',
   backRoute: { name: 'select-plugin' },
   cancelRoute: { name: 'home' },
+  groupFields: true,
 })
 
 const onUpdate = (payload: Record<string, any>) => {
diff --git a/packages/entities/entities-plugins/src/components/PluginEntityForm.vue b/packages/entities/entities-plugins/src/components/PluginEntityForm.vue
index 75418dca2f..458e128d2d 100644
--- a/packages/entities/entities-plugins/src/components/PluginEntityForm.vue
+++ b/packages/entities/entities-plugins/src/components/PluginEntityForm.vue
@@ -31,23 +31,23 @@
 </template>
 
 <script lang="ts">
-import { computed, ref, reactive, provide, watch, type PropType, onBeforeMount, defineComponent } from 'vue'
-import type { AxiosResponse, AxiosRequestConfig } from 'axios'
-import {
-  type PluginEntityInfo,
-  type KonnectPluginFormConfig,
-  type KongManagerPluginFormConfig,
-} from '../types'
 import { useAxios, useHelpers } from '@kong-ui-public/entities-shared'
 import {
+  FORMS_API_KEY,
   customFields,
   getSharedFormName,
-  FORMS_API_KEY,
   sharedForms,
 } from '@kong-ui-public/forms'
 import '@kong-ui-public/forms/dist/style.css'
+import type { AxiosRequestConfig, AxiosResponse } from 'axios'
+import { computed, defineComponent, onBeforeMount, provide, reactive, ref, watch, type PropType } from 'vue'
 import composables from '../composables'
 import endpoints from '../plugins-endpoints'
+import {
+  type KongManagerPluginFormConfig,
+  type KonnectPluginFormConfig,
+  type PluginEntityInfo,
+} from '../types'
 
 // Must explicitly specify these as components since they are rendered dynamically
 export default defineComponent({
@@ -120,7 +120,9 @@ const { axiosInstance } = useAxios({
   headers: props.config.requestHeaders,
 })
 
-const { parseSchema } = composables.useSchemas(props.entityMap.focusedEntity?.id || undefined)
+const { parseSchema } = composables.useSchemas(props.entityMap.focusedEntity?.id || undefined, {
+  groupFields: props.config.groupFields,
+})
 const { convertToDotNotation, unFlattenObject, isObjectEmpty, unsetNullForeignKey } = composables.usePluginHelpers()
 
 const { objectsAreEqual } = useHelpers()
@@ -616,7 +618,12 @@ onBeforeMount(() => {
   }
 
   :deep(.vue-form-generator) {
-    & > fieldset {
+    .k-collapse:not(:last-child) {
+      border-bottom: $kui-border-width-10 solid $kui-color-border;
+      margin-bottom: $kui-space-80;
+    }
+
+    fieldset {
       border: none;
       padding: $kui-space-0;
     }
diff --git a/packages/entities/entities-plugins/src/components/PluginForm.cy.ts b/packages/entities/entities-plugins/src/components/PluginForm.cy.ts
index 41f008f29c..4ca9b6434b 100644
--- a/packages/entities/entities-plugins/src/components/PluginForm.cy.ts
+++ b/packages/entities/entities-plugins/src/components/PluginForm.cy.ts
@@ -220,6 +220,82 @@ describe('<PluginForm />', () => {
       cy.get('#config-private_network').should('be.visible')
     })
 
+    it.only('should show common, required, and advanced fields when groupFields is true', () => {
+      interceptKMSchema({ mockData: schema2 })
+
+      cy.mount(PluginForm, {
+        global: { components: { VueFormGenerator } },
+        props: {
+          config: {
+            ...baseConfigKM,
+            groupFields: true,
+          },
+          pluginType: 'mocking',
+        },
+        router,
+      })
+
+      cy.wait('@getPluginSchema')
+      cy.get('.kong-ui-entities-plugin-form-container').should('be.visible')
+
+      // button state
+      cy.getTestId('form-submit').should('be.visible')
+      cy.getTestId('form-submit').should('be.enabled')
+      cy.getTestId('form-back').should('be.visible')
+      cy.getTestId('form-back').should('be.enabled')
+      cy.getTestId('form-cancel').should('be.visible')
+
+      // scope fields
+      cy.get('.field-selectionGroup').should('be.visible')
+      cy.get('.Global-check').should('be.visible')
+      cy.get('.Scoped-check').should('be.visible')
+      cy.get('.field-selectionGroup').find('.field-AutoSuggest').should('not.be.visible')
+      cy.get('.Scoped-check input').click()
+      cy.get('.field-selectionGroup').find('.field-AutoSuggest').should('be.visible')
+      cy.get('#service-id').should('be.visible')
+      cy.get('#route-id').should('be.visible')
+
+      cy.getTestId('k-collapse-title')
+        .contains('Common Fields')
+        .parents('.k-collapse')
+        .first()
+        .as('commonFields')
+
+      cy.getTestId('k-collapse-title')
+        .contains('Required Fields')
+        .parents('.k-collapse')
+        .first()
+        .as('requiredFields')
+
+      cy.getTestId('k-collapse-title')
+        .contains('Advanced Fields')
+        .parents('.k-collapse')
+        .first()
+        .as('advancedFields')
+
+      // common fields
+      cy.get('@commonFields').find('#enabled').should('exist')
+      cy.get('@commonFields').find('#instance_name').should('exist')
+      cy.get('@commonFields').find('#tags').should('exist')
+      cy.get('@commonFields').find('.plugin-protocols-select').should('be.visible')
+
+      // required fields
+      cy.get('@requiredFields').find('#config-include_base_path').should('be.visible')
+      cy.get('@requiredFields').find('#config-random_status_code').should('be.visible')
+
+      // advanced fields should be hidden by default
+      cy.get('@advancedFields').findTestId('k-collapse-hidden-content').should('be.hidden')
+
+      // reveal them
+      cy.get('@advancedFields').findTestId('k-collapse-trigger-content').click()
+      cy.get('@advancedFields').findTestId('k-collapse-hidden-content').should('be.visible')
+
+      // advanced fields
+      cy.get('@advancedFields').find('#config-api_specification').should('be.visible')
+      cy.get('@advancedFields').find('#config-api_specification_filename').should('be.visible')
+      cy.get('@advancedFields').find('#config-included_status_codes').should('be.visible')
+    })
+
     it('should hide scope selection when hideScopeSelection is true', () => {
       interceptKMSchema()
 
diff --git a/packages/entities/entities-plugins/src/components/PluginForm.vue b/packages/entities/entities-plugins/src/components/PluginForm.vue
index 925eb9087a..119069238b 100644
--- a/packages/entities/entities-plugins/src/components/PluginForm.vue
+++ b/packages/entities/entities-plugins/src/components/PluginForm.vue
@@ -243,7 +243,7 @@ const props = defineProps({
 const router = useRouter()
 const { i18n: { t } } = composables.useI18n()
 const { pluginMetaData, credentialMetaData, credentialSchemas } = composables.usePluginMetaData()
-const { customSchemas, typedefs } = composables.useSchemas(undefined, props.config.app)
+const { customSchemas, typedefs } = composables.useSchemas(undefined, { app: props.config.app })
 const { getMessageFromError } = useErrors()
 const { capitalize } = useStringHelpers()
 const { objectsAreEqual } = useHelpers()
@@ -512,6 +512,7 @@ const buildFormSchema = (parentKey: string, response: Record<string, any>, initi
 
     initialFormSchema[field] = { id: field } // each field's key will be set as the id
     initialFormSchema[field].type = scheme.type === 'boolean' ? 'checkbox' : 'input'
+    initialFormSchema[field].required = scheme.required
 
     if (field.startsWith('config-')) {
       initialFormSchema[field].label = formatPluginFieldLabel(field)
diff --git a/packages/entities/entities-plugins/src/composables/useSchemas.ts b/packages/entities/entities-plugins/src/composables/useSchemas.ts
index 4a176c13eb..d5eb7d60a1 100644
--- a/packages/entities/entities-plugins/src/composables/useSchemas.ts
+++ b/packages/entities/entities-plugins/src/composables/useSchemas.ts
@@ -1,35 +1,68 @@
-import type { CustomSchemas } from '../types'
 import { useStringHelpers } from '@kong-ui-public/entities-shared'
 import { customFields } from '@kong-ui-public/forms'
-import usePluginHelpers from './usePluginHelpers'
+import type { CustomSchemas } from '../types'
+import { aiPromptDecoratorSchema } from './plugin-schemas/AIPromptDecorator'
+import { aiPromptTemplateSchema } from './plugin-schemas/AIPromptTemplate'
 import { applicationRegistrationSchema } from './plugin-schemas/ApplicationRegistration'
+import { ArrayStringFieldSchema } from './plugin-schemas/ArrayStringFieldSchema'
 import { dataDogSchema } from './plugin-schemas/Datadog'
-import { statsDAdvancedSchema } from './plugin-schemas/StatsDAdvanced'
-import { kafkaSchema } from './plugin-schemas/Kafka'
+import { graphqlRateLimitingAdvancedSchema } from './plugin-schemas/GraphQLRateLimitingAdvanced'
 import { jwtSchema } from './plugin-schemas/JWT'
+import { kafkaSchema } from './plugin-schemas/Kafka'
 import { mockingSchema } from './plugin-schemas/Mocking'
 import { preFunctionSchema } from './plugin-schemas/PreFunction'
 import { rateLimitingSchema } from './plugin-schemas/RateLimiting'
 import { requestTransformerAdvancedSchema } from './plugin-schemas/RequestTransformerAdvanced'
+import RequestValidatorSchema from './plugin-schemas/RequestValidator'
 import { routeByHeaderSchema } from './plugin-schemas/RouteByHeader'
-import { aiPromptDecoratorSchema } from './plugin-schemas/AIPromptDecorator'
-import { aiPromptTemplateSchema } from './plugin-schemas/AIPromptTemplate'
-import { graphqlRateLimitingAdvancedSchema } from './plugin-schemas/GraphQLRateLimitingAdvanced'
-import { statsDSchema } from './plugin-schemas/StatsD'
 import { samlSchema } from './plugin-schemas/SAML'
+import { statsDSchema } from './plugin-schemas/StatsD'
+import { statsDAdvancedSchema } from './plugin-schemas/StatsDAdvanced'
 import { vaultAuthSchema } from './plugin-schemas/VaultAuth'
-import { ArrayStringFieldSchema } from './plugin-schemas/ArrayStringFieldSchema'
-import RequestValidatorSchema from './plugin-schemas/RequestValidator'
 import ZipkinSchema from './plugin-schemas/Zipkin'
 import typedefs from './plugin-schemas/typedefs'
+import useI18n from './useI18n'
+import usePluginHelpers from './usePluginHelpers'
+
+export interface Field extends Record<string, any>{
+  model: string
+  required?: boolean
+  styleClasses?: string
+}
+
+export interface Group {
+  legend?: string
+  fields?: Field[]
+  collapsible?: boolean
+  /**
+   * Whether the group is collapsed by default
+   * @default false
+   */
+  collapsedByDefault?: boolean
+}
+
+export interface Schema {
+  fields?: Field[]
+  groups?: Group[]
+}
+
+export interface UseSchemasOptions {
+  app?: 'konnect' | 'kongManager'
+  groupFields?: boolean
+}
+
+const sortFieldByOrder = (a: Field, b: Field) => (a.order ?? 0) - (b.order ?? 0)
+
+const sortFieldByOrderAndModel = (a: Field, b: Field) => sortFieldByOrder(a, b) || a.model.localeCompare(b.model)
 
 /**
  * @param entityId (optional) The id of the entity associated with the plugin
  * @returns
  */
-export const useSchemas = (entityId?: string, app?: 'konnect' | 'kongManager') => {
+export const useSchemas = (entityId?: string, options?: UseSchemasOptions) => {
   const { capitalize } = useStringHelpers()
   const { convertToDotNotation } = usePluginHelpers()
+  const { i18n: { t } } = useI18n()
 
   const customSchemas: CustomSchemas = {
     'application-registration': {
@@ -104,7 +137,7 @@ export const useSchemas = (entityId?: string, app?: 'konnect' | 'kongManager') =
       ...rateLimitingSchema,
     },
 
-    'rate-limiting-advanced': app === 'kongManager'
+    'rate-limiting-advanced': options?.app === 'kongManager'
       ? {
         'config-consumer_groups': rateLimitingSchema['config-consumer_groups'],
       }
@@ -174,7 +207,7 @@ export const useSchemas = (entityId?: string, app?: 'konnect' | 'kongManager') =
 
     comparatorIdx > -1 && inputSchemaFields.splice(comparatorIdx, 1)
 
-    const formSchema = { fields: [] }
+    let formSchema: Schema = { fields: [] }
     const formModel = {}
 
     // Iterate over each schema field to augment with display configuration.
@@ -182,13 +215,67 @@ export const useSchemas = (entityId?: string, app?: 'konnect' | 'kongManager') =
       buildFormSchema(inputSchema[fieldName], fieldName, inputSchema, formModel, formSchema, frontendSchema)
     })
 
-    // Assume the fields are sorted, unless they have an `order` property
-    formSchema.fields.sort((a: Record<string, any>, b: Record<string, any>) => {
-      a.order = a.order || 0
-      b.order = b.order || 0
+    if (options?.groupFields) {
+      const commonFields = []
+      const requiredFields = []
+      const advancedFields = []
 
-      return a.order - b.order
-    })
+      for (const field of formSchema.fields!) {
+        // Fields that don't start with 'config-' are considered common fields
+        if (!field.model.startsWith('config-')) {
+          commonFields.push(field)
+          continue
+        }
+
+        if (field.required) {
+          requiredFields.push(field)
+          continue
+        }
+
+        advancedFields.push(field)
+      }
+
+      const fieldGroups: Group[] = []
+
+      if (commonFields.length > 0) {
+        fieldGroups.push({
+          legend: t('plugins.form.grouping.common_fields'),
+          fields: commonFields.sort(sortFieldByOrder),
+          collapsible: true,
+          collapsedByDefault: false,
+        })
+      }
+
+      if (requiredFields.length > 0) {
+        fieldGroups.push({
+          legend: t('plugins.form.grouping.required_fields'),
+          fields: requiredFields.sort(sortFieldByOrderAndModel),
+          collapsible: true,
+          collapsedByDefault: false,
+        })
+      }
+
+      if (advancedFields.length > 0) {
+        fieldGroups.push({
+          legend: t('plugins.form.grouping.advanced_fields'),
+          fields: advancedFields.sort(sortFieldByOrderAndModel),
+          collapsible: true,
+          collapsedByDefault: true,
+        })
+      }
+
+      formSchema = {
+        groups: fieldGroups,
+      }
+    } else {
+      // Assume the fields are sorted, unless they have an `order` property
+      formSchema.fields!.sort((a: Record<string, any>, b: Record<string, any>) => {
+        a.order = a.order || 0
+        b.order = b.order || 0
+
+        return a.order - b.order
+      })
+    }
 
     return {
       schema: formSchema,
diff --git a/packages/entities/entities-plugins/src/locales/en.json b/packages/entities/entities-plugins/src/locales/en.json
index 2f2fa03f71..f7ab3ca7f4 100644
--- a/packages/entities/entities-plugins/src/locales/en.json
+++ b/packages/entities/entities-plugins/src/locales/en.json
@@ -526,6 +526,11 @@
           "placeholder": "Select a Consumer Group",
           "plural": "Consumer Groups"
         }
+      },
+      "grouping": {
+        "common_fields": "Common Fields",
+        "required_fields": "Required Fields",
+        "advanced_fields": "Advanced Fields"
       }
     }
   },
diff --git a/packages/entities/entities-plugins/src/types/plugin-form.ts b/packages/entities/entities-plugins/src/types/plugin-form.ts
index 16c1d5351b..48c6197d28 100644
--- a/packages/entities/entities-plugins/src/types/plugin-form.ts
+++ b/packages/entities/entities-plugins/src/types/plugin-form.ts
@@ -35,6 +35,8 @@ export interface BasePluginFormConfig {
   entityId?: string
   /** Whether to hide the consumer group scope field. For Kong Manager OSS, this is true */
   disableConsumerGroupScope?: boolean
+  /** Whether to enable grouping for required and advanced (optional) fields. Default: false */
+  groupFields?: boolean
 }
 
 export interface KongManagerPluginSelectConfig extends BasePluginSelectConfig, KongManagerBaseFormConfig {}