@fangxinyan/lumina 0.6.3 → 0.6.5

package/dist/{tokens-BIIUTPKN.css → tokens-EF34LSWI.css}

@@ -20,42 +20,52 @@
 
   /* Distance multiplier — driven by ThemeProvider `intensity` (1..10 → 0.4..1.6). */
   --d: 1;
+  --shadow-scale: 1;
+  --shadow-float-scale: 1;
 
-  --shadow-blur: calc(16px * var(--d));
-  --shadow-offset: calc(6px * var(--d));
-  --shadow-inset-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(4px * var(--d));
+  --shadow-blur: calc(16px * var(--d) * var(--shadow-scale));
+  --shadow-offset: calc(6px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(4px * var(--d) * var(--shadow-scale));
 
-  --neu-out:
+  --neu-shadow-panel:
     var(--shadow-offset) var(--shadow-offset) var(--shadow-blur) var(--shadow-dark),
     calc(var(--shadow-offset) * -1) calc(var(--shadow-offset) * -1) var(--shadow-blur) var(--shadow-light);
 
-  --neu-out-sm:
+  --neu-shadow-control:
     calc(var(--shadow-offset) * 0.5) calc(var(--shadow-offset) * 0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-dark),
     calc(var(--shadow-offset) * -0.5) calc(var(--shadow-offset) * -0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-light);
 
-  --neu-out-lg:
+  --neu-shadow-lift:
     calc(var(--shadow-offset) * 1.6) calc(var(--shadow-offset) * 1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-dark),
     calc(var(--shadow-offset) * -1.6) calc(var(--shadow-offset) * -1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-light);
 
-  --neu-in:
+  --neu-shadow-inset-strong:
     inset var(--shadow-inset-offset) var(--shadow-inset-offset) var(--shadow-inset-blur) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -1) calc(var(--shadow-inset-offset) * -1) var(--shadow-inset-blur) var(--shadow-light);
 
-  --neu-in-sm:
+  --neu-shadow-inset:
     inset calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-light);
 
-  --neu-flat:
+  --neu-shadow-subtle:
     1px 1px 2px var(--shadow-dark),
     -1px -1px 2px var(--shadow-light);
 
   /* Floating-overlay elevation.
      No top-left highlight — there's no continuous surface beneath an overlay
      panel, so the neumorphic light-reflection metaphor would read as a halo. */
-  --neu-float:
-    0 calc(var(--shadow-offset) * 1.8) calc(var(--shadow-blur) * 2.2) var(--shadow-dark),
-    0 calc(var(--shadow-offset) * 0.4) calc(var(--shadow-blur) * 0.7) var(--shadow-dark);
+  --neu-shadow-float:
+    0 calc(var(--shadow-offset) * 1.8 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 2.2 * var(--shadow-float-scale)) var(--shadow-dark),
+    0 calc(var(--shadow-offset) * 0.4 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 0.7 * var(--shadow-float-scale)) var(--shadow-dark);
+
+  --neu-out: var(--neu-shadow-panel);
+  --neu-out-sm: var(--neu-shadow-control);
+  --neu-out-lg: var(--neu-shadow-lift);
+  --neu-in: var(--neu-shadow-inset-strong);
+  --neu-in-sm: var(--neu-shadow-inset);
+  --neu-flat: var(--neu-shadow-subtle);
+  --neu-float: var(--neu-shadow-float);
 
   /* ---- Accent (default sky) ---- */
   --accent: oklch(68% 0.14 235);
@@ -89,7 +99,13 @@
 
   /* ---- Control sizes (density) ---- */
   --ctrl-h: 40px;
+  --ctrl-h-sm: 30px;
+  --ctrl-h-lg: 52px;
+  --field-h-sm: 32px;
+  --field-h-lg: 48px;
   --ctrl-pad-x: 18px;
+  --ctrl-pad-x-sm: 12px;
+  --ctrl-pad-x-lg: 24px;
 
   /* ---- Type ---- */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
@@ -97,6 +113,11 @@
                "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
   --font-display: "SF Pro Display", var(--font-sans);
+  --fs-xs: 11px;
+  --fs-sm: 12px;
+  --fs-md: 13px;
+  --fs-lg: 14px;
+  --fs-xl: 15px;
 
   /* ---- Motion ---- */
   --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
@@ -123,13 +144,17 @@
   --shadow-dark: rgba(0, 0, 0, 0.55);
   --shadow-light: rgba(130, 145, 180, 0.06);
   /* 同时收紧阴影尺寸,深色模式下拟态更内敛 */
-  --shadow-offset: calc(4px * var(--d));
-  --shadow-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(3px * var(--d));
-  --shadow-inset-blur: calc(7px * var(--d));
+  --shadow-offset: calc(4px * var(--d) * var(--shadow-scale));
+  --shadow-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(3px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(7px * var(--d) * var(--shadow-scale));
   --accent-soft: oklch(35% 0.06 235);
   --accent-ink: oklch(82% 0.09 235);
   --accent-glow: oklch(68% 0.14 235 / 0.18);
+  --info:    oklch(78% 0.12 235);
+  --success: oklch(78% 0.14 150);
+  --warning: oklch(82% 0.14 75);
+  --danger:  oklch(76% 0.16 25);
 }
 
 /* 深色模式的 accent-glow 统一降低强度,避免按钮外圈过亮 */

package/dist/tokens.css

@@ -20,42 +20,52 @@
 
   /* Distance multiplier — driven by ThemeProvider `intensity` (1..10 → 0.4..1.6). */
   --d: 1;
+  --shadow-scale: 1;
+  --shadow-float-scale: 1;
 
-  --shadow-blur: calc(16px * var(--d));
-  --shadow-offset: calc(6px * var(--d));
-  --shadow-inset-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(4px * var(--d));
+  --shadow-blur: calc(16px * var(--d) * var(--shadow-scale));
+  --shadow-offset: calc(6px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(4px * var(--d) * var(--shadow-scale));
 
-  --neu-out:
+  --neu-shadow-panel:
     var(--shadow-offset) var(--shadow-offset) var(--shadow-blur) var(--shadow-dark),
     calc(var(--shadow-offset) * -1) calc(var(--shadow-offset) * -1) var(--shadow-blur) var(--shadow-light);
 
-  --neu-out-sm:
+  --neu-shadow-control:
     calc(var(--shadow-offset) * 0.5) calc(var(--shadow-offset) * 0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-dark),
     calc(var(--shadow-offset) * -0.5) calc(var(--shadow-offset) * -0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-light);
 
-  --neu-out-lg:
+  --neu-shadow-lift:
     calc(var(--shadow-offset) * 1.6) calc(var(--shadow-offset) * 1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-dark),
     calc(var(--shadow-offset) * -1.6) calc(var(--shadow-offset) * -1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-light);
 
-  --neu-in:
+  --neu-shadow-inset-strong:
     inset var(--shadow-inset-offset) var(--shadow-inset-offset) var(--shadow-inset-blur) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -1) calc(var(--shadow-inset-offset) * -1) var(--shadow-inset-blur) var(--shadow-light);
 
-  --neu-in-sm:
+  --neu-shadow-inset:
     inset calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-light);
 
-  --neu-flat:
+  --neu-shadow-subtle:
     1px 1px 2px var(--shadow-dark),
     -1px -1px 2px var(--shadow-light);
 
   /* Floating-overlay elevation.
      No top-left highlight — there's no continuous surface beneath an overlay
      panel, so the neumorphic light-reflection metaphor would read as a halo. */
-  --neu-float:
-    0 calc(var(--shadow-offset) * 1.8) calc(var(--shadow-blur) * 2.2) var(--shadow-dark),
-    0 calc(var(--shadow-offset) * 0.4) calc(var(--shadow-blur) * 0.7) var(--shadow-dark);
+  --neu-shadow-float:
+    0 calc(var(--shadow-offset) * 1.8 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 2.2 * var(--shadow-float-scale)) var(--shadow-dark),
+    0 calc(var(--shadow-offset) * 0.4 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 0.7 * var(--shadow-float-scale)) var(--shadow-dark);
+
+  --neu-out: var(--neu-shadow-panel);
+  --neu-out-sm: var(--neu-shadow-control);
+  --neu-out-lg: var(--neu-shadow-lift);
+  --neu-in: var(--neu-shadow-inset-strong);
+  --neu-in-sm: var(--neu-shadow-inset);
+  --neu-flat: var(--neu-shadow-subtle);
+  --neu-float: var(--neu-shadow-float);
 
   /* ---- Accent (default sky) ---- */
   --accent: oklch(68% 0.14 235);
@@ -89,7 +99,13 @@
 
   /* ---- Control sizes (density) ---- */
   --ctrl-h: 40px;
+  --ctrl-h-sm: 30px;
+  --ctrl-h-lg: 52px;
+  --field-h-sm: 32px;
+  --field-h-lg: 48px;
   --ctrl-pad-x: 18px;
+  --ctrl-pad-x-sm: 12px;
+  --ctrl-pad-x-lg: 24px;
 
   /* ---- Type ---- */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
@@ -97,6 +113,11 @@
                "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
   --font-display: "SF Pro Display", var(--font-sans);
+  --fs-xs: 11px;
+  --fs-sm: 12px;
+  --fs-md: 13px;
+  --fs-lg: 14px;
+  --fs-xl: 15px;
 
   /* ---- Motion ---- */
   --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
@@ -123,13 +144,17 @@
   --shadow-dark: rgba(0, 0, 0, 0.55);
   --shadow-light: rgba(130, 145, 180, 0.06);
   /* 同时收紧阴影尺寸,深色模式下拟态更内敛 */
-  --shadow-offset: calc(4px * var(--d));
-  --shadow-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(3px * var(--d));
-  --shadow-inset-blur: calc(7px * var(--d));
+  --shadow-offset: calc(4px * var(--d) * var(--shadow-scale));
+  --shadow-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(3px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(7px * var(--d) * var(--shadow-scale));
   --accent-soft: oklch(35% 0.06 235);
   --accent-ink: oklch(82% 0.09 235);
   --accent-glow: oklch(68% 0.14 235 / 0.18);
+  --info:    oklch(78% 0.12 235);
+  --success: oklch(78% 0.14 150);
+  --warning: oklch(82% 0.14 75);
+  --danger:  oklch(76% 0.16 25);
 }
 
 /* 深色模式的 accent-glow 统一降低强度,避免按钮外圈过亮 */

package/docs/llms/surface.md

@@ -0,0 +1,90 @@
+# Surface 背景面
+
+> 主题感知的背景承载容器,用于给特殊色调内容提供正确的拟态 token 语境。
+
+## 导入
+
+```tsx
+import { Surface, SURFACE_THEME_PRESETS } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础承载
+
+默认继承外部主题,只提供一片稳定的拟态背景。
+
+```tsx
+<Surface padding="lg" radius="xl">
+  <Card title="运行概览" description="Surface 负责外部背景,Card 负责信息分组">
+    <Button variant="primary">开始</Button>
+  </Card>
+</Surface>
+```
+
+### 内置背景预设
+
+preset 会建立一套局部 ThemeProvider,子组件和 useTheme 都处在这套背景 token 下。
+
+```tsx
+<Surface preset="graphite" padding="lg" radius="xl">
+  <Button variant="primary">深色面板</Button>
+</Surface>
+
+<Surface preset="porcelain" padding="lg" radius="xl">
+  <Input placeholder="清亮浅色面板" />
+</Surface>
+```
+
+### 背景语义
+
+tone 只切换背景槽位;适合在同一主题里区分基底、凸起、凹陷和强调底。
+
+```tsx
+<Surface tone="base">base</Surface>
+<Surface tone="raised">raised</Surface>
+<Surface tone="sunken">sunken</Surface>
+<Surface tone="accent">accent</Surface>
+```
+
+### 自定义局部主题
+
+可直接传 mode、accent、tokens 等主题参数。themeRadius 控制子树 token, radius 控制 Surface 自身圆角。
+
+```tsx
+<Surface
+  mode="dark"
+  accent="mint"
+  themeRadius={18}
+  tokens={{
+    bg: "#171d20",
+    "bg-raised": "#20282c",
+    "bg-sunken": "#101517",
+  }}
+>
+  <Card>...</Card>
+</Surface>
+```
+
+## API
+
+**Surface**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| preset | `"inherit" | "mist" | "porcelain" | "graphite" | "ember"` | `"inherit"` | 内置局部背景预设 |
+| tone | `"base" | "raised" | "sunken" | "accent"` | `"base"` | 可见背景槽位 |
+| variant | `"plain" | "raised" | "sunken" | "floating"` | `"plain"` | Surface 自身拟态层级 |
+| padding | `"none" | "sm" | "md" | "lg" | "xl"` | `"md"` | 内边距 |
+| radius | `"none" | "sm" | "md" | "lg" | "xl"` | `"lg"` | Surface 自身圆角 |
+| height | `"content" | "fill" | "screen"` | `"content"` | 高度语义 |
+| bordered | `boolean` | `false` | 显示 token 描边 |
+| scrollable | `boolean` | `false` | 受限高度下允许内部滚动 |
+| mode / colorScheme / accent | `ThemeConfig fields` | — | 局部主题深浅色与强调色 |
+| density / intensity / themeRadius / font | `ThemeConfig fields` | — | 局部密度、阴影、主题圆角和字体 |
+| tokens | `ThemeTokens` | — | 局部 CSS token 覆写 |
+| themes | `ThemePresets` | — | 局部自定义模式注册表 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/theme.md

@@ -48,6 +48,21 @@ t.update({ radius: 14 });    // 一次改多个
 t.reset();                   // 重置到 props 初值
 ```
 
+### 阴影系统
+
+阴影强度、扩散和浮层深度都由 ThemeProvider tokens 驱动,组件只消费语义阴影 token。
+
+```tsx
+const t = useTheme();
+
+t.setIntensity(6);
+t.setTokens({
+  ...t.tokens,
+  "shadow-scale": "1.15",
+  "shadow-float-scale": "1.25",
+});
+```
+
 ### 预设强调色
 
 内置 6 种拟态强调色,点击切换。
@@ -86,6 +101,8 @@ mode 可以指向 themes 中的命名 preset。base 决定 light/dark 基底,tok
 ```tsx
 const themes = {
   graphite: {
+    label: "Graphite",
+    description: "深色",
     base: "dark",
     accent: {
       accent: "oklch(72% 0.13 190)",
@@ -102,6 +119,8 @@ const themes = {
       fg: "#edf1f7",
       "shadow-dark": "rgba(0,0,0,.58)",
       "shadow-light": "rgba(128,146,166,.07)",
+      "shadow-scale": "1",
+      "shadow-float-scale": "1",
     },
   },
 };
@@ -139,6 +158,8 @@ tokens prop 可以改 tokens.css 里任何变量 —— 键名可省略 --。
     bg: "#f5f5f7",           // 等价 --bg
     "--bg-sunken": "#e8e8ed",
     "shadow-dark": "rgba(0,0,0,0.18)",
+    "shadow-scale": "0.9",
+    "shadow-float-scale": "1.15",
     "--font-display": '"Inter", sans-serif',
   }}
 />
@@ -171,11 +192,12 @@ applyTheme(document.documentElement, {
 | intensity | `number` | `5` | 阴影强度 1-10 |
 | radius | `number` | `20` | 圆角基准 px |
 | font | `FontConfig` | `"sf"` | 字体预设或 CSS 栈 |
-| tokens | `Record<string, string>` | — | 任意 CSS 变量覆写 |
+| tokens | `Record<string, string>` | — | 任意 CSS 变量覆写;推荐用语义阴影 token 和 shadow-scale / shadow-float-scale 控制阴影系统 |
 | themes | `Record<string, ThemePreset>` | — | 命名自定义模式 preset |
+| ThemePreset.label / description | `string` | — | 可选展示元信息;ThemePanel 会读取它作为卡片标题和说明 |
 | target | `"root" | "scope"` | `"root"` | 应用到根还是局部 |
 | as | `keyof JSX.IntrinsicElements` | `"div"` | scope 模式的元素标签 |
-| storageKey | `string` | — | localStorage 持久化 key |
+| storageKey | `string` | — | localStorage 持久化 key,包含当前主题状态与自定义 themes |
 | onChange | `(value: ThemeValue) => void` | — | 主题值变更回调 |
 
 

package/docs/llms/themepanel.md

@@ -0,0 +1,128 @@
+# ThemePanel 主题面板
+
+> 可复用的主题快速调节面板,直接驱动最近的 ThemeProvider。
+
+## 导入
+
+```tsx
+import { ThemeProvider, ThemePanel, THEME_PANEL_DEFAULT_PRESET_OPTIONS, THEME_PANEL_DEFAULT_THEME_PRESETS } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 完整面板
+
+默认包含浅色、深色、瓷白、助手、助手暗五个主题卡片,并提供简洁/深度两档新建主题入口;其余控制项直接驱动 useTheme。
+
+```tsx
+<ThemeProvider>
+  <ThemePanel />
+</ThemeProvider>
+```
+
+### 外部保存与回灌
+
+onCreateTheme / onDeleteTheme 会把新建和删除事件交给业务侧;业务侧保存后通过 ThemeProvider themes 回灌。
+
+```tsx
+import { ThemeProvider, ThemePanel, type ThemePresets } from "lumina";
+
+const [themes, setThemes] = React.useState<ThemePresets>({});
+
+<ThemeProvider themes={themes} storageKey="app:theme">
+  <ThemePanel
+    onCreateTheme={(payload) => {
+      setThemes((current) => ({
+        ...current,
+        [String(payload.key)]: payload.preset,
+      }));
+      saveThemeToServerOrStorage(payload);
+    }}
+    onDeleteTheme={(payload) => {
+      setThemes((current) => {
+        const { [String(payload.key)]: removed, ...next } = current;
+        return next;
+      });
+      deleteThemeFromServerOrStorage(payload);
+    }}
+  />
+</ThemeProvider>
+```
+
+### 精简面板
+
+用 sections 控制展示哪些调节项,适合放进抽屉、设置页侧栏或开发调试区。
+
+```tsx
+<ThemePanel
+  compact
+  title="微调"
+  description={null}
+  sections={["accent", "shadow", "radius"]}
+  showReset={false}
+/>
+```
+
+## API
+
+**ThemePanel**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| title | `ReactNode` | `"主题"` | 面板标题;传 null 可隐藏标题文本 |
+| description | `ReactNode` | `"快速调整当前 Lumina 主题"` | 面板副标题 |
+| sections | `ThemePanelSection[]` | — | 展示的控制区及顺序;shadow 区同时控制 intensity / shadow-scale / shadow-float-scale |
+| modeOptions | `ThemePanelModeOption[]` | — | 模式切换项 |
+| presetOptions | `ThemePanelPresetOption[]` | — | 命名主题预设卡片;不传时使用浅色/深色/瓷白/助手/助手暗 + theme.themes,也可完全由业务侧控制 |
+| defaultCustomAccent | `string` | `"#845ef7"` | 自定义强调色初始值 |
+| allowCreateTheme | `boolean` | `true` | 在预设区显示新建主题流程 |
+| defaultCreateThemeName | `string` | `"我的主题"` | 新建主题的默认名称 |
+| createThemeKeyPrefix | `string` | `"user"` | 生成自建主题 mode key 时使用的前缀 |
+| onCreateTheme | `(payload: ThemePanelCreateThemePayload) => void` | — | 保存自建主题后的回调,业务侧可把 payload.preset 存起来并通过 ThemeProvider themes 回灌 |
+| allowDeleteTheme | `boolean` | `true` | 为非默认主题显示删除按钮;默认主题不会显示删除入口 |
+| onDeleteTheme | `(payload: ThemePanelDeleteThemePayload) => void` | — | 删除非默认主题后的回调,业务侧可同步删除外部存储 |
+| showReset | `boolean` | `true` | 显示重置按钮 |
+| compact | `boolean` | `false` | 紧凑布局 |
+
+
+**默认预设常量**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| THEME_PANEL_DEFAULT_PRESET_OPTIONS | `ThemePanelPresetOption[]` | — | ThemePanel 默认卡片列表: 浅色、深色、瓷白、助手、助手暗 |
+| THEME_PANEL_DEFAULT_THEME_PRESETS | `Record<string, ThemePreset>` | — | 默认卡片背后的 ThemePreset 配置 |
+
+
+**ThemePanelPresetOption**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `ThemeMode` | — | 主题 mode key;若存在于 theme.themes 会应用对应 preset |
+| label \* | `ReactNode` | — | 卡片标题 |
+| description | `ReactNode` | — | 卡片说明 |
+| preset | `ThemePreset` | — | 可选 preset;点击时会注册并应用 |
+
+
+**ThemePanelCreateThemePayload**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key | `ThemeMode` | — | 保存后注册到 ThemeProvider 的 mode key |
+| label | `string` | — | 用户输入的主题名称 |
+| description | `string` | — | ThemePanel 生成的说明文案,如自建亮/自建暗 |
+| preset | `ThemePreset` | — | 最终保存到 theme.themes 的主题配置 |
+| presetOption | `ThemePanelPresetOption` | — | 可直接追加到受控 presetOptions 的卡片配置 |
+
+
+**ThemePanelDeleteThemePayload**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key | `ThemeMode` | — | 被删除的主题 mode key |
+| label | `string` | — | 被删除主题的展示名称 |
+| description | `string` | — | 被删除主题的说明文案 |
+| preset | `ThemePreset` | — | 删除前的主题配置;如果对应 key 不存在于 ThemeProvider themes 则为空 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/tooltip.md

@@ -42,6 +42,7 @@ title 与 content 等价,也支持 bottomLeft 等细分位置。
 | title | `ReactNode` | — | content 的等价别名 |
 | placement | `"top" | "bottom" | "left" | "right" | ...` | `"top"` | 位置,支持 bottomLeft 等细分方向 |
 | delay | `number` | `250` | 悬浮延时 (ms) |
+| closeDelay | `number` | `300` | 离开触发器或提示浮层后的关闭延时 (ms) |
 | disabled | `boolean` | `false` | 禁用提示 |
 | open / visible | `boolean` | — | 受控显示状态 |
 | overlayClassName / popupClassName | `string` | — | 浮层 className |

package/docs/llms/typography.md

@@ -57,10 +57,10 @@ import { Typography } from "@fangxinyan/lumina";
 
 ### 省略截断
 
-多行截断并支持「展开」。
+多行截断支持「展开」，悬停时可查看完整内容。
 
 ```tsx
-<Typography.Paragraph ellipsis={{ rows: 2, expandable: true }}>{long}</Typography.Paragraph>
+<Typography.Paragraph ellipsis={{ rows: 2, expandable: true, tooltip: true }}>{long}</Typography.Paragraph>
 ```
 
 ### 链接
@@ -90,6 +90,16 @@ import { Typography } from "@fangxinyan/lumina";
 | ellipsis | `boolean | EllipsisConfig` | — | 截断省略 |
 
 
+**EllipsisConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| rows | `number` | `1` | 截断行数 |
+| expandable | `boolean` | `false` | 显示展开入口 |
+| tooltip | `boolean | ReactNode` | `false` | 悬停显示完整内容 |
+| symbol | `ReactNode` | `"展开"` | 自定义展开文案 |
+
+
 **Typography.Link**
 
 | Prop | 类型 | 默认 | 说明 |

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 拟态风格的 React 18 组件库,目标是 Electron 桌面应用。**写给 AI 编程助手**的按需文档 —— 每个组件单独一个 `.md`,避免一次性读取全部。示例源自 playground 的 demo,可直接复制运行。
 
 - **包名**: `@fangxinyan/lumina`
-- **版本**: `0.6.3`
+- **版本**: `0.6.5`
 - **React 最低版本**: 18
 - **环境**: 带打包器的 React 工程(Vite / Next.js / Webpack / Remix / Electron + Vite 等)
 - **零运行时依赖**: 只依赖 `react` / `react-dom` (peer deps)
@@ -43,6 +43,8 @@
 
 - [Lumina](./llms/intro.md) — 为 Electron 应用定制的拟态风格 React 组件库。
 - [Theme 主题](./llms/theme.md) — ThemeProvider + useTheme,覆盖深浅色、自定义模式、强调色、密度、圆角、字体、阴影强度。
+- [Surface 背景面](./llms/surface.md) — 主题感知的背景承载容器,用于给特殊色调内容提供正确的拟态 token 语境。
+- [ThemePanel 主题面板](./llms/themepanel.md) — 可复用的主题快速调节面板,直接驱动最近的 ThemeProvider。
 
 ### 通用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangxinyan/lumina",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Lumina — Neumorphic component library for Electron & React apps",
   "type": "module",
   "main": "./dist/index.cjs",