lone-format 0.9.1 → 0.9.6

package/dist/JSON_KEY_SORT.md

@@ -0,0 +1,168 @@
+# JSON Key Sorting Feature
+
+## 功能说明
+
+为 `JsonFormat` 组件添加了 JSON 对象 key 排序功能。该功能可以按字母顺序对所有对象的键进行排序，便于查看和比较 JSON 数据。
+
+## 特性
+
+✅ **递归排序**：深度遍历所有嵌套对象，对每个对象的 key 进行排序  
+✅ **保护原数据**：排序只影响显示，不修改原始 JSON 数据  
+✅ **支持过滤**：可以与过滤功能配合使用，对过滤后的数据进行排序  
+✅ **可逆操作**：可以随时清除排序，恢复原始 key 顺序  
+
+## API 使用
+
+### 1. 启用 Key 排序
+
+```typescript
+jsonFormatRef.value?.sortKeys()
+```
+
+调用后，组件会递归地对所有对象的 key 按字母顺序排序并重新渲染。
+
+### 2. 清除 Key 排序
+
+```typescript
+jsonFormatRef.value?.clearSortKeys()
+```
+
+恢复到原始 key 顺序。
+
+### 3. 检查排序状态
+
+```typescript
+const sorted = jsonFormatRef.value?.isSorted()
+```
+
+返回 `true` 表示当前启用了排序，`false` 表示未排序。
+
+## 完整示例
+
+```vue
+<template>
+  <div>
+    <div class="controls">
+      <button @click="toggleSort">
+        {{ isSortEnabled ? '清除排序' : '排序 Keys' }}
+      </button>
+    </div>
+    
+    <JsonFormat ref="jsonRef" v-model="jsonData" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import JsonFormat from 'lone-format/json-format'
+import type { JsonFormatExposed } from 'lone-format/json-format'
+
+const jsonRef = ref<JsonFormatExposed>()
+const isSortEnabled = ref(false)
+
+const jsonData = ref(JSON.stringify({
+  zebra: 'last',
+  apple: 'first',
+  mango: 'middle',
+  banana: 'second'
+}, null, 2))
+
+const toggleSort = () => {
+  if (isSortEnabled.value) {
+    jsonRef.value?.clearSortKeys()
+    isSortEnabled.value = false
+  } else {
+    jsonRef.value?.sortKeys()
+    isSortEnabled.value = true
+  }
+}
+</script>
+```
+
+## 排序示例
+
+### 排序前
+```json
+{
+  "zebra": "last animal",
+  "apple": "first fruit",
+  "mango": "tropical fruit",
+  "banana": "yellow fruit",
+  "user": {
+    "zipCode": "12345",
+    "age": 25,
+    "name": "Alice",
+    "email": "alice@example.com"
+  }
+}
+```
+
+### 排序后
+```json
+{
+  "apple": "first fruit",
+  "banana": "yellow fruit",
+  "mango": "tropical fruit",
+  "user": {
+    "age": 25,
+    "email": "alice@example.com",
+    "name": "Alice",
+    "zipCode": "12345"
+  },
+  "zebra": "last animal"
+}
+```
+
+## 实现原理
+
+1. **深度复制**：排序时创建数据的深度副本，保护原始数据
+2. **递归处理**：
+   - 对象：提取所有 key，按字母排序后重新构建对象
+   - 数组：递归处理每个元素
+   - 原始类型：直接返回
+3. **计算属性**：使用 Vue 的 `computed` 属性实现响应式排序
+4. **状态管理**：通过 `isSorted` 状态控制是否应用排序
+
+## 类型定义
+
+```typescript
+export interface JsonFormatExposed {
+  // ... 其他方法
+  
+  // Key 排序相关方法
+  sortKeys: () => void
+  clearSortKeys: () => void
+  isSorted: () => boolean
+}
+```
+
+## 使用场景
+
+- 📊 **数据对比**：对比两个 JSON 对象时，排序可以让 key 顺序一致
+- 🔍 **快速查找**：在大型 JSON 中按字母顺序查找特定字段
+- 📝 **文档生成**：生成 API 文档时保持字段顺序的一致性
+- ✅ **测试验证**：在单元测试中验证 JSON 结构时更容易比较
+
+## 注意事项
+
+1. **原数据保护**：排序功能不会修改 `v-model` 绑定的原始数据
+2. **性能考虑**：对于超大型 JSON（数千个对象），排序可能需要一些时间
+3. **数组顺序**：数组元素的顺序保持不变，只有对象的 key 会被排序
+4. **与过滤配合**：先应用过滤，再排序，或者反过来都可以
+
+## 测试
+
+项目中提供了测试页面 `test-key-sort.html`，可以直接在浏览器中打开测试排序功能。
+
+```bash
+# 打开测试页面
+open test-key-sort.html
+```
+
+## 更新日志
+
+- **v0.7.1+**: 新增 Key 排序功能
+  - 添加 `sortKeys()` API
+  - 添加 `clearSortKeys()` API
+  - 添加 `isSorted()` API
+  - 在 App.vue 的 Filter Test 标签页中集成排序按钮

package/dist/PIPELINE.md

@@ -0,0 +1,156 @@
+# Automated CI/CD Pipeline Setup
+
+This document explains how to set up and use the automated publishing pipeline for the lone-format project.
+
+## Overview
+
+The pipeline automatically handles:
+1. **Version Bumping**: Automatically increments version in `package.json`
+2. **Building**: Compiles and builds the library
+3. **Publishing**: Publishes to npmjs.com
+4. **Merging**: Merges publish branch to main after successful publish
+
+## Setup Instructions
+
+### 1. Required Secrets
+
+Add the following secrets to your GitHub repository settings:
+
+#### NPM_TOKEN
+1. Go to [npmjs.com](https://npmjs.com) and login
+2. Click your avatar → "Access Tokens"
+3. Click "Generate New Token" → "Automation" (for CI/CD)
+4. Copy the token
+5. In GitHub: Settings → Secrets and variables → Actions → New repository secret
+6. Name: `NPM_TOKEN`, Value: [your token]
+
+### 2. Branch Protection (Optional but Recommended)
+
+Configure branch protection for `main`:
+1. Go to Settings → Branches
+2. Add rule for `main` branch
+3. Check "Require status checks to pass before merging"
+4. Check "Require branches to be up to date before merging"
+
+## Usage
+
+### Automatic Trigger
+
+Push to the `publish` branch to trigger the pipeline:
+
+```bash
+git checkout publish
+git add .
+git commit -m "feat: add new feature"
+git push origin publish
+```
+
+### Version Bump Rules
+
+The pipeline automatically determines version bump type from commit messages:
+
+- **Patch** (0.1.6 → 0.1.7): Default for any commit
+- **Minor** (0.1.6 → 0.2.0): Commits with `feat:` or `minor:` prefix
+- **Major** (0.1.6 → 1.0.0): Commits with `BREAKING CHANGE` or `major:` prefix
+
+### Examples
+
+```bash
+# Patch version bump
+git commit -m "fix: resolve issue with JSON parsing"
+
+# Minor version bump  
+git commit -m "feat: add new theme support"
+
+# Major version bump
+git commit -m "major: complete API redesign
+
+BREAKING CHANGE: API has been completely redesigned"
+```
+
+### Manual Trigger
+
+You can also trigger the pipeline manually:
+1. Go to Actions → "Auto Publish and Merge" workflow
+2. Click "Run workflow"
+3. Select branch `publish` and version type
+4. Click "Run workflow"
+
+## Pipeline Steps
+
+### 1. Build and Publish Job
+- Checks out `publish` branch
+- Sets up Node.js environment
+- Installs dependencies
+- Bumps version based on commit message
+- Builds the library
+- Publishes to npm
+- Commits version changes back to `publish`
+
+### 2. Merge to Main Job
+- Merges `publish` branch to `main`
+- Creates a git tag for the release
+- Creates a GitHub release with changelog
+
+## Workflow Files
+
+The project includes two workflow options:
+
+### `publish.yml` - Full Featured
+- Includes PR creation and auto-merge
+- More complex error handling
+- Better for teams with review processes
+
+### `simple-publish.yml` - Streamlined
+- Direct merge to main (no PRs)
+- Simpler and faster
+- Better for solo developers or trusted teams
+
+## Troubleshooting
+
+### Build Failures
+If the build fails, the pipeline will still attempt to publish with minimal assets. Check the Actions logs for details.
+
+### NPM Publishing Errors
+- Verify `NPM_TOKEN` is set correctly
+- Ensure you have publish permissions for the package
+- Check if the version already exists on npm
+
+### Merge Conflicts
+If merge conflicts occur:
+1. Manually resolve conflicts in `publish` branch
+2. Push the resolved conflicts
+3. The pipeline will retry automatically
+
+## Package Configuration
+
+The `package.json` includes these helpful scripts:
+
+```json
+{
+  "scripts": {
+    "build:lib": "vite build --mode lib",
+    "build:lib:full": "vue-tsc -b && vite build --mode lib", 
+    "publish:lib": "npm publish --access public",
+    "publish:dry": "npm publish --dry-run",
+    "version:patch": "npm version patch --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version", 
+    "version:major": "npm version major --no-git-tag-version"
+  }
+}
+```
+
+## Security Notes
+
+- Never commit `NPM_TOKEN` to the repository
+- Use automation tokens, not personal access tokens
+- Regularly rotate your npm tokens
+- Monitor npm package downloads and versions
+
+## Support
+
+If you encounter issues with the pipeline:
+1. Check the Actions tab for detailed logs
+2. Verify all secrets are properly configured
+3. Ensure branch permissions are correctly set
+4. Review commit message format for version bumping

package/dist/PUBLISH_WORKFLOW.md

@@ -0,0 +1,128 @@
+# 发布工作流程说明
+
+## 📋 概述
+
+当代码推送到 `main` 分支时，GitHub Actions 会自动执行以下流程：
+
+## 🔄 工作流程
+
+### 1. 触发条件
+- **自动触发**: Push 到 `main` 分支
+- **手动触发**: 通过 GitHub Actions UI 手动执行（可选择版本类型）
+
+### 2. 执行步骤
+
+#### Step 1: 在 main 分支升级版本
+1. Checkout `main` 分支
+2. 安装依赖
+3. 根据提交信息自动判断版本升级类型：
+   - `BREAKING CHANGE` 或 `major:` → major 版本
+   - `feat:` 或 `minor:` → minor 版本
+   - 其他 → patch 版本
+4. 执行 `npm version` 升级版本号
+5. 提交版本变更到 `main` 分支（带 `[skip ci]` 避免循环触发）
+
+#### Step 2: 合并到 publish 分支
+1. Fetch `publish` 分支（如不存在则创建）
+2. 切换到 `publish` 分支
+3. 将 `main` 分支合并到 `publish`
+4. 推送 `publish` 分支
+
+#### Step 3: 构建和发布
+1. 在 `publish` 分支执行 `npm run build:lib`
+2. 发布到 npm（使用 NPM_TOKEN secret）
+3. 创建 Git Tag（格式：`vX.Y.Z`）
+4. 推送 Tag 到远程仓库
+
+### 3. 通知结果
+- ✅ 成功：显示发布的版本号
+- ❌ 失败：显示错误信息
+
+## 🎯 分支策略
+
+- **main**: 开发主分支，所有功能开发完成后合并到此分支
+- **publish**: 发布分支，从 main 合并，用于构建和发布到 npm
+- **dev**: 开发分支（可选），用于日常开发
+
+## 📝 提交信息规范
+
+为了自动判断版本升级类型，建议遵循以下提交信息规范：
+
+- `feat: 新功能` → 触发 minor 版本升级
+- `fix: 修复bug` → 触发 patch 版本升级
+- `BREAKING CHANGE: 重大变更` → 触发 major 版本升级
+- `chore: 日常维护` → 触发 patch 版本升级
+
+## ⚙️ 配置要求
+
+### GitHub Secrets
+需要在 GitHub 仓库设置中添加以下 Secret：
+
+- `NPM_TOKEN`: npm 发布令牌
+  - 获取方式：npm 官网 → Access Tokens → Generate New Token → Automation
+
+### 权限设置
+工作流需要以下权限：
+- `contents: write` - 写入仓库内容
+- `pull-requests: write` - 创建 PR
+- `packages: write` - 发布包
+
+## 🚀 使用示例
+
+### 自动发布（推荐）
+```bash
+# 1. 在 dev 分支开发
+git checkout dev
+# ... 进行开发 ...
+
+# 2. 提交代码
+git add .
+git commit -m "feat: 添加新功能"
+git push origin dev
+
+# 3. 合并到 main 分支
+git checkout main
+git merge dev
+git push origin main  # 这会自动触发发布流程
+```
+
+### 手动发布
+1. 访问 GitHub 仓库
+2. 点击 "Actions" 标签
+3. 选择 "Auto Publish and Merge" 工作流
+4. 点击 "Run workflow"
+5. 选择版本类型（patch/minor/major）
+6. 点击 "Run workflow" 按钮
+
+## 🔍 监控和调试
+
+### 查看发布状态
+1. 访问仓库的 Actions 页面
+2. 查看最新的工作流运行记录
+3. 点击查看详细日志
+
+### 常见问题
+
+**Q: 发布失败怎么办？**
+A: 检查以下几点：
+- NPM_TOKEN 是否正确配置
+- package.json 中的 name 和 version 是否正确
+- 是否有足够的权限发布到 npm
+
+**Q: 如何跳过自动发布？**
+A: 在提交信息中添加 `[skip ci]`
+
+**Q: 如何回滚版本？**
+A: 需要手动执行：
+```bash
+npm unpublish <package-name>@<version>
+git tag -d v<version>
+git push origin :refs/tags/v<version>
+```
+
+## 📌 注意事项
+
+1. **避免循环触发**: 版本提交使用 `[skip ci]` 标记
+2. **分支保护**: 建议为 `main` 和 `publish` 分支启用保护规则
+3. **发布前测试**: 确保在 `dev` 分支充分测试后再合并到 `main`
+4. **版本管理**: 遵循语义化版本规范（Semantic Versioning）

package/dist/SETUP_CHECKLIST.md

@@ -0,0 +1,64 @@
+# CI/CD Pipeline Setup Checklist
+
+## ✅ Completed Tasks
+
+- [x] Created GitHub Actions workflows for automated publishing
+- [x] Configured automatic version bumping based on commit messages  
+- [x] Set up npm publishing automation
+- [x] Implemented automatic merge from publish to main branch
+- [x] Added comprehensive documentation
+- [x] Created local testing script
+- [x] Updated build configuration for better reliability
+- [x] Enhanced README with pipeline information
+
+## 📋 Setup Requirements
+
+### Required GitHub Secrets
+- [ ] `NPM_TOKEN` - Automation token from npmjs.com
+
+### Branch Setup
+- [ ] Create `publish` branch for triggering deployments
+- [ ] Configure branch protection on `main` (optional but recommended)
+
+## 🚀 Usage Instructions
+
+### Automated Publishing Flow
+1. Make changes on any branch
+2. Merge/push to `publish` branch
+3. Pipeline automatically:
+   - Bumps version based on commit message
+   - Builds the library  
+   - Publishes to npm
+   - Merges to main branch
+   - Creates GitHub release
+
+### Commit Message Conventions
+- `fix:` or default → patch version (0.1.6 → 0.1.7)
+- `feat:` or `minor:` → minor version (0.1.6 → 0.2.0)  
+- `BREAKING CHANGE` or `major:` → major version (0.1.6 → 1.0.0)
+
+## 📄 Files Created
+
+1. `.github/workflows/publish.yml` - Full-featured workflow with PR creation
+2. `.github/workflows/simple-publish.yml` - Streamlined direct-merge workflow
+3. `PIPELINE.md` - Detailed setup and usage documentation
+4. `scripts/test-pipeline.sh` - Local testing script
+5. Updated `README.md` with pipeline information
+6. Updated `package.json` with additional scripts
+7. Enhanced `vite.config.ts` for better builds
+
+## ⚠️ Important Notes
+
+- The `simple-publish.yml` workflow is recommended for most use cases
+- Disable `publish.yml` if using `simple-publish.yml` to avoid conflicts
+- Ensure NPM_TOKEN has publish permissions for the package
+- Test locally with `./scripts/test-pipeline.sh` before first use
+
+## 🔧 Next Steps
+
+1. Add `NPM_TOKEN` to GitHub repository secrets
+2. Create and test `publish` branch
+3. Make a test commit to verify the pipeline works
+4. Monitor first automated publish for any issues
+
+Pipeline is ready for production use! 🎉

package/dist/filter-simple-test.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Filter Test</title>
+  <script src="./dist/lone-format.umd.cjs"></script>
+  <link rel="stylesheet" href="./dist/lone-format.css">
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      margin: 20px;
+    }
+
+    .test-section {
+      margin: 20px 0;
+      padding: 20px;
+      border: 1px solid #ccc;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>Filter Feature Test</h1>
+
+  <div class="test-section">
+    <h3>Test 1: Basic Filter</h3>
+    <div id="test1"></div>
+  </div>
+
+  <script>
+    // Test basic filter functionality
+    console.log('LoneFormat:', typeof window.LoneFormat);
+    console.log('JsonFormat:', window.LoneFormat?.JsonFormat);
+
+    // Test data
+    const testData = {
+      "users": [
+        { "id": 1, "name": "Alice", "age": 25 },
+        { "id": 2, "name": "Bob", "age": 30 }
+      ],
+      "company": "Test Corp"
+    };
+
+    const jsonString = JSON.stringify(testData, null, 2);
+
+    // Create a simple test
+    document.getElementById('test1').innerHTML = `
+            <textarea rows="10" cols="50">${jsonString}</textarea>
+            <p>Filter functionality is available in the main app.</p>
+        `;
+  </script>
+</body>
+
+</html>