x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/alert.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Alert AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Alert`；模型：v-model:visible；已核对事件：close。
+先读 [通用接入](../core.md)。公开导出：`Alert`；主要模型：v-model:visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./alert-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/alert`（包含 base.css、alert.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/alert)。用 `v-model:visible` 控制显示；`defaultVisible=true`、`type='info'`、`showIcon=true`、`closable=false`。常用类型为 info、success、warning、error、normal。
 
 `close(event)` 返回 `MouseEvent`，`after-close` 在关闭动画结束后触发且无参数。默认插槽放正文，`title` / `icon` / `action` / `close-element` 插槽可自定义对应内容。
@@ -30,4 +32,221 @@ function restore() { visible.value = true; feedback.value = '提示显示中'; }
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/alert.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./alert-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于展示页面内的重要提示、状态说明或操作反馈。
+
+
+### 何时使用
+
+- 页面中有需要用户注意的静态提示、状态说明或操作反馈。
+- 提示不需要自动消失，或希望用户手动关闭。
+- 需要在顶部公告、表单说明、结果反馈等场景中保持内容可见。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert type="info" title="提示">这是一条提示信息。</Alert>
+  <Alert type="success">保存成功，配置已生效。</Alert>
+</template>
+```
+
+### 类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert type="info">用于普通信息提示。</Alert>
+  <Alert type="success">用于成功状态反馈。</Alert>
+  <Alert type="warning">用于需要关注的警告信息。</Alert>
+  <Alert type="strong">用于需要强调的提醒信息。</Alert>
+  <Alert type="error">用于错误或失败信息。</Alert>
+  <Alert type="normal">用于弱提示或中性说明。</Alert>
+</template>
+```
+
+### 标题
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert type="info" title="系统提示">维护窗口为今天 22:00 至 23:00。</Alert>
+  <Alert type="warning">
+    <template #title>容量不足</template>
+    当前空间即将用尽，请及时清理。
+  </Alert>
+</template>
+```
+
+### 可关闭
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Alert } from 'x-next';
+import { ref } from 'vue';
+
+const alertKey = ref(0);
+const closeCount = ref(0);
+const afterCloseCount = ref(0);
+
+const handleClose = () => {
+  closeCount.value += 1;
+};
+
+const handleAfterClose = () => {
+  afterCloseCount.value += 1;
+};
+
+const reset = () => {
+  alertKey.value += 1;
+};
+</script>
+<template>
+<Button size="small" @click="reset">重新显示</Button>
+  <Alert
+    :key="alertKey"
+    closable
+    type="success"
+    @close="handleClose"
+    @after-close="handleAfterClose"
+  >
+    保存成功，点击关闭按钮后会触发关闭事件。
+  </Alert>
+  <div>close：{{ closeCount }} 次，after-close：{{ afterCloseCount }} 次</div>
+</template>
+```
+
+### 受控显示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Alert } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(true);
+</script>
+<template>
+<Button size="small" @click="visible = true">显示提示</Button>
+  <Alert v-model:visible="visible" closable type="info">
+    通过 v-model:visible 控制显示状态，关闭后可由外部重新显示。
+  </Alert>
+</template>
+```
+
+### 隐藏图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert :show-icon="false" type="info">隐藏信息提示的默认图标。</Alert>
+  <Alert :show-icon="false" type="warning" title="无图标标题">
+    标题和正文布局仍然保持可读。
+  </Alert>
+</template>
+```
+
+### 自定义图标和关闭元素
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert type="warning">
+    <template #icon>
+      <span class="custom-icon">!</span>
+    </template>
+    自定义图标会替换默认状态图标。
+  </Alert>
+
+  <Alert closable type="info">
+    <template #close-element>知道了</template>
+    可以通过 close-element 插槽替换关闭按钮内容。
+  </Alert>
+
+  <Alert type="normal">
+    <template #icon>
+      <span class="custom-icon">i</span>
+    </template>
+    normal 类型默认不显示图标；传入 icon 插槽后会显示自定义图标。
+  </Alert>
+</template>
+```
+
+### 操作区
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert, Button } from 'x-next';
+
+</script>
+<template>
+<Alert type="warning" title="容量不足" closable>
+    当前空间即将用尽，请及时清理。
+    <template #action>
+      <Button size="small" type="primary">去处理</Button>
+    </template>
+  </Alert>
+
+  <Alert type="info">
+    有新的配置建议可查看。
+    <template #action>
+      <Button size="small" type="text">查看详情</Button>
+    </template>
+  </Alert>
+</template>
+```
+
+### 顶部公告
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Alert } from 'x-next';
+
+</script>
+<template>
+<Alert banner center>这是居中的顶部公告。</Alert>
+  <Alert banner type="warning">banner 只改变边框和圆角，不会自动改变提示类型。</Alert>
+</template>
+```
+
+### 交互说明
+
+- Alert 是页面内静态提示，不会自动消失。
+- 未传 `visible` 时，Alert 使用内部状态；`closable` 关闭后当前实例会隐藏。
+- 传入 `visible` 或使用 `v-model:visible` 时，显示状态由外部控制，关闭会触发 `update:visible=false`。
+- `close-element` 只替换关闭按钮内容，关闭事件仍由外层关闭按钮承载。
+- `normal` 类型默认不显示图标；如需图标，请使用 `icon` 插槽。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./alert-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/bar-chart-api.md

@@ -0,0 +1,177 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# BarChart 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## BarChart API
+
+公开声明：`dist/components/bar-chart/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| categories | 类目轴标签，与各系列 data 下标对应 | undefined &#124; (string &#124; number)[] | 否 | [] |
+| series | 数据系列，必填 | undefined &#124; BarChartSeries[] | 是 | [] |
+| stack | 多系列是否堆叠；false 时并排 | undefined &#124; false &#124; true | 否 | false |
+| height | 图表高度，数字按 px | undefined &#124; string &#124; number | 否 | 240 |
+| width | 图表宽度，数字按 px | undefined &#124; string &#124; number | 否 | "100%" |
+| max | 数值轴上界；传入后锁定刻度，超出部分截断 | undefined &#124; number | 否 | 未声明 |
+| barWidth | 柱体宽度，默认按类目带自适应 | undefined &#124; number | 否 | 未声明 |
+| barRadius | 柱顶圆角半径 | undefined &#124; number | 否 | 4 |
+| padding | 绘制边距，1-4 个非负数字字符串或单个数字 | undefined &#124; string &#124; number | 否 | "8" |
+| grid | 网格线配置 | undefined &#124; BarChartGridOptions | 否 | null |
+| labels | 轴标签配置 | undefined &#124; BarChartLabelsOptions | 否 | null |
+| tooltip | 悬浮提示 | undefined &#124; false &#124; true | 否 | true |
+| legend | 图例，点击可隐藏/显示系列 | undefined &#124; false &#124; true | 否 | false |
+| valueFormatter | 数值格式化，用于提示、图例与数值轴 | undefined &#124; (value: number) => string | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| loading | 加载中 | undefined &#124; false &#124; true &#124; { [x: string]: unknown; } | 否 | false |
+| ariaLabel | 无障碍名称；设置后画布带 role="img" | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| bar-click | 见场景用法与类型 | undefined &#124; (data: BarChartClickData) => any |
+| legend-change | 见场景用法与类型 | undefined &#124; (visibleIndexes: number[]) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| tooltip | 自定义悬浮提示内容 | undefined &#124; (props: BarChartTooltipSlotProps) => unknown |
+| legend | 自定义图例 | undefined &#124; (props: { series: BarChartSeries[]; hiddenIndexes: number[]; }) => unknown |
+| bar | 自定义柱体渲染 | undefined &#124; (props: { seriesIndex: number; index: number; value: number; x: number; y: number; width: number; height: number; color: string; }) => unknown |
+| empty | 自定义空态内容 | undefined &#124; () => unknown |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface BarChartSeries {
+    /** 系列名，用于悬浮提示与多系列区分 */
+    name?: string;
+    /** 该系列按 categories 顺序排列的值 */
+    data: Array<number | null | undefined>;
+    /** 该系列的颜色，默认取内置分类色板（按系列下标循环） */
+    color?: CSSColor;
+}
+
+interface BarChartGridOptions {
+    /** 是否显示横向网格线，默认 true */
+    horizontalLines?: boolean;
+    /** 横向网格线数量（含基线），默认 4 */
+    horizontalLinesNumber?: number;
+}
+
+interface BarChartLabelsOptions {
+    /** 是否显示类目标签，默认 true */
+    xVisible?: boolean;
+    /** 是否显示数值轴标签，默认 true */
+    yVisible?: boolean;
+    /** 类目标签格式化 */
+    xFormatter?: (label: string, index: number) => string;
+    /** 数值轴刻度格式化 */
+    yFormatter?: (value: number) => string;
+    /** 轴标签字号，默认 12 */
+    fontSize?: number;
+    /** 轴标签颜色，默认取组件文字 token */
+    color?: CSSColor;
+}
+
+interface BarChartTooltipItem {
+    /** 系列下标 */
+    seriesIndex: number;
+    /** 系列名，未提供时为 undefined */
+    name?: string;
+    /** 该系列在当前类目的值 */
+    value: number;
+    /**
+     * 该系列生效的颜色：业务传入值原样返回，未传入时是内置色板的
+     * `var(--x-bar-chart-color-series-N)` 引用，可直接用于 style 背景色。
+     */
+    color: string;
+}
+
+interface BarChartActiveData {
+    /** 类目下标 */
+    index: number;
+    /** 类目标签（已应用 labels.xFormatter） */
+    label: string;
+    /** 各类目的系列值 */
+    items: BarChartTooltipItem[];
+    /** 所有系列的合计值；stack 时为堆叠总值 */
+    total: number;
+}
+
+interface BarChartClickData extends BarChartActiveData {
+    /** 命中的系列下标；点击落在空白或零值类目时为 null */
+    seriesIndex: number | null;
+    /** 命中的柱体值；未命中时为 null */
+    value: number | null;
+}
+
+interface BarChartTooltipSlotProps extends BarChartActiveData {
+    /** 组件当前的数值格式化函数，供自定义内容保持一致 */
+    formatValue: (value: number) => string;
+}
+
+type BarChartProps = ExtractPropTypes<typeof barChartProps>;
+
+interface BarChartPlot {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+
+interface BarChartBarGeometry {
+    /** 类目下标 */
+    index: number;
+    /** 系列下标 */
+    seriesIndex: number;
+    /** 该柱体代表的值 */
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** path 绘制指令（仅顶部圆角） */
+    path: string;
+}
+
+interface ComputeBarLayoutParams {
+    count: number;
+    /** values[seriesIndex][categoryIndex]，调用方需已把 null / 负数归一化为 0 */
+    values: number[][];
+    stack: boolean;
+    plot: BarChartPlot;
+    domainMax: number;
+    barWidth?: number;
+    barRadius: number;
+    /** 堆叠分段之间的间隙，默认 1px */
+    stackGap?: number;
+}
+
+interface BarChartLayout {
+    band: number;
+    barWidth: number;
+    bars: BarChartBarGeometry[];
+    /** 每个类目中心 x，供标签、激活线与悬浮锚点使用 */
+    categoryCenters: number[];
+    /** 每个类目最高柱体顶部的 y；无数据时为绘图区底部 */
+    categoryTops: number[];
+}
+```
+
+
+返回 [BarChart 用法](./bar-chart.md)。