docs: update

Author: hunghg255

docs/.vitepress/config.ts

@@ -1,6 +1,6 @@
 import { defineConfig } from 'vitepress'
-import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
-import ts from 'typescript'
+import { defaultHoverInfoProcessor, transformerTwoslash } from '@shikijs/vitepress-twoslash'
+import { transformerRemoveNotationEscape } from '@shikijs/transformers'
 import { getLocaleConfig } from './locale'
 
 const docsLink = 'https://js-utils-es.vercel.app'
@@ -41,15 +41,60 @@ export default defineConfig({
   },
   markdown: {
     codeTransformers: [
+      {
+        // Render custom themes with codeblocks
+        name: 'shiki:inline-theme',
+        preprocess(code, options) {
+          const reg = /\btheme:([\w,-]+)\b/
+          const match = options.meta?.__raw?.match(reg)
+          if (!match?.[1])
+            return
+          const theme = match[1]
+          const themes = theme.split(',').map(i => i.trim())
+          if (!themes.length)
+            return
+          if (themes.length === 1) {
+            // @ts-expect-error anyway
+            delete options.themes
+            // @ts-expect-error anyway
+            options.theme = themes[0]
+          }
+          else if (themes.length === 2) {
+            // @ts-expect-error anyway
+            delete options.theme
+            // @ts-expect-error anyway
+            options.themes = {
+              light: themes[0],
+              dark: themes[1],
+            }
+          }
+          else {
+            throw new Error(`Only 1 or 2 themes are supported, got ${themes.length}`)
+          }
+          return code
+        },
+      },
+      {
+        name: 'shiki:inline-decorations',
+        preprocess(code, options) {
+          const reg = /^\/\/ @decorations:(.*)\n/
+          code = code.replace(reg, (match, decorations) => {
+            options.decorations ||= []
+            options.decorations.push(...JSON.parse(decorations))
+            return ''
+          })
+          return code
+        },
+      },
       transformerTwoslash({
-        twoslashOptions: {
-          compilerOptions: {
-            jsx: ts.JsxEmit.Preserve,
-            jsxFactory: 'vue',
-            types: ['unplugin-vue-macros/macros-global', 'vue/jsx'],
-          },
+        // errorRendering: 'hover',
+        processHoverInfo(info) {
+          return defaultHoverInfoProcessor(info)
+            // Remove shiki_core namespace
+            .replace(/_shikijs_core\w*\./g, '')
         },
       }),
+      transformerRemoveNotationEscape(),
     ],
   },
 })

docs/.vitepress/locale.ts

@@ -20,7 +20,7 @@ export function getLocaleConfig(lang: string) {
     ['meta', { property: 'og:url', content: docsLink }],
     ['meta', { property: 'twitter:card', content: 'summary_large_image' }],
     ['meta', { property: 'twitter:image', content: `${docsLink}/og.png` }],
-    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+    ['link', { rel: 'icon', href: '/logo.svg', type: 'image/svg+xml' }],
     ['meta', { name: 'theme-color', content: '#914796' }],
   ]
 
@@ -174,7 +174,7 @@ export function getLocaleConfig(lang: string) {
   ]
 
   const themeConfig: DefaultTheme.Config = {
-    logo: '/favicon.svg',
+    logo: '/logo.svg',
     nav,
     sidebar,
     socialLinks: [

docs/.vitepress/theme/index.ts

@@ -20,6 +20,9 @@ export default {
       mapAuthors: [
         {
           name: 'hunghg255',
+          username: 'hunghg255',
+          mapByNameAliases: ['Hung Hoang', 'Hoang Hung'],
+          mapByEmailAliases: ['giahunghust@gmail.com'],
         },
       ],
     })

docs/.vitepress/theme/style.css

@@ -1,3 +1,49 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+
 /**
  * Colors
  * -------------------------------------------------------------------------- */
@@ -135,3 +181,7 @@
 .VPLocalSearchBox .excerpt-wrapper {
   margin-top: 4px;
 }
+
+.VPHomeHero .VPImage {
+  border-radius: 16px;
+}

docs/index.md

@@ -21,10 +21,4 @@ features:
     details: js-utils-es ships up to 97% less JavaScript code compared to other alternative libraries.
   - title: Modern implementation
     details: js-utils-es fully leverages modern JavaScript APIs for straightforward and error-free implementation.
-  - title: Robust types
-    details: js-utils-es offers simple yet robust types for all functions.
-  - title: Battle-tested
-    details: js-utils-es has 100% test coverage, ensuring maximum robustness.
-  - title: Comprehensive runtime support
-    details: js-utils-es supports all JavaScript environments, including Node.js, Deno, Bun, and browsers.
 ---

docs/package.json

@@ -9,13 +9,14 @@
     "preview": "vitepress preview"
   },
   "dependencies": {
+    "@shikijs/transformers": "^1.10.3",
     "prettier": "^3.3.2",
     "shiki": "^1.10.3"
   },
   "devDependencies": {
     "@nolebase/vitepress-plugin-enhanced-mark": "^2.2.1",
     "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.2.1",
-    "@nolebase/vitepress-plugin-git-changelog": "^2.2.1",
+    "@nolebase/vitepress-plugin-git-changelog": "^2.2.2",
     "@nolebase/vitepress-plugin-highlight-targeted-heading": "^2.2.1",
     "@shikijs/vitepress-twoslash": "^1.10.3",
     "@vitejs/plugin-vue-jsx": "^4.0.0",

docs/public/favicon.ico

@@ -27,7 +27,7 @@ Throws an error if `size` is not a positive integer.
 
 ## Examples
 
-```typescript
+```typescript twoslash
 import { chunk } from 'js-utils-es/array';
 
 // Splits an array of numbers into sub-arrays of length 2

docs/public/logo.svg

@@ -18,7 +18,9 @@ function compact<T>(arr: T[]): Array<Exclude<T, false | null | 0 | '' | undefine
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { compact } from 'js-utils-es/array';
+
 compact([0, 1, false, 2, '', 3, null, undefined, 4, Number.NaN, 5]);
 // Returns: [1, 2, 3, 4, 5]
 ```