docs: update

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: ['[email protected]'],
         },
       ],
     })

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/reference/array/chunk.md

@@ -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/reference/array/compact.md

@@ -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]
 ```

docs/reference/array/countBy.md

@@ -19,7 +19,7 @@ function countBy<T>(arr: T[], mapper: (item: T) => string): Record<string, numbe
 
 ## Examples
 
-```javascript
+```typescript twoslash
 import { countBy } from 'js-utils-es/array';
 
 const array = [1, 2, 3, 4, 5, 6];

docs/reference/array/difference.md

@@ -24,7 +24,7 @@ in the second array.
 
 ## Examples
 
-```typescript
+```typescript twoslash
 import { difference } from 'js-utils-es/array';
 
 const array1 = [1, 2, 3, 4, 5];

docs/reference/array/differenceBy.md

@@ -26,8 +26,6 @@ function differenceBy<T, U>(firstArr: T[], secondArr: T[], mapper: (value: T) =>
 ## Examples
 
 ```typescript
-import { differenceBy } from 'js-utils-es/array';
-
 const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
 const array2 = [{ id: 2 }, { id: 4 }];
 const mapper = item => item.id;

docs/reference/array/drop.md

@@ -22,7 +22,9 @@ function drop<T>(arr: T[], itemsCount: number): T[];
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { drop } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const result = drop(array, 2);
 // result will be [3, 4, 5] since the first two elements are dropped.

docs/reference/array/dropRight.md

@@ -22,7 +22,9 @@ function dropRight<T>(arr: T[], itemsCount: number): T[];
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { dropRight } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const result = dropRight(array, 2);
 // result will be [1, 2, 3] since the last two elements are dropped.

docs/reference/array/dropRightWhile.md

@@ -22,7 +22,9 @@ function dropRightWhile<T>(arr: T[], canContinueDropping: (item: T) => boolean):
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { dropRightWhile } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const result = dropRightWhile(array, x => x > 3);
 // result will be [1, 2, 3] since elements greater than 3 are dropped from the end.

docs/reference/array/dropWhile.md

@@ -22,7 +22,9 @@ function dropWhile<T>(arr: T[], canContinueDropping: (item: T) => boolean): T[];
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { dropWhile } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const result = dropWhile(array, x => x < 3);
 // result will be [3, 4, 5] since elements less than 3 are dropped.

docs/reference/array/fill.md

@@ -25,7 +25,9 @@ function fill<T, P>(array: T[], value: P, start: number, end: number): Array<T |
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { fill } from 'js-utils-es/array';
+
 const array1 = [1, 2, 3];
 const result1 = fill(array1, 'a');
 // result1 => ['a', 'a', 'a']

docs/reference/array/flatten.md

@@ -21,7 +21,9 @@ function flatten<T, D extends number = 1>(arr: T[], depth?: D): Array<FlatArray<
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { flatten } from 'js-utils-es/array';
+
 const array = [1, [2, 3], [4, [5, 6]]];
 
 const result1 = flatten(array);

docs/reference/array/flattenDeep.md

@@ -23,7 +23,9 @@ function flattenDeep<T>(arr: T[]): Array<ExtractNestedArrayType<T>>;
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { flattenDeep } from 'js-utils-es/array';
+
 const array = [1, [2, [3]], [4, [5, 6]]];
 
 const result = flattenDeep(array);

docs/reference/array/groupBy.md

@@ -24,7 +24,9 @@ share that key.
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { groupBy } from 'js-utils-es/array';
+
 const array = [
   { category: 'fruit', name: 'apple' },
   { category: 'fruit', name: 'banana' },

docs/reference/array/head.md

@@ -21,7 +21,9 @@ export function head<T>(arr: T[]): T | undefined;
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { head } from 'js-utils-es/array';
+
 const arr1 = [1, 2, 3];
 const firstElement1 = head(arr1);
 // firstElement1 will be 1

docs/reference/array/keyBy.md

@@ -23,7 +23,9 @@ function keyBy<T, K extends PropertyKey>(arr: T[], getKeyFromItem: (item: T) =>
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { keyBy } from 'js-utils-es/array';
+
 const array = [
   { category: 'fruit', name: 'apple' },
   { category: 'fruit', name: 'banana' },

docs/reference/array/orderBy.md

@@ -25,7 +25,9 @@ function orderBy<T>(collection: T[], keys: Array<keyof T>, orders: Order[]): T[]
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { orderBy } from 'js-utils-es/array';
+
 const users = [
   { user: 'fred', age: 48 },
   { user: 'barney', age: 34 },

docs/reference/array/sample.md

@@ -20,7 +20,9 @@ function sample<T>(arr: T[]): T;
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { sample } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const randomElement = sample(array);
 // randomElement will be one of the elements from the array, selected randomly.

docs/reference/array/sampleSize.md

@@ -25,7 +25,9 @@ Throws an error if `size` is greater than the length of `array`.
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { sampleSize } from 'js-utils-es/array';
+
 const result = sampleSize([1, 2, 3], 2);
 // result will be an array containing two of the elements from the array.
 // [1, 2] or [1, 3] or [2, 3]

docs/reference/array/shuffle.md

@@ -20,7 +20,9 @@ function shuffle<T>(arr: T[]): T[];
 
 ## Examples
 
-```typescript
+```typescript twoslash
+import { shuffle } from 'js-utils-es/array';
+
 const array = [1, 2, 3, 4, 5];
 const shuffledArray = shuffle(array);
 // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]