@h-ai/ui 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -151,7 +151,7 @@ components/
 
 | 组件      | 描述   | 主要属性                                                |
 | --------- | ------ | ------------------------------------------------------- |
-| `Modal`   | 模态框 | `open`, `title`, `size`, `closeOnBackdrop`, `showClose` |
+| `Modal`   | 模态框 | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
 | `Drawer`  | 抽屉   | `open`, `position`, `title`, `size`                     |
 | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm`      |
 | `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`                 |
@@ -161,7 +161,7 @@ components/
 | 组件        | 描述     | 主要属性                                 |
 | ----------- | -------- | ---------------------------------------- |
 | `Card`      | 卡片容器 | `title`, `bordered`, `shadow`, `padding` |
-| `DataTable` | 数据表格 | `data`, `columns`, `keyField`, `loading` |
+| `DataTable` | 数据表格 | `data`, `columns`, `keyField`, `loading`, `sortKey`, `sortDir`, `onsort`（列 `sortable` 可排序） |
 | `Accordion` | 手风琴   | `items: AccordionItem[]`                 |
 | `Timeline`  | 时间线   | `items: TimelineItem[]`                  |
 
@@ -192,7 +192,7 @@ components/
 | 组件         | 描述     | 主要属性                                     |
 | ------------ | -------- | -------------------------------------------- |
 | `Tabs`       | 标签页   | `items`, `active`, `type`, `size`            |
-| `Pagination` | 分页     | `page`, `total`, `pageSize`, `showTotal`     |
+| `Pagination` | 分页（统一 table 风格） | `page`, `total`, `pageSize`, `showTotal`, `showJumper`, `showSizeChanger` |
 | `Breadcrumb` | 面包屑   | `items`, `separator`                         |
 | `Steps`      | 步骤条   | `items`, `current`, `direction`, `clickable` |
 | `Dropdown`   | 下拉菜单 | `items`, `trigger`, `position`               |
@@ -212,23 +212,25 @@ components/
 | ------------ | -------- | ------------------------------------------- |
 | `PageHeader` | 页面头部 | `title`, `description`，支持 `actions` 插槽 |
 
-### 场景组件 Scenes（30 个）
+### 场景组件 Scenes（33 个）
 
-#### App 应用级（6 个）
+#### App 应用级（7 个）
 
 | 组件             | 描述             | 主要属性           |
 | ---------------- | ---------------- | ------------------ |
 | `FeedbackModal`  | 反馈模态框       | `open`, `onsubmit` |
 | `SettingsModal`  | 设置模态框       | `open`, `onclose`  |
+| `SettingsLayout` | 设置页布局（分区导航 + 内容区） | `title`, `description`, `sections`, `active`, `onselect` |
 | `LanguageSwitch` | 语言切换         | 无需 Props         |
 | `ThemeColorPicker` | 主题色选择器   | `value`, `presets`, `onchange` |
 | `ThemeSelector`  | 完整主题选择面板 | 无需 Props         |
 | `ThemeToggle`    | 明/暗主题切换    | 无需 Props         |
 
-#### IAM 身份认证（8 个）
+#### IAM 身份认证（9 个）
 
 | 组件                 | 描述       | 主要属性                                              |
 | -------------------- | ---------- | ----------------------------------------------------- |
+| `AuthShell`          | 认证页布局（居中卡片 / 左右分栏） | `variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` |
 | `LoginForm`          | 登录表单   | `loading`, `errors`, `showRememberMe`, `onsubmit`     |
 | `RegisterForm`       | 注册表单   | `loading`, `errors`, `fields`, `onsubmit`             |
 | `ForgotPasswordForm` | 忘记密码   | `mode`, `loading`, `errors`, `onsubmit`               |
@@ -275,11 +277,19 @@ components/
 | 组件                 | 描述         | 主要属性 / 能力 |
 | -------------------- | ------------ | ---------------- |
 | `CrudPage`           | CRUD 主页面  | `crud`, `data`, `permissions`, `form`, `pagination`, `density`, `nav` |
-| `CrudFilterBar`      | 过滤工具栏   | `filterFields`, `searchValue`, `onsearch`, `onfilterchange` |
+| `CrudFilterBar`      | 过滤工具栏（搜索 + 多类型过滤 + 重置） | `filterFields`, `searchValue`, `onsearch`, `onfilterchange`, `onreset` |
 | `CrudDetailPanel`    | 详情面板（抽屉/弹窗） | `open`, `item`, `fields`, `variant`, `drawerWidth`, `modalSize` |
 | `CrudEditPanel`      | 编辑面板（抽屉/弹窗） | `open`, `fields`, `variant`, `drawerWidth`, `modalSize`, `onsubmit` |
 | `CrudDeleteConfirm`  | 删除确认框   | `open`, `loading`, `onconfirm` |
 
+> 列表列头默认支持点击排序（`DataTable` 内置客户端排序，受控模式可通过 `sortKey`/`sortDir`/`onsort` 接管为服务端排序）；存在搜索/过滤条件时筛选栏显示「重置」按钮。过滤工具栏支持常用控件：`select`、`boolean`、`number`、`date`、`date-range`、`text`。分页栏统一为 shadcn 风格（总数 / 每页 / 第 X / Y 页 / 首末翻页 / 跳转到）。
+
+#### 错误页场景（1 个）
+
+| 组件        | 描述         | 主要属性 / 能力 |
+| ----------- | ------------ | ---------------- |
+| `ErrorPage` | 通用错误页（内置 401/403/404/500/503 预设） | `status`, `code`, `title`, `description`, `homeUrl`, `onhome`, `onback` |
+
 > `CrudPage` 通过 `form` 配置新建/编辑的展示形式：
 >
 > - `form.variant`：`'drawer'`（抽屉，默认）或 `'modal'`（弹出窗口）。
@@ -378,6 +388,8 @@ components/
 <ToastContainer />
 ```
 
+`Modal` 不传 `title` / `header` 时会保留右上角关闭按钮，但不额外渲染整条头部。需要调整圆角时可传 `radius="1.4rem"`，内部下拉等浮层需要越界显示时可传 `bodyOverflow="visible"`。
+
 ### 声明式 CRUD 页面（CrudPage）
 
 ```svelte
@@ -506,24 +518,42 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
 ```ts
 import {
   applyTheme, // 应用主题（自动持久化到 localStorage）
+  createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
   getCurrentTheme, // 获取当前主题
   getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
   isDarkTheme, // 检查是否暗色主题
+  normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
+  normalizeThemeId, // 校验主题 ID 并自动回退
   THEME_GROUPS, // 按亮色/暗色分组
   THEMES, // ThemeInfo[] — 15 个精选主题元数据
 } from '@h-ai/ui'
 ```
 
-在 SvelteKit 的 `app.html` 中，请直接写入下面这段脚本内容（与 `getThemeInitScript()` 返回值一致）：
+简单场景可以直接使用 `getThemeInitScript()`；如果应用有自定义存储 key、主题色 CSS 变量或语言偏好，推荐在服务端通过 `createThemeBootstrapScript()` 生成脚本后再注入 `app.html`。
+
+在 SvelteKit 的 `app.html` 中，可以先放一个占位符：
 
 ```html
 <head>
-  <script>
-    (function(){var t='light';try{var s=localStorage.getItem('theme');if(s)t=s}catch{}document.documentElement.setAttribute('data-theme',t)})()
-  </script>
+  <script>%theme_bootstrap%</script>
 </head>
 ```
 
+然后在 `hooks.server.ts` 里注入：
+
+```ts
+import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
+
+const themeBootstrapScript = createThemeBootstrapScript({
+  storageKey: 'hai-demo-preferences',
+  legacyThemeStorageKey: 'hai-demo-theme',
+  defaultThemeColor: '#5765f0',
+  colorCssVar: DEFAULT_THEME_COLOR_CSS_VAR,
+})
+
+transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
+```
+
 ## 国际化 (i18n)
 
 @h-ai/ui 采用**组件内置翻译**模式：

package/auto-import.d.ts

@@ -76,12 +76,14 @@ declare global {
   // scenes - app
   const FeedbackModal: typeof import('@h-ai/ui')['FeedbackModal']
   const LanguageSwitch: typeof import('@h-ai/ui')['LanguageSwitch']
+  const SettingsLayout: typeof import('@h-ai/ui')['SettingsLayout']
   const SettingsModal: typeof import('@h-ai/ui')['SettingsModal']
   const ThemeColorPicker: typeof import('@h-ai/ui')['ThemeColorPicker']
   const ThemeSelector: typeof import('@h-ai/ui')['ThemeSelector']
   const ThemeToggle: typeof import('@h-ai/ui')['ThemeToggle']
 
   // scenes - iam
+  const AuthShell: typeof import('@h-ai/ui')['AuthShell']
   const ChangePasswordForm: typeof import('@h-ai/ui')['ChangePasswordForm']
   const ForgotPasswordForm: typeof import('@h-ai/ui')['ForgotPasswordForm']
   const LoginForm: typeof import('@h-ai/ui')['LoginForm']
@@ -114,6 +116,9 @@ declare global {
   const CrudEditPanel: typeof import('@h-ai/ui')['CrudEditPanel']
   const CrudFilterBar: typeof import('@h-ai/ui')['CrudFilterBar']
   const CrudPage: typeof import('@h-ai/ui')['CrudPage']
+
+  // scenes - error
+  const ErrorPage: typeof import('@h-ai/ui')['ErrorPage']
 }
 
 export {}

package/auto-import.js

@@ -66,11 +66,13 @@ const UI_COMPONENTS = new Set([
   // scenes - app
   'FeedbackModal',
   'LanguageSwitch',
+  'SettingsLayout',
   'SettingsModal',
   'ThemeColorPicker',
   'ThemeSelector',
   'ThemeToggle',
   // scenes - iam
+  'AuthShell',
   'ChangePasswordForm',
   'ForgotPasswordForm',
   'LoginForm',
@@ -99,6 +101,8 @@ const UI_COMPONENTS = new Set([
   'CrudEditPanel',
   'CrudFilterBar',
   'CrudPage',
+  // scenes - error
+  'ErrorPage',
 ])
 
 const TAG_REGEX = /<([A-Z][A-Za-z0-9]*)\b/g

package/dist/components/compounds/DataTable.svelte

@@ -41,10 +41,13 @@
     striped = true,
     hoverable = true,
     density = 'normal',
+    sortKey,
+    sortDir,
+    onsort,
     class: className = '',
   }: {
     data: T[]
-    columns: { key: keyof T | string, label: string, width?: string, align?: 'left' | 'center' | 'right', render?: (item: T) => string }[]
+    columns: { key: keyof T | string, label: string, width?: string, align?: 'left' | 'center' | 'right', sortable?: boolean, render?: (item: T) => string }[]
     keyField: keyof T
     actions?: Snippet<[T]>
     empty?: Snippet
@@ -52,10 +55,66 @@
     striped?: boolean
     hoverable?: boolean
     density?: 'normal' | 'compact'
+    /** 受控排序字段（提供 onsort 时由外部驱动，通常用于服务端排序） */
+    sortKey?: string
+    /** 受控排序方向 */
+    sortDir?: 'asc' | 'desc' | null
+    /** 排序回调；提供时为受控模式（不再对 data 做本地排序），否则组件内部对当前数据做客户端排序 */
+    onsort?: (key: string, dir: 'asc' | 'desc') => void
     class?: string
   } = $props()
 
-  type Column = { key: keyof T | string, label: string, width?: string, align?: 'left' | 'center' | 'right', render?: (item: T) => string }
+  type Column = { key: keyof T | string, label: string, width?: string, align?: 'left' | 'center' | 'right', sortable?: boolean, render?: (item: T) => string }
+
+  // ─── 排序状态 ───
+  const controlled = $derived(typeof onsort === 'function')
+  // 非受控模式下的内部排序状态
+  let localSortKey = $state<string | null>(null)
+  let localSortDir = $state<'asc' | 'desc'>('asc')
+
+  const activeSortKey = $derived(controlled ? (sortKey ?? null) : localSortKey)
+  const activeSortDir = $derived<'asc' | 'desc' | null>(controlled ? (sortDir ?? null) : (localSortKey ? localSortDir : null))
+
+  function toggleSort(col: Column) {
+    if (!col.sortable)
+      return
+    const key = String(col.key)
+    const nextDir: 'asc' | 'desc' = activeSortKey === key && activeSortDir === 'asc' ? 'desc' : 'asc'
+    if (controlled) {
+      onsort?.(key, nextDir)
+      return
+    }
+    localSortKey = key
+    localSortDir = nextDir
+  }
+
+  // 非受控模式：对当前数据做客户端排序（受控模式直接使用外部已排序数据）
+  const sortedData = $derived.by(() => {
+    if (controlled || !localSortKey)
+      return data
+    const key = localSortKey
+    const dir = localSortDir
+    const copy = [...data]
+    copy.sort((a, b) => {
+      const av = (a as Record<string, unknown>)[key]
+      const bv = (b as Record<string, unknown>)[key]
+      if (av === bv)
+        return 0
+      if (av === null || av === undefined)
+        return 1
+      if (bv === null || bv === undefined)
+        return -1
+      let cmp: number
+      if (typeof av === 'number' && typeof bv === 'number') {
+        cmp = av - bv
+      }
+      else {
+        cmp = String(av).localeCompare(String(bv), undefined, { numeric: true })
+      }
+      return dir === 'asc' ? cmp : -cmp
+    })
+    return copy
+  })
 
   const tableClass = $derived(
     density === 'compact'
@@ -108,11 +167,29 @@
     <thead>
       <tr class={headerRowClass}>
         {#each columns as col (String(col.key))}
+          {@const isSorted = activeSortKey === String(col.key)}
           <th
             style={col.width ? `width: ${col.width}` : ''}
             class='{getAlignClass(col.align)} font-medium'
           >
-            {col.label}
+            {#if col.sortable}
+              <button
+                type='button'
+                class='group inline-flex select-none items-center gap-1 rounded-md px-1.5 py-0.5 -mx-1.5 font-medium transition-colors hover:bg-base-content/5 {isSorted ? 'text-base-content' : ''}'
+                onclick={() => toggleSort(col)}
+              >
+                <span>{col.label}</span>
+                {#if isSorted && activeSortDir === 'asc'}
+                  <span class='icon-[tabler--arrow-narrow-up] size-3.5 text-base-content/70'></span>
+                {:else if isSorted && activeSortDir === 'desc'}
+                  <span class='icon-[tabler--arrow-narrow-down] size-3.5 text-base-content/70'></span>
+                {:else}
+                  <span class='icon-[tabler--arrows-sort] size-3.5 text-base-content/30 group-hover:text-base-content/50'></span>
+                {/if}
+              </button>
+            {:else}
+              {col.label}
+            {/if}
           </th>
         {/each}
         {#if actions}
@@ -138,7 +215,7 @@
           </td>
         </tr>
       {:else}
-        {#each data as item (item[keyField])}
+        {#each sortedData as item (item[keyField])}
           <tr class={rowClass}>
             {#each columns as col (String(col.key))}
               <td class={getAlignClass(col.align)}>{getValue(item, col)}</td>

package/dist/components/compounds/DataTable.svelte.d.ts

@@ -7,6 +7,7 @@ declare function $$render<T>(): {
             label: string;
             width?: string;
             align?: "left" | "center" | "right";
+            sortable?: boolean;
             render?: (item: T) => string;
         }[];
         keyField: keyof T;
@@ -16,6 +17,12 @@ declare function $$render<T>(): {
         striped?: boolean;
         hoverable?: boolean;
         density?: "normal" | "compact";
+        /** 受控排序字段（提供 onsort 时由外部驱动，通常用于服务端排序） */
+        sortKey?: string;
+        /** 受控排序方向 */
+        sortDir?: "asc" | "desc" | null;
+        /** 排序回调；提供时为受控模式（不再对 data 做本地排序），否则组件内部对当前数据做客户端排序 */
+        onsort?: (key: string, dir: "asc" | "desc") => void;
         class?: string;
     };
     exports: {};

package/dist/components/compounds/Modal.svelte

@@ -11,6 +11,7 @@
     open = $bindable(false),
     title = '',
     size = 'md',
+    radius = '1rem',
     closeOnBackdrop = true,
     closeOnEscape = true,
     showClose = true,
@@ -29,8 +30,10 @@
   // 只有调用 `showModal()` 进入 top-layer 后，弹框才不会被父级布局和 overflow 裁剪。
   let modalElement: HTMLDialogElement | undefined = $state()
 
-  // 只要存在标题、自定义 header 或关闭按钮，就渲染顶部栏位，保证弹框结构稳定。
-  const hasHeader = $derived(Boolean(header || title || showClose))
+  // 标题区仅在显式提供标题或自定义 header 时出现；
+  // 仅需关闭按钮的场景改为右上角悬浮按钮，避免业务侧额外占一整行头部。
+  const hasHeader = $derived(Boolean(header || title))
+  const hasFloatingClose = $derived(showClose && !hasHeader)
   const sizeMap: Record<string, string> = {
     'xs': 'hai-modal__panel--xs',
     'sm': 'hai-modal__panel--sm',
@@ -55,12 +58,21 @@
       styles.push(`--hai-modal-height: ${height.trim()}`)
     }
 
+    if (typeof radius === 'string' && radius.trim().length > 0) {
+      styles.push(`--hai-modal-radius: ${radius.trim()}`)
+    }
+
+    if (bodyOverflow === 'visible') {
+      styles.push('--hai-modal-panel-overflow: visible')
+    }
+
     return styles.length > 0 ? styles.join('; ') : undefined
   })
 
   const modalBoxClass = $derived(
     cn(
       'hai-modal__panel flex min-h-0 flex-col',
+      'relative',
       'bg-base-100 p-0',
       sizeMap[size],
       className,
@@ -86,6 +98,17 @@
     }
   }
 
+  function handleViewportKeydown(event: KeyboardEvent) {
+    if (
+      event.target === event.currentTarget
+      && closeOnBackdrop
+      && (event.key === 'Enter' || event.key === ' ')
+    ) {
+      event.preventDefault()
+      handleClose()
+    }
+  }
+
   function handleDialogCancel(event: Event) {
     // 原生 dialog 在按下 Escape 时会先触发 cancel；
     // 这里统一接管关闭逻辑，避免浏览器直接 close 后跳过组件自己的 onclose 回调。
@@ -117,74 +140,95 @@
   bind:this={modalElement}
   class='hai-modal'
   oncancel={handleDialogCancel}
-  onclick={handleDialogClick}
 >
-  <div class={modalBoxClass} style={panelStyle}>
-    {#if hasHeader}
-      <!-- 顶部栏单独固定，保证滚动时标题和关闭操作始终可见。 -->
-      <div class='hai-modal__header flex flex-none items-start justify-between gap-4 px-6 py-5 sm:px-7'>
-        {#if header}
-          <div class='flex-1 font-semibold text-[1.05rem] text-base-content/92'>
-            {@render header()}
-          </div>
-        {:else if title}
-          <h3 class='flex-1 font-semibold text-[1.05rem] tracking-tight text-base-content/92'>
-            {title}
-          </h3>
-        {:else}
-          <div class='flex-1'></div>
-        {/if}
+  <div
+    class='hai-modal__viewport'
+    role='button'
+    tabindex='-1'
+    aria-label={uiM('common_close')}
+    onclick={handleDialogClick}
+    onkeydown={handleViewportKeydown}
+  >
+    <div class={modalBoxClass} style={panelStyle}>
+      {#if hasFloatingClose}
+        <button
+          type='button'
+          class='hai-modal__close hai-modal__close--floating'
+          aria-label={uiM('common_close')}
+          onclick={handleClose}
+        >
+          <svg viewBox='0 0 24 24' class='hai-modal__close-icon' aria-hidden='true'>
+            <path
+              d='M6 6l12 12M18 6L6 18'
+              fill='none'
+              stroke='currentColor'
+              stroke-width='1.9'
+              stroke-linecap='round'
+            ></path>
+          </svg>
+        </button>
+      {/if}
 
-        {#if showClose}
-          <button
-            type='button'
-            class='hai-modal__close'
-            aria-label={uiM('common_close')}
-            onclick={handleClose}
-          >
-            <svg viewBox='0 0 24 24' class='hai-modal__close-icon' aria-hidden='true'>
-              <path
-                d='M6 6l12 12M18 6L6 18'
-                fill='none'
-                stroke='currentColor'
-                stroke-width='1.9'
-                stroke-linecap='round'
-              ></path>
-            </svg>
-          </button>
+      {#if hasHeader}
+        <!-- 顶部栏单独固定，保证滚动时标题和关闭操作始终可见。 -->
+        <div class='hai-modal__header flex flex-none items-start justify-between gap-4 px-6 py-5 sm:px-7'>
+          {#if header}
+            <div class='flex-1 font-semibold text-[1.05rem] text-base-content/92'>
+              {@render header()}
+            </div>
+          {:else if title}
+            <h3 class='flex-1 font-semibold text-[1.05rem] tracking-tight text-base-content/92'>
+              {title}
+            </h3>
+          {:else}
+            <div class='flex-1'></div>
+          {/if}
+
+          {#if showClose}
+            <button
+              type='button'
+              class='hai-modal__close'
+              aria-label={uiM('common_close')}
+              onclick={handleClose}
+            >
+              <svg viewBox='0 0 24 24' class='hai-modal__close-icon' aria-hidden='true'>
+                <path
+                  d='M6 6l12 12M18 6L6 18'
+                  fill='none'
+                  stroke='currentColor'
+                  stroke-width='1.9'
+                  stroke-linecap='round'
+                ></path>
+              </svg>
+            </button>
+          {/if}
+        </div>
+      {/if}
+
+      <!-- 主体区域独立滚动，避免长内容把头部和底部一起顶走。 -->
+      <div class={cn('min-h-0 flex-1 px-6 py-5 sm:px-7', bodyOverflowClass, bodyClass)}>
+        {#if children}
+          {@render children()}
         {/if}
       </div>
-    {/if}
 
-    <!-- 主体区域独立滚动，避免长内容把头部和底部一起顶走。 -->
-    <div class={cn('min-h-0 flex-1 px-6 py-5 sm:px-7', bodyOverflowClass, bodyClass)}>
-      {#if children}
-        {@render children()}
+      {#if footer}
+        <!-- 底栏固定在面板底部，用于承接确认/取消或状态摘要。 -->
+        <div class='hai-modal__footer flex flex-none items-center px-6 py-4 sm:px-7'>
+          <div class='flex w-full items-center justify-end gap-3'>
+            {@render footer()}
+          </div>
+        </div>
       {/if}
     </div>
-
-    {#if footer}
-      <!-- 底栏固定在面板底部，用于承接确认/取消或状态摘要。 -->
-      <div class='hai-modal__footer flex flex-none items-center bg-base-100 px-6 py-4 sm:px-7'>
-        <div class='flex w-full items-center justify-end gap-3'>
-          {@render footer()}
-        </div>
-      </div>
-    {/if}
   </div>
 </dialog>
 
 <style>
-  dialog.hai-modal {
-    inset: 0;
-    width: 100vw;
-    min-width: 0;
-    max-width: none;
-    height: 100vh;
-    height: 100dvh;
-    max-height: none;
+  dialog.hai-modal,
+  dialog.hai-modal:modal {
     margin: 0;
-    padding: clamp(1rem, 2.6vw, 2rem);
+    padding: 0;
     border: 0;
     background: transparent;
     outline: none;
@@ -192,9 +236,12 @@
     box-sizing: border-box;
   }
 
-  dialog.hai-modal[open] {
+  .hai-modal__viewport {
+    position: fixed;
+    inset: 0;
     display: grid;
     place-items: center;
+    padding: clamp(1rem, 2.6vw, 2rem);
   }
 
   dialog.hai-modal::backdrop {
@@ -209,8 +256,8 @@
     height: var(--hai-modal-height, auto);
     max-height: calc(100vh - clamp(2rem, 5.2vw, 4rem));
     max-height: calc(100dvh - clamp(2rem, 5.2vw, 4rem));
-    border-radius: 1.4rem;
-    overflow: hidden;
+    border-radius: var(--hai-modal-radius, 1rem);
+    overflow: var(--hai-modal-panel-overflow, hidden);
     color: var(--color-base-content);
     outline: none;
     box-shadow:
@@ -220,12 +267,18 @@
   }
 
   .hai-modal__header {
+    /* 头部单独承接面板圆角，避免滚动主体或主题背景把顶部边缘切成直角。 */
+    border-top-left-radius: inherit;
+    border-top-right-radius: inherit;
     box-shadow: inset 0 -1px 0 color-mix(in srgb, var(--color-base-content) 6%, transparent);
   }
 
   .hai-modal__footer {
+    /* 底栏去掉独立背景后，继续继承圆角，保证底部阴影和面板外轮廓保持一致。 */
+    border-bottom-right-radius: inherit;
+    border-bottom-left-radius: inherit;
     box-shadow: inset 0 1px 0 color-mix(in srgb, var(--color-base-content) 6%, transparent);
-    border-radius: 0 0 1.4rem 1.4rem;
+    border-radius: 0 0 var(--hai-modal-radius, 1rem) var(--hai-modal-radius, 1rem);
   }
 
   .hai-modal__close {
@@ -262,6 +315,13 @@
     height: 1rem;
   }
 
+  .hai-modal__close--floating {
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
+    z-index: 1;
+  }
+
   .hai-modal__panel--xs {
     --hai-modal-width: min(100%, 24rem);
   }
@@ -320,7 +380,7 @@
       max-width: 100%;
       max-height: calc(100vh - 1.7rem);
       max-height: calc(100dvh - 1.7rem);
-      border-radius: 1rem;
+      border-radius: min(var(--hai-modal-radius, 1rem), 1rem);
     }
   }
 </style>