@fangxinyan/lumina 0.1.6 → 0.2.1

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)

package/docs/llms/switch.md

@@ -0,0 +1,60 @@
+# Switch 开关
+
+> 二元状态切换器。
+
+## 导入
+
+```tsx
+import { Switch } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<Switch checked={v} onChange={setV} label="开启通知" />
+```
+
+### 尺寸
+
+提供 sm / md 两档。
+
+```tsx
+<Switch size="sm" defaultChecked />
+<Switch defaultChecked />
+```
+
+### 禁用
+
+```tsx
+<Switch disabled label="不可用" />
+<Switch disabled defaultChecked label="禁用且开启" />
+```
+
+### 轨道内文本
+
+checkedChildren / unCheckedChildren 在轨道内显示简短文字(如 ON/OFF)。
+
+```tsx
+<Switch defaultChecked checkedChildren="ON" unCheckedChildren="OFF" />
+<Switch defaultChecked checkedChildren="1" unCheckedChildren="0" />
+```
+
+## API
+
+**Switch**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| checked / defaultChecked | `boolean` | — | 受控/初始 |
+| onChange | `(checked: boolean) => void` | — | 状态变更 |
+| label | `ReactNode` | — | 右侧文案 |
+| checkedChildren | `ReactNode` | — | 轨道内选中状态文本/图标 |
+| unCheckedChildren | `ReactNode` | — | 轨道内未选中状态文本/图标 |
+| size | `"sm" | "md"` | `"md"` | 尺寸 |
+| disabled | `boolean` | `false` | 禁用 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/table.md

@@ -0,0 +1,188 @@
+# Table 表格
+
+> 结构化数据展示。
+
+## 导入
+
+```tsx
+import { Table } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础表格
+
+```tsx
+<Table rowKey="id" columns={[...]} data={data} />
+```
+
+### 样式变体
+
+三种视觉变体:striped (条纹)、embossed (凸起)、cards (卡片行)。
+
+```tsx
+<Table variant="striped" ... />
+<Table variant="embossed" ... />
+<Table variant="cards" ... />
+```
+
+### 内置分页
+
+传入 pagination 即可自动分页;data 会按当前页切片。传 false 关闭。
+
+```tsx
+<Table
+  rowKey="id"
+  columns={[...]}
+  data={data}               // 24 rows
+  pagination={{ pageSize: 6 }}
+/>
+```
+
+### 固定表头 / 横向滚动
+
+scroll.y 固定表头并限制表体最大高度;scroll.x 设置内容最小宽度。
+
+```tsx
+<Table
+  scroll={{ y: 220, x: 900 }}
+  columns={[...]}
+  data={data}
+/>
+```
+
+### 行选择 (rowSelection)
+
+antd 风格的 rowSelection。表头多选框支持 indeterminate;可通过 getCheckboxProps 禁用指定行。
+
+```tsx
+<Table
+  rowSelection={{
+    selectedRowKeys,
+    onChange: (keys, rows) => setSelectedKeys(keys),
+    getCheckboxProps: (row) => ({ disabled: row.status === "离线" }),
+  }}
+  columns={[...]}
+  data={data}
+/>
+```
+
+### 行选择 · 单选
+
+设置 rowSelection.type = 'radio' 变成单选模式。
+
+```tsx
+<Table
+  rowSelection={{ type: "radio", defaultSelectedRowKeys: [1] }}
+  columns={[...]}
+  data={data}
+/>
+```
+
+### 可展开行
+
+点击左侧箭头按钮展开/收起,在行下方渲染自定义内容。
+
+```tsx
+<Table
+  expandable={{
+    expandedRowRender: (row) => <div>…详情…</div>,
+    rowExpandable: (row) => row.status !== "离线",
+  }}
+  columns={[...]}
+  data={data}
+/>
+```
+
+### 列筛选
+
+在列上配置 filters 即可在列头显示漏斗图标;点击弹出勾选面板,勾选后过滤数据。
+
+```tsx
+<Table
+  columns={[
+    {
+      key: "role", title: "部门", dataIndex: "role",
+      filters: [
+        { text: "设计", value: "设计" },
+        { text: "研发", value: "研发" },
+      ],
+      onFilter: (value, row) => row.role === value,
+    },
+  ]}
+  data={data}
+/>
+```
+
+## API
+
+**Table**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| columns \* | `TableColumn[]` | — | 列定义 |
+| data \* | `Row[]` | — | 数据数组 |
+| rowKey | `string | (row) => key` | — | 行键 |
+| variant | `"default" | "striped" | "embossed" | "cards"` | `"default"` | 视觉变体 |
+| pagination | `false | PaginationConfig` | — | 分页配置;false 关闭 |
+| scroll | `TableScrollConfig` | — | 滚动配置:{ x?, y? } |
+| rowSelection | `RowSelectionConfig` | — | 行选择配置 (antd 风格) |
+| expandable | `ExpandableConfig` | — | 可展开行配置 |
+| sortKey / sortDir / onSort | `—` | — | 受控排序 |
+| onRowClick | `(row, i) => void` | — | 点击行 |
+| selectable / selected / onSelect | `—` | — | 旧版多选 API (保留兼容,优先使用 rowSelection) |
+
+
+**TableColumn**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| key \* | `string` | — | 列唯一键 |
+| title \* | `ReactNode` | — | 表头 |
+| dataIndex | `keyof Row` | — | 取值字段 |
+| render | `(value, row, index) => ReactNode` | — | 单元格渲染 |
+| width | `number | string` | — | 列宽 |
+| align | `"left" | "center" | "right"` | — | 对齐 |
+| sortable | `boolean` | — | 是否可排序 |
+| filters | `{ text, value }[]` | — | 筛选项 |
+| onFilter | `(value, row) => boolean` | — | 筛选判定函数 |
+| defaultFilteredValue | `(string | number)[]` | — | 非受控初始筛选 |
+| filteredValue | `(string | number)[]` | — | 受控筛选值 |
+
+
+**PaginationConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| current | `number` | — | 当前页 (1-indexed),受控 |
+| defaultCurrent | `number` | `1` | 非受控初始页 |
+| pageSize | `number` | `10` | 每页条数 |
+| defaultPageSize | `number` | — | 非受控初始每页条数 |
+| total | `number` | — | 数据总量;默认为 data.length |
+| onChange | `(page, pageSize) => void` | — | 切页回调 |
+
+
+**RowSelectionConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| type | `"checkbox" | "radio"` | `"checkbox"` | 多选或单选 |
+| selectedRowKeys | `(string | number)[]` | — | 受控选中 key |
+| defaultSelectedRowKeys | `(string | number)[]` | — | 非受控初始选中 |
+| onChange | `(keys, rows) => void` | — | 选中变化 |
+| getCheckboxProps | `(row) => { disabled? }` | — | 每行勾选框属性 |
+
+
+**ExpandableConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| expandedRowKeys | `(string | number)[]` | — | 受控已展开 key |
+| defaultExpandedRowKeys | `(string | number)[]` | — | 非受控初始展开 |
+| onExpand | `(expanded, row) => void` | — | 展开/收起回调 |
+| expandedRowRender | `(row, i) => ReactNode` | — | 展开面板渲染 |
+| rowExpandable | `(row) => boolean` | — | 该行是否可展开 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/tablepro.md

@@ -0,0 +1,56 @@
+# Table Pro
+
+> 带工具栏 / 搜索 / 筛选 / 排序 / 多选 / 分页的全功能表格。
+
+## 导入
+
+```tsx
+import { TablePro } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 全功能
+
+工具栏 + 排序 + 新版 rowSelection + 内置分页。相比旧版,Table 自己切片 data,不必外部 slice。
+
+```tsx
+<TablePro
+  rowKey="id" data={filtered} columns={...}
+  rowSelection={{ selectedRowKeys, onChange }}
+  sortKey={sortKey} sortDir={sortDir} onSort={...}
+  pagination={{ pageSize: 4 }}
+  toolbar={<Input ... /> <Select ... />}
+  actions={<Button>新增</Button>}
+/>
+```
+
+### 带可展开行
+
+TablePro 直接透传 expandable 到 Table。
+
+```tsx
+<TablePro
+  title="成员详情"
+  expandable={{
+    expandedRowRender: (row) => <div>...展开内容...</div>,
+  }}
+  ...
+/>
+```
+
+## API
+
+**TablePro**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| ... | `TableProps` | — | 继承自 Table 全部 props (包括新的 pagination / scroll / rowSelection / expandable / filters) |
+| toolbar | `ReactNode` | — | 工具栏内容 |
+| actions | `ReactNode` | — | 工具栏右侧操作 |
+| footer | `ReactNode` | — | 底部 (可选,传了会渲染在分页下方) |
+| title | `ReactNode` | — | 工具栏标题 |
+
+
+---
+[← 回到索引](../llms.md)