Skip to content

fix: improve modal layout and theme bootstrap helpers #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gudaoxuri merged 1 commit into from
Jun 15, 2026
Merged

fix: improve modal layout and theme bootstrap helpers #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions packages/ui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 采用**组件内置翻译**模式：
Expand Down
136 changes: 79 additions & 57 deletions packages/ui/src/lib/components/compounds/Modal.svelte
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 回调。
Expand Down Expand Up @@ -117,84 +128,89 @@
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;
overflow: visible;
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 {
Expand All @@ -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;
}
Expand Down
136 changes: 131 additions & 5 deletions packages/ui/src/lib/theme-config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,11 @@ export const THEME_GROUPS: ThemeGroup[] = [
*/
export const DARK_THEMES = THEMES.filter(t => t.dark).map(t => t.id)

/**
* 支持的主题 ID 列表
*/
export const SUPPORTED_THEME_IDS = THEMES.map(theme => theme.id)

/**
* 默认主题色
*/
Expand All @@ -109,6 +114,20 @@ export const THEME_COLOR_PRESETS: ThemeColorPreset[] = [
{ 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'

/**
* 获取主题信息
*/
Expand All @@ -123,17 +142,121 @@ export function isDarkTheme(themeId: string): boolean {
return DARK_THEMES.includes(themeId)
}

/**
* 归一化主题 ID，不支持的值回退到默认主题。
*/
export function normalizeThemeId(
themeId: string | null | undefined,
fallbackThemeId = DEFAULT_THEME,
): string {
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 function normalizeHexColor(value: string | null | undefined): string | null {
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: string): 'light' | 'dark' {
return isDarkTheme(themeId) ? 'dark' : 'light'
}

// ─── 主题初始化工具 ───

/**
* 默认主题
* 主题首屏恢复脚本里可选的语言字段配置。
*
* 业务侧如果把语言和主题一起落到同一个偏好对象里，可用这组配置在首屏阶段同步恢复语言值，
* 避免 HTML shell 和 hydrate 后的语言状态短暂不一致。
*/
export const DEFAULT_THEME = 'light'
export interface ThemeBootstrapLocaleConfig {
/** 偏好对象中的语言字段名。 */
key: string
/** 默认语言。 */
defaultValue: string
/** 允许的语言列表。 */
supportedValues: string[]
}

/**
* 主题存储键名
* 生成首屏主题恢复脚本时使用的宿主侧配置。
*
* 这组配置刻意只保留“HTML shell 首屏恢复”所需的信息，避免把运行时 helper 或 UI 组件状态
* 泄漏到脚本字符串里，方便不同应用在 `app.html` / 服务端模板中复用同一套恢复逻辑。
*/
export const THEME_STORAGE_KEY = 'theme'
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
}

function escapeJsonForScript(value: unknown): string {
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: ThemeBootstrapScriptOptions): string {
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: Record<string, string> = {
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 防闪烁）
Expand All @@ -142,7 +265,10 @@ export const THEME_STORAGE_KEY = 'theme'
* 对于 SvelteKit `app.html`，请直接粘贴这段脚本字符串的内容，不能写 `{@html getThemeInitScript()}`。
*/
export function getThemeInitScript(): string {
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,
})
}

/**
Expand Down
Loading
Loading