feat(theme): add built-in global component `Badge` (#1239)

Co-authored-by: richardo2016 <richardo2016@gmail.com>
Co-authored-by: Kia Ishii <kia.king.08@gmail.com>
Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>

docs/.vitepress/config.ts

@@ -108,6 +108,7 @@ function sidebarGuide() {
         { text: 'Layout', link: '/guide/theme-layout' },
         { text: 'Home Page', link: '/guide/theme-home-page' },
         { text: 'Team Page', link: '/guide/theme-team-page' },
+        { text: 'Badge', link: '/guide/theme-badge' },
         { text: 'Footer', link: '/guide/theme-footer' },
         { text: 'Search', link: '/guide/theme-search' },
         { text: 'Carbon Ads', link: '/guide/theme-carbon-ads' }

docs/guide/theme-badge.md

@@ -0,0 +1,83 @@
+# Badge
+
+The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version.
+
+## Usage
+
+You may use the `Badge` component which is globally available.
+
+```html
+### Title <Badge type="info" text="default" />
+### Title <Badge type="tip" text="^1.9.0" />
+### Title <Badge type="warning" text="beta" />
+### Title <Badge type="danger" text="caution" />
+```
+
+Code above renders like:
+
+### Title <Badge type="info" text="default" vertical="middle" />
+### Title <Badge type="tip" text="^1.9.0" vertical="middle" />
+### Title <Badge type="warning" text="beta" vertical="middle" />
+### Title <Badge type="danger" text="caution" vertical="middle" />
+
+## Custom Children
+
+`<Badge>` accept `children`, which will be displayed in the badge.
+
+```html
+### Title <Badge type="info">custom element</Badge>
+```
+
+### Title <Badge type="info">custom element</Badge>
+
+## Customize Type Color
+
+you can customize `background-color` of typed `<Badge />` by override css vars. The following is he default values.
+
+```css
+:root {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-text: var(--vp-c-text-2);
+  --vp-badge-info-bg: var(--vp-c-white-soft);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-1);
+  --vp-badge-tip-text: var(--vp-c-green-darker);
+  --vp-badge-tip-bg: var(--vp-c-green-dimm-3);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-1);
+  --vp-badge-warning-text: var(--vp-c-yellow-darker);
+  --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-1);
+  --vp-badge-danger-text: var(--vp-c-red-darker);
+  --vp-badge-danger-bg: var(--vp-c-red-dimm-3);
+}
+
+.dark {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-bg: var(--vp-c-black-mute);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-2);
+  --vp-badge-tip-text: var(--vp-c-green-light);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-2);
+  --vp-badge-warning-text: var(--vp-c-yellow-light);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-2);
+  --vp-badge-danger-text: var(--vp-c-red-light);
+}
+```
+
+## `<Badge>`
+
+`<Badge>` component accepts following props:
+
+```ts
+interface Props {
+  // When `<slot>` is passed, this value gets ignored.
+  text?: string
+
+  // Defaults to `tip`.
+  type?: 'info' | 'tip' | 'warning' | 'danger'
+}
+```

docs/guide/theme-introduction.md

@@ -10,6 +10,7 @@ VitePress comes with its default theme providing many features out of the box. L
 - [Layout](./theme-layout)
 - [Home Page](./theme-home-page)
 - [Team Page](./theme-team-page)
+- [Badge](./theme-badge)
 - [Footer](./theme-footer)
 - [Search](./theme-search)
 - [Carbon Ads](./theme-carbon-ads)
@@ -109,9 +110,12 @@ import DefaultTheme from 'vitepress/theme'
 
 export default {
   ...DefaultTheme,
-  enhanceApp({ app }) {
+  enhanceApp(ctx) {
-    // register global components
+    // extend default theme custom behaviour.
-    app.component('MyGlobalComponent', /* ... */)
+    DefaultTheme.enhanceApp(ctx)
+
+    // register your custom global components
+    ctx.app.component('MyGlobalComponent' /* ... */)
   }
 }
 ```

docs/guide/using-vue.md

@@ -113,8 +113,9 @@ import DefaultTheme from 'vitepress/theme'
 
 export default {
   ...DefaultTheme,
-  enhanceApp({ app }) {
+  enhanceApp(ctx) {
-    app.component('VueClickAwayExample', VueClickAwayExample)
+    DefaultTheme.enhanceApp(ctx)
+    ctx.app.component('VueClickAwayExample', VueClickAwayExample)
   }
 }
 ```

src/client/theme-default/components/VPBadge.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+defineProps<{
+  text?: string
+  type?: 'info' | 'tip' | 'warning' | 'danger'
+}>()
+</script>
+
+<template>
+  <span class="VPBadge" :class="type ?? 'tip'">
+    <slot>{{ text }}</slot>
+  </span>
+</template>
+
+<style scoped>
+.VPBadge {
+  display: inline-block;
+  margin-left: 2px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  padding: 0 8px;
+  line-height: 18px;
+  font-size: 13px;
+  font-weight: 600;
+  transform: translateY(-2px);
+}
+
+h2 .VPBadge {
+  border-radius: 11px;
+  line-height: 20px;
+}
+
+.VPBadge.info {
+  border-color: var(--vp-badge-info-border);
+  color: var(--vp-badge-info-text);
+  background-color: var(--vp-badge-info-bg);
+}
+
+.VPBadge.tip {
+  border-color: var(--vp-badge-tip-border);
+  color: var(--vp-badge-tip-text);
+  background-color: var(--vp-badge-tip-bg);
+}
+
+.VPBadge.warning {
+  border-color: var(--vp-badge-warning-border);
+  color: var(--vp-badge-warning-text);
+  background-color: var(--vp-badge-warning-bg);
+}
+
+.VPBadge.danger {
+  border-color: var(--vp-badge-danger-border);
+  color: var(--vp-badge-danger-text);
+  background-color: var(--vp-badge-danger-bg);
+}
+</style>

src/client/theme-default/index.ts

@@ -8,6 +8,7 @@ import './styles/components/vp-doc.css'
 import './styles/components/vp-sponsor.css'
 
 import { Theme } from 'vitepress'
+import VPBadge from './components/VPBadge.vue'
 import Layout from './Layout.vue'
 import NotFound from './NotFound.vue'
 
@@ -22,7 +23,10 @@ export { default as VPTeamMembers } from './components/VPTeamMembers.vue'
 
 const theme: Theme = {
   Layout,
-  NotFound
+  NotFound,
+  enhanceApp: ({ app }) => {
+    app.component('Badge', VPBadge)
+  }
 }
 
 export default theme

src/client/theme-default/styles/vars.css

@@ -370,3 +370,39 @@
   --vp-home-hero-image-background-image: none;
   --vp-home-hero-image-filter: none;
 }
+
+/**
+ * Component: Badge
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-text: var(--vp-c-text-2);
+  --vp-badge-info-bg: var(--vp-c-white-soft);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-1);
+  --vp-badge-tip-text: var(--vp-c-green-darker);
+  --vp-badge-tip-bg: var(--vp-c-green-dimm-3);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-1);
+  --vp-badge-warning-text: var(--vp-c-yellow-darker);
+  --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-1);
+  --vp-badge-danger-text: var(--vp-c-red-darker);
+  --vp-badge-danger-bg: var(--vp-c-red-dimm-3);
+}
+
+.dark {
+  --vp-badge-info-border: var(--vp-c-divider-light);
+  --vp-badge-info-bg: var(--vp-c-black-mute);
+
+  --vp-badge-tip-border: var(--vp-c-green-dimm-2);
+  --vp-badge-tip-text: var(--vp-c-green-light);
+
+  --vp-badge-warning-border: var(--vp-c-yellow-dimm-2);
+  --vp-badge-warning-text: var(--vp-c-yellow-light);
+
+  --vp-badge-danger-border: var(--vp-c-red-dimm-2);
+  --vp-badge-danger-text: var(--vp-c-red-light);
+}

theme.d.ts

@@ -1,5 +1,6 @@
 // so that users can do `import DefaultTheme from 'vitepress/theme'`
 import type { DefineComponent } from 'vue'
+import { EnhanceAppContext } from './dist/client/index.js'
 
 // TODO: add props for these
 export const VPHomeHero: DefineComponent
@@ -14,6 +15,7 @@ export const VPTeamMembers: DefineComponent
 declare const theme: {
   Layout: DefineComponent
   NotFound: DefineComponent
+  enhanceApp: (ctx: EnhanceAppContext) => void
 }
 
 export default theme