@manohub/ui 0.6.0

package/dist/components/query-state/index.d.ts

@@ -0,0 +1,207 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+/** 三态种类（插画 / 操作区插槽会收到它，便于按状态给不同内容） */
+export type QueryStateKind = 'empty' | 'error';
+export interface QueryStateProps {
+    /** 加载中 → 骨架屏 */
+    loading?: boolean;
+    /** 错误态（truthy 即触发） */
+    error?: unknown;
+    /** 空态：true 用默认文案，string 作为空态标题 */
+    empty?: boolean | string;
+    /** 空态副文案 */
+    emptyDescription?: string;
+    /** 错误态标题（默认「加载失败」） */
+    errorTitle?: string;
+    /** 错误态副文案 */
+    errorDescription?: string;
+    /** 自定义插画资源 URL（不传用内建插画；整幅自定义图形请用 `illustration` 插槽） */
+    illustration?: string;
+    /**
+     * 空态操作按钮（如「新建」）；与 `onEmptyAction` 同时传才渲染。
+     *
+     * 按钮就是本包的 `Button`（`variant="primary"`）—— 空态 / 错误态的主操作与全站按钮同族，
+     * 应用**不需要**再注入任何东西；换外观走主题令牌，换结构走 `actions` 插槽。
+     */
+    emptyActionText?: string;
+    onEmptyAction?: () => void;
+    /** 错误态操作按钮（如「重试」）；与 `onErrorAction` 同时传才渲染（同上） */
+    errorActionText?: string;
+    onErrorAction?: () => void;
+    /** 骨架屏条数 */
+    skeletonRows?: number;
+    /** 骨架屏条高（px） */
+    skeletonRowHeight?: number;
+}
+/**
+ * loading / empty / error 三态容器（自建，替代各 app 手拼的 empty-state + skeleton）。
+ *
+ * 三态互斥，优先级 loading > error > empty > default 插槽。
+ *
+ * ## 视觉构成（三态非加载态一致）
+ *
+ * **插画 → 主文案 → 副文案 → 操作区**，整块垂直居中、留白由令牌给（`.mh-state`）。
+ * 插画默认取内建件（设计交付的「空状态」/「错误」两张图，原样内联在 `utils/state-illustration.ts`），
+ * 可用 `illustration` 属性换成图片资源、或用 `illustration` 插槽整幅自定义；操作区同理有 `actions` 插槽。
+ *
+ * 文案 props 可覆盖（i18n 由消费方传 t() 结果；本包不内置文案）。
+ *
+ * @example 空态带 CTA、错误态带重试
+ * <QueryState
+ *   loading={isLoading}
+ *   error={loadError.value}
+ *   errorActionText={t('common.retry')}
+ *   onErrorAction={() => reload()}
+ *   empty={topics.length === 0}
+ *   empty={t('topic.empty')}
+ *   emptyDescription={t('topic.emptyDescription')}
+ *   emptyActionText={t('topic.create')}
+ *   onEmptyAction={() => openCreate()}>
+ *   <TopicGrid topics={topics} />
+ * </QueryState>
+ */
+export declare const QueryState: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    empty: {
+        type: PropType<boolean | string>;
+        default: boolean;
+    };
+    emptyDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    errorTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    errorDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    illustration: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** 插画宽度（数字按 px；高度按比例自适应）。缺省用样式层默认宽度 */
+    illustrationSize: {
+        type: PropType<number | string>;
+        default: undefined;
+    };
+    emptyActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onEmptyAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    errorActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onErrorAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    skeletonRows: {
+        type: NumberConstructor;
+        default: number;
+    };
+    skeletonRowHeight: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>, () => string | number | boolean | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | import("vue").VNodeArrayChildren | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    empty: {
+        type: PropType<boolean | string>;
+        default: boolean;
+    };
+    emptyDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    errorTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    errorDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    illustration: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** 插画宽度（数字按 px；高度按比例自适应）。缺省用样式层默认宽度 */
+    illustrationSize: {
+        type: PropType<number | string>;
+        default: undefined;
+    };
+    emptyActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onEmptyAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    errorActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onErrorAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    skeletonRows: {
+        type: NumberConstructor;
+        default: number;
+    };
+    skeletonRowHeight: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>> & Readonly<{}>, {
+    error: any;
+    loading: boolean;
+    empty: string | boolean;
+    emptyDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    illustration: string;
+    illustrationSize: string | number;
+    emptyActionText: string;
+    onEmptyAction: () => void;
+    errorActionText: string;
+    onErrorAction: () => void;
+    skeletonRows: number;
+    skeletonRowHeight: number;
+}, SlotsType<{
+    default?: () => VNodeChild;
+    empty?: () => VNodeChild;
+    error?: () => VNodeChild;
+    /** 自定义插画；入参为当前状态种类 */
+    illustration?: (ctx: {
+        kind: QueryStateKind;
+    }) => VNodeChild;
+    /** 自定义操作区（按钮组）；不传则按 *ActionText / on*Action 渲染单个主按钮 */
+    actions?: (ctx: {
+        kind: QueryStateKind;
+    }) => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/query-state/index.js

@@ -0,0 +1,181 @@
+import { defineComponent, createVNode, Fragment } from "vue";
+import { Button } from "../button/index.js";
+import { STATE_ILLUSTRATION_ERROR_SVG, STATE_ILLUSTRATION_EMPTY_SVG } from "../../utils/state-illustration.js";
+const BUILT_IN_ILLUSTRATION = {
+  empty: STATE_ILLUSTRATION_EMPTY_SVG,
+  error: STATE_ILLUSTRATION_ERROR_SVG
+};
+const QueryState = /* @__PURE__ */ defineComponent({
+  name: "QueryState",
+  inheritAttrs: false,
+  props: {
+    loading: {
+      type: Boolean,
+      default: false
+    },
+    /*
+     * truthy 即触发错误态；type 用构造器数组承载 unknown（`type: null` 在 vue-tsc 下被推断为 undefined）。
+     * **`String` 必须排在 `Boolean` 前**：否则 Vue 的布尔转换会把空字符串 `''` 转成 `true`，
+     * 成功态（`error={''}`）也会被判成错误态。
+     */
+    error: {
+      type: [String, Boolean, Object, Number, Array],
+      default: void 0
+    },
+    empty: {
+      type: [Boolean, String],
+      default: false
+    },
+    emptyDescription: {
+      type: String,
+      default: void 0
+    },
+    errorTitle: {
+      type: String,
+      default: "加载失败"
+    },
+    errorDescription: {
+      type: String,
+      default: void 0
+    },
+    illustration: {
+      type: String,
+      default: void 0
+    },
+    /** 插画宽度（数字按 px；高度按比例自适应）。缺省用样式层默认宽度 */
+    illustrationSize: {
+      type: [Number, String],
+      default: void 0
+    },
+    emptyActionText: {
+      type: String,
+      default: void 0
+    },
+    onEmptyAction: {
+      type: Function,
+      default: void 0
+    },
+    errorActionText: {
+      type: String,
+      default: void 0
+    },
+    onErrorAction: {
+      type: Function,
+      default: void 0
+    },
+    skeletonRows: {
+      type: Number,
+      default: 6
+    },
+    skeletonRowHeight: {
+      type: Number,
+      default: 40
+    }
+  },
+  slots: Object,
+  setup(props, {
+    slots,
+    attrs
+  }) {
+    const illustrationWidth = () => props.illustrationSize === void 0 ? void 0 : {
+      width: typeof props.illustrationSize === "number" ? `${props.illustrationSize}px` : props.illustrationSize,
+      height: "auto"
+    };
+    const renderIllustration = (kind) => {
+      if (slots.illustration) {
+        return slots.illustration({
+          kind
+        });
+      }
+      if (props.illustration) {
+        return createVNode("img", {
+          "class": "mh-state-illustration",
+          "src": props.illustration,
+          "alt": "",
+          "style": illustrationWidth()
+        }, null);
+      }
+      return createVNode("span", {
+        "class": "mh-state-illustration",
+        "style": illustrationWidth(),
+        "aria-hidden": "true",
+        "innerHTML": BUILT_IN_ILLUSTRATION[kind]
+      }, null);
+    };
+    const renderActions = (kind, actionText, onAction) => {
+      if (slots.actions) {
+        return slots.actions({
+          kind
+        });
+      }
+      if (!actionText || !onAction) {
+        return null;
+      }
+      return (
+        // 文案走函数 slot 传入而非直接写子节点：直传字符串会触发 Vue 的
+        // 「Non-function value encountered for default slot」告警（同 Panel 的处理）
+        createVNode(Button, {
+          "variant": "primary",
+          "onClick": onAction
+        }, {
+          default: () => actionText
+        })
+      );
+    };
+    const renderState = (config) => {
+      const actions = renderActions(config.kind, config.actionText, config.onAction);
+      return createVNode("div", {
+        "class": "mh-state",
+        "style": attrs.style
+      }, [config.slotFn ? config.slotFn() : createVNode(Fragment, null, [renderIllustration(config.kind), createVNode("div", {
+        "class": "mh-state-title"
+      }, [config.title]), config.description ? createVNode("div", {
+        "class": "mh-state-description"
+      }, [config.description]) : null, actions ? createVNode("div", {
+        "class": "mh-state-actions"
+      }, [actions]) : null])]);
+    };
+    return () => {
+      if (props.loading) {
+        return createVNode("div", {
+          "class": "mh-state"
+        }, [createVNode("div", {
+          "class": "mh-state-skeletons"
+        }, [Array.from({
+          length: props.skeletonRows
+        }).map((_, i) => createVNode("div", {
+          "key": i,
+          "class": "mh-skeleton mh-skeleton--block",
+          "style": {
+            height: `${props.skeletonRowHeight}px`
+          }
+        }, null))])]);
+      }
+      if (props.error) {
+        return renderState({
+          kind: "error",
+          title: props.errorTitle,
+          description: props.errorDescription,
+          slotFn: slots.error,
+          actionText: props.errorActionText,
+          onAction: props.onErrorAction
+        });
+      }
+      if (props.empty) {
+        const title = typeof props.empty === "string" ? props.empty : "暂无数据";
+        return renderState({
+          kind: "empty",
+          title,
+          description: props.emptyDescription,
+          slotFn: slots.empty,
+          actionText: props.emptyActionText,
+          onAction: props.onEmptyAction
+        });
+      }
+      return slots.default?.() ?? null;
+    };
+  }
+});
+export {
+  QueryState
+};