@fangxinyan/lumina 0.2.0 → 0.3.0

package/docs/llms/cascader.md

@@ -0,0 +1,33 @@
+# Cascader 级联选择
+
+> 层级关联数据集合中的多级选择。
+
+## 导入
+
+```tsx
+import { Cascader } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Cascader options={regions} value={addr} onChange={setAddr} />
+```
+
+## API
+
+**Cascader**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| options \* | `CascaderOption[]` | — | 层级选项树 |
+| value / defaultValue | `string[]` | — | 受控/初始路径 |
+| onChange | `(path: string[]) => void` | — | 选择叶子时触发 |
+| placeholder | `string` | — | 占位文案 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/checkbox.md

@@ -0,0 +1,41 @@
+# Checkbox 复选框
+
+> 在一组选项中进行多项选择,或独立切换某个开关项。
+
+## 导入
+
+```tsx
+import { Checkbox } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Checkbox checked={v} onChange={setV} label="同意协议" />
+```
+
+### 全选/半选
+
+indeterminate 用来表示部分选中。
+
+```tsx
+<Checkbox indeterminate={some} checked={all} onChange={...} label="全选" />
+```
+
+## API
+
+**Checkbox**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| checked / defaultChecked | `boolean` | — | 受控/初始 |
+| indeterminate | `boolean` | `false` | 半选态 |
+| onChange | `(checked: boolean) => void` | — | 变更 |
+| label | `ReactNode` | — | 右侧文案 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/colorpicker.md

@@ -0,0 +1,82 @@
+# ColorPicker 颜色选择
+
+> 拟态风格的颜色选择器:HSV 色域、色相、hex 输入、预设调色板。
+
+## 导入
+
+```tsx
+import { ColorPicker } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+非受控用法,点击色块弹出面板。
+
+```tsx
+<ColorPicker defaultValue="#ff6b6b" onChange={setColor} />
+```
+
+### 受控
+
+实时同步 value,失焦 / 拖拽结束时再调用 onChangeComplete。
+
+```tsx
+<ColorPicker value={color} onChange={setColor} showText />
+```
+
+### 尺寸
+
+```tsx
+<ColorPicker size="sm" />
+<ColorPicker />
+<ColorPicker size="lg" />
+```
+
+### 禁用
+
+```tsx
+<ColorPicker disabled defaultValue="#868e96" />
+```
+
+### 自定义预设
+
+presets 传入十六进制数组,面板底部会渲染一排色块。
+
+```tsx
+<ColorPicker
+  presets={["#ff6b6b", "#ffd43b", "#51cf66", "#339af0", "#845ef7"]}
+/>
+```
+
+### 自定义触发器
+
+将 children 作为触发器;色块容器会继承传入的交互元素。
+
+```tsx
+<ColorPicker value={brand} onChange={setBrand}>
+  <Button icon="palette">品牌色 · {brand}</Button>
+</ColorPicker>
+```
+
+## API
+
+**ColorPicker**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `string` | `"#845ef7"` | 十六进制颜色 |
+| onChange | `(hex: string) => void` | — | 每次变化触发(拖拽 / 输入 / 预设点击) |
+| onChangeComplete | `(hex: string) => void` | — | 拖拽/输入结束触发 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 触发器尺寸 |
+| placement | `"top" | "bottom" | "left" | "right"` | `"bottom"` | 面板位置 |
+| presets | `string[]` | — | 预设色数组 |
+| showText | `boolean` | `false` | 触发器右侧显示 hex |
+| disabled | `boolean` | `false` | 禁用 |
+| open / defaultOpen / onOpenChange | `—` | — | 受控面板显隐 |
+| children | `ReactNode` | — | 自定义触发器 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/commandpalette.md

@@ -0,0 +1,58 @@
+# CommandPalette ⌘K 命令面板
+
+> 全局命令搜索与执行入口。
+
+## 示例
+
+### 基础 + 快捷键
+
+在当前页面按 ⌘K / Ctrl+K 打开。分组、快捷键提示、键盘导航都已内置。
+
+```tsx
+const [open, setOpen] = useState(false);
+useEffect(() => {
+  const h = (e: KeyboardEvent) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+      e.preventDefault();
+      setOpen(o => !o);
+    }
+  };
+  window.addEventListener("keydown", h);
+  return () => window.removeEventListener("keydown", h);
+}, []);
+
+<CommandPalette open={open} onOpenChange={setOpen} items={[...]} />
+```
+
+## API
+
+**CommandPalette**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| open / onOpenChange \* | `boolean / (open: boolean) => void` | — | 受控开关 |
+| items \* | `CommandItem[]` | — | 所有命令项 |
+| placeholder | `string` | `"搜索命令…"` | 搜索框占位文本 |
+| filter | `(item, query) => boolean` | `子序列匹配` | 自定义过滤函数 |
+| emptyText | `ReactNode` | — | 无结果占位 |
+| resetOnOpen | `boolean` | `true` | 打开时清空输入 |
+| footer | `ReactNode` | — | 底部区;null 隐藏 |
+
+
+**CommandItem**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `string` | — | 唯一键 |
+| label \* | `string` | — | 主文案(也参与搜索) |
+| description | `ReactNode` | — | 副标题 |
+| icon | `ReactNode` | — | 前置图标 |
+| shortcut | `ReactNode` | — | 右侧快捷键 |
+| keywords | `string[]` | — | 额外搜索关键词 |
+| group | `string` | — | 分组标题 |
+| disabled | `boolean` | — | 禁用 |
+| onSelect | `() => void` | — | 选中回调(会自动关闭面板) |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/contextmenu.md

@@ -0,0 +1,55 @@
+# ContextMenu 右键菜单
+
+> 桌面应用风格的右键上下文菜单。
+
+## 示例
+
+### 基础
+
+```tsx
+<ContextMenu items={[
+  { key: "copy", label: "复制", shortcut: "⌘C", onSelect: () => {} },
+  { key: "cut",  label: "剪切", shortcut: "⌘X", onSelect: () => {} },
+  { key: "d",    type: "divider" },
+  { key: "del",  label: "删除", danger: true, onSelect: () => {} },
+]}>
+  <div>右键点击我</div>
+</ContextMenu>
+```
+
+### 文件管理器示例
+
+典型的文件右键菜单,带图标、快捷键、分组分隔、危险操作高亮。
+
+```tsx
+<ContextMenu items={[...]}>...
+```
+
+## API
+
+**ContextMenu**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| items \* | `ContextMenuItem[]` | — | 菜单项 |
+| children \* | `ReactElement` | — | 触发元素(恰好一个) |
+| disabled | `boolean` | — | 禁用,恢复浏览器原生菜单 |
+| minWidth | `number` | `180` | 面板最小宽度 |
+
+
+**ContextMenuItem**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `string` | — | 唯一键 |
+| label | `ReactNode` | — | 文案 |
+| icon | `ReactNode` | — | 前置图标 |
+| shortcut | `ReactNode` | — | 右侧快捷键提示 |
+| disabled | `boolean` | — | 禁用 |
+| danger | `boolean` | — | 危险态(红色) |
+| type | `"divider"` | — | 置为 "divider" 渲染分隔线 |
+| onSelect | `() => void` | — | 选中回调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/divider.md

@@ -0,0 +1,69 @@
+# Divider 分隔符
+
+> 对内容进行分割。
+
+## 导入
+
+```tsx
+import { Divider } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 水平分隔
+
+```tsx
+<Divider />
+```
+
+### 带文字
+
+```tsx
+<Divider label="分割标题" />
+```
+
+### 文字位置
+
+orientation 控制文字在线上的位置。
+
+```tsx
+<Divider label="左对齐" orientation="left" />
+<Divider label="居中" orientation="center" />
+<Divider label="右对齐" orientation="right" />
+```
+
+### 虚线
+
+dashed 切换为虚线样式,也适用于带文字或垂直方向。
+
+```tsx
+<Divider dashed />
+<Divider dashed label="虚线带文字" />
+<Row>
+  <span>左</span>
+  <Divider direction="vertical" dashed />
+  <span>右</span>
+</Row>
+```
+
+### 垂直分隔
+
+```tsx
+<Divider direction="vertical" />
+```
+
+## API
+
+**Divider**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| direction | `"horizontal" | "vertical"` | `"horizontal"` | 方向 |
+| label | `ReactNode` | — | 中部文字 |
+| orientation | `"left" | "center" | "right"` | `"center"` | 文字位置(仅水平) |
+| dashed | `boolean` | `false` | 虚线样式 |
+| sunken | `boolean` | `false` | 凹陷凹槽样式 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/drawer.md

@@ -0,0 +1,70 @@
+# Drawer 抽屉
+
+> 从屏幕边缘滑出的浮层。
+
+## 导入
+
+```tsx
+import { Drawer } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Drawer open={d} onClose={...} title="标题">...</Drawer>
+```
+
+### 标题右侧 extra
+
+extra 渲染到标题右边,常用来放刷新 / 更多 / 保存按钮。
+
+```tsx
+<Drawer
+  title="订单详情"
+  extra={<><IconButton icon="edit" tip="编辑" /><Button variant="primary">保存</Button></>}
+/>
+```
+
+### 四个方向
+
+placement 控制滑出方向;top / bottom 用 size 控高度。
+
+```tsx
+<Drawer placement="left" size={320} />
+<Drawer placement="top" size={240} />
+```
+
+### 无遮罩 (mask={false})
+
+关闭遮罩的抽屉不阻塞页面其他交互,适合辅助面板。
+
+```tsx
+<Drawer mask={false} />
+```
+
+## API
+
+**Drawer**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| open \* | `boolean` | — | 可见 |
+| onClose | `() => void` | — | 关闭回调 |
+| placement | `"left" | "right" | "top" | "bottom"` | `"right"` | 出现位置 |
+| size | `number | string` | `380` | 宽度(左右)或高度(上下) |
+| title / footer / children | `ReactNode` | — | 头/脚/主体 |
+| extra | `ReactNode` | — | 标题右侧的附加操作区 |
+| mask | `boolean` | `true` | 是否渲染遮罩 |
+| maskClosable | `boolean` | `true` | 点击遮罩关闭 |
+| keyboard | `boolean` | `true` | Esc 关闭 |
+| closable | `boolean` | `true` | 右上角 × |
+| closeIcon | `ReactNode` | — | 自定义关闭图标 |
+| destroyOnClose | `boolean` | `false` | 关闭时卸载子树 |
+| afterOpenChange | `(open: boolean) => void` | — | 动画结束回调 |
+| zIndex | `number` | — | 覆盖 z-index |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/empty.md

@@ -0,0 +1,52 @@
+# Empty 空状态
+
+> 列表、页面或容器无数据时的占位。
+
+## 导入
+
+```tsx
+import { Empty } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Empty title="暂无项目" description="创建一个开始吧" action={<Button>新建</Button>} />
+```
+
+### Subtle 变体
+
+去掉凹陷图标框,用于嵌入已有卡片/对话框中。
+
+```tsx
+<Empty variant="subtle" icon={<Icon name="search" size={28} />} title="未找到结果" />
+```
+
+### 尺寸
+
+sm 适合列表内嵌,md 是默认,lg 用作整页占位。
+
+```tsx
+<Empty size="sm" title="暂无数据" />
+<Empty size="md" title="暂无数据" />
+<Empty size="lg" title="暂无数据" />
+```
+
+## API
+
+**Empty**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| title | `ReactNode` | `"暂无内容"` | 标题 |
+| description | `ReactNode` | — | 描述 |
+| icon | `ReactNode` | — | 图标 |
+| action | `ReactNode` | — | 底部操作 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
+| variant | `"default" | "subtle"` | `"default"` | 样式 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/icon.md

@@ -0,0 +1,34 @@
+# Icon 图标
+
+> 线性图标集,继承当前文字颜色,可调整尺寸与描边。
+
+## 导入
+
+```tsx
+import { Icon } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+通过 name 指定图标,size 控制尺寸,stroke 控制描边粗细。
+
+```tsx
+<Icon name="search" size={16} />
+<Icon name="heart" size={20} stroke={1.5} />
+```
+
+## API
+
+**Icon**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| name \* | `IconName` | — | 图标名 |
+| size | `number` | `16` | 尺寸 (px) |
+| stroke | `number` | `2` | 描边粗细 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/image.md

@@ -0,0 +1,39 @@
+# Image 图片
+
+> 凹陷外框包裹的图片容器,带预览、错误占位。
+
+## 导入
+
+```tsx
+import { Image, ImageGrid } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Image src={url} width={240} height={160} />
+```
+
+### 图片组
+
+```tsx
+<ImageGrid images={images} />
+```
+
+## API
+
+**Image**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| src | `string` | — | 图片 URL |
+| width / height | `number | string` | — | 尺寸 |
+| preview | `boolean` | `true` | 支持点击全屏预览 |
+| hover | `boolean` | `true` | 悬浮放大 |
+| placeholder | `ReactNode` | — | 占位/错误时内容 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/input.md

@@ -0,0 +1,127 @@
+# Input 输入框
+
+> 凹陷凹槽式输入域,支持前后置图标、错误态、禁用态。
+
+## 导入
+
+```tsx
+import { Input, Textarea } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+const [v, setV] = useState("");
+<Input placeholder="输入用户名" value={v} onChange={setV} leadingIcon="user" />
+```
+
+### 前后置图标
+
+leadingIcon / trailingIcon。
+
+```tsx
+<Input placeholder="搜索..." leadingIcon="search" />
+```
+
+### 密码切换
+
+trailingIcon 可点击切换密码可见性。
+
+```tsx
+<Input
+  type={showPw ? "text" : "password"}
+  trailingIcon={showPw ? "eyeOff" : "eye"}
+  onTrailingIconClick={() => setShowPw(s => !s)}
+/>
+```
+
+### 校验错误
+
+invalid 触发红色凹槽。
+
+```tsx
+<Input invalid hint="请输入有效的邮箱" />
+```
+
+### 可清除
+
+allowClear 在值非空时显示 × 按钮,点击即清空。
+
+```tsx
+<Input value={v} onChange={setV} allowClear placeholder="输入后右侧会出现 ×" />
+```
+
+### 前缀 / 后缀
+
+prefix/suffix 在输入框内部以静态文本形式呈现,常用于单位或协议。
+
+```tsx
+<Input prefix="https://" suffix=".com" defaultValue="lumina" />
+<Input prefix="¥" suffix="元" defaultValue="1280" />
+```
+
+### 字数统计 + maxLength
+
+showCount 显示当前字数,配合 maxLength 显示 N / max。
+
+```tsx
+<Input
+  value={v}
+  onChange={setV}
+  maxLength={20}
+  showCount
+  placeholder="最多输入 20 个字"
+/>
+```
+
+### 多行文本
+
+Textarea 与 Input 共享同款凹槽,也支持 allowClear / maxLength / showCount。
+
+```tsx
+<Textarea
+  placeholder="..."
+  value={msg}
+  onChange={setMsg}
+  allowClear
+  maxLength={300}
+  showCount
+/>
+```
+
+## API
+
+**Input**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `string` | — | 受控值 / 初值 |
+| onChange | `(value: string, e) => void` | — | 变更回调 |
+| placeholder | `string` | — | 占位文案 |
+| leadingIcon / trailingIcon | `IconName` | — | 前/后置图标 |
+| prefix | `ReactNode` | — | 左侧内嵌内容(在 leadingIcon 之后) |
+| suffix | `ReactNode` | — | 右侧内嵌内容(在 trailingIcon 之前) |
+| allowClear | `boolean` | `false` | 显示内置的清除按钮 |
+| maxLength | `number` | — | 最大字符数,透传至原生 input |
+| showCount | `boolean` | `false` | 在输入框下方显示字数统计 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
+| invalid | `boolean` | `false` | 错误态 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+**Textarea**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `string` | — | 受控值 / 初值 |
+| onChange | `(value: string, e) => void` | — | 变更回调 |
+| allowClear | `boolean` | `false` | 右上角显示清除按钮 |
+| maxLength | `number` | — | 最大字符数 |
+| showCount | `boolean` | `false` | 显示字数统计 |
+| invalid | `boolean` | `false` | 错误态 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/intro.md

@@ -0,0 +1,6 @@
+# Lumina
+
+> 为 Electron 应用定制的拟态风格 React 组件库。
+
+---
+[← 回到索引](../llms.md)