chore: upgrade docs

Author: sonofmagic

package.json

@@ -38,7 +38,7 @@
     "@commitlint/config-conventional": "^19.8.0",
     "@commitlint/prompt-cli": "^19.8.0",
     "@commitlint/types": "^19.8.0",
-    "@icebreakers/eslint-config": "^1.0.3",
+    "@icebreakers/eslint-config": "^1.0.4",
     "@icebreakers/monorepo": "^0.7.8",
     "@icebreakers/stylelint-config": "^1.0.0",
     "@rollup/pluginutils": "^5.1.4",
@@ -70,9 +70,11 @@
     "dedent": "^1.5.3",
     "defu": "^6.1.4",
     "del": "^8.0.0",
+    "dotenv": "^16.4.7",
     "eslint": "^9.22.0",
     "execa": "^9.5.2",
     "fast-glob": "^3.3.3",
+    "fdir": "^6.4.3",
     "fs-extra": "^11.3.0",
     "get-value": "^4.0.1",
     "html-minifier-terser": "^7.2.0",
@@ -87,7 +89,9 @@
     "mini-css-extract-plugin": "^2.9.2",
     "normalize-newline": "^4.1.0",
     "only-allow": "^1.2.1",
+    "openai": "^4.87.3",
     "pathe": "^2.0.3",
+    "picomatch": "^4.0.2",
     "pkg-types": "^2.1.0",
     "postcss": "^8.5.3",
     "postcss-loader": "^8.1.1",

pnpm-lock.yaml

@@ -1,5 +1,6 @@
 packages:
-  # - 'apps/*'
-  - 'packages/*'
-  - 'scripts/*'
+  - packages/*
+  - scripts/*
   - website
+onlyBuiltDependencies:
+  - esbuild

pnpm-workspace.yaml

@@ -1 +1,2 @@
-public/_pagefind
+public/_pagefind
+.env

website/.gitignore

@@ -1 +1 @@
-# TODO
+# 待办事项

website/content/en/config.mdx

@@ -1,29 +1,28 @@
-
 import { Callout } from 'nextra/components'
 
 # Welcome to Tailwindcss-mangle
 
 ## What is tailwindcss-mangle?
 
-This is a project for compressing and obfuscating the class names generated by `tailwindcss`.
+This is a project designed to compress and obfuscate class names generated by `tailwindcss`.
 
-The purpose of creating this library is to prevent easy copying and plagiarism of pages developed using `tailwindcss`. 
+The purpose of creating this library is that the pages we develop using `tailwindcss` are too easily copied and plagiarized.
 
-By using `tailwindcss-mangle`, it adds a bit of "cost" for potential copycats.
+Using `tailwindcss-mangle` can add a little cost to those who attempt to copy.
 
 ## How to use?
 
-Currently, the usage process is mainly divided into 2 steps:
+Currently, the usage is mainly divided into `2` steps:
 
 1. `Patch`
 2. `Mangle`
 
 ## Patch
 
-This step is used to apply a patch to `tailwindcss` that exposes the context, so it can extract the `Token` it uses internally.
+This step is used to patch `tailwindcss` to expose its context, thereby extracting the `Token` it generates from its internals.
 
-Eventually, it exports these as a `Json` file.
+Finally, it exports this into a `Json` file.
 
 ## Mangle
 
-This step reads the `Json` exported from `Patch` and escapes all the string literals and template strings corresponding to the `Token`.
+Read the `Json` exported by `Patch`, and escape all string literals and template strings corresponding to the `Token` inside.

website/content/en/index.mdx

@@ -1,58 +1,59 @@
 import { Callout } from 'nextra/components'
 
-# 2. Mangle
+# 2.Mangle
 
-## Feature Overview
+
+## Introduction
 
 ```html
-<!-- Before -->
+<!-- Before modification -->
 <div class="z-10 w-full max-w-5xl items-center justify-between font-mono text-sm lg:flex"></div>
-<!-- After -->
+<!-- After modification -->
 <div class="tw-g tw-h tw-i tw-d tw-e tw-j tw-k tw-l"></div>
 ```
 
 ## Usage
 
-### 1. Install the package
+### 1. Install Packages
 
-```sh
+```sh npm2yarn
 npm i -D unplugin-tailwindcss-mangle tailwindcss-patch
 ```
 
-### 2. Run the installation script
+### 2. Run the Installation Script
 
 ```sh
 npx tw-patch install
 ```
 
-### 3. Add the `prepare` script in `package.json`
+### 3. Add `prepare` Script in `package.json`
 
 ```json
   "scripts": {
     "prepare": "tw-patch install"
   },
 ```
 
-### 4. Run the extraction command
+### 4. Run the Extraction Command
 
-Navigate to the same directory as your `package.json` and `tailwind.config.js`, then run:
+Navigate to the directory containing `package.json` and `tailwind.config.js`, then run:
 
 ```sh
 npx tw-patch extract
 ```
 
-> See more options in [tailwindcss-patch](https://github.com/sonofmagic/tailwindcss-mangle/tree/main/packages/tailwindcss-patch)
+> Check out more options in [tailwindcss-patch](https://github.com/sonofmagic/tailwindcss-mangle/tree/main/packages/tailwindcss-patch)
 
 This will generate a JSON file: `.tw-patch/tw-class-list.json`
 
-### 5. Register this plugin
+### 5. Register the Plugin
 
 #### vite
 
 ```js
 import vue from '@vitejs/plugin-vue'
 import utwm from 'unplugin-tailwindcss-mangle/vite'
-// For example: vue vite project
+// For example: a vue vite project
 import { defineConfig } from 'vite'
 // https://vitejs.dev/config/
 export default defineConfig({
@@ -63,23 +64,23 @@ export default defineConfig({
 Then run the script:
 
 ```sh
-# Build the package
+# Generate build package
 yarn build
 # Preview
 yarn preview
 ```
 
-You will see that all class names are renamed to `tw-*`
+You will see all class names renamed to `tw-*`
 
 #### webpack
 
 ```js
 // esm
 import { webpackPlugin as utwm } from 'unplugin-tailwindcss-mangle'
-// Or cjs
+// or cjs
 const utwm = require('unplugin-tailwindcss-mangle/webpack')
 // Use this webpack plugin
-// For example in next.config.js
+// For example next.config.js
 const { defineConfig } = require('@vue/cli-service')
 // vue.config.js
 module.exports = defineConfig({
@@ -90,24 +91,25 @@ module.exports = defineConfig({
     }
   }
 })
+
 ```
 
 ## Notes
 
-This plugin only transforms utility class names that contain `-` or `:`, such as `w-32`, `before:h-[300px]`, `after:dark:via-[#0141ff]/40`. Some class names like `flex`, `relative` will not be transformed.
+This plugin will only transform utility classes containing `-` or `:`, such as `w-32`, `before:h-[300px]`, `after:dark:via-[#0141ff]/40`. Some class names like `flex`, `relative` will not be transformed.
 
-The plugin **traverses** all `html class` attributes and `js` string literals to find the utility classes generated by `tailwindcss`.
+Because the plugin will **traverse** all `html class` attributes and class names in `js` literals, looking for utility classes generated by `tailwindcss`.
 
-Transforming string literals like the following in `js` is dangerous:
+Transforming `js` literals like the following is dangerous:
 
 ```js
 const innerHTML = 'i\'m flex and relative and grid'
 document.body.innerHTML = innerHTML
 ```
 
-Thus, only strings containing `-` or `:` will be transformed.
+Therefore, only strings containing `-` or `:` will be transformed.
 
-Additionally, the plugin provides the `twIgnore` option, which allows some strings to be skipped during the `Mangle`.
+Additionally, the plugin provides an option `twIgnore` to skip `Mangle` for certain strings.
 
 For example:
 
@@ -123,4 +125,4 @@ const className = `${twIgnore`gap-y-4`} bg-zinc-800/30`;
 ```js
 const twIgnore = String.raw;
 const className = `${twIgnore`gap-y-4`} tw-a`;
-```
+```

website/content/en/mangle.mdx

@@ -1,26 +1,26 @@
 # 1. Patch
 
-This step is to export the context extracted from your `tailwindcss` as a `Json` file.
+This step is to export the context extracted from your `tailwindcss` into a `Json` file.
 
 ## Installation
 
-Install using your preferred package manager:
+Choose your preferred package manager for installation.
 
-```sh
+```sh npm2yarn
 npm i -D tailwindcss-patch
 ```
 
-### Apply the Patch
+### Patching
 
-1. Apply the patch to `tailwindcss`
+1. Patch `tailwindcss`
 
-```sh
+```sh npm2yarn
 npx tw-patch install
 ```
 
 ### Register npm hook
 
-1. Add the following command to the `prepare` hook in your `npm` configuration.
+1. Add the command to the `prepare` hook in `npm`
 
 `package.json`
 
@@ -35,25 +35,25 @@ npx tw-patch install
 
 ## Usage
 
-### Command-line Cli
+### Command Line Interface (CLI)
 
-#### Start Extraction
+#### Start Extracting
 
-```sh
+```sh npm2yarn
 npx tw-patch extract
 ```
 
-By default, after a successful execution, a `json` file `.tw-patch/tw-class-list.json` will be generated in your project.
+By default, a `json` file `.tw-patch/tw-class-list.json` will appear in your project upon successful execution.
 
-> Of course, you can customize this behavior using the configuration file `tailwindcss-mangle.config.ts`.
+> Of course, you can customize this behavior through the configuration file `tailwindcss-mangle.config.ts`.
 
-### Nodejs API 
+### Node.js API
 
 ```js
 import { TailwindcssPatcher } from 'tailwindcss-patch'
 
 const twPatcher = new TailwindcssPatcher(/* options */)
-// Perform the patch action
+// Perform patch action
 twPatcher.patch()
 // Get all contexts at runtime
 twPatcher.getContexts()
@@ -63,25 +63,25 @@ twPatcher.getClassSet()
 
 The core of this phase is to obtain the `.tw-patch/tw-class-list.json` file.
 
-Once it is generated, you can start the `Mangle` process.
+Once it is generated, we can proceed with our `Mangle` process.
 
 ## Configuration
 
 ### Initialization
 
-```sh
+```sh npm2yarn
 npx tw-patch init
 ```
 
-This will create a `tailwindcss-mangle.config.ts` file in your current `cwd`:
+This will create a `tailwindcss-mangle.config.ts` file in your current working directory (`cwd`):
 
 ```ts
 import { defineConfig } from 'tailwindcss-patch'
 
 export default defineConfig({})
 ```
 
-You can customize its behavior using the `patch` field:
+You can customize its behavior through the `patch` field:
 
 ```ts
 import { defineConfig } from 'tailwindcss-patch'

website/content/en/patch.mdx

@@ -0,0 +1,64 @@
+# Need to Extract More Metadata When Using Tailwindcss
+
+## Need More Information
+
+Currently, when `tailwindcss` extracts `Candidate` from files/content, it only extracts some string information and does not record the location.
+
+```html
+<div class="flex bg-slate-500/25" />
+            ↑  ↑  ↑               ↑
+          token1      token2
+```
+
+However, this makes it difficult for us to perform a project-level overall analysis.
+
+We cannot know how many tokens are extracted from a file, nor do we know in which files the extracted tokens exist (the relationship between files and tokens is usually many-to-many).
+
+Moreover, if there is a need to modify the generated product from the original source code later, we need to know the original position where the token was extracted.
+
+For example, transforming the extracted token string into an object like the one below:
+
+```ts
+interface Candidate {
+  value: string
+  file: string
+  start: number
+  end: number
+}
+```
+
+Here, `value` is the original string value, `file` is the file from which it was extracted, and `start` and `end` represent the position of this `token` in the file.
+
+This way, we can make precise modifications, such as:
+
+```diff filename="diff"
+// before
+- const className = `gap-y-4 bg-zinc-800/30`;
+// after
++ const className = `a b`;
+```
+
+Otherwise, currently, to make modifications, we have to apply the entire `Candidates` (`Set<string>`) to all files for replacement, which often leads to many unintended changes.
+
+With this, we only need to find the corresponding file and modify the nodes corresponding to its `start` and `end` to achieve the goal.
+
+In fact, this functionality ultimately resembles the `compile-class` feature of `unocss` [compile-class](https://unocss.dev/transformers/compile-class).
+
+## Tailwindcss v4
+
+https://github.com/tailwindlabs/tailwindcss/blob/437579d3f010a98ae4b824a7d5694486119fbdcd/crates/oxide/src/lib.rs#L108
+
+```rs
+    pub fn scan(&mut self) -> Vec<String> {
+        init_tracing();
+        self.prepare();
+        self.check_for_new_files();
+        self.compute_candidates();
+
+        let mut candidates: Vec<String> = self.candidates.clone().into_iter().collect();
+
+        candidates.sort();
+
+        candidates
+    }
+```