@fangxinyan/lumina 0.6.14 → 0.6.16

package/docs/llms/datetimepicker.md

@@ -0,0 +1,83 @@
+# DateTimePicker 日期时间选择
+
+> 输入框触发的日期时间选择器,把 Calendar 与时分秒列组合在同一个浮层内。
+
+## 导入
+
+```tsx
+import { DateTimePicker } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<DateTimePicker defaultValue={new Date(2026, 4, 25, 9, 30)} />
+```
+
+### 受控
+
+value 使用 Date | null,onChange 同时返回 Date 和格式化字符串。
+
+```tsx
+const [startAt, setStartAt] = useState<Date | null>(new Date(2026, 4, 25, 9, 30));
+<DateTimePicker value={startAt} onChange={setStartAt} allowClear />
+```
+
+### 秒级选择
+
+```tsx
+<DateTimePicker
+  value={deployAt}
+  onChange={setDeployAt}
+  format="YYYY-MM-DD HH:mm:ss"
+  showSecond
+/>
+```
+
+### 范围与步进
+
+15 分钟粒度,只允许工作日 08:00 到 20:00 之间的时间。
+
+```tsx
+<DateTimePicker
+  min={new Date(2026, 4, 1, 8)}
+  max={new Date(2026, 4, 31, 20)}
+  minuteStep={15}
+  disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
+  disabledTime={(time) => time.hour === 12}
+/>
+```
+
+### 尺寸与状态
+
+```tsx
+<DateTimePicker size="sm" />
+<DateTimePicker invalid />
+<DateTimePicker size="lg" disabled />
+```
+
+## API
+
+**DateTimePicker**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `Date | null` | — | 受控/初始日期时间 |
+| onChange | `(date: Date | null, dateString: string) => void` | — | 选择或清空时触发 |
+| format | `"YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | ((date) => string)` | `"YYYY-MM-DD HH:mm"` | 显示格式或自定义格式化函数 |
+| showSecond | `boolean` | — | 显示秒列 |
+| hourStep / minuteStep / secondStep | `number` | `1` | 列选项步进 |
+| min / max | `Date` | — | 可选日期时间范围 |
+| disabledDate | `(date: Date) => boolean` | — | 自定义禁用日期 |
+| disabledTime | `(time: TimePickerValue, date: Date) => boolean` | — | 按当前日期禁用具体时间 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 输入框尺寸 |
+| allowClear | `boolean` | `false` | 允许清空 |
+| open / defaultOpen / onOpenChange | `—` | — | 受控浮层显隐 |
+| popupClassName / dropdownClassName | `string` | — | 浮层 className |
+| disabled / readOnly / invalid / placeholder | `—` | — | 常规输入状态 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/timepicker.md

@@ -0,0 +1,81 @@
+# TimePicker 时间选择
+
+> 输入框触发的时分秒选择器,支持步进、范围、禁用时间和秒级选择。
+
+## 导入
+
+```tsx
+import { TimePicker } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础用法
+
+```tsx
+<TimePicker defaultValue="09:30" />
+```
+
+### 受控
+
+value 是 HH:mm / HH:mm:ss 字符串或 null,onChange 第二个参数返回结构化 time。
+
+```tsx
+const [time, setTime] = useState<string | null>("09:30");
+<TimePicker value={time} onChange={setTime} allowClear />
+```
+
+### 秒级选择
+
+```tsx
+<TimePicker
+  value={precise}
+  onChange={setPrecise}
+  format="HH:mm:ss"
+  showSecond
+/>
+```
+
+### 范围与步进
+
+15 分钟粒度,只允许 08:00 到 20:00 之间的时间。
+
+```tsx
+<TimePicker
+  min="08:00"
+  max="20:00"
+  minuteStep={15}
+  disabledTime={(time) => time.hour === 12}
+/>
+```
+
+### 尺寸与状态
+
+```tsx
+<TimePicker size="sm" />
+<TimePicker invalid />
+<TimePicker size="lg" disabled />
+```
+
+## API
+
+**TimePicker**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| value / defaultValue | `string | null` | — | 受控/初始时间 |
+| onChange | `(value: string | null, time: TimePickerValue | null) => void` | — | 选择或清空时触发 |
+| format | `"HH:mm" | "HH:mm:ss"` | `"HH:mm"` | 输出和显示格式 |
+| showSecond | `boolean` | — | 显示秒列 |
+| hourStep / minuteStep / secondStep | `number` | `1` | 列选项步进 |
+| min / max | `string` | — | 可选时间范围 |
+| disabledTime | `(time: TimePickerValue) => boolean` | — | 自定义禁用时间 |
+| size | `"sm" | "md" | "lg"` | `"md"` | 输入框尺寸 |
+| allowClear | `boolean` | `false` | 允许清空 |
+| open / defaultOpen / onOpenChange | `—` | — | 受控浮层显隐 |
+| popupClassName / dropdownClassName | `string` | — | 浮层 className |
+| disabled / readOnly / invalid / placeholder | `—` | — | 常规输入状态 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms.md

@@ -3,7 +3,7 @@
 > 拟态风格的 React 18 组件库,目标是 Electron 桌面应用。**写给 AI 编程助手**的按需文档 —— 每个组件单独一个 `.md`,避免一次性读取全部。示例源自 playground 的 demo,可直接复制运行。
 
 - **包名**: `@fangxinyan/lumina`
-- **版本**: `0.6.14`
+- **版本**: `0.6.16`
 - **React 最低版本**: 18
 - **环境**: 带打包器的 React 工程(Vite / Next.js / Webpack / Remix / Electron + Vite 等)
 - **零运行时依赖**: 只依赖 `react` / `react-dom` (peer deps)
@@ -64,6 +64,9 @@
 - [Select 下拉选择](./llms/select.md) — 下拉选择,支持单/多选、搜索、分组、加载态。
 - [AutoComplete 自动补全](./llms/autocomplete.md) — 输入时展示建议下拉,不限定必须从候选中选。
 - [Cascader 级联选择](./llms/cascader.md) — 层级关联数据集合中的多级选择。
+- [DatePicker 日期选择](./llms/datepicker.md) — 输入框触发的日期选择器,复用 Calendar 并支持范围、禁用日期和格式化。
+- [DateTimePicker 日期时间选择](./llms/datetimepicker.md) — 输入框触发的日期时间选择器,把 Calendar 与时分秒列组合在同一个浮层内。
+- [TimePicker 时间选择](./llms/timepicker.md) — 输入框触发的时分秒选择器,支持步进、范围、禁用时间和秒级选择。
 - [ColorPicker 颜色选择](./llms/colorpicker.md) — 拟态风格的颜色选择器:HSV 色域、色相、hex 输入、预设调色板。
 - [Form 表单](./llms/form.md) — 受控表单,字段绑定 + 校验。
 
@@ -83,7 +86,7 @@
 - [Pagination 分页](./llms/pagination.md) — 分页控件,支持快速跳转与每页条数切换。
 - [Tabs 选项卡](./llms/tabs.md) — 同一层级的内容分组,通过标签切换。
 - [Collapse 折叠面板](./llms/collapse.md) — 纵向折叠面板。
-- [Calendar 日历](./llms/calendar.md) — 查看与选择日期。
+- [Calendar 日历](./llms/calendar.md) — 查看与选择日期,支持快速切换年份和月份。
 
 ### 反馈
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangxinyan/lumina",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "Lumina — Neumorphic component library for Electron & React apps",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -144,9 +144,10 @@
     "build:lib": "tsup",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
+    "test:unit": "vitest run --root . --environment jsdom",
     "gen:docs": "node scripts/gen-llms-doc.mjs",
     "verify:public-api": "node scripts/verify-public-api.mjs",
-    "prepublishOnly": "npm run typecheck && npm run gen:docs && npm run build:lib && npm run verify:public-api"
+    "prepublishOnly": "npm run typecheck && npm run test:unit && npm run gen:docs && npm run build:lib && npm run verify:public-api"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -154,11 +155,13 @@
   },
   "devDependencies": {
     "@babel/standalone": "^7.29.2",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^25.6.0",
     "@types/prismjs": "^1.26.6",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.1",
+    "jsdom": "^29.1.1",
     "postcss": "^8.5.10",
     "postcss-import": "^16.1.1",
     "prismjs": "^1.30.0",
@@ -166,7 +169,8 @@
     "react-dom": "^18.3.1",
     "tsup": "^8.2.4",
     "typescript": "^5.5.4",
-    "vite": "^5.4.2"
+    "vite": "^5.4.2",
+    "vitest": "^4.1.6"
   },
   "keywords": [
     "react",

package/dist/chunk-XG5D777V.js

@@ -1,90 +0,0 @@
-import { Icon } from './chunk-FDZG27IG.js';
-import './tokens-RYJ3DFTU.css';
-import './shared-NJHRNLRH.css';
-import './Calendar-RUTPKREW.css';
-import * as React from 'react';
-import { jsxs, jsx } from 'react/jsx-runtime';
-
-var WEEKDAYS = ["\u65E5", "\u4E00", "\u4E8C", "\u4E09", "\u56DB", "\u4E94", "\u516D"];
-var Calendar = React.forwardRef(({
-  value,
-  defaultValue,
-  onChange,
-  min,
-  max,
-  disabledDate,
-  className = "",
-  ...rest
-}, ref) => {
-  const [inner, setInner] = React.useState(defaultValue ?? /* @__PURE__ */ new Date());
-  const isControlled = value !== void 0;
-  const sel = isControlled ? value : inner;
-  const [view, setView] = React.useState(new Date(sel.getFullYear(), sel.getMonth(), 1));
-  const first = new Date(view.getFullYear(), view.getMonth(), 1);
-  const startDay = first.getDay();
-  const daysInMonth = new Date(view.getFullYear(), view.getMonth() + 1, 0).getDate();
-  const cells = [];
-  for (let i = 0; i < startDay; i++) cells.push(null);
-  for (let d = 1; d <= daysInMonth; d++) cells.push(d);
-  const isSame = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
-  const pick = (d) => {
-    const next = new Date(view.getFullYear(), view.getMonth(), d);
-    if (min && next < min) return;
-    if (max && next > max) return;
-    if (disabledDate?.(next)) return;
-    if (!isControlled) setInner(next);
-    onChange?.(next);
-  };
-  return /* @__PURE__ */ jsxs("div", { ref, className: `calendar ${className}`, ...rest, children: [
-    /* @__PURE__ */ jsxs("div", { className: "calendar-head", children: [
-      /* @__PURE__ */ jsx(
-        "button",
-        {
-          type: "button",
-          className: "btn icon sm ghost",
-          onClick: () => setView(new Date(view.getFullYear(), view.getMonth() - 1, 1)),
-          "aria-label": "Previous month",
-          children: /* @__PURE__ */ jsx(Icon, { name: "chevLeft", size: 14 })
-        }
-      ),
-      /* @__PURE__ */ jsxs("button", { type: "button", className: "calendar-title", children: [
-        view.getFullYear(),
-        " \u5E74 ",
-        view.getMonth() + 1,
-        " \u6708"
-      ] }),
-      /* @__PURE__ */ jsx(
-        "button",
-        {
-          type: "button",
-          className: "btn icon sm ghost",
-          onClick: () => setView(new Date(view.getFullYear(), view.getMonth() + 1, 1)),
-          "aria-label": "Next month",
-          children: /* @__PURE__ */ jsx(Icon, { name: "chevRight", size: 14 })
-        }
-      )
-    ] }),
-    /* @__PURE__ */ jsxs("div", { className: "calendar-grid", children: [
-      WEEKDAYS.map((w) => /* @__PURE__ */ jsx("div", { className: "calendar-dow", children: w }, w)),
-      cells.map((d, i) => {
-        if (d === null) return /* @__PURE__ */ jsx("div", { className: "calendar-cell out" }, i);
-        const date = new Date(view.getFullYear(), view.getMonth(), d);
-        const disabled = min && date < min || max && date > max || (disabledDate?.(date) ?? false);
-        return /* @__PURE__ */ jsx(
-          "button",
-          {
-            type: "button",
-            disabled: !!disabled,
-            className: `calendar-cell ${isSame(date, sel) ? "selected" : ""} ${isSame(date, /* @__PURE__ */ new Date()) ? "today" : ""} ${disabled ? "disabled" : ""}`,
-            onClick: () => pick(d),
-            children: d
-          },
-          i
-        );
-      })
-    ] })
-  ] });
-});
-Calendar.displayName = "Calendar";
-
-export { Calendar };

package/dist/chunk-ZBTGYTQE.cjs

@@ -1,112 +0,0 @@
-'use strict';
-
-var chunkQMX67CVT_cjs = require('./chunk-QMX67CVT.cjs');
-require('./tokens-RYJ3DFTU.css');
-require('./shared-NJHRNLRH.css');
-require('./Calendar-RUTPKREW.css');
-var React = require('react');
-var jsxRuntime = require('react/jsx-runtime');
-
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n.default = e;
-  return Object.freeze(n);
-}
-
-var React__namespace = /*#__PURE__*/_interopNamespace(React);
-
-var WEEKDAYS = ["\u65E5", "\u4E00", "\u4E8C", "\u4E09", "\u56DB", "\u4E94", "\u516D"];
-var Calendar = React__namespace.forwardRef(({
-  value,
-  defaultValue,
-  onChange,
-  min,
-  max,
-  disabledDate,
-  className = "",
-  ...rest
-}, ref) => {
-  const [inner, setInner] = React__namespace.useState(defaultValue ?? /* @__PURE__ */ new Date());
-  const isControlled = value !== void 0;
-  const sel = isControlled ? value : inner;
-  const [view, setView] = React__namespace.useState(new Date(sel.getFullYear(), sel.getMonth(), 1));
-  const first = new Date(view.getFullYear(), view.getMonth(), 1);
-  const startDay = first.getDay();
-  const daysInMonth = new Date(view.getFullYear(), view.getMonth() + 1, 0).getDate();
-  const cells = [];
-  for (let i = 0; i < startDay; i++) cells.push(null);
-  for (let d = 1; d <= daysInMonth; d++) cells.push(d);
-  const isSame = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
-  const pick = (d) => {
-    const next = new Date(view.getFullYear(), view.getMonth(), d);
-    if (min && next < min) return;
-    if (max && next > max) return;
-    if (disabledDate?.(next)) return;
-    if (!isControlled) setInner(next);
-    onChange?.(next);
-  };
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { ref, className: `calendar ${className}`, ...rest, children: [
-    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "calendar-head", children: [
-      /* @__PURE__ */ jsxRuntime.jsx(
-        "button",
-        {
-          type: "button",
-          className: "btn icon sm ghost",
-          onClick: () => setView(new Date(view.getFullYear(), view.getMonth() - 1, 1)),
-          "aria-label": "Previous month",
-          children: /* @__PURE__ */ jsxRuntime.jsx(chunkQMX67CVT_cjs.Icon, { name: "chevLeft", size: 14 })
-        }
-      ),
-      /* @__PURE__ */ jsxRuntime.jsxs("button", { type: "button", className: "calendar-title", children: [
-        view.getFullYear(),
-        " \u5E74 ",
-        view.getMonth() + 1,
-        " \u6708"
-      ] }),
-      /* @__PURE__ */ jsxRuntime.jsx(
-        "button",
-        {
-          type: "button",
-          className: "btn icon sm ghost",
-          onClick: () => setView(new Date(view.getFullYear(), view.getMonth() + 1, 1)),
-          "aria-label": "Next month",
-          children: /* @__PURE__ */ jsxRuntime.jsx(chunkQMX67CVT_cjs.Icon, { name: "chevRight", size: 14 })
-        }
-      )
-    ] }),
-    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "calendar-grid", children: [
-      WEEKDAYS.map((w) => /* @__PURE__ */ jsxRuntime.jsx("div", { className: "calendar-dow", children: w }, w)),
-      cells.map((d, i) => {
-        if (d === null) return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "calendar-cell out" }, i);
-        const date = new Date(view.getFullYear(), view.getMonth(), d);
-        const disabled = min && date < min || max && date > max || (disabledDate?.(date) ?? false);
-        return /* @__PURE__ */ jsxRuntime.jsx(
-          "button",
-          {
-            type: "button",
-            disabled: !!disabled,
-            className: `calendar-cell ${isSame(date, sel) ? "selected" : ""} ${isSame(date, /* @__PURE__ */ new Date()) ? "today" : ""} ${disabled ? "disabled" : ""}`,
-            onClick: () => pick(d),
-            children: d
-          },
-          i
-        );
-      })
-    ] })
-  ] });
-});
-Calendar.displayName = "Calendar";
-
-exports.Calendar = Calendar;