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

package/README.md

@@ -506,24 +506,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/dist/components/compounds/Modal.svelte

@@ -86,6 +86,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 +128,76 @@
   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 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}
 
-        {#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>
+      <!-- 主体区域独立滚动，避免长内容把头部和底部一起顶走。 -->
+      <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 +205,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 {
@@ -220,10 +236,16 @@
   }
 
   .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;
   }

package/dist/components/scenes/ai/markdown-parse.js

@@ -24,6 +24,16 @@ function escapeHtml(text) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
+function createTableCellAttrs(cell) {
+    const attrs = [];
+    if (cell.align) {
+        attrs.push(`style="text-align:${cell.align}"`);
+    }
+    if (cell.text.trim()) {
+        attrs.push(`title="${escapeHtml(cell.text)}"`);
+    }
+    return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+}
 /**
  * 创建自定义渲染器对象
  *
@@ -91,15 +101,13 @@ function createRendererObject(options) {
         table(token) {
             let headerHtml = '';
             for (const cell of token.header) {
-                const align = cell.align ? ` style="text-align:${cell.align}"` : '';
-                headerHtml += `<th${align}>${this.parser.parseInline(cell.tokens)}</th>`;
+                headerHtml += `<th${createTableCellAttrs(cell)}>${this.parser.parseInline(cell.tokens)}</th>`;
             }
             let bodyHtml = '';
             for (const row of token.rows) {
                 let rowHtml = '';
                 for (const cell of row) {
-                    const align = cell.align ? ` style="text-align:${cell.align}"` : '';
-                    rowHtml += `<td${align}>${this.parser.parseInline(cell.tokens)}</td>`;
+                    rowHtml += `<td${createTableCellAttrs(cell)}>${this.parser.parseInline(cell.tokens)}</td>`;
                 }
                 bodyHtml += `<tr>${rowHtml}</tr>`;
             }

package/dist/components/scenes/ai/table/AiTableEditor.svelte

@@ -1097,7 +1097,7 @@
       <thead>
         <tr>
           {#each tableColumns as column (column.key)}
-            <th>{column.label}</th>
+            <th title={column.label}>{column.label}</th>
           {/each}
           {#if editable}
             <th class='hai-ai-table-action-head'>{uiM('data_table_actions')}</th>
@@ -1122,11 +1122,13 @@
               ondrop={event => handleRowDrop(row.row_id, event)}
             >
               {#each tableColumns as column (column.key)}
+                {@const cellInputValue = getCellInputValue(row, column.key)}
                 <td>
                   <input
                     class={resolveCellInputClass(column.type)}
                     type={column.type === 'number' ? 'number' : 'text'}
-                    value={getCellInputValue(row, column.key)}
+                    value={cellInputValue}
+                    title={cellInputValue}
                     disabled={!editable}
                     oninput={event => handleCellInput(row.row_id, column, event)}
                   />

package/dist/theme-config.d.ts

@@ -52,6 +52,10 @@ export declare const THEME_GROUPS: ThemeGroup[];
  * 暗色主题列表
  */
 export declare const DARK_THEMES: string[];
+/**
+ * 支持的主题 ID 列表
+ */
+export declare const SUPPORTED_THEME_IDS: string[];
 /**
  * 默认主题色
  */
@@ -64,6 +68,14 @@ export declare const DEFAULT_THEME_COLOR_CSS_VAR = "--hai-theme-color-default";
  * 内置主题色预设
  */
 export declare const THEME_COLOR_PRESETS: ThemeColorPreset[];
+/**
+ * 默认主题
+ */
+export declare const DEFAULT_THEME = "light";
+/**
+ * 主题存储键名
+ */
+export declare const THEME_STORAGE_KEY = "theme";
 /**
  * 获取主题信息
  */
@@ -73,13 +85,57 @@ export declare function getThemeInfo(themeId: string): ThemeInfo | undefined;
  */
 export declare function isDarkTheme(themeId: string): boolean;
 /**
- * 默认主题
+ * 归一化主题 ID，不支持的值回退到默认主题。
  */
-export declare const DEFAULT_THEME = "light";
+export declare function normalizeThemeId(themeId: string | null | undefined, fallbackThemeId?: string): string;
 /**
- * 主题存储键名
+ * 归一化 Hex 颜色；无效值返回 null。
  */
-export declare const THEME_STORAGE_KEY = "theme";
+export declare function normalizeHexColor(value: string | null | undefined): string | null;
+/**
+ * 解析主题对应的浏览器色调。
+ */
+export declare function resolveThemeTone(themeId: string): 'light' | 'dark';
+/**
+ * 主题首屏恢复脚本里可选的语言字段配置。
+ *
+ * 业务侧如果把语言和主题一起落到同一个偏好对象里，可用这组配置在首屏阶段同步恢复语言值，
+ * 避免 HTML shell 和 hydrate 后的语言状态短暂不一致。
+ */
+export interface ThemeBootstrapLocaleConfig {
+    /** 偏好对象中的语言字段名。 */
+    key: string;
+    /** 默认语言。 */
+    defaultValue: string;
+    /** 允许的语言列表。 */
+    supportedValues: string[];
+}
+/**
+ * 生成首屏主题恢复脚本时使用的宿主侧配置。
+ *
+ * 这组配置刻意只保留“HTML shell 首屏恢复”所需的信息，避免把运行时 helper 或 UI 组件状态
+ * 泄漏到脚本字符串里，方便不同应用在 `app.html` / 服务端模板中复用同一套恢复逻辑。
+ */
+export interface ThemeBootstrapScriptOptions {
+    /** 偏好存储 key。 */
+    storageKey: string;
+    /** 历史主题 key；传 null 表示不做迁移。 */
+    legacyThemeStorageKey?: string | null;
+    /** 默认主题 ID。 */
+    defaultThemeId?: string;
+    /** 默认主题色；传 null 表示不处理主题色。 */
+    defaultThemeColor?: string | null;
+    /** 主题色写入的 CSS 变量；传 null 表示不写。 */
+    colorCssVar?: string | null;
+    /** 主题 tone 写入的 dataset key；传 null 表示不写。 */
+    toneDatasetKey?: string | null;
+    /** 可选的语言字段配置。 */
+    locale?: ThemeBootstrapLocaleConfig | null;
+}
+/**
+ * 生成首屏主题恢复脚本，适合注入到 SvelteKit `app.html` 的 `<script>` 中。
+ */
+export declare function createThemeBootstrapScript(options: ThemeBootstrapScriptOptions): string;
 /**
  * 获取主题初始化脚本（用于 HTML shell 防闪烁）
  *

package/dist/theme-config.js

@@ -46,6 +46,10 @@ export const THEME_GROUPS = [
  * 暗色主题列表
  */
 export const DARK_THEMES = THEMES.filter(t => t.dark).map(t => t.id);
+/**
+ * 支持的主题 ID 列表
+ */
+export const SUPPORTED_THEME_IDS = THEMES.map(theme => theme.id);
 /**
  * 默认主题色
  */
@@ -62,6 +66,17 @@ export const THEME_COLOR_PRESETS = [
     { value: '#13b981', labelKey: 'theme_color_grid_green' },
     { value: '#1f5eff', labelKey: 'theme_color_ocean' },
 ];
+const HEX_COLOR_REGEX = /^#[0-9a-f]{6}$/i;
+const SHORT_HEX_COLOR_REGEX = /^#[0-9a-f]{3}$/i;
+const SUPPORTED_THEME_ID_SET = new Set(SUPPORTED_THEME_IDS);
+/**
+ * 默认主题
+ */
+export const DEFAULT_THEME = 'light';
+/**
+ * 主题存储键名
+ */
+export const THEME_STORAGE_KEY = 'theme';
 /**
  * 获取主题信息
  */
@@ -74,15 +89,68 @@ export function getThemeInfo(themeId) {
 export function isDarkTheme(themeId) {
     return DARK_THEMES.includes(themeId);
 }
-// ─── 主题初始化工具 ───
 /**
- * 默认主题
+ * 归一化主题 ID，不支持的值回退到默认主题。
  */
-export const DEFAULT_THEME = 'light';
+export function normalizeThemeId(themeId, fallbackThemeId = DEFAULT_THEME) {
+    const normalized = `${themeId ?? ''}`;
+    if (SUPPORTED_THEME_ID_SET.has(normalized)) {
+        return normalized;
+    }
+    return SUPPORTED_THEME_ID_SET.has(fallbackThemeId) ? fallbackThemeId : DEFAULT_THEME;
+}
 /**
- * 主题存储键名
+ * 归一化 Hex 颜色；无效值返回 null。
  */
-export const THEME_STORAGE_KEY = 'theme';
+export function normalizeHexColor(value) {
+    const normalized = value?.trim().toLowerCase() ?? '';
+    if (HEX_COLOR_REGEX.test(normalized)) {
+        return normalized;
+    }
+    if (SHORT_HEX_COLOR_REGEX.test(normalized)) {
+        return `#${normalized[1]}${normalized[1]}${normalized[2]}${normalized[2]}${normalized[3]}${normalized[3]}`;
+    }
+    return null;
+}
+/**
+ * 解析主题对应的浏览器色调。
+ */
+export function resolveThemeTone(themeId) {
+    return isDarkTheme(themeId) ? 'dark' : 'light';
+}
+function escapeJsonForScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003C')
+        .replace(/>/g, '\\u003E')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+/**
+ * 生成首屏主题恢复脚本，适合注入到 SvelteKit `app.html` 的 `<script>` 中。
+ */
+export function createThemeBootstrapScript(options) {
+    const defaultThemeId = normalizeThemeId(options.defaultThemeId ?? DEFAULT_THEME);
+    const defaultThemeColor = options.defaultThemeColor == null
+        ? null
+        : normalizeHexColor(options.defaultThemeColor) ?? DEFAULT_THEME_COLOR;
+    const locale = options.locale
+        ? {
+            key: options.locale.key,
+            defaultValue: options.locale.defaultValue,
+            supportedValues: [...options.locale.supportedValues],
+        }
+        : null;
+    const defaultPreferences = {
+        themeId: defaultThemeId,
+    };
+    if (defaultThemeColor) {
+        defaultPreferences.themeColor = defaultThemeColor;
+    }
+    if (locale) {
+        defaultPreferences[locale.key] = locale.defaultValue;
+    }
+    return `(function(){var d=${escapeJsonForScript(defaultPreferences)};var s=${escapeJsonForScript(options.storageKey)};var l=${escapeJsonForScript(options.legacyThemeStorageKey ?? null)};var u=new Set(${escapeJsonForScript(SUPPORTED_THEME_IDS)});var k=new Set(${escapeJsonForScript(DARK_THEMES)});var c=${escapeJsonForScript(options.colorCssVar ?? null)};var y=${escapeJsonForScript(options.toneDatasetKey ?? null)};var i=${escapeJsonForScript(locale)};function n(e){var r=''+(e??'');return u.has(r)?r:d.themeId}function h(e){var r=(''+(e??'')).trim().toLowerCase();if(/^#[0-9a-f]{6}$/i.test(r))return r;if(/^#[0-9a-f]{3}$/i.test(r))return '#'+r[1]+r[1]+r[2]+r[2]+r[3]+r[3];return Object.prototype.hasOwnProperty.call(d,'themeColor')?d.themeColor:null}function g(e){var r={...d,themeId:n(e?.themeId)};if(Object.prototype.hasOwnProperty.call(d,'themeColor'))r.themeColor=h(e?.themeColor);if(i)r[i.key]=i.supportedValues.includes(e?.[i.key])?e[i.key]:d[i.key];return r}function a(e){var r=document.documentElement;var o=k.has(e.themeId)?'dark':'light';r.setAttribute('data-theme',e.themeId);if(y)r.dataset[y]=o;if(c){if(e.themeColor){r.style.setProperty(c,e.themeColor)}else{r.style.removeProperty(c)}}r.style.setProperty('color-scheme',o)}var p=d;try{var f=window.localStorage.getItem(s);if(f){p=g(JSON.parse(f))}else if(l){p=g({themeId:window.localStorage.getItem(l)})}else{p=g(d)}a(p);window.localStorage.setItem(s,JSON.stringify(p));if(l)window.localStorage.removeItem(l)}catch{a(d)}})()`;
+}
 /**
  * 获取主题初始化脚本（用于 HTML shell 防闪烁）
  *
@@ -90,7 +158,10 @@ export const THEME_STORAGE_KEY = 'theme';
  * 对于 SvelteKit `app.html`，请直接粘贴这段脚本字符串的内容，不能写 `{@html getThemeInitScript()}`。
  */
 export function getThemeInitScript() {
-    return `(function(){var t='${DEFAULT_THEME}';try{var s=localStorage.getItem('${THEME_STORAGE_KEY}');if(s)t=s}catch{}document.documentElement.setAttribute('data-theme',t)})()`;
+    return createThemeBootstrapScript({
+        storageKey: THEME_STORAGE_KEY,
+        defaultThemeId: DEFAULT_THEME,
+    });
 }
 /**
  * 应用主题

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.25",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -45,7 +45,7 @@
     "mermaid": "^11.12.0",
     "shiki": "^4.0.2",
     "tailwind-merge": "^3.5.0",
-    "@h-ai/core": "0.1.0-alpha.24"
+    "@h-ai/core": "0.1.0-alpha.25"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",