feat(pageheader): new component [khcp-7898]

packages/core/app-layout/docs/page-header.md

@@ -0,0 +1,71 @@
+# AppPageHeader.vue
+
+A Kong UI dynamic page header component.
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Usage](#usage)
+  - [Install](#install)
+  - [Props](#props)
+  - [Slots](#slots)
+
+## Features
+
+- Reactive updates based on `prop` value changes :rocket:
+- Slottable areas for displaying custom content, icons, etc.
+- Built-in support for rendering breadcrumbs (optional)
+
+## Requirements
+
+- `vue` must be initialized in the host application
+- `@kong/kongponents` must be available as a `dependency` in the host application, along with the package's style imports. [See here for instructions on installing Kongponents](https://kongponents.konghq.com/#globally-install-all-kongponents).
+
+## Usage
+
+### Install
+
+[See instructions for installing the `@kong-ui-public/app-layout` package.](../README.md#install)
+
+### Props
+
+#### `title`
+
+- type: `String`
+- required: `true`
+- default: `''`
+
+The title text of the page.
+
+#### `breadcrumbs`
+
+- type: Array as PropType<BreadcrumbItem[]>
+- required: `false`
+- default: `[]`
+
+Breadcrumb object to be passed into `KBreadcrumb`.
+
+### Slots
+
+#### `${breadcrumb.key}-icon`
+
+We surface `KBreadcrumb`'s [icon slots](https://kongponents.konghq.com/components/breadcrumbs.html#icon-key).
+
+#### `title-before`
+
+Content displayed before the title text, typically an icon.
+
+#### `title-after`
+
+Content displayed after the title text, typically a badge.
+
+#### `actions`
+
+Content displayed opposite the title, typically an action menu.
+
+#### `below`
+
+Content displayed directly below the title.
+
+---
+
+[← Back to `@kong-ui-public/app-layout` docs](../README.md)

packages/core/app-layout/package.json

@@ -38,7 +38,7 @@
     "test:unit:open": "cross-env FORCE_COLOR=1 vitest --ui"
   },
   "peerDependencies": {
-    "@kong/kongponents": "^8.91.1",
+    "@kong/kongponents": "^8.113.0",
     "vue": "^3.3.4",
     "vue-router": "^4.2.4"
   },
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@kong/design-tokens": "^1.7.1",
-    "@kong/kongponents": "^8.91.1",
+    "@kong/kongponents": "^8.113.0",
     "@types/lodash.clonedeep": "^4.5.7",
     "vue": "^3.3.4",
     "vue-router": "^4.2.4"

packages/core/app-layout/sandbox/components/NavLinks.vue

@@ -12,5 +12,8 @@
     <router-link to="/kong-manager-example">
       KM Example
     </router-link>
+    <router-link to="/page-header">
+      PageHeader
+    </router-link>
   </div>
 </template>

packages/core/app-layout/sandbox/index.ts

@@ -28,6 +28,11 @@ const router = createRouter({
       name: 'kong-manager-example',
       component: () => import('./pages/KongManagerLayoutExample.vue'),
     },
+    {
+      path: '/page-header',
+      name: 'page-header',
+      component: () => import('./pages/PageHeaderPage.vue'),
+    },
   ],
 })
 

packages/core/app-layout/sandbox/pages/PageHeaderPage.vue

@@ -0,0 +1,97 @@
+<template>
+  <div class="sandbox-container">
+    <AppPageHeader
+      :breadcrumbs="breadcrumbs"
+      title="Cats are Cool"
+    >
+      <template #icon-home>
+        <KIcon
+          class="home-breadcrumb-icon"
+          color="#169fcc"
+          icon="immunity"
+          size="16"
+        />
+      </template>
+      <template #title-before>
+        <KIcon
+          class="title-icon"
+          color="#169fcc"
+          icon="graduationHat"
+          size="20"
+        />
+      </template>
+      <template #title-after>
+        <KBadge
+          appearance="neutral"
+          shape="rectangular"
+        >
+          TRUTH
+        </KBadge>
+      </template>
+
+      <template #actions>
+        <div class="actions-wrapper">
+          <KInputSwitch
+            v-model="enabled"
+            class="mr-3"
+            :label="enabled ? 'Enabled' : 'Disabled'"
+            label-position="left"
+          />
+          <KButton
+            appearance="creation"
+            icon="plus"
+          >
+            Do Things
+          </KButton>
+        </div>
+      </template>
+
+      <template #below>
+        <div>
+          Cats are a key part of a balanced day (except when walking down stairs)
+        </div>
+      </template>
+    </AppPageHeader>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { AppPageHeader } from '../../src'
+
+const breadcrumbs = computed(() => {
+  return [
+    {
+      key: 'home',
+      to: { name: 'home' },
+      text: 'Home',
+    },
+  ]
+})
+const enabled = ref(false)
+</script>
+
+<style lang="scss" scoped>
+.sandbox-container {
+  padding: 16px;
+}
+
+.home-breadcrumb-icon {
+  align-self: center;
+  display: inline-flex;
+  margin-right: 8px;
+}
+
+.title-icon {
+  display: inline-flex;
+}
+
+.mr-3 {
+  margin-right: 8px;
+}
+
+.actions-wrapper {
+  display: flex;
+  align-items: baseline;
+}
+</style>

packages/core/app-layout/src/components/pageHeader/AppPageHeader.cy.ts

@@ -0,0 +1,84 @@
+// Cypress component test spec file
+
+import AppPageHeader from './AppPageHeader.vue'
+
+describe('<AppPageHeader />', () => {
+  it('should correctly render content when using props', () => {
+    const title = 'Cats are Cool'
+    const breadcrumbTitle = 'Home'
+
+    cy.mount(AppPageHeader, {
+      props: {
+        title,
+        breadcrumbs: [{
+          key: 'home',
+          to: { name: 'home' },
+          text: breadcrumbTitle,
+          icon: 'kong',
+        }],
+      },
+    })
+
+    cy.get('.kong-ui-app-page-header').should('exist')
+    cy.getTestId('page-header-breadcrumbs').should('be.visible')
+    cy.get('.k-breadcrumb-text').should('contain.text', breadcrumbTitle)
+    cy.getTestId('page-header-title').should('be.visible')
+    cy.getTestId('page-header-title').should('contain.text', title)
+  })
+
+  it('should correctly render content when use slots', () => {
+    const title = 'Cats are Cool'
+    const breadcrumbIcon = 'home-breadcrumb-icon'
+    const iconText = 'title-icons-are-cool'
+    const badgeText = 'title-badges-are-cool'
+    const actionsText = 'actions-are-cool'
+    const belowText = 'Cats are the key to a happy life.'
+
+    cy.mount(AppPageHeader, {
+      props: {
+        title,
+        breadcrumbs: [{
+          key: 'home',
+          to: { name: 'home' },
+          text: 'Home',
+        }],
+      },
+      slots: {
+        'icon-home': breadcrumbIcon,
+        'title-before': iconText,
+        'title-after': badgeText,
+        actions: actionsText,
+        below: belowText,
+      },
+    })
+
+    cy.get('.kong-ui-app-page-header').should('exist')
+    cy.get('.k-breadcrumb-icon-wrapper').should('be.visible')
+    cy.get('.k-breadcrumb-icon-wrapper').should('contain.text', breadcrumbIcon)
+    cy.getTestId('page-header-title-before').should('be.visible')
+    cy.getTestId('page-header-title-before').should('contain.text', iconText)
+    cy.getTestId('page-header-title-after').should('be.visible')
+    cy.getTestId('page-header-title-after').should('contain.text', badgeText)
+    cy.getTestId('page-header-actions').should('be.visible')
+    cy.getTestId('page-header-actions').should('contain.text', actionsText)
+    cy.getTestId('page-header-section-below').should('be.visible')
+    cy.getTestId('page-header-section-below').should('contain.text', belowText)
+  })
+
+  it('should not render empty props/slots', () => {
+    const title = 'Cats are Cool'
+
+    cy.mount(AppPageHeader, {
+      props: {
+        title,
+      },
+    })
+
+    cy.get('.kong-ui-app-page-header').should('exist')
+    cy.getTestId('page-header-breadcrumbs').should('not.exist')
+    cy.getTestId('page-header-title-before').should('not.exist')
+    cy.getTestId('page-header-title-after').should('not.exist')
+    cy.getTestId('page-header-actions').should('not.exist')
+    cy.getTestId('page-header-section-below').should('not.exist')
+  })
+})