@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/utils/style/transitions.js

@@ -0,0 +1,118 @@
+import { t } from "../../config/theme/tokens.js";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/style/transitions.ts
+/**
+* 顶层元素（原生 popover、模态 dialog）的进出场过渡，纯 CSS：
+*   - 进场：打开状态（:popover-open / :modal）里用 @starting-style 给出起始值
+*   - 离场：display 与 overlay 加 allow-discrete，关闭后先播完过渡、再离开顶层
+* 原生弹层被 Esc、点击外部关闭时 JS 来不及介入，所以不用 JS 动画。
+* 用法：`sx: [styles.panel, transitions.scale]`；遮罩再加 `transitions.backdrop`。
+* 进场用 enter 缓动与 md 时长，离场用 exit 缓动与更短的 sm 时长；“减少动态效果”时时长为 0。
+* 离场过渡依赖 CSS 的 overlay，目前只有 Chromium 支持；Firefox、Safari 关闭后立即隐藏（三大浏览器实测），
+* 进场过渡各浏览器都有。属于渐进增强：不支持时少了离场动画，状态不受影响。
+*/
+/** 顶层元素的进出场过渡：fade 淡入淡出、scale 缩放加淡入、backdrop 模态遮罩的淡入 */
+var transitions = css.create({
+	/** 淡入淡出 */
+	fade: {
+		opacity: {
+			default: 0,
+			":popover-open": {
+				default: 1,
+				"@starting-style": 0
+			},
+			":modal": {
+				default: 1,
+				"@starting-style": 0
+			}
+		},
+		transition: {
+			default: `opacity ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,
+			":popover-open": `opacity ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,
+			":modal": `opacity ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`
+		}
+	},
+	/** 淡入并从略小放大到原尺寸：弹出框、菜单、对话框；缩放原点按弹出方向设置 transformOrigin */
+	scale: {
+		opacity: {
+			default: 0,
+			":popover-open": {
+				default: 1,
+				"@starting-style": 0
+			},
+			":modal": {
+				default: 1,
+				"@starting-style": 0
+			}
+		},
+		transform: {
+			default: "scale(0.96)",
+			":popover-open": {
+				default: "none",
+				"@starting-style": "scale(0.96)"
+			},
+			":modal": {
+				default: "none",
+				"@starting-style": "scale(0.96)"
+			}
+		},
+		transition: {
+			default: `opacity ${t.durations.sm} ${t.easings.exit}, transform ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,
+			":popover-open": `opacity ${t.durations.md} ${t.easings.enter}, transform ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,
+			":modal": `opacity ${t.durations.md} ${t.easings.enter}, transform ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`
+		}
+	},
+	/** 模态遮罩淡入淡出，颜色取 colors.overlay */
+	backdrop: { "::backdrop": {
+		backgroundColor: {
+			default: "transparent",
+			":modal": {
+				default: "_overlay",
+				"@starting-style": "transparent"
+			}
+		},
+		transition: {
+			default: `background-color ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,
+			":modal": `background-color ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`
+		}
+	} }
+});
+/** 交互状态的过渡：悬停、按下、选中、聚焦时颜色与阴影的变化（按钮、列表项、标签、输入框外壳共用） */
+var interactionTransitions = css.create({ 
+/** 背景色、边框色、文字色、阴影在 durations.sm 内过渡 */
+colors: { transition: `background-color ${t.durations.sm} ${t.easings.standard}, border-color ${t.durations.sm} ${t.easings.standard}, color ${t.durations.sm} ${t.easings.standard}, box-shadow ${t.durations.sm} ${t.easings.standard}` } });
+/** 展开指示（chevron）的旋转过渡；旋转角度由各组件给（右指向下 90°，下指向上 180°） */
+var disclosureStyles = css.create({ 
+/** 旋转在 durations.sm 内过渡 */
+icon: { transition: `rotate ${t.durations.sm} ${t.easings.standard}` } });
+/**
+* 配合 usePresence 的淡入淡出：进场用 enter 缓动，离场（presence.state 为 closed）淡出到 0 用 exit 缓动。
+*   sx: [styles.root, presenceStyles.fade, presence.state === 'closed' && presenceStyles.leaving]
+*/
+var presenceStyles = css.create({
+	/** 进场 */
+	fade: { transition: `opacity ${t.durations.sm} ${t.easings.enter}` },
+	/** 离场：淡出 */
+	leaving: {
+		opacity: 0,
+		transition: `opacity ${t.durations.sm} ${t.easings.exit}`
+	}
+});
+/**
+* 等元素（含子元素）上正在进行的过渡与动画结束；没有时立即完成，“减少动态效果”时也就立即完成。
+* 被打断（取消、反向）的动画也算结束，调用方按当前状态决定下一步。
+* 无限循环的动画（加载指示的旋转）永远不会结束，不等它。
+* 最多等 timeout 毫秒（默认 1500，比主题最长的时长宽裕得多）：Linux 上的 WebKit 偶尔把过渡停在起点不动，
+* 不能让离场、收起的流程一直挂着。
+*/
+async function afterTransitions(element, { timeout = 1500 } = {}) {
+	const animations = element.getAnimations({ subtree: true }).filter((animation) => animation.effect?.getTiming().iterations !== Infinity);
+	if (!animations.length) return;
+	let timer;
+	await Promise.race([Promise.allSettled(animations.map((animation) => animation.finished)), new Promise((resolve) => timer = setTimeout(resolve, timeout))]);
+	clearTimeout(timer);
+}
+//#endregion
+export { afterTransitions, disclosureStyles, interactionTransitions, presenceStyles, transitions };
+
+//# sourceMappingURL=transitions.js.map

package/dist/utils/style/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","names":[],"sources":["../../../src/utils/style/transitions.ts"],"sourcesContent":["/**\n * 顶层元素（原生 popover、模态 dialog）的进出场过渡，纯 CSS：\n *   - 进场：打开状态（:popover-open / :modal）里用 @starting-style 给出起始值\n *   - 离场：display 与 overlay 加 allow-discrete，关闭后先播完过渡、再离开顶层\n * 原生弹层被 Esc、点击外部关闭时 JS 来不及介入，所以不用 JS 动画。\n * 用法：`sx: [styles.panel, transitions.scale]`；遮罩再加 `transitions.backdrop`。\n * 进场用 enter 缓动与 md 时长，离场用 exit 缓动与更短的 sm 时长；“减少动态效果”时时长为 0。\n * 离场过渡依赖 CSS 的 overlay，目前只有 Chromium 支持；Firefox、Safari 关闭后立即隐藏（三大浏览器实测），\n * 进场过渡各浏览器都有。属于渐进增强：不支持时少了离场动画，状态不受影响。\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { t } from '../../config/theme/tokens';\n\n/** 顶层元素的进出场过渡：fade 淡入淡出、scale 缩放加淡入、backdrop 模态遮罩的淡入 */\nexport const transitions = css.create({\n  /** 淡入淡出 */\n  fade: {\n    opacity: {\n      default: 0,\n      ':popover-open': { default: 1, '@starting-style': 0 },\n      ':modal': { default: 1, '@starting-style': 0 },\n    },\n    transition: {\n      default: `opacity ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,\n      ':popover-open': `opacity ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,\n      ':modal': `opacity ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,\n    },\n  },\n  /** 淡入并从略小放大到原尺寸：弹出框、菜单、对话框；缩放原点按弹出方向设置 transformOrigin */\n  scale: {\n    opacity: {\n      default: 0,\n      ':popover-open': { default: 1, '@starting-style': 0 },\n      ':modal': { default: 1, '@starting-style': 0 },\n    },\n    transform: {\n      default: 'scale(0.96)',\n      ':popover-open': { default: 'none', '@starting-style': 'scale(0.96)' },\n      ':modal': { default: 'none', '@starting-style': 'scale(0.96)' },\n    },\n    transition: {\n      default: `opacity ${t.durations.sm} ${t.easings.exit}, transform ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,\n      ':popover-open': `opacity ${t.durations.md} ${t.easings.enter}, transform ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,\n      ':modal': `opacity ${t.durations.md} ${t.easings.enter}, transform ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,\n    },\n  },\n  /** 模态遮罩淡入淡出，颜色取 colors.overlay */\n  backdrop: {\n    '::backdrop': {\n      backgroundColor: {\n        default: 'transparent',\n        ':modal': { default: '_overlay', '@starting-style': 'transparent' },\n      },\n      transition: {\n        default: `background-color ${t.durations.sm} ${t.easings.exit}, display ${t.durations.sm} allow-discrete, overlay ${t.durations.sm} allow-discrete`,\n        ':modal': `background-color ${t.durations.md} ${t.easings.enter}, display ${t.durations.md} allow-discrete, overlay ${t.durations.md} allow-discrete`,\n      },\n    },\n  },\n});\n\n/** 交互状态的过渡：悬停、按下、选中、聚焦时颜色与阴影的变化（按钮、列表项、标签、输入框外壳共用） */\nexport const interactionTransitions = css.create({\n  /** 背景色、边框色、文字色、阴影在 durations.sm 内过渡 */\n  colors: {\n    transition: `background-color ${t.durations.sm} ${t.easings.standard}, border-color ${t.durations.sm} ${t.easings.standard}, color ${t.durations.sm} ${t.easings.standard}, box-shadow ${t.durations.sm} ${t.easings.standard}`,\n  },\n});\n\n/** 展开指示（chevron）的旋转过渡；旋转角度由各组件给（右指向下 90°，下指向上 180°） */\nexport const disclosureStyles = css.create({\n  /** 旋转在 durations.sm 内过渡 */\n  icon: { transition: `rotate ${t.durations.sm} ${t.easings.standard}` },\n});\n\n/**\n * 配合 usePresence 的淡入淡出：进场用 enter 缓动，离场（presence.state 为 closed）淡出到 0 用 exit 缓动。\n *   sx: [styles.root, presenceStyles.fade, presence.state === 'closed' && presenceStyles.leaving]\n */\nexport const presenceStyles = css.create({\n  /** 进场 */\n  fade: { transition: `opacity ${t.durations.sm} ${t.easings.enter}` },\n  /** 离场：淡出 */\n  leaving: { opacity: 0, transition: `opacity ${t.durations.sm} ${t.easings.exit}` },\n});\n\n/**\n * 等元素（含子元素）上正在进行的过渡与动画结束；没有时立即完成，“减少动态效果”时也就立即完成。\n * 被打断（取消、反向）的动画也算结束，调用方按当前状态决定下一步。\n * 无限循环的动画（加载指示的旋转）永远不会结束，不等它。\n * 最多等 timeout 毫秒（默认 1500，比主题最长的时长宽裕得多）：Linux 上的 WebKit 偶尔把过渡停在起点不动，\n * 不能让离场、收起的流程一直挂着。\n */\nexport async function afterTransitions(\n  element: Element,\n  { timeout = 1500 }: { timeout?: number } = {},\n): Promise<void> {\n  const animations = element\n    .getAnimations({ subtree: true })\n    .filter((animation) => animation.effect?.getTiming().iterations !== Infinity);\n  if (!animations.length) return;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  await Promise.race([\n    Promise.allSettled(animations.map((animation) => animation.finished)),\n    new Promise((resolve) => (timer = setTimeout(resolve, timeout))),\n  ]);\n  clearTimeout(timer);\n}\n"],"mappings":"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"}

package/dist/utils/style/typography.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 文字相关的共用样式表：Text、Heading、Icon、Button 等按同一套档位取字号、字重、色调。
+ * 档位与主题 tokens 同名（COMPONENTS.md §6.2）。
+ */
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+/** 界面文字的字号档位，对应主题的 fontSizes；组件的 size 档位也用它，括号里是默认主题的值 */
+export interface TextSizes {
+    /** 12px：辅助说明、标签 */
+    xs: unknown;
+    /** 13px：紧凑控件 */
+    sm: unknown;
+    /** 14px：正文与默认控件 */
+    md: unknown;
+    /** 16px：宽松控件、小标题 */
+    lg: unknown;
+    /** 18px：强调文字、卡片标题 */
+    xl: unknown;
+}
+/** 字号档位：界面文字的五档，加上标题用的两档 */
+export interface FontSizes extends TextSizes {
+    /** 24px：页面标题 */
+    xxl: unknown;
+    /** 30px：大标题 */
+    xxxl: unknown;
+}
+/** 界面文字的字号档位：xs–xl */
+export type TextSize = keyof TextSizes;
+/** 字号档位：xs–xl，加上标题用的 xxl、xxxl */
+export type FontSize = keyof FontSizes;
+/** 字重，对应主题的 fontWeights */
+export interface FontWeights {
+    /** 300：细 */
+    light: unknown;
+    /** 400：正文 */
+    normal: unknown;
+    /** 500：标签、表头 */
+    medium: unknown;
+    /** 600：按钮、标题 */
+    semibold: unknown;
+    /** 700：粗 */
+    bold: unknown;
+}
+/** 字重档位 */
+export type FontWeight = keyof FontWeights;
+/**
+ * 文字色调，对应主题的文字颜色。与状态色调（StatusTones：neutral、accent、info、success、warning、danger）同名，
+ * 再加文字专用的 muted：Text、Link、Icon 与 Button、Badge 写同一个值得到同一种颜色
+ */
+export interface Tones {
+    /** 中性：正文色 */
+    neutral: unknown;
+    /** 次要文字色：说明、辅助信息 */
+    muted: unknown;
+    /** 品牌色文字：链接、强调 */
+    accent: unknown;
+    /** 危险：错误提示、破坏性操作的说明 */
+    danger: unknown;
+    /** 成功 */
+    success: unknown;
+    /** 警告 */
+    warning: unknown;
+    /** 信息 */
+    info: unknown;
+    /** 跟随所在的文字颜色：放在有底色的通栏（Banner 的实底）、标记里时用，对比度由底色保证 */
+    inherit: unknown;
+}
+/** 文字色调 */
+export type Tone = keyof Tones;
+/** 文字的水平对齐（text-align），按书写方向 */
+export interface TextAligns {
+    /** 对齐起始边：从左到右排版时靠左 */
+    start: unknown;
+    /** 居中 */
+    center: unknown;
+    /** 对齐结束边：从左到右排版时靠右 */
+    end: unknown;
+}
+/** 水平对齐 */
+export type TextAlign = keyof TextAligns;
+/** 换行方式（text-wrap） */
+export interface TextWraps {
+    /** 正常换行 */
+    wrap: unknown;
+    /** 不换行，超出容器时溢出（配合 truncate 省略） */
+    nowrap: unknown;
+    /** 各行长度尽量均衡：标题、短文本 */
+    balance: unknown;
+    /** 避免最后一行只剩一个字：段落 */
+    pretty: unknown;
+}
+/** 换行方式 */
+export type TextWrap = keyof TextWraps;
+/** 字号档位 → fontSizes token */
+export declare const fontSizeStyles: Readonly<{
+    lg: css.CompiledStyles;
+    md: css.CompiledStyles;
+    sm: css.CompiledStyles;
+    xl: css.CompiledStyles;
+    xs: css.CompiledStyles;
+    xxl: css.CompiledStyles;
+    xxxl: css.CompiledStyles;
+}>;
+/**
+ * 相对所在字号的档位（em）：组件内部的小字、标题用它，跟着根上的 size 或所在文字一起缩放。
+ * 比例取主题默认字号（md 14px）下与各档的比值：sm ≈ 13px、xs ≈ 12px、lg ≈ 16px、xl ≈ 18px
+ */
+export declare const relativeFontSizeStyles: Readonly<{
+    lg: css.CompiledStyles;
+    sm: css.CompiledStyles;
+    xl: css.CompiledStyles;
+    xs: css.CompiledStyles;
+}>;
+/** 字重档位 → fontWeights token */
+export declare const fontWeightStyles: Readonly<{
+    bold: css.CompiledStyles;
+    light: css.CompiledStyles;
+    medium: css.CompiledStyles;
+    normal: css.CompiledStyles;
+    semibold: css.CompiledStyles;
+}>;
+/** 色调 → 文字颜色 token */
+export declare const toneStyles: Readonly<{
+    accent: css.CompiledStyles;
+    danger: css.CompiledStyles;
+    info: css.CompiledStyles;
+    inherit: css.CompiledStyles;
+    muted: css.CompiledStyles;
+    neutral: css.CompiledStyles;
+    success: css.CompiledStyles;
+    warning: css.CompiledStyles;
+}>;
+/** 水平对齐（按书写方向） */
+export declare const textAlignStyles: Readonly<{
+    center: css.CompiledStyles;
+    end: css.CompiledStyles;
+    start: css.CompiledStyles;
+}>;
+/** 换行方式（text-wrap） */
+export declare const textWrapStyles: Readonly<{
+    balance: css.CompiledStyles;
+    nowrap: css.CompiledStyles;
+    pretty: css.CompiledStyles;
+    wrap: css.CompiledStyles;
+}>;
+/** 截断：truncate 单行省略，clamp 多行截断（行数见 lineClampStyles） */
+export declare const textStyles: Readonly<{
+    clamp: css.CompiledStyles;
+    mono: css.CompiledStyles;
+    numeric: css.CompiledStyles;
+    truncate: css.CompiledStyles;
+}>;
+/** 多行截断的行数：任意值，用动态样式（编译为 CSS 变量），与 textStyles.clamp 一起用 */
+export declare const lineClampStyles: Readonly<{
+    readonly lines: (count: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;

package/dist/utils/style/typography.js

@@ -0,0 +1,80 @@
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/style/typography.ts
+/**
+* 文字相关的共用样式表：Text、Heading、Icon、Button 等按同一套档位取字号、字重、色调。
+* 档位与主题 tokens 同名（COMPONENTS.md §6.2）。
+*/
+/** 字号档位 → fontSizes token */
+var fontSizeStyles = css.create({
+	xs: { fontSize: "_xs" },
+	sm: { fontSize: "_sm" },
+	md: { fontSize: "_md" },
+	lg: { fontSize: "_lg" },
+	xl: { fontSize: "_xl" },
+	xxl: { fontSize: "_xxl" },
+	xxxl: { fontSize: "_xxxl" }
+});
+/**
+* 相对所在字号的档位（em）：组件内部的小字、标题用它，跟着根上的 size 或所在文字一起缩放。
+* 比例取主题默认字号（md 14px）下与各档的比值：sm ≈ 13px、xs ≈ 12px、lg ≈ 16px、xl ≈ 18px
+*/
+var relativeFontSizeStyles = css.create({
+	xs: { fontSize: "0.86em" },
+	sm: { fontSize: "0.93em" },
+	lg: { fontSize: "1.14em" },
+	xl: { fontSize: "1.29em" }
+});
+/** 字重档位 → fontWeights token */
+var fontWeightStyles = css.create({
+	light: { fontWeight: "_light" },
+	normal: { fontWeight: "_normal" },
+	medium: { fontWeight: "_medium" },
+	semibold: { fontWeight: "_semibold" },
+	bold: { fontWeight: "_bold" }
+});
+/** 色调 → 文字颜色 token */
+var toneStyles = css.create({
+	neutral: { color: "_text" },
+	muted: { color: "_textMuted" },
+	accent: { color: "_accentText" },
+	danger: { color: "_dangerText" },
+	success: { color: "_successText" },
+	warning: { color: "_warningText" },
+	info: { color: "_infoText" },
+	inherit: { color: "inherit" }
+});
+/** 水平对齐（按书写方向） */
+var textAlignStyles = css.create({
+	start: { textAlign: "start" },
+	center: { textAlign: "center" },
+	end: { textAlign: "end" }
+});
+/** 换行方式（text-wrap） */
+var textWrapStyles = css.create({
+	wrap: { textWrap: "wrap" },
+	nowrap: { textWrap: "nowrap" },
+	balance: { textWrap: "balance" },
+	pretty: { textWrap: "pretty" }
+});
+/** 截断：truncate 单行省略，clamp 多行截断（行数见 lineClampStyles） */
+var textStyles = css.create({
+	truncate: {
+		overflow: "hidden",
+		textOverflow: "ellipsis",
+		whiteSpace: "nowrap",
+		minWidth: 0
+	},
+	clamp: {
+		display: "-webkit-box",
+		WebkitBoxOrient: "vertical",
+		overflow: "hidden"
+	},
+	numeric: { fontVariantNumeric: "tabular-nums" },
+	mono: { fontFamily: "_mono" }
+});
+/** 多行截断的行数：任意值，用动态样式（编译为 CSS 变量），与 textStyles.clamp 一起用 */
+var lineClampStyles = css.create({ lines: (count) => ({ WebkitLineClamp: count }) });
+//#endregion
+export { fontSizeStyles, fontWeightStyles, lineClampStyles, relativeFontSizeStyles, textAlignStyles, textStyles, textWrapStyles, toneStyles };
+
+//# sourceMappingURL=typography.js.map

package/dist/utils/style/typography.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typography.js","names":[],"sources":["../../../src/utils/style/typography.ts"],"sourcesContent":["/**\n * 文字相关的共用样式表：Text、Heading、Icon、Button 等按同一套档位取字号、字重、色调。\n * 档位与主题 tokens 同名（COMPONENTS.md §6.2）。\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\n// 取值类型写成带注释接口的 keyof：补全与悬停能看到每个取值的效果（见 styles.ts）\n\n/** 界面文字的字号档位，对应主题的 fontSizes；组件的 size 档位也用它，括号里是默认主题的值 */\nexport interface TextSizes {\n  /** 12px：辅助说明、标签 */\n  xs: unknown;\n  /** 13px：紧凑控件 */\n  sm: unknown;\n  /** 14px：正文与默认控件 */\n  md: unknown;\n  /** 16px：宽松控件、小标题 */\n  lg: unknown;\n  /** 18px：强调文字、卡片标题 */\n  xl: unknown;\n}\n\n/** 字号档位：界面文字的五档，加上标题用的两档 */\nexport interface FontSizes extends TextSizes {\n  /** 24px：页面标题 */\n  xxl: unknown;\n  /** 30px：大标题 */\n  xxxl: unknown;\n}\n\n/** 界面文字的字号档位：xs–xl */\nexport type TextSize = keyof TextSizes;\n/** 字号档位：xs–xl，加上标题用的 xxl、xxxl */\nexport type FontSize = keyof FontSizes;\n\n/** 字重，对应主题的 fontWeights */\nexport interface FontWeights {\n  /** 300：细 */\n  light: unknown;\n  /** 400：正文 */\n  normal: unknown;\n  /** 500：标签、表头 */\n  medium: unknown;\n  /** 600：按钮、标题 */\n  semibold: unknown;\n  /** 700：粗 */\n  bold: unknown;\n}\n\n/** 字重档位 */\nexport type FontWeight = keyof FontWeights;\n\n/**\n * 文字色调，对应主题的文字颜色。与状态色调（StatusTones：neutral、accent、info、success、warning、danger）同名，\n * 再加文字专用的 muted：Text、Link、Icon 与 Button、Badge 写同一个值得到同一种颜色\n */\nexport interface Tones {\n  /** 中性：正文色 */\n  neutral: unknown;\n  /** 次要文字色：说明、辅助信息 */\n  muted: unknown;\n  /** 品牌色文字：链接、强调 */\n  accent: unknown;\n  /** 危险：错误提示、破坏性操作的说明 */\n  danger: unknown;\n  /** 成功 */\n  success: unknown;\n  /** 警告 */\n  warning: unknown;\n  /** 信息 */\n  info: unknown;\n  /** 跟随所在的文字颜色：放在有底色的通栏（Banner 的实底）、标记里时用，对比度由底色保证 */\n  inherit: unknown;\n}\n\n/** 文字色调 */\nexport type Tone = keyof Tones;\n\n/** 文字的水平对齐（text-align），按书写方向 */\nexport interface TextAligns {\n  /** 对齐起始边：从左到右排版时靠左 */\n  start: unknown;\n  /** 居中 */\n  center: unknown;\n  /** 对齐结束边：从左到右排版时靠右 */\n  end: unknown;\n}\n\n/** 水平对齐 */\nexport type TextAlign = keyof TextAligns;\n\n/** 换行方式（text-wrap） */\nexport interface TextWraps {\n  /** 正常换行 */\n  wrap: unknown;\n  /** 不换行，超出容器时溢出（配合 truncate 省略） */\n  nowrap: unknown;\n  /** 各行长度尽量均衡：标题、短文本 */\n  balance: unknown;\n  /** 避免最后一行只剩一个字：段落 */\n  pretty: unknown;\n}\n\n/** 换行方式 */\nexport type TextWrap = keyof TextWraps;\n\n/** 字号档位 → fontSizes token */\nexport const fontSizeStyles = css.create({\n  xs: { fontSize: '_xs' },\n  sm: { fontSize: '_sm' },\n  md: { fontSize: '_md' },\n  lg: { fontSize: '_lg' },\n  xl: { fontSize: '_xl' },\n  xxl: { fontSize: '_xxl' },\n  xxxl: { fontSize: '_xxxl' },\n});\n\n/**\n * 相对所在字号的档位（em）：组件内部的小字、标题用它，跟着根上的 size 或所在文字一起缩放。\n * 比例取主题默认字号（md 14px）下与各档的比值：sm ≈ 13px、xs ≈ 12px、lg ≈ 16px、xl ≈ 18px\n */\nexport const relativeFontSizeStyles = css.create({\n  xs: { fontSize: '0.86em' },\n  sm: { fontSize: '0.93em' },\n  lg: { fontSize: '1.14em' },\n  xl: { fontSize: '1.29em' },\n});\n\n/** 字重档位 → fontWeights token */\nexport const fontWeightStyles = css.create({\n  light: { fontWeight: '_light' },\n  normal: { fontWeight: '_normal' },\n  medium: { fontWeight: '_medium' },\n  semibold: { fontWeight: '_semibold' },\n  bold: { fontWeight: '_bold' },\n});\n\n/** 色调 → 文字颜色 token */\nexport const toneStyles = css.create({\n  neutral: { color: '_text' },\n  muted: { color: '_textMuted' },\n  accent: { color: '_accentText' },\n  danger: { color: '_dangerText' },\n  success: { color: '_successText' },\n  warning: { color: '_warningText' },\n  info: { color: '_infoText' },\n  inherit: { color: 'inherit' },\n});\n\n/** 水平对齐（按书写方向） */\nexport const textAlignStyles = css.create({\n  start: { textAlign: 'start' },\n  center: { textAlign: 'center' },\n  end: { textAlign: 'end' },\n});\n\n/** 换行方式（text-wrap） */\nexport const textWrapStyles = css.create({\n  wrap: { textWrap: 'wrap' },\n  nowrap: { textWrap: 'nowrap' },\n  // 标题：各行长度尽量均衡\n  balance: { textWrap: 'balance' },\n  // 段落：避免最后一行只剩一个字\n  pretty: { textWrap: 'pretty' },\n});\n\n/** 截断：truncate 单行省略，clamp 多行截断（行数见 lineClampStyles） */\nexport const textStyles = css.create({\n  // 单行省略：在块级元素或 flex 子项上生效\n  truncate: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', minWidth: 0 },\n  // 多行截断用带 -webkit- 前缀的写法（标准的 line-clamp 尚无浏览器支持），行数见 lineClampStyles\n  clamp: { display: '-webkit-box', WebkitBoxOrient: 'vertical', overflow: 'hidden' },\n  // 数字等宽：表格、金额、计数上下对齐，变化时不跳动\n  numeric: { fontVariantNumeric: 'tabular-nums' },\n  // 等宽字体：编号、件号、代码片段\n  mono: { fontFamily: '_mono' },\n});\n\n/** 多行截断的行数：任意值，用动态样式（编译为 CSS 变量），与 textStyles.clamp 一起用 */\nexport const lineClampStyles = css.create({\n  lines: (count: number) => ({ WebkitLineClamp: count }),\n});\n"],"mappings":";;;;;;;AA0GA,IAAa,iBAAiB,IAAI,OAAO;CACvC,IAAI,EAAE,UAAU,MAAM;CACtB,IAAI,EAAE,UAAU,MAAM;CACtB,IAAI,EAAE,UAAU,MAAM;CACtB,IAAI,EAAE,UAAU,MAAM;CACtB,IAAI,EAAE,UAAU,MAAM;CACtB,KAAK,EAAE,UAAU,OAAO;CACxB,MAAM,EAAE,UAAU,QAAQ;AAC5B,CAAC;;;;;AAMD,IAAa,yBAAyB,IAAI,OAAO;CAC/C,IAAI,EAAE,UAAU,SAAS;CACzB,IAAI,EAAE,UAAU,SAAS;CACzB,IAAI,EAAE,UAAU,SAAS;CACzB,IAAI,EAAE,UAAU,SAAS;AAC3B,CAAC;;AAGD,IAAa,mBAAmB,IAAI,OAAO;CACzC,OAAO,EAAE,YAAY,SAAS;CAC9B,QAAQ,EAAE,YAAY,UAAU;CAChC,QAAQ,EAAE,YAAY,UAAU;CAChC,UAAU,EAAE,YAAY,YAAY;CACpC,MAAM,EAAE,YAAY,QAAQ;AAC9B,CAAC;;AAGD,IAAa,aAAa,IAAI,OAAO;CACnC,SAAS,EAAE,OAAO,QAAQ;CAC1B,OAAO,EAAE,OAAO,aAAa;CAC7B,QAAQ,EAAE,OAAO,cAAc;CAC/B,QAAQ,EAAE,OAAO,cAAc;CAC/B,SAAS,EAAE,OAAO,eAAe;CACjC,SAAS,EAAE,OAAO,eAAe;CACjC,MAAM,EAAE,OAAO,YAAY;CAC3B,SAAS,EAAE,OAAO,UAAU;AAC9B,CAAC;;AAGD,IAAa,kBAAkB,IAAI,OAAO;CACxC,OAAO,EAAE,WAAW,QAAQ;CAC5B,QAAQ,EAAE,WAAW,SAAS;CAC9B,KAAK,EAAE,WAAW,MAAM;AAC1B,CAAC;;AAGD,IAAa,iBAAiB,IAAI,OAAO;CACvC,MAAM,EAAE,UAAU,OAAO;CACzB,QAAQ,EAAE,UAAU,SAAS;CAE7B,SAAS,EAAE,UAAU,UAAU;CAE/B,QAAQ,EAAE,UAAU,SAAS;AAC/B,CAAC;;AAGD,IAAa,aAAa,IAAI,OAAO;CAEnC,UAAU;EAAE,UAAU;EAAU,cAAc;EAAY,YAAY;EAAU,UAAU;CAAE;CAE5F,OAAO;EAAE,SAAS;EAAe,iBAAiB;EAAY,UAAU;CAAS;CAEjF,SAAS,EAAE,oBAAoB,eAAe;CAE9C,MAAM,EAAE,YAAY,QAAQ;AAC9B,CAAC;;AAGD,IAAa,kBAAkB,IAAI,OAAO,EACxC,QAAQ,WAAmB,EAAE,iBAAiB,MAAM,GACtD,CAAC"}

package/dist/utils/style/vars.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 组件之间约定的 CSS 变量（defineVars）：不属于主题，由外层组件设置、里面的组件读取。
+ * 使用方从子路径 `@zerodep-dev/vue-tsx-pro-ui/vars` 导入（同 tokens），主入口不导出。
+ */
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+/** 布局变量 */
+export declare const layoutVars: css.VarGroup<{
+    /**
+     * 页面顶部被粘性元素（AppShell 的顶栏）挡住的高度：标题的 scroll-margin、粘性侧栏的 top 据此让开，
+     * 锚点跳转后标题不会藏在顶栏下面。AppShell 设置它，默认 0
+     */
+    readonly stickyOffset: "0px";
+}>;
+/** 骨架扫光（shimmer.ts）的变量 */
+export declare const shimmerVars: css.VarGroup<{
+    /** 扫过的那道光带的颜色：默认跟随字色；Skeleton 改成正文色的淡色 */
+    readonly highlight: "color-mix(in oklab, currentColor 12%, transparent)";
+}>;

package/dist/utils/style/vars.js

@@ -0,0 +1,21 @@
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/style/vars.ts
+/**
+* 组件之间约定的 CSS 变量（defineVars）：不属于主题，由外层组件设置、里面的组件读取。
+* 使用方从子路径 `@zerodep-dev/vue-tsx-pro-ui/vars` 导入（同 tokens），主入口不导出。
+*/
+/** 布局变量 */
+var layoutVars = css.defineVars("vtp-layout", { 
+/**
+* 页面顶部被粘性元素（AppShell 的顶栏）挡住的高度：标题的 scroll-margin、粘性侧栏的 top 据此让开，
+* 锚点跳转后标题不会藏在顶栏下面。AppShell 设置它，默认 0
+*/
+stickyOffset: "0px" });
+/** 骨架扫光（shimmer.ts）的变量 */
+var shimmerVars = css.defineVars("vtp-shimmer", { 
+/** 扫过的那道光带的颜色：默认跟随字色；Skeleton 改成正文色的淡色 */
+highlight: "color-mix(in oklab, currentColor 12%, transparent)" });
+//#endregion
+export { layoutVars, shimmerVars };
+
+//# sourceMappingURL=vars.js.map

package/dist/utils/style/vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.js","names":[],"sources":["../../../src/utils/style/vars.ts"],"sourcesContent":["/**\n * 组件之间约定的 CSS 变量（defineVars）：不属于主题，由外层组件设置、里面的组件读取。\n * 使用方从子路径 `@zerodep-dev/vue-tsx-pro-ui/vars` 导入（同 tokens），主入口不导出。\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\n\n/** 布局变量 */\nexport const layoutVars = css.defineVars('vtp-layout', {\n  /**\n   * 页面顶部被粘性元素（AppShell 的顶栏）挡住的高度：标题的 scroll-margin、粘性侧栏的 top 据此让开，\n   * 锚点跳转后标题不会藏在顶栏下面。AppShell 设置它，默认 0\n   */\n  stickyOffset: '0px',\n});\n\n/** 骨架扫光（shimmer.ts）的变量 */\nexport const shimmerVars = css.defineVars('vtp-shimmer', {\n  /** 扫过的那道光带的颜色：默认跟随字色；Skeleton 改成正文色的淡色 */\n  highlight: 'color-mix(in oklab, currentColor 12%, transparent)',\n});\n"],"mappings":";;;;;;;AAOA,IAAa,aAAa,IAAI,WAAW,cAAc;;;;;AAKrD,cAAc,MAChB,CAAC;;AAGD,IAAa,cAAc,IAAI,WAAW,eAAe;;AAEvD,WAAW,qDACb,CAAC"}

package/dist/utils/virtual/use-virtualizer.d.ts

@@ -0,0 +1,43 @@
+import { type ExtractorRange, type VirtualItem, type VirtualScrollOptions, type VisibleRange } from './virtualizer';
+/** useVirtualizer 每次同步时读取的选项 */
+export interface UseVirtualizerOptions {
+    /** 总项数 */
+    count: number;
+    /** 滚动容器：元素或 window；还没挂载时为 null */
+    scrollElement: HTMLElement | Window | null;
+    /** 列表开头所在的元素：它与滚动内容开头的距离就是 scrollMargin（容器内边距、表头、列表上方的内容） */
+    list: HTMLElement | null;
+    /** 第 index 项的估计大小（px） */
+    estimateSize: (index: number) => number;
+    /** 第 index 项的 key；数据会重排、增删时给稳定的 key */
+    getItemKey?: (index: number) => PropertyKey;
+    /** 可见范围前后各多渲染几项 */
+    overscan?: number;
+    /** 横向 */
+    horizontal?: boolean;
+    /** 改写要渲染哪些项：始终渲染高亮项、吸顶行 */
+    rangeExtractor?: (range: ExtractorRange) => number[];
+    /** 视口开头被吸顶的内容遮住的部分（px），滚动时读取：滚动到某项时避开 */
+    scrollPaddingStart?: () => number;
+    /** 视口末尾被吸底的内容遮住的部分（px），滚动时读取 */
+    scrollPaddingEnd?: () => number;
+    /** 可见范围（不含 overscan）变化：接近末尾时加载更多 */
+    onRangeChange?: (range: VisibleRange) => void;
+}
+/** useVirtualizer 的返回值 */
+export interface VirtualView {
+    /** 要渲染的项 */
+    readonly items: readonly VirtualItem[];
+    /** 列表的总大小（px） */
+    readonly total: number;
+    /** 当前可见范围 */
+    readonly range: VisibleRange | null;
+    /** 项的 ref：渲染后测量真实大小（元素要带 data-index） */
+    measure: (element: unknown) => void;
+    /** 滚动到第 index 项 */
+    scrollToIndex: (index: number, options?: VirtualScrollOptions) => void;
+    /** 滚动到相对列表开头的位置 */
+    scrollToOffset: (offset: number, options?: VirtualScrollOptions) => void;
+}
+/** 在组件 setup 里调用 */
+export declare function useVirtualizer(read: () => UseVirtualizerOptions): VirtualView;

package/dist/utils/virtual/use-virtualizer.js

@@ -0,0 +1,94 @@
+import { Virtualizer, isWindow } from "./virtualizer.js";
+import { onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/virtual/use-virtualizer.ts
+/**
+* 虚拟滚动的 Vue 接线：把 Virtualizer（virtualizer.ts，不依赖 Vue）接到组件上。
+* VirtualList、DataTable、TreeDataTable、ListboxView（Select、Combobox 的选项）共用。
+*
+*   const virtual = useVirtualizer(() => ({
+*     count: rows.length,
+*     scrollElement: viewport,           // 滚动容器（元素或 window），就绪前为 null
+*     list: body,                         // 列表开头所在的元素：据此算 scrollMargin
+*     estimateSize: () => 40,
+*     getItemKey: (index) => rows[index]!.id,
+*   }));
+*   virtual.items / virtual.total         渲染：只渲染这些项，列表撑到 total 高
+*   ref={virtual.measure}                 每一项的元素：渲染后测量真实大小
+*
+* read 在 watch 里读取：其中读到的响应式数据（行数、key）变化时重新同步；
+* 选项里的函数（estimateSize、onRangeChange）不在这时调用，它们读到的数据不会变成依赖。
+*/
+/** 在组件 setup 里调用 */
+function useVirtualizer(read) {
+	const view = shallowRef({
+		items: [],
+		total: 0,
+		range: null
+	});
+	let current = read();
+	let reported = null;
+	function build(options) {
+		return {
+			count: options.count,
+			overscan: options.overscan,
+			horizontal: options.horizontal,
+			estimateSize: options.estimateSize,
+			getItemKey: options.getItemKey,
+			rangeExtractor: options.rangeExtractor,
+			scrollPaddingStart: () => current.scrollPaddingStart?.() ?? 0,
+			scrollPaddingEnd: () => current.scrollPaddingEnd?.() ?? 0,
+			getScrollElement: () => current.scrollElement,
+			scrollMargin: () => {
+				const { list, scrollElement, horizontal } = current;
+				if (!list || !scrollElement) return 0;
+				const listRect = list.getBoundingClientRect();
+				if (isWindow(scrollElement)) return horizontal ? listRect.left + window.scrollX : listRect.top + window.scrollY;
+				const rootRect = scrollElement.getBoundingClientRect();
+				return horizontal ? listRect.left - rootRect.left + scrollElement.scrollLeft : listRect.top - rootRect.top + scrollElement.scrollTop;
+			},
+			onChange: (changed) => {
+				const range = changed.getVisibleRange();
+				view.value = {
+					items: changed.getVirtualItems(),
+					total: changed.getTotalSize(),
+					range
+				};
+				if (!range || range.startIndex === reported?.startIndex && range.endIndex === reported.endIndex) return;
+				reported = range;
+				current.onRangeChange?.(range);
+			}
+		};
+	}
+	const virtualizer = new Virtualizer(build(current));
+	watch(read, (next) => {
+		current = next;
+		virtualizer.setOptions(build(next));
+	});
+	let unmount;
+	watch(() => read().scrollElement, (element) => {
+		unmount?.();
+		unmount = element ? virtualizer.mount() : void 0;
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	onScopeDispose(() => unmount?.());
+	return {
+		get items() {
+			return view.value.items;
+		},
+		get total() {
+			return view.value.total;
+		},
+		get range() {
+			return view.value.range;
+		},
+		measure: virtualizer.measureElement,
+		scrollToIndex: (index, options) => virtualizer.scrollToIndex(index, options),
+		scrollToOffset: (offset, options) => virtualizer.scrollToOffset(offset, options)
+	};
+}
+//#endregion
+export { useVirtualizer };
+
+//# sourceMappingURL=use-virtualizer.js.map

package/dist/utils/virtual/use-virtualizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-virtualizer.js","names":[],"sources":["../../../src/utils/virtual/use-virtualizer.ts"],"sourcesContent":["/**\n * 虚拟滚动的 Vue 接线：把 Virtualizer（virtualizer.ts，不依赖 Vue）接到组件上。\n * VirtualList、DataTable、TreeDataTable、ListboxView（Select、Combobox 的选项）共用。\n *\n *   const virtual = useVirtualizer(() => ({\n *     count: rows.length,\n *     scrollElement: viewport,           // 滚动容器（元素或 window），就绪前为 null\n *     list: body,                         // 列表开头所在的元素：据此算 scrollMargin\n *     estimateSize: () => 40,\n *     getItemKey: (index) => rows[index]!.id,\n *   }));\n *   virtual.items / virtual.total         渲染：只渲染这些项，列表撑到 total 高\n *   ref={virtual.measure}                 每一项的元素：渲染后测量真实大小\n *\n * read 在 watch 里读取：其中读到的响应式数据（行数、key）变化时重新同步；\n * 选项里的函数（estimateSize、onRangeChange）不在这时调用，它们读到的数据不会变成依赖。\n */\nimport { onScopeDispose, shallowRef, watch } from 'vue';\nimport {\n  isWindow,\n  Virtualizer,\n  type ExtractorRange,\n  type VirtualItem,\n  type VirtualScrollOptions,\n  type VisibleRange,\n} from './virtualizer';\n\n/** useVirtualizer 每次同步时读取的选项 */\nexport interface UseVirtualizerOptions {\n  /** 总项数 */\n  count: number;\n  /** 滚动容器：元素或 window；还没挂载时为 null */\n  scrollElement: HTMLElement | Window | null;\n  /** 列表开头所在的元素：它与滚动内容开头的距离就是 scrollMargin（容器内边距、表头、列表上方的内容） */\n  list: HTMLElement | null;\n  /** 第 index 项的估计大小（px） */\n  estimateSize: (index: number) => number;\n  /** 第 index 项的 key；数据会重排、增删时给稳定的 key */\n  getItemKey?: (index: number) => PropertyKey;\n  /** 可见范围前后各多渲染几项 */\n  overscan?: number;\n  /** 横向 */\n  horizontal?: boolean;\n  /** 改写要渲染哪些项：始终渲染高亮项、吸顶行 */\n  rangeExtractor?: (range: ExtractorRange) => number[];\n  /** 视口开头被吸顶的内容遮住的部分（px），滚动时读取：滚动到某项时避开 */\n  scrollPaddingStart?: () => number;\n  /** 视口末尾被吸底的内容遮住的部分（px），滚动时读取 */\n  scrollPaddingEnd?: () => number;\n  /** 可见范围（不含 overscan）变化：接近末尾时加载更多 */\n  onRangeChange?: (range: VisibleRange) => void;\n}\n\n/** useVirtualizer 的返回值 */\nexport interface VirtualView {\n  /** 要渲染的项 */\n  readonly items: readonly VirtualItem[];\n  /** 列表的总大小（px） */\n  readonly total: number;\n  /** 当前可见范围 */\n  readonly range: VisibleRange | null;\n  /** 项的 ref：渲染后测量真实大小（元素要带 data-index） */\n  measure: (element: unknown) => void;\n  /** 滚动到第 index 项 */\n  scrollToIndex: (index: number, options?: VirtualScrollOptions) => void;\n  /** 滚动到相对列表开头的位置 */\n  scrollToOffset: (offset: number, options?: VirtualScrollOptions) => void;\n}\n\n/** 在组件 setup 里调用 */\nexport function useVirtualizer(read: () => UseVirtualizerOptions): VirtualView {\n  // 渲染需要的只有这些；滚动本身不触发重新渲染\n  const view = shallowRef<{ items: VirtualItem[]; total: number; range: VisibleRange | null }>({\n    items: [],\n    total: 0,\n    range: null,\n  });\n  let current = read();\n  let reported: VisibleRange | null = null;\n\n  function build(options: UseVirtualizerOptions) {\n    return {\n      count: options.count,\n      overscan: options.overscan,\n      horizontal: options.horizontal,\n      estimateSize: options.estimateSize,\n      getItemKey: options.getItemKey,\n      rangeExtractor: options.rangeExtractor,\n      scrollPaddingStart: () => current.scrollPaddingStart?.() ?? 0,\n      scrollPaddingEnd: () => current.scrollPaddingEnd?.() ?? 0,\n      getScrollElement: () => current.scrollElement,\n      scrollMargin: () => {\n        const { list, scrollElement, horizontal } = current;\n        if (!list || !scrollElement) return 0;\n        const listRect = list.getBoundingClientRect();\n        if (isWindow(scrollElement)) {\n          return horizontal ? listRect.left + window.scrollX : listRect.top + window.scrollY;\n        }\n        const rootRect = scrollElement.getBoundingClientRect();\n        return horizontal\n          ? listRect.left - rootRect.left + scrollElement.scrollLeft\n          : listRect.top - rootRect.top + scrollElement.scrollTop;\n      },\n      onChange: (changed: Virtualizer) => {\n        const range = changed.getVisibleRange();\n        view.value = { items: changed.getVirtualItems(), total: changed.getTotalSize(), range };\n        // 测量也会触发 onChange，可见范围没变时不报告\n        if (\n          !range ||\n          (range.startIndex === reported?.startIndex && range.endIndex === reported.endIndex)\n        ) {\n          return;\n        }\n        reported = range;\n        current.onRangeChange?.(range);\n      },\n    };\n  }\n\n  const virtualizer = new Virtualizer(build(current));\n\n  watch(read, (next) => {\n    current = next;\n    virtualizer.setOptions(build(next));\n  });\n\n  // 滚动容器就绪（或换了）时挂载：监听滚动与大小\n  let unmount: (() => void) | undefined;\n  watch(\n    () => read().scrollElement,\n    (element) => {\n      unmount?.();\n      unmount = element ? virtualizer.mount() : undefined;\n    },\n    { immediate: true, flush: 'post' },\n  );\n  onScopeDispose(() => unmount?.());\n\n  return {\n    get items() {\n      return view.value.items;\n    },\n    get total() {\n      return view.value.total;\n    },\n    get range() {\n      return view.value.range;\n    },\n    measure: virtualizer.measureElement as (element: unknown) => void,\n    scrollToIndex: (index, options) => virtualizer.scrollToIndex(index, options),\n    scrollToOffset: (offset, options) => virtualizer.scrollToOffset(offset, options),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,eAAe,MAAgD;CAE7E,MAAM,OAAO,WAAgF;EAC3F,OAAO,CAAC;EACR,OAAO;EACP,OAAO;CACT,CAAC;CACD,IAAI,UAAU,KAAK;CACnB,IAAI,WAAgC;CAEpC,SAAS,MAAM,SAAgC;EAC7C,OAAO;GACL,OAAO,QAAQ;GACf,UAAU,QAAQ;GAClB,YAAY,QAAQ;GACpB,cAAc,QAAQ;GACtB,YAAY,QAAQ;GACpB,gBAAgB,QAAQ;GACxB,0BAA0B,QAAQ,qBAAqB,KAAK;GAC5D,wBAAwB,QAAQ,mBAAmB,KAAK;GACxD,wBAAwB,QAAQ;GAChC,oBAAoB;IAClB,MAAM,EAAE,MAAM,eAAe,eAAe;IAC5C,IAAI,CAAC,QAAQ,CAAC,eAAe,OAAO;IACpC,MAAM,WAAW,KAAK,sBAAsB;IAC5C,IAAI,SAAS,aAAa,GACxB,OAAO,aAAa,SAAS,OAAO,OAAO,UAAU,SAAS,MAAM,OAAO;IAE7E,MAAM,WAAW,cAAc,sBAAsB;IACrD,OAAO,aACH,SAAS,OAAO,SAAS,OAAO,cAAc,aAC9C,SAAS,MAAM,SAAS,MAAM,cAAc;GAClD;GACA,WAAW,YAAyB;IAClC,MAAM,QAAQ,QAAQ,gBAAgB;IACtC,KAAK,QAAQ;KAAE,OAAO,QAAQ,gBAAgB;KAAG,OAAO,QAAQ,aAAa;KAAG;IAAM;IAEtF,IACE,CAAC,SACA,MAAM,eAAe,UAAU,cAAc,MAAM,aAAa,SAAS,UAE1E;IAEF,WAAW;IACX,QAAQ,gBAAgB,KAAK;GAC/B;EACF;CACF;CAEA,MAAM,cAAc,IAAI,YAAY,MAAM,OAAO,CAAC;CAElD,MAAM,OAAO,SAAS;EACpB,UAAU;EACV,YAAY,WAAW,MAAM,IAAI,CAAC;CACpC,CAAC;CAGD,IAAI;CACJ,YACQ,KAAK,CAAC,CAAC,gBACZ,YAAY;EACX,UAAU;EACV,UAAU,UAAU,YAAY,MAAM,IAAI,KAAA;CAC5C,GACA;EAAE,WAAW;EAAM,OAAO;CAAO,CACnC;CACA,qBAAqB,UAAU,CAAC;CAEhC,OAAO;EACL,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,IAAI,QAAQ;GACV,OAAO,KAAK,MAAM;EACpB;EACA,SAAS,YAAY;EACrB,gBAAgB,OAAO,YAAY,YAAY,cAAc,OAAO,OAAO;EAC3E,iBAAiB,QAAQ,YAAY,YAAY,eAAe,QAAQ,OAAO;CACjF;AACF"}