feat(ui): clarify automatic filter helper

Author: Ryson-32

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", () => {

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}

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: "启用" })
     );

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