feat(*): add description on entity list pages (#61)

README.md

@@ -1,6 +1,6 @@
 # Kong Manager OSS
 
-[Installation](#getting-started) | [Provide feedback](https://github.com/Kong/kong-manager/issues/new) | [Ask a question](https://join.slack.com/t/kongcommunity/shared_invite/zt-1s4nb74vo-jLdMEk8MoTm~uMWYMMLPWg) | [Contributing](#contributing) | [Blog](https://konghq.com/blog)
+[Installation](#getting-started) | [Provide feedback](https://github.com/Kong/kong-manager/issues/new/choose) | [Ask a question](https://join.slack.com/t/kongcommunity/shared_invite/zt-1s4nb74vo-jLdMEk8MoTm~uMWYMMLPWg) | [Contributing](#contributing) | [Blog](https://konghq.com/blog)
 
 ![Kong Manager OSS - Plugin list](./media/Plugin%20list.png)
 

package.json

@@ -31,7 +31,7 @@
     "@kong-ui/entities-shared": "^0.44.2",
     "@kong-ui/entities-snis": "^0.14.2",
     "@kong-ui/entities-upstreams-targets": "^0.16.2",
-    "@kong-ui/entities-vaults": "^0.16.2",
+    "@kong-ui/entities-vaults": "^0.17.0",
     "@kong-ui/forms": "^0.21.1",
     "@kong/kongponents": "^8.97.0",
     "@material-design-icons/font": "^0.14.9",

src/components/PageHeader.vue

@@ -60,7 +60,7 @@ const tag = computed(() => `h${props.size}`)
 
 h1, h2, h3, h4, h5, h6, nav {
   margin-top: 0px;
-  margin-bottom: 20px;
+  margin-bottom: 12px;
   display: flex;
   align-items: center;
 }

src/components/SupportText.vue

@@ -0,0 +1,12 @@
+<template>
+  <div class="support-text">
+    <slot />
+  </div>
+</template>
+
+<style scoped lang="scss">
+.support-text {
+  color: var(--black-45);
+  margin-bottom: 16px;
+}
+</style>

src/composables/useDocsLink.ts

@@ -0,0 +1,25 @@
+import { computed } from 'vue'
+import { formatVersion } from '@/utils'
+import { config } from 'config'
+
+export const useDocsLink = (entity: string) => {
+  const version = computed(() => {
+    if (!config.GATEWAY_VERSION) {
+      return 'latest'
+    }
+
+    return `${formatVersion(config.GATEWAY_VERSION)}.x`
+  })
+
+  const docsBase = computed(() => `https://docs.konghq.com/gateway/${version.value}/admin-api`)
+  const docsLink = computed(() => {
+    switch (entity) {
+      case 'key-set':
+        return `${docsBase.value}/#key-sets-entity`
+      default:
+        return `${docsBase.value}/#${entity}-object`
+    }
+  })
+
+  return docsLink
+}

src/locales/en.json

@@ -7,7 +7,8 @@
       "edit": "Edit",
       "save": "Save",
       "create": "Create"
-    }
+    },
+    "learn.more": "Learn more"
   },
   "overview": {
     "info": {
@@ -72,6 +73,7 @@
   },
   "entities": {
     "service": {
+      "description": "Gateway Service entities are abstractions of each of your own upstream services, e.g., a data transformation microservice, a billing API.",
       "created": "Gateway Service {name} is successfully created!",
       "updated": "Gateway Service {name} is successfully updated!",
       "deleted": "Gateway Service {name} is successfully deleted!",
@@ -81,6 +83,7 @@
       "edit.form.title": "Edit Gateway Service"
     },
     "route": {
+      "description": "A Route defines rules to match client requests, and is associated with a Service.",
       "created": "Route {name} is successfully created!",
       "updated": "Route {name} is successfully updated!",
       "deleted": "Route {name} is successfully deleted!",
@@ -90,6 +93,7 @@
       "edit.form.title": "Edit Route"
     },
     "consumer": {
+      "description": "Consumers are the end users of a service.",
       "created": "Consumer {name} is successfully created!",
       "updated": "Consumer {name} is successfully updated!",
       "deleted": "Consumer {name} is successfully deleted!",
@@ -111,6 +115,7 @@
       "edit.form.title": "Edit: {type}"
     },
     "plugin": {
+      "description": "Plugins allow you to extend Kong's capabilities with features like rate limiting, authentication, and logging.",
       "created": "Plugin {name} is successfully created!",
       "updated": "Plugin {name} is successfully updated!",
       "deleted": "Plugin {name} is successfully deleted!",
@@ -121,6 +126,7 @@
       "edit.form.title": "Edit Plugin"
     },
     "upstream": {
+      "description": "An Upstream represents a virtual hostname and can be used to load balance incoming requests over multiple Services.",
       "created": "Upstream {name} is successfully created!",
       "updated": "Upstream {name} is successfully updated!",
       "deleted": "Upstream {name} is successfully deleted!",
@@ -130,6 +136,7 @@
       "edit.form.title": "Edit Upstream"
     },
     "certificate": {
+      "description": "Certificates handle SSL/TLS termination for encrypted requests.",
       "created": "Certificate {id} is successfully created!",
       "updated": "Certificate {id} is successfully updated!",
       "deleted": "Certificate {id} is successfully deleted!",
@@ -139,6 +146,7 @@
       "edit.form.title": "Edit Certificate"
     },
     "ca-certificate": {
+      "description": "CA certificates validate client or server certificates.",
       "created": "CA Certificate {id} is successfully created!",
       "updated": "CA Certificate {id} is successfully updated!",
       "deleted": "CA Certificate {id} is successfully deleted!",
@@ -148,6 +156,7 @@
       "edit.form.title": "Edit CA Certificate"
     },
     "sni": {
+      "description": "An SNI object represents a many-to-one mapping of hostnames to a certificate.",
       "created": "SNI {name} is successfully created!",
       "updated": "SNI {name} is successfully updated!",
       "deleted": "SNI {name} is successfully deleted!",
@@ -168,6 +177,7 @@
       "edit.form.title": "Edit Target"
     },
     "vault": {
+      "description": "Improve the security of your Kong Gateway deployment with centralized secrets.",
       "created": "Vault {name} is successfully created!",
       "updated": "Vault {name} is successfully updated!",
       "deleted": "Vault {name} is successfully deleted!",
@@ -177,6 +187,7 @@
       "edit.form.title": "Edit Vault"
     },
     "key": {
+      "description": "A Key object holds a representation of asymmetric keys in various formats.",
       "created": "Key {name} is successfully created!",
       "updated": "Key {name} is successfully updated!",
       "deleted": "Key {name} is successfully deleted!",
@@ -186,6 +197,7 @@
       "edit.form.title": "Edit Key"
     },
     "key-set": {
+      "description": "A Key Set object holds a collection of asymmetric key objects.",
       "created": "Key Set {name} is successfully created!",
       "updated": "Key Set {name} is successfully updated!",
       "deleted": "Key Set {name} is successfully deleted!",

src/pages/ca-certificates/List.vue

@@ -1,5 +1,14 @@
 <template>
-  <PageHeader :title="t('entities.ca-certificate.list.title')" />
+  <PageHeader :title="t('entities.ca-certificate.list.title')">
+    <template #below-title>
+      <SupportText>
+        {{ t('entities.ca-certificate.description') }}
+        <KExternalLink :href="docsLink">
+          {{ t('global.learn.more') }}
+        </KExternalLink>
+      </SupportText>
+    </template>
+  </PageHeader>
   <CACertificateList
     :config="caCertificateListConfig"
     :can-create="canCreate"
@@ -13,13 +22,14 @@
 </template>
 
 <script setup lang="ts">
+import { computed, reactive } from 'vue'
+import { CACertificateList, type EntityRow } from '@kong-ui/entities-certificates'
 import { useCopyEventHandlers } from '@/composables/useCopyEventHandlers'
 import { useI18n } from '@/composables/useI18n'
 import { useListGeneralConfig } from '@/composables/useListGeneralConfig'
 import { useListRedirect } from '@/composables/useListRedirect'
 import { useToaster } from '@/composables/useToaster'
-import { CACertificateList, type EntityRow } from '@kong-ui/entities-certificates'
-import { computed, reactive } from 'vue'
+import { useDocsLink } from '@/composables/useDocsLink'
 
 defineOptions({
   name: 'CACertificateList',
@@ -28,6 +38,7 @@ defineOptions({
 const { createRedirectRouteQuery } = useListRedirect()
 const toaster = useToaster()
 const { t } = useI18n()
+const docsLink = useDocsLink('ca-certificate')
 
 const createRoute = computed(() => {
   return { name: 'ca-certificate-create' }

src/pages/certificates/List.vue

@@ -1,5 +1,14 @@
 <template>
-  <PageHeader :title="t('entities.certificate.list.title')" />
+  <PageHeader :title="t('entities.certificate.list.title')">
+    <template #below-title>
+      <SupportText>
+        {{ t('entities.certificate.description') }}
+        <KExternalLink :href="docsLink">
+          {{ t('global.learn.more') }}
+        </KExternalLink>
+      </SupportText>
+    </template>
+  </PageHeader>
   <CertificateList
     :config="certificateListConfig"
     :can-create="canCreate"
@@ -13,13 +22,14 @@
 </template>
 
 <script setup lang="ts">
+import { computed, reactive } from 'vue'
+import { CertificateList, type EntityRow } from '@kong-ui/entities-certificates'
 import { useCopyEventHandlers } from '@/composables/useCopyEventHandlers'
 import { useI18n } from '@/composables/useI18n'
 import { useListGeneralConfig } from '@/composables/useListGeneralConfig'
 import { useListRedirect } from '@/composables/useListRedirect'
 import { useToaster } from '@/composables/useToaster'
-import { CertificateList, type EntityRow } from '@kong-ui/entities-certificates'
-import { computed, reactive } from 'vue'
+import { useDocsLink } from '@/composables/useDocsLink'
 
 defineOptions({
   name: 'CertificateList',
@@ -28,6 +38,7 @@ defineOptions({
 const { createRedirectRouteQuery } = useListRedirect()
 const toaster = useToaster()
 const { t } = useI18n()
+const docsLink = useDocsLink('certificate')
 
 const createRoute = computed(() => {
   return { name: 'certificate-create' }

src/pages/consumers/List.vue

@@ -1,5 +1,14 @@
 <template>
-  <PageHeader :title="t('entities.consumer.list.title')" />
+  <PageHeader :title="t('entities.consumer.list.title')">
+    <template #below-title>
+      <SupportText>
+        {{ t('entities.consumer.description') }}
+        <KExternalLink :href="docsLink">
+          {{ t('global.learn.more') }}
+        </KExternalLink>
+      </SupportText>
+    </template>
+  </PageHeader>
   <ConsumerList
     :config="consumerListConfig"
     :can-create="canCreate"
@@ -21,6 +30,7 @@ import { useListRedirect } from '@/composables/useListRedirect'
 import { useCopyEventHandlers } from '@/composables/useCopyEventHandlers'
 import { useToaster } from '@/composables/useToaster'
 import { useI18n } from '@/composables/useI18n'
+import { useDocsLink } from '@/composables/useDocsLink'
 
 defineOptions({
   name: 'ConsumerList',
@@ -29,6 +39,7 @@ defineOptions({
 const { createRedirectRouteQuery } = useListRedirect()
 const toaster = useToaster()
 const { t } = useI18n()
+const docsLink = useDocsLink('consumer')
 
 const createRoute = computed(() => {
   return { name: 'consumer-create' }

src/pages/key-sets/List.vue

@@ -1,5 +1,14 @@
 <template>
-  <PageHeader :title="t('entities.key-set.list.title')" />
+  <PageHeader :title="t('entities.key-set.list.title')">
+    <template #below-title>
+      <SupportText>
+        {{ t('entities.key-set.description') }}
+        <KExternalLink :href="docsLink">
+          {{ t('global.learn.more') }}
+        </KExternalLink>
+      </SupportText>
+    </template>
+  </PageHeader>
   <KeySetList
     :config="keyListConfig"
     :can-create="canCreate"
@@ -21,6 +30,7 @@ import { useListRedirect } from '@/composables/useListRedirect'
 import { useToaster } from '@/composables/useToaster'
 import { useCopyEventHandlers } from '@/composables/useCopyEventHandlers'
 import { useI18n } from '@/composables/useI18n'
+import { useDocsLink } from '@/composables/useDocsLink'
 
 defineOptions({
   name: 'KeySetList',
@@ -29,6 +39,7 @@ defineOptions({
 const { createRedirectRouteQuery } = useListRedirect()
 const toaster = useToaster()
 const { t } = useI18n()
+const docsLink = useDocsLink('key-set')
 
 const filterSchema = computed<FilterSchema>(() => {
   return {

src/pages/keys/List.vue

@@ -2,7 +2,16 @@
   <PageHeader
     v-if="!keySetId"
     :title="t('entities.key.list.title')"
-  />
+  >
+    <template #below-title>
+      <SupportText>
+        {{ t('entities.key.description') }}
+        <KExternalLink :href="docsLink">
+          {{ t('global.learn.more') }}
+        </KExternalLink>
+      </SupportText>
+    </template>
+  </PageHeader>
   <KeyList
     :cache-identifier="cacheIdentifier"
     :config="keyListConfig"
@@ -26,6 +35,7 @@ import { useListRedirect } from '@/composables/useListRedirect'
 import { useToaster } from '@/composables/useToaster'
 import { useCopyEventHandlers } from '@/composables/useCopyEventHandlers'
 import { useI18n } from '@/composables/useI18n'
+import { useDocsLink } from '@/composables/useDocsLink'
 
 defineOptions({
   name: 'KeyList',
@@ -35,6 +45,7 @@ const { createRedirectRouteQuery } = useListRedirect()
 const toaster = useToaster()
 const route = useRoute()
 const { t } = useI18n()
+const docsLink = useDocsLink('keys')
 
 const keySetId = computed(() => (route.params?.id ?? '') as string)
 const cacheIdentifier = computed(() => `routes-${keySetId.value}`)

src/pages/overview/Overview.vue

@@ -193,11 +193,13 @@ onBeforeMount(async () => {
 </script>
 
 <style scoped lang="scss">
+$card-spacing: 32px;
+
 .info-container {
   display: grid;
   grid-template-columns: 1fr 1fr;
-  grid-gap: 32px;
-  margin-bottom: 32px;
+  grid-gap: $card-spacing;
+  margin-bottom: $card-spacing;
 }
 .info-list, .resource-list {
   list-style: none;
@@ -234,7 +236,7 @@ onBeforeMount(async () => {
 
 .resource-card {
   padding: 0;
-  margin-bottom: 32px;
+  margin-bottom: $card-spacing;
 
   :deep(.k-card-header) {
     padding: var(--spacing-lg);