@fangxinyan/lumina 0.7.0 → 0.9.0

package/docs/llms/select.md

@@ -27,6 +27,23 @@ multiple + Tag 形式呈现已选项。
 <Select multiple clearable value={tags} onChange={setTags} options={...} />
 ```
 
+### 数量上限 / 分类限选
+
+maxCount 限制总数；getOptionDisabled 可读取当前选择，实现“一类最多选一个”。
+
+```tsx
+<Select
+  multiple
+  maxCount={2}
+  value={values}
+  onChange={setValues}
+  getOptionDisabled={(option, selectedValues) =>
+    hasOtherSelectionInCategory(option, selectedValues)
+  }
+  options={groupedOptions}
+/>
+```
+
 ### 搜索过滤
 
 searchable + clearable + 选项 icon/description。icon 支持 IconName 或 ReactNode。
@@ -70,6 +87,26 @@ optionRender 承载多行菜单内容；selectedRender 提供适合固定高度
 />
 ```
 
+### 置顶分组与额外操作
+
+分组设置 pinned 后会稳定提升到菜单顶部；optionExtraRender 提供不会触发选中的独立尾部区域。收藏仅是业务侧示例。
+
+```tsx
+const groups = [
+  { label: "其他服务", options: otherOptions },
+  { label: "已收藏", pinned: true, options: favoriteOptions },
+];
+
+<Select
+  value={service}
+  onChange={setService}
+  options={groups}
+  optionExtraRender={(option) => (
+    <IconButton icon={isFavorite(option) ? "starFilled" : "star"} />
+  )}
+/>
+```
+
 ### 分组
 
 options 接受 { label, options } 表示分组。
@@ -108,6 +145,8 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | placeholder | `string` | `"请选择…"` | 空选择时的提示文本 |
 | multiple | `boolean` | `false` | 多选 |
 | maxTagCount | `number` | — | 多选时显示的标签数(超出折叠 +N) |
+| maxCount | `number` | — | 多选允许的最大选择数；达到上限后禁用未选项 |
+| getOptionDisabled | `(option, selectedValues) => boolean` | — | 基于候选项和当前选择动态判断禁用状态 |
 | searchable | `boolean` | `false` | 可搜索 |
 | showSearch | `boolean` | `false` | searchable 的等价别名 |
 | filterOption | `(input, option) => boolean` | — | 自定义过滤 |
@@ -121,6 +160,7 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | loading | `boolean` | `false` | 加载态 |
 | emptyContent | `ReactNode` | — | 空态文案 |
 | optionRender | `(option, info) => ReactNode` | — | 自定义菜单内完整选项内容，并获得 selected / active / index 状态 |
+| optionExtraRender | `(option, info) => ReactNode` | — | 自定义选项尾部的独立内容或操作，不触发选中；info 含 disabled / groupPinned |
 | selectedRender | `(option, info) => ReactNode` | — | 自定义触发器中的紧凑已选内容；单选和多选标签均支持 |
 | listHeight | `number` | `260` | 菜单选项滚动区域最大高度 |
 | popupStyle | `CSSProperties` | — | Portal 菜单内联样式，可覆盖宽度或高度 |
@@ -139,8 +179,18 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | ariaLabel | `string` | — | 复杂选项或 optionRender 的独立可访问名称 |
 | icon | `IconName | ReactNode` | — | 前置图标,可传内置图标名或自定义节点 |
 | description | `ReactNode` | — | 次要描述 |
+| extra | `ReactNode` | — | 选项尾部的静态独立内容或操作；optionExtraRender 存在时由其覆盖 |
 | disabled | `boolean` | `false` | 禁用项 |
 
 
+**SelectOptionGroup**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| label \* | `ReactNode` | — | 分组标题 |
+| options \* | `SelectOption<T>[]` | — | 分组内选项 |
+| pinned | `boolean` | `false` | 稳定提升到菜单顶部，其他项目保持原始顺序 |
+
+
 ---
 [← 回到索引](../llms.md)

package/docs/llms/splitter.md

@@ -13,7 +13,15 @@ import { Splitter } from "@fangxinyan/lumina";
 ### 水平分栏
 
 ```tsx
-<Splitter defaultSize={200} min={120} max={360}>
+<Splitter
+  defaultSize={200}
+  min={120}
+  max={360}
+  firstPaneClassName="workspace-sidebar-pane"
+  firstPaneStyle={{ overflow: "hidden" }}
+  secondPaneClassName="workspace-main-pane"
+  handle={<span aria-hidden>⋮</span>}
+>
   <SidePanel />
   <MainPanel />
 </Splitter>
@@ -64,6 +72,9 @@ const [w, setW] = useState(220);
 | step | `number` | `16` | 方向键步长 (px) |
 | secondMin | `number` | `24` | 第二面板保留的最小尺寸 |
 | storageKey | `string` | — | 持久化尺寸的本地存储键 |
+| firstPaneClassName / firstPaneStyle | `string / CSSProperties` | — | 第一个面板的 class 与内联样式 |
+| secondPaneClassName / secondPaneStyle | `string / CSSProperties` | — | 第二个面板的 class 与内联样式 |
+| handle | `ReactNode` | — | 正式的分隔手柄内容槽；null 隐藏默认握柄 |
 | handleProps | `HTMLAttributes<HTMLDivElement>` | — | 分隔手柄原生属性与 aria-label |
 | children \* | `[ReactNode, ReactNode]` | — | 必须恰好两个子节点 |
 

package/docs/llms/switch.md

@@ -16,15 +16,31 @@ import { Switch } from "@fangxinyan/lumina";
 <Switch checked={v} onChange={setV} label="开启通知" />
 ```
 
-### 原生表单
+### Lumina 表单校验
 
-开启后按 name / value 参与原生表单提交，required 可交给浏览器校验。
+通过 Form.Item 与 message 提供一致的组件反馈，不再触发浏览器原生 required 气泡。name / value 仍会透传到真实 checkbox。
 
 ```tsx
-<form onSubmit={(event) => event.preventDefault()}>
-  <Switch name="notifications" value="enabled" required label="开启通知" />
+<Form
+  layout="inline"
+  onFinish={() => message.success({ key: "switch-validation", content: "通知已开启" })}
+  onFinishFailed={() => message.warning({ key: "switch-validation", content: "请先开启通知" })}
+>
+  <Form.Item
+    name="notifications"
+    valuePropName="checked"
+    rules={[{
+      required: true,
+      message: "请开启通知",
+      validator: (_rule, checked) => checked
+        ? Promise.resolve()
+        : Promise.reject(new Error("请开启通知")),
+    }]}
+  >
+    <Switch name="notifications" value="enabled" label="开启通知" />
+  </Form.Item>
   <Button type="submit">验证提交</Button>
-</form>
+</Form>
 ```
 
 ### 尺寸
@@ -66,6 +82,7 @@ checkedChildren / unCheckedChildren 在轨道内显示简短文字(如 ON/OFF)
 | size | `"sm" | "md"` | `"md"` | 尺寸 |
 | name / value | `string` | — | 原生表单字段名与开启时提交的值 |
 | required / form | `boolean / string` | — | 原生必填约束与关联 form id |
+| invalid | `boolean` | `false` | 错误态，可由 Form.Item 自动注入 |
 | disabled | `boolean` | `false` | 禁用 |
 
 

package/docs/llms/tablepro.md

@@ -25,6 +25,27 @@ import { TablePro } from "@fangxinyan/lumina";
 />
 ```
 
+### 当前行高亮 / 横向空态
+
+activeRowKey 只表达当前上下文，不会勾选行；横向滚动表格的 empty 会始终居中在可视区域。
+
+```tsx
+<TablePro
+  rowKey="id"
+  activeRowKey={activeRowKey}
+  rowClassName={(row) => row.status === "离线" ? "offline-row" : undefined}
+  onRowClick={(row) => setActiveRowKey(row.id)}
+  data={rows}
+  columns={columns}
+/>
+
+<TablePro
+  data={[]}
+  scroll={{ x: 1200 }}
+  empty={<Tag>当前筛选没有结果</Tag>}
+/>
+```
+
 ### 卡片行分页
 
 variant='cards' 与内置 pagination 共用 TablePro 容器背景,分页区不会单独变成另一块底色。
@@ -59,7 +80,8 @@ TablePro 直接透传 expandable 到 Table。
 
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| ... | `TableProps` | — | 继承自 Table 全部 props (包括新的 pagination / scroll / rowSelection / expandable / filters) |
+| ... | `TableProps` | — | 继承自 Table 全部 props (包括 pagination / scroll / rowSelection / expandable / filters) |
+| activeRowKey / rowClassName | `RowKey / string | (row, index) => string` | — | 纯高亮当前行，并支持固定或按行计算的业务类名 |
 | toolbar | `ReactNode` | — | 工具栏内容 |
 | actions | `ReactNode` | — | 工具栏右侧操作 |
 | footer | `ReactNode` | — | 底部 (可选,传了会渲染在分页下方) |

package/docs/llms/tabs.md

@@ -25,6 +25,24 @@ import { Tabs } from "@fangxinyan/lumina";
 <Tabs variant="line" items={[...]} />
 ```
 
+### 满高布局 / 正文独立滚动
+
+fill 让 Tabs 占满父容器，标签条保持固定，只有 tabs-content 滚动；两个 className 可定向接入业务布局。
+
+```tsx
+<div style={{ height: 260 }}>
+  <Tabs
+    fill
+    tabBarClassName="workspace-tabs-bar"
+    contentClassName="workspace-tabs-content"
+    items={[
+      { key: "general", label: "通用", content: <LongSettings /> },
+      { key: "advanced", label: "高级", content: <LongSettings /> },
+    ]}
+  />
+</div>
+```
+
 ### 居中对齐
 
 centered 让标签条在容器中水平居中。
@@ -44,6 +62,9 @@ centered 让标签条在容器中水平居中。
 | onChange | `(key: string) => void` | — | 切换 |
 | variant | `"line" | "pill" | "segmented"` | `"line"` | 样式 |
 | centered | `boolean` | `false` | 标签条居中对齐 |
+| tabBarClassName | `string` | — | 标签条容器的附加类名 |
+| contentClassName | `string` | — | 正文容器的附加类名 |
+| fill | `boolean` | `false` | 占满父容器，并让正文区域独立滚动 |
 
 
 ---

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 拟态风格的 React 18 组件库,目标是 Electron 桌面应用。**写给 AI 编程助手**的按需文档 —— 每个组件单独一个 `.md`,避免一次性读取全部。示例源自 playground 的 demo,可直接复制运行。
 
 - **包名**: `@fangxinyan/lumina`
-- **版本**: `0.7.0`
+- **版本**: `0.9.0`
 - **React 最低版本**: 18
 - **环境**: 带打包器的 React 工程(Vite / Next.js / Webpack / Remix / Electron + Vite 等)
 - **零运行时依赖**: 只依赖 `react` / `react-dom` (peer deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangxinyan/lumina",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Lumina — Neumorphic component library for Electron & React apps",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/chunk-RAK6CENJ.js

@@ -1,83 +0,0 @@
-import { withComponentTheme } from './chunk-DRDDQCDD.js';
-import './tokens-CEJVVA3G.css';
-import './shared-NJHRNLRH.css';
-import './Tabs-A3IG6UZ6.css';
-import * as React from 'react';
-import { jsxs, jsx } from 'react/jsx-runtime';
-
-var getFirstEnabledKey = (items) => items.find((item) => !item.disabled)?.key;
-var TabsBase = React.forwardRef(({
-  items,
-  activeKey,
-  defaultActiveKey,
-  onChange,
-  variant = "line",
-  centered,
-  className = "",
-  ...rest
-}, ref) => {
-  const baseId = React.useId();
-  const tabRefs = React.useRef(/* @__PURE__ */ new Map());
-  const [inner, setInner] = React.useState(defaultActiveKey ?? getFirstEnabledKey(items));
-  const isControlled = activeKey !== void 0;
-  const requested = isControlled ? activeKey : inner;
-  const current = items.some((item) => item.key === requested && !item.disabled) ? requested : getFirstEnabledKey(items);
-  const select = (k) => {
-    if (items.find((item) => item.key === k)?.disabled) return;
-    if (!isControlled) setInner(k);
-    onChange?.(k);
-  };
-  const handleTabKeyDown = (event) => {
-    const enabled = items.filter((item) => !item.disabled);
-    const index = enabled.findIndex((item) => item.key === current);
-    let target;
-    if (event.key === "ArrowRight") target = enabled[(index + 1) % enabled.length];
-    if (event.key === "ArrowLeft") target = enabled[(index - 1 + enabled.length) % enabled.length];
-    if (event.key === "Home") target = enabled[0];
-    if (event.key === "End") target = enabled[enabled.length - 1];
-    if (!target) return;
-    event.preventDefault();
-    tabRefs.current.get(target.key)?.focus();
-    select(target.key);
-  };
-  const active = items.find((i) => i.key === current);
-  const activeIndex = items.findIndex((item) => item.key === current);
-  return /* @__PURE__ */ jsxs("div", { ref, className: `tabs ${variant} ${centered ? "centered" : ""} ${className}`, ...rest, children: [
-    /* @__PURE__ */ jsx("div", { className: "tabs-nav", role: "tablist", children: items.map((it, index) => /* @__PURE__ */ jsx(
-      "button",
-      {
-        ref: (node) => {
-          if (node) tabRefs.current.set(it.key, node);
-          else tabRefs.current.delete(it.key);
-        },
-        type: "button",
-        role: "tab",
-        id: `${baseId}-tab-${index}`,
-        "aria-selected": current === it.key,
-        "aria-controls": it.content !== void 0 ? `${baseId}-panel-${index}` : void 0,
-        tabIndex: current === it.key ? 0 : -1,
-        disabled: it.disabled,
-        className: `tab ${current === it.key ? "active" : ""}`,
-        onClick: () => select(it.key),
-        onKeyDown: handleTabKeyDown,
-        children: it.label
-      },
-      it.key
-    )) }),
-    active?.content !== void 0 && /* @__PURE__ */ jsx(
-      "div",
-      {
-        id: `${baseId}-panel-${activeIndex}`,
-        className: "tabs-content",
-        role: "tabpanel",
-        "aria-labelledby": `${baseId}-tab-${activeIndex}`,
-        tabIndex: 0,
-        children: active.content
-      }
-    )
-  ] });
-});
-TabsBase.displayName = "Tabs";
-var Tabs = withComponentTheme(TabsBase, "Tabs", "tabs");
-
-export { Tabs };