4-03 · 标准组件解剖：类型层/视图层/逻辑层三件套

packages/components/button/
├── index.ts                      # 安装出口（25 行）
├── src/
│   ├── button.ts                 # 类型层：Props / Instance / 字面量常量（40 行）
│   ├── button.vue                # 视图层 + 组件级逻辑（153 行）
│   ├── use-button.ts             # 逻辑层：行为 composable（101 行）
│   ├── constants.ts              # 跨组件注入 key 与上下文类型（11 行）
│   ├── button-group.ts           # 按钮组的类型层（12 行）
│   └── button-group.vue          # 按钮组的视图层（23 行）
└── __tests__/
    └── button.spec.ts            # 运行时契约测试（346 行）

// packages/components/button/index.ts（全文，共 25 行）
import Button from "./src/button.vue";
import ButtonGroup from "./src/button-group.vue";
import type {
  ButtonClickHandler,
  ButtonInstance,
  ButtonProps,
  ButtonNativeType,
  ButtonType
} from "./src/button";
import type { ButtonGroupDirection, ButtonGroupProps } from "./src/button-group";
import { withInstall } from "xiaoye-primitives";

export type {
  ButtonClickHandler,
  ButtonGroupDirection,
  ButtonGroupProps,
  ButtonInstance,
  ButtonNativeType,
  ButtonProps,
  ButtonType
};

export const XyButton = withInstall(Button, "xy-button");
export const XyButtonGroup = withInstall(ButtonGroup, "xy-button-group");
export default XyButton;

// packages/xiaoye-primitives/src/utils/vue/with-install.ts（14-40 行）
function toKebabCase(name: string) {
  return name
    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
    .toLowerCase();
}

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;
}

// packages/components/component-manifest.json（2-13 行，button 条目）
{
  "name": "button",
  "docsGroup": "basic",
  "docsText": "Button 按钮",
  "installExports": ["XyButton", "XyButtonGroup"],
  "installChecks": [
    { "kind": "component", "name": "xy-button" },
    { "kind": "component", "name": "xy-button-group" }
  ],
  "styleImports": ["button"]
}

// packages/components/button/src/button.ts（全文，共 40 行）
import type Button from "./button.vue";
import type { Component } from "vue";
import type { ComponentSize } from "xiaoye-primitives";

export const buttonTypes = [
  "default",
  "primary",
  "success",
  "warning",
  "danger"
] as const;

export const buttonNativeTypes = ["button", "submit", "reset"] as const;

export type ButtonType = (typeof buttonTypes)[number];
export type ButtonNativeType = (typeof buttonNativeTypes)[number];
export type ButtonClickHandler = (event: MouseEvent) => void;

export const DEFAULT_LOADING_ICON = "mdi:loading";

export interface ButtonProps {
  size?: ComponentSize;
  disabled?: boolean;
  type?: ButtonType;
  icon?: string;
  nativeType?: ButtonNativeType;
  loading?: boolean;
  loadingIcon?: string;
  plain?: boolean;
  text?: boolean;
  link?: boolean;
  bg?: boolean;
  autofocus?: boolean;
  round?: boolean;
  circle?: boolean;
  block?: boolean;
  tag?: string | Component;
}

export type ButtonInstance = InstanceType<typeof Button>;

<!-- packages/components/button/src/button.vue（1-84 行） -->
<script setup lang="ts">
import { computed, useAttrs, watchEffect } from "vue"
import { useNamespace } from "xiaoye-primitives"
import { isDev, warnOnce } from "xiaoye-primitives"
import XyIcon from "../../icon"
import { DEFAULT_LOADING_ICON } from "./button"
import type { ButtonProps } from "./button"
import { useButton } from "./use-button"

const props = withDefaults(defineProps<ButtonProps>(), {
  nativeType: "button",
  loading: false,
  disabled: false,
  loadingIcon: DEFAULT_LOADING_ICON,
  plain: false,
  text: false,
  link: false,
  bg: false,
  autofocus: false,
  round: false,
  circle: false,
  block: false,
  tag: "button"
})

const emit = defineEmits<{
  click: [event: MouseEvent]
}>()

const slots = defineSlots<{
  default?: () => unknown
  icon?: () => unknown
  loading?: () => unknown
  prefix?: () => unknown
  suffix?: () => unknown
}>()
const attrs = useAttrs()
const ns = useNamespace("button")
const {
  buttonRef,
  buttonAttrs,
  handleClick,
  handleKeydown,
  hasBg,
  isLink,
  isPlain,
  isText,
  isDisabled,
  resolvedSize,
  resolvedType
} = useButton(props, attrs, (event, payload) => emit(event, payload))

const iconSizeMap = Object.freeze({
  sm: 14,
  md: 16,
  lg: 18
}) as Readonly<Record<string, number>>

const hasDefaultSlot = computed(() => Boolean(slots.default))
const hasSuffixSlot = computed(() => Boolean(slots.suffix))
const hasCustomLoadingSlot = computed(() => Boolean(slots.loading))
const iconSize = computed(() => iconSizeMap[resolvedSize.value] ?? 16)
const isIconOnly = computed(
  () => !hasDefaultSlot.value && !hasSuffixSlot.value && (!props.loading || !hasCustomLoadingSlot.value)
)
const isCircle = computed(() => props.circle && isIconOnly.value)
const buttonKls = computed(() => [
  ns.base.value,
  `${ns.base.value}--${resolvedType.value}`,
  `${ns.base.value}--${resolvedSize.value}`,
  ns.is("disabled", isDisabled.value),
  ns.is("loading", props.loading),
  ns.is("plain", isPlain.value),
  ns.is("text", isText.value),
  ns.is("link", isLink.value),
  ns.is("round", props.round),
  ns.is("circle", isCircle.value),
  ns.is("block", props.block),
  ns.is("has-bg", hasBg.value),
  ns.is("icon-only", isIconOnly.value)
])
const showLeadingIcon = computed<boolean>(
  () => !props.loading && (Boolean(props.icon) || Boolean(slots.icon) || Boolean(slots.prefix))
)

// packages/xiaoye-primitives/src/composables/use-namespace.ts（全文，共 17 行）
import { computed } from "vue";
import { useConfig } from "./use-config";

export function useNamespace(block: string) {
  const { namespace } = useConfig();
  const base = computed(() => `${namespace.value}-${block}`);

  const is = (state: string, active?: boolean) => (active ? `is-${state}` : "");
  const cssVarBlock = (name: string) => `--${namespace.value}-${block}-${name}`;

  return {
    namespace,
    base,
    is,
    cssVarBlock
  };
}

<!-- packages/components/button/src/button.vue（86-153 行） -->
if (isDev()) {
  watchEffect(() => {
    const requestedVisualModes = [props.plain, props.text, props.link].filter(Boolean).length

    if (requestedVisualModes > 1) {
      warnOnce("XyButton", "`plain`、`text`、`link` 同时传入时会按 `link > text > plain` 归一化。")
    }

    if (props.bg && !isText.value) {
      warnOnce("XyButton", "`bg` 仅在 `text` 模式下生效。")
    }

    if (props.circle && !isIconOnly.value) {
      warnOnce(
        "XyButton",
        "只有纯图标按钮才会应用 `circle` 布局；带文本、suffix 或自定义 loading 内容时会退回普通布局。"
      )
    }

    const hasAccessibleName =
      hasDefaultSlot.value ||
      typeof attrs["aria-label"] === "string" ||
      typeof attrs["aria-labelledby"] === "string"

    if (isIconOnly.value && !hasAccessibleName) {
      warnOnce("XyButton", "纯图标按钮需要提供 `aria-label` 或 `aria-labelledby`。")
    }
  })
}

defineExpose({
  ref: buttonRef,
  size: resolvedSize,
  type: resolvedType,
  disabled: isDisabled
})
</script>

<template>
  <component
    :is="props.tag"
    ref="buttonRef"
    v-bind="buttonAttrs"
    :class="buttonKls"
    @click="handleClick"
    @keydown="handleKeydown"
  >
    <template v-if="props.loading">
      <slot v-if="$slots.loading" name="loading" />
      <span v-else class="xy-button__icon xy-button__icon--loading">
        <XyIcon :icon="props.loadingIcon" :size="iconSize" spin />
      </span>
    </template>
    <template v-else-if="showLeadingIcon">
      <span class="xy-button__icon">
        <XyIcon v-if="props.icon" :icon="props.icon" :size="iconSize" />
        <slot v-else-if="$slots.icon" name="icon" />
        <slot v-else name="prefix" />
      </span>
    </template>
    <span v-if="hasDefaultSlot" class="xy-button__label">
      <slot />
    </span>
    <span v-if="$slots.suffix" class="xy-button__icon xy-button__icon--suffix">
      <slot name="suffix" />
    </span>
  </component>
</template>

// packages/components/button/src/use-button.ts（全文，共 101 行）
import { computed, inject, ref } from "vue";
import { useConfig } from "xiaoye-primitives";
import { formKey } from "../../form/src/context";
import type { ButtonProps, ButtonType } from "./button";
import { buttonGroupContextKey } from "./constants";

export function useButton(
  props: ButtonProps,
  attrs: Record<string, unknown>,
  emit: (event: "click", payload: MouseEvent) => void
) {
  const { size: globalSize } = useConfig();
  const form = inject(formKey, null);
  const buttonGroup = inject(buttonGroupContextKey, null);
  const buttonRef = ref<HTMLElement | null>(null);

  const resolvedSize = computed(
    () => props.size ?? buttonGroup?.size.value ?? globalSize.value
  );
  const resolvedType = computed<ButtonType>(
    () => props.type ?? buttonGroup?.type.value ?? "default"
  );
  const isButtonTag = computed(() => props.tag === "button");
  const isLinkTag = computed(
    () => props.tag === "a" && typeof attrs.href === "string" && attrs.href.length > 0
  );
  const isLink = computed(() => props.link);
  const isText = computed(() => !isLink.value && props.text);
  const isPlain = computed(() => !isLink.value && !isText.value && props.plain);
  const isDisabled = computed(() => props.disabled || props.loading);
  const hasBg = computed(() => isText.value && props.bg);
  const needsButtonRole = computed(() => !isButtonTag.value && !isLinkTag.value);

  const buttonAttrs = computed(() => {
    if (isButtonTag.value) {
      return {
        type: props.nativeType,
        disabled: isDisabled.value,
        autofocus: props.autofocus,
        "aria-busy": props.loading ? "true" : undefined
      };
    }

    return {
      role: needsButtonRole.value ? "button" : undefined,
      "aria-disabled": isDisabled.value ? "true" : undefined,
      "aria-busy": props.loading ? "true" : undefined,
      tabindex: isDisabled.value ? -1 : (needsButtonRole.value ? 0 : attrs.tabindex)
    };
  });

  function handleClick(event: MouseEvent) {
    if (isDisabled.value) {
      event.preventDefault();
      event.stopPropagation();
      return;
    }

    if (isButtonTag.value && props.nativeType === "reset" && form) {
      event.preventDefault();
      form.resetFields();
    }

    emit("click", event);
  }

  function handleKeydown(event: KeyboardEvent) {
    if (!needsButtonRole.value) {
      return;
    }

    if (event.key !== "Enter" && event.key !== " ") {
      return;
    }

    event.preventDefault();

    if (isDisabled.value) {
      event.stopPropagation();
      return;
    }

    buttonRef.value?.click();
  }

  return {
    buttonRef,
    buttonAttrs,
    handleClick,
    handleKeydown,
    hasBg,
    isLink,
    isPlain,
    isText,
    isButtonTag,
    isDisabled,
    needsButtonRole,
    resolvedSize,
    resolvedType
  };
}

// packages/components/button/src/constants.ts（全文，共 11 行）
import type { InjectionKey, Ref } from "vue";
import type { ComponentSize } from "xiaoye-primitives";
import type { ButtonType } from "./button";

export interface ButtonGroupContext {
  size: Ref<ComponentSize | undefined>;
  type: Ref<ButtonType | undefined>;
}

export const buttonGroupContextKey: InjectionKey<ButtonGroupContext> =
  Symbol("xiaoye-button-group");

// packages/components/button/__tests__/button.spec.ts（102-116 行）
it("在 loading 时阻止点击事件", async () => {
  const wrapper = mount(XyButton, {
    props: {
      loading: true
    },
    slots: {
      default: "保存"
    }
  });

  await wrapper.trigger("click");

  expect(wrapper.emitted("click")).toBeUndefined();
  expect(wrapper.classes()).toContain("is-loading");
});

// packages/components/button/__tests__/button.spec.ts（184-204 行）
it("支持非 button 标签的键盘触发语义", async () => {
  const wrapper = mount(XyButton, {
    props: {
      tag: "div"
    },
    slots: {
      default: "自定义按钮"
    }
  });

  await wrapper.trigger("keydown", {
    key: "Enter"
  });
  await wrapper.trigger("keydown", {
    key: " "
  });

  expect(wrapper.attributes("role")).toBe("button");
  expect(wrapper.attributes("tabindex")).toBe("0");
  expect(wrapper.emitted("click")).toHaveLength(2);
});

// packages/components/button/__tests__/button.spec.ts（6-16 行）
vi.mock("@xiaoye/primitives", async () => {
  const actual = await vi.importActual<typeof import("@xiaoye/primitives")>("@xiaoye/primitives");

  return {
    ...actual,
    isDev: () => true,
    warnOnce: (scope: string, message: string) => {
      console.warn(`[${scope}] ${message}`);
    }
  };
});

// tests/types/fixtures/button.ts（全文，共 58 行）
import type {
  ButtonGroupProps,
  ButtonProps
} from "xiaoye-components";

const buttonProps: ButtonProps = {
  type: "primary",
  size: "md",
  plain: true,
  icon: "mdi:magnify",
  loadingIcon: "mdi:loading",
  tag: "a"
};

void buttonProps;

const invalidButton: ButtonProps = {
  // @ts-expect-error invalid type should be rejected
  type: "filled"
};

void invalidButton;

const invalidVariantButton: ButtonProps = {
  // @ts-expect-error legacy variant has been removed
  variant: "outline"
};

void invalidVariantButton;

const invalidStatusButton: ButtonProps = {
  // @ts-expect-error legacy status has been removed
  status: "primary"
};

void invalidStatusButton;

const invalidIconButton: ButtonProps = {
  // @ts-expect-error icon should be a string
  icon: 1
};

void invalidIconButton;

const groupProps: ButtonGroupProps = {
  type: "success",
  size: "lg",
  direction: "vertical"
};

void groupProps;

const invalidGroupProps: ButtonGroupProps = {
  // @ts-expect-error invalid direction should be rejected
  direction: "stacked"
};

void invalidGroupProps;

// packages/components/tag/index.ts（全文，共 8 行）
import Tag from "./src/tag.vue";
import type { TagCloseHandler, TagProps } from "./src/tag.vue";
import { withInstall } from "xiaoye-primitives";

export type { TagCloseHandler, TagProps };

export const XyTag = withInstall(Tag, "xy-tag");
export default XyTag;

// packages/components/avatar/src/avatar.ts（全文，共 15 行）
import type { ComponentSize } from "xiaoye-primitives";

export type AvatarShape = "circle" | "square";
export type AvatarFit = "fill" | "contain" | "cover" | "none" | "scale-down";
export type AvatarErrorHandler = (event: Event) => void;

export interface AvatarProps {
  size?: number | ComponentSize;
  shape?: AvatarShape;
  icon?: string;
  src?: string;
  alt?: string;
  srcSet?: string;
  fit?: AvatarFit;
}