From a111afc781f3168120be6bf36f66cdbd4fd9dc71 Mon Sep 17 00:00:00 2001
From: RyanVan <150385913+Ryson-32@users.noreply.github.com>
Date: Sun, 26 Jul 2026 23:38:51 +0800
Subject: [PATCH 1/2] feat(ui): clarify automatic filter helper

---
 .../src/components/ui/form-controls.test.ts   | 28 +++++++++++++++
 packages/ui/src/components/ui/form-field.tsx  | 31 +++++++++++-----
 .../auto-processing-dialog.test.ts            | 35 +++++++++++++++----
 .../auto-processing-dialog.tsx                |  3 +-
 4 files changed, 81 insertions(+), 16 deletions(-)

diff --git a/packages/ui/src/components/ui/form-controls.test.ts b/packages/ui/src/components/ui/form-controls.test.ts
index f8a7681..20b5a02 100644
--- a/packages/ui/src/components/ui/form-controls.test.ts
+++ b/packages/ui/src/components/ui/form-controls.test.ts
@@ -40,6 +40,34 @@ describe("composed form controls", () => {
     expect(html).toContain('aria-invalid="true"');
     expect(html).toContain('aria-required="true"');
     expect(html).toContain('role="alert"');
+    expect(html.indexOf("账号")).toBeLessThan(html.indexOf("<input"));
+    expect(html.indexOf("<input")).toBeLessThan(html.indexOf("用于登录"));
+  });
+
+  it("can place compact helper text between the label and control", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(
+        FormField,
+        {
+          id: "exclude-regex",
+          label: "排除正则",
+          description: "每行一条，匹配到的节点会被全局排除，关闭后恢复。",
+          descriptionPlacement: "before-control",
+        },
+        React.createElement(Input)
+      )
+    );
+    const labelIndex = html.indexOf("排除正则");
+    const descriptionIndex = html.indexOf(
+      "每行一条，匹配到的节点会被全局排除，关闭后恢复。"
+    );
+    const controlIndex = html.indexOf("<input");
+
+    expect(labelIndex).toBeGreaterThanOrEqual(0);
+    expect(descriptionIndex).toBeGreaterThan(labelIndex);
+    expect(controlIndex).toBeGreaterThan(descriptionIndex);
+    expect(html).toContain('class="space-y-1"');
+    expect(html).toContain('aria-describedby="exclude-regex-description"');
   });
 
   it("renders a disabled, labelled switch with its description", () => {
diff --git a/packages/ui/src/components/ui/form-field.tsx b/packages/ui/src/components/ui/form-field.tsx
index 9cfc3b9..96f458a 100644
--- a/packages/ui/src/components/ui/form-field.tsx
+++ b/packages/ui/src/components/ui/form-field.tsx
@@ -15,6 +15,7 @@ export interface FormFieldProps {
   id?: string;
   label: React.ReactNode;
   description?: React.ReactNode;
+  descriptionPlacement?: "before-control" | "after-control";
   error?: React.ReactNode;
   required?: boolean;
   className?: string;
@@ -29,6 +30,7 @@ function FormField({
   id,
   label,
   description,
+  descriptionPlacement = "after-control",
   error,
   required = false,
   className,
@@ -51,19 +53,30 @@ function FormField({
     "aria-invalid": error ? true : controlChild.props["aria-invalid"],
     "aria-required": required || controlChild.props["aria-required"] || undefined,
   });
+  const labelElement = (
+    <Label htmlFor={controlChild.props.id ?? controlId}>
+      {label}
+      {required ? <span aria-hidden="true" className="ml-1 text-red-400">*</span> : null}
+    </Label>
+  );
+  const descriptionElement = description ? (
+    <p id={descriptionId} className="text-xs leading-relaxed text-white/45">
+      {description}
+    </p>
+  ) : null;
 
   return (
     <div className={cn("space-y-2", className)}>
-      <Label htmlFor={controlChild.props.id ?? controlId}>
-        {label}
-        {required ? <span aria-hidden="true" className="ml-1 text-red-400">*</span> : null}
-      </Label>
+      {descriptionPlacement === "before-control" && descriptionElement ? (
+        <div className="space-y-1">
+          {labelElement}
+          {descriptionElement}
+        </div>
+      ) : (
+        labelElement
+      )}
       {control}
-      {description ? (
-        <p id={descriptionId} className="text-xs leading-relaxed text-white/45">
-          {description}
-        </p>
-      ) : null}
+      {descriptionPlacement === "after-control" ? descriptionElement : null}
       {error ? (
         <p id={errorId} className="text-xs leading-relaxed text-red-400" role="alert">
           {error}
diff --git a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
index 8912c76..ae58aa7 100644
--- a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
+++ b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
@@ -6,6 +6,7 @@ import type { ParsedNode } from "@subboost/core/types/node";
 const mocks = vi.hoisted(() => ({
   buttons: [] as Array<Record<string, any>>,
   dialog: null as Record<string, any> | null,
+  formField: null as Record<string, any> | null,
   switchField: null as Record<string, any> | null,
   textarea: null as Record<string, any> | null,
 }));
@@ -28,15 +29,23 @@ vi.mock("@subboost/ui/components/ui/dialog", () => ({
   DialogTitle: (props: any) => React.createElement("h2", null, props.children),
 }));
 vi.mock("@subboost/ui/components/ui/form-field", () => ({
-  FormField: (props: any) =>
-    React.createElement(
+  FormField: (props: any) => {
+    mocks.formField = props;
+    const label = React.createElement("label", null, props.label);
+    const description = props.description
+      ? React.createElement("p", null, props.description)
+      : null;
+    return React.createElement(
       "div",
       null,
-      React.createElement("label", null, props.label),
+      props.descriptionPlacement === "before-control"
+        ? React.createElement("div", null, label, description)
+        : label,
       props.children,
-      props.description ? React.createElement("p", null, props.description) : null,
+      props.descriptionPlacement === "before-control" ? null : description,
       props.error ? React.createElement("p", { role: "alert" }, props.error) : null
-    ),
+    );
+  },
 }));
 vi.mock("@subboost/ui/components/ui/switch-field", () => ({
   SwitchField: (props: any) => {
@@ -111,6 +120,7 @@ describe("NodeManagementAutoProcessingDialog", () => {
   beforeEach(() => {
     mocks.buttons = [];
     mocks.dialog = null;
+    mocks.formField = null;
     mocks.switchField = null;
     mocks.textarea = null;
   });
@@ -121,12 +131,25 @@ describe("NodeManagementAutoProcessingDialog", () => {
     expect(html).toContain("自动处理");
     expect(html).toContain("启用");
     expect(html).toContain("排除正则");
-    expect(html).toContain("每行一条，匹配导入名称。");
+    expect(html).toContain("每行一条，匹配到的节点会被全局排除，关闭后恢复。");
     expect(html).toContain("剩余流量|套餐到期|注意事项");
+    expect(html.indexOf("排除正则")).toBeLessThan(
+      html.indexOf("每行一条，匹配到的节点会被全局排除，关闭后恢复。")
+    );
+    expect(
+      html.indexOf("每行一条，匹配到的节点会被全局排除，关闭后恢复。")
+    ).toBeLessThan(html.indexOf("剩余流量|套餐到期|注意事项"));
     expect(html).toContain("导入 2 · 排除 1 · 保留 1");
     expect(html).toContain("[HK] Alpha");
     expect(html).toContain("原名：Alpha");
     expect(html).not.toContain("原名：Beta");
+    expect(mocks.formField).toEqual(
+      expect.objectContaining({
+        description: "每行一条，匹配到的节点会被全局排除，关闭后恢复。",
+        descriptionPlacement: "before-control",
+        label: "排除正则",
+      })
+    );
     expect(mocks.switchField).toEqual(
       expect.objectContaining({ checked: true, label: "启用" })
     );
diff --git a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
index 6842b1f..8c12197 100644
--- a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
+++ b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
@@ -118,7 +118,8 @@ export function NodeManagementAutoProcessingDialog({
 
         <FormField
           label="排除正则"
-          description="每行一条，匹配导入名称。"
+          description="每行一条，匹配到的节点会被全局排除，关闭后恢复。"
+          descriptionPlacement="before-control"
           error={validationMessage}
         >
           <Textarea

From 575d7c4c6500150fbef79c09b271dddc39815110 Mon Sep 17 00:00:00 2001
From: RyanVan <150385913+Ryson-32@users.noreply.github.com>
Date: Mon, 27 Jul 2026 00:32:15 +0800
Subject: [PATCH 2/2] fix(ui): preserve automatic filter matching guidance

---
 .../ui/src/components/ui/form-controls.test.ts     |  5 ++---
 .../node-management/auto-processing-dialog.test.ts | 14 +++++++-------
 .../node-management/auto-processing-dialog.tsx     |  2 +-
 3 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/packages/ui/src/components/ui/form-controls.test.ts b/packages/ui/src/components/ui/form-controls.test.ts
index 20b5a02..ea3b6f4 100644
--- a/packages/ui/src/components/ui/form-controls.test.ts
+++ b/packages/ui/src/components/ui/form-controls.test.ts
@@ -51,7 +51,7 @@ describe("composed form controls", () => {
         {
           id: "exclude-regex",
           label: "排除正则",
-          description: "每行一条，匹配到的节点会被全局排除，关闭后恢复。",
+          description: "每行一条，按节点导入时的原始名称匹配。",
           descriptionPlacement: "before-control",
         },
         React.createElement(Input)
@@ -59,14 +59,13 @@ describe("composed form controls", () => {
     );
     const labelIndex = html.indexOf("排除正则");
     const descriptionIndex = html.indexOf(
-      "每行一条，匹配到的节点会被全局排除，关闭后恢复。"
+      "每行一条，按节点导入时的原始名称匹配。"
     );
     const controlIndex = html.indexOf("<input");
 
     expect(labelIndex).toBeGreaterThanOrEqual(0);
     expect(descriptionIndex).toBeGreaterThan(labelIndex);
     expect(controlIndex).toBeGreaterThan(descriptionIndex);
-    expect(html).toContain('class="space-y-1"');
     expect(html).toContain('aria-describedby="exclude-regex-description"');
   });
 
diff --git a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
index ae58aa7..5d25b11 100644
--- a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
+++ b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.test.ts
@@ -127,25 +127,25 @@ describe("NodeManagementAutoProcessingDialog", () => {
 
   it("renders the compact wording, counts, and matching display/origin names", () => {
     const { html } = renderDialog();
+    const helperText =
+      "每行一条，按节点导入时的原始名称匹配；命中节点会在生成配置时全局排除，关闭后恢复。";
 
     expect(html).toContain("自动处理");
     expect(html).toContain("启用");
     expect(html).toContain("排除正则");
-    expect(html).toContain("每行一条，匹配到的节点会被全局排除，关闭后恢复。");
+    expect(html).toContain(helperText);
     expect(html).toContain("剩余流量|套餐到期|注意事项");
-    expect(html.indexOf("排除正则")).toBeLessThan(
-      html.indexOf("每行一条，匹配到的节点会被全局排除，关闭后恢复。")
+    expect(html.indexOf("排除正则")).toBeLessThan(html.indexOf(helperText));
+    expect(html.indexOf(helperText)).toBeLessThan(
+      html.indexOf("剩余流量|套餐到期|注意事项")
     );
-    expect(
-      html.indexOf("每行一条，匹配到的节点会被全局排除，关闭后恢复。")
-    ).toBeLessThan(html.indexOf("剩余流量|套餐到期|注意事项"));
     expect(html).toContain("导入 2 · 排除 1 · 保留 1");
     expect(html).toContain("[HK] Alpha");
     expect(html).toContain("原名：Alpha");
     expect(html).not.toContain("原名：Beta");
     expect(mocks.formField).toEqual(
       expect.objectContaining({
-        description: "每行一条，匹配到的节点会被全局排除，关闭后恢复。",
+        description: helperText,
         descriptionPlacement: "before-control",
         label: "排除正则",
       })
diff --git a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
index 8c12197..6334a34 100644
--- a/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
+++ b/packages/ui/src/product/converter/advanced-mode/sections/node-management/auto-processing-dialog.tsx
@@ -118,7 +118,7 @@ export function NodeManagementAutoProcessingDialog({
 
         <FormField
           label="排除正则"
-          description="每行一条，匹配到的节点会被全局排除，关闭后恢复。"
+          description="每行一条，按节点导入时的原始名称匹配；命中节点会在生成配置时全局排除，关闭后恢复。"
           descriptionPlacement="before-control"
           error={validationMessage}
         >