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

package/dist/components/scenes/iam/AuthShell.svelte

@@ -0,0 +1,138 @@
+<!--
+  @component AuthShell
+  认证页布局场景组件
+
+  借鉴 shadcn-admin sign-in / sign-in-2：支持居中卡片（card）与左右分栏（split）两种布局。
+  品牌区、标题、副标题、表单内容由使用方提供。
+
+  使用 Svelte 5 Runes ($props, $derived)
+
+  @example
+  <AuthShell variant="card" title="登录" subtitle="欢迎回来">
+    <LoginForm onsubmit={handleLogin} />
+  </AuthShell>
+-->
+<script lang='ts'>
+  import type { Snippet } from 'svelte'
+  import { cn } from '../../../utils.js'
+
+  const {
+    variant = 'card',
+    title = '',
+    subtitle = '',
+    brandTitle = '',
+    brandText = '',
+    logo,
+    illustration,
+    description,
+    highlights,
+    brand,
+    footer,
+    children,
+    class: className = '',
+  }: {
+    /** 布局形态：'card'（居中卡片，默认）或 'split'（左右分栏） */
+    variant?: 'card' | 'split'
+    /** 表单区标题 */
+    title?: string
+    /** 表单区副标题 */
+    subtitle?: string
+    /** split 模式品牌区主标题 */
+    brandTitle?: string
+    /** split 模式品牌区描述文案 */
+    brandText?: string
+    /** 顶部 Logo 插槽 */
+    logo?: Snippet
+    /** split 模式品牌区插图（如大图/海报） */
+    illustration?: Snippet
+    /** split 模式品牌区描述区（覆盖 brandText） */
+    description?: Snippet
+    /** split 模式品牌区重点信息（如卖点列表） */
+    highlights?: Snippet
+    /** split 模式品牌区自定义插槽（覆盖 brandTitle/brandText） */
+    brand?: Snippet
+    /** 底部插槽（如注册/登录切换链接） */
+    footer?: Snippet
+    /** 表单内容 */
+    children?: Snippet
+    class?: string
+  } = $props()
+
+  const isSplit = $derived(variant === 'split')
+  // split 模式下品牌区已展示 Logo，表单区仅在小屏展示，避免桌面端重复
+  const logoWrapClass = $derived(isSplit ? 'mb-6 flex justify-center lg:hidden' : 'mb-6 flex justify-center')
+</script>
+
+{#snippet formPanel()}
+  <div class='flex w-full max-w-sm flex-col'>
+    {#if logo}
+      <div class={logoWrapClass}>{@render logo()}</div>
+    {/if}
+    {#if title}
+      <h1 class='text-center text-2xl font-semibold tracking-tight text-base-content'>{title}</h1>
+    {/if}
+    {#if subtitle}
+      <p class='mt-2 text-center text-sm text-base-content/55'>{subtitle}</p>
+    {/if}
+    <div class='mt-7'>
+      {#if children}{@render children()}{/if}
+    </div>
+    {#if footer}
+      <div class='mt-6 text-center text-sm text-base-content/60'>{@render footer()}</div>
+    {/if}
+  </div>
+{/snippet}
+
+{#if isSplit}
+  <div class={cn('grid min-h-screen lg:grid-cols-2', className)}>
+    <!-- 品牌区 -->
+    <div class='relative hidden overflow-hidden bg-primary p-10 text-primary-content lg:flex'>
+      <div class='pointer-events-none absolute inset-0 opacity-20' style='background-image: radial-gradient(circle at 20% 20%, currentColor 1px, transparent 1px); background-size: 28px 28px;'></div>
+      {#if brand}
+        {@render brand()}
+      {:else}
+        <div class='relative z-10 flex w-full flex-1 flex-col justify-between gap-10'>
+          <div class='space-y-6'>
+            {#if logo}
+              <div>{@render logo()}</div>
+            {/if}
+            {#if illustration}
+              <div class='overflow-hidden rounded-2xl border border-primary-content/15 bg-primary-content/5 p-2'>
+                {@render illustration()}
+              </div>
+            {/if}
+          </div>
+
+          <div class='space-y-4'>
+            {#if brandTitle}
+              <h2 class='text-3xl font-semibold leading-snug'>{brandTitle}</h2>
+            {/if}
+            {#if description}
+              <div class='max-w-xl text-sm text-primary-content/85'>
+                {@render description()}
+              </div>
+            {:else if brandText}
+              <p class='max-w-xl text-sm text-primary-content/80'>{brandText}</p>
+            {/if}
+          </div>
+
+          {#if highlights}
+            <div class='max-w-xl text-sm text-primary-content/90'>
+              {@render highlights()}
+            </div>
+          {/if}
+        </div>
+      {/if}
+    </div>
+    <!-- 表单区 -->
+    <div class='flex items-center justify-center p-6 sm:p-10'>
+      {@render formPanel()}
+    </div>
+  </div>
+{:else}
+  <div class={cn('flex min-h-screen items-center justify-center bg-base-200/40 p-6', className)}>
+    <div class='w-full max-w-md rounded-2xl border border-base-content/8 bg-base-100 p-8 shadow-sm sm:p-10'>
+      {@render formPanel()}
+    </div>
+  </div>
+{/if}

package/dist/components/scenes/iam/AuthShell.svelte.d.ts

@@ -0,0 +1,45 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** 布局形态：'card'（居中卡片，默认）或 'split'（左右分栏） */
+    variant?: 'card' | 'split';
+    /** 表单区标题 */
+    title?: string;
+    /** 表单区副标题 */
+    subtitle?: string;
+    /** split 模式品牌区主标题 */
+    brandTitle?: string;
+    /** split 模式品牌区描述文案 */
+    brandText?: string;
+    /** 顶部 Logo 插槽 */
+    logo?: Snippet;
+    /** split 模式品牌区插图（如大图/海报） */
+    illustration?: Snippet;
+    /** split 模式品牌区描述区（覆盖 brandText） */
+    description?: Snippet;
+    /** split 模式品牌区重点信息（如卖点列表） */
+    highlights?: Snippet;
+    /** split 模式品牌区自定义插槽（覆盖 brandTitle/brandText） */
+    brand?: Snippet;
+    /** 底部插槽（如注册/登录切换链接） */
+    footer?: Snippet;
+    /** 表单内容 */
+    children?: Snippet;
+    class?: string;
+};
+/**
+ * AuthShell
+ * 认证页布局场景组件
+ *
+ * 借鉴 shadcn-admin sign-in / sign-in-2：支持居中卡片（card）与左右分栏（split）两种布局。
+ * 品牌区、标题、副标题、表单内容由使用方提供。
+ *
+ * 使用 Svelte 5 Runes ($props, $derived)
+ *
+ * @example
+ * <AuthShell variant="card" title="登录" subtitle="欢迎回来">
+ *   <LoginForm onsubmit={handleLogin} />
+ * </AuthShell>
+ */
+declare const AuthShell: import("svelte").Component<$$ComponentProps, {}, "">;
+type AuthShell = ReturnType<typeof AuthShell>;
+export default AuthShell;

package/dist/components/scenes/iam/index.d.ts

@@ -4,6 +4,7 @@
  * 身份认证相关的场景化组件
  * @module index
  */
+export { default as AuthShell } from './AuthShell.svelte';
 export { default as ChangePasswordForm } from './ChangePasswordForm.svelte';
 export { default as ForgotPasswordForm } from './ForgotPasswordForm.svelte';
 export { default as LoginForm } from './LoginForm.svelte';

package/dist/components/scenes/iam/index.js

@@ -4,9 +4,10 @@
  * 身份认证相关的场景化组件
  * @module index
  */
+// 认证表单
+export { default as AuthShell } from './AuthShell.svelte';
 export { default as ChangePasswordForm } from './ChangePasswordForm.svelte';
 export { default as ForgotPasswordForm } from './ForgotPasswordForm.svelte';
-// 认证表单
 export { default as LoginForm } from './LoginForm.svelte';
 export { default as PasswordInput } from './PasswordInput.svelte';
 // 权限控制

package/dist/components/scenes/index.d.ts

@@ -8,6 +8,7 @@ export * from './ai/index.js';
 export * from './app/index.js';
 export * from './crud/index.js';
 export * from './crypto/index.js';
+export * from './error/index.js';
 export * from './iam/index.js';
 export * from './storage/index.js';
 export * from './types.js';

package/dist/components/scenes/index.js

@@ -12,6 +12,8 @@ export * from './app/index.js';
 export * from './crud/index.js';
 // Crypto 场景组件
 export * from './crypto/index.js';
+// 错误页场景组件
+export * from './error/index.js';
 // IAM 场景组件
 export * from './iam/index.js';
 // Storage 场景组件

package/dist/messages/en-US.json

@@ -160,6 +160,8 @@
   "pagination_jump_to": "Go to",
   "pagination_page": "page",
   "pagination_page_size": "{size} / page",
+  "pagination_rows_per_page": "Rows per page",
+  "pagination_page_info": "Page {page} of {total}",
   "severity_critical": "Critical",
   "severity_high": "High",
   "severity_medium": "Medium",
@@ -275,7 +277,24 @@
   "crud_delete_failed": "Delete failed",
   "crud_network_error": "Network error, please try again later",
   "crud_filter_all": "All",
+  "crud_filter_yes": "Yes",
+  "crud_filter_no": "No",
+  "crud_filter_from": "From",
+  "crud_filter_to": "To",
+  "crud_reset": "Reset",
   "crud_total": "{count} items total",
   "crud_detail_empty": "-",
-  "crud_field_required": "This field is required"
+  "crud_field_required": "This field is required",
+  "error_go_back": "Go Back",
+  "error_back_home": "Back to Home",
+  "error_401_title": "Unauthorized",
+  "error_401_desc": "You need to sign in to access this page. Please log in and try again.",
+  "error_403_title": "Access Forbidden",
+  "error_403_desc": "You don't have permission to access this resource. Contact your administrator if you need help.",
+  "error_404_title": "Page Not Found",
+  "error_404_desc": "The page you are looking for doesn't exist or has been moved. Please check the URL.",
+  "error_500_title": "Internal Server Error",
+  "error_500_desc": "Something went wrong on our end. We're working on it, please try again later.",
+  "error_503_title": "Under Maintenance",
+  "error_503_desc": "The system is currently undergoing maintenance. Please check back soon."
 }

package/dist/messages/zh-CN.json

@@ -160,6 +160,8 @@
   "pagination_jump_to": "跳转到",
   "pagination_page": "页",
   "pagination_page_size": "{size} 条/页",
+  "pagination_rows_per_page": "每页",
+  "pagination_page_info": "第 {page} / {total} 页",
   "severity_critical": "严重",
   "severity_high": "高",
   "severity_medium": "中",
@@ -275,7 +277,24 @@
   "crud_delete_failed": "删除失败",
   "crud_network_error": "网络错误，请稍后重试",
   "crud_filter_all": "全部",
+  "crud_filter_yes": "是",
+  "crud_filter_no": "否",
+  "crud_filter_from": "开始日期",
+  "crud_filter_to": "结束日期",
+  "crud_reset": "重置",
   "crud_total": "共 {count} 条",
   "crud_detail_empty": "-",
-  "crud_field_required": "此字段为必填项"
+  "crud_field_required": "此字段为必填项",
+  "error_go_back": "返回上一页",
+  "error_back_home": "返回首页",
+  "error_401_title": "未授权访问",
+  "error_401_desc": "您需要登录后才能访问此页面。请登录后重试。",
+  "error_403_title": "禁止访问",
+  "error_403_desc": "您没有权限访问此资源。如需帮助请联系管理员。",
+  "error_404_title": "页面不存在",
+  "error_404_desc": "您访问的页面不存在或已被移除。请检查地址是否正确。",
+  "error_500_title": "服务器错误",
+  "error_500_desc": "服务器出现了一些问题。我们正在处理，请稍后重试。",
+  "error_503_title": "服务维护中",
+  "error_503_desc": "系统正在维护升级，请稍后再访问。"
 }

package/dist/styles/global.css

@@ -57,7 +57,10 @@ input::-webkit-credentials-auto-fill-button {
 }
 
 /* ─── Focus ring ─── */
-:focus-visible {
+/* 全局 focus-visible 仅用于非表单交互元素（按钮、链接等）
+   表单组件 (.select, .radio, .checkbox, .toggle, .textarea, input, textarea)
+   由 DaisyUI 或组件自身处理焦点样式 */
+:focus-visible:not(input, select, textarea, .select, .radio, .checkbox, .toggle, .textarea) {
   outline: 2px solid oklch(0.6 0.15 250);
   outline-offset: 2px;
   border-radius: 4px;

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/dist/types.d.ts

@@ -438,6 +438,8 @@ export interface ModalProps {
     title?: string;
     /** 尺寸 */
     size?: Size | 'full';
+    /** 面板圆角（任意合法 CSS border-radius 值，默认 1rem） */
+    radius?: string;
     /** 是否可通过点击遮罩关闭 */
     closeOnBackdrop?: boolean;
     /** 是否可通过 ESC 键关闭 */
@@ -601,6 +603,10 @@ export interface PaginationProps {
         page?: string;
         /** 每页条数文案，{size} 会被替换为实际数字 */
         pageSize?: string;
+        /** 每页条数前缀文案（如「每页」/「Rows per page」） */
+        rowsPerPage?: string;
+        /** 页码信息文案，{page} / {total} 会被替换（如「第 {page} / {total} 页」） */
+        pageInfo?: string;
     };
     /** 自定义类名 */
     class?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "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.26"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",