refactor(plugin-sass-palette): correct docs and improve jsdoc

docs/plugins/development/sass-palette/README.md

@@ -26,7 +26,7 @@ npm i -D @vuepress/plugin-sass-palette@next
 ```
 
 ```js title="Your plugin or theme entry"
-import { useSassPalettePlugin } from 'vuepress-plugin-sass-palette'
+import { useSassPalettePlugin } from '@vuepress/plugin-sass-palette'
 
 export const yourPlugin = (options) => (app) => {
   useSassPalettePlugin(app, {

docs/plugins/development/sass-palette/config.md

@@ -16,15 +16,15 @@ Identifier for palette, used to avoid duplicate registration.
 ### config
 
 - Type: `string`
-- Default: `` `.vuepress/styles/${id}-palette.scss` ``
+- Default: `` `.vuepress/styles/${id}-config.scss` ``
 
 User config file path, relative to source dir.
 
 ::: tip
 
-This is the file where user set style variables.
+This is the file where users set style variables.
 
-The default filename is starting with ID above.
+The default filename starts with ID above.
 
 :::
 
@@ -50,32 +50,31 @@ User palette file path, relative to source dir.
 
 ::: tip
 
-This is the file where user control injected CSS variables. All the variables will be converted in to kebab-case and injected.
+This is the file where users control injected CSS variables. All the variables will be converted to kebab-case and injected.
 
-The default filename is starting with ID above.
+The default filename starts with ID above.
 
 :::
 
 ### defaultPalette
 
 - Type: `string`
-- Default: `"@vuepress/plugin-sass-palette/styles/default/palette.scss"`
 
 Default palette file path, should be absolute path.
 
 ::: tip
 
-This is the file you should use to provide default CSS variables with `!default`. All the variable will be converted in to kebab-case and injected.
+This is the file you should use to provide default CSS variables with `!default`. All the variables will be converted to kebab-case and injected.
 
 :::
 
 ### generator
 
 - Type: `string`
 
-Custom generator, used to generate derivative values with the above config.
+Custom generator used to generate derivative values with palette config.
 
-E.g.: You may want to provide a `$theme-color-light` based on `$theme-color`.
+For example: You may want to provide a `$theme-color-light` based on `$theme-color`.
 
 ### style
 
@@ -85,7 +84,7 @@ User style file path, relative to source dir.
 
 ## Alias
 
-Available alias are:
+Available aliases are:
 
 - config: `@sass-palette/${id}-config` (based on `id`)
 - palette: `@sass-palette/${id}-palette` (based on `id`)

docs/plugins/development/sass-palette/guide.md

@@ -7,24 +7,24 @@ icon: lightbulb
 Comparing to [`@vuepress/plugin-palette`](../palette.md), this plugin allows you to:
 
 - Derive related styles based on user configuration
-- Provide style customization similar to theme in plugins
+- Provide style customization similar to themes in plugins
 - Group applications across multiple plugins or themes via id option
 
 Before using the plugin, you need to understand the id option, as well as three styling concepts: configuration, palette and generator.
 
 ## ID Option
 
-To get started, you should understand that this plugin is designed to take across plugins and theme (unlike the official one only for theme).
+To get started, you should understand that this plugin is designed to work across plugins and themes (unlike the official one only for themes).
 
-We are providing `id` option to do that, and using this plugin (by calling `useSassPalette`) with same ID won't have any side effects. Also, all the alias and module names have an ID prefix.
+We are providing `id` option to do that, and using this plugin (by calling `useSassPalette`) with same ID won't have any side effects. Also, all the aliases and module names have an ID prefix.
 
 This will allow you to:
 
-- Share same style system across your plugins (or themes) using same ID without any side effects.
+- Share the same style system across your plugins (or themes) using the same ID without any side effects.
 
   All aliases and module names have an ID prefix, which means you can use a set of style variables within your plugins (or theme) to unify your styles without being affected by other plugins (or themes).
 
-  Users can configure all color variables, breakpoints, and other style configurations in the same file and have them automatically applied on themes and plugins with the same ID.
+  Users can configure all color variables, breakpoints, and other style configurations in the same file and have them automatically applied to themes and plugins with the same ID.
 
   ::: tip Example
 
@@ -142,11 +142,11 @@ Then the below CSS variables will be available under root selector:
 
 :::
 
-Like config file, palette file provides a module named `${$id}-palette` (also including generator values), and it is also limited by `additionalData` option, so you should import the module manually if you want to use it in other Sass files.
+Like config file, palette file provides a module named `${id}-palette` (also including generator values), and it is also limited by `additionalData` option, so you should import the module manually if you want to use it in other Sass files.
 
 ### Color Settings
 
-Since the default theme is providing darkmode, so you probably want different colors under lightmode and darkmode.
+Since the default theme provides dark mode, you probably want different colors under light mode and dark mode.
 
 To achieve that, you should set color variables with a map containing `light` and `dark` keys. Later, the plugin will generate different colors for you.
 
@@ -216,17 +216,17 @@ $moveTransition: 'width 0.3s ease';
 
 ## Helper
 
-We are exposing internal functions which `@vuepress/plugin-sass-palette` uses, as a helper module.
+We are exposing internal functions that `@vuepress/plugin-sass-palette` uses, as a helper module.
 
-You can use this helper with `@sass-palette/helper` alias and call its function to achieve similar features yourself.
+You can use this helper with `@sass-palette/helper` alias and call its functions to achieve similar features yourself.
 
 ## Generator
 
-A generator file is facing developers to generate derived values based on palette file variables.
+A generator file is designed for developers to generate derived values based on palette file variables.
 
-You can access variables from palette file directly in this file and generate new values based on them.
+You can access variables from the palette file directly in this file and generate new values based on them.
 
-Variables in generator file will be also injected as CSS variables like palette, and they will be available in palette module.
+Variables in the generator file will also be injected as CSS variables like palette, and they will be available in the palette module.
 
 ::: details Example
 
@@ -257,11 +257,11 @@ $code-c-bg: abc-config.$highlighter == 'shiki'? #fff: #f8f8f8;
 
 ## User Styles
 
-If you are a theme developer, you may probably want to provide your users a way to custom your theme or the site.
+If you are a theme developer, you may want to provide your users a way to customize your theme or the site.
 
-In this case you should set `style` option as the user style file when using this plugin.
+In this case you should set the `style` option as the user style file when using this plugin.
 
-Later, you should manually include user style file by importing `@sass-palette/${id}-style` **after your theme styles**.
+Later, you should manually include the user style file by importing `@sass-palette/${id}-style` **after your theme styles**.
 
 ::: tip
 

docs/zh/plugins/development/sass-palette/README.md

@@ -26,7 +26,7 @@ npm i -D @vuepress/plugin-sass-palette@next
 ```
 
 ```js title="你的插件或主题入口"
-import { useSassPalettePlugin } from 'vuepress-plugin-sass-palette'
+import { useSassPalettePlugin } from '@vuepress/plugin-sass-palette'
 
 export const yourPlugin = (options) => (app) => {
   useSassPalettePlugin(app, {

docs/zh/plugins/development/sass-palette/config.md

@@ -9,22 +9,22 @@ icon: settings-2
 ### id
 
 - 类型：`string`
-- 必填: 是
+- 必填：是
 
 调色板的唯一 ID，用于避免重复注册。
 
 ### config
 
 - 类型：`string`
-- 默认值：`` `.vuepress/styles/${id}-palette.scss` ``
+- 默认值：`` `.vuepress/styles/${id}-config.scss` ``
 
 用户配置文件路径，相对于源文件夹。
 
 ::: tip
 
 这是用户设置样式变量的文件。
 
-默认路径的文件名拥有上方的 ID 前缀。
+默认路径的文件名以上方的 ID 作为前缀。
 
 :::
 
@@ -52,14 +52,13 @@ icon: settings-2
 
 这是用户控制注入 CSS 变量的文件。所有的变量会被转换为连字符格式然后被注入。
 
-默认路径的文件名拥有上方的 ID 前缀。
+默认路径的文件名以上方的 ID 作为前缀。
 
 :::
 
 ### defaultPalette
 
 - 类型：`string`
-- 默认值：`"@vuepress/plugin-sass-palette/styles/default/palette.scss"`
 
 默认的调色板文件路径，应为绝对路径。
 
@@ -72,18 +71,16 @@ icon: settings-2
 ### generator
 
 - 类型：`string`
-- 必填: 否
 
 自定义的生成器，用于生成调色板配置的衍生值。
 
-如: 你可能想要根据 `$theme-color` 的值提供一个 `$theme-color-light`。
+如：你可能想要根据 `$theme-color` 的值提供一个 `$theme-color-light`。
 
 ### style
 
 - 类型：`string`
-- 必填: 否
 
-用户的样式文件路径，相对于源文件夹。.
+用户的样式文件路径，相对于源文件夹。
 
 ## 别名
 

docs/zh/plugins/development/sass-palette/guide.md

@@ -140,7 +140,7 @@ $color-b: green !default;
 
 :::
 
-和配置文件一样，调色板文件提供了一个 `${$id}-palette` 模块 (也包含生成器的值)，它也受 `additionalData` 选项的限制，因此如果你想在其他 Sass 文件中使用它，你应该手动导入模块。
+和配置文件一样，调色板文件提供了一个 `${id}-palette` 模块 (也包含生成器的值)，它也受 `additionalData` 选项的限制，因此如果你想在其他 Sass 文件中使用它，你应该手动导入模块。
 
 ### 颜色设置
 

plugins/development/plugin-sass-palette/src/node/injectScssConfigModule.ts

@@ -21,11 +21,17 @@ type SassLoaderContext =
     : never
 
 /**
- * Use "additionalData" to make `${getIdPrefix(id)}config` available in scss
+ * Use "additionalData" to make config and palette modules available in SCSS
  *
- * @param config VuePress Bundler config
- * @param app VuePress Node App
- * @param id Module id
+ * 使用 "additionalData" 使配置和调色板模块在 SCSS 中可用
+ *
+ * @description Injects SCSS config and palette modules into bundler configuration using additionalData option.
+ *
+ * 使用 additionalData 选项将 SCSS 配置和调色板模块注入到打包器配置中。
+ *
+ * @param config - VuePress bundler configuration / VuePress 打包器配置
+ * @param app - VuePress app instance / VuePress 应用实例
+ * @param id - Module identifier for the palette / 调色板的模块标识符
  */
 export const injectScssConfigModule = (
   config: unknown,

plugins/development/plugin-sass-palette/src/node/options.ts

@@ -9,11 +9,11 @@ export interface SassPalettePluginOptions {
   /**
    * User config file path, relative to source dir
    *
-   * @description This is the file where user set style variables.
-   *
    * 用户配置文件路径，相对于源文件夹。
    *
-   * @description 这是用户设置样式变量的文件。
+   * @description This is the file where user set style variables.
+   *
+   * 这是用户设置样式变量的文件。
    *
    * @default `.vuepress/styles/${id}-config.scss`
    */
@@ -22,11 +22,11 @@ export interface SassPalettePluginOptions {
   /**
    * Default config file path, should be absolute path.
    *
-   * @description This is the file you should use to provide default style values with `!default`。
-   *
    * 默认的配置文件路径，应为绝对路径。
    *
-   * @description 这是你应该通过 `!default` 来提供默认样式变量的文件。
+   * @description This is the file you should use to provide default style values with `!default`.
+   *
+   * 这是你应该通过 `!default` 来提供默认样式变量的文件。
    *
    * @default "@vuepress/plugin-sass-palette/styles/default/config.scss"
    */
@@ -35,11 +35,11 @@ export interface SassPalettePluginOptions {
   /**
    * User palette file path, relative to source dir.
    *
-   * @description This is the file where user control injected css variables. All the variables will be converted in to kebab-case and injected.
-   *
    * 用户的调色板文件路径，相对于源文件夹。
    *
-   * @description 这是用户控制注入 CSS 变量的文件。所有的变量会被转换为连字符格式然后被注入。
+   * @description This is the file where user-controlled injected CSS variables. All the variables will be converted to kebab-case and injected.
+   *
+   * 这是用户控制注入 CSS 变量的文件。所有的变量会被转换为连字符格式然后被注入。
    *
    * @default `.vuepress/styles/${id}-palette.scss`
    */
@@ -48,23 +48,22 @@ export interface SassPalettePluginOptions {
   /**
    * Default palette file path, should be absolute path.
    *
-   * @description This is the file you should use to provide default css variables with `!default`. All the variable will be converted in to kebab-case and injected.
-   *
    * 默认的调色板文件路径，应为绝对路径。
    *
-   * @description 这是你应该通过 `!default` 来提供默认调色板值的文件。所有的变量会被转换为连字符格式然后被注入。
+   * @description This is the file you should use to provide default CSS variables with `!default`. All the variables will be converted to kebab-case and injected.
+   *
+   * 这是你应该通过 `!default` 来提供默认调色板值的文件。所有的变量会被转换为连字符格式然后被注入。
    */
-
   defaultPalette?: string
 
   /**
    * Custom generator, used to generate derivative values with palette config
    *
-   * e.g: You may want to provide a `$theme-color-light` based on `$themeColor`.
-   *
    * 自定义的生成器，用于生成调色板配置的衍生值。
    *
-   * 如: 你可能想要根据 `$theme-color` 的值提供一个 `$theme-color-light`。
+   * @description You may want to provide a `$theme-color-light` based on `$theme-color`.
+   *
+   * 你可能想要根据 `$theme-color` 的值提供一个 `$theme-color-light`。
    */
   generator?: string
 

plugins/development/plugin-sass-palette/src/node/removePalettePlugin.ts

@@ -1,12 +1,28 @@
 import type { App, PluginObject } from 'vuepress/core'
+import { PLUGIN_NAME } from './utils.js'
 
+/**
+ * Remove sass palette plugin with specific id
+ *
+ * 移除指定 ID 的 Sass 调色板插件
+ *
+ * @description Remove a sass palette plugin instance from app by id to avoid conflicts.
+ *
+ * 通过 ID 从应用中移除一个 Sass 调色板插件实例以避免冲突。
+ *
+ * @example
+ * ```ts
+ * // Remove palette plugin with id "hope"
+ * removePalettePlugin(app, "hope")
+ * ```
+ */
 export const removePalettePlugin = (app: App, id: string): void => {
   const { plugins } = app.pluginApi
 
   const index = plugins
     .filter<
       PluginObject & { id: string }
-    >((plugin): plugin is PluginObject & { id: string } => plugin.name === `@vuepress/plugin-sass-palette`)
+    >((plugin): plugin is PluginObject & { id: string } => plugin.name === PLUGIN_NAME)
     .findIndex((plugin) => plugin.id === id)
 
   if (index !== -1) plugins.splice(index, 1)

plugins/development/plugin-sass-palette/src/node/sassPalettePlugin.ts

@@ -15,6 +15,27 @@ import { EMPTY_FILE, PLUGIN_NAME, getIdPrefix, logger } from './utils.js'
 
 const __dirname = import.meta.dirname || getDirname(import.meta.url)
 
+/**
+ * Sass palette plugin
+ *
+ * Sass 调色板插件
+ *
+ * @description Plugin to provide palette and config file support for themes, allowing users to control theme colors and other style variables.
+ *
+ * 为主题提供调色板和配置文件支持的插件，允许用户控制主题颜色和其他样式变量。
+ *
+ * @example
+ * ```ts
+ * // Use with default options
+ * export default {
+ *   plugins: [
+ *     sassPalettePlugin({
+ *       id: "hope"
+ *     })
+ *   ]
+ * }
+ * ```
+ */
 export const sassPalettePlugin =
   (options: SassPalettePluginOptions): PluginFunction =>
   (app) => {