@manohub/ui 0.6.0

package/dist/components/filter/index.d.ts

@@ -0,0 +1,391 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+/**
+ * 条件值：单值（文本 / 单选）或数组（多选）。数字与字符串同等对待（取值原样透传）。
+ */
+export type FilterValue = string | number | Array<string | number>;
+/** 条件快照：`条件名 → 值`（未选条件的值为空串，语义是「不过滤」） */
+export type FilterValues = Record<string, FilterValue>;
+/**
+ * 「全部」哨兵：选项值等于它即「不过滤」。
+ *
+ * 与既有查询方案（骨架层的筛选适配件）同词，便于迁移时**选项表原样搬运**；
+ * 自绘场景更推荐直接用 `placeholder="全部"` 表达未选（本包 `Select` 把空串视为未选中，
+ * 会显示占位文案）—— 两条路子的最终视觉一致，见 `docs/components/filter.md`。
+ */
+export declare const FILTER_ALL = "all";
+/**
+ * 筛选字段的作用域插槽：控件由消费方渲染，本件交出**归一后**的当前值。
+ *
+ * 与 `Form.Item` 的作用域同形，差别只在归一：筛选语义里「未选」一律是空串
+ * （`'all'` 哨兵 / `null` / 空数组都归到空串），于是消费方直接把 `value` 绑给控件即可，
+ * 不必自己处理哨兵——这是 `Filter.Item` 相对 `Form.Item` 唯一的增量。
+ */
+export interface FilterItemSlotScope {
+    /** 当前条件值（已归一：空串 = 未选） */
+    value: FilterValue;
+    /** 写入该条件（写入前归一） */
+    setValue: (value: FilterValue | undefined | null) => void;
+    /** 清空该条件（等价于 `setValue('')`） */
+    clear: () => void;
+}
+/**
+ * 归一（读与写**同一份实现**，两处不各写一套）：
+ * - `'all'`（哨兵）/ `''` / `null` / `undefined` → `''`（= 不过滤）；
+ * - 数组逐项归一后去空，全空 → `''`；**只剩一项仍是数组**（多选值的类型不降级成标量）；
+ * - 数字原样（`0` 是有效值，不是「空」）；
+ * - 其余原样（不做 trim：归一不负责改写用户输入）。
+ */
+export declare function normalizeFilterValue(value: FilterValue | null | undefined): FilterValue;
+export interface FilterProps {
+    /** 筛选条标题（透传给 `Form.Header`） */
+    title?: string;
+    /** 标题下的说明小字（透传给 `Form.Header`） */
+    description?: string;
+    /** label 列宽（px）；缺省 `56`（见 `FILTER_LABEL_WIDTH`），透传给 `Form` */
+    labelWidth?: number;
+    /** 受控条件快照（`条件名 → 值`）；不传即非受控（由 `defaultValue` 起） */
+    modelValue?: FilterValues;
+    /** 非受控初值；其中的键会一并成为快照的键 */
+    defaultValue?: FilterValues;
+    /** 「筛选」按钮文案 */
+    queryText?: string;
+    /** 「重置」按钮文案 */
+    resetText?: string;
+    /** 是否渲染「重置」按钮（缺省渲染） */
+    showReset?: boolean;
+    /** 条件值变化（快照已归一） */
+    onChange?: (values: FilterValues) => void;
+    /** 「筛选」按钮 / 字段区回车（回车只作用于输入框，且不认浮层里的输入） */
+    onQuery?: (values: FilterValues) => void;
+    /** 「重置」按钮：全部条件清空（**不再触发 `onChange`**，避免与重置回调双触发） */
+    onReset?: (values: FilterValues) => void;
+}
+export interface FilterItemProps {
+    /** 条件名（必填）：快照的键，也是后端查询参数的键（就是 `Form.Item` 的 `name`） */
+    code: string;
+    /** 字段名（渲染在控件左侧的 label） */
+    label?: string;
+    /** 必填标记（透传 `Form.Item`，星号画在 label 文字**之后**） */
+    required?: boolean;
+    /** 校验错误文案（透传 `Form.Item`：非空即进 invalid 态，排在控件下方） */
+    error?: string;
+    /** 控件下方提示（透传 `Form.Item`） */
+    hint?: string;
+}
+/**
+ * 筛选字段（`Filter` 的子件）：**`Form.Item` 的薄包装**。
+ *
+ * 一字段一个子件，`code` 就是 `Form.Item` 的 `name`（值仍然存在 `Form` 里，本件不另起一套存储）；
+ * 增量只有一处 —— **读写的值都是归一后的**（`'all'` / 空数组 / 空值 → 空串），
+ * 于是消费方直接把 `value` 绑给控件，不必自己处理哨兵。
+ *
+ * 字段宽**自适应**：容器够宽一行排下，窄了整体换行（列距 24 / 行距 16）。
+ *
+ * @example
+ * <Filter.Item code="status" label="授权状态">
+ *   {{ default: ({ value, setValue }) => (
+ *       <Select options={statusOptions} modelValue={String(value)} placeholder="全部" onChange={setValue} />
+ *     ) }}
+ * </Filter.Item>
+ */
+export declare const FilterItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    code: {
+        type: StringConstructor;
+        required: true;
+    };
+    label: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    required: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: StringConstructor;
+        default: string;
+    };
+    hint: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    code: {
+        type: StringConstructor;
+        required: true;
+    };
+    label: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    required: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: StringConstructor;
+        default: string;
+    };
+    hint: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    label: string;
+    error: string;
+    required: boolean;
+    hint: string;
+}, SlotsType<{
+    default?: (scope: FilterItemSlotScope) => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** 复合件入口：`Filter` + `Filter.Item`（与 `Form` / `Page` 同款 Object.assign 写法，成员不平级导出） */
+export declare const Filter: {
+    new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
+        title: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        modelValue: {
+            type: PropType<FilterValues>;
+            default: undefined;
+        };
+        defaultValue: {
+            type: PropType<FilterValues>;
+            default: undefined;
+        };
+        queryText: {
+            type: StringConstructor;
+            default: string;
+        };
+        resetText: {
+            type: StringConstructor;
+            default: string;
+        };
+        showReset: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        onChange: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+        onQuery: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+        onReset: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:modelValue"?: ((values: FilterValues) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+        'update:modelValue': (values: FilterValues) => true;
+    }, import("vue").PublicProps, {
+        title: string;
+        onChange: (values: FilterValues) => void;
+        onReset: (values: FilterValues) => void;
+        defaultValue: FilterValues;
+        modelValue: FilterValues;
+        description: string;
+        labelWidth: number;
+        queryText: string;
+        resetText: string;
+        showReset: boolean;
+        onQuery: (values: FilterValues) => void;
+    }, 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<{
+        title: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        modelValue: {
+            type: PropType<FilterValues>;
+            default: undefined;
+        };
+        defaultValue: {
+            type: PropType<FilterValues>;
+            default: undefined;
+        };
+        queryText: {
+            type: StringConstructor;
+            default: string;
+        };
+        resetText: {
+            type: StringConstructor;
+            default: string;
+        };
+        showReset: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        onChange: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+        onQuery: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+        onReset: {
+            type: PropType<(values: FilterValues) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:modelValue"?: ((values: FilterValues) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
+        title: string;
+        onChange: (values: FilterValues) => void;
+        onReset: (values: FilterValues) => void;
+        defaultValue: FilterValues;
+        modelValue: FilterValues;
+        description: string;
+        labelWidth: number;
+        queryText: string;
+        resetText: string;
+        showReset: boolean;
+        onQuery: (values: FilterValues) => void;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<{
+    title: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    labelWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    modelValue: {
+        type: PropType<FilterValues>;
+        default: undefined;
+    };
+    defaultValue: {
+        type: PropType<FilterValues>;
+        default: undefined;
+    };
+    queryText: {
+        type: StringConstructor;
+        default: string;
+    };
+    resetText: {
+        type: StringConstructor;
+        default: string;
+    };
+    showReset: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    onChange: {
+        type: PropType<(values: FilterValues) => void>;
+        default: undefined;
+    };
+    onQuery: {
+        type: PropType<(values: FilterValues) => void>;
+        default: undefined;
+    };
+    onReset: {
+        type: PropType<(values: FilterValues) => void>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onUpdate:modelValue"?: ((values: FilterValues) => any) | undefined;
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    'update:modelValue': (values: FilterValues) => true;
+}, string, {
+    title: string;
+    onChange: (values: FilterValues) => void;
+    onReset: (values: FilterValues) => void;
+    defaultValue: FilterValues;
+    modelValue: FilterValues;
+    description: string;
+    labelWidth: number;
+    queryText: string;
+    resetText: string;
+    showReset: boolean;
+    onQuery: (values: FilterValues) => void;
+}, {}, string, SlotsType<{
+    default?: () => VNodeChild;
+}>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
+    Item: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        code: {
+            type: StringConstructor;
+            required: true;
+        };
+        label: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        required: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            default: string;
+        };
+        hint: {
+            type: StringConstructor;
+            default: string;
+        };
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        code: {
+            type: StringConstructor;
+            required: true;
+        };
+        label: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        required: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            default: string;
+        };
+        hint: {
+            type: StringConstructor;
+            default: string;
+        };
+    }>> & Readonly<{}>, {
+        label: string;
+        error: string;
+        required: boolean;
+        hint: string;
+    }, SlotsType<{
+        default?: (scope: FilterItemSlotScope) => VNodeChild;
+    }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+export type FilterCompound = typeof Filter;

package/dist/components/filter/index.js

@@ -0,0 +1,203 @@
+import { defineComponent, createVNode, ref, h, Fragment } from "vue";
+import { Button } from "../button/index.js";
+import { FormItem, Form } from "../form/index.js";
+const FILTER_ALL = "all";
+const FILTER_LABEL_WIDTH = 68;
+const FILTER_GAP = 16;
+function normalizeFilterValue(value) {
+  if (Array.isArray(value)) {
+    const kept = value.map((item) => normalizeFilterValue(item)).filter((item) => item !== "");
+    return kept.length ? kept : "";
+  }
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "number") return value;
+  return value === "" || value === FILTER_ALL ? "" : value;
+}
+function normalizeValues(values) {
+  const out = {};
+  for (const [code, value] of Object.entries(values ?? {})) {
+    out[code] = normalizeFilterValue(value);
+  }
+  return out;
+}
+const FilterRoot = /* @__PURE__ */ defineComponent({
+  name: "Filter",
+  inheritAttrs: false,
+  props: {
+    title: {
+      type: String,
+      default: void 0
+    },
+    description: {
+      type: String,
+      default: void 0
+    },
+    labelWidth: {
+      type: Number,
+      default: void 0
+    },
+    modelValue: {
+      type: Object,
+      default: void 0
+    },
+    defaultValue: {
+      type: Object,
+      default: void 0
+    },
+    queryText: {
+      type: String,
+      default: "筛选"
+    },
+    resetText: {
+      type: String,
+      default: "重置"
+    },
+    showReset: {
+      type: Boolean,
+      default: true
+    },
+    onChange: {
+      type: Function,
+      default: void 0
+    },
+    onQuery: {
+      type: Function,
+      default: void 0
+    },
+    onReset: {
+      type: Function,
+      default: void 0
+    }
+  },
+  emits: {
+    "update:modelValue": (values) => true
+  },
+  slots: Object,
+  setup(props, {
+    slots,
+    attrs,
+    emit
+  }) {
+    const formRef = ref(null);
+    let clearing = false;
+    const onFormChange = (values) => {
+      if (clearing) return;
+      const snapshot2 = normalizeValues(values);
+      emit("update:modelValue", snapshot2);
+      props.onChange?.(snapshot2);
+    };
+    const snapshot = () => normalizeValues(formRef.value?.getValues());
+    const query = () => props.onQuery?.(snapshot());
+    const reset = () => {
+      clearing = true;
+      const cleared = formRef.value?.clear() ?? {};
+      clearing = false;
+      const next = normalizeValues(cleared);
+      emit("update:modelValue", next);
+      props.onReset?.(next);
+    };
+    const onFieldsKeydown = (event) => {
+      if (event.key !== "Enter" || event.isComposing) return;
+      const target = event.target;
+      if (target?.tagName !== "INPUT" || target.closest("[popover]")) return;
+      event.preventDefault();
+      query();
+    };
+    const renderActions = () => createVNode(Fragment, null, [createVNode(Button, {
+      "variant": "primary",
+      "onClick": query
+    }, {
+      default: () => props.queryText
+    }), props.showReset ? createVNode(Button, {
+      "variant": "secondary",
+      "onClick": reset
+    }, {
+      default: () => props.resetText
+    }) : null]);
+    return () => createVNode(Form, {
+      "ref": formRef,
+      "class": ["mh-filter__form", attrs.class].filter(Boolean).join(" "),
+      "style": attrs.style,
+      "labelWidth": props.labelWidth ?? FILTER_LABEL_WIDTH,
+      "gap": FILTER_GAP,
+      "modelValue": props.modelValue,
+      "defaultValue": props.defaultValue,
+      "onChange": onFormChange
+    }, {
+      default: () => [
+        /* 插槽一律走对象形态：TSX 的 `v-slots={{…}}` 会被当**普通属性**丢掉
+           （见 `list-view/index.tsx` 同款记录），而多子节点直传会触发
+           「Non-function value encountered for default slot」告警（同 `page/index.tsx`）。 */
+        h(Form.Header, {
+          title: props.title,
+          description: props.description
+        }, {
+          extra: renderActions
+        }),
+        // 字段区也用插槽对象形态传子节点：`h()` 的第三参不收 `null`（`slots.default?.()` 的返回可能是 null）
+        h("div", {
+          class: "mh-filter__fields",
+          onKeydown: onFieldsKeydown
+        }, {
+          default: () => slots.default?.()
+        })
+      ]
+    });
+  }
+});
+const FilterItem = /* @__PURE__ */ defineComponent({
+  name: "FilterItem",
+  inheritAttrs: false,
+  props: {
+    code: {
+      type: String,
+      required: true
+    },
+    label: {
+      type: String,
+      default: void 0
+    },
+    required: {
+      type: Boolean,
+      default: false
+    },
+    error: {
+      type: String,
+      default: ""
+    },
+    hint: {
+      type: String,
+      default: ""
+    }
+  },
+  slots: Object,
+  setup(props, {
+    slots,
+    attrs
+  }) {
+    return () => createVNode(FormItem, {
+      "name": props.code,
+      "label": props.label,
+      "required": props.required,
+      "error": props.error,
+      "hint": props.hint,
+      "class": ["mh-filter__item", attrs.class].filter(Boolean).join(" "),
+      "style": attrs.style
+    }, {
+      default: (scope) => slots.default?.({
+        value: normalizeFilterValue(scope.value),
+        setValue: (value) => scope.setValue(normalizeFilterValue(value)),
+        clear: () => scope.setValue("")
+      })
+    });
+  }
+});
+const Filter = Object.assign(FilterRoot, {
+  Item: FilterItem
+});
+export {
+  FILTER_ALL,
+  Filter,
+  FilterItem,
+  normalizeFilterValue
+};