x-next 1.11.0 → 1.11.1

package/AI_USAGE/recipes/form-on-demand.md

@@ -1,7 +1,7 @@
-<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/. -->
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # 按需样式与表单接入
 
-适用版本：x-next@1.11.0；来源指纹：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+适用版本：x-next@1.11.1；来源指纹：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
 
 先读 [通用接入](../core.md)，相关组件规则：[config-provider](../components/config-provider.md)、[input](../components/input.md)、[textarea](../components/textarea.md)、[select](../components/select.md)、[checkbox](../components/checkbox.md)。
 
@@ -9,17 +9,18 @@
 
 若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
 
-下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入：
+下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入。表单控件是行内级元素且宽度 100%，裸放在普通块级容器里会参与行内排版，父级行高会在相邻控件之间留下不均匀间距；示例用 `Space` 纵向堆叠并开启 `fill`，控件撑满父容器且间距一致，业务里也应放进 Space、Form 这类布局容器。
 
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { ConfigProvider, Input, Textarea, Select, Checkbox } from 'x-next';
+import { ConfigProvider, Input, Textarea, Select, Checkbox, Space } from 'x-next';
 import 'x-next/style/form-input';
 import 'x-next/style/form-textarea';
 import 'x-next/style/form-select';
 import 'x-next/style/form-checkbox';
+import 'x-next/style/space';
 const title = ref('');
 const summary = ref('只读接入说明');
 const scopes = ref<string[]>(['read']);
@@ -32,10 +33,12 @@ const options = [{ value: 'read', label: '读取' }, { value: 'write', label: '
 </script>
 <template>
   <ConfigProvider theme-color="#0f766e">
-    <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
-    <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
-    <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
-    <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    <Space direction="vertical" fill size="medium">
+      <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
+      <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
+      <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
+      <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    </Space>
     <p role="status">标题：{{ title || '空' }}；范围：{{ scopes.join(', ') }}；同意：{{ accepted }}</p>
   </ConfigProvider>
 </template>

package/AI_USAGE.md

@@ -1,9 +1,9 @@
-<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/manifest.js. -->
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.11.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.11.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、样式依赖、版本与公开类型声明）：`eec9ec4e05970a1f3325c873b8858e1fcb84282fa4c09d4eda8d5044c833f82a`。
+来源指纹（精选示例、映射、样式依赖、版本与公开类型声明）：`ad9d8731c632355a30f4f53643b1e2bcd861a36f1ed67631339334be1eda0b76`。
 
 本手册覆盖 30 个常用组件与服务；包内还有更多导出可用，只是未在此逐个展开。按业务需要选择即可，不必全部使用。
 
@@ -45,17 +45,9 @@
 | BarChart | `BarChart` | `<x-bar-chart>` | 无 | `x-next/style/bar-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
 | LineChart | `LineChart` | `<x-line-chart>` | 无 | `x-next/style/line-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/line-chart) |
 | PieChart | `PieChart` | `<x-pie-chart>` | 无 | `x-next/style/pie-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/pie-chart) |
-<script setup lang="ts">
-import { ref } from 'vue';
-const cmsTitleDemo = ref('');
-const cmsScopesDemo = ref(['read']);
-const cmsAcceptedDemo = ref(false);
-const cmsOptionsDemo = [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }];
-</script>
-
-本页为每个组件提供一段可直接复制的 Vue SFC，从 `x-next` 根入口导入。把这些示例交给 AI 编程助手作为上下文，它生成的代码就会使用真实的 props 与事件，而不是照搬其他组件库的属性名。
+此文件只维护 AI 使用内容，不用于文档站渲染。组件契约须对照实现、公开类型和行为验证，不能仅凭 JSDoc 推断。完整 Vue SFC 从 `x-next` 根入口导入，生成后接受严格模板检查。
 
-每节开头链接到对应的组件文档，那里有可交互的在线示例和完整 API 表；本页代码聚焦用法要点。随包分发的 `node_modules/x-next/AI_USAGE.md` 是本页的完整版本，可直接提供给 AI 工具读取。
+消费方从 `AI_USAGE/index.md` 和 `core.md` 开始，再读所需组件/场景；`AI_USAGE.md` 保留完整兼容版本。组件文档链接供扩展阅读，若说明与当前实现有冲突，应核实实际消费版本与行为，而非机械照抄。
 
 ## 安装与初始化
 
@@ -78,7 +70,7 @@ createApp(App).mount('#app');
 接入时遵循这些约定：
 
 - **按组件路由传原生属性**：Checkbox / Select 用已核实的 `id/name/aria-*` 属性对象 `v-bind`；Input 用 `inputAttrs`，Textarea 用 `textareaAttrs`。Textarea 的 readonly 也放在 `textareaAttrs` 中。组件 props 和事件直接绑定，不把未知组件 API 塞进 attrs。
-- **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。清空日期、时间统一保存 `''`。
+- **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用组件实际支持的 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。DatePicker / TimePicker 清空实际发出 `undefined`，下方单值字符串示例在业务回调中保存 `''` 以保持受控；这不是组件自动归一化，也不能直接套用于范围模型。
 - **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪。ConfigProvider 的主题会同步到 Trigger 浮层及组件形态 Dialog / Drawer；单独调用 applyThemeColor 或独立创建命令式实例时，仍需按实际 DOM 宿主处理主题。
 - **优先用公开主题变量**：参考[样式与主题](https://x-next.yjmf.com/guide/theme)。暗色容器上的 alias 链会重新声明；`themeColor` 写入的内联 primary alias 有覆盖边界，按主题文档设置相关公开 alias。
 - **约束业务全局 CSS**：reset 用 `:where(...)` 降低优先级并限定作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
@@ -90,26 +82,18 @@ createApp(App).mount('#app');
 
 若直接导入 `.css`，需要自己引入 base、自身和全部内部依赖；精选手册索引列出了依赖，发布包 `dist/style/dependencies.json` 提供完整组件映射。全量 `x-next/style.css` 仍可使用。不要同时混用全量与按需方案。
 
-下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入：
+下面是可独立复制的按需表单 SFC，原生属性按各组件真实路由传入。表单控件是行内级元素且宽度 100%，裸放在普通块级容器里会参与行内排版，父级行高会在相邻控件之间留下不均匀间距；示例用 `Space` 纵向堆叠并开启 `fill`，控件撑满父容器且间距一致，业务里也应放进 Space、Form 这类布局容器。
 
-<div class="example-box example-box-column">
-  <x-config-provider theme-color="#0f766e">
-    <x-input v-model="cmsTitleDemo" :input-attrs="{ id: 'cms-title-demo', name: 'title', 'aria-label': '接入标题' }" allow-clear />
-    <x-textarea model-value="只读接入说明" :textarea-attrs="{ name: 'summary', 'aria-label': '接入说明', readonly: true }" />
-    <x-select v-model="cmsScopesDemo" :options="cmsOptionsDemo" multiple aria-label="接入授权范围" />
-    <x-checkbox v-model="cmsAcceptedDemo" aria-label="接入同意条款">同意条款</x-checkbox>
-  </x-config-provider>
-  <span role="status">标题：{{ cmsTitleDemo || '空' }}；范围：{{ cmsScopesDemo.join(', ') }}；同意：{{ cmsAcceptedDemo }}</span>
-</div>
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { ConfigProvider, Input, Textarea, Select, Checkbox } from 'x-next';
+import { ConfigProvider, Input, Textarea, Select, Checkbox, Space } from 'x-next';
 import 'x-next/style/form-input';
 import 'x-next/style/form-textarea';
 import 'x-next/style/form-select';
 import 'x-next/style/form-checkbox';
+import 'x-next/style/space';
 const title = ref('');
 const summary = ref('只读接入说明');
 const scopes = ref<string[]>(['read']);
@@ -122,10 +106,12 @@ const options = [{ value: 'read', label: '读取' }, { value: 'write', label: '
 </script>
 <template>
   <ConfigProvider theme-color="#0f766e">
-    <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
-    <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
-    <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
-    <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    <Space direction="vertical" fill size="medium">
+      <Input v-model="title" :input-attrs="titleAttrs" allow-clear />
+      <Textarea v-model="summary" :textarea-attrs="summaryAttrs" />
+      <Select v-model="scopes" :options="options" multiple v-bind="selectAttrs" />
+      <Checkbox v-model="accepted" v-bind="checkboxAttrs">同意条款</Checkbox>
+    </Space>
     <p role="status">标题：{{ title || '空' }}；范围：{{ scopes.join(', ') }}；同意：{{ accepted }}</p>
   </ConfigProvider>
 </template>
@@ -211,7 +197,7 @@ const pickerAttrs = { id: 'brand-color', 'aria-label': '品牌色' };
 
 ## Button
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。独立使用时尺寸回退为 `'medium'`，`disabled` / `loading` 默认关闭。
+[组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。尺寸优先级为显式 `size` → ButtonGroup → ConfigProvider → `'medium'`；Button 不通过 FormItem 继承尺寸。`disabled` / `loading` 默认关闭。
 
 `click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
 
@@ -238,7 +224,7 @@ async function save(_event: MouseEvent) {
 
 ## Input
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/input)。`v-model` 为字符串，`input` 随输入触发，`change` 在失焦或回车时触发，`clear` 通知清空；readonly 是组件 prop。原生 id、name、aria、required 用 `inputAttrs`，外部 class / style 落在容器。内部装饰用 prefix / suffix，外侧标签用 prepend / append。
+[组件文档与 live demo](https://x-next.yjmf.com/components/input)。`v-model` 为字符串，`input` 随输入触发；失焦、回车或清空时，值相对聚焦时/上次 change 的记录发生变化才触发 `change(value, event)`。`clear(event)` 通知清空按钮操作；readonly 是组件 prop。原生 id、name、aria、required 用 `inputAttrs`，外部 class / style 落在容器。内部装饰用 prefix / suffix，外侧标签用 prepend / append。
 
 ```vue
 <script setup lang="ts">
@@ -338,7 +324,7 @@ function changed(value: string | number | boolean, _event: Event) {
 
 ## Select
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 使用可变数组，常用字段是 `label`、`value`、`disabled`。
+[组件文档与 live demo](https://x-next.yjmf.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 是选项对象数组，常用字段是 `label`、`value`、`disabled`。静态数组可直接传入；动态选项用 `ref` / `reactive` 等响应式状态更新，支持替换数组，不要求原地修改；公开类型不接受 readonly 数组时先复制成普通数组。
 
 `change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
 
@@ -418,7 +404,7 @@ function changed(value: number) { feedback.value = value ? `评分 ${value}` : '
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
 
-`change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案，line 类型不显示文案。
+`change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案；`type='line'` 或有效尺寸为 `'mini'`（含继承尺寸）时均不显示文案。
 
 ```vue
 <script setup lang="ts">
@@ -468,7 +454,7 @@ function changed(value: DatePickerModelValue, _date: unknown, _text: unknown) {
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/time-picker)。默认 `type='time'`、`allowClear=true`、`disableConfirm=false`，默认格式为 `'HH:mm:ss'`。`format` 同时决定显示与输出；`step` 用 `{ hour, minute, second }`，各步长默认 `1`。
 
-`change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空归一化为 `''`；支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
+`change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空发出 `update:modelValue(undefined)` 和 `change(undefined, undefined)`；本例的业务 `update()` 才归一化为 `''` 保持单值字符串受控。支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
 
 ```vue
 <script setup lang="ts">
@@ -546,7 +532,7 @@ function cancel() { feedback.value = '已取消'; visible.value = false; }
 
 ## Message
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/message)。`Message(options)` 或 `.success()` / `.error()` / `.loading()` 等显示提示。默认 `type='info'`、`duration=3000` 毫秒、`position='top'`、`showClose=false`；`duration=0` 持续显示，内容用 `message` 或 `content`。
+[组件文档与 live demo](https://x-next.yjmf.com/components/message)。`Message(options)` 或 `.success()` / `.error()` / `.loading()` 等显示提示。服务默认 `type='info'`、`duration=3000` 毫秒、`position='top'`、`showClose=false`；`duration=0` 持续显示，内容用 `message` 或 `content`。根入口的 `MessageComponent` 是模板组件，默认 `type='success'`，不要把服务默认值套给组件；需要统一效果时显式传 `type`。
 
 返回句柄只有 `close()`；同一容器和位置下再次传相同 `id` 更新消息，没有句柄 `update()`。`onClose(id?)` 在自动或手动关闭时触发；自定义内容可用 VNode / 渲染函数。页面只清理自己持有的句柄。
 
@@ -607,6 +593,8 @@ onBeforeUnmount(() => handle?.close());
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/notification)。`Notification(options)` 或 `.success()` 等显示通知。服务默认 `type='info'`、`duration=3000` 毫秒、`position='top-right'`、`offset=20`、`showClose=true`；四角位置可选，`duration=0` 持续显示。
 
+根入口 `NotificationComponent` 是模板组件，默认 `offset=0`，与命令式服务不同；模板组件和服务选项按各自公开类型使用。
+
 `title` 和 `message` / `content` 是内容，`footer` / `icon` 可用 VNode 或渲染函数。返回句柄只有 `close()`；同一容器与位置下复用 `id` 更新。`onClick()` 无参数，`onClose(id?)` 接收标识；`.remove(id)` / `.clear(position?)` 是服务级方法。
 
 ```vue
@@ -661,7 +649,7 @@ function cancel(_event: Event) { feedback.value = '已取消删除'; }
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/popover)。使用 `v-model:popup-visible`；默认 `trigger='click'`、`position='bottom'`、`showArrow=false`、`defaultPopupVisible=false`、`unmountOnClose=true`。默认插槽是触发器，`title` / `content` 插槽放浮层内容。
 
-`popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，局部主题下按实际挂载位置核对样式。
+`popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，用于定位、滚动及裁剪。通过 ConfigProvider 配置的主题会由 Trigger 同步到浮层根，默认挂到 body 也生效；任意业务 CSS 变量或仅在局部 DOM 调用 applyThemeColor 不等于该注入协议，仍要核对实际继承。
 
 ```vue
 <script setup lang="ts">
@@ -688,7 +676,7 @@ function changed(value: boolean) { feedback.value = value ? '说明已打开' :
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
 
-无模型和业务 change 事件，由业务更新 `percent`。`status` 为 normal、success、warning、danger，未设置时达到 1 自动为 success；`text` 插槽提供 `{ percent }`。
+无模型和业务 change 事件，由业务更新 `percent`。`status` 为 `'normal' | 'success' | 'warning' | 'strong' | 'danger'`，未设置时达到 1 自动为 success；显式 status 优先，`strong` 不表示完成。`text` 插槽提供 `{ percent }`。
 
 ```vue
 <script setup lang="ts">
@@ -703,6 +691,7 @@ function advance() { percent.value = Math.min(1, percent.value + 0.25); }
     <Progress :percent="percent">
       <template #text="scope">已完成 {{ Math.round(scope.percent * 100) }}%</template>
     </Progress>
+    <Progress :percent="percent" status="strong" />
     <Button :disabled="percent >= 1" @click="advance">推进任务</Button>
   </div>
 </template>
@@ -838,9 +827,9 @@ function refresh() { refreshed.value = true; }
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
 
-**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，resolve 即成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 即失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。返回值是 fetch `Response` 时组件读取响应体；非 2xx 按失败处理，`error.status` 为状态码。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
+**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，通常 resolve 成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。fetch `Response` 为非 2xx 时，即使 Promise resolve 也按失败处理，`error.status` 为状态码；成功响应仅对 JSON/text 内容类型解析，二进制等其他类型保留 Response 本体，不自动转为 Blob。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
 
-列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表；`beforeUpload` 返回 `false` 拦截、返回新 `File` 替换，支持 Promise。
+列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表。`beforeUpload` 返回 `false`、抛错或 Promise reject 都会拒绝入列并触发 `reject`；返回 `File` 替换文件，返回 `Blob` / string 则用原文件名生成新 File。string 是文件内容而非下载 URL；以上返回形式支持 Promise。
 
 `change({ file, fileList })` 覆盖加入、进度、成功、失败和移除；`success` / `error` / `remove` / `progress` 是更细粒度的补充。`autoUpload=false` 时文件先以 `init` 入列，再用组件 `submit()` 上传、`abort()` 取消、`retry()` 重试。图片卡场景可加 `image-preview` 用内置 `ImagePreview` 看图。
 
@@ -888,11 +877,13 @@ function beforeUpload(file: File) {
 
 ## BarChart
 
-[组件文档与 live demo](https://x-next.yjmf.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠并显示合计。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
+[组件文档与 live demo](https://x-next.yjmf.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠。默认提示在当前类目有效条目多于一项时显示合计，与 stack 无直接关联；多系列时零值条目会过滤，隐藏系列不参与提示。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
 
 数值轴自动取 1/2/5 步长的整洁刻度（所以刻度行数可能少于 `grid.horizontalLinesNumber`）；传 `max` 可锁定上界。`loading` 显示加载遮罩；数据全为 0 时显示空态，可用 `empty` 插槽替换。`null` / 负数按 0 处理且不画柱体。
 
-`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`；点击柱体触发 `barClick`，命中具体柱体时带 `seriesIndex` / `value`，未命中时为 `null`。`valueFormatter` 统一控制提示、图例与数值轴的数字格式。
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`。默认图例只显示色块和系列名，不显示数值；`valueFormatter` 作用于默认提示与数值轴，`labels.yFormatter` 可单独覆盖数值轴，不改变图例。
+
+SVG 点击的 x 落在横向类目范围内才触发 `barClick`；直接命中柱体时带 `seriesIndex` / `value`，该范围内未命中柱体则这两个字段为 `null`。x 在类目范围外不触发；不要把此逻辑当成完整二维绘图区边界判断。
 
 ```vue
 <script setup lang="ts">
@@ -930,7 +921,9 @@ function onBarClick(data: { label: string; total: number; value: number | null }
 
 **缺测要显式表达**：把没有数据的点写成 `null`，默认会在该处**断开**折线（不会画成跌到 0）；确需连线时传 `:connect-nulls="true"`。数值轴对纯正数数据保持 0 基线，出现负值才向下扩展；`min` / `max` 可锁定区间。`smooth` 默认开启，`show-points` 默认 `'auto'`（点数少时常显）。
 
-`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`（数值轴会按剩余可见系列重算）；点击触发 `lineClick`，命中数据点时带 `seriesIndex` / `value`。`valueFormatter` 同时作用于提示与图例，`labels.yFormatter` 只作用于数值轴。
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`（数值轴会按剩余可见系列重算）。默认图例只显示色块和系列名，不显示数值；`valueFormatter` 作用于默认提示与数值轴，`labels.yFormatter` 可单独覆盖数值轴。
+
+SVG 点击的 x 落在横向类目范围内才触发 `lineClick`。直接命中圆点时带该点的 `seriesIndex` / `value`；未直接命中时取对应类目中 y 距离最近的可见数据点，只有没有候选点时这两个字段才为 `null`，不是“点空白必为 null”。x 在类目范围外不触发；这不是完整二维绘图区边界判断。
 
 ```vue
 <script setup lang="ts">
@@ -938,7 +931,7 @@ import { ref } from 'vue';
 import { LineChart } from 'x-next';
 import 'x-next/dist/style.css';
 const categories = ref(['09-28', '09-29', '09-30', '10-01', '10-02']);
-// 10-01 当天缺测：null 会让折线在该处断开
+// 09-30 当天缺测：null 会让折线在该处断开
 const series = ref([
   { name: '请求量', data: [820, 932, null, 934, 1290] },
   { name: '错误数', data: [12, 18, null, 9, 22] },

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.11.1] - 2026-10-07
+
+### 修复
+
+- Space `fill` 的间距项规则此前编译成 `.x-space-fill--item`，与运行时类名 `.x-space--item` 不符，`flex: 1` 从未生效；改为直接命中子项后，「撑满父容器并等分可用空间」的公开语义恢复。
+- Space 垂直方向 `fill` 补 `align-items: stretch`，宽度 100% 的表单控件不再被默认 `align="center"` 收缩成内容宽度；文档「撑满宽度」示例的输入框由实测 26px 恢复为满宽，间距项同时改为 flex 容器，控件不再参与行内排版。
+
+### 文档
+
+- AI 使用指南的按需表单示例改用 `Space` 纵向堆叠并引入 `style/space`，说明表单控件是行内级元素、需放进 Space / Form 这类布局容器，避免裸放在块级容器时因父级行高产生 `0 / 6 / 0` 式不均匀间距。完整 SFC、精选手册按需表单片段与文档站 live demo 同步。
+
+### 工程与验证
+
+- 新增 Space 填充的编译产物守卫，拦截「SCSS 可编译但选择器永不适配」这类单元测试与构建都发现不了的静默缺陷；已用还原旧写法的负向验证确认守卫有效。
+- 新增 Space 单组件缺陷与示例修复记录；`pnpm run build`、`check:compiled-css`、`docs:build`、`check:ai-usage`、`test:ai-usage`、Space 单测（25 例）通过。
+
 ## [1.11.0] - 2026-10-06
 
 ### 新增