@fangxinyan/lumina 0.1.6 → 0.2.1

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)

package/docs/llms/list.md

@@ -0,0 +1,41 @@
+# List 列表
+
+> 承载一组结构化的同质化数据。
+
+## 导入
+
+```tsx
+import { List } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础列表
+
+```tsx
+<List items={[{ key, title, description, avatar, actions }]} />
+```
+
+## API
+
+**List**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| items \* | `ListItem[]` | — | 数据列表 |
+| dividers | `boolean` | `true` | 项之间显示分隔线 |
+
+
+**ListItem**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `string` | — | 唯一键 |
+| title / description | `ReactNode` | — | 标题/描述 |
+| avatar | `ReactNode` | — | 前置图标或头像 |
+| actions | `ReactNode` | — | 右侧操作区 |
+| onClick | `() => void` | — | 点击回调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/modal.md

@@ -0,0 +1,89 @@
+# Modal 对话框
+
+> 在不离开当前页面的前提下处理事务。
+
+## 导入
+
+```tsx
+import { Modal } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Modal open={m} onClose={...} title="标题">...</Modal>
+```
+
+### 确认操作 (footer 自定义)
+
+用 footer 自定义底部按钮。传 null 可以去掉 footer。
+
+```tsx
+<Modal footer={<><Button>取消</Button><Button danger>删除</Button></>}>...
+```
+
+### onOk / onCancel + 按钮定制
+
+用默认 footer 的 onOk / onCancel 区分动作,okText / cancelText 改文案,okButtonProps 透传样式。
+
+```tsx
+<Modal
+  onOk={handleSave}
+  onCancel={() => setOpen(false)}
+  okText="发布"
+  cancelText="不发了"
+  okButtonProps={{ icon: "send" }}
+/>
+```
+
+### 异步 confirmLoading
+
+提交过程中 confirmLoading 显示按钮 spinner 并自动禁用;完成后外层再 setOpen(false)。
+
+```tsx
+<Modal confirmLoading={submitting} onOk={async () => {
+  setSubmitting(true);
+  await api.save();
+  setSubmitting(false);
+  setOpen(false);
+}} />
+```
+
+### 隐藏关闭按钮
+
+closable={false} 隐藏右上角 ×,closeIcon 可自定义。
+
+```tsx
+<Modal closable={false} />
+<Modal closeIcon={<Icon name="chevDown" />} />
+```
+
+## API
+
+**Modal**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| open \* | `boolean` | — | 是否可见 |
+| onClose | `() => void` | — | 关闭回调(遮罩/Esc/关闭按钮) |
+| onOk | `() => void` | — | 默认 OK 按钮点击 |
+| onCancel | `() => void` | — | 默认 Cancel 按钮 / Esc / 关闭 / 遮罩触发,缺省则用 onClose |
+| title / description | `ReactNode` | — | 标题/说明 |
+| footer | `ReactNode` | — | 自定义底部(null 去除) |
+| okText / cancelText | `ReactNode` | `"确定" / "取消"` | 默认按钮文案 |
+| okButtonProps / cancelButtonProps | `Partial<ButtonProps>` | — | 透传给默认按钮 |
+| confirmLoading | `boolean` | `false` | OK 按钮显示 spinner 并禁用 |
+| closable | `boolean` | `true` | 显示右上角 × |
+| closeIcon | `ReactNode` | — | 自定义关闭图标 |
+| maskClosable | `boolean` | `true` | 点击遮罩关闭 |
+| escClosable | `boolean` | `true` | Esc 关闭 |
+| width | `number | string` | `440` | 宽度 |
+| destroyOnClose | `boolean` | `false` | 关闭时卸载子树 |
+| afterOpenChange | `(open: boolean) => void` | — | 动画结束后回调 |
+| zIndex | `number` | — | 覆盖遮罩 z-index |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/pagination.md

@@ -0,0 +1,82 @@
+# Pagination 分页
+
+> 分页控件,支持快速跳转与每页条数切换。
+
+## 导入
+
+```tsx
+import { Pagination } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Pagination total={85} page={page} onChange={setPage} />
+```
+
+### 快速跳转
+
+启用 showQuickJumper,输入页码按 Enter 跳转,超出范围会被夹紧。
+
+```tsx
+<Pagination
+  total={250}
+  page={jumpPage}
+  onChange={setJumpPage}
+  showQuickJumper
+/>
+```
+
+### 每页条数
+
+启用 showSizeChanger,切换条数会回到第 1 页并触发 onShowSizeChange + onChange(1)。
+
+```tsx
+<Pagination
+  total={320}
+  page={sizePage}
+  pageSize={pageSize}
+  onChange={setSizePage}
+  showSizeChanger
+  onShowSizeChange={(_cur, size) => setPageSize(size)}
+/>
+```
+
+### 跳转 + 条数 + 自定义选项
+
+同时启用两项,并通过 pageSizeOptions 自定义候选条数。
+
+```tsx
+<Pagination
+  total={999}
+  page={fullPage}
+  pageSize={fullPageSize}
+  onChange={setFullPage}
+  showQuickJumper
+  showSizeChanger
+  pageSizeOptions={[20, 50, 100, 200]}
+  onShowSizeChange={(_cur, size) => setFullPageSize(size)}
+/>
+```
+
+## API
+
+**Pagination**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| total \* | `number` | — | 数据总条数 |
+| pageSize | `number` | `10` | 每页条数 |
+| page / defaultPage | `number` | `1` | 受控/初始页码 |
+| onChange | `(page: number) => void` | — | 页码变化回调 |
+| siblings | `number` | `1` | 当前页两侧可见的页码数 |
+| showQuickJumper | `boolean` | `false` | 显示跳转输入框,按 Enter 跳转 |
+| showSizeChanger | `boolean` | `false` | 显示每页条数选择器,切换后回到第 1 页 |
+| pageSizeOptions | `number[]` | `[10, 20, 50, 100]` | 每页条数候选项 |
+| onShowSizeChange | `(current: number, size: number) => void` | — | 每页条数变更回调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/popover.md

@@ -0,0 +1,34 @@
+# Popover 气泡卡片
+
+> 比 Tooltip 更丰富,可承载交互内容。
+
+## 导入
+
+```tsx
+import { Popover } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Popover content={<>...</>}>
+  <Button>触发</Button>
+</Popover>
+```
+
+## API
+
+**Popover**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| content \* | `ReactNode` | — | 浮层内容 |
+| placement | `"top" | "bottom" | "left" | "right"` | `"bottom"` | 位置 |
+| trigger | `"click" | "hover"` | `"click"` | 触发方式 |
+| open / defaultOpen / onOpenChange | `—` | — | 受控显示 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/progress.md

@@ -0,0 +1,58 @@
+# Progress 进度
+
+> 条形进度 Progress 与环形进度 Ring。
+
+## 导入
+
+```tsx
+import { Progress, Ring } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 条形进度
+
+```tsx
+<Progress value={v} label="下载中" showValue />
+```
+
+### 尺寸
+
+```tsx
+<Progress size="sm" value={60} />
+<Progress value={60} />
+<Progress size="lg" value={60} />
+```
+
+### 环形进度
+
+```tsx
+<Ring value={65} />
+<Ring value={90} tone="success" size={80}><strong>90%</strong></Ring>
+```
+
+## API
+
+**Progress**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value \* | `number` | — | 0–max 之间 |
+| max | `number` | `100` | 最大值 |
+| tone | `"accent" | "success" | "warning" | "danger"` | `"accent"` | 色调 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
+| label | `ReactNode` | — | 顶部文案 |
+| showValue | `boolean` | `false` | 显示百分比 |
+
+
+**Ring**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value \* | `number` | — | 0–100 |
+| size | `number` | `72` | 直径 (px) |
+| tone | `"accent" | "success" | ...` | `"accent"` | 色调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/radio.md

@@ -0,0 +1,43 @@
+# Radio 单选
+
+> 在多个互斥选项中进行单项选择。
+
+## 导入
+
+```tsx
+import { RadioGroup } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<RadioGroup value={v} onChange={setV} options={[
+  { value: "daily", label: "每日" },
+  { value: "weekly", label: "每周" },
+]} />
+```
+
+### 水平排列
+
+direction='horizontal'。
+
+```tsx
+<RadioGroup direction="horizontal" ... />
+```
+
+## API
+
+**RadioGroup**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| options \* | `{ value, label, disabled? }[]` | — | 选项数组 |
+| value / defaultValue | `T` | — | 受控/初始 |
+| onChange | `(value: T) => void` | — | 变更 |
+| direction | `"vertical" | "horizontal"` | `"vertical"` | 方向 |
+
+
+---
+[← 回到索引](../llms.md)