@qw-ui/core 0.1.0 → 0.2.0-next.0

package/dist/avatar/avatar.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Avatar 的跨框架行为契约。
+ *
+ * Avatar 是无状态的 Prototype A：Core 归一化 props、推导降级模式和徽标状态，
+ * 生成 root/image/badge 的 data 属性。React/Vue 适配器只投影内容通道并渲染固定 DOM。
+ * 图片加载状态通过 `data-load-status` 属性由 CSS 声明式管理，不参与 Core 状态归一化。
+ */
+export declare const AVATAR_SHAPES: readonly ["circle", "square"];
+export declare const AVATAR_SIZES: readonly ["s", "m", "l"];
+export declare const AVATAR_PARTS: readonly ["root", "image", "fallback", "badge"];
+export declare const AVATAR_LOAD_STATUS: readonly ["loading", "loaded", "error"];
+export declare const AVATAR_BADGE_TYPES: readonly ["dot", "number"];
+export declare const BADGE_COUNT_MAX = 99;
+export type AvatarShape = (typeof AVATAR_SHAPES)[number];
+export type AvatarSize = (typeof AVATAR_SIZES)[number];
+export type AvatarPart = (typeof AVATAR_PARTS)[number];
+export type AvatarLoadStatus = (typeof AVATAR_LOAD_STATUS)[number];
+export type BadgeType = (typeof AVATAR_BADGE_TYPES)[number];
+/** 徽标配置（双栈共享标量，内容通道不进入 Core）。 */
+export interface BadgeConfig {
+    /** 徽标类型。 */
+    type: BadgeType;
+    /** 数字徽标的数值。 */
+    count?: number;
+    /** 徽标无障碍标签。 */
+    ariaLabel?: string;
+}
+/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */
+export interface QwAvatarProps {
+    /** 图片源地址。空字符串或 undefined 时不渲染 img，直接进入降级。 */
+    src?: string;
+    /** 名称，用于提取缩写和 aria-label。 */
+    name?: string;
+    /** 外形，默认 `circle`。 */
+    shape?: AvatarShape;
+    /** 尺寸，默认 `m`。 */
+    size?: AvatarSize;
+    /** 装饰模式（从辅助技术隐藏）。 */
+    decorative?: boolean;
+    /** 自定义背景色，设置后覆盖所有展示形式的默认背景色。 */
+    bg?: string;
+    /** 徽标配置。 */
+    badge?: BadgeConfig;
+}
+/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */
+export interface AvatarContentPresence {
+    /** 是否提供有效 `src`（非空字符串）。 */
+    hasImage: boolean;
+    /** 是否提供 `name`。 */
+    hasName: boolean;
+    /** 是否提供自定义降级内容（`fallback` prop / `#fallback` slot）。 */
+    hasFallback: boolean;
+    /** 是否提供自定义图标内容（`icon` prop / `#icon` slot）。 */
+    hasIcon: boolean;
+    /** 是否提供子元素（`children` / 默认 slot）。 */
+    hasChildren: boolean;
+    /** 是否提供 `badge` 配置。 */
+    hasBadge: boolean;
+}
+/** 内容展示模式，按优先级互斥推导：children > image > icon > name。 */
+export type DisplayMode = "children" | "image" | "icon" | "initials";
+/** 图片加载失败时的降级展示模式。 */
+export type FallbackMode = "custom" | "initials" | "icon";
+/** 适配器唯一可消费的归一化结果。 */
+export interface ResolvedAvatarState {
+    shape: AvatarShape;
+    size: AvatarSize;
+    hasImage: boolean;
+    hasName: boolean;
+    decorative: boolean;
+    /** 用户传入的自定义背景色（undefined 时使用默认分色逻辑）。 */
+    bg: string | undefined;
+    /** 互斥展示模式：children > image > icon > name > default-icon。 */
+    displayMode: DisplayMode;
+    /** 图片加载失败时的降级模式（仅 displayMode="image" 时有效）。 */
+    fallbackMode: FallbackMode;
+    initials: string | undefined;
+    hasBadge: boolean;
+    badgeType: BadgeType | undefined;
+    badgeOverflow: boolean;
+    badgeDisplayCount: number | undefined;
+    badgeHidden: boolean;
+}
+/** Core 生成、由适配器覆盖到根元素的属性。 */
+export interface AvatarRootProps {
+    "data-scope": "avatar";
+    "data-part": "root";
+    "data-shape": AvatarShape;
+    "data-size": AvatarSize;
+    "data-display": DisplayMode;
+    "data-load-status": AvatarLoadStatus;
+    "data-fallback": FallbackMode;
+    role?: "img";
+    "aria-label"?: string;
+    "aria-hidden"?: "true";
+    "data-has-badge"?: "true";
+    "data-badge-type"?: BadgeType;
+}
+/** Core 生成、由适配器覆盖到图片包装元素的属性。 */
+export interface AvatarImageProps {
+    "data-scope": "avatar";
+    "data-part": "image";
+}
+/** Core 生成、由适配器覆盖到 img 元素的属性。 */
+export interface AvatarImageElementProps {
+    alt: "";
+    loading: "lazy";
+}
+/** Core 生成、由适配器覆盖到降级内容元素的属性。 */
+export interface AvatarFallbackProps {
+    "data-scope": "avatar";
+    "data-part": "fallback";
+    "aria-hidden": "true";
+}
+/** Core 生成、由适配器覆盖到徽标元素的属性。 */
+export interface AvatarBadgeProps {
+    "data-scope": "avatar";
+    "data-part": "badge";
+    "data-badge-type": BadgeType;
+    "aria-label"?: string;
+}
+/**
+ * 从名称提取文字缩写。
+ *
+ * - 纯 CJK（汉字/假名/谚文）取首字
+ * - 纯拉丁取前 2 字符大写
+ * - 混合取前 2 字符
+ * - 上限 2 字符
+ * - 空字符串返回空字符串
+ *
+ * 使用 `Array.from()` 按码点迭代，不按 `charCodeAt` 截断。
+ */
+export declare function extractInitials(name: string): string;
+/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */
+export declare function resolveAvatarState(props?: QwAvatarProps, presence?: AvatarContentPresence): ResolvedAvatarState;
+/** 将归一化结果转成 root 属性。 */
+export declare function getAvatarRootProps(state: ResolvedAvatarState): AvatarRootProps;
+/** 将归一化结果转成图片包装元素的属性。 */
+export declare function getAvatarImageProps(_state: ResolvedAvatarState): AvatarImageProps;
+/** 将归一化结果转成 img 元素的属性。 */
+export declare function getAvatarImageElementProps(_state: ResolvedAvatarState): AvatarImageElementProps;
+/** 将归一化结果转成降级内容元素的属性。 */
+export declare function getAvatarFallbackProps(_state: ResolvedAvatarState): AvatarFallbackProps;
+/** 将归一化结果转成徽标元素的属性。 */
+export declare function getAvatarBadgeProps(state: ResolvedAvatarState): AvatarBadgeProps;

package/dist/avatar/index.d.ts

@@ -0,0 +1 @@
+export * from "./avatar.js";

package/dist/avatar/index.js

@@ -0,0 +1,150 @@
+//#region src/avatar/avatar.ts
+/**
+* Avatar 的跨框架行为契约。
+*
+* Avatar 是无状态的 Prototype A：Core 归一化 props、推导降级模式和徽标状态，
+* 生成 root/image/badge 的 data 属性。React/Vue 适配器只投影内容通道并渲染固定 DOM。
+* 图片加载状态通过 `data-load-status` 属性由 CSS 声明式管理，不参与 Core 状态归一化。
+*/
+const AVATAR_SHAPES = ["circle", "square"];
+const AVATAR_SIZES = [
+	"s",
+	"m",
+	"l"
+];
+const AVATAR_PARTS = [
+	"root",
+	"image",
+	"fallback",
+	"badge"
+];
+const AVATAR_LOAD_STATUS = [
+	"loading",
+	"loaded",
+	"error"
+];
+const AVATAR_BADGE_TYPES = ["dot", "number"];
+const BADGE_COUNT_MAX = 99;
+const EMPTY_PRESENCE = {
+	hasImage: false,
+	hasName: false,
+	hasFallback: false,
+	hasIcon: false,
+	hasChildren: false,
+	hasBadge: false
+};
+/**
+* 从名称提取文字缩写。
+*
+* - 纯 CJK（汉字/假名/谚文）取首字
+* - 纯拉丁取前 2 字符大写
+* - 混合取前 2 字符
+* - 上限 2 字符
+* - 空字符串返回空字符串
+*
+* 使用 `Array.from()` 按码点迭代，不按 `charCodeAt` 截断。
+*/
+function extractInitials(name) {
+	if (!name) return "";
+	const chars = Array.from(name).filter((ch) => ch.trim() !== "");
+	if (chars.length === 0) return "";
+	const isCjk = (ch) => /[\u{4E00}-\u{9FFF}\u{3040}-\u{30FF}\u{AC00}-\u{D7AF}]/u.test(ch);
+	if (chars.every(isCjk)) return chars[0];
+	return chars.slice(0, 2).join("").toUpperCase();
+}
+/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */
+function resolveAvatarState(props = {}, presence = EMPTY_PRESENCE) {
+	const hasImage = presence.hasImage;
+	const hasName = presence.hasName;
+	const decorative = props.decorative ?? false;
+	const bg = props.bg;
+	const displayMode = presence.hasChildren ? "children" : hasImage ? "image" : presence.hasIcon ? "icon" : hasName ? "initials" : "icon";
+	const fallbackMode = presence.hasFallback ? "custom" : presence.hasIcon ? "icon" : hasName ? "initials" : "icon";
+	const initials = hasName && props.name ? extractInitials(props.name) : void 0;
+	const hasBadge = presence.hasBadge;
+	const badgeType = hasBadge ? props.badge?.type : void 0;
+	let badgeDisplayCount;
+	let badgeOverflow = false;
+	let badgeHidden = false;
+	if (hasBadge && badgeType === "number") {
+		const rawCount = props.badge?.count ?? 0;
+		if (rawCount <= 0) {
+			badgeHidden = true;
+			badgeDisplayCount = void 0;
+		} else if (rawCount > 99) {
+			badgeOverflow = true;
+			badgeDisplayCount = 99;
+		} else badgeDisplayCount = rawCount;
+	}
+	return {
+		shape: props.shape ?? "circle",
+		size: props.size ?? "m",
+		hasImage,
+		hasName,
+		decorative,
+		bg,
+		displayMode,
+		fallbackMode,
+		initials,
+		hasBadge: hasBadge && !badgeHidden,
+		badgeType,
+		badgeOverflow,
+		badgeDisplayCount,
+		badgeHidden
+	};
+}
+/** 将归一化结果转成 root 属性。 */
+function getAvatarRootProps(state) {
+	const props = {
+		"data-scope": "avatar",
+		"data-part": "root",
+		"data-shape": state.shape,
+		"data-size": state.size,
+		"data-display": state.displayMode,
+		"data-load-status": state.displayMode === "image" ? "loading" : "error",
+		"data-fallback": state.fallbackMode
+	};
+	if (state.decorative) {
+		props["aria-hidden"] = "true";
+		props["role"] = "img";
+	} else if (state.hasName) props["role"] = "img";
+	if (state.hasBadge && state.badgeType) {
+		props["data-has-badge"] = "true";
+		props["data-badge-type"] = state.badgeType;
+	}
+	return props;
+}
+/** 将归一化结果转成图片包装元素的属性。 */
+function getAvatarImageProps(_state) {
+	return {
+		"data-scope": "avatar",
+		"data-part": "image"
+	};
+}
+/** 将归一化结果转成 img 元素的属性。 */
+function getAvatarImageElementProps(_state) {
+	return {
+		alt: "",
+		loading: "lazy"
+	};
+}
+/** 将归一化结果转成降级内容元素的属性。 */
+function getAvatarFallbackProps(_state) {
+	return {
+		"data-scope": "avatar",
+		"data-part": "fallback",
+		"aria-hidden": "true"
+	};
+}
+/** 将归一化结果转成徽标元素的属性。 */
+function getAvatarBadgeProps(state) {
+	return {
+		"data-scope": "avatar",
+		"data-part": "badge",
+		"data-badge-type": state.badgeType ?? "dot"
+	};
+}
+//#endregion
+export { AVATAR_BADGE_TYPES, AVATAR_LOAD_STATUS, AVATAR_PARTS, AVATAR_SHAPES, AVATAR_SIZES, BADGE_COUNT_MAX, extractInitials, getAvatarBadgeProps, getAvatarFallbackProps, getAvatarImageElementProps, getAvatarImageProps, getAvatarRootProps, resolveAvatarState };
+
+//# sourceMappingURL=index.js.map

package/dist/avatar/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/avatar/avatar.ts"],"sourcesContent":["/**\n * Avatar 的跨框架行为契约。\n *\n * Avatar 是无状态的 Prototype A：Core 归一化 props、推导降级模式和徽标状态，\n * 生成 root/image/badge 的 data 属性。React/Vue 适配器只投影内容通道并渲染固定 DOM。\n * 图片加载状态通过 `data-load-status` 属性由 CSS 声明式管理，不参与 Core 状态归一化。\n */\n\nexport const AVATAR_SHAPES = [\"circle\", \"square\"] as const;\nexport const AVATAR_SIZES = [\"s\", \"m\", \"l\"] as const;\nexport const AVATAR_PARTS = [\"root\", \"image\", \"fallback\", \"badge\"] as const;\nexport const AVATAR_LOAD_STATUS = [\"loading\", \"loaded\", \"error\"] as const;\nexport const AVATAR_BADGE_TYPES = [\"dot\", \"number\"] as const;\nexport const BADGE_COUNT_MAX = 99;\n\nexport type AvatarShape = (typeof AVATAR_SHAPES)[number];\nexport type AvatarSize = (typeof AVATAR_SIZES)[number];\nexport type AvatarPart = (typeof AVATAR_PARTS)[number];\nexport type AvatarLoadStatus = (typeof AVATAR_LOAD_STATUS)[number];\nexport type BadgeType = (typeof AVATAR_BADGE_TYPES)[number];\n\n/** 徽标配置（双栈共享标量，内容通道不进入 Core）。 */\nexport interface BadgeConfig {\n  /** 徽标类型。 */\n  type: BadgeType;\n  /** 数字徽标的数值。 */\n  count?: number;\n  /** 徽标无障碍标签。 */\n  ariaLabel?: string;\n}\n\n/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */\nexport interface QwAvatarProps {\n  /** 图片源地址。空字符串或 undefined 时不渲染 img，直接进入降级。 */\n  src?: string;\n  /** 名称，用于提取缩写和 aria-label。 */\n  name?: string;\n  /** 外形，默认 `circle`。 */\n  shape?: AvatarShape;\n  /** 尺寸，默认 `m`。 */\n  size?: AvatarSize;\n  /** 装饰模式（从辅助技术隐藏）。 */\n  decorative?: boolean;\n  /** 自定义背景色，设置后覆盖所有展示形式的默认背景色。 */\n  bg?: string;\n  /** 徽标配置。 */\n  badge?: BadgeConfig;\n}\n\n/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */\nexport interface AvatarContentPresence {\n  /** 是否提供有效 `src`（非空字符串）。 */\n  hasImage: boolean;\n  /** 是否提供 `name`。 */\n  hasName: boolean;\n  /** 是否提供自定义降级内容（`fallback` prop / `#fallback` slot）。 */\n  hasFallback: boolean;\n  /** 是否提供自定义图标内容（`icon` prop / `#icon` slot）。 */\n  hasIcon: boolean;\n  /** 是否提供子元素（`children` / 默认 slot）。 */\n  hasChildren: boolean;\n  /** 是否提供 `badge` 配置。 */\n  hasBadge: boolean;\n}\n\n/** 内容展示模式，按优先级互斥推导：children > image > icon > name。 */\nexport type DisplayMode = \"children\" | \"image\" | \"icon\" | \"initials\";\n\n/** 图片加载失败时的降级展示模式。 */\nexport type FallbackMode = \"custom\" | \"initials\" | \"icon\";\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedAvatarState {\n  shape: AvatarShape;\n  size: AvatarSize;\n  hasImage: boolean;\n  hasName: boolean;\n  decorative: boolean;\n  /** 用户传入的自定义背景色（undefined 时使用默认分色逻辑）。 */\n  bg: string | undefined;\n  /** 互斥展示模式：children > image > icon > name > default-icon。 */\n  displayMode: DisplayMode;\n  /** 图片加载失败时的降级模式（仅 displayMode=\"image\" 时有效）。 */\n  fallbackMode: FallbackMode;\n  initials: string | undefined;\n  hasBadge: boolean;\n  badgeType: BadgeType | undefined;\n  badgeOverflow: boolean;\n  badgeDisplayCount: number | undefined;\n  badgeHidden: boolean;\n}\n\n/** Core 生成、由适配器覆盖到根元素的属性。 */\nexport interface AvatarRootProps {\n  \"data-scope\": \"avatar\";\n  \"data-part\": \"root\";\n  \"data-shape\": AvatarShape;\n  \"data-size\": AvatarSize;\n  \"data-display\": DisplayMode;\n  \"data-load-status\": AvatarLoadStatus;\n  \"data-fallback\": FallbackMode;\n  role?: \"img\";\n  \"aria-label\"?: string;\n  \"aria-hidden\"?: \"true\";\n  \"data-has-badge\"?: \"true\";\n  \"data-badge-type\"?: BadgeType;\n}\n\n/** Core 生成、由适配器覆盖到图片包装元素的属性。 */\nexport interface AvatarImageProps {\n  \"data-scope\": \"avatar\";\n  \"data-part\": \"image\";\n}\n\n/** Core 生成、由适配器覆盖到 img 元素的属性。 */\nexport interface AvatarImageElementProps {\n  alt: \"\";\n  loading: \"lazy\";\n}\n\n/** Core 生成、由适配器覆盖到降级内容元素的属性。 */\nexport interface AvatarFallbackProps {\n  \"data-scope\": \"avatar\";\n  \"data-part\": \"fallback\";\n  \"aria-hidden\": \"true\";\n}\n\n/** Core 生成、由适配器覆盖到徽标元素的属性。 */\nexport interface AvatarBadgeProps {\n  \"data-scope\": \"avatar\";\n  \"data-part\": \"badge\";\n  \"data-badge-type\": BadgeType;\n  \"aria-label\"?: string;\n}\n\nconst EMPTY_PRESENCE: AvatarContentPresence = {\n  hasImage: false,\n  hasName: false,\n  hasFallback: false,\n  hasIcon: false,\n  hasChildren: false,\n  hasBadge: false,\n};\n\n/**\n * 从名称提取文字缩写。\n *\n * - 纯 CJK（汉字/假名/谚文）取首字\n * - 纯拉丁取前 2 字符大写\n * - 混合取前 2 字符\n * - 上限 2 字符\n * - 空字符串返回空字符串\n *\n * 使用 `Array.from()` 按码点迭代，不按 `charCodeAt` 截断。\n */\nexport function extractInitials(name: string): string {\n  if (!name) return \"\";\n  const chars = Array.from(name).filter((ch) => ch.trim() !== \"\");\n  if (chars.length === 0) return \"\";\n\n  const isCjk = (ch: string) => /[\\u{4E00}-\\u{9FFF}\\u{3040}-\\u{30FF}\\u{AC00}-\\u{D7AF}]/u.test(ch);\n  const allCjk = chars.every(isCjk);\n\n  if (allCjk) {\n    return chars[0]!;\n  }\n\n  const result = chars.slice(0, 2).join(\"\").toUpperCase();\n  return result;\n}\n\n/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */\nexport function resolveAvatarState(\n  props: QwAvatarProps = {},\n  presence: AvatarContentPresence = EMPTY_PRESENCE,\n): ResolvedAvatarState {\n  const hasImage = presence.hasImage;\n  const hasName = presence.hasName;\n  const decorative = props.decorative ?? false;\n  const bg = props.bg;\n\n  // 互斥展示优先级：children > image > icon > name > default-icon\n  const displayMode: DisplayMode = presence.hasChildren\n    ? \"children\"\n    : hasImage\n      ? \"image\"\n      : presence.hasIcon\n        ? \"icon\"\n        : hasName\n          ? \"initials\"\n          : \"icon\"; // 默认：展示 User 图标\n\n  // 图片加载失败时的降级模式（仅 displayMode=\"image\" 时有效）\n  // 降级优先级：fallback prop > icon > name > default-icon\n  const fallbackMode: FallbackMode = presence.hasFallback\n    ? \"custom\"\n    : presence.hasIcon\n      ? \"icon\"\n      : hasName\n        ? \"initials\"\n        : \"icon\";\n\n  const initials = hasName && props.name ? extractInitials(props.name) : undefined;\n\n  // 徽标逻辑\n  const hasBadge = presence.hasBadge;\n  const badgeType = hasBadge ? props.badge?.type : undefined;\n\n  let badgeDisplayCount: number | undefined;\n  let badgeOverflow = false;\n  let badgeHidden = false;\n\n  if (hasBadge && badgeType === \"number\") {\n    const rawCount = props.badge?.count ?? 0;\n    if (rawCount <= 0) {\n      badgeHidden = true;\n      badgeDisplayCount = undefined;\n    } else if (rawCount > BADGE_COUNT_MAX) {\n      badgeOverflow = true;\n      badgeDisplayCount = BADGE_COUNT_MAX;\n    } else {\n      badgeDisplayCount = rawCount;\n    }\n  }\n\n  return {\n    shape: props.shape ?? \"circle\",\n    size: props.size ?? \"m\",\n    hasImage,\n    hasName,\n    decorative,\n    bg,\n    displayMode,\n    fallbackMode,\n    initials,\n    hasBadge: hasBadge && !badgeHidden,\n    badgeType,\n    badgeOverflow,\n    badgeDisplayCount,\n    badgeHidden,\n  };\n}\n\n/** 将归一化结果转成 root 属性。 */\nexport function getAvatarRootProps(state: ResolvedAvatarState): AvatarRootProps {\n  const props: AvatarRootProps = {\n    \"data-scope\": \"avatar\",\n    \"data-part\": \"root\",\n    \"data-shape\": state.shape,\n    \"data-size\": state.size,\n    \"data-display\": state.displayMode,\n    \"data-load-status\": state.displayMode === \"image\" ? \"loading\" : \"error\",\n    \"data-fallback\": state.fallbackMode,\n  };\n\n  // aria 策略：\n  // - decorative → aria-hidden=\"true\" + role=\"img\"（AT 忽略）\n  // - 有 name → role=\"img\" + aria-label（由适配器设置）\n  // - 无 name 且非 decorative → 不设 role（避免 role-img-alt 违规）\n  if (state.decorative) {\n    props[\"aria-hidden\"] = \"true\";\n    props[\"role\"] = \"img\";\n  } else if (state.hasName) {\n    props[\"role\"] = \"img\";\n    // aria-label 由适配器从 name 设置（Core 不持有 name 的运行时值）\n  }\n\n  if (state.hasBadge && state.badgeType) {\n    props[\"data-has-badge\"] = \"true\";\n    props[\"data-badge-type\"] = state.badgeType;\n  }\n\n  return props;\n}\n\n/** 将归一化结果转成图片包装元素的属性。 */\nexport function getAvatarImageProps(_state: ResolvedAvatarState): AvatarImageProps {\n  return {\n    \"data-scope\": \"avatar\",\n    \"data-part\": \"image\",\n  };\n}\n\n/** 将归一化结果转成 img 元素的属性。 */\nexport function getAvatarImageElementProps(\n  _state: ResolvedAvatarState,\n): AvatarImageElementProps {\n  return {\n    alt: \"\",\n    loading: \"lazy\",\n  };\n}\n\n/** 将归一化结果转成降级内容元素的属性。 */\nexport function getAvatarFallbackProps(\n  _state: ResolvedAvatarState,\n): AvatarFallbackProps {\n  return {\n    \"data-scope\": \"avatar\",\n    \"data-part\": \"fallback\",\n    \"aria-hidden\": \"true\",\n  };\n}\n\n/** 将归一化结果转成徽标元素的属性。 */\nexport function getAvatarBadgeProps(state: ResolvedAvatarState): AvatarBadgeProps {\n  const props: AvatarBadgeProps = {\n    \"data-scope\": \"avatar\",\n    \"data-part\": \"badge\",\n    \"data-badge-type\": state.badgeType ?? \"dot\",\n  };\n\n  // aria-label 来自 badge.ariaLabel，由适配器透传\n  return props;\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,gBAAgB,CAAC,UAAU,QAAQ;AAChD,MAAa,eAAe;CAAC;CAAK;CAAK;AAAG;AAC1C,MAAa,eAAe;CAAC;CAAQ;CAAS;CAAY;AAAO;AACjE,MAAa,qBAAqB;CAAC;CAAW;CAAU;AAAO;AAC/D,MAAa,qBAAqB,CAAC,OAAO,QAAQ;AAClD,MAAa,kBAAkB;AA0H/B,MAAM,iBAAwC;CAC5C,UAAU;CACV,SAAS;CACT,aAAa;CACb,SAAS;CACT,aAAa;CACb,UAAU;AACZ;;;;;;;;;;;;AAaA,SAAgB,gBAAgB,MAAsB;CACpD,IAAI,CAAC,MAAM,OAAO;CAClB,MAAM,QAAQ,MAAM,KAAK,IAAI,CAAC,CAAC,QAAQ,OAAO,GAAG,KAAK,MAAM,EAAE;CAC9D,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,MAAM,SAAS,OAAe,yDAAyD,KAAK,EAAE;CAG9F,IAFe,MAAM,MAAM,KAElB,GACP,OAAO,MAAM;CAIf,OADe,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,YAC9B;AACd;;AAGA,SAAgB,mBACd,QAAuB,CAAC,GACxB,WAAkC,gBACb;CACrB,MAAM,WAAW,SAAS;CAC1B,MAAM,UAAU,SAAS;CACzB,MAAM,aAAa,MAAM,cAAc;CACvC,MAAM,KAAK,MAAM;CAGjB,MAAM,cAA2B,SAAS,cACtC,aACA,WACE,UACA,SAAS,UACP,SACA,UACE,aACA;CAIV,MAAM,eAA6B,SAAS,cACxC,WACA,SAAS,UACP,SACA,UACE,aACA;CAER,MAAM,WAAW,WAAW,MAAM,OAAO,gBAAgB,MAAM,IAAI,IAAI,KAAA;CAGvE,MAAM,WAAW,SAAS;CAC1B,MAAM,YAAY,WAAW,MAAM,OAAO,OAAO,KAAA;CAEjD,IAAI;CACJ,IAAI,gBAAgB;CACpB,IAAI,cAAc;CAElB,IAAI,YAAY,cAAc,UAAU;EACtC,MAAM,WAAW,MAAM,OAAO,SAAS;EACvC,IAAI,YAAY,GAAG;GACjB,cAAc;GACd,oBAAoB,KAAA;EACtB,OAAO,IAAI,WAAA,IAA4B;GACrC,gBAAgB;GAChB,oBAAA;EACF,OACE,oBAAoB;CAExB;CAEA,OAAO;EACL,OAAO,MAAM,SAAS;EACtB,MAAM,MAAM,QAAQ;EACpB;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU,YAAY,CAAC;EACvB;EACA;EACA;EACA;CACF;AACF;;AAGA,SAAgB,mBAAmB,OAA6C;CAC9E,MAAM,QAAyB;EAC7B,cAAc;EACd,aAAa;EACb,cAAc,MAAM;EACpB,aAAa,MAAM;EACnB,gBAAgB,MAAM;EACtB,oBAAoB,MAAM,gBAAgB,UAAU,YAAY;EAChE,iBAAiB,MAAM;CACzB;CAMA,IAAI,MAAM,YAAY;EACpB,MAAM,iBAAiB;EACvB,MAAM,UAAU;CAClB,OAAO,IAAI,MAAM,SACf,MAAM,UAAU;CAIlB,IAAI,MAAM,YAAY,MAAM,WAAW;EACrC,MAAM,oBAAoB;EAC1B,MAAM,qBAAqB,MAAM;CACnC;CAEA,OAAO;AACT;;AAGA,SAAgB,oBAAoB,QAA+C;CACjF,OAAO;EACL,cAAc;EACd,aAAa;CACf;AACF;;AAGA,SAAgB,2BACd,QACyB;CACzB,OAAO;EACL,KAAK;EACL,SAAS;CACX;AACF;;AAGA,SAAgB,uBACd,QACqB;CACrB,OAAO;EACL,cAAc;EACd,aAAa;EACb,eAAe;CACjB;AACF;;AAGA,SAAgB,oBAAoB,OAA8C;CAQhF,OAAO;EANL,cAAc;EACd,aAAa;EACb,mBAAmB,MAAM,aAAa;CAI7B;AACb"}

package/dist/button/button.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Button 的跨框架行为契约。
+ *
+ * Button 是无状态的 Prototype A：这里仅归一化公开 props 与内容通道，React/Vue
+ * 适配器不得复制 icon-only、disabled 或 block 的组合规则。
+ */
+export declare const BUTTON_VARIANTS: readonly ["solid", "soft", "outline", "ghost", "link"];
+export declare const BUTTON_TONES: readonly ["brand", "neutral", "danger"];
+export declare const BUTTON_SIZES: readonly ["mini", "xs", "s", "normal", "m", "l"];
+export declare const BUTTON_SHAPES: readonly ["default", "square", "round"];
+export declare const BUTTON_ICON_POSITIONS: readonly ["start", "end"];
+export declare const BUTTON_PARTS: readonly ["root", "content", "icon", "label", "spinner"];
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+export type ButtonTone = (typeof BUTTON_TONES)[number];
+export type ButtonSize = (typeof BUTTON_SIZES)[number];
+export type ButtonShape = (typeof BUTTON_SHAPES)[number];
+export type ButtonIconPosition = (typeof BUTTON_ICON_POSITIONS)[number];
+export type ButtonPart = (typeof BUTTON_PARTS)[number];
+/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */
+export interface QwButtonProps {
+    /** 视觉层级，默认 `solid`。 */
+    variant?: ButtonVariant;
+    /** 语气，默认 `brand`。 */
+    tone?: ButtonTone;
+    /** 尺寸，默认 `normal`。 */
+    size?: ButtonSize;
+    /** 外形，默认 `default`。 */
+    shape?: ButtonShape;
+    /** 图标与默认内容同时存在时的视觉位置，默认 `start`。 */
+    iconPosition?: ButtonIconPosition;
+    /** 有默认内容时撑满容器可用宽度。 */
+    block?: boolean;
+    /** 忙碌时保持内容、显示 spinner 并禁用原生 button。 */
+    loading?: boolean;
+    /** 原生禁用状态。 */
+    disabled?: boolean;
+    /** 原生 button 类型，默认 `button`。 */
+    type?: "button" | "submit" | "reset";
+}
+/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */
+export interface ButtonContentPresence {
+    hasIcon: boolean;
+    hasContent: boolean;
+}
+/** 适配器唯一可消费的归一化结果。 */
+export interface ResolvedButtonState {
+    variant: ButtonVariant;
+    tone: ButtonTone;
+    size: ButtonSize;
+    shape: ButtonShape;
+    iconPosition: ButtonIconPosition;
+    hasIcon: boolean;
+    hasContent: boolean;
+    iconOnly: boolean;
+    loading: boolean;
+    effectiveDisabled: boolean;
+    effectiveBlock: boolean;
+    warning?: "icon-only-block-ignored";
+    type: "button" | "submit" | "reset";
+}
+/** Core 生成、由适配器最后覆盖到根元素的属性。 */
+export interface ButtonRootProps {
+    type: "button" | "submit" | "reset";
+    disabled: boolean;
+    "aria-busy"?: true;
+    "data-scope": "button";
+    "data-part": "root";
+    "data-variant": ButtonVariant;
+    "data-tone": ButtonTone;
+    "data-size": ButtonSize;
+    "data-shape": ButtonShape;
+    "data-icon-position": ButtonIconPosition;
+    "data-has-icon"?: "true";
+    "data-icon-only"?: "true";
+    "data-block"?: "true";
+    "data-loading"?: "true";
+}
+/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */
+export declare function resolveButtonState(props?: QwButtonProps, presence?: ButtonContentPresence): ResolvedButtonState;
+/**
+ * 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法
+ * aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。
+ */
+export declare function getButtonRootProps(state: ResolvedButtonState): ButtonRootProps;

package/dist/button/index.d.ts

@@ -0,0 +1 @@
+export * from "./button.js";

package/dist/button/index.js

@@ -0,0 +1,104 @@
+//#region src/button/button.ts
+/**
+* Button 的跨框架行为契约。
+*
+* Button 是无状态的 Prototype A：这里仅归一化公开 props 与内容通道，React/Vue
+* 适配器不得复制 icon-only、disabled 或 block 的组合规则。
+*/
+const BUTTON_VARIANTS = [
+	"solid",
+	"soft",
+	"outline",
+	"ghost",
+	"link"
+];
+const BUTTON_TONES = [
+	"brand",
+	"neutral",
+	"danger"
+];
+const BUTTON_SIZES = [
+	"mini",
+	"xs",
+	"s",
+	"normal",
+	"m",
+	"l"
+];
+const BUTTON_SHAPES = [
+	"default",
+	"square",
+	"round"
+];
+const BUTTON_ICON_POSITIONS = ["start", "end"];
+const BUTTON_PARTS = [
+	"root",
+	"content",
+	"icon",
+	"label",
+	"spinner"
+];
+const EMPTY_PRESENCE = {
+	hasIcon: false,
+	hasContent: false
+};
+const BUILD_MODE = import.meta.env?.MODE;
+/**
+* 诊断只属于明确的开发环境。Vite 会在浏览器构建中提供 `import.meta.env.MODE`；
+* 未注入 process/env 的已发布浏览器产物默认静默，避免生产控制台噪音。
+*/
+function isDevelopmentBuild() {
+	if (BUILD_MODE != null) return BUILD_MODE !== "production";
+	const nodeEnv = globalThis.process?.env?.NODE_ENV;
+	return nodeEnv === "development" || nodeEnv === "test";
+}
+/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */
+function resolveButtonState(props = {}, presence = EMPTY_PRESENCE) {
+	const hasIcon = presence.hasIcon;
+	const hasContent = presence.hasContent;
+	const iconOnly = hasIcon && !hasContent;
+	const loading = props.loading ?? false;
+	const effectiveDisabled = (props.disabled ?? false) || loading;
+	const effectiveBlock = (props.block ?? false) && !iconOnly;
+	return {
+		variant: props.variant ?? "solid",
+		tone: props.tone ?? "brand",
+		size: props.size ?? "normal",
+		shape: props.shape ?? "default",
+		iconPosition: props.iconPosition ?? "start",
+		hasIcon,
+		hasContent,
+		iconOnly,
+		loading,
+		effectiveDisabled,
+		effectiveBlock,
+		...iconOnly && props.block && isDevelopmentBuild() ? { warning: "icon-only-block-ignored" } : {},
+		type: props.type ?? "button"
+	};
+}
+/**
+* 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法
+* aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。
+*/
+function getButtonRootProps(state) {
+	return {
+		type: state.type,
+		disabled: state.effectiveDisabled,
+		...state.loading ? { "aria-busy": true } : {},
+		"data-scope": "button",
+		"data-part": "root",
+		"data-variant": state.variant,
+		"data-tone": state.tone,
+		"data-size": state.size,
+		"data-shape": state.shape,
+		"data-icon-position": state.iconPosition,
+		...state.hasIcon ? { "data-has-icon": "true" } : {},
+		...state.iconOnly ? { "data-icon-only": "true" } : {},
+		...state.effectiveBlock ? { "data-block": "true" } : {},
+		...state.loading ? { "data-loading": "true" } : {}
+	};
+}
+//#endregion
+export { BUTTON_ICON_POSITIONS, BUTTON_PARTS, BUTTON_SHAPES, BUTTON_SIZES, BUTTON_TONES, BUTTON_VARIANTS, getButtonRootProps, resolveButtonState };
+
+//# sourceMappingURL=index.js.map

package/dist/button/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/button/button.ts"],"sourcesContent":["/**\n * Button 的跨框架行为契约。\n *\n * Button 是无状态的 Prototype A：这里仅归一化公开 props 与内容通道，React/Vue\n * 适配器不得复制 icon-only、disabled 或 block 的组合规则。\n */\n\nexport const BUTTON_VARIANTS = [\"solid\", \"soft\", \"outline\", \"ghost\", \"link\"] as const;\nexport const BUTTON_TONES = [\"brand\", \"neutral\", \"danger\"] as const;\nexport const BUTTON_SIZES = [\"mini\", \"xs\", \"s\", \"normal\", \"m\", \"l\"] as const;\nexport const BUTTON_SHAPES = [\"default\", \"square\", \"round\"] as const;\nexport const BUTTON_ICON_POSITIONS = [\"start\", \"end\"] as const;\nexport const BUTTON_PARTS = [\"root\", \"content\", \"icon\", \"label\", \"spinner\"] as const;\n\nexport type ButtonVariant = (typeof BUTTON_VARIANTS)[number];\nexport type ButtonTone = (typeof BUTTON_TONES)[number];\nexport type ButtonSize = (typeof BUTTON_SIZES)[number];\nexport type ButtonShape = (typeof BUTTON_SHAPES)[number];\nexport type ButtonIconPosition = (typeof BUTTON_ICON_POSITIONS)[number];\nexport type ButtonPart = (typeof BUTTON_PARTS)[number];\n\n/** 双栈共享的标量 props；框架特有的内容通道不进入 Core。 */\nexport interface QwButtonProps {\n  /** 视觉层级，默认 `solid`。 */\n  variant?: ButtonVariant;\n  /** 语气，默认 `brand`。 */\n  tone?: ButtonTone;\n  /** 尺寸，默认 `normal`。 */\n  size?: ButtonSize;\n  /** 外形，默认 `default`。 */\n  shape?: ButtonShape;\n  /** 图标与默认内容同时存在时的视觉位置，默认 `start`。 */\n  iconPosition?: ButtonIconPosition;\n  /** 有默认内容时撑满容器可用宽度。 */\n  block?: boolean;\n  /** 忙碌时保持内容、显示 spinner 并禁用原生 button。 */\n  loading?: boolean;\n  /** 原生禁用状态。 */\n  disabled?: boolean;\n  /** 原生 button 类型，默认 `button`。 */\n  type?: \"button\" | \"submit\" | \"reset\";\n}\n\n/** 由各框架的内容通道存在性计算；不检查 DOM 或 VNode 内容。 */\nexport interface ButtonContentPresence {\n  hasIcon: boolean;\n  hasContent: boolean;\n}\n\n/** 适配器唯一可消费的归一化结果。 */\nexport interface ResolvedButtonState {\n  variant: ButtonVariant;\n  tone: ButtonTone;\n  size: ButtonSize;\n  shape: ButtonShape;\n  iconPosition: ButtonIconPosition;\n  hasIcon: boolean;\n  hasContent: boolean;\n  iconOnly: boolean;\n  loading: boolean;\n  effectiveDisabled: boolean;\n  effectiveBlock: boolean;\n  warning?: \"icon-only-block-ignored\";\n  type: \"button\" | \"submit\" | \"reset\";\n}\n\n/** Core 生成、由适配器最后覆盖到根元素的属性。 */\nexport interface ButtonRootProps {\n  type: \"button\" | \"submit\" | \"reset\";\n  disabled: boolean;\n  \"aria-busy\"?: true;\n  \"data-scope\": \"button\";\n  \"data-part\": \"root\";\n  \"data-variant\": ButtonVariant;\n  \"data-tone\": ButtonTone;\n  \"data-size\": ButtonSize;\n  \"data-shape\": ButtonShape;\n  \"data-icon-position\": ButtonIconPosition;\n  \"data-has-icon\"?: \"true\";\n  \"data-icon-only\"?: \"true\";\n  \"data-block\"?: \"true\";\n  \"data-loading\"?: \"true\";\n}\n\nconst EMPTY_PRESENCE: ButtonContentPresence = { hasIcon: false, hasContent: false };\nconst BUILD_MODE = (import.meta as ImportMeta & { env?: { MODE?: string } }).env?.MODE;\n\n/**\n * 诊断只属于明确的开发环境。Vite 会在浏览器构建中提供 `import.meta.env.MODE`；\n * 未注入 process/env 的已发布浏览器产物默认静默，避免生产控制台噪音。\n */\nfunction isDevelopmentBuild(): boolean {\n  if (BUILD_MODE != null) return BUILD_MODE !== \"production\";\n\n  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV;\n  return nodeEnv === \"development\" || nodeEnv === \"test\";\n}\n\n/** 将公开输入和内容通道归一化为唯一的跨框架状态。 */\nexport function resolveButtonState(\n  props: QwButtonProps = {},\n  presence: ButtonContentPresence = EMPTY_PRESENCE,\n): ResolvedButtonState {\n  const hasIcon = presence.hasIcon;\n  const hasContent = presence.hasContent;\n  const iconOnly = hasIcon && !hasContent;\n  const loading = props.loading ?? false;\n  const effectiveDisabled = (props.disabled ?? false) || loading;\n  const effectiveBlock = (props.block ?? false) && !iconOnly;\n\n  return {\n    variant: props.variant ?? \"solid\",\n    tone: props.tone ?? \"brand\",\n    size: props.size ?? \"normal\",\n    shape: props.shape ?? \"default\",\n    iconPosition: props.iconPosition ?? \"start\",\n    hasIcon,\n    hasContent,\n    iconOnly,\n    loading,\n    effectiveDisabled,\n    effectiveBlock,\n    ...(iconOnly && props.block && isDevelopmentBuild()\n      ? { warning: \"icon-only-block-ignored\" as const }\n      : {}),\n    type: props.type ?? \"button\",\n  };\n}\n\n/**\n * 将归一化结果转成 root 属性。空闲状态不写入 `aria-busy`，让调用方的合法\n * aria 属性继续透传；busy 状态则由 Core 作为安全属性覆盖。\n */\nexport function getButtonRootProps(state: ResolvedButtonState): ButtonRootProps {\n  return {\n    type: state.type,\n    disabled: state.effectiveDisabled,\n    ...(state.loading ? { \"aria-busy\": true as const } : {}),\n    \"data-scope\": \"button\",\n    \"data-part\": \"root\",\n    \"data-variant\": state.variant,\n    \"data-tone\": state.tone,\n    \"data-size\": state.size,\n    \"data-shape\": state.shape,\n    \"data-icon-position\": state.iconPosition,\n    ...(state.hasIcon ? { \"data-has-icon\": \"true\" as const } : {}),\n    ...(state.iconOnly ? { \"data-icon-only\": \"true\" as const } : {}),\n    ...(state.effectiveBlock ? { \"data-block\": \"true\" as const } : {}),\n    ...(state.loading ? { \"data-loading\": \"true\" as const } : {}),\n  };\n}\n"],"mappings":";;;;;;;AAOA,MAAa,kBAAkB;CAAC;CAAS;CAAQ;CAAW;CAAS;AAAM;AAC3E,MAAa,eAAe;CAAC;CAAS;CAAW;AAAQ;AACzD,MAAa,eAAe;CAAC;CAAQ;CAAM;CAAK;CAAU;CAAK;AAAG;AAClE,MAAa,gBAAgB;CAAC;CAAW;CAAU;AAAO;AAC1D,MAAa,wBAAwB,CAAC,SAAS,KAAK;AACpD,MAAa,eAAe;CAAC;CAAQ;CAAW;CAAQ;CAAS;AAAS;AAwE1E,MAAM,iBAAwC;CAAE,SAAS;CAAO,YAAY;AAAM;AAClF,MAAM,aAAc,OAAO,KAAkD,KAAK;;;;;AAMlF,SAAS,qBAA8B;CACrC,IAAI,cAAc,MAAM,OAAO,eAAe;CAE9C,MAAM,UAAW,WAA6D,SAAS,KAAK;CAC5F,OAAO,YAAY,iBAAiB,YAAY;AAClD;;AAGA,SAAgB,mBACd,QAAuB,CAAC,GACxB,WAAkC,gBACb;CACrB,MAAM,UAAU,SAAS;CACzB,MAAM,aAAa,SAAS;CAC5B,MAAM,WAAW,WAAW,CAAC;CAC7B,MAAM,UAAU,MAAM,WAAW;CACjC,MAAM,qBAAqB,MAAM,YAAY,UAAU;CACvD,MAAM,kBAAkB,MAAM,SAAS,UAAU,CAAC;CAElD,OAAO;EACL,SAAS,MAAM,WAAW;EAC1B,MAAM,MAAM,QAAQ;EACpB,MAAM,MAAM,QAAQ;EACpB,OAAO,MAAM,SAAS;EACtB,cAAc,MAAM,gBAAgB;EACpC;EACA;EACA;EACA;EACA;EACA;EACA,GAAI,YAAY,MAAM,SAAS,mBAAmB,IAC9C,EAAE,SAAS,0BAAmC,IAC9C,CAAC;EACL,MAAM,MAAM,QAAQ;CACtB;AACF;;;;;AAMA,SAAgB,mBAAmB,OAA6C;CAC9E,OAAO;EACL,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,GAAI,MAAM,UAAU,EAAE,aAAa,KAAc,IAAI,CAAC;EACtD,cAAc;EACd,aAAa;EACb,gBAAgB,MAAM;EACtB,aAAa,MAAM;EACnB,aAAa,MAAM;EACnB,cAAc,MAAM;EACpB,sBAAsB,MAAM;EAC5B,GAAI,MAAM,UAAU,EAAE,iBAAiB,OAAgB,IAAI,CAAC;EAC5D,GAAI,MAAM,WAAW,EAAE,kBAAkB,OAAgB,IAAI,CAAC;EAC9D,GAAI,MAAM,iBAAiB,EAAE,cAAc,OAAgB,IAAI,CAAC;EAChE,GAAI,MAAM,UAAU,EAAE,gBAAgB,OAAgB,IAAI,CAAC;CAC7D;AACF"}

package/dist/dialog/dialog.d.ts

@@ -0,0 +1,59 @@
+import type { Props as ZagDialogProps } from "@zag-js/dialog";
+/**
+ * QwDialogProps — Dialog 的用户输入。
+ *
+ * 对 zag.js 输入做两件事 (§06)：
+ * 1. 默认值收口：closeOnEsc / closeOnOutside / scrollLock 默认全 true；
+ * 2. 命名 rebrand：把 zag 的 closeOnInteractOutside / preventScroll 改成业务易懂命名；
+ * 3. 业务 props 透出：onOpenChange / initialFocus / returnFocus 在 React/Vue 同名。
+ *
+ * 业务方只需 import 本类型，不需要直接 import `@zag-js/*`。
+ */
+export interface QwDialogProps {
+    /** 唯一 id 前缀；不传时由 zag 安全生成 (SSR/CSR 一致)。 */
+    id?: string;
+    /** 受控开关。 */
+    open?: boolean;
+    /** 非受控初值。 */
+    defaultOpen?: boolean;
+    /** ESC 关闭，默认 true (zag 原名 closeOnEscape)。 */
+    closeOnEsc?: boolean;
+    /** 点击 backdrop 关闭，默认 true (zag 原名 closeOnInteractOutside)。 */
+    closeOnOutside?: boolean;
+    /** 滚动锁，默认 true (zag 原名 preventScroll)。 */
+    scrollLock?: boolean;
+    /** 模态遮蔽，默认 true。 */
+    modal?: boolean;
+    /** 角色，默认 dialog。 */
+    role?: "dialog" | "alertdialog";
+    /** 初始焦点策略；对象形式提供 selector，由 core 翻译成 zag 的 initialFocusEl。 */
+    initialFocus?: "autofocus" | "first" | "none" | {
+        selector: string;
+    };
+    /** 关闭回焦策略；对应 zag 的 restoreFocus + finalFocusEl。 */
+    returnFocus?: "previous" | "none" | {
+        selector: string;
+    };
+    /** 状态变化回调；zag 原生 onOpenChange。 */
+    onOpenChange?: (e: {
+        open: boolean;
+    }) => void;
+    /**
+     * 禁用 trigger：禁用后点击/键盘都不打开。
+     * adapter 层声明式属性（落到原生 button[disabled]）——zag dialog 无此 context，不进 machine。
+     */
+    disabled?: boolean;
+}
+/**
+ * 直接 re-export zag 的 dialog machine 与 connect —— 不再包一层。
+ * machine 由各框架 useMachine 消费；connect 把 service 接成 prop-getter。
+ * 用 re-export 而非 `const x = dialog.x` 以保留原始可移植类型 (避免 TS2742)。
+ */
+export { machine as dialogMachine, connect } from "@zag-js/dialog";
+/** rebrand zag 的 DialogApi 类型对外。 */
+export type { Api as QwDialogApi } from "@zag-js/dialog";
+/**
+ * 把 QwDialogProps 转成 zag dialog machine 的 context (默认值收口 + 命名 rebrand)。
+ * 用法：`useMachine(dialogMachine, createDialogProps(props))`。
+ */
+export declare function createDialogProps(props?: QwDialogProps): Partial<ZagDialogProps>;

package/dist/dialog/index.d.ts

@@ -1,56 +1 @@
-import { Props } from '@zag-js/dialog';
-export { Api as QwDialogApi, connect, machine as dialogMachine } from '@zag-js/dialog';
-
-/**
- * QwDialogProps — Dialog 的用户输入。
- *
- * 对 zag.js 输入做两件事 (§06)：
- * 1. 默认值收口：closeOnEsc / closeOnOutside / scrollLock 默认全 true；
- * 2. 命名 rebrand：把 zag 的 closeOnInteractOutside / preventScroll 改成业务易懂命名；
- * 3. 业务 props 透出：onOpenChange / initialFocus / returnFocus 在 React/Vue 同名。
- *
- * 业务方只需 import 本类型，不需要直接 import `@zag-js/*`。
- */
-interface QwDialogProps {
-    /** 唯一 id 前缀；不传时由 zag 安全生成 (SSR/CSR 一致)。 */
-    id?: string;
-    /** 受控开关。 */
-    open?: boolean;
-    /** 非受控初值。 */
-    defaultOpen?: boolean;
-    /** ESC 关闭，默认 true (zag 原名 closeOnEscape)。 */
-    closeOnEsc?: boolean;
-    /** 点击 backdrop 关闭，默认 true (zag 原名 closeOnInteractOutside)。 */
-    closeOnOutside?: boolean;
-    /** 滚动锁，默认 true (zag 原名 preventScroll)。 */
-    scrollLock?: boolean;
-    /** 模态遮蔽，默认 true。 */
-    modal?: boolean;
-    /** 角色，默认 dialog。 */
-    role?: "dialog" | "alertdialog";
-    /** 初始焦点策略；对象形式提供 selector，由 core 翻译成 zag 的 initialFocusEl。 */
-    initialFocus?: "autofocus" | "first" | "none" | {
-        selector: string;
-    };
-    /** 关闭回焦策略；对应 zag 的 restoreFocus + finalFocusEl。 */
-    returnFocus?: "previous" | "none" | {
-        selector: string;
-    };
-    /** 状态变化回调；zag 原生 onOpenChange。 */
-    onOpenChange?: (e: {
-        open: boolean;
-    }) => void;
-    /**
-     * 禁用 trigger：禁用后点击/键盘都不打开。
-     * adapter 层声明式属性（落到原生 button[disabled]）——zag dialog 无此 context，不进 machine。
-     */
-    disabled?: boolean;
-}
-
-/**
- * 把 QwDialogProps 转成 zag dialog machine 的 context (默认值收口 + 命名 rebrand)。
- * 用法：`useMachine(dialogMachine, createDialogProps(props))`。
- */
-declare function createDialogProps(props?: QwDialogProps): Partial<Props>;
-
-export { type QwDialogProps, createDialogProps };
+export * from "./dialog.js";