@fangxinyan/lumina 0.2.0 → 0.3.0

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)

package/docs/llms/select.md

@@ -0,0 +1,99 @@
+# Select 下拉选择
+
+> 下拉选择,支持单/多选、搜索、分组、加载态。
+
+## 导入
+
+```tsx
+import { Select } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 单选
+
+```tsx
+<Select value={lang} onChange={setLang} options={[
+  { value: "zh", label: "简体中文" },
+  { value: "en", label: "English" },
+]} />
+```
+
+### 多选
+
+multiple + Tag 形式呈现已选项。
+
+```tsx
+<Select multiple clearable value={tags} onChange={setTags} options={...} />
+```
+
+### 搜索过滤
+
+searchable + clearable + 选项 icon/description。
+
+```tsx
+<Select searchable clearable
+  options={[{ value, label, icon, description }]}
+/>
+```
+
+### 分组
+
+options 接受 { label, options } 表示分组。
+
+```tsx
+options={[
+  { label: "前端", options: [...] },
+  { label: "后端", options: [...] },
+]}
+```
+
+### 加载态
+
+loading 时显示 spinner,emptyContent 自定义空态。
+
+```tsx
+<Select searchable loading={loading} options={asyncOpts} />
+```
+
+### 尺寸 / 状态
+
+```tsx
+<Select size="sm" /> <Select /> <Select size="lg" />
+<Select invalid /> <Select disabled />
+```
+
+## API
+
+**Select**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| options \* | `SelectItem<T>[]` | — | 选项,可含 { label, options } 分组 |
+| value / defaultValue | `T | T[]` | — | 受控/初始 |
+| onChange | `(value) => void` | — | 变更 |
+| multiple | `boolean` | `false` | 多选 |
+| maxTagCount | `number` | — | 多选时显示的标签数(超出折叠 +N) |
+| searchable | `boolean` | `false` | 可搜索 |
+| filterOption | `(input, option) => boolean` | — | 自定义过滤 |
+| clearable | `boolean` | `false` | 可清除 |
+| loading | `boolean` | `false` | 加载态 |
+| emptyContent | `ReactNode` | — | 空态文案 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
+| invalid | `boolean` | `false` | 错误态 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+**SelectOption**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value \* | `T` | — | 值 |
+| label | `ReactNode` | — | 显示 |
+| icon | `IconName` | — | 前置图标 |
+| description | `ReactNode` | — | 次要描述 |
+| disabled | `boolean` | `false` | 禁用项 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/sidebar.md

@@ -0,0 +1,43 @@
+# Sidebar 侧边栏
+
+> 应用主导航,沿屏幕左侧垂直排列。
+
+## 导入
+
+```tsx
+import { Sidebar } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Sidebar items={[{ key, label, icon, badge }]} activeKey={active} onSelect={setActive} />
+```
+
+## API
+
+**Sidebar**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| items \* | `SidebarItem[]` | — | 导航项 |
+| activeKey | `string` | — | 当前激活项 |
+| onSelect | `(key: string) => void` | — | 选择回调 |
+| collapsed | `boolean` | `false` | 折叠为图标 |
+| header / footer | `ReactNode` | — | 头/尾内容 |
+
+
+**SidebarItem**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `string` | — | 唯一键 |
+| label | `ReactNode` | — | 文案 |
+| icon | `ReactNode` | — | 前置图标 |
+| badge | `ReactNode` | — | 尾部徽标 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/skeleton.md

@@ -0,0 +1,88 @@
+# Skeleton 骨架屏
+
+> 数据加载前展示页面结构轮廓。
+
+## 导入
+
+```tsx
+import { Skeleton } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Skeleton height={16} width="40%" />
+<Skeleton height={12} />
+<Skeleton height={12} width="80%" />
+```
+
+### 手动组合:头像 + 文本
+
+使用原语 Skeleton 手动拼装 — 更灵活但需要自己写布局。
+
+```tsx
+<Skeleton circle height={48} width={48} />
+<Skeleton height={12} width="50%" />
+```
+
+### 组合模式 (avatar + title + paragraph)
+
+设置 avatar / title / paragraph 任一即切换到组合模式,自动拼装布局。
+
+```tsx
+<Skeleton avatar title paragraph />
+```
+
+### 组合:自定义头像形状、段落行数
+
+```tsx
+<Skeleton
+  avatar={{ shape: "square", size: "lg" }}
+  title={{ width: "30%" }}
+  paragraph={{ rows: 4, width: ["100%", "90%", "70%", "40%"] }}
+/>
+```
+
+### 组合:仅 title + paragraph
+
+关闭 avatar 只渲染标题与段落,其余布局自动调整。
+
+```tsx
+<Skeleton title paragraph={{ rows: 2 }} />
+```
+
+### 动画
+
+wave 是闪光流动,pulse 是透明度脉动,none 是静态占位。
+
+```tsx
+<Skeleton animation="wave" />
+<Skeleton animation="pulse" />
+<Skeleton animation="none" />
+```
+
+## API
+
+**Skeleton (原语模式)**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| width | `number | string` | `"100%"` | 宽度 |
+| height | `number | string` | `16` | 高度 |
+| circle | `boolean` | `false` | 圆形 |
+| animation | `"wave" | "pulse" | "none"` | `"wave"` | 动画 |
+
+
+**Skeleton (组合模式)**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| avatar | `boolean | { shape?: "circle" | "square"; size?: "sm" | "md" | "lg" }` | `false` | 左侧头像骨架。为对象时可定制 shape / size |
+| title | `boolean | { width?: number | string }` | `true (composite)` | 标题行骨架。组合模式下默认 true |
+| paragraph | `boolean | { rows?: number; width?: (number | string)[] }` | `{ rows: 3 }` | 段落行骨架。可指定 rows 与每行宽度(最后一行默认 60%) |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/slider.md

@@ -0,0 +1,72 @@
+# Slider 滑块
+
+> 在连续数值区间内取值。
+
+## 导入
+
+```tsx
+import { Slider } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Slider value={v} onChange={setV} showValue />
+```
+
+### 步进 / 范围
+
+min/max/step 控制取值范围与步进。
+
+```tsx
+<Slider min={0} max={10} step={1} defaultValue={5} showValue />
+```
+
+### 色调
+
+```tsx
+<Slider tone="success" defaultValue={70} />
+<Slider tone="warning" defaultValue={50} />
+<Slider tone="danger" defaultValue={88} />
+```
+
+### 双滑块区间
+
+range 模式下 value / onChange 采用 [min, max] 元组。
+
+```tsx
+const [v, setV] = useState<[number, number]>([20, 70]);
+<Slider range value={v} onChange={setV} showValue />
+```
+
+### 刻度标记
+
+marks 提供可点击刻度,点击即可跳到该值。
+
+```tsx
+<Slider
+  defaultValue={37}
+  marks={{ 0: "0°C", 26: "冷", 37: "正常", 100: "100°C" }}
+/>
+```
+
+## API
+
+**Slider**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `number | [number, number]` | — | 受控/初始;range 模式下为 [number, number] |
+| onChange | `(value) => void` | — | 变更回调,range 模式返回元组 |
+| min / max / step | `number` | — | 区间与步进 |
+| range | `boolean` | `false` | 是否为双滑块区间模式 |
+| marks | `Record<number, ReactNode>` | — | 刻度,点击可跳到对应值 |
+| tone | `"accent" | "success" | "warning" | "danger"` | `"accent"` | 色调 |
+| showValue | `boolean` | `false` | 显示数值 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/spinner.md

@@ -0,0 +1,58 @@
+# Spinner 加载
+
+> 表示任务正在进行,提示用户等待。
+
+## 导入
+
+```tsx
+import { Spinner } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Spinner />
+<Spinner size={28} />
+<Spinner size={40} />
+```
+
+### 色调
+
+```tsx
+<Spinner tone="accent" />
+<Spinner tone="success" />
+<Spinner tone="warning" />
+<Spinner tone="danger" />
+```
+
+### Dots 变体
+
+```tsx
+<Spinner variant="dots" />
+<Spinner variant="dots" size={24} />
+<Spinner variant="dots" size={32} />
+```
+
+### 带文案
+
+```tsx
+<Spinner label="加载中…" />
+<Spinner variant="dots" tone="accent" label="正在同步" />
+```
+
+## API
+
+**Spinner**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| size | `number` | `20` | 尺寸 (px) |
+| tone | `"accent" | "success" | "warning" | "danger" | "current"` | `"accent"` | 色调 |
+| variant | `"ring" | "dots"` | `"ring"` | 样式 |
+| label | `ReactNode` | — | 文案 |
+
+
+---
+[← 回到索引](../llms.md)