@fangxinyan/lumina 0.1.6 → 0.2.1

package/docs/llms/accordion.md

@@ -0,0 +1,66 @@
+# Accordion 折叠面板
+
+> 纵向折叠面板。
+
+## 导入
+
+```tsx
+import { Accordion } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Accordion items={[{ key, title, content }]} />
+```
+
+### 多项展开
+
+multiple 允许同时展开多个面板。
+
+```tsx
+<Accordion multiple defaultActiveKeys={["1", "2"]} ... />
+```
+
+### 手风琴模式
+
+accordion={true} 同一时刻最多只展开一项;与 multiple 同时传入时 accordion 优先。
+
+```tsx
+<Accordion accordion defaultActiveKeys={["1"]} ... />
+```
+
+### 仅图标可点
+
+collapsible="icon" 将展开触发限制在右侧箭头图标上,标题区域不再响应。
+
+```tsx
+<Accordion collapsible="icon" ... />
+```
+
+### 禁用展开
+
+collapsible="disabled" 会禁用所有项的展开交互。
+
+```tsx
+<Accordion collapsible="disabled" defaultActiveKeys={["1"]} ... />
+```
+
+## API
+
+**Accordion**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| items \* | `AccordionItem[]` | — | 面板数据 |
+| multiple | `boolean` | `false` | 可同时展开多个 |
+| accordion | `boolean` | `false` | 手风琴模式(同一时刻最多一项) |
+| collapsible | `"header" | "icon" | "disabled"` | `"header"` | 展开触发区域 |
+| activeKeys / defaultActiveKeys | `string[]` | — | 受控/初始展开 |
+| onChange | `(keys: string[]) => void` | — | 展开变更 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/alert.md

@@ -0,0 +1,64 @@
+# Alert 警告提示
+
+> 页面中嵌入的警告/提示。
+
+## 导入
+
+```tsx
+import { Alert } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 四种语义
+
+```tsx
+<Alert tone="info" title="标题">内容</Alert>
+```
+
+### 无标题 / 可关闭
+
+```tsx
+<Alert tone="info" closable>仅一行的简短提示</Alert>
+```
+
+### 隐藏图标
+
+showIcon={false} 可隐藏左侧语义图标,文本更紧凑。
+
+```tsx
+<Alert tone="info" showIcon={false}>纯文本提示</Alert>
+```
+
+### 自定义操作区
+
+action 插槽可以放置按钮等操作元素,位于内容与关闭按钮之间。
+
+```tsx
+<Alert
+  tone="warning"
+  title="新版本可用"
+  action={<Button size="sm" variant="primary">立即更新</Button>}
+  closable
+>
+  v1.2.0 已发布。
+</Alert>
+```
+
+## API
+
+**Alert**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| tone | `"info" | "success" | "warning" | "danger"` | `"info"` | 语气 |
+| title | `ReactNode` | — | 标题 |
+| icon | `IconName` | — | 自定义图标 |
+| showIcon | `boolean` | `true` | 是否显示语义图标 |
+| action | `ReactNode` | — | 右侧操作区(如按钮) |
+| closable | `boolean` | `false` | 可关闭 |
+| onClose | `() => void` | — | 关闭回调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/avatar.md

@@ -0,0 +1,55 @@
+# Avatar 头像
+
+> 用图像、首字母代表用户或事物。
+
+## 导入
+
+```tsx
+import { Avatar } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+通过 alt 自动生成首字母。
+
+```tsx
+<Avatar alt="金伟" />
+<Avatar alt="陆" size="lg" />
+```
+
+### 方形头像
+
+shape="square" 使用圆角方形,尺寸变化时圆角跟随变化。
+
+```tsx
+<Avatar alt="金" shape="square" />
+<Avatar alt="陆" shape="square" size="lg" />
+```
+
+### 状态
+
+在右下角显示状态点。
+
+```tsx
+<Avatar alt="金" status="online" />
+<Avatar alt="陆" status="busy" />
+```
+
+## API
+
+**Avatar**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| src | `string` | — | 图片 URL |
+| alt | `string` | — | 替代文本/首字母来源 |
+| initials | `string` | — | 自定义首字母 |
+| size | `number | "sm" | "md" | "lg" | "xl"` | `"md"` | 尺寸 |
+| shape | `"circle" | "square"` | `"circle"` | 形状 |
+| status | `"online" | "busy" | "away" | "offline"` | — | 状态点 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/badge.md

@@ -0,0 +1,41 @@
+# Badge 徽标数
+
+> 右上角的小型计数或状态指示器。
+
+## 导入
+
+```tsx
+import { Badge } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 数字徽标
+
+```tsx
+<Badge count={3}><IconButton icon="bell" /></Badge>
+<Badge count={128} max={99}><IconButton icon="mail" /></Badge>
+```
+
+### 圆点
+
+dot 模式不显示数字,只是状态指示。
+
+```tsx
+<Badge dot><IconButton icon="user" /></Badge>
+```
+
+## API
+
+**Badge**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| count | `number` | — | 显示数字 |
+| dot | `boolean` | `false` | 圆点模式 |
+| max | `number` | `99` | 超过显示 max+ |
+| tone | `"neutral" | "accent" | ...` | `"danger"` | 色调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/button.md

@@ -0,0 +1,122 @@
+# Button 按钮
+
+> 标记一个操作命令,响应用户点击行为,触发相应业务逻辑。
+
+## 导入
+
+```tsx
+import { Button, IconButton, Segmented } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础按钮
+
+四种风格:主要、默认、幽灵、危险。
+
+```tsx
+<Button variant="primary">主按钮</Button>
+<Button>默认按钮</Button>
+<Button variant="ghost">幽灵按钮</Button>
+<Button variant="danger">删除</Button>
+```
+
+### 图标按钮
+
+icon 在前,trailingIcon 在后。
+
+```tsx
+<Button variant="primary" icon="sparkle">新建</Button>
+<Button icon="download">下载</Button>
+<Button trailingIcon="arrowRight">下一步</Button>
+```
+
+### 加载与禁用
+
+loading 期间禁用并显示 spinner。
+
+```tsx
+<Button loading={loading} variant="primary" onClick={...}>点我加载</Button>
+<Button disabled>已禁用</Button>
+```
+
+### 尺寸
+
+提供 sm / md / lg 三种高度。
+
+```tsx
+<Button size="sm">Small</Button>
+<Button>Medium</Button>
+<Button size="lg">Large</Button>
+```
+
+### 块级按钮
+
+block 让按钮撑满容器宽度,常用于底部主操作或表单提交。
+
+```tsx
+<Button block variant="primary" icon="send">提交表单</Button>
+<Button block>取消</Button>
+```
+
+### 纯图标按钮
+
+IconButton 是只含图标的方形按钮,常配合 tip 使用。
+
+```tsx
+<IconButton icon="heart" tip="收藏" />
+<IconButton icon="bell" tip="通知" />
+<IconButton icon="settings" tip="设置" />
+```
+
+### 分段控制器
+
+互斥多选项切换。
+
+```tsx
+<Segmented
+  options={[
+    { value: "grid", label: "网格" },
+    { value: "list", label: "列表" },
+    { value: "card", label: "卡片" },
+  ]}
+  defaultValue="grid"
+/>
+```
+
+## API
+
+**Button**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| variant | `"default" | "primary" | "ghost" | "danger"` | `"default"` | 按钮风格 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 按钮尺寸 |
+| icon | `IconName` | — | 前置图标 |
+| trailingIcon | `IconName` | — | 后置图标 |
+| loading | `boolean` | `false` | 加载态 |
+| block | `boolean` | `false` | 撑满父容器宽度 |
+| disabled | `boolean` | `false` | 禁用 |
+| onClick | `(e: MouseEvent) => void` | — | 点击回调 |
+
+
+**IconButton**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| icon \* | `IconName` | — | 图标名 |
+| tip | `string` | — | 悬浮提示 |
+| size / variant | `—` | — | 继承自 Button |
+
+
+**Segmented**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| options \* | `{ value, label, disabled? }[]` | — | 选项数组 |
+| value / defaultValue | `T` | — | 受控/初始选中值 |
+| onChange | `(value: T) => void` | — | 切换回调 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/calendar.md

@@ -0,0 +1,44 @@
+# Calendar 日历
+
+> 查看与选择日期。
+
+## 导入
+
+```tsx
+import { Calendar } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Calendar value={date} onChange={setDate} />
+```
+
+### 禁用日期
+
+通过 disabledDate 将周末标灰并禁止点击;与 min/max 可叠加使用。
+
+```tsx
+<Calendar
+  value={workDate}
+  onChange={setWorkDate}
+  disabledDate={(d) => d.getDay() === 0 || d.getDay() === 6}
+/>
+```
+
+## API
+
+**Calendar**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `Date` | — | 受控/初始日期 |
+| onChange | `(date: Date) => void` | — | 选择回调 |
+| min / max | `Date` | — | 可选范围 |
+| disabledDate | `(date: Date) => boolean` | — | 自定义禁用判断,返回 true 的日期不可选 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/card.md

@@ -0,0 +1,68 @@
+# Card 卡片
+
+> 信息分组容器,提供 raised / flat / sunken 三种视觉变体。
+
+## 导入
+
+```tsx
+import { Card, Panel } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 三种变体
+
+raised(默认凸起)、flat(扁平)、sunken(凹陷)。
+
+```tsx
+<Card>raised</Card>
+<Card variant="flat">flat</Card>
+<Card variant="sunken">sunken</Card>
+```
+
+### 悬浮抬起
+
+hoverable 在鼠标悬浮时轻微上移并加强阴影,适合可点击的卡片列表。
+
+```tsx
+<Card hoverable>可点击卡片</Card>
+```
+
+### Panel
+
+带标题、描述、操作区。
+
+```tsx
+<Panel title="月度营收" description="2026 年 4 月" actions={...}>
+  ¥ 12,480
+</Panel>
+```
+
+### Panel 带操作
+
+```tsx
+<Panel title="..." actions={<Button size="sm" icon="plus">邀请</Button>}>...</Panel>
+```
+
+## API
+
+**Card**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| variant | `"raised" | "flat" | "sunken"` | `"raised"` | 视觉变体 |
+| padding | `"none" | "sm" | "md" | "lg"` | `"md"` | 内边距 |
+| hoverable | `boolean` | `false` | 悬浮时抬起 |
+
+
+**Panel**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| title | `ReactNode` | — | 标题 |
+| description | `ReactNode` | — | 副标题 |
+| actions | `ReactNode` | — | 右上操作区 |
+
+
+---
+[← 回到索引](../llms.md)

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/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)