@manohub/ui 0.6.0

package/dist/components/list-view/index.d.ts

@@ -0,0 +1,563 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+/** 卡片右上状态胶囊的语义档（取色走令牌，与 `Badge` 同源词表） */
+export type ListViewStatusTone = 'primary' | 'success' | 'warning' | 'error' | 'neutral';
+export interface ListViewStatus {
+    /** 胶囊文案 */
+    label: string;
+    /** 语义档：`primary`（默认）/ `success` / `warning` / `error` / `neutral` */
+    tone?: ListViewStatusTone;
+    /** 文案前挂状态圆点（在线 / 离线这类点状状态） */
+    dot?: boolean;
+}
+/**
+ * 卡片网格列表：**容器自适应列数 + 三态内建**。
+ *
+ * ## 列数（响应式口径）
+ *
+ * 列数由**容器宽度**决定，不跟视口断点：`repeat(auto-fill, minmax(min(--mh-list-view-min, 100%), 1fr))`
+ * —— 栏宽变窄自动减列（窄到放不下时回落单列），栏内再嵌组件也不会因为「视口没变」而排错列数。
+ * `minItemWidth` 是唯一的下限入口（缺省 `--ui-grid-column-min`）。
+ *
+ * ## 三态
+ *
+ * - `loading` → **骨架卡网格**（与卡片同尺寸占位，避免加载完成时高度跳动）；
+ * - `error` / `empty` → 委托 `QueryState`（口径同 CONTRACT §4.6：**错误不得塞进空态**，
+ *   两条各自的恢复入口由 `errorActionText` / `emptyActionText` 给）。
+ *
+ * 无数据或失败时消费方**不要渲染分页**（分页归属见 CONTRACT §4.17）。
+ *
+ * ## 卡片外观
+ *
+ * 列表项一律用 `ListView.CardItem`（内部以 `Card interactive` 为壳），消费方不得自绘卡片外观。
+ *
+ * @example 服务卡片列表（三态；分页由承载它的容器给）
+ * <ListView
+ *   minItemWidth={320}
+ *   loading={query.isPending.value}
+ *   error={query.isError.value}
+ *   errorActionText="重试"
+ *   onErrorAction={() => void query.refetch()}
+ *   // 空态：传字符串即空态标题（传 true 会用内置的「暂无数据」）
+ *   empty={items.value.length === 0 ? '暂无服务' : false}>
+ *   {items.value.map((item) => (
+ *     <ListView.CardItem key={item.id} title={item.name} description={item.desc}
+ *       status={{ label: '在线', tone: 'success', dot: true }}
+ *       onClick={() => openDetail(item.id)}
+ *       actions={() => <Button title="编辑" onClick={() => openEdit(item.id)} />} />
+ *   ))}
+ * </ListView>
+ */
+export interface ListViewProps {
+    /**
+     * 卡片最小宽度（px）：容器自适应换列的**唯一**下限（`auto-fill`，窄容器自动减列，
+     * 不依赖视口断点）。缺省回落 `--ui-grid-column-min`（260）。
+     *
+     * 传了它只下发一个自定义属性 `--mh-list-view-min`，列公式仍在 CSS 内（与 `Tree` 缩进同一手法）。
+     */
+    minItemWidth?: number;
+    /** 加载态：渲染**骨架卡**网格（与卡片同尺寸，避免高度跳动） */
+    loading?: boolean;
+    /**
+     * 错误态（truthy 即触发）。构造器顺序同 `表格.error` / `QueryState.error`：
+     * **`String` 必须排在 `Boolean` 前** —— 顺序写反时空字符串会被判成错误态。
+     */
+    error?: unknown;
+    /** 空态：`true` 用默认文案，`string` 作为空态标题 */
+    empty?: boolean | string;
+    /** 空态副文案 */
+    emptyDescription?: string;
+    /** 空态操作按钮（如「新建」）；与 `onEmptyAction` 同时传才渲染 */
+    emptyActionText?: string;
+    onEmptyAction?: () => void;
+    /** 错误态标题（默认「加载失败」） */
+    errorTitle?: string;
+    /** 错误态副文案 */
+    errorDescription?: string;
+    /** 错误态操作按钮（如「重试」）；与 `onErrorAction` 同时传才渲染 */
+    errorActionText?: string;
+    onErrorAction?: () => void;
+    /** 骨架卡数量（缺省 8，与常见一屏卡片数对齐） */
+    skeletonCount?: number;
+}
+/**
+ * 列表卡片项：卡片的**结构化形态**（图标 / 标题 / 副标题 / 描述 / 标签 / 状态胶囊 / 统计 / 操作位）。
+ *
+ * 以 `Card interactive` 为壳，卡片外观与悬浮反馈都来自它；本件只管卡片**内部**的排版与几何
+ * （最小高 144、图标 36、标题 16/600、描述两行截断、尾部贴底、胶囊与标签片），
+ * 几何来源同 `Card`（portal 技能市场卡片实测）。
+ *
+ * 三处「有意为之」：
+ * 1. **操作位默认隐藏**（`opacity: 0`），卡片悬浮或卡内获得焦点时显形；触屏（无 hover 能力）恒显形 ——
+ *    因此按钮始终可聚焦、可点，只是平时不抢视觉；
+ * 2. **操作位点击不冒泡**：卡内按钮（编辑 / 删除）不会顺带触发整卡的 `onClick`（打开详情）；
+ * 3. **状态胶囊与标签片由本件自绘**，不复用 `Badge`：原型是**全圆角胶囊**与无最小宽的标签片，
+ *    而 `Badge` 的几何是方角 + 最小宽（给徽标列宽用的），套进来会改变原型几何。
+ *
+ * @example 带状态、标签与操作位的卡片项
+ * <ListView.CardItem
+ *   icon={resolveIcon(item.icon)}
+ *   title={item.name}
+ *   subtitle={`V${item.version}`}
+ *   description={item.desc}
+ *   tags={[item.topic, item.domain]}
+ *   status={{ label: '在线', tone: 'success', dot: true }}
+ *   extra={() => <><Icon name="download" size={14} />{item.downloadCount}</>}
+ *   actions={() => <Button title="编辑" onClick={() => openEdit(item.id)} />}
+ *   onClick={() => openDetail(item.id)} />
+ */
+export interface ListViewCardItemProps {
+    /** 图标：图片地址（`<img>`，`alt` 走空串——名称已由标题承担）或自定义节点 / 返回节点的函数 */
+    icon?: string | (() => VNodeChild);
+    /** 卡片标题（必填；单行省略） */
+    title: string;
+    /** 副标题（如版本号），排在标题下方一行 */
+    subtitle?: string;
+    /** 描述：两行截断（超长文案请由消费方用 `Tooltip` 补全） */
+    description?: string;
+    /** 标签组（主色弱底 + 主色字的小圆角片），排在尾部左侧 */
+    tags?: string[];
+    /** 右上状态胶囊 */
+    status?: ListViewStatus;
+    /** 整卡点击（打开详情 / 抽屉）；尾部操作位的点击**不会**冒泡到这里 */
+    onClick?: () => void;
+}
+/** 列表卡片项（见 `ListView.CardItem`）：图标 / 标题 / 副标题 / 描述 / 标签 / 状态胶囊 / 操作位 */
+export declare const ListViewCardItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    icon: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    title: {
+        type: StringConstructor;
+        required: true;
+    };
+    subtitle: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    tags: {
+        type: PropType<string[]>;
+        default: undefined;
+    };
+    status: {
+        type: PropType<ListViewStatus>;
+        default: undefined;
+    };
+    /** 尾部左侧自定义内容（如状态徽标）；与 `footer` 插槽等价 */
+    footer: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 尾部右侧统计（如下载量）；渲染在操作位之前 */
+    extra: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 操作位：**默认隐藏、卡片悬浮（或卡内获得焦点）时显形**；点击不冒泡到整卡 */
+    actions: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    onClick: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    icon: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    title: {
+        type: StringConstructor;
+        required: true;
+    };
+    subtitle: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    tags: {
+        type: PropType<string[]>;
+        default: undefined;
+    };
+    status: {
+        type: PropType<ListViewStatus>;
+        default: undefined;
+    };
+    /** 尾部左侧自定义内容（如状态徽标）；与 `footer` 插槽等价 */
+    footer: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 尾部右侧统计（如下载量）；渲染在操作位之前 */
+    extra: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 操作位：**默认隐藏、卡片悬浮（或卡内获得焦点）时显形**；点击不冒泡到整卡 */
+    actions: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    onClick: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    icon: any;
+    extra: any;
+    footer: any;
+    onClick: () => void;
+    actions: any;
+    subtitle: string;
+    status: ListViewStatus;
+    description: string;
+    tags: string[];
+}, SlotsType<{
+    default?: () => VNodeChild;
+    footer?: () => VNodeChild;
+    extra?: () => VNodeChild;
+    actions?: () => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 复合件入口：`ListView` + `ListView.CardItem`
+ * （与 `Panel` 同款 `Object.assign` 复合写法；成员不平级导出）
+ */
+export declare const ListView: {
+    new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
+        minItemWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 固定列数（>0 时不再按容器宽度自适应；窄屏要锁死列数时用） */
+        columns: {
+            type: NumberConstructor;
+            default: number;
+        };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        empty: {
+            type: PropType<boolean | string>;
+            default: boolean;
+        };
+        emptyDescription: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        emptyActionText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        onEmptyAction: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+        errorTitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        errorDescription: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        errorActionText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        onErrorAction: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+        skeletonCount: {
+            type: NumberConstructor;
+            default: number;
+        };
+    }>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {
+        error: any;
+        loading: boolean;
+        empty: string | boolean;
+        emptyDescription: string;
+        errorTitle: string;
+        errorDescription: string;
+        emptyActionText: string;
+        onEmptyAction: () => void;
+        errorActionText: string;
+        onErrorAction: () => void;
+        columns: number;
+        minItemWidth: number;
+        skeletonCount: number;
+    }, true, {}, SlotsType<{
+        default?: () => VNodeChild;
+    }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<import("vue").ExtractPropTypes<{
+        minItemWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 固定列数（>0 时不再按容器宽度自适应；窄屏要锁死列数时用） */
+        columns: {
+            type: NumberConstructor;
+            default: number;
+        };
+        loading: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        empty: {
+            type: PropType<boolean | string>;
+            default: boolean;
+        };
+        emptyDescription: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        emptyActionText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        onEmptyAction: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+        errorTitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        errorDescription: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        errorActionText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        onErrorAction: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+        skeletonCount: {
+            type: NumberConstructor;
+            default: number;
+        };
+    }>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
+        error: any;
+        loading: boolean;
+        empty: string | boolean;
+        emptyDescription: string;
+        errorTitle: string;
+        errorDescription: string;
+        emptyActionText: string;
+        onEmptyAction: () => void;
+        errorActionText: string;
+        onErrorAction: () => void;
+        columns: number;
+        minItemWidth: number;
+        skeletonCount: number;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<{
+    minItemWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 固定列数（>0 时不再按容器宽度自适应；窄屏要锁死列数时用） */
+    columns: {
+        type: NumberConstructor;
+        default: number;
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    empty: {
+        type: PropType<boolean | string>;
+        default: boolean;
+    };
+    emptyDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    emptyActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onEmptyAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    errorTitle: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    errorDescription: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    errorActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onErrorAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    skeletonCount: {
+        type: NumberConstructor;
+        default: number;
+    };
+}>> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, {
+    error: any;
+    loading: boolean;
+    empty: string | boolean;
+    emptyDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    emptyActionText: string;
+    onEmptyAction: () => void;
+    errorActionText: string;
+    onErrorAction: () => void;
+    columns: number;
+    minItemWidth: number;
+    skeletonCount: number;
+}, {}, string, SlotsType<{
+    default?: () => VNodeChild;
+}>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
+    CardItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        icon: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        title: {
+            type: StringConstructor;
+            required: true;
+        };
+        subtitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        tags: {
+            type: PropType<string[]>;
+            default: undefined;
+        };
+        status: {
+            type: PropType<ListViewStatus>;
+            default: undefined;
+        };
+        /** 尾部左侧自定义内容（如状态徽标）；与 `footer` 插槽等价 */
+        footer: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        /** 尾部右侧统计（如下载量）；渲染在操作位之前 */
+        extra: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        /** 操作位：**默认隐藏、卡片悬浮（或卡内获得焦点）时显形**；点击不冒泡到整卡 */
+        actions: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        onClick: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+    }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        icon: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        title: {
+            type: StringConstructor;
+            required: true;
+        };
+        subtitle: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        tags: {
+            type: PropType<string[]>;
+            default: undefined;
+        };
+        status: {
+            type: PropType<ListViewStatus>;
+            default: undefined;
+        };
+        /** 尾部左侧自定义内容（如状态徽标）；与 `footer` 插槽等价 */
+        footer: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        /** 尾部右侧统计（如下载量）；渲染在操作位之前 */
+        extra: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        /** 操作位：**默认隐藏、卡片悬浮（或卡内获得焦点）时显形**；点击不冒泡到整卡 */
+        actions: {
+            type: PropType<any>;
+            default: undefined;
+        };
+        onClick: {
+            type: PropType<() => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{}>, {
+        icon: any;
+        extra: any;
+        footer: any;
+        onClick: () => void;
+        actions: any;
+        subtitle: string;
+        status: ListViewStatus;
+        description: string;
+        tags: string[];
+    }, SlotsType<{
+        default?: () => VNodeChild;
+        footer?: () => VNodeChild;
+        extra?: () => VNodeChild;
+        actions?: () => VNodeChild;
+    }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+export type ListViewCompound = typeof ListView;