x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/date-picker.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # DatePicker AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`DatePicker`；模型：v-model、v-model:popup-visible；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`DatePicker, MonthPicker, QuarterPicker, RangePicker, WeekPicker, YearPicker`；主要模型：v-model、v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./date-picker-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/date-picker`（包含 base.css、button.css、date-picker.css、scrollbar-v2.css、time-picker.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/date-picker)。默认 `type='date'`、`allowClear=true`、`showToday=true`、`showTime=false`、`position='bl'`。`format` 控制显示，`valueFormat` 控制输出；本例使用 `'YYYY-MM-DD'` 字符串。公开 `DatePickerModelValue` 还包含数字、Date、数组和 `undefined`。
 
 `change(value, date, dateString)` 为提交值，`select` 是面板选择；后两个参数声明为 `unknown`。清空返回 `undefined`，本例归一化为 `''` 保持受控。支持 `cell` / `extra` / `prefix` / `suffix-icon` 插槽；带时间选择需确认后提交。
@@ -31,4 +33,377 @@ function changed(value: DatePickerModelValue, _date: unknown, _text: unknown) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/date-picker.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./date-picker-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在表单、筛选和业务配置中输入或选择日期，也可以选择月份、年份、季度、周和日期范围。只需要选择一天内具体时间时，请使用 [TimePicker 时间选择器](./time-picker.md)。
+
+
+### 何时使用
+
+- 用户需要填写生日、截止日期、排期日期、账期等日期字段。
+- 用户需要在筛选表单中选择一个日期范围。
+- 需要限制周末、历史日期或业务不可用日期时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('2026-06-04');
+</script>
+<template>
+<DatePicker v-model="date" />
+</template>
+```
+
+### 受控值和事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('2026-06-04');
+const popupVisible = ref(false);
+const handleSelect = (value: import('x-next').DatePickerModelValue) => console.log('select', value);
+const handleChange = (value: import('x-next').DatePickerModelValue) => console.log('change', value);
+const handleClear = () => console.log('clear');
+</script>
+<template>
+<DatePicker
+    v-model="date"
+    v-model:popup-visible="popupVisible"
+    allow-clear
+    @select="handleSelect"
+    @change="handleChange"
+    @clear="handleClear"
+  />
+</template>
+```
+
+### 月份、年份、季度和周
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { MonthPicker, YearPicker, QuarterPicker, WeekPicker } from 'x-next';
+import { ref } from 'vue';
+
+const month = ref('2026-06');
+const year = ref('2026');
+const quarter = ref('2026-Q2');
+const week = ref('2026-23rd');
+</script>
+<template>
+<MonthPicker v-model="month" />
+  <YearPicker v-model="year" />
+  <QuarterPicker v-model="quarter" />
+  <WeekPicker v-model="week" />
+</template>
+```
+
+### 日期范围
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RangePicker } from 'x-next';
+import { ref } from 'vue';
+
+const range = ref(['2026-06-01', '2026-06-30']);
+</script>
+<template>
+<RangePicker v-model="range" />
+</template>
+```
+
+### 中国农历展示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker, RangePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('2026-02-17');
+const range = ref(['2026-06-19', '2026-09-25']);
+</script>
+<template>
+<DatePicker v-model="date" show-lunar />
+  <RangePicker
+    v-model="range"
+    :show-lunar="{ showSolarFestival: true }"
+  />
+</template>
+```
+
+### 带时间的日期选择
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker, RangePicker } from 'x-next';
+import { ref } from 'vue';
+
+const dateTime = ref('2026-06-04 09:30:00');
+const dateTimeRange = ref(['2026-06-02 00:00:00', '2026-07-29 09:09:06']);
+</script>
+<template>
+<DatePicker v-model="dateTime" show-time />
+  <RangePicker v-model="dateTimeRange" show-time />
+</template>
+```
+
+### 月范围和受控面板
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RangePicker, DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const monthRange = ref(['2026-01', '2026-06']);
+const date = ref('2026-06-04');
+const panel = ref('2026-06-01');
+</script>
+<template>
+<RangePicker v-model="monthRange" mode="month" />
+  <DatePicker
+    v-model="date"
+    v-model:picker-value="panel"
+    show-confirm-btn
+  />
+</template>
+```
+
+### 动态范围限制
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RangePicker } from 'x-next';
+import { ref } from 'vue';
+
+const range = ref<string[]>([]);
+const draft = ref<string[]>([]);
+
+const disabledDate = (current: Date, type?: 'start' | 'end') => {
+  if (type !== 'end' || !draft.value[0]) return false;
+  const start = new Date(draft.value[0]).getTime();
+  const target = current.getTime();
+  return Math.abs(target - start) > 7 * 24 * 60 * 60 * 1000;
+};
+
+const handleCalendarChange = (value: string[]) => {
+  draft.value = value.filter(Boolean);
+};
+</script>
+<template>
+<RangePicker
+    v-model="range"
+    :disabled-date="disabledDate"
+    @calendar-change="handleCalendarChange"
+  />
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+const date = ref('2026-09-30');
+</script>
+<template>
+<DatePicker v-model="date" size="mini" />
+  <DatePicker v-model="date" size="small" />
+  <DatePicker v-model="date" size="medium" />
+  <DatePicker v-model="date" size="large" />
+</template>
+```
+
+### 状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+const date = ref('2026-09-30');
+</script>
+<template>
+<DatePicker v-model="date" allow-clear />
+  <DatePicker default-value="2026-06-04" readonly />
+  <DatePicker default-value="2026-06-04" disabled />
+  <DatePicker v-model="date" error />
+</template>
+```
+
+### 禁用日期
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('2026-06-04');
+const disabledDate = (current: Date) => {
+  const day = current.getDay();
+  return day === 0 || day === 6;
+};
+</script>
+<template>
+<DatePicker v-model="date" :disabled-date="disabledDate" />
+</template>
+```
+
+### 禁止键盘输入
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('2026-06-04');
+</script>
+<template>
+<DatePicker v-model="date" input-read-only />
+</template>
+```
+
+### 快捷项和值格式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+
+const date = ref('');
+const shortcuts = [
+  { label: '今天', value: () => new Date() },
+  { label: '本月初', value: '2026-06-01' },
+];
+</script>
+<template>
+<DatePicker
+    v-model="date"
+    value-format="timestamp"
+    :shortcuts="shortcuts"
+  />
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+const date = ref('2026-09-30');
+</script>
+<template>
+<DatePicker v-model="date">
+    <template #prefix>交付</template>
+    <template #suffix-icon>📅</template>
+    <template #cell="{ label }">
+      <strong>{{ label }}</strong>
+    </template>
+    <template #extra>选择值：{{ date || '未选择' }}</template>
+  </DatePicker>
+</template>
+```
+
+### 表单组合
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, DatePicker, RangePicker, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+const formRef = ref<FormInstance>();
+const formModel = reactive({ date: '', range: ['2026-06-01', '2026-06-30'] });
+const formResult = ref('点击校验查看结果');
+const handleFormValidate = async () => {
+  const errors = await formRef.value!.validate();
+  formResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleFormReset = () => {
+  formRef.value!.resetFields();
+  formResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formModel">
+    <FormItem field="date" label="交付日期" required feedback>
+      <DatePicker v-model="formModel.date" allow-clear />
+    </FormItem>
+    <FormItem field="range" label="周期">
+      <RangePicker v-model="formModel.range" />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleFormValidate">校验</Button>
+        <Button @click="handleFormReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ formResult }}</p>
+</template>
+```
+
+### 键盘导航与焦点
+
+日历只保留一个日期格的 Tab 停靠点。Home / End 到当前网格行首尾；PageUp / PageDown 翻页，日期模式加 Shift 翻年。月、年、季度模式按各自网格移动。方向键跳过禁用日期，不提交值；Enter 执行选择。范围模式可连续选择两端，Tab 正常切换两个输入框；Esc 或完成选择后焦点返回输入框，Tab 离开面板不会形成焦点陷阱。
+
+原生 `id`、`name`、ARIA 和输入事件透传到真实输入；范围首端使用给定 ID，末端使用 `ID-end`。Form 自动关联标签、帮助及校验错误，独立使用时可设置 `aria-label`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { DatePicker } from 'x-next';
+import { ref } from 'vue';
+const date = ref('2026-09-10');
+const range = ref(['2026-09-10', '2026-09-15']);
+const log = ref('等待选择');
+const disabledDate = (date: Date) => [0, 6].includes(date.getDay());
+const onChange = (value: import('x-next').DatePickerModelValue) => { log.value = `change: ${value || '空'}`; };
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "预约日期" } satisfies HTMLAttributes;
+const nativeAttrs2 = { "aria-label": "预约日期范围" } satisfies HTMLAttributes;
+</script>
+<template>
+<DatePicker v-bind="nativeAttrs1" v-model="date"  :disabled-date="disabledDate" @change="onChange" />
+  <DatePicker v-bind="nativeAttrs2" v-model="range" type="date-range"  />
+  <p>{{ log }}</p>
+</template>
+```
+
+### 交互说明
+
+- `showTime` 仅在日期和日期范围模式生效，默认格式为 `YYYY-MM-DD HH:mm:ss`，选择后需要点击“确定”提交。
+- `showLunar` 仅影响日期格辅助展示，不改变 `modelValue`、`format`、范围排序或禁用逻辑；内置数据来自香港天文台 1901-2100 年公历 / 农历对照表，超出范围时默认不展示。
+- 非法手动输入不会提交新值；按 Enter 或失焦时会尝试按 `format` 解析。
+- 普通范围选择会在选择结束值后自动排序并提交；开启 `showTime` 后需要点击“确定”提交。
+- `valueFormat="timestamp"` 会让绑定值和事件值返回时间戳。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./date-picker-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/dialog-api.md

@@ -0,0 +1,142 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Dialog 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Dialog API
+
+公开声明：`dist/components/dialog/use.d.ts`。
+
+### 服务调用
+
+| 签名 |
+| --- |
+| (options: DialogOptions): DialogReturn |
+
+### 服务成员
+
+| 名称 | 类型 |
+| --- | --- |
+| destroyAll | () => void |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DialogBeforeAction = () => boolean | Promise<boolean>;
+
+type DialogContent = string | number | VNode | RenderFunction;
+
+type DialogRenderResult = string | number | VNode | VNode[] | null | undefined;
+
+interface DialogOptions {
+    title?: DialogContent;
+    content?: DialogContent;
+    footer?: boolean | VNode | ((scoped: DialogFooterScoped) => DialogRenderResult);
+    okText?: string;
+    cancelText?: string;
+    mask?: boolean;
+    maskToClose?: boolean;
+    onOk?: (e: Event) => void;
+    beforeOnOk?: DialogBeforeAction;
+    onCancel?: (e: Event) => void;
+    beforeOnCancel?: DialogBeforeAction;
+    width?: number | string;
+    height?: number | string;
+    top?: number | string;
+    center?: boolean;
+    renderTo?: string | HTMLElement;
+    hideCancel?: boolean;
+    hideOk?: boolean;
+    popupClass?: string;
+}
+
+type DialogFooterAction = 'cancel' | 'ok';
+
+interface DialogFooterScoped {
+    cancel(): void;
+    ok(): void;
+    loadingObj?: {
+        ok: boolean;
+        cancel: boolean;
+    };
+}
+
+interface DialogReturn {
+    close(): void;
+    update(options: Partial<DialogOptions>): void;
+}
+
+interface DialogCaller {
+    (options: DialogOptions): DialogReturn;
+    destroyAll(): void;
+}
+```
+
+
+## DialogComponent API
+
+公开声明：`dist/components/dialog/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| renderTo | 见场景用法与类型 | undefined &#124; string &#124; HTMLElement | 否 | "body" |
+| disabled | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| modelValue | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| top | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | "3vh" |
+| center | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| width | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
+| height | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
+| minWidth | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
+| minHeight | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 0 |
+| title | 见场景用法与类型 | undefined &#124; string | 否 | "" |
+| mask | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| destroyOnClosed | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| onBeforeCancel | 见场景用法与类型 | undefined &#124; Function | 否 | 未声明 |
+| maskToClose | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| escToClose | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| fullscreen | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| messageBox | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| popupClass | 见场景用法与类型 | undefined &#124; string | 否 | undefined |
+| showClose | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| showHeaderBottomLine | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| hideFooter | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| closed | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| close | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| open | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| opened | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| update:modelValue | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+| beforeCancel | 见场景用法与类型 | undefined &#124; Function |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| title | 见场景用法与类型 | any |
+| default | 见场景用法与类型 | any |
+| footer | 见场景用法与类型 | any |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DialogInstance = InstanceType<typeof _Dialog>;
+```
+
+
+返回 [Dialog 用法](./dialog.md)。