@hbdlzy/ui-core 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hbdlzy/ui-core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Company shared Vue UI core package.",
   "license": "MIT",
   "repository": {
@@ -17,8 +17,23 @@
       "require": "./dist/index.cjs",
       "types": "./dist/index.d.ts"
     },
+    "./ripple": {
+      "import": "./dist/ripple/index.js",
+      "require": "./dist/ripple/index.cjs",
+      "types": "./dist/ripple/index.d.ts"
+    },
     "./components.manifest.json": "./components.manifest.json"
   },
+  "typesVersions": {
+    "*": {
+      "ripple": [
+        "dist/ripple/index.d.ts"
+      ],
+      "components.manifest.json": [
+        "components.manifest.json"
+      ]
+    }
+  },
   "files": [
     "dist",
     "src",
@@ -48,7 +63,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "vite build && pnpm run build:types",
+    "build": "vite build && vite build --config vite.ripple.config.ts && pnpm run build:types",
     "build:types": "vue-tsc -p tsconfig.build.json --declaration --emitDeclarationOnly"
   }
 }

package/src/components/BaseCard/BaseCard.types.d.ts

@@ -0,0 +1,36 @@
+export type BaseCardCssValue = string | number;
+export interface BaseCardDefaultExportPayload {
+    title?: string;
+    metaText?: string;
+}
+export interface BaseCardProps {
+    title?: string;
+    metaText?: string;
+    showHeader?: boolean;
+    showRight?: boolean;
+    showTitleMarker?: boolean;
+    showExport?: boolean;
+    exportText?: string;
+    exportDisabled?: boolean;
+    exportPayload?: unknown;
+    padding?: BaseCardCssValue;
+    radius?: BaseCardCssValue;
+    borderColor?: string;
+    backgroundColor?: string;
+    shadowColor?: string;
+    headerGap?: BaseCardCssValue;
+    headerMarginBottom?: BaseCardCssValue;
+    leftGap?: BaseCardCssValue;
+    rightGap?: BaseCardCssValue;
+    titleColor?: string;
+    titleSize?: BaseCardCssValue;
+    titleWeight?: string | number;
+    markerColor?: string;
+    markerWidth?: BaseCardCssValue;
+    markerHeight?: BaseCardCssValue;
+    markerRadius?: BaseCardCssValue;
+    markerGap?: BaseCardCssValue;
+    metaColor?: string;
+    metaSize?: BaseCardCssValue;
+    exportColor?: string;
+}

package/src/components/BaseCard/BaseCard.vue.d.ts

@@ -0,0 +1,122 @@
+import type { BaseCardCssValue, BaseCardProps } from './BaseCard.types';
+declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<BaseCardProps>, {
+    title: string;
+    metaText: string;
+    showHeader: boolean;
+    showRight: boolean;
+    showTitleMarker: boolean;
+    showExport: boolean;
+    exportText: string;
+    exportDisabled: boolean;
+    padding: number;
+    radius: number;
+    borderColor: string;
+    backgroundColor: string;
+    shadowColor: string;
+    headerGap: number;
+    headerMarginBottom: number;
+    leftGap: number;
+    rightGap: number;
+    titleColor: string;
+    titleSize: number;
+    titleWeight: number;
+    markerColor: string;
+    markerWidth: number;
+    markerHeight: number;
+    markerRadius: string;
+    markerGap: number;
+    metaColor: string;
+    metaSize: number;
+    exportColor: string;
+}>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    export: (payload?: unknown) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<BaseCardProps>, {
+    title: string;
+    metaText: string;
+    showHeader: boolean;
+    showRight: boolean;
+    showTitleMarker: boolean;
+    showExport: boolean;
+    exportText: string;
+    exportDisabled: boolean;
+    padding: number;
+    radius: number;
+    borderColor: string;
+    backgroundColor: string;
+    shadowColor: string;
+    headerGap: number;
+    headerMarginBottom: number;
+    leftGap: number;
+    rightGap: number;
+    titleColor: string;
+    titleSize: number;
+    titleWeight: number;
+    markerColor: string;
+    markerWidth: number;
+    markerHeight: number;
+    markerRadius: string;
+    markerGap: number;
+    metaColor: string;
+    metaSize: number;
+    exportColor: string;
+}>>> & Readonly<{
+    onExport?: ((payload?: unknown) => any) | undefined;
+}>, {
+    title: string;
+    metaText: string;
+    showHeader: boolean;
+    showRight: boolean;
+    showTitleMarker: boolean;
+    showExport: boolean;
+    exportText: string;
+    exportDisabled: boolean;
+    padding: BaseCardCssValue;
+    radius: BaseCardCssValue;
+    borderColor: string;
+    backgroundColor: string;
+    shadowColor: string;
+    headerGap: BaseCardCssValue;
+    headerMarginBottom: BaseCardCssValue;
+    leftGap: BaseCardCssValue;
+    rightGap: BaseCardCssValue;
+    titleColor: string;
+    titleSize: BaseCardCssValue;
+    titleWeight: string | number;
+    markerColor: string;
+    markerWidth: BaseCardCssValue;
+    markerHeight: BaseCardCssValue;
+    markerRadius: BaseCardCssValue;
+    markerGap: BaseCardCssValue;
+    metaColor: string;
+    metaSize: BaseCardCssValue;
+    exportColor: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>, {
+    "title-label"?(_: {}): any;
+    title?(_: {}): any;
+    "header-right"?(_: {}): any;
+    tip?(_: {}): any;
+    default?(_: {}): any;
+}>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/src/components/BaseCard/README.md

@@ -162,3 +162,36 @@ const handleExport = (payload?: unknown) => {
 - 只要不是强业务容器，就尽量不要在页面层重复写卡片壳子
 - 简单场景直接用 `title + 默认插槽`
 - 需要扩展时优先使用 `title` 和 `header-right` 插槽，而不是复制组件结构
+
+## AI 使用指引
+
+AI 在生成页面时，如果遇到统计块、图表块、列表块、详情块等需要统一外壳的区域，应优先使用 `BaseCard`，不要在页面里重新手写卡片标题、左侧竖杠、右侧时间和导出区域。
+
+推荐优先从统一入口导入：
+
+```ts
+import { BaseCard } from '@hbdlzy/ui'
+```
+
+如果当前只安装了核心包，也可以从 `@hbdlzy/ui-core` 导入。
+
+AI 生成代码时按下面顺序判断：
+
+1. 只有标题和内容时，使用 `title + 默认插槽`
+2. 标题右侧有更新时间、单位、按钮时，优先使用 `metaText`、`header-right` 插槽
+3. 标题旁有单选、筛选、标签时，优先使用 `title` 插槽
+4. 内容顶部有单位提示或说明时，优先使用 `tip` 插槽
+5. 需要导出入口时，优先使用 `showExport + @export`，复杂导出可配合 `BaseExportButton`
+
+AI 不应该做这些事：
+
+- 不要复制 `BaseCard` 的 DOM 和 CSS 到业务页面
+- 不要在每个页面重复实现标题左侧标记、卡片边框、标题区 flex 布局
+- 不要为了一个右侧按钮而重写整个卡片结构，优先用插槽扩展
+- 不要把接口请求、图表初始化、表格逻辑塞进 `BaseCard`，这些能力应由 `BaseEChart`、`BaseTable` 或业务页面负责
+
+生成代码前建议同时读取：
+
+- `packages/ui-core/components.manifest.json`
+- `packages/ui-core/src/components/BaseCard/BaseCard.types.ts`
+- 本 README 的 `Props / Slots / Events` 部分

package/src/components/BaseCard/index.d.ts

@@ -0,0 +1,3 @@
+import BaseCard from './BaseCard.vue';
+export default BaseCard;
+export type { BaseCardCssValue, BaseCardDefaultExportPayload, BaseCardProps } from './BaseCard.types';

package/src/components/BaseEChart/BaseEChart.types.d.ts

@@ -0,0 +1,26 @@
+import type { EChartInitOptions, EChartInstance, EChartLoadingOptions, EChartOption, EChartResizeOptions, EChartSetOptionOptions } from '../../echarts';
+export interface BaseEChartProps {
+    option?: EChartOption;
+    theme?: string | Record<string, unknown>;
+    initOptions?: EChartInitOptions;
+    setOptionOptions?: boolean | EChartSetOptionOptions;
+    loading?: boolean;
+    loadingOptions?: EChartLoadingOptions;
+    autoResize?: boolean;
+    useDefaultColors?: boolean;
+    colorStorageKey?: string;
+    defaultColors?: string[];
+    group?: string;
+}
+export interface BaseEChartExpose {
+    getInstance: () => EChartInstance | null;
+    setOption: (option: EChartOption, setOptionOptions?: boolean | EChartSetOptionOptions) => EChartInstance | null;
+    resize: (resizeOptions?: EChartResizeOptions) => void;
+    dispatchAction: (payload: Record<string, unknown>) => void;
+    showLoading: (type?: string, loadingOptions?: EChartLoadingOptions) => void;
+    hideLoading: () => void;
+    clear: () => void;
+    dispose: () => void;
+    on: (eventName: string, handler: (...args: any[]) => void, context?: unknown) => void;
+    off: (eventName?: string, handler?: (...args: any[]) => void) => void;
+}

package/src/components/BaseEChart/BaseEChart.vue.d.ts

@@ -0,0 +1,66 @@
+import { echarts } from '../../echarts';
+import type { BaseEChartProps } from './BaseEChart.types';
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<BaseEChartProps>, {
+    option: () => {};
+    initOptions: () => echarts.EChartsInitOpts;
+    setOptionOptions: () => echarts.SetOptionOpts;
+    loading: boolean;
+    autoResize: boolean;
+    useDefaultColors: boolean;
+    colorStorageKey: string;
+    defaultColors: () => never[];
+    group: undefined;
+}>>, {
+    getInstance: () => echarts.ECharts | null;
+    setOption: (option: echarts.EChartsOption, setOptionOptions?: boolean | echarts.SetOptionOpts | undefined) => echarts.ECharts | null;
+    resize: (resizeOptions?: echarts.ResizeOpts | undefined) => void;
+    dispatchAction: (payload: Record<string, unknown>) => void;
+    showLoading: (type?: string | undefined, loadingOptions?: object | undefined) => void;
+    hideLoading: () => void;
+    clear: () => void;
+    dispose: () => void;
+    on: (eventName: string, handler: (...args: any[]) => void, context?: unknown) => void;
+    off: (eventName?: string | undefined, handler?: ((...args: any[]) => void) | undefined) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: (chart: echarts.ECharts) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<BaseEChartProps>, {
+    option: () => {};
+    initOptions: () => echarts.EChartsInitOpts;
+    setOptionOptions: () => echarts.SetOptionOpts;
+    loading: boolean;
+    autoResize: boolean;
+    useDefaultColors: boolean;
+    colorStorageKey: string;
+    defaultColors: () => never[];
+    group: undefined;
+}>>> & Readonly<{
+    onReady?: ((chart: echarts.ECharts) => any) | undefined;
+}>, {
+    option: echarts.EChartsOption;
+    loading: boolean;
+    initOptions: echarts.EChartsInitOpts;
+    setOptionOptions: boolean | echarts.SetOptionOpts;
+    autoResize: boolean;
+    useDefaultColors: boolean;
+    colorStorageKey: string;
+    defaultColors: string[];
+    group: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/src/components/BaseEChart/README.md

@@ -134,3 +134,36 @@ const gradient = new echarts.graphic.LinearGradient(0, 0, 0, 1, [
 - 页面层只维护 `option`，不要重复写 `echarts.init`
 - 默认走 `BaseEChart + option`，只有确实需要时再通过 `ref` 调暴露方法
 - 渐变色、图形工具优先从 `@hbdlzy/ui-core` 导出的 `echarts` 使用
+
+## AI 使用指引
+
+AI 在生成 ECharts 图表页面时，应优先使用 `BaseEChart`，不要在页面组件里重复写 `echarts.init`、`setOption`、`resize`、`dispose` 和窗口尺寸监听。
+
+推荐优先从统一入口导入：
+
+```ts
+import { BaseEChart, echarts, type EChartOption, type BaseEChartExpose } from '@hbdlzy/ui'
+```
+
+如果当前只安装了核心包，也可以从 `@hbdlzy/ui-core` 导入。
+
+AI 生成代码时按下面顺序判断：
+
+1. 父容器必须给出明确高度，再放入 `<BaseEChart :option="option" />`
+2. 图表配置统一维护在 `option` 或 `computed option` 中
+3. 需要渐变色、图形工具时，使用统一导出的 `echarts`
+4. 需要手动刷新、隐藏 tooltip、派发 action 时，再通过 `ref<BaseEChartExpose>` 调用暴露方法
+5. 后端数据变化时，只更新 `option` 数据，不重新初始化图表实例
+
+AI 不应该做这些事：
+
+- 不要在业务页面直接调用 `echarts.init(dom)`
+- 不要手动注册 `window.resize` 来处理普通图表自适应
+- 不要在页面卸载时重复写 `dispose`，组件已处理
+- 不要把接口请求逻辑放进 `BaseEChart`，页面层负责取数，图表组件只接收 `option`
+
+生成代码前建议同时读取：
+
+- `packages/ui-core/components.manifest.json`
+- `packages/ui-core/src/components/BaseEChart/BaseEChart.types.ts`
+- 本 README 的 `Props / Events / Expose` 部分

package/src/components/BaseEChart/index.d.ts

@@ -0,0 +1,3 @@
+import BaseEChart from './BaseEChart.vue';
+export default BaseEChart;
+export type { BaseEChartExpose, BaseEChartProps } from './BaseEChart.types';

package/src/components/BaseExportButton/BaseExportButton.types.d.ts

@@ -0,0 +1,21 @@
+import type { ExcelExportOptions } from '../../excel/exportExcel';
+export interface ExportResponseHeaders {
+    [key: string]: string | undefined;
+}
+export interface ExportResponseLike {
+    data: Blob | BlobPart | ArrayBuffer;
+    headers?: ExportResponseHeaders;
+}
+export type ExportRequestHandler = () => Promise<ExportResponseLike>;
+export type ExportMode = 'excel' | 'request' | 'none' | 'invalid';
+export type ExportBeforeHandler = () => boolean | void | Promise<boolean | void>;
+export interface ExportSuccessPayload {
+    mode: Exclude<ExportMode, 'none' | 'invalid'>;
+    fileName?: string;
+}
+export interface BaseExportExcelConfig<Row = Record<string, any>> {
+    excelOptions: ExcelExportOptions<Row>;
+}
+export interface BaseExportRequestConfig {
+    requestHandler: ExportRequestHandler;
+}

package/src/components/BaseExportButton/BaseExportButton.utils.d.ts

@@ -0,0 +1,4 @@
+import type { ExportResponseLike } from './BaseExportButton.types';
+export declare function extractFileNameFromDisposition(contentDisposition?: string): string;
+export declare function normalizeExportFileName(fileName?: string): string;
+export declare function downloadExportResponse(response: ExportResponseLike, fallbackFileName?: string): string;

package/src/components/BaseExportButton/BaseExportButton.vue.d.ts

@@ -0,0 +1,128 @@
+import type { PropType } from 'vue';
+import { type ExcelExportOptions } from '../../excel/exportExcel';
+import type { ExportBeforeHandler, ExportRequestHandler, ExportSuccessPayload } from './BaseExportButton.types';
+declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+        default: string;
+    };
+    type: {
+        type: PropType<"" | "success" | "warning" | "info" | "danger" | "primary">;
+        default: string;
+    };
+    size: {
+        type: PropType<"small" | "default" | "large">;
+        default: string;
+    };
+    plain: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    link: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    text: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    fileName: {
+        type: StringConstructor;
+        default: string;
+    };
+    excelOptions: PropType<ExcelExportOptions<Record<string, any>>>;
+    requestHandler: PropType<ExportRequestHandler>;
+    beforeExport: PropType<ExportBeforeHandler>;
+    successMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    errorMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    autoMessage: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    start: () => void;
+    success: (payload: ExportSuccessPayload) => void;
+    error: (error: unknown) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+        default: string;
+    };
+    type: {
+        type: PropType<"" | "success" | "warning" | "info" | "danger" | "primary">;
+        default: string;
+    };
+    size: {
+        type: PropType<"small" | "default" | "large">;
+        default: string;
+    };
+    plain: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    link: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    text: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    fileName: {
+        type: StringConstructor;
+        default: string;
+    };
+    excelOptions: PropType<ExcelExportOptions<Record<string, any>>>;
+    requestHandler: PropType<ExportRequestHandler>;
+    beforeExport: PropType<ExportBeforeHandler>;
+    successMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    errorMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    autoMessage: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onError?: ((error: unknown) => any) | undefined;
+    onSuccess?: ((payload: ExportSuccessPayload) => any) | undefined;
+    onStart?: (() => any) | undefined;
+}>, {
+    label: string;
+    link: boolean;
+    text: boolean;
+    type: "" | "success" | "warning" | "info" | "danger" | "primary";
+    disabled: boolean;
+    size: "small" | "default" | "large";
+    fileName: string;
+    plain: boolean;
+    successMessage: string;
+    errorMessage: string;
+    autoMessage: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>, {
+    default?(_: {}): any;
+}>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/src/components/BaseExportButton/README.md

@@ -119,3 +119,37 @@ const requestHandler = async () => {
 ## 相关能力
 
 - 工具函数：`@hbdlzy/ui-core` 中的 `exportExcel`
+
+## AI 使用指引
+
+AI 在生成导出入口时，应优先使用 `BaseExportButton` 或 `exportExcel`，不要在每个页面重复写导出按钮 loading、二进制下载、成功失败提示和前端 Excel 生成逻辑。
+
+推荐优先从统一入口导入：
+
+```ts
+import { BaseExportButton, type ExcelExportOptions } from '@hbdlzy/ui'
+```
+
+如果当前只安装了核心包，也可以从 `@hbdlzy/ui-core` 导入。
+
+AI 生成代码时按下面顺序判断：
+
+1. 前端已有完整表格数据时，优先使用 `excelOptions`
+2. 后端返回文件流时，优先使用 `requestHandler + fileName`
+3. 导出前需要校验筛选条件时，使用 `beforeExport`
+4. 页面需要感知结果时，监听 `start`、`success`、`error`
+5. 只需要工具函数而不是按钮时，直接使用 `exportExcel`
+
+AI 不应该做这些事：
+
+- 不要同时传 `excelOptions` 和 `requestHandler`
+- 不要在页面里重复写 `Blob`、`URL.createObjectURL`、临时 `a` 标签下载逻辑
+- 不要在多个页面复制同一套导出 loading 和消息提示
+- 不要把业务查询流程塞进组件，查询参数应由页面层准备好后再触发导出
+
+生成代码前建议同时读取：
+
+- `packages/ui-core/components.manifest.json`
+- `packages/ui-core/src/components/BaseExportButton/BaseExportButton.types.ts`
+- `packages/ui-core/src/excel/exportExcel.ts`
+- 本 README 的 `Props / Events / 约束` 部分

package/src/components/BaseExportButton/index.d.ts

@@ -0,0 +1,5 @@
+import BaseExportButton from './BaseExportButton.vue';
+export { BaseExportButton };
+export { downloadExportResponse, extractFileNameFromDisposition, normalizeExportFileName } from './BaseExportButton.utils';
+export type { BaseExportExcelConfig, BaseExportRequestConfig, ExportBeforeHandler, ExportMode, ExportRequestHandler, ExportResponseHeaders, ExportResponseLike, ExportSuccessPayload } from './BaseExportButton.types';
+export default BaseExportButton;