lingee-ui 0.0.6 → 0.0.8

package/skill/references/components/tag.md

@@ -0,0 +1,59 @@
+# Tag 标签
+
+用于标记和分类的小型标签元素。
+
+- 导入：`import { Tag } from "lingee-ui";`
+- 可用类型：`TagProps`, `TagPresetColor`, `TagSize`, `TagShape`
+
+## 最小示例
+
+```tsx
+import { Tag } from "lingee-ui";
+
+export default function BasicDemo() {
+  return (
+    <div style={{ display: "flex", gap: 8 }}>
+      <Tag>Default</Tag>
+      <Tag color="primary">Primary</Tag>
+    </div>
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `color` | 标签颜色 | `"info" \| "primary" \| "success" \| "warning" \| "danger" \| "amber" \| "yellow" \| "cyan" \| "purple" \| string` | `"info"` |
+| `variant` | 视觉变体 | `"tint" \| "gradient" \| "glow"` | `"tint"` |
+| `size` | 标签尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `shape` | 圆角形状（仅 `variant="tint"` 生效） | `"pill" \| "rounded"` | `"pill"` |
+| `icon` | 前缀图标 | `ReactNode` | - |
+| `background` | 自定义背景 | `string` | - |
+| `closable` | 是否可关闭 | `boolean` | `false` |
+| `onClose` | 关闭回调 | `(e: MouseEvent) => void` | - |
+| `children` | 子内容 | `ReactNode` | - |
+
+### 变体说明
+
+| 变体 | 圆角 | 背景 | 装饰 | 适用场景 |
+|------|------|------|------|----------|
+| `tint` | 由 `shape` 决定 | 同色 8% 纯色浅底 | - | 通用标记、分类 |
+| `gradient` | 8px | 同色 12% → 3% 斜向渐变 | - | 提示类徽标 |
+| `glow` | 12px | 同色 8/12% → 28% 渐变 | 两层模糊光斑 | 等级类徽标 |
+
+`glow` 的 `purple` 使用 128.7° 斜向渐变，`yellow` / `cyan` 使用自上而下的纵向渐变。
+
+### 样式变量
+
+以下 CSS 变量可在消费方覆盖，用于微调间距、图标尺寸与光斑配色：
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `--_tag-gap` | 图标与文字间距 | `2px`（gradient `4px`、glow `10px`） |
+| `--_tag-icon-size` | 图标尺寸 | `14px`（`size="lg"` 与 gradient 的 `danger` 为 `16px`） |
+| `--_tag-font-weight` | 字重 | `400`（glow 为 `500`） |
+| `--_tag-gradient-from` | 渐变起始色（gradient / glow） | 按 `color` 取同色 12%（glow 的 `purple` 为 8%） |
+| `--_tag-gradient-to` | 渐变结束色（gradient / glow） | gradient 取同色 3%，glow 取 28% |
+| `--_tag-glow-primary` | 底层光斑色（仅 glow） | 按 `color` 取对应装饰色 |
+| `--_tag-glow-secondary` | 高光层光斑色（仅 glow） | `rgba(255, 255, 255, 0.64)`（`purple` 为 `0.59`） |

package/skill/references/components/textarea.md

@@ -0,0 +1,30 @@
+# Textarea 多行文本框
+
+多行纯文本编辑控件，支持字数统计和自动高度。
+
+- 导入：`import { Textarea } from "lingee-ui";`
+- 可用类型：`TextareaProps`
+
+## 最小示例
+
+```tsx
+import { Textarea } from "lingee-ui";
+
+export default function BasicDemo() {
+  return <Textarea placeholder="Please enter content..." rows={4} />;
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `placeholder` | 占位文本 | `string` | - |
+| `rows` | 显示行数 | `number` | - |
+| `maxLength` | 最大字符数 | `number` | - |
+| `showCount` | 是否显示字数统计 | `boolean` | `false` |
+| `autoSize` | 自适应高度 | `boolean \| { minRows: number; maxRows: number }` | - |
+| `disabled` | 是否禁用 | `boolean` | `false` |
+| `error` | 是否为错误状态 | `boolean` | `false` |
+| `value` | 受控值 | `string` | - |
+| `onChange` | 值变化回调 | `(e: ChangeEvent) => void` | - |

package/skill/references/components/time-picker.md

@@ -0,0 +1,49 @@
+# TimePicker 时间选择器
+
+用于选择时间的输入组件。
+
+- 导入：`import { TimePicker } from "lingee-ui";`
+- 可用类型：`TimePickerProps`, `TimePickerSize`, `TimeValue`
+
+## 最小示例
+
+```tsx
+import { useState } from "react";
+import { TimePicker } from "lingee-ui";
+
+export default function BasicDemo() {
+  const [value, setValue] = useState(null);
+
+  return (
+    <div style={{ width: 292 }}>
+      {/* 不传 placeholder，展示组件跟随 Provider 语言的默认占位符 */}
+      <TimePicker value={value} onChange={(v) => setValue(v)} />
+    </div>
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `value` | 当前时间（受控） | `TimeValue \| null` | - |
+| `defaultValue` | 默认时间（非受控） | `TimeValue` | - |
+| `onChange` | 时间变化回调 | `(time: TimeValue \| null) => void` | - |
+| `placeholder` | 占位文本 | `string` | `"时:分"` |
+| `disabled` | 是否禁用 | `boolean` | `false` |
+| `showSeconds` | 是否显示秒 | `boolean` | `false` |
+| `size` | 尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `error` | 是否显示错误状态 | `boolean` | `false` |
+| `errorMessage` | 错误提示信息 | `string` | - |
+| `allowClear` | 是否允许清除 | `boolean` | `true` |
+
+### TimeValue
+
+```ts
+interface TimeValue {
+  hour: number;
+  minute: number;
+  second?: number;
+}
+```

package/skill/references/components/toast.md

@@ -0,0 +1,47 @@
+# Toast 全局提示
+
+命令式全局提示组件，用于操作反馈。
+
+- 导入：`import { toast } from "lingee-ui";`
+- 按需导入：`import { toast } from "lingee-ui/toast";`
+- 可用类型：`ToastConfig`, `ToastGlobalConfig`, `ToastType`
+
+## 最小示例
+
+```tsx
+import { toast, Button } from "lingee-ui";
+
+export default function BasicDemo() {
+  return (
+    <div style={{ display: "flex", gap: 12 }}>
+      <Button onClick={() => toast.success("Operation succeeded!")}>Success</Button>
+      <Button onClick={() => toast.error("Something went wrong, please retry")}>Error</Button>
+      <Button onClick={() => toast.warning("Heads up, this is a warning")}>Warning</Button>
+      <Button onClick={() => toast.info("This is an informational message")}>Info</Button>
+    </div>
+  );
+}
+```
+
+## API
+
+Toast 通过命令式方法调用，无需手动渲染组件。
+
+### 方法
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `toast.success(message)` | 成功提示 | `string \| ToastOptions` |
+| `toast.error(message)` | 错误提示 | `string \| ToastOptions` |
+| `toast.warning(message)` | 警告提示 | `string \| ToastOptions` |
+| `toast.info(message)` | 信息提示 | `string \| ToastOptions` |
+| `toast.destroy()` | 销毁所有消息 | - |
+
+### ToastOptions
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `content` | 提示内容 | `string` | - |
+| `duration` | 自动关闭延时（ms），0 为不关闭 | `number` | `3000` |
+| `closable` | 是否可手动关闭 | `boolean` | `false` |
+| `key` | 唯一标识，相同 key 会更新内容 | `string` | - |

package/skill/references/components/tooltip.md

@@ -0,0 +1,33 @@
+# Tooltip 文字提示
+
+鼠标悬停时显示的简短提示信息。
+
+- 导入：`import { Tooltip } from "lingee-ui";`
+- 按需导入：`import { Tooltip } from "lingee-ui/tooltip";`
+- 可用类型：`TooltipProps`, `TooltipPlacement`
+
+## 最小示例
+
+```tsx
+import { Tooltip, Button } from "lingee-ui";
+
+export default function BasicDemo() {
+  return (
+    <Tooltip content="This is a tooltip.">
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `content` | 提示内容 | `ReactNode` | - |
+| `placement` | 弹出方向 | `"top" \| "bottom" \| "left" \| "right" \| "top-start" \| "top-end" \| ...` | `"top"` |
+| `delayDuration` | hover 延迟展示时间（ms） | `number` | `200` |
+| `arrow` | 是否显示箭头 | `boolean` | `true` |
+| `maxWidth` | 浮层最大宽度（px） | `number` | `280` |
+| `scrollable` | 内容超出视口可用高度时限高并滚动 | `boolean` | `true` |
+| `children` | 触发元素 | `ReactNode` | - |

package/skill/references/components/tree.md

@@ -0,0 +1,118 @@
+# Tree 树形控件
+
+用于展示层级结构数据，支持勾选、拖拽排序、异步加载与虚拟滚动。
+
+- 导入：`import { Tree } from "lingee-ui";`
+- 按需导入：`import { Tree } from "lingee-ui/tree";`
+- 可用类型：`TreeProps`, `TreeNodeData`, `TreeNodeState`, `TreeSize`, `TreeIndentGuide`, `TreeFieldNames`, `TreeCheckInfo`, `TreeSelectInfo`, `TreeExpandInfo`, `TreeDropInfo`, `TreeAllowDropOptions`, `TreeExpandAction`
+
+## 最小示例
+
+```tsx
+import { Tree } from "lingee-ui";
+import type { TreeNodeData } from "lingee-ui";
+
+const treeData: TreeNodeData[] = [
+  {
+    key: "finance",
+    title: "Finance Analysis",
+    children: [
+      { key: "finance-annual", title: "Annual Report" },
+      { key: "finance-budget", title: "Budget Execution" },
+      { key: "finance-cost", title: "Cost Breakdown" },
+    ],
+  },
+  {
+    key: "sales",
+    title: "Sales Analysis",
+    children: [
+      { key: "sales-review", title: "Performance Review" },
+      {
+        key: "sales-region",
+        title: "Regional Breakdown",
+        children: [
+          { key: "sales-region-north", title: "North Region" },
+          { key: "sales-region-south", title: "South Region" },
+        ],
+      },
+    ],
+  },
+  { key: "customer", title: "Customer Satisfaction" },
+];
+
+export default function BasicDemo() {
+  return (
+    <div style={{ width: 280 }}>
+      <Tree
+        treeData={treeData}
+        defaultExpandedKeys={["finance", "sales"]}
+        defaultSelectedKeys={["finance-budget"]}
+      />
+    </div>
+  );
+}
+```
+
+## API
+
+### Tree
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `treeData` | 节点数据 | `TreeNodeData[]` | - |
+| `fieldNames` | 字段名映射，用于适配非标准数据结构 | `{ key?, title?, children? }` | - |
+| `size` | 行高尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `indentGuide` | 缩进引导线形态 | `"none" \| "line"` | `"line"` |
+| `expandedKeys` | 展开的节点 key（受控） | `Key[]` | - |
+| `defaultExpandedKeys` | 默认展开的节点 key | `Key[]` | - |
+| `defaultExpandAll` | 默认展开全部节点 | `boolean` | `false` |
+| `autoExpandParent` | 展开子节点时自动展开其父节点 | `boolean` | `false` |
+| `expandAction` | 触发展开的交互方式 | `false \| "click" \| "doubleClick"` | `"click"` |
+| `onExpand` | 展开状态变化回调 | `(keys, info) => void` | - |
+| `selectable` | 是否可选中 | `boolean` | `true` |
+| `multiple` | 是否支持多选 | `boolean` | `false` |
+| `selectedKeys` | 选中的节点 key（受控） | `Key[]` | - |
+| `defaultSelectedKeys` | 默认选中的节点 key | `Key[]` | - |
+| `onSelect` | 选中状态变化回调 | `(keys, info) => void` | - |
+| `checkable` | 是否显示勾选框 | `boolean` | `false` |
+| `checkStrictly` | 父子节点勾选状态不再联动 | `boolean` | `false` |
+| `checkedKeys` | 勾选的节点 key（受控） | `Key[] \| { checked, halfChecked }` | - |
+| `defaultCheckedKeys` | 默认勾选的节点 key | `Key[]` | - |
+| `onCheck` | 勾选状态变化回调 | `(keys, info) => void` | - |
+| `showIcon` | 是否显示节点图标 | `boolean` | `false` |
+| `icon` | 全局节点图标，函数形式可按展开态切换 | `ReactNode \| ((node, state: { expanded, isLeaf }) => ReactNode)` | - |
+| `switcherIcon` | 自定义展开箭头，函数形式可按展开态切换 | `ReactNode \| ((state: { expanded, isLeaf }) => ReactNode)` | - |
+| `titleRender` | 自定义单行内容 | `(node) => ReactNode` | - |
+| `loadData` | 异步加载子节点 | `(node) => Promise<unknown>` | - |
+| `loadedKeys` | 已加载完成的节点 key | `Key[]` | - |
+| `draggable` | 是否可拖拽排序 | `boolean \| ((node) => boolean)` | `false` |
+| `allowDrop` | 校验能否放置到目标位置 | `(options) => boolean` | - |
+| `onDrop` | 拖拽放置回调 | `(info) => void` | - |
+| `height` | 可视区高度，设置后启用虚拟滚动 | `number` | - |
+| `itemHeight` | 虚拟滚动的单项高度 | `number` | 按 `size` 推导 |
+| `virtual` | 关闭虚拟滚动 | `boolean` | - |
+| `disabled` | 整体禁用 | `boolean` | `false` |
+| `loading` | 加载状态，展示遮罩 | `boolean` | `false` |
+| `empty` | 无数据时的展示内容 | `ReactNode` | `<Empty />` |
+| `animated` | 展开 / 折叠是否启用高度过渡动效（虚拟滚动下无效） | `boolean` | `true` |
+| `onRightClick` | 节点右键回调 | `(info) => void` | - |
+
+### TreeNodeData
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| `key` | 节点唯一标识 | `Key` |
+| `title` | 节点标题 | `ReactNode` |
+| `children` | 子节点 | `TreeNodeData[]` |
+| `icon` | 节点前置图标，覆盖 Tree 上的全局 `icon` | `ReactNode` |
+| `disabled` | 是否禁用 | `boolean` |
+| `disableCheckbox` | 是否禁用勾选框 | `boolean` |
+| `checkable` | 是否可勾选 | `boolean` |
+| `isLeaf` | 是否强制视作叶子节点 | `boolean` |
+| `selectable` | 是否可选中 | `boolean` |
+
+## 注意事项
+
+- 组件不持有 `treeData`，异步加载与拖拽排序均需消费方自行更新数据
+- 节点内部结构由底层 `@rc-component/tree` 生成，类名为 `lg-tree-treenode`、`lg-tree-switcher` 等单横线形式，覆盖样式时需按此书写
+- 虚拟滚动开启后行高必须固定，`titleRender` 中不要渲染高度不定的内容

package/skill/references/components/upload.md

@@ -0,0 +1,41 @@
+# Upload 上传
+
+文件上传组件，支持点击和拖拽上传。
+
+- 导入：`import { Upload } from "lingee-ui";`
+- 可用类型：`UploadProps`, `UploadFile`, `UploadFileStatus`, `CustomRequestOptions`, `CustomRequestReturn`, `RejectReason`, `FileItemActions`
+
+## 最小示例
+
+```tsx
+import { Upload, Button } from "lingee-ui";
+
+export default function BasicDemo() {
+  return (
+    <Upload
+      onChange={(fileList) => console.log("File list:", fileList)}
+    >
+      <Button>Click to upload</Button>
+    </Upload>
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `accept` | 接受的文件类型 | `string` | - |
+| `multiple` | 是否允许多选 | `boolean` | `false` |
+| `disabled` | 是否禁用 | `boolean` | `false` |
+| `drag` | 是否启用拖拽上传 | `boolean` | `false` |
+| `maxCount` | 最大文件数量 | `number` | - |
+| `maxSize` | 单文件最大大小（字节） | `number` | - |
+| `fileList` | 文件列表（受控） | `UploadFile[]` | - |
+| `showFileList` | 是否显示文件列表 | `boolean` | `true` |
+| `onChange` | 文件列表变化回调 | `(fileList: UploadFile[]) => void` | - |
+| `onReject` | 校验未通过回调 | `(files: File[], reason: "size" \| "type" \| "count") => void` | - |
+| `customRequest` | 自定义上传请求。省略则为仅收集模式 | `(options: CustomRequestOptions) => { abort }` | - |
+| `pasteable` | 是否支持粘贴文件（如截图） | `boolean` | `false` |
+| `validateAccept` | 是否按 `accept` 校验类型，拦住拖拽与粘贴 | `boolean` | `false` |
+| `children` | 触发区域 | `ReactNode` | - |