4-10 · 泛型组件全链路：以 select 为样本

<script setup lang="ts" generic="T extends string | number">
import { computed, getCurrentInstance, inject, nextTick, ref, watch } from "vue";
import type { StyleValue } from "vue";
import {
  useConfig,
  useDismissibleLayer,
  useFloatingPanel,
  useListNavigation,
  useNamespace,
  useOverlayStack
} from "xiaoye-primitives";
import XyIcon from "../../icon";
import { formItemKey, formKey } from "../../form/src/context";
import { XyLoadingIndicator, resolveLoadingVisualConfig } from "../../loading/src/shared";
import type { LoadingGlobalConfig } from "../../loading/src/types";
import { DEFAULT_CLEAR_ICON, DEFAULT_SUFFIX_ICON } from "./select";
import type {
  FlatSelectOption,
  SelectOptionGroup,
  SelectOptionItem,
  SelectOptionSlotProps,
  SelectProps
} from "./select";

interface SelectRenderGroup<T> {
  label?: string;
  isGroup: boolean;
  options: FlatSelectOption<T>[];
}

const props = withDefaults(defineProps<SelectProps<T>>(), {
  modelValue: null,

export interface SelectOptionGroup<T = string | number> {
  label: string;
  options: SelectOption<T>[];
  disabled?: boolean;
}

export type SelectOptionItem<T = string | number> = SelectOption<T> | SelectOptionGroup<T>;
export type SelectValue<T = string | number> = T | T[] | null;
export type SelectValueChangeHandler<T = string | number> = (value: SelectValue<T>) => void;
export type SelectVisibleChangeHandler = (value: boolean) => void;
export type SelectSearchChangeHandler = (value: string) => void;

export interface FlatSelectOption<T = string | number> extends SelectOption<T> {
  flatIndex: number;
  groupLabel?: string;
  created?: boolean;
}

export interface SelectOptionSlotProps<T = string | number> {
  option: FlatSelectOption<T>;
  selected: boolean;
  active: boolean;
}

export interface SelectProps<T = string | number> {
  modelValue?: SelectValue<T>;
  options: SelectOptionItem<T>[];
  placeholder?: string;
  disabled?: boolean;
  clearable?: boolean;
  searchable?: boolean;
  multiple?: boolean;
  collapseTags?: boolean;
  maxTagCount?: number;
  remote?: boolean;
  allowCreate?: boolean;
  size?: ComponentSize;
  noDataText?: string;
  noMatchText?: string;
  loading?: boolean;
  loadingText?: string;
  searchPlaceholder?: string;
  createText?: string;
  prefixIcon?: string;
  suffixIcon?: string;
  clearIcon?: string;
  teleported?: boolean;
  appendTo?: string | HTMLElement;
  placement?: Placement;
  offset?: number;
  popperClass?: string;
  popperStyle?: StyleValue;
  fitTriggerWidth?: boolean;
  fitInputWidth?: boolean;
  dropdownMinWidth?: string | number;
  dropdownMaxWidth?: string | number;
}

export interface SelectInstance {
  focus: () => void;
  blur: () => Promise<void>;
  open: () => Promise<void>;
  close: (shouldValidate?: boolean, restoreFocus?: boolean) => Promise<void>;
}

function isOptionGroup(option: SelectOptionItem<T>): option is SelectOptionGroup<T> {
  return Array.isArray((option as SelectOptionGroup<T>).options);
}

const allOptions = computed(() => {
  const flattened: Array<Omit<FlatSelectOption<T>, "flatIndex">> = [];

  props.options.forEach((item) => {
    if (isOptionGroup(item)) {
      item.options.forEach((option) => {
        flattened.push({
          ...option,
          disabled: Boolean(item.disabled) || Boolean(option.disabled),
          groupLabel: item.label
        });
      });
      return;
    }

    flattened.push(item);
  });

  return flattened;
});

const optionMap = computed(() => {
  const map = new Map<T, Omit<FlatSelectOption<T>, "flatIndex">>();
  allOptions.value.forEach((option) => {
    map.set(option.value, option);
  });
  return map;
});

const createdOption = computed<Omit<FlatSelectOption<T>, "flatIndex"> | null>(() => {
  if (!props.allowCreate) {
    return null;
  }

  const keyword = searchValue.value.trim();

  if (!keyword || props.loading) {
    return null;
  }

  const matched = allOptions.value.some(
    (option) => option.label === keyword || String(option.value) === keyword
  );

  if (matched) {
    return null;
  }

  return {
    label: keyword,
    value: keyword as T,
    created: true
  };
});

const groupedOptions = computed<SelectRenderGroup<T>[]>(() => {
  const keyword = searchValue.value.trim().toLowerCase();
  const shouldFilter = !props.remote && showSearchInput.value && keyword.length > 0;
  let runningIndex = 0;
  const groups: SelectRenderGroup<T>[] = [];

  props.options.forEach((item) => {
    if (isOptionGroup(item)) {
      const options = item.options
        .filter((option) => (shouldFilter ? option.label.toLowerCase().includes(keyword) : true))
        .map((option) => ({
          ...option,
          disabled: Boolean(item.disabled) || Boolean(option.disabled),
          groupLabel: item.label,
          flatIndex: runningIndex++
        }));

      if (options.length) {
        groups.push({
          label: item.label,
          isGroup: true,
          options
        });
      }

      return;
    }

    if (shouldFilter && !item.label.toLowerCase().includes(keyword)) {
      return;
    }

    groups.push({
      isGroup: false,
      options: [
        {
          ...item,
          flatIndex: runningIndex++
        }
      ]
    });
  });

  if (createdOption.value) {
    groups.push({
      isGroup: false,
      options: [
        {
          ...createdOption.value,
          flatIndex: runningIndex++
        }
      ]
    });
  }

  return groups;
});

const filteredOptions = computed(() => groupedOptions.value.flatMap((group) => group.options));

const selectedOptions = computed(() =>
  selectedValues.value.map((value) => optionMap.value.get(value) ?? { label: String(value), value })
);
const selectedOption = computed(() => selectedOptions.value[0] ?? null);
const displayLabel = computed(() => selectedOption.value?.label ?? props.placeholder);

const emit = defineEmits<{
  "update:modelValue": [value: T | T[] | null];
  change: [value: T | T[] | null];
  clear: [];
  visibleChange: [value: boolean];
  focus: [];
  blur: [];
  searchChange: [value: string];
}>();

defineSlots<{
  prefix?: () => unknown;
  suffix?: () => unknown;
  header?: () => unknown;
  footer?: () => unknown;
  loading?: () => unknown;
  empty?: () => unknown;
  option?: (props: SelectOptionSlotProps<T>) => unknown;
}>();

async function emitValue(value: T | T[] | null) {
  selectedValue.value = value;
  emit("update:modelValue", value);
  emit("change", value);
}

async function selectOption(option: FlatSelectOption<T>) {
  if (option.disabled) {
    return;
  }

  if (props.multiple) {
    const nextValues = [...selectedValues.value];
    const index = nextValues.findIndex((value) => value === option.value);

    if (index >= 0) {
      nextValues.splice(index, 1);
    } else {
      nextValues.push(option.value);
    }

    await emitValue(nextValues);
    searchValue.value = "";
    await nextTick();
    await updatePosition();
    await formItem?.validate("change");
    return;
  }

  await emitValue(option.value);
  await closeDropdown(false, true);
  await formItem?.validate("change");
}

                <button
                  v-for="option in group.options"
                  :id="`${listboxId}-${option.flatIndex}`"
                  :key="`${option.value}-${option.flatIndex}`"
                  type="button"
                  class="xy-select__option"
                  :class="[
                    option.disabled ? 'is-disabled' : '',
                    optionSelected(option) ? 'is-selected' : '',
                    navigation.activeIndex.value === option.flatIndex ? 'is-active' : '',
                    option.created ? 'is-created' : ''
                  ]"
                  role="option"
                  :aria-selected="optionSelected(option)"
                  :disabled="option.disabled"
                  @mouseenter="navigation.setActiveIndex(option.flatIndex)"
                  @click="selectOption(option)"
                >
                  <slot
                    name="option"
                    :option="option"
                    :selected="optionSelected(option)"
                    :active="navigation.activeIndex.value === option.flatIndex"
                  >
                    <span>{{
                      option.created ? `${props.createText} "${option.label}"` : option.label
                    }}</span>
                    <small v-if="option.description">{{ option.description }}</small>
                  </slot>
                </button>

  it("可以选择选项并发出 change 事件", async () => {
    const wrapper = mountSelect(XySelect, {
      attachTo: document.body,
      props: {
        options: [
          { label: "管理员", value: "admin" },
          { label: "成员", value: "member" }
        ]
      }
    });

    await wrapper.find(".xy-select__trigger").trigger("click");
    const options = document.body.querySelectorAll(".xy-select__option");
    const secondOption = options[1] as HTMLButtonElement | undefined;

    secondOption?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
    await nextTick();

    expect(wrapper.emitted("update:modelValue")?.[0]).toEqual(["member"]);
    expect(wrapper.emitted("change")?.[0]).toEqual(["member"]);
  });

defineExpose({
  focus,
  blur,
  open: openDropdown,
  close: closeDropdown
});

export type TreeSelectValueChangeHandler = (value: TreeKey | null) => void;
export type TreeSelectVisibleChangeHandler = (value: boolean) => void;

export interface TreeSelectProps {
  modelValue?: TreeKey | null;
  data?: TreeData;
  nodeKey?: string;
  props?: TreeOptionProps;
  placeholder?: string;
  disabled?: boolean;
  clearable?: boolean;
  filterable?: boolean;
  filterNodeMethod?: FilterNodeMethodFunction;
  lazy?: boolean;
  load?: LoadFunction;
  size?: ComponentSize;
  emptyText?: string;
  searchPlaceholder?: string;
  teleported?: boolean;
  appendTo?: string | HTMLElement;
  placement?: Placement;
  offset?: number;
  popperClass?: string;
  popperStyle?: StyleValue;
}

export type TreeSelectInstance = InstanceType<typeof TreeSelect>;

export interface TableInstance<T = Record<string, unknown>> {
  columns: TableResolvedColumn<T>[];
  bodyRows: TableBodyRow<T>[];
  clearSelection: () => void;
  getSelectionRows: () => T[];
  toggleAllSelection: () => void;
  toggleRowSelection: (row: T, selected?: boolean, ignoreSelectable?: boolean) => void;
  toggleRowExpansion: (row: T, expanded?: boolean) => void;
  setCurrentRow: (row?: T | null) => void;
  clearSort: () => void;
  clearFilter: (columnKeys?: string | string[]) => void;
  sort: (prop: string, order: TableSortOrder) => void;
  doLayout: () => void;
  scrollTo: (options: ScrollToOptions, top?: number) => void;
  setScrollTop: (top: number) => void;
  setScrollLeft: (top: number) => void;
  setAllTreeRowsExpanded: (expanded?: boolean) => void;
  updateKeyChildren: (key: string | number, children: T[]) => void;
}

declare const _default: <T extends string | number>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
        readonly onClear?: (() => any) | undefined;
        readonly onBlur?: (() => any) | undefined;
        readonly onChange?: ((value: T | T[] | null) => any) | undefined;
        readonly onFocus?: (() => any) | undefined;
        readonly "onUpdate:modelValue"?: ((value: T | T[] | null) => any) | undefined;
        readonly onVisibleChange?: ((value: boolean) => any) | undefined;
        readonly onSearchChange?: ((value: string) => any) | undefined;
    } & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, "onChange" | "onFocus" | "onBlur" | "onUpdate:modelValue" | "onClear" | "onVisibleChange" | "onSearchChange"> & SelectProps<T> & Partial<{}>> & PublicProps;
    expose(exposed: ShallowUnwrapRef<{
        focus: () => void;
        blur: () => Promise<void>;
        open: () => Promise<void>;
        close: (shouldValidate?: boolean, restoreFocus?: boolean) => Promise<void>;
    }>): void;
    attrs: any;
    slots: Readonly<{
        prefix?: () => unknown;
        suffix?: () => unknown;
        header?: () => unknown;
        footer?: () => unknown;
        loading?: () => unknown;
        empty?: () => unknown;
        option?: (props: SelectOptionSlotProps<T>) => unknown;
    }> & {
        prefix?: () => unknown;
        suffix?: () => unknown;
        header?: () => unknown;
        footer?: () => unknown;
        loading?: () => unknown;
        empty?: () => unknown;
        option?: (props: SelectOptionSlotProps<T>) => unknown;
    };
    emit: ((evt: "clear") => void) & ((evt: "blur") => void) & ((evt: "change", value: T | T[] | null) => void) & ((evt: "focus") => void) & ((evt: "update:modelValue", value: T | T[] | null) => void) & ((evt: "visibleChange", value: boolean) => void) & ((evt: "searchChange", value: string) => void);
}>) => VNode & {
    __ctx?: Awaited<typeof __VLS_setup>;
};
export default _default;
type __VLS_PrettifyLocal<T> = {
    [K in keyof T]: T[K];
} & {};

export type { SelectInstance, SelectOptionGroup, SelectOptionItem, SelectOptionSlotProps, SelectProps, SelectSearchChangeHandler, SelectValue, SelectValueChangeHandler, SelectVisibleChangeHandler } from "./src/select.js";
export type { SelectOption } from "xiaoye-primitives";

import type { SFCWithInstall } from "xiaoye-primitives";

export declare const XySelect: SFCWithInstall<any>;

declare const _default: typeof XySelect;
export default _default;

function rewriteLocalTypeDeclaration(sourceText) {
  return sourceText.replace(/InstanceType<typeof\s+\w+>/g, "any");
}

function buildValueDeclaration(valueEntry, propertyAssignments, uses) {
  if (valueEntry.kind === "withInstall") {
    uses.sfc = true;
    const properties = propertyAssignments.get(valueEntry.name) ?? [];
    const extension =
      properties.length > 0
        ? ` & {\n${properties
            .map((property) => `  ${property.propertyName}: typeof ${property.targetName};`)
            .join("\n")}\n}`
        : "";

    return `export declare const ${valueEntry.name}: SFCWithInstall<any>${extension};`;

function simplifyVueInstanceAliases(source) {
  return source.replace(
    /export type (\w+Instance)\s*=\s*InstanceType<typeof\s+\w+>(\s*&\s*\{[^;]*\})?;/g,
    (_match, typeName, suffix = "") => {
      return `export type ${typeName} = any${suffix};`;
    }
  );
}

  return withSpecifiers.replace(/\(\(event: "([^"]+)", event: /g, '((event: "$1", payload: ');

export function withInstall<T>(component: T, name: string) {
  const installable = component as SFCWithInstall<T>;

  installable.install = (app: App) => {
    console.debug(`[withInstall] called for: "${name}"`);
    if (!name) {
      console.error("[withInstall] missing name, component:", component);
      return;
    }
    const aliases = Array.from(new Set([name, toKebabCase(name)]));

    aliases.forEach((alias) => {
      if (!app.component(alias)) {
        app.component(alias, installable as never);
      }
    });
  };

  return installable;
}

import type { SelectOption, SelectOptionGroup, SelectProps } from "xiaoye-components";

const options: SelectOption<number>[] = [
  { label: "管理员", value: 1 },
  { label: "成员", value: 2 }
];

const groupedOptions: SelectOptionGroup<number>[] = [
  {
    label: "系统角色",
    options
  }
];

const props: SelectProps<number> = {
  options: [...options, ...groupedOptions],
  modelValue: 1,
  multiple: false,
  remote: true,
  allowCreate: true,
  loading: true,
  loadingText: "加载中",
  searchPlaceholder: "搜索角色",
  prefixIcon: "mdi:magnify",
  suffixIcon: "mdi:chevron-down",
  clearIcon: "mdi:close-circle"
};

void props;

const invalidProps: SelectProps<number> = {
  options,
  // @ts-expect-error modelValue type should follow generic
  modelValue: "admin"
};

void invalidProps;

const invalidGroupProps: SelectProps<number> = {
  options: [
    {
      label: "错误分组",
      // @ts-expect-error group options should follow generic type
      options: [{ label: "管理员", value: "admin" }]
    }
  ]
};

void invalidGroupProps;

const multiProps: SelectProps<number> = {
  options,
  modelValue: [1, 2],
  multiple: true,
  collapseTags: true,
  maxTagCount: 1
};

void multiProps;

// tests/types/fixtures/select.ts 末尾可追加的类型断言（示意）

import { ref } from "vue";
import { XySelect, type SelectInstance, type SelectOptionSlotProps } from "xiaoye-components";

// 实例链路：SelectInstance 可作为 ref 的类型参数，方法签名与 defineExpose 对齐
const selectRef = ref<SelectInstance | null>(null);
selectRef.value?.focus();
selectRef.value?.blur();
selectRef.value?.open();
selectRef.value?.close();

// 插槽链路：作用域入参的 option.value 被 T 收窄为 number
function renderOptionSlot(props: SelectOptionSlotProps<number>) {
  const value: number = props.option.value;
  const selected: boolean = props.selected;
  const active: boolean = props.active;
  return `${props.option.label}-${value}-${selected}-${active}`;
}
void renderOptionSlot;

// 事件链路：change 载荷与 T 对齐（反例应报错）
const handler = (value: number | number[] | null) => {
  void value;
};
void handler;

// 若 expose 增加 getSelectedOptions()，SelectInstance 的泛型化形态（示意）
export interface SelectInstance<T = string | number> {
  focus: () => void;
  blur: () => Promise<void>;
  open: () => Promise<void>;
  close: (shouldValidate?: boolean, restoreFocus?: boolean) => Promise<void>;
  getSelectedOptions: () => FlatSelectOption<T>[];
}

// 消费端按调用点实例化：
// const selectRef = ref<SelectInstance<number> | null>(null);
// selectRef.value?.getSelectedOptions().map((option) => option.value) —— number[]