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

package/dist/utils/dom/resize.js

@@ -0,0 +1,65 @@
+import { watch } from "vue";
+//#region src/utils/dom/resize.ts
+/**
+* 元素大小变化时回调（ResizeObserver）：目标换了自动改观察对象，卸载时断开。在 setup 里调用。
+*
+*   useResizeObserver(() => [viewport, content], sync)
+*
+* 整个应用共用一个 ResizeObserver：同一轮的变化在一次通知里交给各个回调，回调之间不穿插微任务（Vue 的更新），
+* 回调里用 batchLayout 先读后写时，所有组件的读取合并成一次布局。各用各的观察器时，每个回调之后都会先跑一遍
+* Vue 的更新，下一个回调一读布局就要重新排版（一页十几个滚动区域就是十几次）。
+*
+* 回调里同步改布局会触发 “ResizeObserver loop completed with undelivered notifications”：
+* 要改位置、尺寸时放到下一帧（active-indicator、Virtualizer 都这样做）。
+*/
+var handlers = /* @__PURE__ */ new Map();
+var shared;
+function sharedObserver() {
+	shared ??= new ResizeObserver((entries) => {
+		const byHandler = /* @__PURE__ */ new Map();
+		for (const entry of entries) for (const handler of handlers.get(entry.target) ?? []) {
+			const list = byHandler.get(handler);
+			if (list) list.push(entry);
+			else byHandler.set(handler, [entry]);
+		}
+		for (const [handler, list] of byHandler) try {
+			handler(list);
+		} catch (error) {
+			queueMicrotask(() => {
+				throw error;
+			});
+		}
+	});
+	return shared;
+}
+function observe(element, handler) {
+	const set = handlers.get(element) ?? /* @__PURE__ */ new Set();
+	handlers.set(element, set);
+	set.add(handler);
+	sharedObserver().observe(element);
+}
+function unobserve(element, handler) {
+	const set = handlers.get(element);
+	set?.delete(handler);
+	if (set?.size) return;
+	handlers.delete(element);
+	shared?.unobserve(element);
+}
+/** 观察一个或几个元素的大小；targets 在渲染后读取，读到 null 的跳过 */
+function useResizeObserver(targets, onResize) {
+	const handler = (entries) => onResize(entries);
+	watch(() => [targets()].flat().filter((element) => element != null), (elements, _, onCleanup) => {
+		if (!elements.length || typeof ResizeObserver === "undefined") return;
+		for (const element of elements) observe(element, handler);
+		onCleanup(() => {
+			for (const element of elements) unobserve(element, handler);
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+}
+//#endregion
+export { useResizeObserver };
+
+//# sourceMappingURL=resize.js.map

package/dist/utils/dom/resize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize.js","names":[],"sources":["../../../src/utils/dom/resize.ts"],"sourcesContent":["/**\n * 元素大小变化时回调（ResizeObserver）：目标换了自动改观察对象，卸载时断开。在 setup 里调用。\n *\n *   useResizeObserver(() => [viewport, content], sync)\n *\n * 整个应用共用一个 ResizeObserver：同一轮的变化在一次通知里交给各个回调，回调之间不穿插微任务（Vue 的更新），\n * 回调里用 batchLayout 先读后写时，所有组件的读取合并成一次布局。各用各的观察器时，每个回调之后都会先跑一遍\n * Vue 的更新，下一个回调一读布局就要重新排版（一页十几个滚动区域就是十几次）。\n *\n * 回调里同步改布局会触发 “ResizeObserver loop completed with undelivered notifications”：\n * 要改位置、尺寸时放到下一帧（active-indicator、Virtualizer 都这样做）。\n */\nimport { watch } from 'vue';\n\ntype Target = Element | null | undefined;\ntype Handler = (entries: ResizeObserverEntry[]) => void;\n\nconst handlers = new Map<Element, Set<Handler>>();\nlet shared: ResizeObserver | undefined;\n\nfunction sharedObserver() {\n  shared ??= new ResizeObserver((entries) => {\n    const byHandler = new Map<Handler, ResizeObserverEntry[]>();\n    for (const entry of entries) {\n      for (const handler of handlers.get(entry.target) ?? []) {\n        const list = byHandler.get(handler);\n        if (list) list.push(entry);\n        else byHandler.set(handler, [entry]);\n      }\n    }\n    // 一个回调出错不挡别的：报出来（下一个微任务里抛出），其余照常收到通知\n    for (const [handler, list] of byHandler) {\n      try {\n        handler(list);\n      } catch (error) {\n        queueMicrotask(() => {\n          throw error;\n        });\n      }\n    }\n  });\n  return shared;\n}\n\nfunction observe(element: Element, handler: Handler) {\n  const set = handlers.get(element) ?? new Set();\n  handlers.set(element, set);\n  set.add(handler);\n  // 已经在观察的元素重新 observe：新的回调也收到一次初始的大小\n  sharedObserver().observe(element);\n}\n\nfunction unobserve(element: Element, handler: Handler) {\n  const set = handlers.get(element);\n  set?.delete(handler);\n  if (set?.size) return;\n  handlers.delete(element);\n  shared?.unobserve(element);\n}\n\n/** 观察一个或几个元素的大小；targets 在渲染后读取，读到 null 的跳过 */\nexport function useResizeObserver(\n  targets: () => Target | readonly Target[],\n  onResize: (entries: ResizeObserverEntry[]) => void,\n): void {\n  // 每次调用一个独立的回调：同一个函数被几个组件传进来时各算各的\n  const handler: Handler = (entries) => onResize(entries);\n  watch(\n    () => [targets()].flat().filter((element): element is Element => element != null),\n    (elements, _, onCleanup) => {\n      if (!elements.length || typeof ResizeObserver === 'undefined') return;\n      for (const element of elements) observe(element, handler);\n      onCleanup(() => {\n        for (const element of elements) unobserve(element, handler);\n      });\n    },\n    { immediate: true, flush: 'post' },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,IAAM,2BAAW,IAAI,IAA2B;AAChD,IAAI;AAEJ,SAAS,iBAAiB;CACxB,WAAW,IAAI,gBAAgB,YAAY;EACzC,MAAM,4BAAY,IAAI,IAAoC;EAC1D,KAAK,MAAM,SAAS,SAClB,KAAK,MAAM,WAAW,SAAS,IAAI,MAAM,MAAM,KAAK,CAAC,GAAG;GACtD,MAAM,OAAO,UAAU,IAAI,OAAO;GAClC,IAAI,MAAM,KAAK,KAAK,KAAK;QACpB,UAAU,IAAI,SAAS,CAAC,KAAK,CAAC;EACrC;EAGF,KAAK,MAAM,CAAC,SAAS,SAAS,WAC5B,IAAI;GACF,QAAQ,IAAI;EACd,SAAS,OAAO;GACd,qBAAqB;IACnB,MAAM;GACR,CAAC;EACH;CAEJ,CAAC;CACD,OAAO;AACT;AAEA,SAAS,QAAQ,SAAkB,SAAkB;CACnD,MAAM,MAAM,SAAS,IAAI,OAAO,qBAAK,IAAI,IAAI;CAC7C,SAAS,IAAI,SAAS,GAAG;CACzB,IAAI,IAAI,OAAO;CAEf,eAAe,CAAC,CAAC,QAAQ,OAAO;AAClC;AAEA,SAAS,UAAU,SAAkB,SAAkB;CACrD,MAAM,MAAM,SAAS,IAAI,OAAO;CAChC,KAAK,OAAO,OAAO;CACnB,IAAI,KAAK,MAAM;CACf,SAAS,OAAO,OAAO;CACvB,QAAQ,UAAU,OAAO;AAC3B;;AAGA,SAAgB,kBACd,SACA,UACM;CAEN,MAAM,WAAoB,YAAY,SAAS,OAAO;CACtD,YACQ,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,YAAgC,WAAW,IAAI,IAC/E,UAAU,GAAG,cAAc;EAC1B,IAAI,CAAC,SAAS,UAAU,OAAO,mBAAmB,aAAa;EAC/D,KAAK,MAAM,WAAW,UAAU,QAAQ,SAAS,OAAO;EACxD,gBAAgB;GACd,KAAK,MAAM,WAAW,UAAU,UAAU,SAAS,OAAO;EAC5D,CAAC;CACH,GACA;EAAE,WAAW;EAAM,OAAO;CAAO,CACnC;AACF"}

package/dist/utils/dom/ripple.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 波纹：按下时从指针位置扩散出一圈半透明的颜色，松开后淡出（键盘按下 Enter / 空格时从中心扩散）。
+ * 纯 CSS 动画，时长取主题的 durations：开启“减少动态效果”时没有扩散过程，只是按下时变色。
+ * 按钮、导航项、菜单项等可点击的组件共用；宿主元素加 rippleHostStyles.host（定位与裁切）。
+ * 默认开启，createUi / Provider 的 ripple 全局开关，组件的 ripple prop 单独覆盖（见 useRipple）。
+ *
+ *   const ripple = useRipple(() => props.ripple)
+ *   mergeAttrs<'button'>(默认, rest, { ...ripple })
+ */
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+/** 宿主元素需要的样式：波纹相对它定位，超出圆角的部分裁掉 */
+export declare const rippleHostStyles: Readonly<{
+    host: css.CompiledStyles;
+}>;
+/** 波纹 的样式：ripple、fading */
+export declare const rippleStyles: Readonly<{
+    fading: css.CompiledStyles;
+    ripple: css.CompiledStyles;
+}>;
+/** 波纹 的样式：at */
+export declare const ripplePlacementStyles: Readonly<{
+    readonly at: (x: number, y: number, size: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;
+/** useRipple 的结果：展开到宿主元素上（mergeProps 的受管层） */
+export interface RippleHandlers {
+    /** 指针按下：从按下的位置扩散 */
+    onPointerdown: (event: PointerEvent) => void;
+    /** Enter / 空格：从中心扩散 */
+    onKeydown: (event: KeyboardEvent) => void;
+}
+/**
+ * 组件里用的波纹：按开关决定是否出波纹，返回的两个处理函数展开到宿主元素上（`...ripple`）。
+ * own 读组件自己的 ripple prop（没写时为 undefined，沿用配置）；在 setup 里调用
+ */
+export declare function useRipple(own: () => boolean | undefined): RippleHandlers;
+/**
+ * 在 event.currentTarget 上开始一个波纹，松开、移出、取消或失去焦点时淡出并移除。
+ * 键盘事件只认 Enter 与空格（按住不放的重复事件忽略）。
+ */
+export declare function startRipple(event: PointerEvent | KeyboardEvent): void;

package/dist/utils/dom/ripple.js

@@ -0,0 +1,96 @@
+import { t } from "../../config/theme/tokens.js";
+import { useConfig } from "../../config/context.js";
+import { applyStyleAttrs } from "../props.js";
+import { afterTransitions } from "../style/transitions.js";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/dom/ripple.ts
+/**
+* 波纹：按下时从指针位置扩散出一圈半透明的颜色，松开后淡出（键盘按下 Enter / 空格时从中心扩散）。
+* 纯 CSS 动画，时长取主题的 durations：开启“减少动态效果”时没有扩散过程，只是按下时变色。
+* 按钮、导航项、菜单项等可点击的组件共用；宿主元素加 rippleHostStyles.host（定位与裁切）。
+* 默认开启，createUi / Provider 的 ripple 全局开关，组件的 ripple prop 单独覆盖（见 useRipple）。
+*
+*   const ripple = useRipple(() => props.ripple)
+*   mergeAttrs<'button'>(默认, rest, { ...ripple })
+*/
+var expand = css.keyframes({
+	from: { transform: "scale(0)" },
+	to: { transform: "scale(1)" }
+});
+/** 宿主元素需要的样式：波纹相对它定位，超出圆角的部分裁掉 */
+var rippleHostStyles = css.create({ host: {
+	position: "relative",
+	overflow: "hidden"
+} });
+/** 波纹 的样式：ripple、fading */
+var rippleStyles = css.create({
+	ripple: {
+		position: "absolute",
+		borderRadius: "_full",
+		pointerEvents: "none",
+		backgroundColor: "color-mix(in srgb, currentColor 22%, transparent)",
+		animationName: expand,
+		animationDuration: "_durations.lg",
+		animationTimingFunction: "_easings.standard",
+		animationFillMode: "forwards",
+		transition: `opacity ${t.durations.md} ${t.easings.exit}`
+	},
+	fading: { opacity: 0 }
+});
+/** 波纹 的样式：at */
+var ripplePlacementStyles = css.create({ at: (x, y, size) => ({
+	left: x,
+	top: y,
+	width: size,
+	height: size
+}) });
+/**
+* 组件里用的波纹：按开关决定是否出波纹，返回的两个处理函数展开到宿主元素上（`...ripple`）。
+* own 读组件自己的 ripple prop（没写时为 undefined，沿用配置）；在 setup 里调用
+*/
+function useRipple(own) {
+	const config = useConfig();
+	const handler = (event) => {
+		if (own() ?? config.ripple) startRipple(event);
+	};
+	return {
+		onPointerdown: handler,
+		onKeydown: handler
+	};
+}
+/** 不可用的宿主不出波纹 */
+var isDisabled = (host) => host.matches(":disabled, [aria-disabled=\"true\"]");
+/**
+* 在 event.currentTarget 上开始一个波纹，松开、移出、取消或失去焦点时淡出并移除。
+* 键盘事件只认 Enter 与空格（按住不放的重复事件忽略）。
+*/
+function startRipple(event) {
+	const host = event.currentTarget;
+	if (!(host instanceof HTMLElement) || isDisabled(host)) return;
+	const keyboard = event instanceof KeyboardEvent;
+	if (keyboard && (event.repeat || event.key !== "Enter" && event.key !== " ")) return;
+	if (!keyboard && event.button !== 0) return;
+	const rect = host.getBoundingClientRect();
+	const x = keyboard ? rect.width / 2 : event.clientX - rect.left;
+	const y = keyboard ? rect.height / 2 : event.clientY - rect.top;
+	const radius = Math.hypot(Math.max(x, rect.width - x), Math.max(y, rect.height - y));
+	const ripple = document.createElement("span");
+	ripple.setAttribute("aria-hidden", "true");
+	applyStyleAttrs(ripple, css.attrs(rippleStyles.ripple, ripplePlacementStyles.at(x - radius, y - radius, radius * 2)));
+	host.append(ripple);
+	const release = () => {
+		for (const [type, target] of releaseEvents) target.removeEventListener(type, release);
+		ripple.classList.add(...(css.attrs(rippleStyles.fading).class ?? "").split(" "));
+		afterTransitions(ripple).then(() => ripple.remove());
+	};
+	const releaseEvents = keyboard ? [["keyup", host], ["blur", host]] : [
+		["pointerup", window],
+		["pointercancel", window],
+		["pointerleave", host]
+	];
+	for (const [type, target] of releaseEvents) target.addEventListener(type, release);
+}
+//#endregion
+export { rippleHostStyles, ripplePlacementStyles, rippleStyles, startRipple, useRipple };
+
+//# sourceMappingURL=ripple.js.map

package/dist/utils/dom/ripple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.js","names":[],"sources":["../../../src/utils/dom/ripple.ts"],"sourcesContent":["/**\n * 波纹：按下时从指针位置扩散出一圈半透明的颜色，松开后淡出（键盘按下 Enter / 空格时从中心扩散）。\n * 纯 CSS 动画，时长取主题的 durations：开启“减少动态效果”时没有扩散过程，只是按下时变色。\n * 按钮、导航项、菜单项等可点击的组件共用；宿主元素加 rippleHostStyles.host（定位与裁切）。\n * 默认开启，createUi / Provider 的 ripple 全局开关，组件的 ripple prop 单独覆盖（见 useRipple）。\n *\n *   const ripple = useRipple(() => props.ripple)\n *   mergeAttrs<'button'>(默认, rest, { ...ripple })\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { useConfig } from '../../config/context';\nimport { applyStyleAttrs } from '../props';\nimport { afterTransitions } from '../style/transitions';\nimport { t } from '../../config/theme/tokens';\n\nconst expand = css.keyframes({\n  from: { transform: 'scale(0)' },\n  to: { transform: 'scale(1)' },\n});\n\n/** 宿主元素需要的样式：波纹相对它定位，超出圆角的部分裁掉 */\nexport const rippleHostStyles = css.create({\n  host: { position: 'relative', overflow: 'hidden' },\n});\n\n/** 波纹 的样式：ripple、fading */\nexport const rippleStyles = css.create({\n  ripple: {\n    position: 'absolute',\n    borderRadius: '_full',\n    pointerEvents: 'none',\n    // 跟随文字颜色：实底按钮上是浅色，描边按钮上是深色\n    backgroundColor: 'color-mix(in srgb, currentColor 22%, transparent)',\n    animationName: expand,\n    animationDuration: '_durations.lg',\n    animationTimingFunction: '_easings.standard',\n    animationFillMode: 'forwards',\n    transition: `opacity ${t.durations.md} ${t.easings.exit}`,\n  },\n  fading: { opacity: 0 },\n});\n\n// 位置与大小是任意值，用动态样式；单独一个 create，见 COMPONENTS.md §4\n/** 波纹 的样式：at */\nexport const ripplePlacementStyles = css.create({\n  at: (x: number, y: number, size: number) => ({ left: x, top: y, width: size, height: size }),\n});\n\n/** useRipple 的结果：展开到宿主元素上（mergeProps 的受管层） */\nexport interface RippleHandlers {\n  /** 指针按下：从按下的位置扩散 */\n  onPointerdown: (event: PointerEvent) => void;\n  /** Enter / 空格：从中心扩散 */\n  onKeydown: (event: KeyboardEvent) => void;\n}\n\n/**\n * 组件里用的波纹：按开关决定是否出波纹，返回的两个处理函数展开到宿主元素上（`...ripple`）。\n * own 读组件自己的 ripple prop（没写时为 undefined，沿用配置）；在 setup 里调用\n */\nexport function useRipple(own: () => boolean | undefined): RippleHandlers {\n  const config = useConfig();\n  const handler = (event: PointerEvent | KeyboardEvent) => {\n    if (own() ?? config.ripple) startRipple(event);\n  };\n  return { onPointerdown: handler, onKeydown: handler };\n}\n\n/** 不可用的宿主不出波纹 */\nconst isDisabled = (host: Element) => host.matches(':disabled, [aria-disabled=\"true\"]');\n\n/**\n * 在 event.currentTarget 上开始一个波纹，松开、移出、取消或失去焦点时淡出并移除。\n * 键盘事件只认 Enter 与空格（按住不放的重复事件忽略）。\n */\nexport function startRipple(event: PointerEvent | KeyboardEvent): void {\n  const host = event.currentTarget;\n  if (!(host instanceof HTMLElement) || isDisabled(host)) return;\n  const keyboard = event instanceof KeyboardEvent;\n  if (keyboard && (event.repeat || (event.key !== 'Enter' && event.key !== ' '))) return;\n  if (!keyboard && event.button !== 0) return;\n\n  const rect = host.getBoundingClientRect();\n  const x = keyboard ? rect.width / 2 : event.clientX - rect.left;\n  const y = keyboard ? rect.height / 2 : event.clientY - rect.top;\n  // 圆心到最远的角的距离：扩散完正好盖满整个元素\n  const radius = Math.hypot(Math.max(x, rect.width - x), Math.max(y, rect.height - y));\n  const ripple = document.createElement('span');\n  ripple.setAttribute('aria-hidden', 'true');\n  applyStyleAttrs(\n    ripple,\n    css.attrs(rippleStyles.ripple, ripplePlacementStyles.at(x - radius, y - radius, radius * 2)),\n  );\n  host.append(ripple);\n\n  const release = () => {\n    for (const [type, target] of releaseEvents) target.removeEventListener(type, release);\n    ripple.classList.add(...(css.attrs(rippleStyles.fading).class ?? '').split(' '));\n    void afterTransitions(ripple).then(() => ripple.remove());\n  };\n  const releaseEvents: [string, EventTarget][] = keyboard\n    ? [\n        ['keyup', host],\n        ['blur', host],\n      ]\n    : [\n        ['pointerup', window],\n        ['pointercancel', window],\n        ['pointerleave', host],\n      ];\n  for (const [type, target] of releaseEvents) target.addEventListener(type, release);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,IAAM,SAAS,IAAI,UAAU;CAC3B,MAAM,EAAE,WAAW,WAAW;CAC9B,IAAI,EAAE,WAAW,WAAW;AAC9B,CAAC;;AAGD,IAAa,mBAAmB,IAAI,OAAO,EACzC,MAAM;CAAE,UAAU;CAAY,UAAU;AAAS,EACnD,CAAC;;AAGD,IAAa,eAAe,IAAI,OAAO;CACrC,QAAQ;EACN,UAAU;EACV,cAAc;EACd,eAAe;EAEf,iBAAiB;EACjB,eAAe;EACf,mBAAmB;EACnB,yBAAyB;EACzB,mBAAmB;EACnB,YAAY,WAAW,EAAE,UAAU,GAAE,GAAI,EAAE,QAAQ;CACrD;CACA,QAAQ,EAAE,SAAS,EAAE;AACvB,CAAC;;AAID,IAAa,wBAAwB,IAAI,OAAO,EAC9C,KAAK,GAAW,GAAW,UAAkB;CAAE,MAAM;CAAG,KAAK;CAAG,OAAO;CAAM,QAAQ;AAAK,GAC5F,CAAC;;;;;AAcD,SAAgB,UAAU,KAAgD;CACxE,MAAM,SAAS,UAAU;CACzB,MAAM,WAAW,UAAwC;EACvD,IAAI,IAAI,KAAK,OAAO,QAAQ,YAAY,KAAK;CAC/C;CACA,OAAO;EAAE,eAAe;EAAS,WAAW;CAAQ;AACtD;;AAGA,IAAM,cAAc,SAAkB,KAAK,QAAQ,qCAAmC;;;;;AAMtF,SAAgB,YAAY,OAA2C;CACrE,MAAM,OAAO,MAAM;CACnB,IAAI,EAAE,gBAAgB,gBAAgB,WAAW,IAAI,GAAG;CACxD,MAAM,WAAW,iBAAiB;CAClC,IAAI,aAAa,MAAM,UAAW,MAAM,QAAQ,WAAW,MAAM,QAAQ,MAAO;CAChF,IAAI,CAAC,YAAY,MAAM,WAAW,GAAG;CAErC,MAAM,OAAO,KAAK,sBAAsB;CACxC,MAAM,IAAI,WAAW,KAAK,QAAQ,IAAI,MAAM,UAAU,KAAK;CAC3D,MAAM,IAAI,WAAW,KAAK,SAAS,IAAI,MAAM,UAAU,KAAK;CAE5D,MAAM,SAAS,KAAK,MAAM,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC,GAAG,KAAK,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC;CACnF,MAAM,SAAS,SAAS,cAAc,MAAM;CAC5C,OAAO,aAAa,eAAe,MAAM;CACzC,gBACE,QACA,IAAI,MAAM,aAAa,QAAQ,sBAAsB,GAAG,IAAI,QAAQ,IAAI,QAAQ,SAAS,CAAC,CAAC,CAC7F;CACA,KAAK,OAAO,MAAM;CAElB,MAAM,gBAAgB;EACpB,KAAK,MAAM,CAAC,MAAM,WAAW,eAAe,OAAO,oBAAoB,MAAM,OAAO;EACpF,OAAO,UAAU,IAAI,IAAI,IAAI,MAAM,aAAa,MAAM,CAAC,CAAC,SAAS,GAAA,CAAI,MAAM,GAAG,CAAC;EAC/E,iBAAsB,MAAM,CAAC,CAAC,WAAW,OAAO,OAAO,CAAC;CAC1D;CACA,MAAM,gBAAyC,WAC3C,CACE,CAAC,SAAS,IAAI,GACd,CAAC,QAAQ,IAAI,CAAC,IAEhB;EACE,CAAC,aAAa,MAAM;EACpB,CAAC,iBAAiB,MAAM;EACxB,CAAC,gBAAgB,IAAI;CAAC;CAE5B,KAAK,MAAM,CAAC,MAAM,WAAW,eAAe,OAAO,iBAAiB,MAAM,OAAO;AACnF"}

package/dist/utils/dom/roving-focus.d.ts

@@ -0,0 +1,44 @@
+/** 方向键的方向 */
+export interface RovingOrientations {
+    /** 左右键（从右到左排版时反过来） */
+    horizontal: unknown;
+    /** 上下键 */
+    vertical: unknown;
+    /** 四个方向键都可以（如分页、网格状的工具栏） */
+    both: unknown;
+}
+/** rovingFocus 的选项 */
+export interface RovingFocusOptions {
+    /** 项的选择器，在容器内查找；不可用（disabled、aria-disabled="true"）、隐藏的项跳过 */
+    items: string;
+    /** 方向键的方向，默认 horizontal */
+    orientation?: keyof RovingOrientations;
+    /** 到两端后是否从另一端继续，默认 true */
+    loop?: boolean;
+    /** 按字母跳到以它开头的项（菜单、列表），默认 false；匹配的是项的文字 */
+    typeahead?: boolean;
+    /** Tab 进入时落在哪一项：默认是上次聚焦的项，其次是选中或当前的项（aria-selected / pressed / checked / current），再其次是第一项 */
+    initial?: (items: HTMLElement[]) => HTMLElement | undefined;
+}
+/** 开始管理容器里各项的焦点，返回清理函数 */
+export declare function rovingFocus(container: HTMLElement, options: RovingFocusOptions): () => void;
+/** gridFocus 的选项 */
+export interface GridFocusOptions {
+    /** 行的选择器，在容器内查找（如 `[role="row"]`） */
+    rows: string;
+    /** 行里可聚焦的格的选择器（格本身，或格里的按钮）；不可用、隐藏的格跳过 */
+    cells: string;
+    /** PageUp / PageDown 一次移动几行，默认 10 */
+    pageRows?: number;
+    /** Tab 进入时落在哪一格：默认是上次聚焦的格，其次是选中或当前的格，再其次是第一格 */
+    initial?: (cells: HTMLElement[]) => HTMLElement | undefined;
+}
+/**
+ * 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。
+ * ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），
+ * Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。
+ * 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数
+ *
+ *   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role="gridcell"]' }) : undefined));
+ */
+export declare function gridFocus(container: HTMLElement, options: GridFocusOptions): () => void;

package/dist/utils/dom/roving-focus.js

@@ -0,0 +1,184 @@
+import { clamp } from "../data/number.js";
+import { isRtl } from "./direction.js";
+import { createTypeahead } from "./typeahead.js";
+//#region src/utils/dom/roving-focus.ts
+/**
+* 漫游焦点（WAI-ARIA 的 roving tabindex）：一组项里只有一个能用 Tab 进入（tabindex=0），其余为 -1；
+* 组内用方向键移动，Home / End 到两端。Tabs、Toolbar、Menu、ToggleGroup 共用（参考 Radix 的 RovingFocusGroup）。
+* 二维的网格（表格的单元格、整页日历）用 gridFocus：方向键在行列之间移动。
+*
+* 直接管理容器里各项的 tabindex（组件渲染时不要再写 tabindex），所以项可以是任意可聚焦元素：
+* 工具栏里的按钮、标签页、链接都行。项增删、选中项变化时自动重新计算。
+*
+*   _effect(() => (list ? rovingFocus(list, { items: '[role="tab"]', orientation: 'horizontal' }) : undefined));
+*/
+/** 可以停留：没有不可用，也不在隐藏或 inert 的区域里 */
+var isEnabled = (element) => !element.matches(":disabled, [aria-disabled=\"true\"]") && !element.closest("[hidden], [inert]");
+/** 选中或当前的项：Tab 进入时优先落在它上面 */
+var isMarked = (element) => element.getAttribute("aria-selected") === "true" || element.getAttribute("aria-pressed") === "true" || element.getAttribute("aria-checked") === "true" || element.hasAttribute("aria-current") && element.getAttribute("aria-current") !== "false";
+/** 开始管理容器里各项的焦点，返回清理函数 */
+function rovingFocus(container, options) {
+	const { orientation = "horizontal", loop = true } = options;
+	const typeahead = options.typeahead ? createTypeahead() : void 0;
+	let current;
+	const all = () => [...container.querySelectorAll(options.items)].filter((item) => {
+		if (item.parentElement?.closest("[data-roving-focus]") !== container) return false;
+		const layer = item.closest("[popover], dialog");
+		return !layer || layer === container || !container.contains(layer);
+	});
+	const enabled = () => all().filter(isEnabled);
+	/** 定下哪一项是 Tab 进入点，其余设为 -1 */
+	function sync() {
+		const items = enabled();
+		const stop = (current && items.includes(current) ? current : void 0) ?? options.initial?.(items) ?? items.find(isMarked) ?? items[0];
+		for (const item of all()) {
+			const value = item === stop ? "0" : "-1";
+			if (item.getAttribute("tabindex") !== value) item.setAttribute("tabindex", value);
+		}
+	}
+	function onKeydown(event) {
+		if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
+		const items = enabled();
+		const index = items.indexOf(event.target);
+		if (index < 0) return;
+		const rtl = isRtl(container);
+		const horizontal = orientation !== "vertical";
+		const vertical = orientation !== "horizontal";
+		const step = {
+			ArrowRight: horizontal ? rtl ? -1 : 1 : void 0,
+			ArrowLeft: horizontal ? rtl ? 1 : -1 : void 0,
+			ArrowDown: vertical ? 1 : void 0,
+			ArrowUp: vertical ? -1 : void 0,
+			Home: "first",
+			End: "last"
+		}[event.key];
+		if (step === void 0) {
+			const match = typeahead?.next(event.key, items.map((item) => item.textContent ?? ""), index);
+			if (match != null && match >= 0) {
+				event.preventDefault();
+				items[match].focus();
+			}
+			return;
+		}
+		event.preventDefault();
+		let next;
+		if (step === "first") next = 0;
+		else if (step === "last") next = items.length - 1;
+		else if (loop) next = (index + step + items.length) % items.length;
+		else next = clamp(index + step, 0, items.length - 1);
+		items[next].focus();
+	}
+	function onFocusin(event) {
+		const target = event.target;
+		if (!all().includes(target)) return;
+		current = target;
+		sync();
+	}
+	container.setAttribute("data-roving-focus", "");
+	container.addEventListener("keydown", onKeydown);
+	container.addEventListener("focusin", onFocusin);
+	const observer = new MutationObserver(sync);
+	observer.observe(container, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [
+			"disabled",
+			"aria-disabled",
+			"aria-selected",
+			"aria-pressed",
+			"aria-checked",
+			"aria-current",
+			"hidden",
+			"data-roving-focus"
+		]
+	});
+	sync();
+	return () => {
+		container.removeAttribute("data-roving-focus");
+		container.removeEventListener("keydown", onKeydown);
+		container.removeEventListener("focusin", onFocusin);
+		observer.disconnect();
+	};
+}
+/**
+* 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。
+* ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），
+* Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。
+* 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数
+*
+*   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role="gridcell"]' }) : undefined));
+*/
+function gridFocus(container, options) {
+	const pageRows = options.pageRows ?? 10;
+	let current;
+	/** 各行里能停留的格（空行去掉） */
+	const grid = () => [...container.querySelectorAll(options.rows)].map((row) => [...row.querySelectorAll(options.cells)].filter(isEnabled)).filter((cells) => cells.length > 0);
+	const allCells = () => [...container.querySelectorAll(options.cells)];
+	function sync() {
+		const cells = grid().flat();
+		const stop = (current && cells.includes(current) ? current : void 0) ?? options.initial?.(cells) ?? cells.find(isMarked) ?? cells[0];
+		for (const cell of allCells()) {
+			const value = cell === stop ? "0" : "-1";
+			if (cell.getAttribute("tabindex") !== value) cell.setAttribute("tabindex", value);
+		}
+	}
+	function onKeydown(event) {
+		if (event.defaultPrevented || event.altKey || event.metaKey) return;
+		const rows = grid();
+		const row = rows.findIndex((cells) => cells.includes(event.target));
+		if (row < 0) return;
+		const column = rows[row].indexOf(event.target);
+		const rtl = isRtl(container);
+		const last = rows.length - 1;
+		const at = (r, c) => {
+			const cells = rows[clamp(r, 0, last)];
+			return cells[clamp(c, 0, cells.length - 1)];
+		};
+		const ctrl = event.ctrlKey;
+		const next = {
+			ArrowRight: ctrl ? void 0 : () => at(row, column + (rtl ? -1 : 1)),
+			ArrowLeft: ctrl ? void 0 : () => at(row, column + (rtl ? 1 : -1)),
+			ArrowDown: ctrl ? void 0 : () => at(row + 1, column),
+			ArrowUp: ctrl ? void 0 : () => at(row - 1, column),
+			Home: () => ctrl ? rows[0][0] : rows[row][0],
+			End: () => ctrl ? rows[last].at(-1) : rows[row].at(-1),
+			PageDown: ctrl ? void 0 : () => at(row + pageRows, column),
+			PageUp: ctrl ? void 0 : () => at(row - pageRows, column)
+		}[event.key]?.();
+		if (!next) return;
+		event.preventDefault();
+		next.focus();
+	}
+	function onFocusin(event) {
+		const target = event.target;
+		if (!allCells().includes(target)) return;
+		current = target;
+		sync();
+	}
+	container.addEventListener("keydown", onKeydown);
+	container.addEventListener("focusin", onFocusin);
+	const observer = new MutationObserver(sync);
+	observer.observe(container, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [
+			"disabled",
+			"aria-disabled",
+			"aria-selected",
+			"aria-current",
+			"hidden"
+		]
+	});
+	sync();
+	return () => {
+		container.removeEventListener("keydown", onKeydown);
+		container.removeEventListener("focusin", onFocusin);
+		observer.disconnect();
+	};
+}
+//#endregion
+export { gridFocus, rovingFocus };
+
+//# sourceMappingURL=roving-focus.js.map

package/dist/utils/dom/roving-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-focus.js","names":[],"sources":["../../../src/utils/dom/roving-focus.ts"],"sourcesContent":["/**\n * 漫游焦点（WAI-ARIA 的 roving tabindex）：一组项里只有一个能用 Tab 进入（tabindex=0），其余为 -1；\n * 组内用方向键移动，Home / End 到两端。Tabs、Toolbar、Menu、ToggleGroup 共用（参考 Radix 的 RovingFocusGroup）。\n * 二维的网格（表格的单元格、整页日历）用 gridFocus：方向键在行列之间移动。\n *\n * 直接管理容器里各项的 tabindex（组件渲染时不要再写 tabindex），所以项可以是任意可聚焦元素：\n * 工具栏里的按钮、标签页、链接都行。项增删、选中项变化时自动重新计算。\n *\n *   _effect(() => (list ? rovingFocus(list, { items: '[role=\"tab\"]', orientation: 'horizontal' }) : undefined));\n */\nimport { clamp } from '../data/number';\nimport { isRtl } from './direction';\nimport { createTypeahead } from './typeahead';\n\n/** 方向键的方向 */\nexport interface RovingOrientations {\n  /** 左右键（从右到左排版时反过来） */\n  horizontal: unknown;\n  /** 上下键 */\n  vertical: unknown;\n  /** 四个方向键都可以（如分页、网格状的工具栏） */\n  both: unknown;\n}\n\n/** rovingFocus 的选项 */\nexport interface RovingFocusOptions {\n  /** 项的选择器，在容器内查找；不可用（disabled、aria-disabled=\"true\"）、隐藏的项跳过 */\n  items: string;\n  /** 方向键的方向，默认 horizontal */\n  orientation?: keyof RovingOrientations;\n  /** 到两端后是否从另一端继续，默认 true */\n  loop?: boolean;\n  /** 按字母跳到以它开头的项（菜单、列表），默认 false；匹配的是项的文字 */\n  typeahead?: boolean;\n  /** Tab 进入时落在哪一项：默认是上次聚焦的项，其次是选中或当前的项（aria-selected / pressed / checked / current），再其次是第一项 */\n  initial?: (items: HTMLElement[]) => HTMLElement | undefined;\n}\n\n/** 可以停留：没有不可用，也不在隐藏或 inert 的区域里 */\nconst isEnabled = (element: HTMLElement) =>\n  !element.matches(':disabled, [aria-disabled=\"true\"]') && !element.closest('[hidden], [inert]');\n\n/** 选中或当前的项：Tab 进入时优先落在它上面 */\nconst isMarked = (element: HTMLElement) =>\n  element.getAttribute('aria-selected') === 'true' ||\n  element.getAttribute('aria-pressed') === 'true' ||\n  element.getAttribute('aria-checked') === 'true' ||\n  (element.hasAttribute('aria-current') && element.getAttribute('aria-current') !== 'false');\n\n/** 开始管理容器里各项的焦点，返回清理函数 */\nexport function rovingFocus(container: HTMLElement, options: RovingFocusOptions): () => void {\n  const { orientation = 'horizontal', loop = true } = options;\n  const typeahead = options.typeahead ? createTypeahead() : undefined;\n  let current: HTMLElement | undefined;\n\n  // 嵌套的组（自己也调用了 rovingFocus 的容器）各管各的：只取最近的组是自己的项。\n  // 工具栏里的 ToggleGroup 不调用，它的按钮归工具栏\n  // 容器里的弹层（popover、dialog）是另一个焦点范围：工具栏里 Popover 的面板、对话框里的按钮不归工具栏\n  const all = () =>\n    [...container.querySelectorAll<HTMLElement>(options.items)].filter((item) => {\n      if (item.parentElement?.closest('[data-roving-focus]') !== container) return false;\n      const layer = item.closest('[popover], dialog');\n      // 容器自己就是弹层（菜单的面板）时，它里面的项照常归它\n      return !layer || layer === container || !container.contains(layer);\n    });\n  const enabled = () => all().filter(isEnabled);\n\n  /** 定下哪一项是 Tab 进入点，其余设为 -1 */\n  function sync() {\n    const items = enabled();\n    const stop =\n      (current && items.includes(current) ? current : undefined) ??\n      options.initial?.(items) ??\n      items.find(isMarked) ??\n      items[0];\n    for (const item of all()) {\n      const value = item === stop ? '0' : '-1';\n      if (item.getAttribute('tabindex') !== value) item.setAttribute('tabindex', value);\n    }\n  }\n\n  function onKeydown(event: KeyboardEvent) {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;\n    const items = enabled();\n    const index = items.indexOf(event.target as HTMLElement);\n    if (index < 0) return;\n    const rtl = isRtl(container);\n    const horizontal = orientation !== 'vertical';\n    const vertical = orientation !== 'horizontal';\n    const steps: Record<string, number | 'first' | 'last' | undefined> = {\n      ArrowRight: horizontal ? (rtl ? -1 : 1) : undefined,\n      ArrowLeft: horizontal ? (rtl ? 1 : -1) : undefined,\n      ArrowDown: vertical ? 1 : undefined,\n      ArrowUp: vertical ? -1 : undefined,\n      Home: 'first',\n      End: 'last',\n    };\n    const step = steps[event.key];\n    if (step === undefined) {\n      const match = typeahead?.next(\n        event.key,\n        items.map((item) => item.textContent ?? ''),\n        index,\n      );\n      if (match != null && match >= 0) {\n        event.preventDefault();\n        items[match]!.focus();\n      }\n      return;\n    }\n    event.preventDefault();\n    let next: number;\n    if (step === 'first') next = 0;\n    else if (step === 'last') next = items.length - 1;\n    else if (loop) next = (index + step + items.length) % items.length;\n    else next = clamp(index + step, 0, items.length - 1);\n    items[next]!.focus();\n  }\n\n  function onFocusin(event: FocusEvent) {\n    const target = event.target as HTMLElement;\n    if (!all().includes(target)) return;\n    current = target;\n    sync();\n  }\n\n  container.setAttribute('data-roving-focus', '');\n  container.addEventListener('keydown', onKeydown);\n  container.addEventListener('focusin', onFocusin);\n  // 项增删、选中或可用状态变化时重新定 Tab 进入点\n  const observer = new MutationObserver(sync);\n  observer.observe(container, {\n    childList: true,\n    subtree: true,\n    attributes: true,\n    attributeFilter: [\n      'disabled',\n      'aria-disabled',\n      'aria-selected',\n      'aria-pressed',\n      'aria-checked',\n      'aria-current',\n      'hidden',\n      // 嵌套的组挂载时（子组件先于父组件）重新划分各组的项\n      'data-roving-focus',\n    ],\n  });\n  sync();\n\n  return () => {\n    container.removeAttribute('data-roving-focus');\n    container.removeEventListener('keydown', onKeydown);\n    container.removeEventListener('focusin', onFocusin);\n    observer.disconnect();\n  };\n}\n\n/** gridFocus 的选项 */\nexport interface GridFocusOptions {\n  /** 行的选择器，在容器内查找（如 `[role=\"row\"]`） */\n  rows: string;\n  /** 行里可聚焦的格的选择器（格本身，或格里的按钮）；不可用、隐藏的格跳过 */\n  cells: string;\n  /** PageUp / PageDown 一次移动几行，默认 10 */\n  pageRows?: number;\n  /** Tab 进入时落在哪一格：默认是上次聚焦的格，其次是选中或当前的格，再其次是第一格 */\n  initial?: (cells: HTMLElement[]) => HTMLElement | undefined;\n}\n\n/**\n * 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。\n * ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），\n * Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。\n * 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数\n *\n *   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role=\"gridcell\"]' }) : undefined));\n */\nexport function gridFocus(container: HTMLElement, options: GridFocusOptions): () => void {\n  const pageRows = options.pageRows ?? 10;\n  let current: HTMLElement | undefined;\n\n  /** 各行里能停留的格（空行去掉） */\n  const grid = () =>\n    [...container.querySelectorAll<HTMLElement>(options.rows)]\n      .map((row) => [...row.querySelectorAll<HTMLElement>(options.cells)].filter(isEnabled))\n      .filter((cells) => cells.length > 0);\n  const allCells = () => [...container.querySelectorAll<HTMLElement>(options.cells)];\n\n  function sync() {\n    const cells = grid().flat();\n    const stop =\n      (current && cells.includes(current) ? current : undefined) ??\n      options.initial?.(cells) ??\n      cells.find(isMarked) ??\n      cells[0];\n    for (const cell of allCells()) {\n      const value = cell === stop ? '0' : '-1';\n      if (cell.getAttribute('tabindex') !== value) cell.setAttribute('tabindex', value);\n    }\n  }\n\n  function onKeydown(event: KeyboardEvent) {\n    if (event.defaultPrevented || event.altKey || event.metaKey) return;\n    const rows = grid();\n    const row = rows.findIndex((cells) => cells.includes(event.target as HTMLElement));\n    if (row < 0) return;\n    const column = rows[row]!.indexOf(event.target as HTMLElement);\n    const rtl = isRtl(container);\n    const last = rows.length - 1;\n    const at = (r: number, c: number) => {\n      const cells = rows[clamp(r, 0, last)]!;\n      return cells[clamp(c, 0, cells.length - 1)];\n    };\n    const ctrl = event.ctrlKey;\n    const targets: Record<string, (() => HTMLElement | undefined) | undefined> = {\n      ArrowRight: ctrl ? undefined : () => at(row, column + (rtl ? -1 : 1)),\n      ArrowLeft: ctrl ? undefined : () => at(row, column + (rtl ? 1 : -1)),\n      ArrowDown: ctrl ? undefined : () => at(row + 1, column),\n      ArrowUp: ctrl ? undefined : () => at(row - 1, column),\n      Home: () => (ctrl ? rows[0]![0] : rows[row]![0]),\n      End: () => (ctrl ? rows[last]!.at(-1) : rows[row]!.at(-1)),\n      PageDown: ctrl ? undefined : () => at(row + pageRows, column),\n      PageUp: ctrl ? undefined : () => at(row - pageRows, column),\n    };\n    const next = targets[event.key]?.();\n    if (!next) return;\n    event.preventDefault();\n    next.focus();\n  }\n\n  function onFocusin(event: FocusEvent) {\n    const target = event.target as HTMLElement;\n    if (!allCells().includes(target)) return;\n    current = target;\n    sync();\n  }\n\n  container.addEventListener('keydown', onKeydown);\n  container.addEventListener('focusin', onFocusin);\n  const observer = new MutationObserver(sync);\n  observer.observe(container, {\n    childList: true,\n    subtree: true,\n    attributes: true,\n    attributeFilter: ['disabled', 'aria-disabled', 'aria-selected', 'aria-current', 'hidden'],\n  });\n  sync();\n\n  return () => {\n    container.removeEventListener('keydown', onKeydown);\n    container.removeEventListener('focusin', onFocusin);\n    observer.disconnect();\n  };\n}\n"],"mappings":"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"}

package/dist/utils/dom/scroll-spy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。
+ *
+ *   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));
+ *
+ * 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，
+ * 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。
+ * 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。
+ */
+import { type Ref } from 'vue';
+/** useScrollSpy 每次读取的选项 */
+export interface ScrollSpyOptions {
+    /** 要追踪的元素的 id，按文档顺序 */
+    ids: readonly string[];
+    /** 滚动容器；不写时是页面（窗口） */
+    root?: HTMLElement | null;
+}
+/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */
+export declare function useScrollSpy(read: () => ScrollSpyOptions): Readonly<Ref<string | undefined>>;
+/** 目录里的一项 */
+export interface HeadingEntry {
+    /** 标题的 id（锚点） */
+    id: string;
+    /** 标题文字 */
+    label: string;
+    /** 标题级别：2 是 h2，3 是 h3… */
+    level: number;
+}
+/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */
+export declare function collectHeadings(container: ParentNode, selector?: string): HeadingEntry[];

package/dist/utils/dom/scroll-spy.js

@@ -0,0 +1,55 @@
+import { useEventListener } from "./event-listener.js";
+import { onMounted, onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/dom/scroll-spy.ts
+/**
+* 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。
+*
+*   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));
+*
+* 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，
+* 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。
+* 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。
+*/
+/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */
+function useScrollSpy(read) {
+	const current = shallowRef();
+	if (typeof window === "undefined") return current;
+	function update() {
+		const { ids, root } = read();
+		const elements = ids.map((id) => document.getElementById(id)).filter((element) => element !== null);
+		const top = root ? root.getBoundingClientRect().top : 0;
+		const scroller = root ?? document.scrollingElement ?? document.documentElement;
+		const atBottom = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 1;
+		const bottom = root ? root.getBoundingClientRect().bottom : window.innerHeight;
+		let next;
+		for (const element of elements) {
+			const offset = element.getBoundingClientRect().top - top;
+			if (offset <= (parseFloat(getComputedStyle(element).scrollMarginTop) || 0) + 1 || atBottom && offset < bottom - top) next = element.id;
+		}
+		current.value = next;
+	}
+	let frame = 0;
+	const schedule = () => {
+		cancelAnimationFrame(frame);
+		frame = requestAnimationFrame(update);
+	};
+	useEventListener(() => read().root ?? window, "scroll", schedule, { passive: true });
+	useEventListener(window, "resize", schedule);
+	onMounted(update);
+	watch(() => read().root, schedule);
+	watch(() => read().ids, schedule, { flush: "post" });
+	onScopeDispose(() => cancelAnimationFrame(frame));
+	return current;
+}
+/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */
+function collectHeadings(container, selector = "h2[id], h3[id]") {
+	return [...container.querySelectorAll(selector)].map((heading) => ({
+		id: heading.id,
+		label: heading.textContent?.trim() ?? "",
+		level: Number(heading.tagName.slice(1)) || 2
+	}));
+}
+//#endregion
+export { collectHeadings, useScrollSpy };
+
+//# sourceMappingURL=scroll-spy.js.map

package/dist/utils/dom/scroll-spy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-spy.js","names":[],"sources":["../../../src/utils/dom/scroll-spy.ts"],"sourcesContent":["/**\n * 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。\n *\n *   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));\n *\n * 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，\n * 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。\n * 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。\n */\nimport { onMounted, onScopeDispose, shallowRef, watch, type Ref } from 'vue';\nimport { useEventListener } from './event-listener';\n\n/** useScrollSpy 每次读取的选项 */\nexport interface ScrollSpyOptions {\n  /** 要追踪的元素的 id，按文档顺序 */\n  ids: readonly string[];\n  /** 滚动容器；不写时是页面（窗口） */\n  root?: HTMLElement | null;\n}\n\n/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */\nexport function useScrollSpy(read: () => ScrollSpyOptions): Readonly<Ref<string | undefined>> {\n  const current = shallowRef<string | undefined>();\n  if (typeof window === 'undefined') return current;\n\n  function update() {\n    const { ids, root } = read();\n    const elements = ids\n      .map((id) => document.getElementById(id))\n      .filter((element): element is HTMLElement => element !== null);\n    const top = root ? root.getBoundingClientRect().top : 0;\n    const scroller = root ?? document.scrollingElement ?? document.documentElement;\n    const atBottom = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 1;\n    const bottom = root ? root.getBoundingClientRect().bottom : window.innerHeight;\n    let next: string | undefined;\n    for (const element of elements) {\n      const offset = element.getBoundingClientRect().top - top;\n      const line = parseFloat(getComputedStyle(element).scrollMarginTop) || 0;\n      // +1：跳转后元素正好停在阅读线上，取整误差不该让它算作还没到\n      if (offset <= line + 1 || (atBottom && offset < bottom - top)) next = element.id;\n    }\n    current.value = next;\n  }\n\n  // 一帧最多量一次\n  let frame = 0;\n  const schedule = () => {\n    cancelAnimationFrame(frame);\n    frame = requestAnimationFrame(update);\n  };\n  // 滚动容器常常在挂载后才拿到（ref 回调）：换了容器就换绑，并按新容器重新算，不能留着按窗口算的结果\n  useEventListener(() => read().root ?? window, 'scroll', schedule, { passive: true });\n  useEventListener(window, 'resize', schedule);\n  onMounted(update);\n  watch(() => read().root, schedule);\n  watch(() => read().ids, schedule, { flush: 'post' });\n  onScopeDispose(() => cancelAnimationFrame(frame));\n  return current;\n}\n\n/** 目录里的一项 */\nexport interface HeadingEntry {\n  /** 标题的 id（锚点） */\n  id: string;\n  /** 标题文字 */\n  label: string;\n  /** 标题级别：2 是 h2，3 是 h3… */\n  level: number;\n}\n\n/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */\nexport function collectHeadings(\n  container: ParentNode,\n  selector = 'h2[id], h3[id]',\n): HeadingEntry[] {\n  return [...container.querySelectorAll<HTMLElement>(selector)].map((heading) => ({\n    id: heading.id,\n    label: heading.textContent?.trim() ?? '',\n    level: Number(heading.tagName.slice(1)) || 2,\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;AAqBA,SAAgB,aAAa,MAAiE;CAC5F,MAAM,UAAU,WAA+B;CAC/C,IAAI,OAAO,WAAW,aAAa,OAAO;CAE1C,SAAS,SAAS;EAChB,MAAM,EAAE,KAAK,SAAS,KAAK;EAC3B,MAAM,WAAW,IACd,KAAK,OAAO,SAAS,eAAe,EAAE,CAAC,CAAC,CACxC,QAAQ,YAAoC,YAAY,IAAI;EAC/D,MAAM,MAAM,OAAO,KAAK,sBAAsB,CAAC,CAAC,MAAM;EACtD,MAAM,WAAW,QAAQ,SAAS,oBAAoB,SAAS;EAC/D,MAAM,WAAW,SAAS,YAAY,SAAS,gBAAgB,SAAS,eAAe;EACvF,MAAM,SAAS,OAAO,KAAK,sBAAsB,CAAC,CAAC,SAAS,OAAO;EACnE,IAAI;EACJ,KAAK,MAAM,WAAW,UAAU;GAC9B,MAAM,SAAS,QAAQ,sBAAsB,CAAC,CAAC,MAAM;GAGrD,IAAI,WAFS,WAAW,iBAAiB,OAAO,CAAC,CAAC,eAAe,KAAK,KAEjD,KAAM,YAAY,SAAS,SAAS,KAAM,OAAO,QAAQ;EAChF;EACA,QAAQ,QAAQ;CAClB;CAGA,IAAI,QAAQ;CACZ,MAAM,iBAAiB;EACrB,qBAAqB,KAAK;EAC1B,QAAQ,sBAAsB,MAAM;CACtC;CAEA,uBAAuB,KAAK,CAAC,CAAC,QAAQ,QAAQ,UAAU,UAAU,EAAE,SAAS,KAAK,CAAC;CACnF,iBAAiB,QAAQ,UAAU,QAAQ;CAC3C,UAAU,MAAM;CAChB,YAAY,KAAK,CAAC,CAAC,MAAM,QAAQ;CACjC,YAAY,KAAK,CAAC,CAAC,KAAK,UAAU,EAAE,OAAO,OAAO,CAAC;CACnD,qBAAqB,qBAAqB,KAAK,CAAC;CAChD,OAAO;AACT;;AAaA,SAAgB,gBACd,WACA,WAAW,kBACK;CAChB,OAAO,CAAC,GAAG,UAAU,iBAA8B,QAAQ,CAAC,CAAC,CAAC,KAAK,aAAa;EAC9E,IAAI,QAAQ;EACZ,OAAO,QAAQ,aAAa,KAAK,KAAK;EACtC,OAAO,OAAO,QAAQ,QAAQ,MAAM,CAAC,CAAC,KAAK;CAC7C,EAAE;AACJ"}