@veltra/utils 1.4.0 → 1.5.0

package/dist/dom/position.d.ts

@@ -1,12 +1,13 @@
 //#region src/dom/position.d.ts
 /**
- * 获取可滚动的父级
+ * 获取可滚动的父级（纵向或横向可滚动均计入：overflow-x 容器如横向滚动条
+ * 也是滚动父级，弹层需监听其 scroll 事件）
  * @param el 元素
  * @returns
  */
 declare function getScrollParents(el: HTMLElement): HTMLElement[];
 /**
- * 获取最近的可滚动父级
+ * 获取最近的可滚动父级（纵向或横向可滚动均计入）
  * @param el 元素
  * @returns 最近的可滚动父级
  */

package/dist/dom/position.js

@@ -1,6 +1,7 @@
 //#region src/dom/position.ts
 /**
-* 获取可滚动的父级
+* 获取可滚动的父级（纵向或横向可滚动均计入：overflow-x 容器如横向滚动条
+* 也是滚动父级，弹层需监听其 scroll 事件）
 * @param el 元素
 * @returns
 */
@@ -8,20 +9,20 @@ function getScrollParents(el) {
 	const parents = [];
 	let parent = el.parentElement;
 	while (parent) {
-		if (parent.scrollHeight > parent.clientHeight) parents.push(parent);
+		if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) parents.push(parent);
 		parent = parent.parentElement;
 	}
 	return parents;
 }
 /**
-* 获取最近的可滚动父级
+* 获取最近的可滚动父级（纵向或横向可滚动均计入）
 * @param el 元素
 * @returns 最近的可滚动父级
 */
 function getNearestScrollParent(el) {
 	let parent = el.parentElement;
 	while (parent) {
-		if (parent.scrollHeight > parent.clientHeight) return parent;
+		if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) return parent;
 		parent = parent.parentElement;
 	}
 	return null;

package/dist/dom/position.js.map

@@ -1 +1 @@
-{"version":3,"file":"position.js","names":[],"sources":["../../src/dom/position.ts"],"sourcesContent":["/**\n * 获取可滚动的父级\n * @param el 元素\n * @returns\n */\nexport function getScrollParents(el: HTMLElement): HTMLElement[] {\n  const parents: HTMLElement[] = []\n  let parent = el.parentElement\n  while (parent) {\n    if (parent.scrollHeight > parent.clientHeight) {\n      parents.push(parent)\n    }\n\n    parent = parent.parentElement\n  }\n  return parents\n}\n\n/**\n * 获取最近的可滚动父级\n * @param el 元素\n * @returns 最近的可滚动父级\n */\nexport function getNearestScrollParent(el: HTMLElement): HTMLElement | null {\n  let parent = el.parentElement\n  while (parent) {\n    if (parent.scrollHeight > parent.clientHeight) {\n      return parent\n    }\n    parent = parent.parentElement\n  }\n  return null\n}\n\ntype ScrollViewPosition = 'center' | 'start' | 'end'\n\n/**\n * 滚动元素到容器视图中\n * @description 用于替代 `el.scrollIntoView` 方法，因为 `el.scrollIntoView` 在某些情况下会导致外部元素滚动\n * @param el 元素\n * @param container 可滚动容器\n * @param options 滚动选项\n */\nexport function scrollIntoContainerView(\n  el: HTMLElement,\n  container: HTMLElement | null,\n  options?: { block?: ScrollViewPosition; inline?: ScrollViewPosition }\n): void {\n  container = container || getNearestScrollParent(el)\n  if (!container) return\n\n  const { block = 'center', inline = 'center' } = options || {}\n\n  const {\n    offsetTop: eOffsetTop,\n    offsetLeft: eOffsetLeft,\n    offsetHeight: eOffsetHeight,\n    offsetWidth: eOffsetWidth\n  } = el\n\n  const {\n    clientHeight: cClientHeight,\n    clientWidth: cClientWidth,\n    scrollTop: cScrollTop,\n    scrollLeft: cScrollLeft\n  } = container\n\n  const isVerticalInView =\n    cScrollTop + cClientHeight > eOffsetTop + eOffsetHeight && cScrollTop < eOffsetTop\n\n  const isHorizontalInView =\n    cScrollLeft + cClientWidth > eOffsetLeft + eOffsetWidth && cScrollLeft < eOffsetLeft\n\n  // 垂直方向和水平方向都已经在视图中，则不进行滚动\n  if (isVerticalInView && isHorizontalInView) return\n\n  if (!isVerticalInView) {\n    if (block === 'center') {\n      container.scrollTop = eOffsetTop - cClientHeight / 2 + eOffsetHeight / 2\n    } else if (block === 'start') {\n      container.scrollTop = eOffsetTop\n    } else if (block === 'end') {\n      container.scrollTop = eOffsetTop - cClientHeight + eOffsetHeight\n    }\n  }\n\n  if (!isHorizontalInView) {\n    if (inline === 'center') {\n      container.scrollLeft = eOffsetLeft - cClientWidth / 2 + eOffsetWidth / 2\n    } else if (inline === 'start') {\n      container.scrollLeft = eOffsetLeft\n    } else if (inline === 'end') {\n      container.scrollLeft = eOffsetLeft - cClientWidth + eOffsetWidth\n    }\n  }\n}\n"],"mappings":";;;;;;AAKA,SAAgB,iBAAiB,IAAgC;CAC/D,MAAM,UAAyB,CAAC;CAChC,IAAI,SAAS,GAAG;CAChB,OAAO,QAAQ;EACb,IAAI,OAAO,eAAe,OAAO,cAC/B,QAAQ,KAAK,MAAM;EAGrB,SAAS,OAAO;CAClB;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,uBAAuB,IAAqC;CAC1E,IAAI,SAAS,GAAG;CAChB,OAAO,QAAQ;EACb,IAAI,OAAO,eAAe,OAAO,cAC/B,OAAO;EAET,SAAS,OAAO;CAClB;CACA,OAAO;AACT;;;;;;;;AAWA,SAAgB,wBACd,IACA,WACA,SACM;CACN,YAAY,aAAa,uBAAuB,EAAE;CAClD,IAAI,CAAC,WAAW;CAEhB,MAAM,EAAE,QAAQ,UAAU,SAAS,aAAa,WAAW,CAAC;CAE5D,MAAM,EACJ,WAAW,YACX,YAAY,aACZ,cAAc,eACd,aAAa,iBACX;CAEJ,MAAM,EACJ,cAAc,eACd,aAAa,cACb,WAAW,YACX,YAAY,gBACV;CAEJ,MAAM,mBACJ,aAAa,gBAAgB,aAAa,iBAAiB,aAAa;CAE1E,MAAM,qBACJ,cAAc,eAAe,cAAc,gBAAgB,cAAc;CAG3E,IAAI,oBAAoB,oBAAoB;CAE5C,IAAI,CAAC;MACC,UAAU,UACZ,UAAU,YAAY,aAAa,gBAAgB,IAAI,gBAAgB;OAClE,IAAI,UAAU,SACnB,UAAU,YAAY;OACjB,IAAI,UAAU,OACnB,UAAU,YAAY,aAAa,gBAAgB;CAAA;CAIvD,IAAI,CAAC;MACC,WAAW,UACb,UAAU,aAAa,cAAc,eAAe,IAAI,eAAe;OAClE,IAAI,WAAW,SACpB,UAAU,aAAa;OAClB,IAAI,WAAW,OACpB,UAAU,aAAa,cAAc,eAAe;CAAA;AAG1D"}
+{"version":3,"file":"position.js","names":[],"sources":["../../src/dom/position.ts"],"sourcesContent":["/**\n * 获取可滚动的父级（纵向或横向可滚动均计入：overflow-x 容器如横向滚动条\n * 也是滚动父级，弹层需监听其 scroll 事件）\n * @param el 元素\n * @returns\n */\nexport function getScrollParents(el: HTMLElement): HTMLElement[] {\n  const parents: HTMLElement[] = []\n  let parent = el.parentElement\n  while (parent) {\n    if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) {\n      parents.push(parent)\n    }\n\n    parent = parent.parentElement\n  }\n  return parents\n}\n\n/**\n * 获取最近的可滚动父级（纵向或横向可滚动均计入）\n * @param el 元素\n * @returns 最近的可滚动父级\n */\nexport function getNearestScrollParent(el: HTMLElement): HTMLElement | null {\n  let parent = el.parentElement\n  while (parent) {\n    if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) {\n      return parent\n    }\n    parent = parent.parentElement\n  }\n  return null\n}\n\ntype ScrollViewPosition = 'center' | 'start' | 'end'\n\n/**\n * 滚动元素到容器视图中\n * @description 用于替代 `el.scrollIntoView` 方法，因为 `el.scrollIntoView` 在某些情况下会导致外部元素滚动\n * @param el 元素\n * @param container 可滚动容器\n * @param options 滚动选项\n */\nexport function scrollIntoContainerView(\n  el: HTMLElement,\n  container: HTMLElement | null,\n  options?: { block?: ScrollViewPosition; inline?: ScrollViewPosition }\n): void {\n  container = container || getNearestScrollParent(el)\n  if (!container) return\n\n  const { block = 'center', inline = 'center' } = options || {}\n\n  const {\n    offsetTop: eOffsetTop,\n    offsetLeft: eOffsetLeft,\n    offsetHeight: eOffsetHeight,\n    offsetWidth: eOffsetWidth\n  } = el\n\n  const {\n    clientHeight: cClientHeight,\n    clientWidth: cClientWidth,\n    scrollTop: cScrollTop,\n    scrollLeft: cScrollLeft\n  } = container\n\n  const isVerticalInView =\n    cScrollTop + cClientHeight > eOffsetTop + eOffsetHeight && cScrollTop < eOffsetTop\n\n  const isHorizontalInView =\n    cScrollLeft + cClientWidth > eOffsetLeft + eOffsetWidth && cScrollLeft < eOffsetLeft\n\n  // 垂直方向和水平方向都已经在视图中，则不进行滚动\n  if (isVerticalInView && isHorizontalInView) return\n\n  if (!isVerticalInView) {\n    if (block === 'center') {\n      container.scrollTop = eOffsetTop - cClientHeight / 2 + eOffsetHeight / 2\n    } else if (block === 'start') {\n      container.scrollTop = eOffsetTop\n    } else if (block === 'end') {\n      container.scrollTop = eOffsetTop - cClientHeight + eOffsetHeight\n    }\n  }\n\n  if (!isHorizontalInView) {\n    if (inline === 'center') {\n      container.scrollLeft = eOffsetLeft - cClientWidth / 2 + eOffsetWidth / 2\n    } else if (inline === 'start') {\n      container.scrollLeft = eOffsetLeft\n    } else if (inline === 'end') {\n      container.scrollLeft = eOffsetLeft - cClientWidth + eOffsetWidth\n    }\n  }\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,iBAAiB,IAAgC;CAC/D,MAAM,UAAyB,CAAC;CAChC,IAAI,SAAS,GAAG;CAChB,OAAO,QAAQ;EACb,IAAI,OAAO,eAAe,OAAO,gBAAgB,OAAO,cAAc,OAAO,aAC3E,QAAQ,KAAK,MAAM;EAGrB,SAAS,OAAO;CAClB;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,uBAAuB,IAAqC;CAC1E,IAAI,SAAS,GAAG;CAChB,OAAO,QAAQ;EACb,IAAI,OAAO,eAAe,OAAO,gBAAgB,OAAO,cAAc,OAAO,aAC3E,OAAO;EAET,SAAS,OAAO;CAClB;CACA,OAAO;AACT;;;;;;;;AAWA,SAAgB,wBACd,IACA,WACA,SACM;CACN,YAAY,aAAa,uBAAuB,EAAE;CAClD,IAAI,CAAC,WAAW;CAEhB,MAAM,EAAE,QAAQ,UAAU,SAAS,aAAa,WAAW,CAAC;CAE5D,MAAM,EACJ,WAAW,YACX,YAAY,aACZ,cAAc,eACd,aAAa,iBACX;CAEJ,MAAM,EACJ,cAAc,eACd,aAAa,cACb,WAAW,YACX,YAAY,gBACV;CAEJ,MAAM,mBACJ,aAAa,gBAAgB,aAAa,iBAAiB,aAAa;CAE1E,MAAM,qBACJ,cAAc,eAAe,cAAc,gBAAgB,cAAc;CAG3E,IAAI,oBAAoB,oBAAoB;CAE5C,IAAI,CAAC,kBACC;MAAA,UAAU,UACZ,UAAU,YAAY,aAAa,gBAAgB,IAAI,gBAAgB;OAClE,IAAI,UAAU,SACnB,UAAU,YAAY;OACjB,IAAI,UAAU,OACnB,UAAU,YAAY,aAAa,gBAAgB;CAAA;CAIvD,IAAI,CAAC,oBACC;MAAA,WAAW,UACb,UAAU,aAAa,cAAc,eAAe,IAAI,eAAe;OAClE,IAAI,WAAW,SACpB,UAAU,aAAa;OAClB,IAAI,WAAW,OACpB,UAAU,aAAa,cAAc,eAAe;CAAA;AAG1D"}

package/dist/helper/overflow-nav.d.ts

@@ -0,0 +1,41 @@
+//#region src/helper/overflow-nav.d.ts
+/**
+ * 水平溢出滚动导航的共享纯逻辑（tabs / toolbar 三处复制的收敛，见 #17）。
+ * 只提供无 Vue 依赖的计算与副作用，事件绑定 / ResizeObserver / watch 由各
+ * composable 按需组合（三处的监听源与生命周期有真实差异，不强行统一）。
+ */
+/** 视口滚动几何（scrollTo 兼容 HTMLElement 与 vue 模板 ref） */
+interface OverflowNavViewport {
+  scrollLeft: number;
+  scrollWidth: number;
+  clientWidth: number;
+}
+/** 导航按钮状态 */
+interface OverflowNavState {
+  /** 内容是否溢出视口 */
+  overflowing: boolean;
+  /** 可向前（左/上）滚动 */
+  canPrev: boolean;
+  /** 可向后（右/下）滚动 */
+  canNext: boolean;
+}
+/** 依据视口与内容尺寸推导滚动按钮可用状态 */
+declare function computeOverflowNavState(vp: OverflowNavViewport): OverflowNavState;
+type ScrollableElement = OverflowNavViewport & {
+  scrollTo(options: {
+    left: number;
+    behavior: 'smooth';
+  }): void;
+};
+/** 箭头按钮：按视口宽度 80% 的步长平滑滚动 */
+declare function scrollViewportByStep(vp: ScrollableElement, dir: 1 | -1): void;
+/** 目标元素滚入视口（左/右越界时对齐到边缘，留 offset 边距） */
+declare function scrollElementIntoView(vp: HTMLElement, el: HTMLElement, offset?: number): void;
+/**
+ * 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截。
+ * navActive = 导航按钮是否可见（内容未溢出时不消费滚轮）。
+ */
+declare function applyWheelHorizontalScroll(e: WheelEvent, vp: HTMLElement, navActive: boolean): void;
+//#endregion
+export { OverflowNavState, OverflowNavViewport, applyWheelHorizontalScroll, computeOverflowNavState, scrollElementIntoView, scrollViewportByStep };
+//# sourceMappingURL=overflow-nav.d.ts.map

package/dist/helper/overflow-nav.js

@@ -0,0 +1,45 @@
+//#region src/helper/overflow-nav.ts
+/** 依据视口与内容尺寸推导滚动按钮可用状态 */
+function computeOverflowNavState(vp) {
+	const overflowing = vp.scrollWidth - vp.clientWidth > 1;
+	return {
+		overflowing,
+		canPrev: overflowing && vp.scrollLeft > 0,
+		canNext: overflowing && vp.scrollLeft + vp.clientWidth < vp.scrollWidth - 1
+	};
+}
+/** 箭头按钮：按视口宽度 80% 的步长平滑滚动 */
+function scrollViewportByStep(vp, dir) {
+	vp.scrollTo({
+		left: vp.scrollLeft + dir * vp.clientWidth * .8,
+		behavior: "smooth"
+	});
+}
+/** 目标元素滚入视口（左/右越界时对齐到边缘，留 offset 边距） */
+function scrollElementIntoView(vp, el, offset = 8) {
+	const vpRect = vp.getBoundingClientRect();
+	const elRect = el.getBoundingClientRect();
+	if (elRect.left < vpRect.left) vp.scrollTo({
+		left: vp.scrollLeft + (elRect.left - vpRect.left) - offset,
+		behavior: "smooth"
+	});
+	else if (elRect.right > vpRect.right) vp.scrollTo({
+		left: vp.scrollLeft + (elRect.right - vpRect.right) + offset,
+		behavior: "smooth"
+	});
+}
+/**
+* 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截。
+* navActive = 导航按钮是否可见（内容未溢出时不消费滚轮）。
+*/
+function applyWheelHorizontalScroll(e, vp, navActive) {
+	if (!navActive) return;
+	if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) return;
+	if (e.deltaY === 0) return;
+	e.preventDefault();
+	vp.scrollLeft += e.deltaY;
+}
+//#endregion
+export { applyWheelHorizontalScroll, computeOverflowNavState, scrollElementIntoView, scrollViewportByStep };
+
+//# sourceMappingURL=overflow-nav.js.map

package/dist/helper/overflow-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-nav.js","names":[],"sources":["../../src/helper/overflow-nav.ts"],"sourcesContent":["/**\n * 水平溢出滚动导航的共享纯逻辑（tabs / toolbar 三处复制的收敛，见 #17）。\n * 只提供无 Vue 依赖的计算与副作用，事件绑定 / ResizeObserver / watch 由各\n * composable 按需组合（三处的监听源与生命周期有真实差异，不强行统一）。\n */\n\n/** 视口滚动几何（scrollTo 兼容 HTMLElement 与 vue 模板 ref） */\nexport interface OverflowNavViewport {\n  scrollLeft: number\n  scrollWidth: number\n  clientWidth: number\n}\n\n/** 导航按钮状态 */\nexport interface OverflowNavState {\n  /** 内容是否溢出视口 */\n  overflowing: boolean\n  /** 可向前（左/上）滚动 */\n  canPrev: boolean\n  /** 可向后（右/下）滚动 */\n  canNext: boolean\n}\n\n/** 依据视口与内容尺寸推导滚动按钮可用状态 */\nexport function computeOverflowNavState(vp: OverflowNavViewport): OverflowNavState {\n  const overflowing = vp.scrollWidth - vp.clientWidth > 1\n  return {\n    overflowing,\n    canPrev: overflowing && vp.scrollLeft > 0,\n    canNext: overflowing && vp.scrollLeft + vp.clientWidth < vp.scrollWidth - 1\n  }\n}\n\ntype ScrollableElement = OverflowNavViewport & {\n  scrollTo(options: { left: number; behavior: 'smooth' }): void\n}\n\n/** 箭头按钮：按视口宽度 80% 的步长平滑滚动 */\nexport function scrollViewportByStep(vp: ScrollableElement, dir: 1 | -1): void {\n  vp.scrollTo({ left: vp.scrollLeft + dir * vp.clientWidth * 0.8, behavior: 'smooth' })\n}\n\n/** 目标元素滚入视口（左/右越界时对齐到边缘，留 offset 边距） */\nexport function scrollElementIntoView(vp: HTMLElement, el: HTMLElement, offset = 8): void {\n  const vpRect = vp.getBoundingClientRect()\n  const elRect = el.getBoundingClientRect()\n  if (elRect.left < vpRect.left) {\n    vp.scrollTo({ left: vp.scrollLeft + (elRect.left - vpRect.left) - offset, behavior: 'smooth' })\n  } else if (elRect.right > vpRect.right) {\n    vp.scrollTo({\n      left: vp.scrollLeft + (elRect.right - vpRect.right) + offset,\n      behavior: 'smooth'\n    })\n  }\n}\n\n/**\n * 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截。\n * navActive = 导航按钮是否可见（内容未溢出时不消费滚轮）。\n */\nexport function applyWheelHorizontalScroll(\n  e: WheelEvent,\n  vp: HTMLElement,\n  navActive: boolean\n): void {\n  if (!navActive) return\n  if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) return\n  if (e.deltaY === 0) return\n  e.preventDefault()\n  vp.scrollLeft += e.deltaY\n}\n"],"mappings":";;AAwBA,SAAgB,wBAAwB,IAA2C;CACjF,MAAM,cAAc,GAAG,cAAc,GAAG,cAAc;CACtD,OAAO;EACL;EACA,SAAS,eAAe,GAAG,aAAa;EACxC,SAAS,eAAe,GAAG,aAAa,GAAG,cAAc,GAAG,cAAc;CAC5E;AACF;;AAOA,SAAgB,qBAAqB,IAAuB,KAAmB;CAC7E,GAAG,SAAS;EAAE,MAAM,GAAG,aAAa,MAAM,GAAG,cAAc;EAAK,UAAU;CAAS,CAAC;AACtF;;AAGA,SAAgB,sBAAsB,IAAiB,IAAiB,SAAS,GAAS;CACxF,MAAM,SAAS,GAAG,sBAAsB;CACxC,MAAM,SAAS,GAAG,sBAAsB;CACxC,IAAI,OAAO,OAAO,OAAO,MACvB,GAAG,SAAS;EAAE,MAAM,GAAG,cAAc,OAAO,OAAO,OAAO,QAAQ;EAAQ,UAAU;CAAS,CAAC;MACzF,IAAI,OAAO,QAAQ,OAAO,OAC/B,GAAG,SAAS;EACV,MAAM,GAAG,cAAc,OAAO,QAAQ,OAAO,SAAS;EACtD,UAAU;CACZ,CAAC;AAEL;;;;;AAMA,SAAgB,2BACd,GACA,IACA,WACM;CACN,IAAI,CAAC,WAAW;CAChB,IAAI,KAAK,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,EAAE,MAAM,GAAG;CAC7C,IAAI,EAAE,WAAW,GAAG;CACpB,EAAE,eAAe;CACjB,GAAG,cAAc,EAAE;AACrB"}

package/dist/helper/tween.js

@@ -78,8 +78,8 @@ var Tween = class Tween {
 		easeInBack: (p) => p * p * (3.70158 * p - 1),
 		easeOutBack: (p) => 1 + 2.70158 * Math.pow(p - 1, 3) + 1.70158 * Math.pow(p - 1, 2),
 		easeInOutBack: (p) => {
-			const c2 = 1.70158 * 1.525;
-			return p < .5 ? Math.pow(2 * p, 2) * (3.5949095 * 2 * p - c2) / 2 : (Math.pow(2 * p - 2, 2) * (3.5949095 * (p * 2 - 2) + c2) + 2) / 2;
+			const c2 = 2.5949095;
+			return p < .5 ? Math.pow(2 * p, 2) * (7.189819 * p - c2) / 2 : (Math.pow(2 * p - 2, 2) * (3.5949095 * (p * 2 - 2) + c2) + 2) / 2;
 		}
 	};
 };

package/dist/helper/tween.js.map

@@ -1 +1 @@
-{"version":3,"file":"tween.js","names":["pk"],"sources":["../../src/helper/tween.ts"],"sourcesContent":["/** 自 cat-kit 3.x Tween 行为对齐的轻量动画（原 `cat-kit/fe` 导出） */\n\nexport interface AnimeConfig<State extends Record<string, number>> {\n  duration?: number\n  easingFunction?: (progress: number) => number\n  onComplete?(state: State): void\n}\n\nexport interface TweenConfig<State extends Record<string, number>> {\n  duration?: number\n  onUpdate?(state: State): void\n  onComplete?(state: State): void\n  easingFunction?: (progress: number) => number\n}\n\nexport class Tween<State extends Record<string, number> = Record<string, number>> {\n  readonly state: State\n  protected duration = 300\n  protected onUpdate?: (state: State) => void\n  protected onComplete?: (state: State) => void\n  protected frameId?: number\n  protected easingFunction: (progress: number) => number\n  private defaultState: State\n\n  constructor(state: State, config?: TweenConfig<State>) {\n    this.state = state\n    this.defaultState = { ...state }\n    const { duration, onUpdate, onComplete, easingFunction } = config || {}\n    if (duration !== undefined) this.duration = duration\n    if (onUpdate !== undefined) this.onUpdate = onUpdate\n    if (onComplete !== undefined) this.onComplete = onComplete\n    this.easingFunction = easingFunction ?? Tween.easing.linear\n  }\n\n  protected raf(options: {\n    onComplete: () => void\n    duration: number\n    tick: (p: number) => void\n  }): void {\n    const start = performance.now()\n    const { onComplete, tick, duration } = options\n    const update = (timestamp: number) => {\n      const elapsed = timestamp - start\n      const progress = Math.min(elapsed / duration, 1)\n      tick(progress)\n      if (progress < 1) {\n        this.frameId = requestAnimationFrame(update)\n      } else {\n        tick(progress)\n        this.stop()\n        onComplete()\n      }\n    }\n    this.frameId = requestAnimationFrame(update)\n  }\n\n  to(state: Partial<State>, config?: AnimeConfig<State>): void {\n    this.stop()\n    const prevState = { ...this.state }\n    const stateDistance = Object.keys(state).reduce(\n      (acc, key) => {\n        const k = key as keyof State\n        const sv = state[k] as number\n        const pv = prevState[k] as number\n        if ((sv || sv === 0) && (pv || pv === 0)) {\n          acc[key] = sv - pv\n        }\n        return acc\n      },\n      {} as Record<string, number>\n    )\n    const duration = config?.duration || this.duration\n    const easingFunction = config?.easingFunction || this.easingFunction\n    const onComplete = config?.onComplete || this.onComplete\n    this.raf({\n      duration,\n      onComplete: () => {\n        for (const key in state) {\n          if (key in this.state) {\n            ;(this.state as Record<string, number>)[key] = state[key as keyof State] as number\n          }\n        }\n        this.onUpdate?.(this.state)\n        onComplete?.(this.state)\n      },\n      tick: (progress) => {\n        for (const key in stateDistance) {\n          const pk = key as keyof State\n          const target = (prevState[pk] as number) + easingFunction(progress) * stateDistance[key]!\n          ;(this.state as Record<string, number>)[key] = target\n        }\n        this.onUpdate?.(this.state)\n      }\n    })\n  }\n\n  back(config?: AnimeConfig<State>): void {\n    this.to(this.defaultState as Partial<State>, config)\n  }\n\n  private stop(): boolean {\n    if (!this.frameId) return false\n    cancelAnimationFrame(this.frameId)\n    this.frameId = undefined\n    return true\n  }\n\n  static readonly easing = {\n    linear: (p: number) => p,\n    easeInQuad: (p: number) => p * p,\n    easeOutQuad: (p: number) => p * (2 - p),\n    easeInOutQuad: (p: number) => (p < 0.5 ? 2 * p * p : -1 + (4 - 2 * p) * p),\n    easeInBack: (p: number) => p * p * ((2.70158 + 1) * p - 1),\n    easeOutBack: (p: number) => 1 + 2.70158 * Math.pow(p - 1, 3) + 1.70158 * Math.pow(p - 1, 2),\n    easeInOutBack: (p: number) => {\n      const c1 = 1.70158\n      const c2 = c1 * 1.525\n      return p < 0.5\n        ? (Math.pow(2 * p, 2) * ((c2 + 1) * 2 * p - c2)) / 2\n        : (Math.pow(2 * p - 2, 2) * ((c2 + 1) * (p * 2 - 2) + c2) + 2) / 2\n    }\n  }\n}\n"],"mappings":";AAeA,IAAa,QAAb,MAAa,MAAqE;CAChF;CACA,WAAqB;CACrB;CACA;CACA;CACA;CACA;CAEA,YAAY,OAAc,QAA6B;EACrD,KAAK,QAAQ;EACb,KAAK,eAAe,EAAE,GAAG,MAAM;EAC/B,MAAM,EAAE,UAAU,UAAU,YAAY,mBAAmB,UAAU,CAAC;EACtE,IAAI,aAAa,KAAA,GAAW,KAAK,WAAW;EAC5C,IAAI,aAAa,KAAA,GAAW,KAAK,WAAW;EAC5C,IAAI,eAAe,KAAA,GAAW,KAAK,aAAa;EAChD,KAAK,iBAAiB,kBAAkB,MAAM,OAAO;CACvD;CAEA,IAAc,SAIL;EACP,MAAM,QAAQ,YAAY,IAAI;EAC9B,MAAM,EAAE,YAAY,MAAM,aAAa;EACvC,MAAM,UAAU,cAAsB;GACpC,MAAM,UAAU,YAAY;GAC5B,MAAM,WAAW,KAAK,IAAI,UAAU,UAAU,CAAC;GAC/C,KAAK,QAAQ;GACb,IAAI,WAAW,GACb,KAAK,UAAU,sBAAsB,MAAM;QACtC;IACL,KAAK,QAAQ;IACb,KAAK,KAAK;IACV,WAAW;GACb;EACF;EACA,KAAK,UAAU,sBAAsB,MAAM;CAC7C;CAEA,GAAG,OAAuB,QAAmC;EAC3D,KAAK,KAAK;EACV,MAAM,YAAY,EAAE,GAAG,KAAK,MAAM;EAClC,MAAM,gBAAgB,OAAO,KAAK,KAAK,CAAC,CAAC,QACtC,KAAK,QAAQ;GACZ,MAAM,IAAI;GACV,MAAM,KAAK,MAAM;GACjB,MAAM,KAAK,UAAU;GACrB,KAAK,MAAM,OAAO,OAAO,MAAM,OAAO,IACpC,IAAI,OAAO,KAAK;GAElB,OAAO;EACT,GACA,CAAC,CACH;EACA,MAAM,WAAW,QAAQ,YAAY,KAAK;EAC1C,MAAM,iBAAiB,QAAQ,kBAAkB,KAAK;EACtD,MAAM,aAAa,QAAQ,cAAc,KAAK;EAC9C,KAAK,IAAI;GACP;GACA,kBAAkB;IAChB,KAAK,MAAM,OAAO,OAChB,IAAI,OAAO,KAAK,OACb,KAAM,MAAiC,OAAO,MAAM;IAGzD,KAAK,WAAW,KAAK,KAAK;IAC1B,aAAa,KAAK,KAAK;GACzB;GACA,OAAO,aAAa;IAClB,KAAK,MAAM,OAAO,eAAe;KAE/B,MAAM,SAAU,UAAUA,OAAiB,eAAe,QAAQ,IAAI,cAAc;KACnF,KAAM,MAAiC,OAAO;IACjD;IACA,KAAK,WAAW,KAAK,KAAK;GAC5B;EACF,CAAC;CACH;CAEA,KAAK,QAAmC;EACtC,KAAK,GAAG,KAAK,cAAgC,MAAM;CACrD;CAEA,OAAwB;EACtB,IAAI,CAAC,KAAK,SAAS,OAAO;EAC1B,qBAAqB,KAAK,OAAO;EACjC,KAAK,UAAU,KAAA;EACf,OAAO;CACT;CAEA,OAAgB,SAAS;EACvB,SAAS,MAAc;EACvB,aAAa,MAAc,IAAI;EAC/B,cAAc,MAAc,KAAK,IAAI;EACrC,gBAAgB,MAAe,IAAI,KAAM,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,KAAK;EACxE,aAAa,MAAc,IAAI,KAAM,UAAe,IAAI;EACxD,cAAc,MAAc,IAAI,UAAU,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,UAAU,KAAK,IAAI,IAAI,GAAG,CAAC;EAC1F,gBAAgB,MAAc;GAE5B,MAAM,KAAK,UAAK;GAChB,OAAO,IAAI,KACN,KAAK,IAAI,IAAI,GAAG,CAAC,KAAM,YAAU,IAAI,IAAI,MAAO,KAChD,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAM,aAAW,IAAI,IAAI,KAAK,MAAM,KAAK;EACrE;CACF;AACF"}
+{"version":3,"file":"tween.js","names":["pk"],"sources":["../../src/helper/tween.ts"],"sourcesContent":["/** 自 cat-kit 3.x Tween 行为对齐的轻量动画（原 `cat-kit/fe` 导出） */\n\nexport interface AnimeConfig<State extends Record<string, number>> {\n  duration?: number\n  easingFunction?: (progress: number) => number\n  onComplete?(state: State): void\n}\n\nexport interface TweenConfig<State extends Record<string, number>> {\n  duration?: number\n  onUpdate?(state: State): void\n  onComplete?(state: State): void\n  easingFunction?: (progress: number) => number\n}\n\nexport class Tween<State extends Record<string, number> = Record<string, number>> {\n  readonly state: State\n  protected duration = 300\n  protected onUpdate?: (state: State) => void\n  protected onComplete?: (state: State) => void\n  protected frameId?: number\n  protected easingFunction: (progress: number) => number\n  private defaultState: State\n\n  constructor(state: State, config?: TweenConfig<State>) {\n    this.state = state\n    this.defaultState = { ...state }\n    const { duration, onUpdate, onComplete, easingFunction } = config || {}\n    if (duration !== undefined) this.duration = duration\n    if (onUpdate !== undefined) this.onUpdate = onUpdate\n    if (onComplete !== undefined) this.onComplete = onComplete\n    this.easingFunction = easingFunction ?? Tween.easing.linear\n  }\n\n  protected raf(options: {\n    onComplete: () => void\n    duration: number\n    tick: (p: number) => void\n  }): void {\n    const start = performance.now()\n    const { onComplete, tick, duration } = options\n    const update = (timestamp: number) => {\n      const elapsed = timestamp - start\n      const progress = Math.min(elapsed / duration, 1)\n      tick(progress)\n      if (progress < 1) {\n        this.frameId = requestAnimationFrame(update)\n      } else {\n        tick(progress)\n        this.stop()\n        onComplete()\n      }\n    }\n    this.frameId = requestAnimationFrame(update)\n  }\n\n  to(state: Partial<State>, config?: AnimeConfig<State>): void {\n    this.stop()\n    const prevState = { ...this.state }\n    const stateDistance = Object.keys(state).reduce(\n      (acc, key) => {\n        const k = key as keyof State\n        const sv = state[k] as number\n        const pv = prevState[k] as number\n        if ((sv || sv === 0) && (pv || pv === 0)) {\n          acc[key] = sv - pv\n        }\n        return acc\n      },\n      {} as Record<string, number>\n    )\n    const duration = config?.duration || this.duration\n    const easingFunction = config?.easingFunction || this.easingFunction\n    const onComplete = config?.onComplete || this.onComplete\n    this.raf({\n      duration,\n      onComplete: () => {\n        for (const key in state) {\n          if (key in this.state) {\n            ;(this.state as Record<string, number>)[key] = state[key as keyof State] as number\n          }\n        }\n        this.onUpdate?.(this.state)\n        onComplete?.(this.state)\n      },\n      tick: (progress) => {\n        for (const key in stateDistance) {\n          const pk = key as keyof State\n          const target = (prevState[pk] as number) + easingFunction(progress) * stateDistance[key]!\n          ;(this.state as Record<string, number>)[key] = target\n        }\n        this.onUpdate?.(this.state)\n      }\n    })\n  }\n\n  back(config?: AnimeConfig<State>): void {\n    this.to(this.defaultState as Partial<State>, config)\n  }\n\n  private stop(): boolean {\n    if (!this.frameId) return false\n    cancelAnimationFrame(this.frameId)\n    this.frameId = undefined\n    return true\n  }\n\n  static readonly easing = {\n    linear: (p: number) => p,\n    easeInQuad: (p: number) => p * p,\n    easeOutQuad: (p: number) => p * (2 - p),\n    easeInOutQuad: (p: number) => (p < 0.5 ? 2 * p * p : -1 + (4 - 2 * p) * p),\n    easeInBack: (p: number) => p * p * ((2.70158 + 1) * p - 1),\n    easeOutBack: (p: number) => 1 + 2.70158 * Math.pow(p - 1, 3) + 1.70158 * Math.pow(p - 1, 2),\n    easeInOutBack: (p: number) => {\n      const c1 = 1.70158\n      const c2 = c1 * 1.525\n      return p < 0.5\n        ? (Math.pow(2 * p, 2) * ((c2 + 1) * 2 * p - c2)) / 2\n        : (Math.pow(2 * p - 2, 2) * ((c2 + 1) * (p * 2 - 2) + c2) + 2) / 2\n    }\n  }\n}\n"],"mappings":";AAeA,IAAa,QAAb,MAAa,MAAqE;CAChF;CACA,WAAqB;CACrB;CACA;CACA;CACA;CACA;CAEA,YAAY,OAAc,QAA6B;EACrD,KAAK,QAAQ;EACb,KAAK,eAAe,EAAE,GAAG,MAAM;EAC/B,MAAM,EAAE,UAAU,UAAU,YAAY,mBAAmB,UAAU,CAAC;EACtE,IAAI,aAAa,KAAA,GAAW,KAAK,WAAW;EAC5C,IAAI,aAAa,KAAA,GAAW,KAAK,WAAW;EAC5C,IAAI,eAAe,KAAA,GAAW,KAAK,aAAa;EAChD,KAAK,iBAAiB,kBAAkB,MAAM,OAAO;CACvD;CAEA,IAAc,SAIL;EACP,MAAM,QAAQ,YAAY,IAAI;EAC9B,MAAM,EAAE,YAAY,MAAM,aAAa;EACvC,MAAM,UAAU,cAAsB;GACpC,MAAM,UAAU,YAAY;GAC5B,MAAM,WAAW,KAAK,IAAI,UAAU,UAAU,CAAC;GAC/C,KAAK,QAAQ;GACb,IAAI,WAAW,GACb,KAAK,UAAU,sBAAsB,MAAM;QACtC;IACL,KAAK,QAAQ;IACb,KAAK,KAAK;IACV,WAAW;GACb;EACF;EACA,KAAK,UAAU,sBAAsB,MAAM;CAC7C;CAEA,GAAG,OAAuB,QAAmC;EAC3D,KAAK,KAAK;EACV,MAAM,YAAY,EAAE,GAAG,KAAK,MAAM;EAClC,MAAM,gBAAgB,OAAO,KAAK,KAAK,CAAC,CAAC,QACtC,KAAK,QAAQ;GACZ,MAAM,IAAI;GACV,MAAM,KAAK,MAAM;GACjB,MAAM,KAAK,UAAU;GACrB,KAAK,MAAM,OAAO,OAAO,MAAM,OAAO,IACpC,IAAI,OAAO,KAAK;GAElB,OAAO;EACT,GACA,CAAC,CACH;EACA,MAAM,WAAW,QAAQ,YAAY,KAAK;EAC1C,MAAM,iBAAiB,QAAQ,kBAAkB,KAAK;EACtD,MAAM,aAAa,QAAQ,cAAc,KAAK;EAC9C,KAAK,IAAI;GACP;GACA,kBAAkB;IAChB,KAAK,MAAM,OAAO,OAChB,IAAI,OAAO,KAAK,OACb,KAAM,MAAiC,OAAO,MAAM;IAGzD,KAAK,WAAW,KAAK,KAAK;IAC1B,aAAa,KAAK,KAAK;GACzB;GACA,OAAO,aAAa;IAClB,KAAK,MAAM,OAAO,eAAe;KAE/B,MAAM,SAAU,UAAUA,OAAiB,eAAe,QAAQ,IAAI,cAAc;KACnF,KAAM,MAAiC,OAAO;IACjD;IACA,KAAK,WAAW,KAAK,KAAK;GAC5B;EACF,CAAC;CACH;CAEA,KAAK,QAAmC;EACtC,KAAK,GAAG,KAAK,cAAgC,MAAM;CACrD;CAEA,OAAwB;EACtB,IAAI,CAAC,KAAK,SAAS,OAAO;EAC1B,qBAAqB,KAAK,OAAO;EACjC,KAAK,UAAU,KAAA;EACf,OAAO;CACT;CAEA,OAAgB,SAAS;EACvB,SAAS,MAAc;EACvB,aAAa,MAAc,IAAI;EAC/B,cAAc,MAAc,KAAK,IAAI;EACrC,gBAAgB,MAAe,IAAI,KAAM,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,KAAK;EACxE,aAAa,MAAc,IAAI,KAAM,UAAe,IAAI;EACxD,cAAc,MAAc,IAAI,UAAU,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,UAAU,KAAK,IAAI,IAAI,GAAG,CAAC;EAC1F,gBAAgB,MAAc;GAE5B,MAAM,KAAK;GACX,OAAO,IAAI,KACN,KAAK,IAAI,IAAI,GAAG,CAAC,KAAK,WAAe,IAAI,MAAO,KAChD,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAM,aAAW,IAAI,IAAI,KAAK,MAAM,KAAK;EACrE;CACF;AACF"}

package/dist/index.d.ts

@@ -10,10 +10,11 @@ import { createIncrease } from "./helper/create-increase.js";
 import { createToggle } from "./helper/create-toggle.js";
 import { AnimeConfig, Tween, TweenConfig } from "./helper/tween.js";
 import { nextFrame } from "./helper/frame.js";
+import { OverflowNavState, OverflowNavViewport, applyWheelHorizontalScroll, computeOverflowNavState, scrollElementIntoView, scrollViewportByStep } from "./helper/overflow-nav.js";
 import { extractNormalVNodes, fieldKey, isComment, isFragment, isTemplate, isTextNode, shallowComputed } from "./helper/vue.js";
 import { middleProxy } from "./reactive/proxy.js";
 import { DeconstructValue, DefineEvent, Index, Null, RenderReturn, Undef } from "./types/helper.js";
 import { BreakpointName, ColorType, ComponentProps, ComponentSize, FormComponentProps, PresetRule, PropsWithServerQuery, ValidateRule } from "./types/component-common.js";
 import { FormContextModel, FormContextProps, FormFieldItem, injectFormContext, provideFormContext } from "./types/form-context.js";
 import "./types/index.js";
-export { AnimeConfig, BEM, BEMFactory, BreakpointName, CLS_PREFIX, ColorType, ComponentProps, ComponentSize, DeconstructValue, DefineEvent, ExpandTransition, ExpandTransitionOptions, FORM_EMPTY_CONTENT, FormComponentProps, FormContextModel, FormContextProps, FormFieldItem, Index, NAME_SPACE, Null, PresetRule, PropsWithServerQuery, RenderReturn, Tween, TweenConfig, Undef, ValidateRule, addClass, bem, createIncrease, createToggle, extractNormalVNodes, fieldKey, getHighlightChunks, getNearestScrollParent, getScrollParents, injectFormContext, isComment, isFragment, isTemplate, isTextNode, makeBEM, middleProxy, nextFrame, provideFormContext, removeClass, removeStyles, scrollIntoContainerView, setStyles, shallowComputed, withUnit, zIndex };
+export { AnimeConfig, BEM, BEMFactory, BreakpointName, CLS_PREFIX, ColorType, ComponentProps, ComponentSize, DeconstructValue, DefineEvent, ExpandTransition, ExpandTransitionOptions, FORM_EMPTY_CONTENT, FormComponentProps, FormContextModel, FormContextProps, FormFieldItem, Index, NAME_SPACE, Null, OverflowNavState, OverflowNavViewport, PresetRule, PropsWithServerQuery, RenderReturn, Tween, TweenConfig, Undef, ValidateRule, addClass, applyWheelHorizontalScroll, bem, computeOverflowNavState, createIncrease, createToggle, extractNormalVNodes, fieldKey, getHighlightChunks, getNearestScrollParent, getScrollParents, injectFormContext, isComment, isFragment, isTemplate, isTextNode, makeBEM, middleProxy, nextFrame, provideFormContext, removeClass, removeStyles, scrollElementIntoView, scrollIntoContainerView, scrollViewportByStep, setStyles, shallowComputed, withUnit, zIndex };

package/dist/index.js

@@ -10,7 +10,8 @@ import { zIndex } from "./dom/z-index.js";
 import { createToggle } from "./helper/create-toggle.js";
 import { Tween } from "./helper/tween.js";
 import { nextFrame } from "./helper/frame.js";
+import { applyWheelHorizontalScroll, computeOverflowNavState, scrollElementIntoView, scrollViewportByStep } from "./helper/overflow-nav.js";
 import { extractNormalVNodes, fieldKey, isComment, isFragment, isTemplate, isTextNode, shallowComputed } from "./helper/vue.js";
 import { middleProxy } from "./reactive/proxy.js";
 import { injectFormContext, provideFormContext } from "./types/form-context.js";
-export { CLS_PREFIX, ExpandTransition, FORM_EMPTY_CONTENT, NAME_SPACE, Tween, addClass, bem, createIncrease, createToggle, extractNormalVNodes, fieldKey, getHighlightChunks, getNearestScrollParent, getScrollParents, injectFormContext, isComment, isFragment, isTemplate, isTextNode, makeBEM, middleProxy, nextFrame, provideFormContext, removeClass, removeStyles, scrollIntoContainerView, setStyles, shallowComputed, withUnit, zIndex };
+export { CLS_PREFIX, ExpandTransition, FORM_EMPTY_CONTENT, NAME_SPACE, Tween, addClass, applyWheelHorizontalScroll, bem, computeOverflowNavState, createIncrease, createToggle, extractNormalVNodes, fieldKey, getHighlightChunks, getNearestScrollParent, getScrollParents, injectFormContext, isComment, isFragment, isTemplate, isTextNode, makeBEM, middleProxy, nextFrame, provideFormContext, removeClass, removeStyles, scrollElementIntoView, scrollIntoContainerView, scrollViewportByStep, setStyles, shallowComputed, withUnit, zIndex };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/utils",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "files": [
     "dist",
     "src"
@@ -21,6 +21,6 @@
   },
   "peerDependencies": {
     "@cat-kit/core": ">=1.1.8",
-    "vue": ">=3.5.40"
+    "vue": ">=3.5.41"
   }
 }

package/src/dom/position.ts

@@ -1,5 +1,6 @@
 /**
- * 获取可滚动的父级
+ * 获取可滚动的父级（纵向或横向可滚动均计入：overflow-x 容器如横向滚动条
+ * 也是滚动父级，弹层需监听其 scroll 事件）
  * @param el 元素
  * @returns
  */
@@ -7,7 +8,7 @@ export function getScrollParents(el: HTMLElement): HTMLElement[] {
   const parents: HTMLElement[] = []
   let parent = el.parentElement
   while (parent) {
-    if (parent.scrollHeight > parent.clientHeight) {
+    if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) {
       parents.push(parent)
     }
 
@@ -17,14 +18,14 @@ export function getScrollParents(el: HTMLElement): HTMLElement[] {
 }
 
 /**
- * 获取最近的可滚动父级
+ * 获取最近的可滚动父级（纵向或横向可滚动均计入）
  * @param el 元素
  * @returns 最近的可滚动父级
  */
 export function getNearestScrollParent(el: HTMLElement): HTMLElement | null {
   let parent = el.parentElement
   while (parent) {
-    if (parent.scrollHeight > parent.clientHeight) {
+    if (parent.scrollHeight > parent.clientHeight || parent.scrollWidth > parent.clientWidth) {
       return parent
     }
     parent = parent.parentElement

package/src/helper/overflow-nav.ts

@@ -0,0 +1,71 @@
+/**
+ * 水平溢出滚动导航的共享纯逻辑（tabs / toolbar 三处复制的收敛，见 #17）。
+ * 只提供无 Vue 依赖的计算与副作用，事件绑定 / ResizeObserver / watch 由各
+ * composable 按需组合（三处的监听源与生命周期有真实差异，不强行统一）。
+ */
+
+/** 视口滚动几何（scrollTo 兼容 HTMLElement 与 vue 模板 ref） */
+export interface OverflowNavViewport {
+  scrollLeft: number
+  scrollWidth: number
+  clientWidth: number
+}
+
+/** 导航按钮状态 */
+export interface OverflowNavState {
+  /** 内容是否溢出视口 */
+  overflowing: boolean
+  /** 可向前（左/上）滚动 */
+  canPrev: boolean
+  /** 可向后（右/下）滚动 */
+  canNext: boolean
+}
+
+/** 依据视口与内容尺寸推导滚动按钮可用状态 */
+export function computeOverflowNavState(vp: OverflowNavViewport): OverflowNavState {
+  const overflowing = vp.scrollWidth - vp.clientWidth > 1
+  return {
+    overflowing,
+    canPrev: overflowing && vp.scrollLeft > 0,
+    canNext: overflowing && vp.scrollLeft + vp.clientWidth < vp.scrollWidth - 1
+  }
+}
+
+type ScrollableElement = OverflowNavViewport & {
+  scrollTo(options: { left: number; behavior: 'smooth' }): void
+}
+
+/** 箭头按钮：按视口宽度 80% 的步长平滑滚动 */
+export function scrollViewportByStep(vp: ScrollableElement, dir: 1 | -1): void {
+  vp.scrollTo({ left: vp.scrollLeft + dir * vp.clientWidth * 0.8, behavior: 'smooth' })
+}
+
+/** 目标元素滚入视口（左/右越界时对齐到边缘，留 offset 边距） */
+export function scrollElementIntoView(vp: HTMLElement, el: HTMLElement, offset = 8): void {
+  const vpRect = vp.getBoundingClientRect()
+  const elRect = el.getBoundingClientRect()
+  if (elRect.left < vpRect.left) {
+    vp.scrollTo({ left: vp.scrollLeft + (elRect.left - vpRect.left) - offset, behavior: 'smooth' })
+  } else if (elRect.right > vpRect.right) {
+    vp.scrollTo({
+      left: vp.scrollLeft + (elRect.right - vpRect.right) + offset,
+      behavior: 'smooth'
+    })
+  }
+}
+
+/**
+ * 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截。
+ * navActive = 导航按钮是否可见（内容未溢出时不消费滚轮）。
+ */
+export function applyWheelHorizontalScroll(
+  e: WheelEvent,
+  vp: HTMLElement,
+  navActive: boolean
+): void {
+  if (!navActive) return
+  if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) return
+  if (e.deltaY === 0) return
+  e.preventDefault()
+  vp.scrollLeft += e.deltaY
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export * from './helper/frame'
 
 export * from './helper/make-bem'
 
+export * from './helper/overflow-nav'
+
 export * from './helper/vue'
 
 export * from './reactive/proxy'