@fangxinyan/lumina 0.6.17 → 0.7.0

package/dist/{tokens-RYJ3DFTU.css → tokens-CEJVVA3G.css}

@@ -127,6 +127,16 @@
   --dur-slow: 360ms;
 }
 
+/* 尊重系统的减少动态效果偏好，同时保持组件状态切换事件可完成。 */
+@media (prefers-reduced-motion: reduce) {
+  :root,
+  [data-theme] {
+    --dur-fast: 0.01ms;
+    --dur: 0.01ms;
+    --dur-slow: 0.01ms;
+  }
+}
+
 /* Explicit light reset for scoped ThemeProvider instances.
    :root already has these defaults, but nested [data-theme="light"] must not
    inherit a dark or custom parent surface. */

package/dist/tokens.css

@@ -127,6 +127,16 @@
   --dur-slow: 360ms;
 }
 
+/* 尊重系统的减少动态效果偏好，同时保持组件状态切换事件可完成。 */
+@media (prefers-reduced-motion: reduce) {
+  :root,
+  [data-theme] {
+    --dur-fast: 0.01ms;
+    --dur: 0.01ms;
+    --dur-slow: 0.01ms;
+  }
+}
+
 /* Explicit light reset for scoped ThemeProvider instances.
    :root already has these defaults, but nested [data-theme="light"] must not
    inherit a dark or custom parent surface. */

package/docs/llms/appshell.md

@@ -13,12 +13,15 @@ import { AppShell, TitleBar, Sidebar, StatusBar } from "@fangxinyan/lumina";
 ### 完整工作台外壳
 
 ```tsx
-<AppShell
-  titleBar={<TitleBar title="Lumina Mail" platform="mac" />}
-  sidebar={<Sidebar items={items} activeKey={active} onSelect={setActive} />}
->
-  <main>...</main>
-</AppShell>
+<div style={{ height: 480 }}>
+  <AppShell
+    style={{ height: "100%" }}
+    titleBar={<TitleBar title="Lumina Mail" platform="mac" />}
+    sidebar={<Sidebar items={items} activeKey={active} onSelect={setActive} />}
+  >
+    <main>...</main>
+  </AppShell>
+</div>
 ```
 
 ## API

package/docs/llms/autocomplete.md

@@ -12,6 +12,8 @@ import { AutoComplete } from "@fangxinyan/lumina";
 
 ### 基础
 
+输入框使用 combobox / listbox 语义；方向键跳过禁用项，Enter 选择，Esc 或 Tab 关闭。
+
 ```tsx
 <AutoComplete
   options={[
@@ -25,6 +27,8 @@ import { AutoComplete } from "@fangxinyan/lumina";
 
 ### 自定义 label
 
+label 可以是任意 ReactNode；disabled 选项会保留展示，但不会被键盘或鼠标选中。
+
 ```tsx
 options={[{ value: "zh", label: "中文 · Chinese" }]}
 ```
@@ -51,10 +55,12 @@ const [opts, setOpts] = useState([]);
 | onChange | `(value, option?) => void` | — | 文本变更 |
 | onSelect | `(value, option) => void` | — | 选中项回调 |
 | onSearch | `(text) => void` | — | 输入变化回调 |
-| options \* | `{ value, label?, disabled? }[]` | — | 候选项 |
+| options \* | `{ value, label?, disabled? }[]` | — | 候选项；空字符串 value 会过滤，disabled 项不可选且键盘导航会跳过 |
 | filterOption | `boolean | (input, option) => boolean` | `true` | 过滤函数,false 关闭过滤 |
 | notFoundContent | `ReactNode` | — | 无匹配占位 |
-| allowClear / disabled / size / autoFocus / placeholder | `-` | — | 常规属性 |
+| disabled | `boolean` | `false` | 禁用输入并立即关闭已打开的建议面板 |
+| allowClear / size / autoFocus / placeholder | `-` | — | 常规输入属性 |
+| dropdownClassName | `string` | — | Portal 下拉面板 className |
 | matchTriggerWidth | `boolean` | `true` | 下拉宽度跟随输入框 |
 
 

package/docs/llms/avatar.md

@@ -44,11 +44,13 @@ shape="square" 使用圆角方形,尺寸变化时圆角跟随变化。
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | src | `string` | — | 图片 URL |
+| fallbackSrc | `string` | — | 主图片失败后的备用地址 |
 | alt | `string` | — | 替代文本/首字母来源 |
 | initials | `string` | — | 自定义首字母 |
 | size | `number | "sm" | "md" | "lg" | "xl"` | `"md"` | 尺寸 |
 | shape | `"circle" | "square"` | `"circle"` | 形状 |
 | status | `"online" | "busy" | "away" | "offline"` | — | 状态点 |
+| onImageError | `(event) => void` | — | 主图与备用图最终均失败时触发 |
 
 
 ---

package/docs/llms/badge.md

@@ -33,6 +33,8 @@ dot 模式不显示数字,只是状态指示。
 | --- | --- | --- | --- |
 | count | `number` | — | 显示数字 |
 | dot | `boolean` | `false` | 圆点模式 |
+| showZero | `boolean` | `false` | count 为 0 时仍显示 |
+| statusLabel | `string` | — | 徽标可访问文本 |
 | max | `number` | `99` | 超过显示 max+ |
 | tone | `"neutral" | "accent" | ...` | `"danger"` | 色调 |
 

package/docs/llms/calendar.md

@@ -12,8 +12,12 @@ import { Calendar } from "@fangxinyan/lumina";
 
 ### 基础用法
 
+受控 value 可传 null 表示尚未选择，日历仍保留可操作的当前月份。
+
 ```tsx
-<Calendar value={date} onChange={setDate} />
+<Calendar value={date} viewDate={viewDate}
+  onChange={setDate} onViewChange={setViewDate} />
+<Button onClick={() => setDate(null)}>清空选择</Button>
 ```
 
 ### 禁用日期
@@ -34,8 +38,9 @@ import { Calendar } from "@fangxinyan/lumina";
 
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| value / defaultValue | `Date` | — | 受控/初始日期 |
+| value / defaultValue | `Date | null` | — | 受控/初始日期;null 表示没有选中日期 |
 | viewDate | `Date` | — | 外部日期变化时同步可视月份 |
+| onViewChange | `(date: Date) => void` | — | 用户切换可视月份或年份时回调 |
 | onChange | `(date: Date) => void` | — | 选择回调 |
 | min / max | `Date` | — | 可选范围 |
 | disabledDate | `(date: Date) => boolean` | — | 自定义禁用判断,返回 true 的日期不可选 |

package/docs/llms/card.md

@@ -28,6 +28,23 @@ hoverable 在鼠标悬浮时轻微上移并加强阴影,适合可点击的卡片
 <Card hoverable>可点击卡片</Card>
 ```
 
+### 整卡交互
+
+interactive 提供按钮式焦点和键盘语义；标题区 actions 仍可独立响应，disabled 会隔离整张卡片。
+
+```tsx
+<Card
+  interactive
+  hoverable
+  title="可操作卡片"
+  actions={<Button onClick={handleAction}>独立操作</Button>}
+  onClick={handleCardClick}
+>
+  点击卡片空白区域，或聚焦整卡后按 Enter / Space。
+</Card>
+<Card interactive disabled title="禁用卡片">不会响应</Card>
+```
+
 ### 自定义背景色
 
 background 可覆盖卡片根节点背景，纯色、主题 token、color-mix 与渐变都走同一个字段。
@@ -99,6 +116,8 @@ loading 会在正文区域显示中性 overlay；默认 Spin 跟随主题色，l
 | background | `CSSProperties["background"]` | — | 自定义卡片根节点背景，支持主题 token / color-mix / linear-gradient / radial-gradient 等 CSS 背景值 |
 | padding | `"none" | "sm" | "md" | "lg"` | `"md"` | 内边距 |
 | hoverable | `boolean` | `false` | 悬浮时抬起 |
+| interactive | `boolean` | — | 启用按钮式键盘语义；提供 onClick 时自动开启，内部按钮等控件保持独立响应 |
+| disabled | `boolean` | `false` | 禁用交互式卡片并隔离内部控件 |
 | title | `ReactNode` | — | 标题 |
 | description | `ReactNode` | — | 副标题 |
 | actions | `ReactNode` | — | 右上操作区 |
@@ -107,7 +126,7 @@ loading 会在正文区域显示中性 overlay；默认 Spin 跟随主题色，l
 | bodyClassName | `string` | — | 正文容器 className |
 | bodyStyle | `CSSProperties` | — | 正文容器内联样式 |
 | bodyProps | `HTMLAttributes<HTMLDivElement>` | — | 透传给正文容器的 DOM props |
-| loading | `boolean` | `false` | 显示正文加载覆盖层 |
+| loading | `boolean` | `false` | 显示正文加载覆盖层，并暂时隔离正文与标题操作区控件 |
 | loadingOverlay | `ReactNode` | — | 自定义加载覆盖层内容 |
 
 

package/docs/llms/cascader.md

@@ -12,15 +12,31 @@ import { Cascader } from "@fangxinyan/lumina";
 
 ### 基础用法
 
-option.icon 支持 IconName 或 ReactNode。
+option.icon 支持 IconName 或 ReactNode；禁用节点不可通过列选择或搜索结果绕过选中。
 
 ```tsx
 <Cascader options={regions} value={addr} onChange={setAddr} />
 ```
 
+### 复杂节点与独立选中渲染
+
+optionRender 可为每一级节点添加多行信息；selectedRender 只在触发器中显示紧凑摘要。listHeight 与 popupStyle 控制列高和面板宽度。
+
+```tsx
+<Cascader
+  options={assetOptions}
+  value={assetPath}
+  onChange={setAssetPath}
+  optionRender={(option, info) => <AssetNode option={option} selected={info.selected} />}
+  selectedRender={(selectedOptions) => <AssetPath options={selectedOptions} />}
+  listHeight={380}
+  popupStyle={{ minWidth: "min(680px, calc(100vw - 16px))" }}
+/>
+```
+
 ### 搜索与清除
 
-showSearch 开启路径搜索,allowClear 提供一键清空,popupClassName 可标记浮层。
+showSearch 开启路径搜索,allowClear 提供一键清空；搜索框打开后自动聚焦，禁用任一节点的路径不会进入搜索结果。
 
 ```tsx
 <Cascader
@@ -41,13 +57,19 @@ showSearch 开启路径搜索,allowClear 提供一键清空,popupClassName 可
 | --- | --- | --- | --- |
 | options \* | `CascaderOption[]` | — | 层级选项树 |
 | options[].icon | `IconName | ReactNode` | — | 选项前置图标,可传内置图标名或自定义节点 |
+| options[].text | `string` | — | 复杂 label 的独立默认搜索文本 |
+| options[].ariaLabel | `string` | — | 复杂节点或 optionRender 的独立可访问名称 |
 | value / defaultValue | `string[]` | — | 受控/初始路径 |
-| onChange | `(path: string[]) => void` | — | 选择叶子时触发 |
+| onChange | `(path: string[], selectedOptions?: CascaderOption[]) => void` | — | 提交路径时触发，同时返回对应选项对象 |
 | placeholder | `string` | — | 占位文案 |
-| disabled | `boolean` | `false` | 禁用 |
+| disabled | `boolean` | `false` | 禁用触发器并立即关闭已打开的面板 |
 | allowClear | `boolean` | `false` | 显示清除按钮 |
 | showSearch | `boolean | { filter?, render?, limit? }` | — | 搜索路径,支持 boolean / 对象配置 |
-| popupClassName / dropdownClassName | `string` | — | 浮层面板 className |
+| optionRender | `(option, info) => ReactNode` | — | 自定义每一级菜单节点内容，并获得 depth / selected / hasChildren 状态 |
+| selectedRender | `(selectedOptions, values) => ReactNode` | — | 自定义触发器中的紧凑已选路径内容 |
+| listHeight | `number` | `280` | 每列和搜索结果滚动区域的最大高度 |
+| popupStyle | `CSSProperties` | — | Portal 浮层内联样式，可覆盖宽度或高度 |
+| popupClassName / dropdownClassName | `string` | — | Portal 浮层面板 className；会自动跟随所属 Modal / Drawer 的层级 |
 | changeOnSelect | `boolean` | `false` | 允许选中非叶子节点 |
 
 

package/docs/llms/checkbox.md

@@ -16,6 +16,17 @@ import { Checkbox } from "@fangxinyan/lumina";
 <Checkbox checked={v} onChange={setV} label="同意协议" />
 ```
 
+### 原生表单
+
+name / value / required 会落到真实 checkbox，可直接参与浏览器表单提交与约束校验。
+
+```tsx
+<form onSubmit={(event) => event.preventDefault()}>
+  <Checkbox name="agreement" value="accepted" required label="同意条款" />
+  <Button type="submit">验证提交</Button>
+</form>
+```
+
 ### 全选/半选
 
 indeterminate 用来表示部分选中。
@@ -34,6 +45,8 @@ indeterminate 用来表示部分选中。
 | indeterminate | `boolean` | `false` | 半选态 |
 | onChange | `(checked: boolean) => void` | — | 变更 |
 | label | `ReactNode` | — | 右侧文案 |
+| name / value | `string` | — | 原生表单字段名与选中时提交的值 |
+| required / form | `boolean / string` | — | 原生必填约束与关联 form id |
 | disabled | `boolean` | `false` | 禁用 |
 
 

package/docs/llms/collapse.md

@@ -18,10 +18,18 @@ import { Collapse } from "@fangxinyan/lumina";
 
 ### 多项展开
 
-multiple 允许同时展开多个面板。
+multiple={true} 允许同时展开多个面板，也是默认行为。
 
 ```tsx
-<Collapse defaultActiveKey={["1", "2"]} ... />
+<Collapse multiple defaultActiveKey={["1", "2"]} ... />
+```
+
+### multiple={false}
+
+单开模式最多保留一项；即使 activeKey / defaultActiveKey 传入数组，也只采用首项。
+
+```tsx
+<Collapse multiple={false} defaultActiveKey={["1", "2"]} ... />
 ```
 
 ### 手风琴模式
@@ -56,12 +64,12 @@ collapsible="disabled" 会禁用所有项的展开交互。
 | --- | --- | --- | --- |
 | items \* | `CollapseItem[]` | — | 面板数据 |
 | accordion | `boolean` | `false` | 手风琴模式(同一时刻最多一项) |
-| multiple | `boolean` | `true` | 可同时展开多个 |
+| multiple | `boolean` | `true` | 是否可同时展开多个；false 时数组键值只保留首项 |
 | collapsible | `"header" | "icon" | "disabled"` | `"header"` | 展开触发区域 |
-| activeKey / defaultActiveKey | `string | string[]` | — | 受控/初始展开 |
+| activeKey / defaultActiveKey | `string | string[]` | — | 受控/初始展开；单开模式会归一为至多一项 |
 | ghost | `boolean` | `false` | 无外框/阴影的轻量样式 |
 | size | `"small" | "middle" | "large"` | `"middle"` | 尺寸 |
-| onChange | `(keys: string[]) => void` | — | 展开变更 |
+| onChange | `(keys: string[]) => void` | — | 展开变更；单开模式仍统一返回长度不超过 1 的数组 |
 
 
 ---

package/docs/llms/colorpicker.md

@@ -5,7 +5,7 @@
 ## 导入
 
 ```tsx
-import { ColorPicker } from "@fangxinyan/lumina";
+import { ColorPicker, type ColorPickerTriggerElement } from "@fangxinyan/lumina";
 ```
 
 ## 示例
@@ -52,7 +52,7 @@ presets 传入十六进制数组,面板底部会渲染一排色块。
 
 ### 自定义触发器
 
-将 children 作为触发器;色块容器会继承传入的交互元素。
+将 children 作为触发器;纯文本或不能接收 ref 的组件会自动获得可访问的包装节点。
 
 ```tsx
 <ColorPicker value={brand} onChange={setBrand}>
@@ -75,7 +75,8 @@ presets 传入十六进制数组,面板底部会渲染一排色块。
 | showText | `boolean` | `false` | 触发器右侧显示 hex |
 | disabled | `boolean` | `false` | 禁用 |
 | open / defaultOpen / onOpenChange | `—` | — | 受控面板显隐 |
-| children | `ReactNode` | — | 自定义触发器 |
+| children | `ReactNode` | — | 自定义触发器;不能接收 ref 的节点会自动包装 |
+| ref | `Ref<ColorPickerTriggerElement>` | — | 实际触发节点;自定义内容可能返回包装节点 |
 
 
 ---

package/docs/llms/commandpalette.md

@@ -12,7 +12,7 @@ import { CommandPalette } from "@fangxinyan/lumina";
 
 ### 基础 + 快捷键
 
-在当前页面按 ⌘K / Ctrl+K 打开。分组、快捷键提示、键盘导航都已内置。
+在当前页面按 ⌘K / Ctrl+K 打开。方向键、Home / End 会跳过禁用项；Esc 只关闭当前最上层浮层。
 
 ```tsx
 const [open, setOpen] = useState(false);
@@ -27,7 +27,13 @@ useEffect(() => {
   return () => window.removeEventListener("keydown", h);
 }, []);
 
-<CommandPalette open={open} onOpenChange={setOpen} items={[...]} />
+<CommandPalette
+  open={open}
+  onOpenChange={setOpen}
+  items={[...]}
+  className="app-command-panel"
+  overlayClassName="app-command-mask"
+/>
 ```
 
 ## API
@@ -43,6 +49,8 @@ useEffect(() => {
 | emptyText | `ReactNode` | — | 无结果占位 |
 | resetOnOpen | `boolean` | `true` | 打开时清空输入 |
 | footer | `ReactNode` | — | 底部区;null 隐藏 |
+| className | `string` | — | 命令面板节点 className(ref 同样指向该节点) |
+| overlayClassName | `string` | — | 全屏遮罩层 className |
 
 
 **CommandItem**

package/docs/llms/contextmenu.md

@@ -12,6 +12,8 @@ import { ContextMenu } from "@fangxinyan/lumina";
 
 ### 基础
 
+方向键、Home / End、Enter 提供完整键盘导航；Esc 会关闭并把焦点归还给打开前的控件，Tab 会退出并关闭菜单。
+
 ```tsx
 <ContextMenu items={[
   { key: "copy", label: "复制", shortcut: "⌘C", onSelect: () => {} },
@@ -31,6 +33,16 @@ import { ContextMenu } from "@fangxinyan/lumina";
 <ContextMenu items={[...]}>...
 ```
 
+### 禁用自定义菜单
+
+disabled 会立即关闭已打开的菜单，之后不再拦截 contextmenu，浏览器原生菜单恢复可用。
+
+```tsx
+<ContextMenu disabled items={items}>
+  <div>这里使用浏览器原生右键菜单</div>
+</ContextMenu>
+```
+
 ## API
 
 **ContextMenu**
@@ -38,8 +50,8 @@ import { ContextMenu } from "@fangxinyan/lumina";
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | items \* | `ContextMenuItem[]` | — | 菜单项 |
-| children \* | `ReactElement` | — | 触发元素(恰好一个) |
-| disabled | `boolean` | — | 禁用,恢复浏览器原生菜单 |
+| children \* | `ReactNode` | — | 任意触发内容；内部 display: contents 包装不改变布局 |
+| disabled | `boolean` | `false` | 禁用并关闭当前菜单，恢复浏览器原生菜单 |
 | minWidth | `number` | `180` | 面板最小宽度 |
 
 

package/docs/llms/datepicker.md

@@ -47,6 +47,12 @@ min / max 与 disabledDate 会同步作用于 Calendar 单元格和手动输入
 <DatePicker size="lg" disabled />
 ```
 
+### 自定义格式与解析
+
+```tsx
+<DatePicker format={formatDotDate} parse={parseDotDate} />
+```
+
 ## API
 
 **DatePicker**
@@ -56,6 +62,7 @@ min / max 与 disabledDate 会同步作用于 Calendar 单元格和手动输入
 | value / defaultValue | `Date | null` | — | 受控/初始日期 |
 | onChange | `(date: Date | null, dateString: string) => void` | — | 选择或清空时触发 |
 | format | `"YYYY-MM-DD" | "YYYY/MM/DD" | "YYYY年MM月DD日" | ((date) => string)` | `"YYYY-MM-DD"` | 显示格式或自定义格式化函数 |
+| parse | `(input: string) => Date | null` | — | 自定义 format 函数对应的输入解析器 |
 | min / max | `Date` | — | 可选日期范围 |
 | disabledDate | `(date: Date) => boolean` | — | 自定义禁用日期 |
 | size | `"sm" | "md" | "lg"` | `"md"` | 输入框尺寸 |

package/docs/llms/datetimepicker.md

@@ -58,6 +58,12 @@ const [startAt, setStartAt] = useState<Date | null>(new Date(2026, 4, 25, 9, 30)
 <DateTimePicker size="lg" disabled />
 ```
 
+### 自定义格式与解析
+
+```tsx
+<DateTimePicker format={formatSlashDateTime} parse={parseSlashDateTime} />
+```
+
 ## API
 
 **DateTimePicker**
@@ -67,6 +73,7 @@ const [startAt, setStartAt] = useState<Date | null>(new Date(2026, 4, 25, 9, 30)
 | value / defaultValue | `Date | null` | — | 受控/初始日期时间 |
 | onChange | `(date: Date | null, dateString: string) => void` | — | 选择或清空时触发 |
 | format | `"YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | ((date) => string)` | `"YYYY-MM-DD HH:mm"` | 显示格式或自定义格式化函数 |
+| parse | `(input: string) => Date | null` | — | 自定义 format 函数对应的输入解析器 |
 | showSecond | `boolean` | — | 显示秒列 |
 | hourStep / minuteStep / secondStep | `number` | `1` | 列选项步进 |
 | min / max | `Date` | — | 可选日期时间范围 |

package/docs/llms/drawer.md

@@ -12,6 +12,8 @@ import { Drawer } from "@fangxinyan/lumina";
 
 ### 基础
 
+有遮罩时会锁定页面滚动并把焦点限制在抽屉及其子浮层；关闭后焦点回到原触发控件。
+
 ```tsx
 <Drawer open={d} onClose={...} title="标题">...</Drawer>
 ```
@@ -27,6 +29,16 @@ extra 渲染到标题右边,常用来放刷新 / 更多 / 保存按钮。
 />
 ```
 
+### 拟态阴影安全区
+
+抽屉只让正文区滚动，并自动为拟态阴影留出空间；全宽内容可通过 bodyInset="none" 贴边。
+
+```tsx
+<Drawer open={open} title="连接配置">
+  <Card title="远程节点">无需手工补 padding 或修改 overflow。</Card>
+</Drawer>
+```
+
 ### 四个方向
 
 placement 控制滑出方向;top / bottom 用 size 控高度。
@@ -38,7 +50,7 @@ placement 控制滑出方向;top / bottom 用 size 控高度。
 
 ### 无遮罩 (mask={false})
 
-关闭遮罩的抽屉不阻塞页面其他交互,适合辅助面板。
+关闭遮罩的抽屉不锁定滚动、不限制焦点，页面其他区域仍可交互；Esc 与关闭后的焦点归还仍然生效。
 
 ```tsx
 <Drawer mask={false} />
@@ -62,21 +74,25 @@ placement 控制滑出方向;top / bottom 用 size 控高度。
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | open \* | `boolean` | — | 可见 |
-| onClose | `() => void` | — | 关闭回调 |
+| onClose | `() => void` | — | 关闭回调；Esc 仅由当前最上层浮层响应 |
 | placement | `"left" | "right" | "top" | "bottom"` | `"right"` | 出现位置 |
 | size | `number | string` | `380` | 宽度(左右)或高度(上下) |
 | title / footer / children | `ReactNode` | — | 头/脚/主体 |
 | extra | `ReactNode` | — | 标题右侧的附加操作区 |
-| mask | `boolean` | `true` | 是否渲染遮罩 |
+| bodyClassName / bodyStyle / bodyProps | `string / CSSProperties / HTMLAttributes<HTMLDivElement>` | — | 正文容器的 class、样式与 DOM 属性 |
+| bodyOverflow | `CSSProperties['overflow']` | — | 正文容器 overflow 快捷控制 |
+| bodyInset | `"safe" | "none"` | `"safe"` | 正文边缘留白；safe 自动保护拟态阴影，none 用于贴边内容 |
+| mask | `boolean` | `true` | 是否渲染遮罩；有遮罩时启用焦点限制与页面滚动锁定 |
 | maskClosable | `boolean` | `true` | 点击遮罩关闭 |
 | maskClassName | `string` | — | 遮罩层 className |
 | maskStyle | `CSSProperties` | — | 遮罩层内联样式 |
+| className | `string` | — | 抽屉面板 className；ref 同样指向面板 |
 | keyboard | `boolean` | `true` | Esc 关闭 |
 | closable | `boolean` | `true` | 右上角 × |
 | closeIcon | `ReactNode` | — | 自定义关闭图标 |
 | destroyOnClose | `boolean` | `false` | 关闭时卸载子树 |
 | afterOpenChange | `(open: boolean) => void` | — | 动画结束回调 |
-| zIndex | `number` | — | 覆盖 z-index |
+| zIndex | `number` | — | 覆盖抽屉起始层级；所属子浮层会自动排在其上 |
 
 
 ---

package/docs/llms/form.md

@@ -106,7 +106,7 @@ form.resetFields()
 | onFinish / onFinishFailed | `(values | {values, errorFields}) => void` | — | 提交成功/失败 |
 | onValuesChange | `(changed, all) => void` | — | 任一字段变化 |
 | requiredMark | `boolean` | `true` | 是否在必填 label 前显示 * |
-| disabled | `boolean` | — | 整体禁用 |
+| disabled | `boolean` | — | 强制整体禁用;子控件 disabled={false} 不会覆盖 |
 
 
 **Form.Item**
@@ -119,9 +119,12 @@ form.resetFields()
 | noStyle | `boolean` | — | 不渲染外层 item 包装 |
 | valuePropName | `string` | `"value"` | 注入值的 prop 名 |
 | trigger | `string` | `"onChange"` | 监听的事件名 |
+| validateTrigger | `string | string[]` | `"onChange"` | 触发校验的事件名，可配置多个 |
 | initialValue | `any` | — | 此字段初始值;优先级低于 Form initialValues |
+| required | `boolean` | — | 显示必填标记并向真实控件注入 aria-required |
 | help / extra | `ReactNode` | — | 辅助/补充说明 |
 | hidden | `boolean` | — | 隐藏(字段仍保留) |
+| ref / 原生 div 属性 | `Ref<HTMLDivElement> / HTMLAttributes` | — | ref 落到外层节点;支持 className / style / id / data-* / aria-* |
 
 
 **Rule**
@@ -132,7 +135,7 @@ form.resetFields()
 | message | `string` | — | 错误提示文案 |
 | pattern | `RegExp` | — | 正则校验 |
 | min / max / len | `number` | — | 字符串/数组长度或数字范围 |
-| type | `string` | — | "string" \| "number" \| "email" \| "url" \| "array" |
+| type | `"string" | "number" | "email" | "url" | "array"` | — | 字符串、数字、数组及严格 email / url 格式校验 |
 | validator | `(rule, value) => Promise<void>` | — | 自定义,抛出错误或 reject 视为失败 |
 
 

package/docs/llms/icon.md

@@ -5,7 +5,7 @@
 ## 导入
 
 ```tsx
-import { Icon } from "@fangxinyan/lumina";
+import { Icon, DeleteOutlined, LoadingOutlined, StarFilled, ICON_NAMES } from "@fangxinyan/lumina";
 ```
 
 ## 示例
@@ -19,6 +19,20 @@ import { Icon } from "@fangxinyan/lumina";
 <Icon name="heart" size={20} stroke={1.5} />
 ```
 
+### 命名图标组件
+
+Outlined / Filled 命名组件与 Icon 共用同一入口，也支持对应名称的包子路径。
+
+```tsx
+import { DeleteOutlined } from "@fangxinyan/lumina/DeleteOutlined";
+import { LoadingOutlined } from "@fangxinyan/lumina/LoadingOutlined";
+import { StarFilled } from "@fangxinyan/lumina/StarFilled";
+
+<DeleteOutlined aria-label="删除" />
+<LoadingOutlined aria-label="加载中" />
+<StarFilled aria-label="收藏" />
+```
+
 ## API
 
 **Icon**
@@ -28,6 +42,16 @@ import { Icon } from "@fangxinyan/lumina";
 | name \* | `IconName` | — | 图标名 |
 | size | `number` | `16` | 尺寸 (px) |
 | stroke | `number` | `2` | 描边粗细 |
+| title | `string` | — | 语义图标的可访问标题；省略时默认作为装饰图标 |
+
+
+**NamedIconProps**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| size | `number | string` | `"1em"` | 尺寸 |
+| spin | `boolean` | — | 旋转动画 |
+| rotate | `number` | — | 静态旋转角度 |
 
 
 ---

package/docs/llms/image.md

@@ -28,6 +28,25 @@ import { Image, ImageGrid, SpriteImage, LayeredImage } from "@fangxinyan/lumina"
 />
 ```
 
+### 精细预览
+
+点击或按 Enter / Space 打开；预览层内置焦点限制、Esc 关闭与焦点归还，以及放大、缩小、适配窗口、1:1、滚轮缩放和拖拽平移。
+
+```tsx
+<Image
+  src={url}
+  width={260}
+  height={180}
+  previewMaxWidth="90vw"
+  previewMaxHeight="76vh"
+  renderPreviewToolbar={({ fitToWindow, scale }) => (
+    <Button size="sm" variant="ghost" icon="star" onClick={fitToWindow}>
+      标记 {Math.round(scale * 100)}%
+    </Button>
+  )}
+/>
+```
+
 ### 图标 / 原始资源
 
 variant="icon" 会默认去掉外层 padding,适合 1:1 装备、物品、头像缩略图；variant="raw" 保留原始图片比例。
@@ -79,9 +98,11 @@ LayeredImage 将多张图片叠在同一个盒子里,适合头像 + 头像框、
 | frame | `boolean` | `framed 时 true` | 是否保留内层凹陷 frame |
 | padding | `number | string` | — | 外层留白,raw/icon 默认 0 |
 | objectFit / objectPosition | `CSSProperties` | — | 底层 img 的 object-fit / object-position |
-| preview | `boolean` | `true` | 支持点击全屏预览 |
+| preview | `boolean` | `framed 时 true` | 启用点击或 Enter / Space 全屏预览；打开时限制焦点并锁定滚动，Esc 关闭后归还焦点 |
 | previewClassName | `string` | — | 预览蒙层 className |
 | previewStyle | `CSSProperties` | — | 预览蒙层内联样式 |
+| previewMaxWidth / previewMaxHeight | `number | string` | `"80vw" / "80vh"` | 预览适配态的最大尺寸 |
+| renderPreviewToolbar | `(controls) => ReactNode` | — | 在预览工具栏追加自定义按钮；追加控件同样参与焦点循环 |
 | hover | `boolean` | `true` | 悬浮放大 |
 | placeholder | `ReactNode` | — | 占位/错误时内容 |
 | imgProps | `ImgHTMLAttributes` | — | 透传到底层 img 的属性 |

package/docs/llms/list.md

@@ -16,6 +16,17 @@ import { List } from "@fangxinyan/lumina";
 <List items={[{ key, title, description, avatar, actions }]} />
 ```
 
+### 可点击与无分隔线
+
+提供 onClick 时整行获得按钮语义；dividers={false} 适合更轻量的操作列表。
+
+```tsx
+<List
+  dividers={false}
+  items={[{ title: "下载构建产物", onClick: handleClick }]}
+/>
+```
+
 ## API
 
 **List**