@fangxinyan/lumina 0.2.0 → 0.3.0

package/docs/llms/splitter.md

@@ -0,0 +1,63 @@
+# Splitter 可拖拽分栏
+
+> 两栏之间可拖拽的分隔条,支持横向、纵向与嵌套。
+
+## 示例
+
+### 水平分栏
+
+```tsx
+<Splitter defaultSize={200} min={120} max={360}>
+  <SidePanel />
+  <MainPanel />
+</Splitter>
+```
+
+### 垂直分栏
+
+direction="vertical" 让面板上下排列,分隔条变成横条。
+
+```tsx
+<Splitter direction="vertical" defaultSize={120} min={60}>...</Splitter>
+```
+
+### 嵌套分栏
+
+组合使用两个 Splitter 可以搭出 IDE 风格的三区布局。
+
+```tsx
+<Splitter defaultSize={180}>
+  <SideNav />
+  <Splitter direction="vertical" defaultSize={180}>
+    <Editor />
+    <Terminal />
+  </Splitter>
+</Splitter>
+```
+
+### 受控模式
+
+通过 size / onResize 可以持久化宽度或与其他状态联动。
+
+```tsx
+const [w, setW] = useState(220);
+<Splitter size={w} onResize={setW}>...</Splitter>
+```
+
+## API
+
+**Splitter**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| direction | `"horizontal" | "vertical"` | `"horizontal"` | 布局方向 |
+| defaultSize | `number` | `240` | 非受控初始宽/高 (px) |
+| size / onResize | `number / (n: number) => void` | — | 受控宽/高 |
+| onResizeEnd | `(n: number) => void` | — | 拖动结束回调 |
+| min / max | `number` | `80 / Infinity` | 尺寸限制 (px) |
+| step | `number` | `16` | 方向键步长 (px) |
+| children \* | `[ReactNode, ReactNode]` | — | 必须恰好两个子节点 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/statusbar.md

@@ -0,0 +1,53 @@
+# StatusBar 状态栏
+
+> 窗口底部状态栏,展示分支、编码、行列等应用元信息。
+
+## 示例
+
+### 基础
+
+```tsx
+<StatusBar
+  left={<StatusBar.Item icon={<Icon name="check" size={12} />} tone="success">Ready</StatusBar.Item>}
+  right={<StatusBar.Item tone="muted">UTF-8</StatusBar.Item>}
+/>
+```
+
+### 可点击项
+
+为 Item 提供 onClick 会渲染成按钮,支持悬停高亮。
+
+```tsx
+<StatusBar.Item onClick={...}>TypeScript</StatusBar.Item>
+```
+
+### 语义色
+
+tone 控制文字颜色:default / muted / accent / success / warning / danger。
+
+```tsx
+<StatusBar.Item tone="danger">3 errors</StatusBar.Item>
+```
+
+## API
+
+**StatusBar**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| left | `ReactNode` | — | 左侧槽位 |
+| center | `ReactNode` | — | 中部槽位(绝对居中) |
+| right | `ReactNode` | — | 右侧槽位 |
+
+
+**StatusBar.Item**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| icon | `ReactNode` | — | 前置图标 |
+| tone | `"default" | "muted" | "accent" | "success" | "warning" | "danger"` | `"default"` | 语义色 |
+| onClick | `(e) => void` | — | 点击回调(提供时渲染为 button) |
+
+
+---
+[← 回到索引](../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)

package/docs/llms/tabs.md

@@ -0,0 +1,50 @@
+# Tabs 选项卡
+
+> 同一层级的内容分组,通过标签切换。
+
+## 导入
+
+```tsx
+import { Tabs } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础
+
+```tsx
+<Tabs items={[
+  { key: "general", label: "通用", content: <>...</> },
+  { key: "account", label: "账户", content: <>...</> },
+]} />
+```
+
+### 下划线变体
+
+```tsx
+<Tabs variant="line" items={[...]} />
+```
+
+### 居中对齐
+
+centered 让标签条在容器中水平居中。
+
+```tsx
+<Tabs centered items={[...]} />
+```
+
+## API
+
+**Tabs**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| items \* | `TabItem[]` | — | 标签数据 |
+| activeKey / defaultActiveKey | `string` | — | 受控/初始激活 |
+| onChange | `(key: string) => void` | — | 切换 |
+| variant | `"line" | "pill" | "segmented"` | `"line"` | 样式 |
+| centered | `boolean` | `false` | 标签条居中对齐 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/tag.md

@@ -0,0 +1,77 @@
+# Tag 标签
+
+> 标记关键词、状态或分类。
+
+## 导入
+
+```tsx
+import { Tag } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 语气
+
+```tsx
+<Tag>Default</Tag>
+<Tag tone="accent">Accent</Tag>
+<Tag tone="success">Success</Tag>
+```
+
+### 实心
+
+```tsx
+<Tag tone="accent" solid>Solid</Tag>
+```
+
+### 圆点状态
+
+dot 渲染前置色块。
+
+```tsx
+<Tag tone="success" dot>在线</Tag>
+```
+
+### 前置图标
+
+icon 使用内置 Icon 组件,颜色随语气自动适配。
+
+```tsx
+<Tag tone="success" icon="check2">已完成</Tag>
+<Tag tone="info" icon="star">推荐</Tag>
+```
+
+### 无边框
+
+bordered={false} 去除 flat 阴影,只保留文本色。
+
+```tsx
+<Tag bordered={false}>Default</Tag>
+<Tag tone="accent" bordered={false}>Accent</Tag>
+```
+
+### 可移除
+
+removable + onRemove 实现关闭按钮。
+
+```tsx
+<Tag removable onRemove={() => remove(t.id)}>{t.label}</Tag>
+```
+
+## API
+
+**Tag**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| tone | `"neutral" | "accent" | "info" | "success" | "warning" | "danger"` | `"neutral"` | 色调 |
+| solid | `boolean` | `false` | 实心填充 |
+| dot | `boolean` | `false` | 前置圆点 |
+| icon | `IconName` | — | 前置图标 |
+| bordered | `boolean` | `true` | 是否显示外框 flat 阴影 |
+| removable | `boolean` | `false` | 显示 × |
+| onRemove | `() => void` | — | 关闭回调 |
+
+
+---
+[← 回到索引](../llms.md)