feat(web): add dialog header alias

Author: pallyoung

packages/web/src/components/ui/index.ts

@@ -23,7 +23,7 @@ export { Input } from "./input";
 export type { KbdProps } from "./kbd";
 export { Kbd } from "./kbd";
 export type { ModalProps, ModalSize } from "./modal";
-export { Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from "./modal";
+export { DialogHeader, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from "./modal";
 export type { NoticeProps, NoticeTone } from "./notice";
 export { Notice } from "./notice";
 export type { PillProps } from "./pill";

packages/web/src/components/ui/modal/README.md

@@ -5,9 +5,9 @@
 
 ```tsx
 <Modal open onOpenChange={setOpen}>
-  <ModalHeader>
+  <DialogHeader>
     <ModalTitle>Workspace details</ModalTitle>
-  </ModalHeader>
+  </DialogHeader>
   <ModalBody>Body</ModalBody>
   <ModalFooter>Footer</ModalFooter>
 </Modal>
@@ -26,4 +26,6 @@
 ## 注意
 - 组件通过 portal 渲染到 `document.body`。
 - 打开后会把焦点移入弹窗，关闭后恢复到先前焦点。
+- `DialogHeader` 是弹层 header 的 canonical 入口；`ModalHeader` 保留为兼容命名。
+- 如需标准化 icon / copy / description 结构，使用 `dialog-header__leading`、`dialog-header__icon`、`dialog-header__copy`、`dialog-header__description`。
 - 迁移期仍保留 `modal-overlay`、`modal-card`、`modal-header`、`modal-title`、`modal-body`、`modal-footer` 等兼容类名。

packages/web/src/components/ui/modal/index.module.css

@@ -53,6 +53,47 @@
   border-bottom: 1px solid var(--border);
 }
 
+.dialogHeader,
+:global(.dialog-header) {
+  align-items: flex-start;
+}
+
+:global(.dialog-header__leading) {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sp-3);
+  min-width: 0;
+  flex: 1;
+}
+
+:global(.dialog-header__copy) {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+}
+
+:global(.dialog-header__icon) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-md);
+  flex-shrink: 0;
+  background: var(--bg-hover);
+  color: var(--text-secondary);
+}
+
+:global(.dialog-header__description) {
+  margin: 0;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+  color: var(--text-tertiary);
+}
+
 .title,
 :global(.modal-title) {
   display: flex;
@@ -110,6 +151,8 @@
 
   .header,
   :global(.modal-header),
+  .dialogHeader,
+  :global(.dialog-header),
   .body,
   :global(.modal-body),
   .footer,

packages/web/src/components/ui/modal/index.test.tsx

@@ -2,7 +2,7 @@ import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createRef } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from ".";
+import { DialogHeader, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle } from ".";
 
 const activeElementState = {
   current: null as HTMLElement | null,
@@ -78,6 +78,20 @@ describe("Modal", () => {
     expect(document.body).toContainElement(dialog);
   });
 
+  it("exports DialogHeader as the canonical modal header alias", () => {
+    render(
+      <DialogHeader>
+        <ModalTitle>Workspace details</ModalTitle>
+      </DialogHeader>
+    );
+
+    const header = document.querySelector(".dialog-header");
+
+    expect(header).not.toBeNull();
+    expect(header).toHaveClass("modal-header");
+    expect(screen.getByText("Workspace details")).toBeInTheDocument();
+  });
+
   it("applies the large card variant for size='lg'", () => {
     render(<ModalFixture size="lg" />);
 

packages/web/src/components/ui/modal/index.tsx

@@ -134,6 +134,21 @@ export function ModalHeader({ className, ...props }: HTMLAttributes<HTMLDivEleme
   return <div {...props} className={clsx(styles.header, "modal-header", className)} />;
 }
 
+export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      {...props}
+      className={clsx(
+        styles.header,
+        styles.dialogHeader,
+        "modal-header",
+        "dialog-header",
+        className
+      )}
+    />
+  );
+}
+
 export function ModalTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
   const context = useContext(ModalContext);
   const fallbackId = useId();

packages/web/src/features/supervisor/components/objective-dialog.test.tsx

@@ -203,6 +203,43 @@ describe("ObjectiveDialog", () => {
     expect(screen.getByRole("dialog")).toHaveClass("supervisor-dialog--disable");
   });
 
+  it("renders the dialog header through the canonical dialog header anatomy", () => {
+    const store = createStore();
+    window.localStorage.setItem("ui.locale", JSON.stringify("en"));
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand: vi.fn() } as never);
+    store.set(
+      supervisorDialogAtom,
+      createDialogState({
+        mode: "disable",
+      })
+    );
+    store.set(supervisorsAtom, new Map([["sess-1", createSupervisor()]]));
+
+    render(
+      <Provider store={store}>
+        <ObjectiveDialog workspaceId="ws-1" />
+      </Provider>
+    );
+
+    const dialog = screen.getByRole("dialog");
+    const header = dialog.querySelector(".dialog-header");
+    const leading = header?.querySelector(".dialog-header__leading");
+    const icon = header?.querySelector(".dialog-header__icon");
+    const copy = header?.querySelector(".dialog-header__copy");
+    const description = header?.querySelector(".dialog-header__description");
+    const closeButton = screen.getByRole("button", { name: "Close" });
+
+    expect(header).not.toBeNull();
+    expect(leading).not.toBeNull();
+    expect(icon).not.toBeNull();
+    expect(copy).not.toBeNull();
+    expect(description).toHaveTextContent(
+      "Stop automatic evaluation. The current session's supervision cycles will be removed."
+    );
+    expect(closeButton).toHaveClass("modal-close");
+  });
+
   it("renders footer actions with shared button compatibility classes", () => {
     const store = createStore();
     window.localStorage.setItem("ui.locale", JSON.stringify("en"));

packages/web/src/features/supervisor/views/shared/objective-dialog.tsx

@@ -1,11 +1,11 @@
 import { X } from "lucide-react";
 import {
   Button,
+  DialogHeader,
   IconButton,
   Modal,
   ModalBody,
   ModalFooter,
-  ModalHeader,
   ModalTitle,
 } from "../../../../components/ui";
 import { useViewport } from "../../../../hooks/use-viewport";
@@ -40,23 +40,24 @@ export function ObjectiveDialog({ workspaceId, sessionId }: ObjectiveDialogProps
 
   return (
     <Modal className={`supervisor-dialog supervisor-dialog--${mode}`} onOpenChange={close} open>
-      <ModalHeader>
-        <div className="supervisor-dialog-header">
-          <span className="supervisor-dialog-header-icon" aria-hidden="true">
+      <DialogHeader>
+        <div className="dialog-header__leading">
+          <span className="dialog-header__icon supervisor-dialog-header-icon" aria-hidden="true">
             <ObjectiveDialogModeIcon mode={mode} />
           </span>
-          <div>
+          <div className="dialog-header__copy">
             <ModalTitle>{copy.title}</ModalTitle>
-            <span className="supervisor-dialog-subtitle">{copy.subtitle}</span>
+            <p className="dialog-header__description">{copy.subtitle}</p>
           </div>
         </div>
         <IconButton
           aria-label={t("action.close")}
+          className="modal-close"
           icon={<X size={14} />}
           onClick={close}
           size="sm"
         />
-      </ModalHeader>
+      </DialogHeader>
 
       <ModalBody>
         <ObjectiveDialogContent

packages/web/src/styles/components.css

@@ -3741,13 +3741,6 @@ body.is-resizing-panels * {
   line-height: 1.25;
 }
 
-.supervisor-dialog-header {
-  display: flex;
-  align-items: center;
-  gap: var(--sp-3);
-  min-width: 0;
-}
-
 .supervisor-dialog-header-icon {
   display: inline-flex;
   align-items: center;
@@ -3759,24 +3752,16 @@ body.is-resizing-panels * {
   color: var(--icon-success);
 }
 
-.supervisor-dialog[data-mode="edit"] .supervisor-dialog-header-icon {
+.supervisor-dialog--edit .supervisor-dialog-header-icon {
   background: var(--icon-surface-info);
   color: var(--icon-info);
 }
 
-.supervisor-dialog[data-mode="disable"] .supervisor-dialog-header-icon {
+.supervisor-dialog--disable .supervisor-dialog-header-icon {
   background: var(--icon-surface-error);
   color: var(--icon-error);
 }
 
-.supervisor-dialog-subtitle {
-  display: block;
-  margin-top: 2px;
-  font-size: var(--text-xs);
-  font-weight: var(--font-normal);
-  color: var(--text-tertiary);
-}
-
 .supervisor-dialog .textarea {
   font-family: var(--font-mono);
   font-size: var(--text-sm);

packages/web/src/styles/components.theme.test.ts

@@ -29,6 +29,10 @@ const confirmDialogStyles = readFileSync(
   `${process.cwd()}/src/components/ui/confirm-dialog/index.module.css`,
   "utf8"
 );
+const modalStylesheet = readFileSync(
+  `${process.cwd()}/src/components/ui/modal/index.module.css`,
+  "utf8"
+);
 
 function getLastGroupedRuleBlockFrom(source: string, pattern: RegExp) {
   const matches = Array.from(source.matchAll(pattern));
@@ -613,6 +617,31 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(hasRuleBlock(".workspace-sidebar-panel__header .panel-header__title-row")).toBe(false);
   });
 
+  it("keeps dialog headers on the approved modal header contract", () => {
+    const modalTitle = getLastRuleBlockFrom(modalStylesheet, ".title");
+    const dialogHeader =
+      getRuleBlocksFrom(modalStylesheet, ".dialogHeader").find((block) =>
+        block.includes("align-items: flex-start")
+      ) ?? "";
+    const dialogIcon = getLastRuleBlock(".supervisor-dialog-header-icon");
+    const editTone = getLastRuleBlock(".supervisor-dialog--edit .supervisor-dialog-header-icon");
+    const disableTone = getLastRuleBlock(
+      ".supervisor-dialog--disable .supervisor-dialog-header-icon"
+    );
+
+    expect(modalTitle).toContain("font-size: var(--text-lg)");
+    expect(modalTitle).toContain("font-weight: var(--font-semibold)");
+    expect(dialogHeader).toContain("align-items: flex-start");
+    expect(dialogIcon).toContain("width: 28px");
+    expect(dialogIcon).toContain("height: 28px");
+    expect(editTone).toContain("var(--icon-surface-info)");
+    expect(editTone).toContain("var(--icon-info)");
+    expect(disableTone).toContain("var(--icon-surface-error)");
+    expect(disableTone).toContain("var(--icon-error)");
+    expect(hasRuleBlock(".supervisor-dialog-header")).toBe(false);
+    expect(hasRuleBlock(".supervisor-dialog-subtitle")).toBe(false);
+  });
+
   it("uses a unified inline sheet treatment for mobile selectors and keeps topbar controls height-aligned", () => {
     const inlineSheet = getLastRuleBlock(".mobile-inline-sheet");
     const inlineSheetAction = getLastRuleBlock(".mobile-inline-sheet__action");